@aotter/mantle 0.2.0 → 0.2.1-alpha.2

package/docs/handbook/guides/agent-workflow-acceptance.md

@@ -8,10 +8,13 @@ author's replay remain useful; they do not establish independent acceptance. A
 fresh context is not enough if the author still chooses a workflow that mirrors
 the implementation. Every acceptance round gives the evaluator only a
 role and the entry points that role uses; it derives realistic tasks itself
-and the author scores them against a private rubric.
+and the author scores them against a private rubric. The first delivery gets
+full acceptance; after a repair, the change decides what
+[re-runs](#re-verify-what-a-repair-touches).
 If independent acceptance is not run, report `UNVERIFIED`; if a fresh evaluator
 or authorized test transport is unavailable, report `BLOCKED`; neither outcome
-is done.
+is done. Either way, report the evidence you do have in the
+[layered handoff](#report-done-ness-in-layers).
 
 Use the surface the intended user actually uses: a real browser session for
 Admin and application pages; for REST, an HTTP client plus the public API
@@ -110,7 +113,9 @@ the evidence.
    (at least once after a first look, again after its first attempts), executes
    it, and reports PASS/FAIL/BLOCKED per goal with readbacks, rejected writes,
    recovery attempts and interaction counts. Zero findings is a valid result.
-4. **One fresh agent per role, every surface.** For the default two roles, run
+4. **One fresh agent per role, every surface.** In the first round, and in any
+   round the [re-verification rule](#re-verify-what-a-repair-touches) widens
+   to all of them, cover every role and surface. For the default two roles, run
    an `admin` evaluator and a `user` evaluator in the same round on shared live
    data, in the brief's natural order. Between them they cover every surface
    the app exposes to each role: Admin for `admin`, pages for visitors and
@@ -124,24 +129,80 @@ the evidence.
    discoverable), P2 (friction) or P3 (suggestion), with evidence and the
    smallest repair. Separate a violated explicit requirement, a demonstrated
    defect and a newly inferred product wish; a wish is not permission to grow
-   the product.
-6. **Repair outside the evaluator's context, then start over.** The author keeps
-   the findings ledger, makes the smallest in-scope repair, adds focused
-   regressions (authorization, OCC, atomicity), and freezes a new revision.
-   The next round uses new agents and new fixtures and passes them nothing
-   from earlier rounds.
-7. **Converge or stop.** A round converges when it has no P0 or P1 and the
-   evaluators' observed results cover every rubric item visible to their roles;
-   items outside any role's view (another caller's isolation, hidden state)
-   need author regressions, reported under that label. Run at most three
+   the product. A goal the evaluator's own environment stopped (its tool
+   approval, sandbox or network, not an app refusal) is not a finding: record
+   it as an [environment block](#report-done-ness-in-layers) and rerun that
+   role once it is lifted.
+6. **Repair outside the evaluator's context, then re-verify what it touches.**
+   The author keeps the findings ledger, makes the smallest in-scope repair,
+   adds focused regressions (authorization, OCC, atomicity), and freezes a new
+   revision. The next round re-runs the roles and surfaces the
+   [re-verification rule](#re-verify-what-a-repair-touches) names, with new
+   agents and new fixtures, and passes them nothing from earlier rounds.
+7. **Converge or stop.** A round converges when it has no P0 or P1 and
+   evaluator-observed results cover every rubric item visible to their roles:
+   from this round, or reused from an earlier round under the
+   re-verification rule. Items outside any role's view (another caller's
+   isolation, hidden state) need author regressions, reported under that
+   label. Run at most three
    rounds. If the third still has a P0 or P1 or an uncovered rubric item, report
    BLOCKED with the remaining ledger, not acceptance. Setup cleans fixtures in
    `finally` after every round, including aborted ones.
 
 If a fresh agent or authorized test transport is unavailable, record independent
-acceptance as BLOCKED and report the scripted checks separately. Do not invent
+acceptance as BLOCKED and report the scripted checks on their own
+[layers](#report-done-ness-in-layers). Do not invent
 an independent result. Do not deploy or publish merely to obtain acceptance.
 
+Acceptance proves the behavior, not its speed. Once a round converges, the
+[performance skill](../../skills/performance/SKILL.md) decides which performance
+checks apply and holds them to their targets; a performance repair that changes
+what a role sees or can do returns here, scoped by the
+[re-verification rule](#re-verify-what-a-repair-touches).
+
+## Re-verify what a repair touches
+
+The first delivery always gets full acceptance: every role, every surface.
+After a repair, the change itself decides what runs again, not the finding
+that prompted it. Rounds before convergence are not accepted, so diff against
+evidence, not rounds: for each item you want to reuse, diff the current
+revision against the revision it was observed at, and pick the widest row that
+diff matches. A chain of repairs adds up; a page-only repair followed by a
+handler repair has to re-run what the handler repair reaches.
+
+| The repair changes | Re-run with fresh evaluators | May reuse |
+| --- | --- | --- |
+| Only presentation: page or Admin layout, CSS, copy, client-side display | Blind acceptance of the affected UI, for each role that uses it. A shared component or layout affects every page that renders it. | REST and MCP evidence from the same business-rule version |
+| A public contract: a tool or route description, input, output or error shape; the generated client or other `generated/` output it changes | That surface for each role that uses it, plus every UI that consumes it | Other surfaces at the same business-rule version |
+| Authentication, sessions, roles, `requires`, row or tenant scope | Every surface that the changed rule guards, for every affected role | Nothing those surfaces depend on |
+| A SQL Procedure or View, a `uniqueIndexes` entry, a check or lock, a migration that changes results, a handler's business rule | Every surface that reads or writes that data | Nothing those surfaces depend on |
+| A shared transport: the service entry, routing, the HTTP or MCP mount, a shared error envelope | Every surface on that transport | Nothing on that transport |
+
+The business-rule version is the revision of the manifests, SQL, migrations,
+handlers, authorization and service entry. A repair that changes none of
+them keeps that version, so evidence collected at it still stands for
+surfaces the repair did not reach. A repair that changes any of them
+starts a new business-rule version, and looking at the UI alone is not
+enough. One exception: a repair that only adds or drops a non-unique Schema
+`indexes` entry and its migration keeps the version. It changes speed, not
+which rows a read returns or which writes are refused. A `uniqueIndexes`
+entry, a check or a lock does change which writes succeed, so it falls in the
+SQL row. When the diff is unclear, widen.
+
+Every row still runs the author's regressions on the new revision (layers 1
+and 2 of the [layered report](#report-done-ness-in-layers)): `pnpm check`,
+`pnpm smoke`, `pnpm test` and the focused regressions for the repair.
+
+A re-run evaluator is as fresh as the first: a new agent, new fixtures, only
+its role and the entry points under re-test. Do not tell it what was
+repaired, what to check or what an earlier evaluator did. No previous
+answers, rubric or precomputed steps.
+
+For every rubric item that was not re-run, record the round and revision its
+evidence comes from and why the changes since that revision could not affect
+it. Never report a
+reused item as observed in a later round.
+
 ## Hand each role to its evaluator
 
 Setup signs each role in; the evaluator receives the role's access, never a credential it could reuse or widen.
@@ -185,7 +246,8 @@ Fill this in per role. It names the role and the doors, never the jobs:
 > first look at the interface and again after your first attempts. Then do the
 > work and report each goal as PASS/FAIL/BLOCKED with what you read back,
 > what was refused, what it cost you, and the smallest change that would have
-> helped. Report what you covered and what you could not reach; finding nothing
+> helped. For BLOCKED, say whether the service refused you or your own tools
+> or permissions stopped you. Report what you covered and what you could not reach; finding nothing
 > wrong is acceptable.
 
 The author separately verifies isolation between callers, stale-version
@@ -194,6 +256,50 @@ through authorized test fixtures. Do not grant the evaluator extra authority
 just to observe hidden state. Keep author regressions distinct from what the
 fresh agent actually observed.
 
+## Report done-ness in layers
+
+Report a handoff in four layers, in this order, each for the exact commit. Each
+layer proves something the others do not; a passing layer neither replaces nor
+is invalidated by another layer's result.
+
+| Layer | What it proves | Evidence |
+| --- | --- | --- |
+| 1. Generation and types | Manifests compile, `generated/` is current, the app typechecks and builds. No handler runs. | `pnpm check` (includes `generate --check`), `pnpm build` |
+| 2. Business rules and permissions | Handlers on a fresh local D1 over HTTP: each operation at its edges, refusals, caller isolation, visitor pages, MCP discovery, the Admin MCP App loading. Author's evidence. | `pnpm smoke`, `pnpm test`; [Local HTTP checks](local-testing.md) |
+| 3. Independent acceptance, per role | A fresh agent given only its role and entry points finds and finishes that role's work on each surface it uses. | Per role: the [rounds](#run-role-only-acceptance-rounds-until-they-converge) verdict and surfaces covered, naming the round and revision of any [reused](#re-verify-what-a-repair-touches) evidence |
+| 4. External platform | A real MCP host connects over OAuth; the production origin serves the deployed app. Local cookie sessions prove neither. | Host and version, identity, origin, observed result |
+
+Give each layer, and each role on layer 3, one status:
+
+- **verified**: the evidence above, with its command or host and result.
+- **failed**: the product is wrong. Name the failing check or finding.
+- **BLOCKED**: the layer could not run. Give the reason, what refused or is
+  missing, and what would unblock it.
+- **not applicable**: with the reason. Layer 4 is not applicable unless the
+  requested work includes an external host connection or a deployment.
+
+A layer nobody attempted is UNVERIFIED, as above. A block from the execution
+environment (an agent's approval policy refusing fictional writes, no browser,
+no network, a sandbox) is BLOCKED on that layer only. It is never a failed
+layer or a product finding, and it does not invalidate the evidence on other
+layers. Do not work around it by widening the evaluator's authority, faking a
+result or deploying; ask whoever controls the environment and rerun only that
+layer on the same revision.
+
+The work is done only when layers 1 to 3 are verified for every role and
+surface, and layer 4 is verified or not applicable. Partial evidence is still
+reported, layer by layer; it is not done:
+
+```markdown
+| Layer | Status | Evidence |
+| --- | --- | --- |
+| 1. Generation and types | verified | `pnpm check`, `pnpm build` at <commit> |
+| 2. Business rules and permissions | verified | `pnpm smoke` (<n> checks), `pnpm test` |
+| 3. Acceptance: admin | BLOCKED: evaluator's approval policy refused to create fictional records; needs <permission> | round 1 stopped at goal <n> |
+| 3. Acceptance: user | verified: CONVERGED in round <n> | member pages in round <n>; MCP reused from round <m> at <revision> (page-only repair) |
+| 4. External platform | not applicable: no deployment or external host requested | |
+```
+
 ## Record evidence in the existing issue or handoff
 
 Use ordinary Markdown; no new receipt schema or framework is required:
@@ -201,16 +307,20 @@ Use ordinary Markdown; no new receipt schema or framework is required:
 - Original brief, the private rubric, roles, environment, per-round budgets
   and round cap.
 - Setup assistance and what each agent could access; identify distinct rounds.
-- Per round: revision, each evaluator's derived goals (first list and
+- Per round: revision, business-rule version, the roles and surfaces re-run
+  and why (the [re-verification rule](#re-verify-what-a-repair-touches) row),
+  each evaluator's derived goals (first list and
   refinements) and criteria, the gaps between them and the rubric, per-goal
   PASS/FAIL/BLOCKED, actual readbacks and interaction references,
   request/page/tool counts
   and negative/recovery attempts, with their differing scope stated.
 - Findings ledger with P0–P3, owner, disposition, minimal repair and
   regression commands/results.
-- Coverage of each rubric item (evaluator-observed, author regression only, or
-  UNVERIFIED); the final CONVERGED / BLOCKED / UNVERIFIED verdict and rounds
-  used. Retain every failed report.
+- Coverage of each rubric item (evaluator-observed in this round,
+  evaluator-observed and reused from round `<n>` at `<revision>` with the reason,
+  author regression only, or UNVERIFIED); the final CONVERGED / BLOCKED / UNVERIFIED verdict and rounds
+  used, which is layer 3 of the [layered report](#report-done-ness-in-layers).
+  Retain every failed report.
 - Fixture cleanup result and every remaining limitation.
 
 Keep credentials, raw auth logs, full resource HTML and private operational

package/docs/handbook/guides/local-testing.md

@@ -7,8 +7,9 @@ description: Scripted local checks before acceptance - handlers over real HTTP,
 or a feature ready, run it on a fresh local D1 and drive it over HTTP. In an app written by `mantle init`, that is
 `smoke.mjs` on the shell's `smoke-kit.mjs` (`pnpm smoke`): it applies `generated/schema.sql` and `seed.sql`, starts
 `wrangler dev --local`, signs users in with the console email code and deletes everything afterwards.
-These checks are the author's evidence. [Independent acceptance](agent-workflow-acceptance.md) comes after them and
-does not replace them, nor they it.
+These checks are the author's evidence: layers 1 and 2 of the
+[layered handoff report](agent-workflow-acceptance.md#report-done-ness-in-layers). [Independent
+acceptance](agent-workflow-acceptance.md) comes after them and does not replace them, nor they it.
 
 ## What smoke covers
 
@@ -26,15 +27,59 @@ does not replace them, nor they it.
 - **Admin:** `pnpm build`, then `pnpm test` (`generated/admin-mcp-app.check.mjs`) loads the Admin MCP App in an MCP
   host and fails on a network error, console error or exception. It needs `playwright-core` and Chrome
   (`npx playwright-core install chromium`, or `MANTLE_TEST_CHROMIUM=<executable>`). With no browser it fails: report
-  it as BLOCKED, not skipped.
+  that check as BLOCKED on layer 2, not skipped and not as a product failure.
 
 Better Auth allows 3 one-time-code requests per minute per client IP; the kit gives each user its own
 `cf-connecting-ip`. Credentials come only from the kit's sign-in: a check never scrapes another session or builds a
 Caller by hand.
 
+## Seed data
+
+Create test records through the app itself: in `smoke.mjs` or the `pnpm accept` fixtures module, call the app's own
+REST, MCP or Admin operations as a signed-in user (`call("POST", "/admin/api/operations/create-event", { cookie: admin,
+body })`), or insert through the Store (`store(db, caller).collection("events").insert(...)`). Mantle then fills every
+system column (`id`, `version`, `created_at`, `updated_at`, `author_id`, and on a publishing Schema `status` and
+`published_at` through its publish Procedure) and enforces the Schema's checks, scope and references, exactly as for
+real data.
+
+Keep `seed.sql` for static reference data that no surface writes, such as categories or department budgets.
+`pnpm db:seed` and `smoke-kit.mjs` apply it as native SQL, which bypasses all of the above, so the seed sets each
+system column itself:
+
+| Column | SQLite and D1 (`cloudflare-d1`, `bun-sqlite`) | PostgreSQL | If the seed omits it |
+|---|---|---|---|
+| `id` | text, unique | text, unique | the insert fails |
+| `version` | `1` | `1` | `1` |
+| `created_at` | integer microseconds since the Unix epoch | `timestamptz` | the insert fails |
+| `updated_at` | integer microseconds; the same as `created_at` | `timestamptz` | SQLite and D1 store `0`: Admin shows 1970-01-01. PostgreSQL stores `now()` |
+| `author_id` | the creator's user id, or `NULL` for system rows | the same | `NULL`: under `restrict: { <schema>: "author_id = auth.uid()" }` no member sees the row |
+| `status` (publishing) | `'draft'`, `'published'` or `'archived'` | the same | `'draft'` |
+| `published_at` (publishing) | microseconds when `status` is `'published'`, otherwise `NULL` | `timestamptz`, otherwise `NULL` | `NULL` |
+
+A field- or owner-scoped Schema also needs its scope column. Use fixed instants for repeatable fixtures
+(`1767225600000000` is 2026-01-01T00:00:00Z), or the moment the seed runs (`unixepoch() * 1000000` on SQLite and
+D1, `now()` on PostgreSQL). For a publishing `posts` Schema on D1:
+
+```sql
+INSERT INTO posts (id, version, created_at, updated_at, author_id, status, published_at, title, body) VALUES
+  ('welcome', 1, 1767225600000000, 1767225600000000, NULL, 'published', 1767225600000000, 'Welcome', '# Welcome'),
+  ('draft-note', 1, unixepoch() * 1000000, unixepoch() * 1000000, NULL, 'draft', NULL, 'Draft', '# Draft');
+```
+
+The same rows on PostgreSQL:
+
+```sql
+INSERT INTO posts (id, version, created_at, updated_at, author_id, status, published_at, title, body) VALUES
+  ('welcome', 1, '2026-01-01T00:00:00Z', '2026-01-01T00:00:00Z', NULL, 'published', '2026-01-01T00:00:00Z', 'Welcome', '# Welcome'),
+  ('draft-note', 1, now(), now(), NULL, 'draft', NULL, 'Draft', '# Draft');
+```
+
+A seed is local test data; never apply it to an existing production database.
+
 ## Account for every surface
 
 In the app's README or handoff, list each declared surface (Admin, each MCP endpoint, REST, each visitor page type)
 as verified (command, identity and result), intentionally not exposed, or UNVERIFIED with a reason. Local cookie
-sessions do not prove an external MCP host's OAuth connection or a production origin; record those separately.
-Record the commands and their results for the exact commit, fix failures and rerun the affected checks.
+sessions do not prove an external MCP host's OAuth connection or a production origin; those are layer 4. Record the
+commands and their results for the exact commit in the layered report, fix failures and rerun the affected checks. A
+check the environment prevented (no browser, no network, a refused approval) is BLOCKED with its reason, not failed.

package/docs/handbook/guides/mcp-apps.md

@@ -33,6 +33,46 @@ passed through as the resource's `_meta.ui`. `domain` is the dedicated sandbox
 origin for hosts that serve each App from its own origin; use the form that
 host documents.
 
+### Tool metadata and result `_meta`
+
+A hand-built kernel `Tool` may set `meta`, merged into its `_meta` in
+`tools/list` with what App links produce: the top level shallowly, `ui` one key
+deep. Use it for keys such as `ui.visibility`, `ui.resourceUri` with
+`openai/outputTemplate`, or `openai/fileParams`. A value that contradicts an App
+link (another `ui.resourceUri` than the `renders` resource, or a visibility other
+than `["app"]` on an `appOnly` tool) fails when `mcp()` is constructed.
+`meta: { ui: { visibility: ["app"] } }` hides any tool, a Procedure included,
+from clients that declare no MCP Apps support, as `appOnly` does for Views. It
+is a listing hint only: `tools/call` still runs every identity, scope, `check`
+and `authorize` decision, so an App-only write is authorized like any other.
+
+A `run` may return `withResultMeta(data, meta)` from `@aotter/mantle/mcp`. The
+result's text and `structuredContent` are built from `data` exactly as before;
+`meta` goes only into the result `_meta`, beside `net.aotter.mantle/tool`, which
+it cannot replace. Hosts give result `_meta` to the App, not the model, so a
+signed upload URL belongs there:
+
+```ts
+import { withResultMeta, type Tool } from '@aotter/mantle/mcp';
+
+declare function signUpload(caller: unknown): Promise<{ id: string; url: string; headers: Record<string, string> }>;
+
+const uploadTarget: Tool<unknown> = {
+  name: 'upload_target', surface: 'public', description: 'Prepare an upload.', closed: true,
+  meta: { ui: { visibility: ['app'] } },
+  inputSchema: { type: 'object', additionalProperties: false }, validate: raw => raw as Record<string, unknown>,
+  run: async (_db, caller) => {
+    const upload = await signUpload(caller);
+    return withResultMeta({ id: upload.id }, { uploadUrl: upload.url, requiredHeaders: upload.headers });
+  },
+};
+```
+
+`callTool` and `callToolLazy` return the wrapper itself, `{ data, _meta }`.
+A caller that forwards a result to a model, such as an application's own agent,
+must forward only `data` and drop `_meta`, or the signed URL leaks through that
+path. A thrown error still produces the standard diagnostics result.
+
 ## Package and application ownership
 
 Core (`@aotter/mantle`) owns tools, resources, endpoint links and server authorization,