@frockbot/plugin-bot-template 0.3.24 → 0.3.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-bot-template",
-  "version": "0.3.24",
+  "version": "0.3.25",
   "private": false,
   "type": "module",
   "exports": {
@@ -24,20 +24,20 @@
     "typecheck": "vue-tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/client-core": "0.3.24",
-    "@frockbot/client-ui": "0.3.24",
-    "@frockbot/configuration-core": "0.3.24",
-    "@frockbot/connection-core": "0.3.24",
-    "@frockbot/kernel-agent-loop": "0.3.24",
-    "@frockbot/kernel-contracts": "0.3.24",
-    "@frockbot/plugin-settings": "0.3.24",
-    "@frockbot/plugin-shell": "0.3.24",
-    "@frockbot/template-core": "0.3.24",
+    "@frockbot/client-core": "0.3.25",
+    "@frockbot/client-ui": "0.3.25",
+    "@frockbot/configuration-core": "0.3.25",
+    "@frockbot/connection-core": "0.3.25",
+    "@frockbot/kernel-agent-loop": "0.3.25",
+    "@frockbot/kernel-contracts": "0.3.25",
+    "@frockbot/plugin-settings": "0.3.25",
+    "@frockbot/plugin-shell": "0.3.25",
+    "@frockbot/template-core": "0.3.25",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
-    "@frockbot/plugin-tools": "0.3.24",
+    "@frockbot/plugin-tools": "0.3.25",
     "@types/bun": "1.4.0",
     "@vitejs/plugin-vue": "6.0.8",
     "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",

package/src/import-apply.test.ts

@@ -35,6 +35,14 @@ const sheep = {
 
 class MemoryStorage implements UserSettingsStorage {
   readonly values = new Map<string, unknown>();
+  /**
+   * The order durable writes and alarm arming happened in. An import that is
+   * mid-apply has to be recoverable from the alarm alone, so "the deadline was
+   * recorded before the record said `applying`" is the claim, not merely "an
+   * alarm was set at some point".
+   */
+  readonly trace: string[] = [];
+  alarm: number | null = null;
   get<T>(key: string): Promise<T | undefined> {
     return Promise.resolve(this.values.get(key) as T | undefined);
   }
@@ -44,14 +52,35 @@ class MemoryStorage implements UserSettingsStorage {
     keyOrEntries: string | Record<string, unknown>,
     value?: T,
   ): Promise<void> {
-    if (typeof keyOrEntries === "string") this.values.set(keyOrEntries, value);
+    if (typeof keyOrEntries === "string") this.record(keyOrEntries, value);
     else {
       for (const [key, entry] of Object.entries(keyOrEntries)) {
-        this.values.set(key, entry);
+        this.record(key, entry);
       }
     }
     return Promise.resolve();
   }
+  getAlarm(): Promise<number | null> {
+    return Promise.resolve(this.alarm);
+  }
+  setAlarm(scheduledTime: number | Date): Promise<void> {
+    this.alarm =
+      typeof scheduledTime === "number"
+        ? scheduledTime
+        : scheduledTime.getTime();
+    this.trace.push("alarm:set");
+    return Promise.resolve();
+  }
+  private record(key: string, value: unknown): void {
+    this.values.set(key, value);
+    if (key === "bot-template:import-recovery-at") {
+      this.trace.push(value ? "recovery:owed" : "recovery:clear");
+    }
+    const status = (value as { status?: unknown } | undefined)?.status;
+    if (key.startsWith("bot-template:import:") && typeof status === "string") {
+      this.trace.push(`import:${status}`);
+    }
+  }
   async transaction<T>(
     callback: (storage: UserSettingsTransaction) => Promise<T>,
   ): Promise<T> {
@@ -438,6 +467,75 @@ describe("failure is a visible, repairable record", () => {
     ).toHaveLength(1);
   });
 
+  it("records the recovery deadline before the record says applying", async () => {
+    const { contribution, storage } = await harness();
+    await plan(contribution);
+    storage.trace.length = 0;
+    await apply(contribution);
+
+    // The deadline and the alarm are both in place before the record enters
+    // `applying`, so an eviction at any point after that leaves an object
+    // scheduled to finish the walk.
+    expect(storage.trace[0]).toBe("recovery:owed");
+    expect(storage.trace.indexOf("alarm:set")).toBeLessThan(
+      storage.trace.indexOf("import:applying"),
+    );
+  });
+
+  it("clears the recovery debt once the import is terminal", async () => {
+    const { contribution, storage } = await harness();
+    await plan(contribution);
+    await apply(contribution);
+    expect(storage.values.get("bot-template:import-recovery-at")).toBe(0);
+  });
+
+  it("records a visible failure and clears the debt when a step fails", async () => {
+    const failures: Record<string, string> = {};
+    const { contribution, storage } = await harness({ failures });
+    const record = await plan(contribution);
+    // The state an eviction mid-walk leaves: `applying`, with no process to
+    // finish it. This pass cannot finish it either, because the writer throws.
+    failures.install = "the Catalog is unreachable";
+    await storage.put(`bot-template:import:${record.importId}`, {
+      ...record,
+      status: "applying",
+      steps: record.steps.map((step) =>
+        step.kind === "bot/create" ? { ...step, status: "done" } : step,
+      ),
+    });
+    await contribution.recoverImports(USER);
+
+    // Failed is terminal and repairable — the card names the step and the
+    // reason — so nothing is owed a further recovery.
+    const listed = (await contribution.listImports(USER)).imports[0]!;
+    expect(listed.status).toBe("failed");
+    expect(listed.failure).toContain("the Catalog is unreachable");
+    expect(storage.values.get("bot-template:import-recovery-at")).toBe(0);
+  });
+
+  it("re-arms the alarm when a recovery pass leaves the import applying", async () => {
+    const { contribution, storage } = await harness();
+    const record = await plan(contribution);
+    await storage.put(`bot-template:import:${record.importId}`, {
+      ...record,
+      status: "applying",
+    });
+    // The plan the walk needs is unreadable, so the pass throws before any
+    // step runs and the record stays `applying`.
+    storage.values.delete(`bot-template:import:plan:${record.importId}`);
+    storage.alarm = null;
+    await contribution.recoverImports(USER);
+
+    const listed = (await contribution.listImports(USER)).imports[0]!;
+    expect(listed.status).toBe("applying");
+    // Still owed, and still scheduled: the next alarm tries again rather than
+    // the import waiting for unrelated work to wake the object.
+    expect(
+      storage.values.get("bot-template:import-recovery-at"),
+    ).toBeGreaterThan(0);
+    expect(storage.alarm).not.toBeNull();
+  });
+
   it("resumes an import left mid-apply from the recovery pass", async () => {
     const { contribution, recording, storage } = await harness();
     const record = await plan(contribution);

package/src/shared.ts

@@ -422,6 +422,17 @@ export interface TemplateImportReceiptV1 {
 /** Most imports one User may hold, so planning cannot fill the object. */
 export const MAX_TEMPLATE_IMPORTS_V1 = 100;
 
+/**
+ * Where one import record lives in the User Durable Object's storage.
+ *
+ * Named here rather than kept private to the Contribution because a durability
+ * test has to be able to leave an import in the state an eviction mid-apply
+ * would leave it in, without an RPC that would also finish it.
+ */
+export function templateImportRecordKeyV1(importId: string): string {
+  return `bot-template:import:${importId}`;
+}
+
 function importStatus(value: unknown): TemplateImportStatusV1 {
   const found = TEMPLATE_IMPORT_STATUSES_V1.find((known) => known === value);
   if (!found)

package/src/user.ts

@@ -58,6 +58,7 @@ import {
   type TemplateImportRecordV1,
   type TemplateImportStepReceiptV1,
   templateCommandFingerprintV1,
+  templateImportRecordKeyV1,
   type TemplateCommandV1,
   type TemplateExportSummaryV1,
   type TemplateShareListViewV1,
@@ -70,6 +71,23 @@ export const BOT_TEMPLATE_PACKAGE_ID = "bot-template";
 const SHARE_PREFIX = "bot-template:share:";
 const IMPORT_PREFIX = "bot-template:import:";
 const IMPORT_INDEX_KEY = "bot-template:import-index";
+/**
+ * The durable record that a recovery pass is owed.
+ *
+ * An apply that is evicted mid-walk leaves its record `applying` and nothing
+ * in the process to finish it, so the intent to recover is written down before
+ * the record enters that state and is cleared only once no import is mid-apply.
+ * A value of `0` means nothing is owed.
+ */
+const IMPORT_RECOVERY_KEY = "bot-template:import-recovery-at";
+/**
+ * How long after entering `applying` the alarm is asked to fire.
+ *
+ * Short, because it is a recovery deadline rather than a schedule: an apply
+ * that finishes in-process clears it before it matters, and one that does not
+ * is work a User is waiting on.
+ */
+const IMPORT_RECOVERY_DELAY_MS = 5_000;
 const SHARE_INDEX_KEY = "bot-template:share-index";
 const RECEIPT_PREFIX = "bot-template:receipt:";
 
@@ -154,8 +172,22 @@ export interface TemplateImportWriterV1 {
   }): Promise<{ status: string; routineId?: string }>;
 }
 
+/**
+ * This Package's slice of the User Durable Object's storage.
+ *
+ * `setAlarm` is how an import that is still mid-apply keeps its own recovery
+ * scheduled instead of waiting for some other owner of the object's single
+ * alarm to happen to wake it. Both alarm methods are optional so a host with
+ * no alarm at all still imports; on such a host an interrupted import stays
+ * visible and repairable rather than resuming by itself.
+ */
+export interface BotTemplateStorageV1 extends UserSettingsStorage {
+  getAlarm?(): Promise<number | null>;
+  setAlarm?(scheduledTime: number | Date): Promise<void>;
+}
+
 export interface BotTemplateUserHostV1 {
-  storage: UserSettingsStorage;
+  storage: BotTemplateStorageV1;
   settings: UserSettingsBackendContribution;
   bots: TemplateBotReaderV1;
   blobs: TemplateBlobStoreV1;
@@ -613,6 +645,12 @@ export class BotTemplateUserBackendContribution {
     const plan = await this.readImportPlan(importId);
     if (!plan) throw new TemplateShareNotFoundError(importId);
 
+    // The recovery deadline is written *before* the record says `applying`.
+    // An eviction between the two then leaves an object that is owed a
+    // recovery it does not need, which the next pass simply clears; the other
+    // order would leave an import mid-apply that nothing is scheduled to
+    // finish.
+    await this.scheduleImportRecovery();
     record = await this.patchImport(importId, (current) => ({
       ...current,
       status: "applying",
@@ -626,7 +664,7 @@ export class BotTemplateUserBackendContribution {
         outcome = await this.runImportStep(userId, plan, step, writer);
       } catch (error) {
         const failure = error instanceof Error ? error.message : String(error);
-        return this.patchImport(importId, (current) => ({
+        const failed = await this.patchImport(importId, (current) => ({
           ...current,
           status: "failed",
           failure: `${step.key}: ${failure}`,
@@ -636,6 +674,10 @@ export class BotTemplateUserBackendContribution {
               : entry,
           ),
         }));
+        // Failed is terminal and visible: the card carries the failure and
+        // re-issuing the command retries. Nothing is owed a recovery.
+        await this.settleImportRecovery();
+        return failed;
       }
       record = await this.patchImport(importId, (current) => ({
         ...current,
@@ -654,10 +696,12 @@ export class BotTemplateUserBackendContribution {
         ),
       }));
     }
-    return this.patchImport(importId, (current) => ({
+    const applied = await this.patchImport(importId, (current) => ({
       ...current,
       status: "applied",
     }));
+    await this.settleImportRecovery();
+    return applied;
   }
 
   /** Every import left mid-apply, resumed. Called from the User DO's alarm. */
@@ -673,6 +717,45 @@ export class BotTemplateUserBackendContribution {
         // finish must not stop the other owners of this alarm from running.
       }
     }
+    // A pass that could not finish an import leaves it `applying`, so the
+    // deadline is re-armed here: recovery stays scheduled until every import
+    // is terminal, rather than depending on some other owner of this object's
+    // alarm to fire again.
+    await this.settleImportRecovery();
+  }
+
+  /**
+   * Write down that a recovery is owed, and pull the object's alarm forward to
+   * the deadline if nothing earlier is already scheduled.
+   */
+  private async scheduleImportRecovery(): Promise<void> {
+    const storage = this.host.storage;
+    if (!storage.setAlarm) return;
+    const at = this.now() + IMPORT_RECOVERY_DELAY_MS;
+    await storage.put(IMPORT_RECOVERY_KEY, at);
+    const scheduled = await storage.getAlarm?.();
+    if (scheduled === undefined || scheduled === null || scheduled > at) {
+      await storage.setAlarm(at);
+    }
+  }
+
+  /**
+   * Clear the recovery debt, or renew it if any import is still mid-apply.
+   *
+   * The object's single alarm belongs to every User-scoped owner of one, so
+   * this never cancels it: it only records that this Package no longer needs
+   * it, and re-arms when it does.
+   */
+  private async settleImportRecovery(): Promise<void> {
+    if (!this.host.storage.setAlarm) return;
+    for (const importId of await this.importIndex()) {
+      const record = await this.readImport(importId);
+      if (record?.status === "applying") {
+        await this.scheduleImportRecovery();
+        return;
+      }
+    }
+    await this.host.storage.put(IMPORT_RECOVERY_KEY, 0);
   }
 
   private async runImportStep(
@@ -805,7 +888,7 @@ export class BotTemplateUserBackendContribution {
         );
       }
       await transaction.put({
-        [`${IMPORT_PREFIX}${record.importId}`]: record,
+        [templateImportRecordKeyV1(record.importId)]: record,
         [`${IMPORT_PREFIX}plan:${record.importId}`]: plan,
         [IMPORT_INDEX_KEY]: [...index, record.importId],
       });
@@ -818,14 +901,14 @@ export class BotTemplateUserBackendContribution {
   ): Promise<TemplateImportRecordV1> {
     return this.host.storage.transaction(async (transaction) => {
       const stored = await transaction.get<unknown>(
-        `${IMPORT_PREFIX}${importId}`,
+        templateImportRecordKeyV1(importId),
       );
       if (stored === undefined) throw new TemplateShareNotFoundError(importId);
       const next = decodeTemplateImportRecordV1({
         ...patch(decodeTemplateImportRecordV1(stored)),
         updatedAt: new Date(this.now()).toISOString(),
       });
-      await transaction.put(`${IMPORT_PREFIX}${importId}`, next);
+      await transaction.put(templateImportRecordKeyV1(importId), next);
       return next;
     });
   }
@@ -834,7 +917,7 @@ export class BotTemplateUserBackendContribution {
     importId: string,
   ): Promise<TemplateImportRecordV1 | undefined> {
     const stored = await this.host.storage.get<unknown>(
-      `${IMPORT_PREFIX}${importId}`,
+      templateImportRecordKeyV1(importId),
     );
     return stored === undefined
       ? undefined