@tangle-network/agent-app 0.45.25 → 0.45.27

package/dist/signoff/proof.d.ts

@@ -0,0 +1,515 @@
+import { z } from 'zod';
+import { b as SignoffReport } from '../types-U7Nz-txa.js';
+
+/** Bumped when the canonical body shape changes; a verifier refuses versions it does not know. */
+declare const SIGNOFF_PROOF_VERSION = 1;
+/**
+ * The runner's step outcomes, restated as proof vocabulary.
+ *
+ * A status is carried alongside the exit code because they answer different
+ * questions and only one of them is safe on its own: a step that was `skipped`,
+ * `cancelled` or `blocked` never produced an exit code at all, and defaulting
+ * that to `0` is precisely how a run that did not happen reads as a pass.
+ *
+ * The `satisfies` and the `Exclude` below pin this list to the runner's own
+ * union in BOTH directions, so a status added there fails this file's typecheck
+ * instead of quietly arriving as an unmodelled string.
+ */
+declare const SIGNOFF_STEP_STATUSES: readonly ["passed", "failed", "skipped", "cancelled", "blocked"];
+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>;
+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.
+ */
+declare function canonicalJson(value: CanonicalValue): string;
+declare function canonicalizeProofBody(body: SignoffProofBody): string;
+declare function hashProofBody(body: SignoffProofBody): string;
+/** The digest a runner records for a step's combined output. Shared so both halves agree. */
+declare function hashStepOutput(output: string): string;
+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. */
+declare function readSignoffKey(path: string): Uint8Array;
+declare function sealProof(body: SignoffProofBody, key?: Uint8Array): SignoffProof;
+/** Constant-time comparison of two hex digests of equal length. */
+declare function macMatches(expected: string, actual: string): boolean;
+interface ToolingFactsInput {
+    readonly repoDir: string;
+    /** Package names whose resolved on-disk version belongs in the proof. */
+    readonly peerNames: readonly string[];
+}
+/**
+ * The versions that actually resolved on disk — the field CI's clean install
+ * makes trustworthy and a warm local `node_modules` does not. A below-floor peer
+ * is invisible to typecheck and to a green suite (it fails at the wire call), so
+ * the proof records what was really there rather than what the manifest asks for.
+ */
+declare function collectToolingFacts(input: ToolingFactsInput): SignoffProofBody['tooling'];
+/** Resolved version from the consumer's own `node_modules`, or `null` when the package is not there. */
+declare function readInstalledVersion(repoDir: string, packageName: string): string | null;
+/** Every `@tangle-network/*` name the repo declares as a peer or a dependency. */
+declare function tangleDependencyNames(repoDir: string): readonly string[];
+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;
+}
+declare function buildSignoffProof(input: BuildSignoffProofInput): SignoffProof;
+/** Parse an untrusted proof document, failing loud on any shape the verifier cannot reason about. */
+declare function parseSignoffProof(json: string): SignoffProof;
+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.
+ */
+declare function formatSignoffSummary(proof: SignoffProof): string;
+
+/**
+ * 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.
+ */
+
+/**
+ * A step that never executed has no exit code, so it is recorded as one no
+ * process can produce. `status` is what a reader and the verifier judge on;
+ * this exists so the field is never a plausible-looking `0`.
+ */
+declare const NO_EXIT_CODE = -1;
+/** The `command` of a step that never executed. A skipped step had no command line. */
+declare const NOT_EXECUTED_COMMAND = "(never executed)";
+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;
+}
+/** Every seed the run used, keyed so a reader can replay one step rather than the whole run. */
+declare function seedsFromReport(report: SignoffReport): Record<string, string | number>;
+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.
+ */
+
+declare const SIGNOFF_NOTES_REF = "refs/notes/signoff";
+/**
+ * The git configuration a repo needs for notes to travel. Emitted by the CLI
+ * when a proof cannot be found, because the usual cause is an unconfigured repo
+ * rather than an unsigned commit.
+ */
+declare const SIGNOFF_NOTES_GIT_CONFIG: readonly string[];
+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;
+type SignoffProofLookup = {
+    readonly found: true;
+    readonly proof: SignoffProof;
+    readonly commit: string;
+    readonly binding: 'exact' | 'tree-equivalent';
+} | {
+    readonly found: false;
+    readonly commit: string;
+};
+/** The note attached to exactly this commit, or `found: false`. Never searches. */
+declare function readSignoffProofNote(repoDir: string, rev: string): SignoffProofLookup;
+/** Every proof stored under the notes ref, paired with the commit it annotates. */
+declare function listSignoffProofs(repoDir: string): readonly {
+    readonly commit: string;
+    readonly proof: SignoffProof;
+}[];
+/**
+ * Answer "was this SHA signed off" for any commit, including one produced by a
+ * rebase or a squash-merge of the branch that was actually verified.
+ *
+ * Exact note first. Then the tree scan — a proof whose `commitTree` equals this
+ * commit's tree verified byte-identical content, which is the strongest claim
+ * available once the SHA has been rewritten. The binding is returned so a caller
+ * can tell the two apart; nothing here treats them as the same thing.
+ */
+declare function resolveSignoffProof(repoDir: string, rev: string): SignoffProofLookup;
+
+/** A git invocation that exited non-zero, carrying stderr so the caller can act. */
+declare class SignoffGitError extends Error {
+    readonly args: readonly string[];
+    readonly status: number | null;
+    readonly stderr: string;
+    constructor(args: readonly string[], status: number | null, stderr: string);
+}
+interface GitResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Run git and hand back the raw result. `GIT_OPTIONAL_LOCKS=0` keeps a read
+ * from touching the index while another agent works the same worktree — this
+ * repo is shared by concurrent sessions.
+ */
+declare function runGit(repoDir: string, args: readonly string[], options?: {
+    readonly input?: string;
+    readonly env?: Readonly<Record<string, string>>;
+}): GitResult;
+/** Run git, or throw. Trailing newline is stripped — every caller wants the value, not the line. */
+declare function gitText(repoDir: string, args: readonly string[], options?: {
+    readonly input?: string;
+    readonly env?: Readonly<Record<string, string>>;
+}): string;
+/**
+ * Is `ancestor` reachable from `descendant`? A port rather than a direct call so
+ * the verifier stays a pure function over facts a caller supplies.
+ */
+type IsAncestorFn = (ancestor: string, descendant: string) => boolean;
+declare function gitIsAncestor(repoDir: string): IsAncestorFn;
+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;
+}
+/** Resolve a revision to the commit it names, failing loud on an unknown rev. */
+declare function resolveCommit(repoDir: string, rev: string): string;
+declare function readCommitFacts(repoDir: string, rev: string): CommitFacts;
+/**
+ * Hash the tree the checks actually ran against, including uncommitted and
+ * untracked (non-ignored) files.
+ *
+ * This is the field that makes drift detectable. A sign-off that ran over an
+ * edited worktree produces a tree id no commit carries, so it cannot verify
+ * against the commit it claims — which is the intended outcome, not a bug.
+ *
+ * Written through a throwaway index (`GIT_INDEX_FILE`) so a concurrent agent's
+ * staged work in the real index is neither read nor disturbed. `git add -A`
+ * honours `.gitignore`, so `node_modules` / `dist` stay out.
+ */
+declare function computeWorktreeTree(repoDir: string): 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`.
+ */
+
+/**
+ * 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)
+ */
+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. */
+declare function requiredStepsFor(repo: string): readonly string[];
+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;
+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[];
+};
+type SignoffVerifyOutcome = ({
+    readonly found: true;
+} & SignoffVerification) | SignoffLookupFailure;
+/** Verify by revision: find the proof attached to that SHA (or to its content), then check it. */
+declare function verifySignoffAtRev(input: VerifySignoffAtRevInput): SignoffVerifyOutcome;
+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. */
+declare function verifySignoffProofFile(input: VerifySignoffFileInput): SignoffVerification;
+/** One line per failure, prefixed by its code, in the order the checks ran. */
+declare function formatSignoffVerification(result: SignoffVerification): string;
+
+export { type AttachSignoffProofInput, type AttachedSignoffProof, type BuildSignoffProofInput, type CommitFacts, type GitResult, type IsAncestorFn, NOT_EXECUTED_COMMAND, NO_EXIT_CODE, type ProofFromReportInput, SIGNOFF_NOTES_GIT_CONFIG, SIGNOFF_NOTES_REF, SIGNOFF_PROOF_VERSION, SIGNOFF_REQUIRED_STEPS, SIGNOFF_STEP_STATUSES, type SignoffCommitBinding, type SignoffFailure, type SignoffFailureCode, SignoffGitError, type SignoffLookupFailure, type SignoffProof, type SignoffProofBody, type SignoffProofLookup, type SignoffProofPeer, type SignoffProofSeal, type SignoffProofStep, type SignoffProofSubject, type SignoffVerification, type SignoffVerifyOutcome, type ToolingFactsInput, type VerifySignoffAtRevInput, type VerifySignoffFileInput, type VerifySignoffProofOptions, attachSignoffProof, buildSignoffProof, canonicalJson, canonicalizeProofBody, collectToolingFacts, computeWorktreeTree, formatSignoffSummary, formatSignoffVerification, gitIsAncestor, gitText, hashProofBody, hashStepOutput, listSignoffProofs, macMatches, parseSignoffProof, proofFromSignoffReport, readCommitFacts, readInstalledVersion, readSignoffKey, readSignoffProofNote, requiredStepsFor, resolveCommit, resolveSignoffProof, runGit, sealProof, seedsFromReport, serializeSignoffProof, signoffKeyId, signoffProofBodySchema, signoffProofSchema, signoffProofSealSchema, signoffProofStepSchema, tangleDependencyNames, verifySignoffAtRev, verifySignoffProof, verifySignoffProofFile };

package/dist/signoff/proof.js

@@ -0,0 +1,148 @@
+import {
+  SIGNOFF_NOTES_GIT_CONFIG,
+  SIGNOFF_NOTES_REF,
+  SIGNOFF_PROOF_VERSION,
+  SIGNOFF_REQUIRED_STEPS,
+  SIGNOFF_STEP_STATUSES,
+  SignoffGitError,
+  attachSignoffProof,
+  buildSignoffProof,
+  canonicalJson,
+  canonicalizeProofBody,
+  collectToolingFacts,
+  computeWorktreeTree,
+  formatSignoffSummary,
+  formatSignoffVerification,
+  gitIsAncestor,
+  gitText,
+  hashProofBody,
+  hashStepOutput,
+  listSignoffProofs,
+  macMatches,
+  parseSignoffProof,
+  readCommitFacts,
+  readInstalledVersion,
+  readSignoffKey,
+  readSignoffProofNote,
+  requiredStepsFor,
+  resolveCommit,
+  resolveSignoffProof,
+  runGit,
+  sealProof,
+  serializeSignoffProof,
+  signoffKeyId,
+  signoffProofBodySchema,
+  signoffProofSchema,
+  signoffProofSealSchema,
+  signoffProofStepSchema,
+  tangleDependencyNames,
+  verifySignoffAtRev,
+  verifySignoffProof,
+  verifySignoffProofFile
+} from "../chunk-N3G3FSM4.js";
+
+// src/signoff/proof-from-report.ts
+var NO_EXIT_CODE = -1;
+var NOT_EXECUTED_COMMAND = "(never executed)";
+function stepFromResult(result, startedAtEpochMs) {
+  const attempts = result.attempts;
+  const worst = attempts.reduce((worstSoFar, attempt) => attempt.exitCode !== 0 ? attempt.exitCode : worstSoFar, 0);
+  return {
+    id: result.name,
+    command: attempts[0]?.command ?? NOT_EXECUTED_COMMAND,
+    cwd: ".",
+    status: result.status,
+    exitCode: attempts.length === 0 ? NO_EXIT_CODE : worst,
+    durationMs: Math.max(0, Math.round(result.durationMs)),
+    startedAt: new Date(startedAtEpochMs + (result.startedAtMs ?? 0)).toISOString(),
+    // Every attempt's output, in order — a shuffled step that failed on the
+    // second seed must not digest to the same value as one that passed twice.
+    outputSha256: hashStepOutput(attempts.map((attempt) => attempt.output).join("\n"))
+  };
+}
+function seedsFromReport(report) {
+  const seeds = { base: report.seedBase };
+  for (const step of report.steps) {
+    step.attempts.forEach((attempt, index) => {
+      if (attempt.seed !== null) seeds[`${step.name}#${index}`] = attempt.seed;
+    });
+  }
+  return seeds;
+}
+function proofFromSignoffReport(input) {
+  const { report } = input;
+  const repoDir = input.repoDir ?? report.repo.root;
+  const facts = readCommitFacts(repoDir, "HEAD");
+  if (facts.commit !== report.repo.head) {
+    throw new Error(`HEAD moved during the sign-off: the run verified ${report.repo.head}, ${repoDir} is now at ${facts.commit}`);
+  }
+  const startedAtEpochMs = Date.parse(report.startedAt);
+  const install = {
+    id: "install",
+    command: report.install.command,
+    cwd: report.workspace,
+    status: report.install.exitCode === 0 ? "passed" : "failed",
+    exitCode: report.install.exitCode,
+    durationMs: Math.max(0, Math.round(report.install.durationMs)),
+    startedAt: new Date(startedAtEpochMs).toISOString(),
+    outputSha256: hashStepOutput(report.install.output)
+  };
+  const steps = [install, ...report.steps.map((step) => stepFromResult(step, startedAtEpochMs))];
+  return buildSignoffProof({
+    repoDir,
+    repo: input.repo,
+    steps,
+    wallClockMs: report.wallClockMs,
+    declaredRequired: input.declaredRequired ?? steps.map((step) => step.id),
+    seeds: seedsFromReport(report),
+    key: input.key,
+    now: input.now
+  });
+}
+export {
+  NOT_EXECUTED_COMMAND,
+  NO_EXIT_CODE,
+  SIGNOFF_NOTES_GIT_CONFIG,
+  SIGNOFF_NOTES_REF,
+  SIGNOFF_PROOF_VERSION,
+  SIGNOFF_REQUIRED_STEPS,
+  SIGNOFF_STEP_STATUSES,
+  SignoffGitError,
+  attachSignoffProof,
+  buildSignoffProof,
+  canonicalJson,
+  canonicalizeProofBody,
+  collectToolingFacts,
+  computeWorktreeTree,
+  formatSignoffSummary,
+  formatSignoffVerification,
+  gitIsAncestor,
+  gitText,
+  hashProofBody,
+  hashStepOutput,
+  listSignoffProofs,
+  macMatches,
+  parseSignoffProof,
+  proofFromSignoffReport,
+  readCommitFacts,
+  readInstalledVersion,
+  readSignoffKey,
+  readSignoffProofNote,
+  requiredStepsFor,
+  resolveCommit,
+  resolveSignoffProof,
+  runGit,
+  sealProof,
+  seedsFromReport,
+  serializeSignoffProof,
+  signoffKeyId,
+  signoffProofBodySchema,
+  signoffProofSchema,
+  signoffProofSealSchema,
+  signoffProofStepSchema,
+  tangleDependencyNames,
+  verifySignoffAtRev,
+  verifySignoffProof,
+  verifySignoffProofFile
+};
+//# sourceMappingURL=proof.js.map

package/dist/signoff/proof.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/signoff/proof-from-report.ts"],"sourcesContent":["/**\n * The join between the runner and the proof: one sign-off run produces one\n * report, and this turns that report into the signed, attachable record.\n *\n * Nothing here re-runs or re-judges anything. The runner owns what happened; the\n * proof owns what is provable about it later. Keeping the two in one direction\n * is what stops a second, drifting idea of \"which steps ran\" from appearing.\n */\nimport { hashStepOutput, buildSignoffProof, type SignoffProof, type SignoffProofStep } from './proof-record'\nimport { readCommitFacts } from './proof-git'\nimport type { SignoffReport, SignoffStepResult } from './types'\n\n/**\n * A step that never executed has no exit code, so it is recorded as one no\n * process can produce. `status` is what a reader and the verifier judge on;\n * this exists so the field is never a plausible-looking `0`.\n */\nexport const NO_EXIT_CODE = -1\n\n/** The `command` of a step that never executed. A skipped step had no command line. */\nexport const NOT_EXECUTED_COMMAND = '(never executed)'\n\nexport interface ProofFromReportInput {\n  readonly report: SignoffReport\n  /** Repo identity the verifier's required-step table is keyed on. */\n  readonly repo: string\n  /** Source repository. Defaults to the root the run recorded. */\n  readonly repoDir?: string\n  /** Step ids the run treated as required. Defaults to every step the report carries. */\n  readonly declaredRequired?: readonly string[]\n  readonly key?: Uint8Array\n  readonly now?: Date\n}\n\nfunction stepFromResult(result: SignoffStepResult, startedAtEpochMs: number): SignoffProofStep {\n  const attempts = result.attempts\n  const worst = attempts.reduce<number>((worstSoFar, attempt) => (attempt.exitCode !== 0 ? attempt.exitCode : worstSoFar), 0)\n  return {\n    id: result.name,\n    command: attempts[0]?.command ?? NOT_EXECUTED_COMMAND,\n    cwd: '.',\n    status: result.status,\n    exitCode: attempts.length === 0 ? NO_EXIT_CODE : worst,\n    durationMs: Math.max(0, Math.round(result.durationMs)),\n    startedAt: new Date(startedAtEpochMs + (result.startedAtMs ?? 0)).toISOString(),\n    // Every attempt's output, in order — a shuffled step that failed on the\n    // second seed must not digest to the same value as one that passed twice.\n    outputSha256: hashStepOutput(attempts.map((attempt) => attempt.output).join('\\n')),\n  }\n}\n\n/** Every seed the run used, keyed so a reader can replay one step rather than the whole run. */\nexport function seedsFromReport(report: SignoffReport): Record<string, string | number> {\n  const seeds: Record<string, string | number> = { base: report.seedBase }\n  for (const step of report.steps) {\n    step.attempts.forEach((attempt, index) => {\n      if (attempt.seed !== null) seeds[`${step.name}#${index}`] = attempt.seed\n    })\n  }\n  return seeds\n}\n\nexport function proofFromSignoffReport(input: ProofFromReportInput): SignoffProof {\n  const { report } = input\n  const repoDir = input.repoDir ?? report.repo.root\n\n  // HEAD moving during a run makes every later claim ambiguous — the checks ran\n  // over one commit and the proof would name another. Refused, not reconciled.\n  const facts = readCommitFacts(repoDir, 'HEAD')\n  if (facts.commit !== report.repo.head) {\n    throw new Error(`HEAD moved during the sign-off: the run verified ${report.repo.head}, ${repoDir} is now at ${facts.commit}`)\n  }\n\n  const startedAtEpochMs = Date.parse(report.startedAt)\n  const install: SignoffProofStep = {\n    id: 'install',\n    command: report.install.command,\n    cwd: report.workspace,\n    status: report.install.exitCode === 0 ? 'passed' : 'failed',\n    exitCode: report.install.exitCode,\n    durationMs: Math.max(0, Math.round(report.install.durationMs)),\n    startedAt: new Date(startedAtEpochMs).toISOString(),\n    outputSha256: hashStepOutput(report.install.output),\n  }\n  const steps = [install, ...report.steps.map((step) => stepFromResult(step, startedAtEpochMs))]\n\n  return buildSignoffProof({\n    repoDir,\n    repo: input.repo,\n    steps,\n    wallClockMs: report.wallClockMs,\n    declaredRequired: input.declaredRequired ?? steps.map((step) => step.id),\n    seeds: seedsFromReport(report),\n    key: input.key,\n    now: input.now,\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBO,IAAM,eAAe;AAGrB,IAAM,uBAAuB;AAcpC,SAAS,eAAe,QAA2B,kBAA4C;AAC7F,QAAM,WAAW,OAAO;AACxB,QAAM,QAAQ,SAAS,OAAe,CAAC,YAAY,YAAa,QAAQ,aAAa,IAAI,QAAQ,WAAW,YAAa,CAAC;AAC1H,SAAO;AAAA,IACL,IAAI,OAAO;AAAA,IACX,SAAS,SAAS,CAAC,GAAG,WAAW;AAAA,IACjC,KAAK;AAAA,IACL,QAAQ,OAAO;AAAA,IACf,UAAU,SAAS,WAAW,IAAI,eAAe;AAAA,IACjD,YAAY,KAAK,IAAI,GAAG,KAAK,MAAM,OAAO,UAAU,CAAC;AAAA,IACrD,WAAW,IAAI,KAAK,oBAAoB,OAAO,eAAe,EAAE,EAAE,YAAY;AAAA;AAAA;AAAA,IAG9E,cAAc,eAAe,SAAS,IAAI,CAAC,YAAY,QAAQ,MAAM,EAAE,KAAK,IAAI,CAAC;AAAA,EACnF;AACF;AAGO,SAAS,gBAAgB,QAAwD;AACtF,QAAM,QAAyC,EAAE,MAAM,OAAO,SAAS;AACvE,aAAW,QAAQ,OAAO,OAAO;AAC/B,SAAK,SAAS,QAAQ,CAAC,SAAS,UAAU;AACxC,UAAI,QAAQ,SAAS,KAAM,OAAM,GAAG,KAAK,IAAI,IAAI,KAAK,EAAE,IAAI,QAAQ;AAAA,IACtE,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAEO,SAAS,uBAAuB,OAA2C;AAChF,QAAM,EAAE,OAAO,IAAI;AACnB,QAAM,UAAU,MAAM,WAAW,OAAO,KAAK;AAI7C,QAAM,QAAQ,gBAAgB,SAAS,MAAM;AAC7C,MAAI,MAAM,WAAW,OAAO,KAAK,MAAM;AACrC,UAAM,IAAI,MAAM,oDAAoD,OAAO,KAAK,IAAI,KAAK,OAAO,cAAc,MAAM,MAAM,EAAE;AAAA,EAC9H;AAEA,QAAM,mBAAmB,KAAK,MAAM,OAAO,SAAS;AACpD,QAAM,UAA4B;AAAA,IAChC,IAAI;AAAA,IACJ,SAAS,OAAO,QAAQ;AAAA,IACxB,KAAK,OAAO;AAAA,IACZ,QAAQ,OAAO,QAAQ,aAAa,IAAI,WAAW;AAAA,IACnD,UAAU,OAAO,QAAQ;AAAA,IACzB,YAAY,KAAK,IAAI,GAAG,KAAK,MAAM,OAAO,QAAQ,UAAU,CAAC;AAAA,IAC7D,WAAW,IAAI,KAAK,gBAAgB,EAAE,YAAY;AAAA,IAClD,cAAc,eAAe,OAAO,QAAQ,MAAM;AAAA,EACpD;AACA,QAAM,QAAQ,CAAC,SAAS,GAAG,OAAO,MAAM,IAAI,CAAC,SAAS,eAAe,MAAM,gBAAgB,CAAC,CAAC;AAE7F,SAAO,kBAAkB;AAAA,IACvB;AAAA,IACA,MAAM,MAAM;AAAA,IACZ;AAAA,IACA,aAAa,OAAO;AAAA,IACpB,kBAAkB,MAAM,oBAAoB,MAAM,IAAI,CAAC,SAAS,KAAK,EAAE;AAAA,IACvE,OAAO,gBAAgB,MAAM;AAAA,IAC7B,KAAK,MAAM;AAAA,IACX,KAAK,MAAM;AAAA,EACb,CAAC;AACH;","names":[]}

package/dist/spend/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node