@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

package/docs/adr/0029-mcp-apps-interaction-contracts.md

@@ -1,324 +0,0 @@
-# ADR-0029: Official MCP SDK, interaction contracts and MCP Apps
-
-**Status:** Accepted
-
-**Date:** 2026-09-25
-
-**Related:** epic [#1110](https://github.com/aotter/mantle/issues/1110)
-(supersedes #1109); tracked as [#1114](https://github.com/aotter/mantle/issues/1114).
-Builds on [ADR-0012](0012-views-as-public-rest.md),
-[ADR-0014](0014-auth-better-auth-and-multi-tenant-mcp.md),
-[ADR-0019](0019-sealed-manifest-runtime-pipeline.md),
-[ADR-0020](0020-builtin-handler-contracts-and-matched-upsert.md),
-[ADR-0022](0022-caller-observed-version-occ.md),
-[ADR-lite 845](adr-lite-845-frontend-client.md),
-[ADR-lite 861](adr-lite-861-admin-webmcp.md).
-Amends [ADR-lite 909](adr-lite-909-admin-ui-kit.md) (the kit moves to
-`@aotter/mantle-ui`). External: MCP specification 2025-11-25 and 2026-07-28,
-the MCP Apps extension, and the official TypeScript SDK
-(`@modelcontextprotocol/server` 2.1.0, `client` 2.1.0, `ext-apps` 2.0.0).
-
-## Context
-
-Mantle projects callable capabilities from the sealed RuntimePlan
-(`CallableCapabilityProjector`) and serves them over a hand-written JSON-RPC
-dispatcher in `mantle-runtime/src/infrastructure/mcp`. The #1109 goal (agents
-discover capabilities, find the right record, and open an interaction UI in
-chat) exposed three gaps.
-
-**Protocol.** The hand-written dispatcher accepts only protocol `2025-11-25`,
-has no resource layer, and duplicates negotiation, batching and error framing
-that the official SDK already owns. MCP Apps would add `resources/*`,
-`ui://` resources and `_meta.ui` negotiation on top. The repository already
-tests against the official client (#1023), and the official
-`@modelcontextprotocol/ext-apps` 2.0 server helpers target SDK 2.x.
-
-**Semantics in the wrong layer.** Tool semantics live in the transport:
-generic-tool role floors, entry mutability checks, argument parsing, media
-tool descriptions and `expected_version` annotation are in `McpToolCatalog`
-and `McpJsonRpcDispatcher.dispatchToolByName`. They must survive a transport
-swap unchanged.
-
-**Interaction contracts.** Verified on `develop` @ `35d2c14`:
-
-1. Row binding is inferred, and only in Admin. `discoverRowBindings`
-   (`mantle-admin/src/mountMantleAdmin.ts`) picks a same-name property, then a
-   lone single-field unique index, then `id`. The procurement example omits
-   `x-mantle-ref` because the inference would bind `requestNumber` where
-   builtin `update` needs the entry id.
-2. Admin's View page has no row operations; bindings are keyed by collection.
-3. SQL Views declare no output (ADR-lite 845).
-4. `lockedCollection()` in `ManifestGraphValidator` infers the collection an
-   OCC write locks. It is a diagnostic heuristic, not an execution contract.
-5. Staff MCP has no single-entry read.
-6. Admin binds the version read when the dialog opens
-   (`row-operations.tsx`), not the version of the row the user saw.
-7. Business errors are JSON-RPC `-32000` errors with `error.data`.
-8. Website preview (`?preview=1`) is authorized by a staff session cookie,
-   which is a third-party cookie inside a host's sandboxed iframe.
-9. Canonical Admin refuses framing (`frame-ancestors 'none'`).
-10. An MCP App's `tools/call` is proxied by the host with the model's client
-    credential. The server cannot tell a UI call from a model call.
-
-## Decision
-
-### 1. Protocol belongs to the official SDK; semantics belong to Mantle
-
-All MCP wire handling uses the official TypeScript SDK: JSON-RPC framing,
-version negotiation, transports, `tools/*`, `resources/*` and MCP Apps
-metadata. Mantle keeps authorization, guards, OCC, audit, validation and the
-diagnostic vocabulary. Official packages are pinned to exact versions and
-never forked. No hand-written JSON-RPC handling remains in the repository.
-
-Both protocol eras are served: `2026-07-28` and `2025-*` in stateless mode
-(`createMcpHandler(..., { legacy: "stateless" })`).
-
-### 2. Runtime is transport-neutral
-
-Runtime stops knowing about MCP. It provides:
-
-- `CapabilityCatalog` (domain service): one transport-neutral description per
-  callable capability on a surface: Views, Procedures, generic authoring and
-  lifecycle operations, and media upload. Each carries name, surface, title,
-  description, `inputSchema`, declared `outputSchema`, annotations,
-  `requiresIdentity` and the argument that identifies the operation for audit.
-- `InvokeCapabilityUseCase` (use case): the single execution entry and the
-  single validation point. It returns
-  `{ ok: true, data } | { ok: false, diagnostic }`. Missing or ill-typed
-  arguments are `VALIDATION_FAILED` diagnostics.
-
-Nothing under `domain/` or `usecase/` imports an MCP concept.
-
-### 3. Validate once
-
-The SDK receives each `inputSchema` through `fromJsonSchema(schema, validator)`
-with a pass-through validator: the schema is advertised unchanged, and the
-SDK does not validate. Runtime validates once, so MCP, HTTP and Admin report
-the same Mantle diagnostic, and the Ajv instance the default validator would
-pull in is not bundled.
-
-`outputSchema` is the safe projection from #1127: an allowlist that only
-loosens the declared schema, so a standard client validator accepts every
-value Runtime accepts. Ineligible outputs advertise none. Views advertise none.
-
-### 4. Results and errors (D1)
-
-- **Success:** `content` is one JSON text block; `structuredContent` carries
-  the value when it is a plain object.
-- **Business failure:** `isError: true` with `{ diagnostics: [Diagnostic] }`
-  (the ADR-0008 shape) as a JSON text block, repeated as `structuredContent`
-  unless the tool advertises an `outputSchema`. Structured results must
-  conform to that schema, and 1.x clients validate them even on `isError`.
-  This replaces the JSON-RPC `-32000` business error and is a breaking wire
-  change, announced with the cutover.
-- **Protocol failure** (malformed request, unknown method, unsupported
-  version) stays a JSON-RPC error owned by the SDK.
-- **Authentication:** an anonymous call to a tool whose capability
-  `requiresIdentity` (including any member of a 2025-era batch) is answered
-  before the SDK with HTTP 401 and a `WWW-Authenticate` challenge built by the
-  SDK helper. The SDK's own
-  `scopeChallenge` covers scopes only; identity stays outside it.
-
-### 5. Identity stays outside the SDK
-
-The SDK never verifies tokens. Adapters verify the caller with `mantle-auth`
-(ADR-0014), build the `HandlerContext`, and pass it as `authInfo.extra`. The
-server factory reads it per request. Authorization extensions such as EMA are
-unaffected.
-
-### 6. Packages and dependency direction (D7)
-
-Two packages are added; no other package is split.
-
-| Package | Responsibility |
-|---|---|
-| `@aotter/mantle-mcp` | Optional. Registers the capability catalog on an official `McpServer` per surface (`createMantleMcpServer`), wraps `createMcpHandler` (`createMantleMcpHandler`), writes audit per call, and registers MCP Apps resources and app tools through `@modelcontextprotocol/ext-apps/server`. No UI dependency. |
-| `@aotter/mantle-ui` | Optional. `/controller`: framework-free interaction controller; must not import React. `/` (root): React interaction components. `/kit` (with `kit.css` and `tokens.css`): the ADR-lite 909 kit moved from `@aotter/mantle-admin-ui/kit`, whose libraries are optional peers so `/controller` installs none. `/mcp-app`: a single-file `ui://` HTML build (`vite-plugin-singlefile`) using the official `App` bridge. |
-
-```text
-mantle-spec ◄── mantle-runtime ◄── mantle-mcp ◄── adapters, mantle-admin
-                      ▲                 │
-                      │                 └──► @modelcontextprotocol/server, ext-apps/server
-                      │ (types only)
-              mantle-ui/controller ◄── mantle-ui ◄── mantle-ui/mcp-app ──► ext-apps (App)
-                                           ▲
-                                     mantle-admin-ui
-```
-
-- Arrows point from consumer to dependency. Server packages never depend on
-  UI packages; `mantle-mcp` receives MCP App HTML as injected bytes.
-
-> **Amendment (0.2.0):** results carry no `_meta` interaction description.
-> `planApp(plan, { surface, html })` (`@aotter/mantle/mcp`) embeds the plan's
-> catalog (each View tool's columns as the fields they read, and, for a View
-> that reads one table and outputs its `id`, the Procedure tools whose
-> `target` is that Schema) as a JSON script in the injected HTML, and renders
-> every View tool of the surface. A rendered result names its tool in
-> `_meta["net.aotter.mantle/tool"]`. The App (`mantleAppHtml` from
-> `@aotter/mantle-ui/mcp-app`) reviews a row as listed; a moved version is the
-> server's `CONFLICT`. The preset serves it on `/mcp/staff`; a member-facing
-> App is the application's own.
-- `@aotter/mantle-admin-ui/kit` re-exports from `@aotter/mantle-ui` for one
-  minor release, then is removed.
-- No exported UI module depends on Admin's router, global API client, query
-  singletons or cookie session.
-
-### 7. Interaction contract
-
-| Term | Meaning |
-|---|---|
-| **Capability** | A callable View or Procedure on one surface, with its Trigger identity. |
-| **Target** | The entity an interaction is about: collection plus a stable key, never a display label. |
-| **Reference** | A declared relation from a field to a target collection and key. A reference alone does not mean an operation mutates or locks that entity. |
-| **Operation target** | The entity an operation mutates and whose version it locks. |
-| **Snapshot read** | The authorized read that produces what the human sees, including its version. |
-| **Input binding** | An explicit mapping from snapshot fields to operation input. |
-| **Version binding** | The input field carrying the observed version, taken from the snapshot the human saw. |
-| **Renderer** | Presentation of a snapshot, form, review or outcome. Owns no semantics. |
-
-Rules:
-
-- An interaction is **entity-bound** only when target, snapshot read, input
-  binding and (when required) version binding are all established by the
-  contract. Otherwise no automatic binding is offered; the operation stays
-  usable as an ordinary form.
-- Nothing is guessed from names.
-- **Derivable today:** builtin `update`/`delete`/`archive` and id-based
-  `upsert` target `handler.schema` by input `id`, with `expectedVersion` when
-  declared; a non-SQL View's rows target its `from` collection when `fields`
-  includes `id`, and supply a version only when `fields` includes `version`.
-- **Declared (D4, grammar-revise #1116):**
-  - `x-mantle-ref: { schema, field }` on a Schema or View field names the
-    target collection and the key field. `field` must be `id` or a
-    single-field unique index of `schema`.
-  - `Procedure.spec.target: { schema, id, version? }` names a `ref`
-    handler's operation target: `id` and `version` are input property names.
-    It is rejected on builtin handlers, whose target is already derivable.
-  - Queries, notifications and multi-entity Procedures declare no target.
-- `lockedCollection()` stays a diagnostic heuristic.
-- SQL Views are not bound automatically until a validated output contract
-  admits them.
-- **View purpose (D5, #1115):** `View.spec.description` is added and projected
-  into the View tool description.
-
-### 8. Snapshot and version (D2)
-
-- Public and member snapshots are read only through declared, parameterized
-  Views.
-- Staff snapshots use a bounded single-entry read offered only for
-  collections that are the target of a declared interaction. Other staff
-  reads go through Views. This limits which records flow into a model
-  provider's context.
-- The version bound to an operation is the version the human saw. A newer
-  read is shown as "changed since the list" and requires a deliberate re-read
-  and review; it never rebinds silently. Background refresh never replaces
-  user edits.
-- Conflicts preserve user input. Uncertain writes (timeout, abort) are not
-  retried; the controller reconciles first.
-
-### 9. Projection ownership (D8)
-
-- Spec resolves D4 declarations during link. The RuntimePlan compiler emits
-  interaction descriptors (`plan.interactions`); this advances
-  `RUNTIME_PLAN_VERSION`.
-- The capability catalog, Admin operations and the web client all read
-  `plan.interactions`. HTTP-only staff Procedures never enter an MCP
-  projection.
-- Admin's inference is kept for one minor release. When an operation is bound
-  only by inference, Admin logs one deprecation warning pointing to
-  `Procedure.spec.target`. The next minor removes the inference.
-- Dynamic availability is advisory. No mutating handler runs to infer
-  availability.
-
-### 10. MCP Apps
-
-Implemented the way the official `add-app-to-server` and `create-mcp-app`
-skills describe:
-
-- `mantle-mcp` registers `ui://` resources with `registerAppResource` and
-  interaction tools with `registerAppTool` and `_meta.ui.resourceUri`.
-  App-only helpers use `_meta.ui.visibility: ["app"]` and are read-only.
-- Negotiation uses `getUiCapability`, per request. A 2026-07-28 request, or a
-  2025-era `initialize`, that declares no MCP Apps support gets no `_meta.ui`,
-  no resources and no app-only tools; everything else is unchanged.
-- A stateless 2025-era request after `initialize` carries no client
-  capabilities. It is treated as possibly supporting MCP Apps: it gets the App
-  metadata and the app-only tools, so hosts with MCP Apps can call them on
-  every request. Hosts without MCP Apps ignore the metadata but may list the
-  app-only tools to the model. This is why app-only tools must be declared
-  read-only.
-- Each surface is its own `McpServer`; staff resources never appear on public.
-- Resources hold reusable assets only: no caller data, no bearer. Per-call data
-  travels in `structuredContent`. Every app tool keeps its text `content`.
-- Opening an interaction is read-only; a mutation is always a separate
-  explicit `tools/call`. Canonical Admin keeps refusing framing.
-- **Preview (D10):** a staff-only, read-only, app-only `preview_entry` tool,
-  offered only when a Web renderer is mounted, returns the rendered HTML in
-  `structuredContent` under bearer authorization. The app shows it in a
-  sandboxed `srcdoc` iframe without `allow-same-origin`. The response is
-  `no-store` and the HTML never enters a shared resource.
-- **Hosts (D6):** CI runs the official `basic-host` and
-  `@modelcontextprotocol/client`; Claude and ChatGPT are verified manually per
-  release of this feature. No identical behavior across hosts is assumed.
-
-### 11. Human approval (D3)
-
-Deferred. UI confirmation and app-only visibility do not prove a human
-decision (Context 10). The handbook documents the pattern that works today: a
-`readOnly: true` Schema blocks generic writes, and an approval Procedure with
-only an HTTP Trigger and a `ctx.staff` requirement appears in Admin but in no
-MCP catalog. A test asserts an MCP-audience token cannot call an HTTP
-Trigger. Any future Core mechanism is enforced at the server boundary and
-binds target, input and version.
-
-### 12. Presentation boundary
-
-Renderer registries and `uiSchema` carry presentation only. Target, input
-mapping, authorization, side effects and version semantics are never declared
-there.
-
-## Consequences
-
-- One validated interaction definition drives Admin, application frontends
-  and chat hosts. Admin becomes a consumer of binding rules.
-- Applications that do not use MCP no longer carry any MCP code in Runtime.
-  Applications that do add `@aotter/mantle-mcp` and its SDK dependency;
-  measured on a minimal Worker, SDK plus zod is about 82 KiB gzip without Ajv.
-- MCP business errors change from JSON-RPC errors to `isError` results
-  (`breaking-change`), announced when adapters cut over.
-- Manifests that need entity-bound interactions for `ref` handlers or non-id
-  references adopt the D4 declarations. The sealed plan version advances, so
-  applications rerun `mantle generate`.
-- Hosts without MCP Apps support see only the additive `structuredContent`
-  and `outputSchema`.
-
-## Alternatives
-
-- **Keep the hand-written dispatcher and add MCP Apps to it.** Duplicates
-  the SDK, stays on one protocol version, and diverges from the official
-  ext-apps helpers.
-- **Validate in both the SDK and Runtime.** Two error shapes for one mistake,
-  and Ajv in every Worker.
-- **Put MCP Apps in Runtime with an injected provider.** Makes Runtime own a
-  protocol extension; the SDK already owns resources.
-- **More packages** (separate controller, kit, app packages). Three
-  versioning surfaces for one feature; subpaths give the same boundaries.
-- **Each surface derives relations itself.** Status quo; inconsistent.
-- **Bindings in `uiSchema` or an SDK-side registry.** A second, unvalidated
-  Manifest; rejected by #1109.
-- **Embed canonical Admin.** Requires weakening framing and cookie policy.
-- **Promote `lockedCollection()` to the execution contract.** A reference does
-  not prove mutation or locking.
-
-## How to apply
-
-Work follows epic #1110 as stacked PRs:
-
-1. #1126, #1127 — dispatcher factory; `structuredContent` and `outputSchema`.
-2. #1129 — `CapabilityCatalog` and `InvokeCapabilityUseCase`.
-3. #1130 — `@aotter/mantle-mcp`.
-4. #1131 — adapters, Admin and templates cut over; hand-written dispatcher
-   deleted.
-5. #1115, #1116 — grammar-revise; then #1120 interaction descriptors.
-6. #1121 — MCP Apps registration; #1122, #1123, #1124 — `@aotter/mantle-ui`;
-   #1125 — preview; #1119 — host matrix.

package/docs/adr/0030-store.md

@@ -1,40 +0,0 @@
-# ADR-0030: Store — one persistence object over one relational query AST
-
-**Status:** Accepted (#1151). Runtime slices shipped in 0.1.5 alphas; the grammar slice, the storage port and the removal of the parallel paths are decided for 0.2.0 by [ADR-0032](0032-store-centric-core-and-service-contract.md). Manifest authoring is amended by [ADR-0034](0034-store-is-authored-as-sql.md).
-
-**Date:** 2026-09-26
-
-## Context
-
-Entry persistence grew parallel paths: builtin-op use cases over `EntryRepository`, `ctx.writeAtomically` over `AtomicEntryWriter`, declarative Views with their own Filter AST, typed-query bindings, `runtime.entries` readers and the TTL sweeper. Each re-implements filters, OCC and SQL for every adapter, and the public vocabulary stops at id-addressed single rows. A consumer deleting one workout (swolhalla/swolhalla-mantle#15) expands it to two statements per row — about 51 queries for a small workout and 615 for a large one — or bypasses Mantle with raw SQL against Mantle-owned tables.
-
-## Decision
-
-**Store** is the single persistence object: `ctx.store` inside Procedures (bound to the caller) and `runtime.store` for trusted host code.
-
-- Queries are a closed **relational AST with a JSON shape**: SQL vocabulary and semantics (`select`/`from`/`where`/`orderBy`, NULL, subqueries), never a SQL string. Adapters compile it; values are always bound and identifiers come only from the linked Schema, so row scope and OCC can be injected structurally later.
-- Where grammar: `{ column: value }` is equality and sibling keys AND; `{ column: { eq, ne, gt, gte, lt, lte, like, in, notIn, isNull } }`; `and`/`or`/`not`; `in`/`notIn` accept a `{ select, from, where }` subquery. Columns are scalar Schema fields plus the native `id`, `status`, `version`, `createdAt`, `updatedAt`, `authorId`. `like` requires a string column, uses SQLite patterns and `\` as its escape character. `ne` follows SQL and excludes NULL.
-- Rows are flat (native columns next to Schema fields; the parser forbids clashes). Pagination is keyset `limit` (1–500) / `cursor` over one scalar `orderBy` column with `id` as tie-breaker. Declared-required fields can still be NULL in storage (publishing drafts validate partially; added columns start NULL), so NULLs sort last in either direction and the cursor carries a NULL value; no row falls between pages. A cursor is bound to its Schema, column and direction. TTL-expired rows stay hidden everywhere, including subqueries (ADR-0028).
-- `select` returns every lifecycle status: it is a trusted-handler read, not a public View. A Procedure exposed to callers must filter `status` itself (ADR-0025 applies to public Views only). `ne` and `not` follow SQL three-valued logic and exclude NULL; subqueries exclude NULL values so `notIn` behaves like its array form (a NULL left-hand value still matches `notIn` only when the list is empty, as in SQL). A `where` nests at most 16 levels and counts at most 256 objects, comparisons and subqueries in total. A Schema field named `and`, `or` or `not` cannot be filtered.
-- Storage support is an optional `StoreReader` capability; absent support is `RESOURCE_UNAVAILABLE`. Invalid queries are `INPUT_VALIDATION_FAILED`. A statement binds at most 100 values (D1's limit) on every adapter.
-- `store.view(name, options)` runs a named View with the caller's context; `store.id()` returns an entry id.
-- Runtime validates and snapshots Store queries before calling a storage adapter, including nested set-delete filters. Storage adapters retain dialect-specific limits and SQL compilation. `sweepExpired` is host maintenance and rejects every caller-bound Procedure Store, including an anonymous caller.
-- A Schema may declare one identity scope as `scope: { ownerId: "$ctx.user.id" }`, where the named field is a required scalar string and starts an index. Caller-bound Store reads and deletes structurally AND this predicate into every touched Schema, including subqueries. Insert fills the field and rejects a conflicting value; id-based update/delete check the row owner before hooks. A missing caller identity fails closed. `expect` counts affected rows after scope. `runtime.store` remains trusted and unscoped. Until declarative Views use Store IR, a declarative View over a scoped Schema must carry the same top-level identity predicate and auth gate. Native SQL Views remain a trusted escape hatch.
-
-Delivery order (each a reviewed PR): (1) `select`, `view`, `id` — this ADR's first slice; (2) `store.write(ops)` with `insert`/`update`/`delete`, `lock` and `expect`, set-based deletes over live rows only, rejected on Schemas with per-row delete hooks and on publishing Schemas (published entries are protected), replacing `ctx.writeAtomically`; (3) manifest grammar (handler `ref | store`, View `select`, Schema `scope`) and removal of the parallel read paths, under grammar-revise.
-
-## Consequences
-
-- One compiler per dialect replaces per-path SQL generators as later slices land; the SQLite family (D1, Bun, libSQL) implements it first, IndexedDB fails closed until it opts in.
-- Handlers get multi-Schema reads without raw SQL; Web and Admin keep `EntryReader` until the grammar slice.
-- Breaking changes are limited to 0.1.5-alpha APIs until the grammar slice, which ships with a `mantle-update` codemod.
-
-## Alternatives
-
-MongoDB-flavoured operators (`deleteMany`, `$in`) were considered first and rejected: every backend is relational, document semantics (nested paths, missing versus null) mismatch SQLite, and SQL is the vocabulary agents know best. SQL strings cannot carry injected scope and locks without a parser. Extending `writeAtomically` alone would add a fifth path.
-
-> **Amendment (ADR-0034):** Manifests now carry SQL, and the CLI's parser lowers it to this AST before it reaches any Worker. The Store API still takes no SQL string. The AST grows to what the SQL dialect needs (expressions, `CASE`, joins, aggregates, window functions, `RETURNING`, `ON CONFLICT`), and native SQL Views are no longer an escape hatch.
-
-## New folder rationale
-
-`usecase/store/` holds the Store facade that binds storage capability, the View executor and the id generator to one caller context; it has no storage or platform imports.

package/docs/adr/0031-host-cloud-core-contract.md

@@ -1,102 +0,0 @@
-# ADR 0031: Cloud supplies the host Core pin
-
-Status: Accepted for mantle-host protocols 2, 4, 5 and 6.
-
-The backend artifact includes `sdkVersion` and `sdkRevision` in its hashed
-bytes. The old host bundled a fixed Core revision. Cloud can run the previous
-Core release, so a host built from current Core cannot assume its own revision
-is the revision Cloud accepts. Asking only the backend upload grant is too
-late: that grant requires the artifact hash first.
-
-`save` now preflights the project and emits `cloud-host-contract` with the
-project ID. Control returns `{ projectId, core: { version, revision }, protocol }`
-from the deployed Cloud configuration. The script validates the project,
-40-hex revision and protocol minimum before packing. It persists the pin and
-backend hash together. Upload grants, HTTP responses and the frontend kit must
-echo the same pin; a difference fails before another upload and requires a new
-save. No static Core pin is shipped in the plugin. The script contacts only
-the granted Cloud HTTP endpoints; the contract comes through the Cloud MCP
-tool, like upload grants.
-
-Protocol 2 changes the MCP save sequence and requires both Core version and
-revision in `kit.json`. Control must provide the contract tool and pin echoes
-before this host script is offered to users. A future change to the MCP
-sequence, artifact bytes or validation meaning requires a protocol bump. A
-new Core release using these same rules changes only the Cloud contract pin.
-
-## Protocol 4: verified project Git source
-
-Protocol 4 changes the save sequence: an ordinary push and Cloud source receipt
-precede backend reservation. The receipt binds project/version, commit, target
-and Core pin. The helper reads clean committed Git objects, and Cloud checks
-the plan/YAML and retained ZIP against that commit. A changed Cloud pin requires
-a new source receipt before save; an immutable saved release keeps its stored
-bytes for review and rollback. The helper can reopen an existing project with
-an authorized short-lived read credential, without creating a new project.
-
-Artifacts repository provisioning, credentials, receipt records, resource
-cleanup and deployment policy belong to the Cloud service. Core vendors its exact
-helper artifact/checksum and documents the MCP workflow; it gains no provider
-adapter, SQL compiler, runtime wiring or new Manifest grammar. Client-built
-handlers/static files are not represented as server build attestation.
-
-## Agent orchestration and offline packing (#1368)
-
-Cloud MCP remains protocol 4 and owns lifecycle state and permissions. The plugin
-helper no longer mirrors candidate/deploy state or polls Cloud. Its public bundle
-contains safe Git source transport and offline backend/frontend/source packing.
-The agent discovers MCP schemas, records non-secret operation IDs for identical
-retries, and observes server state before publication. Packaging still uses the
-installed Core compiler; this is not a Core runtime/provider adapter change.
-
-`pack backend --contract -` validates the project and Cloud pin. `pack frontend`
-requires the backend commit and ready kit candidate, and emits immutable hashes.
-The agent checks these against reservations and uses native HTTP grant transport.
-Cloud admission and plan/archive verification remain unchanged; handler/static
-bundles remain client-built. The source transport also rejects secret-named files
-in reachable history, without claiming to scan source content for credentials.
-
-## Protocol 5: mandatory structural website acceptance
-
-A shared artifact validator runs in offline frontend packing and host admission,
-and the host repeats it before new publication. The uploader cannot disable it
-with an artifact flag or a self-reported checklist. A permanent canonical origin
-is bound to the immutable static upload receipt and checked against the selected
-site at reservation. Current rule/version and frontend hash bind the report;
-changing a candidate or bytes requires fresh evidence. Existing stored releases
-remain readable and rollback preserves their historical bytes.
-
-The plugin packer requires `--origin` and emits structured missing-check
-diagnostics. The upload MCP contract requires `canonicalOrigin`. This changes
-validation meaning and therefore increments the host protocol, not the Manifest
-grammar or Core runtime. The validator checks built HTML AST structure and
-metadata, deterministic sitemap/robots and SPA routing configuration without
-executing untrusted code or launching a browser. The host provides Admin, OTP
-and media wiring; artifact validation does not certify delivery, uploads,
-arbitrary authorization, visual behavior, content truth or dynamic HTML refresh.
-A REST-only host must report dynamic-content SEO unsupported.
-
-## Local preparation and additive continuation (#1381)
-
-The existing offline helper may run explicit application check/build argv arrays, pack a clean fixed commit and ordinarily push it in a single `prepare` entry. It returns source-admission arguments and deterministic artifact metadata; no Cloud lifecycle state, HTTP upload, polling or publication is added. Commands cannot silently commit source changes; dirty tracked output fails the existing clean-commit checks. Credentials stay in session memory/stdin. Native host responses may add continuation facts derived from their authoritative resource/lease rows; read-only backend status remains read-only. These additions do not change artifact bytes, admission rules or protocol 5 validation meaning.
-
-## Protocol 6: durable publication and read-only handoff (#1385)
-
-Publication changes the native MCP sequence: one accepted publication operation
-continues durably in Cloud, including recoverable provider waits, without an
-agent repeatedly advancing deployment steps. The agent observes authoritative
-deployment status until terminal; status reads never start or advance work.
-Interrupted acceptance is recovered through the same immutable operation and
-arguments, not a replacement candidate. Permission revocation and deterministic
-refusals remain terminal until their stated correction; background work does not
-retain a credential or turn a previous authorization into permanent authority.
-
-This sequence change requires protocol 6. A client must validate that contract
-before relying on autonomous publication; it cannot merely poll a protocol 5
-host and expect progression. Historical source/release artifacts keep their
-identity and rollback rules. The new sequence does not change Manifest grammar
-or claim server build attestation. Local preparation and builds stay in the
-agent environment; the helper gains no deployment scheduler or build container.
-An accepted operation, ready preview or expired preview is not evidence of a
-serving release or completed cleanup. Terminal state, access policy and literal
-publication URL come from Cloud's authoritative status.