@lunora/codegen 0.0.0 → 1.0.0-alpha.10

package/dist/index.d.mts

@@ -0,0 +1,1562 @@
+import { Finding } from '@lunora/advisor';
+export type { Finding } from '@lunora/advisor';
+import { Node, Project } from 'ts-morph';
+import { StudioFeaturesResult } from '@lunora/do';
+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.
+*/
+interface ColumnMetaIR {
+  /** `.default(...)` or `.$defaultFn(...)` present — field is optional on insert. */
+  hasDefault?: boolean;
+  /** `.$onUpdateFn(...)` present. */
+  hasOnUpdate?: boolean;
+  /** Default `true`; `.nullable()` flips it to `false`. */
+  notNull: boolean;
+  /** `.unique()` present. */
+  unique?: boolean;
+}
+/** Reflective representation of a single validator call from the schema. */
+interface ValidatorIR {
+  /** For `v.storage(bucket?)` — the named typed bucket the object key lives in, when given. */
+  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)`. */
+  keyType?: ValidatorIR;
+  /** Kind of validator (string, number, id, object, optional, array, union, literal, record, ...). */
+  kind: string;
+  /** For `v.literal(value)` — the literal value as source text. */
+  literalValue?: string;
+  /** For `v.union(a, b, ...)`. */
+  members?: ValidatorIR[];
+  /** For `v.object({...})`. */
+  shape?: Record<string, ValidatorIR>;
+  /** Verbatim source text — used in emitted code when we can't reconstruct from AST. */
+  sourceText?: string;
+  /** For `v.id("table")` — the table name. */
+  tableName?: string;
+  valueType?: ValidatorIR;
+}
+interface IndexIR {
+  fields: ReadonlyArray<string>;
+  name: string;
+  unique?: boolean;
+}
+interface SearchIndexIR {
+  /** Primary text-search field. */
+  field: string;
+  /** Optional filter fields surfaced alongside the FTS column. */
+  filterFields?: ReadonlyArray<string>;
+  name: string;
+}
+interface VectorIndexIR {
+  dimensions?: number;
+  /** Shape A: the single source column. Shape B: undefined (derived via a `select` fn). */
+  field?: string;
+  /** Shape A: metadata field names mirrored into Vectorize. */
+  metadata?: ReadonlyArray<string>;
+  metric?: "cosine" | "dot-product" | "euclidean";
+  name: string;
+  /** Owning table the vectors are sourced from. */
+  table: string;
+}
+/**
+* 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.
+*/
+interface RankIndexIR {
+  name: string;
+  /** Columns scoping each ranking; omitted ⇒ one global rank over the table. */
+  partitionBy?: ReadonlyArray<string>;
+  /** Ordered sort keys driving the rank. */
+  sortBy: ReadonlyArray<RankSortKeyIR>;
+}
+interface RelationIR {
+  /** FK column: on this table for `one`, on the target table for `many`. */
+  field: string;
+  kind: "many" | "one";
+  /** Accessor name the relation is loaded under (the `with` key). */
+  name: string;
+  /** FK behaviour applied to holder rows when the referenced parent is deleted. */
+  onDelete?: "cascade" | "restrict" | "set null";
+  /** Referenced column (defaults to `_id`). */
+  references: string;
+  /** Target table name. */
+  table: string;
+}
+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`.
+  */
+  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.
+  */
+  globalBackend?: "d1" | "hyperdrive";
+  indexes: ReadonlyArray<IndexIR>;
+  name: string;
+  /** Rank indexes declared inline via `.rankIndex(name, …)`. */
+  rankIndexes: ReadonlyArray<RankIndexIR>;
+  /** Declared relations (via `.relations((r) => …)`), keyed in source order. */
+  relations: ReadonlyArray<RelationIR>;
+  searchIndexes: ReadonlyArray<SearchIndexIR>;
+  shape: Record<string, ValidatorIR>;
+  shardMode: "global" | "root" | {
+    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;
+  };
+  /** 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;
+  tables: ReadonlyArray<TableIR>;
+  /** All vector indexes (inline Shape A hoisted + standalone Shape B), flattened. */
+  vectorIndexes: ReadonlyArray<VectorIndexIR>;
+}
+interface FunctionIR {
+  args: Record<string, ValidatorIR>;
+  exportName: string;
+  /** 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.
+  */
+  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`).
+  */
+  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.
+  */
+  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).
+*/
+interface MigrationIR {
+  /** Export binding name, used to reference the module member in generated imports. */
+  exportName: string;
+  /** Path relative to `&lt;projectRoot>/lunora/` without extension, e.g. "migrations". */
+  filePath: string;
+  /** Stable migration id — the registry key and per-shard run-state key. */
+  id: string;
+  /** Table the migration iterates; `""` when not a static string literal. */
+  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.
+*/
+interface CronJobIR {
+  /** Static args object (source-text JSON), defaults to `{}`. */
+  args: Record<string, unknown>;
+  /** Compiled standard cron expression, e.g. `"0 9 * * *"`. */
+  cron: string;
+  /** Target function ref `namespace:fn`. Present for a function target; absent when {@link CronJobIR.workflow} is set. */
+  functionPath?: string;
+  /** 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.
+  */
+  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.
+*/
+interface ContainerIR {
+  /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
+  bindingName: string;
+  /** Static Dockerfile build args (wrangler `image_vars`), when declared as literals. */
+  buildArgs?: Record<string, string>;
+  /** 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.
+  */
+  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.
+  */
+  image: {
+    buildContext: string;
+    dockerfilePath: string;
+    kind: "dockerfile";
+  } | {
+    buildDir: string;
+    kind: "build";
+  } | {
+    kind: "registry";
+    reference: string;
+  };
+  /** Static `instanceType`, when declared. */
+  instanceType?: string | {
+    diskMb?: number;
+    memoryMib?: number;
+    vcpu?: number;
+  };
+  /** Static `maxInstances`, when declared. */
+  maxInstances?: number;
+  /** Static wrangler `containers[].name` override, when declared. */
+  name?: string;
+  /** Static rolling-deploy tuning, when declared as literals. */
+  rollout?: {
+    gracePeriodSeconds?: number;
+    stepPercentage?: number;
+  };
+  /**
+  * 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.
+*/
+interface WorkflowIR {
+  /** The Cloudflare `Workflow` binding name, e.g. `WORKFLOW_ORDER_PIPELINE`. */
+  bindingName: string;
+  /** Generated `WorkflowEntrypoint` class name, e.g. `OrderPipelineWorkflow`. */
+  className: string;
+  /** 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.
+  */
+  name: string;
+}
+/**
+* A `ctx.workflows.get("name")…` call discovered in a function body — the
+* use-site analog of {@link WorkflowIR} (which is the declaration side). Feeds
+* the `workflow_unused` lint (a declared workflow with zero call sites) and the
+* `workflow_unknown_target` lint (a `.get("x")` whose `x` isn't declared — a
+* typo catcher). {@link WorkflowCallIR.workflow} is `""` when the `get(...)`
+* argument is not a string literal (a dynamic name — which suppresses the
+* unused-workflow heuristic rather than producing a false positive).
+*/
+interface WorkflowCallIR {
+  /** Export binding name of the function performing the call, e.g. `create`. */
+  exportName: string;
+  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension (the api namespace). */
+  file: string;
+  /** 1-based line of the `get(...)` call. */
+  line: number;
+  /** The referenced workflow export name, or `""` when the argument is not a string literal. */
+  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).
+*/
+interface QueryReadIR {
+  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** The chain calls `.filter(...)`. */
+  hasFilter: boolean;
+  /** The chain narrows with `.withIndex(...)` or `.withSearchIndex(...)`. */
+  hasIndex: boolean;
+  /** 1-based line of the `query(...)` call. */
+  line: number;
+  /** Queried table name, or `""` when the argument is not a string literal. */
+  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`.
+*/
+interface AuthApiCallIR {
+  /** Export binding name of the function performing the call, e.g. "createOrg". */
+  exportName: string;
+  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** True when the call's argument object includes a `headers` property. */
+  hasHeaders: boolean;
+  /** 1-based line of the call, or `0` when unknown. */
+  line: number;
+  /** The better-auth method invoked (e.g. `banUser`); empty when not statically known. */
+  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.
+*/
+interface InsertWriteIR {
+  /** Export binding name of the function performing the insert, e.g. "send". */
+  exportName: string;
+  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension (the api namespace). */
+  file: string;
+  /** 1-based line of the `insert(...)` call. */
+  line: number;
+  /** Target table name, or `""` when the argument is not a string literal. */
+  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.
+*/
+interface NondeterministicCallIR {
+  /** The non-deterministic API invoked, e.g. `Date.now` / `Math.random` / `crypto.randomUUID` / `fetch`. */
+  callee: string;
+  /** Export binding name of the function performing the call, e.g. `sendMessage`. */
+  exportName: string;
+  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension (the api namespace). */
+  file: string;
+  /** Which procedure kind the call lives in — only `query`/`mutation` handlers are recorded. */
+  kind: "mutation" | "query";
+  /** 1-based line of the call, or `0` when unknown. */
+  line: number;
+}
+/**
+* One `ctx.r2sql` access lexically inside a `query`/`mutation` handler — the
+* `r2sql_outside_action` advisor lint input. Structurally identical to the
+* advisor's `AdvisorR2sqlCall` (same field set) so values pass straight through
+* `lintSchema` without conversion, exactly as `NondeterministicCallIR` does.
+* Only `query`/`mutation` handlers are recorded; `action(...)` is the intended
+* home for `ctx.r2sql` and is skipped.
+*/
+interface R2sqlCallIR {
+  /** The accessed `ctx.r2sql` surface, e.g. `ctx.r2sql.query` / `ctx.r2sql.from`. */
+  callee: string;
+  /** Export binding name of the function performing the access. */
+  exportName: string;
+  /** Source file relative to the lunora dir, without extension (the api namespace). */
+  file: string;
+  /** Which procedure kind the access lives in — only `query`/`mutation` handlers are recorded. */
+  kind: "mutation" | "query";
+  /** 1-based line of the access, or `0` when unknown. */
+  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`.
+*/
+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.
+  */
+  rlsTables: string[];
+  /** Tables read by the procedure via `ctx.db.query/findMany/findFirst/…`. */
+  tablesRead: string[];
+  /** Tables written by the procedure via `ctx.db.insert/patch/replace/delete`. */
+  tablesWritten: string[];
+  /** `true` when the procedure's builder chain includes `.use(rls(...))`. */
+  usesRls: boolean;
+  /** `"internal"` for `internalQuery` / `internalMutation` / `internalAction`. */
+  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.
+*/
+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`).
+  */
+  maskColumns: {
+    column: string;
+    table: string;
+  }[];
+  /** Tables read by the procedure via `ctx.db.query/findMany/findFirst/get`. */
+  tablesRead: string[];
+  /** Tables written by the procedure via `ctx.db.insert/patch/replace/delete`. */
+  tablesWritten: string[];
+  /** `true` when the procedure's builder chain includes `.use(mask(...))`. */
+  usesMask: boolean;
+  /** `"internal"` for `internalQuery` / `internalMutation` / `internalAction`. */
+  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.
+*/
+interface MaskColumnMetadataIR {
+  /** Column the mask policy redacts. */
+  column: string;
+  /** Declared masking strategy: `"redact"`/`"hash"` string literals, else `"custom"` for a `MaskFn`. */
+  strategy: "custom" | "hash" | "redact";
+  /** Logical table the masked column belongs to. */
+  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}.
+*/
+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.
+*/
+interface RlsPolicyIR {
+  /** Source file (relative to `lunora/`, without extension) the policy is declared in. */
+  file: string;
+  /** Operation the policy gates: `read` covers get/query/findMany, the rest are writes. */
+  on: "delete" | "insert" | "read" | "update";
+  /** Export name of the procedure whose `.use(rls(...))` chain declared this policy. */
+  procedure: string;
+  /** Logical table the policy applies to. Empty when not a string literal. */
+  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`.
+*/
+interface RlsRoleIR {
+  /** Optional human-readable description from `defineRole(name, { description })`. */
+  description?: string;
+  /** Role label attached to the request identity (e.g. `"admin"`). */
+  name: string;
+  /** Permission names this role grants, deduped and in declared order. */
+  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.
+*/
+interface RlsMetadataIR {
+  /** Every statically-discovered policy `(table, on, procedure)` entry. */
+  policies: RlsPolicyIR[];
+  /** Every statically-discovered role, deduped by name (first declaration wins). */
+  roles: RlsRoleIR[];
+}
+/** One statically-discovered `defineStorageRule({ bucket, on, prefix })` entry from a `.use(storageRules(...))` chain. */
+interface StorageRuleIR {
+  bucket: string;
+  /** Relative to `lunora/`. */
+  file: string;
+  on: "delete" | "list" | "read" | "write";
+  /** Optional key-prefix scope; absent ⇒ the whole bucket. */
+  prefix?: string;
+  /** The exported procedure that installed the rule. */
+  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.
+*/
+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.
+*/
+interface HttpRouteIR {
+  /** `v.*` validators decoding the JSON request body (`.body({...})`), keyed by field. */
+  body: Record<string, ValidatorIR>;
+  /** 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". */
+  filePath: string;
+  /** HTTP verb the route binds to (uppercased), e.g. `"GET"`. */
+  method: string;
+  /** The `.output(validator)` return schema when declared; absent ⇒ TS-inferred / best-effort. */
+  output?: ValidatorIR;
+  /** `v.*` validators decoding the hono path params (`.params({...})`), keyed by `:name`. */
+  params: Record<string, ValidatorIR>;
+  /** The route path passed to `httpRoute.&lt;verb>(path)`, e.g. `/api/todos/:id`. */
+  path: string;
+  /** `v.*` validators decoding the URL query string (`.searchParams({...})`), keyed by name. */
+  searchParams: Record<string, ValidatorIR>;
+  /** `true` when declared via the terminal `.stream(...)` (Server-Sent Events) rather than `.handler(...)`. */
+  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.
+*/
+interface ProcedureMiddlewareIR {
+  /** `true` when the handler (or a helper inside it) references `ctx.mail` / `ctx.email`. */
+  callsMail: boolean;
+  /** Export binding name of the procedure (e.g. `signUp`). */
+  exportName: string;
+  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** Registration kind — only `mutation`/`action` are write-shaped; `query` is read-only. */
+  kind: "action" | "mutation" | "query";
+  /** `true` when the chain carries `.use(verifyTurnstile(...))` or a `protectPublic({ captcha })` bundle. */
+  usesCaptcha: boolean;
+  /** `true` when the chain carries `.use(mask(...))`. */
+  usesMask: boolean;
+  /** `true` when the chain carries `.use(rateLimit(...))` or a `protectPublic({ rateLimit })` bundle. */
+  usesRateLimit: boolean;
+  /** `true` when the chain carries `.use(rls(...))`. */
+  usesRls: boolean;
+  /** `"internal"` for `internalQuery` / `internalMutation` / `internalAction`. */
+  visibility: "internal" | "public";
+  /** `true` when the handler inserts into a user/session/account-shaped table. */
+  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.
+*/
+interface ArgumentValidatorIR {
+  /** Arg names declared as `v.any()` (unvalidated, untyped input). */
+  anyArgs: string[];
+  /** Export binding name of the procedure (e.g. `updateProfile`). */
+  exportName: string;
+  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the registration call, or `0` when unknown. */
+  line: number;
+  /** Arg names declared as `v.string()` with no statically-visible max-length bound. */
+  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`.
+*/
+interface SecretLiteralIR {
+  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** Heuristic that matched, e.g. `stripe_live_key` / `aws_access_key` / `pem_private_key` / `high_entropy`. */
+  kind: string;
+  /** 1-based line of the literal, or `0` when unknown. */
+  line: number;
+  /** Redacted preview of the literal (first few chars + length) for the finding detail — never the full secret. */
+  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`.
+*/
+interface SqlInterpolationIR {
+  /** Export binding name of the procedure performing the `ctx.sql` call. */
+  exportName: string;
+  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** 1-based line of the interpolation, or `0` when unknown. */
+  line: number;
+}
+/**
+* One discovered `httpRoute.&lt;verb>("/admin/…")` route on an admin/privileged-looking
+* path, with whether its builder chain references an auth/admin guard — the
+* `admin_route_without_guard` lint input. Structurally identical to
+* `AdvisorAdminRoute`.
+*/
+interface AdminRouteIR {
+  /** Export binding name of the route handler. */
+  exportName: string;
+  /** Source file relative to `&lt;projectRoot>/lunora/`, without extension. */
+  file: string;
+  /** HTTP verb the route binds to (uppercased), e.g. `"POST"`. */
+  method: string;
+  /** The route path, e.g. `/admin/users`. */
+  path: string;
+  /** `true` when the handler body references an auth/session/admin guard (`ctx.auth`, `getSession`, `requireAdmin`, …). */
+  usesGuard: boolean;
+}
+interface ProjectIR {
+  crons: ReadonlyArray<CronJobIR>;
+  functions: ReadonlyArray<FunctionIR>;
+  /** Typed REST routes discovered from `httpRoute.&lt;verb>(...)` builder chains. */
+  httpRoutes: ReadonlyArray<HttpRouteIR>;
+  migrations: ReadonlyArray<MigrationIR>;
+  schema: SchemaIR;
+}
+/**
+* Run the static lints against a discovered {@link SchemaIR} and the reads/writes/calls
+* found in function bodies: query reads feed `filter_without_index`, insert writes
+* feed `table_without_insert`, authApi calls feed `auth_api_call_without_headers`,
+* rls procedure snapshots feed `rls_uncovered_table`, and mask procedure
+* snapshots feed `mask_uncovered_pii_column`; declared containers
+* feed the `container_*` lints; declared workflows + `ctx.workflows.get(...)` call
+* sites feed the `workflow_unused` / `workflow_unknown_target` lints; non-deterministic
+* calls inside query/mutation handlers feed the `nondeterministic_query_mutation` lint
+* (all default empty for callers that don't analyze functions/containers/workflows).
+* The IR types are structurally identical to the advisor's evidence types so they
+* pass straight through without conversion. Returns the findings; surfacing them
+* (console, error overlay, studio Advisors table) is the caller's choice.
+*/
+declare const lintSchema: (schema: SchemaIR, queries?: ReadonlyArray<QueryReadIR>, inserts?: ReadonlyArray<InsertWriteIR>, authApiCalls?: ReadonlyArray<AuthApiCallIR>, rlsProcedures?: ReadonlyArray<RlsProcedureIR>, containers?: ReadonlyArray<ContainerIR>, workflows?: ReadonlyArray<WorkflowIR>, workflowCalls?: ReadonlyArray<WorkflowCallIR>, maskProcedures?: ReadonlyArray<MaskProcedureIR>, nondeterministicCalls?: ReadonlyArray<NondeterministicCallIR>, procedureProtections?: ReadonlyArray<ProcedureMiddlewareIR>, argumentValidators?: ReadonlyArray<ArgumentValidatorIR>, secretLiterals?: ReadonlyArray<SecretLiteralIR>, sqlInterpolations?: ReadonlyArray<SqlInterpolationIR>, adminRoutes?: ReadonlyArray<AdminRouteIR>, r2sqlCalls?: ReadonlyArray<R2sqlCallIR>) => Finding[];
+/**
+* Render advisor findings as a single multi-line string for console surfacing:
+* a one-line summary header followed by one `[LEVEL] name: detail` line per
+* finding. Returns `""` when there are no findings.
+*/
+declare const formatAdvisories: (findings: ReadonlyArray<Finding>) => string;
+/**
+* An error thrown by codegen discovery when the user's schema or function
+* source has a structural problem that can be pinpointed to a specific source
+* location. The `file`, `line`, and `column` properties mirror what Vite's
+* error-overlay `loc` field expects so the browser can display the exact spot.
+*/
+declare class CodegenDiagnosticError extends Error {
+  readonly column: number;
+  readonly file: string;
+  readonly line: number;
+  constructor(message: string, file: string, line: number, column: number);
+}
+/**
+* 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.
+*/
+declare const discoverAuthApiCalls: (project: Project, lunoraDirectory: string) => AuthApiCallIR[];
+/** The only file containers may be declared in — mirrors `lunora/crons.ts`. */
+declare const CONTAINERS_FILENAME = "containers.ts";
+/**
+* Discover every container the project declares: exported `defineContainer()`
+* calls in `lunora/containers.ts`. Returns `[]` when the file doesn't exist.
+* Wrangler-relevant fields (`image`, `instanceType`, `maxInstances`, `name`)
+* must be static literals; runtime-only fields (`env`, `sleepAfter`, …) may be
+* any expression since the generated class imports the definition object.
+*/
+declare const discoverContainers: (project: Project, lunoraDirectory: string) => ContainerIR[];
+/**
+* Scan every `.ts` file under `lunoraDir` for `cronJobs()` builder registrations
+* (`crons.interval(...)`, `crons.daily(...)`, `crons.cron(...)`, …) and lift them
+* into {@link CronJobIR}. Schedules are compiled to standard cron expressions;
+* function references are resolved to their `namespace:fn` dispatch path, while a
+* 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.
+*/
+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.
+*/
+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).
+*/
+declare const discoverInserts: (project: Project, lunoraDirectory: string) => InsertWriteIR[];
+/**
+* Discover masking usage for every exported Lunora procedure under the lunora
+* source directory — the column-level twin of `discoverRlsProcedures`. For each
+* procedure, records whether its builder chain includes `.use(mask(...))`, which
+* `(table, column)` pairs that mask declares, and which tables it reads/writes
+* through `ctx.db`. Feeds the `mask_uncovered_pii_column` advisor lint.
+*/
+declare const discoverMaskProcedures: (project: Project, lunoraDirectory: string) => MaskProcedureIR[];
+/**
+* Aggregate the schema-wide masking metadata the studio's data-browser mask
+* toggle reads: every statically-discovered `(table, column, strategy)` masked
+* column across the project's `.use(mask(...))` chains. Walks the same builder
+* chains as {@link discoverMaskProcedures} but carries the strategy the preview
+* needs to choose redact-vs-hash-vs-custom rendering. Deduped by `(table,
+* column)` with the first declaration winning, so a column masked by several
+* procedures lists once — the same evidence the advisor lint uses.
+*/
+/**
+* Scan all `.ts` files under `lunoraDir` for top-level
+* `export const x = defineMigration({...})` declarations and lift them into
+* {@link MigrationIR}. `id` must be a static string literal (it's the registry
+* key); `table` is best-effort and left `""` when not a literal.
+*/
+declare const discoverMigrations: (project: Project, lunoraDirectory: string) => MigrationIR[];
+/**
+* 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.
+*/
+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.
+*/
+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.
+*/
+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;
+/**
+* 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.
+*/
+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.
+*/
+interface EmitServerOptions {
+  containers?: ReadonlyArray<ContainerIR>;
+  hasAi?: boolean;
+  /** A `lunora/` source uses `@lunora/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;
+  /** 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. */
+  hasImages?: boolean;
+  /** A `lunora/` source uses `@lunora/kv` / `ctx.kv` — wires `ctx.kv` onto every ctx. */
+  hasKv?: boolean;
+  hasPayments?: boolean;
+  /** A `lunora/` source uses `@lunora/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. */
+  hasR2sql?: boolean;
+  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>, useUmbrella?: boolean) => string;
+/**
+* Storage-column map per table for the file browser: `{ table: [field, …] }` for
+* every field declared `v.storage(...)` (unwrapping `v.optional(...)`). The
+* generated shard hands this to the base `storageColumns` hook so the admin
+* `storageReferences` read can join R2 objects back to the rows that own them
+* (and flag orphans — objects no row references). Only scalar storage columns
+* are emitted; an array-of-storage field can't be matched by an equality scan,
+* so it is skipped here.
+*/
+/**
+* Emit `_generated/containers.ts` — one container-enabled Durable Object class
+* per `defineContainer` export, each a thin subclass of `LunoraContainer`
+* (`@lunora/container/do`) constructed with the user's definition object. The
+* worker entry must re-export these classes: wrangler requires every
+* `containers[].class_name` to be exported by the deployed worker. Returns ""
+* when the project declares no containers (the file is not written then).
+*/
+declare const 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;
+interface EmitShardOptions {
+  advisories?: ReadonlyArray<Finding>;
+  containers?: ReadonlyArray<ContainerIR>;
+  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;
+  /** 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;
+  hasPayments?: boolean;
+  /** A `lunora/` source reads `ctx.r2sql` (R2 SQL) — wires `ctx.r2sql` onto the ActionCtx only. */
+  hasR2sql?: boolean;
+  maskMetadata?: MaskMetadataIR;
+  rlsMetadata?: RlsMetadataIR;
+  schema: SchemaIR;
+  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 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.
+*/
+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.
+*/
+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.
+*/
+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 {
+  /** 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`). */
+  hasAnalytics: boolean;
+  /** App depends on `@lunora/auth` → emit `.auth()` + the lazy build/migrate dance. */
+  hasAuth: boolean;
+  /** App uses `@lunora/browser` / `ctx.browser` → emit `.browser()`. */
+  hasBrowser: boolean;
+  /** App depends on a worker-composition framework adapter (`@lunora/astro`/`@lunora/svelte`/`@lunora/vue`) → emit `.buildFrameworkWorker(host)`. */
+  hasFramework: boolean;
+  /** Schema declares **D1-backed** `.global()` tables → emit `.global()` (D1 ctx-db + studio introspector + cross-shard relations). */
+  hasGlobal: boolean;
+  /** App uses `@lunora/hyperdrive` / `ctx.sql` → emit `.hyperdrive()`. */
+  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()`. */
+  hasImages: boolean;
+  /** App uses `@lunora/kv` / `ctx.kv` → emit `.kv()`. */
+  hasKv: boolean;
+  /** App uses `@lunora/payment` / `ctx.payments` → emit `.payment()`. */
+  hasPayments: boolean;
+  /** App uses `@lunora/r2sql` / `ctx.r2sql` → emit `.r2sql()`. */
+  hasR2sql: boolean;
+  /** App imports `@lunora/scheduler` / declares crons → emit `.scheduler()`. */
+  hasScheduler: boolean;
+  /** App uses `@lunora/storage` → emit `.storage()` (DO `ctx.storage` + studio file browser). */
+  hasStorage: boolean;
+  /** Schema declares vector indexes → emit `.vectors()` (the Vectorize index map backing `ctx.vectors`). */
+  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;
+  /** 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;
+  /** 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.
+*/
+declare const emitApp: (options: EmitAppOptions) => string;
+/** Inputs the OpenAPI emitter needs from a codegen run. */
+interface OpenApiEmitInput {
+  functions: ReadonlyArray<FunctionIR>;
+  httpRoutes: ReadonlyArray<HttpRouteIR>;
+  /** `info.version`; defaults to `"0.0.0"` with a TODO when the project version is unknown. */
+  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).
+*/
+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.
+*/
+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).
+*/
+declare const emitOpenApiModule: (document_: Record<string, unknown>) => string;
+/** The OpenRPC dialect version this emitter targets. */
+declare const OPENRPC_VERSION = "1.3.2";
+/** Inputs the OpenRPC emitter needs from a codegen run. */
+interface OpenRpcEmitInput {
+  functions: ReadonlyArray<FunctionIR>;
+  /** `info.version`; defaults to `"0.0.0"` with a TODO when the project version is unknown. */
+  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).
+*/
+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.
+*/
+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).
+*/
+declare const emitOpenRpcModule: (document_: Record<string, unknown>) => string;
+/** Current snapshot format version. Bumped if the structural shape below changes. */
+declare const SCHEMA_SNAPSHOT_VERSION: 1;
+/** A single field's structural shape: its value kind and whether it is optional. */
+interface FieldSnapshot {
+  /** The validator kind (`string`, `number`, `id`, `object`, …) after unwrapping `v.optional`. */
+  kind: string;
+  /** True when declared `v.optional(...)` — accepts `undefined` / absent on insert. */
+  optional: boolean;
+}
+/** A single secondary index's structural shape. */
+interface IndexSnapshot {
+  fields: ReadonlyArray<string>;
+  unique: boolean;
+}
+/** A single relation's structural shape. */
+interface RelationSnapshot {
+  field: string;
+  kind: "many" | "one";
+  table: string;
+}
+/** Structural snapshot of one table. */
+interface TableSnapshot {
+  /** Field name → {@link FieldSnapshot}, in declared order. */
+  fields: Record<string, FieldSnapshot>;
+  /** Index name → {@link IndexSnapshot}. */
+  indexes: Record<string, IndexSnapshot>;
+  /** Relation accessor name → {@link RelationSnapshot}. */
+  relations: Record<string, RelationSnapshot>;
+  /**
+  * `"root"` (default single-DO), `"global"` (D1-replicated), or
+  * `"shardBy:&lt;field>"` (partitioned). Encoded as a string so the snapshot
+  * stays a plain JSON-stable value.
+  */
+  shardMode: string;
+}
+/** The committed baseline — a deterministic structural view of the whole schema. */
+interface SchemaSnapshot {
+  /**
+  * Cloudflare DO data-residency jurisdiction declared via `.jurisdiction("…")`,
+  * or absent. Tracked because changing it strands all existing Durable Object
+  * data (a DO name maps to a different ID per jurisdiction). Optional, so old
+  * baselines written before this field parse cleanly (absent ⇒ undefined).
+  *
+  * Typed as a plain `string` (not the authoring union) on purpose: this is
+  * STORED data that a newer Lunora may have written with a jurisdiction this
+  * version doesn't yet know. Preserving the raw value keeps the breaking
+  * `changedJurisdiction` diff correct under a downgrade — coercing an unknown
+  * value to `undefined` would fail OPEN and hide the most destructive change.
+  */
+  jurisdiction?: string;
+  /** Sorted list of every declared `defineMigration` id at capture time. */
+  migrationIds: ReadonlyArray<string>;
+  /** Table name → {@link TableSnapshot}, keys sorted for stable serialization. */
+  tables: Record<string, TableSnapshot>;
+  version: typeof SCHEMA_SNAPSHOT_VERSION;
+}
+/** One classified structural change between the baseline and the current schema. */
+interface DriftChange {
+  /** `"breaking"` changes need a data migration; `"safe"` changes are additive. */
+  severity: "breaking" | "safe";
+  /** Human-readable, actionable description (used in the gate message). */
+  summary: string;
+  /** A machine-readable change discriminator. */
+  type: "addedIndex" | "addedOptionalField" | "addedRelation" | "addedRequiredField" | "addedTable" | "changedJurisdiction" | "changedFieldKind" | "changedIndex" | "changedShardMode" | "fieldOptionalToRequired" | "fieldRequiredToOptional" | "removedField" | "removedIndex" | "removedRelation" | "removedTable";
+}
+/** The result of diffing two snapshots: every classified change. */
+interface SchemaDrift {
+  /** Every classified change, in a stable order (added/changed per table, then removals). */
+  changes: ReadonlyArray<DriftChange>;
+}
+/**
+* Build a {@link SchemaSnapshot} from a parsed {@link SchemaIR} and the set of
+* declared migration ids. Tables and migration ids are sorted so the emitted
+* JSON is byte-stable across runs (no spurious diffs / churn).
+*/
+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;
+}
+/**
+* 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.
+*/
+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.
+*/
+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.
+*/
+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}.
+*/
+declare const runCodegen: (options: CodegenOptions) => CodegenResult;
+interface CodegenOptions {
+  /**
+  * Which machine-readable API spec(s) to emit into `_generated/`.
+  *
+  * `"openapi"` (the default) writes only `openapi.json` (OpenAPI 3.1; covers
+  * both the RPC functions and `httpRouter()` REST routes). `"openrpc"` writes
+  * only `openrpc.json` (OpenRPC 1.x; the RPC functions only — OpenRPC cannot
+  * represent REST routes). `"both"` writes both files; `"none"` writes neither.
+  *
+  * Regardless of the choice, `CodegenResult.generated.openApi` and `.openRpc`
+  * always carry the rendered string (computation is cheap and pure); only the
+  * on-disk write is gated by this option.
+  */
+  apiSpec?: "both" | "none" | "openapi" | "openrpc";
+  /**
+  * When true, run discovery + emit (so any schema/function parse error
+  * surfaces) but skip writing files to `_generated/`. The returned
+  * `outputDirectory` is still the path that *would* have been written.
+  */
+  dryRun?: boolean;
+  /**
+  * Run the static schema advisor (unindexed FKs, …) during codegen.
+  * Defaults to `true`. When `false`, `CodegenResult.advisories` is empty.
+  * Computed regardless of `dryRun`; codegen never prints them — see
+  * {@link CodegenResult.advisories}.
+  */
+  lint?: boolean;
+  /** Override the lunora subdirectory name. Defaults to `"lunora"`. */
+  lunoraDirectory?: string;
+  /**
+  * Reuse a previously-constructed ts-morph {@link Project} instead of building
+  * a fresh one each run. The caller owns refreshing its source files from disk
+  * (see {@link refreshCodegenProject}) — codegen does not re-read changed files
+  * off an injected Project. Built via {@link createCodegenProject} when absent.
+  * Used by the Vite dev-loop to avoid re-parsing the whole TS program on every
+  * save; omit it (CLI one-shot path) to get the default fresh-Project behaviour.
+  */
+  project?: Project;
+  /** Project root containing the `lunora/` directory. */
+  projectRoot: string;
+  /**
+  * 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;
+}
+interface CodegenResult {
+  /**
+  * Static schema advisor findings (e.g. unindexed foreign keys) produced
+  * this run. Empty when `lint` is `false` or the schema is clean. Codegen
+  * does not print these itself — each caller presents them through its own
+  * channel (the CLI logger, the vite overlay, the studio Advisors table).
+  * `formatAdvisories` is exported for a plain multi-line rendering.
+  */
+  advisories: ReadonlyArray<Finding>;
+  /**
+  * Containers discovered from `defineContainer` exports in
+  * `lunora/containers.ts` — the list the config layer reconciles into
+  * wrangler's `containers[]`, `CONTAINER_*` Durable Object bindings, and
+  * migration classes. Empty when the project declares no containers.
+  */
+  containers: ReadonlyArray<ContainerIR>;
+  /**
+  * Deduplicated cron schedules discovered from `cronJobs()` definitions —
+  * the array the vite plugin reconciles into `wrangler.jsonc`'s
+  * `triggers.crons`. Empty when the project declares no crons.
+  */
+  cronTriggers: ReadonlyArray<string>;
+  generated: {
+    api: string; /** Fluent worker-composition builder (`_generated/app.ts`) — `defineApp()`. Always written. */
+    app: string;
+    /** Container DO classes (`_generated/containers.ts`); `""` (and not written) when no containers are declared. */
+    containers: string;
+    crons: string;
+    dataModel: string;
+    drizzleGlobal: string;
+    drizzleShard: string;
+    functions: string; /** OpenAPI 3.1.0 document (`_generated/openapi.json`), pretty-printed JSON. */
+    openApi: string;
+    /**
+    * OpenAPI document as an importable TS module (`_generated/openapi.ts`) —
+    * `export const openApiSpec`, the worker imports it for
+    * `createWorker({ openApiSpec })`. Same document as `openApi`. Written
+    * alongside `openapi.json` whenever `apiSpec` includes `openapi`.
+    */
+    openApiModule: string;
+    /** OpenRPC 1.x document (`_generated/openrpc.json`), pretty-printed JSON. Always computed; written only when `apiSpec` includes `openrpc`. */
+    openRpc: string;
+    /**
+    * OpenRPC document as an importable TS module (`_generated/openrpc.ts`) —
+    * `export const openRpcSpec`, for `createWorker({ openRpcSpec })`. Same
+    * document as `openRpc`. Written alongside `openrpc.json` whenever
+    * `apiSpec` includes `openrpc`.
+    */
+    openRpcModule: string;
+    /** Project-bound seed client (`_generated/seed.ts`); `""` (and not written) when `@lunora/seed` is not a declared dependency. */
+    seed: string;
+    server: string;
+    shard: string; /** Static vector-index registry (`_generated/vectors.ts`) — `LUNORA_VECTOR_INDEXES`. Empty array body when the schema declares none. */
+    vectors: string;
+    /** WorkflowEntrypoint classes (`_generated/workflows.ts`); `""` (and not written) when no workflows are declared. */
+    workflows: string;
+  };
+  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`.
+  */
+  schemaSnapshot: SchemaSnapshot;
+  /** Absolute path of the committed baseline file (`lunora/.lunora-schema.json`). */
+  schemaSnapshotPath: string;
+  /**
+  * Workflows discovered from `defineWorkflow` exports in
+  * `lunora/workflows.ts` — the list the config layer reconciles into
+  * wrangler's `workflows[]` array. Workflows are NOT Durable Objects, so this
+  * adds no binding or migration. Empty when the project declares no workflows.
+  */
+  workflows: ReadonlyArray<WorkflowIR>;
+}
+/**
+* Convert a {@link SchemaIR} into a synthetic runtime {@link Schema} carrying just
+* the `tables[name].shape` surface `@lunora/seed` introspects. System columns
+* (`_id`, `_creationTime`) are absent from the IR shape, exactly as the seed
+* engine expects (it assigns `_id` itself).
+*/
+declare const schemaFromIr: (ir: SchemaIR) => Schema;
+/**
+* Convert a codegen {@link ValidatorIR} into a JSON Schema node. A thin wrapper
+* over the shared {@link jsonSchemaFromNode} core (from `@lunora/values`) with the
+* IR-backed {@link irReader}, so the kind→schema mapping is the *same* algorithm
+* `@lunora/values`' `toJsonSchema` runs — codegen never instantiates the runtime
+* `v.*` objects, it only holds the reflected IR. Shared by the OpenAPI and
+* OpenRPC emitters so both surfaces speak one JSON Schema dialect.
+*/
+declare const validatorIrToJsonSchema: (validator: ValidatorIR) => JsonSchema;
+/** Build `{ type: "object", properties, required }` from an IR shape (mirrors `@lunora/values`' object mapping). */
+
+/**
+* The machine-readable `LunoraError` codes Lunora emits on the RPC + REST
+* surfaces, enumerated from `@lunora/server`'s `CODE_STATUS` map plus the
+* runtime/DO dispatch codes (`FUNCTION_NOT_FOUND`, `PAYLOAD_TOO_LARGE`,
+* `METHOD_NOT_ALLOWED`, the `*_NOT_CONFIGURED` admin gates, …). The list documents
+* the contract; clients switch on `error.code`. Kept sorted for stable output.
+*/
+declare const LUNORA_ERROR_CODES: ReadonlyArray<string>;
+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 };