feat(lisp): surface catalog_ops on Step (#920) (#937)

* feat(lisp): surface catalog_ops on Step (#920)

`EvalContext` already collected per-call records for the PTC-Lisp
`catalog/` builtins (operation, args, outcome, reason, duration_ms)
via `append_catalog_op/2`, but nothing propagated them out of the
sandbox — `Step` had `tool_calls` and `pmap_calls` but no
`catalog_ops`, so the tracing data was dropped at execution boundary.

## Changes

* `Step` gains a `:catalog_ops` field of type `[catalog_op()]`.
  `@type catalog_op` mirrors the EvalContext definition.
  Default-constructed steps (`Step.ok/2`, `Step.error/*`) initialise
  it to `[]`.
* `Lisp.apply_memory_contract/3` propagates
  `Enum.reverse(ctx.catalog_ops)` into the success Step.
* The `error_with_ctx` branch in `Lisp.run/2` does the same for
  programs that fail mid-execution.

Ordering is chronological (oldest first), matching how `tool_calls`
and `pmap_calls` are already surfaced.

## Tests

Four new cases in `test/catalog_builtins_test.exs`:
1. Single successful op produces one `:ok` record with args + duration
2. Multiple ops appear in chronological order
3. World fault produces `:nil_world_fault` record with reason atom
4. Programs without catalog calls expose `step.catalog_ops == []`

Full suite green: 4927 tests, 0 failures.

Closes #920

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(lisp): propagate catalog_ops through merge, closures, and HOF stash

Fixes three context-propagation gaps identified in PR #937 review:
- EvalContext.merge/2: add catalog_ops to parallel branch merge (pmap/pcalls)
- execute_closure/4: carry caller_ctx.catalog_ops into closure context
- push/stash/pop_side_effects: include catalog_ops in HOF stash mechanism

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

Author: 3 people

lib/ptc_runner/lisp.ex

@@ -497,6 +497,7 @@ defmodule PtcRunner.Lisp do
             prints: eval_ctx.prints,
             tool_calls: cleaned_tool_calls,
             pmap_calls: cleaned_pmap_calls,
+            catalog_ops: Enum.reverse(eval_ctx.catalog_ops),
             child_traces: child_traces,
             child_steps: child_steps,
             journal: eval_ctx.journal,
@@ -668,6 +669,7 @@ defmodule PtcRunner.Lisp do
       prints: Enum.reverse(ctx.prints),
       tool_calls: cleaned_tool_calls,
       pmap_calls: cleaned_pmap_calls,
+      catalog_ops: Enum.reverse(ctx.catalog_ops),
       child_traces: child_traces,
       child_steps: child_steps
     }

lib/ptc_runner/lisp/eval/apply.ex

@@ -638,7 +638,7 @@ defmodule PtcRunner.Lisp.Eval.Apply do
 
   defp push_side_effect_stash do
     stack = Process.get(:__ptc_hof_stack, [])
-    Process.put(:__ptc_hof_stack, [%{tool_calls: [], prints: []} | stack])
+    Process.put(:__ptc_hof_stack, [%{tool_calls: [], prints: [], catalog_ops: []} | stack])
   end
 
   defp stash_side_effects(%EvalContext{} = ctx) do
@@ -649,7 +649,8 @@ defmodule PtcRunner.Lisp.Eval.Apply do
         # then previous invocations'.
         updated = %{
           tool_calls: ctx.tool_calls ++ top.tool_calls,
-          prints: ctx.prints ++ top.prints
+          prints: ctx.prints ++ top.prints,
+          catalog_ops: ctx.catalog_ops ++ top.catalog_ops
         }
 
         Process.put(:__ptc_hof_stack, [updated | rest])
@@ -670,6 +671,7 @@ defmodule PtcRunner.Lisp.Eval.Apply do
         eval_ctx
         |> Map.update!(:tool_calls, fn existing -> top.tool_calls ++ existing end)
         |> Map.update!(:prints, fn existing -> top.prints ++ existing end)
+        |> Map.update!(:catalog_ops, fn existing -> top.catalog_ops ++ existing end)
 
       [] ->
         eval_ctx
@@ -717,7 +719,8 @@ defmodule PtcRunner.Lisp.Eval.Apply do
             tool_cache: caller_ctx.tool_cache,
             summaries: caller_ctx.summaries,
             journal: caller_ctx.journal,
-            catalog_exec: caller_ctx.catalog_exec
+            catalog_exec: caller_ctx.catalog_exec,
+            catalog_ops: caller_ctx.catalog_ops
         }
 
         case do_eval_fn.(body, closure_ctx) do

lib/ptc_runner/lisp/eval/context.ex

@@ -327,6 +327,7 @@ defmodule PtcRunner.Lisp.Eval.Context do
       | prints: ctx2.prints ++ ctx1.prints,
         tool_calls: ctx2.tool_calls ++ ctx1.tool_calls,
         pmap_calls: ctx2.pmap_calls ++ ctx1.pmap_calls,
+        catalog_ops: ctx2.catalog_ops ++ ctx1.catalog_ops,
         user_ns: Map.merge(ctx1.user_ns, ctx2.user_ns),
         iteration_count: ctx1.iteration_count + ctx2.iteration_count,
         summaries: Map.merge(ctx1.summaries, ctx2.summaries),

lib/ptc_runner/step.ex

@@ -193,6 +193,7 @@ defmodule PtcRunner.Step do
     :prints,
     :tool_calls,
     :pmap_calls,
+    :catalog_ops,
     :child_traces,
     :child_steps,
     :messages,
@@ -300,6 +301,30 @@ defmodule PtcRunner.Step do
           error_count: non_neg_integer()
         }
 
+  @typedoc """
+  PTC-Lisp `catalog/` builtin invocation record (aggregator mode).
+
+  Captured for each `catalog/summary`, `catalog/list-servers`,
+  `catalog/list-tools`, `catalog/describe-tool`, and
+  `catalog/search-tools` call dispatched through `catalog_exec`.
+
+  Fields:
+  - `operation`: The builtin variant (`:summary`, `:list_servers`,
+    `:list_tools`, `:describe_tool`, `:search_tools`)
+  - `args`: Normalized argument map (shape depends on operation)
+  - `outcome`: `:ok` on success, `:nil_world_fault` when a world fault
+    was swallowed to `nil`, `:error` on programmer faults that raised
+  - `reason`: World-fault reason atom when `outcome == :nil_world_fault`
+  - `duration_ms`: How long the catalog dispatch took
+  """
+  @type catalog_op :: %{
+          operation: atom(),
+          args: map(),
+          outcome: :ok | :nil_world_fault | :error,
+          reason: atom() | nil,
+          duration_ms: non_neg_integer()
+        }
+
   @type t :: %__MODULE__{
           return: term() | nil,
           fail: fail() | nil,
@@ -314,6 +339,7 @@ defmodule PtcRunner.Step do
           prints: [String.t()],
           tool_calls: [tool_call()],
           pmap_calls: [pmap_call()],
+          catalog_ops: [catalog_op()],
           child_traces: [String.t()],
           child_steps: [t()],
           messages: [message()] | nil,
@@ -350,6 +376,7 @@ defmodule PtcRunner.Step do
       prints: [],
       tool_calls: [],
       pmap_calls: [],
+      catalog_ops: [],
       child_traces: [],
       child_steps: []
     }
@@ -428,6 +455,7 @@ defmodule PtcRunner.Step do
       prints: [],
       tool_calls: [],
       pmap_calls: [],
+      catalog_ops: [],
       child_traces: [],
       child_steps: []
     }

test/catalog_builtins_test.exs

@@ -370,4 +370,56 @@ defmodule PtcRunner.CatalogBuiltinsTest do
       assert step.return == []
     end
   end
+
+  # ============================================================
+  # catalog_ops tracing is surfaced on Step (#920)
+  # ============================================================
+
+  describe "step.catalog_ops" do
+    test "successful op produces one ok record in execution order" do
+      {:ok, step} =
+        Lisp.run(
+          ~s|(catalog/describe-tool "github" "search")|,
+          catalog_exec: mock_catalog_exec()
+        )
+
+      assert [op] = step.catalog_ops
+      assert op.operation == :describe_tool
+      assert op.outcome == :ok
+      assert op.reason == nil
+      assert op.args == %{server: "github", tool: "search"}
+      assert is_integer(op.duration_ms) and op.duration_ms >= 0
+    end
+
+    test "multiple ops appear in chronological (not reverse) order" do
+      {:ok, step} =
+        Lisp.run(
+          ~s|(do (catalog/list-servers) (catalog/list-tools "github") (catalog/summary))|,
+          catalog_exec: mock_catalog_exec()
+        )
+
+      assert [op1, op2, op3] = step.catalog_ops
+      assert op1.operation == :list_servers
+      assert op2.operation == :list_tools
+      assert op2.args == %{server: "github"}
+      assert op3.operation == :summary
+    end
+
+    test "world fault produces :nil_world_fault record with reason" do
+      exec = fn _op, _args -> {:world_fault, :upstream_unavailable} end
+
+      {:ok, step} =
+        Lisp.run(~s|(or (catalog/list-tools "github") [])|, catalog_exec: exec)
+
+      assert [op] = step.catalog_ops
+      assert op.operation == :list_tools
+      assert op.outcome == :nil_world_fault
+      assert op.reason == :upstream_unavailable
+    end
+
+    test "step from a program without catalog calls has empty catalog_ops" do
+      {:ok, step} = Lisp.run("(+ 1 2)", catalog_exec: mock_catalog_exec())
+      assert step.catalog_ops == []
+    end
+  end
 end