phasegate 0.163.0 → 0.165.0

package/scripts/harness/attestation/application/usecases/produce-attestation-usecase.ts

@@ -0,0 +1,155 @@
+// @unit attestation
+// @layer application
+
+import { AttestationRecord, type GateResult, type SourceEntry } from "../../domain/entities/attestation-record.js";
+import type { ContentHasherPort } from "../../domain/ports/content-hasher-port.js";
+import type { GranularityDerivationService } from "../../domain/services/granularity-derivation-service.js";
+import { SignatureBlock } from "../../domain/value-objects/signature-block.js";
+import { ValidatorOutcome } from "../../domain/value-objects/validator-outcome.js";
+import type { AttestationDocument } from "../dto/attestation-document.js";
+import type { ProduceAttestationInput } from "../dto/produce-attestation-input.js";
+import type { AttestationRecordMapper } from "../mappers/attestation-record-mapper.js";
+import type { AttestationRepositoryPort } from "../ports/attestation-repository-port.js";
+import type { GateResultSourcePort } from "../ports/gate-result-source-port.js";
+import type { SourceDigesterPort } from "../ports/source-digester-port.js";
+
+const SCHEMA_VERSION = "phasegate-attestation/v1";
+const PREDICATE_TYPE = "https://phasegate.dev/attestation/gate-run/v1";
+const DEFAULT_INPUT_SOURCES: readonly string[] = Object.freeze([
+  "phasegate.config.json",
+  ".harness/requirement-test-matrix.json",
+]);
+
+export interface ProduceAttestationDeps {
+  readonly gateResultSource: GateResultSourcePort;
+  readonly sourceDigester: SourceDigesterPort;
+  readonly hasher: ContentHasherPort;
+  readonly repository: AttestationRepositoryPort;
+  readonly granularityService: GranularityDerivationService;
+  readonly mapper: AttestationRecordMapper;
+  /** git commit SHA 取得（決定論的 source 化のため）。取得不能なら null。 */
+  readonly gitCommitProvider: () => Promise<string | null>;
+  /** metadata.producer の pkg version。 */
+  readonly pkgVersion: string;
+  /** metadata.producedAt 用クロック。 */
+  readonly clock?: () => Date;
+  /** 入力 source パス群（既定は config + matrix）。 */
+  readonly inputSourcePaths?: readonly string[];
+}
+
+export interface ProduceAttestationResult {
+  readonly document: AttestationDocument | null;
+  readonly exitCode: 0 | 1 | 2;
+}
+
+/**
+ * H16-01: gate 結果取得 → source digest 取得 → granularity 導出 → 集約構築 → 封印 → 出力。
+ */
+export class ProduceAttestationUseCase {
+  constructor(private readonly deps: ProduceAttestationDeps) {}
+
+  async execute(input: ProduceAttestationInput): Promise<ProduceAttestationResult> {
+    // 1. mode == "signed" は not-yet-implemented（record 出力なし・exit 2）
+    if (input.mode === "signed") {
+      return { document: null, exitCode: 2 };
+    }
+
+    // 2. gate 結果取得（validatorSet と gateResult 組み立て）
+    const gate = await this.deps.gateResultSource.fetchGateResult();
+    const validatorSet = gate.validatorResults.map((r) =>
+      ValidatorOutcome.create({ validatorId: r.validatorId, passed: r.passed, skipped: r.skipped }),
+    );
+    const gateResult: GateResult = gate.allPassed ? "pass" : "fail";
+
+    // 3. require-pass && gate fail → record を一切生成/出力せず exit 1
+    if (input.requirePass && gateResult !== "pass") {
+      return { document: null, exitCode: 1 };
+    }
+
+    // 4. inputs.sources 構築（config / matrix の sha256 + git commit SHA）と inputDigest 算出
+    const sources = await this.buildSources();
+    const preInputRecord = this.assembleRecord({
+      validatorSet,
+      gateResult,
+      sources,
+      inputDigest: sources[0].digest, // 仮置き。直後に computeInputDigest で確定
+      producedAt: "1970-01-01T00:00:00Z",
+      producer: `phasegate-attestation/${this.deps.pkgVersion}`,
+      gitCommit: null,
+    });
+    const inputDigest = preInputRecord.computeInputDigest(this.deps.hasher);
+
+    // 5. granularity 導出（domain service）
+    // 6. metadata 構築
+    const now = (this.deps.clock ?? (() => new Date()))().toISOString();
+    const gitCommit = await this.deps.gitCommitProvider();
+
+    // 7. 集約構築 → seal で attestationDigest 確定（INV-4）
+    const record = this.assembleRecord({
+      validatorSet,
+      gateResult,
+      sources,
+      inputDigest,
+      producedAt: now,
+      producer: `phasegate-attestation/${this.deps.pkgVersion}`,
+      gitCommit,
+    });
+    const sealed = record.seal(this.deps.hasher);
+
+    // 8. document へ射影して永続化
+    const document = this.deps.mapper.toDocument(sealed);
+    await this.deps.repository.write(input.out, document);
+
+    // 9. 成功
+    return { document, exitCode: 0 };
+  }
+
+  private assembleRecord(args: {
+    validatorSet: ValidatorOutcome[];
+    gateResult: GateResult;
+    sources: SourceEntry[];
+    inputDigest: SourceEntry["digest"];
+    producedAt: string;
+    producer: string;
+    gitCommit: string | null;
+  }): AttestationRecord {
+    const granularity = this.deps.granularityService.derive(args.validatorSet);
+    return AttestationRecord.create({
+      schemaVersion: SCHEMA_VERSION,
+      predicateType: PREDICATE_TYPE,
+      subject: {
+        command: "phasegate:ci-check",
+        gateResult: args.gateResult,
+        validatorSet: args.validatorSet,
+      },
+      inputs: {
+        digestAlgorithm: "sha256",
+        sources: args.sources,
+        inputDigest: args.inputDigest,
+      },
+      granularity: { traceability: granularity },
+      metadata: {
+        producedAt: args.producedAt,
+        producer: args.producer,
+        gitCommit: args.gitCommit,
+      },
+      // 仮の unsigned-poc block（seal 前）。seal が正しい digest で置換する。
+      signature: SignatureBlock.unsignedPoc(args.inputDigest),
+    });
+  }
+
+  private async buildSources(): Promise<SourceEntry[]> {
+    const paths = this.deps.inputSourcePaths ?? DEFAULT_INPUT_SOURCES;
+    const sources: SourceEntry[] = [];
+    for (const path of paths) {
+      const digest = await this.deps.sourceDigester.digestFile(path);
+      sources.push({ path, digest });
+    }
+    // git commit SHA を source エントリとして取り込む（inputDigest に含める）
+    const gitCommit = await this.deps.gitCommitProvider();
+    if (gitCommit !== null) {
+      sources.push({ path: "git:HEAD", digest: this.deps.hasher.sha256(gitCommit) });
+    }
+    return sources;
+  }
+}

package/scripts/harness/attestation/application/usecases/verify-attestation-usecase.ts

@@ -0,0 +1,137 @@
+// @unit attestation
+// @layer application
+
+import type { AttestationRecord } from "../../domain/entities/attestation-record.js";
+import type { ContentHasherPort } from "../../domain/ports/content-hasher-port.js";
+import type { GranularityDerivationService } from "../../domain/services/granularity-derivation-service.js";
+import type { VerifyAttestationInput } from "../dto/verify-attestation-input.js";
+import type { VerifyAttestationChecks, VerifyAttestationOutput } from "../dto/verify-attestation-output.js";
+import type { AttestationRecordMapper } from "../mappers/attestation-record-mapper.js";
+import type { AttestationRepositoryPort } from "../ports/attestation-repository-port.js";
+import type { SourceDigesterPort } from "../ports/source-digester-port.js";
+
+export interface VerifyAttestationDeps {
+  readonly repository: AttestationRepositoryPort;
+  readonly sourceDigester: SourceDigesterPort;
+  readonly hasher: ContentHasherPort;
+  readonly granularityService: GranularityDerivationService;
+  readonly mapper: AttestationRecordMapper;
+}
+
+export interface VerifyAttestationResult {
+  readonly output: VerifyAttestationOutput;
+  readonly exitCode: 0 | 1 | 2;
+}
+
+const SUPPORTED_MODE = "unsigned-poc";
+
+/**
+ * H16-02: 既存 record を読み込み、機械的 5 チェックを再計算で行う。
+ */
+export class VerifyAttestationUseCase {
+  constructor(private readonly deps: VerifyAttestationDeps) {}
+
+  async execute(input: VerifyAttestationInput): Promise<VerifyAttestationResult> {
+    // 1. read（不在/parse 失敗 → exitCode 2, schema fail）
+    let raw: unknown;
+    try {
+      raw = await this.deps.repository.read(input.filePath);
+    } catch (e) {
+      return this.fail2({ schema: false }, [`cannot read attestation: ${errMsg(e)}`]);
+    }
+
+    // 3(先出し). mode サポート判定は shape に依存しないため、生の signature.mode を先に確認する。
+    //   非対応 mode（signed）は exitCode 2（mode check fail）。
+    const rawMode = extractMode(raw);
+    if (rawMode !== null && rawMode !== SUPPORTED_MODE) {
+      return this.fail2({ schema: true, mode: false }, [`unsupported signature mode: "${rawMode}"`]);
+    }
+
+    // 2. shape/型検証（不正 → exitCode 2, schema fail）
+    let record: AttestationRecord;
+    try {
+      record = this.deps.mapper.fromDocument(raw);
+    } catch (e) {
+      return this.fail2({ schema: false }, [`malformed attestation: ${errMsg(e)}`]);
+    }
+
+    // ここまで schema OK, mode OK
+    const mismatches: string[] = [];
+
+    // 4. attestationDigest 再計算 == 格納値
+    const recomputedAttestation = record.computeAttestationDigest(this.deps.hasher);
+    const attestationDigestOk = recomputedAttestation.equals(record.signature.attestationDigest);
+    if (!attestationDigestOk) {
+      mismatches.push(
+        `attestationDigest mismatch: stored ${record.signature.attestationDigest.value}, recomputed ${recomputedAttestation.value}`,
+      );
+    }
+
+    // 5. inputs.sources[].digest を現在ファイルから再計算 == 格納値
+    let inputHashesOk = true;
+    for (const source of record.inputs.sources) {
+      if (source.path === "git:HEAD") {
+        // git commit source は現在の HEAD ではなく生成時点の値を証明する。
+        // ファイル再読込の対象外（再照合は inputDigest 経由の整合で担保）。
+        continue;
+      }
+      let current: string;
+      try {
+        current = (await this.deps.sourceDigester.digestFile(source.path)).value;
+      } catch (e) {
+        inputHashesOk = false;
+        mismatches.push(`cannot re-hash source "${source.path}": ${errMsg(e)}`);
+        continue;
+      }
+      if (current !== source.digest.value) {
+        inputHashesOk = false;
+        mismatches.push(`input hash mismatch for "${source.path}": stored ${source.digest.value}, current ${current}`);
+      }
+    }
+
+    // 6. granularity を validatorSet から再導出 == 格納値（anti-laundering）
+    const rederived = this.deps.granularityService.derive(record.subject.validatorSet);
+    const granularityOk = rederived.equals(record.granularity.traceability);
+    if (!granularityOk) {
+      mismatches.push("granularity mismatch: stored granularity does not match re-derived value");
+    }
+
+    const checks: VerifyAttestationChecks = {
+      schema: true,
+      mode: true,
+      attestationDigest: attestationDigestOk,
+      inputHashes: inputHashesOk,
+      granularity: granularityOk,
+    };
+    const ok = attestationDigestOk && inputHashesOk && granularityOk;
+
+    return {
+      output: { ok, checks, mismatches },
+      exitCode: ok ? 0 : 1,
+    };
+  }
+
+  private fail2(partialChecks: Partial<VerifyAttestationChecks>, mismatches: string[]): VerifyAttestationResult {
+    const checks: VerifyAttestationChecks = {
+      schema: false,
+      mode: false,
+      attestationDigest: false,
+      inputHashes: false,
+      granularity: false,
+      ...partialChecks,
+    };
+    return { output: { ok: false, checks, mismatches }, exitCode: 2 };
+  }
+}
+
+function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+function extractMode(raw: unknown): string | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const signature = (raw as Record<string, unknown>).signature;
+  if (typeof signature !== "object" || signature === null) return null;
+  const mode = (signature as Record<string, unknown>).mode;
+  return typeof mode === "string" ? mode : null;
+}

package/scripts/harness/attestation/composition-root.ts

@@ -0,0 +1,93 @@
+/**
+ * @layer infrastructure
+ * @unit attestation
+ *
+ * Composition Root — attestation Unit の依存性組み立て。
+ * createAttestationModule() は adapters + usecases + handlers を組み立て、
+ * 公開する 2 ハンドラ（attest / verify-attestation）を返す。
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { AttestationRecordMapper } from "./application/mappers/attestation-record-mapper.js";
+import { ProduceAttestationUseCase } from "./application/usecases/produce-attestation-usecase.js";
+import { VerifyAttestationUseCase } from "./application/usecases/verify-attestation-usecase.js";
+import { GranularityDerivationService } from "./domain/services/granularity-derivation-service.js";
+import { CiCheckGateResultAdapter } from "./infrastructure/adapters/ci-check-gate-result-adapter.js";
+import { FileSystemAttestationRepositoryAdapter } from "./infrastructure/adapters/file-system-attestation-repository-adapter.js";
+import { FileSystemSourceDigesterAdapter } from "./infrastructure/adapters/file-system-source-digester-adapter.js";
+import { NodeCryptoContentHasherAdapter } from "./infrastructure/adapters/node-crypto-content-hasher-adapter.js";
+import { AttestHandler } from "./presentation/handlers/attest-handler.js";
+import { VerifyAttestationHandler } from "./presentation/handlers/verify-attestation-handler.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface AttestationModule {
+  readonly attestHandler: AttestHandler;
+  readonly verifyAttestationHandler: VerifyAttestationHandler;
+}
+
+export interface AttestationModuleOptions {
+  /** metadata.producer の pkg version。既定 "0.0.0"。 */
+  readonly pkgVersion?: string;
+  /** git commit SHA 取得器のオーバーライド（テスト用）。既定は `git rev-parse HEAD`。 */
+  readonly gitCommitProvider?: () => Promise<string | null>;
+  /** ci-check subprocess の main.ts パスオーバーライド（テスト用）。 */
+  readonly mainTsPath?: string;
+  /** metadata.producedAt 用クロックのオーバーライド（テスト用）。 */
+  readonly clock?: () => Date;
+}
+
+/**
+ * attestation Unit のモジュールを組み立てる。
+ * @param rootDir プロジェクトルート（source digest / repository の baseDir）。
+ */
+export function createAttestationModule(rootDir: string, options?: AttestationModuleOptions): AttestationModule {
+  // Infrastructure adapters
+  const hasher = new NodeCryptoContentHasherAdapter();
+  const sourceDigester = new FileSystemSourceDigesterAdapter(rootDir);
+  const gateResultSource = new CiCheckGateResultAdapter({ mainTsPath: options?.mainTsPath });
+  const repository = new FileSystemAttestationRepositoryAdapter(rootDir);
+
+  // Domain services / mappers
+  const granularityService = new GranularityDerivationService();
+  const mapper = new AttestationRecordMapper();
+
+  const gitCommitProvider = options?.gitCommitProvider ?? (() => defaultGitCommitProvider(rootDir));
+
+  // Use cases
+  const produceUseCase = new ProduceAttestationUseCase({
+    gateResultSource,
+    sourceDigester,
+    hasher,
+    repository,
+    granularityService,
+    mapper,
+    gitCommitProvider,
+    pkgVersion: options?.pkgVersion ?? "0.0.0",
+    clock: options?.clock,
+  });
+  const verifyUseCase = new VerifyAttestationUseCase({
+    repository,
+    sourceDigester,
+    hasher,
+    granularityService,
+    mapper,
+  });
+
+  // Handlers
+  const attestHandler = new AttestHandler(produceUseCase);
+  const verifyAttestationHandler = new VerifyAttestationHandler(verifyUseCase);
+
+  return { attestHandler, verifyAttestationHandler };
+}
+
+async function defaultGitCommitProvider(cwd: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd });
+    const sha = stdout.trim();
+    return sha.length > 0 ? sha : null;
+  } catch {
+    return null;
+  }
+}

package/scripts/harness/attestation/domain/entities/attestation-record.ts

@@ -0,0 +1,240 @@
+// @unit attestation
+// @layer domain
+
+import type { ContentHasherPort } from "../ports/content-hasher-port.js";
+import { GranularityDerivationService } from "../services/granularity-derivation-service.js";
+import type { Digest } from "../value-objects/digest.js";
+import type { GranularityClaim } from "../value-objects/granularity-claim.js";
+import { SignatureBlock } from "../value-objects/signature-block.js";
+import type { ValidatorOutcome } from "../value-objects/validator-outcome.js";
+
+export type GateResult = "pass" | "fail";
+
+export interface SourceEntry {
+  readonly path: string;
+  readonly digest: Digest;
+}
+
+export interface SubjectSection {
+  readonly command: string;
+  readonly gateResult: GateResult;
+  readonly validatorSet: readonly ValidatorOutcome[];
+}
+
+export interface InputsSection {
+  readonly digestAlgorithm: "sha256";
+  readonly sources: readonly SourceEntry[];
+  readonly inputDigest: Digest;
+}
+
+export interface MetadataSection {
+  readonly producedAt: string;
+  readonly producer: string;
+  readonly gitCommit: string | null;
+}
+
+export interface AttestationRecordProps {
+  readonly schemaVersion: string;
+  readonly predicateType: string;
+  readonly subject: SubjectSection;
+  readonly inputs: InputsSection;
+  readonly granularity: { readonly traceability: GranularityClaim };
+  readonly metadata: MetadataSection;
+  readonly signature: SignatureBlock;
+}
+
+/**
+ * INV-1/2/3/6 のいずれかに違反した場合の集約不変条件違反例外。
+ * errorCode: L1-051（logical_design §2.4）
+ */
+export class AttestationInvariantError extends Error {
+  readonly errorCode = "L1-051";
+
+  constructor(message: string) {
+    super(`${message} [L1-051]`);
+    this.name = "AttestationInvariantError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+const derivationService = new GranularityDerivationService();
+
+/**
+ * canonical JSON 直列化（§1.4.1）: キー昇順ソート（再帰）・空白なし・配列順序保持。
+ * この規則が record format の中核契約であり、生成と検証で完全一致する必要がある。
+ */
+export function canonicalStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => canonicalStringify(v)).join(",")}]`;
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort();
+  const entries = keys.map((k) => `${JSON.stringify(k)}:${canonicalStringify(record[k])}`);
+  return `{${entries.join(",")}}`;
+}
+
+/**
+ * attestation ドキュメント1件を整合性境界として扱う単一集約。
+ */
+export class AttestationRecord {
+  readonly schemaVersion: string;
+  readonly predicateType: string;
+  readonly subject: SubjectSection;
+  readonly inputs: InputsSection;
+  readonly granularity: { readonly traceability: GranularityClaim };
+  readonly metadata: MetadataSection;
+  readonly signature: SignatureBlock;
+
+  private constructor(props: AttestationRecordProps) {
+    this.schemaVersion = props.schemaVersion;
+    this.predicateType = props.predicateType;
+    this.subject = props.subject;
+    this.inputs = props.inputs;
+    this.granularity = props.granularity;
+    this.metadata = props.metadata;
+    this.signature = props.signature;
+    Object.freeze(this);
+  }
+
+  static create(props: AttestationRecordProps): AttestationRecord {
+    // INV-1: gateResult == "pass" iff validatorSet.every(passed || skipped)
+    const allGreen = props.subject.validatorSet.every((o) => o.isGreen());
+    const expectedGateResult: GateResult = allGreen ? "pass" : "fail";
+    if (props.subject.gateResult !== expectedGateResult) {
+      throw new AttestationInvariantError(
+        `INV-1 violated: gateResult "${props.subject.gateResult}" does not match validatorSet allPassed rule (expected "${expectedGateResult}")`,
+      );
+    }
+
+    // INV-3: granularity == GranularityDerivationService.derive(validatorSet)
+    const derived = derivationService.derive(props.subject.validatorSet);
+    if (!props.granularity.traceability.equals(derived)) {
+      throw new AttestationInvariantError(
+        "INV-3 violated: granularity.traceability does not match mechanically derived granularity (anti-laundering)",
+      );
+    }
+
+    // INV-6: unsigned-poc のとき algorithm/keyId/value は null（SignatureBlock.create で保証済み）
+    // INV-2: attestationDigest present iff mode set —
+    //   SignatureBlock は常に mode + attestationDigest を持つため構造的に成立
+    if (props.signature.mode === "unsigned-poc") {
+      if (props.signature.algorithm !== null || props.signature.keyId !== null || props.signature.value !== null) {
+        throw new AttestationInvariantError(
+          "INV-6 violated: unsigned-poc signature must have null algorithm/keyId/value",
+        );
+      }
+    }
+
+    return new AttestationRecord(props);
+  }
+
+  /**
+   * 既存 document を「格納されたまま」に再構築する（verify 用）。
+   * INV-1/INV-3 を強制しない — verify はこれらを機械的チェックとして検出し
+   * check 失敗（exitCode 1）として報告する責務を持つため、ここで例外を投げてはならない。
+   * SignatureBlock 側の INV-6 は VO 構築時に既に保証されている。
+   */
+  static reconstruct(props: AttestationRecordProps): AttestationRecord {
+    return new AttestationRecord(props);
+  }
+
+  gateResult(): GateResult {
+    return this.subject.gateResult;
+  }
+
+  /**
+   * §1.4.2: sources を path 昇順で安定ソートした `[{ path, digest }]` の canonical JSON の sha256。
+   */
+  computeInputDigest(hasher: ContentHasherPort): Digest {
+    const sorted = [...this.inputs.sources]
+      .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+      .map((s) => ({ path: s.path, digest: s.digest.value }));
+    return hasher.sha256(canonicalStringify(sorted));
+  }
+
+  /**
+   * §1.4.1 step1-3: signature ブロック全体と volatile metadata（producedAt/gitCommit）を
+   * 除去した plain object を返す（producer は決定論的なので残す）。
+   */
+  toCanonicalPayload(): Record<string, unknown> {
+    return {
+      schemaVersion: this.schemaVersion,
+      predicateType: this.predicateType,
+      subject: {
+        command: this.subject.command,
+        gateResult: this.subject.gateResult,
+        validatorSet: this.subject.validatorSet.map((o) => ({
+          validatorId: o.validatorId,
+          passed: o.passed,
+          skipped: o.skipped,
+        })),
+      },
+      inputs: {
+        digestAlgorithm: this.inputs.digestAlgorithm,
+        sources: this.inputs.sources.map((s) => ({ path: s.path, digest: s.digest.value })),
+        inputDigest: this.inputs.inputDigest.value,
+      },
+      granularity: {
+        traceability: {
+          validator: this.granularity.traceability.validator,
+          level: this.granularity.traceability.level,
+          claim: this.granularity.traceability.claim,
+          knownLimitations: [...this.granularity.traceability.knownLimitations],
+        },
+      },
+      metadata: {
+        producer: this.metadata.producer,
+      },
+    };
+  }
+
+  /**
+   * §1.4.1 step4: canonical payload の canonical JSON を sha256 にかけて attestationDigest を得る。
+   */
+  computeAttestationDigest(hasher: ContentHasherPort): Digest {
+    return hasher.sha256(canonicalStringify(this.toCanonicalPayload()));
+  }
+
+  /**
+   * computeAttestationDigest() を signature.attestationDigest に反映した封印済み record を返す（INV-4）。
+   */
+  seal(hasher: ContentHasherPort): AttestationRecord {
+    const digest = this.computeAttestationDigest(hasher);
+    return AttestationRecord.create({
+      schemaVersion: this.schemaVersion,
+      predicateType: this.predicateType,
+      subject: this.subject,
+      inputs: this.inputs,
+      granularity: this.granularity,
+      metadata: this.metadata,
+      signature: SignatureBlock.unsignedPoc(digest),
+    });
+  }
+
+  equals(other: AttestationRecord): boolean {
+    if (this.schemaVersion !== other.schemaVersion) return false;
+    if (this.predicateType !== other.predicateType) return false;
+    if (this.subject.command !== other.subject.command) return false;
+    if (this.subject.gateResult !== other.subject.gateResult) return false;
+    if (this.subject.validatorSet.length !== other.subject.validatorSet.length) return false;
+    if (!this.subject.validatorSet.every((o, i) => o.equals(other.subject.validatorSet[i]))) {
+      return false;
+    }
+    if (this.inputs.digestAlgorithm !== other.inputs.digestAlgorithm) return false;
+    if (!this.inputs.inputDigest.equals(other.inputs.inputDigest)) return false;
+    if (this.inputs.sources.length !== other.inputs.sources.length) return false;
+    if (
+      !this.inputs.sources.every(
+        (s, i) => s.path === other.inputs.sources[i].path && s.digest.equals(other.inputs.sources[i].digest),
+      )
+    ) {
+      return false;
+    }
+    if (!this.granularity.traceability.equals(other.granularity.traceability)) return false;
+    if (!this.signature.equals(other.signature)) return false;
+    return true;
+  }
+}

package/scripts/harness/attestation/domain/ports/content-hasher-port.ts

@@ -0,0 +1,13 @@
+// @unit attestation
+// @layer domain
+
+import type { Digest } from "../value-objects/digest.js";
+
+/**
+ * canonical payload / source content の sha256 を計算するポート（外部→ドメイン）。
+ * 実体（node:crypto）は Infrastructure に隔離する。
+ * digest 計算は集約の不変条件 INV-4/INV-5 の一部であるため domain 層に配置する。
+ */
+export interface ContentHasherPort {
+  sha256(content: string): Digest;
+}

package/scripts/harness/attestation/domain/services/granularity-derivation-service.ts

@@ -0,0 +1,51 @@
+// @unit attestation
+// @layer domain
+
+import {
+  GranularityClaim,
+  KNOWN_LIMITATIONS_REGISTRY,
+  TRACEABILITY_VALIDATOR_ID,
+} from "../value-objects/granularity-claim.js";
+import type { ValidatorOutcome } from "../value-objects/validator-outcome.js";
+
+const TRACEABILITY_NOT_RUN_CLAIM =
+  "Traceability (L3-004) was not part of this gate run; no file-level traceability guarantee is asserted.";
+
+/**
+ * validator set + 静的 known-limitations registry から GranularityClaim を機械導出する純粋サービス。
+ * 生成（H16-01）と検証（H16-02 anti-laundering 再導出）で完全に同一の結果を返すため、
+ * 決定論的かつ全域（total）でなければならない。
+ *
+ * anti-laundering: 導出は静的 registry のみを真実の源とする。格納された granularity を
+ * 過大主張へ改竄しても、再導出は常に registry の honest な file-level 主張を返すため mismatch が検出される。
+ * また validator set から L3-004 を除去する改竄も、導出結果が「not run」へ変化するため検出される。
+ */
+export class GranularityDerivationService {
+  /**
+   * validator set から traceability の GranularityClaim を導出する。
+   * 1. registry から traceability 検査に対応する validatorId（L3-004）を引く
+   * 2. L3-004 が validator set に含まれるか確認する
+   * 3. 含まれる場合は registry の file-level 定義（known-limitation 付き）を、
+   *    含まれない場合は「not run」主張を構築する
+   */
+  derive(validatorSet: readonly ValidatorOutcome[]): GranularityClaim {
+    const definition = KNOWN_LIMITATIONS_REGISTRY[TRACEABILITY_VALIDATOR_ID];
+    const present = validatorSet.some((o) => o.validatorId === TRACEABILITY_VALIDATOR_ID);
+
+    if (!present) {
+      return GranularityClaim.create({
+        validator: definition.validator,
+        level: definition.level,
+        claim: TRACEABILITY_NOT_RUN_CLAIM,
+        knownLimitations: [],
+      });
+    }
+
+    return GranularityClaim.create({
+      validator: definition.validator,
+      level: definition.level,
+      claim: definition.claim,
+      knownLimitations: definition.knownLimitations,
+    });
+  }
+}