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

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,8 +1081,31 @@ 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>;
+  /**
+  * A `lunora/` source reads `ctx.access` — wires the verified Cloudflare Access
+  * facade (`@lunora/cloudflare-access/context`) onto every ctx. Distinct from
+  * `emitApp`'s `hasAccess` (which gates the worker's `.access()` resolveIdentity
+  * method); this one gates the per-request `ctx.access` read surface.
+  */
+  hasAccessFacade?: boolean;
   hasAi?: boolean;
   /** A `lunora/` source uses `@lunora/bindings/analytics` / `ctx.analytics` — wires the write helper onto every ctx. */
   hasAnalytics?: boolean;
@@ -1031,6 +1134,7 @@ interface EmitServerOptions {
 }
 declare const emitServer: ({
   containers,
+  hasAccessFacade,
   hasAi,
   hasAnalytics,
   hasBrowser,
@@ -1047,7 +1151,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
@@ -1091,6 +1195,8 @@ interface EmitShardOptions {
     key: string;
     type: "boolean" | "number" | "object" | "string";
   }>;
+  /** A `lunora/` source reads `ctx.access` — wires the verified Cloudflare Access facade onto every ctx. */
+  hasAccessFacade?: boolean;
   hasAi?: boolean;
   /** A `lunora/` source reads `ctx.analytics` — wires the Analytics Engine write helper onto every ctx. */
   hasAnalytics?: boolean;
@@ -1110,10 +1216,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. */
@@ -1124,6 +1234,7 @@ declare const emitShard: ({
   advisories,
   containers,
   flagKeys,
+  hasAccessFacade,
   hasAi,
   hasAnalytics,
   hasBrowser,
@@ -1135,9 +1246,11 @@ declare const emitShard: ({
   hasPipelines,
   hasR2sql,
   maskMetadata,
+  mutators,
   queues,
   rlsMetadata,
   schema,
+  shapes,
   storageRules,
   studioFeatures,
   useUmbrella,
@@ -1202,6 +1315,8 @@ declare const emitVectors: (vectorIndexes: ReadonlyArray<VectorIndexIR>) => stri
 declare const emitWranglerCronTriggers: (crons: ReadonlyArray<CronJobIR>) => string[];
 /** Which capability methods the generated `defineApp` builder exposes — one flag per package-backed feature the app actually uses. */
 interface EmitAppOptions {
+  /** App depends on `@lunora/cloudflare-access` → emit `.access()` (wire the Cloudflare Access `resolveIdentity`, composed ahead of `@lunora/auth` when both are present). */
+  hasAccess: boolean;
   /** App uses `@lunora/ai` / `ctx.ai` → emit `.ai()` (override the Workers AI binding backing `ctx.ai`). */
   hasAi: boolean;
   /** App uses `@lunora/bindings/analytics` / `ctx.analytics` → emit `.analytics()` (override the dataset backing `ctx.analytics`). */
@@ -1591,6 +1706,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 +1842,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,8 +1081,31 @@ 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>;
+  /**
+  * A `lunora/` source reads `ctx.access` — wires the verified Cloudflare Access
+  * facade (`@lunora/cloudflare-access/context`) onto every ctx. Distinct from
+  * `emitApp`'s `hasAccess` (which gates the worker's `.access()` resolveIdentity
+  * method); this one gates the per-request `ctx.access` read surface.
+  */
+  hasAccessFacade?: boolean;
   hasAi?: boolean;
   /** A `lunora/` source uses `@lunora/bindings/analytics` / `ctx.analytics` — wires the write helper onto every ctx. */
   hasAnalytics?: boolean;
@@ -1031,6 +1134,7 @@ interface EmitServerOptions {
 }
 declare const emitServer: ({
   containers,
+  hasAccessFacade,
   hasAi,
   hasAnalytics,
   hasBrowser,
@@ -1047,7 +1151,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
@@ -1091,6 +1195,8 @@ interface EmitShardOptions {
     key: string;
     type: "boolean" | "number" | "object" | "string";
   }>;
+  /** A `lunora/` source reads `ctx.access` — wires the verified Cloudflare Access facade onto every ctx. */
+  hasAccessFacade?: boolean;
   hasAi?: boolean;
   /** A `lunora/` source reads `ctx.analytics` — wires the Analytics Engine write helper onto every ctx. */
   hasAnalytics?: boolean;
@@ -1110,10 +1216,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. */
@@ -1124,6 +1234,7 @@ declare const emitShard: ({
   advisories,
   containers,
   flagKeys,
+  hasAccessFacade,
   hasAi,
   hasAnalytics,
   hasBrowser,
@@ -1135,9 +1246,11 @@ declare const emitShard: ({
   hasPipelines,
   hasR2sql,
   maskMetadata,
+  mutators,
   queues,
   rlsMetadata,
   schema,
+  shapes,
   storageRules,
   studioFeatures,
   useUmbrella,
@@ -1202,6 +1315,8 @@ declare const emitVectors: (vectorIndexes: ReadonlyArray<VectorIndexIR>) => stri
 declare const emitWranglerCronTriggers: (crons: ReadonlyArray<CronJobIR>) => string[];
 /** Which capability methods the generated `defineApp` builder exposes — one flag per package-backed feature the app actually uses. */
 interface EmitAppOptions {
+  /** App depends on `@lunora/cloudflare-access` → emit `.access()` (wire the Cloudflare Access `resolveIdentity`, composed ahead of `@lunora/auth` when both are present). */
+  hasAccess: boolean;
   /** App uses `@lunora/ai` / `ctx.ai` → emit `.ai()` (override the Workers AI binding backing `ctx.ai`). */
   hasAi: boolean;
   /** App uses `@lunora/bindings/analytics` / `ctx.analytics` → emit `.analytics()` (override the dataset backing `ctx.analytics`). */
@@ -1591,6 +1706,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 +1842,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-D-AbhmRh.mjs';
+export { emitApp } from './packem_shared/emitApp-CV81L74c.mjs';
+export { buildOpenApiDocument, emitOpenApi, emitOpenApiModule } from './packem_shared/buildOpenApiDocument-DoK7_x1g.mjs';
+export { OPENRPC_VERSION, buildOpenRpcDocument, emitOpenRpc, emitOpenRpcModule } from './packem_shared/OPENRPC_VERSION-DDT4mIzD.mjs';
+export { SCHEMA_SNAPSHOT_FILENAME, createCodegenProject, refreshCodegenProject, runCodegen } from './packem_shared/SCHEMA_SNAPSHOT_FILENAME-ExbveiC6.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';