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

package/docs/handbook/reference/diagnostics.md

@@ -1,193 +1,26 @@
----
-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.
----
-# Diagnostics
+# Diagnostics and errors
 
-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).
+Generation returns diagnostics with `code`, `path` and `message`. Grammar/SQL errors retain compiler codes and source locations. `GENERATE_UNSUPPORTED` identifies declarations or boundary features the native generator cannot honor; it must not silently omit behavior.
 
-## Shape
+Bare queries preserve native errors except required conflict/uncertain-write classifications. At a JSON boundary, `wire(error)` or `surfaceFailure(error)` from `@aotter/mantle/contracts` redacts unclassified native failures. Selected generated REST/MCP/Admin boundaries apply their own error envelopes.
 
-```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;
-  };
-}
-```
+| Core code | HTTP | Meaning |
+| --- | --- | --- |
+| INPUT_VALIDATION_FAILED | 400 | Invalid external input, paging or Store operation |
+| UNAUTHENTICATED | 401 | Caller lacks required authenticated authority |
+| AUTH_DENIED | 403 | Predicate, role or session-origin refusal; a generic Admin write to a read-only Schema |
+| NOT_FOUND | 404 | Missing or excluded resource |
+| METHOD_NOT_ALLOWED | 405 | Path exists for another method |
+| CONFLICT | 409 | Unique clash, stale lock or failed row/state guard |
+| OUTCOME_UNKNOWN | 503 | Write may have committed; reconcile without automatic retry |
 
-| 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. |
+A `CONFLICT` carries `kind`: `"row"` when a row statement changed no row (missing or not visible, a stale version, or a
+state its WHERE no longer allows; one message covers all three, so it never reveals whether the row exists), `"unique"`
+for a unique-index clash and `"check"` for a Schema check (with `schema` and `check`). Match `kind`, not the message.
+To recover from `"row"`, read the record again and decide from its current state: retry with its current version only when the change still applies, and never retry blindly. A Procedure can name a precise reason itself (a ref handler that reads the row first, or a RETURNING the caller checks).
 
-`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.
+Unknown errors map to redacted `INTERNAL_ERROR` (500). A custom `ContractError` outside the core set must carry an explicit status. Media uses its selected `mediaError` contract. Never expose SQL errors, tokens or credentials.
 
-`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).
+The runtime runs no DDL or schema checks. Schema installation and failures belong to [the native migration tool](../concepts/runtime-and-adapters.md#schema-installation-and-migrations), not a boot diagnostic.
 
-## Validate-only
-
-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 |
-|---|---|---|
-| `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.
-
-## Source
-
-- [`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)
+User-field generation diagnostics are `AUTH_ROLE_REMOVED` (`auth.role` / `auth.hasRole`), `USER_REF_SCOPE_ONLY` (`auth.user` outside `scope` / `restrict`), `USER_FIELD_INVALID` (literal name/value or template grammar), `USER_FIELD_POSITION` (SET of a partition) and `USER_FIELD_CONFLICT` (column type/enum disagreement, or a reference to a field-scoped Schema without its scope terms). Warnings are `USER_FIELD_VALUES_UNENUMERATED` (no enum list), `USER_SCOPE_PUBLIC_ANON_EMPTY` (anonymous public reads are refused), `USER_SCOPE_ADMIN_VALUES` (an admin target reads field-scoped rows) and `USER_SCOPE_JOIN_DROPS` (a join of Schemas scoped by different fields). A generated app supplies the literal USER_REFS_V1 bind capability version; a mismatch throws `USER_REFS_VERSION` before native SQL.

package/docs/handbook/reference/features.md

@@ -1,55 +1,45 @@
----
-description: Manifest capability table mapping authoring goals to Schema, View, Procedure and Trigger fields, generated APIs and Admin behavior.
----
-# 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 |
-|---|---|---|---|
-| 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)
+# Supported declarations
+
+The native 0.2.0 SDK compiles the closed v2 grammar for four targets. Generation diagnostics, rather than historical APIs or release plans, define the checked-out implementation. Existing integrations require explicit app wiring and data migration; initial schema.sql is for an empty database.
+
+## Supported
+
+| Feature | Availability / agent action |
+| --- | --- |
+| Closed v2 Schema/View/Procedure grammar, PostgreSQL SQL authoring | Generated for Bun SQLite, Bun PostgreSQL, Cloudflare D1 and Cloudflare PostgreSQL; dialect behavior stays native. |
+| Operational Schemas, scope, TTL read visibility, indexes, checks, native SQL facilities | Generated initial DDL and compiled SQL policy; run migrations and TTL maintenance in application code. |
+| System-only TTL maintenance | Generated `<schema>.sweepExpired`, bounded cursor scans and optional dry-run; app owns `scheduled()` wiring and cron configuration. See [TTL maintenance](../guides/native-execution.md#ttl-maintenance). |
+| Typed SQL Views and Procedures, auth predicates, OCC, atomic writes | Generated bare queries accept validated inputs and a verified Caller; date/date-time outputs are ISO strings, native errors stay internal. |
+| Typed Store collections and internal Views/Procedures | Shared Store, AND-only filters, indexed non-null keyset ordering, atomic batches; interactive transactions on SQLite/PostgreSQL. |
+| Searchable fields, Store search and SQL search/rank | Generated SQLite/D1 FTS5 trigram table and maintenance triggers; PostgreSQL ILIKE. Store find/first trim non-empty search and match exact id OR declared fields, within the caller's row rules. |
+| Better Auth integration and Workers builds | App owns `auth.ts` and `resolveCaller`; optional [OAuth helpers](../guides/oauth.md) provide consent/connected apps, live grant/session checks and DPoP. `mantle generate` emits native Wrangler build configuration. Keep heavy auth imports lazy. |
+| Transactional email port, English templates and dev console sender | Optional `@aotter/mantle/email`; app supplies the sender and passes locale through. See [email wiring](../guides/email.md). |
+| View keyset pages, generated boundary validation and HTTP error mapping | Generated `paged/views/*` for proved exposed/internal Views: indexed non-null tuples, complete groups and singleton joins/lookups; `validation/*` and `wire`; see [surface contracts](surface.md). |
+| REST and `http` Trigger exposure | Supported generated `rest.ts`; app mounts with `{ db, caller }` and required `handlers` for ref contracts. Public Views page at `/api/views/<name>`; HTTP Triggers keep method/path. |
+| Generated MCP and `mcp` Trigger exposure | Public/admin tools, shared generated checks, publishing transitions on admin only; SDK loads on matching requests. Install the official MCP peer for manifests selecting this surface. |
+| Dynamic `web.ts` (`llms.txt`, sitemap, `.md` alternates, head tags) | Generated; mount `web({ ... })`; see [surface contracts](surface.md#optional-web-output). |
+| Native Admin bindings, server and console | Supported; select `--admin` / `admin: true` and mount `entries(bindings.schemas, bindings.adapter)`. Shared authorized read templates, native Procedure writes and the console; see [Native Admin](../guides/native-admin.md).  |
+| Localized Schemas and translations | Plain-string locale values, atomic published-parent guard, SQL parent visibility and generated page locale helper; see [Translations](../concepts/lifecycle-and-locales.md#translations). |
+| Opt-in `lifecycle: publishing` | Generated status, `published_at`, admin-only transitions and published-only public reads; see [Publishing](../concepts/lifecycle-and-locales.md). |
+| `ref` Procedures and typed `Handlers` | Generated `Handlers` type; pass implementations at `store(db, caller, { handlers })`; `mantle generate` lists them. See [ref Procedures](../guides/native-execution.md#ref-procedures). |
+| Optional site settings and media | Select `site` defaults at generation to emit the generated `site` module and deployment tables; native media upload lifecycle, app-owned R2/signing. See [media](../cloudflare/media-r2.md). |
+
+## Refused
+
+Each unsupported declaration produces `GENERATE_UNSUPPORTED`, its manifest path,
+and the following hint. Invalid grammar/SQL retains the compiler's own diagnostic
+codes and paths. Multiple declarations produce multiple diagnostics.
+
+| Declaration | Do instead |
+| --- | --- |
+| `schedule` Triggers, including disabled ones | Wire `scheduled()` yourself. |
+| `lifecycle` Triggers: before/after hooks, including targets using `ref` | Write a custom handler. |
+| `requires.guard` on a View or Procedure | Write a custom handler that checks authorization before executing queries. |
+| A View projecting a native `geo` value | Select the latitude and longitude columns explicitly. |
+| Dynamic or repeated View output names | Give each SELECT output a unique explicit alias. |
+| Declared date/date-time outputs without one SELECT item per output | Expand the SELECT list explicitly. |
+| Input properties differing only in case | Rename input properties to be unique without regard to case. |
+| PostgreSQL JSON/date/date-time parameters used without the declared cast | Wrap each occurrence in the concrete `CAST(... AS <type>)` shown by the diagnostic. |
+
+
+Store handles simple AND reads and writes; use internal Views for OR, joins, aggregates and reuse. Ref Procedures are supported with a typed caller/transaction-bound Store. See [typed queries](../guides/typed-queries.md), [lifecycle/locales](../concepts/lifecycle-and-locales.md) and [database ownership](../concepts/runtime-and-adapters.md).

package/docs/handbook/reference/manifest.md

@@ -1,134 +1,11 @@
----
-description: Envelope fields, unknown-key policy, multi-document YAML, LocalizedText, naming rules and reserved names shared by every Manifest kind.
----
-# Manifest envelope and conventions
+# Manifest envelope
 
-This page covers the rules that apply to every Manifest document before kind-specific validation runs. Read it once; the four atom pages ([Schema](./schema.md), [View](./view.md), [Procedure](./procedure.md), [Trigger](./trigger.md)) assume it. Diagnostic codes named here are catalogued in [Diagnostics](./diagnostics.md).
+Every YAML document has `apiVersion: cms.mantle.aotter.net/v2`, `kind`, `metadata.name` and `spec`. Kinds are Schema, View, Procedure and Trigger. Pass explicit file paths to `mantle generate`; a file may contain several documents separated by `---`.
 
-For a task-to-field table covering all four atoms, see the [Manifest feature reference](./features.md). For the resulting console, see [Customize Admin](../guides/admin-ui.md).
+The grammar is closed. Unknown keys and invalid declarations fail generation. Names are unique per kind; Schema and field names cannot differ only by case. Quote non-identifier Schema names in SQL. `input` and `auth` are reserved.
 
-## Envelope
+Titles and descriptions accept a string or locale map, such as `{ en: Products, zh-TW: 商品 }`. Selected UI/MCP chooses the configured locale with fallback.
 
-Every document is a YAML mapping with exactly four top-level keys.
+Author SQL in PostgreSQL syntax. Generation renders it for postgres or sqlite, including bound inputs and compiled row policy. SQL native columns use `id`, `version`, `created_at`, `updated_at`, `author_id`, plus `status` / `published_at` for publishing. Store uses storage names too. Manifest index declarations use authored field/native names (`createdAt`), which compile to storage names.
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema | View | Procedure | Trigger
-metadata:
-  name: posts
-spec:
-  # kind-specific
-```
-
-| Field | Type | Required | Rules |
-|---|---|---|---|
-| `apiVersion` | literal | yes | Exactly `cms.mantle.aotter.net/v1`. Anything else is `INVALID_MANIFEST_ENVELOPE` at `/apiVersion`. |
-| `kind` | enum | yes | `Schema`, `View`, `Procedure` or `Trigger`. |
-| `metadata` | mapping | yes | Only the key `name` is accepted. There is no `namespace`. |
-| `metadata.name` | string | yes | Non-empty. Unique within its kind (`DUPLICATE_NAME`, one diagnostic per occurrence). A Schema and a View may share a name. |
-| `spec` | mapping | yes | Kind-specific; see the atom pages. |
-
-A document that is not a mapping is rejected with `manifest must be a YAML mapping`.
-
-## Unknown-key policy
-
-The parser rejects keys outside the shipped grammar at every level it knows. The diagnostic is `INVALID_MANIFEST_ENVELOPE` with the message `<dotted.path> is not supported` and a JSON Pointer to the offending key (for example `spec.foo is not supported` at `/spec/foo`). Enum values outside the grammar are rejected the same way.
-
-| Pointer | Allowed keys |
-|---|---|
-| `/` | `apiVersion`, `kind`, `metadata`, `spec` |
-| `/metadata` | `name` |
-| `/spec` (Schema) | `title`, `description`, `schema`, `uiSchema`, `uniqueIndexes`, `indexes`, `searchableFields`, `localized`, `translates`, `lifecycle` |
-| `/spec` (View) | `title`, `uiSchema`, `from`, `sql`, `surface`, `cache`, `requires`, `filter`, `fields`, `orderBy`, `limit`, `params` |
-| `/spec` (Procedure) | `title`, `description`, `requires`, `input`, `uiSchema`, `output`, `handler`, `mcp` |
-| `/spec` (Trigger) | `source`, `target` |
-| `/spec/translates` | `parent`, `on` |
-| `/spec/requires` | `auth`, `guard` |
-| `/spec/requires/auth` | `all` |
-| `/spec/requires/guard` | `procedure` |
-| `/spec/requires/auth/all/<i>` (object form) | exactly one of `ctx.staff`, `ctx.auth.scope` |
-| `/spec/handler` (`kind: ref`) | `kind`, `ref` |
-| `/spec/handler` (`kind: builtin`) | `kind`, `op`, `schema`, `match` |
-| `/spec/filter/<op>` | `field`, `value` |
-| `/spec/orderBy/<i>` | `field`, `direction` |
-| `/spec/cache` (View) | `sharedMaxAge` |
-| `/spec/source` (`kind: http`) | `kind`, `method`, `path` |
-| `/spec/source` (`kind: lifecycle`) | `kind`, `schema`, `on`, `errorPolicy` |
-| `/spec/source` (`kind: mcp`) | `kind`, `surface` |
-| `/spec/target` | `procedure` |
-| `/spec/uiSchema` (View) | `list` (only on `surface: staff`; violations are `VIEW_UI_INVALID`) |
-| `/spec/uiSchema/list` (View) | `columns`, `searchFields`, `filterFields` |
-| `/spec/uiSchema` (Schema) | `fields`, `list`, `nav` |
-| `/spec/uiSchema/list` (Schema) | `filterField`, `primaryField`, `columns` |
-| `/spec/uiSchema/nav` (Schema) | `standalone`, `parentField` |
-| `/spec/uiSchema` (Procedure) | `collectionAction`, `fields` |
-
-`uiSchema` roots are closed. Schema accepts `fields`, `list`, and `nav`; Procedure accepts `collectionAction` and `fields`; View accepts `list` on `surface: staff`. Nested keys are closed. A Schema that declares `uiSchema.collectionAction` is rejected with `SCHEMA_UI_INVALID`. JSON Schema documents inside `spec.schema`, `spec.input`, `spec.output` and `spec.params` follow the [JSON Schema subset](./schema.md#json-schema-subset) instead of an allowlist.
-
-## Multi-document YAML and sources
-
-The parser consumes a set of sources, each `{ sourceId, text }`. The CLI builds this set from the immediate `.yaml` and `.yml` files of the manifests directory, sorted lexicographically, with the file path as `sourceId`; an unreadable or empty directory is `MANIFEST_ROOT_NOT_FOUND`. Nested directories are not read.
-
-Within one source:
-
-- `---` separates documents. A feature commonly bundles a Procedure and its Triggers in one file.
-- YAML merge keys (`<<`) are disabled.
-- Alias expansion is capped at 100 aliases per document. Exceeding the cap is `INVALID_MANIFEST_ENVELOPE` with the message `YAML alias-expansion limit exceeded`.
-- Empty or `null` documents are skipped.
-- A YAML syntax error is `INVALID_MANIFEST_ENVELOPE` at `/`, prefixed `[doc <index>]`.
-
-Parsing is all-or-nothing. Any error-severity diagnostic in any document withholds the whole parsed set; later stages never see a partial graph. Every diagnostic carries `source: { sourceId, documentIndex, path }` plus a line and column span when the YAML node is known.
-
-## LocalizedText
-
-`Schema.spec.title` (required), `Schema.spec.description`, `View.spec.title`, `Procedure.spec.title` and `Procedure.spec.description` accept either a plain string or a locale map.
-
-```yaml
-title: Products
-# or
-title: { en: Products, "zh-TW": 商品 }
-```
-
-The parser rejects an empty string, an empty map `{}`, an array, an empty locale key and any non-string or empty value. JSON Schema property `title` and `description` keywords accept the same shape for Admin labels and help text; MCP tool schemas collapse them to the `en` value.
-
-Resolution order (`resolveLocalizedText`): the viewer's preferred locale, then the site's canonical locale, then the first key in insertion order. A value that was never set resolves to `null`.
-
-## Naming rules for `metadata.name`
-
-| Rule | Applies to | Diagnostic |
-|---|---|---|
-| Non-empty string, unique within the kind. | all kinds | `DUPLICATE_NAME` |
-| Must match `/^[A-Za-z][A-Za-z0-9_.-]*$/` when the Schema declares any `indexes` or `uniqueIndexes`. | Schema | `SCHEMA_INDEX_INVALID` at `/metadata/name` |
-| Unique after MCP mangling (`mcpToolNameSegment`: lower-case, `-` becomes `_`). Two Schemas, or two Views, that mangle to the same segment collide. | Schema, View | `MCP_TOOL_NAME_COLLISION` |
-| A Procedure's mangled name must not equal a reserved generic tool name, start with a reserved tool prefix, equal a Schema's mangled segment, or equal another Procedure's mangled name. | Procedure | `MCP_TOOL_NAME_COLLISION` |
-| One MCP Trigger per `(surface, tool name)`. | Trigger | `MCP_TOOL_NAME_COLLISION` |
-| Unique lower-camel identifier within each group (`entries`, `views`, `procedures`, `triggers`) when running `mantle generate`. The identifier joins the `[A-Za-z0-9]+` runs of the name, lower-casing the first and capitalising the rest; `my-orders` and `My Orders` both become `myOrders`. | all kinds | `CODEGEN_IDENTIFIER_COLLISION` |
-
-Names containing `-` must be double-quoted when used as tables in a `sql` View (`"post-translations"`).
-
-## Reserved names
-
-| Namespace | Reserved | Effect |
-|---|---|---|
-| Entry columns | `id`, `status`, `version`, `createdAt`, `updatedAt`, `authorId` | Native on every Schema; a data property may not reuse the name (`INVALID_MANIFEST_ENVELOPE`). Where they may appear in Views and indexes: [Schema reference](./schema.md#reserved-entry-columns) (ADR-0025). |
-| Data field | `locale` | A non-localized Schema that declares `properties.locale` is rejected; use a domain name such as `orderLocale`. On a localized Schema the runtime requires `data.locale` on writes. |
-| Data field | `expectedVersion` | Reserved Procedure OCC wire name. A Schema that declares `spec.schema.properties.expectedVersion` is `INVALID_MANIFEST_ENVELOPE` (ADR-0022). New reserved names need an ADR. |
-| View params | `page`, `show`, `cursor` | Owned by the runtime for pagination. Declaring them under `params.properties` is `VIEW_PARAMS_RESERVED_NAME`. |
-| Builtin input | `id`, `expectedVersion` | Contract fields for builtin `update`, `delete`, `archive`, and version-checked `upsert`. `expectedVersion` is the observed native `entry.version` at read time (not `version+1`). Matched upsert must declare it as a strict number and must not declare `id`. New reserved wire names need an ADR. |
-| MCP tool names | `request_publish`, `unpublish_entry`, `archive_entry`, `delete_entry`, `create_media_upload`, `commit_media_upload` | A Procedure that mangles to one of these is `MCP_TOOL_NAME_COLLISION`. |
-| MCP tool prefixes | `create_draft_`, `update_draft_`, `create_record_`, `update_record_`, `query_view_` | Same as above. |
-| HTTP paths | Every `http` Trigger path must start with `/api/` (`TRIGGER_PATH_INVALID` at validate time). The Cloudflare Worker additionally reserves `/admin`, `/_mantle`, `/api/auth`, `/api/views`, `/oauth`, `/mcp`, any path starting `/.well-known/oauth`, and the exact registrations `*` and `/*`; a Trigger under one of these fails at boot with `TRIGGER_PATH_INVALID`. | See [Trigger](./trigger.md#http-source). |
-
-## Source
-
-- [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.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/SchemaIndexChecker.ts`](../../../packages/mantle-spec/src/domain/service/SchemaIndexChecker.ts)
-- [`packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts`](../../../packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts)
-- [`packages/mantle-spec/src/domain/service/McpToolNaming.ts`](../../../packages/mantle-spec/src/domain/service/McpToolNaming.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/loadManifests.ts`](../../../packages/mantle-spec/src/infrastructure/cli/loadManifests.ts)
-- [`packages/mantle-spec/src/kernel/diagnostic.ts`](../../../packages/mantle-spec/src/kernel/diagnostic.ts)
-- [`packages/mantle/src/codegen/emitMantleModule.ts`](../../../packages/mantle/src/codegen/emitMantleModule.ts)
-- [`packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts`](../../../packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
+Use `input.<name>`, `auth.uid()`, `now()` and supported `mantle.*` functions. Only declared relations and allowed SQL constructs may be referenced. See [Schema](schema.md), [View](view.md), [Procedure](procedure.md), [Trigger](trigger.md) and [CLI](../start/project-and-cli.md).