@lunora/codegen 1.0.0-alpha.3 → 1.0.0-alpha.30

package/dist/packem_shared/{GENERATED_HEADER-CuLyj0WQ.mjs → GENERATED_HEADER-f6nMvllu.mjs}

@@ -1,27 +1,200 @@
+import { LunoraError } from '@lunora/errors';
 import { s as sanitizeNamespace } from './paths-BRd6JHuF.mjs';
 
+const LITERAL_VALUE_RE = /^(?:"[^"\\]*"|'[^'\\]*'|-?\d+(?:\.\d+)?|true|false|null)$/u;
+
+const PASS_THROUGH_KINDS = /* @__PURE__ */ new Set(["any", "bigint", "boolean", "date", "id", "null", "number", "storage", "string", "timestamp"]);
+const hasColumnModifier = (node) => node.column !== void 0;
+const emitScalarGuard = (kind, inExpr) => {
+  switch (kind) {
+    case "bigint": {
+      return `if (typeof ${inExpr} !== "bigint") return DEFER;
+`;
+    }
+    case "boolean": {
+      return `if (typeof ${inExpr} !== "boolean") return DEFER;
+`;
+    }
+    case "date":
+    case "number":
+    case "timestamp": {
+      return `if (typeof ${inExpr} !== "number" || !Number.isFinite(${inExpr})) return DEFER;
+`;
+    }
+    case "null": {
+      return `if (${inExpr} !== null) return DEFER;
+`;
+    }
+    // string / id / storage all parse as a bare string at runtime.
+    default: {
+      return `if (typeof ${inExpr} !== "string") return DEFER;
+`;
+    }
+  }
+};
+const compileLiteral = (node, inExpr) => {
+  const literal = node.literalValue?.trim();
+  if (literal === void 0 || !LITERAL_VALUE_RE.test(literal)) {
+    return void 0;
+  }
+  return { out: inExpr, pre: `if (${inExpr} !== ${literal}) return DEFER;
+` };
+};
+const compileNode = (node, inExpr, context) => {
+  if (hasColumnModifier(node)) {
+    return void 0;
+  }
+  if (node.hasRefinement || node.sourceText !== void 0) {
+    return void 0;
+  }
+  if (PASS_THROUGH_KINDS.has(node.kind)) {
+    if (node.kind === "any") {
+      return { out: inExpr, pre: "" };
+    }
+    return { out: inExpr, pre: emitScalarGuard(node.kind, inExpr) };
+  }
+  switch (node.kind) {
+    case "array": {
+      return compileArray(node, inExpr, context);
+    }
+    case "literal": {
+      return compileLiteral(node, inExpr);
+    }
+    case "object": {
+      return compileObject(node, inExpr, context);
+    }
+    default: {
+      return void 0;
+    }
+  }
+};
+const compileArray = (node, inExpr, context) => {
+  const { inner } = node;
+  if (!inner) {
+    return void 0;
+  }
+  const id = context.next();
+  const array = `__arr${String(id)}`;
+  const index = `__i${String(id)}`;
+  const element = `__e${String(id)}`;
+  const innerEmit = compileNode(inner, element, context);
+  if (!innerEmit) {
+    return void 0;
+  }
+  const pre = `if (!Array.isArray(${inExpr})) return DEFER;
+const ${array} = new Array(${inExpr}.length);
+for (let ${index} = 0; ${index} < ${inExpr}.length; ${index}++) {
+const ${element} = ${inExpr}[${index}];
+${innerEmit.pre}${array}[${index}] = ${innerEmit.out};
+}
+`;
+  return { out: array, pre };
+};
+const compileField = (key, node, access, context) => {
+  const keyLiteral = JSON.stringify(key);
+  if (node.kind === "optional") {
+    if (node.hasRefinement || node.sourceText !== void 0 || hasColumnModifier(node)) {
+      return void 0;
+    }
+    const { inner } = node;
+    if (!inner) {
+      return void 0;
+    }
+    const innerEmit = compileNode(inner, access, context);
+    if (!innerEmit) {
+      return void 0;
+    }
+    const id = context.next();
+    const has = `__has${String(id)}`;
+    const value = `__val${String(id)}`;
+    const pre = `let ${has} = false;
+let ${value};
+if (${access} !== undefined) {
+${innerEmit.pre}${value} = ${innerEmit.out};
+${has} = true;
+}
+`;
+    return { entry: `...(${has} ? { ${keyLiteral}: ${value} } : {})`, pre };
+  }
+  const emit = compileNode(node, access, context);
+  if (!emit) {
+    return void 0;
+  }
+  return { entry: `${keyLiteral}: ${emit.out}`, pre: emit.pre };
+};
+const compileFields = (shape, accessFor, context) => {
+  let pre = "";
+  const entries = [];
+  for (const key of Object.keys(shape)) {
+    const node = shape[key];
+    if (!node) {
+      return void 0;
+    }
+    const field = compileField(key, node, accessFor(key), context);
+    if (!field) {
+      return void 0;
+    }
+    pre += field.pre;
+    entries.push(field.entry);
+  }
+  return { entries: entries.join(", "), pre };
+};
+const compileObject = (node, inExpr, context) => {
+  const shape = node.shape ?? {};
+  const fields = compileFields(shape, (key) => `${inExpr}[${JSON.stringify(key)}]`, context);
+  if (!fields) {
+    return void 0;
+  }
+  const id = context.next();
+  const object = `__obj${String(id)}`;
+  const pre = `if (typeof ${inExpr} !== "object" || ${inExpr} === null || Array.isArray(${inExpr})) return DEFER;
+${fields.pre}const ${object} = { ${fields.entries} };
+`;
+  return { out: object, pre };
+};
+const compileArgsValidator = (args) => {
+  let counter = 0;
+  const context = {
+    next: () => {
+      counter += 1;
+      return counter;
+    }
+  };
+  const fields = compileFields(args, (key) => `source[${JSON.stringify(key)}]`, context);
+  if (!fields) {
+    return void 0;
+  }
+  return `(source) => {
+if (typeof source !== "object" || source === null || Array.isArray(source)) return DEFER;
+${fields.pre}return { ${fields.entries} };
+}`;
+};
+
 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",
+  flags: "lunorash/flags",
   server: "lunorash/server",
   serverDataModel: "lunorash/server/data-model",
   serverDrizzle: "lunorash/server/drizzle",
-  serverTypes: "lunorash/server/types"
+  serverTypes: "lunorash/server/types",
+  values: "lunorash/values"
 } : {
   client: "@lunora/client",
   do: "@lunora/do",
+  flags: "@lunora/flags",
   server: "@lunora/server",
   serverDataModel: "@lunora/server/data-model",
   serverDrizzle: "@lunora/server/drizzle",
-  serverTypes: "@lunora/server/types"
+  serverTypes: "@lunora/server/types",
+  values: "@lunora/values"
 };
 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)}`);
+    throw new LunoraError("INTERNAL", `@lunora/codegen: ${context} is not a valid JS identifier: ${JSON.stringify(value)}`);
   }
 };
 const renderPropertyKey = (fieldName) => IDENTIFIER_RE.test(fieldName) ? fieldName : JSON.stringify(fieldName);
@@ -48,7 +221,10 @@ const literalToType = (value) => {
     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)}`);
+    throw new LunoraError(
+      "INTERNAL",
+      `@lunora/codegen: v.literal() argument is not a parseable string/number/boolean/null literal: ${JSON.stringify(value)}`
+    );
   }
   return value;
 };
@@ -430,6 +606,26 @@ import type { InsertModel } from "./dataModel.js";
 export const createSeedClient = (options?: SeedClientOptions): SeedClient<InsertModel> => createSeedClientBase<InsertModel>(schema, options);
 `;
 };
+const emitCollections = (shapes, hasDatabase, useUmbrella = false) => {
+  if (shapes.length === 0 || !hasDatabase) {
+    return "";
+  }
+  const base = baseSpecifiers(useUmbrella);
+  const factories = shapes.map((shape) => {
+    assertIdentifier(shape.exportName, "shape export name");
+    return `/** Live collection for the \`${shape.exportName}\` replication shape — pass the shape's validated \`args\` (its partition selector). */
+export const ${shape.exportName}Collection = (client: LunoraClient, args?: Record<string, unknown>): Collection<Row, string> =>
+    createCollection(lunoraCollectionOptions({ client, shape: { args, name: "${shape.exportName}" } }).config);`;
+  }).join("\n\n");
+  return `${GENERATED_HEADER}import type { LunoraClient } from "${base.client}";
+import { lunoraCollectionOptions } from "@lunora/db/collections";
+import type { Row } from "@lunora/db";
+import type { Collection } from "@tanstack/db";
+import { createCollection } from "@tanstack/db";
+
+${factories}
+`;
+};
 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];
@@ -444,7 +640,7 @@ const CALL_REGISTERED_HELPER = `const callRegistered = async <R>(context: Caller
 
     return (await registered.handler(context, args ?? {})) as R;
 };`;
-const renderFunctionRegistry = (functions, migrations) => {
+const renderFunctionRegistry = (functions, migrations, mutators = [], shapes = []) => {
   const aliasByPath = /* @__PURE__ */ new Map();
   const registerPath = (filePath) => {
     if (!aliasByPath.has(filePath)) {
@@ -457,9 +653,15 @@ const renderFunctionRegistry = (functions, migrations) => {
   for (const migration of migrations) {
     registerPath(migration.filePath);
   }
+  for (const mutator of mutators) {
+    registerPath(mutator.filePath);
+  }
+  for (const shape of shapes) {
+    registerPath(shape.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)}`);
+      throw new LunoraError("INTERNAL", `@lunora/codegen: refusing to emit import for unsafe file path: ${JSON.stringify(filePath)}`);
     }
     return `import * as ${alias} from "../${filePath}.js";`;
   }).join("\n");
@@ -469,15 +671,37 @@ const renderFunctionRegistry = (functions, migrations) => {
   const migrationEntries = migrations.map(
     (migration) => `    ${JSON.stringify(migration.id)}: ${aliasByPath.get(migration.filePath) ?? ""}.${migration.exportName} as unknown as RegisteredDataMigration,`
   ).join("\n");
+  const mutatorEntries = mutators.map(
+    (mutator) => `    "${sanitizeNamespace(mutator.filePath)}:${mutator.exportName}": ${aliasByPath.get(mutator.filePath) ?? ""}.${mutator.exportName} as unknown as RegisteredLunoraFunction,`
+  ).join("\n");
+  const shapeEntries = shapes.map((shape) => `    "${shape.exportName}": ${aliasByPath.get(shape.filePath) ?? ""}.${shape.exportName} as unknown as RegisteredShape,`).join("\n");
+  const mutatorPaths = mutators.map((mutator) => `${sanitizeNamespace(mutator.filePath)}:${mutator.exportName}`);
+  const combinedDispatch = [dispatchEntries, mutatorEntries].filter((entries) => entries.length > 0).join("\n");
+  const installLines = functions.map((definition) => {
+    if (definition.lifecycle || Object.keys(definition.args).length === 0) {
+      return void 0;
+    }
+    const compiled = compileArgsValidator(definition.args);
+    if (compiled === void 0) {
+      return void 0;
+    }
+    const alias = aliasByPath.get(definition.filePath) ?? "";
+    return `installCompiledValidatorMap(${alias}.${definition.exportName}.args, ${compiled});`;
+  }).filter((line) => line !== void 0).join("\n");
   return {
-    dispatchBody: dispatchEntries.length > 0 ? `
-${dispatchEntries}
+    dispatchBody: combinedDispatch.length > 0 ? `
+${combinedDispatch}
 ` : "",
     importBlock: importLines.length > 0 ? `${importLines}
 
 ` : "",
+    installBlock: installLines,
     migrationBody: migrationEntries.length > 0 ? `
 ${migrationEntries}
+` : "",
+    mutatorPaths,
+    shapeBody: shapeEntries.length > 0 ? `
+${shapeEntries}
 ` : ""
   };
 };
@@ -531,15 +755,19 @@ const buildStorageBucketNames = (schema, ruleBuckets = []) => {
 };
 const emitServer = ({
   containers = [],
+  hasAccessFacade = false,
   hasAi = false,
   hasAnalytics = false,
   hasBrowser = false,
+  hasFlags = false,
   hasHyperdrive = false,
   hasImages = false,
   hasKv = false,
   hasPayments = false,
   hasPipelines = false,
   hasR2sql = false,
+  identity,
+  queues = [],
   schema,
   storageRuleBuckets = [],
   useUmbrella = false,
@@ -573,6 +801,11 @@ const emitServer = ({
       assertIdentifier(workflow.bindingName, `workflow binding "${workflow.bindingName}"`);
       return `    /** Workflow binding for the \`${workflow.exportName}\` workflow. */
     readonly ${workflow.bindingName}?: unknown;`;
+    }),
+    ...queues.map((queue) => {
+      assertIdentifier(queue.bindingName, `queue binding "${queue.bindingName}"`);
+      return `    /** Queue producer binding for the \`${queue.exportName}\` queue. */
+    readonly ${queue.bindingName}?: unknown;`;
     })
   ].join("\n");
   const envBlock = `
@@ -595,7 +828,13 @@ ${envBindingFields}` : ""}
 /** Alias for {@link CloudflareBindings} — the typed shape of \`env\`. */
 export type Env = CloudflareBindings;`;
   const kvContextField = hasKv ? `
-    readonly kv: import("@lunora/kv").Kv;` : "";
+    readonly kv: import("@lunora/bindings/kv").Kv;` : "";
+  const accessContextField = hasAccessFacade ? `
+    /** Verified Cloudflare Access identity — a synchronous facade over the resolved claims (email / groups / hasGroup / claims). Anonymous when no Access token is present. */
+    readonly access: import("@lunora/cloudflare-access/context").AccessFacade;` : "";
+  const flagsContextField = hasFlags ? `
+    /** Feature-flag evaluation (OpenFeature). Reads are memoized per request; evaluations never throw — a provider error resolves to the supplied default. */
+    readonly flags: import("${base.flags}").LunoraFlags;` : "";
   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.
@@ -606,18 +845,18 @@ export type Env = CloudflareBindings;`;
     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;` : "";
+    readonly images: import("@lunora/bindings/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;` : "";
+    readonly analytics: import("@lunora/bindings/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;` : "";
+    readonly pipelines: import("@lunora/bindings/pipelines").PipelineClient;` : "";
   const r2sqlActionField = hasR2sql ? `
     /**
      * R2 SQL over Apache Iceberg tables (window functions, DISTINCT, set operations). Non-deterministic — available only in actions. Reads here are NOT tracked by Lunora live queries.
      */
-    readonly r2sql: import("@lunora/r2sql").R2SqlClient;` : "";
+    readonly r2sql: import("@lunora/bindings/r2sql").R2SqlClient;` : "";
   const hasWorkflows = workflows.length > 0;
   const workflowsTypeImport = hasWorkflows ? `import type { WorkflowHandle } from "@lunora/workflow";
 import type * as lunoraWorkflowDefinitions from "../workflows.js";
@@ -638,6 +877,35 @@ ${workflows.map((workflow) => `    get(name: ${JSON.stringify(workflow.exportNam
   const workflowsOmit = hasWorkflows ? ` | "workflows"` : "";
   const workflowsContextField = hasWorkflows ? `
     readonly workflows: LunoraWorkflows;` : "";
+  const hasQueues = queues.length > 0;
+  const queuesTypeImport = hasQueues ? `import type { QueueProducer } from "@lunora/queue";
+import type * as lunoraQueueDefinitions from "../queues.js";
+` : "";
+  const queuesTypeBlock = hasQueues ? `
+
+/** Message body type carried by a \`defineQueue\` definition (its phantom \`__lunoraBody\`). */
+type QueueBodyOf<Definition> = Definition extends { __lunoraBody?: infer Body } ? (unknown extends Body ? unknown : NonNullable<Body>) : unknown;
+
+/** This project's declared queues, addressable from \`ctx.queues\` by their \`lunora/queues.ts\` export name. */
+export interface LunoraQueues {
+${queues.map((queue) => `    readonly ${queue.exportName}: QueueProducer<QueueBodyOf<typeof lunoraQueueDefinitions.${queue.exportName}>>;`).join("\n")}
+}` : "";
+  const queuesContextField = hasQueues ? `
+    readonly queues: LunoraQueues;` : "";
+  const identityTypeImport = identity ? `import type { InferIdentity } from "${base.server}";
+import type * as lunoraIdentityContract from "../identity.js";
+` : "";
+  const identityTypeBlock = identity ? `
+
+/** This app's declared identity claim contract (\`defineIdentity\` in \`lunora/identity.ts\`) — the typed shape of \`ctx.auth.getIdentity()\`, the RLS policy \`ctx.auth.identity\`, and the \`authorizeShard\`/\`authorizeFanOut\` identity argument. */
+export type Identity = InferIdentity<typeof lunoraIdentityContract.${identity.exportName}>;
+
+/** \`ctx.auth\` narrowed so \`getIdentity()\` resolves the declared {@link Identity} contract instead of the untyped claim bag. */
+type NarrowedAuth = Omit<QueryCtxBase["auth"], "getIdentity"> & { getIdentity: () => Promise<Identity | null> };` : "";
+  const authOmit = identity ? ` | "auth"` : "";
+  const authContextField = identity ? `
+    readonly auth: NarrowedAuth;` : "";
+  const policyIdentityArgument = identity ? ", Identity" : "";
   const server = `${GENERATED_HEADER}import { createPolicyDsl, initLunora, v as vBase } from "${base.server}";
 import type {
     ActionBuilder,
@@ -659,11 +927,11 @@ import type {
 } from "${base.server}";
 
 import type { DataModel, DatabaseReaderFacade, DatabaseWriterFacade, Doc, Id as IdOfTable, OrmReader, OrmWriter, Relations, TableName } from "./dataModel.js";
-${aiTypeImport}${paymentsTypeImport}${containersTypeImport}${workflowsTypeImport}
+${aiTypeImport}${paymentsTypeImport}${containersTypeImport}${workflowsTypeImport}${queuesTypeImport}${identityTypeImport}
 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}
+export type StorageBucketName = ${storageBucketUnion};${envBlock}${workflowsTypeBlock}${queuesTypeBlock}${identityTypeBlock}
 
 /**
  * Project-typed contexts. The base contexts from \`@lunora/server\` are
@@ -692,22 +960,22 @@ type TypedTableQuery = (<T extends TableName>(table: T) => TableReader<Doc<T>>)
  */
 type TypedTableGet = <T extends TableName>(id: IdOfTable<T>) => Promise<Doc<T> | null>;
 
-export interface QueryCtx extends Omit<QueryCtxBase, "db" | "storage"> {
+export interface QueryCtx extends Omit<QueryCtxBase, "db" | "storage"${authOmit}> {
     readonly db: Omit<DatabaseReader, "query" | "get"> & DatabaseReaderFacade & { query: TypedTableQuery; get: TypedTableGet };
     readonly orm: OrmReader;
-    readonly storage: ReadOnlyStorage<StorageBucketName>;${kvContextField}${analyticsContextField}
+    readonly storage: ReadOnlyStorage<StorageBucketName>;${accessContextField}${kvContextField}${flagsContextField}${analyticsContextField}${authContextField}
 }
 
-export interface MutationCtx extends Omit<MutationCtxBase, "db" | "storage"${workflowsOmit}> {
+export interface MutationCtx extends Omit<MutationCtxBase, "db" | "storage"${workflowsOmit}${authOmit}> {
     readonly db: Omit<DatabaseWriter, "query" | "get"> & DatabaseWriterFacade & { query: TypedTableQuery; get: TypedTableGet };
     readonly orm: OrmWriter;
-    readonly storage: ReadOnlyStorage<StorageBucketName>;${kvContextField}${analyticsContextField}${workflowsContextField}
+    readonly storage: ReadOnlyStorage<StorageBucketName>;${accessContextField}${kvContextField}${flagsContextField}${analyticsContextField}${workflowsContextField}${queuesContextField}${authContextField}
 }
 
-export interface ActionCtx extends Omit<ActionCtxBase, "db" | "storage"${workflowsOmit}> {
+export interface ActionCtx extends Omit<ActionCtxBase, "db" | "storage"${workflowsOmit}${authOmit}> {
     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}${r2sqlActionField}${workflowsContextField}
+    readonly storage: StorageBase<StorageBucketName>;${accessContextField}${aiActionField}${paymentsActionField}${containersActionField}${kvContextField}${flagsContextField}${hyperdriveActionField}${browserActionField}${imagesActionField}${analyticsContextField}${pipelinesActionField}${r2sqlActionField}${workflowsContextField}${queuesContextField}${authContextField}
 }
 
 /**
@@ -747,7 +1015,7 @@ export const internalAction = lunoraBuilders.internalAction as unknown as Intern
  * 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>();
+export const definePolicy = createPolicyDsl<DataModel, Relations${policyIdentityArgument}>();
 
 /**
  * The validator builder \`v\`, with \`v.id(...)\` constrained to THIS schema's
@@ -777,10 +1045,40 @@ const renderLifecycleManifest = (functions) => {
   }
   return manifest;
 };
-const emitFunctions = (functions, migrations = []) => {
+const emitFunctions = (functions, migrations = [], useUmbrella = false, mutators = [], shapes = []) => {
   const hasFunctions = functions.length > 0;
-  const { dispatchBody, importBlock, migrationBody } = renderFunctionRegistry(functions, migrations);
+  const base = baseSpecifiers(useUmbrella);
+  const { dispatchBody, importBlock, installBlock, migrationBody, mutatorPaths, shapeBody } = renderFunctionRegistry(functions, migrations, mutators, shapes);
   const lifecycleHooks = renderLifecycleManifest(functions);
+  const shapeTypeImport = shapes.length > 0 ? `import type { RegisteredShape } from "${base.server}";
+` : "";
+  const shapeRegistry = shapes.length > 0 ? `
+/**
+ * Replication-shape registry — one entry per \`defineShape\` in \`lunora/shapes.ts\`.
+ * The generated ShardDO's \`resolveShape\` override looks a shape up by name and
+ * evaluates its trusted \`compileWhere(ctx, args)\` to authorize + scope a
+ * \`shape_subscribe\` (reads-as-permissions).
+ */
+export const LUNORA_SHAPES: Record<string, RegisteredShape> = {${shapeBody}};
+` : "";
+  const mutatorPathsRegistry = mutatorPaths.length > 0 ? `
+/**
+ * Custom-mutator function paths — the \`LUNORA_FUNCTIONS\` keys the generated
+ * ShardDO's \`isCustomMutator\` override routes through the client-watermark push
+ * protocol (\`x-lunora-client-id\`/\`x-lunora-client-seq\` ordering).
+ */
+export const LUNORA_MUTATOR_PATHS: ReadonlySet<string> = new Set([${mutatorPaths.map((path) => JSON.stringify(path)).join(", ")}]);
+` : "";
+  const compiledArgsImport = installBlock.length > 0 ? `import { DEFER_VALIDATION as DEFER, installCompiledValidatorMap } from "${base.values}";
+` : "";
+  const compiledArgsInstall = installBlock.length > 0 ? `
+/**
+ * AOT-compiled argument validators (Worker-safe, no \`eval\`). Each is installed
+ * onto its function's live \`.args\` object and consulted by the interpreted
+ * parser as a zero-allocation fast path; anything it can't model is deferred.
+ */
+${installBlock}
+` : "";
   const caller = renderCaller(functions);
   const callerTypes = caller.types ? `
 ${caller.types}
@@ -795,7 +1093,7 @@ ${caller.implementation}
   const callRegisteredHelper = hasFunctions ? `${CALL_REGISTERED_HELPER}
 
 ` : "";
-  return `${GENERATED_HEADER}${importBlock}import type { ActionCtx, MutationCtx, QueryCtx } from "./server.js";
+  return `${GENERATED_HEADER}${importBlock}${compiledArgsImport}${shapeTypeImport}import type { ActionCtx, MutationCtx, QueryCtx } from "./server.js";
 ${dataModelImport}
 /**
  * Single registered function, narrowed to the shape \`handleRpc\` needs.
@@ -821,7 +1119,7 @@ export interface RegisteredLunoraFunction {
  * emits (\`api[namespace][fn].__lunoraRef === "namespace:fn"\`).
  */
 export const LUNORA_FUNCTIONS: Record<string, RegisteredLunoraFunction> = {${dispatchBody}};
-
+${compiledArgsInstall}${shapeRegistry}${mutatorPathsRegistry}
 /**
  * Connection-lifecycle manifest: the function paths the generated ShardDO
  * dispatches when a client's WebSocket connects (\`connect\`) or disconnects
@@ -1042,7 +1340,7 @@ const emitKvFragments = (hasKv) => {
     kv?: (env: Record<string, unknown>) => KVNamespaceLike;`,
     contextField: `
                 kv,`,
-    importLines: [`import type { Kv, KVNamespaceLike } from "@lunora/kv";`, `import { createKv } from "@lunora/kv";`],
+    importLines: [`import type { Kv, KVNamespaceLike } from "@lunora/bindings/kv";`, `import { createKv } from "@lunora/bindings/kv";`],
     stub: `
 const kvStub: Kv = {
     delete: async () => {
@@ -1067,6 +1365,116 @@ const kvStub: Kv = {
 `
   };
 };
+const emitFlagsFragments = (hasFlags, flagsSpecifier) => {
+  if (!hasFlags) {
+    return EMPTY_HELPER_FRAGMENTS;
+  }
+  return {
+    build: `
+            const flags: import("${flagsSpecifier}").LunoraFlags = createFlags({
+                hooks: flagsConfig.hooks,
+                logger: flagsConfig.logger,
+                provider: () => config.flags?.(env) ?? flagsConfig.provider(env),
+                targetingKey: () => flagsConfig.identify?.({ identity: identity ?? null, userId: userId ?? null }),
+            });
+`,
+    configField: `
+    flags?: (env: Record<string, unknown>) => import("${flagsSpecifier}").Provider;`,
+    contextField: `
+                flags,`,
+    importLines: [`import { createFlags } from "${flagsSpecifier}";`, `import flagsConfig from "../flags.js";`],
+    stub: ""
+  };
+};
+const emitAccessFragments = (hasAccessFacade) => {
+  if (!hasAccessFacade) {
+    return EMPTY_HELPER_FRAGMENTS;
+  }
+  return {
+    build: `
+            const access = accessFacade(identity, userId);
+`,
+    configField: "",
+    contextField: `
+                access,`,
+    importLines: [`import { accessFacade } from "@lunora/cloudflare-access/context";`],
+    stub: ""
+  };
+};
+const emitFlagsOverrides = (flagKeys, hasFlags, flagsSpecifier) => {
+  if (!hasFlags) {
+    return { constant: "", evaluateOverride: "", subscriptionOverride: "" };
+  }
+  const clientBuild = (targetingKey) => `
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            const flags: import("${flagsSpecifier}").LunoraFlags = createFlags({
+                hooks: flagsConfig.hooks,
+                logger: flagsConfig.logger,
+                provider: () => config.flags?.(env) ?? flagsConfig.provider(env),
+                targetingKey: ${targetingKey},
+            });`;
+  const constant = `
+/** Statically-discovered feature flags (\`ctx.flags.<type>("key")\` reads) served via \`__lunora_admin__:listFlags\` + the reactive \`__lunora_flags__:\` channel. */
+const LUNORA_FLAG_KEYS: ReadonlyArray<{ key: string; type: "boolean" | "number" | "object" | "string" }> = ${JSON.stringify(flagKeys, void 0, 4)};
+`;
+  const evaluateOverride = `
+        protected override async evaluateFlags(context?: Record<string, unknown>): Promise<FlagsResult> {${clientBuild("undefined")}
+            const evalContext = context as import("${flagsSpecifier}").EvaluationContext | undefined;
+            const evaluations: FlagsResult["flags"] = [];
+
+            for (const entry of LUNORA_FLAG_KEYS) {
+                // eslint-disable-next-line no-await-in-loop -- flags evaluate sequentially; each shares the single memoized provider client
+                const details =
+                    entry.type === "boolean"
+                        ? await flags.details.boolean(entry.key, false, evalContext)
+                        : entry.type === "number"
+                          ? await flags.details.number(entry.key, 0, evalContext)
+                          : entry.type === "string"
+                            ? await flags.details.string(entry.key, "", evalContext)
+                            : await flags.details.object(entry.key, {}, evalContext);
+
+                evaluations.push({ errorCode: details.errorCode, key: entry.key, reason: details.reason, type: entry.type, value: details.value, variant: details.variant });
+            }
+
+            return { configured: true, flags: evaluations };
+        }
+`;
+  const subscriptionOverride = `
+        protected override runFlagSubscriptionRead(_functionPath: string, args: Record<string, unknown>, identity?: { identity?: Record<string, unknown>; userId?: string }): Promise<unknown> {${clientBuild("() => flagsConfig.identify?.({ identity: identity?.identity ?? null, userId: identity?.userId ?? null })")}
+            const key = typeof args.key === "string" ? args.key : "";
+
+            // SECURITY: the reactive channel is public (any socket, no auth). Serve
+            // ONLY statically-discovered flag keys — an arbitrary client-supplied key
+            // would let a subscriber probe the value of internal/unreleased flags the
+            // app never exposes. Unknown key ⇒ the "nothing to deliver" sentinel.
+            // eslint-disable-next-line unicorn/no-null -- the base hook's "nothing to deliver" sentinel
+            if (key.length === 0 || !LUNORA_FLAG_KEYS.some((entry) => entry.key === key)) {
+                return Promise.resolve(null);
+            }
+
+            // SECURITY: evaluate under the socket's server-verified identity ONLY
+            // (the targetingKey resolved above). Client-supplied targeting context is
+            // NOT honored on this public channel — otherwise a subscriber could spoof
+            // targeting attributes (e.g. plan/role) to unlock a flag gated on them.
+            const context = undefined;
+
+            if (args.type === "number") {
+                return flags.number(key, typeof args.default === "number" ? args.default : 0, context);
+            }
+
+            if (args.type === "string") {
+                return flags.string(key, typeof args.default === "string" ? args.default : "", context);
+            }
+
+            if (args.type === "object") {
+                return flags.object(key, (args.default ?? {}) as import("${flagsSpecifier}").JsonValue, context);
+            }
+
+            return flags.boolean(key, typeof args.default === "boolean" ? args.default : false, context);
+        }
+`;
+  return { constant, evaluateOverride, subscriptionOverride };
+};
 const emitAnalyticsFragments = (hasAnalytics) => {
   if (!hasAnalytics) {
     return EMPTY_HELPER_FRAGMENTS;
@@ -1082,8 +1490,8 @@ const emitAnalyticsFragments = (hasAnalytics) => {
     contextField: `
                 analytics,`,
     importLines: [
-      `import type { AnalyticsClient, AnalyticsEngineDatasetLike } from "@lunora/analytics";`,
-      `import { createAnalytics } from "@lunora/analytics";`
+      `import type { AnalyticsClient, AnalyticsEngineDatasetLike } from "@lunora/bindings/analytics";`,
+      `import { createAnalytics } from "@lunora/bindings/analytics";`
     ],
     stub: `
 const analyticsStub: AnalyticsClient = {
@@ -1112,7 +1520,7 @@ const emitImagesFragments = (hasImages) => {
     // 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";`],
+    importLines: [`import type { Images, ImagesBindingLike } from "@lunora/bindings/images";`, `import { createImages } from "@lunora/bindings/images";`],
     stub: `
 const imagesStub: Images = {
     info: async () => {
@@ -1211,10 +1619,10 @@ const emitR2sqlFragments = (hasR2sql) => {
     // ActionCtx-only: attached via the \`ctx.r2sql = r2sql\` assignment in the
     // \`isAction\` block, never the every-ctx object literal.
     contextField: "",
-    importLines: [`import type { R2SqlClient } from "@lunora/r2sql";`, `import { createR2Sql } from "@lunora/r2sql";`],
+    importLines: [`import type { R2SqlClient } from "@lunora/bindings/r2sql";`, `import { createR2Sql } from "@lunora/bindings/r2sql";`],
     // The stub is typed `R2SqlClient`, so TS flags a missing method at build
     // time — but it must stay structurally in sync with that interface
-    // (`@lunora/r2sql` client.ts) when a method is added there.
+    // (`@lunora/bindings/r2sql` client.ts) when a method is added there.
     stub: `
 const r2sqlStub: R2SqlClient = {
     describe: async () => {
@@ -1239,17 +1647,46 @@ const r2sqlStub: R2SqlClient = {
 `
   };
 };
-const emitContainers = (containers) => {
+const emitPipelinesFragments = (hasPipelines) => {
+  if (!hasPipelines) {
+    return EMPTY_HELPER_FRAGMENTS;
+  }
+  const pipelinesMissing = `throw new Error("ctx.pipelines: no Pipelines binding found. Add a \\\`pipelines\\\` binding (env.PIPELINES) to wrangler.jsonc, or pass \\\`pipelines\\\` to createShardDO().");`;
+  return {
+    build: `
+            const pipelinesBinding = config.pipelines?.(env) ?? (env as Record<string, unknown>).PIPELINES;
+            const pipelines: PipelineClient = pipelinesBinding ? createPipelines({ binding: pipelinesBinding as PipelineBindingLike }) : pipelinesStub;
+`,
+    configField: `
+    pipelines?: (env: Record<string, unknown>) => PipelineBindingLike;`,
+    // ActionCtx-only: attached via the \`ctx.pipelines = pipelines\` assignment
+    // in the \`isAction\` block, never the every-ctx object literal.
+    contextField: "",
+    importLines: [
+      `import type { PipelineBindingLike, PipelineClient } from "@lunora/bindings/pipelines";`,
+      `import { createPipelines } from "@lunora/bindings/pipelines";`
+    ],
+    stub: `
+const pipelinesStub: PipelineClient = {
+    send: async () => {
+        ${pipelinesMissing}
+    },
+};
+`
+  };
+};
+const emitContainers = (containers, jurisdiction) => {
   if (containers.length === 0) {
     return "";
   }
+  const jurisdictionArgument = jurisdiction ? `, ${JSON.stringify(jurisdiction)}` : "";
   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}");
+        super(ctx, env, ${container.exportName}, "${container.exportName}"${jurisdictionArgument});
     }
 }
 `;
@@ -1261,14 +1698,21 @@ export class ${container.className} extends LunoraContainer {
  * requires each \`containers[].class_name\` to be exported by the worker:
  *
  * \`export * from "./lunora/_generated/containers.js";\`
+ *
+ * \`ContainerProxy\` is re-exported alongside them: the egress-interception path
+ * (\`allowedHosts\`/\`deniedHosts\`/\`interceptHttps\` and the runtime
+ * \`handle.egress\` controls) routes container outbound traffic through this
+ * WorkerEntrypoint, so it too must be exported by the deployed worker.
  */
-import LunoraContainer from "@lunora/container/do";
+import { LunoraContainer } from "@lunora/container/do";
 
 import { ${imports} } from "../containers.js";
 
+export { ContainerProxy } from "@lunora/container/do";
+
 ${classes}`;
 };
-const emitContainerFragments = (containers) => {
+const emitContainerFragments = (containers, jurisdiction) => {
   if (containers.length === 0) {
     return { build: "", contextField: "", importLines: [], specs: "" };
   }
@@ -1281,8 +1725,11 @@ const emitContainerFragments = (containers) => {
     return `    { binding: "${container.bindingName}", exportName: "${container.exportName}"${maxInstances} },`;
   }).join("\n");
   return {
+    // Schema `.jurisdiction("…")` pins every container DO this shard reaches
+    // to the data-residency region; the arg is omitted when undeclared so
+    // existing generated output is unchanged.
     build: `
-            const containers = createContainerContext(env, LUNORA_CONTAINERS);
+            const containers = createContainerContext(env, LUNORA_CONTAINERS${jurisdiction ? `, ${JSON.stringify(jurisdiction)}` : ""});
 `,
     contextField: `
                 containers,`,
@@ -1335,6 +1782,32 @@ type WorkflowOutputOf<Definition> = Definition extends { __output?: infer Output
 
 ${classes}`;
 };
+const emitQueues = (queues) => {
+  const pushQueues = queues.filter((queue) => queue.mode === "push");
+  if (pushQueues.length === 0) {
+    return "";
+  }
+  for (const queue of pushQueues) {
+    assertIdentifier(queue.exportName, `queue export "${queue.exportName}"`);
+  }
+  const imports = pushQueues.map((queue) => queue.exportName).join(", ");
+  const entries = pushQueues.map((queue) => `    ${JSON.stringify(queue.name)}: { definition: ${queue.exportName}, exportName: ${JSON.stringify(queue.exportName)} },`).join("\n");
+  return `${GENERATED_HEADER}/**
+ * Push-consumer registry for the queues declared in \`lunora/queues.ts\`. The
+ * composed worker's \`queue(batch, env, ctx)\` entry routes each delivered batch
+ * by \`batch.queue\` to the matching \`defineQueue\` handler. Wired automatically
+ * by \`defineApp\` — you don't import this directly.
+ */
+import type { QueueRegistry } from "@lunora/queue";
+
+import { ${imports} } from "../queues.js";
+
+/** Stable wrangler queue name → { definition, exportName } for batch routing. */
+export const LUNORA_QUEUE_REGISTRY: QueueRegistry = {
+${entries}
+};
+`;
+};
 const emitWorkflowFragments = (workflows) => {
   if (workflows.length === 0) {
     return { build: "", contextField: "", importLines: [], specs: "" };
@@ -1360,6 +1833,31 @@ ${specEntries}
 `
   };
 };
+const emitQueueFragments = (queues) => {
+  if (queues.length === 0) {
+    return { build: "", contextField: "", importLines: [], specs: "" };
+  }
+  for (const queue of queues) {
+    assertIdentifier(queue.exportName, `queue export "${queue.exportName}"`);
+    assertIdentifier(queue.bindingName, `queue binding "${queue.bindingName}"`);
+  }
+  const specEntries = queues.map((queue) => `    { binding: "${queue.bindingName}", exportName: "${queue.exportName}", name: ${JSON.stringify(queue.name)} },`).join("\n");
+  return {
+    build: `
+            const queues = createQueueContext(env, LUNORA_QUEUES);
+`,
+    contextField: `
+                queues,`,
+    importLines: [`import type { QueueBindingSpec } from "@lunora/queue";`, `import { createQueueContext } from "@lunora/queue";`],
+    // 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.queues\` (codegen-derived from \`lunora/queues.ts\`). */
+const LUNORA_QUEUES: ReadonlyArray<QueueBindingSpec> = [
+${specEntries}
+];
+`
+  };
+};
 const emitWorkflowsMetadataFragments = (workflows) => {
   if (workflows.length === 0) {
     return { constant: "", override: "" };
@@ -1386,6 +1884,33 @@ const LUNORA_WORKFLOWS_INFO: WorkflowsResult = ${JSON.stringify(metadata, void 0
 `
   };
 };
+const emitQueuesMetadataFragments = (queues) => {
+  if (queues.length === 0) {
+    return { constant: "", override: "" };
+  }
+  const metadata = {
+    queues: queues.map((queue) => {
+      return {
+        binding: queue.bindingName,
+        ...queue.tuning.deadLetterQueue === void 0 ? {} : { deadLetterQueue: queue.tuning.deadLetterQueue },
+        exportName: queue.exportName,
+        mode: queue.mode,
+        name: queue.name
+      };
+    })
+  };
+  return {
+    constant: `
+/** Read-only declared-queue metadata (discovered from \`lunora/queues.ts\`) served via \`__lunora_admin__:listQueues\` for the studio's queues view. */
+const LUNORA_QUEUES_INFO: QueuesResult = ${JSON.stringify(metadata, void 0, 4)};
+`,
+    override: `
+        protected override queuesMetadata(): QueuesResult {
+            return LUNORA_QUEUES_INFO;
+        }
+`
+  };
+};
 const emitPaymentFragments = (hasPayments) => {
   if (!hasPayments) {
     return { build: "", configField: "", contextField: "", imports: [], stub: "" };
@@ -1441,13 +1966,15 @@ const paymentStub: LunoraPayment = {
 `
   };
 };
-const buildDoTypeImports = (hasVectors, hasWorkflows) => [
+const buildDoTypeImports = (hasVectors, hasWorkflows, hasQueues, hasFlags) => [
   "AdvisoryFinding",
   "DatabaseWriterLike",
   "DataMigrationLike",
+  ...hasFlags ? ["FlagsResult"] : [],
   "LogSink",
   "MaskPoliciesResult",
   "MigrationRunResult",
+  ...hasQueues ? ["QueuesResult"] : [],
   "RunShardApplyCdcArgs",
   "RunShardMigrationArgs",
   "RlsPoliciesResult",
@@ -1469,36 +1996,50 @@ const buildDoTypeImports = (hasVectors, hasWorkflows) => [
 const emitShard = ({
   advisories = [],
   containers = [],
+  flagKeys = [],
+  hasAccessFacade = false,
   hasAi = false,
   hasAnalytics = false,
   hasBrowser = false,
+  hasFlags = false,
   hasHyperdrive = false,
   hasImages = false,
   hasKv = false,
   hasPayments = false,
+  hasPipelines = false,
   hasR2sql = false,
   maskMetadata,
+  mutators = [],
+  queues = [],
   rlsMetadata,
   schema,
+  shapes = [],
   storageRules,
   studioFeatures,
   useUmbrella = false,
   workflows = []
 }) => {
   const base = baseSpecifiers(useUmbrella);
+  const hasMutators = mutators.length > 0;
+  const hasShapes = shapes.length > 0;
   const { build: aiBuild, configField: aiConfigField, contextField: aiContextField, stub: aiStub } = emitAiFragments(hasAi);
+  const accessFragments = emitAccessFragments(hasAccessFacade);
   const kvFragments = emitKvFragments(hasKv);
+  const flagsFragments = emitFlagsFragments(hasFlags, base.flags);
+  const flagsOverrides = emitFlagsOverrides(flagKeys, hasFlags, base.flags);
   const analyticsFragments = emitAnalyticsFragments(hasAnalytics);
   const imagesFragments = emitImagesFragments(hasImages);
   const hyperdriveFragments = emitHyperdriveFragments(hasHyperdrive);
   const browserFragments = emitBrowserFragments(hasBrowser);
   const r2sqlFragments = emitR2sqlFragments(hasR2sql);
+  const pipelinesFragments = emitPipelinesFragments(hasPipelines);
+  const { build: queuesBuild, contextField: queuesContextField, importLines: queueImportLines, specs: queueSpecs } = emitQueueFragments(queues);
   const {
     build: containersBuild,
     contextField: containersContextField,
     importLines: containerImportLines,
     specs: containerSpecs
-  } = emitContainerFragments(containers);
+  } = emitContainerFragments(containers, schema.jurisdiction);
   const {
     build: workflowsBuild,
     contextField: workflowsContextField,
@@ -1517,20 +2058,29 @@ const emitShard = ({
   const maskData = maskMetadata ?? { columns: [] };
   const storageRulesData = storageRules ?? { rules: [] };
   const studioFeaturesData = studioFeatures ?? {
+    analytics: false,
+    auth: false,
+    containers: false,
+    flags: false,
+    kv: false,
     mail: false,
     payments: false,
+    queues: false,
     scheduler: false,
     storage: false,
     vectors: false,
     workflows: false
   };
   const { constant: workflowsMetadataConst, override: workflowsMetadataOverride } = emitWorkflowsMetadataFragments(workflows);
+  const { constant: queuesMetadataConst, override: queuesMetadataOverride } = emitQueuesMetadataFragments(queues);
   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");
+  const hasSourcedTables = schema.tables.some((table) => table.externalSource !== void 0);
   if (hasD1Global && hasHyperdriveGlobal) {
-    throw new Error(
+    throw new LunoraError(
+      "INTERNAL",
       'lunora codegen: mixing `.global()` (D1) and `.global({ backend: "hyperdrive" })` tables in one app is not supported yet — use a single global backend.'
     );
   }
@@ -1539,41 +2089,113 @@ const emitShard = ({
   const tableIndexes = buildTableIndexes(schema);
   const tableColumns = buildTableColumns(schema);
   const storageColumns = buildStorageColumns(schema);
-  const doTypeImports = buildDoTypeImports(hasVectors, workflows.length > 0);
+  const doTypeImports = buildDoTypeImports(hasVectors, workflows.length > 0, queues.length > 0, hasFlags);
+  if (hasShapes) {
+    doTypeImports.push("WhereInput");
+  }
   const relationFanout = emitRelationFanout(hasGlobalTables);
+  const shapeResolveOverride = hasShapes ? `
+        protected override resolveShape(name: string, args: Record<string, unknown>, identity?: { identity?: Record<string, unknown>; userId?: string }): { columns?: readonly string[]; effectiveWhere?: WhereInput; global?: boolean; table: string } | undefined {
+            const shape = LUNORA_SHAPES[name];
+
+            if (!shape) {
+                return undefined;
+            }
+
+            this.ensureMigrated();
+
+            // Trusted ctx from the socket's OWN verified identity — the client
+            // supplies only the shape name + args; \`compileWhere\` validates the
+            // args then runs the shape's \`where(ctx, args)\` under that identity,
+            // so which rows replicate is a server decision (reads-as-permissions).
+            const ctx = this.buildCtx({ functionPath: \`__shape__:\${name}\`, identity });
+            const shapeWhere = shape.compileWhere(ctx, args) as unknown as WhereInput;
+
+            // AND-compose with the table's RLS read base-where. A shape runs no
+            // procedure, so the \`.use(rls(...))\` middleware never fires; without
+            // this merge its reads would bypass every read policy on the table
+            // (rows the caller can't see would replicate). \`composeShapeReadWhere\`
+            // evaluates the table's read policies under this same trusted ctx —
+            // exactly the request-time path — and fails closed under a
+            // \`.rls("required")\` schema for a non-\`.public()\`, policy-less table.
+            const effectiveWhere = composeShapeReadWhere(LUNORA_RLS_READ_REGISTRY, {
+                ctx,
+                identity: identity?.identity ?? null,
+                rlsRequired: (schema as unknown as { rlsMode?: string }).rlsMode === "required",
+                roles: (ctx as { auth?: { roles?: readonly string[] } }).auth?.roles ?? [],
+                shapeWhere,
+                table: shape.table,
+                tablePublic: (schema as unknown as { tables: Record<string, { isPublic?: boolean }> }).tables[shape.table]?.isPublic === true,
+                userId: identity?.userId ?? null,
+            });
+
+            // A live shape pokes only from its OWN shard's op-log, so a \`where()\`
+            // that joins to a \`.shardBy()\` table (rows in another DO) is rejected
+            // here — the first point the compiled predicate + shard modes are both
+            // known. Remedy: denormalize, or move the joined table to \`.global()\`.
+            assertShapeShardable(effectiveWhere, schema as unknown as SchemaLike, shape.table);
+
+            // A \`.global()\` table lives in D1 (no per-DO op-log): flag it so the
+            // base serves it through the latency-tiered poll path (\`readGlobalShapeRows\`)
+            // instead of the CDC poke path.
+            const isGlobal = (schema as unknown as SchemaLike).tables[shape.table]?.shardMode?.kind === "global";
+
+            return { columns: shape.columns, effectiveWhere, global: isGlobal, table: shape.table };
+        }
+` : "";
+  const customMutatorOverride = hasMutators ? `
+        protected override isCustomMutator(functionPath: string): boolean {
+            return LUNORA_MUTATOR_PATHS.has(functionPath);
+        }
+` : "";
+  const shapeReadRegistryConst = hasShapes ? `
+/** Per-table RLS read policies (hoisted from \`.use(rls(...))\` chains) the shape resolver AND-merges into each \`defineShape\` predicate so partial replication honours read policies. */
+const LUNORA_RLS_READ_REGISTRY = buildRlsReadRegistry(Object.values(LUNORA_FUNCTIONS));
+` : "";
+  const shapeGuardImport = hasShapes ? "assertShapeShardable, " : "";
   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
+    `import { applyCdcChanges, ${shapeGuardImport}createShardCtxDb, ${hasSourcedTables ? "isSourceDue, pullExternalSourceTick, " : ""}runDataMigration, runShardMigrations, ${relationFanout.importFragment}ShardDO as ShardDOBase } from "${base.do}";`,
+    ...hasSourcedTables ? [`import type { ExternalSourceLike, SourceClientLike } from "${base.do}";`] : [],
+    // `asBucketStorage` (the bucket-aware `ctx.storage` wrapper) and
+    // `createSecrets` (the `ctx.secrets` core built-in) live in
     // `@lunora/server`, the single source — imported here rather than stamped
-    // inline into every generated shard.
-    `import { asBucketStorage } from "${base.server}";`
+    // inline into every generated shard. With shapes, also pull the RLS
+    // read-registry builder + `composeShapeReadWhere` so `resolveShape` can
+    // AND-merge a shape's predicate with the table's read base-where.
+    hasShapes ? `import { asBucketStorage, buildRlsReadRegistry, composeShapeReadWhere, createSecrets } from "${base.server}";` : `import { asBucketStorage, createSecrets } 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";`
+      `import type { SchemaLike as VectorSchemaLike, VectorizeIndexLike, VectorSearchLike } from "@lunora/bindings/vectors";`,
+      `import { createContextVectors, createVectors, createVectorSyncHook } from "@lunora/bindings/vectors";`
     );
   }
   if (hasAi) {
     importLines.push(`import type { AiBindingLike, LunoraAi } from "@lunora/ai";`, `import { createAi } from "@lunora/ai";`);
   }
   importLines.push(
+    ...accessFragments.importLines,
     ...kvFragments.importLines,
+    ...flagsFragments.importLines,
     ...analyticsFragments.importLines,
     ...imagesFragments.importLines,
     ...hyperdriveFragments.importLines,
     ...browserFragments.importLines,
     ...r2sqlFragments.importLines,
+    ...pipelinesFragments.importLines,
     ...containerImportLines,
     ...workflowImportLines,
+    ...queueImportLines,
     ...paymentsImports,
     ``,
     `import schema from "../schema.js";`,
-    `import { LUNORA_FUNCTIONS, LUNORA_LIFECYCLE_HOOKS, LUNORA_MIGRATIONS } from "./functions.js";`
+    // Local-first sync registries are pulled in alongside the function table
+    // only when the project declares them, so the import list stays minimal.
+    `import { ${["LUNORA_FUNCTIONS", "LUNORA_LIFECYCLE_HOOKS", "LUNORA_MIGRATIONS", ...hasMutators ? ["LUNORA_MUTATOR_PATHS"] : [], ...hasShapes ? ["LUNORA_SHAPES"] : []].join(", ")} } from "./functions.js";`
   );
   const vectorsConfigField = hasVectors ? `
     vectors?: (env: Record<string, unknown>) => Record<string, VectorizeIndexLike>;` : "";
@@ -1581,6 +2203,8 @@ const emitShard = ({
     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 sourceClientConfigField = hasSourcedTables ? `
+    sourceClient?: (env: Record<string, unknown>, binding: string) => { query: <Row = Record<string, unknown>>(text: string, params?: readonly unknown[]) => Promise<Row[]> } | undefined;` : "";
   const globalDatabaseStub = hasGlobalTables ? `
 const globalDbStub: DatabaseWriterLike = {
     aggregate: async () => {
@@ -1698,6 +2322,144 @@ const vectorsStub: VectorSearchLike = {
   const bindTableHelper = "";
   const globalDatabaseThunk = hasHyperdriveGlobal ? "config.hyperdriveGlobal" : "config.d1";
   const globalDatabaseLine = hasGlobalTables ? `            const globalDb: DatabaseWriterLike = ${globalDatabaseThunk}?.(env, { identity, userId }) ?? globalDbStub;
+` : "";
+  const globalShapeReaderOverride = hasShapes && hasGlobalTables ? `
+        protected override async readGlobalShapeRows(resolved: { columns?: readonly string[]; effectiveWhere?: WhereInput; global?: boolean; table: string }, identity?: { identity?: Record<string, unknown>; userId?: string }): Promise<Array<{ doc: Record<string, unknown>; id: string }>> {
+            const env = this.env as Record<string, unknown>;
+            const globalDb: DatabaseWriterLike = ${globalDatabaseThunk}?.(env, identity) ?? globalDbStub;
+            const rows: Array<{ doc: Record<string, unknown>; id: string }> = [];
+
+            let cursor: null | string = null;
+
+            // Drain every page of the global membership so the seed/diff sees the
+            // full rowset (D1 \`findMany\` is paginated). Stop one row past the cap:
+            // a broad \`.global()\` shape would otherwise materialize an unbounded
+            // array before the caller's \`withinGlobalShapeBound\` check rejects it,
+            // so bail early and let the caller fail it closed.
+            do {
+                // eslint-disable-next-line no-await-in-loop -- sequential page drain to assemble the full membership
+                const page = await globalDb.findMany(resolved.table, { cursor, where: resolved.effectiveWhere });
+
+                for (const doc of page.page) {
+                    rows.push({ doc, id: String((doc as { _id?: unknown })._id) });
+
+                    if (rows.length > ShardDOBase.GLOBAL_SHAPE_MAX_ROWS) {
+                        return rows;
+                    }
+                }
+
+                cursor = page.isDone ? null : page.continueCursor;
+            } while (cursor !== null);
+
+            return rows;
+        }
+` : "";
+  const sourceClientCacheConst = hasSourcedTables ? `
+const sourceClientCache = new WeakMap<object, Map<string, SourceClientLike>>();
+const sourcePollAtCache = new WeakMap<object, Map<string, number>>();
+` : "";
+  const externalSourceOverride = hasSourcedTables ? `
+        protected override async pollExternalSources(): Promise<number> {
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            const sourced = Object.entries((schema as unknown as SchemaLike).tables)
+                .map(([table, definition]) => [table, (definition as { externalSource?: ExternalSourceLike }).externalSource] as const)
+                .filter((entry): entry is [string, ExternalSourceLike] => entry[1] !== undefined);
+
+            if (sourced.length === 0) {
+                return 0;
+            }
+
+            const shardKey = this.currentShardKey();
+            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,
+            });
+
+            let clients = sourceClientCache.get(this);
+
+            if (clients === undefined) {
+                clients = new Map();
+                sourceClientCache.set(this, clients);
+            }
+
+            let polledAt = sourcePollAtCache.get(this);
+
+            if (polledAt === undefined) {
+                polledAt = new Map();
+                sourcePollAtCache.set(this, polledAt);
+            }
+
+            const now = Date.now();
+            // \`active\` counts non-manual sources: while > 0 the alarm re-arms; a
+            // manual-only schema returns 0 so the shared alarm goes idle.
+            let active = 0;
+
+            for (const [table, source] of sourced) {
+                if (source.refresh === "manual") {
+                    continue;
+                }
+
+                active += 1;
+
+                if (!isSourceDue(source.refresh, polledAt.get(table), now)) {
+                    continue;
+                }
+
+                try {
+                    let client = clients.get(source.binding);
+
+                    if (client === undefined) {
+                        client = config.sourceClient?.(env, source.binding);
+
+                        if (client !== undefined) {
+                            clients.set(source.binding, client);
+                        }
+                    }
+
+                    if (client === undefined) {
+                        // No SqlClient resolved for this binding (host never wired
+                        // \`config.sourceClient\`, or wired it wrong). Surface it in the
+                        // Logs panel and stamp \`polledAt\` so a persistent misconfig backs
+                        // off to \`refresh.everyMs\` instead of retrying every alarm tick.
+                        this.recordExternalSourceError(table, new Error(\`external-source: no sourceClient resolved for binding "\${source.binding}"\`));
+                        polledAt.set(table, now);
+                        continue;
+                    }
+
+                    // eslint-disable-next-line no-await-in-loop -- one sourced table at a time; slices are independent but small and sequential keeps the writer transaction simple
+                    await pullExternalSourceTick(this.sql as SqlExec, writer, client, table, source, shardKey);
+                    polledAt.set(table, now);
+                } catch (error) {
+                    this.recordExternalSourceError(table, error);
+                    // Stamp on failure too, so a persistently failing source throttles
+                    // to \`refresh.everyMs\` rather than being hammered every tick.
+                    polledAt.set(table, now);
+                }
+            }
+
+            return active;
+        }
+` : "";
+  const sourceConstructorOverride = hasSourcedTables ? `
+        public constructor(state: ShardDOState, env: unknown) {
+            super(state, env);
+
+            const autoSourced = Object.values((schema as unknown as SchemaLike).tables).some((definition) => {
+                const source = (definition as { externalSource?: ExternalSourceLike }).externalSource;
+
+                return source !== undefined && source.refresh !== "manual";
+            });
+
+            if (autoSourced) {
+                void this.scheduleSourcePoll();
+            }
+        }
 ` : "";
   const facadeBlock = hasTables ? `
             const facade = db as unknown as Record<string, ReturnType<typeof bindTableFacade>>;
@@ -1711,18 +2473,23 @@ ${schema.tables.map(
     (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 || hasR2sql;
+  const secretsBuild = `
+            const secrets = createSecrets(env);
+`;
+  const everyContextBuild = `${accessFragments.build}${kvFragments.build}${flagsFragments.build}${analyticsFragments.build}${secretsBuild}`;
+  const everyContextField = `${accessFragments.contextField}${kvFragments.contextField}${flagsFragments.contextField}${analyticsFragments.contextField}
+                secrets,`;
+  const actionOnlyHasAny = hasImages || hasHyperdrive || hasBrowser || hasR2sql || hasPipelines;
   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}${r2sqlFragments.build}${[
+${imagesFragments.build}${hyperdriveFragments.build}${browserFragments.build}${r2sqlFragments.build}${pipelinesFragments.build}${[
     ...hasImages ? ["                ctx.images = images;"] : [],
     ...hasHyperdrive ? ["                ctx.sql = sql;"] : [],
     ...hasBrowser ? ["                ctx.browser = browser;"] : [],
-    ...hasR2sql ? ["                ctx.r2sql = r2sql;"] : []
+    ...hasR2sql ? ["                ctx.r2sql = r2sql;"] : [],
+    ...hasPipelines ? ["                ctx.pipelines = pipelines;"] : []
   ].join("\n")}
             }
 ` : "";
@@ -1762,14 +2529,14 @@ const LUNORA_STORAGE_RULES: StorageRulesResult = ${JSON.stringify(storageRulesDa
 
 /** 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}
+${flagsOverrides.constant}${shapeReadRegistryConst}${workflowsMetadataConst}${queuesMetadataConst}${containerSpecs}${workflowSpecs}${queueSpecs}
 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}${r2sqlFragments.configField}${paymentsConfigField}${d1ConfigField}${hyperdriveGlobalConfigField}
+    storage?: (env: Record<string, unknown>) => unknown;${vectorsConfigField}${aiConfigField}${kvFragments.configField}${flagsFragments.configField}${analyticsFragments.configField}${imagesFragments.configField}${hyperdriveFragments.configField}${browserFragments.configField}${r2sqlFragments.configField}${pipelinesFragments.configField}${paymentsConfigField}${d1ConfigField}${hyperdriveGlobalConfigField}${sourceClientConfigField}
 }
 
 const schedulerStub = {
@@ -1807,7 +2574,7 @@ const storageStub = {
         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}${r2sqlFragments.stub}${paymentStub}${bindTableHelper}
+${globalDatabaseStub}${sourceClientCacheConst}${vectorsStub}${aiStub}${kvFragments.stub}${flagsFragments.stub}${analyticsFragments.stub}${imagesFragments.stub}${hyperdriveFragments.stub}${browserFragments.stub}${r2sqlFragments.stub}${pipelinesFragments.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
@@ -1848,7 +2615,7 @@ const dispatchRun = async (expected: FunctionKind, functionPath: string, args: R
  * from the worker entry so wrangler binds it by name.
  */
 export const createShardDO = (config: ShardDOConfig = {}): new (state: ShardDOState, env: unknown) => ShardDOBase =>
-    class extends ShardDOBase {
+    class extends ShardDOBase {${sourceConstructorOverride}
         private migrated = false;
 
         public override async handleRpc(functionPath: string, args: Record<string, unknown>): Promise<unknown> {
@@ -1877,8 +2644,20 @@ export const createShardDO = (config: ShardDOConfig = {}): new (state: ShardDOSt
             // 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.
+            //
+            // The replay bookkeeping (idempotency dedup row + custom-mutator
+            // watermark advance) commits INSIDE this span via
+            // \`commitMutationBookkeeping\`, so the writes, the dedup row, and the
+            // watermark are atomic — a crash can't leave the writes durable without
+            // the replay guard.
             if (registered.kind === "mutation") {
-                return this.runInTransaction(() => registered.handler(ctx, args));
+                return this.runInTransaction(async () => {
+                    const result = await registered.handler(ctx, args);
+
+                    this.commitMutationBookkeeping(result);
+
+                    return result;
+                });
             }
 
             return registered.handler(ctx, args);
@@ -1916,7 +2695,7 @@ ${relationFanout.override}
                 iterator: (signal) => (registered.handler as (context: unknown, args: Record<string, unknown>, signal: AbortSignal) => AsyncIterable<unknown>)(this.buildCtx({ functionPath }), args, signal),
             };
         }
-
+${customMutatorOverride}${shapeResolveOverride}${globalShapeReaderOverride}${externalSourceOverride}
         protected override lifecycleHookPaths(event: "connect" | "disconnect"): readonly string[] {
             return LUNORA_LIFECYCLE_HOOKS[event];
         }
@@ -1952,7 +2731,7 @@ ${relationFanout.override}
         protected override studioFeatures(): StudioFeaturesResult {
             return LUNORA_STUDIO_FEATURES;
         }
-${workflowsMetadataOverride}
+${flagsOverrides.evaluateOverride}${flagsOverrides.subscriptionOverride}${workflowsMetadataOverride}${queuesMetadataOverride}
         protected override advisories(): AdvisoryFinding[] {
             return LUNORA_ADVISORIES;
         }
@@ -2186,7 +2965,7 @@ ${workflowsMetadataOverride}
             // 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}
+${vectorsBuild}${aiBuild}${everyContextBuild}${containersBuild}${workflowsBuild}${queuesBuild}
             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
@@ -2209,6 +2988,14 @@ ${facadeBlock}${paymentsBuild}
                 warn: (...args: unknown[]) => { this.recordUserLog(logFunctionPath, "warn", args, observability); },
             };
 
+            // \`ctx.now\`: the wall-clock instant (epoch ms) this function began,
+            // captured ONCE so the whole handler body sees a single stable value.
+            // Query/mutation handlers must be deterministic (they may be re-run on
+            // OCC retry / subscription re-eval), so they must read time through
+            // \`ctx.now\` instead of \`Date.now()\` — the \`nondeterministic_query_mutation\`
+            // advisor flags the latter. Actions may still use ambient \`Date.now()\`.
+            const now = Date.now();
+
             const ctx: Record<string, unknown> = {
                 auth: {
                     getIdentity: async () => identity ?? null,
@@ -2217,9 +3004,10 @@ ${facadeBlock}${paymentsBuild}
                 db,
                 fetch: globalThis.fetch.bind(globalThis),
                 ip: this.getCurrentIp(),
-                log,${ormContextField}
+                log,
+                now,${ormContextField}
                 scheduler,
-                storage,${vectorsContextField}${aiContextField}${everyContextField}${paymentsContextField}${containersContextField}${workflowsContextField}
+                storage,${vectorsContextField}${aiContextField}${everyContextField}${paymentsContextField}${containersContextField}${workflowsContextField}${queuesContextField}
             };
 ${isActionLine}${actionOnlyBlock}
             ctx.runAction = (reference: FunctionReference, fnArgs: Record<string, unknown>) => dispatchRun("action", reference.__lunoraRef, fnArgs, ctx);
@@ -2483,4 +3271,4 @@ const emitWranglerCronTriggers = (crons) => {
   return triggers;
 };
 
-export { GENERATED_HEADER, buildStorageColumns, emitApi, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitSeed, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers };
+export { GENERATED_HEADER, buildStorageColumns, emitApi, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitQueues, emitSeed, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers };