@frockbot/kernel-do 0.0.0 → 0.1.1

package/src/run-recovery.ts

@@ -0,0 +1,163 @@
+import {
+  Session,
+  type SessionEvent,
+  toolCallOccurrences,
+  validateSettledToolOccurrenceJournal,
+  validateToolOccurrenceJournal,
+  turnFailureMessage,
+} from "@frockbot/kernel-contracts";
+import { BotTurnExecutionError } from "./turn-errors.js";
+import type { StoredRunCodecV1, StoredRunV1 } from "./run-records.js";
+
+export type BotRunRecoveryPlan =
+  | { kind: "complete"; responseText: string }
+  | { kind: "fail"; failure: string }
+  | { kind: "restart"; previous: SessionEvent[] }
+  | { kind: "resume" }
+  | { kind: "reconcile"; repairs: SessionEvent[] };
+
+export type ModelRequestJournalState =
+  | { status: "none" }
+  | {
+      status: "unresolved" | "completed";
+      request: Extract<SessionEvent, { type: "model/request" }>;
+    }
+  | {
+      status: "no-effect";
+      request: Extract<SessionEvent, { type: "model/request" }>;
+      outcome: Extract<SessionEvent, { type: "model/effect-not-started" }>;
+    };
+
+function invalidToolJournal(error: unknown): BotRunRecoveryPlan {
+  return {
+    kind: "fail",
+    failure: `Invalid durable tool journal: ${
+      error instanceof Error ? error.message : "unknown structural error"
+    }`,
+  };
+}
+
+export function latestModelRequestJournalState(
+  events: readonly SessionEvent[],
+): ModelRequestJournalState {
+  let state: ModelRequestJournalState = { status: "none" };
+  for (const event of events) {
+    if (event.type === "model/request") {
+      state = { status: "unresolved", request: event };
+    } else if (
+      event.type === "model/effect-not-started" &&
+      state.status === "unresolved" &&
+      event.requestId === state.request.request.requestId
+    ) {
+      state = { status: "no-effect", request: state.request, outcome: event };
+    } else if (
+      event.type === "assistant/message" &&
+      state.status !== "none" &&
+      event.requestId === state.request.request.requestId
+    ) {
+      state = { status: "completed", request: state.request };
+    }
+  }
+  return state;
+}
+
+export function planBotRunRecovery<Snapshot>(
+  run: StoredRunV1<Snapshot>,
+  latest: readonly SessionEvent[],
+  codec: StoredRunCodecV1<Snapshot>,
+): BotRunRecoveryPlan {
+  codec.require(run);
+  let toolJournal: ReturnType<typeof validateToolOccurrenceJournal>;
+  try {
+    toolJournal = validateToolOccurrenceJournal(run.events);
+  } catch (error) {
+    return invalidToolJournal(error);
+  }
+  const terminalTurn = run.events.findLast(
+    (event) => event.type === "turn/end",
+  );
+  const lastAssistant = run.events.findLast(
+    (event) => event.type === "assistant/message",
+  );
+  if (terminalTurn?.type === "turn/end") {
+    try {
+      validateSettledToolOccurrenceJournal(run.events);
+    } catch (error) {
+      return invalidToolJournal(error);
+    }
+    if (terminalTurn.outcome !== "completed") {
+      return {
+        kind: "fail",
+        failure: turnFailureMessage(terminalTurn.outcome, terminalTurn.reason),
+      };
+    }
+    return {
+      kind: "complete",
+      responseText:
+        lastAssistant?.type === "assistant/message" ? lastAssistant.text : "",
+    };
+  }
+  const modelState = latestModelRequestJournalState(run.events);
+  if (modelState.status === "no-effect") {
+    try {
+      validateSettledToolOccurrenceJournal(run.events);
+    } catch (error) {
+      return invalidToolJournal(error);
+    }
+    return { kind: "resume" };
+  }
+  if (modelState.status === "completed") {
+    const resumableOccurrences = new Set(
+      lastAssistant?.type === "assistant/message"
+        ? toolCallOccurrences(
+            lastAssistant.turn,
+            lastAssistant.step,
+            lastAssistant.toolCalls,
+          ).map((occurrence) => occurrence.occurrenceId)
+        : [],
+    );
+    const skippedOccurrence = [...toolJournal.values()].find(
+      (entry) =>
+        !entry.intent &&
+        !entry.result &&
+        !resumableOccurrences.has(entry.occurrence.occurrenceId),
+    );
+    if (skippedOccurrence) {
+      return invalidToolJournal(
+        new Error(
+          `tool occurrence "${skippedOccurrence.occurrence.occurrenceId}" was skipped before recovery`,
+        ),
+      );
+    }
+    const unresolvedIntent = [...toolJournal.values()].some(
+      (entry) => entry.intent && !entry.result,
+    );
+    if (!unresolvedIntent) return { kind: "resume" };
+  }
+  const hasExternalIntent = run.events.some(
+    (event) => event.type === "model/request" || event.type === "tool/call",
+  );
+  if (!hasExternalIntent) {
+    if (toolJournal.size > 0) {
+      return invalidToolJournal(
+        new Error("assistant tool occurrences have no durable model request"),
+      );
+    }
+    return {
+      kind: "restart",
+      previous: [...latest.slice(0, run.previousEventCount)],
+    };
+  }
+  const session = new Session(run.sessionId, () => {}, latest);
+  return { kind: "reconcile", repairs: session.reconcileForResume() };
+}
+
+export function eventsForFailedRun(
+  durableRun: { events: SessionEvent[] } | undefined,
+  error: unknown,
+): SessionEvent[] {
+  if (durableRun) return structuredClone(durableRun.events);
+  return error instanceof BotTurnExecutionError
+    ? structuredClone(error.events)
+    : [];
+}

package/src/run-terminal.ts

@@ -0,0 +1,220 @@
+import {
+  decodeSessionEvent,
+  type SessionEvent,
+} from "@frockbot/kernel-contracts";
+import type {
+  BotTurnCompletion,
+  StoredRunCodecV1,
+  StoredRunV1,
+} from "./run-records.js";
+
+export interface RunTerminalStorage {
+  get<T>(key: string): Promise<T | undefined>;
+  put(entries: Record<string, unknown>): Promise<void>;
+  delete(key: string): Promise<boolean>;
+}
+
+export interface RunTerminalKeys {
+  run: string;
+  activeRun: string;
+  latestEvents: string;
+  notificationPrefix: string;
+}
+
+/**
+ * Records a Package writes in the same transaction that settles a Turn. The
+ * kernel never reads them: it is handed opaque key/value pairs and a reader
+ * bound to the settling transaction, exactly as it is handed notification
+ * content, so a Package can make a durable decision atomic with the settlement
+ * without the kernel holding the policy that produced it.
+ */
+export type TerminalPackageRecords<Snapshot> = (input: {
+  run: StoredRunV1<Snapshot>;
+  read<T>(key: string): Promise<T | undefined>;
+}) => Promise<Record<string, unknown>>;
+
+/** The kernel owns these; a Package record may never land on one. */
+function assertPackageRecordKeys(
+  records: Record<string, unknown>,
+  keys: RunTerminalKeys,
+): void {
+  for (const key of Object.keys(records)) {
+    if (
+      key === keys.run ||
+      key === keys.activeRun ||
+      key === keys.latestEvents ||
+      key.startsWith(keys.notificationPrefix)
+    ) {
+      throw new Error(`terminal record "${key}" is a kernel key`);
+    }
+  }
+}
+
+export async function completeStoredRun<Snapshot>(
+  codec: StoredRunCodecV1<Snapshot>,
+  storage: RunTerminalStorage,
+  keys: RunTerminalKeys,
+  runId: string,
+  previous: readonly SessionEvent[],
+  result: BotTurnCompletion,
+  packageRecords?: TerminalPackageRecords<Snapshot>,
+): Promise<"completed" | "cancelled"> {
+  const activeRunId = await storage.get<string>(keys.activeRun);
+  if (activeRunId !== runId) throw new Error(`run "${runId}" is not active`);
+  const stored = await storage.get<StoredRunV1<Snapshot>>(keys.run);
+  if (!stored) throw new Error(`run "${runId}" was not accepted`);
+  const run = codec.require(stored);
+  const events = result.events.map(decodeSessionEvent);
+  const latestEvents = [...previous, ...events].map(decodeSessionEvent);
+  // Durable Stop intent recorded before this settlement wins: the run becomes
+  // terminal `cancelled` with no response text, failure, or notification.
+  if (run.stopRequestedAt) {
+    const { responseText: _text, failure: _failure, ...settled } = run;
+    const cancelled = codec.require({
+      ...settled,
+      events,
+      status: "cancelled",
+      phase:
+        settled.phase === "reconciliation-required"
+          ? "executing"
+          : settled.phase,
+    } satisfies StoredRunV1<Snapshot>);
+    await storage.put({
+      [keys.run]: structuredClone(cancelled),
+      [keys.latestEvents]: structuredClone(latestEvents),
+    });
+    await storage.delete(keys.activeRun);
+    return "cancelled";
+  }
+  const completed = codec.require({
+    ...run,
+    events,
+    status: "completed",
+    responseText: result.text,
+  } satisfies StoredRunV1<Snapshot>);
+  const records: Record<string, unknown> = {
+    [keys.run]: structuredClone(completed),
+    [keys.latestEvents]: structuredClone(latestEvents),
+  };
+  if (result.notification) {
+    records[`${keys.notificationPrefix}${result.notification.notificationId}`] =
+      structuredClone(result.notification);
+  }
+  if (packageRecords) {
+    const contributed = await packageRecords({
+      run: completed,
+      read: <T>(key: string) => storage.get<T>(key),
+    });
+    assertPackageRecordKeys(contributed, keys);
+    for (const [key, value] of Object.entries(contributed)) {
+      records[key] = structuredClone(value);
+    }
+  }
+  await storage.put(records);
+  await storage.delete(keys.activeRun);
+  return "completed";
+}
+
+/**
+ * Settles a stopped run as terminal `cancelled` and clears its active marker.
+ * A cancelled run produces no response text, no failure, and no notification.
+ */
+export async function cancelStoredRun<Snapshot>(
+  codec: StoredRunCodecV1<Snapshot>,
+  storage: RunTerminalStorage,
+  keys: RunTerminalKeys,
+  runId: string,
+  previous: readonly SessionEvent[],
+  events: readonly SessionEvent[],
+): Promise<"cancelled" | "preserved-completion" | "missing"> {
+  const stored = await storage.get<StoredRunV1<Snapshot>>(keys.run);
+  if (!stored) return "missing";
+  const run = codec.require(stored);
+  if (run.status === "completed") return "preserved-completion";
+  if (!run.stopRequestedAt) {
+    throw new Error(`run "${runId}" has no durable stop intent`);
+  }
+  const decodedEvents = events.map(decodeSessionEvent);
+  const latestEvents = [...previous, ...decodedEvents].map(decodeSessionEvent);
+  const { responseText: _text, failure: _failure, ...settled } = run;
+  const cancelled = codec.require({
+    ...settled,
+    events: decodedEvents,
+    status: "cancelled",
+    phase:
+      settled.phase === "reconciliation-required" ? "executing" : settled.phase,
+  } satisfies StoredRunV1<Snapshot>);
+  await storage.put({
+    [keys.run]: structuredClone(cancelled),
+    [keys.latestEvents]: structuredClone(latestEvents),
+  });
+  if ((await storage.get<string>(keys.activeRun)) === runId) {
+    await storage.delete(keys.activeRun);
+  }
+  return "cancelled";
+}
+
+export async function failStoredRun<Snapshot>(
+  codec: StoredRunCodecV1<Snapshot>,
+  storage: RunTerminalStorage,
+  keys: RunTerminalKeys,
+  runId: string,
+  previous: readonly SessionEvent[],
+  events: readonly SessionEvent[],
+  failure: string,
+): Promise<"failed" | "cancelled" | "preserved-completion" | "missing"> {
+  const stored = await storage.get<StoredRunV1<Snapshot>>(keys.run);
+  if (!stored) return "missing";
+  const run = codec.require(stored);
+  if (run.status === "completed") return "preserved-completion";
+  // A stopped run never becomes `failed`: Stop is the durable outcome.
+  if (run.stopRequestedAt) {
+    return cancelStoredRun(codec, storage, keys, runId, previous, events);
+  }
+  const decodedEvents = events.map(decodeSessionEvent);
+  const latestEvents = [...previous, ...decodedEvents].map(decodeSessionEvent);
+  const failed = codec.require({
+    ...run,
+    events: decodedEvents,
+    status: "failed",
+    phase: run.phase === "reconciliation-required" ? "executing" : run.phase,
+    failure,
+  } satisfies StoredRunV1<Snapshot>);
+  await storage.put({
+    [keys.run]: structuredClone(failed),
+    [keys.latestEvents]: structuredClone(latestEvents),
+  });
+  if ((await storage.get<string>(keys.activeRun)) === runId) {
+    await storage.delete(keys.activeRun);
+  }
+  return "failed";
+}
+
+export async function requireStoredRunReconciliation<Snapshot>(
+  codec: StoredRunCodecV1<Snapshot>,
+  storage: RunTerminalStorage,
+  keys: RunTerminalKeys,
+  runId: string,
+  previous: readonly SessionEvent[],
+  events: readonly SessionEvent[],
+  failure: string,
+): Promise<void> {
+  const activeRunId = await storage.get<string>(keys.activeRun);
+  if (activeRunId !== runId) throw new Error(`run "${runId}" is not active`);
+  const stored = await storage.get<StoredRunV1<Snapshot>>(keys.run);
+  if (!stored) throw new Error(`run "${runId}" was not accepted`);
+  const run = codec.require(stored);
+  const decodedEvents = events.map(decodeSessionEvent);
+  const latestEvents = [...previous, ...decodedEvents].map(decodeSessionEvent);
+  const reconciliation = codec.require({
+    ...run,
+    events: decodedEvents,
+    status: "reconciliation-required",
+    phase: "reconciliation-required",
+    failure,
+  } satisfies StoredRunV1<Snapshot>);
+  await storage.put({
+    [keys.run]: structuredClone(reconciliation),
+    [keys.latestEvents]: structuredClone(latestEvents),
+  });
+}

package/src/storage-keys.ts

@@ -0,0 +1,129 @@
+/**
+ * Durable keys the Bot Durable Object authority owns. Packages that share the
+ * object's storage read them through the authority, never by key.
+ */
+export const RUN_PREFIX = "run:";
+export const RUN_INDEX_PREFIX = "run-index:";
+export const RUN_ADMISSION_FENCE_PREFIX = "run-admission-fence:";
+export const RUN_ADMISSION_FENCE_INDEX_KEY = "run-admission-fences";
+export const MAX_RUN_ADMISSION_FENCES = 256;
+export const ACTIVE_RUN_KEY = "active-run";
+export const LATEST_EVENTS_KEY = "latest-events";
+export const IDENTITY_KEY = "identity";
+export const NOTIFICATION_PREFIX = "notification:";
+export const COMPOSITION_CURRENT_KEY = "composition:current";
+export const COMPOSITION_GENERATION_PREFIX = "composition:generation:";
+export const COMPOSITION_INDEX_PREFIX = "composition:index:";
+export const COMPOSITION_LAST_KNOWN_GOOD_KEY = "composition:last-known-good";
+export const COMPOSITION_FAILURE_PREFIX = "composition:failure:";
+export const COMPOSITION_FAILURE_COUNT_PREFIX = "composition:failure-count:";
+export const COMPOSITION_QUARANTINE_PREFIX = "composition:quarantine:";
+/** Attempts are zero-padded so the prefix listing is attempt-ordered. */
+export const COMPOSITION_FAILURE_ATTEMPT_DIGITS = 4;
+export const RECOVERY_ALARM_DELAY_MS = 60_000;
+/** The current generation of one durable-root file. */
+export const WORKSPACE_GENERATION_PREFIX = "workspace:generation:";
+/** Preserved losing writes for one durable-root file. */
+export const WORKSPACE_CONFLICT_PREFIX = "workspace:conflict:";
+/** One unsettled durable-root sync push intent, by effect id (ADR 0013). */
+export const WORKSPACE_SYNC_EFFECT_PREFIX = "workspace:sync-effect:";
+/** The monotonic cursor every minted Workspace generation id advances. */
+export const WORKSPACE_GENERATION_CURSOR_KEY = "workspace:generation-cursor";
+/** Longest readable key tail before it is fingerprinted; Durable Object keys are bounded. */
+const WORKSPACE_KEY_TAIL_LIMIT = 900;
+
+function fingerprint(value: string): string {
+  let hash = 0xcbf29ce484222325n;
+  for (const byte of new TextEncoder().encode(value)) {
+    hash ^= BigInt(byte);
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
+/**
+ * The key tail identifying one file in one durable root. Readable while it
+ * fits — a root key plus a relative path — and fingerprinted past that, so a
+ * long path can never push a Durable Object key over its bound.
+ */
+export function workspaceFileKeyTail(rootKey: string, path: string): string {
+  const tail = `${rootKey}:${path}`;
+  if (tail.length <= WORKSPACE_KEY_TAIL_LIMIT) return tail;
+  return `${tail.slice(0, WORKSPACE_KEY_TAIL_LIMIT - 20)}#${fingerprint(tail)}`;
+}
+
+export function workspaceGenerationKey(rootKey: string, path: string): string {
+  return `${WORKSPACE_GENERATION_PREFIX}${workspaceFileKeyTail(rootKey, path)}`;
+}
+
+export function workspaceConflictPrefix(rootKey: string, path: string): string {
+  return `${WORKSPACE_CONFLICT_PREFIX}${workspaceFileKeyTail(rootKey, path)}:`;
+}
+
+export function workspaceConflictKey(
+  rootKey: string,
+  path: string,
+  generationId: string,
+): string {
+  return `${workspaceConflictPrefix(rootKey, path)}${generationId}`;
+}
+
+export function runIndexKey(acceptedAt: string, runId: string): string {
+  return `${RUN_INDEX_PREFIX}${acceptedAt}:${runId}`;
+}
+
+export function compositionGenerationKey(generationId: string): string {
+  return `${COMPOSITION_GENERATION_PREFIX}${generationId}`;
+}
+
+export function compositionIndexKey(
+  createdAt: string,
+  generationId: string,
+): string {
+  return `${COMPOSITION_INDEX_PREFIX}${createdAt}:${generationId}`;
+}
+
+export function compositionFailurePrefix(generationId: string): string {
+  return `${COMPOSITION_FAILURE_PREFIX}${generationId}:`;
+}
+
+export function compositionFailureKey(
+  generationId: string,
+  attempt: number,
+): string {
+  return `${compositionFailurePrefix(generationId)}${String(attempt).padStart(
+    COMPOSITION_FAILURE_ATTEMPT_DIGITS,
+    "0",
+  )}`;
+}
+
+export function compositionFailureCountKey(generationId: string): string {
+  return `${COMPOSITION_FAILURE_COUNT_PREFIX}${generationId}`;
+}
+
+export function compositionQuarantineKey(generationId: string): string {
+  return `${COMPOSITION_QUARANTINE_PREFIX}${generationId}`;
+}
+
+export function storedRunAdmissionFences(input: unknown): string[] {
+  if (input === undefined) return [];
+  if (
+    !Array.isArray(input) ||
+    input.length > MAX_RUN_ADMISSION_FENCES ||
+    input.some(
+      (runId) =>
+        typeof runId !== "string" || runId.length < 1 || runId.length > 128,
+    )
+  ) {
+    throw new Error("Stored run admission fences are invalid");
+  }
+  return [...new Set(input)];
+}
+
+/**
+ * The key one sync push intent is recorded under. The effect id is already a
+ * bounded digest minted by the sync, so it is used verbatim.
+ */
+export function workspaceSyncEffectKey(effectId: string): string {
+  return `${WORKSPACE_SYNC_EFFECT_PREFIX}${effectId}`;
+}