@lunora/do 1.0.0-alpha.30 → 1.0.0-alpha.32

package/dist/packem_shared/{ROOT_DO_SIZE_WARN_BYTES-BA8QOChj.mjs → ROOT_DO_SIZE_WARN_BYTES-BWz51mpB.mjs}

@@ -2,7 +2,7 @@ import { LunoraError, toErrorBody } from '@lunora/errors';
 import { drizzle } from 'drizzle-orm/durable-sqlite';
 import { c as constantTimeEqual } from './constant-time-equal-BVRWZgES.mjs';
 import { j as jsonResponse } from './json-response-BdbtpOhm.mjs';
-import { e as encodeWire, a as awaitWsDrain, t as trySendFrame, d as decodeWire, s as subscriptionListDeltas, b as sendDeltaFrames } from './subscription-delivery-CWigSEr3.mjs';
+import { e as encodeWire, d as decodeWire } from './wire-codec-CzQc1pvf.mjs';
 import { parseExportShardArgs, parseImportShardArgs } from './exportShardRows-Dy3oFZ26.mjs';
 import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
 import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-CYwBpyTr.mjs';
@@ -12,19 +12,84 @@ import { createFanoutCounters, ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX,
 import { LogBuffer } from './LogBuffer-B_Ezju_N.mjs';
 import { recordCapturedMail, clearCapturedMail, readCapturedMail, MAIL_TABLE } from './MAIL_RETENTION-CPpgl-dX.mjs';
 import { readBookmark, armRestore } from './armRestore-4Px61hHS.mjs';
-import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-BYlSGY0N.mjs';
-import { stableStringify } from './stableStringify-MydiuScU.mjs';
+import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-DnSvbjil.mjs';
+import { stableWireKey } from './stableWireKey-DKuXO7T5.mjs';
+import { awaitWsDrain, trySendFrame, subscriptionListDeltas, sendDeltaFrames } from './subscriptionListDeltas-CT76bYny.mjs';
 import { fingerprintError } from '@lunora/fingerprint';
 import { redact, standardRules } from '@visulima/redact';
 import { i as isDevEnvironment, c as buildSettings, b as buildSecurityAudit } from './security-audit-CucgBice.mjs';
-import { runReadonlySql } from './MAX_SQL_ROWS-D57CJaT9.mjs';
+import { runReadonlySql } from './MAX_SQL_ROWS-iFAA8FbD.mjs';
 import { ConflictError } from './ConflictError-CLoq37xH.mjs';
 import { e as deleteGlobalShapeSnapshotsForConnection, g as readIdempotent, h as writeIdempotent, t as trimIdempotent, r as readClientWatermark, m as migrateClientWatermark, c as advanceClientWatermark, d as deleteGlobalShapeSnapshot, f as readGlobalShapeSnapshot, w as writeGlobalShapeSnapshot } from './ctx-db-idempotency-BdcNpvY4.mjs';
 import { CDC_LOG_TABLE, readCdcChanges, readCdcCursor, readCdcEpoch, minCdcSeq, bumpCdcEpoch } from './CDC_LOG_TABLE-DjJEHiM2.mjs';
+import { stableStringify } from './stableStringify-mC40mZts.mjs';
 import { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-Cz9dHyh1.mjs';
 
 const MAX_BATCH_ENTRIES = 500;
 
+const evictOldestEntry = (map, capacity) => {
+  if (map.size < capacity) {
+    return;
+  }
+  const oldest = map.keys().next().value;
+  if (oldest !== void 0) {
+    map.delete(oldest);
+  }
+};
+
+const textEncoder = new TextEncoder();
+const fromBase64Url = (input) => {
+  const padded = input.replaceAll("-", "+").replaceAll("_", "/") + "===".slice((input.length + 3) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.codePointAt(index) ?? 0;
+  }
+  return bytes;
+};
+const KEY_CACHE_MAX = 64;
+const keyCache = /* @__PURE__ */ new Map();
+const importHmacKey = async (secret) => {
+  const cached = keyCache.get(secret);
+  if (cached) {
+    return cached;
+  }
+  evictOldestEntry(keyCache, KEY_CACHE_MAX);
+  const keyPromise = crypto.subtle.importKey("raw", textEncoder.encode(secret), { hash: "SHA-256", name: "HMAC" }, false, ["sign", "verify"]);
+  keyCache.set(secret, keyPromise);
+  return keyPromise;
+};
+const verifyCanonical = async (secret, canonical, sigBytes) => {
+  const cryptoKey = await importHmacKey(secret);
+  return crypto.subtle.verify("HMAC", cryptoKey, sigBytes, textEncoder.encode(canonical));
+};
+
+const WS_ADMIN_TOKEN_VERSION = "v1";
+const verifyWsAdminToken = async (secret, token, now = Date.now()) => {
+  if (secret.length === 0 || token.length === 0) {
+    return false;
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return false;
+  }
+  const [version, expString, signature] = parts;
+  if (version !== WS_ADMIN_TOKEN_VERSION || signature.length === 0) {
+    return false;
+  }
+  const expiresAtMs = Number(expString);
+  if (!Number.isFinite(expiresAtMs) || expiresAtMs <= now) {
+    return false;
+  }
+  let signatureBytes;
+  try {
+    signatureBytes = fromBase64Url(signature);
+  } catch {
+    return false;
+  }
+  return verifyCanonical(secret, `${version}.${expString}`, signatureBytes);
+};
+
 const AUDIT_LOG_TABLE = "__lunora_audit__";
 const AUDIT_LOG_RETENTION = 1e3;
 const runSql$3 = (sql, query, ...params) => {
@@ -321,7 +386,7 @@ const parseRelayName = (name) => {
   return { ownerKey, relayIndex };
 };
 
-const shapeRoutingKey = (name, args) => stableStringify({ args: args ?? {}, name });
+const shapeRoutingKey = (name, args) => stableWireKey({ args: args ?? {}, name });
 const DEFAULT_PROMOTION_THRESHOLDS = { tDown: 4e3, tUp: 8e3 };
 const nextPromotionState = (current, subscribers, thresholds = DEFAULT_PROMOTION_THRESHOLDS) => {
   if (thresholds.tDown >= thresholds.tUp) {
@@ -480,12 +545,12 @@ class RelayLink {
       case "relay_shape_poke": {
         const iterated = this.host.getWebSockets().length;
         const startMs = Date.now();
-        const delivered = this.onShapePoke(message);
+        const delivered = this.onShapePoke({ ...message, args: decodeWire(message.args) });
         this.host.recordShapePokeFanout(iterated, delivered, Date.now() - startMs);
         return noContent();
       }
       case "relay_shape_subscribe": {
-        return jsonRelayResponse(this.onShapeSubscribe(message));
+        return jsonRelayResponse(this.onShapeSubscribe({ ...message, args: decodeWire(message.args) }));
       }
       default: {
         return assertNeverFrame(message);
@@ -677,7 +742,9 @@ class OwnerRelay extends RelayLink {
       }
       entry.cursor = frameCursor;
       const poke = {
-        args: entry.args,
+        // `args` wire-encoded for the same reason as `rowsPatch` below; the
+        // relay decodes them at `handleControl` before the routing match.
+        args: encodeWire(entry.args),
         checkpoint: frameCursor,
         epoch,
         fromCursor,
@@ -724,7 +791,9 @@ class OwnerRelay extends RelayLink {
       }
       entry.cursor = frameCursor;
       const poke = {
-        args: entry.args,
+        // `args` wire-encoded like `rowsPatch`; decoded relay-side at
+        // `handleControl` before the routing match.
+        args: encodeWire(entry.args),
         checkpoint: frameCursor,
         epoch,
         fromCursor,
@@ -859,8 +928,8 @@ class OwnerRelay extends RelayLink {
     if (this.tableHasAnyMask(base.table)) {
       return false;
     }
-    const baseWhere = stableStringify(base.effectiveWhere);
-    const baseColumns = stableStringify(base.columns);
+    const baseWhere = stableWireKey(base.effectiveWhere);
+    const baseColumns = stableWireKey(base.columns);
     let enumerated = false;
     const populate = (side) => {
       const backing = { groups: [`grp_${side}`], roles: [side], sub: `__lunora_probe_${side}__` };
@@ -890,7 +959,7 @@ class OwnerRelay extends RelayLink {
       } catch {
         return false;
       }
-      return resolved !== void 0 && resolved.global !== true && resolved.table === base.table && stableStringify(resolved.effectiveWhere) === baseWhere && stableStringify(resolved.columns) === baseColumns;
+      return resolved !== void 0 && resolved.global !== true && resolved.table === base.table && stableWireKey(resolved.effectiveWhere) === baseWhere && stableWireKey(resolved.columns) === baseColumns;
     });
     return matches && !enumerated;
   }
@@ -938,7 +1007,10 @@ class RelayMember extends RelayLink {
     }
     await this.announce();
     const request = {
-      args: shape.args ?? {},
+      // Wire-encode before the relay->owner `JSON.stringify` hop: the shard
+      // decoded these args at its `shape_subscribe` entry point, so a
+      // `bigint`/`Date`/bytes arg would otherwise throw (or corrupt) here.
+      args: encodeWire(shape.args ?? {}),
       connectionId: this.host.readAttachment(ws).connectionId,
       identity: identity.identity,
       name: shape.name,
@@ -1420,6 +1492,7 @@ const findDanglingReferences = (sql, storageColumns, liveKeys) => {
 
 const WS_KEEPALIVE_PING = "lunora-ping";
 const WS_KEEPALIVE_PONG = "lunora-pong";
+const REQUIRE_EPHEMERAL_ENV_VALUES = /* @__PURE__ */ new Set(["1", "enabled", "on", "true", "yes"]);
 const UNDELIVERED_BASELINE = "<undelivered>";
 const ROOT_DO_SIZE_WARN_BYTES = 1073741824;
 const CDC_RESUME_SCAN_LIMIT = 1e4;
@@ -2512,7 +2585,24 @@ class ShardDO {
         ws.send(JSON.stringify({ id: envelope.id, message: "admin subscription requires admin authorization", type: "error" }));
         return;
       }
-      const status = this.subscribe(ws, envelope.id, envelope.query);
+      let query;
+      try {
+        query = envelope.query.args === void 0 ? envelope.query : { ...envelope.query, args: decodeWire(envelope.query.args) };
+      } catch {
+        try {
+          ws.send(
+            JSON.stringify({
+              code: "BAD_SUBSCRIPTION_ARGS",
+              error: { code: "BAD_SUBSCRIPTION_ARGS", message: "subscription args failed wire decoding" },
+              id: envelope.id,
+              type: "error"
+            })
+          );
+        } catch {
+        }
+        return;
+      }
+      const status = this.subscribe(ws, envelope.id, query);
       if (status !== "ok") {
         const code = status === "too_many" ? "TOO_MANY_SUBSCRIPTIONS" : "SUBSCRIPTION_PERSIST_FAILED";
         const errorMessage = status === "too_many" ? `subscription cap of ${String(ShardDO.MAX_SUBSCRIPTIONS_PER_SOCKET)} reached on this socket` : "failed to persist subscription attachment";
@@ -2524,13 +2614,20 @@ class ShardDO {
       }
       ws.send(JSON.stringify({ id: envelope.id, type: "ack" }));
       if (functionPath) {
-        await this.seedSubscription(ws, envelope.id, envelope.query, functionPath, isAdmin);
+        await this.seedSubscription(ws, envelope.id, query, functionPath, isAdmin);
       }
       return;
     }
     if (envelope.type === "shape_subscribe" && envelope.shape) {
+      let shapeArgs;
+      try {
+        shapeArgs = envelope.shape.args === void 0 ? void 0 : decodeWire(envelope.shape.args);
+      } catch {
+        this.sendShapeSubscribeError(ws, envelope.id, "BAD_SUBSCRIPTION_ARGS", "shape args failed wire decoding");
+        return;
+      }
       await this.handleShapeSubscribe(ws, envelope.id, {
-        args: envelope.shape.args,
+        args: shapeArgs,
         name: envelope.shape.name,
         sinceEpoch: envelope.sinceEpoch,
         sinceSeq: envelope.sinceCheckpoint
@@ -6303,9 +6400,14 @@ class ShardDO {
    * server logs, browser history, and `Referer` headers on any
    * subresource the upgrade page loads after the handshake. Use a
    * short-lived rotating token in production rather than a long-lived
-   * secret.
+   * secret — for the ADMIN credential specifically, the worker mints one
+   * (`POST /_lunora/admin/ws-token`) and {@link isAdminSocket} accepts it, so
+   * the master `LUNORA_ADMIN_TOKEN` never rides the URL.
+   *
+   * Async because the admin fallback ({@link isAdminSocket}) verifies the
+   * ephemeral sub-token with WebCrypto HMAC.
    */
-  isUpgradeAllowed(request) {
+  async isUpgradeAllowed(request) {
     const env = this.env ?? {};
     const allowedOrigins = env.LUNORA_ALLOWED_ORIGINS;
     if (allowedOrigins && allowedOrigins.trim() !== "") {
@@ -6321,7 +6423,7 @@ class ShardDO {
     const expectedBearer = env.LUNORA_WS_BEARER;
     if (expectedBearer && expectedBearer.length > 0) {
       const supplied = this.suppliedWsToken(request);
-      if (!supplied || !constantTimeEqual(supplied, expectedBearer) && !this.isAdminSocket(request)) {
+      if (!supplied || !constantTimeEqual(supplied, expectedBearer) && !await this.isAdminSocket(request)) {
         return false;
       }
     }
@@ -6342,19 +6444,40 @@ class ShardDO {
     return new URL(request.url).searchParams.get("token") ?? void 0;
   }
   /**
-   * Whether the upgrade presented a token matching `LUNORA_ADMIN_TOKEN`,
-   * constant-time compared. Closed (returns `false`) when the admin token is
-   * unset, mirroring `isAdminAuthorized` for the HTTP path so admin
-   * streaming is opt-in rather than exposed by default.
+   * Whether the upgrade presented an admin credential: the master
+   * `LUNORA_ADMIN_TOKEN` (constant-time compared) or a short-lived sub-token
+   * the worker minted with it (`POST /_lunora/admin/ws-token` —
+   * HMAC-verified statelessly here, since both isolates hold the master token
+   * in `env`). The ephemeral token is what the studio sends in `?token=`, so
+   * the master credential stays out of URLs/logs. Closed (resolves `false`)
+   * when the admin token is unset, mirroring `isAdminAuthorized` for the HTTP
+   * path so admin streaming is opt-in rather than exposed by default.
+   *
+   * Enforcement: with `LUNORA_REQUIRE_EPHEMERAL_WS_TOKEN` set
+   * (`1`/`true`/`on`/`yes`/`enabled`), a raw master token in the
+   * `?token=` query parameter is rejected — the query string is exactly
+   * where it leaks. The `Authorization` header path still takes the master
+   * token: browsers can't set it on a WS upgrade, so it never rides a URL.
    */
-  isAdminSocket(request) {
+  async isAdminSocket(request) {
     const env = this.env ?? {};
     const adminToken = env.LUNORA_ADMIN_TOKEN;
     if (!adminToken || adminToken.length === 0) {
       return false;
     }
     const supplied = this.suppliedWsToken(request);
-    return supplied !== void 0 && constantTimeEqual(supplied, adminToken);
+    if (supplied === void 0) {
+      return false;
+    }
+    if (await verifyWsAdminToken(adminToken, supplied)) {
+      return true;
+    }
+    const fromQuery = extractBearerToken(request.headers.get("authorization")) === void 0;
+    const requireEphemeral = REQUIRE_EPHEMERAL_ENV_VALUES.has((env.LUNORA_REQUIRE_EPHEMERAL_WS_TOKEN ?? "").trim().toLowerCase());
+    if (fromQuery && requireEphemeral) {
+      return false;
+    }
+    return constantTimeEqual(supplied, adminToken);
   }
   /**
    * Register the hibernation-safe ping/pong keepalive. The runtime answers a
@@ -6396,10 +6519,11 @@ class ShardDO {
     }
     return void 0;
   }
-  handleWebSocketUpgrade(request) {
-    if (!this.isUpgradeAllowed(request)) {
+  async handleWebSocketUpgrade(request) {
+    if (!await this.isUpgradeAllowed(request)) {
       return new Response("Forbidden", { status: 403 });
     }
+    const admin = await this.isAdminSocket(request);
     const pair = new WebSocketPair();
     const client = pair[0];
     const server = pair[1];
@@ -6409,7 +6533,7 @@ class ShardDO {
     const expiresAtRaw = Number(request.headers.get("x-lunora-identity-exp"));
     const expiresAt = Number.isFinite(expiresAtRaw) && expiresAtRaw > 0 ? expiresAtRaw : void 0;
     server.serializeAttachment?.({
-      admin: this.isAdminSocket(request),
+      admin,
       connectionId: crypto.randomUUID(),
       subs: {},
       ...expiresAt === void 0 ? {} : { expiresAt },

package/dist/packem_shared/{ReactiveCache-BYlSGY0N.mjs → ReactiveCache-DnSvbjil.mjs}

@@ -1,5 +1,6 @@
-import { stableStringify } from './stableStringify-MydiuScU.mjs';
+import { stableWireKey } from './stableWireKey-DKuXO7T5.mjs';
 import { depKey, SCAN_DEP } from './SCAN_DEP-DLJF8dsj.mjs';
+export { stableStringify } from './stableStringify-mC40mZts.mjs';
 
 const DEFAULT_MAX_ENTRIES = 1e3;
 const DEFAULT_MAX_BYTES = 4 * 1024 * 1024;
@@ -227,6 +228,6 @@ class ReactiveCache {
     }
   }
 }
-const reactiveCacheKey = (functionPath, args, identity) => `${identity ?? "\0anon"}\0${functionPath}:${stableStringify(args)}`;
+const reactiveCacheKey = (functionPath, args, identity) => `${identity ?? "\0anon"}\0${functionPath}:${stableWireKey(args)}`;
 
-export { ReactiveCache, reactiveCacheKey, stableStringify };
+export { ReactiveCache, reactiveCacheKey, stableWireKey };

package/dist/packem_shared/{diffExternalSource-Cx9HUPJj.mjs → diffExternalSource-CovHfdyo.mjs}

@@ -1,4 +1,4 @@
-import { stableStringify } from './stableStringify-MydiuScU.mjs';
+import { stableStringify } from './stableStringify-mC40mZts.mjs';
 
 const projectExternalSourceRow = (row, columns) => {
   const projected = { _id: row._id };

package/dist/packem_shared/isSoftDeleted-i5kKh6Up.mjs

@@ -0,0 +1,183 @@
+import { LunoraError } from '@lunora/errors';
+import { sql } from 'drizzle-orm';
+import { r as runDrizzle } from './do-exec-5eQy5cEi.mjs';
+import { runExternalSourceTick, materializeExternalRowsIncremental } from './materializeExternalRows-FyA5Rwn4.mjs';
+
+const SOURCE_CURSOR_TABLE = "__lunora_source_cursor";
+const serializeCursor = (value) => {
+  if (value instanceof Date) {
+    return `d:${value.toISOString()}`;
+  }
+  if (typeof value === "bigint") {
+    return `b:${value.toString()}`;
+  }
+  if (typeof value === "number") {
+    return `n:${value.toString()}`;
+  }
+  return `s:${value}`;
+};
+const deserializeCursor = (text) => {
+  const rest = text.slice(2);
+  switch (text[0]) {
+    case "b": {
+      return BigInt(rest);
+    }
+    case "d": {
+      return new Date(rest);
+    }
+    case "n": {
+      return Number(rest);
+    }
+    default: {
+      return rest;
+    }
+  }
+};
+const INTEGER_STRING = /^-?\d+$/;
+const DECIMAL_STRING = /^-?\d+(?:\.\d+)?$/;
+const cursorAfter = (a, b) => {
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() > b.getTime();
+  }
+  if (typeof a === "bigint" && typeof b === "bigint") {
+    return a > b;
+  }
+  if (typeof a === "number" && typeof b === "number") {
+    return a > b;
+  }
+  if (typeof a === "string" && typeof b === "string" && DECIMAL_STRING.test(a) && DECIMAL_STRING.test(b)) {
+    if (INTEGER_STRING.test(a) && INTEGER_STRING.test(b)) {
+      return BigInt(a) > BigInt(b);
+    }
+    return Number(a) > Number(b);
+  }
+  return String(a) > String(b);
+};
+const maxCursorValue = (rows, column, current) => {
+  let best = current === null ? void 0 : deserializeCursor(current);
+  for (const row of rows) {
+    const raw = row[column];
+    if (raw === null || raw === void 0) {
+      continue;
+    }
+    const value = raw;
+    if (best === void 0 || cursorAfter(value, best)) {
+      best = value;
+    }
+  }
+  return best === void 0 ? null : serializeCursor(best);
+};
+const migrateSourceCursor = (sql$1) => {
+  runDrizzle(
+    sql$1,
+    sql`CREATE TABLE IF NOT EXISTS ${sql.identifier(SOURCE_CURSOR_TABLE)} (
+            table_name TEXT NOT NULL,
+            shard_key TEXT NOT NULL,
+            watermark TEXT,
+            last_reconcile_ms INTEGER,
+            PRIMARY KEY (table_name, shard_key)
+        )`
+  );
+};
+const readSourceCursor = (sql$1, table, shardKey) => {
+  const rows = runDrizzle(
+    sql$1,
+    sql`SELECT watermark, last_reconcile_ms FROM ${sql.identifier(SOURCE_CURSOR_TABLE)} WHERE table_name = ${table} AND shard_key = ${shardKey} LIMIT 1`
+  ).toArray();
+  const row = rows[0];
+  return { lastReconcileMs: row?.last_reconcile_ms ?? null, watermark: row?.watermark ?? null };
+};
+const writeSourceCursor = (sql$1, table, shardKey, state) => {
+  runDrizzle(
+    sql$1,
+    sql`INSERT INTO ${sql.identifier(SOURCE_CURSOR_TABLE)} (table_name, shard_key, watermark, last_reconcile_ms)
+             VALUES (${table}, ${shardKey}, ${state.watermark}, ${state.lastReconcileMs})
+             ON CONFLICT(table_name, shard_key) DO UPDATE SET watermark = excluded.watermark, last_reconcile_ms = excluded.last_reconcile_ms`
+  );
+};
+
+const liftSourceId = (row, options = {}) => {
+  const { idColumn = "id", map } = options;
+  const idValue = row[idColumn];
+  if (idValue === void 0 || idValue === null) {
+    throw new LunoraError("INTERNAL", `external-source: row is missing id column "${idColumn}"`);
+  }
+  if (typeof idValue !== "string" && typeof idValue !== "number" && typeof idValue !== "bigint") {
+    throw new TypeError(`external-source: id column "${idColumn}" must be a string or number`);
+  }
+  const id = String(idValue);
+  if (map) {
+    return { ...map(row), _id: id };
+  }
+  const body = {};
+  for (const [key, value] of Object.entries(row)) {
+    if (key !== idColumn) {
+      body[key] = value;
+    }
+  }
+  return { ...body, _id: id };
+};
+const isSourceDue = (refresh, lastPolledMs, nowMs) => {
+  if (refresh === "manual") {
+    return false;
+  }
+  if (refresh === void 0 || lastPolledMs === void 0) {
+    return true;
+  }
+  return nowMs - lastPolledMs >= refresh.everyMs;
+};
+const pullAndLift = async (client, query, parameters, source) => {
+  const rows = await client.query(query, parameters);
+  const documents = rows.map((row) => liftSourceId(row, { idColumn: source.idColumn, map: source.map }));
+  return { documents, rows };
+};
+const pullExternalSourceTick = async (sql, writer, client, table, source, shardKey) => {
+  const parameters = source.tenantBy ? source.tenantBy(shardKey) : [];
+  const { documents } = await pullAndLift(client, source.query, parameters, source);
+  return runExternalSourceTick(sql, writer, documents, { columns: source.columns, table });
+};
+const isSoftDeleted = (row, column) => {
+  const value = row[column];
+  return value !== null && value !== void 0 && value !== false && value !== 0;
+};
+const pullExternalSourceIncrementalTick = async (sql, writer, client, table, source, shardKey, nowMs) => {
+  const { cursor } = source;
+  if (!cursor) {
+    throw new LunoraError(
+      "INTERNAL",
+      `external-source: table "${table}" is mode "incremental" but has no \`cursor\` — this should have been rejected at defineSchema`
+    );
+  }
+  migrateSourceCursor(sql);
+  const state = readSourceCursor(sql, table, shardKey);
+  const tenantParameters = source.tenantBy ? source.tenantBy(shardKey) : [];
+  const reconcileDue = source.reconcileEveryMs !== void 0 && (state.lastReconcileMs === null || nowMs - state.lastReconcileMs >= source.reconcileEveryMs);
+  const fullPull = state.watermark === null || reconcileDue;
+  let slice;
+  let applied;
+  if (state.watermark === null || reconcileDue) {
+    slice = await pullAndLift(client, source.query, tenantParameters, source);
+    ({ applied } = await runExternalSourceTick(sql, writer, slice.documents, { columns: source.columns, table }));
+  } else {
+    slice = await pullAndLift(client, cursor.query, [...tenantParameters, deserializeCursor(state.watermark)], source);
+    const { softDeleteColumn } = source;
+    const deletedIds = softDeleteColumn ? new Set(
+      slice.documents.flatMap((document, index) => {
+        const row = slice.rows[index];
+        return row && isSoftDeleted(row, softDeleteColumn) ? [String(document._id)] : [];
+      })
+    ) : void 0;
+    ({ applied } = await materializeExternalRowsIncremental(writer, slice.documents, { columns: source.columns, deletedIds, table }));
+  }
+  const watermark = maxCursorValue(slice.rows, cursor.column, state.watermark);
+  if (fullPull && watermark === null && slice.rows.length > 0) {
+    throw new LunoraError(
+      "INTERNAL",
+      `external-source: table "${table}" (mode "incremental") pulled ${String(slice.rows.length)} rows but none carry the cursor column "${cursor.column}" — the seed \`query\` must project it (matching \`cursor.query\`'s alias), or the watermark can never advance.`
+    );
+  }
+  writeSourceCursor(sql, table, shardKey, { lastReconcileMs: fullPull ? nowMs : state.lastReconcileMs, watermark });
+  return { applied };
+};
+
+export { isSoftDeleted, isSourceDue, liftSourceId, pullExternalSourceIncrementalTick, pullExternalSourceTick };

package/dist/packem_shared/{materializeExternalRows-CTqZisSC.mjs → materializeExternalRows-FyA5Rwn4.mjs}

@@ -1,13 +1,32 @@
 import { applyCdcChanges } from './CDC_LOG_TABLE-DjJEHiM2.mjs';
 import { s as selectShapeRows } from './ctx-db-shapes-Cz9dHyh1.mjs';
-import { diffExternalSource, projectExternalSourceRow } from './diffExternalSource-Cx9HUPJj.mjs';
-import { stableStringify } from './stableStringify-MydiuScU.mjs';
+import { diffExternalSource, projectExternalSourceRow } from './diffExternalSource-CovHfdyo.mjs';
+import { stableStringify } from './stableStringify-mC40mZts.mjs';
 
 const materializeExternalRows = async (writer, pulled, baseline, options) => {
   const { changes, nextBaseline } = diffExternalSource(pulled, baseline, options);
   await applyCdcChanges(writer, changes);
   return { applied: changes.length, nextBaseline };
 };
+const materializeExternalRowsIncremental = async (writer, pulled, options) => {
+  const { columns, deletedIds, table } = options;
+  const changes = [];
+  for (const source of pulled) {
+    const value = projectExternalSourceRow(source, columns);
+    const id = String(value._id);
+    if (deletedIds?.has(id)) {
+      changes.push({ id, op: "delete", seq: 0, table, ts: 0 });
+      continue;
+    }
+    const stored = await writer.get(id, table);
+    if (stored && stableStringify(projectExternalSourceRow({ ...stored, _id: id }, columns)) === stableStringify(value)) {
+      continue;
+    }
+    changes.push({ doc: value, id, op: "insert", seq: 0, table, ts: 0 });
+  }
+  await applyCdcChanges(writer, changes);
+  return { applied: changes.length };
+};
 const readExternalSourceBaseline = (sql, table, columns) => {
   const baseline = /* @__PURE__ */ new Map();
   for (const { doc, id } of selectShapeRows(sql, table, void 0)) {
@@ -20,4 +39,4 @@ const runExternalSourceTick = async (sql, writer, pulled, options) => {
   return materializeExternalRows(writer, pulled, baseline, options);
 };
 
-export { materializeExternalRows, readExternalSourceBaseline, runExternalSourceTick };
+export { materializeExternalRows, materializeExternalRowsIncremental, readExternalSourceBaseline, runExternalSourceTick };

package/dist/packem_shared/{stableStringify-MydiuScU.mjs → stableStringify-mC40mZts.mjs}

@@ -9,7 +9,7 @@ const stableStringify = (value) => {
     return "null";
   }
   if (typeof value === "bigint") {
-    throw new TypeError("stableStringify: cannot use a bigint in a cache key (query/subscription/shape args) — pass it as a string");
+    throw new TypeError("stableStringify: cannot use a bigint in a stable JSON cache key — pass it as a string, or use stableWireKey");
   }
   if (value === null || typeof value !== "object") {
     return JSON.stringify(value);
@@ -21,7 +21,7 @@ const stableStringify = (value) => {
   if (proto !== null && proto !== Object.prototype) {
     const name = value.constructor?.name ?? "value";
     throw new TypeError(
-      `stableStringify: cannot use a ${name} in a cache key (query/subscription/shape args) — only plain objects, arrays, and JSON primitives are supported`
+      `stableStringify: cannot use a ${name} in a stable JSON cache key — only plain objects, arrays, and JSON primitives are supported (wire-typed values key via stableWireKey)`
     );
   }
   const record = value;

package/dist/packem_shared/stableWireKey-DKuXO7T5.mjs

@@ -0,0 +1,6 @@
+import { stableStringify } from './stableStringify-mC40mZts.mjs';
+import { e as encodeWire } from './wire-codec-CzQc1pvf.mjs';
+
+const stableWireKey = (value) => stableStringify(encodeWire(value));
+
+export { stableWireKey };