@lunora/codegen 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/index.d.ts

@@ -25,6 +25,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)`. */
@@ -100,6 +109,36 @@ 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 (the incremental-mode delete-visibility companion). */
+  hasReconcile?: 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"` | `"incremental"`). */
+  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
@@ -109,6 +148,13 @@ interface TableIR {
   */
   externallyManaged?: boolean;
   /**
+  * 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.
@@ -126,10 +172,23 @@ 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;
+  };
   /** 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>;
@@ -179,6 +238,59 @@ interface MigrationIR {
   table: string;
 }
 /**
+* 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 {
+  /** 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;
+}
+/**
+* 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 {
+  /** 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;
+}
+/**
+* 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
@@ -288,6 +400,79 @@ interface WorkflowIR {
   * 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>;
+}
+/** 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
@@ -384,6 +569,26 @@ interface NondeterministicCallIR {
   line: number;
 }
 /**
+* One `ctx.r2sql` access lexically inside a `query`/`mutation` handler — the
+* `r2sql_outside_action` advisor lint input. Structurally identical to the
+* advisor's `AdvisorR2sqlCall` (same field set) so values pass straight through
+* `lintSchema` without conversion, exactly as `NondeterministicCallIR` does.
+* Only `query`/`mutation` handlers are recorded; `action(...)` is the intended
+* home for `ctx.r2sql` and is skipped.
+*/
+interface R2sqlCallIR {
+  /** The accessed `ctx.r2sql` surface, e.g. `ctx.r2sql.query` / `ctx.r2sql.from`. */
+  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
@@ -678,15 +883,16 @@ interface ProjectIR {
 * 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
+* 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: (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>) => Finding[];
+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>, shapes?: ReadonlyArray<ShapeIR>, mutatorWrites?: ReadonlyArray<MutatorWriteIR>) => 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
@@ -711,8 +917,14 @@ declare class CodegenDiagnosticError extends Error {
 * 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) => CodegenDiagnosticError;
+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
@@ -738,6 +950,21 @@ declare const discoverContainers: (project: Project, lunoraDirectory: string) =>
 * workflow start. Names must be unique across the project.
 */
 declare const discoverCrons: (project: Project, lunoraDirectory: string, workflows?: ReadonlyArray<WorkflowIR>) => CronJobIR[];
+/** The only file a feature-flag provider may be declared in — mirrors `lunora/queues.ts`. */
+declare const FLAGS_FILENAME = "flags.ts";
+/** One statically-discovered flag read: the key plus the value type its `ctx.flags.&lt;type>` call implies. */
+
+/**
+* Discover the feature-flag provider a project declares in `lunora/flags.ts`.
+* Returns `undefined` when the file doesn't exist (the app has no flags). The
+* read is metadata-only and lenient: codegen wires `ctx.flags` purely from the
+* file's *existence* (`run-codegen.ts`) and imports the real module for the
+* provider value — this IR exists solely so the config layer can reconcile the
+* wrangler `flagship` binding for the Flagship binding-mode provider. Anything
+* it can't read statically degrades to a `custom` provider (no binding), never
+* a thrown error.
+*/
+declare const discoverFlags: (project: Project, lunoraDirectory: string) => FlagsIR | undefined;
 /**
 * Scan all .ts files under `lunoraDir` (skipping `_generated/` and `schema.ts`)
 * for top-level `export const x = query/mutation/action({...})` registrations.
@@ -780,6 +1007,23 @@ declare const discoverMaskProcedures: (project: Project, lunoraDirectory: string
 * key); `table` is best-effort and left `""` when not a literal.
 */
 declare const discoverMigrations: (project: Project, lunoraDirectory: string) => MigrationIR[];
+/** The only file custom mutators may be declared in — mirrors `lunora/queues.ts`. */
+declare const MUTATORS_FILENAME = "mutators.ts";
+/**
+* Decide whether a call's callee is `defineMutator` — either the bare imported
+* identifier (`defineMutator(...)`) or a namespace member access
+* (`server.defineMutator(...)`). Both are valid ES module syntax, so discovery
+* must see mutators declared either way.
+*/
+
+/**
+* Discover every custom mutator the project declares: exported
+* `defineMutator()` calls in `lunora/mutators.ts`. Returns `[]` when the file
+* doesn't exist. Only the export binding is lifted — the runtime object 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
@@ -803,6 +1047,28 @@ declare const discoverNondeterministicCalls: (project: Project, lunoraDirectory:
 * dropping the rest keeps the lint input small.
 */
 declare const discoverQueries: (project: Project, lunoraDirectory: string) => QueryReadIR[];
+/** The only file queues may be declared in — mirrors `lunora/workflows.ts`. */
+declare const QUEUES_FILENAME = "queues.ts";
+/**
+* Discover every queue the project declares: exported `defineQueue()` calls in
+* `lunora/queues.ts`. Returns `[]` when the file doesn't exist. Only the
+* wrangler-relevant literals (`name`/`mode`/batch tuning) are read; the handler
+* body is runtime-only, so codegen never evaluates it.
+*/
+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:
@@ -822,7 +1088,17 @@ declare const discoverRlsMetadata: (project: Project, lunoraDirectory: string) =
 * 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) => SchemaIR;
+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
@@ -861,22 +1137,51 @@ declare const emitApi: (functions: ReadonlyArray<FunctionIR>, workflows?: Readon
 * 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/collections.ts` — one TanStack DB collection factory per
+* `defineShape` in `lunora/shapes.ts` (the local-first partial-replication
+* surface). Each factory builds a live collection that syncs its shape's rowset
+* through the client's poke protocol (`subscribeShape`), so an app feeds the
+* result straight to `useLiveQuery`.
+*
+* 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 {
   containers?: ReadonlyArray<ContainerIR>;
+  /**
+  * 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;
   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/bindings/r2sql` / `ctx.r2sql` — wires `ctx.r2sql` onto ActionCtx only. */
+  hasR2sql?: boolean;
+  /** 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. */
@@ -885,20 +1190,24 @@ interface EmitServerOptions {
 }
 declare const emitServer: ({
   containers,
+  hasAccessFacade,
   hasAi,
   hasAnalytics,
   hasBrowser,
+  hasFlags,
   hasHyperdrive,
   hasImages,
   hasKv,
   hasPayments,
   hasPipelines,
+  hasR2sql,
+  queues,
   schema,
   storageRuleBuckets,
   useUmbrella,
   workflows
 }?: EmitServerOptions) => string;
-declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>) => string;
+declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>, useUmbrella?: boolean, mutators?: ReadonlyArray<MutatorIR>, shapes?: ReadonlyArray<ShapeIR>) => string;
 /**
 * Storage-column map per table for the file browser: `{ table: [field, …] }` for
 * every field declared `v.storage(...)` (unwrapping `v.optional(...)`). The
@@ -916,7 +1225,7 @@ declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?:
 * `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;
+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`
@@ -926,14 +1235,31 @@ declare const emitContainers: (containers: ReadonlyArray<ContainerIR>) => string
 * when the project declares no workflows (the file is not written then).
 */
 declare const emitWorkflows: (workflows: ReadonlyArray<WorkflowIR>) => string;
+/**
+* Emit `_generated/queues.ts` — the push-consumer registry the worker `queue()`
+* handler dispatches through. Maps each push queue's stable wrangler name (which
+* `batch.queue` carries) to its `defineQueue` definition + export name. Pull
+* queues are consumed by an external worker, so they carry no handler and are
+* omitted here. Returns "" (and the file is not written) when no push queues are
+* declared — a pull-only or queue-free app keeps a clean `_generated/`.
+*/
 interface EmitShardOptions {
   advisories?: ReadonlyArray<Finding>;
   containers?: ReadonlyArray<ContainerIR>;
+  /** 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. */
@@ -941,9 +1267,19 @@ interface EmitShardOptions {
   /** A `lunora/` source reads `ctx.kv` — wires `ctx.kv` onto every ctx. */
   hasKv?: 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;
   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;
+  /** 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. */
@@ -953,16 +1289,24 @@ interface EmitShardOptions {
 declare const emitShard: ({
   advisories,
   containers,
+  flagKeys,
+  hasAccessFacade,
   hasAi,
   hasAnalytics,
   hasBrowser,
+  hasFlags,
   hasHyperdrive,
   hasImages,
   hasKv,
   hasPayments,
+  hasPipelines,
+  hasR2sql,
   maskMetadata,
+  mutators,
+  queues,
   rlsMetadata,
   schema,
+  shapes,
   storageRules,
   studioFeatures,
   useUmbrella,
@@ -1027,9 +1371,11 @@ declare const emitVectors: (vectorIndexes: ReadonlyArray<VectorIndexIR>) => stri
 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 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;
@@ -1043,12 +1389,16 @@ 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 uses `@lunora/payment` / `ctx.payments` → emit `.payment()`. */
   hasPayments: boolean;
+  /** App declares push queues (`defineQueue`) → wire `LUNORA_QUEUE_REGISTRY` into the worker's `queue()` consumer entry. */
+  hasQueue: boolean;
+  /** App uses `@lunora/bindings/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). */
@@ -1057,6 +1407,8 @@ 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;
+  /** 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. */
@@ -1201,6 +1553,19 @@ interface TableSnapshot {
 }
 /** 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. */
@@ -1214,7 +1579,7 @@ interface DriftChange {
   /** 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";
+  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 {
@@ -1316,6 +1681,11 @@ declare const refreshCodegenProject: (project: Project, lunoraDirectory: string)
 * Top-level codegen entry. Parses `&lt;projectRoot>/lunora/schema.ts` and every
 * function file under `&lt;projectRoot>/lunora/`, then writes
 * `_generated/{api,server,dataModel}.ts` next to them.
+*
+* When `LUNORA_CODEGEN_TIMING` is set (truthy), a single diagnostic summary
+* line is written to stderr with the total wall time and the discovery-vs-emit
+* split — opt-in instrumentation that is otherwise zero-cost and side-effect-free
+* on the returned {@link CodegenResult}.
 */
 declare const runCodegen: (options: CodegenOptions) => CodegenResult;
 interface CodegenOptions {
@@ -1392,6 +1762,8 @@ interface CodegenResult {
   generated: {
     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;
@@ -1416,6 +1788,8 @@ interface CodegenResult {
     * `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;
@@ -1426,6 +1800,13 @@ interface CodegenResult {
   };
   outputDirectory: string;
   /**
+  * Queues discovered from `defineQueue` exports in `lunora/queues.ts` — the
+  * list the config layer reconciles into wrangler's `queues.producers[]` /
+  * `queues.consumers[]`. Queues are NOT Durable Objects, so this adds no
+  * binding or migration. Empty when the project declares no queues.
+  */
+  queues: ReadonlyArray<QueueIR>;
+  /**
   * 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
@@ -1469,5 +1850,52 @@ declare const validatorIrToJsonSchema: (validator: ValidatorIR) => JsonSchema;
 * the contract; clients switch on `error.code`. Kept sorted for stable output.
 */
 declare const LUNORA_ERROR_CODES: ReadonlyArray<string>;
+/**
+* Lunora-specific error→solution hints. A small rule table mapping the exact
+* messages Lunora throws — codegen/schema diagnostics, worker-entry export gaps,
+* and the runtime data-layer conflicts — to an actionable fix.
+*
+* This table is the single source of truth shared by every consumer that wants
+* to turn a raw Lunora error into a fix hint: the Vite error overlay
+* (`@lunora/vite`) renders the Markdown in the browser, and the standalone
+* `lunora dev` CLI prints it to the terminal. It lives in `@lunora/codegen`
+* because codegen owns most of the throw sites, so the hints stay next to the
+* code that produces the messages.
+*
+* Matching is on the **message text**. By the time a diagnostic reaches a
+* consumer it has often been flattened to a plain `{ message }` (the overlay
+* pushes codegen errors through `server.hot.send` with `name === "Error"`), so
+* the class identity is gone and the message is the only stable signal.
+*
+* Bodies are Markdown — the overlay renders them; the CLI prints them (lightly
+* de-marked) as-is.
+*/
+/** A resolved hint for a recognized Lunora error. */
+interface LunoraSolution {
+  /** Markdown body shown under the header. */
+  body: string;
+  /** Short header for the solution. */
+  header: string;
+  /** Stable id (used in DEBUG logs and tests). */
+  id: string;
+}
+/** A single error→solution rule: a {@link LunoraSolution} plus its matcher. */
+interface LunoraSolutionRule extends LunoraSolution {
+  /** True when this rule recognizes the error message. */
+  test: (message: string) => boolean;
+}
+/**
+* The rules, ordered most- to least-specific: the dev-time codegen/schema rules
+* come first because they're the errors a developer hits while editing
+* `lunora/`, then the runtime data-layer conflicts that surface from the worker.
+* The first matching rule (in array order) wins.
+*/
+declare const LUNORA_SOLUTION_RULES: ReadonlyArray<LunoraSolutionRule>;
+/**
+* Find the first Lunora solution whose rule matches `message`, or `undefined`
+* if none recognize it. Consumers turn the returned Markdown into their own
+* presentation (overlay panel, terminal hint, …).
+*/
+declare const findLunoraSolution: (message: string) => LunoraSolution | undefined;
 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 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, 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 { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, LUNORA_SOLUTION_RULES, type LunoraSolution, type LunoraSolutionRule, MUTATORS_FILENAME, type MaskProcedureIR, type MigrationIR, type MutatorIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, SHAPES_FILENAME, 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, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverMutators, discoverNondeterministicCalls, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverShapes, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, findLunoraSolution, formatAdvisories, lintSchema, parseSchemaSnapshot, refreshCodegenProject, runCodegen, schemaFromIr, serializeSchemaSnapshot, validatorIrToJsonSchema };