@syncular/server 0.1.3 → 0.2.1

package/src/blob-handlers.ts

@@ -0,0 +1,340 @@
+/**
+ * Blob upload + download handlers (SPEC.md §5.9.3, §5.9.5).
+ *
+ * Upload verifies the content address (§5.9.3); download re-authorizes on
+ * every request against the rows that reference the blob (§5.9.5) — a
+ * `blobId` is never a bearer capability. Framework-free; the hono/runtime
+ * adapters map these onto `PUT/GET <mount>/blobs/{blobId}`.
+ */
+import { blobIdFor, isBlobId } from './blob-store';
+import type { SyncRequestContext } from './context';
+import { clockOf, RESOLVER_OUTAGE } from './context';
+import { SyncError, syncError } from './errors';
+import { emitEvent } from './events';
+import { compileSchema } from './schema';
+import { authorizeWrite, type ResolvedScopes } from './scopes';
+import { issueBlobUploadUrl, issueBlobUrl } from './signed-url';
+
+const DEFAULT_MAX_BLOB_BYTES = 64 * 1024 * 1024;
+
+export interface BlobUploadRequest {
+  readonly blobId: string;
+  readonly bytes: Uint8Array;
+  /** Advisory MIME type from the upload `Content-Type`, if any. */
+  readonly mediaType?: string;
+}
+
+export interface BlobDownloadResult {
+  /**
+   * The blob bytes, when served inline. **Absent** when the host configured
+   * `blobSignedUrls` and a `url` was issued: the sync server exits the egress
+   * path and the client fetches `url` directly (§5.9.5 always-issue).
+   */
+  readonly bytes?: Uint8Array;
+  readonly headers: Record<string, string>;
+  /**
+   * §5.9.5 delegated presign (always-issue): a provider-signed GET URL for
+   * the bytes, issued only after the row-derived authorization check passed.
+   * Present iff the host configured `blobSignedUrls`; when present, `bytes` is
+   * absent and the client MUST fetch the URL directly (no host auth), verify
+   * the content address, and on failure re-request this endpoint — never fall
+   * through (§5.9.5 recovery rule).
+   */
+  readonly url?: string;
+  readonly urlExpiresAtMs?: number;
+}
+
+/** `POST <mount>/blobs/{blobId}/upload-grant` request body (§5.9.3). */
+export interface BlobUploadGrantRequest {
+  readonly blobId: string;
+  /** Declared uncompressed size — the size-cap check runs against this. */
+  readonly byteLength: number;
+  /** Advisory MIME type, if any. */
+  readonly mediaType?: string;
+}
+
+/**
+ * `POST <mount>/blobs/{blobId}/upload-grant` result (§5.9.3). Exactly one of:
+ * `{url, urlExpiresAtMs}` — a presigned PUT the client uses direct-to-storage;
+ * or `{present: true}` — the blob already exists (idempotent §5.9.3), so the
+ * client skips the PUT; or `{}` (no fields) — the host has no presigned-upload
+ * store configured, so the client streams through the direct PUT endpoint
+ * (§5.9.3 capability, not fallback).
+ */
+export interface BlobUploadGrantResult {
+  readonly url?: string;
+  readonly urlExpiresAtMs?: number;
+  readonly present?: boolean;
+}
+
+/** `PUT <mount>/blobs/{blobId}` (§5.9.3). Host auth is the adapter's job. */
+export async function handleBlobUpload(
+  ctx: SyncRequestContext,
+  request: BlobUploadRequest,
+): Promise<void> {
+  const store = ctx.blobs;
+  if (store === undefined) {
+    throw syncError('blob.not_found', 'this server has no blob store (§5.9)');
+  }
+  if (!isBlobId(request.blobId)) {
+    throw syncError(
+      'blob.hash_mismatch',
+      'blobId path is not "sha256:<64 hex>" (§5.9.1)',
+    );
+  }
+  const maxBytes = ctx.maxBlobBytes ?? DEFAULT_MAX_BLOB_BYTES;
+  if (request.bytes.length > maxBytes) {
+    throw syncError(
+      'blob.too_large',
+      `blob exceeds the ${maxBytes}-byte cap (§5.9.3)`,
+    );
+  }
+  const computed = await blobIdFor(request.bytes);
+  if (computed !== request.blobId) {
+    throw syncError(
+      'blob.hash_mismatch',
+      'uploaded bytes do not hash to the blobId path (§5.9.3)',
+    );
+  }
+  const clock = clockOf(ctx);
+  await store.put(
+    ctx.partition,
+    request.blobId,
+    request.bytes,
+    clock(),
+    request.mediaType,
+  );
+  if (ctx.events !== undefined) {
+    emitEvent(ctx.events, {
+      type: 'blob.uploaded',
+      atMs: clock(),
+      partition: ctx.partition,
+      actorId: ctx.actorId,
+      blobId: request.blobId,
+      bytes: request.bytes.length,
+    });
+  }
+}
+
+/**
+ * `GET <mount>/blobs/{blobId}` (§5.9.5). Authorization derives from the
+ * referencing rows: the actor may download iff at least one row in the
+ * reference index passes the §3.4 scope check for the actor.
+ */
+export async function handleBlobDownload(
+  ctx: SyncRequestContext,
+  blobId: string,
+): Promise<BlobDownloadResult> {
+  const events = ctx.events;
+  if (events === undefined) return downloadBlob(ctx, blobId);
+  const clock = clockOf(ctx);
+  const startedAtMs = clock();
+  try {
+    const result = await downloadBlob(ctx, blobId);
+    emitEvent(events, {
+      type: 'blob.downloaded',
+      atMs: clock(),
+      partition: ctx.partition,
+      actorId: ctx.actorId,
+      blobId,
+      outcome: 'ok',
+      // Presigned delivery carries no inline bytes (§5.9.5 always-issue); the
+      // byte count is unknown to the sync server, which exited the egress path.
+      bytes: result.bytes?.length ?? 0,
+      durationMs: clock() - startedAtMs,
+    });
+    return result;
+  } catch (error) {
+    emitEvent(events, {
+      type: 'blob.downloaded',
+      atMs: clock(),
+      partition: ctx.partition,
+      actorId: ctx.actorId,
+      blobId,
+      outcome: 'error',
+      errorCode: error instanceof SyncError ? error.code : 'internal',
+      durationMs: clock() - startedAtMs,
+    });
+    throw error;
+  }
+}
+
+async function downloadBlob(
+  ctx: SyncRequestContext,
+  blobId: string,
+): Promise<BlobDownloadResult> {
+  const store = ctx.blobs;
+  if (store === undefined) {
+    throw syncError('blob.not_found', 'this server has no blob store (§5.9)');
+  }
+  if (!isBlobId(blobId)) {
+    throw syncError('blob.not_found', 'malformed blobId (§5.9.1)');
+  }
+  // §5.9.5 always-issue: when presign is configured the server exits the
+  // egress path — it only needs to know the object EXISTS (a HEAD/`has`), not
+  // the bytes. Inline delivery loads the bytes; presigned delivery does not.
+  const presignConfigured = ctx.blobSignedUrls !== undefined;
+  let entry: { record: { mediaType?: string }; bytes: Uint8Array } | undefined;
+  let mediaType: string | undefined;
+  if (presignConfigured) {
+    if (!(await store.has(ctx.partition, blobId))) {
+      throw syncError('blob.not_found', 'unknown blob (§5.9.5)');
+    }
+  } else {
+    entry = await store.get(ctx.partition, blobId);
+    if (entry === undefined) {
+      throw syncError('blob.not_found', 'unknown blob (§5.9.5)');
+    }
+    mediaType = entry.record.mediaType;
+  }
+
+  // §5.9.5 authorization: resolve once, then test referencing rows.
+  const listRows = ctx.storage.listRowsReferencingBlob;
+  if (listRows === undefined) {
+    // Storage without the reference index cannot authorize a download —
+    // fail closed (never serve bytes we cannot authorize).
+    throw syncError(
+      'blob.forbidden',
+      'storage has no blob reference index (§5.9.4)',
+    );
+  }
+  let resolved: ResolvedScopes;
+  try {
+    const allowed = await ctx.resolveScopes({
+      partition: ctx.partition,
+      actorId: ctx.actorId,
+    });
+    // §7.3.3: leases never authorize a blob download — an outage denies.
+    resolved =
+      allowed === RESOLVER_OUTAGE ? { ok: false } : { ok: true, allowed };
+  } catch (error) {
+    if (ctx.events !== undefined) {
+      emitEvent(ctx.events, {
+        type: 'scopes.resolve_failed',
+        atMs: clockOf(ctx)(),
+        partition: ctx.partition,
+        actorId: ctx.actorId,
+        phase: 'blob-download',
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+    resolved = { ok: false };
+  }
+  if (!resolved.ok) {
+    throw syncError('blob.forbidden', 'scope resolution failed (§5.9.5)');
+  }
+
+  const schema = compileSchema(ctx.schema);
+  // A blob download can hit a fresh storage instance before any sync
+  // request has run (Workers): make sure the row tables exist first.
+  await ctx.storage.ensureSchema(schema);
+  const rows = await listRows.call(ctx.storage, ctx.partition, blobId);
+  let authorized = false;
+  for (const row of rows) {
+    const table = schema.tables.get(row.table);
+    if (table === undefined) continue;
+    if (authorizeWrite(table, row.scopes, resolved)) {
+      authorized = true;
+      break;
+    }
+  }
+  if (!authorized) {
+    // Never 404 here: existence-vs-authorization must not leak (§5.9.5).
+    throw syncError(
+      'blob.forbidden',
+      'no referencing row authorizes this actor (§5.9.5)',
+    );
+  }
+
+  // §5.9.5 delegated presign (always-issue): authorization has passed above,
+  // so a signed URL is now a short-TTL bearer grant to exactly these immutable
+  // bytes. When configured, issue it and return NO bytes — the client fetches
+  // the URL directly. Never before the check, never a capability from the id.
+  if (ctx.blobSignedUrls !== undefined) {
+    const issued = await issueBlobUrl(ctx.blobSignedUrls, {
+      partition: ctx.partition,
+      blobId,
+      nowMs: clockOf(ctx)(),
+    });
+    return {
+      headers: {
+        ETag: `"${blobId}"`,
+        'Cache-Control': 'private, max-age=0',
+        Vary: 'Authorization, Accept-Encoding',
+      },
+      url: issued.url,
+      urlExpiresAtMs: issued.urlExpiresAtMs,
+    };
+  }
+
+  // Inline delivery (no presign store configured): the bytes were loaded.
+  const bytes = entry?.bytes;
+  if (bytes === undefined) {
+    // Unreachable: presign not configured ⇒ `entry` was loaded above.
+    throw syncError('blob.not_found', 'blob bytes unavailable (§5.9.5)');
+  }
+  return {
+    bytes,
+    headers: {
+      'Content-Type': mediaType ?? 'application/octet-stream',
+      ETag: `"${blobId}"`,
+      'Cache-Control': 'private, max-age=0',
+      Vary: 'Authorization, Accept-Encoding',
+    },
+  };
+}
+
+/**
+ * `POST <mount>/blobs/{blobId}/upload-grant` (§5.9.3 presigned upload). Host
+ * auth is the adapter's job — uploading is host-auth-only, not scope-bearing,
+ * so any authenticated actor may obtain a grant within the size cap (§5.9.3).
+ *
+ * The size cap is enforced HERE, up front, against the declared `byteLength`
+ * (the object-store hop cannot re-check the streamed byte count). Integrity is
+ * NOT checked here: the object store places bytes at the content-addressed key,
+ * and the address is verified at reference time (§5.9.6 push existence) and on
+ * every download (§5.9.5/§5.1). Returns a presigned single PUT, or a
+ * `present` marker if the blob already exists (idempotent §5.9.3), or an empty
+ * result when no presigned-upload store is configured (client streams direct).
+ */
+export async function handleBlobUploadGrant(
+  ctx: SyncRequestContext,
+  request: BlobUploadGrantRequest,
+): Promise<BlobUploadGrantResult> {
+  const store = ctx.blobs;
+  if (store === undefined) {
+    throw syncError('blob.not_found', 'this server has no blob store (§5.9)');
+  }
+  if (!isBlobId(request.blobId)) {
+    throw syncError(
+      'blob.hash_mismatch',
+      'blobId path is not "sha256:<64 hex>" (§5.9.1)',
+    );
+  }
+  const maxBytes = ctx.maxBlobBytes ?? DEFAULT_MAX_BLOB_BYTES;
+  if (
+    !Number.isInteger(request.byteLength) ||
+    request.byteLength < 0 ||
+    request.byteLength > maxBytes
+  ) {
+    // §5.9.3: cap enforced at grant issuance, before any URL is minted.
+    throw syncError(
+      'blob.too_large',
+      `blob byteLength exceeds the ${maxBytes}-byte cap (§5.9.3)`,
+    );
+  }
+  // §5.9.3 no presigned-upload store: report no grant; the client streams
+  // through the direct PUT endpoint (capability, not fallback).
+  if (ctx.blobUploadUrls === undefined) return {};
+  // Idempotent §5.9.3: an already-present blob needs no PUT.
+  if (await store.has(ctx.partition, request.blobId)) {
+    return { present: true };
+  }
+  const issued = await issueBlobUploadUrl(ctx.blobUploadUrls, {
+    partition: ctx.partition,
+    blobId: request.blobId,
+    byteLength: request.byteLength,
+    nowMs: clockOf(ctx)(),
+  });
+  return { url: issued.url, urlExpiresAtMs: issued.urlExpiresAtMs };
+}

package/src/content-encoding.ts

@@ -0,0 +1,94 @@
+/**
+ * §5.8 shipped compression posture for the direct segment endpoint:
+ * negotiate `Content-Encoding` from the request's `Accept-Encoding`
+ * (zstd preferred, gzip fallback, identity when the client offers
+ * neither), feature-detecting the runtime's codecs — zero dependencies.
+ *
+ * Segment bytes are stored and content-addressed UNCOMPRESSED (§5.1);
+ * this is a per-response serving concern only. It is never applied to
+ * stored objects or the signed-URL path (§5.8: presigned GETs serve the
+ * addressed bytes verbatim; edge compression is a deployment concern).
+ *
+ * Decision data (2026-07-03, 100k-row bench table, Bun 1.3): rows
+ * segments 6.2× in 8 ms (zstd) / 7.7× in 42 ms (gzip); sqlite images
+ * 3.4× in 14 ms (zstd) / 51 ms (gzip); client decompression ≤ 8 ms.
+ */
+
+export type SegmentContentEncoding = 'zstd' | 'gzip';
+
+interface Codec {
+  readonly encoding: SegmentContentEncoding;
+  readonly compress: (bytes: Uint8Array) => Uint8Array;
+}
+
+interface BunCompressors {
+  readonly zstdCompressSync?: (bytes: Uint8Array) => Uint8Array;
+  readonly gzipSync?: (bytes: Uint8Array) => Uint8Array;
+}
+
+/** Preference order is zstd, gzip (§5.8). Non-Bun runtimes without these
+ * codecs serve identity — negotiation, never a hard requirement here. */
+function detectCodecs(): readonly Codec[] {
+  const bun = (globalThis as { Bun?: BunCompressors }).Bun;
+  const codecs: Codec[] = [];
+  const zstd = bun?.zstdCompressSync;
+  if (typeof zstd === 'function') {
+    codecs.push({ encoding: 'zstd', compress: (bytes) => zstd(bytes) });
+  }
+  const gzip = bun?.gzipSync;
+  if (typeof gzip === 'function') {
+    codecs.push({ encoding: 'gzip', compress: (bytes) => gzip(bytes) });
+  }
+  return codecs;
+}
+
+const CODECS = detectCodecs();
+
+/** Bodies below this size are served identity (headers outweigh gains). */
+const MIN_COMPRESS_BYTES = 1024;
+
+/** Does the `Accept-Encoding` header value accept `encoding` (q > 0)? */
+function accepts(header: string, encoding: SegmentContentEncoding): boolean {
+  for (const entry of header.split(',')) {
+    const [rawName, ...params] = entry.trim().split(';');
+    const name = rawName?.trim().toLowerCase();
+    if (name !== encoding) continue;
+    for (const param of params) {
+      const [key, value] = param.trim().split('=');
+      if (key?.trim().toLowerCase() === 'q' && Number(value) === 0) {
+        return false;
+      }
+    }
+    return true;
+  }
+  return false;
+}
+
+export interface EncodedSegmentBody {
+  readonly bytes: Uint8Array;
+  /** Absent ⇒ identity (no `Content-Encoding` header). */
+  readonly contentEncoding?: SegmentContentEncoding;
+}
+
+/**
+ * Compress a buffered segment body per §5.8. Returns the original bytes
+ * (identity) when the client offered no supported encoding, the body is
+ * tiny, or the runtime has no codec.
+ */
+export function encodeSegmentBody(
+  bytes: Uint8Array,
+  acceptEncoding: string | undefined,
+): EncodedSegmentBody {
+  if (acceptEncoding === undefined || bytes.length < MIN_COMPRESS_BYTES) {
+    return { bytes };
+  }
+  for (const codec of CODECS) {
+    if (accepts(acceptEncoding, codec.encoding)) {
+      return {
+        bytes: codec.compress(bytes),
+        contentEncoding: codec.encoding,
+      };
+    }
+  }
+  return { bytes };
+}

package/src/context.ts

@@ -0,0 +1,176 @@
+/**
+ * The host context for `handleSyncRequest` (REVISE B2): storage, the
+ * `resolveScopes` host callback (runs in the host process — the moat),
+ * clock, and a segment store. Framework-free; adapters supply `partition`
+ * and `actorId` from host authentication (§1.1).
+ */
+import type { ScopeMap } from '@syncular/core';
+import type { BlobStore } from './blob-store';
+import type { CrdtMergerRegistry } from './crdt-merger';
+import type { SyncularServerEvents } from './events';
+import type { LeaseStore } from './lease-store';
+import type { ServerSchema } from './schema';
+import type { SegmentStore } from './segment-store';
+import type {
+  BlobPresignConfig,
+  BlobUploadPresignConfig,
+  SegmentUrlConfig,
+} from './signed-url';
+import type { SqliteImageBuilder } from './sqlite-image';
+import type { ServerStorage, StoredCommit } from './storage';
+import type { ValidatorRegistry } from './validate';
+
+/** SSP2 body content type (§1.1). */
+export const SSP2_CONTENT_TYPE = 'application/vnd.syncular.sync.v2';
+
+export interface ResolveScopesArgs {
+  readonly partition: string;
+  readonly actorId: string;
+  /**
+   * The requesting client (§1.5). Present on sync rounds (the lease key,
+   * §7.3.3); absent on segment/blob downloads, which re-authorize by
+   * actor + scopes only (§5.5, §5.9.5) and never consult a lease.
+   */
+  readonly clientId?: string;
+}
+
+/**
+ * Sentinel a resolver returns to signal a **live-authorization outage**
+ * (§7.3.3): the live authority is unreachable, so the server SHOULD
+ * authorize this request against the actor's stored lease instead of
+ * throwing. Distinct from throwing (§3.2 rule 5, which still fails loud
+ * and revokes). Only meaningful when `leases` is configured; without a
+ * lease store an outage degrades to `sync.auth_lease_required`.
+ */
+export const RESOLVER_OUTAGE = Symbol.for('syncular.resolver_outage');
+export type ResolverOutage = typeof RESOLVER_OUTAGE;
+
+/**
+ * Host callback: actor → allowed scopes (§3.2 step 3). Resolved at most
+ * once per request and memoized (§3.4 step 1). `'*'` means "any value for
+ * this variable". A throwing resolver revokes subscriptions and rejects
+ * writes with `sync.forbidden` — fail loud, never leak. Returning
+ * `RESOLVER_OUTAGE` instead opts the request into lease authorization
+ * (§7.3.3) — a deliberate outage signal, not a failure.
+ */
+export type ResolveScopes = (
+  args: ResolveScopesArgs,
+) => ScopeMap | ResolverOutage | Promise<ScopeMap | ResolverOutage>;
+
+/** §7.3: auth-lease feature config. Absent ⇒ leases off (zero cost). */
+export interface LeaseConfig {
+  /** Lease TTL in ms — the sliding window width (§7.3.3). */
+  readonly ttlMs: number;
+  /** The lease store (§7.3.1); host-owned, optional like blobs. */
+  readonly store: LeaseStore;
+}
+
+export interface ServerLimits {
+  /** Operation cap per request (§6.1 `sync.too_many_operations`). */
+  readonly maxOperationsPerRequest: number;
+  /** Inline rows segments up to this size (§5.7 SHOULD: 256 KiB). */
+  readonly inlineSegmentMaxBytes: number;
+}
+
+export const DEFAULT_LIMITS: ServerLimits = {
+  maxOperationsPerRequest: 500,
+  inlineSegmentMaxBytes: 256 * 1024,
+};
+
+/** Receives applied commits for realtime fanout (§8.2). */
+export interface RealtimeNotifier {
+  notifyCommit(partition: string, commit: StoredCommit): void | Promise<void>;
+}
+
+export interface SyncServerConfig {
+  readonly schema: ServerSchema;
+  readonly storage: ServerStorage;
+  readonly segments: SegmentStore;
+  /**
+   * Blob store (§5.9). Absent ⇒ blobs unsupported: a table with a
+   * `blob_ref` column may still sync (the ref is just a string), but the
+   * push existence check (§6.6) and the `/blobs` endpoints require it.
+   */
+  readonly blobs?: BlobStore;
+  /** Max upload size for `/blobs` (§5.9.3 `blob.too_large`); default 64 MiB. */
+  readonly maxBlobBytes?: number;
+  /**
+   * CRDT merger registry (§5.10.2), `crdtType` → merge fn. Absent ⇒ no
+   * column can CRDT-merge: a push touching a `crdt` column then fails
+   * `sync.crdt_merge_failed` (§5.10.6). Kept out of core — the reference
+   * `yjs-doc` merger ships in `@syncular/crdt-yjs` (the blob-store rule).
+   */
+  readonly crdtMergers?: CrdtMergerRegistry;
+  /**
+   * §6.7 per-table write-validation hooks (`table` → validator). Absent ⇒
+   * the feature is off: the push path pays only an `undefined` check and
+   * builds no validator context — zero cost. Present ⇒ each push operation
+   * on a listed table runs its validator after decode + §3.4 scope
+   * authorization, inside the commit transaction; a throw rejects the
+   * whole commit atomically (§6.4) with the host code (§6.3). Kept a host
+   * callback (like `resolveScopes`) — business rules live in the host
+   * process, never on the wire.
+   */
+  readonly validators?: ValidatorRegistry;
+  readonly resolveScopes: ResolveScopes;
+  /**
+   * §7.3 auth leases. Absent ⇒ the feature is off: no `LEASE` frame is
+   * ever emitted and a `RESOLVER_OUTAGE` signal degrades to
+   * `sync.auth_lease_required`. Present ⇒ successful authorized rounds
+   * issue/refresh a lease and outages authorize against it.
+   */
+  readonly leases?: LeaseConfig;
+  /** Epoch-ms clock; defaults to `Date.now`. */
+  readonly clock?: () => number;
+  readonly limits?: Partial<ServerLimits>;
+  /** §5.4 signed-URL delivery: native HMAC tokens or delegated presign. */
+  readonly signedUrls?: SegmentUrlConfig;
+  /**
+   * §5.9.5 signed-URL delivery for BLOB downloads (delegated presign,
+   * always-issue). When set, `handleBlobDownload` issues a provider-presigned
+   * GET URL AFTER the row-derived authorization check and returns
+   * `url`/`urlExpiresAtMs` on `BlobDownloadResult` WITHOUT loading the bytes
+   * (the sync server exits the download egress path). The reference client
+   * fetches the URL directly (§5.9.5 recovery rule: failure ⇒ re-request,
+   * never fall-through). Absent ⇒ blobs are served inline (the shipped
+   * default).
+   */
+  readonly blobSignedUrls?: BlobPresignConfig;
+  /**
+   * §5.9.3 presigned-upload (direct-to-storage) delivery. When set,
+   * `handleBlobUploadGrant` issues a single provider-presigned PUT URL AFTER
+   * host authentication + the size-cap check, and the client PUTs bytes
+   * straight to the object store (the sync server exits the upload egress
+   * path). Absent ⇒ the `/upload-grant` route reports no grant and clients
+   * stream through the direct `PUT /blobs/{blobId}` endpoint (§5.9.3 —
+   * capability, not fallback). Never a multipart/chunk protocol (single PUT).
+   */
+  readonly blobUploadUrls?: BlobUploadPresignConfig;
+  /**
+   * §5.3 sqlite-image builder (TODO §4.2), injected so the pull path never
+   * statically imports `bun:sqlite`. Absent ⇒ the sqlite-image lane is off
+   * (bit-2 clients are served the rows lane) — the Workers/edge posture. A
+   * Bun/Node host wires `buildSqliteImage` from `@syncular/server`.
+   */
+  readonly sqliteImageBuilder?: SqliteImageBuilder;
+  readonly realtime?: RealtimeNotifier;
+  /**
+   * Optional structured-events sink (ops seam). Absent ⇒ zero cost: no
+   * event objects are built. A throwing sink never affects processing.
+   */
+  readonly events?: SyncularServerEvents;
+}
+
+/** Per-request context: the config plus host-authenticated identity. */
+export interface SyncRequestContext extends SyncServerConfig {
+  readonly partition: string;
+  readonly actorId: string;
+}
+
+export function clockOf(ctx: SyncServerConfig): () => number {
+  return ctx.clock ?? Date.now;
+}
+
+export function limitsOf(ctx: SyncServerConfig): ServerLimits {
+  return { ...DEFAULT_LIMITS, ...ctx.limits };
+}

package/src/crdt-merger.ts

@@ -0,0 +1,33 @@
+/**
+ * CRDT column merge registry (SPEC.md §5.10.2) — the pluggability seam.
+ *
+ * The server core NEVER depends on a CRDT library. A `crdt` column (§2.4
+ * tag 8) is merged server-side on push (§5.10.3) by a host-supplied
+ * `CrdtMerger`, selected per column by its schema-IR `crdtType` (§5.10.1).
+ * The reference `yjs-doc` merger lives in `@syncular/crdt-yjs`, keeping
+ * Yjs out of core/server (the blob-store placement rule, §5.9.2, applied to
+ * CRDT).
+ */
+
+/**
+ * Merge a `crdt` column's stored value with an incoming push value,
+ * returning the new stored bytes (§5.10.2). `stored` is `null` when the row
+ * is new or the column was NULL. Implementations MUST be commutative,
+ * associative, and idempotent over the updates they consume — the CRDT
+ * contract that makes concurrent-order-independent convergence and
+ * idempotent replay hold (§5.10.3).
+ *
+ * A synchronous return is fine; async is allowed so a native/WASM merger can
+ * cross an FFI boundary.
+ */
+export type CrdtMerger = (
+  stored: Uint8Array | null,
+  incoming: Uint8Array,
+) => Uint8Array | Promise<Uint8Array>;
+
+/**
+ * `crdtType` (§5.10.1) → merger. Supplied through `SyncServerConfig`
+ * (§ context). Absent ⇒ no column can CRDT-merge: a push touching a `crdt`
+ * column then fails `sync.crdt_merge_failed` (§5.10.2, §5.10.6).
+ */
+export type CrdtMergerRegistry = Readonly<Record<string, CrdtMerger>>;