@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/src/shared/git-failure.ts

@@ -0,0 +1,196 @@
+/**
+ * What went wrong between this deployment and its git host, in the terms an
+ * admin can act on.
+ *
+ * ONE classifier for every place that talks to the KB remote on the admin's
+ * behalf: the connection check (Test connection, and the save that proves the
+ * connection first) and the setup-time KB startup phase. Two tables of git
+ * wordings drift — a host that changes its phrasing gets learned in one and
+ * misread in the other — so there is exactly one, here.
+ *
+ * The raw text is an INPUT, never an output: a `cause` is a fixed sentence per
+ * kind (the one exception is a startup step's own name, which is code, not
+ * git output). What git actually said belongs in the server log.
+ */
+
+export type GitFailureKind =
+  | 'credentials-rejected'
+  | 'not-found'
+  | 'unreachable'
+  | 'write-refused'
+  | 'push-refused-by-policy'
+  | 'step-failed'
+  | 'unknown';
+
+export interface GitFailure {
+  kind: GitFailureKind;
+  /** One sentence: what to do about it. */
+  cause: string;
+}
+
+const CAUSES: Record<Exclude<GitFailureKind, 'step-failed'>, string> = {
+  'credentials-rejected':
+    'The host rejected the credentials — check the access token, and that the token username matches the host (GitHub x-access-token, GitLab oauth2, Bitbucket x-token-auth).',
+  'not-found':
+    'There is no repository at that address, or the token cannot see it — check the repository address and that the token has access to that repository.',
+  unreachable:
+    "This server could not reach the git host — check the repository address and this server's network access to that host, then retry.",
+  'write-refused':
+    'The token can read the repository but not write to it — grant it write (push) access to the repository, then retry.',
+  'push-refused-by-policy':
+    "A branch protection rule or hook on the repository refused the initialization push — allow the deployment's account to push to the protected branches, then retry.",
+  unknown:
+    'The knowledge base could not be initialized for a reason not listed here — the server log has the full error.',
+};
+
+function stepFailed(step: string): GitFailure {
+  return {
+    kind: 'step-failed',
+    cause: `The startup step "${step}" failed — the server log has its error; fix what it names, then retry.`,
+  };
+}
+
+/**
+ * How the startup runner prefixes a failure it attributes to a step
+ * (`kb-startup-runner.ts`): a throw, or a declared `stopBoot`.
+ */
+const STEP_PREFIX = /KB startup step "([^"]+)" (?:failed|stopped the boot): ([\s\S]*)/;
+
+/** How `kb-git.ts` prefixes a failed git invocation: `git <subcommand> failed: …`. */
+const GIT_PREFIX = /^git \S+ failed:/;
+
+/** What a failure's text is the answer to, when the caller knows. */
+export interface GitFailureContext {
+  /**
+   * `write`: the text answers a push. The startup phase's own pushes say so in
+   * their `git push failed:` prefix; the connection check's dry-run push says
+   * so here. Either way the repository was just READ with these credentials,
+   * so a bare 403 or 404, or a generic "denied" / "forbidden", is the host
+   * refusing the write — not a missing repository, not a bad login.
+   */
+  operation?: 'read' | 'write';
+}
+
+/**
+ * Classify a failure from its text. Raw text is safe here — none of it reaches
+ * the result — and is the better input where a caller holds it: a scrub
+ * replacing a token that happens to spell part of git's wording would change
+ * the reading.
+ *
+ * Order is load-bearing:
+ *  1. Refusals that NAME a policy, then a permission, come first — GitHub
+ *     answers a read-only token's push with a 403 that would otherwise read as
+ *     "bad credentials", and GitLab's protected-branch refusal also says "not
+ *     allowed to push".
+ *  2. Authentication failures come before the generic refusals of a write: a
+ *     public repository reads anonymously, so a push is where a made-up token
+ *     is first presented, and "the host rejected the token" is not "grant it a
+ *     permission". GitLab's auth failure says "Access denied", which a write's
+ *     generic "denied" would otherwise claim.
+ *  3. Then a write's generic refusals, a missing repository, and an
+ *     unreachable host — "unable to access" last, because a refusal arrives
+ *     wrapped in it.
+ */
+export function classifyGitFailure(text: string, context: GitFailureContext = {}): GitFailure {
+  let body = text;
+  const step = STEP_PREFIX.exec(text);
+  if (step) {
+    // A step that failed IN GIT is classified by what git said — that cause is
+    // the more actionable one. A step that failed on its own terms is named;
+    // its message is prose we cannot promise to read correctly.
+    if (!GIT_PREFIX.test(step[2]!.trimStart())) return stepFailed(step[1]!);
+    body = step[2]!;
+  }
+
+  // A status number proves nothing from inside a URL — `/acme/404-notes.git`
+  // or a port carries the digits with no refusal having happened, and a failed
+  // command's message quotes its whole argv — nor from curl's own
+  // `Failed to connect to <host> port 403`. Words still count wherever they
+  // appear; digits only outside URLs and port numbers.
+  const m = body.replace(/\bhttps?:\/\/\S+/gi, ' ').replace(/\bport \d+/gi, ' ');
+  const isWrite = context.operation === 'write' || /\bgit push failed\b/i.test(m);
+
+  if (
+    /pre-receive hook declined|hook declined|protected branch|GH006|GH013|\[remote rejected\]/i.test(m)
+  ) {
+    return known('push-refused-by-policy');
+  }
+  // Each host's own words for "this token may not push": GitHub classic and
+  // fine-grained, GitLab, Bitbucket, Azure DevOps.
+  if (
+    /Permission to \S+ denied|write access to repository not granted|not allowed to push|push access denied|lack one or more required privilege scopes|GenericContribute/i.test(
+      m,
+    )
+  ) {
+    return known('write-refused');
+  }
+  if (
+    /Authentication failed|could not read Username|could not read Password|Invalid username or (?:token|password)|invalid credentials|HTTP Basic: Access denied|\b401\b/i.test(
+      m,
+    ) ||
+    // On a read a 403 is the login refused; on a write the host already knows
+    // who this is (see below).
+    (!isWrite && /\b403\b/.test(m))
+  ) {
+    return known('credentials-rejected');
+  }
+  // A write refused in no host's particular words: these credentials just
+  // read the repository, so it exists and the login worked.
+  if (isWrite && /\b40[34]\b|\bdenied\b|forbidden|not found/i.test(m)) {
+    return known('write-refused');
+  }
+  if (/not found|repository .* does not exist|\b404\b/i.test(m)) {
+    return known('not-found');
+  }
+  if (
+    /timed out|ETIMEDOUT|could not resolve host|Failed to connect|Connection refused|ECONNREFUSED|Network is unreachable|SSL|\bTLS\b|certificate|unable to access/i.test(
+      m,
+    )
+  ) {
+    return known('unreachable');
+  }
+  return known('unknown');
+}
+
+function known(kind: Exclude<GitFailureKind, 'step-failed'>): GitFailure {
+  return { kind, cause: CAUSES[kind] };
+}
+
+/**
+ * A failure whose message is already scrubbed for the log, carrying the
+ * classification read from the text BEFORE the scrub.
+ *
+ * Scrubbing and classifying both want the raw text, and they cannot share it
+ * in order: a scrub is free to rewrite the very words the classifier reads (a
+ * token that spells `connect` turns "Failed to connect" into something else),
+ * while carrying the raw text on to wherever classification happens would put
+ * the secret into every error that travels. So the place that holds the raw
+ * text does both, once, and only the scrubbed message and the fixed-sentence
+ * classification leave it.
+ */
+export class ClassifiedFailure extends Error {
+  /**
+   * `cause` carries the failure this one classifies when a caller still needs
+   * its shape — a `GitRunError` whose fields say whether git ran at all. It is
+   * a redacted error by then, never the raw text.
+   */
+  constructor(
+    message: string,
+    readonly failure: GitFailure,
+    opts?: { cause?: unknown },
+  ) {
+    super(message, opts);
+    this.name = 'ClassifiedFailure';
+  }
+}
+
+/** A failure of a known kind, with its fixed sentence — for a caller that knows the kind without reading text. */
+export function gitFailure(kind: Exclude<GitFailureKind, 'step-failed'>): GitFailure {
+  return known(kind);
+}
+
+/** The classification a failure carries, else one read from its message. */
+export function failureOf(err: unknown): GitFailure {
+  if (err instanceof ClassifiedFailure) return err.failure;
+  return classifyGitFailure(err instanceof Error ? err.message : String(err));
+}

package/src/shared/git-internals.ts

@@ -0,0 +1,179 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { GitInternalsError } from './domain-errors.js';
+import { isAbsence } from './fs.contract.js';
+
+/**
+ * The repository's internal git folder is never a workspace path.
+ *
+ * `.git/` holds the object database, the refs and the clone's config — the
+ * credential helper among it. No file tool and no workspace route reads,
+ * lists, writes or moves anything there; git itself is the only writer. The
+ * rule is judged on segments, never on a prefix, so `.github/` and
+ * `.gitkeep` stay ordinary paths.
+ *
+ * Two checks, both needed:
+ *   - {@link hasGitInternalsSegment} is LEXICAL: any spelling that names the
+ *     folder — `.GIT`, `%2egit`, `a/../.git`, `a\.git` — is refused before
+ *     anything touches the disk, so a refusal takes no lock and records no
+ *     read.
+ *   - {@link assertNotGitInternals} adds the RESOLVED form: the deepest part
+ *     of the path that exists is run through `realpath`, so a symbolic link
+ *     in the repository that points into the folder is refused the same way.
+ */
+
+/**
+ * Percent-decode until the spelling stops changing (`%252e` is `.` twice
+ * removed), however many layers deep. No pass limit is needed: a pass that
+ * changes anything makes the string shorter, so the loop always ends.
+ */
+function percentDecoded(value: string): string {
+  let current = value;
+  for (;;) {
+    const next = current.replace(/%([0-9a-f]{2})/gi, (_m, hex: string) => String.fromCharCode(parseInt(hex, 16)));
+    if (next === current) return current;
+    current = next;
+  }
+}
+
+/**
+ * Whether one path segment names the git folder. Case-folded, because a
+ * case-insensitive volume opens `.GIT` as `.git`; trailing dots and spaces
+ * dropped, because Windows does the same to `.git.` and `.git `.
+ */
+function isGitSegment(segment: string): boolean {
+  return segment.replace(/[. ]+$/, '').toLowerCase() === '.git';
+}
+
+/** True when any segment of `inputPath`, in any spelling, is the git folder. */
+export function hasGitInternalsSegment(inputPath: unknown): boolean {
+  if (typeof inputPath !== 'string') return false;
+  return percentDecoded(inputPath)
+    .split(/[\\/]+/)
+    .some(isGitSegment);
+}
+
+/** Refuse `inputPath` lexically. See {@link hasGitInternalsSegment}. */
+export function assertNoGitInternalsSegment(inputPath: unknown): void {
+  if (hasGitInternalsSegment(inputPath)) throw new GitInternalsError();
+}
+
+const errCode = (err: unknown): unknown => (err as { code?: unknown })?.code;
+
+/** `null` for "nothing resolvable here" (absent, or a link loop); every other filesystem error is rethrown. */
+function nullWhenUnresolvable(err: unknown): null {
+  if (isAbsence(err) || errCode(err) === 'ELOOP') return null;
+  throw err;
+}
+
+/** Dangling links followed by hand before the chain counts as a loop (Linux's own limit). */
+const MAX_LINK_HOPS = 40;
+
+/**
+ * `realpath` of the deepest existing ancestor of `absolutePath`, with the
+ * missing rest joined back on. A DANGLING link on the way is followed by hand:
+ * `realpath` refuses it, but a write through it lands at its target, so the
+ * target is what gets judged (`notes.md -> .git/hooks/post-checkout`).
+ */
+async function resolvedRealPath(absolutePath: string): Promise<string | null> {
+  let existing = absolutePath;
+  const rest: string[] = [];
+  let hops = 0;
+  for (;;) {
+    const real = await fs.realpath(existing).catch(nullWhenUnresolvable);
+    if (real !== null) return path.join(real, ...rest);
+    // EINVAL is "not a link": nothing to follow. Any other failure — a
+    // permission error, say — is thrown, never guessed past lexically.
+    const target =
+      hops < MAX_LINK_HOPS
+        ? await fs.readlink(existing).catch((err: unknown) => (errCode(err) === 'EINVAL' ? null : nullWhenUnresolvable(err)))
+        : null;
+    if (target !== null) {
+      const parent = await fs.realpath(path.dirname(existing)).catch(nullWhenUnresolvable);
+      if (parent !== null) {
+        hops++;
+        existing = path.resolve(parent, target);
+        continue;
+      }
+    }
+    const up = path.dirname(existing);
+    if (up === existing) return null;
+    rest.unshift(path.basename(existing));
+    existing = up;
+  }
+}
+
+/**
+ * Refuse a path under `rootDir` that names the git folder or resolves into it.
+ *
+ * `inputPath` is the caller's own spelling (checked lexically, encoded forms
+ * included, and probed on disk every way it could land — see
+ * {@link candidateTargets}); `absolutePath`, when a layer has already
+ * decided where the path goes, is that place, judged AS WELL. Both in one
+ * call, because the two answer different questions — a link reached by a
+ * reading this layer does not use is caught only by the spelling, a link the
+ * layer's own resolution follows only by the place — and one call walks the
+ * root once and probes a place that both name once. Only the part below
+ * `rootDir` is judged, so a workspaces root that itself sits under some
+ * `.git` directory does not refuse everything. A link that leaves the root
+ * is judged on its target's path relative to the root, so a link into
+ * another checkout's `.git` is refused too; whether such a link may be
+ * followed at all is the containment checks' business.
+ */
+export async function assertNotGitInternals(rootDir: string, inputPath: string, absolutePath?: string): Promise<void> {
+  assertNoGitInternalsSegment(inputPath);
+  const root = path.resolve(rootDir);
+  const realRoot = await resolvedRealPath(root);
+  // Each place once, remembering whether a layer resolved it (probed as
+  // given) or only a spelling named it (probed only inside the root).
+  const targets = new Map<string, boolean>();
+  for (const target of candidateTargets(root, inputPath)) targets.set(target, false);
+  if (absolutePath !== undefined) targets.set(absolutePath, true);
+  for (const [target, resolved] of targets) {
+    const relative = path.relative(root, target);
+    if (hasGitInternalsSegment(relative)) throw new GitInternalsError();
+    if (realRoot === null) continue;
+    // A raw spelling fans out into candidates, and one of them can name a
+    // place outside the workspace entirely — `/etc/…`, a deep climb. Such a
+    // candidate is judged by the lexical reading above (a link into another
+    // checkout's `.git` is named there) but NOT probed on disk: probing it
+    // would let an unreadable external directory answer with its own
+    // `EACCES` instead of the path rule's typed refusal for a spelling that
+    // was never a workspace path. A path a layer already resolved is the one
+    // place it is, so it is probed as given.
+    // `..` and `../…` are the climbs; `..link` is an ordinary name that merely
+    // starts with those characters, and a link by that name can point into the
+    // folder — so it is probed like any other entry under the root.
+    const climbsOut = relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+    if (!resolved && (relative === '' || climbsOut)) continue;
+    const realTarget = await resolvedRealPath(target);
+    if (realTarget !== null && hasGitInternalsSegment(path.relative(realRoot, realTarget))) throw new GitInternalsError();
+  }
+}
+
+/**
+ * Every place one raw spelling could LAND, because a spelling is not yet a
+ * path until something decides how to read it.
+ *
+ * A backslash separates segments on Windows and is an ordinary character in a
+ * filename here, so `kb\\Notes\\..\\link` is read BOTH ways; an absolute path
+ * is both the path it names and — as every workspace caller reads it — that
+ * path with its leading slashes dropped, under the workspace; and a leading
+ * climb (`../kb/link`) is both the climb it spells and the path left when the
+ * climb is dropped, which is how a lenient reader takes it. The spelling is
+ * refused when ANY reading lands in the git folder: which reading a later
+ * layer picks is not something this rule should have to predict.
+ *
+ * This is what a CALLER's own spelling needs. A path some layer has already
+ * resolved arrives as `absolutePath` and is judged as the one place it is.
+ */
+function candidateTargets(root: string, inputPath: string): string[] {
+  const targets = new Set<string>();
+  for (const spelling of new Set([inputPath, inputPath.replace(/\\/g, '/')])) {
+    const anchored = spelling.replace(/^[\\/]+/, '');
+    targets.add(path.resolve(root, anchored));
+    targets.add(path.resolve(root, anchored.replace(/^(\.\.?[\\/])+/, '')));
+    if (/^[\\/]/.test(spelling)) targets.add(path.resolve(spelling));
+  }
+  return [...targets];
+}

package/src/shared/git.contract.ts

@@ -0,0 +1,170 @@
+/**
+ * The contract for RUNNING git. Nothing here spawns anything — the one
+ * implementation is `NodeGitRunner` in `modules/workflow/git`, wired once by
+ * the composition root and injected into every module that shells out to git,
+ * so no module carries an `execFile('git', …)` of its own.
+ *
+ * WHY THERE IS A PORT AT ALL. Git was spawned from six places, each with its
+ * own environment, its own buffer ceiling and its own error shape. Four of the
+ * six had no deadline at all, and the two that did (the KB startup runner, the
+ * setup screen's `ls-remote`) set `execFile`'s own `timeout`, which signals git
+ * and then goes on waiting for output pipes a surviving transport helper still
+ * holds — see `killTree` in the implementation for what that measured out at.
+ * A git process that never returns is not
+ * a hypothetical: an unreachable host, a hung credential helper, or a remote
+ * that accepts the connection and then stops talking all produce one. And a
+ * hung git is not one stalled request. It holds the workspace mutex, which is
+ * what serializes every other operation on that clone, so one dead remote takes
+ * the workspace with it — and, while the commit worker is single-flight, every
+ * other workspace too. The file is on disk and shows as saved; git history
+ * silently stops moving.
+ *
+ * So the point of this contract is the DEADLINE, and the deadline is not
+ * optional: {@link https://github.com/Bevel-Software/Hexis Hexis}'s
+ * "Opened Connections Have a Closing Owner" invariant requires that a spawned
+ * child be closed on every path including timeout and abandonment, and a wait
+ * that can never be abandoned cannot satisfy it. Every call made through this
+ * port carries one, and the implementation kills the child when it expires.
+ *
+ * WHAT THIS PORT DOES NOT DO. It does not lock. Serializing git against a
+ * clone is the `WorkspaceMutex`'s job, under the canonical workspace id, and
+ * moving that responsibility here would give the codebase two answers to
+ * "which operations exclude each other". A runner is told what to run and
+ * where; whether it was safe to run it there was decided before the call.
+ *
+ * It also does not stream. A long-lived child whose output is piped somewhere
+ * as it arrives — `git http-backend` serving a clone, `git archive` piped into
+ * a download — is a different lifetime with a different owner, and stays with
+ * the code that owns it.
+ */
+
+/**
+ * Strip the configured git token out of text on its way into an error, a log
+ * line or a response.
+ *
+ * git puts the remote URL into a great many of its messages, and on a
+ * token-authenticated remote that URL carries the credential. Without this, a
+ * push failure writes the deployment's token into the container log, the API
+ * response, and any change request the recovery agent opens about it.
+ *
+ * Read from the environment at call time rather than captured: the setup screen
+ * can supply a token after boot, and `DeploymentSettingsService.syncGitTokenEnv`
+ * puts it here — a value captured at module load would be the empty string for
+ * exactly the deployments that configure their token that way.
+ */
+export function redactGitToken(text: string): string {
+  const token = process.env.GITHUB_TOKEN;
+  const scrubbed = token ? text.replaceAll(token, '***') : text;
+  // URL userinfo as well: a remote spelled `https://user:pass@host` would
+  // otherwise leak `pass` verbatim through every git failure that quotes the
+  // URL back, whatever the token setting.
+  return scrubbed.replace(/:\/\/[^/@\s]+@/g, '://***@');
+}
+
+/**
+ * What a completed git invocation produced. `stdout` is decoded text unless
+ * the call asked for bytes (see {@link GitRunOptions.encoding}); `stderr` is
+ * always text, since its only use is a message.
+ */
+export interface GitRunResult<TOut = string> {
+  stdout: TOut;
+  stderr: string;
+}
+
+export interface GitRunOptions {
+  /**
+   * Bytes to feed the subprocess on stdin — used by the
+   * `--pathspec-from-file=-` commit/add paths so that a several-hundred-file
+   * batch never has to ride the argv (Windows caps a command line at ~32K
+   * characters), and by `cat-file --batch` to name the objects it wants.
+   */
+  input?: string;
+  /**
+   * Override the runner's default deadline for this one call. For an operation
+   * whose legitimate duration is unlike the rest — a first clone of a large
+   * repository, say — rather than raising the deployment-wide default to
+   * accommodate it.
+   */
+  timeoutMs?: number;
+  /**
+   * Environment entries laid over the runner's own for this one call. For the
+   * variables git reads as INPUT to a specific command — `GIT_DIR`,
+   * `GIT_INDEX_FILE` and `GIT_WORK_TREE` pointing a plumbing command at a
+   * scratch index, `GIT_AUTHOR_*` naming a committer, a helper-read credential
+   * — never for the settings that make every invocation safe, which the
+   * runner sets and a caller cannot unset.
+   */
+  env?: NodeJS.ProcessEnv;
+  /**
+   * `'buffer'` returns stdout as raw bytes. For output whose framing is in
+   * BYTES rather than characters: `cat-file --batch` announces each object as
+   * `<oid> <type> <size>` and follows it with exactly `size` bytes, and a
+   * decoded string cannot be walked by that count once the content is not
+   * ASCII. Default `'utf8'`.
+   */
+  encoding?: 'utf8' | 'buffer';
+}
+
+/**
+ * A git invocation that did not succeed: a non-zero exit, a failure to spawn,
+ * or a deadline that expired.
+ *
+ * `exitCode` and `stderr` are carried so that callers can tell an EXPECTED
+ * non-zero exit (`merge-base` exiting 1 for "no common ancestor", `diff
+ * --quiet` exiting 1 for "there are differences") from an infrastructure
+ * failure, without parsing message text. Several callers already read
+ * `exitCode` this way.
+ *
+ * `timedOut` is the distinction the deadline adds, and it matters: a timeout is
+ * a statement about the host or the network, never about the repository. Code
+ * that treats a non-zero exit as a permanent answer — "there is no such ref",
+ * "there is nothing to commit" — would draw exactly the wrong conclusion from
+ * one, so a caller that interprets exit codes must exclude it first.
+ */
+export class GitRunError extends Error {
+  /** Process exit code, when the process ran and exited. */
+  readonly exitCode?: number;
+  /** Captured stderr, with any configured git token redacted. */
+  readonly stderr?: string;
+  /** True when the deadline expired and the child was killed. */
+  readonly timedOut: boolean;
+
+  /**
+   * No `cause`, on purpose: the child-process error it would carry holds the
+   * unredacted command line and stderr, and a logger that serializes errors
+   * walks the cause chain. Everything a caller can act on is on the fields
+   * above, redacted.
+   */
+  constructor(message: string, opts: { exitCode?: number; stderr?: string; timedOut?: boolean } = {}) {
+    super(message);
+    this.name = 'GitRunError';
+    this.exitCode = opts.exitCode;
+    this.stderr = opts.stderr;
+    this.timedOut = opts.timedOut ?? false;
+  }
+}
+
+/** Whether a failure came from the deadline rather than from git's own answer. */
+export function isGitTimeout(err: unknown): boolean {
+  return err instanceof GitRunError && err.timedOut;
+}
+
+/**
+ * Runs one git command to completion and returns what it wrote.
+ *
+ * `cwd` is the directory git runs in; `args` are passed to the executable
+ * verbatim, never through a shell. Throws {@link GitRunError} for every
+ * failure, the deadline included.
+ */
+export interface IGitRunner {
+  /**
+   * The deadline a call gets when it names none — the deployment's configured
+   * ceiling. A caller whose command is legitimately long (a first clone) asks
+   * for `Math.max(defaultTimeoutMs, itsOwnFloor)`, so an operator who raised
+   * the ceiling raises it there too rather than being overridden by a
+   * constant.
+   */
+  readonly defaultTimeoutMs: number;
+  run(cwd: string, args: string[], opts: GitRunOptions & { encoding: 'buffer' }): Promise<GitRunResult<Buffer>>;
+  run(cwd: string, args: string[], opts?: GitRunOptions & { encoding?: 'utf8' }): Promise<GitRunResult>;
+}

package/src/shared/http-errors.ts

@@ -0,0 +1,36 @@
+import type { WorkflowDomainError } from './domain-errors.js';
+
+/**
+ * THE response body for a domain refusal: the error's own message, plus
+ * whatever its payload carries, for a client that switches on the shape
+ * rather than on the prose.
+ *
+ * The payload is an open `Record<string, unknown>` and deliberately stays
+ * that way — `WorkflowValidationError` takes one from its caller — so this
+ * lists no closed set. The discriminator to reach for is `kind`
+ * (`path-traversal`, `unreadable-archive`, `no-shared-history`, …), which
+ * most refusals carry; beside it they add whatever context that kind needs
+ * (`branchName`, `head`/`base`, `conflictedPaths`, `feature`), and
+ * `AccessConfigError` carries `accessConfigErrors` instead. Read the
+ * subclass to know what its own refusal brings.
+ *
+ * Eight route surfaces built this object by hand, and seven of them spread
+ * the payload AFTER the message:
+ *
+ *   { error: err.message, ...err.payload }   // payload wins
+ *
+ * A payload is a `Record<string, unknown>`, so a key named `error` is
+ * expressible — and in that shape it silently replaces the one line the
+ * client renders, leaving a refusal that says something else entirely. The
+ * eighth site had it right and said so in a comment; this is that comment
+ * made into the only way to build the body.
+ *
+ * The STATUS is deliberately not decided here. Each surface keeps its own
+ * 5xx policy — the admin roster routes never leak a 5xx detail, while the
+ * workspace routes surface `AccessConfigError`'s message because an admin
+ * has to read it — and those differ on purpose, not by drift.
+ */
+export function domainErrorBody(err: WorkflowDomainError): Record<string, unknown> {
+  // Payload FIRST, `error` LAST: the message always wins.
+  return { ...(err.payload ?? {}), error: err.message };
+}