@checkstack/script-packages-backend 0.2.0

package/src/blob-gc-runner.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test";
+import type { ManifestEntry } from "@checkstack/script-packages-common";
+import { createBlobGcTrigger, type BlobGcRunnerDeps } from "./blob-gc-runner";
+import type { InstallerLock } from "./install-state-store";
+import type { BlobStore } from "./blob-store";
+import { createBlobStoreRegistry } from "./blob-store-registry";
+import type { GcBlob } from "./blob-gc";
+
+function entry(integrity: string): ManifestEntry {
+  return { name: integrity, version: "1.0.0", integrity };
+}
+
+function fakeStore(id: string, deletes: string[]): BlobStore {
+  return {
+    id,
+    put: async () => {},
+    get: async () => undefined,
+    has: async () => true,
+    delete: async ({ integrity }) => void deletes.push(`${id}:${integrity}`),
+    list: async () => [],
+  };
+}
+
+function lockThatGrants(calls: string[]): InstallerLock {
+  return {
+    tryInstallerLock: async () => ({
+      release: async () => void calls.push("released"),
+    }),
+  };
+}
+
+const OLD = new Date(Date.now() - 2 * 24 * 60 * 60 * 1000);
+
+function makeDeps(over: Partial<BlobGcRunnerDeps> = {}): {
+  deps: BlobGcRunnerDeps;
+  storeDeletes: string[];
+  lockCalls: string[];
+  pruned: number[];
+  removed: string[];
+} {
+  const storeDeletes: string[] = [];
+  const lockCalls: string[] = [];
+  const pruned: number[] = [];
+  const removed: string[] = [];
+  const registry = createBlobStoreRegistry();
+  registry.register(fakeStore("postgres", storeDeletes));
+  registry.register(fakeStore("s3", storeDeletes));
+
+  const deps: BlobGcRunnerDeps = {
+    installerLock: lockThatGrants(lockCalls),
+    blobStores: registry,
+    loadCurrent: async () => ({ lockfileHash: "CUR", manifest: [entry("a")] }),
+    recentHistory: async () => [[entry("a")]],
+    pruneHistory: async (keep) => void pruned.push(keep),
+    listBlobs: async (): Promise<GcBlob[]> => [
+      { integrity: "a", backend: "postgres", sizeBytes: 10, createdAt: OLD },
+      {
+        integrity: "orphan",
+        backend: "s3",
+        sizeBytes: 99,
+        createdAt: OLD,
+      },
+    ],
+    removeBlobRow: async (i) => void removed.push(i),
+    isBusy: async () => false,
+    recordRun: async () => {},
+    ...over,
+  };
+  return { deps, storeDeletes, lockCalls, pruned, removed };
+}
+
+describe("createBlobGcTrigger", () => {
+  test("deletes orphan bytes via its recorded backend, drops the index row, releases the lock", async () => {
+    const { deps, storeDeletes, lockCalls, removed } = makeDeps();
+    const out = await createBlobGcTrigger(deps)();
+    expect(out.ran).toBe(true);
+    expect(out.deleted).toBe(1);
+    expect(out.bytesReclaimed).toBe(99);
+    // routed to s3 (the orphan's backend), referenced "a" untouched.
+    expect(storeDeletes).toEqual(["s3:orphan"]);
+    expect(removed).toEqual(["orphan"]);
+    expect(lockCalls).toContain("released");
+  });
+
+  test("refuses + releases nothing when the installer lock is held", async () => {
+    const { deps, storeDeletes } = makeDeps({
+      installerLock: { tryInstallerLock: async () => null },
+    });
+    const out = await createBlobGcTrigger(deps)();
+    expect(out.ran).toBe(false);
+    expect(out.reason).toMatch(/installer lock/i);
+    expect(storeDeletes).toHaveLength(0);
+  });
+
+  test("prunes lockfile history to the retained window and releases the lock even on failure", async () => {
+    const { deps, pruned, lockCalls } = makeDeps({
+      listBlobs: async () => {
+        throw new Error("db down");
+      },
+      retainPrevious: 2,
+    });
+    const out = await createBlobGcTrigger(deps)();
+    expect(out.ran).toBe(false);
+    expect(out.reason).toBe("db down");
+    // pruneHistory(keep = retainPrevious + 1) still ran; lock released.
+    expect(pruned).toEqual([3]);
+    expect(lockCalls).toContain("released");
+  });
+
+  test("unions the live install-state manifest into the retained set", async () => {
+    // History is empty, but the current manifest references "a" → keep it.
+    const { deps, storeDeletes } = makeDeps({
+      recentHistory: async () => [],
+      loadCurrent: async () => ({ lockfileHash: "CUR", manifest: [entry("a")] }),
+    });
+    const out = await createBlobGcTrigger(deps)();
+    expect(storeDeletes).toEqual(["s3:orphan"]); // "a" retained via current
+    expect(out.deleted).toBe(1);
+  });
+});

package/src/blob-gc-runner.ts

@@ -0,0 +1,139 @@
+import type {
+  BlobGcSummary,
+  ManifestEntry,
+} from "@checkstack/script-packages-common";
+import {
+  DEFAULT_BLOB_GC_GRACE_MS,
+  DEFAULT_BLOB_GC_RETAIN_PREVIOUS,
+} from "@checkstack/script-packages-common";
+import { extractErrorMessage } from "@checkstack/common";
+import type { InstallerLock } from "./install-state-store";
+import type { BlobStoreRegistry } from "./blob-store-registry";
+import { runBlobGc, type GcBlob } from "./blob-gc";
+
+/**
+ * Build a `triggerBlobGc()` callable that wires the pure {@link runBlobGc}
+ * orchestration to the real stores + blob backends, and is shared by the
+ * admin `gcBlobs` RPC and the scheduled recurring job (so the safety logic
+ * lives in exactly one place).
+ *
+ * Mutual exclusion: the trigger takes the installer-election advisory lock
+ * for the whole pass, so a concurrent install / migration (which contend for
+ * the same lock) cannot run while GC does, and vice versa. If the lock is
+ * held, GC refuses cleanly (the install / migration wins; GC retries on its
+ * next scheduled run). On top of the lock, {@link runBlobGc} re-checks
+ * `isBusy()`.
+ *
+ * Retained set: the current desired manifest PLUS the previous N hashes'
+ * manifests, from lockfile history. History older than the retention window
+ * is pruned after a successful pass.
+ */
+export interface BlobGcRunnerDeps {
+  installerLock: InstallerLock;
+  blobStores: BlobStoreRegistry;
+  /** Current desired manifest + hash (from install state). */
+  loadCurrent(): Promise<{
+    lockfileHash: string | null;
+    manifest: ManifestEntry[];
+  }>;
+  /** Most-recent `limit` manifests from lockfile history (newest first). */
+  recentHistory(limit: number): Promise<ManifestEntry[][]>;
+  /** Prune history rows beyond the most-recent `keep` hashes. */
+  pruneHistory(keep: number): Promise<void>;
+  /** Every indexed blob with size + created_at. */
+  listBlobs(): Promise<GcBlob[]>;
+  /** Remove a blob's index row (after its bytes are deleted). */
+  removeBlobRow(integrity: string): Promise<void>;
+  /** True while an install OR storage migration is in flight. */
+  isBusy(): Promise<boolean>;
+  /** Persist the run summary for the admin UI. */
+  recordRun(input: { deleted: number; bytesReclaimed: number }): Promise<void>;
+  /** Keep current + this many previous hashes (default 1). */
+  retainPrevious?: number;
+  /** Grace window in ms (default 24h). */
+  graceMs?: number;
+  logger?: { debug(msg: string): void; error(msg: string): void };
+}
+
+export function createBlobGcTrigger(
+  deps: BlobGcRunnerDeps,
+): () => Promise<BlobGcSummary> {
+  const retainPrevious = deps.retainPrevious ?? DEFAULT_BLOB_GC_RETAIN_PREVIOUS;
+  const graceMs = deps.graceMs ?? DEFAULT_BLOB_GC_GRACE_MS;
+
+  return async function triggerBlobGc(): Promise<BlobGcSummary> {
+    // Election: hold the installer lock for the whole pass so an install /
+    // migration cannot start concurrently (they contend for the same lock).
+    const lock = await deps.installerLock.tryInstallerLock();
+    if (!lock) {
+      const reason =
+        "An install or storage migration holds the installer lock; skipping blob GC.";
+      deps.logger?.debug(reason);
+      return {
+        ran: false,
+        reason,
+        candidates: 0,
+        deleted: 0,
+        keptWithinGrace: 0,
+        bytesReclaimed: 0,
+      };
+    }
+
+    try {
+      // Retain current + previous N. We pull `retainPrevious + 1` history
+      // rows (the current hash is itself recorded in history on install) and
+      // additionally union the live install-state manifest in case history
+      // hasn't caught up yet — when in doubt, retain.
+      return await runBlobGc({
+        deps: {
+          retainedManifests: async () => {
+            const manifests = await deps.recentHistory(retainPrevious + 1);
+            const current = await deps.loadCurrent();
+            if (current.lockfileHash && current.manifest.length > 0) {
+              manifests.push(current.manifest);
+            }
+            return manifests;
+          },
+          listBlobs: deps.listBlobs,
+          deleteBlob: async ({ integrity, backend }) => {
+            // Route the byte-delete to the blob's recorded backend, then drop
+            // the index row. If the backend isn't registered (shouldn't
+            // happen), skip the byte-delete but still drop the row so a
+            // dangling reference doesn't linger.
+            if (deps.blobStores.has(backend)) {
+              await deps.blobStores.get(backend).delete({ integrity });
+            } else {
+              deps.logger?.error(
+                `Blob GC: backend "${backend}" for ${integrity} not registered; dropping index row only.`,
+              );
+            }
+            await deps.removeBlobRow(integrity);
+          },
+          isBusy: deps.isBusy,
+          recordRun: deps.recordRun,
+          graceMs,
+          logger: deps.logger,
+        },
+      });
+    } catch (error) {
+      const message = extractErrorMessage(error);
+      deps.logger?.error(`Blob GC pass failed: ${message}`);
+      return {
+        ran: false,
+        reason: message,
+        candidates: 0,
+        deleted: 0,
+        keptWithinGrace: 0,
+        bytesReclaimed: 0,
+      };
+    } finally {
+      // Prune history beyond the retained window (best-effort), then release.
+      await deps.pruneHistory(retainPrevious + 1).catch((error) => {
+        deps.logger?.error(
+          `Blob GC: pruning lockfile history failed: ${extractErrorMessage(error)}`,
+        );
+      });
+      await lock.release();
+    }
+  };
+}

package/src/blob-gc.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, test } from "bun:test";
+import type { ManifestEntry } from "@checkstack/script-packages-common";
+import { runBlobGc, type BlobGcDeps, type GcBlob } from "./blob-gc";
+
+const NOW = 1_700_000_000_000;
+const HOUR = 60 * 60 * 1000;
+const DAY = 24 * HOUR;
+
+function entry(name: string, integrity: string): ManifestEntry {
+  return { name, version: "1.0.0", integrity };
+}
+
+function blob(over: Partial<GcBlob> & { integrity: string }): GcBlob {
+  return {
+    backend: "postgres",
+    sizeBytes: 100,
+    createdAt: new Date(NOW - 2 * DAY), // past-grace by default
+    ...over,
+  };
+}
+
+function makeDeps(
+  over: Partial<BlobGcDeps> = {},
+): {
+  deps: BlobGcDeps;
+  deletes: { integrity: string; backend: string }[];
+  recorded: { deleted: number; bytesReclaimed: number }[];
+} {
+  const deletes: { integrity: string; backend: string }[] = [];
+  const recorded: { deleted: number; bytesReclaimed: number }[] = [];
+  const deps: BlobGcDeps = {
+    retainedManifests: async () => [[entry("a", "sha-a")]],
+    listBlobs: async () => [blob({ integrity: "sha-a" })],
+    deleteBlob: async (input) => void deletes.push(input),
+    isBusy: async () => false,
+    recordRun: async (r) => void recorded.push(r),
+    now: () => NOW,
+    ...over,
+  };
+  return { deps, deletes, recorded };
+}
+
+describe("runBlobGc", () => {
+  test("never deletes a blob referenced by a retained manifest", async () => {
+    const { deps, deletes } = makeDeps({
+      retainedManifests: async () => [[entry("a", "sha-a")]],
+      listBlobs: async () => [
+        blob({ integrity: "sha-a" }),
+        blob({ integrity: "sha-orphan" }),
+      ],
+    });
+    const out = await runBlobGc({ deps });
+    expect(out.ran).toBe(true);
+    // Only the orphan is a candidate; the referenced blob is untouched.
+    expect(deletes.map((d) => d.integrity)).toEqual(["sha-orphan"]);
+    expect(out.candidates).toBe(1);
+    expect(out.deleted).toBe(1);
+  });
+
+  test("retains blobs referenced by ANY retained manifest (current + previous)", async () => {
+    const { deps, deletes } = makeDeps({
+      // current references sha-a, previous references sha-b.
+      retainedManifests: async () => [
+        [entry("a", "sha-a")],
+        [entry("b", "sha-b")],
+      ],
+      listBlobs: async () => [
+        blob({ integrity: "sha-a" }),
+        blob({ integrity: "sha-b" }),
+        blob({ integrity: "sha-old" }),
+      ],
+    });
+    const out = await runBlobGc({ deps });
+    expect(deletes.map((d) => d.integrity)).toEqual(["sha-old"]);
+    expect(out.deleted).toBe(1);
+  });
+
+  test("deletes unreferenced blobs past the grace window", async () => {
+    const { deps, deletes } = makeDeps({
+      retainedManifests: async () => [[entry("a", "sha-a")]],
+      listBlobs: async () => [
+        blob({ integrity: "sha-old", createdAt: new Date(NOW - 2 * DAY) }),
+      ],
+      graceMs: DAY,
+    });
+    const out = await runBlobGc({ deps });
+    expect(deletes.map((d) => d.integrity)).toEqual(["sha-old"]);
+    expect(out.deleted).toBe(1);
+    expect(out.keptWithinGrace).toBe(0);
+  });
+
+  test("keeps unreferenced blobs still within the grace window", async () => {
+    const { deps, deletes } = makeDeps({
+      retainedManifests: async () => [[entry("a", "sha-a")]],
+      listBlobs: async () => [
+        blob({ integrity: "sha-fresh", createdAt: new Date(NOW - HOUR) }),
+      ],
+      graceMs: DAY,
+    });
+    const out = await runBlobGc({ deps });
+    expect(deletes).toHaveLength(0);
+    expect(out.candidates).toBe(1);
+    expect(out.deleted).toBe(0);
+    expect(out.keptWithinGrace).toBe(1);
+  });
+
+  test("refuses to run while an install / migration is in flight", async () => {
+    const { deps, deletes } = makeDeps({
+      isBusy: async () => true,
+      listBlobs: async () => [blob({ integrity: "sha-old" })],
+    });
+    const out = await runBlobGc({ deps });
+    expect(out.ran).toBe(false);
+    expect(out.reason).toMatch(/install|migration/i);
+    expect(deletes).toHaveLength(0);
+  });
+
+  test("routes each delete to the blob's recorded backend", async () => {
+    const { deps, deletes } = makeDeps({
+      retainedManifests: async () => [[]],
+      listBlobs: async () => [
+        blob({ integrity: "sha-pg", backend: "postgres" }),
+        blob({ integrity: "sha-s3", backend: "s3" }),
+      ],
+    });
+    await runBlobGc({ deps });
+    expect(deletes).toEqual([
+      { integrity: "sha-pg", backend: "postgres" },
+      { integrity: "sha-s3", backend: "s3" },
+    ]);
+  });
+
+  test("accounts for reclaimed bytes", async () => {
+    const { deps, recorded } = makeDeps({
+      retainedManifests: async () => [[]],
+      listBlobs: async () => [
+        blob({ integrity: "x", sizeBytes: 500 }),
+        blob({ integrity: "y", sizeBytes: 250 }),
+      ],
+    });
+    const out = await runBlobGc({ deps });
+    expect(out.bytesReclaimed).toBe(750);
+    expect(recorded).toEqual([{ deleted: 2, bytesReclaimed: 750 }]);
+  });
+
+  test("is idempotent: a re-run after deletion reclaims nothing", async () => {
+    let store = [blob({ integrity: "x" }), blob({ integrity: "orphan" })];
+    const deps: BlobGcDeps = {
+      retainedManifests: async () => [[entry("x", "x")]],
+      listBlobs: async () => store,
+      deleteBlob: async ({ integrity }) => {
+        store = store.filter((b) => b.integrity !== integrity);
+      },
+      isBusy: async () => false,
+      now: () => NOW,
+    };
+    const first = await runBlobGc({ deps });
+    expect(first.deleted).toBe(1);
+    const second = await runBlobGc({ deps });
+    expect(second.deleted).toBe(0);
+    expect(second.candidates).toBe(0);
+  });
+
+  test("a failed single delete is logged and skipped, not fatal", async () => {
+    const errors: string[] = [];
+    const { deps } = makeDeps({
+      retainedManifests: async () => [[]],
+      listBlobs: async () => [
+        blob({ integrity: "bad" }),
+        blob({ integrity: "good" }),
+      ],
+      deleteBlob: async ({ integrity }) => {
+        if (integrity === "bad") throw new Error("backend offline");
+      },
+      logger: { debug: () => {}, error: (m) => void errors.push(m) },
+    });
+    const out = await runBlobGc({ deps });
+    // "good" still deleted; "bad" retained for next pass.
+    expect(out.deleted).toBe(1);
+    expect(errors.some((e) => /bad/.test(e))).toBe(true);
+  });
+});

package/src/blob-gc.ts

@@ -0,0 +1,161 @@
+import type {
+  BlobGcSummary,
+  ManifestEntry,
+} from "@checkstack/script-packages-common";
+import { DEFAULT_BLOB_GC_GRACE_MS } from "@checkstack/script-packages-common";
+import { extractErrorMessage } from "@checkstack/common";
+
+/**
+ * Blob garbage collection: prune content-addressed blobs no longer referenced
+ * by any RETAINED lockfile manifest (the current desired hash + the previous
+ * N), older than a grace window.
+ *
+ * GC is destructive, so every deletion is provably safe:
+ *  - **Retained set:** the union of blob integrities across the retained
+ *    manifests (current + previous N). Any blob NOT in that union is a
+ *    candidate. When in doubt we retain.
+ *  - **Grace window:** a candidate is only deleted when it is older than the
+ *    grace window (keyed on `script_package_blob.created_at`), so a pod /
+ *    satellite mid-reconcile toward a just-superseded hash can still pull a
+ *    blob that was just dropped from the retained set.
+ *  - **Mutual exclusion:** the caller holds the installer-election advisory
+ *    lock while GC runs AND we re-check `isBusy()` (install OR migration in
+ *    flight) before deleting, so GC can never race a concurrent install that
+ *    is publishing blobs for a new hash.
+ *  - **Per-backend routing:** each blob is deleted from the backend recorded
+ *    in its index row, then the index row is removed.
+ *
+ * All collaborators are injected so the orchestration is unit-testable
+ * without a DB or a real blob store.
+ */
+
+/** One indexed blob, as the GC needs to see it. */
+export interface GcBlob {
+  integrity: string;
+  backend: string;
+  sizeBytes: number;
+  createdAt: Date;
+}
+
+export interface BlobGcDeps {
+  /**
+   * The retained manifests: the current desired manifest plus the previous N
+   * (most-recent-first or any order; only the union of integrities matters).
+   */
+  retainedManifests(): Promise<ManifestEntry[][]>;
+  /** Every indexed blob (integrity + backend + size + created_at). */
+  listBlobs(): Promise<GcBlob[]>;
+  /** Delete a blob's bytes from `backend`, then its index row. Idempotent. */
+  deleteBlob(input: { integrity: string; backend: string }): Promise<void>;
+  /**
+   * True while an install OR a storage migration is in flight. Re-checked
+   * AFTER the lock is held (an install on this very pod could be mid-publish
+   * without holding the installer lock for the whole window).
+   */
+  isBusy(): Promise<boolean>;
+  /** Record the run summary (for the admin UI). Best-effort. */
+  recordRun?(input: {
+    deleted: number;
+    bytesReclaimed: number;
+  }): Promise<void>;
+  /** Now, injectable for deterministic grace tests. */
+  now?(): number;
+  /** Grace window in ms (default 24h). */
+  graceMs?: number;
+  logger?: { debug(msg: string): void; error(msg: string): void };
+}
+
+/**
+ * Run one blob-GC pass. The caller MUST already hold the installer-election
+ * advisory lock (so an install/migration cannot start mid-pass); this
+ * function additionally refuses if `isBusy()` reports an active install /
+ * migration, as a belt-and-braces guard.
+ *
+ * Idempotent: a second run with the same inputs finds the just-deleted blobs
+ * gone and reports zero further deletions.
+ */
+export async function runBlobGc({
+  deps,
+}: {
+  deps: BlobGcDeps;
+}): Promise<BlobGcSummary> {
+  const graceMs = deps.graceMs ?? DEFAULT_BLOB_GC_GRACE_MS;
+  const now = deps.now?.() ?? Date.now();
+
+  if (await deps.isBusy()) {
+    const reason =
+      "An install or storage migration is in flight; skipping blob GC.";
+    deps.logger?.debug(reason);
+    return {
+      ran: false,
+      reason,
+      candidates: 0,
+      deleted: 0,
+      keptWithinGrace: 0,
+      bytesReclaimed: 0,
+    };
+  }
+
+  // Retained set = union of integrities across every retained manifest.
+  const retained = new Set<string>();
+  for (const manifest of await deps.retainedManifests()) {
+    for (const entry of manifest) retained.add(entry.integrity);
+  }
+
+  const blobs = await deps.listBlobs();
+  const candidates = blobs.filter((b) => !retained.has(b.integrity));
+
+  let deleted = 0;
+  let keptWithinGrace = 0;
+  let bytesReclaimed = 0;
+
+  for (const blob of candidates) {
+    const ageMs = now - blob.createdAt.getTime();
+    if (ageMs < graceMs) {
+      keptWithinGrace++;
+      deps.logger?.debug(
+        `Blob GC: keeping unreferenced ${blob.integrity} (age ${Math.round(
+          ageMs / 1000,
+        )}s < grace ${Math.round(graceMs / 1000)}s).`,
+      );
+      continue;
+    }
+    try {
+      await deps.deleteBlob({
+        integrity: blob.integrity,
+        backend: blob.backend,
+      });
+      deleted++;
+      bytesReclaimed += blob.sizeBytes;
+      deps.logger?.debug(
+        `Blob GC: deleted ${blob.integrity} from "${blob.backend}" ` +
+          `(${blob.sizeBytes} bytes).`,
+      );
+    } catch (error) {
+      // A single failed delete must not abort the whole pass; the blob is
+      // simply retained until the next run. Never silently swallow: log it.
+      deps.logger?.error(
+        `Blob GC: failed to delete ${blob.integrity} from "${blob.backend}": ${extractErrorMessage(
+          error,
+        )}. Retaining for the next pass.`,
+      );
+    }
+  }
+
+  await deps.recordRun?.({ deleted, bytesReclaimed }).catch(() => {
+    // Recording the summary is best-effort UI state; never fail the pass.
+  });
+
+  deps.logger?.debug(
+    `Blob GC complete: ${candidates.length} candidate(s), ${deleted} deleted ` +
+      `(${bytesReclaimed} bytes), ${keptWithinGrace} kept within grace.`,
+  );
+
+  return {
+    ran: true,
+    candidates: candidates.length,
+    deleted,
+    keptWithinGrace,
+    bytesReclaimed,
+  };
+}

package/src/blob-hash.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import { blobSha256, toUint8Array, verifyBlobSha256 } from "./blob-hash";
+
+const bytes = new TextEncoder().encode("the real blob");
+const hash = blobSha256(bytes);
+
+describe("blobSha256 byte-type boundary", () => {
+  // Regression: a real-package install reads blob bytes from a store backend
+  // whose `get` can yield a raw ArrayBuffer (e.g. an S3/HTTP transport).
+  // `crypto.Hash.update()` rejects a bare ArrayBuffer
+  // ("Received an instance of ArrayBuffer"), failing the install with
+  // status=error. The hash boundary must normalize ArrayBuffer -> Uint8Array.
+  test("hashes a raw ArrayBuffer without throwing", () => {
+    const u8 = new TextEncoder().encode("blob-from-an-arraybuffer-source");
+    // A standalone ArrayBuffer holding exactly these bytes.
+    const ab = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength);
+    expect(ab).toBeInstanceOf(ArrayBuffer);
+    // Must not throw, and must equal the Uint8Array digest over the same bytes.
+    expect(blobSha256(ab)).toBe(blobSha256(u8));
+  });
+
+  test("a Uint8Array view hashes identically to its ArrayBuffer", () => {
+    const u8 = new Uint8Array([0, 1, 2, 250, 255, 128, 64]);
+    const ab = u8.buffer.slice(0);
+    expect(blobSha256(ab)).toBe(blobSha256(u8));
+  });
+
+  test("verifyBlobSha256 accepts an ArrayBuffer", () => {
+    const u8 = new TextEncoder().encode("verify me");
+    const ab = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength);
+    const verdict = verifyBlobSha256({
+      entry: { blobSha256: blobSha256(u8) },
+      bytes: ab,
+    });
+    expect(verdict.ok).toBe(true);
+  });
+
+  test("toUint8Array returns the same instance for a Uint8Array", () => {
+    const u8 = new Uint8Array([1, 2, 3]);
+    expect(toUint8Array(u8)).toBe(u8);
+  });
+});
+
+describe("verifyBlobSha256", () => {
+  test("ok when the hash matches", () => {
+    const verdict = verifyBlobSha256({ entry: { blobSha256: hash }, bytes });
+    expect(verdict.ok).toBe(true);
+  });
+
+  test("rejects tampered bytes with expected + actual hashes", () => {
+    const tampered = new TextEncoder().encode("the EVIL blob");
+    const verdict = verifyBlobSha256({
+      entry: { blobSha256: hash },
+      bytes: tampered,
+    });
+    expect(verdict.ok).toBe(false);
+    if (!verdict.ok) {
+      expect(verdict.expected).toBe(hash);
+      expect(verdict.actual).toBe(blobSha256(tampered));
+      expect(verdict.actual).not.toBe(verdict.expected);
+    }
+  });
+
+  test("backward-safe: no recorded hash skips verification", () => {
+    // Entries published before blobSha256 must still seed (until re-install
+    // regenerates the manifest). Any bytes pass.
+    const verdict = verifyBlobSha256({ entry: {}, bytes });
+    expect(verdict.ok).toBe(true);
+  });
+});