@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/signoff/proof-record.d.ts

@@ -0,0 +1,202 @@
+import { z } from 'zod';
+/** Bumped when the canonical body shape changes; a verifier refuses versions it does not know. */
+export declare const SIGNOFF_PROOF_VERSION = 1;
+declare const signoffProofStepSchema: z.ZodObject<{
+    id: z.ZodString;
+    command: z.ZodString;
+    cwd: z.ZodString;
+    status: z.ZodEnum<{
+        skipped: "skipped";
+        failed: "failed";
+        cancelled: "cancelled";
+        blocked: "blocked";
+        passed: "passed";
+    }>;
+    exitCode: z.ZodNumber;
+    durationMs: z.ZodNumber;
+    startedAt: z.ZodString;
+    outputSha256: z.ZodString;
+}, z.core.$strip>;
+declare const signoffProofPeerSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const signoffProofSubjectSchema: z.ZodObject<{
+    repo: z.ZodString;
+    commit: z.ZodString;
+    tree: z.ZodString;
+    commitTree: z.ZodString;
+    parents: z.ZodArray<z.ZodString>;
+    committedAt: z.ZodString;
+}, z.core.$strip>;
+declare const signoffProofBodySchema: z.ZodObject<{
+    proofVersion: z.ZodNumber;
+    subject: z.ZodObject<{
+        repo: z.ZodString;
+        commit: z.ZodString;
+        tree: z.ZodString;
+        commitTree: z.ZodString;
+        parents: z.ZodArray<z.ZodString>;
+        committedAt: z.ZodString;
+    }, z.core.$strip>;
+    signedAt: z.ZodString;
+    host: z.ZodObject<{
+        hostname: z.ZodString;
+        platform: z.ZodString;
+        arch: z.ZodString;
+        user: z.ZodString;
+    }, z.core.$strip>;
+    tooling: z.ZodObject<{
+        node: z.ZodString;
+        pnpm: z.ZodNullable<z.ZodString>;
+        peers: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    wallClockMs: z.ZodNumber;
+    seeds: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    declaredRequired: z.ZodArray<z.ZodString>;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        command: z.ZodString;
+        cwd: z.ZodString;
+        status: z.ZodEnum<{
+            skipped: "skipped";
+            failed: "failed";
+            cancelled: "cancelled";
+            blocked: "blocked";
+            passed: "passed";
+        }>;
+        exitCode: z.ZodNumber;
+        durationMs: z.ZodNumber;
+        startedAt: z.ZodString;
+        outputSha256: z.ZodString;
+    }, z.core.$strip>>;
+    verdict: z.ZodEnum<{
+        fail: "fail";
+        pass: "pass";
+    }>;
+}, z.core.$strip>;
+declare const signoffProofSealSchema: z.ZodObject<{
+    algorithm: z.ZodEnum<{
+        sha256: "sha256";
+        "hmac-sha256": "hmac-sha256";
+    }>;
+    bodySha256: z.ZodString;
+    keyId: z.ZodNullable<z.ZodString>;
+    mac: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const signoffProofSchema: z.ZodObject<{
+    body: z.ZodObject<{
+        proofVersion: z.ZodNumber;
+        subject: z.ZodObject<{
+            repo: z.ZodString;
+            commit: z.ZodString;
+            tree: z.ZodString;
+            commitTree: z.ZodString;
+            parents: z.ZodArray<z.ZodString>;
+            committedAt: z.ZodString;
+        }, z.core.$strip>;
+        signedAt: z.ZodString;
+        host: z.ZodObject<{
+            hostname: z.ZodString;
+            platform: z.ZodString;
+            arch: z.ZodString;
+            user: z.ZodString;
+        }, z.core.$strip>;
+        tooling: z.ZodObject<{
+            node: z.ZodString;
+            pnpm: z.ZodNullable<z.ZodString>;
+            peers: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                version: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        wallClockMs: z.ZodNumber;
+        seeds: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        declaredRequired: z.ZodArray<z.ZodString>;
+        steps: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            command: z.ZodString;
+            cwd: z.ZodString;
+            status: z.ZodEnum<{
+                skipped: "skipped";
+                failed: "failed";
+                cancelled: "cancelled";
+                blocked: "blocked";
+                passed: "passed";
+            }>;
+            exitCode: z.ZodNumber;
+            durationMs: z.ZodNumber;
+            startedAt: z.ZodString;
+            outputSha256: z.ZodString;
+        }, z.core.$strip>>;
+        verdict: z.ZodEnum<{
+            fail: "fail";
+            pass: "pass";
+        }>;
+    }, z.core.$strip>;
+    seal: z.ZodObject<{
+        algorithm: z.ZodEnum<{
+            sha256: "sha256";
+            "hmac-sha256": "hmac-sha256";
+        }>;
+        bodySha256: z.ZodString;
+        keyId: z.ZodNullable<z.ZodString>;
+        mac: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SignoffProofStep = z.infer<typeof signoffProofStepSchema>;
+export type SignoffProofPeer = z.infer<typeof signoffProofPeerSchema>;
+export type SignoffProofSubject = z.infer<typeof signoffProofSubjectSchema>;
+export type SignoffProofBody = z.infer<typeof signoffProofBodySchema>;
+export type SignoffProofSeal = z.infer<typeof signoffProofSealSchema>;
+export type SignoffProof = z.infer<typeof signoffProofSchema>;
+type CanonicalValue = string | number | boolean | null | readonly CanonicalValue[] | {
+    readonly [key: string]: CanonicalValue;
+};
+/**
+ * Deterministic JSON: object keys sorted, array order preserved, no whitespace.
+ *
+ * The seal is a hash over this string, so two readers must produce byte-identical
+ * bytes from the same record. `undefined` throws rather than vanishing — a field
+ * that silently disappears is a field the hash stops covering.
+ */
+export declare function canonicalJson(value: CanonicalValue): string;
+export declare function canonicalizeProofBody(body: SignoffProofBody): string;
+export declare function hashProofBody(body: SignoffProofBody): string;
+/** The digest a runner records for a step's combined output. Shared so both halves agree. */
+export declare function hashStepOutput(output: string): string;
+export declare function signoffKeyId(key: Uint8Array): string;
+/** Read the local sign-off key. Throws when absent — an unreadable key is never a silent downgrade to unsealed. */
+export declare function readSignoffKey(path: string): Uint8Array;
+export declare function sealProof(body: SignoffProofBody, key?: Uint8Array): SignoffProof;
+/** Constant-time comparison of two hex digests of equal length. */
+export declare function macMatches(expected: string, actual: string): boolean;
+export interface BuildSignoffProofInput {
+    readonly repoDir: string;
+    /** Repo identity the verifier's required-step table is keyed on. */
+    readonly repo: string;
+    /** Revision the sign-off is for; defaults to `HEAD`. */
+    readonly rev?: string;
+    readonly steps: readonly SignoffProofStep[];
+    /** Measured elapsed time for the run. Required — it is not derivable from the steps. */
+    readonly wallClockMs: number;
+    /** Step ids this run treated as required. Checked against the verifier's table. */
+    readonly declaredRequired: readonly string[];
+    readonly seeds: Readonly<Record<string, string | number>>;
+    readonly peerNames?: readonly string[];
+    readonly key?: Uint8Array;
+    readonly now?: Date;
+}
+export declare function buildSignoffProof(input: BuildSignoffProofInput): SignoffProof;
+/** Parse an untrusted proof document, failing loud on any shape the verifier cannot reason about. */
+export declare function parseSignoffProof(json: string): SignoffProof;
+export declare function serializeSignoffProof(proof: SignoffProof): string;
+/**
+ * The single line an operator pastes into a PR or a merge commit: how many steps
+ * ran, how long it took, the seeds, and the verdict.
+ */
+export declare function formatSignoffSummary(proof: SignoffProof): string;
+export {};

package/dist/signoff/proof-verify.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `verify-proof` — the half a reader runs, on a machine that did not produce
+ * the proof, to decide whether a commit was really signed off.
+ *
+ * The verifier never believes the document. Every claim it can re-derive, it
+ * re-derives from git and compares; every claim it cannot re-derive is reported
+ * as recorded, not as checked. The one field the proof is deliberately not
+ * allowed to own is **which steps were required**: a run that declares its own
+ * bar can declare an empty one, so the authoritative table lives here and a
+ * proof declaring fewer requirements than its repo's table fails as
+ * `lowered-bar`.
+ */
+import type { CommitFacts, IsAncestorFn } from './proof-git';
+import { type SignoffProof } from './proof-record';
+/**
+ * The steps a repo's sign-off MUST cover, transcribed from each repo's CI job.
+ * A runner is free to run more; it may never run fewer.
+ *
+ *   agent-app     .github/workflows/ci.yml
+ *   tax-agent     .github/workflows/deploy.yml (the `ci` job)
+ *   legal-agent   .github/workflows/deploy.yml (the `ci` job)
+ */
+export declare const SIGNOFF_REQUIRED_STEPS: Readonly<Record<string, readonly string[]>>;
+/** Throws for a repo with no table — an unrecognised repo has no bar, and no bar is not a pass. */
+export declare function requiredStepsFor(repo: string): readonly string[];
+export type SignoffFailureCode = 'unsupported-version' | 'body-tampered' | 'mac-missing' | 'mac-invalid' | 'unknown-repo' | 'repo-mismatch' | 'tree-mismatch' | 'dirty-worktree' | 'commit-unbound' | 'missing-required-step' | 'lowered-bar' | 'duplicate-step' | 'step-failed' | 'verdict-fail' | 'stale-proof';
+export interface SignoffFailure {
+    readonly code: SignoffFailureCode;
+    readonly detail: string;
+}
+/** How the proof attaches to the commit that was asked about. */
+export type SignoffCommitBinding = 
+/** The proof names this exact commit. */
+'exact'
+/** A different commit id, but byte-identical content — a rebase or a squash of what was verified. */
+ | 'tree-equivalent'
+/** Neither. The proof does not describe this commit. */
+ | 'none';
+export interface SignoffVerification {
+    readonly ok: boolean;
+    readonly commitBinding: SignoffCommitBinding;
+    /** True only when a key was supplied AND the mac over the canonical body matched. */
+    readonly macChecked: boolean;
+    readonly failures: readonly SignoffFailure[];
+    readonly proof: SignoffProof;
+    readonly target: CommitFacts;
+    readonly requiredSteps: readonly string[];
+}
+export interface VerifySignoffProofOptions {
+    /** The commit the reader is asking about, read from git — never from the proof. */
+    readonly target: CommitFacts;
+    /**
+     * Reachability in the target's history. Required, because the clock cannot
+     * answer staleness on its own: git records committer time to the SECOND, so a
+     * proof and the commit it is being replayed onto routinely share a timestamp.
+     * Ancestry is exact and clock-free.
+     */
+    readonly isAncestor: IsAncestorFn;
+    /** Local HMAC key. Omitted, the mac is reported unchecked rather than assumed good. */
+    readonly key?: Uint8Array;
+    /** Overrides the built-in table. Supplying `[]` is a deliberate no-bar check, and says so. */
+    readonly requiredSteps?: readonly string[];
+    /** Repo identity the caller expects; a mismatch against the proof is a failure, not a rename. */
+    readonly expectRepo?: string;
+}
+export declare function verifySignoffProof(proof: SignoffProof, options: VerifySignoffProofOptions): SignoffVerification;
+export interface VerifySignoffAtRevInput {
+    readonly repoDir: string;
+    readonly rev: string;
+    readonly key?: Uint8Array;
+    readonly requiredSteps?: readonly string[];
+    readonly expectRepo?: string;
+}
+type SignoffLookupFailure = {
+    readonly found: false;
+    readonly commit: string;
+    readonly hint: readonly string[];
+};
+export type SignoffVerifyOutcome = ({
+    readonly found: true;
+} & SignoffVerification) | SignoffLookupFailure;
+/** Verify by revision: find the proof attached to that SHA (or to its content), then check it. */
+export declare function verifySignoffAtRev(input: VerifySignoffAtRevInput): SignoffVerifyOutcome;
+export interface VerifySignoffFileInput {
+    readonly repoDir: string;
+    readonly file: string;
+    /**
+     * The commit to check the file against. REQUIRED, and deliberately not
+     * defaulted to the commit the proof names: a proof checked against its own
+     * subject can never fail the commit binding, which is a check that reads as
+     * strong and cannot catch anything. The reader always states what they are
+     * asking about.
+     */
+    readonly rev: string;
+    readonly key?: Uint8Array;
+    readonly requiredSteps?: readonly string[];
+    readonly expectRepo?: string;
+}
+/** Verify a proof document on disk. The repo is still required — "matches the tree it claims" is not answerable without it. */
+export declare function verifySignoffProofFile(input: VerifySignoffFileInput): SignoffVerification;
+/** One line per failure, prefixed by its code, in the order the checks ran. */
+export declare function formatSignoffVerification(result: SignoffVerification): string;
+export {};

package/dist/signoff/proof.d.ts

@@ -1,314 +1,39 @@
-import { z } from 'zod';
-import { b as SignoffReport } from '../types-Bd6uW9vQ.js';
-
 /**
- * Is `ancestor` reachable from `descendant`? A port rather than a direct call so
- * the verifier stays a pure function over facts a caller supplies.
+ * The sign-off proof surface: build a machine-checkable record of a local
+ * verification run, attach it to the commit it verified, and check it later.
+ *
+ * Node-only (git, `fs`, `crypto`) and deliberately its own subpath, the way
+ * `/peer-floors` is — a consumer runs this from a script, never from a bundle.
+ *
+ * The threat model is in `proof-record.ts` and the carrier tradeoff is in
+ * `proof-attach.ts`. Both are load-bearing; read them before relying on a proof.
+ *
+ * **Surface is narrowed to what a caller composes, not what this file happens
+ * to define.** The `agent-app-signoff` bin itself does NOT build or attach a
+ * proof today — it runs the gate and prints the plain report (`./cli.ts`); the
+ * proof pipeline below is the documented composition [`docs/signoff-proof.md`]
+ * a product wires into its OWN CI step. Schema internals, hashing primitives
+ * and low-level git plumbing (`canonicalJson`, `hashProofBody`, `sealProof`,
+ * `runGit`, the zod schemas, …) stay module-internal, where `knip` can see
+ * them unused rather than reading as committed public API with zero callers.
  */
-type IsAncestorFn = (ancestor: string, descendant: string) => boolean;
-interface CommitFacts {
-    /** 40-hex commit id. */
-    readonly commit: string;
-    /** 40-hex id of the tree the COMMIT points at. */
-    readonly commitTree: string;
-    readonly parents: readonly string[];
-    /** Committer date, UTC ISO-8601 with a `Z` suffix. */
-    readonly committedAt: string;
-}
-
-declare const signoffProofStepSchema: z.ZodObject<{
-    id: z.ZodString;
-    command: z.ZodString;
-    cwd: z.ZodString;
-    status: z.ZodEnum<{
-        passed: "passed";
-        failed: "failed";
-        skipped: "skipped";
-        cancelled: "cancelled";
-        blocked: "blocked";
-    }>;
-    exitCode: z.ZodNumber;
-    durationMs: z.ZodNumber;
-    startedAt: z.ZodString;
-    outputSha256: z.ZodString;
-}, z.core.$strip>;
-declare const signoffProofPeerSchema: z.ZodObject<{
-    name: z.ZodString;
-    version: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>;
-declare const signoffProofSubjectSchema: z.ZodObject<{
-    repo: z.ZodString;
-    commit: z.ZodString;
-    tree: z.ZodString;
-    commitTree: z.ZodString;
-    parents: z.ZodArray<z.ZodString>;
-    committedAt: z.ZodString;
-}, z.core.$strip>;
-declare const signoffProofBodySchema: z.ZodObject<{
-    proofVersion: z.ZodNumber;
-    subject: z.ZodObject<{
-        repo: z.ZodString;
-        commit: z.ZodString;
-        tree: z.ZodString;
-        commitTree: z.ZodString;
-        parents: z.ZodArray<z.ZodString>;
-        committedAt: z.ZodString;
-    }, z.core.$strip>;
-    signedAt: z.ZodString;
-    host: z.ZodObject<{
-        hostname: z.ZodString;
-        platform: z.ZodString;
-        arch: z.ZodString;
-        user: z.ZodString;
-    }, z.core.$strip>;
-    tooling: z.ZodObject<{
-        node: z.ZodString;
-        pnpm: z.ZodNullable<z.ZodString>;
-        peers: z.ZodArray<z.ZodObject<{
-            name: z.ZodString;
-            version: z.ZodNullable<z.ZodString>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>;
-    wallClockMs: z.ZodNumber;
-    seeds: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
-    declaredRequired: z.ZodArray<z.ZodString>;
-    steps: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        command: z.ZodString;
-        cwd: z.ZodString;
-        status: z.ZodEnum<{
-            passed: "passed";
-            failed: "failed";
-            skipped: "skipped";
-            cancelled: "cancelled";
-            blocked: "blocked";
-        }>;
-        exitCode: z.ZodNumber;
-        durationMs: z.ZodNumber;
-        startedAt: z.ZodString;
-        outputSha256: z.ZodString;
-    }, z.core.$strip>>;
-    verdict: z.ZodEnum<{
-        pass: "pass";
-        fail: "fail";
-    }>;
-}, z.core.$strip>;
-declare const signoffProofSealSchema: z.ZodObject<{
-    algorithm: z.ZodEnum<{
-        sha256: "sha256";
-        "hmac-sha256": "hmac-sha256";
-    }>;
-    bodySha256: z.ZodString;
-    keyId: z.ZodNullable<z.ZodString>;
-    mac: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>;
-declare const signoffProofSchema: z.ZodObject<{
-    body: z.ZodObject<{
-        proofVersion: z.ZodNumber;
-        subject: z.ZodObject<{
-            repo: z.ZodString;
-            commit: z.ZodString;
-            tree: z.ZodString;
-            commitTree: z.ZodString;
-            parents: z.ZodArray<z.ZodString>;
-            committedAt: z.ZodString;
-        }, z.core.$strip>;
-        signedAt: z.ZodString;
-        host: z.ZodObject<{
-            hostname: z.ZodString;
-            platform: z.ZodString;
-            arch: z.ZodString;
-            user: z.ZodString;
-        }, z.core.$strip>;
-        tooling: z.ZodObject<{
-            node: z.ZodString;
-            pnpm: z.ZodNullable<z.ZodString>;
-            peers: z.ZodArray<z.ZodObject<{
-                name: z.ZodString;
-                version: z.ZodNullable<z.ZodString>;
-            }, z.core.$strip>>;
-        }, z.core.$strip>;
-        wallClockMs: z.ZodNumber;
-        seeds: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
-        declaredRequired: z.ZodArray<z.ZodString>;
-        steps: z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            command: z.ZodString;
-            cwd: z.ZodString;
-            status: z.ZodEnum<{
-                passed: "passed";
-                failed: "failed";
-                skipped: "skipped";
-                cancelled: "cancelled";
-                blocked: "blocked";
-            }>;
-            exitCode: z.ZodNumber;
-            durationMs: z.ZodNumber;
-            startedAt: z.ZodString;
-            outputSha256: z.ZodString;
-        }, z.core.$strip>>;
-        verdict: z.ZodEnum<{
-            pass: "pass";
-            fail: "fail";
-        }>;
-    }, z.core.$strip>;
-    seal: z.ZodObject<{
-        algorithm: z.ZodEnum<{
-            sha256: "sha256";
-            "hmac-sha256": "hmac-sha256";
-        }>;
-        bodySha256: z.ZodString;
-        keyId: z.ZodNullable<z.ZodString>;
-        mac: z.ZodNullable<z.ZodString>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-type SignoffProofStep = z.infer<typeof signoffProofStepSchema>;
-type SignoffProofPeer = z.infer<typeof signoffProofPeerSchema>;
-type SignoffProofSubject = z.infer<typeof signoffProofSubjectSchema>;
-type SignoffProofBody = z.infer<typeof signoffProofBodySchema>;
-type SignoffProofSeal = z.infer<typeof signoffProofSealSchema>;
-type SignoffProof = z.infer<typeof signoffProofSchema>;
-/** Read the local sign-off key. Throws when absent — an unreadable key is never a silent downgrade to unsealed. */
-declare function readSignoffKey(path: string): Uint8Array;
-/** Parse an untrusted proof document, failing loud on any shape the verifier cannot reason about. */
-declare function parseSignoffProof(json: string): SignoffProof;
+export { verifySignoffProof, type SignoffCommitBinding, type SignoffFailure, type SignoffFailureCode, type SignoffVerification, type VerifySignoffProofOptions, } from './proof-verify';
+export { formatSignoffSummary, parseSignoffProof, readSignoffKey } from './proof-record';
+export type { SignoffProof, SignoffProofBody, SignoffProofPeer, SignoffProofSeal, SignoffProofStep, SignoffProofSubject, } from './proof-record';
+/** Types needed to construct `VerifySignoffProofOptions.target`/`.isAncestor`
+ *  without pulling in this package's OWN git-shelling implementation — a
+ *  consumer supplies commit facts and ancestry however it already tracks
+ *  them (its own git library, a cache, …). */
+export type { CommitFacts, IsAncestorFn } from './proof-git';
 /**
- * The single line an operator pastes into a PR or a merge commit: how many steps
- * ran, how long it took, the seeds, and the verdict.
+ * The SIGNING side — building a proof from a report and attaching it to the
+ * commit it verified. Nobody in this repo calls these today (the census that
+ * justified narrowing this barrel found zero callers, this pair included);
+ * they stay exported anyway because `docs/signoff-proof.md`'s documented
+ * composition is the ONLY way to reach them at all — `package.json` declares
+ * no `./signoff/proof-attach` or `./signoff/proof-from-report` subpath, so
+ * dropping these here would make a real, tested, documented capability
+ * unreachable from outside the package, not merely unexercised inside it.
  */
-declare function formatSignoffSummary(proof: SignoffProof): string;
-
-/**
- * `verify-proof` — the half a reader runs, on a machine that did not produce
- * the proof, to decide whether a commit was really signed off.
- *
- * The verifier never believes the document. Every claim it can re-derive, it
- * re-derives from git and compares; every claim it cannot re-derive is reported
- * as recorded, not as checked. The one field the proof is deliberately not
- * allowed to own is **which steps were required**: a run that declares its own
- * bar can declare an empty one, so the authoritative table lives here and a
- * proof declaring fewer requirements than its repo's table fails as
- * `lowered-bar`.
- */
-
-type SignoffFailureCode = 'unsupported-version' | 'body-tampered' | 'mac-missing' | 'mac-invalid' | 'unknown-repo' | 'repo-mismatch' | 'tree-mismatch' | 'dirty-worktree' | 'commit-unbound' | 'missing-required-step' | 'lowered-bar' | 'duplicate-step' | 'step-failed' | 'verdict-fail' | 'stale-proof';
-interface SignoffFailure {
-    readonly code: SignoffFailureCode;
-    readonly detail: string;
-}
-/** How the proof attaches to the commit that was asked about. */
-type SignoffCommitBinding = 
-/** The proof names this exact commit. */
-'exact'
-/** A different commit id, but byte-identical content — a rebase or a squash of what was verified. */
- | 'tree-equivalent'
-/** Neither. The proof does not describe this commit. */
- | 'none';
-interface SignoffVerification {
-    readonly ok: boolean;
-    readonly commitBinding: SignoffCommitBinding;
-    /** True only when a key was supplied AND the mac over the canonical body matched. */
-    readonly macChecked: boolean;
-    readonly failures: readonly SignoffFailure[];
-    readonly proof: SignoffProof;
-    readonly target: CommitFacts;
-    readonly requiredSteps: readonly string[];
-}
-interface VerifySignoffProofOptions {
-    /** The commit the reader is asking about, read from git — never from the proof. */
-    readonly target: CommitFacts;
-    /**
-     * Reachability in the target's history. Required, because the clock cannot
-     * answer staleness on its own: git records committer time to the SECOND, so a
-     * proof and the commit it is being replayed onto routinely share a timestamp.
-     * Ancestry is exact and clock-free.
-     */
-    readonly isAncestor: IsAncestorFn;
-    /** Local HMAC key. Omitted, the mac is reported unchecked rather than assumed good. */
-    readonly key?: Uint8Array;
-    /** Overrides the built-in table. Supplying `[]` is a deliberate no-bar check, and says so. */
-    readonly requiredSteps?: readonly string[];
-    /** Repo identity the caller expects; a mismatch against the proof is a failure, not a rename. */
-    readonly expectRepo?: string;
-}
-declare function verifySignoffProof(proof: SignoffProof, options: VerifySignoffProofOptions): SignoffVerification;
-
-/**
- * The join between the runner and the proof: one sign-off run produces one
- * report, and this turns that report into the signed, attachable record.
- *
- * Nothing here re-runs or re-judges anything. The runner owns what happened; the
- * proof owns what is provable about it later. Keeping the two in one direction
- * is what stops a second, drifting idea of "which steps ran" from appearing.
- */
-
-interface ProofFromReportInput {
-    readonly report: SignoffReport;
-    /** Repo identity the verifier's required-step table is keyed on. */
-    readonly repo: string;
-    /** Source repository. Defaults to the root the run recorded. */
-    readonly repoDir?: string;
-    /** Step ids the run treated as required. Defaults to every step the report carries. */
-    readonly declaredRequired?: readonly string[];
-    readonly key?: Uint8Array;
-    readonly now?: Date;
-}
-declare function proofFromSignoffReport(input: ProofFromReportInput): SignoffProof;
-
-/**
- * Attaching a proof to the commit it verified.
- *
- * ## Why `git notes`, and what the two rejected carriers cost
- *
- * **A commit-message trailer** cannot work for the field that matters. The
- * trailer is part of the commit object, so writing it changes the SHA the proof
- * claims to cover — the proof would have to be produced before the commit it
- * names exists. Amending re-writes the SHA again, and GitHub's squash-merge
- * rebuilds the message from the PR body, so the trailer does not survive the one
- * transition it would need to.
- *
- * **A committed artifact directory** (`.signoff/<sha>.json`) changes the tree,
- * so the tree hash inside the proof can never cover the file carrying it. It
- * also lands in every diff, and it is exactly the "file someone can forget"
- * shape the requirement rules out — deleting it is a normal-looking change.
- *
- * **`git notes` wins because it is the only carrier that is addressed BY the
- * SHA without being part of it.** The note is written after the commit exists,
- * it changes neither the SHA nor the tree, and `git notes show <sha>` is a
- * definite yes/no for any commit anyone can name.
- *
- * ## The tradeoff `git notes` really carries, and how this module answers it
- *
- * Notes are attached to a commit id, and a rebase or a squash-merge produces a
- * NEW commit id, so the note does not follow by itself. Two mechanisms close
- * that gap, and both are needed:
- *
- *  1. `notes.rewriteRef` (see `SIGNOFF_NOTES_GIT_CONFIG`) makes local rebase and
- *     amend copy the note forward automatically.
- *  2. `resolveSignoffProof` falls back to a **tree scan**: it reads every proof
- *     under the notes ref and matches on the TREE the commit carries. A rebase
- *     or a squash of one branch onto an unchanged base preserves the tree, so
- *     the content that was verified is still provably the content that merged,
- *     even though the SHA changed. The verifier reports which binding it used —
- *     `exact` or `tree-equivalent` — and never conflates them.
- *
- * Notes are neither pushed nor fetched by default; `SIGNOFF_NOTES_GIT_CONFIG`
- * carries the refspecs that fix that, and a missing note is reported as
- * `not-found`, never as a pass.
- */
-
-interface AttachSignoffProofInput {
-    readonly repoDir: string;
-    readonly proof: SignoffProof;
-    /** Revision to annotate; defaults to the commit the proof names. */
-    readonly rev?: string;
-    /** Replace an existing note. Off by default so a second sign-off cannot quietly overwrite the first. */
-    readonly overwrite?: boolean;
-}
-interface AttachedSignoffProof {
-    readonly commit: string;
-    readonly ref: string;
-}
-declare function attachSignoffProof(input: AttachSignoffProofInput): AttachedSignoffProof;
-
-export { type AttachSignoffProofInput, type AttachedSignoffProof, type CommitFacts, type IsAncestorFn, type ProofFromReportInput, type SignoffCommitBinding, type SignoffFailure, type SignoffFailureCode, type SignoffProof, type SignoffProofBody, type SignoffProofPeer, type SignoffProofSeal, type SignoffProofStep, type SignoffProofSubject, type SignoffVerification, type VerifySignoffProofOptions, attachSignoffProof, formatSignoffSummary, parseSignoffProof, proofFromSignoffReport, readSignoffKey, verifySignoffProof };
+export { proofFromSignoffReport, type ProofFromReportInput } from './proof-from-report';
+export { attachSignoffProof, type AttachSignoffProofInput, type AttachedSignoffProof } from './proof-attach';

package/dist/signoff/report.d.ts

@@ -0,0 +1,7 @@
+import type { SignoffReport, SignoffStepResult } from './types';
+/** Concurrency actually achieved, measured from the step windows rather than
+ *  asserted from the config. A claimed speedup nobody measured is a wish. */
+export declare function peakConcurrency(steps: readonly SignoffStepResult[]): number;
+export declare function formatSignoffReport(report: SignoffReport): string;
+/** One line for a commit message, a PR comment, or a chat handoff. */
+export declare function formatSignoffLine(report: SignoffReport): string;