trajectories 0.0.0 → 0.1.1

package/legacy/src/sync.ts

@@ -0,0 +1,1219 @@
+import { Database } from "bun:sqlite";
+import { prepareSyncStore, type SyncPreparationJob, type SyncPreparationReply } from "./sync-preparation.js";
+import type { DiscoverySummary } from "./discovery.js";
+import { setTimeout as sleep } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { TrajectoryDb } from "./db.js";
+import { TrajectoryReader } from "./reader.js";
+import {
+  APPEND_TAIL_BYTES,
+  DEFAULT_INGEST_RECORD_BYTES,
+  IngestBudgetExceeded,
+  ingestDiscoveredSession,
+  isIncrementalJsonl,
+  sessionNeedsIngest,
+  sourceFingerprint,
+  type IngestWork,
+} from "./ingest.js";
+import {
+  DEFAULT_PRESSURE_STATE,
+  adaptPressure,
+  samplePressure,
+  scaledLimit,
+  type AdaptivePressureState,
+  type PressureSnapshot,
+} from "./pressure.js";
+import { scanSessions, type SessionScanOptions } from "./scanner.js";
+import type { DiscoveredSession, IngestCursor, IngestQueueEntry } from "./types.js";
+import {
+  acquireWriterLease,
+  DEFAULT_WRITER_LEASE_WAIT_MS,
+  describeLeaseHolder,
+  isMemoryStorePath,
+  readWriterLease,
+  writerLockPath,
+  WriterLeaseBusyError,
+  type WriterLease,
+  type WriterLeaseMetadata,
+} from "./writer-lease.js";
+
+export const SYNC_PROTOCOL_VERSION = 2;
+export const DEFAULT_SYNC_SESSION_BUDGET = 25;
+export const DEFAULT_SYNC_SOURCE_BYTES = 64 * 1024 * 1024;
+export const DEFAULT_SYNC_WALL_MS = 120_000;
+export const DEFAULT_SYNC_RETRY_BUDGET = 3;
+export const DEFAULT_SYNC_SESSION_ATTEMPTS = 8;
+export const DEFAULT_SYNC_READ_BYTES_PER_SECOND = 8 * 1024 * 1024;
+export const DEFAULT_SYNC_WORKER_MS = 30_000;
+export const DEFAULT_SYNC_WORKERS = 2;
+export const DEFAULT_SYNC_FRESH_SESSIONS = 5;
+export const DEFAULT_SYNC_FRESH_WINDOW_MS = 60 * 60 * 1000;
+export const DEFAULT_SYNC_CHUNK_BYTES = 1024 * 1024;
+export const DEFAULT_SYNC_MAINTENANCE_MS = 5_000;
+export const DEFAULT_SYNC_FTS_MERGE_PAGES = 64;
+export const DEFAULT_WAL_AUTOCHECKPOINT_PAGES = 1000;
+
+/** Grace between SIGTERM and SIGKILL for a disposable child the deadline stopped. */
+export const WORKER_KILL_GRACE_MS = 250;
+/**
+ * How long an expired worker wave may take to finish reaping its children: the
+ * kill grace plus process exit, so the lease is never released underneath a
+ * worker that is still dying. `LEDGER_WAVE_REAP_MS` overrides it for heavily
+ * loaded volumes (strict non-negative-integer parse, clamped to at least the
+ * kill grace so the window can never undercut the escalation sequence);
+ * unparsable values keep the default.
+ */
+const WAVE_REAP_MS = WORKER_KILL_GRACE_MS * 2;
+
+export function waveReapMsFor(raw: string | undefined): number {
+  if (raw === undefined || !/^\d+$/.test(raw.trim())) return WAVE_REAP_MS;
+  return Math.max(Number.parseInt(raw.trim(), 10), WORKER_KILL_GRACE_MS);
+}
+
+function readWaveReapMs(): number {
+  return waveReapMsFor(process.env.LEDGER_WAVE_REAP_MS);
+}
+
+export interface SyncBudgets {
+  sessions: number;
+  sourceBytes: number;
+  wallMs: number;
+  retries: number;
+  attemptsPerSession: number;
+  readBytesPerSecond: number;
+  workerMs: number;
+  workers: number;
+  freshSessions: number;
+  freshWindowMs: number;
+  chunkBytes: number;
+  maintenanceMs: number;
+  ftsMergePages: number;
+}
+
+export interface SyncOptions extends Pick<SessionScanOptions, "sources" | "roots"> {
+  dbPath: string;
+  scanLimit?: number;
+  maxRecordBytes?: number;
+  budgets?: Partial<SyncBudgets>;
+  pressureMode?: "auto" | "off";
+  workerCommand?: string[];
+  maintenanceCommand?: string[];
+  /** Test/embedding seam; production uses the private leaf preparation verb. */
+  preparationCommand?: string[];
+}
+
+export interface SyncWorkerJob {
+  protocol_version: typeof SYNC_PROTOCOL_VERSION;
+  db_path: string;
+  item: DiscoveredSession;
+  max_chunk_bytes: number;
+  max_record_bytes: number;
+  max_source_bytes: number;
+  read_bytes_per_second: number;
+  max_wall_ms: number;
+  max_attempts: number;
+}
+
+interface CursorState {
+  session_id: string | null;
+  bytes_ingested: number;
+  record_count: number;
+  status: string;
+  prefix_hash: string | null;
+}
+
+export interface SyncWorkerReply {
+  protocol_version: typeof SYNC_PROTOCOL_VERSION;
+  type: "sync_worker_result";
+  outcome: "ok" | "budget_exhausted" | "error";
+  results: Record<string, number>;
+  attempts: number;
+  budget?: "source_bytes" | "wall_time";
+  error_code?: "ingest_failed" | "database_busy" | "writer_busy";
+  work: IngestWork;
+  cursor_before: CursorState | null;
+  cursor_after: CursorState | null;
+  cursor_changed: boolean;
+  needs_ingest_after: boolean;
+  stalled: boolean;
+}
+
+/** A disposable child the pass stopped at a deadline: which process, under which bound. */
+export interface WorkerStop {
+  pid: number;
+  timeout_ms: number;
+  label: string;
+}
+
+export interface WorkerInvocation {
+  status: "ok" | "spawn_failed" | "timed_out" | "protocol_error" | "failed";
+  reply?: SyncWorkerReply;
+  /** Present when a deadline stopped the child instead of it replying. */
+  stop?: WorkerStop;
+}
+
+export interface SyncMaintenanceJob {
+  protocol_version: typeof SYNC_PROTOCOL_VERSION;
+  db_path: string;
+  fts_merge_pages: number;
+  wal_autocheckpoint_pages: number;
+}
+
+export interface SyncMaintenanceReply {
+  protocol_version: typeof SYNC_PROTOCOL_VERSION;
+  type: "sync_maintenance_result";
+  fts_changes: number;
+  optimize_actions: number;
+  wal_busy: number;
+  wal_log_frames: number;
+  wal_checkpointed_frames: number;
+  elapsed_ms: number;
+}
+
+export interface MaintenanceInvocation {
+  status: "ok" | "spawn_failed" | "timed_out" | "protocol_error" | "failed" | "disabled" | "skipped";
+  reply?: SyncMaintenanceReply;
+  /** Present when a deadline stopped the child instead of it replying. */
+  stop?: WorkerStop;
+}
+
+export interface SyncDependencies {
+  /** Test-only in-process seam. Production discovery must use the disposable child. */
+  scan?: typeof scanSessions;
+  runWorker?: (
+    job: SyncWorkerJob,
+    timeoutMs: number,
+    command: string[],
+    signal?: AbortSignal,
+  ) => Promise<WorkerInvocation>;
+  runMaintenance?: (job: SyncMaintenanceJob, timeoutMs: number, command: string[]) => Promise<MaintenanceInvocation>;
+  pressure?: () => PressureSnapshot;
+  now?: () => Date;
+}
+
+export interface SyncSummary {
+  type: "sync_summary";
+  schema_version: 2;
+  /** Completion never implies that deleted, unsupported or unobserved history is archived. */
+  completion_scope?: "known_work";
+  discovery?: DiscoverySummary;
+  preparation_ms?: number;
+  outcome: "complete" | "pending" | "pending_budget" | "pending_retry" | "pending_pressure" | "wall_budget_exceeded";
+  elapsed_ms: number;
+  timing: { scan_ms: number; queue_ms: number; workers_ms: number; maintenance_ms: number; derive_ms: number };
+  discovered: number;
+  queued_at_start: number;
+  sessions_admitted: number;
+  lanes: { fresh: number; backlog: number };
+  worker_processes: number;
+  worker_attempts: number;
+  retries_scheduled: number;
+  completed: number;
+  results: Record<string, number>;
+  work: IngestWork & { unavailable_worker_reports: number; source_bytes_reserved: number };
+  pending: { total: number; eligible: number; retrying: number };
+  budgets: SyncBudgets & {
+    exhausted: string[];
+    effective: Pick<SyncBudgets, "sessions" | "sourceBytes" | "readBytesPerSecond" | "workers" | "freshSessions">;
+  };
+  pressure: {
+    mode: "auto" | "off";
+    initial: PressureSnapshot;
+    final: PressureSnapshot;
+    state: AdaptivePressureState;
+  };
+  maintenance: MaintenanceInvocation;
+  /** Present only on a scheduled pass that yielded the store to another writer. */
+  skipped?: { reason: "writer_busy"; holder: WriterLeaseMetadata | null };
+}
+
+function positiveInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`${name} must be a positive safe integer`);
+  return value;
+}
+
+function nonnegativeInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${name} must be a nonnegative safe integer`);
+  return value;
+}
+
+function budgets(input: Partial<SyncBudgets> = {}): SyncBudgets {
+  const sessions = positiveInteger(input.sessions ?? DEFAULT_SYNC_SESSION_BUDGET, "session budget");
+  return {
+    sessions,
+    sourceBytes: positiveInteger(input.sourceBytes ?? DEFAULT_SYNC_SOURCE_BYTES, "source byte budget"),
+    wallMs: positiveInteger(input.wallMs ?? DEFAULT_SYNC_WALL_MS, "wall budget"),
+    retries: nonnegativeInteger(input.retries ?? DEFAULT_SYNC_RETRY_BUDGET, "retry budget"),
+    attemptsPerSession: positiveInteger(input.attemptsPerSession ?? DEFAULT_SYNC_SESSION_ATTEMPTS, "per-session attempt budget"),
+    readBytesPerSecond: positiveInteger(input.readBytesPerSecond ?? DEFAULT_SYNC_READ_BYTES_PER_SECOND, "read rate"),
+    workerMs: positiveInteger(input.workerMs ?? DEFAULT_SYNC_WORKER_MS, "worker deadline"),
+    workers: positiveInteger(input.workers ?? DEFAULT_SYNC_WORKERS, "worker concurrency"),
+    freshSessions: nonnegativeInteger(input.freshSessions ?? DEFAULT_SYNC_FRESH_SESSIONS, "fresh session budget"),
+    freshWindowMs: positiveInteger(input.freshWindowMs ?? DEFAULT_SYNC_FRESH_WINDOW_MS, "fresh window"),
+    chunkBytes: positiveInteger(input.chunkBytes ?? DEFAULT_SYNC_CHUNK_BYTES, "sync chunk bytes"),
+    maintenanceMs: nonnegativeInteger(input.maintenanceMs ?? DEFAULT_SYNC_MAINTENANCE_MS, "maintenance deadline"),
+    ftsMergePages: nonnegativeInteger(input.ftsMergePages ?? DEFAULT_SYNC_FTS_MERGE_PAGES, "FTS merge pages"),
+  };
+}
+
+function cursorState(cursor: IngestCursor | null): CursorState | null {
+  return cursor && {
+    session_id: cursor.session_id,
+    bytes_ingested: cursor.bytes_ingested,
+    record_count: cursor.record_count,
+    status: cursor.status,
+    prefix_hash: cursor.prefix_hash ?? null,
+  };
+}
+
+function getCursor(db: TrajectoryDb, item: DiscoveredSession): IngestCursor | null {
+  return db.getIngestCursor(item.source, item.id, item.path);
+}
+
+function emptyWork(): IngestWork {
+  return { source_bytes_read: 0, source_bytes_hashed: 0, historical_records_hashed: 0 };
+}
+
+function addWork(target: IngestWork, addition: IngestWork): void {
+  target.source_bytes_read += addition.source_bytes_read;
+  target.source_bytes_hashed += addition.source_bytes_hashed;
+  target.historical_records_hashed += addition.historical_records_hashed;
+}
+
+function addCounts(target: Record<string, number>, addition: Record<string, number>): void {
+  for (const [key, value] of Object.entries(addition)) target[key] = (target[key] ?? 0) + value;
+}
+
+function validateJob(value: unknown): SyncWorkerJob {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid_worker_job");
+  const job = value as Record<string, unknown>;
+  const item = job.item as Record<string, unknown> | undefined;
+  if (job.protocol_version !== SYNC_PROTOCOL_VERSION || typeof job.db_path !== "string" || !job.db_path ||
+    !item || typeof item.source !== "string" || !item.source || typeof item.id !== "string" || !item.id ||
+    typeof item.path !== "string" || !item.path) throw new Error("invalid_worker_job");
+  for (const key of ["max_chunk_bytes", "max_record_bytes", "max_source_bytes", "read_bytes_per_second", "max_wall_ms", "max_attempts"] as const) {
+    positiveInteger(job[key] as number, key);
+  }
+  if ((job.max_record_bytes as number) < (job.max_chunk_bytes as number)) throw new Error("invalid_worker_job");
+  return value as SyncWorkerJob;
+}
+
+export async function executeSyncWorker(
+  input: unknown,
+  options: { workerChild?: boolean } = {},
+): Promise<SyncWorkerReply> {
+  const job = validateJob(input);
+  // The parent's lease is this child's write authority; check it before any
+  // store handle exists.
+  if (options.workerChild) requireParentLease(job.db_path);
+  const db = new TrajectoryDb(job.db_path);
+  const before = cursorState(getCursor(db, job.item));
+  const totalWork = emptyWork();
+  const results: Record<string, number> = {};
+  const started = performance.now();
+  let attempts = 0;
+  let needsIngest = true;
+  let stalled = false;
+  try {
+    while (attempts < job.max_attempts && needsIngest) {
+      const elapsed = performance.now() - started;
+      const remainingWall = Math.floor(job.max_wall_ms - elapsed);
+      const remainingBytes = job.max_source_bytes - totalWork.source_bytes_read;
+      if (remainingWall <= 0 || remainingBytes <= 0) {
+        const after = cursorState(getCursor(db, job.item));
+        return {
+          protocol_version: SYNC_PROTOCOL_VERSION, type: "sync_worker_result", outcome: "budget_exhausted",
+          budget: remainingWall <= 0 ? "wall_time" : "source_bytes", results, attempts, work: totalWork,
+          cursor_before: before, cursor_after: after,
+          cursor_changed: JSON.stringify(before) !== JSON.stringify(after),
+          needs_ingest_after: true, stalled: false,
+        };
+      }
+      const attemptBefore = cursorState(getCursor(db, job.item));
+      attempts++;
+      const result = await ingestDiscoveredSession(db, job.item, {
+        maxChunkBytes: job.max_chunk_bytes,
+        maxRecordBytes: job.max_record_bytes,
+        maxSourceBytes: remainingBytes,
+        readBytesPerSecond: job.read_bytes_per_second,
+        maxWallMs: remainingWall,
+      });
+      addWork(totalWork, result.work ?? emptyWork());
+      results[result.kind] = (results[result.kind] ?? 0) + 1;
+      const attemptAfter = cursorState(getCursor(db, job.item));
+      needsIngest = sessionNeedsIngest(db, job.item, { maxRecordBytes: job.max_record_bytes });
+      if (needsIngest && JSON.stringify(attemptBefore) === JSON.stringify(attemptAfter)) {
+        stalled = true;
+        break;
+      }
+    }
+    const after = cursorState(getCursor(db, job.item));
+    return {
+      protocol_version: SYNC_PROTOCOL_VERSION,
+      type: "sync_worker_result",
+      outcome: "ok",
+      results,
+      attempts,
+      work: totalWork,
+      cursor_before: before,
+      cursor_after: after,
+      cursor_changed: JSON.stringify(before) !== JSON.stringify(after),
+      needs_ingest_after: needsIngest,
+      stalled,
+    };
+  } catch (error) {
+    const after = cursorState(getCursor(db, job.item));
+    if (error instanceof IngestBudgetExceeded) {
+      addWork(totalWork, error.work);
+      return {
+        protocol_version: SYNC_PROTOCOL_VERSION, type: "sync_worker_result", outcome: "budget_exhausted",
+        budget: error.budget, results, attempts, work: totalWork, cursor_before: before, cursor_after: after,
+        cursor_changed: JSON.stringify(before) !== JSON.stringify(after), needs_ingest_after: true, stalled: false,
+      };
+    }
+    return {
+      protocol_version: SYNC_PROTOCOL_VERSION, type: "sync_worker_result", outcome: "error",
+      error_code: error instanceof Error && /database is (locked|busy)|SQLITE_BUSY/i.test(error.message)
+        ? "database_busy" : "ingest_failed",
+      results, attempts, work: totalWork, cursor_before: before, cursor_after: after,
+      cursor_changed: JSON.stringify(before) !== JSON.stringify(after), needs_ingest_after: true, stalled: true,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+export async function executeSyncWorkerStdio(options: { workerChild?: boolean } = {}): Promise<void> {
+  const raw = await readBoundedProtocol(Bun.stdin.stream());
+  if (raw.length > 64 * 1024) throw new Error("invalid_worker_job");
+  const input = JSON.parse(raw);
+  let reply: SyncWorkerReply;
+  try {
+    reply = await executeSyncWorker(input, options);
+  } catch (error) {
+    if (!(error instanceof WriterLeaseBusyError)) throw error;
+    // The refusal is a normal protocol reply, so the parent defers the session
+    // durably instead of treating it as a crashed child.
+    console.error(error.message);
+    reply = {
+      protocol_version: SYNC_PROTOCOL_VERSION, type: "sync_worker_result", outcome: "error",
+      error_code: "writer_busy", results: {}, attempts: 0, work: emptyWork(),
+      cursor_before: null, cursor_after: null, cursor_changed: false,
+      needs_ingest_after: true, stalled: false,
+    };
+  }
+  process.stdout.write(JSON.stringify(reply) + "\n");
+}
+
+function validWork(value: unknown): value is IngestWork {
+  if (!value || typeof value !== "object") return false;
+  return ["source_bytes_read", "source_bytes_hashed", "historical_records_hashed"]
+    .every((key) => Number.isSafeInteger((value as Record<string, unknown>)[key]) && Number((value as Record<string, unknown>)[key]) >= 0);
+}
+
+function validCounts(value: unknown): value is Record<string, number> {
+  return !!value && typeof value === "object" && !Array.isArray(value) &&
+    Object.entries(value).every(([key, count]) => key.length > 0 && Number.isSafeInteger(count) && Number(count) >= 0);
+}
+
+function parseWorkerReply(raw: string): SyncWorkerReply | null {
+  if (raw.length > 64 * 1024) return null;
+  try {
+    const reply = JSON.parse(raw) as SyncWorkerReply;
+    if (reply.protocol_version !== SYNC_PROTOCOL_VERSION || reply.type !== "sync_worker_result" ||
+      !["ok", "budget_exhausted", "error"].includes(reply.outcome) || !validWork(reply.work) ||
+      !validCounts(reply.results) || !Number.isSafeInteger(reply.attempts) || reply.attempts < 0 ||
+      typeof reply.cursor_changed !== "boolean" || typeof reply.needs_ingest_after !== "boolean" ||
+      typeof reply.stalled !== "boolean") return null;
+    return reply;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Kill sequence for a disposable child: SIGTERM for a chance to exit cleanly,
+ * SIGKILL after the grace, and the answer is pending until the child is reaped.
+ * Callers race it against whatever they were waiting on, so a child that
+ * ignores SIGTERM — or a stdout pipe a descendant keeps open — cannot keep the
+ * caller's await pending. The kill is pid-scoped: a descendant holding that
+ * pipe lives on as its own process, and nothing here waits on it.
+ */
+/**
+ * Kill escalation is pid-scoped by design: today's workers are leaf `bun
+ * __sync-worker` processes with no descendants, and a process-group kill
+ * (setsid + kill(-pid)) would make workers survive the parent's death —
+ * trading a real orphan regression for a hypothetical descendant. If a worker
+ * ever spawns children, switch this to group semantics and pin the orphan
+ * behavior (issue #39 item 1; the recorded trigger is this comment).
+ */
+async function terminateChild(child: Bun.Subprocess<"pipe", "pipe", "ignore">): Promise<void> {
+  if (child.exitCode !== null) return;
+  try { child.kill("SIGTERM"); } catch { /* already exited */ }
+  await sleep(WORKER_KILL_GRACE_MS);
+  try { child.kill("SIGKILL"); } catch { /* already exited */ }
+  try { await child.exited; } catch { /* reaped elsewhere */ }
+}
+
+export async function readBoundedProtocol(stream: ReadableStream<Uint8Array>, maxBytes = 64 * 1024): Promise<string> {
+  const reader = stream.getReader();
+  const parts: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) throw new Error("protocol_output_too_large");
+      parts.push(value);
+    }
+    return Buffer.concat(parts).toString("utf8");
+  } finally { reader.releaseLock(); }
+}
+
+async function spawnJsonChild<T>(
+  input: unknown,
+  timeoutMs: number,
+  command: string[],
+  parse: (raw: string) => T | null,
+  options: { label: string; env?: Record<string, string | undefined>; signal?: AbortSignal },
+): Promise<{ status: WorkerInvocation["status"]; reply?: T; stop?: WorkerStop }> {
+  let child: Bun.Subprocess<"pipe", "pipe", "ignore">;
+  try {
+    child = Bun.spawn(command, { stdin: "pipe", stdout: "pipe", stderr: "ignore", env: options.env });
+  } catch {
+    return { status: "spawn_failed" };
+  }
+  // Both the child's own deadline and the pass's wall stop it through this one
+  // sequence, and the sequence's completion is what settles the call: the reply
+  // drain races it, so a stream that never closes loses instead of holding the
+  // await open forever.
+  const killed = Promise.withResolvers<void>();
+  let stopped = false;
+  let termination: Promise<void> | null = null;
+  const killChild = (): void => {
+    stopped = true;
+    termination ??= terminateChild(child).then(() => killed.resolve());
+  };
+  const timer = setTimeout(killChild, timeoutMs);
+  const onAbort = (): void => killChild();
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  if (options.signal?.aborted) killChild();
+  try {
+    child.stdin.write(JSON.stringify(input));
+    child.stdin.end();
+    const drain = (async () => {
+      const raw = await readBoundedProtocol(child.stdout);
+      return { raw, exitCode: await child.exited };
+    })();
+    await Promise.race([drain, killed.promise]);
+    // The drain can win the race on the SIGTERM EOF while the child is already
+    // stopped, so the flag — not the race winner — decides the status.
+    if (stopped) {
+      return {
+        status: "timed_out",
+        stop: { pid: child.pid, timeout_ms: timeoutMs, label: options.label },
+      };
+    }
+    const { raw, exitCode } = await drain;
+    if (exitCode !== 0) return { status: "failed" };
+    const reply = parse(raw.trim());
+    return reply ? { status: "ok", reply } : { status: "protocol_error" };
+  } catch {
+    return stopped ? { status: "timed_out", stop: { pid: child.pid, timeout_ms: timeoutMs, label: options.label } }
+      : { status: "protocol_error" };
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+    if (termination) {
+      // The stop sequence owns the reap; waiting for it keeps a dying child
+      // from outliving the call that opened it.
+      await termination;
+    } else if (child.exitCode === null) {
+      await terminateChild(child);
+    }
+  }
+}
+
+export async function spawnSyncWorker(
+  job: SyncWorkerJob,
+  timeoutMs: number,
+  command: string[],
+  signal?: AbortSignal,
+): Promise<WorkerInvocation> {
+  // The parent holds the writer lease across the whole pass; the marker only
+  // tells the child it was spawned by one. Its authority is checked against the
+  // parent's lease (see requireParentLease), never trusted from the environment.
+  return spawnJsonChild(job, timeoutMs, command, parseWorkerReply, {
+    label: "sync_worker",
+    env: { ...process.env, LEDGER_SYNC_WORKER: "1" },
+    signal,
+  });
+}
+
+function validateMaintenanceJob(value: unknown): SyncMaintenanceJob {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid_maintenance_job");
+  const job = value as Record<string, unknown>;
+  if (job.protocol_version !== SYNC_PROTOCOL_VERSION || typeof job.db_path !== "string" || !job.db_path) {
+    throw new Error("invalid_maintenance_job");
+  }
+  nonnegativeInteger(job.fts_merge_pages as number, "fts_merge_pages");
+  positiveInteger(job.wal_autocheckpoint_pages as number, "wal_autocheckpoint_pages");
+  return value as SyncMaintenanceJob;
+}
+
+export function executeSyncMaintenance(
+  input: unknown,
+  options: { workerChild?: boolean } = {},
+): SyncMaintenanceReply {
+  const job = validateMaintenanceJob(input);
+  if (options.workerChild) requireParentLease(job.db_path);
+  const started = performance.now();
+  const db = new Database(job.db_path);
+  try {
+    db.run("PRAGMA busy_timeout = 15000");
+    db.run("PRAGMA journal_mode = WAL");
+    db.run(`PRAGMA wal_autocheckpoint = ${job.wal_autocheckpoint_pages}`);
+    const ftsChanges = job.fts_merge_pages > 0
+      ? db.run("INSERT INTO records_fts(records_fts, rank) VALUES ('merge', ?)", [job.fts_merge_pages]).changes
+      : 0;
+    const optimizeActions = db.query("PRAGMA optimize").all().length;
+    const checkpoint = db.query<{ busy: number; log: number; checkpointed: number }, []>(
+      "PRAGMA wal_checkpoint(PASSIVE)",
+    ).get() ?? { busy: 0, log: 0, checkpointed: 0 };
+    return {
+      protocol_version: SYNC_PROTOCOL_VERSION,
+      type: "sync_maintenance_result",
+      fts_changes: ftsChanges,
+      optimize_actions: optimizeActions,
+      wal_busy: checkpoint.busy,
+      wal_log_frames: checkpoint.log,
+      wal_checkpointed_frames: checkpoint.checkpointed,
+      elapsed_ms: performance.now() - started,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+export async function executeSyncMaintenanceStdio(options: { workerChild?: boolean } = {}): Promise<void> {
+  const raw = await readBoundedProtocol(Bun.stdin.stream());
+  if (raw.length > 64 * 1024) throw new Error("invalid_maintenance_job");
+  process.stdout.write(JSON.stringify(executeSyncMaintenance(JSON.parse(raw), options)) + "\n");
+}
+
+function parseMaintenanceReply(raw: string): SyncMaintenanceReply | null {
+  if (raw.length > 64 * 1024) return null;
+  try {
+    const reply = JSON.parse(raw) as SyncMaintenanceReply;
+    if (reply.protocol_version !== SYNC_PROTOCOL_VERSION || reply.type !== "sync_maintenance_result") return null;
+    for (const value of [reply.fts_changes, reply.optimize_actions, reply.wal_busy,
+      reply.wal_log_frames, reply.wal_checkpointed_frames, reply.elapsed_ms]) {
+      if (!Number.isFinite(value) || value < 0) return null;
+    }
+    return reply;
+  } catch {
+    return null;
+  }
+}
+
+export async function spawnSyncMaintenance(
+  job: SyncMaintenanceJob,
+  timeoutMs: number,
+  command: string[],
+): Promise<MaintenanceInvocation> {
+  return spawnJsonChild(job, timeoutMs, command, parseMaintenanceReply, { label: "sync_maintenance" });
+}
+
+function retryAt(now: Date, attempts: number): string {
+  const delayMs = Math.min(6 * 60 * 60 * 1000, 15 * 60 * 1000 * 2 ** Math.min(attempts, 5));
+  return new Date(now.getTime() + delayMs).toISOString();
+}
+
+function workerEntry(): string[] {
+  return [process.execPath, fileURLToPath(new URL("../bin/ledger-core.ts", import.meta.url)), "__sync-worker"];
+}
+
+function maintenanceEntry(): string[] {
+  return [process.execPath, fileURLToPath(new URL("../bin/ledger-core.ts", import.meta.url)), "__sync-maintenance"];
+}
+
+export function workerReservation(
+  item: IngestQueueEntry,
+  limits: Pick<SyncBudgets, "attemptsPerSession" | "chunkBytes">,
+  remaining: number,
+): number {
+  // Directory-backed native sessions span metadata plus companion files;
+  // discovery only sizes the metadata file. Reserve the assembled footprint.
+  const sourceBytes = item.native?.kind === "opencode-storage" || item.native?.kind === "fx-directory"
+    ? sourceFingerprint(item)?.size ?? item.sizeBytes
+    : item.sizeBytes;
+  const desired = isIncrementalJsonl(item)
+    ? limits.attemptsPerSession * (limits.chunkBytes + APPEND_TAIL_BYTES)
+    : Math.max(1, sourceBytes ?? limits.chunkBytes);
+  return Math.max(1, Math.min(desired, remaining));
+}
+
+function pressureOffSnapshot(): PressureSnapshot {
+  return { platform: process.platform, severity: "unavailable", cpu: null, memory: null, io: null,
+    cgroup_memory_ratio: null, cgroup_cpu_cores: null, reasons: ["pressure_mode_off"] };
+}
+
+function effectiveLimits(limits: SyncBudgets, state: AdaptivePressureState, snapshot: PressureSnapshot) {
+  const sessions = scaledLimit(limits.sessions, state.scale_permille);
+  const quotaWorkers = snapshot.cgroup_cpu_cores === null
+    ? limits.workers
+    : Math.max(1, Math.floor(snapshot.cgroup_cpu_cores));
+  return {
+    sessions,
+    sourceBytes: scaledLimit(limits.sourceBytes, state.scale_permille),
+    readBytesPerSecond: scaledLimit(limits.readBytesPerSecond, state.scale_permille),
+    workers: Math.min(sessions, quotaWorkers, scaledLimit(limits.workers, state.scale_permille)),
+    freshSessions: limits.freshSessions === 0 ? 0 : Math.min(sessions, scaledLimit(limits.freshSessions, state.scale_permille)),
+  };
+}
+
+/** Result of the sync lease policy: this pass owns the store, or it does not run. */
+type SyncLeaseOutcome =
+  | { status: "held"; lease: WriterLease }
+  | { status: "exempt" }
+  | { status: "skipped"; holder: WriterLeaseMetadata | null };
+
+/**
+ * Lease policy for the sync entry point. A scheduled pass yields the store to a
+ * foreground writer instead of queueing behind it, and a foreground verb waits
+ * briefly before refusing with a typed error. Nothing here consults the
+ * environment: the worker-child marker is a transport hint only, and a child
+ * proves its authority by naming its parent (see requireParentLease).
+ */
+function acquireSyncLease(dbPath: string): SyncLeaseOutcome {
+  if (isMemoryStorePath(dbPath)) return { status: "exempt" };
+  const scheduled = process.env.LEDGER_SCHEDULER === "1";
+  try {
+    return {
+      status: "held",
+      lease: acquireWriterLease(dbPath, {
+        waitMs: scheduled ? 0 : DEFAULT_WRITER_LEASE_WAIT_MS,
+        holder: scheduled ? "scheduler" : "sync",
+      }),
+    };
+  } catch (error) {
+    if (!scheduled || !(error instanceof WriterLeaseBusyError)) throw error;
+    console.error(`[ledger] sync skipped: another writer holds the store (${describeLeaseHolder(error.holder)})`);
+    return { status: "skipped", holder: error.holder };
+  }
+}
+
+/**
+ * A disposable worker child writes on its parent's authority, and that authority
+ * is the parent's lease. The check is attribution and invocation binding — it
+ * decides whether this invocation may write and which process is to be named —
+ * NOT mutual exclusion: exclusion rests on the store's own SQLite write lock
+ * plus the parent's lease held across the whole pass. Trusting a transport marker
+ * instead would let an ambient environment variable, or a hand-invoked private
+ * verb, write to a store its caller does not own.
+ */
+function requireParentLease(dbPath: string): void {
+  const holder = readWriterLease(dbPath);
+  if (holder?.pid === process.ppid) return;
+  throw new WriterLeaseBusyError(
+    writerLockPath(dbPath),
+    holder,
+    `worker authority check failed: parent does not hold the lease (${describeLeaseHolder(holder)})`,
+  );
+}
+
+/**
+ * Zero-work summary for a scheduled pass that yielded the store. It reports no
+ * work instead of a fabricated ingestion, and names the holder that owns the
+ * store until it finishes.
+ */
+function skippedSyncSummary(
+  limits: SyncBudgets,
+  started: number,
+  pressureMode: "auto" | "off",
+  readPressure: () => PressureSnapshot,
+  holder: WriterLeaseMetadata | null,
+): SyncSummary {
+  const pressure = pressureMode === "auto" ? readPressure() : pressureOffSnapshot();
+  return {
+    type: "sync_summary",
+    schema_version: 2,
+    outcome: "complete",
+    elapsed_ms: performance.now() - started,
+    timing: { scan_ms: 0, queue_ms: 0, workers_ms: 0, maintenance_ms: 0, derive_ms: 0 },
+    discovered: 0,
+    queued_at_start: 0,
+    sessions_admitted: 0,
+    lanes: { fresh: 0, backlog: 0 },
+    worker_processes: 0,
+    worker_attempts: 0,
+    retries_scheduled: 0,
+    completed: 0,
+    results: {},
+    work: { ...emptyWork(), unavailable_worker_reports: 0, source_bytes_reserved: 0 },
+    pending: { total: 0, eligible: 0, retrying: 0 },
+    budgets: { ...limits, exhausted: [], effective: effectiveLimits(limits, DEFAULT_PRESSURE_STATE, pressure) },
+    pressure: { mode: pressureMode, initial: pressure, final: pressure, state: { ...DEFAULT_PRESSURE_STATE } },
+    maintenance: limits.maintenanceMs === 0 ? { status: "disabled" } : { status: "skipped" },
+    skipped: { reason: "writer_busy", holder },
+  };
+}
+
+/** One worker wave: each child's report, or `null` for a child the wall stopped. */
+interface WaveWait {
+  expired: boolean;
+  invocations: Array<WorkerInvocation | null>;
+}
+
+/**
+ * Wait for one worker wave, but never past the pass's own wall deadline. The
+ * children are disposable and ours, so expiry aborts them through the same kill
+ * sequence their own deadlines use — a pid-scoped kill — and waits for that
+ * sequence to finish reaping them: the lease must not be released underneath a
+ * dying writer. A child that never closes its stdout cannot keep this await
+ * pending, because the abort settles it, and a sibling that already reported
+ * keeps its real result: only the children still pending at the clock are
+ * wall-stopped.
+ */
+async function awaitWorkerWave(
+  jobs: SyncWorkerJob[],
+  wallRemainingMs: number,
+  run: (job: SyncWorkerJob, signal: AbortSignal) => Promise<WorkerInvocation>,
+): Promise<WaveWait> {
+  const abort = new AbortController();
+  const invocations: Array<WorkerInvocation | null> = jobs.map(() => null);
+  const wave = Promise.all(jobs.map((job, index) => run(job, abort.signal).then((invocation) => {
+    invocations[index] = invocation;
+    return invocation;
+  })));
+  let expired = false;
+  // The clock is cleared either way: a pass that finishes early must not keep a
+  // pending timer alive for the rest of its wall budget.
+  const stopped = Promise.withResolvers<void>();
+  const clock = setTimeout(() => { expired = true; stopped.resolve(); }, wallRemainingMs);
+  void wave.then(() => stopped.resolve(), () => stopped.resolve());
+  await stopped.promise;
+  clearTimeout(clock);
+  // A rejected runner still fails the pass, exactly as it did without the race.
+  if (!expired) { await wave; return { expired: false, invocations }; }
+  // Snapshot before the abort: what has reported by now is a report, and what
+  // the abort is about to stop must not be mistaken for one.
+  const reported = [...invocations];
+  abort.abort();
+  const reaped = Promise.withResolvers<void>();
+  const reap = setTimeout(reaped.resolve, readWaveReapMs());
+  void wave.then(() => reaped.resolve(), () => reaped.resolve());
+  await reaped.promise;
+  clearTimeout(reap);
+  return { expired: true, invocations: reported };
+}
+
+export class SyncPreparationError extends Error {
+  readonly code: string;
+  constructor(status: string) {
+    super(`Sync preparation ${status}; initialization/discovery did not complete. The committed store and discovery checkpoint remain authoritative; retry a bounded sync.`);
+    this.name = "SyncPreparationError";
+    this.code = status === "timed_out" ? "SYNC_WALL_TIMEOUT" : "SYNC_PREPARATION_FAILED";
+  }
+}
+
+function validatePreparationJob(input: unknown): SyncPreparationJob {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("invalid_preparation_job");
+  const job = input as SyncPreparationJob;
+  if (job.protocol_version !== SYNC_PROTOCOL_VERSION || typeof job.db_path !== "string" || !job.db_path ||
+    (job.sources !== undefined && (!Array.isArray(job.sources) || job.sources.some(source => typeof source !== "string"))) ||
+    (job.roots !== undefined && (!job.roots || typeof job.roots !== "object" || Array.isArray(job.roots) || Object.values(job.roots).some(root => typeof root !== "string")))) {
+    throw new Error("invalid_preparation_job");
+  }
+  positiveInteger(job.scan_limit, "scan limit");
+  positiveInteger(job.max_record_bytes, "max record bytes");
+  return job;
+}
+
+export async function executeSyncPreparationStdio(): Promise<void> {
+  const job = validatePreparationJob(JSON.parse(await readBoundedProtocol(Bun.stdin.stream())));
+  requireParentLease(job.db_path);
+  try {
+    const result = await prepareSyncStore(job);
+    process.stdout.write(JSON.stringify(result) + "\n");
+  } catch (error) {
+    // Preserve typed schema/operator failures without allowing arbitrary stdout
+    // to masquerade as a successful phase. No source bodies in protocol errors.
+    const message = error instanceof Error ? error.message : String(error);
+    process.stdout.write(JSON.stringify({ protocol_version: SYNC_PROTOCOL_VERSION,
+      type: "sync_preparation_error", code: message.includes("schema version") ? "SCHEMA_MISMATCH" : "SYNC_PREPARATION_FAILED",
+      message: message.slice(0, 2048) }) + "\n");
+  }
+}
+
+interface PreparationFailure { protocol_version: 2; type: "sync_preparation_error"; code: string; message: string }
+function parsePreparationReply(raw: string): SyncPreparationReply | PreparationFailure | null {
+  try {
+    const reply = JSON.parse(raw);
+    if (reply.protocol_version !== SYNC_PROTOCOL_VERSION) return null;
+    if (reply.type === "sync_preparation_error" && typeof reply.code === "string" && typeof reply.message === "string") return reply;
+    if (reply.type !== "sync_preparation_result" || !Number.isSafeInteger(reply.discovered) || reply.discovered < 0 ||
+      ![reply.init_ms, reply.scan_ms, reply.queue_ms].every(value => Number.isFinite(value) && value >= 0)) return null;
+    return reply;
+  } catch { return null; }
+}
+
+async function prepareInChild(options: SyncOptions, scanLimit: number, maxRecordBytes: number, remaining: number): Promise<SyncPreparationReply> {
+  if (remaining <= 0) throw new SyncPreparationError("timed_out");
+  const result = await spawnJsonChild<SyncPreparationReply | PreparationFailure>({ protocol_version: SYNC_PROTOCOL_VERSION,
+    db_path: options.dbPath, sources: options.sources, roots: options.roots, scan_limit: scanLimit, max_record_bytes: maxRecordBytes },
+    remaining, options.preparationCommand ?? [process.execPath, fileURLToPath(new URL("../bin/ledger-core.ts", import.meta.url)), "__sync-prepare"],
+    parsePreparationReply, { label: "sync_preparation" });
+  if (result.status !== "ok" || !result.reply) throw new SyncPreparationError(result.status);
+  if (result.reply.type === "sync_preparation_error") {
+    const error = new SyncPreparationError("failed");
+    Object.assign(error, { code: result.reply.code, message: result.reply.message });
+    throw error;
+  }
+  return result.reply;
+}
+
+export async function runSync(options: SyncOptions, dependencies: SyncDependencies = {}): Promise<SyncSummary> {
+  if (!options.dbPath) throw new Error("dbPath is required");
+  const limits = budgets(options.budgets);
+  if (limits.freshSessions > limits.sessions) throw new Error("fresh session budget cannot exceed session budget");
+  const maxRecordBytes = positiveInteger(options.maxRecordBytes ?? DEFAULT_INGEST_RECORD_BYTES, "max record bytes");
+  if (limits.chunkBytes > maxRecordBytes) throw new Error("sync chunk bytes cannot exceed max record bytes");
+  const scanLimit = positiveInteger(options.scanLimit ?? 1000, "scan limit");
+  const scan = dependencies.scan ?? scanSessions;
+  const runWorker = dependencies.runWorker ?? spawnSyncWorker;
+  const runMaintenance = dependencies.runMaintenance ?? spawnSyncMaintenance;
+  const readPressure = dependencies.pressure ?? samplePressure;
+  const now = dependencies.now ?? (() => new Date());
+  const pressureMode = options.pressureMode ?? "auto";
+  const started = performance.now();
+  const workDeadline = Math.max(1, limits.wallMs - limits.maintenanceMs);
+  // The lease attaches before the store handle: a refused or skipped pass must
+  // leave the database exactly as it found it.
+  const lease = acquireSyncLease(options.dbPath);
+  if (lease.status === "skipped") {
+    return skippedSyncSummary(limits, started, pressureMode, readPressure, lease.holder);
+  }
+  const held = lease.status === "held" ? lease.lease : null;
+  try {
+    const exhausted = new Set<string>();
+    // The pass's own deadline is the one exhaustion the pass owns, and it gets its
+    // own outcome instead of hiding behind the per-worker and per-budget keys that
+    // share `exhausted` (`wall_time` is also a worker budget boundary).
+    let wallBudgetExceeded = false;
+    const exhaustWallBudget = (): void => { exhausted.add("wall_time"); wallBudgetExceeded = true; };
+    const work = { ...emptyWork(), unavailable_worker_reports: 0, source_bytes_reserved: 0 };
+    const results: Record<string, number> = {};
+    let workerProcesses = 0;
+    let workerAttempts = 0;
+    let retriesScheduled = 0;
+    let completed = 0;
+    let maintenance: MaintenanceInvocation = limits.maintenanceMs === 0 ? { status: "disabled" } : { status: "skipped" };
+    let scanMs = 0;
+    let queueMs = 0;
+    let workersMs = 0;
+    let maintenanceMs = 0;
+    let deriveMs = 0;
+    const initialPressure = pressureMode === "auto" ? readPressure() : pressureOffSnapshot();
+    const preparationStarted = performance.now();
+    const prepared = !dependencies.scan && !isMemoryStorePath(options.dbPath)
+      ? await prepareInChild(options, scanLimit, maxRecordBytes, Math.floor(workDeadline - (performance.now() - started)))
+      : null;
+    const preparationMs = performance.now() - preparationStarted;
+    const db = new TrajectoryDb(options.dbPath, { initialize: prepared === null });
+    let dbClosed = false;
+    try {
+      let finalPressure = initialPressure;
+      let pressureState = pressureMode === "auto" ? db.getAdaptivePressureState() : { ...DEFAULT_PRESSURE_STATE };
+      let pressureReducedThisRun = false;
+      if (pressureMode === "auto") {
+        const decision = adaptPressure(pressureState, initialPressure);
+        pressureState = decision.state;
+        pressureReducedThisRun = initialPressure.severity === "constrained" || initialPressure.severity === "critical";
+        db.setAdaptivePressureState(pressureState, now().toISOString());
+        if (decision.pause) exhausted.add("pressure");
+      }
+      let effective = effectiveLimits(limits, pressureState, initialPressure);
+      // The derive-rule counter's one-shot runs here, under the writer lease,
+      // before in-process admission and before workers on the prepared path.
+      // It is skipped under critical pressure exactly like the maintenance
+      // child — a rebuild is the kind of heavy one-shot this pass defers, and
+      // the flag is durable, so the next pass picks it up. A failure
+      // propagates: the store could not re-project its own canonical records,
+      // which is a broken store, not a pass that ran out of budget.
+      if (!exhausted.has("pressure")) {
+        const deriveStarted = performance.now();
+        if (db.reindexFts()) deriveMs = performance.now() - deriveStarted;
+      }
+      let discoveredCount = prepared?.discovered ?? 0;
+      scanMs = prepared?.scan_ms ?? 0;
+      queueMs = prepared?.queue_ms ?? 0;
+      if (!prepared) {
+        // Injectable scans are a deterministic test seam; file-backed production
+        // never enters this in-process branch. The default memory store is local.
+        const scanStarted = performance.now();
+        let clock: ReturnType<typeof setTimeout> | undefined;
+        const remaining = Math.max(1, workDeadline - (performance.now() - started));
+        try {
+          const result = await Promise.race([
+            scan({ sources: options.sources, roots: options.roots, limit: scanLimit, discovery: db.getDiscoveryCheckpoints() }),
+            new Promise<never>((_, reject) => { clock = setTimeout(() => reject(new SyncPreparationError("timed_out")), remaining); }),
+          ]);
+          discoveredCount = result.sessions.length;
+          scanMs = performance.now() - scanStarted;
+          const admissionStarted = performance.now();
+          db.admitDiscovery(result, item => sessionNeedsIngest(db, item, { maxRecordBytes }), now());
+          queueMs = performance.now() - admissionStarted;
+        } finally { clearTimeout(clock); }
+      }
+      const queueStarted = performance.now();
+      if (performance.now() - started >= workDeadline) exhaustWallBudget();
+
+      const queuedAtStart = db.getIngestQueueSummary(now().toISOString()).total;
+      const cutoff = new Date(now().getTime() - limits.freshWindowMs).toISOString();
+      const selected = exhausted.size ? { items: [], fresh: 0, backlog: 0 }
+        : db.getQueuedIngestLanes(effective.sessions, effective.freshSessions, cutoff, now().toISOString());
+      queueMs += performance.now() - queueStarted;
+      const readyAtStart = db.getIngestQueueSummary(now().toISOString()).eligible;
+      // An empty selection because an earlier boundary (wall, pressure) stopped the
+      // pass before admission is not the session budget's doing: with no lane
+      // admitted there is no admission to call limited.
+      const sessionBudgetLimited = selected.items.length > 0 && readyAtStart > selected.items.length;
+      const queue = [...selected.items];
+      let sessionAttemptsLimited = false;
+      let budgetCharge = 0;
+      let failedAttempts = 0;
+
+      while (queue.length > 0 && exhausted.size === 0) {
+        const elapsed = performance.now() - started;
+        if (elapsed >= workDeadline) { exhaustWallBudget(); break; }
+        if (workerProcesses >= effective.sessions) { exhausted.add("sessions"); break; }
+        if (budgetCharge >= effective.sourceBytes) { exhausted.add("source_bytes"); break; }
+        if (failedAttempts >= Math.max(1, limits.retries)) { exhausted.add("retries"); break; }
+
+        if (pressureMode === "auto") {
+          const sampled = readPressure();
+          finalPressure = sampled;
+          if (sampled.severity === "critical") {
+            if (pressureState.last_severity !== "critical") pressureState = adaptPressure(pressureState, sampled).state;
+            pressureReducedThisRun = true;
+            db.setAdaptivePressureState(pressureState, now().toISOString());
+            exhausted.add("pressure");
+            break;
+          }
+          if (sampled.severity === "constrained" && !pressureReducedThisRun) {
+            pressureState = adaptPressure(pressureState, sampled).state;
+            pressureReducedThisRun = true;
+            db.setAdaptivePressureState(pressureState, now().toISOString());
+            effective = effectiveLimits(limits, pressureState, sampled);
+          }
+        }
+
+        const remainingFailureSlots = Math.max(1, limits.retries) - failedAttempts;
+        const maxWave = Math.min(effective.workers, remainingFailureSlots, queue.length, effective.sessions - workerProcesses);
+        const wave: Array<{ item: IngestQueueEntry; reservation: number; job: SyncWorkerJob }> = [];
+        let available = effective.sourceBytes - budgetCharge;
+        while (wave.length < maxWave && queue.length > 0 && available > 0) {
+          const item = queue[0];
+          const remainingSlots = maxWave - wave.length;
+          const fairShare = Math.max(1, Math.floor(available / remainingSlots));
+          const desired = workerReservation(item, limits, fairShare);
+          queue.shift();
+          const reservation = desired;
+          available -= reservation;
+          const remainingWall = Math.max(1, Math.floor(workDeadline - elapsed));
+          wave.push({
+            item,
+            reservation,
+            job: {
+              protocol_version: SYNC_PROTOCOL_VERSION,
+              db_path: options.dbPath,
+              item,
+              max_chunk_bytes: Math.min(limits.chunkBytes, maxRecordBytes),
+              max_record_bytes: maxRecordBytes,
+              max_source_bytes: reservation,
+              read_bytes_per_second: Math.max(1, Math.floor(effective.readBytesPerSecond / maxWave)),
+              max_wall_ms: Math.min(limits.workerMs, remainingWall),
+              max_attempts: limits.attemptsPerSession,
+            },
+          });
+        }
+        if (wave.length === 0) { exhausted.add("source_bytes"); break; }
+        workerProcesses += wave.length;
+        work.source_bytes_reserved += wave.reduce((sum, entry) => sum + entry.reservation, 0);
+        const workersStarted = performance.now();
+        const workerCommand = options.workerCommand ?? workerEntry();
+        // The pass owns the deadline: the wave is waited for at most the wall that
+        // is actually left, whatever the runners do with their own budgets.
+        const wallRemaining = Math.max(0, Math.ceil(workDeadline - (performance.now() - started)));
+        const waited = await awaitWorkerWave(wave.map(entry => entry.job), wallRemaining,
+          (job, signal) => runWorker(job, job.max_wall_ms, workerCommand, signal));
+        workersMs += performance.now() - workersStarted;
+        // The deadline is the pass's boundary, not the session's: nothing is
+        // failed or backed off for it, and a sibling that already reported keeps
+        // its real result below.
+        if (waited.expired) exhaustWallBudget();
+
+        for (let index = 0; index < wave.length; index++) {
+          const { item, reservation, job } = wave[index];
+          const reported = waited.invocations[index];
+          if (reported === null) {
+            // Stopped at the wall with its reads unknown: keep the reservation
+            // charged and the session durably queued for the next pass.
+            budgetCharge += reservation;
+            workerAttempts++;
+            work.unavailable_worker_reports++;
+            results.timed_out = (results.timed_out ?? 0) + 1;
+            continue;
+          }
+          let invocation = reported;
+          const reply = invocation.reply;
+          if (reply && (reply.work.source_bytes_read > reservation || reply.attempts > job.max_attempts)) {
+            invocation = { status: "protocol_error" };
+          }
+          const acceptedReply = invocation.status === "ok" ? invocation.reply : undefined;
+          if (acceptedReply) {
+            budgetCharge += acceptedReply.work.source_bytes_read;
+            addWork(work, acceptedReply.work);
+            workerAttempts += acceptedReply.attempts;
+            addCounts(results, acceptedReply.results);
+          } else {
+            budgetCharge += reservation;
+            workerAttempts++;
+            work.unavailable_worker_reports++;
+          }
+
+          if (invocation.status !== "ok" || !acceptedReply || acceptedReply.outcome === "error") {
+            failedAttempts++;
+            retriesScheduled++;
+            const stamp = now();
+            const status = invocation.status === "ok" ? acceptedReply?.error_code ?? "worker_error" : invocation.status;
+            db.markQueuedIngestRetry(item, status, retryAt(stamp, item.attempt_count), stamp.toISOString());
+            results[status] = (results[status] ?? 0) + 1;
+            continue;
+          }
+          if (acceptedReply.outcome === "budget_exhausted") {
+            const workerBudget = acceptedReply.budget ?? "worker_budget";
+            if (workerBudget === "source_bytes") {
+              budgetCharge += reservation - acceptedReply.work.source_bytes_read;
+            }
+            // A worker whose wall budget was the pass's remaining wall reports the
+            // pass's own boundary: it spent what was left, or could not finish
+            // inside it. A worker budget under the wall stays the worker's own.
+            if (workerBudget === "wall_time" && job.max_wall_ms < limits.workerMs) exhaustWallBudget();
+            else if (workerBudget !== "source_bytes" || budgetCharge >= effective.sourceBytes) exhausted.add(workerBudget);
+            db.markQueuedIngestProgress(item, `pending_${acceptedReply.budget ?? "worker_budget"}`, now().toISOString());
+            results.budget_exhausted = (results.budget_exhausted ?? 0) + 1;
+            continue;
+          }
+          if (!acceptedReply.needs_ingest_after || acceptedReply.results.tombstoned) {
+            // The planner re-checks `sessionNeedsIngest`, but a listing the store
+            // itself refused — the committed id of a grouped source's member file —
+            // still looks ingestable to it, because the group mapping is only
+            // visible after the read. Its answer is final: the session was deleted
+            // by the user, so the item leaves the queue instead of returning as a
+            // retry every pass. A later scan enqueues it again if the deletion is
+            // ever undone, since discovery is what fills the queue.
+            db.removeQueuedIngest(item);
+            completed++;
+          } else if (acceptedReply.stalled || !acceptedReply.cursor_changed) {
+            failedAttempts++;
+            retriesScheduled++;
+            const stamp = now();
+            db.markQueuedIngestRetry(item, "no_progress", retryAt(stamp, item.attempt_count), stamp.toISOString());
+            results.no_progress = (results.no_progress ?? 0) + 1;
+          } else {
+            sessionAttemptsLimited ||= acceptedReply.attempts >= limits.attemptsPerSession;
+            db.markQueuedIngestProgress(item, "progress", now().toISOString());
+          }
+        }
+        // The wall is spent: the admissions stop here and the queue keeps what
+        // this pass did not get to.
+        if (waited.expired) break;
+      }
+
+      const pending = db.getIngestQueueSummary(now().toISOString());
+      const discovery = db.getDiscoverySummary();
+      if (discovery?.pending_sources) exhausted.add("discovery");
+      if (pending.total > 0 && sessionBudgetLimited) exhausted.add("sessions");
+      if (pending.total > 0 && sessionAttemptsLimited) exhausted.add("session_attempts");
+      if (pressureMode === "auto") {
+        finalPressure = readPressure();
+        if (finalPressure.severity === "critical") exhausted.add("pressure");
+      }
+
+      const maintenanceRemaining = Math.floor(limits.wallMs - (performance.now() - started));
+      if (limits.maintenanceMs > 0 && work.source_bytes_read === 0 &&
+        !exhausted.has("pressure") && maintenanceRemaining > 0) {
+        const timeout = Math.min(limits.maintenanceMs, maintenanceRemaining);
+        const maintenanceStarted = performance.now();
+        db.close();
+        dbClosed = true;
+        maintenance = await runMaintenance({
+          protocol_version: SYNC_PROTOCOL_VERSION,
+          db_path: options.dbPath,
+          fts_merge_pages: limits.ftsMergePages,
+          wal_autocheckpoint_pages: DEFAULT_WAL_AUTOCHECKPOINT_PAGES,
+        }, timeout, options.maintenanceCommand ?? maintenanceEntry());
+        maintenanceMs = performance.now() - maintenanceStarted;
+      }
+
+      const outcome: SyncSummary["outcome"] = pending.total === 0 && !discovery?.pending_sources ? "complete"
+        : exhausted.has("pressure") ? "pending_pressure"
+          : wallBudgetExceeded ? "wall_budget_exceeded"
+            : exhausted.size > 0 && !(exhausted.size === 1 && exhausted.has("retries")) ? "pending_budget"
+              : pending.retrying > 0 || exhausted.has("retries") ? "pending_retry" : "pending";
+      // Post-pass durable coverage signal (issue #37): how many sources stand
+      // degraded after this pass recorded its verdicts. Maintenance closes the
+      // writer handle, so re-read through a short-lived reader when needed; the
+      // read-only reader never migrates, so this cannot reopen the write path.
+      let coverageSignal: ReturnType<TrajectoryDb["getSourceCoverageSummary"]> = null;
+      if (!dbClosed) {
+        coverageSignal = db.getSourceCoverageSummary();
+      } else {
+        try {
+          const reader = new TrajectoryReader(options.dbPath);
+          try {
+            coverageSignal = reader.getSourceCoverageSummary();
+          } finally {
+            reader.close();
+          }
+        } catch {
+          // In-memory stores and never-materialized paths have no reader
+          // surface; the signal is simply unknown for this pass.
+          coverageSignal = null;
+        }
+      }
+      return {
+        type: "sync_summary",
+        schema_version: 2,
+        completion_scope: "known_work",
+        ...(discovery ? { discovery } : {}),
+        preparation_ms: preparationMs,
+        outcome,
+        elapsed_ms: performance.now() - started,
+        timing: { scan_ms: scanMs, queue_ms: queueMs, workers_ms: workersMs, maintenance_ms: maintenanceMs, derive_ms: deriveMs },
+        discovered: discoveredCount,
+        queued_at_start: queuedAtStart,
+        sessions_admitted: selected.items.length,
+        lanes: { fresh: selected.fresh, backlog: selected.backlog },
+        worker_processes: workerProcesses,
+        worker_attempts: workerAttempts,
+        retries_scheduled: retriesScheduled,
+        completed,
+        results,
+        work,
+        pending,
+        budgets: { ...limits, exhausted: [...exhausted].sort(), effective },
+        pressure: { mode: pressureMode, initial: initialPressure, final: finalPressure, state: pressureState },
+        maintenance,
+        ...(coverageSignal ? { coverage: coverageSignal } : {}),
+      };
+    } finally {
+      if (!dbClosed) db.close();
+    }
+  } finally {
+    held?.close();
+  }
+}