@lunora/codegen 0.0.0 → 1.0.0-alpha.2

package/dist/packem_shared/emitApi-hRVC-kE7.mjs

@@ -0,0 +1,2426 @@
+import { s as sanitizeNamespace } from './paths-BRd6JHuF.mjs';
+
+const GENERATED_HEADER = "// GENERATED by @lunora/codegen — do not edit.\n// Run `lunora codegen` to regenerate.\n\n";
+const baseSpecifiers = (useUmbrella = false) => useUmbrella ? {
+  client: "lunorash/client",
+  do: "lunorash/do",
+  server: "lunorash/server",
+  serverDataModel: "lunorash/server/data-model",
+  serverDrizzle: "lunorash/server/drizzle",
+  serverTypes: "lunorash/server/types"
+} : {
+  client: "@lunora/client",
+  do: "@lunora/do",
+  server: "@lunora/server",
+  serverDataModel: "@lunora/server/data-model",
+  serverDrizzle: "@lunora/server/drizzle",
+  serverTypes: "@lunora/server/types"
+};
+const IDENTIFIER_RE = /^[A-Za-z_$][\w$]*$/u;
+const LITERAL_VALUE_RE = /^(?:"[^"\\]*"|'[^'\\]*'|-?\d+(?:\.\d+)?|true|false|null)$/u;
+const IMPORT_PATH_RE = /^[\w./-]+$/u;
+const assertIdentifier = (value, context) => {
+  if (!IDENTIFIER_RE.test(value)) {
+    throw new Error(`@lunora/codegen: ${context} is not a valid JS identifier: ${JSON.stringify(value)}`);
+  }
+};
+const renderPropertyKey = (fieldName) => IDENTIFIER_RE.test(fieldName) ? fieldName : JSON.stringify(fieldName);
+const SCALAR_TYPE_BY_KIND = {
+  any: "unknown",
+  bigint: "bigint",
+  boolean: "boolean",
+  bytes: "ArrayBuffer",
+  // Epoch-millisecond numbers; the distinction is semantic only.
+  date: "number",
+  // v.from() wraps an external Standard Schema validator whose output type is
+  // not statically recoverable at codegen time — emit `unknown` so the
+  // generated api types still compile without depending on the library.
+  from: "unknown",
+  null: "null",
+  number: "number",
+  // The key of a stored R2 object — a string; the distinction is semantic only.
+  storage: "string",
+  string: "string",
+  timestamp: "number"
+};
+const literalToType = (value) => {
+  if (value === void 0) {
+    return "unknown";
+  }
+  if (!LITERAL_VALUE_RE.test(value)) {
+    throw new Error(`@lunora/codegen: v.literal() argument is not a parseable string/number/boolean/null literal: ${JSON.stringify(value)}`);
+  }
+  return value;
+};
+const validatorToType = (validator) => {
+  const scalar = SCALAR_TYPE_BY_KIND[validator.kind];
+  if (scalar !== void 0) {
+    return scalar;
+  }
+  switch (validator.kind) {
+    case "array": {
+      return `Array<${validator.inner ? validatorToType(validator.inner) : "unknown"}>`;
+    }
+    case "id": {
+      const tableName = validator.tableName ?? "_unknown_";
+      assertIdentifier(tableName, "v.id() table name");
+      return `Id<"${tableName}">`;
+    }
+    case "literal": {
+      return literalToType(validator.literalValue);
+    }
+    case "object": {
+      if (!validator.shape) {
+        return "Record<string, unknown>";
+      }
+      const fields = Object.entries(validator.shape).map(([key, child]) => `${renderPropertyKey(key)}: ${validatorToType(child)}`).join("; ");
+      return `{ ${fields} }`;
+    }
+    case "optional": {
+      return `${validator.inner ? validatorToType(validator.inner) : "unknown"} | undefined`;
+    }
+    case "record": {
+      const key = validator.keyType ? validatorToType(validator.keyType) : "string";
+      const value = validator.valueType ? validatorToType(validator.valueType) : "unknown";
+      return `Record<${key}, ${value}>`;
+    }
+    case "union": {
+      return validator.members && validator.members.length > 0 ? validator.members.map((member) => validatorToType(member)).join(" | ") : "never";
+    }
+    default: {
+      return "unknown";
+    }
+  }
+};
+const renderArgsType = (args) => {
+  const entries = Object.entries(args);
+  if (entries.length === 0) {
+    return "{}";
+  }
+  return `{ ${entries.map(([key, validator]) => {
+    const propertyKey = renderPropertyKey(key);
+    if (validator.kind === "optional") {
+      const inner = validator.inner ? validatorToType(validator.inner) : "unknown";
+      return `${propertyKey}?: ${inner}`;
+    }
+    return `${propertyKey}: ${validatorToType(validator)}`;
+  }).join("; ")} }`;
+};
+const isOptionalOnInsert = (validator) => validator.kind === "optional" || Boolean(validator.column?.hasDefault);
+const renderInsertInterface = (table) => {
+  assertIdentifier(table.name, "table name");
+  const fields = Object.entries(table.shape).map(([fieldName, validator]) => {
+    const inner = validator.kind === "optional" && validator.inner ? validator.inner : validator;
+    const type = validatorToType(inner);
+    const propertyKey = renderPropertyKey(fieldName);
+    return isOptionalOnInsert(validator) ? `    ${propertyKey}?: ${type};` : `    ${propertyKey}: ${type};`;
+  }).join("\n");
+  const body = fields ? `
+${fields}
+` : "";
+  return `export interface Insert_${table.name} {
+    _id?: Id<"${table.name}">;
+    _creationTime?: number;${body}}`;
+};
+const emitDataModel = (schema, useUmbrella = false) => {
+  const base = baseSpecifiers(useUmbrella);
+  for (const table of schema.tables) {
+    assertIdentifier(table.name, "table name");
+  }
+  const tableNames = schema.tables.map((table) => `"${table.name}"`).join(" | ") || "never";
+  const documents = schema.tables.map((table) => {
+    const fields = Object.entries(table.shape).map(([fieldName, validator]) => {
+      const propertyKey = renderPropertyKey(fieldName);
+      if (validator.kind === "optional") {
+        const inner = validator.inner ? validatorToType(validator.inner) : "unknown";
+        return `    ${propertyKey}?: ${inner};`;
+      }
+      return `    ${propertyKey}: ${validatorToType(validator)};`;
+    }).join("\n");
+    const body = fields ? `
+${fields}
+` : "";
+    return `export interface Doc_${table.name} {
+    _id: Id<"${table.name}">;
+    _creationTime: number;${body}}`;
+  }).join("\n\n");
+  const documentMap = schema.tables.map((table) => `    ${table.name}: Doc_${table.name};`).join("\n");
+  const indexNamesByTable = schema.tables.map((table) => {
+    const names = table.indexes.map((index) => JSON.stringify(index.name)).join(" | ");
+    return `    ${table.name}: ${names || "never"};`;
+  }).join("\n");
+  const searchIndexNamesByTable = schema.tables.map((table) => {
+    const names = table.shardMode === "global" ? "" : table.searchIndexes.map((index) => JSON.stringify(index.name)).join(" | ");
+    return `    ${table.name}: ${names || "never"};`;
+  }).join("\n");
+  const rankIndexNamesByTable = schema.tables.map((table) => {
+    const names = table.rankIndexes.map((index) => JSON.stringify(index.name)).join(" | ");
+    return `    ${table.name}: ${names || "never"};`;
+  }).join("\n");
+  const vectorIndexNames = schema.vectorIndexes.map((index) => JSON.stringify(index.name)).join(" | ") || "never";
+  const insertInterfaces = schema.tables.map((table) => renderInsertInterface(table)).join("\n\n");
+  const insertMap = schema.tables.map((table) => `    ${table.name}: Insert_${table.name};`).join("\n");
+  const relationsMap = schema.tables.map((table) => {
+    const entries = table.relations.map((relation) => {
+      assertIdentifier(relation.table, "relation target table");
+      return `        ${renderPropertyKey(relation.name)}: ${relation.kind === "one" ? "OneRelation" : "ManyRelation"}<"${relation.table}">;`;
+    }).join("\n");
+    return entries ? `    ${table.name}: {
+${entries}
+    };` : `    ${table.name}: {};`;
+  }).join("\n");
+  return `${GENERATED_HEADER}import type {
+    DatabaseReaderFacade as DatabaseReaderFacadeOf,
+    DatabaseWriterFacade as DatabaseWriterFacadeOf,
+    LoadWith as LoadWithOf,
+    TableReaderFacade as TableReaderFacadeOf,
+    TableWriterFacade as TableWriterFacadeOf,
+    WithArg as WithArgOf,
+} from "${base.serverDataModel}";
+
+export type {
+    AggregateOp,
+    GroupByEntry,
+    OrderBy,
+    QueryArgs,
+    QueryPage,
+    RankPage,
+    RankResult,
+    RestrictableQueryOptions,
+    RestrictableQueryOptionsOf,
+    SearchFilterBuilder,
+    SearchReader,
+    TableAggregateOptions,
+    TableAggregateOptionsOf,
+    TableGroupByOptions,
+    TableGroupByOptionsOf,
+    TableRankOptions,
+    TableRankPageOptions,
+    Where,
+    WhereOf,
+    WhereOperators,
+} from "${base.serverDataModel}";
+
+export type TableName = ${tableNames};
+
+export type Id<TName extends string> = string & { readonly __table: TName };
+
+${documents}
+
+export interface DataModel {
+${documentMap}
+}
+
+export type Doc<T extends keyof DataModel> = DataModel[T];
+
+/**
+ * Per-table index name union. \`never\` for tables without secondary indexes.
+ * Used by \`TableReader.withIndex()\` to constrain callers to declared names.
+ */
+export interface IndexNamesByTable {
+${indexNamesByTable}
+}
+
+export type IndexName<T extends keyof DataModel> = IndexNamesByTable[T];
+
+/** Per-table search-index name union. \`never\` for tables without searchIndex. */
+export interface SearchIndexNamesByTable {
+${searchIndexNamesByTable}
+}
+
+export type SearchIndexName<T extends keyof DataModel> = SearchIndexNamesByTable[T];
+
+/** Per-table rank-index name union. \`never\` for tables without a rankIndex. */
+export interface RankIndexNamesByTable {
+${rankIndexNamesByTable}
+}
+
+export type RankIndexName<T extends keyof DataModel> = RankIndexNamesByTable[T];
+
+/** Union of declared vector index names. \`never\` when none are declared. */
+export type VectorIndexName = ${vectorIndexNames};
+
+${insertInterfaces}
+
+/** Per-table insert shape, accepted by \`ctx.db.<table>.insert(...)\`. */
+export interface InsertModel {
+${insertMap}
+}
+
+export type Insert<T extends keyof DataModel> = InsertModel[T];
+
+/**
+ * Phantom relation descriptors. They carry the relation kind and target table
+ * as type parameters only — there is no runtime value — so the \`with\` argument
+ * and its return type can be inferred from {@link Relations}.
+ */
+export interface OneRelation<Target extends keyof DataModel> {
+    readonly __relationKind: "one";
+    readonly __target: Target;
+}
+
+export interface ManyRelation<Target extends keyof DataModel> {
+    readonly __relationKind: "many";
+    readonly __target: Target;
+}
+
+/** Per-table relation map keyed by accessor name. \`{}\` for tables with none. */
+export interface Relations {
+${relationsMap}
+}
+
+/** The \`with\` argument for table \`T\` — see \`@lunora/server/data-model\`. */
+export type WithArg<T extends keyof DataModel> = WithArgOf<DataModel, Relations, T>;
+
+/** \`Doc<T>\` narrowed to exactly the relations requested in the with-arg \`W\`. */
+export type LoadWith<T extends keyof DataModel, W> = LoadWithOf<DataModel, Relations, T, W>;
+
+/** Read-only typed table accessor exposed on \`QueryCtx.db.<table>\`. */
+export type TableReaderFacade<T extends keyof DataModel> = TableReaderFacadeOf<DataModel, Relations, RankIndexNamesByTable, SearchIndexNamesByTable, T>;
+
+/** Read-write typed table accessor exposed on \`MutationCtx.db.<table>\` / \`ActionCtx.db.<table>\`. */
+export type TableWriterFacade<T extends keyof DataModel> = TableWriterFacadeOf<DataModel, InsertModel, Relations, RankIndexNamesByTable, SearchIndexNamesByTable, T>;
+
+/** Per-table read facade — \`ctx.db.<table>\` on a \`QueryCtx\`. */
+export type DatabaseReaderFacade = DatabaseReaderFacadeOf<DataModel, Relations, RankIndexNamesByTable, SearchIndexNamesByTable>;
+
+/** Per-table read-write facade — \`ctx.db.<table>\` on a \`MutationCtx\` / \`ActionCtx\`. */
+export type DatabaseWriterFacade = DatabaseWriterFacadeOf<DataModel, InsertModel, Relations, RankIndexNamesByTable, SearchIndexNamesByTable>;
+
+/** Insert builder returned by \`ctx.orm.insert(table)\`. */
+export interface OrmInsertBuilder<T extends keyof DataModel> {
+    values: (values: Insert<T>) => Promise<Id<T>>;
+}
+
+/** Replace builder returned by \`ctx.orm.replace(table, id)\` — swaps the whole document. */
+export interface OrmReplaceBuilder<T extends keyof DataModel> {
+    with: (values: Insert<T>) => Promise<void>;
+}
+
+/** Update builder returned by \`ctx.orm.update(table, id)\` — patches the named fields. */
+export interface OrmUpdateBuilder<T extends keyof DataModel> {
+    set: (values: Partial<Insert<T>>) => Promise<void>;
+}
+
+/** Read-only ORM surface — \`ctx.orm\` on a \`QueryCtx\`. Mirrors \`ctx.db\` reads under a kitcn-style \`query\` namespace. */
+export interface OrmReader {
+    query: DatabaseReaderFacade;
+}
+
+/** Read-write ORM surface — \`ctx.orm\` on a \`MutationCtx\` / \`ActionCtx\`. Writes are addressed by id, like \`ctx.db\`. */
+export interface OrmWriter extends OrmReader {
+    delete: <T extends keyof DataModel>(table: T, id: Id<T>) => Promise<void>;
+    insert: <T extends keyof DataModel>(table: T) => OrmInsertBuilder<T>;
+    replace: <T extends keyof DataModel>(table: T, id: Id<T>) => OrmReplaceBuilder<T>;
+    update: <T extends keyof DataModel>(table: T, id: Id<T>) => OrmUpdateBuilder<T>;
+}
+`;
+};
+const GENERATED_IMPORT_RE = /import\("(?<spec>(?:\.\.?\/)*_generated\/[^"]+)"\)/gu;
+const GENERATED_PREFIX_RE = /^(?:\.\.?\/)*_generated\//u;
+const relocateGeneratedImports = (returnType) => returnType.replaceAll(GENERATED_IMPORT_RE, (_match, spec) => {
+  const stripped = spec.replace(GENERATED_PREFIX_RE, "./");
+  return `import("${stripped}")`;
+});
+const referencedDataModelImports = (body) => ["Doc", "Id"].filter((name) => new RegExp(String.raw`\b${name}<`, "u").test(body));
+const renderApiBody = (functions) => {
+  const namespaces = /* @__PURE__ */ new Map();
+  for (const definition of functions) {
+    const list = namespaces.get(definition.filePath) ?? [];
+    list.push(definition);
+    namespaces.set(definition.filePath, list);
+  }
+  const renderNamespace = ([file, list]) => {
+    const members = list.map((definition) => {
+      const argsType = renderArgsType(definition.args);
+      const returnType = relocateGeneratedImports(definition.returnType);
+      return `        ${definition.exportName}: FunctionReference<"${definition.kind}", ${argsType}, ${returnType}>;`;
+    }).join("\n");
+    return `    ${renderPropertyKey(sanitizeNamespace(file))}: {
+${members}
+    };`;
+  };
+  return [...namespaces.entries()].toSorted(([a], [b]) => a.localeCompare(b)).map((entry) => renderNamespace(entry)).join("\n");
+};
+const renderWorkflowsRef = (workflows) => {
+  if (workflows.length === 0) {
+    return { block: "", importLine: "" };
+  }
+  const sorted = [...workflows].toSorted((a, b) => a.exportName.localeCompare(b.exportName));
+  const refMembers = sorted.map((workflow) => `    ${workflow.exportName}: WorkflowReference<WorkflowParamsOf<typeof lunoraWorkflowDefinitions.${workflow.exportName}>>;`).join("\n");
+  const objectMembers = sorted.map(
+    (workflow) => `    ${workflow.exportName}: { isLunoraWorkflow: true, binding: ${JSON.stringify(workflow.bindingName)}, name: ${JSON.stringify(workflow.exportName)} },`
+  ).join("\n");
+  const block = `
+/** Params type carried by a \`defineWorkflow\` definition (its phantom \`__params\`). */
+type WorkflowParamsOf<Definition> = Definition extends { __params?: infer Params } ? (unknown extends Params ? Record<string, unknown> : Params) : Record<string, unknown>;
+
+/** A typed reference to a durable workflow, addressable for \`cronJobs()\` targets. Mirrors \`@lunora/scheduler\`'s \`WorkflowReference\` structurally. */
+export interface WorkflowReference<Params = Record<string, unknown>> {
+    readonly isLunoraWorkflow: true;
+    readonly __params?: Params;
+    readonly binding: string;
+    readonly name: string;
+}
+
+/** This project's durable workflows, addressable as typed references (e.g. \`crons.daily("digest", …, workflows.digestPipeline, params)\`). */
+export interface WorkflowsRef {
+${refMembers}
+}
+
+export const workflows: WorkflowsRef = {
+${objectMembers}
+};
+`;
+  return { block, importLine: `import type * as lunoraWorkflowDefinitions from "../workflows.js";
+` };
+};
+const emitApi = (functions, workflows = [], useUmbrella = false) => {
+  const base = baseSpecifiers(useUmbrella);
+  const publicFunctions = functions.filter((definition) => definition.visibility !== "internal");
+  const internalFunctions = functions.filter((definition) => definition.visibility === "internal");
+  const publicBody = renderApiBody(publicFunctions);
+  const internalBody = renderApiBody(internalFunctions);
+  const combinedBody = `${publicBody}
+${internalBody}`;
+  const dataModelImports = referencedDataModelImports(combinedBody);
+  const dataModelImportLine = dataModelImports.length > 0 ? `
+import type { ${dataModelImports.join(", ")} } from "./dataModel.js";
+` : "";
+  const apiBlock = publicBody ? `
+${publicBody}
+` : "";
+  const internalBlock = internalBody ? `
+${internalBody}
+` : "";
+  const workflowsRef = renderWorkflowsRef(workflows);
+  return `${GENERATED_HEADER}import { anyApi } from "${base.serverTypes}";
+import type { FunctionReference } from "${base.client}";
+${workflowsRef.importLine}${dataModelImportLine}
+export interface ApiTypes {${apiBlock}}
+
+export const api = anyApi as unknown as ApiTypes;
+
+/** Internal functions — callable only server-side via \`ctx.run*\`, never from a client. */
+export interface InternalApiTypes {${internalBlock}}
+
+export const internal = anyApi as unknown as InternalApiTypes;
+${workflowsRef.block}`;
+};
+const emitSeed = (enabled) => {
+  if (!enabled) {
+    return "";
+  }
+  return `${GENERATED_HEADER}import { createSeedClient as createSeedClientBase } from "@lunora/seed";
+import type { SeedClient, SeedClientOptions } from "@lunora/seed";
+
+import schema from "../schema.js";
+import type { InsertModel } from "./dataModel.js";
+
+/**
+ * Schema-aware seed client with this project's \`InsertModel\` and runtime schema
+ * pre-bound. Each table is a method; call it with a count, a range, explicit
+ * partial rows, or per-field overrides. Foreign keys connect to rows seeded
+ * earlier in the run, and FK-parent tables are seeded automatically.
+ * @example
+ * const seed = createSeedClient({ seed: 1 });
+ * const { users } = await seed.users(5);
+ * const { posts } = await seed.posts((x) => x([10, 20]));
+ */
+export const createSeedClient = (options?: SeedClientOptions): SeedClient<InsertModel> => createSeedClientBase<InsertModel>(schema, options);
+`;
+};
+const moduleAlias = (filePath, index) => `lunora_${sanitizeNamespace(filePath)}_${String(index)}`;
+const CALL_REGISTERED_HELPER = `const callRegistered = async <R>(context: CallerCtx, functionPath: string, args: Record<string, unknown> | undefined): Promise<R> => {
+    const registered = LUNORA_FUNCTIONS[functionPath];
+
+    if (!registered) {
+        throw Object.assign(new Error(\`function not registered: \${functionPath}\`), {
+            name: "LunoraError",
+            code: "FUNCTION_NOT_FOUND",
+            status: 404,
+        });
+    }
+
+    return (await registered.handler(context, args ?? {})) as R;
+};`;
+const renderFunctionRegistry = (functions, migrations) => {
+  const aliasByPath = /* @__PURE__ */ new Map();
+  const registerPath = (filePath) => {
+    if (!aliasByPath.has(filePath)) {
+      aliasByPath.set(filePath, moduleAlias(filePath, aliasByPath.size));
+    }
+  };
+  for (const definition of functions) {
+    registerPath(definition.filePath);
+  }
+  for (const migration of migrations) {
+    registerPath(migration.filePath);
+  }
+  const importLines = [...aliasByPath.entries()].map(([filePath, alias]) => {
+    if (!IMPORT_PATH_RE.test(filePath)) {
+      throw new Error(`@lunora/codegen: refusing to emit import for unsafe file path: ${JSON.stringify(filePath)}`);
+    }
+    return `import * as ${alias} from "../${filePath}.js";`;
+  }).join("\n");
+  const dispatchEntries = functions.map(
+    (definition) => `    "${sanitizeNamespace(definition.filePath)}:${definition.exportName}": ${aliasByPath.get(definition.filePath) ?? ""}.${definition.exportName} as unknown as RegisteredLunoraFunction,`
+  ).join("\n");
+  const migrationEntries = migrations.map(
+    (migration) => `    ${JSON.stringify(migration.id)}: ${aliasByPath.get(migration.filePath) ?? ""}.${migration.exportName} as unknown as RegisteredDataMigration,`
+  ).join("\n");
+  return {
+    dispatchBody: dispatchEntries.length > 0 ? `
+${dispatchEntries}
+` : "",
+    importBlock: importLines.length > 0 ? `${importLines}
+
+` : "",
+    migrationBody: migrationEntries.length > 0 ? `
+${migrationEntries}
+` : ""
+  };
+};
+const renderCaller = (functions) => {
+  const namespaces = /* @__PURE__ */ new Map();
+  for (const definition of functions) {
+    const list = namespaces.get(definition.filePath) ?? [];
+    list.push(definition);
+    namespaces.set(definition.filePath, list);
+  }
+  const ordered = [...namespaces.entries()].toSorted(([a], [b]) => a.localeCompare(b));
+  const types = ordered.map(([file, list]) => {
+    const members = list.map((definition) => {
+      const argsType = renderArgsType(definition.args);
+      const optional = argsType === "{}" ? "?" : "";
+      const returnType = relocateGeneratedImports(definition.returnType);
+      if (definition.kind === "stream") {
+        return `        ${definition.exportName}: (args${optional}: ${argsType}) => Promise<AsyncIterable<${returnType}>>;`;
+      }
+      return `        ${definition.exportName}: (args${optional}: ${argsType}) => Promise<${returnType}>;`;
+    }).join("\n");
+    return `    ${renderPropertyKey(sanitizeNamespace(file))}: {
+${members}
+    };`;
+  }).join("\n");
+  const implementation = ordered.map(([file, list]) => {
+    const namespace = sanitizeNamespace(file);
+    const leaves = list.map((definition) => `        ${definition.exportName}: (args) => callRegistered(context, "${namespace}:${definition.exportName}", args),`).join("\n");
+    return `    ${renderPropertyKey(namespace)}: {
+${leaves}
+    },`;
+  }).join("\n");
+  return { implementation, types };
+};
+const buildStorageBucketNames = (schema, ruleBuckets = []) => {
+  const named = /* @__PURE__ */ new Set();
+  for (const table of schema.tables) {
+    for (const validator of Object.values(table.shape)) {
+      const resolved = validator.kind === "optional" && validator.inner ? validator.inner : validator;
+      if (resolved.kind === "storage" && typeof resolved.bucket === "string" && resolved.bucket !== "") {
+        named.add(resolved.bucket);
+      }
+    }
+  }
+  for (const bucket of ruleBuckets) {
+    if (bucket !== "" && bucket !== "default") {
+      named.add(bucket);
+    }
+  }
+  return ["default", ...[...named].toSorted((a, b) => a.localeCompare(b))];
+};
+const emitServer = ({
+  containers = [],
+  hasAi = false,
+  hasAnalytics = false,
+  hasBrowser = false,
+  hasHyperdrive = false,
+  hasImages = false,
+  hasKv = false,
+  hasPayments = false,
+  hasPipelines = false,
+  schema,
+  storageRuleBuckets = [],
+  useUmbrella = false,
+  workflows = []
+} = {}) => {
+  const base = baseSpecifiers(useUmbrella);
+  const storageBucketUnion = buildStorageBucketNames(schema ?? { tables: []}, storageRuleBuckets).map((name) => JSON.stringify(name)).join(" | ");
+  const aiTypeImport = hasAi ? `import type { LunoraAi } from "@lunora/ai";
+` : "";
+  const aiActionField = hasAi ? `
+    readonly ai: LunoraAi;` : "";
+  const paymentsTypeImport = hasPayments ? `import type { LunoraPayment } from "@lunora/payment";
+` : "";
+  const paymentsActionField = hasPayments ? `
+    readonly payments: LunoraPayment;` : "";
+  const containersTypeImport = containers.length > 0 ? `import type { ContainerAccessor } from "@lunora/container";
+` : "";
+  const containersActionField = containers.length > 0 ? `
+    readonly containers: {${containers.map((container) => `
+        readonly ${container.exportName}: ContainerAccessor;`).join("")}
+    };` : "";
+  const envBindingFields = [
+    ...hasAi ? [`    /** Workers AI binding (the conventional \`env.AI\`), narrowing \`ctx.ai\`. */
+    readonly AI?: unknown;`] : [],
+    ...containers.map((container) => {
+      assertIdentifier(container.bindingName, `container binding "${container.bindingName}"`);
+      return `    /** Durable Object namespace for the \`${container.exportName}\` container. */
+    readonly ${container.bindingName}?: unknown;`;
+    }),
+    ...workflows.map((workflow) => {
+      assertIdentifier(workflow.bindingName, `workflow binding "${workflow.bindingName}"`);
+      return `    /** Workflow binding for the \`${workflow.exportName}\` workflow. */
+    readonly ${workflow.bindingName}?: unknown;`;
+    })
+  ].join("\n");
+  const envBlock = `
+
+/**
+ * This project's Cloudflare bindings, as far as codegen can discover them from
+ * \`lunora/\` source — the container/workflow Durable Object namespaces and the
+ * conventional Workers AI binding. Bindings the config layer reconciles from
+ * user-named wrangler config (R2/KV/D1/\`services\`/queues/…) aren't statically
+ * visible here, so the open index signature keeps them reachable (cast at the
+ * use site). Service bindings (\`env.<SERVICE>.fetch(...)\` / RPC stubs) live
+ * under this signature too — Lunora can't type a third-party worker's RPC
+ * surface, so treat them as \`Fetcher\`/\`Service<unknown>\` and cast.
+ */
+export interface CloudflareBindings {
+    readonly [binding: string]: unknown;${envBindingFields ? `
+${envBindingFields}` : ""}
+}
+
+/** Alias for {@link CloudflareBindings} — the typed shape of \`env\`. */
+export type Env = CloudflareBindings;`;
+  const kvContextField = hasKv ? `
+    readonly kv: import("@lunora/kv").Kv;` : "";
+  const hyperdriveActionField = hasHyperdrive ? `
+    /**
+     * 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.
+     */
+    readonly sql: import("@lunora/hyperdrive").SqlClient;` : "";
+  const browserActionField = hasBrowser ? `
+    /** Browser Rendering (screenshots/PDF/scrape). Non-deterministic — available only in actions. */
+    readonly browser: import("@lunora/browser").Browser;` : "";
+  const imagesActionField = hasImages ? `
+    /** Cloudflare Images transforms (resize/format/optimize). Non-deterministic — available only in actions. */
+    readonly images: import("@lunora/images").Images;` : "";
+  const analyticsContextField = hasAnalytics ? `
+    /** Analytics Engine telemetry sink. Fire-and-forget and sampled; do not read it back in-handler. */
+    readonly analytics: import("@lunora/analytics").AnalyticsClient;` : "";
+  const pipelinesActionField = hasPipelines ? `
+    /** Pipelines ingestion sink (durable, R2-backed). Fire-and-forget and batched; do not read it back in-handler. */
+    readonly pipelines: import("@lunora/pipelines").PipelineClient;` : "";
+  const hasWorkflows = workflows.length > 0;
+  const workflowsTypeImport = hasWorkflows ? `import type { WorkflowHandle } from "@lunora/workflow";
+import type * as lunoraWorkflowDefinitions from "../workflows.js";
+` : "";
+  const workflowsTypeBlock = hasWorkflows ? `
+
+/** Params type carried by a \`defineWorkflow\` definition (its phantom \`__params\`). */
+type WorkflowParamsOf<Definition> = Definition extends { __params?: infer Params }
+    ? unknown extends Params
+        ? Record<string, unknown>
+        : NonNullable<Params>
+    : Record<string, unknown>;
+
+/** This project's declared workflows, addressable from \`ctx.workflows\` by their \`lunora/workflows.ts\` export name. */
+export interface LunoraWorkflows {
+${workflows.map((workflow) => `    get(name: ${JSON.stringify(workflow.exportName)}): WorkflowHandle<WorkflowParamsOf<typeof lunoraWorkflowDefinitions.${workflow.exportName}>>;`).join("\n")}
+}` : "";
+  const workflowsOmit = hasWorkflows ? ` | "workflows"` : "";
+  const workflowsContextField = hasWorkflows ? `
+    readonly workflows: LunoraWorkflows;` : "";
+  const server = `${GENERATED_HEADER}import { createPolicyDsl, initLunora, v as vBase } from "${base.server}";
+import type {
+    ActionBuilder,
+    ActionCtx as ActionCtxBase,
+    ColumnValidator,
+    DatabaseReader,
+    DatabaseWriter,
+    EmptyArgs,
+    InternalActionBuilder,
+    InternalMutationBuilder,
+    InternalQueryBuilder,
+    MutationBuilder,
+    MutationCtx as MutationCtxBase,
+    QueryBuilder,
+    QueryCtx as QueryCtxBase,
+    ReadOnlyStorage,
+    Storage as StorageBase,
+    TableReader,
+} from "${base.server}";
+
+import type { DataModel, DatabaseReaderFacade, DatabaseWriterFacade, Doc, Id as IdOfTable, OrmReader, OrmWriter, Relations, TableName } from "./dataModel.js";
+${aiTypeImport}${paymentsTypeImport}${containersTypeImport}${workflowsTypeImport}
+export type { DataModel, Doc, Id, TableName } from "./dataModel.js";
+
+/** Storage buckets this schema declares (\`v.storage("name")\`), narrowing \`ctx.storage.bucket(name)\`. */
+export type StorageBucketName = ${storageBucketUnion};${envBlock}${workflowsTypeBlock}
+
+/**
+ * Project-typed contexts. The base contexts from \`@lunora/server\` are
+ * untyped against the schema; here \`db\` is widened to the generated per-table
+ * facade (\`ctx.db.<table>.findMany(...)\`) while keeping the legacy structural
+ * \`db.get\`/\`db.query\` surface for back-compat, and \`storage\` is narrowed so
+ * \`ctx.storage.bucket(name)\` autocompletes the declared buckets.
+ */
+/**
+ * The Convex-style fluent reader \`ctx.db.query(table)\`, bound to this schema:
+ * a table-name literal narrows the row type, so \`.collect()\` / \`.first()\` /
+ * \`.take()\` (and the \`.withIndex()\` / \`.filter()\` / \`.order()\` chain) resolve
+ * as \`Doc<table>\` with no \`as unknown as Doc<...>\` casts. The per-table accessor
+ * \`ctx.db.<table>\` stays available alongside it via the facade.
+ *
+ * Intersected with the wide \`(string) => TableReader\` signature so the bound
+ * \`ctx.db\` is still structurally assignable to schema-agnostic consumers that
+ * call \`db.query(someString)\` (e.g. \`@lunora/ratelimit\`'s \`createDbStore\`).
+ */
+type TypedTableQuery = (<T extends TableName>(table: T) => TableReader<Doc<T>>) & ((table: string) => TableReader);
+
+/**
+ * The point read \`ctx.db.get(id)\`, bound to this schema: an \`Id<"table">\`
+ * carries its table name, so the resolved document is typed \`Doc<table>\` (or
+ * \`null\` when absent) with no \`as Doc<...>\` cast. Mirrors {@link TypedTableQuery}.
+ */
+type TypedTableGet = <T extends TableName>(id: IdOfTable<T>) => Promise<Doc<T> | null>;
+
+export interface QueryCtx extends Omit<QueryCtxBase, "db" | "storage"> {
+    readonly db: Omit<DatabaseReader, "query" | "get"> & DatabaseReaderFacade & { query: TypedTableQuery; get: TypedTableGet };
+    readonly orm: OrmReader;
+    readonly storage: ReadOnlyStorage<StorageBucketName>;${kvContextField}${analyticsContextField}
+}
+
+export interface MutationCtx extends Omit<MutationCtxBase, "db" | "storage"${workflowsOmit}> {
+    readonly db: Omit<DatabaseWriter, "query" | "get"> & DatabaseWriterFacade & { query: TypedTableQuery; get: TypedTableGet };
+    readonly orm: OrmWriter;
+    readonly storage: ReadOnlyStorage<StorageBucketName>;${kvContextField}${analyticsContextField}${workflowsContextField}
+}
+
+export interface ActionCtx extends Omit<ActionCtxBase, "db" | "storage"${workflowsOmit}> {
+    readonly db: Omit<DatabaseWriter, "query" | "get"> & DatabaseWriterFacade & { query: TypedTableQuery; get: TypedTableGet };
+    readonly orm: OrmWriter;
+    readonly storage: StorageBase<StorageBucketName>;${aiActionField}${paymentsActionField}${containersActionField}${kvContextField}${hyperdriveActionField}${browserActionField}${imagesActionField}${analyticsContextField}${pipelinesActionField}${workflowsContextField}
+}
+
+/**
+ * Procedure builders bound to this project's typed contexts. Chain
+ * \`.input({...})\` to declare args, \`.use(middleware)\` for rate limiting / RLS /
+ * masking (each middleware may refine \`ctx\`), then the terminal
+ * \`.query()\` / \`.mutation()\` / \`.action()\` with a \`({ ctx, args }) => ...\`
+ * handler. \`.output(validator)\` and (queries) \`.stream()\` are also available.
+ */
+const lunoraBuilders = initLunora.dataModel<DataModel>().create();
+
+/** \`query\` builder bound to this project's typed {@link QueryCtx}. */
+export const query = lunoraBuilders.query as unknown as QueryBuilder<QueryCtx, EmptyArgs>;
+
+/** \`mutation\` builder bound to this project's typed {@link MutationCtx}. */
+export const mutation = lunoraBuilders.mutation as unknown as MutationBuilder<MutationCtx, EmptyArgs>;
+
+/** \`action\` builder bound to this project's typed {@link ActionCtx}. */
+export const action = lunoraBuilders.action as unknown as ActionBuilder<ActionCtx, EmptyArgs>;
+
+/** \`internalQuery\` builder bound to this project's typed {@link QueryCtx} — never exposed on \`api\`. */
+export const internalQuery = lunoraBuilders.internalQuery as unknown as InternalQueryBuilder<QueryCtx, EmptyArgs>;
+
+/** \`internalMutation\` builder bound to this project's typed {@link MutationCtx} — never exposed on \`api\`. */
+export const internalMutation = lunoraBuilders.internalMutation as unknown as InternalMutationBuilder<MutationCtx, EmptyArgs>;
+
+/** \`internalAction\` builder bound to this project's typed {@link ActionCtx} — never exposed on \`api\`. */
+export const internalAction = lunoraBuilders.internalAction as unknown as InternalActionBuilder<ActionCtx, EmptyArgs>;
+
+/**
+ * \`definePolicy\` bound to THIS schema's {@link DataModel} + {@link Relations}.
+ * Import it from here (\`./_generated/server\`) instead of \`@lunora/server\` to get
+ * a relation-aware RLS authoring surface: \`table\` autocompletes to a real table
+ * name and the \`when\` predicate type-checks against the table's columns **and**
+ * its declared relations — \`{ author: { is: {...} } }\`, \`{ posts: { some: {...} } }\`,
+ * etc. (the \`@lunora/do\` pre-resolver resolves relation predicates on reads).
+ * Runtime-identical to \`@lunora/server\`'s \`definePolicy\`; only the types narrow,
+ * so the \`rls()\` chain discovers a policy authored either way the same.
+ */
+export const definePolicy = createPolicyDsl<DataModel, Relations>();
+
+/**
+ * The validator builder \`v\`, with \`v.id(...)\` constrained to THIS schema's
+ * table names — so the argument autocompletes and returns a precise
+ * \`Id<"table">\`. Identical to \`@lunora/server\`'s \`v\` at runtime; the only
+ * difference is the tightened \`id\` type.
+ *
+ * Import \`v\` from here (\`./_generated/server\`) in your queries/mutations/actions
+ * to get table-name autocomplete. \`lunora/schema.ts\` can't use it — it is the
+ * file that defines the table names, so they aren't known yet there; pass the
+ * names as string literals and the generated \`Id<"table">\` types still catch a
+ * typo wherever the id is used.
+ */
+export const v = vBase as unknown as Omit<typeof vBase, "id"> & {
+    id: <T extends TableName>(table: T) => ColumnValidator<IdOfTable<T>, IdOfTable<T>>;
+};
+`;
+  return server;
+};
+const renderLifecycleManifest = (functions) => {
+  const manifest = { connect: [], disconnect: [] };
+  for (const definition of functions) {
+    if (!definition.lifecycle) {
+      continue;
+    }
+    manifest[definition.lifecycle].push(`${sanitizeNamespace(definition.filePath)}:${definition.exportName}`);
+  }
+  return manifest;
+};
+const emitFunctions = (functions, migrations = []) => {
+  const hasFunctions = functions.length > 0;
+  const { dispatchBody, importBlock, migrationBody } = renderFunctionRegistry(functions, migrations);
+  const lifecycleHooks = renderLifecycleManifest(functions);
+  const caller = renderCaller(functions);
+  const callerTypes = caller.types ? `
+${caller.types}
+` : "";
+  const callerImpl = caller.implementation ? `
+${caller.implementation}
+` : "";
+  const callerDataModelImports = referencedDataModelImports(caller.types);
+  const dataModelImport = callerDataModelImports.length > 0 ? `import type { ${callerDataModelImports.join(", ")} } from "./dataModel.js";
+` : "";
+  const callerParameter = hasFunctions ? "context" : "_context";
+  const callRegisteredHelper = hasFunctions ? `${CALL_REGISTERED_HELPER}
+
+` : "";
+  return `${GENERATED_HEADER}${importBlock}import type { ActionCtx, MutationCtx, QueryCtx } from "./server.js";
+${dataModelImport}
+/**
+ * Single registered function, narrowed to the shape \`handleRpc\` needs.
+ * The real argument validators / return types are checked elsewhere — at
+ * the dispatch site we erase to \`unknown\` so a single map can host every
+ * registered function.
+ */
+export interface RegisteredLunoraFunction {
+    kind: "action" | "mutation" | "query" | "stream";
+    args: Record<string, unknown>;
+    /**
+     * For \`"action" | "mutation" | "query"\` the handler is awaited and its result returned.
+     * For \`"stream"\` the handler returns an \`AsyncIterable\` synchronously and takes an
+     * \`AbortSignal\` as a third argument — the runtime drives it frame-by-frame.
+     */
+    handler: ((context: unknown, args: Record<string, unknown>) => Promise<unknown> | unknown) | ((context: unknown, args: Record<string, unknown>, signal?: AbortSignal) => AsyncIterable<unknown>);
+    /** \`"internal"\` functions are rejected on the external RPC path; absence === public. */
+    visibility?: "internal" | "public";
+}
+
+/**
+ * Static dispatch table. The key matches the \`__lunoraRef\` the client
+ * emits (\`api[namespace][fn].__lunoraRef === "namespace:fn"\`).
+ */
+export const LUNORA_FUNCTIONS: Record<string, RegisteredLunoraFunction> = {${dispatchBody}};
+
+/**
+ * Connection-lifecycle manifest: the function paths the generated ShardDO
+ * dispatches when a client's WebSocket connects (\`connect\`) or disconnects
+ * (\`disconnect\`). Each path also resolves through {@link LUNORA_FUNCTIONS}; the
+ * DO runs every hook under the socket's verified identity via system dispatch.
+ */
+export const LUNORA_LIFECYCLE_HOOKS: { connect: readonly string[]; disconnect: readonly string[] } = {
+    connect: [${lifecycleHooks.connect.map((path) => JSON.stringify(path)).join(", ")}],
+    disconnect: [${lifecycleHooks.disconnect.map((path) => JSON.stringify(path)).join(", ")}],
+};
+
+/**
+ * Resolve and invoke a registered function from an external caller. Throws a
+ * LunoraError-shaped object (404) when the path is unknown — the runtime's
+ * structural error mapper turns that into the right HTTP status. Internal
+ * functions are treated as not-found so their existence never leaks to clients.
+ */
+export const dispatchLunoraFunction = async (functionPath: string, context: unknown, args: Record<string, unknown>): Promise<unknown> => {
+    const registered = LUNORA_FUNCTIONS[functionPath];
+
+    if (!registered || registered.visibility === "internal") {
+        throw Object.assign(new Error(\`function not registered: \${functionPath}\`), {
+            name: "LunoraError",
+            code: "FUNCTION_NOT_FOUND",
+            status: 404,
+        });
+    }
+
+    return registered.handler(context, args);
+};
+
+/**
+ * A handler context accepted by {@link createCaller}. The runtime context the
+ * shard DO builds is uniform across kinds, so any handler's \`ctx\` works here.
+ */
+export type CallerCtx = ActionCtx | MutationCtx | QueryCtx;
+
+/**
+ * Typed, in-process server-to-server caller. Every registered function — public
+ * *and* internal — is reachable; each call dispatches against the same shard
+ * with the supplied \`context\`, exactly like \`ctx.runQuery\`/\`runMutation\`/
+ * \`runAction\` but without re-stating the function path.
+ */
+export interface Caller {${callerTypes}}
+
+${callRegisteredHelper}/** Build a {@link Caller} bound to \`context\` (typically a handler's \`ctx\`). */
+export const createCaller = (${callerParameter}: CallerCtx): Caller => ({${callerImpl}});
+
+/**
+ * Single registered data migration, narrowed to the shape the per-shard runner
+ * consumes. \`up\`/\`down\` are erased to a structural transform; the authoring
+ * validation lives in \`defineMigration\`.
+ */
+export interface RegisteredDataMigration {
+    batchSize?: number;
+    down?: (document: Record<string, unknown>) => Record<string, unknown> | undefined;
+    id: string;
+    table: string;
+    up: (document: Record<string, unknown>) => Record<string, unknown> | undefined;
+}
+
+/**
+ * Registry of online data migrations keyed by \`defineMigration\`'s \`id\`. The
+ * shard DO's admin RPC and the CLI resolve migrations to run through this map.
+ */
+export const LUNORA_MIGRATIONS: Record<string, RegisteredDataMigration> = {${migrationBody}};
+`;
+};
+const buildTableReferences = (schema) => {
+  const references = {};
+  for (const table of schema.tables) {
+    const fields = {};
+    for (const [field, validator] of Object.entries(table.shape)) {
+      const resolved = validator.kind === "optional" && validator.inner ? validator.inner : validator;
+      if (resolved.kind === "id" && resolved.tableName !== void 0) {
+        fields[field] = resolved.tableName;
+      }
+    }
+    if (Object.keys(fields).length > 0) {
+      references[table.name] = fields;
+    }
+  }
+  return references;
+};
+const buildStorageColumns = (schema) => {
+  const byTable = {};
+  for (const table of schema.tables) {
+    const fields = [];
+    for (const [field, validator] of Object.entries(table.shape)) {
+      const resolved = validator.kind === "optional" && validator.inner ? validator.inner : validator;
+      if (resolved.kind === "storage") {
+        fields.push(field);
+      }
+    }
+    if (fields.length > 0) {
+      byTable[table.name] = fields;
+    }
+  }
+  return byTable;
+};
+const buildTableIndexes = (schema) => {
+  const byTable = {};
+  for (const table of schema.tables) {
+    const entries = [
+      ...table.indexes.map((index) => {
+        return { fields: [...index.fields], name: index.name, type: "index", ...index.unique === true ? { unique: true } : {} };
+      }),
+      ...table.searchIndexes.map((index) => {
+        return { fields: [index.field, ...index.filterFields ?? []], name: index.name, type: "search" };
+      }),
+      ...table.rankIndexes.map((index) => {
+        return { fields: index.sortBy.map((key) => key.field), name: index.name, type: "rank" };
+      }),
+      ...table.vectorIndexes.map((index) => {
+        return { fields: index.field === void 0 ? [] : [index.field], name: index.name, type: "vector" };
+      })
+    ];
+    if (entries.length > 0) {
+      byTable[table.name] = entries;
+    }
+  }
+  return byTable;
+};
+const buildTableColumns = (schema) => {
+  const byTable = {};
+  for (const table of schema.tables) {
+    const columns = [
+      { name: "_id", optional: false, pk: true, type: "id" },
+      { name: "_creationTime", optional: false, type: "number" }
+    ];
+    for (const [field, validator] of Object.entries(table.shape)) {
+      const optional = validator.kind === "optional" || Boolean(validator.column?.hasDefault);
+      const resolved = validator.kind === "optional" && validator.inner ? validator.inner : validator;
+      const column = { name: field, optional, type: resolved.kind };
+      if (resolved.kind === "id" && resolved.tableName !== void 0) {
+        column.ref = resolved.tableName;
+      }
+      if (resolved.kind === "storage") {
+        column.isStorage = true;
+      }
+      columns.push(column);
+    }
+    byTable[table.name] = columns;
+  }
+  return byTable;
+};
+const emitRelationFanout = (hasGlobalTables) => {
+  if (!hasGlobalTables) {
+    return { importFragment: "", override: "" };
+  }
+  return {
+    importFragment: "serveRelationFanout, ",
+    override: `
+        protected override async runRelationFanoutRead(functionPath: string, args: Record<string, unknown>): Promise<unknown> {
+            this.ensureMigrated();
+
+            const { db } = this.buildCtx({ functionPath }) as { db: DatabaseWriterLike };
+
+            return serveRelationFanout(schema as unknown as SchemaLike, db, functionPath, args);
+        }
+`
+  };
+};
+const emitAiFragments = (hasAi) => {
+  if (!hasAi) {
+    return { build: "", configField: "", contextField: "", stub: "" };
+  }
+  const aiMissing = `throw new Error("ctx.ai: no AI binding found. Add an \\\`ai\\\` binding (env.AI) to wrangler.jsonc, or pass \\\`ai\\\` to createShardDO().");`;
+  return {
+    // Build ctx.ai from the resolved Workers AI binding (a `config.ai` thunk
+    // override, else `env.AI`). createAi is provider-agnostic — a model-id
+    // string resolves Workers AI, any AI SDK model object passes through — so
+    // a handler is never locked to Workers AI. Falls back to `aiStub`.
+    build: `
+            const aiBinding = config.ai?.(env) ?? (env as Record<string, unknown>).AI;
+            const ai: LunoraAi = aiBinding ? createAi({ binding: aiBinding as AiBindingLike }) : aiStub;
+`,
+    // Optional override for the Workers AI binding. When omitted, ctx.ai is
+    // built from `env.AI` (the conventional binding the config layer
+    // auto-reconciles); the thunk lets a caller point it elsewhere or inject
+    // a double in tests.
+    configField: `
+    ai?: (env: Record<string, unknown>) => AiBindingLike;`,
+    contextField: `
+                ai,`,
+    stub: `
+const aiStub: LunoraAi = {
+    embeddingModel: () => {
+        ${aiMissing}
+    },
+    model: () => {
+        ${aiMissing}
+    },
+    run: async () => {
+        ${aiMissing}
+    },
+    // workersai is a callable-with-properties; a bare throwing arrow isn't
+    // structurally assignable, so cast it. Never invoked (the stub throws first).
+    workersai: (() => {
+        ${aiMissing}
+    }) as unknown as LunoraAi["workersai"],
+};
+`
+  };
+};
+const EMPTY_HELPER_FRAGMENTS = { build: "", configField: "", contextField: "", importLines: [], stub: "" };
+const emitKvFragments = (hasKv) => {
+  if (!hasKv) {
+    return EMPTY_HELPER_FRAGMENTS;
+  }
+  const kvMissing = `throw new Error("ctx.kv: no KV binding found. Add a \\\`kv_namespaces\\\` binding (env.KV) to wrangler.jsonc, or pass \\\`kv\\\` to createShardDO().");`;
+  return {
+    build: `
+            const kvBinding = config.kv?.(env) ?? (env as Record<string, unknown>).KV;
+            const kv: Kv = kvBinding ? createKv({ namespace: kvBinding as KVNamespaceLike }) : kvStub;
+`,
+    configField: `
+    kv?: (env: Record<string, unknown>) => KVNamespaceLike;`,
+    contextField: `
+                kv,`,
+    importLines: [`import type { Kv, KVNamespaceLike } from "@lunora/kv";`, `import { createKv } from "@lunora/kv";`],
+    stub: `
+const kvStub: Kv = {
+    delete: async () => {
+        ${kvMissing}
+    },
+    get: async () => {
+        ${kvMissing}
+    },
+    getRaw: async () => {
+        ${kvMissing}
+    },
+    getWithMetadata: async () => {
+        ${kvMissing}
+    },
+    list: async () => {
+        ${kvMissing}
+    },
+    put: async () => {
+        ${kvMissing}
+    },
+};
+`
+  };
+};
+const emitAnalyticsFragments = (hasAnalytics) => {
+  if (!hasAnalytics) {
+    return EMPTY_HELPER_FRAGMENTS;
+  }
+  const analyticsMissing = `throw new Error("ctx.analytics: no Analytics Engine binding found. Add an \\\`analytics_engine_datasets\\\` binding (env.ANALYTICS) to wrangler.jsonc, or pass \\\`analytics\\\` to createShardDO().");`;
+  return {
+    build: `
+            const analyticsBinding = config.analytics?.(env) ?? (env as Record<string, unknown>).ANALYTICS;
+            const analytics: AnalyticsClient = analyticsBinding ? createAnalytics(analyticsBinding as AnalyticsEngineDatasetLike) : analyticsStub;
+`,
+    configField: `
+    analytics?: (env: Record<string, unknown>) => AnalyticsEngineDatasetLike;`,
+    contextField: `
+                analytics,`,
+    importLines: [
+      `import type { AnalyticsClient, AnalyticsEngineDatasetLike } from "@lunora/analytics";`,
+      `import { createAnalytics } from "@lunora/analytics";`
+    ],
+    stub: `
+const analyticsStub: AnalyticsClient = {
+    track: () => {
+        ${analyticsMissing}
+    },
+    writeDataPoint: () => {
+        ${analyticsMissing}
+    },
+};
+`
+  };
+};
+const emitImagesFragments = (hasImages) => {
+  if (!hasImages) {
+    return EMPTY_HELPER_FRAGMENTS;
+  }
+  const imagesMissing = `throw new Error("ctx.images: no Images binding found. Add an \\\`images\\\` binding (env.IMAGES) to wrangler.jsonc, or pass \\\`images\\\` to createShardDO().");`;
+  return {
+    build: `
+            const imagesBinding = config.images?.(env) ?? (env as Record<string, unknown>).IMAGES;
+            const images: Images = imagesBinding ? createImages({ binding: imagesBinding as ImagesBindingLike }) : imagesStub;
+`,
+    configField: `
+    images?: (env: Record<string, unknown>) => ImagesBindingLike;`,
+    // ActionCtx-only: woven onto the action ctx object, never query/mutation.
+    contextField: `
+                images,`,
+    importLines: [`import type { Images, ImagesBindingLike } from "@lunora/images";`, `import { createImages } from "@lunora/images";`],
+    stub: `
+const imagesStub: Images = {
+    info: async () => {
+        ${imagesMissing}
+    },
+    transform: async () => {
+        ${imagesMissing}
+    },
+};
+`
+  };
+};
+const emitHyperdriveFragments = (hasHyperdrive) => {
+  if (!hasHyperdrive) {
+    return EMPTY_HELPER_FRAGMENTS;
+  }
+  const sqlMissing = `throw new Error("ctx.sql: provide a \\\`sql\\\` config thunk that builds a SqlClient from your driver, e.g. \\\`sql: (env) => fromPostgresJs(postgres(env.HYPERDRIVE.connectionString))\\\`.");`;
+  return {
+    build: `
+            const sql: SqlClient = config.sql ? config.sql(env) : sqlStub;
+`,
+    configField: `
+    sql?: (env: Record<string, unknown>) => SqlClient;`,
+    // ActionCtx-only: woven onto the action ctx object, never query/mutation.
+    contextField: `
+                sql,`,
+    importLines: [`import type { SqlClient } from "@lunora/hyperdrive";`],
+    stub: `
+const sqlStub: SqlClient = {
+    query: async () => {
+        ${sqlMissing}
+    },
+};
+`
+  };
+};
+const emitBrowserFragments = (hasBrowser) => {
+  if (!hasBrowser) {
+    return EMPTY_HELPER_FRAGMENTS;
+  }
+  const browserMissing = `throw new Error("ctx.browser: provide a \\\`browser\\\` config thunk, e.g. \\\`browser: (env) => createBrowser({ binding: env.BROWSER, launch })\\\` with \\\`import { launch } from '@cloudflare/playwright'\\\`.");`;
+  return {
+    build: `
+            const browser: Browser = config.browser ? config.browser(env) : browserStub;
+`,
+    configField: `
+    browser?: (env: Record<string, unknown>) => Browser;`,
+    // ActionCtx-only: woven onto the action ctx object, never query/mutation.
+    contextField: `
+                browser,`,
+    // Type-only import: the generated build never calls `createBrowser`
+    // (the `config.browser` thunk owns construction, injecting the optional
+    // `@cloudflare/playwright` peer the worker stays free of), so only the
+    // `Browser` type is referenced here.
+    importLines: [`import type { Browser } from "@lunora/browser";`],
+    stub: `
+const browserStub: Browser = {
+    content: async () => {
+        ${browserMissing}
+    },
+    launch: async () => {
+        ${browserMissing}
+    },
+    pdf: async () => {
+        ${browserMissing}
+    },
+    scrape: async () => {
+        ${browserMissing}
+    },
+    screenshot: async () => {
+        ${browserMissing}
+    },
+};
+`
+  };
+};
+const emitContainers = (containers) => {
+  if (containers.length === 0) {
+    return "";
+  }
+  const classes = containers.map((container) => {
+    assertIdentifier(container.exportName, `container export "${container.exportName}"`);
+    assertIdentifier(container.className, `container class "${container.className}"`);
+    return `/** Container DO for the \`${container.exportName}\` definition (binding \`${container.bindingName}\`). */
+export class ${container.className} extends LunoraContainer {
+    public constructor(ctx: ConstructorParameters<typeof LunoraContainer>[0], env: Record<string, unknown>) {
+        super(ctx, env, ${container.exportName}, "${container.exportName}");
+    }
+}
+`;
+  }).join("\n");
+  const imports = containers.map((container) => container.exportName).join(", ");
+  return `${GENERATED_HEADER}/**
+ * Container-enabled Durable Object classes for the containers declared in
+ * \`lunora/containers.ts\`. Re-export them from your worker entry — wrangler
+ * requires each \`containers[].class_name\` to be exported by the worker:
+ *
+ * \`export * from "./lunora/_generated/containers.js";\`
+ */
+import LunoraContainer from "@lunora/container/do";
+
+import { ${imports} } from "../containers.js";
+
+${classes}`;
+};
+const emitContainerFragments = (containers) => {
+  if (containers.length === 0) {
+    return { build: "", contextField: "", importLines: [], specs: "" };
+  }
+  for (const container of containers) {
+    assertIdentifier(container.exportName, `container export "${container.exportName}"`);
+    assertIdentifier(container.bindingName, `container binding "${container.bindingName}"`);
+  }
+  const specEntries = containers.map((container) => {
+    const maxInstances = container.maxInstances === void 0 ? "" : `, maxInstances: ${String(container.maxInstances)}`;
+    return `    { binding: "${container.bindingName}", exportName: "${container.exportName}"${maxInstances} },`;
+  }).join("\n");
+  return {
+    build: `
+            const containers = createContainerContext(env, LUNORA_CONTAINERS);
+`,
+    contextField: `
+                containers,`,
+    importLines: [`import type { ContainerBindingSpec } from "@lunora/container";`, `import { createContainerContext } from "@lunora/container";`],
+    // eslint-disable-next-line no-secrets/no-secrets -- the emitted readonly-array type annotation is dense generated TS, not a credential
+    specs: `
+/** Wiring specs for \`ctx.containers\` (codegen-derived from \`lunora/containers.ts\`). */
+const LUNORA_CONTAINERS: ReadonlyArray<ContainerBindingSpec> = [
+${specEntries}
+];
+`
+  };
+};
+const emitWorkflows = (workflows) => {
+  if (workflows.length === 0) {
+    return "";
+  }
+  const classes = workflows.map((workflow) => {
+    assertIdentifier(workflow.exportName, `workflow export "${workflow.exportName}"`);
+    assertIdentifier(workflow.className, `workflow class "${workflow.className}"`);
+    return `/** WorkflowEntrypoint for the \`${workflow.exportName}\` definition (binding \`${workflow.bindingName}\`). */
+export class ${workflow.className} extends LunoraWorkflow<WorkflowParamsOf<typeof ${workflow.exportName}>, WorkflowOutputOf<typeof ${workflow.exportName}>> {
+    public constructor(ctx: ConstructorParameters<typeof LunoraWorkflow>[0], env: Record<string, unknown>) {
+        super(ctx, env, ${workflow.exportName}, "${workflow.exportName}");
+    }
+}
+`;
+  }).join("\n");
+  const imports = workflows.map((workflow) => workflow.exportName).join(", ");
+  return `${GENERATED_HEADER}/**
+ * WorkflowEntrypoint classes for the workflows declared in
+ * \`lunora/workflows.ts\`. Re-export them from your worker entry — wrangler
+ * requires each \`workflows[].class_name\` to be exported by the worker:
+ *
+ * \`export * from "./lunora/_generated/workflows.js";\`
+ */
+import LunoraWorkflow from "@lunora/workflow/do";
+
+import { ${imports} } from "../workflows.js";
+
+/** Params type carried by a \`defineWorkflow\` definition (its phantom \`__params\`), so each entrypoint keeps the authored \`ctx.params\` type. */
+type WorkflowParamsOf<Definition> = Definition extends { __params?: infer Params }
+    ? unknown extends Params
+        ? Record<string, unknown>
+        : NonNullable<Params>
+    : Record<string, unknown>;
+
+/** Output type carried by a \`defineWorkflow\` definition (its phantom \`__output\`), so each entrypoint keeps the authored return type. */
+type WorkflowOutputOf<Definition> = Definition extends { __output?: infer Output } ? Output : unknown;
+
+${classes}`;
+};
+const emitWorkflowFragments = (workflows) => {
+  if (workflows.length === 0) {
+    return { build: "", contextField: "", importLines: [], specs: "" };
+  }
+  for (const workflow of workflows) {
+    assertIdentifier(workflow.exportName, `workflow export "${workflow.exportName}"`);
+    assertIdentifier(workflow.bindingName, `workflow binding "${workflow.bindingName}"`);
+  }
+  const specEntries = workflows.map((workflow) => `    { binding: "${workflow.bindingName}", exportName: "${workflow.exportName}" },`).join("\n");
+  return {
+    build: `
+            const workflows = createWorkflowContext(env, LUNORA_WORKFLOWS);
+`,
+    contextField: `
+                workflows,`,
+    importLines: [`import type { WorkflowBindingSpec } from "@lunora/workflow";`, `import { createWorkflowContext } from "@lunora/workflow";`],
+    // eslint-disable-next-line no-secrets/no-secrets -- the emitted readonly-array type annotation is dense generated TS, not a credential
+    specs: `
+/** Wiring specs for \`ctx.workflows\` (codegen-derived from \`lunora/workflows.ts\`). */
+const LUNORA_WORKFLOWS: ReadonlyArray<WorkflowBindingSpec> = [
+${specEntries}
+];
+`
+  };
+};
+const emitWorkflowsMetadataFragments = (workflows) => {
+  if (workflows.length === 0) {
+    return { constant: "", override: "" };
+  }
+  const metadata = {
+    workflows: workflows.map((workflow) => {
+      return {
+        binding: workflow.bindingName,
+        className: workflow.className,
+        exportName: workflow.exportName,
+        name: workflow.name
+      };
+    })
+  };
+  return {
+    constant: `
+/** Read-only declared-workflow metadata (discovered from \`lunora/workflows.ts\`) served via \`__lunora_admin__:listWorkflows\` for the studio's workflows view. */
+const LUNORA_WORKFLOWS_INFO: WorkflowsResult = ${JSON.stringify(metadata, void 0, 4)};
+`,
+    override: `
+        protected override workflowsMetadata(): WorkflowsResult {
+            return LUNORA_WORKFLOWS_INFO;
+        }
+`
+  };
+};
+const emitPaymentFragments = (hasPayments) => {
+  if (!hasPayments) {
+    return { build: "", configField: "", contextField: "", imports: [], stub: "" };
+  }
+  const missing = `throw new Error("ctx.payments: no payment configured. Pass \\\`payment\\\` to createShardDO().");`;
+  return {
+    imports: [
+      `import type { LunoraDatabaseLike as LunoraPaymentDbLike, LunoraPayment, PaymentsFromContextOptions } from "@lunora/payment";`,
+      `import { paymentsFromContext } from "@lunora/payment";`
+    ],
+    // Built after `db` (the store rides ctx.db) and `userId` (the default authorizer ties a
+    // referenceId to the caller). The adapter — which carries provider secrets — comes from
+    // the `config.payment` thunk over env. Falls back to `paymentStub`.
+    build: `
+            const payments: LunoraPayment = config.payment
+                ? paymentsFromContext({ auth: { userId: userId ?? null }, db: db as unknown as LunoraPaymentDbLike }, config.payment(env))
+                : paymentStub;
+`,
+    configField: `
+    payment?: (env: Record<string, unknown>) => PaymentsFromContextOptions;`,
+    contextField: `
+                payments,`,
+    stub: `
+const paymentStub: LunoraPayment = {
+    attach: () => {
+        ${missing}
+    },
+    cancelSubscription: () => {
+        ${missing}
+    },
+    check: () => {
+        ${missing}
+    },
+    createCheckout: () => {
+        ${missing}
+    },
+    createPortalSession: () => {
+        ${missing}
+    },
+    handleWebhook: () => {
+        ${missing}
+    },
+    listBalances: () => {
+        ${missing}
+    },
+    listSubscriptions: () => {
+        ${missing}
+    },
+    track: () => {
+        ${missing}
+    },
+} as unknown as LunoraPayment;
+`
+  };
+};
+const buildDoTypeImports = (hasVectors, hasWorkflows) => [
+  "AdvisoryFinding",
+  "DatabaseWriterLike",
+  "DataMigrationLike",
+  "LogSink",
+  "MaskPoliciesResult",
+  "MigrationRunResult",
+  "RunShardApplyCdcArgs",
+  "RunShardMigrationArgs",
+  "RlsPoliciesResult",
+  "RunShardRankBeforeArgs",
+  "RunShardRankPageArgs",
+  "RunShardWriteArgs",
+  "RunShardWriteResult",
+  "SchedulerLike",
+  "SchemaLike",
+  "ShardDOState",
+  "ShardRankPageResult",
+  "SqlExec",
+  "StorageRulesResult",
+  "StudioFeaturesResult",
+  "SystemReaderStorageLike",
+  ...hasWorkflows ? ["WorkflowsResult"] : [],
+  ...hasVectors ? ["WriteHook"] : []
+];
+const emitShard = ({
+  advisories = [],
+  containers = [],
+  hasAi = false,
+  hasAnalytics = false,
+  hasBrowser = false,
+  hasHyperdrive = false,
+  hasImages = false,
+  hasKv = false,
+  hasPayments = false,
+  maskMetadata,
+  rlsMetadata,
+  schema,
+  storageRules,
+  studioFeatures,
+  useUmbrella = false,
+  workflows = []
+}) => {
+  const base = baseSpecifiers(useUmbrella);
+  const { build: aiBuild, configField: aiConfigField, contextField: aiContextField, stub: aiStub } = emitAiFragments(hasAi);
+  const kvFragments = emitKvFragments(hasKv);
+  const analyticsFragments = emitAnalyticsFragments(hasAnalytics);
+  const imagesFragments = emitImagesFragments(hasImages);
+  const hyperdriveFragments = emitHyperdriveFragments(hasHyperdrive);
+  const browserFragments = emitBrowserFragments(hasBrowser);
+  const {
+    build: containersBuild,
+    contextField: containersContextField,
+    importLines: containerImportLines,
+    specs: containerSpecs
+  } = emitContainerFragments(containers);
+  const {
+    build: workflowsBuild,
+    contextField: workflowsContextField,
+    importLines: workflowImportLines,
+    specs: workflowSpecs
+  } = emitWorkflowFragments(workflows);
+  const {
+    build: paymentsBuild,
+    configField: paymentsConfigField,
+    contextField: paymentsContextField,
+    imports: paymentsImports,
+    stub: paymentStub
+  } = emitPaymentFragments(hasPayments);
+  const advisoryData = advisories;
+  const rlsData = rlsMetadata ?? { policies: [], roles: [] };
+  const maskData = maskMetadata ?? { columns: [] };
+  const storageRulesData = storageRules ?? { rules: [] };
+  const studioFeaturesData = studioFeatures ?? {
+    mail: false,
+    payments: false,
+    scheduler: false,
+    storage: false,
+    vectors: false,
+    workflows: false
+  };
+  const { constant: workflowsMetadataConst, override: workflowsMetadataOverride } = emitWorkflowsMetadataFragments(workflows);
+  const hasVectors = schema.vectorIndexes.length > 0;
+  const hasGlobalTables = schema.tables.some((table) => table.shardMode === "global");
+  const hasHyperdriveGlobal = schema.tables.some((table) => table.shardMode === "global" && table.globalBackend === "hyperdrive");
+  const hasD1Global = schema.tables.some((table) => table.shardMode === "global" && table.globalBackend !== "hyperdrive");
+  if (hasD1Global && hasHyperdriveGlobal) {
+    throw new Error(
+      'lunora codegen: mixing `.global()` (D1) and `.global({ backend: "hyperdrive" })` tables in one app is not supported yet — use a single global backend.'
+    );
+  }
+  const hasTables = schema.tables.length > 0;
+  const tableReferences = buildTableReferences(schema);
+  const tableIndexes = buildTableIndexes(schema);
+  const tableColumns = buildTableColumns(schema);
+  const storageColumns = buildStorageColumns(schema);
+  const doTypeImports = buildDoTypeImports(hasVectors, workflows.length > 0);
+  const relationFanout = emitRelationFanout(hasGlobalTables);
+  const importLines = [
+    `import type { ${doTypeImports.join(", ")} } from "${base.do}";`,
+    `import { applyCdcChanges, createShardCtxDb, runDataMigration, runShardMigrations, ${relationFanout.importFragment}ShardDO as ShardDOBase } from "${base.do}";`,
+    // `asBucketStorage` (the bucket-aware `ctx.storage` wrapper) lives in
+    // `@lunora/server`, the single source — imported here rather than stamped
+    // inline into every generated shard.
+    `import { asBucketStorage } from "${base.server}";`
+  ];
+  if (hasTables) {
+    importLines.push(`import { bindOrm, bindTableFacade } from "${base.server}";`);
+  }
+  if (hasVectors) {
+    importLines.push(
+      `import type { SchemaLike as VectorSchemaLike, VectorizeIndexLike, VectorSearchLike } from "@lunora/vectors";`,
+      `import { createContextVectors, createVectors, createVectorSyncHook } from "@lunora/vectors";`
+    );
+  }
+  if (hasAi) {
+    importLines.push(`import type { AiBindingLike, LunoraAi } from "@lunora/ai";`, `import { createAi } from "@lunora/ai";`);
+  }
+  importLines.push(
+    ...kvFragments.importLines,
+    ...analyticsFragments.importLines,
+    ...imagesFragments.importLines,
+    ...hyperdriveFragments.importLines,
+    ...browserFragments.importLines,
+    ...containerImportLines,
+    ...workflowImportLines,
+    ...paymentsImports,
+    ``,
+    `import schema from "../schema.js";`,
+    `import { LUNORA_FUNCTIONS, LUNORA_LIFECYCLE_HOOKS, LUNORA_MIGRATIONS } from "./functions.js";`
+  );
+  const vectorsConfigField = hasVectors ? `
+    vectors?: (env: Record<string, unknown>) => Record<string, VectorizeIndexLike>;` : "";
+  const d1ConfigField = hasD1Global ? `
+    d1?: (env: Record<string, unknown>, request?: { identity?: Record<string, unknown>; userId?: string }) => DatabaseWriterLike | undefined;` : "";
+  const hyperdriveGlobalConfigField = hasHyperdriveGlobal ? `
+    hyperdriveGlobal?: (env: Record<string, unknown>, request?: { identity?: Record<string, unknown>; userId?: string }) => DatabaseWriterLike | undefined;` : "";
+  const globalDatabaseStub = hasGlobalTables ? `
+const globalDbStub: DatabaseWriterLike = {
+    aggregate: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    count: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    delete: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    findFirst: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    findFirstOrThrow: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    findMany: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    get: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    groupBy: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    insert: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    normalizeId: () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    patch: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    query: () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    rank: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    rankPage: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+    replace: async () => {
+        throw new Error("ctx.db.<globalTable>: no global backend configured. Pass \`d1\` or \`hyperdriveGlobal\` to createShardDO().");
+    },
+};
+` : "";
+  const vectorsStub = hasVectors ? `
+const vectorsStub: VectorSearchLike = {
+    deleteByIds: async () => {
+        throw new Error("ctx.vectors: no vectors configured. Pass \`vectors\` to createShardDO().");
+    },
+    getByIds: async () => {
+        throw new Error("ctx.vectors: no vectors configured. Pass \`vectors\` to createShardDO().");
+    },
+    query: async () => {
+        throw new Error("ctx.vectors: no vectors configured. Pass \`vectors\` to createShardDO().");
+    },
+    upsert: async () => {
+        throw new Error("ctx.vectors: no vectors configured. Pass \`vectors\` to createShardDO().");
+    },
+    upsertNow: async () => {
+        throw new Error("ctx.vectors: no vectors configured. Pass \`vectors\` to createShardDO().");
+    },
+};
+` : "";
+  const vectorsBuild = hasVectors ? `
+            let vectors: VectorSearchLike;
+            let onWrite: WriteHook | undefined;
+
+            if (config.vectors) {
+                const lunora = createVectors({ indexes: config.vectors(env) });
+
+                vectors = createContextVectors(lunora);
+                onWrite = createVectorSyncHook({ schema: schema as unknown as VectorSchemaLike, vectors });
+            } else {
+                vectors = vectorsStub;
+                onWrite = undefined;
+            }
+` : "";
+  const globalDatabaseField = hasGlobalTables ? "\n                globalDb," : "";
+  const authField = "\n                auth: { identity: identity ?? null, userId: userId ?? null },";
+  const databaseOptions = hasVectors ? `{${authField}
+                broadcast: (delta) => {
+                    this.recordChangedTable(delta.table);
+                },
+                cdc: config.cdc ?? false,
+                enforceRls: true,
+                onIndexUse: this.getCtxDbIndexUseHook(),
+                onRead: options.onRead ?? this.getCtxDbReadHook(),
+                onWrite,
+                scheduler,
+                schema: schema as unknown as SchemaLike,
+                sql: this.sql as SqlExec,
+                storage,${globalDatabaseField}
+            }` : `{${authField}
+                broadcast: (delta) => {
+                    this.recordChangedTable(delta.table);
+                },
+                cdc: config.cdc ?? false,
+                enforceRls: true,
+                onIndexUse: this.getCtxDbIndexUseHook(),
+                onRead: options.onRead ?? this.getCtxDbReadHook(),
+                scheduler,
+                schema: schema as unknown as SchemaLike,
+                sql: this.sql as SqlExec,
+                storage,${globalDatabaseField}
+            }`;
+  const vectorsContextField = hasVectors ? `
+                vectors,` : "";
+  const ormContextField = hasTables ? `
+                orm: bindOrm(facade),` : "";
+  const bindTableHelper = "";
+  const globalDatabaseThunk = hasHyperdriveGlobal ? "config.hyperdriveGlobal" : "config.d1";
+  const globalDatabaseLine = hasGlobalTables ? `            const globalDb: DatabaseWriterLike = ${globalDatabaseThunk}?.(env, { identity, userId }) ?? globalDbStub;
+` : "";
+  const facadeBlock = hasTables ? `
+            const facade = db as unknown as Record<string, ReturnType<typeof bindTableFacade>>;
+${schema.tables.map(
+    // Always bind through `db` (the shard ctx-db) — even for `.global()`
+    // tables. `createShardCtxDb` routes global ops to the D1 `globalDb`
+    // internally AND stamps the read-dependency / change-broadcast hooks that
+    // drive live subscriptions; binding a global facade straight to `globalDb`
+    // would skip those, so a `ctx.db.<global>` read/write would never refresh
+    // a subscriber of that table.
+    (table) => `            facade[${JSON.stringify(table.name)}] = bindTableFacade(db, ${JSON.stringify(table.name)});`
+  ).join("\n")}
+` : "";
+  const everyContextBuild = `${kvFragments.build}${analyticsFragments.build}`;
+  const everyContextField = `${kvFragments.contextField}${analyticsFragments.contextField}`;
+  const actionOnlyHasAny = hasImages || hasHyperdrive || hasBrowser;
+  const actionOnlyBlock = actionOnlyHasAny ? `
+            // ActionCtx-only helpers (external, non-deterministic I/O): constructed
+            // and attached only for an \`action\` so query/mutation ctx never carry them.
+            if (isAction) {
+${imagesFragments.build}${hyperdriveFragments.build}${browserFragments.build}${[
+    ...hasImages ? ["                ctx.images = images;"] : [],
+    ...hasHyperdrive ? ["                ctx.sql = sql;"] : [],
+    ...hasBrowser ? ["                ctx.browser = browser;"] : []
+  ].join("\n")}
+            }
+` : "";
+  const isActionLine = actionOnlyHasAny ? `            const isAction = LUNORA_FUNCTIONS[options.functionPath ?? ""]?.kind === "action";
+` : "";
+  return `${GENERATED_HEADER}${importLines.join("\n")}
+
+type FunctionKind = "action" | "mutation" | "query";
+
+interface FunctionReference {
+    __lunoraRef: string;
+}
+
+/** Foreign-key columns per table (\`v.id("target")\` fields) for the data browser. */
+const LUNORA_TABLE_REFS: Record<string, Record<string, string>> = ${JSON.stringify(tableReferences, void 0, 4)};
+
+/** Declared indexes per table (secondary, search, rank, vector) for the schema viewer. */
+const LUNORA_TABLE_INDEXES: Record<string, Array<{ fields: string[]; name: string; type: "index" | "rank" | "search" | "vector"; unique?: boolean }>> = ${JSON.stringify(tableIndexes, void 0, 4)};
+
+/** Columns per table (typed, with PK/FK markers) for the studio's schema diagram, served via \`__lunora_admin__:describeTable\`. */
+const LUNORA_TABLE_COLUMNS: Record<string, Array<{ isStorage?: boolean; name: string; optional: boolean; pk?: boolean; ref?: string; type: string }>> = ${JSON.stringify(tableColumns, void 0, 4)};
+
+/** Storage-key columns per table (\`v.storage(...)\` fields) for the file browser's records↔files join. */
+const LUNORA_STORAGE_COLUMNS: Record<string, string[]> = ${JSON.stringify(storageColumns, void 0, 4)};
+
+/** Static schema advisories (computed by @lunora/advisor at codegen time) served via \`__lunora_admin__:getAdvisories\`. */
+const LUNORA_ADVISORIES: AdvisoryFinding[] = ${JSON.stringify(advisoryData, void 0, 4)};
+
+/** Read-only RLS metadata (policies + roles discovered from \`.use(rls(...))\` chains) served via \`__lunora_admin__:rlsPolicies\` for the studio's RLS inspector. */
+const LUNORA_RLS_METADATA: RlsPoliciesResult = ${JSON.stringify(rlsData, void 0, 4)};
+
+/** Read-only masking metadata (table + column + strategy discovered from \`.use(mask(...))\` chains) served via \`__lunora_admin__:maskPolicies\` for the studio's data-browser mask preview. */
+const LUNORA_MASK_METADATA: MaskPoliciesResult = ${JSON.stringify(maskData, void 0, 4)};
+
+/** Read-only storage access-rule metadata (discovered from \`.use(storageRules(...))\` chains) served via \`__lunora_admin__:storageRules\` for the studio's access-rules view. */
+const LUNORA_STORAGE_RULES: StorageRulesResult = ${JSON.stringify(storageRulesData, void 0, 4)};
+
+/** Which optional package-backed features this app wires up (discovered from imports / \`ctx.*\` reads / schema signals) served via \`__lunora_admin__:studioFeatures\` so the studio hides nav pages whose package isn't enabled. */
+const LUNORA_STUDIO_FEATURES: StudioFeaturesResult = ${JSON.stringify(studioFeaturesData, void 0, 4)};
+${workflowsMetadataConst}${containerSpecs}${workflowSpecs}
+export interface ShardDOConfig {
+    /** Opt into change-data-capture: records a post-image to \`__cdc_log\` on every write (backs streaming export + replay-PITR). */
+    cdc?: boolean;
+    /** Optional telemetry sink. When supplied, each \`ctx.log.*\` call is forwarded to \`sink.onLog\`. Pass the SAME sink you give \`createWorker({ observability })\` (which drives \`onRpc\`) to route both RPC and log events. */
+    observability?: (env: Record<string, unknown>) => LogSink | undefined;
+    scheduler?: (env: Record<string, unknown>) => unknown;
+    storage?: (env: Record<string, unknown>) => unknown;${vectorsConfigField}${aiConfigField}${kvFragments.configField}${analyticsFragments.configField}${imagesFragments.configField}${hyperdriveFragments.configField}${browserFragments.configField}${paymentsConfigField}${d1ConfigField}${hyperdriveGlobalConfigField}
+}
+
+const schedulerStub = {
+    cancel: async () => {
+        throw new Error("ctx.scheduler: no scheduler configured. Pass \`scheduler\` to createShardDO().");
+    },
+    runAfter: async () => {
+        throw new Error("ctx.scheduler: no scheduler configured. Pass \`scheduler\` to createShardDO().");
+    },
+    runAt: async () => {
+        throw new Error("ctx.scheduler: no scheduler configured. Pass \`scheduler\` to createShardDO().");
+    },
+};
+
+const storageStub = {
+    delete: async () => {
+        throw new Error("ctx.storage: no storage configured. Pass \`storage\` to createShardDO().");
+    },
+    download: async () => {
+        throw new Error("ctx.storage: no storage configured. Pass \`storage\` to createShardDO().");
+    },
+    getMetadata: async () => {
+        throw new Error("ctx.storage: no storage configured. Pass \`storage\` to createShardDO().");
+    },
+    getSignedUrl: async () => {
+        throw new Error("ctx.storage: no storage configured. Pass \`storage\` to createShardDO().");
+    },
+    getUrl: () => {
+        throw new Error("ctx.storage: no storage configured. Pass \`storage\` to createShardDO().");
+    },
+    list: async () => {
+        throw new Error("ctx.storage: no storage configured. Pass \`storage\` to createShardDO().");
+    },
+    upload: async () => {
+        throw new Error("ctx.storage: no storage configured. Pass \`storage\` to createShardDO().");
+    },
+};
+${globalDatabaseStub}${vectorsStub}${aiStub}${kvFragments.stub}${analyticsFragments.stub}${imagesFragments.stub}${hyperdriveFragments.stub}${browserFragments.stub}${paymentStub}${bindTableHelper}
+// Bound in-process \`ctx.run*\` composition depth so a self- or cyclically-
+// referencing call fails loudly with a clear error instead of overflowing the
+// stack. Tracked across the awaited handler chain (one DO invocation is
+// single-threaded), so the counter reflects true nesting depth.
+const MAX_RUN_DEPTH = 32;
+let runDepth = 0;
+
+const dispatchRun = async (expected: FunctionKind, functionPath: string, args: Record<string, unknown>, ctx: unknown): Promise<unknown> => {
+    const registered = LUNORA_FUNCTIONS[functionPath];
+
+    if (!registered) {
+        throw new Error(\`unknown function: \${functionPath}\`);
+    }
+
+    if (registered.kind !== expected) {
+        throw new Error(\`ctx.run\${expected[0]!.toUpperCase()}\${expected.slice(1)}: "\${functionPath}" is registered as a \${registered.kind}, not a \${expected}\`);
+    }
+
+    if (runDepth >= MAX_RUN_DEPTH) {
+        throw Object.assign(new Error(\`ctx.run*: composition depth limit (\${MAX_RUN_DEPTH}) exceeded — likely a cyclic runQuery/runMutation\`), {
+            name: "LunoraError",
+            code: "RUN_DEPTH_EXCEEDED",
+            status: 500,
+        });
+    }
+
+    runDepth += 1;
+
+    try {
+        return await registered.handler(ctx, args);
+    } finally {
+        runDepth -= 1;
+    }
+};
+
+/**
+ * Build the project's shard Durable Object. Export the result as \`ShardDO\`
+ * from the worker entry so wrangler binds it by name.
+ */
+export const createShardDO = (config: ShardDOConfig = {}): new (state: ShardDOState, env: unknown) => ShardDOBase =>
+    class extends ShardDOBase {
+        private migrated = false;
+
+        public override async handleRpc(functionPath: string, args: Record<string, unknown>): Promise<unknown> {
+            const registered = LUNORA_FUNCTIONS[functionPath];
+
+            // Internal functions are reachable server-side only: via \`ctx.run*\`
+            // composition, or a trusted system dispatch (scheduler/cron, marked by
+            // \`isSystemDispatch()\`). A client RPC never carries that flag, so its
+            // internals stay not-found and never leak across the external boundary.
+            if (!registered || (registered.visibility === "internal" && !this.isSystemDispatch())) {
+                throw Object.assign(new Error(\`function not registered: \${functionPath}\`), {
+                    name: "LunoraError",
+                    code: "FUNCTION_NOT_FOUND",
+                    status: 404,
+                });
+            }
+
+            this.ensureMigrated();
+
+            const ctx = this.buildCtx({ functionPath });
+
+            // A mutation's writes must commit all-or-nothing: wrap its dispatch in
+            // the DO's BEGIN/COMMIT span so any throw (a validator, an RLS denial,
+            // an OCC conflict, a failed row mid-\`insertMany\`/\`patchMany\`) rolls
+            // back every write the mutation made. Queries are read-only and actions
+            // do external I/O that can't be rolled back, so both dispatch directly.
+            // \`ctx.run*\` composition runs inside this span (it never re-enters
+            // handleRpc); runInTransaction's own guard rejects accidental nesting.
+            if (registered.kind === "mutation") {
+                return this.runInTransaction(() => registered.handler(ctx, args));
+            }
+
+            return registered.handler(ctx, args);
+        }
+${relationFanout.override}
+        protected override async executeSubscription(functionPath: string, args: Record<string, unknown>, identity?: { identity?: Record<string, unknown>; userId?: string }): Promise<{ result: unknown; tables: Set<string> } | null> {
+            const registered = LUNORA_FUNCTIONS[functionPath];
+
+            if (!registered || registered.kind !== "query" || registered.visibility === "internal") {
+                return null;
+            }
+
+            this.ensureMigrated();
+
+            const tables = new Set<string>();
+            // Identity is threaded EXPLICITLY from the (deferred/interleaved)
+            // subscription caller — never read from the shared per-request field
+            // here — so a concurrent RPC can't leak its identity into this re-run.
+            const ctx = this.buildCtx({ functionPath, identity, onRead: (table) => tables.add(table) });
+            const result = await registered.handler(ctx, args);
+
+            return { result, tables };
+        }
+
+        protected override executeStream(functionPath: string, args: Record<string, unknown>): null | { iterator: (signal: AbortSignal) => AsyncIterable<unknown> } {
+            const registered = LUNORA_FUNCTIONS[functionPath];
+
+            if (!registered || registered.kind !== "stream" || registered.visibility === "internal") {
+                return null;
+            }
+
+            this.ensureMigrated();
+
+            return {
+                iterator: (signal) => (registered.handler as (context: unknown, args: Record<string, unknown>, signal: AbortSignal) => AsyncIterable<unknown>)(this.buildCtx({ functionPath }), args, signal),
+            };
+        }
+
+        protected override lifecycleHookPaths(event: "connect" | "disconnect"): readonly string[] {
+            return LUNORA_LIFECYCLE_HOOKS[event];
+        }
+
+        protected override tableRefs(table: string): Record<string, string> | undefined {
+            return LUNORA_TABLE_REFS[table];
+        }
+
+        protected override tableIndexes(table: string): Array<{ fields: string[]; name: string; type: "index" | "rank" | "search" | "vector"; unique?: boolean }> {
+            return LUNORA_TABLE_INDEXES[table] ?? [];
+        }
+
+        protected override tableColumns(table: string): Array<{ isStorage?: boolean; name: string; optional: boolean; pk?: boolean; ref?: string; type: string }> {
+            return LUNORA_TABLE_COLUMNS[table] ?? [];
+        }
+
+        protected override storageColumns(): Record<string, string[]> {
+            return LUNORA_STORAGE_COLUMNS;
+        }
+
+        protected override rlsMetadata(): RlsPoliciesResult {
+            return LUNORA_RLS_METADATA;
+        }
+
+        protected override maskMetadata(): MaskPoliciesResult {
+            return LUNORA_MASK_METADATA;
+        }
+
+        protected override storageRulesMetadata(): StorageRulesResult {
+            return LUNORA_STORAGE_RULES;
+        }
+
+        protected override studioFeatures(): StudioFeaturesResult {
+            return LUNORA_STUDIO_FEATURES;
+        }
+${workflowsMetadataOverride}
+        protected override advisories(): AdvisoryFinding[] {
+            return LUNORA_ADVISORIES;
+        }
+
+        protected override async runShardDataMigration(args: RunShardMigrationArgs): Promise<MigrationRunResult> {
+            const migration = LUNORA_MIGRATIONS[args.id];
+
+            if (!migration) {
+                throw Object.assign(new Error(\`data migration "\${args.id}" is not registered\`), {
+                    name: "LunoraError",
+                    code: "MIGRATION_NOT_FOUND",
+                    status: 404,
+                });
+            }
+
+            this.ensureMigrated();
+
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            const scheduler = (config.scheduler?.(env) ?? schedulerStub) as SchedulerLike;
+            const writer = createShardCtxDb({
+                broadcast: (delta) => {
+                    this.recordChangedTable(delta.table);
+                },
+                cdc: config.cdc ?? false,
+                scheduler,
+                schema: schema as unknown as SchemaLike,
+                sql: this.sql as SqlExec,
+            });
+
+            return runDataMigration({
+                batchSize: args.batchSize,
+                direction: args.direction,
+                dryRun: args.dryRun,
+                maxBatches: args.maxBatches,
+                migration: migration as unknown as DataMigrationLike,
+                // Flush after each batch so live migrationStatus subscribers see
+                // progress mid-run (the base method records the reserved state
+                // table the raw-SQL progress write is invisible to the tracker).
+                onBatch: () => this.flushMigrationProgress(),
+                sql: this.sql as SqlExec,
+                writer,
+            });
+        }
+
+        protected override async runShardWrite(args: RunShardWriteArgs): Promise<RunShardWriteResult> {
+            const definition = (schema as unknown as SchemaLike).tables[args.table];
+
+            if (!definition) {
+                throw Object.assign(new Error(\`unknown table: \${args.table}\`), { name: "LunoraError", code: "UNKNOWN_TABLE", status: 404 });
+            }
+
+            // \`.global()\` tables live in D1, not this DO's SQLite — editing them
+            // here would corrupt nothing but would fail confusingly, so reject up
+            // front with a clear code the studio can surface.
+            if (definition.shardMode?.kind === "global") {
+                throw Object.assign(new Error(\`table "\${args.table}" is global; edit it through D1, not the shard\`), {
+                    name: "LunoraError",
+                    code: "GLOBAL_TABLE_NOT_EDITABLE",
+                    status: 400,
+                });
+            }
+
+            this.ensureMigrated();
+
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            const scheduler = (config.scheduler?.(env) ?? schedulerStub) as SchedulerLike;
+            const writer = createShardCtxDb({
+                broadcast: (delta) => {
+                    this.recordChangedTable(delta.table);
+                },
+                cdc: config.cdc ?? false,
+                scheduler,
+                schema: schema as unknown as SchemaLike,
+                sql: this.sql as SqlExec,
+            });
+
+            if (args.op === "insert") {
+                const id = await writer.insert(args.table, args.doc ?? {});
+
+                return { id, op: "insert" };
+            }
+
+            if (args.op === "delete") {
+                await writer.delete(args.id ?? "");
+
+                return { id: args.id ?? null, op: "delete" };
+            }
+
+            if (args.op === "replace") {
+                await writer.replace(args.id ?? "", args.doc ?? {});
+
+                return { id: args.id ?? null, op: "replace" };
+            }
+
+            await writer.patch(args.id ?? "", args.doc ?? {});
+
+            return { id: args.id ?? null, op: "patch" };
+        }
+
+        protected override async deleteRowThroughWriter(table: string, id: string): Promise<void> {
+            const definition = (schema as unknown as SchemaLike).tables[table];
+
+            if (!definition) {
+                throw Object.assign(new Error(\`unknown table: \${table}\`), { name: "LunoraError", code: "UNKNOWN_TABLE", status: 404 });
+            }
+
+            // \`.global()\` tables live in D1, not this DO's SQLite — the same
+            // guard \`runShardWrite\` applies to single-row edits.
+            if (definition.shardMode?.kind === "global") {
+                throw Object.assign(new Error(\`table "\${table}" is global; edit it through D1, not the shard\`), {
+                    name: "LunoraError",
+                    code: "GLOBAL_TABLE_NOT_EDITABLE",
+                    status: 400,
+                });
+            }
+
+            this.ensureMigrated();
+
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            const scheduler = (config.scheduler?.(env) ?? schedulerStub) as SchedulerLike;
+            const writer = createShardCtxDb({
+                broadcast: (delta) => {
+                    this.recordChangedTable(delta.table);
+                },
+                cdc: config.cdc ?? false,
+                scheduler,
+                schema: schema as unknown as SchemaLike,
+                sql: this.sql as SqlExec,
+            });
+
+            // Routes through the writer (not raw SQL) so FTS / aggregate / rank
+            // shadow tables stay in sync and \`onDelete\` cascades fire — the
+            // bounded loop lives in the base \`runShardBulkDelete\`.
+            await writer.delete(id);
+        }
+
+        protected override async runShardRankBefore(args: RunShardRankBeforeArgs): Promise<{ before: number; total: number }> {
+            this.ensureMigrated();
+
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            const scheduler = (config.scheduler?.(env) ?? schedulerStub) as SchedulerLike;
+            const writer = createShardCtxDb({
+                broadcast: (delta) => {
+                    this.recordChangedTable(delta.table);
+                },
+                cdc: config.cdc ?? false,
+                scheduler,
+                schema: schema as unknown as SchemaLike,
+                sql: this.sql as SqlExec,
+            });
+
+            // \`rankBefore\` is optional on \`DatabaseWriterLike\` (the D1 twin omits it),
+            // but the shard writer from \`createShardCtxDb\` always defines it.
+            if (!writer.rankBefore) {
+                throw Object.assign(new Error("rankBefore is unavailable on the shard writer"), { name: "LunoraError", code: "NOT_IMPLEMENTED", status: 500 });
+            }
+
+            return writer.rankBefore(args.table, args.index, {
+                partitionKey: args.partitionKey,
+                rowId: args.rowId,
+                sortValues: args.sortValues,
+            });
+        }
+
+        protected override async runShardRankPage(args: RunShardRankPageArgs): Promise<ShardRankPageResult> {
+            this.ensureMigrated();
+
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            const scheduler = (config.scheduler?.(env) ?? schedulerStub) as SchedulerLike;
+            const writer = createShardCtxDb({
+                broadcast: (delta) => {
+                    this.recordChangedTable(delta.table);
+                },
+                cdc: config.cdc ?? false,
+                scheduler,
+                schema: schema as unknown as SchemaLike,
+                sql: this.sql as SqlExec,
+            });
+
+            // \`rankPageRows\` is optional on \`DatabaseWriterLike\` (the D1 twin omits it),
+            // but the shard writer from \`createShardCtxDb\` always defines it. The sort
+            // directions live in the schema's rankIndex, so the shard reads them itself;
+            // \`args.directions\` is only the coordinator's comparator hint and isn't forwarded.
+            if (!writer.rankPageRows) {
+                throw Object.assign(new Error("rankPage is unavailable on the shard writer"), { name: "LunoraError", code: "NOT_IMPLEMENTED", status: 500 });
+            }
+
+            return writer.rankPageRows(args.table, args.index, {
+                after: args.after,
+                cursor: args.cursor,
+                partitionKey: args.partitionKey,
+                take: args.take,
+            });
+        }
+
+        protected override async runShardApplyCdc(args: RunShardApplyCdcArgs): Promise<{ applied: number }> {
+            this.ensureMigrated();
+
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            const scheduler = (config.scheduler?.(env) ?? schedulerStub) as SchedulerLike;
+            const writer = createShardCtxDb({
+                broadcast: (delta) => {
+                    this.recordChangedTable(delta.table);
+                },
+                cdc: config.cdc ?? false,
+                scheduler,
+                schema: schema as unknown as SchemaLike,
+                sql: this.sql as SqlExec,
+            });
+
+            await applyCdcChanges(writer, args.changes);
+
+            return { applied: args.changes.length };
+        }
+
+        protected override ensureMigrated(): void {
+            if (this.migrated) {
+                return;
+            }
+
+            runShardMigrations(this.sql as SqlExec, schema as unknown as SchemaLike, { cdc: config.cdc ?? false });
+            this.migrated = true;
+        }
+
+        private buildCtx(options: { functionPath?: string; identity?: { identity?: Record<string, unknown>; userId?: string }; onRead?: (table: string) => void } = {}): unknown {
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            // When the caller threads an explicit identity (subscription seed /
+            // refresh — both run in deferred/interleaved contexts), use it by
+            // value and NEVER read the shared per-request identity field, which a
+            // concurrent RPC may have re-set. Otherwise (the synchronous RPC
+            // dispatch path) fall back to the per-request fields as before.
+            const userId = options.identity ? options.identity.userId : this.getCurrentUserId();
+            const identity = options.identity ? options.identity.identity : this.getCurrentIdentity();
+${vectorsBuild}${aiBuild}${everyContextBuild}${containersBuild}${workflowsBuild}
+            const scheduler = (config.scheduler?.(env) ?? schedulerStub) as SchedulerLike;
+            // Build the storage adapter once and share it between \`ctx.storage\`
+            // and \`ctx.db.system._storage\` so both read the same R2 binding. The
+            // \`storageStub\` fallback satisfies SystemReaderStorageLike structurally
+            // (its \`list\`/\`getMetadata\` throw the "no storage configured" error).
+            const storage = asBucketStorage(config.storage?.(env) ?? storageStub) as unknown as SystemReaderStorageLike;
+${globalDatabaseLine}            const db: DatabaseWriterLike = createShardCtxDb(${databaseOptions});
+${facadeBlock}${paymentsBuild}
+            // \`ctx.log\`: each call is captured + attributed to the executing
+            // function and routed to the optional \`observability\` sink. The DO base
+            // also buffers it (studio Logs panel) and emits a structured console
+            // event the dev-server formats in the terminal.
+            const observability = config.observability?.(env);
+            const logFunctionPath = options.functionPath ?? "";
+            const log = {
+                debug: (...args: unknown[]) => { this.recordUserLog(logFunctionPath, "debug", args, observability); },
+                error: (...args: unknown[]) => { this.recordUserLog(logFunctionPath, "error", args, observability); },
+                info: (...args: unknown[]) => { this.recordUserLog(logFunctionPath, "info", args, observability); },
+                log: (...args: unknown[]) => { this.recordUserLog(logFunctionPath, "log", args, observability); },
+                warn: (...args: unknown[]) => { this.recordUserLog(logFunctionPath, "warn", args, observability); },
+            };
+
+            const ctx: Record<string, unknown> = {
+                auth: {
+                    getIdentity: async () => identity ?? null,
+                    userId: userId ?? null,
+                },
+                db,
+                fetch: globalThis.fetch.bind(globalThis),
+                ip: this.getCurrentIp(),
+                log,${ormContextField}
+                scheduler,
+                storage,${vectorsContextField}${aiContextField}${everyContextField}${paymentsContextField}${containersContextField}${workflowsContextField}
+            };
+${isActionLine}${actionOnlyBlock}
+            ctx.runAction = (reference: FunctionReference, fnArgs: Record<string, unknown>) => dispatchRun("action", reference.__lunoraRef, fnArgs, ctx);
+            ctx.runMutation = (reference: FunctionReference, fnArgs: Record<string, unknown>) => dispatchRun("mutation", reference.__lunoraRef, fnArgs, ctx);
+            ctx.runQuery = (reference: FunctionReference, fnArgs: Record<string, unknown>) => dispatchRun("query", reference.__lunoraRef, fnArgs, ctx);
+
+            return ctx;
+        }
+    };
+`;
+};
+const validatorToDrizzleColumn = (validator) => {
+  switch (validator.kind) {
+    case "array":
+    case "object":
+    case "record":
+    case "union": {
+      return {
+        builder: "text",
+        mode: "json",
+        notNull: true,
+        typeAnnotation: validatorToType(validator)
+      };
+    }
+    case "bigint": {
+      return { builder: "blob", mode: "bigint", notNull: true };
+    }
+    case "boolean": {
+      return { builder: "integer", mode: "boolean", notNull: true };
+    }
+    case "bytes": {
+      return { builder: "blob", mode: "buffer", notNull: true };
+    }
+    case "date":
+    case "timestamp": {
+      return { builder: "integer", notNull: true };
+    }
+    case "id": {
+      return { builder: "text", notNull: true };
+    }
+    case "literal": {
+      const value = validator.literalValue ?? "";
+      if (value.startsWith('"') || value.startsWith("'")) {
+        return { builder: "text", notNull: true };
+      }
+      if (value === "true" || value === "false") {
+        return { builder: "integer", mode: "boolean", notNull: true };
+      }
+      if (value === "null") {
+        return { builder: "text", notNull: true };
+      }
+      return { builder: "real", notNull: true };
+    }
+    case "null": {
+      return { builder: "text", notNull: true };
+    }
+    case "number": {
+      return { builder: "real", notNull: true };
+    }
+    case "optional": {
+      const inner = validator.inner ? validatorToDrizzleColumn(validator.inner) : { builder: "text", notNull: false };
+      return { ...inner, notNull: false };
+    }
+    case "storage":
+    case "string": {
+      return { builder: "text", notNull: true };
+    }
+    default: {
+      return { builder: "text", notNull: true };
+    }
+  }
+};
+const renderDrizzleColumn = (name, validator, knownTables) => {
+  assertIdentifier(name, "drizzle column name");
+  const column = validatorToDrizzleColumn(validator);
+  const isOptional = validator.kind === "optional";
+  const innerValidator = isOptional && validator.inner ? validator.inner : validator;
+  const modeArgument = column.mode ? `, { mode: "${column.mode}" }` : "";
+  let expression = `${column.builder}("${name}"${modeArgument})`;
+  if (column.typeAnnotation) {
+    expression += `.$type<${column.typeAnnotation}>()`;
+  }
+  if (innerValidator.kind === "id" && innerValidator.tableName && knownTables.has(innerValidator.tableName)) {
+    expression += `.references(() => ${innerValidator.tableName}._id)`;
+  }
+  if (column.notNull) {
+    expression += ".notNull()";
+  }
+  return expression;
+};
+const renderIndexEntry = (index) => {
+  assertIdentifier(index.name, "drizzle index name");
+  const constructor = index.unique ? "uniqueIndex" : "index";
+  const fields = index.fields.map((field) => {
+    assertIdentifier(field, "drizzle index field");
+    return `t.${field}`;
+  }).join(", ");
+  return `    ${index.name}: ${constructor}("${index.name}").on(${fields}),`;
+};
+const renderDrizzleTable = (table, knownTables) => {
+  assertIdentifier(table.name, "table name");
+  const columns = [
+    `    _id: text("_id").primaryKey(),`,
+    `    _creationTime: integer("_creationTime").notNull(),`,
+    ...Object.entries(table.shape).map(([fieldName, validator]) => `    ${fieldName}: ${renderDrizzleColumn(fieldName, validator, knownTables)},`)
+  ].join("\n");
+  const indexBody = table.indexes.length > 0 ? `, (t) => ({
+${table.indexes.map((index) => renderIndexEntry(index)).join("\n")}
+})` : "";
+  return `export const ${table.name} = sqliteTable("${table.name}", {
+${columns}
+}${indexBody});`;
+};
+const usedImports = (tables) => {
+  const columns = /* @__PURE__ */ new Set();
+  const indexes = /* @__PURE__ */ new Set();
+  columns.add("text");
+  columns.add("integer");
+  columns.add("sqliteTable");
+  for (const table of tables) {
+    for (const validator of Object.values(table.shape)) {
+      const column = validatorToDrizzleColumn(validator);
+      columns.add(column.builder);
+    }
+    for (const index of table.indexes) {
+      indexes.add(index.unique ? "uniqueIndex" : "index");
+    }
+  }
+  return { columns: [...columns].toSorted((a, b) => a.localeCompare(b)), indexes: [...indexes].toSorted((a, b) => a.localeCompare(b)) };
+};
+const renderDrizzleFile = (tables, useUmbrella = false) => {
+  if (tables.length === 0) {
+    return `${GENERATED_HEADER}export {};
+`;
+  }
+  const base = baseSpecifiers(useUmbrella);
+  const { columns, indexes } = usedImports(tables);
+  const importParts = [...indexes, ...columns].toSorted((a, b) => a.localeCompare(b));
+  const knownTables = new Set(tables.map((table) => table.name));
+  const tableBlocks = tables.map((table) => renderDrizzleTable(table, knownTables)).join("\n\n");
+  return `${GENERATED_HEADER}import { ${importParts.join(", ")} } from "${base.serverDrizzle}";
+
+${tableBlocks}
+`;
+};
+const emitDrizzleSchema = (schema, useUmbrella = false) => {
+  const globalTables = schema.tables.filter((table) => table.shardMode === "global");
+  const shardTables = schema.tables.filter((table) => table.shardMode !== "global");
+  return {
+    global: renderDrizzleFile(globalTables, useUmbrella),
+    shard: renderDrizzleFile(shardTables, useUmbrella)
+  };
+};
+const emitCrons = (crons) => {
+  const triggers = [];
+  const byExpression = /* @__PURE__ */ new Map();
+  for (const cron of crons) {
+    const existing = byExpression.get(cron.cron);
+    if (existing) {
+      existing.push(cron);
+    } else {
+      byExpression.set(cron.cron, [cron]);
+      triggers.push(cron.cron);
+    }
+  }
+  const triggerEntries = triggers.map((expression) => `    ${JSON.stringify(expression)},`).join("\n");
+  const triggerBody = triggerEntries.length > 0 ? `
+${triggerEntries}
+` : "";
+  const mapEntries = [...byExpression.entries()].map(([expression, jobs]) => {
+    const jobEntries = jobs.map((job) => {
+      const targetField = job.workflow ? `workflow: ${JSON.stringify(job.workflow.binding)}` : `functionPath: ${JSON.stringify(job.functionPath)}`;
+      return `        { name: ${JSON.stringify(job.name)}, ${targetField}, args: ${JSON.stringify(job.args)} },`;
+    }).join("\n");
+    return `    ${JSON.stringify(expression)}: [
+${jobEntries}
+    ],`;
+  }).join("\n");
+  const mapBody = mapEntries.length > 0 ? `
+${mapEntries}
+` : "";
+  return `${GENERATED_HEADER}/**
+ * One scheduled cron invocation. Exactly one target is set: \`functionPath\` is
+ * the \`namespace:fn\` dispatch ref (matches \`__lunoraRef\`), invoked on the
+ * shard; \`workflow\` is a \`WORKFLOW_*\` binding name whose durable workflow is
+ * started fresh per fire. \`args\` are forwarded verbatim (a workflow's become
+ * its \`params\`).
+ */
+export interface LunoraCronJob {
+    args: Record<string, unknown>;
+    functionPath?: string;
+    name: string;
+    workflow?: string;
+}
+
+/**
+ * Deduplicated cron schedules — mirror of wrangler's \`triggers.crons\`. The
+ * Lunora vite plugin keeps \`wrangler.jsonc\` in sync with this array.
+ */
+export const LUNORA_CRON_TRIGGERS: ReadonlyArray<string> = [${triggerBody}];
+
+/**
+ * Dispatcher map keyed by cron expression. The Worker's \`scheduled()\` handler
+ * looks up \`event.cron\` here and dispatches every job in the list.
+ */
+export const LUNORA_CRONS: Record<string, ReadonlyArray<LunoraCronJob>> = {${mapBody}};
+`;
+};
+const emitVectors = (vectorIndexes) => {
+  const entries = [...vectorIndexes].toSorted((a, b) => a.name.localeCompare(b.name)).map((index) => {
+    const parts = [`name: ${JSON.stringify(index.name)}`, `table: ${JSON.stringify(index.table)}`];
+    if (index.field !== void 0) {
+      parts.push(`field: ${JSON.stringify(index.field)}`);
+    }
+    if (index.dimensions !== void 0) {
+      parts.push(`dimensions: ${JSON.stringify(index.dimensions)}`);
+    }
+    if (index.metric !== void 0) {
+      parts.push(`metric: ${JSON.stringify(index.metric)}`);
+    }
+    if (index.metadata !== void 0) {
+      parts.push(`metadata: ${JSON.stringify(index.metadata)}`);
+    }
+    return `    { ${parts.join(", ")} },`;
+  }).join("\n");
+  const body = entries.length > 0 ? `
+${entries}
+` : "";
+  return `${GENERATED_HEADER}/**
+ * One vector index declared in \`schema.ts\` — an inline \`.vectorize()\` column
+ * or a standalone \`defineVectorIndex()\`. \`field\` is the source column (absent
+ * for a \`select\`-derived Shape B index); \`metadata\` lists the row fields
+ * mirrored into Vectorize for filtering.
+ */
+export interface LunoraVectorIndex {
+    dimensions?: number;
+    field?: string;
+    metadata?: ReadonlyArray<string>;
+    metric?: "cosine" | "dot-product" | "euclidean";
+    name: string;
+    table: string;
+}
+
+/**
+ * Static registry of every vector index in the schema, sorted by name.
+ * Vectorize cannot enumerate indexes at runtime, so the worker passes this to
+ * \`createWorker({ vectorIntrospector })\` to back the studio's vector browser.
+ */
+export const LUNORA_VECTOR_INDEXES: ReadonlyArray<LunoraVectorIndex> = [${body}];
+`;
+};
+const emitWranglerCronTriggers = (crons) => {
+  const seen = /* @__PURE__ */ new Set();
+  const triggers = [];
+  for (const cron of crons) {
+    if (!seen.has(cron.cron)) {
+      seen.add(cron.cron);
+      triggers.push(cron.cron);
+    }
+  }
+  return triggers;
+};
+
+export { GENERATED_HEADER, buildStorageColumns, emitApi, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitSeed, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers };