@frockbot/kernel-do 0.3.41 → 0.3.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-do",
-  "version": "0.3.41",
+  "version": "0.3.43",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,8 +12,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-composition": "0.3.41",
-    "@frockbot/kernel-contracts": "0.3.41",
+    "@frockbot/kernel-composition": "0.3.43",
+    "@frockbot/kernel-contracts": "0.3.43",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/authority.ts

@@ -10,7 +10,10 @@ import {
   type SessionEvent,
 } from "@frockbot/kernel-contracts";
 import type { CompositionGenerationV1 } from "@frockbot/kernel-composition/generation";
-import { DurableCompositionStore } from "./composition-store.js";
+import {
+  DurableCompositionStore,
+  decodeCompositionPinV1,
+} from "./composition-store.js";
 import { DurableCompositionFailureLog } from "./composition-failures.js";
 import {
   boundedRunFailureV1,
@@ -22,11 +25,13 @@ import {
   storedRunRecordV2,
   storedRunSubagentRoleV1,
   storedRunTurnTypeV1,
+  unreadableStoredRunV1,
   type BotNotificationIntent,
   type BotTurnCommand,
   type BotTurnCompletion,
   type StoredRunCodecV1,
   type StoredRunV1,
+  type UnreadableStoredRunV1,
 } from "./run-records.js";
 import {
   completeStoredRun,
@@ -67,6 +72,7 @@ import {
 } from "./conversations.js";
 import {
   ACTIVE_RUN_KEY,
+  COMPOSITION_CURRENT_KEY,
   CONVERSATION_INDEX_KEY,
   CONVERSATION_KEY,
   MAX_LISTED_CONVERSATIONS,
@@ -235,6 +241,14 @@ function runWasDiscardedV1(
   return Boolean(run?.stopRequestedAt || run?.supersededAt);
 }
 
+/**
+ * One run as the display-only read boundary sees it: either the decoded
+ * record, or the bounded identity of a record that could not be decoded.
+ */
+export type DisplayRunReadV1<Snapshot> =
+  | { readonly readable: true; readonly run: StoredRunV1<Snapshot> }
+  | { readonly readable: false; readonly run: UnreadableStoredRunV1 };
+
 export interface BotDurableAuthorityOptions<Snapshot> {
   state: DurableObjectState;
   codec: StoredRunCodecV1<Snapshot>;
@@ -400,6 +414,14 @@ export class BotDurableAuthority<Snapshot> {
    * Makes the durably queued run the active one, recomputing the history it
    * starts from: the Turn it waited behind appended events, and the queued
    * Turn's model request derives from everything that is durable now.
+   *
+   * The Composition pin is recomputed here for the same reason. A queued Turn
+   * is admitted but has not started, and "an in-flight Turn keeps its pinned
+   * implementation" is about a Turn that is running, not one that is waiting.
+   * The Turn ahead of it can author a Package or follow a deployment while it
+   * waits, and pinning what the pointer said at admission ran the queued Turn
+   * without the member that was just added — the tool the Bot had told the
+   * person it had built.
    */
   private async promoteQueuedRun(runId: string): Promise<
     | "not-queued"
@@ -449,9 +471,18 @@ export class BotDurableAuthority<Snapshot> {
       // repair applies before this Turn starts on it.
       const repaired = repairedSessionLogV1(run.sessionId, storedEvents);
       const latestEvents = repaired ?? storedEvents;
+      // The pointer is materialized at admission, so it is there; a Bot whose
+      // record somehow is not keeps the generation it was admitted under
+      // rather than failing a Turn it is owed.
+      const pointer = await transaction.get<unknown>(COMPOSITION_CURRENT_KEY);
+      const compositionGenerationId =
+        pointer === undefined
+          ? run.compositionGenerationId
+          : decodeCompositionPinV1(pointer).generationId;
       const promoted = this.codec.require({
         ...run,
         phase: "admitted",
+        compositionGenerationId,
         previousEventCount: latestEvents.length,
         ...storedRunEventFieldsV2(latestEvents.length, []),
       } satisfies StoredRunV1<Snapshot>);
@@ -1227,6 +1258,61 @@ export class BotDurableAuthority<Snapshot> {
     return this.readRunFrom(this.ctx.storage, runId, "display");
   }
 
+  /**
+   * The record alone, for display, never throwing on a record it cannot read.
+   *
+   * The transcript is the one reader that must survive a bad row. Execution
+   * and recovery stay strict — they act on the record, and acting on a record
+   * nobody can decode is how a Turn gets settled twice — but a read that only
+   * draws the conversation owes the person the other forty Turns. An
+   * undecodable record comes back as {@link UnreadableStoredRunV1}: the run id
+   * from the lookup key plus whatever scraped strings are safe, which is
+   * enough to render exactly one degraded row.
+   */
+  async readRunHeaderForDisplay(
+    runId: string,
+  ): Promise<DisplayRunReadV1<Snapshot> | undefined> {
+    const raw = await this.ctx.storage.get<unknown>(`${RUN_PREFIX}${runId}`);
+    if (raw === undefined) return undefined;
+    try {
+      return { readable: true, run: this.codec.require(raw) };
+    } catch {
+      return { readable: false, run: unreadableStoredRunV1(runId, raw) };
+    }
+  }
+
+  /**
+   * The journal behind a display header, degrading rather than throwing.
+   *
+   * Takes the header the caller already read rather than the run id: a
+   * transcript page reads one record per candidate and hydrates only the ones
+   * it keeps, and re-reading the record here would put that read back.
+   */
+  async hydrateRunForDisplay(
+    header: DisplayRunReadV1<Snapshot>,
+  ): Promise<DisplayRunReadV1<Snapshot>> {
+    if (!header.readable) return header;
+    try {
+      return {
+        readable: true,
+        run: await this.hydrateRun(this.ctx.storage, header.run, "display"),
+      };
+    } catch {
+      return {
+        readable: false,
+        run: unreadableStoredRunV1(header.run.runId, header.run),
+      };
+    }
+  }
+
+  /** {@link readRunHeaderForDisplay} with its journal hydrated. */
+  async readStoredRunForDisplayOrDegraded(
+    runId: string,
+  ): Promise<DisplayRunReadV1<Snapshot> | undefined> {
+    const header = await this.readRunHeaderForDisplay(runId);
+    return header ? this.hydrateRunForDisplay(header) : undefined;
+  }
+
   private async readRunFrom(
     storage: SessionEventLogStorage,
     runId: string,
@@ -1235,7 +1321,16 @@ export class BotDurableAuthority<Snapshot> {
     const run = this.codec.optional(
       await storage.get<unknown>(`${RUN_PREFIX}${runId}`),
     );
-    if (!run?.eventRange) return run;
+    if (!run) return undefined;
+    return this.hydrateRun(storage, run, fidelity);
+  }
+
+  private async hydrateRun(
+    storage: SessionEventLogStorage,
+    run: StoredRunV1<Snapshot>,
+    fidelity: "exact" | "display",
+  ): Promise<StoredRunV1<Snapshot>> {
+    if (!run.eventRange) return run;
     const log = new SessionEventLog(storage);
     const events =
       fidelity === "display"

package/src/composition-store.test.ts

@@ -3,6 +3,9 @@ import {
   bootstrapGeneration,
   compositionArtifactSetHashV1,
   compositionGenerationIdV1,
+  CompositionPinConflictError,
+  COMPOSITION_PIN_ATTEMPTS_V1,
+  pinCompositionWithRetryV1,
   type CompositionGenerationV1,
   type CompositionMemberV1,
 } from "@frockbot/kernel-composition/generation";
@@ -506,6 +509,123 @@ describe("Bot Durable Object Composition records", () => {
   });
 });
 
+describe("a pinning proposal compares and swaps the pointer", () => {
+  test("a proposal derived from the generation the pointer still names wins", async () => {
+    const storage = new MemoryStorage();
+    const store = createStore(storage);
+    const parent = await store.current();
+    const next = await grownSuccessor(parent, "2026-09-01T00:00:00.000Z");
+
+    await store.propose(next, {
+      pin: true,
+      expectedCurrentGenerationId: parent.generationId,
+    });
+
+    expect((await store.current()).generationId).toBe(next.generationId);
+  });
+
+  test("a proposal derived from a pointer that has since moved is refused whole", async () => {
+    const storage = new MemoryStorage();
+    const store = createStore(storage);
+    // What the losing writer snapshotted before it yielded.
+    const stale = await store.current();
+    // What landed while it was yielded: a Package the Bot authored.
+    const authored = await grownSuccessor(stale, "2026-09-01T00:00:00.000Z");
+    await store.propose(authored, {
+      pin: true,
+      expectedCurrentGenerationId: stale.generationId,
+    });
+
+    const derivedFromStale = await successor(stale, "2026-09-01T00:00:01.000Z");
+    await expect(
+      store.propose(derivedFromStale, {
+        pin: true,
+        expectedCurrentGenerationId: stale.generationId,
+      }),
+    ).rejects.toBeInstanceOf(CompositionPinConflictError);
+
+    // The pointer still names the winner, and the loser wrote nothing at all:
+    // no generation record, no index entry, so no retention quota was spent on
+    // a proposal that never applied.
+    expect((await store.current()).generationId).toBe(authored.generationId);
+    expect(await store.read(derivedFromStale.generationId)).toBeUndefined();
+    expect(await store.retainedCount()).toBe(2);
+    // And the authored member is still there — the whole point of refusing.
+    expect(
+      (await store.current()).members.map((member) => member.packageId),
+    ).toEqual(["bot-authored-greeter", "shell"]);
+  });
+
+  test("the loser re-derives from the winner and keeps both members", async () => {
+    const storage = new MemoryStorage();
+    const store = createStore(storage);
+    const stale = await store.current();
+    const authored = await grownSuccessor(stale, "2026-09-01T00:00:00.000Z");
+    await store.propose(authored, {
+      pin: true,
+      expectedCurrentGenerationId: stale.generationId,
+    });
+
+    let derivedFrom = stale;
+    let attempts = 0;
+    const pinned = await pinCompositionWithRetryV1(async () => {
+      attempts += 1;
+      // A first attempt that derives from the snapshot it took before it
+      // yielded, and a retry that re-reads — which is the merge.
+      const parent = attempts === 1 ? stale : await store.current();
+      derivedFrom = parent;
+      const generation = await successor(
+        parent,
+        `2026-09-01T00:00:0${attempts}.000Z`,
+      );
+      await store.propose(generation, {
+        pin: true,
+        expectedCurrentGenerationId: parent.generationId,
+      });
+      return generation;
+    });
+
+    expect(attempts).toBe(2);
+    expect(derivedFrom.generationId).toBe(authored.generationId);
+    expect((await store.current()).generationId).toBe(pinned.generationId);
+    expect(pinned.members.map((member) => member.packageId)).toEqual([
+      "bot-authored-greeter",
+      "shell",
+    ]);
+  });
+
+  test("gives up after a bounded number of losses rather than spinning", async () => {
+    const storage = new MemoryStorage();
+    const store = createStore(storage);
+    const stale = await store.current();
+    let attempts = 0;
+
+    await expect(
+      pinCompositionWithRetryV1(async () => {
+        attempts += 1;
+        // Someone else always wins: every attempt derives from a pointer that
+        // has already moved by the time it proposes.
+        const winner = await successor(
+          await store.current(),
+          `2026-09-0${attempts}T00:00:00.000Z`,
+        );
+        await store.propose(winner, { pin: true });
+        const generation = await successor(
+          stale,
+          `2026-09-0${attempts}T00:00:01.000Z`,
+        );
+        await store.propose(generation, {
+          pin: true,
+          expectedCurrentGenerationId: stale.generationId,
+        });
+        return generation;
+      }),
+    ).rejects.toBeInstanceOf(CompositionPinConflictError);
+
+    expect(attempts).toBe(COMPOSITION_PIN_ATTEMPTS_V1);
+  });
+});
+
 interface TurnProbe {
   authority: BotDurableAuthority<undefined>;
   store: DurableCompositionStore;

package/src/composition-store.ts

@@ -8,6 +8,7 @@ import { decodeCompositionFailureV1 } from "@frockbot/kernel-composition/activat
 import {
   assertCompositionArtifactSetHashV1,
   compositionGenerationIdV1,
+  CompositionPinConflictError,
   type CompositionGenerationV1,
   type CompositionOriginV1,
   type CompositionStore,
@@ -151,7 +152,7 @@ export class DurableCompositionStore implements CompositionStore {
 
   async propose(
     generation: CompositionGenerationV1,
-    options: { pin?: boolean } = {},
+    options: { pin?: boolean; expectedCurrentGenerationId?: string } = {},
   ): Promise<void> {
     const proposed = decodeCompositionGenerationV1(generation);
     if (proposed.status !== "pending") {
@@ -164,6 +165,23 @@ export class DurableCompositionStore implements CompositionStore {
     await this.ctx.storage.transaction(async (transaction) => {
       const bootstrap = await this.bootstrapGeneration(transaction);
       this.assertRequiredCoreSet(bootstrap, proposed);
+      // Compare-and-swap before anything is written: a proposal derived from a
+      // pointer that has since moved would drop whatever the winner added, so
+      // it is refused whole rather than merged blind. Nothing has been put yet,
+      // so the caller re-derives from the pointer it lost to and tries again.
+      if (options.pin && options.expectedCurrentGenerationId !== undefined) {
+        const pointer = await transaction.get<unknown>(COMPOSITION_CURRENT_KEY);
+        const currentId =
+          pointer === undefined
+            ? undefined
+            : decodeCompositionPinV1(pointer).generationId;
+        if (currentId !== options.expectedCurrentGenerationId) {
+          throw new CompositionPinConflictError(
+            options.expectedCurrentGenerationId,
+            currentId,
+          );
+        }
+      }
       const key = compositionGenerationKey(proposed.generationId);
       if ((await transaction.get<unknown>(key)) !== undefined) {
         throw new Error(

package/src/run-records.ts

@@ -980,3 +980,60 @@ export interface BotTurnCompletion {
   events: SessionEvent[];
   notification?: BotNotificationIntent;
 }
+
+/**
+ * The little that can be trusted about a run record nobody can decode.
+ *
+ * A transcript read is display-only: it never resumes, settles or recovers a
+ * Turn, so it does not need the record to be valid — it needs enough to draw
+ * one row saying which Turn could not be read. The run id comes from the
+ * admission index key, which is authority; everything else is scraped from the
+ * raw value and kept only where it is plainly a safe, bounded string, so a
+ * record corrupt in any other field still yields a renderable row.
+ */
+export interface UnreadableStoredRunV1 {
+  readonly runId: string;
+  readonly sessionId?: string;
+  readonly acceptedAt?: string;
+  readonly input?: string;
+  readonly admission?: { readonly turnType?: TurnTypeV1 };
+}
+
+/** Scrape a record that failed to decode down to {@link UnreadableStoredRunV1}. */
+export function unreadableStoredRunV1(
+  runId: string,
+  raw: unknown,
+): UnreadableStoredRunV1 {
+  const candidate =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : {};
+  const admission =
+    candidate.admission &&
+    typeof candidate.admission === "object" &&
+    !Array.isArray(candidate.admission)
+      ? (candidate.admission as Record<string, unknown>)
+      : undefined;
+  let turnType: TurnTypeV1 | undefined;
+  try {
+    if (admission?.turnType !== undefined) {
+      turnType = decodeTurnTypeV1(admission.turnType);
+    }
+  } catch {
+    turnType = undefined;
+  }
+  return {
+    runId,
+    ...(boundedString(candidate.sessionId, 257)
+      ? { sessionId: candidate.sessionId }
+      : {}),
+    ...(boundedString(candidate.acceptedAt, 64) &&
+    Number.isFinite(Date.parse(candidate.acceptedAt))
+      ? { acceptedAt: candidate.acceptedAt }
+      : {}),
+    ...(boundedString(candidate.input, 32_000)
+      ? { input: candidate.input }
+      : {}),
+    ...(turnType ? { admission: { turnType } } : {}),
+  };
+}