mlx-bun 0.3.0 → 0.4.0

package/src/kv-store.ts

@@ -1,3 +1,4 @@
+import { type CheckpointAttachment, attachmentBytes, disposeAttachments } from "./backends/mlx/checkpoint-state";
 import { cleanupFailure, disposeResources } from "./engine/resources";
 // KV-cache persistence: save prompt caches to disk, reload by streamed copy.
 // The serialization core of the SSD cold tier (docs/design/kv-cache.md).
@@ -86,6 +87,7 @@ interface TensorSlot {
 export interface CacheHeaderEntry {
   kind: CacheKind;
   offset: number;
+  minimumReusableOffset?: number;
   /** rotating variants: ring write index */
   idx?: number;
   /** rotating variants: window size */
@@ -114,6 +116,7 @@ export interface CacheHeaderEntry {
 }
 
 export interface KvSaveMeta {
+  attachments?: CheckpointAttachment[];
   modelId?: string;
   /** configFingerprint(config) — covers every graph-shaping field incl.
    *  the kv-quant scheme, so a scheme flip invalidates naturally. */
@@ -139,10 +142,11 @@ export interface KvSaveMeta {
   };
 }
 
-export interface KvFileHeader extends KvSaveMeta {
+export interface KvFileHeader extends Omit<KvSaveMeta, "attachments"> {
+  attachments?: Array<Omit<CheckpointAttachment, "tensors"> & { tensors: TensorSlot[] }>;
   /** Absent in earlier v3 files, which used mlx-cache-v3. */
   codecProvider?: string;
-  formatVersion: 3;
+  formatVersion: 3 | 4;
   createdAt: number;
   tokens: number[];
   caches: CacheHeaderEntry[];
@@ -273,8 +277,8 @@ const CACHE_CODECS = {
     },
     clone: (cache, context) => {
       const c = cache as KVCache;
-      if (!c.keys || !c.values) throw new Error("cannot clone an empty cache");
       const clone = new KVCache();
+      if (!c.keys || !c.values) return clone;
       clone.restoreState(
         context.liveView(c.keys, c.offset),
         context.liveView(c.values, c.offset),
@@ -305,8 +309,8 @@ const CACHE_CODECS = {
     },
     clone: (cache, context) => {
       const c = cache as RotatingKVCache;
-      if (!c.keys || !c.values) throw new Error("cannot clone an empty cache");
       const clone = new RotatingKVCache(c.maxSize);
+      if (!c.keys || !c.values) return clone;
       clone.restoreState(context.view(c.keys), context.view(c.values), c.offset, c.ringIdx);
       return clone;
     },
@@ -332,8 +336,8 @@ const CACHE_CODECS = {
     },
     clone: (cache, context) => {
       const c = cache as QuantizedKVCache;
-      if (!c.keys || !c.values) throw new Error("cannot clone an empty cache");
       const clone = new QuantizedKVCache(c.groupSize, c.bits);
+      if (!c.keys || !c.values) return clone;
       clone.restoreState(
         context.tripleView(c.keys, c.offset),
         context.tripleView(c.values, c.offset),
@@ -363,8 +367,8 @@ const CACHE_CODECS = {
     },
     clone: (cache, context) => {
       const c = cache as RotatingQuantizedKVCache;
-      if (!c.keys || !c.values) throw new Error("cannot clone an empty cache");
       const clone = new RotatingQuantizedKVCache(c.maxSize, c.groupSize, c.bits);
+      if (!c.keys || !c.values) return clone;
       clone.restoreState(
         context.tripleView(c.keys, null), context.tripleView(c.values, null),
         c.offset, c.ringIdx,
@@ -515,6 +519,17 @@ export function createCacheCodecProvider(
 
 export const legacyCacheCodecs = createCacheCodecProvider("mlx-cache-v3", CACHE_CODECS);
 
+/** Old TQ files lack the conversion boundary. Keep them reusable at their
+ * stored offset, but never infer that an earlier precision state is valid. */
+export function cacheHeaderMinimumReusableOffset(entry: CacheHeaderEntry): number {
+  const offset = entry.minimumReusableOffset ?? (entry.kind === "turboquant" ? entry.offset : 0);
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > entry.offset)
+    throw new Error("invalid cache minimum reusable offset");
+  return offset;
+}
+export const cacheHeadersMinimumReusableOffset = (caches: readonly CacheHeaderEntry[]): number =>
+  Math.max(0, ...caches.map(cacheHeaderMinimumReusableOffset));
+
 export const cacheHeadersTrimmable = (
   caches: readonly CacheHeaderEntry[], codecs: CacheCodecProvider = legacyCacheCodecs,
 ): boolean => caches.every((entry) => codecs.forHeader(entry).headerTrimmable(entry));
@@ -547,6 +562,7 @@ function snapshotCache(c: Cache, dataOffset: number, codecs: CacheCodecProvider)
 
   try {
     const entry = codecs.forCache(c).snapshot(c, { slots, push, liveSlice, liveMlaSlice, pushTriple });
+    if (c.minimumReusableOffset !== undefined) entry.minimumReusableOffset = c.minimumReusableOffset;
     return { entry, sources, next: cursor };
   } catch (error) {
     for (const source of sources) if (source.disposeAfter) source.arr.dispose();
@@ -588,7 +604,9 @@ export function cloneKvCaches(caches: Cache[], codecs: CacheCodecProvider = lega
   const out: Cache[] = [];
   try {
     for (const c of caches) {
-      out.push(codecs.forCache(c).clone(c, { view, liveView, mlaView, tripleView }));
+      const clone = codecs.forCache(c).clone(c, { view, liveView, mlaView, tripleView });
+      if (c.minimumReusableOffset !== undefined) clone.minimumReusableOffset = c.minimumReusableOffset;
+      out.push(clone);
       pending.length = 0; // transferred to the returned cache
     }
   } catch (err) {
@@ -615,10 +633,24 @@ function* saveKvCacheSteps(path: string, tokens: number[], caches: Cache[], meta
       dataOffset = s.next;
     }
 
+    const { attachments: liveAttachments, ...identity } = meta;
+    const attachments = liveAttachments?.map((attachment) => ({
+      schema: attachment.schema,
+      metadata: { ...attachment.metadata },
+      tensors: attachment.tensors.map((arr) => {
+        const slot: TensorSlot = { off: dataOffset, bytes: arr.nbytes,
+          shape: [...arr.shape], dtype: arr.dtype, hash: "0000000000000000" };
+        dataOffset = alignUp(dataOffset + slot.bytes);
+        sources.push({ arr, disposeAfter: false });
+        return slot;
+      }),
+    }));
+
     // Header size is final NOW: hashes are fixed-width placeholders that get
     // patched in place (same byte length) after the data pass computes them.
     const header: KvFileHeader = {
-      formatVersion: 3, createdAt: Date.now(), ...meta, codecProvider: codecs.id, tokens, caches: entries,
+      formatVersion: attachments?.length ? 4 : 3, createdAt: Date.now(), ...identity,
+      ...(attachments?.length ? { attachments } : {}), codecProvider: codecs.id, tokens, caches: entries,
     };
     const headerLen = new TextEncoder().encode(JSON.stringify(header)).length;
     const dataStart = alignUp(PREFIX_LEN + headerLen);
@@ -639,7 +671,7 @@ function* saveKvCacheSteps(path: string, tokens: number[], caches: Cache[], meta
       // pages, which makes them VISIBLE to ps RSS — accounting, not an
       // allocation (see bench-serve.ts' per-leg RSS note).
       let srcIdx = 0;
-      for (const e of entries) {
+      for (const e of [...entries, ...(attachments ?? [])]) {
         for (const slot of e.tensors) {
           const src = sources[srcIdx++]!;
           const c = ops.contiguous(src.arr);
@@ -717,6 +749,7 @@ export async function saveKvCacheAsync(
 /** One pending write-behind item: an entry's copied tokens + OWNED
  *  zero-copy cache clones (the queue disposes them on every exit path). */
 export interface SpillItem {
+  attachments?: CheckpointAttachment[];
   tokens: number[];
   caches: Cache[];
   ns: string;
@@ -761,6 +794,8 @@ export class SpillQueue {
     readonly store: (item: SpillItem) => Promise<unknown>,
     /** Clone disposal — frees the pinned GPU memory. */
     readonly disposeClones: (caches: Cache[]) => void,
+    /** Zero-byte control barriers may need to survive capacity shedding. */
+    readonly canDrop: (item: SpillItem) => boolean = () => true,
   ) {}
 
   /** Bytes pinned by queued (not yet flushed) clones. */
@@ -776,7 +811,7 @@ export class SpillQueue {
     const result = new Promise<boolean>((resolve) => { settle = resolve; });
     const rec: SpillRec = {
       ...item,
-      bytes: this.bytesOf(item.caches),
+      bytes: this.bytesOf(item.caches) + attachmentBytes(item.attachments),
       dropped: false,
       settle,
     };
@@ -784,7 +819,7 @@ export class SpillQueue {
     this.#bytes += rec.bytes;
     while (this.#bytes > this.capBytes) {
       const victim = this.#queue.find(
-        (p) => !p.dropped && p !== this.#inFlight && p !== rec,
+        (p) => !p.dropped && p !== this.#inFlight && p !== rec && this.canDrop(p),
       );
       if (!victim) break; // only the new item (or in-flight) left — soft cap
       this.#drop(victim);
@@ -803,12 +838,19 @@ export class SpillQueue {
       } finally {
         this.#inFlight = null;
         this.#remove(rec);
-        this.disposeClones(rec.caches);
+        disposeResources([{ dispose: () => this.disposeClones(rec.caches) },
+          { dispose: () => disposeAttachments(rec.attachments) }]);
       }
     });
     return result;
   }
 
+  /** Cancel queued ownership, excluding the write already in flight. */
+  cancelWhere(matches: (item: SpillItem) => boolean): void {
+    for (const rec of [...this.#queue])
+      if (!rec.dropped && rec !== this.#inFlight && matches(rec)) this.#drop(rec);
+  }
+
   /** Settles when everything enqueued so far has flushed or dropped
    *  (tests and graceful shutdown). */
   drain(): Promise<void> { return this.#chain; }
@@ -818,7 +860,8 @@ export class SpillQueue {
     this.#dropped++;
     rec.settle(false);
     this.#remove(rec);
-    this.disposeClones(rec.caches);
+    disposeResources([{ dispose: () => this.disposeClones(rec.caches) },
+          { dispose: () => disposeAttachments(rec.attachments) }]);
   }
 
   #remove(rec: SpillRec): void {
@@ -848,7 +891,7 @@ export function readKvHeader(path: string): KvFileHeader & { dataStart: number }
     if (BigInt(Bun.hash(body)) !== expectHash)
       throw new Error(`${path}: header hash mismatch (truncated or corrupt)`);
     const header = JSON.parse(new TextDecoder().decode(body)) as KvFileHeader;
-    if (header.formatVersion !== 3)
+    if (header.formatVersion !== 3 && header.formatVersion !== 4)
       throw new Error(`${path}: unsupported formatVersion ${header.formatVersion}`);
     return { ...header, dataStart };
   } finally {
@@ -857,6 +900,7 @@ export function readKvHeader(path: string): KvFileHeader & { dataStart: number }
 }
 
 export interface LoadedKvCache {
+  attachments?: CheckpointAttachment[];
   tokens: number[];
   header: KvFileHeader;
   caches: Cache[];
@@ -1026,20 +1070,30 @@ export function loadKvCache(
     ({ packed: arr(slots[at]!), scales: arr(slots[at + 1]!), biases: arr(slots[at + 2]!) });
 
   const caches: Cache[] = [];
+  const attachments: CheckpointAttachment[] = [];
   try {
     for (const e of header.caches) {
       const codec = codecs.forHeader(e);
-      caches.push(codec.load(e, { path, arr, grownArr, triple }));
+      const minimumOffset = cacheHeaderMinimumReusableOffset(e);
+      const cache = codec.load(e, { path, arr, grownArr, triple });
+      cache.minimumReusableOffset = minimumOffset;
+      caches.push(cache);
       // This entry's tensors are now owned by its cache — stop tracking them
       // (the catch must not double-free through both pending AND caches).
       pending.length = 0;
     }
+    for (const attachment of header.attachments ?? []) {
+      attachments.push({ schema: attachment.schema, metadata: { ...attachment.metadata },
+        tensors: attachment.tensors.map(arr) });
+      pending.length = 0;
+    }
   } catch (err) {
+    disposeAttachments(attachments);
     for (const a of pending) a.dispose(); // the mid-entry orphans
     for (const c of caches) c.dispose();
     throw err;
   } finally {
     mmap.unmap(); // every tensor was copied out — nothing aliases the file
   }
-  return { tokens: header.tokens, header, caches };
+  return { tokens: header.tokens, header, caches, ...(attachments.length ? { attachments } : {}) };
 }

package/src/lab/paged-kv/paged-kv-rows.ts

@@ -0,0 +1,83 @@
+import type { BatchableCache, Cache, Mask } from "../../model/gemma4-base";
+import { buildBatchedDecodeMask, mergeKVRows } from "../../model/batched-mask";
+import { MlxArray } from "../../mlx/array";
+import { disposeResources } from "../../engine/resources";
+import { PagedKVCache, poolBlocksFor } from "./paged-kv";
+
+/** Block storage owns row membership; attention consumes the same gathered
+ * K/V representation as the existing paged cache. No scheduler policy here. */
+export class PagedKvRows implements BatchableCache {
+  #rows: PagedKVCache[] = [];
+  #rope?: MlxArray;
+  #ropeOffset = -1;
+
+  constructor(readonly capacityTokens: number, readonly blockSize: number) {}
+  signature(): string { return "kv:paged-rows"; }
+  get batchSize(): number { return this.#rows.length; }
+  get offset(): number { return Math.max(0, ...this.#rows.map(row => row.offset)); }
+  get rowOffsets(): number[] { return this.#rows.map(row => row.offset); }
+  get leftPad(): number[] { const width = this.offset; return this.#rows.map(row => width - row.offset); }
+  get ropeOffsetArr(): MlxArray | undefined {
+    if (this.#rows.length < 2) return undefined;
+    if (!this.#rope || this.#ropeOffset !== this.offset) {
+      this.releaseRopeArr();
+      this.#rope = MlxArray.fromInt32(Int32Array.from(this.rowOffsets), [this.batchSize]);
+      this.#ropeOffset = this.offset;
+    }
+    return this.#rope;
+  }
+  releaseRopeArr(): void { this.#rope?.dispose(); this.#rope = undefined; this.#ropeOffset = -1; }
+  makeEmptyBatch(): PagedKvRows { return new PagedKvRows(this.capacityTokens, this.blockSize); }
+
+  mergeRows(rows: readonly Cache[]): void {
+    const next: PagedKVCache[] = [];
+    try {
+      for (const source of rows) {
+        if (source instanceof PagedKvRows) {
+          for (const row of source.#rows) next.push(row.clone());
+        } else if (source instanceof PagedKVCache) next.push(source.clone());
+        else throw new Error(`Paged rows cannot merge ${source.signature()}`);
+      }
+    } catch (error) { disposeResources(next); throw error; }
+    const previous = this.#rows; this.#rows = next;
+    this.releaseRopeArr(); disposeResources(previous);
+  }
+  extractRow(row: number): PagedKVCache { return this.#rows[row]!.clone(); }
+  filterRows(keep: readonly number[]): void {
+    const previous = this.#rows;
+    this.#rows = keep.map(row => previous[row]!);
+    const retained = new Set(keep);
+    this.releaseRopeArr();
+    disposeResources(previous.filter((_, row) => !retained.has(row)));
+  }
+
+  updateAndFetch(keys: MlxArray, values: MlxArray): [MlxArray, MlxArray] {
+    if (this.#rows.length === 1) return this.#rows[0]!.updateAndFetch(keys, values);
+    const fetched: Array<{ keys: MlxArray; values: MlxArray }> = [];
+    try {
+      for (const [row, storage] of this.#rows.entries()) {
+        using k = keys.slice([row, 0, 0, 0], [row + 1, ...keys.shape.slice(1)]);
+        using v = values.slice([row, 0, 0, 0], [row + 1, ...values.shape.slice(1)]);
+        const [nextK, nextV] = storage.updateAndFetch(k, v);
+        fetched.push({ keys: nextK, values: nextV });
+      }
+      const result = mergeKVRows(fetched);
+      return [result.keys, result.values];
+    } finally { disposeResources(fetched.flatMap(row => [row.keys, row.values])); }
+  }
+  makeMask(tokens: number, window: number | null): Mask {
+    if (this.#rows.length === 1) return this.#rows[0]!.makeMask(tokens, window);
+    return { mode: "array", arr: buildBatchedDecodeMask(this.batchSize, tokens,
+      this.offset + tokens, this.leftPad, window) };
+  }
+  state(): MlxArray[] { return this.#rows.flatMap(row => row.state()); }
+  isTrimmable(): boolean { return true; }
+  trim(tokens: number): void { for (const row of this.#rows) row.trim(tokens); this.releaseRopeArr(); }
+  projectedBytes(tokens: number): number {
+    const pool = this.#rows.find(row => row.pool)?.pool;
+    if (!pool) return 0;
+    const bytesPerBlock = (pool.keys.nbytes + pool.values.nbytes) / pool.numBlocks;
+    return poolBlocksFor(tokens, this.blockSize) * bytesPerBlock;
+  }
+  dispose(): void { const rows = this.#rows; this.#rows = []; this.releaseRopeArr(); disposeResources(rows); }
+}

package/src/lab/paged-kv/paged-kv.ts

@@ -1,7 +1,7 @@
 // Paged KV cache — vLLM-style block-pool storage behind the standard Cache
 // interface (docs/design/kv-cache.md). OPTIONAL and default-off
-// (`--paged-kv` / GenerateOptions.pagedKv); v1 scope is serial batch=1
-// decode on Gemma4-family plain full-attention layers, bf16 only.
+// (`--paged-kv` / GenerateOptions.pagedKv); Gemma4-family plain full-attention
+// layers, bf16 only. PagedKvRows composes independent pools at B1/B>1.
 //
 // Storage: K/V live in fixed-size per-layer pool tensors
 // [numBlocks, H_kv, blockSize, headDim]; a host-side block table maps the
@@ -17,9 +17,8 @@
 // Motivation, which says this honestly).
 //
 // Deliberately NOT a KVCache subclass (the TurboQuantKVCache reasoning):
-// every instanceof gate in the tree — CompiledDecode.supports, the batch
-// gateway's #modelCachesBatchable, generated forwards' #matches() — must
-// EXCLUDE paged caches and fall back to the monolith/uncompiled path.
+// compiled graph adapters exclude the changing block-list geometry. The
+// cache-layout binding supplies dynamic rows independently of scheduling.
 
 import { MlxArray } from "../../mlx/array";
 import { Dtype } from "../../mlx/ffi";
@@ -58,16 +57,24 @@ export class BlockPool {
      *  reach v1's gemma4 scope, but the pool stays shape-honest). */
     vHeadDim?: number;
     dtype: Dtype;
-  }) {
+  }, source?: BlockPool) {
     this.numBlocks = opts.numBlocks;
     this.blockSize = opts.blockSize;
-    this.keys = ops.zeros(
+    this.keys = source ? ops.contiguous(source.keys) : ops.zeros(
       [opts.numBlocks, opts.numKvHeads, opts.blockSize, opts.headDim], opts.dtype);
-    this.values = ops.zeros(
+    this.values = source ? ops.contiguous(source.values) : ops.zeros(
       [opts.numBlocks, opts.numKvHeads, opts.blockSize, opts.vHeadDim ?? opts.headDim],
       opts.dtype);
     // LIFO free list, low indices first — deterministic layout for tests.
-    this.#free = Array.from({ length: opts.numBlocks }, (_, i) => opts.numBlocks - 1 - i);
+    this.#free = source ? [...source.#free] : Array.from({ length: opts.numBlocks }, (_, i) => opts.numBlocks - 1 - i);
+  }
+
+  /** Independent ownership and allocation metadata over immutable MLX buffers.
+   * Functional writes detach storage while another snapshot retains it. */
+  clone(): BlockPool {
+    return new BlockPool({ numBlocks: this.numBlocks, blockSize: this.blockSize,
+      numKvHeads: this.keys.shape[1]!, headDim: this.keys.shape[3]!,
+      vHeadDim: this.values.shape[3]!, dtype: this.keys.dtype }, this);
   }
 
   get freeBlocks(): number {
@@ -134,8 +141,7 @@ export class BlockPool {
  *  shape): head count / head dims / dtype come from the first k/v pair,
  *  so the wiring (maybePageKv) needs no per-model shape plumbing. */
 export class PagedKVCache implements Cache {
-  /** Distinct kind: paged layout is serial-only and never merges into a
-   *  batch, so no capability guard should ever match it as plain. */
+  /** Distinct storage kind; the row adapter preserves its block pools. */
   signature(): string { return "kv:paged"; }
   /** Matches KVCache.STEP: v1's growth granularity is a permutation of
    *  today's 256-token step into fixed reusable slots, not a new tuning
@@ -155,6 +161,14 @@ export class PagedKVCache implements Cache {
     readonly blockSize: number,
   ) {}
 
+  clone(): PagedKVCache {
+    const copy = new PagedKVCache(this.capacityTokens, this.blockSize);
+    copy.offset = this.offset;
+    copy.blockTable = [...this.blockTable];
+    copy.pool = this.pool?.clone() ?? null;
+    return copy;
+  }
+
   get #blockSize(): number {
     return this.blockSize;
   }

package/src/mlx/array.ts

@@ -232,7 +232,7 @@ export class MlxArray {
     );
   }
 
-  /** Raw bytes of the evaluated array (copy). bf16/f16/f32 only. */
+  /** Raw bytes of a supported floating-point or integer array (copy). */
   rawBytes(): Uint8Array {
     return this.rawBytesView().slice();
   }
@@ -253,6 +253,7 @@ export class MlxArray {
       : dt === Dtype.float16 ? C.mlx_array_data_float16(this.handle)
       : dt === Dtype.bfloat16 ? C.mlx_array_data_bfloat16(this.handle)
       : dt === Dtype.uint32 ? C.mlx_array_data_uint32(this.handle)
+      : dt === Dtype.int32 ? C.mlx_array_data_int32(this.handle)
       : dt === Dtype.uint8 ? C.mlx_array_data_uint8(this.handle)
       : dt === Dtype.int8 ? C.mlx_array_data_int8(this.handle)
       : null;

package/src/model/artifact-identity.ts

@@ -0,0 +1,73 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Identity calculation owns bytes; this interface owns memo persistence. */
+export interface ArtifactIdentityStore {
+  get(key: string): Promise<string | undefined>;
+  put(key: string, digest: string): void;
+}
+
+export class FileArtifactIdentityStore implements ArtifactIdentityStore {
+  readonly #memory = new Map<string, string>();
+  readonly #pending = new Set<Promise<void>>();
+  constructor(readonly directory: string) {}
+
+  async get(key: string): Promise<string | undefined> {
+    const memory = this.#memory.get(key);
+    if (memory) return memory;
+    try {
+      const digest = await readFile(join(this.directory, key), "utf8");
+      if (!/^[0-9a-f]{64}$/.test(digest)) return undefined;
+      this.#memory.set(key, digest);
+      return digest;
+    } catch { return undefined; }
+  }
+
+  put(key: string, digest: string): void {
+    this.#memory.set(key, digest);
+    const temporary = join(this.directory, `${key}.${process.pid}.${randomUUID()}.tmp`);
+    const write = async () => {
+      try {
+        await mkdir(this.directory, { recursive: true });
+        await writeFile(temporary, digest);
+        await rename(temporary, join(this.directory, key));
+      } catch { await rm(temporary, { force: true }).catch(() => {}); }
+    };
+    const pending = write().finally(() => this.#pending.delete(pending));
+    this.#pending.add(pending);
+  }
+
+  async flush(): Promise<void> { await Promise.all(this.#pending); }
+}
+
+const defaultStore = new FileArtifactIdentityStore(join(homedir(), ".cache", "mlx-bun", "artifact-identities"));
+export interface ArtifactIdentityFile { name: string; path: string; }
+
+async function revision(files: readonly ArtifactIdentityFile[]): Promise<string> {
+  return JSON.stringify(await Promise.all(files.map(async file => {
+    const path = await realpath(file.path), info = await stat(path, { bigint: true });
+    return [file.name, path, info.dev, info.ino, info.size, info.mtimeNs, info.ctimeNs].map(String);
+  })));
+}
+
+/** Preserve the existing seed/name/byte digest, reusing it while file revisions
+ * are unchanged. ctime catches same-size edits even when mtime is restored.
+ * A memo miss computes the full identity; persistence never delays its caller. */
+export async function artifactIdentity(seed: string, input: readonly ArtifactIdentityFile[],
+  store: ArtifactIdentityStore = defaultStore): Promise<string> {
+  const files = [...input].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  const before = await revision(files);
+  const key = createHash("sha256").update(JSON.stringify([seed, before])).digest("hex");
+  const cached = await store.get(key);
+  if (cached) return cached;
+  const digest = createHash("sha256").update(seed);
+  for (const file of files) {
+    digest.update(file.name);
+    for await (const chunk of Bun.file(file.path).stream()) digest.update(chunk);
+  }
+  const value = digest.digest("hex");
+  if (before === await revision(files)) store.put(key, value);
+  return value;
+}