@agent-native/core 0.130.1 → 0.131.2

package/corpus/templates/content/docs/product/capabilities/content.diff.filtered-review.md

@@ -0,0 +1,79 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.diff.filtered-review"
+name: "Filtered change review"
+user_promise: "A reviewer can accept or reject one change or an exact visible set without accidentally deciding newer or hidden changes."
+primary_user_job: "Review a manageable subset of a large proposal while preserving dependency safety and auditability."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.diff.in-place"]
+related_features:
+  [
+    "content.feature.review-changes-in-place",
+    "content.feature.explore-alternatives-safely",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Filtered bulk review snapshots the exact eligible change identities and bases, validates dependencies and authority atomically, and records idempotent decisions without sweeping in concurrent matches."
+proof_requirements:
+  [
+    "Exact filter/selection snapshot semantics",
+    "Dependency and mixed-authority preflight",
+    "Idempotent atomic apply with durable Event receipts",
+    "Concurrent additions, stale changes, retry, undo, and UI/Action coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Filtered change review
+
+## Why this exists
+
+Large change sets need a humane slice, but “accept all visible” must mean exactly what the reviewer saw—not whatever happened to match later.
+
+## Example workflow
+
+An editor filters an agent proposal to changes in one section, selects the visible compatible changes, and accepts them. A new change that arrives while review is open remains pending; a hidden prerequisite is surfaced rather than silently applied.
+
+## Product contract
+
+- A filtered decision resolves exact eligible change IDs, observed bases, and filter context at selection time.
+- New matching changes do not enter an already prepared bulk decision.
+- Preflight checks dependencies, stale bases, source policy, and authority for the full intended set.
+- Mixed permissions or incompatible dependencies produce an explicit repair/narrowing state, never an invisible partial commit.
+- Repeated delivery of the same approved decision is idempotent and emits durable receipts.
+
+## Boundaries and non-goals
+
+- This does not decide the typed rendering of a single change or generate proposals.
+- It is not a generic Database bulk-edit engine, though both need exact selection semantics.
+- Agents may narrow scope only when faithful to the request and must report skipped work.
+
+## Acceptance stories
+
+### Freeze the visible set
+
+Given a reviewer filters to five pending changes, when a sixth matching change arrives before **Accept visible** completes, then only the five resolved IDs are decided and the sixth remains pending.
+
+### Refuse unsafe partial approval
+
+Given a selected change depends on an inaccessible or stale prerequisite, when the reviewer accepts the set, then no subset silently applies and Content explains the dependency or authority repair path.
+
+## Current evidence
+
+Existing source-review and bulk-operation machinery offers useful examples of selection and audit behavior. It does not prove generic filtered review snapshot, dependency, and idempotent decision semantics; this remains `approved_shape`.
+
+## Proof plan
+
+1. Exercise single, selected, filtered, and all-visible decisions across typed change kinds.
+2. Race concurrent additions, edits, removals, retries, and duplicate requests.
+3. Test dependencies, mixed authority, source locks, stale bases, undo, and Event/History receipts.
+4. Verify UI and agent Action parity, accessibility, and clear scope reporting.
+
+## Open questions
+
+Filter language and progress presentation may vary; exact selection snapshot and no-silent-partial behavior may not.

package/corpus/templates/content/docs/product/capabilities/content.diff.in-place.md

@@ -0,0 +1,80 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.diff.in-place"
+name: "In-place typed review"
+user_promise: "Changes are reviewed inside the ordinary Page, Database, Board, template, source, or code surface that gives them meaning."
+primary_user_job: "Evaluate a proposed change in context rather than translating it from a generic red/green destination."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.event.committed", "content.renderer.typed"]
+related_features:
+  [
+    "content.feature.review-changes-in-place",
+    "content.feature.explore-alternatives-safely",
+    "content.feature.evolve-systems-safely",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Typed change identities and dependencies render in the normal object surface, retain causal/actor context, and record durable authorized review decisions."
+proof_requirements:
+  [
+    "Typed change model for bodies, Blocks, Properties, memberships, and structured values",
+    "Ordinary renderer integration and accessible in-place comparison",
+    "Durable accept/reject/defer/supersede Events with authority",
+    "Stale, dependency, conflict, source, and agent-run coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# In-place typed review
+
+## Why this exists
+
+A property, Block, membership, and source proposal carry different meaning. Review should meet each where it lives instead of flattening all work into an unreadable universal diff.
+
+## Example workflow
+
+An agent proposes article copy and Status changes. The editor sees copy changes in the Page editor, the Status change in its Property renderer, accepts one, rejects the other, and History records the durable decisions with the run context.
+
+## Product contract
+
+- A change has stable identity, target type, dependencies, actor/origin, causal context, before/after material, and disposition.
+- Body, Block, Property, membership, and structured changes render through their ordinary typed surfaces.
+- Accept, reject, defer, and supersede are authorized durable decisions that emit Events and preserve why a proposal ended.
+- A stale target, incompatible dependency, source authority restriction, or conflict is explicit; no review button silently applies a plausible partial result.
+- Agent and human proposals use the same review model and Actions.
+
+## Boundaries and non-goals
+
+- This capability does not define filtered-set selection, AI assistance, or named Version branching.
+- It does not replace low-level Events, logical Revisions, or recovery snapshots.
+- A typed renderer may degrade honestly; review may not discard unknown source content.
+
+## Acceptance stories
+
+### Review mixed typed changes in context
+
+Given a proposal changes a paragraph and a select Property, when an editor opens review, then each difference renders in its ordinary surface and the editor can decide independently where dependencies allow.
+
+### Surface a stale conflict honestly
+
+Given a proposal is based on a Block another editor changed, when review attempts acceptance, then Content shows a stale/rebase/conflict state and does not overwrite the newer change.
+
+## Current evidence
+
+Source change sets, document snapshots, and Builder review machinery are donor substrate. The repository does not yet prove one generic typed in-place diff system across Content objects, so this remains `approved_shape`.
+
+## Proof plan
+
+1. Propose and render each supported change type through UI and shared Actions.
+2. Test dependency ordering, stale bases, conflicts, source locks, permission changes, and Undo.
+3. Verify Events, History, agent attribution, recovery, and accessible comparison.
+4. Exercise reload, concurrent decisions, portable output, and unavailable renderers.
+
+## Open questions
+
+The internal change representation and exact visual affordances remain open; typed context and durable authorized disposition are settled.

package/corpus/templates/content/docs/product/capabilities/content.discussion.page.md

@@ -0,0 +1,80 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.discussion.page"
+name: "Page Discussion"
+user_promise: "Every Page has one continuing Discussion for humane, Page-wide collaboration and curated activity."
+primary_user_job: "Discuss the larger meaning of work without losing the Page and revision context that gives the conversation sense."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.object.page",
+    "content.object.blocks-field",
+    "content.event.committed",
+  ]
+related_features: ["content.feature.collaborate-in-context"]
+roadmap_boundary: "feature"
+acceptance_summary: "A lazily materialized canonical Page Discussion supports rich messages, bounded threads, reactions, Page-version cursors, selected Event/Comment activity, access, and notifications without replacing Comments or History."
+proof_requirements:
+  [
+    "Canonical Page Discussion identity across current and future Versions",
+    "Rich message, reply, mention, reaction, and bounded-thread behavior",
+    "Revision/Event cursor and curated activity projection",
+    "Access, notification, permalink, UI/Action, and concurrency coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Page Discussion
+
+## Why this exists
+
+Exact comments are not enough for the larger conversation: why the change matters, what was decided, and what should happen next. Discussion gives that conversation one durable home.
+
+## Example workflow
+
+A teammate starts a Page Discussion about an unclear strategy, replies in one focused sub-thread, links a relevant Comment thread, and later opens “view the Page then” to see the revision cursor that existed when the message was posted.
+
+## Product contract
+
+- Every Page has one canonical Discussion identity, created lazily on first use and authoritative across current and future Page Versions.
+- Messages use Blocks fields; they may reply to or mention a message or actor, while one message opens at most one focused sub-conversation rather than infinite nesting.
+- A message may connect to Comment threads without moving those Comments out of their Page-owned context.
+- Each message records quiet Page Version and Revision/Event cursor context; UI reveals historical Page/diff on demand.
+- Discussion curates selected collaboration Events and grouped Comment activity. History remains exhaustive; Comments remain exact anchors.
+
+## Boundaries and non-goals
+
+- Discussion is not another body Block, Database membership, task engine, or named Version.
+- It does not replace Comments, Info, Annotations, Versions, or History; these are separate rails/modes.
+- Curated activity does not duplicate Event authority or expose inaccessible details.
+
+## Acceptance stories
+
+### Continue one conversation across Versions
+
+Given a Page has a Discussion and later receives a named Version, when a collaborator opens either Version, then the same Discussion is available with each message's appropriate Version cursor preserved.
+
+### Keep a focused thread bounded
+
+Given a Discussion message has replies, when a reply starts a sub-conversation, then subsequent replies remain understandable in that bounded thread and do not build an infinitely nested tree.
+
+## Current evidence
+
+Current Comments, mentions, notifications substrate, and document history provide adjacent pieces. A universal canonical Discussion, rich message grammar, cursors, and curated activity projection are not yet proven; this remains `approved_shape`.
+
+## Proof plan
+
+1. Create canonical Discussions, messages, replies, mentions, reactions, and Comment links across Page lifecycle operations.
+2. Verify cursors, historical Page/diff links, selected Event grouping, and History separation.
+3. Test access changes, notifications, permalinks, agents, external continuation boundaries, and deletion.
+4. Exercise concurrent messages/reactions, reload, keyboard, and assistive technology.
+
+## Open questions
+
+Default grouping and activity-selection rules remain product refinement; they cannot make Discussion the recovery authority or create a second Page identity.

package/corpus/templates/content/docs/product/capabilities/content.embed.host-grant.md

@@ -0,0 +1,70 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.embed.host-grant"
+name: "Embedded host grants"
+user_promise: "An embedded host gets only the mount and Actions it was granted, never more authority than the viewer."
+primary_user_job: "Use Content inside another application without silently giving that application broad access to my work."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "configured"
+dependencies: ["content.embed.surface", "content.access.visibility-closure"]
+related_features: ["content.feature.work-on-content-inside-another-application"]
+roadmap_boundary: "feature"
+acceptance_summary: "A named host grant scopes mount identity, permitted Actions, audience, expiry and revocation; every call is additionally constrained by the signed-in viewer's current Content authority."
+proof_requirements:
+  [
+    "Grant issuance, scope, expiry, revocation, origin, and audience validation tests",
+    "Cross-host authorization tests proving host grants cannot widen viewer access",
+    "Embedded mutation and denied-action interface workflow with audit receipts",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Embedded host grants
+
+## Why this exists
+
+An embed is a borrowed room, not a spare key to the building.
+
+## Example workflow
+
+A planner mounts one project brief in a sibling app. The host may render and edit that brief through its grant; a request for another Page is denied even if the host knows its ID.
+
+## Product contract
+
+- A grant names host, mount, permitted Action capability, audience, lifetime, and revocation state.
+- Every host request validates its grant and then resolves the current viewer's Content access; a host can only narrow, never widen, that authority.
+- The shared Actions retain validation, Events, history, and honest outcomes. Hosts receive no database credentials or bypass route.
+- Grant changes take effect for subsequent calls and do not retroactively publish cached material.
+
+## Boundaries and non-goals
+
+Embed surface owns rendering and lifecycle; sharing owns ordinary resource access. This does not make all hosts trusted or grant a host blanket workspace access.
+
+## Acceptance stories
+
+### Limit a mounted brief
+
+Given a host grant for one Page and read permission, when the host requests a different Page, then Content denies it even if the viewer could open that Page directly.
+
+### Revoke a host capability
+
+Given a host has edit permission, when the owner revokes the grant, then its next mutation is denied and no new Event is committed.
+
+## Current evidence
+
+Donor evidence: shared toolkit components and Content access primitives can support reuse. No repository proof yet covers signed grants, origin validation, revocation, or host/viewer intersection; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Define signed or server-resolved grants with narrow capability claims.
+2. Test expiry, revocation, origin, mount substitution, and authority intersection.
+3. Verify an embedded edit and denial path with receipts and accessible status.
+
+## Open questions
+
+- The host identity handshake remains open provided it cannot widen viewer authority.

package/corpus/templates/content/docs/product/capabilities/content.embed.mcp-app.md

@@ -0,0 +1,69 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.embed.mcp-app"
+name: "MCP App embedding"
+user_promise: "Compatible agent hosts can show a focused Content surface without receiving a copied object or broader authority."
+primary_user_job: "Open the same governed Content object from a compatible agent host and understand what the host may do."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "external_host"
+dependencies: ["content.embed.surface", "content.embed.host-grant"]
+related_features: ["content.feature.work-on-content-inside-another-application"]
+roadmap_boundary: "feature"
+acceptance_summary: "An MCP App integration adapts the canonical embed mount and host-grant contract to compatible hosts, preserves viewer-scoped actions and receipts, and fails clearly when host capabilities are absent."
+proof_requirements:
+  [
+    "Protocol compatibility and host capability-negotiation tests",
+    "Grant and viewer-authority parity tests against the ordinary embedded surface",
+    "Compatible-host mount, mutation, unavailable-host, and revocation workflow",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# MCP App embedding
+
+## Why this exists
+
+MCP App support should widen where Content can appear, not what an outside host may possess.
+
+## Example workflow
+
+An agent host opens a granted Page as an MCP App. It renders the canonical mount, calls only granted Actions, and reports an unavailable capability when the host cannot provide the required presentation feature.
+
+## Product contract
+
+- This surface adapts `content.embed.surface` and `content.embed.host-grant`; it does not invent a parallel object, auth, or mutation path.
+- Host capability negotiation names what the host can render or invoke. Missing capability is unavailable, not a successful empty mount.
+- Viewer access, grant scope, validation, Events, history, and receipts remain Content-owned.
+
+## Boundaries and non-goals
+
+This does not make every MCP client a supported editor, expose all Actions as tools, or replace native sibling-app embedding.
+
+## Acceptance stories
+
+### Mount the canonical object
+
+Given a compatible host and a grant for one Page, when it opens the MCP App, then it sees the canonical Page state rather than a copied snapshot.
+
+### Tell the truth about host limits
+
+Given a host that lacks a required interaction capability, when it requests that mount mode, then Content reports it unavailable and does not silently substitute broader access.
+
+## Current evidence
+
+Donor evidence: `changelog/2026-07-28-builder-content-reads-now-negotiate-the-newest-mcp-protocol-.md` records protocol-related substrate. No complete Content MCP App mount and grant proof exists; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Implement narrow protocol negotiation over the canonical embed contract.
+2. Test compatible, incompatible, revoked, and viewer-denied cases.
+3. Verify a real host mount and mutation receipt without a copied authority path.
+
+## Open questions
+
+- The first compatible host and supported interaction subset remain open.

package/corpus/templates/content/docs/product/capabilities/content.embed.surface.md

@@ -0,0 +1,74 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.embed.surface"
+name: "Embedded Content surface"
+user_promise: "The same Page, View, or focused Content experience can appear in another app without splitting identity, history, or permissions."
+primary_user_job: "Work on a canonical Content object in the application where my work is happening."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "configured"
+dependencies: ["content.agent.action-parity", "content.access.page-database"]
+related_features:
+  [
+    "content.feature.work-on-content-inside-another-application",
+    "content.feature.build-living-dashboards",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "A stable mount contract renders a selected canonical Content surface responsively and routes its allowed interactions through shared Actions, current access, history, and application state without cloning the object."
+proof_requirements:
+  [
+    "Mount identity, lifecycle, responsive rendering, and application-state tests",
+    "Shared Action, access, history, and concurrent-update parity tests",
+    "Host workflow covering read, edit, navigation, unsupported mode, and unmount/remount",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Embedded Content surface
+
+## Why this exists
+
+Work often happens beside Content; moving the window should not create another truth.
+
+## Example workflow
+
+A planning app mounts a project Database View. A person filters it and opens a Page; the same object, access checks, and history are visible when they later return to Content.
+
+## Product contract
+
+- A mount identifies one Page, View, or focused surface and uses stable Content identity, not serialized copies.
+- Rendering, navigation, application state, accessibility, and responsive layout have explicit mount boundaries.
+- Reads and mutations use shared Actions and current viewer access; concurrent changes remain observable through the ordinary sync model.
+- Unsupported surface modes say so explicitly instead of becoming a half-functional clone.
+
+## Boundaries and non-goals
+
+Host grants own host authority; this record owns the reusable UI and lifecycle. It is not an iframe-only requirement or a new Content shell for every host.
+
+## Acceptance stories
+
+### Continue the same edit
+
+Given a Page mounted in a host, when an editor changes it through the mount, then Content records the ordinary change and the canonical editor shows it after synchronization.
+
+### Preserve mount limits
+
+Given a host requests a surface mode that is not supported by the mount contract, when it renders, then it receives an explicit unavailable state rather than a copied fallback editor.
+
+## Current evidence
+
+Donor evidence: Content components, Actions, and application-state patterns already support reuse. No stable mount lifecycle, cross-host state, or full responsive proof exists; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Define mount inputs, lifecycle, state ownership, and supported surfaces.
+2. Test parity under changing access and concurrent canonical edits.
+3. Run host read/edit/navigation/remount workflows at responsive sizes.
+
+## Open questions
+
+- The first transport and host component packaging remain open.

package/corpus/templates/content/docs/product/capabilities/content.event.committed.md

@@ -0,0 +1,85 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.event.committed"
+name: "Committed Events"
+user_promise: "Meaningful committed changes have one durable, actor-aware Event spine."
+primary_user_job: "Understand what changed, by whom and why, without mistaking every keystroke or snapshot for intentional work."
+kind: "primitive"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies: []
+related_features:
+  [
+    "content.feature.durable-foundations",
+    "content.feature.collaborate-in-context",
+    "content.feature.review-changes-in-place",
+    "content.feature.trust-your-connected-sources",
+    "content.feature.evolve-systems-safely",
+    "content.feature.when-this-happens-that-follows",
+    "content.feature.collect-structured-input",
+    "content.feature.move-without-starting-over",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Every meaningful committed mutation writes an atomic durable Event with actor, authority, origin, causality, target, and recoverable outcome in the same transaction or reliable outbox."
+proof_requirements:
+  [
+    "Atomic outbox or equivalent commit coupling for mutation paths",
+    "Actor, authority, origin, target, causality, and outcome attribution",
+    "Human, agent, Rule, automation, API, and source mutation coverage",
+    "Failure, retry, idempotency, access, and recovery evidence",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Committed Events
+
+## Why this exists
+
+People need a trustworthy account of meaningful work. A cursor twitch is not history, and an untraceable automated change is a ghost in the machinery.
+
+## Example workflow
+
+An agent updates several Blocks and a Property in one authorized run. Content commits atomic Events for the actual mutations, ties them to the authorizing context and causal run, and lets a reviewer later inspect the grouped Revision without claiming the run was a single database write.
+
+## Product contract
+
+- A committed Event records one meaningful atomic change after it commits, not every keystroke or cursor move.
+- It retains actor, authority, origin, target, causal context, outcome, and recoverable change information appropriate to the operation.
+- Human editing coalesces at logical commit boundaries; agents, Rules, source syncs, and automation carry explicit causality.
+- Event emission couples to mutation through one transaction or reliable outbox so a committed change cannot quietly lose its Event.
+- Events are atomic facts. Logical Revisions group related Events; snapshots protect recovery; named Versions are deliberate alternatives.
+
+## Boundaries and non-goals
+
+- Events do not make every persistence snapshot a reviewable Revision.
+- They do not replace Discussion's curated collaboration timeline or History's queryable projection.
+- The spine does not authorize an operation or expose inaccessible Event contents.
+
+## Acceptance stories
+
+### Attribute an agent run accurately
+
+Given an authorized agent run changes two Blocks and one Property, when it commits, then each meaningful mutation has an Event with agent origin and causal run, and the signed-in person is retained as authority rather than substituted as the actor.
+
+### Fail without a phantom success
+
+Given a mutation cannot persist its Event/outbox record, when the commit fails, then the mutation is not reported as success and retry cannot create duplicate live meaning.
+
+## Current evidence
+
+Existing document actions, snapshots, source audit machinery, and action infrastructure are useful donors. The repository does not yet demonstrate one atomic actor-aware Event spine across mutation paths; this remains `in_progress`.
+
+## Proof plan
+
+1. Inventory and exercise Page, Database, comment, source, Rule, automation, and review mutations.
+2. Simulate transaction/outbox interruption, retry, duplicate delivery, and partial failure.
+3. Verify attribution, causal grouping inputs, access-scoped reads, recovery, and Undo.
+4. Test real UI and shared agent/API Actions under concurrent commits.
+
+## Open questions
+
+Outbox transport and payload storage can vary. The atomic fact, attribution, and no-dropped-success contract cannot.

package/corpus/templates/content/docs/product/capabilities/content.expression.cached-result.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.expression.cached-result"
+name: "Cached expression results"
+user_promise: "See the last valid computed value quickly while knowing whether it still reflects current inputs."
+primary_user_job: "Read a last valid result while understanding freshness."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.expression.language", "content.event.committed"]
+related_features: ["content.feature.data-that-keeps-itself-right"]
+roadmap_boundary: "feature"
+acceptance_summary: "Expression consumers render the last valid result stale-first, mark freshness and failure truthfully, refresh in the background, and retain the previous valid value when refresh is ordinary work."
+proof_requirements:
+  [
+    "A valid cached result is distinct from a missing value, a failed evaluation, and an unavailable input.",
+    "Input or dependency changes make cached output visibly stale; successful refresh replaces it atomically.",
+    "A failed refresh preserves the last valid result with an error state and retry path rather than reporting a clean empty value.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Cached expression results
+
+## Why this exists
+
+A blank dashboard during an ordinary refresh is less useful than the last known answer, but a stale answer must never masquerade as current. People need both speed and a clear account of freshness or failure.
+
+## Example workflow
+
+Priya opens a dashboard after an upstream change, sees yesterday's total marked stale, and keeps it beside a retryable refresh failure.
+
+## Product contract
+
+- A valid cached result is distinct from a missing value, a failed evaluation, and an unavailable input.
+- Input or dependency changes make cached output visibly stale; successful refresh replaces it atomically.
+- A failed refresh preserves the last valid result with an error state and retry path rather than reporting a clean empty value.
+
+## Boundaries and non-goals
+
+- `content.expression.language` owns evaluation and dependency semantics; cached-result behavior owns freshness, replacement, and stale/error presentation.
+- A cache is not a source of truth, must not bypass access, and must not turn a failed refresh into an empty successful value.
+
+## Acceptance stories
+
+### Do not collapse failed refresh
+
+Given refresh fails after a valid value, then the prior value remains stale with error, not blank or zero.
+
+### Respect viewer access
+
+Given a result was cached for a broader audience, when a narrower viewer opens it, then it is withheld or reevaluated.
+
+## Current evidence
+
+No cache implementation exists. `actions/update-document.ts` and committed mutation paths donate invalidation inputs, not freshness or audience-safe cache behavior.
+
+## Proof plan
+
+1. Change direct/transitive input and verify stale-first replacement.
+2. Distinguish evaluator, provider, timeout, and access failures.
+3. Change viewer access and prove no cache leakage.
+4. Test retry, invalidation, and eviction.
+
+## Open questions
+
+Lifetime, scheduling, and offline policy remain open.