@lunora/codegen 1.0.0-alpha.26 → 1.0.0-alpha.261

package/dist/packem_shared/shard-WXSIZRpD.mjs

@@ -0,0 +1,1438 @@
+import{LunoraError as vt}from"@lunora/errors";import{serializeSchemaSnapshot as kt,hashSchemaSnapshot as St}from"./SCHEMA_SNAPSHOT_VERSION-C0oHwiJZ.mjs";import{isHyperdriveGlobalTable as Rt,isD1GlobalTable as xt}from"./isD1GlobalTable-udvHAAzD.mjs";import{p as At,i as Dt}from"./ir-DBSvhNa-.mjs";import{r as h}from"./json-data-Chfs2Cz5.mjs";import{r as C,e as Tt,a as Ot,b as Et,c as Ct,d as Lt,f as It,g as _t,h as Mt,i as Pt,j as qt,k as Nt,l as $t,m as Ft,n as Ut,o as Bt,p as Wt,q as jt}from"./shard-runtime-B1nU9CRa.mjs";import{u as K,i as Ht,G as Vt,d as Kt}from"./shared-BXUKWh7t.mjs";const Gt=`        /**
+         * The bare writer every admin/maintenance entry point writes through.
+         *
+         * Admin and maintenance writes go through the SAME reactive-cache hooks as a
+         * user mutation. Without this, a studio row edit, a TTL sweep, an admin
+         * import, a CDC apply or a data-migration backfill writes without
+         * invalidating, and the next query answers from the pre-write snapshot.
+         *
+         * \`headroom\` meters the transaction. An admin \`/rpc\` caller passes nothing
+         * and falls back to \`this.transactionHeadroom()\`, which for an admin RPC is
+         * \`undefined\` — \`handleAdminRpc\` answers before \`beginDispatch\`, so no
+         * per-dispatch meter is in flight and a bulk loop is bounded by its per-call
+         * row cap alone. The TTL sweep (an alarm work item, no dispatch) passes its
+         * own by-value tracker explicitly instead.
+         */
+        private adminWriter(headroom?: TransactionHeadroomTracker): DatabaseWriterLike {
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            const scheduler = (config.scheduler?.(env) ?? schedulerStub) as SchedulerLike;
+
+            return createShardCtxDb({
+                ...this.ctxDbTuning(),
+                broadcast: (delta) => {
+                    this.recordChangedTable(delta.table, delta.indexKeys);
+                },
+                cdc: config.cdc ?? false,
+                headroom,
+                // Live predicate, same as the user-facing ctx — see \`databaseOptions\`.
+                inTransaction: () => this.isInTransaction(),
+                scheduler,
+                schema: schema as unknown as SchemaLike,
+                sql: this.sql as SqlExec,
+            });
+        }`,p=(a="")=>`            const writer = this.adminWriter(${a});`,Qt=`${Gt}
+
+        protected override async runShardDataMigration(args: RunShardMigrationArgs): Promise<MigrationRunResult> {
+            this.ensureMigrated();
+
+            // Falls back to the framework's reserved re-projection backfill
+            // (\`__lunora_reproject__<table>\`), which rewrites rows whose
+            // v.bigint()/v.bytes() columns are still stored in the pre-projection
+            // tagged form. Built here rather than at module scope because it
+            // needs this shard's \`sql\` handle to tell a legacy row from a
+            // current one.
+            const migration = LUNORA_MIGRATIONS[args.id] ?? buildReprojectionMigration(args.id, schema as unknown as SchemaLike, this.sql as SqlExec);
+
+            if (!migration) {
+                throw new LunoraError("MIGRATION_NOT_FOUND", \`data migration "\${args.id}" is not registered\`, { status: 404 });
+            }
+
+${p()}
+
+            return runDataMigration({
+                batchSize: args.batchSize,
+                direction: args.direction,
+                dryRun: args.dryRun,
+                maxBatches: args.maxBatches,
+                migration: migration as unknown as DataMigrationLike,
+                // Flush after each batch so live migrationStatus subscribers see
+                // progress mid-run (the base method records the reserved state
+                // table the raw-SQL progress write is invisible to the tracker).
+                onBatch: () => this.flushMigrationProgress(),
+                sql: this.sql as SqlExec,
+                writer,
+            });
+        }
+
+        protected override async runShardWrite(args: RunShardWriteArgs, headroom?: TransactionHeadroomTracker): Promise<RunShardWriteResult> {
+            const definition = (schema as unknown as SchemaLike).tables[args.table];
+
+            if (!definition) {
+                throw new LunoraError("UNKNOWN_TABLE", \`unknown table: \${args.table}\`, { status: 404 });
+            }
+
+            // \`.global()\` tables live in D1, not this DO's SQLite — editing them
+            // here would corrupt nothing but would fail confusingly, so reject up
+            // front with a clear code the studio can surface.
+            if (definition.shardMode?.kind === "global") {
+                throw new LunoraError("GLOBAL_TABLE_NOT_EDITABLE", \`table "\${args.table}" is global; edit it through D1, not the shard\`, { status: 400 });
+            }
+
+            this.ensureMigrated();
+
+${p("headroom ?? this.transactionHeadroom()")}
+
+            if (args.op === "insert") {
+                const id = await writer.insert(args.table, args.doc ?? {});
+
+                return { id, op: "insert" };
+            }
+
+            // Every by-id op PINS \`args.table\`. Unpinned, \`locateRowById\` probes
+            // every non-global table for the id, so a request naming table A with an
+            // id belonging to table B locates and mutates B's row — the by-id IDOR
+            // the per-table \`ctx.db.<table>\` facade pins against. Pinning also stops
+            // an absent row falling through to the \`.global()\` D1 twin, though that
+            // branch is already unreachable here: \`adminWriter\` is built without a
+            // \`globalDb\`, so a miss throws \`NOT_FOUND\` either way.
+            // \`hard\` is set only by the BULK delete arm, which needs the row gone
+            // from the physical table for its next batch's scan to make progress.
+            // A single-row \`writeRow\` delete never carries it, so it keeps the
+            // table's declared \`.softDelete()\` behaviour.
+            if (args.op === "delete") {
+                await writer.delete(args.id ?? "", args.table, { hard: args.hard === true });
+
+                return { id: args.id ?? null, op: "delete" };
+            }
+
+            if (args.op === "replace") {
+                await writer.replace(args.id ?? "", args.doc ?? {}, args.table);
+
+                return { id: args.id ?? null, op: "replace" };
+            }
+
+            await writer.patch(args.id ?? "", args.doc ?? {}, args.table);
+
+            return { id: args.id ?? null, op: "patch" };
+        }
+
+        // The base \`ShardDO\` cannot build a schema-aware writer, so its
+        // \`runShardExport\`/\`runShardImport\` return \`[]\` and \`{inserted:{}}\`.
+        // Those are success-shaped: an empty export is what a correct export of
+        // an empty shard looks like, so a backup of a populated sharded schema
+        // reported success and wrote nothing, and an import reported success and
+        // dropped every row. Overriding both here is what makes the two admin
+        // RPCs real for a \`.shardBy()\` table.
+        //
+        // NOTE: the admin export RPC is not paginated — \`parseExportShardArgs\`
+        // takes \`tables\`/\`batchSize\` but no cursor, and the coordinator issues
+        // one call per shard — so the rows are collected into a single response.
+        // \`batchSize\` bounds the SQLite scan page, not the reply. A shard holding
+        // more rows than fit in the DO's memory budget will therefore fail the
+        // export rather than stream it. That is a loud failure where the bug this
+        // replaces was a silent empty one, but a cursor on the RPC is what makes
+        // this a complete backup path for large shards.
+        protected override async runShardExport(args: RunShardExportArgs): Promise<ExportRow[]> {
+            this.ensureMigrated();
+
+${p()}
+
+            const rows: ExportRow[] = [];
+
+            // \`exportShardRows\` walks in keyset batches so a large table does not
+            // materialize at once inside the generator; the admin RPC's response
+            // is a single array, so it is collected here rather than streamed.
+            for await (const row of exportShardRows(writer, schema as unknown as SchemaLike, { batchSize: args.batchSize, tables: args.tables })) {
+                rows.push(row);
+            }
+
+            return rows;
+        }
+
+        protected override async runShardImport(args: RunShardImportArgs): Promise<ImportShardResult> {
+            this.ensureMigrated();
+
+${p()}
+
+            // \`importShardRows\` inserts with \`allowExplicitId\`, so a source
+            // database's \`_id\`s carry across verbatim and every foreign key
+            // referencing them stays valid without a second remapping pass.
+            return importShardRows(writer, schema as unknown as SchemaLike, { rows: args.rows, startLine: args.startLine });
+        }
+
+        protected override async runShardRankBefore(args: RunShardRankBeforeArgs): Promise<{ before: number; total: number }> {
+            this.ensureMigrated();
+
+${p()}
+
+            // \`rankBefore\` is optional on \`DatabaseWriterLike\` (the D1 twin omits it),
+            // but the shard writer from \`createShardCtxDb\` always defines it.
+            if (!writer.rankBefore) {
+                throw new LunoraError("NOT_IMPLEMENTED", "rankBefore is unavailable on the shard writer", { status: 500 });
+            }
+
+            return writer.rankBefore(args.table, args.index, {
+                partitionKey: args.partitionKey,
+                rowId: args.rowId,
+                sortValues: args.sortValues,
+            });
+        }
+
+        protected override async runShardFindRelated(args: RunShardFindRelatedArgs): Promise<RelatedPage> {
+            this.ensureMigrated();
+
+${p()}
+
+            // \`related\` is optional on \`DatabaseWriterLike\` (the D1 twin omits it),
+            // but the shard writer from \`createShardCtxDb\` always defines it — it
+            // derives the edge set from this app's schema.
+            if (!writer.related) {
+                throw new LunoraError("NOT_IMPLEMENTED", "findRelated is unavailable on the shard writer", { status: 500 });
+            }
+
+            return writer.related(
+                { id: args.id, table: args.table },
+                { cursor: args.cursor, depth: args.depth, direction: args.direction, edges: args.edges, limit: args.limit },
+            );
+        }
+
+        protected override async runShardRankPage(args: RunShardRankPageArgs): Promise<ShardRankPageResult> {
+            this.ensureMigrated();
+
+${p()}
+
+            // \`rankPageRows\` is optional on \`DatabaseWriterLike\` (the D1 twin omits it),
+            // but the shard writer from \`createShardCtxDb\` always defines it. The sort
+            // directions live in the schema's rankIndex, so the shard reads them itself;
+            // \`args.directions\` is only the coordinator's comparator hint and isn't forwarded.
+            if (!writer.rankPageRows) {
+                throw new LunoraError("NOT_IMPLEMENTED", "rankPage is unavailable on the shard writer", { status: 500 });
+            }
+
+            return writer.rankPageRows(args.table, args.index, {
+                after: args.after,
+                cursor: args.cursor,
+                partitionKey: args.partitionKey,
+                take: args.take,
+            });
+        }
+
+        protected override async runShardApplyCdc(args: RunShardApplyCdcArgs): Promise<{ applied: number }> {
+            this.ensureMigrated();
+
+${p()}
+
+            await applyCdcChanges(writer, args.changes);
+
+            return { applied: args.changes.length };
+        }`,zt=({actionOnlyBuild:a,actionOnlyFields:r,agentsBuild:e,agentsContextField:n,containersBuild:t,containersContextField:o,databaseOptions:d,everyContextBuild:m,everyContextField:f,facadeBlock:c,globalDatabaseLine:w,notifyBuild:S,ormContextField:y,paymentsBuild:L,paymentsContextField:i,queuesBuild:g,queuesContextField:I,topicsBuild:_,topicsContextField:M,vectorsBuild:A,vectorsContextField:P,workflowsBuild:q,workflowsContextField:R})=>{const l=r.length>0,D=l?`
+            // ActionCtx-only helpers (external, non-deterministic I/O): constructed
+            // and attached only for an \`action\` so query/mutation ctx never carry them.
+            if (isAction) {
+${a.replaceAll(/^(?=.)/gmu,"    ")}${r.map(k=>`                ctx.${k} = ${k};`).join(`
+`)}
+            }
+`:"";return`        private buildCtx(options: { bookmarks?: DispatchBookmark; functionPath?: string; headroom?: TransactionHeadroomTracker; identity?: SubscriptionIdentity; kind?: "query"; onRead?: (table: string, idOrScan?: string) => void; onReadRange?: (range: KeyRange) => void; scope?: QueryReadScope; trusted?: boolean } = {}): unknown {
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            // The caller context this ctx runs under, resolved ONCE on one
+            // discriminant. When the caller threads an explicit identity
+            // (subscription seed / refresh / stream pull / shape resolve — all
+            // deferred or interleaved), it is used by value and the shared
+            // per-request fields are never read, because a concurrent RPC owns
+            // them: a refresh in particular runs inside the writing dispatch's
+            // \`flushChangedTables\`, BEFORE its \`endDispatch\`, so \`getCurrentIp()\`
+            // there is the MUTATING caller's address. Otherwise (the synchronous
+            // RPC dispatch path) it falls back to those fields as before.
+            //
+            // One expression, not one per field: three parallel ternaries on the
+            // same discriminant is how \`ip\` came to be the only one still reading
+            // the shared field.
+            const caller: SubscriptionIdentity = options.identity ?? {
+                identity: this.getCurrentIdentity(),
+                ip: this.getCurrentIp(),
+                userId: this.getCurrentUserId(),
+            };
+            const { identity, ip, userId } = caller;
+${A}${m}${t}${q}${g}${_}${e}
+            // Which dispatch this ctx belongs to. Drives the two deferral facades
+            // below and the \`ctx.run*\` caller guard; a ctx built for an
+            // admin/lifecycle path has no registered function, and so no kind. An
+            // untracked \`ctx.runQuery\` overrides it with \`"query"\`: the sub-query
+            // keeps the caller's \`functionPath\` for attribution but runs as a query.
+            const contextKind = options.kind ?? LUNORA_FUNCTIONS[options.functionPath ?? ""]?.kind;
+            // \`list\`/\`get\` are the two methods \`ctx.db.system.query("_scheduled_functions")\`
+            // reaches through, and pending jobs live in the SchedulerDO — nothing the
+            // CDC changelog records — so reading them must forfeit a delta resume.
+            // The scheduler's own \`runAfter\`/\`runAt\`/\`cancel\` are writes and stay unstamped.
+            const schedulerBase = markUnvouchableReads((config.scheduler?.(env) ?? schedulerStub) as SchedulerLike, options.onRead, ["get", "list"]);
+            // \`ctx.scheduler.runAfter(0, ...)\` is documented as the deterministic
+            // equivalent of an \`afterCommit\` hook, and the SchedulerDO persists the
+            // job the moment it is called — so inside a mutation the call is BUFFERED
+            // and replayed after the transaction commits (a rollback drops it).
+            // Wrapped on the same dispatches as the deferred-delete queue and for the
+            // same reason: \`ctx.runMutation\` hands the CALLER's ctx to the callee, so
+            // a mutation reached from an action schedules through the action's ctx.
+            // An action's own schedules stay immediate — the window is only open
+            // while a transaction is (see \`runMutationTransaction\`).
+            //
+            // Every kind but \`query\` is wrapped, because \`runMutationTransaction\`
+            // is installed on \`ctx.runMutation\` for every kind but \`query\`: a
+            // STREAM ctx, and an admin/lifecycle ctx with no registered kind at all,
+            // both get the BEGIN/COMMIT span for a mutation they compose, and used
+            // to get it with the deferral missing — so that mutation's job reached
+            // the SchedulerDO while its transaction was still open, and survived the
+            // rollback. A query cannot host a mutation handler (\`dispatchRun\`
+            // refuses it) and its ctx is built on the hot subscription path, so it
+            // stays unwrapped.
+            //
+            // Wrapped OUTSIDE the read-stamping facade so \`get\`/\`list\` stay stamped.
+            //
+            // \`this.scheduleOutbox()\` is what keeps the buffer honest. Everything
+            // between the COMMIT and the scheduler's acknowledgement is outside the
+            // transaction, so a failure there leaves writes that are durable and a
+            // job that exists nowhere — and the mutation's replay-dedup row committed
+            // inside the span, so the client's retry is answered from cache and told
+            // it succeeded. The outbox takes custody of each buffered call inside the
+            // transaction and releases it once the scheduler has the job; what
+            // survives is retried by \`pollScheduleOutbox\` on the shared poll alarm.
+            const scheduler = contextKind === "query" ? schedulerBase : withDeferredSchedules(schedulerBase, this.scheduleOutbox());
+            // Build the storage adapter once and share it between \`ctx.storage\`
+            // and \`ctx.db.system._storage\` so both read the same R2 binding. The
+            // \`storageStub\` fallback satisfies SystemReaderStorageLike structurally
+            // (its \`list\`/\`getMetadata\` throw the "no storage configured" error).
+            //
+            // Wrapped BEFORE the split so both consumers share one stamping facade.
+            // Only the methods that actually reach R2 are stamped: \`getUrl\` and
+            // \`getSignedUrl\` build a URL from the configured base (and an HMAC) and
+            // read nothing, and they are what handlers overwhelmingly call — stamping
+            // them would forfeit resumes for a dependency that cannot move the result.
+            // \`bucket\` IS stamped: it hands back a sub-facade this wrapper does not
+            // reach, so the selection is the last point at which the read can be seen.
+            //
+            // The request origin is the storage base fallback for mutations and
+            // actions on the synchronous dispatch only. A deferred caller
+            // (\`options.identity\` set) runs outside the dispatch that owns the
+            // field, the same hazard \`getCurrentIp\` has. A query never gets it: a
+            // live query re-runs with no request behind it, and the reactive
+            // cache does not key on the host, so a query that signs URLs needs a
+            // declared \`publicBaseUrl\` either way.
+            const requestOrigin = contextKind !== "query" && options.identity === undefined ? this.getCurrentOrigin() : undefined;
+            const makeStorage = (origin?: string): SystemReaderStorageLike =>
+                markUnvouchableReads(asBucketStorage(config.storage?.(env, origin) ?? storageStub) as SystemReaderStorageLike, options.onRead, [
+                    "bucket",
+                    "download",
+                    "getMetadata",
+                    "list",
+                ]);
+            const storage = makeStorage(requestOrigin);
+            // \`ctx.storage.deleteAfterCommit(key)\`, on every dispatch that can host
+            // a MUTATION handler — which is not only a mutation dispatch:
+            // \`ctx.runMutation\` hands the CALLER's ctx to the callee, so a mutation
+            // reached from an action runs on the action's ctx. Wrapping mutations
+            // alone made that composition throw a bare TypeError on a method the
+            // handler's own type promises. Queries stay unwrapped: they cannot host
+            // one, and their ctx is built on the hot subscription path.
+            //
+            // Every dispatch wrapped here also flushes (see \`handleRpc\` and
+            // \`runReactor\`) — a queue nothing drains leaks silently, which is worse
+            // than not having the method at all.
+            //
+            // Wrapped OUTSIDE the read-stamping facade so \`bucket(name)\` still
+            // resolves through it and stays stamped, and applied only to
+            // \`ctx.storage\` so \`ctx.db.system._storage\` (which shares the adapter
+            // above) is untouched.
+            const contextStorage = contextKind === "mutation" || contextKind === "action" ? withDeferredDeletes(storage) : storage;
+            // \`ctx.log\`: the DO base builds the attributed logger (structured
+            // fields + \`.with(...)\` child + trace correlation) and routes each call
+            // to the optional \`observability\` sink. It also buffers the line (studio
+            // Logs panel) and emits a structured console event the dev-server formats.
+            //
+            // Resolved BEFORE \`ctx.db\` below, because the database is wrapped in
+            // auto-instrumentation that needs the sink, the trace anchor, and the
+            // dispatch's wide-event handle.
+            const observability = config.observability?.(env);
+            const logFunctionPath = options.functionPath ?? "";
+            const log = this.makeLogger(logFunctionPath, observability);
+            const traceAnchor = this.resolveDispatchAnchor(Boolean(options.identity));
+
+            // \`ctx.span\`: the handle onto the DISPATCH's own span — the wide-event
+            // surface. Attributes attached here accumulate for the whole request
+            // and are folded into the one span it already emits, instead of
+            // becoming N separate log lines. Shares \`traceAnchor\` with \`ctx.trace\`
+            // so both write to the same trace.
+            const span = this.makeDispatchSpan(traceAnchor, observability);
+
+${w}            // \`ctx.db\`, wrapped in automatic instrumentation: by default this
+            // adds aggregate counters (call count, total time, per-operation
+            // breakdown) to the wide event rather than a span per call, so a
+            // handler making hundreds of queries stays readable. See
+            // \`instrumentDatabase\` for the \`"spans"\` / \`"off"\` levels.
+            const db: DatabaseWriterLike = this.instrumentDb(createShardCtxDb(${d}), logFunctionPath, traceAnchor, observability);
+${c}${L}
+
+            // \`ctx.trace\` / \`ctx.metrics\`: spans and measurements to the same sink.
+            // The trace anchor is threaded explicitly for the same reason \`identity\`
+            // is — a deferred caller (a subscription re-run) must not inherit the
+            // writing mutation's trace from the shared per-request field.
+            const trace = this.makeTracer(logFunctionPath, observability, traceAnchor);
+            const metrics = this.makeMetrics(logFunctionPath, observability);
+${S}
+            // \`ctx.now\`: the wall-clock instant (epoch ms) this function began,
+            // captured ONCE so the whole handler body sees a single stable value.
+            // A \`query\` handler is re-run by every live subscription that reads it,
+            // so \`Date.now()\` there flickers between re-evaluations. A \`mutation\`
+            // handler does not replay under ordinary dispatch (an OCC conflict throws
+            // to the caller rather than retrying internally), but one called from a
+            // workflow step or queue consumer runs again when that step replays. Both
+            // read time through \`ctx.now\` — the \`nondeterministic_query_mutation\`
+            // advisor flags \`Date.now()\`. Actions may still use ambient \`Date.now()\`.
+            const now = Date.now();
+
+            const ctx: Record<string, unknown> = {
+                auth: {
+                    getIdentity: async () => identity ?? null,
+                    userId: userId ?? null,
+                },
+                db,
+                // Instrumented \`fetch\`: a CLIENT span per outbound call plus W3C
+                // \`traceparent\` propagation, so time spent in a downstream service
+                // is visible and its spans join this trace. Degrades to the bare
+                // global when no sink is configured.
+                fetch: this.makeFetch(logFunctionPath, traceAnchor, observability),
+                // A GETTER, not a plain field, so the reactive cache can tell a
+                // handler that reads the caller's address from the majority that
+                // never do. \`ctx.ip\` is per-request state the memo must be keyed
+                // by — otherwise two anonymous callers share one entry and the
+                // second is served the first's address — but keying every entry
+                // by address would shard the cache per client for every query.
+                // Reading it here marks the dispatch's scope; \`runCachedQuery\`
+                // folds the address into the key for this function from then on.
+                get ip() {
+                    options.scope?.markIpRead();
+
+                    return ip;
+                },
+                log,
+                metrics,
+                now,
+                // The same request origin the storage fallback above uses, handed
+                // to the handler so code that signs its own URLs (a copy-in
+                // \`createStorage\`) can fall back to it too. \`undefined\` for a
+                // query and for a deferred dispatch, for the reasons given there.
+                origin: requestOrigin,${y}
+                scheduler,
+                span,
+                storage: contextStorage,
+                trace,${P}${f}${i}${o}${R}${I}${M}${n}
+            };
+${l?`            const isAction = contextKind === "action";
+`:""}${D}
+            const installRun = (target: Record<string, unknown>, kind: typeof contextKind): void => {
+                target.runAction = (reference: FunctionReference, fnArgs: Record<string, unknown>) => dispatchRun("action", reference.__lunoraRef, fnArgs, target, kind);
+                // The composed mutation runs under the SAME wrapper the top-level RPC
+                // uses, so "do the transactional work in a mutation and call it from the
+                // action" — the recipe the docs give for atomicity — actually is atomic.
+                target.runMutation = (reference: FunctionReference, fnArgs: Record<string, unknown>) =>
+                    dispatchRun("mutation", reference.__lunoraRef, fnArgs, target, kind, async (work) => this.runMutationTransaction(target, work));
+                // \`ctx.runQuery(ref, args, { untracked: true })\` runs the sub-query on
+                // its OWN query context, built without the subscription's read-footprint
+                // hooks — so its reads never enter this subscription's footprint and a
+                // write to the tables it touched does not re-run us. Everything else is
+                // inherited: \`functionPath\` (log/metric attribution), \`headroom\` (the
+                // sub-query must not escape this dispatch's resource ceiling),
+                // \`scope\` (the reactive-cache capture — an untracked sub-query's reads
+                // must still be deps of the entry the OUTER query is memoized as, or
+                // the memo goes stale), and — load-bearing — the resolved \`caller\` BY VALUE
+                // (identity, userId AND ip). Omitting it would let \`buildCtx\` fall back
+                // to the shared per-request fields, which a concurrent RPC may have
+                // re-set, and an RLS-scoped sub-query would then read as the wrong user
+                // from the wrong address. A tracked call runs on \`queryContext()\` below.
+                target.runQuery = (reference: FunctionReference, fnArgs: Record<string, unknown>, runOptions?: { untracked?: boolean }) =>
+                    dispatchRun(
+                        "query",
+                        reference.__lunoraRef,
+                        fnArgs,
+                        runOptions?.untracked === true
+                            ? this.buildCtx({ bookmarks: options.bookmarks, functionPath: options.functionPath, headroom: options.headroom, identity: caller, kind: "query", scope: options.scope })
+                            : queryContext(),
+                        kind,
+                    );
+            };
+
+            // A query composed from a mutation or action runs on a QUERY view of
+            // this ctx, so it behaves exactly as it does when called directly or
+            // live: same \`db\`, read hooks, trace and \`now\`, but every field that
+            // depends on the dispatch kind or the request origin is re-derived for a
+            // query — no \`ctx.origin\`, storage with no origin fallback (and no
+            // \`deleteAfterCommit\`), the unwrapped scheduler, no ActionCtx-only
+            // helpers, and a \`run*\` guard that refuses a mutation or action. A new
+            // kind- or origin-dependent ctx field must be overridden here too.
+            // Copied by descriptor so the \`ip\` getter is carried over, not read.
+            // Built on the first composed call only; a query ctx is its own view.
+            let queryView: Record<string, unknown> | undefined;
+            const queryContext = (): Record<string, unknown> => {
+                if (contextKind === "query") {
+                    return ctx;
+                }
+
+                if (queryView === undefined) {
+                    const descriptors: PropertyDescriptorMap = Object.getOwnPropertyDescriptors(ctx);
+${r.map(k=>`                    delete descriptors.${k};
+`).join("")}                    // Writable and configurable, like the plain fields they replace.
+                    const field = (value: unknown): PropertyDescriptor => ({ configurable: true, enumerable: true, value, writable: true });
+
+                    queryView = Object.defineProperties({}, {
+                        ...descriptors,
+                        origin: field(undefined),
+                        scheduler: field(schedulerBase),
+                        storage: field(makeStorage()),
+                    }) as Record<string, unknown>;
+                    installRun(queryView, "query");
+                }
+
+                return queryView;
+            };
+
+            installRun(ctx, contextKind);
+
+            return ctx;
+        }`},Xt=`// Bound in-process \`ctx.run*\` composition depth so a self- or cyclically-
+// referencing call fails loudly with a clear error instead of overflowing the
+// stack. Tracked across the awaited handler chain (one DO invocation is
+// single-threaded), so the counter reflects true nesting depth.
+const MAX_RUN_DEPTH = 32;
+let runDepth = 0;
+
+const dispatchRun = async (
+    expected: FunctionKind,
+    functionPath: string,
+    args: Record<string, unknown>,
+    ctx: unknown,
+    // The kind of the context making the call, and — for a mutation target — the
+    // transaction wrapper to run it under. Both are supplied by \`buildCtx\`, which
+    // is the only place that knows which dispatch this \`ctx\` belongs to. Widened
+    // past \`FunctionKind\` because the registry also carries \`"stream"\`, and
+    // \`undefined\` for a ctx built outside a registered function (admin, migration).
+    callerKind?: "stream" | FunctionKind,
+    runTransactional?: (work: () => Promise<unknown>) => Promise<unknown>,
+): Promise<unknown> => {
+    // A query is read-only. The ctx object installs \`run*\` on every kind (one
+    // shape, built once), so the TYPE is all that stops a query from writing —
+    // and a cast walks straight past it, inside a subscription re-run that can
+    // execute many times per write. Checked on the CALLER, before the registry
+    // lookup, so \`ctx.runMutation\` from a query fails identically whatever it
+    // aimed at.
+    if (callerKind === "query" && expected !== "query") {
+        throw new LunoraError(
+            "RUN_KIND_FORBIDDEN",
+            \`ctx.run\${expected[0]!.toUpperCase()}\${expected.slice(1)}: a query may only compose other queries (tried to run "\${functionPath}")\`,
+        );
+    }
+
+    const registered = LUNORA_FUNCTIONS[functionPath];
+
+    if (!registered) {
+        throw new Error(\`unknown function: \${functionPath}\`);
+    }
+
+    if (registered.kind !== expected) {
+        throw new Error(\`ctx.run\${expected[0]!.toUpperCase()}\${expected.slice(1)}: "\${functionPath}" is registered as a \${registered.kind}, not a \${expected}\`);
+    }
+
+    if (runDepth >= MAX_RUN_DEPTH) {
+        throw new LunoraError("RUN_DEPTH_EXCEEDED", \`ctx.run*: composition depth limit (\${MAX_RUN_DEPTH}) exceeded — likely a cyclic runQuery/runMutation\`);
+    }
+
+    runDepth += 1;
+
+    try {
+        // A mutation composed from an action (or an http action) is the shape the
+        // docs prescribe for atomicity — "do the transactional reads and writes in
+        // a mutation and call it from the action". It only holds if the composed
+        // dispatch gets the same BEGIN/COMMIT span and single-writer gate the
+        // top-level mutation path gets; without it every write autocommits and a
+        // mid-handler throw leaves the earlier ones durable. A \`runMutation\` from
+        // inside a mutation rides the enclosing span instead of opening a second
+        // one (see \`runMutationTransaction\`).
+        if (runTransactional) {
+            return await runTransactional(async () => registered.handler(ctx, args));
+        }
+
+        return await registered.handler(ctx, args);
+    } finally {
+        runDepth -= 1;
+    }
+};`,Jt=`        public override async handleRpc(functionPath: string, args: Record<string, unknown>, headroom?: TransactionHeadroomTracker, scope?: QueryReadScope, bookmarks?: DispatchBookmark): Promise<unknown> {
+            const registered = LUNORA_FUNCTIONS[functionPath];
+
+            // Internal functions are reachable server-side only: via \`ctx.run*\`
+            // composition, or a trusted system dispatch (scheduler/cron, marked by
+            // \`isSystemDispatch()\`). A client RPC never carries that flag, so its
+            // internals stay not-found and never leak across the external boundary.
+            if (!registered || (registered.visibility === "internal" && !this.isSystemDispatch())) {
+                throw new LunoraError("FUNCTION_NOT_FOUND", \`function not registered: \${functionPath}\`);
+            }
+
+            this.ensureMigrated();
+
+            // \`headroom\`, when the caller supplied one, is threaded straight
+            // through to \`buildCtx\` — bypassing its \`this.transactionHeadroom()\`
+            // fallback (the racy shared-field read) entirely for THIS dispatch.
+            // The main \`/rpc\` path always supplies one; \`dispatchLifecycle\` /
+            // \`handleRunAs\` don't mint their own and omit it, so they keep the
+            // prior fallback behavior unchanged.
+            //
+            // \`scope\` is the reactive cache's per-dispatch read capture, threaded
+            // the same way and for the same reason: the ctx-db read hooks resolve
+            // their tracker at READ time, so binding them to the scope THIS
+            // dispatch was handed is what keeps a concurrent query's reads out of
+            // our dep set — and ours out of theirs. A dispatch with no scope (a
+            // mutation, an action, a cache-less shard) builds unbound hooks that
+            // stamp no deps.
+            const ctx = this.buildCtx({ bookmarks, functionPath, headroom, scope, trusted: registered.lifecycle === "init" });
+
+            // A mutation's writes must commit all-or-nothing, so its dispatch runs
+            // under \`runMutationTransaction\` — the ONE place that opens the span,
+            // settles the deferred schedules and flushes the deferred deletes. The
+            // same helper backs \`ctx.runMutation\` and \`runReactor\`, because a
+            // mutation reached by composition is promised exactly these guarantees
+            // and used to get none of them.
+            //
+            // The replay bookkeeping (idempotency dedup row + custom-mutator
+            // watermark advance) commits INSIDE the 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. It is deliberately NOT in the shared helper: it is
+            // per-REQUEST bookkeeping, and a composed sub-mutation has no request of
+            // its own to record.
+            if (registered.kind === "mutation") {
+                return await this.runMutationTransaction(ctx, async () => {
+                    const value = await registered.handler(ctx, args);
+
+                    this.commitMutationBookkeeping(value);
+
+                    return value;
+                });
+            }
+
+            const result = await registered.handler(ctx, args);
+
+            // An action is not itself transactional, but \`ctx.runMutation\` runs its
+            // submutations on THIS ctx, so anything they queued after their own
+            // transaction settled lands here. A dispatch with nothing queued no-ops.
+            await this.deferPastResponse(flushDeferredDeletes(ctx));
+
+            return result;
+        }
+
+        /**
+         * Run one mutation handler with the atomicity every caller of a mutation is
+         * promised: a BEGIN/COMMIT span (with the single-writer gate
+         * \`ShardRunner.runInTransaction\` composes in front of it), scheduled jobs
+         * held until that span commits, and the deferred object deletes flushed
+         * only once it has.
+         *
+         * Shared by the three entry points that dispatch a mutation handler — the
+         * top-level RPC, \`ctx.runMutation\` from an action or http action, and a
+         * reactor — because the guarantee is a property of the mutation, not of how
+         * it was reached. The docs tell users to put the transactional part in a
+         * mutation and call it from the action precisely so that composition is
+         * atomic.
+         *
+         * A \`ctx.runMutation\` issued from inside a mutation is NESTED: SQLite-in-DO
+         * has no savepoints and \`runInTransaction\` rejects a second open, so it
+         * rides the enclosing span, which also owns its commit and therefore its
+         * scheduler flush.
+         *
+         * Both deferral windows are opened here and settled against the SAME
+         * outcome. The delete window is what keeps a composed mutation's queued
+         * object deletes off the caller's flush when it rolls back: \`ctx\` is
+         * shared, so without a window the keys are indistinguishable from the
+         * action's own and the action's flush destroys objects whose rows the
+         * rollback put back.
+         */
+        private async runMutationTransaction<T>(ctx: unknown, work: () => Promise<T>): Promise<T> {
+            const settleSchedules = beginDeferredSchedules(ctx as { scheduler?: unknown });
+            // Synchronous and non-throwing (it only moves queue entries), so it can
+            // settle first on every path and cannot mask the outcome.
+            const settleDeletes = beginDeferredDeletes(ctx);
+
+            if (this.isInTransaction()) {
+                try {
+                    const nested = await work();
+
+                    settleDeletes(true);
+                    await settleSchedules(true);
+
+                    return nested;
+                } catch (error) {
+                    settleDeletes(false);
+                    await settleSchedules(false);
+
+                    throw error;
+                }
+            }
+
+            let result: T;
+
+            try {
+                result = await this.runInTransaction(work);
+            } catch (error) {
+                // The span rolled back, so the rows are gone and the jobs that were
+                // to run "after I commit" must go with them. Dropping them is the
+                // whole point of buffering: a persisted job for a write that never
+                // landed fires against state that does not exist.
+                //
+                // The queued object deletes go the same way, and for a sharper
+                // reason: the rows they were to clean up after are still there, and
+                // an R2 delete cannot be undone.
+                settleDeletes(false);
+                await settleSchedules(false);
+
+                throw error;
+            }
+
+            // Committed, so this span's queued keys join whatever the flush below
+            // (or an enclosing span's) will drain.
+            settleDeletes(true);
+
+            // Committed. Schedules first and AWAITED: \`runAfter(0, ...)\` is
+            // documented as the deterministic equivalent of an \`afterCommit\` hook,
+            // so the job must be enqueued after the commit, and a failure to enqueue
+            // it must be visible rather than swallowed.
+            //
+            // In a \`finally\`, because both halves of this are post-commit cleanup
+            // and neither is allowed to cancel the other. \`settleSchedules\` drains
+            // its whole queue and then rethrows what failed, so a SchedulerDO that
+            // refused one job used to take the object cleanup down with it — the
+            // rows were durably gone and their objects leaked with nothing logged.
+            try {
+                await settleSchedules(true);
+            } finally {
+                // Then the objects whose rows are now durably gone. Deliberately AFTER
+                // the span, never inside it: an R2 delete cannot roll back, so a delete
+                // issued from within a transaction that later aborts destroys data the
+                // surviving row still points at.
+                //
+                // \`flushDeferredDeletes\` never rejects — the mutation has already
+                // succeeded, so a failed cleanup must not turn into a failed response.
+                // A leaked object is reported through \`ctx.log\` instead, with its key.
+                await this.deferPastResponse(flushDeferredDeletes(ctx));
+            }
+
+            return result;
+        }
+
+        // Only a \`mutation\` may enter the base class's single-writer gate for
+        // mutation-replay dedup — it is \`blockConcurrencyWhile\`, so gating an
+        // action would stall every other dispatch on the shard for the length of
+        // its outbound I/O, on nothing but a caller-supplied header. Unregistered
+        // paths answer \`false\`; \`handleRpc\` above rejects them anyway.
+        protected override isMutationFunction(functionPath: string): boolean {
+            return LUNORA_FUNCTIONS[functionPath]?.kind === "mutation";
+        }
+
+        // The scheduler the deferred-schedule outbox retries through. Only the
+        // CONFIGURED one: falling back to \`schedulerStub\` would have an app with no
+        // scheduler retry every entry against a thrower until the attempt ceiling
+        // parked it, and there is nothing to park — an app with no scheduler has no
+        // \`ctx.scheduler\` call that reached the buffer in the first place.
+        protected override scheduleOutboxScheduler(): SchedulerLike | undefined {
+            return config.scheduler?.((this.env ?? {}) as Record<string, unknown>) as SchedulerLike | undefined;
+        }`,Yt=`        protected override async executeSubscription(functionPath: string, args: Record<string, unknown>, identity?: SubscriptionIdentity): Promise<{ ranges?: Map<string, KeyRange[]>; result: unknown; tables: Set<string> } | null> {
+            const registered = LUNORA_FUNCTIONS[functionPath];
+
+            if (!registered || registered.kind !== "query" || registered.visibility === "internal") {
+                return null;
+            }
+
+            this.ensureMigrated();
+
+            const footprint = createReadFootprint();
+            // Identity is threaded EXPLICITLY from the (deferred/interleaved)
+            // subscription caller — never read from the shared per-request field
+            // here — so a concurrent RPC can't leak its identity into this re-run.
+            const ctx = this.buildCtx({ functionPath, headroom: this.subscriptionHeadroom(), identity, onRead: footprint.onRead, onReadRange: footprint.onReadRange });
+            const result = await registered.handler(ctx, args);
+
+            // Ranges come from THIS run's reads, never a shared field on the DO:
+            // a deferred re-run interleaves with unrelated dispatches.
+            return { ranges: footprint.ranges(), result, tables: footprint.tables };
+        }
+
+        protected override executeStream(functionPath: string, args: Record<string, unknown>, identity?: SubscriptionIdentity): null | { durable?: { ttlMs?: number }; iterator: (signal: AbortSignal) => AsyncIterable<unknown> } {
+            const registered = LUNORA_FUNCTIONS[functionPath];
+
+            if (!registered || registered.kind !== "stream" || registered.visibility === "internal") {
+                return null;
+            }
+
+            this.ensureMigrated();
+
+            return {
+                ...(registered.durable ? { durable: registered.durable as { ttlMs?: number } } : {}),
+                // Identity threaded EXPLICITLY from the socket, exactly as
+                // \`executeSubscription\` above: the iterator is pulled after this
+                // frame returned, interleaved with unrelated dispatches, so
+                // \`buildCtx\`'s per-request fallback would run an \`rls()\` /
+                // \`ctx.auth\` stream as nobody — or as a concurrent RPC's caller.
+                iterator: (signal) => (registered.handler as (context: unknown, args: Record<string, unknown>, signal: AbortSignal) => AsyncIterable<unknown>)(this.buildCtx({ functionPath, identity }), args, signal),
+            };
+        }`,Zt=a=>{const r={};for(const e of a.tables){const n={};for(const[t,o]of Object.entries(e.shape)){const d=K(o);d.kind==="id"&&d.tableName!==void 0&&(n[t]=d.tableName)}Object.keys(n).length>0&&(r[e.name]=n)}return r},er=a=>{const r={};for(const e of a.tables){const n=[];for(const[t,o]of Object.entries(e.shape))K(o).kind==="storage"&&n.push(t);n.length>0&&(r[e.name]=n)}return r},tr=a=>{const r={};for(const e of a.tables){const n=[...e.indexes.map(t=>({fields:[...t.fields],name:t.name,type:"index",...t.unique===!0?{unique:!0}:{}})),...e.searchIndexes.map(t=>({fields:[t.field,...t.filterFields??[]],name:t.name,type:"search"})),...(e.geoIndexes??[]).map(t=>({fields:[t.field],name:t.name,type:"geo"})),...e.rankIndexes.map(t=>({fields:t.sortBy.map(o=>o.field),name:t.name,type:"rank"})),...e.vectorIndexes.map(t=>({fields:t.field===void 0?[]:[t.field],name:t.name,type:"vector"}))];n.length>0&&(r[e.name]=n)}return r},rr=a=>{const r=[];for(const e of a.tables)!e.ttl||e.shardMode==="global"||r.push({...e.ttl.after===void 0?{}:{after:e.ttl.after},field:e.ttl.field,...e.softDelete?{softDeleteField:e.softDelete.field}:{},table:e.name});return r},ar=a=>{if(a.kind!=="union"||a.members===void 0||a.members.length===0)return;const r=[];for(const e of a.members){if(e.kind!=="literal"||e.literalValue===void 0)return;try{const n=JSON.parse(e.literalValue);if(typeof n!="string")return;r.push(n)}catch{return}}return r},nr=(a,r,e)=>{const n=K(r),t={name:a,optional:Ht(r),type:n.kind};if(n.kind==="id"&&n.tableName!==void 0){t.ref=n.tableName;const d=e.get(a);d!==void 0&&(t.onDelete=d)}n.kind==="storage"&&(t.isStorage=!0,n.bucket!==void 0&&(t.bucket=n.bucket));const o=ar(n);return o!==void 0&&(t.enumValues=o),n.column?.notNull===!1&&(t.nullable=!0),t},sr=a=>{const r={};for(const e of a.tables){const n=[{name:"_id",optional:!1,pk:!0,type:"id"},{name:"_creationTime",optional:!1,type:"number"},...e.commitOrdered===!0?[{name:"_commitSeq",optional:!1,type:"number"}]:[]],t=new Map(e.relations.filter(o=>o.kind==="one").map(o=>[o.field,o.onDelete]));for(const[o,d]of Object.entries(e.shape))n.push(nr(o,d,t));r[e.name]=n}return r},or=({hasMutators:a,hasShapes:r,rlsData:e})=>{const n=r?`
+        protected override resolveShape(name: string, args: Record<string, unknown>, identity?: SubscriptionIdentity): { 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 });
+            // \`ownerField\` resolves an \`owner: true\` shape: only here is the table's
+            // \`.ownedBy(field)\` column in scope, so the DO hands it to the shape
+            // rather than every shape restating the ownership check in its \`where\`.
+            const shapeWhere = shape.compileWhere(ctx, args, {
+                ownerField: (schema as unknown as { tables: Record<string, { ownerField?: string }> }).tables[shape.table]?.ownerField,
+            }) as unknown as WhereInput;
+
+            // AND-compose with the read policies this SHAPE declares
+            // (\`defineShape({ use: [guard] })\`, pre-indexed into
+            // \`shape.rlsRegistry\`). A shape runs no procedure, so the
+            // \`.use(rls(...))\` middleware never fires; without this merge its
+            // reads would bypass the read policies it opted into.
+            // \`composeShapeReadWhere\` evaluates them under this same trusted ctx
+            // and fails closed under a \`.rls("required")\` schema for a
+            // non-\`.public()\` table the shape declared no read policy for.
+            //
+            // The registry is the shape's OWN — never one folded from every
+            // registered function. A project-wide union let one admin-only
+            // procedure's allow-all read policy unrestrict every shape on the
+            // table; see the SCOPE note in \`shape-read-base.ts\`.
+            //
+            // It is NOT identical to the request-time path, and must not be
+            // described as such: roles come from the identity's \`roles\` claim
+            // only, because no middleware runs here to contribute
+            // \`ctx.auth.roles\`. Derive roles at the identity if a policy gates
+            // on them — see \`shape-read-base.ts\`.
+            const effectiveWhere = composeShapeReadWhere(shape.rlsRegistry, {
+                ctx,
+                identity: identity?.identity ?? null,
+                rlsRequired: (schema as unknown as { rlsMode?: string }).rlsMode === "required",
+                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 };
+        }
+`:"",t=r?[...new Set(e.policies.filter(c=>c.on==="read"&&c.table!=="").map(c=>c.table))].toSorted((c,w)=>c.localeCompare(w)):[],o=t.length>0?`
+/** Refuses to boot a shape that would replicate around the read policies its table is governed by (\`defineShape({ use })\` is how a shape opts in; \`use: []\` acknowledges an ungoverned one). */
+assertShapesDeclareReadPolicies(LUNORA_SHAPES, ${JSON.stringify(t)}, (schema as unknown as { rlsMode?: string }).rlsMode === "required");
+`:"";return{customMutatorOverride:a?`
+        protected override isCustomMutator(functionPath: string): boolean {
+            return LUNORA_MUTATOR_PATHS.has(functionPath);
+        }
+`:"",shapeGuardImport:r?"assertShapeShardable, ":"",shapeReadPolicyAssertion:o,shapeReadPolicyImport:o===""?"":"assertShapesDeclareReadPolicies, ",shapeResolveOverride:n}},ir=(a,r)=>a?`
+        protected override async readGlobalShapeRows(resolved: { columns?: readonly string[]; effectiveWhere?: WhereInput; global?: boolean; table: string }, identity?: SubscriptionIdentity): Promise<Array<{ doc: Record<string, unknown>; id: string }>> {
+            const env = this.env as Record<string, unknown>;
+            // A shape read performs no writes, so the widened request only needs
+            // the inbound bookmark (pin the membership drain to the caller's own
+            // prior writes) — no \`onBookmark\` here.
+            //
+            // The two identity members are named rather than spread, matching the
+            // dispatch-path request built in \`buildCtx\`. A spread would also hand
+            // the global writer \`ip\`, and \`globalShapeReadKey\` — the per-flush
+            // cache in front of this read — keys on identity + userId only. Equal
+            // keys must mean equal rows, so a field the writer can scope by has to
+            // be either in the key or out of the request; it is out.
+            const globalRequest = { ...this.globalCdcOptions(config.cdc ?? false), bookmark: this.getInboundBookmark(), identity: identity?.identity, userId: identity?.userId };
+            const globalDb: DatabaseWriterLike = ${r}?.(env, globalRequest) ?? 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;
+        }
+
+        protected override async readGlobalChangedTables(sinceSeq: number, cursorOnly?: boolean): Promise<{ cursor: number; floor?: number; tables: string[] } | undefined> {
+            const env = this.env as Record<string, unknown>;
+            // Metadata-only: this asks the global changelog which TABLES moved,
+            // never what changed in them, so it costs one small read per poll tick
+            // for the whole shard — and a tick whose answer omits a shape's table
+            // skips that shape's membership drain entirely.
+            // Named local, not an inline object literal — same reason as the
+            // dispatch path and \`readGlobalShapeRows\`: \`bookmark\` is not declared
+            // on the narrower Hyperdrive thunk's \`request\` type, and an inline
+            // literal trips an excess-property error (TS2353) that makes the
+            // emitted \`shard.ts\` uncompilable for every Hyperdrive-global app with
+            // a \`defineShape\`. The Hyperdrive factory simply never reads it.
+            const globalRequest = { ...this.globalCdcOptions(config.cdc ?? false), bookmark: this.getInboundBookmark() };
+            const globalDb: DatabaseWriterLike = ${r}?.(env, globalRequest) ?? globalDbStub;
+
+            return globalDb.cdcChangedTables?.(sinceSeq, { cursorOnly });
+        }
+`:"",dr=a=>({externalSourceOverride:a?`
+        protected override async pollExternalSources(trace?: TraceRefLike): Promise<number | undefined> {
+            const env = (this.env ?? {}) as Record<string, unknown>;
+            const sourced = Object.entries((schema as unknown as SchemaLike).tables)
+                .map(([table, definition]) => [table, (definition as { externalSource?: ExternalSourceLike }).externalSource] as const)
+                .filter((entry): entry is [string, ExternalSourceLike] => entry[1] !== undefined);
+
+            if (sourced.length === 0) {
+                return undefined;
+            }
+
+            const shardKey = this.currentShardKey();
+            const scheduler = (config.scheduler?.(env) ?? schedulerStub) as SchedulerLike;
+
+            let clients = sourceClientCache.get(this);
+
+            if (clients === undefined) {
+                clients = new Map();
+                sourceClientCache.set(this, clients);
+            }
+
+            let polledAt = sourcePollAtCache.get(this);
+
+            if (polledAt === undefined) {
+                polledAt = new Map();
+                sourcePollAtCache.set(this, polledAt);
+            }
+
+            const now = Date.now();
+            // \`nextDueAt\` tracks the EARLIEST next-due timestamp across every
+            // non-manual source; the shared alarm re-arms there instead of the
+            // fixed 2 s global-shape floor, so a large \`refresh.everyMs\` actually
+            // sleeps until it's due. Stays \`undefined\` when every source is
+            // \`refresh: "manual"\`, so the shared alarm goes idle for this tier.
+            let nextDueAt: number | undefined;
+
+            for (const [table, source] of sourced) {
+                if (source.refresh === "manual") {
+                    continue;
+                }
+
+                if (isSourceDue(source.refresh, polledAt.get(table), now)) {
+                    try {
+                        let client = clients.get(source.binding);
+
+                        if (client === undefined) {
+                            client = config.sourceClient?.(env, source.binding);
+
+                            if (client !== undefined) {
+                                clients.set(source.binding, client);
+                            }
+                        }
+
+                        if (client === undefined) {
+                            // No SqlClient resolved for this binding (host never wired
+                            // \`config.sourceClient\`, or wired it wrong). Surface it in the
+                            // Logs panel and stamp \`polledAt\` so a persistent misconfig backs
+                            // off to \`refresh.everyMs\` instead of retrying every alarm tick.
+                            this.recordExternalSourceError(table, new Error(\`external-source: no sourceClient resolved for binding "\${source.binding}"\`), trace);
+                        } else {
+                            // A FRESH tracker per TABLE, not one shared across the whole
+                            // loop: one table's runaway pull must not spend a budget a
+                            // sibling table needs, and a limit hit here must not block
+                            // that sibling from getting its own full budget this tick.
+                            const writer = createShardCtxDb({
+                                // Admin and maintenance writes go through the SAME reactive-cache hooks as
+                                // a user mutation. Without this, a studio row edit, a TTL sweep, an admin
+                                // import, a CDC apply or a data-migration backfill writes without
+                                // invalidating, and the next query answers from the pre-write snapshot.
+                                ...this.ctxDbTuning(),
+                                broadcast: (delta) => {
+                                    this.recordChangedTable(delta.table, delta.indexKeys);
+                                },
+                                cdc: config.cdc ?? false,
+                                headroom: this.alarmHeadroom(),
+                                scheduler,
+                                schema: schema as unknown as SchemaLike,
+                                sql: this.sql as SqlExec,
+                            });
+
+                            if (source.mode === "incremental") {
+                                // Incremental (plan 136): pull only rows past the durable
+                                // watermark (or a full-pull seed/reconcile), upsert-only.
+                                // eslint-disable-next-line no-await-in-loop -- one sourced table at a time; sequential keeps the writer transaction simple
+                                await pullExternalSourceIncrementalTick(this.sql as SqlExec, writer, client, table, source, shardKey, now);
+                            } else {
+                                // eslint-disable-next-line no-await-in-loop -- one sourced table at a time; slices are independent but small and sequential keeps the writer transaction simple
+                                await pullExternalSourceTick(this.sql as SqlExec, writer, client, table, source, shardKey);
+                            }
+                        }
+
+                        // Timestamp AFTER the poll finishes, not the batch-start \`now\` — a
+                        // poll that outruns \`everyMs\` must not make \`nextDueAt\` (below)
+                        // stale-immediate and re-arm the alarm in a hammering loop.
+                        polledAt.set(table, Date.now());
+                    } catch (error) {
+                        if (error instanceof LunoraError && error.code === "TRANSACTION_LIMIT_EXCEEDED") {
+                            // Batch full, not a genuine failure. Incremental mode only
+                            // persists its watermark AFTER a full apply (see
+                            // \`pullExternalSourceIncrementalTick\`), so this throw left it
+                            // untouched — the next tick safely re-pulls/re-applies the
+                            // SAME slice (idempotent upsert). Full-pull mode (and an
+                            // incremental source's own occasional full-pull/reconcile
+                            // sweep) has no resumable cursor at all — deliberately not
+                            // inventing one here; a retry just redoes the whole pull,
+                            // safe if wasteful. Either way: warn instead of
+                            // \`recordExternalSourceError\`, and leave \`polledAt\`
+                            // UNCHANGED (skip the stamp below via \`continue\`) so this
+                            // table stays "due" and \`nextPollAlarmTarget\`'s existing
+                            // due-now floor re-arms the shared alarm promptly — not a
+                            // fresh \`setAlarm(now)\`.
+                            this.recordExternalSourceWarning(
+                                table,
+                                \`external-source poll for "\${table}" hit the transaction limit mid-batch; resuming next tick: \${error.message}\`,
+                                trace,
+                            );
+
+                            nextDueAt = nextDueAt === undefined ? now : Math.min(nextDueAt, now);
+
+                            continue;
+                        }
+
+                        this.recordExternalSourceError(table, error, trace);
+                        // Stamp on failure too, so a persistently failing source throttles
+                        // to \`refresh.everyMs\` rather than being hammered every tick.
+                        polledAt.set(table, Date.now());
+                    }
+                }
+
+                // This source's own next-due time, read AFTER the poll-or-skip above
+                // so a just-polled source reports \`now + everyMs\` (its FRESH due
+                // time), not the stale pre-poll one. An omitted \`refresh\` (poll
+                // every tick) is due again immediately.
+                const sourceNextDueAt = source.refresh === undefined ? now : (polledAt.get(table) ?? now) + source.refresh.everyMs;
+
+                nextDueAt = nextDueAt === undefined ? sourceNextDueAt : Math.min(nextDueAt, sourceNextDueAt);
+            }
+
+            return nextDueAt;
+        }
+`:"",sourceBootstrap:a?`
+            const autoSourced = Object.values((schema as unknown as SchemaLike).tables).some((definition) => {
+                const source = (definition as { externalSource?: ExternalSourceLike }).externalSource;
+
+                return source !== undefined && source.refresh !== "manual";
+            });
+
+            if (autoSourced) {
+                void this.scheduleSourcePoll();
+            }
+`:"",sourceClientCacheConst:a?`
+const sourceClientCache = new WeakMap<object, Map<string, SourceClientLike>>();
+const sourcePollAtCache = new WeakMap<object, Map<string, number>>();
+`:""}),cr=(a,r)=>{const e=r.length>0,t=a?C("vectorsStub: VectorSearchLike","ctx.vectors: no vectors configured. Pass `vectors` to createShardDO().",["deleteByIds","getByIds","query","upsert","upsertNow"]):"",o=e?`            const vectorShardKey = this.currentShardKey();
+`:"",d=e?"namespace: vectorShardKey === ROOT_SHARD_NAME ? undefined : vectorShardKey, ":"",f=`, { ${["deferAfterCommit: (work) => this.deferAfterCommit(work)",...e?["namespace: vectorShardKey === ROOT_SHARD_NAME ? undefined : vectorShardKey",`shardedIndexNames: [${r.map(S=>JSON.stringify(S)).join(", ")}]`]:[]].join(", ")} }`,c=a?`
+            const vectorSync = this.vectorSync(env);
+            // Vectorize lives outside this shard's SQLite, so a query whose result
+            // depends on a similarity search cannot be proven current on reconnect —
+            // an unrelated upsert (or a re-index) moves the matches without touching
+            // \`__cdc_log\`. Only \`ctx.vectors\` is wrapped: the write-through
+            // vector-sync hook keeps calling the bare facade.
+            const bareVectors = vectorSync?.vectors ?? vectorsStub;
+            const vectors = markUnvouchableReads(bareVectors, options.onRead, ["getByIds", "query"]);
+            const onWrite = vectorSync?.onWrite;
+`:"";return{vectorSyncMethod:a?`
+        private vectorSync(env: Record<string, unknown>): { backfill: VectorBackfillSync; onWrite: WriteHook; vectors: VectorSearchLike } | undefined {
+            if (!config.vectors) {
+                return undefined;
+            }
+
+            const lunora = createVectors({ indexes: config.vectors(env) });
+${o}            const vectors = createContextVectors(lunora${f});
+
+            return {
+                backfill: createVectorBackfillSync({ ${d}schema: schema as unknown as VectorSchemaLike, upsertMany: lunora.upsertMany, vectors }),
+                onWrite: createVectorSyncHook({ ${d}schema: schema as unknown as VectorSchemaLike, vectors }),
+                vectors,
+            };
+        }
+
+        // \`__lunora_admin__:backfillVectors\`: the rows that predate a vector index,
+        // a page at a time, each page ordered on the after-commit chain so it
+        // never lands over a newer write's vector.
+        protected override async runShardVectorBackfill(options: { maxPages?: number; restart?: boolean }): Promise<VectorBackfillProgress> {
+            this.ensureMigrated();
+
+            const vectorSync = this.vectorSync((this.env ?? {}) as Record<string, unknown>);
+
+            if (!vectorSync) {
+                throw new LunoraError("NOT_IMPLEMENTED", "vector backfill is unavailable: no vectors configured. Pass \`vectors\` to createShardDO().");
+            }
+
+            return backfillVectorIndexes(this.sql as SqlExec, vectorBackfillTargets(schema as unknown as VectorSchemaLike), vectorSync.backfill, {
+                ...options,
+                ordered: async (read, work) => this.runOrderedAfterWrites(read, work),
+            });
+        }
+`:"",vectorsBuild:c,vectorsStub:t}},kr=({advisories:a=[],advisorProcedures:r=[],agents:e=[],capabilities:n=new Set,containers:t=[],env:o,flagKeys:d=[],hasFlags:m=!1,hasNotify:f=!1,hasVectors:c=!0,maskMetadata:w,mutators:S=[],queues:y=[],rlsMetadata:L,schema:i,schemaSnapshot:g,shapes:I=[],storageRules:_,studioFeatures:M,services:A=[],topics:P=[],useUmbrella:q=!1,workflows:R=[]})=>{const l=Kt(q),D=S.length>0,v=I.length>0,k=g===void 0?"":kt(g),te=g===void 0?"":`
+/** Structural schema snapshot + its content hash, recorded in the shard's \`__lunora_schema_history\` ledger on cold start so the studio can show a schema-version timeline and diff any two versions. */
+const LUNORA_SCHEMA_SNAPSHOT: { hash: string; json: string } = { hash: ${JSON.stringify(St(g))}, json: ${JSON.stringify(k)} };
+`,re=g===void 0?"":", schemaSnapshot: LUNORA_SCHEMA_SNAPSHOT",b=Tt(n),T=Ot(m,l.flags),N=Et(d,m,l.flags),$=jt(f),F=Ct(o),{build:ae,contextField:ne,importLines:se,specs:oe}=Lt(At(y)),{build:ie,contextField:de,importLines:ce,specs:le}=It(P,y),U=_t(A,l.server),{build:he,contextField:ue,importLines:pe,specs:me}=Mt(t,i.jurisdiction),{build:ge,contextField:be,importLines:fe,specs:we}=Pt(R),{build:ye,contextField:ve,importLines:ke,specs:Se}=qt(e),{build:Re,configField:xe,contextField:Ae,imports:De,stub:Te}=Nt(n.has("payments")),Oe=a,Ee=r,G=L??{policies:[],roles:[]},Ce=w??{columns:[]},Le=_??{rules:[]},Ie=M??{analytics:!1,auth:!1,containers:!1,flags:!1,kv:!1,mail:!1,notifications:!1,payments:!1,queues:!1,scheduler:!1,storage:!1,vectors:!1,workflows:!1},{constant:_e,override:Me}=$t(R),{constant:Pe,override:qe}=Ft(y),u=c&&i.vectorIndexes.length>0,B=new Set(i.tables.filter(s=>Dt(s)).map(s=>s.name)),Q=u&&i.vectorIndexes.some(s=>B.has(s.table)),x=i.tables.some(s=>s.shardMode==="global"),W=Ut(B),j=i.tables.some(s=>Rt(s)),z=i.tables.some(s=>xt(s)),O=i.tables.some(s=>s.externalSource!==void 0),X=i.tables.some(s=>s.memory===!0),H=i.tables.some(s=>s.shardMode!=="global"&&s.searchIndexes.length>0);if(z&&j)throw new vt("INTERNAL",'lunora codegen: mixing `.global()` (D1) and `.global({ backend: "hyperdrive" })` tables in one app is not supported yet — use a single global backend.');const V=i.tables.length>0,Ne=Zt(i),$e=tr(i),Fe=sr(i),Ue=er(i),J=rr(i),Y=Bt(u,R.length>0,y.length>0,m,H);v&&Y.push("WhereInput");const Z=Wt(x),{customMutatorOverride:Be,shapeGuardImport:We,shapeReadPolicyAssertion:je,shapeReadPolicyImport:He,shapeResolveOverride:Ve}=or({hasMutators:D,hasShapes:v,rlsData:G}),E=[`import type { ${Y.join(", ")} } from "${l.do}";`,`import { applyCdcChanges, ${H?"backfillSearchIndexes, ":""}${u?"backfillVectorIndexes, ":""}buildReprojectionMigration, ${X?"clearMemoryTables, ":""}${We}createReadFootprint, createShardCtxDb, exportShardRows, importShardRows, ${O?"isSourceDue, pullExternalSourceIncrementalTick, pullExternalSourceTick, ":""}markUnvouchableReads, ${Q?"ROOT_SHARD_NAME, ":""}runDataMigration, runShardMigrations, ${Z.importFragment}ShardDO as ShardDOBase } from "${l.do}";`,...O?[`import type { ExternalSourceLike, SourceClientLike, TraceRefLike } from "${l.do}";`]:[],v?`import { asBucketStorage, ${He}beginDeferredDeletes, beginDeferredSchedules, composeShapeReadWhere, createSecrets, flushDeferredDeletes, LunoraError, withDeferredDeletes, withDeferredSchedules } from "${l.server}";`:`import { asBucketStorage, beginDeferredDeletes, beginDeferredSchedules, createSecrets, flushDeferredDeletes, LunoraError, withDeferredDeletes, withDeferredSchedules } from "${l.server}";`];V&&E.push(`import { bindOrm, bindTableFacade } from "${l.server}";`),u&&E.push('import type { SchemaLike as VectorSchemaLike, VectorBackfillSync, VectorizeIndexLike, VectorSearchLike } from "@lunora/bindings/vectors";','import { createContextVectors, createVectorBackfillSync, createVectors, createVectorSyncHook, vectorBackfillTargets } from "@lunora/bindings/vectors";'),E.push(...b.importLines,...T.importLines,...$.importLines,...F.importLines,...pe,...fe,...se,...ce,...U.importLines,...ke,...De,"",'import schema from "../schema.js";',`import { ${["LUNORA_FUNCTIONS","LUNORA_LIFECYCLE_HOOKS","LUNORA_MIGRATIONS",...D?["LUNORA_MUTATOR_PATHS"]:[],...v?["LUNORA_SHAPES"]:[]].join(", ")} } from "./functions.js";`);const Ke=u?`
+    vectors?: (env: Record<string, unknown>) => Record<string, VectorizeIndexLike>;`:"",Ge=z?`
+    d1?: (env: Record<string, unknown>, request?: { bookmark?: string; cdc?: boolean; cdcRetentionMs?: number; identity?: Record<string, unknown>; onBookmark?: (bookmark: string | undefined) => void; userId?: string }) => DatabaseWriterLike | undefined;`:"",Qe=j?`
+    hyperdriveGlobal?: (env: Record<string, unknown>, request?: { cdc?: boolean; cdcRetentionMs?: number; identity?: Record<string, unknown>; userId?: string }) => DatabaseWriterLike | undefined;`:"",ze=O?`
+    sourceClient?: (env: Record<string, unknown>, binding: string) => { query: <Row = Record<string, unknown>>(text: string, params?: readonly unknown[]) => Promise<Row[]> } | undefined;`:"",Xe="ctx.db.<globalTable>: no global backend configured. Pass `d1` or `hyperdriveGlobal` to createShardDO().",Je="ctx.scheduler: no scheduler configured. Pass `scheduler` to createShardDO().",Ye="ctx.storage: no storage configured. Pass `storage` to createShardDO().",Ze=x?C("globalDbStub: DatabaseWriterLike",Xe,["aggregate","count","delete","findFirst","findFirstOrThrow","findMany","get","groupBy","insert","normalizeId","patch","query","rank","rankPage","replace"],{sync:["normalizeId","query"]}):"",{vectorSyncMethod:et,vectorsBuild:tt,vectorsStub:rt}=cr(u,Q?i.vectorIndexes.filter(s=>B.has(s.table)).map(s=>s.name):[]),at=`{
+                ...this.ctxDbTuning(),
+                auth: { identity: identity ?? null, userId: userId ?? null },
+                broadcast: (delta) => {
+                    this.recordChangedTable(delta.table, delta.indexKeys);
+                },
+                // Read at call time, not captured: the baseline belongs to the
+                // dispatch in flight, and a queued mutation admitted after a
+                // sibling's prologue must be judged against ITS caller's cursor.
+                baselineSeq: () => this.getCurrentBaselineSeq(),
+                cdc: config.cdc ?? false,
+                // A dispatch with NO caller identity runs system-trusted: RLS scopes
+                // rows to a user, and these have no user to scope to. This is the tier
+                // migrations, imports and the external-source poll loop already run in
+                // (see \`adminWriterPrelude\`). Only \`onShardInit\` and \`onQueryChange\`
+                // reach it; \`onConnect\`/\`onDisconnect\` carry a verified identity and
+                // stay guarded like any request.
+                enforceRls: options.trusted !== true,
+                headroom: options.headroom ?? this.transactionHeadroom(),
+                // A live predicate, not a flag: the transaction opens AFTER this ctx
+                // is built (a mutation dispatch wraps the handler), so only a call-time
+                // read reports the truth. \`_commitSeq\` reuses one sequence across
+                // writes only while they commit together — an action is not wrapped, so
+                // each of its writes allocates its own.
+                inTransaction: () => this.isInTransaction(),
+                onIndexUse: this.getCtxDbIndexUseHook(),
+                onStalePatchDropped: (event) => {
+                    this.recordStalePatchDropped(event);
+                },
+                // Bound to THIS dispatch's reactive-cache read scope (\`handleRpc\`
+                // threads it in), so two concurrent queries never stamp each
+                // other's dep sets. \`executeSubscription\` overrides both with its
+                // own \`ReadFootprint\` pair instead, and a dispatch with neither
+                // gets an unbound hook that stamps no deps.
+                onRead: options.onRead ?? this.getCtxDbReadHook(options.scope),
+                // Left \`undefined\` when there is no scope so \`createShardCtxDb\`
+                // keeps its own "degrade a provable slice to a whole-table dep"
+                // fallback rather than reporting into a no-op.
+                onReadRange: options.onReadRange ?? (options.scope === undefined ? undefined : this.getCtxDbReadRangeHook(options.scope)),${u?`
+                // Vectorize is outside this shard's SQLite and cannot roll back, so
+                // the sync is held until the mutation's transaction has COMMITTED
+                // (\`deferAfterCommit\`) instead of running inline. Inline, a write
+                // that later aborted left a vector pointing at a row that does not
+                // exist — which a search then surfaces — and a rolled-back delete
+                // left the row with its vector already purged. Outside a
+                // transaction (an action) nothing is open and it runs at once.
+                onWrite: onWrite === undefined ? undefined : (event) => this.deferAfterCommit(() => onWrite(event)),`:""}
+                scheduler,
+                schema: schema as unknown as SchemaLike,
+                sql: this.sql as SqlExec,
+                storage,${x?`
+                globalDb,`:""}
+            }`,nt=u?`
+                vectors,`:"",st=V?`
+                orm: bindOrm(facade),`:"",ee=j?"config.hyperdriveGlobal":"config.d1",ot=x?`            const globalRequest = { ...this.globalCdcOptions(config.cdc ?? false), bookmark: this.getInboundBookmark(), identity, onBookmark: (bookmarkValue: string | undefined) => { if (options.bookmarks !== undefined) { options.bookmarks.value = bookmarkValue; } }, userId };
+            const globalDb: DatabaseWriterLike = ${ee}?.(env, globalRequest) ?? globalDbStub;
+`:"",it=ir(v&&x,ee),{externalSourceOverride:dt,sourceBootstrap:ct,sourceClientCacheConst:lt}=dr(O),ht=`
+        protected override async runShardInit(): Promise<void> {
+            this.ensureMigrated();
+${X?`            clearMemoryTables(this.sql as SqlExec, schema as unknown as SchemaLike);
+`:""}
+            await this.dispatchShardInit();
+        }
+`,ut=J.length>0?`
+            if (LUNORA_TTL_SWEEPS.length > 0) {
+                void this.scheduleTtlSweep();
+            }
+`:"",pt=`
+        public constructor(state: ShardDOState, env: unknown) {
+            super(state, env, {
+                // Every writer this file builds spreads the ctxDbTuning() slice —
+                // the user-facing ctx and all three admin/maintenance writers — so
+                // the base class can drop its coarse invalidation backstop. Only the
+                // emitter can know that; a hand-written subclass leaves this unset
+                // and keeps the backstop.
+                ctxDbCacheWired: true,
+                ...(config.maxRelationKeys === undefined ? {} : { maxRelationKeys: config.maxRelationKeys }),
+                ...(config.reactiveCache ? { reactiveCache: config.reactiveCache === true ? {} : config.reactiveCache } : {}),
+                ...(config.relationExistsPushDown === undefined ? {} : { relationExistsPushDown: config.relationExistsPushDown }),
+                // The same sink \`buildCtx\` resolves, made reachable before any ctx
+                // exists — a trigger that fails first still flushes and fuses.
+                ...(config.observability === undefined ? {} : { telemetrySink: () => config.observability?.((env ?? {}) as Record<string, unknown>) }),
+            });
+${ct}${ut}        }
+
+        protected override isCacheableQuery(functionPath: string): boolean {
+            // NOT \`kind === "query"\` alone. A cache hit answers without running
+            // \`handleRpc\`, so the \`internal\` refusal at the top of it is skipped —
+            // and an \`internalQuery\` primed by a trusted system dispatch was then
+            // served to an anonymous client that the refusal would have 404'd.
+            //
+            // \`perDispatch\` is the same argument one layer out: the procedure's
+            // own \`.use()\` chain runs INSIDE \`handleRpc\`, so a hit skips it too.
+            // A \`.use(rateLimit(...))\` query was therefore charged once and then
+            // served from the memo to every later request — each of which still
+            // reached this Durable Object and still cost it a dispatch, so only
+            // the accounting was skipped. Metering and memoizing are mutually
+            // exclusive; the author asking for the first is choosing against the
+            // second.
+            const registered = LUNORA_FUNCTIONS[functionPath];
+
+            return registered?.kind === "query" && registered.visibility !== "internal" && registered.perDispatch !== true;
+        }
+
+        protected override isPaidFunction(functionPath: string): boolean {
+            return LUNORA_FUNCTIONS[functionPath]?.x402 !== undefined;
+        }
+`,mt=V?`
+            const facade = db as unknown as Record<string, ReturnType<typeof bindTableFacade>>;
+${i.tables.map(s=>`            facade[${JSON.stringify(s.name)}] = bindTableFacade(db, ${JSON.stringify(s.name)});`).join(`
+`)}
+`:"",gt=`${b.everyBuild}${T.build}${F.build}
+            const secrets = createSecrets(env);
+`,bt=`${b.everyFields}${T.contextField}${$.contextField}${F.contextField}
+                secrets,`,ft=$.build,wt=[...b.actionFields,...A.length>0?["services"]:[]],yt=`${b.actionBuild}${U.build}`;return`${Vt}${E.join(`
+`)}
+
+type FunctionKind = "action" | "mutation" | "query";
+
+interface FunctionReference {
+    __lunoraRef: string;
+}
+
+/** Foreign-key columns per table (\`v.id("target")\` fields) for the data browser. */
+const LUNORA_TABLE_REFS = ${h(Ne,"Record<string, Record<string, string>>")};
+
+/** Declared indexes per table (secondary, search, geo, rank, vector) for the schema viewer. */
+const LUNORA_TABLE_INDEXES = ${h($e,'Record<string, Array<{ fields: string[]; name: string; type: "geo" | "index" | "rank" | "search" | "vector"; unique?: boolean }>>')};
+
+/** Columns per table (typed, with PK/FK markers) for the studio's schema diagram, served via \`__lunora_admin__:describeTable\`. */
+const LUNORA_TABLE_COLUMNS = ${h(Fe,`Record<
+    string,
+    Array<{
+        bucket?: string;
+        enumValues?: string[];
+        isStorage?: boolean;
+        name: string;
+        nullable?: boolean;
+        onDelete?: "cascade" | "restrict" | "set null";
+        optional: boolean;
+        pk?: boolean;
+        ref?: string;
+        type: string;
+    }>
+>`)};
+
+/** Storage-key columns per table (\`v.storage(...)\` fields) for the file browser's records↔files join. */
+const LUNORA_STORAGE_COLUMNS = ${h(Ue,"Record<string, string[]>")};
+
+/** Declarative TTL policies (\`.ttl(field, { after? })\`) the DO alarm sweep auto-expires rows for. */
+const LUNORA_TTL_SWEEPS = ${h(J,"Array<{ after?: number; field: string; softDeleteField?: string; table: string }>")};
+
+/** Static schema advisories (computed by @lunora/advisor at codegen time) served via \`__lunora_admin__:getAdvisories\`. */
+const LUNORA_ADVISORIES = ${h(Oe,"AdvisoryFinding[]")};
+
+/** Every declared procedure (discovered by @lunora/codegen) served via \`__lunora_admin__:getAdvisorProcedures\` — the health map's denominator. */
+const LUNORA_ADVISOR_PROCEDURES = ${h(Ee,"AdvisorProcedure[]")};
+
+/** Read-only RLS metadata (policies + roles discovered from \`.use(rls(...))\` chains) served via \`__lunora_admin__:rlsPolicies\` for the studio's RLS inspector. */
+const LUNORA_RLS_METADATA = ${h(G,"RlsPoliciesResult")};
+${je}
+/** Read-only masking metadata (table + column + strategy discovered from \`.use(mask(...))\` chains) served via \`__lunora_admin__:maskPolicies\` for the studio's data-browser mask preview. */
+const LUNORA_MASK_METADATA = ${h(Ce,"MaskPoliciesResult")};
+
+/** Read-only storage access-rule metadata (discovered from \`.use(storageRules(...))\` chains) served via \`__lunora_admin__:storageRules\` for the studio's access-rules view. */
+const LUNORA_STORAGE_RULES = ${h(Le,"StorageRulesResult")};
+
+/** 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 = ${h(Ie,"StudioFeaturesResult")};
+${te}${W.constant}${N.constant}${_e}${Pe}${me}${we}${oe}${le}${U.specs}${Se}
+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;
+    /** Ceiling on the join keys one relation-crossing \`where\` predicate may pre-resolve via semijoin before failing closed. Omit for the engine default. */
+    maxRelationKeys?: number;
+    /** Enable the per-shard reactive query cache: \`true\` for the defaults, or an options object to tune the caps. Query results are memoized by \`(functionPath, args, identity)\` and invalidated by the ctx-db write hooks before the subscription broadcast, so subscribers never observe a pre-write value. Omitted (or \`false\`) keeps every dispatch re-running its handler. */
+    reactiveCache?: boolean | { maxBytes?: number; maxEntries?: number };
+    /** Resolution policy for a relation-crossing \`where\` whose child is co-located in this shard: \`"auto"\` (cost-based, the engine default), \`"always"\` (inline correlated EXISTS) or \`"never"\` (universal semijoin). All three return identical rows. */
+    relationExistsPushDown?: "always" | "auto" | "never";
+    /** Optional telemetry sink. When supplied, each \`ctx.log.*\` call is forwarded to \`sink.onLog\`. Pass the SAME sink you give \`createWorker({ observability })\` (which drives \`onRpc\`) to route both RPC and log events. */
+    observability?: (env: Record<string, unknown>) => TelemetrySink | undefined;
+    /** \`unknown\` because \`@lunora/scheduler\`'s \`Scheduler\` is not assignable to \`SchedulerLike\`; the shard casts it. */
+    scheduler?: (env: Record<string, unknown>) => unknown;
+    /** \`origin\` is the origin the current \`/rpc\` request reached the worker on — the fallback base for signed object URLs when no \`publicBaseUrl\` is configured. \`undefined\` off the synchronous dispatch path. */
+    storage?: (env: Record<string, unknown>, origin?: string) => unknown;${Ke}${b.configFields}${T.configField}${xe}${Ge}${Qe}${ze}${W.configField}
+}
+${C("schedulerStub",Je,["cancel","runAfter","runAt"])}${C("storageStub",Ye,["createMultipartUpload","delete","download","generateUploadUrl","getMetadata","getPresignedUrl","getSignedUrl","getUrl","head","list","resumeMultipartUpload","store","upload"],{sync:["getUrl","resumeMultipartUpload"]})}${Ze}${lt}${rt}${b.stubs}${Te}
+${Xt}
+
+/**
+ * Build the project's shard Durable Object. Export the result as \`ShardDO\`
+ * from the worker entry so wrangler binds it by name.
+ */
+export const createShardDO = (config: ShardDOConfig = {}): new (state: ShardDOState, env: unknown) => ShardDOBase =>
+    class extends ShardDOBase {${pt}
+        private migrated = false;
+
+${Jt}
+${Z.override}
+${Yt}
+${Be}${Ve}${it}${dt}
+        protected override lifecycleHookPaths(event: "connect" | "disconnect" | "init" | "reactor" | "whisper"): readonly string[] {
+            return LUNORA_LIFECYCLE_HOOKS[event];
+        }
+${W.override}${ht}
+        // One \`onQueryChange\` dispatch. Mirrors \`executeSubscription\` — the
+        // socket-terminated half of the same reactivity — and differs only in who
+        // consumes the result: the base's \`dispatchReactors\` stores the digest as
+        // the new baseline and the footprint as the "should I even re-run this"
+        // gate, instead of pushing a frame down a socket.
+        //
+        // Dispatched through \`runMutationTransaction\` because a reactor handler is
+        // a mutation: its writes must commit all-or-nothing, the jobs it schedules
+        // must wait for that commit, and the objects its row deletes orphaned must
+        // be flushed once it lands. Safe to open a span here: the refresh drain
+        // runs OUTSIDE any dispatch transaction (it is post-flush background work),
+        // so this never nests.
+        //
+        // NO identity is threaded, and the ctx is built \`trusted\`. A reactor fires
+        // because data moved, not because anyone asked, so there is no user for RLS
+        // to scope to — it runs in the same system tier as migrations and the
+        // external-source poll loop. Inheriting the shared per-request identity
+        // would instead run an app's reactor as whichever user happened to write
+        // last, which is worse than running it as nobody.
+        protected override async runReactor(functionPath: string, previousDigest?: string): Promise<{ digest: string; ran: boolean; tables: readonly string[] } | undefined> {
+            const registered = LUNORA_FUNCTIONS[functionPath];
+
+            if (!registered || registered.kind !== "mutation") {
+                return undefined;
+            }
+
+            this.ensureMigrated();
+
+            const footprint = createReadFootprint();
+            const ctx = this.buildCtx({ functionPath, headroom: this.subscriptionHeadroom(), onRead: footprint.onRead, onReadRange: footprint.onReadRange, trusted: true });
+            const outcome = (await this.runMutationTransaction(ctx, async () =>
+                registered.handler(ctx, { previousDigest } as unknown as Record<string, unknown>),
+            )) as {
+                digest: string;
+                ran: boolean;
+            };
+
+            return { digest: outcome.digest, ran: outcome.ran, tables: [...footprint.tables] };
+        }
+
+
+        protected override tableRefs(table: string): Record<string, string> | undefined {
+            return LUNORA_TABLE_REFS[table];
+        }
+
+        protected override tableIndexes(table: string): Array<{ fields: string[]; name: string; type: "geo" | "index" | "rank" | "search" | "vector"; unique?: boolean }> {
+            return LUNORA_TABLE_INDEXES[table] ?? [];
+        }
+
+        protected override ttlSweeps(): ReadonlyArray<{ after?: number; field: string; softDeleteField?: string; table: string }> {
+            return LUNORA_TTL_SWEEPS;
+        }
+
+        protected override tableColumns(table: string): Array<{
+            bucket?: string;
+            enumValues?: string[];
+            isStorage?: boolean;
+            name: string;
+            nullable?: boolean;
+            onDelete?: "cascade" | "restrict" | "set null";
+            optional: boolean;
+            pk?: boolean;
+            ref?: string;
+            type: string;
+        }> {
+            return LUNORA_TABLE_COLUMNS[table] ?? [];
+        }
+
+        protected override storageColumns(): Record<string, string[]> {
+            return LUNORA_STORAGE_COLUMNS;
+        }
+
+        protected override rlsMetadata(): RlsPoliciesResult {
+            return LUNORA_RLS_METADATA;
+        }
+
+        protected override maskMetadata(): MaskPoliciesResult {
+            return LUNORA_MASK_METADATA;
+        }
+
+        protected override storageRulesMetadata(): StorageRulesResult {
+            return LUNORA_STORAGE_RULES;
+        }
+
+        protected override studioFeatures(): StudioFeaturesResult {
+            return LUNORA_STUDIO_FEATURES;
+        }
+${N.evaluateOverride}${N.subscriptionOverride}${Me}${qe}
+        protected override advisories(): AdvisoryFinding[] {
+            return LUNORA_ADVISORIES;
+        }
+
+        protected override advisorProcedures(): AdvisorProcedure[] {
+            return LUNORA_ADVISOR_PROCEDURES;
+        }
+
+${Qt}
+
+        protected override ensureMigrated(): void {
+            if (this.migrated) {
+                return;
+            }
+
+            runShardMigrations(this.sql as SqlExec, schema as unknown as SchemaLike, { cdc: config.cdc ?? false${re} });
+            this.migrated = true;
+        }
+${H?`
+        protected override runShardSearchBackfill(options: { maxPages?: number }): SearchBackfillProgress {
+            // Migrations create the fts5 companions; without them every backfill
+            // statement would raise "no such table" on a shard that has never
+            // served a request.
+            this.ensureMigrated();
+
+            return backfillSearchIndexes(this.sql as SqlExec, schema as unknown as SchemaLike, options);
+        }
+`:""}${et}
+${zt({actionOnlyFields:wt,agentsBuild:ye,agentsContextField:ve,containersBuild:he,containersContextField:ue,databaseOptions:at,everyContextBuild:gt,everyContextField:bt,facadeBlock:mt,globalDatabaseLine:ot,notifyBuild:ft,ormContextField:st,paymentsBuild:Re,paymentsContextField:Ae,queuesBuild:ae,queuesContextField:ne,topicsBuild:ie,topicsContextField:de,vectorsBuild:tt,vectorsContextField:nt,workflowsBuild:ge,workflowsContextField:be,actionOnlyBuild:yt})}
+    };
+`};export{er as b,kr as e};