@lunora/codegen 1.0.0-alpha.15 → 1.0.0-alpha.150

package/dist/index.d.mts

@@ -1,14 +1,177 @@
-import { Finding } from '@lunora/advisor';
+import { AdvisorExportSink, AdvisorGeoIndexUsage, AdvisorNotifyCall, AdvisorNotifyConfig, Finding, LintContext, AdvisorProcedureProtection } from '@lunora/advisor';
 export type { Finding } from '@lunora/advisor';
-import { Node, Project } from 'ts-morph';
-import { StudioFeaturesResult } from '@lunora/do';
+import { Project, Node } from 'ts-morph';
+import { LunoraError } from '@lunora/errors';
+export { MESSAGE_SOLUTIONS as LUNORA_SOLUTION_RULES, type Solution as LunoraSolution, type SolutionRule as LunoraSolutionRule, findSolutionByMessage as findLunoraSolution } from '@lunora/errors';
+import { StudioFeaturesResult } from '@lunora/shard-engine';
 import { Schema } from '@lunora/server';
 import { JsonSchema } from '@lunora/values';
+import { LanguageName } from 'quicktype-core';
+/** Current snapshot format version. Bumped if the structural shape below changes. */
+declare const SCHEMA_SNAPSHOT_VERSION: 1;
+/**
+ * A single field's structural shape.
+ *
+ * `kind` + `optional` were once the whole record, which made every change INSIDE
+ * a validator invisible to the diff, to the serialized baseline, and to the
+ * content hash — `v.id("users")` → `v.id("orgs")`, `v.array(v.string())` →
+ * `v.array(v.bigint())` (which changes the storage projection), a swapped union
+ * member, an added `.unique()`. Zero drift, byte-identical snapshot, same hash,
+ * so `recordSchemaVersion` did not even append a ledger row.
+ *
+ * Everything past `optional` is therefore recorded too. All of it is declared
+ * OPTIONAL so a baseline written before the deepening still parses (no
+ * {@link SCHEMA_SNAPSHOT_VERSION} bump, which `parseSnapshotJson` would turn into
+ * a hard reject with no upgrade path) — see {@link recordsFieldDetail} for how the
+ * differ tells "this baseline predates the detail" from "this field has none".
+ */
+interface FieldSnapshot {
+  /** `v.object({…})` member shapes, key-sorted. */
+  fields?: Record<string, FieldSnapshot>;
+  /** `v.record(key, …)` key shape. */
+  key?: FieldSnapshot;
+  /** The validator kind (`string`, `number`, `id`, `object`, …) after unwrapping `v.optional`. */
+  kind: string;
+  /** `v.literal(value)` — the literal as source text. */
+  literal?: string;
+  /** `v.union(…)` members, in canonical (not declaration) order — a union is a set. */
+  members?: ReadonlyArray<FieldSnapshot>;
+  /** `.nullable()` — the column accepts SQL NULL. Always written by a current snapshot. */
+  nullable?: boolean;
+  /** `v.array(inner)` element / `v.record(…, value)` value shape. */
+  of?: FieldSnapshot;
+  /** True when declared `v.optional(...)` — accepts `undefined` / absent on insert. */
+  optional: boolean;
+  /** `v.id("table")` — the referenced table. */
+  ref?: string;
+  /**
+   * A `.check()`/`.max()`/`.email()`/… predicate is declared on the column. Only
+   * its PRESENCE is knowable — the IR cannot represent the closure — so
+   * `.max(200)` → `.max(500)` stays invisible; adding the first refinement to a
+   * populated column does not.
+   */
+  refined?: boolean;
+  /** `.unique()`. Always written by a current snapshot — see {@link recordsFieldDetail}. */
+  unique?: boolean;
+}
+/** A single secondary index's structural shape. */
+interface IndexSnapshot {
+  fields: ReadonlyArray<string>;
+  unique: boolean;
+}
+/** A single relation's structural shape. */
+interface RelationSnapshot {
+  field: string;
+  kind: "many" | "one";
+  table: string;
+}
+/** Structural snapshot of one table. */
+interface TableSnapshot {
+  /** Field name → {@link FieldSnapshot}, in declared order. */
+  fields: Record<string, FieldSnapshot>;
+  /** Index name → {@link IndexSnapshot}. */
+  indexes: Record<string, IndexSnapshot>;
+  /** Relation accessor name → {@link RelationSnapshot}. */
+  relations: Record<string, RelationSnapshot>;
+  /**
+   * `"root"` (default single-DO), `"global"` (D1-replicated), or
+   * `"shardBy:<field>"` (partitioned). Encoded as a string so the snapshot
+   * stays a plain JSON-stable value.
+   */
+  shardMode: string;
+}
+/** A deterministic structural view of the whole schema at one point in time. */
+interface SchemaSnapshot {
+  /**
+   * Cloudflare DO data-residency jurisdiction declared via `.jurisdiction("…")`,
+   * or absent. Tracked because changing it strands all existing Durable Object
+   * data (a DO name maps to a different ID per jurisdiction). Optional, so old
+   * baselines written before this field parse cleanly (absent ⇒ undefined).
+   *
+   * Typed as a plain `string` (not the authoring union) on purpose: this is
+   * STORED data that a newer Lunora may have written with a jurisdiction this
+   * version doesn't yet know. Preserving the raw value keeps the breaking
+   * `changedJurisdiction` diff correct under a downgrade — coercing an unknown
+   * value to `undefined` would fail OPEN and hide the most destructive change.
+   */
+  jurisdiction?: string;
+  /** Sorted list of every declared `defineMigration` id at capture time. */
+  migrationIds: ReadonlyArray<string>;
+  /** Table name → {@link TableSnapshot}, keys sorted for stable serialization. */
+  tables: Record<string, TableSnapshot>;
+  version: typeof SCHEMA_SNAPSHOT_VERSION;
+}
+/**
+ * Whether a change is anchored to one table's own shape, or to the schema as a
+ * whole.
+ *
+ * This is the signal a UI needs to decide which tables to mark as changed, and
+ * it lives HERE — next to the change union it classifies — rather than as a
+ * hand-maintained set of type names in the consumer. A set in the consumer gives
+ * zero compile-time pressure: adding a variant to `DriftChange["type"]` would
+ * silently render an affected table as untouched, which is exactly the
+ * UI-disagrees-with-the-deploy-gate divergence this module exists to prevent.
+ */
+type DriftScope = "schema" | "table";
+/**
+ * What actually fixes a change, so a consumer can name the right tool.
+ *
+ * - `"backfill"` — a `defineMigration` transform rewrites the affected rows.
+ *   The ONLY value for which a data migration is the answer.
+ * - `"rehome"` — the rows' physical storage moves (a different Durable Object,
+ *   or a different region). The per-shard runner only ever replaces a row inside
+ *   the shard it was handed, so no transform reaches these; the fix is an
+ *   export/import round trip, or a revert.
+ * - `"code"` — nothing happens to stored data; a query or a call site has to
+ *   change (a dropped index, a dropped relation).
+ * - `"none"` — additive, nothing to do.
+ *
+ * This lives HERE, next to the change union, for the same reason {@link DriftScope}
+ * does: a hand-maintained set of type names in the consumer gives zero
+ * compile-time pressure, so a new variant would silently default to whatever the
+ * set omits. The deploy gate uses this to decide both what a data migration may
+ * excuse and which tables it offers to scaffold one for — a wrong default there
+ * sends the operator to a tool that cannot work.
+ */
+type DriftRemediation = "backfill" | "code" | "none" | "rehome";
+/** One classified structural change between two snapshots. */
+interface DriftChange {
+  /** What fixes this change — see {@link DriftRemediation}. `"none"` for every `safe` change. */
+  remediation: DriftRemediation;
+  /**
+   * `"table"` means this table's own DDL moved (fields, indexes, shard mode) —
+   * a relation whose foreign key lives on the OTHER table stays `"schema"`, so
+   * the "changed" signal keeps meaning "this table's shape moved".
+   */
+  scope: DriftScope;
+  /** `"breaking"` changes need attention before deploy; `"safe"` changes are additive. */
+  severity: "breaking" | "safe";
+  /** Human-readable, actionable description (used in the gate message). */
+  summary: string;
+  /** The table this change belongs to. Always set when `scope` is `"table"`. */
+  table?: string;
+  /** A machine-readable change discriminator. */
+  type: "addedFieldConstraint" | "addedIndex" | "addedOptionalField" | "addedRelation" | "addedRequiredField" | "addedTable" | "changedFieldKind" | "changedFieldShape" | "changedIndex" | "changedJurisdiction" | "changedShardMode" | "fieldOptionalToRequired" | "fieldRequiredToOptional" | "relaxedFieldConstraint" | "removedField" | "removedIndex" | "removedRelation" | "removedTable" | "widenedFieldShape";
+}
+/** The result of diffing two snapshots: every classified change. */
+interface SchemaDrift {
+  /** Every classified change, in a stable order (added/changed per table, then removals). */
+  changes: ReadonlyArray<DriftChange>;
+}
+/** Serialize a snapshot to the exact bytes written to `lunora/.lunora-schema.json` (trailing newline). */
+declare const serializeSchemaSnapshot: (snapshot: SchemaSnapshot) => string;
+/**
+ * Diff the current snapshot against a baseline and classify every structural
+ * change. Pure — no I/O. When `baseline` is `undefined` (no snapshot yet) there
+ * is no drift to report: every table is treated as a fresh additive
+ * `addedTable`, so a first deploy is never blocked.
+ */
+declare const diffSchemaSnapshots: (baseline: SchemaSnapshot | undefined, current: SchemaSnapshot) => SchemaDrift;
 /**
-* AST-observable subset of a column's modifier chain (`.unique()`, `.default()`,
-* …). Function-valued modifiers (`.$defaultFn`/`.$onUpdateFn`) can't be
-* serialized, so only their *presence* is recorded.
-*/
+ * AST-observable subset of a column's modifier chain (`.unique()`, `.default()`,
+ * …). Function-valued modifiers (`.$defaultFn`/`.$onUpdateFn`) can't be
+ * serialized, so only their *presence* is recorded.
+ */
 interface ColumnMetaIR {
   /** `.default(...)` or `.$defaultFn(...)` present — field is optional on insert. */
   hasDefault?: boolean;
@@ -26,13 +189,12 @@ interface ValidatorIR {
   /** Column modifiers (`.unique()`, `.default()`, `.nullable()`, …) when present. */
   column?: ColumnMetaIR;
   /**
-  * `true` when this validator carries a `.check(...)` refinement. The predicate
-  * is a runtime closure the AST→IR step can't represent, so the node keeps its
-  * base `kind` but records the refinement's presence here. The AOT args-validator
-  * compiler declines any node with this flag (compiling it would silently skip
-  * the predicate). `.meta(...)` is pure metadata with no parse effect and does
-  * NOT set this.
-  */
+   * `true` when this validator carries a refinement (`.check(...)`, `.max(n)`,
+   * `.email()`, …) — anything that narrows the accepted values without changing
+   * the kind. `schema-drift` hashes this, so a bound counts here even when it is
+   * modelled below. `.meta(...)` is pure metadata with no parse effect and does
+   * NOT set it.
+   */
   hasRefinement?: boolean;
   /** For `v.optional(inner)` / `v.array(inner)`. */
   inner?: ValidatorIR;
@@ -48,8 +210,30 @@ interface ValidatorIR {
   shape?: Record<string, ValidatorIR>;
   /** Verbatim source text — used in emitted code when we can't reconstruct from AST. */
   sourceText?: string;
+  /**
+   * The `n` of a `v.string().max(n)` written with a numeric literal — the one
+   * refinement predicate the IR can represent exactly (`value.length <= n`).
+   * The AOT compiler emits it as a guard instead of declining the node, which
+   * is what keeps a length-bounded public argument on the fast path.
+   */
+  stringMaxLength?: number;
   /** For `v.id("table")` — the table name. */
   tableName?: string;
+  /**
+   * For `v.from(externalSchema)` — the wrapped Standard Schema's inferred type,
+   * rendered as TS source. Recovered through the type checker from
+   * `~standard.types.output`, mirroring the runtime's `InferStandardOutput`.
+   * Absent when it could not be recovered safely, in which case the emitted
+   * type falls back to `unknown`.
+   */
+  tsType?: string;
+  /**
+   * `true` when this validator carries a refinement the IR could NOT model — a
+   * `.check(...)` closure, `.email()`, `.pattern(re)`, a `.max()` whose bound is
+   * not a literal. The AOT args-validator compiler declines any node with this
+   * flag, because compiling it would silently skip the predicate.
+   */
+  unmodelledRefinement?: boolean;
   valueType?: ValidatorIR;
 }
 interface IndexIR {
@@ -58,11 +242,32 @@ interface IndexIR {
   unique?: boolean;
 }
 interface SearchIndexIR {
-  /** Primary text-search field. */
+  /** Primary text-search field; a dot-separated path reads a nested field. */
   field: string;
   /** Optional filter fields surfaced alongside the FTS column. */
   filterFields?: ReadonlyArray<string>;
+  /** Text-analysis profile (accent folding + that language's stopwords). */
+  language?: string;
+  name: string;
+  /** Skip the migration-time backfill of the search companion (large tables index out-of-band). */
+  staged?: boolean;
+  /** `"native"` opts into the engine's own full-text index where it has one (Postgres). */
+  strategy?: string;
+}
+/** A `.geoIndex(name, { field, precision? })` declaration — a geohash companion over a `v.geoPoint()` column. */
+interface GeoIndexIR {
+  /** The `v.geoPoint()` column feeding the geohash. */
+  field: string;
   name: string;
+  /** Geohash precision (characters) maintained on the companion; omitted ⇒ the runtime default. */
+  precision?: number;
+}
+/** A `.ttl(field, { after? })` declaration — declarative table-level auto-expiry. */
+interface TtlIR {
+  /** Millisecond offset added to `field` to derive the expiry (`field + after`); omitted ⇒ `field` is the absolute expiry. */
+  after?: number;
+  /** The epoch-millisecond expiry column. */
+  field: string;
 }
 interface VectorIndexIR {
   dimensions?: number;
@@ -76,19 +281,19 @@ interface VectorIndexIR {
   table: string;
 }
 /**
-* One ordering key on a rank index's `sortBy`: the column and direction.
-* Mirrors the runtime `RankSortKey` (defaults `direction` to `"asc"`).
-*/
+ * One ordering key on a rank index's `sortBy`: the column and direction.
+ * Mirrors the runtime `RankSortKey` (defaults `direction` to `"asc"`).
+ */
 interface RankSortKeyIR {
   direction: "asc" | "desc";
   field: string;
 }
 /**
-* A `.rankIndex(name, { sortBy, partitionBy?, where? })` declaration. The owning
-* table is always the table the index is declared on, so — unlike a vector index
-* — there is no separate `on`/`table` reference to carry: it rides along on its
-* {@link TableIR}. Only the fields needed for type emission are captured.
-*/
+ * A `.rankIndex(name, { sortBy, partitionBy?, where? })` declaration. The owning
+ * table is always the table the index is declared on, so — unlike a vector index
+ * — there is no separate `on`/`table` reference to carry: it rides along on its
+ * {@link TableIR}. Only the fields needed for type emission are captured.
+ */
 interface RankIndexIR {
   name: string;
   /** Columns scoping each ranking; omitted ⇒ one global rank over the table. */
@@ -109,21 +314,93 @@ interface RelationIR {
   /** Target table name. */
   table: string;
 }
+/**
+ * Statically-discovered `.source(...)` config (plan 077). Only the bits the
+ * advisor lints + DO wiring need are captured; `map`/`tenantBy` are functions and
+ * cannot be serialized, so their presence is recorded as `hasTenantBy` rather than
+ * the function itself.
+ */
+interface ExternalSourceIR {
+  /** The wrangler Hyperdrive binding name. */
+  binding: string;
+  /** Whether a `columns` projection allow-list was given. */
+  columns?: ReadonlyArray<string>;
+  /** `true` when a `reconcileEveryMs` was given — one of the two incremental delete-visibility paths the `external_source_incremental_no_delete_path` lint checks. */
+  hasReconcile?: boolean;
+  /** `true` when a `softDeleteColumn` was given — the other incremental delete-visibility path. */
+  hasSoftDelete?: boolean;
+  /** `true` when a `tenantBy` mapper was given — the tenant-isolation boundary the `external_source_unscoped` lint checks. */
+  hasTenantBy: boolean;
+  /** The `idColumn` literal, when given (defaults to `"id"` at runtime). */
+  idColumn?: string;
+  /** Delete-detection mode literal, when given (`"full-pull"` today). */
+  mode?: string;
+  /** The membership query literal, when statically knowable. */
+  query?: string;
+  /**
+   * `true` when `.source(...)` was present but its argument was **not** a static
+   * object literal (e.g. `.source(buildConfig())`), so none of the fields above
+   * could be read. The source still exists — this flag lets `hasSourcedTables`
+   * (codegen) and the `external_source_*` lints treat it as a source that can't be
+   * verified, instead of mistaking it for no `.source()` at all.
+   */
+  unanalyzable?: boolean;
+}
 interface TableIR {
   /**
-  * `true` when the table chain carried `.externallyManaged()` — its rows are
-  * written outside Lunora's discoverable insert path (adapter/migration/
-  * middleware), so advisor insert-path lints skip it. Optional: hand-built
-  * IR and the runtime `fromServerSchema` path default it to `false`.
-  */
+   * `true` when the table chain carried `.commitOrdered()` — every row carries
+   * `_commitSeq`, a per-shard integer allocated once per mutation and strictly
+   * increasing in commit order. Optional: hand-built IR and tables that never
+   * called `.commitOrdered()` default it to `false`.
+   */
+  commitOrdered?: boolean;
+  /**
+   * The `defineSchemaExtension` key that contributed this table, set when it
+   * arrived through `defineSchema(...).extend(...)`. Absent for a table the app
+   * declared itself.
+   *
+   * Drives the generated `AppTableName` union: an add-on's tables
+   * (`ratelimit_buckets`, …) are real tables and stay in `TableName`, but an app
+   * enumerating "my tables" should not have to know about them.
+   */
+  extensionKey?: string;
+  /**
+   * `true` when the table chain carried `.externallyManaged()` — its rows are
+   * written outside Lunora's discoverable insert path (adapter/migration/
+   * middleware), so advisor insert-path lints skip it. Optional: hand-built
+   * IR and the runtime `fromServerSchema` path default it to `false`.
+   */
   externallyManaged?: boolean;
   /**
-  * Storage backend for a `.global()` table: `"d1"` (default) or
-  * `"hyperdrive"` (a Postgres/MySQL database via Cloudflare Hyperdrive). Only
-  * meaningful when `shardMode === "global"`; absent for sharded/root tables.
-  */
+   * Set when the chain carried `.source(...)` — the table is materialized from an
+   * external Hyperdrive-backed database by a system poll loop (plan 077). Carries
+   * the statically-knowable bits the advisor lints read; the functions (`map`,
+   * `tenantBy`) are not serialized, only their presence (`hasTenantBy`).
+   */
+  externalSource?: ExternalSourceIR;
+  /**
+   * Storage backend for a `.global()` table: `"d1"` (default) or
+   * `"hyperdrive"` (a Postgres/MySQL database via Cloudflare Hyperdrive). Only
+   * meaningful when `shardMode === "global"`; absent for sharded/root tables.
+   */
+  /** Geospatial indexes declared inline via `.geoIndex(name, …)`. Optional so hand-built IR may omit it (discovery always sets it). */
+  geoIndexes?: ReadonlyArray<GeoIndexIR>;
   globalBackend?: "d1" | "hyperdrive";
   indexes: ReadonlyArray<IndexIR>;
+  /**
+   * `true` when the table chain carried `.public()` — an explicit opt-OUT of
+   * the schema's `.rls("required")` enforcement for this one table. Optional:
+   * hand-built IR and tables that never called `.public()` default it to
+   * `false`.
+   */
+  isPublic?: boolean;
+  /**
+   * `true` when the table chain carried `.memory()` — its rows are cleared on
+   * every Durable Object cold start and never reach the CDC changelog.
+   * Optional: hand-built IR and tables that never called `.memory()` default it
+   * to `false`.
+   */
+  memory?: boolean;
   name: string;
   /** Rank indexes declared inline via `.rankIndex(name, …)`. */
   rankIndexes: ReadonlyArray<RankIndexIR>;
@@ -139,6 +416,8 @@ interface TableIR {
   softDelete?: {
     field: string;
   };
+  /** Set when the chain carried `.ttl(field, { after? })` — the declarative auto-expiry policy read by the DO alarm sweep. */
+  ttl?: TtlIR;
   /** Vector indexes declared inline via `.vectorize()` (DSL Shape A). */
   vectorIndexes: ReadonlyArray<VectorIndexIR>;
 }
@@ -146,54 +425,100 @@ interface TableIR {
 type JurisdictionIR = "eu" | "fedramp" | "us";
 interface SchemaIR {
   /**
-  * Cloudflare data-residency jurisdiction declared via
-  * `defineSchema(...).jurisdiction("…")`. Emitted into the generated worker's
-  * `createWorker({ jurisdiction })` (and `ctx.scheduler` / `ctx.containers`).
-  * Absent ⇒ un-pinned.
-  */
+   * Cloudflare data-residency jurisdiction declared via
+   * `defineSchema(...).jurisdiction("…")`. Emitted into the generated worker's
+   * `createWorker({ jurisdiction })` (and `ctx.scheduler` / `ctx.containers`).
+   * Absent ⇒ un-pinned.
+   */
   jurisdiction?: JurisdictionIR;
+  /**
+   * Set when `defineSchema(...).rls("required")` was chained onto the schema —
+   * every table's `ctx.db` write path is denied without an RLS-covering
+   * procedure unless the table itself is `.public()` (see {@link TableIR.isPublic}).
+   * Absent when the schema never called `.rls("required")`.
+   */
+  rlsMode?: "required";
   tables: ReadonlyArray<TableIR>;
   /** All vector indexes (inline Shape A hoisted + standalone Shape B), flattened. */
   vectorIndexes: ReadonlyArray<VectorIndexIR>;
 }
+/**
+ * Statically-read mirror of `@lunora/server`'s `RestCacheConfig`. Every field is
+ * optional because discovery only records literals it could actually read off the
+ * `.expose({ cache: … })` object.
+ */
+interface ExposeCacheIR {
+  maxAge?: number;
+  scope?: "private" | "public";
+  staleWhileRevalidate?: number;
+  tag?: string;
+  vary?: string;
+}
 interface FunctionIR {
   args: Record<string, ValidatorIR>;
   exportName: string;
-  /** Path relative to `&lt;projectRoot>/lunora/` without extension, e.g. "messages". */
+  /**
+   * Set by the `.expose({ rest: true })` builder modifier (plan 167). When
+   * `rest` is `true` the function is published on the public REST surface, so the
+   * OpenAPI emitter describes it as a real `/_lunora/rest/<namespace>/<fn>` path
+   * (the single source of truth the runtime router also derives from). Absent →
+   * RPC-only (the default; not on the REST surface).
+   *
+   * `cache` mirrors the `RestCacheConfig` the runtime turns into response
+   * headers, so the emitted spec can document the `Cache-Control` a caller will
+   * actually observe. Only statically-readable literal fields are carried; a
+   * computed value is simply absent (the spec under-documents rather than lies).
+   */
+  expose?: {
+    cache?: ExposeCacheIR;
+    rest?: boolean;
+  };
+  /** Path relative to `<projectRoot>/lunora/` without extension, e.g. "messages". */
   filePath: string;
   kind: "action" | "mutation" | "query" | "stream";
   /**
-  * Set on connection-lifecycle hooks (`onConnect`/`onDisconnect`): the socket
-  * side the hook fires on. Such a function is also an internal mutation (so it
-  * lands in `LUNORA_FUNCTIONS` for path dispatch); emit additionally collects
-  * it into the `LUNORA_LIFECYCLE_HOOKS` manifest keyed by this side. Absent on
-  * ordinary functions.
-  */
-  lifecycle?: "connect" | "disconnect";
-  /**
-  * Serialized TS source for the handler's return type, with `Promise&lt;T>`
-  * unwrapped so callers see `T` directly. Defaults to `"unknown"` when
-  * ts-morph cannot resolve the type (typically because the consuming
-  * project lacks a tsconfig that can reach `@lunora/server`).
-  */
+   * Set on connection-lifecycle hooks (`onConnect`/`onDisconnect`): the socket
+   * side the hook fires on. Such a function is also an internal mutation (so it
+   * lands in `LUNORA_FUNCTIONS` for path dispatch); emit additionally collects
+   * it into the `LUNORA_LIFECYCLE_HOOKS` manifest keyed by this side. Absent on
+   * ordinary functions.
+   */
+  lifecycle?: "connect" | "disconnect" | "init" | "reactor";
+  /**
+   * The `.output(validator)` declaration, when the chain has one.
+   *
+   * Takes precedence over {@link FunctionIR.returnType} (the handler's
+   * inferred type) for the emitted `FunctionReference`. `.output()` is what
+   * validates at runtime and what a reader takes as the contract, so the two
+   * must agree — see the emit-side note for what went wrong when they did not.
+   */
+  output?: ValidatorIR;
+  /**
+   * Serialized TS source for the handler's return type, with `Promise<T>`
+   * unwrapped so callers see `T` directly. Defaults to `"unknown"` when
+   * ts-morph cannot resolve the type (typically because the consuming
+   * project lacks a tsconfig that can reach `@lunora/server`).
+   */
   returnType: string;
   /**
-  * Call surface the function is exposed on. Absent (or `"public"`) means it
-  * lands in the generated `api`; `"internal"` routes it to the separate
-  * `internal` object and is rejected by the DO's external RPC path.
-  */
+   * Call surface the function is exposed on. Absent (or `"public"`) means it
+   * lands in the generated `api`; `"internal"` routes it to the separate
+   * `internal` object and is rejected by the DO's external RPC path.
+   */
   visibility?: "internal" | "public";
 }
 /**
-* A `defineMigration({...})` declaration discovered in the user's lunora
-* sources. The emitted `LUNORA_MIGRATIONS` registry keys on {@link MigrationIR.id}; the
-* import wiring needs {@link MigrationIR.exportName}/{@link MigrationIR.filePath}. {@link MigrationIR.table} is
-* informational (the runtime object carries the authoritative value).
-*/
+ * A `defineMigration({...})` declaration discovered in the user's lunora
+ * sources. The emitted `LUNORA_MIGRATIONS` registry keys on {@link MigrationIR.id}; the
+ * import wiring needs {@link MigrationIR.exportName}/{@link MigrationIR.filePath}. The runtime object
+ * carries the authoritative {@link MigrationIR.table}, but the lifted value is
+ * load-bearing at build time: the schema-drift gate matches it against the
+ * tables with breaking drift, so a migration left at `""` covers nothing.
+ */
 interface MigrationIR {
   /** Export binding name, used to reference the module member in generated imports. */
   exportName: string;
-  /** Path relative to `&lt;projectRoot>/lunora/` without extension, e.g. "migrations". */
+  /** Path relative to `<projectRoot>/lunora/` without extension, e.g. "migrations". */
   filePath: string;
   /** Stable migration id — the registry key and per-shard run-state key. */
   id: string;
@@ -201,12 +526,109 @@ interface MigrationIR {
   table: string;
 }
 /**
-* A single cron job lifted from a `cronJobs()` builder in `lunora/crons.ts`.
-* Mirrors `@lunora/scheduler`'s `CronJob`: {@link CronJobIR.cron} is the compiled
-* standard cron expression, {@link CronJobIR.functionPath} is the target
-* `__lunoraRef` (`namespace:fn`), and {@link CronJobIR.args} is the static
-* argument object passed at registration.
-*/
+ * A `defineShape({...})` declaration discovered in `lunora/shapes.ts`
+ * (local-first sync engine, Phase 7). The emitted `LUNORA_SHAPES` registry keys
+ * on {@link ShapeIR.exportName}; the generated DO's `resolveShape` override
+ * dispatches a `shape_subscribe` to the matching registered shape. Discovery is
+ * marker-driven (the `__lunoraShape` brand) — no field metadata is lifted here
+ * because the runtime object (`columns`/`compileWhere`) carries the authority.
+ */
+interface ShapeIR {
+  /**
+   * The shape's `args` validator map — its partition selector. Lifted so
+   * `_generated/collections.ts` can type the selector a caller passes instead of
+   * widening it to `Record<string, unknown>`. `{}` for a parameterless shape.
+   */
+  args: Record<string, ValidatorIR>;
+  /** Export binding name — the shape's registry key and import member. */
+  exportName: string;
+  /** Path relative to `<projectRoot>/lunora/` without extension — always `"shapes"`. */
+  filePath: string;
+  /**
+   * The `table` string literal from the `defineShape({ table })` call, lifted
+   * only for static advisor lints (the runtime object stays authoritative).
+   * `undefined` when `table` is not a plain string literal — lints skip those.
+   */
+  table?: string;
+}
+/**
+ * The single `defineIdentity({...})` claim contract discovered in
+ * `lunora/identity.ts`. Discovery is **marker-driven** (the `__lunoraIdentity`
+ * brand, exactly like {@link ShapeIR}) — no claim metadata is lifted here
+ * because the emitted `_generated/server.ts` recovers the claim *type* from the
+ * declaration itself (`InferIdentity` over the contract's `typeof`), and the
+ * runtime object (`validate`/`onInvalid`) carries the authority at the boundary.
+ * Exactly one per app; absent ⇒ generated output is byte-identical to today.
+ */
+interface IdentityIR {
+  /** Export binding name — the namespace member `_generated/server.ts` reads via `typeof`. */
+  exportName: string;
+}
+/**
+ * The single `defineEnv({...})` contract discovered in `lunora/env.ts`. Like
+ * {@link IdentityIR}, only the export binding is lifted — the emitted
+ * `_generated/server.ts` recovers the validated shape from the declaration
+ * itself (`ReturnType` over the accessor's `typeof`), and the generated ShardDO
+ * applies the same accessor to the worker `env` at ctx-build time to populate
+ * `ctx.env`. Exactly one per app; absent ⇒ generated output is byte-identical.
+ */
+interface EnvIR {
+  /** Export binding name — the namespace member `_generated/server.ts` reads via `typeof`. */
+  exportName: string;
+}
+/**
+ * A `defineMutator({...})` declaration discovered in `lunora/mutators.ts`
+ * (local-first sync engine, Phase 7). The emitted registry registers the
+ * authoritative `server` impl into the DO's `LUNORA_FUNCTIONS` table (so
+ * `handleRpc` transaction-wraps it) and records its path in
+ * `LUNORA_MUTATOR_PATHS` so the DO's `isCustomMutator` override routes the
+ * client-watermark push protocol. The client `client` impl is split into the
+ * browser bundle separately — only the path crosses to the server side.
+ */
+interface MutatorIR {
+  /**
+   * The mutator's `args` validator map, parsed exactly as a procedure's is, so
+   * the emitted `api.mutators.<name>` reference carries the arg type a client
+   * `defineMutator` infers instead of restating. `{}` for a parameterless
+   * mutator (or one whose `args` isn't an inline object literal).
+   */
+  args: Record<string, ValidatorIR>;
+  /** Export binding name — the mutator's registry key and import member. */
+  exportName: string;
+  /** Path relative to `<projectRoot>/lunora/` without extension — always `"mutators"`. */
+  filePath: string;
+  /**
+   * Serialized TS source for the authoritative `server` impl's return type,
+   * `Promise<T>` unwrapped. `"unknown"` when ts-morph can't resolve it — same
+   * contract as {@link FunctionIR.returnType}.
+   */
+  returnType: string;
+}
+/**
+ * A whole-row `ctx.db.replace(id, document)` write discovered inside a custom
+ * mutator's inline `server` impl (`lunora/mutators.ts`) — the input the
+ * `mutator_full_row_replace` advisor lint consumes. A `replace` overwrites the
+ * entire row, so a concurrent edit to a different column on a synced table is
+ * clobbered; `ctx.db.patch(id, { field })` merges at the column level instead.
+ * Structurally identical to `AdvisorMutatorWrite` so it passes straight through
+ * to the advisor without conversion, exactly as `InsertWriteIR` does for
+ * `AdvisorInsertWrite`.
+ */
+interface MutatorWriteIR {
+  /** The mutator export whose `server` impl performs the replace, e.g. `renameChannel`. */
+  exportName: string;
+  /** Openable source path the replace appears in — always `lunora/mutators.ts`. */
+  file: string;
+  /** 1-based line of the `replace(...)` call. */
+  line: number;
+}
+/**
+ * A single cron job lifted from a `cronJobs()` builder in `lunora/crons.ts`.
+ * Mirrors `@lunora/scheduler`'s `CronJob`: {@link CronJobIR.cron} is the compiled
+ * standard cron expression, {@link CronJobIR.functionPath} is the target
+ * `__lunoraRef` (`namespace:fn`), and {@link CronJobIR.args} is the static
+ * argument object passed at registration.
+ */
 interface CronJobIR {
   /** Static args object (source-text JSON), defaults to `{}`. */
   args: Record<string, unknown>;
@@ -217,25 +639,25 @@ interface CronJobIR {
   /** Unique, human-readable job name. */
   name: string;
   /**
-  * Set when the job targets a durable workflow (a `lunora/workflows.ts`
-  * export) instead of a function: the workflow's `WORKFLOW_*` binding name
-  * plus its export name. On each fire the worker starts a new workflow
-  * INSTANCE (the {@link CronJobIR.args} become its `params`) rather than
-  * dispatching a one-shot function.
-  */
+   * Set when the job targets a durable workflow (a `lunora/workflows.ts`
+   * export) instead of a function: the workflow's `WORKFLOW_*` binding name
+   * plus its export name. On each fire the worker starts a new workflow
+   * INSTANCE (the {@link CronJobIR.args} become its `params`) rather than
+   * dispatching a one-shot function.
+   */
   workflow?: {
     binding: string;
     exportName: string;
   };
 }
 /**
-* A container lifted from a `defineContainer()` export in
-* `lunora/containers.ts`. Carries everything the emitters and the config layer
-* need to wire wrangler (`containers[]` + the Durable Object binding +
-* migration class) and the generated `_generated/containers.ts` DO class.
-* Names are derived via `@lunora/container`'s shared helpers so codegen and
-* the config layer can never disagree.
-*/
+ * A container lifted from a `defineContainer()` export in
+ * `lunora/containers.ts`. Carries everything the emitters and the config layer
+ * need to wire wrangler (`containers[]` + the Durable Object binding +
+ * migration class) and the generated `_generated/containers.ts` DO class.
+ * Names are derived via `@lunora/container`'s shared helpers so codegen and
+ * the config layer can never disagree.
+ */
 interface ContainerIR {
   /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
   bindingName: string;
@@ -244,18 +666,18 @@ interface ContainerIR {
   /** Generated DO class name, e.g. `TranscoderContainer`. */
   className: string;
   /**
-  * Whether the container may open outbound internet connections, when the
-  * value was a static literal. `undefined` means the field was omitted (the
-  * platform default is `true`) or wasn't a literal. Lifted for the advisor.
-  */
+   * Whether the container may open outbound internet connections, when the
+   * value was a static literal. `undefined` means the field was omitted (the
+   * platform default is `true`) or wasn't a literal. Lifted for the advisor.
+   */
   enableInternet?: boolean;
   /** The `lunora/containers.ts` export name, e.g. `transcoder`. */
   exportName: string;
   /**
-  * Normalized image source: a local Dockerfile (`dockerfile`), a pre-built
-  * registry reference (`registry`), or a Railpack source directory (`build`)
-  * that the deploy step builds and pushes before wrangler runs.
-  */
+   * Normalized image source: a local Dockerfile (`dockerfile`), a pre-built
+   * registry reference (`registry`), or a Railpack source directory (`build`)
+   * that the deploy step builds and pushes before wrangler runs.
+   */
   image: {
     buildContext: string;
     dockerfilePath: string;
@@ -283,20 +705,20 @@ interface ContainerIR {
     stepPercentage?: number;
   };
   /**
-  * The static `sleepAfter` value, when it was a literal. `undefined` means
-  * omitted (platform default `"10m"`) or non-literal. Lifted for the advisor.
-  */
+   * The static `sleepAfter` value, when it was a literal. `undefined` means
+   * omitted (platform default `"10m"`) or non-literal. Lifted for the advisor.
+   */
   sleepAfter?: number | string;
 }
 /**
-* A workflow lifted from a `defineWorkflow()` export in `lunora/workflows.ts`.
-* Carries what the emitters and the config layer need to wire the wrangler
-* `workflows[]` entry and the generated `_generated/workflows.ts`
-* `WorkflowEntrypoint` class. Unlike containers, workflows are NOT Durable
-* Objects — wrangler gets only a `workflows[]` entry, never a `durable_objects`
-* binding or a migration class. Names are derived via `@lunora/workflow`'s
-* shared helpers so codegen and the config layer can never disagree.
-*/
+ * A workflow lifted from a `defineWorkflow()` export in `lunora/workflows.ts`.
+ * Carries what the emitters and the config layer need to wire the wrangler
+ * `workflows[]` entry and the generated `_generated/workflows.ts`
+ * `WorkflowEntrypoint` class. Unlike containers, workflows are NOT Durable
+ * Objects — wrangler gets only a `workflows[]` entry, never a `durable_objects`
+ * binding or a migration class. Names are derived via `@lunora/workflow`'s
+ * shared helpers so codegen and the config layer can never disagree.
+ */
 interface WorkflowIR {
   /** The Cloudflare `Workflow` binding name, e.g. `WORKFLOW_ORDER_PIPELINE`. */
   bindingName: string;
@@ -305,21 +727,97 @@ interface WorkflowIR {
   /** The `lunora/workflows.ts` export name, e.g. `orderPipeline`. */
   exportName: string;
   /**
-  * The stable wrangler `workflows[].name`. Defaults to the kebab-cased export
-  * name (`orderPipeline` → `order-pipeline`); a static `name:` literal in the
-  * definition overrides it.
-  */
+   * The stable wrangler `workflows[].name`. Defaults to the kebab-cased export
+   * name (`orderPipeline` → `order-pipeline`); a static `name:` literal in the
+   * definition overrides it.
+   */
+  name: string;
+  /**
+   * Durable step labels lifted from the handler body — the first string-literal
+   * argument of every `ctx.step.do` / `.sleep` / `.sleepUntil` / `.waitForEvent`
+   * call. Feeds the duplicate-step-name lint, which flags a name used twice
+   * (Cloudflare memoizes by name, so the second call silently returns the
+   * first's cached result). Calls with a non-literal name are omitted (not
+   * statically comparable).
+   */
+  steps: ReadonlyArray<WorkflowStepIR>;
+}
+/**
+ * An agent lifted from a `defineAgent()` export in `lunora/agents.ts`. A
+ * `defineAgent` compiles its durable tool-loop onto a Cloudflare Workflow, so —
+ * like {@link WorkflowIR} — an agent is NOT a Durable Object: wrangler gets only
+ * a `workflows[]` entry, never a `durable_objects` binding or a migration class.
+ * Carries what the emitters and the config layer need to wire the generated
+ * agent `WorkflowEntrypoint` class (e.g. `SupportAgentWorkflow`), the typed
+ * per-agent `ctx.agents` producer, and the reconciled wrangler `workflows[]`
+ * entry. Names are derived via `@lunora/agent`'s shared helpers so codegen and
+ * the config layer can never disagree.
+ */
+interface AgentIR {
+  /** The Cloudflare `Workflow` binding name, e.g. `AGENT_SUPPORT`. */
+  bindingName: string;
+  /** Generated `WorkflowEntrypoint` class name, e.g. `SupportAgentWorkflow`. */
+  className: string;
+  /** The `lunora/agents.ts` export name, e.g. `support`. */
+  exportName: string;
+  /**
+   * The stable wrangler `workflows[].name`. Defaults to the kebab-cased export
+   * name (`support` → `agent-support`); a static `name:` literal in the
+   * definition overrides it.
+   */
+  name: string;
+  /**
+   * Whether the definition declares an `onEmail` mapper on
+   * `defineAgent({ onEmail: … })`. When `true` the emitter wires this agent
+   * onto the worker's top-level `email()` handler (via `@lunora/agent/inbound`)
+   * so inbound mail starts a durable run. Detected by AST PRESENCE — the
+   * closure is never evaluated — and written to IR only when present, so
+   * email-free agents (and agent-free projects) stay byte-identical.
+   */
+  onEmail?: boolean;
+  /**
+   * Whether the definition opted into public run-starts via
+   * `defineAgent({ publicRun: true })` — emitted into the `ctx.agents` wiring
+   * spec so the public `agents:agentRun` mutation can gate on it fail-closed.
+   * Absent (falsy) means server-side starts only; the field is written to IR
+   * only when the literal is `true`, so agent-free and non-opted-in output is
+   * byte-identical.
+   */
+  publicRun?: boolean;
+  /**
+   * Whether the definition opted into a real-time voice session via a `voice`
+   * block on `defineAgent({ voice: … })`. Unlike the durable loop (a Workflow),
+   * the voice path IS a Durable Object — so when this is `true` the emitter
+   * generates the `voiceClassName` `VoiceSessionDO` subclass and the
+   * `api.agents.{name}Voice` client reference, and the config layer reconciles
+   * a `durable_objects` binding (`voiceBindingName`) + `new_sqlite_classes`
+   * migration. Written to IR only when the literal is present, so voice-free
+   * agents (and agent-free projects) stay byte-identical.
+   */
+  voice?: boolean;
+  /** The voice DO's Cloudflare `DurableObjectNamespace` binding name, e.g. `VOICE_SUPPORT`. Present only when `voice`. */
+  voiceBindingName?: string;
+  /** Generated `VoiceSessionDO` subclass name, e.g. `SupportVoiceDO`. Present only when `voice`. */
+  voiceClassName?: string;
+}
+/** One durable step call lifted from a workflow handler body (the use side of {@link WorkflowIR.steps}). */
+interface WorkflowStepIR {
+  /** 1-based line of the durable step call. */
+  line: number;
+  /** The native step method invoked: `do` / `sleep` / `sleepUntil` / `waitForEvent`. */
+  method: string;
+  /** The step's static label (the first string-literal argument). */
   name: string;
 }
 /**
-* A queue lifted from a `defineQueue()` export in `lunora/queues.ts`. Carries
-* what the emitters and the config layer need to wire the typed `ctx.queues`
-* producer, the generated worker `queue()` dispatch, and the wrangler
-* `queues.producers[]` / `queues.consumers[]` entries. Like workflows, a queue
-* is NOT a Durable Object — wrangler gets only `queues.*` entries. Names are
-* derived via `@lunora/queue`'s shared helpers so codegen and the config layer
-* can never disagree.
-*/
+ * A queue lifted from a `defineQueue()` export in `lunora/queues.ts`. Carries
+ * what the emitters and the config layer need to wire the typed `ctx.queues`
+ * producer, the generated worker `queue()` dispatch, and the wrangler
+ * `queues.producers[]` / `queues.consumers[]` entries. Like workflows, a queue
+ * is NOT a Durable Object — wrangler gets only `queues.*` entries. Names are
+ * derived via `@lunora/queue`'s shared helpers so codegen and the config layer
+ * can never disagree.
+ */
 interface QueueIR {
   /** The Cloudflare `Queue` producer binding name, e.g. `QUEUE_EMAIL`. */
   bindingName: string;
@@ -328,10 +826,10 @@ interface QueueIR {
   /** How the queue is consumed: `"push"` (a worker `queue()` handler) or `"pull"` (external HTTP). */
   mode: "pull" | "push";
   /**
-  * The stable wrangler queue name (`queues.producers[].queue`). Defaults to
-  * the kebab-cased export name (`emailQueue` → `email-queue`); a static
-  * `name:` literal in the definition overrides it.
-  */
+   * The stable wrangler queue name (`queues.producers[].queue`). Defaults to
+   * the kebab-cased export name (`emailQueue` → `email-queue`); a static
+   * `name:` literal in the definition overrides it.
+   */
   name: string;
   /** Push-consumer batch/retry tuning, mirrored onto the wrangler `queues.consumers[]` entry. */
   tuning: {
@@ -343,42 +841,42 @@ interface QueueIR {
   };
 }
 /**
-* The feature-flag provider declared by the default export of `lunora/flags.ts`
-* (`defineFlags({ provider, … })`). Discovery is **metadata-only** — codegen
-* imports the real module at runtime for the provider value; this IR exists so
-* the config layer can reconcile/validate the wrangler `flagship` binding when
-* the app uses Flagship in binding mode. A `custom` provider (any other
-* OpenFeature factory) carries no binding to reconcile.
-*/
+ * The feature-flag provider declared by the default export of `lunora/flags.ts`
+ * (`defineFlags({ provider, … })`). Discovery is **metadata-only** — codegen
+ * imports the real module at runtime for the provider value; this IR exists so
+ * the config layer can reconcile/validate the wrangler `flagship` binding when
+ * the app uses Flagship in binding mode. A `custom` provider (any other
+ * OpenFeature factory) carries no binding to reconcile.
+ */
 interface FlagsIR {
   /**
-  * The wrangler `flagship[].binding` name — set **only** for a flagship
-  * `provider` in binding mode (`flagshipProvider({ binding: "FLAGS" })`). The
-  * config layer hints/validates a matching `flagship` binding from this.
-  */
+   * The wrangler `flagship[].binding` name — set **only** for a flagship
+   * `provider` in binding mode (`flagshipProvider({ binding: "FLAGS" })`). The
+   * config layer hints/validates a matching `flagship` binding from this.
+   */
   bindingName?: string;
   /**
-  * Flagship operating mode — `"binding"` (wrangler binding, needs a
-  * `flagship` entry) or `"http"` (no binding); `undefined` for a `custom`
-  * provider or when the mode can't be read statically.
-  */
+   * Flagship operating mode — `"binding"` (wrangler binding, needs a
+   * `flagship` entry) or `"http"` (no binding); `undefined` for a `custom`
+   * provider or when the mode can't be read statically.
+   */
   mode?: "binding" | "http";
   /** `"flagship"` when the provider is `flagshipProvider(...)`, else `"custom"` (any other OpenFeature provider factory). */
   provider: "custom" | "flagship";
 }
 /**
-* A `ctx.workflows.get("name")…` call discovered in a function body — the
-* use-site analog of {@link WorkflowIR} (which is the declaration side). Feeds
-* the `workflow_unused` lint (a declared workflow with zero call sites) and the
-* `workflow_unknown_target` lint (a `.get("x")` whose `x` isn't declared — a
-* typo catcher). {@link WorkflowCallIR.workflow} is `""` when the `get(...)`
-* argument is not a string literal (a dynamic name — which suppresses the
-* unused-workflow heuristic rather than producing a false positive).
-*/
+ * A `ctx.workflows.get("name")…` call discovered in a function body — the
+ * use-site analog of {@link WorkflowIR} (which is the declaration side). Feeds
+ * the `workflow_unused` lint (a declared workflow with zero call sites) and the
+ * `workflow_unknown_target` lint (a `.get("x")` whose `x` isn't declared — a
+ * typo catcher). {@link WorkflowCallIR.workflow} is `""` when the `get(...)`
+ * argument is not a string literal (a dynamic name — which suppresses the
+ * unused-workflow heuristic rather than producing a false positive).
+ */
 interface WorkflowCallIR {
   /** Export binding name of the function performing the call, e.g. `create`. */
   exportName: string;
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension (the api namespace). */
+  /** Source file relative to `<projectRoot>/lunora/`, without extension (the api namespace). */
   file: string;
   /** 1-based line of the `get(...)` call. */
   line: number;
@@ -386,14 +884,24 @@ interface WorkflowCallIR {
   workflow: string;
 }
 /**
-* A `ctx.db.query("table")…` read discovered in a function body, reduced to what
-* the `filter_without_index` advisor lint needs: which table, whether the chain
-* narrows with an index, and whether it filters. `table` is `""` when the
-* `query(...)` argument is not a string literal (a dynamic table — not lintable).
-*/
+ * A `ctx.db.query("table")…` read discovered in a function body, reduced to what
+ * the query advisor lints need: which table, whether the chain narrows with an
+ * index, whether it filters, and which terminal materializes the result.
+ * `table` is `""` when the `query(...)` argument is not a string literal (a
+ * dynamic table — not lintable).
+ */
 interface QueryReadIR {
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  /** Exported procedure the read sits in, or `""` at module scope. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
+  /**
+   * True when the chain's `.filter()` predicate compares `_id`
+   * (`(d) => d._id === args.id`) — a full scan for a row that `ctx.db.get`
+   * addresses directly. Optional so a feeder predating this field still
+   * typechecks; absent is treated as "not a primary-key filter".
+   */
+  filtersPrimaryKey?: boolean;
   /** The chain calls `.filter(...)`. */
   hasFilter: boolean;
   /** The chain narrows with `.withIndex(...)` or `.withSearchIndex(...)`. */
@@ -402,18 +910,30 @@ interface QueryReadIR {
   line: number;
   /** Queried table name, or `""` when the argument is not a string literal. */
   table: string;
+  /**
+   * The materializing call the chain ends in — `"collect"`, `"take"`,
+   * `"paginate"`, `"first"`, `"unique"`, … — i.e. how much of the narrowed set
+   * the read actually loads.
+   *
+   * `undefined` when the chain reaches no recognised terminal (a reader passed
+   * on, a bare `query(...)`) AND when a feeder predating this field produced
+   * the read. The two are deliberately not distinguished: no consumer could act
+   * on the difference, so the terminal-shaped lints skip the read either way
+   * rather than guessing a terminal.
+   */
+  terminal?: string;
 }
 /**
-* A `ctx.authApi.&lt;method>(...)` call discovered in a function body, attributed
-* to the exported function (and its file = api namespace) that performs it.
-* Structurally identical to `AdvisorAuthApiCall` so it passes straight through
-* to the advisor lint without conversion, exactly as `InsertWriteIR` does for
-* `AdvisorInsertWrite`.
-*/
+ * A `ctx.authApi.<method>(...)` call discovered in a function body, attributed
+ * to the exported function (and its file = api namespace) that performs it.
+ * Structurally identical to `AdvisorAuthApiCall` so it passes straight through
+ * to the advisor lint without conversion, exactly as `InsertWriteIR` does for
+ * `AdvisorInsertWrite`.
+ */
 interface AuthApiCallIR {
   /** Export binding name of the function performing the call, e.g. "createOrg". */
   exportName: string;
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** True when the call's argument object includes a `headers` property. */
   hasHeaders: boolean;
@@ -423,16 +943,16 @@ interface AuthApiCallIR {
   method: string;
 }
 /**
-* A `ctx.db.insert("table", …)` write discovered in a function body, attributed
-* to the exported function (and its file = api namespace) that performs it — the
-* write-side analog of {@link QueryReadIR}. Lets tooling wire a table's write
-* action by behavior (which function inserts into it) rather than by naming.
-* {@link InsertWriteIR.table} is `""` when the argument is not a string literal.
-*/
+ * A `ctx.db.insert("table", …)` write discovered in a function body, attributed
+ * to the exported function (and its file = api namespace) that performs it — the
+ * write-side analog of {@link QueryReadIR}. Lets tooling wire a table's write
+ * action by behavior (which function inserts into it) rather than by naming.
+ * {@link InsertWriteIR.table} is `""` when the argument is not a string literal.
+ */
 interface InsertWriteIR {
   /** Export binding name of the function performing the insert, e.g. "send". */
   exportName: string;
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension (the api namespace). */
+  /** Source file relative to `<projectRoot>/lunora/`, without extension (the api namespace). */
   file: string;
   /** 1-based line of the `insert(...)` call. */
   line: number;
@@ -440,20 +960,20 @@ interface InsertWriteIR {
   table: string;
 }
 /**
-* A non-deterministic API call (`Date.now`, `Math.random`, `crypto.randomUUID`,
-* `crypto.getRandomValues`, `fetch`) discovered lexically inside a `query(...)`
-* or `mutation(...)` handler body — the `nondeterministic_query_mutation` lint
-* input. Structurally identical to `AdvisorNondeterministicCall` so values pass
-* straight through to the advisor without conversion, exactly as `AuthApiCallIR`
-* does for `AdvisorAuthApiCall`. `action(...)` handlers are never recorded —
-* actions are the determinism escape hatch.
-*/
+ * A non-deterministic API call (`Date.now`, `Math.random`, `crypto.randomUUID`,
+ * `crypto.getRandomValues`, `fetch`) discovered lexically inside a `query(...)`
+ * or `mutation(...)` handler body — the `nondeterministic_query_mutation` lint
+ * input. Structurally identical to `AdvisorNondeterministicCall` so values pass
+ * straight through to the advisor without conversion, exactly as `AuthApiCallIR`
+ * does for `AdvisorAuthApiCall`. `action(...)` handlers are never recorded —
+ * actions are the determinism escape hatch.
+ */
 interface NondeterministicCallIR {
   /** The non-deterministic API invoked, e.g. `Date.now` / `Math.random` / `crypto.randomUUID` / `fetch`. */
   callee: string;
   /** Export binding name of the function performing the call, e.g. `sendMessage`. */
   exportName: string;
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension (the api namespace). */
+  /** Source file relative to `<projectRoot>/lunora/`, without extension (the api namespace). */
   file: string;
   /** Which procedure kind the call lives in — only `query`/`mutation` handlers are recorded. */
   kind: "mutation" | "query";
@@ -461,15 +981,18 @@ interface NondeterministicCallIR {
   line: number;
 }
 /**
-* One `ctx.r2sql` access lexically inside a `query`/`mutation` handler — the
-* `r2sql_outside_action` advisor lint input. Structurally identical to the
-* advisor's `AdvisorR2sqlCall` (same field set) so values pass straight through
-* `lintSchema` without conversion, exactly as `NondeterministicCallIR` does.
-* Only `query`/`mutation` handlers are recorded; `action(...)` is the intended
-* home for `ctx.r2sql` and is skipped.
-*/
-interface R2sqlCallIR {
-  /** The accessed `ctx.r2sql` surface, e.g. `ctx.r2sql.query` / `ctx.r2sql.from`. */
+ * One `ctx.<property>` access lexically inside a `query`/`mutation` handler —
+ * the feeder shape behind every "action-only surface used outside an action"
+ * advisor lint (`hyperdrive_outside_action` for `ctx.sql`,
+ * `r2sql_outside_action` for `ctx.r2sql`). Structurally identical to the
+ * advisor's `AdvisorHyperdriveCall` / `AdvisorR2sqlCall` (same field set) so
+ * values pass straight through `lintSchema` without conversion, exactly as
+ * {@link NondeterministicCallIR} does. Only `query`/`mutation` handlers are
+ * recorded; `action(...)` is the only context where these surfaces are even
+ * typed, so it is the intended home and is skipped.
+ */
+interface ContextPropertyCallIR {
+  /** The accessed surface, e.g. `ctx.sql.query` / `ctx.r2sql.from` — the property, suffixed with the method when one is called on it. */
   callee: string;
   /** Export binding name of the function performing the access. */
   exportName: string;
@@ -477,25 +1000,25 @@ interface R2sqlCallIR {
   file: string;
   /** Which procedure kind the access lives in — only `query`/`mutation` handlers are recorded. */
   kind: "mutation" | "query";
-  /** 1-based line of the access, or `0` when unknown. */
+  /** 1-based line of the access. */
   line: number;
 }
 /**
-* Per-procedure RLS usage snapshot, produced by `discoverRlsProcedures` for the
-* `rls_uncovered_table` advisor lint. Structurally identical to
-* `AdvisorRlsProcedure` (they share the same field set) so values pass straight
-* through to the advisor without conversion, exactly as `AuthApiCallIR` does for
-* `AdvisorAuthApiCall`.
-*/
+ * Per-procedure RLS usage snapshot, produced by `discoverRlsProcedures` for the
+ * `rls_uncovered_table` advisor lint. Structurally identical to
+ * `AdvisorRlsProcedure` (they share the same field set) so values pass straight
+ * through to the advisor without conversion, exactly as `AuthApiCallIR` does for
+ * `AdvisorAuthApiCall`.
+ */
 interface RlsProcedureIR {
   /** Export binding name of the procedure (e.g. `listDocuments`). */
   exportName: string;
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /**
-  * Table names extracted from the `rls(policies)` array literal. Empty when the
-  * policies argument is not a statically-readable array literal.
-  */
+   * Table names extracted from the `rls(policies)` array literal. Empty when the
+   * policies argument is not a statically-readable array literal.
+   */
   rlsTables: string[];
   /** Tables read by the procedure via `ctx.db.query/findMany/findFirst/…`. */
   tablesRead: string[];
@@ -507,22 +1030,22 @@ interface RlsProcedureIR {
   visibility: "internal" | "public";
 }
 /**
-* One procedure reduced to the facts the `mask_uncovered_pii_column` lint needs:
-* whether its builder chain includes `.use(mask(...))`, which `(table, column)`
-* pairs that mask declares, and which tables the procedure reads/writes. The
-* column-level analogue of {@link RlsProcedureIR}. Structurally identical to
-* `AdvisorMaskProcedure` so values pass straight through without conversion.
-*/
+ * One procedure reduced to the facts the `mask_uncovered_pii_column` lint needs:
+ * whether its builder chain includes `.use(mask(...))`, which `(table, column)`
+ * pairs that mask declares, and which tables the procedure reads/writes. The
+ * column-level analogue of {@link RlsProcedureIR}. Structurally identical to
+ * `AdvisorMaskProcedure` so values pass straight through without conversion.
+ */
 interface MaskProcedureIR {
   /** Export binding name of the procedure (e.g. `listUsers`). */
   exportName: string;
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /**
-  * `(table, column)` pairs this procedure's `mask(policies)` object literal
-  * declares. Empty when the policies argument is not a statically-readable
-  * object literal (conservative: `usesMask` is still `true`).
-  */
+   * `(table, column)` pairs this procedure's `mask(policies)` object literal
+   * declares. Empty when the policies argument is not a statically-readable
+   * object literal (conservative: `usesMask` is still `true`).
+   */
   maskColumns: {
     column: string;
     table: string;
@@ -537,14 +1060,14 @@ interface MaskProcedureIR {
   visibility: "internal" | "public";
 }
 /**
-* One masked column surfaced to the studio's data-browser mask preview: a
-* `(table, column)` pair plus the declared {@link MaskProcedureIR} strategy so
-* the preview can pick redact-vs-hash-vs-custom rendering. Aggregated across the
-* project's `.use(mask(...))` chains by `discoverMaskMetadata`; the descriptive
-* twin of {@link RlsPolicyIR}. `"custom"` covers any non-string strategy (a
-* `(value, ctx) => …` function) — its logic is an opaque closure, never read by
-* the UI; the preview renders a fixed sentinel for it.
-*/
+ * One masked column surfaced to the studio's data-browser mask preview: a
+ * `(table, column)` pair plus the declared {@link MaskProcedureIR} strategy so
+ * the preview can pick redact-vs-hash-vs-custom rendering. Aggregated across the
+ * project's `.use(mask(...))` chains by `discoverMaskMetadata`; the descriptive
+ * twin of {@link RlsPolicyIR}. `"custom"` covers any non-string strategy (a
+ * `(value, ctx) => …` function) — its logic is an opaque closure, never read by
+ * the UI; the preview renders a fixed sentinel for it.
+ */
 interface MaskColumnMetadataIR {
   /** Column the mask policy redacts. */
   column: string;
@@ -554,24 +1077,48 @@ interface MaskColumnMetadataIR {
   table: string;
 }
 /**
-* Schema-wide masking metadata the codegen emits into the generated ShardDO so
-* the studio's data-browser mask toggle can preview what a non-privileged caller
-* would see. Aggregated across every `.use(mask(...))` chain in the project —
-* purely descriptive (table + column + strategy), never the masking closure. The
-* column-level analogue of {@link RlsMetadataIR}.
-*/
+ * Schema-wide masking metadata the codegen emits into the generated ShardDO so
+ * the studio's data-browser mask toggle can preview what a non-privileged caller
+ * would see. Aggregated across every `.use(mask(...))` chain in the project —
+ * purely descriptive (table + column + strategy), never the masking closure. The
+ * column-level analogue of {@link RlsMetadataIR}.
+ */
 interface MaskMetadataIR {
   /** Every statically-discovered masked column, deduped by `(table, column)` (first declaration wins). */
   columns: MaskColumnMetadataIR[];
 }
 /**
-* One statically-readable policy entry from an `rls([...])` array literal,
-* surfaced to the studio's read-only RLS inspector via the generated
-* `rlsPolicies()` hook. Captures the policy's `table` + `on` operation and the
-* procedure it guards — never the `when` predicate, which is an opaque JS
-* closure (its logic stays in code, not the UI). Produced by
-* `discoverRlsProcedures` alongside the lint IR.
-*/
+ * One masked column whose `mask(policies)` strategy is a statically-known
+ * literal (`"hash"` or `"redact"`) — the `mask_weak_hash_strategy_on_pii` lint
+ * input. Unlike {@link MaskColumnMetadataIR} (app-wide, deduped by `(table,
+ * column)`, studio-preview evidence), this is per declaration site (file + line
+ * + enclosing export), undeduped, so the lint can point at the exact
+ * `mask(...)` call that applies a weak strategy. A `MaskFn` (custom, non-literal)
+ * strategy carries no lint-relevant signal and is never recorded here.
+ * Structurally identical to `AdvisorMaskStrategy`.
+ */
+interface MaskStrategyIR {
+  /** Masked column name. */
+  column: string;
+  /** Export binding name of the procedure whose `.use(mask(...))` chain declared this column, or `"<module>"` when declared at file scope. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the masked column's strategy property. */
+  line: number;
+  /** The statically-known strategy literal: `"hash"` or `"redact"`. */
+  strategy: string;
+  /** Logical table the masked column belongs to. */
+  table: string;
+}
+/**
+ * One statically-readable policy entry from an `rls([...])` array literal,
+ * surfaced to the studio's read-only RLS inspector via the generated
+ * `rlsPolicies()` hook. Captures the policy's `table` + `on` operation and the
+ * procedure it guards — never the `when` predicate, which is an opaque JS
+ * closure (its logic stays in code, not the UI). Produced by
+ * `discoverRlsProcedures` alongside the lint IR.
+ */
 interface RlsPolicyIR {
   /** Source file (relative to `lunora/`, without extension) the policy is declared in. */
   file: string;
@@ -583,12 +1130,12 @@ interface RlsPolicyIR {
   table: string;
 }
 /**
-* One statically-readable role entry from an `rls(policies, { roles: [...] })`
-* call, surfaced to the studio's RLS inspector. Captures the role's `name`,
-* optional `description`, and the names of the permissions it grants (string
-* literals or `definePermission("name")` calls). Produced by
-* `discoverRlsProcedures`.
-*/
+ * One statically-readable role entry from an `rls(policies, { roles: [...] })`
+ * call, surfaced to the studio's RLS inspector. Captures the role's `name`,
+ * optional `description`, and the names of the permissions it grants (string
+ * literals or `definePermission("name")` calls). Produced by
+ * `discoverRlsProcedures`.
+ */
 interface RlsRoleIR {
   /** Optional human-readable description from `defineRole(name, { description })`. */
   description?: string;
@@ -598,11 +1145,11 @@ interface RlsRoleIR {
   permissions: string[];
 }
 /**
-* Schema-wide RLS metadata the codegen emits into the generated ShardDO so the
-* studio's read-only inspector can list, per table, which policies guard it and
-* what roles are defined. Aggregated across every `.use(rls(...))` chain in the
-* project — purely descriptive, never the predicate logic.
-*/
+ * Schema-wide RLS metadata the codegen emits into the generated ShardDO so the
+ * studio's read-only inspector can list, per table, which policies guard it and
+ * what roles are defined. Aggregated across every `.use(rls(...))` chain in the
+ * project — purely descriptive, never the predicate logic.
+ */
 interface RlsMetadataIR {
   /** Every statically-discovered policy `(table, on, procedure)` entry. */
   policies: RlsPolicyIR[];
@@ -621,27 +1168,36 @@ interface StorageRuleIR {
   procedure: string;
 }
 /**
-* Schema-wide storage-access-rule metadata emitted into the generated ShardDO so
-* the studio's read-only inspector can list, per bucket, which operations are
-* gated and under what key prefix. Aggregated across every
-* `.use(storageRules(...))` chain — descriptive only, never the predicate logic.
-*/
+ * Schema-wide storage-access-rule metadata emitted into the generated ShardDO so
+ * the studio's read-only inspector can list, per bucket, which operations are
+ * gated and under what key prefix. Aggregated across every
+ * `.use(storageRules(...))` chain — descriptive only, never the predicate logic.
+ */
 interface StorageRulesMetadataIR {
   rules: StorageRuleIR[];
 }
 /**
-* A typed REST route declared with the `httpRoute.&lt;verb>("/path")…` builder in
-* `@lunora/server` and mounted on `httpRouter()`. Captured statically from the
-* builder chain so the OpenAPI emitter can render a real `paths` entry: the verb
-* + path become the operation's method + URL, and the accumulated validator maps
-* become its query parameters, path parameters, and request body.
-*/
+ * A typed REST route declared with the `httpRoute.<verb>("/path")…` builder in
+ * `@lunora/server` and mounted on `httpRouter()`. Captured statically from the
+ * builder chain so the OpenAPI emitter can render a real `paths` entry: the verb
+ * + path become the operation's method + URL, and the accumulated validator maps
+ * become its query parameters, path parameters, and request body.
+ */
 interface HttpRouteIR {
   /** `v.*` validators decoding the JSON request body (`.body({...})`), keyed by field. */
   body: Record<string, ValidatorIR>;
+  /**
+   * Rendered TS type of one SSE chunk — the `R` the `.stream(handler)`
+   * handler yields — inferred from the handler via the type checker. Present
+   * only when {@link HttpRouteIR.stream} is `true`; `"unknown"` when the
+   * checker can't resolve enough context. Feeds the emitted
+   * `HttpStreamRef<Chunk, …>` so the chunk type flows to the client.
+   * @experimental Part of the HTTP-SSE stream surface (the `httpStreams.*` emission).
+   */
+  chunkType?: string;
   /** Export binding name of the route handler (used only for diagnostics / dedupe). */
   exportName: string;
-  /** Path relative to `&lt;projectRoot>/lunora/` without extension, e.g. "http". */
+  /** Path relative to `<projectRoot>/lunora/` without extension, e.g. "http". */
   filePath: string;
   /** HTTP verb the route binds to (uppercased), e.g. `"GET"`. */
   method: string;
@@ -649,7 +1205,7 @@ interface HttpRouteIR {
   output?: ValidatorIR;
   /** `v.*` validators decoding the hono path params (`.params({...})`), keyed by `:name`. */
   params: Record<string, ValidatorIR>;
-  /** The route path passed to `httpRoute.&lt;verb>(path)`, e.g. `/api/todos/:id`. */
+  /** The route path passed to `httpRoute.<verb>(path)`, e.g. `/api/todos/:id`. */
   path: string;
   /** `v.*` validators decoding the URL query string (`.searchParams({...})`), keyed by name. */
   searchParams: Record<string, ValidatorIR>;
@@ -657,28 +1213,69 @@ interface HttpRouteIR {
   stream: boolean;
 }
 /**
-* Per-procedure protective-middleware snapshot, produced by
-* `discoverProcedureMiddleware` for the security lints
-* (`public_mutation_without_ratelimit`, `user_creating_mutation_without_captcha`).
-* Records which `.use(...)` guards a procedure's builder chain carries plus the
-* behavioural facts that decide whether a guard is *expected* (does it write a
-* user/session table, does it send mail). `protectPublic({ rateLimit, captcha })`
-* is unwrapped: the bundle's object-literal keys set `usesRateLimit`/`usesCaptcha`
-* exactly as the individual `.use(rateLimit(...))` / `.use(verifyTurnstile(...))`
-* steps would. Structurally identical to `AdvisorProcedureProtection` so values
-* pass straight through to the advisor without conversion.
-*/
+ * Per-procedure protective-middleware snapshot, produced by
+ * `discoverProcedureMiddleware` for the security lints
+ * (`public_mutation_without_ratelimit`, `user_creating_mutation_without_captcha`).
+ * Records which `.use(...)` guards a procedure's builder chain carries plus the
+ * behavioural facts that decide whether a guard is *expected* (does it write a
+ * user/session table, does it send mail). `protectPublic({ rateLimit, captcha })`
+ * is unwrapped: the bundle's object-literal keys set `usesRateLimit`/`usesCaptcha`
+ * exactly as the individual `.use(rateLimit(...))` / `.use(verifyTurnstile(...))`
+ * steps would. Structurally identical to `AdvisorProcedureProtection` so values
+ * pass straight through to the advisor without conversion.
+ */
 interface ProcedureMiddlewareIR {
-  /** `true` when the handler (or a helper inside it) references `ctx.mail` / `ctx.email`. */
-  callsMail: boolean;
+  /**
+   * `true` when the handler body could be read statically — an inline function
+   * expression/arrow, or a same-file identifier resolved to one. `false` for a
+   * genuinely cross-file handler (an imported function, or an identifier that
+   * doesn't resolve in this file), in which case every behavioural fact below
+   * is `undefined` rather than a false "not observed" — the feeder never saw
+   * the body, so it has nothing to report.
+   */
+  analyzableBody: boolean;
+  /** `true` when the handler (or a helper inside it) references `ctx.mail` / `ctx.email`. `undefined` when `analyzableBody` is `false`. */
+  callsMail?: boolean;
+  /** `true` when the handler emits a structured observability event (`ctx.log` / `ctx.span` / `ctx.trace`). */
+  emitsEvent?: boolean;
+  /** `true` when a `// lunora-advisor-exempt` directive sits above the export. */
+  exempt: boolean;
+  /** The `-- reason` from that directive, or `""`. */
+  exemptReason: string;
   /** Export binding name of the procedure (e.g. `signUp`). */
   exportName: string;
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  /** `true` when the handler fans work out to a privileged, cost-bearing dispatch surface (scheduler `runAfter`/`runAt`, a queue producer send, or a workflow create). Feeds the privileged-fanout lint. `undefined` when `analyzableBody` is `false`. */
+  fanOut?: boolean;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
-  /** Registration kind — only `mutation`/`action` are write-shaped; `query` is read-only. */
+  /** `true` when the handler wraps work in `try`/`catch`. */
+  handlesErrors?: boolean;
+  /**
+   * `true` when the procedure declares an email-shaped argument (`email`,
+   * `emailAddress`, `userEmail`, …), `false` when it provably declares none,
+   * and **absent** when the argument list can't be read statically (a
+   * `.input(sharedSchema)`, a spread, or a factory whose `args` comes from a
+   * variable). Feeds `signup_mutation_without_disposable_gating`, which can
+   * only be actioned when there is an address to gate — so "unreadable" must
+   * stay distinguishable from "none", or the lint would clear itself on a
+   * registration that may well expose one.
+   */
+  hasEmailArg?: boolean;
   kind: "action" | "mutation" | "query";
+  /** `true` when the handler reaches an outbound surface (`ctx.fetch`, mail, queues, storage, sql, ai, …) that can fail. */
+  reachesOutbound?: boolean;
+  /** `true` when the handler runs any AI generation, bounded or not. */
+  runsAiGeneration?: boolean;
+  /** `true` when the handler throws a bare `new Error(...)` rather than a coded `LunoraError`. */
+  throwsBareError?: boolean;
+  /** `true` when the handler runs an AI generation (`generateText`/`streamText`/`generateObject`/`streamObject`) with no `maxOutputTokens` bound in its config literal. Feeds the `ai_unbounded_generation_public` lint. `undefined` when `analyzableBody` is `false`. */
+  unboundedAiGeneration?: boolean;
   /** `true` when the chain carries `.use(verifyTurnstile(...))` or a `protectPublic({ captcha })` bundle. */
   usesCaptcha: boolean;
+  /** `true` when the chain carries `.use(emailGateMiddleware(...))` (`@lunora/auth`). Feeds the `signup_mutation_without_disposable_gating` lint. */
+  usesEmailGate: boolean;
+  /** `true` when the handler calls `ctx.db.insertManyUnsafe(...)`, bypassing validators and triggers. Feeds the `insert_many_unsafe_user_data` lint. `undefined` when `analyzableBody` is `false`. */
+  usesInsertManyUnsafe?: boolean;
   /** `true` when the chain carries `.use(mask(...))`. */
   usesMask: boolean;
   /** `true` when the chain carries `.use(rateLimit(...))` or a `protectPublic({ rateLimit })` bundle. */
@@ -687,23 +1284,23 @@ interface ProcedureMiddlewareIR {
   usesRls: boolean;
   /** `"internal"` for `internalQuery` / `internalMutation` / `internalAction`. */
   visibility: "internal" | "public";
-  /** `true` when the handler inserts into a user/session/account-shaped table. */
-  writesUserTable: boolean;
+  /** `true` when the handler inserts into a user/session/account-shaped table. `undefined` when `analyzableBody` is `false`. */
+  writesUserTable?: boolean;
 }
 /**
-* Per-procedure argument-validator snapshot, produced by the
-* argument-validator discoverer for the input-hardening lints
-* (`public_arg_uses_any`, `unbounded_string_arg`). Only public procedures are
-* recorded — internal functions take server-trusted input. Structurally identical
-* to `AdvisorArgumentValidator` so it passes straight through to the advisor
-* without conversion.
-*/
+ * Per-procedure argument-validator snapshot, produced by the
+ * argument-validator discoverer for the input-hardening lints
+ * (`public_arg_uses_any`, `unbounded_string_arg`). Only public procedures are
+ * recorded — internal functions take server-trusted input. Structurally identical
+ * to `AdvisorArgumentValidator` so it passes straight through to the advisor
+ * without conversion.
+ */
 interface ArgumentValidatorIR {
   /** Arg names declared as `v.any()` (unvalidated, untyped input). */
   anyArgs: string[];
   /** Export binding name of the procedure (e.g. `updateProfile`). */
   exportName: string;
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the registration call, or `0` when unknown. */
   line: number;
@@ -711,13 +1308,34 @@ interface ArgumentValidatorIR {
   unboundedStringArgs: string[];
 }
 /**
-* One secret-shaped string literal discovered in `lunora/` source — the
-* `hardcoded_secret` lint input. Complements the pre-commit `vis secrets` scan by
-* surfacing the same class of finding in-IDE via the studio Advisors table.
-* Structurally identical to `AdvisorSecretLiteral`.
-*/
+ * One factory/constructor call in `lunora/` whose config object literal a
+ * security lint inspects for a present-or-absent key — the shared input for the
+ * config-call security lints (payment authorize, inbound-mail verify, rate-limit
+ * store, browser private-targets). Structurally identical to `AdvisorConfigCall`
+ * so it passes straight through to the advisor without conversion.
+ */
+interface ConfigCallIR {
+  /** `true` when the config argument was a static object literal the feeder could read. */
+  analyzable: boolean;
+  /** The factory function or constructor name at the call site, e.g. `createPayment` / `RateLimiter`. */
+  callee: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the call site, or `0` when unknown. */
+  line: number;
+  /** Keys present in the config object literal (empty when not `analyzable`). */
+  presentKeys: string[];
+  /** Keys in the config object literal explicitly assigned the literal `true`. */
+  trueKeys: string[];
+}
+/**
+ * One secret-shaped string literal discovered in `lunora/` source — the
+ * `hardcoded_secret` lint input. Complements the pre-commit `vis secrets` scan by
+ * surfacing the same class of finding in-IDE via the studio Advisors table.
+ * Structurally identical to `AdvisorSecretLiteral`.
+ */
 interface SecretLiteralIR {
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** Heuristic that matched, e.g. `stripe_live_key` / `aws_access_key` / `pem_private_key` / `high_entropy`. */
   kind: string;
@@ -727,282 +1345,1695 @@ interface SecretLiteralIR {
   preview: string;
 }
 /**
-* One `ctx.sql.query(text, …)` / `ctx.sql.unsafe(text, …)` call whose `text`
-* argument is built in place rather than passed as a fixed statement — the
-* `sql_injection_risk` lint input. The Hyperdrive driver binds ONLY the `params`
-* array; the `text` string is spliced verbatim into the SQL, so a `text` assembled
-* from a string concatenation or a substitution template literal is an injection
-* vector. A fixed string literal / no-substitution template is safe. Structurally
-* identical to `AdvisorSqlInterpolation`.
-*/
+ * One `ctx.sql.query(text, …)` / `ctx.sql.unsafe(text, …)` call whose `text`
+ * argument is built in place rather than passed as a fixed statement — the
+ * `sql_injection_risk` lint input. The Hyperdrive driver binds ONLY the `params`
+ * array; the `text` string is spliced verbatim into the SQL, so a `text` assembled
+ * from a string concatenation or a substitution template literal is an injection
+ * vector. A fixed string literal / no-substitution template is safe. Structurally
+ * identical to `AdvisorSqlInterpolation`.
+ */
 interface SqlInterpolationIR {
   /** Export binding name of the procedure performing the `ctx.sql` call. */
   exportName: string;
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the interpolation, or `0` when unknown. */
   line: number;
 }
 /**
-* One discovered `httpRoute.&lt;verb>("/admin/…")` route on an admin/privileged-looking
-* path, with whether its builder chain references an auth/admin guard — the
-* `admin_route_without_guard` lint input. Structurally identical to
-* `AdvisorAdminRoute`.
-*/
-interface AdminRouteIR {
-  /** Export binding name of the route handler. */
+ * One `ctx.fetch(url, …)` call inside an action whose URL argument is derived
+ * from the handler's `args` — the `action_fetch_ssrf` lint input. `ctx.fetch` is
+ * the action-only outbound-request escape hatch with no host allowlist, so a URL
+ * assembled from request input is a server-side request forgery vector (cloud
+ * metadata endpoints, internal services). Only arg-derived URLs reach here; a
+ * fixed literal or a URL built from config/`ctx.*` is not recorded. Structurally
+ * identical to `AdvisorArgumentDerivedFetch`.
+ */
+interface ArgumentDerivedFetchIR {
+  /** Export binding name of the action performing the `ctx.fetch` call. */
   exportName: string;
-  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
-  /** HTTP verb the route binds to (uppercased), e.g. `"POST"`. */
+  /** 1-based line of the `ctx.fetch` call, or `0` when unknown. */
+  line: number;
+}
+/**
+ * One `ctx.kv.<method>(key, …)` call whose namespace key is derived from the
+ * handler's `args` with no server-side scoping — the `kv_unscoped_user_key_idor`
+ * lint input. Workers KV is a single flat namespace, so a key taken straight from
+ * request input lets any caller read, overwrite, or delete another user's entry
+ * (IDOR). Only arg-derived, unscoped keys reach here; a fixed literal, or a key
+ * prefixed with a server-trusted identity (`${ctx.auth.userId}:…` — references
+ * `ctx`, so treated as scoped), is not recorded. `list` is excluded (it takes a
+ * prefix, not a per-entry key). Structurally identical to `AdvisorKvKeyAccess`.
+ */
+interface KvKeyAccessIR {
+  /** Export binding name of the procedure performing the `ctx.kv` access. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `ctx.kv` call, or `0` when unknown. */
+  line: number;
+  /** The `ctx.kv` method invoked: `get` / `getRaw` / `getWithMetadata` / `put` / `delete`. */
   method: string;
-  /** The route path, e.g. `/admin/users`. */
-  path: string;
-  /** `true` when the handler body references an auth/session/admin guard (`ctx.auth`, `getSession`, `requireAdmin`, …). */
-  usesGuard: boolean;
 }
-interface ProjectIR {
-  crons: ReadonlyArray<CronJobIR>;
-  functions: ReadonlyArray<FunctionIR>;
-  /** Typed REST routes discovered from `httpRoute.&lt;verb>(...)` builder chains. */
-  httpRoutes: ReadonlyArray<HttpRouteIR>;
-  migrations: ReadonlyArray<MigrationIR>;
-  schema: SchemaIR;
+/**
+ * One `ctx.db` write (`insert` / `replace` / `patch` / `insertManyUnsafe`) that sets
+ * an ownership / identity column — `userId`, `ownerId`, `tenantId`, and the like —
+ * from the handler's `args` instead of the server-trusted identity. The
+ * `owner_field_from_args_not_auth` lint input: the ownership column decides who a
+ * row belongs to, so a value taken from request input lets any caller write rows
+ * owned by another user or tenant (the act-as-any-user / cross-tenant IDOR vector).
+ * A column stamped from `ctx.*`, or set to a fixed literal, is not recorded; only an
+ * arg-derived identity write reaches here. Structurally identical to
+ * `AdvisorOwnerFieldWrite`.
+ */
+/**
+ * One branching `defineShape({ where })` / `definePolicy({ when })` predicate arm
+ * that returns an unrestricted predicate — the `unrestricted_where_branch` lint
+ * input. A denial arm must match NO rows (`deny()` / `{ OR: [] }`); `{}` matches
+ * every row, so the near-miss silently replicates the whole table.
+ */
+interface UnrestrictedWhereBranchIR {
+  /** Export binding name of the shape / policy the predicate belongs to. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** Which unrestricted form was returned. */
+  form: "empty-object" | "undefined";
+  /** The config key carrying the predicate (`where` for a shape, `when` for a policy). */
+  key: string;
+  /** 1-based line of the offending returned expression. */
+  line: number;
+  /** The declaring call (`defineShape` / `definePolicy`). */
+  owner: string;
+}
+interface OwnerFieldWriteIR {
+  /** Export binding name of the procedure performing the write. */
+  exportName: string;
+  /** The identity column being written from `args` (e.g. `userId`). */
+  field: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `ctx.db` write call, or `0` when unknown. */
+  line: number;
+  /** The `ctx.db` write method (`insert` / `replace` / `patch` / `insertManyUnsafe`). */
+  method: string;
+  /**
+   * Visibility of the enclosing procedure. `internal` procedures are not
+   * reachable by a caller, so the lint's premise ("any caller can write rows
+   * owned by another user") does not hold there — see
+   * `owner_field_from_args_not_auth`. `undefined` when the write sits outside
+   * any recognised procedure (a bare helper).
+   */
+  visibility?: "internal" | "public";
 }
 /**
-* Run the static lints against a discovered {@link SchemaIR} and the reads/writes/calls
-* found in function bodies: query reads feed `filter_without_index`, insert writes
-* feed `table_without_insert`, authApi calls feed `auth_api_call_without_headers`,
-* rls procedure snapshots feed `rls_uncovered_table`, and mask procedure
-* snapshots feed `mask_uncovered_pii_column`; declared containers
-* feed the `container_*` lints; declared workflows + `ctx.workflows.get(...)` call
-* sites feed the `workflow_unused` / `workflow_unknown_target` lints; non-deterministic
-* calls inside query/mutation handlers feed the `nondeterministic_query_mutation` lint
-* (all default empty for callers that don't analyze functions/containers/workflows).
-* The IR types are structurally identical to the advisor's evidence types so they
-* pass straight through without conversion. Returns the findings; surfacing them
-* (console, error overlay, studio Advisors table) is the caller's choice.
-*/
-declare const lintSchema: (schema: SchemaIR, queries?: ReadonlyArray<QueryReadIR>, inserts?: ReadonlyArray<InsertWriteIR>, authApiCalls?: ReadonlyArray<AuthApiCallIR>, rlsProcedures?: ReadonlyArray<RlsProcedureIR>, containers?: ReadonlyArray<ContainerIR>, workflows?: ReadonlyArray<WorkflowIR>, workflowCalls?: ReadonlyArray<WorkflowCallIR>, maskProcedures?: ReadonlyArray<MaskProcedureIR>, nondeterministicCalls?: ReadonlyArray<NondeterministicCallIR>, procedureProtections?: ReadonlyArray<ProcedureMiddlewareIR>, argumentValidators?: ReadonlyArray<ArgumentValidatorIR>, secretLiterals?: ReadonlyArray<SecretLiteralIR>, sqlInterpolations?: ReadonlyArray<SqlInterpolationIR>, adminRoutes?: ReadonlyArray<AdminRouteIR>, r2sqlCalls?: ReadonlyArray<R2sqlCallIR>) => Finding[];
-/**
-* Render advisor findings as a single multi-line string for console surfacing:
-* a one-line summary header followed by one `[LEVEL] name: detail` line per
-* finding. Returns `""` when there are no findings.
-*/
-declare const formatAdvisories: (findings: ReadonlyArray<Finding>) => string;
+ * One `ctx.storage.<bucket>.<method>(key, …)` call whose R2 object key is derived
+ * from the handler's `args` with no server-side scoping — the
+ * `storage_key_from_user_args` lint input. The bucket read/write/URL/delete methods
+ * key by their first argument, so an object key taken straight from request input is
+ * object-level IDOR (read/overwrite/delete anyone's object). A key referencing a
+ * server-trusted `ctx.*` value (e.g. `${ctx.auth.userId}/…`) is treated as scoped
+ * and is not recorded; only an arg-derived, `ctx`-free key reaches here.
+ * Structurally identical to `AdvisorStorageKeyAccess`.
+ */
+interface StorageKeyAccessIR {
+  /** Export binding name of the procedure performing the storage call. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the storage call, or `0` when unknown. */
+  line: number;
+  /** The bucket method invoked with the arg-derived key, e.g. `get` / `put` / `delete` / `download`. */
+  method: string;
+  /**
+   * Visibility of the enclosing procedure. `internal` procedures have no
+   * untrusted caller by construction — see `owner_field_from_args_not_auth`'s
+   * identical split — so `storage_key_from_user_args` drops the finding to
+   * INFO rather than ERROR there. `undefined` when the access sits outside any
+   * registered procedure the feeder could attribute it to.
+   */
+  visibility?: "internal" | "public";
+}
 /**
-* An error thrown by codegen discovery when the user's schema or function
-* source has a structural problem that can be pinpointed to a specific source
-* location. The `file`, `line`, and `column` properties mirror what Vite's
-* error-overlay `loc` field expects so the browser can display the exact spot.
-*/
-declare class CodegenDiagnosticError extends Error {
-  readonly column: number;
-  readonly file: string;
-  readonly line: number;
-  constructor(message: string, file: string, line: number, column: number);
+ * One `ctx.containers.<exportName>.get(name, …)` call whose instance key is derived
+ * from the handler's `args` with no server-side scoping — the
+ * `container_instance_key_from_user_input` lint input. Each container definition's
+ * `.get(name)` accessor routes to one instance per `name`, so a key taken straight from
+ * request input lets any caller reach another tenant's container (a cross-tenant IDOR). A
+ * fixed literal key, or one derived from a server-trusted identity (`${ctx.auth.userId}` —
+ * references `ctx`, so treated as scoped), is not recorded; only an arg-derived, unscoped
+ * key reaches here. `.any()`/`.pool()` take no key and are not sinks. Structurally
+ * identical to `AdvisorContainerKeyAccess`.
+ */
+interface ContainerKeyAccessIR {
+  /** Export binding name of the procedure performing the `ctx.containers` access. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `ctx.containers.*.get` call, or `0` when unknown. */
+  line: number;
+  /** The container accessor method invoked — always `get`. */
+  method: string;
 }
 /**
-* Build a {@link CodegenDiagnosticError} whose message includes the source
-* location and whose `file`/`line`/`column` properties are set from the
-* ts-morph `Node`'s position in its source file.
-*
-* Message format: `@lunora/codegen: &lt;detail> (&lt;file>:&lt;line>:&lt;column>)`
-*
-* `meta` is merged onto the returned error for callers that also carry the
-* project-wide `LunoraError` envelope (`code`/`name`/`status`) — it never
-* touches `file`/`line`/`column`, and the error stays an instance of
-* {@link CodegenDiagnosticError} so the Vite overlay's `instanceof` location
-* lookup is unaffected.
-*/
-declare const diagnosticAt: (node: Node, detail: string, meta?: Record<string, unknown>) => CodegenDiagnosticError;
+ * One `ctx.ai.run(model, …)` call whose model-id argument is derived from the handler's
+ * `args` with no server-side scoping — the `ai_raw_run_escape_hatch` lint input.
+ * `ctx.ai.run` is the raw Workers AI binding passthrough, bypassing the typed
+ * `ctx.ai.model(...)` + AI-SDK layer (`generateText`/`streamText`/…) that caps output and
+ * enforces a schema, so an arg-derived model id lets any caller select an arbitrary model.
+ * A fixed literal model, or one scoped by a server-trusted `ctx.*` value, is not recorded;
+ * only an arg-derived, unscoped model id reaches here (an arg-derived `inputs` argument is
+ * normal usage and is never inspected). Structurally identical to `AdvisorAiRawRun`.
+ */
+interface AiRawRunIR {
+  /** Export binding name of the procedure performing the `ctx.ai.run` call. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `ctx.ai.run` call, or `0` when unknown. */
+  line: number;
+}
 /**
-* Discover `ctx.authApi.&lt;method>(...)` (and bare `authApi.&lt;method>(...)`) calls
-* under the lunora source directory and attribute each to the exported function
-* (and file) performing it. Calls outside an exported declaration are dropped.
-*/
-declare const discoverAuthApiCalls: (project: Project, lunoraDirectory: string) => AuthApiCallIR[];
-/** The only file containers may be declared in — mirrors `lunora/crons.ts`. */
-declare const CONTAINERS_FILENAME = "containers.ts";
+ * One `ctx.vectors.<method>(indexName, input)` call whose `input.namespace` is derived
+ * from the handler's `args` with no server-side scoping — the
+ * `vectors_namespace_from_user_input` lint input. A Vectorize namespace partitions one
+ * index into isolated sub-collections, so a namespace taken straight from request input
+ * lets any caller read or poison another tenant's vectors. A fixed literal namespace, or
+ * one prefixed with a server-trusted identity (`${ctx.auth.orgId}` — references `ctx`, so
+ * treated as scoped), is not recorded; only an arg-derived, unscoped namespace reaches
+ * here. Structurally identical to `AdvisorVectorNamespaceAccess`.
+ */
+interface VectorNamespaceAccessIR {
+  /** Export binding name of the procedure performing the `ctx.vectors` access. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `ctx.vectors` call, or `0` when unknown. */
+  line: number;
+  /** The `ctx.vectors` method invoked: `query` / `upsert` / `upsertMany`. */
+  method: string;
+}
 /**
-* Discover every container the project declares: exported `defineContainer()`
-* calls in `lunora/containers.ts`. Returns `[]` when the file doesn't exist.
-* Wrangler-relevant fields (`image`, `instanceType`, `maxInstances`, `name`)
-* must be static literals; runtime-only fields (`env`, `sleepAfter`, …) may be
-* any expression since the generated class imports the definition object.
-*/
-declare const discoverContainers: (project: Project, lunoraDirectory: string) => ContainerIR[];
+ * One `ctx.mail`/`ctx.email` `send`/`queue` call whose recipient field (`to`/`cc`/`bcc`)
+ * is derived from the handler's `args` with no server-side scoping — the
+ * `mail_recipient_from_request_input` lint input. A recipient taken straight from request
+ * input turns the deployment into an open relay / spam amplifier (any caller can direct
+ * mail to an arbitrary address). A fixed literal recipient, or one scoped by a
+ * server-trusted `ctx.*` value (e.g. `ctx.auth.user.email`), is not recorded; only an
+ * arg-derived, unscoped recipient reaches here. Structurally identical to
+ * `AdvisorMailRecipientAccess`.
+ */
+interface MailRecipientAccessIR {
+  /** Export binding name of the procedure performing the `ctx.mail`/`ctx.email` call. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `ctx.mail`/`ctx.email` call, or `0` when unknown. */
+  line: number;
+  /** The mailer method invoked: `send` / `queue`. */
+  method: string;
+}
 /**
-* Scan every `.ts` file under `lunoraDir` for `cronJobs()` builder registrations
-* (`crons.interval(...)`, `crons.daily(...)`, `crons.cron(...)`, …) and lift them
-* into {@link CronJobIR}. Schedules are compiled to standard cron expressions;
-* function references are resolved to their `namespace:fn` dispatch path, while a
-* bare identifier naming a declared workflow (`workflows`) resolves to a durable
-* workflow start. Names must be unique across the project.
-*/
-declare const discoverCrons: (project: Project, lunoraDirectory: string, workflows?: ReadonlyArray<WorkflowIR>) => CronJobIR[];
-/** The only file a feature-flag provider may be declared in — mirrors `lunora/queues.ts`. */
-declare const FLAGS_FILENAME = "flags.ts";
-/** One statically-discovered flag read: the key plus the value type its `ctx.flags.&lt;type>` call implies. */
-
-/**
-* Discover the feature-flag provider a project declares in `lunora/flags.ts`.
-* Returns `undefined` when the file doesn't exist (the app has no flags). The
-* read is metadata-only and lenient: codegen wires `ctx.flags` purely from the
-* file's *existence* (`run-codegen.ts`) and imports the real module for the
-* provider value — this IR exists solely so the config layer can reconcile the
-* wrangler `flagship` binding for the Flagship binding-mode provider. Anything
-* it can't read statically degrades to a `custom` provider (no binding), never
-* a thrown error.
-*/
-declare const discoverFlags: (project: Project, lunoraDirectory: string) => FlagsIR | undefined;
+ * One `ctx.browser.<method>(url, …)` call whose navigation URL (`arguments[0]`)
+ * is derived from the handler's `args` with no server-side scoping — the
+ * `browser_user_url_without_allowlist` lint input. The lint additionally
+ * cross-references `createBrowser` config-call evidence to suppress findings
+ * when the browser is hardened with an `allowedHosts` allowlist or
+ * `resolveDns`. Structurally identical to `AdvisorBrowserUrlAccess`.
+ */
+interface BrowserUrlAccessIR {
+  /** Export binding name of the procedure performing the `ctx.browser` call. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `ctx.browser` call, or `0` when unknown. */
+  line: number;
+  /** The browser method invoked: `content` / `pdf` / `scrape` / `screenshot`. */
+  method: string;
+}
 /**
-* Scan all .ts files under `lunoraDir` (skipping `_generated/` and `schema.ts`)
-* for top-level `export const x = query/mutation/action({...})` registrations.
-*/
-declare const discoverFunctions: (project: Project, lunoraDirectory: string) => FunctionIR[];
+ * One runtime container-override call: a `<handle>.start({ enableInternet: true, … })`
+ * launch override, or a `<handle>.egress.<method>(...)` runtime firewall mutation
+ * (`allow` / `deny` / `setAllowed`) — the `container_start_enable_internet_override`
+ * and `container_runtime_egress_relaxation` lint input. Both shapes re-open network
+ * access the static `defineContainer` declaration (and its `container_public_internet`
+ * lint) assumes is locked down. Matched structurally by call shape, independent of the
+ * receiver's resolved type. Structurally identical to `AdvisorContainerOverride`.
+ */
+interface ContainerOverrideIR {
+  /** e.g. the egress method name, or `"enableInternet: true"`. */
+  detail: string;
+  /** Export binding name of the procedure performing the call. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** Which override shape matched. */
+  kind: "egress_relaxation" | "enable_internet";
+  /** 1-based line of the call, or `0` when unknown. */
+  line: number;
+}
 /**
-* Scan all `.ts` files under `lunoraDir` (skipping `_generated/` and `schema.ts`)
-* for `export const x = httpRoute.&lt;verb>(...)…handler(...)` typed REST routes.
-* These are the headline OpenAPI target: each becomes a real `paths` entry.
-*/
-declare const discoverHttpRoutes: (project: Project, lunoraDirectory: string) => HttpRouteIR[];
+ * One `buildImageDeliveryUrl({ key, … })` call (`@lunora/bindings/images`) whose
+ * `key` — the CDN transform's source image, an absolute URL or an
+ * origin-relative key — is derived from the handler's `args` with no
+ * server-side scoping — the `images_url_source_from_user_input` lint input.
+ * `ctx.images.transform`/`info` take image *bytes*, never a URL, so they are not
+ * sinks; only the `key` of `buildImageDeliveryUrl` accepts a URL-or-key source
+ * and is inspected. An arg-derived `key` lets any caller point the CDN's
+ * `/cdn-cgi/image/` transform at an attacker-chosen origin (SSRF / open proxy)
+ * or at an arbitrary key under the account's own store. A fixed literal, or a
+ * key scoped by a server-trusted `ctx.*` value, is not recorded. Structurally
+ * identical to `AdvisorImageDeliveryUrlAccess`.
+ */
+interface ImageDeliveryUrlAccessIR {
+  /** Export binding name of the procedure performing the `buildImageDeliveryUrl` call. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `buildImageDeliveryUrl` call, or `0` when unknown. */
+  line: number;
+}
 /**
-* Discover `ctx.db.insert("table", …)` writes under the lunora source directory
-* and attribute each to the exported function (and file) performing it. Calls
-* with a non-literal table argument, or outside an exported declaration, are
-* dropped (`table === ""` / no enclosing export).
-*/
-declare const discoverInserts: (project: Project, lunoraDirectory: string) => InsertWriteIR[];
+ * One `createAuth({...})` call's configuration snapshot — the shared input for
+ * the five `auth_*` security lints (trusted-origins wildcard, CSRF check
+ * disabled, secure cookies disabled, email verification disabled, session
+ * freshAge zero). Matched by callee NAME (an `import`-agnostic, fail-closed
+ * convention the other feeders share), so a re-export or alias still resolves.
+ * When the config argument isn't a statically-analyzable object literal (a
+ * top-level spread, or not an object literal at all), `analyzable` is `false`
+ * and every boolean fact defaults to its SAFE (not-flagged) value — an opaque
+ * config can't be relied on either way. Structurally identical to
+ * `AdvisorAuthConfig`.
+ */
+interface AuthConfigIR {
+  /** `true` when the call's config argument was a static object literal the feeder could read. */
+  analyzable: boolean;
+  /** `advanced.disableCSRFCheck === true`. */
+  disableCsrfCheck: boolean;
+  /** `emailAndPassword.enabled === true`. */
+  emailPasswordEnabled: boolean;
+  /** Export binding name enclosing the `createAuth(...)` call. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `createAuth(...)` call, or `0` when unknown. */
+  line: number;
+  /** `emailAndPassword.requireEmailVerification === true` present. */
+  requireEmailVerification: boolean;
+  /** `trustedOrigins` array literal contains a `"*"` element. */
+  /** `plugins` includes `scim(...)` while `database` is a non-transactional Lunora adapter — a combination that throws at runtime. */
+  scimOnNonTransactionalAdapter: boolean;
+  /** `advanced.useSecureCookies === false`. */
+  secureCookiesDisabled: boolean;
+  /** `session.freshAge === 0` (explicit literal). */
+  sessionFreshAgeZero: boolean;
+  trustedOriginsWildcard: boolean;
+}
 /**
-* Discover masking usage for every exported Lunora procedure under the lunora
-* source directory — the column-level twin of `discoverRlsProcedures`. For each
-* procedure, records whether its builder chain includes `.use(mask(...))`, which
-* `(table, column)` pairs that mask declares, and which tables it reads/writes
-* through `ctx.db`. Feeds the `mask_uncovered_pii_column` advisor lint.
-*/
-declare const discoverMaskProcedures: (project: Project, lunoraDirectory: string) => MaskProcedureIR[];
+ * One `rateLimit`/`dbRateLimit` middleware call (`@lunora/ratelimit`) whose
+ * `key` selector — the per-caller rate-limit sub-key, `(ctx) => string |
+ * undefined` — is derived from the handler's `args` with no server-side
+ * scoping (no reference to the trusted `ctx` binding anywhere in the selector)
+ * — the `ratelimit_key_spoofable_or_global` lint input. A key an attacker
+ * controls lets them rotate it per request and bypass the limit entirely,
+ * defeating its purpose. A selector scoped by `ctx` (e.g. `ctx.auth.userId`,
+ * `ctx.ip`), or one with no `args` reference at all (a fixed/global bucket —
+ * the "no key" case this lint deliberately does not flag, to keep it low-FP),
+ * is not recorded. Structurally identical to `AdvisorRatelimitKeySelector`.
+ */
+interface RatelimitKeySelectorIR {
+  /** The `rateLimit`/`dbRateLimit` callee invoked. */
+  callee: string;
+  /** Export binding name of the procedure whose `.use(...)` chain carries the call. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** The rate limit's `name` argument (the second positional argument), or `""` when not a string literal. */
+  limitName: string;
+  /** 1-based line of the `rateLimit`/`dbRateLimit` call, or `0` when unknown. */
+  line: number;
+}
 /**
-* Aggregate the schema-wide masking metadata the studio's data-browser mask
-* toggle reads: every statically-discovered `(table, column, strategy)` masked
-* column across the project's `.use(mask(...))` chains. Walks the same builder
-* chains as {@link discoverMaskProcedures} but carries the strategy the preview
-* needs to choose redact-vs-hash-vs-custom rendering. Deduped by `(table,
-* column)` with the first declaration winning, so a column masked by several
-* procedures lists once — the same evidence the advisor lint uses.
-*/
-/**
-* Scan all `.ts` files under `lunoraDir` for top-level
-* `export const x = defineMigration({...})` declarations and lift them into
-* {@link MigrationIR}. `id` must be a static string literal (it's the registry
-* key); `table` is best-effort and left `""` when not a literal.
-*/
-declare const discoverMigrations: (project: Project, lunoraDirectory: string) => MigrationIR[];
+ * One payload-derived privileged dispatch — a `ctx.run`/`context.run` back into a
+ * Lunora function from inside a `defineQueue` push handler or a `defineWorkflow`
+ * handler, whose args reference the handler's untrusted payload (`context.params`
+ * for a workflow, a `for (… of batch.messages)` body for a queue) — the
+ * `privileged_dispatch_unvalidated_payload` lint input. Both handler kinds run
+ * under the **system identity** (RLS disabled), so forwarding attacker-influenced
+ * payload into the dispatch bypasses the target's row policy. The resolved
+ * `targetFile`/`targetExport` let the lint join RLS-procedure evidence and fire
+ * only for RLS-gated targets. Structurally identical to `AdvisorPrivilegedDispatch`.
+ */
+interface PrivilegedDispatchIR {
+  /** `"queue"` for a `defineQueue` handler, `"workflow"` for a `defineWorkflow` handler. */
+  dispatchKind: "queue" | "workflow";
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** Export binding name of the handler performing the dispatch. */
+  handlerExport: string;
+  /** 1-based line of the dispatch call, or `0` when unknown. */
+  line: number;
+  /** Export name of the dispatched target (`send` in `api.messages.send`). */
+  targetExport: string;
+  /** File path of the dispatched target relative to `lunora/` (`messages` in `api.messages.send`). */
+  targetFile: string;
+}
 /**
-* Discover non-deterministic API calls (`Date.now`, `new Date()`, `Date()`,
-* `Math.random`, `crypto.randomUUID`, `crypto.getRandomValues` — including
-* `globalThis`/`self`/`window`-prefixed receivers — and `fetch`) lexically inside
-* the handler body of every exported `query(...)` / `mutation(...)` registration
-* under the lunora source directory — the `nondeterministic_query_mutation` lint
-* input. `action(...)` (and `stream(...)`) registrations are intentionally
-* skipped: actions run exactly once and may use ambient APIs freely.
-*
-* Traversal is scoped to the handler node (not the whole declaration), mirroring
-* how the auth-api / insert feeders attribute calls — so a call in a sibling
-* helper outside the handler, or in a nested `action(...)` passed elsewhere, is
-* not attributed to the query/mutation. One {@link NondeterministicCallIR} is
-* produced per call site.
-*/
-declare const discoverNondeterministicCalls: (project: Project, lunoraDirectory: string) => NondeterministicCallIR[];
+ * One discovered `httpRoute.<verb>("/admin/…")` route on an admin/privileged-looking
+ * path, with whether its builder chain references an auth/admin guard — the
+ * `admin_route_without_guard` lint input. Structurally identical to
+ * `AdvisorAdminRoute`.
+ */
+interface AdminRouteIR {
+  /** Export binding name of the route handler. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** HTTP verb the route binds to (uppercased), e.g. `"POST"`. */
+  method: string;
+  /** The route path, e.g. `/admin/users`. */
+  path: string;
+  /** `true` when the handler body references an auth/session/admin guard (`ctx.auth`, `getSession`, `requireAdmin`, …). */
+  usesGuard: boolean;
+}
 /**
-* Discover `ctx.db.query("table")…` reads under the lunora source directory and
-* reduce each to a {@link QueryReadIR}. Only reads that call `.filter()` are
-* returned — an unfiltered read is never a `filter_without_index` candidate, so
-* dropping the rest keeps the lint input small.
-*/
-declare const discoverQueries: (project: Project, lunoraDirectory: string) => QueryReadIR[];
+ * One tracked `ctx.storage.<bucket>.<method>(...)` upload/signing call — the
+ * shared input for the storage config-hygiene security lints
+ * (`storage_upload_without_content_type_allowlist`, `storage_upload_without_max_size`,
+ * `storage_generate_upload_url_no_content_type_pin`, `storage_presigned_url_for_private_content`).
+ * `upload`/`store` carry the `UploadOptions` guards (`allowedContentTypes` /
+ * `maxSize`); `generateUploadUrl` carries the signed-PUT `contentType` pin;
+ * `getPresignedUrl`/`getSignedUrl` carry a statically-known `expiresInSeconds`
+ * literal. `presentKeys` is empty (and `expiresInSeconds` unset) when the
+ * options argument was absent, a non-literal, or a spread — see `analyzable`.
+ * Structurally identical to `AdvisorStorageUpload`.
+ */
+interface StorageUploadIR {
+  /** `true` when the call's options-object argument (or its deliberate absence) was statically resolvable. */
+  analyzable: boolean;
+  /** Numeric literal value of an `expiresInSeconds` option, when statically known (`getSignedUrl` / `getPresignedUrl` only). */
+  expiresInSeconds?: number;
+  /** Export binding name of the procedure performing the call. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the call, or `0` when unknown. */
+  line: number;
+  /** The `ctx.storage` method invoked. */
+  method: "generateUploadUrl" | "getPresignedUrl" | "getSignedUrl" | "store" | "upload";
+  /** Options-object keys present at the call site (empty when not `analyzable`, or when no options argument was passed). */
+  presentKeys: string[];
+}
+/**
+ * One discovered `httpAction`/`httpRoute` handler in `lunora/` that performs a
+ * side effect (`ctx.runMutation` / `ctx.runAction` / a `ctx.db.{insert,patch,
+ * replace,delete,insertManyUnsafe}` write) from the HTTP edge, with whether it
+ * reads `ctx.auth` — the `http_action_missing_auth_guard` lint input. A handler
+ * that mutates state or dispatches an action without ever consulting the request
+ * identity is an unauthenticated write bypassing identity/RLS. Only handlers with
+ * a statically-resolvable inline body and `ctx` binding are recorded (fail-safe
+ * under-report); read-only handlers are never recorded. Structurally identical to
+ * `AdvisorHttpActionGuard`.
+ */
+interface HttpActionGuardIR {
+  /** Export binding name of the handler (or `"<module>"` when mounted inline / not a named binding). */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** Which HTTP surface the handler is: a raw `httpAction` or a typed `httpRoute` route. */
+  kind: "httpAction" | "httpRoute";
+  /** 1-based line of the handler call, or `0` when unknown. */
+  line: number;
+  /** For an `httpRoute`, the uppercased verb (`"POST"`); absent for a raw `httpAction`. */
+  method?: string;
+  /** `true` when the handler reads `ctx.auth` (a direct member access or a `const { auth } = ctx` destructure). */
+  readsAuth: boolean;
+  /** The first side effect found, as a stable label: `runMutation`, `runAction`, or `db.<method>`. */
+  sideEffect: string;
+}
+/**
+ * One response-header write, inside an `httpAction` handler, whose value is derived
+ * from raw request input (`request.headers`, `request.url`/query, `await
+ * request.json()`) with no CR/LF sanitizer — the
+ * `http_action_response_header_injection` lint input. A `Request`-derived string
+ * placed verbatim into a response header lets a caller smuggle `\r\n` and inject
+ * extra headers or split the response (header injection / response splitting). Only
+ * sites whose value is request-tainted AND unguarded are recorded: a value routed
+ * through a CR/LF guard (`isSafeHeaderValue`), a URL/URI encoder
+ * (`encodeURIComponent`/`encodeURI`), a numeric coercion (`Number`/`parseInt`/
+ * `parseFloat`), or `btoa` is treated as safe and never recorded (`String(...)` /
+ * `.toString()` are NOT sanitizers — they don't strip CR/LF). Structurally
+ * identical to `AdvisorHttpHeaderWrite`.
+ */
+interface HttpHeaderWriteIR {
+  /** Export binding name of the enclosing handler, or `"<module>"` when mounted inline. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** The header name being written (`"location"`), or `""` when the key is not a string literal. */
+  headerName: string;
+  /** 1-based line of the request-tainted header value. */
+  line: number;
+  /** How the header was written. */
+  via: "headers-append" | "headers-ctor" | "headers-set" | "response-init";
+}
+/**
+ * One rate-limit / Turnstile middleware call in `lunora/` — the
+ * `ratelimit_middleware_fail_open` lint input. `rateLimit`/`dbRateLimit`
+ * (`@lunora/ratelimit`) and `verifyTurnstileMiddleware` (`@lunora/auth`) each
+ * accept a `failOpen` escape hatch that admits every request when the
+ * limiter/siteverify is unavailable; `failOpen` is `true` only when the options
+ * literal set it to the boolean literal `true` (anything else is fail-closed).
+ * The lint escalates a fail-open guard to a finding when the guarded procedure
+ * (`exportName`/`limitName`) looks auth/payment-sensitive. Structurally
+ * identical to `AdvisorFailOpenGuard`.
+ */
+interface FailOpenGuardIR {
+  /** The middleware factory at the call site: `rateLimit` / `dbRateLimit` / `verifyTurnstileMiddleware`. */
+  callee: string;
+  /** Export binding name of the procedure the guard is attached to, or `"<module>"` at file scope. */
+  exportName: string;
+  /** `true` only when the options literal set `failOpen: true` as a boolean literal; a non-literal or absent option is treated as fail-closed. */
+  failOpen: boolean;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** The rate-limit `name` (second string argument) for `rateLimit`/`dbRateLimit`; `""` for `verifyTurnstileMiddleware`. */
+  limitName: string;
+  /** 1-based line of the middleware call, or `0` when unknown. */
+  line: number;
+}
+/**
+ * One `ctx.flags.boolean("key", <boolean-literal>)` read in `lunora/` — the
+ * `flag_gates_security_with_unsafe_default` lint input. OpenFeature returns the
+ * `defaultValue` when the provider errors, so a fail-open default on a
+ * security-shaped key silently opens access during an outage. Only reads with a
+ * statically-known string key and boolean-literal default are recorded; the lint
+ * owns the security-shape + polarity judgment. Structurally identical to
+ * `AdvisorFlagSecurityDefault`.
+ */
+interface FlagSecurityDefaultIR {
+  /** The boolean-literal default returned on a provider outage (fail-open value). */
+  defaultValue: boolean;
+  /** Export binding name of the procedure performing the flag read, or `"<module>"` at file scope. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** The flag key — the first string-literal argument of `ctx.flags.boolean`. */
+  key: string;
+  /** 1-based line of the `ctx.flags.boolean` call, or `0` when unknown. */
+  line: number;
+}
+/**
+ * One `ctx.flags` read lexically inside a `query(...)` handler — the
+ * `flag_read_in_subscription` advisor lint input. Flag changes append nothing to
+ * `__cdc_log`, so a subscribed query is never re-run when a flag flips and keeps
+ * serving the branch it last picked; `useFlag` is the reactive path. Structurally
+ * identical to the advisor's `AdvisorFlagRead` (same field set) so values pass
+ * straight through `lintSchema` without conversion, exactly as `ContextPropertyCallIR` does.
+ *
+ * Only `query` handlers are recorded — unlike `ContextPropertyCallIR` / `NondeterministicCallIR`
+ * there is no `kind` field, because `mutation`/`action` handlers run once and have
+ * no subscription staleness to warn about, so the feeder drops them rather than
+ * handing the lint rows it would discard.
+ */
+interface FlagReadIR {
+  /** The accessed `ctx.flags` surface, e.g. `ctx.flags.boolean` / `ctx.flags.details.string`. */
+  callee: string;
+  /** Export binding name of the query performing the read. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension (the api namespace). */
+  file: string;
+  /** 1-based line of the read, or `0` when unknown. */
+  line: number;
+}
+/**
+ * One `generateText` / `streamText` call in `lunora/` whose `tools` reach a
+ * privileged side effect (a DB write, function dispatch, or outbound
+ * fetch/mail/queue send). `userInputDerived` records whether the model input
+ * (`prompt`/`messages`/`system`) flows from the handler's `args`; the
+ * `ai_tool_side_effect_prompt_injection` lint fires only when it does.
+ * Structurally identical to `AdvisorAiToolSideEffect`.
+ */
+interface AiToolSideEffectIR {
+  /** Export binding name of the procedure performing the call. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the generation call, or `0` when unknown. */
+  line: number;
+  /** The generation entrypoint invoked. */
+  method: "generateText" | "streamText";
+  /** The privileged side-effect sink a model-callable tool reaches (`ctx.db.insert`, `ctx.run`, `ctx.fetch`, …). */
+  sideEffect: string;
+  /** `true` when a model-input option is derived from the handler's `args` (a bare `args.x`, or a name destructured from `args`). */
+  userInputDerived: boolean;
+}
+/**
+ * One `<receiver>.identity.<key>` claim read in `lunora/`, where `<receiver>` is
+ * an RLS/mask policy `auth` (or `ctx.auth`/`context.auth`). `declared` records
+ * whether `<key>` is in the app's `defineIdentity({ ... })` contract (or the
+ * always-present `userId`); the `identity_undeclared_claim_trusted` lint fires on
+ * the undeclared reads. Emitted only when a resolvable identity contract exists.
+ * Structurally identical to `AdvisorIdentityClaimRead`.
+ */
+interface IdentityClaimReadIR {
+  /** `true` when `key` is a declared claim (in the `defineIdentity` contract, or the always-present `userId`). */
+  declared: boolean;
+  /** Export binding name of the enclosing declaration (`<module>` at file scope). */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** The claim key read off the identity bag. */
+  key: string;
+  /** 1-based line of the read, or `0` when unknown. */
+  line: number;
+}
+/**
+ * One payment webhook-adapter construction in `lunora/` (`createStripeAdapter` /
+ * `createPolarAdapter` / `createAutumnAdapter` / `createDodoPaymentsAdapter`).
+ * `toleranceSeconds` carries the statically-known `webhookToleranceSeconds`
+ * replay window when it is a plain numeric literal; the payment-webhook
+ * wide-tolerance lint fires when it exceeds a conservative ceiling. Structurally
+ * identical to `AdvisorPaymentWebhook`.
+ */
+interface PaymentWebhookIR {
+  /** The adapter factory invoked. */
+  callee: "createAutumnAdapter" | "createDodoPaymentsAdapter" | "createPolarAdapter" | "createStripeAdapter";
+  /** Export binding name of the enclosing declaration (`<module>` at file scope). */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the construction, or `0` when unknown. */
+  line: number;
+  /** Statically-known `webhookToleranceSeconds` literal, when present and a plain numeric literal. */
+  toleranceSeconds?: number;
+}
+/**
+ * One `ctx.db.<table>.findMany({ includeDeleted })` list read whose
+ * `includeDeleted` is either a hardcoded `true` or derived from the handler's
+ * `args` — the `soft_delete_include_deleted_from_args` lint input. The lint joins
+ * `table` against the schema's soft-delete tables and `visibility` against
+ * `.public()` before flagging. Structurally identical to `AdvisorSoftDeleteRead`
+ * so values pass straight through without conversion.
+ */
+interface SoftDeleteReadIR {
+  /** Export binding name of the procedure performing the read. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** `true` when `includeDeleted` was derived from the handler's `args` (any caller can flip it). */
+  fromArgs: boolean;
+  /** `true` when `includeDeleted` was a hardcoded `true` literal (always resurfaces soft-deleted rows). */
+  hardcodedTrue: boolean;
+  /** 1-based line of the read call. */
+  line: number;
+  /** Table read, or `""` when the table-arg form's first argument wasn't a string literal. */
+  table: string;
+  /** `"internal"` for `internalQuery` / `internalMutation` / `internalAction`. */
+  visibility: "internal" | "public";
+}
+/**
+ * One `ctx.db.<table>.findMany({ with: { <rel> } })` relation-hydrating list read
+ * — the `masked_relation_leak_via_with` lint input. Column masking does not
+ * descend into `with`-hydrated relations, so a masked table surfaced only through
+ * a `with` on an unprotected parent read is returned in the clear. The lint
+ * resolves each relation accessor to its target table and joins it against the
+ * discovered mask evidence before flagging. Structurally identical to
+ * `AdvisorRelationLoad` so values pass straight through without conversion.
+ */
+interface RelationLoadIR {
+  /** Export binding name of the procedure performing the read. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the read call. */
+  line: number;
+  /** Parent table the read targets, or `""` when the table-arg form's first argument wasn't a string literal. */
+  parentTable: string;
+  /** Relation accessor names named in the read's `with: { … }` map — matched against the parent table's declared relations. */
+  relations: string[];
+  /** `"internal"` for `internalQuery` / `internalMutation` / `internalAction`. */
+  visibility: "internal" | "public";
+}
+/**
+ * One `query` handler whose `return` hands back the raw rows of a table — the
+ * result of a `ctx.db.<table>.findMany()` / `.findFirst()` / `.get()` read, or a
+ * `ctx.db.query("<table>")…collect()` fluent chain — returned directly (or through
+ * one local `const` hop) with no hand-built projection. The
+ * `output_projection_missing_on_public_read` lint keeps only `visibility ===
+ * "public"` rows with no `.output(...)` / `.use(mask(...))` on the chain, then
+ * joins `table` against the schema and flags one whose columns are PII-named.
+ * Structurally identical to `AdvisorRawRowReturn` so values pass straight through
+ * without conversion.
+ */
+interface RawRowReturnIR {
+  /** Export binding name of the query returning the raw rows. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `return` (or concise-body) expression. */
+  line: number;
+  /** Table whose raw rows are returned, or `""` when the read's table wasn't a string literal. */
+  table: string;
+  /** `true` when the procedure's builder chain carries a `.use(mask(...))` step. */
+  usesMask: boolean;
+  /** `true` when the procedure's builder chain carries an `.output(...)` return-shape projection. */
+  usesOutput: boolean;
+  /** `"internal"` for `internalQuery`; `"public"` for `query`. */
+  visibility: "internal" | "public";
+}
+/**
+ * One `query`/`mutation` handler that gates a `ctx.db.get`/`patch`/`delete` on a
+ * null-checked `ctx.db.normalizeId(table, id)` result — the
+ * `normalize_id_used_as_authorization` lint input. `normalizeId` validates an id's
+ * structural shape only (it never reads the database), so a non-null result proves
+ * the id is well-formed, never that the caller owns the row; gating access on it is
+ * an IDOR. The lint owns the negative proof — it keeps only `visibility === "public"`
+ * rows with no `.use(rls(...))` and no ownership/identity mention (`mentionsOwnership`),
+ * then joins `table` against the schema's RLS mode before flagging. Structurally
+ * identical to `AdvisorNormalizeIdAuthorization` so values pass straight through.
+ */
+interface NormalizeIdAuthorizationIR {
+  /** Export binding name of the procedure performing the normalize-then-access. */
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `ctx.db.normalizeId(...)` call the access is gated on. */
+  line: number;
+  /** `true` when the handler anywhere reads an ownership-named identifier or `ctx.auth`/`ctx.identity`/… — an intervening ownership signal. */
+  mentionsOwnership: boolean;
+  /** The id-first `ctx.db` sink the normalized id reaches. */
+  sinkMethod: "delete" | "get" | "patch";
+  /** Table named in the `normalizeId` call, or `""` when its table argument wasn't a string literal. */
+  table: string;
+  /** `true` when the procedure's builder chain carries a `.use(rls(...))` step. */
+  usesRls: boolean;
+  /** `"internal"` for `internalQuery`/`internalMutation`; `"public"` for `query`/`mutation`. */
+  visibility: "internal" | "public";
+}
+/**
+ * One committed `wrangler.jsonc` `vars` entry whose value is a plaintext secret —
+ * the `plaintext_secret_in_wrangler_vars` lint input. `vars` are baked into the
+ * deployed Worker in cleartext and checked into source control, so a real API key
+ * / token / private key there ships the secret to every reader of the repo and the
+ * bundle; it belongs in a Secrets Store binding or `wrangler secret put`. Produced
+ * by `@lunora/config` (which reads `wrangler.jsonc`), not a ts-morph feeder —
+ * codegen only passes it through. Structurally identical to `AdvisorWranglerVariable`.
+ */
+interface WranglerVariableIR {
+  /** The `wrangler.jsonc` file the var was read from, relative to the project root. */
+  file: string;
+  /** The offending `vars` key (e.g. `STRIPE_SECRET_KEY`). */
+  key: string;
+  /** Heuristic that matched, e.g. `stripe_live_key` / `private_key` / `secret_named_var`. */
+  kind: string;
+  /** Redacted preview of the value (first few chars + length) for the finding detail — never the full secret. */
+  preview: string;
+}
+interface ProjectIR {
+  crons: ReadonlyArray<CronJobIR>;
+  functions: ReadonlyArray<FunctionIR>;
+  /** Typed REST routes discovered from `httpRoute.<verb>(...)` builder chains. */
+  httpRoutes: ReadonlyArray<HttpRouteIR>;
+  migrations: ReadonlyArray<MigrationIR>;
+  schema: SchemaIR;
+}
+/**
+ * One import of a migrated-away platform's SDK still present in `lunora/`
+ * source. Structurally identical to the advisor's `AdvisorStaleMigrationImport`
+ * so it passes through the feeder without conversion.
+ */
+interface StaleMigrationImportIR {
+  /** Source file relative to the lunora dir, no extension. */
+  file: string;
+  /** 1-based line of the import, or `0` when unknown. */
+  line: number;
+  /** The imported module, e.g. `@supabase/supabase-js`. */
+  moduleSpecifier: string;
+  /** Which migration guide covers this platform. */
+  platform: "convex" | "firebase" | "supabase";
+}
+/**
+ * Named inputs for {@link lintSchema}. Every feeder is a discrete key rather than
+ * a positional argument: the feeder list grows every few releases and many IR
+ * types are structurally similar (`{file, exportName, line}`-shaped evidence),
+ * so a positional call was a silent-transposition hazard — swapping two adjacent
+ * arguments could typecheck yet feed the wrong evidence to the wrong lint and
+ * corrupt a security advisory. `schema` is the only required field; every other
+ * feeder defaults to "not analyzed" when omitted.
+ */
+interface LintSchemaOptions {
+  adminRoutes?: ReadonlyArray<AdminRouteIR>;
+  aiRawRuns?: ReadonlyArray<AiRawRunIR>;
+  aiToolSideEffects?: ReadonlyArray<AiToolSideEffectIR>;
+  argumentDerivedFetches?: ReadonlyArray<ArgumentDerivedFetchIR>;
+  argumentValidators?: ReadonlyArray<ArgumentValidatorIR>;
+  authApiCalls?: ReadonlyArray<AuthApiCallIR>;
+  authConfigs?: ReadonlyArray<AuthConfigIR>;
+  browserUrlAccesses?: ReadonlyArray<BrowserUrlAccessIR>;
+  configCalls?: ReadonlyArray<ConfigCallIR>;
+  containerKeyAccesses?: ReadonlyArray<ContainerKeyAccessIR>;
+  containerOverrides?: ReadonlyArray<ContainerOverrideIR>;
+  containers?: ReadonlyArray<ContainerIR>;
+  exportSinks?: ReadonlyArray<AdvisorExportSink>;
+  failOpenGuards?: ReadonlyArray<FailOpenGuardIR>;
+  flagReads?: ReadonlyArray<FlagReadIR>;
+  flagSecurityDefaults?: ReadonlyArray<FlagSecurityDefaultIR>;
+  geoIndexUsages?: ReadonlyArray<AdvisorGeoIndexUsage>;
+  httpActionGuards?: ReadonlyArray<HttpActionGuardIR>;
+  httpHeaderWrites?: ReadonlyArray<HttpHeaderWriteIR>;
+  hyperdriveCalls?: ReadonlyArray<ContextPropertyCallIR>;
+  identityClaimReads?: ReadonlyArray<IdentityClaimReadIR>;
+  imageDeliveryUrlAccesses?: ReadonlyArray<ImageDeliveryUrlAccessIR>;
+  inserts?: ReadonlyArray<InsertWriteIR>;
+  kvKeyAccesses?: ReadonlyArray<KvKeyAccessIR>;
+  mailRecipientAccesses?: ReadonlyArray<MailRecipientAccessIR>;
+  maskProcedures?: ReadonlyArray<MaskProcedureIR>;
+  maskStrategies?: ReadonlyArray<MaskStrategyIR>;
+  mutatorWrites?: ReadonlyArray<MutatorWriteIR>;
+  nondeterministicCalls?: ReadonlyArray<NondeterministicCallIR>;
+  normalizeIdAuthorizations?: ReadonlyArray<NormalizeIdAuthorizationIR>;
+  notifyCalls?: ReadonlyArray<AdvisorNotifyCall>;
+  notifyConfig?: AdvisorNotifyConfig;
+  ownerFieldWrites?: ReadonlyArray<OwnerFieldWriteIR>;
+  paymentWebhooks?: ReadonlyArray<PaymentWebhookIR>;
+  privilegedDispatches?: ReadonlyArray<PrivilegedDispatchIR>;
+  procedureProtections?: ReadonlyArray<ProcedureMiddlewareIR>;
+  queries?: ReadonlyArray<QueryReadIR>;
+  queues?: ReadonlyArray<QueueIR>;
+  r2sqlCalls?: ReadonlyArray<ContextPropertyCallIR>;
+  ratelimitKeySelectors?: ReadonlyArray<RatelimitKeySelectorIR>;
+  rawRowReturns?: ReadonlyArray<RawRowReturnIR>;
+  relationLoads?: ReadonlyArray<RelationLoadIR>;
+  rlsProcedures?: ReadonlyArray<RlsProcedureIR>;
+  schema: SchemaIR;
+  secretLiterals?: ReadonlyArray<SecretLiteralIR>;
+  shapes?: ReadonlyArray<ShapeIR>;
+  softDeleteReads?: ReadonlyArray<SoftDeleteReadIR>;
+  sqlInterpolations?: ReadonlyArray<SqlInterpolationIR>;
+  staleMigrationImports?: ReadonlyArray<StaleMigrationImportIR>;
+  storageKeyAccesses?: ReadonlyArray<StorageKeyAccessIR>;
+  storageUploads?: ReadonlyArray<StorageUploadIR>;
+  unrestrictedWhereBranches?: ReadonlyArray<UnrestrictedWhereBranchIR>;
+  vectorNamespaceAccesses?: ReadonlyArray<VectorNamespaceAccessIR>;
+  workflowCalls?: ReadonlyArray<WorkflowCallIR>;
+  workflows?: ReadonlyArray<WorkflowIR>;
+  wranglerVariables?: ReadonlyArray<WranglerVariableIR>;
+}
+/**
+ * Normalize feeder options into the advisor's {@link LintContext} — the input
+ * both `runAdvisor` and `scoreAdvisor` take. Shared by {@link lintSchema} so the
+ * lint run and the scored map always see byte-identical evidence.
+ *
+ * Exported instead of a `mapSchema(options)` convenience that lints *and* scores:
+ * such a wrapper would either re-run every rule or need a `findings` escape hatch
+ * nothing could validate against its `options`, so mismatched findings would
+ * silently produce a wrong map. Two lines at the call site buys that away:
+ *
+ * ```ts
+ * const context = toAdvisorContext(options);
+ * const map = scoreAdvisor(context.procedureProtections ?? [], runAdvisor(context, { source: "static" }));
+ * ```
+ */
+declare const toAdvisorContext: (options: LintSchemaOptions) => LintContext;
+/**
+ * Run the static lints against a discovered {@link SchemaIR} and the reads/writes/calls
+ * found in function bodies: query reads feed `filter_without_index`, insert writes
+ * feed `table_without_insert`, authApi calls feed `auth_api_call_without_headers`,
+ * rls procedure snapshots feed `rls_uncovered_table`, mask procedure
+ * snapshots feed `mask_uncovered_pii_column`, and per-column mask strategies
+ * feed `mask_weak_hash_strategy_on_pii`; declared containers
+ * feed the `container_*` lints; declared workflows (with their durable step labels)
+ * + `ctx.workflows.get(...)` call sites feed the `workflow_unused` /
+ * `workflow_unknown_target` / duplicate-step-name lints; non-deterministic
+ * calls inside query/mutation handlers feed the `nondeterministic_query_mutation` lint
+ * (all default empty for callers that don't analyze functions/containers/workflows).
+ * The IR types are structurally identical to the advisor's evidence types so they
+ * pass straight through without conversion. Returns the findings; surfacing them
+ * (console, error overlay, studio Advisors table) is the caller's choice.
+ */
+declare const lintSchema: (options: LintSchemaOptions) => Finding[];
+/**
+ * Render advisor findings as a single multi-line string for console surfacing:
+ * a one-line summary header followed by one `[LEVEL] name: detail` line per
+ * finding. Returns `""` when there are no findings.
+ */
+declare const formatAdvisories: (findings: ReadonlyArray<Finding>) => string;
+/**
+ * The canonical capability list. **Order is load-bearing** for the `emit-app.ts`
+ * long-tail: the fluent methods are emitted in the order the `appMethod`-bearing
+ * rows appear here, so this array is ordered to reproduce the original
+ * `LONG_TAIL` sequence (ai, analytics, browser, hyperdrive, images, kv, payment,
+ * r2sql, vectors). The `serverCtxField` rows are referenced by name in the ctx
+ * interface templates, so their order here is not output-affecting.
+ */
+declare const CAPABILITY_ROWS: readonly [{
+  readonly contextProperty: "access";
+  readonly key: "access";
+  readonly moduleSpecifier: "@lunora/cloudflare-access";
+}, {
+  readonly appMethod: {
+    readonly configKey: "ai";
+    readonly doc: "Override the Workers AI binding backing `ctx.ai` (defaults to `env.AI`).";
+    readonly method: "ai";
+  };
+  readonly contextProperty: "ai";
+  readonly key: "ai";
+  readonly moduleSpecifier: "@lunora/ai";
+}, {
+  readonly appMethod: {
+    readonly configKey: "analytics";
+    readonly doc: "Override the Analytics Engine dataset backing `ctx.analytics` (defaults to `env.ANALYTICS`).";
+    readonly method: "analytics";
+  };
+  readonly contextProperty: "analytics";
+  readonly key: "analytics";
+  readonly moduleSpecifier: "@lunora/bindings/analytics";
+  readonly serverCtxField: {
+    readonly field: "\n    /** Analytics Engine telemetry sink. Fire-and-forget and sampled; do not read it back in-handler. */\n    readonly analytics: import(\"@lunora/bindings/analytics\").AnalyticsClient;";
+    readonly tier: "every";
+  };
+}, {
+  readonly appMethod: {
+    readonly configKey: "browser";
+    readonly doc: "Override the Browser Rendering binding backing `ctx.browser` (defaults to `env.BROWSER`).";
+    readonly method: "browser";
+  };
+  readonly contextProperty: "browser";
+  readonly key: "browser";
+  readonly moduleSpecifier: "@lunora/browser";
+  readonly serverCtxField: {
+    readonly field: "\n    /** Browser Rendering (screenshots/PDF/scrape). Non-deterministic — available only in actions. */\n    readonly browser: import(\"@lunora/browser\").Browser;";
+    readonly tier: "action";
+  };
+}, {
+  readonly contextProperty: "containers";
+  readonly key: "container";
+  readonly moduleSpecifier: "@lunora/container";
+}, {
+  readonly contextProperty: "flags";
+  readonly key: "flags";
+  readonly moduleSpecifier: "@lunora/flags";
+}, {
+  readonly appMethod: {
+    readonly configKey: "sql";
+    readonly doc: "Wire the Hyperdrive SQL client backing `ctx.sql` — build it with `createHyperdrive` + `fromPostgresJs`/`fromNodePg`/`fromMysql2`.";
+    readonly method: "hyperdrive";
+  };
+  readonly contextProperty: "sql";
+  readonly key: "hyperdrive";
+  readonly moduleSpecifier: "@lunora/hyperdrive";
+  readonly serverCtxField: {
+    readonly field: "\n    /**\n     * External database access via Hyperdrive. Non-deterministic — available only in actions. Writes here are NOT tracked by Lunora live queries; subscriptions will not re-run on external DB changes.\n     */\n    readonly sql: import(\"@lunora/hyperdrive\").SqlClient;";
+    readonly tier: "action";
+  };
+}, {
+  readonly appMethod: {
+    readonly configKey: "images";
+    readonly doc: "Override the Images binding backing `ctx.images` (defaults to `env.IMAGES`).";
+    readonly method: "images";
+  };
+  readonly contextProperty: "images";
+  readonly key: "images";
+  readonly moduleSpecifier: "@lunora/bindings/images";
+  readonly serverCtxField: {
+    readonly field: "\n    /** Cloudflare Images transforms (resize/format/optimize). Non-deterministic — available only in actions. */\n    readonly images: import(\"@lunora/bindings/images\").Images;";
+    readonly tier: "action";
+  };
+}, {
+  readonly appMethod: {
+    readonly configKey: "kv";
+    readonly doc: "Override the Workers KV binding backing `ctx.kv` (defaults to `env.KV`).";
+    readonly method: "kv";
+  };
+  readonly contextProperty: "kv";
+  readonly key: "kv";
+  readonly moduleSpecifier: "@lunora/bindings/kv";
+  readonly serverCtxField: {
+    readonly field: "\n    readonly kv: import(\"@lunora/bindings/kv\").Kv;";
+    readonly tier: "every";
+  };
+}, {
+  readonly key: "mail";
+  readonly moduleSpecifier: "@lunora/mail";
+}, {
+  readonly contextProperty: "notify";
+  readonly key: "notify";
+  readonly moduleSpecifier: "@lunora/notify";
+}, {
+  readonly appMethod: {
+    readonly configKey: "payment";
+    readonly doc: "Wire the payment options backing `ctx.payments`.";
+    readonly method: "payment";
+  };
+  readonly contextProperty: "payments";
+  readonly key: "payments";
+  readonly moduleSpecifier: "@lunora/payment";
+}, {
+  readonly appMethod: {
+    readonly configKey: "x402";
+    readonly doc: "Wire the x402 agent-wallet pay rail backing `ctx.x402` — a payment-enabled `fetch` that answers `402` challenges under a mandatory spend policy (ActionCtx-only; spends real funds).";
+    readonly method: "x402";
+  };
+  readonly contextProperty: "x402";
+  readonly key: "x402";
+  readonly moduleSpecifier: "@lunora/x402/pay";
+}, {
+  readonly contextProperty: "pipelines";
+  readonly key: "pipelines";
+  readonly moduleSpecifier: "@lunora/bindings/pipelines";
+  readonly serverCtxField: {
+    readonly field: "\n    /** Pipelines ingestion sink (durable, R2-backed). Fire-and-forget and batched; do not read it back in-handler. */\n    readonly pipelines: import(\"@lunora/bindings/pipelines\").PipelineClient;";
+    readonly tier: "action";
+  };
+}, {
+  readonly appMethod: {
+    readonly configKey: "r2sql";
+    readonly doc: "Wire the R2 SQL client backing `ctx.r2sql` — build it with `createR2Sql({ accountId, apiToken, bucket })` (defaults to env `R2_SQL_TOKEN` / `R2_SQL_ACCOUNT_ID` / `R2_SQL_BUCKET`).";
+    readonly method: "r2sql";
+  };
+  readonly contextProperty: "r2sql";
+  readonly key: "r2sql";
+  readonly moduleSpecifier: "@lunora/bindings/r2sql";
+  readonly serverCtxField: {
+    readonly field: "\n    /**\n     * R2 SQL over Apache Iceberg tables (window functions, DISTINCT, set operations). Non-deterministic — available only in actions. Reads here are NOT tracked by Lunora live queries.\n     */\n    readonly r2sql: import(\"@lunora/bindings/r2sql\").R2SqlClient;";
+    readonly tier: "action";
+  };
+}, {
+  readonly contextProperty: "scheduler";
+  readonly key: "scheduler";
+  readonly moduleSpecifier: "@lunora/scheduler";
+}, {
+  readonly contextProperty: "storage";
+  readonly key: "storage";
+  readonly moduleSpecifier: "@lunora/storage";
+}, {
+  readonly appMethod: {
+    readonly configKey: "vectors";
+    readonly doc: "Wire the Vectorize index map backing `ctx.vectors`.";
+    readonly method: "vectors";
+  };
+  readonly contextProperty: "vectors";
+  readonly key: "vectors";
+  readonly moduleSpecifier: "@lunora/bindings/vectors";
+}, {
+  readonly contextProperty: "workflows";
+  readonly key: "workflows";
+  readonly moduleSpecifier: "@lunora/workflow";
+}];
+/** The literal union of every capability id — the single source of truth for `FeatureUsage`'s keys (so they cannot drift). */
+type CapabilityKey = (typeof CAPABILITY_ROWS)[number]["key"];
+/** The default codegen target — today's behavior, byte-identical goldens. */
+declare const DEFAULT_TARGET = "cloudflare";
+/**
+ * Read `target` from `<projectRoot>/lunora.json`.
+ *
+ * This lives in `@lunora/codegen` rather than `@lunora/config` — where the rest
+ * of the `lunora.json` reading lives — because `@lunora/config` depends on
+ * `@lunora/codegen`, not the reverse. Putting it there and importing it here
+ * would invert that edge, so config delegates to this instead and there is
+ * still exactly one parser for the key.
+ *
+ * Best-effort and deliberately unvalidated: a missing file, malformed JSONC, or
+ * a non-string value all collapse to `undefined`, because those are shape
+ * errors rather than a name the user meant. An unrecognized *name* is returned
+ * as-is so the caller's registry lookup rejects it — swallowing a typo into the
+ * default would ship an app to the wrong provider.
+ * @param projectRoot Directory containing `lunora.json`.
+ * @returns the declared target, or `undefined` when none is usable.
+ */
+declare const readProjectTarget: (projectRoot: string) => string | undefined;
+/**
+ * The target codegen should emit for: an explicit option wins, then
+ * `lunora.json`, then the default.
+ *
+ * `runCodegen` applies this itself so a caller that forgets to pass a target
+ * still emits the surface the project declared. That default matters more than
+ * it looks: a call site that silently omits the target emits the *default*
+ * surface with no diagnostic to notice, and the mismatch only shows up at
+ * runtime on the deployed app.
+ * @param projectRoot Directory containing `lunora.json`.
+ * @param explicit A caller-supplied target, if any.
+ * @returns the resolved target id — not guaranteed to be registered.
+ */
+declare const resolveCodegenTarget: (projectRoot: string, explicit?: string) => string;
+/**
+ * The target ids codegen can gate against.
+ *
+ * `@lunora/config`'s driver registry (`deployTargetIds`) used to assert
+ * equality against this — "two id spaces for one concept" — on the theory that
+ * a target with a matrix but no driver "gates a surface nothing can deploy."
+ * Both registries list `cloudflare` and `node` today, so they happen to agree;
+ * the assertion stays relaxed because agreement is a coincidence of timing, not
+ * an invariant. "Codegen can gate capabilities for this target" and "the CLI can
+ * deploy to it" are different questions, and a new host answers the first the
+ * moment its capability matrix lands — before its deploy driver exists. See
+ * `@lunora/config`'s `project-config.test.ts` for where that relaxed invariant
+ * lives.
+ * @returns the registered matrix ids, sorted.
+ */
+declare const platformMatrixIds: () => ReadonlyArray<string>;
+/** An advisor-style diagnostic about a target's platform capabilities. */
+interface PlatformDiagnostic {
+  /** The codegen capability this concerns, when it is feature-specific. */
+  feature?: CapabilityKey;
+  /** Severity. All three names are errors — each drops or misdirects an emitted surface. */
+  level: "error" | "warn";
+  /** Human-readable explanation of the gap. */
+  message: string;
+  /** The lint id: `platform_unsupported_feature`, `platform_undeclared_feature`, or `platform_unknown_target`. */
+  name: "platform_undeclared_feature" | "platform_unknown_target" | "platform_unsupported_feature";
+  /** How to resolve it. */
+  remediation: string;
+  /** The requested deploy target. */
+  target: string;
+}
+/**
+ * Committed, tracked baseline file holding the blessed structural schema
+ * snapshot the pre-deploy drift gate diffs against. Lives in `lunora/` (NOT the
+ * gitignored `_generated/`) so it is committed alongside `schema.ts`. Leading
+ * dot keeps it tucked away next to the schema it describes.
+ */
+declare const SCHEMA_SNAPSHOT_FILENAME = ".lunora-schema.json";
+/**
+ * Walk up from `startPath` until we find a `tsconfig.json` or hit the file
+ * system root. Returns the absolute path to the tsconfig, or `undefined`.
+ *
+ * Exported (see the bottom-of-file `export { findTsconfig }`) so a long-lived
+ * caller (the Vite dev-loop's cached-Project invalidation) can ask "which
+ * tsconfig would {@link createCodegenProject} resolve right now?" without
+ * duplicating the walk — recomputing it per call is a handful of `existsSync`
+ * checks, negligible next to a Project rebuild.
+ */
+declare const findTsconfig: (startPath: string) => string | undefined;
+/**
+ * Construct the ts-morph `Project` codegen discovers over. Prefers the user's
+ * `tsconfig.json` (when one is found walking up from `lunoraDirectory`) so
+ * cross-file type resolution and path aliases work; falls back to an isolated
+ * project otherwise. This is the exact construction {@link runCodegen} uses
+ * when no `project` is injected — exported so a long-lived caller (the Vite
+ * dev-loop) can build one once and reuse it across runs via
+ * {@link refreshCodegenProject} instead of re-parsing the user's whole TS
+ * program on every save.
+ */
+declare const createCodegenProject: (lunoraDirectory: string) => Project;
+/**
+ * Synchronise a reused {@link createCodegenProject} Project with the current
+ * on-disk state of `lunoraDirectory`, so the next {@link runCodegen} sees the
+ * same files a freshly-constructed Project would — without re-parsing the whole
+ * TS program. Adds any on-disk source file the Project doesn't yet have, and
+ * `refreshFromFileSystemSync()`es the ones it does (picking up edits); then
+ * removes Project source files under `lunoraDirectory` that no longer exist on
+ * disk (the classic stale-deleted-file cache bug).
+ *
+ * Files outside `lunoraDirectory` — e.g. a shared validator or type pulled in
+ * via the user's tsconfig — are also `refreshFromFileSystemSync()`ed, but only
+ * the ones already loaded into the Project; none are added. `resolveValidatorAlias`
+ * (parse-validator.ts) follows `getAliasedSymbol()` across module boundaries, so a
+ * validator defined outside `lunoraDirectory` is genuinely read from whatever
+ * source the Project currently holds — leaving those files stale made a reused
+ * Project (the Vite dev loop) silently disagree with a fresh one (`lunora
+ * codegen`) about the same source. `node_modules` is excluded: its `.d.ts` set
+ * dominates the file count and never changes mid dev-loop, so refreshing it would
+ * reinstate close to the full re-parse cost this cache exists to avoid.
+ */
+declare const refreshCodegenProject: (project: Project, lunoraDirectory: string) => void;
+/**
+ * Top-level codegen entry. Parses `<projectRoot>/lunora/schema.ts` and every
+ * function file under `<projectRoot>/lunora/`, then writes
+ * `_generated/{api,server,dataModel}.ts` next to them.
+ *
+ * When `LUNORA_CODEGEN_TIMING` is set (truthy), a single diagnostic summary
+ * line is written to stderr with the total wall time and the discovery-vs-emit
+ * split — opt-in instrumentation that is otherwise zero-cost and side-effect-free
+ * on the returned {@link CodegenResult}.
+ */
+declare const runCodegen: (options: CodegenOptions) => CodegenResult;
+interface CodegenOptions {
+  /**
+   * Which machine-readable API spec(s) to emit into `_generated/`.
+   *
+   * `"openapi"` (the default) writes only `openapi.json` (OpenAPI 3.1; covers
+   * both the RPC functions and `httpRouter()` REST routes). `"openrpc"` writes
+   * only `openrpc.json` (OpenRPC 1.x; the RPC functions only — OpenRPC cannot
+   * represent REST routes). `"both"` writes both files; `"none"` writes neither.
+   *
+   * Regardless of the choice, `CodegenResult.generated.openApi` and `.openRpc`
+   * always carry the rendered string (computation is cheap and pure); only the
+   * on-disk write is gated by this option.
+   */
+  apiSpec?: "both" | "none" | "openapi" | "openrpc";
+  /**
+   * When true, run discovery + emit (so any schema/function parse error
+   * surfaces) but skip writing files to `_generated/`. The returned
+   * `outputDirectory` is still the path that *would* have been written.
+   */
+  dryRun?: boolean;
+  /**
+   * Run the static schema advisor (unindexed FKs, …) during codegen.
+   * Defaults to `true`. When `false`, `CodegenResult.advisories` is empty.
+   * Computed regardless of `dryRun`; codegen never prints them — see
+   * {@link CodegenResult.advisories}.
+   */
+  lint?: boolean;
+  /** Override the lunora subdirectory name. Defaults to `"lunora"`. */
+  lunoraDirectory?: string;
+  /**
+   * Reuse a previously-constructed ts-morph {@link Project} instead of building
+   * a fresh one each run. The caller owns refreshing its source files from disk
+   * (see {@link refreshCodegenProject}) — codegen does not re-read changed files
+   * off an injected Project. Built via {@link createCodegenProject} when absent.
+   * Used by the Vite dev-loop to avoid re-parsing the whole TS program on every
+   * save; omit it (CLI one-shot path) to get the default fresh-Project behaviour.
+   */
+  project?: Project;
+  /** Project root containing the `lunora/` directory. */
+  projectRoot: string;
+  /**
+   * The deploy target codegen tailors the emitted `ctx.*` surface to.
+   * Defaults to `"cloudflare"` — whose capability matrix marks every feature
+   * native or emulated, so the default output is unchanged (byte-identical
+   * goldens). A target that marks a used feature unsupported omits its
+   * `ctx.*` surface and reports it in {@link CodegenResult.platformDiagnostics}.
+   * Only `"cloudflare"` is registered until other per-target `@lunora/platform`
+   * matrices land; an unknown target emits the full surface un-gated and a
+   * `platform_unknown_target` diagnostic.
+   */
+  target?: string;
+  /**
+   * Re-bless the committed schema-drift baseline (`lunora/.lunora-schema.json`)
+   * with the current structural snapshot. The baseline is ALWAYS written on
+   * first capture (when the file is absent); set this to overwrite an existing
+   * one — e.g. after the developer has added the data migration that justifies
+   * a breaking change. Ignored when `dryRun` is true.
+   */
+  updateSchemaBaseline?: boolean;
+  /**
+   * Committed `wrangler.jsonc` `vars` entries that hold plaintext secrets — the
+   * `plaintext_secret_in_wrangler_vars` lint input. Produced by `@lunora/config`
+   * (which reads `wrangler.jsonc`) and threaded through by the CLI / Vite plugin;
+   * codegen only forwards it to the advisor. Absent when no wrangler config is
+   * present or the caller doesn't scan it.
+   */
+  wranglerVariables?: ReadonlyArray<WranglerVariableIR>;
+}
+interface CodegenResult {
+  /**
+   * The normalized advisor evidence the findings were produced from, so a
+   * caller can score it into a health map (`scoreAdvisor`) without re-running
+   * discovery. `undefined` under `lint: false`.
+   *
+   * Deliberately not scored here: the map carries a `generatedAt` stamp, and
+   * codegen's result stays a pure function of the sources.
+   */
+  advisorContext?: LintContext;
+  /**
+   * Static schema advisor findings (e.g. unindexed foreign keys) produced
+   * this run. Empty when `lint` is `false` or the schema is clean. Codegen
+   * does not print these itself — each caller presents them through its own
+   * channel (the CLI logger, the vite overlay, the studio Advisors table).
+   * `formatAdvisories` is exported for a plain multi-line rendering.
+   */
+  advisories: ReadonlyArray<Finding>;
+  /**
+   * Agents discovered from `defineAgent` exports in `lunora/agents.ts` — the
+   * list the config layer reconciles into wrangler's `workflows[]` array (an
+   * agent compiles onto a Cloudflare Workflow). Agents are NOT Durable Objects,
+   * so this adds no binding or migration. Empty when the project declares none.
+   */
+  agents: ReadonlyArray<AgentIR>;
+  /**
+   * Containers discovered from `defineContainer` exports in
+   * `lunora/containers.ts` — the list the config layer reconciles into
+   * wrangler's `containers[]`, `CONTAINER_*` Durable Object bindings, and
+   * migration classes. Empty when the project declares no containers.
+   */
+  containers: ReadonlyArray<ContainerIR>;
+  /**
+   * Deduplicated cron schedules discovered from `cronJobs()` definitions —
+   * the array the vite plugin reconciles into `wrangler.jsonc`'s
+   * `triggers.crons`. Empty when the project declares no crons.
+   */
+  cronTriggers: ReadonlyArray<string>;
+  generated: {
+    /** WorkflowEntrypoint classes for declared agents (`_generated/agents.ts`); `""` (and not written) when no agents are declared. */
+    agents: string;
+    api: string;
+    /** Fluent worker-composition builder (`_generated/app.ts`) — `defineApp()`. Always written. */
+    app: string;
+    /** Partial-replication collection factories (`_generated/collections.ts`); `""` (and not written) unless the project declares shapes and installs `@lunora/db`. */
+    collections: string;
+    /** Container DO classes (`_generated/containers.ts`); `""` (and not written) when no containers are declared. */
+    containers: string;
+    crons: string;
+    dataModel: string;
+    drizzleGlobal: string;
+    drizzleShard: string;
+    functions: string;
+    /** OpenAPI 3.1.0 document (`_generated/openapi.json`), pretty-printed JSON. */
+    openApi: string;
+    /**
+     * OpenAPI document as an importable TS module (`_generated/openapi.ts`) —
+     * `export const openApiSpec`, the worker imports it for
+     * `createWorker({ openApiSpec })`. Same document as `openApi`. Written
+     * alongside `openapi.json` whenever `apiSpec` includes `openapi`.
+     */
+    openApiModule: string;
+    /** OpenRPC 1.x document (`_generated/openrpc.json`), pretty-printed JSON. Always computed; written only when `apiSpec` includes `openrpc`. */
+    openRpc: string;
+    /**
+     * OpenRPC document as an importable TS module (`_generated/openrpc.ts`) —
+     * `export const openRpcSpec`, for `createWorker({ openRpcSpec })`. Same
+     * document as `openRpc`. Written alongside `openrpc.json` whenever
+     * `apiSpec` includes `openrpc`.
+     */
+    openRpcModule: string;
+    /** Push-consumer queue registry (`_generated/queues.ts`); `""` (and not written) when no push queues are declared. */
+    queues: string;
+    /** Project-bound seed client (`_generated/seed.ts`); `""` (and not written) when `@lunora/seed` is not a declared dependency. */
+    seed: string;
+    server: string;
+    shard: string;
+    /** Static vector-index registry (`_generated/vectors.ts`) — `LUNORA_VECTOR_INDEXES`. Empty array body when the schema declares none. */
+    vectors: string;
+    /** WorkflowEntrypoint classes (`_generated/workflows.ts`); `""` (and not written) when no workflows are declared. */
+    workflows: string;
+  };
+  /**
+   * Data migrations discovered from `defineMigration` exports under `lunora/`,
+   * each with the table it iterates. The drift gate matches a NEW id against
+   * its table so a backfill only excuses breaking drift on the table it
+   * actually visits. Empty when the project declares none.
+   */
+  migrations: ReadonlyArray<MigrationIR>;
+  outputDirectory: string;
+  /**
+   * Portability diagnostics for the requested {@link CodegenOptions.target}:
+   * `ctx.*` features the app uses that the target does not support (omitted
+   * from the emitted surface), or an unknown target. Empty for a
+   * fully-supported app on the default Cloudflare target. Presentation is the
+   * caller's job, like {@link CodegenResult.advisories}.
+   */
+  platformDiagnostics: ReadonlyArray<PlatformDiagnostic>;
+  /**
+   * Queues discovered from `defineQueue` exports in `lunora/queues.ts` — the
+   * list the config layer reconciles into wrangler's `queues.producers[]` /
+   * `queues.consumers[]`. Queues are NOT Durable Objects, so this adds no
+   * binding or migration. Empty when the project declares no queues.
+   */
+  queues: ReadonlyArray<QueueIR>;
+  /**
+   * The CURRENT structural schema snapshot computed this run (tables + field
+   * kinds/optionality + indexes/relations/shard mode + declared migration ids).
+   * The pre-deploy drift gate diffs this against the committed baseline read
+   * from {@link CodegenResult.schemaSnapshotPath}. Always present, even on a
+   * `dryRun`.
+   */
+  schemaSnapshot: SchemaSnapshot;
+  /** Absolute path of the committed baseline file (`lunora/.lunora-schema.json`). */
+  schemaSnapshotPath: string;
+  /**
+   * Workflows discovered from `defineWorkflow` exports in
+   * `lunora/workflows.ts` — the list the config layer reconciles into
+   * wrangler's `workflows[]` array. Workflows are NOT Durable Objects, so this
+   * adds no binding or migration. Empty when the project declares no workflows.
+   */
+  workflows: ReadonlyArray<WorkflowIR>;
+}
+/** Deduplicated, sorted names of every ERROR-level advisory in `advisories`. */
+declare const errorAdvisoryNames: (advisories: ReadonlyArray<Pick<Finding, "level" | "name">>) => ReadonlyArray<string>;
+/** Deduplicated, sorted names of every error-level platform diagnostic in `platformDiagnostics`. */
+declare const errorPlatformDiagnosticNames: (platformDiagnostics: ReadonlyArray<Pick<PlatformDiagnostic, "level" | "name">>) => ReadonlyArray<string>;
+/**
+ * Convenience read combining both categories from a full {@link CodegenResult}
+ * — the shape the Vite plugin's `buildBlockingMessage` needs, which (unlike
+ * the CLI's `lunora codegen`/`lunora deploy`) folds ERROR-level advisories and
+ * platform diagnostics into a single blocking message with no strict/CI
+ * opt-out.
+ */
+declare const describeErrorLevelFindings: (result: Pick<CodegenResult, "advisories" | "platformDiagnostics">) => {
+  advisoryNames: ReadonlyArray<string>;
+  platformDiagnosticNames: ReadonlyArray<string>;
+};
+/**
+ * An error thrown by codegen discovery when the user's schema or function
+ * source has a structural problem that can be pinpointed to a specific source
+ * location. A `LunoraError` subclass (`code: "CODEGEN_DIAGNOSTIC"`); the `file`,
+ * `line`, and `column` properties (also passed through as the base `loc`) mirror
+ * what Vite's error-overlay `loc` field expects so the browser can display the
+ * exact spot.
+ */
+declare class CodegenDiagnosticError extends LunoraError {
+  readonly column: number;
+  readonly file: string;
+  readonly line: number;
+  constructor(message: string, file: string, line: number, column: number);
+}
+/**
+ * Build a {@link CodegenDiagnosticError} whose message includes the source
+ * location and whose `file`/`line`/`column` properties are set from the
+ * ts-morph `Node`'s position in its source file.
+ *
+ * Message format: `@lunora/codegen: <detail> (<file>:<line>:<column>)`
+ *
+ * `meta` is merged onto the returned error for callers that also carry the
+ * project-wide `LunoraError` envelope (`code`/`name`/`status`) — it never
+ * touches `file`/`line`/`column`, and the error stays an instance of
+ * {@link CodegenDiagnosticError} so the Vite overlay's `instanceof` location
+ * lookup is unaffected.
+ */
+declare const diagnosticAt: (node: Node, detail: string, meta?: Record<string, unknown>) => CodegenDiagnosticError;
+/** The only file agents may be declared in — mirrors `lunora/workflows.ts`. */
+declare const AGENTS_FILENAME = "agents.ts";
+/**
+ * Discover every agent the project declares: exported `defineAgent()` calls in
+ * `lunora/agents.ts`. Returns `[]` when the file doesn't exist. Only four things
+ * are read statically — the optional `name` override (wrangler `workflows[].name`),
+ * the optional `publicRun` opt-in (the `agents:agentRun` capability gate), the
+ * presence of a `voice` block (which turns on the voice-session Durable Object),
+ * and the presence of an `onEmail` mapper (which wires the worker `email()`
+ * handler); the rest of the agent config (model / tools / memory / voice models /
+ * the `onEmail` closure body) is runtime-only, so codegen never evaluates it.
+ */
+declare const discoverAgents: (project: Project, lunoraDirectory: string) => AgentIR[];
+/**
+ * Discover `ctx.authApi.<method>(...)` (and bare `authApi.<method>(...)`) calls
+ * under the lunora source directory and attribute each to the exported function
+ * (and file) performing it. Calls outside an exported declaration are dropped.
+ */
+declare const discoverAuthApiCalls: (project: Project, lunoraDirectory: string) => AuthApiCallIR[];
+/** The only file containers may be declared in — mirrors `lunora/crons.ts`. */
+declare const CONTAINERS_FILENAME = "containers.ts";
+/**
+ * Discover every container the project declares: exported `defineContainer()`
+ * calls in `lunora/containers.ts`. Returns `[]` when the file doesn't exist.
+ * Wrangler-relevant fields (`image`, `instanceType`, `maxInstances`, `name`)
+ * must be static literals; runtime-only fields (`env`, `sleepAfter`, …) may be
+ * any expression since the generated class imports the definition object.
+ */
+declare const discoverContainers: (project: Project, lunoraDirectory: string) => ContainerIR[];
+/**
+ * Scan every `.ts` file under `lunoraDir` for `cronJobs()` builder registrations
+ * (`crons.interval(...)`, `crons.daily(...)`, `crons.cron(...)`, …) and lift them
+ * into {@link CronJobIR}. Schedules are compiled to standard cron expressions;
+ * function references are resolved to their `namespace:fn` dispatch path, while a
+ * `workflows.NAME` / `agents.NAME` reference (or a bare identifier naming a
+ * declared workflow) resolves to a durable workflow start. Names must be unique
+ * across the project.
+ */
+declare const discoverCrons: (project: Project, lunoraDirectory: string, workflows?: ReadonlyArray<WorkflowIR>, agents?: ReadonlyArray<AgentIR>) => CronJobIR[];
+/** The only file a feature-flag provider may be declared in — mirrors `lunora/queues.ts`. */
+declare const FLAGS_FILENAME = "flags.ts";
+/**
+ * Discover the feature-flag provider a project declares in `lunora/flags.ts`.
+ * Returns `undefined` when the file doesn't exist (the app has no flags). The
+ * read is metadata-only and lenient: codegen wires `ctx.flags` purely from the
+ * file's *existence* (`run-codegen.ts`) and imports the real module for the
+ * provider value — this IR exists solely so the config layer can reconcile the
+ * wrangler `flagship` binding for the Flagship binding-mode provider. Anything
+ * it can't read statically degrades to a `custom` provider (no binding), never
+ * a thrown error.
+ */
+declare const discoverFlags: (project: Project, lunoraDirectory: string) => FlagsIR | undefined;
+/**
+ * Scan all .ts files under `lunoraDir` (skipping `_generated/` and `schema.ts`)
+ * for top-level `export const x = query/mutation/action({...})` registrations.
+ */
+declare const discoverFunctions: (project: Project, lunoraDirectory: string) => FunctionIR[];
+/**
+ * Scan all `.ts` files under `lunoraDir` (skipping `_generated/` and `schema.ts`)
+ * for `export const x = httpRoute.<verb>(...)…handler(...)` typed REST routes.
+ * These are the headline OpenAPI target: each becomes a real `paths` entry.
+ */
+declare const discoverHttpRoutes: (project: Project, lunoraDirectory: string) => HttpRouteIR[];
+/**
+ * Discover Hyperdrive `ctx.sql` accesses inside exported `query(...)` /
+ * `mutation(...)` handlers — the `hyperdrive_outside_action` lint input.
+ *
+ * The lint shipped with no feeder at all: it returns `[]` unless
+ * `context.hyperdriveCalls` is set, and nothing set it, so the one guardrail
+ * against non-deterministic external SQL in a reactive handler never fired.
+ * `ctx.sql` is typed on `ActionCtx` only, so `action(...)` bodies are skipped by
+ * the shared walker — an access there is correct usage, not a finding.
+ */
+declare const discoverHyperdriveCalls: (project: Project, lunoraDirectory: string) => ContextPropertyCallIR[];
+/**
+ * Discover `ctx.db.insert("table", …)` writes under the lunora source directory
+ * and attribute each to the exported function (and file) performing it. Calls
+ * with a non-literal table argument, or outside an exported declaration, are
+ * dropped (`table === ""` / no enclosing export).
+ */
+declare const discoverInserts: (project: Project, lunoraDirectory: string) => InsertWriteIR[];
+/**
+ * Discover masking usage for every exported Lunora procedure under the lunora
+ * source directory — the column-level twin of `discoverRlsProcedures`. For each
+ * procedure, records whether its builder chain includes `.use(mask(...))`, which
+ * `(table, column)` pairs that mask declares, and which tables it reads/writes
+ * through `ctx.db`. Feeds the `mask_uncovered_pii_column` advisor lint.
+ */
+declare const discoverMaskProcedures: (project: Project, lunoraDirectory: string) => MaskProcedureIR[];
+/**
+ * Scan all `.ts` files under `lunoraDir` for top-level
+ * `export const x = defineMigration({...})` declarations and lift them into
+ * {@link MigrationIR}. `id` must be a static string literal (it's the registry
+ * key); `table` is best-effort and left `""` when not a literal.
+ */
+declare const discoverMigrations: (project: Project, lunoraDirectory: string) => MigrationIR[];
+/** The only file custom mutators may be declared in — mirrors `lunora/queues.ts`. */
+declare const MUTATORS_FILENAME = "mutators.ts";
+/**
+ * Discover every custom mutator the project declares: exported
+ * `defineMutator()` calls in `lunora/mutators.ts`. Returns `[]` when the file
+ * doesn't exist. The export binding plus the declared `args` / `server` return
+ * type are lifted — enough to emit a typed `api.mutators.<name>` reference —
+ * while the runtime object still carries the authoritative `server` impl +
+ * `handler`, so codegen never evaluates the body. The client `client` impl is
+ * split into the browser bundle separately.
+ */
+declare const discoverMutators: (project: Project, lunoraDirectory: string) => MutatorIR[];
+/**
+ * Discover non-deterministic API calls (`Date.now`, `new Date()`, `Date()`,
+ * `Math.random`, `crypto.randomUUID`, `crypto.getRandomValues` — including
+ * `globalThis`/`self`/`window`-prefixed receivers — and `fetch`) lexically inside
+ * the handler body of every exported `query(...)` / `mutation(...)` registration
+ * under the lunora source directory — the `nondeterministic_query_mutation` lint
+ * input. `action(...)` (and `stream(...)`) registrations are intentionally
+ * skipped: actions run exactly once and may use ambient APIs freely.
+ *
+ * Traversal is scoped to the handler node (not the whole declaration), mirroring
+ * how the auth-api / insert feeders attribute calls — so a call in a sibling
+ * helper outside the handler, or in a nested `action(...)` passed elsewhere, is
+ * not attributed to the query/mutation. One {@link NondeterministicCallIR} is
+ * produced per call site.
+ */
+declare const discoverNondeterministicCalls: (project: Project, lunoraDirectory: string) => NondeterministicCallIR[];
+/** The only file a `@lunora/notify` provider may be declared in — mirrors `lunora/flags.ts`. */
+declare const NOTIFY_FILENAME = "notify.ts";
+/**
+ * Discover `ctx.notify` / `ctx.push` sends lexically inside the handler body of
+ * every exported `query(...)` / `mutation(...)` registration under the lunora
+ * source directory — the `notify_send_outside_action` lint input. `action(...)`
+ * (and `stream(...)`) registrations are intentionally skipped: a notification
+ * send is external I/O that belongs in actions. One {@link AdvisorNotifyCall} is
+ * produced per send site.
+ */
+declare const discoverNotifyCalls: (project: Project, lunoraDirectory: string) => AdvisorNotifyCall[];
+/**
+ * Discover which push channels the project's `lunora/notify.ts` default export
+ * (`defineNotify({...})`) wires plus whether any handler sends a push — the
+ * `notify_missing_push_config` lint input. Returns `undefined` when the file is
+ * absent (the app declares no notify config). The read is metadata-only and
+ * lenient (like `discoverFlags`): a `webPush`/`fcm` property's mere presence
+ * counts as the channel being wired; a non-literal config degrades to "unwired"
+ * rather than throwing.
+ */
+declare const discoverNotifyConfig: (project: Project, lunoraDirectory: string) => AdvisorNotifyConfig | undefined;
+/**
+ * Every package name the project declares a dependency on, read from the
+ * `package.json` at the project root across all four dependency fields
+ * (`dependencies`, `devDependencies`, `peerDependencies`,
+ * `optionalDependencies`).
+ *
+ * Returns `undefined` — NOT an empty set — when the manifest is absent or
+ * unparseable, which is the whole reason this exists. Studio nav gating can
+ * treat "declares nothing" and "cannot tell" the same way, but a check that
+ * errors on a missing package cannot: conflating them makes it fire on every
+ * project without a root `package.json` (the codegen fixtures, an embedded
+ * schema, a tool driving `runCodegen` directly).
+ */
+declare const readPackageDependencies: (projectRoot: string) => Set<string> | undefined;
+/**
+ * Discover every `ctx.db.query("table")…` read under the lunora source directory
+ * and reduce each to a {@link QueryReadIR}.
+ *
+ * Reads without a `.filter()` are kept too. They are never
+ * `filter_without_index` candidates (that lint gates on `hasFilter`), but an
+ * unfiltered, unindexed `.collect()` is the read `unbounded_collect` exists for
+ * — and dropping it here is precisely why nothing could see it.
+ */
+declare const discoverQueries: (project: Project, lunoraDirectory: string) => QueryReadIR[];
 /** The only file queues may be declared in — mirrors `lunora/workflows.ts`. */
 declare const QUEUES_FILENAME = "queues.ts";
 /**
-* Discover every queue the project declares: exported `defineQueue()` calls in
-* `lunora/queues.ts`. Returns `[]` when the file doesn't exist. Only the
-* wrangler-relevant literals (`name`/`mode`/batch tuning) are read; the handler
-* body is runtime-only, so codegen never evaluates it.
-*/
+ * Discover every queue the project declares: exported `defineQueue()` calls in
+ * `lunora/queues.ts`. Returns `[]` when the file doesn't exist. Only the
+ * wrangler-relevant literals (`name`/`mode`/batch tuning) are read; the handler
+ * body is runtime-only, so codegen never evaluates it.
+ */
 declare const discoverQueues: (project: Project, lunoraDirectory: string) => QueueIR[];
 /**
-* Discover `ctx.r2sql` accesses lexically inside the handler body of every
-* exported `query(...)` / `mutation(...)` registration under the lunora source
-* directory — the `r2sql_outside_action` lint input. `action(...)` (and
-* `stream(...)`) registrations are intentionally skipped: R2 SQL is the
-* external, non-reactive surface that belongs in actions.
-*
-* Traversal is scoped to the handler node (not the whole declaration), mirroring
-* `discoverNondeterministicCalls` — so a `ctx.r2sql` touch in a sibling helper
-* outside the handler is not attributed to the query/mutation. One
-* {@link R2sqlCallIR} is produced per access site.
-*/
-declare const discoverR2sqlCalls: (project: Project, lunoraDirectory: string) => R2sqlCallIR[];
+ * Discover `ctx.r2sql` accesses inside exported `query(...)` / `mutation(...)`
+ * handlers — the `r2sql_outside_action` lint input. `action(...)` is the
+ * intended home for R2 SQL and is skipped by the shared walker.
+ */
+declare const discoverR2sqlCalls: (project: Project, lunoraDirectory: string) => ContextPropertyCallIR[];
 declare const discoverRlsProcedures: (project: Project, lunoraDirectory: string) => RlsProcedureIR[];
 /**
-* Aggregate the schema-wide RLS metadata the studio's read-only inspector reads:
-* every statically-discovered `(table, on, procedure)` policy entry plus every
-* role declared via `rls(policies, { roles })`. Walks the same builder chains as
-* {@link discoverRlsProcedures} but extracts the richer `{ on }` operation +
-* role/permission shape rather than the lint's table-name set.
-*
-* Only the **builder** form (`c.use(rls(...)).query(...)`) can declare policies,
-* so bare-factory procedures contribute nothing. The `when` predicate is never
-* read — it's an opaque JS closure whose logic belongs in code, not the UI.
-* Roles are deduped by name (first declaration wins) so a role registered on
-* several procedures lists once.
-*/
+ * Aggregate the schema-wide RLS metadata the studio's read-only inspector reads:
+ * every statically-discovered `(table, on, procedure)` policy entry plus every
+ * role declared via `rls(policies, { roles })`. Walks the same builder chains as
+ * `discoverRlsProcedures` but extracts the richer `{ on }` operation +
+ * role/permission shape rather than the lint's table-name set.
+ *
+ * Only the **builder** form (`c.use(rls(...)).query(...)`) can declare policies,
+ * so bare-factory procedures contribute nothing. The `when` predicate is never
+ * read — it's an opaque JS closure whose logic belongs in code, not the UI.
+ * Roles are deduped by name (first declaration wins) so a role registered on
+ * several procedures lists once.
+ */
 declare const discoverRlsMetadata: (project: Project, lunoraDirectory: string) => RlsMetadataIR;
 /**
-* Load `&lt;projectRoot>/lunora/schema.ts`, find `defineSchema({...})`, and
-* return a structural IR. Throws if the file or call cannot be found.
-*/
-declare const discoverSchema: (project: Project, schemaPath: string, projectRoot?: string) => SchemaIR;
+ * Which sandbox tools a project imports from `@lunora/agent` (main entry or the
+ * `/sandbox` subpath), detected by NAMED value import. Drives two things:
+ * registering the `sandbox:invoke` dispatcher (ANY of the three tools — an agent
+ * whose only sandbox tool was `fsTool` used to be missed here, so every
+ * `ls`/`read`/`write`/`rm`/`stat` died on FUNCTION_NOT_FOUND) and provisioning
+ * the `BROWSER` wrangler binding (`browserTool` only — the browser op runs on
+ * `ctx.browser` inside the dispatcher, while `fsTool` reads a hand-declared R2
+ * bucket).
+ */
+interface SandboxUsage {
+  /** `import { browserTool } from "@lunora/agent"` (or `/sandbox`) appears in `lunora/`. */
+  usesSandboxBrowser: boolean;
+  /** `import { containerTool } from "@lunora/agent"` (or `/sandbox`) appears in `lunora/`. */
+  usesSandboxContainer: boolean;
+  /** `import { fsTool } from "@lunora/agent"` (or `/sandbox`) appears in `lunora/`. */
+  usesSandboxFs: boolean;
+}
 /**
-* Aggregate the schema-wide storage-rule metadata the studio's inspector reads:
-* every statically-discovered `(bucket, on, prefix, procedure)` entry across all
-* `.use(storageRules(...))` chains. Only the builder form can declare rules, so
-* bare-factory procedures contribute nothing.
-*/
+ * Scan the `lunora/` source set for named imports of the sandbox tools
+ * ({@link TOOL_FLAGS}) from `@lunora/agent` (main entry or the `/sandbox`
+ * subpath). Type-only imports (the input/option types) do not count — only a
+ * value import wires a tool into an agent. A project that imports none yields
+ * all-`false` and codegen emits byte-identical output.
+ */
+declare const discoverSandboxUsage: (project: Project, lunoraDirectory: string) => SandboxUsage;
+/**
+ * Load `<projectRoot>/lunora/schema.ts`, find `defineSchema({...})`, and
+ * return a structural IR. Throws if the file or call cannot be found.
+ */
+declare const discoverSchema: (project: Project, schemaPath: string, projectRoot?: string) => SchemaIR;
+/** The only file shapes may be declared in — mirrors `lunora/queues.ts`. */
+declare const SHAPES_FILENAME = "shapes.ts";
+/**
+ * Discover every replication shape the project declares: exported
+ * `defineShape()` calls in `lunora/shapes.ts`. Returns `[]` when the file
+ * doesn't exist. Only the export binding is lifted — the runtime object carries
+ * the authoritative `table`/`columns`/`compileWhere`, so codegen never
+ * evaluates the predicate.
+ */
+declare const discoverShapes: (project: Project, lunoraDirectory: string) => ShapeIR[];
+/**
+ * Aggregate the schema-wide storage-rule metadata the studio's inspector reads:
+ * every statically-discovered `(bucket, on, prefix, procedure)` entry across all
+ * `.use(storageRules(...))` chains. Only the builder form can declare rules, so
+ * bare-factory procedures contribute nothing.
+ */
 declare const discoverStorageRulesMetadata: (project: Project, lunoraDirectory: string) => StorageRulesMetadataIR;
 /** The only file workflows may be declared in — mirrors `lunora/containers.ts`. */
 declare const WORKFLOWS_FILENAME = "workflows.ts";
 /**
-* Discover every workflow the project declares: exported `defineWorkflow()`
-* calls in `lunora/workflows.ts`. Returns `[]` when the file doesn't exist. The
-* only wrangler-relevant literal is the optional `name` override; the workflow
-* body is runtime-only, so codegen never evaluates it.
-*/
+ * Discover every workflow the project declares: exported `defineWorkflow()`
+ * calls in `lunora/workflows.ts`. Returns `[]` when the file doesn't exist. The
+ * only wrangler-relevant literal is the optional `name` override; the workflow
+ * body is runtime-only, so codegen never evaluates it.
+ */
 declare const discoverWorkflows: (project: Project, lunoraDirectory: string) => WorkflowIR[];
 declare const GENERATED_HEADER = "// GENERATED by @lunora/codegen — do not edit.\n// Run `lunora codegen` to regenerate.\n\n";
-/** Emit `_generated/dataModel.ts` — `Doc&lt;"name">` + `Id&lt;"name">` for every table. */
-declare const emitDataModel: (schema: SchemaIR, useUmbrella?: boolean) => string;
-/**
-* Emit `_generated/api.ts` — the typed `api.*` registry (public functions), the
-* `internal.*` registry, and (when the project declares workflows) the typed
-* `workflows.*` reference object. `api`/`internal` are the same `anyApi` proxy
-* at runtime (the `__lunoraRef` is identical); visibility is enforced
-* server-side at dispatch, not in the reference. Splitting the *types* keeps
-* internal functions off the client-facing `api` surface.
-*/
-declare const emitApi: (functions: ReadonlyArray<FunctionIR>, workflows?: ReadonlyArray<WorkflowIR>, useUmbrella?: boolean) => string;
-/**
-* Emit `_generated/seed.ts` — a project-bound `createSeedClient` with this
-* schema's `InsertModel` and runtime schema pre-applied, so a test or script
-* calls `createSeedClient({ seed: 1 }).users(5)` with full column types and no
-* manual wiring. The runtime schema is the default export of `lunora/schema.ts`
-* (the same import the generated ShardDO uses).
-*
-* Returns `""` when `@lunora/seed` is not a declared dependency, so projects
-* that don't use it keep a clean `_generated/` and never import the package.
-*/
+/** Emit `_generated/dataModel.ts` — `Doc<"name">` + `Id<"name">` for every table. */
+declare const emitDataModel: (schema: SchemaIR) => string;
+/**
+ * Emit `_generated/api.ts` — the typed `api.*` registry (public functions), the
+ * `internal.*` registry, and (when the project declares them) the typed
+ * `workflows.*` / `agents.*` scheduler-target reference objects. `api`/`internal` are the same `anyApi` proxy
+ * at runtime (the `__lunoraRef` is identical); visibility is enforced
+ * server-side at dispatch, not in the reference. Splitting the *types* keeps
+ * internal functions off the client-facing `api` surface.
+ */
+interface EmitApiOptions {
+  agents?: ReadonlyArray<AgentIR>;
+  functions: ReadonlyArray<FunctionIR>;
+  /** Typed REST routes; only `.stream()` (SSE) routes emit a `httpStreams.*` reference. */
+  httpRoutes?: ReadonlyArray<HttpRouteIR>;
+  /** Custom mutators (`lunora/mutators.ts`) — emitted as `api.mutators.*` so a client `serverRef` is compile-checked. */
+  mutators?: ReadonlyArray<MutatorIR>;
+  useUmbrella?: boolean;
+  workflows?: ReadonlyArray<WorkflowIR>;
+}
+declare const emitApi: (options: EmitApiOptions) => string;
+/**
+ * Emit `_generated/collections.ts` — a typed TanStack DB binding per `defineShape`
+ * in `lunora/shapes.ts` (the local-first partial-replication surface).
+ *
+ * Each shape emits **two** entry points.
+ *
+ * `<shape>CollectionOptions(options)` is the composable form: it returns the full
+ * `LunoraCollectionOptions` — `config` for `createCollection`, plus `checkpoints`
+ * (which `bindMutators` gates optimistic overlays on) and `scope`. This is what an app
+ * with custom mutators needs, and what the old single-factory form made impossible: it
+ * built the collection internally and dropped `checkpoints` on the floor, so there was
+ * no way to wire mutators to the collection codegen produced.
+ *
+ * `<shape>Collection(options)` is the convenience form for a read-only collection: it
+ * returns `{ checkpoints, collection, scope }` rather than a bare `Collection`, so the
+ * sync controls stay reachable even from the short path.
+ *
+ * Both are typed: `args` comes from the shape's own validators (a parameterless
+ * shape takes none), rows resolve to `Doc<"table">` when the shape names its table
+ * with a literal, and `shardKey` / `getKey` / `load` / `onError` / `checkpoints` are
+ * all threadable — a sharded table needs `shardKey` for its watermark to land in the
+ * right bucket, and a server-minted `_id` that differs from the app's natural key
+ * needs `getKey`.
+ *
+ * Returns `""` (so `writeIfPresent` skips the file) unless the project both
+ * declares shapes AND installs `@lunora/db` — the add-on that ships
+ * `lunoraCollectionOptions`. `@lunora/db` stays a scoped install even under the
+ * `lunorash` umbrella (an opt-in add-on, like `@lunora/auth`), so its import is
+ * always `@lunora/db/collections`; only the in-umbrella `@lunora/client` import
+ * is remapped to `lunorash/client`.
+ */
+declare const emitCollections: (shapes: ReadonlyArray<ShapeIR>, hasDatabase: boolean, useUmbrella?: boolean) => string;
 interface EmitServerOptions {
+  /** Agents declared via `defineAgent` exports — wires the typed `ctx.agents` producers onto Mutation/Action contexts. */
+  agents?: ReadonlyArray<AgentIR>;
   containers?: ReadonlyArray<ContainerIR>;
+  /**
+   * The single `defineEnv(...)` contract declared in `lunora/env.ts`. When
+   * present, `ctx.env` is typed as the validated `InferEnv` shape (recovered
+   * via `ReturnType` over the accessor's `typeof`). `undefined` leaves `ctx.env`
+   * the base optional binding record — byte-identical to today.
+   */
+  env?: EnvIR;
+  /**
+   * A `lunora/` source reads `ctx.access` — wires the verified Cloudflare Access
+   * facade (`@lunora/cloudflare-access/context`) onto every ctx. Distinct from
+   * `emitApp`'s `hasAccess` (which gates the worker's `.access()` resolveIdentity
+   * method); this one gates the per-request `ctx.access` read surface.
+   */
+  hasAccessFacade?: boolean;
   hasAi?: boolean;
   /** A `lunora/` source uses `@lunora/bindings/analytics` / `ctx.analytics` — wires the write helper onto every ctx. */
   hasAnalytics?: boolean;
@@ -1016,11 +3047,26 @@ interface EmitServerOptions {
   hasImages?: boolean;
   /** A `lunora/` source uses `@lunora/bindings/kv` / `ctx.kv` — wires `ctx.kv` onto every ctx. */
   hasKv?: boolean;
+  /** The project declares `lunora/notify.ts` — wires `ctx.notify` + its `ctx.push` alias (`@lunora/notify`) onto every ctx. */
+  hasNotify?: boolean;
   hasPayments?: boolean;
   /** A `lunora/` source uses `@lunora/bindings/pipelines` / `ctx.pipelines` — wires `ctx.pipelines` onto ActionCtx only. */
   hasPipelines?: boolean;
   /** A `lunora/` source uses `@lunora/bindings/r2sql` / `ctx.r2sql` — wires `ctx.r2sql` onto ActionCtx only. */
   hasR2sql?: boolean;
+  /** The target platform supports a vector store. `false` withholds `ctx.vectors` even when the schema declares an index. */
+  hasVectors?: boolean;
+  /** A `lunora/` source uses `@lunora/x402/pay` / `ctx.x402` — wires the agent-wallet pay rail onto ActionCtx only. */
+  hasX402?: boolean;
+  /**
+   * The single `defineIdentity(...)` claim contract declared in
+   * `lunora/identity.ts` (Plan 080). When present, `ctx.auth.getIdentity()`,
+   * the RLS policy `ctx.auth.identity`, and the shard-authorization hooks
+   * narrow to the declared shape (recovered via `InferIdentity` over the
+   * contract's `typeof`). `undefined` keeps the identity an untyped bag —
+   * byte-identical to today.
+   */
+  identity?: IdentityIR;
   /** Queues declared via `defineQueue` exports — wires the typed `ctx.queues` producers onto Mutation/Action contexts. */
   queues?: ReadonlyArray<QueueIR>;
   schema?: SchemaIR;
@@ -1029,68 +3075,62 @@ interface EmitServerOptions {
   useUmbrella?: boolean;
   workflows?: ReadonlyArray<WorkflowIR>;
 }
-declare const emitServer: ({
-  containers,
-  hasAi,
-  hasAnalytics,
-  hasBrowser,
-  hasFlags,
-  hasHyperdrive,
-  hasImages,
-  hasKv,
-  hasPayments,
-  hasPipelines,
-  hasR2sql,
-  queues,
-  schema,
-  storageRuleBuckets,
-  useUmbrella,
-  workflows
-}?: EmitServerOptions) => string;
-declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>, useUmbrella?: boolean) => string;
-/**
-* Storage-column map per table for the file browser: `{ table: [field, …] }` for
-* every field declared `v.storage(...)` (unwrapping `v.optional(...)`). The
-* generated shard hands this to the base `storageColumns` hook so the admin
-* `storageReferences` read can join R2 objects back to the rows that own them
-* (and flag orphans — objects no row references). Only scalar storage columns
-* are emitted; an array-of-storage field can't be matched by an equality scan,
-* so it is skipped here.
-*/
-/**
-* Emit `_generated/containers.ts` — one container-enabled Durable Object class
-* per `defineContainer` export, each a thin subclass of `LunoraContainer`
-* (`@lunora/container/do`) constructed with the user's definition object. The
-* worker entry must re-export these classes: wrangler requires every
-* `containers[].class_name` to be exported by the deployed worker. Returns ""
-* when the project declares no containers (the file is not written then).
-*/
+declare const emitServer: ({ agents, containers, env, hasAccessFacade, hasAi, hasAnalytics, hasBrowser, hasVectors, hasFlags, hasHyperdrive, hasImages, hasKv, hasNotify, hasPayments, hasPipelines, hasR2sql, hasX402, identity, queues, schema, storageRuleBuckets, useUmbrella, workflows }?: EmitServerOptions) => string;
+interface EmitFunctionsOptions {
+  agents?: ReadonlyArray<AgentIR>;
+  functions: ReadonlyArray<FunctionIR>;
+  migrations?: ReadonlyArray<MigrationIR>;
+  mutators?: ReadonlyArray<MutatorIR>;
+  shapes?: ReadonlyArray<ShapeIR>;
+  /** Import of a sandbox tool (`browserTool`/`containerTool`) auto-registers the `sandbox:invoke` action. */
+  usesSandbox?: boolean;
+  useUmbrella?: boolean;
+}
+declare const emitFunctions: (options: EmitFunctionsOptions) => string;
+/**
+ * Emit `_generated/containers.ts` — one container-enabled Durable Object class
+ * per `defineContainer` export, each a thin subclass of `LunoraContainer`
+ * (`@lunora/container/do`) constructed with the user's definition object. The
+ * worker entry must re-export these classes: wrangler requires every
+ * `containers[].class_name` to be exported by the deployed worker. Returns ""
+ * when the project declares no containers (the file is not written then).
+ */
 declare const emitContainers: (containers: ReadonlyArray<ContainerIR>, jurisdiction?: JurisdictionIR) => string;
 /**
-* Emit `_generated/workflows.ts` — one `WorkflowEntrypoint` class per
-* `defineWorkflow` export, each a thin subclass of `LunoraWorkflow`
-* (`@lunora/workflow/do`) constructed with the user's definition object. The
-* worker entry must re-export these classes: wrangler requires every
-* `workflows[].class_name` to be exported by the deployed worker. Returns ""
-* when the project declares no workflows (the file is not written then).
-*/
+ * Emit `_generated/workflows.ts` — one `WorkflowEntrypoint` class per
+ * `defineWorkflow` export, each a thin subclass of `LunoraWorkflow`
+ * (`@lunora/workflow/do`) constructed with the user's definition object. The
+ * worker entry must re-export these classes: wrangler requires every
+ * `workflows[].class_name` to be exported by the deployed worker. Returns ""
+ * when the project declares no workflows (the file is not written then).
+ */
 declare const emitWorkflows: (workflows: ReadonlyArray<WorkflowIR>) => string;
 /**
-* Emit `_generated/queues.ts` — the push-consumer registry the worker `queue()`
-* handler dispatches through. Maps each push queue's stable wrangler name (which
-* `batch.queue` carries) to its `defineQueue` definition + export name. Pull
-* queues are consumed by an external worker, so they carry no handler and are
-* omitted here. Returns "" (and the file is not written) when no push queues are
-* declared — a pull-only or queue-free app keeps a clean `_generated/`.
-*/
+ * Emit `_generated/agents.ts` — one `WorkflowEntrypoint` class per `defineAgent`
+ * export, each a thin subclass of `LunoraWorkflow` (`@lunora/workflow/do`)
+ * constructed with the compiled agent tool-loop (`compileAgentWorkflow`). Like
+ * `_generated/workflows.ts`, the worker entry must re-export these classes:
+ * wrangler requires every `workflows[].class_name` to be exported by the
+ * deployed worker. Returns "" when the project declares no agents (the file is
+ * not written then).
+ */
+declare const emitAgents: (agents: ReadonlyArray<AgentIR>) => string;
 interface EmitShardOptions {
   advisories?: ReadonlyArray<Finding>;
+  /** Every declared procedure — the health map's denominator, served via `getAdvisorProcedures`. */
+  advisorProcedures?: ReadonlyArray<AdvisorProcedureProtection>;
+  /** Agents declared via `defineAgent` exports in `lunora/agents.ts` — wires the typed `ctx.agents` producers. */
+  agents?: ReadonlyArray<AgentIR>;
   containers?: ReadonlyArray<ContainerIR>;
-  /** Statically-discovered `ctx.flags.&lt;type>("key")` reads — the studio Flags page + reactive evaluation iterate these. */
+  /** The single `defineEnv(...)` contract declared in `lunora/env.ts` — applies the accessor to the worker `env` to populate `ctx.env`. */
+  env?: EnvIR;
+  /** Statically-discovered `ctx.flags.<type>("key")` reads — the studio Flags page + reactive evaluation iterate these. */
   flagKeys?: ReadonlyArray<{
     key: string;
     type: "boolean" | "number" | "object" | "string";
   }>;
+  /** A `lunora/` source reads `ctx.access` — wires the verified Cloudflare Access facade onto every ctx. */
+  hasAccessFacade?: boolean;
   hasAi?: boolean;
   /** A `lunora/` source reads `ctx.analytics` — wires the Analytics Engine write helper onto every ctx. */
   hasAnalytics?: boolean;
@@ -1104,104 +3144,110 @@ interface EmitShardOptions {
   hasImages?: boolean;
   /** A `lunora/` source reads `ctx.kv` — wires `ctx.kv` onto every ctx. */
   hasKv?: boolean;
+  /** The project declares `lunora/notify.ts` — wires `ctx.notify` + its `ctx.push` alias (`@lunora/notify`) onto every ctx. */
+  hasNotify?: boolean;
   hasPayments?: boolean;
   /** A `lunora/` source reads `ctx.pipelines` — wires `ctx.pipelines` onto the ActionCtx only. */
   hasPipelines?: boolean;
   /** A `lunora/` source reads `ctx.r2sql` (R2 SQL) — wires `ctx.r2sql` onto the ActionCtx only. */
   hasR2sql?: boolean;
+  /** A `lunora/` source reads `ctx.x402` — wires the agent-wallet pay rail onto the ActionCtx only. */
+  hasX402?: boolean;
   maskMetadata?: MaskMetadataIR;
+  /** Custom mutators declared via `defineMutator` in `lunora/mutators.ts` — wires the `isCustomMutator` push-protocol override. */
+  mutators?: ReadonlyArray<MutatorIR>;
   /** Queues declared via `defineQueue` exports in `lunora/queues.ts` — wires the typed `ctx.queues` producers. */
   queues?: ReadonlyArray<QueueIR>;
   rlsMetadata?: RlsMetadataIR;
   schema: SchemaIR;
+  /**
+   * The structural snapshot the pre-deploy drift gate diffs against, threaded
+   * in so the emitted DO records it in `__lunora_schema_history` on cold start
+   * (plan 200 — the Studio's schema-version timeline). Optional so an emitter
+   * caller that has no snapshot (tests, fixtures) emits the pre-ledger shape
+   * unchanged.
+   */
+  schemaSnapshot?: SchemaSnapshot;
+  /** Replication shapes declared via `defineShape` in `lunora/shapes.ts` — wires the `resolveShape` subscription override. */
+  shapes?: ReadonlyArray<ShapeIR>;
   storageRules?: StorageRulesMetadataIR;
   studioFeatures?: StudioFeaturesResult;
   /** The project depends on the `lunora` umbrella — import base packages via its subpaths. */
   useUmbrella?: boolean;
   workflows?: ReadonlyArray<WorkflowIR>;
 }
-declare const emitShard: ({
-  advisories,
-  containers,
-  flagKeys,
-  hasAi,
-  hasAnalytics,
-  hasBrowser,
-  hasFlags,
-  hasHyperdrive,
-  hasImages,
-  hasKv,
-  hasPayments,
-  hasPipelines,
-  hasR2sql,
-  maskMetadata,
-  queues,
-  rlsMetadata,
-  schema,
-  storageRules,
-  studioFeatures,
-  useUmbrella,
-  workflows
-}: EmitShardOptions) => string;
-/**
-* Emit drizzle `sqliteTable` definitions for the project schema, split into
-* `global` (D1-backed) and `shard` (DO-SQLite-backed) buckets. Tables marked
-* `.global()` go in the global file; everything else (default root + `.shardBy()`)
-* goes in the shard file.
-*
-* `searchIndexes` are intentionally not emitted — drizzle has no `sqliteTable`
-* abstraction for FTS5 virtual tables. FTS plumbing is handled by the runtime
-* outside of drizzle.
-*/
+declare const emitShard: ({ advisories, advisorProcedures, agents, containers, env, flagKeys, hasAccessFacade, hasAi, hasAnalytics, hasBrowser, hasFlags, hasHyperdrive, hasImages, hasKv, hasNotify, hasPayments, hasPipelines, hasR2sql, hasX402, maskMetadata, mutators, queues, rlsMetadata, schema, schemaSnapshot, shapes, storageRules, studioFeatures, useUmbrella, workflows }: EmitShardOptions) => string;
+/**
+ * Emit drizzle `sqliteTable` definitions for the project schema, split into
+ * `global` (D1-backed) and `shard` (DO-SQLite-backed) buckets. Tables marked
+ * `.global()` go in the global file; everything else (default root + `.shardBy()`)
+ * goes in the shard file.
+ *
+ * `searchIndexes` are intentionally not emitted — drizzle has no `sqliteTable`
+ * abstraction for FTS5 virtual tables. FTS plumbing is handled by the runtime
+ * outside of drizzle.
+ */
 declare const emitDrizzleSchema: (schema: SchemaIR, useUmbrella?: boolean) => {
   global: string;
   shard: string;
 };
 /**
-* Emit `_generated/crons.ts` from the discovered cron jobs.
-*
-* `LUNORA_CRON_TRIGGERS` is the deduplicated schedule array — what lands in
-* wrangler's `triggers.crons` (the vite plugin reconciles it into
-* `wrangler.jsonc`, and {@link emitWranglerCronTriggers} renders the same list
-* for the CLI / docs).
-*
-* `LUNORA_CRONS` is the dispatcher map keyed by cron expression, each value a
-* list of `{ name, functionPath, args }`. Cloudflare's `scheduled()` handler
-* receives only the cron string, so multiple jobs sharing one expression must
-* all fire — hence a list per key rather than a single entry.
-*
-* Jobs arrive pre-sorted by name (deterministic output); the trigger array
-* preserves first-seen order of distinct expressions.
-*
-* Cloudflare caps a Worker at **3 Cron Triggers** (i.e. 3 distinct cron
-* expressions). Because the dispatcher fires every job sharing an expression,
-* many jobs can ride a single trigger — only the count of *distinct* schedules
-* matters. `lunora codegen` warns when that count exceeds the limit; for
-* finer-grained scheduling use Durable Object alarms (`@lunora/scheduler`),
-* which have no such cap.
-*/
+ * Emit `_generated/crons.ts` from the discovered cron jobs.
+ *
+ * `LUNORA_CRON_TRIGGERS` is the deduplicated schedule array — what lands in
+ * wrangler's `triggers.crons` (the vite plugin reconciles it into
+ * `wrangler.jsonc`, and {@link emitWranglerCronTriggers} renders the same list
+ * for the CLI / docs).
+ *
+ * `LUNORA_CRONS` is the dispatcher map keyed by cron expression, each value a
+ * list of `{ name, functionPath, args }`. Cloudflare's `scheduled()` handler
+ * receives only the cron string, so multiple jobs sharing one expression must
+ * all fire — hence a list per key rather than a single entry.
+ *
+ * Jobs arrive pre-sorted by name (deterministic output); the trigger array
+ * preserves first-seen order of distinct expressions.
+ *
+ * Cloudflare caps a Worker at **3 Cron Triggers** (i.e. 3 distinct cron
+ * expressions). Because the dispatcher fires every job sharing an expression,
+ * many jobs can ride a single trigger — only the count of *distinct* schedules
+ * matters. `lunora codegen` warns when that count exceeds the limit; for
+ * finer-grained scheduling use Durable Object alarms (`@lunora/scheduler`),
+ * which have no such cap.
+ */
 declare const emitCrons: (crons: ReadonlyArray<CronJobIR>) => string;
 /**
-* Render `_generated/vectors.ts` — the static registry of every vector index
-* declared in `schema.ts` (inline `.vectorize()` columns + standalone
-* `defineVectorIndex()` definitions).
-*
-* Cloudflare Vectorize exposes no way to enumerate an account's indexes at
-* runtime — a binding can `describe()` itself but the worker can't ask "which
-* indexes exist". So this generated array is the source of truth the studio's
-* vector browser lists, and the worker's admin route pairs each entry with its
-* live `describe()` stats. Entries are sorted by name for deterministic output.
-*/
+ * Render `_generated/vectors.ts` — the static registry of every vector index
+ * declared in `schema.ts` (inline `.vectorize()` columns + standalone
+ * `defineVectorIndex()` definitions).
+ *
+ * Cloudflare Vectorize exposes no way to enumerate an account's indexes at
+ * runtime — a binding can `describe()` itself but the worker can't ask "which
+ * indexes exist". So this generated array is the source of truth the studio's
+ * vector browser lists, and the worker's admin route pairs each entry with its
+ * live `describe()` stats. Entries are sorted by name for deterministic output.
+ */
 declare const emitVectors: (vectorIndexes: ReadonlyArray<VectorIndexIR>) => string;
 /**
-* Render the deduplicated cron schedules as a JSON fragment suitable for
-* splicing into `wrangler.jsonc`'s `triggers.crons`. The vite plugin uses this
-* (plus the parsed wrangler config) to reconcile generated triggers without the
-* user hand-editing the file.
-*/
+ * Render the deduplicated cron schedules as a JSON fragment suitable for
+ * splicing into `wrangler.jsonc`'s `triggers.crons`. The vite plugin uses this
+ * (plus the parsed wrangler config) to reconcile generated triggers without the
+ * user hand-editing the file.
+ */
 declare const emitWranglerCronTriggers: (crons: ReadonlyArray<CronJobIR>) => string[];
 /** Which capability methods the generated `defineApp` builder exposes — one flag per package-backed feature the app actually uses. */
 interface EmitAppOptions {
+  /**
+   * Inbound-email agents (`defineAgent({ onEmail })`) → wire the worker's
+   * top-level `email()` handler to `dispatchAgentEmail(...)` (from
+   * `@lunora/agent/inbound`), so received mail starts a durable run. Empty/absent
+   * ⇒ no wiring, byte-identical output for email-free (and agent-free) projects.
+   */
+  emailAgents?: ReadonlyArray<{
+    bindingName: string;
+    exportName: string;
+  }>;
+  /** App depends on `@lunora/cloudflare-access` → emit `.access()` (wire the Cloudflare Access `resolveIdentity`, composed ahead of `@lunora/auth` when both are present). */
+  hasAccess: boolean;
   /** App uses `@lunora/ai` / `ctx.ai` → emit `.ai()` (override the Workers AI binding backing `ctx.ai`). */
   hasAi: boolean;
   /** App uses `@lunora/bindings/analytics` / `ctx.analytics` → emit `.analytics()` (override the dataset backing `ctx.analytics`). */
@@ -1220,8 +3266,21 @@ interface EmitAppOptions {
   hasHyperdriveGlobal: boolean;
   /** App uses `@lunora/bindings/images` / `ctx.images` → emit `.images()`. */
   hasImages: boolean;
-  /** App uses `@lunora/bindings/kv` / `ctx.kv` → emit `.kv()`. */
+  /** App uses `@lunora/bindings/kv` / `ctx.kv` → emit `.kv()`. Usage-only, because the method's parameter type reads `ShardConfig["kv"]`, and that config field is emitted on the same usage signal. */
   hasKv: boolean;
+  /**
+   * Wire the studio's zero-config KV introspector. Gated on `studioFeatures.kv`
+   * (usage OR a declared `@lunora/bindings` dependency), NOT on {@link EmitAppOptions.hasKv},
+   * so a visible KV tab always has a working backend — never the reverse.
+   *
+   * Kept separate from `hasKv` deliberately: the two were accidentally equal
+   * while the dependency arm in `discover/studio-features.ts` matched a subpath
+   * and could never fire. Fixing that arm made them diverge, and the shared flag
+   * emitted a `.kv()` builder whose `ShardConfig["kv"]` type did not exist.
+   */
+  hasKvIntrospector: boolean;
+  /** App declares `lunora/notify.ts` (`@lunora/notify`) → wire `options.notifySubscriptionStore` so the studio Notifications page can read registered devices. */
+  hasNotify: boolean;
   /** App uses `@lunora/payment` / `ctx.payments` → emit `.payment()`. */
   hasPayments: boolean;
   /** App declares push queues (`defineQueue`) → wire `LUNORA_QUEUE_REGISTRY` into the worker's `queue()` consumer entry. */
@@ -1236,30 +3295,53 @@ interface EmitAppOptions {
   hasVectors: boolean;
   /** App declares Cloudflare Workflows (`defineWorkflow`) → wire `options.workflowsClient` so the studio's workflow-instance proxy can reach the CF REST API. */
   hasWorkflow: boolean;
+  /** App uses `@lunora/x402/pay` / `ctx.x402` → emit `.x402()` (wire the agent-wallet pay rail). */
+  hasX402: boolean;
+  /** The single `defineIdentity(...)` contract in `lunora/identity.ts` (Plan 080) → import it as a VALUE and wire `options.identity`, so the runtime trust boundary validates every resolved identity before it becomes `ctx.auth`. `undefined` ⇒ no wiring, byte-identical output. */
+  identity?: IdentityIR;
   /** Schema declares `.jurisdiction("…")` → pin every DO the worker reaches (shards, fan-out, scheduler, containers) to the Cloudflare data-residency jurisdiction. */
   jurisdiction?: JurisdictionIR;
+  /**
+   * Every table the schema declares. Emitted as a literal `listSchemaTables`
+   * so export can answer "every table" with a real list: shard discovery is
+   * driven by the table list, so an export naming no tables reaches no shards.
+   * A literal (rather than a read off the imported `schema`) keeps this working
+   * for apps with no `.global()` tables, which never import `schema` at all.
+   */
+  tableNames: ReadonlyArray<string>;
   /** Project depends on the unscoped `lunorash` umbrella → import the runtime via `lunorash/runtime` instead of `@lunora/runtime`. */
   useUmbrella: boolean;
+  /**
+   * Voice-enabled agents (`defineAgent({ voice: … })`) → wire
+   * `options.voiceAgents`, mapping each agent's export name to its `VOICE_*`
+   * Durable Object namespace binding so the runtime exposes
+   * `/_lunora/voice/<exportName>`. Empty/absent ⇒ no wiring, byte-identical
+   * output for voice-free (and agent-free) projects.
+   */
+  voiceAgents?: ReadonlyArray<{
+    bindingName: string;
+    exportName: string;
+  }>;
   /** An OpenAPI spec is emitted (`openapi.ts`) → wire `openApiSpec` into the worker. */
   wantsOpenApi: boolean;
   /** An OpenRPC spec is emitted (`openrpc.ts`) → wire `openRpcSpec` into the worker. */
   wantsOpenRpc: boolean;
 }
 /**
-* Emit `_generated/app.ts` — a fluent, feature-specialized worker-composition
-* builder. Only the methods for capabilities THIS app uses are emitted, so the
-* builder's type surface (IntelliSense) lists exactly what can be configured.
-*
-* Each capability declaration is fanned into BOTH runtime surfaces: the DO-side
-* `createShardDO(...)` factory that backs `ctx.*`, and the worker-side
-* `createWorker(...)` options that back the studio/admin endpoints — so storage
-* / scheduler / global are declared once instead of twice. The builder is pure
-* sugar over the public `createWorker` / `createShardDO`; both stay usable.
-*
-* Lives in generated code (not `@lunora/runtime`, which is dependency-free) so
-* it can import the add-on packages the app installed (`@lunora/auth`,
-* `@lunora/storage`, …) directly.
-*/
+ * Emit `_generated/app.ts` — a fluent, feature-specialized worker-composition
+ * builder. Only the methods for capabilities THIS app uses are emitted, so the
+ * builder's type surface (IntelliSense) lists exactly what can be configured.
+ *
+ * Each capability declaration is fanned into BOTH runtime surfaces: the DO-side
+ * `createShardDO(...)` factory that backs `ctx.*`, and the worker-side
+ * `createWorker(...)` options that back the studio/admin endpoints — so storage
+ * / scheduler / global are declared once instead of twice. The builder is pure
+ * sugar over the public `createWorker` / `createShardDO`; both stay usable.
+ *
+ * Lives in generated code (not `@lunora/runtime`, which is dependency-free) so
+ * it can import the add-on packages the app installed (`@lunora/auth`,
+ * `@lunora/storage`, …) directly.
+ */
 declare const emitApp: (options: EmitAppOptions) => string;
 /** Inputs the OpenAPI emitter needs from a codegen run. */
 interface OpenApiEmitInput {
@@ -1269,40 +3351,40 @@ interface OpenApiEmitInput {
   version?: string;
 }
 /**
-* Emit an OpenAPI 3.1.0 document covering both Lunora function surfaces.
-*
-* `httpRouter()` typed REST routes become real `paths` keyed by their method +
-* URL, with query/path parameters and JSON request bodies derived from their
-* `v.*` validators, and a response schema from `.output()` when declared.
-*
-* RPC `query`/`mutation`/`action` functions become one operation each on
-* `POST /_lunora/rpc` (disambiguated by a `#functionPath` path fragment), with a
-* requestBody pinning `functionPath` + typed `args`. `internal`/`stream`
-* functions are excluded (unreachable / not invocable on the external RPC path).
-*
-* Operations are grouped into `tags` by file namespace, and every operation
-* references a reusable `LunoraError` error-response component enumerating the
-* standard error codes. Borrows oRPC's per-procedure-operation + tag-grouping +
-* internal-filtering structure; the JSON Schema dialect matches `@lunora/values`
-* (Draft 2020-12). Returns the document as a plain object (the single source of
-* truth `emitOpenApi` stringifies and `emitOpenApiModule` inlines, so the
-* `.json` and `.ts` artifacts can never drift).
-*/
+ * Emit an OpenAPI 3.1.0 document covering both Lunora function surfaces.
+ *
+ * `httpRouter()` typed REST routes become real `paths` keyed by their method +
+ * URL, with query/path parameters and JSON request bodies derived from their
+ * `v.*` validators, and a response schema from `.output()` when declared.
+ *
+ * RPC `query`/`mutation`/`action` functions become one operation each on
+ * `POST /_lunora/rpc` (disambiguated by a `#functionPath` path fragment), with a
+ * requestBody pinning `functionPath` + typed `args`. `internal`/`stream`
+ * functions are excluded (unreachable / not invocable on the external RPC path).
+ *
+ * Operations are grouped into `tags` by file namespace, and every operation
+ * references a reusable `LunoraError` error-response component enumerating the
+ * standard error codes. Borrows oRPC's per-procedure-operation + tag-grouping +
+ * internal-filtering structure; the JSON Schema dialect matches `@lunora/values`
+ * (Draft 2020-12). Returns the document as a plain object (the single source of
+ * truth `emitOpenApi` stringifies and `emitOpenApiModule` inlines, so the
+ * `.json` and `.ts` artifacts can never drift).
+ */
 declare const buildOpenApiDocument: (input: OpenApiEmitInput) => Record<string, unknown>;
 /**
-* Emit the OpenAPI 3.1 document as a pretty-printed JSON string
-* (`_generated/openapi.json`) — the portable artifact for external tooling.
-*/
+ * Emit the OpenAPI 3.1 document as a pretty-printed JSON string
+ * (`_generated/openapi.json`) — the portable artifact for external tooling.
+ */
 declare const emitOpenApi: (input: OpenApiEmitInput) => string;
 /**
-* Emit the OpenAPI document as an importable TS module
-* (`_generated/openapi.ts`) the worker entry imports and passes to
-* `createWorker({ openApiSpec })`. The document object literal is inlined
-* verbatim (same `JSON.stringify` form the `.json` uses), so the `.ts` and
-* `.json` are byte-identical content and regenerate together — closing the gap
-* where a Worker cannot read the JSON file at runtime. `document_` is the object
-* returned by {@link buildOpenApiDocument} (reused, never recomputed).
-*/
+ * Emit the OpenAPI document as an importable TS module
+ * (`_generated/openapi.ts`) the worker entry imports and passes to
+ * `createWorker({ openApiSpec })`. The document object literal is inlined
+ * verbatim (same `JSON.stringify` form the `.json` uses), so the `.ts` and
+ * `.json` are byte-identical content and regenerate together — closing the gap
+ * where a Worker cannot read the JSON file at runtime. `document_` is the object
+ * returned by {@link buildOpenApiDocument} (reused, never recomputed).
+ */
 declare const emitOpenApiModule: (document_: Record<string, unknown>) => string;
 /** The OpenRPC dialect version this emitter targets. */
 declare const OPENRPC_VERSION = "1.3.2";
@@ -1313,416 +3395,431 @@ interface OpenRpcEmitInput {
   version?: string;
 }
 /**
-* Emit an OpenRPC 1.x document describing Lunora's JSON-RPC surface.
-*
-* Only the RPC `query`/`mutation`/`action` functions become `methods` — one per
-* function, `name` = `file:fn`. `internal` (off the external RPC path) and
-* `stream` (not invocable over the RPC envelope) are excluded, the same filter
-* the OpenAPI emitter applies. Each method's single `args` param is typed from
-* the function's `v.*` validators (`argsObjectSchema`); `result` is the
-* `.output()` schema when declared, else a best-effort inferred schema. The
-* standard `LunoraError` codes ride along under each method's `errors`.
-*
-* `httpRouter()` typed REST routes are deliberately omitted — OpenRPC is
-* RPC-only and cannot represent REST paths; the OpenAPI document is the spec
-* that covers the REST surface. Methods are sorted by name for stable output.
-* Returns the document as a plain object (the single source of truth
-* `emitOpenRpc` stringifies and `emitOpenRpcModule` inlines, so the `.json` and
-* `.ts` artifacts can never drift).
-*/
+ * Emit an OpenRPC 1.x document describing Lunora's JSON-RPC surface.
+ *
+ * Only the RPC `query`/`mutation`/`action` functions become `methods` — one per
+ * function, `name` = `file:fn`. `internal` (off the external RPC path) and
+ * `stream` (not invocable over the RPC envelope) are excluded, the same filter
+ * the OpenAPI emitter applies. Each method's single `args` param is typed from
+ * the function's `v.*` validators (`argsObjectSchema`); `result` is the
+ * `.output()` schema when declared, else a best-effort inferred schema. The
+ * standard `LunoraError` codes ride along under each method's `errors`.
+ *
+ * `httpRouter()` typed REST routes are deliberately omitted — OpenRPC is
+ * RPC-only and cannot represent REST paths; the OpenAPI document is the spec
+ * that covers the REST surface. Methods are sorted by name for stable output.
+ * Returns the document as a plain object (the single source of truth
+ * `emitOpenRpc` stringifies and `emitOpenRpcModule` inlines, so the `.json` and
+ * `.ts` artifacts can never drift).
+ */
 declare const buildOpenRpcDocument: (input: OpenRpcEmitInput) => Record<string, unknown>;
 /**
-* Emit the OpenRPC 1.x document as a pretty-printed JSON string
-* (`_generated/openrpc.json`) — the portable artifact for external tooling.
-*/
+ * Emit the OpenRPC 1.x document as a pretty-printed JSON string
+ * (`_generated/openrpc.json`) — the portable artifact for external tooling.
+ */
 declare const emitOpenRpc: (input: OpenRpcEmitInput) => string;
 /**
-* Emit the OpenRPC document as an importable TS module
-* (`_generated/openrpc.ts`) the worker entry imports and passes to
-* `createWorker({ openRpcSpec })`. The document object literal is inlined
-* verbatim (same `JSON.stringify` form the `.json` uses), so the `.ts` and
-* `.json` are byte-identical content and regenerate together. `document_` is
-* the object returned by {@link buildOpenRpcDocument} (reused, never recomputed).
-*/
+ * Emit the OpenRPC document as an importable TS module
+ * (`_generated/openrpc.ts`) the worker entry imports and passes to
+ * `createWorker({ openRpcSpec })`. The document object literal is inlined
+ * verbatim (same `JSON.stringify` form the `.json` uses), so the `.ts` and
+ * `.json` are byte-identical content and regenerate together. `document_` is
+ * the object returned by {@link buildOpenRpcDocument} (reused, never recomputed).
+ */
 declare const emitOpenRpcModule: (document_: Record<string, unknown>) => string;
-/** Current snapshot format version. Bumped if the structural shape below changes. */
-declare const SCHEMA_SNAPSHOT_VERSION: 1;
-/** A single field's structural shape: its value kind and whether it is optional. */
-interface FieldSnapshot {
-  /** The validator kind (`string`, `number`, `id`, `object`, …) after unwrapping `v.optional`. */
-  kind: string;
-  /** True when declared `v.optional(...)` — accepts `undefined` / absent on insert. */
-  optional: boolean;
-}
-/** A single secondary index's structural shape. */
-interface IndexSnapshot {
-  fields: ReadonlyArray<string>;
-  unique: boolean;
-}
-/** A single relation's structural shape. */
-interface RelationSnapshot {
-  field: string;
-  kind: "many" | "one";
-  table: string;
-}
-/** Structural snapshot of one table. */
-interface TableSnapshot {
-  /** Field name → {@link FieldSnapshot}, in declared order. */
-  fields: Record<string, FieldSnapshot>;
-  /** Index name → {@link IndexSnapshot}. */
-  indexes: Record<string, IndexSnapshot>;
-  /** Relation accessor name → {@link RelationSnapshot}. */
-  relations: Record<string, RelationSnapshot>;
-  /**
-  * `"root"` (default single-DO), `"global"` (D1-replicated), or
-  * `"shardBy:&lt;field>"` (partitioned). Encoded as a string so the snapshot
-  * stays a plain JSON-stable value.
-  */
-  shardMode: string;
-}
-/** The committed baseline — a deterministic structural view of the whole schema. */
-interface SchemaSnapshot {
-  /**
-  * Cloudflare DO data-residency jurisdiction declared via `.jurisdiction("…")`,
-  * or absent. Tracked because changing it strands all existing Durable Object
-  * data (a DO name maps to a different ID per jurisdiction). Optional, so old
-  * baselines written before this field parse cleanly (absent ⇒ undefined).
-  *
-  * Typed as a plain `string` (not the authoring union) on purpose: this is
-  * STORED data that a newer Lunora may have written with a jurisdiction this
-  * version doesn't yet know. Preserving the raw value keeps the breaking
-  * `changedJurisdiction` diff correct under a downgrade — coercing an unknown
-  * value to `undefined` would fail OPEN and hide the most destructive change.
-  */
-  jurisdiction?: string;
-  /** Sorted list of every declared `defineMigration` id at capture time. */
-  migrationIds: ReadonlyArray<string>;
-  /** Table name → {@link TableSnapshot}, keys sorted for stable serialization. */
-  tables: Record<string, TableSnapshot>;
-  version: typeof SCHEMA_SNAPSHOT_VERSION;
-}
-/** One classified structural change between the baseline and the current schema. */
-interface DriftChange {
-  /** `"breaking"` changes need a data migration; `"safe"` changes are additive. */
-  severity: "breaking" | "safe";
-  /** Human-readable, actionable description (used in the gate message). */
-  summary: string;
-  /** A machine-readable change discriminator. */
-  type: "addedIndex" | "addedOptionalField" | "addedRelation" | "addedRequiredField" | "addedTable" | "changedJurisdiction" | "changedFieldKind" | "changedIndex" | "changedShardMode" | "fieldOptionalToRequired" | "fieldRequiredToOptional" | "removedField" | "removedIndex" | "removedRelation" | "removedTable";
-}
-/** The result of diffing two snapshots: every classified change. */
-interface SchemaDrift {
-  /** Every classified change, in a stable order (added/changed per table, then removals). */
-  changes: ReadonlyArray<DriftChange>;
-}
 /**
-* Build a {@link SchemaSnapshot} from a parsed {@link SchemaIR} and the set of
-* declared migration ids. Tables and migration ids are sorted so the emitted
-* JSON is byte-stable across runs (no spurious diffs / churn).
-*/
+ * Build a {@link SchemaSnapshot} from a parsed {@link SchemaIR} and the set of
+ * declared migration ids. Tables and migration ids are sorted so the emitted
+ * JSON is byte-stable across runs AND across machines (no spurious diffs /
+ * churn) — see `sortKeys` in `shared/schema-snapshot.ts` for why that ordering
+ * must not be locale-aware.
+ *
+ * Field / index / relation keys are sorted the same way, by `tableSnapshotOf` —
+ * see there for why declaration order was the wrong default for a hashed file.
+ */
 declare const buildSchemaSnapshot: (schema: SchemaIR, migrationIds: ReadonlyArray<string>) => SchemaSnapshot;
-/** Serialize a snapshot to the exact bytes written to `lunora/.lunora-schema.json` (trailing newline). */
-declare const serializeSchemaSnapshot: (snapshot: SchemaSnapshot) => string;
 /**
-* Thrown by {@link parseSchemaSnapshot} when the baseline file exists but is
-* malformed (bad JSON / wrong version / invalid table shape). Lets the CLI gate
-* treat a corrupt baseline as a hard error rather than silently degrading to a
-* "first capture" that would mask drift and then overwrite the bad file.
-*/
-declare class SchemaSnapshotParseError extends Error {
-  override readonly name = "SchemaSnapshotParseError";
-}
-/**
-* Parse a committed snapshot file. Returns `undefined` ONLY when the content is
-* absent/empty; throws {@link SchemaSnapshotParseError} when content is present
-* but malformed (bad JSON, wrong version, or structurally-invalid tables) so the
-* caller can distinguish "no baseline yet" (a legitimate first capture) from "a
-* corrupt baseline" (which must not be silently treated as a first capture).
-*/
-declare const parseSchemaSnapshot: (content: string | undefined) => SchemaSnapshot | undefined;
+ * Thrown by {@link parseSchemaSnapshot} when the baseline file exists but is
+ * malformed (bad JSON / wrong version / invalid table shape). Lets the CLI gate
+ * treat a corrupt baseline as a hard error rather than silently degrading to a
+ * "first capture" that would mask drift and then overwrite the bad file.
+ */
+declare class SchemaSnapshotParseError extends LunoraError {
+  constructor(message: string);
+}
 /**
-* Diff the current snapshot against a committed baseline and classify every
-* structural change. Pure — no I/O. When `baseline` is `undefined` (no committed
-* snapshot yet) there is no drift to report: every table is treated as a fresh
-* additive `addedTable`, so a first deploy is never blocked.
-*/
-declare const diffSchemaSnapshots: (baseline: SchemaSnapshot | undefined, current: SchemaSnapshot) => SchemaDrift;
+ * Parse a committed snapshot file. Returns `undefined` ONLY when the content is
+ * absent/empty; throws {@link SchemaSnapshotParseError} when content is present
+ * but malformed (bad JSON, wrong version, or structurally-invalid tables) so the
+ * caller can distinguish "no baseline yet" (a legitimate first capture) from "a
+ * corrupt baseline" (which must not be silently treated as a first capture).
+ *
+ * The parsing itself lives in `shared/schema-snapshot.ts` (the Studio reads the
+ * same JSON out of the DO ledger); this wrapper only applies the CLI's policy of
+ * treating a malformed baseline as fatal.
+ */
+declare const parseSchemaSnapshot: (content: string | undefined) => SchemaSnapshot | undefined;
 /** The decision the pre-deploy gate returns. */
 interface SchemaDriftDecision {
-  /** True when the deploy must be blocked (breaking drift with no new migration, and no override). */
+  /** True when the deploy must be blocked (breaking drift no new migration covers, and no override). */
   blocked: boolean;
   /** Every classified change (both severities), for reporting. */
   changes: ReadonlyArray<DriftChange>;
-  /** Migration ids declared now but absent from the baseline — proof a migration was added. */
+  /**
+   * Migration ids declared now but absent from the baseline. Reported for
+   * context; the gate acts on which of them cover an affected TABLE, not on how
+   * many there are.
+   */
   newMigrationIds: ReadonlyArray<string>;
   /**
-  * A multi-line, actionable explanation. Always present; empty string when
-  * there is no drift at all. Mirrors the D1-placeholder guard's message style.
-  */
+   * A multi-line, actionable explanation. Always present; empty string when
+   * there is no drift at all. Mirrors the D1-placeholder guard's message style.
+   */
   reason: string;
 }
 /**
-* Decide whether breaking schema drift should block a deploy.
-*
-* Blocks only when the baseline exists (a first-ever capture is never blocking),
-* there is at least one `breaking` change, no NEW migration id was added since
-* the baseline, and the `allowDrift` override is not set. Safe-only drift (or
-* breaking drift accompanied by a new migration id) passes.
-*/
+ * Decide whether breaking schema drift should block a deploy.
+ *
+ * Blocks only when the baseline exists (a first-ever capture is never blocking),
+ * there is at least one `breaking` change, no new migration COVERS it, and the
+ * `allowDrift` override is not set. Safe-only drift passes.
+ *
+ * "Covers" is per-table, not per-run: a new migration excuses breaking drift on
+ * the table it iterates, and nothing else. Counting new ids alone let a backfill
+ * on `messages` unblock a required field added to `users` — the gate reported
+ * "accompanied by a migration" for a change that migration would never visit.
+ * The shard-mode diff cites this block to justify the studio not shipping a
+ * stranded-rows detector (see `shared/schema-snapshot.ts`), and that claim only
+ * holds if an unrelated migration cannot wave it through.
+ *
+ * Only a `"backfill"` change is coverable at all. A `"rehome"` change moves rows
+ * to another Durable Object or region and a `"code"` change breaks a call site;
+ * rewriting rows fixes neither, so a migration must not excuse them however well
+ * its table matches. Those are cleared by fixing the code or accepting the new
+ * shape (`--allow-schema-drift` / `--update-schema-baseline`).
+ */
 declare const evaluateSchemaDrift: (options: {
   allowDrift?: boolean;
   baseline: SchemaSnapshot | undefined;
+  /** The command printing the remediation, so it names only flags that command accepts. */
+  command?: string;
   current: SchemaSnapshot;
+  /** This run's declared migrations, so a new one is matched to the table it iterates. */
+  migrations: ReadonlyArray<Pick<MigrationIR, "id" | "table">>;
 }) => SchemaDriftDecision;
 /**
-* Committed, tracked baseline file holding the blessed structural schema
-* snapshot the pre-deploy drift gate diffs against. Lives in `lunora/` (NOT the
-* gitignored `_generated/`) so it is committed alongside `schema.ts`. Leading
-* dot keeps it tucked away next to the schema it describes.
-*/
-declare const SCHEMA_SNAPSHOT_FILENAME = ".lunora-schema.json";
+ * Convert a {@link SchemaIR} into a synthetic runtime {@link Schema} carrying just
+ * the `tables[name].shape` surface `@lunora/seed` introspects. System columns
+ * (`_id`, `_creationTime`) are absent from the IR shape, exactly as the seed
+ * engine expects (it assigns `_id` itself).
+ */
+declare const schemaFromIr: (ir: SchemaIR) => Schema;
 /**
-* Construct the ts-morph `Project` codegen discovers over. Prefers the user's
-* `tsconfig.json` (when one is found walking up from `lunoraDirectory`) so
-* cross-file type resolution and path aliases work; falls back to an isolated
-* project otherwise. This is the exact construction {@link runCodegen} uses
-* when no `project` is injected — exported so a long-lived caller (the Vite
-* dev-loop) can build one once and reuse it across runs via
-* {@link refreshCodegenProject} instead of re-parsing the user's whole TS
-* program on every save.
-*/
-declare const createCodegenProject: (lunoraDirectory: string) => Project;
+ * Convert a codegen {@link ValidatorIR} into a JSON Schema node. A thin wrapper
+ * over the shared {@link jsonSchemaFromNode} core (from `@lunora/values`) with the
+ * IR-backed {@link irReader}, so the kind→schema mapping is the *same* algorithm
+ * `@lunora/values`' `toJsonSchema` runs — codegen never instantiates the runtime
+ * `v.*` objects, it only holds the reflected IR. Shared by the OpenAPI and
+ * OpenRPC emitters so both surfaces speak one JSON Schema dialect.
+ */
+declare const validatorIrToJsonSchema: (validator: ValidatorIR) => JsonSchema;
 /**
-* Synchronise a reused {@link createCodegenProject} Project with the current
-* on-disk state of `lunoraDirectory`, so the next {@link runCodegen} sees the
-* same files a freshly-constructed Project would — without re-parsing the whole
-* TS program. Adds any on-disk source file the Project doesn't yet have, and
-* `refreshFromFileSystemSync()`es the ones it does (picking up edits); then
-* removes Project source files under `lunoraDirectory` that no longer exist on
-* disk (the classic stale-deleted-file cache bug).
-*
-* Files outside `lunoraDirectory` (e.g. those pulled in by the user's tsconfig)
-* are left untouched — they back type resolution and rarely change in the
-* dev-loop; a tsconfig change invalidates the whole cached Project upstream.
-*/
-declare const refreshCodegenProject: (project: Project, lunoraDirectory: string) => void;
+ * The machine-readable `LunoraError` codes Lunora emits on the RPC + REST
+ * surfaces, enumerated from `@lunora/server`'s `CODE_STATUS` map plus the
+ * runtime/DO dispatch codes (`FUNCTION_NOT_FOUND`, `PAYLOAD_TOO_LARGE`,
+ * `METHOD_NOT_ALLOWED`, the `*_NOT_CONFIGURED` admin gates, …). The list documents
+ * the contract; clients switch on `error.code`. Kept sorted for stable output.
+ */
+declare const LUNORA_ERROR_CODES: ReadonlyArray<string>;
 /**
-* Top-level codegen entry. Parses `&lt;projectRoot>/lunora/schema.ts` and every
-* function file under `&lt;projectRoot>/lunora/`, then writes
-* `_generated/{api,server,dataModel}.ts` next to them.
-*
-* When `LUNORA_CODEGEN_TIMING` is set (truthy), a single diagnostic summary
-* line is written to stderr with the total wall time and the discovery-vs-emit
-* split — opt-in instrumentation that is otherwise zero-cost and side-effect-free
-* on the returned {@link CodegenResult}.
-*/
-declare const runCodegen: (options: CodegenOptions) => CodegenResult;
-interface CodegenOptions {
-  /**
-  * Which machine-readable API spec(s) to emit into `_generated/`.
-  *
-  * `"openapi"` (the default) writes only `openapi.json` (OpenAPI 3.1; covers
-  * both the RPC functions and `httpRouter()` REST routes). `"openrpc"` writes
-  * only `openrpc.json` (OpenRPC 1.x; the RPC functions only — OpenRPC cannot
-  * represent REST routes). `"both"` writes both files; `"none"` writes neither.
-  *
-  * Regardless of the choice, `CodegenResult.generated.openApi` and `.openRpc`
-  * always carry the rendered string (computation is cheap and pure); only the
-  * on-disk write is gated by this option.
-  */
-  apiSpec?: "both" | "none" | "openapi" | "openrpc";
-  /**
-  * When true, run discovery + emit (so any schema/function parse error
-  * surfaces) but skip writing files to `_generated/`. The returned
-  * `outputDirectory` is still the path that *would* have been written.
-  */
-  dryRun?: boolean;
+ * Language-agnostic half of SDK generation: turn an OpenRPC document
+ * (`_generated/openrpc.json`, see {@link file://../openrpc.ts}) into the parsed
+ * shape every per-language target renders from.
+ *
+ * Nothing here knows about a target language. A target supplies its own member
+ * naming and templates (see {@link file://./targets}); everything that would
+ * otherwise be re-derived per language — how a `functionPath` splits, which
+ * runtime verb a kind maps to, whether a schema is real or the untyped
+ * placeholder, how namespaces group and sort — lives here exactly once.
+ *
+ * That single-source rule is not stylistic. `paths.ts` documents the same
+ * discipline for namespaces ("if these ever disagree, runtime dispatch silently
+ * misses functions"), and the failure mode here is the same in a new costume: a
+ * target that re-derives a model name renders an import pointing at a class
+ * quicktype never emitted.
+ *
+ * Deriving names in one place is necessary but NOT sufficient, because only
+ * half the decision is ours: quicktype chooses whether a predicted name becomes
+ * a declared type, and different backends answer differently for the same
+ * schema. {@link withDeclaredModels} reconciles the two halves before a target
+ * renders anything.
+ */
+/** One OpenRPC method as {@link file://../openrpc.ts} emits it. */
+interface OpenRpcMethod {
+  name: string;
+  params?: ReadonlyArray<{
+    name: string;
+    schema?: Record<string, unknown>;
+  }>;
+  result?: {
+    name: string;
+    schema?: Record<string, unknown>;
+  };
+  summary?: string;
+  "x-lunora-function-kind"?: string;
+}
+/** The `_generated/openrpc.json` document. */
+interface OpenRpcDocument {
+  info?: {
+    title?: string;
+    version?: string;
+  };
+  methods: ReadonlyArray<OpenRpcMethod>;
+}
+/** The runtime verbs a generated SDK can call. Mirrors the client transports. */
+type RuntimeVerb = "action" | "mutation" | "query";
+/** One RPC function, parsed and language-neutral. */
+interface SdkMethod {
   /**
-  * Run the static schema advisor (unindexed FKs, …) during codegen.
-  * Defaults to `true`. When `false`, `CodegenResult.advisories` is empty.
-  * Computed regardless of `dryRun`; codegen never prints them — see
-  * {@link CodegenResult.advisories}.
-  */
-  lint?: boolean;
-  /** Override the lunora subdirectory name. Defaults to `"lunora"`. */
-  lunoraDirectory?: string;
+   * Where this function's ARGUMENT nulls mean "unset" and where they mean
+   * "null" — see {@link ModelNullPaths}.
+   *
+   * On the method rather than on a shared render input because it is a
+   * per-method fact and the parser already holds the schema it comes from. Read
+   * by the three targets whose rendered models cannot tell the two apart
+   * (ruby, rust, swift); the other five have a marker of their own and ignore
+   * it.
+   */
+  argsNullPaths: ModelNullPaths;
   /**
-  * Reuse a previously-constructed ts-morph {@link Project} instead of building
-  * a fresh one each run. The caller owns refreshing its source files from disk
-  * (see {@link refreshCodegenProject}) — codegen does not re-read changed files
-  * off an injected Project. Built via {@link createCodegenProject} when absent.
-  * Used by the Vite dev-loop to avoid re-parsing the whole TS program on every
-  * save; omit it (CLI one-shot path) to get the default fresh-Project behaviour.
-  */
-  project?: Project;
-  /** Project root containing the `lunora/` directory. */
-  projectRoot: string;
+   * Generated args model name, or `undefined` when NO model could be named for
+   * this function's arguments.
+   *
+   * `undefined` does NOT mean "takes no arguments" — see {@link SdkMethod.takesArgs}.
+   * A schema carrying a `v.bigint()` or `v.bytes()` gets no model deliberately
+   * (`hasUnrepresentableWireType`), and a backend that cannot name a shape leaves
+   * it undeclared. Both still take arguments, just untyped ones.
+   */
+  argsType: string | undefined;
+  /** Raw exported function name (`"list"`), before any naming convention. */
+  functionName: string;
+  /** The wire identifier (`"messages:list"`), emitted verbatim into calls. */
+  functionPath: string;
+  /** Raw file namespace (`"messages"`), before any naming convention. */
+  namespace: string;
+  /** Generated result model name, or `undefined` while the result is untyped. */
+  resultType: string | undefined;
+  /** Human summary for the doc comment. */
+  summary: string;
   /**
-  * Re-bless the committed schema-drift baseline (`lunora/.lunora-schema.json`)
-  * with the current structural snapshot. The baseline is ALWAYS written on
-  * first capture (when the file is absent); set this to overwrite an existing
-  * one — e.g. after the developer has added the data migration that justifies
-  * a breaking change. Ignored when `dryRun` is true.
-  */
-  updateSchemaBaseline?: boolean;
+   * Whether this function declares arguments at all, independent of whether a
+   * model could be named for them.
+   *
+   * A target emits three shapes from this: a TYPED parameter when `argsType` is
+   * set, an UNTYPED wire-shaped parameter when it is not but this is true, and no
+   * parameter at all when this is false. Collapsing the middle case into the last
+   * is what made `v.bigint()` functions uncallable with arguments.
+   */
+  takesArgs: boolean;
+  /** Which runtime verb this dispatches to. */
+  verb: RuntimeVerb;
 }
-interface CodegenResult {
-  /**
-  * Static schema advisor findings (e.g. unindexed foreign keys) produced
-  * this run. Empty when `lint` is `false` or the schema is clean. Codegen
-  * does not print these itself — each caller presents them through its own
-  * channel (the CLI logger, the vite overlay, the studio Advisors table).
-  * `formatAdvisories` is exported for a plain multi-line rendering.
-  */
-  advisories: ReadonlyArray<Finding>;
+/** One namespace's functions, sorted. */
+interface SdkNamespace {
+  methods: ReadonlyArray<SdkMethod>;
+  /** Raw namespace (`"messages"`); a target applies its own casing. */
+  name: string;
+}
+/**
+ * True when a schema actually describes a shape.
+ *
+ * `openrpc.ts` emits a description-only placeholder for any function without a
+ * declared `.output()` (the return type is TS-inferred and absent from the IR).
+ * A placeholder must never become a generated model: quicktype would render an
+ * empty type, and the surface would decode every response into it — silently
+ * discarding the real payload rather than leaving it untyped.
+ */
+declare const isTypedSchema: (schema: Record<string, unknown> | undefined) => boolean;
+/**
+ * A path from a model's root to one property. `*` stands for every element of an
+ * array or every value of a record, neither of which has named positions.
+ */
+type SchemaPath = ReadonlyArray<string>;
+/**
+ * Where a model's nulls mean different things — the one fact a generated model
+ * flattens away, and the reason three ports could not send a `v.nullable()`
+ * argument at all.
+ *
+ * An unset `v.optional()` and a `v.nullable()` set to null are the SAME value in
+ * every generated model (a nil field), and opposite things on the wire: the
+ * validator rejects an explicit null for the first and requires the key present
+ * for the second. Neither Ruby, Rust nor Swift renders a marker telling them
+ * apart, so the distinction is computed here, from the schema, where `required`
+ * still exists — and handed to the targets that need it.
+ *
+ * Two lists rather than one because the ports need opposite operations. Ruby and
+ * Rust project a whole value tree and prune nulls, so they prune at
+ * {@link ModelNullPaths.optional} and nowhere else — which also stops them
+ * dropping a legitimate null inside a record or an array, as a blanket prune
+ * does. Swift's `JSONEncoder` has already dropped every struct-property nil
+ * before the transport sees a tree, so it restores nulls at
+ * {@link ModelNullPaths.nullable} instead: an absent key at a required path can
+ * only have been a nil, so putting the null back is exact.
+ *
+ * A `$ref` is NOT resolved. `openrpc.ts` inlines everything it emits, so this
+ * never comes up for a generated document — but `--spec` accepts a hand-written
+ * one, and there a `$ref`'d sub-object contributes no paths at all: the ports
+ * that prune would send its unset optionals as null, and Swift would not restore
+ * its nullables. Inline the schema, or teach this to follow the pointer.
+ *
+ * Both lists name PROPERTIES only. A record's values and an array's elements can
+ * be null too, but no port drops one: the pruning ports prune at `optional`
+ * paths, which a `*` position can never be, and `JSONEncoder` drops a nil only
+ * from a struct property — a nil inside a dictionary or array encodes as null.
+ * Listing a `*` leaf would also make Swift's restore INVENT record keys that
+ * were never there, which is why the walk records the path it descends through
+ * but never the `*` position itself.
+ */
+interface ModelNullPaths {
+  /** Required properties that permit null — a null there is a VALUE and must survive. */
+  nullable: ReadonlyArray<SchemaPath>;
+  /** Properties absent from their object's `required` — a null there means UNSET. */
+  optional: ReadonlyArray<SchemaPath>;
+}
+/** What a target renders from. */
+interface SdkRenderInput {
   /**
-  * Containers discovered from `defineContainer` exports in
-  * `lunora/containers.ts` — the list the config layer reconciles into
-  * wrangler's `containers[]`, `CONTAINER_*` Durable Object bindings, and
-  * migration classes. Empty when the project declares no containers.
-  */
-  containers: ReadonlyArray<ContainerIR>;
+   * The rendered model source, to be written as the target's model file.
+   *
+   * Empty for a target that emits its own model FILES via
+   * {@link SdkTarget.renderModels} — those are already written, and this string
+   * exists only so the declared-model reconciliation reads one shape.
+   */
+  models: string;
+  /** Namespaces and their functions, already sorted. */
+  namespaces: ReadonlyArray<SdkNamespace>;
+}
+/**
+ * One directory or file of the hand-written transport, and where it lands in the
+ * output.
+ *
+ * `from` is relative to `sdks/<target id>/` and `to` is relative to `--out`. The
+ * two differ because a repo layout and a consumable layout are not the same
+ * shape: the Ruby transport lives under `lib/` so `ruby -Ilib` works in the
+ * repo, while a vendored copy has no `lib` to point at, and the Rust transport
+ * is the repo's root crate but a nested one in the output.
+ *
+ * Only the runtime is listed. A transport's own conformance suite and its
+ * `generated_check/` sample are deliberately absent — they assert against
+ * `protocol/fixtures/`, which is not copied, so vendoring them would ship a user
+ * a test suite that cannot run.
+ */
+interface SdkVendorEntry {
+  /** Path under `sdks/<id>/`. A directory is copied recursively. */
+  from: string;
+  /** Destination path under `--out`. */
+  to: string;
+}
+/** A language target. One per `--lang` value. */
+interface SdkTarget {
+  /** The `--lang` value (`"python"`, `"go"`, …). */
+  id: string;
   /**
-  * Deduplicated cron schedules discovered from `cronJobs()` definitions —
-  * the array the vite plugin reconciles into `wrangler.jsonc`'s
-  * `triggers.crons`. Empty when the project declares no crons.
-  */
-  cronTriggers: ReadonlyArray<string>;
-  generated: {
-    api: string; /** Fluent worker-composition builder (`_generated/app.ts`) — `defineApp()`. Always written. */
-    app: string;
-    /** Container DO classes (`_generated/containers.ts`); `""` (and not written) when no containers are declared. */
-    containers: string;
-    crons: string;
-    dataModel: string;
-    drizzleGlobal: string;
-    drizzleShard: string;
-    functions: string; /** OpenAPI 3.1.0 document (`_generated/openapi.json`), pretty-printed JSON. */
-    openApi: string;
-    /**
-    * OpenAPI document as an importable TS module (`_generated/openapi.ts`) —
-    * `export const openApiSpec`, the worker imports it for
-    * `createWorker({ openApiSpec })`. Same document as `openApi`. Written
-    * alongside `openapi.json` whenever `apiSpec` includes `openapi`.
-    */
-    openApiModule: string;
-    /** OpenRPC 1.x document (`_generated/openrpc.json`), pretty-printed JSON. Always computed; written only when `apiSpec` includes `openrpc`. */
-    openRpc: string;
-    /**
-    * OpenRPC document as an importable TS module (`_generated/openrpc.ts`) —
-    * `export const openRpcSpec`, for `createWorker({ openRpcSpec })`. Same
-    * document as `openRpc`. Written alongside `openrpc.json` whenever
-    * `apiSpec` includes `openrpc`.
-    */
-    openRpcModule: string;
-    /** Push-consumer queue registry (`_generated/queues.ts`); `""` (and not written) when no push queues are declared. */
-    queues: string;
-    /** Project-bound seed client (`_generated/seed.ts`); `""` (and not written) when `@lunora/seed` is not a declared dependency. */
-    seed: string;
-    server: string;
-    shard: string; /** Static vector-index registry (`_generated/vectors.ts`) — `LUNORA_VECTOR_INDEXES`. Empty array body when the schema declares none. */
-    vectors: string;
-    /** WorkflowEntrypoint classes (`_generated/workflows.ts`); `""` (and not written) when no workflows are declared. */
-    workflows: string;
+   * The quicktype backend + renderer options that produce this target's
+   * models, or absent when the target emits its own (see
+   * {@link SdkTarget.renderModels}) or none at all.
+   *
+   * `LanguageName` is quicktype's own union, so a target naming a backend
+   * quicktype does not ship fails to compile rather than at run time.
+   */
+  quicktype?: {
+    lang: LanguageName;
+    rendererOptions?: Record<string, string>;
   };
-  outputDirectory: string;
   /**
-  * Queues discovered from `defineQueue` exports in `lunora/queues.ts` — the
-  * list the config layer reconciles into wrangler's `queues.producers[]` /
-  * `queues.consumers[]`. Queues are NOT Durable Objects, so this adds no
-  * binding or migration. Empty when the project declares no queues.
-  */
-  queues: ReadonlyArray<QueueIR>;
+   * Render the SDK. Returns file contents keyed by path relative to the
+   * output directory (nested paths are created as needed).
+   *
+   * This includes the BUILD MANIFEST the layout needs — `go.mod`, `Cargo.toml`,
+   * `Package.swift`, a crate root — because those name the vendored transport
+   * and are therefore part of "how this language resolves the copy", not
+   * something a consumer should have to write. Languages that resolve by
+   * directory (Python, Ruby, Java, Kotlin) emit no manifest.
+   */
+  render: (input: SdkRenderInput) => Record<string, string>;
   /**
-  * The CURRENT structural schema snapshot computed this run (tables + field
-  * kinds/optionality + indexes/relations/shard mode + declared migration ids).
-  * The pre-deploy drift gate diffs this against the committed baseline read
-  * from {@link CodegenResult.schemaSnapshotPath}. Always present, even on a
-  * `dryRun`.
-  */
-  schemaSnapshot: SchemaSnapshot;
-  /** Absolute path of the committed baseline file (`lunora/.lunora-schema.json`). */
-  schemaSnapshotPath: string;
+   * Emit this target's models from the schema directly, INSTEAD of quicktype,
+   * as file contents keyed by path relative to the output directory.
+   *
+   * Present only for the two JVM targets, and the exception is earned rather
+   * than a preference: quicktype's Java and Kotlin backends rename properties
+   * and, under `just-types`, emit no mapping metadata, so a model they render
+   * cannot be projected back onto the wire — and the only complete mapping
+   * they offer requires a Jackson / Klaxon / kotlinx dependency, which is the
+   * one thing these JDK-only transports are defined not to have.
+   * `targets/java.ts` records every option that was measured.
+   *
+   * A MAP rather than the single string quicktype returns, because Java takes
+   * one file per class: its single-file render is not compilable Java at all.
+   * The values are still joined for {@link SdkRenderInput.models}, so the
+   * declared-model reconciliation is the same code for every target.
+   */
+  renderModels?: (document: OpenRpcDocument) => Record<string, string>;
   /**
-  * Workflows discovered from `defineWorkflow` exports in
-  * `lunora/workflows.ts` — the list the config layer reconciles into
-  * wrangler's `workflows[]` array. Workflows are NOT Durable Objects, so this
-  * adds no binding or migration. Empty when the project declares no workflows.
-  */
-  workflows: ReadonlyArray<WorkflowIR>;
-}
-/**
-* Convert a {@link SchemaIR} into a synthetic runtime {@link Schema} carrying just
-* the `tables[name].shape` surface `@lunora/seed` introspects. System columns
-* (`_id`, `_creationTime`) are absent from the IR shape, exactly as the seed
-* engine expects (it assigns `_id` itself).
-*/
-declare const schemaFromIr: (ir: SchemaIR) => Schema;
-/**
-* Convert a codegen {@link ValidatorIR} into a JSON Schema node. A thin wrapper
-* over the shared {@link jsonSchemaFromNode} core (from `@lunora/values`) with the
-* IR-backed {@link irReader}, so the kind→schema mapping is the *same* algorithm
-* `@lunora/values`' `toJsonSchema` runs — codegen never instantiates the runtime
-* `v.*` objects, it only holds the reflected IR. Shared by the OpenAPI and
-* OpenRPC emitters so both surfaces speak one JSON Schema dialect.
-*/
-declare const validatorIrToJsonSchema: (validator: ValidatorIR) => JsonSchema;
-/** Build `{ type: "object", properties, required }` from an IR shape (mirrors `@lunora/values`' object mapping). */
-
-/**
-* The machine-readable `LunoraError` codes Lunora emits on the RPC + REST
-* surfaces, enumerated from `@lunora/server`'s `CODE_STATUS` map plus the
-* runtime/DO dispatch codes (`FUNCTION_NOT_FOUND`, `PAYLOAD_TOO_LARGE`,
-* `METHOD_NOT_ALLOWED`, the `*_NOT_CONFIGURED` admin gates, …). The list documents
-* the contract; clients switch on `error.code`. Kept sorted for stable output.
-*/
-declare const LUNORA_ERROR_CODES: ReadonlyArray<string>;
-/**
-* Lunora-specific error→solution hints. A small rule table mapping the exact
-* messages Lunora throws — codegen/schema diagnostics, worker-entry export gaps,
-* and the runtime data-layer conflicts — to an actionable fix.
-*
-* This table is the single source of truth shared by every consumer that wants
-* to turn a raw Lunora error into a fix hint: the Vite error overlay
-* (`@lunora/vite`) renders the Markdown in the browser, and the standalone
-* `lunora dev` CLI prints it to the terminal. It lives in `@lunora/codegen`
-* because codegen owns most of the throw sites, so the hints stay next to the
-* code that produces the messages.
-*
-* Matching is on the **message text**. By the time a diagnostic reaches a
-* consumer it has often been flattened to a plain `{ message }` (the overlay
-* pushes codegen errors through `server.hot.send` with `name === "Error"`), so
-* the class identity is gone and the message is the only stable signal.
-*
-* Bodies are Markdown — the overlay renders them; the CLI prints them (lightly
-* de-marked) as-is.
-*/
-/** A resolved hint for a recognized Lunora error. */
-interface LunoraSolution {
-  /** Markdown body shown under the header. */
-  body: string;
-  /** Short header for the solution. */
-  header: string;
-  /** Stable id (used in DEBUG logs and tests). */
-  id: string;
+   * THIRD-PARTY packages a consuming project must still install, reported by
+   * the CLI. Empty for six of the eight — the transport is vendored and those
+   * six reach the wire with only their standard library.
+   *
+   * A list, and not derivable from the transport, because a target's MODELS can
+   * carry a dependency the transport does not: quicktype's Ruby backend emits
+   * `Dry::Struct` types with no renderer option to avoid them, so a Ruby SDK
+   * needs the gems even though `sdks/ruby` itself is dependency-free.
+   */
+  requires: ReadonlyArray<string>;
+  /**
+   * Which parts of `sdks/<id>/` are the transport, and where they land under
+   * `--out`. See {@link SdkVendorEntry}.
+   */
+  vendor: ReadonlyArray<SdkVendorEntry>;
 }
-/** A single error→solution rule: a {@link LunoraSolution} plus its matcher. */
-interface LunoraSolutionRule extends LunoraSolution {
-  /** True when this rule recognizes the error message. */
-  test: (message: string) => boolean;
+/** Every language `lunora sdk generate --lang` accepts, keyed by id. */
+declare const SDK_TARGETS: Readonly<Record<string, SdkTarget>>;
+/** The accepted `--lang` values, sorted — for help text and error messages. */
+declare const SDK_LANGUAGES: ReadonlyArray<string>;
+/** The files a generation run writes, keyed by path relative to the output directory. */
+type SdkFiles = Record<string, string>;
+/** What a generation run produced, plus what it had to weaken and why. */
+interface SdkResult {
+  files: SdkFiles;
+  /**
+   * Model names predicted from the schema that the chosen backend did not
+   * declare, so their call sites fell back to an untyped return. Surfaced
+   * rather than swallowed — silently weaker types are how an SDK looks
+   * finished while returning `Any` everywhere.
+   */
+  undeclared: ReadonlyArray<string>;
+  /**
+   * Functions whose args or result carry a `v.bigint()` or `v.bytes()`. No
+   * typed model can represent those — the wire needs a tagged value that no
+   * generated field produces — so their parameters stay untyped and the
+   * caller passes wire values directly.
+   */
+  unrepresentable: ReadonlyArray<string>;
 }
 /**
-* The rules, ordered most- to least-specific: the dev-time codegen/schema rules
-* come first because they're the errors a developer hits while editing
-* `lunora/`, then the runtime data-layer conflicts that surface from the worker.
-* The first matching rule (in array order) wins.
-*/
-declare const LUNORA_SOLUTION_RULES: ReadonlyArray<LunoraSolutionRule>;
-/**
-* Find the first Lunora solution whose rule matches `message`, or `undefined`
-* if none recognize it. Consumers turn the returned Markdown into their own
-* presentation (overlay panel, terminal hint, …).
-*/
-declare const findLunoraSolution: (message: string) => LunoraSolution | undefined;
+ * Generate the SDK for `document` in `target`'s language.
+ *
+ * Async only because the model layer is: quicktype's renderer is promise-based.
+ * The surface itself is pure, so a target's `render` stays synchronous and
+ * unit-testable without touching quicktype.
+ *
+ * Models are rendered BEFORE the surface because the surface's model references
+ * depend on what the backend actually declared — see {@link withDeclaredModels}.
+ */
+declare const generateSdk: (document: OpenRpcDocument, target: SdkTarget) => Promise<SdkResult>;
+/** The matching secret rule's `kind` for a string value, or `undefined` when none matches. */
+declare const secretKindOf: (value: string) => string | undefined;
+/** A redacted preview of a secret value — first 4 chars plus its length, never the full value. */
+declare const redact: (value: string) => string;
 declare const VERSION = "0.0.0";
-export { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, LUNORA_SOLUTION_RULES, type LunoraSolution, type LunoraSolutionRule, type MaskProcedureIR, type MigrationIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverNondeterministicCalls, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, findLunoraSolution, formatAdvisories, lintSchema, parseSchemaSnapshot, refreshCodegenProject, runCodegen, schemaFromIr, serializeSchemaSnapshot, validatorIrToJsonSchema };
+export { AGENTS_FILENAME, type AgentIR, type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type ContextPropertyCallIR, type CronJobIR, DEFAULT_TARGET, type DriftChange, type DriftRemediation, type DriftScope, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type LintSchemaOptions, MUTATORS_FILENAME, type MaskProcedureIR, type MigrationIR, type MutatorIR, NOTIFY_FILENAME, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcDocument, type OpenRpcEmitInput, type OpenRpcMethod, type PlatformDiagnostic, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, type RuntimeVerb, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, SDK_LANGUAGES, SDK_TARGETS, SHAPES_FILENAME, type SandboxUsage, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type SdkFiles, type SdkMethod, type SdkNamespace, type SdkRenderInput, type SdkResult, type SdkTarget, type ShapeIR, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, type WranglerVariableIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, describeErrorLevelFindings, diagnosticAt, diffSchemaSnapshots, discoverAgents, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverHyperdriveCalls, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverMutators, discoverNondeterministicCalls, discoverNotifyCalls, discoverNotifyConfig, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSandboxUsage, discoverSchema, discoverShapes, discoverStorageRulesMetadata, discoverWorkflows, emitAgents, emitApi, emitApp, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, errorAdvisoryNames, errorPlatformDiagnosticNames, evaluateSchemaDrift, findTsconfig, formatAdvisories, generateSdk, isTypedSchema, lintSchema, parseSchemaSnapshot, platformMatrixIds, readPackageDependencies, readProjectTarget, redact, refreshCodegenProject, resolveCodegenTarget, runCodegen, schemaFromIr, secretKindOf, serializeSchemaSnapshot, toAdvisorContext, validatorIrToJsonSchema };