@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/docs/adapter-guide.md

@@ -1,222 +0,0 @@
-# Adapter implementation guide
-
-This guide is the fresh-developer entry point for implementing a new mantle platform adapter.
-
-Read this with [ADR-0019](adr/0019-sealed-manifest-runtime-pipeline.md). The source of truth for TypeScript shapes is `packages/mantle-runtime/src/domain/port/`.
-
-Adapter packages live under `packages/adapters/<platform>/` using a plural `adapters` bucket. The npm package names stay unchanged, for example `@aotter/mantle-cloudflare`. Keep adapters in this monorepo until the runtime/spec API is stable enough that coordinated releases across separate repositories would not create version skew for consumers.
-
-## Required storage boundary
-
-A storage adapter prepares one `RuntimePlan` into semantic ports:
-
-| Contract | Source | Cloudflare example |
-|---|---|---|
-| `MantleStorageAdapter` / `PreparedMantleStorage` | `packages/mantle-runtime/src/domain/port/MantleStorageAdapter.ts` | `SqliteMantleStorageAdapter` over `D1DatabaseDriver` |
-| `EntryRepository & EntryReader` | Existing semantic content ports | `DatabaseEntryRepository` supplied by the SQLite adapter |
-| `ViewQueryExecutor` | `packages/mantle-runtime/src/domain/port/ViewQueryExecutor.ts` | `SqliteViewQueryExecutor` |
-
-`DatabaseDriver` is only the reusable SQLite/D1 implementation seam. A
-PostgreSQL, MongoDB, or application-owned-table adapter implements the semantic
-ports directly; it does not emulate D1 and needs no mapping DSL. Platform types
-such as `D1Database`, Postgres pools, and Mongo clients remain in adapter code.
-
-## Optional capabilities
-
-Optional ports are enabled only when a feature needs them:
-
-| Contract | Source | Required when |
-|---|---|---|
-| `MediaStorage` | `packages/mantle-runtime/src/domain/port/MediaStorage.ts` | The adapter exposes admin/MCP media upload flows. |
-| `DeferredHookDispatcher` | `packages/mantle-runtime/src/domain/port/DeferredHookDispatcher.ts` | The adapter wants at-least-once queue delivery for `after_*` lifecycle hooks. |
-
-Test seams such as `Clock` and `IdGenerator` are injectable through `createMantleRuntime`, but normal adapters do not need custom implementations.
-
-Deferred delivery is an optional, versioned wire contract. Queue acceptance is
-not atomic with the entry write; adapters must preserve the supplied event id,
-validate untrusted messages before dereferencing them, surface handler failures
-to their retry mechanism, and document poison-message/DLQ behavior. See
-[Deferred lifecycle hooks on Cloudflare Queues](deferred-lifecycle-queues.md)
-for the reference implementation and exact guarantees.
-
-## Storage preparation
-
-Compile before deployment preparation, then pass only the sealed plan:
-
-```ts
-import {
-  bootMantleRuntime,
-  SqliteMantleStorageAdapter,
-} from "@aotter/mantle-runtime";
-
-const storage = new SqliteMantleStorageAdapter(db, siteDefaults);
-const runtime = await bootMantleRuntime({
-  plan,
-  storage,
-  handlers,
-  ports,
-  deployment: {
-    reservedHttpPathPrefixes: selectedCapabilities.flatMap(
-      (capability) => capability.reservedHttpPathPrefixes,
-    ),
-  },
-});
-```
-
-`bootMantleRuntime` performs one attempt and derives Procedure readiness from
-the supplied handlers. The platform adapter remains responsible for lazy boot,
-promise caching, retry policy, and teardown.
-
-Hosts that need work between preparation and binding may keep the same stages
-public and explicit:
-
-```ts
-const prepared = await prepareDeployment(plan, storage, {
-  handlerNames: Object.keys(handlers ?? {}),
-});
-const runtime = createMantleRuntime({ prepared, handlers, ports });
-```
-
-The prepared revision carries its exact plan, but exposes both `plan` and
-`storage`; it seals the pairing invariant rather than hiding low-level host
-capabilities. Omit `handlerNames` only for a read-only embedding that never
-dispatches Procedures.
-
-The official SQLite adapter runs canonical migrations, materializes one native
-table per Schema, prepares indexes and Views, and skips mutation for an
-unchanged storage revision. A
-custom adapter owns its own preparation and returns application-owned semantic
-ports. Unsupported native View dialects fail before the adapter mutates state.
-
-### Bun embedding
-
-> **Experimental.** The Bun and Vercel adapters may change in a minor
-> release. They cover public Views and HTTP Triggers; the host owns
-> authentication and CSRF, and Auth, Admin and MCP are Cloudflare-only today.
-> Cloudflare is the supported host.
-
-`@aotter/mantle-bun` is the minimal SQLite reference: pass an application-owned
-`bun:sqlite` `Database` and a compiled `RuntimePlan` to `createBunMantle()`.
-Its `handle()` returns `null` for sibling routes and a Web-standard `Response`
-for manifest-declared public Views and HTTP Triggers. The host owns
-`Bun.serve`, database shutdown, authentication, and CSRF policy; the adapter
-prepares the semantic revision once and retries only after failed preparation.
-
-### Vercel Functions embedding
-
-`@aotter/mantle-vercel` accepts a compiled plan plus any application-owned
-`MantleStorageAdapter` and reuses the same public View/HTTP Trigger transport as
-Bun. It maps deferred work to Vercel Functions `waitUntil` and otherwise leaves
-the Web Handler, auth/CSRF, and route composition to the application. The
-optional `/libsql` subpath adapts a caller-owned remote Turso/libSQL client to
-the canonical SQLite chain; the default entry has no database-vendor policy.
-Vercel's read-only filesystem and writable `/tmp` are never durable state.
-
-### Browser IndexedDB embedding
-
-`@aotter/mantle-indexeddb` implements the same required semantic storage ports
-over one application-owned IndexedDB database. It keeps browser globals out of
-Runtime Core, supports declarative Views with a documented O(n) collection
-scan, and exposes `deleteDatabase()` only on the concrete adapter. The host owns
-database naming, `navigator.storage` persistence requests, active-runtime
-selection, UI invalidation, and any remote synchronization.
-
-## HTTP and MCP surfaces
-
-The runtime is a library, not an HTTP server. A new adapter must mount equivalent framework routes:
-
-| Surface | Adapter responsibility | Cloudflare reference |
-|---|---|---|
-| Runtime HTTP endpoints | Route HTTP Triggers and public View REST endpoints into runtime use cases. | `packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts` |
-| Optional Admin | Supply session/request context and assets to `mantle-admin`; mount only when selected. | `packages/adapters/cloudflare/src/mount/mountAdmin.ts` |
-| Auth endpoints | Own sign-in/session/OAuth metadata through the adapter's Better Auth implementation selected by Admin/OAuth surfaces. | `packages/adapters/cloudflare/src/auth/createAuth.ts` |
-| MCP endpoints | Mount `/mcp/staff` and `/mcp` behind one canonical protected resource. The adapter verifies Better Auth JWTs, normalizes the caller, re-reads the staff D1 role, then dispatches JSON-RPC. | `packages/adapters/cloudflare/src/mount/mountMcp.ts`, `auth/createAuth.ts` |
-
-Auth is not a runtime port. Per [ADR-0014](adr/0014-auth-better-auth-and-multi-tenant-mcp.md), the adapter owns Better Auth wiring and passes authenticated user/staff context into runtime dispatchers. Procedure handlers receive that data through `HandlerContext` in `packages/mantle-runtime/src/domain/model/HandlerContext.ts`.
-
-The adapter must also normalize verified credential metadata into
-`HandlerContext.auth` (`credential`, opaque `credentialId`, optional
-`clientId`, scopes). Platform-native session/OAuth verification stays in the
-adapter. A narrow adapter extension seam may let consumer code verify its own
-API-key or personal-token formats, but credential storage/issuance must not
-become a runtime port. The Cloudflare reference is
-`mount/resolveCaller.ts`; consumer usage is documented in
-[API and MCP authorization](examples/cf-primitives-guarded-api.md).
-
-Minimum HTTP behavior for a full adapter:
-
-- Route manifest HTTP Triggers to `runtime.invokeProcedure`.
-- Route `GET /api/views/<name>` to `runtime.executeView`.
-- Mount admin content APIs with session/role checks before calling runtime content use cases.
-- Serve selected Admin SPA assets through `AdminAssetServer`, with an SPA catchall for client-side routes.
-- Mount public render routes and markdown mirrors when the application exposes public pages.
-- Translate runtime diagnostics and validation failures into stable HTTP JSON responses instead of throwing raw errors.
-- Evaluate target auth and dynamic guards through the runtime use cases; do
-  not duplicate guard logic in HTTP handlers.
-
-For the Cloudflare adapter, public rendering requires three matching consumer
-inputs: `mountPublicRoutes(...)` route declarations, a `TemplateRegistry`
-passed through `MantleCloudflareConfig.templates`, and a `publicPathResolver`
-passed through `MantleCloudflareConfig.publicPathResolver`. Omitting public routes is valid for a headless
-consumer; mounting every Schema automatically is not, because some collections
-are private even when they contain a slug.
-
-`TemplateRegistry` and `createPublicPathResolver` come from
-`@aotter/mantle-web`. Other adapters can call `createMantleWeb(runtime)` and map
-its document operations into their own routing and cache conventions.
-
-### HTTP cache contract
-
-Keep responses private by default. For Cloudflare, apply the final policy after
-all routes and preserve only explicit anonymous public opt-in. Follow the
-[public cache contract](handbook/cloudflare/public-web.md#cache-contract) and the
-[performance harness](performance-harness.md#cache-contract) for verification.
-
-Minimum auth/MCP behavior:
-
-- Provide Better Auth-compatible sign-in/session routes for the platform.
-- Validate `/mcp/staff` requests with the staff D1 admin role (`owner`/`editor`/`contributor`).
-- Validate `/mcp` requests with any authenticated session (D1 role check is surface-driven, not OAuth-scope-driven — claude.ai rejects colon-shaped scopes).
-- Advertise a single non-colon scope (default `["mcp"]`) in `scopes_supported`. Per-surface enforcement happens server-side in the apiHandler.
-- Build `McpAuthContext` from the validated session and pass it to `McpJsonRpcDispatcher`.
-- Build Procedure/View `HandlerContext` with `user`, live `staff`, normalized
-  `auth`, adapter `env`, and optional `waitUntil`.
-- Re-read mutable staff role for each protected REST/MCP invocation. Token or
-  consent-time role snapshots are not an authorization boundary.
-- Keep `tools/list` filtering as UX only; route every `tools/call` through the
-  same auth evaluator and guard runner used by REST.
-
-## Static assets
-
-`AdminAssetServer` belongs to optional `@aotter/mantle-admin`. Headless Core
-storage preparation and binding do not accept or require a static asset port.
-
-## Implementation checklist
-
-- [ ] Run `runStorageConformance` from `@aotter/mantle-runtime/testing/storage`
-      against a disposable prepared-storage factory. See the
-      [Runtime conformance guide](../packages/mantle-runtime/README.md#storage-adapter-conformance)
-      for coverage, cleanup, locale setup, and remaining adapter-specific tests.
-- [ ] Implement `MantleStorageAdapter` returning existing semantic ports, or reuse `SqliteMantleStorageAdapter` with an already-owned handle.
-- [ ] Call `bootMantleRuntime()` once per semantic revision, or explicitly prepare before binding.
-- [ ] Mount HTTP Trigger and View REST surfaces.
-- [ ] Mount admin/public render routes and admin SPA assets.
-- [ ] Provide adapter-owned Better Auth wiring and session helpers.
-- [ ] Normalize session/OAuth and any consumer credential seam into
-      `HandlerContext.auth`; never put raw credentials in runtime context.
-- [ ] Mount `/mcp/staff` and `/mcp` behind one resource-bound token verifier. Enforce the live staff role inside the apiHandler.
-- [ ] Preserve the HTTP cache contract: private by default; explicit anonymous 200 `GET`/`HEAD` public opt-in only.
-- [ ] Prove one guarded target has identical REST/MCP outcomes, including
-      mutable revocation on the next call.
-- [ ] Add optional `MediaStorage` or `DeferredHookDispatcher` only when the adapter supports those features.
-- [ ] For deferred hooks, document at-least-once delivery, idempotency,
-      message limits, retries/DLQ, and the non-transactional write-to-enqueue gap.
-- [ ] Verify the runtime package still has no platform-specific imports.
-
-## Current non-goals
-
-- Do not add `SessionRepository`, `OAuthVerifier`, `UserRepository`, or `StaffRepository` runtime ports. Those were pre-ADR-0014 concepts and are not part of the current adapter contract.
-- Do not add API-key, personal-token, transaction, billing, or entitlement
-  repositories to Core. They are consumer state behind the adapter resolver
-  and guard Procedure.
-- Do not generalize `DatabaseDriver` for PostgreSQL/MongoDB or add a mapping DSL. Implement semantic ports; SQLite/D1 alone reuse the canonical SQL chain.

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

@@ -1,440 +0,0 @@
-# ADR-0001: 4-atom YAML manifest model under `cms.mantle.aotter.net/v1`
-
-**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); last amended 2026-08-16
-
-**Deciders**: phsu
-
-**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.
-
----
-
-## Context
-
-The SDK's surface area to consumers is YAML manifests. The
-question is: what set of resource kinds does that surface
-expose? Too few and authors find themselves cramming concepts
-into the wrong atom; too many and consumers face a long enum of
-"what kind do I write today" with overlapping semantics.
-
-Earlier iterations of this CMS experimented with 11 domain-shaped
-kinds (`ContentSchema`, `ContentView`, `Form`, `Membership`,
-`Email`, `Webhook`, `Workflow`, `ScheduledJob`, etc.). Two
-problems surfaced:
-
-1. **Authors couldn't find the right atom for a new feature.**
-   "Is a contact form a `Form`, a `Workflow`, an `Email`, or all
-   three?" Real features cross domain boundaries.
-2. **Atoms drifted toward overlap.** A `Form` developed an
-   `email:` block; a `Webhook` developed a `validation:` block;
-   each new kind grew to subsume neighbors.
-
-A multi-round design experiment (6 rounds + R6.5 falsification +
-R7 reframing, run as a 4-agent debate over a blog feature
-progression: like button → threaded comments → private posts →
-rate-limited writes → cross-Schema invariants) reduced the kind
-count to 4 and tested those 4 against 6 increasingly demanding
-features without needing a 5th.
-
-The relevant history that this ADR records (so future readers
-don't re-litigate it):
-
-- **R0 — "atoms ≡ PG primitives" claim**: the experiment opened
-  with the heuristic "4 kinds because Postgres has 4
-  application-developer primitives." Held for 6 rounds without
-  challenge.
-- **R6.5 — falsification round**: an agent proposed cutting to
-  3 atoms by folding `Procedure` into `Schema.operations` (PG
-  functions attach to schemas in pg_proc). 92→58 LOC reduction
-  in the worked example by adding a default-CRUD shortcut.
-  Accepted by the round's judge.
-- **R7 — user reframing**: reverted to 4 atoms, but for a
-  different reason than R0. The right axis isn't "PG
-  primitive"; it's "contract vs implementation × state vs
-  event":
-
-  | | request | event |
-  |---|---|---|
-  | external API | View (read) / write-API atom | (empty in v0.1) |
-  | internal | (Schema's writes are via the write-API atom) | Trigger (reaction) / Schema (state) |
-
-**Design lesson** (worth surfacing because it shaped both this
-ADR and the multi-doc YAML decision below): in multi-round
-agent-team debates, decisions ratified in early rounds tend to
-inherit forward through later rounds even when the local
-conditions that justified them have changed. The orchestrator
-must re-test prior naming / structural decisions whenever the
-spec surface materially shifts; agent-team consensus is a strong
-signal but not authoritative.
-
-## Decision
-
-The SDK exposes exactly **four declarative resource kinds** under
-the `cms.mantle.aotter.net/v1` API group:
-
-| Atom | Postgres equivalent | Externally exposed by itself? | Has user code? |
-|---|---|---|---|
-| `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` + 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 / lifecycle, declare a
-`Trigger` whose `target.procedure` points at it. The same
-Procedure can be bound by multiple Triggers (HTTP + MCP,
-all sharing one handler).
-
-This is "Path A" relative to an alternative considered (and
-rejected — see below) where Procedures carried an inline
-`expose:` block.
-
-### PG-1:1 mapping is the primary onboarding pitch
-
-The mapping above is what new authors see first. Authors with
-Postgres background orient instantly. Authors without it get a
-mental anchor with 30 years of Codd/SQL/PostgREST literature
-behind it.
-
-### Composition rule
-
-Anything more domain-shaped than these 4 (a `Form`,
-`Membership`, `Email`, `Webhook`, `Workflow`, `ScheduledJob`)
-is **not** an atom. It is composed in the consumer project by
-combining the 4 atoms with consumer TypeScript. If a proposed
-new feature wants a 5th kind, the proposer must show the 4
-existing atoms cannot express it.
-
-## Consequences
-
-### Pros
-
-- One question — "is it state, a query, an operation, or an
-  event-binding?" — picks the atom every time. No "form vs
-  workflow" gray zone.
-- Read/write asymmetry (Views auto-mount, Procedures require
-  Triggers) matches HTTP safe-vs-unsafe semantics. Authors don't
-  have to remember which kinds the SDK auto-routes; the rule is
-  derivable from the atom's nature.
-- PG mapping gives the spec 30 years of literature and battle
-  testing as background. Postgres has shipped these primitives
-  in the same shape since SQL-92 (Schema, View, Procedure) plus
-  Active Database / ECA rules from the 1990s (Trigger).
-- Closed atom count makes the SDK's testing surface tractable:
-  every code path can be enumerated as
-  Schema-creation / View-query / Procedure-invocation /
-  Trigger-firing combinations.
-
-### Costs
-
-- Atoms are coarse. A "form-with-validation-and-email" feature
-  is 3 manifests (Schema + Procedure + Trigger), not 1. Mitigated
-  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.
-- 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.
-
-### Risks
-
-- **Authors try to subsume domain concepts into the 4 atoms by
-  cramming.** A `Form` becomes "a Schema + a Procedure + an
-  ad-hoc validator block in the handler." Mitigated by
-  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 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
-  defensible; the discipline is to flag the choice consciously.
-
-## Alternatives considered
-
-**(a) 11 domain-shaped kinds (early scaffolding)**.
-Rejected: cross-cutting features didn't fit single kinds;
-adjacent kinds drifted toward overlap. Authors couldn't pick.
-
-**(b) 5 kinds — keep `Policy` as a separate atom**.
-Rejected: row/field-level policy is sub-spec on the atom whose
-data it concerns (Schema-attached visibility, Procedure-attached
-auth gate). Lifting Policy to a kind invented a 5th locator
-authors had to consult; folding it kept the locator count down.
-
-**(c) 3 kinds — fold Procedure into `Schema.operations`** (R6.5).
-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 through the shipped
-`handler.kind: builtin` shortcut.
-
-**(d) 4 kinds with `Procedure` retaining inline
-`expose: { http: ... }` for single-source bindings**.
-Rejected: created two ways to bind HTTP (inline `expose:` for
-single-source, separate `Trigger` for multi-source). Doctrine
-tax forever. Multi-doc YAML solves the file-count complaint
-that motivated `expose:` without inventing redundant grammar.
-See § Authoring shape below for the full retirement rationale.
-
-## How to apply
-
-- Adding a new feature: ask which of the 4 atoms holds each
-  piece. Use the "external by itself?" column to settle "do I
-  need a Trigger here?"
-- Adding a new top-level kind: do not. First express as a
-  composition of the 4 + consumer TS. If the composition is
-  awkward, look for sub-spec on an existing atom before adding
-  a 5th kind.
-- Renaming an atom: do not. The names are public surface; even
-  internally-motivated renames tend to drag schema-revise effort
-  across consumers, code, docs, and agent training data. Bias
-  toward keeping the names.
-- Reading the spec: Schema = state, View = read API,
-  Procedure = write API (internal), Trigger = binding. That
-  4-word gloss covers ~90% of the questions authors ask.
-
-## Implementation status
-
-Names + PG-1:1 framing are documented in this ADR and the manifest grammar
-reference. Manifest TS types live in `packages/mantle-spec/`. The external
-[`aotter/mantle-starters`](https://github.com/aotter/mantle-starters)
-repository declared alpha-era consumer instances of each atom; new applications
-are authored directly under [ADR-0021](0021-retire-starter-scaffolding.md).
-Runtime dispatcher, View executor, and Procedure dispatcher live in this repository.
-
----
-
-## Grammar changes
-
-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.
-
----
-
-## Authoring shape: multi-doc YAML (was POC ADR-0006)
-
-> Folded in 2026-05-03 from POC ADR-0006 ("Multi-doc YAML over
-> inline shortcuts for atom co-location"). The decision below
-> defines how authors lay manifests out on disk; it is the
-> direct corollary of "Trigger does all binding" above.
-
-### Context
-
-The 4-atom model means a single user-visible feature commonly
-bundles multiple atoms. A contact form is at minimum:
-
-- A `Schema` for `contact-messages`
-- A `Procedure` `send-contact-message` (handler validates +
-  inserts)
-- A `Trigger` binding the Procedure to `POST /api/contact`
-
-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:
-
-> 4 個 manifest 為了一顆 like 按鈕？要寫成這樣才能用？
-
-(Translation: 4 manifests just for a like button? You have to
-write all this to make it work?)
-
-Two paths surfaced to address the file count:
-
-#### Path A — Multi-doc YAML
-
-YAML's standard `---` separator allows multiple documents in
-one file. The fixed site manifest carries all atoms:
-
-```yaml
-# manifests/site.yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata: { name: contact-messages }
-spec:
-  schema: { ... }
-
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata: { name: send-contact-message }
-spec:
-  input:  { ... }
-  output: { ... }
-  handler: { kind: ref, ref: send-contact-message }
-
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata: { name: contact-http }
-spec:
-  source: { kind: http, method: POST, path: /api/contact }
-  target: { procedure: send-contact-message }
-```
-
-One file, three atoms, conceptual separation preserved. The
-loader reads `site.yaml` and parses each `---` block as a separate
-manifest.
-
-#### Path B — Inline shortcut on Procedure (`expose:`)
-
-Add a `Procedure.expose:` block that absorbs single-source HTTP
-binding inline, eliminating the Trigger for the 1:1 case:
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata: { name: send-contact-message }
-spec:
-  expose:
-    http: { method: POST, path: /api/contact }
-  input:  { ... }
-  output: { ... }
-  handler: { kind: ref, ref: send-contact-message }
-```
-
-The two paths solve the same surface concern (file count) but
-have very different structural implications.
-
-### Decision
-
-**Path A: Multi-doc YAML.** `Procedure.expose:` is permanently
-retired. Trigger does ALL transport binding. Co-locate related
-atoms in one file via `---`.
-
-#### Why Path B was retired
-
-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 + MCP):
-  separate `Trigger` per transport
-
-This is the exact "two ways to do the same thing" failure mode.
-Doctrine resolves it on paper ("expose for single, Trigger for
-multi") but creates permanent tax:
-
-- Authors must remember which form to use, and switch when
-  cardinality changes (a single-HTTP Procedure that later
-  needs an MCP binding has to be refactored from `expose:` to
-  `Trigger`).
-- The validator must understand both forms; OpenAPI emission
-  has two source paths to walk.
-- The PG-1:1 mapping is muddied: "Procedure ≡ pg_proc" is clean
-  only if Procedure is internal-callable (no transport surface);
-  `expose:` gives Procedure transport semantics, weakening the
-  analogy.
-- AI authors trying to introspect the manifest model get
-  conflicting signals about what the atom does.
-
-#### What multi-doc YAML accomplishes
-
-- 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 the site.
-- The PG-1:1 framing stays clean: Procedure is
-  internal-callable, Trigger is the binding atom.
-
-#### Fixed file contract
-
-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
-
-#### Pros
-
-- Single mechanism for HTTP binding (Trigger). Validator,
-  OpenAPI emitter, runtime dispatcher all walk one shape.
-- Conceptual atom separation preserved. The 4-atom story holds
-  for every feature.
-- 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.
-
-#### Costs
-
-- Author must learn YAML's multi-doc syntax (`---`). This is
-  standard YAML 1.2 and supported by every loader, but it is
-  one more piece of syntax than "one file = one document."
-- Some loaders (older / non-compliant) don't handle multi-doc.
-  Standard `js-yaml` / `yaml` libraries do; the SDK uses
-  `yaml` (already a dependency).
-- 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
-  files. Acceptable for v0.1.
-
-#### Risks
-
-- **Author convenience pressure to reintroduce `expose:`.**
-  Someone shows up with "but for the 80% case where I have one
-  HTTP binding, the inline form is so much shorter!" The
-  argument is real; the answer is: doctrine that creates two
-  ways is permanent tax that grows with the codebase.
-  Mitigation: this section is the answer to that argument; flag
-  attempts and link here.
-- **`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
-
-**(a) Path B: `Procedure.expose:`**.
-Rejected (this section's main subject). Doctrine tax forever; PG
-analogy weakened; cardinality refactor required when
-single-source becomes multi-source.
-
-**(b) One file per atom (early scaffolding default)**.
-Rejected: file count complaint is real for multi-atom features.
-Path A solves it without inventing redundancy.
-
-**(c) New top-level kind `Feature` that bundles atoms**.
-Rejected: turns a YAML file-organization concern into a spec
-question. The 4-atom contract holds; an envelope-around-atoms
-is structural noise.
-
-**(d) Make Trigger optional with a default of "auto-mount the
-Procedure at /api/p/<name>"**.
-Rejected: hides the binding decision from the author, breaks
-the PG-1:1 mapping (Procedures are not externally exposed by
-themselves), and creates a third way to bind (this default +
-explicit `Trigger` + explicit `expose:`).
-
-### How to apply
-
-- 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
-  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
-  (`site.yaml#/2/spec/from`) so multi-doc location stays
-  precise.