@frockbot/plugin-fly-sprite 0.3.26 → 0.3.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-fly-sprite",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "private": false,
   "type": "module",
   "exports": {
@@ -25,16 +25,16 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/computer-core": "0.3.26",
-    "@frockbot/computer-host-protocol": "0.3.26",
-    "@frockbot/computer-host-runtime": "0.3.26",
-    "@frockbot/kernel-contracts": "0.3.26",
-    "@frockbot/plugin-computer": "0.3.26",
+    "@frockbot/computer-core": "0.3.28",
+    "@frockbot/computer-host-protocol": "0.3.28",
+    "@frockbot/computer-host-runtime": "0.3.28",
+    "@frockbot/kernel-contracts": "0.3.28",
+    "@frockbot/plugin-computer": "0.3.28",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {
-    "@frockbot/plugin-testkit": "0.3.26",
-    "@frockbot/workspace-store": "0.3.26",
+    "@frockbot/plugin-testkit": "0.3.28",
+    "@frockbot/workspace-store": "0.3.28",
     "@types/bun": "1.4.0",
     "@types/node": "26.2.0",
     "typescript": "^7.0.2"

package/src/provider.ts

@@ -304,6 +304,7 @@ function summarize(report: WorkspaceSyncReportV1): ComputerSyncSummaryV1 {
   const failed = report.failures[0];
   const ignored = total((root) => root.ignored);
   const omitted = total((root) => root.omitted);
+  const required = report.roots.flatMap((root) => root.required);
   const detail: string[] = [];
   // Reproducible trees (node_modules, dist, …) are excluded by design; the
   // count is kept on the summary for the Session log, but it is not a reason
@@ -315,6 +316,16 @@ function summarize(report: WorkspaceSyncReportV1): ComputerSyncSummaryV1 {
       `Omitted ${omitted} manifest ${omitted === 1 ? "entry" : "entries"} at the sync safety limit.`,
     );
   }
+  // A path the caller declared required, that the Computer holds and the store
+  // still does not, is the one outcome a caller must never read as success.
+  const stranded = required.filter(
+    (entry) => entry.contentHash !== undefined && !entry.durable,
+  );
+  if (stranded[0]) {
+    detail.push(
+      `${stranded.length} required ${stranded.length === 1 ? "file is" : "files are"} on the Computer but not in the Workspace, starting at "${stranded[0].path}".`,
+    );
+  }
   if (failed) {
     detail.push(
       `${report.failures.length} sync ${report.failures.length === 1 ? "operation" : "operations"} failed${failed.path ? ` at "${failed.path}"` : ""}: ${failed.status}: ${failed.reason}.`,
@@ -328,7 +339,7 @@ function summarize(report: WorkspaceSyncReportV1): ComputerSyncSummaryV1 {
       report.failures.length > 0 &&
       report.roots.every((root) => root.failures.length > 0)
         ? "unavailable"
-        : report.failures.length > 0 || omitted > 0
+        : report.failures.length > 0 || omitted > 0 || stranded.length > 0
           ? "degraded"
           : "ok",
     detail: detail.join(" ").slice(0, 512),
@@ -343,6 +354,7 @@ function summarize(report: WorkspaceSyncReportV1): ComputerSyncSummaryV1 {
     omitted,
     conflicts: report.conflicts.length,
     failures: report.failures.length,
+    ...(required.length > 0 ? { required } : {}),
   };
   return summary;
 }

package/src/sync.test.ts

@@ -11,7 +11,10 @@ import {
   type WorkspaceRootV1,
   type WorkspaceWriterV1,
 } from "@frockbot/kernel-contracts";
-import { createObjectWorkspaceFilesV1 } from "@frockbot/workspace-store";
+import {
+  createObjectWorkspaceFilesV1,
+  workspaceObjectKeyV1,
+} from "@frockbot/workspace-store";
 import {
   createInMemoryObjectBucketV1,
   createInMemoryWorkspaceGenerationsV1,
@@ -1351,7 +1354,7 @@ describe("the durable-root sync on the Computer handle", () => {
         { botId: BOT },
         { providerId: "fly-sprite", generation: 1 },
       );
-    return { sprite, store, generations, effects, provider, open };
+    return { sprite, store, bucket, generations, effects, provider, open };
   }
 
   test("pulls the store's durable roots onto the Computer before the Bot's first use", async () => {
@@ -1488,6 +1491,173 @@ describe("the durable-root sync on the Computer handle", () => {
     expect(refused.status).toBe("refused");
   });
 
+  // Production, 2026-09-04, run 76b4f8d9: `applet build` wrote `dist/`, the
+  // publish sync answered `pushed=0 removed=0 failures=0`, and the publish then
+  // read `dist/manifest.json` as `not-found` and told the Bot to build again.
+  // The reconcile had trusted the sidecar: hash matched, entry "clean",
+  // nothing to do — while the store held no object for it at all. A required
+  // path is the one thing the caller has asserted about, so the Computer's
+  // copy of it decides, not its sidecar.
+  test("pushes a required file the store is missing even when its sidecar says clean", async () => {
+    const { sprite, store, open } = providerHarness([
+      APPLET_SOURCE_PACKAGE_ROOT,
+    ]);
+    const handle = await open();
+    const appletId = "pub-user-1.0123456789abcdef0123456789abcdef";
+    const path = `${appletId}/dist/manifest.json`;
+    const manifest = '{"tools":[{"name":"add"},{"name":"list"}]}';
+    sprite.shellWrite(MOUNTS.appletSource, path, manifest);
+    // One good publish: the store takes the bytes and the Computer records the
+    // sidecar that attributes them.
+    await handle.sync!.reconcileRoot!(appletSourceRoot, "publish", {
+      requiredPaths: [path],
+    });
+    const stat = await store.stat({ root: appletSourceRoot, path });
+    expect(stat.status).toBe("ok");
+    if (stat.status !== "ok") return;
+    // The object goes; the sidecar and the built file do not.
+    await store.delete({
+      path: { root: appletSourceRoot, path },
+      writer: USER_WRITER,
+      expectedGenerationId: stat.entry.generation.generationId,
+    });
+    expect(
+      sprite.files.has(`${MOUNTS.appletSource}/.frockbot-generations/${path}`),
+    ).toBe(true);
+
+    const summary = await handle.sync!.reconcileRoot!(
+      appletSourceRoot,
+      "publish",
+      { requiredPaths: [path] },
+    );
+
+    expect(summary).toMatchObject({
+      status: "ok",
+      pushed: 1,
+      removed: 0,
+      failures: 0,
+    });
+    const read = await store.read({ root: appletSourceRoot, path });
+    expect(read.status).toBe("ok");
+    if (read.status === "ok")
+      expect(decoder.decode(read.file.bytes)).toBe(manifest);
+    expect(summary.required).toEqual([
+      { path, contentHash: sha256(encoder.encode(manifest)), durable: true },
+    ]);
+  });
+
+  // The same drift, the other way round: the file the publish needs must never
+  // be deleted from the Computer because the store is missing it. Before this,
+  // the reconcile read the absence as a store-side delete and removed the build
+  // output — the publish's own artifact — on the way past.
+  test("never removes a required file from the Computer because the store lacks it", async () => {
+    const { sprite, store, generations, open } = providerHarness([
+      APPLET_SOURCE_PACKAGE_ROOT,
+    ]);
+    const handle = await open();
+    const appletId = "pub-user-1.0123456789abcdef0123456789abcdef";
+    const path = `${appletId}/dist/server.js`;
+    sprite.shellWrite(MOUNTS.appletSource, path, "export class A{}");
+    await handle.sync!.reconcileRoot!(appletSourceRoot, "publish", {
+      requiredPaths: [path],
+    });
+    const stat = await store.stat({ root: appletSourceRoot, path });
+    if (stat.status !== "ok") throw new Error("the first push did not land");
+    // A recorded store-side delete: the ledger holds a tombstone, so this is a
+    // removal by every rule the sync knows — and a required path still wins.
+    await store.delete({
+      path: { root: appletSourceRoot, path },
+      writer: USER_WRITER,
+      expectedGenerationId: stat.entry.generation.generationId,
+    });
+    expect((await generations.current(appletSourceRoot, path))?.deleted).toBe(
+      true,
+    );
+
+    await handle.sync!.reconcileRoot!(appletSourceRoot, "publish", {
+      requiredPaths: [path],
+    });
+
+    expect(sprite.text(`${MOUNTS.appletSource}/${path}`)).toBe(
+      "export class A{}",
+    );
+    expect((await store.read({ root: appletSourceRoot, path })).status).toBe(
+      "ok",
+    );
+  });
+
+  // A store that lost the object but kept the generation the sidecar names is
+  // repaired rather than re-written: the bytes already match, so a second
+  // generation for identical content would be noise in the ledger.
+  test("repairs a required file's sidecar without writing a second generation", async () => {
+    const { sprite, store, open } = providerHarness([
+      APPLET_SOURCE_PACKAGE_ROOT,
+    ]);
+    const handle = await open();
+    const appletId = "pub-user-1.0123456789abcdef0123456789abcdef";
+    const path = `${appletId}/dist/manifest.json`;
+    sprite.shellWrite(MOUNTS.appletSource, path, '{"tools":[]}');
+    await handle.sync!.reconcileRoot!(appletSourceRoot, "publish", {
+      requiredPaths: [path],
+    });
+    // `rm -rf dist && applet build` reproducing byte-identical output, with the
+    // sidecar lost: the store already holds these bytes.
+    sprite.files.delete(`${MOUNTS.appletSource}/.frockbot-generations/${path}`);
+
+    const summary = await handle.sync!.reconcileRoot!(
+      appletSourceRoot,
+      "publish",
+      { requiredPaths: [path] },
+    );
+
+    expect(summary).toMatchObject({ status: "ok", pushed: 0, conflicts: 0 });
+    expect(summary.required).toMatchObject([{ path, durable: true }]);
+    expect(
+      sprite.files.has(`${MOUNTS.appletSource}/.frockbot-generations/${path}`),
+    ).toBe(true);
+  });
+
+  // A required file the Computer simply does not have is still a truthful
+  // answer, and the caller is owed the fact rather than a silent `ok`.
+  test("reports a required file the Computer does not hold", async () => {
+    const { open } = providerHarness([APPLET_SOURCE_PACKAGE_ROOT]);
+    const handle = await open();
+    const path = "pub-user-1.0123456789abcdef0123456789abcdef/dist/ui.html";
+
+    const summary = await handle.sync!.reconcileRoot!(
+      appletSourceRoot,
+      "publish",
+      { requiredPaths: [path] },
+    );
+
+    expect(summary.status).toBe("ok");
+    expect(summary.required).toEqual([{ path, durable: false }]);
+  });
+
+  // ADR 0013 makes a delete a recorded generation, so an absence the ledger
+  // never recorded is drift and not a removal. The general case: an ordinary
+  // Skill whose object went missing under a sidecar keeps its bytes, and the
+  // sync puts them back rather than deleting the User's file.
+  test("re-pushes rather than removes when the store recorded no removal", async () => {
+    const { sprite, store, bucket, open } = providerHarness();
+    const handle = await open();
+    sprite.shellWrite(MOUNTS.skills, "deploy/SKILL.md", "# deploy");
+    await handle.sync!.reconcile("turn-end");
+    expect(
+      (await store.read({ root: skillsRoot, path: "deploy/SKILL.md" })).status,
+    ).toBe("ok");
+    // The object disappears with no ledger tombstone: not a delete anyone made.
+    await bucket.delete(workspaceObjectKeyV1(skillsRoot, "deploy/SKILL.md"));
+
+    const summary = await handle.sync!.reconcile("turn-end");
+
+    expect(summary).toMatchObject({ removed: 0, failures: 0 });
+    expect(sprite.text(`${MOUNTS.skills}/deploy/SKILL.md`)).toBe("# deploy");
+    expect(
+      (await store.read({ root: skillsRoot, path: "deploy/SKILL.md" })).status,
+    ).toBe("ok");
+  });
+
   // Production, 2026-09-04: `applet build` wrote a 470 KB `dist/ui.html`, and
   // every publish that followed failed, because one `base64` of the file was
   // 627 KB of answer and the storage command may answer 500 KB. Both directions

package/src/sync.ts

@@ -309,6 +309,20 @@ export interface WorkspaceSyncFailureV1 extends WorkspaceFailureV1 {
   path?: string;
 }
 
+/**
+ * What the run saw for one path its caller declared required.
+ *
+ * `durable` is a statement about the store and not about the sidecar: it is
+ * true only when the store answered with the same content hash the Computer
+ * holds, or accepted a push of exactly those bytes during this run.
+ */
+export interface WorkspaceSyncRequiredPathV1 {
+  path: string;
+  /** sha-256 of the bytes on the Computer, absent when it held no such file. */
+  contentHash?: string;
+  durable: boolean;
+}
+
 export interface WorkspaceSyncRootReportV1 {
   root: WorkspaceRootV1;
   /** Store generations materialized on the Computer. */
@@ -329,6 +343,8 @@ export interface WorkspaceSyncRootReportV1 {
   omitted: number;
   conflicts: WorkspaceSyncConflictV1[];
   failures: WorkspaceSyncFailureV1[];
+  /** One row per path the caller declared required; empty when it named none. */
+  required: WorkspaceSyncRequiredPathV1[];
 }
 
 export interface WorkspaceSyncReportV1 {
@@ -405,6 +421,7 @@ function emptyReport(root: WorkspaceRootV1): WorkspaceSyncRootReportV1 {
     omitted: 0,
     conflicts: [],
     failures: [],
+    required: [],
   };
 }
 
@@ -439,6 +456,7 @@ class WorkspaceRootSync implements WorkspaceRootSyncV1 {
     requiredPaths: readonly string[] = [],
   ): Promise<WorkspaceSyncRootReportV1> {
     const report = emptyReport(root);
+    const required = new Set(requiredPaths);
     const scanned = await this.options.computer.scan(root, requiredPaths);
     if (isFailure(scanned)) {
       report.failures.push({ ...scanned, root });
@@ -468,8 +486,28 @@ class WorkspaceRootSync implements WorkspaceRootSyncV1 {
       // Push first: a Computer-side write must reach the store's conditional
       // write before the pull could overwrite it.
       for (const entry of scanned.scan.entries) {
-        if (this.clean(entry)) continue;
-        const pushed = await this.push(root, entry, report);
+        // A required path is authoritative on the Computer. The caller has
+        // asserted that these exact bytes must be readable from the store when
+        // this returns, so the sidecar's opinion is not enough: ask the store
+        // what it holds, and push whenever it does not hold these bytes. A
+        // sidecar that survived its file (sidecars live outside `dist/`, so
+        // `rm -rf dist` never touches them) or an object the store lost after
+        // the push that recorded one otherwise leaves a "clean" entry nobody
+        // ever carries — the publish failure of 2026-09-04.
+        const drift = required.has(entry.path)
+          ? await this.requiredDrift(root, entry, report)
+          : undefined;
+        if (drift?.kind === "aligned") {
+          settled.add(entry.path);
+          continue;
+        }
+        if (!drift && this.clean(entry)) continue;
+        const pushed = await this.push(
+          root,
+          entry,
+          report,
+          drift ? { expected: drift.expected } : undefined,
+        );
         if (pushed === "pushed") settled.add(entry.path);
         else if (pushed === "conflict") conflicted.add(entry.path);
         else held.add(entry.path);
@@ -515,16 +553,91 @@ class WorkspaceRootSync implements WorkspaceRootSyncV1 {
       if (stored.generations.has(entry.path)) continue;
       if (held.has(entry.path) || settled.has(entry.path)) continue;
       if (conflicted.has(entry.path)) continue;
+      // A required path is never turned into a local removal. The caller named
+      // it because the Computer's copy is the thing being published; deleting
+      // it because the store is missing it destroys the very bytes the caller
+      // asked for, and the forced push above has already had its say.
+      if (required.has(entry.path)) continue;
       if (!entry.recorded) continue;
       // The Computer holds a file the store recorded and no longer holds: a
       // delete happened there. It becomes a removal here, recorded, never a
-      // silent overwrite.
-      const removed = await this.removeLocally(root, entry, report);
+      // silent overwrite — *if* the store actually recorded a removal. When
+      // the ledger is reachable and holds no tombstone for the path, this is
+      // sidecar/store drift rather than a delete, and re-pushing the bytes the
+      // Computer still holds is the repair. See ADR 0013: a removal is a
+      // recorded generation, so an absence with no record is not one.
+      const tombstone = await this.storeTombstone(root, entry);
+      if (tombstone === "no-removal-recorded") {
+        if (readOnlyOnComputer) continue;
+        const pushed = await this.push(root, entry, report, {
+          expected: null,
+        });
+        if (pushed === "pushed") settled.add(entry.path);
+        continue;
+      }
+      const removed = await this.removeLocally(root, entry, report, tombstone);
       if (removed) report.removedOnComputer.push(entry.path);
     }
+    for (const path of required) {
+      const entry = local.get(path);
+      report.required.push({
+        path,
+        ...(entry ? { contentHash: entry.contentHash } : {}),
+        // Either this run put those bytes in the store, or the listing already
+        // answered with them. Anything else is reported as not durable, which
+        // is what makes the caller's own failure honest.
+        durable:
+          entry !== undefined &&
+          (settled.has(path) ||
+            stored.generations.get(path)?.contentHash === entry.contentHash),
+      });
+    }
     return report;
   }
 
+  /**
+   * What the store holds for one required path, when that differs from the
+   * Computer.
+   *
+   * `undefined` means nothing is provable — the store could not answer — and
+   * the sidecar rule stands. `aligned` means the store already holds these
+   * exact bytes, and the sidecar (missing or stale) is repaired rather than a
+   * second generation written. Otherwise the answer carries the generation the
+   * forced push must condition on, so the push cannot lose a race it started.
+   */
+  private async requiredDrift(
+    root: WorkspaceRootV1,
+    entry: ComputerSyncEntryV1,
+    report: WorkspaceSyncRootReportV1,
+  ): Promise<
+    { kind: "aligned" } | { kind: "push"; expected: string | null } | undefined
+  > {
+    const current = await this.options.store.stat({ root, path: entry.path });
+    if (current.status === "not-found") {
+      return this.clean(entry) ? { kind: "push", expected: null } : undefined;
+    }
+    if (current.status !== "ok") return undefined;
+    if (current.entry.generation.contentHash !== entry.contentHash) {
+      return { kind: "push", expected: current.entry.generation.generationId };
+    }
+    if (entry.recorded?.generationId === current.entry.generation.generationId)
+      return { kind: "aligned" };
+    // The store holds these bytes under a generation the Computer does not
+    // record. Repair the sidecar so the next run agrees, and carry nothing.
+    const bytes = await this.options.computer.read(root, entry.path);
+    if (isFailure(bytes)) return { kind: "aligned" };
+    const sidecar = await this.options.computer.materialize(
+      root,
+      entry.path,
+      bytes.bytes,
+      current.entry.generation,
+    );
+    if (sidecar.status !== "ok") {
+      report.failures.push({ ...sidecar, root, path: entry.path });
+    }
+    return { kind: "aligned" };
+  }
+
   /** True when the file's bytes are still the ones its sidecar attributes. */
   private clean(entry: ComputerSyncEntryV1): boolean {
     return (
@@ -579,13 +692,21 @@ class WorkspaceRootSync implements WorkspaceRootSyncV1 {
     root: WorkspaceRootV1,
     entry: ComputerSyncEntryV1,
     report: WorkspaceSyncRootReportV1,
+    /**
+     * The generation to condition on, when the caller has read the store and
+     * knows better than the sidecar. Absent means the sidecar decides, which
+     * is the ordinary case.
+     */
+    override?: { expected: string | null },
   ): Promise<"pushed" | "conflict" | "held"> {
     const bytes = await this.options.computer.read(root, entry.path);
     if (isFailure(bytes)) {
       report.failures.push({ ...bytes, root, path: entry.path });
       return "held";
     }
-    const expected = entry.recorded?.generationId ?? null;
+    const expected = override
+      ? override.expected
+      : (entry.recorded?.generationId ?? null);
     const effect: WorkspaceSyncEffectV1 = {
       effectId: workspaceSyncEffectIdV1(
         root,
@@ -814,8 +935,8 @@ class WorkspaceRootSync implements WorkspaceRootSyncV1 {
     root: WorkspaceRootV1,
     entry: ComputerSyncEntryV1,
     report: WorkspaceSyncRootReportV1,
+    tombstone: WorkspaceGenerationV1,
   ): Promise<boolean> {
-    const tombstone = await this.storeTombstone(root, entry);
     const removed = await this.options.computer.remove(
       root,
       entry.path,
@@ -836,15 +957,23 @@ class WorkspaceRootSync implements WorkspaceRootSyncV1 {
    * The tombstone generation to record on the Computer for a store-side
    * delete. The ledger holds the writer when the Durable Object is reachable;
    * otherwise the removal is recorded with no writer, which is the truth.
+   *
+   * `"no-removal-recorded"` is the third answer, and the one that keeps the
+   * removal rule honest: the ledger answered, and it holds no tombstone for
+   * this path. ADR 0013 makes a delete a recorded generation, so an absence
+   * with no record is drift between the sidecar and the store rather than a
+   * delete, and the caller re-pushes instead of destroying the file. An
+   * unreachable ledger says nothing either way, so the removal stands.
    */
   private async storeTombstone(
     root: WorkspaceRootV1,
     entry: ComputerSyncEntryV1,
-  ): Promise<WorkspaceGenerationV1> {
+  ): Promise<WorkspaceGenerationV1 | "no-removal-recorded"> {
     if (this.options.generations) {
       try {
         const record = await this.options.generations.current(root, entry.path);
         if (record?.deleted) return record.generation;
+        return "no-removal-recorded";
       } catch {
         // The ledger is unreachable; record the removal without a writer.
       }