phasegate 0.229.0 → 0.264.0

package/docs/guide/configuration.md

@@ -76,6 +76,36 @@ The plan identifies target fields, managed artifacts, commands, validation, risk
     "format": "json",
     "outputDir": "reports"
   },
+  "world": {
+    "enabled": false,
+    "corpus": {
+      "productRoots": ["docs/product"],
+      "inceptionRoots": ["docs/inception"],
+      "adrRoots": ["docs/ADR"],
+      "sourceRoots": ["scripts/harness"],
+      "include": ["**/*"],
+      "exclude": []
+    },
+    "inputs": {
+      "matrixPath": ".harness/requirement-test-matrix.json",
+      "attestationPath": ".harness/attestation.json",
+      "integrityManifestPath": "phasegate.integrity.json"
+    },
+    "declarations": {
+      "constraintsPath": "phasegate.world-constraints.json",
+      "baselinePath": "phasegate.world-baseline.json",
+      "waiversPath": "phasegate.world-waivers.json",
+      "debtsPath": "phasegate.world-debts.json"
+    },
+    "output": {
+      "obligationReportPath": ".harness/world-obligations.json"
+    },
+    "sessionStart": {
+      "enabled": true,
+      "maxItems": 5,
+      "maxChars": 2000
+    }
+  },
   "preCommit": {
     "implementationExtensions": [".ts"]
   },
@@ -115,6 +145,8 @@ The `strict` preset also enables:
 - `bundleSizeLimit` -- 500 KB default cap
 - `deadCodeGC` -- automatic dead-code garbage collection
 
+All three presets resolve the same World Model defaults with `world.enabled: false`. This switch controls future automatic L2/L3 and hook integration; it does not disable explicit `world:inspect`, `world:pin`, or `world:derive` commands. Enabling automatic World gates remains an explicit rollout decision. <!-- @work-item-id WI-300 -->
+
 ---
 
 ### Field Reference
@@ -216,6 +248,30 @@ Example for Python and TypeScript:
 
 The metadata validators read `@unit` and `@layer` with language-agnostic regular expressions, so Python `# @unit api` and Go `// @unit api` style comments are both valid as long as the file extension is included here.
 
+#### `world`
+
+<!-- @work-item-id WI-300 -->
+
+`world` configures the World Model read corpus and reviewed control inputs. It is available in both v2 and v3 config schemas. Nested fields may be omitted and are resolved from the selected preset.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enabled` | `false` | Enables future automatic validator/hook integration; explicit `world:*` commands remain available |
+| `corpus.productRoots` | `["docs/product"]` | Canonical product corpus roots |
+| `corpus.inceptionRoots` | `["docs/inception"]` | Proposal/delta corpus roots |
+| `corpus.adrRoots` | `["docs/ADR"]` | ADR corpus roots |
+| `corpus.sourceRoots` | `["scripts/harness"]` | Source/test corpus roots |
+| `corpus.include` / `exclude` | `["**/*"]` / `[]` | Versioned selection patterns |
+| `inputs.matrixPath` | `.harness/requirement-test-matrix.json` | Matrix owner projection input |
+| `inputs.attestationPath` | `.harness/attestation.json` | Attestation evidence input |
+| `inputs.integrityManifestPath` | `phasegate.integrity.json` | Integrity declaration input |
+| `declarations.*Path` | `phasegate.world-{constraints,baseline,waivers,debts}.json` | Git-reviewed external declarations |
+| `output.obligationReportPath` | `.harness/world-obligations.json` | Generated, non-authoritative report path |
+| `sessionStart.enabled` | `true` | Allows the bounded World summary when session integration is installed |
+| `sessionStart.maxItems` / `maxChars` | `5` / `2000` | Summary caps; valid ranges are 1–20 and 1–8000 |
+
+All paths are project-relative POSIX paths. Absolute paths, backslashes, `.` / `..` segments, cross-role corpus root overlap, and case-fold collisions are rejected. When the matching World field is omitted, legacy `paths.designDocs`, `paths.inceptionDocs`, and `layers.L3.requirementMatrixPath` remain compatible inputs. A present but invalid `world` section fails closed; it is never replaced with defaults silently.
+
 #### `phase2Extensions`
 
 <!-- @work-item-id WI-170 -->

package/docs/templates/ci/aidlc-gate.yml

@@ -7,8 +7,10 @@
 # 実行内容:
 #   1. bypass:audit — bypass trailer / evidence 監査
 #   2. phasegate lint  — L1 Biome AST ルール検証
-#   3. phasegate:ci-check — L3 CI バリデータ（security / performance / coverage / nyquist）
-#   4. 失敗時: PR にエラーサマリーをコメント
+#   3. requirement-test matrix をcurrent testsから再生成
+#   4. world.enabled=true の場合、world:derive を2回実行してbyte一致を検証
+#   5. phasegate:ci-check — L3 CI バリデータ（security / performance / coverage / nyquist / World）
+#   6. 失敗時: PR にエラーサマリーをコメント
 
 name: AIDLC Quality Gate
 
@@ -77,6 +79,44 @@ jobs:
           echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
           exit $EXIT_CODE
 
+      # L3-004 consumes the generated requirement-test matrix. Always rebuild it
+      # from this checkout instead of trusting a stale or persisted artifact.
+      - name: Generate requirement-test matrix
+        if: always()
+        run: npx phasegate phasegate:generate-matrix
+
+      # Automatic World integration is selected only by an explicit true value.
+      # Missing/false keeps existing projects compatible; invalid JSON is a hard
+      # configuration error and must not be laundered into a disabled result.
+      - name: Detect World Model enablement
+        id: world_config
+        if: always()
+        shell: bash
+        run: |
+          set -euo pipefail
+          ENABLED=$(node --input-type=module <<'NODE'
+          import { existsSync, readFileSync } from 'node:fs';
+          if (!existsSync('phasegate.config.json')) {
+            process.stdout.write('false');
+          } else {
+            const config = JSON.parse(readFileSync('phasegate.config.json', 'utf8'));
+            process.stdout.write(config.world?.enabled === true ? 'true' : 'false');
+          }
+          NODE
+          )
+          echo "enabled=$ENABLED" >> "$GITHUB_OUTPUT"
+
+      - name: World derive determinism
+        if: steps.world_config.outputs.enabled == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          FIRST="$RUNNER_TEMP/phasegate-world-first.json"
+          SECOND="$RUNNER_TEMP/phasegate-world-second.json"
+          npx phasegate world:derive --json > "$FIRST"
+          npx phasegate world:derive --json > "$SECOND"
+          cmp --silent "$FIRST" "$SECOND"
+
       # L3: CI バリデータ（security / performance / coverage / nyquist）
       - name: L3 CI Check
         id: ci_check

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.229.0",
+  "version": "0.264.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/agent-integration/application/dto/open-world-obligations-context-dto.ts

@@ -0,0 +1,30 @@
+// @unit agent-integration
+// @layer application
+// @work-item-id WI-304
+
+export type OpenWorldObligationClassification =
+  | "new-structural"
+  | "invalid-declaration"
+  | "expired-waiver"
+  | "policy-diagnostic"
+  | "cleanup-required"
+  | "waived";
+
+export interface OpenWorldObligationContextItemDto {
+  readonly kind: "structural" | "cleanup-required" | "policy-diagnostic";
+  readonly classification: OpenWorldObligationClassification;
+  readonly ruleId: string | null;
+  readonly constraintId: string | null;
+  readonly violationFingerprint: string | null;
+  readonly subjectId: string | null;
+  readonly policyCode?: string | null;
+}
+
+export type OpenWorldObligationsContextDto =
+  | { readonly status: "disabled" }
+  | { readonly status: "unavailable" }
+  | {
+      readonly status: "available";
+      readonly entries: readonly OpenWorldObligationContextItemDto[];
+      readonly adoptedLegacyCount: number;
+    };

package/scripts/harness/agent-integration/application/ports/world-obligations-query-port.ts

@@ -0,0 +1,30 @@
+// @unit agent-integration
+// @layer application
+// @work-item-id WI-304
+
+export type QueriedWorldObligationClassification =
+  | "adopted-legacy"
+  | "new-structural"
+  | "invalid-declaration"
+  | "expired-waiver"
+  | "policy-diagnostic"
+  | "cleanup-required"
+  | "waived";
+
+export interface QueriedWorldObligationEntry {
+  readonly kind: "structural" | "cleanup-required" | "policy-diagnostic";
+  readonly classification: QueriedWorldObligationClassification;
+  readonly ruleId: string | null;
+  readonly constraintId: string | null;
+  readonly violationFingerprint: string | null;
+  readonly subjectId?: string | null;
+  readonly policyCode?: string | null;
+}
+
+export type WorldObligationsQueryResult =
+  | { readonly status: "available"; readonly entries: readonly QueriedWorldObligationEntry[] }
+  | { readonly status: "unavailable" };
+
+export interface WorldObligationsQueryPort {
+  query(): Promise<WorldObligationsQueryResult>;
+}

package/scripts/harness/agent-integration/application/usecases/get-open-world-obligations-context-usecase.ts

@@ -0,0 +1,66 @@
+// @unit agent-integration
+// @layer application
+// @work-item-id WI-304
+
+import type {
+  OpenWorldObligationContextItemDto,
+  OpenWorldObligationsContextDto,
+} from "../dto/open-world-obligations-context-dto.js";
+import type { QueriedWorldObligationEntry, WorldObligationsQueryPort } from "../ports/world-obligations-query-port.js";
+
+interface Dependencies {
+  readonly worldObligationsQueryPort: WorldObligationsQueryPort;
+}
+
+const priority = (entry: OpenWorldObligationContextItemDto): number => {
+  if (entry.classification === "new-structural" || entry.classification === "invalid-declaration") return 0;
+  if (entry.classification === "expired-waiver" || entry.classification === "policy-diagnostic") return 1;
+  if (entry.classification === "cleanup-required") return 2;
+  return 3;
+};
+
+const stableKey = (entry: OpenWorldObligationContextItemDto): string =>
+  [
+    priority(entry).toString().padStart(2, "0"),
+    entry.ruleId ?? "",
+    entry.constraintId ?? "",
+    entry.violationFingerprint ?? "",
+    entry.subjectId ?? "",
+    entry.policyCode ?? "",
+  ].join("\u0000");
+
+type DisplayableQueriedEntry = QueriedWorldObligationEntry & {
+  readonly classification: Exclude<QueriedWorldObligationEntry["classification"], "adopted-legacy">;
+};
+
+const isDisplayable = (entry: QueriedWorldObligationEntry): entry is DisplayableQueriedEntry =>
+  entry.classification !== "adopted-legacy";
+
+const toContextItem = (entry: DisplayableQueriedEntry): OpenWorldObligationContextItemDto => ({
+  kind: entry.kind,
+  classification: entry.classification,
+  ruleId: entry.ruleId,
+  constraintId: entry.constraintId,
+  violationFingerprint: entry.violationFingerprint,
+  subjectId: entry.subjectId ?? null,
+  policyCode: entry.policyCode ?? null,
+});
+
+export class GetOpenWorldObligationsContextUseCase {
+  constructor(private readonly dependencies: Dependencies) {}
+
+  async execute(input: { readonly enabled: boolean }): Promise<OpenWorldObligationsContextDto> {
+    if (!input.enabled) return { status: "disabled" };
+
+    const result = await this.dependencies.worldObligationsQueryPort.query();
+    if (result.status === "unavailable") return { status: "unavailable" };
+
+    const adoptedLegacyCount = result.entries.filter((entry) => entry.classification === "adopted-legacy").length;
+    const entries = result.entries
+      .filter(isDisplayable)
+      .map(toContextItem)
+      .sort((left, right) => (stableKey(left) < stableKey(right) ? -1 : stableKey(left) > stableKey(right) ? 1 : 0));
+
+    return { status: "available", entries: Object.freeze(entries), adoptedLegacyCount };
+  }
+}

package/scripts/harness/agent-integration/infrastructure/adapters/world-model-open-obligations-query-adapter.ts

@@ -0,0 +1,58 @@
+// @unit agent-integration
+// @layer infrastructure
+// @work-item-id WI-304
+
+import { createWorldModelModule, type WorldResolvedConfigInput } from "../../../world-model/index.js";
+import type {
+  QueriedWorldObligationEntry,
+  WorldObligationsQueryPort,
+  WorldObligationsQueryResult,
+} from "../../application/ports/world-obligations-query-port.js";
+
+interface Options {
+  readonly rootDir: string;
+  readonly resolvedConfig?: WorldResolvedConfigInput;
+}
+
+export class WorldModelOpenObligationsQueryAdapter implements WorldObligationsQueryPort {
+  constructor(private readonly options: Options) {}
+
+  async query(): Promise<WorldObligationsQueryResult> {
+    try {
+      const world = createWorldModelModule(this.options);
+      const derived = await world.deriveWorldObligationsUseCase.execute({ writeReport: false });
+      if (derived.status !== "derived") return { status: "unavailable" };
+
+      const report = derived.result.report;
+      const entries: QueriedWorldObligationEntry[] = [
+        ...report.structuralObligations.map((entry) => ({
+          kind: "structural" as const,
+          classification: entry.classification,
+          ruleId: entry.ruleId,
+          constraintId: entry.constraintId,
+          violationFingerprint: entry.violationFingerprint,
+        })),
+        ...report.repaidBaselineEntries.map((entry) => ({
+          kind: "cleanup-required" as const,
+          classification: "cleanup-required" as const,
+          ruleId: entry.ruleId,
+          constraintId: entry.constraintId,
+          violationFingerprint: entry.violationFingerprint,
+        })),
+        ...report.policyDiagnostics.map((entry) => ({
+          kind: "policy-diagnostic" as const,
+          classification:
+            entry.code === "expired-waiver" ? ("expired-waiver" as const) : ("policy-diagnostic" as const),
+          ruleId: null,
+          constraintId: null,
+          violationFingerprint: null,
+          subjectId: entry.subjectId,
+          policyCode: entry.code,
+        })),
+      ];
+      return { status: "available", entries: Object.freeze(entries) };
+    } catch {
+      return { status: "unavailable" };
+    }
+  }
+}

package/scripts/harness/agent-integration/presentation/session-start-hook.ts

@@ -1,13 +1,18 @@
 // @unit agent-integration
 // @layer presentation
+// @work-item-id WI-304
 
 import { buildCiGovernance } from "../../ci-governance/composition-root.js";
+import { createConfigFoundationModule, toWorldModelConfig } from "../../config-foundation/index.js";
+import { GetOpenWorldObligationsContextUseCase } from "../application/usecases/get-open-world-obligations-context-usecase.js";
+import { WorldModelOpenObligationsQueryAdapter } from "../infrastructure/adapters/world-model-open-obligations-query-adapter.js";
 import {
   buildIntegrityUnverifiableWarning,
   buildIntegrityWarning,
   buildSessionStartContext,
   collectPhasegateStatus,
 } from "./phasegate-status-context.js";
+import { buildWorldObligationsSessionContext } from "./world-obligations-session-context.js";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -36,6 +41,36 @@ async function buildIntegrityContext(cwd: string): Promise<string | null> {
   }
 }
 
+/**
+ * World の保存済み report は読まず、公開 facade の pure derive から現在の open obligation を要約する。
+ * config/derive の失敗は固定 warning へ縮退し、repository 由来のエラー文字列は中継しない。
+ */
+async function buildWorldContext(cwd: string): Promise<string | null> {
+  try {
+    const configModule = createConfigFoundationModule();
+    const resolved = await configModule.usecases.loadResolvedConfigUseCase.execute();
+    const worldConfig = toWorldModelConfig(resolved.config);
+    if (worldConfig === undefined) return null;
+
+    const contextUseCase = new GetOpenWorldObligationsContextUseCase({
+      worldObligationsQueryPort: new WorldModelOpenObligationsQueryAdapter({
+        rootDir: cwd,
+        resolvedConfig: worldConfig,
+      }),
+    });
+    const context = await contextUseCase.execute({
+      enabled: worldConfig.enabled && worldConfig.sessionStart.enabled,
+    });
+    return buildWorldObligationsSessionContext(context, {
+      maxItems: worldConfig.sessionStart.maxItems,
+      maxChars: worldConfig.sessionStart.maxChars,
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "ConfigNotFoundError") return null;
+    return buildWorldObligationsSessionContext({ status: "unavailable" }, { maxItems: 5, maxChars: 2000 });
+  }
+}
+
 async function main(): Promise<void> {
   try {
     await readStdin();
@@ -46,7 +81,8 @@ async function main(): Promise<void> {
   const status = await collectPhasegateStatus(process.cwd());
   const baseContext = buildSessionStartContext(status);
   const integrityContext = await buildIntegrityContext(process.cwd());
-  const additionalContext = integrityContext === null ? baseContext : `${integrityContext}\n\n${baseContext}`;
+  const worldContext = await buildWorldContext(process.cwd());
+  const additionalContext = [integrityContext, worldContext, baseContext].filter((item) => item !== null).join("\n\n");
 
   const output = {
     hookSpecificOutput: {

package/scripts/harness/agent-integration/presentation/world-obligations-session-context.ts

@@ -0,0 +1,60 @@
+// @unit agent-integration
+// @layer presentation
+// @work-item-id WI-304
+
+import type {
+  OpenWorldObligationContextItemDto,
+  OpenWorldObligationsContextDto,
+} from "../application/dto/open-world-obligations-context-dto.js";
+
+const UNAVAILABLE_WARNING =
+  "⚠ World obligations unavailable at SessionStart; continuing fail-open. Run phasegate world:derive.";
+const HEADER = "## World open obligations (SessionStart)";
+const HARD_MAX_ITEMS = 5;
+const HARD_MAX_CHARS = 2000;
+
+export const countUnicodeScalars = (value: string): number => [...value].length;
+
+const renderEntry = (entry: OpenWorldObligationContextItemDto): string => {
+  if (entry.kind === "policy-diagnostic") {
+    return `- [BLOCKING ${entry.classification}] subject=${entry.subjectId ?? "unknown"}`;
+  }
+  const label =
+    entry.classification === "cleanup-required"
+      ? "CLEANUP"
+      : entry.classification === "waived"
+        ? "WAIVED"
+        : `BLOCKING ${entry.classification}`;
+  return `- [${label}] ${entry.ruleId ?? "unknown-rule"} constraint=${entry.constraintId ?? "implicit"} fingerprint=${entry.violationFingerprint ?? "none"}`;
+};
+
+const renderAvailable = (
+  input: Extract<OpenWorldObligationsContextDto, { status: "available" }>,
+  shown: number,
+): string => {
+  const lines = [HEADER, ...input.entries.slice(0, shown).map(renderEntry)];
+  if (input.adoptedLegacyCount > 0) lines.push(`- Adopted legacy: ${input.adoptedLegacyCount} (summary only)`);
+  if (input.entries.length === 0 && input.adoptedLegacyCount === 0) lines.push("- None.");
+  const omitted = input.entries.length - shown;
+  if (omitted > 0) lines.push(`... ${omitted} more; run phasegate world:derive`);
+  return lines.join("\n");
+};
+
+export function buildWorldObligationsSessionContext(
+  input: OpenWorldObligationsContextDto,
+  limits: { readonly maxItems: number; readonly maxChars: number },
+): string | null {
+  const maxItems = Math.min(limits.maxItems, HARD_MAX_ITEMS);
+  const maxChars = Math.min(limits.maxChars, HARD_MAX_CHARS);
+  if (input.status === "disabled") return null;
+  if (input.status === "unavailable") {
+    return countUnicodeScalars(UNAVAILABLE_WARNING) <= maxChars ? UNAVAILABLE_WARNING : null;
+  }
+
+  const maximumShown = Math.min(input.entries.length, maxItems);
+  for (let shown = maximumShown; shown >= 0; shown -= 1) {
+    const candidate = renderAvailable(input, shown);
+    if (countUnicodeScalars(candidate) <= maxChars) return candidate;
+  }
+  return null;
+}

package/scripts/harness/attestation/application/dto/attestation-document.ts

@@ -1,8 +1,9 @@
 // @unit attestation
 // @layer application
+// @work-item-id WI-306
 
 /**
- * record format `phasegate-attestation/v1` の plain object 表現（logical_design §1.4.3）。
+ * versioned record formatのplain object表現（logical_design §1.4.3 / WI-306）。
  * ファイル入出力・stdout エコー・mapper の境界で用いる契約型。VO はプリミティブ展開する。
  */
 export interface AttestationDocumentValidatorOutcome {
@@ -23,9 +24,7 @@ export interface AttestationDocumentGranularityClaim {
   readonly knownLimitations: string[];
 }
 
-export interface AttestationDocument {
-  readonly schemaVersion: "phasegate-attestation/v1";
-  readonly predicateType: string;
+interface AttestationDocumentBase {
   readonly subject: {
     readonly command: string;
     readonly gateResult: "pass" | "fail";
@@ -54,3 +53,17 @@ export interface AttestationDocument {
     readonly value: string | null;
   };
 }
+
+export interface AttestationDocumentV1 extends AttestationDocumentBase {
+  readonly schemaVersion: "phasegate-attestation/v1";
+  readonly predicateType: "https://phasegate.dev/attestation/gate-run/v1";
+}
+
+export interface AttestationDocumentV2 extends AttestationDocumentBase {
+  readonly schemaVersion: "phasegate-attestation/v2";
+  readonly predicateType: "https://phasegate.dev/attestation/gate-run/v2";
+  /** 実行時のWorld canonical corpusRoot。個別fragment digestは保持しない。 */
+  readonly worldSnapshotRoot: string;
+}
+
+export type AttestationDocument = AttestationDocumentV1 | AttestationDocumentV2;

package/scripts/harness/attestation/application/mappers/attestation-record-mapper.ts

@@ -1,5 +1,6 @@
 // @unit attestation
 // @layer application
+// @work-item-id WI-306
 
 import {
   AttestationRecord,
@@ -44,15 +45,20 @@ function requireBoolean(v: unknown, field: string): boolean {
   return v;
 }
 
+function rejectUnknownFields(value: Record<string, unknown>, allowed: readonly string[], field: string): void {
+  const unsupported = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unsupported.length > 0) {
+    throw new MalformedAttestationError(`${field} contains unsupported fields: ${unsupported.sort().join(", ")}`);
+  }
+}
+
 /**
  * AttestationRecord（domain）↔ AttestationDocument（application DTO）の双方向変換。
  */
 export class AttestationRecordMapper {
   /** 集約を plain object へ射影（VO をプリミティブ展開）。 */
   toDocument(record: AttestationRecord): AttestationDocument {
-    return {
-      schemaVersion: record.schemaVersion as "phasegate-attestation/v1",
-      predicateType: record.predicateType,
+    const common = {
       subject: {
         command: record.subject.command,
         gateResult: record.subject.gateResult,
@@ -63,7 +69,7 @@ export class AttestationRecordMapper {
         })),
       },
       inputs: {
-        digestAlgorithm: "sha256",
+        digestAlgorithm: "sha256" as const,
         sources: record.inputs.sources.map((s) => ({ path: s.path, digest: s.digest.value })),
         inputDigest: record.inputs.inputDigest.value,
       },
@@ -89,6 +95,19 @@ export class AttestationRecordMapper {
         value: record.signature.value,
       },
     };
+    if (record.worldSnapshotRoot !== null) {
+      return {
+        ...common,
+        schemaVersion: "phasegate-attestation/v2",
+        predicateType: "https://phasegate.dev/attestation/gate-run/v2",
+        worldSnapshotRoot: record.worldSnapshotRoot.value,
+      };
+    }
+    return {
+      ...common,
+      schemaVersion: "phasegate-attestation/v1",
+      predicateType: "https://phasegate.dev/attestation/gate-run/v1",
+    };
   }
 
   /**
@@ -102,6 +121,37 @@ export class AttestationRecordMapper {
 
     const schemaVersion = requireString(doc.schemaVersion, "schemaVersion");
     const predicateType = requireString(doc.predicateType, "predicateType");
+    let worldSnapshotRoot: Digest | undefined;
+    if (schemaVersion === "phasegate-attestation/v1") {
+      if (predicateType !== "https://phasegate.dev/attestation/gate-run/v1") {
+        throw new MalformedAttestationError("v1 predicateType does not match schemaVersion");
+      }
+      if (doc.worldSnapshotRoot !== undefined) {
+        throw new MalformedAttestationError("v1 must not contain worldSnapshotRoot");
+      }
+    } else if (schemaVersion === "phasegate-attestation/v2") {
+      if (predicateType !== "https://phasegate.dev/attestation/gate-run/v2") {
+        throw new MalformedAttestationError("v2 predicateType does not match schemaVersion");
+      }
+      worldSnapshotRoot = this.toDigest(doc.worldSnapshotRoot, "worldSnapshotRoot");
+      rejectUnknownFields(
+        doc,
+        [
+          "schemaVersion",
+          "predicateType",
+          "subject",
+          "inputs",
+          "granularity",
+          "acBoundScope",
+          "worldSnapshotRoot",
+          "metadata",
+          "signature",
+        ],
+        "v2 attestation",
+      );
+    } else {
+      throw new MalformedAttestationError(`unsupported schemaVersion: ${schemaVersion}`);
+    }
 
     const subject = doc.subject;
     if (!isObject(subject)) {
@@ -185,6 +235,7 @@ export class AttestationRecordMapper {
       },
       signature: this.toSignatureBlock(mode, attestationDigest, signature),
       acBoundScope,
+      ...(worldSnapshotRoot === undefined ? {} : { worldSnapshotRoot }),
     };
 
     // verify 用の再構築: INV-1/INV-3 は verify usecase が機械的チェックとして検出するため

package/scripts/harness/attestation/application/ports/sha256-capability.ts

@@ -0,0 +1,25 @@
+// @unit attestation
+// @layer application
+// @work-item-id WI-286
+
+/**
+ * Unit境界を越えて受け渡すplain SHA-256 digest。
+ *
+ * 64桁lowercase hexのruntime invariantはproviderと各consumer-local VOが検証する。
+ * attestation domainのDigestはこのpublic contractへ露出しない。
+ */
+export type Sha256DigestString = `sha256:${string}`;
+
+/**
+ * Raw bytesをSHA-256するattestation public capability。
+ */
+export interface Sha256Capability {
+  hashBytes(bytes: Uint8Array): Sha256DigestString;
+}
+
+/**
+ * Unicode normalizationを行わず、TextEncoderのUTF-8 bytesをpublic capabilityへ渡す。
+ */
+export function hashUtf8(capability: Sha256Capability, text: string): Sha256DigestString {
+  return capability.hashBytes(new TextEncoder().encode(text));
+}

package/scripts/harness/attestation/application/ports/world-snapshot-root-provider.ts

@@ -0,0 +1,10 @@
+// @unit attestation
+// @layer application
+// @work-item-id WI-306
+
+/**
+ * attestationが所有するconsumer port。providerのWorld domain型を公開しない。
+ */
+export interface WorldSnapshotRootProvider {
+  getWorldSnapshotRoot(): Promise<string>;
+}