@lunora/codegen 1.0.0-alpha.8 → 1.0.0-alpha.80

package/dist/index.d.mts

@@ -1,14 +1,137 @@
-import { Finding } from '@lunora/advisor';
+import { AdvisorExportSink, AdvisorGeoIndexUsage, AdvisorNotifyCall, AdvisorNotifyConfig, Finding, LintContext, AdvisorProcedureProtection } from '@lunora/advisor';
 export type { Finding } from '@lunora/advisor';
+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 { Node, Project } from 'ts-morph';
-import { StudioFeaturesResult } from '@lunora/do';
+import { StudioFeaturesResult } from '@lunora/shard-engine';
+import '@lunora/platform';
 import { Schema } from '@lunora/server';
 import { JsonSchema } from '@lunora/values';
 /**
-* 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.
-*/
+ * The structural schema-snapshot format and its diff, shared by `@lunora/codegen`
+ * (which builds snapshots from the parsed schema IR and gates deploys on the
+ * diff) and `@lunora/studio` (which renders the same diff as a visual migration
+ * history).
+ *
+ * Having ONE diff is the point: the Studio's schema-history view and the
+ * pre-deploy drift gate must classify a change identically, or the UI will say a
+ * change is safe while `lunora deploy` refuses it. `@lunora/codegen` is a
+ * build-time package the browser bundle cannot import, and neither package sits
+ * below the other, so — like `shared/quote-identifier.ts` — this lives outside
+ * both and is bundler-inlined into each. Keep it genuinely zero-dependency
+ * (relative/built-in imports only) or inlining breaks. Consumers must drop
+ * `outDir`/`rootDir` from their `tsconfig.json` (a set `rootDir` raises TS6059
+ * for this out-of-package file under `tsc --noEmit`).
+ *
+ * What stays in `@lunora/codegen`: building a snapshot from `SchemaIR`, the
+ * `SchemaSnapshotParseError` class (it extends `LunoraError`), and the deploy
+ * gate's policy (`evaluateSchemaDrift`). What lives here: the format, the diff,
+ * the severity classification, and the content hash.
+ */
+/** 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:<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";
+/** One classified structural change between two snapshots. */
+interface DriftChange {
+  /**
+   * `"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 a data migration; `"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: "addedIndex" | "addedOptionalField" | "addedRelation" | "addedRequiredField" | "addedTable" | "changedFieldKind" | "changedIndex" | "changedJurisdiction" | "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>;
+}
+/** 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.
+ */
 interface ColumnMetaIR {
   /** `.default(...)` or `.$defaultFn(...)` present — field is optional on insert. */
   hasDefault?: boolean;
@@ -25,6 +148,15 @@ interface ValidatorIR {
   bucket?: string;
   /** 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.
+   */
+  hasRefinement?: boolean;
   /** For `v.optional(inner)` / `v.array(inner)`. */
   inner?: ValidatorIR;
   /** For `v.record(key, value)`. */
@@ -41,6 +173,14 @@ interface ValidatorIR {
   sourceText?: string;
   /** 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;
   valueType?: ValidatorIR;
 }
 interface IndexIR {
@@ -49,11 +189,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;
@@ -67,19 +228,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. */
@@ -100,21 +261,79 @@ 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`.
-  */
+   * 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;
   name: string;
   /** Rank indexes declared inline via `.rankIndex(name, …)`. */
   rankIndexes: ReadonlyArray<RankIndexIR>;
@@ -126,48 +345,107 @@ interface TableIR {
     field: string;
     kind: "shardBy";
   };
+  /** Set when the chain carried `.softDelete()` — the marker column's name (default `deletedAt`). The column is injected into `shape` so `Doc_*` carries it. */
+  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>;
 }
+/** The Cloudflare DO data-residency jurisdictions the schema may declare. Canonical literal set for the codegen package. */
+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.
+   */
+  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;
+  /**
+   * 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/&lt;namespace>/&lt;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 `&lt;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.
-  */
+   * 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`).
-  */
+   * 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&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`).
+   */
   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}. {@link MigrationIR.table} is
+ * informational (the runtime object carries the authoritative value).
+ */
 interface MigrationIR {
   /** Export binding name, used to reference the module member in generated imports. */
   exportName: string;
@@ -179,12 +457,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&lt;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 `&lt;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.&lt;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 `&lt;projectRoot>/lunora/` without extension — always `"mutators"`. */
+  filePath: string;
+  /**
+   * Serialized TS source for the authoritative `server` impl's return type,
+   * `Promise&lt;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>;
@@ -195,25 +570,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;
@@ -222,18 +597,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;
@@ -261,20 +636,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;
@@ -283,21 +658,152 @@ 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.
+ */
+interface QueueIR {
+  /** The Cloudflare `Queue` producer binding name, e.g. `QUEUE_EMAIL`. */
+  bindingName: string;
+  /** The `lunora/queues.ts` export name, e.g. `emailQueue`. */
+  exportName: string;
+  /** 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.
+   */
   name: string;
+  /** Push-consumer batch/retry tuning, mirrored onto the wrangler `queues.consumers[]` entry. */
+  tuning: {
+    deadLetterQueue?: string;
+    maxBatchSize?: number;
+    maxBatchTimeout?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+  };
+}
+/**
+ * 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.
+   */
+  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.
+   */
+  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;
@@ -309,14 +815,23 @@ 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 `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).
+ */
 interface QueryReadIR {
+  /** Exported procedure the read sits in, or `""` at module scope. */
+  exportName: string;
   /** Source file relative to `&lt;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(...)`. */
@@ -327,12 +842,12 @@ interface QueryReadIR {
   table: 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.&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`.
+ */
 interface AuthApiCallIR {
   /** Export binding name of the function performing the call, e.g. "createOrg". */
   exportName: string;
@@ -346,12 +861,12 @@ 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;
@@ -363,14 +878,14 @@ 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;
@@ -384,13 +899,13 @@ 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.
-*/
+ * 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`. */
   callee: string;
@@ -404,21 +919,21 @@ interface R2sqlCallIR {
   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. */
   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[];
@@ -430,22 +945,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. */
   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;
@@ -460,14 +975,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;
@@ -477,24 +992,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 `"&lt;module>"` when declared at file scope. */
+  exportName: string;
+  /** Source file relative to `&lt;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;
@@ -506,12 +1045,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;
@@ -521,11 +1060,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[];
@@ -544,24 +1083,33 @@ 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.&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.
+ */
 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&lt;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". */
@@ -580,28 +1128,60 @@ 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 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;
+  /** `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. */
+  fanOut: boolean;
   /** Source file relative to `&lt;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. */
+  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. */
+  usesInsertManyUnsafe: boolean;
   /** `true` when the chain carries `.use(mask(...))`. */
   usesMask: boolean;
   /** `true` when the chain carries `.use(rateLimit(...))` or a `protectPublic({ rateLimit })` bundle. */
@@ -614,13 +1194,13 @@ interface ProcedureMiddlewareIR {
   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[];
@@ -634,11 +1214,32 @@ 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 `&lt;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. */
   file: string;
@@ -650,14 +1251,14 @@ 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;
@@ -667,11 +1268,343 @@ interface SqlInterpolationIR {
   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`.
-*/
+ * 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. */
+  file: string;
+  /** 1-based line of the `ctx.fetch` call, or `0` when unknown. */
+  line: number;
+}
+/**
+ * One `ctx.kv.&lt;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 `&lt;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;
+}
+/**
+ * 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 `&lt;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 `&lt;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";
+}
+/**
+ * One `ctx.storage.&lt;bucket>.&lt;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 `&lt;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;
+}
+/**
+ * One `ctx.containers.&lt;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 `&lt;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;
+}
+/**
+ * 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 `&lt;projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `ctx.ai.run` call, or `0` when unknown. */
+  line: number;
+}
+/**
+ * One `ctx.vectors.&lt;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 `&lt;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;
+}
+/**
+ * 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 `&lt;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;
+}
+/**
+ * One `ctx.browser.&lt;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 `&lt;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;
+}
+/**
+ * One runtime container-override call: a `&lt;handle>.start({ enableInternet: true, … })`
+ * launch override, or a `&lt;handle>.egress.&lt;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 `&lt;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;
+}
+/**
+ * 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 `&lt;projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the `buildImageDeliveryUrl` call, or `0` when unknown. */
+  line: number;
+}
+/**
+ * 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 `&lt;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;
+}
+/**
+ * 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 `&lt;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;
+}
+/**
+ * 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 `&lt;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;
+}
+/**
+ * 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. */
   exportName: string;
@@ -684,6 +1617,317 @@ interface AdminRouteIR {
   /** `true` when the handler body references an auth/session/admin guard (`ctx.auth`, `getSession`, `requireAdmin`, …). */
   usesGuard: boolean;
 }
+/**
+ * One tracked `ctx.storage.&lt;bucket>.&lt;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 `&lt;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 `"&lt;module>"` when mounted inline / not a named binding). */
+  exportName: string;
+  /** Source file relative to `&lt;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.&lt;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 `"&lt;module>"` when mounted inline. */
+  exportName: string;
+  /** Source file relative to `&lt;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 `"&lt;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 `&lt;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", &lt;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 `"&lt;module>"` at file scope. */
+  exportName: string;
+  /** Source file relative to `&lt;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 `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 `&lt;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 `&lt;receiver>.identity.&lt;key>` claim read in `lunora/`, where `&lt;receiver>` is
+ * an RLS/mask policy `auth` (or `ctx.auth`/`context.auth`). `declared` records
+ * whether `&lt;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 (`&lt;module>` at file scope). */
+  exportName: string;
+  /** Source file relative to `&lt;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 (`&lt;module>` at file scope). */
+  exportName: string;
+  /** Source file relative to `&lt;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.&lt;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 `&lt;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.&lt;table>.findMany({ with: { &lt;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 `&lt;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.&lt;table>.findMany()` / `.findFirst()` / `.get()` read, or a
+ * `ctx.db.query("&lt;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 `&lt;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 `&lt;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>;
@@ -693,388 +1937,646 @@ interface ProjectIR {
   schema: SchemaIR;
 }
 /**
-* 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.
-*/
+ * 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>;
+  flagSecurityDefaults?: ReadonlyArray<FlagSecurityDefaultIR>;
+  geoIndexUsages?: ReadonlyArray<AdvisorGeoIndexUsage>;
+  httpActionGuards?: ReadonlyArray<HttpActionGuardIR>;
+  httpHeaderWrites?: ReadonlyArray<HttpHeaderWriteIR>;
+  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<R2sqlCallIR>;
+  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>;
+  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;
 /**
-* 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 {
+ * 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: &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.
-*/
+ * 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;
-/**
-* 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.
-*/
+/** 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.&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";
 /**
-* 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.
-*/
+ * 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
-* 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[];
-/**
-* Scan all .ts files under `lunoraDir` (skipping `_generated/` and `schema.ts`)
-* for top-level `export const x = query/mutation/action({...})` registrations.
-*/
+ * 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.&lt;verb>(...)…handler(...)` typed REST routes.
-* These are the headline OpenAPI target: each becomes a real `paths` entry.
-*/
+ * 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[];
 /**
-* 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).
-*/
+ * 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.
-*/
+ * 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[];
 /**
-* 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.
-*/
+ * 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[];
-/**
-* 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.
-*/
+/** 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.&lt;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[];
-/**
-* 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.
-*/
+/** 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;
+/**
+ * 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[];
-/**
-* 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.
-*/
+/** 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.
+ */
+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[];
 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
+ * {@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.
+ */
 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 (either tool) and provisioning the
+ * `BROWSER` wrangler binding (`browserTool` — the browser op runs on
+ * `ctx.browser` inside the dispatcher).
+ */
+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;
+}
+declare const discoverSandboxUsage: (project: Project, lunoraDirectory: string) => SandboxUsage;
 /**
-* 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.
-*/
+ * 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;
+/** 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/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.
+ *
+ * `&lt;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.
+ *
+ * `&lt;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&lt;"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/analytics` / `ctx.analytics` — wires the write helper onto every ctx. */
+  /** A `lunora/` source uses `@lunora/bindings/analytics` / `ctx.analytics` — wires the write helper onto every ctx. */
   hasAnalytics?: boolean;
   /** A `lunora/` source uses `@lunora/browser` / `ctx.browser` — wires `ctx.browser` onto ActionCtx only. */
   hasBrowser?: boolean;
+  /** The project declares `lunora/flags.ts` — wires `ctx.flags` (OpenFeature) onto every ctx. */
+  hasFlags?: boolean;
   /** A `lunora/` source uses `@lunora/hyperdrive` / `ctx.sql` — wires `ctx.sql` onto ActionCtx only. */
   hasHyperdrive?: boolean;
-  /** A `lunora/` source uses `@lunora/images` / `ctx.images` — wires `ctx.images` onto ActionCtx only. */
+  /** A `lunora/` source uses `@lunora/bindings/images` / `ctx.images` — wires `ctx.images` onto ActionCtx only. */
   hasImages?: boolean;
-  /** A `lunora/` source uses `@lunora/kv` / `ctx.kv` — wires `ctx.kv` onto every ctx. */
+  /** 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/pipelines` / `ctx.pipelines` — wires `ctx.pipelines` onto ActionCtx only. */
+  /** A `lunora/` source uses `@lunora/bindings/pipelines` / `ctx.pipelines` — wires `ctx.pipelines` onto ActionCtx only. */
   hasPipelines?: boolean;
-  /** A `lunora/` source uses `@lunora/r2sql` / `ctx.r2sql` — wires `ctx.r2sql` onto ActionCtx only. */
+  /** A `lunora/` source uses `@lunora/bindings/r2sql` / `ctx.r2sql` — wires `ctx.r2sql` onto ActionCtx only. */
   hasR2sql?: 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;
   storageRuleBuckets?: ReadonlyArray<string>;
   /** The project depends on the `lunora` umbrella — import base packages via its subpaths. */
   useUmbrella?: boolean;
   workflows?: ReadonlyArray<WorkflowIR>;
 }
-declare const emitServer: ({
-  containers,
-  hasAi,
-  hasAnalytics,
-  hasBrowser,
-  hasHyperdrive,
-  hasImages,
-  hasKv,
-  hasPayments,
-  hasPipelines,
-  hasR2sql,
-  schema,
-  storageRuleBuckets,
-  useUmbrella,
-  workflows
-}?: EmitServerOptions) => string;
-declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>) => 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 emitContainers: (containers: ReadonlyArray<ContainerIR>) => 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).
-*/
+declare const emitServer: ({ agents, containers, env, hasAccessFacade, hasAi, hasAnalytics, hasBrowser, 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).
+ */
 declare const emitWorkflows: (workflows: ReadonlyArray<WorkflowIR>) => string;
+/**
+ * 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>;
+  /** 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.&lt;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;
   /** A `lunora/` source reads `ctx.browser` — wires `ctx.browser` onto the ActionCtx only. */
   hasBrowser?: boolean;
+  /** The project declares `lunora/flags.ts` — wires `ctx.flags` (OpenFeature) onto every ctx. */
+  hasFlags?: boolean;
   /** A `lunora/` source reads `ctx.sql` (Hyperdrive) — wires `ctx.sql` onto the ActionCtx only. */
   hasHyperdrive?: boolean;
   /** A `lunora/` source reads `ctx.images` — wires `ctx.images` onto the ActionCtx only. */
   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,
-  hasAi,
-  hasAnalytics,
-  hasBrowser,
-  hasHyperdrive,
-  hasImages,
-  hasKv,
-  hasPayments,
-  hasR2sql,
-  maskMetadata,
-  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/analytics` / `ctx.analytics` → emit `.analytics()` (override the dataset backing `ctx.analytics`). */
+  /** App uses `@lunora/bindings/analytics` / `ctx.analytics` → emit `.analytics()` (override the dataset backing `ctx.analytics`). */
   hasAnalytics: boolean;
   /** App depends on `@lunora/auth` → emit `.auth()` + the lazy build/migrate dance. */
   hasAuth: boolean;
@@ -1088,13 +2590,17 @@ interface EmitAppOptions {
   hasHyperdrive: boolean;
   /** Schema declares **Hyperdrive-backed** `.global({ backend: "hyperdrive" })` tables → emit `.hyperdriveGlobal()` (reactive Postgres/MySQL ctx-db over Hyperdrive). */
   hasHyperdriveGlobal: boolean;
-  /** App uses `@lunora/images` / `ctx.images` → emit `.images()`. */
+  /** App uses `@lunora/bindings/images` / `ctx.images` → emit `.images()`. */
   hasImages: boolean;
-  /** App uses `@lunora/kv` / `ctx.kv` → emit `.kv()`. */
+  /** App uses `@lunora/bindings/kv` / `ctx.kv` → emit `.kv()`. */
   hasKv: 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 uses `@lunora/r2sql` / `ctx.r2sql` → emit `.r2sql()`. */
+  /** App declares push queues (`defineQueue`) → wire `LUNORA_QUEUE_REGISTRY` into the worker's `queue()` consumer entry. */
+  hasQueue: boolean;
+  /** App uses `@lunora/bindings/r2sql` / `ctx.r2sql` → emit `.r2sql()`. */
   hasR2sql: boolean;
   /** App imports `@lunora/scheduler` / declares crons → emit `.scheduler()`. */
   hasScheduler: boolean;
@@ -1104,28 +2610,45 @@ 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;
   /** 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/&lt;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 {
@@ -1135,40 +2658,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";
@@ -1179,347 +2702,577 @@ 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 {
-  /** 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" | "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).
-*/
-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;
-/**
-* 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;
-/** 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). */
-  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. */
-  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.
-  */
-  reason: 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 `&lt;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.
+ *
+ * Exported so `@lunora/config` can assert that its driver registry and this
+ * capability-matrix registry name the same targets. They are two id spaces for one
+ * concept: a target that ships a driver but no matrix passes the CLI's
+ * validation and then emits an un-gated surface, and one with a matrix but no
+ * driver gates a surface nothing can deploy. Today both hold exactly
+ * `cloudflare`, which is why nothing has noticed.
+ * @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. `platform_unsupported_feature` and `platform_unknown_target` are both 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` or `platform_unknown_target`. */
+  name: "platform_unknown_target" | "platform_unsupported_feature";
+  /** How to resolve it. */
+  remediation: string;
+  /** The requested deploy target. */
+  target: 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.
-*/
-declare const evaluateSchemaDrift: (options: {
-  allowDrift?: boolean;
-  baseline: SchemaSnapshot | undefined;
-  current: SchemaSnapshot;
-}) => 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.
-*/
+ * 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";
 /**
-* 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.
-*/
+ * 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. 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.
-*/
+ * 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;
 /**
-* 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}.
-*/
+ * 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.
-  */
+   * 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.
-  */
+   * 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}.
-  */
+   * 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.
-  */
+   * 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;
   /**
-  * 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.
-  */
+   * 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 {
   /**
-  * 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.
-  */
+   * 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>;
   /**
-  * 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.
-  */
+   * 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.
-  */
+   * 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. */
+    /** 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. */
+    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`.
-    */
+     * 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`.
-    */
+     * 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. */
+    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;
   };
   outputDirectory: 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`.
-  */
+   * 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 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).
-*/
+ * 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 deliberately NOT sorted: they are emitted in
+ * declaration order from the schema source, which is already deterministic for a
+ * given source file and keeps the snapshot readable next to the schema it mirrors.
+ */
+declare const buildSchemaSnapshot: (schema: SchemaIR, migrationIds: ReadonlyArray<string>) => SchemaSnapshot;
+/**
+ * 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);
+}
+/**
+ * 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). */
+  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. */
+  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.
+   */
+  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.
+ */
+declare const evaluateSchemaDrift: (options: {
+  allowDrift?: boolean;
+  baseline: SchemaSnapshot | undefined;
+  current: SchemaSnapshot;
+}) => SchemaDriftDecision;
+/**
+ * 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.
-*/
+ * 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.
-*/
+/**
+ * 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>;
+/** 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, type FieldSnapshot, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type MaskProcedureIR, type MigrationIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, type QueryReadIR, 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, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverNondeterministicCalls, discoverQueries, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, 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 CronJobIR, DEFAULT_TARGET, type DriftChange, 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 OpenRpcEmitInput, type PlatformDiagnostic, 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, SHAPES_FILENAME, type SandboxUsage, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, 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, diagnosticAt, diffSchemaSnapshots, discoverAgents, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, 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, evaluateSchemaDrift, formatAdvisories, lintSchema, parseSchemaSnapshot, platformMatrixIds, readProjectTarget, redact, refreshCodegenProject, resolveCodegenTarget, runCodegen, schemaFromIr, secretKindOf, serializeSchemaSnapshot, toAdvisorContext, validatorIrToJsonSchema };