@nanobpm/urban 0.68.0 → 0.69.0

package/dist/context/binding/index.d.ts

@@ -1,5 +1,5 @@
 export { type ContextBinding, ContextBindingError, isContextBinding, parseContextBinding, } from "./descriptor.ts";
 export { type ContextIdentity, contextIdentityKey, resolveContextIdentity, sameContext, } from "./identity.ts";
 export { type ResolvedContextHandle, type SubstrateBackend, type SubstrateResolveOptions, } from "./backend.ts";
-export { GitSubstrateBackend, type GitRunner, GIT_SAFETY_CONFIG, hardenedGitArgs, SubstrateResolveError, } from "./git-backend.ts";
+export { GitSubstrateBackend, type GitRunner, GIT_SAFETY_CONFIG, hardenedGitArgs, redactUrlUserinfo, SubstrateResolveError, } from "./git-backend.ts";
 export { ContextResolver, type ContextResolverOptions, type ResolveOptions, defaultContextCacheRoot, resolveContextBinding, } from "./resolver.ts";

package/dist/context/binding/index.js

@@ -10,5 +10,5 @@
 // future PII/mutable or self-hosted backend.
 export { ContextBindingError, isContextBinding, parseContextBinding, } from "./descriptor.js";
 export { contextIdentityKey, resolveContextIdentity, sameContext, } from "./identity.js";
-export { GitSubstrateBackend, GIT_SAFETY_CONFIG, hardenedGitArgs, SubstrateResolveError, } from "./git-backend.js";
+export { GitSubstrateBackend, GIT_SAFETY_CONFIG, hardenedGitArgs, redactUrlUserinfo, SubstrateResolveError, } from "./git-backend.js";
 export { ContextResolver, defaultContextCacheRoot, resolveContextBinding, } from "./resolver.js";

package/dist/context/git/guard-registry.d.ts

@@ -0,0 +1,26 @@
+import type { PiiCandidate, PiiGuard } 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 declare class PreCommitGuardRegistry {
+    #private;
+    /**
+     * 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[]);
+    /** Register an ADDITIONAL guard. Cannot displace the mandatory default guard. */
+    register(guard: PiiGuard): void;
+    /** A snapshot of the registered guards, in run order (mandatory guard first). */
+    get guards(): readonly PiiGuard[];
+    /**
+     * 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;
+}

package/dist/context/git/guard-registry.js

@@ -0,0 +1,52 @@
+// 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 { preCommitPiiGuard } from "../pii/index.js";
+/**
+ * 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.
+    #guards;
+    /**
+     * 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 = []) {
+        this.#guards = [preCommitPiiGuard, ...additional];
+    }
+    /** Register an ADDITIONAL guard. Cannot displace the mandatory default guard. */
+    register(guard) {
+        this.#guards.push(guard);
+    }
+    /** A snapshot of the registered guards, in run order (mandatory guard first). */
+    get guards() {
+        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) {
+        for (const guard of this.#guards) {
+            guard.assert(candidate);
+        }
+    }
+}

package/dist/context/git/index.d.ts

@@ -1 +1,4 @@
-export {};
+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/dist/context/git/index.js

@@ -1 +1,21 @@
-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.js";
+export { PreCommitGuardRegistry } from "./guard-registry.js";
+export { GitWriteSubstrate, SubstrateWriteError, substratePath, } from "./substrate.js";
+export { ContextWriter, DEFAULT_BOT_AUTHOR, DEFAULT_WRITE_AUTHOR, GovernanceError, serialiseRecord, } from "./writer.js";

package/dist/context/git/layout.d.ts

@@ -0,0 +1,46 @@
+import type { MemoryRecord, MemoryScope } from "../schema/index.ts";
+/** The directory (relative to the substrate root) all records live under. */
+export declare const LAYOUT_ROOT: "records";
+/** The on-disk extension every serialised record file carries. */
+export declare const RECORD_FILE_EXTENSION: ".json";
+/**
+ * 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 declare const UNSCOPED_BUCKET: "_";
+/**
+ * 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 declare function sanitizeSegment(value: string): string;
+/** The directory (relative to the substrate root) that holds a whole scope. */
+export declare function scopeDir(scope: MemoryScope): string;
+/**
+ * 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 declare function recordDir(scope: MemoryScope, scopeRef?: string): string;
+/**
+ * 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 declare function recordRelativePath(record: MemoryRecord): string;
+/**
+ * `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 declare function isRecordPath(relPath: string): boolean;

package/dist/context/git/layout.js

@@ -0,0 +1,96 @@
+// 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";
+/** The directory (relative to the substrate root) all records live under. */
+export const LAYOUT_ROOT = "records";
+/** The on-disk extension every serialised record file carries. */
+export const RECORD_FILE_EXTENSION = ".json";
+/**
+ * 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 = "_";
+/**
+ * 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) {
+    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) {
+    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) {
+    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, scopeRef) {
+    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) {
+    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) {
+    const normalised = relPath.replace(/\\/g, "/").replace(/^\.\//, "");
+    return (normalised.startsWith(`${LAYOUT_ROOT}/`) &&
+        normalised.endsWith(RECORD_FILE_EXTENSION) &&
+        !normalised.includes(".."));
+}

package/dist/context/git/substrate.d.ts

@@ -0,0 +1,95 @@
+import { type GitRunner } from "../binding/index.ts";
+/** Error thrown when a substrate write/governance git operation fails. */
+export declare class SubstrateWriteError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** 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 declare class GitWriteSubstrate implements WriteSubstrate {
+    #private;
+    readonly rootPath: string;
+    constructor(rootPath: string, gitRunner?: GitRunner);
+    writeRecordFile(relPath: string, content: string): Promise<void>;
+    readFileAtRef(ref: string, relPath: string): Promise<string>;
+    diffPaths(baseRef: string, branch: string): Promise<readonly string[]>;
+    currentBranch(): Promise<string>;
+    createBranch(name: string, from: string): Promise<void>;
+    checkout(ref: string): Promise<void>;
+    restoreClean(ref: string, pathspec: string): Promise<void>;
+    stageAndCommit(pathspec: string, message: string, author: CommitAuthor): Promise<string>;
+    mergeBranch(branch: string, message: string, author: CommitAuthor): Promise<string>;
+    branchExists(name: string): Promise<boolean>;
+    isMerged(commitish: string, ref: string): Promise<boolean>;
+}
+/** Join a substrate-relative path onto an absolute root (POSIX-in, native-out). */
+export declare function substratePath(root: string, relPath: string): string;

package/dist/context/git/substrate.js

@@ -0,0 +1,190 @@
+// 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 } from "../binding/index.js";
+const execFileAsync = promisify(execFile);
+/** Error thrown when a substrate write/governance git operation fails. */
+export class SubstrateWriteError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "SubstrateWriteError";
+    }
+}
+const defaultWriteGitRunner = 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 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 {
+    rootPath;
+    #git;
+    constructor(rootPath, gitRunner = defaultWriteGitRunner) {
+        if (!isAbsolute(rootPath)) {
+            throw new SubstrateWriteError(`substrate rootPath must be absolute: ${rootPath}`);
+        }
+        this.rootPath = rootPath;
+        this.#git = gitRunner;
+    }
+    async writeRecordFile(relPath, content) {
+        const target = this.#resolveWithinRoot(relPath);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content, "utf8");
+    }
+    async readFileAtRef(ref, relPath) {
+        // 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, branch) {
+        // `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) {
+        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() {
+        const out = await this.#git(["rev-parse", "--abbrev-ref", "HEAD"], this.rootPath);
+        return out.trim();
+    }
+    async createBranch(name, from) {
+        // `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) {
+        await this.#git(["checkout", "--end-of-options", ref], this.rootPath);
+    }
+    async restoreClean(ref, pathspec) {
+        // `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, message, author) {
+        // 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, message, author) {
+        // `--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) {
+        try {
+            await this.#git(["show-ref", "--verify", "--quiet", `refs/heads/${name}`], this.rootPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async isMerged(commitish, ref) {
+        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) {
+        // `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, relPath) {
+    return join(root, relPath);
+}