@react-native-harness/cache 1.4.0

package/dist/__tests__/warmth.test.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createHarnessCachePaths } from '../paths.js';
+import { isDomainWarm } from '../warmth.js';
+describe('isDomainWarm', () => {
+    let projectRoot;
+    beforeEach(() => {
+        projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-cache-'));
+    });
+    afterEach(() => {
+        fs.rmSync(projectRoot, { recursive: true, force: true });
+    });
+    it('is false when the domain directory does not exist', () => {
+        const paths = createHarnessCachePaths(projectRoot);
+        expect(isDomainWarm('metro', paths)).toBe(false);
+    });
+    it('is false when the domain directory exists but is empty', () => {
+        const paths = createHarnessCachePaths(projectRoot);
+        fs.mkdirSync(paths.metroTransform, { recursive: true });
+        expect(isDomainWarm('metro', paths)).toBe(false);
+    });
+    it('is true when the domain directory exists and has entries', () => {
+        const paths = createHarnessCachePaths(projectRoot);
+        fs.mkdirSync(paths.metroTransform, { recursive: true });
+        fs.writeFileSync(path.join(paths.metroTransform, 'entry'), 'data');
+        expect(isDomainWarm('metro', paths)).toBe(true);
+    });
+    it('is false when the path exists but is a file, not a directory', () => {
+        const paths = createHarnessCachePaths(projectRoot);
+        fs.mkdirSync(path.dirname(paths.metroTransform), { recursive: true });
+        fs.writeFileSync(paths.metroTransform, 'not a directory');
+        expect(isDomainWarm('metro', paths)).toBe(false);
+    });
+});

package/dist/domains/metro.d.ts

@@ -0,0 +1,8 @@
+export declare const METRO_KEY_FILENAMES: readonly string[];
+export declare const computeMetroStaticInputs: (options: {
+    projectRoot: string;
+    repoRoot: string;
+    bundlerMetroVersion: string;
+    salt?: string;
+}) => Record<string, string>;
+//# sourceMappingURL=metro.d.ts.map

package/dist/domains/metro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metro.d.ts","sourceRoot":"","sources":["../../src/domains/metro.ts"],"names":[],"mappings":"AA0DA,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAKhD,CAAC;AAgGF,eAAO,MAAM,wBAAwB,GAAI,SAAS;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAqCxB,CAAC"}

package/dist/domains/metro.js

@@ -0,0 +1,151 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '@react-native-harness/tools';
+const cacheLogger = logger.child('cache');
+// Metro resolves its own config by walking UP from the project root (see
+// Metro's loadConfig docs), never by scanning the tree downward. Lockfiles in
+// a monorepo live at the repo root, i.e. somewhere on projectRoot's ancestor
+// chain. So instead of a downward `hashFiles('**/…')`-style walk (which also
+// has to dodge node_modules/.git/dist/build to avoid vendored copies), we
+// walk upward from projectRoot to repoRoot (inclusive) and hash every
+// candidate key file that exists along that chain. Sibling workspace
+// packages are never on this chain, so their configs can't spuriously
+// invalidate this project's cache key.
+const LOCKFILE_NAMES = [
+    'bun.lock',
+    'bun.lockb',
+    'package-lock.json',
+    'npm-shrinkwrap.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+];
+// Metro config candidates: `metro.config.*` at the directory root, plus the
+// `.config/metro.*` directory convention Metro also resolves.
+const METRO_CONFIG_EXTENSIONS = [
+    'js',
+    'cjs',
+    'mjs',
+    'ts',
+    'cts',
+    'mts',
+    'json',
+];
+const METRO_CONFIG_NAMES = METRO_CONFIG_EXTENSIONS.map((extension) => `metro.config.${extension}`);
+const METRO_CONFIG_DIR_NAMES = METRO_CONFIG_EXTENSIONS.map((extension) => `.config/metro.${extension}`);
+// Babel only resolves root configs named `babel.config.*` (note: no `.ts` —
+// Babel does not resolve `babel.config.ts`). File-relative `.babelrc` and the
+// `package.json` `babel`/`metro` fields are intentionally out of scope.
+const BABEL_CONFIG_NAMES = [
+    'babel.config.json',
+    'babel.config.js',
+    'babel.config.cjs',
+    'babel.config.mjs',
+    'babel.config.cts',
+];
+// Relative-to-examined-directory paths checked at every directory on the
+// ancestor chain. All candidates that exist are hashed (rather than
+// emulating Metro/Babel's own first-match-wins resolution), which is
+// deterministic and strictly more conservative.
+export const METRO_KEY_FILENAMES = [
+    ...LOCKFILE_NAMES,
+    ...METRO_CONFIG_NAMES,
+    ...METRO_CONFIG_DIR_NAMES,
+    ...BABEL_CONFIG_NAMES,
+];
+/**
+ * Directories to examine: projectRoot and every ancestor directory up to and
+ * including repoRoot. Defensive: if projectRoot isn't inside repoRoot (or
+ * repoRoot can't be related to it), fall back to examining projectRoot alone
+ * rather than guessing.
+ */
+const collectAncestorDirectories = (projectRoot, repoRoot) => {
+    const resolvedProjectRoot = path.resolve(projectRoot);
+    const resolvedRepoRoot = path.resolve(repoRoot);
+    if (resolvedProjectRoot === resolvedRepoRoot) {
+        return [resolvedProjectRoot];
+    }
+    const relative = path.relative(resolvedRepoRoot, resolvedProjectRoot);
+    const isProjectRootInsideRepoRoot = relative !== '' &&
+        !relative.startsWith(`..${path.sep}`) &&
+        relative !== '..' &&
+        !path.isAbsolute(relative);
+    if (!isProjectRootInsideRepoRoot) {
+        return [resolvedProjectRoot];
+    }
+    const directories = [];
+    let current = resolvedProjectRoot;
+    for (;;) {
+        directories.push(current);
+        if (current === resolvedRepoRoot) {
+            break;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            // Reached the filesystem root without hitting repoRoot; defensive
+            // guard against an infinite loop.
+            break;
+        }
+        current = parent;
+    }
+    return directories;
+};
+const collectKeyFiles = (directories, repoRoot) => {
+    const matches = [];
+    for (const directory of directories) {
+        for (const candidate of METRO_KEY_FILENAMES) {
+            const fullPath = path.join(directory, candidate);
+            if (!fs.existsSync(fullPath) || !fs.statSync(fullPath).isFile()) {
+                continue;
+            }
+            matches.push({
+                relativePath: path
+                    .relative(repoRoot, fullPath)
+                    .split(path.sep)
+                    .join('/'),
+                content: fs.readFileSync(fullPath),
+            });
+        }
+    }
+    return matches;
+};
+const hashKeyFiles = (matches) => {
+    const hash = createHash('sha256');
+    for (const match of matches
+        .slice()
+        .sort((a, b) => (a.relativePath < b.relativePath ? -1 : 1))) {
+        hash.update(match.relativePath);
+        hash.update('\0');
+        hash.update(match.content);
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+};
+export const computeMetroStaticInputs = (options) => {
+    try {
+        const resolvedProjectRoot = path.resolve(options.projectRoot);
+        const resolvedRepoRoot = path.resolve(options.repoRoot);
+        // Validate both roots exist so a missing directory degrades to the
+        // always-miss fallback below instead of silently hashing zero files.
+        if (!fs.statSync(resolvedProjectRoot).isDirectory()) {
+            throw new Error(`projectRoot "${resolvedProjectRoot}" is not a directory`);
+        }
+        if (!fs.statSync(resolvedRepoRoot).isDirectory()) {
+            throw new Error(`repoRoot "${resolvedRepoRoot}" is not a directory`);
+        }
+        const directories = collectAncestorDirectories(resolvedProjectRoot, resolvedRepoRoot);
+        const matches = collectKeyFiles(directories, resolvedRepoRoot);
+        return {
+            lockfileHash: hashKeyFiles(matches),
+            bundlerMetroVersion: options.bundlerMetroVersion,
+            ...(options.salt ? { salt: options.salt } : {}),
+        };
+    }
+    catch (error) {
+        cacheLogger.warn(`Failed to compute Metro cache key inputs for "${options.projectRoot}". Falling back to an always-miss key.`, error);
+        return {
+            lockfileHash: 'unavailable',
+            bundlerMetroVersion: options.bundlerMetroVersion,
+        };
+    }
+};

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { type CacheDomainId, type HarnessCachePaths } from './paths.js';
+import { type CacheKeyInputs, type CacheSnapshot, type CacheSnapshotEntry, type DomainRestorePlan, type DomainSavePlan, type RestorePlan, type SavePlan, type SavePolicy } from './plan.js';
+import { computeMetroStaticInputs, METRO_KEY_FILENAMES } from './domains/metro.js';
+export { computeMetroStaticInputs, METRO_KEY_FILENAMES };
+export type { CacheDomainId, HarnessCachePaths };
+export type { CacheKeyInputs, CacheSnapshot, CacheSnapshotEntry, DomainRestorePlan, DomainSavePlan, RestorePlan, SavePlan, SavePolicy, };
+export interface HarnessCache {
+    readonly paths: HarnessCachePaths;
+    isWarm(domain: CacheDomainId): boolean;
+    ensureDomainDirectories(domain: CacheDomainId): void;
+    planRestore(inputs: Partial<Record<CacheDomainId, CacheKeyInputs>>): RestorePlan;
+    snapshot(): CacheSnapshot;
+    planSave(before: CacheSnapshot, policy: SavePolicy, inputs: Partial<Record<CacheDomainId, CacheKeyInputs>>): SavePlan;
+    writeKeysFile(plan: RestorePlan | SavePlan): void;
+}
+export declare const createHarnessCache: (options: {
+    projectRoot: string;
+}) => HarnessCache;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEnF,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,CAAC;AAEzD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,CAAC;AACjD,YAAY,EACV,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,UAAU,GACX,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC;IACvC,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IACrD,WAAW,CACT,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,GACrD,WAAW,CAAC;IACf,QAAQ,IAAI,aAAa,CAAC;IAC1B,QAAQ,CACN,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,GACrD,QAAQ,CAAC;IACZ,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,QAAQ,GAAG,IAAI,CAAC;CACnD;AAID,eAAO,MAAM,kBAAkB,GAAI,SAAS;IAC1C,WAAW,EAAE,MAAM,CAAC;CACrB,KAAG,YAwBH,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import { logger } from '@react-native-harness/tools';
+import { createHarnessCachePaths, getDomainDirectories, } from './paths.js';
+import { planRestore, planSave, snapshot, writeKeysFile, } from './plan.js';
+import { isDomainWarm } from './warmth.js';
+import { computeMetroStaticInputs, METRO_KEY_FILENAMES } from './domains/metro.js';
+export { computeMetroStaticInputs, METRO_KEY_FILENAMES };
+const cacheLogger = logger.child('cache');
+export const createHarnessCache = (options) => {
+    const paths = createHarnessCachePaths(options.projectRoot);
+    return {
+        paths,
+        isWarm: (domain) => isDomainWarm(domain, paths),
+        ensureDomainDirectories: (domain) => {
+            for (const directory of getDomainDirectories(domain, paths)) {
+                try {
+                    fs.mkdirSync(directory, { recursive: true });
+                }
+                catch (error) {
+                    cacheLogger.warn(`Failed to create cache directory "${directory}". Continuing with a cold cache.`, error);
+                }
+            }
+        },
+        planRestore: (inputs) => planRestore(paths, inputs),
+        snapshot: () => snapshot(paths),
+        planSave: (before, policy, inputs) => planSave(paths, before, policy, inputs),
+        writeKeysFile: (plan) => writeKeysFile(paths, plan),
+    };
+};

package/dist/paths.d.ts

@@ -0,0 +1,14 @@
+export type CacheDomainId = 'metro';
+export interface HarnessCachePaths {
+    readonly root: string;
+    readonly metroTransform: string;
+    readonly metroFileMap: string;
+}
+export declare const createHarnessCachePaths: (projectRoot: string) => HarnessCachePaths;
+/**
+ * Directories that make up a cache domain. `metro` covers both the transform
+ * cache and the file-map (haste) cache so `ensureDomainDirectories` prepares
+ * both ahead of a run.
+ */
+export declare const getDomainDirectories: (domain: CacheDomainId, paths: HarnessCachePaths) => readonly string[];
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC;AAEpC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,eAAO,MAAM,uBAAuB,GAClC,aAAa,MAAM,KAClB,iBAQF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,aAAa,EACrB,OAAO,iBAAiB,KACvB,SAAS,MAAM,EAOjB,CAAC"}

package/dist/paths.js

@@ -0,0 +1,26 @@
+import path from 'node:path';
+const HARNESS_DIRNAME = '.harness';
+const CACHE_DIRNAME = 'cache';
+const METRO_TRANSFORM_DIRNAME = 'metro';
+const METRO_FILE_MAP_DIRNAME = 'metro-file-map';
+export const createHarnessCachePaths = (projectRoot) => {
+    const root = path.join(projectRoot, HARNESS_DIRNAME, CACHE_DIRNAME);
+    return {
+        root,
+        metroTransform: path.join(root, METRO_TRANSFORM_DIRNAME),
+        metroFileMap: path.join(root, METRO_FILE_MAP_DIRNAME),
+    };
+};
+/**
+ * Directories that make up a cache domain. `metro` covers both the transform
+ * cache and the file-map (haste) cache so `ensureDomainDirectories` prepares
+ * both ahead of a run.
+ */
+export const getDomainDirectories = (domain, paths) => {
+    switch (domain) {
+        case 'metro':
+            return [paths.metroTransform, paths.metroFileMap];
+        default:
+            return [];
+    }
+};

package/dist/plan.d.ts

@@ -0,0 +1,54 @@
+import type { CacheDomainId, HarnessCachePaths } from './paths.js';
+export interface CacheKeyInputs {
+    os: string;
+    staticInputs: Record<string, string>;
+}
+export interface DomainRestorePlan {
+    paths: string[];
+    restoreKey: string;
+    restorePrefixes: string[];
+    accretive: boolean;
+}
+export interface RestorePlan {
+    version: 1;
+    domains: Partial<Record<CacheDomainId, DomainRestorePlan>>;
+}
+export interface CacheSnapshotEntry {
+    path: string;
+    sizeBytes: number;
+    mtimeMs: number;
+}
+export type CacheSnapshot = Partial<Record<CacheDomainId, CacheSnapshotEntry[]>>;
+export interface SavePolicy {
+    mode: 'default-branch' | 'always' | 'never';
+    isDefaultBranch: boolean;
+}
+export interface DomainSavePlan {
+    shouldSave: boolean;
+    saveKey: string;
+    delta: {
+        addedEntries: number;
+        removedEntries: number;
+        addedBytes: number;
+    };
+}
+export interface SavePlan {
+    version: 1;
+    domains: Partial<Record<CacheDomainId, DomainSavePlan>>;
+}
+export declare const planRestore: (paths: HarnessCachePaths, inputs: Partial<Record<CacheDomainId, CacheKeyInputs>>) => RestorePlan;
+/**
+ * Synchronous snapshot of on-disk cache contents, keyed by domain. Never
+ * throws: a domain whose directories cannot be read is reported as empty.
+ */
+export declare const snapshot: (paths: HarnessCachePaths) => CacheSnapshot;
+export declare const planSave: (paths: HarnessCachePaths, before: CacheSnapshot, policy: SavePolicy, inputs: Partial<Record<CacheDomainId, CacheKeyInputs>>) => SavePlan;
+/**
+ * Written to `<cache-root>/keys.json`, outside any domain's cached
+ * subdirectories, so it is never itself part of what gets restored/saved.
+ * It is a secondary/debug artifact; the actual data flow between CI steps
+ * goes through GITHUB_OUTPUT, not by re-reading this file. Cache I/O must
+ * never fail a run, so write failures are logged and swallowed.
+ */
+export declare const writeKeysFile: (paths: HarnessCachePaths, plan: RestorePlan | SavePlan) => void;
+//# sourceMappingURL=plan.d.ts.map

package/dist/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAOnE,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,iBAAiB,CAAC,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC;AAEjF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,gBAAgB,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC5C,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,CAAC;CACzD;AA+ED,eAAO,MAAM,WAAW,GACtB,OAAO,iBAAiB,EACxB,QAAQ,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,KACrD,WAqBF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,iBAAiB,KAAG,aAoBnD,CAAC;AAgDF,eAAO,MAAM,QAAQ,GACnB,OAAO,iBAAiB,EACxB,QAAQ,aAAa,EACrB,QAAQ,UAAU,EAClB,QAAQ,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,KACrD,QA0BF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,iBAAiB,EACxB,MAAM,WAAW,GAAG,QAAQ,KAC3B,IASF,CAAC"}

package/dist/plan.js

@@ -0,0 +1,177 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '@react-native-harness/tools';
+import { getDomainDirectories } from './paths.js';
+const cacheLogger = logger.child('cache');
+const KEYS_FILENAME = 'keys.json';
+const HASH_LENGTH = 16;
+const ALL_DOMAINS = ['metro'];
+/**
+ * Accretive domains only ever grow (transform/file-map caches keyed by
+ * content hash) so a save is always safe to key off the static hash plus a
+ * content hash, and prior saves can be found via a prefix match on the
+ * static hash. Non-accretive domains would need an exact key match instead.
+ * A domain not yet handled here defaults to non-accretive (exact-match),
+ * matching the safe-fallback style of `getDomainDirectories`/
+ * `getWarmthDirectory`: prefix-matching into an unknown domain's saves would
+ * not be a neutral no-op, so the conservative default is to require an exact
+ * key match rather than silently opt a future domain into accretive lookup.
+ */
+const isAccretiveDomain = (domain) => {
+    switch (domain) {
+        case 'metro':
+            return true;
+        default:
+            return false;
+    }
+};
+const hashSortedEntries = (entries) => createHash('sha256')
+    .update(entries
+    .slice()
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, value]) => `${key}=${value}`)
+    .join('\n'))
+    .digest('hex')
+    .slice(0, HASH_LENGTH);
+const buildStaticHashKey = (domain, inputs) => {
+    const hash = hashSortedEntries(Object.entries(inputs.staticInputs));
+    return `harness-${domain}-${inputs.os}-${hash}`;
+};
+const buildContentHash = (entries) => hashSortedEntries(entries.map((entry) => [entry.path, String(entry.sizeBytes)]));
+const walkDirectory = (root, directory, entries) => {
+    let dirents;
+    try {
+        dirents = fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        // Missing/unreadable directory is treated as empty rather than an error.
+        return;
+    }
+    for (const dirent of dirents) {
+        const fullPath = path.join(directory, dirent.name);
+        if (dirent.isDirectory()) {
+            walkDirectory(root, fullPath, entries);
+        }
+        else if (dirent.isFile()) {
+            const stat = fs.statSync(fullPath);
+            entries.push({
+                path: path.relative(root, fullPath),
+                sizeBytes: stat.size,
+                mtimeMs: stat.mtimeMs,
+            });
+        }
+    }
+};
+export const planRestore = (paths, inputs) => {
+    const domains = {};
+    for (const domain of ALL_DOMAINS) {
+        const domainInputs = inputs[domain];
+        if (!domainInputs) {
+            continue;
+        }
+        const restoreKey = buildStaticHashKey(domain, domainInputs);
+        const accretive = isAccretiveDomain(domain);
+        domains[domain] = {
+            paths: [...getDomainDirectories(domain, paths)],
+            restoreKey,
+            restorePrefixes: accretive ? [`${restoreKey}-`] : [],
+            accretive,
+        };
+    }
+    return { version: 1, domains };
+};
+/**
+ * Synchronous snapshot of on-disk cache contents, keyed by domain. Never
+ * throws: a domain whose directories cannot be read is reported as empty.
+ */
+export const snapshot = (paths) => {
+    const result = {};
+    for (const domain of ALL_DOMAINS) {
+        try {
+            const entries = [];
+            for (const directory of getDomainDirectories(domain, paths)) {
+                walkDirectory(paths.root, directory, entries);
+            }
+            result[domain] = entries;
+        }
+        catch (error) {
+            cacheLogger.warn(`Failed to snapshot cache domain "${domain}". Treating as empty.`, error);
+            result[domain] = [];
+        }
+    }
+    return result;
+};
+const diffSnapshots = (before, after) => {
+    const beforeByPath = new Map(before.map((entry) => [entry.path, entry]));
+    const afterByPath = new Map(after.map((entry) => [entry.path, entry]));
+    let addedEntries = 0;
+    let removedEntries = 0;
+    let addedBytes = 0;
+    for (const [entryPath, afterEntry] of afterByPath) {
+        const beforeEntry = beforeByPath.get(entryPath);
+        if (!beforeEntry || beforeEntry.sizeBytes !== afterEntry.sizeBytes) {
+            addedEntries += 1;
+            addedBytes += afterEntry.sizeBytes;
+        }
+    }
+    for (const entryPath of beforeByPath.keys()) {
+        if (!afterByPath.has(entryPath)) {
+            removedEntries += 1;
+        }
+    }
+    return { addedEntries, removedEntries, addedBytes };
+};
+const shouldSaveForPolicy = (policy, delta) => {
+    if (delta.addedEntries + delta.removedEntries === 0) {
+        return false;
+    }
+    switch (policy.mode) {
+        case 'always':
+            return true;
+        case 'default-branch':
+            return policy.isDefaultBranch;
+        case 'never':
+            return false;
+    }
+};
+export const planSave = (paths, before, policy, inputs) => {
+    const after = snapshot(paths);
+    const domains = {};
+    for (const domain of ALL_DOMAINS) {
+        const domainInputs = inputs[domain];
+        if (!domainInputs) {
+            continue;
+        }
+        const beforeEntries = before[domain] ?? [];
+        const afterEntries = after[domain] ?? [];
+        const delta = diffSnapshots(beforeEntries, afterEntries);
+        const staticHashKey = buildStaticHashKey(domain, domainInputs);
+        const accretive = isAccretiveDomain(domain);
+        domains[domain] = {
+            shouldSave: shouldSaveForPolicy(policy, delta),
+            saveKey: accretive
+                ? `${staticHashKey}-${buildContentHash(afterEntries)}`
+                : staticHashKey,
+            delta,
+        };
+    }
+    return { version: 1, domains };
+};
+/**
+ * Written to `<cache-root>/keys.json`, outside any domain's cached
+ * subdirectories, so it is never itself part of what gets restored/saved.
+ * It is a secondary/debug artifact; the actual data flow between CI steps
+ * goes through GITHUB_OUTPUT, not by re-reading this file. Cache I/O must
+ * never fail a run, so write failures are logged and swallowed.
+ */
+export const writeKeysFile = (paths, plan) => {
+    const filePath = path.join(paths.root, KEYS_FILENAME);
+    try {
+        fs.mkdirSync(paths.root, { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(plan, null, 2));
+    }
+    catch (error) {
+        cacheLogger.warn(`Failed to write cache keys file "${filePath}".`, error);
+    }
+};