@frockbot/kernel-do 0.3.25 → 0.3.26

package/package.json

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

package/src/applets.test.ts

@@ -18,7 +18,10 @@ import {
   decodeAppletHealthV1,
   decodeAppletMountInputV1,
   decodeAppletPointerV1,
+  decodeAppletTrialV1,
   decodeFocusedAppletV1,
+  APPLET_ROLLBACK_FACET_NAME_V1,
+  APPLET_TRIAL_KEY,
   mintAppletViewerTokenV1,
   newAppletIdV1,
   verifyAppletViewerTokenV1,
@@ -189,6 +192,36 @@ describe("Applet durable records", () => {
     ).toThrow();
   });
 
+  test("a trial names the candidate, and the previous generation only when there is one", () => {
+    const mountInput = {
+      schemaVersion: 1 as const,
+      userId: "user-42",
+      appletId: APPLET,
+      generationId: "g2",
+      loaderId: HASH_A,
+      serverHash: HASH_B,
+      contract: 1,
+    };
+    const first = { schemaVersion: 1 as const, candidate: mountInput };
+    expect(decodeAppletTrialV1(first)).toEqual(first as never);
+    const over = {
+      schemaVersion: 1 as const,
+      candidate: mountInput,
+      previous: { ...mountInput, generationId: "g1" },
+    };
+    expect(decodeAppletTrialV1(over)).toEqual(over as never);
+    expect(() =>
+      decodeAppletTrialV1({
+        ...first,
+        candidate: { ...mountInput, contract: 2 },
+      }),
+    ).toThrow();
+    // The rollback facet is a facet name, not a storage key: they must not
+    // collide with the live one.
+    expect(APPLET_ROLLBACK_FACET_NAME_V1).toBe("applet-rollback");
+    expect(APPLET_TRIAL_KEY).toBe("applet:trial");
+  });
+
   test("a focused Applet may be null", () => {
     const focused = {
       schemaVersion: 1 as const,

package/src/applets.ts

@@ -65,6 +65,17 @@ export const APPLET_FAILURE_PREFIX = "applet:failure:";
  * at mount time.
  */
 export const APPLET_MOUNT_INPUT_KEY = "applet:mount-input";
+/**
+ * Applet Durable Object: the open activation trial, if one is in flight.
+ *
+ * An activation is a commit boundary the kernel owns, not a mount the candidate
+ * is trusted to survive (ADR 0038). While this key exists the facet's storage is
+ * provisional: a byte copy of it is parked in the rollback facet, and whatever
+ * reads the Applet next either finds the trial committed — the key deleted — or
+ * rolls it back before answering. That is what makes an interrupted publish
+ * recoverable rather than half-migrated.
+ */
+export const APPLET_TRIAL_KEY = "applet:trial";
 /** Bot Durable Object: the Session's focused Applet. */
 export const APPLET_FOCUSED_KEY = "applets:focused";
 
@@ -72,6 +83,16 @@ export const APPLET_FOCUSED_KEY = "applets:focused";
 export const APPLET_FAILURE_ATTEMPT_DIGITS = 4;
 /** The one facet name the kernel mounts under an `AppletState` object. */
 export const APPLET_FACET_NAME_V1 = "applet";
+/**
+ * The second facet name an `AppletState` object uses, and it holds no code.
+ *
+ * The Durable Object facet API can clone a facet's whole storage, so the kernel
+ * parks a byte copy of the live Applet here for the length of one activation
+ * trial and clones it back if the candidate fails. Nothing is ever mounted
+ * against it; it exists only to be copied from. `AppletState` is the one place
+ * that call is made, and an architecture check keeps it that way.
+ */
+export const APPLET_ROLLBACK_FACET_NAME_V1 = "applet-rollback";
 /** The Instance Contract version this kernel speaks. */
 export const APPLET_CONTRACT_V1 = 1;
 /** Most generations one Applet retains before the oldest are pruned. */
@@ -166,6 +187,20 @@ export interface AppletMountInputV1 {
   contract: 1;
 }
 
+/**
+ * One activation in flight: which generation is being tried over the Applet's
+ * live storage, and which one the rollback facet holds the storage of.
+ *
+ * `previous` is absent for an Applet's first generation, where there is no data
+ * to protect and a failure discards the candidate's storage instead of
+ * restoring anything.
+ */
+export interface AppletTrialV1 {
+  schemaVersion: 1;
+  candidate: AppletMountInputV1;
+  previous?: AppletMountInputV1;
+}
+
 /** One Session's focused Applet. `null` closes the canvas. */
 export interface FocusedAppletV1 {
   schemaVersion: 1;
@@ -352,6 +387,29 @@ export function decodeAppletMountInputV1(
   };
 }
 
+export function decodeAppletTrialV1(
+  input: unknown,
+  label = "Applet trial",
+): AppletTrialV1 {
+  const value = record(input, label);
+  exactKeys(value, ["schemaVersion", "candidate"], ["previous"], label);
+  if (value.schemaVersion !== 1) {
+    throw new Error(`${label}.schemaVersion is unsupported`);
+  }
+  return {
+    schemaVersion: 1,
+    candidate: decodeAppletMountInputV1(value.candidate, `${label}.candidate`),
+    ...(value.previous === undefined
+      ? {}
+      : {
+          previous: decodeAppletMountInputV1(
+            value.previous,
+            `${label}.previous`,
+          ),
+        }),
+  };
+}
+
 export function decodeFocusedAppletV1(
   input: unknown,
   label = "focused Applet",