@frockbot/kernel-do 0.3.41 → 0.3.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-do",
-  "version": "0.3.41",
+  "version": "0.3.42",
   "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.42",
+    "@frockbot/kernel-contracts": "0.3.42",
     "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,
@@ -67,6 +70,7 @@ import {
 } from "./conversations.js";
 import {
   ACTIVE_RUN_KEY,
+  COMPOSITION_CURRENT_KEY,
   CONVERSATION_INDEX_KEY,
   CONVERSATION_KEY,
   MAX_LISTED_CONVERSATIONS,
@@ -400,6 +404,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 +461,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>);

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(