@nanobpm/urban 0.68.1 → 0.69.0

package/src/context/git/guard-registry.ts

@@ -0,0 +1,59 @@
+// Slice S3 (git/governance) — the mandatory pre-commit guard registry.
+//
+// This is the seam that makes PII enforcement NON-OPTIONAL and default-DENY BY
+// CONSTRUCTION on every write path. A registry is ALWAYS seeded with the S6
+// mandatory guard (`preCommitPiiGuard`) as its first, non-removable member:
+//
+//  - there is no method to remove or replace the default guard, and
+//  - a freshly-constructed registry (the default the writer uses when a caller
+//    supplies no wiring at all) already contains it,
+//
+// so a caller cannot silently bypass PII enforcement. Additional guards can only
+// be ADDED (making the policy stricter), never subtracted. The writer calls
+// {@link PreCommitGuardRegistry.assertAll} immediately before it stages/commits
+// any record, so a write carrying PII is rejected before it is ever committed.
+
+import type { PiiCandidate, PiiGuard } from "../pii/index.ts";
+import { preCommitPiiGuard } from "../pii/index.ts";
+
+/**
+ * An append-only registry of pre-commit guards. The mandatory S6 PII guard is
+ * pre-registered as the default and cannot be removed; callers may register
+ * ADDITIONAL guards, which run in addition to (never instead of) the default.
+ */
+export class PreCommitGuardRegistry {
+  // Index 0 is ALWAYS the mandatory S6 PII guard. There is no removal API, so it
+  // is impossible to end up with a registry that does not enforce it.
+  readonly #guards: PiiGuard[];
+
+  /**
+   * Build a registry. It is seeded with the mandatory {@link preCommitPiiGuard}
+   * first; any `additional` guards are appended after it. Even with no arguments
+   * the resulting registry enforces PII by construction.
+   */
+  constructor(additional: readonly PiiGuard[] = []) {
+    this.#guards = [preCommitPiiGuard, ...additional];
+  }
+
+  /** Register an ADDITIONAL guard. Cannot displace the mandatory default guard. */
+  register(guard: PiiGuard): void {
+    this.#guards.push(guard);
+  }
+
+  /** A snapshot of the registered guards, in run order (mandatory guard first). */
+  get guards(): readonly PiiGuard[] {
+    return [...this.#guards];
+  }
+
+  /**
+   * Run EVERY registered guard against `candidate`. The mandatory PII guard runs
+   * first. Each guard is default-DENY: the first guard to detect a violation
+   * throws (a {@link import("../pii/index.ts").PiiGuardError} for the PII guard),
+   * so a candidate carrying PII never reaches the commit that follows this call.
+   */
+  assertAll(candidate: PiiCandidate): void {
+    for (const guard of this.#guards) {
+      guard.assert(candidate);
+    }
+  }
+}

package/src/context/git/index.ts

@@ -1,2 +1,51 @@
-// Slice S3 (git/governance) — owner replaces this placeholder barrel.
-export {};
+// @nanobpm/urban/context/git — slice S3 (git substrate + PR-governance).
+//
+// The git-as-system-of-record WRITE + governance layer, built on top of a
+// resolved substrate handle (S1), the validated record schema (S2), and the
+// mandatory PII pre-commit guard (S6). It publishes three things downstream:
+//
+//  1. APPEND / GOVERNANCE — ContextWriter: append-via-commit for
+//     human/measured/instance facts, and PR-governance (propose → ratify) for
+//     agent-retro hypotheses, with the mandatory PII guard wired into EVERY write
+//     path so PII is rejected before any commit, by construction.
+//  2. PATH / NAMESPACE PARTITIONING — the layout helper (recordRelativePath,
+//     recordDir, scopeDir, isRecordPath, LAYOUT_ROOT). S4 retrieval and the S6 CI
+//     slice READ this exact layout, so it is exported as a stable seam.
+//  3. THE WRITE SUBSTRATE SEAM — WriteSubstrate / GitWriteSubstrate: the write
+//     path is abstracted over the substrate (not hard-wired to public git),
+//     leaving room for a future PII/mutable backend, and the
+//     PreCommitGuardRegistry that makes the PII guard non-bypassable.
+
+export {
+  LAYOUT_ROOT,
+  RECORD_FILE_EXTENSION,
+  UNSCOPED_BUCKET,
+  isRecordPath,
+  recordDir,
+  recordRelativePath,
+  sanitizeSegment,
+  scopeDir,
+} from "./layout.ts";
+
+export { PreCommitGuardRegistry } from "./guard-registry.ts";
+
+export {
+  type CommitAuthor,
+  GitWriteSubstrate,
+  SubstrateWriteError,
+  substratePath,
+  type WriteSubstrate,
+} from "./substrate.ts";
+
+export {
+  type AppendResult,
+  ContextWriter,
+  type ContextWriterOptions,
+  DEFAULT_BOT_AUTHOR,
+  DEFAULT_WRITE_AUTHOR,
+  GovernanceError,
+  type ProposalResult,
+  type RatifyResult,
+  type ResolvedSubstrateHandle,
+  serialiseRecord,
+} from "./writer.ts";

package/src/context/git/layout.test.ts

@@ -0,0 +1,112 @@
+// Slice S3 (git/governance) — unit tests for the path/namespace layout helper.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { MemoryRecord } from "../schema/index.ts";
+import {
+  LAYOUT_ROOT,
+  UNSCOPED_BUCKET,
+  isRecordPath,
+  recordDir,
+  recordRelativePath,
+  sanitizeSegment,
+  scopeDir,
+} from "./layout.ts";
+
+function record(overrides: Partial<MemoryRecord>): MemoryRecord {
+  const base: MemoryRecord = {
+    schemaVersion: 1,
+    id: "rec-1",
+    scope: "epic",
+    mode: "empirical",
+    provenance: "measured",
+    authority: "authoritative",
+    statement: "a measured fact",
+    createdAt: "2026-01-01T00:00:00Z",
+  };
+  return { ...base, ...overrides };
+}
+
+test("scopeDir / recordDir partition by scope and scopeRef", () => {
+  assert.equal(scopeDir("epic"), `${LAYOUT_ROOT}/epic`);
+  assert.equal(recordDir("epic", "issue-303"), `${LAYOUT_ROOT}/epic/issue-303`);
+  // No scopeRef → the shared bucket.
+  assert.equal(recordDir("corpus"), `${LAYOUT_ROOT}/corpus/${UNSCOPED_BUCKET}`);
+});
+
+test("recordRelativePath is deterministic and scoped", () => {
+  const r = record({ scope: "epic", scopeRef: "issue-303", id: "rec-42" });
+  assert.equal(recordRelativePath(r), `${LAYOUT_ROOT}/epic/issue-303/rec-42.json`);
+  // Same record → same path (idempotent write target).
+  assert.equal(recordRelativePath(r), recordRelativePath({ ...r }));
+});
+
+test("records without scopeRef land in the shared bucket", () => {
+  const r = record({ scope: "corpus", id: "global-1" });
+  assert.equal(recordRelativePath(r), `${LAYOUT_ROOT}/corpus/${UNSCOPED_BUCKET}/global-1.json`);
+});
+
+test("sanitizeSegment neutralises path traversal and separators", () => {
+  // A traversal attempt can never produce a `..` or a separator.
+  const nasty = sanitizeSegment("../../etc/passwd");
+  assert.ok(!nasty.includes("/"));
+  assert.ok(!nasty.includes(".."));
+  assert.notEqual(nasty, "");
+  // A clean value is preserved verbatim.
+  assert.equal(sanitizeSegment("rec-1"), "rec-1");
+});
+
+test("distinct lossy ids never collide onto one segment", () => {
+  const a = sanitizeSegment("a/b");
+  const b = sanitizeSegment("a\\b");
+  assert.notEqual(a, b);
+});
+
+test("a traversal id cannot escape the layout root", () => {
+  const r = record({ scope: "epic", scopeRef: "../../escape", id: "../../../root" });
+  const path = recordRelativePath(r);
+  assert.ok(path.startsWith(`${LAYOUT_ROOT}/epic/`));
+  assert.ok(!path.includes(".."));
+});
+
+test("isRecordPath selects record files under the layout root", () => {
+  assert.equal(isRecordPath("records/epic/issue-303/rec-42.json"), true);
+  assert.equal(isRecordPath("./records/corpus/_/global-1.json"), true);
+  assert.equal(isRecordPath("records\\epic\\x\\r.json"), true);
+  assert.equal(isRecordPath("records/epic/x/notes.md"), false);
+  assert.equal(isRecordPath("other/epic/x/r.json"), false);
+  assert.equal(isRecordPath("records/../secrets/r.json"), false);
+});
+
+test("sanitizeSegment eliminates internal '..' sequences", () => {
+  // An internal `..` (e.g. "a..b") must not survive: `isRecordPath` rejects any
+  // path containing "..", so a record whose id/scopeRef carried one would be
+  // invisible to retrieval/CI. It is disambiguated with a hash, never dropped.
+  const seg = sanitizeSegment("a..b");
+  assert.ok(!seg.includes(".."));
+  assert.notEqual(seg, sanitizeSegment("a.b"));
+});
+
+test("a sanitised scopeRef can never collide with UNSCOPED_BUCKET", () => {
+  // A raw scopeRef of exactly "_" must NOT map onto the shared unscoped bucket,
+  // otherwise a scoped record and an unscoped record share a directory.
+  const seg = sanitizeSegment(UNSCOPED_BUCKET);
+  assert.notEqual(seg, UNSCOPED_BUCKET);
+  assert.notEqual(
+    recordDir("epic", UNSCOPED_BUCKET),
+    recordDir("epic"),
+  );
+});
+
+test("every recordRelativePath output is a valid isRecordPath (no writer/scan drift)", () => {
+  // The writer's output and the retrieval/CI scanner must agree by construction:
+  // any path recordRelativePath emits must be selected by isRecordPath, for even
+  // adversarial ids/scopeRefs.
+  const adversarial = ["a..b", "..", ".", "_", "../../escape", "", "  ", "a/b\\c"];
+  for (const scopeRef of adversarial) {
+    for (const id of adversarial) {
+      const path = recordRelativePath(record({ scope: "epic", scopeRef, id }));
+      assert.equal(isRecordPath(path), true, `not a record path: ${path}`);
+    }
+  }
+});

package/src/context/git/layout.ts

@@ -0,0 +1,110 @@
+// Slice S3 (git/governance) — the on-disk path / namespace partitioning.
+//
+// Records are persisted into the substrate repo under a stable, deterministic
+// layout keyed by the record's scope (and, where present, its `scopeRef`). This
+// helper is the SINGLE SOURCE OF TRUTH for that layout: the write path (this
+// slice) writes to it, and BOTH S4 (retrieval) and the S6 CI slice READ it, so
+// it is exported as a small, stable surface rather than duplicated per-consumer.
+//
+// The scheme is:
+//
+//   records/<scope>/<scopeRef-bucket>/<id>.json
+//
+// where `<scope>` is a controlled-vocabulary ladder level (element … corpus),
+// `<scopeRef-bucket>` is the sanitised `scopeRef` (or the shared `_` bucket when
+// a record carries no `scopeRef`), and `<id>` is the sanitised record id. Every
+// path component is sanitised to a filesystem-safe segment that can never
+// contain a path separator or `..`, so an untrusted `id`/`scopeRef` can never
+// escape the layout root (path-traversal safe by construction).
+
+import { createHash } from "node:crypto";
+import type { MemoryRecord, MemoryScope } from "../schema/index.ts";
+
+/** The directory (relative to the substrate root) all records live under. */
+export const LAYOUT_ROOT = "records" as const;
+
+/** The on-disk extension every serialised record file carries. */
+export const RECORD_FILE_EXTENSION = ".json" as const;
+
+/**
+ * The bucket directory used for records that carry no `scopeRef` (e.g. a
+ * `corpus`-scoped record). `sanitizeSegment` never returns exactly `"_"` — an
+ * input that would sanitise to `"_"` is treated as reserved and gets a `_<hash>`
+ * form instead — so a sanitised `scopeRef` can never collide with this bucket.
+ */
+export const UNSCOPED_BUCKET = "_" as const;
+
+/**
+ * Reduce an untrusted string to a single filesystem-safe path segment.
+ *
+ * The result contains only `[A-Za-z0-9._-]`, never a path separator, never a
+ * `..` sequence, and is never `""`, `.`, `..`, or exactly `"_"` — so it can
+ * never traverse out of its parent directory nor collide with
+ * {@link UNSCOPED_BUCKET}. When sanitisation is LOSSY (the cleaned form differs
+ * from the input, or collapses to a reserved value) a short hash of the ORIGINAL
+ * value is appended, so two distinct raw values can never silently collide onto
+ * one segment while a clean value is preserved verbatim.
+ */
+export function sanitizeSegment(value: string): string {
+  const cleaned = value
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/\.{2,}/g, ".")
+    .replace(/^[-.]+|[-.]+$/g, "")
+    .slice(0, 100);
+  const reserved =
+    cleaned === "" ||
+    cleaned === "." ||
+    cleaned === ".." ||
+    cleaned === UNSCOPED_BUCKET;
+  if (reserved) {
+    return `_${shortHash(value)}`;
+  }
+  // Preserve a clean, reversible value verbatim; disambiguate a lossy one so
+  // distinct inputs never map to the same segment.
+  return cleaned === value ? cleaned : `${cleaned}-${shortHash(value)}`;
+}
+
+function shortHash(value: string): string {
+  return createHash("sha256").update(value, "utf8").digest("hex").slice(0, 12);
+}
+
+/** The directory (relative to the substrate root) that holds a whole scope. */
+export function scopeDir(scope: MemoryScope): string {
+  return `${LAYOUT_ROOT}/${scope}`;
+}
+
+/**
+ * The directory a record with the given `scope`/`scopeRef` is partitioned into.
+ * Records sharing a `(scope, scopeRef)` namespace land in the same directory, so
+ * a retrieval slice can list one namespace cheaply.
+ */
+export function recordDir(scope: MemoryScope, scopeRef?: string): string {
+  const bucket = scopeRef === undefined ? UNSCOPED_BUCKET : sanitizeSegment(scopeRef);
+  return `${scopeDir(scope)}/${bucket}`;
+}
+
+/**
+ * The full path (relative to the substrate root, POSIX separators) a record is
+ * persisted at. Deterministic: the same record id/scope always maps to the same
+ * path, so re-appending an updated record with the same id overwrites its file
+ * in place while git retains the full append-only history.
+ */
+export function recordRelativePath(record: MemoryRecord): string {
+  return `${recordDir(record.scope, record.scopeRef)}/${sanitizeSegment(record.id)}${RECORD_FILE_EXTENSION}`;
+}
+
+/**
+ * `true` iff `relPath` looks like a record file under the layout root (used by
+ * S4 retrieval and the S6 CI scan to select record files while walking the
+ * substrate). Accepts POSIX or native separators and rejects anything that is
+ * not a `.json` file beneath `records/`.
+ */
+export function isRecordPath(relPath: string): boolean {
+  const normalised = relPath.replace(/\\/g, "/").replace(/^\.\//, "");
+  return (
+    normalised.startsWith(`${LAYOUT_ROOT}/`) &&
+    normalised.endsWith(RECORD_FILE_EXTENSION) &&
+    !normalised.includes("..")
+  );
+}

package/src/context/git/substrate.ts

@@ -0,0 +1,287 @@
+// Slice S3 (git/governance) — the WRITE substrate seam.
+//
+// The write path is deliberately abstracted over a {@link WriteSubstrate}
+// interface rather than hard-wired to public git, leaving a clean seam for a
+// future PII/mutable or self-hosted backend (the same seam S1's read side keeps
+// via `SubstrateBackend`). {@link GitWriteSubstrate} is the default, git-only
+// MVP implementation: it composes append-via-commit, branch creation, checkout,
+// and merge primitives over a local working copy using an injectable
+// {@link GitRunner} (so tests drive a local temp repo without any network).
+
+import { execFile } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { hardenedGitArgs, redactUrlUserinfo, type GitRunner } from "../binding/index.ts";
+
+const execFileAsync = promisify(execFile);
+
+/** Error thrown when a substrate write/governance git operation fails. */
+export class SubstrateWriteError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "SubstrateWriteError";
+  }
+}
+
+const defaultWriteGitRunner: GitRunner = async (args, cwd) => {
+  const hardened = hardenedGitArgs(args);
+  try {
+    const { stdout } = await execFileAsync("git", hardened, {
+      cwd,
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    return stdout;
+  } catch (cause) {
+    const label = `git ${hardened.map(redactUrlUserinfo).join(" ")}`;
+    throw new SubstrateWriteError(`substrate git command failed: ${label}`, { cause });
+  }
+};
+
+/** The identity a commit/merge is attributed to. */
+export interface CommitAuthor {
+  readonly name: string;
+  readonly email: string;
+}
+
+/**
+ * The write seam the governance layer composes. A future mutable/PII backend can
+ * implement this interface differently (e.g. against a database with real
+ * erasure) without the writer or its callers changing. Every method operates on
+ * a single logical substrate working copy rooted at {@link rootPath}.
+ */
+export interface WriteSubstrate {
+  /** Absolute path to the substrate working copy. */
+  readonly rootPath: string;
+  /** Write `content` to `relPath` (relative to {@link rootPath}), creating dirs. */
+  writeRecordFile(relPath: string, content: string): Promise<void>;
+  /** Read the file at `relPath` as it exists on `ref`, without touching the tree. */
+  readFileAtRef(ref: string, relPath: string): Promise<string>;
+  /**
+   * The substrate-relative paths changed on `branch` relative to its merge-base
+   * with `baseRef` — i.e. exactly the set of files a `baseRef`-into-`branch` merge
+   * would introduce/modify. Lets a caller assert a merge is limited to expected
+   * files before performing it.
+   */
+  diffPaths(baseRef: string, branch: string): Promise<readonly string[]>;
+  /** The name of the currently checked-out branch. */
+  currentBranch(): Promise<string>;
+  /** Create (or reset) branch `name` at `from` and check it out. */
+  createBranch(name: string, from: string): Promise<void>;
+  /** Check out an existing branch/ref. */
+  checkout(ref: string): Promise<void>;
+  /**
+   * Recover the shared working copy to a pristine checkout of `ref`: force-checks
+   * out `ref` — moving HEAD and discarding ALL tracked modifications across the
+   * whole working copy, not only those under `pathspec` — then removes untracked
+   * files/dirs UNDER `pathspec`, leaving untracked files OUTSIDE `pathspec`
+   * untouched. The broad tracked-file reset is intended: the substrate working
+   * copy is a single-writer, serialised recovery seam, so callers must not keep
+   * unrelated tracked edits in it across a write that might fail.
+   */
+  restoreClean(ref: string, pathspec: string): Promise<void>;
+  /**
+   * Stage the changes UNDER `pathspec` (only) and commit them as `author`;
+   * returns the new commit sha. Staging is deliberately scoped to the caller's
+   * record path(s) — never a blanket `git add -A` — so an unrelated change
+   * elsewhere in the shared working copy can never be swept into a commit that
+   * the per-record PII guard only inspected the record content for.
+   */
+  stageAndCommit(pathspec: string, message: string, author: CommitAuthor): Promise<string>;
+  /** Merge `branch` into the current branch as `author`; returns the merge sha. */
+  mergeBranch(branch: string, message: string, author: CommitAuthor): Promise<string>;
+  /** `true` iff a local branch named `name` exists. */
+  branchExists(name: string): Promise<boolean>;
+  /**
+   * `true` iff `commitish` is an ancestor of (or equal to) `ref` — i.e. landed
+   * on it. Both operands are git commit-ish inputs: a raw sha, a branch name, or
+   * any other ref resolvable to a commit. `ContextWriter.isRatified` deliberately
+   * passes a branch ref (the proposal branch tip) here to bind the check to the
+   * real tip rather than a caller-supplied sha, so implementations MUST resolve
+   * `commitish` as a general ref, not assume a sha-only input.
+   */
+  isMerged(commitish: string, ref: string): Promise<boolean>;
+}
+
+/**
+ * The default git-only write substrate. Composes commit/branch/merge primitives
+ * over a local working copy. Commit author identity is passed per-commit via
+ * `-c user.name=… -c user.email=…`, so a bare temp repo with no configured user
+ * still commits cleanly (and every write path can attribute a bot vs. human
+ * author independently).
+ */
+export class GitWriteSubstrate implements WriteSubstrate {
+  readonly rootPath: string;
+  readonly #git: GitRunner;
+
+  constructor(rootPath: string, gitRunner: GitRunner = defaultWriteGitRunner) {
+    if (!isAbsolute(rootPath)) {
+      throw new SubstrateWriteError(`substrate rootPath must be absolute: ${rootPath}`);
+    }
+    this.rootPath = rootPath;
+    this.#git = gitRunner;
+  }
+
+  async writeRecordFile(relPath: string, content: string): Promise<void> {
+    const target = this.#resolveWithinRoot(relPath);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, content, "utf8");
+  }
+
+  async readFileAtRef(ref: string, relPath: string): Promise<string> {
+    // Read the blob at `ref:relPath` via `git show` — a pure read that never
+    // mutates the working tree (no checkout), so a failed read/guard cannot leave
+    // the shared working copy on the wrong branch. `#resolveWithinRoot` still
+    // rejects any traversal path before it reaches git.
+    this.#resolveWithinRoot(relPath);
+    return this.#git(["show", "--end-of-options", `${ref}:${relPath}`], this.rootPath);
+  }
+
+  async diffPaths(baseRef: string, branch: string): Promise<readonly string[]> {
+    // `base...branch` (symmetric-difference range) lists files changed on `branch`
+    // since it forked from `baseRef` — precisely what a merge of `branch` would
+    // bring onto `baseRef`. `-z` NUL-delimits paths so unusual names never split
+    // wrong; `--end-of-options` stops a ref that looks like a flag being parsed.
+    const out = await this.#git(
+      ["diff", "--name-only", "-z", "--end-of-options", `${baseRef}...${branch}`],
+      this.rootPath,
+    );
+    return out.split("\0").filter((p) => p.length > 0);
+  }
+
+  // Resolve a caller-supplied substrate-relative path to an absolute path,
+  // refusing anything that escapes the substrate root. Defence in depth: the
+  // layout helper already produces traversal-safe paths, but no read/write may
+  // ever leave the substrate root regardless of the relPath handed in.
+  #resolveWithinRoot(relPath: string): string {
+    const target = resolve(this.rootPath, relPath);
+    const rel = relative(this.rootPath, target);
+    if (rel === "" || rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel)) {
+      throw new SubstrateWriteError(`record path escapes the substrate root: ${relPath}`);
+    }
+    return target;
+  }
+
+  async currentBranch(): Promise<string> {
+    const out = await this.#git(["rev-parse", "--abbrev-ref", "HEAD"], this.rootPath);
+    return out.trim();
+  }
+
+  async createBranch(name: string, from: string): Promise<void> {
+    // `checkout -B` creates or resets the branch to `from` and checks it out.
+    // `--end-of-options` stops an option-style ref from being parsed as a flag.
+    await this.#git(["checkout", "-B", name, "--end-of-options", from], this.rootPath);
+  }
+
+  async checkout(ref: string): Promise<void> {
+    await this.#git(["checkout", "--end-of-options", ref], this.rootPath);
+  }
+
+  async restoreClean(ref: string, pathspec: string): Promise<void> {
+    // `checkout --force <ref>` moves HEAD to `ref` and discards modifications to ALL
+    // tracked files across the working copy (not just under `pathspec`) — the full
+    // reset a post-failure recovery of this single-writer working copy wants. `clean
+    // -fd` then removes leftover UNTRACKED files/dirs, scoped to `pathspec` (the
+    // record layout root) so it never touches untracked files elsewhere. `--` ends
+    // option parsing before the pathspec so a path that looks like a flag is never
+    // misread as one.
+    await this.#git(["checkout", "--force", "--end-of-options", ref], this.rootPath);
+    await this.#git(["clean", "-fd", "--", pathspec], this.rootPath);
+  }
+
+  async stageAndCommit(
+    pathspec: string,
+    message: string,
+    author: CommitAuthor,
+  ): Promise<string> {
+    // Stage ONLY the caller's record path(s) — `add -A -- <pathspec>` — never a
+    // blanket `git add -A`. A blanket stage would sweep ANY unrelated tracked or
+    // untracked change in the shared single-writer working copy into this commit,
+    // bypassing the per-record PII guard that inspected the record content alone
+    // (and risking committing stray residue outside the record layout). `-A` still
+    // captures adds/modifies/deletes, but confined to `pathspec`; `--` ends option
+    // parsing so a path that looks like a flag is never misread.
+    await this.#git(["add", "-A", "--", pathspec], this.rootPath);
+    await this.#git(
+      [
+        "-c",
+        `user.name=${author.name}`,
+        "-c",
+        `user.email=${author.email}`,
+        "commit",
+        "--no-gpg-sign",
+        "--allow-empty",
+        "-m",
+        message,
+      ],
+      this.rootPath,
+    );
+    return this.#revParse("HEAD");
+  }
+
+  async mergeBranch(branch: string, message: string, author: CommitAuthor): Promise<string> {
+    // `--no-ff` always records a merge commit, so ratification (a merge) is a
+    // distinct, auditable event even when the branch could fast-forward.
+    try {
+      await this.#git(
+        [
+          "-c",
+          `user.name=${author.name}`,
+          "-c",
+          `user.email=${author.email}`,
+          "merge",
+          "--no-ff",
+          "--no-gpg-sign",
+          "-m",
+          message,
+          "--end-of-options",
+          branch,
+        ],
+        this.rootPath,
+      );
+    } catch (cause) {
+      // A failed merge (e.g. a content conflict) leaves the working tree in a
+      // conflicted MERGE_HEAD state. Abort it best-effort so the shared working
+      // copy is clean for the next serialised operation, then surface the cause.
+      await this.#git(["merge", "--abort"], this.rootPath).catch(() => {});
+      throw cause;
+    }
+    return this.#revParse("HEAD");
+  }
+
+  async branchExists(name: string): Promise<boolean> {
+    try {
+      await this.#git(["show-ref", "--verify", "--quiet", `refs/heads/${name}`], this.rootPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async isMerged(commitish: string, ref: string): Promise<boolean> {
+    try {
+      // `--end-of-options` (as every other ref-passing call in this file) stops an
+      // option-style `commitish`/`ref` (e.g. a caller-supplied baseBranch override)
+      // from being parsed as a `git merge-base` flag rather than a revision.
+      await this.#git(
+        ["merge-base", "--is-ancestor", "--end-of-options", commitish, ref],
+        this.rootPath,
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async #revParse(ref: string): Promise<string> {
+    // `git rev-parse` echoes `--end-of-options` back as output, so it is omitted
+    // here; `ref` on this path is always an internally-produced value (`HEAD`).
+    const out = await this.#git(["rev-parse", ref], this.rootPath);
+    return out.trim();
+  }
+}
+
+/** Join a substrate-relative path onto an absolute root (POSIX-in, native-out). */
+export function substratePath(root: string, relPath: string): string {
+  return join(root, relPath);
+}