@lunora/codegen 1.0.0-alpha.81 → 1.0.0-alpha.83

package/dist/index.d.mts

@@ -1,10 +1,10 @@
 import { AdvisorExportSink, AdvisorGeoIndexUsage, AdvisorNotifyCall, AdvisorNotifyConfig, Finding, LintContext, AdvisorProcedureProtection } from '@lunora/advisor';
 export type { Finding } from '@lunora/advisor';
+import '@lunora/platform';
+import { Project, Node } from 'ts-morph';
 import { LunoraError } from '@lunora/errors';
 export { MESSAGE_SOLUTIONS as LUNORA_SOLUTION_RULES, type Solution as LunoraSolution, type SolutionRule as LunoraSolutionRule, findSolutionByMessage as findLunoraSolution } from '@lunora/errors';
-import { Node, Project } from 'ts-morph';
 import { StudioFeaturesResult } from '@lunora/shard-engine';
-import '@lunora/platform';
 import { Schema } from '@lunora/server';
 import { JsonSchema } from '@lunora/values';
 /**
@@ -1140,22 +1140,31 @@ interface HttpRouteIR {
  * pass straight through to the advisor without conversion.
  */
 interface ProcedureMiddlewareIR {
-  /** `true` when the handler (or a helper inside it) references `ctx.mail` / `ctx.email`. */
-  callsMail: boolean;
+  /**
+   * `true` when the handler body could be read statically — an inline function
+   * expression/arrow, or a same-file identifier resolved to one. `false` for a
+   * genuinely cross-file handler (an imported function, or an identifier that
+   * doesn't resolve in this file), in which case every behavioural fact below
+   * is `undefined` rather than a false "not observed" — the feeder never saw
+   * the body, so it has nothing to report.
+   */
+  analyzableBody: boolean;
+  /** `true` when the handler (or a helper inside it) references `ctx.mail` / `ctx.email`. `undefined` when `analyzableBody` is `false`. */
+  callsMail?: boolean;
   /** `true` when the handler emits a structured observability event (`ctx.log` / `ctx.span` / `ctx.trace`). */
-  emitsEvent: boolean;
+  emitsEvent?: boolean;
   /** `true` when a `// lunora-advisor-exempt` directive sits above the export. */
   exempt: boolean;
   /** The `-- reason` from that directive, or `""`. */
   exemptReason: string;
   /** Export binding name of the procedure (e.g. `signUp`). */
   exportName: string;
-  /** `true` when the handler fans work out to a privileged, cost-bearing dispatch surface (scheduler `runAfter`/`runAt`, a queue producer send, or a workflow create). Feeds the privileged-fanout lint. */
-  fanOut: boolean;
+  /** `true` when the handler fans work out to a privileged, cost-bearing dispatch surface (scheduler `runAfter`/`runAt`, a queue producer send, or a workflow create). Feeds the privileged-fanout lint. `undefined` when `analyzableBody` is `false`. */
+  fanOut?: boolean;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** `true` when the handler wraps work in `try`/`catch`. */
-  handlesErrors: boolean;
+  handlesErrors?: boolean;
   /**
    * `true` when the procedure declares an email-shaped argument (`email`,
    * `emailAddress`, `userEmail`, …), `false` when it provably declares none,
@@ -1169,19 +1178,19 @@ interface ProcedureMiddlewareIR {
   hasEmailArg?: boolean;
   kind: "action" | "mutation" | "query";
   /** `true` when the handler reaches an outbound surface (`ctx.fetch`, mail, queues, storage, sql, ai, …) that can fail. */
-  reachesOutbound: boolean;
+  reachesOutbound?: boolean;
   /** `true` when the handler runs any AI generation, bounded or not. */
-  runsAiGeneration: boolean;
+  runsAiGeneration?: boolean;
   /** `true` when the handler throws a bare `new Error(...)` rather than a coded `LunoraError`. */
-  throwsBareError: boolean;
-  /** `true` when the handler runs an AI generation (`generateText`/`streamText`/`generateObject`/`streamObject`) with no `maxOutputTokens` bound in its config literal. Feeds the `ai_unbounded_generation_public` lint. */
-  unboundedAiGeneration: boolean;
+  throwsBareError?: boolean;
+  /** `true` when the handler runs an AI generation (`generateText`/`streamText`/`generateObject`/`streamObject`) with no `maxOutputTokens` bound in its config literal. Feeds the `ai_unbounded_generation_public` lint. `undefined` when `analyzableBody` is `false`. */
+  unboundedAiGeneration?: boolean;
   /** `true` when the chain carries `.use(verifyTurnstile(...))` or a `protectPublic({ captcha })` bundle. */
   usesCaptcha: boolean;
   /** `true` when the chain carries `.use(emailGateMiddleware(...))` (`@lunora/auth`). Feeds the `signup_mutation_without_disposable_gating` lint. */
   usesEmailGate: boolean;
-  /** `true` when the handler calls `ctx.db.insertManyUnsafe(...)`, bypassing validators and triggers. Feeds the `insert_many_unsafe_user_data` lint. */
-  usesInsertManyUnsafe: boolean;
+  /** `true` when the handler calls `ctx.db.insertManyUnsafe(...)`, bypassing validators and triggers. Feeds the `insert_many_unsafe_user_data` lint. `undefined` when `analyzableBody` is `false`. */
+  usesInsertManyUnsafe?: boolean;
   /** `true` when the chain carries `.use(mask(...))`. */
   usesMask: boolean;
   /** `true` when the chain carries `.use(rateLimit(...))` or a `protectPublic({ rateLimit })` bundle. */
@@ -1190,8 +1199,8 @@ interface ProcedureMiddlewareIR {
   usesRls: boolean;
   /** `"internal"` for `internalQuery` / `internalMutation` / `internalAction`. */
   visibility: "internal" | "public";
-  /** `true` when the handler inserts into a user/session/account-shaped table. */
-  writesUserTable: boolean;
+  /** `true` when the handler inserts into a user/session/account-shaped table. `undefined` when `analyzableBody` is `false`. */
+  writesUserTable?: boolean;
 }
 /**
  * Per-procedure argument-validator snapshot, produced by the
@@ -1374,6 +1383,14 @@ interface StorageKeyAccessIR {
   line: number;
   /** The bucket method invoked with the arg-derived key, e.g. `get` / `put` / `delete` / `download`. */
   method: string;
+  /**
+   * Visibility of the enclosing procedure. `internal` procedures have no
+   * untrusted caller by construction — see `owner_field_from_args_not_auth`'s
+   * identical split — so `storage_key_from_user_args` drops the finding to
+   * INFO rather than ERROR there. `undefined` when the access sits outside any
+   * registered procedure the feeder could attribute it to.
+   */
+  visibility?: "internal" | "public";
 }
 /**
  * One `ctx.containers.<exportName>.get(name, …)` call whose instance key is derived
@@ -2040,1152 +2057,1184 @@ declare const lintSchema: (options: LintSchemaOptions) => Finding[];
  */
 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. A `LunoraError` subclass (`code: "CODEGEN_DIAGNOSTIC"`); the `file`,
- * `line`, and `column` properties (also passed through as the base `loc`) mirror
- * what Vite's error-overlay `loc` field expects so the browser can display the
- * exact spot.
+ * The canonical capability list. **Order is load-bearing** for the `emit-app.ts`
+ * long-tail: the fluent methods are emitted in the order the `appMethod`-bearing
+ * rows appear here, so this array is ordered to reproduce the original
+ * `LONG_TAIL` sequence (ai, analytics, browser, hyperdrive, images, kv, payment,
+ * r2sql, vectors). The `serverCtxField` rows are referenced by name in the ctx
+ * interface templates, so their order here is not output-affecting.
  */
-declare class CodegenDiagnosticError extends LunoraError {
-  readonly column: number;
-  readonly file: string;
-  readonly line: number;
-  constructor(message: string, file: string, line: number, column: number);
-}
+declare const CAPABILITY_ROWS: readonly [{
+  readonly contextProperty: "access";
+  readonly key: "access";
+  readonly moduleSpecifier: "@lunora/cloudflare-access";
+}, {
+  readonly appMethod: {
+    readonly configKey: "ai";
+    readonly doc: "Override the Workers AI binding backing `ctx.ai` (defaults to `env.AI`).";
+    readonly method: "ai";
+  };
+  readonly contextProperty: "ai";
+  readonly key: "ai";
+  readonly moduleSpecifier: "@lunora/ai";
+}, {
+  readonly appMethod: {
+    readonly configKey: "analytics";
+    readonly doc: "Override the Analytics Engine dataset backing `ctx.analytics` (defaults to `env.ANALYTICS`).";
+    readonly method: "analytics";
+  };
+  readonly contextProperty: "analytics";
+  readonly key: "analytics";
+  readonly moduleSpecifier: "@lunora/bindings/analytics";
+  readonly serverCtxField: {
+    readonly field: "\n    /** Analytics Engine telemetry sink. Fire-and-forget and sampled; do not read it back in-handler. */\n    readonly analytics: import(\"@lunora/bindings/analytics\").AnalyticsClient;";
+    readonly tier: "every";
+  };
+}, {
+  readonly appMethod: {
+    readonly configKey: "browser";
+    readonly doc: "Override the Browser Rendering binding backing `ctx.browser` (defaults to `env.BROWSER`).";
+    readonly method: "browser";
+  };
+  readonly contextProperty: "browser";
+  readonly key: "browser";
+  readonly moduleSpecifier: "@lunora/browser";
+  readonly serverCtxField: {
+    readonly field: "\n    /** Browser Rendering (screenshots/PDF/scrape). Non-deterministic — available only in actions. */\n    readonly browser: import(\"@lunora/browser\").Browser;";
+    readonly tier: "action";
+  };
+}, {
+  readonly contextProperty: "containers";
+  readonly key: "container";
+  readonly moduleSpecifier: "@lunora/container";
+}, {
+  readonly contextProperty: "flags";
+  readonly key: "flags";
+  readonly moduleSpecifier: "@lunora/flags";
+}, {
+  readonly appMethod: {
+    readonly configKey: "sql";
+    readonly doc: "Wire the Hyperdrive SQL client backing `ctx.sql` — build it with `createHyperdrive` + `fromPostgresJs`/`fromNodePg`/`fromMysql2`.";
+    readonly method: "hyperdrive";
+  };
+  readonly contextProperty: "sql";
+  readonly key: "hyperdrive";
+  readonly moduleSpecifier: "@lunora/hyperdrive";
+  readonly serverCtxField: {
+    readonly field: "\n    /**\n     * External database access via Hyperdrive. Non-deterministic — available only in actions. Writes here are NOT tracked by Lunora live queries; subscriptions will not re-run on external DB changes.\n     */\n    readonly sql: import(\"@lunora/hyperdrive\").SqlClient;";
+    readonly tier: "action";
+  };
+}, {
+  readonly appMethod: {
+    readonly configKey: "images";
+    readonly doc: "Override the Images binding backing `ctx.images` (defaults to `env.IMAGES`).";
+    readonly method: "images";
+  };
+  readonly contextProperty: "images";
+  readonly key: "images";
+  readonly moduleSpecifier: "@lunora/bindings/images";
+  readonly serverCtxField: {
+    readonly field: "\n    /** Cloudflare Images transforms (resize/format/optimize). Non-deterministic — available only in actions. */\n    readonly images: import(\"@lunora/bindings/images\").Images;";
+    readonly tier: "action";
+  };
+}, {
+  readonly appMethod: {
+    readonly configKey: "kv";
+    readonly doc: "Override the Workers KV binding backing `ctx.kv` (defaults to `env.KV`).";
+    readonly method: "kv";
+  };
+  readonly contextProperty: "kv";
+  readonly key: "kv";
+  readonly moduleSpecifier: "@lunora/bindings/kv";
+  readonly serverCtxField: {
+    readonly field: "\n    readonly kv: import(\"@lunora/bindings/kv\").Kv;";
+    readonly tier: "every";
+  };
+}, {
+  readonly key: "mail";
+  readonly moduleSpecifier: "@lunora/mail";
+}, {
+  readonly contextProperty: "notify";
+  readonly key: "notify";
+  readonly moduleSpecifier: "@lunora/notify";
+}, {
+  readonly appMethod: {
+    readonly configKey: "payment";
+    readonly doc: "Wire the payment options backing `ctx.payments`.";
+    readonly method: "payment";
+  };
+  readonly contextProperty: "payments";
+  readonly key: "payments";
+  readonly moduleSpecifier: "@lunora/payment";
+}, {
+  readonly appMethod: {
+    readonly configKey: "x402";
+    readonly doc: "Wire the x402 agent-wallet pay rail backing `ctx.x402` — a payment-enabled `fetch` that answers `402` challenges under a mandatory spend policy (ActionCtx-only; spends real funds).";
+    readonly method: "x402";
+  };
+  readonly contextProperty: "x402";
+  readonly key: "x402";
+  readonly moduleSpecifier: "@lunora/x402/pay";
+}, {
+  readonly contextProperty: "pipelines";
+  readonly key: "pipelines";
+  readonly moduleSpecifier: "@lunora/bindings/pipelines";
+  readonly serverCtxField: {
+    readonly field: "\n    /** Pipelines ingestion sink (durable, R2-backed). Fire-and-forget and batched; do not read it back in-handler. */\n    readonly pipelines: import(\"@lunora/bindings/pipelines\").PipelineClient;";
+    readonly tier: "action";
+  };
+}, {
+  readonly appMethod: {
+    readonly configKey: "r2sql";
+    readonly doc: "Wire the R2 SQL client backing `ctx.r2sql` — build it with `createR2Sql({ accountId, apiToken, bucket })` (defaults to env `R2_SQL_TOKEN` / `R2_SQL_ACCOUNT_ID` / `R2_SQL_BUCKET`).";
+    readonly method: "r2sql";
+  };
+  readonly contextProperty: "r2sql";
+  readonly key: "r2sql";
+  readonly moduleSpecifier: "@lunora/bindings/r2sql";
+  readonly serverCtxField: {
+    readonly field: "\n    /**\n     * R2 SQL over Apache Iceberg tables (window functions, DISTINCT, set operations). Non-deterministic — available only in actions. Reads here are NOT tracked by Lunora live queries.\n     */\n    readonly r2sql: import(\"@lunora/bindings/r2sql\").R2SqlClient;";
+    readonly tier: "action";
+  };
+}, {
+  readonly contextProperty: "scheduler";
+  readonly key: "scheduler";
+  readonly moduleSpecifier: "@lunora/scheduler";
+}, {
+  readonly contextProperty: "storage";
+  readonly key: "storage";
+  readonly moduleSpecifier: "@lunora/storage";
+}, {
+  readonly appMethod: {
+    readonly configKey: "vectors";
+    readonly doc: "Wire the Vectorize index map backing `ctx.vectors`.";
+    readonly method: "vectors";
+  };
+  readonly contextProperty: "vectors";
+  readonly key: "vectors";
+  readonly moduleSpecifier: "@lunora/bindings/vectors";
+}, {
+  readonly contextProperty: "workflows";
+  readonly key: "workflows";
+  readonly moduleSpecifier: "@lunora/workflow";
+}];
+/** The literal union of every capability id — the single source of truth for `FeatureUsage`'s keys (so they cannot drift). */
+type CapabilityKey = (typeof CAPABILITY_ROWS)[number]["key"];
+/** The default codegen target — today's behavior, byte-identical goldens. */
+declare const DEFAULT_TARGET = "cloudflare";
 /**
- * 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.
+ * Read `target` from `&lt;projectRoot>/lunora.json`.
  *
- * Message format: `@lunora/codegen: &lt;detail> (&lt;file>:&lt;line>:&lt;column>)`
+ * This lives in `@lunora/codegen` rather than `@lunora/config` — where the rest
+ * of the `lunora.json` reading lives — because `@lunora/config` depends on
+ * `@lunora/codegen`, not the reverse. Putting it there and importing it here
+ * would invert that edge, so config delegates to this instead and there is
+ * still exactly one parser for the key.
  *
- * `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.
+ * Best-effort and deliberately unvalidated: a missing file, malformed JSONC, or
+ * a non-string value all collapse to `undefined`, because those are shape
+ * errors rather than a name the user meant. An unrecognized *name* is returned
+ * as-is so the caller's registry lookup rejects it — swallowing a typo into the
+ * default would ship an app to the wrong provider.
+ * @param projectRoot Directory containing `lunora.json`.
+ * @returns the declared target, or `undefined` when none is usable.
  */
-declare const diagnosticAt: (node: Node, detail: string, meta?: Record<string, unknown>) => CodegenDiagnosticError;
-/** The only file agents may be declared in — mirrors `lunora/workflows.ts`. */
-declare const AGENTS_FILENAME = "agents.ts";
+declare const readProjectTarget: (projectRoot: string) => string | undefined;
 /**
- * Discover every agent the project declares: exported `defineAgent()` calls in
- * `lunora/agents.ts`. Returns `[]` when the file doesn't exist. Only four things
- * are read statically — the optional `name` override (wrangler `workflows[].name`),
- * the optional `publicRun` opt-in (the `agents:agentRun` capability gate), the
- * presence of a `voice` block (which turns on the voice-session Durable Object),
- * and the presence of an `onEmail` mapper (which wires the worker `email()`
- * handler); the rest of the agent config (model / tools / memory / voice models /
- * the `onEmail` closure body) is runtime-only, so codegen never evaluates it.
+ * The target codegen should emit for: an explicit option wins, then
+ * `lunora.json`, then the default.
+ *
+ * `runCodegen` applies this itself so a caller that forgets to pass a target
+ * still emits the surface the project declared. That default matters more than
+ * it looks: a call site that silently omits the target emits the *default*
+ * surface with no diagnostic to notice, and the mismatch only shows up at
+ * runtime on the deployed app.
+ * @param projectRoot Directory containing `lunora.json`.
+ * @param explicit A caller-supplied target, if any.
+ * @returns the resolved target id — not guaranteed to be registered.
  */
-declare const discoverAgents: (project: Project, lunoraDirectory: string) => AgentIR[];
+declare const resolveCodegenTarget: (projectRoot: string, explicit?: string) => string;
 /**
- * Discover `ctx.authApi.&lt;method>(...)` (and bare `authApi.&lt;method>(...)`) calls
- * under the lunora source directory and attribute each to the exported function
- * (and file) performing it. Calls outside an exported declaration are dropped.
+ * The target ids codegen can gate against.
+ *
+ * `@lunora/config`'s driver registry (`deployTargetIds`) used to assert
+ * equality against this — "two id spaces for one concept" — on the theory that
+ * a target with a matrix but no driver "gates a surface nothing can deploy."
+ * Plan 234 found that reasoning incomplete by registering `node` here: a
+ * codegen-gateable target and a deployable target are genuinely different
+ * questions, and a spike/dev-only host answers the first "yes" and the second
+ * "not yet" without that being a bug in either registry. See
+ * `plans/234-node-host-findings.md` for the finding and `@lunora/config`'s
+ * `project-config.test.ts` for where the now-relaxed invariant lives.
+ * @returns the registered matrix ids, sorted.
  */
-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";
+declare const platformMatrixIds: () => ReadonlyArray<string>;
+/** An advisor-style diagnostic about a target's platform capabilities. */
+interface PlatformDiagnostic {
+  /** The codegen capability this concerns, when it is feature-specific. */
+  feature?: CapabilityKey;
+  /** Severity. All three names are errors — each drops or misdirects an emitted surface. */
+  level: "error" | "warn";
+  /** Human-readable explanation of the gap. */
+  message: string;
+  /** The lint id: `platform_unsupported_feature`, `platform_undeclared_feature`, or `platform_unknown_target`. */
+  name: "platform_undeclared_feature" | "platform_unknown_target" | "platform_unsupported_feature";
+  /** How to resolve it. */
+  remediation: string;
+  /** The requested deploy target. */
+  target: string;
+}
 /**
- * Discover every container the project declares: exported `defineContainer()`
- * calls in `lunora/containers.ts`. Returns `[]` when the file doesn't exist.
- * Wrangler-relevant fields (`image`, `instanceType`, `maxInstances`, `name`)
- * must be static literals; runtime-only fields (`env`, `sleepAfter`, …) may be
- * any expression since the generated class imports the definition object.
- */
-declare const discoverContainers: (project: Project, lunoraDirectory: string) => ContainerIR[];
-/**
- * Scan every `.ts` file under `lunoraDir` for `cronJobs()` builder registrations
- * (`crons.interval(...)`, `crons.daily(...)`, `crons.cron(...)`, …) and lift them
- * into {@link CronJobIR}. Schedules are compiled to standard cron expressions;
- * function references are resolved to their `namespace:fn` dispatch path, while a
- * `workflows.NAME` / `agents.NAME` reference (or a bare identifier naming a
- * declared workflow) resolves to a durable workflow start. Names must be unique
- * across the project.
- */
-declare const discoverCrons: (project: Project, lunoraDirectory: string, workflows?: ReadonlyArray<WorkflowIR>, agents?: ReadonlyArray<AgentIR>) => CronJobIR[];
-/** The only file a feature-flag provider may be declared in — mirrors `lunora/queues.ts`. */
-declare const FLAGS_FILENAME = "flags.ts";
-/**
- * Discover the feature-flag provider a project declares in `lunora/flags.ts`.
- * Returns `undefined` when the file doesn't exist (the app has no flags). The
- * read is metadata-only and lenient: codegen wires `ctx.flags` purely from the
- * file's *existence* (`run-codegen.ts`) and imports the real module for the
- * provider value — this IR exists solely so the config layer can reconcile the
- * wrangler `flagship` binding for the Flagship binding-mode provider. Anything
- * it can't read statically degrades to a `custom` provider (no binding), never
- * a thrown error.
- */
-declare const discoverFlags: (project: Project, lunoraDirectory: string) => FlagsIR | undefined;
-/**
- * Scan all .ts files under `lunoraDir` (skipping `_generated/` and `schema.ts`)
- * for top-level `export const x = query/mutation/action({...})` registrations.
- */
-declare const discoverFunctions: (project: Project, lunoraDirectory: string) => FunctionIR[];
-/**
- * Scan all `.ts` files under `lunoraDir` (skipping `_generated/` and `schema.ts`)
- * for `export const x = httpRoute.&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[];
-/**
- * Scan all `.ts` files under `lunoraDir` for top-level
- * `export const x = defineMigration({...})` declarations and lift them into
- * {@link MigrationIR}. `id` must be a static string literal (it's the registry
- * key); `table` is best-effort and left `""` when not a literal.
- */
-declare const discoverMigrations: (project: Project, lunoraDirectory: string) => MigrationIR[];
-/** The only file custom mutators may be declared in — mirrors `lunora/queues.ts`. */
-declare const MUTATORS_FILENAME = "mutators.ts";
-/**
- * Discover every custom mutator the project declares: exported
- * `defineMutator()` calls in `lunora/mutators.ts`. Returns `[]` when the file
- * doesn't exist. The export binding plus the declared `args` / `server` return
- * type are lifted — enough to emit a typed `api.mutators.&lt;name>` reference —
- * while the runtime object still carries the authoritative `server` impl +
- * `handler`, so codegen never evaluates the body. The client `client` impl is
- * split into the browser bundle separately.
- */
-declare const discoverMutators: (project: Project, lunoraDirectory: string) => MutatorIR[];
-/**
- * Discover non-deterministic API calls (`Date.now`, `new Date()`, `Date()`,
- * `Math.random`, `crypto.randomUUID`, `crypto.getRandomValues` — including
- * `globalThis`/`self`/`window`-prefixed receivers — and `fetch`) lexically inside
- * the handler body of every exported `query(...)` / `mutation(...)` registration
- * under the lunora source directory — the `nondeterministic_query_mutation` lint
- * input. `action(...)` (and `stream(...)`) registrations are intentionally
- * skipped: actions run exactly once and may use ambient APIs freely.
- *
- * Traversal is scoped to the handler node (not the whole declaration), mirroring
- * how the auth-api / insert feeders attribute calls — so a call in a sibling
- * helper outside the handler, or in a nested `action(...)` passed elsewhere, is
- * not attributed to the query/mutation. One {@link NondeterministicCallIR} is
- * produced per call site.
- */
-declare const discoverNondeterministicCalls: (project: Project, lunoraDirectory: string) => NondeterministicCallIR[];
-/** The only file a `@lunora/notify` provider may be declared in — mirrors `lunora/flags.ts`. */
-declare const NOTIFY_FILENAME = "notify.ts";
-/**
- * Discover `ctx.notify` / `ctx.push` sends lexically inside the handler body of
- * every exported `query(...)` / `mutation(...)` registration under the lunora
- * source directory — the `notify_send_outside_action` lint input. `action(...)`
- * (and `stream(...)`) registrations are intentionally skipped: a notification
- * send is external I/O that belongs in actions. One {@link AdvisorNotifyCall} is
- * produced per send site.
- */
-declare const discoverNotifyCalls: (project: Project, lunoraDirectory: string) => AdvisorNotifyCall[];
-/**
- * Discover which push channels the project's `lunora/notify.ts` default export
- * (`defineNotify({...})`) wires plus whether any handler sends a push — the
- * `notify_missing_push_config` lint input. Returns `undefined` when the file is
- * absent (the app declares no notify config). The read is metadata-only and
- * lenient (like `discoverFlags`): a `webPush`/`fcm` property's mere presence
- * counts as the channel being wired; a non-literal config degrades to "unwired"
- * rather than throwing.
- */
-declare const discoverNotifyConfig: (project: Project, lunoraDirectory: string) => AdvisorNotifyConfig | undefined;
-/**
- * Discover `ctx.db.query("table")…` reads under the lunora source directory and
- * reduce each to a {@link QueryReadIR}. Only reads that call `.filter()` are
- * returned — an unfiltered read is never a `filter_without_index` candidate, so
- * dropping the rest keeps the lint input small.
+ * 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 discoverQueries: (project: Project, lunoraDirectory: string) => QueryReadIR[];
-/** The only file queues may be declared in — mirrors `lunora/workflows.ts`. */
-declare const QUEUES_FILENAME = "queues.ts";
+declare const SCHEMA_SNAPSHOT_FILENAME = ".lunora-schema.json";
 /**
- * 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.
+ * 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 discoverQueues: (project: Project, lunoraDirectory: string) => QueueIR[];
+declare const createCodegenProject: (lunoraDirectory: string) => Project;
 /**
- * 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.
+ * 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).
  *
- * 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.
+ * 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 discoverR2sqlCalls: (project: Project, lunoraDirectory: string) => R2sqlCallIR[];
-declare const discoverRlsProcedures: (project: Project, lunoraDirectory: string) => RlsProcedureIR[];
+declare const refreshCodegenProject: (project: Project, lunoraDirectory: string) => void;
 /**
- * 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.
+ * 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.
  *
- * 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;
-/**
- * Which sandbox tools a project imports from `@lunora/agent` (main entry or the
- * `/sandbox` subpath), detected by NAMED value import. Drives two things:
- * registering the `sandbox:invoke` dispatcher (either tool) and provisioning the
- * `BROWSER` wrangler binding (`browserTool` — the browser op runs on
- * `ctx.browser` inside the dispatcher).
+ * 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}.
  */
-interface SandboxUsage {
-  /** `import { browserTool } from "@lunora/agent"` (or `/sandbox`) appears in `lunora/`. */
-  usesSandboxBrowser: boolean;
-  /** `import { containerTool } from "@lunora/agent"` (or `/sandbox`) appears in `lunora/`. */
-  usesSandboxContainer: boolean;
+declare const runCodegen: (options: CodegenOptions) => CodegenResult;
+interface CodegenOptions {
+  /**
+   * Which machine-readable API spec(s) to emit into `_generated/`.
+   *
+   * `"openapi"` (the default) writes only `openapi.json` (OpenAPI 3.1; covers
+   * both the RPC functions and `httpRouter()` REST routes). `"openrpc"` writes
+   * only `openrpc.json` (OpenRPC 1.x; the RPC functions only — OpenRPC cannot
+   * represent REST routes). `"both"` writes both files; `"none"` writes neither.
+   *
+   * Regardless of the choice, `CodegenResult.generated.openApi` and `.openRpc`
+   * always carry the rendered string (computation is cheap and pure); only the
+   * on-disk write is gated by this option.
+   */
+  apiSpec?: "both" | "none" | "openapi" | "openrpc";
+  /**
+   * When true, run discovery + emit (so any schema/function parse error
+   * surfaces) but skip writing files to `_generated/`. The returned
+   * `outputDirectory` is still the path that *would* have been written.
+   */
+  dryRun?: boolean;
+  /**
+   * Run the static schema advisor (unindexed FKs, …) during codegen.
+   * Defaults to `true`. When `false`, `CodegenResult.advisories` is empty.
+   * Computed regardless of `dryRun`; codegen never prints them — see
+   * {@link CodegenResult.advisories}.
+   */
+  lint?: boolean;
+  /** Override the lunora subdirectory name. Defaults to `"lunora"`. */
+  lunoraDirectory?: string;
+  /**
+   * Reuse a previously-constructed ts-morph {@link Project} instead of building
+   * a fresh one each run. The caller owns refreshing its source files from disk
+   * (see {@link refreshCodegenProject}) — codegen does not re-read changed files
+   * off an injected Project. Built via {@link createCodegenProject} when absent.
+   * Used by the Vite dev-loop to avoid re-parsing the whole TS program on every
+   * save; omit it (CLI one-shot path) to get the default fresh-Project behaviour.
+   */
+  project?: Project;
+  /** Project root containing the `lunora/` directory. */
+  projectRoot: string;
+  /**
+   * The deploy target codegen tailors the emitted `ctx.*` surface to.
+   * Defaults to `"cloudflare"` — whose capability matrix marks every feature
+   * native or emulated, so the default output is unchanged (byte-identical
+   * goldens). A target that marks a used feature unsupported omits its
+   * `ctx.*` surface and reports it in {@link CodegenResult.platformDiagnostics}.
+   * Only `"cloudflare"` is registered until other per-target `@lunora/platform`
+   * matrices land; an unknown target emits the full surface un-gated and a
+   * `platform_unknown_target` diagnostic.
+   */
+  target?: string;
+  /**
+   * Re-bless the committed schema-drift baseline (`lunora/.lunora-schema.json`)
+   * with the current structural snapshot. The baseline is ALWAYS written on
+   * first capture (when the file is absent); set this to overwrite an existing
+   * one — e.g. after the developer has added the data migration that justifies
+   * a breaking change. Ignored when `dryRun` is true.
+   */
+  updateSchemaBaseline?: boolean;
+  /**
+   * Committed `wrangler.jsonc` `vars` entries that hold plaintext secrets — the
+   * `plaintext_secret_in_wrangler_vars` lint input. Produced by `@lunora/config`
+   * (which reads `wrangler.jsonc`) and threaded through by the CLI / Vite plugin;
+   * codegen only forwards it to the advisor. Absent when no wrangler config is
+   * present or the caller doesn't scan it.
+   */
+  wranglerVariables?: ReadonlyArray<WranglerVariableIR>;
 }
-declare const discoverSandboxUsage: (project: Project, lunoraDirectory: string) => SandboxUsage;
+interface CodegenResult {
+  /**
+   * The normalized advisor evidence the findings were produced from, so a
+   * caller can score it into a health map (`scoreAdvisor`) without re-running
+   * discovery. `undefined` under `lint: false`.
+   *
+   * Deliberately not scored here: the map carries a `generatedAt` stamp, and
+   * codegen's result stays a pure function of the sources.
+   */
+  advisorContext?: LintContext;
+  /**
+   * Static schema advisor findings (e.g. unindexed foreign keys) produced
+   * this run. Empty when `lint` is `false` or the schema is clean. Codegen
+   * does not print these itself — each caller presents them through its own
+   * channel (the CLI logger, the vite overlay, the studio Advisors table).
+   * `formatAdvisories` is exported for a plain multi-line rendering.
+   */
+  advisories: ReadonlyArray<Finding>;
+  /**
+   * Agents discovered from `defineAgent` exports in `lunora/agents.ts` — the
+   * list the config layer reconciles into wrangler's `workflows[]` array (an
+   * agent compiles onto a Cloudflare Workflow). Agents are NOT Durable Objects,
+   * so this adds no binding or migration. Empty when the project declares none.
+   */
+  agents: ReadonlyArray<AgentIR>;
+  /**
+   * Containers discovered from `defineContainer` exports in
+   * `lunora/containers.ts` — the list the config layer reconciles into
+   * wrangler's `containers[]`, `CONTAINER_*` Durable Object bindings, and
+   * migration classes. Empty when the project declares no containers.
+   */
+  containers: ReadonlyArray<ContainerIR>;
+  /**
+   * Deduplicated cron schedules discovered from `cronJobs()` definitions —
+   * the array the vite plugin reconciles into `wrangler.jsonc`'s
+   * `triggers.crons`. Empty when the project declares no crons.
+   */
+  cronTriggers: ReadonlyArray<string>;
+  generated: {
+    /** WorkflowEntrypoint classes for declared agents (`_generated/agents.ts`); `""` (and not written) when no agents are declared. */
+    agents: string;
+    api: string;
+    /** Fluent worker-composition builder (`_generated/app.ts`) — `defineApp()`. Always written. */
+    app: string;
+    /** Partial-replication collection factories (`_generated/collections.ts`); `""` (and not written) unless the project declares shapes and installs `@lunora/db`. */
+    collections: string;
+    /** Container DO classes (`_generated/containers.ts`); `""` (and not written) when no containers are declared. */
+    containers: string;
+    crons: string;
+    dataModel: string;
+    drizzleGlobal: string;
+    drizzleShard: string;
+    functions: string;
+    /** OpenAPI 3.1.0 document (`_generated/openapi.json`), pretty-printed JSON. */
+    openApi: string;
+    /**
+     * OpenAPI document as an importable TS module (`_generated/openapi.ts`) —
+     * `export const openApiSpec`, the worker imports it for
+     * `createWorker({ openApiSpec })`. Same document as `openApi`. Written
+     * alongside `openapi.json` whenever `apiSpec` includes `openapi`.
+     */
+    openApiModule: string;
+    /** OpenRPC 1.x document (`_generated/openrpc.json`), pretty-printed JSON. Always computed; written only when `apiSpec` includes `openrpc`. */
+    openRpc: string;
+    /**
+     * OpenRPC document as an importable TS module (`_generated/openrpc.ts`) —
+     * `export const openRpcSpec`, for `createWorker({ openRpcSpec })`. Same
+     * document as `openRpc`. Written alongside `openrpc.json` whenever
+     * `apiSpec` includes `openrpc`.
+     */
+    openRpcModule: string;
+    /** Push-consumer queue registry (`_generated/queues.ts`); `""` (and not written) when no push queues are declared. */
+    queues: string;
+    /** Project-bound seed client (`_generated/seed.ts`); `""` (and not written) when `@lunora/seed` is not a declared dependency. */
+    seed: string;
+    server: string;
+    shard: string;
+    /** Static vector-index registry (`_generated/vectors.ts`) — `LUNORA_VECTOR_INDEXES`. Empty array body when the schema declares none. */
+    vectors: string;
+    /** WorkflowEntrypoint classes (`_generated/workflows.ts`); `""` (and not written) when no workflows are declared. */
+    workflows: string;
+  };
+  outputDirectory: string;
+  /**
+   * Portability diagnostics for the requested {@link CodegenOptions.target}:
+   * `ctx.*` features the app uses that the target does not support (omitted
+   * from the emitted surface), or an unknown target. Empty for a
+   * fully-supported app on the default Cloudflare target. Presentation is the
+   * caller's job, like {@link CodegenResult.advisories}.
+   */
+  platformDiagnostics: ReadonlyArray<PlatformDiagnostic>;
+  /**
+   * Queues discovered from `defineQueue` exports in `lunora/queues.ts` — the
+   * list the config layer reconciles into wrangler's `queues.producers[]` /
+   * `queues.consumers[]`. Queues are NOT Durable Objects, so this adds no
+   * binding or migration. Empty when the project declares no queues.
+   */
+  queues: ReadonlyArray<QueueIR>;
+  /**
+   * The CURRENT structural schema snapshot computed this run (tables + field
+   * kinds/optionality + indexes/relations/shard mode + declared migration ids).
+   * The pre-deploy drift gate diffs this against the committed baseline read
+   * from {@link CodegenResult.schemaSnapshotPath}. Always present, even on a
+   * `dryRun`.
+   */
+  schemaSnapshot: SchemaSnapshot;
+  /** Absolute path of the committed baseline file (`lunora/.lunora-schema.json`). */
+  schemaSnapshotPath: string;
+  /**
+   * Workflows discovered from `defineWorkflow` exports in
+   * `lunora/workflows.ts` — the list the config layer reconciles into
+   * wrangler's `workflows[]` array. Workflows are NOT Durable Objects, so this
+   * adds no binding or migration. Empty when the project declares no workflows.
+   */
+  workflows: ReadonlyArray<WorkflowIR>;
+}
+/** Deduplicated, sorted names of every ERROR-level advisory in `advisories`. */
+declare const errorAdvisoryNames: (advisories: ReadonlyArray<Pick<Finding, "level" | "name">>) => ReadonlyArray<string>;
+/** Deduplicated, sorted names of every error-level platform diagnostic in `platformDiagnostics`. */
+declare const errorPlatformDiagnosticNames: (platformDiagnostics: ReadonlyArray<Pick<PlatformDiagnostic, "level" | "name">>) => ReadonlyArray<string>;
 /**
- * Load `&lt;projectRoot>/lunora/schema.ts`, find `defineSchema({...})`, and
- * return a structural IR. Throws if the file or call cannot be found.
+ * Convenience read combining both categories from a full {@link CodegenResult}
+ * — the shape the Vite plugin's `buildBlockingMessage` needs, which (unlike
+ * the CLI's `lunora codegen`/`lunora deploy`) folds ERROR-level advisories and
+ * platform diagnostics into a single blocking message with no strict/CI
+ * opt-out.
  */
-declare const 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";
+declare const describeErrorLevelFindings: (result: Pick<CodegenResult, "advisories" | "platformDiagnostics">) => {
+  advisoryNames: ReadonlyArray<string>;
+  platformDiagnosticNames: ReadonlyArray<string>;
+};
 /**
- * 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.
+ * An error thrown by codegen discovery when the user's schema or function
+ * source has a structural problem that can be pinpointed to a specific source
+ * location. A `LunoraError` subclass (`code: "CODEGEN_DIAGNOSTIC"`); the `file`,
+ * `line`, and `column` properties (also passed through as the base `loc`) mirror
+ * what Vite's error-overlay `loc` field expects so the browser can display the
+ * exact spot.
  */
-declare const discoverShapes: (project: Project, lunoraDirectory: string) => ShapeIR[];
+declare class CodegenDiagnosticError extends LunoraError {
+  readonly column: number;
+  readonly file: string;
+  readonly line: number;
+  constructor(message: string, file: string, line: number, column: number);
+}
 /**
- * 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.
+ * 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 discoverStorageRulesMetadata: (project: Project, lunoraDirectory: string) => StorageRulesMetadataIR;
-/** The only file workflows may be declared in — mirrors `lunora/containers.ts`. */
-declare const WORKFLOWS_FILENAME = "workflows.ts";
+declare const diagnosticAt: (node: Node, detail: string, meta?: Record<string, unknown>) => CodegenDiagnosticError;
+/** The only file agents may be declared in — mirrors `lunora/workflows.ts`. */
+declare const AGENTS_FILENAME = "agents.ts";
 /**
- * Discover every workflow the project declares: exported `defineWorkflow()`
- * calls in `lunora/workflows.ts`. Returns `[]` when the file doesn't exist. The
- * only wrangler-relevant literal is the optional `name` override; the workflow
- * body is runtime-only, so codegen never evaluates it.
+ * Discover every agent the project declares: exported `defineAgent()` calls in
+ * `lunora/agents.ts`. Returns `[]` when the file doesn't exist. Only four things
+ * are read statically — the optional `name` override (wrangler `workflows[].name`),
+ * the optional `publicRun` opt-in (the `agents:agentRun` capability gate), the
+ * presence of a `voice` block (which turns on the voice-session Durable Object),
+ * and the presence of an `onEmail` mapper (which wires the worker `email()`
+ * handler); the rest of the agent config (model / tools / memory / voice models /
+ * the `onEmail` closure body) is runtime-only, so codegen never evaluates it.
  */
-declare const 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;
+declare const discoverAgents: (project: Project, lunoraDirectory: string) => AgentIR[];
 /**
- * Emit `_generated/api.ts` — the typed `api.*` registry (public functions), the
- * `internal.*` registry, and (when the project declares them) the typed
- * `workflows.*` / `agents.*` scheduler-target reference objects. `api`/`internal` are the same `anyApi` proxy
- * at runtime (the `__lunoraRef` is identical); visibility is enforced
- * server-side at dispatch, not in the reference. Splitting the *types* keeps
- * internal functions off the client-facing `api` surface.
+ * 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.
  */
-interface EmitApiOptions {
-  agents?: ReadonlyArray<AgentIR>;
-  functions: ReadonlyArray<FunctionIR>;
-  /** Typed REST routes; only `.stream()` (SSE) routes emit a `httpStreams.*` reference. */
-  httpRoutes?: ReadonlyArray<HttpRouteIR>;
-  /** Custom mutators (`lunora/mutators.ts`) — emitted as `api.mutators.*` so a client `serverRef` is compile-checked. */
-  mutators?: ReadonlyArray<MutatorIR>;
-  useUmbrella?: boolean;
-  workflows?: ReadonlyArray<WorkflowIR>;
-}
-declare const emitApi: (options: EmitApiOptions) => string;
+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";
 /**
- * Emit `_generated/collections.ts` — a typed TanStack DB binding per `defineShape`
- * in `lunora/shapes.ts` (the local-first partial-replication surface).
- *
- * Each shape emits **two** entry points.
- *
- * `&lt;shape>CollectionOptions(options)` is the composable form: it returns the full
- * `LunoraCollectionOptions` — `config` for `createCollection`, plus `checkpoints`
- * (which `bindMutators` gates optimistic overlays on) and `scope`. This is what an app
- * with custom mutators needs, and what the old single-factory form made impossible: it
- * built the collection internally and dropped `checkpoints` on the floor, so there was
- * no way to wire mutators to the collection codegen produced.
- *
- * `&lt;shape>Collection(options)` is the convenience form for a read-only collection: it
- * returns `{ checkpoints, collection, scope }` rather than a bare `Collection`, so the
- * sync controls stay reachable even from the short path.
- *
- * Both are typed: `args` comes from the shape's own validators (a parameterless
- * shape takes none), rows resolve to `Doc&lt;"table">` when the shape names its table
- * with a literal, and `shardKey` / `getKey` / `load` / `onError` / `checkpoints` are
- * all threadable — a sharded table needs `shardKey` for its watermark to land in the
- * right bucket, and a server-minted `_id` that differs from the app's natural key
- * needs `getKey`.
- *
- * Returns `""` (so `writeIfPresent` skips the file) unless the project both
- * declares shapes AND installs `@lunora/db` — the add-on that ships
- * `lunoraCollectionOptions`. `@lunora/db` stays a scoped install even under the
- * `lunorash` umbrella (an opt-in add-on, like `@lunora/auth`), so its import is
- * always `@lunora/db/collections`; only the in-umbrella `@lunora/client` import
- * is remapped to `lunorash/client`.
+ * 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 emitCollections: (shapes: ReadonlyArray<ShapeIR>, hasDatabase: boolean, useUmbrella?: boolean) => string;
-interface EmitServerOptions {
-  /** Agents declared via `defineAgent` exports — wires the typed `ctx.agents` producers onto Mutation/Action contexts. */
-  agents?: ReadonlyArray<AgentIR>;
-  containers?: ReadonlyArray<ContainerIR>;
-  /**
-   * The single `defineEnv(...)` contract declared in `lunora/env.ts`. When
-   * present, `ctx.env` is typed as the validated `InferEnv` shape (recovered
-   * via `ReturnType` over the accessor's `typeof`). `undefined` leaves `ctx.env`
-   * the base optional binding record — byte-identical to today.
-   */
-  env?: EnvIR;
-  /**
-   * A `lunora/` source reads `ctx.access` — wires the verified Cloudflare Access
-   * facade (`@lunora/cloudflare-access/context`) onto every ctx. Distinct from
-   * `emitApp`'s `hasAccess` (which gates the worker's `.access()` resolveIdentity
-   * method); this one gates the per-request `ctx.access` read surface.
-   */
-  hasAccessFacade?: boolean;
-  hasAi?: boolean;
-  /** A `lunora/` source uses `@lunora/bindings/analytics` / `ctx.analytics` — wires the write helper onto every ctx. */
-  hasAnalytics?: boolean;
-  /** 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/bindings/images` / `ctx.images` — wires `ctx.images` onto ActionCtx only. */
-  hasImages?: boolean;
-  /** A `lunora/` source uses `@lunora/bindings/kv` / `ctx.kv` — wires `ctx.kv` onto every ctx. */
-  hasKv?: boolean;
-  /** The project declares `lunora/notify.ts` — wires `ctx.notify` + its `ctx.push` alias (`@lunora/notify`) onto every ctx. */
-  hasNotify?: boolean;
-  hasPayments?: boolean;
-  /** A `lunora/` source uses `@lunora/bindings/pipelines` / `ctx.pipelines` — wires `ctx.pipelines` onto ActionCtx only. */
-  hasPipelines?: boolean;
-  /** A `lunora/` source uses `@lunora/bindings/r2sql` / `ctx.r2sql` — wires `ctx.r2sql` onto ActionCtx only. */
-  hasR2sql?: boolean;
-  /** A `lunora/` source uses `@lunora/x402/pay` / `ctx.x402` — wires the agent-wallet pay rail onto ActionCtx only. */
-  hasX402?: boolean;
-  /**
-   * The single `defineIdentity(...)` claim contract declared in
-   * `lunora/identity.ts` (Plan 080). When present, `ctx.auth.getIdentity()`,
-   * the RLS policy `ctx.auth.identity`, and the shard-authorization hooks
-   * narrow to the declared shape (recovered via `InferIdentity` over the
-   * contract's `typeof`). `undefined` keeps the identity an untyped bag —
-   * byte-identical to today.
-   */
-  identity?: IdentityIR;
-  /** Queues declared via `defineQueue` exports — wires the typed `ctx.queues` producers onto Mutation/Action contexts. */
-  queues?: ReadonlyArray<QueueIR>;
-  schema?: SchemaIR;
-  storageRuleBuckets?: ReadonlyArray<string>;
-  /** The project depends on the `lunora` umbrella — import base packages via its subpaths. */
-  useUmbrella?: boolean;
-  workflows?: ReadonlyArray<WorkflowIR>;
-}
-declare const emitServer: ({ agents, containers, env, hasAccessFacade, hasAi, hasAnalytics, hasBrowser, hasFlags, hasHyperdrive, hasImages, hasKv, hasNotify, hasPayments, hasPipelines, hasR2sql, hasX402, identity, queues, schema, storageRuleBuckets, useUmbrella, workflows }?: EmitServerOptions) => string;
-interface EmitFunctionsOptions {
-  agents?: ReadonlyArray<AgentIR>;
-  functions: ReadonlyArray<FunctionIR>;
-  migrations?: ReadonlyArray<MigrationIR>;
-  mutators?: ReadonlyArray<MutatorIR>;
-  shapes?: ReadonlyArray<ShapeIR>;
-  /** Import of a sandbox tool (`browserTool`/`containerTool`) auto-registers the `sandbox:invoke` action. */
-  usesSandbox?: boolean;
-  useUmbrella?: boolean;
-}
-declare const emitFunctions: (options: EmitFunctionsOptions) => string;
+declare const discoverContainers: (project: Project, lunoraDirectory: string) => ContainerIR[];
 /**
- * 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).
+ * Scan every `.ts` file under `lunoraDir` for `cronJobs()` builder registrations
+ * (`crons.interval(...)`, `crons.daily(...)`, `crons.cron(...)`, …) and lift them
+ * into {@link CronJobIR}. Schedules are compiled to standard cron expressions;
+ * function references are resolved to their `namespace:fn` dispatch path, while a
+ * `workflows.NAME` / `agents.NAME` reference (or a bare identifier naming a
+ * declared workflow) resolves to a durable workflow start. Names must be unique
+ * across the project.
  */
-declare const emitContainers: (containers: ReadonlyArray<ContainerIR>, jurisdiction?: JurisdictionIR) => string;
+declare const discoverCrons: (project: Project, lunoraDirectory: string, workflows?: ReadonlyArray<WorkflowIR>, agents?: ReadonlyArray<AgentIR>) => CronJobIR[];
+/** The only file a feature-flag provider may be declared in — mirrors `lunora/queues.ts`. */
+declare const FLAGS_FILENAME = "flags.ts";
 /**
- * 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).
+ * 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 emitWorkflows: (workflows: ReadonlyArray<WorkflowIR>) => string;
+declare const discoverFlags: (project: Project, lunoraDirectory: string) => FlagsIR | undefined;
 /**
- * Emit `_generated/agents.ts` — one `WorkflowEntrypoint` class per `defineAgent`
- * export, each a thin subclass of `LunoraWorkflow` (`@lunora/workflow/do`)
- * constructed with the compiled agent tool-loop (`compileAgentWorkflow`). Like
- * `_generated/workflows.ts`, the worker entry must re-export these classes:
- * wrangler requires every `workflows[].class_name` to be exported by the
- * deployed worker. Returns "" when the project declares no agents (the file is
- * not written then).
+ * Scan all .ts files under `lunoraDir` (skipping `_generated/` and `schema.ts`)
+ * for top-level `export const x = query/mutation/action({...})` registrations.
  */
-declare const emitAgents: (agents: ReadonlyArray<AgentIR>) => string;
-interface EmitShardOptions {
-  advisories?: ReadonlyArray<Finding>;
-  /** Every declared procedure — the health map's denominator, served via `getAdvisorProcedures`. */
-  advisorProcedures?: ReadonlyArray<AdvisorProcedureProtection>;
-  /** Agents declared via `defineAgent` exports in `lunora/agents.ts` — wires the typed `ctx.agents` producers. */
-  agents?: ReadonlyArray<AgentIR>;
-  containers?: ReadonlyArray<ContainerIR>;
-  /** The single `defineEnv(...)` contract declared in `lunora/env.ts` — applies the accessor to the worker `env` to populate `ctx.env`. */
-  env?: EnvIR;
-  /** Statically-discovered `ctx.flags.&lt;type>("key")` reads — the studio Flags page + reactive evaluation iterate these. */
-  flagKeys?: ReadonlyArray<{
-    key: string;
-    type: "boolean" | "number" | "object" | "string";
-  }>;
-  /** A `lunora/` source reads `ctx.access` — wires the verified Cloudflare Access facade onto every ctx. */
-  hasAccessFacade?: boolean;
-  hasAi?: boolean;
-  /** A `lunora/` source reads `ctx.analytics` — wires the Analytics Engine write helper onto every ctx. */
-  hasAnalytics?: boolean;
-  /** A `lunora/` source reads `ctx.browser` — wires `ctx.browser` onto the ActionCtx only. */
-  hasBrowser?: boolean;
-  /** The project declares `lunora/flags.ts` — wires `ctx.flags` (OpenFeature) onto every ctx. */
-  hasFlags?: boolean;
-  /** A `lunora/` source reads `ctx.sql` (Hyperdrive) — wires `ctx.sql` onto the ActionCtx only. */
-  hasHyperdrive?: boolean;
-  /** A `lunora/` source reads `ctx.images` — wires `ctx.images` onto the ActionCtx only. */
-  hasImages?: boolean;
-  /** A `lunora/` source reads `ctx.kv` — wires `ctx.kv` onto every ctx. */
-  hasKv?: boolean;
-  /** The project declares `lunora/notify.ts` — wires `ctx.notify` + its `ctx.push` alias (`@lunora/notify`) onto every ctx. */
-  hasNotify?: boolean;
-  hasPayments?: boolean;
-  /** A `lunora/` source reads `ctx.pipelines` — wires `ctx.pipelines` onto the ActionCtx only. */
-  hasPipelines?: boolean;
-  /** A `lunora/` source reads `ctx.r2sql` (R2 SQL) — wires `ctx.r2sql` onto the ActionCtx only. */
-  hasR2sql?: boolean;
-  /** A `lunora/` source reads `ctx.x402` — wires the agent-wallet pay rail onto the ActionCtx only. */
-  hasX402?: boolean;
-  maskMetadata?: MaskMetadataIR;
-  /** Custom mutators declared via `defineMutator` in `lunora/mutators.ts` — wires the `isCustomMutator` push-protocol override. */
-  mutators?: ReadonlyArray<MutatorIR>;
-  /** Queues declared via `defineQueue` exports in `lunora/queues.ts` — wires the typed `ctx.queues` producers. */
-  queues?: ReadonlyArray<QueueIR>;
-  rlsMetadata?: RlsMetadataIR;
-  schema: SchemaIR;
-  /**
-   * The structural snapshot the pre-deploy drift gate diffs against, threaded
-   * in so the emitted DO records it in `__lunora_schema_history` on cold start
-   * (plan 200 — the Studio's schema-version timeline). Optional so an emitter
-   * caller that has no snapshot (tests, fixtures) emits the pre-ledger shape
-   * unchanged.
-   */
-  schemaSnapshot?: SchemaSnapshot;
-  /** Replication shapes declared via `defineShape` in `lunora/shapes.ts` — wires the `resolveShape` subscription override. */
-  shapes?: ReadonlyArray<ShapeIR>;
-  storageRules?: StorageRulesMetadataIR;
-  studioFeatures?: StudioFeaturesResult;
-  /** The project depends on the `lunora` umbrella — import base packages via its subpaths. */
-  useUmbrella?: boolean;
-  workflows?: ReadonlyArray<WorkflowIR>;
-}
-declare const emitShard: ({ advisories, advisorProcedures, agents, containers, env, flagKeys, hasAccessFacade, hasAi, hasAnalytics, hasBrowser, hasFlags, hasHyperdrive, hasImages, hasKv, hasNotify, hasPayments, hasPipelines, hasR2sql, hasX402, maskMetadata, mutators, queues, rlsMetadata, schema, schemaSnapshot, shapes, storageRules, studioFeatures, useUmbrella, workflows }: EmitShardOptions) => string;
+declare const discoverFunctions: (project: Project, lunoraDirectory: string) => FunctionIR[];
 /**
- * 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.
+ * 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 emitDrizzleSchema: (schema: SchemaIR, useUmbrella?: boolean) => {
-  global: string;
-  shard: string;
-};
+declare const discoverHttpRoutes: (project: Project, lunoraDirectory: string) => HttpRouteIR[];
 /**
- * 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.
+ * 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 emitCrons: (crons: ReadonlyArray<CronJobIR>) => string;
+declare const discoverInserts: (project: Project, lunoraDirectory: string) => InsertWriteIR[];
 /**
- * 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.
+ * 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 emitVectors: (vectorIndexes: ReadonlyArray<VectorIndexIR>) => string;
+declare const discoverMaskProcedures: (project: Project, lunoraDirectory: string) => MaskProcedureIR[];
 /**
- * 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.
+ * 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 emitWranglerCronTriggers: (crons: ReadonlyArray<CronJobIR>) => string[];
-/** Which capability methods the generated `defineApp` builder exposes — one flag per package-backed feature the app actually uses. */
-interface EmitAppOptions {
-  /**
-   * Inbound-email agents (`defineAgent({ onEmail })`) → wire the worker's
-   * top-level `email()` handler to `dispatchAgentEmail(...)` (from
-   * `@lunora/agent/inbound`), so received mail starts a durable run. Empty/absent
-   * ⇒ no wiring, byte-identical output for email-free (and agent-free) projects.
-   */
-  emailAgents?: ReadonlyArray<{
-    bindingName: string;
-    exportName: string;
-  }>;
-  /** App depends on `@lunora/cloudflare-access` → emit `.access()` (wire the Cloudflare Access `resolveIdentity`, composed ahead of `@lunora/auth` when both are present). */
-  hasAccess: boolean;
-  /** App uses `@lunora/ai` / `ctx.ai` → emit `.ai()` (override the Workers AI binding backing `ctx.ai`). */
-  hasAi: boolean;
-  /** App uses `@lunora/bindings/analytics` / `ctx.analytics` → emit `.analytics()` (override the dataset backing `ctx.analytics`). */
-  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/bindings/images` / `ctx.images` → emit `.images()`. */
-  hasImages: boolean;
-  /** App uses `@lunora/bindings/kv` / `ctx.kv` → emit `.kv()`. */
-  hasKv: boolean;
-  /** App declares `lunora/notify.ts` (`@lunora/notify`) → wire `options.notifySubscriptionStore` so the studio Notifications page can read registered devices. */
-  hasNotify: boolean;
-  /** App uses `@lunora/payment` / `ctx.payments` → emit `.payment()`. */
-  hasPayments: boolean;
-  /** App 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). */
-  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;
-  /** App uses `@lunora/x402/pay` / `ctx.x402` → emit `.x402()` (wire the agent-wallet pay rail). */
-  hasX402: boolean;
-  /** The single `defineIdentity(...)` contract in `lunora/identity.ts` (Plan 080) → import it as a VALUE and wire `options.identity`, so the runtime trust boundary validates every resolved identity before it becomes `ctx.auth`. `undefined` ⇒ no wiring, byte-identical output. */
-  identity?: IdentityIR;
-  /** Schema declares `.jurisdiction("…")` → pin every DO the worker reaches (shards, fan-out, scheduler, containers) to the Cloudflare data-residency jurisdiction. */
-  jurisdiction?: JurisdictionIR;
-  /** Project depends on the unscoped `lunorash` umbrella → import the runtime via `lunorash/runtime` instead of `@lunora/runtime`. */
-  useUmbrella: boolean;
-  /**
-   * Voice-enabled agents (`defineAgent({ voice: … })`) → wire
-   * `options.voiceAgents`, mapping each agent's export name to its `VOICE_*`
-   * Durable Object namespace binding so the runtime exposes
-   * `/_lunora/voice/&lt;exportName>`. Empty/absent ⇒ no wiring, byte-identical
-   * output for voice-free (and agent-free) projects.
-   */
-  voiceAgents?: ReadonlyArray<{
-    bindingName: string;
-    exportName: string;
-  }>;
-  /** An OpenAPI spec is emitted (`openapi.ts`) → wire `openApiSpec` into the worker. */
-  wantsOpenApi: boolean;
-  /** An OpenRPC spec is emitted (`openrpc.ts`) → wire `openRpcSpec` into the worker. */
-  wantsOpenRpc: boolean;
-}
+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";
 /**
- * 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.
+ * Discover every custom mutator the project declares: exported
+ * `defineMutator()` calls in `lunora/mutators.ts`. Returns `[]` when the file
+ * doesn't exist. The export binding plus the declared `args` / `server` return
+ * type are lifted — enough to emit a typed `api.mutators.&lt;name>` reference —
+ * while the runtime object still carries the authoritative `server` impl +
+ * `handler`, so codegen never evaluates the body. The client `client` impl is
+ * split into the browser bundle separately.
  */
-declare const 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;
-}
+declare const discoverMutators: (project: Project, lunoraDirectory: string) => MutatorIR[];
 /**
- * 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.
+ * 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.
  *
- * 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).
+ * Traversal is scoped to the handler node (not the whole declaration), mirroring
+ * how the auth-api / insert feeders attribute calls — so a call in a sibling
+ * helper outside the handler, or in a nested `action(...)` passed elsewhere, is
+ * not attributed to the query/mutation. One {@link NondeterministicCallIR} is
+ * produced per call site.
+ */
+declare const discoverNondeterministicCalls: (project: Project, lunoraDirectory: string) => NondeterministicCallIR[];
+/** The only file a `@lunora/notify` provider may be declared in — mirrors `lunora/flags.ts`. */
+declare const NOTIFY_FILENAME = "notify.ts";
+/**
+ * Discover `ctx.notify` / `ctx.push` sends lexically inside the handler body of
+ * every exported `query(...)` / `mutation(...)` registration under the lunora
+ * source directory — the `notify_send_outside_action` lint input. `action(...)`
+ * (and `stream(...)`) registrations are intentionally skipped: a notification
+ * send is external I/O that belongs in actions. One {@link AdvisorNotifyCall} is
+ * produced per send site.
+ */
+declare const discoverNotifyCalls: (project: Project, lunoraDirectory: string) => AdvisorNotifyCall[];
+/**
+ * Discover which push channels the project's `lunora/notify.ts` default export
+ * (`defineNotify({...})`) wires plus whether any handler sends a push — the
+ * `notify_missing_push_config` lint input. Returns `undefined` when the file is
+ * absent (the app declares no notify config). The read is metadata-only and
+ * lenient (like `discoverFlags`): a `webPush`/`fcm` property's mere presence
+ * counts as the channel being wired; a non-literal config degrades to "unwired"
+ * rather than throwing.
+ */
+declare const discoverNotifyConfig: (project: Project, lunoraDirectory: string) => AdvisorNotifyConfig | undefined;
+/**
+ * Every package name the project declares a dependency on, read from the
+ * `package.json` at the project root across all four dependency fields
+ * (`dependencies`, `devDependencies`, `peerDependencies`,
+ * `optionalDependencies`).
  *
- * 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).
+ * Returns `undefined` — NOT an empty set — when the manifest is absent or
+ * unparseable, which is the whole reason this exists. Studio nav gating can
+ * treat "declares nothing" and "cannot tell" the same way, but a check that
+ * errors on a missing package cannot: conflating them makes it fire on every
+ * project without a root `package.json` (the codegen fixtures, an embedded
+ * schema, a tool driving `runCodegen` directly).
  */
-declare const buildOpenApiDocument: (input: OpenApiEmitInput) => Record<string, unknown>;
+declare const readPackageDependencies: (projectRoot: string) => Set<string> | undefined;
 /**
- * Emit the OpenAPI 3.1 document as a pretty-printed JSON string
- * (`_generated/openapi.json`) — the portable artifact for external tooling.
+ * 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 emitOpenApi: (input: OpenApiEmitInput) => string;
+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";
 /**
- * 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).
+ * 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 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;
-}
+declare const discoverQueues: (project: Project, lunoraDirectory: string) => QueueIR[];
 /**
- * Emit an OpenRPC 1.x document describing Lunora's JSON-RPC surface.
+ * 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.
  *
- * 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`.
+ * 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.
  *
- * `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).
+ * 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 buildOpenRpcDocument: (input: OpenRpcEmitInput) => Record<string, unknown>;
+declare const discoverRlsMetadata: (project: Project, lunoraDirectory: string) => RlsMetadataIR;
 /**
- * Emit the OpenRPC 1.x document as a pretty-printed JSON string
- * (`_generated/openrpc.json`) — the portable artifact for external tooling.
+ * Which sandbox tools a project imports from `@lunora/agent` (main entry or the
+ * `/sandbox` subpath), detected by NAMED value import. Drives two things:
+ * registering the `sandbox:invoke` dispatcher (either tool) and provisioning the
+ * `BROWSER` wrangler binding (`browserTool` — the browser op runs on
+ * `ctx.browser` inside the dispatcher).
  */
-declare const emitOpenRpc: (input: OpenRpcEmitInput) => string;
+interface SandboxUsage {
+  /** `import { browserTool } from "@lunora/agent"` (or `/sandbox`) appears in `lunora/`. */
+  usesSandboxBrowser: boolean;
+  /** `import { containerTool } from "@lunora/agent"` (or `/sandbox`) appears in `lunora/`. */
+  usesSandboxContainer: boolean;
+}
+declare const discoverSandboxUsage: (project: Project, lunoraDirectory: string) => SandboxUsage;
 /**
- * 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).
+ * Load `&lt;projectRoot>/lunora/schema.ts`, find `defineSchema({...})`, and
+ * return a structural IR. Throws if the file or call cannot be found.
  */
-declare const emitOpenRpcModule: (document_: Record<string, unknown>) => string;
+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";
 /**
- * The canonical capability list. **Order is load-bearing** for the `emit-app.ts`
- * long-tail: the fluent methods are emitted in the order the `appMethod`-bearing
- * rows appear here, so this array is ordered to reproduce the original
- * `LONG_TAIL` sequence (ai, analytics, browser, hyperdrive, images, kv, payment,
- * r2sql, vectors). The `serverCtxField` rows are referenced by name in the ctx
- * interface templates, so their order here is not output-affecting.
+ * 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 CAPABILITY_ROWS: readonly [{
-  readonly contextProperty: "access";
-  readonly key: "access";
-  readonly moduleSpecifier: "@lunora/cloudflare-access";
-}, {
-  readonly appMethod: {
-    readonly configKey: "ai";
-    readonly doc: "Override the Workers AI binding backing `ctx.ai` (defaults to `env.AI`).";
-    readonly method: "ai";
-  };
-  readonly contextProperty: "ai";
-  readonly key: "ai";
-  readonly moduleSpecifier: "@lunora/ai";
-}, {
-  readonly appMethod: {
-    readonly configKey: "analytics";
-    readonly doc: "Override the Analytics Engine dataset backing `ctx.analytics` (defaults to `env.ANALYTICS`).";
-    readonly method: "analytics";
-  };
-  readonly contextProperty: "analytics";
-  readonly key: "analytics";
-  readonly moduleSpecifier: "@lunora/bindings/analytics";
-  readonly serverCtxField: {
-    readonly field: "\n    /** Analytics Engine telemetry sink. Fire-and-forget and sampled; do not read it back in-handler. */\n    readonly analytics: import(\"@lunora/bindings/analytics\").AnalyticsClient;";
-    readonly tier: "every";
-  };
-}, {
-  readonly appMethod: {
-    readonly configKey: "browser";
-    readonly doc: "Override the Browser Rendering binding backing `ctx.browser` (defaults to `env.BROWSER`).";
-    readonly method: "browser";
-  };
-  readonly contextProperty: "browser";
-  readonly key: "browser";
-  readonly moduleSpecifier: "@lunora/browser";
-  readonly serverCtxField: {
-    readonly field: "\n    /** Browser Rendering (screenshots/PDF/scrape). Non-deterministic — available only in actions. */\n    readonly browser: import(\"@lunora/browser\").Browser;";
-    readonly tier: "action";
-  };
-}, {
-  readonly contextProperty: "containers";
-  readonly key: "container";
-  readonly moduleSpecifier: "@lunora/container";
-}, {
-  readonly contextProperty: "flags";
-  readonly key: "flags";
-  readonly moduleSpecifier: "@lunora/flags";
-}, {
-  readonly appMethod: {
-    readonly configKey: "sql";
-    readonly doc: "Wire the Hyperdrive SQL client backing `ctx.sql` — build it with `createHyperdrive` + `fromPostgresJs`/`fromNodePg`/`fromMysql2`.";
-    readonly method: "hyperdrive";
-  };
-  readonly contextProperty: "sql";
-  readonly key: "hyperdrive";
-  readonly moduleSpecifier: "@lunora/hyperdrive";
-  readonly serverCtxField: {
-    readonly field: "\n    /**\n     * External database access via Hyperdrive. Non-deterministic — available only in actions. Writes here are NOT tracked by Lunora live queries; subscriptions will not re-run on external DB changes.\n     */\n    readonly sql: import(\"@lunora/hyperdrive\").SqlClient;";
-    readonly tier: "action";
-  };
-}, {
-  readonly appMethod: {
-    readonly configKey: "images";
-    readonly doc: "Override the Images binding backing `ctx.images` (defaults to `env.IMAGES`).";
-    readonly method: "images";
-  };
-  readonly contextProperty: "images";
-  readonly key: "images";
-  readonly moduleSpecifier: "@lunora/bindings/images";
-  readonly serverCtxField: {
-    readonly field: "\n    /** Cloudflare Images transforms (resize/format/optimize). Non-deterministic — available only in actions. */\n    readonly images: import(\"@lunora/bindings/images\").Images;";
-    readonly tier: "action";
-  };
-}, {
-  readonly appMethod: {
-    readonly configKey: "kv";
-    readonly doc: "Override the Workers KV binding backing `ctx.kv` (defaults to `env.KV`).";
-    readonly method: "kv";
-  };
-  readonly contextProperty: "kv";
-  readonly key: "kv";
-  readonly moduleSpecifier: "@lunora/bindings/kv";
-  readonly serverCtxField: {
-    readonly field: "\n    readonly kv: import(\"@lunora/bindings/kv\").Kv;";
-    readonly tier: "every";
-  };
-}, {
-  readonly key: "mail";
-  readonly moduleSpecifier: "@lunora/mail";
-}, {
-  readonly contextProperty: "notify";
-  readonly key: "notify";
-  readonly moduleSpecifier: "@lunora/notify";
-}, {
-  readonly appMethod: {
-    readonly configKey: "payment";
-    readonly doc: "Wire the payment options backing `ctx.payments`.";
-    readonly method: "payment";
-  };
-  readonly contextProperty: "payments";
-  readonly key: "payments";
-  readonly moduleSpecifier: "@lunora/payment";
-}, {
-  readonly appMethod: {
-    readonly configKey: "x402";
-    readonly doc: "Wire the x402 agent-wallet pay rail backing `ctx.x402` — a payment-enabled `fetch` that answers `402` challenges under a mandatory spend policy (ActionCtx-only; spends real funds).";
-    readonly method: "x402";
-  };
-  readonly contextProperty: "x402";
-  readonly key: "x402";
-  readonly moduleSpecifier: "@lunora/x402/pay";
-}, {
-  readonly contextProperty: "pipelines";
-  readonly key: "pipelines";
-  readonly moduleSpecifier: "@lunora/bindings/pipelines";
-  readonly serverCtxField: {
-    readonly field: "\n    /** Pipelines ingestion sink (durable, R2-backed). Fire-and-forget and batched; do not read it back in-handler. */\n    readonly pipelines: import(\"@lunora/bindings/pipelines\").PipelineClient;";
-    readonly tier: "action";
-  };
-}, {
-  readonly appMethod: {
-    readonly configKey: "r2sql";
-    readonly doc: "Wire the R2 SQL client backing `ctx.r2sql` — build it with `createR2Sql({ accountId, apiToken, bucket })` (defaults to env `R2_SQL_TOKEN` / `R2_SQL_ACCOUNT_ID` / `R2_SQL_BUCKET`).";
-    readonly method: "r2sql";
-  };
-  readonly contextProperty: "r2sql";
-  readonly key: "r2sql";
-  readonly moduleSpecifier: "@lunora/bindings/r2sql";
-  readonly serverCtxField: {
-    readonly field: "\n    /**\n     * R2 SQL over Apache Iceberg tables (window functions, DISTINCT, set operations). Non-deterministic — available only in actions. Reads here are NOT tracked by Lunora live queries.\n     */\n    readonly r2sql: import(\"@lunora/bindings/r2sql\").R2SqlClient;";
-    readonly tier: "action";
-  };
-}, {
-  readonly contextProperty: "scheduler";
-  readonly key: "scheduler";
-  readonly moduleSpecifier: "@lunora/scheduler";
-}, {
-  readonly contextProperty: "storage";
-  readonly key: "storage";
-  readonly moduleSpecifier: "@lunora/storage";
-}, {
-  readonly appMethod: {
-    readonly configKey: "vectors";
-    readonly doc: "Wire the Vectorize index map backing `ctx.vectors`.";
-    readonly method: "vectors";
-  };
-  readonly contextProperty: "vectors";
-  readonly key: "vectors";
-  readonly moduleSpecifier: "@lunora/bindings/vectors";
-}, {
-  readonly contextProperty: "workflows";
-  readonly key: "workflows";
-  readonly moduleSpecifier: "@lunora/workflow";
-}];
-/** The literal union of every capability id — the single source of truth for `FeatureUsage`'s keys (so they cannot drift). */
-type CapabilityKey = (typeof CAPABILITY_ROWS)[number]["key"];
-/** The default codegen target — today's behavior, byte-identical goldens. */
-declare const DEFAULT_TARGET = "cloudflare";
+declare const discoverShapes: (project: Project, lunoraDirectory: string) => ShapeIR[];
 /**
- * Read `target` from `&lt;projectRoot>/lunora.json`.
- *
- * This lives in `@lunora/codegen` rather than `@lunora/config` — where the rest
- * of the `lunora.json` reading lives — because `@lunora/config` depends on
- * `@lunora/codegen`, not the reverse. Putting it there and importing it here
- * would invert that edge, so config delegates to this instead and there is
- * still exactly one parser for the key.
- *
- * Best-effort and deliberately unvalidated: a missing file, malformed JSONC, or
- * a non-string value all collapse to `undefined`, because those are shape
- * errors rather than a name the user meant. An unrecognized *name* is returned
- * as-is so the caller's registry lookup rejects it — swallowing a typo into the
- * default would ship an app to the wrong provider.
- * @param projectRoot Directory containing `lunora.json`.
- * @returns the declared target, or `undefined` when none is usable.
+ * 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 readProjectTarget: (projectRoot: string) => string | undefined;
+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";
 /**
- * The target codegen should emit for: an explicit option wins, then
- * `lunora.json`, then the default.
- *
- * `runCodegen` applies this itself so a caller that forgets to pass a target
- * still emits the surface the project declared. That default matters more than
- * it looks: a call site that silently omits the target emits the *default*
- * surface with no diagnostic to notice, and the mismatch only shows up at
- * runtime on the deployed app.
- * @param projectRoot Directory containing `lunora.json`.
- * @param explicit A caller-supplied target, if any.
- * @returns the resolved target id — not guaranteed to be registered.
+ * 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 resolveCodegenTarget: (projectRoot: string, explicit?: string) => string;
+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;
 /**
- * The target ids codegen can gate against.
- *
- * Exported so `@lunora/config` can assert that its driver registry and this
- * capability-matrix registry name the same targets. They are two id spaces for one
- * concept: a target that ships a driver but no matrix passes the CLI's
- * validation and then emits an un-gated surface, and one with a matrix but no
- * driver gates a surface nothing can deploy. Today both hold exactly
- * `cloudflare`, which is why nothing has noticed.
- * @returns the registered matrix ids, sorted.
+ * Emit `_generated/api.ts` — the typed `api.*` registry (public functions), the
+ * `internal.*` registry, and (when the project declares them) the typed
+ * `workflows.*` / `agents.*` scheduler-target reference objects. `api`/`internal` are the same `anyApi` proxy
+ * at runtime (the `__lunoraRef` is identical); visibility is enforced
+ * server-side at dispatch, not in the reference. Splitting the *types* keeps
+ * internal functions off the client-facing `api` surface.
  */
-declare const platformMatrixIds: () => ReadonlyArray<string>;
-/** An advisor-style diagnostic about a target's platform capabilities. */
-interface PlatformDiagnostic {
-  /** The codegen capability this concerns, when it is feature-specific. */
-  feature?: CapabilityKey;
-  /** Severity. `platform_unsupported_feature` and `platform_unknown_target` are both errors — each drops or misdirects an emitted surface. */
-  level: "error" | "warn";
-  /** Human-readable explanation of the gap. */
-  message: string;
-  /** The lint id: `platform_unsupported_feature` or `platform_unknown_target`. */
-  name: "platform_unknown_target" | "platform_unsupported_feature";
-  /** How to resolve it. */
-  remediation: string;
-  /** The requested deploy target. */
-  target: string;
+interface EmitApiOptions {
+  agents?: ReadonlyArray<AgentIR>;
+  functions: ReadonlyArray<FunctionIR>;
+  /** Typed REST routes; only `.stream()` (SSE) routes emit a `httpStreams.*` reference. */
+  httpRoutes?: ReadonlyArray<HttpRouteIR>;
+  /** Custom mutators (`lunora/mutators.ts`) — emitted as `api.mutators.*` so a client `serverRef` is compile-checked. */
+  mutators?: ReadonlyArray<MutatorIR>;
+  useUmbrella?: boolean;
+  workflows?: ReadonlyArray<WorkflowIR>;
 }
+declare const emitApi: (options: EmitApiOptions) => string;
 /**
- * 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).
+ * Emit `_generated/collections.ts` — a typed TanStack DB binding per `defineShape`
+ * in `lunora/shapes.ts` (the local-first partial-replication surface).
  *
- * 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.
+ * Each shape emits **two** entry points.
  *
- * 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;
+ * `&lt;shape>CollectionOptions(options)` is the composable form: it returns the full
+ * `LunoraCollectionOptions` — `config` for `createCollection`, plus `checkpoints`
+ * (which `bindMutators` gates optimistic overlays on) and `scope`. This is what an app
+ * with custom mutators needs, and what the old single-factory form made impossible: it
+ * built the collection internally and dropped `checkpoints` on the floor, so there was
+ * no way to wire mutators to the collection codegen produced.
+ *
+ * `&lt;shape>Collection(options)` is the convenience form for a read-only collection: it
+ * returns `{ checkpoints, collection, scope }` rather than a bare `Collection`, so the
+ * sync controls stay reachable even from the short path.
+ *
+ * Both are typed: `args` comes from the shape's own validators (a parameterless
+ * shape takes none), rows resolve to `Doc&lt;"table">` when the shape names its table
+ * with a literal, and `shardKey` / `getKey` / `load` / `onError` / `checkpoints` are
+ * all threadable — a sharded table needs `shardKey` for its watermark to land in the
+ * right bucket, and a server-minted `_id` that differs from the app's natural key
+ * needs `getKey`.
+ *
+ * Returns `""` (so `writeIfPresent` skips the file) unless the project both
+ * declares shapes AND installs `@lunora/db` — the add-on that ships
+ * `lunoraCollectionOptions`. `@lunora/db` stays a scoped install even under the
+ * `lunorash` umbrella (an opt-in add-on, like `@lunora/auth`), so its import is
+ * always `@lunora/db/collections`; only the in-umbrella `@lunora/client` import
+ * is remapped to `lunorash/client`.
+ */
+declare const emitCollections: (shapes: ReadonlyArray<ShapeIR>, hasDatabase: boolean, useUmbrella?: boolean) => string;
+interface EmitServerOptions {
+  /** Agents declared via `defineAgent` exports — wires the typed `ctx.agents` producers onto Mutation/Action contexts. */
+  agents?: ReadonlyArray<AgentIR>;
+  containers?: ReadonlyArray<ContainerIR>;
   /**
-   * The deploy target codegen tailors the emitted `ctx.*` surface to.
-   * Defaults to `"cloudflare"` — whose capability matrix marks every feature
-   * native or emulated, so the default output is unchanged (byte-identical
-   * goldens). A target that marks a used feature unsupported omits its
-   * `ctx.*` surface and reports it in {@link CodegenResult.platformDiagnostics}.
-   * Only `"cloudflare"` is registered until other per-target `@lunora/platform`
-   * matrices land; an unknown target emits the full surface un-gated and a
-   * `platform_unknown_target` diagnostic.
+   * The single `defineEnv(...)` contract declared in `lunora/env.ts`. When
+   * present, `ctx.env` is typed as the validated `InferEnv` shape (recovered
+   * via `ReturnType` over the accessor's `typeof`). `undefined` leaves `ctx.env`
+   * the base optional binding record — byte-identical to today.
    */
-  target?: string;
+  env?: EnvIR;
   /**
-   * 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.
+   * 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.
    */
-  updateSchemaBaseline?: boolean;
+  hasAccessFacade?: boolean;
+  hasAi?: boolean;
+  /** 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/bindings/images` / `ctx.images` — wires `ctx.images` onto ActionCtx only. */
+  hasImages?: boolean;
+  /** A `lunora/` source uses `@lunora/bindings/kv` / `ctx.kv` — wires `ctx.kv` onto every ctx. */
+  hasKv?: boolean;
+  /** The project declares `lunora/notify.ts` — wires `ctx.notify` + its `ctx.push` alias (`@lunora/notify`) onto every ctx. */
+  hasNotify?: boolean;
+  hasPayments?: boolean;
+  /** A `lunora/` source uses `@lunora/bindings/pipelines` / `ctx.pipelines` — wires `ctx.pipelines` onto ActionCtx only. */
+  hasPipelines?: boolean;
+  /** A `lunora/` source uses `@lunora/bindings/r2sql` / `ctx.r2sql` — wires `ctx.r2sql` onto ActionCtx only. */
+  hasR2sql?: boolean;
+  /** A `lunora/` source uses `@lunora/x402/pay` / `ctx.x402` — wires the agent-wallet pay rail onto ActionCtx only. */
+  hasX402?: boolean;
   /**
-   * Committed `wrangler.jsonc` `vars` entries that hold plaintext secrets — the
-   * `plaintext_secret_in_wrangler_vars` lint input. Produced by `@lunora/config`
-   * (which reads `wrangler.jsonc`) and threaded through by the CLI / Vite plugin;
-   * codegen only forwards it to the advisor. Absent when no wrangler config is
-   * present or the caller doesn't scan it.
+   * The single `defineIdentity(...)` claim contract declared in
+   * `lunora/identity.ts` (Plan 080). When present, `ctx.auth.getIdentity()`,
+   * the RLS policy `ctx.auth.identity`, and the shard-authorization hooks
+   * narrow to the declared shape (recovered via `InferIdentity` over the
+   * contract's `typeof`). `undefined` keeps the identity an untyped bag —
+   * byte-identical to today.
    */
-  wranglerVariables?: ReadonlyArray<WranglerVariableIR>;
+  identity?: IdentityIR;
+  /** Queues declared via `defineQueue` exports — wires the typed `ctx.queues` producers onto Mutation/Action contexts. */
+  queues?: ReadonlyArray<QueueIR>;
+  schema?: SchemaIR;
+  storageRuleBuckets?: ReadonlyArray<string>;
+  /** The project depends on the `lunora` umbrella — import base packages via its subpaths. */
+  useUmbrella?: boolean;
+  workflows?: ReadonlyArray<WorkflowIR>;
 }
-interface CodegenResult {
-  /**
-   * The normalized advisor evidence the findings were produced from, so a
-   * caller can score it into a health map (`scoreAdvisor`) without re-running
-   * discovery. `undefined` under `lint: false`.
-   *
-   * Deliberately not scored here: the map carries a `generatedAt` stamp, and
-   * codegen's result stays a pure function of the sources.
-   */
-  advisorContext?: LintContext;
-  /**
-   * Static schema advisor findings (e.g. unindexed foreign keys) produced
-   * this run. Empty when `lint` is `false` or the schema is clean. Codegen
-   * does not print these itself — each caller presents them through its own
-   * channel (the CLI logger, the vite overlay, the studio Advisors table).
-   * `formatAdvisories` is exported for a plain multi-line rendering.
-   */
-  advisories: ReadonlyArray<Finding>;
-  /**
-   * Agents discovered from `defineAgent` exports in `lunora/agents.ts` — the
-   * list the config layer reconciles into wrangler's `workflows[]` array (an
-   * agent compiles onto a Cloudflare Workflow). Agents are NOT Durable Objects,
-   * so this adds no binding or migration. Empty when the project declares none.
-   */
-  agents: ReadonlyArray<AgentIR>;
+declare const emitServer: ({ agents, containers, env, hasAccessFacade, hasAi, hasAnalytics, hasBrowser, hasFlags, hasHyperdrive, hasImages, hasKv, hasNotify, hasPayments, hasPipelines, hasR2sql, hasX402, identity, queues, schema, storageRuleBuckets, useUmbrella, workflows }?: EmitServerOptions) => string;
+interface EmitFunctionsOptions {
+  agents?: ReadonlyArray<AgentIR>;
+  functions: ReadonlyArray<FunctionIR>;
+  migrations?: ReadonlyArray<MigrationIR>;
+  mutators?: ReadonlyArray<MutatorIR>;
+  shapes?: ReadonlyArray<ShapeIR>;
+  /** Import of a sandbox tool (`browserTool`/`containerTool`) auto-registers the `sandbox:invoke` action. */
+  usesSandbox?: boolean;
+  useUmbrella?: boolean;
+}
+declare const emitFunctions: (options: EmitFunctionsOptions) => string;
+/**
+ * Emit `_generated/containers.ts` — one container-enabled Durable Object class
+ * per `defineContainer` export, each a thin subclass of `LunoraContainer`
+ * (`@lunora/container/do`) constructed with the user's definition object. The
+ * worker entry must re-export these classes: wrangler requires every
+ * `containers[].class_name` to be exported by the deployed worker. Returns ""
+ * when the project declares no containers (the file is not written then).
+ */
+declare const emitContainers: (containers: ReadonlyArray<ContainerIR>, jurisdiction?: JurisdictionIR) => string;
+/**
+ * Emit `_generated/workflows.ts` — one `WorkflowEntrypoint` class per
+ * `defineWorkflow` export, each a thin subclass of `LunoraWorkflow`
+ * (`@lunora/workflow/do`) constructed with the user's definition object. The
+ * worker entry must re-export these classes: wrangler requires every
+ * `workflows[].class_name` to be exported by the deployed worker. Returns ""
+ * when the project declares no workflows (the file is not written then).
+ */
+declare const emitWorkflows: (workflows: ReadonlyArray<WorkflowIR>) => string;
+/**
+ * Emit `_generated/agents.ts` — one `WorkflowEntrypoint` class per `defineAgent`
+ * export, each a thin subclass of `LunoraWorkflow` (`@lunora/workflow/do`)
+ * constructed with the compiled agent tool-loop (`compileAgentWorkflow`). Like
+ * `_generated/workflows.ts`, the worker entry must re-export these classes:
+ * wrangler requires every `workflows[].class_name` to be exported by the
+ * deployed worker. Returns "" when the project declares no agents (the file is
+ * not written then).
+ */
+declare const emitAgents: (agents: ReadonlyArray<AgentIR>) => string;
+interface EmitShardOptions {
+  advisories?: ReadonlyArray<Finding>;
+  /** Every declared procedure — the health map's denominator, served via `getAdvisorProcedures`. */
+  advisorProcedures?: ReadonlyArray<AdvisorProcedureProtection>;
+  /** Agents declared via `defineAgent` exports in `lunora/agents.ts` — wires the typed `ctx.agents` producers. */
+  agents?: ReadonlyArray<AgentIR>;
+  containers?: ReadonlyArray<ContainerIR>;
+  /** The single `defineEnv(...)` contract declared in `lunora/env.ts` — applies the accessor to the worker `env` to populate `ctx.env`. */
+  env?: EnvIR;
+  /** Statically-discovered `ctx.flags.&lt;type>("key")` reads — the studio Flags page + reactive evaluation iterate these. */
+  flagKeys?: ReadonlyArray<{
+    key: string;
+    type: "boolean" | "number" | "object" | "string";
+  }>;
+  /** A `lunora/` source reads `ctx.access` — wires the verified Cloudflare Access facade onto every ctx. */
+  hasAccessFacade?: boolean;
+  hasAi?: boolean;
+  /** A `lunora/` source reads `ctx.analytics` — wires the Analytics Engine write helper onto every ctx. */
+  hasAnalytics?: boolean;
+  /** A `lunora/` source reads `ctx.browser` — wires `ctx.browser` onto the ActionCtx only. */
+  hasBrowser?: boolean;
+  /** The project declares `lunora/flags.ts` — wires `ctx.flags` (OpenFeature) onto every ctx. */
+  hasFlags?: boolean;
+  /** A `lunora/` source reads `ctx.sql` (Hyperdrive) — wires `ctx.sql` onto the ActionCtx only. */
+  hasHyperdrive?: boolean;
+  /** A `lunora/` source reads `ctx.images` — wires `ctx.images` onto the ActionCtx only. */
+  hasImages?: boolean;
+  /** A `lunora/` source reads `ctx.kv` — wires `ctx.kv` onto every ctx. */
+  hasKv?: boolean;
+  /** The project declares `lunora/notify.ts` — wires `ctx.notify` + its `ctx.push` alias (`@lunora/notify`) onto every ctx. */
+  hasNotify?: boolean;
+  hasPayments?: boolean;
+  /** A `lunora/` source reads `ctx.pipelines` — wires `ctx.pipelines` onto the ActionCtx only. */
+  hasPipelines?: boolean;
+  /** A `lunora/` source reads `ctx.r2sql` (R2 SQL) — wires `ctx.r2sql` onto the ActionCtx only. */
+  hasR2sql?: boolean;
+  /** A `lunora/` source reads `ctx.x402` — wires the agent-wallet pay rail onto the ActionCtx only. */
+  hasX402?: boolean;
+  maskMetadata?: MaskMetadataIR;
+  /** Custom mutators declared via `defineMutator` in `lunora/mutators.ts` — wires the `isCustomMutator` push-protocol override. */
+  mutators?: ReadonlyArray<MutatorIR>;
+  /** Queues declared via `defineQueue` exports in `lunora/queues.ts` — wires the typed `ctx.queues` producers. */
+  queues?: ReadonlyArray<QueueIR>;
+  rlsMetadata?: RlsMetadataIR;
+  schema: SchemaIR;
   /**
-   * 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.
+   * The structural snapshot the pre-deploy drift gate diffs against, threaded
+   * in so the emitted DO records it in `__lunora_schema_history` on cold start
+   * (plan 200 — the Studio's schema-version timeline). Optional so an emitter
+   * caller that has no snapshot (tests, fixtures) emits the pre-ledger shape
+   * unchanged.
    */
-  containers: ReadonlyArray<ContainerIR>;
-  /**
-   * Deduplicated cron schedules discovered from `cronJobs()` definitions —
-   * the array the vite plugin reconciles into `wrangler.jsonc`'s
-   * `triggers.crons`. Empty when the project declares no crons.
-   */
-  cronTriggers: ReadonlyArray<string>;
-  generated: {
-    /** WorkflowEntrypoint classes for declared agents (`_generated/agents.ts`); `""` (and not written) when no agents are declared. */
-    agents: string;
-    api: string;
-    /** Fluent worker-composition builder (`_generated/app.ts`) — `defineApp()`. Always written. */
-    app: string;
-    /** Partial-replication collection factories (`_generated/collections.ts`); `""` (and not written) unless the project declares shapes and installs `@lunora/db`. */
-    collections: string;
-    /** Container DO classes (`_generated/containers.ts`); `""` (and not written) when no containers are declared. */
-    containers: string;
-    crons: string;
-    dataModel: string;
-    drizzleGlobal: string;
-    drizzleShard: string;
-    functions: string;
-    /** OpenAPI 3.1.0 document (`_generated/openapi.json`), pretty-printed JSON. */
-    openApi: string;
-    /**
-     * OpenAPI document as an importable TS module (`_generated/openapi.ts`) —
-     * `export const openApiSpec`, the worker imports it for
-     * `createWorker({ openApiSpec })`. Same document as `openApi`. Written
-     * alongside `openapi.json` whenever `apiSpec` includes `openapi`.
-     */
-    openApiModule: string;
-    /** OpenRPC 1.x document (`_generated/openrpc.json`), pretty-printed JSON. Always computed; written only when `apiSpec` includes `openrpc`. */
-    openRpc: string;
-    /**
-     * OpenRPC document as an importable TS module (`_generated/openrpc.ts`) —
-     * `export const openRpcSpec`, for `createWorker({ openRpcSpec })`. Same
-     * document as `openRpc`. Written alongside `openrpc.json` whenever
-     * `apiSpec` includes `openrpc`.
-     */
-    openRpcModule: string;
-    /** Push-consumer queue registry (`_generated/queues.ts`); `""` (and not written) when no push queues are declared. */
-    queues: string;
-    /** Project-bound seed client (`_generated/seed.ts`); `""` (and not written) when `@lunora/seed` is not a declared dependency. */
-    seed: string;
-    server: string;
-    shard: string;
-    /** Static vector-index registry (`_generated/vectors.ts`) — `LUNORA_VECTOR_INDEXES`. Empty array body when the schema declares none. */
-    vectors: string;
-    /** WorkflowEntrypoint classes (`_generated/workflows.ts`); `""` (and not written) when no workflows are declared. */
-    workflows: string;
-  };
-  outputDirectory: string;
-  /**
-   * Portability diagnostics for the requested {@link CodegenOptions.target}:
-   * `ctx.*` features the app uses that the target does not support (omitted
-   * from the emitted surface), or an unknown target. Empty for a
-   * fully-supported app on the default Cloudflare target. Presentation is the
-   * caller's job, like {@link CodegenResult.advisories}.
-   */
-  platformDiagnostics: ReadonlyArray<PlatformDiagnostic>;
-  /**
-   * Queues discovered from `defineQueue` exports in `lunora/queues.ts` — the
-   * list the config layer reconciles into wrangler's `queues.producers[]` /
-   * `queues.consumers[]`. Queues are NOT Durable Objects, so this adds no
-   * binding or migration. Empty when the project declares no queues.
-   */
-  queues: ReadonlyArray<QueueIR>;
+  schemaSnapshot?: SchemaSnapshot;
+  /** Replication shapes declared via `defineShape` in `lunora/shapes.ts` — wires the `resolveShape` subscription override. */
+  shapes?: ReadonlyArray<ShapeIR>;
+  storageRules?: StorageRulesMetadataIR;
+  studioFeatures?: StudioFeaturesResult;
+  /** The project depends on the `lunora` umbrella — import base packages via its subpaths. */
+  useUmbrella?: boolean;
+  workflows?: ReadonlyArray<WorkflowIR>;
+}
+declare const emitShard: ({ advisories, advisorProcedures, agents, containers, env, flagKeys, hasAccessFacade, hasAi, hasAnalytics, hasBrowser, hasFlags, hasHyperdrive, hasImages, hasKv, hasNotify, hasPayments, hasPipelines, hasR2sql, hasX402, maskMetadata, mutators, queues, rlsMetadata, schema, schemaSnapshot, shapes, storageRules, studioFeatures, useUmbrella, workflows }: EmitShardOptions) => string;
+/**
+ * Emit drizzle `sqliteTable` definitions for the project schema, split into
+ * `global` (D1-backed) and `shard` (DO-SQLite-backed) buckets. Tables marked
+ * `.global()` go in the global file; everything else (default root + `.shardBy()`)
+ * goes in the shard file.
+ *
+ * `searchIndexes` are intentionally not emitted — drizzle has no `sqliteTable`
+ * abstraction for FTS5 virtual tables. FTS plumbing is handled by the runtime
+ * outside of drizzle.
+ */
+declare const emitDrizzleSchema: (schema: SchemaIR, useUmbrella?: boolean) => {
+  global: string;
+  shard: string;
+};
+/**
+ * Emit `_generated/crons.ts` from the discovered cron jobs.
+ *
+ * `LUNORA_CRON_TRIGGERS` is the deduplicated schedule array — what lands in
+ * wrangler's `triggers.crons` (the vite plugin reconciles it into
+ * `wrangler.jsonc`, and {@link emitWranglerCronTriggers} renders the same list
+ * for the CLI / docs).
+ *
+ * `LUNORA_CRONS` is the dispatcher map keyed by cron expression, each value a
+ * list of `{ name, functionPath, args }`. Cloudflare's `scheduled()` handler
+ * receives only the cron string, so multiple jobs sharing one expression must
+ * all fire — hence a list per key rather than a single entry.
+ *
+ * Jobs arrive pre-sorted by name (deterministic output); the trigger array
+ * preserves first-seen order of distinct expressions.
+ *
+ * Cloudflare caps a Worker at **3 Cron Triggers** (i.e. 3 distinct cron
+ * expressions). Because the dispatcher fires every job sharing an expression,
+ * many jobs can ride a single trigger — only the count of *distinct* schedules
+ * matters. `lunora codegen` warns when that count exceeds the limit; for
+ * finer-grained scheduling use Durable Object alarms (`@lunora/scheduler`),
+ * which have no such cap.
+ */
+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 {
   /**
-   * 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`.
+   * Inbound-email agents (`defineAgent({ onEmail })`) → wire the worker's
+   * top-level `email()` handler to `dispatchAgentEmail(...)` (from
+   * `@lunora/agent/inbound`), so received mail starts a durable run. Empty/absent
+   * ⇒ no wiring, byte-identical output for email-free (and agent-free) projects.
    */
-  schemaSnapshot: SchemaSnapshot;
-  /** Absolute path of the committed baseline file (`lunora/.lunora-schema.json`). */
-  schemaSnapshotPath: string;
+  emailAgents?: ReadonlyArray<{
+    bindingName: string;
+    exportName: string;
+  }>;
+  /** App depends on `@lunora/cloudflare-access` → emit `.access()` (wire the Cloudflare Access `resolveIdentity`, composed ahead of `@lunora/auth` when both are present). */
+  hasAccess: boolean;
+  /** App uses `@lunora/ai` / `ctx.ai` → emit `.ai()` (override the Workers AI binding backing `ctx.ai`). */
+  hasAi: boolean;
+  /** App uses `@lunora/bindings/analytics` / `ctx.analytics` → emit `.analytics()` (override the dataset backing `ctx.analytics`). */
+  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/bindings/images` / `ctx.images` → emit `.images()`. */
+  hasImages: boolean;
+  /** App uses `@lunora/bindings/kv` / `ctx.kv` → emit `.kv()`. */
+  hasKv: boolean;
+  /** App declares `lunora/notify.ts` (`@lunora/notify`) → wire `options.notifySubscriptionStore` so the studio Notifications page can read registered devices. */
+  hasNotify: boolean;
+  /** App uses `@lunora/payment` / `ctx.payments` → emit `.payment()`. */
+  hasPayments: boolean;
+  /** App 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). */
+  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;
+  /** App uses `@lunora/x402/pay` / `ctx.x402` → emit `.x402()` (wire the agent-wallet pay rail). */
+  hasX402: boolean;
+  /** The single `defineIdentity(...)` contract in `lunora/identity.ts` (Plan 080) → import it as a VALUE and wire `options.identity`, so the runtime trust boundary validates every resolved identity before it becomes `ctx.auth`. `undefined` ⇒ no wiring, byte-identical output. */
+  identity?: IdentityIR;
+  /** Schema declares `.jurisdiction("…")` → pin every DO the worker reaches (shards, fan-out, scheduler, containers) to the Cloudflare data-residency jurisdiction. */
+  jurisdiction?: JurisdictionIR;
+  /** Project depends on the unscoped `lunorash` umbrella → import the runtime via `lunorash/runtime` instead of `@lunora/runtime`. */
+  useUmbrella: boolean;
   /**
-   * 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.
+   * Voice-enabled agents (`defineAgent({ voice: … })`) → wire
+   * `options.voiceAgents`, mapping each agent's export name to its `VOICE_*`
+   * Durable Object namespace binding so the runtime exposes
+   * `/_lunora/voice/&lt;exportName>`. Empty/absent ⇒ no wiring, byte-identical
+   * output for voice-free (and agent-free) projects.
    */
-  workflows: ReadonlyArray<WorkflowIR>;
+  voiceAgents?: ReadonlyArray<{
+    bindingName: string;
+    exportName: string;
+  }>;
+  /** An OpenAPI spec is emitted (`openapi.ts`) → wire `openApiSpec` into the worker. */
+  wantsOpenApi: boolean;
+  /** An OpenRPC spec is emitted (`openrpc.ts`) → wire `openRpcSpec` into the worker. */
+  wantsOpenRpc: boolean;
 }
+/**
+ * Emit `_generated/app.ts` — a fluent, feature-specialized worker-composition
+ * builder. Only the methods for capabilities THIS app uses are emitted, so the
+ * builder's type surface (IntelliSense) lists exactly what can be configured.
+ *
+ * Each capability declaration is fanned into BOTH runtime surfaces: the DO-side
+ * `createShardDO(...)` factory that backs `ctx.*`, and the worker-side
+ * `createWorker(...)` options that back the studio/admin endpoints — so storage
+ * / scheduler / global are declared once instead of twice. The builder is pure
+ * sugar over the public `createWorker` / `createShardDO`; both stay usable.
+ *
+ * Lives in generated code (not `@lunora/runtime`, which is dependency-free) so
+ * it can import the add-on packages the app installed (`@lunora/auth`,
+ * `@lunora/storage`, …) directly.
+ */
+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;
 /**
  * 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
@@ -3244,6 +3293,8 @@ interface SchemaDriftDecision {
 declare const evaluateSchemaDrift: (options: {
   allowDrift?: boolean;
   baseline: SchemaSnapshot | undefined;
+  /** The command printing the remediation, so it names only flags that command accepts. */
+  command?: string;
   current: SchemaSnapshot;
 }) => SchemaDriftDecision;
 /**
@@ -3275,4 +3326,4 @@ declare const secretKindOf: (value: string) => string | undefined;
 /** A redacted preview of a secret value — first 4 chars plus its length, never the full value. */
 declare const redact: (value: string) => string;
 declare const VERSION = "0.0.0";
-export { AGENTS_FILENAME, type AgentIR, type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, DEFAULT_TARGET, type DriftChange, type DriftScope, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type LintSchemaOptions, MUTATORS_FILENAME, type MaskProcedureIR, type MigrationIR, type MutatorIR, NOTIFY_FILENAME, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type PlatformDiagnostic, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, SHAPES_FILENAME, type SandboxUsage, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type ShapeIR, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, type WranglerVariableIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAgents, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverMutators, discoverNondeterministicCalls, discoverNotifyCalls, discoverNotifyConfig, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSandboxUsage, discoverSchema, discoverShapes, discoverStorageRulesMetadata, discoverWorkflows, emitAgents, emitApi, emitApp, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, formatAdvisories, lintSchema, parseSchemaSnapshot, platformMatrixIds, readProjectTarget, redact, refreshCodegenProject, resolveCodegenTarget, runCodegen, schemaFromIr, secretKindOf, serializeSchemaSnapshot, toAdvisorContext, validatorIrToJsonSchema };
+export { AGENTS_FILENAME, type AgentIR, type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, DEFAULT_TARGET, type DriftChange, type DriftScope, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type LintSchemaOptions, MUTATORS_FILENAME, type MaskProcedureIR, type MigrationIR, type MutatorIR, NOTIFY_FILENAME, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type PlatformDiagnostic, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, SHAPES_FILENAME, type SandboxUsage, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type ShapeIR, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, type WranglerVariableIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, describeErrorLevelFindings, diagnosticAt, diffSchemaSnapshots, discoverAgents, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverMutators, discoverNondeterministicCalls, discoverNotifyCalls, discoverNotifyConfig, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSandboxUsage, discoverSchema, discoverShapes, discoverStorageRulesMetadata, discoverWorkflows, emitAgents, emitApi, emitApp, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, errorAdvisoryNames, errorPlatformDiagnosticNames, evaluateSchemaDrift, formatAdvisories, lintSchema, parseSchemaSnapshot, platformMatrixIds, readPackageDependencies, readProjectTarget, redact, refreshCodegenProject, resolveCodegenTarget, runCodegen, schemaFromIr, secretKindOf, serializeSchemaSnapshot, toAdvisorContext, validatorIrToJsonSchema };