@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/runtime/attestations.d.ts

@@ -34,12 +34,27 @@
 /**
  * The currently-accepted predicate schema versions. CI rejects any envelope
  * whose `payload.schemaVersion` is not in this allowlist — this is the
- * forward-compatibility hatch (we add a new version here when we change the
- * predicate shape, and CI keeps accepting v1 until we explicitly remove it).
+ * forward-compatibility hatch.
+ *
+ * AISDLC-103 (Verifier Phase 3) narrowed this to `['v3']` only:
+ *  - `v1` envelopes (pre-AISDLC-94, diffHash-only) are rejected.
+ *  - `v2` was never landed as a distinct schemaVersion — the AISDLC-94
+ *    `contentHash` and AISDLC-101 `contentHashV3` shipped under the v1
+ *    schemaVersion as additive optional fields during the dual- and
+ *    triple-hash soak windows.
+ *  - `v3` envelopes carry `contentHashV3` as a required field and DO NOT
+ *    carry `diffHash` or `contentHash` (the legacy hashes are forbidden;
+ *    a v3 envelope smuggling either field is rejected by
+ *    `validatePredicateShape`).
+ *
+ * AISDLC-362 (contentHashV5): adds `'v5'` to the allowlist. v5 envelopes
+ * carry `contentHashV5` AND `signedMergeBase` in addition to v3+v4 hashes
+ * (backward-compat dual-write). The schemaVersion field is bumped to `'v5'`
+ * on new envelopes so verifiers can detect the v5 fast-path immediately.
  *
  * Exported so the `verify-attestation` workflow can `import`/inline it.
  */
-export declare const ACCEPTED_SCHEMA_VERSIONS: readonly ["v1"];
+export declare const ACCEPTED_SCHEMA_VERSIONS: readonly ["v3", "v5"];
 export type SchemaVersion = (typeof ACCEPTED_SCHEMA_VERSIONS)[number];
 /**
  * The DSSE PAE payload type for our predicate. DSSE spec mandates a payload
@@ -83,14 +98,142 @@ export interface AttestationPredicate {
     subject: {
         digest: SubjectDigest;
     };
-    /** sha256 of `git diff origin/main...HEAD` at attestation time. */
-    diffHash: string;
+    /**
+     * Per-file-delta content binding (AISDLC-101 — required as of AISDLC-103
+     * Phase 3). sha256 over a canonical line-per-file string of the form
+     * `<path>\t<fileDeltaHash>\n` (sorted ascending by path), where
+     * `fileDeltaHash[path] = sha256(<base_blob_sha> + ' -> ' +
+     * <head_blob_sha>)`. The base blob SHA comes from the merge-base of the
+     * PR's `<baseRef>` and `<headRef>`; the head blob SHA from the PR's
+     * `<headRef>`.
+     *
+     * Why this is the only content binding in v3:
+     *  - `diffHash` (legacy v1, sha256 of literal `git diff` text) broke on
+     *    every rebase because `@@` hunk headers shift even when the
+     *    post-apply file content doesn't change.
+     *  - `contentHash` (AISDLC-94, sha256 of `(path, head_blob_sha)` per
+     *    file) was rebase-tolerant for the no-overlap case but broke in the
+     *    AISDLC-93 / PR #102 sibling-overlap case (the rebased file's HEAD
+     *    blob contained the sibling's contributions, so the head blob SHA
+     *    changed even though OUR contribution was unchanged).
+     *  - `contentHashV3` commits to the (base, head) blob-pair TRANSITION
+     *    per file ("we moved file F from blob A to blob B"). Stable when
+     *    paired with the producer-side pre-sign rebase from AISDLC-102 even
+     *    in the sibling-overlap case, and a genuine content tampering still
+     *    flips the head blob SHA → fileDeltaHash flips → reject (threat
+     *    model preserved).
+     *
+     * Required for v3 envelopes. The dual-hash (v1 → AISDLC-94) and
+     * triple-hash (AISDLC-94 → AISDLC-101) windows kept this optional under
+     * schemaVersion `v1`; AISDLC-103 narrows the accepted-schema-versions
+     * allowlist to `['v3']` and makes `contentHashV3` mandatory in
+     * `validatePredicateShape`. Legacy envelopes carrying only `diffHash`
+     * and/or `contentHash` are rejected with a schemaVersion-allowlist reason.
+     */
+    contentHashV3: string;
+    /**
+     * Base-independent per-file head-blob binding (AISDLC-193.1). sha256
+     * over `JSON.stringify(sorted([{path, headBlobSha}]))` for every
+     * changed file in `<base>...<head>`, EXCLUDING the envelope file
+     * itself (`.ai-sdlc/attestations/<sha>.dsse.json` — see
+     * `isAttestationEnvelopePath` for the rationale).
+     *
+     * Why both v3 AND v4 ship side by side during the transition:
+     *  - In-flight envelopes signed before AISDLC-193.1 carry only `v3`.
+     *    Verifier accepts those via the existing v3 ancestor walk so the
+     *    queue doesn't reject envelopes that were valid yesterday.
+     *  - New envelopes carry BOTH so the verifier prefers v4 (skip the
+     *    walk, base-independent) but can fall back to v3 if v4 doesn't
+     *    match (= the rare case where head blobs DID change between
+     *    signing and verification — e.g. amend-after-sign).
+     *
+     * After the transition window, `contentHashV3` will be deprecated
+     * and the verifier will require `contentHashV4`. For now both are
+     * populated by `buildPredicate` so any envelope this code emits is
+     * verifiable on both legs. The TypeScript type marks v4 as OPTIONAL
+     * because envelopes parsed from disk that pre-date AISDLC-193.1 will
+     * not carry the field; `validatePredicateShape` accepts the absence
+     * (= legacy v3 envelope) and the verifier falls back to the v3
+     * ancestor walk in that case.
+     */
+    contentHashV4?: string;
+    /**
+     * Delta-hash with embedded frozen merge-base (AISDLC-362 — contentHashV5).
+     *
+     * SHA-256 of canonical JSON: `JSON.stringify({schemaVersion:'v5',
+     * signedMergeBase:'<40-char-sha>',files:[{path,blobSha}...]})` where:
+     *   - `signedMergeBase` is `git merge-base origin/main HEAD` captured at
+     *     sign time and embedded in BOTH the envelope predicate AND the v5 hash
+     *     input so verifier can REPRODUCE the EXACT diff the signer used.
+     *   - `files` is `git diff <signedMergeBase>..HEAD --name-only` with blob
+     *     SHAs from HEAD — same approach as v4 `{path, headBlobSha}` but
+     *     diffed against the FROZEN merge-base, not the moving `origin/main`.
+     *
+     * Why this is the ultimate fix:
+     *   - v4 (`{path, headBlobSha}` from `origin/main..HEAD`) still invalidates
+     *     when a sibling PR merges and its files overlap with our PR — the
+     *     diff base moves from `merge-base-A` to `merge-base-B` and new files
+     *     appear in the diff enumeration even though OUR blobs didn't change.
+     *   - v5 FREEZES the diff base at `signedMergeBase`. On queue rebase:
+     *     verifier uses `git diff <signedMergeBase>..<probe-HEAD>` which
+     *     enumerates the SAME file set as the signer. Non-overlapping sibling
+     *     merges don't add new files to the set → v5 matches.
+     *   - Overlapping sibling merges (a sibling changed the SAME file our PR
+     *     touches) → the head blob SHA of that file differs → v5 hash flips →
+     *     verifier correctly rejects (operator must re-review).
+     *
+     * Optional (populated for v5 envelopes, absent for v3-only legacy envelopes).
+     * When present, the verifier prefers v5 over v4 over v3 (priority order).
+     */
+    contentHashV5?: string;
+    /**
+     * The `git merge-base origin/main HEAD` SHA captured at sign time.
+     * Embedded in the envelope predicate so the verifier can reproduce the
+     * EXACT diff the signer used (`git diff <signedMergeBase>..<probe-HEAD>`).
+     *
+     * Only present when `contentHashV5` is populated (= v5 envelopes). Absent
+     * on legacy v3/v4 envelopes; the verifier falls back to v4 then v3 in
+     * those cases.
+     */
+    signedMergeBase?: string;
     /** sha256 of `.ai-sdlc/review-policy.md` at attestation time. */
     policyHash: string;
     /** Reviewer entries — typically 3 (code/test/security). */
     reviewers: ReviewerEntry[];
     /** Plugin version from `ai-sdlc-plugin/plugin.json`. */
     pluginVersion: string;
+    /**
+     * Pipeline-cli version from `pipeline-cli/package.json` (RFC-0012 Phase 6 /
+     * AISDLC-100.6). Forensic / audit purpose only — the verifier logs this
+     * but does NOT enforce a specific version. Equivalent to AISDLC-87/AISDLC-94's
+     * `pluginVersion` field but for the `@ai-sdlc/pipeline-cli` workspace package.
+     *
+     * Optional in v1 for backward compatibility — envelopes signed BEFORE
+     * pipeline-cli existed (and BEFORE this field landed) carry no
+     * `pipelineVersion` and the verifier still accepts them, logging
+     * `<missing> (legacy envelope)` instead.
+     */
+    pipelineVersion?: string;
+    /**
+     * Harness that produced the developer + reviewer verdicts (AISDLC-202.3).
+     * Populated by the calling adapter (e.g. `CodexHarnessAdapter` sets
+     * `{ name: 'codex', version: '0.128.0' }` when signing a Codex-run task).
+     * Claude Code paths omit this field or set `{ name: 'claude-code' }`.
+     *
+     * Optional for backward compatibility: envelopes produced before
+     * AISDLC-202.3 carry no `harness` field; the verifier accepts them and
+     * logs `<unknown>` when the field is absent. Downstream trust decisions
+     * (e.g. "require Codex review for Claude-developed PRs") can filter on
+     * `harness.name` without failing envelopes that predate this field.
+     *
+     * `name` is constrained to `SHORT_ID` (letters, digits, dot, dash,
+     * underscore) to prevent CR/LF injection into GITHUB_OUTPUT. `version`
+     * is constrained to `SEMVER` when present.
+     */
+    harness?: {
+        name: string;
+        version?: string;
+    };
     /** Iteration count — how many dev rounds the work went through. */
     iterationCount: number;
     /**
@@ -119,7 +262,7 @@ export interface DsseSignature {
     /**
      * Identifier of the public key that produced this signature. Used to
      * look up the trusted-reviewer entry. Free-form — typically `<identity>:
-     * <machine>` (e.g. `dominique@reliablegenius.io:laptop-2025`).
+     * <machine>` (e.g. `contributor@example.com:laptop-2025`).
      */
     keyid: string;
     /** base64-encoded raw ed25519 signature (64 bytes → 88 chars b64). */
@@ -148,13 +291,18 @@ export type VerifyResult = {
     reason: string;
 };
 /**
- * Validate a parsed predicate against the v1 schema regex patterns.
+ * Validate a parsed predicate against the v3 schema regex patterns.
  *
  * Returns `null` when the predicate is shape-valid; otherwise returns
  * a static failure reason that does NOT embed any user-controlled
  * value (just the field path). This is the load-bearing property:
  * the malicious value never reaches the `reason` string, so it can't
  * propagate to GITHUB_OUTPUT or commit-status descriptions.
+ *
+ * AISDLC-103 (Verifier Phase 3): `contentHashV3` is now required, and the
+ * legacy `diffHash` / `contentHash` fields are FORBIDDEN — a predicate
+ * carrying either is treated as a v1/v2 envelope smuggling itself into the
+ * v3 window and rejected with a static reason.
  */
 export declare function validatePredicateShape(parsed: unknown): string | null;
 /**
@@ -165,10 +313,270 @@ export declare function validatePredicateShape(parsed: unknown): string | null;
  * Frozen to discourage callers from mutating it.
  */
 export declare const REQUIRED_REVIEWER_AGENT_IDS: readonly string[];
+/**
+ * Name-equivalence map for the reviewer-set completeness check (AISDLC-252).
+ *
+ * A "role" is satisfied when any of the listed agentIds is present in the
+ * envelope's reviewer set. This lets codex-harness variants (`code-reviewer-codex`,
+ * `test-reviewer-codex`) satisfy the same role as their Claude counterparts,
+ * enabling the bidirectional cross-harness review goal without requiring a
+ * redundant Claude review on Codex-reviewed PRs.
+ *
+ * Security stays Claude-only: `security-reviewer` has no codex variant per
+ * `feedback_subagent_model_selection.md` (Claude Opus for security reasoning
+ * depth is not yet validated for Codex o4-mini).
+ *
+ * The map is keyed by role name (= the canonical agentId), each value is the
+ * set of ALL agentIds that satisfy the role (including the canonical one).
+ *
+ * Frozen to discourage callers from mutating it.
+ */
+export declare const REVIEWER_ROLE_EQUIVALENCES: Readonly<Record<string, readonly string[]>>;
+/**
+ * When the implementer ran in Codex (`predicate.harness.name === 'codex'`),
+ * these reviewer roles MUST be satisfied by a reviewer whose `harness` field
+ * differs from `codex`. Per RFC-0010 §13.10 `requiresIndependentHarnessFrom`:
+ * code and test reviewers must come from a different harness than the
+ * implementer to preserve cross-harness independence.
+ *
+ * Security is excluded — it is always Claude-only regardless.
+ *
+ * Frozen to discourage callers from mutating it.
+ */
+export declare const INDEPENDENCE_REQUIRED_ROLES: readonly string[];
+/**
+ * One entry in the changed-file set used to compute `contentHash`
+ * (AISDLC-94). `path` is the repo-relative forward-slash path; `blobSha`
+ * is the git blob SHA-1 (40 lowercase hex chars) of the file's CURRENT
+ * post-apply content at the attested commit.
+ *
+ * For deleted files, set `blobSha` to the empty string — the canonical
+ * line still includes the path so a delete-vs-keep difference between
+ * two PRs produces different hashes.
+ */
+export interface ChangedFileEntry {
+    path: string;
+    blobSha: string;
+}
+/**
+ * One entry in the per-file-delta set used to compute `contentHashV3`
+ * (AISDLC-101). `path` is the repo-relative forward-slash path;
+ * `baseBlobSha` is the git blob SHA-1 of the file at the merge-base of
+ * `<baseRef>` and `<headRef>` (= the file's content BEFORE the PR's
+ * commits replayed); `headBlobSha` is the git blob SHA-1 of the file at
+ * `<headRef>` (= AFTER the PR's commits).
+ *
+ * For files that don't exist at one of the endpoints (newly added or
+ * deleted), the corresponding `*BlobSha` is the empty string. The
+ * canonical line still includes the path so:
+ *   - "added file" (`base=''`, `head=<sha>`) → distinct from "kept file"
+ *     (`base=<old>`, `head=<new>`)
+ *   - "deleted file" (`base=<old>`, `head=''`) → distinct from "added file"
+ */
+export interface ChangedFileDeltaEntry {
+    path: string;
+    baseBlobSha: string;
+    headBlobSha: string;
+}
+/**
+ * Regex matching the envelope self-exclusion path pattern
+ * `.ai-sdlc/attestations/<sha>.dsse.json`. Used to filter out the
+ * envelope file itself from the file collector for AISDLC-193.1
+ * `contentHashV4` and AISDLC-101 `contentHashV3` purposes.
+ *
+ * The chore-commit pattern signs the predicate at the dev-commit (HEAD
+ * BEFORE the envelope file exists), then the chore commit on top adds
+ * the envelope file at `.ai-sdlc/attestations/<sha>.dsse.json`. If the
+ * collector includes the envelope file in the hashed file set, the
+ * verifier (which runs against PR HEAD = dev-commit + chore commit)
+ * will see an EXTRA entry for the envelope that the signer never saw
+ * → mismatch even on direct PR HEAD without any rebase.
+ *
+ * The exclusion applies to the file COLLECTOR for HASHING purposes
+ * only. The verifier's chore-commit allowlist (`scripts/verify-attestation.mjs`
+ * `CHORE_COMMIT_PATH_ALLOWLIST`) STILL allows the envelope file in the
+ * chore commit's diff — that's a separate concern from "what is in the
+ * file set we hash."
+ *
+ * Anchored with `^...$` against the forward-slash-normalized path so
+ * an attacker cannot bypass with `./.ai-sdlc/attestations/x.dsse.json`
+ * or `foo/.ai-sdlc/attestations/x.dsse.json`. Note that git's
+ * `--name-only` always emits paths relative to the repo root with
+ * forward slashes, so the match is straightforward in practice.
+ */
+export declare const ATTESTATION_ENVELOPE_PATH_PATTERN: RegExp;
+/**
+ * Predicate to determine whether a file path identifies an attestation
+ * envelope and should therefore be excluded from `contentHashV3` /
+ * `contentHashV4` file enumeration. Defensive about backslash
+ * normalization (Windows callers).
+ */
+export declare function isAttestationEnvelopePath(path: string): boolean;
+/**
+ * The "shared churn" exclude list for content-hash computations (AISDLC-258,
+ * AISDLC-362). Applied to v3, v4, and v5 file collectors on BOTH the signer
+ * and verifier sides.
+ *
+ * Files in this list are EXCLUDED from all file collectors. When a file
+ * appears in this list, changes to it after signing (e.g. from a merge-queue
+ * rebase that regenerated `pnpm-lock.yaml`) do NOT cause content-hash
+ * mismatches, so the operator is never asked to re-sign just because a shared
+ * tooling file was regenerated automatically.
+ *
+ * **Security trade-off (operator-approved, 2026-05-10):** An attacker
+ * COULD slip malicious changes through these files undetected (the
+ * attestation would still pass even if the ignore-listed file was
+ * tampered). The operator accepted this risk because:
+ *  - None of these files contain reviewable hand-written code.
+ *  - `pnpm-lock.yaml` is generated from `package.json` (which IS hashed).
+ *  - `CHANGELOG.md` variants are auto-generated by release-please from
+ *    commit history (which IS hashed via the commit-level binding).
+ *  - `generated-schemas.ts` is generated from spec schemas (reviewed
+ *    separately in the spec/ PR that changed them).
+ *
+ * **DO NOT add to this list:** `package.json` (real dep changes are
+ * reviewable), source files, test files, configs, RFCs, or anything a
+ * human writes by hand. The list is intentionally narrow.
+ *
+ * Paths are exact matches against the forward-slash-normalized repo-relative
+ * path emitted by `git diff --name-only`. Patterns (globs/regex) are NOT
+ * supported to keep the list auditable — every entry must be exact.
+ *
+ * Exported so `scripts/verify-attestation.mjs` can import it from the
+ * orchestrator barrel and apply the same exclusions on the verifier side.
+ */
+export declare const CONTENTHASH_SHARED_CHURN_FILES: readonly string[];
+/**
+ * Backward-compatible alias for `CONTENTHASH_SHARED_CHURN_FILES` (renamed in
+ * AISDLC-362). Callers that imported the v4-specific name continue to work.
+ * @deprecated Use `CONTENTHASH_SHARED_CHURN_FILES` instead.
+ */
+export declare const CONTENTHASHV4_IGNORE_FILES: readonly string[];
+/**
+ * Predicate to determine whether a file path should be excluded from
+ * content-hash computations (v3/v4/v5) because it is a "shared churn" file
+ * (see `CONTENTHASH_SHARED_CHURN_FILES`). Defensive about backslash
+ * normalization.
+ *
+ * Note: this predicate is intentionally separate from
+ * `isAttestationEnvelopePath` because the two exclusions serve different
+ * purposes and may diverge independently. Merge them only if the list
+ * becomes large enough to warrant a single unified predicate.
+ */
+export declare function isIgnoredForContentHash(path: string): boolean;
+/**
+ * One entry in the base-independent per-file head-blob set used to
+ * compute `contentHashV4` (AISDLC-193.1). Identical in shape to
+ * `ChangedFileEntry` (AISDLC-94's `contentHash`) but with `headBlobSha`
+ * naming for clarity — v4 binds reviewers' approval to "I approved
+ * THESE files at THESE specific head blobs," nothing about the base.
+ *
+ * Why v4 was added on top of v3:
+ *   - v3 binds the (base_blob, head_blob) PAIR per file. When the
+ *     merge queue rebases the PR onto a sibling-merged main, the base
+ *     blob SHA for shared files changes (the merge-base shifts forward
+ *     to include the sibling's contributions). The fileDeltaHash flips
+ *     even though the post-apply file content the reviewers approved
+ *     hasn't moved → contentHashV3 invalidates → required check fails
+ *     → queue rejects the PR. Net: every queued code-touching PR
+ *     deadlocks at the gate.
+ *   - v4 binds only `{path, headBlobSha}`. The head blob SHA captures
+ *     "this is the EXACT file content the reviewers signed off on."
+ *     Whatever the rebase does to the base ref, as long as the head
+ *     blob SHAs are unchanged, the v4 hash matches.
+ *   - Threat model preserved: any genuine post-sign content tampering
+ *     (someone amends the PR to add unreviewed code) flips the head
+ *     blob SHA → v4 hash flips → verifier rejects.
+ */
+export interface ChangedFileHeadEntry {
+    path: string;
+    headBlobSha: string;
+}
+/**
+ * One entry in the v5 file set used by `computeContentHashV5` (AISDLC-362).
+ * Structurally identical to `ChangedFileHeadEntry` — `path` plus the HEAD
+ * blob SHA. The difference from v4 is that the FILE SET is enumerated via
+ * `git diff <signedMergeBase>..HEAD` (frozen diff base) instead of
+ * `git diff origin/main..HEAD` (moving diff base). Same fields, different
+ * enumeration semantics — separate type for clarity.
+ */
+export interface ChangedFileV5Entry {
+    path: string;
+    blobSha: string;
+}
+/**
+ * Return shape of `collectChangedFileEntriesForV5`. Bundles the frozen
+ * `signedMergeBase` SHA with the file entries so the signer can embed it in
+ * the predicate and the hash without a separate git call.
+ */
+export interface V5CollectResult {
+    /** Files changed between `signedMergeBase` and `headRef`. */
+    entries: ChangedFileV5Entry[];
+    /**
+     * The `git merge-base <baseRef> <headRef>` SHA captured at collection time.
+     * This is the FROZEN diff base embedded in the envelope predicate and the
+     * v5 hash. The verifier uses it to reproduce the exact file set the signer
+     * used: `git diff <signedMergeBase>..<probe-HEAD> --name-only`.
+     */
+    signedMergeBase: string;
+}
+/**
+ * Compute the rebase-stable `contentHashV5` (AISDLC-362) over a file set
+ * and a frozen merge-base SHA.
+ *
+ * Canonical form: `SHA-256(JSON.stringify({schemaVersion:'v5',
+ * signedMergeBase:'<40-char>', files:[{path,blobSha}...]}))` where `files`
+ * is sorted ascending by path.
+ *
+ * Why v5 beats v4 for rebase-stability:
+ *   - v4 enumerates files via `git diff origin/main..HEAD`. When a sibling
+ *     PR merges between sign-time and verify-time, `origin/main` moves
+ *     forward. Files the sibling touched now appear in the v4 diff that
+ *     weren't there at sign-time → v4 hash diverges even though OUR blobs
+ *     are unchanged.
+ *   - v5 enumerates files via `git diff <signedMergeBase>..HEAD`. The
+ *     `signedMergeBase` is computed ONCE at sign time and frozen in the
+ *     envelope. At verify time, the verifier recomputes
+ *     `git diff <signedMergeBase>..<probe-HEAD>` using the SAME frozen
+ *     base → same file set → same hash, regardless of how many sibling
+ *     PRs merged on `main` in the interim.
+ *   - Overlapping sibling merges (sibling changed a file OUR PR also touches)
+ *     → the head blob SHA of that file differs from what we signed → v5
+ *     hash flips → verifier correctly rejects (operator must re-review).
+ *
+ * Threat model preserved: any genuine post-sign content tampering flips the
+ * head blob SHA → v5 hash flips → verifier rejects.
+ *
+ * Pure function. Idempotent against double-enumeration via dedup-by-path.
+ */
+export declare function computeContentHashV5(entries: ChangedFileV5Entry[], signedMergeBase: string): string;
+/**
+ * Collect the file set for `computeContentHashV5` (AISDLC-362).
+ *
+ * This is the LOAD-BEARING CHANGE vs v4:
+ *   - v4: `git diff origin/main..HEAD` — the base moves as siblings merge.
+ *   - v5: `git merge-base <baseRef> <headRef>` → frozen SHA, then
+ *         `git diff <signedMergeBase>..HEAD` — the base is FROZEN.
+ *
+ * The frozen merge-base is returned alongside the entries so the signer can
+ * embed it in both the v5 hash and the predicate's `signedMergeBase` field.
+ *
+ * File enumeration applies the same exclusions as v3/v4:
+ *   - Attestation envelope files (`ATTESTATION_ENVELOPE_PATH_PATTERN`)
+ *   - Shared churn files (`CONTENTHASH_SHARED_CHURN_FILES`)
+ *
+ * Blob SHAs are resolved from `headRef` (= HEAD at sign time).
+ *
+ * @param repoRoot  Absolute path to the git worktree root.
+ * @param baseRef   Typically `'origin/main'`. Used ONLY for computing the
+ *                  merge-base — the diff itself is against the frozen SHA.
+ * @param headRef   Typically `'HEAD'`.
+ * @param options   Optional injection points for tests (stub `runGit`).
+ */
+export declare function collectChangedFileEntriesForV5(repoRoot: string, baseRef?: string, headRef?: string, options?: CollectChangedFileEntriesOptions): V5CollectResult;
 /** Inputs for building an attestation predicate. */
 export interface BuildPredicateInputs {
     commitSha: string;
-    diff: string | Buffer;
     policy: string | Buffer;
     reviewers: Array<{
         agentId: string;
@@ -178,10 +586,53 @@ export interface BuildPredicateInputs {
         findings: ReviewerEntry['findings'];
     }>;
     pluginVersion: string;
+    /**
+     * Pipeline-cli version from `pipeline-cli/package.json` (AISDLC-100.6).
+     * Optional — when omitted (e.g. legacy callers, environments where
+     * pipeline-cli isn't installed), the predicate's `pipelineVersion` field
+     * is also omitted. Forensic / audit purpose only — the verifier logs
+     * this but does not enforce.
+     */
+    pipelineVersion?: string;
+    /**
+     * Harness that produced the developer + reviewer verdicts (AISDLC-202.3).
+     * Optional — when omitted, the predicate carries no `harness` field
+     * (back-compat with pre-202.3 envelopes). When provided, the adapter
+     * populates both `name` (required, SHORT_ID) and optionally `version`
+     * (SEMVER). Example: `{ name: 'codex', version: '0.128.0' }`.
+     *
+     * The signing script (`sign-attestation.mjs`) passes this via
+     * `--harness-name` + `--harness-version` CLI flags.
+     */
+    harness?: {
+        name: string;
+        version?: string;
+    };
     iterationCount: number;
     harnessNote: string;
     /** Override `signedAt` for deterministic tests. */
     signedAt?: string;
+    /**
+     * Per-file-delta set for `contentHashV3` (AISDLC-101 / AISDLC-103).
+     * REQUIRED for v3 envelopes — captures the (base_blob_sha →
+     * head_blob_sha) transition per file. Pass `[]` for no-op PRs (the
+     * resulting `contentHashV3` is `sha256('')`, which is well-defined and
+     * still verifiable).
+     */
+    changedFileDeltas: ChangedFileDeltaEntry[];
+    /**
+     * v5 file entries from `collectChangedFileEntriesForV5` (AISDLC-362).
+     * Optional — when omitted, no `contentHashV5` or `signedMergeBase` fields
+     * are emitted in the predicate (= a legacy v3+v4 envelope). When provided
+     * alongside `v5MergeBase`, the predicate carries all three hashes (v3, v4,
+     * v5) for maximum backward + forward compatibility.
+     */
+    v5Entries?: ChangedFileV5Entry[];
+    /**
+     * The frozen merge-base SHA from `collectChangedFileEntriesForV5`.
+     * Required when `v5Entries` is provided. Must be a 40-char hex SHA-1.
+     */
+    v5MergeBase?: string;
 }
 /**
  * Compute a sha256 hex digest. Single source of truth for the hashing
@@ -190,10 +641,184 @@ export interface BuildPredicateInputs {
 export declare function sha256Hex(input: string | Buffer): string;
 /** Compute a sha1 hex digest (used for git commit SHAs in the subject). */
 export declare function sha1Hex(input: string | Buffer): string;
+/**
+ * Compute the rebase-tolerant `contentHash` (AISDLC-94) over a changed-file
+ * set. The canonical encoding is one line per entry, sorted ascending by
+ * path, with `<path>\t<blobSha>\n` per line. The whole string is sha256-ed.
+ *
+ * Why this beats `diffHash`:
+ *   - Rebasing PR-X onto a new `main` that already touched the same files
+ *     does NOT change the post-apply blob SHAs (assuming no conflict),
+ *     so `contentHash` stays stable across the rebase.
+ *   - A conflict resolution that picks different content WILL change the
+ *     blob SHA → `contentHash` changes → attestation correctly invalidated.
+ *   - Force-pushing a no-op edit (e.g. `git commit --amend --no-edit`) keeps
+ *     blob SHAs identical → `contentHash` stays stable.
+ *
+ * The deduplication step makes the function idempotent if a caller
+ * accidentally passes the same path twice (last-write-wins per path).
+ *
+ * Pure function. The caller (sign-attestation script) is responsible for
+ * gathering the file set (via `git diff --name-only` + `git ls-tree`).
+ */
+export declare function computeContentHash(entries: ChangedFileEntry[]): string;
+/**
+ * Optional injection points for `collectChangedFileEntries`. Defaults are
+ * production behaviour; tests pass synthetic `runGit` to avoid spawning git.
+ */
+export interface CollectChangedFileEntriesOptions {
+    /**
+     * Run `git <args>` in `cwd` and return stdout (utf-8). Defaults to
+     * `execFileSync` with the git-context env scrubbed (see `cleanGitEnv`).
+     * Tests pass a stub so they don't depend on a real worktree.
+     */
+    runGit?: (args: string[], cwd: string) => string;
+}
+/**
+ * Collect the changed-file set used to compute `contentHash` (AISDLC-94).
+ *
+ * Returns one `{ path, blobSha }` entry per file in
+ * `git diff --name-only <baseRef>...<headRef>` with the blob SHA from
+ * `git ls-tree -r <headRef> -- <path>`. Deleted files get an empty
+ * `blobSha` (the path still appears so the canonical encoding distinguishes
+ * "deleted" from "kept").
+ *
+ * `--no-renames` so a rename shows up as add+delete (= two entries) — that
+ * way a rebase that resolved a conflict by renaming differently produces a
+ * different hash. `-c core.quotepath=false` mirrors the verifier's git
+ * helper so unicode paths come back as raw UTF-8.
+ *
+ * Path entries containing `\t` or `\n` are rejected to keep the canonical
+ * encoding injective (mirrors the rejection in `computeContentHash`). Such
+ * paths are exceedingly rare in practice — git's default config disallows
+ * `\n` in tracked filenames on most platforms — but we defend in depth so
+ * malicious or pathological inputs can't smuggle entries past the binding.
+ *
+ * Extracted from the previously-duplicated helpers in
+ * `ai-sdlc-plugin/scripts/sign-attestation.mjs` so a single source of truth
+ * applies the same parsing + validation at every signing site.
+ */
+export declare function collectChangedFileEntries(baseRef: string, headRef: string, repoRoot: string, options?: CollectChangedFileEntriesOptions): ChangedFileEntry[];
+/**
+ * Compute the per-file-delta `contentHashV3` (AISDLC-101) over a set of
+ * `{path, baseBlobSha, headBlobSha}` triples. The canonical encoding is
+ * one line per entry, sorted ascending by path, with
+ * `<path>\t<fileDeltaHash>\n` per line, where
+ * `fileDeltaHash = sha256(baseBlobSha + ' -> ' + headBlobSha)`. The
+ * outer `contentHashV3` is the sha256 of the concatenated lines.
+ *
+ * Why per-file delta hashing — and what it adds vs. AISDLC-94's `contentHash`:
+ *   - `contentHash` (AISDLC-94) hashes the post-apply blob SHA per file.
+ *     If a sibling PR landed between OUR sign + OUR merge AND modified
+ *     the SAME file, the rebased file's HEAD blob SHA contains both the
+ *     sibling contribution AND ours → contentHash diverges (false reject).
+ *   - `contentHashV3` (AISDLC-101) hashes the (base, head) blob-pair
+ *     transition per file. Provides a stricter "we moved file F from blob
+ *     A to blob B" binding than just "we ended up at blob B". Any genuine
+ *     content change still flips the head blob SHA → fileDeltaHash flips
+ *     → contentHashV3 flips → reject (threat model preserved).
+ *
+ * This is the SECOND line of defense in the 3-layer rebase-tolerance
+ * plan (AISDLC-94 = Phase 1 verifier-side dual-hash, AISDLC-102 = Phase 1.5
+ * producer-side pre-sign rebase, AISDLC-101 = Phase 2 per-file delta).
+ * The verifier OR's all three legs during the triple-hash window.
+ *
+ * Path-delimiter rejection (\t / \n) mirrors `computeContentHash` so the
+ * canonical encoding stays injective regardless of caller input.
+ *
+ * Pure function. Idempotent against double-enumeration via dedup-by-path
+ * (last-write-wins per path), same as `computeContentHash`.
+ */
+export declare function computeContentHashV3(entries: ChangedFileDeltaEntry[]): string;
+/**
+ * Compute the BASE-INDEPENDENT per-file head-blob `contentHashV4`
+ * (AISDLC-193.1) over a set of `{path, headBlobSha}` pairs. The
+ * canonical encoding is `JSON.stringify(sorted-by-path-array-of-{path,
+ * headBlobSha}-objects)`, hashed with sha256.
+ *
+ * Why JSON-of-sorted-array (and not the v3 `<path>\t<fileDeltaHash>\n`
+ * canonical) for v4:
+ *   - JSON's quoting rules already cover delimiter injection
+ *     (a malicious path containing tab/newline can't smuggle through
+ *     because they round-trip as escape sequences). We still reject
+ *     such paths defensively so the canonical stays injective and
+ *     the on-the-wire representation is what readers expect.
+ *   - JSON is unambiguous about field ordering (stringify of a
+ *     `{path, headBlobSha}` literal always emits `path` first,
+ *     `headBlobSha` second — V8's object-key ordering is insertion
+ *     order, and we insert in this order in the .map() below).
+ *   - Easier to extend: future hash versions can add fields
+ *     (`mode`, `executable bit`, etc) to the entry objects without
+ *     breaking the canonical encoding scheme.
+ *
+ * Why this is BASE-INDEPENDENT (= the whole point):
+ *   - v3's per-file delta hashes the (base_blob, head_blob) pair.
+ *     When the merge queue rebases the PR onto current main (which
+ *     advanced past the merge-base the producer signed against), the
+ *     base blob SHA for any shared file changes → v3 invalidates.
+ *   - v4 hashes only `{path, headBlobSha}`. Whatever the rebase does
+ *     to the base ref or the merge-base, as long as the head blob SHA
+ *     (= the actual reviewed file content) is unchanged, v4 matches.
+ *   - The reviewer never approved "base_blob X → head_blob Y"; they
+ *     approved "the file contents at head_blob Y." v4 binds to that
+ *     directly.
+ *
+ * Threat model preserved:
+ *   - Genuine post-sign content tampering (someone amends the PR to
+ *     add unreviewed code) flips the head blob SHA → v4 hash flips →
+ *     verifier rejects. Same threat-model surface as v3.
+ *   - The signing key still has to be a trusted reviewer's; v4
+ *     doesn't change the signature/key flow, just what the predicate
+ *     binds to.
+ *
+ * Pure function. Idempotent against double-enumeration via dedup-by-path
+ * (last-write-wins per path), same as `computeContentHash` and
+ * `computeContentHashV3`.
+ */
+export declare function computeContentHashV4(entries: ChangedFileHeadEntry[]): string;
+/**
+ * Collect the per-file-delta set used to compute `contentHashV3` (AISDLC-101).
+ *
+ * Returns one `{ path, baseBlobSha, headBlobSha }` entry per file in
+ * `git diff --name-only <baseRef>...<headRef>`. The base blob SHA is read
+ * from the *merge-base* of `<baseRef>` and `<headRef>` (which the `...`
+ * 3-dot diff range already targets — `A...B` diffs against
+ * `merge-base(A,B)`); the head blob SHA from `<headRef>`. Files newly
+ * added in the PR have empty `baseBlobSha`; deleted files have empty
+ * `headBlobSha`.
+ *
+ * Mirrors `collectChangedFileEntries`'s flag set (`--no-renames`,
+ * `core.quotepath=false`) for consistency with the other binding's file
+ * enumeration.
+ *
+ * Extracted so a single source of truth handles the two ls-tree lookups
+ * (one per endpoint) at every signing site (`sign-attestation.mjs`).
+ */
+export declare function collectChangedFileDeltaEntries(baseRef: string, headRef: string, repoRoot: string, options?: CollectChangedFileEntriesOptions): ChangedFileDeltaEntry[];
+/**
+ * Project a v3 `ChangedFileDeltaEntry` set down to the v4
+ * `ChangedFileHeadEntry` shape (`{path, headBlobSha}`). Convenience
+ * for callers that already collected v3 deltas and want to dual-emit
+ * both hashes from the same file enumeration. Pure function.
+ *
+ * The envelope self-exclusion is enforced upstream by
+ * `collectChangedFileDeltaEntries`, so this projection is a simple
+ * field-pick — no path filtering needed here.
+ */
+export declare function projectDeltaEntriesToHeadEntries(deltas: ChangedFileDeltaEntry[]): ChangedFileHeadEntry[];
 /**
  * Build the predicate payload from raw inputs. Pure function — no I/O,
  * no signing. The caller (`/ai-sdlc execute` Step 10) reads files and git
  * output, then hands them here.
+ *
+ * AISDLC-103 (Verifier Phase 3): always emits a v3 envelope. The caller
+ * MUST provide `changedFileDeltas` (use `[]` for no-op PRs); the legacy
+ * `diff` + `changedFiles` inputs were dropped along with the legacy
+ * `diffHash` + `contentHash` fields.
+ *
+ * AISDLC-362 (contentHashV5): when `v5Entries` + `v5MergeBase` are provided,
+ * also emits `contentHashV5` and `signedMergeBase` in the predicate and bumps
+ * `schemaVersion` to `'v5'`. The verifier prefers v5 when present.
  */
 export declare function buildPredicate(inputs: BuildPredicateInputs): AttestationPredicate;
 /**
@@ -236,8 +861,9 @@ export interface VerifyOptions {
      */
     trustedReviewers: TrustedReviewer[];
     /**
-     * What the predicate's `subject.digest.sha1`, `diffHash`, `policyHash`,
-     * and `reviewers[].agentFileHash` MUST equal. Mismatch = invalid.
+     * What the predicate's `subject.digest.sha1`, `contentHashV3`,
+     * `policyHash`, and `reviewers[].agentFileHash` MUST equal. Mismatch =
+     * invalid.
      *
      * `expectedAgentFileHashes` is a map from agentId to its sha256 — we
      * tolerate the predicate listing fewer or more reviewers than the map,
@@ -245,7 +871,33 @@ export interface VerifyOptions {
      */
     expected: {
         commitSha: string;
-        diffHash: string;
+        contentHashV3: string;
+        /**
+         * AISDLC-193.1 base-independent per-file head-blob binding.
+         * Optional — callers that want v4-prefer behavior pass it; callers
+         * that only have v3 (legacy) leave it undefined.
+         *
+         * When BOTH this AND the envelope's `contentHashV4` are present,
+         * the verifier prefers v4 (base-independent → survives queue
+         * rebases). When v4 matches, v3 is NOT consulted (this is the
+         * whole point — v3 will mismatch on a queue rebase even though
+         * the reviewed content is unchanged).
+         *
+         * When the envelope is legacy v3-only (no `contentHashV4`), the
+         * verifier falls back to the v3 check unconditionally regardless
+         * of whether `expected.contentHashV4` is supplied.
+         */
+        contentHashV4?: string;
+        /**
+         * AISDLC-362 frozen-merge-base delta hash. Optional — callers that
+         * want v5-prefer behavior pass it; callers without v5 leave it
+         * undefined (fallback to v4 then v3).
+         *
+         * When BOTH this AND the envelope's `contentHashV5` are present,
+         * the verifier prefers v5 (highest rebase-stability). When v5
+         * matches, v4 and v3 are NOT consulted.
+         */
+        contentHashV5?: string;
         policyHash: string;
         expectedAgentFileHashes: Record<string, string>;
     };