@quereus/sync 3.3.0 → 4.0.0

package/dist/src/metadata/schema-migration.d.ts

@@ -18,7 +18,7 @@ export interface StoredMigration {
 }
 /**
  * Serialize a migration for storage.
- * Format: 26 bytes HLC + 4 bytes version + 1 byte type length + type + ddl
+ * Format: 30 bytes HLC + 4 bytes version + 1 byte type length + type + ddl
  */
 export declare function serializeMigration(migration: StoredMigration): Uint8Array;
 /**

package/dist/src/metadata/schema-migration.js

@@ -8,18 +8,18 @@ import { serializeHLC, deserializeHLC, compareHLC } from '../clock/hlc.js';
 import { buildSchemaMigrationKey, buildSchemaMigrationScanBounds } from './keys.js';
 /**
  * Serialize a migration for storage.
- * Format: 26 bytes HLC + 4 bytes version + 1 byte type length + type + ddl
+ * Format: 30 bytes HLC + 4 bytes version + 1 byte type length + type + ddl
  */
 export function serializeMigration(migration) {
     const encoder = new TextEncoder();
     const typeBytes = encoder.encode(migration.type);
     const ddlBytes = encoder.encode(migration.ddl);
     const hlcBytes = serializeHLC(migration.hlc);
-    const buffer = new Uint8Array(26 + 4 + 1 + typeBytes.length + ddlBytes.length);
+    const buffer = new Uint8Array(30 + 4 + 1 + typeBytes.length + ddlBytes.length);
     let offset = 0;
-    // HLC (26 bytes)
+    // HLC (30 bytes)
     buffer.set(hlcBytes, offset);
-    offset += 26;
+    offset += 30;
     // Schema version (4 bytes, big-endian)
     const view = new DataView(buffer.buffer);
     view.setUint32(offset, migration.schemaVersion, false);
@@ -39,9 +39,9 @@ export function serializeMigration(migration) {
 export function deserializeMigration(buffer) {
     const decoder = new TextDecoder();
     let offset = 0;
-    // HLC (26 bytes)
-    const hlc = deserializeHLC(buffer.slice(0, 26));
-    offset += 26;
+    // HLC (30 bytes)
+    const hlc = deserializeHLC(buffer.slice(0, 30));
+    offset += 30;
     // Schema version (4 bytes)
     const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
     const schemaVersion = view.getUint32(offset, false);

package/dist/src/metadata/schema-version.d.ts

@@ -5,7 +5,7 @@
  * "most destructive wins" conflict resolution for schema changes.
  *
  * Key format: sv:{schema}.{table}:{column}
- * Value: HLC (26 bytes) + 1 byte type + type-specific data
+ * Value: HLC (30 bytes) + 1 byte type + type-specific data
  *
  * Column types:
  * - 0x01: Regular column (type affinity, nullable, default)

package/dist/src/metadata/schema-version.js

@@ -5,7 +5,7 @@
  * "most destructive wins" conflict resolution for schema changes.
  *
  * Key format: sv:{schema}.{table}:{column}
- * Value: HLC (26 bytes) + 1 byte type + type-specific data
+ * Value: HLC (30 bytes) + 1 byte type + type-specific data
  *
  * Column types:
  * - 0x01: Regular column (type affinity, nullable, default)
@@ -65,20 +65,20 @@ export function serializeSchemaVersion(version) {
     if (version.ddl !== undefined)
         data.ddl = version.ddl;
     const dataBytes = encoder.encode(JSON.stringify(data));
-    const buffer = new Uint8Array(26 + 1 + dataBytes.length);
+    const buffer = new Uint8Array(30 + 1 + dataBytes.length);
     buffer.set(hlcBytes, 0);
-    buffer[26] = typeByte;
-    buffer.set(dataBytes, 27);
+    buffer[30] = typeByte;
+    buffer.set(dataBytes, 31);
     return buffer;
 }
 /**
  * Deserialize a schema version from storage.
  */
 export function deserializeSchemaVersion(buffer) {
-    const hlc = deserializeHLC(buffer.slice(0, 26));
-    const typeByte = buffer[26];
+    const hlc = deserializeHLC(buffer.slice(0, 30));
+    const typeByte = buffer[30];
     const type = typeByte === 0x01 ? 'column' : typeByte === 0x02 ? 'dropped' : 'table';
-    const dataJson = decoder.decode(buffer.slice(27));
+    const dataJson = decoder.decode(buffer.slice(31));
     const data = dataJson ? JSON.parse(dataJson) : {};
     return {
         hlc,

package/dist/src/metadata/tombstones.d.ts

@@ -4,7 +4,7 @@
  * When a row is deleted, a tombstone is created with the deletion HLC.
  * Tombstones prevent deleted rows from being resurrected by older writes.
  */
-import type { SqlValue } from '@quereus/quereus';
+import type { Row, SqlValue } from '@quereus/quereus';
 import type { KVStore, WriteBatch } from '@quereus/store';
 import { type HLC } from '../clock/hlc.js';
 /**
@@ -13,14 +13,29 @@ import { type HLC } from '../clock/hlc.js';
 export interface Tombstone {
     hlc: HLC;
     createdAt: number;
+    /**
+     * Optional last-known row image before deletion (the engine's `oldRow` at delete
+     * time). Persisted so it reaches a receiver via `getChangesSince`, which
+     * re-resolves deletions from the tombstone. Best-effort audit/undo metadata:
+     * absent when the delete carried no `oldRow` and on snapshot-reconstructed
+     * tombstones. A tombstone with no `priorRow` serializes to the fixed 38-byte head.
+     */
+    priorRow?: Row;
 }
 /**
  * Serialize a tombstone for storage.
- * Format: 26 bytes HLC + 8 bytes createdAt
+ *
+ * Format: 30 bytes HLC + 8 bytes createdAt, then — only when a `priorRow` is
+ * present — a trailing JSON array of the row's values, each through the column
+ * version `encodeSqlValue` helper so `Uint8Array`/`bigint`/`null` cells round-trip.
+ * A tombstone with no `priorRow` serializes to the unchanged 38-byte head.
  */
 export declare function serializeTombstone(tombstone: Tombstone): Uint8Array;
 /**
- * Deserialize a tombstone from storage.
+ * Deserialize a tombstone from storage. Absent-tolerant: bytes beyond the 38-byte
+ * head are the JSON-encoded `priorRow` (see {@link serializeTombstone}); a
+ * head-only buffer (no before-image, or a snapshot-reconstructed tombstone)
+ * deserializes with `priorRow` absent.
  */
 export declare function deserializeTombstone(buffer: Uint8Array): Tombstone;
 /**
@@ -28,20 +43,22 @@ export declare function deserializeTombstone(buffer: Uint8Array): Tombstone;
  */
 export declare class TombstoneStore {
     private readonly kv;
-    private readonly tombstoneTTL;
-    constructor(kv: KVStore, tombstoneTTL: number);
+    private readonly retentionHorizonMs;
+    constructor(kv: KVStore, retentionHorizonMs: number);
     /**
      * Get the tombstone for a row, if it exists.
      */
     getTombstone(schemaName: string, tableName: string, pk: SqlValue[]): Promise<Tombstone | undefined>;
     /**
-     * Create a tombstone for a deleted row.
+     * Create a tombstone for a deleted row. `priorRow` (optional) is the row's
+     * last-known image, persisted as best-effort audit/undo metadata.
      */
-    setTombstone(schemaName: string, tableName: string, pk: SqlValue[], hlc: HLC): Promise<void>;
+    setTombstone(schemaName: string, tableName: string, pk: SqlValue[], hlc: HLC, priorRow?: Row): Promise<void>;
     /**
-     * Set tombstone in a batch.
+     * Set tombstone in a batch. `priorRow` (optional) is the row's last-known image,
+     * persisted as best-effort audit/undo metadata.
      */
-    setTombstoneBatch(batch: WriteBatch, schemaName: string, tableName: string, pk: SqlValue[], hlc: HLC): void;
+    setTombstoneBatch(batch: WriteBatch, schemaName: string, tableName: string, pk: SqlValue[], hlc: HLC, priorRow?: Row): void;
     /**
      * Delete a tombstone (used when resurrecting a row).
      */

package/dist/src/metadata/tombstones.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tombstones.d.ts","sourceRoot":"","sources":["../../../src/metadata/tombstones.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,KAAK,GAAG,EAA4C,MAAM,iBAAiB,CAAC;AAGrF;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,GAAG,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,UAAU,CASnE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAKlE;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBADZ,EAAE,EAAE,OAAO,EACX,YAAY,EAAE,MAAM;IAGvC;;OAEG;IACG,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,GACb,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAOjC;;OAEG;IACG,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,EACd,GAAG,EAAE,GAAG,GACP,OAAO,CAAC,IAAI,CAAC;IAMhB;;OAEG;IACH,iBAAiB,CACf,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,EACd,GAAG,EAAE,GAAG,GACP,IAAI;IAMP;;OAEG;IACG,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,GACb,OAAO,CAAC,IAAI,CAAC;IAKhB;;;OAGG;IACG,oBAAoB,CACxB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,EACd,WAAW,EAAE,GAAG,EAChB,iBAAiB,EAAE,OAAO,GACzB,OAAO,CAAC,OAAO,CAAC;IAanB;;;OAGG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkB1E;;OAEG;IACI,gBAAgB,CACrB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,aAAa,CAAC;QAAE,EAAE,EAAE,QAAQ,EAAE,CAAC;QAAC,SAAS,EAAE,SAAS,CAAA;KAAE,CAAC;CAc3D"}
+{"version":3,"file":"tombstones.d.ts","sourceRoot":"","sources":["../../../src/metadata/tombstones.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,KAAK,GAAG,EAA4C,MAAM,iBAAiB,CAAC;AAOrF;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,GAAG,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,UAAU,CAenE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAWlE;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBADlB,EAAE,EAAE,OAAO,EACX,kBAAkB,EAAE,MAAM;IAG7C;;OAEG;IACG,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,GACb,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAOjC;;;OAGG;IACG,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,EACd,GAAG,EAAE,GAAG,EACR,QAAQ,CAAC,EAAE,GAAG,GACb,OAAO,CAAC,IAAI,CAAC;IAMhB;;;OAGG;IACH,iBAAiB,CACf,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,EACd,GAAG,EAAE,GAAG,EACR,QAAQ,CAAC,EAAE,GAAG,GACb,IAAI;IAMP;;OAEG;IACG,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,GACb,OAAO,CAAC,IAAI,CAAC;IAKhB;;;OAGG;IACG,oBAAoB,CACxB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,EACd,WAAW,EAAE,GAAG,EAChB,iBAAiB,EAAE,OAAO,GACzB,OAAO,CAAC,OAAO,CAAC;IAanB;;;OAGG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkB1E;;OAEG;IACI,gBAAgB,CACrB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,aAAa,CAAC;QAAE,EAAE,EAAE,QAAQ,EAAE,CAAC;QAAC,SAAS,EAAE,SAAS,CAAA;KAAE,CAAC;CAc3D"}

package/dist/src/metadata/tombstones.js

@@ -5,37 +5,58 @@
  * Tombstones prevent deleted rows from being resurrected by older writes.
  */
 import { serializeHLC, deserializeHLC, compareHLC } from '../clock/hlc.js';
+import { encodeSqlValue, decodeSqlValue } from './column-version.js';
 import { buildTombstoneKey, buildTombstoneScanBounds, decodePK } from './keys.js';
+/** Fixed-size head of a serialized tombstone: 30 bytes HLC + 8 bytes createdAt. */
+const TOMBSTONE_HEAD_BYTES = 38;
 /**
  * Serialize a tombstone for storage.
- * Format: 26 bytes HLC + 8 bytes createdAt
+ *
+ * Format: 30 bytes HLC + 8 bytes createdAt, then — only when a `priorRow` is
+ * present — a trailing JSON array of the row's values, each through the column
+ * version `encodeSqlValue` helper so `Uint8Array`/`bigint`/`null` cells round-trip.
+ * A tombstone with no `priorRow` serializes to the unchanged 38-byte head.
  */
 export function serializeTombstone(tombstone) {
-    const result = new Uint8Array(34);
+    const head = new Uint8Array(TOMBSTONE_HEAD_BYTES);
     const hlcBytes = serializeHLC(tombstone.hlc);
-    result.set(hlcBytes, 0);
-    const view = new DataView(result.buffer);
-    view.setBigUint64(26, BigInt(tombstone.createdAt), false);
+    head.set(hlcBytes, 0);
+    const view = new DataView(head.buffer);
+    view.setBigUint64(30, BigInt(tombstone.createdAt), false);
+    if (tombstone.priorRow === undefined)
+        return head;
+    const payload = new TextEncoder().encode(JSON.stringify(tombstone.priorRow.map(encodeSqlValue)));
+    const result = new Uint8Array(head.length + payload.length);
+    result.set(head, 0);
+    result.set(payload, head.length);
     return result;
 }
 /**
- * Deserialize a tombstone from storage.
+ * Deserialize a tombstone from storage. Absent-tolerant: bytes beyond the 38-byte
+ * head are the JSON-encoded `priorRow` (see {@link serializeTombstone}); a
+ * head-only buffer (no before-image, or a snapshot-reconstructed tombstone)
+ * deserializes with `priorRow` absent.
  */
 export function deserializeTombstone(buffer) {
-    const hlc = deserializeHLC(buffer.slice(0, 26));
+    const hlc = deserializeHLC(buffer.slice(0, 30));
     const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-    const createdAt = Number(view.getBigUint64(26, false));
-    return { hlc, createdAt };
+    const createdAt = Number(view.getBigUint64(30, false));
+    const tombstone = { hlc, createdAt };
+    if (buffer.byteLength > TOMBSTONE_HEAD_BYTES) {
+        const values = JSON.parse(new TextDecoder().decode(buffer.slice(TOMBSTONE_HEAD_BYTES)));
+        tombstone.priorRow = values.map(decodeSqlValue);
+    }
+    return tombstone;
 }
 /**
  * Tombstone store operations.
  */
 export class TombstoneStore {
     kv;
-    tombstoneTTL;
-    constructor(kv, tombstoneTTL) {
+    retentionHorizonMs;
+    constructor(kv, retentionHorizonMs) {
         this.kv = kv;
-        this.tombstoneTTL = tombstoneTTL;
+        this.retentionHorizonMs = retentionHorizonMs;
     }
     /**
      * Get the tombstone for a row, if it exists.
@@ -48,19 +69,21 @@ export class TombstoneStore {
         return deserializeTombstone(data);
     }
     /**
-     * Create a tombstone for a deleted row.
+     * Create a tombstone for a deleted row. `priorRow` (optional) is the row's
+     * last-known image, persisted as best-effort audit/undo metadata.
      */
-    async setTombstone(schemaName, tableName, pk, hlc) {
+    async setTombstone(schemaName, tableName, pk, hlc, priorRow) {
         const key = buildTombstoneKey(schemaName, tableName, pk);
-        const tombstone = { hlc, createdAt: Date.now() };
+        const tombstone = { hlc, createdAt: Date.now(), ...(priorRow !== undefined ? { priorRow } : {}) };
         await this.kv.put(key, serializeTombstone(tombstone));
     }
     /**
-     * Set tombstone in a batch.
+     * Set tombstone in a batch. `priorRow` (optional) is the row's last-known image,
+     * persisted as best-effort audit/undo metadata.
      */
-    setTombstoneBatch(batch, schemaName, tableName, pk, hlc) {
+    setTombstoneBatch(batch, schemaName, tableName, pk, hlc, priorRow) {
         const key = buildTombstoneKey(schemaName, tableName, pk);
-        const tombstone = { hlc, createdAt: Date.now() };
+        const tombstone = { hlc, createdAt: Date.now(), ...(priorRow !== undefined ? { priorRow } : {}) };
         batch.put(key, serializeTombstone(tombstone));
     }
     /**
@@ -98,7 +121,7 @@ export class TombstoneStore {
         let count = 0;
         for await (const entry of this.kv.iterate(bounds)) {
             const tombstone = deserializeTombstone(entry.value);
-            if (now - tombstone.createdAt > this.tombstoneTTL) {
+            if (now - tombstone.createdAt > this.retentionHorizonMs) {
                 batch.delete(entry.key);
                 count++;
             }

package/dist/src/metadata/tombstones.js.map

@@ -1 +1 @@
-{"version":3,"file":"tombstones.js","sourceRoot":"","sources":["../../../src/metadata/tombstones.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tombstones.js","sourceRoot":"","sources":["../../../src/metadata/tombstones.ts"],"names":[],"mappings":"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"}

package/dist/src/sql/basis-lifecycle-tvf.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `quereus_basis_lifecycle()` — in-SQL introspection of the durable per-basis-table
+ * lifecycle records the sync layer maintains on each lens deploy
+ * (`docs/migration.md` § 2 Converge). A zero-argument table-valued function listing
+ * every stored {@link BasisTableLifecycleRecord}, one row per record, so a developer
+ * can surface legacy / retirement-candidate tables without writing host code:
+ *
+ * ```sql
+ * select "table", state, "unmappedSince"
+ * from quereus_basis_lifecycle()
+ * where state = 'derivation-source-only'
+ * order by "unmappedSince";
+ * ```
+ *
+ * Pure convenience over {@link SyncManager.getBasisTableLifecycle} — no engine change.
+ * The TVF closes over the `SyncManager` (the host's smallest registration seam), and
+ * the records are read programmatically from KV, so the rows survive a restart and a
+ * fresh `Database` over the same store reflects the prior deploy's classification.
+ */
+import type { Database } from '@quereus/quereus';
+import type { SyncManager } from '../sync/manager.js';
+/**
+ * Register the `quereus_basis_lifecycle()` introspection TVF against `db`, reading
+ * from `syncManager`. Opt-in: the host calls this once after `createSyncModule(...)`
+ * (no auto-registration — `createSyncModule` takes no `Database`, and relay-only
+ * deployments need no SQL surface). The `quereus_`-prefixed name avoids collision
+ * with user tables/functions.
+ *
+ * Safe to call once per `Database`; a repeat call (same name/arity) **replaces** the
+ * prior registration rather than erroring or corrupting state (engine
+ * `registerFunction` → `Schema.addFunction` is a keyed overwrite).
+ */
+export declare function registerBasisLifecycleTvf(db: Database, syncManager: SyncManager): void;
+//# sourceMappingURL=basis-lifecycle-tvf.d.ts.map

package/dist/src/sql/basis-lifecycle-tvf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basis-lifecycle-tvf.d.ts","sourceRoot":"","sources":["../../../src/sql/basis-lifecycle-tvf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAoB,MAAM,kBAAkB,CAAC;AAEnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAoCtD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,GAAG,IAAI,CAwCtF"}

package/dist/src/sql/basis-lifecycle-tvf.js

@@ -0,0 +1,101 @@
+/**
+ * `quereus_basis_lifecycle()` — in-SQL introspection of the durable per-basis-table
+ * lifecycle records the sync layer maintains on each lens deploy
+ * (`docs/migration.md` § 2 Converge). A zero-argument table-valued function listing
+ * every stored {@link BasisTableLifecycleRecord}, one row per record, so a developer
+ * can surface legacy / retirement-candidate tables without writing host code:
+ *
+ * ```sql
+ * select "table", state, "unmappedSince"
+ * from quereus_basis_lifecycle()
+ * where state = 'derivation-source-only'
+ * order by "unmappedSince";
+ * ```
+ *
+ * Pure convenience over {@link SyncManager.getBasisTableLifecycle} — no engine change.
+ * The TVF closes over the `SyncManager` (the host's smallest registration seam), and
+ * the records are read programmatically from KV, so the rows survive a restart and a
+ * fresh `Database` over the same store reflects the prior deploy's classification.
+ */
+import { createTableValuedFunction, INTEGER_TYPE, TEXT_TYPE } from '@quereus/quereus';
+/** A read-only generated column spec for the TVF's relation return type. */
+function col(name, logicalType, nullable) {
+    return {
+        name,
+        type: { typeClass: 'scalar', logicalType, nullable, isReadOnly: true },
+        generated: true,
+    };
+}
+/**
+ * Project one lifecycle record onto its ordered SQL row. Column order MUST match
+ * the `returnType.columns` list below. Optional record fields coalesce to `null`
+ * (a `Row` cannot hold `undefined`); booleans emit as INTEGER 0/1 (engine
+ * convention, mirroring `table_info`'s `notnull`/`pk`); `mappedBy` renders as a
+ * JSON array string (empty ⇒ `"[]"`, never null); the `evictPolicy` union
+ * (`'never'` | `'immediate'` | a numeric ms horizon) collapses to its string form.
+ */
+function rowFromRecord(r) {
+    return [
+        r.schema,
+        r.table,
+        r.state,
+        JSON.stringify(r.mappedBy ?? []),
+        r.derivationSource ? 1 : 0,
+        r.inBasis ? 1 : 0,
+        r.mappedSince ?? null,
+        r.unmappedSince ?? null,
+        r.detachedAt ?? null,
+        r.lastDirectlyMappedWriteAt ?? null,
+        r.evictPolicy == null ? null : String(r.evictPolicy),
+    ];
+}
+/**
+ * Register the `quereus_basis_lifecycle()` introspection TVF against `db`, reading
+ * from `syncManager`. Opt-in: the host calls this once after `createSyncModule(...)`
+ * (no auto-registration — `createSyncModule` takes no `Database`, and relay-only
+ * deployments need no SQL surface). The `quereus_`-prefixed name avoids collision
+ * with user tables/functions.
+ *
+ * Safe to call once per `Database`; a repeat call (same name/arity) **replaces** the
+ * prior registration rather than erroring or corrupting state (engine
+ * `registerFunction` → `Schema.addFunction` is a keyed overwrite).
+ */
+export function registerBasisLifecycleTvf(db, syncManager) {
+    const schema = createTableValuedFunction({
+        name: 'quereus_basis_lifecycle',
+        numArgs: 0,
+        // Records change across deploys (and across restarts), so the result is not
+        // a pure function of its (empty) argument list.
+        deterministic: false,
+        returnType: {
+            typeClass: 'relation',
+            isReadOnly: true,
+            isSet: false,
+            columns: [
+                col('schema', TEXT_TYPE, false),
+                col('table', TEXT_TYPE, false),
+                col('state', TEXT_TYPE, false),
+                col('mappedBy', TEXT_TYPE, false),
+                col('derivationSource', INTEGER_TYPE, false),
+                col('inBasis', INTEGER_TYPE, false),
+                col('mappedSince', INTEGER_TYPE, true),
+                col('unmappedSince', INTEGER_TYPE, true),
+                col('detachedAt', INTEGER_TYPE, true),
+                col('lastDirectlyMappedWriteAt', INTEGER_TYPE, true),
+                col('evictPolicy', TEXT_TYPE, true),
+            ],
+            keys: [],
+            rowConstraints: [],
+        },
+    }, 
+    // Snapshot the full record array once, then yield — iteration is over a stable
+    // array, immune to a concurrent deploy mutating records mid-scan.
+    async function* () {
+        const records = await syncManager.getBasisTableLifecycle();
+        for (const record of records) {
+            yield rowFromRecord(record);
+        }
+    });
+    db.registerFunction(schema);
+}
+//# sourceMappingURL=basis-lifecycle-tvf.js.map

package/dist/src/sql/basis-lifecycle-tvf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"basis-lifecycle-tvf.js","sourceRoot":"","sources":["../../../src/sql/basis-lifecycle-tvf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,yBAAyB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAItF,4EAA4E;AAC5E,SAAS,GAAG,CAAC,IAAY,EAAE,WAAwB,EAAE,QAAiB;IACpE,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,EAAE,SAAS,EAAE,QAAiB,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE;QAC/E,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CAAC,CAA4B;IACjD,OAAO;QACL,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,KAAK;QACP,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC;QAChC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC,CAAC,WAAW,IAAI,IAAI;QACrB,CAAC,CAAC,aAAa,IAAI,IAAI;QACvB,CAAC,CAAC,UAAU,IAAI,IAAI;QACpB,CAAC,CAAC,yBAAyB,IAAI,IAAI;QACnC,CAAC,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;KACrD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CAAC,EAAY,EAAE,WAAwB;IAC9E,MAAM,MAAM,GAAG,yBAAyB,CACtC;QACE,IAAI,EAAE,yBAAyB;QAC/B,OAAO,EAAE,CAAC;QACV,4EAA4E;QAC5E,gDAAgD;QAChD,aAAa,EAAE,KAAK;QACpB,UAAU,EAAE;YACV,SAAS,EAAE,UAAU;YACrB,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE;gBACP,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC;gBAC/B,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC;gBAC9B,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC;gBAC9B,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC;gBACjC,GAAG,CAAC,kBAAkB,EAAE,YAAY,EAAE,KAAK,CAAC;gBAC5C,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,CAAC;gBACnC,GAAG,CAAC,aAAa,EAAE,YAAY,EAAE,IAAI,CAAC;gBACtC,GAAG,CAAC,eAAe,EAAE,YAAY,EAAE,IAAI,CAAC;gBACxC,GAAG,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,CAAC;gBACrC,GAAG,CAAC,2BAA2B,EAAE,YAAY,EAAE,IAAI,CAAC;gBACpD,GAAG,CAAC,aAAa,EAAE,SAAS,EAAE,IAAI,CAAC;aACpC;YACD,IAAI,EAAE,EAAE;YACR,cAAc,EAAE,EAAE;SACnB;KACF;IACD,+EAA+E;IAC/E,kEAAkE;IAClE,KAAK,SAAS,CAAC;QACb,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,sBAAsB,EAAE,CAAC;QAC3D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC,CACF,CAAC;IAEF,EAAE,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC"}

package/dist/src/sync/admission.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Group-atomic admission core for the sync ingress data-apply seam.
+ *
+ * Centralizes the docs/sync.md § Transactional Integrity During Sync write
+ * ordering — **data first → metadata second → abort with no metadata** — that
+ * every ingress modality must uphold:
+ *   - wire `applyChanges`            (change-applicator.ts)  → `admitGroup`
+ *   - non-streaming `applySnapshot`  (snapshot.ts)           → `admitGroup`
+ *   - each streaming flush in `applySnapshotStream` (snapshot-stream.ts)
+ *                                                            → `applyDataToStore`
+ *
+ * Streaming keeps its own checkpoint-based consistency model (interleaved
+ * metadata/data flushes, resume on a saved checkpoint) and so reuses only the
+ * `applyDataToStore` seam — for the same `status:'error'` emission on a
+ * whole-batch flush throw — rather than the full `admitGroup` unit.
+ */
+import type { HLC } from '../clock/hlc.js';
+import type { ApplyToStoreOptions, DataChangeToApply, SchemaChangeToApply } from './protocol.js';
+import type { SyncContext } from './sync-context.js';
+/**
+ * Data-first half of the admission invariant: apply this unit's data + schema to
+ * the store, emit `status:'error'` and rethrow on a whole-batch throw, surface any
+ * reported assertion violations, then abort (throw) on any per-change
+ * `ApplyToStoreResult.errors` — all BEFORE the caller commits any CRDT metadata.
+ * No-op when there is no `applyToStore` callback or nothing to apply.
+ *
+ * The two failure shapes are mutually exclusive (a throw never reaches
+ * `throwIfApplyErrors`), so `status:'error'` is emitted at most once. The
+ * violation emit does not touch sync-state, so it cannot affect that invariant.
+ *
+ * Assertion violations are emitted BEFORE the per-change abort gate. Whenever the
+ * seam reports a violation it ran in REPORT mode and the batch already COMMITTED —
+ * the violating row's data + derived effects (MV deltas, watch capture) are
+ * durably in storage. A later `throwIfApplyErrors` throw blocks only the CRDT-
+ * metadata commit; it does NOT roll back those storage writes. So a reported
+ * violation is a fact about already-committed data and must be surfaced even when
+ * an unrelated per-change error aborts the batch in the same invocation — the two
+ * facts are orthogonal: "B's data landed and broke a local invariant" and "the
+ * batch can't fully admit because A failed and will retry" are both true.
+ *
+ * Emitting before the abort closes a permanent-notification-loss gap: were the
+ * emit on the success branch only, a mixed batch (per-change error + reported
+ * violation) would throw past it, drop the event, and on retry the value-identical
+ * row is suppressed → empty seam batch → the assertion is never re-evaluated →
+ * the host is never notified about durably-committed violating data. That same
+ * value-identical suppression now correctly prevents DOUBLE-notification on retry
+ * (B is suppressed, so no second event fires), matching the idempotent-re-apply
+ * guarantee. On the pure-success path (no per-change errors) behavior is unchanged.
+ */
+export declare function applyDataToStore(ctx: SyncContext, dataChanges: DataChangeToApply[], schemaChanges: SchemaChangeToApply[], options: ApplyToStoreOptions): Promise<void>;
+/**
+ * One group-atomic admission unit: data + schema to apply, the CRDT metadata to
+ * commit only once that data landed, and the local HLC clock watermark to merge
+ * on full-unit success.
+ *
+ * A "group" is one *admission unit*, not necessarily one source transaction — the
+ * wire path admits the whole resolved `ChangeSet[]` as a single all-or-nothing
+ * unit (the single per-peer `lastSyncHLC` watermark cannot express a partial
+ * commit), and each snapshot path admits its wholesale load as one unit.
+ */
+export interface AdmissionGroup {
+    readonly dataChanges: DataChangeToApply[];
+    readonly schemaChanges: SchemaChangeToApply[];
+    readonly applyOptions: ApplyToStoreOptions;
+    /** Commit this unit's CRDT metadata. Runs ONLY after the data write landed. */
+    readonly commitMetadata: () => Promise<void>;
+    /**
+     * Local HLC clock watermark to merge in on full-unit success. The per-PEER
+     * `lastSyncHLC` is the transport caller's concern (it differs per modality and
+     * transport) and is deliberately NOT advanced here.
+     */
+    readonly watermarkHLC?: HLC;
+}
+/**
+ * Full group-atomic admission: data first → metadata second → advance the local
+ * clock watermark, aborting (with no metadata committed) on any data-apply
+ * failure. The realization of "apply a transaction group atomically, advance the
+ * watermark idempotently".
+ */
+export declare function admitGroup(ctx: SyncContext, group: AdmissionGroup): Promise<void>;
+//# sourceMappingURL=admission.d.ts.map

package/dist/src/sync/admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.d.ts","sourceRoot":"","sources":["../../../src/sync/admission.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,KAAK,EACX,mBAAmB,EAEnB,iBAAiB,EACjB,mBAAmB,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,gBAAgB,CACrC,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,iBAAiB,EAAE,EAChC,aAAa,EAAE,mBAAmB,EAAE,EACpC,OAAO,EAAE,mBAAmB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,mBAAmB,EAAE,CAAC;IAC9C,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,GAAG,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvF"}

package/dist/src/sync/admission.js

@@ -0,0 +1,94 @@
+/**
+ * Group-atomic admission core for the sync ingress data-apply seam.
+ *
+ * Centralizes the docs/sync.md § Transactional Integrity During Sync write
+ * ordering — **data first → metadata second → abort with no metadata** — that
+ * every ingress modality must uphold:
+ *   - wire `applyChanges`            (change-applicator.ts)  → `admitGroup`
+ *   - non-streaming `applySnapshot`  (snapshot.ts)           → `admitGroup`
+ *   - each streaming flush in `applySnapshotStream` (snapshot-stream.ts)
+ *                                                            → `applyDataToStore`
+ *
+ * Streaming keeps its own checkpoint-based consistency model (interleaved
+ * metadata/data flushes, resume on a saved checkpoint) and so reuses only the
+ * `applyDataToStore` seam — for the same `status:'error'` emission on a
+ * whole-batch flush throw — rather than the full `admitGroup` unit.
+ */
+import { persistHLCState, throwIfApplyErrors, toError } from './sync-context.js';
+/**
+ * Data-first half of the admission invariant: apply this unit's data + schema to
+ * the store, emit `status:'error'` and rethrow on a whole-batch throw, surface any
+ * reported assertion violations, then abort (throw) on any per-change
+ * `ApplyToStoreResult.errors` — all BEFORE the caller commits any CRDT metadata.
+ * No-op when there is no `applyToStore` callback or nothing to apply.
+ *
+ * The two failure shapes are mutually exclusive (a throw never reaches
+ * `throwIfApplyErrors`), so `status:'error'` is emitted at most once. The
+ * violation emit does not touch sync-state, so it cannot affect that invariant.
+ *
+ * Assertion violations are emitted BEFORE the per-change abort gate. Whenever the
+ * seam reports a violation it ran in REPORT mode and the batch already COMMITTED —
+ * the violating row's data + derived effects (MV deltas, watch capture) are
+ * durably in storage. A later `throwIfApplyErrors` throw blocks only the CRDT-
+ * metadata commit; it does NOT roll back those storage writes. So a reported
+ * violation is a fact about already-committed data and must be surfaced even when
+ * an unrelated per-change error aborts the batch in the same invocation — the two
+ * facts are orthogonal: "B's data landed and broke a local invariant" and "the
+ * batch can't fully admit because A failed and will retry" are both true.
+ *
+ * Emitting before the abort closes a permanent-notification-loss gap: were the
+ * emit on the success branch only, a mixed batch (per-change error + reported
+ * violation) would throw past it, drop the event, and on retry the value-identical
+ * row is suppressed → empty seam batch → the assertion is never re-evaluated →
+ * the host is never notified about durably-committed violating data. That same
+ * value-identical suppression now correctly prevents DOUBLE-notification on retry
+ * (B is suppressed, so no second event fires), matching the idempotent-re-apply
+ * guarantee. On the pure-success path (no per-change errors) behavior is unchanged.
+ */
+export async function applyDataToStore(ctx, dataChanges, schemaChanges, options) {
+    if (!ctx.applyToStore || (dataChanges.length === 0 && schemaChanges.length === 0))
+        return;
+    let result;
+    try {
+        result = await ctx.applyToStore(dataChanges, schemaChanges, options);
+    }
+    catch (error) {
+        // Emit error state so UI can react. CRDT metadata is NOT committed,
+        // allowing the same changes to be re-resolved on the next sync attempt.
+        ctx.syncEvents.emitSyncStateChange({ status: 'error', error: toError(error) });
+        throw error;
+    }
+    // Surface any local assertion violations the seam reported. A reported
+    // violation means the report-mode seam COMMITTED the violating row (data +
+    // derived effects durable); we notify the host once per violated assertion.
+    // This runs BEFORE the abort gate below so a co-occurring per-change error
+    // cannot drop the notification about data that is already committed.
+    if (result.assertionViolations) {
+        for (const violation of result.assertionViolations) {
+            ctx.syncEvents.emitAssertionViolation({
+                assertion: violation.assertion,
+                samples: violation.samples,
+            });
+        }
+    }
+    // Per-change storage failures (the adapter collects rather than throws) abort
+    // the apply identically to a whole-batch throw: emit error + throw, with no
+    // metadata committed, so the whole batch re-resolves and re-applies
+    // idempotently on the next sync. See throwIfApplyErrors / docs/sync.md.
+    throwIfApplyErrors(ctx, result);
+}
+/**
+ * Full group-atomic admission: data first → metadata second → advance the local
+ * clock watermark, aborting (with no metadata committed) on any data-apply
+ * failure. The realization of "apply a transaction group atomically, advance the
+ * watermark idempotently".
+ */
+export async function admitGroup(ctx, group) {
+    await applyDataToStore(ctx, group.dataChanges, group.schemaChanges, group.applyOptions);
+    await group.commitMetadata(); // metadata SECOND
+    if (group.watermarkHLC) {
+        ctx.hlcManager.receive(group.watermarkHLC); // monotonic merge, idempotent
+        await persistHLCState(ctx);
+    }
+}
+//# sourceMappingURL=admission.js.map

package/dist/src/sync/admission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.js","sourceRoot":"","sources":["../../../src/sync/admission.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAUH,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,GAAgB,EAChB,WAAgC,EAChC,aAAoC,EACpC,OAA4B;IAE5B,IAAI,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,CAAC;QAAE,OAAO;IAE1F,IAAI,MAA0B,CAAC;IAC/B,IAAI,CAAC;QACJ,MAAM,GAAG,MAAM,GAAG,CAAC,YAAY,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,oEAAoE;QACpE,wEAAwE;QACxE,GAAG,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC/E,MAAM,KAAK,CAAC;IACb,CAAC;IAED,uEAAuE;IACvE,2EAA2E;IAC3E,4EAA4E;IAC5E,2EAA2E;IAC3E,qEAAqE;IACrE,IAAI,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAChC,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,mBAAmB,EAAE,CAAC;YACpD,GAAG,CAAC,UAAU,CAAC,sBAAsB,CAAC;gBACrC,SAAS,EAAE,SAAS,CAAC,SAAS;gBAC9B,OAAO,EAAE,SAAS,CAAC,OAAO;aAC1B,CAAC,CAAC;QACJ,CAAC;IACF,CAAC;IAED,8EAA8E;IAC9E,4EAA4E;IAC5E,oEAAoE;IACpE,wEAAwE;IACxE,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AACjC,CAAC;AA0BD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAgB,EAAE,KAAqB;IACvE,MAAM,gBAAgB,CAAC,GAAG,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IACxF,MAAM,KAAK,CAAC,cAAc,EAAE,CAAC,CAAoB,kBAAkB;IACnE,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACxB,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAI,8BAA8B;QAC7E,MAAM,eAAe,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;AACF,CAAC"}