@syncular/server 0.21.0 → 0.22.0

package/dist/s3-segment-store.js

@@ -1,4 +1,4 @@
-import { segmentIdFor } from './segment-store.js';
+import { mergeSegmentRecord, publicationRecord, publicationsForRecord, segmentBytesEqual, segmentIdFor, selectSegmentPublication, } from './segment-store.js';
 import { EMPTY_PAYLOAD_SHA256, presignUrl, sha256Hex, signRequest, } from './sigv4.js';
 const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
 const SEGMENT_ID_PATTERN = /^sha256:[0-9a-f]{64}$/;
@@ -19,7 +19,7 @@ const RECORD_META_HEADER = 'x-amz-meta-syncular-record';
  * S3 stats `approximate: true`. They are a health gauge, not an invoice.
  */
 const STATS_KEY_SUFFIX = 'stats/segments.json';
-const STATS_CAS_ATTEMPTS = 16;
+const CAS_ATTEMPTS = 16;
 function emptyStats() {
     return { count: 0, bytes: 0, rowsSegments: 0, sqliteSegments: 0 };
 }
@@ -33,18 +33,8 @@ function parseStatsJson(json) {
     };
 }
 // Runtime-neutral base64url: `Buffer` is not present on
-// Cloudflare Workers without `nodejs_compat`, so the object-metadata record
-// header is (de)coded with `btoa`/`atob`, available in every runtime.
-function utf8ToBase64url(text) {
-    let binary = '';
-    for (const byte of new TextEncoder().encode(text)) {
-        binary += String.fromCharCode(byte);
-    }
-    return btoa(binary)
-        .replaceAll('+', '-')
-        .replaceAll('/', '_')
-        .replace(/=+$/, '');
-}
+// Cloudflare Workers without `nodejs_compat`, so a legacy object-metadata
+// record header is decoded with `atob`, available in every runtime.
 function base64urlToUtf8(value) {
     const binary = atob(value.replaceAll('-', '+').replaceAll('_', '/'));
     const bytes = new Uint8Array(binary.length);
@@ -58,6 +48,54 @@ function recordToJson(record) {
 function isMediaType(value) {
     return value === 'rows' || value === 'sqlite';
 }
+/** One publication inside a stored record (or a legacy materialized one). */
+function parsePublication(value, source) {
+    if (typeof value !== 'object' || value === null) {
+        throw new Error(`S3SegmentStore: corrupt publication in ${source}`);
+    }
+    const p = value;
+    const strings = ['partition', 'logEpoch', 'table', 'scopeDigest'];
+    const numbers = [
+        'schemaVersion',
+        'asOfCommitSeq',
+        'rowCount',
+        'byteLength',
+        'createdAtMs',
+        'expiresAtMs',
+    ];
+    for (const field of strings) {
+        if (typeof p[field] !== 'string') {
+            throw new Error(`S3SegmentStore: bad publication field ${field} in ${source}`);
+        }
+    }
+    for (const field of numbers) {
+        if (typeof p[field] !== 'number') {
+            throw new Error(`S3SegmentStore: bad publication field ${field} in ${source}`);
+        }
+    }
+    if (!isMediaType(p.mediaType)) {
+        throw new Error(`S3SegmentStore: bad publication mediaType in ${source}`);
+    }
+    const cursorOk = (v) => v === null || typeof v === 'string';
+    if (!cursorOk(p.rowCursor) || !cursorOk(p.nextRowCursor)) {
+        throw new Error(`S3SegmentStore: bad publication cursor in ${source}`);
+    }
+    return {
+        partition: p.partition,
+        logEpoch: p.logEpoch,
+        table: p.table,
+        schemaVersion: p.schemaVersion,
+        mediaType: p.mediaType,
+        scopeDigest: p.scopeDigest,
+        asOfCommitSeq: p.asOfCommitSeq,
+        rowCount: p.rowCount,
+        rowCursor: p.rowCursor,
+        nextRowCursor: p.nextRowCursor,
+        byteLength: p.byteLength,
+        createdAtMs: p.createdAtMs,
+        expiresAtMs: p.expiresAtMs,
+    };
+}
 function parseRecordJson(json, source) {
     let parsed;
     try {
@@ -102,14 +140,32 @@ function parseRecordJson(json, source) {
     if (!cursorOk(r.rowCursor) || !cursorOk(r.nextRowCursor)) {
         throw new Error(`S3SegmentStore: bad record cursor in ${source}`);
     }
-    return {
+    const scopeDigest = r.scopeDigest;
+    // Records written before §5.1 recorded the digest set carry only the
+    // primary digest; the object is a cache entry with a TTL, so reading it
+    // back as a one-digest record is correct, not a degraded path.
+    const rawDigests = r.scopeDigests;
+    if (rawDigests !== undefined &&
+        (!Array.isArray(rawDigests) ||
+            rawDigests.some((digest) => typeof digest !== 'string'))) {
+        throw new Error(`S3SegmentStore: bad record scopeDigests in ${source}`);
+    }
+    const rawPublications = r.publications;
+    if (rawPublications !== undefined && !Array.isArray(rawPublications)) {
+        throw new Error(`S3SegmentStore: bad record publications in ${source}`);
+    }
+    const top = {
         segmentId: r.segmentId,
         partition: r.partition,
         logEpoch: r.logEpoch,
         table: r.table,
         schemaVersion: r.schemaVersion,
         mediaType: r.mediaType,
-        scopeDigest: r.scopeDigest,
+        scopeDigest,
+        scopeDigests: [
+            scopeDigest,
+            ...(rawDigests ?? []).filter((digest) => digest !== scopeDigest),
+        ],
         asOfCommitSeq: r.asOfCommitSeq,
         rowCount: r.rowCount,
         rowCursor: r.rowCursor,
@@ -118,6 +174,15 @@ function parseRecordJson(json, source) {
         createdAtMs: r.createdAtMs,
         expiresAtMs: r.expiresAtMs,
     };
+    return {
+        ...top,
+        // A record from before per-publication provenance, or a legacy record
+        // whose union came from object metadata, materializes its publications
+        // from the merged top-level context — the old single-record read.
+        publications: rawPublications === undefined
+            ? publicationsForRecord(top)
+            : rawPublications.map((value) => parsePublication(value, source)),
+    };
 }
 export class S3SegmentStore {
     #config;
@@ -140,6 +205,10 @@ export class S3SegmentStore {
     objectKeyFor(segmentId) {
         return `${this.#prefix}seg/${segmentId.replace(':', '/')}`;
     }
+    /** `{keyPrefix}rec/sha256/{hex}.json` — the §5.1 record (§5.1 union). */
+    #recordKeyFor(segmentId) {
+        return `${this.#prefix}rec/${segmentId.replace(':', '/')}.json`;
+    }
     async #findKeyFor(key) {
         const canonical = JSON.stringify([
             key.partition,
@@ -180,6 +249,8 @@ export class S3SegmentStore {
             await response.arrayBuffer();
             return undefined;
         }
+        if (options?.allow412 === true && response.status === 412)
+            return response;
         if (!response.ok) {
             const detail = (await response.text()).slice(0, 300);
             throw new Error(`S3SegmentStore: ${method} ${key} failed with ${response.status}: ${detail}`);
@@ -237,7 +308,7 @@ export class S3SegmentStore {
      * that already stored the bytes.
      */
     async #bumpStats(delta) {
-        for (let attempt = 0; attempt < STATS_CAS_ATTEMPTS; attempt++) {
+        for (let attempt = 0; attempt < CAS_ATTEMPTS; attempt++) {
             const { stats, etag } = await this.#readStats();
             const next = {
                 count: stats.count + delta.count,
@@ -248,87 +319,164 @@ export class S3SegmentStore {
             if (await this.#writeStatsCas(next, etag))
                 return;
         }
-        // Lost the CAS race `STATS_CAS_ATTEMPTS` times running — leave the
+        // Lost the CAS race `CAS_ATTEMPTS` times running — leave the
         // counters as-is. `stats()` stays APPROXIMATE by contract.
     }
     async put(metadata, bytes, nowMs) {
         const segmentId = await segmentIdFor(bytes);
-        const record = {
-            ...metadata,
-            segmentId,
-            byteLength: bytes.length,
-            createdAtMs: nowMs,
-            expiresAtMs: nowMs + this.#ttlMs,
-        };
-        const recordJson = recordToJson(record);
-        // Detect an idempotent re-put (same content-address ⇒ same key) so the
-        // stats accumulator counts each distinct segment once, not once per PUT.
-        const objectKey = this.objectKeyFor(segmentId);
-        const preexisting = await this.#request('HEAD', objectKey);
-        await preexisting?.arrayBuffer();
-        const isNew = preexisting === undefined;
-        const response = await this.#request('PUT', objectKey, {
+        await this.#putBytes(segmentId, bytes);
+        for (let attempt = 0; attempt < CAS_ATTEMPTS; attempt++) {
+            // The id IS the content address, so an existing record means a second
+            // scope published the same bytes: read it back and merge the digest set
+            // (§5.1).
+            const preexisting = await this.#readRecord(segmentId);
+            const record = mergeSegmentRecord(preexisting?.record, metadata, segmentId, bytes.length, nowMs, this.#ttlMs);
+            const recordJson = recordToJson(record);
+            // The digest set is monotone (§5.1) and this is a read-modify-write: a
+            // concurrent publisher of the same bytes computed its own union from the
+            // same pre-state, so an unconditional PUT would drop one of the digests
+            // and make that scope's download `sync.forbidden`. The write is
+            // conditional on the record body that was read — the record ETag is the
+            // body hash, so it changes whenever the union does — and a `412`
+            // re-reads and merges again. In-process dedupe cannot cover this: two
+            // scopes whose rows are byte-identical are two builds, and two server
+            // instances share one bucket.
+            const conditional = preexisting?.etag === undefined
+                ? { 'if-none-match': '*' }
+                : { 'if-match': preexisting.etag };
+            const response = await this.#request('PUT', this.#recordKeyFor(segmentId), {
+                body: new TextEncoder().encode(recordJson),
+                headers: { 'content-type': 'application/json', ...conditional },
+                allow412: true,
+            });
+            if (response !== undefined && response.status === 412) {
+                await response.arrayBuffer();
+                continue;
+            }
+            await response?.arrayBuffer();
+            if (preexisting === undefined) {
+                await this.#bumpStats({
+                    count: 1,
+                    bytes: bytes.length,
+                    rowsSegments: metadata.mediaType === 'rows' ? 1 : 0,
+                    sqliteSegments: metadata.mediaType === 'sqlite' ? 1 : 0,
+                });
+            }
+            if (metadata.rowCursor === null) {
+                const pointer = await this.#request('PUT', await this.#findKeyFor(metadata), {
+                    body: new TextEncoder().encode(recordJson),
+                    headers: { 'content-type': 'application/json' },
+                });
+                await pointer?.arrayBuffer();
+            }
+            return record;
+        }
+        throw new Error(`S3SegmentStore: ${CAS_ATTEMPTS} conditional writes in a row lost the race for ${segmentId} — the stored digest set would have dropped a scope`);
+    }
+    /**
+     * Write the immutable bytes object. Create-only, so a second publisher of
+     * identical bytes is a no-op and a second publisher of DIFFERENT bytes under
+     * the same content address is the hash collision §5.1 requires to fail
+     * loudly instead of overwriting.
+     */
+    async #putBytes(segmentId, bytes) {
+        const key = this.objectKeyFor(segmentId);
+        const response = await this.#request('PUT', key, {
             body: bytes,
             headers: {
                 'content-type': 'application/octet-stream',
-                [RECORD_META_HEADER]: utf8ToBase64url(recordJson),
+                'if-none-match': '*',
             },
+            allow412: true,
         });
-        await response?.arrayBuffer();
-        if (isNew) {
-            await this.#bumpStats({
-                count: 1,
-                bytes: bytes.length,
-                rowsSegments: metadata.mediaType === 'rows' ? 1 : 0,
-                sqliteSegments: metadata.mediaType === 'sqlite' ? 1 : 0,
-            });
+        if (response === undefined || response.status !== 412) {
+            await response?.arrayBuffer();
+            return;
         }
-        if (metadata.rowCursor === null) {
-            const pointer = await this.#request('PUT', await this.#findKeyFor(metadata), {
-                body: new TextEncoder().encode(recordJson),
-                headers: { 'content-type': 'application/json' },
-            });
-            await pointer?.arrayBuffer();
+        await response.arrayBuffer();
+        const current = await this.#request('GET', key);
+        if (current === undefined)
+            return;
+        const stored = new Uint8Array(await current.arrayBuffer());
+        if (!segmentBytesEqual(stored, bytes)) {
+            throw new Error(`S3SegmentStore: content-address collision at ${segmentId} (§5.1)`);
         }
-        return record;
+    }
+    /**
+     * Read the record object plus the ETag of the body that was read, so the
+     * union write can be made conditional on exactly that pre-state (§5.1).
+     *
+     * A record written before the record/bytes split rides in the bytes object's
+     * user metadata; it is read here and its union is materialized into a record
+     * object by the next `put`. That shape carries no usable ETag for the union
+     * (the bytes ETag is a content hash), which is exactly why it was replaced.
+     * A bytes object with neither a record object nor the legacy metadata is an
+     * entry whose record is missing — a cache miss, not corruption, so `get`
+     * reports it as absent and the client re-pulls.
+     */
+    async #readRecord(segmentId) {
+        if (!SEGMENT_ID_PATTERN.test(segmentId))
+            return undefined;
+        const response = await this.#request('GET', this.#recordKeyFor(segmentId));
+        if (response !== undefined) {
+            return {
+                record: parseRecordJson(await response.text(), 'segment record'),
+                etag: response.headers.get('etag') ?? undefined,
+            };
+        }
+        const legacy = await this.#request('GET', this.objectKeyFor(segmentId));
+        if (legacy === undefined)
+            return undefined;
+        const meta = legacy.headers.get(RECORD_META_HEADER);
+        await legacy.arrayBuffer();
+        if (meta === null)
+            return undefined;
+        return {
+            record: parseRecordJson(base64urlToUtf8(meta), segmentId),
+            etag: undefined,
+        };
     }
     async get(segmentId) {
         if (!SEGMENT_ID_PATTERN.test(segmentId))
             return undefined;
+        const record = await this.#readRecord(segmentId);
+        if (record === undefined)
+            return undefined;
         const response = await this.#request('GET', this.objectKeyFor(segmentId));
         if (response === undefined)
             return undefined;
-        const bytes = new Uint8Array(await response.arrayBuffer());
-        const meta = response.headers.get(RECORD_META_HEADER);
-        if (meta === null) {
-            throw new Error(`S3SegmentStore: object for ${segmentId} lacks ${RECORD_META_HEADER}`);
-        }
-        const record = parseRecordJson(base64urlToUtf8(meta), segmentId);
-        return { record, bytes };
+        return {
+            record: record.record,
+            bytes: new Uint8Array(await response.arrayBuffer()),
+        };
     }
     async find(key, nowMs) {
         const response = await this.#request('GET', await this.#findKeyFor(key));
         if (response === undefined)
             return undefined;
         const record = parseRecordJson(await response.text(), 'reuse pointer');
-        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) {
-            return undefined;
-        }
-        if (record.expiresAtMs <= nowMs)
+        // The pointer is keyed by the full context, but the record body is the
+        // whole merged entry: select the publication the key names, never the
+        // top-level fields or the digest union (§5.1).
+        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 undefined;
         // Lifecycle GC may have removed the object while the pointer survived.
         const head = await this.#request('HEAD', this.objectKeyFor(record.segmentId));
         if (head === undefined)
             return undefined;
         await head.arrayBuffer();
-        return record;
+        return publicationRecord(record, publication);
     }
     /**
      * Store-wide counters from the pointer-object accumulator (never a LIST).

package/dist/schema.js

@@ -72,6 +72,17 @@ export function compileSchema(schema) {
         if (primaryKeyIndex === undefined) {
             throw new Error(`table ${table.name}: primary key ${JSON.stringify(table.primaryKey)} is not a column`);
         }
+        // §2.4 primary-key eligibility: a primary key MUST render to a `rowId`
+        // string every implementation produces identically and local storage
+        // resolves without deferring to a SQLite build.
+        const primaryKeyColumn = table.columns[primaryKeyIndex];
+        if (primaryKeyColumn !== undefined &&
+            primaryKeyColumn.type !== 'string' &&
+            primaryKeyColumn.type !== 'integer' &&
+            primaryKeyColumn.type !== 'boolean' &&
+            primaryKeyColumn.type !== 'json') {
+            throw new Error(`table ${table.name}: primary key ${JSON.stringify(table.primaryKey)} has an ineligible column type (§2.4); a primary key must be string, integer, boolean, or json`);
+        }
         if (table.scopes.length === 0) {
             throw new Error(`table ${table.name}: every synced table declares at least one scope pattern (§3.1)`);
         }

package/dist/segment-download.d.ts

@@ -1,5 +1,5 @@
 import type { SyncRequestContext } from './context.js';
-import type { SegmentRecord } from './segment-store.js';
+import { type SegmentRecord } from './segment-store.js';
 export interface SegmentDownloadRequest {
     readonly segmentId: string;
     /** The `X-Syncular-Scopes` header: canonical JSON of the requested map. */

package/dist/segment-download.js

@@ -3,6 +3,7 @@ import { SyncError, syncError } from './errors.js';
 import { emitEvent } from './events.js';
 import { compileSchema } from './schema.js';
 import { computeEffective, scopeDigest } from './scopes.js';
+import { publicationRecord } from './segment-store.js';
 function parseScopesHeader(header) {
     let parsed;
     try {
@@ -62,25 +63,18 @@ export async function handleSegmentDownload(ctx, request) {
 async function downloadSegment(ctx, request) {
     const registry = await touchAuthenticatedPartition(ctx);
     const entry = await ctx.segments.get(request.segmentId);
-    if (entry === undefined ||
-        entry.record.partition !== ctx.partition ||
-        entry.record.logEpoch !== registry.logEpoch) {
+    if (entry === undefined) {
         throw syncError('sync.not_found', 'unknown segment (§5.5)');
     }
-    if (entry.record.expiresAtMs <= clockOf(ctx)()) {
-        throw syncError('sync.segment_expired', 'segment TTL elapsed — re-pull to mint fresh descriptors (§5.1)');
-    }
-    const schema = compileSchema(ctx.schema);
-    const table = schema.tables.get(entry.record.table);
-    if (table === undefined) {
-        throw syncError('sync.not_found', 'segment table no longer served');
+    // Select the caller's own publication context. A publication under a
+    // different partition or a stale log epoch is not this caller's grant, and
+    // the entry's existence must not leak across that boundary (§5.5).
+    const inContext = entry.record.publications.filter((publication) => publication.partition === ctx.partition &&
+        publication.logEpoch === registry.logEpoch);
+    if (inContext.length === 0) {
+        throw syncError('sync.not_found', 'unknown segment (§5.5)');
     }
     const requested = parseScopesHeader(request.scopesHeader);
-    for (const [key, values] of Object.entries(requested)) {
-        if (!table.declaredVariables.has(key) || values.includes('*')) {
-            throw syncError('sync.invalid_subscription', 'invalid requested scopes (§3.2)');
-        }
-    }
     let resolved;
     try {
         const allowed = await ctx.resolveScopes({
@@ -111,11 +105,42 @@ async function downloadSegment(ctx, request) {
         throw syncError('sync.forbidden', 'segment scopes not held (§5.5)');
     }
     const digest = await scopeDigest(outcome.effective);
-    if (digest !== entry.record.scopeDigest) {
+    // The digest is the grant, but only inside the caller's partition and live
+    // epoch: identical bytes published elsewhere never authorize this caller.
+    const forDigest = inContext.filter((publication) => publication.scopeDigest === digest);
+    if (forDigest.length === 0) {
         throw syncError('sync.forbidden', 'scope digest mismatch (§3.5, §5.5)');
     }
+    // TTL is per publication: an unrelated refresh of another publication must
+    // not extend this grant, and an expired old pin must not shadow a live one.
+    const now = clockOf(ctx)();
+    const live = forDigest.filter((publication) => publication.expiresAtMs > now);
+    if (live.length === 0) {
+        throw syncError('sync.segment_expired', 'segment TTL elapsed — re-pull to mint fresh descriptors (§5.1)');
+    }
+    // Choose among the live candidates that the compiled schema serves and that
+    // declare every requested scope. A malformed or custom record whose newer
+    // publication names another table must not fail the download while an
+    // earlier valid publication of the same bytes exists.
+    const schema = compileSchema(ctx.schema);
+    const candidates = live.filter((publication) => {
+        const table = schema.tables.get(publication.table);
+        return (table !== undefined &&
+            Object.entries(requested).every(([key, values]) => table.declaredVariables.has(key) && !values.includes('*')));
+    });
+    if (candidates.length === 0) {
+        const served = live.some((publication) => schema.tables.has(publication.table));
+        if (!served) {
+            throw syncError('sync.not_found', 'segment table no longer served');
+        }
+        throw syncError('sync.invalid_subscription', 'invalid requested scopes (§3.2)');
+    }
+    const publication = candidates[candidates.length - 1];
     return {
-        record: entry.record,
+        // The returned record is projected onto the selected publication, so its
+        // `scopeDigests`/`publications` compatibility view cannot union a grant
+        // from another partition (§5.1).
+        record: publicationRecord(entry.record, publication),
         bytes: entry.bytes,
         headers: {
             'Content-Type': 'application/octet-stream',

package/dist/segment-store.d.ts

@@ -12,12 +12,90 @@ export interface SegmentMetadata {
     readonly rowCursor: string | null;
     readonly nextRowCursor: string | null;
 }
+/**
+ * One publication of a content address (§5.1): the full descriptor context
+ * that authorized the bytes plus that publication's own cache lifetime.
+ * Identical bytes have one content address, so one stored entry carries one
+ * publication per distinct (partition, logEpoch, table, schemaVersion,
+ * mediaType, scopeDigest, asOfCommitSeq, cursors) context it was published
+ * under. Authorization selects a matching publication; it never unions
+ * digests across a different partition or epoch.
+ */
+export interface SegmentPublication extends SegmentMetadata {
+    readonly byteLength: number;
+    readonly createdAtMs: number;
+    readonly expiresAtMs: number;
+}
 export interface SegmentRecord extends SegmentMetadata {
     readonly segmentId: string;
+    /**
+     * Every scope digest this content was published under (§3.5), primary
+     * first. A compatibility view over `publications`; download and `find`
+     * authorize on a matching publication, not on this union.
+     */
+    readonly scopeDigests: readonly string[];
+    /** Every publication of this content address, oldest first (§5.1). */
+    readonly publications: readonly SegmentPublication[];
     readonly byteLength: number;
     readonly createdAtMs: number;
     readonly expiresAtMs: number;
 }
+/** Canonical identity of one publication; two equal keys are one grant. */
+export declare function publicationKey(metadata: SegmentMetadata): string;
+/**
+ * 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 declare function publicationsForRecord(record: SegmentMetadata & {
+    readonly scopeDigests: readonly string[];
+    readonly byteLength: number;
+    readonly createdAtMs: number;
+    readonly expiresAtMs: number;
+}): SegmentPublication[];
+/**
+ * The newest publication matching a context, or undefined (§5.5). Optional
+ * `nowMs` skips publications whose own TTL has elapsed, so an expired
+ * `asOf`/schema publication never shadows a newer live one.
+ */
+export interface SegmentPublicationSelector {
+    readonly partition: string;
+    readonly logEpoch: string;
+    readonly scopeDigest: string;
+    readonly table?: string;
+    readonly schemaVersion?: number;
+    readonly mediaType?: 'rows' | 'sqlite';
+    readonly asOfCommitSeq?: number;
+    readonly rowCursor?: string | null;
+    readonly nowMs?: number;
+}
+export declare function selectSegmentPublication(record: SegmentRecord, context: SegmentPublicationSelector): SegmentPublication | 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 declare function publicationRecord(record: SegmentRecord, publication: SegmentPublication): SegmentRecord;
+/** Byte equality for the content-address collision check (§5.1). */
+export declare function segmentBytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * 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 declare function mergeSegmentRecord(existing: SegmentRecord | undefined, metadata: SegmentMetadata, segmentId: string, byteLength: number, nowMs: number, ttlMs: number): SegmentRecord;
 /**
  * The §5.3 reuse key: sqlite images are not byte-deterministic, so
  * cross-client dedup is a metadata lookup, not hash convergence — one
@@ -63,6 +141,14 @@ export interface SegmentStore {
      * Unexpired record for the §5.3 reuse key (whole-table segments only:
      * `rowCursor` null), or undefined. Servers MUST reuse instead of
      * rebuilding sqlite images while one exists (§5.3).
+     *
+     * The digest matches when it is one of the record's `scopeDigests`
+     * (§5.1). That cannot hand a sqlite image to the wrong digest: a sqlite
+     * image embeds its `scopeDigest` in its bytes, and a merge requires byte
+     * equality, so two images published under different digests are never
+     * byte-identical and never share one entry. Only rows segments merge
+     * across digests, and their bytes carry no digest for a reader to compare
+     * against the descriptor.
      */
     find(key: SegmentFindKey, nowMs: number): Promise<SegmentRecord | undefined>;
     /** Admin/console counters: ADDITIVE, optional. */