@syncular/server 0.21.1 → 0.23.0

package/src/s3-segment-store.ts

@@ -6,12 +6,19 @@
  * Key layout (deterministic — every lookup is a GET/HEAD, never a LIST):
  *
  *   {keyPrefix}seg/sha256/{hex}
- *     The segment bytes, verbatim (the object body MUST be exactly the
- *     content-addressed bytes so presigned GETs serve them directly and
- *     the client's §5.1 hash check passes). The full `SegmentRecord`
- *     (minus bytes) rides along as object user metadata
- *     `x-amz-meta-syncular-record` = base64url(JSON), so `get` is a
- *     single GET.
+ *     The segment bytes, verbatim and immutable (the object body MUST be
+ *     exactly the content-addressed bytes so presigned GETs serve them
+ *     directly and the client's §5.1 hash check passes).
+ *
+ *   {keyPrefix}rec/sha256/{hex}.json
+ *     The `SegmentRecord` (§5.1). It is the one MUTABLE object of the two:
+ *     the scope-digest set is a union that every publication extends, so
+ *     the merge is a read-modify-write. Keeping the record in the body (not
+ *     in the bytes object's user metadata) is what makes that write
+ *     conditional — a body ETag changes when the union changes, while the
+ *     bytes ETag is a content hash and is identical for identical bytes. A
+ *     `412` re-reads and merges again, so no concurrent publication can drop
+ *     another one's digest. `get` therefore reads two objects.
  *
  *   {keyPrefix}find/{sha256Hex(canonical reuse key)}.json
  *     Whole-table reuse pointer (§5.3): written only when
@@ -21,9 +28,14 @@
  *     confirm the segment object itself still exists — lifecycle GC may
  *     remove objects independently of pointers).
  *
+ * Records written before the split kept the record in the bytes object's
+ * user metadata `x-amz-meta-syncular-record`; `get` still reads that shape
+ * and the next `put` materializes the record object from it, so an upgrade
+ * loses no cache entry.
+ *
  * TTL mapping: expiry is **store-side and authoritative** — `expiresAtMs`
- * (put-time + `ttlMs`, default 24 h) is recorded in the object metadata
- * and the pointer; `get` returns expired records so §5.5 can answer
+ * (put-time + `ttlMs`, default 24 h) is recorded in the record and the
+ * pointer; `get` returns expired records so §5.5 can answer
  * `sync.segment_expired`, and `find` filters them out itself. S3 lifecycle
  * expiration is garbage collection only: configure it comfortably ABOVE
  * `ttlMs` (e.g. 2 days for the 24 h default) so clients normally see the
@@ -33,11 +45,19 @@
 import type {
   SegmentFindKey,
   SegmentMetadata,
+  SegmentPublication,
   SegmentRecord,
   SegmentStore,
   SegmentStoreStats,
 } from './segment-store';
-import { segmentIdFor } from './segment-store';
+import {
+  mergeSegmentRecord,
+  publicationRecord,
+  publicationsForRecord,
+  segmentBytesEqual,
+  segmentIdFor,
+  selectSegmentPublication,
+} from './segment-store';
 import type { DelegatedPresignConfig, SegmentUrlIssue } from './signed-url';
 import {
   EMPTY_PAYLOAD_SHA256,
@@ -89,7 +109,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;
 
 interface StatsAccumulator {
   count: number;
@@ -113,19 +133,8 @@ function parseStatsJson(json: string): StatsAccumulator {
 }
 
 // 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: string): string {
-  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: string): string {
   const binary = atob(value.replaceAll('-', '+').replaceAll('_', '/'));
   const bytes = new Uint8Array(binary.length);
@@ -141,6 +150,60 @@ function isMediaType(value: unknown): value is 'rows' | 'sqlite' {
   return value === 'rows' || value === 'sqlite';
 }
 
+/** One publication inside a stored record (or a legacy materialized one). */
+function parsePublication(value: unknown, source: string): SegmentPublication {
+  if (typeof value !== 'object' || value === null) {
+    throw new Error(`S3SegmentStore: corrupt publication in ${source}`);
+  }
+  const p = value as Record<string, unknown>;
+  const strings = ['partition', 'logEpoch', 'table', 'scopeDigest'] as const;
+  const numbers = [
+    'schemaVersion',
+    'asOfCommitSeq',
+    'rowCount',
+    'byteLength',
+    'createdAtMs',
+    'expiresAtMs',
+  ] as const;
+  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: unknown): v is string | null =>
+    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 as string,
+    logEpoch: p.logEpoch as string,
+    table: p.table as string,
+    schemaVersion: p.schemaVersion as number,
+    mediaType: p.mediaType,
+    scopeDigest: p.scopeDigest as string,
+    asOfCommitSeq: p.asOfCommitSeq as number,
+    rowCount: p.rowCount as number,
+    rowCursor: p.rowCursor,
+    nextRowCursor: p.nextRowCursor,
+    byteLength: p.byteLength as number,
+    createdAtMs: p.createdAtMs as number,
+    expiresAtMs: p.expiresAtMs as number,
+  };
+}
+
 function parseRecordJson(json: string, source: string): SegmentRecord {
   let parsed: unknown;
   try {
@@ -185,14 +248,36 @@ function parseRecordJson(json: string, source: string): SegmentRecord {
   if (!cursorOk(r.rowCursor) || !cursorOk(r.nextRowCursor)) {
     throw new Error(`S3SegmentStore: bad record cursor in ${source}`);
   }
-  return {
+  const scopeDigest = r.scopeDigest as string;
+  // 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 as string,
     partition: r.partition as string,
     logEpoch: r.logEpoch as string,
     table: r.table as string,
     schemaVersion: r.schemaVersion as number,
     mediaType: r.mediaType,
-    scopeDigest: r.scopeDigest as string,
+    scopeDigest,
+    scopeDigests: [
+      scopeDigest,
+      ...((rawDigests ?? []) as string[]).filter(
+        (digest) => digest !== scopeDigest,
+      ),
+    ],
     asOfCommitSeq: r.asOfCommitSeq as number,
     rowCount: r.rowCount as number,
     rowCursor: r.rowCursor,
@@ -201,6 +286,16 @@ function parseRecordJson(json: string, source: string): SegmentRecord {
     createdAtMs: r.createdAtMs as number,
     expiresAtMs: r.expiresAtMs as number,
   };
+  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 implements SegmentStore {
@@ -227,6 +322,11 @@ export class S3SegmentStore implements SegmentStore {
     return `${this.#prefix}seg/${segmentId.replace(':', '/')}`;
   }
 
+  /** `{keyPrefix}rec/sha256/{hex}.json` — the §5.1 record (§5.1 union). */
+  #recordKeyFor(segmentId: string): string {
+    return `${this.#prefix}rec/${segmentId.replace(':', '/')}.json`;
+  }
+
   async #findKeyFor(key: SegmentFindKey): Promise<string> {
     const canonical = JSON.stringify([
       key.partition,
@@ -255,6 +355,8 @@ export class S3SegmentStore implements SegmentStore {
     options?: {
       readonly body?: Uint8Array;
       readonly headers?: Readonly<Record<string, string>>;
+      /** Return a `412` response instead of throwing (conditional writes). */
+      readonly allow412?: boolean;
     },
   ): Promise<Response | undefined> {
     const url = this.#urlFor(key);
@@ -278,6 +380,7 @@ export class S3SegmentStore implements SegmentStore {
       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(
@@ -349,7 +452,7 @@ export class S3SegmentStore implements SegmentStore {
    * that already stored the bytes.
    */
   async #bumpStats(delta: StatsAccumulator): Promise<void> {
-    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: StatsAccumulator = {
         count: stats.count + delta.count,
@@ -359,7 +462,7 @@ export class S3SegmentStore implements SegmentStore {
       };
       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.
   }
 
@@ -369,65 +472,151 @@ export class S3SegmentStore implements SegmentStore {
     nowMs: number,
   ): Promise<SegmentRecord> {
     const segmentId = await segmentIdFor(bytes);
-    const record: SegmentRecord = {
-      ...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: Record<string, string> =
+        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: string, bytes: Uint8Array): Promise<void> {
+    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 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)`,
       );
-      await pointer?.arrayBuffer();
     }
-    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: string,
+  ): Promise<{ record: SegmentRecord; etag: string | undefined } | undefined> {
+    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: string,
   ): Promise<{ record: SegmentRecord; bytes: Uint8Array } | undefined> {
     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(
@@ -437,19 +626,21 @@ export class S3SegmentStore implements SegmentStore {
     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) return undefined;
+    // 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',
@@ -457,7 +648,7 @@ export class S3SegmentStore implements SegmentStore {
     );
     if (head === undefined) return undefined;
     await head.arrayBuffer();
-    return record;
+    return publicationRecord(record, publication);
   }
 
   /**

package/src/schema.ts

@@ -228,6 +228,21 @@ export function compileSchema(schema: ServerSchema): CompiledSchema {
         `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/src/segment-download.ts

@@ -4,8 +4,9 @@
  * A segment reference is not a bearer capability: every download re-runs
  * `resolveScopes`, recomputes the effective scopes from the supplied
  * `X-Syncular-Scopes` requested map, recomputes the scope digest, and
- * compares it with the segment's stored digest. Mismatch, revoked status,
- * or resolution failure ⇒ `sync.forbidden`.
+ * requires that digest to be one of the digests the stored content was
+ * published under (§5.5). Mismatch, revoked status, or resolution failure
+ * ⇒ `sync.forbidden`.
  */
 import type { ScopeMap } from '@syncular/core';
 import type { SyncRequestContext } from './context';
@@ -18,7 +19,7 @@ import { SyncError, syncError } from './errors';
 import { emitEvent } from './events';
 import { compileSchema } from './schema';
 import { computeEffective, type ResolvedScopes, scopeDigest } from './scopes';
-import type { SegmentRecord } from './segment-store';
+import { publicationRecord, type SegmentRecord } from './segment-store';
 
 export interface SegmentDownloadRequest {
   readonly segmentId: string;
@@ -102,34 +103,22 @@ async function downloadSegment(
 ): Promise<SegmentDownloadResult> {
   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)',
-    );
+  // 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 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');
-  }
   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: ResolvedScopes;
   try {
@@ -160,12 +149,74 @@ async function downloadSegment(
     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]!;
+
+  // RFC 0007: a descriptor minted before this partition declared a backfill
+  // checkpoint is not a complete window once the projection becomes
+  // checkpointed. SPEC §9 mints segments per schema version, so refuse and
+  // let the client re-pull for a fresh descriptor.
+  const checkpoints = await ctx.storage.readCheckpoints(ctx.partition);
+  if (
+    checkpoints.some(
+      (checkpoint) => checkpoint.schemaVersion > publication.schemaVersion,
+    )
+  ) {
+    throw syncError(
+      'sync.segment_expired',
+      'segment predates the partition backfill checkpoint — re-pull (§5.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',