@syncular/server 0.32.1 → 0.34.0

package/dist/bucket-segment-store.js

@@ -0,0 +1,445 @@
+import { mergeSegmentRecord, publicationRecord, publicationsForRecord, segmentBytesEqual, segmentIdFor, selectSegmentPublication, } from './segment-store.js';
+import { sha256Hex } from './sigv4.js';
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const SEGMENT_ID_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/** Legacy record carried in the bytes object's user metadata. */
+const LEGACY_RECORD_META_KEY = '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.
+ *
+ * The write is guarded by an ETag compare-and-swap (`ifMatch`, or `createOnly`
+ * to create): the loop re-reads and retries on a failed precondition, 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
+ * writes, can drift them — so the admin surface labels these stats
+ * `approximate: true`. They are a health gauge, not an invoice.
+ */
+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, label) {
+    if (typeof value !== 'object' || value === null) {
+        throw new Error(`${label}: 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(`${label}: bad publication field ${field} in ${source}`);
+        }
+    }
+    for (const field of numbers) {
+        if (typeof p[field] !== 'number') {
+            throw new Error(`${label}: bad publication field ${field} in ${source}`);
+        }
+    }
+    if (!isMediaType(p.mediaType)) {
+        throw new Error(`${label}: bad publication mediaType in ${source}`);
+    }
+    const cursorOk = (v) => v === null || typeof v === 'string';
+    if (!cursorOk(p.rowCursor) || !cursorOk(p.nextRowCursor)) {
+        throw new Error(`${label}: 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, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new Error(`${label}: corrupt record JSON in ${source}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error(`${label}: 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(`${label}: bad record field ${field} in ${source}`);
+        }
+    }
+    for (const field of numbers) {
+        if (typeof r[field] !== 'number') {
+            throw new Error(`${label}: bad record field ${field} in ${source}`);
+        }
+    }
+    if (!isMediaType(r.mediaType)) {
+        throw new Error(`${label}: bad record mediaType in ${source}`);
+    }
+    const cursorOk = (v) => v === null || typeof v === 'string';
+    if (!cursorOk(r.rowCursor) || !cursorOk(r.nextRowCursor)) {
+        throw new Error(`${label}: 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(`${label}: bad record scopeDigests in ${source}`);
+    }
+    const rawPublications = r.publications;
+    if (rawPublications !== undefined && !Array.isArray(rawPublications)) {
+        throw new Error(`${label}: 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, label)),
+    };
+}
+export class BucketSegmentStore {
+    #bucket;
+    #ttlMs;
+    #prefix;
+    /** Error prefix: the concrete store class the host constructed. */
+    #label;
+    constructor(bucket, options) {
+        this.#bucket = bucket;
+        this.#ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
+        this.#prefix = options?.keyPrefix ?? '';
+        this.#label = this.constructor.name;
+    }
+    /** `{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}`;
+    }
+    /** Read the stats accumulator + its ETag (for the CAS write), or none. */
+    async #readStats() {
+        const object = await this.#bucket.get(this.#statsKey());
+        if (object === undefined) {
+            return { stats: emptyStats(), etag: undefined };
+        }
+        return {
+            stats: parseStatsJson(await object.text()),
+            etag: object.etag,
+        };
+    }
+    /**
+     * Conditionally write the stats accumulator. `etag` present ⇒ `ifMatch`
+     * (update the object we read); absent ⇒ `createOnly` (create only). Returns
+     * `false` on a failed precondition so the caller retries.
+     */
+    async #writeStatsCas(stats, etag) {
+        return this.#bucket.put(this.#statsKey(), {
+            body: new TextEncoder().encode(JSON.stringify(stats)),
+            contentType: 'application/json',
+            ...(etag === undefined ? { createOnly: true } : { ifMatch: etag }),
+        });
+    }
+    /**
+     * 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 failed
+            // precondition 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 written = await this.#bucket.put(this.#recordKeyFor(segmentId), {
+                body: new TextEncoder().encode(recordJson),
+                contentType: 'application/json',
+                ...(preexisting?.etag === undefined
+                    ? { createOnly: true }
+                    : { ifMatch: preexisting.etag }),
+            });
+            if (!written)
+                continue;
+            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) {
+                await this.#bucket.put(await this.#findKeyFor(metadata), {
+                    body: new TextEncoder().encode(recordJson),
+                    contentType: 'application/json',
+                });
+            }
+            return record;
+        }
+        throw new Error(`${this.#label}: ${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 written = await this.#bucket.put(key, {
+            body: bytes,
+            contentType: 'application/octet-stream',
+            createOnly: true,
+        });
+        if (written)
+            return;
+        const current = await this.#bucket.get(key);
+        if (current === undefined)
+            return;
+        const stored = new Uint8Array(await current.arrayBuffer());
+        if (!segmentBytesEqual(stored, bytes)) {
+            throw new Error(`${this.#label}: 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 object = await this.#bucket.get(this.#recordKeyFor(segmentId));
+        if (object !== undefined) {
+            return {
+                record: parseRecordJson(await object.text(), 'segment record', this.#label),
+                etag: object.etag,
+            };
+        }
+        const legacy = await this.#bucket.get(this.objectKeyFor(segmentId));
+        if (legacy === undefined)
+            return undefined;
+        const meta = legacy.metadata[LEGACY_RECORD_META_KEY];
+        await legacy.arrayBuffer();
+        if (meta === undefined)
+            return undefined;
+        return {
+            record: parseRecordJson(base64urlToUtf8(meta), segmentId, this.#label),
+            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 object = await this.#bucket.get(this.objectKeyFor(segmentId));
+        if (object === undefined)
+            return undefined;
+        return {
+            record: record.record,
+            bytes: new Uint8Array(await object.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 object = await this.#bucket.get(this.objectKeyFor(segmentId));
+        if (object === undefined || object.body === null)
+            return undefined;
+        return {
+            record: record.record,
+            body: object.body,
+            byteLength: record.record.byteLength,
+        };
+    }
+    async find(key, nowMs) {
+        const pointer = await this.#bucket.get(await this.#findKeyFor(key));
+        if (pointer === undefined)
+            return undefined;
+        const record = parseRecordJson(await pointer.text(), 'reuse pointer', this.#label);
+        // 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.#bucket.head(this.objectKeyFor(record.segmentId));
+        if (head === undefined)
+            return undefined;
+        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,
+        };
+    }
+}

package/dist/context.d.ts

@@ -69,6 +69,13 @@ export declare const DEFAULT_LIMITS: ServerLimits;
 /** Receives applied commits for realtime fanout (§8.2). */
 export interface RealtimeNotifier {
     notifyCommit(partition: string, commit: StoredCommit): void | Promise<void>;
+    /**
+     * A pull changed the client's persisted subscription list (§8.7). A hub
+     * re-registers that client's live sockets, so a client that runs its
+     * rounds over HTTP while a socket is open receives deltas for the new
+     * subscriptions.
+     */
+    notifySubscriptions?(partition: string, clientId: string): void | Promise<void>;
 }
 export interface SyncServerConfig {
     readonly schema: ServerSchema;

package/dist/d1-storage.js

@@ -45,7 +45,7 @@ import { StorageQueryError } from './storage-errors.js';
 import { decodeRow } from '@syncular/core';
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { assertAppendOnlyMigration, assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, latestScopedChangeSeqSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertAppendOnlyMigration, assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { asUint8Array, collectCommitWindowPage, deserializePushResult, placeholders, serializePushResult, sqliteDdlStatements, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors.js';
@@ -1456,7 +1456,7 @@ export class D1ServerStorage {
         if (firstVariable === undefined || values.length === 0)
             return 0;
         // Concurrent reads of a pull share one `db.batch` round trip.
-        const [row] = await this.#batchedAll(latestScopedChangeSeqSql(values.length), values.flatMap((value) => [partition, query.table, firstVariable, value]));
+        const [row] = await this.#batchedAll(LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL, [partition, query.table, firstVariable, JSON.stringify(values)]);
         return row?.seq ?? 0;
     }
     async readCommitWindow(partition, query) {

package/dist/handler.js

@@ -484,6 +484,10 @@ async function* streamResponse(plan, ctx, schema, report) {
             updatedAtMs: clockOf(ctx)(),
             subscriptions,
         });
+        if (ctx.realtime?.notifySubscriptions !== undefined &&
+            JSON.stringify((previous?.subscriptions ?? []).map((s) => [s.id, s.table, s.scopes])) !== JSON.stringify(subscriptions.map((s) => [s.id, s.table, s.scopes]))) {
+            await ctx.realtime.notifySubscriptions(ctx.partition, plan.header.clientId);
+        }
     }
     catch (error) {
         if (error instanceof SyncError) {

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export * from './admin.js';
 export * from './authoritative-query.js';
 export * from './blob-handlers.js';
 export * from './blob-store.js';
+export * from './bucket-blob-store.js';
+export * from './bucket-segment-store.js';
 export * from './content-encoding.js';
 export * from './context.js';
 export * from './crdt-merger.js';
@@ -33,8 +35,10 @@ export * from './readiness.js';
 export { DEFAULT_REACTION_INITIAL_BACKOFF_MS, DEFAULT_REACTION_LEASE_MS, DEFAULT_REACTION_MAX_ATTEMPTS, DEFAULT_REACTION_MAX_BACKOFF_MS, DEFAULT_REACTION_RETENTION, MAX_REACTION_FAILURE_DETAILS_BYTES, MAX_REACTION_PAYLOAD_BYTES, MAX_REACTIONS_PER_COMMIT, PermanentReactionError, pruneReactions, ReactionRunner, reactionIdempotencyKey, retryDeadLetterReaction, RetryableReactionError, type PlannedReaction, type PruneReactionsOptions, type ReactionHandler, type ReactionHandlerInput, type ReactionHandlers, type ReactionPlan, type ReactionPlanner, type ReactionPlannerInput, type ReactionPruneResult, type ReactionRetentionPolicy, type ReactionRunnerOptions, type ReactionRunResult, type ReactionTypeMap, } from './reactions.js';
 export * from './realtime.js';
 export * from './restore.js';
+export * from './object-bucket.js';
 export * from './relational-rows.js';
 export * from './s3-blob-store.js';
+export * from './s3-object-bucket.js';
 export * from './s3-segment-store.js';
 export * from './schema.js';
 export * from './scopes.js';

package/dist/index.js

@@ -11,6 +11,8 @@ export * from './admin.js';
 export * from './authoritative-query.js';
 export * from './blob-handlers.js';
 export * from './blob-store.js';
+export * from './bucket-blob-store.js';
+export * from './bucket-segment-store.js';
 export * from './content-encoding.js';
 export * from './context.js';
 export * from './crdt-merger.js';
@@ -37,8 +39,10 @@ export * from './readiness.js';
 export { DEFAULT_REACTION_INITIAL_BACKOFF_MS, DEFAULT_REACTION_LEASE_MS, DEFAULT_REACTION_MAX_ATTEMPTS, DEFAULT_REACTION_MAX_BACKOFF_MS, DEFAULT_REACTION_RETENTION, MAX_REACTION_FAILURE_DETAILS_BYTES, MAX_REACTION_PAYLOAD_BYTES, MAX_REACTIONS_PER_COMMIT, PermanentReactionError, pruneReactions, ReactionRunner, reactionIdempotencyKey, retryDeadLetterReaction, RetryableReactionError, } from './reactions.js';
 export * from './realtime.js';
 export * from './restore.js';
+export * from './object-bucket.js';
 export * from './relational-rows.js';
 export * from './s3-blob-store.js';
+export * from './s3-object-bucket.js';
 export * from './s3-segment-store.js';
 export * from './schema.js';
 export * from './scopes.js';

package/dist/object-bucket.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The object-bucket seam: the handful of object-store operations the durable
+ * segment store (§5.1) and blob store (§5.9.2) actually perform, expressed
+ * without an HTTP transport.
+ *
+ * Two adapters implement it — `S3ObjectBucket` (`s3-object-bucket.ts`,
+ * hand-rolled SigV4 over `fetch`) and the R2 binding adapter in
+ * `@syncular/server-workers` (`r2-stores.ts`, the Worker's `env.BUCKET`) — so
+ * one implementation of the store logic (`bucket-segment-store.ts`,
+ * `bucket-blob-store.ts`) runs over both. The key layouts are the same on
+ * either transport, so a bucket can be served through the S3 API for one host
+ * and the binding for another.
+ *
+ * Everything here is structural: an adapter may be any object with these
+ * methods, and Cloudflare's `R2Bucket` is assignable to the declaration in
+ * `r2-stores.ts` without a dependency on `@cloudflare/workers-types`.
+ */
+/** One stored object, readable once. Mirrors `R2ObjectBody`. */
+export interface BucketObject {
+    /** The body, streamed; `null` only if the backend served none. */
+    readonly body: ReadableStream<Uint8Array<ArrayBuffer>> | null;
+    /** Backend ETag of the stored object (opaque, used as a CAS token). */
+    readonly etag: string | undefined;
+    /** Stored size in bytes, when the backend reports one. */
+    readonly size: number | undefined;
+    /** User metadata: the `x-amz-meta-*` headers S3-side, `customMetadata` on R2. */
+    readonly metadata: Readonly<Record<string, string>>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+}
+/** One stored object's description without its body. Mirrors `R2Object`. */
+export interface BucketObjectHead {
+    readonly etag: string | undefined;
+    readonly size: number | undefined;
+    readonly metadata: Readonly<Record<string, string>>;
+}
+export interface BucketWriteOptions {
+    readonly body: Uint8Array;
+    readonly contentType: string;
+    /** User metadata; values must be ASCII (both backends require it). */
+    readonly metadata?: Readonly<Record<string, string>> | undefined;
+    /**
+     * Create-only write (`If-None-Match: *`, R2 `etagDoesNotMatch: '*'`). The
+     * content-addressed bytes object is written this way so a second publisher
+     * of identical bytes is a no-op and a hash collision cannot overwrite.
+     */
+    readonly createOnly?: boolean | undefined;
+    /**
+     * Compare-and-swap write (`If-Match`, R2 `etagMatches`): the write lands
+     * only if the stored ETag still equals this. The read-modify-write of the
+     * segment record and of the stats accumulator depend on it.
+     */
+    readonly ifMatch?: string | undefined;
+}
+/** One page of keys under a prefix. `cursor` is set when more remain. */
+export interface BucketListPage {
+    readonly keys: readonly string[];
+    readonly cursor: string | undefined;
+}
+export interface ObjectBucket {
+    /** The object plus its bytes, or `undefined` when the key is absent. */
+    get(key: string): Promise<BucketObject | undefined>;
+    head(key: string): Promise<BucketObjectHead | undefined>;
+    /**
+     * Write one object. Returns `false` when the `createOnly` / `ifMatch`
+     * precondition failed, so the caller can re-read and retry; a backend that
+     * ignores conditional writes would instead silently lose a concurrent
+     * update, which is why the return value is not optional.
+     */
+    put(key: string, options: BucketWriteOptions): Promise<boolean>;
+    /** Delete one object. Deleting an absent key succeeds (idempotent). */
+    delete(key: string): Promise<void>;
+    /**
+     * List keys under a prefix, one page at a time. The blob orphan sweep
+     * (§5.9.2) is the only caller: everything on the hot path is a GET/HEAD.
+     */
+    list(prefix: string, cursor?: string): Promise<BucketListPage>;
+}

package/dist/object-bucket.js

@@ -0,0 +1,18 @@
+/**
+ * The object-bucket seam: the handful of object-store operations the durable
+ * segment store (§5.1) and blob store (§5.9.2) actually perform, expressed
+ * without an HTTP transport.
+ *
+ * Two adapters implement it — `S3ObjectBucket` (`s3-object-bucket.ts`,
+ * hand-rolled SigV4 over `fetch`) and the R2 binding adapter in
+ * `@syncular/server-workers` (`r2-stores.ts`, the Worker's `env.BUCKET`) — so
+ * one implementation of the store logic (`bucket-segment-store.ts`,
+ * `bucket-blob-store.ts`) runs over both. The key layouts are the same on
+ * either transport, so a bucket can be served through the S3 API for one host
+ * and the binding for another.
+ *
+ * Everything here is structural: an adapter may be any object with these
+ * methods, and Cloudflare's `R2Bucket` is assignable to the declaration in
+ * `r2-stores.ts` without a dependency on `@cloudflare/workers-types`.
+ */
+export {};

package/dist/operations-realtime.js

@@ -195,5 +195,8 @@ export function composeRealtimeNotifiers(...notifiers) {
         notifyCommit: async (partition, commit) => {
             await Promise.all(notifiers.map((notifier) => notifier.notifyCommit(partition, commit)));
         },
+        notifySubscriptions: async (partition, clientId) => {
+            await Promise.all(notifiers.map((notifier) => notifier.notifySubscriptions?.(partition, clientId)));
+        },
     };
 }

package/dist/operations.d.ts

@@ -1,6 +1,6 @@
 import { type AuthoritativeRelationPlan } from './authoritative-query.js';
-import { type RemoteOperationResponse, type RowValue } from '@syncular/core';
-import type { SyncRequestContext } from './context.js';
+import { type RemoteOperationRequest, type RemoteOperationResponse, type RowValue } from '@syncular/core';
+import type { ResolveScopes, SyncRequestContext } from './context.js';
 import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, AuthoritativeQueryValue } from './storage.js';
 import { type ValidateRow } from './validate.js';
 export interface RemoteQueryDependency {
@@ -101,5 +101,22 @@ export declare class RemoteOperationRegistry {
     constructor(operations: readonly RegisteredRemoteOperation[]);
     get(id: string): RegisteredRemoteOperation | undefined;
 }
-export declare function handleRemoteOperation(bytes: Uint8Array, ctx: SyncRequestContext, registry: RemoteOperationRegistry): Promise<Uint8Array>;
+/**
+ * The registry and identity one remote operation request runs with
+ * (REMOTE.md §5.1). `actorId` is the commit's actor and defaults to the
+ * authenticated actor; `resolveScopes` replaces the configured resolver for
+ * this request.
+ */
+export interface RemoteOperationBinding {
+    readonly registry: RemoteOperationRegistry;
+    readonly actorId?: string;
+    readonly resolveScopes?: ResolveScopes;
+}
+/**
+ * Chooses the binding of one decoded request (REMOTE.md §5.1). `ctx` carries
+ * the authenticated actor; the resolver runs after the client-id binding
+ * check and may throw a `SyncError` or a `ValidationRejection`.
+ */
+export type RemoteOperationResolver = (request: RemoteOperationRequest, ctx: SyncRequestContext) => RemoteOperationBinding | Promise<RemoteOperationBinding>;
+export declare function handleRemoteOperation(bytes: Uint8Array, authenticated: SyncRequestContext, operations: RemoteOperationRegistry | RemoteOperationResolver): Promise<Uint8Array>;
 export {};