crewhaus 0.1.8 → 0.2.0

package/dist/alert-sink.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Item 31 — construct the `AlertSink` the alert watchdog uses for durable +
+ * off-box delivery of a threshold breach. Two channels, both best-effort:
+ *   - `appendAudit`   → a tamper-evident `alert_raised` record on the
+ *                       hash-chained audit log (so the alert history itself is
+ *                       auditable);
+ *   - `fireAlertHook` → the settings.json `alert` hook (HOOK_EVENTS gained
+ *                       `"alert"` additively) AND/OR an `alerts.webhook` POST.
+ *
+ * Side-effect-free + injected (audit log, hook runner, hook list, fetch) so
+ * this entry file (which runs an argv switch on import) stays testable and no
+ * network/audit I/O happens at import time. `crewhaus run` wires the real
+ * `openAuditLog`, `loadHooks`+`runHooks`, and `globalThis.fetch`.
+ */
+import type { AlertSink } from "@crewhaus/runtime-core";
+/** Minimal audit seam — structurally satisfied by `@crewhaus/audit-log`. */
+export type AlertAuditSink = {
+    append(input: {
+        readonly kind: "alert_raised";
+        readonly payload: unknown;
+    }): Promise<unknown>;
+};
+/** Minimal hook seam — structurally satisfied by `hooks-engine`'s `runHooks`. */
+export type AlertHookRunner = (event: "alert", payload: unknown, matcherKey: string) => Promise<void>;
+export type BuildAlertSinkOptions = {
+    /** Durable audit log (undefined ⇒ no audit channel). */
+    readonly audit?: AlertAuditSink;
+    /** Runs settings.json `alert` hooks (undefined ⇒ no hook channel). */
+    readonly runAlertHooks?: AlertHookRunner;
+    /** Webhook URL to POST the breach JSON to (undefined ⇒ no webhook channel). */
+    readonly webhookUrl?: string;
+    /** Injected fetch (defaults to global fetch) for the webhook POST. */
+    readonly fetchImpl?: typeof fetch;
+    /** Warn sink for best-effort delivery failures (defaults to stderr). */
+    readonly warn?: (line: string) => void;
+};
+/**
+ * Build the `AlertSink`, or `undefined` when NO channel is configured (so the
+ * caller spreads nothing into `runChatLoop` and the watchdog keeps only its
+ * trace-event + snapshot behaviour). Every channel is best-effort: a failure
+ * is warned, never thrown — an alert-delivery hiccup must not fail a run.
+ */
+export declare function buildAlertSink(opts: BuildAlertSinkOptions): AlertSink | undefined;
+/**
+ * Read the optional `alerts` block from a parsed settings.json root. Only the
+ * `webhook` string is consumed today; unknown keys are ignored (additive).
+ */
+export declare function alertWebhookFromSettings(settingsRoot: unknown): string | undefined;

package/dist/alert-sink.js

@@ -0,0 +1,86 @@
+/**
+ * Build the `AlertSink`, or `undefined` when NO channel is configured (so the
+ * caller spreads nothing into `runChatLoop` and the watchdog keeps only its
+ * trace-event + snapshot behaviour). Every channel is best-effort: a failure
+ * is warned, never thrown — an alert-delivery hiccup must not fail a run.
+ */
+export function buildAlertSink(opts) {
+    const hasAudit = opts.audit !== undefined;
+    const hasHooks = opts.runAlertHooks !== undefined;
+    const hasWebhook = typeof opts.webhookUrl === "string" && opts.webhookUrl !== "";
+    if (!hasAudit && !hasHooks && !hasWebhook)
+        return undefined;
+    const warn = opts.warn ?? ((line) => process.stderr.write(`${line}\n`));
+    const sink = {};
+    if (hasAudit) {
+        sink.appendAudit = async (breach) => {
+            await opts.audit?.append({ kind: "alert_raised", payload: breach });
+        };
+    }
+    if (hasHooks || hasWebhook) {
+        sink.fireAlertHook = async (breach) => {
+            // Match the hook by the breached metric name so a settings.json hook can
+            // target `matcher: "cost_burn_usd_per_min"`, etc.
+            if (hasHooks) {
+                try {
+                    await opts.runAlertHooks?.("alert", breach, "metric");
+                }
+                catch (err) {
+                    warn(`[alert] hook failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            if (hasWebhook && opts.webhookUrl !== undefined) {
+                // F5 — warn (never block) on a non-https scheme, mirroring
+                // security-digest.ts's notifySecurityDigest: an alert breach payload
+                // carries session/metric/threshold detail, and posting it cleartext
+                // leaks it to every on-path observer. Advisory only — the webhook
+                // still POSTs; a local tunnel/dev receiver is a legitimate use case.
+                if (isNonHttpsUrl(opts.webhookUrl)) {
+                    warn(`[alert] webhook ${opts.webhookUrl} uses plain http — the breach payload will transit unencrypted; prefer an https webhook`);
+                }
+                const doFetch = opts.fetchImpl ?? fetch;
+                try {
+                    const res = await doFetch(opts.webhookUrl, {
+                        method: "POST",
+                        headers: { "content-type": "application/json" },
+                        body: JSON.stringify(breach),
+                    });
+                    if (!res.ok)
+                        warn(`[alert] webhook POST returned ${res.status}`);
+                }
+                catch (err) {
+                    warn(`[alert] webhook POST failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        };
+    }
+    return sink;
+}
+/**
+ * F5 — true when `url` parses and its scheme is anything other than
+ * `https:` (notably plain `http:`). An unparseable URL returns `false` here
+ * — the webhook POST itself will surface that failure via its own
+ * try/catch, so this check only ever adds the scheme warning, never a new
+ * failure mode.
+ */
+function isNonHttpsUrl(url) {
+    try {
+        return new URL(url).protocol !== "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the optional `alerts` block from a parsed settings.json root. Only the
+ * `webhook` string is consumed today; unknown keys are ignored (additive).
+ */
+export function alertWebhookFromSettings(settingsRoot) {
+    if (typeof settingsRoot !== "object" || settingsRoot === null)
+        return undefined;
+    const alerts = settingsRoot.alerts;
+    if (typeof alerts !== "object" || alerts === null)
+        return undefined;
+    const webhook = alerts.webhook;
+    return typeof webhook === "string" && webhook !== "" ? webhook : undefined;
+}

package/dist/approval-gate.d.ts

@@ -0,0 +1,127 @@
+/** Thrown for malformed config / approvals files. The CLI routes the message
+ *  through `die()`; tests assert on `.message`. */
+export declare class ApprovalGateError extends Error {
+    readonly name = "ApprovalGateError";
+}
+export declare const ENVIRONMENTS_CONFIG_RELPATH = ".crewhaus/environments.json";
+export declare const APPROVALS_RELDIR = ".crewhaus/approvals";
+export type EnvironmentPolicy = {
+    readonly requireApproval: boolean;
+    /** Distinct approvals required to flip this env. Defaults to 1 when
+     *  requireApproval is true and unset. */
+    readonly minApprovals: number;
+};
+export type EnvironmentsConfig = {
+    readonly environments: Readonly<Record<string, EnvironmentPolicy>>;
+    /** true when a real config file was found (vs the all-unprotected default). */
+    readonly fromFile: boolean;
+};
+/**
+ * Load `.crewhaus/environments.json` from a harness root. A missing file
+ * yields the all-unprotected default (`fromFile: false`). A present-but-
+ * malformed file throws — a protected-env policy that silently degraded to
+ * "unprotected" would be the worst possible failure mode.
+ */
+export declare function loadEnvironmentsConfig(rootDir: string): EnvironmentsConfig;
+/** The policy for `env`, or an unprotected default. */
+export declare function policyForEnv(config: EnvironmentsConfig, env: string): EnvironmentPolicy;
+export type ApprovalRecord = {
+    readonly approver: string;
+    readonly ts: string;
+    /** Candidate version this approval is FOR; when set it must match the
+     *  version being promoted to count. */
+    readonly version?: string;
+    readonly comment?: string;
+};
+/** Approvals file name for a (spec, env) pair. `/` is not possible in a spec
+ *  registry name, so `__` is a safe joiner. */
+export declare function approvalsFileName(specName: string, env: string): string;
+/**
+ * Read recorded approvals for a (spec, env) from
+ * `.crewhaus/approvals/<spec>__<env>.json`. Missing file → []. A malformed
+ * file throws (a dropped approval could silently under-count the quorum).
+ */
+export declare function readApprovals(rootDir: string, specName: string, env: string): ApprovalRecord[];
+export type PrCheckState = {
+    /** "success" | "pending" | "failure" | "none" (no PR found for the change). */
+    readonly conclusion: "success" | "pending" | "failure" | "none";
+    readonly prNumber?: number;
+    readonly url?: string;
+};
+/** Reader seam: resolve the PR-check state for a (spec, env, version) change.
+ *  Production drives `gh`; tests inject a fixed state. */
+export type PrCheckReader = (args: {
+    readonly specName: string;
+    readonly env: string;
+    readonly version: string;
+}) => Promise<PrCheckState>;
+/** One entry in a GitHub PR's `statusCheckRollup` — a StatusContext carries a
+ *  `state`, a CheckRun carries a `conclusion`; either (or neither) may be set. */
+export type RollupCheck = {
+    readonly conclusion?: string;
+    readonly state?: string;
+};
+/**
+ * F3(a) — FAIL-CLOSED rollup verdict. A PR is a `success` witness ONLY when it
+ * has at least one check AND every check terminated in an explicit SUCCESS.
+ * Any failure/cancel/timeout, any still-running check, and any
+ * SKIPPED/NEUTRAL/unknown conclusion yields NOT a witness — an ambiguous or
+ * non-passing state must never sign off a protected promotion.
+ */
+export declare function rollupConclusion(rollup: ReadonlyArray<RollupCheck>): "success" | "pending" | "failure" | "none";
+/**
+ * F3(b) — does this PR reference `version` as a bounded token in its head ref,
+ * title, or body? `propose` names the branch `propose/<slug>-<version>-<hash>-
+ * <stamp>`, so the version is a bounded segment of the head ref; a bare
+ * substring match would let `v1` witness `v10`, so require non-alphanumeric
+ * (or string-edge) bounds. Binds the PR witness to the EXACT promoted version.
+ */
+export declare function prReferencesVersion(pr: {
+    readonly headRefName?: string;
+    readonly title?: string;
+    readonly body?: string;
+}, version: string): boolean;
+export type ApprovalDecisionInput = {
+    readonly specName: string;
+    readonly toEnv: string;
+    /** The candidate version the promotion would pin to. */
+    readonly toVersion: string;
+    readonly policy: EnvironmentPolicy;
+    readonly approvals: ReadonlyArray<ApprovalRecord>;
+    /** Present only when a PR-check witness was consulted. */
+    readonly prCheck?: PrCheckState;
+};
+export type ApprovalDecision = {
+    readonly satisfied: boolean;
+    /** Distinct approvers whose approval is valid for this candidate version. */
+    readonly countedApprovers: ReadonlyArray<string>;
+    /** True when a green PR check contributed a witness. */
+    readonly prWitness: boolean;
+    readonly required: number;
+    readonly reason: string;
+};
+/**
+ * Decide whether the gate is satisfied. Counts DISTINCT approvers whose
+ * approval either carries no version pin or matches `toVersion`, plus one
+ * collective witness for a green PR check. Satisfied when
+ * `witnesses >= required`.
+ */
+export declare function decideApproval(input: ApprovalDecisionInput): ApprovalDecision;
+/** The `governance_approval` audit payload for a gate evaluation. Recorded
+ *  whether or not the gate was satisfied. */
+export type GovernanceApprovalPayload = {
+    readonly name: string;
+    readonly toEnv: string;
+    readonly toVersion: string;
+    readonly required: number;
+    readonly satisfied: boolean;
+    readonly countedApprovers: ReadonlyArray<string>;
+    readonly prWitness: boolean;
+    readonly prNumber?: number;
+    readonly actor?: string;
+    readonly ts: number;
+};
+export declare function buildGovernancePayload(input: ApprovalDecisionInput, decision: ApprovalDecision, opts: {
+    readonly actor?: string;
+    readonly now: () => number;
+}): GovernanceApprovalPayload;

package/dist/approval-gate.js

@@ -0,0 +1,254 @@
+/**
+ * Item 59 (half 1) — approval-gated promotion. `crewhaus deploy promote
+ * --require-approval` must not flip a PROTECTED environment's pin until an
+ * approval quorum is satisfied: a recorded set of approval tokens AND/OR a
+ * green PR check. The gate is a side-effect-free decision layer that runs
+ * BEFORE the deployment-controller's `promote` — the controller stays a dumb
+ * pin-flipper; policy lives here (and is testable without a registry).
+ *
+ * Factored out of the entry file `index.ts` (which runs a top-level argv
+ * switch and so cannot be imported by a test without executing the CLI).
+ * Mirrors `retention.ts` / `audit-verify.ts`: pure config + decision, plus a
+ * thin recorded-approvals reader over `.crewhaus/approvals`.
+ *
+ * WHAT IS PROTECTED — `.crewhaus/environments.json` declares which
+ * environments require approval and how many:
+ *
+ *   { "environments": {
+ *       "prod":    { "requireApproval": true,  "minApprovals": 2 },
+ *       "staging": { "requireApproval": false }
+ *   } }
+ *
+ * A missing file / missing entry means the env is UNPROTECTED (the pre-item-59
+ * behavior — `promote` runs unconditionally). `--require-approval` is opt-in
+ * per invocation; an env can also be marked protected in the config so a
+ * plain `promote` to it is refused with a pointer to `--require-approval`.
+ *
+ * WHAT SATISFIES THE GATE — two independent, OR-combined witnesses:
+ *   1. Recorded approvals: `.crewhaus/approvals/<spec>__<env>.json` holds an
+ *      array of `{ approver, ts, version? }`. Distinct approvers count toward
+ *      `minApprovals`; an approval pinned to a DIFFERENT candidate version
+ *      than the one being promoted does not count (you approved v2, not v3).
+ *   2. A green PR check: an injected `PrCheckReader` resolves the merge/CI
+ *      state of the proposal PR for this change. A `success` conclusion
+ *      counts as one collective approval witness (a reviewed+green PR is the
+ *      team's sign-off) — enough on its own only when `minApprovals <= 1`,
+ *      otherwise it ADDS to the recorded-approval count.
+ *
+ * The gate NEVER approves itself: with no witnesses it refuses, and the
+ * refusal is as audit-worthy as the approval — both produce a
+ * `governance_approval` record so a scheduled promotion that was blocked is
+ * evidenced too.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Thrown for malformed config / approvals files. The CLI routes the message
+ *  through `die()`; tests assert on `.message`. */
+export class ApprovalGateError extends Error {
+    name = "ApprovalGateError";
+}
+export const ENVIRONMENTS_CONFIG_RELPATH = ".crewhaus/environments.json";
+export const APPROVALS_RELDIR = ".crewhaus/approvals";
+/**
+ * Load `.crewhaus/environments.json` from a harness root. A missing file
+ * yields the all-unprotected default (`fromFile: false`). A present-but-
+ * malformed file throws — a protected-env policy that silently degraded to
+ * "unprotected" would be the worst possible failure mode.
+ */
+export function loadEnvironmentsConfig(rootDir) {
+    const path = join(rootDir, ENVIRONMENTS_CONFIG_RELPATH);
+    if (!existsSync(path))
+        return { environments: {}, fromFile: false };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        throw new ApprovalGateError(`${ENVIRONMENTS_CONFIG_RELPATH} is not valid JSON: ${err.message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new ApprovalGateError(`${ENVIRONMENTS_CONFIG_RELPATH} must be a JSON object`);
+    }
+    const envsRaw = parsed["environments"];
+    if (typeof envsRaw !== "object" || envsRaw === null) {
+        throw new ApprovalGateError(`${ENVIRONMENTS_CONFIG_RELPATH} must carry an "environments" object`);
+    }
+    const environments = {};
+    for (const [env, v] of Object.entries(envsRaw)) {
+        if (typeof v !== "object" || v === null) {
+            throw new ApprovalGateError(`environments.${env} must be an object`);
+        }
+        const rec = v;
+        const requireApproval = rec["requireApproval"] === true;
+        let minApprovals = 1;
+        if (rec["minApprovals"] !== undefined) {
+            const n = rec["minApprovals"];
+            if (typeof n !== "number" || !Number.isInteger(n) || n < 1) {
+                throw new ApprovalGateError(`environments.${env}.minApprovals must be a positive integer`);
+            }
+            minApprovals = n;
+        }
+        environments[env] = { requireApproval, minApprovals };
+    }
+    return { environments, fromFile: true };
+}
+/** The policy for `env`, or an unprotected default. */
+export function policyForEnv(config, env) {
+    return config.environments[env] ?? { requireApproval: false, minApprovals: 1 };
+}
+/** Approvals file name for a (spec, env) pair. `/` is not possible in a spec
+ *  registry name, so `__` is a safe joiner. */
+export function approvalsFileName(specName, env) {
+    return `${specName}__${env}.json`;
+}
+/**
+ * Read recorded approvals for a (spec, env) from
+ * `.crewhaus/approvals/<spec>__<env>.json`. Missing file → []. A malformed
+ * file throws (a dropped approval could silently under-count the quorum).
+ */
+export function readApprovals(rootDir, specName, env) {
+    const path = join(rootDir, APPROVALS_RELDIR, approvalsFileName(specName, env));
+    if (!existsSync(path))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        throw new ApprovalGateError(`approvals file ${path} is not valid JSON: ${err.message}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new ApprovalGateError(`approvals file ${path} must be a JSON array of { approver, ts }`);
+    }
+    const out = [];
+    for (const item of parsed) {
+        if (typeof item !== "object" || item === null)
+            continue;
+        const rec = item;
+        if (typeof rec["approver"] !== "string" || typeof rec["ts"] !== "string")
+            continue;
+        out.push({
+            approver: rec["approver"],
+            ts: rec["ts"],
+            ...(typeof rec["version"] === "string" ? { version: rec["version"] } : {}),
+            ...(typeof rec["comment"] === "string" ? { comment: rec["comment"] } : {}),
+        });
+    }
+    return out;
+}
+/** Terminal check conclusions/states that mean FAILURE (fail-closed). */
+const ROLLUP_FAILED = new Set([
+    "FAILURE",
+    "CANCELLED",
+    "TIMED_OUT",
+    "ACTION_REQUIRED",
+    "STARTUP_FAILURE",
+    "STALE",
+    "ERROR",
+]);
+/** States that mean a check is still RUNNING (not yet a witness). */
+const ROLLUP_RUNNING = new Set([
+    "PENDING",
+    "IN_PROGRESS",
+    "QUEUED",
+    "WAITING",
+    "REQUESTED",
+]);
+/**
+ * F3(a) — FAIL-CLOSED rollup verdict. A PR is a `success` witness ONLY when it
+ * has at least one check AND every check terminated in an explicit SUCCESS.
+ * Any failure/cancel/timeout, any still-running check, and any
+ * SKIPPED/NEUTRAL/unknown conclusion yields NOT a witness — an ambiguous or
+ * non-passing state must never sign off a protected promotion.
+ */
+export function rollupConclusion(rollup) {
+    if (rollup.length === 0)
+        return "none";
+    let anyFail = false;
+    let anyPending = false;
+    let allSuccess = true;
+    for (const c of rollup) {
+        const state = (c.state ?? "").toUpperCase();
+        const conclusion = (c.conclusion ?? "").toUpperCase();
+        const terminal = conclusion !== "" ? conclusion : state;
+        if (ROLLUP_RUNNING.has(state) || ROLLUP_RUNNING.has(conclusion) || terminal === "") {
+            anyPending = true;
+        }
+        if (ROLLUP_FAILED.has(state) || ROLLUP_FAILED.has(conclusion))
+            anyFail = true;
+        // Only an explicit SUCCESS counts toward "all passed"; SKIPPED/NEUTRAL/
+        // anything else leaves allSuccess false (fail-closed).
+        if (terminal !== "SUCCESS")
+            allSuccess = false;
+    }
+    if (anyFail)
+        return "failure";
+    if (anyPending)
+        return "pending";
+    return allSuccess ? "success" : "none";
+}
+/**
+ * F3(b) — does this PR reference `version` as a bounded token in its head ref,
+ * title, or body? `propose` names the branch `propose/<slug>-<version>-<hash>-
+ * <stamp>`, so the version is a bounded segment of the head ref; a bare
+ * substring match would let `v1` witness `v10`, so require non-alphanumeric
+ * (or string-edge) bounds. Binds the PR witness to the EXACT promoted version.
+ */
+export function prReferencesVersion(pr, version) {
+    const esc = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const bounded = new RegExp(`(^|[^A-Za-z0-9.])${esc}([^A-Za-z0-9.]|$)`);
+    return [pr.headRefName, pr.title, pr.body].some((s) => typeof s === "string" && bounded.test(s));
+}
+/**
+ * Decide whether the gate is satisfied. Counts DISTINCT approvers whose
+ * approval either carries no version pin or matches `toVersion`, plus one
+ * collective witness for a green PR check. Satisfied when
+ * `witnesses >= required`.
+ */
+export function decideApproval(input) {
+    const required = input.policy.minApprovals;
+    const counted = new Set();
+    for (const a of input.approvals) {
+        if (a.version !== undefined && a.version !== input.toVersion)
+            continue;
+        counted.add(a.approver);
+    }
+    const prWitness = input.prCheck?.conclusion === "success";
+    const witnesses = counted.size + (prWitness ? 1 : 0);
+    const satisfied = witnesses >= required;
+    let reason;
+    if (satisfied) {
+        const parts = [];
+        if (counted.size > 0)
+            parts.push(`${counted.size} recorded approval(s): ${[...counted].sort().join(", ")}`);
+        if (prWitness)
+            parts.push(`green PR check (#${input.prCheck?.prNumber ?? "?"})`);
+        reason = `quorum met (${witnesses}/${required}) — ${parts.join("; ")}`;
+    }
+    else {
+        const missing = required - witnesses;
+        const detail = [];
+        detail.push(`have ${witnesses} witness(es), need ${required}`);
+        if (counted.size > 0)
+            detail.push(`approvers: ${[...counted].sort().join(", ")}`);
+        if (input.prCheck !== undefined && !prWitness) {
+            detail.push(`PR check: ${input.prCheck.conclusion}`);
+        }
+        reason = `quorum NOT met — ${detail.join("; ")} (${missing} more needed; record approvals in ${APPROVALS_RELDIR}/${approvalsFileName(input.specName, input.toEnv)} or land a green proposal PR)`;
+    }
+    return { satisfied, countedApprovers: [...counted].sort(), prWitness, required, reason };
+}
+export function buildGovernancePayload(input, decision, opts) {
+    return {
+        name: input.specName,
+        toEnv: input.toEnv,
+        toVersion: input.toVersion,
+        required: decision.required,
+        satisfied: decision.satisfied,
+        countedApprovers: decision.countedApprovers,
+        prWitness: decision.prWitness,
+        ...(input.prCheck?.prNumber !== undefined ? { prNumber: input.prCheck.prNumber } : {}),
+        ...(opts.actor !== undefined ? { actor: opts.actor } : {}),
+        ts: opts.now(),
+    };
+}

package/dist/audit-verify.d.ts

@@ -0,0 +1,69 @@
+import type { VerifyResult } from "@crewhaus/audit-log";
+/**
+ * Item 34 — `crewhaus audit verify` plumbing, factored out of the entry file
+ * `index.ts` (which runs a top-level argv switch and so cannot be imported by
+ * a test without executing the CLI). Side-effect-free and directly
+ * unit-testable, mirroring `scope-audit.ts` / `justification-gate.ts` /
+ * `doctor-checks.ts`.
+ *
+ * Two halves:
+ *   1. `resolveAnchorFlag` — parse the `--anchor <scheme>:<path>` flag. Only
+ *      `file:` ships today (`@crewhaus/audit-log`'s `FileAnchorStore`); an
+ *      unknown scheme throws so the entry file can `die()` with the allowed
+ *      list instead of silently skipping the cross-check the user asked for.
+ *   2. `summarizeVerifyResult` — turn the library's `VerifyResult` into the
+ *      per-check ✓/~/✗ summary lines + exit code. The exit-code contract:
+ *      0 only when the chain is intact AND (when an anchor store was
+ *      explicitly requested) the external anchor was actually cross-checked —
+ *      a requested-but-unconsulted anchor exits 1, because a scheduled
+ *      tamper check that silently skipped its strongest witness is worse
+ *      than one that fails loudly.
+ */
+export type AnchorFlagChoice = {
+    readonly scheme: "file";
+    readonly path: string;
+};
+/** Thrown by `resolveAnchorFlag` on a malformed `--anchor` value. The CLI
+ *  entry file catches it and routes the message through `die()`; tests
+ *  assert on `.message` without the process exiting. */
+export declare class InvalidAnchorFlagError extends Error {
+    readonly value: string;
+    readonly name = "InvalidAnchorFlagError";
+    constructor(value: string);
+}
+/**
+ * Parse the raw `--anchor` flag value (or undefined when absent). `file:<path>`
+ * selects the file-backed AnchorStore rooted at `<path>`; anything else —
+ * missing scheme, empty path, unknown scheme (S3 et al. are out of scope) —
+ * throws {@link InvalidAnchorFlagError}.
+ */
+export declare function resolveAnchorFlag(flagValue: string | undefined): AnchorFlagChoice | undefined;
+export type VerifySummary = {
+    readonly lines: ReadonlyArray<string>;
+    readonly exitCode: 0 | 1;
+};
+/**
+ * Render a `VerifyResult` as per-check summary lines + the process exit code.
+ * `anchorRequested` is whether the user passed `--anchor`: when true, an
+ * `ok` result whose external anchor was NOT actually consulted (store empty,
+ * unreadable, or lagging into nonexistence) is a FAILURE — the check the
+ * user scheduled did not run, so exiting 0 would fabricate assurance.
+ */
+export declare function summarizeVerifyResult(result: VerifyResult, opts: {
+    readonly anchorRequested: boolean;
+}): VerifySummary;
+/** Shape shared with `index.ts`'s DoctorCheck (label/pass/warn/reason). */
+export type AuditIntegrityCheck = {
+    readonly label: string;
+    readonly pass: boolean;
+    readonly warn?: boolean;
+    readonly reason?: string;
+};
+/**
+ * Map a `VerifyResult` onto the doctor's ✓/~/✗ check shape so `crewhaus
+ * doctor` can surface audit-log tampering when a `.crewhaus/audit` store
+ * exists in the cwd. An intact chain without the on-host anchor is a warn
+ * ("~"), never a failure — mirroring the library's limitation-not-tamper
+ * stance — and a broken chain fails doctor with the first finding inline.
+ */
+export declare function buildAuditIntegrityCheck(result: VerifyResult): AuditIntegrityCheck;