@agent-native/core 0.130.2 → 0.131.3

package/corpus/templates/content/docs/product/capabilities/content.view.map.md

@@ -0,0 +1,77 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.map"
+name: "Map View"
+user_promise: "Map renders typed locations with points, clustering, filtering, and record previews before adding richer geographic layers."
+primary_user_job: "See authorized records in their meaningful places and open the underlying record without making map coordinates a second source of truth."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.property.location", "content.view.renderer-conformance"]
+related_features: []
+roadmap_boundary: "supporting"
+acceptance_summary: "Map projects access-scoped canonical results with typed locations, filters, clustering, previews, and shared record actions."
+proof_requirements:
+  [
+    "Typed location selection, invalid or absent location, viewport, filter, and cluster behavior",
+    "Access-safe markers, counts, previews, search, export, and shared Action editing",
+    "Real-interface keyboard, assistive alternative, provider-unavailable, and reload workflows",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Map View
+
+## Why this exists
+
+Place can be the clearest way to find work, provided a pin remains a projection of a
+typed location on a canonical record.
+
+## Example workflow
+
+A coordinator filters locations to an authorized region, selects a cluster, previews a
+record, and opens it. Changing the record's location uses the ordinary shared Action;
+the pin updates after the canonical change.
+
+## Product contract
+
+- Map consumes a canonical Database or Query result and a declared typed location field.
+- Markers, clusters, viewport filters, previews, and counts are access-scoped.
+- Selecting a pin opens or edits the canonical record through shared View Actions.
+- Missing, invalid, stale, and provider-unavailable locations report honestly.
+
+## Boundaries and non-goals
+
+`content.property.location` owns location meaning. Map is not geocoding custody, route
+planning, a geographic layer editor, or a second record store.
+
+## Acceptance stories
+
+### Explore only authorized places
+
+Given a result containing private locations, when a viewer opens Map, then no marker,
+cluster count, preview, or viewport query exposes those records.
+
+### Edit a location through its record
+
+Given an authorized marker, when an editor changes its typed location, then the shared
+Action updates one canonical record and the Map refreshes without duplicate state.
+
+## Current evidence
+
+No current implementation evidence proves Map's location, access, interaction, and
+recovery contract. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test typed locations, invalid values, filters, clusters, and canonical preview/open.
+2. Verify access closure through markers, counts, viewport changes, exports, and agents.
+3. Exercise keyboard alternatives, source/provider failure, reload, and dense geographic results.
+
+## Open questions
+
+The first provider boundary and offline geographic behavior remain implementation questions.

package/corpus/templates/content/docs/product/capabilities/content.view.personal-state.md

@@ -0,0 +1,99 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.personal-state"
+name: "Personal View state"
+user_promise: "A shared View remembers one private arrangement per person and supports named Only-me Views without copying records."
+primary_user_job: "Explore and remember a useful personal arrangement without changing the dependable View everyone else shares."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.view.query", "content.share.views"]
+related_features: ["content.feature.make-the-workspace-yours"]
+roadmap_boundary: "feature"
+acceptance_summary: "Each shared View remembers one unnamed personal arrangement per user, supports any number of named Only-me Views, exposes effective state to agents, and never publishes personal exploration accidentally."
+proof_requirements:
+  [
+    "One automatically persisted personal arrangement per user and shared View",
+    "Reset, Save as new View, and permissioned Update shared View behavior",
+    "Focused View Instance containing shared, personal, effective, and delta state for UI and agents",
+    "Access isolation, link behavior, persistence, multi-device recovery, and no record copying",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Personal View state
+
+## Why this exists
+
+Shared Views need dependable defaults, but people also need to sort, filter, group, resize, and collapse data while they work. Requiring a save decision after every exploration creates meta-work; publishing every experiment creates chaos.
+
+## Example workflow
+
+An editor opens the team's shared Content Calendar, filters to their own recent articles, resizes columns, and groups by status. Content quietly remembers that arrangement and shows **Viewing with personal changes**. The editor can reset, save it as a named **Only me** View, or deliberately update the shared View if they have permission.
+
+## Product contract
+
+- Every shared saved View may remember at most one unnamed personal arrangement for each user.
+- The arrangement automatically persists filters, sorting, grouping, column order/size, collapsed sections, and other supported presentation state without a recurring **Save for me** action.
+- When personal state differs, the interface quietly shows **Viewing with personal changes**.
+- **Reset to shared View** removes the remembered override.
+- **Save as new View** creates a stable named View over the same owner input with visibility **Only me** or an allowed shared destination. A person may create many named private Views.
+- **Update shared View** deliberately replaces the shared default only with the required Database/Query authority and records an ordinary reversible Revision.
+- The focused View Instance contains the shared definition, remembered personal override, effective state, and delta between them.
+- Agents receive that effective focused state so they understand what the person sees. They may run arbitrary ephemeral Queries behind the scenes without changing the visible arrangement.
+- An agent changes the personal arrangement only when asked to show a result, saves a named View only when asked, and updates the shared default only through the explicit permitted action.
+- Ordinary copied View links resolve to the saved View definition, never the sender's unnamed personal arrangement.
+- Personal state changes presentation and safe creation seeds only. It never copies records, changes source truth, grants access, or creates a private fork of the Database/Query.
+
+## Permissions and failure behavior
+
+- Personal arrangements and Only-me Views are visible only to their owner and system processes acting within that person's authority.
+- Saving a shared destination or updating a shared View requires the normal owner permissions; personal state cannot bypass them.
+- Effective results still intersect all View, input, row, field, Source, and viewer access.
+- If personal configuration temporarily references an unavailable field, Content preserves it in a degraded state when the absence may be temporary. Intentional field deletion follows the atomic cleanup contract.
+- Persistence failure leaves the shared View unchanged and reports that the personal arrangement was not remembered; it must not silently publish the state instead.
+
+## Boundaries and non-goals
+
+- This Capability owns personal presentation state, not Query semantics or Database values.
+- It does not make copied links carry hidden sender state.
+- It does not restrict a person to one named private View; the one-item limit applies only to the automatic unnamed arrangement per shared View.
+- Ephemeral agent exploration is not a saved View and does not mutate UI unless requested.
+
+## Acceptance stories
+
+### Remember without publishing
+
+Given two people open the same shared View, when one changes filters, grouping, and column sizing, then only that person's effective arrangement changes and persists across reload while the other person and shared definition remain unchanged.
+
+### Save several private alternatives
+
+Given one personal arrangement, when its owner chooses **Save as new View** twice with **Only me**, then two stable private Views exist over the same canonical records while the shared View still retains only one unnamed override for that person.
+
+### Keep links predictable
+
+Given a person copies the URL while viewing personal changes, when another authorized viewer opens it, then they receive the saved View definition plus their own personal state, never the sender's override.
+
+### Give agents the real focused surface
+
+Given a focused View with temporary personal filters, when an agent is asked about what is visible, then it receives shared, personal, effective, and delta state and may query further without publishing or changing the arrangement unless asked.
+
+## Current evidence
+
+Existing View controls and application-state patterns are useful substrate, but the complete unnamed persistence model, named Only-me Views, delta indication, scoped save/update actions, multi-device behavior, and agent-effective context are not proven. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Persist and reset each supported personal filter, sort, group, layout, sizing, and collapsed-state override across reload and devices.
+2. Create several Only-me Views, attempt shared saves with and without authority, and verify one reversible shared Revision.
+3. Copy links under personal changes and verify predictable recipient behavior.
+4. Inspect application state and agent actions for shared/personal/effective/delta parity and non-mutating exploration.
+5. Exercise schema deletion, temporary unavailability, access revocation, persistence failure, Undo, accessibility, and recovery.
+
+## Open questions
+
+Exact cross-device conflict resolution for simultaneous personal arrangements and the retention policy for long-unused unnamed overrides remain open implementation/product details.

package/corpus/templates/content/docs/product/capabilities/content.view.pivot.md

@@ -0,0 +1,76 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.pivot"
+name: "Pivot View"
+user_promise: "Pivot places dimensions on rows and columns, typed aggregations in cells, and drills back to canonical records."
+primary_user_job: "Compare an authorized measure across two meaningful dimensions and inspect the records behind any result."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.view.grouping-aggregation"]
+related_features: ["content.feature.understand-what-your-data-says"]
+roadmap_boundary: "feature"
+acceptance_summary: "Pivot configures typed row and column dimensions with access-safe measures, totals, and drill-in to canonical contributing records."
+proof_requirements:
+  [
+    "Typed dimensions, measure selection, totals, nulls, ordering, and configuration persistence",
+    "Access-safe cells, totals, drill-in, export, agent context, and empty or unavailable input tests",
+    "Real-interface keyboard table navigation, responsive overflow, reload, and dense-data workflow",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Pivot View
+
+## Why this exists
+
+One flat group can answer “how much?”; a pivot makes the crossing of two questions
+legible without detaching its cells from the records that made them.
+
+## Example workflow
+
+A lead puts project on rows, status on columns, and estimate sum in cells. Selecting a
+cell opens its authorized contributing records rather than a copied spreadsheet range.
+
+## Product contract
+
+- Pivot is a saved View configuration over canonical, access-scoped Query results.
+- Row and column dimensions and typed measures use grouping and aggregation semantics.
+- Cells, totals, labels, drill-in, export, and agent context reveal only authorized input.
+- Configuration persists independently of the canonical records and reports unavailable data honestly.
+
+## Boundaries and non-goals
+
+Grouping and aggregation own measure semantics. Pivot is not a formula grid, a writable
+cell store, or a replacement for Chart.
+
+## Acceptance stories
+
+### Compare two dimensions
+
+Given an authorized task result, when a viewer pivots project by status, then each cell
+and total reflects only eligible records and preserves the selected typed measure.
+
+### Inspect a cell
+
+Given a visible cell, when the viewer drills in, then the resulting collection contains
+only its authorized contributors and maintains canonical record identity.
+
+## Current evidence
+
+The grouping dependency establishes intended substrate; no repository evidence proves a
+complete Pivot renderer. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test dimensions, measures, totals, nulls, ordering, persistence, and drill-in.
+2. Verify disclosure closure across cells, totals, exports, and agents.
+3. Exercise responsive table navigation, dense data, reload, and unavailable sources.
+
+## Open questions
+
+The initial dimension-depth limit and display policy for sparse matrices need design.

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

@@ -0,0 +1,106 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.query"
+name: "Database and Query Views"
+user_promise: "A View is one stable presentation over exactly one Database or Query, with its own downstream filters, layout, and renderer"
+primary_user_job: "Present and refine one collection for a particular workflow without changing the collection's identity or upstream meaning."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.query.object", "content.property.typed"]
+related_features:
+  [
+    "content.feature.make-the-workspace-yours",
+    "content.feature.see-your-information-your-way",
+    "content.feature.understand-what-your-data-says",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Named Views retain stable identity and presentation over one owner input, bind configuration to stable fields, refine but never widen that input, and remain reusable without becoming collections or granting access."
+proof_requirements:
+  [
+    "Stable View identity, one owning Database/Query, default selection, links, embeds, templates, deletion, and copying",
+    "Renderer, visible fields, filters, sorts, groups, formatting, layout, and creation-seed ownership",
+    "Stable field bindings plus atomic cleanup or truthful degraded state during schema evolution",
+    "Access narrowing, shared Action parity, personal/effective state, accessibility, persistence, and recovery",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Database and Query Views
+
+## Why this exists
+
+The same collection can support very different work: quick List capture, a grouped Board, a Calendar, or an analytical Chart. People need to save those presentations without duplicating records, hiding a second collection beneath the screen, or confusing a temporary filter with the Query's meaning.
+
+## Example workflow
+
+A Projects Database has a shared Board grouped by Status and a private List showing only the current person's recent projects. Both are stable Views over the same Database. Changing the List filter does not change the Database or Board, and changing a project so it no longer matches simply moves it out of the List while preserving the record.
+
+## Product contract
+
+- A named View has stable identity and an addressable URL while belonging to exactly one Database or Query.
+- A Database or Query selects one default View. A link, embed, template, sidebar pin, or agent may address another named View directly.
+- The View owns renderer, visible fields, downstream filters, sorting, grouping, layout, formatting, collapsed state, and safe creation seeds.
+- Query filters define the upstream result contract. View filters refine what this presentation shows and can never widen past that input.
+- An ordinary View directly over a Database uses its implicit base Query; no hidden named Query is created.
+- **Save as new View** creates another View over the same owner. **Save as Query** appears on Query-building surfaces, not as ordinary View promotion.
+- **Create Query from this View** may prefill a builder with owner, filters, fields, and sorting, but the person confirms sources, output schema, variables, and write behavior before saving a separate Query.
+- A View binds to stable Property and Query-output IDs. Local aliases and formatting remain View-owned; matching display names never create semantic equivalence.
+- An embedding occurrence may select a named View and apply occurrence-local presentation overrides without mutating the saved View.
+- Deleting a View deletes only its configuration. Copying a View to another input creates a new View and explicitly maps compatible stable fields; a View never silently retargets itself.
+
+## Schema evolution and access
+
+- Renaming a bound field preserves the View automatically.
+- Before intentional deletion or incompatible type change, Content gives one compact impact summary. Confirmation applies the schema change and dependent cleanup as one attributable Revision.
+- Intentional deletion removes only affected filter leaves, sorts, groups, columns, seeds, or renderer bindings; unaffected configuration remains. Nested groups simplify and empty groups disappear.
+- Temporary source unavailability, permission loss, or stale provider schema is not deletion. The View preserves configuration and shows a typed degraded or Unavailable state rather than widening itself.
+- A View may be shared or **Only me** and may narrow access below its owner, never widen it. Effective visibility intersects View, Database/Query, Source, row, field, and viewer access.
+- Restricting a View protects the saved surface; it does not revoke access someone independently has to the underlying records elsewhere.
+- Private View cleanup and impact counts never expose private configuration to a schema editor.
+
+## Boundaries and non-goals
+
+- A View does not own records, source schemas, canonical values, Query variables, or provider write authority.
+- View filters control visibility, not validity. Database validation alone decides whether a mutation may commit.
+- A View never grants row access or runs with its creator's authority.
+- Sidebar is a navigation projection that may render a View; it is not a general View renderer owned here.
+- Renderer-specific behavior belongs to each View-family Capability and the shared conformance contract.
+
+## Acceptance stories
+
+### Preserve upstream meaning
+
+Given a Query that admits only published records and two Views with different downstream filters, when one View filter is removed, then it may reveal only other published Query results and never records excluded upstream.
+
+### Survive schema change coherently
+
+Given a View whose nested filter, grouping, and displayed column use one Property, when an authorized editor deletes that Property after one impact confirmation, then only the affected configuration is removed in the same Revision, unaffected settings remain, and Undo restores both schema and View.
+
+### Narrow without granting access
+
+Given an Only-me View over a shared Database and a shared link to another View, when readers open either, then each receives only the intersection they may already access and no View reveals private counts or records.
+
+### Delete presentation without deleting data
+
+Given a named View linked and embedded in several places, when it is deleted, then its configuration and references enter the normal broken/recovery state while the owner Database/Query and canonical records remain unchanged.
+
+## Current evidence
+
+Content already has useful saved Database Views, filters, sorting, grouping, and several renderers. The complete stable View identity, Database-or-Query ownership, private/shared alternatives, typed field bindings, schema-evolution cleanup, occurrence overrides, and renderer-conformance contract are not yet proven end to end. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Create, link, embed, pin, copy, delete, restore, and select default named Views over both Databases and Queries.
+2. Exercise every shared renderer setting, downstream filter, sort, group, layout, formatting, and occurrence override through UI and Actions.
+3. Rename, delete, restore, and change types of local, custom, source, and Query-output fields; verify atomic cleanup versus degraded preservation.
+4. Run shared, Only-me, and occurrence-local Views under changing record/field/source access; verify no widening or derived leaks.
+5. Verify personal overrides, agent context, creation seeds, reload, concurrent shared edits, accessibility, export, and recovery.
+
+## Open questions
+
+The stable ID `content.view.query` sounds Query-specific even though the accepted concept is a general View over a Database or Query. Preserve the ID until a deliberate normalization provides a replacement. Exact ownership of named-View identity across this record, Shared Views, and Personal View State should remain this record for the generic primitive, with the others adding their focused policy.

package/corpus/templates/content/docs/product/capabilities/content.view.renderer-conformance.md

@@ -0,0 +1,77 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.renderer-conformance"
+name: "View renderer conformance"
+user_promise: "Every View obeys the same permissions, Actions, agent context, accessibility, persistence, performance, and recovery contract."
+primary_user_job: "Move between Views confidently because changing the renderer never changes what I may know, do, recover, or ask an agent to do."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.renderer.typed", "content.view.query"]
+related_features: ["content.feature.see-your-information-your-way"]
+roadmap_boundary: "feature"
+acceptance_summary: "Every renderer consumes canonical access-scoped results and implements shared Actions, agent context, accessible interaction, persisted configuration, bounded performance, and truthful recovery."
+proof_requirements:
+  [
+    "Reusable conformance suite for result, permission, Action, and agent-context parity",
+    "Keyboard and assistive-technology, persistence, reload, failure, stale, and recovery fixtures",
+    "Representative renderer real-interface and performance-budget workflows",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# View renderer conformance
+
+## Why this exists
+
+Changing how a collection looks must not quietly change its authority. A renderer is a
+projection, not a new application hiding behind a pretty icon.
+
+## Example workflow
+
+An editor switches the same Database from Table to Timeline, asks the agent about the
+focused result, then reloads. Both surfaces use the same authorized records and Actions;
+each preserves only its own presentation settings.
+
+## Product contract
+
+- Every View renders its canonical Database or Query result after access evaluation.
+- Renderers use one typed Action and agent-context contract; UI affordances never widen authority.
+- Configuration, focused selection, empty, stale, unavailable, denied, and recovery states are explicit.
+- Keyboard and assistive-technology access, bounded loading, and persistence are conformance requirements.
+
+## Boundaries and non-goals
+
+Typed renderers and Queries supply common substrate. This does not force identical
+layouts, make every renderer writable, or replace renderer-specific product contracts.
+
+## Acceptance stories
+
+### Keep authority while changing renderer
+
+Given a viewer with partial row and field access, when they switch Views, then results,
+counts, previews, Actions, exports, and agent context disclose no additional information.
+
+### Recover consistently
+
+Given an unavailable query or a failed mutation, when any conforming View renders it,
+then it reports the state and retry or recovery route without presenting empty success.
+
+## Current evidence
+
+Timeline and existing Database renderers provide useful donor paths, but they do not
+prove a cross-renderer suite or complete contract. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Create reusable fixtures for permissions, results, Actions, agent context, and state transitions.
+2. Run keyboard, assistive technology, persistence, recovery, and reload checks per renderer.
+3. Measure representative large-result workflows and test unavailable or stale inputs.
+
+## Open questions
+
+The first enforceable conformance-harness API and performance budgets need implementation design.

package/corpus/templates/content/docs/product/capabilities/content.view.scale.md

@@ -0,0 +1,77 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.scale"
+name: "Large Database performance"
+user_promise: "Databases stay responsive and incrementally queryable well beyond a few hundred rows"
+primary_user_job: "Find, change, and navigate a large authorized collection without waiting for every row to arrive or trusting an incomplete result as final."
+kind: "surface"
+state: "failing"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.view.query"]
+related_features: ["content.feature.see-your-information-your-way"]
+roadmap_boundary: "feature"
+acceptance_summary: "Views use server-side typed queries, bounded windows and aggregates, indexes, explicit partial states, and measured interaction budgets for large authorized collections."
+proof_requirements:
+  [
+    "Server-side filter, sort, pagination/window, index, cursor, and bounded-aggregate coverage",
+    "Partial-result, mutation, refresh, access-change, and unavailable-source correctness tests",
+    "Real-interface performance traces for representative large collections and renderer interactions",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Large Database performance
+
+## Why this exists
+
+A View that feels quick only while its collection is small has not yet earned the word
+View. Scale must preserve both responsiveness and truthful result boundaries.
+
+## Example workflow
+
+An editor filters a large Database, scrolls to another window, edits a visible record,
+and refreshes after another editor changes the result. The interface identifies partial
+loading and does not count unseen rows as if it had completed the query.
+
+## Product contract
+
+- Filtering, sorting, access evaluation, pagination, and aggregates execute against bounded typed results.
+- Windows, cursors, counts, totals, and loading state state whether results are complete, partial, stale, or unavailable.
+- Mutations reconcile with canonical results and do not silently retain a record that no longer matches.
+- Performance work preserves renderer conformance, accessible navigation, and Action parity.
+
+## Boundaries and non-goals
+
+Query execution owns collection semantics. This Capability is not a client-side cache
+excuse, a permission shortcut, or a promise of unbounded instant export.
+
+## Acceptance stories
+
+### Navigate a partial result honestly
+
+Given a large authorized result, when a viewer opens and scrolls it, then they can
+navigate incremental windows and distinguish loaded rows and totals from incomplete work.
+
+### Reconcile a changing collection
+
+Given a visible record changed to no longer match a filter, when the Action succeeds,
+then the View removes or repositions it truthfully without stale duplicate rows.
+
+## Current evidence
+
+The prior record is `failing`; existing View code does not constitute measured server-side
+query, budget, or real-interface proof. It remains `failing`.
+
+## Proof plan
+
+1. Benchmark indexed filters, sorts, cursors, windows, and bounded aggregates at representative sizes.
+2. Test partial, stale, access-changing, unavailable, and mutation-reconciliation states.
+3. Capture real UI traces for initial load, navigation, edit, refresh, and accessible keyboard use.
+
+## Open questions
+
+Target data sizes and interaction budgets need an agreed workload before a verified claim.