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

package/dist/build/spec/domain/model/ManifestGrammar.d.ts

@@ -0,0 +1,439 @@
+/**
+ * K8s-style manifest envelope, scoped to the cms group of the mantle universe.
+ *
+ *   apiVersion: cms.mantle.aotter.net/v2
+ *   kind: <Kind>
+ *   metadata: { name }
+ *   spec: { ... kind-specific ... }
+ *
+ * Sibling group `analytics.mantle.aotter.net/v1` lives in the parallel mantle (OLAP)
+ * project and is parsed there — the two systems share lineage and mantle.ai
+ * domain but not parsers.
+ *
+ * The parser rejects keys and enum values outside this shipped grammar.
+ * Future syntax is added only with its implementation.
+ */
+export declare const API_VERSION: "cms.mantle.aotter.net/v2";
+export type ApiVersion = typeof API_VERSION;
+/** Media-shaped `x-mcp-hint` values — the subset marking a field as
+ *  holding a media asset URL. */
+export type MediaMcpHint = "media" | "media-image" | "media-video" | "media-file";
+export declare function isMediaMcpHint(value: unknown): value is MediaMcpHint;
+/** Loose JSON Schema shape — we don't constrain it at the type level.
+ *  Manifest authoring stays JSON Schema; runtime validators translate
+ *  to zod (Workers-CSP-safe). Cross-collection refs use the custom
+ *  keyword `x-mantle-ref: <collectionName>` on string-typed fields holding
+ *  foreign-key IDs; `x-mcp-hint` is a widget-intent hint. The grammar
+ *  accepts strings; the conventional values agents and admin
+ *  widgets understand are `markdown`, `html`, `richtext`, `code`,
+ *  `media`, `media-image`, `media-video`, `media-file`, `money-minor`,
+ *  `timestamp-ms`, and `idempotency-key`. */
+export type JsonSchema = {
+    readonly $defs?: Readonly<Record<string, JsonSchema>>;
+    readonly $ref?: string;
+    readonly oneOf?: readonly JsonSchema[];
+    readonly const?: unknown;
+    readonly type?: string | readonly string[];
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly required?: readonly string[];
+    readonly items?: JsonSchema;
+    readonly enum?: readonly unknown[];
+    readonly format?: string;
+    readonly pattern?: string;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly nullable?: boolean;
+    /** Standard JSON Schema annotation. At the root of a Schema manifest,
+     *  Mantle keeps generic Admin and Admin MCP authoring read-only while
+     *  allowing trusted Procedure handlers to maintain the projection. */
+    readonly readOnly?: boolean;
+    readonly default?: unknown;
+    readonly additionalProperties?: boolean | JsonSchema;
+    /** Standard JSON Schema keyword: help text for this property, shown
+     *  under the admin-UI form field (`entry-edit-view.tsx`) and the
+     *  row-operation dialog's bound-field label fallback
+     *  (`row-operations.tsx`). Accepts a plain string OR the same
+     *  `LocalizedText` locale-map shape used by `Schema.spec.description`
+     *  (#453, mirroring the property `title` keyword's #443 shape) —
+     *  admin-ui resolves it client-side with `resolveLocalizedText`. `en`
+     *  can stay the dev/OpenAPI-doc string while `zh-TW` etc. carry
+     *  operator-readable copy. Optional; absent renders no help text
+     *  (unchanged v0.1 behavior). */
+    readonly description?: LocalizedText;
+    /** Standard JSON Schema keyword (#443): a human-facing label for this
+     *  property, for admin-UI form labels / list column headers /
+     *  operation form labels. Accepts a plain string OR the same
+     *  `LocalizedText` locale-map shape used by `Schema.spec.title` —
+     *  admin-ui resolves it client-side with `resolveLocalizedText`, same
+     *  as any other `LocalizedText` field. Optional; absent means the
+     *  consumer humanizes the property name instead (unchanged v0.1
+     *  behavior). */
+    readonly title?: LocalizedText;
+    /** Custom: cross-collection reference. The string form names the target
+     *  Schema and means the value is that entry's `id`; the object form also
+     *  names the target field (ADR-0029). */
+    readonly "x-mantle-ref"?: string | MantleRefTarget;
+    /** Custom: hint for MCP tool / agent prompt context. */
+    readonly "x-mcp-hint"?: string;
+    readonly [key: string]: unknown;
+};
+export declare const MANTLE_REF_KEYWORD: "x-mantle-ref";
+/**
+ * A property's string options: its `enum`, or a `oneOf` whose every branch is a string `const` (the standard way to give each
+ * option a `title`). Undefined when the property is neither.
+ */
+export declare function enumOptions(property: JsonSchema | undefined): {
+    readonly value: string;
+    readonly title?: LocalizedText;
+}[] | undefined;
+/** Object form of `x-mantle-ref`: which Schema the value points at, and
+ *  which of its fields holds the value (`id` or a single-field unique
+ *  index). */
+export interface MantleRefTarget {
+    readonly schema: string;
+    readonly field: string;
+}
+/** Normalize either `x-mantle-ref` form, or `null` when the property carries
+ *  none (or a malformed value, which graph validation reports). */
+export declare function resolveMantleRef(property: unknown): MantleRefTarget | null;
+export declare const MCP_HINT_KEYWORD: "x-mcp-hint";
+/** A 0.1.x Schema-property keyword; 0.2.0 refuses it (Schema.spec.scope and a Procedure's SQL replace it). */
+export declare const MANTLE_BIND_KEYWORD: "x-mantle-bind";
+/**
+ * A human-facing label/blurb that is either a plain string (single
+ * language, the v0.1 shape) or a map of locale code → string (e.g.
+ * `{ en: "Products", "zh-TW": "商品" }`) so one manifest can serve a
+ * multi-language admin UI. `Schema.spec.title`/`.description`,
+ * `Procedure.spec.title`/`.description`, and `View.spec.title`/`.description`
+ * use this shape; consumers resolve it to a single displayable string
+ * with `resolveLocalizedText`.
+ */
+export type LocalizedText = string | Readonly<Record<string, string>>;
+/** A non-empty string or a non-empty `{ locale: non-empty string }` map. */
+export declare const isLocalizedText: (v: unknown) => v is LocalizedText;
+/**
+ * Resolve a `LocalizedText` value to a single displayable string for
+ * `preferred` (typically the viewer's chosen admin language), falling
+ * back to `canonical` (the site's canonical locale) and finally to the
+ * record's first own-enumerable entry (insertion order). A plain
+ * string is returned as-is — even an empty string, since only
+ * `null`/`undefined` map to `null` here; shape validation (rejecting
+ * empty strings) is the parser's job, not this resolver's. `null` /
+ * `undefined` input (the field was never set) resolves to `null`, and
+ * an empty record (structurally invalid, but resolved defensively)
+ * also resolves to `null` since there is nothing to fall back to.
+ */
+export declare function resolveLocalizedText(value: LocalizedText | null | undefined, preferred: string, canonical?: string | null): string | null;
+/**
+ * Four declarative atoms. Each maps 1-to-1 to a Postgres primitive — see
+ * ADR-0001 / `docs/handbook/concepts/four-atoms.md` for the mapping. `Procedure`
+ * is the only kind with a code seam (handler ref to consumer's TS file).
+ */
+export type ManifestKind = "Schema" | "View" | "Procedure" | "Trigger";
+export interface ManifestMetadata {
+    /** Resource identifier, e.g. `posts`. Required. Globally unique within
+     *  `(kind, deployment)`. */
+    readonly name: string;
+}
+interface ManifestEnvelope<K extends ManifestKind, S> {
+    readonly apiVersion: ApiVersion;
+    readonly kind: K;
+    readonly metadata: ManifestMetadata;
+    readonly spec: S;
+}
+export type SchemaManifest = ManifestEnvelope<"Schema", SchemaManifestSpec>;
+export interface SchemaManifestSpec {
+    /** Human-readable label for the admin UI. Required at v0.1.x —
+     *  the SPA renders this in the sidebar and elsewhere instead of
+     *  the bare `metadata.name`. Either a plain string, or a
+     *  `LocalizedText` map of locale → string (e.g.
+     *  `{ en: "Products", "zh-TW": "商品" }`) so one manifest can serve a
+     *  multi-language admin UI — the SPA resolves it client-side via
+     *  `resolveLocalizedText`. AI authors MUST populate it in the user's
+     *  primary language (the install-time chosen locale) at minimum,
+     *  since end-admin users may not even read English. See ADR-0010 and
+     *  the authoring contract § Schema authoring. */
+    readonly title: LocalizedText;
+    /** Same string-or-locale-map shape as `title`. Optional. */
+    readonly description?: LocalizedText;
+    /** JSON Schema Draft 2020-12 describing per-entry data. May carry the
+     *  property extensions `x-mantle-ref` and `x-mcp-hint`. */
+    readonly schema: JsonSchema;
+    /** Admin-only presentation. Closed Schema roots: `fields`, `list`,
+     *  `nav`. Optional. */
+    readonly uiSchema?: Record<string, unknown>;
+    /** Boolean SQL expressions over this Schema's own columns, enforced by triggers on every insert and update
+     *  (ADR-0034). No subqueries. Example: `stock >= 0`. */
+    readonly checks?: readonly string[];
+    /** Composite unique-index declarations, e.g. `[[slug, locale]]`. */
+    readonly uniqueIndexes?: ReadonlyArray<ReadonlyArray<string>>;
+    /** Ordered composite non-unique indexes over top-level scalar fields. */
+    readonly indexes?: ReadonlyArray<ReadonlyArray<string>>;
+    /** Top-level string fields included in Admin/MCP free-text search.
+     *  Entry id is always searched; absent or empty means id-only. This is
+     *  intentionally independent from `indexes`: substring LIKE queries do
+     *  not benefit from ordinary B-tree indexes. */
+    readonly searchableFields?: readonly string[];
+    /** Whether entries in this collection carry a per-row locale. Default
+     *  `false`. When `true`, `data.locale` MUST be present and ∈ site
+     *  `locales`; when `false`, `data.locale` MUST be absent. See
+     *  ADR-0010. Mutually constrained with `translates`. */
+    readonly localized?: boolean;
+    /** Parent/child translation pattern: this Schema is the translatable
+     *  companion to a non-localized parent Schema, joined by a shared
+     *  field. Requires explicit `localized: true` and at least one
+     *  locale-specific field besides `locale` and the join field. See ADR-0010. */
+    readonly translates?: TranslatesBinding;
+    /** Content-workflow mode. Default `'publishing'` (draft → published →
+     *  archived, no approval queue). `'operational'` marks record
+     *  Schemas (orders, inventory snapshots, audit rows) that are written
+     *  by Procedures rather than authored: entries are live on creation,
+     *  editable in place, and have no publish/unpublish transitions — the
+     *  admin hides the content-lifecycle chrome for them. */
+    readonly lifecycle?: LifecycleMode;
+    /** Logical expiry policy. Physical removal requires an explicit sweep. */
+    readonly ttl?: {
+        readonly field: string;
+        readonly expireAfterSeconds: number;
+    };
+    /** The Schema's row template (ADR-0046 amendment): AND-joined `column = auth.uid()` /
+     *  `column IN auth.user('field')` terms, enforced on every read and write of the Schema. */
+    readonly scope?: string;
+}
+export interface TranslatesBinding {
+    /** Name of the parent Schema this translation table joins to. Must
+     *  resolve to a declared Schema; the parent itself MUST NOT be
+     *  `localized: true` (it carries the non-translatable facts). */
+    readonly parent: string;
+    /** Field present in both parent's and this Schema's
+     *  `spec.schema.properties` and used as the join key. Conventionally
+     *  `slug` for content, but any stable identifier works. */
+    readonly on: string;
+}
+export type LifecycleMode = "publishing" | "operational";
+export type ViewManifest = ManifestEnvelope<"View", ViewManifestSpec>;
+export interface ViewCachePolicy {
+    /** Maximum shared-cache staleness for anonymous REST reads, in seconds. */
+    readonly sharedMaxAge: number;
+}
+export declare const VIEW_SURFACES: readonly ["public", "admin", "internal"];
+export type ViewSurface = (typeof VIEW_SURFACES)[number];
+export interface ViewManifestSpec {
+    /** Human-readable label for the admin UI's report sidebar / report
+     *  page (#443). Same string-or-locale-map `LocalizedText` shape as
+     *  `Schema.spec.title`. Optional — Views didn't carry a title before
+     *  v0.1.x; when absent the admin UI falls back to a Title-Cased
+     *  rendering of `metadata.name`, exactly as before this field
+     *  existed. */
+    readonly title?: LocalizedText;
+    /** What the View answers, for agents and people choosing a query
+     *  (ADR-0029). Projected into the View's MCP tool description; absent
+     *  keeps the generated "Query <surface> View '<name>'." text. */
+    readonly description?: LocalizedText;
+    /** Admin's list for a `surface: admin` View: `uiSchema.list.columns`, and
+     *  `searchFields` / `filterFields`, which Store compiles to `LIKE` and `=`
+     *  conditions on the View's outputs for Admin's search box and filters
+     *  (ADR-0032 decision 5). REST and MCP are unchanged. */
+    readonly uiSchema?: Record<string, unknown>;
+    /** One read-only `SELECT` over declared Schemas (ADR-0034). It reads the
+     *  declared `input` as `input.<name>` and the caller as `auth.uid()` /
+     *  `auth.role()`; the CLI compiles it to the plan's IR. */
+    readonly sql: string;
+    /** Adapter exposure policy.
+     *  `"public"` auto-mounts at the public
+     *  `GET /api/views/<name>` (v0.1 default; `requires` may still gate
+     *  the call). When `"admin"` the View is
+     *  NOT mounted on the public path — it mounts at
+     *  `GET /admin/api/views/<name>` behind the admin gate and becomes
+     *  the report-sidebar source. Guards data behind an admin session; use
+     *  it for any View over sensitive rows. `"internal"` mounts on no
+     *  adapter and is callable only through `runtime.store.as(ctx).view()`. */
+    readonly surface: ViewSurface;
+    /** Optional anonymous REST response-cache policy. Validation limits this
+     *  to public Views that read no caller and no TTL or operational Schema. */
+    readonly cache?: ViewCachePolicy;
+    /** Auth gate. Identical shape to `ProcedureManifestSpec.requires.auth`.
+     *  When absent the View is public — `ExecuteViewUseCase` skips the
+     *  predicate check. When present, ALL predicates must hold; the
+     *  runtime enforces with `evaluateAuthAll`. Closed predicate
+     *  vocabulary: `ctx.user`, `ctx.admin`, `ctx.auth`, and
+     *  `ctx.auth.scope`; an optional guard names one consumer Procedure. */
+    readonly requires?: AuthorizationRequirements;
+    /** Extra row terms per Schema this target reads (ADR-0046): AND-ed onto that Schema's scope; never widens. */
+    readonly restrict?: Readonly<Record<string, string>>;
+    /** Caller-supplied parameters, read in `sql` as `input.<name>`. MUST be
+     *  `type: "object"` with declared `properties`. `limit` and `cursor` are
+     *  reserved: the runtime owns them for pagination. */
+    readonly input?: JsonSchema;
+}
+/** Reserved query-string names on the View REST surface. A View `input` may
+ *  not declare them (`VIEW_INPUT_RESERVED_NAME`). */
+export declare const VIEW_INPUT_RESERVED: readonly ["limit", "cursor"];
+export type ProcedureManifest = ManifestEnvelope<"Procedure", ProcedureManifestSpec>;
+export interface ProcedureManifestSpec {
+    /** Human-readable label for the admin UI's admin-operations surface
+     *  (#430). Same string-or-locale-map `LocalizedText` shape as
+     *  `Schema.spec.title`. Optional — Procedures didn't carry a title
+     *  before v0.1.x; when absent the admin UI falls back to a
+     *  Title-Cased rendering of `metadata.name`. */
+    readonly title?: LocalizedText;
+    /** Same string-or-locale-map shape as `title`. Optional. Surfaced by
+     *  `GET /admin/api/operations` as the operation's `description`
+     *  field (replaces the pre-#430 hack of reading
+     *  `spec.input.description`). */
+    readonly description?: LocalizedText;
+    /** Authorization via `requires.auth.all` plus one optional
+     *  `requires.guard.procedure`; static predicates are closed to
+     *  `ctx.user`, `ctx.admin`, `ctx.auth`, and `ctx.auth.scope`. */
+    readonly requires?: AuthorizationRequirements;
+    /** Extra row terms per Schema this target reads (ADR-0046): AND-ed onto that Schema's scope; never widens. */
+    readonly restrict?: Readonly<Record<string, string>>;
+    /** JSON Schema for the request body. */
+    readonly input: JsonSchema;
+    /** Admin-only field widget choices. Does not affect input validation
+     *  or the MCP tool schema. */
+    readonly uiSchema?: Record<string, unknown>;
+    /** JSON Schema for the response body. */
+    readonly output: JsonSchema;
+    /** Handler binding: `{ ref }` (consumer supplies a handler map) or
+     *  `{ sql }` (write statements, compiled to the plan's IR; ADR-0034). */
+    readonly handler: HandlerBinding;
+    /** MCP tool annotations the author declares because Core cannot infer
+     *  them for a `ref` handler (#972). They override the generated defaults
+     *  (`procedureAnnotations`);
+     *  An `x-mcp-hint: idempotency-key` input does not infer an
+     *  `idempotentHint` annotation in 0.2. A `readOnlyHint: true` on a `sql`
+     *  handler, which always writes, is rejected at validation. */
+    readonly mcp?: ProcedureMcpAnnotations;
+    /** The entity the handler mutates and whose version it locks
+     *  (ADR-0029). Needed only for entity-bound interactions and automatic
+     *  version binding. */
+    readonly target?: ProcedureTarget;
+}
+export interface ProcedureTarget {
+    /** Target Schema. */
+    readonly schema: string;
+    /** Required string input property carrying the target entry id. */
+    readonly id: string;
+    /** Number input property carrying the observed version, when locked. */
+    readonly version?: string;
+}
+export declare const PROCEDURE_TARGET_KEYS: readonly ["schema", "id", "version"];
+export interface ProcedureMcpAnnotations {
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly openWorldHint?: boolean;
+}
+export declare const PROCEDURE_MCP_ANNOTATION_KEYS: readonly ["readOnlyHint", "destructiveHint", "openWorldHint"];
+export type HandlerBinding = HandlerRefBinding | HandlerSqlBinding;
+export interface HandlerRefBinding {
+    /** Opaque registration key (NOT a path). The consumer passes a matching
+     *  key in the runtime/Worker `handlers` map. */
+    readonly ref: string;
+}
+/** One or more write statements (`INSERT`, `UPDATE`, `DELETE`), applied as
+ *  one batch. Reads `input.<name>`, `auth.uid()`, `auth.role()`, `now()`. */
+export interface HandlerSqlBinding {
+    readonly sql: string;
+}
+/** Closed predicate vocabulary. `ctx.user` and `ctx.auth` are bare
+ *  strings; `ctx.admin` and `ctx.auth.scope` carry scalar data under
+ *  literal object keys.
+ */
+export interface AuthorizationRequirements {
+    readonly auth?: {
+        readonly all: readonly AuthPredicate[];
+    };
+    /** Dynamic, consumer-owned authorization check. The named Procedure
+     *  receives the target's validated input/params and the same
+     *  HandlerContext before the target executes. */
+    readonly guard?: {
+        readonly procedure: string;
+    };
+}
+export type AuthPredicate = CtxUserPredicate | "ctx.admin" | CtxAuthPredicate | CtxAuthScopePredicate;
+export type CtxUserPredicate = "ctx.user";
+/** Requires any verified credential normalized into HandlerContext.auth. */
+export type CtxAuthPredicate = "ctx.auth";
+/** Requires one opaque, consumer-owned scope. Repeat under `all` for
+ *  multiple required scopes. */
+export interface CtxAuthScopePredicate {
+    readonly "ctx.auth.scope": string;
+}
+/** Role names are application-owned; the privileged layer comes from Better Auth. */
+export type AdminRole = string;
+export declare function isAdminRole(s: string): s is AdminRole;
+export type TriggerManifest = ManifestEnvelope<"Trigger", TriggerManifestSpec>;
+export interface TriggerManifestSpec {
+    readonly source: TriggerSource;
+    /** The Procedure invoked when this Trigger fires. */
+    readonly target: {
+        readonly procedure: string;
+    };
+}
+/** Supported Trigger sources. */
+export type TriggerSource = HttpTriggerSource | LifecycleTriggerSource | McpTriggerSource | ScheduleTriggerSource;
+/** Five-field POSIX cron expression in UTC (weekday 0 = Sunday). Registration remains host-owned. */
+export interface ScheduleTriggerSource {
+    readonly kind: "schedule";
+    readonly cron: string;
+    readonly enabled?: boolean;
+}
+export interface HttpTriggerSource {
+    readonly kind: "http";
+    readonly method: HttpMethod;
+    /** OpenAPI `{param}` syntax. Path params auto-bind to identically-named
+     *  fields on the target Procedure's `input`. No optional segments. */
+    readonly path: string;
+}
+/** Shipped v0.1 lifecycle hook vocabulary: before/after ×
+ *  create/update/delete plus the publish boundary. New entries require an
+ *  explicit grammar-revise round. */
+export declare const LIFECYCLE_HOOKS: readonly ["before_create", "after_create", "before_update", "after_update", "before_delete", "after_delete", "before_publish", "after_publish"];
+export type LifecycleHook = (typeof LIFECYCLE_HOOKS)[number];
+export interface LifecycleTriggerSource {
+    readonly kind: "lifecycle";
+    /** Schema this Trigger watches (`Schema.metadata.name`). */
+    readonly schema: string;
+    /** Hooks bound by this Trigger. Non-empty. */
+    readonly on: readonly LifecycleHook[];
+}
+/** Surfaces an MCP-source Trigger can be bound to. `admin` ⇒
+ *  `/mcp/admin` (bearer + role gate); `public` ⇒ `/mcp` (bearer only).
+ *  The procedure's own `requires.auth` still gates the call —
+ *  surface determines visibility in `tools/list`. */
+export declare const MCP_TRIGGER_SURFACES: readonly ["admin", "public"];
+export type McpTriggerSurface = (typeof MCP_TRIGGER_SURFACES)[number];
+export interface McpTriggerSource {
+    readonly kind: "mcp";
+    /** Which MCP surface this Procedure is callable from. The
+     *  Procedure's `requires.auth` continues to evaluate against the
+     *  authenticated caller — surface only controls discovery. */
+    readonly surface: McpTriggerSurface;
+}
+/** v0.1 HTTP methods that may carry a body. GET is intentionally absent
+ *  — read endpoints are Views, not Procedures. */
+export type HttpMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+export type Manifest = SchemaManifest | ViewManifest | ProcedureManifest | TriggerManifest;
+/** Storage-row metadata columns reserved across every Schema. Used by
+ *  the View SQL compiler (to project them as native columns rather
+ *  than `json_extract`) and by the type emitter (to surface them on
+ *  every Entry interface). Adding a new reserved column is a grammar
+ *  revise — touch this constant + every consumer. */
+export declare const RESERVED_ENTRY_COLUMNS: readonly ["id", "status", "version", "createdAt", "updatedAt", "authorId"];
+/**
+ * Reserved Procedure input wire names. `expectedVersion` is the observed
+ * native `entry.version` at read time (not version+1). First-party Admin/SDK
+ * bind and hide it; other callers supply it. Schema `spec.schema.properties`
+ * must not collide — validate is fail-closed (`INVALID_MANIFEST_ENVELOPE`).
+ * New reserved names need an ADR (ADR-0022).
+ */
+export declare const EXPECTED_VERSION_PROPERTY: "expectedVersion";
+/** Rules between an input object's fields: only View and Procedure input takes them, and AI tool catalogues advertise them as sentences. */
+export declare const INPUT_RULE_KEYWORDS: readonly ["dependentRequired", "anyOf", "if", "then", "else"];
+export declare const RESERVED_PROCEDURE_INPUT_NAMES: readonly ["expectedVersion"];
+export {};

package/dist/build/spec/domain/model/RuntimePlan.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The sealed plan (ADR-0032 decision 5, ADR-0034): what the CLI compiles from the manifests and Core executes.
+ * Every SQL source is already IR here, so no Worker parses SQL. Pure types and constants.
+ */
+import type { AuthorizationRequirements, JsonSchema, LocalizedText, ProcedureMcpAnnotations, ProcedureTarget, TriggerSource } from "./ManifestGrammar.js";
+import type { SqlNode, SqlPlan } from "./SqlIr.js";
+import type { UserScope, UserFieldSpec } from "./UserFields.js";
+export declare const RUNTIME_PLAN_VERSION: 6;
+/** A Schema as storage and Store see it. Keys of `fields` and `names` are lower case: SQL folds unquoted identifiers. */
+export interface PlanSchema {
+    readonly userScopes?: readonly UserScope[];
+    /** The name as declared: the key of `schemas` is lower case. */
+    readonly name: string;
+    readonly title?: LocalizedText;
+    readonly description?: LocalizedText;
+    /** Admin-only presentation, opaque to Core. */
+    readonly uiSchema?: Readonly<Record<string, unknown>>;
+    readonly localized?: boolean;
+    readonly scope?: string;
+    readonly ttl?: string;
+    readonly ttlSeconds?: number;
+    readonly publishing?: boolean;
+    /** column -> Mantle type: text integer real bool json timestamptz date numeric(p,s) geo */
+    readonly fields: Readonly<Record<string, string>>;
+    /** lower-cased column -> the name the JSON Schema declares */
+    readonly names: Readonly<Record<string, string>>;
+    /** The Schema's JSON Schema: Store validates the values of a write against it. */
+    readonly schema: JsonSchema;
+    /** Boolean expressions over the row's own columns, as IR. */
+    readonly checks?: readonly SqlNode[];
+    /** A translation publishes only once the parent entry that shares `on` is published (ADR-0010). Names as declared. */
+    readonly translates?: {
+        readonly parent: string;
+        readonly on: string;
+    };
+    readonly search?: readonly string[];
+    readonly unique?: readonly (readonly string[])[];
+    readonly indexes?: readonly (readonly string[])[];
+}
+/** A target's extra row terms per Schema (`restrict`): AND-ed onto that Schema's scope, never dropped by `{ all: true }`. */
+export type PlanRestrict = Readonly<Record<string, {
+    readonly owner?: string;
+    readonly terms: readonly UserScope[];
+}>>;
+export interface PlanView extends SqlPlan {
+    readonly restrict?: PlanRestrict;
+    readonly title?: LocalizedText;
+    readonly description?: LocalizedText;
+    readonly uiSchema?: Readonly<Record<string, unknown>>;
+    /** input property -> Mantle type */
+    readonly inputs: Readonly<Record<string, string>>;
+    readonly input?: JsonSchema;
+    /** The SQL as authored, which Admin shows; the IR (`stmts`) is what runs. */
+    readonly source: string;
+    readonly surface: "public" | "admin" | "internal";
+    readonly requires?: AuthorizationRequirements;
+    /** `spec.cache.sharedMaxAge`: REST lets a shared cache keep an anonymous read this many seconds. Only an unguarded public View has it. */
+    readonly sharedMaxAge?: number;
+    /** Output name -> the Schema field it reads unchanged (`SELECT t.f`, `t.f AS f`, `*`, `created_at`) or a `sum`/`min`/`max` of it; the Store decodes these as `select` does. */
+    readonly columns?: Readonly<Record<string, {
+        readonly schema: string;
+        readonly field: string;
+    }>>;
+}
+export interface PlanProcedure {
+    readonly restrict?: PlanRestrict;
+    readonly trustedOnly?: true;
+    readonly title?: LocalizedText;
+    readonly description?: LocalizedText;
+    readonly uiSchema?: Readonly<Record<string, unknown>>;
+    readonly input: JsonSchema;
+    readonly output: JsonSchema;
+    /** input property -> Mantle type, for an inline `sql` handler */
+    readonly inputs: Readonly<Record<string, string>>;
+    readonly requires?: AuthorizationRequirements;
+    readonly target?: ProcedureTarget;
+    readonly mcp?: ProcedureMcpAnnotations;
+    /** An inline handler carries its SQL as authored (`source`), which Admin shows; the IR is what runs. */
+    readonly handler: {
+        readonly ref: string;
+    } | {
+        readonly sql: SqlPlan;
+        readonly source: string;
+    };
+}
+export interface PlanTrigger {
+    readonly source: TriggerSource;
+    readonly procedure: string;
+}
+/** A statement as the dialect printed it at `mantle generate` (ADR-0044). Binds are Core's BindSpec as JSON. */
+export interface LoweredStatement {
+    readonly sql: string;
+    readonly binds: readonly {
+        readonly k: string;
+        readonly [key: string]: unknown;
+    }[];
+    readonly kind: "read" | "row" | "set";
+    readonly schema?: string;
+    readonly verb?: "insert" | "update" | "delete";
+    /** Omitted when false. */
+    readonly hooked?: true;
+    /** Omitted when false. */
+    readonly publish?: true;
+    /** The policy AST has a RETURNING clause. */
+    readonly returns?: true;
+    /** A write's table, lower case (D1's unique-conflict op mapping). */
+    readonly target?: string;
+}
+/** A paged statement of a View under one request shape, printed. The page size is a bind (`limit`), so one statement serves every page size. */
+export interface LoweredPage {
+    readonly sql: string;
+    /** Where each extra bind comes from on a request, after the View's own binds: a cursor key, the search pattern, an equality value or the page size + 1. */
+    readonly sources: readonly ({
+        readonly cursor: number;
+    } | {
+        readonly search: true;
+    } | {
+        readonly eq: number;
+    } | {
+        readonly limit: true;
+    })[];
+    readonly flat?: true;
+    readonly names: readonly string[];
+    readonly nkeys: number;
+}
+export interface LoweredView extends LoweredStatement {
+    /** The length of the policy AST's sort clause. */
+    readonly nkeys: number;
+    /** By Core's page shape key (`pageShape`): no cursor, and a cursor whose every key is non-null. */
+    readonly paged: Readonly<Record<string, LoweredPage>>;
+}
+export type LoweredMode = "caller" | "public" | "trusted";
+/** What `mantle generate` printed for the plan's dialect (ADR-0044): text, bind recipes and paging metadata, never ASTs. */
+export interface PlanLowered {
+    /** The `@aotter/mantle` version that lowered. */
+    readonly mantle: string;
+    /** The dialect's name and version, and its `lowerKey` ("" when absent): a runtime on another uses none of it. */
+    readonly dialect: {
+        readonly name: string;
+        readonly version: string;
+        readonly key: string;
+    };
+    readonly views: Readonly<Record<string, Readonly<Partial<Record<LoweredMode, LoweredView>>>>>;
+    readonly procedures: Readonly<Record<string, Readonly<Partial<Record<"caller" | "trusted", readonly LoweredStatement[]>>>>>;
+}
+export interface RuntimePlan {
+    readonly access?: {
+        readonly roles: readonly string[];
+        readonly userFields: Readonly<Record<string, UserFieldSpec>>;
+        readonly warnings: readonly string[];
+    };
+    readonly version: typeof RUNTIME_PLAN_VERSION;
+    /** The dialect the SQL was compiled for (ADR-0035 decision 5); boot refuses a storage of another. */
+    readonly dialect: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** SHA-256 of the plan without this field (`planFingerprint`). */
+    readonly fingerprint: string;
+    readonly schemas: Readonly<Record<string, PlanSchema>>;
+    readonly views: Readonly<Record<string, PlanView>>;
+    readonly procedures: Readonly<Record<string, PlanProcedure>>;
+    readonly triggers: Readonly<Record<string, PlanTrigger>>;
+    /** Optional, covered by the fingerprint, and ignored by a runtime it does not match (ADR-0044). */
+    readonly lowered?: PlanLowered;
+}
+/** System-column type metadata for View output lineage. */
+export declare const NATIVE_OUTPUT_TYPES: Readonly<Record<string, string>>;