@syncular/server 0.21.1 → 0.23.0

package/dist/segment-store.js

@@ -8,6 +8,144 @@
  */
 import { sha256Hex } from './scopes.js';
 export const DEFAULT_SEGMENT_TTL_MS = 24 * 60 * 60 * 1000;
+/** Canonical identity of one publication; two equal keys are one grant. */
+export function publicationKey(metadata) {
+    return JSON.stringify([
+        metadata.partition,
+        metadata.logEpoch,
+        metadata.table,
+        metadata.schemaVersion,
+        metadata.mediaType,
+        metadata.scopeDigest,
+        metadata.asOfCommitSeq,
+        metadata.rowCursor,
+        metadata.nextRowCursor,
+    ]);
+}
+/**
+ * Materialize publications for a record written before provenance existed
+ * (in-flight 0.21 objects, §5.1). Only the merged top-level context is
+ * known, so each recorded digest is one publication under it: that is the
+ * old single-record read behavior preserved verbatim.
+ */
+export function publicationsForRecord(record) {
+    return record.scopeDigests.map((scopeDigest) => ({
+        partition: record.partition,
+        logEpoch: record.logEpoch,
+        table: record.table,
+        schemaVersion: record.schemaVersion,
+        mediaType: record.mediaType,
+        scopeDigest,
+        asOfCommitSeq: record.asOfCommitSeq,
+        rowCount: record.rowCount,
+        rowCursor: record.rowCursor,
+        nextRowCursor: record.nextRowCursor,
+        byteLength: record.byteLength,
+        createdAtMs: record.createdAtMs,
+        expiresAtMs: record.expiresAtMs,
+    }));
+}
+export function selectSegmentPublication(record, context) {
+    for (let index = record.publications.length - 1; index >= 0; index--) {
+        const publication = record.publications[index];
+        if (publication.partition === context.partition &&
+            publication.logEpoch === context.logEpoch &&
+            publication.scopeDigest === context.scopeDigest &&
+            (context.table === undefined || publication.table === context.table) &&
+            (context.schemaVersion === undefined ||
+                publication.schemaVersion === context.schemaVersion) &&
+            (context.mediaType === undefined ||
+                publication.mediaType === context.mediaType) &&
+            (context.asOfCommitSeq === undefined ||
+                publication.asOfCommitSeq === context.asOfCommitSeq) &&
+            (context.rowCursor === undefined ||
+                publication.rowCursor === context.rowCursor) &&
+            (context.nowMs === undefined || publication.expiresAtMs > context.nowMs)) {
+            return publication;
+        }
+    }
+    return undefined;
+}
+/**
+ * Project a record onto one publication. The compatibility view is narrowed
+ * to that grant: `scopeDigests` and `publications` hold only the chosen
+ * publication, so a caller that authorizes from them cannot union a grant
+ * from a different partition or epoch.
+ */
+export function publicationRecord(record, publication) {
+    return {
+        ...record,
+        ...publication,
+        scopeDigests: [publication.scopeDigest],
+        publications: [publication],
+    };
+}
+/** Byte equality for the content-address collision check (§5.1). */
+export function segmentBytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Merge one publication into the stored entry for the same content address
+ * (§5.1). Identical bytes are one entry: the record takes the incoming
+ * publication's metadata (a later publisher's descriptor, scope digest, and
+ * cursors stay consistent with what it just published), the scope digests
+ * union with the incoming digest first (the record's primary `scopeDigest`),
+ * `createdAtMs` keeps the earliest sighting, and `expiresAtMs` takes the
+ * later expiry. A publication with the incoming context merges into that
+ * publication's own lifetime; a publication with a new context is appended,
+ * so no context's grant is overwritten or extended by another. Publications
+ * whose own TTL has elapsed at `nowMs` are pruned from the stored entry —
+ * SPEC §5.5 lets the cache forget expired grants, and pruning on put keeps
+ * the publication set bounded by live contexts instead of by every context
+ * ever seen. Callers MUST have proven the bytes identical first.
+ */
+export function mergeSegmentRecord(existing, metadata, segmentId, byteLength, nowMs, ttlMs) {
+    // Prune grants that have already elapsed at this write (§5.5): bounded by
+    // live contexts, not by the unbounded set of contexts ever published.
+    const prior = (existing?.publications ?? []).filter((publication) => publication.expiresAtMs > nowMs);
+    const fresh = {
+        ...metadata,
+        byteLength,
+        createdAtMs: nowMs,
+        expiresAtMs: nowMs + ttlMs,
+    };
+    const key = publicationKey(metadata);
+    const at = prior.findIndex((publication) => publicationKey(publication) === key);
+    // Re-publication of one context merges that publication's lifetime only:
+    // an unrelated refresh must not extend another publication's grant (§5.1).
+    const publications = at < 0
+        ? [...prior, fresh]
+        : prior.map((publication, index) => index === at
+            ? {
+                ...fresh,
+                createdAtMs: Math.min(publication.createdAtMs, nowMs),
+                expiresAtMs: Math.max(publication.expiresAtMs, nowMs + ttlMs),
+            }
+            : publication);
+    return {
+        ...metadata,
+        segmentId,
+        // Compatibility view over the retained publications only, incoming
+        // primary first: a pruned publication's digest is gone, not just its
+        // descriptor.
+        scopeDigests: [
+            metadata.scopeDigest,
+            ...new Set(publications
+                .map((publication) => publication.scopeDigest)
+                .filter((digest) => digest !== metadata.scopeDigest)),
+        ],
+        publications,
+        byteLength,
+        createdAtMs: Math.min(existing?.createdAtMs ?? nowMs, nowMs),
+        expiresAtMs: Math.max(existing?.expiresAtMs ?? nowMs + ttlMs, nowMs + ttlMs),
+    };
+}
 export async function segmentIdFor(bytes) {
     return `sha256:${await sha256Hex(bytes)}`;
 }
@@ -19,13 +157,11 @@ export class MemorySegmentStore {
     }
     async put(metadata, bytes, nowMs) {
         const segmentId = await segmentIdFor(bytes);
-        const record = {
-            ...metadata,
-            segmentId,
-            byteLength: bytes.length,
-            createdAtMs: nowMs,
-            expiresAtMs: nowMs + this.#ttlMs,
-        };
+        const existing = this.#entries.get(segmentId);
+        if (existing !== undefined && !segmentBytesEqual(existing.bytes, bytes)) {
+            throw new Error(`MemorySegmentStore: content-address collision at ${segmentId} (§5.1)`);
+        }
+        const record = mergeSegmentRecord(existing?.record, metadata, segmentId, bytes.length, nowMs, this.#ttlMs);
         this.#entries.set(segmentId, { record, bytes });
         return record;
     }
@@ -34,16 +170,19 @@ export class MemorySegmentStore {
     }
     async find(key, nowMs) {
         for (const { record } of this.#entries.values()) {
-            if (record.partition === key.partition &&
-                record.logEpoch === key.logEpoch &&
-                record.table === key.table &&
-                record.schemaVersion === key.schemaVersion &&
-                record.mediaType === key.mediaType &&
-                record.scopeDigest === key.scopeDigest &&
-                record.asOfCommitSeq === key.asOfCommitSeq &&
-                record.rowCursor === null &&
-                record.expiresAtMs > nowMs) {
-                return record;
+            const publication = selectSegmentPublication(record, {
+                partition: key.partition,
+                logEpoch: key.logEpoch,
+                table: key.table,
+                schemaVersion: key.schemaVersion,
+                mediaType: key.mediaType,
+                scopeDigest: key.scopeDigest,
+                asOfCommitSeq: key.asOfCommitSeq,
+                rowCursor: null,
+                nowMs,
+            });
+            if (publication !== undefined) {
+                return publicationRecord(record, publication);
             }
         }
         return undefined;

package/dist/signed-url.d.ts

@@ -129,10 +129,16 @@ export declare function signSegmentToken(key: string | Uint8Array, claims: Segme
 /**
  * Verify a segment token per §5.4. Throws `SyncError sync.forbidden` on any
  * failure (MAC, expiry, or claim mismatch).
+ *
+ * `scopeDigest` is the set of scope digests the token may authorize. Pass the
+ * digests of the stored record's publications that match the verifying host's
+ * partition: identical bytes are one content address (§5.1), but a digest
+ * recorded under another partition is not this host's grant (§5.4). A single
+ * string stays valid for a record with one publication.
  */
 export declare function verifySegmentToken(key: string | Uint8Array, token: string, expected: {
     readonly segmentId: string;
-    readonly scopeDigest: string;
+    readonly scopeDigest: string | readonly string[];
     readonly audience: string;
     readonly nowMs: number;
     readonly skewSeconds?: number;

package/dist/signed-url.js

@@ -108,6 +108,12 @@ const DEFAULT_SKEW_SECONDS = 60;
 /**
  * Verify a segment token per §5.4. Throws `SyncError sync.forbidden` on any
  * failure (MAC, expiry, or claim mismatch).
+ *
+ * `scopeDigest` is the set of scope digests the token may authorize. Pass the
+ * digests of the stored record's publications that match the verifying host's
+ * partition: identical bytes are one content address (§5.1), but a digest
+ * recorded under another partition is not this host's grant (§5.4). A single
+ * string stays valid for a record with one publication.
  */
 export async function verifySegmentToken(key, token, expected) {
     const forbidden = (reason) => syncError('sync.forbidden', `segment token rejected: ${reason}`);
@@ -135,7 +141,10 @@ export async function verifySegmentToken(key, token, expected) {
     }
     if (claims.seg !== expected.segmentId)
         throw forbidden('segment mismatch');
-    if (claims.sd !== expected.scopeDigest)
+    const scopeDigests = typeof expected.scopeDigest === 'string'
+        ? [expected.scopeDigest]
+        : expected.scopeDigest;
+    if (!scopeDigests.includes(claims.sd))
         throw forbidden('scope-digest mismatch');
     if (claims.aud !== expected.audience)
         throw forbidden('audience mismatch');

package/dist/sqlite-dialect.d.ts

@@ -29,8 +29,14 @@ import type { StoredChange, StoredCommit, StoredPushResult, StoredRow } from './
  * range that returns already-ordered rows — the same covering-index shape
  * the Postgres storage documents (§3.1, performance-by-
  * construction).
+ *
+ * `sync_row_scopes_by_row` is the one secondary scope index: a per-row
+ * scope replacement predicates on `(partition, tbl, row_id)`, and `row_id`
+ * is the LAST PRIMARY KEY column, so that predicate cannot narrow the
+ * inverted index. Declared here so every SQLite-family storage (and D1,
+ * which applies this same DDL) keeps the same plan shape as Postgres.
  */
-export declare const SQLITE_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq INTEGER NOT NULL DEFAULT 0,\n  horizon_seq INTEGER NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_partition_registry(\n  partition TEXT PRIMARY KEY,\n  log_epoch TEXT NOT NULL,\n  epoch_required INTEGER NOT NULL DEFAULT 0,\n  last_authenticated_at_ms INTEGER NOT NULL\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,\n  row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result TEXT NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,\n  available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,\n  last_failure TEXT,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  wire_version INTEGER NOT NULL DEFAULT 1,\n  cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,\n  updated_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\nCREATE TABLE IF NOT EXISTS sync_tombstones(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id)\n);\n";
+export declare const SQLITE_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq INTEGER NOT NULL DEFAULT 0,\n  horizon_seq INTEGER NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_partition_registry(\n  partition TEXT PRIMARY KEY,\n  log_epoch TEXT NOT NULL,\n  epoch_required INTEGER NOT NULL DEFAULT 0,\n  last_authenticated_at_ms INTEGER NOT NULL\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE INDEX IF NOT EXISTS sync_row_scopes_by_row\n  ON sync_row_scopes(partition, tbl, row_id);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,\n  writer_version INTEGER,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,\n  row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result TEXT NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,\n  available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,\n  last_failure TEXT,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  wire_version INTEGER NOT NULL DEFAULT 1,\n  cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,\n  updated_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\nCREATE TABLE IF NOT EXISTS sync_tombstones(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_backfill_checkpoints(\n  partition TEXT NOT NULL, name TEXT NOT NULL,\n  schema_version INTEGER NOT NULL,\n  state TEXT NOT NULL CHECK(state IN ('declared','backfilling','activated')),\n  watermark INTEGER NOT NULL DEFAULT 0,\n  owner_epoch INTEGER NOT NULL DEFAULT 0,\n  observed_rows INTEGER NOT NULL DEFAULT 0,\n  updated_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, name)\n);\nCREATE TABLE IF NOT EXISTS sync_writer_fence(\n  partition TEXT PRIMARY KEY,\n  required_writer_version INTEGER NOT NULL\n);\n";
 /** Split the DDL into individual statements (D1 applies them one by one). */
 export declare function sqliteDdlStatements(): string[];
 /** `?,?,…` for an `IN (…)` clause of `count` positional parameters. */

package/dist/sqlite-dialect.js

@@ -11,6 +11,12 @@ import { matchesEffective } from './scopes.js';
  * range that returns already-ordered rows — the same covering-index shape
  * the Postgres storage documents (§3.1, performance-by-
  * construction).
+ *
+ * `sync_row_scopes_by_row` is the one secondary scope index: a per-row
+ * scope replacement predicates on `(partition, tbl, row_id)`, and `row_id`
+ * is the LAST PRIMARY KEY column, so that predicate cannot narrow the
+ * inverted index. Declared here so every SQLite-family storage (and D1,
+ * which applies this same DDL) keeps the same plan shape as Postgres.
  */
 export const SQLITE_DDL = `
 CREATE TABLE IF NOT EXISTS sync_partitions(
@@ -29,10 +35,13 @@ CREATE TABLE IF NOT EXISTS sync_row_scopes(
   var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,
   PRIMARY KEY(partition, tbl, var, value, row_id)
 );
+CREATE INDEX IF NOT EXISTS sync_row_scopes_by_row
+  ON sync_row_scopes(partition, tbl, row_id);
 CREATE TABLE IF NOT EXISTS sync_commits(
   partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,
   client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,
   actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,
+  writer_version INTEGER,
   PRIMARY KEY(partition, commit_seq)
 );
 CREATE INDEX IF NOT EXISTS sync_commits_by_time
@@ -94,6 +103,20 @@ CREATE TABLE IF NOT EXISTS sync_tombstones(
   commit_seq INTEGER NOT NULL,
   PRIMARY KEY(partition, tbl, row_id)
 );
+CREATE TABLE IF NOT EXISTS sync_backfill_checkpoints(
+  partition TEXT NOT NULL, name TEXT NOT NULL,
+  schema_version INTEGER NOT NULL,
+  state TEXT NOT NULL CHECK(state IN ('declared','backfilling','activated')),
+  watermark INTEGER NOT NULL DEFAULT 0,
+  owner_epoch INTEGER NOT NULL DEFAULT 0,
+  observed_rows INTEGER NOT NULL DEFAULT 0,
+  updated_at_ms INTEGER NOT NULL,
+  PRIMARY KEY(partition, name)
+);
+CREATE TABLE IF NOT EXISTS sync_writer_fence(
+  partition TEXT PRIMARY KEY,
+  required_writer_version INTEGER NOT NULL
+);
 `;
 /** Split the DDL into individual statements (D1 applies them one by one). */
 export function sqliteDdlStatements() {

package/dist/sqlite-segment-store.js

@@ -1,7 +1,7 @@
 /**
  * SQLite-backed segment store over the shared synchronous driver.
  */
-import { DEFAULT_SEGMENT_TTL_MS, segmentIdFor, } from './segment-store.js';
+import { DEFAULT_SEGMENT_TTL_MS, mergeSegmentRecord, publicationKey, publicationRecord, publicationsForRecord, segmentBytesEqual, segmentIdFor, selectSegmentPublication, } from './segment-store.js';
 import { SqliteAdapterRequiredError, } from './sqlite-driver.js';
 export class SqliteSegmentStore {
     db;
@@ -23,6 +23,33 @@ export class SqliteSegmentStore {
         byte_length INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,
         expires_at_ms INTEGER NOT NULL, bytes BLOB NOT NULL
       );
+    `);
+        // One row per scope digest a content address was published under (§5.1):
+        // identical bytes from two scopes share a `segment_id` and must both stay
+        // downloadable (§5.5).
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sync_segment_scopes(
+        segment_id TEXT NOT NULL, scope_digest TEXT NOT NULL,
+        PRIMARY KEY (segment_id, scope_digest)
+      );
+    `);
+        // One row per publication of a content address (§5.1): the same bytes
+        // under a different partition, epoch, table, or pin are distinct grants
+        // and must each stay downloadable. Rows written before this table existed
+        // materialize from the top-level record plus `sync_segment_scopes` on
+        // read, so an in-flight 0.21 object loses no publication.
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sync_segment_publications(
+        segment_id TEXT NOT NULL, pub_key TEXT NOT NULL,
+        partition TEXT NOT NULL, log_epoch TEXT NOT NULL,
+        tbl TEXT NOT NULL, schema_version INTEGER NOT NULL,
+        media_type TEXT NOT NULL, scope_digest TEXT NOT NULL,
+        as_of_commit_seq INTEGER NOT NULL, row_count INTEGER NOT NULL,
+        row_cursor TEXT, next_row_cursor TEXT,
+        byte_length INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,
+        expires_at_ms INTEGER NOT NULL,
+        PRIMARY KEY (segment_id, pub_key)
+      );
     `);
         const columns = this.db
             .query('PRAGMA table_info(sync_segments)')
@@ -30,23 +57,89 @@ export class SqliteSegmentStore {
         if (!columns.some((column) => column.name === 'log_epoch')) {
             this.db.exec("ALTER TABLE sync_segments ADD COLUMN log_epoch TEXT NOT NULL DEFAULT ''");
         }
+        // Backfill digests recorded before the side table existed, so an
+        // upgraded store keeps `find`/download working for cached segments.
+        this.db.exec(`INSERT OR IGNORE INTO sync_segment_scopes(segment_id, scope_digest)
+       SELECT segment_id, scope_digest FROM sync_segments`);
+    }
+    /** Every digest recorded for a content address, primary first. */
+    #scopeDigestsFor(segmentId, primary) {
+        const rows = this.db
+            .query('SELECT scope_digest FROM sync_segment_scopes WHERE segment_id=?')
+            .all(segmentId);
+        const digests = rows.map((row) => row.scope_digest);
+        return [primary, ...digests.filter((digest) => digest !== primary)];
+    }
+    /** Stored publications for a content address, oldest first. */
+    #publicationsFor(segmentId) {
+        const rows = this.db
+            .query('SELECT * FROM sync_segment_publications WHERE segment_id=? ORDER BY rowid')
+            .all(segmentId);
+        return rows.map((row) => ({
+            partition: row.partition,
+            logEpoch: row.log_epoch,
+            table: row.tbl,
+            schemaVersion: row.schema_version,
+            mediaType: row.media_type === 'sqlite' ? 'sqlite' : 'rows',
+            scopeDigest: row.scope_digest,
+            asOfCommitSeq: row.as_of_commit_seq,
+            rowCount: row.row_count,
+            rowCursor: row.row_cursor,
+            nextRowCursor: row.next_row_cursor,
+            byteLength: row.byte_length,
+            createdAtMs: row.created_at_ms,
+            expiresAtMs: row.expires_at_ms,
+        }));
     }
     async put(metadata, bytes, nowMs) {
         const segmentId = await segmentIdFor(bytes);
-        const record = {
-            ...metadata,
-            segmentId,
-            byteLength: bytes.length,
-            createdAtMs: nowMs,
-            expiresAtMs: nowMs + this.#ttlMs,
-        };
-        this.db
-            .query(`INSERT OR REPLACE INTO sync_segments(
-          segment_id, partition, log_epoch, tbl, schema_version, media_type,
-          scope_digest, as_of_commit_seq, row_count, row_cursor,
-          next_row_cursor, byte_length, created_at_ms, expires_at_ms, bytes
-        ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
-            .run(record.segmentId, record.partition, record.logEpoch, record.table, record.schemaVersion, record.mediaType, record.scopeDigest, record.asOfCommitSeq, record.rowCount, record.rowCursor, record.nextRowCursor, record.byteLength, record.createdAtMs, record.expiresAtMs, bytes);
+        const existing = await this.get(segmentId);
+        if (existing !== undefined && !segmentBytesEqual(existing.bytes, bytes)) {
+            throw new Error(`SqliteSegmentStore: content-address collision at ${segmentId} (§5.1)`);
+        }
+        const record = mergeSegmentRecord(existing?.record, metadata, segmentId, bytes.length, nowMs, this.#ttlMs);
+        // The bytes are proven identical to the stored ones, so replacing the
+        // row with the merged record (metadata, digest set, merged times) is the
+        // merge: the other digests live in `sync_segment_scopes` below. The
+        // publication set is rewritten from the merged record in one transaction
+        // so a crash cannot leave provenance half-applied.
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            this.db
+                .query(`INSERT OR REPLACE INTO sync_segments(
+            segment_id, partition, log_epoch, tbl, schema_version, media_type,
+            scope_digest, as_of_commit_seq, row_count, row_cursor,
+            next_row_cursor, byte_length, created_at_ms, expires_at_ms, bytes
+          ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+                .run(record.segmentId, record.partition, record.logEpoch, record.table, record.schemaVersion, record.mediaType, record.scopeDigest, record.asOfCommitSeq, record.rowCount, record.rowCursor, record.nextRowCursor, record.byteLength, record.createdAtMs, record.expiresAtMs, bytes);
+            // Rebuild the digest side table from the merged record so a pruned
+            // (expired) publication's digest disappears from the compatibility
+            // view instead of lingering as a stale scope row.
+            this.db
+                .query('DELETE FROM sync_segment_scopes WHERE segment_id=?')
+                .run(record.segmentId);
+            const insertScope = this.db.query(`INSERT OR IGNORE INTO sync_segment_scopes(segment_id, scope_digest)
+         VALUES (?,?)`);
+            for (const digest of record.scopeDigests) {
+                insertScope.run(record.segmentId, digest);
+            }
+            this.db
+                .query('DELETE FROM sync_segment_publications WHERE segment_id=?')
+                .run(record.segmentId);
+            const insertPublication = this.db.query(`INSERT INTO sync_segment_publications(
+           segment_id, pub_key, partition, log_epoch, tbl, schema_version,
+           media_type, scope_digest, as_of_commit_seq, row_count, row_cursor,
+           next_row_cursor, byte_length, created_at_ms, expires_at_ms
+         ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`);
+            for (const publication of record.publications) {
+                insertPublication.run(record.segmentId, publicationKey(publication), publication.partition, publication.logEpoch, publication.table, publication.schemaVersion, publication.mediaType, publication.scopeDigest, publication.asOfCommitSeq, publication.rowCount, publication.rowCursor, publication.nextRowCursor, publication.byteLength, publication.createdAtMs, publication.expiresAtMs);
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
         return record;
     }
     async get(segmentId) {
@@ -55,40 +148,59 @@ export class SqliteSegmentStore {
             .get(segmentId);
         if (row === null)
             return undefined;
+        const scopeDigests = this.#scopeDigestsFor(row.segment_id, row.scope_digest);
+        const top = {
+            segmentId: row.segment_id,
+            partition: row.partition,
+            logEpoch: row.log_epoch,
+            table: row.tbl,
+            schemaVersion: row.schema_version,
+            mediaType: row.media_type === 'sqlite' ? 'sqlite' : 'rows',
+            scopeDigest: row.scope_digest,
+            scopeDigests,
+            asOfCommitSeq: row.as_of_commit_seq,
+            rowCount: row.row_count,
+            rowCursor: row.row_cursor,
+            nextRowCursor: row.next_row_cursor,
+            byteLength: row.byte_length,
+            createdAtMs: row.created_at_ms,
+            expiresAtMs: row.expires_at_ms,
+        };
+        const stored = this.#publicationsFor(row.segment_id);
         return {
             record: {
-                segmentId: row.segment_id,
-                partition: row.partition,
-                logEpoch: row.log_epoch,
-                table: row.tbl,
-                schemaVersion: row.schema_version,
-                mediaType: row.media_type === 'sqlite' ? 'sqlite' : 'rows',
-                scopeDigest: row.scope_digest,
-                asOfCommitSeq: row.as_of_commit_seq,
-                rowCount: row.row_count,
-                rowCursor: row.row_cursor,
-                nextRowCursor: row.next_row_cursor,
-                byteLength: row.byte_length,
-                createdAtMs: row.created_at_ms,
-                expiresAtMs: row.expires_at_ms,
+                ...top,
+                publications: stored.length > 0 ? stored : publicationsForRecord(top),
             },
             bytes: new Uint8Array(row.bytes),
         };
     }
     async find(key, nowMs) {
-        const row = this.db
-            .query(`SELECT segment_id, row_count, next_row_cursor, byte_length,
-                created_at_ms, expires_at_ms
-         FROM sync_segments
+        // A publication row is the provenance index; a record written before the
+        // table existed falls back to the legacy top-level/scope join below.
+        const publication = this.db
+            .query(`SELECT segment_id FROM sync_segment_publications
          WHERE partition=? AND log_epoch=? AND tbl=? AND schema_version=? AND media_type=?
            AND scope_digest=? AND as_of_commit_seq=? AND row_cursor IS NULL
            AND expires_at_ms > ?
          LIMIT 1`)
             .get(key.partition, key.logEpoch, key.table, key.schemaVersion, key.mediaType, key.scopeDigest, key.asOfCommitSeq, nowMs);
-        if (row === null)
+        const legacy = this.db
+            .query(`SELECT s.segment_id
+         FROM sync_segments s
+         JOIN sync_segment_scopes sc ON sc.segment_id = s.segment_id
+         WHERE s.partition=? AND s.log_epoch=? AND s.tbl=? AND s.schema_version=? AND s.media_type=?
+           AND sc.scope_digest=? AND s.as_of_commit_seq=? AND s.row_cursor IS NULL
+           AND s.expires_at_ms > ?
+         LIMIT 1`)
+            .get(key.partition, key.logEpoch, key.table, key.schemaVersion, key.mediaType, key.scopeDigest, key.asOfCommitSeq, nowMs);
+        const segmentId = publication?.segment_id ?? legacy?.segment_id;
+        if (segmentId === undefined)
             return undefined;
-        return {
-            segmentId: row.segment_id,
+        const entry = await this.get(segmentId);
+        if (entry === undefined)
+            return undefined;
+        const match = selectSegmentPublication(entry.record, {
             partition: key.partition,
             logEpoch: key.logEpoch,
             table: key.table,
@@ -96,13 +208,12 @@ export class SqliteSegmentStore {
             mediaType: key.mediaType,
             scopeDigest: key.scopeDigest,
             asOfCommitSeq: key.asOfCommitSeq,
-            rowCount: row.row_count,
             rowCursor: null,
-            nextRowCursor: row.next_row_cursor,
-            byteLength: row.byte_length,
-            createdAtMs: row.created_at_ms,
-            expiresAtMs: row.expires_at_ms,
-        };
+            nowMs,
+        });
+        if (match === undefined)
+            return undefined;
+        return publicationRecord(entry.record, match);
     }
     async stats() {
         const row = this.db

package/dist/sqlite-storage.d.ts

@@ -1,14 +1,14 @@
 import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import type { CompiledSchema, CompiledTable } from './schema.js';
 import { type SqliteDatabase } from './sqlite-driver.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export declare class SqliteServerStorage implements ServerStorage {
     #private;
     readonly db: SqliteDatabase;
     constructor(db?: SqliteDatabase | string);
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name: string): CompiledTable;
-    ensureSchema(schema: CompiledSchema): Promise<void>;
+    ensureSchema(schema: CompiledSchema, checkpoints?: readonly CheckpointDeclaration[]): Promise<void>;
     touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
     rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
     listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
@@ -16,12 +16,20 @@ export declare class SqliteServerStorage implements ServerStorage {
     /** Internal: write a row + refresh its scope-index entries. */
     writeRow(partition: string, table: string, row: StoredRow): void;
     getMaxCommitSeq(partition: string): Promise<number>;
-    queryAuthoritative(partition: string, query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
+    queryAuthoritative(partition: string, query: AuthoritativeQueryRequest, checkpoints?: readonly CheckpointDeclaration[]): Promise<AuthoritativeQueryResult>;
     getPartitionLogEpoch(partition: string): Promise<string | undefined>;
     getHorizonSeq(partition: string): Promise<number>;
     setHorizonSeq(partition: string, seq: number): Promise<void>;
     pruneCommitsThrough(partition: string, query: CommitPruneQuery): Promise<CommitPruneResult>;
     getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
+    readServeGate(partition: string, runningSchemaVersion: number): Promise<ServeGate>;
+    readCheckpoints(partition: string): Promise<StoredCheckpoint[]>;
+    declareCheckpoint(partition: string, name: string, schemaVersion: number, nowMs: number): Promise<StoredCheckpoint>;
+    activateCheckpoint(partition: string, name: string, ownerEpoch: number, watermark: number, sources: readonly string[], nowMs: number): Promise<'activated' | 'stale' | 'unverifiable'>;
+    claimCheckpoint(partition: string, name: string, schemaVersion: number, nowMs: number): Promise<StoredCheckpoint>;
+    advanceCheckpoint(partition: string, name: string, ownerEpoch: number, watermark: number, observedRows: number, nowMs: number): Promise<boolean>;
+    sourceCoverageSeq(partition: string, tables: readonly string[]): Promise<number>;
+    hasSourceChangesAbove(partition: string, tables: readonly string[], seq: number): Promise<'clean' | 'changed' | 'unverifiable'>;
     getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
     getPushResult(partition: string, clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
     claimReactions(partition: string, query: ReactionClaimQuery): Promise<StoredReaction[]>;