@nanobpm/urban 0.68.1 → 0.69.1

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

@@ -0,0 +1,154 @@
+import type { PiiGuard } from "../pii/index.ts";
+import { type MemoryRecord } from "../schema/index.ts";
+import { type CommitAuthor, type WriteSubstrate } from "./substrate.ts";
+/** Thrown when a write violates the PR-governance rules of this layer. */
+export declare class GovernanceError extends Error {
+    constructor(message: string);
+}
+/** The default author attributed to direct (human/measured/instance) appends. */
+export declare const DEFAULT_WRITE_AUTHOR: CommitAuthor;
+/** The bot author attributed to proposed priors and their ratifying merges. */
+export declare const DEFAULT_BOT_AUTHOR: CommitAuthor;
+/**
+ * The single source of truth for the proposal (bot "PR") branch namespace.
+ * `proposePrior` creates branches under it and `ratify` refuses to merge anything
+ * outside it, so an arbitrary caller-named branch can never be ratified.
+ */
+export declare const PROPOSAL_BRANCH_PREFIX: "context/proposal/";
+/** The minimal resolved-handle shape the writer consumes (from S1). */
+export interface ResolvedSubstrateHandle {
+    /**
+     * Absolute path to the local substrate working copy. MUST be absolute —
+     * `GitWriteSubstrate` rejects a relative root. S1's `ResolvedContextHandle`
+     * guarantees this, but the requirement is not obvious from this type alone.
+     */
+    readonly localPath: string;
+    readonly ref: string;
+}
+/** Options for {@link ContextWriter}. All optional; the defaults are safe. */
+export interface ContextWriterOptions {
+    /** Override the write substrate (seam for a future mutable/PII backend). */
+    readonly substrate?: WriteSubstrate;
+    /**
+     * ADDITIONAL pre-commit guards. The mandatory S6 PII guard is always present
+     * (see {@link PreCommitGuardRegistry}); these can only make enforcement
+     * stricter, never bypass it.
+     */
+    readonly guards?: readonly PiiGuard[];
+    /**
+     * The base branch records land on / are proposed against. Defaults to the
+     * resolved substrate handle's `ref` (the S1-resolved branch), falling back to
+     * the substrate's currently checked-out branch only when the handle carries no
+     * ref.
+     */
+    readonly baseBranch?: string;
+    /** Author for direct appends. Defaults to {@link DEFAULT_WRITE_AUTHOR}. */
+    readonly author?: CommitAuthor;
+    /** Author for proposed priors + merges. Defaults to {@link DEFAULT_BOT_AUTHOR}. */
+    readonly botAuthor?: CommitAuthor;
+}
+/** The outcome of a direct append (ratified immediately on the base branch). */
+export interface AppendResult {
+    /** Substrate-relative path the record was written to (see the layout helper). */
+    readonly path: string;
+    /** The commit that persisted the record on its write branch. */
+    readonly commit: string;
+    /** The merge commit that landed it on the base branch. */
+    readonly mergeCommit: string;
+    /** The base branch the record now lives on. */
+    readonly branch: string;
+    /** Always `true`: a direct append is ratified on landing. */
+    readonly ratified: true;
+}
+/**
+ * The outcome of a proposed prior (a bot "PR"). The record lives on
+ * {@link branch} only — it is NOT on the base branch until {@link ContextWriter.ratify}
+ * merges it. Pass this handle back to `ratify` to accept the proposal.
+ */
+export interface ProposalResult {
+    /** Substrate-relative path the record was written to on the proposal branch. */
+    readonly path: string;
+    /** The commit on the proposal branch that carries the proposed record. */
+    readonly commit: string;
+    /** The proposal (bot "PR") branch. Not merged until ratified. */
+    readonly branch: string;
+    /** The base branch this proposal targets. */
+    readonly baseBranch: string;
+    /** A stable id for the proposal (useful for logging/correlation). */
+    readonly proposalId: string;
+    /** Always `false` on creation: a proposal is an unratified hypothesis. */
+    readonly ratified: false;
+}
+/** The outcome of ratifying (merging) a proposed prior onto the base branch. */
+export interface RatifyResult {
+    /** The merge commit that landed the proposal on the base branch. */
+    readonly mergeCommit: string;
+    /** The base branch the proposal was ratified onto. */
+    readonly baseBranch: string;
+}
+/**
+ * The git-as-system-of-record writer. One instance is bound to one resolved
+ * substrate handle. Operations are serialised within the instance (a single
+ * working copy has one working tree), so interleaved calls never race each
+ * other's checkout/commit; each still lands on its own branch, so nothing is
+ * clobbered.
+ */
+export declare class ContextWriter {
+    #private;
+    constructor(handle: ResolvedSubstrateHandle, options?: ContextWriterOptions);
+    /** The pre-commit guards that run before every write (mandatory PII first). */
+    get guards(): readonly PiiGuard[];
+    /**
+     * APPEND-VIA-COMMIT (direct, ratified-on-landing) write path for
+     * human/measured/instance records. Validates the record against the S2 schema
+     * (including the forgery-resistance invariants), runs the mandatory PII guard,
+     * then commits it on a fresh write branch and merges it onto the base branch.
+     *
+     * `agent-retro` records are REJECTED here by construction: an agent proposal is
+     * a hypothesis that must go through governance ({@link proposePrior} +
+     * {@link ratify}), never a direct append. This is what stops an unratified
+     * prior from landing on the authoritative line without a merge.
+     */
+    appendRecord(input: unknown): Promise<AppendResult>;
+    /**
+     * PR-GOVERNANCE write path: write a record as a PROPOSED prior on a bot branch
+     * (the git-only stand-in for a bot PR). The record is committed on its own
+     * branch and left UNMERGED, so it is not on the base branch — an unratified
+     * hypothesis. Ratify it with {@link ratify}.
+     *
+     * This is the mandatory path for `agent-retro` records and is available for any
+     * record a caller wants to route through governance rather than land directly.
+     * The mandatory PII guard runs here too, before the commit.
+     */
+    proposePrior(input: unknown): Promise<ProposalResult>;
+    /**
+     * Ratify a proposed prior by MERGING its bot branch onto the base branch. After
+     * this the proposal's record is on the authoritative line. Ratification records
+     * that the hypothesis was ACCEPTED; it does not (and cannot) upgrade an
+     * `agent-retro` record's authority to `authoritative` — the S2 schema forbids
+     * that, so the record remains an accepted hypothesis, never a forged fact.
+     */
+    ratify(proposal: ProposalResult): Promise<RatifyResult>;
+    /**
+     * `true` iff the proposal has been ratified (its proposal branch has been merged
+     * onto the base branch). A never-ratified proposal reads back as `false`, so an
+     * unmerged prior can never masquerade as a ratified one.
+     *
+     * The check requires the proposal branch to STILL EXIST under the proposal
+     * namespace (that existence is a deliberate part of the non-forgeability guard —
+     * see below). A proposal whose branch was merged and then DELETED therefore reads
+     * back `false`: this is a governance status query over live proposal branches, not
+     * a historical "was this commit ever merged" audit.
+     */
+    isRatified(proposal: ProposalResult): Promise<boolean>;
+}
+/**
+ * Serialise a record to deterministic, pretty-printed JSON with a trailing LF.
+ * Keys are emitted in a canonical (sorted) order so two semantically identical
+ * records serialise byte-for-byte identically regardless of the key INSERTION
+ * order they were constructed with — `JSON.stringify` otherwise preserves
+ * insertion order, which would let equal records produce differing output. The
+ * key set is DERIVED from the record itself (not a hand-maintained list), so a
+ * newly added field is never silently dropped from the serialised form.
+ */
+export declare function serialiseRecord(record: MemoryRecord): string;

package/dist/context/git/writer.js

@@ -0,0 +1,395 @@
+// Slice S3 (git/governance) — git-as-system-of-record WRITE + governance.
+//
+// Builds the write and governance layer on top of a resolved substrate handle
+// (from S1), the validated record schema (from S2), and the mandatory PII guard
+// (from S6). It does NOT re-implement clone/pull (S1), the record schema (S2),
+// or the PII classifier/guard (S6) — it composes them.
+//
+// Governance model (git-only MVP, no external services):
+//
+//  - APPEND-VIA-COMMIT: a validated record is persisted as a commit on the base
+//    branch (append-only provenance). Used for human/measured/instance records —
+//    facts and human-authored priors that land directly.
+//  - PR-GOVERNANCE: an `agent-retro` prior is a PROPOSAL, written as a BOT branch
+//    (the git-only stand-in for a bot PR) that is NOT on the base branch until it
+//    is MERGED. A merge == ratification. Because the S2 schema forbids
+//    `agent-retro` from ever being `authoritative`, an unmerged (or even a
+//    merged) agent-retro record can never present as a measured/authoritative
+//    fact — governance decides only whether the *hypothesis* is accepted onto the
+//    authoritative line, never whether it becomes a fact.
+//  - CONCURRENCY: within a SINGLE ContextWriter instance, writes are serialised
+//    on the shared working tree (see #queue) and each still lands on its own
+//    uniquely-named branch, so interleaved calls never clobber each other and
+//    disjoint records merge cleanly. This guarantee is PER-INSTANCE: two
+//    ContextWriter instances (or separate processes) pointing at the SAME working
+//    copy are not coordinated and can interleave checkouts/commits and corrupt the
+//    tree — use a separate clone (or external locking) per concurrent writer.
+//  - PII BY CONSTRUCTION: the mandatory S6 guard is pre-registered in the guard
+//    registry and run before EVERY commit on the default code path. A caller that
+//    supplies no special wiring still gets it, so a PII-carrying write is rejected
+//    before it is committed.
+import { randomUUID } from "node:crypto";
+import { assertMemoryRecord, } from "../schema/index.js";
+import { PreCommitGuardRegistry } from "./guard-registry.js";
+import { LAYOUT_ROOT, recordRelativePath } from "./layout.js";
+import { GitWriteSubstrate, } from "./substrate.js";
+/** Thrown when a write violates the PR-governance rules of this layer. */
+export class GovernanceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GovernanceError";
+    }
+}
+/** The default author attributed to direct (human/measured/instance) appends. */
+export const DEFAULT_WRITE_AUTHOR = {
+    name: "nano-context",
+    email: "context@nanobpm.local",
+};
+/** The bot author attributed to proposed priors and their ratifying merges. */
+export const DEFAULT_BOT_AUTHOR = {
+    name: "nano-context-bot",
+    email: "context-bot@nanobpm.local",
+};
+/**
+ * The single source of truth for the proposal (bot "PR") branch namespace.
+ * `proposePrior` creates branches under it and `ratify` refuses to merge anything
+ * outside it, so an arbitrary caller-named branch can never be ratified.
+ */
+export const PROPOSAL_BRANCH_PREFIX = "context/proposal/";
+/**
+ * The git-as-system-of-record writer. One instance is bound to one resolved
+ * substrate handle. Operations are serialised within the instance (a single
+ * working copy has one working tree), so interleaved calls never race each
+ * other's checkout/commit; each still lands on its own branch, so nothing is
+ * clobbered.
+ */
+export class ContextWriter {
+    #substrate;
+    #guards;
+    #baseBranchOverride;
+    #author;
+    #botAuthor;
+    // A promise chain that serialises mutating operations on the shared working
+    // tree so two in-flight writes cannot interleave their checkout/commit steps.
+    #queue = Promise.resolve();
+    constructor(handle, options = {}) {
+        this.#substrate = options.substrate ?? new GitWriteSubstrate(handle.localPath);
+        // The registry ALWAYS contains the mandatory PII guard; `guards` can only add.
+        this.#guards = new PreCommitGuardRegistry(options.guards ?? []);
+        this.#baseBranchOverride = options.baseBranch ?? (handle.ref || undefined);
+        this.#author = options.author ?? DEFAULT_WRITE_AUTHOR;
+        this.#botAuthor = options.botAuthor ?? DEFAULT_BOT_AUTHOR;
+    }
+    /** The pre-commit guards that run before every write (mandatory PII first). */
+    get guards() {
+        return this.#guards.guards;
+    }
+    /**
+     * APPEND-VIA-COMMIT (direct, ratified-on-landing) write path for
+     * human/measured/instance records. Validates the record against the S2 schema
+     * (including the forgery-resistance invariants), runs the mandatory PII guard,
+     * then commits it on a fresh write branch and merges it onto the base branch.
+     *
+     * `agent-retro` records are REJECTED here by construction: an agent proposal is
+     * a hypothesis that must go through governance ({@link proposePrior} +
+     * {@link ratify}), never a direct append. This is what stops an unratified
+     * prior from landing on the authoritative line without a merge.
+     */
+    appendRecord(input) {
+        return this.#serialise(async () => {
+            const record = assertMemoryRecord(input);
+            this.#assertDirectlyAppendable(record.provenance);
+            // MANDATORY PII enforcement BY CONSTRUCTION — before ANY commit.
+            this.#guards.assertAll(record);
+            const base = await this.#resolveBaseBranch();
+            const relPath = recordRelativePath(record);
+            const writeBranch = this.#branchName("append", record.id);
+            // A mid-operation failure (createBranch/write/commit/merge) must never leave
+            // the SHARED working tree parked on a transient write branch with a
+            // half-written record for the next serialised call to inherit; the `finally`
+            // best-effort restores the resolved base and discards any residue.
+            // Reduce the schema-validated (non-empty-string only) `id` to a single
+            // commit-message line before interpolation, so a newline in `id` can never
+            // inject extra commit-message lines or a forged trailer. Derived once and
+            // reused for both the append commit and its merge subject.
+            const idLine = commitLine(record.id);
+            try {
+                await this.#substrate.createBranch(writeBranch, base);
+                await this.#substrate.writeRecordFile(relPath, serialiseRecord(record));
+                const commit = await this.#substrate.stageAndCommit(relPath, `context(append): ${record.provenance}/${record.scope} ${idLine}`, this.#author);
+                await this.#substrate.checkout(base);
+                const mergeCommit = await this.#substrate.mergeBranch(writeBranch, `context(append): land ${idLine} onto ${base}`, this.#author);
+                return { path: relPath, commit, mergeCommit, branch: base, ratified: true };
+            }
+            finally {
+                await this.#restoreBase(base);
+            }
+        });
+    }
+    /**
+     * PR-GOVERNANCE write path: write a record as a PROPOSED prior on a bot branch
+     * (the git-only stand-in for a bot PR). The record is committed on its own
+     * branch and left UNMERGED, so it is not on the base branch — an unratified
+     * hypothesis. Ratify it with {@link ratify}.
+     *
+     * This is the mandatory path for `agent-retro` records and is available for any
+     * record a caller wants to route through governance rather than land directly.
+     * The mandatory PII guard runs here too, before the commit.
+     */
+    proposePrior(input) {
+        return this.#serialise(async () => {
+            const record = assertMemoryRecord(input);
+            // MANDATORY PII enforcement BY CONSTRUCTION — before ANY commit.
+            this.#guards.assertAll(record);
+            const base = await this.#resolveBaseBranch();
+            const relPath = recordRelativePath(record);
+            const proposalId = `${sanitizeRef(record.id)}-${randomUUID().slice(0, 8)}`;
+            const proposalBranch = `${PROPOSAL_BRANCH_PREFIX}${proposalId}`;
+            // As with `appendRecord`, a mid-operation failure must not strand the shared
+            // working tree on the proposal branch; the `finally` restores the base. The
+            // proposal COMMIT is preserved on its own branch (a hypothesis until
+            // ratified) — restoring the base only moves the working tree off it, it does
+            // not discard the committed proposal.
+            try {
+                await this.#substrate.createBranch(proposalBranch, base);
+                await this.#substrate.writeRecordFile(relPath, serialiseRecord(record));
+                const commit = await this.#substrate.stageAndCommit(relPath, `context(propose): ${record.provenance}/${record.scope} ${commitLine(record.id)} [hypothesis]`, this.#botAuthor);
+                return {
+                    path: relPath,
+                    commit,
+                    branch: proposalBranch,
+                    baseBranch: base,
+                    proposalId,
+                    ratified: false,
+                };
+            }
+            finally {
+                // Leave the proposal branch UNMERGED — restoring the base only checks the
+                // working tree back onto it; the proposal stays an unratified hypothesis.
+                await this.#restoreBase(base);
+            }
+        });
+    }
+    /**
+     * Ratify a proposed prior by MERGING its bot branch onto the base branch. After
+     * this the proposal's record is on the authoritative line. Ratification records
+     * that the hypothesis was ACCEPTED; it does not (and cannot) upgrade an
+     * `agent-retro` record's authority to `authoritative` — the S2 schema forbids
+     * that, so the record remains an accepted hypothesis, never a forged fact.
+     */
+    ratify(proposal) {
+        return this.#serialise(async () => {
+            if (!(await this.#substrate.branchExists(proposal.branch))) {
+                throw new GovernanceError(`cannot ratify: proposal branch ${proposal.branch} does not exist.`);
+            }
+            // DEFENCE 1 — only a branch in the proposal namespace may be ratified, so a
+            // caller cannot merge an arbitrary local branch onto the authoritative line.
+            if (!proposal.branch.startsWith(PROPOSAL_BRANCH_PREFIX)) {
+                throw new GovernanceError(`cannot ratify: ${proposal.branch} is not a proposal branch ` +
+                    `(expected a ${PROPOSAL_BRANCH_PREFIX}* branch).`);
+            }
+            // DEFENCE 2 — the merge target is the writer's OWN resolved base branch, never
+            // a caller-supplied one. `ProposalResult` is a plain object, so a consumer can
+            // mutate `proposal.baseBranch` to steer the merge onto a different line than
+            // this writer is bound to (undermining the "one resolved handle" contract).
+            // Resolve the base ourselves and reject any proposal that targets a different
+            // one; every downstream step (diff, checkout, merge) uses `base`, not the
+            // untrusted `proposal.baseBranch`.
+            const base = await this.#resolveBaseBranch();
+            if (proposal.baseBranch !== base) {
+                throw new GovernanceError(`cannot ratify: proposal targets base ${proposal.baseBranch}, but this ` +
+                    `writer is bound to ${base}. A proposal may only be ratified onto the ` +
+                    "base branch its writer resolved.");
+            }
+            // DEFENCE 3 — the merge must introduce EXACTLY the one proposed record file
+            // and nothing else. A proposal branch created/amended outside `proposePrior`
+            // could carry extra files (more records, or content outside the record
+            // layout) that a single-file re-read would never see; merging it would land
+            // that content UNGUARDED. Bounding the diff to `[proposal.path]` makes the
+            // file we re-guard below provably the ONLY candidate content being merged.
+            const changed = await this.#substrate.diffPaths(base, proposal.branch);
+            if (changed.length !== 1 || changed[0] !== proposal.path) {
+                throw new GovernanceError(`cannot ratify: proposal branch ${proposal.branch} changes ` +
+                    `${JSON.stringify(changed)}, expected exactly ["${proposal.path}"]. ` +
+                    "A ratifying merge may introduce only its single proposed record file.");
+            }
+            // The pre-commit guard is a NON-OPTIONAL step on EVERY write path (S6), and
+            // a ratifying merge is a write onto the authoritative line. The proposal
+            // branch content is untrusted here: re-read (at the ref, without mutating the
+            // working tree), re-validate against the S2 schema, and re-run the mandatory
+            // PII guard BEFORE merging, so a PII-carrying (or otherwise invalid) record
+            // can never be ratified onto the base branch.
+            const proposed = await this.#substrate.readFileAtRef(proposal.branch, proposal.path);
+            const record = assertMemoryRecord(parseRecordJson(proposed, proposal.path));
+            this.#guards.assertAll(record);
+            // DEFENCE 4 — the on-disk path must be the record's canonical layout path, so
+            // a record can never be ratified under a path that mismatches its validated
+            // scope/scopeRef/id (which would make it invisible to layout-based retrieval).
+            const canonical = recordRelativePath(record);
+            if (proposal.path !== canonical) {
+                throw new GovernanceError(`cannot ratify: proposal path ${proposal.path} does not match the ` +
+                    `record's canonical layout ${canonical}.`);
+            }
+            // A ratifying merge is a mutating op on the SHARED working tree, so — like
+            // `appendRecord` and `proposePrior` — its checkout+merge must run under a
+            // `finally` that restores the base. A `mergeBranch` failure (conflict, or a
+            // failed abort) would otherwise strand the tree on `base` mid-merge (or with
+            // conflict residue) for the next serialised op to inherit, breaking the
+            // class contract that every mutating op leaves the tree clean and on base.
+            try {
+                await this.#substrate.checkout(base);
+                // The merge commit message is derived from the GUARDED, schema-validated
+                // `record.id` (re-read and re-guarded above), never the caller-controlled
+                // `proposal.proposalId` on the plain-object handle. Interpolating the latter
+                // would let a consumer inject unguarded content (PII, newlines) into the
+                // commit message and bypass the mandatory PII guard, which only inspects
+                // record content. `commitLine` additionally collapses the id to a single
+                // line so even a guarded-but-newline-bearing id cannot inject a trailer.
+                const mergeCommit = await this.#substrate.mergeBranch(proposal.branch, `context(ratify): merge record ${commitLine(record.id)} onto ${base}`, this.#botAuthor);
+                return { mergeCommit, baseBranch: base };
+            }
+            finally {
+                await this.#restoreBase(base);
+            }
+        });
+    }
+    /**
+     * `true` iff the proposal has been ratified (its proposal branch has been merged
+     * onto the base branch). A never-ratified proposal reads back as `false`, so an
+     * unmerged prior can never masquerade as a ratified one.
+     *
+     * The check requires the proposal branch to STILL EXIST under the proposal
+     * namespace (that existence is a deliberate part of the non-forgeability guard —
+     * see below). A proposal whose branch was merged and then DELETED therefore reads
+     * back `false`: this is a governance status query over live proposal branches, not
+     * a historical "was this commit ever merged" audit.
+     */
+    isRatified(proposal) {
+        return this.#serialise(async () => {
+            // Derive the ancestry check from TRUSTED data only — NEVER the caller-controlled
+            // `proposal.commit`. `ProposalResult` is a plain object, so a consumer can set
+            // `commit` to any commit already reachable from base (e.g. base's own HEAD) and
+            // read back a forged `true`, even though the proposal branch was never merged.
+            // First bound the branch to the proposal namespace and require it to exist, so a
+            // caller cannot point us at an arbitrary already-merged local branch (mirrors
+            // ratify's DEFENCE 1). A branch that fails either check is, by definition, not a
+            // ratified proposal.
+            if (!proposal.branch.startsWith(PROPOSAL_BRANCH_PREFIX) ||
+                !(await this.#substrate.branchExists(proposal.branch))) {
+                return false;
+            }
+            // Bind the ancestry check to the writer's OWN resolved base, never the
+            // caller-supplied `proposal.baseBranch`. That field is a plain-object handle
+            // a consumer can mutate to any ref where the proposal branch tip happens to be
+            // an ancestor, which would report an UNratified hypothesis as ratified. Reject a
+            // retargeted proposal outright (same trust boundary as ratify's DEFENCE 2).
+            const base = await this.#resolveBaseBranch();
+            if (proposal.baseBranch !== base) {
+                throw new GovernanceError(`cannot check ratification: proposal targets base ${proposal.baseBranch}, ` +
+                    `but this writer is bound to ${base}.`);
+            }
+            // Check ancestry against the proposal BRANCH TIP (re-resolved by git), never the
+            // untrusted `proposal.commit` hash: a proposal is ratified iff its branch has
+            // been merged onto the resolved base.
+            return this.#substrate.isMerged(proposal.branch, base);
+        });
+    }
+    #assertDirectlyAppendable(provenance) {
+        if (provenance === "agent-retro") {
+            throw new GovernanceError("an 'agent-retro' prior is a hypothesis and must be routed through governance " +
+                "(proposePrior + ratify), not appended directly. Merging the proposal ratifies it.");
+        }
+    }
+    async #resolveBaseBranch() {
+        return this.#baseBranchOverride ?? (await this.#substrate.currentBranch());
+    }
+    // Best-effort return of the shared working tree to `base`, discarding any
+    // uncommitted/untracked residue under the record layout. Runs in the `finally`
+    // of each mutating op so a failure never strands the tree on a transient branch;
+    // swallows its own error so it can never mask the original operation's failure.
+    async #restoreBase(base) {
+        try {
+            await this.#substrate.restoreClean(base, LAYOUT_ROOT);
+        }
+        catch {
+            // best-effort only — never mask the original operation's error.
+        }
+    }
+    #branchName(kind, id) {
+        return `context/${kind}/${sanitizeRef(id)}-${randomUUID().slice(0, 8)}`;
+    }
+    // Serialise mutating operations: chain each onto the previous so the shared
+    // working tree is only ever touched by one operation at a time. Failures are
+    // isolated — a rejected operation does not poison the queue for the next call.
+    #serialise(op) {
+        const run = this.#queue.then(op, op);
+        this.#queue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+}
+/**
+ * Serialise a record to deterministic, pretty-printed JSON with a trailing LF.
+ * Keys are emitted in a canonical (sorted) order so two semantically identical
+ * records serialise byte-for-byte identically regardless of the key INSERTION
+ * order they were constructed with — `JSON.stringify` otherwise preserves
+ * insertion order, which would let equal records produce differing output. The
+ * key set is DERIVED from the record itself (not a hand-maintained list), so a
+ * newly added field is never silently dropped from the serialised form.
+ */
+export function serialiseRecord(record) {
+    return `${JSON.stringify(record, Object.keys(record).sort(), 2)}\n`;
+}
+/** Parse proposal-branch JSON, surfacing malformed content as a GovernanceError. */
+function parseRecordJson(content, path) {
+    try {
+        return JSON.parse(content);
+    }
+    catch (cause) {
+        throw new GovernanceError(`cannot ratify: proposed record at ${path} is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+}
+/**
+ * Reduce a value to a single commit-message line: collapse every whitespace run
+ * (spaces, tabs, and crucially CR/LF) to one space, trim, and cap the length. The
+ * record `id` is schema-validated only as a NON-EMPTY string, so without this a
+ * newline in `id` would split the commit subject and inject extra message lines or
+ * a forged trailer (e.g. a fake `Signed-off-by:`), and an unbounded-length `id`
+ * would produce a huge commit subject/merge message that degrades git and
+ * log/telemetry handling (the on-disk path is already length-bounded by
+ * `sanitizeSegment`). This is the categorical guard for both defect classes at
+ * every commit/merge interpolation site; distinct from `sanitizeRef`, which builds
+ * git-ref-safe branch segments.
+ *
+ * The schema validates `id` as a NON-EMPTY string (`length > 0`), which admits a
+ * whitespace-only id (e.g. `"   "`). Collapsing then trimming that yields the empty
+ * string, which would leave a commit/merge subject with a MISSING id — degrading
+ * auditability and log correlation. Fall back to an explicit placeholder so every
+ * subject carries an unambiguous, non-empty token in that case.
+ */
+const MAX_COMMIT_LINE = 120;
+const EMPTY_COMMIT_LINE = "<empty>";
+function commitLine(value) {
+    const collapsed = value.replace(/\s+/g, " ").trim();
+    if (collapsed.length === 0)
+        return EMPTY_COMMIT_LINE;
+    return collapsed.length > MAX_COMMIT_LINE
+        ? `${collapsed.slice(0, MAX_COMMIT_LINE - 1)}…`
+        : collapsed;
+}
+/** Reduce an id to a git-ref-safe branch segment (no `..`, spaces, or `~^:?*[`). */
+function sanitizeRef(id) {
+    let cleaned = id
+        .trim()
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/\.\.+/g, "-")
+        .replace(/^[-.]+|[-.]+$/g, "")
+        .slice(0, 60);
+    // A git ref component may not END in `.lock` (git reserves that suffix for its
+    // own lock files), so an id like `foo.lock` would otherwise yield a segment git
+    // rejects. Strip a trailing `.lock` and re-trim; loop so a pathological
+    // `foo.lock.lock` can't sneak one past a single pass.
+    while (/\.lock$/.test(cleaned)) {
+        cleaned = cleaned.replace(/\.lock$/, "").replace(/[-.]+$/g, "");
+    }
+    return cleaned === "" || cleaned === "." || cleaned === ".." ? "record" : cleaned;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.68.1",
+	"version": "0.69.1",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",
@@ -103,7 +103,7 @@
 		"@nanobpm/nano-sdk": "^1.2.5",
 		"@nanobpm/workflow": "^0.12.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
-		"create-urban-app": "^0.14.0",
+		"create-urban-app": "^0.15.0",
 		"yaml": "^2.9.0"
 	},
 	"devDependencies": {

package/src/context/binding/index.ts

@@ -34,6 +34,7 @@ export {
   type GitRunner,
   GIT_SAFETY_CONFIG,
   hardenedGitArgs,
+  redactUrlUserinfo,
   SubstrateResolveError,
 } from "./git-backend.ts";