@agent-native/core 0.130.1 → 0.131.2

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.

package/corpus/templates/content/docs/product/capabilities/content.reader.documents.md

@@ -0,0 +1,69 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.reader.documents"
+name: "Document Reader"
+user_promise: "The earlier separate PDF/EPUB reader proposal remains readable lineage rather than an active second product contract."
+primary_user_job: "Understand where native document-reading work belongs without building a separate reader identity or data system."
+kind: "surface"
+state: "superseded"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.reader.surface"]
+related_features: []
+roadmap_boundary: "superseded"
+acceptance_summary: "This lineage record directs new reading and annotation work to the unified Reader surface, keeps PDF export distinct, and prevents a separate document-reader app or source model from becoming an active requirement."
+proof_requirements:
+  [
+    "Catalog validation that supersession target remains present",
+    "Review of new reader work confirming it targets content.reader.surface",
+    "Regression review ensuring PDF export is not represented as native annotation support",
+  ]
+evidence: []
+superseded_by: "content.reader.surface"
+last_reviewed: "2026-07-29"
+---
+
+# Document Reader
+
+## Why this exists
+
+The original narrow reader idea captured a real need but split the product where one Reader surface now carries the contract.
+
+## Example workflow
+
+A contributor looking for PDF annotation requirements follows this record to `content.reader.surface` and `content.research.annotation`, rather than creating a new PDF/EPUB app and data model.
+
+## Product contract
+
+- This record is lineage only. New reading work targets the unified Reader surface over Content objects and source representations.
+- PDF export remains a read-oriented output path, not a substitute for reading state, selectors, or annotations.
+- Any later separate app shell may reuse the Reader contract without creating separate Content identity or custody.
+
+## Boundaries and non-goals
+
+This record does not specify new implementation, verify a reader, or preserve a separate document-only roadmap.
+
+## Acceptance stories
+
+### Route a new request correctly
+
+Given a proposal for EPUB highlighting, when it is classified, then it is evaluated against Reader surface and Annotation contracts rather than this superseded record.
+
+### Keep export distinct
+
+Given a PDF export improvement, when it is documented, then it does not claim native reading progress or annotation support.
+
+## Current evidence
+
+Repository product records identify `content.reader.surface` as the active unified target. This superseded record has no implementation proof and intentionally makes no delivery claim.
+
+## Proof plan
+
+1. Keep the supersession link valid in the product-doc guard.
+2. Review future reader records for unified identity and annotation ownership.
+3. Reject any new separate reader contract unless a later Shape explicitly changes this boundary.
+
+## Open questions
+
+- None; implementation questions belong to `content.reader.surface`.

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

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.reader.surface"
+name: "Reader surface"
+user_promise: "Read and annotate text, documents, web material, and media through one specialized Content surface."
+primary_user_job: "Read comfortably, find my place, and mark exact material without creating a separate copy of the source."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.author.media",
+    "content.research.annotation",
+    "content.source.adapters",
+  ]
+related_features: ["content.feature.read-and-annotate-anything"]
+roadmap_boundary: "feature"
+acceptance_summary: "A specialized, embeddable Reader renders stable Content and source representations with accessible personal reading preferences, durable progress, multimodal selectors, synchronized media/transcript modes, and Actions for annotation and assistive features."
+proof_requirements:
+  [
+    "Representation, selector, progress, preference, accessibility, and offline/cache policy tests across text and media",
+    "Annotation, version-change, source-availability, playback/transcript, and assistive-action tests",
+    "End-to-end read, annotate, resume, re-anchor, and embedded-reader workflow",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Reader surface
+
+## Why this exists
+
+Reading has its own rhythm: the work should be quiet, personal, and still connected to the object it interprets.
+
+## Example workflow
+
+A researcher opens a PDF representation, adjusts width and type, highlights a page range, adds an Annotation, resumes later at progress, and can follow a transcript while audio plays.
+
+## Product contract
+
+- Reader is an embeddable Content surface, not necessarily a separate application or dataset.
+- It renders text, PDFs, EPUBs, web material, audio, video, and transcripts through stable representation handles and source-aware fallbacks.
+- Per-viewer typography, theme, pagination/flow, progress, accessibility, cache/offline policy, text-to-speech, and dictation are personal surface state; they do not change shared source truth.
+- Annotations use durable selectors and version/revision context. Media playback and transcript positions remain synchronized where representations support them.
+
+## Boundaries and non-goals
+
+Annotations own contribution identity; adapters own representations and source availability; public reading owns public pages. Reader does not promise every format is editable or locally available.
+
+## Acceptance stories
+
+### Resume without changing the source
+
+Given two readers of the same source, when one changes typography and progress, then their preferences persist for that viewer without mutating the shared Page or other reader's layout.
+
+### Mark exact media material
+
+Given a source video with a transcript, when a researcher annotates a transcript range, then the Annotation retains the source representation and time/range selector and can reopen the corresponding media location.
+
+## Current evidence
+
+Donor evidence: editor media and source representations provide foundations for rendering. No dedicated multimodal Reader, personal progress model, or end-to-end annotation proof exists; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Define reader representation, personal state, selector, accessibility, and cache contracts.
+2. Test text, paged, transcript, audio/video, unavailable source, revision, and assistive paths.
+3. Verify reading, annotation, resume, and embed workflows in a real interface.
+
+## Open questions
+
+- The first format sequence and offline storage limits remain open.

package/corpus/templates/content/docs/product/capabilities/content.relationship.edge.md

@@ -0,0 +1,183 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.relationship.edge"
+name: "Typed Relationships"
+user_promise: "One typed edge substrate powers relation Properties, inline typed Page references, backlinks, Info, graph queries, and Graph editing"
+primary_user_job: "Connect two Pages once, give that connection a useful meaning, and manage it consistently from any Content surface."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.object.page",
+    "content.object.reference",
+    "content.property.typed",
+    "content.access.page-database",
+    "content.event.committed",
+  ]
+related_features:
+  [
+    "content.feature.living-references",
+    "content.feature.run-projects-your-way",
+    "content.feature.plan-work-across-time",
+    "content.feature.sketch-connections-keep-whats-true",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "People can create, inspect, edit, bulk-remove, restore, and query one canonical Relationship through every authorized surface without duplicated truth, silent partial mutation, access leaks, or lost concurrent history."
+proof_requirements:
+  [
+    "Canonical identity and projection parity across Relation Properties, Connections, inline references, Graph, Canvas promotion, agents, Rules, imports, and Sources",
+    "Directional cardinality, uniqueness, local-to-governed lifecycle, deletion, bulk mutation, and causal concurrency behavior",
+    "Access-first traversal and aggregation plus identical permission decisions through UI and Actions",
+    "Real-interface keyboard, accessibility, recovery, and Undo workflows",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Typed Relationships
+
+## Why this exists
+
+People encounter connections in many places: a Relation column, an `@` mention, a backlink, a project dependency, a Graph edge, or a line drawn on a Canvas. If each surface stores its own version of the connection, the workspace develops several incompatible kinds of truth.
+
+Content instead stores one canonical typed Relationship between stable Page identities. Relation Properties, Info, Queries, Graph, Canvas, agents, Rules, imports, and source adapters are projections and editing routes over that same edge.
+
+## Example workflow
+
+A team has a Tasks Database and a Projects Database. Adding a `Project` Relation Property to Tasks creates a local Relationship type and its first visible projection. A task editor connects a task to a project from the cell. The project immediately shows the inverse connection in **Info → Connections**, and an optional inverse Relation Property can expose the same edge as an editable `Tasks` column.
+
+Later, the team selects several tasks and assigns the same project in one bulk edit. Removing the `Project` column does not erase those relationships. If the team truly wants to remove both the column and its knowledge, the removal dialog offers **Remove Property and its N relationships**, reports the exact authorized impact, commits one Revision, and supports Undo.
+
+## Product contract
+
+### One relationship, many projections
+
+- Every semantic Relationship is one durable edge between stable Page IDs.
+- Both directions are always access-scoped and queryable. Content has no semantically one-way relationship whose inverse disappears from the system; people decide only where each direction is displayed and editable.
+- A directional Relationship type has a forward label and an optional inverse label. A symmetric type such as `Related to` has one canonical unordered edge, not two mirrored writable values.
+- A Relationship type and a visible Relation Property have separate stable identities. The type owns meaning, labels, per-direction cardinality, target constraints, provenance policy, and governing scope. The Property is one Database's editable projection of that type in one direction.
+- Databases own Relation Properties, not Relationships. Pages may be related without belonging to a Database, and removing a Property does not make the underlying edge anonymous or inaccessible.
+- Every editing surface invokes the same typed Relationship Action. No UI, agent, Rule, import, provider, Graph, or Canvas receives a private mutation engine.
+
+### Where people manage relationships
+
+- Adding an ordinary Relation column creates a local Relationship type and its first Property projection. It feels like adding any other column; no catalog ceremony is required.
+- **Info → Connections** is the universal relationship surface. It shows every accessible incoming and outgoing connection, including types not exposed as columns.
+- A Relation picker may use a Database or Query to narrow candidates, but the stored endpoint is the selected Page's stable ID. The edge remains if that Page later leaves the picker Query.
+- Ordinary Page mentions and transclusions create system-managed structural edges with their own mutation rules. An advanced inline action may create a semantic typed reference. Removing one anchored mention does not delete an independently asserted semantic Relationship.
+- In freeform Canvas mode, a drawn connector is view-local brainstorming state until someone explicitly promotes it to a Relationship type. In semantic Graph mode, the active edge tool requires a Relationship type before drawing commits an edge.
+- Existing relationships may be projected as Graph or Canvas lines. Deleting the visual occurrence or removing an object from one View never deletes the canonical Relationship.
+
+### Local and governed definitions
+
+- A local Relationship type belongs to the Content space where it was created and remains resolvable in Connections after its last visible Property is removed.
+- **Save as Custom Property** promotes the definition into the governed Custom Properties catalog at an allowed Personal, Workspace, or Organization scope.
+- Another Database may adopt the governed Property, creating another projection of the same Relationship type rather than copying its semantic identity.
+- Each projection may choose a local display alias, formatting, renderer, and visibility without changing the shared definition.
+- **Detach to local Property** preserves the projected data while creating an independent local definition.
+- Shared definitions are version-pinned. Label, cardinality, constraint, or inverse changes are proposed as readable updates that consuming Database owners adopt explicitly; catalog edits never silently rewrite every relationship system.
+- Provider-backed Relation fields use the same projection model while retaining source identity and synchronization authority.
+
+## Cardinality and identity
+
+- Cardinality is defined independently in each direction. A Task may have one Parent task while a parent has many children; a symmetric `Related to` type may be many-to-many.
+- Requiredness is separate Database/Property validation. `At most one` does not mean `must have one`.
+- Selecting a new target in a single-value Relation Property replaces the observed existing edge as one atomic change.
+- Moving a one-to-one target that is already related elsewhere requires an explicit replacement confirmation and permission to remove the old edge as well as create the new one.
+- Tightening a type from many to one never deletes existing edges. Existing violations become **Needs attention**; new mutations cannot worsen them, and authorized owners can resolve a filtered set.
+- A directional type permits at most one live edge for the same type, source, and target. Adding it again is idempotent. Symmetric types treat `(A, B)` and `(B, A)` as the same pair.
+- Different Relationship types remain independent, and reversed directional edges may coexist. Cycle rules are explicit validation on types or workflows, not deduplication and not a universal ban.
+- Self-relationships are disabled by default and can be enabled as an advanced Relationship-type option.
+- Repeated anchored citations or mentions retain their own occurrences and history while Connections may summarize them as one Page-to-Page relationship.
+- A connection that needs several independent instances with dates, roles, or state becomes an intermediate Page with Properties rather than several indistinguishable parallel edges.
+
+## Permissions and authority
+
+- Editing a forward Relation Property requires **Can edit entries** in the Database owning that projection, access to the target Page, permission to use the Relationship type, and satisfaction of its constraints.
+- An explicitly editable inverse Relation Property grants the matching inverse-side editing route. An inverse shown only in Connections remains read-only from that side.
+- On an ordinary Page, **Can edit** permits outgoing directional Relationship changes through Connections. Incoming directional edges remain read-only unless the actor also has an authorized source-side or editable-inverse route.
+- A symmetric Relationship may be changed through an authorized edit route on either endpoint.
+- Seeing an endpoint or an incoming edge never grants authority to sever it. Owning a Relationship type does not grant access to every private edge that uses it.
+- Same-Organization cross-Workspace edges may be allowed by policy. Cross-Organization canonical edges are prohibited by default until federation can preserve both organizations' access, deletion, and governance guarantees.
+- Source-managed edges additionally obey the Source's **View only**, **Keep in sync**, or **Review before write-back** policy and provider capabilities. A local relationship pointing to a source-backed Page does not automatically become provider-owned.
+- Counts, rollups, graph degree, Queries, expressions, agents, inverse projections, exports, and graph traversal are computed only over edges and endpoints the viewer may access. Physical inverse indexes may improve performance but never become a second truth.
+
+## Bulk operations, deletion, and concurrency
+
+- Multi-cell selection, row bulk edit, paste/fill, and filtered selection may add Relationships. Delete/Backspace, **Clear relationships**, target removal, and filtered bulk editing remove the exact selected edges.
+- Bulk mutation preflights the complete selection. Ambiguous input or mixed permissions never produces a silent partial commit. Content identifies conflicts or locked items and lets the person narrow explicitly; an agent may narrow only when that remains faithful to the request and must report skipped scope.
+- A filtered bulk removal resolves exact edge IDs and activation states when the selection is made. New concurrent matches are not swept in later.
+- Removing a Relation Property preserves its Relationships by default. The destructive dialog offers **Remove Property** or **Remove Property and its N relationships**, with an access-scoped impact count, one attributable Revision, and Undo. **Manage relationships** opens a filterable collection before removal.
+- Removing an edge removes the activation state the operation observed. A genuinely concurrent authorized addition that the remover did not observe survives. A later removal made after observing that addition wins.
+- Re-adding a removed Relationship continues one stable lineage with another activation period. Concurrent duplicate additions converge on that same live lineage.
+- Successful single-value replacements serialize through committed-event order so only one target remains live; history and Undo preserve the displaced choices.
+- Trashing a Page suspends its active Relationships and restoring it restores them. Permanent deletion retains only inaccessible audit/history evidence.
+- Relationship definitions archive rather than cascading deletion across their edges.
+
+## Failure behavior
+
+- Constraint, permission, access, source-authority, and cardinality failures are typed failures, never successful empty results.
+- A bulk operation with ambiguous values, mixed authority, or an invalid cardinality change does not half-commit.
+- When a one-to-one move cannot remove the old edge, Content leaves both prior states unchanged and explains the required authority.
+- Broken, trashed, inaccessible, and permanently deleted endpoints remain distinguishable according to the viewer's authority without leaking private identity.
+- Ordinary concurrent convergence does not interrupt people with a conflict dialog. Intervention appears only when no valid authorized state can be committed.
+
+## Boundaries and non-goals
+
+- Relationships do not create a parallel graph datastore, permission model, Action surface, or task-dependency engine.
+- Relation Properties are projections, not the owners of the underlying knowledge.
+- Graph owns semantic graph layout and editing; Canvas owns intentional spatial arrangement and draft connectors; Queries own access-scoped traversal and result contracts.
+- Schedule constraints may interpret dependency Relationships, but this Capability does not calculate critical paths or repair dates.
+- Merely drawing a freeform Canvas line does not assert semantic truth.
+- A relationship never grants access to either endpoint.
+- Provider synchronization is proven separately for each adapter and cannot stand in for the generic Relationship contract.
+
+## Acceptance stories
+
+### Create once and edit from either direction
+
+Given two authorized Pages and a directional Relationship type with forward and inverse projections, when an editor creates the edge from the forward Relation Property and later removes it through the editable inverse projection, then Info, both Properties, Queries, Graph, and the shared Action surface show one canonical edge and one coherent history.
+
+### Preserve knowledge when a column disappears
+
+Given a Relation Property containing several Relationships, when a Database editor removes only the Property, then the Relationships remain visible in authorized Connections and Queries. When the editor instead chooses **Remove Property and its N relationships**, the exact authorized edges are removed in one reversible Revision and newer concurrent edges are preserved.
+
+### Enforce directional cardinality atomically
+
+Given a one-parent Relationship and a bulk paste containing several proposed parents for one Task, when the edit is submitted, then no subset commits and Content identifies the conflicting input. Given one valid replacement, the observed prior parent is replaced atomically and the inverse projection updates.
+
+### Keep authority attached to the route
+
+Given a person who may view both endpoints but may edit only the target Page, when they inspect an incoming directional edge in Connections, then they can see it but cannot remove it unless an editable inverse Property or other authorized route exists. Graph, Canvas, agents, and Rules return the same decision.
+
+### Converge without inventing history
+
+Given one client removes the edge it observed while another concurrently re-adds it, when both commits settle, then the unseen addition remains live, no duplicate appears, and Versions shows the actual removal and re-add. A subsequent informed removal makes the edge inactive.
+
+### Protect private neighborhoods
+
+Given an authorized Page related to an endpoint the viewer cannot access, when the viewer opens Connections, runs a Query, inspects Graph, calculates counts or rollups, or exports the Page, then the private endpoint and its existence do not leak. A known direct reference returns an honest access denial.
+
+## Current evidence
+
+Current code can model and display some relation values, which is useful donor substrate. Relation is not yet a generally user-creatable Property, and the current Notion path treats relations as unsupported. No evidence currently proves the shared type identity, universal Connections editor, bulk/deletion semantics, cardinality, access closure, source policy, or causal concurrency contract. This Capability therefore remains `approved_shape`.
+
+## Proof plan
+
+Proof requires deterministic Action and persistence tests plus real-interface workflows:
+
+1. Create local, governed, symmetric, directional, self-enabled, and source-backed Relationship types; rename and version them without changing stable identity.
+2. Create, edit, and remove the same edge through forward and inverse Properties, Connections, inline typed references, Graph, Canvas promotion, agents, Rules, and imports; verify identical permission and Event behavior.
+3. Exercise one-to-one, one-to-many, many-to-many, replacement, tightening, cycle validation, duplicate addition, and invalid-target cases.
+4. Exercise bulk add/remove, mixed permissions, filtered selection, property-only removal, destructive property-plus-edge removal, Undo, and new concurrent matches.
+5. Race add/add, add/remove, replacement/replacement, deletion/restoration, and definition updates; verify one valid live state and complete causal history.
+6. Re-run cells, Connections, backlinks, Queries, traversal, Graph, counts, rollups, aggregates, exports, public output, and agent reads under changing access; verify access is applied before computation.
+7. Verify keyboard and assistive-technology paths for relation pickers, Connections, impact dialogs, bulk selection, and repair states.
+
+## Open questions
+
+The core product behavior above is settled. Implementation may still choose storage layout, index strategy, causal metadata representation, and exact control placement provided those choices satisfy this contract. Federation must be separately designed before enabling canonical cross-Organization Relationships.