@sgtbeatdown/pi-tasks 0.1.14 → 0.1.16

package/src/task-store.ts

@@ -1,4 +1,5 @@
-import { TERMINAL_INTENT_OPERATION, TaskProtocolError } from "./task-protocol";
+import { TASK_WORK_LIMITS } from "./task-work-scope";
+import { TASK_EVENT_TYPES, TERMINAL_INTENT_OPERATION, TaskProtocolError } from "./task-protocol";
 import type { RelayTransportBinding, RelayEnvelope, TaskEndpoint, TaskEvent, TaskRecord, TaskSnapshot, TerminalDeliveryState, TerminalTaskIntentType } from "./task-protocol";
 
 export interface TaskStoreOptions {
@@ -16,29 +17,64 @@ export interface TaskOperationRecord {
   readonly taskId: string; readonly operation: string; readonly logicalId: string;
   readonly logicalType: string; readonly envelopeIds: readonly string[];
 }
+export interface PresentationRecord { readonly taskId: string; readonly eventId: string; }
+export interface PendingPresentation extends PresentationRecord { readonly order: number; }
 export interface TaskStore {
   transaction<T>(operation: () => T): T;
+  /** Synchronous hook after each top-level commit or non-transactional write; a throwing listener is isolated and logged. */
+  onChange(listener: () => void): () => void;
   putTask(task: Omit<TaskRecord, "events">): void;
   getTask(taskId: string): TaskSnapshot | undefined;
   listTasks(): readonly TaskSnapshot[];
+  /** Whether any task of this lifetime is active; indexed, no snapshot is built. */
+  hasActiveTasks(): boolean;
   setStatus(taskId: string, status: TaskRecord["status"]): void;
+  /** Follows a reassignment; existing envelopes keep their addresses. */
+  setTarget(taskId: string, target: TaskEndpoint): void;
   appendEvent(event: TaskEvent): boolean;
   putOutbox(envelope: RelayEnvelope): void;
   outbox(state: OutboxRecord["state"]): readonly OutboxRecord[];
+  /** Indexed lookup, fair rotation and cooldown are required store capabilities. */
+  getOutboxRecord(envelopeId: string): OutboxRecord | undefined;
+  hasPendingOutbox(): boolean;
+  /** Rotates fairly but yields only each target's oldest pending envelope (per-target FIFO). */
+  selectPendingOutbox(limit: number, now: number, maxInspections?: number): readonly OutboxRecord[];
+  /** Older pending envelopes to the same target, oldest first; the envelope may be sent only once this is empty. */
+  pendingOutboxAhead(envelopeId: string): readonly string[];
+  outboxRetryAt(envelopeId: string): number;
+  postponeOutbox(envelopeId: string, until: number): void;
   markOutboxAccepted(envelopeId: string): void;
   quarantineOutbox(envelopeId: string, input: OutboxQuarantineInput): void;
   quarantinedOutbox(): readonly OutboxQuarantineRecord[];
+  /** Indexed lookup of one quarantined envelope. */
+  getQuarantine(envelopeId: string): OutboxQuarantineRecord | undefined;
   persistInbox(envelope: RelayEnvelope, cursor: string): boolean;
+  /** Store arrival order of a persisted inbox envelope; shares the presentation order sequence. */
+  inboxOrder(envelopeId: string): number | undefined;
+  inboxEnvelope(envelopeId: string): RelayEnvelope | undefined;
+  /** Origin-local canonical events awaiting Pi presentation; ids only, events stay in the task log. */
+  enqueuePresentation(details: PresentationRecord): void;
+  pendingPresentations(): readonly PendingPresentation[];
+  completePresentation(eventId: string): void;
   getReceiveCursor(): string;
   setReceiveCursor(cursor: string): void;
   trackRelayDeliveries(endpoint: TaskEndpoint, deliveries: readonly { readonly cursor: string; readonly envelopeId: string }[]): void;
   pendingRelayEnvelopeId(endpoint: TaskEndpoint, cursor: string): string | undefined;
-  requestRelayAcknowledgement(endpoint: TaskEndpoint, cursor: string): void;
-  requestedRelayAcknowledgements(endpoint: TaskEndpoint): readonly string[];
+  /** Tracked, unacknowledged deliveries in this endpoint scope, oldest cursor first. */
+  pendingRelayDeliveries(endpoint: TaskEndpoint): readonly { readonly cursor: string; readonly envelopeId: string }[];
+  /** Highest tracked cursor in this endpoint scope; intake fetches after it. */
+  relayIntakeCursor(endpoint: TaskEndpoint): string;
+  requestRelayAcknowledgement(endpoint: TaskEndpoint, cursor: string, retryAt?: number): void;
+  requestedRelayAcknowledgements(endpoint: TaskEndpoint, limit?: number, now?: number): readonly string[];
+  relayAcknowledgementRetryAt(endpoint: TaskEndpoint, cursor: string): number;
   acknowledgeRelayCursor(endpoint: TaskEndpoint, cursor: string): void;
   putIntent(intentId: string, taskId: string, envelopeId: string): void;
+  /** Locally submitted intent only; retained through acceptance or quarantine in this RAM lifetime. */
+  getIntentEnvelope(intentId: string): RelayEnvelope | undefined;
   putInsertionReceipt(taskId: string, eventId: string): boolean;
   reserveTaskOperation(input: TaskOperationRecord): { readonly created: boolean; readonly record: TaskOperationRecord };
+  /** Withdraws a reservation whose envelopes were never offered to the relay, with its pending envelopes and intent row. */
+  discardUnsentOperation(taskId: string, operation: string): void;
   getEndpointGeneration(): string | undefined;
   setEndpointGeneration(generation: string): void;
   getEndpointBinding(): TaskEndpoint | undefined;
@@ -50,9 +86,15 @@ export interface TaskStore {
 }
 
 const LIMITS = { entries: 16_384, bytes: 32 * 1024 * 1024 };
-type Cell = { readonly text: string; readonly bytes: number; readonly order: number };
-type Undo = { readonly table: Map<string, Cell>; readonly key: string; readonly prior: Cell | undefined };
-interface Checkpoint { frontier: string; highWater: string; pending: Record<string, string>; requested: Record<string, true>; }
+// `text` is the immutable source of truth and of the byte charge; `value` is its lazily parsed, deep-frozen form.
+type Cell = { readonly text: string; readonly bytes: number; readonly order: number; value?: unknown };
+type Undo = { readonly name: string; readonly table: Map<string, Cell>; readonly key: string; readonly prior: Cell | undefined };
+interface Checkpoint { frontier: string; highWater: string; pending: Record<string, string>; requested: Record<string, number>; }
+const freeze = <T>(value: T): T => {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) { Object.freeze(value); for (const child of Object.values(value)) freeze(child); }
+  return value;
+};
+const read = <T>(row: Cell): T => (row.value ??= freeze(JSON.parse(row.text))) as T;
 
 /** One endpoint lifetime. No SQLite, files, migrations, startup reads or replay. */
 export function createTaskStore(options: TaskStoreOptions = {}): TaskStore {
@@ -61,29 +103,74 @@ export function createTaskStore(options: TaskStoreOptions = {}): TaskStore {
   if (!Number.isInteger(maxEntries) || maxEntries < 1 || maxEntries > LIMITS.entries || !Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > LIMITS.bytes) throw new TypeError("invalid task memory limit");
   const tables = new Map<string, Map<string, Cell>>();
   const frames: Map<string, Undo>[] = [];
+  // ID-only retry rotation, bounded by the existing pending outbox; no payload copy.
+  const pendingOutbox = new Map<string, number>();
+  // Per-target FIFO: pending ids grouped by target; outbox cell order is creation order.
+  const pendingByTarget = new Map<string, Set<string>>(), pendingTarget = new Map<string, string>();
+  const syncPendingOutbox = (id: string) => {
+    const row = tables.get("outbox")?.get(id);
+    const record = row && read<OutboxRecord>(row);
+    if (record?.state === "pending") {
+      if (!pendingOutbox.has(id)) pendingOutbox.set(id, 0);
+      if (!pendingTarget.has(id)) {
+        const key = pair(record.envelope.target.relay, record.envelope.target.id);
+        pendingTarget.set(id, key);
+        const ids = pendingByTarget.get(key) ?? new Set<string>(); ids.add(id); pendingByTarget.set(key, ids);
+      }
+    } else {
+      pendingOutbox.delete(id);
+      const key = pendingTarget.get(id);
+      if (key !== undefined) { pendingTarget.delete(id); const ids = pendingByTarget.get(key)!; ids.delete(id); if (!ids.size) pendingByTarget.delete(key); }
+    }
+  };
+  const outboxOrder = (id: string) => tables.get("outbox")!.get(id)!.order;
+  const pendingAhead = (id: string): string[] => {
+    const key = pendingTarget.get(id); if (key === undefined) return [];
+    const order = outboxOrder(id);
+    return [...pendingByTarget.get(key)!].filter(other => outboxOrder(other) < order).sort((a, b) => outboxOrder(a) - outboxOrder(b));
+  };
+  // Cell-derived indexes, updated with every cell change including rollback; never a second copy of the data.
+  const eventsByTask = new Map<string, Set<string>>(), activeTasks = new Set<string>();
+  const reindex = (name: string, key: string, before: Cell | undefined, after: Cell | undefined) => {
+    if (name === "tasks") {
+      if (after && read<TaskRecord>(after).status === "active") activeTasks.add(key); else activeTasks.delete(key);
+    } else if (name === "events") {
+      if (before) { const taskId = read<TaskEvent>(before).taskId, ids = eventsByTask.get(taskId); ids?.delete(key); if (ids?.size === 0) eventsByTask.delete(taskId); }
+      if (after) { const taskId = read<TaskEvent>(after).taskId, ids = eventsByTask.get(taskId) ?? new Set<string>(); ids.add(key); eventsByTask.set(taskId, ids); }
+    }
+  };
   let bytes = 0, entries = 0, sequence = 0, closed = false;
+  const listeners = new Set<() => void>();
+  // Listeners run after state is final; a failure is logged, not rethrown, because the write already committed.
+  const notify = () => { for (const listener of [...listeners]) { try { listener(); } catch (error) { console.error("pi-tasks: task store change listener failed", error); } } };
+  // Top-level writes refresh the pending-outbox index before notifying so listeners see committed state.
+  const committed = (name: string, key: string) => { if (frames.length) return; if (name === "outbox") syncPendingOutbox(key); notify(); };
   const remember = (name: string, key: string, target: Map<string, Cell>, prior: Cell | undefined) => {
     const frame = frames.at(-1), identity = JSON.stringify([name, key]);
-    if (frame && !frame.has(identity)) frame.set(identity, { table: target, key, prior });
+    if (frame && !frame.has(identity)) frame.set(identity, { name, table: target, key, prior });
   };
   const check = () => { if (closed) throw new TaskProtocolError("RELAY_CLOSED", "task state is closed", { retryable: false }); };
   const table = (name: string) => { check(); let value = tables.get(name); if (!value) { value = new Map(); tables.set(name, value); } return value; };
-  const get = <T>(name: string, key: string): T | undefined => { const row = table(name).get(key); return row ? JSON.parse(row.text) as T : undefined; };
-  const rows = <T>(name: string): T[] => [...table(name).values()].sort((a, b) => a.order - b.order).map(row => JSON.parse(row.text) as T);
+  const get = <T>(name: string, key: string): T | undefined => { const row = table(name).get(key); return row ? read<T>(row) : undefined; };
+  const rows = <T>(name: string): T[] => [...table(name).values()].sort((a, b) => a.order - b.order).map(row => read<T>(row));
+  const taskEvents = (taskId: string): TaskEvent[] => { const events = table("events"); return [...eventsByTask.get(taskId) ?? []].map(id => read<TaskEvent>(events.get(id)!)); };
   const put = (name: string, key: string, value: unknown, onlyNew = false): boolean => {
     const target = table(name), prior = target.get(key);
     if (onlyNew && prior) return false;
     const text = JSON.stringify(value), size = Buffer.byteLength(text) + Buffer.byteLength(key) + 64;
     if (bytes - (prior?.bytes ?? 0) + size > maxBytes || (!prior && entries >= maxEntries)) throw new TaskProtocolError("TASK_CAPACITY", "active task state is full", { retryable: false });
     remember(name, key, target, prior);
-    target.set(key, { text, bytes: size, order: prior?.order ?? sequence++ });
+    const cell = { text, bytes: size, order: prior?.order ?? sequence++ };
+    target.set(key, cell); reindex(name, key, prior, cell);
     bytes += size - (prior?.bytes ?? 0); if (!prior) entries++;
+    committed(name, key);
     return true;
   };
   const remove = (name: string, key: string) => {
     const target = table(name), prior = target.get(key); if (!prior) return;
     remember(name, key, target, prior);
-    target.delete(key); bytes -= prior.bytes; entries--;
+    target.delete(key); reindex(name, key, prior, undefined); bytes -= prior.bytes; entries--;
+    committed(name, key);
   };
   const pair = (a: string, b: string) => JSON.stringify([a, b]);
   const requireTask = (id: string) => { if (!get("tasks", id)) throw new TaskProtocolError("TASK_NOT_FOUND", "task is not active in this endpoint lifetime"); };
@@ -91,7 +178,8 @@ export function createTaskStore(options: TaskStoreOptions = {}): TaskStore {
   const terminal = (task: Omit<TaskRecord, "events">): TerminalDeliveryState => {
     const record = get<TaskOperationRecord>("operations", pair(task.taskId, TERMINAL_INTENT_OPERATION));
     if (!record) return { state: "not_submitted" };
-    if (!["task.completed", "task.failed", "task.cancelled"].includes(record.logicalType) || record.envelopeIds.length !== 1) throw new Error("terminal operation is malformed");
+    const type = TASK_EVENT_TYPES[record.logicalType];
+    if (!type?.terminal || !type.intent || record.envelopeIds.length !== 1) throw new Error("terminal operation is malformed");
     const identity = { intentId: record.logicalId, intentType: record.logicalType as TerminalTaskIntentType, envelopeId: record.envelopeIds[0]!, origin: task.origin };
     const outbox = get<OutboxRecord>("outbox", identity.envelopeId);
     if (outbox) return { state: outbox.state, ...identity };
@@ -106,43 +194,84 @@ export function createTaskStore(options: TaskStoreOptions = {}): TaskStore {
     if (bound && (bound.relay !== endpoint.relay || bound.id !== endpoint.id)) throw new TaskProtocolError("RELAY_RESET", "delivery checkpoint belongs to a retired endpoint", { retryable: false });
     return JSON.stringify([endpoint.relay, endpoint.id, store.getRelayTransportBinding()?.epoch]);
   };
-  const checkpoint = (endpoint: TaskEndpoint): Checkpoint => get<Checkpoint>("checkpoints", checkpointKey(endpoint)) ?? { frontier: store.getReceiveCursor(), highWater: store.getReceiveCursor(), pending: {}, requested: {} };
+  // A mutable copy: callers edit it before writing it back, and the cached cell value is frozen.
+  const checkpoint = (endpoint: TaskEndpoint): Checkpoint => structuredClone(get<Checkpoint>("checkpoints", checkpointKey(endpoint))) ?? { frontier: store.getReceiveCursor(), highWater: store.getReceiveCursor(), pending: {}, requested: {} };
   const writeCheckpoint = (endpoint: TaskEndpoint, value: Checkpoint) => { put("checkpoints", checkpointKey(endpoint), value); };
   const store: TaskStore = {
     transaction<T>(operation: () => T): T {
       check(); const priorBytes = bytes, priorEntries = entries, priorSequence = sequence;
       const frame = new Map<string, Undo>(); frames.push(frame);
+      let result: T, topLevelChange = false;
       try {
-        const result = operation();
+        result = operation();
         if (result instanceof Promise) throw new TypeError("task transactions must be synchronous");
         const parent = frames.at(-2);
-        if (parent) for (const [key, item] of frame) if (!parent.has(key)) parent.set(key, item);
-        return result;
+        if (parent) {
+          for (const [key, item] of frame) if (!parent.has(key)) parent.set(key, item);
+        } else {
+          for (const item of frame.values()) if (item.table === tables.get("outbox")) syncPendingOutbox(item.key);
+          topLevelChange = frame.size > 0;
+        }
       } catch (error) {
-        for (const item of [...frame.values()].reverse()) { if (item.prior) item.table.set(item.key, item.prior); else item.table.delete(item.key); }
+        for (const item of [...frame.values()].reverse()) {
+          const current = item.table.get(item.key);
+          if (item.prior) item.table.set(item.key, item.prior); else item.table.delete(item.key);
+          reindex(item.name, item.key, current, item.prior);
+        }
         bytes = priorBytes; entries = priorEntries; sequence = priorSequence;
         throw error;
       } finally { frames.pop(); }
+      if (topLevelChange) notify();
+      return result;
     },
+    onChange(listener) { const entry = () => listener(); listeners.add(entry); return () => { listeners.delete(entry); }; },
     putTask(task) { put("tasks", task.taskId, task, true); },
-    getTask(id) { const task = get<Omit<TaskRecord, "events">>("tasks", id); return task ? snapshot(task, rows<TaskEvent>("events").filter(event => event.taskId === id)) : undefined; },
+    getTask(id) { const task = get<Omit<TaskRecord, "events">>("tasks", id); return task ? snapshot(task, taskEvents(id)) : undefined; },
     listTasks() {
-      const events = new Map<string, TaskEvent[]>();
-      for (const event of rows<TaskEvent>("events")) { const list = events.get(event.taskId) ?? []; list.push(event); events.set(event.taskId, list); }
-      return rows<Omit<TaskRecord, "events">>("tasks").sort((a, b) => a.createdAt - b.createdAt || a.taskId.localeCompare(b.taskId)).map(task => snapshot(task, events.get(task.taskId) ?? []));
+      return rows<Omit<TaskRecord, "events">>("tasks").sort((a, b) => a.createdAt - b.createdAt || a.taskId.localeCompare(b.taskId)).map(task => snapshot(task, taskEvents(task.taskId)));
     },
+    hasActiveTasks() { check(); return activeTasks.size > 0; },
     setStatus(id, status) { const task = get<Omit<TaskRecord, "events">>("tasks", id); if (task) put("tasks", id, { ...task, status }); },
+    setTarget(id, target) { const task = get<Omit<TaskRecord, "events">>("tasks", id); if (task) put("tasks", id, { ...task, target }); },
     appendEvent(event) { requireTask(event.taskId); return put("events", event.eventId, event, true); },
-    putOutbox(envelope) { put("outbox", envelope.envelopeId, { envelope, state: "pending" }, true); },
+    putOutbox(envelope) { put("outbox", envelope.envelopeId, { envelope, state: "pending" }, true); if (!frames.length) syncPendingOutbox(envelope.envelopeId); },
     outbox(status) { return rows<OutboxRecord>("outbox").filter(item => item.state === status); },
-    markOutboxAccepted(id) { const prior = get<OutboxRecord>("outbox", id); if (prior) put("outbox", id, { ...prior, state: "accepted" }); },
+    getOutboxRecord(id) { return get<OutboxRecord>("outbox", id); },
+    hasPendingOutbox() { check(); return pendingOutbox.size > 0; },
+    selectPendingOutbox(limit, now, maxInspections = TASK_WORK_LIMITS.retryInspections) {
+      check();
+      const selected: OutboxRecord[] = [];
+      // Also bound inspection when the queue is cooling down. Rotate even skipped IDs.
+      const inspections = Math.min(pendingOutbox.size, TASK_WORK_LIMITS.retryInspections, maxInspections);
+      for (let i = 0; i < inspections && selected.length < limit; i++) {
+        const [id, retryAt] = pendingOutbox.entries().next().value!;
+        pendingOutbox.delete(id); pendingOutbox.set(id, retryAt);
+        // Only a target's oldest pending envelope is sendable; inspecting any of its ids offers the head.
+        const head = pendingAhead(id)[0] ?? id;
+        if (pendingOutbox.get(head)! <= now && !selected.some(record => record.envelope.envelopeId === head)) {
+          const record = get<OutboxRecord>("outbox", head);
+          if (record?.state === "pending") selected.push(record);
+        }
+      }
+      return selected;
+    },
+    pendingOutboxAhead(id) { check(); return pendingAhead(id); },
+    outboxRetryAt(id) { check(); return pendingOutbox.get(id) ?? 0; },
+    postponeOutbox(id, until) { check(); if (pendingOutbox.has(id)) pendingOutbox.set(id, until); },
+    markOutboxAccepted(id) { const prior = get<OutboxRecord>("outbox", id); if (prior) put("outbox", id, { ...prior, state: "accepted" }); if (!frames.length) syncPendingOutbox(id); },
     quarantineOutbox(id, input) {
       store.transaction(() => { const prior = get<OutboxRecord>("outbox", id); if (!prior) return;
         put("quarantine", id, { ...input, envelope: prior.envelope, priorState: prior.state }, true); remove("outbox", id);
       });
     },
     quarantinedOutbox() { return rows<OutboxQuarantineRecord>("quarantine"); },
+    getQuarantine(id) { return get<OutboxQuarantineRecord>("quarantine", id); },
     persistInbox(envelope, cursor) { return put("inbox", envelope.envelopeId, { envelope, cursor }, true); },
+    inboxOrder(id) { return table("inbox").get(id)?.order; },
+    inboxEnvelope(id) { return get<{ envelope: RelayEnvelope }>("inbox", id)?.envelope; },
+    enqueuePresentation(details) { requireTask(details.taskId); put("presentation", details.eventId, { taskId: details.taskId, eventId: details.eventId }, true); },
+    pendingPresentations() { return [...table("presentation").values()].sort((a, b) => a.order - b.order).map(row => ({ ...read<PresentationRecord>(row), order: row.order })); },
+    completePresentation(eventId) { remove("presentation", eventId); },
     getReceiveCursor() { return state<string>("cursor") ?? "0"; },
     setReceiveCursor(cursor) { put("state", "cursor", cursor); },
     trackRelayDeliveries(endpoint, deliveries) {
@@ -156,12 +285,21 @@ export function createTaskStore(options: TaskStoreOptions = {}): TaskStore {
       writeCheckpoint(endpoint, value);
     },
     pendingRelayEnvelopeId(endpoint, cursor) { return checkpoint(endpoint).pending[cursor]; },
-    requestRelayAcknowledgement(endpoint, cursor) {
+    pendingRelayDeliveries(endpoint) {
+      return Object.entries(checkpoint(endpoint).pending).map(([cursor, envelopeId]) => ({ cursor, envelopeId }))
+        .sort((left, right) => BigInt(left.cursor) < BigInt(right.cursor) ? -1 : 1);
+    },
+    relayIntakeCursor(endpoint) { return checkpoint(endpoint).highWater; },
+    requestRelayAcknowledgement(endpoint, cursor, retryAt = 0) {
       const value = checkpoint(endpoint);
       if (value.pending[cursor] === undefined) throw new TaskProtocolError("INVALID_CURSOR", "relay delivery is not pending in this endpoint scope");
-      value.requested[cursor] = true; writeCheckpoint(endpoint, value);
+      value.requested[cursor] = retryAt; writeCheckpoint(endpoint, value);
     },
-    requestedRelayAcknowledgements(endpoint) { return Object.keys(checkpoint(endpoint).requested); },
+    requestedRelayAcknowledgements(endpoint, limit = Number.MAX_SAFE_INTEGER, now = Date.now()) {
+      const value = checkpoint(endpoint);
+      return Object.keys(value.requested).filter(cursor => value.requested[cursor]! <= now).slice(0, limit);
+    },
+    relayAcknowledgementRetryAt(endpoint, cursor) { return checkpoint(endpoint).requested[cursor] ?? 0; },
     acknowledgeRelayCursor(endpoint, cursor) {
       store.transaction(() => {
         const value = checkpoint(endpoint); if (value.pending[cursor] === undefined) return;
@@ -173,15 +311,31 @@ export function createTaskStore(options: TaskStoreOptions = {}): TaskStore {
       });
     },
     putIntent(intentId, taskId, envelopeId) { put("intents", intentId, { taskId, envelopeId }, true); },
+    getIntentEnvelope(intentId) {
+      const intent = get<{ taskId: string; envelopeId: string }>("intents", intentId);
+      if (!intent) return undefined;
+      const envelope = (get<OutboxRecord>("outbox", intent.envelopeId) ?? get<OutboxQuarantineRecord>("quarantine", intent.envelopeId))?.envelope;
+      return envelope?.taskId === intent.taskId ? envelope : undefined;
+    },
     putInsertionReceipt(taskId, eventId) { requireTask(taskId); return put("insertions", pair(taskId, eventId), true, true); },
     reserveTaskOperation(input) { requireTask(input.taskId); const key = pair(input.taskId, input.operation); const created = put("operations", key, input, true); return { created, record: get<TaskOperationRecord>("operations", key)! }; },
+    discardUnsentOperation(taskId, operation) {
+      store.transaction(() => {
+        const key = pair(taskId, operation), record = get<TaskOperationRecord>("operations", key); if (!record) return;
+        for (const id of record.envelopeIds) {
+          if (get<OutboxRecord>("outbox", id)?.state !== "pending") throw new Error("only a pending, never-sent operation can be discarded");
+          remove("outbox", id);
+        }
+        remove("intents", record.logicalId); remove("operations", key);
+      });
+    },
     getEndpointGeneration() { return state<string>("generation"); },
     setEndpointGeneration(value) { put("state", "generation", value); },
     getEndpointBinding() { return state<TaskEndpoint>("endpoint"); },
     setEndpointBinding(value) { put("state", "endpoint", value); },
     getRelayTransportBinding() { return state<RelayTransportBinding>("transport"); },
     setRelayTransportBinding(value) { put("state", "transport", value); },
-    clear() { check(); if (frames.length) throw new Error("cannot clear task state during a transaction"); tables.clear(); bytes = entries = sequence = 0; },
+    clear() { check(); if (frames.length) throw new Error("cannot clear task state during a transaction"); tables.clear(); eventsByTask.clear(); activeTasks.clear(); pendingOutbox.clear(); pendingByTarget.clear(); pendingTarget.clear(); bytes = entries = sequence = 0; },
     close() { if (closed) return; store.clear(); closed = true; },
   };
   return store;

package/src/task-work-scope.ts

@@ -0,0 +1,98 @@
+import { TaskProtocolError } from "./task-protocol";
+
+export const TASK_WORK_LIMITS = { scopedSends: 56, retries: 8, acknowledgements: 48, pageItems: 50,
+  deadlineMs: 2_000, retrySliceMs: 250, ackRepairSliceMs: 250, capacityCooldownMs: 5_000, retryInspections: 64,
+  // Fetched-but-unacknowledged relay deliveries; intake pauses at this bound until ACKs drain it.
+  pendingDeliveries: 200 } as const;
+
+/** Time source for delivery budgets: the background deadline, admission slices and retry cooldowns. Tests inject virtual time. */
+export interface TaskTimers {
+  /** Wall-clock milliseconds, comparable with stored retry times. */
+  now(): number;
+  /** Monotonic milliseconds for admission slices. */
+  elapsed(): number;
+  /** A signal that aborts once `ms` have passed. */
+  timeout(ms: number): AbortSignal;
+}
+
+export const SYSTEM_TASK_TIMERS: TaskTimers = { now: () => Date.now(), elapsed: () => performance.now(), timeout: ms => AbortSignal.timeout(ms) };
+
+/** Required envelopes a phased pass persisted; its ship phase sends them in persist order. */
+export interface TaskShipment {
+  readonly envelopeIds: readonly string[];
+  /** Throws the blocked-delivery error once the envelopes were offered. */
+  readonly verify?: () => void;
+  /** Runs once every envelope is accepted, e.g. staging the raw ACK that accepted fan-out authorizes. */
+  readonly accepted?: () => void;
+  /** Set by the ship phase, with the first send or blocked-delivery failure, if any. */
+  shipped: boolean;
+  failure?: unknown;
+}
+
+/** Shared counts for nested receipts/fanout; background I/O also has one finite window. */
+export interface TaskWorkScope {
+  readonly signal: AbortSignal;
+  readonly attemptedSends: Set<string>;
+  readonly attemptedAcknowledgements: Set<string>;
+  readonly blockedRetryTargets: Set<string>;
+  retryStarted: boolean;
+  /**
+   * Fixed at creation for a refresh pass: its driver runs intake, presentation, required sends,
+   * ACKs and old-work retry as explicit phases, so core operations never start old-work retry
+   * or ACK repair on their own.
+   */
+  readonly phased: boolean;
+  /** Deferred required sends of a phased pass, in persist order. */
+  readonly shipments: TaskShipment[];
+  claimSend(envelopeId: string, retry: boolean): boolean;
+  claimAcknowledgement(cursor: string): boolean;
+  canAcknowledge(): boolean;
+  remainingAcknowledgements(): number;
+  canRetry(): boolean;
+  canRepairAcknowledgement(): boolean;
+  backgroundSignal(): AbortSignal;
+}
+
+export function createTaskWorkScope(signal?: AbortSignal, mode: "background" | "foreground" | "phased" = "background", timers: TaskTimers = SYSTEM_TASK_TIMERS): TaskWorkScope {
+  const caller = signal ?? new AbortController().signal;
+  let background: AbortSignal | undefined;
+  const backgroundSignal = () => background ??= AbortSignal.any([caller, timers.timeout(TASK_WORK_LIMITS.deadlineMs)]);
+  // Foreground requests retain the transport/caller timeout. Their speculative
+  // retries start a bounded background window only after required sends finish.
+  const active = mode === "foreground" ? caller : backgroundSignal();
+  const attemptedSends = new Set<string>(), attemptedAcknowledgements = new Set<string>(), blockedRetryTargets = new Set<string>();
+  let scopedSends = 0, retrySends = 0, acknowledgements = 0;
+  let retryUntil: number | undefined, repairUntil: number | undefined;
+  return {
+    signal: active, attemptedSends, attemptedAcknowledgements, blockedRetryTargets, retryStarted: false, phased: mode === "phased", shipments: [],
+    backgroundSignal,
+    claimSend(id, retry) {
+      if ((retry ? backgroundSignal() : active).aborted || attemptedSends.has(id) || (retry ? retrySends >= TASK_WORK_LIMITS.retries : scopedSends >= TASK_WORK_LIMITS.scopedSends)) return false;
+      attemptedSends.add(id);
+      if (retry) retrySends++; else scopedSends++;
+      return true;
+    },
+    claimAcknowledgement(cursor) {
+      if (active.aborted || attemptedAcknowledgements.has(cursor) || acknowledgements >= TASK_WORK_LIMITS.acknowledgements) return false;
+      attemptedAcknowledgements.add(cursor); acknowledgements++;
+      return true;
+    },
+    canAcknowledge() { return !active.aborted && acknowledgements < TASK_WORK_LIMITS.acknowledgements; },
+    remainingAcknowledgements() { return active.aborted ? 0 : TASK_WORK_LIMITS.acknowledgements - acknowledgements; },
+    // Slices stop admission, not completion: an admitted request gets the
+    // remaining background window, including cancellation and late fences.
+    canRetry() { return !backgroundSignal().aborted && timers.elapsed() < (retryUntil ??= timers.elapsed() + TASK_WORK_LIMITS.retrySliceMs); },
+    canRepairAcknowledgement() { return !backgroundSignal().aborted && timers.elapsed() < (repairUntil ??= timers.elapsed() + TASK_WORK_LIMITS.ackRepairSliceMs); },
+  };
+}
+
+export function deferredTaskDelivery(details?: Record<string, unknown>): TaskProtocolError {
+  return new TaskProtocolError("TASK_DELIVERY_DEFERRED", "task delivery deferred by the local work budget or retry cooldown", { retryable: true, details });
+}
+
+/** Known admission backpressure gets at least one normal polling interval, without another timer. */
+export function capacityRetryAt(error: unknown, now = Date.now()): number | undefined {
+  if (!(error instanceof TaskProtocolError) || error.code !== "RELAY_CAPACITY" || !error.retryable) return undefined;
+  const hint = error.details?.retryAfterMs;
+  return now + Math.max(TASK_WORK_LIMITS.capacityCooldownMs, typeof hint === "number" && Number.isFinite(hint) && hint >= 0 ? hint : 0);
+}

package/src/volatile-task-session.ts

@@ -1,5 +1,6 @@
 import { createTaskCore } from "./task-core";
 import type { TaskCore } from "./task-core";
+import { RESET_CODES, RETRY_CODES, taskErrorMessage } from "./task-errors";
 import { TASK_PROTOCOL_VERSION, TaskProtocolError } from "./task-protocol";
 import type { RelayTransportBinding, TaskEndpoint, TaskRelay } from "./task-protocol";
 import type { TaskStore } from "./task-store";
@@ -8,8 +9,6 @@ import { fromWolfpackEnvelope, toWolfpackEnvelope, WOLFPACK_TASK_RELAY_ID } from
 export const VOLATILE_PROFILE = "volatile-v1";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const CURSOR = /^(0|[1-9][0-9]{0,31})$/;
-const RESET_CODES = new Set(["RELAY_RESET", "REGISTRATION_EXPIRED", "SOURCE_MISMATCH", "CALLER_DEAD", "CALLER_NOT_FOUND"]);
-const RETRY_CODES = new Set(["RELAY_CAPACITY", "RELAY_UNAVAILABLE", "PEER_UNREACHABLE"]);
 
 export interface VolatileTaskSessionOptions {
   /** Explicit trusted endpoint ingress URL. No default route or installed server. */
@@ -123,6 +122,7 @@ class Transport {
   private expiresAt = 0;
   private renewing: Promise<RelayTransportBinding> | undefined;
   private active = 0;
+  private readonly waiters: Array<{ reserved: boolean; grant(): void }> = [];
   constructor(private url: string, private caller: string, private generation: string, prior: RelayTransportBinding | undefined,
     private fetcher: typeof fetch, private timeoutMs: number, private onReset: (expected: RelayTransportBinding | undefined) => void) { this.binding = prior; }
   stop(): void { this.stopSignal.abort(); }
@@ -202,13 +202,34 @@ class Transport {
       },
     };
   }
+  // FIFO in-flight slots: 8 for ordinary requests, 2 more held for acknowledge/connect.
+  // A waiter has sent nothing, so its abort is a plain retryable ABORTED; RELAY_CAPACITY
+  // only ever comes from the server.
+  private fits(reserved: boolean): boolean { return this.active < (reserved ? 10 : 8); }
+  private acquire(reserved: boolean, signal?: AbortSignal): Promise<void> {
+    if (this.fits(reserved)) { this.active++; return Promise.resolve(); }
+    return new Promise((resolve, reject) => {
+      const cleanup = () => { signal?.removeEventListener("abort", cancel); this.stopSignal.signal.removeEventListener("abort", cancel); };
+      const waiter = { reserved, grant: () => { cleanup(); this.active++; resolve(); } };
+      const cancel = () => {
+        cleanup(); this.waiters.splice(this.waiters.indexOf(waiter), 1);
+        reject(this.stopSignal.signal.aborted ? failure("RELAY_RESET", false, { mayHaveBeenDelivered: true }) : failure("ABORTED", true));
+      };
+      this.waiters.push(waiter);
+      signal?.addEventListener("abort", cancel, { once: true }); this.stopSignal.signal.addEventListener("abort", cancel, { once: true });
+      if (signal?.aborted) cancel();
+    });
+  }
+  private release(): void {
+    this.active--;
+    for (const waiter of [...this.waiters]) if (this.fits(waiter.reserved)) { this.waiters.splice(this.waiters.indexOf(waiter), 1); waiter.grant(); }
+  }
   private async request(body: Record<string, unknown>, signal?: AbortSignal): Promise<{ epoch: string; value: unknown }> {
     this.assertActive();
     const reserved = body.operation === "acknowledge" || body.operation === "connect";
-    if (this.active >= (reserved ? 10 : 8)) throw failure("RELAY_CAPACITY", true);
     const encoded = JSON.stringify(body);
     if (Buffer.byteLength(encoded) > 64 * 1024) throw failure("PAYLOAD_TOO_LARGE", false);
-    this.active++;
+    await this.acquire(reserved, signal);
     const controller = new AbortController();
     let timedOut = false;
     const abort = () => controller.abort();
@@ -268,14 +289,15 @@ class Transport {
       if (!result.ok || data.ok !== true || !uuid(data.epoch)) throw failure("INVALID_RESPONSE", true);
       return { epoch: data.epoch, value: data.value };
     } catch (error) {
-      if (error instanceof TaskProtocolError) throw error;
-      throw failure("RELAY_UNAVAILABLE", true, { mayHaveBeenDelivered: true });
+      // Every failure of an admitted request names its relay operation for the status line.
+      const known = error instanceof TaskProtocolError ? error : failure("RELAY_UNAVAILABLE", true, { mayHaveBeenDelivered: true });
+      throw new TaskProtocolError(known.code, known.message, { retryable: known.retryable, details: { ...known.details, operation: body.operation } });
     } finally {
-      clearTimeout(timer); this.active--; signal?.removeEventListener("abort", abort); this.stopSignal.signal.removeEventListener("abort", abort); controller.signal.removeEventListener("abort", rejectAbort);
+      clearTimeout(timer); this.release(); signal?.removeEventListener("abort", abort); this.stopSignal.signal.removeEventListener("abort", abort); controller.signal.removeEventListener("abort", rejectAbort);
     }
   }
 }
-function failure(code: string, retryable: boolean, details?: Record<string, unknown>): TaskProtocolError { return new TaskProtocolError(code, code, { retryable, details }); }
+function failure(code: string, retryable: boolean, details?: Record<string, unknown>): TaskProtocolError { return new TaskProtocolError(code, taskErrorMessage(code), { retryable, details }); }
 function record(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); }
 function text(value: unknown): value is string { return typeof value === "string" && value.length > 0 && value.length <= 512; }
 function uuid(value: unknown): value is string { return typeof value === "string" && UUID.test(value); }