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

package/docs/adr/adr-lite-803-request-diagnostics.md

@@ -1,38 +0,0 @@
-# ADR-lite: request-scoped Cloudflare diagnostics
-
-Status: implemented diagnostic record for #803; real-auth controls and measured
-comparison acceptance belong to the #812 harness. This does not close the
-separate starter provisioning/Smart Placement portion of #803.
-
-Use native AsyncLocalStorage and a small versioned testing entry point instead of
-a global current-request counter or a configurable production telemetry system.
-Production mounts only check for an existing test context. With none, there are
-no diagnostic clock reads, binding wrappers, records, observers or response headers.
-Runtime, auth, role, catalog, dispatcher-build and dispatch retain their ownership
-and authorization order. The ordinary runtime-ready promise keeps its identity.
-
-Native D1 instrumentation sits beneath both Auth and Runtime and is idempotent.
-It preserves receivers, bind chains, first-column behavior and native objects in
-batches; no second driver observer is added for counting. Provider failures and
-unknown metadata remain visible. Request context is captured when an operation
-starts, so shared work belongs to its initiator. Catalog waiters inherit source
-classification and wait time without inheriting the owner's binding counts.
-
-The record freezes at response creation. Inclusive spans can overlap, and partial
-metadata or deferred work must not be presented as a full total. A test-only cloned
-MCP response supplies the JSON-RPC outcome without exposing its content; that
-inspection is outside totalMs but remains instrumentation overhead for HTTP timing.
-Observer errors never replace application results. D1/KV/R2 operations emit only
-counts, sizes with their source/coverage, and durations; object keys, SQL, caller
-identities and credentials never enter the record.
-
-R2 GET bodies stay native. Successful direct stream-to-PUT completion confirms
-payload bytes; canceled, incomplete and unconsumed reads remain unknown. This
-avoids losing R2's known-length stream property or hiding buffering overhead.
-
-Checks deliberately overlap MCP requests and share KV hit/failure loads, then
-retry after failure. Native I/O is counted once per owner, and denied requests
-leave unreached phases null. Additional checks preserve native D1 private receiver
-and batch semantics, sync/async observer failure, immutable deferred snapshots,
-R2 stream identity and partial-transfer uncertainty. The collector fixture labels
-its deterministic auth explicitly; it is not evidence of native-auth parity.

package/docs/adr/adr-lite-808-route-readiness.md

@@ -1,47 +0,0 @@
-# Route-owned Cloudflare readiness (#808)
-
-Status: accepted for the unreleased #806–812 implementation. Follows ADR-0019
-(preparation owns migrations) and amends ADR-0014's unconditional HTTP boot rule.
-
-The facade assembles immutable route projections once, then prepares only for
-routes that consume canonical storage. It retains one retryable preparation
-promise, the sealed plan and Better Auth's existing global AsyncLocalStorage,
-`ready` observation, failed-assembly eviction and HTTP `waitUntil` ownership.
-
-| Surface | Readiness, including an empty database |
-| --- | --- |
-| Consumer constant health, `/api/views` catalog | No content preparation. |
-| Static Admin shell and assets | No content preparation; incomplete Auth still fails closed as before. |
-| Manifest View/Trigger | Prepare before credential resolution, then use the same runtime invocation. |
-| Admin API, configured Auth base path, OAuth UI/discovery | Prepare before session/provider work. Auth tables share canonical migrations. |
-| MCP, including missing-token challenge | Prepare before the selected Auth verifier. A custom Auth implementation may require D1 even for a denied request; the facade cannot assume otherwise. |
-| Public page/list/discovery and favicon fallback | Their existing `ref.get()` starts preparation when content is needed. |
-| Consumer extension handlers | Call the supplied `getRuntime()` or `ref.get()` before using Mantle content or database-backed Auth. Pure handlers need neither. |
-| Queue/scheduled `getRuntime(env)` | Await both runtime preparation and Auth initialization, unchanged. |
-
-No deployment-time migration flag or KV readiness authority is introduced. A
-current database's first protected route needs one fingerprint SELECT; an empty
-or changed database performs canonical setup there. Concurrent first uses share
-that work. A failed preparation returns the facade's redacted 500, and later
-requests retry. Static availability is not a promise that data is ready.
-
-The pre-change full-facade fixture recorded 106 SQL operations for its empty-DB
-health request (its four Schemas include indexes), then 1 fingerprint operation
-for each new-state health/catalog/shell/challenge. These are statement counts,
-not network round trips. Its dry-run bundle was 3,921.40 KiB / 690.43 KiB gzip
-with Wrangler 4.124.0 and compatibility date 2026-07-08. Esbuild attributed
-1,342,428 emitted bytes to Better Auth, 76,078 to Admin, 24,624 to Web and
-203,130 to Runtime; the rest includes transitive libraries and adapter code.
-Byte attribution does not measure startup CPU. We retain static imports and
-immutable mount-time projections: deferring those modules has not yet been
-justified by a startup profile. The final #812 report owns the separate startup,
-preparation-wall and warm-dispatch measurements.
-
-Post-change full-facade workerd checks pass all 13 operation gates: empty-DB
-health and fresh-state health/catalog/shell perform zero **content** queries;
-the challenge retains its one fingerprint query. The fixture Auth is a stated
-stub. A separate real Better Auth regression records one eager oauthResource
-lookup while `ready` initializes; Better Auth 1.7.2 defers missing-table resource
-seeding to first access. Subsequent static requests perform no additional Auth
-queries. This background initialization is retained, not counted as eliminated
-content preparation or hidden behind a zero-total-SQL claim.

package/docs/adr/adr-lite-809-bounded-public-content.md

@@ -1,71 +0,0 @@
-# ADR-lite: bounded public content and complete discovery
-
-Status: implemented for #809; combined deployment measurements tracked in #812.
-Context: ADR-0010 translation joins, ADR-0019 sealed semantic storage, #792 Web
-transport/cache ownership. No manifest keys or remote Web SDK are introduced.
-
-## Decision
-
-Add the semantic `EntryReader.readPublishedPage` operation instead of silently
-capping generic `readPublished`. Forward pages sort by updatedAt and id descending,
-with default 50 / maximum 2,000 rows and a 1-MiB data-JSON budget. A single larger
-entry remains readable and advances the cursor. This budget covers the selected
-canonical data, excluding envelope bytes, joined parents, media and consumer HTML.
-SQLite uses indexed, bounded candidates, a running byte sum and lookahead before
-transfer to Worker memory. Exact locale plus shared entries are merged in SQL.
-Selected data fields retain JSON types and use one bound JSON field list, including
-for projections larger than D1's ordinary bind or SQL-function argument limits.
-
-The optional Web use cases return an explicit page object. Cloudflare mounts
-publish `Link: rel="next"` and map cursors to URLs. Web passes `nextPageUrl` to
-the list template; the host renders accessible navigation with its own language
-and design. The adapter does not rewrite template HTML. Existing templates must
-adopt this field to retain visible continuation. Web-owned llms composition
-retains its body link. An empty intermediate/final llms page remains traversable.
-Root llms reads each canonical page once and expands shared entries per locale
-without repeated canonical reads. Unknown/unmapped/no-content rows consume their
-place in the page; they do not prevent reaching later eligible rows.
-
-Sitemap parts project path metadata and default to 2,000 entries, expanding shared
-routes per locale. The index walks the same metadata-page boundaries as the parts,
-so a byte-limited part cannot cause skipped URLs. Small sites keep a single urlset.
-Additional routes appear only in the first part. A custom path resolver must declare
-its required data fields to obtain projection; otherwise full bounded data remains
-available. Protocol limits fail explicitly instead of silently truncating URLs.
-
-Translation lists request only the newest published parent per join value. Storage
-ranks matching IDs before loading their bodies, preventing duplicate historical
-parents from multiplying transferred rows. Missing/draft parents leave the child
-unchanged. Child data still wins and media resolution remains one batch per page.
-
-## Limits and alternatives
-
-Sitemap index generation is O(N) metadata work on an origin MISS. It retains one
-page and the index's URL list rather than all entry bodies; the protocol permits
-at most 50,000 parts. Persisted generation/part boundaries would require an explicit
-publication/invalidation owner and are deferred until index traffic justifies it.
-A hard `LIMIT 500` would lose discovery URLs and is rejected. Offset pages would
-make deep traversal grow with depth and are rejected. Entry caching would leave
-the cold materialization spike and stale-state questions unresolved.
-
-Pages reflect live canonical state, not a cross-request snapshot: publishing or
-changing sort keys during a crawl can move entries between pages. Browser-local
-IndexedDB shares the semantic cursor and output budget but still scans a local
-collection. Parent/media data and consumer template expansion have separate costs;
-there is no promise that arbitrary consumer rendering fits 1 MiB.
-
-## Verification
-
-Real SQLite tests walk the 18 combinations of 100/10,000/50,000 rows, 64 B/4 KiB
-body and 1/3/10 locales, comparing complete llms/sitemap URL sets. List transfer is
-21 rows at limit 20 in every case; 50,000 mixed rows and 10 locales retain all
-275,000 URLs. Tests cover tied sort keys, >1-MiB entries, JSON projection types,
-missing projected keys, parent duplicates/missing/drafts, child overrides, media
-batching and persistence-field privacy. HTTP tests walk visible continuations,
-empty final pages, sitemap indexes and staff-only preview behavior. The portable
-storage conformance suite checks new semantics across adapters.
-
-Wrangler-local records native D1 query/row work for list, llms and sitemap alongside
-existing readiness, View, Procedure and Admin gates. Node traversal CPU/RSS includes
-fixture/assertion costs and is not reported as Worker CPU. Combined #812 evidence
-will supply Worker CPU, heap, cache HIT/MISS, remote controls and placement results.

package/docs/adr/adr-lite-812-native-parity.md

@@ -1,150 +0,0 @@
-# ADR-lite: native and full-facade performance evidence (#812)
-
-Status: implemented; local gates passed. The deployment report and per-block
-budget verdicts are maintained in [PR #821](https://github.com/aotter/mantle/pull/821).
-
-The existing HTTP harness now records TTFB and full-body timing separately,
-response bytes, and bounded concurrent arrivals. `pnpm bench:wrangler` keeps the
-old row/query regressions and adds a native smoke matrix. `pnpm bench:parity`
-runs the larger matrix, real Better Auth PKCE/OTP/consent/JWT/DPoP issuance,
-revocation/role/replay denials, prepared D1 across fresh workerd processes, and
-R2 transfers. No token, cookie, proof, user ID, SQL, argument or object key enters
-the diagnostic record. Only the secret-protected synthetic fixture has control
-endpoints; never bind it to a consumer database or bucket.
-
-## Controls and boundaries
-
-| Layer | Work |
-|---|---|
-| F0 | Fixed fetch response; standalone `floor-worker.ts` measures module/bundle floor. R2 F0 performs HEAD only. |
-| F1 | Hono + native SQL and the same public payload; no authentication. |
-| F2 | Native Worker, shared real Auth/session/consent/fresh-role/DPoP checks, SQL compiler and validators, response envelope. MCP shares protocol dispatch and View execution; unmeasured mutations fail closed. |
-| M | Full `createMantleWorker`, same sealed plan, bindings, data and security policy. R2 uses the production storage commit adapter directly. |
-
-Protected parity is F2/M. The View and catalog response bodies must match, drafts
-stay private, and auth/protocol errors must fail correctly. Procedure input errors
-compare status/code, not complete diagnostic wording. Admin/Web are facade coverage,
-not a matched-native claim. R2 measures native stream metadata commits and failure/
-retry; D1 MediaAsset publication is covered by the separate #810 integration test.
-The shared comparison bundle intentionally keeps dependencies/configuration equal;
-it cannot measure the difference between standalone application bundle sizes.
-
-The planner runs outside workerd. Route/Schema/View axes each use 1/10/100/1,000;
-extra Schemas are unindexed to keep the index-count axis fixed. Each Schema is a
-native table, so the axis is not a claim that 1,000 simultaneous Schema tables
-are an advisable production design. Body/row axes use 64 B/4 KiB and
-100/10,000/50,000;
-locales use 1/3/10, MCP client concurrency uses 1/4/8, R2 uses 1/3/12 variants at
-1/64/256 KiB. Actual simultaneous arrivals can be below client concurrency. The remote fleet
-can add isolates during a batch. A request is repeat-in-isolate only after that
-exact workload previously completed there; overlapping first arrivals stay in
-the first-for-workload cohort. Two global warmups alone cannot prove a warm fleet.
-First requests retain their raw records and a bounded extra-six-statement setup
-allowance; repeat MCP requests must meet the exact two/three/four-statement gate.
-Parity summaries use repeat cohorts; first-for-workload does not necessarily mean
-cold module startup (another workload may already have used that isolate).
-
-## Stable gates and measured signals
-
-- Indexed public View: one statement and at most 100 available rows read at every
-  tested data size. MCP catalog: two statements (grant + fresh role), one KV GET;
-  View: three statements with Bearer, four with native DPoP replay reservation.
-- Selected Trigger: four segment lookups at every route count in the portable
-  regression; native last-route requests retain one statement at 1,000 routes.
-- Public HTML/llms: two warm statements and less than 1 MiB selected JSON. Sitemap
-  index remains explicit O(N) metadata work to enumerate complete part links.
-- R2: exactly N GET + N PUT, known full-body bytes, at most three transfers in
-  flight; a first-batch failure starts no later batch and a retry succeeds.
-- Fixture HTTP bodies at most 2 MiB; inspector heap after each batch at most
-  96 MiB. This is an observed JS heap ceiling, not instantaneous peak memory or
-  retained-after-GC heap. Custom application templates retain their own limits.
-
-The default fixture bundle gate is 4,500 KiB raw / 800 KiB gzip (measured
-3,699.93 / 647.98 KiB). The standalone F0 is 0.52 / 0.34 KiB; a 1,000-route
-fixture is 4,051.18 / 668.60 KiB. Larger manifest-axis builds are reported
-separately. Module startup profiles are a local diagnostic; actual deployed
-startup must remain below the provider limit and is recorded during acceptance.
-
-No cross-machine latency gate is used. CDP batch samples estimate local active JS
-(including warmup); they are not per-request or billing CPU. Native Tail CPU/wall
-are correlated by random request ID only in remote runs; unavailable timing stays
-null. D1 metadata sums cover only `metadataStatements`; native Auth `.first()` does
-not return rows/duration, and zero cannot substitute for that missing coverage.
-
-The 2026-09-08 full local run contained 2,697 measured requests / 144 cases, no
-unexpected HTTP status, max response 84,185 B, and max observed heap 67,103,480 B.
-The observed F2/M p50 full-body delta for the 50k-row/4KiB View was -0.347 ms
-(95% within-run bootstrap interval [-0.727, 0.128]); MCP catalog +0.903 ms
-[0.470, 1.070]; Bearer MCP View -0.578 ms [-1.235, 0.329]. These are localhost
-measurements, not a remote parity conclusion. Ten orthogonal route/Schema/View
-runs and both extra locale runs also passed. Self-review corrected a fixture that
-accidentally scaled indexes with Schemas, an English-only page assertion in the
-multilingual fixture, and missing D1 metadata incorrectly summarized as zero.
-
-## Remote difference budget (calibrated 2026-09-08)
-
-The first complete off-a block (05:44:20–05:57:16 UTC, SDK 1798e78) contains
-1,385 requests with 100% native CPU coverage, 46 first-for-workload arrivals and
-no unexpected status failures. Public cache returned MISS then HIT; the HIT
-had no invocation record. Warm F2/M CPU medians match at 0 ms health, 2 ms View,
-1 ms Procedure, 2 ms MCP catalog and 3 ms Bearer MCP View. DPoP medians differ
-by 0–1 ms; the largest within-run CPU delta upper interval is 2 ms. One hundred
-requests per layer/diagnostics mode measure roughly +1 ms median CPU for the
-collector itself on both layers. This is native millisecond-resolution telemetry.
-
-Freeze this initial budget before evaluating the on-a/off-b/on-b blocks:
-
-- At least 20 repeat-in-isolate samples per layer, equivalent successful payloads
-  and current authorization checks; expected denial cases are functional gates.
-- Upper 95% bootstrap interval for M minus F2 median platform CPU: at most 2 ms.
-- Upper 95% bootstrap interval for M minus F2 median full-body latency: at most
-  max(15 ms, 5% of the paired F2 median). Compare consistent placement contexts;
-  report changes in ingress/execution placement separately.
-- Exact warm statement/binding budgets and zero unexpected outcomes still apply.
-  Latency/CPU differences are a matched deployment acceptance budget, not an
-  absolute cross-machine CI timer gate. First-for-workload records stay visible;
-  the budget makes no blanket claim about cold setup or all native workloads.
-
-## Reproduction and remote acceptance
-
-Run from the repository root with built workspace dependencies:
-
-```sh
-pnpm bench:wrangler
-pnpm bench:parity
-BENCH_ROUTES=1000 BENCH_CASES=scaling pnpm bench:parity
-BENCH_SCHEMAS=1000 BENCH_CASES=scaling pnpm bench:parity
-BENCH_VIEWS=1000 BENCH_CASES=scaling pnpm bench:parity
-BENCH_LOCALES=en,fr,de BENCH_QUICK=1 pnpm bench:parity
-node scripts/summarize-wrangler-parity.mjs /path/to/report.json
-```
-
-For remote acceptance, provision dedicated synthetic D1/KV (R2 when enabled),
-put a random 32+ character BENCHMARK_KEY secret, and deploy the fixture with
-BENCH_REMOTE_RECORDS=1. Run with BENCH_ORIGIN, BENCHMARK_KEY, BENCH_ACCOUNT_ID,
-BENCH_PROFILE_NAME, BENCH_BLOCK and BENCH_PLACEMENT in the process environment.
-The runner uses Wrangler's existing named-profile authentication to open the
-same native trace-v1 API used by `wrangler tail`. It retains only the nonce-
-correlated diagnostic fields and native CPU/wall timing in memory, never request
-headers/body/URL, credentials or unrelated logs. The tail session is deleted at
-completion. No paid Tail Worker, sink database writes or elevated log API token
-is needed. Off-mode records also correlate platform CPU to measure overhead.
-
-PHSU has no R2 subscription; its remote run uses BENCH_SKIP_R2=1. R2 coverage
-comes from native workerd, with no remote R2 latency claim. A paid Tail Worker
-attempt was rejected by the provider, then replaced by the verified real-time API.
-
-Alternate off/on/off/on deployment blocks and BENCH_ORDER=reverse for the second
-pair. Record actual placement status, request `cf-placement` when supplied,
-ingress colo, deployment version, SDK/Wrangler/compatibility date, sampling window
-and errors. Origin timings force private/no-store; a separate probe requires a
-real public MISS followed by HIT with no invocation record. Local runs never
-invent HITs. A deployed Worker with existing D1 is labeled deployment-first.
-
-Use `wrangler deploy --dry-run --outfile <bundle>` followed by
-`wrangler check startup --worker <bundle> --outfile <profile>` for module startup.
-Record standalone F0, the full fixture and the actual packed consumer separately.
-Set the remote F2/M CPU/latency difference budget after collecting the baseline,
-then evaluate repeated blocks with bootstrap intervals, explaining shared-host
-and cross-request correlation. Smart Placement provisioning belongs to #803;
-INSUFFICIENT_INVOCATIONS is not evidence of a placement latency improvement.

package/docs/adr/adr-lite-823-home-statistics.md

@@ -1,64 +0,0 @@
-# ADR-lite: collection creation statistics on Admin home
-
-Status: proposed with #823; implementation stays in an unmerged demo PR.
-Context: ADR-0019 semantic storage and optional Admin composition.
-
-Add one optional `EntryReader.readCreationStatistics` read. SQLite/D1 implements
-it; custom adapters without it return an explicit unavailable state in Admin.
-The staff guard runs before storage access, and successful responses are private,
-no-store. The endpoint accepts only primary, visible collections and four range
-presets. No manifest keys, generic aggregation language or new cache port.
-
-Each card independently persists its range and interval/cumulative mode in
-`cms.preference.collection-statistics.<collection>`. Only preferences enter
-localStorage. The chart and CSV describe current retained rows by native
-`createdAt`, all statuses, with current `uiSchema.list.filterField` classification.
-Unknown values share an Other series. Deleted rows are absent: these are creation
-cohorts of retained rows, not an event log or historical inventory. Cumulative
-means a prefix sum inside the selected range, starting from zero.
-
-Ranges are 1h/5m, 24h/1h, 7d/6h and 20d/1d. Every interval is half-open; the last
-ends at the observation time. CSV uses ISO UTC bounds while chart labels use the
-browser's timezone. SVG steps preserve exact bucket extents without interpolation.
-The toolbar download exports the current card's mode, current total and series;
-CSV cells are quoted and formula-shaped headers are neutralized.
-
-## Aggregation and freshness
-
-A single SQL statement returns a total and sparse grouped counts from one SQLite
-snapshot. Each native Schema table carries `_mantle_created_at` and its own
-creation index. The range branch searches that index, and the total branch
-counts index entries. Other field columns stay in the database; only count rows
-reach the Worker.
-
-The existing Cloudflare KV decorator caches MCP site configuration, not entry
-queries. Reusing that key/projection would mix unrelated data and mutation
-ownership. Direct aggregation is sufficient for this demo: Wrangler-local with
-10,000 rows returned 897 bytes with one statement, 30,002 engine rows read and
-p50/p95 of 4.26/5.80 ms (10 samples). A real SQLite test also aggregates 50,000
-4-KiB rows into at most 40 count rows / 4 KiB and verifies immediate updates and
-deletes. These are local measurements, not remote latency guarantees.
-
-There is no server statistics cache to evict or repopulate after a racing write.
-Every Admin/MCP/Procedure committed write is visible on the next read, including
-subtype updates and deletes. React Query data stays in memory, becomes stale
-immediately, and refetches on mount/focus and every 60 seconds while the home is
-active. Successful UI mutations invalidate its common statistics query prefix.
-Changing only cumulative mode reuses the same count data without another query.
-
-`ponytail:` exact totals still take O(N) index work and filtered time ranges may
-read JSON for subtype grouping; returned bytes are bounded by bucket/enum count,
-not row count. If measured production read volume makes this expensive, add a
-transactionally maintained collection revision/projection and revision-keyed KV
-snapshots. Plain KV delete-after-write is insufficient because eventual
-consistency and racing miss fills can serve old aggregates. No cron, event store,
-generic cache framework or eager write-through aggregate is justified here.
-
-## Verification
-
-Runtime SQLite tests cover lower/upper edges, unknown subtype, collection
-isolation, zero rows, edits/deletes, invalid windows, range index use and 50k rows.
-Admin tests cover 401/403 before storage, invalid collection/range (including
-prototype names), all presets, no-store, and unsupported adapters. UI tests cover
-all preference combinations, zero filling, stacking, prefix sums and CSV safety.
-Browser QA covers independent per-card preferences, reload, both themes and CSV.

package/docs/adr/adr-lite-842-mcp-authoring.md

@@ -1,30 +0,0 @@
-# ADR-lite #842: Applicable generic MCP authoring
-
-Status: Accepted for implementation following maintainer approval.
-
-The staff catalog and dispatcher remain shared by remote MCP and Admin
-WebMCP (ADR-0014, ADR-0019, ADR-lite-861). No new manifest switch or tool
-registry is introduced. Adapters retain current staff-role verification;
-declared Procedures and Views retain their own authorization and guards.
-
-Generic lifecycle tools are offered only when at least one writable content
-Schema exists. Delete is offered only when a writable Schema exists. Read
-tools list actual collection names, lifecycle, searchable and sortable fields.
-Root readOnly remains the existing way to require Procedure-owned writes;
-declaring a Procedure alone does not disable normal authoring.
-
-Discovery is not enforcement: the dispatcher rejects absent catalog names,
-checks the target row for readOnly and lifecycle suitability, and binds
-per-collection updates to their declared collection before mutation. Unsupported
-lifecycle calls return CONFLICT with an explicit reason; wrong-collection IDs
-return NOT_FOUND. Existing status/OCC checks remain in the use cases.
-Generic staff tools also apply Admin's rank table at `tools/call`:
-contributor may create/update drafts; editor+ is required for lifecycle,
-delete, media, and operational record tools. Declared Procedures keep their
-own `requires` predicates. `tools/list` may still show editor tools to
-contributors; a guessed call is `AUTH_DENIED`.
-
-Compatibility: operational-only and read-only sites lose unusable generic
-tools. Clients must rediscover tools rather than retaining a global tool list.
-Mixed sites must choose a collection listed in the tool description. Public
-catalogs remain only declared capabilities and gain no collection metadata.

package/docs/adr/adr-lite-845-frontend-client.md

@@ -1,38 +0,0 @@
-# ADR-lite #845: frontend calls use the existing HTTP Trigger contract
-
-Status: Accepted for implementation under #845 and mantle-home #86.
-
-`mantle-web/client` is a browser-safe fetch client for declared public Views and
-HTTP Triggers. `mantle-web/client-runtime` projects that contract from the sealed
-RuntimePlan and binds the same client to `createMantleRequestHandler`, with a
-request-local principal. Local SSR makes no network call and invokes no internal
-EntryReader. Calls retain Trigger identity. No manifest grammar changes.
-
-The public contract uses wire names, input/output schemas and the plan fingerprint.
-View rows remain records: the existing View API does not promise a generated row
-schema. The generic response shape includes rows/page/show/hasMore. This is not a
-new generator or validation engine; Runtime still validates and authorizes.
-
-Remote callers inject fetch and a request-local token resolver. Clients never
-retry a mutation or follow redirects with credentials. Business diagnostics and
-OAuth challenge remain available in MantleClientError; network and abort errors
-remain native errors. The browser export imports no runtime or storage module.
-
-Cloudflare's opt-in frontendOrigins accepts exact origins for API CORS, exposes
-WWW-Authenticate and permits Authorization/Content-Type preflights. Cross-origin
-responses use no-store and do not enable cookie credentials. Cookie CSRF checks
-and configured bearer issuer/audience/scope checks remain the same. Host-owned
-OAuth/connection policy is independent of application revision. Existing Better
-Auth PKCE registration, consent and revocation remain the authority.
-
-In a provider composed with MCP, user grants for additional configured resources
-carry the same consent lineage and session binding as MCP grants. Verification
-reuses the current-consent/session check for those resources too; API JWTs cannot
-outlive revocation or become valid again on reconnect. OAuth discovery responses
-also receive the configured exact-origin CORS policy for public browser clients.
-
-Existing native public cache tags and purge handle same-Worker invalidation.
-External consumers start with private/no-store, or explicitly bound TTL; durable
-remote invalidation delivery remains the parent #792 contract and must be proven
-before advertising a stronger freshness guarantee. Cloud's integration includes
-the actual external consumer and browser evidence, not only this package change.

package/docs/adr/adr-lite-861-admin-webmcp.md

@@ -1,48 +0,0 @@
-# ADR-lite #861: Staff MCP through the Admin session
-
-Status: Accepted for implementation following maintainer approval.
-
-> **Amendment (0.2.0):** Admin answers no MCP. `POST /admin/api/mcp` is
-> removed; the browser calls a staff tool with `POST /admin/api/webmcp/<tool>`
-> and its input as JSON, which Admin runs as the staff MCP surface does, with
-> the session. The catalog is still the staff MCP surface's; an MCP client
-> with a token uses `/mcp/staff`.
-
-Admin WebMCP uses the canonical staff MCP catalog and JSON-RPC dispatcher.
-`GET /admin/api/webmcp` supplies the same tool definitions plus UI route hints;
-`POST /admin/api/mcp` carries MCP requests using the current Admin session.
-Both endpoints check the current mutable staff role. POST retains Admin's
-cross-origin mutation rejection and body limit. Procedure predicates still
-see a session credential, never a fabricated OAuth scope. Public/member MCP
-capabilities and HTTP-only staff procedures are not added to this catalog.
-This extends ADR-0014/0019 without changing manifest grammar.
-
-Descriptions, input schemas, OCC and error diagnostics come from the existing
-MCP catalog/dispatcher. Media tools appear only with media storage and declared
-purposes. Agents PUT binaries directly to the authorized upload URLs between
-create_media_upload and commit_media_upload; WebMCP carries no binary payload.
-
-Admin owns two UI-only tools: admin_get_context and admin_navigate. Successful
-operations invalidate query data and navigate when a known result target is
-available. Unknown custom operations stay on the current page. Failure never
-triggers navigation or an automatic mutation retry. Navigation input must be
-an Admin page, not an external URL or API/auth path.
-
-The green indicator appears after document.modelContext registration succeeds.
-Its dialog shows the registered tool catalog and uses Admin i18n with the
-established English fallback. The prompt tells the agent to inspect the catalog;
-tool descriptions own operation-specific guidance. Developer interface docs
-show the same live catalog. The initial translations include English,
-Traditional Chinese and Simplified Chinese.
-Registration uses AbortSignal lifetime cleanup. Browsers without WebMCP retain
-the existing UI. The browser API is feature-detected, not polyfilled.
-
-Only the explicitly marked, same-origin sandbox preview accepts the parent
-message-port tool bridge. It reuses the same executor even in browsers without
-native WebMCP. Canonical Admin refuses embedding and installs no parent bridge.
-Builder keeps reset/seed/observe and member/anonymous sandbox tests; owner
-staff calls traverse the iframe Admin executor and existing sandbox HTTP bridge.
-Timeout/cancellation does not imply a write was rolled back; reconcile before
-retry. Preview remains isolated from live network APIs.
-
-Reference: https://webmachinelearning.github.io/webmcp/

package/docs/adr/adr-lite-909-admin-ui-kit.md

@@ -1,37 +0,0 @@
-# ADR-lite 909: Mantle Admin UI kit export
-
-**Status:** Accepted; amended by [ADR-0029](0029-mcp-apps-interaction-contracts.md) (the kit moves to `@aotter/mantle-ui`, with a one-minor re-export from `@aotter/mantle-admin-ui/kit`)
-
-## Context
-
-Mantle applications need the Admin product's React/shadcn visual language
-without copying components or embedding the full Admin SPA. The Admin package
-previously exposed only static product assets and a server-side token string.
-Its same-origin `preview.html` contract remains the correct boundary for a
-complete embedded Admin or Developer UI.
-
-## Decision
-
-`@aotter/mantle-admin-ui/kit` exports the existing domain-neutral shadcn
-primitives and Mantle one-time-code input. `kit.css` contains their compiled
-Tailwind styles and complete Admin theme; `tokens.css` contains only the stable
-Mantle design variables.
-
-The kit does not export the Admin application, authenticated layout, router,
-queries, API client, or feature views. Those modules assume Admin routes and
-transport contracts and remain private. Consumers needing the complete product
-use the canonical Admin assets or the explicit same-origin sandbox preview.
-
-Copy-owned shadcn recipes may compose the public kit into working defaults.
-They are installed as source in the consuming application rather than exposed
-as another runtime framework. The first recipe is an email OTP page with
-optional legal links.
-
-## Consequences
-
-- Applications can share Mantle controls and visual tokens without depending
-  on Builder internals or duplicating Admin CSS.
-- The static Admin SPA remains unchanged and optional.
-- New public kit components require package-level contract and rendering tests.
-- Authentication and legal-consent policy remain application concerns, not UI
-  primitive behavior.