@untangle-code/storage-local 0.0.0-stage → 0.1.1

package/dist/storage.js

@@ -0,0 +1,34 @@
+import { DEFAULT_ANALYSIS_CACHE_MAX_BYTES, LocalAnalysisCache, LocalContentCache, } from "./analysis-cache.js";
+import { LocalCheckpointStore } from "./checkpoint-store.js";
+import { DEFAULT_EMBEDDING_CACHE_MAX_BYTES, LocalEmbeddingCache } from "./embedding-cache.js";
+import { buildStateDirLayout, ensureStateDirLayout } from "./layout.js";
+import { LocalFileSystem } from "./local-file-system.js";
+import { FileLockProvider } from "./lock-provider.js";
+import { LocalSearchJourneyStore } from "./search-journey-store.js";
+/**
+ * Builds the `.untangle/` layout under `stateRoot` (creating every directory
+ * if needed) and returns the wired-up local storage adapters. `stateRoot`
+ * becomes the ONLY root the returned `FileSystemPort` will resolve paths
+ * within (rule 3: "kein Schreiben ausserhalb des Zustandsverzeichnisses").
+ */
+export async function openLocalStorage(stateRoot, options, callOptions) {
+    const fs = new LocalFileSystem([stateRoot]);
+    const layout = buildStateDirLayout(stateRoot);
+    await ensureStateDirLayout(fs, layout, callOptions);
+    const embeddingCache = new LocalEmbeddingCache(fs, layout.cache.embeddings, options.clock, options.random, {
+        maxBytes: options.embeddingCacheMaxBytes ?? DEFAULT_EMBEDDING_CACHE_MAX_BYTES,
+    });
+    const analysisMaxBytes = options.analysisCacheMaxBytes ?? DEFAULT_ANALYSIS_CACHE_MAX_BYTES;
+    const analysisCache = new LocalAnalysisCache(new LocalContentCache(fs, layout.cache.analysis.parse, options.clock, options.random, {
+        maxBytes: analysisMaxBytes,
+    }), new LocalContentCache(fs, layout.cache.analysis.chunk, options.clock, options.random, {
+        maxBytes: analysisMaxBytes,
+    }), new LocalContentCache(fs, layout.cache.analysis.metrics, options.clock, options.random, {
+        maxBytes: analysisMaxBytes,
+    }));
+    const checkpoints = new LocalCheckpointStore(fs, layout.jobs, options.random);
+    const locks = new FileLockProvider(fs, layout.locks, options.clock, options.random, options.host);
+    const searchJourneys = new LocalSearchJourneyStore(fs, layout.productComplexity.sessions, options.random, locks, options.clock);
+    return { layout, fs, embeddingCache, analysisCache, checkpoints, locks, searchJourneys };
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,gCAAgC,EAChC,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,iCAAiC,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC9F,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAuB,MAAM,aAAa,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAwBpE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAAiB,EACjB,OAA4B,EAC5B,WAA6B;IAE7B,MAAM,EAAE,GAAG,IAAI,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAEpD,MAAM,cAAc,GAAG,IAAI,mBAAmB,CAC5C,EAAE,EACF,MAAM,CAAC,KAAK,CAAC,UAAU,EACvB,OAAO,CAAC,KAAK,EACb,OAAO,CAAC,MAAM,EACd;QACE,QAAQ,EAAE,OAAO,CAAC,sBAAsB,IAAI,iCAAiC;KAC9E,CACF,CAAC;IACF,MAAM,gBAAgB,GAAG,OAAO,CAAC,qBAAqB,IAAI,gCAAgC,CAAC;IAC3F,MAAM,aAAa,GAAG,IAAI,kBAAkB,CAC1C,IAAI,iBAAiB,CAAC,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;QACpF,QAAQ,EAAE,gBAAgB;KAC3B,CAAC,EACF,IAAI,iBAAiB,CAAC,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;QACpF,QAAQ,EAAE,gBAAgB;KAC3B,CAAC,EACF,IAAI,iBAAiB,CAAC,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;QACtF,QAAQ,EAAE,gBAAgB;KAC3B,CAAC,CACH,CAAC;IACF,MAAM,WAAW,GAAG,IAAI,oBAAoB,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAG,IAAI,gBAAgB,CAAC,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAClG,MAAM,cAAc,GAAG,IAAI,uBAAuB,CAChD,EAAE,EACF,MAAM,CAAC,iBAAiB,CAAC,QAAQ,EACjC,OAAO,CAAC,MAAM,EACd,KAAK,EACL,OAAO,CAAC,KAAK,CACd,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC;AAC3F,CAAC"}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@untangle-code/storage-local",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "Untangle local state under .untangle/: cache (embeddings/parser/git-blobs), atomic checkpoint mirror, file-based LockProvider, path-sandboxed FileSystemPort adapter.",
+  "license": "AGPL-3.0-only",
+  "homepage": "https://github.com/lboel/untangle",
+  "bugs": {
+    "url": "https://github.com/lboel/untangle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lboel/untangle.git",
+    "directory": "packages/storage-local"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^22.13.0 || >=24.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/test-helpers.*",
+    "!dist/**/test-support.*",
+    "!dist/**/test-support/**",
+    "!dist/**/testing/**",
+    "!dist/**/__tests__/**",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/test-helpers.ts",
+    "!src/**/test-support.ts",
+    "!src/**/test-support/**",
+    "!src/**/testing/**",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "THIRD_PARTY_LICENSES.md"
+  ],
+  "dependencies": {
+    "@untangle-code/domain": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.7",
+    "typescript": "5.9.3",
+    "vitest": "3.2.7",
+    "@untangle-code/testkit": "0.1.1"
+  },
+  "scripts": {
+    "build": "node ../../scripts/tsc-build.mjs tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
 }

package/src/abort.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared `AbortSignal` handling (spec.md §22: "public APIs MUST support
+ * abort signals"; rule 9: every long-running method respects `AbortSignal`
+ * and aborts with `JOB_CANCELLED`).
+ *
+ * Every port method in this package is `async`, so throwing synchronously
+ * here still surfaces as a rejected Promise to the caller — unlike
+ * `@untangle-code/testkit`'s `abortedRejection` (which exists specifically
+ * for a few NON-`async` methods where a synchronous throw would be a bug).
+ */
+import type { PortCallOptions } from "@untangle-code/domain";
+import { UntangleError } from "@untangle-code/domain";
+
+/** Throws `UntangleError("JOB_CANCELLED", …)` when `options.signal` is already aborted. */
+export function assertNotAborted(options: PortCallOptions | undefined, operation: string): void {
+  if (options?.signal?.aborted) {
+    throw new UntangleError("JOB_CANCELLED", `"${operation}" was aborted`, { operation });
+  }
+}
+
+/** Builds a `PortCallOptions` from an optional `AbortSignal` without ever setting
+ * `signal: undefined` explicitly — required because domain's `PortCallOptions` is
+ * checked under `exactOptionalPropertyTypes`. */
+export function portOptions(signal: AbortSignal | undefined): PortCallOptions | undefined {
+  return signal === undefined ? undefined : { signal };
+}

package/src/analysis-cache.ts

@@ -0,0 +1,404 @@
+/**
+ * Inhaltsadressierte Caches fuer Parse, Chunk und Komplexitaet (WP-100,
+ * docs/INDEX-SHARING.md §5) — unter `.untangle/cache/analysis/`.
+ *
+ * WARUM ES SIE GIBT: Parsen, Chunken und Messen sind reine Funktionen des
+ * Dateiinhalts. Ohne Cache rechnet jeder Lauf sie neu, obwohl sich zwischen
+ * zwei Laeufen (und zwischen zwei Worktrees desselben Repositoriums)
+ * typischerweise nur wenige Prozent der Dateien unterscheiden. Der
+ * Einbettungs-Cache (spec.md §9.4) ist bereits inhaltsadressiert; diese drei
+ * Caches schliessen die Luecke davor.
+ *
+ * DER SCHLUESSEL IST DIE GANZE SICHERHEIT. Ein Cache, der ein falsches
+ * Ergebnis liefert, ist schlimmer als kein Cache: das falsche Ergebnis ist
+ * nicht sichtbar. Der Schluesselbau steht deshalb in `@untangle-code/domain`
+ * (analysis-cache-key.ts) und traegt jede Eingabe, von der der gespeicherte
+ * Wert abhaengt.
+ *
+ * ABLAGE: ein JSON je Eintrag, zwei Hexzeichen tief geshardet
+ * (`<hash[0:2]>/<hash>.json`), plus ein `index.json` je Cache mit Groesse und
+ * letztem Zugriff — die Buchfuehrung fuer die Verdraengung nach Groesse (LRU).
+ *
+ * UNTERSCHIED ZUM EINBETTUNGS-CACHE: dessen Manifest wird bei JEDER Mutation
+ * geschrieben. Das waere hier falsch: drei Caches mal zwei Zugriffe je Datei
+ * ergaeben sechs Manifest-Schreibvorgaenge je Datei und fraessen genau die
+ * Zeit auf, die der Cache spart. Das Manifest wird deshalb im Speicher
+ * gefuehrt und alle {@link MANIFEST_FLUSH_INTERVAL} Mutationen sowie bei
+ * {@link LocalContentCache.flush} geschrieben. PREIS: bricht der Lauf hart ab,
+ * koennen geschriebene Eintraege im Manifest fehlen. Das kostet Treffer und
+ * laesst Dateien ungezaehlt liegen — es liefert NIE ein falsches Ergebnis,
+ * weil ein Wert ausschliesslich ueber das Manifest gefunden wird.
+ *
+ * Lesen degradiert kontrolliert (architecture.md §12: lokale Caches sind
+ * loeschbar und rekonstruierbar): fehlende Datei, kaputtes JSON, kaputtes
+ * Manifest — alles ist ein Fehlschlag des Nachschlagens, kein geworfener
+ * Fehler.
+ */
+import * as nodePath from "node:path";
+
+import type {
+  AnalysisCacheKind,
+  Clock,
+  FileSystemPort,
+  PortCallOptions,
+  Random,
+} from "@untangle-code/domain";
+import { sha256Hex } from "@untangle-code/domain";
+
+import { assertNotAborted } from "./abort.js";
+import { isNotFoundError } from "./fs-errors.js";
+
+// Der Schluesselbau liegt in `@untangle-code/domain`, weil ihn BEIDE Seiten
+// brauchen: dieses Paket legt ab, `@untangle-code/core` schlaegt nach. Zwei
+// Kopien desselben Schluessels waeren die sicherste Art, den Cache eines Tages
+// an der falschen Stelle treffen zu lassen. Hier nur weitergereicht, damit ein
+// Aufrufer beides aus einem Paket bekommt.
+export {
+  ANALYSIS_CACHE_KINDS,
+  buildChunkCacheKey,
+  buildMetricsCacheKey,
+  buildParseCacheKey,
+  type AnalysisCacheKind,
+  type AnalysisIdentityKeyPartsV1,
+} from "@untangle-code/domain";
+
+/** 256 MiB je Cache — eine Untangle-Vorgabe, keine Spec-Zahl. */
+export const DEFAULT_ANALYSIS_CACHE_MAX_BYTES = 256 * 1024 * 1024;
+
+/** Nach so vielen Mutationen wird das Manifest geschrieben. */
+export const MANIFEST_FLUSH_INTERVAL = 64;
+
+const MANIFEST_FILE_NAME = "index.json";
+
+export interface ContentCacheStatsV1 {
+  entryCount: number;
+  totalBytes: number;
+  /** Treffer seit dem Oeffnen dieses Cache-Objekts. */
+  hits: number;
+  /** Fehlschlaege seit dem Oeffnen dieses Cache-Objekts. */
+  misses: number;
+  /** Trefferquote in [0,1]; 0, wenn nichts nachgeschlagen wurde. */
+  hitRate: number;
+  /** Wie viele Eintraege die Groessengrenze verdraengt hat. */
+  evictions: number;
+}
+
+interface ManifestEntryV1 {
+  fileName: string;
+  sizeBytes: number;
+  lastAccessEpochMs: number;
+}
+
+interface ManifestV1 {
+  version: 1;
+  entries: Record<string, ManifestEntryV1>;
+}
+
+function encode(text: string): Uint8Array {
+  return new TextEncoder().encode(text);
+}
+
+function signalOptions(options: PortCallOptions | undefined): PortCallOptions | undefined {
+  return options?.signal ? { signal: options.signal } : undefined;
+}
+
+function totalBytesOf(manifest: ManifestV1): number {
+  let total = 0;
+  for (const entry of Object.values(manifest.entries)) {
+    total += entry.sizeBytes;
+  }
+  return total;
+}
+
+function pickEvictionCandidate(manifest: ManifestV1, protectedKey: string): string | null {
+  const keys = Object.keys(manifest.entries);
+  let best: string | null = null;
+  let bestAccess = Number.POSITIVE_INFINITY;
+  for (const key of keys) {
+    if (key === protectedKey && keys.length === 1) {
+      // Der eben geschriebene Eintrag ist der letzte — ihn zu verdraengen
+      // hiesse, `set()` stillschweigend wirkungslos zu machen.
+      continue;
+    }
+    const entry = manifest.entries[key];
+    if (entry !== undefined && entry.lastAccessEpochMs < bestAccess) {
+      bestAccess = entry.lastAccessEpochMs;
+      best = key;
+    }
+  }
+  return best;
+}
+
+/**
+ * Ein inhaltsadressierter JSON-Cache mit Groessengrenze, Verdraengung und
+ * Trefferquote. Der Schluessel ist eine undurchsichtige Zeichenkette; wer ihn
+ * baut, verantwortet seine Vollstaendigkeit (siehe Kopf dieser Datei).
+ */
+export class LocalContentCache {
+  private readonly maxBytes: number;
+  private manifest: ManifestV1 | null = null;
+  private dirty = 0;
+  private hits = 0;
+  private misses = 0;
+  private evictions = 0;
+
+  public constructor(
+    private readonly fs: FileSystemPort,
+    private readonly dir: string,
+    private readonly clock: Clock,
+    private readonly random: Random,
+    options?: { maxBytes?: number },
+  ) {
+    this.maxBytes = options?.maxBytes ?? DEFAULT_ANALYSIS_CACHE_MAX_BYTES;
+  }
+
+  private manifestPath(): string {
+    return nodePath.join(this.dir, MANIFEST_FILE_NAME);
+  }
+
+  private entryFileName(logicalKey: string): string {
+    const hash = sha256Hex(logicalKey);
+    return nodePath.join(hash.slice(0, 2), `${hash}.json`);
+  }
+
+  private entryPath(fileName: string): string {
+    return nodePath.join(this.dir, fileName);
+  }
+
+  private async loadManifest(options: PortCallOptions | undefined): Promise<ManifestV1> {
+    if (this.manifest !== null) {
+      return this.manifest;
+    }
+    let text: string;
+    try {
+      text = await this.fs.readTextFile(this.manifestPath(), options);
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        this.manifest = { version: 1, entries: {} };
+        return this.manifest;
+      }
+      throw error;
+    }
+    try {
+      const parsed = JSON.parse(text) as Partial<ManifestV1>;
+      this.manifest =
+        parsed.entries === undefined
+          ? { version: 1, entries: {} }
+          : { version: 1, entries: parsed.entries };
+    } catch {
+      // Kaputtes Manifest — leerer Cache statt geworfener Fehler.
+      this.manifest = { version: 1, entries: {} };
+    }
+    return this.manifest;
+  }
+
+  private async persistManifest(options: PortCallOptions | undefined): Promise<void> {
+    const manifest = this.manifest;
+    if (manifest === null) {
+      return;
+    }
+    await this.fs.mkdir(this.dir, { recursive: true, ...signalOptions(options) });
+    const tempPath = `${this.manifestPath()}.${this.random.uuid()}.tmp`;
+    await this.fs.writeFile(tempPath, encode(JSON.stringify(manifest)), options);
+    await this.fs.rename(tempPath, this.manifestPath(), options);
+    this.dirty = 0;
+  }
+
+  private async touched(options: PortCallOptions | undefined): Promise<void> {
+    this.dirty++;
+    if (this.dirty >= MANIFEST_FLUSH_INTERVAL) {
+      await this.persistManifest(options);
+    }
+  }
+
+  /** Schreibt das Manifest, falls Mutationen ausstehen. Am Ende eines Laufs aufrufen. */
+  public async flush(options?: PortCallOptions): Promise<void> {
+    if (this.dirty > 0) {
+      await this.persistManifest(options);
+    }
+  }
+
+  /** Der Wert, oder `null` fuer "nicht im Cache". Wirft nicht fuer kaputte Eintraege. */
+  public async get(logicalKey: string, options?: PortCallOptions): Promise<unknown | null> {
+    assertNotAborted(options, "analysis_cache_get");
+    const manifest = await this.loadManifest(options);
+    const entry = manifest.entries[logicalKey];
+    if (entry === undefined) {
+      this.misses++;
+      return null;
+    }
+    let text: string;
+    try {
+      text = await this.fs.readTextFile(this.entryPath(entry.fileName), options);
+    } catch (error) {
+      if (!isNotFoundError(error)) {
+        throw error;
+      }
+      delete manifest.entries[logicalKey];
+      await this.touched(options);
+      this.misses++;
+      return null;
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(text);
+    } catch {
+      delete manifest.entries[logicalKey];
+      await this.touched(options);
+      this.misses++;
+      return null;
+    }
+    entry.lastAccessEpochMs = this.clock.nowEpochMs();
+    this.dirty++;
+    this.hits++;
+    return value;
+  }
+
+  public async set(logicalKey: string, value: unknown, options?: PortCallOptions): Promise<void> {
+    assertNotAborted(options, "analysis_cache_set");
+    const fileName = this.entryFileName(logicalKey);
+    const entryPath = this.entryPath(fileName);
+    const bytes = encode(JSON.stringify(value));
+
+    await this.fs.mkdir(nodePath.dirname(entryPath), {
+      recursive: true,
+      ...signalOptions(options),
+    });
+    const tempPath = `${entryPath}.${this.random.uuid()}.tmp`;
+    await this.fs.writeFile(tempPath, bytes, options);
+    await this.fs.rename(tempPath, entryPath, options);
+
+    const manifest = await this.loadManifest(options);
+    manifest.entries[logicalKey] = {
+      fileName,
+      sizeBytes: bytes.length,
+      lastAccessEpochMs: this.clock.nowEpochMs(),
+    };
+    await this.evictUntilWithinLimit(manifest, logicalKey, options);
+    await this.touched(options);
+  }
+
+  private async evictUntilWithinLimit(
+    manifest: ManifestV1,
+    justWrittenKey: string,
+    options: PortCallOptions | undefined,
+  ): Promise<void> {
+    let total = totalBytesOf(manifest);
+    while (total > this.maxBytes) {
+      const victim = pickEvictionCandidate(manifest, justWrittenKey);
+      if (victim === null) {
+        break;
+      }
+      const entry = manifest.entries[victim];
+      delete manifest.entries[victim];
+      if (entry !== undefined) {
+        total -= entry.sizeBytes;
+        this.evictions++;
+        try {
+          await this.fs.remove(this.entryPath(entry.fileName), options);
+        } catch {
+          // Der Manifest-Eintrag ist so oder so weg; ein spaeterer `get`
+          // trifft nicht mehr.
+        }
+      }
+    }
+  }
+
+  public async stats(options?: PortCallOptions): Promise<ContentCacheStatsV1> {
+    assertNotAborted(options, "analysis_cache_stats");
+    const manifest = await this.loadManifest(options);
+    const lookups = this.hits + this.misses;
+    return {
+      entryCount: Object.keys(manifest.entries).length,
+      totalBytes: totalBytesOf(manifest),
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: lookups === 0 ? 0 : this.hits / lookups,
+      evictions: this.evictions,
+    };
+  }
+
+  /** Loescht ausschliesslich das eigene Verzeichnis dieses Caches. */
+  public async clear(options?: PortCallOptions): Promise<void> {
+    assertNotAborted(options, "analysis_cache_clear");
+    await this.fs.remove(this.dir, { recursive: true, ...signalOptions(options) });
+    this.manifest = { version: 1, entries: {} };
+    this.dirty = 0;
+  }
+}
+
+/** Trefferquoten aller drei Caches, einzeln und zusammen. */
+export interface AnalysisCacheStatsV1 {
+  parse: ContentCacheStatsV1;
+  chunk: ContentCacheStatsV1;
+  metrics: ContentCacheStatsV1;
+  totalHits: number;
+  totalMisses: number;
+  /** Trefferquote ueber alle drei Caches in [0,1]. */
+  hitRate: number;
+}
+
+/**
+ * Die drei Caches als ein Gegenstand — genau die Form, die
+ * `@untangle-code/core` als `AnalysisCacheLike` erwartet.
+ */
+export class LocalAnalysisCache {
+  public constructor(
+    public readonly parse: LocalContentCache,
+    public readonly chunk: LocalContentCache,
+    public readonly metrics: LocalContentCache,
+  ) {}
+
+  private of(kind: AnalysisCacheKind): LocalContentCache {
+    if (kind === "parse") return this.parse;
+    if (kind === "chunk") return this.chunk;
+    return this.metrics;
+  }
+
+  public async get(
+    kind: AnalysisCacheKind,
+    key: string,
+    options?: PortCallOptions,
+  ): Promise<unknown | null> {
+    return this.of(kind).get(key, options);
+  }
+
+  public async set(
+    kind: AnalysisCacheKind,
+    key: string,
+    value: unknown,
+    options?: PortCallOptions,
+  ): Promise<void> {
+    await this.of(kind).set(key, value, options);
+  }
+
+  /** Schreibt die Manifeste aller drei Caches. */
+  public async flush(options?: PortCallOptions): Promise<void> {
+    await this.parse.flush(options);
+    await this.chunk.flush(options);
+    await this.metrics.flush(options);
+  }
+
+  public async stats(options?: PortCallOptions): Promise<AnalysisCacheStatsV1> {
+    const parse = await this.parse.stats(options);
+    const chunk = await this.chunk.stats(options);
+    const metrics = await this.metrics.stats(options);
+    const totalHits = parse.hits + chunk.hits + metrics.hits;
+    const totalMisses = parse.misses + chunk.misses + metrics.misses;
+    const lookups = totalHits + totalMisses;
+    return {
+      parse,
+      chunk,
+      metrics,
+      totalHits,
+      totalMisses,
+      hitRate: lookups === 0 ? 0 : totalHits / lookups,
+    };
+  }
+
+  public async clear(options?: PortCallOptions): Promise<void> {
+    await this.parse.clear(options);
+    await this.chunk.clear(options);
+    await this.metrics.clear(options);
+  }
+}

package/src/checkpoint-store.ts

@@ -0,0 +1,155 @@
+/**
+ * Local checkpoint mirror (architecture.md §12, §13.3; spec.md §11.2:
+ * "Nach jedem konfigurierten Dateibatch MUSS ein Checkpoint gespeichert
+ * werden" / "Bei Neustart MUSS der Job ab dem letzten bestätigten
+ * Checkpoint fortsetzbar sein").
+ *
+ * Every write is temp-file-then-rename: the checkpoint at `jobs/<jobId>.json`
+ * is only ever created or replaced by a single atomic `rename` onto that
+ * exact path, so a process crash mid-write leaves, at worst, an orphaned
+ * `*.tmp` file next to it — the real path itself is always either the
+ * previous good checkpoint or the new one, never a half-written mix of both
+ * (see README "Entscheidungen" for the crash-simulation test).
+ *
+ * `jobs/latest/<hash>.json` is a small secondary index — "which job is the
+ * latest checkpoint for this repo+ref" — so `loadLatest` does not have to
+ * list and parse every checkpoint file. It is written the same atomic way,
+ * AFTER the checkpoint itself, so a crash between the two writes leaves the
+ * pointer stale (pointing at the previous job) rather than pointing at a
+ * checkpoint that does not exist — `loadLatest` degrades to `null` if the
+ * pointer cannot be trusted at all (spec.md §25.2: reads degrade optional
+ * data in a controlled way), while `load(jobId)` on an actually corrupted
+ * checkpoint body throws instead, because THAT is the resume-critical record
+ * itself, not an accelerator index over it.
+ */
+import * as nodePath from "node:path";
+
+import type {
+  CheckpointStorePort,
+  FileSystemPort,
+  IndexCheckpointV1,
+  PortCallOptions,
+  Random,
+} from "@untangle-code/domain";
+import { ID_COMPONENT_SEPARATOR, sha256Hex, UntangleError } from "@untangle-code/domain";
+
+import { assertNotAborted } from "./abort.js";
+import { isNotFoundError } from "./fs-errors.js";
+
+const POINTER_DIR_NAME = "latest";
+
+interface LatestPointerV1 {
+  jobId: string;
+}
+
+function encode(text: string): Uint8Array {
+  return new TextEncoder().encode(text);
+}
+
+function signalOptions(options: PortCallOptions | undefined): PortCallOptions | undefined {
+  return options?.signal ? { signal: options.signal } : undefined;
+}
+
+/** Local, atomically-mirrored `CheckpointStorePort` under `jobs/`. */
+export class LocalCheckpointStore implements CheckpointStorePort {
+  public constructor(
+    private readonly fs: FileSystemPort,
+    private readonly jobsDir: string,
+    private readonly random: Random,
+  ) {}
+
+  private pathForJob(jobId: string): string {
+    return nodePath.join(this.jobsDir, `${jobId}.json`);
+  }
+
+  /**
+   * Both components are variable-length, so a plain concatenation would be
+   * ambiguous (e.g. `repoId="ab"` + `refId="c"` vs. `repoId="a"` +
+   * `refId="bc"`) — joined with the same separator domain's own identity
+   * model uses for exactly this reason (`identity.ts`'s doc comment).
+   */
+  private pointerPathFor(repoId: string, refId: string): string {
+    const hash = sha256Hex(`${repoId}${ID_COMPONENT_SEPARATOR}${refId}`);
+    return nodePath.join(this.jobsDir, POINTER_DIR_NAME, `${hash}.json`);
+  }
+
+  private async writeAtomic(
+    finalPath: string,
+    content: string,
+    options: PortCallOptions | undefined,
+  ): Promise<void> {
+    const dir = nodePath.dirname(finalPath);
+    await this.fs.mkdir(dir, { recursive: true, ...signalOptions(options) });
+    const tempPath = `${finalPath}.${this.random.uuid()}.tmp`;
+    await this.fs.writeFile(tempPath, encode(content), options);
+    await this.fs.rename(tempPath, finalPath, options);
+  }
+
+  public async save(checkpoint: IndexCheckpointV1, options?: PortCallOptions): Promise<void> {
+    assertNotAborted(options, "checkpoint_save");
+    await this.writeAtomic(this.pathForJob(checkpoint.jobId), JSON.stringify(checkpoint), options);
+    const pointer: LatestPointerV1 = { jobId: checkpoint.jobId };
+    await this.writeAtomic(
+      this.pointerPathFor(checkpoint.repoId, checkpoint.refId),
+      JSON.stringify(pointer),
+      options,
+    );
+  }
+
+  public async load(jobId: string, options?: PortCallOptions): Promise<IndexCheckpointV1 | null> {
+    assertNotAborted(options, "checkpoint_load");
+    let text: string;
+    try {
+      text = await this.fs.readTextFile(this.pathForJob(jobId), options);
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        return null;
+      }
+      throw error;
+    }
+    try {
+      return JSON.parse(text) as IndexCheckpointV1;
+    } catch (parseError) {
+      // Should never happen given atomic temp+rename writes — this is a
+      // defensive, loud failure (fail-closed, spec.md §25.2) for the one
+      // record a resume actually depends on, not a "missing optional data"
+      // case that could silently degrade to "start over".
+      throw new UntangleError(
+        "INDEX_INCOMPLETE",
+        `checkpoint "${jobId}" is corrupted and cannot be safely resumed from`,
+        { operation: "checkpoint_load", context: { jobId }, cause: parseError },
+      );
+    }
+  }
+
+  public async loadLatest(
+    repoId: string,
+    refId: string,
+    options?: PortCallOptions,
+  ): Promise<IndexCheckpointV1 | null> {
+    assertNotAborted(options, "checkpoint_load_latest");
+    let text: string;
+    try {
+      text = await this.fs.readTextFile(this.pointerPathFor(repoId, refId), options);
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        return null;
+      }
+      throw error;
+    }
+    let pointer: LatestPointerV1;
+    try {
+      pointer = JSON.parse(text) as LatestPointerV1;
+    } catch {
+      // The pointer is an accelerator index, not the resume record itself —
+      // degrade to "no known latest" rather than throwing (spec.md §25.2).
+      return null;
+    }
+    return this.load(pointer.jobId, options);
+  }
+
+  public async delete(jobId: string, options?: PortCallOptions): Promise<void> {
+    assertNotAborted(options, "checkpoint_delete");
+    await this.fs.remove(this.pathForJob(jobId), options);
+  }
+}