tracegrove 0.0.0-stage → 0.3.1

package/dist/source/gitObjectProof.js

@@ -0,0 +1,115 @@
+import { createHash } from 'node:crypto';
+import { GitSourceSnapshot, GIT_COMMIT_PROOF_LIMITS, GIT_SNAPSHOT_LIMITS, digestOfBytes, digestOfValue, sameDigest, verifySelfDigest } from "../protocol/index.js";
+import { Conflict } from "../core/errors.js";
+import { assertSnapshotPaths } from "./snapshotPaths.js";
+export function gitObjectId(type, bytes, algorithm) {
+    return createHash(algorithm).update(`${type} ${bytes.byteLength}\0`).update(bytes).digest('hex');
+}
+function decode(value, bound) {
+    const bytes = Buffer.from(value, 'base64');
+    if (bytes.length > bound || bytes.toString('base64') !== value)
+        throw new Conflict('Git object proof has noncanonical or oversized bytes');
+    return bytes;
+}
+function verify(input, actual) {
+    const snapshot = GitSourceSnapshot.parse(input);
+    if (!verifySelfDigest(snapshot) || !snapshot.commitProof)
+        throw new Conflict('Git commit proof is missing or its snapshot seal changed');
+    if (snapshot.files.reduce((sum, file) => sum + file.bytes, 0) > GIT_SNAPSHOT_LIMITS.totalBytes)
+        throw new Conflict('Git proof snapshot exceeds the total file byte bound');
+    const proof = snapshot.commitProof;
+    const algorithm = snapshot.commit.length === 40 ? 'sha1' : 'sha256';
+    const oidBytes = algorithm === 'sha1' ? 20 : 32;
+    const commit = decode(proof.commitBase64, GIT_COMMIT_PROOF_LIMITS.commitBytes);
+    const observedCommit = gitObjectId('commit', commit, algorithm);
+    if (observedCommit !== snapshot.commit)
+        throw new Conflict('Git commit object disagrees with selected snapshot commit');
+    const root = /^tree ([a-f0-9]{40}|[a-f0-9]{64})\n/.exec(commit.toString('utf8'))?.[1];
+    if (!root || root.length !== snapshot.commit.length)
+        throw new Conflict('Git commit proof has no valid root tree');
+    const trees = new Map();
+    let total = 0;
+    for (const entry of proof.trees) {
+        const bytes = decode(entry.base64, GIT_COMMIT_PROOF_LIMITS.treeBytes);
+        total += bytes.length;
+        if (total > GIT_COMMIT_PROOF_LIMITS.totalTreeBytes || trees.has(entry.objectId) ||
+            gitObjectId('tree', bytes, algorithm) !== entry.objectId)
+            throw new Conflict('Git tree object proof is duplicated, oversized or changed');
+        trees.set(entry.objectId, bytes);
+    }
+    assertSnapshotPaths(snapshot.files.map(file => file.path));
+    const declared = new Map(snapshot.files.map(file => [file.path, file]));
+    if (actual && actual.length !== declared.size)
+        throw new Conflict('Git proof needs the complete actual snapshot file closure');
+    const files = actual ? new Map(actual.map(file => {
+        const path = file.path;
+        const mode = file.mode;
+        const source = file.bytes;
+        const expected = declared.get(path);
+        if (!expected || mode !== expected.mode || !(source instanceof Uint8Array) || source.byteLength !== expected.bytes)
+            throw new Conflict('Actual snapshot bytes disagree with the declared file closure');
+        return [path, { path, mode, bytes: Buffer.from(source) }];
+    })) : null;
+    if (files && (files.size !== actual.length || files.size !== declared.size))
+        throw new Conflict('Git proof needs the complete actual snapshot file closure');
+    const visited = new Set();
+    const paths = new Set();
+    const pending = [{ id: root, prefix: '' }];
+    let nodes = 0;
+    while (pending.length) {
+        const selected = pending.pop();
+        const bytes = trees.get(selected.id);
+        if (!bytes)
+            throw new Conflict('Git tree object closure is incomplete');
+        if (!bytes.length)
+            throw new Conflict('Git snapshot cannot materialize empty Git directories');
+        visited.add(selected.id);
+        let offset = 0;
+        const names = new Set();
+        while (offset < bytes.length) {
+            if (++nodes > GIT_COMMIT_PROOF_LIMITS.nodes)
+                throw new Conflict('Git object proof exceeds the complete traversal bound');
+            const space = bytes.indexOf(32, offset);
+            const nul = bytes.indexOf(0, space + 1);
+            if (space < offset || nul <= space + 1 || nul + 1 + oidBytes > bytes.length)
+                throw new Conflict('Git tree object record is truncated');
+            const mode = bytes.subarray(offset, space).toString('ascii');
+            const name = new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(space + 1, nul));
+            if (names.has(name) || name.includes('/') || name === '.' || name === '..' || !name)
+                throw new Conflict('Git tree object has an ambiguous path');
+            names.add(name);
+            const path = selected.prefix ? `${selected.prefix}/${name}` : name;
+            assertSnapshotPaths([path]);
+            const id = bytes.subarray(nul + 1, nul + 1 + oidBytes).toString('hex');
+            offset = nul + 1 + oidBytes;
+            if (mode === '40000') {
+                pending.push({ id, prefix: path });
+                continue;
+            }
+            const entry = declared.get(path);
+            if (!['100644', '100755'].includes(mode) || !entry || entry.mode !== mode || entry.objectId !== id || paths.has(path))
+                throw new Conflict('Git object tree differs from the declared snapshot files');
+            paths.add(path);
+            if (files) {
+                const file = files.get(path);
+                if (!file || file.mode !== entry.mode || file.bytes.length !== entry.bytes || !sameDigest(digestOfBytes(file.bytes), entry.digest) ||
+                    gitObjectId('blob', file.bytes, algorithm) !== id)
+                    throw new Conflict('Actual snapshot bytes disagree with the Git commit tree');
+            }
+        }
+    }
+    if (paths.size !== declared.size || visited.size !== trees.size)
+        throw new Conflict('Git object proof has omitted files or unrelated trees');
+    return { algorithm, commit: observedCommit, tree: root, proofDigest: digestOfValue(proof) };
+}
+/** Structural object/manifest links only: cannot certify SHA-256 file bytes without reading them. */
+export function verifyGitSnapshotProofMetadata(snapshot) {
+    return { verification: 'object_links_only', binding: verify(snapshot) };
+}
+/** Hashes every actual file through its Git blob identity and the full tree/commit object closure. */
+export function verifyGitSnapshotCommit(snapshot, files) {
+    if (!Array.isArray(files))
+        throw new Conflict('actual Git source files are required');
+    return { ...verify(snapshot, files), verification: 'actual_file_bytes' };
+}
+//# sourceMappingURL=gitObjectProof.js.map

package/dist/source/gitObjectProof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitObjectProof.js","sourceRoot":"","sources":["../../src/source/gitObjectProof.ts"],"names":[],"mappings":"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"}

package/dist/source/snapshotPaths.d.ts

@@ -0,0 +1,2 @@
+/** Shared Git/transport path rules; prevent aliases before any filesystem write. */
+export declare function assertSnapshotPaths(paths: string[]): void;

package/dist/source/snapshotPaths.js

@@ -0,0 +1,24 @@
+import { RepositoryPath } from "../protocol/primitives.js";
+import { Conflict } from "../core/errors.js";
+/** Shared Git/transport path rules; prevent aliases before any filesystem write. */
+export function assertSnapshotPaths(paths) {
+    const seen = new Set();
+    const spellings = new Map();
+    for (const raw of paths) {
+        const path = RepositoryPath.parse(raw);
+        const canonical = path.normalize('NFC').toLowerCase();
+        const parts = path.split('/');
+        if (seen.has(canonical) || parts.some(part => /^(?:\.git|con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part) || /[. ]$/.test(part) || /[<>"|?*]/.test(part))) {
+            throw new Conflict('Git snapshot path is not portable or is duplicated');
+        }
+        seen.add(canonical);
+        for (let length = 1; length <= parts.length; length++) {
+            const prefix = parts.slice(0, length).join('/');
+            const key = prefix.normalize('NFC').toLowerCase();
+            if (spellings.has(key) && spellings.get(key) !== prefix)
+                throw new Conflict('Git snapshot contains aliased directory names');
+            spellings.set(key, prefix);
+        }
+    }
+}
+//# sourceMappingURL=snapshotPaths.js.map

package/dist/source/snapshotPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotPaths.js","sourceRoot":"","sources":["../../src/source/snapshotPaths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,oFAAoF;AACpF,MAAM,UAAU,mBAAmB,CAAC,KAAe;IACjD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAAC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5E,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAAC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QAC9F,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,uDAAuD,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACjK,MAAM,IAAI,QAAQ,CAAC,oDAAoD,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACpB,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,IAAI,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;YACtD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAAC,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACnG,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,MAAM;gBAAE,MAAM,IAAI,QAAQ,CAAC,+CAA+C,CAAC,CAAC;YAC7H,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/source/snapshotTree.d.ts

@@ -0,0 +1,15 @@
+import { GitSourceSnapshot, type GitCommitObservation } from '../protocol/schemas/gitSources.ts';
+export type SnapshotFile = {
+    path: string;
+    mode: '100644' | '100755';
+    bytes: Buffer;
+};
+export declare function readGitSnapshotManifest(path: string): GitSourceSnapshot;
+/** Read every pinned regular file, ignoring untracked inputs that will never enter the launch copy. */
+export declare function readGitSnapshotTree(input: unknown, sourceRoot: string): SnapshotFile[];
+export declare function readGitSnapshotSource(input: unknown, sourceRoot: string): {
+    files: SnapshotFile[];
+    gitSource: GitCommitObservation | null;
+};
+/** Exclusively create a private tree; a failed write removes only this owned directory. */
+export declare function writeGitSnapshotTree(files: SnapshotFile[], destination: string): void;

package/dist/source/snapshotTree.js

@@ -0,0 +1,79 @@
+import { lstatSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { GitSourceSnapshot, GIT_SNAPSHOT_LIMITS } from "../protocol/schemas/gitSources.js";
+import { digestOfBytes, sameDigest, verifySelfDigest } from "../protocol/canonical.js";
+import { Conflict } from "../core/errors.js";
+import { readBoundedFile } from "../core/boundedFile.js";
+import { assertSnapshotPaths } from "./snapshotPaths.js";
+import { verifyGitSnapshotCommit, verifyGitSnapshotProofMetadata } from "./gitObjectProof.js";
+export function readGitSnapshotManifest(path) {
+    let snapshot;
+    try {
+        snapshot = GitSourceSnapshot.parse(JSON.parse(readBoundedFile(path, 32 * 1024 * 1024).toString('utf8')));
+    }
+    catch {
+        throw new Conflict('Choose a bounded, regular source snapshot manifest with valid metadata');
+    }
+    if (!verifySelfDigest(snapshot))
+        throw new Conflict('Git snapshot manifest digest mismatch');
+    if (snapshot.commitProof)
+        verifyGitSnapshotProofMetadata(snapshot);
+    return snapshot;
+}
+/** Read every pinned regular file, ignoring untracked inputs that will never enter the launch copy. */
+export function readGitSnapshotTree(input, sourceRoot) {
+    return readGitSnapshotSource(input, sourceRoot).files;
+}
+export function readGitSnapshotSource(input, sourceRoot) {
+    const snapshot = GitSourceSnapshot.parse(input);
+    if (!verifySelfDigest(snapshot))
+        throw new Conflict('Git snapshot manifest digest mismatch');
+    assertSnapshotPaths(snapshot.files.map(file => file.path));
+    if (snapshot.files.reduce((sum, file) => sum + file.bytes, 0) > GIT_SNAPSHOT_LIMITS.totalBytes)
+        throw new Conflict('Git snapshot exceeds the total byte bound');
+    const root = resolve(sourceRoot);
+    const checked = new Set();
+    const directory = (path) => {
+        if (checked.has(path))
+            return;
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new Conflict('Git snapshot refuses linked or non-directory parents');
+        checked.add(path);
+    };
+    directory(root);
+    const files = snapshot.files.map(file => {
+        let parent = root;
+        for (const segment of file.path.split('/').slice(0, -1)) {
+            parent = join(parent, segment);
+            directory(parent);
+        }
+        const bytes = readBoundedFile(join(root, file.path), file.bytes, file.bytes);
+        if (!sameDigest(digestOfBytes(bytes), file.digest))
+            throw new Conflict('Git snapshot file digest mismatch');
+        return { path: file.path, mode: file.mode, bytes };
+    });
+    return { files, gitSource: snapshot.commitProof ? verifyGitSnapshotCommit(snapshot, files) : null };
+}
+/** Exclusively create a private tree; a failed write removes only this owned directory. */
+export function writeGitSnapshotTree(files, destination) {
+    if (!files.length || files.length > GIT_SNAPSHOT_LIMITS.files || files.some(file => file.bytes.length > GIT_SNAPSHOT_LIMITS.fileBytes) ||
+        files.reduce((sum, file) => sum + file.bytes.length, 0) > GIT_SNAPSHOT_LIMITS.totalBytes)
+        throw new Conflict('Git snapshot tree exceeds complete-coverage bounds');
+    assertSnapshotPaths(files.map(file => file.path));
+    mkdirSync(destination, { mode: 0o700 });
+    try {
+        for (const file of files) {
+            const path = join(destination, file.path);
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            writeFileSync(path, file.bytes, { flag: 'wx', mode: file.mode === '100755' ? 0o700 : 0o600 });
+            if (!readBoundedFile(path, file.bytes.length, file.bytes.length).equals(file.bytes))
+                throw new Conflict('snapshot bytes changed while writing');
+        }
+    }
+    catch (error) {
+        rmSync(destination, { recursive: true, force: true });
+        throw error;
+    }
+}
+//# sourceMappingURL=snapshotTree.js.map

package/dist/source/snapshotTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotTree.js","sourceRoot":"","sources":["../../src/source/snapshotTree.ts"],"names":[],"mappings":"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"}

package/docs/agent-guide.md

@@ -0,0 +1,21 @@
+# Agent and CI command guide
+
+Use the installed binary through `npx --no-install tracegrove` so CI never fetches an unrelated package. Pass `--json` and check both exit status and report fields; do not classify a run from prose alone.
+
+| Command | Effect | Result |
+| --- | --- | --- |
+| `status --json` | Reads the current project and run state | `tracegrove.status/v1` and ordered `next` commands |
+| `discover --json` | Compares discovered routes and authored flows | Coverage suggestions, no app launch |
+| `check --json` | Compiles authoring files | `ok` and located issues; may evaluate trusted TypeScript authoring modules |
+| `doctor --dir . --json` | Checks the native plan without app launch | `tracegrove.doctor/v1`, `checks`, `errors`, `blocked`, `execution: not_started` |
+| `test --json` | Starts the selected app and executes scenarios | `tracegrove.run-summary/v1`, `outcome`, `cases`, `blockers`, `runDir`, `bundleVerified` |
+| `verify-bundle --bundle <dir> --json` | Checks existing evidence | `ok`, `problems`, `outcome`, `receipts`; no app launch |
+| `draft --intent '<goal>'` | Starts a coding agent to edit drafts | Review changed files and compile/run afterward |
+| `heal --dry-run` | Runs and diagnoses the suite | Findings without retained agent edits |
+| `heal` | May retain bounded setup/flow edits | `tracegrove.heal/v1`; inspect saved diff and backups |
+
+Exit codes: 0 clean/passed; 1 assertion failure; 2 blocked/inconclusive; 3 infrastructure failure; 4 cancellation. A top-level JSON error uses `tracegrove.cli-error/v1`, with a public class, bounded reason codes and recovery actions. Normal reports and artifacts may contain application data; protect them with your usual workspace access controls. `--json=false` selects prose errors, while `--jsonl` keeps its event stream.
+
+Agent drafting uses the configured Claude Code or Codex CLI and its existing permissions. Tracegrove's prompt is not a filesystem sandbox. The default models are explicit in the adapter, and one Claude model-alias retry is recorded when used. A requested `maxBudgetUsd` is supported by the Claude adapter; the Codex adapter blocks it rather than ignoring a spending limit. Commit or stash work before drafting or healing, review proposed changes, and preserve the original failed run. A passing compiled flow is not proof of intended behavior.
+
+The same short flows compile into the strict `workflow.*/v1` corpus. The browser, native jobs, MCP, evidence and recovery guides are shipped in this package. General portable profiles are reference-only; they cannot be passed to the present CLI as an executable target.

package/docs/browser-driver.md

@@ -0,0 +1,146 @@
+# Local browser driver
+
+`BrowserDriver` runs real Chromium in a fresh, nonpersistent context. It does
+not connect to an existing browser profile. Install its pinned browser before
+running browser tests or using the driver in a project with Tracegrove installed:
+
+```sh
+npx --no-install playwright install chromium
+```
+
+Linux CI uses `playwright install --with-deps chromium` to install the browser
+and its system libraries.
+
+Run the packaged browser sample through the same low-level CLI as an API case,
+from a directory where Tracegrove is installed:
+
+```sh
+npx --no-install tracegrove sample-config --sample notes-browser --output "$PWD/notes-browser"
+npx --no-install tracegrove plan --config "$PWD/notes-browser/verification/workflow.yaml" --output "$PWD/notes-browser-request.json"
+npx --no-install tracegrove run --request "$PWD/notes-browser-request.json"
+```
+
+Use fresh output paths: sample generation refuses to overwrite a project. The
+run prints its execution ID and bundle path. Pass that path to
+`npx --no-install tracegrove verify-bundle --bundle <path>` for independent verification.
+The sample shares its real app, personas, fixture recipes, and cleanup with
+`notes-api`; only its browser runner, binding, and case differ.
+
+The exported `BrowserCommand`, `BrowserLocator`, and `BrowserObservation` Zod
+schemas also have generated JSON Schemas. Commands navigate, click, fill, or
+read visible text. Locators use exact roles, labels, or test IDs. Arbitrary
+scripts and selectors are not accepted. Observations contain browser facts;
+the driver does not decide whether a scenario passes.
+
+Each operation has a deadline. Cancellation or a failed mutating operation closes the
+context and browser before returning. Calls on one driver are serialized by
+rejecting concurrent operations. Closing is idempotent. A closure acknowledgement
+does not prove cleanup of an operating-system process tree after controller death.
+
+Page requests must stay on the admitted origin. Chromium's CDP Fetch interception
+checks every redirect hop while retaining native response streaming. Service
+workers and WebSockets are disabled, and extra pages are closed. This is page
+request filtering, not an operating system network sandbox; arbitrary application
+code, workers, and popups require a host network boundary for full confinement.
+
+`collectVideo()` closes the browser, flushes the WebM recording, and reads at
+most 32 MiB from a regular file without following a final symlink. `dispose()`
+removes the private temporary recording directory. Recordings and DOM text are
+raw and may contain application data; callers must apply their evidence access
+and retention policy before storing or sharing them. This driver does not issue
+credentials or copy an owner's authenticated session.
+
+The real-browser tests submit a local form, check an independent server receipt,
+read the resulting DOM, and inspect the flushed recording. Separate tests cover
+cross-origin paths, page requests and redirects, cancellation, timeout, invalid
+commands, and expired startup.
+
+The core runner profile accepts `adapter: browser`. A typed `ui.navigate` step
+has a path; `ui.action` carries a click or fill command; `ui.observe` carries a
+semantic target, predicate, and poll interval. DOM predicates address
+`browser.text` or `browser.url` through the `browser.observation/1` oracle.
+HTTP steps and fixtures can run in the same case for independent readback.
+
+Each poll counts against `maxBrowserActions`. Case method and resource-prefix
+rules filter page requests; read-only cases allow only GET and HEAD. Persona
+viewport, locale, timezone, and reduced motion are passed to the browser. Pointer
+activation uses clicks, keyboard activation uses focus with Enter or Space for toggles, and touch
+activation uses taps. Host-issued bearer credentials are added only to admitted
+page requests, never expanded into filled values or recorded commands.
+Network events record methods, paths, and response statuses without request
+headers or query strings. Recording more than 512 network events invalidates
+collection. Required traces and declared redaction policies remain blocked.
+
+Before closing a successful session, collection completes a layout-aware
+screenshot, then requests another capture and waits for a frame presented after
+the first capture through Playwright’s public screencast callback. Only then
+does it stop and flush the encoder. A fresh frame delivered during the first
+capture can still contain older pixels. This uses the cleanup deadline, not an
+arbitrary recording delay. Collection failures name their capture, frame, or
+flush phase without exposing page text or Playwright diagnostics.
+The controller seals the recording bytes into the portable bundle and records
+browser duration and artifact bytes. Verification reproduces the frozen runner
+capabilities, independently reduces browser assertions, and checks video hashes
+and byte counts. A required recording cannot be satisfied by an event log alone.
+
+The integrated native tests cover pointer, keyboard, and 375px simulated touch,
+combining an authenticated UI, DOM observation,
+independent API assertions, fixture cleanup, video capture, and portable bundle
+verification. A decoded-frame test checks the recorded terminal visual state.
+This proves local behavior. Hosted admission, staging personas, and
+controller-death browser cleanup remain open; no production qualification is claimed.
+
+## Short flows and Grove
+
+The packaged sample also includes a short browser flow. From the same installed directory:
+
+```sh
+npx --no-install tracegrove test --config "$PWD/notes-browser/tracegrove.config.yaml" --grep notes.browser
+npx --no-install tracegrove ui --dir "$PWD/notes-browser"
+```
+
+Open the printed loopback address and select the browser scenario. Its step
+panel shows expected and observed text plus native recording controls. The
+player supports keyboard playback and byte-range seeking, and preserves its
+position when changing steps. Each media request verifies one immutable bundle
+snapshot and binds the digest to that run and scenario. Corrupt, unbound, or
+symlinked recordings are refused.
+
+Browser commands reuse the core command and locator schemas:
+
+```yaml
+title: Show the seeded note
+given: { existing: existing-note }
+browser:
+  allowPaths: [/ui, /notes]
+  allowMethods: [GET, HEAD]
+steps:
+  - browser: { kind: navigate, path: /ui }
+    expect: { status: 200 }
+  - browser: { kind: click, target: { by: role, role: button, name: Refresh } }
+  - browser: { kind: read, target: { by: testId, name: notes } }
+    expect: { text: Existing note }
+```
+
+`fill` accepts a semantic `target` and string `value`. Browser reads require
+`expect.text` and poll until it holds. Click/fill steps assert completion; add a
+DOM read or independent API readback to establish the effect. Browser steps use
+the default persona, and browser flows require a recording. Set `maxActions`
+and `maxArtifactBytes` inside the flow's `browser` block to tune their budgets.
+Its allowed paths and methods combine with those derived from HTTP steps and
+fixtures into the flow's effect envelope.
+
+Persona configuration accepts optional `viewport`, `inputMode`, `locale`,
+`timezone`, and `reducedMotion` fields alongside `subject`. Simulated touch
+does not qualify a physical mobile device. Required traces, executable
+redaction policies, and non-browser native surfaces remain unsupported.
+
+Read-only observation timeouts preserve the browser for final evidence collection.
+Browser polling retains its last completed observation at the deadline so an
+unmet expectation keeps its observed value and remains an assertion failure.
+Cancellation and actual browser errors still propagate; failed mutating actions
+close the browser to revoke late effects.
+
+Capture failures remain infrastructure failures with no accepted video. The sealed `browser.failed` event includes a bounded driver `cause` and `phase` (`capture`, `frame`, or `flush`) when available; unknown exceptions expose neither their message nor arbitrary fields.
+
+Recordings use the persona viewport at native size, rounded up to even dimensions for VP9 (at most one padding pixel per edge), instead of scaling mobile content into a desktop canvas. Fresh-frame and encoder-flush checks remain required.

package/docs/getting-started.md

@@ -0,0 +1,13 @@
+# Test an existing app
+
+Start with the [npm README](https://www.npmjs.com/package/tracegrove) and its synthetic Notes sample. In your own repository, install `tracegrove@0.3.1` as a development dependency, then run `npx --no-install tracegrove init`. Review the generated config and flow before running them.
+
+`tracegrove.config.yaml` names a `project`, an `app` adapter (`node`, `fastapi`, or `django`), its entry point and health route, source paths to digest, and test personas. Put flows at `tracegrove/<area>/<behavior>.flow.yaml`; their case IDs use `<area>.<behavior>`. A flow contains named steps with methods, paths, expected statuses and optional independent read requests (`observe: true`). Put reusable fixtures at `tracegrove/fixtures/<name>.fixture.yaml`. Steps can `save` a response value and refer to it later as `{name}`; inspect the generated starter flow or packaged Notes sample for a complete example. `npx --no-install tracegrove check --json` compiles these files without starting the app. `doctor --dir . --json` checks the selected native plan; it can probe an interpreter version but does not run your app.
+
+The local adapter assigns a loopback port and owned data directory. Your app must consume the injected port and `TRACEGROVE_DATA_DIR` and recognize the per-run synthetic `TRACEGROVE_TOKENS` in test mode. Keep the test token path disabled in production. The Django adapter invokes migration before start: verify that Django's configured database lives in the injected data directory. Do not point a test run at a shared or production database.
+
+Run `npx --no-install tracegrove test --json`. A passing JSON summary names `runDir`, `executionId`, per-case outcomes, and `bundleVerified`. The run folder contains readable summaries, JUnit and `bundle/`. Run `npx --no-install tracegrove verify-bundle --bundle <runDir>/bundle --json` to independently check the stored files and verdict. Verification does not rerun your app or establish who produced an unsigned bundle.
+
+If a prerequisite blocks, read `blockers[]` and the suggested recovery before retrying. A nonzero assertion result is a finding about the app or test, not a setup failure. For a single interrupt, wait for the owned cleanup and inspect its receipts. Keep the run folder until you have exported any evidence you need. `recovery-status` reads an existing checkpoint but cannot clear ownership or restart work.
+
+Browser tests need the pinned Playwright Chromium installed through your environment's approved dependency path. The browser and native job guides are in this npm package. External staging, a general cloud runner and arbitrary shell launchers are not available through the current CLI.

package/docs/git-object-proof.md

@@ -0,0 +1,100 @@
+# Git object checks for pinned snapshots
+
+New `materializeGitSnapshot` outputs include the raw commit/tree object proof and each
+file's Git blob identity. The resolver reads immutable Git objects with its existing
+restricted environment; materialization verifies the complete proof before creating
+an output directory. No fetch, checkout, helper, signature verification or application
+execution is added.
+
+`verifyGitSnapshotCommit(snapshot, files)` independently hashes every actual file as a
+Git blob, checks paths and modes against the complete raw tree closure, and hashes that
+tree/commit chain against the selected commit. Both SHA-1 and SHA-256 object formats
+are supported. Its observation has `verification: actual_file_bytes` and binds the
+computed commit, root tree, object algorithm and proof digest. It needs captured bytes
+and proof objects and captures each supplied file buffer once before both hash checks,
+so it continues to work after the Git store and source directory
+are unavailable.
+
+```ts
+const files = readGitSnapshotTree(snapshot, sourceRoot);
+const observed = verifyGitSnapshotCommit(snapshot, files);
+```
+
+`verifyGitSnapshotProofMetadata(snapshot)` checks object/manifest links without reading
+source files. Its distinct `verification: object_links_only` result is not a runtime
+observation. A resealed manifest could pair a new SHA-256 file checksum with an old Git
+blob ID; metadata alone cannot prove that association. Actual-file verification rejects
+it even when the new checksums and manifest seal agree.
+
+## Launch and saved evidence
+
+Snapshot reads now verify object proofs when present. The trusted supervisor copies the
+pinned files into its owned tree and verifies the private copy again before launching
+the application. It sends the computed Git observation over its existing IPC channel.
+The parent refuses missing/mismatched observations for proof-bearing snapshots, and
+the sealed identity attestation records the observed fields. The application cannot
+establish this observation through its health response.
+
+Saved-bundle verification checks the proof's metadata, snapshot ref, component file
+closure and recorded Git observation after the private launch directory is removed.
+It does not regain the full source bytes from that observation. Authenticating the host
+and its runtime file measurements remains the issuer's job. Existing proof-less snapshots
+remain component-only and receive no Git observation. Repository binding is a separate,
+explicit option described below; remote ownership and dependency-install provenance are
+not inferred from Git object hashes.
+
+## Bind a repository role
+
+Materialization also saves a sealed `resolution.json` next to `snapshot.json`. To connect
+the selected resolver head to a repository role:
+
+```sh
+tracegrove test --config ./head/source/tracegrove.config.yaml \
+  --source-snapshot ./head/snapshot.json --source-repository-role application
+```
+
+The same flags work with `compile`. Compilation verifies the complete source tree,
+checks the sealed resolution sidecar against the snapshot, and emits `SourceSelection`,
+the original `RevisionMatrix`, and snapshot documents in the normal frozen corpus. The
+planner binds that selection to the request and every cell. Existing component-only
+snapshot runs do not change unless a repository role is provided. Old snapshots can
+be rematerialized to obtain a sidecar; no network access is required.
+
+The descriptor uses `urn:tracegrove:git-object:<algorithm>:<commit>` and origin
+`snapshot_bundle`. It identifies the actual Git object, not ownership of a GitHub URL.
+`requestedRef` in the target is the immutable commit; `requestedExpression` in source
+selection retains the resolver's original expression. Both Git SHA-1 and SHA-256 work.
+`dirty: false` describes the supervisor's complete private pinned copy, not the checkout.
+
+Lockfile identity v1 hashes a sorted manifest of complete pinned path, mode and SHA-256
+digest for `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`,
+`bun.lock`, `bun.lockb`, `uv.lock`, `poetry.lock`, `Pipfile.lock`, `Cargo.lock`, `Gemfile.lock`,
+`composer.lock` and `go.sum` at any depth. No recognized lockfile produces an explicit
+empty-manifest digest. This identifies pinned lockfiles; it does not establish which
+dependencies were installed.
+
+Repository observation is derived only after the supervisor's `actual_file_bytes`
+observation matches the proof. Planning, execution preflight, saved-bundle checks and
+revision assessment share the frozen source-closure checks. They reject different
+roles, remote URLs, lockfile identities, missing closure documents and source plans
+whose reviewed matrix differs. Base snapshots and multi-repository resolution sidecars
+cannot use this single-head binding; companion repositories are never silently dropped.
+They remain available for component-only runs until a complete multi-host binding exists.
+
+Two independent native campaigns can now meet a revision-level local qualification
+policy and activate through the durable scenario store. The tests simulate issuer and
+physical-lease authority explicitly. This does not establish hosted issuer trust, live
+staging coverage, remote repository ownership, or a reviewed-source promotion by itself.
+
+Proofs fail on missing or duplicate trees, unrelated objects, malformed/canonicalization
+errors, changed file/object/mode bindings, incomplete actual file coverage and unsupported
+tree entries. Symlinks, submodules, empty Git directories and nonportable paths cannot
+be silently omitted. Prototype bounds are 1 MiB per commit, 4 MiB per tree, 8 MiB total
+tree bytes, 8,192 distinct trees and 20,000 traversal entries, in addition to the existing
+10,000-file/32 MiB snapshot bound. Unsupported coverage blocks instead of truncating it.
+
+Tests use real SHA-1/SHA-256 repositories, binary files and reused subtrees; remove the
+Git/source paths before pure verification; and exercise resealed forged commits, trees,
+files and runtime attestations. Native pinned launches and independent bundle reads
+verify the observation path. These are local integrity/runtime facts, not hosted issuer
+authentication, author identity, a signed release or remote repository ownership.

package/docs/local-execution-recovery.md

@@ -0,0 +1,55 @@
+# Local acquisition recovery gate
+
+The executable local path records ownership in the existing fsynced, single-writer ProjectionLedger. Each new execution initializes `ownership:<executionId>` with its scope, immutable request digest, campaign, attempt and generation. Host and fixture reservations precede workspace acquisition/host startup or application-API create. Observed physical IDs are acknowledged before readback/steps, and cleanup moves through pending to removed only after the existing trusted host stop or registered deletion plus absence readback confirms it. Internal typed host and fixture acknowledgements remain separate: a fixture named `host.process` or `host.workspace` cannot borrow a successful host acknowledgement from the legacy public display-key arrays.
+
+No credentials or fixture request/cleanup arguments are added to this inventory. Physical resource IDs and native workspace/process identities remain private operational metadata in the existing private ledger. The owner must protect that directory.
+
+After controller interruption, redelivery of the same frozen idempotency key checks the prior inventory before admitting a new attempt. Reserved, observed or cleanup-pending entries block with `ownership_reconciliation_required`. Legacy interrupted attempts without inventory block with `ownership_inventory_missing`. Wrong request/scope/attempt/generation cannot discharge the inventory. Cleanly recorded removed inventory permits a fresh attempt through the existing admission path; an empty initialized inventory means no acquisition was reserved. Existing finalized redelivery returns its existing result without replaying effects.
+
+This is deliberately a recovery gate, not an automatic janitor. A controller crash after a real acquisition but before its acknowledgement leaves a durable reservation even if the native supervisor subsequently cleans up. No cleanup acknowledgement is invented from supervisor exit, workspace disappearance, an old PID or elapsed lease time. There is no automatic cross-process takeover/deletion or credential reconstruction, and no operator command to discharge unresolved inventory in this slice. Such cases remain blocked pending a separately reviewed reconciliation path with independent ownership and cleanup evidence. Do not edit ledger records to bypass the gate.
+
+The actual local supervisor still handles ordinary controller disconnect and cleanup. A persistence failure must not prevent best-effort cleanup of resources already known in memory; it does prevent a successful durable completion acknowledgement. A process/power loss during the ledger write inherits the ledger's existing uncertain-write and corrupt-tail behavior.
+
+Tests exercise real native acquisition and application-API fixture create in subprocesses, kill the controller before the executor receives their acknowledgements, reopen the actual persisted ledger, and prove redelivery performs no second acquisition. Other tests exercise native/sample cleanup, reservation/acknowledgement ordering, invalid cleanup transitions and foreign binding rejection. They do not qualify a remote provider, shared-resource fencing, distributed leases, machine power-loss recovery, or a durable supervisor-to-controller cleanup journal. Atomic artifact publication is a separate milestone.
+
+## Read-only recovery inspection
+
+```sh
+tracegrove recovery-status --state-dir <owned-state> --execution <execution-id> --json
+```
+
+This command reads an existing checkpoint without opening `LocalLedger` for writing. It creates
+no directories, locks or credentials, does not contact a controller, and never probes or kills a
+PID. It does not append interrupted/finalized transitions, delete resources, discharge ownership,
+sync a commit, resume a run or admit an acquisition. The existing execution path remains the
+authority for all recovery and admission decisions.
+
+The strict `tracegrove.recovery-status/v1` report includes a journal sequence/content digest,
+lock presence (not process liveness), recorded phase, counts by resource kind/state, bounded
+evidence status, static recovery guidance and an optional verified **historical** outcome.
+It omits raw journal records, resource keys, physical IDs, PIDs, paths, controller tokens,
+cleanup arguments and candidate diagnostics. The checkpoint digest identifies selected local
+bytes; it is not a signature or an admission token. The local process scope and filesystem owner
+must already be authorized to inspect the private state directory.
+
+The journal uses the same schema/sequence/version parser as the existing writer. Inspection is
+bounded to 16 MiB and 100,000 records; oversized, nonregular, linked, malformed or partial inputs
+fail closed. The directory identity, journal bytes and lock fingerprint are checked before and
+after capture and again after evidence inspection. Concurrent changes return an explicit changed
+checkpoint rather than a ready result. This is a checkpoint observation, not a promise that a
+live writer cannot change state after the command returns or confinement against hostile parent
+replacement during filesystem operations.
+
+Ownership counts describe the journal's recorded states, not newly observed absence. The
+committed-bundle path reuses the executor's exact ledger/request/selection/scope/attempt/generation/
+receipt binding checks and full bounded bundle reduction. Exit 0 means either matching finalized
+historical evidence or a recorded interrupted commit available for normal readback; exit 2 means
+another state or unavailable/invalid evidence. Every report says `actionAuthority: none`,
+`execution: not_started_by_inspection` and `verificationVerdict: not_evaluated`. Unknown cleanup
+remains unresolved even when a workspace disappeared or a controller exited. A stale lock does
+not itself record interruption; only normal trusted writer reconciliation can do that.
+
+Automatic janitor/discharge, durable supervisor acknowledgements and provider recovery remain
+separate gates. The supervisor's current `host.cleaned` message is ephemeral IPC. Adding cleanup
+authority requires bound ownership/cleanup evidence admitted by the existing exclusive ledger
+writer; this status command provides neither that evidence nor a new journal.