@aotter/mantle 0.1.0-alpha.9 → 0.1.2-alpha.2

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

@@ -0,0 +1,150 @@
+# 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

@@ -0,0 +1,64 @@
+# 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

@@ -0,0 +1,30 @@
+# 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-861-admin-webmcp.md

@@ -0,0 +1,42 @@
+# ADR-lite #861: Staff MCP through the Admin session
+
+Status: Accepted for implementation following maintainer approval.
+
+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

@@ -0,0 +1,37 @@
+# ADR-lite 909: Mantle Admin UI kit export
+
+**Status:** Accepted
+
+## 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.