@syncular/server 0.32.0 → 0.33.0

package/dist/s3-segment-store.d.ts

@@ -1,48 +1,15 @@
 /**
  * S3-compatible segment store (SPEC.md §5.1 cache semantics, §5.4
- * delegated presign) — AWS S3, Cloudflare R2, MinIO. Zero dependencies:
- * hand-rolled SigV4 over `fetch` (sigv4.ts).
+ * delegated presign) — AWS S3, Cloudflare R2's S3 endpoint, MinIO. Zero
+ * dependencies: hand-rolled SigV4 over `fetch` (sigv4.ts).
  *
- * Key layout (deterministic — every lookup is a GET/HEAD, never a LIST):
- *
- *   {keyPrefix}seg/sha256/{hex}
- *     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
- *     `rowCursor === null`, body = the record JSON. The reuse key is the
- *     canonical JSON array `[partition, table, schemaVersion, mediaType,
- *     scopeDigest, asOfCommitSeq]`, so `find` is one GET (plus a HEAD to
- *     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 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
- * precise, retryable `sync.segment_expired` and hit `sync.not_found` only
- * long after. Never set lifecycle below `ttlMs`.
+ * The store logic (key layout, record CAS, reuse pointers, stats
+ * accumulator) is `BucketSegmentStore`, shared with `R2SegmentStore` in
+ * `@syncular/server-workers`; this class adds the S3 REST transport
+ * (`S3ObjectBucket`) and the SigV4 presign methods, which a bucket binding
+ * cannot mint.
  */
-import type { SegmentFindKey, SegmentMetadata, SegmentRecord, SegmentStore, SegmentStoreStats, SegmentStream } from './segment-store.js';
+import { BucketSegmentStore } from './bucket-segment-store.js';
 import type { DelegatedPresignConfig, SegmentUrlIssue } from './signed-url.js';
 export interface S3SegmentStoreConfig {
     /**
@@ -65,28 +32,9 @@ export interface S3SegmentStoreConfig {
     /** Segment TTL (§5.1 cache semantics). Default 24 h. */
     readonly ttlMs?: number;
 }
-export declare class S3SegmentStore implements SegmentStore {
+export declare class S3SegmentStore extends BucketSegmentStore {
     #private;
     constructor(config: S3SegmentStoreConfig);
-    /** `{keyPrefix}seg/sha256/{hex}` — the §5.4 "key embeds the segmentId". */
-    objectKeyFor(segmentId: string): string;
-    put(metadata: SegmentMetadata, bytes: Uint8Array, nowMs: number): Promise<SegmentRecord>;
-    get(segmentId: string): Promise<{
-        record: SegmentRecord;
-        bytes: Uint8Array;
-    } | undefined>;
-    /** The record plus the object GET's body, never buffered (see `get`). */
-    open(segmentId: string): Promise<SegmentStream | undefined>;
-    find(key: SegmentFindKey, nowMs: number): Promise<SegmentRecord | undefined>;
-    /**
-     * Store-wide counters from the pointer-object accumulator (never a LIST).
-     * Marked `approximate: true`: the counters are maintained by a best-effort
-     * ETag-CAS read-modify-write on `put`, so a crash between the segment PUT
-     * and the accumulator write, or lifecycle GC that deletes objects the
-     * accumulator still counts, can drift them. Exact within a single writer;
-     * a health gauge under concurrency. See the README "S3 stats".
-     */
-    stats(): Promise<SegmentStoreStats>;
     /**
      * SigV4 presigned GET for a segment object (§5.4 delegated presign).
      * The signed key embeds the `segmentId` (equivalence rule) and

package/dist/s3-segment-store.js

@@ -1,196 +1,31 @@
-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}$/;
-const RECORD_META_HEADER = 'x-amz-meta-syncular-record';
 /**
- * Stats accumulator (§ "S3 stats" in the README). The store keeps a small
- * counter object under a fixed key, updated read-modify-write on `put`. It
- * exists because a LIST-free store (every lookup is a GET/HEAD) has no cheap
- * way to count objects on demand — so `stats()` reads the accumulator instead
- * of enumerating the bucket.
+ * S3-compatible segment store (SPEC.md §5.1 cache semantics, §5.4
+ * delegated presign) — AWS S3, Cloudflare R2's S3 endpoint, MinIO. Zero
+ * dependencies: hand-rolled SigV4 over `fetch` (sigv4.ts).
  *
- * The write is guarded by an ETag compare-and-swap (`If-Match`, or
- * `If-None-Match: *` to create): the loop re-reads and retries on a `412`
- * precondition failure, so concurrent writers do not silently clobber each
- * other's increment. The counters are still APPROXIMATE — a crash between the
- * segment PUT and the accumulator CAS, or a writer against a backend that
- * ignores conditional headers, can drift them — so the admin surface labels
- * S3 stats `approximate: true`. They are a health gauge, not an invoice.
+ * The store logic (key layout, record CAS, reuse pointers, stats
+ * accumulator) is `BucketSegmentStore`, shared with `R2SegmentStore` in
+ * `@syncular/server-workers`; this class adds the S3 REST transport
+ * (`S3ObjectBucket`) and the SigV4 presign methods, which a bucket binding
+ * cannot mint.
  */
-const STATS_KEY_SUFFIX = 'stats/segments.json';
-const CAS_ATTEMPTS = 16;
-function emptyStats() {
-    return { count: 0, bytes: 0, rowsSegments: 0, sqliteSegments: 0 };
-}
-function parseStatsJson(json) {
-    const parsed = JSON.parse(json);
-    return {
-        count: Number(parsed.count ?? 0),
-        bytes: Number(parsed.bytes ?? 0),
-        rowsSegments: Number(parsed.rowsSegments ?? 0),
-        sqliteSegments: Number(parsed.sqliteSegments ?? 0),
-    };
-}
-// Runtime-neutral base64url: `Buffer` is not present on
-// 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);
-    for (let i = 0; i < binary.length; i++)
-        bytes[i] = binary.charCodeAt(i);
-    return new TextDecoder().decode(bytes);
-}
-function recordToJson(record) {
-    return JSON.stringify(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 {
-        parsed = JSON.parse(json);
-    }
-    catch {
-        throw new Error(`S3SegmentStore: corrupt record JSON in ${source}`);
-    }
-    if (typeof parsed !== 'object' || parsed === null) {
-        throw new Error(`S3SegmentStore: corrupt record in ${source}`);
-    }
-    const r = parsed;
-    const strings = [
-        'segmentId',
-        'partition',
-        'logEpoch',
-        'table',
-        'scopeDigest',
-    ];
-    const numbers = [
-        'schemaVersion',
-        'asOfCommitSeq',
-        'rowCount',
-        'byteLength',
-        'createdAtMs',
-        'expiresAtMs',
-    ];
-    for (const field of strings) {
-        if (typeof r[field] !== 'string') {
-            throw new Error(`S3SegmentStore: bad record field ${field} in ${source}`);
-        }
-    }
-    for (const field of numbers) {
-        if (typeof r[field] !== 'number') {
-            throw new Error(`S3SegmentStore: bad record field ${field} in ${source}`);
-        }
-    }
-    if (!isMediaType(r.mediaType)) {
-        throw new Error(`S3SegmentStore: bad record mediaType in ${source}`);
-    }
-    const cursorOk = (v) => v === null || typeof v === 'string';
-    if (!cursorOk(r.rowCursor) || !cursorOk(r.nextRowCursor)) {
-        throw new Error(`S3SegmentStore: bad record cursor in ${source}`);
-    }
-    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,
-        scopeDigests: [
-            scopeDigest,
-            ...(rawDigests ?? []).filter((digest) => digest !== scopeDigest),
-        ],
-        asOfCommitSeq: r.asOfCommitSeq,
-        rowCount: r.rowCount,
-        rowCursor: r.rowCursor,
-        nextRowCursor: r.nextRowCursor,
-        byteLength: r.byteLength,
-        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;
+import { BucketSegmentStore, } from './bucket-segment-store.js';
+import { S3ObjectBucket } from './s3-object-bucket.js';
+import { presignUrl } from './sigv4.js';
+const SEGMENT_ID_PATTERN = /^sha256:[0-9a-f]{64}$/;
+export class S3SegmentStore extends BucketSegmentStore {
+    #bucket;
+    #region;
     #credentials;
-    #ttlMs;
-    #prefix;
     constructor(config) {
-        this.#config = config;
+        const options = {
+            keyPrefix: config.keyPrefix,
+            ttlMs: config.ttlMs,
+        };
+        const bucket = new S3ObjectBucket(config);
+        super(bucket, options);
+        this.#bucket = bucket;
+        this.#region = config.region;
         this.#credentials = {
             accessKeyId: config.accessKeyId,
             secretAccessKey: config.secretAccessKey,
@@ -198,319 +33,6 @@ export class S3SegmentStore {
                 ? { sessionToken: config.sessionToken }
                 : {}),
         };
-        this.#ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
-        this.#prefix = config.keyPrefix ?? '';
-    }
-    /** `{keyPrefix}seg/sha256/{hex}` — the §5.4 "key embeds the segmentId". */
-    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,
-            key.logEpoch,
-            key.table,
-            key.schemaVersion,
-            key.mediaType,
-            key.scopeDigest,
-            key.asOfCommitSeq,
-        ]);
-        return `${this.#prefix}find/${await sha256Hex(canonical)}.json`;
-    }
-    #statsKey() {
-        return `${this.#prefix}${STATS_KEY_SUFFIX}`;
-    }
-    #urlFor(key) {
-        const endpoint = this.#config.endpoint.replace(/\/+$/, '');
-        return new URL(`${endpoint}/${this.#config.bucket}/${key}`);
-    }
-    async #request(method, key, options) {
-        const url = this.#urlFor(key);
-        const body = options?.body;
-        const headers = await signRequest({
-            method,
-            url,
-            region: this.#config.region,
-            credentials: this.#credentials,
-            nowMs: Date.now(),
-            payloadHash: body === undefined ? EMPTY_PAYLOAD_SHA256 : await sha256Hex(body),
-            ...(options?.headers !== undefined ? { headers: options.headers } : {}),
-        });
-        const response = await fetch(url, {
-            method,
-            headers,
-            ...(body !== undefined ? { body: body } : {}),
-        });
-        if (response.status === 404) {
-            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}`);
-        }
-        return response;
-    }
-    /** Read the stats accumulator + its ETag (for the CAS write), or none. */
-    async #readStats() {
-        const response = await this.#request('GET', this.#statsKey());
-        if (response === undefined) {
-            return { stats: emptyStats(), etag: undefined };
-        }
-        const etag = response.headers.get('etag') ?? undefined;
-        const stats = parseStatsJson(await response.text());
-        return { stats, etag };
-    }
-    /**
-     * Conditionally write the stats accumulator. `etag` present ⇒ `If-Match`
-     * (update the object we read); absent ⇒ `If-None-Match: *` (create only).
-     * Returns `false` on a `412` precondition failure so the caller retries.
-     */
-    async #writeStatsCas(stats, etag) {
-        const url = this.#urlFor(this.#statsKey());
-        const body = new TextEncoder().encode(JSON.stringify(stats));
-        const conditional = etag === undefined ? { 'if-none-match': '*' } : { 'if-match': etag };
-        const headers = await signRequest({
-            method: 'PUT',
-            url,
-            region: this.#config.region,
-            credentials: this.#credentials,
-            nowMs: Date.now(),
-            payloadHash: await sha256Hex(body),
-            headers: { 'content-type': 'application/json', ...conditional },
-        });
-        const response = await fetch(url, {
-            method: 'PUT',
-            headers,
-            body: body,
-        });
-        if (response.status === 412) {
-            await response.arrayBuffer();
-            return false;
-        }
-        if (!response.ok) {
-            const detail = (await response.text()).slice(0, 300);
-            throw new Error(`S3SegmentStore: stats PUT failed with ${response.status}: ${detail}`);
-        }
-        await response.arrayBuffer();
-        return true;
-    }
-    /**
-     * Fold `delta` into the stats accumulator under an ETag compare-and-swap
-     * retry loop. Best-effort: exhausting the retry budget leaves the counters
-     * drifted (they are documented APPROXIMATE) rather than failing the `put`
-     * that already stored the bytes.
-     */
-    async #bumpStats(delta) {
-        for (let attempt = 0; attempt < CAS_ATTEMPTS; attempt++) {
-            const { stats, etag } = await this.#readStats();
-            const next = {
-                count: stats.count + delta.count,
-                bytes: stats.bytes + delta.bytes,
-                rowsSegments: stats.rowsSegments + delta.rowsSegments,
-                sqliteSegments: stats.sqliteSegments + delta.sqliteSegments,
-            };
-            if (await this.#writeStatsCas(next, etag))
-                return;
-        }
-        // 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);
-        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',
-                'if-none-match': '*',
-            },
-            allow412: true,
-        });
-        if (response === undefined || response.status !== 412) {
-            await response?.arrayBuffer();
-            return;
-        }
-        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)`);
-        }
-    }
-    /**
-     * 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;
-        return {
-            record: record.record,
-            bytes: new Uint8Array(await response.arrayBuffer()),
-        };
-    }
-    /** The record plus the object GET's body, never buffered (see `get`). */
-    async open(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 || response.body === null)
-            return undefined;
-        return {
-            record: record.record,
-            body: response.body,
-            byteLength: record.record.byteLength,
-        };
-    }
-    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');
-        // 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 publicationRecord(record, publication);
-    }
-    /**
-     * Store-wide counters from the pointer-object accumulator (never a LIST).
-     * Marked `approximate: true`: the counters are maintained by a best-effort
-     * ETag-CAS read-modify-write on `put`, so a crash between the segment PUT
-     * and the accumulator write, or lifecycle GC that deletes objects the
-     * accumulator still counts, can drift them. Exact within a single writer;
-     * a health gauge under concurrency. See the README "S3 stats".
-     */
-    async stats() {
-        const { stats } = await this.#readStats();
-        return {
-            count: stats.count,
-            bytes: stats.bytes,
-            rowsSegments: stats.rowsSegments,
-            sqliteSegments: stats.sqliteSegments,
-            approximate: true,
-        };
     }
     /**
      * SigV4 presigned GET for a segment object (§5.4 delegated presign).
@@ -526,8 +48,8 @@ export class S3SegmentStore {
         const ttlSeconds = options?.ttlSeconds ?? 900;
         const nowMs = options?.nowMs ?? Date.now();
         const url = await presignUrl({
-            url: this.#urlFor(this.objectKeyFor(segmentId)),
-            region: this.#config.region,
+            url: this.#bucket.urlFor(this.objectKeyFor(segmentId)),
+            region: this.#region,
             credentials: this.#credentials,
             nowMs,
             expiresSeconds: ttlSeconds,

package/dist/seed.js

@@ -13,6 +13,7 @@ import { decodeMessage, encodeMessage, encodeSparseRow, PROTOCOL_WIRE_VERSION, }
 import { SyncError } from './errors.js';
 import { composeEvents } from './events-ring.js';
 import { handleSyncRequest } from './handler.js';
+import { renderScopeValue } from './scopes.js';
 /** Structured terminal failure from the real push path used by a seed. */
 export class SeedMutationError extends Error {
     name = 'SeedMutationError';
@@ -94,9 +95,9 @@ export async function seedMutations(config, target, mutations) {
         }
         const values = table.columns.map((column) => (byColumn.get(column.name) ?? null));
         const pkIndex = table.columns.findIndex((c) => c.name === table.primaryKey);
-        const rowId = values[pkIndex];
-        if (typeof rowId !== 'string' || rowId.length === 0) {
-            throw new SyncError('sync.invalid_request', `seedMutations: table ${table.name}: upsert requires a non-empty string primary key`);
+        const rowId = renderScopeValue(values[pkIndex]);
+        if (rowId === undefined) {
+            throw new SyncError('sync.invalid_request', `seedMutations: table ${table.name}: upsert requires a non-empty primary key`);
         }
         return {
             table: mutation.table,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
   },
   "dependencies": {
-    "@syncular/core": "0.32.0"
+    "@syncular/core": "0.33.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"