@lunora/codegen 1.0.0-alpha.15 → 1.0.0-alpha.17

package/dist/index.d.mts

@@ -201,6 +201,59 @@ interface MigrationIR {
   table: string;
 }
 /**
+* A `defineShape({...})` declaration discovered in `lunora/shapes.ts`
+* (local-first sync engine, Phase 7). The emitted `LUNORA_SHAPES` registry keys
+* on {@link ShapeIR.exportName}; the generated DO's `resolveShape` override
+* dispatches a `shape_subscribe` to the matching registered shape. Discovery is
+* marker-driven (the `__lunoraShape` brand) — no field metadata is lifted here
+* because the runtime object (`columns`/`compileWhere`) carries the authority.
+*/
+interface ShapeIR {
+  /** Export binding name — the shape's registry key and import member. */
+  exportName: string;
+  /** Path relative to `<projectRoot>/lunora/` without extension — always `"shapes"`. */
+  filePath: string;
+  /**
+  * The `table` string literal from the `defineShape({ table })` call, lifted
+  * only for static advisor lints (the runtime object stays authoritative).
+  * `undefined` when `table` is not a plain string literal — lints skip those.
+  */
+  table?: string;
+}
+/**
+* A `defineMutator({...})` declaration discovered in `lunora/mutators.ts`
+* (local-first sync engine, Phase 7). The emitted registry registers the
+* authoritative `server` impl into the DO's `LUNORA_FUNCTIONS` table (so
+* `handleRpc` transaction-wraps it) and records its path in
+* `LUNORA_MUTATOR_PATHS` so the DO's `isCustomMutator` override routes the
+* client-watermark push protocol. The client `client` impl is split into the
+* browser bundle separately — only the path crosses to the server side.
+*/
+interface MutatorIR {
+  /** Export binding name — the mutator's registry key and import member. */
+  exportName: string;
+  /** Path relative to `<projectRoot>/lunora/` without extension — always `"mutators"`. */
+  filePath: string;
+}
+/**
+* A whole-row `ctx.db.replace(id, document)` write discovered inside a custom
+* mutator's inline `server` impl (`lunora/mutators.ts`) — the input the
+* `mutator_full_row_replace` advisor lint consumes. A `replace` overwrites the
+* entire row, so a concurrent edit to a different column on a synced table is
+* clobbered; `ctx.db.patch(id, { field })` merges at the column level instead.
+* Structurally identical to `AdvisorMutatorWrite` so it passes straight through
+* to the advisor without conversion, exactly as `InsertWriteIR` does for
+* `AdvisorInsertWrite`.
+*/
+interface MutatorWriteIR {
+  /** The mutator export whose `server` impl performs the replace, e.g. `renameChannel`. */
+  exportName: string;
+  /** Openable source path the replace appears in — always `lunora/mutators.ts`. */
+  file: string;
+  /** 1-based line of the `replace(...)` call. */
+  line: number;
+}
+/**
 * A single cron job lifted from a `cronJobs()` builder in `lunora/crons.ts`.
 * Mirrors `@lunora/scheduler`'s `CronJob`: {@link CronJobIR.cron} is the compiled
 * standard cron expression, {@link CronJobIR.functionPath} is the target
@@ -783,7 +836,7 @@ interface ProjectIR {
 * pass straight through without conversion. Returns the findings; surfacing them
 * (console, error overlay, studio Advisors table) is the caller's choice.
 */
-declare const lintSchema: (schema: SchemaIR, queries?: ReadonlyArray<QueryReadIR>, inserts?: ReadonlyArray<InsertWriteIR>, authApiCalls?: ReadonlyArray<AuthApiCallIR>, rlsProcedures?: ReadonlyArray<RlsProcedureIR>, containers?: ReadonlyArray<ContainerIR>, workflows?: ReadonlyArray<WorkflowIR>, workflowCalls?: ReadonlyArray<WorkflowCallIR>, maskProcedures?: ReadonlyArray<MaskProcedureIR>, nondeterministicCalls?: ReadonlyArray<NondeterministicCallIR>, procedureProtections?: ReadonlyArray<ProcedureMiddlewareIR>, argumentValidators?: ReadonlyArray<ArgumentValidatorIR>, secretLiterals?: ReadonlyArray<SecretLiteralIR>, sqlInterpolations?: ReadonlyArray<SqlInterpolationIR>, adminRoutes?: ReadonlyArray<AdminRouteIR>, r2sqlCalls?: ReadonlyArray<R2sqlCallIR>) => Finding[];
+declare const lintSchema: (schema: SchemaIR, queries?: ReadonlyArray<QueryReadIR>, inserts?: ReadonlyArray<InsertWriteIR>, authApiCalls?: ReadonlyArray<AuthApiCallIR>, rlsProcedures?: ReadonlyArray<RlsProcedureIR>, containers?: ReadonlyArray<ContainerIR>, workflows?: ReadonlyArray<WorkflowIR>, workflowCalls?: ReadonlyArray<WorkflowCallIR>, maskProcedures?: ReadonlyArray<MaskProcedureIR>, nondeterministicCalls?: ReadonlyArray<NondeterministicCallIR>, procedureProtections?: ReadonlyArray<ProcedureMiddlewareIR>, argumentValidators?: ReadonlyArray<ArgumentValidatorIR>, secretLiterals?: ReadonlyArray<SecretLiteralIR>, sqlInterpolations?: ReadonlyArray<SqlInterpolationIR>, adminRoutes?: ReadonlyArray<AdminRouteIR>, r2sqlCalls?: ReadonlyArray<R2sqlCallIR>, shapes?: ReadonlyArray<ShapeIR>, mutatorWrites?: ReadonlyArray<MutatorWriteIR>) => Finding[];
 /**
 * Render advisor findings as a single multi-line string for console surfacing:
 * a one-line summary header followed by one `[LEVEL] name: detail` line per
@@ -898,6 +951,23 @@ declare const discoverMaskProcedures: (project: Project, lunoraDirectory: string
 * key); `table` is best-effort and left `""` when not a literal.
 */
 declare const discoverMigrations: (project: Project, lunoraDirectory: string) => MigrationIR[];
+/** The only file custom mutators may be declared in — mirrors `lunora/queues.ts`. */
+declare const MUTATORS_FILENAME = "mutators.ts";
+/**
+* Decide whether a call's callee is `defineMutator` — either the bare imported
+* identifier (`defineMutator(...)`) or a namespace member access
+* (`server.defineMutator(...)`). Both are valid ES module syntax, so discovery
+* must see mutators declared either way.
+*/
+
+/**
+* Discover every custom mutator the project declares: exported
+* `defineMutator()` calls in `lunora/mutators.ts`. Returns `[]` when the file
+* doesn't exist. Only the export binding is lifted — the runtime object carries
+* the authoritative `server` impl + `handler`, so codegen never evaluates the
+* body. The client `client` impl is split into the browser bundle separately.
+*/
+declare const discoverMutators: (project: Project, lunoraDirectory: string) => MutatorIR[];
 /**
 * Discover non-deterministic API calls (`Date.now`, `new Date()`, `Date()`,
 * `Math.random`, `crypto.randomUUID`, `crypto.getRandomValues` — including
@@ -963,6 +1033,16 @@ declare const discoverRlsMetadata: (project: Project, lunoraDirectory: string) =
 * return a structural IR. Throws if the file or call cannot be found.
 */
 declare const discoverSchema: (project: Project, schemaPath: string, projectRoot?: string) => SchemaIR;
+/** The only file shapes may be declared in — mirrors `lunora/queues.ts`. */
+declare const SHAPES_FILENAME = "shapes.ts";
+/**
+* Discover every replication shape the project declares: exported
+* `defineShape()` calls in `lunora/shapes.ts`. Returns `[]` when the file
+* doesn't exist. Only the export binding is lifted — the runtime object carries
+* the authoritative `table`/`columns`/`compileWhere`, so codegen never
+* evaluates the predicate.
+*/
+declare const discoverShapes: (project: Project, lunoraDirectory: string) => ShapeIR[];
 /**
 * Aggregate the schema-wide storage-rule metadata the studio's inspector reads:
 * every statically-discovered `(bucket, on, prefix, procedure)` entry across all
@@ -1001,6 +1081,22 @@ declare const emitApi: (functions: ReadonlyArray<FunctionIR>, workflows?: Readon
 * Returns `""` when `@lunora/seed` is not a declared dependency, so projects
 * that don't use it keep a clean `_generated/` and never import the package.
 */
+
+/**
+* Emit `_generated/collections.ts` — one TanStack DB collection factory per
+* `defineShape` in `lunora/shapes.ts` (the local-first partial-replication
+* surface). Each factory builds a live collection that syncs its shape's rowset
+* through the client's poke protocol (`subscribeShape`), so an app feeds the
+* result straight to `useLiveQuery`.
+*
+* Returns `""` (so `writeIfPresent` skips the file) unless the project both
+* declares shapes AND installs `@lunora/db` — the add-on that ships
+* `lunoraCollectionOptions`. `@lunora/db` stays a scoped install even under the
+* `lunorash` umbrella (an opt-in add-on, like `@lunora/auth`), so its import is
+* always `@lunora/db/collections`; only the in-umbrella `@lunora/client` import
+* is remapped to `lunorash/client`.
+*/
+declare const emitCollections: (shapes: ReadonlyArray<ShapeIR>, hasDatabase: boolean, useUmbrella?: boolean) => string;
 interface EmitServerOptions {
   containers?: ReadonlyArray<ContainerIR>;
   hasAi?: boolean;
@@ -1047,7 +1143,7 @@ declare const emitServer: ({
   useUmbrella,
   workflows
 }?: EmitServerOptions) => string;
-declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>, useUmbrella?: boolean) => string;
+declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>, useUmbrella?: boolean, mutators?: ReadonlyArray<MutatorIR>, shapes?: ReadonlyArray<ShapeIR>) => string;
 /**
 * Storage-column map per table for the file browser: `{ table: [field, …] }` for
 * every field declared `v.storage(...)` (unwrapping `v.optional(...)`). The
@@ -1110,10 +1206,14 @@ interface EmitShardOptions {
   /** A `lunora/` source reads `ctx.r2sql` (R2 SQL) — wires `ctx.r2sql` onto the ActionCtx only. */
   hasR2sql?: boolean;
   maskMetadata?: MaskMetadataIR;
+  /** Custom mutators declared via `defineMutator` in `lunora/mutators.ts` — wires the `isCustomMutator` push-protocol override. */
+  mutators?: ReadonlyArray<MutatorIR>;
   /** Queues declared via `defineQueue` exports in `lunora/queues.ts` — wires the typed `ctx.queues` producers. */
   queues?: ReadonlyArray<QueueIR>;
   rlsMetadata?: RlsMetadataIR;
   schema: SchemaIR;
+  /** Replication shapes declared via `defineShape` in `lunora/shapes.ts` — wires the `resolveShape` subscription override. */
+  shapes?: ReadonlyArray<ShapeIR>;
   storageRules?: StorageRulesMetadataIR;
   studioFeatures?: StudioFeaturesResult;
   /** The project depends on the `lunora` umbrella — import base packages via its subpaths. */
@@ -1135,9 +1235,11 @@ declare const emitShard: ({
   hasPipelines,
   hasR2sql,
   maskMetadata,
+  mutators,
   queues,
   rlsMetadata,
   schema,
+  shapes,
   storageRules,
   studioFeatures,
   useUmbrella,
@@ -1591,6 +1693,8 @@ interface CodegenResult {
   generated: {
     api: string; /** Fluent worker-composition builder (`_generated/app.ts`) — `defineApp()`. Always written. */
     app: string;
+    /** Partial-replication collection factories (`_generated/collections.ts`); `""` (and not written) unless the project declares shapes and installs `@lunora/db`. */
+    collections: string;
     /** Container DO classes (`_generated/containers.ts`); `""` (and not written) when no containers are declared. */
     containers: string;
     crons: string;
@@ -1725,4 +1829,4 @@ declare const LUNORA_SOLUTION_RULES: ReadonlyArray<LunoraSolutionRule>;
 */
 declare const findLunoraSolution: (message: string) => LunoraSolution | undefined;
 declare const VERSION = "0.0.0";
-export { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, LUNORA_SOLUTION_RULES, type LunoraSolution, type LunoraSolutionRule, type MaskProcedureIR, type MigrationIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverNondeterministicCalls, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, findLunoraSolution, formatAdvisories, lintSchema, parseSchemaSnapshot, refreshCodegenProject, runCodegen, schemaFromIr, serializeSchemaSnapshot, validatorIrToJsonSchema };
+export { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, LUNORA_SOLUTION_RULES, type LunoraSolution, type LunoraSolutionRule, MUTATORS_FILENAME, type MaskProcedureIR, type MigrationIR, type MutatorIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, SHAPES_FILENAME, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type ShapeIR, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverMutators, discoverNondeterministicCalls, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverShapes, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, findLunoraSolution, formatAdvisories, lintSchema, parseSchemaSnapshot, refreshCodegenProject, runCodegen, schemaFromIr, serializeSchemaSnapshot, validatorIrToJsonSchema };

package/dist/index.d.ts

@@ -201,6 +201,59 @@ interface MigrationIR {
   table: string;
 }
 /**
+* A `defineShape({...})` declaration discovered in `lunora/shapes.ts`
+* (local-first sync engine, Phase 7). The emitted `LUNORA_SHAPES` registry keys
+* on {@link ShapeIR.exportName}; the generated DO's `resolveShape` override
+* dispatches a `shape_subscribe` to the matching registered shape. Discovery is
+* marker-driven (the `__lunoraShape` brand) — no field metadata is lifted here
+* because the runtime object (`columns`/`compileWhere`) carries the authority.
+*/
+interface ShapeIR {
+  /** Export binding name — the shape's registry key and import member. */
+  exportName: string;
+  /** Path relative to `<projectRoot>/lunora/` without extension — always `"shapes"`. */
+  filePath: string;
+  /**
+  * The `table` string literal from the `defineShape({ table })` call, lifted
+  * only for static advisor lints (the runtime object stays authoritative).
+  * `undefined` when `table` is not a plain string literal — lints skip those.
+  */
+  table?: string;
+}
+/**
+* A `defineMutator({...})` declaration discovered in `lunora/mutators.ts`
+* (local-first sync engine, Phase 7). The emitted registry registers the
+* authoritative `server` impl into the DO's `LUNORA_FUNCTIONS` table (so
+* `handleRpc` transaction-wraps it) and records its path in
+* `LUNORA_MUTATOR_PATHS` so the DO's `isCustomMutator` override routes the
+* client-watermark push protocol. The client `client` impl is split into the
+* browser bundle separately — only the path crosses to the server side.
+*/
+interface MutatorIR {
+  /** Export binding name — the mutator's registry key and import member. */
+  exportName: string;
+  /** Path relative to `<projectRoot>/lunora/` without extension — always `"mutators"`. */
+  filePath: string;
+}
+/**
+* A whole-row `ctx.db.replace(id, document)` write discovered inside a custom
+* mutator's inline `server` impl (`lunora/mutators.ts`) — the input the
+* `mutator_full_row_replace` advisor lint consumes. A `replace` overwrites the
+* entire row, so a concurrent edit to a different column on a synced table is
+* clobbered; `ctx.db.patch(id, { field })` merges at the column level instead.
+* Structurally identical to `AdvisorMutatorWrite` so it passes straight through
+* to the advisor without conversion, exactly as `InsertWriteIR` does for
+* `AdvisorInsertWrite`.
+*/
+interface MutatorWriteIR {
+  /** The mutator export whose `server` impl performs the replace, e.g. `renameChannel`. */
+  exportName: string;
+  /** Openable source path the replace appears in — always `lunora/mutators.ts`. */
+  file: string;
+  /** 1-based line of the `replace(...)` call. */
+  line: number;
+}
+/**
 * A single cron job lifted from a `cronJobs()` builder in `lunora/crons.ts`.
 * Mirrors `@lunora/scheduler`'s `CronJob`: {@link CronJobIR.cron} is the compiled
 * standard cron expression, {@link CronJobIR.functionPath} is the target
@@ -783,7 +836,7 @@ interface ProjectIR {
 * pass straight through without conversion. Returns the findings; surfacing them
 * (console, error overlay, studio Advisors table) is the caller's choice.
 */
-declare const lintSchema: (schema: SchemaIR, queries?: ReadonlyArray<QueryReadIR>, inserts?: ReadonlyArray<InsertWriteIR>, authApiCalls?: ReadonlyArray<AuthApiCallIR>, rlsProcedures?: ReadonlyArray<RlsProcedureIR>, containers?: ReadonlyArray<ContainerIR>, workflows?: ReadonlyArray<WorkflowIR>, workflowCalls?: ReadonlyArray<WorkflowCallIR>, maskProcedures?: ReadonlyArray<MaskProcedureIR>, nondeterministicCalls?: ReadonlyArray<NondeterministicCallIR>, procedureProtections?: ReadonlyArray<ProcedureMiddlewareIR>, argumentValidators?: ReadonlyArray<ArgumentValidatorIR>, secretLiterals?: ReadonlyArray<SecretLiteralIR>, sqlInterpolations?: ReadonlyArray<SqlInterpolationIR>, adminRoutes?: ReadonlyArray<AdminRouteIR>, r2sqlCalls?: ReadonlyArray<R2sqlCallIR>) => Finding[];
+declare const lintSchema: (schema: SchemaIR, queries?: ReadonlyArray<QueryReadIR>, inserts?: ReadonlyArray<InsertWriteIR>, authApiCalls?: ReadonlyArray<AuthApiCallIR>, rlsProcedures?: ReadonlyArray<RlsProcedureIR>, containers?: ReadonlyArray<ContainerIR>, workflows?: ReadonlyArray<WorkflowIR>, workflowCalls?: ReadonlyArray<WorkflowCallIR>, maskProcedures?: ReadonlyArray<MaskProcedureIR>, nondeterministicCalls?: ReadonlyArray<NondeterministicCallIR>, procedureProtections?: ReadonlyArray<ProcedureMiddlewareIR>, argumentValidators?: ReadonlyArray<ArgumentValidatorIR>, secretLiterals?: ReadonlyArray<SecretLiteralIR>, sqlInterpolations?: ReadonlyArray<SqlInterpolationIR>, adminRoutes?: ReadonlyArray<AdminRouteIR>, r2sqlCalls?: ReadonlyArray<R2sqlCallIR>, shapes?: ReadonlyArray<ShapeIR>, mutatorWrites?: ReadonlyArray<MutatorWriteIR>) => Finding[];
 /**
 * Render advisor findings as a single multi-line string for console surfacing:
 * a one-line summary header followed by one `[LEVEL] name: detail` line per
@@ -898,6 +951,23 @@ declare const discoverMaskProcedures: (project: Project, lunoraDirectory: string
 * key); `table` is best-effort and left `""` when not a literal.
 */
 declare const discoverMigrations: (project: Project, lunoraDirectory: string) => MigrationIR[];
+/** The only file custom mutators may be declared in — mirrors `lunora/queues.ts`. */
+declare const MUTATORS_FILENAME = "mutators.ts";
+/**
+* Decide whether a call's callee is `defineMutator` — either the bare imported
+* identifier (`defineMutator(...)`) or a namespace member access
+* (`server.defineMutator(...)`). Both are valid ES module syntax, so discovery
+* must see mutators declared either way.
+*/
+
+/**
+* Discover every custom mutator the project declares: exported
+* `defineMutator()` calls in `lunora/mutators.ts`. Returns `[]` when the file
+* doesn't exist. Only the export binding is lifted — the runtime object carries
+* the authoritative `server` impl + `handler`, so codegen never evaluates the
+* body. The client `client` impl is split into the browser bundle separately.
+*/
+declare const discoverMutators: (project: Project, lunoraDirectory: string) => MutatorIR[];
 /**
 * Discover non-deterministic API calls (`Date.now`, `new Date()`, `Date()`,
 * `Math.random`, `crypto.randomUUID`, `crypto.getRandomValues` — including
@@ -963,6 +1033,16 @@ declare const discoverRlsMetadata: (project: Project, lunoraDirectory: string) =
 * return a structural IR. Throws if the file or call cannot be found.
 */
 declare const discoverSchema: (project: Project, schemaPath: string, projectRoot?: string) => SchemaIR;
+/** The only file shapes may be declared in — mirrors `lunora/queues.ts`. */
+declare const SHAPES_FILENAME = "shapes.ts";
+/**
+* Discover every replication shape the project declares: exported
+* `defineShape()` calls in `lunora/shapes.ts`. Returns `[]` when the file
+* doesn't exist. Only the export binding is lifted — the runtime object carries
+* the authoritative `table`/`columns`/`compileWhere`, so codegen never
+* evaluates the predicate.
+*/
+declare const discoverShapes: (project: Project, lunoraDirectory: string) => ShapeIR[];
 /**
 * Aggregate the schema-wide storage-rule metadata the studio's inspector reads:
 * every statically-discovered `(bucket, on, prefix, procedure)` entry across all
@@ -1001,6 +1081,22 @@ declare const emitApi: (functions: ReadonlyArray<FunctionIR>, workflows?: Readon
 * Returns `""` when `@lunora/seed` is not a declared dependency, so projects
 * that don't use it keep a clean `_generated/` and never import the package.
 */
+
+/**
+* Emit `_generated/collections.ts` — one TanStack DB collection factory per
+* `defineShape` in `lunora/shapes.ts` (the local-first partial-replication
+* surface). Each factory builds a live collection that syncs its shape's rowset
+* through the client's poke protocol (`subscribeShape`), so an app feeds the
+* result straight to `useLiveQuery`.
+*
+* Returns `""` (so `writeIfPresent` skips the file) unless the project both
+* declares shapes AND installs `@lunora/db` — the add-on that ships
+* `lunoraCollectionOptions`. `@lunora/db` stays a scoped install even under the
+* `lunorash` umbrella (an opt-in add-on, like `@lunora/auth`), so its import is
+* always `@lunora/db/collections`; only the in-umbrella `@lunora/client` import
+* is remapped to `lunorash/client`.
+*/
+declare const emitCollections: (shapes: ReadonlyArray<ShapeIR>, hasDatabase: boolean, useUmbrella?: boolean) => string;
 interface EmitServerOptions {
   containers?: ReadonlyArray<ContainerIR>;
   hasAi?: boolean;
@@ -1047,7 +1143,7 @@ declare const emitServer: ({
   useUmbrella,
   workflows
 }?: EmitServerOptions) => string;
-declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>, useUmbrella?: boolean) => string;
+declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>, useUmbrella?: boolean, mutators?: ReadonlyArray<MutatorIR>, shapes?: ReadonlyArray<ShapeIR>) => string;
 /**
 * Storage-column map per table for the file browser: `{ table: [field, …] }` for
 * every field declared `v.storage(...)` (unwrapping `v.optional(...)`). The
@@ -1110,10 +1206,14 @@ interface EmitShardOptions {
   /** A `lunora/` source reads `ctx.r2sql` (R2 SQL) — wires `ctx.r2sql` onto the ActionCtx only. */
   hasR2sql?: boolean;
   maskMetadata?: MaskMetadataIR;
+  /** Custom mutators declared via `defineMutator` in `lunora/mutators.ts` — wires the `isCustomMutator` push-protocol override. */
+  mutators?: ReadonlyArray<MutatorIR>;
   /** Queues declared via `defineQueue` exports in `lunora/queues.ts` — wires the typed `ctx.queues` producers. */
   queues?: ReadonlyArray<QueueIR>;
   rlsMetadata?: RlsMetadataIR;
   schema: SchemaIR;
+  /** Replication shapes declared via `defineShape` in `lunora/shapes.ts` — wires the `resolveShape` subscription override. */
+  shapes?: ReadonlyArray<ShapeIR>;
   storageRules?: StorageRulesMetadataIR;
   studioFeatures?: StudioFeaturesResult;
   /** The project depends on the `lunora` umbrella — import base packages via its subpaths. */
@@ -1135,9 +1235,11 @@ declare const emitShard: ({
   hasPipelines,
   hasR2sql,
   maskMetadata,
+  mutators,
   queues,
   rlsMetadata,
   schema,
+  shapes,
   storageRules,
   studioFeatures,
   useUmbrella,
@@ -1591,6 +1693,8 @@ interface CodegenResult {
   generated: {
     api: string; /** Fluent worker-composition builder (`_generated/app.ts`) — `defineApp()`. Always written. */
     app: string;
+    /** Partial-replication collection factories (`_generated/collections.ts`); `""` (and not written) unless the project declares shapes and installs `@lunora/db`. */
+    collections: string;
     /** Container DO classes (`_generated/containers.ts`); `""` (and not written) when no containers are declared. */
     containers: string;
     crons: string;
@@ -1725,4 +1829,4 @@ declare const LUNORA_SOLUTION_RULES: ReadonlyArray<LunoraSolutionRule>;
 */
 declare const findLunoraSolution: (message: string) => LunoraSolution | undefined;
 declare const VERSION = "0.0.0";
-export { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, LUNORA_SOLUTION_RULES, type LunoraSolution, type LunoraSolutionRule, type MaskProcedureIR, type MigrationIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverNondeterministicCalls, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, findLunoraSolution, formatAdvisories, lintSchema, parseSchemaSnapshot, refreshCodegenProject, runCodegen, schemaFromIr, serializeSchemaSnapshot, validatorIrToJsonSchema };
+export { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, LUNORA_SOLUTION_RULES, type LunoraSolution, type LunoraSolutionRule, MUTATORS_FILENAME, type MaskProcedureIR, type MigrationIR, type MutatorIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, SHAPES_FILENAME, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type ShapeIR, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverMutators, discoverNondeterministicCalls, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverShapes, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, findLunoraSolution, formatAdvisories, lintSchema, parseSchemaSnapshot, refreshCodegenProject, runCodegen, schemaFromIr, serializeSchemaSnapshot, validatorIrToJsonSchema };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { formatAdvisories, lintSchema } from './packem_shared/formatAdvisories-8NIv1k0I.mjs';
+export { formatAdvisories, lintSchema } from './packem_shared/formatAdvisories-LM8-Ixjw.mjs';
 export { CodegenDiagnosticError, diagnosticAt } from './packem_shared/CodegenDiagnosticError-DeblMkzO.mjs';
 export { default as discoverAuthApiCalls } from './packem_shared/discoverAuthApiCalls-CoirYbg6.mjs';
 export { CONTAINERS_FILENAME, discoverContainers } from './packem_shared/CONTAINERS_FILENAME-DlP6YM_Q.mjs';
@@ -9,19 +9,21 @@ export { default as discoverHttpRoutes } from './packem_shared/discoverHttpRoute
 export { default as discoverInserts } from './packem_shared/discoverInserts-C7zxXkUf.mjs';
 export { default as discoverMaskProcedures } from './packem_shared/discoverMaskProcedures-Cm81kwrb.mjs';
 export { default as discoverMigrations } from './packem_shared/discoverMigrations-Bi5nJ0mJ.mjs';
+export { MUTATORS_FILENAME, discoverMutators } from './packem_shared/MUTATORS_FILENAME-BhqdPtKp.mjs';
 export { default as discoverNondeterministicCalls } from './packem_shared/discoverNondeterministicCalls-C4M8AXmQ.mjs';
 export { default as discoverQueries } from './packem_shared/discoverQueries-B0wGT-xe.mjs';
 export { QUEUES_FILENAME, discoverQueues } from './packem_shared/QUEUES_FILENAME-B5_eWCRe.mjs';
 export { default as discoverR2sqlCalls } from './packem_shared/discoverR2sqlCalls-BVNMd428.mjs';
 export { discoverRlsMetadata, default as discoverRlsProcedures } from './packem_shared/discoverRlsMetadata-BS9GOGC5.mjs';
 export { default as discoverSchema } from './packem_shared/discoverSchema-BnWHHJ4T.mjs';
+export { SHAPES_FILENAME, discoverShapes } from './packem_shared/SHAPES_FILENAME-ChV7MqgE.mjs';
 export { default as discoverStorageRulesMetadata } from './packem_shared/discoverStorageRulesMetadata-Da8BKXcI.mjs';
 export { WORKFLOWS_FILENAME, discoverWorkflows } from './packem_shared/WORKFLOWS_FILENAME-D62dcBGg.mjs';
-export { GENERATED_HEADER, emitApi, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers } from './packem_shared/GENERATED_HEADER-CkZUgM4_.mjs';
-export { emitApp } from './packem_shared/emitApp-DGmlt5fq.mjs';
-export { buildOpenApiDocument, emitOpenApi, emitOpenApiModule } from './packem_shared/buildOpenApiDocument-BSoDzIn8.mjs';
-export { OPENRPC_VERSION, buildOpenRpcDocument, emitOpenRpc, emitOpenRpcModule } from './packem_shared/OPENRPC_VERSION-VINwUAxf.mjs';
-export { SCHEMA_SNAPSHOT_FILENAME, createCodegenProject, refreshCodegenProject, runCodegen } from './packem_shared/SCHEMA_SNAPSHOT_FILENAME-DsBxQ5C_.mjs';
+export { GENERATED_HEADER, emitApi, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers } from './packem_shared/GENERATED_HEADER-BoVKLcnE.mjs';
+export { emitApp } from './packem_shared/emitApp-Bh0HsQVK.mjs';
+export { buildOpenApiDocument, emitOpenApi, emitOpenApiModule } from './packem_shared/buildOpenApiDocument-CB2brlbc.mjs';
+export { OPENRPC_VERSION, buildOpenRpcDocument, emitOpenRpc, emitOpenRpcModule } from './packem_shared/OPENRPC_VERSION-BMCOe3B6.mjs';
+export { SCHEMA_SNAPSHOT_FILENAME, createCodegenProject, refreshCodegenProject, runCodegen } from './packem_shared/SCHEMA_SNAPSHOT_FILENAME-BA9tjjOl.mjs';
 export { SCHEMA_SNAPSHOT_VERSION, SchemaSnapshotParseError, buildSchemaSnapshot, diffSchemaSnapshots, evaluateSchemaDrift, parseSchemaSnapshot, serializeSchemaSnapshot } from './packem_shared/SCHEMA_SNAPSHOT_VERSION-wWGP2_5E.mjs';
 export { schemaFromIr } from './packem_shared/schemaFromIr-DTYsLBaA.mjs';
 export { LUNORA_ERROR_CODES, validatorIrToJsonSchema } from './packem_shared/LUNORA_ERROR_CODES-CySpQPD3.mjs';

package/dist/packem_shared/{GENERATED_HEADER-CkZUgM4_.mjs → GENERATED_HEADER-BoVKLcnE.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}
 ` : ""
   };
 };
@@ -984,11 +1020,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 +1068,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 +1094,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
@@ -1910,15 +1965,19 @@ 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 kvFragments = emitKvFragments(hasKv);
   const flagsFragments = emitFlagsFragments(hasFlags);
@@ -1980,15 +2039,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}";`);
@@ -2017,7 +2140,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 +2267,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>>;
@@ -2211,7 +2367,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 +2482,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 +2533,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 +3109,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-BMCOe3B6.mjs}

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

package/dist/packem_shared/{SCHEMA_SNAPSHOT_FILENAME-DsBxQ5C_.mjs → SCHEMA_SNAPSHOT_FILENAME-BA9tjjOl.mjs}

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { Node, SyntaxKind, Project } from 'ts-morph';
-import { lintSchema } from './formatAdvisories-8NIv1k0I.mjs';
+import { lintSchema } from './formatAdvisories-LM8-Ixjw.mjs';
 import { listLunoraSourceFiles, lunoraRelativePath, classifyProcedureCall, discoverFunctions } from './discoverFunctions-BWMczzBx.mjs';
 import discoverAuthApiCalls from './discoverAuthApiCalls-CoirYbg6.mjs';
 import { discoverContainers } from './CONTAINERS_FILENAME-DlP6YM_Q.mjs';
@@ -12,19 +12,21 @@ import discoverHttpRoutes from './discoverHttpRoutes-CfP6cMzt.mjs';
 import discoverInserts from './discoverInserts-C7zxXkUf.mjs';
 import discoverMaskProcedures, { discoverMaskMetadata } from './discoverMaskProcedures-Cm81kwrb.mjs';
 import discoverMigrations from './discoverMigrations-Bi5nJ0mJ.mjs';
+import { MUTATORS_FILENAME, isDefineMutatorCallee, discoverMutators } from './MUTATORS_FILENAME-BhqdPtKp.mjs';
 import discoverNondeterministicCalls from './discoverNondeterministicCalls-C4M8AXmQ.mjs';
 import discoverQueries from './discoverQueries-B0wGT-xe.mjs';
 import { discoverQueues } from './QUEUES_FILENAME-B5_eWCRe.mjs';
 import discoverR2sqlCalls from './discoverR2sqlCalls-BVNMd428.mjs';
 import discoverRlsProcedures, { discoverRlsMetadata } from './discoverRlsMetadata-BS9GOGC5.mjs';
 import discoverSchema from './discoverSchema-BnWHHJ4T.mjs';
+import { discoverShapes } from './SHAPES_FILENAME-ChV7MqgE.mjs';
 import discoverStorageRulesMetadata from './discoverStorageRulesMetadata-Da8BKXcI.mjs';
 import { e as enclosingExportName$1 } from './discover-ast-CT6BgBr4.mjs';
 import { discoverWorkflows } from './WORKFLOWS_FILENAME-D62dcBGg.mjs';
-import { buildStorageColumns, emitDataModel, emitApi, emitServer, emitFunctions, emitShard, emitContainers, emitWorkflows, emitQueues, emitCrons, emitVectors, emitDrizzleSchema, emitSeed, emitWranglerCronTriggers } from './GENERATED_HEADER-CkZUgM4_.mjs';
-import { emitApp } from './emitApp-DGmlt5fq.mjs';
-import { buildOpenApiDocument, emitOpenApiModule } from './buildOpenApiDocument-BSoDzIn8.mjs';
-import { buildOpenRpcDocument, emitOpenRpcModule } from './OPENRPC_VERSION-VINwUAxf.mjs';
+import { buildStorageColumns, emitDataModel, emitApi, emitServer, emitFunctions, emitShard, emitCollections, emitContainers, emitWorkflows, emitQueues, emitCrons, emitVectors, emitDrizzleSchema, emitSeed, emitWranglerCronTriggers } from './GENERATED_HEADER-BoVKLcnE.mjs';
+import { emitApp } from './emitApp-Bh0HsQVK.mjs';
+import { buildOpenApiDocument, emitOpenApiModule } from './buildOpenApiDocument-CB2brlbc.mjs';
+import { buildOpenRpcDocument, emitOpenRpcModule } from './OPENRPC_VERSION-BMCOe3B6.mjs';
 import { buildSchemaSnapshot, serializeSchemaSnapshot } from './SCHEMA_SNAPSHOT_VERSION-wWGP2_5E.mjs';
 
 const HTTP_VERBS = /* @__PURE__ */ new Set(["delete", "get", "head", "options", "patch", "post", "put"]);
@@ -329,6 +331,61 @@ const buildStudioFeatures = (usage, signals) => {
   };
 };
 
+const isDatabaseReplaceCall = (call) => {
+  const callee = call.getExpression();
+  if (!Node.isPropertyAccessExpression(callee) || callee.getName() !== "replace") {
+    return false;
+  }
+  const receiver = callee.getExpression();
+  if (Node.isPropertyAccessExpression(receiver)) {
+    return receiver.getName() === "db";
+  }
+  return Node.isIdentifier(receiver) && receiver.getText() === "db";
+};
+const serverImplNode = (call) => {
+  const argument = call.getArguments()[0];
+  if (argument === void 0 || !Node.isObjectLiteralExpression(argument)) {
+    return void 0;
+  }
+  const property = argument.getProperty("server");
+  if (property === void 0) {
+    return void 0;
+  }
+  return Node.isPropertyAssignment(property) ? property.getInitializer() : property;
+};
+const exportedDefineMutatorCall = (declaration) => {
+  if (!declaration.isExported()) {
+    return void 0;
+  }
+  const initializer = declaration.getInitializer();
+  if (initializer?.getKind() !== SyntaxKind.CallExpression) {
+    return void 0;
+  }
+  const call = initializer;
+  return isDefineMutatorCallee(call.getExpression()) ? call : void 0;
+};
+const writesFromDeclaration = (declaration) => {
+  const call = exportedDefineMutatorCall(declaration);
+  const serverImpl = call === void 0 ? void 0 : serverImplNode(call);
+  if (serverImpl === void 0) {
+    return [];
+  }
+  const nameNode = declaration.getNameNode();
+  const exportName = Node.isIdentifier(nameNode) ? nameNode.getText() : "";
+  return serverImpl.getDescendantsOfKind(SyntaxKind.CallExpression).filter((replaceCall) => isDatabaseReplaceCall(replaceCall)).map((replaceCall) => {
+    return { exportName, file: "lunora/mutators.ts", line: replaceCall.getStartLineNumber() };
+  });
+};
+const mutatorWritesFromSource = (source) => source.getVariableDeclarations().flatMap((declaration) => writesFromDeclaration(declaration));
+const discoverMutatorWrites = (project, lunoraDirectory) => {
+  const mutatorsPath = join(lunoraDirectory, MUTATORS_FILENAME);
+  if (!existsSync(mutatorsPath)) {
+    return [];
+  }
+  const source = project.getSourceFile(mutatorsPath) ?? project.addSourceFileAtPath(mutatorsPath);
+  return mutatorWritesFromSource(source);
+};
+
 const discoverPackageDependencies = (projectRoot) => {
   const manifestPath = join(projectRoot, "package.json");
   if (!existsSync(manifestPath)) {
@@ -743,6 +800,8 @@ const runCodegen = (options) => {
   const functions = discoverFunctions(project, lunoraDirectory);
   const httpRoutes = discoverHttpRoutes(project, lunoraDirectory);
   const migrations = discoverMigrations(project, lunoraDirectory);
+  const shapes = discoverShapes(project, lunoraDirectory);
+  const mutators = discoverMutators(project, lunoraDirectory);
   const workflows = discoverWorkflows(project, lunoraDirectory);
   const queues = discoverQueues(project, lunoraDirectory);
   const crons = discoverCrons(project, lunoraDirectory, workflows);
@@ -763,7 +822,9 @@ const runCodegen = (options) => {
     discoverSecrets(project, lunoraDirectory),
     discoverSqlInterpolation(project, lunoraDirectory),
     discoverAdminRoutes(project, lunoraDirectory),
-    discoverR2sqlCalls(project, lunoraDirectory)
+    discoverR2sqlCalls(project, lunoraDirectory),
+    shapes,
+    discoverMutatorWrites(project, lunoraDirectory)
   );
   const rlsMetadata = discoverRlsMetadata(project, lunoraDirectory);
   const maskMetadata = discoverMaskMetadata(project, lunoraDirectory);
@@ -812,7 +873,7 @@ const runCodegen = (options) => {
     useUmbrella,
     workflows
   });
-  const functionsContent = emitFunctions(functions, migrations, useUmbrella);
+  const functionsContent = emitFunctions(functions, migrations, useUmbrella, mutators, shapes);
   const shardContent = emitShard({
     advisories,
     containers,
@@ -828,14 +889,17 @@ const runCodegen = (options) => {
     hasPipelines,
     hasR2sql,
     maskMetadata,
+    mutators,
     queues,
     rlsMetadata,
     schema,
+    shapes,
     storageRules: storageRulesMetadata,
     studioFeatures,
     useUmbrella,
     workflows
   });
+  const collectionsContent = emitCollections(shapes, dependencies.has("@lunora/db"), useUmbrella);
   const containersContent = emitContainers(containers, schema.jurisdiction);
   const workflowsContent = emitWorkflows(workflows);
   const queuesContent = emitQueues(queues);
@@ -909,6 +973,7 @@ const runCodegen = (options) => {
     writeIfPresent(join(outputDirectory, "workflows.ts"), workflowsContent);
     writeIfPresent(join(outputDirectory, "queues.ts"), queuesContent);
     writeIfPresent(join(outputDirectory, "seed.ts"), seedContent);
+    writeIfPresent(join(outputDirectory, "collections.ts"), collectionsContent);
     if (wantsOpenApi) {
       writeIfChanged(join(outputDirectory, "openapi.json"), openApiContent);
       writeIfChanged(join(outputDirectory, "openapi.ts"), openApiModuleContent);
@@ -935,6 +1000,7 @@ const runCodegen = (options) => {
     generated: {
       api: apiContent,
       app: appContent,
+      collections: collectionsContent,
       containers: containersContent,
       crons: cronsContent,
       dataModel: dataModelContent,

package/dist/packem_shared/SHAPES_FILENAME-ChV7MqgE.mjs

@@ -0,0 +1,94 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { SyntaxKind, Node } from 'ts-morph';
+import { diagnosticAt } from './CodegenDiagnosticError-DeblMkzO.mjs';
+
+const SHAPES_FILENAME = "shapes.ts";
+const SHAPE_MODULE_SPECIFIERS = /* @__PURE__ */ new Set(["@lunora/server", "lunorash/server"]);
+const isDefineShape = (identifier) => {
+  const symbol = identifier.getSymbol();
+  if (!symbol) {
+    return identifier.getText() === "defineShape";
+  }
+  for (const declaration of symbol.getDeclarations()) {
+    if (!Node.isImportSpecifier(declaration)) {
+      continue;
+    }
+    if (!SHAPE_MODULE_SPECIFIERS.has(declaration.getImportDeclaration().getModuleSpecifierValue())) {
+      return false;
+    }
+    return declaration.getNameNode().getText() === "defineShape";
+  }
+  return false;
+};
+const isShapeNamespaceImport = (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 && SHAPE_MODULE_SPECIFIERS.has(importDeclaration.getModuleSpecifierValue());
+  }
+  return false;
+};
+const isDefineShapeCallee = (callee) => {
+  if (Node.isIdentifier(callee)) {
+    return isDefineShape(callee);
+  }
+  if (Node.isPropertyAccessExpression(callee)) {
+    const object = callee.getExpression();
+    return callee.getName() === "defineShape" && Node.isIdentifier(object) && isShapeNamespaceImport(object);
+  }
+  return false;
+};
+const tableLiteralFrom = (call) => {
+  const [config] = call.getArguments();
+  if (!config || !Node.isObjectLiteralExpression(config)) {
+    return void 0;
+  }
+  const tableProperty = config.getProperty("table");
+  if (!tableProperty || !Node.isPropertyAssignment(tableProperty)) {
+    return void 0;
+  }
+  const value = tableProperty.getInitializer();
+  return value && Node.isStringLiteral(value) ? value.getLiteralValue() : void 0;
+};
+const shapesFromSource = (source) => {
+  const shapes = [];
+  for (const declaration of source.getVariableDeclarations()) {
+    if (!declaration.isExported()) {
+      continue;
+    }
+    const initializer = declaration.getInitializer();
+    if (initializer?.getKind() !== SyntaxKind.CallExpression) {
+      continue;
+    }
+    const callExpression = initializer;
+    const callee = callExpression.getExpression();
+    if (!isDefineShapeCallee(callee)) {
+      continue;
+    }
+    const nameNode = declaration.getNameNode();
+    if (!Node.isIdentifier(nameNode)) {
+      throw diagnosticAt(nameNode, "defineShape exports must be plain named exports (no destructuring)");
+    }
+    shapes.push({ exportName: nameNode.getText(), filePath: "shapes", table: tableLiteralFrom(callExpression) });
+  }
+  return shapes;
+};
+const discoverShapes = (project, lunoraDirectory) => {
+  const shapesPath = join(lunoraDirectory, SHAPES_FILENAME);
+  if (!existsSync(shapesPath)) {
+    return [];
+  }
+  const source = project.getSourceFile(shapesPath) ?? project.addSourceFileAtPath(shapesPath);
+  const shapes = shapesFromSource(source);
+  shapes.sort((a, b) => a.exportName.localeCompare(b.exportName));
+  return shapes;
+};
+
+export { SHAPES_FILENAME, discoverShapes };

package/dist/packem_shared/{buildOpenApiDocument-BSoDzIn8.mjs → buildOpenApiDocument-CB2brlbc.mjs}

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

package/dist/packem_shared/{emitApp-DGmlt5fq.mjs → emitApp-Bh0HsQVK.mjs}

@@ -1,4 +1,4 @@
-import { GENERATED_HEADER } from './GENERATED_HEADER-CkZUgM4_.mjs';
+import { GENERATED_HEADER } from './GENERATED_HEADER-BoVKLcnE.mjs';
 
 const LONG_TAIL = [
   ["hasAi", "ai", "ai", "Override the Workers AI binding backing `ctx.ai` (defaults to `env.AI`)."],

package/dist/packem_shared/{formatAdvisories-8NIv1k0I.mjs → formatAdvisories-LM8-Ixjw.mjs}

@@ -31,12 +31,16 @@ const toAdvisorSchema = (schema) => {
             references: relation.references,
             table: relation.table
           };
-        })
+        }),
+        shardKind: typeof table.shardMode === "string" ? table.shardMode : "shardBy"
       };
     })
   };
 };
-const lintSchema = (schema, queries = [], inserts, authApiCalls, rlsProcedures, containers, workflows, workflowCalls, maskProcedures, nondeterministicCalls, procedureProtections, argumentValidators, secretLiterals, sqlInterpolations, adminRoutes, r2sqlCalls) => runAdvisor(
+const toAdvisorShapes = (shapes) => shapes.map((shape) => {
+  return { exportName: shape.exportName, file: `lunora/${shape.filePath}.ts`, table: shape.table };
+});
+const lintSchema = (schema, queries = [], inserts, authApiCalls, rlsProcedures, containers, workflows, workflowCalls, maskProcedures, nondeterministicCalls, procedureProtections, argumentValidators, secretLiterals, sqlInterpolations, adminRoutes, r2sqlCalls, shapes, mutatorWrites) => runAdvisor(
   {
     adminRoutes,
     argValidators: argumentValidators,
@@ -44,6 +48,7 @@ const lintSchema = (schema, queries = [], inserts, authApiCalls, rlsProcedures,
     containers,
     inserts,
     maskProcedures,
+    mutatorWrites,
     nondeterministicCalls,
     procedureProtections,
     queries,
@@ -51,6 +56,7 @@ const lintSchema = (schema, queries = [], inserts, authApiCalls, rlsProcedures,
     rlsProcedures,
     schema: toAdvisorSchema(schema),
     secretLiterals,
+    shapes: shapes === void 0 ? void 0 : toAdvisorShapes(shapes),
     sqlInterpolations,
     workflowCalls,
     workflows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/codegen",
-  "version": "1.0.0-alpha.15",
+  "version": "1.0.0-alpha.17",
   "description": "Code generator for Lunora: emits _generated/{api,server,dataModel}.ts from your schema",
   "keywords": [
     "cloudflare",
@@ -46,8 +46,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/advisor": "1.0.0-alpha.7",
-    "@lunora/container": "1.0.0-alpha.4",
+    "@lunora/advisor": "1.0.0-alpha.8",
+    "@lunora/container": "1.0.0-alpha.5",
     "@lunora/queue": "1.0.0-alpha.1",
     "@lunora/scheduler": "1.0.0-alpha.3",
     "@lunora/values": "1.0.0-alpha.3",