@lunora/do 1.0.0-alpha.31 → 1.0.0-alpha.33

package/dist/index.d.mts

@@ -2407,6 +2407,11 @@ interface MaterializeResult {
   /** `id → projected-value JSON` — the post-tick membership, to feed back as `baseline` next tick. */
   nextBaseline: Map<string, string>;
 }
+/** The outcome of one incremental materialize pass. No baseline: incremental applies only the pulled slice, never a full-membership diff. */
+interface IncrementalMaterializeResult {
+  /** Number of `CdcChange`s applied (upserts + tombstone deletes) for the pulled slice. */
+  applied: number;
+}
 /**
 * Diff `pulled` against `baseline` and apply the delta to `writer`. Returns the
 * applied count and the next baseline. A steady-state tick (membership unchanged)
@@ -2417,6 +2422,36 @@ declare const materializeExternalRows: (writer: DatabaseWriterLike, pulled: Read
   table: string;
 }) => Promise<MaterializeResult>;
 /**
+* Apply an **incremental** slice (plan 136): the freshly-pulled rows changed since
+* the watermark, upsert-only. Unlike {@link materializeExternalRows} this reads no
+* baseline and never diffs the full membership — an absent row means "unchanged
+* since the watermark", NOT "deleted". Each pulled row is projected with the SAME
+* {@link projectExternalSourceRow} full-pull uses, so an incrementally-upserted row
+* is byte-identical to how the next reconcile sweep's full-pull would store it (no
+* spurious update on reconcile).
+*
+* Delete visibility comes from `deletedIds` — the ids the caller resolved from the
+* source's soft-delete tombstone column. Every other pulled row is an `insert`,
+* which {@link applyCdcChanges} upserts (insert, or replace on conflict), so a
+* changed existing row is updated and a genuinely new row is inserted without the
+* caller tracking which is which.
+*
+* **Content short-circuit.** An incremental cursor query uses `>= watermark` (so
+* rows sharing the boundary value are never skipped), which means a steady-state
+* tick re-pulls the boundary row(s) unchanged. Blindly upserting them would append
+* a `__cdc_log` entry, broadcast a spurious `update` to every `defineShape`
+* subscriber, re-run search/aggregate/rank sync, and fire `onWrite` (a Vectorize
+* re-embed = real cost) on every tick — and `replace` would reset `_creationTime`.
+* So each row is diffed against its stored projection (the SAME
+* {@link projectExternalSourceRow} + {@link stableStringify} full-pull uses) and
+* skipped when byte-identical — mirroring the full-pull diff's steady-state no-op.
+*/
+declare const materializeExternalRowsIncremental: (writer: DatabaseWriterLike, pulled: ReadonlyArray<Record<string, unknown>>, options: {
+  columns?: ReadonlyArray<string>;
+  deletedIds?: ReadonlySet<string>;
+  table: string;
+}) => Promise<IncrementalMaterializeResult>;
+/**
 * Read the materialized table's current membership as the canonical full-pull
 * baseline (`id → canonical JSON`). Reuses the shape scanner (`selectShapeRows`)
 * and the SAME {@link projectExternalSourceRow} + {@link stableStringify} the diff
@@ -2445,23 +2480,50 @@ interface SourceClientLike {
 type SourceRefresh = "manual" | {
   everyMs: number;
 };
+/** The incremental cursor config (plan 136): the watermark column + the watermark-parameterized pull query. */
+interface SourceCursorLike {
+  column: string;
+  query: string;
+}
 /** The runtime `.source(...)` config the poll loop reads — a structural mirror of `@lunora/server`'s `ExternalSourceDefinition` (only the fields the tick uses). */
 interface ExternalSourceLike {
   binding: string;
   columns?: ReadonlyArray<string>;
+  cursor?: SourceCursorLike;
   idColumn?: string;
   map?: (row: Record<string, unknown>) => Record<string, unknown>;
+  mode?: string;
   query: string;
+  reconcileEveryMs?: number;
   refresh?: SourceRefresh;
+  softDeleteColumn?: string;
   tenantBy?: (shardKey: string) => ReadonlyArray<unknown>;
 }
+/**
+* Coerce a driver-native value that `stableStringify` can't represent (see
+* `shared/stable-key.ts`) into its JSON-safe form: a `Date` → its ISO string, a
+* `bigint` → its decimal string. Every other value passes through unchanged.
+*
+* node-pg / postgres-js / mysql2 return `timestamp`/`datetime` columns as JS
+* `Date` and `bigint`/`int8` columns as `bigint` — both throw a `TypeError` out of
+* `stableStringify` (used by the full-pull diff and the incremental content
+* short-circuit), which bricks ingest for any table with such a column (e.g. the
+* canonical `cursor: { column: "updated_at" }` incremental config). This is the
+* single boundary where driver-native types cross into DO SQLite JSON; a new
+* source driver (or a new non-JSON column type) must be normalized here too.
+* `shared/stable-key.ts`'s throw contract is intentionally left unchanged — this
+* normalizes the value *before* it can ever reach that encoder.
+*/
+
 /**
 * Lift an external row to a Lunora document: the `idColumn` value becomes a
 * stringified `_id`, then either `map` shapes the body or every other column is
 * copied verbatim. Throws on a missing/null id, and on a non-scalar id, so a
 * misconfigured query fails loudly instead of materializing rows under the literal
 * id `"undefined"` (or collapsing many rows onto one id). Shared with
-* `@lunora/hyperdrive`'s `projectSourceRow`.
+* `@lunora/hyperdrive`'s `projectSourceRow`. The returned document's values are
+* normalized (see {@link normalizeSourceValue}) so a `Date`/`bigint` column never
+* reaches `stableStringify` un-normalized.
 */
 declare const liftSourceId: (row: Record<string, unknown>, options?: {
   idColumn?: string;
@@ -2482,6 +2544,39 @@ declare const isSourceDue: (refresh: SourceRefresh | undefined, lastPolledMs: nu
 */
 declare const pullExternalSourceTick: (sql: SqlExec, writer: DatabaseWriterLike, client: SourceClientLike, table: string, source: ExternalSourceLike, shardKey: string) => Promise<MaterializeResult>;
 /**
+* Whether an upstream row is a soft-delete tombstone under `column`. A set
+* `deleted_at` (any non-null value, e.g. a timestamp), an `is_deleted = true`, or a
+* non-zero flag all read as deleted; `null` / `undefined` / `false` / `0` mean
+* live. Note an **empty string** reads as deleted (`"" !== 0`), so an upstream that
+* clears the column to `""` rather than `NULL` for a live row would mis-signal —
+* use `NULL` for live rows. The incremental query MUST return tombstoned rows
+* (don't filter `WHERE deleted_at IS NULL`) or the delete is never observed.
+*/
+declare const isSoftDeleted: (row: Record<string, unknown>, column: string) => boolean;
+/**
+* Run one **incremental** tick (plan 136). Reads the durable watermark for
+* `(table, shardKey)`; on the first ever poll or when the `reconcileEveryMs` sweep
+* is due it runs a **full-pull** (seed/GC: {@link runExternalSourceTick} observes
+* deletes and re-establishes membership), otherwise it pulls only rows past the
+* watermark via `cursor.query` and upserts them ({@link materializeExternalRowsIncremental},
+* tombstones → deletes). Either way it advances the watermark to the max cursor
+* value seen and persists it (and the reconcile timestamp).
+*
+* **Crash safety** is by ordering + idempotency, NOT an atomic transaction across
+* the two write channels (the apply goes through the `writer`; the watermark write
+* is a raw `sql` write): the watermark advances only AFTER a fully-applied slice,
+* so a crash between the apply and the watermark write leaves the watermark behind
+* and the next tick re-pulls the same `>= watermark` slice — which the upsert
+* short-circuits (unchanged rows) or re-applies idempotently. It only ever replays,
+* never skips (same self-healing argument as `advanceClientWatermark`).
+*
+* Requires `source.cursor` (validated at `defineSchema` for incremental mode); a
+* missing cursor throws rather than silently degrading to a stuck watermark.
+*/
+declare const pullExternalSourceIncrementalTick: (sql: SqlExec, writer: DatabaseWriterLike, client: SourceClientLike, table: string, source: ExternalSourceLike, shardKey: string, nowMs: number) => Promise<{
+  applied: number;
+}>;
+/**
 * Reserved `functionPath` prefix for admin introspection RPCs. These travel
 * over the same `/_lunora/rpc` → shard `/rpc` path as ordinary functions, but
 * `ShardDO` intercepts them before user dispatch and serves them from the
@@ -4325,6 +4420,19 @@ declare abstract class ShardDO {
   private static rootSizeWarned;
   /** Test-only: reset the static "warned once" flag. */
   static resetRootSizeWarning(): void;
+  /**
+  * Compute the shared poll alarm's next wake time from both tiers' signals.
+  * Global shapes need the fixed `GLOBAL_SHAPE_POLL_INTERVAL_MS` floor whenever
+  * any are subscribed (a global table has no per-DO op-log, so it can only be
+  * polled). External-source ingest instead reports the earliest NEXT-DUE
+  * timestamp across its non-manual sources (or `undefined` when none exist) —
+  * a source with a large `refresh.everyMs` must sleep until it's actually due,
+  * not spin at the global-shape floor. Returns `undefined` when NEITHER tier
+  * has pending work, so the DO can go fully idle instead of re-arming for no
+  * reason; otherwise the earlier of the two candidate times (never later than
+  * `nowMs`, so a source that's already due arms essentially immediately).
+  */
+  private static nextPollAlarmTarget;
   protected state: ShardDOState;
   protected env: unknown;
   /**
@@ -4656,12 +4764,17 @@ declare abstract class ShardDO {
   /** Hibernation API: invoked on socket error. */
   webSocketError(_ws: WebSocket, _error: unknown): void;
   /**
-  * Durable Object alarm handler — the heartbeat for `.global()`-table shapes.
-  * The runtime wakes this when the poll alarm armed by `scheduleGlobalPoll`
-  * fires; it refreshes every subscribed global shape (diff-poke from the global
-  * backend) and re-arms while any remain. With no global subscribers left, the
-  * alarm is not re-armed and the DO goes idle. A base-only / global-free DO
-  * never arms it, so this stays dormant there.
+  * Durable Object alarm handler — the heartbeat for `.global()`-table shapes
+  * AND external-source (`.source(...)`) ingest, which share one alarm. The
+  * runtime wakes this when the poll alarm armed by `scheduleGlobalPoll` fires;
+  * it refreshes every subscribed global shape (diff-poke from the global
+  * backend), materializes any due sourced tables, and re-arms at
+  * {@link ShardDO.nextPollAlarmTarget} — the fixed floor while global shapes
+  * are subscribed, or the earliest source next-due time when only ingest
+  * remains (so a 1-hour-`refresh` source sleeps ~1 hour instead of waking
+  * every 2 s). With neither tier pending, the alarm is not re-armed and the DO
+  * goes idle. A base-only / global-free / source-free DO never arms it, so
+  * this stays dormant there.
   */
   alarm(): Promise<void>;
   /** Subclasses implement function dispatch. */
@@ -5328,16 +5441,23 @@ declare abstract class ShardDO {
   /**
   * Poll external-source (`.source(...)`) tables once (plan 077): materialize
   * each sourced table's freshly-pulled tenant slice into this DO's SQLite. The
-  * base `ShardDO` has no sourced tables, so it returns `0` and the ingest tier
-  * stays dormant — zero behavior change for every existing DO. The codegen
-  * subclass overrides it to, per sourced table, build a `createShardCtxDb`
-  * writer, read the tenant slice from Hyperdrive under this DO's shard key, and
-  * run `runExternalSourceTick` (read local baseline → diff → apply via the
-  * validated CDC writer). Returns the number of sourced tables still being
-  * polled, so the shared poll alarm ({@link ShardDO.alarm}) re-arms while ingest
-  * is active.
+  * base `ShardDO` has no sourced tables, so it returns `undefined` and the
+  * ingest tier stays dormant — zero behavior change for every existing DO. The
+  * codegen subclass overrides it to, per sourced table, build a
+  * `createShardCtxDb` writer, read the tenant slice from Hyperdrive under this
+  * DO's shard key, and run `runExternalSourceTick` (read local baseline → diff
+  * → apply via the validated CDC writer).
+  *
+  * Returns the EARLIEST next-due timestamp (absolute epoch ms) across every
+  * non-manual sourced table — `polledAt.get(table) ?? now` plus that source's
+  * `refresh.everyMs` — or `undefined` when every sourced table is
+  * `refresh: "manual"` (or there are none). NOT a bare active count: the
+  * shared poll alarm ({@link ShardDO.alarm}) uses this to re-arm at the exact
+  * next time ingest needs to run, instead of spinning at the fixed
+  * `GLOBAL_SHAPE_POLL_INTERVAL_MS` floor for a source whose `refresh.everyMs`
+  * is, say, an hour away.
   */
-  protected pollExternalSources(): Promise<number>;
+  protected pollExternalSources(): Promise<number | undefined>;
   /**
   * Arm the shared poll alarm for external-source ingest (plan 077). The alarm is
   * shared with the global-shape poll tier; the codegen subclass calls this once
@@ -6337,11 +6457,18 @@ declare abstract class ShardDO {
   */
   private saveGlobalSnapshot;
   /**
-  * Arm the poll alarm for `.global()` shapes if one isn't already pending.
-  * Idempotent — every global-shape seed calls it, but only the first arms the
-  * alarm. Degrades to a no-op when the runtime exposes no `setAlarm` (the unit
-  * harness): a global shape is then seed-only, which the poll-loop tests assert
-  * by driving {@link ShardDO.alarm} directly.
+  * Arm the poll alarm if one isn't already pending. Idempotent — every
+  * global-shape seed calls it, but only the first arms the alarm. Degrades to
+  * a no-op when the runtime exposes no `setAlarm` (the unit harness): a global
+  * shape is then seed-only, which the poll-loop tests assert by driving
+  * {@link ShardDO.alarm} directly.
+  *
+  * `atMs` lets {@link ShardDO.alarm} re-arm at a computed target — the
+  * earlier of the fixed global-shape floor and the earliest external-source
+  * next-due time — instead of always the fixed floor. Every OTHER caller
+  * (a fresh global-shape seed, {@link ShardDO.scheduleSourcePoll}'s initial
+  * kick) omits it and gets the original `GLOBAL_SHAPE_POLL_INTERVAL_MS`
+  * default, since neither knows a more precise due time yet.
   */
   private scheduleGlobalPoll;
   /**
@@ -6704,4 +6831,4 @@ interface WhereSqlStrategy {
 * `undefined` when the input imposes no constraint (empty `where`).
 */
 declare const compileWhereSql: (where: WhereInput | undefined, strategy: WhereSqlStrategy) => SQL | undefined;
-export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, type ExternalSourceDiffResult, type ExternalSourceLike, FLAGS_FUNCTION_PREFIX, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FlagEvaluation, type FlagsResult, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MaterializeResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type SchedulableWorkflowReferenceLike, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, type ShapeSubscriptionQuery, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection, type SourceClientLike, type SourceRefresh, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertShapeShardable, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createShardCtxDb, createSystemReader, decodeCursor, depKey, diffExternalSource, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, fanOutScalarCounts, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, isSourceDue, liftSourceId, listTables, matchesRankStaticWhere, matchesStaticWhere, materializeExternalRows, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, pullExternalSourceTick, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readExternalSourceBaseline, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runExternalSourceTick, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, softDeleteScope, sortColumnName, stableStringify, stableWireKey, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };
+export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, type ExternalSourceDiffResult, type ExternalSourceLike, FLAGS_FUNCTION_PREFIX, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FlagEvaluation, type FlagsResult, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IncrementalMaterializeResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MaterializeResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type SchedulableWorkflowReferenceLike, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, type ShapeSubscriptionQuery, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection, type SourceClientLike, type SourceCursorLike, type SourceRefresh, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertShapeShardable, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createShardCtxDb, createSystemReader, decodeCursor, depKey, diffExternalSource, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, fanOutScalarCounts, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, isSoftDeleted, isSourceDue, liftSourceId, listTables, matchesRankStaticWhere, matchesStaticWhere, materializeExternalRows, materializeExternalRowsIncremental, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, pullExternalSourceIncrementalTick, pullExternalSourceTick, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readExternalSourceBaseline, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runExternalSourceTick, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, softDeleteScope, sortColumnName, stableStringify, stableWireKey, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };

package/dist/index.d.ts

@@ -2407,6 +2407,11 @@ interface MaterializeResult {
   /** `id → projected-value JSON` — the post-tick membership, to feed back as `baseline` next tick. */
   nextBaseline: Map<string, string>;
 }
+/** The outcome of one incremental materialize pass. No baseline: incremental applies only the pulled slice, never a full-membership diff. */
+interface IncrementalMaterializeResult {
+  /** Number of `CdcChange`s applied (upserts + tombstone deletes) for the pulled slice. */
+  applied: number;
+}
 /**
 * Diff `pulled` against `baseline` and apply the delta to `writer`. Returns the
 * applied count and the next baseline. A steady-state tick (membership unchanged)
@@ -2417,6 +2422,36 @@ declare const materializeExternalRows: (writer: DatabaseWriterLike, pulled: Read
   table: string;
 }) => Promise<MaterializeResult>;
 /**
+* Apply an **incremental** slice (plan 136): the freshly-pulled rows changed since
+* the watermark, upsert-only. Unlike {@link materializeExternalRows} this reads no
+* baseline and never diffs the full membership — an absent row means "unchanged
+* since the watermark", NOT "deleted". Each pulled row is projected with the SAME
+* {@link projectExternalSourceRow} full-pull uses, so an incrementally-upserted row
+* is byte-identical to how the next reconcile sweep's full-pull would store it (no
+* spurious update on reconcile).
+*
+* Delete visibility comes from `deletedIds` — the ids the caller resolved from the
+* source's soft-delete tombstone column. Every other pulled row is an `insert`,
+* which {@link applyCdcChanges} upserts (insert, or replace on conflict), so a
+* changed existing row is updated and a genuinely new row is inserted without the
+* caller tracking which is which.
+*
+* **Content short-circuit.** An incremental cursor query uses `>= watermark` (so
+* rows sharing the boundary value are never skipped), which means a steady-state
+* tick re-pulls the boundary row(s) unchanged. Blindly upserting them would append
+* a `__cdc_log` entry, broadcast a spurious `update` to every `defineShape`
+* subscriber, re-run search/aggregate/rank sync, and fire `onWrite` (a Vectorize
+* re-embed = real cost) on every tick — and `replace` would reset `_creationTime`.
+* So each row is diffed against its stored projection (the SAME
+* {@link projectExternalSourceRow} + {@link stableStringify} full-pull uses) and
+* skipped when byte-identical — mirroring the full-pull diff's steady-state no-op.
+*/
+declare const materializeExternalRowsIncremental: (writer: DatabaseWriterLike, pulled: ReadonlyArray<Record<string, unknown>>, options: {
+  columns?: ReadonlyArray<string>;
+  deletedIds?: ReadonlySet<string>;
+  table: string;
+}) => Promise<IncrementalMaterializeResult>;
+/**
 * Read the materialized table's current membership as the canonical full-pull
 * baseline (`id → canonical JSON`). Reuses the shape scanner (`selectShapeRows`)
 * and the SAME {@link projectExternalSourceRow} + {@link stableStringify} the diff
@@ -2445,23 +2480,50 @@ interface SourceClientLike {
 type SourceRefresh = "manual" | {
   everyMs: number;
 };
+/** The incremental cursor config (plan 136): the watermark column + the watermark-parameterized pull query. */
+interface SourceCursorLike {
+  column: string;
+  query: string;
+}
 /** The runtime `.source(...)` config the poll loop reads — a structural mirror of `@lunora/server`'s `ExternalSourceDefinition` (only the fields the tick uses). */
 interface ExternalSourceLike {
   binding: string;
   columns?: ReadonlyArray<string>;
+  cursor?: SourceCursorLike;
   idColumn?: string;
   map?: (row: Record<string, unknown>) => Record<string, unknown>;
+  mode?: string;
   query: string;
+  reconcileEveryMs?: number;
   refresh?: SourceRefresh;
+  softDeleteColumn?: string;
   tenantBy?: (shardKey: string) => ReadonlyArray<unknown>;
 }
+/**
+* Coerce a driver-native value that `stableStringify` can't represent (see
+* `shared/stable-key.ts`) into its JSON-safe form: a `Date` → its ISO string, a
+* `bigint` → its decimal string. Every other value passes through unchanged.
+*
+* node-pg / postgres-js / mysql2 return `timestamp`/`datetime` columns as JS
+* `Date` and `bigint`/`int8` columns as `bigint` — both throw a `TypeError` out of
+* `stableStringify` (used by the full-pull diff and the incremental content
+* short-circuit), which bricks ingest for any table with such a column (e.g. the
+* canonical `cursor: { column: "updated_at" }` incremental config). This is the
+* single boundary where driver-native types cross into DO SQLite JSON; a new
+* source driver (or a new non-JSON column type) must be normalized here too.
+* `shared/stable-key.ts`'s throw contract is intentionally left unchanged — this
+* normalizes the value *before* it can ever reach that encoder.
+*/
+
 /**
 * Lift an external row to a Lunora document: the `idColumn` value becomes a
 * stringified `_id`, then either `map` shapes the body or every other column is
 * copied verbatim. Throws on a missing/null id, and on a non-scalar id, so a
 * misconfigured query fails loudly instead of materializing rows under the literal
 * id `"undefined"` (or collapsing many rows onto one id). Shared with
-* `@lunora/hyperdrive`'s `projectSourceRow`.
+* `@lunora/hyperdrive`'s `projectSourceRow`. The returned document's values are
+* normalized (see {@link normalizeSourceValue}) so a `Date`/`bigint` column never
+* reaches `stableStringify` un-normalized.
 */
 declare const liftSourceId: (row: Record<string, unknown>, options?: {
   idColumn?: string;
@@ -2482,6 +2544,39 @@ declare const isSourceDue: (refresh: SourceRefresh | undefined, lastPolledMs: nu
 */
 declare const pullExternalSourceTick: (sql: SqlExec, writer: DatabaseWriterLike, client: SourceClientLike, table: string, source: ExternalSourceLike, shardKey: string) => Promise<MaterializeResult>;
 /**
+* Whether an upstream row is a soft-delete tombstone under `column`. A set
+* `deleted_at` (any non-null value, e.g. a timestamp), an `is_deleted = true`, or a
+* non-zero flag all read as deleted; `null` / `undefined` / `false` / `0` mean
+* live. Note an **empty string** reads as deleted (`"" !== 0`), so an upstream that
+* clears the column to `""` rather than `NULL` for a live row would mis-signal —
+* use `NULL` for live rows. The incremental query MUST return tombstoned rows
+* (don't filter `WHERE deleted_at IS NULL`) or the delete is never observed.
+*/
+declare const isSoftDeleted: (row: Record<string, unknown>, column: string) => boolean;
+/**
+* Run one **incremental** tick (plan 136). Reads the durable watermark for
+* `(table, shardKey)`; on the first ever poll or when the `reconcileEveryMs` sweep
+* is due it runs a **full-pull** (seed/GC: {@link runExternalSourceTick} observes
+* deletes and re-establishes membership), otherwise it pulls only rows past the
+* watermark via `cursor.query` and upserts them ({@link materializeExternalRowsIncremental},
+* tombstones → deletes). Either way it advances the watermark to the max cursor
+* value seen and persists it (and the reconcile timestamp).
+*
+* **Crash safety** is by ordering + idempotency, NOT an atomic transaction across
+* the two write channels (the apply goes through the `writer`; the watermark write
+* is a raw `sql` write): the watermark advances only AFTER a fully-applied slice,
+* so a crash between the apply and the watermark write leaves the watermark behind
+* and the next tick re-pulls the same `>= watermark` slice — which the upsert
+* short-circuits (unchanged rows) or re-applies idempotently. It only ever replays,
+* never skips (same self-healing argument as `advanceClientWatermark`).
+*
+* Requires `source.cursor` (validated at `defineSchema` for incremental mode); a
+* missing cursor throws rather than silently degrading to a stuck watermark.
+*/
+declare const pullExternalSourceIncrementalTick: (sql: SqlExec, writer: DatabaseWriterLike, client: SourceClientLike, table: string, source: ExternalSourceLike, shardKey: string, nowMs: number) => Promise<{
+  applied: number;
+}>;
+/**
 * Reserved `functionPath` prefix for admin introspection RPCs. These travel
 * over the same `/_lunora/rpc` → shard `/rpc` path as ordinary functions, but
 * `ShardDO` intercepts them before user dispatch and serves them from the
@@ -4325,6 +4420,19 @@ declare abstract class ShardDO {
   private static rootSizeWarned;
   /** Test-only: reset the static "warned once" flag. */
   static resetRootSizeWarning(): void;
+  /**
+  * Compute the shared poll alarm's next wake time from both tiers' signals.
+  * Global shapes need the fixed `GLOBAL_SHAPE_POLL_INTERVAL_MS` floor whenever
+  * any are subscribed (a global table has no per-DO op-log, so it can only be
+  * polled). External-source ingest instead reports the earliest NEXT-DUE
+  * timestamp across its non-manual sources (or `undefined` when none exist) —
+  * a source with a large `refresh.everyMs` must sleep until it's actually due,
+  * not spin at the global-shape floor. Returns `undefined` when NEITHER tier
+  * has pending work, so the DO can go fully idle instead of re-arming for no
+  * reason; otherwise the earlier of the two candidate times (never later than
+  * `nowMs`, so a source that's already due arms essentially immediately).
+  */
+  private static nextPollAlarmTarget;
   protected state: ShardDOState;
   protected env: unknown;
   /**
@@ -4656,12 +4764,17 @@ declare abstract class ShardDO {
   /** Hibernation API: invoked on socket error. */
   webSocketError(_ws: WebSocket, _error: unknown): void;
   /**
-  * Durable Object alarm handler — the heartbeat for `.global()`-table shapes.
-  * The runtime wakes this when the poll alarm armed by `scheduleGlobalPoll`
-  * fires; it refreshes every subscribed global shape (diff-poke from the global
-  * backend) and re-arms while any remain. With no global subscribers left, the
-  * alarm is not re-armed and the DO goes idle. A base-only / global-free DO
-  * never arms it, so this stays dormant there.
+  * Durable Object alarm handler — the heartbeat for `.global()`-table shapes
+  * AND external-source (`.source(...)`) ingest, which share one alarm. The
+  * runtime wakes this when the poll alarm armed by `scheduleGlobalPoll` fires;
+  * it refreshes every subscribed global shape (diff-poke from the global
+  * backend), materializes any due sourced tables, and re-arms at
+  * {@link ShardDO.nextPollAlarmTarget} — the fixed floor while global shapes
+  * are subscribed, or the earliest source next-due time when only ingest
+  * remains (so a 1-hour-`refresh` source sleeps ~1 hour instead of waking
+  * every 2 s). With neither tier pending, the alarm is not re-armed and the DO
+  * goes idle. A base-only / global-free / source-free DO never arms it, so
+  * this stays dormant there.
   */
   alarm(): Promise<void>;
   /** Subclasses implement function dispatch. */
@@ -5328,16 +5441,23 @@ declare abstract class ShardDO {
   /**
   * Poll external-source (`.source(...)`) tables once (plan 077): materialize
   * each sourced table's freshly-pulled tenant slice into this DO's SQLite. The
-  * base `ShardDO` has no sourced tables, so it returns `0` and the ingest tier
-  * stays dormant — zero behavior change for every existing DO. The codegen
-  * subclass overrides it to, per sourced table, build a `createShardCtxDb`
-  * writer, read the tenant slice from Hyperdrive under this DO's shard key, and
-  * run `runExternalSourceTick` (read local baseline → diff → apply via the
-  * validated CDC writer). Returns the number of sourced tables still being
-  * polled, so the shared poll alarm ({@link ShardDO.alarm}) re-arms while ingest
-  * is active.
+  * base `ShardDO` has no sourced tables, so it returns `undefined` and the
+  * ingest tier stays dormant — zero behavior change for every existing DO. The
+  * codegen subclass overrides it to, per sourced table, build a
+  * `createShardCtxDb` writer, read the tenant slice from Hyperdrive under this
+  * DO's shard key, and run `runExternalSourceTick` (read local baseline → diff
+  * → apply via the validated CDC writer).
+  *
+  * Returns the EARLIEST next-due timestamp (absolute epoch ms) across every
+  * non-manual sourced table — `polledAt.get(table) ?? now` plus that source's
+  * `refresh.everyMs` — or `undefined` when every sourced table is
+  * `refresh: "manual"` (or there are none). NOT a bare active count: the
+  * shared poll alarm ({@link ShardDO.alarm}) uses this to re-arm at the exact
+  * next time ingest needs to run, instead of spinning at the fixed
+  * `GLOBAL_SHAPE_POLL_INTERVAL_MS` floor for a source whose `refresh.everyMs`
+  * is, say, an hour away.
   */
-  protected pollExternalSources(): Promise<number>;
+  protected pollExternalSources(): Promise<number | undefined>;
   /**
   * Arm the shared poll alarm for external-source ingest (plan 077). The alarm is
   * shared with the global-shape poll tier; the codegen subclass calls this once
@@ -6337,11 +6457,18 @@ declare abstract class ShardDO {
   */
   private saveGlobalSnapshot;
   /**
-  * Arm the poll alarm for `.global()` shapes if one isn't already pending.
-  * Idempotent — every global-shape seed calls it, but only the first arms the
-  * alarm. Degrades to a no-op when the runtime exposes no `setAlarm` (the unit
-  * harness): a global shape is then seed-only, which the poll-loop tests assert
-  * by driving {@link ShardDO.alarm} directly.
+  * Arm the poll alarm if one isn't already pending. Idempotent — every
+  * global-shape seed calls it, but only the first arms the alarm. Degrades to
+  * a no-op when the runtime exposes no `setAlarm` (the unit harness): a global
+  * shape is then seed-only, which the poll-loop tests assert by driving
+  * {@link ShardDO.alarm} directly.
+  *
+  * `atMs` lets {@link ShardDO.alarm} re-arm at a computed target — the
+  * earlier of the fixed global-shape floor and the earliest external-source
+  * next-due time — instead of always the fixed floor. Every OTHER caller
+  * (a fresh global-shape seed, {@link ShardDO.scheduleSourcePoll}'s initial
+  * kick) omits it and gets the original `GLOBAL_SHAPE_POLL_INTERVAL_MS`
+  * default, since neither knows a more precise due time yet.
   */
   private scheduleGlobalPoll;
   /**
@@ -6704,4 +6831,4 @@ interface WhereSqlStrategy {
 * `undefined` when the input imposes no constraint (empty `where`).
 */
 declare const compileWhereSql: (where: WhereInput | undefined, strategy: WhereSqlStrategy) => SQL | undefined;
-export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, type ExternalSourceDiffResult, type ExternalSourceLike, FLAGS_FUNCTION_PREFIX, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FlagEvaluation, type FlagsResult, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MaterializeResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type SchedulableWorkflowReferenceLike, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, type ShapeSubscriptionQuery, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection, type SourceClientLike, type SourceRefresh, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertShapeShardable, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createShardCtxDb, createSystemReader, decodeCursor, depKey, diffExternalSource, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, fanOutScalarCounts, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, isSourceDue, liftSourceId, listTables, matchesRankStaticWhere, matchesStaticWhere, materializeExternalRows, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, pullExternalSourceTick, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readExternalSourceBaseline, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runExternalSourceTick, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, softDeleteScope, sortColumnName, stableStringify, stableWireKey, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };
+export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, type ExternalSourceDiffResult, type ExternalSourceLike, FLAGS_FUNCTION_PREFIX, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FlagEvaluation, type FlagsResult, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IncrementalMaterializeResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MaterializeResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type SchedulableWorkflowReferenceLike, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, type ShapeSubscriptionQuery, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection, type SourceClientLike, type SourceCursorLike, type SourceRefresh, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertShapeShardable, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createShardCtxDb, createSystemReader, decodeCursor, depKey, diffExternalSource, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, fanOutScalarCounts, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, isSoftDeleted, isSourceDue, liftSourceId, listTables, matchesRankStaticWhere, matchesStaticWhere, materializeExternalRows, materializeExternalRowsIncremental, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, pullExternalSourceIncrementalTick, pullExternalSourceTick, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readExternalSourceBaseline, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runExternalSourceTick, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, softDeleteScope, sortColumnName, stableStringify, stableWireKey, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };

package/dist/index.mjs

@@ -3,13 +3,13 @@ export { AGGREGATE_SQL_FUNCTION, aggregateSqlFunction, matchesStaticWhere, norma
 export { aggregateTableName, coerceAggregateNumber, encodeAggregateKey, foldAggregateTally, readAggregateValue } from './packem_shared/aggregateTableName-CxNqY1Sl.mjs';
 export { CountRlsUnsupportedError, mergeWhere, planAggregateLookup, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy } from './packem_shared/CountRlsUnsupportedError-BGxj0pgS.mjs';
 export { AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, ensureAuthMetricsTables, readAuthMetrics, recordAuthEvent } from './packem_shared/AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
-export { NotUniqueError, assertValidClientId, createShardCtxDb, normalizeIdStructurally } from './packem_shared/NotUniqueError-BigrdT_W.mjs';
+export { NotUniqueError, assertValidClientId, createShardCtxDb, normalizeIdStructurally } from './packem_shared/NotUniqueError-Ca21uDuU.mjs';
 export { DATA_MIGRATION_STATE_TABLE, readMigrationStatus, runDataMigration } from './packem_shared/DATA_MIGRATION_STATE_TABLE-CYwBpyTr.mjs';
 export { SCAN_DEP, createDependencyTracker, depKey } from './packem_shared/SCAN_DEP-DLJF8dsj.mjs';
 export { renderSql } from './packem_shared/renderSql-D6eUcn2N.mjs';
 export { diffExternalSource } from './packem_shared/diffExternalSource-CovHfdyo.mjs';
-export { materializeExternalRows, readExternalSourceBaseline, runExternalSourceTick } from './packem_shared/materializeExternalRows-CoGmFmsY.mjs';
-export { isSourceDue, liftSourceId, pullExternalSourceTick } from './packem_shared/isSourceDue-Bj7I3v1b.mjs';
+export { materializeExternalRows, materializeExternalRowsIncremental, readExternalSourceBaseline, runExternalSourceTick } from './packem_shared/materializeExternalRows-DlQWMlw_.mjs';
+export { isSoftDeleted, isSourceDue, liftSourceId, pullExternalSourceIncrementalTick, pullExternalSourceTick } from './packem_shared/isSoftDeleted-YLKR6JYw.mjs';
 export { FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, ensureFunctionMetricsTables, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, recordFunctionMetric } from './packem_shared/FUNCTION_METRICS_BUCKETS_TABLE-UDNVD7FS.mjs';
 export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, FLAGS_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, facetColumn, listTables, readTablePage, selectMatchingIds } from './packem_shared/ADMIN_FUNCTIONS-CAHLZMj8.mjs';
 export { LogBuffer } from './packem_shared/LogBuffer-B_Ezju_N.mjs';
@@ -26,16 +26,16 @@ export { RLS_UNWRAP_SYMBOL, RlsRequiredError, guardWriter } from './packem_share
 export { buildFtsMatch, ftsTableName, scoreDocument, stringifySearchText, tokenizeSearch } from './packem_shared/buildFtsMatch-BLEMawrp.mjs';
 export { M as MIN_ADMIN_TOKEN_LENGTH, a as MIN_AUTH_SECRET_LENGTH, b as buildSecurityAudit } from './packem_shared/security-audit-CucgBice.mjs';
 export { SESSION_DO_TTL_DEFAULT, SessionDO } from './packem_shared/SESSION_DO_TTL_DEFAULT-BnSKgVO4.mjs';
-export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-BWz51mpB.mjs';
+export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-afQHUhyA.mjs';
 export { SHARD_REGISTRY_DO_NAME, ShardRegistryDO } from './packem_shared/SHARD_REGISTRY_DO_NAME-D99roc-r.mjs';
 export { MAX_SQL_ROWS, assertReadonly, runReadonlySql } from './packem_shared/MAX_SQL_ROWS-iFAA8FbD.mjs';
 export { createSystemReader } from './packem_shared/createSystemReader-D12eNH13.mjs';
 export { ConflictError } from './packem_shared/ConflictError-CLoq37xH.mjs';
 export { hasTrigger, runTriggers } from './packem_shared/hasTrigger-5N6_Fx0A.mjs';
 export { compileWhereSql } from './packem_shared/compileWhereSql-DE6yfRcQ.mjs';
-export { CDC_LOG_TABLE, applyCdcChanges, readCdcChanges, trimCdcChanges } from './packem_shared/CDC_LOG_TABLE-DjJEHiM2.mjs';
+export { CDC_LOG_TABLE, applyCdcChanges, readCdcChanges, trimCdcChanges } from './packem_shared/CDC_LOG_TABLE-uwOJxJJZ.mjs';
 export { backfillAggregateIndexes, backfillRankIndexes } from './packem_shared/backfillAggregateIndexes-DDoT-UUI.mjs';
-export { runShardMigrations } from './packem_shared/runShardMigrations-BGx4v2B6.mjs';
+export { runShardMigrations } from './packem_shared/runShardMigrations-DFzx6Qld.mjs';
 export { stableStringify } from './packem_shared/stableStringify-mC40mZts.mjs';
 export { stableWireKey } from './packem_shared/stableWireKey-DKuXO7T5.mjs';
 export { subscriptionListDeltas } from './packem_shared/subscriptionListDeltas-CT76bYny.mjs';

package/dist/packem_shared/{CDC_LOG_TABLE-DjJEHiM2.mjs → CDC_LOG_TABLE-uwOJxJJZ.mjs}

@@ -79,7 +79,7 @@ const bumpCdcEpoch = (sql$1) => {
 };
 const applyCdcChange = async (writer, change) => {
   if (change.op === "delete") {
-    await writer.delete(change.id);
+    await writer.delete(change.id, change.table);
     return;
   }
   const document = change.doc ?? {};

package/dist/packem_shared/{NotUniqueError-BigrdT_W.mjs → NotUniqueError-Ca21uDuU.mjs}

@@ -3,8 +3,8 @@ import { sql } from 'drizzle-orm';
 import { matchesStaticWhere, aggregateSqlFunction, normalizeCountArgument, throwingScheduler } from './AGGREGATE_SQL_FUNCTION-CQsu2Xga.mjs';
 import { encodeAggregateKey, foldAggregateTally, aggregateTableName, coerceAggregateNumber, readAggregateValue } from './aggregateTableName-CxNqY1Sl.mjs';
 import { mergeWhere, CountRlsUnsupportedError, selectIndexForGroupBy, selectIndexForCount, selectIndexForAggregate } from './CountRlsUnsupportedError-BGxj0pgS.mjs';
-import { appendCdcChange } from './CDC_LOG_TABLE-DjJEHiM2.mjs';
-export { CDC_LOG_TABLE, applyCdcChanges, bumpCdcEpoch, minCdcSeq, readCdcChanges, readCdcCursor, readCdcEpoch, trimCdcChanges } from './CDC_LOG_TABLE-DjJEHiM2.mjs';
+import { appendCdcChange } from './CDC_LOG_TABLE-uwOJxJJZ.mjs';
+export { CDC_LOG_TABLE, applyCdcChanges, bumpCdcEpoch, minCdcSeq, readCdcChanges, readCdcCursor, readCdcEpoch, trimCdcChanges } from './CDC_LOG_TABLE-uwOJxJJZ.mjs';
 import { r as runDrizzle } from './do-exec-5eQy5cEi.mjs';
 import { i as isFtsAvailable, D as DOC_COLUMN$1, r as rowToDocument, A as AGG_KEY, a as AGG_VALUE, b as AGG_COUNT, d as aggUpsertSql, j as jsonPathSql, q as quoteIdentifier, t as tableColumns, e as qualifiedJsonPathSql } from './do-sql-BCHCWtrD.mjs';
 import { param } from './renderSql-D6eUcn2N.mjs';
@@ -23,7 +23,7 @@ import { runTriggers } from './hasTrigger-5N6_Fx0A.mjs';
 import { compileWhereSql } from './compileWhereSql-DE6yfRcQ.mjs';
 export { backfillAggregateIndexes, backfillRankIndexes } from './backfillAggregateIndexes-DDoT-UUI.mjs';
 export { C as CLIENT_WATERMARK_TABLE, G as GLOBAL_SHAPE_SNAPSHOT_TABLE, I as IDEMPOTENCY_TABLE, c as advanceClientWatermark, d as deleteGlobalShapeSnapshot, e as deleteGlobalShapeSnapshotsForConnection, m as migrateClientWatermark, b as migrateGlobalShapeSnapshot, r as readClientWatermark, f as readGlobalShapeSnapshot, g as readIdempotent, t as trimIdempotent, w as writeGlobalShapeSnapshot, h as writeIdempotent } from './ctx-db-idempotency-BdcNpvY4.mjs';
-export { runShardMigrations } from './runShardMigrations-BGx4v2B6.mjs';
+export { runShardMigrations } from './runShardMigrations-DFzx6Qld.mjs';
 export { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-Cz9dHyh1.mjs';
 
 const rankIndexFieldsUnchanged = (index, previous, next) => {

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

@@ -21,7 +21,7 @@ import { i as isDevEnvironment, c as buildSettings, b as buildSecurityAudit } fr
 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 { CDC_LOG_TABLE, readCdcChanges, readCdcCursor, readCdcEpoch, minCdcSeq, bumpCdcEpoch } from './CDC_LOG_TABLE-uwOJxJJZ.mjs';
 import { stableStringify } from './stableStringify-mC40mZts.mjs';
 import { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-Cz9dHyh1.mjs';
 
@@ -2088,6 +2088,25 @@ class ShardDO {
   static resetRootSizeWarning() {
     ShardDO.rootSizeWarned = false;
   }
+  /**
+   * Compute the shared poll alarm's next wake time from both tiers' signals.
+   * Global shapes need the fixed `GLOBAL_SHAPE_POLL_INTERVAL_MS` floor whenever
+   * any are subscribed (a global table has no per-DO op-log, so it can only be
+   * polled). External-source ingest instead reports the earliest NEXT-DUE
+   * timestamp across its non-manual sources (or `undefined` when none exist) —
+   * a source with a large `refresh.everyMs` must sleep until it's actually due,
+   * not spin at the global-shape floor. Returns `undefined` when NEITHER tier
+   * has pending work, so the DO can go fully idle instead of re-arming for no
+   * reason; otherwise the earlier of the two candidate times (never later than
+   * `nowMs`, so a source that's already due arms essentially immediately).
+   */
+  static nextPollAlarmTarget(globalShapesRemaining, nextSourceDueAt, nowMs) {
+    const globalTarget = globalShapesRemaining > 0 ? nowMs + ShardDO.GLOBAL_SHAPE_POLL_INTERVAL_MS : void 0;
+    if (globalTarget === void 0) {
+      return nextSourceDueAt === void 0 ? void 0 : Math.max(nextSourceDueAt, nowMs);
+    }
+    return nextSourceDueAt === void 0 ? globalTarget : Math.min(globalTarget, nextSourceDueAt);
+  }
   state;
   env;
   /**
@@ -2709,31 +2728,38 @@ class ShardDO {
   webSocketError(_ws, _error) {
   }
   /**
-   * Durable Object alarm handler — the heartbeat for `.global()`-table shapes.
-   * The runtime wakes this when the poll alarm armed by `scheduleGlobalPoll`
-   * fires; it refreshes every subscribed global shape (diff-poke from the global
-   * backend) and re-arms while any remain. With no global subscribers left, the
-   * alarm is not re-armed and the DO goes idle. A base-only / global-free DO
-   * never arms it, so this stays dormant there.
+   * Durable Object alarm handler — the heartbeat for `.global()`-table shapes
+   * AND external-source (`.source(...)`) ingest, which share one alarm. The
+   * runtime wakes this when the poll alarm armed by `scheduleGlobalPoll` fires;
+   * it refreshes every subscribed global shape (diff-poke from the global
+   * backend), materializes any due sourced tables, and re-arms at
+   * {@link ShardDO.nextPollAlarmTarget} — the fixed floor while global shapes
+   * are subscribed, or the earliest source next-due time when only ingest
+   * remains (so a 1-hour-`refresh` source sleeps ~1 hour instead of waking
+   * every 2 s). With neither tier pending, the alarm is not re-armed and the DO
+   * goes idle. A base-only / global-free / source-free DO never arms it, so
+   * this stays dormant there.
    */
   async alarm() {
     this.globalPollScheduled = false;
-    let remaining;
+    let globalShapesRemaining;
     try {
-      remaining = await this.pollGlobalShapes();
+      globalShapesRemaining = await this.pollGlobalShapes();
     } catch (error) {
       this.recordShapeError("shape:poll", error);
-      remaining = 1;
+      globalShapesRemaining = 1;
     }
+    let nextSourceDueAt;
     try {
-      remaining += await this.pollExternalSources();
+      nextSourceDueAt = await this.pollExternalSources();
     } catch (error) {
       this.recordShapeError("source:poll", error);
-      remaining += 1;
+      nextSourceDueAt = Date.now() + ShardDO.GLOBAL_SHAPE_POLL_INTERVAL_MS;
     }
     await this.flushChangedTables();
-    if (remaining > 0) {
-      await this.scheduleGlobalPoll();
+    const nextAlarmAt = ShardDO.nextPollAlarmTarget(globalShapesRemaining, nextSourceDueAt, Date.now());
+    if (nextAlarmAt !== void 0) {
+      await this.scheduleGlobalPoll(nextAlarmAt);
     }
   }
   /**
@@ -3881,18 +3907,25 @@ class ShardDO {
   /**
    * Poll external-source (`.source(...)`) tables once (plan 077): materialize
    * each sourced table's freshly-pulled tenant slice into this DO's SQLite. The
-   * base `ShardDO` has no sourced tables, so it returns `0` and the ingest tier
-   * stays dormant — zero behavior change for every existing DO. The codegen
-   * subclass overrides it to, per sourced table, build a `createShardCtxDb`
-   * writer, read the tenant slice from Hyperdrive under this DO's shard key, and
-   * run `runExternalSourceTick` (read local baseline → diff → apply via the
-   * validated CDC writer). Returns the number of sourced tables still being
-   * polled, so the shared poll alarm ({@link ShardDO.alarm}) re-arms while ingest
-   * is active.
+   * base `ShardDO` has no sourced tables, so it returns `undefined` and the
+   * ingest tier stays dormant — zero behavior change for every existing DO. The
+   * codegen subclass overrides it to, per sourced table, build a
+   * `createShardCtxDb` writer, read the tenant slice from Hyperdrive under this
+   * DO's shard key, and run `runExternalSourceTick` (read local baseline → diff
+   * → apply via the validated CDC writer).
+   *
+   * Returns the EARLIEST next-due timestamp (absolute epoch ms) across every
+   * non-manual sourced table — `polledAt.get(table) ?? now` plus that source's
+   * `refresh.everyMs` — or `undefined` when every sourced table is
+   * `refresh: "manual"` (or there are none). NOT a bare active count: the
+   * shared poll alarm ({@link ShardDO.alarm}) uses this to re-arm at the exact
+   * next time ingest needs to run, instead of spinning at the fixed
+   * `GLOBAL_SHAPE_POLL_INTERVAL_MS` floor for a source whose `refresh.everyMs`
+   * is, say, an hour away.
    */
   // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass implements the real Hyperdrive-backed poll
   pollExternalSources() {
-    return Promise.resolve(0);
+    return Promise.resolve(void 0);
   }
   /**
    * Arm the shared poll alarm for external-source ingest (plan 077). The alarm is
@@ -6171,13 +6204,20 @@ class ShardDO {
     }
   }
   /**
-   * Arm the poll alarm for `.global()` shapes if one isn't already pending.
-   * Idempotent — every global-shape seed calls it, but only the first arms the
-   * alarm. Degrades to a no-op when the runtime exposes no `setAlarm` (the unit
-   * harness): a global shape is then seed-only, which the poll-loop tests assert
-   * by driving {@link ShardDO.alarm} directly.
-   */
-  async scheduleGlobalPoll() {
+   * Arm the poll alarm if one isn't already pending. Idempotent — every
+   * global-shape seed calls it, but only the first arms the alarm. Degrades to
+   * a no-op when the runtime exposes no `setAlarm` (the unit harness): a global
+   * shape is then seed-only, which the poll-loop tests assert by driving
+   * {@link ShardDO.alarm} directly.
+   *
+   * `atMs` lets {@link ShardDO.alarm} re-arm at a computed target — the
+   * earlier of the fixed global-shape floor and the earliest external-source
+   * next-due time — instead of always the fixed floor. Every OTHER caller
+   * (a fresh global-shape seed, {@link ShardDO.scheduleSourcePoll}'s initial
+   * kick) omits it and gets the original `GLOBAL_SHAPE_POLL_INTERVAL_MS`
+   * default, since neither knows a more precise due time yet.
+   */
+  async scheduleGlobalPoll(atMs) {
     if (this.globalPollScheduled) {
       return;
     }
@@ -6187,7 +6227,7 @@ class ShardDO {
     }
     this.globalPollScheduled = true;
     try {
-      await setAlarm.call(this.state.storage, Date.now() + ShardDO.GLOBAL_SHAPE_POLL_INTERVAL_MS);
+      await setAlarm.call(this.state.storage, atMs ?? Date.now() + ShardDO.GLOBAL_SHAPE_POLL_INTERVAL_MS);
     } catch {
       this.globalPollScheduled = false;
     }

package/dist/packem_shared/isSoftDeleted-YLKR6JYw.mjs

@@ -0,0 +1,217 @@
+import { LunoraError } from '@lunora/errors';
+import { sql } from 'drizzle-orm';
+import { r as runDrizzle } from './do-exec-5eQy5cEi.mjs';
+import { runExternalSourceTick, materializeExternalRowsIncremental } from './materializeExternalRows-DlQWMlw_.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 normalizeSourceValue = (value) => {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "bigint") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((element) => normalizeSourceValue(element));
+  }
+  if (value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+    return normalizeSourceDocument(value);
+  }
+  return value;
+};
+const normalizeSourceDocument = (document) => {
+  const normalized = {};
+  for (const [key, value] of Object.entries(document)) {
+    normalized[key] = normalizeSourceValue(value);
+  }
+  return normalized;
+};
+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 normalizeSourceDocument({ ...map(row), _id: id });
+  }
+  const body = {};
+  for (const [key, value] of Object.entries(row)) {
+    if (key !== idColumn) {
+      body[key] = value;
+    }
+  }
+  return normalizeSourceDocument({ ...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);
+    const { softDeleteColumn } = source;
+    const documents = softDeleteColumn ? slice.documents.filter((_document, index) => {
+      const row = slice.rows[index];
+      return !(row && isSoftDeleted(row, softDeleteColumn));
+    }) : slice.documents;
+    ({ applied } = await runExternalSourceTick(sql, writer, 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.`
+    );
+  }
+  const noRowCarriesCursor = slice.rows.length > 0 && slice.rows.every((row) => row[cursor.column] === null || row[cursor.column] === void 0);
+  if (!fullPull && noRowCarriesCursor) {
+    throw new LunoraError(
+      "INTERNAL",
+      `external-source: table "${table}" (mode "incremental") pulled ${String(slice.rows.length)} rows but none carry the cursor column "${cursor.column}" — \`cursor.query\` must project it (matching the seed \`query\`'s alias), or the watermark can never advance and every tick re-pulls the same stranded slice.`
+    );
+  }
+  writeSourceCursor(sql, table, shardKey, { lastReconcileMs: fullPull ? nowMs : state.lastReconcileMs, watermark });
+  return { applied };
+};
+
+export { isSoftDeleted, isSourceDue, liftSourceId, normalizeSourceValue, pullExternalSourceIncrementalTick, pullExternalSourceTick };

package/dist/packem_shared/materializeExternalRows-DlQWMlw_.mjs

@@ -0,0 +1,45 @@
+import { applyCdcChanges } from './CDC_LOG_TABLE-uwOJxJJZ.mjs';
+import { s as selectShapeRows } from './ctx-db-shapes-Cz9dHyh1.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)) {
+      const existing = await writer.get(id, table);
+      if (existing) {
+        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)) {
+    baseline.set(id, stableStringify(projectExternalSourceRow({ ...doc, _id: id }, columns)));
+  }
+  return baseline;
+};
+const runExternalSourceTick = async (sql, writer, pulled, options) => {
+  const baseline = readExternalSourceBaseline(sql, options.table, options.columns);
+  return materializeExternalRows(writer, pulled, baseline, options);
+};
+
+export { materializeExternalRows, materializeExternalRowsIncremental, readExternalSourceBaseline, runExternalSourceTick };

package/dist/packem_shared/{runShardMigrations-BGx4v2B6.mjs → runShardMigrations-DFzx6Qld.mjs}

@@ -1,6 +1,6 @@
 import { sql } from 'drizzle-orm';
 import { aggregateTableName } from './aggregateTableName-CxNqY1Sl.mjs';
-import { migrateCdcLog, migrateCdcMeta } from './CDC_LOG_TABLE-DjJEHiM2.mjs';
+import { migrateCdcLog, migrateCdcMeta } from './CDC_LOG_TABLE-uwOJxJJZ.mjs';
 import { m as migrateClientWatermark, a as migrateIdempotency, b as migrateGlobalShapeSnapshot } from './ctx-db-idempotency-BdcNpvY4.mjs';
 import { r as runDrizzle } from './do-exec-5eQy5cEi.mjs';
 import { D as DOC_COLUMN, j as jsonPathSql, c as createIndexSql, t as tableColumns, i as isFtsAvailable, A as AGG_KEY, a as AGG_VALUE, b as AGG_COUNT } from './do-sql-BCHCWtrD.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/do",
-  "version": "1.0.0-alpha.31",
+  "version": "1.0.0-alpha.33",
   "description": "Lunora Durable Objects: ShardDO (SQLite, OCC, hibernated WebSocket subscriptions) and SessionDO",
   "keywords": [
     "cloudflare",
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@lunora/errors": "1.0.0-alpha.5",
-    "@lunora/fingerprint": "1.0.0-alpha.2",
+    "@lunora/fingerprint": "1.0.0-alpha.3",
     "@visulima/redact": "3.0.0",
     "drizzle-orm": "^0.45.2"
   },

package/dist/packem_shared/isSourceDue-Bj7I3v1b.mjs

@@ -1,41 +0,0 @@
-import { LunoraError } from '@lunora/errors';
-import { runExternalSourceTick } from './materializeExternalRows-CoGmFmsY.mjs';
-
-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 pullExternalSourceTick = async (sql, writer, client, table, source, shardKey) => {
-  const parameters = source.tenantBy ? source.tenantBy(shardKey) : [];
-  const rows = await client.query(source.query, parameters);
-  const documents = rows.map((row) => liftSourceId(row, { idColumn: source.idColumn, map: source.map }));
-  return runExternalSourceTick(sql, writer, documents, { columns: source.columns, table });
-};
-
-export { isSourceDue, liftSourceId, pullExternalSourceTick };

package/dist/packem_shared/materializeExternalRows-CoGmFmsY.mjs

@@ -1,23 +0,0 @@
-import { applyCdcChanges } from './CDC_LOG_TABLE-DjJEHiM2.mjs';
-import { s as selectShapeRows } from './ctx-db-shapes-Cz9dHyh1.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 readExternalSourceBaseline = (sql, table, columns) => {
-  const baseline = /* @__PURE__ */ new Map();
-  for (const { doc, id } of selectShapeRows(sql, table, void 0)) {
-    baseline.set(id, stableStringify(projectExternalSourceRow({ ...doc, _id: id }, columns)));
-  }
-  return baseline;
-};
-const runExternalSourceTick = async (sql, writer, pulled, options) => {
-  const baseline = readExternalSourceBaseline(sql, options.table, options.columns);
-  return materializeExternalRows(writer, pulled, baseline, options);
-};
-
-export { materializeExternalRows, readExternalSourceBaseline, runExternalSourceTick };