npm - @ai-sdlc/orchestrator - Versions diffs - 0.9.0 → 0.10.0 - Mend

@ai-sdlc/orchestrator 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/dist/__test-helpers/git-env.d.ts +40 -0
package/dist/__test-helpers/git-env.js +73 -0
package/dist/admission-composite.d.ts +22 -0
package/dist/admission-composite.js +85 -2
package/dist/admission-enrichment.js +12 -2
package/dist/admission-hc.d.ts +20 -1
package/dist/admission-hc.js +12 -1
package/dist/admission-score.d.ts +14 -0
package/dist/admission-score.js +7 -1
package/dist/cli/commands/git-remote.d.ts +25 -0
package/dist/cli/commands/git-remote.js +80 -1
package/dist/cli/commands/init-features.d.ts +208 -0
package/dist/cli/commands/init-features.js +473 -0
package/dist/cli/commands/init-templates.d.ts +104 -0
package/dist/cli/commands/init-templates.js +399 -0
package/dist/cli/commands/init.d.ts +22 -0
package/dist/cli/commands/init.js +158 -1
package/dist/design-authority.d.ts +13 -0
package/dist/design-authority.js +13 -0
package/dist/execute.js +8 -5
package/dist/models/classifier.d.ts +3 -1
package/dist/models/classifier.js +61 -5
package/dist/pillar-breakdown.d.ts +23 -1
package/dist/pillar-breakdown.js +9 -0
package/dist/runtime/attestations.d.ts +502 -10
package/dist/runtime/attestations.js +759 -24
package/dist/runtime/parallelism-flag.d.ts +21 -3
package/dist/runtime/parallelism-flag.js +27 -6
package/dist/runtime/port-allocator.d.ts +11 -0
package/dist/runtime/port-allocator.js +30 -0
package/package.json +3 -2

package/dist/runtime/attestations.d.ts CHANGED Viewed

@@ -34,12 +34,22 @@
 /**
  * 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`).
  *
  * 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"];
 export type SchemaVersion = (typeof ACCEPTED_SCHEMA_VERSIONS)[number];
 /**
  * The DSSE PAE payload type for our predicate. DSSE spec mandates a payload
@@ -83,14 +93,103 @@ 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;
     /** 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;
     /**
@@ -148,13 +247,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 +269,181 @@ 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 `contentHashV4` (AISDLC-258).
+ *
+ * Files in this list are EXCLUDED from the v4 file collector in BOTH the
+ * signer (`collectChangedFileDeltaEntries`) and the verifier
+ * (`computeHeadContentHashV4` in `scripts/verify-attestation.mjs`). 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
+ * `contentHashV4` to mismatch, 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 CONTENTHASHV4_IGNORE_FILES: readonly string[];
+/**
+ * Predicate to determine whether a file path should be excluded from the
+ * `contentHashV4` computation because it is a "shared churn" file (see
+ * `CONTENTHASHV4_IGNORE_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;
+}
 /** Inputs for building an attestation predicate. */
 export interface BuildPredicateInputs {
     commitSha: string;
-    diff: string | Buffer;
     policy: string | Buffer;
     reviewers: Array<{
         agentId: string;
@@ -178,10 +453,40 @@ 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[];
 }
 /**
  * Compute a sha256 hex digest. Single source of truth for the hashing
@@ -190,10 +495,180 @@ 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.
  */
 export declare function buildPredicate(inputs: BuildPredicateInputs): AttestationPredicate;
 /**
@@ -236,8 +711,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 +721,23 @@ 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;
         policyHash: string;
         expectedAgentFileHashes: Record<string, string>;
     };