@lunora/codegen 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/index.d.mts

@@ -25,6 +25,15 @@ interface ValidatorIR {
   bucket?: string;
   /** Column modifiers (`.unique()`, `.default()`, `.nullable()`, …) when present. */
   column?: ColumnMetaIR;
+  /**
+  * `true` when this validator carries a `.check(...)` refinement. The predicate
+  * is a runtime closure the AST→IR step can't represent, so the node keeps its
+  * base `kind` but records the refinement's presence here. The AOT args-validator
+  * compiler declines any node with this flag (compiling it would silently skip
+  * the predicate). `.meta(...)` is pure metadata with no parse effect and does
+  * NOT set this.
+  */
+  hasRefinement?: boolean;
   /** For `v.optional(inner)` / `v.array(inner)`. */
   inner?: ValidatorIR;
   /** For `v.record(key, value)`. */
@@ -126,10 +135,23 @@ interface TableIR {
     field: string;
     kind: "shardBy";
   };
+  /** Set when the chain carried `.softDelete()` — the marker column's name (default `deletedAt`). The column is injected into `shape` so `Doc_*` carries it. */
+  softDelete?: {
+    field: string;
+  };
   /** Vector indexes declared inline via `.vectorize()` (DSL Shape A). */
   vectorIndexes: ReadonlyArray<VectorIndexIR>;
 }
+/** The Cloudflare DO data-residency jurisdictions the schema may declare. Canonical literal set for the codegen package. */
+type JurisdictionIR = "eu" | "fedramp" | "us";
 interface SchemaIR {
+  /**
+  * Cloudflare data-residency jurisdiction declared via
+  * `defineSchema(...).jurisdiction("…")`. Emitted into the generated worker's
+  * `createWorker({ jurisdiction })` (and `ctx.scheduler` / `ctx.containers`).
+  * Absent ⇒ un-pinned.
+  */
+  jurisdiction?: JurisdictionIR;
   tables: ReadonlyArray<TableIR>;
   /** All vector indexes (inline Shape A hoisted + standalone Shape B), flattened. */
   vectorIndexes: ReadonlyArray<VectorIndexIR>;
@@ -384,6 +406,26 @@ interface NondeterministicCallIR {
   line: number;
 }
 /**
+* One `ctx.r2sql` access lexically inside a `query`/`mutation` handler — the
+* `r2sql_outside_action` advisor lint input. Structurally identical to the
+* advisor's `AdvisorR2sqlCall` (same field set) so values pass straight through
+* `lintSchema` without conversion, exactly as `NondeterministicCallIR` does.
+* Only `query`/`mutation` handlers are recorded; `action(...)` is the intended
+* home for `ctx.r2sql` and is skipped.
+*/
+interface R2sqlCallIR {
+  /** The accessed `ctx.r2sql` surface, e.g. `ctx.r2sql.query` / `ctx.r2sql.from`. */
+  callee: string;
+  /** Export binding name of the function performing the access. */
+  exportName: string;
+  /** Source file relative to the lunora dir, without extension (the api namespace). */
+  file: string;
+  /** Which procedure kind the access lives in — only `query`/`mutation` handlers are recorded. */
+  kind: "mutation" | "query";
+  /** 1-based line of the access, or `0` when unknown. */
+  line: number;
+}
+/**
 * Per-procedure RLS usage snapshot, produced by `discoverRlsProcedures` for the
 * `rls_uncovered_table` advisor lint. Structurally identical to
 * `AdvisorRlsProcedure` (they share the same field set) so values pass straight
@@ -686,7 +728,7 @@ interface ProjectIR {
 * pass straight through without conversion. Returns the findings; surfacing them
 * (console, error overlay, studio Advisors table) is the caller's choice.
 */
-declare const lintSchema: (schema: SchemaIR, queries?: ReadonlyArray<QueryReadIR>, inserts?: ReadonlyArray<InsertWriteIR>, authApiCalls?: ReadonlyArray<AuthApiCallIR>, rlsProcedures?: ReadonlyArray<RlsProcedureIR>, containers?: ReadonlyArray<ContainerIR>, workflows?: ReadonlyArray<WorkflowIR>, workflowCalls?: ReadonlyArray<WorkflowCallIR>, maskProcedures?: ReadonlyArray<MaskProcedureIR>, nondeterministicCalls?: ReadonlyArray<NondeterministicCallIR>, procedureProtections?: ReadonlyArray<ProcedureMiddlewareIR>, argumentValidators?: ReadonlyArray<ArgumentValidatorIR>, secretLiterals?: ReadonlyArray<SecretLiteralIR>, sqlInterpolations?: ReadonlyArray<SqlInterpolationIR>, adminRoutes?: ReadonlyArray<AdminRouteIR>) => Finding[];
+declare const lintSchema: (schema: SchemaIR, queries?: ReadonlyArray<QueryReadIR>, inserts?: ReadonlyArray<InsertWriteIR>, authApiCalls?: ReadonlyArray<AuthApiCallIR>, rlsProcedures?: ReadonlyArray<RlsProcedureIR>, containers?: ReadonlyArray<ContainerIR>, workflows?: ReadonlyArray<WorkflowIR>, workflowCalls?: ReadonlyArray<WorkflowCallIR>, maskProcedures?: ReadonlyArray<MaskProcedureIR>, nondeterministicCalls?: ReadonlyArray<NondeterministicCallIR>, procedureProtections?: ReadonlyArray<ProcedureMiddlewareIR>, argumentValidators?: ReadonlyArray<ArgumentValidatorIR>, secretLiterals?: ReadonlyArray<SecretLiteralIR>, sqlInterpolations?: ReadonlyArray<SqlInterpolationIR>, adminRoutes?: ReadonlyArray<AdminRouteIR>, r2sqlCalls?: ReadonlyArray<R2sqlCallIR>) => Finding[];
 /**
 * Render advisor findings as a single multi-line string for console surfacing:
 * a one-line summary header followed by one `[LEVEL] name: detail` line per
@@ -711,8 +753,14 @@ declare class CodegenDiagnosticError extends Error {
 * ts-morph `Node`'s position in its source file.
 *
 * Message format: `@lunora/codegen: &lt;detail> (&lt;file>:&lt;line>:&lt;column>)`
+*
+* `meta` is merged onto the returned error for callers that also carry the
+* project-wide `LunoraError` envelope (`code`/`name`/`status`) — it never
+* touches `file`/`line`/`column`, and the error stays an instance of
+* {@link CodegenDiagnosticError} so the Vite overlay's `instanceof` location
+* lookup is unaffected.
 */
-declare const diagnosticAt: (node: Node, detail: string) => CodegenDiagnosticError;
+declare const diagnosticAt: (node: Node, detail: string, meta?: Record<string, unknown>) => CodegenDiagnosticError;
 /**
 * Discover `ctx.authApi.&lt;method>(...)` (and bare `authApi.&lt;method>(...)`) calls
 * under the lunora source directory and attribute each to the exported function
@@ -803,6 +851,19 @@ declare const discoverNondeterministicCalls: (project: Project, lunoraDirectory:
 * dropping the rest keeps the lint input small.
 */
 declare const discoverQueries: (project: Project, lunoraDirectory: string) => QueryReadIR[];
+/**
+* Discover `ctx.r2sql` accesses lexically inside the handler body of every
+* exported `query(...)` / `mutation(...)` registration under the lunora source
+* directory — the `r2sql_outside_action` lint input. `action(...)` (and
+* `stream(...)`) registrations are intentionally skipped: R2 SQL is the
+* external, non-reactive surface that belongs in actions.
+*
+* Traversal is scoped to the handler node (not the whole declaration), mirroring
+* `discoverNondeterministicCalls` — so a `ctx.r2sql` touch in a sibling helper
+* outside the handler is not attributed to the query/mutation. One
+* {@link R2sqlCallIR} is produced per access site.
+*/
+declare const discoverR2sqlCalls: (project: Project, lunoraDirectory: string) => R2sqlCallIR[];
 declare const discoverRlsProcedures: (project: Project, lunoraDirectory: string) => RlsProcedureIR[];
 /**
 * Aggregate the schema-wide RLS metadata the studio's read-only inspector reads:
@@ -822,7 +883,7 @@ declare const discoverRlsMetadata: (project: Project, lunoraDirectory: string) =
 * Load `&lt;projectRoot>/lunora/schema.ts`, find `defineSchema({...})`, and
 * return a structural IR. Throws if the file or call cannot be found.
 */
-declare const discoverSchema: (project: Project, schemaPath: string) => SchemaIR;
+declare const discoverSchema: (project: Project, schemaPath: string, projectRoot?: string) => SchemaIR;
 /**
 * Aggregate the schema-wide storage-rule metadata the studio's inspector reads:
 * every statically-discovered `(bucket, on, prefix, procedure)` entry across all
@@ -877,6 +938,8 @@ interface EmitServerOptions {
   hasPayments?: boolean;
   /** A `lunora/` source uses `@lunora/pipelines` / `ctx.pipelines` — wires `ctx.pipelines` onto ActionCtx only. */
   hasPipelines?: boolean;
+  /** A `lunora/` source uses `@lunora/r2sql` / `ctx.r2sql` — wires `ctx.r2sql` onto ActionCtx only. */
+  hasR2sql?: boolean;
   schema?: SchemaIR;
   storageRuleBuckets?: ReadonlyArray<string>;
   /** The project depends on the `lunora` umbrella — import base packages via its subpaths. */
@@ -893,12 +956,13 @@ declare const emitServer: ({
   hasKv,
   hasPayments,
   hasPipelines,
+  hasR2sql,
   schema,
   storageRuleBuckets,
   useUmbrella,
   workflows
 }?: EmitServerOptions) => string;
-declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>) => string;
+declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>, useUmbrella?: boolean) => string;
 /**
 * Storage-column map per table for the file browser: `{ table: [field, …] }` for
 * every field declared `v.storage(...)` (unwrapping `v.optional(...)`). The
@@ -916,7 +980,7 @@ declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?:
 * `containers[].class_name` to be exported by the deployed worker. Returns ""
 * when the project declares no containers (the file is not written then).
 */
-declare const emitContainers: (containers: ReadonlyArray<ContainerIR>) => string;
+declare const emitContainers: (containers: ReadonlyArray<ContainerIR>, jurisdiction?: JurisdictionIR) => string;
 /**
 * Emit `_generated/workflows.ts` — one `WorkflowEntrypoint` class per
 * `defineWorkflow` export, each a thin subclass of `LunoraWorkflow`
@@ -941,6 +1005,8 @@ interface EmitShardOptions {
   /** A `lunora/` source reads `ctx.kv` — wires `ctx.kv` onto every ctx. */
   hasKv?: boolean;
   hasPayments?: boolean;
+  /** A `lunora/` source reads `ctx.r2sql` (R2 SQL) — wires `ctx.r2sql` onto the ActionCtx only. */
+  hasR2sql?: boolean;
   maskMetadata?: MaskMetadataIR;
   rlsMetadata?: RlsMetadataIR;
   schema: SchemaIR;
@@ -960,6 +1026,7 @@ declare const emitShard: ({
   hasImages,
   hasKv,
   hasPayments,
+  hasR2sql,
   maskMetadata,
   rlsMetadata,
   schema,
@@ -1049,6 +1116,8 @@ interface EmitAppOptions {
   hasKv: boolean;
   /** App uses `@lunora/payment` / `ctx.payments` → emit `.payment()`. */
   hasPayments: boolean;
+  /** App uses `@lunora/r2sql` / `ctx.r2sql` → emit `.r2sql()`. */
+  hasR2sql: boolean;
   /** App imports `@lunora/scheduler` / declares crons → emit `.scheduler()`. */
   hasScheduler: boolean;
   /** App uses `@lunora/storage` → emit `.storage()` (DO `ctx.storage` + studio file browser). */
@@ -1057,6 +1126,8 @@ interface EmitAppOptions {
   hasVectors: boolean;
   /** App declares Cloudflare Workflows (`defineWorkflow`) → wire `options.workflowsClient` so the studio's workflow-instance proxy can reach the CF REST API. */
   hasWorkflow: boolean;
+  /** Schema declares `.jurisdiction("…")` → pin every DO the worker reaches (shards, fan-out, scheduler, containers) to the Cloudflare data-residency jurisdiction. */
+  jurisdiction?: JurisdictionIR;
   /** Project depends on the unscoped `lunorash` umbrella → import the runtime via `lunorash/runtime` instead of `@lunora/runtime`. */
   useUmbrella: boolean;
   /** An OpenAPI spec is emitted (`openapi.ts`) → wire `openApiSpec` into the worker. */
@@ -1201,6 +1272,19 @@ interface TableSnapshot {
 }
 /** The committed baseline — a deterministic structural view of the whole schema. */
 interface SchemaSnapshot {
+  /**
+  * Cloudflare DO data-residency jurisdiction declared via `.jurisdiction("…")`,
+  * or absent. Tracked because changing it strands all existing Durable Object
+  * data (a DO name maps to a different ID per jurisdiction). Optional, so old
+  * baselines written before this field parse cleanly (absent ⇒ undefined).
+  *
+  * Typed as a plain `string` (not the authoring union) on purpose: this is
+  * STORED data that a newer Lunora may have written with a jurisdiction this
+  * version doesn't yet know. Preserving the raw value keeps the breaking
+  * `changedJurisdiction` diff correct under a downgrade — coercing an unknown
+  * value to `undefined` would fail OPEN and hide the most destructive change.
+  */
+  jurisdiction?: string;
   /** Sorted list of every declared `defineMigration` id at capture time. */
   migrationIds: ReadonlyArray<string>;
   /** Table name → {@link TableSnapshot}, keys sorted for stable serialization. */
@@ -1214,7 +1298,7 @@ interface DriftChange {
   /** Human-readable, actionable description (used in the gate message). */
   summary: string;
   /** A machine-readable change discriminator. */
-  type: "addedIndex" | "addedOptionalField" | "addedRelation" | "addedRequiredField" | "addedTable" | "changedFieldKind" | "changedIndex" | "changedShardMode" | "fieldOptionalToRequired" | "fieldRequiredToOptional" | "removedField" | "removedIndex" | "removedRelation" | "removedTable";
+  type: "addedIndex" | "addedOptionalField" | "addedRelation" | "addedRequiredField" | "addedTable" | "changedJurisdiction" | "changedFieldKind" | "changedIndex" | "changedShardMode" | "fieldOptionalToRequired" | "fieldRequiredToOptional" | "removedField" | "removedIndex" | "removedRelation" | "removedTable";
 }
 /** The result of diffing two snapshots: every classified change. */
 interface SchemaDrift {
@@ -1316,6 +1400,11 @@ declare const refreshCodegenProject: (project: Project, lunoraDirectory: string)
 * Top-level codegen entry. Parses `&lt;projectRoot>/lunora/schema.ts` and every
 * function file under `&lt;projectRoot>/lunora/`, then writes
 * `_generated/{api,server,dataModel}.ts` next to them.
+*
+* When `LUNORA_CODEGEN_TIMING` is set (truthy), a single diagnostic summary
+* line is written to stderr with the total wall time and the discovery-vs-emit
+* split — opt-in instrumentation that is otherwise zero-cost and side-effect-free
+* on the returned {@link CodegenResult}.
 */
 declare const runCodegen: (options: CodegenOptions) => CodegenResult;
 interface CodegenOptions {
@@ -1470,4 +1559,4 @@ declare const validatorIrToJsonSchema: (validator: ValidatorIR) => JsonSchema;
 */
 declare const LUNORA_ERROR_CODES: ReadonlyArray<string>;
 declare const VERSION = "0.0.0";
-export { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, type FieldSnapshot, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type MaskProcedureIR, type MigrationIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, type QueryReadIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverNondeterministicCalls, discoverQueries, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, formatAdvisories, lintSchema, parseSchemaSnapshot, refreshCodegenProject, runCodegen, schemaFromIr, serializeSchemaSnapshot, validatorIrToJsonSchema };
+export { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, type FieldSnapshot, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type MaskProcedureIR, type MigrationIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, type QueryReadIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverNondeterministicCalls, discoverQueries, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, formatAdvisories, lintSchema, parseSchemaSnapshot, refreshCodegenProject, runCodegen, schemaFromIr, serializeSchemaSnapshot, validatorIrToJsonSchema };

package/dist/index.d.ts

@@ -25,6 +25,15 @@ interface ValidatorIR {
   bucket?: string;
   /** Column modifiers (`.unique()`, `.default()`, `.nullable()`, …) when present. */
   column?: ColumnMetaIR;
+  /**
+  * `true` when this validator carries a `.check(...)` refinement. The predicate
+  * is a runtime closure the AST→IR step can't represent, so the node keeps its
+  * base `kind` but records the refinement's presence here. The AOT args-validator
+  * compiler declines any node with this flag (compiling it would silently skip
+  * the predicate). `.meta(...)` is pure metadata with no parse effect and does
+  * NOT set this.
+  */
+  hasRefinement?: boolean;
   /** For `v.optional(inner)` / `v.array(inner)`. */
   inner?: ValidatorIR;
   /** For `v.record(key, value)`. */
@@ -126,10 +135,23 @@ interface TableIR {
     field: string;
     kind: "shardBy";
   };
+  /** Set when the chain carried `.softDelete()` — the marker column's name (default `deletedAt`). The column is injected into `shape` so `Doc_*` carries it. */
+  softDelete?: {
+    field: string;
+  };
   /** Vector indexes declared inline via `.vectorize()` (DSL Shape A). */
   vectorIndexes: ReadonlyArray<VectorIndexIR>;
 }
+/** The Cloudflare DO data-residency jurisdictions the schema may declare. Canonical literal set for the codegen package. */
+type JurisdictionIR = "eu" | "fedramp" | "us";
 interface SchemaIR {
+  /**
+  * Cloudflare data-residency jurisdiction declared via
+  * `defineSchema(...).jurisdiction("…")`. Emitted into the generated worker's
+  * `createWorker({ jurisdiction })` (and `ctx.scheduler` / `ctx.containers`).
+  * Absent ⇒ un-pinned.
+  */
+  jurisdiction?: JurisdictionIR;
   tables: ReadonlyArray<TableIR>;
   /** All vector indexes (inline Shape A hoisted + standalone Shape B), flattened. */
   vectorIndexes: ReadonlyArray<VectorIndexIR>;
@@ -384,6 +406,26 @@ interface NondeterministicCallIR {
   line: number;
 }
 /**
+* One `ctx.r2sql` access lexically inside a `query`/`mutation` handler — the
+* `r2sql_outside_action` advisor lint input. Structurally identical to the
+* advisor's `AdvisorR2sqlCall` (same field set) so values pass straight through
+* `lintSchema` without conversion, exactly as `NondeterministicCallIR` does.
+* Only `query`/`mutation` handlers are recorded; `action(...)` is the intended
+* home for `ctx.r2sql` and is skipped.
+*/
+interface R2sqlCallIR {
+  /** The accessed `ctx.r2sql` surface, e.g. `ctx.r2sql.query` / `ctx.r2sql.from`. */
+  callee: string;
+  /** Export binding name of the function performing the access. */
+  exportName: string;
+  /** Source file relative to the lunora dir, without extension (the api namespace). */
+  file: string;
+  /** Which procedure kind the access lives in — only `query`/`mutation` handlers are recorded. */
+  kind: "mutation" | "query";
+  /** 1-based line of the access, or `0` when unknown. */
+  line: number;
+}
+/**
 * Per-procedure RLS usage snapshot, produced by `discoverRlsProcedures` for the
 * `rls_uncovered_table` advisor lint. Structurally identical to
 * `AdvisorRlsProcedure` (they share the same field set) so values pass straight
@@ -686,7 +728,7 @@ interface ProjectIR {
 * pass straight through without conversion. Returns the findings; surfacing them
 * (console, error overlay, studio Advisors table) is the caller's choice.
 */
-declare const lintSchema: (schema: SchemaIR, queries?: ReadonlyArray<QueryReadIR>, inserts?: ReadonlyArray<InsertWriteIR>, authApiCalls?: ReadonlyArray<AuthApiCallIR>, rlsProcedures?: ReadonlyArray<RlsProcedureIR>, containers?: ReadonlyArray<ContainerIR>, workflows?: ReadonlyArray<WorkflowIR>, workflowCalls?: ReadonlyArray<WorkflowCallIR>, maskProcedures?: ReadonlyArray<MaskProcedureIR>, nondeterministicCalls?: ReadonlyArray<NondeterministicCallIR>, procedureProtections?: ReadonlyArray<ProcedureMiddlewareIR>, argumentValidators?: ReadonlyArray<ArgumentValidatorIR>, secretLiterals?: ReadonlyArray<SecretLiteralIR>, sqlInterpolations?: ReadonlyArray<SqlInterpolationIR>, adminRoutes?: ReadonlyArray<AdminRouteIR>) => Finding[];
+declare const lintSchema: (schema: SchemaIR, queries?: ReadonlyArray<QueryReadIR>, inserts?: ReadonlyArray<InsertWriteIR>, authApiCalls?: ReadonlyArray<AuthApiCallIR>, rlsProcedures?: ReadonlyArray<RlsProcedureIR>, containers?: ReadonlyArray<ContainerIR>, workflows?: ReadonlyArray<WorkflowIR>, workflowCalls?: ReadonlyArray<WorkflowCallIR>, maskProcedures?: ReadonlyArray<MaskProcedureIR>, nondeterministicCalls?: ReadonlyArray<NondeterministicCallIR>, procedureProtections?: ReadonlyArray<ProcedureMiddlewareIR>, argumentValidators?: ReadonlyArray<ArgumentValidatorIR>, secretLiterals?: ReadonlyArray<SecretLiteralIR>, sqlInterpolations?: ReadonlyArray<SqlInterpolationIR>, adminRoutes?: ReadonlyArray<AdminRouteIR>, r2sqlCalls?: ReadonlyArray<R2sqlCallIR>) => Finding[];
 /**
 * Render advisor findings as a single multi-line string for console surfacing:
 * a one-line summary header followed by one `[LEVEL] name: detail` line per
@@ -711,8 +753,14 @@ declare class CodegenDiagnosticError extends Error {
 * ts-morph `Node`'s position in its source file.
 *
 * Message format: `@lunora/codegen: &lt;detail> (&lt;file>:&lt;line>:&lt;column>)`
+*
+* `meta` is merged onto the returned error for callers that also carry the
+* project-wide `LunoraError` envelope (`code`/`name`/`status`) — it never
+* touches `file`/`line`/`column`, and the error stays an instance of
+* {@link CodegenDiagnosticError} so the Vite overlay's `instanceof` location
+* lookup is unaffected.
 */
-declare const diagnosticAt: (node: Node, detail: string) => CodegenDiagnosticError;
+declare const diagnosticAt: (node: Node, detail: string, meta?: Record<string, unknown>) => CodegenDiagnosticError;
 /**
 * Discover `ctx.authApi.&lt;method>(...)` (and bare `authApi.&lt;method>(...)`) calls
 * under the lunora source directory and attribute each to the exported function
@@ -803,6 +851,19 @@ declare const discoverNondeterministicCalls: (project: Project, lunoraDirectory:
 * dropping the rest keeps the lint input small.
 */
 declare const discoverQueries: (project: Project, lunoraDirectory: string) => QueryReadIR[];
+/**
+* Discover `ctx.r2sql` accesses lexically inside the handler body of every
+* exported `query(...)` / `mutation(...)` registration under the lunora source
+* directory — the `r2sql_outside_action` lint input. `action(...)` (and
+* `stream(...)`) registrations are intentionally skipped: R2 SQL is the
+* external, non-reactive surface that belongs in actions.
+*
+* Traversal is scoped to the handler node (not the whole declaration), mirroring
+* `discoverNondeterministicCalls` — so a `ctx.r2sql` touch in a sibling helper
+* outside the handler is not attributed to the query/mutation. One
+* {@link R2sqlCallIR} is produced per access site.
+*/
+declare const discoverR2sqlCalls: (project: Project, lunoraDirectory: string) => R2sqlCallIR[];
 declare const discoverRlsProcedures: (project: Project, lunoraDirectory: string) => RlsProcedureIR[];
 /**
 * Aggregate the schema-wide RLS metadata the studio's read-only inspector reads:
@@ -822,7 +883,7 @@ declare const discoverRlsMetadata: (project: Project, lunoraDirectory: string) =
 * Load `&lt;projectRoot>/lunora/schema.ts`, find `defineSchema({...})`, and
 * return a structural IR. Throws if the file or call cannot be found.
 */
-declare const discoverSchema: (project: Project, schemaPath: string) => SchemaIR;
+declare const discoverSchema: (project: Project, schemaPath: string, projectRoot?: string) => SchemaIR;
 /**
 * Aggregate the schema-wide storage-rule metadata the studio's inspector reads:
 * every statically-discovered `(bucket, on, prefix, procedure)` entry across all
@@ -877,6 +938,8 @@ interface EmitServerOptions {
   hasPayments?: boolean;
   /** A `lunora/` source uses `@lunora/pipelines` / `ctx.pipelines` — wires `ctx.pipelines` onto ActionCtx only. */
   hasPipelines?: boolean;
+  /** A `lunora/` source uses `@lunora/r2sql` / `ctx.r2sql` — wires `ctx.r2sql` onto ActionCtx only. */
+  hasR2sql?: boolean;
   schema?: SchemaIR;
   storageRuleBuckets?: ReadonlyArray<string>;
   /** The project depends on the `lunora` umbrella — import base packages via its subpaths. */
@@ -893,12 +956,13 @@ declare const emitServer: ({
   hasKv,
   hasPayments,
   hasPipelines,
+  hasR2sql,
   schema,
   storageRuleBuckets,
   useUmbrella,
   workflows
 }?: EmitServerOptions) => string;
-declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>) => string;
+declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>, useUmbrella?: boolean) => string;
 /**
 * Storage-column map per table for the file browser: `{ table: [field, …] }` for
 * every field declared `v.storage(...)` (unwrapping `v.optional(...)`). The
@@ -916,7 +980,7 @@ declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?:
 * `containers[].class_name` to be exported by the deployed worker. Returns ""
 * when the project declares no containers (the file is not written then).
 */
-declare const emitContainers: (containers: ReadonlyArray<ContainerIR>) => string;
+declare const emitContainers: (containers: ReadonlyArray<ContainerIR>, jurisdiction?: JurisdictionIR) => string;
 /**
 * Emit `_generated/workflows.ts` — one `WorkflowEntrypoint` class per
 * `defineWorkflow` export, each a thin subclass of `LunoraWorkflow`
@@ -941,6 +1005,8 @@ interface EmitShardOptions {
   /** A `lunora/` source reads `ctx.kv` — wires `ctx.kv` onto every ctx. */
   hasKv?: boolean;
   hasPayments?: boolean;
+  /** A `lunora/` source reads `ctx.r2sql` (R2 SQL) — wires `ctx.r2sql` onto the ActionCtx only. */
+  hasR2sql?: boolean;
   maskMetadata?: MaskMetadataIR;
   rlsMetadata?: RlsMetadataIR;
   schema: SchemaIR;
@@ -960,6 +1026,7 @@ declare const emitShard: ({
   hasImages,
   hasKv,
   hasPayments,
+  hasR2sql,
   maskMetadata,
   rlsMetadata,
   schema,
@@ -1049,6 +1116,8 @@ interface EmitAppOptions {
   hasKv: boolean;
   /** App uses `@lunora/payment` / `ctx.payments` → emit `.payment()`. */
   hasPayments: boolean;
+  /** App uses `@lunora/r2sql` / `ctx.r2sql` → emit `.r2sql()`. */
+  hasR2sql: boolean;
   /** App imports `@lunora/scheduler` / declares crons → emit `.scheduler()`. */
   hasScheduler: boolean;
   /** App uses `@lunora/storage` → emit `.storage()` (DO `ctx.storage` + studio file browser). */
@@ -1057,6 +1126,8 @@ interface EmitAppOptions {
   hasVectors: boolean;
   /** App declares Cloudflare Workflows (`defineWorkflow`) → wire `options.workflowsClient` so the studio's workflow-instance proxy can reach the CF REST API. */
   hasWorkflow: boolean;
+  /** Schema declares `.jurisdiction("…")` → pin every DO the worker reaches (shards, fan-out, scheduler, containers) to the Cloudflare data-residency jurisdiction. */
+  jurisdiction?: JurisdictionIR;
   /** Project depends on the unscoped `lunorash` umbrella → import the runtime via `lunorash/runtime` instead of `@lunora/runtime`. */
   useUmbrella: boolean;
   /** An OpenAPI spec is emitted (`openapi.ts`) → wire `openApiSpec` into the worker. */
@@ -1201,6 +1272,19 @@ interface TableSnapshot {
 }
 /** The committed baseline — a deterministic structural view of the whole schema. */
 interface SchemaSnapshot {
+  /**
+  * Cloudflare DO data-residency jurisdiction declared via `.jurisdiction("…")`,
+  * or absent. Tracked because changing it strands all existing Durable Object
+  * data (a DO name maps to a different ID per jurisdiction). Optional, so old
+  * baselines written before this field parse cleanly (absent ⇒ undefined).
+  *
+  * Typed as a plain `string` (not the authoring union) on purpose: this is
+  * STORED data that a newer Lunora may have written with a jurisdiction this
+  * version doesn't yet know. Preserving the raw value keeps the breaking
+  * `changedJurisdiction` diff correct under a downgrade — coercing an unknown
+  * value to `undefined` would fail OPEN and hide the most destructive change.
+  */
+  jurisdiction?: string;
   /** Sorted list of every declared `defineMigration` id at capture time. */
   migrationIds: ReadonlyArray<string>;
   /** Table name → {@link TableSnapshot}, keys sorted for stable serialization. */
@@ -1214,7 +1298,7 @@ interface DriftChange {
   /** Human-readable, actionable description (used in the gate message). */
   summary: string;
   /** A machine-readable change discriminator. */
-  type: "addedIndex" | "addedOptionalField" | "addedRelation" | "addedRequiredField" | "addedTable" | "changedFieldKind" | "changedIndex" | "changedShardMode" | "fieldOptionalToRequired" | "fieldRequiredToOptional" | "removedField" | "removedIndex" | "removedRelation" | "removedTable";
+  type: "addedIndex" | "addedOptionalField" | "addedRelation" | "addedRequiredField" | "addedTable" | "changedJurisdiction" | "changedFieldKind" | "changedIndex" | "changedShardMode" | "fieldOptionalToRequired" | "fieldRequiredToOptional" | "removedField" | "removedIndex" | "removedRelation" | "removedTable";
 }
 /** The result of diffing two snapshots: every classified change. */
 interface SchemaDrift {
@@ -1316,6 +1400,11 @@ declare const refreshCodegenProject: (project: Project, lunoraDirectory: string)
 * Top-level codegen entry. Parses `&lt;projectRoot>/lunora/schema.ts` and every
 * function file under `&lt;projectRoot>/lunora/`, then writes
 * `_generated/{api,server,dataModel}.ts` next to them.
+*
+* When `LUNORA_CODEGEN_TIMING` is set (truthy), a single diagnostic summary
+* line is written to stderr with the total wall time and the discovery-vs-emit
+* split — opt-in instrumentation that is otherwise zero-cost and side-effect-free
+* on the returned {@link CodegenResult}.
 */
 declare const runCodegen: (options: CodegenOptions) => CodegenResult;
 interface CodegenOptions {
@@ -1470,4 +1559,4 @@ declare const validatorIrToJsonSchema: (validator: ValidatorIR) => JsonSchema;
 */
 declare const LUNORA_ERROR_CODES: ReadonlyArray<string>;
 declare const VERSION = "0.0.0";
-export { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, type FieldSnapshot, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type MaskProcedureIR, type MigrationIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, type QueryReadIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverNondeterministicCalls, discoverQueries, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, formatAdvisories, lintSchema, parseSchemaSnapshot, refreshCodegenProject, runCodegen, schemaFromIr, serializeSchemaSnapshot, validatorIrToJsonSchema };
+export { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, type FieldSnapshot, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type MaskProcedureIR, type MigrationIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, type QueryReadIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverNondeterministicCalls, discoverQueries, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, formatAdvisories, lintSchema, parseSchemaSnapshot, refreshCodegenProject, runCodegen, schemaFromIr, serializeSchemaSnapshot, validatorIrToJsonSchema };

package/dist/index.mjs

@@ -1,25 +1,26 @@
-export { formatAdvisories, lintSchema } from './packem_shared/lintSchema-DicbOHvH.mjs';
-export { CodegenDiagnosticError, diagnosticAt } from './packem_shared/CodegenDiagnosticError-54jWDxA9.mjs';
-export { default as discoverAuthApiCalls } from './packem_shared/discoverAuthApiCalls-C35R6z0T.mjs';
-export { CONTAINERS_FILENAME, discoverContainers } from './packem_shared/CONTAINERS_FILENAME-0K-pjNb8.mjs';
-export { default as discoverCrons } from './packem_shared/discoverCrons-BL6iGuJ3.mjs';
-export { discoverFunctions } from './packem_shared/discoverFunctions-DEgAcRuD.mjs';
-export { default as discoverHttpRoutes } from './packem_shared/discoverHttpRoutes-C978pBiG.mjs';
-export { default as discoverInserts } from './packem_shared/discoverInserts-CRQdXvHO.mjs';
-export { default as discoverMaskProcedures } from './packem_shared/discoverMaskProcedures-B64zA740.mjs';
-export { default as discoverMigrations } from './packem_shared/discoverMigrations-Doj_-BAA.mjs';
-export { default as discoverNondeterministicCalls } from './packem_shared/discoverNondeterministicCalls-4KiPQxQU.mjs';
-export { default as discoverQueries } from './packem_shared/discoverQueries-BkIi0dBD.mjs';
-export { discoverRlsMetadata, default as discoverRlsProcedures } from './packem_shared/discoverRlsMetadata-DpRB1HMe.mjs';
-export { default as discoverSchema } from './packem_shared/discoverSchema-BBulgGbH.mjs';
-export { default as discoverStorageRulesMetadata } from './packem_shared/discoverStorageRulesMetadata-DAqJUxUv.mjs';
-export { WORKFLOWS_FILENAME, discoverWorkflows } from './packem_shared/discoverWorkflows-DRDQdhfq.mjs';
-export { GENERATED_HEADER, emitApi, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers } from './packem_shared/emitApi-hRVC-kE7.mjs';
-export { emitApp } from './packem_shared/emitApp-CzZ6GbrD.mjs';
-export { buildOpenApiDocument, emitOpenApi, emitOpenApiModule } from './packem_shared/buildOpenApiDocument-yHVN66Xd.mjs';
-export { OPENRPC_VERSION, buildOpenRpcDocument, emitOpenRpc, emitOpenRpcModule } from './packem_shared/buildOpenRpcDocument-BZGY1-jT.mjs';
-export { SCHEMA_SNAPSHOT_FILENAME, createCodegenProject, refreshCodegenProject, runCodegen } from './packem_shared/createCodegenProject-DGJm0_Pk.mjs';
-export { SCHEMA_SNAPSHOT_VERSION, SchemaSnapshotParseError, buildSchemaSnapshot, diffSchemaSnapshots, evaluateSchemaDrift, parseSchemaSnapshot, serializeSchemaSnapshot } from './packem_shared/buildSchemaSnapshot-DzLDbWk3.mjs';
+export { formatAdvisories, lintSchema } from './packem_shared/formatAdvisories-8NIv1k0I.mjs';
+export { CodegenDiagnosticError, diagnosticAt } from './packem_shared/CodegenDiagnosticError-DeblMkzO.mjs';
+export { default as discoverAuthApiCalls } from './packem_shared/discoverAuthApiCalls-CoirYbg6.mjs';
+export { CONTAINERS_FILENAME, discoverContainers } from './packem_shared/CONTAINERS_FILENAME-DlP6YM_Q.mjs';
+export { default as discoverCrons } from './packem_shared/discoverCrons-Cev7RRAf.mjs';
+export { discoverFunctions } from './packem_shared/discoverFunctions-BWMczzBx.mjs';
+export { default as discoverHttpRoutes } from './packem_shared/discoverHttpRoutes-CfP6cMzt.mjs';
+export { default as discoverInserts } from './packem_shared/discoverInserts-C7zxXkUf.mjs';
+export { default as discoverMaskProcedures } from './packem_shared/discoverMaskProcedures-Cm81kwrb.mjs';
+export { default as discoverMigrations } from './packem_shared/discoverMigrations-Bi5nJ0mJ.mjs';
+export { default as discoverNondeterministicCalls } from './packem_shared/discoverNondeterministicCalls-C4M8AXmQ.mjs';
+export { default as discoverQueries } from './packem_shared/discoverQueries-B0wGT-xe.mjs';
+export { default as discoverR2sqlCalls } from './packem_shared/discoverR2sqlCalls-BVNMd428.mjs';
+export { discoverRlsMetadata, default as discoverRlsProcedures } from './packem_shared/discoverRlsMetadata-BS9GOGC5.mjs';
+export { default as discoverSchema } from './packem_shared/discoverSchema-BnWHHJ4T.mjs';
+export { default as discoverStorageRulesMetadata } from './packem_shared/discoverStorageRulesMetadata-Da8BKXcI.mjs';
+export { WORKFLOWS_FILENAME, discoverWorkflows } from './packem_shared/WORKFLOWS_FILENAME-D62dcBGg.mjs';
+export { GENERATED_HEADER, emitApi, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers } from './packem_shared/GENERATED_HEADER-BiFXNUvo.mjs';
+export { emitApp } from './packem_shared/emitApp-KfMaKXWe.mjs';
+export { buildOpenApiDocument, emitOpenApi, emitOpenApiModule } from './packem_shared/buildOpenApiDocument-Cu3mZl-8.mjs';
+export { OPENRPC_VERSION, buildOpenRpcDocument, emitOpenRpc, emitOpenRpcModule } from './packem_shared/OPENRPC_VERSION-B4i9Qp3v.mjs';
+export { SCHEMA_SNAPSHOT_FILENAME, createCodegenProject, refreshCodegenProject, runCodegen } from './packem_shared/SCHEMA_SNAPSHOT_FILENAME-Bvv7qa_u.mjs';
+export { SCHEMA_SNAPSHOT_VERSION, SchemaSnapshotParseError, buildSchemaSnapshot, diffSchemaSnapshots, evaluateSchemaDrift, parseSchemaSnapshot, serializeSchemaSnapshot } from './packem_shared/SCHEMA_SNAPSHOT_VERSION-wWGP2_5E.mjs';
 export { schemaFromIr } from './packem_shared/schemaFromIr-DTYsLBaA.mjs';
 export { LUNORA_ERROR_CODES, validatorIrToJsonSchema } from './packem_shared/LUNORA_ERROR_CODES-CySpQPD3.mjs';
 

package/dist/packem_shared/{CONTAINERS_FILENAME-0K-pjNb8.mjs → CONTAINERS_FILENAME-DlP6YM_Q.mjs}

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { containerClassName, containerBindingName, normalizeContainerImage } from '@lunora/container';
 import { SyntaxKind, Node } from 'ts-morph';
-import { diagnosticAt } from './CodegenDiagnosticError-54jWDxA9.mjs';
+import { diagnosticAt } from './CodegenDiagnosticError-DeblMkzO.mjs';
 
 const CONTAINERS_FILENAME = "containers.ts";
 const isDefineContainer = (identifier) => {

package/dist/packem_shared/{CodegenDiagnosticError-54jWDxA9.mjs → CodegenDiagnosticError-DeblMkzO.mjs}

@@ -10,13 +10,14 @@ class CodegenDiagnosticError extends Error {
     this.column = column;
   }
 }
-const diagnosticAt = (node, detail) => {
+const diagnosticAt = (node, detail, meta) => {
   const sourceFile = node.getSourceFile();
   const file = sourceFile.getFilePath();
   const line = node.getStartLineNumber();
   const { column } = sourceFile.getLineAndColumnAtPos(node.getStart());
   const message = `@lunora/codegen: ${detail} (${file}:${line.toString()}:${column.toString()})`;
-  return new CodegenDiagnosticError(message, file, line, column);
+  const error = new CodegenDiagnosticError(message, file, line, column);
+  return meta ? Object.assign(error, meta) : error;
 };
 
 export { CodegenDiagnosticError, diagnosticAt };