@lunora/codegen 1.0.0-alpha.16 → 1.0.0-alpha.18

package/dist/packem_shared/{GENERATED_HEADER-CkZUgM4_.mjs → GENERATED_HEADER-D-AbhmRh.mjs}

@@ -600,6 +600,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];
@@ -614,7 +634,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)) {
@@ -627,6 +647,12 @@ 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)}`);
@@ -639,6 +665,12 @@ 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;
@@ -651,8 +683,8 @@ const renderFunctionRegistry = (functions, migrations) => {
     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}
 
@@ -660,6 +692,10 @@ ${dispatchEntries}
     installBlock: installLines,
     migrationBody: migrationEntries.length > 0 ? `
 ${migrationEntries}
+` : "",
+    mutatorPaths,
+    shapeBody: shapeEntries.length > 0 ? `
+${shapeEntries}
 ` : ""
   };
 };
@@ -713,6 +749,7 @@ const buildStorageBucketNames = (schema, ruleBuckets = []) => {
 };
 const emitServer = ({
   containers = [],
+  hasAccessFacade = false,
   hasAi = false,
   hasAnalytics = false,
   hasBrowser = false,
@@ -785,6 +822,9 @@ ${envBindingFields}` : ""}
 export type Env = CloudflareBindings;`;
   const kvContextField = hasKv ? `
     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("@lunora/flags").LunoraFlags;` : "";
@@ -902,19 +942,19 @@ type TypedTableGet = <T extends TableName>(id: IdOfTable<T>) => Promise<Doc<T> |
 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}${flagsContextField}${analyticsContextField}
+    readonly storage: ReadOnlyStorage<StorageBucketName>;${accessContextField}${kvContextField}${flagsContextField}${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}${flagsContextField}${analyticsContextField}${workflowsContextField}${queuesContextField}
+    readonly storage: ReadOnlyStorage<StorageBucketName>;${accessContextField}${kvContextField}${flagsContextField}${analyticsContextField}${workflowsContextField}${queuesContextField}
 }
 
 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}${flagsContextField}${hyperdriveActionField}${browserActionField}${imagesActionField}${analyticsContextField}${pipelinesActionField}${r2sqlActionField}${workflowsContextField}${queuesContextField}
+    readonly storage: StorageBase<StorageBucketName>;${accessContextField}${aiActionField}${paymentsActionField}${containersActionField}${kvContextField}${flagsContextField}${hyperdriveActionField}${browserActionField}${imagesActionField}${analyticsContextField}${pipelinesActionField}${r2sqlActionField}${workflowsContextField}${queuesContextField}
 }
 
 /**
@@ -984,11 +1024,30 @@ const renderLifecycleManifest = (functions) => {
   }
   return manifest;
 };
-const emitFunctions = (functions, migrations = [], useUmbrella = false) => {
+const emitFunctions = (functions, migrations = [], useUmbrella = false, mutators = [], shapes = []) => {
   const hasFunctions = functions.length > 0;
   const base = baseSpecifiers(useUmbrella);
-  const { dispatchBody, importBlock, installBlock, migrationBody } = renderFunctionRegistry(functions, migrations);
+  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 ? `
@@ -1013,7 +1072,7 @@ ${caller.implementation}
   const callRegisteredHelper = hasFunctions ? `${CALL_REGISTERED_HELPER}
 
 ` : "";
-  return `${GENERATED_HEADER}${importBlock}${compiledArgsImport}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.
@@ -1039,7 +1098,7 @@ export interface RegisteredLunoraFunction {
  * emits (\`api[namespace][fn].__lunoraRef === "namespace:fn"\`).
  */
 export const LUNORA_FUNCTIONS: Record<string, RegisteredLunoraFunction> = {${dispatchBody}};
-${compiledArgsInstall}
+${compiledArgsInstall}${shapeRegistry}${mutatorPathsRegistry}
 /**
  * Connection-lifecycle manifest: the function paths the generated ShardDO
  * dispatches when a client's WebSocket connects (\`connect\`) or disconnects
@@ -1306,6 +1365,21 @@ const emitFlagsFragments = (hasFlags) => {
     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) => {
   if (!hasFlags) {
     return { constant: "", evaluateOverride: "", subscriptionOverride: "" };
@@ -1899,6 +1973,7 @@ const emitShard = ({
   advisories = [],
   containers = [],
   flagKeys = [],
+  hasAccessFacade = false,
   hasAi = false,
   hasAnalytics = false,
   hasBrowser = false,
@@ -1910,16 +1985,21 @@ const emitShard = ({
   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);
   const flagsOverrides = emitFlagsOverrides(flagKeys, hasFlags);
@@ -1980,15 +2060,79 @@ const emitShard = ({
   const tableColumns = buildTableColumns(schema);
   const storageColumns = buildStorageColumns(schema);
   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}";`,
+    `import { applyCdcChanges, ${shapeGuardImport}createShardCtxDb, runDataMigration, runShardMigrations, ${relationFanout.importFragment}ShardDO as ShardDOBase } 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, createSecrets } 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}";`);
@@ -2003,6 +2147,7 @@ const emitShard = ({
     importLines.push(`import type { AiBindingLike, LunoraAi } from "@lunora/ai";`, `import { createAi } from "@lunora/ai";`);
   }
   importLines.push(
+    ...accessFragments.importLines,
     ...kvFragments.importLines,
     ...flagsFragments.importLines,
     ...analyticsFragments.importLines,
@@ -2017,7 +2162,9 @@ const emitShard = ({
     ...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>;` : "";
@@ -2142,6 +2289,37 @@ 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 facadeBlock = hasTables ? `
             const facade = db as unknown as Record<string, ReturnType<typeof bindTableFacade>>;
@@ -2158,8 +2336,8 @@ ${schema.tables.map(
   const secretsBuild = `
             const secrets = createSecrets(env);
 `;
-  const everyContextBuild = `${kvFragments.build}${flagsFragments.build}${analyticsFragments.build}${secretsBuild}`;
-  const everyContextField = `${kvFragments.contextField}${flagsFragments.contextField}${analyticsFragments.contextField}
+  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 ? `
@@ -2211,7 +2389,7 @@ 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)};
-${flagsOverrides.constant}${workflowsMetadataConst}${queuesMetadataConst}${containerSpecs}${workflowSpecs}${queueSpecs}
+${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;
@@ -2326,8 +2504,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);
@@ -2365,7 +2555,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}
         protected override lifecycleHookPaths(event: "connect" | "disconnect"): readonly string[] {
             return LUNORA_LIFECYCLE_HOOKS[event];
         }
@@ -2941,4 +3131,4 @@ const emitWranglerCronTriggers = (crons) => {
   return triggers;
 };
 
-export { GENERATED_HEADER, buildStorageColumns, emitApi, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitQueues, emitSeed, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers };
+export { GENERATED_HEADER, buildStorageColumns, emitApi, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitQueues, emitSeed, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers };

package/dist/packem_shared/MUTATORS_FILENAME-BhqdPtKp.mjs

@@ -0,0 +1,81 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { Node, SyntaxKind } from 'ts-morph';
+import { diagnosticAt } from './CodegenDiagnosticError-DeblMkzO.mjs';
+
+const MUTATORS_FILENAME = "mutators.ts";
+const MUTATOR_MODULE_SPECIFIERS = /* @__PURE__ */ new Set(["@lunora/server", "lunorash/server"]);
+const isDefineMutator = (identifier) => {
+  const symbol = identifier.getSymbol();
+  if (!symbol) {
+    return identifier.getText() === "defineMutator";
+  }
+  for (const declaration of symbol.getDeclarations()) {
+    if (!Node.isImportSpecifier(declaration)) {
+      continue;
+    }
+    if (!MUTATOR_MODULE_SPECIFIERS.has(declaration.getImportDeclaration().getModuleSpecifierValue())) {
+      return false;
+    }
+    return declaration.getNameNode().getText() === "defineMutator";
+  }
+  return false;
+};
+const isMutatorNamespaceImport = (identifier) => {
+  const symbol = identifier.getSymbol();
+  if (!symbol) {
+    return false;
+  }
+  for (const declaration of symbol.getDeclarations()) {
+    if (!Node.isNamespaceImport(declaration)) {
+      continue;
+    }
+    const importDeclaration = declaration.getFirstAncestorByKind(SyntaxKind.ImportDeclaration);
+    return importDeclaration !== void 0 && MUTATOR_MODULE_SPECIFIERS.has(importDeclaration.getModuleSpecifierValue());
+  }
+  return false;
+};
+const isDefineMutatorCallee = (callee) => {
+  if (Node.isIdentifier(callee)) {
+    return isDefineMutator(callee);
+  }
+  if (Node.isPropertyAccessExpression(callee)) {
+    const object = callee.getExpression();
+    return callee.getName() === "defineMutator" && Node.isIdentifier(object) && isMutatorNamespaceImport(object);
+  }
+  return false;
+};
+const mutatorsFromSource = (source) => {
+  const mutators = [];
+  for (const declaration of source.getVariableDeclarations()) {
+    if (!declaration.isExported()) {
+      continue;
+    }
+    const initializer = declaration.getInitializer();
+    if (initializer?.getKind() !== SyntaxKind.CallExpression) {
+      continue;
+    }
+    const callee = initializer.getExpression();
+    if (!isDefineMutatorCallee(callee)) {
+      continue;
+    }
+    const nameNode = declaration.getNameNode();
+    if (!Node.isIdentifier(nameNode)) {
+      throw diagnosticAt(nameNode, "defineMutator exports must be plain named exports (no destructuring)");
+    }
+    mutators.push({ exportName: nameNode.getText(), filePath: "mutators" });
+  }
+  return mutators;
+};
+const discoverMutators = (project, lunoraDirectory) => {
+  const mutatorsPath = join(lunoraDirectory, MUTATORS_FILENAME);
+  if (!existsSync(mutatorsPath)) {
+    return [];
+  }
+  const source = project.getSourceFile(mutatorsPath) ?? project.addSourceFileAtPath(mutatorsPath);
+  const mutators = mutatorsFromSource(source);
+  mutators.sort((a, b) => a.exportName.localeCompare(b.exportName));
+  return mutators;
+};
+
+export { MUTATORS_FILENAME, discoverMutators, isDefineMutatorCallee };

package/dist/packem_shared/{OPENRPC_VERSION-VINwUAxf.mjs → OPENRPC_VERSION-DDT4mIzD.mjs}

@@ -1,4 +1,4 @@
-import { GENERATED_HEADER } from './GENERATED_HEADER-CkZUgM4_.mjs';
+import { GENERATED_HEADER } from './GENERATED_HEADER-D-AbhmRh.mjs';
 import { s as sanitizeNamespace } from './paths-BRd6JHuF.mjs';
 import { argsObjectSchema, LUNORA_ERROR_CODES } from './LUNORA_ERROR_CODES-CySpQPD3.mjs';