@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/lab/module/src/module-lab-source.js

@@ -0,0 +1,50 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, realpathSync } from "node:fs";
+import { register } from "node:module";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { sourceFingerprint } from "./source-fingerprint.js";
+const hookRoots = new Set();
+function registerReloadHook(root) {
+    const real = realpathSync(root);
+    if (hookRoots.has(real))
+        return;
+    hookRoots.add(real);
+    register(new URL("./reload-hook.mjs", import.meta.url), { data: { roots: [real] } });
+}
+export class ModuleLabSource {
+    options;
+    path;
+    root;
+    generation = 0;
+    fingerprint;
+    constructor(configPath, options = {}) {
+        this.options = options;
+        this.path = resolve(configPath);
+        this.root = dirname(this.path);
+    }
+    changed() {
+        return this.fingerprint !== undefined && sourceFingerprint(this.root) !== this.fingerprint;
+    }
+    async load() {
+        const { path, root } = this;
+        if (!existsSync(path))
+            throw new Error(`No lab configuration at ${path}. Pass --config <lab.config.ts> or start the server in the consumer's directory.`);
+        const generation = this.generation++;
+        if (generation > 0 && this.options.reload)
+            registerReloadHook(root);
+        this.fingerprint = sourceFingerprint(root);
+        const url = pathToFileURL(path).href + (generation > 0 && this.options.reload ? `?product-lab-generation=${generation}` : "");
+        const module = (await import(__rewriteRelativeImportExtension(url)));
+        return module.default;
+    }
+}

package/adapters/lab/module/src/reload-hook.mjs

@@ -0,0 +1,24 @@
+// Module resolve hook for `product-lab mcp` lab reloads (registered by load.ts).
+// A reload imports lab.config.ts with `?product-lab-generation=N`; this hook
+// gives the same parameter to every file that module graph imports from inside
+// the lab's directory (never node_modules), so edited integration, topology and
+// step files are evaluated again while product-lab itself and every dependency
+// stay single instances (the core relies on instanceof checks).
+import { URL } from "node:url";
+
+const roots = new Set();
+
+export async function initialize(data) {
+  for (const root of data?.roots ?? []) roots.add(root.endsWith("/") ? root : `${root}/`);
+}
+
+export async function resolve(specifier, context, next) {
+  const result = await next(specifier, context);
+  if (!context.parentURL || !result.url.startsWith("file:")) return result;
+  const generation = new URL(context.parentURL).searchParams.get("product-lab-generation");
+  if (!generation) return result;
+  const url = new URL(result.url);
+  if (url.pathname.includes("/node_modules/") || ![...roots].some((root) => url.pathname.startsWith(root))) return result;
+  url.searchParams.set("product-lab-generation", generation);
+  return { ...result, url: url.href };
+}

package/adapters/lab/module/src/source-fingerprint.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Fingerprint of a lab's own source files (under its directory; dot
+ * directories, node_modules, dist and __baselines__ skipped): path, size and
+ * mtime. A change means lab.config.ts or something it imports may have been
+ * edited. Only source files (and links, to learn what they point at) are
+ * statted: images, logs and other output beside the lab are never read.
+ */
+export declare function sourceFingerprint(root: string): string;

package/adapters/lab/module/src/source-fingerprint.js

@@ -0,0 +1,48 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+const SOURCE = /\.(ts|mts|cts|js|mjs|cjs|json)$/;
+const MAX_FINGERPRINT_ENTRIES = 20_000;
+const NOT_SOURCE = new Set(["node_modules", "dist", "__baselines__"]);
+export function sourceFingerprint(root) {
+    const hash = createHash("sha256");
+    let entries = 0;
+    const walk = (dir) => {
+        let found;
+        try {
+            found = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        }
+        catch {
+            return;
+        }
+        for (const entry of found) {
+            if (++entries > MAX_FINGERPRINT_ENTRIES)
+                return;
+            const name = entry.name;
+            if (name.startsWith(".") || NOT_SOURCE.has(name) || name.endsWith(".tsbuildinfo"))
+                continue;
+            const path = join(dir, name);
+            if (entry.isDirectory()) {
+                walk(path);
+                continue;
+            }
+            if (!entry.isSymbolicLink() && !(entry.isFile() && SOURCE.test(name)))
+                continue;
+            let stat;
+            try {
+                stat = statSync(path);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory())
+                walk(path);
+            else if (SOURCE.test(name))
+                hash.update(`${path}\0${stat.size}\0${stat.mtimeMs}\n`);
+        }
+    };
+    walk(root);
+    return hash.digest("hex");
+}

package/adapters/lab/module/src/transpiled-client-bundles.d.ts

@@ -0,0 +1,8 @@
+import type { ClientBundleCheck, ClientBundleChecker } from "@parity/product-lab/ports/lab";
+/** The JavaScript the panel serves for a module file. */
+export declare function transpileClientModule(source: string, fileName?: string): string;
+/** The runtime imports of transpiled code (type-only and unused imports are gone). */
+export declare function runtimeImports(code: string): string[];
+export declare class TranspiledClientBundles implements ClientBundleChecker {
+    check(file: string, secret: (text: string) => boolean): ClientBundleCheck;
+}

package/adapters/lab/module/src/transpiled-client-bundles.js

@@ -0,0 +1,57 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+import { JsxEmit, ModuleKind, ScriptTarget, transpileModule } from "typescript";
+const SPECIFIERS = /(?:\bimport|\bexport)\s*(?:[^'"()]*?\bfrom\s*)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+export function transpileClientModule(source, fileName = "module.ts") {
+    return transpileModule(source, { fileName, compilerOptions: { target: ScriptTarget.ES2022, module: ModuleKind.ESNext, jsx: JsxEmit.React, jsxFactory: "React.createElement", jsxFragmentFactory: "React.Fragment" } }).outputText;
+}
+export function runtimeImports(code) {
+    return [...code.matchAll(SPECIFIERS)].map((match) => (match[1] ?? match[2]));
+}
+export class TranspiledClientBundles {
+    check(file, secret) {
+        const root = dirname(file);
+        const files = [];
+        const problems = [];
+        let realRoot;
+        try {
+            realRoot = realpathSync(root);
+        }
+        catch {
+            return { root, files: [], refused: `its folder ${root} does not exist` };
+        }
+        const visit = (path, from) => {
+            let real;
+            try {
+                real = realpathSync(path);
+            }
+            catch {
+                problems.push(`${from} imports ${relative(realRoot, path) || path}, which does not exist`);
+                return;
+            }
+            const inside = relative(realRoot, real);
+            if (inside.startsWith(`..${sep}`) || inside === ".." || inside.startsWith(sep)) {
+                problems.push(`${from} imports ${real}, outside its UI folder ${root}: server-side code (services, signers, secrets) never enters a client bundle`);
+                return;
+            }
+            if (files.includes(inside))
+                return;
+            files.push(inside);
+            const text = readFileSync(real, "utf8");
+            if (secret(text))
+                problems.push(`${inside} contains one of the lab's secret values`);
+            for (const specifier of runtimeImports(transpileClientModule(text, real))) {
+                if (!specifier.startsWith("./") && !specifier.startsWith("../")) {
+                    problems.push(`${inside} imports the package ${specifier}: a client bundle imports only files of its own UI folder (no signer, chain or lab packages)`);
+                    continue;
+                }
+                const target = resolve(dirname(real), specifier);
+                visit([target, `${target}.ts`, `${target}.tsx`, `${target}.js`, `${target}.jsx`].find((candidate) => existsSync(candidate)) ?? target, inside);
+            }
+        };
+        visit(file, relative(root, file) || file);
+        return problems.length ? { root, files: [], refused: problems.join("; ") } : { root, files };
+    }
+}

package/adapters/notify/file/README.md

@@ -0,0 +1,5 @@
+# Local notification adapter
+
+`@product-lab/notify-file` exports `FileNotifier` and `NoopNotifier`, implementations of `Notifier` from `@product-lab/ports/notify`. `FileNotifier(directory)` writes one Markdown and JSON pair per notification key and records receipts in `sent.json`; repeated sends of the same run pair return `duplicate`, while a later recurrence after recovery has a new key. `NoopNotifier` returns `skipped`. No network is used.
+
+This provider depends on core domain/port packages. Composition, tools and examples may construct it; core and entrypoints must use the port. The directory is intended for one writer at a time; cross-process concurrent delivery is not supported. Test with `bunx nx run notify-file:test`; lint/typecheck use the same project targets.

package/adapters/notify/file/src/file-notifier.d.ts

@@ -0,0 +1,11 @@
+import type { CompatibilityNotification } from "@parity/product-lab/domain/suites";
+import type { Notifier, NotifierReceipt } from "@parity/product-lab/ports/notify";
+export declare class FileNotifier implements Notifier {
+    readonly directory: string;
+    private readonly now;
+    readonly id = "file";
+    constructor(directory: string, now?: () => Date);
+    send(notification: CompatibilityNotification): Promise<NotifierReceipt>;
+    private index;
+    private write;
+}

package/adapters/notify/file/src/file-notifier.js

@@ -0,0 +1,45 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const slug = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "row";
+export class FileNotifier {
+    directory;
+    now;
+    id = "file";
+    constructor(directory, now = () => new Date()) {
+        this.directory = directory;
+        this.now = now;
+    }
+    async send(notification) {
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        const hash = createHash("sha256").update(notification.key).digest("hex");
+        const index = this.index();
+        const earlier = index.sent[hash];
+        if (earlier)
+            return { status: "duplicate", location: join(this.directory, earlier.file) };
+        const at = this.now();
+        const base = `${at.toISOString().replace(/[:.]/g, "-")}-${slug(notification.product)}-${slug(notification.suite)}-${slug(notification.row)}-${hash.slice(0, 12)}`;
+        const markdown = join(this.directory, `${base}.md`);
+        writeFileSync(markdown, `${notification.markdown.trimEnd()}\n`, { mode: 0o600 });
+        writeFileSync(join(this.directory, `${base}.json`), `${JSON.stringify({ sentAt: at.toISOString(), notifier: this.id, ...notification }, null, 2)}\n`, { mode: 0o600 });
+        this.write({ ...index, sent: { ...index.sent, [hash]: { file: `${base}.md`, at: at.toISOString(), title: notification.title } } });
+        return { status: "sent", location: markdown };
+    }
+    index() {
+        const file = join(this.directory, "sent.json");
+        if (!existsSync(file))
+            return { kind: "product-lab-sent-notifications", schemaVersion: 1, sent: {} };
+        const data = JSON.parse(readFileSync(file, "utf8"));
+        if (data.kind !== "product-lab-sent-notifications" || data.schemaVersion !== 1 || typeof data.sent !== "object")
+            throw new Error(`${file} is not a product-lab notification index; move it away or choose another directory`);
+        return data;
+    }
+    write(index) {
+        const file = join(this.directory, "sent.json");
+        const temporary = `${file}.${process.pid}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify(index, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temporary, file);
+    }
+}

package/adapters/notify/file/src/index.d.ts

@@ -0,0 +1,2 @@
+export { FileNotifier } from "./file-notifier.js";
+export { NoopNotifier } from "./noop-notifier.js";

package/adapters/notify/file/src/index.js

@@ -0,0 +1,4 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { FileNotifier } from "./file-notifier.js";
+export { NoopNotifier } from "./noop-notifier.js";

package/adapters/notify/file/src/noop-notifier.d.ts

@@ -0,0 +1,6 @@
+import type { CompatibilityNotification } from "@parity/product-lab/domain/suites";
+import type { Notifier, NotifierReceipt } from "@parity/product-lab/ports/notify";
+export declare class NoopNotifier implements Notifier {
+    readonly id = "none";
+    send(_notification: CompatibilityNotification): Promise<NotifierReceipt>;
+}

package/adapters/notify/file/src/noop-notifier.js

@@ -0,0 +1,8 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export class NoopNotifier {
+    id = "none";
+    async send(_notification) {
+        return { status: "skipped" };
+    }
+}

package/adapters/storage/filesystem/README.md

@@ -0,0 +1,41 @@
+# @product-lab/storage-filesystem
+
+File-system storage (refactor step 1).
+
+| Class | Implements | Notes |
+| --- | --- | --- |
+| `NodeFileSystem` | `FileSystem` ([`@product-lab/ports/system`](../../../core/ports/src/driven/system/file-system.d.ts)) | private directories (0700); `writePrivateJson` and `writePrivateBytes` atomic (temporary file, fsync, rename) and 0600; `readText` and `listDirectory` serve injected adapter file reads; moved from core's `workspaces/files.ts` |
+| `WorkspaceStore<T>` | (storage for the manual workspace) | moved from core's `workspaces/store.ts`; takes `FileSystem`, `LockManager` and `IdGenerator` |
+| `FileEvidenceJournal` | `EvidenceJournal` ([`@product-lab/ports/storage`](../../../core/ports/src/driven/storage/evidence-journal.d.ts)) | `<directory>/timeline.jsonl` (file name configurable), one JSON line per entry, `bigint` as a decimal string, mode 0600; `open()` creates the private directory. The file half of core's `ScenarioJournal`, moved in step 1 |
+| `FileRunManifestStore` | `RunManifestStore` ([`@product-lab/ports/storage`](../../../core/ports/src/driven/storage/run-manifest-store.d.ts)) | `record(environment, manifest)` writes `<directory>/<environment>-<ISO time>-<run id prefix>/run-manifest.json` through `FileSystem.writePrivateJson` (atomic, 0600, private parents) and returns the path; `writeTo(path, manifest)` writes one where asked. Takes `FileSystem`, the directory (conventionally `<lab root>/.product-lab/runs`), `Clock` and `IdGenerator`. `compileLab` records through it |
+| `FileRecordingStore` | `RecordingStore` ([`@product-lab/ports/recording`](../../../core/ports/src/driven/recording/recording-store.d.ts), Phase 9) | `<directory>/<id>/recording.json` and `frames/<frame>.png` (directories 0700, files 0600), written into `.pending-*` and renamed so a reader never sees half a recording; `read` validates with the domain's `RunRecording.from` and refuses an id or frame file that names a path; retention (`RecordingRetention`) runs after every write; `list` names unreadable recordings instead of failing Videos (backlog 18b): `<directory>/videos/<name>`, shared by the recordings of the scenarios one page lived through; `videos/` is never read as a recording, and retention removes a video with the last recording that names it (one no recording names is left; video bytes are not counted in the size limit). Backlog 192: other files kept with a recording (`save`'s `files`: its host logs) go under it, one folder deep (`hosts/<file>`), written with it; a path that leaves its folder is refused |
+| `FileVisualBaselines` | `VisualBaselines` ([`@product-lab/ports/recording`](../../../core/ports/src/driven/recording/step-check-ports.d.ts), backlog 40) | `FileVisualBaselines(labRoot)`: a baseline is a `.png` at a lab-relative path (the domain's `baselinePath`: `<feature dir>/__baselines__/<feature>/<scenario>/<host kind>/<step>-<actor>.png`), written whole through a temporary file and renamed; `evidence` keeps a check's actual image, diff (`.png`) or scan (`.json`) under `<lab>/.product-lab/visual/` and returns its path. An absolute path, one that leaves the lab or another file type is refused. Tests: `tests/file-visual-baselines.test.ts`. |
+| `FileJourneyDocs` | `JourneyDocsStore` ([`@product-lab/ports/recording`](../../../core/ports/src/driven/recording/journey-docs-store.d.ts), backlog 47) | `<out>/README.md` (index), `<out>/<slug>/README.md` and `step-<n>.png`, each written to a temporary name and renamed; unchanged files left alone; `<out>/.product-lab-journeys.json` lists what it wrote, so a later write removes its own stale files and refuses, before writing anything, to replace a file it did not write. Tests: `tests/file-journey-docs.test.ts`. |
+| `FileBreakpointStore`, `FileFixtureStore` | `FixtureStore` ([`@product-lab/ports/storage`](../../../core/ports/src/driven/storage/fixture-store.d.ts), fixtures) | `<root>/<name>/fixture.json` beside `environment/` and `session/`. `stage(name)` works in `<name>.partial-<id>` and `commit(record)` renames it into place (an earlier save moves aside, then goes), so a failed save leaves the earlier one; `digest(root, patterns)` hashes the matching files' paths and bytes (sha256; `node_modules` skipped); `text(root, path)` (backlog 35b) reads a fixture's setup feature inside the lab, so the characters it makes join the key; `copyTrees` and `replaceTrees` copy through the `TreeCloner` port, `replaceTrees` moving each target aside (`.replaced-<id>`) until `commit` or `rollback`; `setAside(targets)` (30 September 2026, `fixture refresh`'s rebuild) moves each existing target to `.before-rebuild-<id>` so the next start makes a fresh one, `commit` deleting and `rollback` restoring them. Takes the root (the composition root gives `<lab root>/.product-lab/fixtures`), a `TreeCloner` and an `IdGenerator` |
+| `FileRpcChoices` | `RpcChoices` ([`@product-lab/ports/storage`](../../../core/ports/src/driven/storage/rpc-choices.d.ts), 3 October 2026) | `<lab>/.product-lab/state/rpc.json`: the RPC per chain a person chose in the lab window, per environment, with its reason; plain URLs only (`rpcLiteralErrors` refuses one with credentials before writing, naming the field), written whole and atomically, directory 0700, file 0600; `clear(environment)`. Test: `tests/file-rpc-choices.test.ts` |
+| `FileEnvironmentOptionChoices` | `EnvironmentOptionChoices` ([`@product-lab/ports/storage`](../../../core/ports/src/driven/storage/environment-option-choices.d.ts), backlog 184) | `<lab>/.product-lab/state/environment-options.json`: the option a person last chose per environment (`{ "paseo-copy": "light" }`), written whole and atomically, directory 0700, file 0600; a damaged file is refused on read, naming it, and replaced by the next choice. Test: `tests/file-environment-option-choices.test.ts` |
+| `LockRunningLabRecord` | `RunningLabRecord` ([`@product-lab/ports/storage`](../../../core/ports/src/driven/storage/running-lab.d.ts), B1 step a, backlog B2) | The lab running in a folder as a lock (`<lab>/.product-lab/running/<config name>`, its `owner.json` the record; one per configuration): one claim wins, the lock's own liveness check (pid and start time) makes a dead holder's record stale, and `read()` never names this process's own and creates nothing (no record directory, or no folder, is no running lab). B1: `claim()` writes a token new at every start (`accessToken`, `owner.json` mode 600) that the window's runtime API asks for. Test: `tests/lock-running-lab-record.test.ts`; on disk with a second process, `composition/tests/running-lab.test.ts`; `others()` reads the records beside it (the folder's other configurations that run) |
+| `FileBreakpointStore` | `BreakpointStore` ([`@product-lab/ports/storage`](../../../core/ports/src/driven/storage/breakpoint-store.d.ts), backlog 17) | `<lab>/.product-lab/breakpoints.json`: read (missing is empty), written whole and atomically (temporary file, rename), directory 0700, file 0600 (`FileJsonDocument`, `src/file-json-document.ts`). Test: `tests/file-breakpoint-store.test.ts` |
+| `FileLabSettingsStore` | `LabSettingsStore` ([`@product-lab/ports/storage`](../../../core/ports/src/driven/storage/lab-settings-store.d.ts), panel Settings) | `<lab>/.product-lab/settings.json`, the same `FileJsonDocument` storage. Test: `tests/file-breakpoint-store.test.ts` |
+| `FileLockStore` | `LockStore` ([`@product-lab/ports/versions`](../../../core/ports/src/driven/versions/lock-store.d.ts), Phase 6) | `lab.lock.json`: `read()` parses it strictly with the domain's `LabLock.parse` (every problem listed, prefixed with the path) and returns it with its digest (`lockDigest`: sha256 of the canonical JSON, so formatting does not change it); `write(lock, expected)` is a compare-and-swap against the digest the caller read (or `absent`), refusing with `VersionError` `lock-conflict` and leaving the file as it was, then writes through `writePrivateJson` (atomic, 0600). With an optional `LockManager` the check and write also exclude other processes (`<lock>.write-lock`) |
+
+`WorkspaceStore` is an exclusive manual workspace: `new WorkspaceStore(directory, binding, { files, locks, ids }).open()` takes `<directory>/owner.lock` (a lock left by a dead lab process is taken over; an incomplete one is refused for inspection) and loads `workspace.json`, refusing one saved for another chain generation (`binding`). `close()` releases the lock only if this store still holds it; the data stays.
+
+`@product-lab/storage-filesystem/running-lab` (`src/running-lab.ts`) exports `LockRunningLabRecord` and `NodeFileSystem` alone: the index loads the domain, and `product-lab mcp` reads the running-lab record before it loads the lab (entrypoints/mcp/README.md, "Start").
+
+Exports (`src/index.ts`): `NodeFileSystem`, `WorkspaceStore`, `WorkspaceManifest`, `WorkspaceStoreDependencies`, `FileEvidenceJournal`, `FileRunManifestStore`, `FileLockStore`, `lockDigest`, `FileSuiteEvidenceBundles`, `FileRecordingStore`, `FileVisualBaselines`, `FileFixtureStore`, `FileFixtureArchives` (with `BundleContentError`, `BUNDLE_MANIFEST`, `bundlePartName`), `DirectoryFixtureSource`, `FileRunBundleArchives`: fixture bundles (30 September 2026): a saved fixture's directory streamed into a POSIX tar, zstd-compressed (node:zlib) and cut into parts beside an index (`<name>.tar.zst.001`, …; at most `partBytes` each), every file's size and sha256 taken while it streams and the manifest archived last; `unpack` checks every part and every file while it extracts and refuses (removing what it wrote) a changed or missing part, a file whose checksum differs, a file the index does not list or lacks, and an entry or link outside the bundle. Links (28 October 2026, security review F1: two chained links each passed a check read as text, and a file written through the second landed outside the target): nothing a bundle holds may write or point outside the target. Every link is created last, after every file and folder, and each folder on the way to an entry must be a real folder on disk (`lstat`), so nothing is written through a link; an entry at or under a link's path, or a link at a taken path, is refused; a link must stay inside the target read as text, and once all links exist, the folders its target passes through must be real folders, so a link through another link is refused (`tests/tar-archive.test.ts`). `DirectoryFixtureSource(id, directory)` (`FixtureSource`, the same record): a directory of published bundles and their catalog (`manifest.json`), such as a shared drive. `download` copies each file into the cache and checks its size and sha256 while it streams; a cached file that still checks out is kept, and a mismatch is refused with the partial file removed. `publish` copies a bundle in and then replaces the catalog atomically. A directory carries no build attestation.
+
+`FileRunBundleArchives` (`RunBundleArchives`, backlog 20, 3 October 2026): a run bundle is one file, `<id>.plbundle`, a zstd-compressed POSIX tar (`tar --zstd -xf` opens it) whose first entry is the index `bundle.json`. `write` hashes every entry before archiving so the index can list them all and come first, refuses an entry that changes while it is archived, and writes beside the target then renames, so a bundle is never half written. `readIndex` decompresses only until the index ends (a bundle damaged further on still shows its index). `extract` checks every entry's size and sha256 against the index, refuses an unlisted, missing or escaping entry, a link or a folder entry (a run bundle holds files only), and a bundle that does not start with its index, and removes what it wrote. The tar code (ustar and PAX headers, the entry walk, the checking extractor) is shared with `FileFixtureArchives` in `src/tar-archive.ts`; moving it there changed nothing fixture bundles write or accept (their tests unchanged, and the same parts byte for byte).
+
+| | |
+| --- | --- |
+| Nx project | `storage-filesystem` |
+| Tags | `scope:provider`, `type:adapter` |
+| Depends on | `@product-lab/ports`; `@product-lab/domain` (since Phase 6, for `LabLock`) |
+| Used by | the composition root (`composition/src/node-system.ts`: `NodeFileSystem` and a `FileRunManifestStore` as `SystemPorts.runManifests`, which the environment adapters write their run manifests through) and `tools/verify` (`src/node-system.ts`, the same bundle); `examples/notes` and another example (`FileEvidenceJournal`; the other also `WorkspaceStore`), `tools/eval` (`FileEvidenceJournal`, through `@parity/product-lab/storage-filesystem`); other adapters take the `FileSystem` and `RunManifestStore` ports instead of importing this package |
+
+Tests: `bunx nx run storage-filesystem:test` (real disk for `NodeFileSystem`, `FileEvidenceJournal`, `FileRunManifestStore`, `FileLockStore` and `FileRecordingStore` (`tests/file-recording-store.test.ts`: private whole writes, retention on write, refused paths, unreadable recordings) and `FileFixtureStore` (`tests/file-fixture-store.test.ts`: commit, a failed save keeping the earlier one, digests, replace and rollback) and `DirectoryFixtureSource` (`tests/directory-fixture-source.test.ts`: publish, a checked download and a cache hit; a changed or missing file) and `FileFixtureArchives` (`tests/file-fixture-archives.test.ts`: a round trip with modes, a long path, an empty file, a link and parts split at the limit; the tampering controls above) and `FileRunBundleArchives` (`tests/file-run-bundle-archives.test.ts`: a round trip with the index first, also through plain `tar`; the index read from a bundle damaged further on; checksum, size, unlisted and missing entries, an escaping or index-named entry, a link or a folder entry, a file that is not a bundle, a non-empty target) and the tar extractor's links (`tests/tar-archive.test.ts`: chained links that climb out of the target, a file under a link, a link through a link, a link replaced by a later entry, hard and absolute links, and inside links that still extract); an in-memory lock for `WorkspaceStore`). With `FileLockManager` on disk and after a crashed owner: `tools/verify/tests/system-adapters.test.ts`.
+
+`FileSuiteEvidenceBundles` implements the optional suite evidence port: begin a fresh per-suite namespace under a reusable report directory, capture the exact resolution, seal completed report/receipt files, and read bounded digest-checked files with canonical containment. It never resolves versions or writes a version lock. `tests/suite-evidence-bundles.test.ts` covers repeated report directories, stale cross-suite references, immutable namespaces, changed manifests, cross-row references, symlink escape and oversized files.
+
+Receipts are stored under `.lock-bump-evidence/<suite-id>/<row-id>`; the current suite report selects its own immutable bundle. Reusing a suite ID refuses rather than overwriting evidence. `read` throws `SuiteEvidenceError` (`@product-lab/domain/suites`) with a `code` and the `evidence` file it concerns (a tampered receipt, resolution or report is `digest-mismatch` naming which; another row's reference `foreign-row`, another suite run's `foreign-suite`, a path out of the suite `escape`, a missing suite record or namespace `missing`), so the lock proposal (`ProposeLock` in `@product-lab/application`, G2) branches on fields, never on text. This adapter proposes and writes nothing.

package/adapters/storage/filesystem/src/directory-fixture-source.d.ts

@@ -0,0 +1,19 @@
+import type { FixtureDownload, FixtureSource, FixtureSourceFiles } from "@parity/product-lab/ports/storage";
+export declare class DirectoryFixtureSource implements FixtureSource {
+    readonly id: string;
+    /** The source directory (absolute). */
+    readonly directory: string;
+    readonly kind: "directory";
+    constructor(id: string, 
+    /** The source directory (absolute). */
+    directory: string);
+    get location(): string;
+    catalog(): Promise<unknown>;
+    download(files: FixtureSourceFiles, directory: string, options?: {
+        signal?: AbortSignal;
+        progress?: (bytes: number) => void;
+    }): Promise<FixtureDownload>;
+    publish(index: string, files: FixtureSourceFiles, catalog: unknown, signal?: AbortSignal): Promise<{
+        written: string[];
+    }>;
+}

package/adapters/storage/filesystem/src/directory-fixture-source.js

@@ -0,0 +1,83 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { BundleContentError } from "./file-fixture-archives.js";
+const CATALOG = "manifest.json";
+async function sha256Of(file) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(file))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+async function copyChecked(from, to, expected, signal) {
+    if (existsSync(to) && (expected.bytes === undefined || statSync(to).size === expected.bytes) && (await sha256Of(to)) === expected.sha256)
+        return 0;
+    if (!existsSync(from))
+        throw new BundleContentError(`${basename(from)} is not in the source directory ${dirname(from)}`);
+    const size = statSync(from).size;
+    if (expected.bytes !== undefined && size !== expected.bytes)
+        throw new BundleContentError(`${basename(from)} is ${size} bytes in the source; its catalog says ${expected.bytes}`);
+    const partial = `${to}.partial`;
+    const hash = createHash("sha256");
+    const source = createReadStream(from);
+    source.on("data", (chunk) => hash.update(chunk));
+    await pipeline(source, createWriteStream(partial, { mode: 0o644 }), ...(signal ? [{ signal }] : []));
+    const sha256 = hash.digest("hex");
+    if (sha256 !== expected.sha256) {
+        rmSync(partial, { force: true });
+        throw new BundleContentError(`${basename(from)} does not match its checksum (sha256 ${sha256.slice(0, 12)}…, the catalog says ${expected.sha256.slice(0, 12)}…)`);
+    }
+    renameSync(partial, to);
+    return size;
+}
+export class DirectoryFixtureSource {
+    id;
+    directory;
+    kind = "directory";
+    constructor(id, 
+    directory) {
+        this.id = id;
+        this.directory = directory;
+    }
+    get location() {
+        return this.directory;
+    }
+    async catalog() {
+        const file = join(this.directory, CATALOG);
+        if (!existsSync(file))
+            return undefined;
+        try {
+            return JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch (error) {
+            throw new Error(`${file} is not a fixture catalog (not JSON)`, { cause: error });
+        }
+    }
+    async download(files, directory, options = {}) {
+        mkdirSync(directory, { recursive: true });
+        let fetchedBytes = 0;
+        const entries = [{ file: files.index, sha256: files.indexSha256 }, ...files.parts.map((part) => ({ ...part }))];
+        for (const entry of entries) {
+            fetchedBytes += await copyChecked(join(this.directory, entry.file), join(directory, entry.file), entry, options.signal);
+            options.progress?.(fetchedBytes);
+        }
+        return { index: join(directory, files.index), fetchedBytes, attestation: { status: "unavailable", reason: "a directory source carries no build attestation" } };
+    }
+    async publish(index, files, catalog, signal) {
+        mkdirSync(this.directory, { recursive: true });
+        const written = [];
+        for (const entry of [{ file: files.index, sha256: files.indexSha256 }, ...files.parts]) {
+            const target = join(this.directory, entry.file);
+            await copyChecked(join(dirname(index), entry.file), target, entry, signal);
+            written.push(target);
+        }
+        const file = join(this.directory, CATALOG);
+        writeFileSync(`${file}.partial`, JSON.stringify(catalog, null, 2) + "\n", { mode: 0o644 });
+        renameSync(`${file}.partial`, file);
+        written.push(file);
+        return { written };
+    }
+}

package/adapters/storage/filesystem/src/file-breakpoint-store.d.ts

@@ -0,0 +1,4 @@
+import type { BreakpointStore } from "@parity/product-lab/ports/storage";
+import { FileJsonDocument } from "./file-json-document.js";
+export declare class FileBreakpointStore extends FileJsonDocument implements BreakpointStore {
+}

package/adapters/storage/filesystem/src/file-breakpoint-store.js

@@ -0,0 +1,5 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { FileJsonDocument } from "./file-json-document.js";
+export class FileBreakpointStore extends FileJsonDocument {
+}

package/adapters/storage/filesystem/src/file-environment-option-choices.d.ts

@@ -0,0 +1,11 @@
+import type { EnvironmentOptionChoices } from "@parity/product-lab/ports/storage";
+export declare class FileEnvironmentOptionChoices implements EnvironmentOptionChoices {
+    readonly location: string;
+    private writes;
+    constructor(location: string);
+    read(environment: string): string | undefined;
+    /** A damaged file is replaced: the person's new choice matters more than the ones it no longer holds. */
+    write(environment: string, option: string): void;
+    private document;
+    private save;
+}

package/adapters/storage/filesystem/src/file-environment-option-choices.js

@@ -0,0 +1,44 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export class FileEnvironmentOptionChoices {
+    location;
+    writes = 0;
+    constructor(location) {
+        this.location = location;
+    }
+    read(environment) {
+        const choice = this.document()[environment];
+        return typeof choice === "string" ? choice : undefined;
+    }
+    write(environment, option) {
+        let document = {};
+        try {
+            document = this.document();
+        }
+        catch {
+        }
+        this.save({ ...document, [environment]: option });
+    }
+    document() {
+        if (!existsSync(this.location))
+            return {};
+        try {
+            const value = JSON.parse(readFileSync(this.location, "utf8"));
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                throw new Error("expected an object of environments");
+            return value;
+        }
+        catch (error) {
+            throw new Error(`${this.location} is damaged (${error instanceof Error ? error.message : String(error)}). Delete it to forget every remembered option.`, { cause: error });
+        }
+    }
+    save(document) {
+        mkdirSync(dirname(this.location), { recursive: true, mode: 0o700 });
+        const temporary = `${this.location}.${process.pid}.${++this.writes}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(temporary, 0o600);
+        renameSync(temporary, this.location);
+    }
+}

package/adapters/storage/filesystem/src/file-evidence-journal.d.ts

@@ -0,0 +1,10 @@
+import type { EvidenceJournal } from "@parity/product-lab/ports/storage";
+/** `<directory>/timeline.jsonl`, one JSON entry per line (`bigint` as a decimal string). */
+export declare class FileEvidenceJournal implements EvidenceJournal {
+    private readonly directory;
+    readonly location: string;
+    constructor(directory: string, file?: string);
+    /** Create the directory (private). Call before the first append. */
+    open(): this;
+    append(entry: unknown): void;
+}

package/adapters/storage/filesystem/src/file-evidence-journal.js

@@ -0,0 +1,19 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+export class FileEvidenceJournal {
+    directory;
+    location;
+    constructor(directory, file = "timeline.jsonl") {
+        this.directory = directory;
+        this.location = join(directory, file);
+    }
+    open() {
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        return this;
+    }
+    append(entry) {
+        appendFileSync(this.location, JSON.stringify(entry, (_, value) => (typeof value === "bigint" ? value.toString() : value)) + "\n", { mode: 0o600 });
+    }
+}

package/adapters/storage/filesystem/src/file-fixture-archives.d.ts

@@ -0,0 +1,17 @@
+import type { FixturePlatform } from "@parity/product-lab/domain";
+import type { FixtureArchivePacked, FixtureArchivePackRequest, FixtureArchives, FixtureArchiveUnpackRequest } from "@parity/product-lab/ports/storage";
+export { BundleContentError } from "./tar-archive.js";
+/** The manifest archived as the bundle's last entry. */
+export declare const BUNDLE_MANIFEST = "bundle-manifest.json";
+/** Parts of a bundle whose index is `index`: `<name>.tar.zst.<NNN>` beside it (`<name>`: the index without `.json`). */
+export declare function bundlePartName(index: string, number: number): string;
+export declare class FileFixtureArchives implements FixtureArchives {
+    platform(): FixturePlatform;
+    pack(request: FixtureArchivePackRequest): Promise<FixtureArchivePacked>;
+    writeIndex(file: string, index: unknown): void;
+    fileSha256(file: string): Promise<string>;
+    readIndex(file: string): unknown;
+    unpack(request: FixtureArchiveUnpackRequest): Promise<{
+        json: Readonly<Record<string, unknown>>;
+    }>;
+}