@agent-native/core 0.130.2 → 0.131.2

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

@@ -0,0 +1,76 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.property.catalog"
+name: "Custom Properties"
+user_promise: "Reuse an approved field definition deliberately without making same-named local columns secretly equal."
+primary_user_job: "Reuse a governed field and safely update or detach it."
+kind: "primitive"
+state: "exploring"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.property.typed", "content.template.governance"]
+related_features:
+  [
+    "content.feature.connect-your-sources",
+    "content.feature.share-how-your-organization-works",
+    "content.feature.evolve-systems-safely",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Custom Properties are governed, scoped reusable typed definitions with stable identity, description, provenance, query semantics, versioned updates, impact preview, safe migration, and detachable local copies."
+proof_requirements:
+  [
+    "The add-column picker distinguishes built-in local types, source-backed fields, and personal, workspace, or organization Custom Properties.",
+    "A definition's stable identity—not its name—controls query meaning, provenance, and compatible updates.",
+    "A consumer may detach to a local field; updates are reviewed and impact-previewed, never silently applied.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Custom Properties
+
+## Why this exists
+
+Same-named columns are not shared meaning. Organizations need a way to reuse a field deliberately, understand where it came from, and evolve it without silently rewriting a local database.
+
+## Example workflow
+
+Marta publishes Customer tier, a database adopts it, previews an enum update, and another database detaches locally while keeping values.
+
+## Product contract
+
+- The add-column picker distinguishes built-in local types, source-backed fields, and personal, workspace, or organization Custom Properties.
+- A definition's stable identity—not its name—controls query meaning, provenance, and compatible updates.
+- A consumer may detach to a local field; updates are reviewed and impact-previewed, never silently applied.
+
+## Boundaries and non-goals
+
+- `content.property.typed` owns type semantics and Template governance owns catalog policy; Custom Properties own reusable definition/adoption identity.
+- The catalog does not equate columns by name, make local columns secretly global, or auto-migrate incompatible values.
+
+## Acceptance stories
+
+### Labels are not identity
+
+Given local and organization Status fields, when an author opens Add column, then Add column distinguishes their IDs and origins.
+
+### Stage risky migration
+
+Given a breaking type/option update, when its owner proposes publication, then Content previews impact and blocks or stages unsafe conversion.
+
+## Current evidence
+
+`server/plugins/db.ts`, `actions/configure-document-property.ts`, `actions/bind-content-database-source-field.ts`, and `DocumentProperties.tsx` are donors; catalog/adoption/detach/migration do not exist.
+
+## Proof plan
+
+1. Build scoped Add column discovery with IDs/provenance.
+2. Adopt across databases and test semantics/access.
+3. Publish compatible/breaking versions with impact/migration/receipts.
+4. Detach without losing values.
+
+## Open questions
+
+Scope names need root judgment.

package/corpus/templates/content/docs/product/capabilities/content.property.constraints.md

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.property.constraints"
+name: "Property validation and defaults"
+user_promise: "Configure requiredness, defaults, validation, formatting, and edit policy once and trust every write path to enforce them."
+primary_user_job: "Set constraints and defaults every mutation path enforces."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.property.typed", "content.expression.language"]
+related_features:
+  [
+    "content.feature.data-that-keeps-itself-right",
+    "content.feature.collect-structured-input",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Property configuration validates every mutation atomically; formulas remain live, while defaults evaluate once during a successful creation transaction and become stored values."
+proof_requirements:
+  [
+    "Constraints, format, requiredness, and edit policy are typed configuration interpreted by the shared mutation boundary.",
+    "Defaults evaluate exactly once only after the creation transaction has enough context to succeed; they are not live formulas.",
+    "Validation failure returns typed field diagnostics and commits no partial mutation through UI, agent, import, source sync, or API.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Property validation and defaults
+
+## Why this exists
+
+A rule that only the form enforces is not a data rule. Authors need defaults and validation to behave predictably whether a record comes from a person, agent, import, or source synchronization.
+
+## Example workflow
+
+Elena creates a Form row with required Priority and a Due date default; the default stores once while a formula remains live.
+
+## Product contract
+
+- Constraints, format, requiredness, and edit policy are typed configuration interpreted by the shared mutation boundary.
+- Defaults evaluate exactly once only after the creation transaction has enough context to succeed; they are not live formulas.
+- Validation failure returns typed field diagnostics and commits no partial mutation through UI, agent, import, source sync, or API.
+
+## Boundaries and non-goals
+
+- Typed Properties own field type and Expressions own live computation; this record owns transaction-time defaults, constraints, format, and edit policy.
+- Defaults are not formulas, and client-side form checks are not a substitute for the shared mutation boundary.
+
+## Acceptance stories
+
+### Roll back atomically
+
+Given an agent changes two fields and one is invalid, when the mutation commits, then neither commits and the failing field is identified.
+
+### Do not turn defaults live
+
+Given a current-actor default, when the actor later changes, then later actor changes do not rewrite the stored value.
+
+## Current evidence
+
+`actions/configure-document-property.ts`, `set-document-property.ts`, and lifecycle tests are donors; cross-origin rule semantics are unproved.
+
+## Proof plan
+
+1. Configure/test via forms, UI, actions, import, and sync.
+2. Verify defaults evaluate once and formulas remain live.
+3. Test invalid multi-field rollback and typed errors.
+4. Exercise denied dependencies and retry.
+
+## Open questions
+
+Default dependency ordering needs shaping.

package/corpus/templates/content/docs/product/capabilities/content.property.guarded-change.md

@@ -0,0 +1,76 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.property.guarded-change"
+name: "Guarded property changes"
+user_promise: "Require an explained confirmation or policy check before a sensitive field transition while keeping one general validation engine."
+primary_user_job: "Satisfy a clear shared safeguard before sensitive changes."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.property.constraints", "content.event.committed"]
+related_features:
+  [
+    "content.feature.trust-your-connected-sources",
+    "content.feature.data-that-keeps-itself-right",
+    "content.feature.publish-with-confidence",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Any Property can declare validation and safeguards for sensitive transitions; the shared mutation boundary evaluates them, explains required confirmation or policy failure, and records committed changes normally."
+proof_requirements:
+  [
+    "Status is a useful UI for a guarded change but is not the exclusive safeguard engine.",
+    "UI, agent, automation, source sync, import, and API calls use the same validation and policy boundary.",
+    "A blocked transition produces an actionable reason and no partial write; accepted confirmation or policy result is attributable in history.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Guarded property changes
+
+## Why this exists
+
+Some values carry consequences that deserve more than an accidental click, yet a special status dialog cannot protect the same change made by automation. People need one explainable safeguard at the mutation boundary.
+
+## Example workflow
+
+A release manager moves Draft to Published with required confirmation and sees the same policy apply to agent and source-sync changes.
+
+## Product contract
+
+- Status is a useful UI for a guarded change but is not the exclusive safeguard engine.
+- UI, agent, automation, source sync, import, and API calls use the same validation and policy boundary.
+- A blocked transition produces an actionable reason and no partial write; accepted confirmation or policy result is attributable in history.
+
+## Boundaries and non-goals
+
+- Constraints own ordinary validity; committed events own attribution/history; guarded change owns the added safeguard decision and explanation.
+- Status is only one useful surface: safeguards are not status-only workflows, a new permission system, or a client-only confirmation.
+
+## Acceptance stories
+
+### Guard every origin
+
+Given source sync attempts a sensitive transition, when it reaches the mutation boundary, then it receives the same decision as UI.
+
+### Explain refusal
+
+Given confirmation is absent, when an editor requests the transition, then no mutation occurs and the rule/next action are clear.
+
+## Current evidence
+
+`actions/change-content-database-source-role.ts` and `set-document-property.ts` are donors; general safeguard evaluation is absent.
+
+## Proof plan
+
+1. Configure safeguards on status, date, relation, and ordinary fields.
+2. Compare UI/action/agent/automation/import/sync decisions.
+3. Test expiry, retry, concurrency, no partial writes.
+4. Verify explanations and actor history.
+
+## Open questions
+
+Vocabulary and separate-reviewer policy remain open.

package/corpus/templates/content/docs/product/capabilities/content.property.location.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.property.location"
+name: "Typed locations"
+user_promise: "Store a place or coordinates as a meaningful location that maps, queries, sources, and export can understand."
+primary_user_job: "Capture a place at known precision for portable use."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.property.typed"]
+related_features: []
+roadmap_boundary: "supporting"
+acceptance_summary: "Location Properties preserve a typed structured place and coordinates with clear precision, display, query, source mapping, and portable export behavior."
+proof_requirements:
+  [
+    "A location is typed structured data, not a display string or map pin owned by one renderer.",
+    "Authors can keep a human place, coordinates, and known precision without fabricating missing geocoding data.",
+    "Maps and sources are projections/adapters; access, queries, and export use the canonical value and disclose unsupported fields honestly.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Typed locations
+
+## Why this exists
+
+A place has more meaning than an address string, but false precision is actively misleading. Authors need to preserve what they know about a location while letting maps and exports consume it without inventing details.
+
+## Example workflow
+
+Nia records a field visit with label, coordinates, and approximate precision; map and nearby query use it while export retains known data.
+
+## Product contract
+
+- A location is typed structured data, not a display string or map pin owned by one renderer.
+- Authors can keep a human place, coordinates, and known precision without fabricating missing geocoding data.
+- Maps and sources are projections/adapters; access, queries, and export use the canonical value and disclose unsupported fields honestly.
+
+## Boundaries and non-goals
+
+- Typed Properties own the value contract; map Views and provider adapters consume or map locations without becoming the source of truth.
+- Locations do not imply geocoding, tracking, hidden precision, or an automatic map-provider dependency.
+
+## Acceptance stories
+
+### Do not invent precision
+
+Given a source only provides a city, when Content imports it, then Content keeps city/precision without fabricating coordinates.
+
+### Maps are projections
+
+Given a renderer fails, when a person opens the Location Property, then the location remains queryable and exportable.
+
+## Current evidence
+
+`app/components/editor/DocumentProperties.tsx` maps location to `place`; `shared/properties.ts` includes `place`, but no structured location schema exists.
+
+## Proof plan
+
+1. Author labels/coordinates/precision and serialize them.
+2. Query/render in map and non-map surfaces.
+3. Import partial provider values without invented geocoding.
+4. Export/import with access-aware coordinates.
+
+## Open questions
+
+Points versus polygons/routes is open.

package/corpus/templates/content/docs/product/capabilities/content.property.typed.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.property.typed"
+name: "Typed Properties"
+user_promise: "Define stored and computed fields whose values and descriptions stay meaningful in every surface."
+primary_user_job: "Define fields whose types survive every Content operation."
+kind: "primitive"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies: []
+related_features: ["content.feature.data-that-keeps-itself-right"]
+roadmap_boundary: "feature"
+acceptance_summary: "Properties declare stable stored or computed types, descriptions, configuration, and renderer contracts so values can be authored, queried, validated, rendered, and exported without ambiguous coercion."
+proof_requirements:
+  [
+    "Stored values and computed results both declare exact output types; presentation is a renderer choice, not a hidden data conversion.",
+    "Descriptions and typed semantics are available to people, agents, queries, validation, and export.",
+    "Unknown, invalid, absent, and unreadable values remain distinct.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Typed Properties
+
+## Why this exists
+
+A field label alone cannot tell a database, export, or agent what a value means. Without durable types, dates become text and missing access becomes an innocent blank, quietly corrupting later work.
+
+## Example workflow
+
+Dara adds a place field, describes it, and sees the same typed value in property panel, database view, and export.
+
+## Product contract
+
+- Stored values and computed results both declare exact output types; presentation is a renderer choice, not a hidden data conversion.
+- Descriptions and typed semantics are available to people, agents, queries, validation, and export.
+- Unknown, invalid, absent, and unreadable values remain distinct.
+
+## Boundaries and non-goals
+
+- `content.property.constraints` owns validation/default behavior and `content.expression.language` owns computed semantics; Typed Properties own declared value/output types.
+- A renderer may change presentation but cannot change stored meaning or coerce denied/invalid/absent states into a normal value.
+
+## Acceptance stories
+
+### Keep computed type
+
+Given a date formula, when sorted/rendered/exported, then each consumer gets a declared date.
+
+### Do not coerce absence
+
+Given unreadable relation and blank text, then renderers keep them distinct.
+
+## Current evidence
+
+`shared/properties.ts`, `actions/configure-document-property.ts`, and `app/components/editor/DocumentProperties.tsx` are donors; formula output types are not durable general declarations.
+
+## Proof plan
+
+1. Create/query/render/export stored and computed types.
+2. Propagate descriptions to UI/actions/agents/serialization.
+3. Test absent, invalid, unreadable, unsupported values.
+4. Compare UI/action validation.
+
+## Open questions
+
+Computed output taxonomy needs root judgment.

package/corpus/templates/content/docs/product/capabilities/content.publish.public.md

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.publish.public"
+name: "Public publication"
+user_promise: "Publish one chosen Page revision at a stable public destination while private work continues safely."
+primary_user_job: "Make an approved version public without accidentally publishing draft edits, comments, or private dependencies."
+kind: "workflow"
+state: "approved_shape"
+publicness: "public"
+availability: "configured"
+dependencies:
+  [
+    "content.access.visibility-closure",
+    "content.version.branching",
+    "content.renderer.typed",
+  ]
+related_features: ["content.feature.publish-with-confidence"]
+roadmap_boundary: "feature"
+acceptance_summary: "A Page-first publication object binds a stable destination to one Page, selected Version, and exact revision, previews the actual audience closure, records lifecycle events, and changes only when an authorized publisher explicitly updates or withdraws it."
+proof_requirements:
+  [
+    "Publication identity, revision binding, lifecycle, URL, and rollback tests",
+    "Audience-closure and private-collaboration leakage tests",
+    "Publisher preview, publish, private follow-on edit, update, and unpublish interface workflow",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Public publication
+
+## Why this exists
+
+Public truth deserves a deliberate pin, not whatever happened to be in the editor when the wind changed.
+
+## Example workflow
+
+An editor previews the approved article revision, publishes it at a stable URL, continues private revision work, then explicitly replaces the public revision after another preview.
+
+## Product contract
+
+- Publication is Page-first and binds Page identity, selected Version, exact revision, destination, audience closure, and lifecycle history.
+- The stable URL serves the last explicitly published revision; private edits, comments, unpublished Versions, and inaccessible assets do not follow it automatically.
+- Preview evaluates the real audience closure and renderer fallback before publish. Publish, update, and unpublish are explicit guarded actions with actor/origin receipts.
+- Provider publishing remains a separate Source lifecycle action, not a consequence of public Content publication.
+
+## Boundaries and non-goals
+
+Public reading owns rendering; sharing owns access; provider adapters own external publishing. This does not turn every shared Page into a public publication.
+
+## Acceptance stories
+
+### Hold a public revision steady
+
+Given a published Page and a private draft edit, when the draft changes, then the public URL keeps serving the prior bound revision until an authorized publisher updates it.
+
+### Prevent private closure leaks
+
+Given the selected revision references a private comment and inaccessible asset, when preview runs, then it identifies their public treatment and publishing does not expose either.
+
+## Current evidence
+
+Donor evidence: `server/lib/public-documents.ts`, `server/lib/public-documents.spec.ts`, and `app/routes/p.$id.tsx` implement public Page substrate. They do not prove Page/Version/revision publication identity or lifecycle isolation; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Model publication bindings and guarded lifecycle Actions.
+2. Test revision stability, closure, rollback, update, withdrawal, and provider separation.
+3. Verify preview and full public lifecycle in the browser.
+
+## Open questions
+
+- Publication scheduling and multiple destinations are future decisions.

package/corpus/templates/content/docs/product/capabilities/content.publish.reading.md

@@ -0,0 +1,74 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.publish.reading"
+name: "Public reading"
+user_promise: "A shareable reading surface faithfully renders the intended public Content truth."
+primary_user_job: "Let readers open a public document quickly and understand the same meaningful content an editor approved."
+kind: "surface"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.renderer.typed", "content.access.visibility-closure"]
+related_features: ["content.feature.publish-with-confidence"]
+roadmap_boundary: "feature"
+acceptance_summary: "A cache-safe public shell resolves only public reading data, renders supported Content blocks through the shared semantic pipeline with safe fallbacks, and preserves metadata, accessible navigation, embeds, and portable links without personalized SSR."
+proof_requirements:
+  [
+    "SSR shell, access, cache, metadata, and no-personalization regression tests",
+    "Shared renderer fidelity and fallback tests for public blocks, media, and embeds",
+    "Browser reading workflow for public, unavailable, and changed-public-content states",
+  ]
+evidence:
+  [
+    "../../../app/routes/p.$id.tsx",
+    "../../../app/__tests__/public-document-route.test.ts",
+  ]
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Public reading
+
+## Why this exists
+
+Publication needs a reader, not merely a route that happens to return HTML.
+
+## Example workflow
+
+A visitor opens a public article link, reads a faithful server-rendered shell, uses accessible headings and media fallbacks, and gets an honest unavailable state for a withdrawn page.
+
+## Product contract
+
+- Public SSR remains one impersonal cacheable shell; personal state and authorization branches happen after load, never by cookie-varying the shell.
+- The reader uses shared semantic rendering and deliberate fallbacks so public reading, export, and editor meaning do not drift gratuitously.
+- Metadata, canonical links, embeds, assets, and accessible navigation reflect the published public closure.
+- Missing, withdrawn, or inaccessible public artifacts are explicit states, not stale content or empty success.
+
+## Boundaries and non-goals
+
+Publication owns exact revision choice; this owns rendering that choice. It does not make private editor capabilities public or duplicate the Reader surface.
+
+## Acceptance stories
+
+### Serve a public shell safely
+
+Given a public Page, when an anonymous reader opens it, then the server returns public content without a personalized cache branch and the client may add only viewer-local behavior after load.
+
+### Handle withdrawal honestly
+
+Given a published destination has been withdrawn, when a reader follows its stable URL, then it receives an explicit unavailable page rather than stale prior content.
+
+## Current evidence
+
+Implementation evidence: `app/routes/p.$id.tsx` and `app/__tests__/public-document-route.test.ts` cover current public route behavior. Donor evidence does not yet prove full renderer fidelity, publication-version integration, or all fallback cases, so this record remains `in_progress`.
+
+## Proof plan
+
+1. Test public cache-shell and access invariants against all public route paths.
+2. Add renderer fixtures for supported blocks, assets, embeds, and fallbacks.
+3. Browser-test public read, unavailable, and updated-public-revision states.
+
+## Open questions
+
+- The public reading typography and optional interactive enhancement set remain open.

package/corpus/templates/content/docs/product/capabilities/content.query.object.md

@@ -0,0 +1,114 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.query.object"
+name: "Reusable Query objects"
+user_promise: "A one-off inline Query can be promoted into a named reusable Content object that behaves like a dynamic Database without owning its source records"
+primary_user_job: "Define a reusable live collection across one or more authorized inputs without copying or taking ownership of their records."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  ["content.expression.language", "content.access.visibility-closure"]
+related_features:
+  [
+    "content.feature.make-the-workspace-yours",
+    "content.feature.connect-your-sources",
+    "content.feature.work-across-every-workspace",
+    "content.feature.sketch-connections-keep-whats-true",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Inline and named Queries derive access-scoped typed collections with stable output contracts, composable inputs, explicit write-through and creation routes, and no ownership of source records."
+proof_requirements:
+  [
+    "Stable inline/named Query identity, typed AST, variables, output schema, history, reference, embed, and template behavior",
+    "Access-first composition of Databases, Sources, and Queries with cycle, scale, stale, and unavailable states",
+    "Canonical provenance plus unambiguous field write-through and explicit creation routes",
+    "Visual editor and agent manipulation of the same validated typed representation",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Reusable Query objects
+
+## Why this exists
+
+People often need a live collection whose members come from several places or satisfy reusable conditions. Copying those records into another Database creates stale duplicates and ambiguous ownership. A Query composes the originals while keeping their identity, permissions, and write authority intact.
+
+## Example workflow
+
+A team combines Blog articles and Resources, aligns each source's title field into one output called `Title`, filters to published material, and renders the result as a List. The inline result can be saved as a named Query, embedded on another Page, and reused by a later Query. Editing an article title writes to that article's canonical owner; the aligned `Title` definition remains Query-owned presentation.
+
+## Product contract
+
+- A Query derives a typed collection from Databases, approved Sources, other Queries, or access-scoped graph traversal.
+- Its definition may include unions, joins, intrinsic filters, projected fields, aliases, computed fields, output types, variables, documentation, limits, and ordering that is part of the result's meaning.
+- Query filters define the reusable input contract. A View may filter that result further but can never unfilter records the Query excluded.
+- One-off Queries may remain inline in a View or Block. **Save as Query** gives the same typed definition stable identity, title, description, access, history, discoverability, references, embeds, templates, Views, and Query-as-input reuse.
+- A named Query owns its AST, variables, output-field identities, aliases, computed fields, documentation, compatible default renderers, and history.
+- Input Databases and Sources exclusively own canonical records, memberships, schemas, stored values, source permissions, and provider write authority.
+- Every result retains canonical record identity, source provenance, stable field mapping, freshness, access, and write capability.
+- The visual builder and agents manipulate the same validated typed AST. Faux SQL or a typed inspector may help power users, but there is no separate AI-only query language.
+- A Query's complete definition is visible to its readers. It never runs with its owner's authority; each dependency and result is evaluated for the current viewer.
+
+## Editing and creation
+
+- An ordinary mapped field may write through only when canonical record identity, field mapping, actor permission, source policy, and provider capability are unambiguous.
+- Computed fields, aggregates, lossy alignments, and ambiguous joined fields are read-only.
+- A Query declares zero or more permitted creation routes that end at writable Databases or Sources. A Query never pretends to own new rows.
+- When exactly one route applies, creation proceeds with safe defaults and contextual seeds. When several apply, the View may choose an allowed default or Content asks for a compact destination choice. With no route, the Query is truthfully read-only.
+- Human, agent, automation, and API creation use the same route analysis and committed Action.
+
+## Failure and scale behavior
+
+- Missing access at any dependency is applied before evaluation. The Query does not borrow owner credentials or leak excluded records through counts, groups, aggregates, errors, or metadata.
+- A required inaccessible, stale, or unavailable dependency produces a typed degraded or Unavailable state according to the Query contract; it is never silently pruned into a plausible partial answer.
+- Query-to-Query composition performs dependency and cycle analysis before save.
+- Pagination, limits, traversal bounds, aggregation bounds, and cancellation prevent one reusable Query from becoming an unbounded background job.
+- A failed write-through or mixed provider outcome remains distinguishable from a successful read-only result.
+
+## Boundaries and non-goals
+
+- A Database owns a governed writable collection; a Query derives a collection; a View presents and downstream-filters either input.
+- An ordinary Database View does not hide a named Query beneath it. **Create Query from this View** is an explicit builder flow that confirms sources, output schema, variables, and write behavior.
+- Query output aliases never rename source fields, and computed output never becomes stored source data by implication.
+- Saving a Query does not materialize or duplicate its records.
+- A Query is not an access grant. If someone needs a fixed result that recipients may see without source access, they create an explicitly published/materialized snapshot.
+
+## Acceptance stories
+
+### Promote an inline Query without copying records
+
+Given an inline Query over two Databases, when an editor chooses **Save as Query**, then the definition gains stable identity and the original occurrence references it while every result still points to its canonical source record.
+
+### Preserve authority during composed writes
+
+Given a result with one mapped source field, one computed field, and two possible creation routes, when an editor changes each field and creates a record, then the mapped edit follows its authorized owner, the computed edit is refused, and creation uses an explicit permitted destination rather than guessing.
+
+### Re-evaluate for every viewer
+
+Given a shared cross-workspace Query whose readers have different source access, when each opens it, then both see the full definition but only their authorized result intersection. Counts, aggregates, and nested Queries reveal no inaccessible records.
+
+### Fail honestly on a broken dependency
+
+Given a required nested Query becomes unavailable or cyclic, when the parent evaluates, then it reports the typed dependency failure and preserves the saved definition instead of returning a clean-looking partial or empty result.
+
+## Current evidence
+
+Existing filters, saved Views, source federation, row-union, joined-detail, and write-routing code provide useful donor machinery. They do not yet prove one reusable Query object, a common typed AST, Query-as-source composition, access-first nested evaluation, explicit output contracts, or the complete write/create model. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Build equivalent inline and named Queries through visual controls and agent Actions; compare their typed AST and output schema.
+2. Compose Databases, provider Sources, graph traversal, and nested Queries with aliases, computed fields, variables, joins, unions, limits, and cycle checks.
+3. Verify record/field provenance, mapped writes, read-only derived fields, zero/one/many creation routes, defaults, validation, Events, and retries.
+4. Run every Query under differing Page, Database, Source, row, field, and workspace access and verify access before all computation.
+5. Exercise unavailable, stale, partial-provider, scale-bound, cancellation, and recovery behavior without losing the saved definition.
+6. Link, embed, template, version, export, and reuse the named Query through the real interface and shared Actions.
+
+## Open questions
+
+The stable `content.view.source-query` ID currently names the cross-source specialization even though it is semantically a Query. Preserve it until a deliberate normalization supplies a replacement ID. The internal common query engine may eventually deserve a private substrate record, but it must not become a fourth user-facing object beside Database, Query, and View.