@lunora/codegen 1.0.0-alpha.82 → 1.0.0-alpha.84

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,105 +2057,575 @@ 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.
+ * 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 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";
+declare const SCHEMA_SNAPSHOT_FILENAME = ".lunora-schema.json";
 /**
- * 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.
+ * 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 discoverFlags: (project: Project, lunoraDirectory: string) => FlagsIR | undefined;
+declare const createCodegenProject: (lunoraDirectory: string) => Project;
 /**
- * Scan all .ts files under `lunoraDir` (skipping `_generated/` and `schema.ts`)
- * for top-level `export const x = query/mutation/action({...})` registrations.
+ * Synchronise a reused {@link createCodegenProject} Project with the current
+ * on-disk state of `lunoraDirectory`, so the next {@link runCodegen} sees the
+ * same files a freshly-constructed Project would — without re-parsing the whole
+ * TS program. Adds any on-disk source file the Project doesn't yet have, and
+ * `refreshFromFileSystemSync()`es the ones it does (picking up edits); then
+ * removes Project source files under `lunoraDirectory` that no longer exist on
+ * disk (the classic stale-deleted-file cache bug).
+ *
+ * Files outside `lunoraDirectory` (e.g. those pulled in by the user's tsconfig)
+ * are left untouched — they back type resolution and rarely change in the
+ * dev-loop; a tsconfig change invalidates the whole cached Project upstream.
  */
-declare const discoverFunctions: (project: Project, lunoraDirectory: string) => FunctionIR[];
+declare const refreshCodegenProject: (project: Project, lunoraDirectory: string) => void;
 /**
- * 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.
+ * Top-level codegen entry. Parses `&lt;projectRoot>/lunora/schema.ts` and every
+ * function file under `&lt;projectRoot>/lunora/`, then writes
+ * `_generated/{api,server,dataModel}.ts` next to them.
+ *
+ * When `LUNORA_CODEGEN_TIMING` is set (truthy), a single diagnostic summary
+ * line is written to stderr with the total wall time and the discovery-vs-emit
+ * split — opt-in instrumentation that is otherwise zero-cost and side-effect-free
+ * on the returned {@link CodegenResult}.
  */
-declare const discoverHttpRoutes: (project: Project, lunoraDirectory: string) => HttpRouteIR[];
+declare const runCodegen: (options: CodegenOptions) => CodegenResult;
+interface CodegenOptions {
+  /**
+   * Which machine-readable API spec(s) to emit into `_generated/`.
+   *
+   * `"openapi"` (the default) writes only `openapi.json` (OpenAPI 3.1; covers
+   * both the RPC functions and `httpRouter()` REST routes). `"openrpc"` writes
+   * only `openrpc.json` (OpenRPC 1.x; the RPC functions only — OpenRPC cannot
+   * represent REST routes). `"both"` writes both files; `"none"` writes neither.
+   *
+   * Regardless of the choice, `CodegenResult.generated.openApi` and `.openRpc`
+   * always carry the rendered string (computation is cheap and pure); only the
+   * on-disk write is gated by this option.
+   */
+  apiSpec?: "both" | "none" | "openapi" | "openrpc";
+  /**
+   * When true, run discovery + emit (so any schema/function parse error
+   * surfaces) but skip writing files to `_generated/`. The returned
+   * `outputDirectory` is still the path that *would* have been written.
+   */
+  dryRun?: boolean;
+  /**
+   * Run the static schema advisor (unindexed FKs, …) during codegen.
+   * Defaults to `true`. When `false`, `CodegenResult.advisories` is empty.
+   * Computed regardless of `dryRun`; codegen never prints them — see
+   * {@link CodegenResult.advisories}.
+   */
+  lint?: boolean;
+  /** Override the lunora subdirectory name. Defaults to `"lunora"`. */
+  lunoraDirectory?: string;
+  /**
+   * Reuse a previously-constructed ts-morph {@link Project} instead of building
+   * a fresh one each run. The caller owns refreshing its source files from disk
+   * (see {@link refreshCodegenProject}) — codegen does not re-read changed files
+   * off an injected Project. Built via {@link createCodegenProject} when absent.
+   * Used by the Vite dev-loop to avoid re-parsing the whole TS program on every
+   * save; omit it (CLI one-shot path) to get the default fresh-Project behaviour.
+   */
+  project?: Project;
+  /** Project root containing the `lunora/` directory. */
+  projectRoot: string;
+  /**
+   * The deploy target codegen tailors the emitted `ctx.*` surface to.
+   * Defaults to `"cloudflare"` — whose capability matrix marks every feature
+   * native or emulated, so the default output is unchanged (byte-identical
+   * goldens). A target that marks a used feature unsupported omits its
+   * `ctx.*` surface and reports it in {@link CodegenResult.platformDiagnostics}.
+   * Only `"cloudflare"` is registered until other per-target `@lunora/platform`
+   * matrices land; an unknown target emits the full surface un-gated and a
+   * `platform_unknown_target` diagnostic.
+   */
+  target?: string;
+  /**
+   * Re-bless the committed schema-drift baseline (`lunora/.lunora-schema.json`)
+   * with the current structural snapshot. The baseline is ALWAYS written on
+   * first capture (when the file is absent); set this to overwrite an existing
+   * one — e.g. after the developer has added the data migration that justifies
+   * a breaking change. Ignored when `dryRun` is true.
+   */
+  updateSchemaBaseline?: boolean;
+  /**
+   * Committed `wrangler.jsonc` `vars` entries that hold plaintext secrets — the
+   * `plaintext_secret_in_wrangler_vars` lint input. Produced by `@lunora/config`
+   * (which reads `wrangler.jsonc`) and threaded through by the CLI / Vite plugin;
+   * codegen only forwards it to the advisor. Absent when no wrangler config is
+   * present or the caller doesn't scan it.
+   */
+  wranglerVariables?: ReadonlyArray<WranglerVariableIR>;
+}
+interface CodegenResult {
+  /**
+   * The normalized advisor evidence the findings were produced from, so a
+   * caller can score it into a health map (`scoreAdvisor`) without re-running
+   * discovery. `undefined` under `lint: false`.
+   *
+   * Deliberately not scored here: the map carries a `generatedAt` stamp, and
+   * codegen's result stays a pure function of the sources.
+   */
+  advisorContext?: LintContext;
+  /**
+   * Static schema advisor findings (e.g. unindexed foreign keys) produced
+   * this run. Empty when `lint` is `false` or the schema is clean. Codegen
+   * does not print these itself — each caller presents them through its own
+   * channel (the CLI logger, the vite overlay, the studio Advisors table).
+   * `formatAdvisories` is exported for a plain multi-line rendering.
+   */
+  advisories: ReadonlyArray<Finding>;
+  /**
+   * Agents discovered from `defineAgent` exports in `lunora/agents.ts` — the
+   * list the config layer reconciles into wrangler's `workflows[]` array (an
+   * agent compiles onto a Cloudflare Workflow). Agents are NOT Durable Objects,
+   * so this adds no binding or migration. Empty when the project declares none.
+   */
+  agents: ReadonlyArray<AgentIR>;
+  /**
+   * Containers discovered from `defineContainer` exports in
+   * `lunora/containers.ts` — the list the config layer reconciles into
+   * wrangler's `containers[]`, `CONTAINER_*` Durable Object bindings, and
+   * migration classes. Empty when the project declares no containers.
+   */
+  containers: ReadonlyArray<ContainerIR>;
+  /**
+   * Deduplicated cron schedules discovered from `cronJobs()` definitions —
+   * the array the vite plugin reconciles into `wrangler.jsonc`'s
+   * `triggers.crons`. Empty when the project declares no crons.
+   */
+  cronTriggers: ReadonlyArray<string>;
+  generated: {
+    /** WorkflowEntrypoint classes for declared agents (`_generated/agents.ts`); `""` (and not written) when no agents are declared. */
+    agents: string;
+    api: string;
+    /** Fluent worker-composition builder (`_generated/app.ts`) — `defineApp()`. Always written. */
+    app: string;
+    /** Partial-replication collection factories (`_generated/collections.ts`); `""` (and not written) unless the project declares shapes and installs `@lunora/db`. */
+    collections: string;
+    /** Container DO classes (`_generated/containers.ts`); `""` (and not written) when no containers are declared. */
+    containers: string;
+    crons: string;
+    dataModel: string;
+    drizzleGlobal: string;
+    drizzleShard: string;
+    functions: string;
+    /** OpenAPI 3.1.0 document (`_generated/openapi.json`), pretty-printed JSON. */
+    openApi: string;
+    /**
+     * OpenAPI document as an importable TS module (`_generated/openapi.ts`) —
+     * `export const openApiSpec`, the worker imports it for
+     * `createWorker({ openApiSpec })`. Same document as `openApi`. Written
+     * alongside `openapi.json` whenever `apiSpec` includes `openapi`.
+     */
+    openApiModule: string;
+    /** OpenRPC 1.x document (`_generated/openrpc.json`), pretty-printed JSON. Always computed; written only when `apiSpec` includes `openrpc`. */
+    openRpc: string;
+    /**
+     * OpenRPC document as an importable TS module (`_generated/openrpc.ts`) —
+     * `export const openRpcSpec`, for `createWorker({ openRpcSpec })`. Same
+     * document as `openRpc`. Written alongside `openrpc.json` whenever
+     * `apiSpec` includes `openrpc`.
+     */
+    openRpcModule: string;
+    /** Push-consumer queue registry (`_generated/queues.ts`); `""` (and not written) when no push queues are declared. */
+    queues: string;
+    /** Project-bound seed client (`_generated/seed.ts`); `""` (and not written) when `@lunora/seed` is not a declared dependency. */
+    seed: string;
+    server: string;
+    shard: string;
+    /** Static vector-index registry (`_generated/vectors.ts`) — `LUNORA_VECTOR_INDEXES`. Empty array body when the schema declares none. */
+    vectors: string;
+    /** WorkflowEntrypoint classes (`_generated/workflows.ts`); `""` (and not written) when no workflows are declared. */
+    workflows: string;
+  };
+  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>;
 /**
- * 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).
+ * 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 discoverInserts: (project: Project, lunoraDirectory: string) => InsertWriteIR[];
+declare const describeErrorLevelFindings: (result: Pick<CodegenResult, "advisories" | "platformDiagnostics">) => {
+  advisoryNames: ReadonlyArray<string>;
+  platformDiagnosticNames: ReadonlyArray<string>;
+};
 /**
- * Discover masking usage for every exported Lunora procedure under the lunora
+ * An error thrown by codegen discovery when the user's schema or function
+ * source has a structural problem that can be pinpointed to a specific source
+ * location. A `LunoraError` subclass (`code: "CODEGEN_DIAGNOSTIC"`); the `file`,
+ * `line`, and `column` properties (also passed through as the base `loc`) mirror
+ * what Vite's error-overlay `loc` field expects so the browser can display the
+ * exact spot.
+ */
+declare class CodegenDiagnosticError extends LunoraError {
+  readonly column: number;
+  readonly file: string;
+  readonly line: number;
+  constructor(message: string, file: string, line: number, column: number);
+}
+/**
+ * Build a {@link CodegenDiagnosticError} whose message includes the source
+ * location and whose `file`/`line`/`column` properties are set from the
+ * ts-morph `Node`'s position in its source file.
+ *
+ * Message format: `@lunora/codegen: &lt;detail> (&lt;file>:&lt;line>:&lt;column>)`
+ *
+ * `meta` is merged onto the returned error for callers that also carry the
+ * project-wide `LunoraError` envelope (`code`/`name`/`status`) — it never
+ * touches `file`/`line`/`column`, and the error stays an instance of
+ * {@link CodegenDiagnosticError} so the Vite overlay's `instanceof` location
+ * lookup is unaffected.
+ */
+declare const diagnosticAt: (node: Node, detail: string, meta?: Record<string, unknown>) => CodegenDiagnosticError;
+/** The only file agents may be declared in — mirrors `lunora/workflows.ts`. */
+declare const AGENTS_FILENAME = "agents.ts";
+/**
+ * Discover every agent the project declares: exported `defineAgent()` calls in
+ * `lunora/agents.ts`. Returns `[]` when the file doesn't exist. Only four things
+ * are read statically — the optional `name` override (wrangler `workflows[].name`),
+ * the optional `publicRun` opt-in (the `agents:agentRun` capability gate), the
+ * presence of a `voice` block (which turns on the voice-session Durable Object),
+ * and the presence of an `onEmail` mapper (which wires the worker `email()`
+ * handler); the rest of the agent config (model / tools / memory / voice models /
+ * the `onEmail` closure body) is runtime-only, so codegen never evaluates it.
+ */
+declare const discoverAgents: (project: Project, lunoraDirectory: string) => AgentIR[];
+/**
+ * Discover `ctx.authApi.&lt;method>(...)` (and bare `authApi.&lt;method>(...)`) calls
+ * under the lunora source directory and attribute each to the exported function
+ * (and file) performing it. Calls outside an exported declaration are dropped.
+ */
+declare const discoverAuthApiCalls: (project: Project, lunoraDirectory: string) => AuthApiCallIR[];
+/** The only file containers may be declared in — mirrors `lunora/crons.ts`. */
+declare const CONTAINERS_FILENAME = "containers.ts";
+/**
+ * Discover every container the project declares: exported `defineContainer()`
+ * calls in `lunora/containers.ts`. Returns `[]` when the file doesn't exist.
+ * Wrangler-relevant fields (`image`, `instanceType`, `maxInstances`, `name`)
+ * must be static literals; runtime-only fields (`env`, `sleepAfter`, …) may be
+ * any expression since the generated class imports the definition object.
+ */
+declare const discoverContainers: (project: Project, lunoraDirectory: string) => ContainerIR[];
+/**
+ * Scan every `.ts` file under `lunoraDir` for `cronJobs()` builder registrations
+ * (`crons.interval(...)`, `crons.daily(...)`, `crons.cron(...)`, …) and lift them
+ * into {@link CronJobIR}. Schedules are compiled to standard cron expressions;
+ * function references are resolved to their `namespace:fn` dispatch path, while a
+ * `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
@@ -2748,458 +3235,6 @@ declare const emitOpenRpc: (input: OpenRpcEmitInput) => string;
  * the object returned by {@link buildOpenRpcDocument} (reused, never recomputed).
  */
 declare const emitOpenRpcModule: (document_: Record<string, unknown>) => string;
-/**
- * The canonical capability list. **Order is load-bearing** for the `emit-app.ts`
- * long-tail: the fluent methods are emitted in the order the `appMethod`-bearing
- * rows appear here, so this array is ordered to reproduce the original
- * `LONG_TAIL` sequence (ai, analytics, browser, hyperdrive, images, kv, payment,
- * r2sql, vectors). The `serverCtxField` rows are referenced by name in the ctx
- * interface templates, so their order here is not output-affecting.
- */
-declare const CAPABILITY_ROWS: readonly [{
-  readonly contextProperty: "access";
-  readonly key: "access";
-  readonly moduleSpecifier: "@lunora/cloudflare-access";
-}, {
-  readonly appMethod: {
-    readonly configKey: "ai";
-    readonly doc: "Override the Workers AI binding backing `ctx.ai` (defaults to `env.AI`).";
-    readonly method: "ai";
-  };
-  readonly contextProperty: "ai";
-  readonly key: "ai";
-  readonly moduleSpecifier: "@lunora/ai";
-}, {
-  readonly appMethod: {
-    readonly configKey: "analytics";
-    readonly doc: "Override the Analytics Engine dataset backing `ctx.analytics` (defaults to `env.ANALYTICS`).";
-    readonly method: "analytics";
-  };
-  readonly contextProperty: "analytics";
-  readonly key: "analytics";
-  readonly moduleSpecifier: "@lunora/bindings/analytics";
-  readonly serverCtxField: {
-    readonly field: "\n    /** Analytics Engine telemetry sink. Fire-and-forget and sampled; do not read it back in-handler. */\n    readonly analytics: import(\"@lunora/bindings/analytics\").AnalyticsClient;";
-    readonly tier: "every";
-  };
-}, {
-  readonly appMethod: {
-    readonly configKey: "browser";
-    readonly doc: "Override the Browser Rendering binding backing `ctx.browser` (defaults to `env.BROWSER`).";
-    readonly method: "browser";
-  };
-  readonly contextProperty: "browser";
-  readonly key: "browser";
-  readonly moduleSpecifier: "@lunora/browser";
-  readonly serverCtxField: {
-    readonly field: "\n    /** Browser Rendering (screenshots/PDF/scrape). Non-deterministic — available only in actions. */\n    readonly browser: import(\"@lunora/browser\").Browser;";
-    readonly tier: "action";
-  };
-}, {
-  readonly contextProperty: "containers";
-  readonly key: "container";
-  readonly moduleSpecifier: "@lunora/container";
-}, {
-  readonly contextProperty: "flags";
-  readonly key: "flags";
-  readonly moduleSpecifier: "@lunora/flags";
-}, {
-  readonly appMethod: {
-    readonly configKey: "sql";
-    readonly doc: "Wire the Hyperdrive SQL client backing `ctx.sql` — build it with `createHyperdrive` + `fromPostgresJs`/`fromNodePg`/`fromMysql2`.";
-    readonly method: "hyperdrive";
-  };
-  readonly contextProperty: "sql";
-  readonly key: "hyperdrive";
-  readonly moduleSpecifier: "@lunora/hyperdrive";
-  readonly serverCtxField: {
-    readonly field: "\n    /**\n     * External database access via Hyperdrive. Non-deterministic — available only in actions. Writes here are NOT tracked by Lunora live queries; subscriptions will not re-run on external DB changes.\n     */\n    readonly sql: import(\"@lunora/hyperdrive\").SqlClient;";
-    readonly tier: "action";
-  };
-}, {
-  readonly appMethod: {
-    readonly configKey: "images";
-    readonly doc: "Override the Images binding backing `ctx.images` (defaults to `env.IMAGES`).";
-    readonly method: "images";
-  };
-  readonly contextProperty: "images";
-  readonly key: "images";
-  readonly moduleSpecifier: "@lunora/bindings/images";
-  readonly serverCtxField: {
-    readonly field: "\n    /** Cloudflare Images transforms (resize/format/optimize). Non-deterministic — available only in actions. */\n    readonly images: import(\"@lunora/bindings/images\").Images;";
-    readonly tier: "action";
-  };
-}, {
-  readonly appMethod: {
-    readonly configKey: "kv";
-    readonly doc: "Override the Workers KV binding backing `ctx.kv` (defaults to `env.KV`).";
-    readonly method: "kv";
-  };
-  readonly contextProperty: "kv";
-  readonly key: "kv";
-  readonly moduleSpecifier: "@lunora/bindings/kv";
-  readonly serverCtxField: {
-    readonly field: "\n    readonly kv: import(\"@lunora/bindings/kv\").Kv;";
-    readonly tier: "every";
-  };
-}, {
-  readonly key: "mail";
-  readonly moduleSpecifier: "@lunora/mail";
-}, {
-  readonly contextProperty: "notify";
-  readonly key: "notify";
-  readonly moduleSpecifier: "@lunora/notify";
-}, {
-  readonly appMethod: {
-    readonly configKey: "payment";
-    readonly doc: "Wire the payment options backing `ctx.payments`.";
-    readonly method: "payment";
-  };
-  readonly contextProperty: "payments";
-  readonly key: "payments";
-  readonly moduleSpecifier: "@lunora/payment";
-}, {
-  readonly appMethod: {
-    readonly configKey: "x402";
-    readonly doc: "Wire the x402 agent-wallet pay rail backing `ctx.x402` — a payment-enabled `fetch` that answers `402` challenges under a mandatory spend policy (ActionCtx-only; spends real funds).";
-    readonly method: "x402";
-  };
-  readonly contextProperty: "x402";
-  readonly key: "x402";
-  readonly moduleSpecifier: "@lunora/x402/pay";
-}, {
-  readonly contextProperty: "pipelines";
-  readonly key: "pipelines";
-  readonly moduleSpecifier: "@lunora/bindings/pipelines";
-  readonly serverCtxField: {
-    readonly field: "\n    /** Pipelines ingestion sink (durable, R2-backed). Fire-and-forget and batched; do not read it back in-handler. */\n    readonly pipelines: import(\"@lunora/bindings/pipelines\").PipelineClient;";
-    readonly tier: "action";
-  };
-}, {
-  readonly appMethod: {
-    readonly configKey: "r2sql";
-    readonly doc: "Wire the R2 SQL client backing `ctx.r2sql` — build it with `createR2Sql({ accountId, apiToken, bucket })` (defaults to env `R2_SQL_TOKEN` / `R2_SQL_ACCOUNT_ID` / `R2_SQL_BUCKET`).";
-    readonly method: "r2sql";
-  };
-  readonly contextProperty: "r2sql";
-  readonly key: "r2sql";
-  readonly moduleSpecifier: "@lunora/bindings/r2sql";
-  readonly serverCtxField: {
-    readonly field: "\n    /**\n     * R2 SQL over Apache Iceberg tables (window functions, DISTINCT, set operations). Non-deterministic — available only in actions. Reads here are NOT tracked by Lunora live queries.\n     */\n    readonly r2sql: import(\"@lunora/bindings/r2sql\").R2SqlClient;";
-    readonly tier: "action";
-  };
-}, {
-  readonly contextProperty: "scheduler";
-  readonly key: "scheduler";
-  readonly moduleSpecifier: "@lunora/scheduler";
-}, {
-  readonly contextProperty: "storage";
-  readonly key: "storage";
-  readonly moduleSpecifier: "@lunora/storage";
-}, {
-  readonly appMethod: {
-    readonly configKey: "vectors";
-    readonly doc: "Wire the Vectorize index map backing `ctx.vectors`.";
-    readonly method: "vectors";
-  };
-  readonly contextProperty: "vectors";
-  readonly key: "vectors";
-  readonly moduleSpecifier: "@lunora/bindings/vectors";
-}, {
-  readonly contextProperty: "workflows";
-  readonly key: "workflows";
-  readonly moduleSpecifier: "@lunora/workflow";
-}];
-/** The literal union of every capability id — the single source of truth for `FeatureUsage`'s keys (so they cannot drift). */
-type CapabilityKey = (typeof CAPABILITY_ROWS)[number]["key"];
-/** The default codegen target — today's behavior, byte-identical goldens. */
-declare const DEFAULT_TARGET = "cloudflare";
-/**
- * Read `target` from `&lt;projectRoot>/lunora.json`.
- *
- * This lives in `@lunora/codegen` rather than `@lunora/config` — where the rest
- * of the `lunora.json` reading lives — because `@lunora/config` depends on
- * `@lunora/codegen`, not the reverse. Putting it there and importing it here
- * would invert that edge, so config delegates to this instead and there is
- * still exactly one parser for the key.
- *
- * Best-effort and deliberately unvalidated: a missing file, malformed JSONC, or
- * a non-string value all collapse to `undefined`, because those are shape
- * errors rather than a name the user meant. An unrecognized *name* is returned
- * as-is so the caller's registry lookup rejects it — swallowing a typo into the
- * default would ship an app to the wrong provider.
- * @param projectRoot Directory containing `lunora.json`.
- * @returns the declared target, or `undefined` when none is usable.
- */
-declare const readProjectTarget: (projectRoot: string) => string | undefined;
-/**
- * The target codegen should emit for: an explicit option wins, then
- * `lunora.json`, then the default.
- *
- * `runCodegen` applies this itself so a caller that forgets to pass a target
- * still emits the surface the project declared. That default matters more than
- * it looks: a call site that silently omits the target emits the *default*
- * surface with no diagnostic to notice, and the mismatch only shows up at
- * runtime on the deployed app.
- * @param projectRoot Directory containing `lunora.json`.
- * @param explicit A caller-supplied target, if any.
- * @returns the resolved target id — not guaranteed to be registered.
- */
-declare const resolveCodegenTarget: (projectRoot: string, explicit?: string) => string;
-/**
- * The target ids codegen can gate against.
- *
- * Exported so `@lunora/config` can assert that its driver registry and this
- * capability-matrix registry name the same targets. They are two id spaces for one
- * concept: a target that ships a driver but no matrix passes the CLI's
- * validation and then emits an un-gated surface, and one with a matrix but no
- * driver gates a surface nothing can deploy. Today both hold exactly
- * `cloudflare`, which is why nothing has noticed.
- * @returns the registered matrix ids, sorted.
- */
-declare const platformMatrixIds: () => ReadonlyArray<string>;
-/** An advisor-style diagnostic about a target's platform capabilities. */
-interface PlatformDiagnostic {
-  /** The codegen capability this concerns, when it is feature-specific. */
-  feature?: CapabilityKey;
-  /** Severity. `platform_unsupported_feature` and `platform_unknown_target` are both errors — each drops or misdirects an emitted surface. */
-  level: "error" | "warn";
-  /** Human-readable explanation of the gap. */
-  message: string;
-  /** The lint id: `platform_unsupported_feature` or `platform_unknown_target`. */
-  name: "platform_unknown_target" | "platform_unsupported_feature";
-  /** How to resolve it. */
-  remediation: string;
-  /** The requested deploy target. */
-  target: string;
-}
-/**
- * Committed, tracked baseline file holding the blessed structural schema
- * snapshot the pre-deploy drift gate diffs against. Lives in `lunora/` (NOT the
- * gitignored `_generated/`) so it is committed alongside `schema.ts`. Leading
- * dot keeps it tucked away next to the schema it describes.
- */
-declare const SCHEMA_SNAPSHOT_FILENAME = ".lunora-schema.json";
-/**
- * Construct the ts-morph `Project` codegen discovers over. Prefers the user's
- * `tsconfig.json` (when one is found walking up from `lunoraDirectory`) so
- * cross-file type resolution and path aliases work; falls back to an isolated
- * project otherwise. This is the exact construction {@link runCodegen} uses
- * when no `project` is injected — exported so a long-lived caller (the Vite
- * dev-loop) can build one once and reuse it across runs via
- * {@link refreshCodegenProject} instead of re-parsing the user's whole TS
- * program on every save.
- */
-declare const createCodegenProject: (lunoraDirectory: string) => Project;
-/**
- * Synchronise a reused {@link createCodegenProject} Project with the current
- * on-disk state of `lunoraDirectory`, so the next {@link runCodegen} sees the
- * same files a freshly-constructed Project would — without re-parsing the whole
- * TS program. Adds any on-disk source file the Project doesn't yet have, and
- * `refreshFromFileSystemSync()`es the ones it does (picking up edits); then
- * removes Project source files under `lunoraDirectory` that no longer exist on
- * disk (the classic stale-deleted-file cache bug).
- *
- * Files outside `lunoraDirectory` (e.g. those pulled in by the user's tsconfig)
- * are left untouched — they back type resolution and rarely change in the
- * dev-loop; a tsconfig change invalidates the whole cached Project upstream.
- */
-declare const refreshCodegenProject: (project: Project, lunoraDirectory: string) => void;
-/**
- * Top-level codegen entry. Parses `&lt;projectRoot>/lunora/schema.ts` and every
- * function file under `&lt;projectRoot>/lunora/`, then writes
- * `_generated/{api,server,dataModel}.ts` next to them.
- *
- * When `LUNORA_CODEGEN_TIMING` is set (truthy), a single diagnostic summary
- * line is written to stderr with the total wall time and the discovery-vs-emit
- * split — opt-in instrumentation that is otherwise zero-cost and side-effect-free
- * on the returned {@link CodegenResult}.
- */
-declare const runCodegen: (options: CodegenOptions) => CodegenResult;
-interface CodegenOptions {
-  /**
-   * Which machine-readable API spec(s) to emit into `_generated/`.
-   *
-   * `"openapi"` (the default) writes only `openapi.json` (OpenAPI 3.1; covers
-   * both the RPC functions and `httpRouter()` REST routes). `"openrpc"` writes
-   * only `openrpc.json` (OpenRPC 1.x; the RPC functions only — OpenRPC cannot
-   * represent REST routes). `"both"` writes both files; `"none"` writes neither.
-   *
-   * Regardless of the choice, `CodegenResult.generated.openApi` and `.openRpc`
-   * always carry the rendered string (computation is cheap and pure); only the
-   * on-disk write is gated by this option.
-   */
-  apiSpec?: "both" | "none" | "openapi" | "openrpc";
-  /**
-   * When true, run discovery + emit (so any schema/function parse error
-   * surfaces) but skip writing files to `_generated/`. The returned
-   * `outputDirectory` is still the path that *would* have been written.
-   */
-  dryRun?: boolean;
-  /**
-   * Run the static schema advisor (unindexed FKs, …) during codegen.
-   * Defaults to `true`. When `false`, `CodegenResult.advisories` is empty.
-   * Computed regardless of `dryRun`; codegen never prints them — see
-   * {@link CodegenResult.advisories}.
-   */
-  lint?: boolean;
-  /** Override the lunora subdirectory name. Defaults to `"lunora"`. */
-  lunoraDirectory?: string;
-  /**
-   * Reuse a previously-constructed ts-morph {@link Project} instead of building
-   * a fresh one each run. The caller owns refreshing its source files from disk
-   * (see {@link refreshCodegenProject}) — codegen does not re-read changed files
-   * off an injected Project. Built via {@link createCodegenProject} when absent.
-   * Used by the Vite dev-loop to avoid re-parsing the whole TS program on every
-   * save; omit it (CLI one-shot path) to get the default fresh-Project behaviour.
-   */
-  project?: Project;
-  /** Project root containing the `lunora/` directory. */
-  projectRoot: string;
-  /**
-   * The deploy target codegen tailors the emitted `ctx.*` surface to.
-   * Defaults to `"cloudflare"` — whose capability matrix marks every feature
-   * native or emulated, so the default output is unchanged (byte-identical
-   * goldens). A target that marks a used feature unsupported omits its
-   * `ctx.*` surface and reports it in {@link CodegenResult.platformDiagnostics}.
-   * Only `"cloudflare"` is registered until other per-target `@lunora/platform`
-   * matrices land; an unknown target emits the full surface un-gated and a
-   * `platform_unknown_target` diagnostic.
-   */
-  target?: string;
-  /**
-   * Re-bless the committed schema-drift baseline (`lunora/.lunora-schema.json`)
-   * with the current structural snapshot. The baseline is ALWAYS written on
-   * first capture (when the file is absent); set this to overwrite an existing
-   * one — e.g. after the developer has added the data migration that justifies
-   * a breaking change. Ignored when `dryRun` is true.
-   */
-  updateSchemaBaseline?: boolean;
-  /**
-   * Committed `wrangler.jsonc` `vars` entries that hold plaintext secrets — the
-   * `plaintext_secret_in_wrangler_vars` lint input. Produced by `@lunora/config`
-   * (which reads `wrangler.jsonc`) and threaded through by the CLI / Vite plugin;
-   * codegen only forwards it to the advisor. Absent when no wrangler config is
-   * present or the caller doesn't scan it.
-   */
-  wranglerVariables?: ReadonlyArray<WranglerVariableIR>;
-}
-interface CodegenResult {
-  /**
-   * The normalized advisor evidence the findings were produced from, so a
-   * caller can score it into a health map (`scoreAdvisor`) without re-running
-   * discovery. `undefined` under `lint: false`.
-   *
-   * Deliberately not scored here: the map carries a `generatedAt` stamp, and
-   * codegen's result stays a pure function of the sources.
-   */
-  advisorContext?: LintContext;
-  /**
-   * Static schema advisor findings (e.g. unindexed foreign keys) produced
-   * this run. Empty when `lint` is `false` or the schema is clean. Codegen
-   * does not print these itself — each caller presents them through its own
-   * channel (the CLI logger, the vite overlay, the studio Advisors table).
-   * `formatAdvisories` is exported for a plain multi-line rendering.
-   */
-  advisories: ReadonlyArray<Finding>;
-  /**
-   * Agents discovered from `defineAgent` exports in `lunora/agents.ts` — the
-   * list the config layer reconciles into wrangler's `workflows[]` array (an
-   * agent compiles onto a Cloudflare Workflow). Agents are NOT Durable Objects,
-   * so this adds no binding or migration. Empty when the project declares none.
-   */
-  agents: ReadonlyArray<AgentIR>;
-  /**
-   * Containers discovered from `defineContainer` exports in
-   * `lunora/containers.ts` — the list the config layer reconciles into
-   * wrangler's `containers[]`, `CONTAINER_*` Durable Object bindings, and
-   * migration classes. Empty when the project declares no containers.
-   */
-  containers: ReadonlyArray<ContainerIR>;
-  /**
-   * Deduplicated cron schedules discovered from `cronJobs()` definitions —
-   * the array the vite plugin reconciles into `wrangler.jsonc`'s
-   * `triggers.crons`. Empty when the project declares no crons.
-   */
-  cronTriggers: ReadonlyArray<string>;
-  generated: {
-    /** WorkflowEntrypoint classes for declared agents (`_generated/agents.ts`); `""` (and not written) when no agents are declared. */
-    agents: string;
-    api: string;
-    /** Fluent worker-composition builder (`_generated/app.ts`) — `defineApp()`. Always written. */
-    app: string;
-    /** Partial-replication collection factories (`_generated/collections.ts`); `""` (and not written) unless the project declares shapes and installs `@lunora/db`. */
-    collections: string;
-    /** Container DO classes (`_generated/containers.ts`); `""` (and not written) when no containers are declared. */
-    containers: string;
-    crons: string;
-    dataModel: string;
-    drizzleGlobal: string;
-    drizzleShard: string;
-    functions: string;
-    /** OpenAPI 3.1.0 document (`_generated/openapi.json`), pretty-printed JSON. */
-    openApi: string;
-    /**
-     * OpenAPI document as an importable TS module (`_generated/openapi.ts`) —
-     * `export const openApiSpec`, the worker imports it for
-     * `createWorker({ openApiSpec })`. Same document as `openApi`. Written
-     * alongside `openapi.json` whenever `apiSpec` includes `openapi`.
-     */
-    openApiModule: string;
-    /** OpenRPC 1.x document (`_generated/openrpc.json`), pretty-printed JSON. Always computed; written only when `apiSpec` includes `openrpc`. */
-    openRpc: string;
-    /**
-     * OpenRPC document as an importable TS module (`_generated/openrpc.ts`) —
-     * `export const openRpcSpec`, for `createWorker({ openRpcSpec })`. Same
-     * document as `openRpc`. Written alongside `openrpc.json` whenever
-     * `apiSpec` includes `openrpc`.
-     */
-    openRpcModule: string;
-    /** Push-consumer queue registry (`_generated/queues.ts`); `""` (and not written) when no push queues are declared. */
-    queues: string;
-    /** Project-bound seed client (`_generated/seed.ts`); `""` (and not written) when `@lunora/seed` is not a declared dependency. */
-    seed: string;
-    server: string;
-    shard: string;
-    /** Static vector-index registry (`_generated/vectors.ts`) — `LUNORA_VECTOR_INDEXES`. Empty array body when the schema declares none. */
-    vectors: string;
-    /** WorkflowEntrypoint classes (`_generated/workflows.ts`); `""` (and not written) when no workflows are declared. */
-    workflows: string;
-  };
-  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>;
-}
 /**
  * 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
@@ -3291,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, readPackageDependencies, 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 };