@quereus/sync 3.2.1 → 4.0.0

package/dist/src/sync/change-applicator.d.ts

@@ -7,6 +7,7 @@
  *   3. commitChangeMetadata — persist CRDT metadata
  */
 import type { ColumnVersion } from '../metadata/column-version.js';
+import type { Tombstone } from '../metadata/tombstones.js';
 import type { ChangeSet, Change, ApplyResult, DataChangeToApply } from './protocol.js';
 import type { SyncContext } from './sync-context.js';
 /**
@@ -19,16 +20,66 @@ export interface ResolvedChange {
     dataChange?: DataChangeToApply;
     /** For column changes: the old version to clean up in the change log. */
     oldColumnVersion?: ColumnVersion;
+    /** For delete changes: the prior tombstone whose stale delete entry to clean up in the change log. */
+    oldTombstone?: Tombstone;
 }
 /**
  * Apply change sets from a remote peer.
  *
  * Three-phase process:
- *   1. Resolve all changes (no writes)
+ *   1. Resolve all changes (no writes); divert out-of-basis straggler changes
  *   2. Apply data to store via callback
- *   3. Commit CRDT metadata
+ *   3. Commit CRDT metadata (+ durable quarantine of diverted changes)
+ *
+ * Unknown-table disposition: a change referencing a table outside the local basis
+ * (a retired-table straggler delta — see `docs/migration.md` § 4 Contract) is
+ * **diverted** during resolution — never resolved, applied, or recorded as CRDT
+ * metadata, so the change log stays clean (no survivor-HLC pollution). Diverted
+ * changes are held (durably, idempotently — `quarantine`, or `store-and-forward`
+ * which additionally marks them forwardable) or ignored per
+ * {@link SyncConfig.unknownTableDisposition}, and telemetered either way.
  */
 export declare function applyChanges(ctx: SyncContext, changes: ChangeSet[]): Promise<ApplyResult>;
+/**
+ * Replay held out-of-basis changes (`quarantine` + forwardable `store-and-forward`
+ * entries) into tables that have since reappeared in the local basis — the revival
+ * half of the unknown-table contract (`docs/migration.md` § 4 Contract). The
+ * sibling of {@link applyChanges}' data branch, minus the schema-migration and
+ * unknown-table-divert machinery: held changes have no DDL and their table is, by
+ * the basis gate, already present.
+ *
+ * Driven two ways, never interleaved: the host calls {@link SyncManager.drainHeldChanges}
+ * from its periodic maintenance sweep, and {@link drainReappearedTables} calls it
+ * reactively from {@link applyChanges} the moment an inbound `create_table` revives a
+ * held table (gated by {@link SyncConfig.drainOnReappear}). Either way drain runs as a
+ * SEPARATE apply, after any re-creating batch has fully committed — fresh data is
+ * already in storage and the older held changes simply LWW-resolve against it. The
+ * invariant is "never INTERLEAVE drain into the admitting batch", not "never drain
+ * inline": a reactive post-commit drain is its own admission unit, distinct from the
+ * batch it follows.
+ *
+ * Scope mirrors {@link QuarantineStore.list}: `(schema, table)` drains one table,
+ * `(schema)` drains a schema, `()` sweeps every held entry whose table is back.
+ * Bounded by the held set (itself bounded by the retention horizon); zero-cost when
+ * nothing is held. With NO basis oracle every group's table reports `undefined`
+ * column names ⇒ every group is skipped ⇒ this returns 0 (the relay-only no-op).
+ *
+ * @returns the number of held entries cleared from the hold (across present tables).
+ */
+export declare function drainHeldChanges(ctx: SyncContext, schema?: string, table?: string): Promise<number>;
+/**
+ * Best-effort scoped drain of tables that just reappeared in the local basis, run as
+ * SEPARATE post-commit apply unit(s) after the re-creating batch committed. Advisory:
+ * each table is drained independently and any failure is logged + swallowed (the held
+ * entries stay held for the periodic sweep). No-op when {@link SyncConfig.drainOnReappear}
+ * is disabled or the list is empty. Each {@link drainHeldChanges} call is cheap when
+ * nothing is held (a scoped `quarantine.list` returning `[]`) and a no-op when the table
+ * is still absent (the oracle gate in {@link drainTableGroup}).
+ */
+export declare function drainReappearedTables(ctx: SyncContext, tables: ReadonlyArray<{
+    schema: string;
+    table: string;
+}>): Promise<void>;
 /**
  * Resolve CRDT conflicts for a single change WITHOUT writing metadata.
  *
@@ -39,6 +90,18 @@ export declare function resolveChange(ctx: SyncContext, change: Change): Promise
  * Commit CRDT metadata for resolved changes.
  *
  * Phase 3 of the 3-phase apply pattern: called AFTER data is written to store.
+ *
+ * In-batch repeats of one key are collapsed to the max-HLC winner before any write.
+ * Two versions of the same key can land in a single `applyChanges` batch (e.g.
+ * concurrent deletes of the same pk relayed together), and Phase 1 resolved BOTH
+ * against the same pre-batch prior version — neither saw the other. Writing both would
+ * leave two change-log entries for one key, re-attributing the older entry to the later
+ * HLC and breaking {@link SyncManagerImpl}'s `collectChangesSince` LOAD-BEARING
+ * INVARIANT (survivor's log HLC == its current version's HLC). So only the winner's
+ * metadata + change-log entry are written; losers are never written and the single
+ * pre-batch prior entry is deleted once. Mirrors the local write-path dedup in
+ * `recordDataEvent` / `recordColumnVersions`, keeping the delete and column paths
+ * symmetric.
  */
 export declare function commitChangeMetadata(ctx: SyncContext, resolvedChanges: ResolvedChange[]): Promise<void>;
 //# sourceMappingURL=change-applicator.d.ts.map

package/dist/src/sync/change-applicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"change-applicator.d.ts","sourceRoot":"","sources":["../../../src/sync/change-applicator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EACX,SAAS,EACT,MAAM,EACN,WAAW,EACX,iBAAiB,EAGjB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,aAAa,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CACjC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,SAAS,EAAE,GAClB,OAAO,CAAC,WAAW,CAAC,CA6HtB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAClC,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,cAAc,CAAC,CAwGzB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACzC,GAAG,EAAE,WAAW,EAChB,eAAe,EAAE,cAAc,EAAE,GAC/B,OAAO,CAAC,IAAI,CAAC,CA2Df"}
+{"version":3,"file":"change-applicator.d.ts","sourceRoot":"","sources":["../../../src/sync/change-applicator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,KAAK,EACX,SAAS,EACT,MAAM,EAGN,WAAW,EACX,iBAAiB,EAGjB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,aAAa,CAAC;IACjC,sGAAsG;IACtG,YAAY,CAAC,EAAE,SAAS,CAAC;CACzB;AA2CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CACjC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,SAAS,EAAE,GAClB,OAAO,CAAC,WAAW,CAAC,CAoMtB;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CACrC,GAAG,EAAE,WAAW,EAChB,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAsBjB;AAsFD;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAC1C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GACtD,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAClC,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,cAAc,CAAC,CAkHzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CACzC,GAAG,EAAE,WAAW,EAChB,eAAe,EAAE,cAAc,EAAE,GAC/B,OAAO,CAAC,IAAI,CAAC,CAsCf"}