@syncular/server 0.15.44 → 0.15.46

package/src/realtime.ts

@@ -31,7 +31,7 @@ import {
   type WakeReason,
 } from '@syncular/core';
 import type { SyncRequestContext, SyncServerConfig } from './context';
-import { RESOLVER_OUTAGE } from './context';
+import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE } from './context';
 import { SyncError, syncError } from './errors';
 import { emitEvent, type SyncularServerEvents } from './events';
 import { createSyncResponseStream } from './handler';
@@ -963,6 +963,12 @@ export class RealtimeHub {
   async connect(options: RealtimeConnectOptions): Promise<RealtimeSession> {
     const { storage } = this.#config;
     const clock = this.#config.clock ?? Date.now;
+    if (options.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
+      throw syncError(
+        'sync.invalid_client_id',
+        'clientId uses a reserved server-command namespace (§1.5)',
+      );
+    }
     const record = await storage.getClientRecord(
       options.partition,
       options.clientId,

package/src/relational-rows.ts

@@ -1,5 +1,5 @@
 /**
- * Relational current-row storage (DESIGN-relational-server-storage.md).
+ * Relational current-row storage.
  *
  * Every synced table is a REAL table in the server database — the app's
  * columns with proper type affinities, queryable with plain SQL/joins/BI —
@@ -65,7 +65,7 @@ export function quoteIdent(name: string): string {
   return `"${name.replaceAll('"', '""')}"`;
 }
 
-/** §5.3-style type affinities, per dialect (DESIGN type-mapping table). */
+/** §5.3-style type affinities, per dialect. */
 export function columnSqlType(
   column: RowColumn,
   dialect: RelationalDialect,
@@ -204,11 +204,11 @@ export function physicalIndexName(declaredName: string): string {
 }
 
 /**
- * CREATE INDEX IF NOT EXISTS for the table's user-declared indexes
- * (DESIGN "user indexes" — the same declared names/columns the client
- * materializes; cross-table index-name uniqueness is the user's schema
- * concern, exactly as it is client-side). Server-side the physical name
- * carries the {@link SYNC_INDEX_PREFIX} ownership marker.
+ * CREATE INDEX IF NOT EXISTS for the table's user-declared indexes. These use
+ * the same declared names and columns the client materializes. Cross-table
+ * index-name uniqueness is the user's schema concern, as it is client-side.
+ * Server-side the physical name carries the {@link SYNC_INDEX_PREFIX}
+ * ownership marker.
  */
 export function createIndexDdl(table: CompiledTable): string[] {
   // User indexes name app columns — nothing to index without the projection.
@@ -478,8 +478,8 @@ export function deleteRowSql(
 }
 
 /**
- * The schema-version marker table gating DDL work (DESIGN "server-side
- * schema migration"): `ensureSchema` compares the stored version and skips
+ * The schema-version marker table gates DDL work. `ensureSchema` compares the
+ * stored version and skips
  * all introspection/DDL when it matches — one cheap read per storage
  * instance (relevant for D1's per-request instantiation).
  *

package/src/s3-blob-store.ts

@@ -98,7 +98,7 @@ function parseStatsJson(json: string): StatsAccumulator {
   };
 }
 
-// Runtime-neutral base64url (TODO §4.2): `Buffer` is not present on
+// Runtime-neutral base64url: `Buffer` is not present on
 // Cloudflare Workers without `nodejs_compat`, so the metadata header is
 // (de)coded with `btoa`/`atob`, available in every runtime.
 function utf8ToBase64url(text: string): string {

package/src/s3-segment-store.ts

@@ -112,7 +112,7 @@ function parseStatsJson(json: string): StatsAccumulator {
   };
 }
 
-// Runtime-neutral base64url (TODO §4.2): `Buffer` is not present on
+// Runtime-neutral base64url: `Buffer` is not present on
 // Cloudflare Workers without `nodejs_compat`, so the object-metadata record
 // header is (de)coded with `btoa`/`atob`, available in every runtime.
 function utf8ToBase64url(text: string): string {

package/src/schema.ts

@@ -3,7 +3,7 @@
  *
  * The server is configured with a schema IR: tables, columns with the six
  * §2.4 column types, scope patterns per §3.1, and a schema version. Codegen
- * (B5) will emit this shape later; tests hand-write it.
+ * Typegen emits this shape; tests hand-write it.
  */
 import {
   type RowColumn,
@@ -14,9 +14,8 @@ import {
 export type ScopePatternSpec = string | { pattern: string; column: string };
 
 /**
- * A user-declared index (the migration subset's CREATE INDEX). With
- * relational server storage these apply server-side too (DESIGN
- * "user indexes") — the same declaration the client materializes.
+ * A user-declared index (the migration subset's CREATE INDEX). Relational
+ * server storage applies the same declaration the client materializes.
  */
 export interface IndexSchema {
   readonly name: string;
@@ -35,7 +34,7 @@ export interface TableSchema {
   /** User indexes (optional) — created on the server's relational tables. */
   readonly indexes?: readonly IndexSchema[];
   /**
-   * Server-side column materialization (DESIGN-relational-server-storage.md
+   * Server-side column materialization
    * "optional materialization"). When `true` (the usual default) the server's
    * row table carries the app's typed columns as a queryable projection;
    * when `false` it carries only the `_sync_*` meta columns — same storage
@@ -142,8 +141,8 @@ export function compileSchema(schema: ServerSchema): CompiledSchema {
     if (tables.has(table.name)) {
       throw new Error(`duplicate table ${JSON.stringify(table.name)}`);
     }
-    // Identifier rules (DESIGN "current-row tables") live in core's
-    // validatePortableRelationalIdentifier, shared with typegen: app tables
+    // Identifier rules live in core's validatePortableRelationalIdentifier,
+    // shared with typegen: app tables
     // share a namespace with the sync infrastructure tables (`sync_*`) and
     // carry `_sync_*` meta columns, so both prefixes are reserved, and
     // Postgres silently truncates identifiers over 63 bytes.

package/src/seed.ts

@@ -1,5 +1,5 @@
 /**
- * The public seeding helper (RFC 0002 §2.5): push app-shaped mutations
+ * The public seeding helper: push app-shaped mutations
  * through the REAL push path — one `handleSyncRequest` round built from the
  * server schema — so demos, dev servers, and ops scripts seed data with one
  * supported call. This is the same §6 pipeline every client write takes

package/src/segment-store.ts

@@ -44,8 +44,8 @@ export interface SegmentFindKey {
 }
 
 /**
- * Coarse store-level counters for the admin/console read surface (TODO
- * §2.5). Optional — a store that omits `stats()` simply cannot report them.
+ * Coarse store-level counters for the admin/console read surface. Optional:
+ * a store that omits `stats()` simply cannot report them.
  * All counts include expired-but-not-yet-evicted entries (the store's own
  * bytes on disk), split by media type.
  */
@@ -80,7 +80,7 @@ export interface SegmentStore {
    * rebuilding sqlite images while one exists (§5.3).
    */
   find(key: SegmentFindKey, nowMs: number): Promise<SegmentRecord | undefined>;
-  /** Admin/console counters (TODO §2.5) — ADDITIVE, optional. */
+  /** Admin/console counters: ADDITIVE, optional. */
   stats?(): Promise<SegmentStoreStats>;
 }
 

package/src/signed-url.ts

@@ -198,8 +198,8 @@ export interface SegmentTokenClaims {
 
 const encoder = new TextEncoder();
 
-// Runtime-neutral base64url (no `Buffer` — Workers/Deno/browser safe; TODO
-// §4.2): `btoa`/`atob` operate on binary strings, present in every runtime.
+// Runtime-neutral base64url: `btoa`/`atob` operate on binary strings and are
+// present in every supported runtime.
 function base64url(bytes: Uint8Array): string {
   let binary = '';
   for (const byte of bytes) binary += String.fromCharCode(byte);

package/src/sigv4.ts

@@ -1,10 +1,10 @@
 /**
  * Minimal AWS Signature Version 4 — exactly the subset the S3 segment
  * store needs (header-signed requests and presigned GET URLs), hand-rolled
- * per the dependency-light doctrine (REVISE): SigV4 is small and
+ * per the dependency-light doctrine: SigV4 is small and
  * well-specified, so no SDK.
  *
- * Runtime-neutral (TODO §4.2): the crypto primitives are Web Crypto
+ * Runtime-neutral: the crypto primitives are Web Crypto
  * (`crypto.subtle`), not `node:crypto`, so this module runs unchanged on
  * Cloudflare Workers / Deno / browsers as well as Bun/Node. `crypto.subtle`
  * is async, so signing is async throughout; the `S3SegmentStore` consumers
@@ -94,9 +94,7 @@ export function amzTimestamps(nowMs: number): {
 }
 
 /** Sorted, fully re-encoded canonical query string from *decoded* pairs. */
-export function canonicalQuery(
-  params: Iterable<readonly [string, string]>,
-): string {
+function canonicalQuery(params: Iterable<readonly [string, string]>): string {
   return [...params]
     .map(([k, v]) => [uriEncode(k, true), uriEncode(v, true)] as const)
     .sort(([ak, av], [bk, bv]) =>

package/src/sqlite-blob-store.ts

@@ -3,7 +3,7 @@
  * dependency-free). Bun-specific by design (top-level `bun:sqlite` import),
  * so it lives in its own module — the runtime-neutral `BlobStore` interface,
  * `MemoryBlobStore`, `blobIdFor`, and `isBlobId` stay in `blob-store.ts` for
- * the Workers/edge core (TODO §4.2 neutrality discipline; enforced by
+ * the Workers/edge core (runtime neutrality is enforced by
  * `test/runtime-neutrality.test.ts`).
  */
 import { Database } from 'bun:sqlite';

package/src/sqlite-dialect.ts

@@ -11,8 +11,7 @@
  * db.prepare(sql).bind(...).all()`); a shared execution layer would have to
  * pick one calling convention and adapt the other, which is uglier than two
  * thin storage classes that each speak their driver's native shape while
- * importing the same SQL text and codecs from here (TODO §4.2 judgment
- * call — "clean parallel implementation against the storage contract").
+ * importing the same SQL text and codecs from here.
  * Both classes run the identical `test/storage-contract.ts`, so the
  * behavior is held key-for-key regardless.
  */
@@ -35,7 +34,7 @@ import type {
  * The inverted scope index carries the ordered column (`commit_seq` /
  * `row_id`) last in the PRIMARY KEY, so the candidate scan is an index
  * range that returns already-ordered rows — the same covering-index shape
- * the Postgres storage documents (§3.1, REVISE B2 performance-by-
+ * the Postgres storage documents (§3.1, performance-by-
  * construction).
  */
 export const SQLITE_DDL = `
@@ -75,6 +74,26 @@ CREATE TABLE IF NOT EXISTS sync_push_results(
   client_commit_id TEXT NOT NULL, result TEXT NOT NULL,
   PRIMARY KEY(partition, client_id, client_commit_id)
 );
+CREATE TABLE IF NOT EXISTS sync_reactions(
+  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,
+  type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,
+  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,
+  source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,
+  available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,
+  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,
+  lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,
+  last_failure TEXT,
+  PRIMARY KEY(partition, idempotency_key),
+  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))
+);
+CREATE INDEX IF NOT EXISTS sync_reactions_due
+  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);
+CREATE INDEX IF NOT EXISTS sync_reactions_lease
+  ON sync_reactions(partition, status, lease_expires_at_ms);
+CREATE INDEX IF NOT EXISTS sync_reactions_completed
+  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);
+CREATE INDEX IF NOT EXISTS sync_reactions_dead_letter
+  ON sync_reactions(partition, status, available_at_ms, idempotency_key);
 CREATE TABLE IF NOT EXISTS sync_clients(
   partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,
   cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,

package/src/sqlite-image.ts

@@ -62,7 +62,7 @@ export interface SqliteImageInput {
 
 /**
  * The §5.3 image-builder capability, injected through
- * `SyncServerConfig.sqliteImageBuilder` (TODO §4.2). Building an image needs
+ * `SyncServerConfig.sqliteImageBuilder`. Building an image needs
  * a real SQLite engine (`bun:sqlite` here), which is not available on every
  * runtime — Cloudflare Workers has none. So the core takes the builder as an
  * optional capability rather than importing `bun:sqlite` on the pull path:

package/src/sqlite-lease-store.ts

@@ -3,7 +3,7 @@
  * dependency-free). Bun-specific by design (top-level `bun:sqlite` import),
  * so it lives in its own module — the runtime-neutral `LeaseStore` interface,
  * `LeaseRecord`, and `MemoryLeaseStore` stay in `lease-store.ts` for the
- * Workers/edge core (TODO §4.2 neutrality discipline; enforced by
+ * Workers/edge core (runtime neutrality is enforced by
  * `test/runtime-neutrality.test.ts`).
  */
 import { Database } from 'bun:sqlite';

package/src/sqlite-segment-store.ts

@@ -4,8 +4,8 @@
  * top level, so it lives in its own module — importing it opts into the Bun
  * runtime. The runtime-neutral `SegmentStore` interface, `MemorySegmentStore`,
  * and `segmentIdFor` stay in `segment-store.ts` so the Workers/edge core can
- * import them without pulling in `bun:sqlite` (TODO §4.2 neutrality
- * discipline; enforced by `test/runtime-neutrality.test.ts`).
+ * import them without pulling in `bun:sqlite` (runtime neutrality is enforced
+ * by `test/runtime-neutrality.test.ts`).
  */
 import { Database } from 'bun:sqlite';
 import {