@frockbot/kernel-do 0.3.2 → 0.3.4

package/src/memory-storage.fixture.ts

@@ -45,8 +45,21 @@ export class MemoryStorage {
     );
   }
 
+  /**
+   * Transactions run one at a time, as a Durable Object's do. Two admissions
+   * that arrive together must not both read "no run is pending" and both
+   * write themselves into the slot, and a fixture that let them would prove
+   * the opposite of what the tests are for.
+   */
+  #serialized: Promise<unknown> = Promise.resolve();
+
   transaction<T>(callback: (storage: MemoryStorage) => Promise<T>): Promise<T> {
-    return callback(this);
+    const next = this.#serialized.then(
+      () => callback(this),
+      () => callback(this),
+    );
+    this.#serialized = next.catch(() => undefined);
+    return next;
   }
 
   setAlarm(scheduledTime: number): Promise<void> {

package/src/run-records.ts

@@ -22,7 +22,34 @@ export interface StoredRunCodecV1<Snapshot> {
 }
 
 export type StoredRunStatus =
-  "running" | "completed" | "failed" | "cancelled" | "reconciliation-required";
+  | "running"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "superseded"
+  | "reconciliation-required";
+
+/**
+ * The admission lane a Turn was accepted on.
+ *
+ * A `user` admission is a person speaking to the Bot and may supersede
+ * whatever is running; a `background` admission — a Routine firing, a subagent
+ * dispatch — never supersedes and waits. The lane is durable because the
+ * decision to interrupt is made in the admission transaction and has to
+ * survive eviction alongside the run it interrupted.
+ */
+export type RunLaneV1 = "user" | "background";
+
+const RUN_LANES_V1: readonly RunLaneV1[] = ["user", "background"];
+
+/**
+ * The lane a turn type belongs to when its record names none. Chat is the
+ * conversation, so it is the User's lane; every other turn type is work the
+ * Bot started for itself.
+ */
+export function defaultRunLaneV1(turnType: TurnTypeV1): RunLaneV1 {
+  return turnType === "chat" ? "user" : "background";
+}
 
 export type StoredEffectAdmissionOutcome = "admitted" | "fenced";
 
@@ -80,6 +107,13 @@ const STORED_RUN_ORIGIN_TRIGGERS: readonly StoredRunTriggerV1[] = [
 export interface StoredRunAdmissionV1 {
   schemaVersion: 1;
   turnType: TurnTypeV1;
+  /**
+   * The lane this Turn was admitted on. Absent means the lane its turn type
+   * defaults to, so no producer writing today's lanes changes a stored byte;
+   * a later lane that is not a turn type's default — bot-to-bot messaging's
+   * `agent` lane — names itself here.
+   */
+  lane?: RunLaneV1;
   /**
    * The subagent role the Turn was admitted under, when it had one. Recorded
    * for the same reason the turn type is: recovery after eviction has to
@@ -90,7 +124,7 @@ export interface StoredRunAdmissionV1 {
 }
 
 export type StoredRunPhase =
-  "admitted" | "executing" | "reconciliation-required";
+  "queued" | "admitted" | "executing" | "reconciliation-required";
 
 export interface StoredRunV1<Snapshot = unknown> {
   runId: string;
@@ -106,6 +140,15 @@ export interface StoredRunV1<Snapshot = unknown> {
   phase: StoredRunPhase;
   /** Durable Stop intent; orthogonal to status and phase. */
   stopRequestedAt?: string;
+  /**
+   * Durable supersede intent: a later user-lane admission has taken this
+   * Turn's place. Orthogonal to status and phase exactly as Stop is, and read
+   * the same way — every new effect is fenced from the instant it is
+   * recorded, and the settlement that follows is terminal `superseded`.
+   */
+  supersededAt?: string;
+  /** The run whose admission superseded this one. */
+  supersededBy?: string;
   /** The Composition generation pinned in the same transaction that admitted the run. */
   compositionGenerationId: string;
   configurationSnapshot: Snapshot;
@@ -137,6 +180,15 @@ export function storedRunTurnTypeV1(run: {
   return run.admission?.turnType ?? "chat";
 }
 
+/** The lane a stored run was admitted on. */
+export function storedRunLaneV1(run: {
+  admission?: StoredRunAdmissionV1;
+}): RunLaneV1 {
+  return (
+    run.admission?.lane ?? defaultRunLaneV1(run.admission?.turnType ?? "chat")
+  );
+}
+
 /**
  * The `admission` field a Turn records — nothing at all for a chat Turn with
  * no recorded origin, so no stored bytes change for the Turn every producer
@@ -146,14 +198,25 @@ export function storedRunAdmissionV1(
   turnType: TurnTypeV1 | undefined,
   origin?: StoredRunOriginV1,
   subagentRole?: string,
+  lane?: RunLaneV1,
 ): { admission?: StoredRunAdmissionV1 } {
   const admitted = turnType ?? "chat";
-  if (admitted === "chat" && origin === undefined && subagentRole === undefined)
+  // A lane that is already the turn type's default is not written: it says
+  // nothing the record does not, and writing it would change the bytes of the
+  // Turn every producer writes today.
+  const named = lane && lane !== defaultRunLaneV1(admitted) ? lane : undefined;
+  if (
+    admitted === "chat" &&
+    origin === undefined &&
+    subagentRole === undefined &&
+    named === undefined
+  )
     return {};
   return {
     admission: {
       schemaVersion: 1,
       turnType: admitted,
+      ...(named ? { lane: named } : {}),
       ...(subagentRole ? { subagentRole } : {}),
       ...(origin ? { origin } : {}),
     },
@@ -168,9 +231,11 @@ const STORED_RUN_STATUSES: readonly StoredRunStatus[] = [
   "completed",
   "failed",
   "cancelled",
+  "superseded",
   "reconciliation-required",
 ];
 const STORED_RUN_PHASES: readonly StoredRunPhase[] = [
+  "queued",
   "admitted",
   "executing",
   "reconciliation-required",
@@ -193,6 +258,8 @@ const STORED_RUN_OPTIONAL_KEYS = [
   "responseText",
   "failure",
   "stopRequestedAt",
+  "supersededAt",
+  "supersededBy",
   "admission",
   "directTool",
 ] as const;
@@ -333,6 +400,7 @@ function decodeStoredRunAdmission(
   const allowed = new Set([
     "schemaVersion",
     "turnType",
+    "lane",
     "subagentRole",
     "origin",
   ]);
@@ -352,6 +420,13 @@ function decodeStoredRunAdmission(
   } catch {
     throw new Error(`run "${runId}" has an invalid admission turn type`);
   }
+  const lane =
+    candidate.lane === undefined
+      ? undefined
+      : RUN_LANES_V1.find((value) => value === candidate.lane);
+  if (candidate.lane !== undefined && !lane) {
+    throw new Error(`run "${runId}" has an invalid admission lane`);
+  }
   if (
     candidate.subagentRole !== undefined &&
     (typeof candidate.subagentRole !== "string" ||
@@ -363,6 +438,7 @@ function decodeStoredRunAdmission(
   return {
     schemaVersion: 1,
     turnType,
+    ...(lane === undefined ? {} : { lane }),
     ...(candidate.subagentRole === undefined
       ? {}
       : { subagentRole: candidate.subagentRole as string }),
@@ -521,6 +597,25 @@ function requireStoredRunRecordV1<Snapshot>(
   ) {
     throw new Error(`run "${runId}" has invalid stopRequestedAt`);
   }
+  if (
+    candidate.supersededAt !== undefined &&
+    (!boundedString(candidate.supersededAt, 64) ||
+      !Number.isFinite(Date.parse(candidate.supersededAt as string)))
+  ) {
+    throw new Error(`run "${runId}" has invalid supersededAt`);
+  }
+  if (
+    candidate.supersededBy !== undefined &&
+    !boundedString(candidate.supersededBy, 128)
+  ) {
+    throw new Error(`run "${runId}" has invalid supersededBy`);
+  }
+  if (
+    candidate.supersededBy !== undefined &&
+    candidate.supersededAt === undefined
+  ) {
+    throw new Error(`run "${runId}" names a superseder with no supersede time`);
+  }
   if (
     status === "completed"
       ? candidate.responseText === undefined || candidate.failure !== undefined
@@ -538,6 +633,9 @@ function requireStoredRunRecordV1<Snapshot>(
   if (status === "cancelled" && candidate.stopRequestedAt === undefined) {
     throw new Error(`run "${runId}" has no durable stop intent`);
   }
+  if (status === "superseded" && candidate.supersededAt === undefined) {
+    throw new Error(`run "${runId}" has no durable supersede intent`);
+  }
   if (
     (status === "reconciliation-required") !==
     (phase === "reconciliation-required")
@@ -566,6 +664,12 @@ function requireStoredRunRecordV1<Snapshot>(
     ...(candidate.stopRequestedAt === undefined
       ? {}
       : { stopRequestedAt: candidate.stopRequestedAt as string }),
+    ...(candidate.supersededAt === undefined
+      ? {}
+      : { supersededAt: candidate.supersededAt as string }),
+    ...(candidate.supersededBy === undefined
+      ? {}
+      : { supersededBy: candidate.supersededBy as string }),
     ...(candidate.admission === undefined
       ? {}
       : { admission: decodeStoredRunAdmission(candidate.admission, runId) }),
@@ -602,6 +706,25 @@ export interface BotTurnCommand {
    */
   skills?: SkillRefV1[];
   directTool?: DirectToolCommandV1;
+  /**
+   * The lane this command asks to be admitted on. Absent means the lane its
+   * turn type defaults to.
+   */
+  lane?: RunLaneV1;
+  /**
+   * The explicit intent to replace whatever is running with this command. A
+   * user-lane command that carries it is the authenticated cancellation of the
+   * active Turn: that run terminalizes `superseded` and this one takes its
+   * place. Without it a second command is refused exactly as it always was.
+   *
+   * `runId` is provenance — the run the sender had observed, which may already
+   * be stale — and never the target. Its absence means the sender had observed
+   * no run at all, which is a race rather than a different intention, so it
+   * supersedes just the same. The whole field is part of the command
+   * fingerprint, so a replayed command replays and never interrupts a second
+   * Turn.
+   */
+  supersedes?: { runId?: string };
 }
 
 /**
@@ -616,12 +739,15 @@ export function botTurnCommandFingerprintV1(
 ): string {
   const turnType = command.turnType ?? "chat";
   const skills = command.skills ?? [];
+  const lane = command.lane ?? defaultRunLaneV1(turnType);
   if (
     turnType !== "chat" ||
     command.origin !== undefined ||
     command.subagentRole !== undefined ||
     skills.length > 0 ||
-    command.directTool !== undefined
+    command.directTool !== undefined ||
+    lane !== defaultRunLaneV1(turnType) ||
+    command.supersedes !== undefined
   ) {
     return `bot-turn-command-v2:${JSON.stringify({
       userId: command.userId,
@@ -629,8 +755,10 @@ export function botTurnCommandFingerprintV1(
       sessionId: command.sessionId,
       text: command.text,
       turnType,
+      ...(lane === defaultRunLaneV1(turnType) ? {} : { lane }),
       ...(command.subagentRole ? { subagentRole: command.subagentRole } : {}),
       ...(command.origin ? { origin: command.origin } : {}),
+      ...(command.supersedes ? { supersedes: command.supersedes } : {}),
       ...(skills.length > 0 ? { skills: skills.map(formatSkillRefV1) } : {}),
       ...(command.directTool ? { directTool: command.directTool } : {}),
     })}`;

package/src/run-terminal.ts

@@ -50,6 +50,83 @@ function assertPackageRecordKeys(
   }
 }
 
+/**
+ * Records a Package writes in the transaction that settles a Turn as
+ * `superseded`. Same shape and same rule as `TerminalPackageRecords`: the
+ * kernel writes opaque keys and holds none of the policy that produced them.
+ * It is a separate seam because a superseded Turn is not a completed one — the
+ * Package that owns the conversation wants to leave the *next* Turn a durable
+ * note, not advance the records a finished Turn advances.
+ */
+export type SupersededPackageRecords<Snapshot> = (input: {
+  run: StoredRunV1<Snapshot>;
+  read<T>(key: string): Promise<T | undefined>;
+}) => Promise<Record<string, unknown>>;
+
+/**
+ * Settles a superseded run as terminal `superseded` and clears its active
+ * marker. Like a cancelled run it produces no response text, no failure, and
+ * no notification: the Turn that replaced it is what the User is watching.
+ */
+export async function supersedeStoredRun<Snapshot>(
+  codec: StoredRunCodecV1<Snapshot>,
+  storage: RunTerminalStorage,
+  keys: RunTerminalKeys,
+  runId: string,
+  previous: readonly SessionEvent[],
+  events: readonly SessionEvent[],
+  packageRecords?: SupersededPackageRecords<Snapshot>,
+): Promise<"superseded"> {
+  const stored = await storage.get<StoredRunV1<Snapshot>>(keys.run);
+  if (!stored) throw new Error(`run "${runId}" was not accepted`);
+  const run = codec.require(stored);
+  if (!run.supersededAt) {
+    throw new Error(`run "${runId}" has no durable supersede intent`);
+  }
+  const decodedEvents = events.map(decodeSessionEvent);
+  const { responseText: _text, failure: _failure, ...settled } = run;
+  // A run superseded while still queued never started, never appended an
+  // event, and never spoke: it settles as a record on its own and leaves both
+  // the session log and the running Turn exactly where they were.
+  const queued = settled.phase === "queued";
+  const superseded = codec.require({
+    ...settled,
+    events: queued ? [] : decodedEvents,
+    status: "superseded",
+    phase:
+      settled.phase === "reconciliation-required"
+        ? "executing"
+        : settled.phase === "queued"
+          ? "admitted"
+          : settled.phase,
+  } satisfies StoredRunV1<Snapshot>);
+  const records: Record<string, unknown> = {
+    [keys.run]: structuredClone(superseded),
+    ...(queued
+      ? {}
+      : {
+          [keys.latestEvents]: structuredClone(
+            [...previous, ...decodedEvents].map(decodeSessionEvent),
+          ),
+        }),
+  };
+  if (packageRecords && !queued) {
+    const contributed = await packageRecords({
+      run: superseded,
+      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);
+  if ((await storage.get<string>(keys.activeRun)) === runId) {
+    await storage.delete(keys.activeRun);
+  }
+  return "superseded";
+}
+
 export async function completeStoredRun<Snapshot>(
   codec: StoredRunCodecV1<Snapshot>,
   storage: RunTerminalStorage,
@@ -58,7 +135,8 @@ export async function completeStoredRun<Snapshot>(
   previous: readonly SessionEvent[],
   result: BotTurnCompletion,
   packageRecords?: TerminalPackageRecords<Snapshot>,
-): Promise<"completed" | "cancelled"> {
+  supersededRecords?: SupersededPackageRecords<Snapshot>,
+): Promise<"completed" | "cancelled" | "superseded"> {
   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);
@@ -66,6 +144,20 @@ export async function completeStoredRun<Snapshot>(
   const run = codec.require(stored);
   const events = result.events.map(decodeSessionEvent);
   const latestEvents = [...previous, ...events].map(decodeSessionEvent);
+  // Stop outranks supersede: the User asked for this Turn to stop, and a
+  // message that arrived after that does not turn their cancellation into
+  // something else.
+  if (run.supersededAt && !run.stopRequestedAt) {
+    return supersedeStoredRun(
+      codec,
+      storage,
+      keys,
+      runId,
+      previous,
+      result.events,
+      supersededRecords,
+    );
+  }
   // Durable Stop intent recorded before this settlement wins: the run becomes
   // terminal `cancelled` with no response text, failure, or notification.
   if (run.stopRequestedAt) {
@@ -162,7 +254,10 @@ export async function failStoredRun<Snapshot>(
   previous: readonly SessionEvent[],
   events: readonly SessionEvent[],
   failure: string,
-): Promise<"failed" | "cancelled" | "preserved-completion" | "missing"> {
+  supersededRecords?: SupersededPackageRecords<Snapshot>,
+): Promise<
+  "failed" | "cancelled" | "superseded" | "preserved-completion" | "missing"
+> {
   const stored = await storage.get<StoredRunV1<Snapshot>>(keys.run);
   if (!stored) return "missing";
   const run = codec.require(stored);
@@ -171,6 +266,18 @@ export async function failStoredRun<Snapshot>(
   if (run.stopRequestedAt) {
     return cancelStoredRun(codec, storage, keys, runId, previous, events);
   }
+  // Nor does a superseded one. The Turn that replaced it is the outcome.
+  if (run.supersededAt) {
+    return supersedeStoredRun(
+      codec,
+      storage,
+      keys,
+      runId,
+      previous,
+      events,
+      supersededRecords,
+    );
+  }
   const decodedEvents = events.map(decodeSessionEvent);
   const latestEvents = [...previous, ...decodedEvents].map(decodeSessionEvent);
   const failed = codec.require({

package/src/storage-keys.ts

@@ -8,6 +8,14 @@ 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";
+/**
+ * The one admitted user-lane Turn waiting for the object to become free.
+ *
+ * A single slot, not a queue: a second user message supersedes the first
+ * waiting one exactly as it supersedes a running one, so the Bot is never
+ * working through a backlog of things the User has already replaced.
+ */
+export const PENDING_RUN_KEY = "pending-run";
 export const LATEST_EVENTS_KEY = "latest-events";
 export const IDENTITY_KEY = "identity";
 export const NOTIFICATION_PREFIX = "notification:";