Bind the originating query to the canvas: persisted tool-call recipes for deterministic replay

[Weegy]

Summary

Extension of #5. Deterministic refresh only works if the canvas knows how its data was produced. Today that knowledge evaporates after the turn: the LLM interprets the user's request, makes tool calls, gets responses, and composes the tree — and none of that pipeline is persisted with the canvas. Only the resulting tree (with its dataRefs) survives.

This issue proposes binding the query to the canvas: persist the resolved data-production recipe — the concrete tool calls with their final parameters, the response→primitive data mapping, and the composition decisions — as a first-class part of the canvas, so the canvas can be re-materialized deterministically, with no LLM in the loop.

Motivation

• Deterministic refresh for data-driven canvases (no LLM turn) #5's canvas_refresh covers the easy half: re-resolving dataRefs that point at refreshable sources. But much canvas data is not a single addressable ref — it is the output of tool calls the LLM issued during the turn (search results, aggregations, cross-service joins, computed series feeding a chart). Without recording those calls, that data is frozen forever.
• Determinism is the point: the same recorded recipe replayed against the same sources must yield the same canvas modulo newer data. The LLM's only job was figuring the recipe out once; re-running it should never need interpretation again.
• It is the foundation for everything downstream: scheduled refresh, live-mode sharing (Canvas sharing: grant read access to other users (snapshot + live modes) #6 — replay under the grantee's identity), and an honest delete story (Delete canvases from the Omadia UI (per-user removal, full delete on last reference) #8 — the recipe is part of what gets deleted).

Proposed behavior

1. Canvas recipe. When a turn produces or patches a canvas, Tier 2 persists alongside the tree: the ordered set of tool calls (tool id, resolved/concrete parameters — no free-text placeholders), the mapping from each response to the primitive data it populated (by stable primitive id), and any deterministic post-processing applied (sort, limit, aggregation expressed as data ops, not prose).
2. Refresh = replay. canvas_refresh (Deterministic refresh for data-driven canvases (no LLM turn) #5) executes the recipe: re-run the recorded tool calls with the recorded parameters, re-apply the recorded mappings, diff against the current revision, emit patch ops. The LLM is not invoked.
3. Parameterization, not re-interpretation. Recipe parameters that are time-relative ("last 30 days") are stored as resolved expressions (now − 30d), not as the frozen values, so replay moves the window deterministically. The set of allowed expressions is small and closed — anything that would need interpretation stays frozen and is marked non-refreshable.
4. Drift handling. If a recorded tool call fails on replay (tool removed, schema changed, permission revoked), the affected primitives get a defined stale/error state and the client offers the escalation path from Deterministic refresh for data-driven canvases (no LLM turn) #5: one explicit LLM turn to rebuild the recipe. The new recipe replaces the old one.
5. Determinism contract. Recipes record the ops-catalog version and tool versions they were built against; replay refuses (with the drift path above) rather than silently producing different semantics on a version mismatch.

Open questions

• Granularity: one recipe per canvas, or per data-bearing primitive (a table and a chart on the same surface may have independent refresh cadences and failure modes)? Per-primitive looks right and matches Deterministic refresh for data-driven canvases (no LLM turn) #5's subtree scope.
• How are non-deterministic tools marked? The tool/ops catalog likely needs a deterministic: boolean (or replayable) flag so Tier 2 knows what may enter a recipe.
• Recipe visibility: do we show users what a refresh will do (the recorded calls) for trust/debugging — e.g., in a canvas inspector pane?
• Storage: recipes belong in the durable canvas store introduced by Canvas sharing: grant read access to other users (snapshot + live modes) #6/Delete canvases from the Omadia UI (per-user removal, full delete on last reference) #8 and must be included in delete and (decided per mode) in sharing.

Affected areas

• Tier 2 orchestrator: recipe capture during turn execution, replay engine, drift detection, expression resolver
• Tool/ops catalog: replayability flag, versioning metadata on recorded calls
• Protocol: refresh error/staleness states per primitive (extends Deterministic refresh for data-driven canvases (no LLM turn) #5's surface events)
• Durable canvas store (Canvas sharing: grant read access to other users (snapshot + live modes) #6/Delete canvases from the Omadia UI (per-user removal, full delete on last reference) #8): recipe persistence, lifecycle coupled to the canvas

Related

• Deterministic refresh for data-driven canvases (no LLM turn) #5 (deterministic refresh — this issue supplies the mechanism for non-dataRef data; attach as sub-issue/follow-up)
• Canvas sharing: grant read access to other users (snapshot + live modes) #6 (sharing — live mode replays the recipe under the grantee's identity)
• Delete canvases from the Omadia UI (per-user removal, full delete on last reference) #8 (deletion — recipes are part of the canvas's persisted footprint)

[Weegy]

Implementation plan

Baseline already shipped with #5 phase 2 (PR #10 / the Tier-2 companion PR): per-container source recipes (publish tool's source param = tool + exact input + fieldKey→attribute map), captured by the synthesis layer, replayed via the kernel's out-of-turn tool invocation with no LLM in the path, announced as surface_data_ref_created { refreshable }, agent-turn fallback that re-captures. What this issue adds on top, in dependency order:

WP1 — Replayability flag in the tool catalog (S)

replayable?: boolean on the native tool spec (plugin API), threaded into the kernel tool registry; out-of-turn invocation refuses non-flagged tools; recipe capture validates the recorded tool against the registry before storing. Each integration declares replayability for its own read tools in its tool specs — the platform consumes the declaration generically. Answers open question 2 — deny-by-default: only explicitly replayable tools enter recipes.

WP2 — Durable recipe store (M) — the core of this issue

Recipes move from the in-memory LRU into the durable canvas state. Ownership decision: the canvas channel already owns durable canvas state (the per-user registry via the kernel memory accessor) — it additionally persists per-canvas recipe files and provides a canvasRecipeStore@1 service the canvas orchestrator consumes (capture = write-through, replay = lazy load after boot; LRU stays as cache). Recipes never round-trip through the client (they contain raw queries). Lifecycle coupling for #8: when a registry update drops a canvas, the channel deletes its recipes in the same operation — recipes are part of the deleted footprint.
Per-recipe metadata: capturedAt, opsCatalogVersion, toolName, pluginId (from the registry — provenance without hard-coding any provider).

WP3 — Determinism contract + drift handling (S–M)

Replay refuses on: tool no longer registered / no longer replayable / ops-catalog version mismatch. On refusal or replay failure: emit surface_data_ref_invalidated { id, reason } inside the fallback run (sequenced after its opening event), client clears the container's refreshable state → the instant-refresh marker disappears until the fallback turn re-captures a fresh recipe. The fallback IS the §4 escalation path (one explicit LLM turn, new recipe replaces the old).

WP4 — Closed time-expression set (S)

Preferred answer to §3: recipes use the data source's native relative date operators wherever its query language supports them — the source resolves the window at execution time, which is strictly more robust than client-side expressions. Complement for sources without such operators: a closed placeholder set in recorded inputs — {{today}}, {{now-Nd}}, {{startOfWeek}}, {{startOfMonth}} — resolved by substitution at replay, whitelist-validated at capture. Anything else stays frozen and the recipe is marked non-refreshable (per spec).

WP5 — Deterministic post-processing ops (S)

Optional recipe ops: [{op:'sort',by,dir}, {op:'limit',n}] (closed set), applied after field mapping in the replay mapper — covers 'top N by X' canvases without prose interpretation.

WP6 — Recipe inspector (M, client)

Trust/debugging surface (open question 3): extend surface_data_ref_created additively with tool + capturedAt; the client already keeps per-container dataRef state, so an inspector pane (canvas chrome ⓘ / library card detail) renders 'how this refreshes' — recorded tool, capture time, deterministic vs agent mode, last refresh — with zero extra round-trips.

Settled open questions

• Granularity: per-container (= per data-bearing primitive), matching Deterministic refresh for data-driven canvases (no LLM turn) #5's scope — already how capture/replay work.
• Storage: channel-owned durable store next to the registry (WP2), included in Delete canvases from the Omadia UI (per-user removal, full delete on last reference) #8 deletion; sharing semantics (replay under grantee identity) stay with Canvas sharing: grant read access to other users (snapshot + live modes) #6.

Out of scope here

Scheduled/auto-refresh (enabled by this, separate issue), the #6 grantee-identity replay, and full DataRef bulk-fetch token validation (the announce-only HMAC from #5 hardens then).

Suggested order: WP1 → WP2 → WP3 → WP4+WP5 (parallel, small) → WP6. WP1–WP3 make refresh survive restarts and version drift — the substance of this issue; WP4–WP6 are quality-of-life on top.