@agent-native/core 0.130.2 → 0.131.3

package/corpus/templates/content/docs/product/capabilities/content.template.graph.md

@@ -0,0 +1,76 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.template.graph"
+name: "Multi-object Templates"
+user_promise: "Start from a reusable system of Pages, Databases, Views, Properties, Rules, expressions, and bodies, then own the result."
+primary_user_job: "Create an owned system from a reusable object graph."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  ["content.object.page", "content.object.database", "content.object.reference"]
+related_features:
+  [
+    "content.feature.share-how-your-organization-works",
+    "content.feature.capture-into-action",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "A Template serializes a portable graph of ordinary Content primitives and creates an owned, editable instance with stable internal references, provenance, and optional version pinning."
+proof_requirements:
+  [
+    "Templates fork; they do not possess the instance or create a live hidden copy.",
+    "Instantiation remaps graph-local identities while preserving declared external references and access checks.",
+    "The instance remains ordinary editable Content with provenance to the source Template and version used.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Multi-object Templates
+
+## Why this exists
+
+A working system spans more than one page, yet copying a folder of loose objects loses the relationships that make it work. Teams need a reusable starting graph that becomes genuinely theirs after installation.
+
+## Example workflow
+
+Kai installs a research Template graph, edits its new database and view freely, and traces the owned instance to the source version.
+
+## Product contract
+
+- Templates fork; they do not possess the instance or create a live hidden copy.
+- Instantiation remaps graph-local identities while preserving declared external references and access checks.
+- The instance remains ordinary editable Content with provenance to the source Template and version used.
+
+## Boundaries and non-goals
+
+- Pages, Databases, Views, Properties, Rules, Expressions, and Blocks remain the canonical objects; the Template records their portable graph and provenance.
+- Templates fork rather than possess; they do not create a parallel datastore, fixed singleton, or hidden live synchronization channel.
+
+## Acceptance stories
+
+### Fork, do not possess
+
+Given two teams adopt the Template, when one team edits its local database, then one local database edit does not affect the other or source.
+
+### Remap internal identity
+
+Given internal links and an external reference, when the graph instantiates, then new links point locally and external reference remains declared/access-checked.
+
+## Current evidence
+
+`docs/product/architecture.md` defines graph snapshots; Page, Database, and Reference records are donors, not graph serialization/instance recovery.
+
+## Proof plan
+
+1. Serialize ordinary objects, rules, expressions, bodies, and references.
+2. Instantiate twice and verify independent IDs/provenance/access.
+3. Test unavailable dependencies and recovery without half graphs.
+4. Round-trip portable graph export/import.
+
+## Open questions
+
+All-or-nothing versus staged recovery needs root judgment.

package/corpus/templates/content/docs/product/capabilities/content.template.item-body.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.template.item-body"
+name: "Database item Templates"
+user_promise: "Offer more than one useful starting body for a database record, including a clear default and context-aware embedded views."
+primary_user_job: "Start a database item with a governed body and context."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.template.graph", "content.object.blocks-field"]
+related_features: ["content.feature.share-how-your-organization-works"]
+roadmap_boundary: "feature"
+acceptance_summary: "Database item Templates are Template graph variants for a Database with one selected default, typed creation context, dynamic embedded views, and view-derived creation defaults."
+proof_requirements:
+  [
+    "Each body template is an ordinary graph-backed snapshot associated with the Database, not a parallel content type.",
+    "Creation applies the chosen template and defaults once within a successful transaction; dynamic views bind the newly created record context.",
+    "Changing the database default affects future creation only and never overwrites existing item bodies.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Database item Templates
+
+## Why this exists
+
+One database can hold several kinds of work, and a blank page makes each new record start from nothing. Authors need a chosen starting body that carries the new item's actual context without rewriting existing records.
+
+## Example workflow
+
+Kai creates a request from a Bug report body Template; its embedded view binds the new record and later default changes affect only future rows.
+
+## Product contract
+
+- Each body template is an ordinary graph-backed snapshot associated with the Database, not a parallel content type.
+- Creation applies the chosen template and defaults once within a successful transaction; dynamic views bind the newly created record context.
+- Changing the database default affects future creation only and never overwrites existing item bodies.
+
+## Boundaries and non-goals
+
+- `content.template.graph` owns template snapshot identity and `content.object.blocks-field` owns the item body; this record owns Database-specific choice and creation context.
+- Item Templates do not rewrite existing bodies when a default changes or create a hidden global-current-page binding.
+
+## Acceptance stories
+
+### Keep existing bodies
+
+Given default body changes, when an existing item opens, then existing item bodies remain unchanged.
+
+### Bind current item explicitly
+
+Given an embedded view, when the item Template creates a record, then it uses declared new-item context, not hidden global page state.
+
+## Current evidence
+
+`actions/create-document.ts` and `app/components/editor/DocumentBlockFields.tsx` are donors; per-database variants are absent.
+
+## Proof plan
+
+1. Create variants, choose default, test every creation route.
+2. Apply defaults/current-record binding in one transaction.
+3. Change defaults and verify future-only behavior.
+4. Test missing context/incompatible view/failed creation.
+
+## Open questions
+
+Context-sensitive default selection beyond one explicit default remains open.

package/corpus/templates/content/docs/product/capabilities/content.template.update.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.template.update"
+name: "Template updates"
+user_promise: "Review what changed in a template and selectively bring compatible improvements into my owned instance."
+primary_user_job: "Selectively apply template improvements without losing local work."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.template.graph", "content.diff.in-place"]
+related_features: ["content.feature.evolve-systems-safely"]
+roadmap_boundary: "feature"
+acceptance_summary: "Template instances never auto-update; they show a structural, typed, provenance-aware diff and permit dependency-safe selective apply or reset while preserving local additions."
+proof_requirements:
+  [
+    "An update compares the pinned/adopted source version with the proposed version and identifies affected objects, formulas, Rules, Views, and dependencies.",
+    "The owner chooses follow, pin, selectively apply, or reset; local additions remain unless the owner deliberately removes them.",
+    "Partial apply is dependency-safe, receipt-backed, previewed for impact, and never a silent remote overwrite.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Template updates
+
+## Why this exists
+
+A template improvement is useful only if an instance owner can see its consequences before accepting it. Remote changes must not overwrite the local adaptations that made the template fit real work.
+
+## Example workflow
+
+Kai reviews a template update, applies a formula but not a view, and keeps a locally added property untouched.
+
+## Product contract
+
+- An update compares the pinned/adopted source version with the proposed version and identifies affected objects, formulas, Rules, Views, and dependencies.
+- The owner chooses follow, pin, selectively apply, or reset; local additions remain unless the owner deliberately removes them.
+- Partial apply is dependency-safe, receipt-backed, previewed for impact, and never a silent remote overwrite.
+
+## Boundaries and non-goals
+
+- `content.template.graph` owns source/instance graph identity and `content.diff.in-place` owns review presentation; this record owns update notice, impact, and selective apply/reset.
+- Updates never auto-apply, overwrite local additions silently, or use a remote version as a new permission authority.
+
+## Acceptance stories
+
+### Never auto-update
+
+Given a new approved version, when an owner opens the instance, then instance remains pinned until owner acts.
+
+### Require dependencies
+
+Given selected change needs a property, when the owner applies it, then Content applies it or explains why partial apply cannot commit.
+
+## Current evidence
+
+`docs/product/features/content.feature.evolve-systems-safely.md` records donors; typed graph diff/impact/apply/recovery are absent.
+
+## Proof plan
+
+1. Diff graph versions including formulas, Rules, views, dependencies.
+2. Preview consumers and local additions.
+3. Selectively apply/reset with receipts/recovery.
+4. Test conflicts, denial, and retry without overwrite.
+
+## Open questions
+
+Conflict presentation and reset granularity remain open.

package/corpus/templates/content/docs/product/capabilities/content.time.types.md

@@ -0,0 +1,85 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.time.types"
+name: "Dates, times, and durations"
+user_promise: "Date, Instant, ranges, Duration, and explicit timezone conversion"
+primary_user_job: "Represent time accurately for the meaning I intend and see its conversion, filtering, rendering, and export without silent timezone drift."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.property.typed"]
+related_features:
+  [
+    "content.feature.data-that-keeps-itself-right",
+    "content.feature.plan-work-across-time",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Typed Date, Instant, ranges, Duration, and explicit timezone conversion preserve distinct semantics through storage, filters, rendering, Actions, and export."
+proof_requirements:
+  [
+    "Date-only, instant, range, duration, timezone, validation, storage, and round-trip coverage",
+    "Filter, sort, expression, renderer, Action, export, import, and agent-context semantic coverage",
+    "DST, locale, invalid value, missing zone, reload, and recovery workflows",
+  ]
+evidence:
+  [
+    "../../../app/components/editor/database/calendar-timeline.ts",
+    "../../../app/components/editor/DocumentDatabase.test.ts",
+  ]
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Dates, times, and durations
+
+## Why this exists
+
+“Tuesday” and “Tuesday at 09:00 in a zone” are different promises. Content must retain
+that difference from storage to a person reading an export months later.
+
+## Example workflow
+
+An editor records a date-only deadline and a zoned meeting instant, filters both in a
+Timeline, travels to another timezone, and exports them with their distinct meaning intact.
+
+## Product contract
+
+- Date, Instant, range, Duration, and timezone are typed values with non-interchangeable semantics.
+- Date-only values do not acquire a hidden timezone; Instants retain an explicit conversion context.
+- Filters, sorts, expressions, renderers, Actions, import/export, and agents preserve the declared type.
+- Invalid, ambiguous, missing-zone, stale, and unavailable values are explicit rather than coerced into success.
+
+## Boundaries and non-goals
+
+Typed Properties own general value storage. This is not a calendar provider, scheduling
+policy, or permission model.
+
+## Acceptance stories
+
+### Preserve a date-only value
+
+Given a date-only deadline, when a viewer changes timezone and filters or exports it,
+then Content retains the same calendar date rather than shifting it as an Instant.
+
+### Convert an Instant explicitly
+
+Given a zoned meeting Instant, when a viewer changes display timezone, then its displayed
+local time changes by explicit conversion while its stored instant and history remain stable.
+
+## Current evidence
+
+`calendar-timeline.ts` and Database tests provide date-window donor behavior. They do
+not prove the complete typed storage, timezone, expression, import/export, and recovery
+contract; this Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test every type through validation, storage, round trip, filters, sorts, and expressions.
+2. Verify rendering, Actions, import/export, agents, and type-preserving history.
+3. Exercise DST, locale, invalid/missing zone, reload, unavailable input, and recovery workflows.
+
+## Open questions
+
+The serialized interchange representation and display-zone preference policy need design.

package/corpus/templates/content/docs/product/capabilities/content.version.branching.md

@@ -0,0 +1,151 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.version.branching"
+name: "Named Page Versions"
+user_promise: "Multiple named body versions evolve in parallel under one Page identity and shared properties"
+primary_user_job: "Explore and review a substantial alternative without disturbing the current Page or splitting the work across duplicate Pages."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.version.field-history", "content.diff.in-place"]
+related_features:
+  [
+    "content.feature.living-references",
+    "content.feature.explore-alternatives-safely",
+    "content.feature.read-and-annotate-anything",
+    "content.feature.publish-with-confidence",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "One Page can hold named alternative bodies with narrower access, independent history, in-place comparison and selective merge, explicit canonical promotion, Version-aware collaboration, and lossless recovery."
+proof_requirements:
+  [
+    "Stable Page and Version identity with shared title, Properties, sharing ceiling, and Discussion",
+    "Independent body history, in-place compare, bidirectional selective merge, durable review decisions, and canonical promotion",
+    "Version-aware Comments, Discussion, Annotations, receipts, search, agents, publication, and exports under access intersection",
+    "Archive, restore, failure recovery, and lossless round-trip of the Version graph",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Named Page Versions
+
+## Why this exists
+
+People need to explore a meaningful alternative without changing the current or published work before the alternative is ready. Copying the Page solves isolation by breaking everything else: identity, Properties, access, Discussion, source provenance, and history drift into parallel objects.
+
+Named Versions keep the work on one Page. They add deliberate alternative bodies and review workflows above ordinary Blocks-field history; they do not turn every autosave into a branch.
+
+## Example workflow
+
+A team has a published article and wants to attempt a larger rewrite. An editor creates a private Version called `Rewrite`, leaves Comments for an agent, and lets the agent edit that Version while the canonical article remains unchanged. The team compares `Rewrite` with the current Version inside the ordinary Page interface, accepts some changes and rejects others, then promotes `Rewrite` when it is ready. The former current Version remains intact and addressable, and publication stays pinned until someone explicitly updates it.
+
+## Product contract
+
+### One Page, deliberate alternatives
+
+- The Page retains one stable ID and URL across every Version.
+- The Page title, top-level Properties, Database memberships, source identity, and sharing boundary remain Page-owned and common across Versions.
+- Each named Version has stable identity, a human label, Version-specific body state, its own revision history, and a place in the Page's Version graph.
+- Exactly one authorized Version is current or canonical. Promoting another Version changes that pointer; it does not overwrite or delete the former current Version.
+- A named Version is not an Event, logical Revision, recovery snapshot, duplicate Page, source representation, or publication. Those concepts may refer to a Version but retain their own identities and lifecycles.
+- Ordinary Blocks-field history continues independently beneath every named Version and exists even on Pages that never create an alternative.
+
+### Versions in the ordinary Page interface
+
+- Opening Versions changes the normal Page surface. Selecting a Version renders that body in the ordinary editor rather than in a separate diff application.
+- Comparing two authorized Versions shows typed differences in place while retaining unchanged context.
+- Review may accept or reject one change, all currently visible changes, or a safe filtered set. Compatible changes may move in either direction.
+- Accepted and rejected decisions persist immediately with actor, origin, and Version context. Retrying an already-applied decision is idempotent.
+- Selective merge does not collapse the two Version identities. Each body and its history remain independently addressable afterward.
+- If either side changes after a comparison was prepared, Content shows a stale, refresh, rebase, or typed conflict state. It never silently applies a change against a different base or converts a failed comparison into `no differences`.
+
+### Collaboration stays with the Page
+
+- A Page has one Discussion across all Versions. It is not cloned per alternative.
+- A Discussion message records the named Version and exact Revision/Event cursor visible when it was posted. The shared feed may be filtered to the current Version or all authorized Versions.
+- Replies inherit the root message's Version scope. A person who cannot access a private Version cannot infer its messages through counts, unread state, participants, notifications, search, summaries, or agents.
+- Comments remain Page-owned and target stable Blocks, precise ranges, the named Version and Revision, and quoted fallback context. Deleting or replacing the target text never deletes the Comment.
+- Annotations retain exact Version and source-revision context. Ordinary edits may relocate an anchor within that Version; sibling Versions never inherit it silently.
+- A filtered visible set of Comments or Annotations may be carried to another Version. Preview distinguishes exact matches, proposed relocations, and unresolved anchors. Accepting a mapping adds a destination target to the same contribution identity and preserves the original target and conversation.
+- Execution receipts and other Version-aware contributions keep the Version context visible when reviewed later.
+
+## Access and publication
+
+- Versions inherit Page access by default. A named Version may restrict access to fewer people but can never be shared more broadly than its Page.
+- Effective authority is the intersection of Page access and the Version restriction. Page identity and top-level Properties remain visible according to Page access; the Version body, history, diffs, attachments, receipts, and Version-scoped contributions inherit the narrower boundary.
+- Inaccessible Versions are absent from ambient discovery. Their labels, participants, counts, backlinks, Query membership, search results, notifications, summaries, and agent context do not leak.
+- A known opaque Version link returns an honest access-denied state without exposing private metadata and may offer the normal request-access path when policy permits.
+- Search, Queries, references, embeds, agents, compare, merge, export, and source synchronization apply Version access before reading or computing.
+- Ordinary Revisions inherit their named Version's access and are not independently shareable.
+- Publication is separately pinned to an explicitly selected Version and exact Revision. Promoting the collaborative current Version does not silently alter what is public.
+
+## Promotion, archive, recovery, and export
+
+- Promotion requires the relevant edit/structural authority, commits atomically, and leaves exactly one current Version.
+- The replaced current Version remains a normal alternative with its body, history, access, and collaboration anchors intact.
+- Non-current Versions can be archived and restored without changing stable identity or losing history.
+- Recovery failures cannot leave a half-promoted state or a Page with ambiguous current identity.
+- A lossless Content archive preserves authorized Version identities, graph/ancestry information, bodies, per-field history, Discussion, Comments, Annotations, receipts, access metadata, provenance, and assets or stable handles.
+- Static or compatibility exports resolve as the acting user. They include only authorized material and report unresolved dependencies rather than silently presenting an incomplete export as complete.
+
+## Boundaries and non-goals
+
+- Named Versions do not replace per-Blocks-field revision history, Undo, recovery snapshots, or queryable History.
+- Versions is the product surface; typed diffs, filtered review, merge, and comparison are modes or supporting capabilities beneath it.
+- Creating a Version does not duplicate the Page, title, Properties, membership, source identity, or Discussion.
+- Publication state is not inferred from which Version is current.
+- Comments and Annotations are not copied automatically into sibling Versions. Carry-forward is an explicit, provenance-preserving operation.
+- This Capability does not define a second permission, event, Action, or export engine.
+
+## Acceptance stories
+
+### Work privately beside a stable canonical body
+
+Given a Page with a current Version, when an editor creates a restricted `Rewrite` Version and changes its body, then the Page ID, title, Properties, memberships, sharing ceiling, and Discussion remain common while the current body's content remains unchanged.
+
+### Compare and merge without destroying either alternative
+
+Given two authorized Versions containing typed Block additions, edits, moves, and deletions, when a reviewer compares them in the normal Page interface and accepts only selected changes, then only those compatible changes move, both Version identities remain, and every decision has durable attribution. Retrying an accepted decision does not duplicate it.
+
+### Promote without publishing by accident
+
+Given a public artifact pinned to Version A at revision R, when an authorized editor promotes Version B to current, then B becomes the sole collaborative current Version, A remains addressable, and the public artifact remains pinned to A/R until explicitly updated.
+
+### Keep private Versions truly private
+
+Given a Page viewer without access to restricted Version B, when they open Discussion, search, run a Query, ask an agent, follow an embed, inspect notifications, compare Versions, or export the Page, then neither B nor its derived counts, labels, participants, content, or contributions are disclosed. A known direct link yields only an honest denial.
+
+### Carry forward research without losing its origin
+
+Given a filtered Annotation rail containing exact, relocatable, and unresolved anchors from Version A, when an authorized person chooses **Carry visible to this version** for Version B and accepts a subset, then accepted contributions gain B targets with mapping provenance, unresolved anchors remain unresolved, and every original A target and conversation stays intact.
+
+### Recover the complete Page state
+
+Given a Page with several Versions, independent Blocks-field histories, archived alternatives, Version-scoped collaboration, and assets, when an authorized lossless export is restored, then stable Page and Version identities, current designation, bodies, access, histories, anchors, receipts, and authorized dependencies remain coherent.
+
+## Current evidence
+
+Content currently preserves whole-document snapshots and can restore earlier title/body state. Those snapshots are useful recovery donor machinery, not named Versions: they do not prove stable alternative identities, parallel bodies, Version-specific access, a revision graph, in-place selective merge, promotion, or Version-aware collaboration. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Create, rename, edit, compare, merge, promote, archive, restore, and address named Versions through both the interface and shared Actions.
+2. Verify Page-shared title, Properties, memberships, source identity, access ceiling, and Discussion while independently editing Version bodies and Blocks-field histories.
+3. Exercise additions, deletions, moves, structured Blocks, partial review, all-visible review, retries, stale bases, incompatible dependencies, concurrent promotion, and persistence failure.
+4. Verify Discussion, Comments, Annotations, receipts, carry-forward, orphan recovery, and exact Version/Revision links across ordinary edits and promotion.
+5. Run the complete access matrix through direct reads, search, Queries, counts, notifications, references, embeds, agents, comparisons, publication, and exports.
+6. Round-trip a lossless archive and verify stable identity, current state, access, histories, collaboration, provenance, and authorized assets.
+7. Complete the Feature workflow through the real Page UI with keyboard and assistive technology, not only schema or Action tests.
+
+## Open questions
+
+- A named Version's exact payload still needs one decision: the primary body only, every Page-owned Blocks field, or an explicitly selected set. Whatever is chosen must not overload Versions to represent separate media/source formats.
+- Branch-from rules, ancestry representation, naming collisions, rename behavior, and whether merge creates a distinct graph node remain open.
+- Dependency behavior for partially accepting structurally dependent changes needs a precise oracle.
+- Concurrent promotion and archiving/restoring the current Version need atomic rules.
+- The exact portable Markdown/MDX representation of several named Versions and per-field histories remains open even though the lossless archive obligation is settled.
+- Version-specific role grammar, carry-forward authority, anchor relocation thresholds, and the detailed filter/re-anchor controls remain product decisions.

package/corpus/templates/content/docs/product/capabilities/content.version.field-history.md

@@ -0,0 +1,103 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.version.field-history"
+name: "Blocks-field revision history"
+user_promise: "Every Blocks field preserves attributable comparison and recovery independently of later named Page Versions."
+primary_user_job: "Understand, compare, and recover how any rich-content field changed without turning every edit into a named alternative."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.blocks-field", "content.event.committed"]
+related_features:
+  [
+    "content.feature.durable-foundations",
+    "content.feature.explore-alternatives-safely",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Every editable Blocks field retains stable Block identity, attributable causal Revisions, comparison, and recovery across ordinary editing and named-Version operations."
+proof_requirements:
+  [
+    "Independent attributable revision history for every Blocks field",
+    "Stable Block and field identity through edits, reorder, deletion, and recovery",
+    "Causal Revision grouping distinct from Events, snapshots, and named Versions",
+    "In-place comparison and recovery through UI and shared Actions",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Blocks-field revision history
+
+## Why this exists
+
+Rich content appears in Page bodies, additional Blocks Properties, Comments, Discussion messages, annotations, and other Content objects. People need to know what changed and recover mistakes in any of those bodies without making every keystroke a named Version or every field a miniature Page.
+
+## Example workflow
+
+A Page contains a primary article body and a separate research-notes Blocks field. An agent edits both in one run. The editor can inspect each field's attributable history, compare the relevant Revisions in place, and restore only the research notes without replacing the article body, Page title, or Properties. If the Page later gains named Versions, each alternative continues to retain its own field history.
+
+## Product contract
+
+- Every editable rich-content body is a Blocks field with stable identity and one canonical owning object.
+- Every Block retains stable identity through ordinary text edits, structured edits, and reordering. Deleted content remains addressable through authorized history.
+- A committed Event is one atomic fact. A logical Revision groups causally related edits by actor, intent, action, or agent run. A recovery snapshot is persistence machinery. A named Version is a deliberate alternative. The interface never treats these as synonyms merely because they happened near the same time.
+- Each Blocks field owns its own attributable revision sequence, comparison, and recovery boundary.
+- A single action may causally touch several fields while preserving which changes belong to each field. Restoring one field does not silently replace unrelated Page state.
+- History records the actual actor, authority, origin, and causal run. Agent work is attributable as agent work rather than being flattened into the signed-in person's authorship.
+- Comparison renders through the ordinary typed editor and renderer for that field. Unknown or unavailable Block renderers preserve their source and produce an explicit degraded state rather than dropping content.
+- Creating, promoting, archiving, restoring, or merging a named Page Version never erases the underlying field histories.
+- Comments, Annotations, references, and other anchors retain their historical Block/field/Revision targets even when current content changes or is deleted.
+
+## Permissions and failure behavior
+
+- History reads and restores use the owning object's access plus any narrower named-Version boundary.
+- A person or agent cannot recover a field into a state they may inspect but lack authority to edit.
+- Inaccessible or pruned history is not reported as an empty successful timeline. Known direct references return an honest denial without leaking content.
+- A failed restore leaves the current field and its history unchanged. Recovery is one atomic, attributable Revision and can itself be inspected or undone.
+- Concurrent current edits cannot be silently overwritten by a restore prepared against an older state; Content exposes a stale/conflict state or applies a contractually safe merge.
+
+## Boundaries and non-goals
+
+- Field history does not create a named Version for every edit.
+- Snapshot timing does not decide Revision boundaries; causality and editing intent do.
+- A Blocks field is not a full Page and does not acquire independent top-level Properties, sharing, or Database membership.
+- This Capability does not define the Page-level branching graph, selective cross-Version merge, or canonical promotion owned by `content.version.branching`.
+- Queryable History may project these Revisions across objects, but it is not the source of truth for the field's identity.
+
+## Acceptance stories
+
+### Recover one field without replacing its Page
+
+Given a Page with two Blocks fields and unrelated top-level Properties, when an editor restores an earlier Revision of one field, then only that field changes, the other field and Properties remain intact, and the restore produces a new attributable Revision.
+
+### Preserve anchors after deletion
+
+Given a Comment anchored to a Block range, when the range and then the Block are deleted, then the Comment remains durable and can open the historical field Revision showing the original target rather than being auto-archived or attached to plausible-looking new text.
+
+### Keep agent edits attributable
+
+Given one agent run edits several Blocks in two fields, when a reviewer opens History, then the changes are grouped by causal run while remaining inspectable per field and are attributed to the agent and authorizing context.
+
+### Survive named-Version operations
+
+Given two named Versions with independent edits to the same logical field, when one is promoted and the other archived and restored, then both field histories, Block identities, anchors, and actors remain intact.
+
+## Current evidence
+
+Current whole-document snapshots and restore behavior demonstrate useful recovery substrate. They do not prove independently addressable Blocks-field history, causal Revision grouping, stable Block identity across every edit, cross-field selective recovery, or preservation through named Versions. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Exercise text and structured Block edits, moves, deletions, and restores in every Blocks-field-owning object.
+2. Verify Event-to-Revision grouping for human, agent, automation, API, and integration actors.
+3. Compare and restore one field while other fields, title, Properties, memberships, and concurrent edits remain intact.
+4. Verify Comment, Annotation, reference, and execution-receipt anchors before and after edits, deletion, restore, and named-Version operations.
+5. Test access denial, stale restore, persistence interruption, Undo, reload, export, and lossless round-trip.
+6. Run the workflow through the real editor and shared Actions, including keyboard and assistive-technology inspection.
+
+## Open questions
+
+The remaining major seam is how one named Page Version selects or groups several independently versioned Blocks fields. Physical snapshot cadence, storage layout, compaction, and indexing remain implementation choices as long as the causal and recovery contract survives.