@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/conductor/recovery-operations.js

@@ -1,7 +1,9 @@
 /**
  * Shared Bridge API operator-recovery operations (BAPI-872).
  *
- * Centralizes stop, abandon, and ticket unpark/adopt-current-head-and-unpark so
+ * Centralizes stop, abandon, ticket unpark/adopt-current-head-and-unpark, and
+ * (BAPI-1154) the three run-addressed repair verbs — scope-reparse,
+ * dispatch-remediation, merge-child — so
  * the conductor CLI recovery verbs (`recovery-cli.ts`) and `plane down`
  * (`../plane/shutdown.ts`, wired through `../plane/cli.ts`) share EXACTLY the
  * same stop semantics, and so this module — never a caller — owns every
@@ -15,7 +17,9 @@
  * callers: `recovery-cli.ts` and `plane/shutdown.ts`.
  */
 import { randomUUID } from "crypto";
-import { adoptCurrentHeadAndUnparkTicket, ConductorBridgeApiError, fetchEpicRunState, safeDiagnosticMessage, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, } from "./bridge-api-client.js";
+import { adoptCurrentHeadAndUnparkTicket, completeMergeChild, ConductorBridgeApiError, dispatchRemediation, fetchEpicRunState, mergeChild, safeDiagnosticMessage, scopeReparse, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, } from "./bridge-api-client.js";
+import { DEFAULT_GATE_NAME } from "./git-ci-types.js";
+import { resolveLocalMergeMethod, runApprovedLocalMerge } from "./local-merge.js";
 /**
  * Bounded total attempts for a ticket-recovery CAS retry loop. Each attempt
  * begins with a fresh, authoritative state read — so this bounds full
@@ -217,3 +221,122 @@ export async function unparkEpicTicketWithRetry(access, options) {
 export async function adoptCurrentHeadAndUnparkWithRetry(access, options) {
     return ticketRecoveryWithRetry(access, options, (a, args) => adoptCurrentHeadAndUnparkTicket(a, args));
 }
+/**
+ * Classify a thrown client error. A 4xx carrying a server `error_code` is a
+ * NAMED refusal and keeps that code; everything else (transport, timeout, 5xx
+ * without a code, an unparseable body) is `unavailable` with a bounded
+ * diagnostic. No raw body, URL, header, or credential ever reaches either shape.
+ */
+function classifyRepairError(err, fallback) {
+    if (err instanceof ConductorBridgeApiError && typeof err.status === "number" && err.errorCode) {
+        return {
+            ok: false,
+            kind: "refused",
+            code: err.errorCode,
+            status: err.status,
+            message: err.bodyPreview ?? err.errorCode,
+        };
+    }
+    return { ok: false, kind: "unavailable", message: safeDiagnosticMessage(err, fallback) };
+}
+/** Re-drive the run's own index scope. The server decides ownership. */
+export async function scopeReparseRepair(access, options, deps = {}) {
+    try {
+        const call = deps.scopeReparse ?? scopeReparse;
+        return { ok: true, result: await call(access, options) };
+    }
+    catch (err) {
+        return classifyRepairError(err, "scope-reparse request failed");
+    }
+}
+/**
+ * Dispatch a remediation job with driver context. `context` must already be
+ * validated against `DRIVER_CONTEXT_MAX_BYTES`; the server selects the job type.
+ */
+export async function dispatchRemediationRepair(access, options, deps = {}) {
+    try {
+        const call = deps.dispatchRemediation ?? dispatchRemediation;
+        return { ok: true, result: await call(access, options) };
+    }
+    catch (err) {
+        return classifyRepairError(err, "dispatch-remediation request failed");
+    }
+}
+/** A local failure reason is forwarded only when it is a bounded token. */
+const LOCAL_MERGE_REASON_RE = /^[a-z0-9_.:-]{1,200}$/;
+function boundedLocalMergeReason(reason) {
+    return typeof reason === "string" && LOCAL_MERGE_REASON_RE.test(reason)
+        ? reason
+        : "gh_merge_failed";
+}
+/**
+ * Merge the run's PR-bound child. The operator supplies only the PR number.
+ *
+ * When the server merges (repository `merge_execution = server`) its answer is
+ * final. When the repository merges locally — the default, and the only mode
+ * that works on an App without `contents: write` — the server returns an
+ * approval, this operation executes it with the operator's own `gh` through the
+ * SAME `runApprovedLocalMerge` the MCP merge tool uses (head-drift guard,
+ * `--match-head-commit`, and the ambiguity ladder included), and reports what
+ * `gh` did to the completion route, whose answer is the result. The approval's
+ * head SHA is consumed here and never returned or printed.
+ */
+export async function mergeChildRepair(access, options, deps = {}) {
+    let approval;
+    try {
+        approval = await (deps.mergeChild ?? mergeChild)(access, options);
+    }
+    catch (err) {
+        return classifyRepairError(err, "merge-child request failed");
+    }
+    const { local_execution: local, ...serverResult } = approval;
+    if (local === null) {
+        return { ok: true, result: serverResult };
+    }
+    const runLocal = deps.runLocalMerge ?? runApprovedLocalMerge;
+    let succeeded = false;
+    let alreadyMerged = false;
+    let failureReason = "gh_merge_failed";
+    try {
+        const localResult = await runLocal({
+            repo_name: access.repoName,
+            pr_number: options.prNumber,
+            expected_head_sha: local.expected_head_sha,
+            gate: { name: DEFAULT_GATE_NAME },
+            // A correlation label for the local executor's own in-memory evidence,
+            // which is discarded — never the server's action key, which the server
+            // recomposes itself at completion.
+            action_key: `merge-child:${options.epicRunId}:${options.prNumber}`,
+        }, { method: resolveLocalMergeMethod(local.merge_method) }, { env: deps.env ?? process.env });
+        succeeded = localResult.status === "succeeded";
+        alreadyMerged = succeeded && localResult.reason === "already_merged";
+        failureReason = boundedLocalMergeReason(localResult.reason);
+    }
+    catch {
+        succeeded = false;
+    }
+    try {
+        const completion = await (deps.completeMergeChild ?? completeMergeChild)(access, {
+            epicRunId: options.epicRunId,
+            prNumber: options.prNumber,
+            result: succeeded ? (alreadyMerged ? "already_merged" : "merged") : "failed",
+            ...(succeeded ? {} : { reason: failureReason }),
+        });
+        const { local_execution: _ignored, ...completed } = completion;
+        return { ok: true, result: completed };
+    }
+    catch (err) {
+        if (succeeded) {
+            // The merge is REAL whether or not the report landed. Reporting a failure
+            // here would invite a second merge attempt on a merged pull request.
+            return {
+                ok: false,
+                kind: "unavailable",
+                message: "the pull request was merged by your local gh, but the server could not record it " +
+                    `(${safeDiagnosticMessage(err, "completion request failed")}); re-run merge-child ` +
+                    "to record it — a merged pull request is answered as already_merged",
+            };
+        }
+        return classifyRepairError(err, "merge-child completion failed");
+    }
+}

package/build/conductor/repair-contract.js

@@ -0,0 +1,58 @@
+/**
+ * The shared contract for the run-addressed operator repair verbs (BAPI-1154):
+ * `scope-reparse`, `dispatch-remediation`, and `merge-child`.
+ *
+ * CLI-only, exactly like the BAPI-872 recovery verbs: none of these names is ever
+ * registered as an MCP tool (`index-static.test.ts` pins that). This module is the
+ * TypeScript mirror of `api/library/epic_conductor/operator_repair_contract.py` —
+ * the verb names, the CLOSED refusal-code table, the driver-context byte cap, and
+ * the bounded result shapes the Bridge client returns. A parity test keeps the two
+ * aligned; the CLI renders the server's code and never infers ownership or state
+ * from error prose.
+ *
+ * `release-job` is deliberately absent: its defect was already fixed by BAPI-1147
+ * and the executor's per-job timeout bounds any residual strand.
+ */
+export const VERB_SCOPE_REPARSE = "scope-reparse";
+export const VERB_DISPATCH_REMEDIATION = "dispatch-remediation";
+export const VERB_MERGE_CHILD = "merge-child";
+/** Every repair verb, in the order an operator meets them. */
+export const OPERATOR_REPAIR_VERBS = [
+    VERB_SCOPE_REPARSE,
+    VERB_DISPATCH_REMEDIATION,
+    VERB_MERGE_CHILD,
+];
+/**
+ * The ONE cap on driver context, in UTF-8 BYTES — the same number the server
+ * enforces (`DRIVER_CONTEXT_MAX_BYTES` in `prompt_specs.py`). Over-cap context is
+ * rejected before it is transmitted, never truncated: a code-changing worker must
+ * see the operator's complete instruction or none of it.
+ */
+export const DRIVER_CONTEXT_MAX_BYTES = 16384;
+/** The closed refusal-code vocabulary, mirroring the server table. */
+export const OPERATOR_REPAIR_REFUSAL_CODES = [
+    "TICKET_NOT_IN_RUN",
+    "DRIVER_CONTEXT_INVALID",
+    "RUN_NOT_DISPATCHABLE",
+    "TICKET_NOT_REMEDIABLE",
+    "MERGE_HELD_BEHIND_PEER",
+    "REMEDIATION_JOB_IN_FLIGHT",
+    "REMEDIATION_LANE_BUSY",
+    "REMEDIATION_BUDGET_EXHAUSTED",
+    "REMEDIATION_HELD",
+    "REMEDIATION_CONTRACT_ERROR",
+    "REMEDIATION_NO_PULL_REQUEST",
+    "ROW_VERSION_CONFLICT",
+    "DISPATCH_ENQUEUE_FAILED",
+    "SCOPE_REPARSE_REFUSED",
+    "SCOPE_LOOKUP_FAILED",
+    "MERGE_HEAD_UNBOUND",
+    "MERGE_GATE_UNRESOLVABLE",
+    "MERGE_NOT_COMPLETED",
+    "MERGE_COMPLETION_REFUSED",
+];
+/** True when `code` is one of the closed repair refusal codes. */
+export function isOperatorRepairRefusalCode(code) {
+    return (typeof code === "string" &&
+        OPERATOR_REPAIR_REFUSAL_CODES.includes(code));
+}

package/build/conductor/run-branch.js

@@ -0,0 +1,137 @@
+/**
+ * Canonical TypeScript run-branch DECLARATION resolution (BAPI-1127).
+ *
+ * The TypeScript counterpart of `api/models/run_branch.py`, and the only place
+ * in this package that answers "which base branch, if any, does this persisted
+ * run's `policy_json` DECLARE?" Before BAPI-1127 the question was answered in
+ * three places that disagreed — the defaulting resolver in `epic-runtime.ts`
+ * (a `??` scan that stopped on a present-but-blank `base_branch` and therefore
+ * never consulted the camelCase alias), `bridge-api-client.ts#readEpicRunCompletionState`
+ * (snake_case only, and it did not trim), and the Python resolver across the
+ * wire. The two runtimes feed the SAME epic run from opposite sides, so a
+ * disagreement means the server provisions one branch while the CLI cuts worker
+ * branches from another, silently.
+ *
+ * **Declaration only.** This module answers exactly one question and stops:
+ * what branch did the policy declare? It deliberately does NOT:
+ *
+ *   - apply the TypeScript-only `main` default. That is a DISPATCH-layer policy
+ *     owned by `epic-runtime.ts#resolveEffectiveRunBaseBranch`. A classification
+ *     or observation consumer that adopted it would report `main` for a run that
+ *     declared nothing, conflating "declared no branch" with "dispatches from
+ *     main" — the exact confusion that kept `featureBranch` honest before.
+ *   - apply branch-name validity rules. `validateBranchName` is an OPERATIONAL
+ *     judgment made by whichever caller is about to hand the value to git or a
+ *     provider, and it is applied there.
+ *
+ * **The frozen cross-runtime dispositions** (BAPI-1127, and the same two rules
+ * `api/models/run_branch.py` states):
+ *
+ *   - A NON-STRING candidate is ABSENT, not fatal. The ordered scan skips it and
+ *     continues to the next key, so the legacy row
+ *     `{"base_branch": 42, "baseBranch": "epic/X"}` resolves to `epic/X` rather
+ *     than failing closed on the unusable snake_case value. The strict server-side
+ *     `RunPolicy` boundary already rejects a non-string `base_branch` before it can
+ *     be stored, so this rule governs legacy and out-of-band rows only.
+ *   - A MALFORMED or over-length declaration is still a DECLARATION. It is
+ *     returned complete and trimmed, never truncated, rejected, or replaced with
+ *     a default; format and length are validated at the point of operational use.
+ *
+ * **Why a leaf.** `epic-runtime.ts` already imports from `bridge-api-client.ts`,
+ * so putting the shared resolver in either one and importing it from the other
+ * would close a cycle. This module imports NOTHING — not the API client, not a
+ * command runner, not `base-ref.js`'s validator — so every consumer can depend on
+ * it freely. That is the same reasoning `api/models/run_branch.py:13-24` gives for
+ * its own placement.
+ *
+ * The cross-language contract is frozen as data in
+ * `tests/pytest/fixtures/run_branch_vectors.json` and enforced from both sides by
+ * `mcp_server/src/conductor/run-branch.test.ts` and
+ * `tests/pytest/models/test_run_branch_vectors.py`.
+ */
+/**
+ * The policy keys consulted, IN ORDER. Both spellings are accepted because both
+ * have been written by real clients; `base_branch` is canonical and `baseBranch`
+ * is the legacy alias. Named once so the precedence is stated in exactly one
+ * place, mirroring `POLICY_BASE_BRANCH_KEYS` in `api/models/run_branch.py`.
+ */
+export const POLICY_BASE_BRANCH_KEYS = ["base_branch", "baseBranch"];
+/**
+ * Return the trimmed string, or `undefined` for anything that is not a usable
+ * one.
+ *
+ * A blank or whitespace-only value is NOT a branch: accepting it would let a run
+ * created with `base_branch: "   "` classify as a feature-branch run, which at
+ * the merge-admission boundary would hand it the ungated-auto-merge exception on
+ * the strength of whitespace. The Python twin is `run_branch._nonblank`.
+ *
+ * KNOWN GAP — the trim is proven equivalent only for ASCII whitespace
+ * (BAPI-1127 review). `String.prototype.trim()` and Python's `str.strip()` do
+ * not strip the same character class, so four inputs resolve differently and
+ * none is in the vector table:
+ *
+ * | declared value      | Python `_nonblank`   | this function        |
+ * |---------------------|----------------------|----------------------|
+ * | `"\u001cepic/X"`    | `"epic/X"`           | `"\u001cepic/X"`     |
+ * | `"\u0085"`          | absent (blank)       | `"\u0085"`           |
+ * | `"\u0085epic/X"`    | `"epic/X"`           | `"\u0085epic/X"`     |
+ * | `"\ufeffmain"`      | `"\ufeffmain"`       | `"main"`             |
+ *
+ * `str.strip()` also strips U+001C-U+001F and U+0085; `trim()` also strips
+ * U+FEFF. Note the second row is the sharp one: U+0085 is above 0x7F, so
+ * `validateBranchName`'s control-character rule does NOT reject it either.
+ *
+ * Left as FOLLOW-UP rather than fixed here, deliberately. Picking the canonical
+ * class is a contract decision of the same kind BAPI-1127 froze for the
+ * non-string and malformed-name rows — and it was frozen in the TICKET, not by
+ * the implementer. Normalizing Python's class would additionally change
+ * feature-branch classification for a policy the `RunPolicy` boundary accepts
+ * today (`{"base_branch": "\u0085"}` classifies as no-feature-branch now), which
+ * BAPI-1127's acceptance criteria forbid. `RunPolicy` accepts any strict string,
+ * so these values are storable, but they are vanishingly unlikely in practice.
+ * Recorded alongside the `git check-ref-format` follow-up in `base-ref.ts`.
+ */
+function nonblank(candidate) {
+    if (typeof candidate !== "string")
+        return undefined;
+    const trimmed = candidate.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Resolve the branch a persisted run's `policy_json` declares, if any.
+ *
+ * Returns the first non-blank string found across {@link POLICY_BASE_BRANCH_KEYS},
+ * in that order, trimmed; or `undefined` when the policy declares none.
+ *
+ * The scan is SEQUENTIAL, not nullish-coalescing: a candidate that is not a
+ * non-blank string is skipped and the scan CONTINUES to the next key. `??` falls
+ * through only for `null`/`undefined`, which is why the pre-BAPI-1127 expression
+ * stopped at a present-but-blank `base_branch` and reported the dispatch default
+ * for a policy that plainly declared `baseBranch: "epic/X"`.
+ *
+ * A non-mapping policy (`null`, `undefined`, a primitive, an array) declares
+ * nothing. Shape is the typed boundary's job, not this resolver's — the Python
+ * twin makes the same call for the same reason.
+ *
+ * The returned value is never truncated and carries no operational length or
+ * format bound. See the module docstring for both frozen dispositions.
+ */
+export function resolveDeclaredRunBaseBranch(policyJson) {
+    if (policyJson === null || typeof policyJson !== "object" || Array.isArray(policyJson)) {
+        return undefined;
+    }
+    const policy = policyJson;
+    for (const key of POLICY_BASE_BRANCH_KEYS) {
+        // OWN properties only. A Python dict has no prototype chain, so a plain
+        // `policy[key]` would not be the same read: it also sees `Object.prototype`,
+        // and a polluted prototype would make EVERY policy in the process appear to
+        // declare a branch. Real inputs come from `JSON.parse`, which never produces
+        // inherited keys, so this costs nothing and closes the gap.
+        if (!Object.prototype.hasOwnProperty.call(policy, key))
+            continue;
+        const resolved = nonblank(policy[key]);
+        if (resolved !== undefined)
+            return resolved;
+    }
+    return undefined;
+}

package/build/conductor/store.js

@@ -334,7 +334,7 @@ function buildAuxiliaryTablesSql() {
     );
 
     -- The supervisor projection is actively maintained by the conductor
-    -- supervisor runtime (BAPI-396, \`conductor supervise --run-id <id>\`): the
+    -- supervisor runtime (BAPI-396, \`epic-implementer supervise --run-id <id>\`): the
     -- foreground loop upserts a row after every deterministic iteration. It is
     -- the OPERATIONAL state mirror of the run; raw events remain the source of
     -- truth. The existing JSON columns are sufficient for resumable state, so the
@@ -822,7 +822,7 @@ export function rowToSupervisorProjection(row) {
  * Read the supervisor projection for `run_id` (read-only). Returns
  * `{ run_id, status: "unknown", projection: null }` when no projection exists.
  * The projection is maintained by the conductor supervisor runtime
- * (`conductor supervise`); this read never derives state from raw events.
+ * (`epic-implementer supervise`); this read never derives state from raw events.
  */
 export async function getSupervisorSnapshot(runId, config = resolveConductorStoreConfig()) {
     const db = await openReadonlyConductorDatabaseIfExists(config);

package/build/conductor/supervisor-runtime.js

@@ -1,7 +1,7 @@
 /**
  * Foreground supervisor runtime loop (BAPI-396, conductor C4).
  *
- * `conductor supervise --run-id <id>` runs this run-scoped, visible, ephemeral
+ * `epic-implementer supervise --run-id <id>` runs this run-scoped, visible, ephemeral
  * loop. It polls the conductor ledger, reduces raw events into deterministic
  * worker watchdog state, persists an operational projection, escalates stuck
  * workers (terminal output + idempotent ledger event), and terminates when all

package/build/conductor/test-run-branch-vectors.js

@@ -0,0 +1,165 @@
+/**
+ * BAPI-1127 — TypeScript-side loader for the SHARED cross-runtime vector table.
+ *
+ * `tests/pytest/fixtures/run_branch_vectors.json` lives at the repository root,
+ * outside this package, because it is not this package's fixture: it is the
+ * contract between this package and the Python server, and both sides read the
+ * same bytes. Python reaches it from `tests/pytest/models/`; this module is how
+ * the compiled `node:test` suites reach it.
+ *
+ * **Why `readFileSync` and not a JSON import.** Importing the JSON would require
+ * `resolveJsonModule` plus a widened `include` in `tsconfig.json`, which would
+ * inline a test fixture into the PUBLISHED bundle. `build/**\/*.test.js` is
+ * excluded from the package `files` list, so a compiled test reading a
+ * repository-root path ships nothing; a JSON module baked into the emitted
+ * source would.
+ *
+ * **Why the path is searched rather than computed.** The compiled test executes
+ * from `mcp_server/build/conductor/`, not `mcp_server/src/conductor/`, so a
+ * hard-coded `../../../` is correct for exactly one of the two and silently
+ * wrong for the other. Walking up until the fixture is found is correct from
+ * either, and from any CI checkout depth.
+ *
+ * Nothing here is reachable from the MCP server runtime — it is imported only by
+ * `*.test.ts` — so it adds no startup cost and touches no stdio.
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** Repository-root-relative location of the shared table. */
+const FIXTURE_RELATIVE_PATH = path.join("tests", "pytest", "fixtures", "run_branch_vectors.json");
+function repositoryRoot() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    // 8 levels is far more than the 3 either real layout needs; the loop exists to
+    // be layout-independent, not to search the whole filesystem.
+    for (let i = 0; i < 8; i++) {
+        try {
+            readFileSync(path.join(dir, FIXTURE_RELATIVE_PATH));
+            return dir;
+        }
+        catch {
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    throw new Error(`run_branch_vectors.json not found above ${fileURLToPath(import.meta.url)}. ` +
+        "The shared cross-runtime vector table is required; this suite must not " +
+        "pass without it.");
+}
+function readDocument() {
+    const fixturePath = path.join(repositoryRoot(), FIXTURE_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = readFileSync(fixturePath, "utf8");
+    }
+    catch (err) {
+        throw new Error(`shared vector fixture is unreadable at ${fixturePath}: ${String(err)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`shared vector fixture is not valid JSON (${fixturePath}): ${String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`shared vector fixture is not a JSON object (${fixturePath}).`);
+    }
+    return parsed;
+}
+/** JSON `null` means "no declaration"; TypeScript spells that `undefined`. */
+function nullToUndefined(value) {
+    return value === null ? undefined : value;
+}
+/**
+ * Load the shared resolution vectors, THROWING on every vacuous state.
+ *
+ * A missing, unreadable, malformed, or empty table is a failure and never a
+ * skip: a parity suite that quietly parametrizes zero cases reports green while
+ * proving nothing, which is the exact outcome these vectors exist to prevent.
+ */
+export function loadResolutionVectors() {
+    const raw = readDocument()["resolution_vectors"];
+    if (!Array.isArray(raw)) {
+        throw new Error("shared vector fixture has no 'resolution_vectors' array.");
+    }
+    if (raw.length === 0) {
+        throw new Error("shared vector fixture declares zero resolution vectors; every parity " +
+            "assertion below would be vacuous.");
+    }
+    return raw.map((entry, index) => {
+        if (!entry || typeof entry !== "object") {
+            throw new Error(`resolution vector #${index} is not an object.`);
+        }
+        const e = entry;
+        if (typeof e["id"] !== "string" || e["id"].length === 0) {
+            throw new Error(`resolution vector #${index} has no id.`);
+        }
+        if (typeof e["policy_present"] !== "boolean") {
+            throw new Error(`resolution vector ${e["id"]} has no boolean policy_present.`);
+        }
+        if (!("expected_declared_branch" in e)) {
+            throw new Error(`resolution vector ${e["id"]} has no expected_declared_branch.`);
+        }
+        return {
+            id: e["id"],
+            note: typeof e["note"] === "string" ? e["note"] : "",
+            policyPresent: e["policy_present"],
+            policyJson: e["policy_present"] ? e["policy_json"] : undefined,
+            expectedDeclaredBranch: nullToUndefined(e["expected_declared_branch"]),
+            typescriptEffectiveBase: nullToUndefined(e["typescript_effective_base"]),
+            typescriptEffectiveErrorType: nullToUndefined(e["typescript_effective_error_type"]),
+        };
+    });
+}
+/** Load the shared branch-name validity vectors, with the same loud failures. */
+export function loadBranchNameVectors() {
+    const raw = readDocument()["branch_name_validation"];
+    if (!Array.isArray(raw)) {
+        throw new Error("shared vector fixture has no 'branch_name_validation' array.");
+    }
+    if (raw.length === 0) {
+        throw new Error("shared vector fixture declares zero branch-name vectors; every validator " +
+            "assertion below would be vacuous.");
+    }
+    return raw.map((entry, index) => {
+        if (!entry || typeof entry !== "object") {
+            throw new Error(`branch-name vector #${index} is not an object.`);
+        }
+        const e = entry;
+        if (typeof e["id"] !== "string" || e["id"].length === 0) {
+            throw new Error(`branch-name vector #${index} has no id.`);
+        }
+        if (typeof e["input"] !== "string") {
+            throw new Error(`branch-name vector ${e["id"]} has a non-string input.`);
+        }
+        if (typeof e["valid"] !== "boolean") {
+            throw new Error(`branch-name vector ${e["id"]} has no boolean 'valid'.`);
+        }
+        return {
+            id: e["id"],
+            note: typeof e["note"] === "string" ? e["note"] : "",
+            input: e["input"],
+            valid: e["valid"],
+            errorType: nullToUndefined(e["error_type"]),
+        };
+    });
+}
+/**
+ * The substring each `error_type` must appear as in a validator diagnostic.
+ *
+ * The adapters assert the ACTUAL message, not merely that some error occurred,
+ * so a validator that started reporting the wrong rule would fail rather than
+ * pass on a coincidentally-truthy result. Kept here, beside the loader, because
+ * both the TypeScript validator suite and the effective-base suite need it.
+ */
+export const ERROR_TYPE_MESSAGE_FRAGMENTS = {
+    empty: "must not be empty",
+    too_long: "255 characters or fewer",
+    leading_hyphen: "must not start with '-'",
+    double_dot: "must not contain '..'",
+    lock_suffix: "must not end with '.lock'",
+    control_character: "must not contain control characters",
+};