@syncular/server 0.1.3 → 0.2.0

package/dist/blob-store.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Content-addressed blob store (SPEC.md §5.9.2).
+ *
+ * Blobs are the file-attachment bytes a row references through a `blob_ref`
+ * column (§2.4 tag 7). Unlike segments (§5.1 TTL cache entries), blobs are
+ * **durable**: a blob referenced by a live row must stay downloadable
+ * indefinitely (§5.9.5 B3). The store is keyed by `blobId`
+ * (`"sha256:" + hex`), shares the S3/R2 backend and presign machinery with
+ * segments, and exposes an orphan sweep (§5.9.2) rather than row-tied
+ * deletion.
+ */
+import { type SyncularServerEvents } from './events.js';
+import type { ServerStorage } from './storage.js';
+export interface BlobRecord {
+    readonly blobId: string;
+    readonly partition: string;
+    readonly byteLength: number;
+    /** Advisory MIME type persisted from the upload, if any (§5.9.5). */
+    readonly mediaType?: string;
+    readonly createdAtMs: number;
+}
+/**
+ * Coarse blob-store counters for the admin/console read surface (TODO
+ * §2.5), partition-scoped. Optional. `count`/`bytes` are total stored
+ * blobs; a store that omits `stats()` cannot report them.
+ */
+export interface BlobStoreStats {
+    readonly count: number;
+    readonly bytes: number;
+    /**
+     * ADDITIVE marker — present and `true` only on stores whose counters are
+     * approximate (a LIST-free S3/R2 accumulator). Absent on the exact
+     * in-process stores (memory/sqlite). The admin surface carries it through.
+     */
+    readonly approximate?: boolean;
+}
+export interface BlobStore {
+    /**
+     * Store blob bytes under `blobId` (idempotent — same id ⇒ no-op success,
+     * §5.9.3). The caller has already verified the content address matches.
+     */
+    put(partition: string, blobId: string, bytes: Uint8Array, nowMs: number, mediaType?: string): Promise<BlobRecord>;
+    /** Presence check for the push existence rule (§5.9.6) and download. */
+    has(partition: string, blobId: string): Promise<boolean>;
+    get(partition: string, blobId: string): Promise<{
+        record: BlobRecord;
+        bytes: Uint8Array;
+    } | undefined>;
+    /**
+     * §5.9.2 orphan sweep: delete blobs uploaded before `olderThanMs` that
+     * no live row references. The set of referenced blobIds is supplied by
+     * the storage reference index — the store never scans rows itself.
+     * Returns the deleted blobIds.
+     */
+    sweepOrphans(partition: string, olderThanMs: number, referencedBlobIds: ReadonlySet<string>): Promise<string[]>;
+    /** Admin/console counters (TODO §2.5) — ADDITIVE, optional. */
+    stats?(partition: string): Promise<BlobStoreStats>;
+}
+/** `"sha256:" + hex` of the bytes — the content address (§5.9.1). */
+export declare function blobIdFor(bytes: Uint8Array): Promise<string>;
+export declare function isBlobId(value: string): boolean;
+export declare class MemoryBlobStore implements BlobStore {
+    #private;
+    put(partition: string, blobId: string, bytes: Uint8Array, nowMs: number, mediaType?: string): Promise<BlobRecord>;
+    has(partition: string, blobId: string): Promise<boolean>;
+    get(partition: string, blobId: string): Promise<{
+        record: BlobRecord;
+        bytes: Uint8Array;
+    } | undefined>;
+    sweepOrphans(partition: string, olderThanMs: number, referencedBlobIds: ReadonlySet<string>): Promise<string[]>;
+    stats(partition: string): Promise<BlobStoreStats>;
+}
+export interface SweepOrphanBlobsOptions {
+    /**
+     * Grace period: a blob uploaded within the last `graceMs` is NEVER swept,
+     * even if unreferenced. This is the whole protection for the §5.9.2
+     * upload-before-reference race — a fresh upload is legitimately
+     * unreferenced until its push lands, so the grace MUST comfortably exceed
+     * any sane upload→push latency. Default 24 h (well above any push window).
+     */
+    readonly graceMs?: number;
+    /** Sweep clock (epoch ms); defaults to `Date.now`. */
+    readonly nowMs?: number;
+    /** Optional structured-events sink (`blob.swept`). */
+    readonly events?: SyncularServerEvents;
+}
+export interface SweepOrphanBlobsResult {
+    readonly partition: string;
+    readonly swept: string[];
+    readonly referencedCount: number;
+}
+/**
+ * §5.9.2 orphan sweep — the ready-made GC helper. Reads the live keep-set
+ * (`storage.listReferencedBlobIds`) and hands it, with the grace cutoff, to
+ * `blobStore.sweepOrphans`, which deletes only blobs BOTH unreferenced AND
+ * older than the grace period. Returns the swept ids and emits one
+ * `blob.swept` ops event.
+ *
+ * The upload-before-reference race, stated honestly: a client uploads bytes
+ * before pushing the row that references them (§5.9.2), so a just-uploaded
+ * blob is unreferenced until its push arrives. The grace period is the ONLY
+ * thing standing between that fresh blob and deletion — keep it far above any
+ * push latency (the 24 h default is deliberately generous). The store's
+ * `createdAtMs` (object metadata) is the upload time the cutoff compares
+ * against.
+ *
+ * Requires `storage.listReferencedBlobIds` (the §5.9.4 reference index). A
+ * storage backend without it cannot be swept safely — this throws rather
+ * than sweeping against an empty keep-set (which would delete everything).
+ */
+export declare function sweepOrphanBlobs(storage: ServerStorage, blobStore: BlobStore, partition: string, options?: SweepOrphanBlobsOptions): Promise<SweepOrphanBlobsResult>;

package/dist/content-encoding.d.ts

@@ -0,0 +1,27 @@
+/**
+ * §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';
+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 declare function encodeSegmentBody(bytes: Uint8Array, acceptEncoding: string | undefined): EncodedSegmentBody;

package/dist/content-encoding.js

@@ -0,0 +1,69 @@
+/**
+ * §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.
+ */
+/** Preference order is zstd, gzip (§5.8). Non-Bun runtimes without these
+ * codecs serve identity — negotiation, never a hard requirement here. */
+function detectCodecs() {
+    const bun = globalThis.Bun;
+    const codecs = [];
+    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, encoding) {
+    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;
+}
+/**
+ * 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, acceptEncoding) {
+    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/dist/context.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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.js';
+import type { CrdtMergerRegistry } from './crdt-merger.js';
+import type { SyncularServerEvents } from './events.js';
+import type { LeaseStore } from './lease-store.js';
+import type { ServerSchema } from './schema.js';
+import type { SegmentStore } from './segment-store.js';
+import type { BlobPresignConfig, BlobUploadPresignConfig, SegmentUrlConfig } from './signed-url.js';
+import type { SqliteImageBuilder } from './sqlite-image.js';
+import type { ServerStorage, StoredCommit } from './storage.js';
+import type { ValidatorRegistry } from './validate.js';
+/** SSP2 body content type (§1.1). */
+export declare 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 declare const RESOLVER_OUTAGE: unique symbol;
+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 declare const DEFAULT_LIMITS: ServerLimits;
+/** 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 declare function clockOf(ctx: SyncServerConfig): () => number;
+export declare function limitsOf(ctx: SyncServerConfig): ServerLimits;

package/dist/context.js

@@ -0,0 +1,21 @@
+/** SSP2 body content type (§1.1). */
+export const SSP2_CONTENT_TYPE = 'application/vnd.syncular.sync.v2';
+/**
+ * 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 const DEFAULT_LIMITS = {
+    maxOperationsPerRequest: 500,
+    inlineSegmentMaxBytes: 256 * 1024,
+};
+export function clockOf(ctx) {
+    return ctx.clock ?? Date.now;
+}
+export function limitsOf(ctx) {
+    return { ...DEFAULT_LIMITS, ...ctx.limits };
+}

package/dist/crdt-merger.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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>>;

package/dist/crdt-merger.js

@@ -0,0 +1,11 @@
+/**
+ * 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).
+ */
+export {};

package/dist/d1-storage.d.ts

@@ -0,0 +1,50 @@
+import type { CompiledSchema, CompiledTable } from './schema.js';
+import type { ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredRow } from './storage.js';
+export interface D1PreparedStatement {
+    bind(...values: unknown[]): D1PreparedStatement;
+    first<T = Record<string, unknown>>(): Promise<T | null>;
+    all<T = Record<string, unknown>>(): Promise<{
+        results: T[];
+    }>;
+    run(): Promise<unknown>;
+}
+export interface D1Database {
+    prepare(query: string): D1PreparedStatement;
+    batch(statements: D1PreparedStatement[]): Promise<unknown[]>;
+    exec(query: string): Promise<unknown>;
+}
+export declare class D1ServerStorage implements ServerStorage {
+    #private;
+    constructor(db: D1Database);
+    /** Apply the schema DDL (idempotent). Call once before use. */
+    migrate(): Promise<void>;
+    /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
+    table(name: string): CompiledTable;
+    ensureSchema(schema: CompiledSchema): Promise<void>;
+    begin(partition: string): Promise<StorageTransaction>;
+    getMaxCommitSeq(partition: string): Promise<number>;
+    getHorizonSeq(partition: string): Promise<number>;
+    setHorizonSeq(partition: string, seq: number): Promise<void>;
+    pruneCommitsThrough(partition: string, seq: number): Promise<number>;
+    getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
+    getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
+    getPushResult(partition: string, clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
+    readCommitWindow(partition: string, query: CommitWindowQuery): Promise<StoredCommit[]>;
+    scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
+    getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
+    putClientRecord(partition: string, record: ClientRecord): Promise<void>;
+    listClientCursors(partition: string): Promise<ClientCursorInfo[]>;
+    listRowsReferencingBlob(partition: string, blobId: string): Promise<{
+        readonly table: string;
+        readonly rowId: string;
+        readonly scopes: Record<string, string>;
+    }[]>;
+    listReferencedBlobIds(partition: string): Promise<string[]>;
+    listClientRecords(partition: string): Promise<ClientRecord[]>;
+    listCommitMetadata(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
+    scopeActivity(partition: string, query: ScopeActivityQuery): Promise<ScopeCommitActivity[]>;
+    getRowScopes(partition: string, table: string, rowId: string): Promise<{
+        serverVersion: number;
+        scopes: Record<string, string>;
+    } | undefined>;
+}

package/dist/errors.d.ts

@@ -1,10 +1,36 @@
-export declare class SyncClientSchemaUnsupportedError extends Error {
-    readonly code: 'sync.client_schema_unsupported';
-    readonly schemaVersion: number | null;
-    readonly supportedSchemaVersions: readonly number[];
-    constructor(options: {
-        schemaVersion: number | null | undefined;
-        supportedSchemaVersions: readonly number[];
-    });
+/**
+ * Server-side protocol errors (SPEC.md §10).
+ *
+ * Every request-level failure raised by the server core is a `SyncError`
+ * carrying the fixed catalog metadata of §10.2 (`category`, `retryable`,
+ * `recommendedAction`) plus an HTTP status for transport adapters. The
+ * catalog is closed: creating a `SyncError` with an unknown code throws.
+ */
+export interface ErrorCatalogEntry {
+    readonly category: string;
+    readonly retryable: boolean;
+    readonly recommendedAction: string;
+    readonly httpStatus: number;
 }
-//# sourceMappingURL=errors.d.ts.map
+/** The §10.2 wire catalog (21 sync.* + 4 blob.* codes), keyed by stable code. */
+export declare const ERROR_CATALOG: Readonly<Record<string, ErrorCatalogEntry>>;
+export declare class SyncError extends Error {
+    readonly name = "SyncError";
+    readonly code: string;
+    readonly category: string;
+    readonly retryable: boolean;
+    readonly recommendedAction: string;
+    readonly httpStatus: number;
+    readonly details?: string;
+    constructor(code: string, message?: string, details?: string);
+}
+export declare function syncError(code: string, message?: string, details?: string): SyncError;
+/** The §10.1 JSON error shape, for HTTP-level error bodies (§1.1). */
+export declare function errorBody(error: SyncError): {
+    code: string;
+    category: string;
+    retryable: boolean;
+    recommendedAction: string;
+    message: string;
+    details?: unknown;
+};