@vzn/vx 0.0.0 → 0.0.14

package/src/cache/cas-backend.ts

@@ -0,0 +1,97 @@
+// CASBackend — pluggable content-addressed storage beneath the cache.
+//
+// Today's Cache + LayeredCache both bundle "where do the bytes live"
+// with "how do we look up entries metadata + key derivation."
+// CASBackend separates the former so a future R2/S3 backend
+// or REAPI CAS bridge can drop in without touching the
+// orchestrator or the SQL entries index.
+//
+// Two reference implementations in this file:
+//   - MemoryCASBackend — testing + in-memory builds. Holds raw bytes.
+//   - FsCASBackend     — writes bytes to a directory; mirrors what
+//                        Cache.save does today. Bun-native using Bun.file
+//                        for the read path so big artifacts stream
+//                        without slurping into memory.
+//
+// Cache.ts has NOT yet been rewired to use a CASBackend — that's a
+// follow-up (Phase 1b). This file ships the abstraction + the two
+// reference impls so downstream work (R2, otel-bridge, distributed-ci)
+// can rely on the type. Byte-identical behaviour today.
+
+import { rm } from 'node:fs/promises'
+import path from 'node:path'
+import type { Digest } from './digest.js'
+
+export interface CASBackend {
+  /** Write bytes under `digest`. Idempotent — putting the same digest twice is a no-op. */
+  put(digest: Digest, bytes: Uint8Array): Promise<void>
+  /** Read bytes under `digest`, or null if absent. */
+  get(digest: Digest): Promise<Uint8Array | null>
+  /** Cheap existence probe — no bytes round-tripped if possible. */
+  has(digest: Digest): Promise<boolean>
+  /** Drop one entry (eviction). No-op if absent. */
+  remove(digest: Digest): Promise<void>
+}
+
+/** In-memory backend, useful for tests and ephemeral runs. */
+export class MemoryCASBackend implements CASBackend {
+  private readonly store = new Map<string, Uint8Array>()
+
+  async put(digest: Digest, bytes: Uint8Array): Promise<void> {
+    if (bytes.byteLength !== digest.sizeBytes) {
+      throw new Error(
+        `MemoryCASBackend.put: sizeBytes mismatch (digest=${digest.sizeBytes}, actual=${bytes.byteLength})`,
+      )
+    }
+    this.store.set(digest.hash, bytes)
+  }
+
+  async get(digest: Digest): Promise<Uint8Array | null> {
+    return this.store.get(digest.hash) ?? null
+  }
+
+  async has(digest: Digest): Promise<boolean> {
+    return this.store.has(digest.hash)
+  }
+
+  async remove(digest: Digest): Promise<void> {
+    this.store.delete(digest.hash)
+  }
+
+  /** Test-only: how many entries are held. */
+  size(): number {
+    return this.store.size
+  }
+}
+
+/** Filesystem-backed backend writing `<rootDir>/<hash>.tar.zst` files. */
+export class FsCASBackend implements CASBackend {
+  constructor(private readonly rootDir: string) {}
+
+  private pathFor(digest: Digest): string {
+    return path.join(this.rootDir, `${digest.hash}.tar.zst`)
+  }
+
+  async put(digest: Digest, bytes: Uint8Array): Promise<void> {
+    if (bytes.byteLength !== digest.sizeBytes) {
+      throw new Error(
+        `FsCASBackend.put: sizeBytes mismatch (digest=${digest.sizeBytes}, actual=${bytes.byteLength})`,
+      )
+    }
+    await Bun.write(this.pathFor(digest), bytes)
+  }
+
+  async get(digest: Digest): Promise<Uint8Array | null> {
+    const file = Bun.file(this.pathFor(digest))
+    if (!(await file.exists())) return null
+    return new Uint8Array(await file.arrayBuffer())
+  }
+
+  async has(digest: Digest): Promise<boolean> {
+    return Bun.file(this.pathFor(digest)).exists()
+  }
+
+  async remove(digest: Digest): Promise<void> {
+    await rm(this.pathFor(digest), { force: true })
+  }
+}

package/src/cache/digest.ts

@@ -0,0 +1,47 @@
+// Digest — the explicit content-address used by every cache layer.
+//
+// Lifted as a first-class type (architecture-review-2026-06.md §4.3)
+// so storage backends become pluggable beneath CacheLayer: local FS,
+// R2, S3, or a future REAPI CAS bridge all speak (hash, sizeBytes).
+//
+// Two practical wins from making this explicit:
+//   1. sizeBytes is the truncation check at transport boundaries (HTTP
+//      Content-Length, R2 ETag-by-size). Free correctness, free corrupt-
+//      artifact-early-fail.
+//   2. CASBackend.has(digest) can answer with just the metadata, no
+//      bytes round-trip — what existence probes want.
+//
+// Why sizeBytes is `number` and not `bigint`: Bun.file().size returns
+// number; JS Number safely represents integers to 2^53-1 (~9 PB); no
+// real cache artifact gets there. Bigint would create the same
+// JSON.stringify-throws nuisance we already navigated for ns timestamps.
+
+export interface Digest {
+  readonly hash: string
+  readonly sizeBytes: number
+}
+
+export function makeDigest(hash: string, sizeBytes: number): Digest {
+  if (!/^[0-9a-f]+$/i.test(hash)) {
+    throw new Error(`invalid digest hash: ${JSON.stringify(hash)}`)
+  }
+  if (!Number.isInteger(sizeBytes) || sizeBytes < 0) {
+    throw new Error(`invalid digest sizeBytes: ${sizeBytes}`)
+  }
+  return { hash, sizeBytes }
+}
+
+export function digestEqual(a: Digest, b: Digest): boolean {
+  return a.hash === b.hash && a.sizeBytes === b.sizeBytes
+}
+
+/** Stable wire format for logging / RPC: `hash/sizeBytes`. */
+export function digestString(d: Digest): string {
+  return `${d.hash}/${d.sizeBytes}`
+}
+
+export function parseDigest(s: string): Digest {
+  const slash = s.indexOf('/')
+  if (slash === -1) throw new Error(`invalid digest string: ${JSON.stringify(s)}`)
+  return makeDigest(s.slice(0, slash), Number(s.slice(slash + 1)))
+}

package/src/cache/index.ts

@@ -0,0 +1,28 @@
+// Module contract. Cross-module imports must come through here; see
+// docs/design/module-isolation-2026-06.md and tests/module-boundaries.test.ts.
+// tar.ts is internal — artifact pack/extract is an implementation detail.
+
+export {
+  Cache,
+  type CacheEntry,
+  type CacheLayer,
+  type CachePolicy,
+  FULL_CACHE_POLICY,
+  type InvocationRecord,
+  parseCachePolicy,
+  type RunRecord,
+  type TaskInputRow,
+  WORKSPACE_OUTPUT_PREFIX,
+} from './cache.js'
+export { type CASBackend, FsCASBackend, MemoryCASBackend } from './cas-backend.js'
+export { type Digest, digestEqual, digestString, makeDigest, parseDigest } from './digest.js'
+export {
+  cleanOutputs,
+  cleanWorkspaceOutputs,
+  GitFilesCache,
+  populateGitFilesCache,
+  resolveInputs,
+  resolveOutputs,
+  resolveWorkspaceOutputs,
+} from './inputs.js'
+export { LayeredCache, type RemoteCacheLayer } from './layered-cache.js'