@syncular/server 0.15.44 → 0.15.46

package/src/authoritative-query.ts

@@ -0,0 +1,218 @@
+import type { CompiledTable } from './schema';
+import { quoteIdent, SYNC_PARTITION_COLUMN } from './relational-rows';
+import type { AuthoritativeQueryValue } from './storage';
+
+export interface PreparedAuthoritativeQuery {
+  readonly sql: string;
+  readonly params: readonly (AuthoritativeQueryValue | typeof PARTITION_BIND)[];
+}
+
+export interface BoundAuthoritativeQuery {
+  readonly sql: string;
+  readonly params: readonly AuthoritativeQueryValue[];
+}
+
+const PARTITION_BIND = Symbol('syncular.authoritative_partition');
+
+const RESERVED_ALIAS = new Set([
+  'on',
+  'where',
+  'group',
+  'order',
+  'inner',
+  'left',
+  'right',
+  'full',
+  'outer',
+  'natural',
+  'join',
+  'cross',
+  'using',
+  'limit',
+  'having',
+]);
+const IDENT = '[A-Za-z_][A-Za-z0-9_]*';
+const TABLE_REF_RE = new RegExp(
+  `\\b(FROM|(?:NATURAL\\s+)?(?:(?:LEFT|RIGHT|FULL)(?:\\s+OUTER)?|INNER|CROSS)?\\s*JOIN)\\s+((?:\\(\\s*)*)(${IDENT})(?:\\s+(?:AS\\s+)?((?!(?:${[...RESERVED_ALIAS].join('|')})\\b)${IDENT}))?`,
+  'gi',
+);
+
+function protectedSqlEnd(sql: string, index: number): number | undefined {
+  const char = sql[index];
+  const next = sql[index + 1];
+  if (char === "'" || char === '"' || char === '`') {
+    let end = index + 1;
+    while (end < sql.length) {
+      if (sql[end] === char && sql[end + 1] === char) end += 2;
+      else if (sql[end] === char) return end + 1;
+      else end += 1;
+    }
+    return sql.length;
+  }
+  if (char === '[') {
+    const end = sql.indexOf(']', index + 1);
+    return end < 0 ? sql.length : end + 1;
+  }
+  if (char === '-' && next === '-') {
+    const end = sql.indexOf('\n', index);
+    return end < 0 ? sql.length : end;
+  }
+  if (char === '/' && next === '*') {
+    const end = sql.indexOf('*/', index + 2);
+    return end < 0 ? sql.length : end + 2;
+  }
+  return undefined;
+}
+
+function maskedSql(sql: string): string {
+  let out = '';
+  let index = 0;
+  while (index < sql.length) {
+    const end = protectedSqlEnd(sql, index);
+    if (end === undefined) out += sql[index];
+    else out += sql.slice(index, end).replace(/[^\n]/g, ' ');
+    index = end ?? index + 1;
+  }
+  return out;
+}
+
+/**
+ * Turn generated local SQL into a partition-local authoritative statement.
+ * Only relations declared by the generated descriptor are rewritten. Values
+ * remain parameters; request data is never interpolated into SQL.
+ */
+export function prepareAuthoritativeQuery(
+  sql: string,
+  params: readonly AuthoritativeQueryValue[],
+  declaredTables: readonly string[],
+  tables: ReadonlyMap<string, CompiledTable>,
+): PreparedAuthoritativeQuery {
+  if (maskedSql(sql).includes(';'))
+    throw new Error('registered query must be one SELECT');
+  const declared = new Set(declaredTables);
+  const masked = maskedSql(sql);
+  const replacements: Array<{
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+  }> = [];
+  const found = new Set<string>();
+  for (const match of masked.matchAll(TABLE_REF_RE)) {
+    const rawTable = match[3] as string;
+    const table = tables.get(rawTable);
+    if (table === undefined) continue;
+    if (!declared.has(table.name)) {
+      throw new Error('registered query table metadata does not match its SQL');
+    }
+    if (!table.materialize) {
+      throw new Error('registered query targets a non-materialized table');
+    }
+    let alias = match[4];
+    if (alias !== undefined && RESERVED_ALIAS.has(alias.toLowerCase())) {
+      alias = undefined;
+    }
+    const matchStart = match.index ?? 0;
+    const afterOperator = (match[1] as string).length;
+    const relative = match[0]
+      .toLowerCase()
+      .indexOf(rawTable.toLowerCase(), afterOperator);
+    const start = matchStart + relative;
+    const projection = table.columns.map((column) => quoteIdent(column.name));
+    replacements.push({
+      start,
+      end: start + rawTable.length,
+      text: `(SELECT ${projection.join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=/*syncular_partition*/?)${alias === undefined ? ` AS ${quoteIdent(table.name)}` : ''}`,
+    });
+    found.add(table.name);
+  }
+  if (
+    found.size !== declared.size ||
+    [...declared].some((table) => !found.has(table))
+  ) {
+    throw new Error('registered query table metadata does not match its SQL');
+  }
+  let rewritten = sql;
+  for (const replacement of replacements.sort(
+    (left, right) => right.start - left.start,
+  )) {
+    rewritten =
+      rewritten.slice(0, replacement.start) +
+      replacement.text +
+      rewritten.slice(replacement.end);
+  }
+
+  const bound: (AuthoritativeQueryValue | typeof PARTITION_BIND)[] = [];
+  let anonymousIndex = 0;
+  let rendered = '';
+  for (let index = 0; index < rewritten.length; index += 1) {
+    if (rewritten.startsWith('/*syncular_partition*/?', index)) {
+      rendered += '?';
+      bound.push(PARTITION_BIND);
+      index += '/*syncular_partition*/?'.length - 1;
+      continue;
+    }
+    const protectedEnd = protectedSqlEnd(rewritten, index);
+    if (protectedEnd !== undefined) {
+      rendered += rewritten.slice(index, protectedEnd);
+      index = protectedEnd - 1;
+      continue;
+    }
+    const char = rewritten[index] as string;
+    if (char !== '?') {
+      rendered += char;
+      continue;
+    }
+    let end = index + 1;
+    while (end < rewritten.length && /[0-9]/.test(rewritten[end] as string)) {
+      end += 1;
+    }
+    const numbered = rewritten.slice(index + 1, end);
+    const parameterIndex =
+      numbered.length > 0
+        ? Number.parseInt(numbered, 10) - 1
+        : anonymousIndex++;
+    if (numbered.length > 0) {
+      anonymousIndex = Math.max(anonymousIndex, parameterIndex + 1);
+    }
+    if (parameterIndex < 0 || parameterIndex >= params.length) {
+      throw new Error('registered query bind metadata does not match its SQL');
+    }
+    const value = params[parameterIndex];
+    if (value === undefined) {
+      throw new Error('registered query bind metadata does not match its SQL');
+    }
+    rendered += '?';
+    bound.push(value);
+    index = end - 1;
+  }
+  return { sql: rendered, params: bound };
+}
+
+export function bindAuthoritativePartition(
+  prepared: PreparedAuthoritativeQuery,
+  partition: string,
+): BoundAuthoritativeQuery {
+  return {
+    sql: prepared.sql,
+    params: prepared.params.map((value) =>
+      value === PARTITION_BIND ? partition : value,
+    ),
+  };
+}
+
+export function postgresPlaceholders(sql: string): string {
+  let bind = 0;
+  let rendered = '';
+  for (let index = 0; index < sql.length; index += 1) {
+    const protectedEnd = protectedSqlEnd(sql, index);
+    if (protectedEnd !== undefined) {
+      rendered += sql.slice(index, protectedEnd);
+      index = protectedEnd - 1;
+    } else if (sql[index] === '?') {
+      rendered += `$${++bind}`;
+    } else {
+      rendered += sql[index];
+    }
+  }
+  return rendered;
+}

package/src/context.ts

@@ -1,5 +1,5 @@
 /**
- * The host context for `handleSyncRequest` (REVISE B2): storage, the
+ * The host context for `handleSyncRequest`: 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).
@@ -9,6 +9,7 @@ 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 { AnyReactionPlanner } from './reactions';
 import type { ServerSchema } from './schema';
 import type { SegmentStore } from './segment-store';
 import type {
@@ -23,6 +24,9 @@ import type { CommitValidator, ValidatorRegistry } from './validate';
 /** SSP2 body content type (§1.1). */
 export const SSP2_CONTENT_TYPE = 'application/vnd.syncular.sync.v2';
 
+/** Internal idempotency namespace. Ordinary SSP2 client IDs cannot use it. */
+export const REMOTE_COMMAND_CLIENT_ID_PREFIX = '["remote-command",';
+
 export interface ResolveScopesArgs {
   readonly partition: string;
   readonly actorId: string;
@@ -119,6 +123,12 @@ export interface SyncServerConfig {
    * commit-log/idempotency append. A throw rolls back the complete commit.
    */
   readonly commitValidator?: CommitValidator;
+  /**
+   * Pure durable-reaction planner. Runs once after candidate validation and
+   * before commit-log/idempotency append. Its bounded records are enqueued in
+   * the same transaction; handlers run later through `ReactionRunner`.
+   */
+  readonly reactionPlanner?: AnyReactionPlanner;
   readonly resolveScopes: ResolveScopes;
   /**
    * §7.3 auth leases. Absent ⇒ the feature is off: no `LEASE` frame is
@@ -154,7 +164,7 @@ export interface SyncServerConfig {
    */
   readonly blobUploadUrls?: BlobUploadPresignConfig;
   /**
-   * §5.3 sqlite-image builder (TODO §4.2), injected so the pull path never
+   * §5.3 sqlite-image builder, 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`.

package/src/d1-storage.ts

@@ -1,5 +1,5 @@
 /**
- * Cloudflare D1 server storage (TODO §4.2 — the Workers deployment rung).
+ * Cloudflare D1 server storage for Workers deployments.
  *
  * D1 *is* SQLite exposed over an async, statement-at-a-time API
  * (`prepare(sql).bind(...).all()` / `.first()` / `.run()`, plus `batch([…])`
@@ -40,6 +40,10 @@
  * rather than a lock D1 does not expose.
  */
 import { decodeRow, type RowValue } from '@syncular/core';
+import {
+  bindAuthoritativePartition,
+  prepareAuthoritativeQuery,
+} from './authoritative-query';
 import { syncError } from './errors';
 import {
   commitWindowPageSql,
@@ -79,14 +83,24 @@ import {
   toStoredRow,
 } from './sqlite-dialect';
 import type {
+  AuthoritativeQueryRequest,
+  AuthoritativeQueryResult,
   ClientCursorInfo,
   ClientRecord,
   ClientSubscription,
   CommitMetadata,
   CommitMetadataQuery,
   CommitWindowQuery,
+  DurableJsonValue,
   IndexRowScanQuery,
   NewCommit,
+  NewReaction,
+  PrunedReactionCounts,
+  ReactionClaimQuery,
+  ReactionFailure,
+  ReactionFailureUpdate,
+  ReactionListQuery,
+  ReactionPruneQuery,
   RowScanQuery,
   ScopeActivityQuery,
   ScopeCommitActivity,
@@ -94,6 +108,7 @@ import type {
   StorageTransaction,
   StoredCommit,
   StoredPushResult,
+  StoredReaction,
   StoredRow,
 } from './storage';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors';
@@ -122,6 +137,52 @@ interface BufferedStatement {
   readonly params: readonly unknown[];
 }
 
+interface D1ReactionRecord {
+  idempotency_key: string;
+  type: string;
+  version: number;
+  payload: string;
+  source_client_id: string;
+  source_client_commit_id: string;
+  source_commit_seq: number;
+  created_at_ms: number;
+  available_at_ms: number;
+  status: StoredReaction['status'];
+  attempts: number;
+  max_attempts: number;
+  lease_owner: string | null;
+  lease_expires_at_ms: number | null;
+  completed_at_ms: number | null;
+  last_failure: string | null;
+}
+
+function toStoredReaction(record: D1ReactionRecord): StoredReaction {
+  return {
+    idempotencyKey: record.idempotency_key,
+    type: record.type,
+    version: record.version,
+    payload: JSON.parse(record.payload) as DurableJsonValue,
+    sourceClientId: record.source_client_id,
+    sourceClientCommitId: record.source_client_commit_id,
+    sourceCommitSeq: record.source_commit_seq,
+    createdAtMs: record.created_at_ms,
+    maxAttempts: record.max_attempts,
+    status: record.status,
+    attempts: record.attempts,
+    availableAtMs: record.available_at_ms,
+    ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
+    ...(record.lease_expires_at_ms !== null
+      ? { leaseExpiresAtMs: record.lease_expires_at_ms }
+      : {}),
+    ...(record.completed_at_ms !== null
+      ? { completedAtMs: record.completed_at_ms }
+      : {}),
+    ...(record.last_failure !== null
+      ? { lastFailure: JSON.parse(record.last_failure) as ReactionFailure }
+      : {}),
+  };
+}
+
 function relationalValuesEqual(left: RowValue, right: RowValue): boolean {
   if (left instanceof Uint8Array && right instanceof Uint8Array) {
     return (
@@ -588,6 +649,32 @@ class D1Transaction implements StorageTransaction {
     );
   }
 
+  async enqueueReactions(reactions: readonly NewReaction[]): Promise<void> {
+    this.#assertOpen();
+    for (const reaction of reactions) {
+      this.#buffer_(
+        `INSERT INTO sync_reactions(
+           partition, idempotency_key, type, version, payload,
+           source_client_id, source_client_commit_id, source_commit_seq,
+           created_at_ms, available_at_ms, status, attempts, max_attempts
+         ) VALUES (?,?,?,?,?,?,?,?,?,?,'pending',0,?)`,
+        [
+          this.#partition,
+          reaction.idempotencyKey,
+          reaction.type,
+          reaction.version,
+          JSON.stringify(reaction.payload),
+          reaction.sourceClientId,
+          reaction.sourceClientCommitId,
+          reaction.sourceCommitSeq,
+          reaction.createdAtMs,
+          reaction.createdAtMs,
+          reaction.maxAttempts,
+        ],
+      );
+    }
+  }
+
   async commit(): Promise<void> {
     this.#assertOpen();
     if (this.#buffer.length === 0) {
@@ -687,7 +774,7 @@ export class D1ServerStorage implements ServerStorage {
       const bindCount = tableColumnNames(table).length;
       if (bindCount > D1_MAX_BIND_PARAMS) {
         throw new Error(
-          `table ${JSON.stringify(table.name)} needs ${bindCount} bound parameters per upsert — D1 caps statements at ${D1_MAX_BIND_PARAMS} (DESIGN "D1 bind-parameter limit")`,
+          `table ${JSON.stringify(table.name)} needs ${bindCount} bound parameters per upsert; D1 caps statements at ${D1_MAX_BIND_PARAMS}`,
         );
       }
     }
@@ -831,6 +918,61 @@ export class D1ServerStorage implements ServerStorage {
     return row?.max_commit_seq ?? 0;
   }
 
+  async queryAuthoritative(
+    partition: string,
+    query: AuthoritativeQueryRequest,
+  ): Promise<AuthoritativeQueryResult> {
+    if (this.#tables === undefined) {
+      throw new Error(
+        'ensureSchema(schema) must run before registered queries',
+      );
+    }
+    const prepared = bindAuthoritativePartition(
+      prepareAuthoritativeQuery(
+        query.sql,
+        query.params,
+        query.tables,
+        this.#tables,
+      ),
+      partition,
+    );
+    const results = await this.#db.batch([
+      this.#db.prepare(prepared.sql).bind(...prepared.params),
+      this.#db
+        .prepare('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
+        .bind(partition),
+    ]);
+    const rowsResult = results[0];
+    const cursorResult = results[1];
+    if (
+      typeof rowsResult !== 'object' ||
+      rowsResult === null ||
+      !('results' in rowsResult) ||
+      !Array.isArray(rowsResult.results) ||
+      typeof cursorResult !== 'object' ||
+      cursorResult === null ||
+      !('results' in cursorResult) ||
+      !Array.isArray(cursorResult.results)
+    ) {
+      throw new Error('D1 registered query returned an invalid batch result');
+    }
+    const cursor = cursorResult.results[0];
+    const maxCommitSeq =
+      typeof cursor === 'object' &&
+      cursor !== null &&
+      'max_commit_seq' in cursor &&
+      typeof cursor.max_commit_seq === 'number'
+        ? cursor.max_commit_seq
+        : 0;
+    return {
+      rows: rowsResult.results.filter(
+        (row): row is Readonly<Record<string, unknown>> =>
+          typeof row === 'object' && row !== null,
+      ),
+      maxCommitSeq,
+    };
+  }
+
   async getHorizonSeq(partition: string): Promise<number> {
     const row = await this.#db
       .prepare('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
@@ -918,6 +1060,216 @@ export class D1ServerStorage implements ServerStorage {
     }
   }
 
+  async claimReactions(
+    partition: string,
+    query: ReactionClaimQuery,
+  ): Promise<StoredReaction[]> {
+    if (query.types.length === 0 || query.limit <= 0) return [];
+    if (query.types.length + 7 > D1_MAX_BIND_PARAMS) {
+      throw new Error('D1 reaction claim exceeds the bound-parameter limit');
+    }
+    const typeParams = query.types.map(() => '?').join(',');
+    const { results } = await this.#db
+      .prepare(
+        `UPDATE sync_reactions
+            SET status='leased', attempts=attempts+1,
+                lease_owner=?, lease_expires_at_ms=?, completed_at_ms=NULL
+          WHERE (partition, idempotency_key) IN (
+            SELECT partition, idempotency_key
+              FROM sync_reactions
+             WHERE partition=? AND type IN (${typeParams})
+               AND ((status='pending' AND available_at_ms<=?)
+                 OR (status='leased' AND lease_expires_at_ms<=?))
+             ORDER BY CASE WHEN status='leased' THEN lease_expires_at_ms
+                           ELSE available_at_ms END,
+                      created_at_ms, idempotency_key
+             LIMIT ?
+          )
+        RETURNING *`,
+      )
+      .bind(
+        query.leaseOwner,
+        Math.min(Number.MAX_SAFE_INTEGER, query.nowMs + query.leaseDurationMs),
+        partition,
+        ...query.types,
+        query.nowMs,
+        query.nowMs,
+        query.limit,
+      )
+      .all<D1ReactionRecord>();
+    return results
+      .map(toStoredReaction)
+      .sort(
+        (a, b) =>
+          a.createdAtMs - b.createdAtMs ||
+          a.idempotencyKey.localeCompare(b.idempotencyKey),
+      );
+  }
+
+  async completeReaction(
+    partition: string,
+    idempotencyKey: string,
+    leaseOwner: string,
+    completedAtMs: number,
+  ): Promise<boolean> {
+    const record = await this.#db
+      .prepare(
+        `UPDATE sync_reactions
+            SET status='completed', completed_at_ms=?,
+                lease_owner=NULL, lease_expires_at_ms=NULL
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?
+        RETURNING idempotency_key`,
+      )
+      .bind(completedAtMs, partition, idempotencyKey, leaseOwner)
+      .first<{ idempotency_key: string }>();
+    return record !== null;
+  }
+
+  async extendReactionLease(
+    partition: string,
+    idempotencyKey: string,
+    leaseOwner: string,
+    leaseExpiresAtMs: number,
+  ): Promise<boolean> {
+    const record = await this.#db
+      .prepare(
+        `UPDATE sync_reactions SET lease_expires_at_ms=?
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?
+        RETURNING idempotency_key`,
+      )
+      .bind(leaseExpiresAtMs, partition, idempotencyKey, leaseOwner)
+      .first<{ idempotency_key: string }>();
+    return record !== null;
+  }
+
+  async failReaction(
+    partition: string,
+    idempotencyKey: string,
+    update: ReactionFailureUpdate,
+  ): Promise<boolean> {
+    const record = await this.#db
+      .prepare(
+        `UPDATE sync_reactions
+            SET status=?, available_at_ms=?, last_failure=?,
+                lease_owner=NULL, lease_expires_at_ms=NULL
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?
+        RETURNING idempotency_key`,
+      )
+      .bind(
+        update.retryAtMs === undefined ? 'dead-letter' : 'pending',
+        update.retryAtMs ?? update.failure.atMs,
+        JSON.stringify(update.failure),
+        partition,
+        idempotencyKey,
+        update.leaseOwner,
+      )
+      .first<{ idempotency_key: string }>();
+    return record !== null;
+  }
+
+  async retryReaction(
+    partition: string,
+    idempotencyKey: string,
+    nowMs: number,
+  ): Promise<boolean> {
+    const record = await this.#db
+      .prepare(
+        `UPDATE sync_reactions
+            SET status='pending', attempts=0, available_at_ms=?,
+                last_failure=NULL, lease_owner=NULL, lease_expires_at_ms=NULL,
+                completed_at_ms=NULL
+          WHERE partition=? AND idempotency_key=? AND status='dead-letter'
+        RETURNING idempotency_key`,
+      )
+      .bind(nowMs, partition, idempotencyKey)
+      .first<{ idempotency_key: string }>();
+    return record !== null;
+  }
+
+  async getReaction(
+    partition: string,
+    idempotencyKey: string,
+  ): Promise<StoredReaction | undefined> {
+    const record = await this.#db
+      .prepare(
+        'SELECT * FROM sync_reactions WHERE partition=? AND idempotency_key=?',
+      )
+      .bind(partition, idempotencyKey)
+      .first<D1ReactionRecord>();
+    return record === null ? undefined : toStoredReaction(record);
+  }
+
+  async listReactions(
+    partition: string,
+    query: ReactionListQuery,
+  ): Promise<StoredReaction[]> {
+    const where = ['partition=?'];
+    const params: (string | number)[] = [partition];
+    if (query.statuses !== undefined && query.statuses.length > 0) {
+      where.push(`status IN (${query.statuses.map(() => '?').join(',')})`);
+      params.push(...query.statuses);
+    }
+    if (query.types !== undefined && query.types.length > 0) {
+      where.push(`type IN (${query.types.map(() => '?').join(',')})`);
+      params.push(...query.types);
+    }
+    if (params.length + 1 > D1_MAX_BIND_PARAMS) {
+      throw new Error('D1 reaction list exceeds the bound-parameter limit');
+    }
+    params.push(query.limit);
+    const { results } = await this.#db
+      .prepare(
+        `SELECT * FROM sync_reactions WHERE ${where.join(' AND ')}
+          ORDER BY created_at_ms DESC, idempotency_key DESC LIMIT ?`,
+      )
+      .bind(...params)
+      .all<D1ReactionRecord>();
+    return results.map(toStoredReaction);
+  }
+
+  async pruneReactions(
+    partition: string,
+    query: ReactionPruneQuery,
+  ): Promise<PrunedReactionCounts> {
+    if (query.limit <= 0) return { completed: 0, deadLetter: 0 };
+    const { results } = await this.#db
+      .prepare(
+        `DELETE FROM sync_reactions
+          WHERE partition=? AND idempotency_key IN (
+            SELECT idempotency_key FROM sync_reactions
+             WHERE partition=?
+               AND ((status='completed' AND completed_at_ms IS NOT NULL
+                     AND completed_at_ms<?)
+                 OR (status='dead-letter' AND available_at_ms<?))
+             ORDER BY CASE WHEN status='completed' THEN completed_at_ms
+                           ELSE available_at_ms END,
+                      idempotency_key
+             LIMIT ?
+          )
+            AND ((status='completed' AND completed_at_ms IS NOT NULL
+                  AND completed_at_ms<?)
+              OR (status='dead-letter' AND available_at_ms<?))
+        RETURNING status`,
+      )
+      .bind(
+        partition,
+        partition,
+        query.completedBeforeMs,
+        query.deadLetterBeforeMs,
+        query.limit,
+        query.completedBeforeMs,
+        query.deadLetterBeforeMs,
+      )
+      .all<{ status: 'completed' | 'dead-letter' }>();
+    return {
+      completed: results.filter((row) => row.status === 'completed').length,
+      deadLetter: results.filter((row) => row.status === 'dead-letter').length,
+    };
+  }
+
   async readCommitWindow(
     partition: string,
     query: CommitWindowQuery,
@@ -1137,7 +1489,7 @@ export class D1ServerStorage implements ServerStorage {
     return results.map((r) => r.blob_id);
   }
 
-  // -- admin/console read surface (TODO §2.5) --------------------------------
+  // -- admin/console read surface --------------------------------------------
 
   async listClientRecords(partition: string): Promise<ClientRecord[]> {
     const { results } = await this.#db