@agent-native/core 0.130.2 → 0.131.2

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.

package/corpus/templates/content/docs/product/capabilities/content.expression.catalog.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.expression.catalog"
+name: "Expression catalog"
+user_promise: "Promote a useful expression or variable into a governed reusable definition with clear ownership and version."
+primary_user_job: "Promote reusable expressions with controlled version adoption."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.expression.language", "content.template.governance"]
+related_features: ["content.feature.put-your-organizations-know-how-to-work"]
+roadmap_boundary: "feature"
+acceptance_summary: "The catalog governs named Expressions and zero-input Variables with stable identity, scope, descriptions, versions, approvals, provenance, references, inspection, and deliberate adoption."
+proof_requirements:
+  [
+    "An inline expression may be promoted when reuse is real; a zero-input expression is a Variable, not a separate language.",
+    "Catalog discovery and mutation honor scope and access, while callers can inspect type, dependencies, provenance, and version.",
+    "Adoption records a pinned or following version choice and never silently rewrites a consumer.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Expression catalog
+
+## Why this exists
+
+A useful computation should be reusable without becoming an invisible shared global that changes under its consumers. Teams need to know what it accepts, who owns it, and which version each workflow chose.
+
+## Example workflow
+
+Omar promotes `businessDays(start, end)`, adopts version 1 in two databases, and sees both consumers before publishing a signature-changing version 2.
+
+## Product contract
+
+- An inline expression may be promoted when reuse is real; a zero-input expression is a Variable, not a separate language.
+- Catalog discovery and mutation honor scope and access, while callers can inspect type, dependencies, provenance, and version.
+- Adoption records a pinned or following version choice and never silently rewrites a consumer.
+
+## Boundaries and non-goals
+
+- `content.expression.language` owns AST/type semantics; catalog governance owns named definition identity, approval, adoption, and version provenance.
+- The catalog does not make expressions ambient globals, silently update callers, or create a second Variable language.
+
+## Acceptance stories
+
+### Variables share the language
+
+Given a zero-input entry, when cataloged, then it is a Variable with the same AST and version rules.
+
+### Preserve consumer choice
+
+Given a signature changes, then consumers stay pinned or explicitly follow after impact review.
+
+## Current evidence
+
+`actions/configure-document-property.ts` and template records are donors; no expression catalog, version, or adoption records exist.
+
+## Proof plan
+
+1. Promote inline expressions/Variables with ID, scope, signature, dependencies, provenance.
+2. Adopt pinned/following versions in formulas/templates/Rules.
+3. Publish signature changes with impact and consumer choice.
+4. Test denied scope and unavailable dependencies.
+
+## Open questions
+
+Organization approval requirements remain open.

package/corpus/templates/content/docs/product/capabilities/content.expression.language.md

@@ -0,0 +1,76 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.expression.language"
+name: "Typed expression language"
+user_promise: "Use one understandable expression language whenever a configuration needs computation."
+primary_user_job: "Configure computation once across Content surfaces."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: []
+related_features:
+  [
+    "content.feature.make-the-workspace-yours",
+    "content.feature.data-that-keeps-itself-right",
+    "content.feature.build-living-dashboards",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Expressions share one typed AST and editor across formulas, views, validation, Rules, schedules, body configuration, and reusable definitions; zero-input expressions are Variables, while references remain stored typed values."
+proof_requirements:
+  [
+    "Stored references preserve identity without executing; expressions can return, compare, traverse, or render typed values.",
+    "The type system, dependency graph, and access checks are shared by every consumer rather than each surface inventing a dialect.",
+    "Compile, type, cycle, unavailable-input, and access failures stay distinguishable from a valid empty result.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Typed expression language
+
+## Why this exists
+
+Configuration becomes untrustworthy when each surface invents its own formula, filter, or rule syntax. People need one way to understand computation and one set of honest diagnostics when it cannot be evaluated.
+
+## Example workflow
+
+Inez previews a formula against a row, reuses its AST in validation, and sees a cycle before saving either configuration.
+
+## Product contract
+
+- Stored references preserve identity without executing; expressions can return, compare, traverse, or render typed values.
+- The type system, dependency graph, and access checks are shared by every consumer rather than each surface inventing a dialect.
+- Compile, type, cycle, unavailable-input, and access failures stay distinguishable from a valid empty result.
+
+## Boundaries and non-goals
+
+- Typed Properties, Views, Rules, and Templates consume this language; none owns a competing evaluator or private grammar.
+- Expressions do not replace stable References, bypass access, or collapse invalid, unavailable, and empty values into one result.
+
+## Acceptance stories
+
+### Keep references distinct
+
+Given `@Project`, when stored, then it remains a typed reference; `@Project.Status` is computation.
+
+### Explain impossible computation
+
+Given a cycle or unreadable query, then typechecking reports that distinct cause.
+
+## Current evidence
+
+`actions/configure-document-property.ts`, `shared/properties.ts`, and `shared/nfm.ts` are donors; common AST/typechecking/access-scoped query semantics are absent.
+
+## Proof plan
+
+1. Parse/typecheck/round-trip formulas, filters, validation, Rules, schedules, and body contexts.
+2. Test references and access separately.
+3. Detect cycles, missing values, stale input, and denied query handles.
+4. Compare two editors' persisted AST and diagnostics.
+
+## Open questions
+
+Syntax and initial built-ins remain open.

package/corpus/templates/content/docs/product/capabilities/content.feedback.signal.md

@@ -0,0 +1,67 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.feedback.signal"
+name: "Reactions and Polls"
+user_promise: "Structured reactions and option-based Polls live inside the Page Discussion and can render through views or embeds"
+primary_user_job: "Collect lightweight feedback in the discussion where its context and access belong."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.discussion.page", "content.access.safe-aggregate"]
+related_features: ["content.feature.collaborate-in-context"]
+roadmap_boundary: "feature"
+acceptance_summary: "Reactions and Polls are Discussion messages with stable option identities, response and close rules, one featured Poll per Page, access-safe results, anti-abuse controls, and shared View or embed rendering.."
+proof_requirements:
+  [
+    "Typed contract, authorization, validation, Event/history, and recovery coverage",
+    "Cross-surface UI, Action, agent-context, reload, and failure-state coverage",
+    "Real-interface keyboard and assistive-technology workflow coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Reactions and Polls
+
+## Why this exists
+
+Votes and reactions make sense beside the conversation that gave them meaning; a survey silo loses both context and access boundaries.
+
+## Example workflow
+
+A Page owner posts a Poll with stable options in Discussion, features it on the Page, and later closes it. A View renders the same result without creating another poll.
+
+## Product contract
+
+Reactions and Polls are Discussion messages with stable option identities, response and close rules, one featured Poll per Page, access-safe results, anti-abuse controls, and shared View or embed rendering.
+
+## Boundaries and non-goals
+
+Discussion owns message identity and safe aggregates own totals. This is not a survey silo, anonymous access bypass, or a new Page type.
+
+## Acceptance stories
+
+### Close a featured decision poll
+
+Given private respondents, when another viewer opens the featured Poll, then results reveal only the aggregation allowed by their access.
+
+### Hide private votes in a rollup
+
+Given a closed Poll, when a late response is attempted, then Content refuses it while preserving the Poll and prior attributed responses.
+
+## Current evidence
+
+No complete Poll identity, response, visibility, renderer, and recovery proof is recorded. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test Discussion Poll identity, featured limits, stable options, close state, and responses.
+2. Verify visibility, safe aggregates, abuse controls, Views, and embeds.
+3. Exercise late responses, unavailable Discussions, keyboard voting, and result announcements.
+
+## Open questions
+
+The initial reaction vocabulary and anonymous-response policy need design.

package/corpus/templates/content/docs/product/capabilities/content.form.shared-engine.md

@@ -0,0 +1,72 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.form.shared-engine"
+name: "Shared Form engine"
+user_promise: "Content Form Views and Agent Native Forms use one schema, validation, permission, and idempotent submission engine."
+primary_user_job: "Collect structured input once with the same contract whether it arrives from a Form View, an embedded Form, or an agent."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.property.constraints",
+    "content.agent.action-parity",
+    "content.event.committed",
+  ]
+related_features: ["content.feature.collect-structured-input"]
+roadmap_boundary: "feature"
+acceptance_summary: "Form schemas define typed fields, validation, permission, submission target, idempotency, and receipts."
+proof_requirements:
+  [
+    "Typed contract, authorization, validation, Event/history, and recovery coverage",
+    "Cross-surface UI, Action, agent-context, reload, and failure-state coverage",
+    "Real-interface keyboard and assistive-technology workflow coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Shared Form engine
+
+## Why this exists
+
+A question should not become less trustworthy because it appears in an embed instead of a Form View. One submission contract keeps duplicate and invalid input honest.
+
+## Example workflow
+
+A requester submits an intake Form from an embed. The same schema validates it as the internal Form View, rejects a duplicate idempotency key, and creates one canonical record with an Event.
+
+## Product contract
+
+Form schemas define typed fields, validation, permission, submission target, idempotency, and receipts. Content Form Views, Agent Native Forms, and agents call one submission Action.
+
+## Boundaries and non-goals
+
+Property constraints own field rules and Events own committed receipts. This is not a second forms datastore, raw endpoint bypass, or a promise that every form is public.
+
+## Acceptance stories
+
+### Return the original receipt on retry
+
+Given the same submission is retried, when the idempotency key matches, then Content returns the original receipt and creates no duplicate record.
+
+### Reject a hidden field from an embed
+
+Given an unauthorized field value, when it is submitted from an embed or agent, then shared validation denies it with the same typed failure.
+
+## Current evidence
+
+No complete shared schema, idempotency, cross-surface permission, and recovery proof is recorded. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Define one schema and submit it from Form Views, embeds, and agents.
+2. Test validation, permissions, idempotency, receipts, retries, and target availability.
+3. Run keyboard and screen-reader completion flows with rejected-field recovery.
+
+## Open questions
+
+Public-form identity and draft-save policy need design.