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

package/docs/handbook/reference/diagnostics.md

@@ -1,193 +1,84 @@
 ---
-description: The Diagnostic shape and the complete closed code catalog — every validate, boot and runtime code, what it means and the HTTP status it maps to.
+description: The structured Diagnostic shape, the wire error envelope, HTTP statuses, and the diagnostic codes Mantle 0.2.0 raises from mantle generate, boot and run time.
 ---
 # Diagnostics
 
-Every failure in Mantle is a `Diagnostic`: one structured object with a stable code, the phase that produced it and a JSON Pointer to the offending place. The catalog is closed — adding a code is a grammar-revise event — so an agent can group by `code` or filter by `phase` without parsing prose. This page is the whole catalog. The rules that raise each code live on the atom pages: [Manifest](./manifest.md), [Schema](./schema.md), [View](./view.md), [Procedure](./procedure.md), [Trigger](./trigger.md), [Authorization](./authorization.md) and [Site config](./site-config.md).
-
-## Shape
+Every refusal is a `Diagnostic`, from `mantle generate` to a REST call:
 
 ```ts
 interface Diagnostic {
-  readonly code: DiagnosticCode;
-  readonly phase: "validate" | "test" | "boot" | "runtime";
-  readonly severity: "error" | "warning";
-  readonly path: string;
-  readonly source?: SourceLocation;
-  readonly value?: unknown;
-  readonly expected?: string;
-  readonly candidates?: readonly string[];
-  readonly suggestion?: string;
-  readonly message: string;
-  readonly failure?: {
-    readonly outcome: "not-applied" | "partial" | "unknown";
-    readonly retry: "never" | "after-change" | "safe" | "reconcile";
-    readonly resource?: string;
-  };
+  code: DiagnosticCode;          // the catalog below
+  phase: "validate" | "boot" | "runtime" | "test";
+  severity: "error" | "warning";
+  path: string;                  // where: a manifest pointer, a route, a field
+  message: string;               // for people; never parse it
+  source?: { sourceId, documentIndex, path, … };   // the manifest file and document
+  value?: unknown; expected?: string; candidates?: string[]; suggestion?: string;
+  failure?: { outcome: "not-applied" | "partial" | "unknown"; retry: "never" | "after-change" | "safe" | "reconcile"; resource? };
+  conflict?: { opIndex?: number; reason: "lock" | "expect" | "unique" };
 }
 ```
 
-| Field | Meaning |
-|---|---|
-| `code` | One of the codes below. Unprefixed `UPPER_SNAKE`. |
-| `phase` | Which loop produced it. The same code may appear in more than one phase when it names the same root cause. |
-| `severity` | `error` withholds the result of its stage; `warning` does not. |
-| `path` | Where the problem is. In validate and boot phases a manifest path such as `manifest:Procedure/expire-order#/spec/handler/ref`; in the runtime phase a target path plus a JSON Pointer, such as `manifest:View/my-orders#/params/locale`. |
-| `source` | Authored location: `{ sourceId, documentIndex, path }` plus a line and column span when the YAML node is known. Present on parse diagnostics. |
-| `value` | The offending value, when one can be shown. |
-| `expected` | What would have been accepted, in prose. |
-| `candidates` | The valid alternatives — declared handler keys, enabled locales, declared Procedure names. Security-sensitive. |
-| `suggestion` | Nearest-match hint, when one is computed. |
-| `message` | Human-readable. Call sites may supply their own; otherwise it is derived as `[<phase>/<code>] at <path>; expected <…>; got <…>; (did you mean <…>?)`. The structured fields stay authoritative. |
-
-`candidates` is stripped by `redactForWire` before any HTTP egress, because listing valid alternatives to an untrusted caller leaks schema information. Internal phases — validate, test and boot — skip that redaction, so a CLI or boot log keeps the full list. One or more diagnostics travel across a transport boundary inside a `DiagnosticError`; the boundary catch emits the structured payload instead of falling back to the `INTERNAL_ERROR` envelope reserved for genuinely unexpected throws.
-
-`failure` describes safe effect and recovery facts for storage and service failures. `safe` means retrying the same idempotent operation is safe, not that Mantle automatically retries it. Unknown write/send outcomes require reconciliation unless the adapter guarantees idempotence. Provider payloads, SQL and credentials belong in `DiagnosticError`’s internal `cause`, never public fields. See the [port operation matrix](../../adr/0023-port-failure-contract.md).
+`mantle generate` prints `CODE path: message`; a SQL diagnostic's message
+starts with `SQL <line>:<column> near "<token>"`. Over HTTP a failure is
+`{ "error": <diagnostic> }` with the status below; internal details are
+redacted. Over MCP it is a tool error result carrying the same code.
+Handler code catches `DiagnosticError` and reads `error.diagnostic.code`.
 
-## Validate-only
+## Run time
 
-Raised by the parser, the graph validator and the code generator. `mantle validate` and `mantle generate` surface these; parsing is all-or-nothing, so one error-severity diagnostic withholds the whole parsed set.
-
-| Code | Meaning | HTTP |
+| Code | HTTP | Meaning |
 |---|---|---|
-| `INVALID_MANIFEST_ENVELOPE` | Wrong `apiVersion`, unknown key at a known level, wrong value shape, a YAML syntax or alias-limit failure, a Schema data property named `expectedVersion` (reserved Procedure OCC token; ADR-0022), or a Schema data property named after a native entry column (`id`, `status`, `version`, `createdAt`, `updatedAt`, `authorId`). | — |
-| `DUPLICATE_NAME` | Two documents of the same kind declare the same `metadata.name`. | — |
-| `VIEW_FROM_UNKNOWN_SCHEMA` | `spec.from` names no declared Schema. | — |
-| `VIEW_FIELD_NOT_IN_SCHEMA` | A `fields` entry or `orderBy[i].field` is neither a Schema property nor a reserved entry column. | — |
-| `VIEW_FILTER_FIELD_NOT_IN_SCHEMA` | A filter comparison names an unknown field. | — |
-| `VIEW_PARAMS_INVALID_SHAPE` | `spec.params` is not an object schema with an object `properties`. | — |
-| `VIEW_PARAMS_RESERVED_NAME` | `params.properties` declares `page`, `show` or `cursor`. | — |
-| `VIEW_FILTER_PARAM_REF_UNKNOWN` | `{ $param: <name> }` names a param that is not declared. | — |
-| `VIEW_FILTER_PARAM_REF_NOT_REQUIRED` | The referenced param is not listed in `params.required`. | — |
-| `VIEW_FILTER_CTX_USER_REF_INVALID` | The `{ "$ctx.user": "id" }` sentinel is malformed or used outside `eq`. | — |
-| `VIEW_FILTER_CTX_USER_REF_REQUIRES_AUTH` | The sentinel is used without `ctx.user` in `requires.auth.all`. | — |
-| `VIEW_FILTER_CTX_USER_REF_REQUIRES_INDEX` | The bound field is not the leftmost field of a declared index. | — |
-| `VIEW_ORDERBY_INVALID` | An `orderBy` entry has the wrong shape or an unknown `direction`. | — |
-| `VIEW_UI_INVALID` | A View `uiSchema` key is unknown, used on a public View, or names an unknown output field. | — |
-| `VIEW_PUBLIC_STATUS_INVALID` | A public View over a `publishing` Schema compares `status` to anything but `published`. The runtime always reads published rows only on that surface, so the filter can only contradict it. | — |
-| `REQUIRED_FIELD_UNKNOWN` | A `required` entry of `spec.schema` is not declared under `properties`. | — |
-| `INVALID_PATTERN` | A `pattern` does not compile as a JavaScript regular expression. | — |
-| `JSON_SCHEMA_UNSUPPORTED` | A JSON Schema keyword outside the accepted subset. | — |
-| `JSON_SCHEMA_REF_INVALID` | A `$ref` does not begin `#/$defs/` or does not resolve in the same document. | — |
-| `JSON_SCHEMA_LIMIT_EXCEEDED` | Nesting deeper than 100 levels, or more than 10,000 schema nodes. | — |
-| `BIND_VALUE_NOT_IN_ENUM` | `x-mantle-bind` is not `ctx.user`, `ctx.staff` or `now`. | — |
-| `AUTH_PREDICATE_NOT_IN_ENUM` | A `ctx.staff` role is not `owner`, `editor` or `contributor`. | — |
-| `GUARD_PROCEDURE_UNKNOWN` | `requires.guard.procedure` names no declared Procedure. | — |
-| `GUARD_SELF_REFERENCE` | A Procedure names itself as its own guard. | — |
-| `GUARD_PROCEDURE_BUILTIN` | The guard Procedure uses a builtin handler instead of `handler.kind: ref`. | — |
-| `GUARD_CHAIN_NOT_ALLOWED` | The guard Procedure itself declares a guard. | — |
-| `SCHEMA_INDEX_INVALID` | An index tuple breaks a shape, naming, reserved-column, type or duplication rule. | — |
-| `SCHEMA_INDEX_FIELD_UNKNOWN` | An `indexes` field is not a top-level Schema property. | — |
-| `UNIQUE_INDEX_FIELD_UNKNOWN` | A `uniqueIndexes` field is not a top-level Schema property. | — |
-| `SCHEMA_SEARCH_INVALID` | `searchableFields` repeats an entry or names a non-string property. | — |
-| `SCHEMA_SEARCH_FIELD_UNKNOWN` | A `searchableFields` entry is not a Schema property. | — |
-| `SCHEMA_TTL_INVALID` | TTL must name a top-level date-time field and a finite nonnegative duration. | — |
-| `SCHEMA_TTL_TRANSLATION_UNSUPPORTED` | TTL on either side of a translation join cannot guarantee the joined content's expiry. | — |
-| `VIEW_TTL_NATIVE_UNSAFE` | A native SQL View cannot guarantee logical expiry while a Schema has TTL. | — |
-| `SCHEMA_UI_INVALID` | A Schema or Procedure `uiSchema` rule is broken, including unknown roots, invalid `nav.standalone`, or a Schema declaring `uiSchema.collectionAction`. | — |
-| `HANDLER_BUILTIN_NOT_IN_V010` | A builtin Procedure was invoked on a runtime assembled without the builtin collaborator. | — |
-| `MANIFEST_ROOT_NOT_FOUND` | The manifests directory is missing, unreadable, or contains no `.yaml` or `.yml` file. | — |
-| `MANIFEST_READ_FAILED` | A manifest source could not be read. | — |
-| `CODEGEN_IDENTIFIER_COLLISION` | Two names in one group collapse to the same generated lower-camel identifier. | — |
-| `SCHEDULE_INPUT_INVALID` | A scheduled Procedure cannot accept the empty object supplied by its system Trigger. | — |
-| `SCHEDULE_AUTH_INVALID` | A scheduled Procedure requires user or staff authority that the system caller never has. | — |
-| `FIXTURE_SCHEMA_VIOLATION` | Reserved for consumer-authored test diagnostics on the `test` phase. Core emits purpose-shaped harness reports instead. | — |
-
-## Cross-phase
-
-Named by the same code in validate, boot or runtime, depending on where the condition is detectable.
-
-| Code | Meaning | HTTP |
-|---|---|---|
-| `HANDLER_NOT_REGISTERED` | A `handler.kind: ref` key has no function in the `handlers` map. Boot attaches the registered keys as `candidates`; the runtime occurrence is defence in depth. | `500` |
-| `TRIGGER_TARGET_PROCEDURE_UNKNOWN` | `spec.target.procedure` names no declared Procedure. | — |
-| `TRIGGER_PATH_COLLISION` | Two HTTP Triggers claim the same `(method, path)`. | — |
-| `TRIGGER_PATH_INVALID` | An HTTP Trigger path does not start `/api/` (validate), or falls under an adapter-reserved prefix (boot). | — |
-| `MCP_TOOL_NAME_COLLISION` | Two atoms mangle to the same MCP tool name, a Procedure takes a reserved generic name or prefix, or two MCP Triggers share a `(surface, tool name)`. | — |
-| `MCP_TOOL_DESCRIPTION_MISSING` | Warning. A Procedure reached by an MCP Trigger has no `spec.description`; `tools/list` would show a generated placeholder instead of something an agent can choose by. | — |
-| `MCP_TOOL_INPUT_UNREACHABLE` | Warning. An MCP write tool requires `expectedVersion` for a collection that no View on the same surface exposes `version` for, so an agent cannot read the value it must send. SQL Views are checked only by a conservative token scan. | — |
-| `MCP_TOOL_INPUT_UNION_AMBIGUOUS` | Warning. An MCP-surfaced Procedure input is a top-level `oneOf`; MCP clients render it poorly, and when its branches require fields the advertised `required` omits a caller satisfying the schema can still be rejected. Prefer one tool per branch. Disable or tune through `ValidateManifestsRequest.mcpInput`, or `mantle validate --no-mcp-input-checks`. | — |
-| `MCP_TOOL_INPUT_UNBOUNDED` | Warning. An MCP-surfaced Procedure input has an array without `maxItems` (or above the configured bound) or a free-form object with no declared properties, so an agent must serialise an unbounded payload into one `tools/call`. Typed maps (`additionalProperties: { type: … }`) do not count as free-form. | — |
-| `PROCEDURE_NOT_FOUND` | An invocation names a Procedure that is not in the compiled plan. | — |
-| `NOT_FOUND` | The addressed resource does not exist: an entry id, a View name, a media asset, an operation name. | `404` |
-| `METHOD_NOT_ALLOWED` | The path exists but the method is not bound. | `405` |
-| `VIEW_DIALECT_UNSUPPORTED` | The bound storage adapter does not support a `sql` View's dialect. | — |
-
-## Builtin handlers and lifecycle
-
-| Code | Meaning | HTTP |
-|---|---|---|
-| `BUILTIN_HANDLER_SCHEMA_UNKNOWN` | `handler.schema` names no declared Schema. | — |
-| `BUILTIN_HANDLER_CONTRACT_INVALID` | The Procedure's `input` breaks the builtin op's contract, such as a missing `expectedVersion` on `update` or a `match` tuple that is not exactly one `uniqueIndexes` entry; or `spec.mcp` contradicts the op (`readOnlyHint: true` on any builtin, `destructiveHint: false` on `op: delete`). | — |
-| `LIFECYCLE_SCHEMA_UNKNOWN` | A lifecycle Trigger's `source.schema` names no declared Schema. | — |
-| `LIFECYCLE_HOOK_REJECTED` | A `before_*` hook aborted the mutation. The diagnostic names the rejecting hook. | `409` |
-
-## Locale and translates
-
-| Code | Meaning | HTTP |
-|---|---|---|
-| `SCHEMA_LOCALIZED_REQUIRES_SITE_LOCALES` | A Schema declares `localized: true` while the site has no valid locales. | — |
-| `TRANSLATES_PARENT_UNKNOWN` | `translates.parent` names no declared Schema. | `409` |
-| `TRANSLATES_REQUIRES_LOCALIZED` | A Schema declares `translates` without `localized: true`. | — |
-| `TRANSLATES_REQUIRES_CONTENT_FIELD` | A translation child declares no property besides `locale` and the join field. | — |
-| `TRANSLATES_FIELD_NOT_IN_PARENT` | The join field is not declared in the parent's `properties`. | — |
-| `TRANSLATES_FIELD_NOT_IN_CHILD` | The join field is not declared in the child's own `properties`. | — |
-| `TRANSLATES_PARENT_IS_LOCALIZED` | The named parent is itself `localized: true`. | — |
-
-## Runtime
-
-These are the codes that reach a caller. Everything else in this catalog is caught before traffic.
-
-| Code | Meaning | HTTP |
-|---|---|---|
-| `RESOURCE_EXHAUSTED` | A known capacity or quota refusal. | `507` |
-| `RESOURCE_UNAVAILABLE` | A required storage or service dependency is unavailable. | `503` |
-| `RATE_LIMITED` | A recognized request-rate refusal. | `429` |
-| `OUTCOME_UNKNOWN` | The operation may have taken effect; reconcile before retry. | `503` |
-| `PARTIAL_FAILURE` | Some effects completed; inspect the operation’s recovery contract. | `503` |
-| `PRECONDITION_FAILED` | A storage or service precondition failed. | `412` |
-| `INPUT_VALIDATION_FAILED` | Procedure input, View params or an entry's `data` failed the compiled schema, including the write-time locale gate. | `400` |
-| `INVALID_LOCALE` | A locale value is not a canonical Mantle v0.1 tag. Also raised at boot against `site_config/locales`. | `400` |
-| `UNAUTHENTICATED` | An auth predicate failed and the caller presented no identity at all. | `401` |
-| `ENTITLEMENT_REQUIRED` | A guard Procedure denied the call on current business state. | `402` |
-| `AUTH_DENIED` | An auth predicate failed for a caller that is authenticated in some way, or an Admin caller lacks the required staff role. | `403` |
-| `CONFLICT` | Optimistic-concurrency mismatch, unique-index violation, an illegal lifecycle transition, or a generic write against a read-only Schema. Not retryable as sent. | `409` |
-| `OUTPUT_VALIDATION_FAILED` | A handler returned a value that does not match its declared `output`. A handler bug. | `500` |
-| `INTERNAL_ERROR` | An uncaught handler exception. | `500` |
-| `DISPATCHER_NOT_BUILT` | The runtime feature is not implemented in this build. | `501` |
-| `MEDIA_NOT_CONFIGURED` | Media uploads are not enabled: no `mediaStorage` port is bound. | `501` |
-| `MEDIA_PURPOSE_REJECTED` | The requested `purpose` is not declared in `siteDefaults.media.purposes`. The declared set is returned in `expected`. | `400` |
-| `MEDIA_MIME_REJECTED` | The declared mime is outside the accepted image set. | `400` |
-| `MEDIA_SVG_REJECTED` | An SVG upload was attempted while the adapter has SVG disabled; object storage does not sanitize SVG payloads. | `400` |
-| `MEDIA_SIZE_EXCEEDED` | A declared `byteSize` exceeds the cap. | `400` |
-| `MEDIA_VARIANTS_INCOMPLETE` | The variants manifest does not cover every mime the purpose requires. | `400` |
-| `MEDIA_VARIANT_SIZE_EXCEEDED` | One variant's `byteSize` exceeds its mime's `maxBytes`. | `400` |
-| `MEDIA_VARIANTS_SUSPICIOUS_SIZE` | A modern format is larger than its fallback, so the uploader skipped optimization for that variant. | `400` |
-| `MEDIA_UPLOAD_EXPIRED` | The upload capability's TTL elapsed, or it never existed. | `410` |
-| `MEDIA_OBJECT_NOT_FOUND` | Commit ran before every variant's bytes reached the storage backend. | `409` |
-| `MEDIA_CHECKSUM_MISMATCH` | Uploaded bytes do not match the declared checksum. | `409` |
-| `MEDIA_ASSET_NOT_FOUND` | No `media_assets` row matches the id. | `404` |
-
-## How diagnostics surface
-
-Only the runtime phase maps to HTTP. `httpStatusFor` reads the status table above; **a runtime code that is not in that table becomes `500`**. Validate, test and boot phases have no HTTP mapping at all — they surface through:
-
-- **CLI exit codes.** `mantle validate`, `mantle generate` and `mantle-harness` print each diagnostic as `<code> <path>: <message>` in text mode or as JSON otherwise. Exit `0` means no errors (warnings are allowed), `1` means one or more errors, `2` means a CLI invocation problem.
-- **A thrown `BootValidationError`.** Deployment preparation collects boot diagnostics and throws them together; the error carries the full `diagnostics` array.
-- **Worker init logs.** On Cloudflare the facade boots the runtime once per isolate. A boot failure is logged and the request boundary returns a redacted `{ ok: false, error: "internal_error" }` with `500`, so the diagnostic detail stays in the log rather than on the wire.
-
-Five codes are declared in the catalog but not emitted anywhere in the shipped source at this version: `FIXTURE_SCHEMA_VIOLATION` (reserved for consumer tests by design), `MANIFEST_READ_FAILED`, `METHOD_NOT_ALLOWED`, `DISPATCHER_NOT_BUILT` and `MEDIA_CHECKSUM_MISMATCH`. They remain part of the public contract because the catalog, not the current set of throw sites, is the contract.
+| `INPUT_VALIDATION_FAILED` | 400 | input against its schema, a failed `check`, a malformed body or query |
+| `UNAUTHENTICATED` | 401 | no caller, or a presented credential that failed |
+| `ENTITLEMENT_REQUIRED` | 402 | a guard found no entitlement |
+| `AUTH_DENIED` | 403 | a signed-in caller fails a predicate or a role, or a cross-origin session write |
+| `NOT_FOUND` | 404 | no such route, View, row or operation for this caller |
+| `METHOD_NOT_ALLOWED` | 405 | |
+| `CONFLICT` | 409 | a lock, a row op that wrote nothing, a unique index; `conflict` says which and which op |
+| `LIFECYCLE_HOOK_REJECTED` | 409 | for a before hook that rejects with it |
+| `PRECONDITION_FAILED` | 412 | |
+| `RATE_LIMITED` | 429 | |
+| `INTERNAL_ERROR`, `OUTPUT_VALIDATION_FAILED` | 500 | a handler threw something that is not a `DiagnosticError`, or returned what `output` refuses |
+| `RESOURCE_UNAVAILABLE`, `OUTCOME_UNKNOWN`, `PARTIAL_FAILURE` | 503 | storage was unreachable; after `OUTCOME_UNKNOWN` the write may or may not have applied, so retry with the same ids and locks |
+| `RESOURCE_EXHAUSTED` | 507 | |
+| `INVOCATION_DEPTH_EXCEEDED` | 500 | more than 8 nested invocations (hooks and `ctx.invoke`) |
+| `PROCEDURE_NOT_FOUND` | 500 | `invokeProcedure` with a name the plan lacks |
+| `SITE_NOT_CONFIGURED` | 501 | Admin's `/site-settings` on a runtime without site defaults |
+| `MEDIA_*` | 400, 404, 409, 410, 501 | media uploads: `MEDIA_NOT_CONFIGURED` (501) without media storage and site defaults, `MEDIA_UPLOAD_EXPIRED` (410), `MEDIA_ASSET_NOT_FOUND` (404), `MEDIA_OBJECT_NOT_FOUND` and `MEDIA_CHECKSUM_MISMATCH` (409), and 400 for a refused type, size, purpose or variant set |
+
+Admin's statistics route answers 501 with the wire code
+`STATISTICS_UNAVAILABLE`, which is not a `DiagnosticCode`. `DISPATCHER_NOT_BUILT`
+(501) is in the catalog and not raised by 0.2.0.
+
+## Boot
+
+| Code | Meaning |
+|---|---|
+| `HANDLER_NOT_REGISTERED`, `HANDLER_NOT_DECLARED` | the handlers map lacks a plan ref, or has one the plan lacks |
+| `PLAN_FINGERPRINT_MISMATCH` | the plan is not the expected one, or was compiled for another dialect or plan version |
+| `SCHEDULE_NOT_WIRED` | an enabled schedule Trigger without `schedules: true` |
+| `STORAGE_CHANGE_BLOCKED` | storage has a difference boot will not change; the message names it and hints SQL |
+| `STORAGE_TABLE_NOT_OWNED` | a table Mantle would create exists and is not Mantle's |
+| `INVALID_LOCALE`, `SCHEMA_LOCALIZED_REQUIRES_SITE_LOCALES` | a site `locales` entry that is not a language with an optional 2-letter region, or a `localized` Schema without site `locales` |
 
-## Source
+## `mantle generate`
 
-- [`packages/mantle-spec/src/kernel/diagnostic.ts`](../../../packages/mantle-spec/src/kernel/diagnostic.ts)
-- [`packages/mantle-spec/src/domain/service/ManifestParser.ts`](../../../packages/mantle-spec/src/domain/service/ManifestParser.ts)
-- [`packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts`](../../../packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts)
-- [`packages/mantle-spec/src/domain/service/CrossSchemaChecker.ts`](../../../packages/mantle-spec/src/domain/service/CrossSchemaChecker.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/loadManifests.ts`](../../../packages/mantle-spec/src/infrastructure/cli/loadManifests.ts)
-- [`packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts`](../../../packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts)
-- [`packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts`](../../../packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts)
-- [`packages/mantle-runtime/src/usecase/media/diagnostics.ts`](../../../packages/mantle-runtime/src/usecase/media/diagnostics.ts)
-- [`packages/mantle-runtime/src/domain/service/EntryMutationDiagnostics.ts`](../../../packages/mantle-runtime/src/domain/service/EntryMutationDiagnostics.ts)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
+| Codes | About |
+|---|---|
+| `INVALID_MANIFEST_ENVELOPE`, `DUPLICATE_NAME`, `MANIFEST_ROOT_NOT_FOUND`, `MANIFEST_READ_FAILED` | files and the envelope; a `v1` apiVersion fails here and names the upgrade guide; `x-mantle-bind` fails and names its replacements (`spec.scope`, `auth.uid()`, `now()`) |
+| `REQUIRED_FIELD_UNKNOWN`, `INVALID_PATTERN`, `JSON_SCHEMA_UNSUPPORTED`, `JSON_SCHEMA_REF_INVALID`, `JSON_SCHEMA_LIMIT_EXCEEDED` | JSON Schemas |
+| `SCHEMA_INDEX_INVALID`, `SCHEMA_INDEX_FIELD_UNKNOWN`, `UNIQUE_INDEX_FIELD_UNKNOWN`, `SCHEMA_SEARCH_INVALID`, `SCHEMA_SEARCH_FIELD_UNKNOWN`, `SCHEMA_TTL_INVALID`, `SCHEMA_TTL_TRANSLATION_UNSUPPORTED`, `SCHEMA_UI_INVALID`, `SCHEMA_NAME_CASE_COLLISION`, `FIELD_NAME_CASE_COLLISION`, `MANTLE_REF_INVALID` | Schemas |
+| `TRANSLATES_PARENT_UNKNOWN`, `TRANSLATES_REQUIRES_LOCALIZED`, `TRANSLATES_REQUIRES_CONTENT_FIELD`, `TRANSLATES_FIELD_NOT_IN_PARENT`, `TRANSLATES_FIELD_NOT_IN_CHILD`, `TRANSLATES_PARENT_IS_LOCALIZED` | `translates` |
+| `VIEW_INPUT_INVALID_SHAPE`, `VIEW_INPUT_RESERVED_NAME`, `VIEW_CACHE_INVALID`, `VIEW_UI_INVALID` | Views |
+| `SQL_SYNTAX`, `SQL_UNSUPPORTED`, `SQL_FUNCTION`, `SQL_RELATION`, `SQL_COLUMN`, `SQL_WRITE`, `SQL_SHAPE`, `SQL_TYPE` | View and Procedure SQL, with a position |
+| `AUTH_PREDICATE_NOT_IN_ENUM`, `GUARD_PROCEDURE_UNKNOWN`, `GUARD_SELF_REFERENCE`, `GUARD_PROCEDURE_NOT_REF`, `GUARD_CHAIN_NOT_ALLOWED`, `PROCEDURE_TARGET_INVALID` | `requires` and `target` |
+| `TRIGGER_TARGET_PROCEDURE_UNKNOWN`, `TRIGGER_PATH_COLLISION`, `TRIGGER_PATH_INVALID`, `SCHEDULE_INPUT_INVALID`, `SCHEDULE_AUTH_INVALID`, `LIFECYCLE_SCHEMA_UNKNOWN`, `LIFECYCLE_TARGET_NOT_REF` | Triggers |
+| `MCP_TOOL_NAME_COLLISION`, `MCP_TOOL_DESCRIPTION_MISSING` (warning), `MCP_TOOL_INPUT_UNION_AMBIGUOUS`, `MCP_TOOL_INPUT_UNBOUNDED` | MCP tools |
+| `GENERATE_FEATURE_DEPENDENCY_MISSING` | a selected feature, identity, host or dialect whose package is not installed, or `admin` with identity `none`; the message carries the install command |
+
+A schedule Trigger whose cron Cloudflare cannot run the same way, or any
+enabled schedule Trigger on host `bun`, fails with exit 1 as
+`Trigger <name>: <message>` before anything is written.
+
+`FIXTURE_SCHEMA_VIOLATION` is reserved for consumer test diagnostics.

package/docs/handbook/reference/features.md

@@ -1,55 +1,53 @@
 ---
-description: Manifest capability table mapping authoring goals to Schema, View, Procedure and Trigger fields, generated APIs and Admin behavior.
+description: A task-to-feature table for Mantle 0.2.0 manifests — what to declare for each common need, with links to the field reference and an example.
 ---
 # Manifest feature reference
 
-All paths below are relative to the atom's `spec`. The envelope is always
-`apiVersion`, `kind`, `metadata.name`, `spec`. Features compose from these four
-atoms; there is no separate Form, Workflow or UI manifest kind. See the
-[envelope reference](./manifest.md) for naming and unknown-key rules.
-
-## Capability table
-
-| Goal | Atom and fields | Runtime / surface effect | Contract |
+| You need | Declare | Reference | Example |
 |---|---|---|---|
-| Define stored business data | Schema `schema` | Validated fields; storage adapter prepares the Schema. Generated entry types follow the JSON Schema subset. | [Schema](./schema.md) |
-| Choose draft publishing or live records | Schema `lifecycle` | `publishing` has draft/publish transitions; `operational` creates live records. Admin workflow follows this choice. | [Lifecycle](../concepts/lifecycle-and-locales.md) |
-| Label fields and collections | Schema `title`, `description`, property `title`, `description` | Localized Admin labels/help. Does not rename data keys. | [LocalizedText](./manifest.md#localizedtext) |
-| Make Procedure-managed records | Schema `schema.readOnly` | Disables generic authoring writes; declared Procedures still work. | [Read-only collections](./schema.md#root-readonly-true) |
-| Find and constrain records | Schema `indexes`, `uniqueIndexes`, `searchableFields` | Native access paths, uniqueness and declared substring-search fields. Search fields do not create indexes. | [Indexes](./schema.md#indexes) |
-| Translate or relate records | Schema `localized`, `translates`; property `x-mantle-ref` | Locale rows, joined translations, relation controls and folded child collections. | [Schema](./schema.md), [Admin guide](../guides/admin-ui.md) |
-| Stamp trusted values | Property `x-mantle-bind` | Runtime stamps identity/time; generic agent inputs exclude bound fields and Admin shows them read-only. | [Binding](./schema.md#x-mantle-bind) |
-| Adjust collection inputs and list | Schema `uiSchema.fields`, `.list`, `.nav` | Textareas, operational columns/tabs, standalone child navigation. No CSS or component injection. | [Admin guide](../guides/admin-ui.md) |
-| Query one Schema portably | View `from`, `fields`, `filter`, `orderBy`, `limit`, `params` | Named query with generated typed params and projected rows. | [View](./view.md), [typed queries](../guides/typed-queries.md) |
-| Join or aggregate in SQLite | View `sql`, `params`, `limit` | One bound SELECT; requires a SQLite-capable adapter. Generated row type is `unknown`. | [SQL Views](./view.md#sql) |
-| Choose read visibility | View `surface` | `public`: public REST/MCP; `staff`: Admin reports/staff MCP; `internal`: host binding only. Transports require host composition. | [Surfaces](./view.md#surfaces) |
-| Authorize a query or action | View / Procedure `requires.auth`, `requires.guard` | Runtime checks verified caller context and optional guard. Visibility and UI metadata do not grant access. | [Authorization](./authorization.md) |
-| Filter by caller identity | View `filter` with `$ctx.user: id` | Declarative equality filter; requires user auth and a left-prefix index. | [Identity filters](./view.md#value-forms) |
-| Cache anonymous published reads | View `cache.sharedMaxAge` | Eligible public declarative publishing reads receive shared HTTP cache policy when the host configures cache scope. | [View cache](../concepts/views.md#shared-response-cache) |
-| Configure a report | Staff View `title`, `uiSchema.list` | Ordered report/CSV columns, server-side search and exact filters. | [View list](./view.md#uischemalist) |
-| Define an action | Procedure `input`, `output`, `handler` | Typed input/output; builtin mutation or registered host handler. A Procedure does not create an HTTP route by itself. | [Procedure](./procedure.md) |
-| Put an action in Admin | Procedure `uiSchema.collectionAction`, `.fields`; input `x-mantle-ref`; qualifying Trigger | Collection/row actions and forms; eligible standalone operations appear under Operations. | [Admin guide](../guides/admin-ui.md) |
-| Describe an agent action | Procedure `title`, `description`, `mcp` | Tool descriptions and behavior annotations; enforcement remains in runtime authorization/validation. | [Procedure](./procedure.md) |
-| Expose an HTTP action | Trigger `source: { kind: http, method, path }`, `target.procedure` | Handler on the declared `/api/` path through supporting host adapters. | [HTTP Trigger](./trigger.md#http-source) |
-| Expose an agent action | Trigger `source: { kind: mcp, surface }`, `target.procedure` | Public or staff MCP tool; Procedure authorization still applies. | [Trigger](./trigger.md) |
-| React to content lifecycle | Trigger `source: { kind: lifecycle, schema, on, errorPolicy }`, `target.procedure` | Invokes the action on selected lifecycle events. Deferred execution needs host support. | [Hooks](../concepts/procedures-and-triggers.md) |
-
-## Where manifest control ends
-
-Manifests describe data, callable behavior and supported presentation metadata.
-They do not declare arbitrary React components, visitor routes, page layouts,
-CSS, provider credentials or deployment resources. Those belong to application
-source and optional host packages. For an Admin change, consult the
-[rendering map](../guides/admin-ui.md) before deciding that custom UI is needed.
-
-The pipeline is source → parse → link → compile → prepare storage → bind
-runtime. `mantle generate` projects the plan and types; it does not start a
-server. Programmatic `emitMantleModule({ plan })` also accepts an already
-compiled plan; see [typed queries](../guides/typed-queries.md).
-
-## Source
-
-- [Manifest grammar](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
-- [Admin UI validation](../../../packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts)
-- [Type generation](../../../packages/mantle-spec/src/usecase/EmitTypesUseCase.ts)
-- [Runtime binding generation](../../../packages/mantle/src/codegen/emitMantleModule.ts)
+| A table | a Schema with a JSON Schema | [Schema](./schema.md) | every example |
+| Authored content with drafts and publishing | `lifecycle: publishing` (the default) | [Lifecycle](../concepts/lifecycle-and-locales.md) | [Publication](../../examples/publication.md) |
+| Records written by the system | `lifecycle: operational` | [Lifecycle](../concepts/lifecycle-and-locales.md) | [Intake form](../../examples/intake.md) |
+| Rows only their owner may ever see | `scope: { owner: auth.uid() }` | [Authorization](../concepts/authorization.md) | reference service `orders` |
+| A member sees their own rows, staff see all | store `auth.uid()` in the SQL, filter `WHERE x = auth.uid()` | [Authorization](../concepts/authorization.md) | [Procurement](../../examples/procurement.md) |
+| A rule every write obeys | `checks: ["stock >= 0"]` | [Schema](./schema.md#checks) | [Commerce inventory](../../examples/commerce-inventory.md) |
+| Uniqueness | `uniqueIndexes` | [Schema](./schema.md#indexes) | [Commerce](../../examples/commerce.md) |
+| Full-text search | `searchableFields` and `mantle.search` | [View](./view.md) | [Publication](../../examples/publication.md) |
+| Places | `format: geo` and `mantle.near` / `mantle.distance` | [View](./view.md) | |
+| Rows that expire | `ttl`, then `sweepExpired` | [Lifecycle](../concepts/lifecycle-and-locales.md#ttl) | |
+| Translations | `localized`, `translates` | [Schema](./schema.md#localized-and-translates) | [Publication](../../examples/publication.md) |
+| A public read | a View, `surface: public` | [View](./view.md) | every example |
+| A staff report with CSV | a View, `surface: staff`, `uiSchema.list` | [Admin](../guides/admin-ui.md) | [Reservation](../../examples/reservation.md) |
+| A read only code uses | a View, `surface: internal` | [Query from TypeScript](../guides/typed-queries.md) | [Commerce inventory](../../examples/commerce-inventory.md) |
+| Joins, aggregates, windows | the View's SQL | [View](./view.md#what-the-d1-dialect-accepts) | reference service `sales-by-item` |
+| A write | a Procedure with `handler: { sql }` | [Procedure](./procedure.md) | every example |
+| Several writes, all or nothing | several statements in one `sql` | [Procedure](./procedure.md#handlersql) | reference service `place-order` |
+| An upsert | `INSERT … ON CONFLICT (…) DO UPDATE` | [Procedure](./procedure.md) | reference service `restock` |
+| No lost updates | `WHERE id = input.id AND version = input.expectedVersion` | [Procedure](./procedure.md#row-ops-and-set-ops) | [Commerce](../../examples/commerce.md) |
+| Code: call a service, read then write, set `status` | `handler: { ref }` | [Procedure](./procedure.md#handlerref) | [Commerce inventory](../../examples/commerce-inventory.md) |
+| An HTTP route | a Trigger `kind: http` | [Trigger](./trigger.md#http) | every example |
+| An agent tool | a Trigger `kind: mcp`, or a View | [MCP and agents](../concepts/mcp-and-agents.md) | every example |
+| An Admin operation | a Trigger `kind: mcp, surface: staff` | [Admin](../guides/admin-ui.md) | [Procurement](../../examples/procurement.md) |
+| Signed-in callers only | `requires: { auth: { all: [ctx.user] } }` | [Authorization requirements](./authorization.md) | [Procurement](../../examples/procurement.md) |
+| Staff roles | `{ ctx.staff: [owner, editor] }` | [Authorization requirements](./authorization.md) | [Commerce](../../examples/commerce.md) |
+| API keys and scopes | a custom `CallerResolver`, `{ ctx.auth.scope: … }` | [Authorization](../concepts/authorization.md) | [Guarded API access](../../examples/guarded-api.md) |
+| A live check before one action | `requires.guard` | [Authorization requirements](./authorization.md#guard) | [Intake with bot check](../../examples/intake-hooks.md) |
+| A rule before every write of a Schema | a `before_*` lifecycle Trigger | [Trigger](./trigger.md#lifecycle) | |
+| Side effects after a write | an `after_*` lifecycle Trigger | [Trigger](./trigger.md#lifecycle) | [Intake with bot check](../../examples/intake-hooks.md) |
+| A recurring job | a Trigger `kind: schedule` (POSIX cron) | [Trigger](./trigger.md#schedule) | [Commerce inventory](../../examples/commerce-inventory.md) |
+| A signed webhook | a route in the service's `fetch`, then `runtime.invokeProcedure` | [Writes](../concepts/procedures-and-triggers.md#webhooks) | [Commerce inventory](../../examples/commerce-inventory.md) |
+| Media uploads | `d1Storage(db, { site })` and `r2MediaStorage` | [Media uploads with R2](../cloudflare/media-r2.md) | |
+
+## Not in 0.2.0
+
+| 0.1.x feature | In 0.2.0 |
+|---|---|
+| builtin handlers (`create`, `update`, `upsert`, `delete`, `archive`) | SQL statements; `archive` is a `ref` handler setting `status` |
+| the Filter AST, `params`, `$param`, `$ctx.user` | the View's SQL, `input`, `input.<name>`, `auth.uid()` |
+| `page` / `show` | `limit` / `cursor` |
+| `x-mantle-bind` | `scope`, or `auth.uid()` / `now()` in the SQL |
+| generated record tools on Staff MCP | declared Procedures with `mcp` Triggers |
+| `errorPolicy` on lifecycle hooks | before hooks fail closed; after hooks are best effort |
+| deferred hooks on a Queue | after hooks run after the commit; a queue is the service's own |
+| Mantle-rendered public pages, templates, sitemap | not ported; render from your own `fetch` |
+| `mantle validate`, `emit-openapi`, `mantle skills` | `mantle generate` and `mantle generate --check` |