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

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

@@ -0,0 +1,232 @@
+# Independently accept a user-facing workflow
+
+Before reporting any user-facing deliverable as done, exercise it from the
+user's position with a fresh end-user agent. This applies to Admin pages and
+customisations, application pages and web routes, REST APIs used by clients,
+MCP tools and MCP Apps. Generation, typechecking, scripted smoke tests and an
+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.
+If independent acceptance is not run, report `UNVERIFIED`; if a fresh evaluator
+or authorized test transport is unavailable, report `BLOCKED`; neither outcome
+is done.
+
+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
+reference and base URL a real client developer receives; an MCP client for
+tools; and the real MCP App host/AppBridge flow for Apps. This is an
+application-authoring practice, not an SDK runtime service or a new test runner.
+Use the project's existing local setup, normal authorized sign-in and isolated
+fixtures. Setup hands over the role's established browser session or client
+token; the evaluator never acquires or widens credentials. Give it only its
+authorized surface. Do not enable extra routes, roles or generic writes to make
+the exercise pass.
+
+## Audit MCP tool design before implementation
+
+Start with the original user brief, business role and explicit requirements,
+not a list of CRUD endpoints or a task derived from what you implemented.
+Before writing manifests or handlers, record the intended jobs and assumptions
+in the existing design note. The capability map feeds the private rubric
+(below); an evaluator receives only its role and chooses its own tasks and
+observable success criteria. Do not expand application scope or authority
+merely to satisfy an evaluator's newly inferred product wish.
+
+In the application's existing design note or issue, map each goal step to its
+proposed public capability: discovery inputs, returned IDs and evidence, allowed
+caller, write/transaction boundary and recovery. Mark missing capabilities or
+unresolved contracts as gaps before writing manifests or handlers. Review the
+following rubric against that map:
+
+| Design question | Required contract or explicit gap |
+| --- | --- |
+| Can the agent locate the right record? | Bounded search/filter inputs, stable IDs, deterministic cursor paging and sensible limits. It must not scan every list or guess an ID from a display label. |
+| Can it choose an eligible relation? | Finding an ID is not proof of business eligibility: verify the role, state and ownership required by the relationship. Return enough labels to distinguish same-name choices before writing. |
+| Can it correct an ordinary mistake? | State how to amend, clear or replace optional fields and relations, and how duplicate records are detected or reconciled. Test omitted, null and empty inputs against that contract; existence and type checks alone do not establish business validity. Express conditional-required inputs with the supported [input rules](../reference/surface.md) before writing handler checks. |
+| Can it read a complete business result? | ID-based detail/readback under the intended caller, including every relation the goal creates or changes. A parent list is not proof of its child/contact/state details. Distinguish absent/inaccessible from incomplete evidence. |
+| Can it verify a create or update? | Return the backend entity ID, actual committed version where applicable, and a safe result summary or a documented authorized readback. State the exact result nesting. Echoed input or the submitted `expectedVersion` is not proof of committed state. Specify PATCH versus full replacement and omitted/null-field semantics so an update cannot erase unseen fields. |
+| What does a version protect? | Name its entity/snapshot scope; a parent version does not imply child rows or aggregates are unchanged. Use the reviewed observed version for OCC, define conflict behavior and preserve the user's proposed changes without silently rebinding/retrying. |
+| Can it complete a business transition? | Name permitted source/destination states, preconditions, related effects and final readback. Prefer an outcome-oriented operation when arbitrary field updates would leave the workflow unfinished. |
+| What commits together? | Define the native Procedure/Store atomic boundary. Separate tool calls are independent; describe partial success and deliberate compensation. Do not imply that an agent can roll back earlier calls or that compensation is always possible. |
+| Can it interpret refusal and failure? | Document success and structured diagnostic/error envelopes, including MCP `isError`; HTTP 200 or a wrapper's transport success is insufficient. Inspect raw MCP diagnostics separately from host-visible wrapper errors; a wrapper label alone does not locate a runtime defect or require global error normalization. Missing relations, stale versions and denied callers need meaningful refusals without leaking another caller's records or native internals. |
+| What happens after a duplicate or uncertain write? | State whether idempotency exists, its key/scope/lifetime when supported, or that repeated successful calls may repeat effects. Provide an authorized reconciliation route for timeout/unknown outcomes; never automatically retry an uncertain write. |
+| Can it explain amounts correctly? | Declare currency, stored/wire units, exact-value representation, rounding and whether null means unknown. Label every ratio's numerator and denominator: cost/budget, sales/budget and gross/sales are different measures. |
+| Does data remain usable without an App? | Keep ordinary reads data-only; attach a renderer deliberately for interactive inspection, with structured/text fallback. Rendering must not write or imply approval. Host catalog refresh, OAuth and real client/UI behavior have separate acceptance; descriptions cannot force generative UI layout. |
+| Does every step respect the user's authority? | Verify least privilege, tenant/owner scope, allowed fields, relation access and negative cases on the server. Tool visibility, annotations, descriptions and UI confirmation never grant permission. Use authorized disposable fixtures and a cleanup owner without widening production writes/deletes. |
+
+A design passes this audit only when each required goal step has a supported
+capability and verifiable output/recovery; preserve unresolved gaps and owners.
+The audit is a design review, not execution evidence. Record intentional
+exclusions, but keep an unmet explicit user requirement unresolved until the
+user changes its scope; do not redefine it as optional to make a round pass.
+Reuse the installed version's Views,
+Procedures, Store and surface contracts; a missing business tool is not by
+itself an SDK runtime defect.
+
+For simple creates/partial updates, prefer a declared Store-backed `ref`
+Procedure: await the caller-bound Store write, return a safe allowlist with its
+actual returned ID/version, and keep `requires` plus generated input validation
+at invocation. A transaction-bound write result remains provisional until the
+outer transaction commits; publish success only after that boundary completes. Store row policy alone is not Procedure authorization. Define
+omitted versus null patch semantics; never fill unseen fields with defaults.
+Keep SQL Procedures for atomic stock changes, conditional state transitions and
+related writes. A TypeScript pre-read does not replace an atomic WHERE/CHECK;
+D1 supports batch, not an interactive transaction or consuming an earlier batch
+result. See the [Store write guide](typed-queries.md#prefer-store-backed-ref-procedures-for-simple-writes).
+
+Then implement the minimum contract and run generated/type, authorization,
+atomicity and other relevant regressions. Follow the independent acceptance
+rounds below before claiming the user-facing work is done. Keep the author's
+capability map and worked call sequence out of the fresh agent's prompt: an MCP
+evaluator must discover the workflow from public tool descriptions and results.
+
+## Run role-only acceptance rounds until they converge
+
+The evaluator gets a role, not a task list. It works out what that role needs
+to get done from the interface itself; what it derives, and what it misses, is
+the evidence.
+
+1. **Write a private rubric first.** From the original brief, the author lists
+   what each role must be able to do on each surface (Admin, application
+   pages, REST, MCP), with observable success criteria, explicit exclusions
+   and the authority each role must not have. The rubric stays with the author;
+   no evaluator ever sees it, its wording or its order.
+2. **Hand each evaluator only its role.** Supply the business role and context
+   in one or two sentences, the entry points that role really uses (Admin URL,
+   site URL, REST base URL and API reference, MCP endpoint), a signed-in browser
+   session or client token from setup, the interaction/time/write budget,
+   permitted fake-data actions and what is forbidden (source, SQL, internal
+   docs, the database, other roles' credentials, blind retries of uncertain
+   writes). Withhold the brief's requirement list, capability maps, tool names,
+   precomputed IDs and earlier reports. Seed realistic fixtures: other owners'
+   records, several states and more than one page of results. Run the evaluator
+   outside the project directory, without Mantle skills or project instruction
+   files, and record that isolation.
+3. **Let it derive the work, then do it.** Before any interaction the evaluator
+   writes down what this role would need to accomplish and how it would know
+   each one succeeded. It then refines that list as it discovers the interface
+   (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
+   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
+   members, REST for client developers, MCP for both roles' AI clients. A
+   surface no evaluator reached stays UNVERIFIED.
+5. **Score against the rubric outside the evaluator.** The author compares the
+   evaluator's derived goals and results with the rubric. A rubric item the
+   evaluator never thought of is itself a finding: the interface did not make
+   that job discoverable. Classify every finding P0 (data loss, authority or
+   integrity defect, uncertain write), P1 (a rubric item FAIL, BLOCKED or not
+   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
+   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
+an independent result. Do not deploy or publish merely to obtain acceptance.
+
+## 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.
+This is the authorized test transport the BLOCKED rule above refers to.
+
+- **Local session URL (the app shell's default).** `pnpm accept` in an app written by `mantle init` starts the app
+  on a fresh local D1, signs the admin in, runs an optional fixtures module, signs the user in and prints one local
+  URL per role. Each URL forwards every request with that role's session and refuses `/api/auth/*`. Give the
+  evaluator only its URL: MCP at `<url>/mcp` (user) or `<url>/mcp/admin` (admin) for any streamable HTTP MCP client,
+  Admin at `<url>/admin` and member pages at `<url>/` in a browser, REST at `<url>/` with no credential. An evaluator
+  without an MCP client uses `node accept.mjs mcp <endpoint> [tool [json]]`, which prints the raw result including
+  `isError`. The app README's "Independent acceptance" section shows the fixtures module.
+- **An external MCP host over OAuth.** To accept the connection a real client uses (Claude, ChatGPT or another host
+  that supports MCP OAuth), deploy or tunnel the app as you would for that host, add `<origin>/mcp` or
+  `<origin>/mcp/admin` to the host in setup, and complete sign-in and consent as the role's fictional identity. The
+  evaluator then works in that already-connected host. Its token stays in the host; the evaluator neither sees nor
+  requests it. Record this as OAuth evidence, separate from the local session URL (see
+  [OAuth](oauth.md)).
+
+Either way, the evaluator's prompt names the URL or the connected host, never a cookie, token or sign-in step.
+
+If you cannot start a fresh agent yourself (for example, you are a subagent without that tool), prepare everything
+else: the rubric, the fixtures module, `pnpm accept` running, and one filled-in role prompt per role (below) naming
+its URL. Hand the prompts to whoever can start agents (the person or the orchestrating agent), keep the app running,
+and report acceptance as BLOCKED with the prompts attached until their reports come back. Score those reports as
+usual.
+
+## Give the agent a role
+
+Fill this in per role. It names the role and the doors, never the jobs:
+
+> You are [role, for example "a purchasing manager"] at [business context in
+> one sentence]. You use [entry points for this role from `pnpm accept`: Admin
+> URL, site URL, REST base URL and reference, MCP endpoint]; setup has already
+> signed you in as [fictional identity]. Budget: [interactions/time/writes]. You may create and
+> change fictional records; [owner] cleans up. Do not read source, internal docs
+> or a database, use anyone else's access, or retry a write whose outcome you
+> do not know.
+> First, write down what someone in this role needs to get done with this
+> service and how you would tell each one worked. Refine that list after a
+> 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
+> wrong is acceptable.
+
+The author separately verifies isolation between callers, stale-version
+refusal, unknown-outcome handling and effects hidden from the evaluator's role
+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.
+
+## Record evidence in the existing issue or handoff
+
+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
+  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.
+- Fixture cleanup result and every remaining limitation.
+
+Keep credentials, raw auth logs, full resource HTML and private operational
+details local/private; publish only sanitized contract evidence. Do not claim a
+call-cost improvement when rounds exercise different negative/discovery cases.
+Version fields usually describe an entity row, not all related aggregates;
+state money units and the denominator of any budget or margin calculation.
+
+## Keep surface evidence distinct
+
+Evidence from one surface does not prove another. Tool metadata and protocol
+discovery do not prove that an MCP App rendered in its real host through
+AppBridge; a REST response does not prove the Admin or application page; and a
+browser rendering does not prove an external client can use the REST contract.
+Record the actual browser, client or host version, identity, observed interface
+and behavior for the deliverable under acceptance. Keep data results available
+without Apps; descriptions cannot force a host's generative UI layout. Local
+cookie-session acceptance, OAuth client integration and long-term renewal
+likewise require their own evidence when they are part of the requested work.

package/docs/handbook/guides/email.md

@@ -0,0 +1,86 @@
+# Transactional email
+
+Import the optional email port from `@aotter/mantle/email`. Mantle supplies
+`EmailSender`, `EmailSendArgs`, English `signInCodeEmail`, `signInLinkEmail`
+and `adminInvitationEmail` templates, and `ConsoleEmailSender` for local
+development. Applications select and configure their sender and Better Auth
+plugins.
+
+`send({ to, subject, text, html?, locale, category? })` returns `Promise<void>`.
+The templates return `{ subject, text }`, with the same English text as 0.2;
+they do not translate or consume `locale`. Pass the recipient's locale through
+to the sender, which can select localized templates. Existing categories are
+`auth.email-otp.<type>`, `auth.magic-link.sign-in` and `auth.admin-invitation`.
+
+## Application wiring
+
+```ts
+import { emailOTP } from "better-auth/plugins";
+import { hashEmailOtp } from "@aotter/mantle/auth/hardening";
+import { signInCodeEmail, adminInvitationEmail, type EmailSender } from "@aotter/mantle/email";
+
+const locale = (request?: Request) =>
+  request?.headers.get("accept-language")?.split(",")[0]?.split(";")[0]?.trim() || "en";
+
+// Include this plugin in the app's Better Auth options.
+export const emailPlugin = (sender: EmailSender, secret: string) => emailOTP({
+  storeOTP: { hash: otp => hashEmailOtp(secret, otp) },
+  sendVerificationOTP: ({ email, otp, type }, ctx) => sender.send({
+    to: email, ...signInCodeEmail(otp), locale: locale(ctx?.request),
+    category: `auth.email-otp.${type}`,
+  }),
+});
+
+// Use the configured, trusted application origin, never an incoming Host or
+// Origin header. The application grants the OSS "admin" role before sending.
+export const inviteEmail = (sender: EmailSender, origin: string, to: string, language: string) =>
+  sender.send({
+    to, ...adminInvitationEmail("admin", new URL("/admin/sign-in", origin).href),
+    locale: language, category: "auth.admin-invitation",
+  });
+```
+
+For magic links, pass Better Auth's generated URL to `signInLinkEmail(url)`;
+configure Better Auth's `baseURL` and `trustedOrigins` to prevent untrusted
+callback destinations. Templates preserve their input as plain text and never
+interpret it as HTML. If a sender supplies `html`, it owns escaping untrusted
+text and attributes and validating link destinations. Pass structured fields
+to the provider; do not interpolate them into raw MIME headers.
+
+Use `new ConsoleEmailSender()` only in explicitly selected local development.
+It logs recipients, codes and links and sends nothing; never select it in
+production or log live messages in a production sender. Provider failures
+reject the promise; the application owns error handling and retry policy.
+
+**Never let the response wait for the send.** Better Auth calls
+`sendVerificationOTP` for `email-verification` and `forget-password` only when
+the user exists, so a response that waits for the provider reveals whether an
+account exists. Configure Better Auth's `advanced.backgroundTasks.handler` (on
+Workers, `ctx.waitUntil`) so the send runs after the response, as 0.2 did; the
+app-owned auth template wires it.
+
+## Cloudflare Email Service binding
+
+Use a verified sender and a Cloudflare Email Service `send_email` binding.
+The binding composes the message natively; no mail SDK or MIME builder is needed.
+
+```jsonc
+{ "send_email": [{ "name": "EMAIL" }] }
+```
+
+```ts
+import type { SendEmail } from "@cloudflare/workers-types";
+import type { EmailSender } from "@aotter/mantle/email";
+
+interface Env { EMAIL: SendEmail; EMAIL_FROM: string }
+export const emailSender = (env: Env): EmailSender => ({
+  async send({ to, subject, text, html }) {
+    await env.EMAIL.send({ from: env.EMAIL_FROM, to, subject, text, html });
+  },
+});
+```
+
+The English example ignores `locale` and `category`; a localized provider may
+use both. The binding's verified sender and recipient restrictions still apply.
+This example does not provision a sender, enable an auth method or send mail
+without application wiring.

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

@@ -0,0 +1,40 @@
+---
+description: Scripted local checks before acceptance - handlers over real HTTP, public pages without JavaScript, MCP discovery, Admin's MCP App, and how to account for every surface.
+---
+# Local HTTP checks
+
+`pnpm check` proves that the manifests compile and the app typechecks; it runs no handler. Before you report an app
+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.
+
+## What smoke covers
+
+- **Every Procedure and HTTP Trigger the app declares:** valid input with the expected status and body (a status
+  below 500 is not success), invalid input, an anonymous call to a protected operation, the other role, and the
+  stored result read back. Use only the generated routes, inputs and permissions.
+- **Business rules at their edges:** the oversell, the stale `expectedVersion`, the second approval, a refusal that
+  must leave nothing behind (check the rows with the kit's `sql`), and two concurrent calls where a race matters.
+- **Each caller sees only its own rows:** a second member's records are absent from lists and refused by id.
+- **Visitor pages:** the checks in [public pages](public-pages.md#check-before-you-report-done), requested without
+  JavaScript.
+- **MCP:** `assertMcpDiscovery(endpoint, { tools, headers })` from `smoke-kit.mjs` for `/mcp` and `/mcp/admin`, with
+  the expected tools taken from generated code (the app-shell README shows it), plus a separate assertion that an
+  anonymous call and a member calling `/mcp/admin` are refused. Discovery needs no business `tools/call`.
+- **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.
+
+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.
+
+## 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.