@opendatalabs/personal-server-ts-server 1.33.8 → 1.34.1

package/dist/storage/pdpp-records-sqlite-store.js

@@ -0,0 +1,1440 @@
+import { createHash } from "node:crypto";
+import { randomUUID } from "node:crypto";
+import { encodeRecordKey, planIngest, RecordKeyError, summarizeIngest, decodeCursor, encodeCursor, InvalidCursorSyntaxError, CursorExpiredError, InvalidCursorError, BlobConflictError, } from "@opendatalabs/personal-server-ts-core/storage/pdpp-records";
+import { isCompletionTime, liveSnapshotDigest, parseCompletionRequest, StreamCompletionError, } from "./pdpp-stream-completion.js";
+export { StreamCompletionError, } from "./pdpp-stream-completion.js";
+const RFC3339_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?(?:[Zz]|[+-](\d{2}):(\d{2}))$/;
+/** RFC 3339 `date-time`, with calendar-valid fields. No clock check. */
+export function isRfc3339DateTime(value) {
+    if (typeof value !== "string")
+        return false;
+    const match = RFC3339_DATE_TIME.exec(value);
+    if (!match)
+        return false;
+    const [year, month, day, hour, minute, second] = match
+        .slice(1, 7)
+        .map(Number);
+    const offsetHour = Number(match[8] ?? 0);
+    const offsetMinute = Number(match[9] ?? 0);
+    const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate();
+    return (month >= 1 &&
+        month <= 12 &&
+        day >= 1 &&
+        day <= daysInMonth &&
+        hour <= 23 &&
+        minute <= 59 &&
+        second <= 59 &&
+        offsetHour <= 23 &&
+        offsetMinute <= 59 &&
+        !Number.isNaN(Date.parse(value)));
+}
+export class PdppBindingError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+function blobIdForBytes(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+/**
+ * Schema migrations for the desktop SQLite backend of the PDPP record
+ * persistence index, applied in order and tracked in `pdpp_schema_version`
+ * so re-opening an existing database never re-runs or reinterprets an
+ * already-applied migration (C7: "no schema version, no ALTER path").
+ *
+ * `pdpp_records` holds current state (one row per instance+stream+record_key).
+ * `pdpp_record_changes` holds full version history for mutable_state streams
+ * (append_only streams only ever have one history row per key, at version 1,
+ * since duplicates are no-ops). `pdpp_blobs` holds blob metadata,
+ * `pdpp_blob_bytes` holds bytes, and `pdpp_blob_claims` ties pending uploads
+ * to an instance generation.
+ */
+const MIGRATIONS = [
+    // v1: initial schema.
+    `
+CREATE TABLE IF NOT EXISTS pdpp_records (
+  instance TEXT NOT NULL,
+  stream TEXT NOT NULL,
+  record_key TEXT NOT NULL,
+  data TEXT, -- JSON; NULL when deleted = 1
+  version INTEGER NOT NULL,
+  emitted_at TEXT NOT NULL,
+  deleted INTEGER NOT NULL DEFAULT 0,
+  deleted_at TEXT,
+  PRIMARY KEY (instance, stream, record_key)
+);
+
+CREATE TABLE IF NOT EXISTS pdpp_record_changes (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  instance TEXT NOT NULL,
+  stream TEXT NOT NULL,
+  record_key TEXT NOT NULL,
+  version INTEGER NOT NULL,
+  data TEXT, -- JSON; NULL for a tombstone version
+  emitted_at TEXT NOT NULL,
+  deleted INTEGER NOT NULL DEFAULT 0,
+  deleted_at TEXT,
+  written_at INTEGER NOT NULL -- monotonic write sequence, for changes_since horizons
+);
+
+CREATE INDEX IF NOT EXISTS idx_pdpp_record_changes_lookup
+  ON pdpp_record_changes (instance, stream, record_key, version);
+
+CREATE INDEX IF NOT EXISTS idx_pdpp_record_changes_horizon
+  ON pdpp_record_changes (stream, instance, written_at);
+
+CREATE INDEX IF NOT EXISTS idx_pdpp_records_stream
+  ON pdpp_records (stream, instance, emitted_at);
+
+CREATE TABLE IF NOT EXISTS pdpp_blobs (
+  blob_id TEXT PRIMARY KEY,
+  mime_type TEXT NOT NULL,
+  size_bytes INTEGER NOT NULL,
+  sha256 TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS pdpp_write_clock (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  value INTEGER NOT NULL
+);
+INSERT OR IGNORE INTO pdpp_write_clock (id, value) VALUES (1, 0);
+`,
+    // v2: blob_ref reverse index (C2 fix — blob authorization must be able to
+    // find the record that references a blob_id, not trust field-name
+    // presence alone). Extracted from data.blob_ref.blob_id at write time so
+    // lookup is an indexed column read, not a per-request JSON scan.
+    `
+ALTER TABLE pdpp_records ADD COLUMN blob_id TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_pdpp_records_blob_id
+  ON pdpp_records (blob_id);
+`,
+    // v3: actual blob byte storage, separate from `pdpp_blobs` metadata so an
+    // existing metadata-only row (legacy fixture, or a blob whose bytes were
+    // never ingested by this store) is untouched by this migration and simply
+    // has no matching pdpp_blob_bytes row -- getBlobBytes reports that as
+    // "unavailable", not as corruption.
+    `
+CREATE TABLE IF NOT EXISTS pdpp_blob_bytes (
+  blob_id TEXT PRIMARY KEY REFERENCES pdpp_blobs (blob_id),
+  bytes BLOB NOT NULL
+);
+`,
+    // v4: persist the method generation and generation-scoped blob claims.
+    // Existing instances remain unbound until their owner resets them.
+    `
+CREATE TABLE IF NOT EXISTS pdpp_instance_binding (
+  instance TEXT PRIMARY KEY,
+  method TEXT,
+  generation INTEGER NOT NULL CHECK (generation > 0),
+  reset_clock INTEGER NOT NULL DEFAULT 0
+);
+
+INSERT OR IGNORE INTO pdpp_instance_binding (instance, method, generation, reset_clock)
+SELECT DISTINCT instance, NULL, 1, 0 FROM pdpp_records;
+
+CREATE TABLE IF NOT EXISTS pdpp_blob_claims (
+  blob_id TEXT NOT NULL REFERENCES pdpp_blobs (blob_id),
+  instance TEXT NOT NULL,
+  generation INTEGER NOT NULL,
+  PRIMARY KEY (blob_id, instance)
+);
+
+INSERT OR IGNORE INTO pdpp_blob_claims (blob_id, instance, generation)
+SELECT DISTINCT r.blob_id, r.instance, b.generation
+FROM pdpp_records r
+JOIN pdpp_instance_binding b ON b.instance = r.instance
+JOIN pdpp_blobs m ON m.blob_id = r.blob_id
+WHERE r.blob_id IS NOT NULL AND r.deleted = 0;
+`,
+    // v5: database epoch for opaque cursor binding. Tokens from a different
+    // records DB, a rebuilt records DB, or a pre-epoch implementation expire
+    // instead of being interpreted against this store.
+    `
+CREATE TABLE IF NOT EXISTS pdpp_store_metadata (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  epoch TEXT NOT NULL
+);
+`,
+    // v6: the instance handle is also the connection id. Keep its source,
+    // owner-facing label, and deletion tombstone on the existing binding row.
+    `
+ALTER TABLE pdpp_instance_binding ADD COLUMN source_id TEXT;
+ALTER TABLE pdpp_instance_binding ADD COLUMN label TEXT NOT NULL DEFAULT '';
+ALTER TABLE pdpp_instance_binding ADD COLUMN deleted_at TEXT;
+`,
+    // v7: completion evidence for P7. A row says the stream's current live set
+    // is exactly what one full replace by `method` in `generation` delivered,
+    // collected at the producer's `source_collected_at`. Only `replaceStream`
+    // writes it; any other write to the stream deletes it.
+    `
+CREATE TABLE IF NOT EXISTS pdpp_stream_completion (
+  instance TEXT NOT NULL,
+  stream TEXT NOT NULL,
+  method TEXT NOT NULL,
+  generation INTEGER NOT NULL,
+  source_collected_at TEXT NOT NULL,
+  write_seq INTEGER NOT NULL,
+  live_count INTEGER NOT NULL,
+  PRIMARY KEY (instance, stream)
+);
+`,
+    // v8: arrival order for the legacy view. Desktop served a stream in the
+    // order each live key last arrived, and an unchanged re-delivery moved a
+    // key to the end without a new version. A row holds the latest arrival of
+    // one live key in the generation that wrote it. It is not record state:
+    // no version, emitted_at, history row or write clock moves with it. Rows
+    // stored before v8 have none, and none is guessed for them.
+    `
+CREATE TABLE IF NOT EXISTS pdpp_record_arrival (
+  instance TEXT NOT NULL,
+  stream TEXT NOT NULL,
+  record_key TEXT NOT NULL,
+  generation INTEGER NOT NULL,
+  arrival INTEGER NOT NULL,
+  PRIMARY KEY (instance, stream, record_key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_pdpp_record_arrival_order
+  ON pdpp_record_arrival (instance, stream, arrival);
+`,
+    // v9: native completion receipts (completeStreams). A receipt may now carry
+    // the digest of the live set it describes and how its time was taken. Both
+    // are null on every receipt P7 writes and on every receipt stored before
+    // v9, which stay producer-asserted and are never relabeled. The columns are
+    // added by `addCompletionProofColumns`, which keeps one that already exists
+    // only if it is a compatible nullable TEXT column, so a database whose
+    // version was only rewound can be upgraded again.
+    "",
+    // v10: cover the stream-summary query so it need not visit JSON record rows.
+    `
+CREATE INDEX IF NOT EXISTS idx_pdpp_records_live_instance_stream_emitted_at
+  ON pdpp_records (instance, stream, emitted_at)
+  WHERE deleted = 0;
+`,
+    // v11: monotonic cursor for arrival-only ordering changes in the legacy view.
+    `
+CREATE TABLE IF NOT EXISTS pdpp_record_arrival_clock (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  value INTEGER NOT NULL
+);
+INSERT OR IGNORE INTO pdpp_record_arrival_clock (id, value) VALUES (1, 0);
+`,
+];
+function addCompletionProofColumns(db) {
+    // `table_xinfo`, unlike `table_info`, also lists generated columns.
+    const existing = new Map(db.prepare("PRAGMA table_xinfo(pdpp_stream_completion)").all().map((column) => [column.name, column]));
+    for (const name of ["snapshot_sha256", "collection_time_basis"]) {
+        const column = existing.get(name);
+        if (!column) {
+            db.exec(`ALTER TABLE pdpp_stream_completion ADD COLUMN ${name} TEXT`);
+        }
+        else if (column.type.toUpperCase() !== "TEXT" ||
+            column.notnull !== 0 ||
+            column.dflt_value !== null ||
+            column.pk !== 0 ||
+            column.hidden !== 0) {
+            throw new Error(`pdpp_stream_completion.${name} exists with an incompatible definition; v9 needs a nullable TEXT column with no default. Refusing to open.`);
+        }
+    }
+}
+function migrate(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS pdpp_schema_version (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      version INTEGER NOT NULL
+    );
+    INSERT OR IGNORE INTO pdpp_schema_version (id, version) VALUES (1, 0);
+  `);
+    const current = db
+        .prepare("SELECT version FROM pdpp_schema_version WHERE id = 1")
+        .get();
+    const applyFrom = db.transaction((fromVersion) => {
+        for (let v = fromVersion; v < MIGRATIONS.length; v++) {
+            db.exec(MIGRATIONS[v]);
+            if (v === 8)
+                addCompletionProofColumns(db);
+            if (v === 4) {
+                db.prepare("INSERT OR IGNORE INTO pdpp_store_metadata (id, epoch) VALUES (1, ?)").run(randomUUID());
+            }
+        }
+        db.prepare("UPDATE pdpp_schema_version SET version = ? WHERE id = 1").run(MIGRATIONS.length);
+    });
+    if (current.version < MIGRATIONS.length) {
+        applyFrom(current.version);
+    }
+    else if (current.version > MIGRATIONS.length) {
+        // A newer schema version than this code knows how to read. Refuse to
+        // guess at compatibility rather than silently reinterpreting unknown
+        // state (matches the AS store's UnsupportedAuthStateError precedent).
+        throw new Error(`pdpp_records database schema version ${current.version} is newer than this build supports (${MIGRATIONS.length}). Refusing to open — upgrade this build before opening this database.`);
+    }
+}
+function sweepStaleBlobClaims(db) {
+    db.transaction(() => {
+        db.exec(`
+      DELETE FROM pdpp_blob_claims
+      WHERE NOT EXISTS (
+        SELECT 1 FROM pdpp_instance_binding b
+        WHERE b.instance = pdpp_blob_claims.instance
+          AND b.generation = pdpp_blob_claims.generation
+      );
+    `);
+        deleteUnclaimedBlobs(db);
+    })();
+}
+function deleteUnclaimedBlobs(db) {
+    db.exec(`
+    DELETE FROM pdpp_blob_bytes
+    WHERE blob_id IN (
+      SELECT blob_id FROM pdpp_blobs b
+      WHERE NOT EXISTS (SELECT 1 FROM pdpp_blob_claims c WHERE c.blob_id = b.blob_id)
+        AND NOT EXISTS (SELECT 1 FROM pdpp_records r WHERE r.blob_id = b.blob_id AND r.deleted = 0)
+    );
+    DELETE FROM pdpp_blobs
+    WHERE NOT EXISTS (SELECT 1 FROM pdpp_blob_claims c WHERE c.blob_id = pdpp_blobs.blob_id)
+      AND NOT EXISTS (SELECT 1 FROM pdpp_records r WHERE r.blob_id = pdpp_blobs.blob_id AND r.deleted = 0);
+  `);
+}
+function toBinding(row) {
+    return {
+        instance: row.instance,
+        sourceId: row.source_id,
+        label: row.label,
+        deletedAt: row.deleted_at,
+        method: row.method,
+        generation: row.generation,
+        resetClock: row.reset_clock,
+    };
+}
+function ensureBinding(db, instance) {
+    db.prepare("INSERT OR IGNORE INTO pdpp_instance_binding (instance, method, generation, reset_clock) VALUES (?, NULL, 1, 0)").run(instance);
+    return db
+        .prepare("SELECT * FROM pdpp_instance_binding WHERE instance = ?")
+        .get(instance);
+}
+// A horizon that is not a non-negative integer would compare false against
+// every reset_clock and pass the P10c fence, so it is refused.
+function parseHorizon(value) {
+    const horizon = Number(value);
+    if (!/^\d+$/.test(String(value)) || !Number.isSafeInteger(horizon)) {
+        throw new InvalidCursorError();
+    }
+    return horizon;
+}
+function parseOffset(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new InvalidCursorError();
+    }
+    return value;
+}
+function instanceHasRecords(db, instance) {
+    const row = db
+        .prepare(`SELECT EXISTS(SELECT 1 FROM pdpp_records WHERE instance = ?)
+        OR EXISTS(SELECT 1 FROM pdpp_record_changes WHERE instance = ?) AS has_records`)
+        .get(instance, instance);
+    return row.has_records === 1;
+}
+function extractBlobId(data) {
+    if (!data)
+        return null;
+    const blobRef = data.blob_ref;
+    if (blobRef &&
+        typeof blobRef === "object" &&
+        typeof blobRef.blob_id === "string") {
+        return blobRef.blob_id;
+    }
+    return null;
+}
+function toRow(db) {
+    if (db.deleted) {
+        return {
+            instance: db.instance,
+            stream: db.stream,
+            recordKey: db.record_key,
+            version: db.version,
+            deletedAt: db.deleted_at ?? db.emitted_at,
+            emittedAt: db.emitted_at,
+            deleted: true,
+        };
+    }
+    return {
+        instance: db.instance,
+        stream: db.stream,
+        recordKey: db.record_key,
+        data: db.data ? JSON.parse(db.data) : {},
+        version: db.version,
+        emittedAt: db.emitted_at,
+        deleted: false,
+    };
+}
+function projectFields(data, fields) {
+    if (!fields)
+        return data;
+    const projected = {};
+    for (const field of fields) {
+        if (field in data)
+            projected[field] = data[field];
+    }
+    return projected;
+}
+/**
+ * SQLite-backed PdppRecordStore for desktop persistence. Requires
+ * `better-sqlite3` (already a `packages/server` dependency in this repo).
+ * A readonly database must already have the current schema; no migration,
+ * journal-mode change or stale-blob sweep runs. SQLite rejects write methods.
+ */
+export function createSqliteRecordStore(db) {
+    if (db.readonly) {
+        const current = db
+            .prepare("SELECT version FROM pdpp_schema_version WHERE id = 1")
+            .get();
+        if (current?.version !== MIGRATIONS.length) {
+            throw new Error("Readonly PDPP store requires the current schema version");
+        }
+    }
+    else {
+        db.pragma("journal_mode = WAL");
+        migrate(db);
+        sweepStaleBlobClaims(db);
+    }
+    const nextWriteSeq = db.prepare("UPDATE pdpp_write_clock SET value = value + 1 WHERE id = 1 RETURNING value");
+    const readWriteClockStmt = db.prepare("SELECT value FROM pdpp_write_clock WHERE id = 1");
+    const readWriteClock = () => readWriteClockStmt.get().value;
+    const getCurrentStmt = db.prepare("SELECT * FROM pdpp_records WHERE instance = ? AND stream = ? AND record_key = ?");
+    const upsertCurrentStmt = db.prepare(`
+    INSERT INTO pdpp_records (instance, stream, record_key, data, version, emitted_at, deleted, deleted_at, blob_id)
+    VALUES (@instance, @stream, @record_key, @data, @version, @emitted_at, @deleted, @deleted_at, @blob_id)
+    ON CONFLICT (instance, stream, record_key) DO UPDATE SET
+      data = excluded.data,
+      version = excluded.version,
+      emitted_at = excluded.emitted_at,
+      deleted = excluded.deleted,
+      deleted_at = excluded.deleted_at,
+      blob_id = excluded.blob_id
+  `);
+    const insertHistoryStmt = db.prepare(`
+    INSERT INTO pdpp_record_changes
+      (instance, stream, record_key, version, data, emitted_at, deleted, deleted_at, written_at)
+    VALUES (@instance, @stream, @record_key, @version, @data, @emitted_at, @deleted, @deleted_at, @written_at)
+  `);
+    const putBlobStmt = db.prepare(`
+    INSERT INTO pdpp_blobs (blob_id, mime_type, size_bytes, sha256)
+    VALUES (@blob_id, @mime_type, @size_bytes, @sha256)
+    ON CONFLICT (blob_id) DO UPDATE SET
+      mime_type = excluded.mime_type, size_bytes = excluded.size_bytes, sha256 = excluded.sha256
+  `);
+    const getBlobStmt = db.prepare("SELECT * FROM pdpp_blobs WHERE blob_id = ?");
+    const findBlobRefsStmt = db.prepare("SELECT instance, stream, record_key FROM pdpp_records WHERE blob_id = ? AND deleted = 0");
+    const insertBlobBytesStmt = db.prepare("INSERT INTO pdpp_blob_bytes (blob_id, bytes) VALUES (@blob_id, @bytes)");
+    const getBlobBytesStmt = db.prepare("SELECT bytes FROM pdpp_blob_bytes WHERE blob_id = ?");
+    const dropCompletionStmt = db.prepare("DELETE FROM pdpp_stream_completion WHERE instance = ? AND stream = ?");
+    const noteArrivalStmt = db.prepare(`
+    INSERT INTO pdpp_record_arrival (instance, stream, record_key, generation, arrival)
+    VALUES (@instance, @stream, @record_key, @generation, (
+      SELECT COALESCE(MAX(arrival), 0) + 1 FROM pdpp_record_arrival
+      WHERE instance = @instance AND stream = @stream
+    ))
+    ON CONFLICT (instance, stream, record_key) DO UPDATE SET
+      generation = excluded.generation,
+      arrival = excluded.arrival
+  `);
+    const forgetArrivalStmt = db.prepare("DELETE FROM pdpp_record_arrival WHERE instance = ? AND stream = ? AND record_key = ?");
+    /** `recordKey` is now the last live key of its stream to arrive. */
+    function noteArrival(instance, stream, recordKey, generation) {
+        noteArrivalStmt.run({
+            instance,
+            stream,
+            record_key: recordKey,
+            generation,
+        });
+        db.prepare("UPDATE pdpp_record_arrival_clock SET value = value + 1 WHERE id = 1").run();
+    }
+    function latestVersion(instance, stream, recordKey) {
+        const row = getCurrentStmt.get(instance, stream, recordKey);
+        return row?.version ?? 0;
+    }
+    function ingestBatch(envelopes, streamSemantics, primaryKeyFields, binding, validateData) {
+        const results = [];
+        // The whole batch is one SQLite transaction: a thrown error rolls back
+        // every write from this call, never leaving partial version/
+        // record_changes state. A rejected envelope is an outcome, not a
+        // failure: it writes nothing and the rest of the batch proceeds.
+        // Reads inside the transaction see earlier writes of the same batch, so
+        // two envelopes for one key are decided in order.
+        const runBatch = db.transaction(() => {
+            if (!binding) {
+                // P8a: every canonical write names its method and generation. A write
+                // without them (the sync importer, which has no method identity)
+                // cannot be checked against the binding or the blob claims, so it is
+                // refused whether or not the instance has a binding row yet.
+                envelopes.forEach((_, index) => results.push({
+                    index,
+                    outcome: "rejected",
+                    reason: "method_required",
+                }));
+                return;
+            }
+            const { generation } = binding;
+            if (envelopes.length > 0) {
+                checkBinding(binding.method, generation, envelopes);
+            }
+            envelopes.forEach((envelope, index) => {
+                const plan = planIngest(index, envelope, streamSemantics(envelope.stream, envelope.instance), primaryKeyFields(envelope.stream, envelope.instance), (recordKey) => {
+                    const row = getCurrentStmt.get(envelope.instance, envelope.stream, recordKey);
+                    return row
+                        ? {
+                            deleted: row.deleted === 1,
+                            data: row.data ? JSON.parse(row.data) : null,
+                        }
+                        : undefined;
+                }, validateData);
+                results.push(plan.outcome);
+                if (!plan.write) {
+                    // An equal re-delivery is still an arrival. A delete of a missing
+                    // key and an append_only conflict are not.
+                    if (plan.outcome.outcome === "unchanged" &&
+                        !plan.outcome.flag &&
+                        envelope.op !== "delete") {
+                        noteArrival(envelope.instance, envelope.stream, encodeRecordKey(envelope.key), generation);
+                    }
+                    return;
+                }
+                const { recordKey, data } = plan.write;
+                const blobId = extractBlobId(data);
+                if (binding &&
+                    blobId &&
+                    !blobClaimedByCurrentGeneration(blobId, envelope.instance)) {
+                    results[results.length - 1] = {
+                        index,
+                        outcome: "rejected",
+                        reason: "blob_unclaimed",
+                    };
+                    return;
+                }
+                writeVersion(envelope.instance, envelope.stream, recordKey, data, envelope.emitted_at);
+                if (data === null) {
+                    forgetArrivalStmt.run(envelope.instance, envelope.stream, recordKey);
+                }
+                else {
+                    noteArrival(envelope.instance, envelope.stream, recordKey, generation);
+                }
+            });
+        });
+        runBatch();
+        return summarizeIngest(results);
+    }
+    function blobClaimedByCurrentGeneration(blobId, instance) {
+        return !!db
+            .prepare("SELECT 1 FROM pdpp_blob_claims WHERE blob_id = ? AND instance = ? AND generation = (SELECT generation FROM pdpp_instance_binding WHERE instance = ?)")
+            .get(blobId, instance, instance);
+    }
+    /** Writes the next version of a key: `data === null` is a tombstone. */
+    function writeVersion(instance, stream, recordKey, data, emittedAt) {
+        const deleted = data === null;
+        const version = latestVersion(instance, stream, recordKey) + 1;
+        const writtenAt = nextWriteSeq.get();
+        // The stream no longer holds what a replace delivered. `replaceStream`
+        // writes its own receipt after its writes.
+        dropCompletionStmt.run(instance, stream);
+        const dataJson = deleted ? null : JSON.stringify(data);
+        const deletedAt = deleted ? emittedAt : null;
+        upsertCurrentStmt.run({
+            instance,
+            stream,
+            record_key: recordKey,
+            data: dataJson,
+            version,
+            emitted_at: emittedAt,
+            deleted: deleted ? 1 : 0,
+            deleted_at: deletedAt,
+            blob_id: extractBlobId(data),
+        });
+        insertHistoryStmt.run({
+            instance,
+            stream,
+            record_key: recordKey,
+            version,
+            data: dataJson,
+            emitted_at: emittedAt,
+            deleted: deleted ? 1 : 0,
+            deleted_at: deletedAt,
+            written_at: writtenAt.value,
+        });
+    }
+    // P7: the records are the complete live set of (instance, stream) from a
+    // covered full refresh by the bound method. Under Q1 every live row of the
+    // instance was written by that method in this generation, so a live key the
+    // snapshot lacks has no other evidence and is tombstoned. Any rejected
+    // record rejects the whole request before anything is written.
+    //
+    // With `sourceCollectedAt`, an applied replace also stores its completion
+    // receipt in the same transaction. Without it there is no receipt, and an
+    // older one is deleted: it would describe a collection that is no longer
+    // the latest.
+    function replaceStream(input) {
+        if (input.sourceCollectedAt !== undefined &&
+            !isRfc3339DateTime(input.sourceCollectedAt)) {
+            throw new TypeError("invalid_source_collected_at");
+        }
+        if (input.completionPolicy !== undefined &&
+            (input.completionPolicy !== "preserve_if_unchanged" ||
+                input.sourceCollectedAt !== undefined)) {
+            throw new TypeError("invalid_completion_policy");
+        }
+        return db.transaction(() => {
+            checkInstanceBinding(input.instance, input.method, input.generation);
+            const seen = new Set();
+            /** Live keys of the snapshot, in the order it delivered them. */
+            const snapshotOrder = [];
+            const results = [];
+            const writes = [];
+            input.envelopes.forEach((envelope, index) => {
+                const reject = (reason) => results.push({ index, outcome: "rejected", reason });
+                let recordKey;
+                try {
+                    recordKey = encodeRecordKey(envelope.key);
+                }
+                catch (err) {
+                    if (err instanceof RecordKeyError)
+                        return reject(err.message);
+                    throw err;
+                }
+                if (seen.has(recordKey))
+                    return reject("duplicate key in snapshot");
+                seen.add(recordKey);
+                const plan = planIngest(index, envelope, "mutable_state", input.primaryKey, (key) => {
+                    const row = getCurrentStmt.get(input.instance, input.stream, key);
+                    return row
+                        ? {
+                            deleted: row.deleted === 1,
+                            data: row.data ? JSON.parse(row.data) : null,
+                        }
+                        : undefined;
+                }, input.validateData);
+                if (plan.outcome.outcome === "rejected") {
+                    return void results.push(plan.outcome);
+                }
+                if (envelope.op !== "delete")
+                    snapshotOrder.push(recordKey);
+                if (!plan.write)
+                    return void results.push(plan.outcome);
+                const blobId = extractBlobId(plan.write.data);
+                if (blobId && !blobClaimedByCurrentGeneration(blobId, input.instance)) {
+                    return reject("blob_unclaimed");
+                }
+                results.push(plan.outcome);
+                writes.push({
+                    recordKey,
+                    data: plan.write.data,
+                    emittedAt: envelope.emitted_at,
+                });
+            });
+            const summary = summarizeIngest(results);
+            if (summary.rejected.length > 0) {
+                return { ...summary, applied: false, deleted: 0 };
+            }
+            const preserved = input.completionPolicy
+                ? validReceiptOfUnchangedSet(input, writes.length, seen)
+                : false;
+            for (const write of writes) {
+                writeVersion(input.instance, input.stream, write.recordKey, write.data, write.emittedAt);
+            }
+            const missing = db
+                .prepare("SELECT record_key FROM pdpp_records WHERE instance = ? AND stream = ? AND deleted = 0")
+                .all(input.instance, input.stream).filter(({ record_key }) => !seen.has(record_key));
+            for (const { record_key } of missing) {
+                writeVersion(input.instance, input.stream, record_key, null, input.emittedAt);
+            }
+            // Desktop rebuilt a fully refreshed stream in emit order, unchanged
+            // keys included.
+            db.prepare("DELETE FROM pdpp_record_arrival WHERE instance = ? AND stream = ?").run(input.instance, input.stream);
+            for (const recordKey of snapshotOrder) {
+                noteArrival(input.instance, input.stream, recordKey, input.generation);
+            }
+            if (!preserved)
+                dropCompletionStmt.run(input.instance, input.stream);
+            if (input.sourceCollectedAt !== undefined) {
+                db.prepare(`INSERT INTO pdpp_stream_completion
+             (instance, stream, method, generation, source_collected_at, write_seq, live_count)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`).run(input.instance, input.stream, input.method, input.generation, input.sourceCollectedAt, readWriteClock(), db
+                    .prepare("SELECT COUNT(*) AS n FROM pdpp_records WHERE instance = ? AND stream = ? AND deleted = 0")
+                    .get(input.instance, input.stream).n);
+            }
+            return { ...summary, applied: true, deleted: missing.length };
+        })();
+    }
+    // Under `preserve_if_unchanged`: true when this replace writes nothing to
+    // the stream's rows, no live key is missing from the snapshot, and the
+    // stream's current receipt still describes the live set. The receipt is then
+    // left as stored. Changed content is judged by `planIngest` (`writes` is
+    // empty only when every snapshot key is live and equal), and a retained
+    // extra key shows up as a live key the snapshot lacks. Anything else,
+    // including a stale or tampered receipt, returns false and the caller drops
+    // the receipt as P7 always has.
+    function validReceiptOfUnchangedSet(input, writeCount, seen) {
+        if (writeCount > 0)
+            return false;
+        const rows = db
+            .prepare("SELECT record_key, data FROM pdpp_records WHERE instance = ? AND stream = ? AND deleted = 0")
+            .all(input.instance, input.stream);
+        if (rows.some((row) => !seen.has(row.record_key)))
+            return false;
+        const prior = db
+            .prepare("SELECT * FROM pdpp_stream_completion WHERE instance = ? AND stream = ?")
+            .get(input.instance, input.stream);
+        if (!prior)
+            return false;
+        const binding = db
+            .prepare("SELECT source_id FROM pdpp_instance_binding WHERE instance = ?")
+            .get(input.instance);
+        try {
+            return receiptInvariantsHold(prior, {
+                method: input.method,
+                generation: input.generation,
+                liveCount: rows.length,
+                clock: readWriteClock(),
+                lastChange: lastChangeSeq(input.instance, input.stream),
+                digest: () => liveSnapshotDigest({ ...input, sourceId: binding.source_id }, input.primaryKey, rows.map((row) => ({
+                    recordKey: row.record_key,
+                    dataJson: row.data,
+                }))),
+            });
+        }
+        catch (error) {
+            // A live set the digest cannot describe cannot match a native receipt.
+            if (error instanceof StreamCompletionError)
+                return false;
+            throw error;
+        }
+    }
+    function checkBinding(method, generation, envelopes) {
+        const instances = new Set(envelopes.map((envelope) => envelope.instance));
+        if (instances.size !== 1)
+            throw new PdppBindingError("invalid_request");
+        checkInstanceBinding([...instances][0], method, generation);
+    }
+    /** Check every write against the connection's registered method/generation. */
+    function checkInstanceBinding(instance, method, generation) {
+        // Only a named method may write.
+        if (typeof method !== "string" || method.length === 0) {
+            throw new PdppBindingError("method_required");
+        }
+        const current = ensureBinding(db, instance);
+        if (current.deleted_at !== null) {
+            throw new PdppBindingError("connection_deleted");
+        }
+        if (current.source_id === null) {
+            throw new PdppBindingError("connection_required");
+        }
+        if (current.generation !== generation) {
+            throw new PdppBindingError("binding_generation_mismatch");
+        }
+        if (current.method !== method) {
+            throw new PdppBindingError("instance_bound_to_other_method");
+        }
+    }
+    // Read-only: an instance with no row reports the row `ensureBinding` would
+    // create, without creating it.
+    function getInstanceBinding(instance) {
+        const row = db
+            .prepare("SELECT * FROM pdpp_instance_binding WHERE instance = ?")
+            .get(instance) ?? {
+            instance,
+            source_id: null,
+            label: "",
+            deleted_at: null,
+            method: null,
+            generation: 1,
+            reset_clock: 0,
+        };
+        return {
+            ...toBinding(row),
+            empty: !instanceHasRecords(db, instance),
+        };
+    }
+    function resetInstanceBinding(input) {
+        return db.transaction(() => {
+            const current = ensureBinding(db, input.instance);
+            if (current.deleted_at !== null) {
+                throw new PdppBindingError("connection_deleted");
+            }
+            if (input.instance.startsWith("conn_") && current.source_id === null) {
+                throw new PdppBindingError("connection_required");
+            }
+            if (current.method !== input.expectedMethod ||
+                current.generation !== input.expectedGeneration) {
+                const alreadyReset = current.method === input.nextMethod &&
+                    current.generation === input.expectedGeneration + 1 &&
+                    !instanceHasRecords(db, input.instance);
+                if (alreadyReset)
+                    return { binding: toBinding(current), alreadyReset: true };
+                throw new PdppBindingError("binding_generation_mismatch");
+            }
+            // A registered connection has one method for its lifetime. Reset may
+            // erase its data and advance the generation, but it cannot rebind the
+            // connection to another method.
+            if (current.source_id !== null && current.method !== input.nextMethod) {
+                throw new PdppBindingError("connection_conflict");
+            }
+            eraseInstanceData(input.instance);
+            const resetClock = nextWriteSeq.get().value;
+            db.prepare("UPDATE pdpp_instance_binding SET method = ?, generation = ?, reset_clock = ? WHERE instance = ?").run(input.nextMethod, input.expectedGeneration + 1, resetClock, input.instance);
+            return {
+                binding: toBinding(ensureBinding(db, input.instance)),
+                alreadyReset: false,
+            };
+        })();
+    }
+    function listConnections(sourceId) {
+        const rows = db
+            .prepare("SELECT * FROM pdpp_instance_binding WHERE source_id = ? AND deleted_at IS NULL ORDER BY instance")
+            .all(sourceId);
+        return rows.map(toBinding);
+    }
+    function registerConnection(input) {
+        return db.transaction(() => {
+            const current = ensureBinding(db, input.instance);
+            if (current.deleted_at !== null) {
+                throw new PdppBindingError("connection_deleted");
+            }
+            if (current.source_id !== null &&
+                (current.source_id !== input.sourceId ||
+                    current.method !== input.method)) {
+                throw new PdppBindingError("connection_conflict");
+            }
+            if (current.method !== null && current.method !== input.method) {
+                throw new PdppBindingError("connection_conflict");
+            }
+            db.prepare("UPDATE pdpp_instance_binding SET source_id = ?, method = ?, label = ? WHERE instance = ?").run(input.sourceId, input.method, input.label, input.instance);
+            return getInstanceBinding(input.instance);
+        })();
+    }
+    function deleteConnection(instance) {
+        return db.transaction(() => {
+            const current = ensureBinding(db, instance);
+            if (current.deleted_at !== null)
+                return toBinding(current);
+            eraseInstanceData(instance);
+            const resetClock = nextWriteSeq.get().value;
+            const deletedAt = new Date().toISOString();
+            db.prepare("UPDATE pdpp_instance_binding SET deleted_at = ?, generation = generation + 1, reset_clock = ? WHERE instance = ?").run(deletedAt, resetClock, instance);
+            return getInstanceBinding(instance);
+        })();
+    }
+    function eraseInstanceData(instance) {
+        db.prepare("DELETE FROM pdpp_records WHERE instance = ?").run(instance);
+        db.prepare("DELETE FROM pdpp_record_changes WHERE instance = ?").run(instance);
+        db.prepare("DELETE FROM pdpp_blob_claims WHERE instance = ?").run(instance);
+        db.prepare("DELETE FROM pdpp_stream_completion WHERE instance = ?").run(instance);
+        db.prepare("DELETE FROM pdpp_record_arrival WHERE instance = ?").run(instance);
+        deleteUnclaimedBlobs(db);
+    }
+    function listStreamCompletions(instance) {
+        const rows = db
+            .prepare("SELECT * FROM pdpp_stream_completion WHERE instance = ? ORDER BY stream")
+            .all(instance);
+        return rows.map((row) => ({
+            instance: row.instance,
+            stream: row.stream,
+            method: row.method,
+            generation: row.generation,
+            sourceCollectedAt: row.source_collected_at,
+            writeSeq: row.write_seq,
+            liveCount: row.live_count,
+        }));
+    }
+    function lastChangeSeq(instance, stream) {
+        return db
+            .prepare("SELECT COALESCE(MAX(written_at), 0) AS seq FROM pdpp_record_changes WHERE instance = ? AND stream = ?")
+            .get(instance, stream).seq;
+    }
+    /**
+     * Whether a stored receipt still describes the live set it was written
+     * for. It never compares the write clock to the global one: unrelated
+     * writes move that without touching this stream.
+     */
+    function receiptInvariantsHold(prior, expected) {
+        const native = prior.snapshot_sha256 !== null;
+        return (prior.method === expected.method &&
+            prior.generation === expected.generation &&
+            prior.live_count === expected.liveCount &&
+            Number.isSafeInteger(prior.write_seq) &&
+            prior.write_seq >= 0 &&
+            prior.write_seq <= expected.clock &&
+            prior.write_seq >= expected.lastChange &&
+            (native
+                ? isCompletionTime(prior.source_collected_at)
+                : isRfc3339DateTime(prior.source_collected_at)) &&
+            native === (prior.collection_time_basis !== null) &&
+            (!native ||
+                (prior.snapshot_sha256 === expected.digest() &&
+                    prior.collection_time_basis === "host_run_finished")));
+    }
+    function completeStreams(rawRequest, declarations) {
+        const request = parseCompletionRequest(rawRequest);
+        return db
+            .transaction(() => {
+            const binding = db
+                .prepare("SELECT * FROM pdpp_instance_binding WHERE instance = ?")
+                .get(request.instance);
+            if (!binding || binding.source_id === null) {
+                throw new PdppBindingError("connection_required");
+            }
+            if (binding.deleted_at !== null) {
+                throw new PdppBindingError("connection_deleted");
+            }
+            if (binding.source_id !== request.sourceId) {
+                throw new PdppBindingError("source_mismatch");
+            }
+            if (binding.generation !== request.generation) {
+                throw new PdppBindingError("binding_generation_mismatch");
+            }
+            if (binding.method !== request.method) {
+                throw new PdppBindingError("instance_bound_to_other_method");
+            }
+            const clock = readWriteClock();
+            const requestedAt = Date.parse(request.sourceCollectedAt);
+            // Validate every stream before the first receipt is written.
+            const writes = [];
+            for (const proof of request.streams) {
+                const primaryKey = declarations(request.sourceId, proof.stream);
+                if (primaryKey === undefined) {
+                    throw new StreamCompletionError("unknown_stream");
+                }
+                if (primaryKey.length === 0 ||
+                    !primaryKey.every((field) => typeof field === "string" && field)) {
+                    throw new StreamCompletionError("invalid_declaration");
+                }
+                const rows = db
+                    .prepare("SELECT record_key, data FROM pdpp_records WHERE instance = ? AND stream = ? AND deleted = 0")
+                    .all(request.instance, proof.stream);
+                if (rows.length !== proof.liveCount) {
+                    throw new StreamCompletionError("snapshot_conflict");
+                }
+                const digest = liveSnapshotDigest({ ...request, stream: proof.stream }, primaryKey, rows.map((row) => ({
+                    recordKey: row.record_key,
+                    dataJson: row.data,
+                })));
+                if (digest !== proof.snapshotSha256) {
+                    throw new StreamCompletionError("snapshot_conflict");
+                }
+                const prior = db
+                    .prepare("SELECT * FROM pdpp_stream_completion WHERE instance = ? AND stream = ?")
+                    .get(request.instance, proof.stream);
+                if (!prior) {
+                    writes.push({ stream: proof.stream, kind: "insert" });
+                    continue;
+                }
+                // A receipt is deleted by every write that could invalidate it, so a
+                // stored one that disagrees with the live data was tampered with.
+                const native = prior.snapshot_sha256 !== null;
+                if (!receiptInvariantsHold(prior, {
+                    method: request.method,
+                    generation: request.generation,
+                    liveCount: rows.length,
+                    clock,
+                    lastChange: lastChangeSeq(request.instance, proof.stream),
+                    digest: () => digest,
+                })) {
+                    throw new StreamCompletionError("invalid_prior_receipt");
+                }
+                const priorAt = Date.parse(prior.source_collected_at);
+                if (requestedAt < priorAt) {
+                    throw new StreamCompletionError("time_conflict");
+                }
+                if (requestedAt === priorAt) {
+                    // Same instant: an exact replay keeps its bytes. A digest-less
+                    // receipt cannot be relabeled as native proof at its own time.
+                    if (!native)
+                        throw new StreamCompletionError("time_conflict");
+                    writes.push({ stream: proof.stream, kind: "keep" });
+                }
+                else {
+                    writes.push({ stream: proof.stream, kind: "update" });
+                }
+            }
+            for (const [index, write] of writes.entries()) {
+                const proof = request.streams[index];
+                if (write.kind === "insert") {
+                    db.prepare(`INSERT INTO pdpp_stream_completion
+               (instance, stream, method, generation, source_collected_at, write_seq, live_count, snapshot_sha256, collection_time_basis)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(request.instance, proof.stream, request.method, request.generation, request.sourceCollectedAt, clock, proof.liveCount, proof.snapshotSha256, request.collectionTimeBasis);
+                }
+                else if (write.kind === "update") {
+                    db.prepare(`UPDATE pdpp_stream_completion
+                SET source_collected_at = ?, write_seq = ?, snapshot_sha256 = ?, collection_time_basis = ?
+              WHERE instance = ? AND stream = ?`).run(request.sourceCollectedAt, clock, proof.snapshotSha256, request.collectionTimeBasis, request.instance, proof.stream);
+                }
+            }
+            return {
+                receipts: request.streams.map((proof) => {
+                    const row = db
+                        .prepare("SELECT * FROM pdpp_stream_completion WHERE instance = ? AND stream = ?")
+                        .get(request.instance, proof.stream);
+                    return {
+                        instance: row.instance,
+                        stream: row.stream,
+                        method: row.method,
+                        generation: row.generation,
+                        sourceCollectedAt: row.source_collected_at,
+                        writeSeq: row.write_seq,
+                        liveCount: row.live_count,
+                        snapshotSha256: row.snapshot_sha256,
+                        collectionTimeBasis: "host_run_finished",
+                    };
+                }),
+            };
+        })
+            .immediate();
+    }
+    function listArrivalOrder(instance, stream) {
+        const rows = db
+            .prepare(`SELECT a.record_key FROM pdpp_record_arrival a
+         JOIN pdpp_instance_binding b
+           ON b.instance = a.instance AND b.generation = a.generation
+         WHERE a.instance = ? AND a.stream = ?
+         ORDER BY a.arrival`)
+            .all(instance, stream);
+        return rows.map((row) => row.record_key);
+    }
+    function getRecord(instance, stream, recordKey) {
+        const row = getCurrentStmt.get(instance, stream, recordKey);
+        if (!row || row.deleted)
+            return undefined;
+        return toRow(row);
+    }
+    // P10c: a token whose horizon is below the reset_clock of any instance it
+    // reads spans a reset. `null` means the token predates horizons, so any
+    // reset of a read instance expires it.
+    function assertNotResetSince(instanceIds, horizons) {
+        if (instanceIds.length === 0)
+            return;
+        const resetClocks = db
+            .prepare(`SELECT reset_clock FROM pdpp_instance_binding
+         WHERE instance IN (${instanceIds.map(() => "?").join(",")}) AND reset_clock > 0`)
+            .all(...instanceIds);
+        if (resetClocks.some(({ reset_clock }) => horizons.some((h) => h === null || h < reset_clock))) {
+            throw new CursorExpiredError();
+        }
+    }
+    function cursorEpoch() {
+        const row = db
+            .prepare("SELECT epoch FROM pdpp_store_metadata WHERE id = 1")
+            .get();
+        if (!row)
+            throw new CursorExpiredError();
+        return row.epoch;
+    }
+    function assertCursorScope(payload, stream) {
+        if (payload.stream !== stream) {
+            throw new CursorExpiredError();
+        }
+        if (payload.epoch !== cursorEpoch()) {
+            throw new CursorExpiredError();
+        }
+    }
+    function listRecords(stream, options) {
+        let startAfter = null;
+        let horizon;
+        if (options.cursor) {
+            const payload = decodeCursor(options.cursor);
+            if (payload.kind !== "list")
+                throw new InvalidCursorError();
+            assertCursorScope(payload, stream);
+            if (payload.order !== options.order)
+                throw new InvalidCursorError();
+            const cursorHorizon = payload.horizon === undefined ? null : parseHorizon(payload.horizon);
+            assertNotResetSince(options.instanceIds, [cursorHorizon]);
+            // A legacy cursor that survives the fence read no reset instance; it
+            // is anchored at the current clock from here on.
+            horizon = cursorHorizon ?? readWriteClock();
+            startAfter = { val: payload.sortValue ?? "", key: payload.recordKey };
+        }
+        else {
+            horizon = readWriteClock();
+        }
+        const placeholders = options.instanceIds.map(() => "?").join(",");
+        const dir = options.order === "asc" ? "ASC" : "DESC";
+        const cmp = options.order === "asc" ? ">" : "<";
+        let sql = `
+      SELECT * FROM pdpp_records
+      WHERE stream = ? AND deleted = 0 AND instance IN (${placeholders})
+    `;
+        const params = [stream, ...options.instanceIds];
+        if (startAfter) {
+            sql += ` AND (emitted_at ${cmp} ? OR (emitted_at = ? AND record_key ${cmp} ?))`;
+            params.push(startAfter.val, startAfter.val, startAfter.key);
+        }
+        sql += ` ORDER BY emitted_at ${dir}, record_key ${dir} LIMIT ?`;
+        params.push(options.limit + 1);
+        const rows = db.prepare(sql).all(...params);
+        const hasMore = rows.length > options.limit;
+        const page = rows.slice(0, options.limit);
+        const last = page[page.length - 1];
+        return {
+            data: page.map((row) => {
+                const stored = toRow(row);
+                return { ...stored, data: projectFields(stored.data, options.fields) };
+            }),
+            hasMore,
+            nextCursor: hasMore && last
+                ? encodeCursor({
+                    kind: "list",
+                    stream,
+                    epoch: cursorEpoch(),
+                    order: options.order,
+                    sortValue: last.emitted_at,
+                    recordKey: last.record_key,
+                    horizon: String(horizon),
+                })
+                : undefined,
+            horizon: String(horizon),
+        };
+    }
+    function deleteRecord(instance, stream, recordKey, deletedAt, streamSemantics) {
+        if (streamSemantics === "append_only")
+            return false;
+        let result = false;
+        const run = db.transaction(() => {
+            const existing = getCurrentStmt.get(instance, stream, recordKey);
+            if (!existing || existing.deleted)
+                return;
+            const version = existing.version + 1;
+            const writtenAt = nextWriteSeq.get();
+            dropCompletionStmt.run(instance, stream);
+            upsertCurrentStmt.run({
+                instance,
+                stream,
+                record_key: recordKey,
+                data: null,
+                version,
+                emitted_at: deletedAt,
+                deleted: 1,
+                deleted_at: deletedAt,
+                blob_id: null,
+            });
+            insertHistoryStmt.run({
+                instance,
+                stream,
+                record_key: recordKey,
+                version,
+                data: null,
+                emitted_at: deletedAt,
+                deleted: 1,
+                deleted_at: deletedAt,
+                written_at: writtenAt.value,
+            });
+            forgetArrivalStmt.run(instance, stream, recordKey);
+            result = true;
+        });
+        run();
+        return result;
+    }
+    function changesSince(stream, options) {
+        let horizon;
+        let sinceHorizon;
+        let offset = 0;
+        if (options.cursor) {
+            const payload = decodeCursor(options.cursor);
+            if (payload.kind !== "changes_since")
+                throw new InvalidCursorError();
+            assertCursorScope(payload, stream);
+            horizon = parseHorizon(payload.horizon);
+            sinceHorizon =
+                payload.sinceHorizon !== null
+                    ? parseHorizon(payload.sinceHorizon)
+                    : null;
+            offset = parseOffset(payload.offset);
+        }
+        else if (options.changesSince) {
+            let payload;
+            try {
+                payload = decodeCursor(options.changesSince);
+            }
+            catch (err) {
+                if (err instanceof InvalidCursorSyntaxError)
+                    throw new CursorExpiredError();
+                throw err;
+            }
+            if (payload.kind !== "changes_since")
+                throw new InvalidCursorError();
+            assertCursorScope(payload, stream);
+            sinceHorizon = parseHorizon(payload.horizon);
+            horizon = nextWriteSeq.get().value;
+        }
+        else {
+            sinceHorizon = null;
+            horizon = nextWriteSeq.get().value;
+        }
+        assertNotResetSince(options.instanceIds, [
+            horizon,
+            sinceHorizon ?? horizon,
+        ]);
+        const placeholders = options.instanceIds.map(() => "?").join(",");
+        // Latest history row per key, as of the horizon.
+        const latestRows = db
+            .prepare(`
+        SELECT c.* FROM pdpp_record_changes c
+        WHERE c.stream = ? AND c.instance IN (${placeholders}) AND c.written_at <= ?
+        AND c.version = (
+          SELECT MAX(c2.version) FROM pdpp_record_changes c2
+          WHERE c2.stream = c.stream AND c2.instance = c.instance
+            AND c2.record_key = c.record_key AND c2.written_at <= ?
+        )
+      `)
+            .all(stream, ...options.instanceIds, horizon, horizon);
+        const changed = [];
+        for (const entry of latestRows) {
+            if (sinceHorizon !== null) {
+                const wroteSincePrior = db
+                    .prepare(`SELECT 1 FROM pdpp_record_changes
+             WHERE stream = ? AND instance = ? AND record_key = ?
+             AND written_at > ? AND written_at <= ? LIMIT 1`)
+                    .get(entry.stream, entry.instance, entry.record_key, sinceHorizon, horizon);
+                if (!wroteSincePrior)
+                    continue;
+            }
+            if (entry.deleted) {
+                changed.push({
+                    instance: entry.instance,
+                    stream: entry.stream,
+                    recordKey: entry.record_key,
+                    version: entry.version,
+                    deletedAt: entry.deleted_at ?? entry.emitted_at,
+                    emittedAt: entry.emitted_at,
+                    deleted: true,
+                });
+                continue;
+            }
+            const currentData = entry.data ? JSON.parse(entry.data) : {};
+            const projectedNow = projectFields(currentData, options.fields);
+            if (sinceHorizon !== null && options.fields) {
+                const priorRow = db
+                    .prepare(`SELECT * FROM pdpp_record_changes
+             WHERE stream = ? AND instance = ? AND record_key = ? AND written_at <= ?
+             ORDER BY version DESC LIMIT 1`)
+                    .get(entry.stream, entry.instance, entry.record_key, sinceHorizon);
+                if (priorRow && !priorRow.deleted) {
+                    const priorData = priorRow.data ? JSON.parse(priorRow.data) : {};
+                    const priorProjected = projectFields(priorData, options.fields);
+                    if (JSON.stringify(priorProjected) === JSON.stringify(projectedNow)) {
+                        continue;
+                    }
+                }
+            }
+            // Return the RAW (unprojected) data here, not `projectedNow`.
+            // `projectedNow`/`priorProjected` above exist only to decide
+            // eligibility (did the grant-authorized projection change) without
+            // leaking a hidden-field change. A caller enforcing time_constraint
+            // against `data` needs the real field value; projecting here would
+            // silently break that filter for any grant whose fields don't happen
+            // to include the time_constraint field. Response field projection is
+            // the caller's job, applied after any filtering on real values.
+            changed.push({
+                instance: entry.instance,
+                stream: entry.stream,
+                recordKey: entry.record_key,
+                data: currentData,
+                version: entry.version,
+                emittedAt: entry.emitted_at,
+                deleted: false,
+            });
+        }
+        changed.sort((a, b) => a.recordKey.localeCompare(b.recordKey));
+        const page = changed.slice(offset, offset + options.limit);
+        const hasMore = offset + options.limit < changed.length;
+        return {
+            data: page,
+            hasMore,
+            nextCursor: hasMore
+                ? encodeCursor({
+                    kind: "changes_since",
+                    stream,
+                    epoch: cursorEpoch(),
+                    horizon: String(horizon),
+                    sinceHorizon: sinceHorizon !== null ? String(sinceHorizon) : null,
+                    offset: offset + options.limit,
+                })
+                : undefined,
+            nextChangesSince: hasMore
+                ? undefined
+                : encodeCursor({
+                    kind: "changes_since",
+                    stream,
+                    epoch: cursorEpoch(),
+                    horizon: String(horizon),
+                    sinceHorizon: null,
+                    offset: 0,
+                }),
+        };
+    }
+    function listStreams(instanceIds) {
+        const placeholders = instanceIds.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT stream, COUNT(*) as count, MAX(emitted_at) as last_updated
+         FROM pdpp_records WHERE deleted = 0 AND instance IN (${placeholders})
+         GROUP BY stream`)
+            .all(...instanceIds);
+        return rows.map((r) => ({
+            stream: r.stream,
+            recordCount: r.count,
+            lastUpdated: r.last_updated,
+        }));
+    }
+    function getBlobMeta(blobId) {
+        const row = getBlobStmt.get(blobId);
+        if (!row)
+            return undefined;
+        return {
+            blobId: row.blob_id,
+            mimeType: row.mime_type,
+            sizeBytes: row.size_bytes,
+            sha256: row.sha256,
+        };
+    }
+    /** True only when a stored bytes row actually hash/size-matches `meta`. */
+    function storedBytesVerify(meta) {
+        const row = getBlobBytesStmt.get(meta.blobId);
+        if (!row)
+            return false;
+        const stored = new Uint8Array(row.bytes);
+        if (stored.byteLength !== meta.sizeBytes)
+            return false;
+        return createHash("sha256").update(stored).digest("hex") === meta.sha256;
+    }
+    function storeBlobBytes(bytes, mimeType) {
+        const blobId = blobIdForBytes(bytes);
+        const sha256 = blobId.slice("sha256:".length);
+        const candidate = {
+            blobId,
+            mimeType,
+            sizeBytes: bytes.byteLength,
+            sha256,
+        };
+        // The existing-row read and the write both happen inside one
+        // transaction, not a check-then-upsert outside it -- otherwise two
+        // concurrent writers for the same content could both see "no existing
+        // row" and race to insert, or one could complete a metadata-only row
+        // while another concurrently overwrites it.
+        const run = db.transaction(() => {
+            const existing = getBlobMeta(blobId);
+            if (existing) {
+                if (existing.mimeType !== mimeType ||
+                    existing.sha256 !== sha256 ||
+                    existing.sizeBytes !== bytes.byteLength) {
+                    throw new BlobConflictError(blobId, existing);
+                }
+                const bytesRow = getBlobBytesStmt.get(blobId);
+                if (!bytesRow) {
+                    // Metadata-only row (legacy/test fixture via putBlobMeta, or a
+                    // prior write that never got this far): complete it with real
+                    // bytes now instead of reporting a false "already stored" no-op.
+                    insertBlobBytesStmt.run({
+                        blob_id: existing.blobId,
+                        bytes: Buffer.from(bytes),
+                    });
+                    return existing;
+                }
+                if (!storedBytesVerify(existing)) {
+                    // Bytes present but corrupt relative to their own metadata.
+                    // Refuse rather than report success over broken content, and
+                    // rather than silently repair -- the row stays exactly as it was
+                    // (the transaction makes no writes on this branch).
+                    throw new BlobConflictError(blobId, existing);
+                }
+                // Verified idempotent no-op: content and mimeType both match.
+                return existing;
+            }
+            putBlobStmt.run({
+                blob_id: candidate.blobId,
+                mime_type: candidate.mimeType,
+                size_bytes: candidate.sizeBytes,
+                sha256: candidate.sha256,
+            });
+            insertBlobBytesStmt.run({
+                blob_id: candidate.blobId,
+                bytes: Buffer.from(bytes),
+            });
+            return candidate;
+        });
+        return run();
+    }
+    function storeBlobBytesForInstance(input) {
+        return db.transaction(() => {
+            const binding = ensureBinding(db, input.instance);
+            if (binding.deleted_at !== null) {
+                throw new PdppBindingError("connection_deleted");
+            }
+            if (binding.source_id === null) {
+                throw new PdppBindingError("connection_required");
+            }
+            if (binding.generation !== input.generation) {
+                throw new PdppBindingError("binding_generation_mismatch");
+            }
+            if (binding.method !== input.method) {
+                throw new PdppBindingError("instance_bound_to_other_method");
+            }
+            const meta = storeBlobBytes(input.bytes, input.mimeType);
+            db.prepare(`INSERT INTO pdpp_blob_claims (blob_id, instance, generation)
+         VALUES (?, ?, ?)
+         ON CONFLICT (blob_id, instance) DO UPDATE SET generation = excluded.generation`).run(meta.blobId, input.instance, input.generation);
+            return meta;
+        })();
+    }
+    function getBlobBytes(blobId) {
+        const meta = getBlobMeta(blobId);
+        if (!meta)
+            return undefined;
+        const row = getBlobBytesStmt.get(blobId);
+        if (!row)
+            return undefined;
+        const bytes = new Uint8Array(row.bytes);
+        if (bytes.byteLength !== meta.sizeBytes)
+            return undefined;
+        const actualHash = createHash("sha256").update(bytes).digest("hex");
+        if (actualHash !== meta.sha256)
+            return undefined;
+        return bytes;
+    }
+    return {
+        listConnections,
+        registerConnection,
+        deleteConnection,
+        ingestBatch,
+        getInstanceBinding,
+        readSnapshot: (read) => db.transaction(read).deferred(),
+        resetInstanceBinding,
+        storeBlobBytesForInstance,
+        replaceStream,
+        listStreamCompletions,
+        completeStreams,
+        listArrivalOrder,
+        getRecord,
+        listRecords,
+        deleteRecord,
+        changesSince,
+        listStreams,
+        putBlobMeta: (meta) => putBlobStmt.run({
+            blob_id: meta.blobId,
+            mime_type: meta.mimeType,
+            size_bytes: meta.sizeBytes,
+            sha256: meta.sha256,
+        }),
+        getBlobMeta,
+        storeBlobBytes,
+        getBlobBytes,
+        findBlobReferences: (blobId) => {
+            const rows = findBlobRefsStmt.all(blobId);
+            return rows.map((row) => ({
+                instance: row.instance,
+                stream: row.stream,
+                recordKey: row.record_key,
+            }));
+        },
+        close: () => db.close(),
+    };
+}
+//# sourceMappingURL=pdpp-records-sqlite-store.js.map