@aotter/mantle 0.1.0-alpha.1 → 0.1.0-alpha.11

package/docs/adr/0001-four-atom-manifest-model.md

@@ -1,12 +1,20 @@
 # ADR-0001: 4-atom YAML manifest model under `cms.mantle.aotter.net/v1`
 
-**Status:** Carried over from POC v0.0.x; refreshed and folded for v0.1.0 (incorporates POC ADRs 0005 + 0006).
+**Status:** Accepted for the four-atom grammar and multi-document YAML;
+the fixed `site.yaml` file contract is superseded by ADR-0019.
 
-**Date**: 2026-04-30 (POC origin), refreshed 2026-05-03 for v0.1.0 rebuild
+**Date**: 2026-04-30 (POC origin); last amended 2026-08-16
 
 **Deciders**: phsu
 
-**Related**: ADR-0002 (closed enums for bindings)
+**Related**: ADR-0002 (closed enums for bindings),
+[ADR-0019](0019-sealed-manifest-runtime-pipeline.md) (caller-owned source boundary)
+
+> **2026-08-16 amendment:** the four atoms and multi-document YAML remain
+> normative. Core no longer assigns source file names: its parser accepts
+> caller-owned source IDs, and its CLI reads immediate `.yaml` / `.yml` files
+> in lexicographic order. `manifests/site.yaml` remains only a starter
+> convention. Fixed-file statements below are retained as decision history.
 
 ---
 
@@ -78,14 +86,14 @@ the `cms.mantle.aotter.net/v1` API group:
 | `Schema` | `CREATE TABLE` | no | no |
 | `View` | `CREATE VIEW` | yes (auto-mounted at `GET /api/views/<name>`; see ADR-0012) | no |
 | `Procedure` | `CREATE FUNCTION ... LANGUAGE plpgsql` | **no** (transport-agnostic; needs a Trigger to bind) | **yes — handler ref to consumer's TS** |
-| `Trigger` | `CREATE TRIGGER` + `pg_cron` + PostgREST route + `LISTEN/NOTIFY` | yes (the binding atom) | no |
+| `Trigger` | `CREATE TRIGGER` + route/tool binding | yes (the binding atom) | no |
 
 ### Path A: Trigger does all binding
 
 A Procedure is **not externally exposed by itself**. To make it
-callable over HTTP / MCP / cron / lifecycle / queue, declare a
+callable over HTTP / MCP / lifecycle, declare a
 `Trigger` whose `target.procedure` points at it. The same
-Procedure can be bound by multiple Triggers (HTTP + cron + MCP,
+Procedure can be bound by multiple Triggers (HTTP + MCP,
 all sharing one handler).
 
 This is "Path A" relative to an alternative considered (and
@@ -135,9 +143,6 @@ existing atoms cannot express it.
   by multi-doc YAML grouping (see § Authoring shape below).
 - "Procedure is not directly exposed" is a teaching point; new
   authors initially try to call a Procedure URL and get 404.
-  Mitigated by the dispatcher emitting a hint in the 404 if a
-  Procedure exists with no Trigger binding (DRAFT — not yet
-  spec'd as a code).
 - The PG-1:1 pitch breaks down once authors look at the actual
   storage layer (D1 today). The mapping is conceptual; the
   runtime is SQLite + JSON.
@@ -150,12 +155,9 @@ existing atoms cannot express it.
   multi-doc YAML keeping atoms separate while the file count
   stays low; reviewers should push back when a single Procedure's
   handler becomes a workflow engine.
-- **Trigger.source.kind expansion pressure.** v0.1 only ships
-  `http`. As MCP / cron / lifecycle / queue source kinds land
-  (DRAFT — see § Future grammar discipline below), the same
-  atom has to accommodate radically different invocation shapes.
-  The contract holds (one binding atom, many source kinds) but
-  each new kind is a design pass.
+- **Trigger.source.kind expansion pressure.** v0.1 ships `http`, `mcp`,
+  and `lifecycle`. Each new source kind requires a complete grammar and
+  runtime design pass.
 - **The PG-1:1 pitch may become a constraint.** If a future
   capability has no PG analogue, framing pressure will push to
   shoehorn it into the table or to break the pitch. Either is
@@ -178,8 +180,8 @@ Rejected: under R7's reframing, the right axis is contract /
 implementation × state / event, not "PG attachment." Schema
 holds state; Procedure holds operations against state; folding
 them conflates "what data exists" with "what can happen to data."
-Also the LOC win that motivated the fold (92→58 via default-CRUD)
-was recovered without folding — captured in the DRAFT
+Also the LOC win that motivated the fold (92→58 via default CRUD)
+was recovered without folding through the shipped
 `handler.kind: builtin` shortcut.
 
 **(d) 4 kinds with `Procedure` retaining inline
@@ -217,251 +219,12 @@ executor, and Procedure dispatcher live in this repository.
 
 ---
 
-## Future grammar discipline (was POC ADR-0005)
-
-> Folded in 2026-05-03 from POC ADR-0005 ("v0.1 minimum essential
-> grammar; rich grammar reserved as DRAFT"). The discipline below
-> applies to every key inside every atom defined above.
-
-### Context
-
-The 4-atom design experiment (same 6 rounds + R6.5 + R7 cited
-above) produced a rich inner grammar:
-
-- 18 grammar keys across the 4 atoms
-- 7 meta-rules (DRY across `requires` siblings; one-site
-  placeholder evaluation; SDK helper doctrine; closed
-  `x-mantle-bind` enum; list-shape for cross-resource refs;
-  singleton-fallback exception; ctx.system origin invariant)
-- 2 closed enums (`x-mantle-bind`, `ctx.*` predicate identity)
-- 2 placeholder namespaces (`:ctx.*` identity bindings, `$.*`
-  data-flow bindings)
-- ~36 cognitive surface units (consumer-cc count)
-
-The pressure-tested grammar covered features as ambitious as
-`Trigger.target.project` (declarative cross-Schema aggregate
-projection in same-tx), `Schema.spec.policies.{visible,
-readable, writable}` (PG-RLS-style row/field policy),
-`View.recursive` (declarative recursive CTEs),
-`requires.window/quota/owns/contains` (temporal predicates,
-rate caps, row ownership, array containment), and
-`handler.kind: builtin` (default-CRUD shortcut).
-
-Shipping all of that in v0.1 would mean roughly 5–10× the
-dispatcher / validator / type-system surface v0.1 actually
-needs, plus an OpenAPI emission story for keys (recursive CTEs,
-RLS) that have no clean OpenAPI mapping.
-
-The user principle, articulated 2026-04-30 EOD:
-
-> 本次 iteration 只匡出四個 yml 最 minimum essential 的 grammar，
-> 四個都蓋出來且能動，之後當應用場景擴充真的有需要再往上蓋。
-
-(Translation: this iteration only ships the absolute minimum
-grammar to make the 4 atoms work end-to-end; each extension
-arrives when a real application use case demands it.)
-
-This is YAGNI applied to grammar surface, motivated by:
-
-- The runtime cost above.
-- The risk that speculative grammar locks the wrong shape —
-  features designed in the abstract often look different once a
-  real use case applies pressure (R3-R5 of the design experiment
-  showed multiple grammar shapes proposed and revised as
-  features unfolded).
-- The maintenance cost of keys nobody uses but everybody must
-  understand.
-
-### Decision
+## Grammar changes
 
-The v0.1 ship targets **minimum essential grammar only**. Rich
-grammar from the design experiment is preserved as DRAFT in the
-manifest grammar reference; it lands when a concrete use case
-forces it.
-
-#### v0.1 grammar lock per atom
-
-**Schema (v0.1)**:
-- `spec.schema:` (JSON Schema 2020-12 body)
-- `spec.uniqueIndexes:` (composite uniques)
-- `spec.indexes:` (ordered composite, non-unique access paths)
-- Property extensions: `x-mantle-bind`, `x-mantle-ref`, `x-mcp-hint`
-
-**View (v0.1)**:
-- `spec.from:` (source Schema)
-- `spec.fields:` (projected fields)
-- `spec.filter:` AST — `eq`, `gt`, `gte`, `lt`, `lte`, `and`, `or`
-- `spec.orderBy:`
-- `spec.limit:`
-- `spec.params:` (required query params referenced by filter values)
-- `spec.requires.{auth, guard}:` (same authorization contract as Procedure)
-
-**Procedure (v0.1)**:
-- `spec.requires.auth.all:` (closed predicate vocabulary)
-- `spec.requires.guard.procedure:` (one consumer-owned dynamic guard)
-- `spec.input:` (JSON Schema 2020-12)
-- `spec.output:` (JSON Schema 2020-12)
-- `spec.handler.{kind: ref, ref: <opaque-key>}` — author-supplied
-  handler function
-- `spec.handler.{kind: builtin, op: <create | update | upsert |
-  delete>, schema: <Schema name>}` — SDK-supplied CRUD shortcut
-  (promoted to v0.1.0; runtime implemented by `InvokeBuiltinUseCase`)
-
-**Trigger (v0.1)**:
-- `spec.source.kind: http` — public HTTP endpoint
-- `spec.source.{method, path}` (when `kind: http`)
-- `spec.source.kind: lifecycle` — entry-writer hook (promoted to
-  v0.1.0; runtime implemented by `LifecycleHookingEntryRepository`)
-- `spec.source.{schema, on, errorPolicy}` (when `kind: lifecycle`)
-- `spec.source.kind: mcp` plus `surface: public | staff` — MCP tool
-  exposure for a declared Procedure
-- `spec.target.procedure:`
-
-#### v0.1 closed enums
-
-- `x-mantle-bind: {ctx.user, ctx.staff, now}`
-- `ctx.*` predicate vocabulary: `{user, staff, auth, auth.scope}` (no
-  `system` until a use case forces it)
-- `Trigger.source.kind: {http, lifecycle, mcp}`
-- `Procedure.handler.kind: {ref, builtin}`
-- `BuiltinOp: {create, update, upsert, delete}`
-- `LifecycleHook: {before_create, after_create, before_update,
-  after_update, before_delete, after_delete, before_publish,
-  after_publish}`
-
-#### What's DRAFT (do not implement, do not type)
-
-- Schema: `policies.{visible, readable, writable, owner}`,
-  `x-mantle-ref` auto-lift to virtual column,
-  computed columns via projection Trigger
-- View: `recursive`, `gatedBy`, `join`, `policies.skip`,
-  filter AST extensions (`contains`, `not`, `in`, `like`)
-- Procedure: `requires.auth.{any | all}` with disjunction;
-  `owns:`, `contains:`, `withinMinutes:`, `requires.window`,
-  `requires.quota`, `errors`, `retry`
-- Trigger: `source.kind: {cron, queue}`,
-  `target.project`, `atomicity`
-  (`source.kind: mcp` was promoted in alpha.16 — #281)
-- Cross-cutting: `ctx.system`, `$.*` placeholder namespace,
-  `staffBypass:`
-
-#### Discipline
-
-- The v0.1 validator **rejects DRAFT keys at parse time** with a
-  `DRAFT_KEY_USED` warning (not error — see the
-  AI-as-primary-author contract on permissive bias). The
-  diagnostic explicitly references the future-grammar reference
-  so authors know the key is reserved, not
-  unsupported-and-forgotten.
-- Each DRAFT key has a documented **landing condition** (the
-  use case that surfaces it). Promoting a key to v0.1+ requires
-  showing that condition has been met — not just "it would be
-  nice to have."
-- Each promotion goes through a 3-agent design review
-  (yml-editor proposes / code-impler tests buildability /
-  fresh-dev verifies clarity) before locking.
-- The v0.1 floor is the floor, not the ceiling. The atom set
-  (4) is locked; the grammar inside each atom is permitted to
-  grow.
-
-### Consequences
-
-#### Pros
-
-- v0.1 dispatcher / validator / types are tractable in a small
-  number of weeks, not many months.
-- Author cognitive surface is small: 4 atoms × ~5 keys each ≈
-  20 things to learn, instead of 18 keys with ~36 cognitive
-  surface units.
-- DRAFT keys document where the spec is **going**, so authors
-  with future requirements can tell whether the project is on
-  trajectory or not — without those features being prematurely
-  committed.
-- Each DRAFT promotion gets a real use case attached, so the
-  grammar evolves under empirical pressure rather than
-  speculation. This was the design experiment's strongest
-  signal: features like `View.recursive` and
-  `Trigger.target.project` looked very different once a real
-  feature (threaded comments, cross-Schema invariants) applied
-  pressure.
-
-#### Costs
-
-- Authors with ambitions beyond v0.1 (private posts, role-gated
-  reads, rate limits, recursive views) must wait or write
-  handler-side TS. For some projects this is enough to shop
-  elsewhere; that's acceptable for an OSS v0.1.
-- DRAFT documentation is itself a maintenance burden — the
-  reference has to stay coherent as the spec evolves; stale
-  DRAFT entries (features no longer planned) need pruning.
-- The "warning, not error, on DRAFT keys" rule means an author
-  who copies a DRAFT example into a manifest doesn't fail —
-  they get a warning. This requires the validator to know the
-  full DRAFT vocabulary, not just the v0.1 vocabulary.
-
-#### Risks
-
-- **Grammar surface grows ad-hoc.** Each DRAFT promotion looks
-  reasonable; together they reproduce the over-grammar v0.1
-  was avoiding. Mitigation: 3-agent review per promotion;
-  promotions land in batches with documented use cases, not
-  one-by-one.
-- **DRAFT becomes vaporware.** Some DRAFT features are listed
-  but never land because their use case never surfaces.
-  Mitigation: this is fine — the appendix is documenting
-  shapes, not commitments. If a DRAFT entry stays cold for >12
-  months, prune it from the appendix and let the future
-  proposer re-derive it.
-- **Authors hit walls and route around the SDK.** "I need
-  `View.recursive` so I'll just write raw SQL in a Procedure
-  handler" — over time this drifts the actual extension shape
-  away from what the SDK eventually builds. Mitigation: when
-  ad-hoc handler patterns repeat, that's the use case that
-  promotes the DRAFT key. Watch handler implementations for
-  recurring patterns.
-
-### Alternatives considered
-
-**(a) Ship the full experiment grammar in v0.1**.
-Rejected: 5–10× the dispatcher work; locks shapes in the
-abstract before real use cases apply pressure; author surface
-explodes.
-
-**(b) Don't document DRAFT at all; ship v0.1 spec only**.
-Rejected: authors with future requirements have no way to
-evaluate trajectory; the design experiment's results would be
-lost institutionally; future proposals would re-litigate solved
-questions. The DRAFT reference is a forward-looking invariant.
-
-**(c) Ship a subset of DRAFT in v0.1 (e.g. `policies.visible`
-and `requires.auth.any`)**.
-Rejected: any line we draw between v0.1 and DRAFT has the same
-litigation problem. The principled cut is "minimum essential to
-make 4 atoms work end-to-end"; anything richer needs a specific
-motivation. None of the DRAFT features had that motivation in
-the v0.1 ship list.
-
-**(d) Promote DRAFT keys lazily — implement at runtime when
-authors ask, no spec lock**.
-Rejected: spec coherence demands keys are spec'd before they
-ship. Authors writing against runtime-only features get
-silently broken on SDK upgrades.
-
-### How to apply
-
-- Authoring v0.1 manifests: stick to the v0.1 vocabulary above.
-  If something seems missing, check the DRAFT reference; if it's
-  there and you have a concrete use case, file an issue
-  describing the use case.
-- SDK code: implement only v0.1 keys in the dispatcher /
-  validator / types. DRAFT keys are documented but not handled.
-- DRAFT promotion: needs a documented use case + 3-agent design
-  review + ADR landing the promotion (with cross-link to the
-  use case).
-- Pruning DRAFT: if an entry has stayed cold for 12+ months,
-  propose removal in a small ADR. Removal is reversible (the
-  shape is in the experiment transcripts and prior ADR
-  history).
+The parser accepts only grammar implemented by the current SDK. Unknown keys and
+closed-enum values fail validation; Mantle does not reserve speculative syntax.
+Add new grammar only alongside a concrete use case, runtime behavior, validation,
+and an ADR update. Earlier experiments remain available in git history.
 
 ---
 
@@ -482,7 +245,7 @@ bundles multiple atoms. A contact form is at minimum:
   inserts)
 - A `Trigger` binding the Procedure to `POST /api/contact`
 
-Three atoms, three manifests. With one file per manifest, a
+Three atoms, three documents. With one file per atom, a
 small site with 10 features has 30+ manifest files. An early
 design-experiment vibe-user called this out:
 
@@ -496,10 +259,10 @@ Two paths surfaced to address the file count:
 #### Path A — Multi-doc YAML
 
 YAML's standard `---` separator allows multiple documents in
-one file. A "feature file" carries all atoms for that feature:
+one file. The fixed site manifest carries all atoms:
 
 ```yaml
-# manifests/contact.yaml
+# manifests/site.yaml
 apiVersion: cms.mantle.aotter.net/v1
 kind: Schema
 metadata: { name: contact-messages }
@@ -525,7 +288,7 @@ spec:
 ```
 
 One file, three atoms, conceptual separation preserved. The
-loader walks files and parses each `---` block as a separate
+loader reads `site.yaml` and parses each `---` block as a separate
 manifest.
 
 #### Path B — Inline shortcut on Procedure (`expose:`)
@@ -560,7 +323,7 @@ Path B created **two ways to bind a Procedure to HTTP**:
 
 - For a Procedure with one HTTP transport: inline `expose:` on
   Procedure
-- For a Procedure with multiple transports (HTTP + cron + MCP):
+- For a Procedure with multiple transports (HTTP + MCP):
   separate `Trigger` per transport
 
 This is the exact "two ways to do the same thing" failure mode.
@@ -582,31 +345,20 @@ multi") but creates permanent tax:
 
 #### What multi-doc YAML accomplishes
 
-- File count drops without inventing redundancy. A feature →
-  one file, regardless of how many atoms it requires.
+- File count drops without inventing redundancy. A site has one
+  authored manifest file regardless of how many atoms it requires.
 - Atom separation stays honest. Every atom has its own
   envelope (`apiVersion`, `kind`, `metadata`, `spec`); there
   is no "shortcut form."
-- Related atoms sit next to each other for readers reviewing a
-  feature.
+- Related atoms sit next to each other for readers reviewing the site.
 - The PG-1:1 framing stays clean: Procedure is
   internal-callable, Trigger is the binding atom.
 
-#### File organization conventions (suggested, not enforced)
-
-- One feature → one file. Name the file by feature
-  (`contact.yaml`, `posts.yaml`, `comments.yaml`), not by atom
-  type.
-- The shared file holds the Procedure + its Trigger + (when
-  feature-specific) the Schema and View.
-- Schemas that are referenced by many features can live in
-  their own `<schema-name>.schema.yaml` file.
-- Views with no Procedure / Trigger neighbors live in
-  `<view-name>.view.yaml`.
+#### Fixed file contract
 
-The validator does not enforce naming conventions; it walks
-all `*.yaml` under the manifest root and parses every `---`
-block as a manifest.
+The authored file is always `manifests/site.yaml`. The common loader rejects
+a missing or differently named file, and every `---` document becomes one
+atom. This is enforced so humans and agents never need a file-discovery rule.
 
 ### Consequences
 
@@ -616,8 +368,7 @@ block as a manifest.
   OpenAPI emitter, runtime dispatcher all walk one shape.
 - Conceptual atom separation preserved. The 4-atom story holds
   for every feature.
-- File count tractable. A typical small site is 5–20 manifest
-  files, not 30+.
+- File count is fixed at one authored manifest.
 - Cardinality changes (1 HTTP → HTTP + cron) are additive (add
   a Trigger); no refactor needed.
 - AI authors learn one mental model, not two.
@@ -630,9 +381,8 @@ block as a manifest.
 - Some loaders (older / non-compliant) don't handle multi-doc.
   Standard `js-yaml` / `yaml` libraries do; the SDK uses
   `yaml` (already a dependency).
-- File-discovery patterns (`find . -name "send-contact-message.trigger.yaml"`)
-  no longer work for atoms inside multi-doc files. Authors
-  must `grep` instead.
+- Authors use `grep` by atom name inside `manifests/site.yaml` instead of
+  discovering feature-specific filenames.
 - Editor support: YAML language servers handle multi-doc, but
   some IDE features (e.g. JSON Schema validation per document
   in a multi-doc file) work less smoothly than in single-doc
@@ -647,18 +397,9 @@ block as a manifest.
   ways is permanent tax that grows with the codebase.
   Mitigation: this section is the answer to that argument; flag
   attempts and link here.
-- **Multi-doc files grow unwieldy.** A "shop" feature might
-  have a Schema + 3 Procedures + 5 Triggers + 2 Views. One
-  file with 11 atoms is harder to navigate than 11 files.
-  Mitigation: file-organization convention is suggestion, not
-  rule; authors are free to split when it stops helping.
-- **Co-location breaks discoverability for shared atoms.**
-  A Schema referenced by 4 features can live in any of those
-  4 files (or its own). Without grep / IDE go-to-def, finding
-  the Schema definition requires knowing where the author
-  put it. Mitigation: Loop 1 (`mantle validate`) emits the
-  filesystem path in `VIEW_FROM_UNKNOWN_SCHEMA` diagnostics;
-  IDE-shaped tooling (LSP — DRAFT) closes the rest.
+- **`site.yaml` can grow.** Search by `kind` plus `metadata.name`; reconsider
+  splitting only when real projects show that one deterministic location is
+  worse than file discovery.
 
 ### Alternatives considered
 
@@ -685,14 +426,14 @@ explicit `Trigger` + explicit `expose:`).
 
 ### How to apply
 
-- Authoring: one feature → one file with `---` separators.
+- Authoring: put every atom in `manifests/site.yaml`, separated by `---`.
 - Reviewing: when an author writes a Procedure with an inline
   HTTP binding, push back with this section.
 - Refactoring: a feature that grew from one HTTP binding to
-  one HTTP + one cron + one MCP doesn't change the Procedure;
-  it adds two more Triggers in the same file.
-- Tooling: SDK loader walks `*.yaml` under manifest root and
-  parses each `---` block; static validator emits diagnostics
+  HTTP + MCP doesn't change the Procedure; it adds one Trigger
+  in the same file.
+- Tooling: SDK loader reads `<manifest-root>/site.yaml` and parses each `---`
+  block; static validator emits diagnostics
   with file path + manifest pointer
-  (`feature.yaml#/2/spec/from`) so multi-doc location stays
+  (`site.yaml#/2/spec/from`) so multi-doc location stays
   precise.

package/docs/adr/0002-closed-enums-for-bindings.md

@@ -96,26 +96,19 @@ The vocabulary is exactly:
 
 - `ctx.user` — caller is signed in as an end-user
 - `ctx.staff: [<role>, ...]` — caller is signed in as staff in one of these roles
-
-Anything beyond (`any:` disjunction; `owns:`, `withinMinutes:`,
-`contains:`, quota predicates) is DRAFT — see
-[ADR-0001](0001-four-atom-manifest-model.md) § Future grammar
-discipline.
+- `ctx.auth` — caller supplied an adapter-verified credential
+- `ctx.auth.scope: <scope>` — credential carries the exact scope
 
 ### Adding a new entry is an explicit grammar-revise round
 
-New `x-mantle-bind` values or `ctx.*` predicates do not get added
-ad-hoc. They go through the discipline gate documented in
-[ADR-0001](0001-four-atom-manifest-model.md) § Future grammar
-discipline:
+New `x-mantle-bind` values or `ctx.*` predicates do not get added ad hoc:
 
 1. A documented use case showing the existing closed set cannot
    express the requirement.
 2. A design pass on what the new value's runtime semantics are
    (where does it come from? when is it null? what happens at
    the storage layer?).
-3. A spec doc revision, including the v0.1-vs-DRAFT
-   classification.
+3. A spec doc revision.
 4. Code that updates the validator to accept the new value.
 
 This treats the closed set as load-bearing infrastructure, not
@@ -208,10 +201,8 @@ attributes.
 - New manifest using a value not in the enum: parse error,
   exact diagnostic shape with `candidates` populated. AI authors
   fix in one turn.
-- New use case wanting an entry not in the enum: open a
-  grammar-revise discussion per ADR-0001 § Future grammar
-  discipline. Document the use case in the spec PR; do not
-  fast-track.
+- New use case wanting an entry not in the enum: document the concrete
+  semantics and add validation, runtime behavior, and docs together.
 - Lookups (e.g. "stamp the team_id"): handler-side TS, not
   binding metadata. The Procedure handler has the lookup
   context anyway.

package/docs/adr/0007-ai-as-primary-author.md

@@ -100,6 +100,8 @@ What it catches:
   `View.filter` refer only to declared properties of that Schema
 - `Schema.uniqueIndexes` and `Schema.indexes` contain valid ordered
   tuples of scalar properties declared in `spec.schema.properties`
+- `Schema.searchableFields` contains unique top-level string properties
+- `Schema.uiSchema.list.filterField` names an indexed operational string enum
 - `x-mantle-bind: <value>` is in the closed enum
 - `requires.auth.all` predicates are in the v0.1 vocabulary
 - `Trigger.source.path` does not collide with another Trigger
@@ -250,9 +252,9 @@ Concrete artifacts today:
 - Version-matched Core skills ship inside `@aotter/mantle`, through the Mantle
   agent plugin, and through exact-byte repo-local projections written by
   `mantle skills`.
-- The umbrella `mantle` CLI exposes `validate`, `generate`, `skills`, `update`,
-  `introspect`, `emit-openapi`, and `emit-types`; direct spec installs expose
-  the authoring subset through `mantle-spec`.
+- The umbrella `mantle` CLI exposes `create`, `generate`, `validate`,
+  `emit-openapi`, `update`, and `skills`; direct spec installs expose advanced
+  `introspect` and `emit-types` primitives through `mantle-spec`.
 - `@aotter/mantle/runtime/testing` and `mantle-harness` expose the measured
   SQLite/index and live-HTTP checks described in Loop 2.
 
@@ -264,7 +266,7 @@ Concrete artifacts today:
   admin: write a post, update a draft, request publish, list
   submissions.
 - Future ops-role verbs that don't exist yet but have an obvious
-  operator use case ("translate this draft", "schedule for Friday").
+  operator use case ("translate this draft", "publish this entry").
   When added, they land as **new SDK builtin tools** — declared in
   the MCP catalog source under the closed Day-1 set, not
   auto-generated from consumer Procedures.

package/docs/adr/0008-structured-diagnostic-shape.md

@@ -126,7 +126,7 @@ code string. That was retired because:
 ### `path` format
 
 - For static validation: filesystem path + JSON Pointer fragment,
-  e.g. `manifests/recent-published.view.yaml#/spec/from`.
+  e.g. `manifests/site.yaml#/3/spec/from`.
 - For a consumer test diagnostic: test file path + assertion location when
   available, e.g. `tests/handlers/contact.test.ts:42`.
 - For boot-time: manifest pointer (no on-disk path because boot
@@ -250,7 +250,7 @@ Diagnostic candidate (alternative (d) below) applies to zod —
   and AI authors see the same structure.
 - Single source of truth. The interface, code constants, and
   formatter all live in `@aotter/mantle-spec`; the runtime
-  package and adapters import them. A future `mantle-netlify`
+  package and adapters import them. A future adapter
   inherits the shape for free.
 
 ### Costs

package/docs/adr/0009-consumer-supplied-manifests.md

@@ -1,13 +1,18 @@
 # ADR-0009: Consumer-supplied manifests at SDK boot
 
-**Status:** Carried over from POC v0.0.x; amended for the parser-free v0.1
-consumer boundary.
+**Status:** Superseded by ADR-0019.
 
-**Date:** 2026-05-01 (POC); last amended 2026-08-03
+**Date:** 2026-05-01 (POC); superseded 2026-08-16
 
 **Related:** [ADR-0001](0001-four-atom-manifest-model.md),
 [ADR-0007](0007-ai-as-primary-author.md),
-[ADR-0018](0018-core-starters-repository-boundary.md)
+[ADR-0018](0018-core-starters-repository-boundary.md),
+[ADR-0019](0019-sealed-manifest-runtime-pipeline.md)
+
+> **Supersession note:** consumer ownership remains durable, but the exact
+> `site.yaml`, generated `site.ts`, and parser-free array workflow below is
+> historical. The sealed source → parse → link → compile pipeline in ADR-0019
+> is current; source names and generated code are optional caller concerns.
 
 ## Context
 
@@ -22,9 +27,10 @@ YAML machinery into the runtime bundle and coupled consumers to Wrangler
 
 ## Decision
 
-Consumers own YAML under `manifests/`. The installed `mantle` CLI parses and
-validates that YAML, then writes the machine-owned runtime module and handler
-types:
+Consumers own exactly `manifests/site.yaml`. The installed `mantle` CLI parses
+and validates its multi-document YAML, then writes the machine-owned runtime
+module and handler types. A missing or differently named file fails before
+generation:
 
 ```bash
 pnpm exec mantle generate
@@ -72,7 +78,7 @@ runtime boot validation covers cross-manifest and registered-handler facts.
 
 The external [`aotter/mantle-starters`](https://github.com/aotter/mantle-starters)
 repository owns the blank project and typed overlays. Materialized projects
-carry their own `manifests/`, generated module, handlers, and package scripts;
+carry their own `manifests/site.yaml`, generated module, handlers, and package scripts;
 they consume the exact packed Core artifact rather than a workspace link.
 
 ## Consequences
@@ -128,7 +134,7 @@ runtime.
 
 When authoring or reviewing a generated project:
 
-1. Edit YAML only under `manifests/`.
+1. Edit only `manifests/site.yaml`; do not create feature-named manifest files.
 2. Run the installed `pnpm exec mantle generate`.
 3. Import `manifest` from `.mantle/generated/site.js` into the conventional
    Worker, or pass it as `CmsConfig.manifests` in low-level composition.