phasegate 0.229.0 → 0.264.0

package/scripts/harness/world-model/application/dto/world-inspection-dto.ts

@@ -0,0 +1,43 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-291
+
+export type WorldJsonValue = null | boolean | number | string | readonly WorldJsonValue[] | WorldJsonObject;
+
+export interface WorldJsonObject {
+  readonly [key: string]: WorldJsonValue;
+}
+
+export interface WorldInventoryCountDto {
+  readonly value: string;
+  readonly count: number;
+}
+
+export interface WorldExtractionDiagnosticDto extends WorldJsonObject {
+  readonly code: string;
+  readonly line: number | null;
+  readonly nodeId: string | null;
+  readonly pathKey: string | null;
+  readonly payload: WorldJsonObject;
+}
+
+export interface WorldInspectionDto {
+  readonly snapshotId: string;
+  readonly schemaVersion: string;
+  readonly extractorVersion: string;
+  readonly corpusRoot: string;
+  readonly summary: {
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+    readonly diagnosticCount: number;
+    readonly hardDiagnosticCount: number;
+  };
+  readonly inventory: {
+    readonly nodeTypes: readonly WorldInventoryCountDto[];
+    readonly corpusRoles: readonly WorldInventoryCountDto[];
+    readonly artifactKinds: readonly WorldInventoryCountDto[];
+  };
+  readonly nodes: readonly WorldJsonObject[];
+  readonly edges: readonly WorldJsonObject[];
+  readonly diagnostics: readonly WorldExtractionDiagnosticDto[];
+}

package/scripts/harness/world-model/application/dto/world-obligation-report-dto.ts

@@ -0,0 +1,54 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-295
+
+import type { CanonicalJsonObject } from "../../domain/services/canonical-json-serializer.js";
+
+export type StructuralObligationClassification = "adopted-legacy" | "new-structural" | "invalid-declaration" | "waived";
+
+export interface StructuralObligationDto {
+  readonly violationFingerprint: string;
+  readonly ruleId: string;
+  readonly constraintId: string | null;
+  readonly factType: string | null;
+  readonly subject: CanonicalJsonObject;
+  readonly claimantPin: CanonicalJsonObject | null;
+  readonly premisePin: CanonicalJsonObject | null;
+  readonly expected: CanonicalJsonObject;
+  readonly observed: CanonicalJsonObject;
+  readonly classification: StructuralObligationClassification;
+  readonly waiver: CanonicalJsonObject | null;
+}
+
+export interface RepaidBaselineEntryDto {
+  readonly violationFingerprint: string;
+  readonly ruleId: string;
+  readonly constraintId: string | null;
+  readonly classification: "repaid";
+  readonly disposition: "cleanup-required";
+}
+
+export interface PolicyDiagnosticDto {
+  readonly code: string;
+  readonly subjectId: string | null;
+  readonly details: CanonicalJsonObject;
+}
+
+export interface ObligationReportSummaryDto {
+  readonly structuralObligations: number;
+  readonly repaidBaselineEntries: number;
+  readonly declaredSemanticDebts: number;
+  readonly policyDiagnostics: number;
+}
+
+export interface WorldObligationReportDto {
+  readonly schemaVersion: "phasegate-world-obligation-report/v1";
+  readonly evaluationId: string;
+  readonly rulesetVersion: string;
+  readonly policyInputsDigest: string;
+  readonly structuralObligations: readonly StructuralObligationDto[];
+  readonly repaidBaselineEntries: readonly RepaidBaselineEntryDto[];
+  readonly declaredSemanticDebts: readonly CanonicalJsonObject[];
+  readonly policyDiagnostics: readonly PolicyDiagnosticDto[];
+  readonly summary: ObligationReportSummaryDto;
+}

package/scripts/harness/world-model/application/dto/world-resolved-config-input.ts

@@ -0,0 +1,127 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-291, WI-300
+
+import { PathKey } from "../../domain/value-objects/path-key.js";
+
+export interface WorldResolvedConfigInput {
+  readonly enabled?: boolean;
+  readonly corpus?: {
+    readonly productRoots?: readonly string[];
+    readonly inceptionRoots?: readonly string[];
+    readonly adrRoots?: readonly string[];
+    readonly sourceRoots?: readonly string[];
+    readonly include?: readonly string[];
+    readonly exclude?: readonly string[];
+  };
+  readonly inputs?: {
+    readonly matrixPath?: string;
+    readonly attestationPath?: string;
+    readonly integrityManifestPath?: string;
+  };
+  readonly declarations?: {
+    readonly constraintsPath?: string;
+    readonly baselinePath?: string;
+    readonly waiversPath?: string;
+    readonly debtsPath?: string;
+  };
+  readonly output?: { readonly obligationReportPath?: string };
+  readonly sessionStart?: {
+    readonly enabled?: boolean;
+    readonly maxItems?: number;
+    readonly maxChars?: number;
+  };
+  readonly designDocsRoot?: string;
+  readonly inceptionRoot?: string;
+  readonly requirementMatrixPath?: string;
+}
+
+export interface WorldCorpusConfig {
+  readonly enabled: boolean;
+  readonly productScopes: readonly {
+    readonly productRoot: string;
+    readonly designDocsRoot: string;
+    readonly unitRoot: string;
+  }[];
+  readonly inceptionRoots: readonly string[];
+  readonly adrRoots: readonly string[];
+  readonly sourceRoots: readonly string[];
+  readonly include: readonly string[];
+  readonly exclude: readonly string[];
+  readonly matrixPath: string;
+  readonly attestationPath: string;
+  readonly integrityManifestPath: string;
+  readonly constraintsPath: string;
+  readonly baselinePath: string;
+  readonly waiversPath: string;
+  readonly debtsPath: string;
+  readonly obligationReportPath: string;
+  readonly sessionStart: { readonly enabled: boolean; readonly maxItems: number; readonly maxChars: number };
+}
+
+const validatePath = (value: string): string => PathKey.create(value).toString();
+const validatePaths = (values: readonly string[]): readonly string[] => Object.freeze(values.map(validatePath));
+
+const deriveProductRoot = (designDocsRoot: string): string => {
+  const normalized = designDocsRoot.replace(/\/+$/, "");
+  return normalized.endsWith("/construction") ? normalized.slice(0, -"/construction".length) : normalized;
+};
+
+const resolveProductRoots = (input?: WorldResolvedConfigInput): readonly string[] => {
+  if (input?.corpus?.productRoots !== undefined) return validatePaths(input.corpus.productRoots);
+  if (input?.designDocsRoot === undefined) return Object.freeze(["docs/product"]);
+  const productRoot = validatePath(deriveProductRoot(input.designDocsRoot));
+  return Object.freeze(productRoot === "docs/product" ? [productRoot] : ["docs/product", productRoot]);
+};
+
+const assertLimit = (name: string, value: number, maximum: number): number => {
+  if (!Number.isInteger(value) || value < 1 || value > maximum) {
+    throw new Error(`${name} must be an integer between 1 and ${maximum}`);
+  }
+  return value;
+};
+
+export const resolveWorldCorpusConfig = (input?: WorldResolvedConfigInput): WorldCorpusConfig => {
+  const productRoots = resolveProductRoots(input);
+  const inceptionRoots = validatePaths(input?.corpus?.inceptionRoots ?? [input?.inceptionRoot ?? "docs/inception"]);
+  const adrRoots = validatePaths(input?.corpus?.adrRoots ?? ["docs/ADR"]);
+  const sourceRoots = validatePaths(input?.corpus?.sourceRoots ?? ["scripts/harness"]);
+  if ([productRoots, inceptionRoots, adrRoots, sourceRoots].some((roots) => roots.length === 0)) {
+    throw new Error("World corpus roots must not be empty");
+  }
+  const include = Object.freeze([...(input?.corpus?.include ?? ["**/*"])]);
+  const exclude = Object.freeze([...(input?.corpus?.exclude ?? [])]);
+  if (include.length === 0 || [...include, ...exclude].some((pattern) => pattern.length === 0)) {
+    throw new Error("World corpus selection patterns must not be empty");
+  }
+  return Object.freeze({
+    enabled: input?.enabled ?? false,
+    productScopes: Object.freeze(
+      productRoots.map((productRoot) => ({
+        productRoot,
+        designDocsRoot: validatePath(`${productRoot}/construction`),
+        unitRoot: validatePath(`${productRoot}/units`),
+      })),
+    ),
+    inceptionRoots,
+    adrRoots,
+    sourceRoots,
+    include,
+    exclude,
+    matrixPath: validatePath(
+      input?.inputs?.matrixPath ?? input?.requirementMatrixPath ?? ".harness/requirement-test-matrix.json",
+    ),
+    attestationPath: validatePath(input?.inputs?.attestationPath ?? ".harness/attestation.json"),
+    integrityManifestPath: validatePath(input?.inputs?.integrityManifestPath ?? "phasegate.integrity.json"),
+    constraintsPath: validatePath(input?.declarations?.constraintsPath ?? "phasegate.world-constraints.json"),
+    baselinePath: validatePath(input?.declarations?.baselinePath ?? "phasegate.world-baseline.json"),
+    waiversPath: validatePath(input?.declarations?.waiversPath ?? "phasegate.world-waivers.json"),
+    debtsPath: validatePath(input?.declarations?.debtsPath ?? "phasegate.world-debts.json"),
+    obligationReportPath: validatePath(input?.output?.obligationReportPath ?? ".harness/world-obligations.json"),
+    sessionStart: Object.freeze({
+      enabled: input?.sessionStart?.enabled ?? true,
+      maxItems: assertLimit("world.sessionStart.maxItems", input?.sessionStart?.maxItems ?? 5, 20),
+      maxChars: assertLimit("world.sessionStart.maxChars", input?.sessionStart?.maxChars ?? 2000, 8000),
+    }),
+  });
+};

package/scripts/harness/world-model/application/dto/world-snapshot-root-dto.ts

@@ -0,0 +1,8 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-306
+
+export interface WorldSnapshotRootDto {
+  readonly schemaVersion: "phasegate-world-snapshot-root/v1";
+  readonly worldSnapshotRoot: string;
+}

package/scripts/harness/world-model/application/facades/pinned-design-endpoint-facade.ts

@@ -0,0 +1,63 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-305
+
+import type { PinnedDesignEndpointDto, PinnedDesignEndpointReadResultDto } from "../dto/pinned-design-endpoint-dto.js";
+import type { ConstraintDeclarationRepositoryPort } from "../ports/world-control-declaration-repository-port.js";
+
+const EXPLICIT_FRAGMENT_ID = /^pgw:v1:fragment:(product|inception):(.+)$/;
+const compare = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+export class PinnedDesignEndpointFacade {
+  constructor(private readonly repository: ConstraintDeclarationRepositoryPort) {}
+
+  async read(): Promise<PinnedDesignEndpointReadResultDto> {
+    const result = await this.repository.load();
+    if (result.state === "invalid") {
+      return Object.freeze({
+        state: "unavailable",
+        diagnosticCodes: Object.freeze([...new Set(result.diagnostics.map((item) => item.code))].sort(compare)),
+      });
+    }
+    if (result.value.malformedDeclarations.length > 0 || result.value.diagnostics.length > 0) {
+      return Object.freeze({
+        state: "unavailable",
+        diagnosticCodes: Object.freeze(
+          [
+            ...(result.value.malformedDeclarations.length > 0 ? ["malformed-constraint-declaration"] : []),
+            ...result.value.diagnostics.map((item) => item.code),
+          ].sort(compare),
+        ),
+      });
+    }
+    const endpoints: PinnedDesignEndpointDto[] = [];
+    for (const record of result.value.records) {
+      for (const endpoint of ["claimant", "premise"] as const) {
+        const nodeId = record[endpoint].nodeId.toString();
+        const match = EXPLICIT_FRAGMENT_ID.exec(nodeId);
+        if (!match) continue;
+        endpoints.push(
+          Object.freeze({
+            constraintId: record.constraintId.toString(),
+            endpoint,
+            nodeId,
+            corpusRole: match[1] as "product" | "inception",
+            declaredKey: match[2],
+          }),
+        );
+      }
+    }
+    endpoints.sort(
+      (left, right) =>
+        compare(left.corpusRole, right.corpusRole) ||
+        compare(left.declaredKey, right.declaredKey) ||
+        compare(left.constraintId, right.constraintId) ||
+        compare(left.endpoint, right.endpoint),
+    );
+    return Object.freeze({
+      state: "available",
+      endpoints: Object.freeze(endpoints),
+      diagnosticCodes: Object.freeze([]),
+    });
+  }
+}

package/scripts/harness/world-model/application/facades/world-snapshot-root-facade.ts

@@ -0,0 +1,19 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-306
+
+import type { WorldSnapshotRootDto } from "../dto/world-snapshot-root-dto.js";
+import type { BuildSnapshotContract } from "../usecases/build-snapshot-use-case.js";
+
+/** World domain型を公開せずcurrent corpusRootだけを返すpublic read facade。 */
+export class WorldSnapshotRootFacade {
+  constructor(private readonly buildSnapshot: BuildSnapshotContract) {}
+
+  async read(): Promise<WorldSnapshotRootDto> {
+    const snapshot = await this.buildSnapshot.execute();
+    return {
+      schemaVersion: "phasegate-world-snapshot-root/v1",
+      worldSnapshotRoot: snapshot.corpusRoot.toString(),
+    };
+  }
+}

package/scripts/harness/world-model/application/ports/obligation-report-writer-port.ts

@@ -0,0 +1,7 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-295, WI-296
+
+export interface ObligationReportWriterPort {
+  write(bytes: Uint8Array, reportPath?: string): Promise<void>;
+}

package/scripts/harness/world-model/application/ports/world-control-declaration-repository-port.ts

@@ -0,0 +1,57 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-294
+
+import type { ConstraintRecord, MalformedConstraintDeclaration } from "../../domain/entities/constraint-record.js";
+import type {
+  AdoptionBaseline,
+  SemanticDebtDeclaration,
+  WorldWaiver,
+} from "../../domain/entities/control-declarations.js";
+import type { ExplicitConstraintRelation } from "../../domain/value-objects/explicit-constraint-relation.js";
+import type { ExplicitNodeAlias } from "../../domain/value-objects/explicit-node-alias.js";
+
+export interface WorldControlDiagnosticDto {
+  readonly code: string;
+  readonly path: string;
+  readonly locator: string | null;
+  readonly message: string;
+}
+
+export interface ConstraintDeclarationSet {
+  readonly schemaVersion: "phasegate-world-constraints/v1";
+  readonly records: readonly ConstraintRecord[];
+  readonly malformedDeclarations: readonly MalformedConstraintDeclaration[];
+  readonly aliases: readonly ExplicitNodeAlias[];
+  readonly relations: readonly ExplicitConstraintRelation[];
+  readonly diagnostics: readonly WorldControlDiagnosticDto[];
+}
+
+export type WorldControlReadResult<T> =
+  | { readonly state: "absent"; readonly value: T; readonly diagnostics: readonly WorldControlDiagnosticDto[] }
+  | { readonly state: "loaded"; readonly value: T; readonly diagnostics: readonly WorldControlDiagnosticDto[] }
+  | { readonly state: "invalid"; readonly diagnostics: readonly WorldControlDiagnosticDto[] };
+
+export type WorldControlReplaceResult =
+  | { readonly state: "written"; readonly path: string }
+  | { readonly state: "invalid"; readonly diagnostics: readonly WorldControlDiagnosticDto[] };
+
+export interface ConstraintDeclarationRepositoryPort {
+  load(): Promise<WorldControlReadResult<ConstraintDeclarationSet>>;
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult>;
+}
+
+export interface AdoptionBaselineRepositoryPort {
+  load(): Promise<WorldControlReadResult<AdoptionBaseline | null>>;
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult>;
+}
+
+export interface WaiverDeclarationRepositoryPort {
+  load(): Promise<WorldControlReadResult<readonly WorldWaiver[]>>;
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult>;
+}
+
+export interface SemanticDebtRepositoryPort {
+  load(): Promise<WorldControlReadResult<readonly SemanticDebtDeclaration[]>>;
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult>;
+}

package/scripts/harness/world-model/application/ports/world-fact-source-port.ts

@@ -0,0 +1,17 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-291
+
+import type { Edge } from "../../domain/entities/edge.js";
+import type { ExtractionDiagnostic } from "../../domain/entities/extraction-diagnostic.js";
+import type { WorldNode } from "../../domain/entities/world-node.js";
+
+export interface WorldFactBatch {
+  readonly nodes: readonly WorldNode[];
+  readonly edges: readonly Edge[];
+  readonly diagnostics: readonly ExtractionDiagnostic[];
+}
+
+export interface WorldFactSourcePort {
+  extract(): Promise<readonly WorldFactBatch[]>;
+}

package/scripts/harness/world-model/application/usecases/build-snapshot-use-case.ts

@@ -0,0 +1,111 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-291
+
+import type { Edge } from "../../domain/entities/edge.js";
+import { ExtractionDiagnostic } from "../../domain/entities/extraction-diagnostic.js";
+import type { Snapshot } from "../../domain/entities/snapshot.js";
+import type { WorldNode } from "../../domain/entities/world-node.js";
+import type { CanonicalJsonSerializer } from "../../domain/services/canonical-json-serializer.js";
+import type { SnapshotRootDeriver } from "../../domain/services/snapshot-root-deriver.js";
+import type { Sha256Digest } from "../../domain/value-objects/sha256-digest.js";
+import type { WorldFactSourcePort } from "../ports/world-fact-source-port.js";
+
+export interface BuildSnapshotContract {
+  execute(): Promise<Snapshot>;
+}
+
+export interface BuildSnapshotUseCaseDeps {
+  readonly factSource: WorldFactSourcePort;
+  readonly rootDeriver: SnapshotRootDeriver;
+  readonly serializer: CanonicalJsonSerializer;
+  readonly schemaVersion: string;
+  readonly extractorVersion: string;
+  readonly corpusConfigDigest: Sha256Digest;
+}
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+export class BuildSnapshotUseCase implements BuildSnapshotContract {
+  constructor(private readonly deps: BuildSnapshotUseCaseDeps) {}
+
+  async execute(): Promise<Snapshot> {
+    const batches = await this.deps.factSource.extract();
+    const diagnostics = batches.flatMap((batch) => batch.diagnostics);
+    const nodes = this.admitNodes(
+      batches.flatMap((batch) => batch.nodes),
+      diagnostics,
+    );
+    const edges = this.admitEdges(
+      batches.flatMap((batch) => batch.edges),
+      new Set(nodes.map((node) => node.id.toString())),
+      diagnostics,
+    );
+    return this.deps.rootDeriver.buildSnapshot({
+      schemaVersion: this.deps.schemaVersion,
+      extractorVersion: this.deps.extractorVersion,
+      corpusConfigDigest: this.deps.corpusConfigDigest,
+      nodes,
+      edges,
+      extractionDiagnostics: diagnostics,
+    });
+  }
+
+  private admitNodes(candidates: readonly WorldNode[], diagnostics: ExtractionDiagnostic[]): readonly WorldNode[] {
+    const grouped = new Map<string, WorldNode[]>();
+    for (const candidate of candidates) {
+      const key = candidate.id.toString();
+      grouped.set(key, [...(grouped.get(key) ?? []), candidate]);
+    }
+    const admitted: WorldNode[] = [];
+    for (const [nodeId, entries] of [...grouped.entries()].sort(([left], [right]) => compareStrings(left, right))) {
+      if (entries.length === 1) {
+        admitted.push(entries[0]);
+        continue;
+      }
+      diagnostics.push(
+        ExtractionDiagnostic.create({
+          code: "duplicate-node-id",
+          nodeId: entries[0].id,
+          payload: {
+            candidates: entries.length,
+            candidateFacts: entries
+              .map((entry) => this.deps.serializer.stringify(entry.toCanonicalValue()))
+              .sort(compareStrings),
+            nodeId,
+          },
+        }),
+      );
+    }
+    return admitted;
+  }
+
+  private admitEdges(
+    candidates: readonly Edge[],
+    nodeIds: ReadonlySet<string>,
+    diagnostics: ExtractionDiagnostic[],
+  ): readonly Edge[] {
+    const unique = new Map<string, Edge>();
+    for (const edge of candidates) {
+      const key = this.deps.serializer.stringify(edge.toCanonicalValue());
+      if (!unique.has(key)) unique.set(key, edge);
+    }
+    const admitted: Edge[] = [];
+    for (const [edgeKey, edge] of [...unique.entries()].sort(([left], [right]) => compareStrings(left, right))) {
+      const missingEndpoints = [edge.from.toString(), edge.to.toString()]
+        .filter((endpoint) => !nodeIds.has(endpoint))
+        .sort(compareStrings);
+      if (missingEndpoints.length === 0) {
+        admitted.push(edge);
+        continue;
+      }
+      diagnostics.push(
+        ExtractionDiagnostic.create({
+          code: "missing-edge-endpoint",
+          payload: { edge: edgeKey, missingEndpoints },
+        }),
+      );
+    }
+    return admitted;
+  }
+}

package/scripts/harness/world-model/application/usecases/derive-obligations-use-case.ts

@@ -0,0 +1,155 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-295, WI-296
+
+import type { CanonicalJsonSerializer } from "../../domain/services/canonical-json-serializer.js";
+import type { ConstraintFindingDto } from "../../domain/services/constraint-evaluator.js";
+import type { ObligationDerivationService } from "../../domain/services/obligation-derivation-service.js";
+import type {
+  PolicyInputsDigestDerivation,
+  PolicyInputsDigestDeriver,
+} from "../../domain/services/policy-inputs-digest-deriver.js";
+import type { SnapshotRootDeriver } from "../../domain/services/snapshot-root-deriver.js";
+import type { Sha256Digest } from "../../domain/value-objects/sha256-digest.js";
+import type { WorldObligationReportDto } from "../dto/world-obligation-report-dto.js";
+import type { ObligationReportWriterPort } from "../ports/obligation-report-writer-port.js";
+import type {
+  AdoptionBaselineRepositoryPort,
+  SemanticDebtRepositoryPort,
+  WaiverDeclarationRepositoryPort,
+  WorldControlDiagnosticDto,
+  WorldControlReadResult,
+} from "../ports/world-control-declaration-repository-port.js";
+
+export interface DeriveObligationsInput {
+  readonly rulesetVersion: string;
+  readonly findings: readonly ConstraintFindingDto[];
+  readonly corpusRoot: Sha256Digest;
+  readonly constraintRoot: Sha256Digest;
+  readonly evaluationConfigDigest: Sha256Digest;
+  readonly policyAsOfDate: string | null;
+  readonly writeReport: boolean;
+  readonly reportPath?: string;
+}
+
+export type ReportPersistenceResult =
+  | { readonly state: "not-requested" }
+  | { readonly state: "written" }
+  | { readonly state: "failed"; readonly message: string };
+
+export type DeriveObligationsResult =
+  | {
+      readonly status: "derived";
+      readonly report: WorldObligationReportDto;
+      readonly canonicalBytes: Uint8Array;
+      readonly persistence: ReportPersistenceResult;
+    }
+  | {
+      readonly status: "invalid-policy-input";
+      readonly diagnostics: readonly WorldControlDiagnosticDto[];
+    };
+
+interface Dependencies {
+  readonly baselineRepository: AdoptionBaselineRepositoryPort;
+  readonly waiverRepository: WaiverDeclarationRepositoryPort;
+  readonly semanticDebtRepository: SemanticDebtRepositoryPort;
+  readonly policyInputsDigestDeriver: PolicyInputsDigestDeriver;
+  readonly evaluationIdDeriver: SnapshotRootDeriver;
+  readonly obligationDerivationService: ObligationDerivationService;
+  readonly serializer: CanonicalJsonSerializer;
+  readonly writer: ObligationReportWriterPort;
+}
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const diagnosticsOf = <T>(result: WorldControlReadResult<T>): readonly WorldControlDiagnosticDto[] =>
+  result.state === "invalid" ? result.diagnostics : [];
+
+export class DeriveObligationsUseCase {
+  constructor(private readonly dependencies: Dependencies) {}
+
+  async execute(input: DeriveObligationsInput): Promise<DeriveObligationsResult> {
+    const [baselineResult, waiverResult, debtResult] = await Promise.all([
+      this.dependencies.baselineRepository.load(),
+      this.dependencies.waiverRepository.load(),
+      this.dependencies.semanticDebtRepository.load(),
+    ]);
+    const diagnostics = [
+      ...diagnosticsOf(baselineResult),
+      ...diagnosticsOf(waiverResult),
+      ...diagnosticsOf(debtResult),
+    ].sort(
+      (left, right) =>
+        compareStrings(left.code, right.code) ||
+        compareStrings(left.path, right.path) ||
+        compareStrings(left.locator ?? "", right.locator ?? ""),
+    );
+    if (baselineResult.state === "invalid" || waiverResult.state === "invalid" || debtResult.state === "invalid") {
+      return Object.freeze({
+        status: "invalid-policy-input",
+        diagnostics: Object.freeze(diagnostics),
+      });
+    }
+
+    let policy: PolicyInputsDigestDerivation;
+    try {
+      policy = this.dependencies.policyInputsDigestDeriver.derive({
+        baseline: baselineResult.value,
+        waivers: waiverResult.value,
+        semanticDebts: debtResult.value,
+        policyAsOfDate: input.policyAsOfDate,
+      });
+    } catch (error) {
+      return Object.freeze({
+        status: "invalid-policy-input",
+        diagnostics: Object.freeze([
+          {
+            code: "invalid-policy-as-of-date",
+            path: "world.policyAsOfDate",
+            locator: null,
+            message: error instanceof Error ? error.message : String(error),
+          },
+        ]),
+      });
+    }
+    const evaluation = this.dependencies.evaluationIdDeriver.deriveEvaluationId({
+      schemaVersion: "phasegate-world-evaluation/v1",
+      rulesetVersion: input.rulesetVersion,
+      corpusRoot: input.corpusRoot,
+      constraintRoot: input.constraintRoot,
+      evaluationConfigDigest: input.evaluationConfigDigest,
+      policyInputsDigest: policy.digest,
+    });
+    const report: WorldObligationReportDto = this.dependencies.obligationDerivationService.derive({
+      evaluationId: evaluation.evaluationId,
+      rulesetVersion: input.rulesetVersion,
+      policyInputsDigest: policy.digest,
+      findings: input.findings,
+      baseline: baselineResult.value,
+      waivers: waiverResult.value,
+      semanticDebts: debtResult.value,
+      policyAsOfDate: policy.resolvedPolicyAsOfDate,
+    });
+    const canonicalBytes = this.dependencies.serializer.serialize(report);
+    let persistence: ReportPersistenceResult = Object.freeze({
+      state: "not-requested",
+    });
+    if (input.writeReport) {
+      try {
+        await this.dependencies.writer.write(canonicalBytes, input.reportPath);
+        persistence = Object.freeze({ state: "written" });
+      } catch (error) {
+        persistence = Object.freeze({
+          state: "failed",
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    return Object.freeze({
+      status: "derived",
+      report,
+      canonicalBytes,
+      persistence,
+    });
+  }
+}