Content-Addressed Caching - Cache Keys, Remote Cache, Remote Execution & Poisoning

"""Content-addressed task cache: an undeclared env var produces a WRONG cache hit.

The "build" bakes API_URL into the bundle (like NEXT_PUBLIC_* or VITE_* variables).
Version A hashes only declared files, so a production build restores the preview bundle.
Version B fixes it two ways: the env var is part of the key, and the task only sees
declared variables (strict env filtering), so a missing declaration fails loudly.
"""
import hashlib, json

def key_of(parts: dict) -> str:
    return hashlib.sha256(json.dumps(parts, sort_keys=True).encode()).hexdigest()[:12]

files = {"src/app.ts": "fetch(API_URL + '/orders')", "package-lock.json": "lock-v1"}
toolchain = {"node": "22.14.0", "os": "linux-x64"}

def build_task(env: dict) -> str:
    # The task reads API_URL from its environment, whether or not anyone declared it.
    return f"bundle(api={env.get('API_URL', '<unset>')})"

def run(cache, env, declared_env, strict, label):
    parts = {"task": "build", "files": {k: key_of({"c": v}) for k, v in files.items()},
             "toolchain": toolchain,
             "env": {k: env.get(k) for k in sorted(declared_env)}}
    k = key_of(parts)
    if k in cache:
        print(f"{label:28} key={k} HIT  -> {cache[k]}")
        return cache[k]
    task_env = {n: env[n] for n in declared_env if n in env} if strict else dict(env)
    out = build_task(task_env)
    cache[k] = out
    print(f"{label:28} key={k} MISS -> {out}")
    return out

preview = {"API_URL": "https://preview.api.example", "HOME": "/home/ci"}
prod = {"API_URL": "https://api.example", "HOME": "/home/ci"}

print("A) loose: env var used but not declared in the key")
cache = {}
run(cache, preview, declared_env=[], strict=False, label="preview build")
out = run(cache, prod, declared_env=[], strict=False, label="production build")
print("   shipped to production:", out, "<- WRONG, preview URL")

print("B) strict + declared: API_URL is part of the cache key")
cache = {}
run(cache, preview, declared_env=["API_URL"], strict=True, label="preview build")
run(cache, prod, declared_env=["API_URL"], strict=True, label="production build")
run(cache, prod, declared_env=["API_URL"], strict=True, label="production rebuild")

print("C) strict but forgot to declare: the task sees nothing, so the bug is visible")
cache = {}
run(cache, prod, declared_env=[], strict=True, label="production build")

A) loose: env var used but not declared in the key
preview build                key=ae77a3b61f5d MISS -> bundle(api=https://preview.api.example)
production build             key=ae77a3b61f5d HIT  -> bundle(api=https://preview.api.example)
   shipped to production: bundle(api=https://preview.api.example) <- WRONG, preview URL
B) strict + declared: API_URL is part of the cache key
preview build                key=a9d96fecc8b1 MISS -> bundle(api=https://preview.api.example)
production build             key=81b70cd5321b MISS -> bundle(api=https://api.example)
production rebuild           key=81b70cd5321b HIT  -> bundle(api=https://api.example)
C) strict but forgot to declare: the task sees nothing, so the bug is visible
production build             key=ae77a3b61f5d MISS -> bundle(api=<unset>)

// Cache and remote-execution economics with illustrative numbers (not benchmarks).
// Expected task time with a cache = hashing + lookup + (hit ? restore : run + upload).
// Caching loses when the task is cheaper than a network round trip or the artifact is huge.

type TaskProfile = { name: string; runSec: number; artifactMB: number };

const lookupSec = 0.15;      // one round trip to a remote cache (example value)
const hashSec = 0.05;        // hashing declared inputs (example value)
const mbPerSec = 50;         // download/upload throughput (example value)

function expected(t: TaskProfile, hitRate: number) {
  const transfer = t.artifactMB / mbPerSec;
  const hit = hashSec + lookupSec + transfer;              // restore outputs
  const miss = hashSec + lookupSec + t.runSec + transfer;  // run, then upload
  return hitRate * hit + (1 - hitRate) * miss;
}

const profiles: TaskProfile[] = [
  { name: "typecheck pkg", runSec: 40, artifactMB: 2 },
  { name: "lint tiny pkg", runSec: 0.1, artifactMB: 0.01 },
  { name: "docker image", runSec: 25, artifactMB: 1500 },
];

console.log("task            no-cache  hit=50%  hit=90%  verdict");
for (const p of profiles) {
  const e50 = expected(p, 0.5);
  const e90 = expected(p, 0.9);
  const verdict = e90 < p.runSec ? "cache it" : "do not cache remotely";
  console.log(
    `${p.name.padEnd(15)} ${p.runSec.toFixed(1).padStart(7)}s ${e50.toFixed(1).padStart(7)}s ${e90.toFixed(1).padStart(7)}s  ${verdict}`,
  );
}

// Remote execution: many workers help only until you hit the critical path.
const actions = 400;          // independent compile actions (example)
const perAction = 3;          // seconds each (example)
const criticalPath = 30;      // longest dependency chain in seconds (example)
for (const workers of [8, 64, 512]) {
  const t = Math.max(criticalPath, (actions * perAction) / workers);
  console.log(`remote execution with ${String(workers).padStart(3)} workers: about ${t.toFixed(0)}s (critical path floor ${criticalPath}s)`);
}

task            no-cache  hit=50%  hit=90%  verdict
typecheck pkg      40.0s    20.2s     4.2s  cache it
lint tiny pkg       0.1s     0.3s     0.2s  do not cache remotely
docker image       25.0s    42.7s    32.7s  do not cache remotely
remote execution with   8 workers: about 150s (critical path floor 30s)
remote execution with  64 workers: about 30s (critical path floor 30s)
remote execution with 512 workers: about 30s (critical path floor 30s)