phasegate 0.229.0 → 0.264.0

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

@@ -0,0 +1,146 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-296, WI-297
+// @work-item-id WI-300
+
+import { ExtractionDiagnostic } from "../../domain/entities/extraction-diagnostic.js";
+import type { Snapshot } from "../../domain/entities/snapshot.js";
+import { ConstraintEvaluator, type ConstraintFindingDto } from "../../domain/services/constraint-evaluator.js";
+import type { SnapshotRootDeriver } from "../../domain/services/snapshot-root-deriver.js";
+import { ChangeProvenance } from "../../domain/value-objects/change-provenance.js";
+import { PathKey } from "../../domain/value-objects/path-key.js";
+import type { Sha256Digest } from "../../domain/value-objects/sha256-digest.js";
+import type {
+  ConstraintDeclarationRepositoryPort,
+  WorldControlDiagnosticDto,
+} from "../ports/world-control-declaration-repository-port.js";
+import type { BuildSnapshotContract } from "./build-snapshot-use-case.js";
+import type { DeriveObligationsResult, DeriveObligationsUseCase } from "./derive-obligations-use-case.js";
+
+export interface PolicyDatePort {
+  currentUtcDate(): string;
+}
+
+export type DeriveWorldObligationsResult =
+  | { readonly status: "derived"; readonly result: Extract<DeriveObligationsResult, { status: "derived" }> }
+  | { readonly status: "execution-failure"; readonly diagnostics: readonly WorldControlDiagnosticDto[] };
+
+export interface DeriveWorldObligationsInput {
+  readonly writeReport: boolean;
+  readonly reportPath?: string;
+  readonly baselineSnapshot?: Snapshot;
+}
+
+interface Dependencies {
+  readonly buildSnapshot: BuildSnapshotContract;
+  readonly constraintRepository: ConstraintDeclarationRepositoryPort;
+  readonly rootDeriver: SnapshotRootDeriver;
+  readonly deriveObligations: DeriveObligationsUseCase;
+  readonly policyDate: PolicyDatePort;
+  readonly constraintConfigDigest: Sha256Digest;
+  readonly evaluationConfigDigest: Sha256Digest;
+  readonly constraintPath?: string;
+}
+
+const RULESET_VERSION = "phasegate-world-wcr/v1";
+
+export class DeriveWorldObligationsUseCase {
+  constructor(private readonly dependencies: Dependencies) {}
+
+  async execute(input: DeriveWorldObligationsInput): Promise<DeriveWorldObligationsResult> {
+    const [snapshot, constraints] = await Promise.all([
+      this.dependencies.buildSnapshot.execute(),
+      this.dependencies.constraintRepository.load(),
+    ]);
+    if (constraints.state === "invalid") {
+      return { status: "execution-failure", diagnostics: constraints.diagnostics };
+    }
+    const declarationDiagnostics = [
+      ...constraints.value.diagnostics.map((item) =>
+        ExtractionDiagnostic.create({
+          code: item.code,
+          path: PathKey.create(item.path),
+          payload: { locator: item.locator, message: item.message },
+        }),
+      ),
+      ...constraints.value.malformedDeclarations.map((declaration) =>
+        ExtractionDiagnostic.create({
+          code: "malformed-constraint-declaration",
+          path: PathKey.create(this.dependencies.constraintPath ?? "phasegate.world-constraints.json"),
+          payload: declaration.toCanonicalValue(),
+        }),
+      ),
+    ];
+    const constraintRoot = this.dependencies.rootDeriver.deriveConstraintRoot({
+      schemaVersion: constraints.value.schemaVersion,
+      rulesetVersion: RULESET_VERSION,
+      constraintConfigDigest: this.dependencies.constraintConfigDigest,
+      constraints: constraints.value.records.map((record) => ({
+        id: record.constraintId,
+        value: record.toCanonicalValue(),
+      })),
+      explicitClaims: [],
+      aliases: constraints.value.aliases.map((alias) => ({
+        id: alias.from,
+        value: alias.toCanonicalValue(),
+      })),
+      declarationDiagnostics,
+    }).root;
+    const evaluation = new ConstraintEvaluator().evaluateFull({
+      currentSnapshot: snapshot,
+      baselineSnapshot: input.baselineSnapshot,
+      records: constraints.value.records,
+      malformedDeclarations: constraints.value.malformedDeclarations,
+      aliases: constraints.value.aliases,
+      relations: constraints.value.relations,
+      changeProvenance: ChangeProvenance.between(input.baselineSnapshot ?? null, snapshot),
+    });
+    const implicitFindings = snapshot.extractionDiagnostics.flatMap((diagnostic): readonly ConstraintFindingDto[] => {
+      if (diagnostic.code !== "duplicate-node-id" || diagnostic.nodeId === undefined) return [];
+      const facts = Array.isArray(diagnostic.payload.candidateFacts) ? diagnostic.payload.candidateFacts : [];
+      const digests = facts
+        .flatMap((fact) => {
+          if (typeof fact !== "string") return [];
+          try {
+            const parsed = JSON.parse(fact) as { contentDigest?: unknown };
+            return typeof parsed.contentDigest === "string" ? [parsed.contentDigest] : [];
+          } catch {
+            return [];
+          }
+        })
+        .sort();
+      return [
+        {
+          ruleId: "WCR-005",
+          constraintId: null,
+          factType: null,
+          endpoint: null,
+          claimant: null,
+          premise: null,
+          declarationArtifactId: "",
+          declarationLocator: "",
+          evidence: {
+            nodeId: diagnostic.nodeId.toString(),
+            candidateCount:
+              typeof diagnostic.payload.candidates === "number" ? diagnostic.payload.candidates : digests.length,
+            candidateContentDigests: digests,
+            resolution: "global-node-id",
+          },
+        },
+      ];
+    });
+    const result = await this.dependencies.deriveObligations.execute({
+      rulesetVersion: RULESET_VERSION,
+      findings: [...evaluation.findings, ...implicitFindings],
+      corpusRoot: snapshot.corpusRoot,
+      constraintRoot,
+      evaluationConfigDigest: this.dependencies.evaluationConfigDigest,
+      policyAsOfDate: this.dependencies.policyDate.currentUtcDate(),
+      writeReport: input.writeReport,
+      reportPath: input.reportPath,
+    });
+    return result.status === "derived"
+      ? { status: "derived", result }
+      : { status: "execution-failure", diagnostics: result.diagnostics };
+  }
+}

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

@@ -0,0 +1,74 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-291
+
+import type {
+  WorldExtractionDiagnosticDto,
+  WorldInspectionDto,
+  WorldInventoryCountDto,
+  WorldJsonObject,
+} from "../dto/world-inspection-dto.js";
+import type { BuildSnapshotContract } from "./build-snapshot-use-case.js";
+
+export interface InspectWorldContract {
+  execute(): Promise<WorldInspectionDto>;
+}
+
+export interface InspectWorldUseCaseDeps {
+  readonly buildSnapshot: BuildSnapshotContract;
+}
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const countValues = (values: readonly string[]): readonly WorldInventoryCountDto[] => {
+  const counts = new Map<string, number>();
+  for (const value of values) counts.set(value, (counts.get(value) ?? 0) + 1);
+  return [...counts.entries()]
+    .sort(([left], [right]) => compareStrings(left, right))
+    .map(([value, count]) => ({ value, count }));
+};
+
+export class InspectWorldUseCase implements InspectWorldContract {
+  constructor(private readonly deps: InspectWorldUseCaseDeps) {}
+
+  async execute(): Promise<WorldInspectionDto> {
+    const snapshot = await this.deps.buildSnapshot.execute();
+    const nodes = snapshot.nodes
+      .map((node) => node.toCanonicalValue() as WorldJsonObject)
+      .sort((left, right) => compareStrings(String(left.id), String(right.id)));
+    const edges = snapshot.edges
+      .map((edge) => edge.toCanonicalValue() as WorldJsonObject)
+      .sort((left, right) => compareStrings(JSON.stringify(left), JSON.stringify(right)));
+    const diagnostics = snapshot.extractionDiagnostics
+      .map((diagnostic) => diagnostic.toCanonicalValue() as WorldExtractionDiagnosticDto)
+      .sort((left, right) => compareStrings(JSON.stringify(left), JSON.stringify(right)));
+    const artifactNodes = snapshot.nodes.filter((node) => node.projection.type === "artifact");
+    const hardDiagnosticCount = snapshot.extractionDiagnostics.filter(
+      (diagnostic) => diagnostic.code !== "not-present",
+    ).length;
+    return {
+      snapshotId: snapshot.id.toString(),
+      schemaVersion: snapshot.schemaVersion,
+      extractorVersion: snapshot.extractorVersion,
+      corpusRoot: snapshot.corpusRoot.toString(),
+      summary: {
+        nodeCount: nodes.length,
+        edgeCount: edges.length,
+        diagnosticCount: diagnostics.length,
+        hardDiagnosticCount,
+      },
+      inventory: {
+        nodeTypes: countValues(snapshot.nodes.map((node) => node.id.nodeType)),
+        corpusRoles: countValues(
+          artifactNodes.map((node) => (node.projection.type === "artifact" ? node.projection.corpusRole : "")),
+        ),
+        artifactKinds: countValues(
+          artifactNodes.map((node) => (node.projection.type === "artifact" ? node.projection.artifactKind : "")),
+        ),
+      },
+      nodes,
+      edges,
+      diagnostics,
+    };
+  }
+}

package/scripts/harness/world-model/application/usecases/pin-constraint-endpoint-use-case.ts

@@ -0,0 +1,139 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-296
+
+import { ConstraintRecord } from "../../domain/entities/constraint-record.js";
+import type { Snapshot } from "../../domain/entities/snapshot.js";
+import { NodePin } from "../../domain/value-objects/node-pin.js";
+import { WorldNodeId } from "../../domain/value-objects/world-node-id.js";
+import type {
+  ConstraintDeclarationRepositoryPort,
+  ConstraintDeclarationSet,
+  WorldControlDiagnosticDto,
+} from "../ports/world-control-declaration-repository-port.js";
+import type { BuildSnapshotContract } from "./build-snapshot-use-case.js";
+
+export type PinEndpointRole = "claimant" | "premise";
+
+export interface PinConstraintEndpointInput {
+  readonly constraintId: string;
+  readonly endpoint: PinEndpointRole;
+  readonly apply: boolean;
+}
+
+export type PinConstraintEndpointResult =
+  | { readonly status: "preview" | "applied" | "unchanged"; readonly candidate: PinCandidateDto }
+  | { readonly status: "domain-failure"; readonly code: string; readonly message: string }
+  | { readonly status: "execution-failure"; readonly diagnostics: readonly WorldControlDiagnosticDto[] };
+
+export interface PinCandidateDto {
+  readonly constraintId: string;
+  readonly endpoint: PinEndpointRole;
+  readonly nodeId: string;
+  readonly beforeDigest: string;
+  readonly afterDigest: string;
+  readonly changed: boolean;
+}
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const serialize = (set: ConstraintDeclarationSet, replacement: ConstraintRecord): unknown => ({
+  schemaVersion: set.schemaVersion,
+  constraints: set.records
+    .map((record) => (record.constraintId.equals(replacement.constraintId) ? replacement : record))
+    .sort((left, right) => compareStrings(left.constraintId.toString(), right.constraintId.toString()))
+    .map((record) => ({
+      constraintId: record.constraintId.toString(),
+      factType: record.factType,
+      claimant: record.claimant.toCanonicalValue(),
+      premise: record.premise.toCanonicalValue(),
+      applicableRuleIds: record.applicableRuleIds.map((ruleId) => ruleId.toString()),
+    })),
+  aliases: set.aliases
+    .map((alias) => ({ from: alias.from.toString(), to: alias.to.toString() }))
+    .sort((left, right) => compareStrings(left.from, right.from)),
+});
+
+const resolveNode = (snapshot: Snapshot, set: ConstraintDeclarationSet, nodeId: WorldNodeId) => {
+  const duplicate = snapshot.extractionDiagnostics.some(
+    (diagnostic) => diagnostic.code === "duplicate-node-id" && diagnostic.nodeId?.equals(nodeId),
+  );
+  if (duplicate) return { ok: false as const, code: "duplicate-endpoint", message: `duplicate endpoint: ${nodeId}` };
+  const exact = snapshot.nodes.filter((node) => node.id.equals(nodeId));
+  if (exact.length === 1) return { ok: true as const, node: exact[0] };
+  const aliases = set.aliases.filter((alias) => alias.from.equals(nodeId));
+  if (aliases.length !== 1 || set.aliases.some((alias) => alias.from.equals(aliases[0]?.to))) {
+    return {
+      ok: false as const,
+      code: aliases.length === 0 ? "missing-endpoint" : "ambiguous-endpoint-alias",
+      message: `endpoint cannot be resolved uniquely: ${nodeId}`,
+    };
+  }
+  const targets = snapshot.nodes.filter((node) => node.id.equals(aliases[0].to));
+  return targets.length === 1
+    ? { ok: true as const, node: targets[0] }
+    : {
+        ok: false as const,
+        code: targets.length === 0 ? "missing-endpoint" : "duplicate-endpoint",
+        message: `alias target cannot be resolved uniquely: ${aliases[0].to}`,
+      };
+};
+
+export class PinConstraintEndpointUseCase {
+  constructor(
+    private readonly buildSnapshot: BuildSnapshotContract,
+    private readonly repository: ConstraintDeclarationRepositoryPort,
+  ) {}
+
+  async execute(input: PinConstraintEndpointInput): Promise<PinConstraintEndpointResult> {
+    let constraintId: WorldNodeId;
+    try {
+      constraintId = WorldNodeId.parse(input.constraintId);
+      if (constraintId.nodeType !== "constraint") throw new Error("not constraint ID");
+    } catch {
+      return { status: "domain-failure", code: "invalid-constraint-id", message: input.constraintId };
+    }
+    const [snapshot, loaded] = await Promise.all([this.buildSnapshot.execute(), this.repository.load()]);
+    if (loaded.state === "invalid") return { status: "execution-failure", diagnostics: loaded.diagnostics };
+    if (loaded.value.malformedDeclarations.length > 0 || loaded.value.diagnostics.length > 0) {
+      return {
+        status: "domain-failure",
+        code: "malformed-constraint-declaration",
+        message: "constraint declarations contain malformed or ambiguous candidates",
+      };
+    }
+    const records = loaded.value.records.filter((record) => record.constraintId.equals(constraintId));
+    if (records.length !== 1) {
+      return { status: "domain-failure", code: "constraint-not-found", message: input.constraintId };
+    }
+    const record = records[0];
+    const before = input.endpoint === "claimant" ? record.claimant : record.premise;
+    const resolved = resolveNode(snapshot, loaded.value, before.nodeId);
+    if (!resolved.ok) return { status: "domain-failure", code: resolved.code, message: resolved.message };
+    const after = NodePin.create({ nodeId: before.nodeId, contentDigest: resolved.node.contentDigest });
+    const replacement = ConstraintRecord.create({
+      constraintId: record.constraintId,
+      schemaVersion: record.schemaVersion,
+      factType: record.factType,
+      claimant: input.endpoint === "claimant" ? after : record.claimant,
+      premise: input.endpoint === "premise" ? after : record.premise,
+      applicableRuleIds: record.applicableRuleIds,
+      declarationArtifactId: record.declarationArtifactId,
+      declarationLocator: record.declarationLocator,
+    });
+    const candidate = Object.freeze({
+      constraintId: input.constraintId,
+      endpoint: input.endpoint,
+      nodeId: before.nodeId.toString(),
+      beforeDigest: before.contentDigest.toString(),
+      afterDigest: after.contentDigest.toString(),
+      changed: !before.contentDigest.equals(after.contentDigest),
+    });
+    if (!input.apply) return { status: "preview", candidate };
+    if (!candidate.changed) return { status: "unchanged", candidate };
+    const written = await this.repository.replaceAtomically(serialize(loaded.value, replacement));
+    return written.state === "written"
+      ? { status: "applied", candidate }
+      : { status: "execution-failure", diagnostics: written.diagnostics };
+  }
+}

package/scripts/harness/world-model/composition-root.ts

@@ -0,0 +1,247 @@
+// @unit world-model
+// @layer composition
+// @work-item-id WI-291
+// @work-item-id WI-292
+// @work-item-id WI-295
+// @work-item-id WI-296, WI-297
+// @work-item-id WI-300
+// @work-item-id WI-305
+// @work-item-id WI-306
+
+import { createAttestationModule, createSha256Capability } from "../attestation/index.js";
+import { createTraceabilityModelModule } from "../traceability-model/index.js";
+import {
+  resolveWorldCorpusConfig,
+  type WorldResolvedConfigInput,
+} from "./application/dto/world-resolved-config-input.js";
+import { PinnedDesignEndpointFacade } from "./application/facades/pinned-design-endpoint-facade.js";
+import { WorldSnapshotRootFacade } from "./application/facades/world-snapshot-root-facade.js";
+import { BuildSnapshotUseCase } from "./application/usecases/build-snapshot-use-case.js";
+import { DeriveObligationsUseCase } from "./application/usecases/derive-obligations-use-case.js";
+import {
+  DeriveWorldObligationsUseCase,
+  type PolicyDatePort,
+} from "./application/usecases/derive-world-obligations-use-case.js";
+import { InspectWorldUseCase } from "./application/usecases/inspect-world-use-case.js";
+import { PinConstraintEndpointUseCase } from "./application/usecases/pin-constraint-endpoint-use-case.js";
+import { CanonicalJsonSerializer } from "./domain/services/canonical-json-serializer.js";
+import { ObligationDerivationService } from "./domain/services/obligation-derivation-service.js";
+import { PolicyInputsDigestDeriver } from "./domain/services/policy-inputs-digest-deriver.js";
+import { SnapshotRootDeriver } from "./domain/services/snapshot-root-deriver.js";
+import { ViolationFingerprintDeriver } from "./domain/services/violation-fingerprint-deriver.js";
+import { AdrFactExtractor } from "./infrastructure/adapters/adr-fact-extractor.js";
+import { AssembledWorldFactSource } from "./infrastructure/adapters/assembled-world-fact-source.js";
+import {
+  AttestationFactExtractor,
+  AttestationVerificationHandlerAdapter,
+} from "./infrastructure/adapters/attestation-fact-extractor.js";
+import { AttestationSha256WorldHashingAdapter } from "./infrastructure/adapters/attestation-sha256-world-hashing-adapter.js";
+import { CompositeDesignFactSource } from "./infrastructure/adapters/composite-design-fact-source.js";
+import { DesignCorpusFactExtractor } from "./infrastructure/adapters/design-corpus-fact-extractor.js";
+import { FileSystemObligationReportWriterAdapter } from "./infrastructure/adapters/file-system-obligation-report-writer-adapter.js";
+import {
+  FileSystemAdoptionBaselineRepositoryAdapter,
+  FileSystemConstraintDeclarationRepositoryAdapter,
+  FileSystemSemanticDebtRepositoryAdapter,
+  FileSystemWaiverDeclarationRepositoryAdapter,
+} from "./infrastructure/adapters/file-system-world-control-repository-adapters.js";
+import { IntegrityManifestFactExtractor } from "./infrastructure/adapters/integrity-manifest-fact-extractor.js";
+import { MarkdownDesignFactExtractor } from "./infrastructure/adapters/markdown-design-fact-extractor.js";
+import { MatrixFactExtractor } from "./infrastructure/adapters/matrix-fact-extractor.js";
+import { ProductFactExtractor } from "./infrastructure/adapters/product-fact-extractor.js";
+import { ProposalFactExtractor } from "./infrastructure/adapters/proposal-fact-extractor.js";
+import { SourceMetadataFactExtractor } from "./infrastructure/adapters/source-metadata-fact-extractor.js";
+import { TestReferenceSourceFactExtractor } from "./infrastructure/adapters/test-reference-source-fact-extractor.js";
+import { TraceabilityDesignFactAdapter } from "./infrastructure/adapters/traceability-design-fact-adapter.js";
+import { TraceabilityWorldReadFacadeMerger } from "./infrastructure/adapters/traceability-world-read-facade-merger.js";
+import { UnitFactExtractor } from "./infrastructure/adapters/unit-fact-extractor.js";
+import { WorldDeriveCommandHandler } from "./presentation/cli/world-derive-command-handler.js";
+import { WorldInspectCommandHandler } from "./presentation/cli/world-inspect-command-handler.js";
+import { WorldPinCommandHandler } from "./presentation/cli/world-pin-command-handler.js";
+
+const WORLD_SNAPSHOT_SCHEMA_VERSION = "phasegate-world-snapshot/v1";
+const WORLD_EXTRACTOR_VERSION = "phasegate-world-extractor/v2";
+
+export interface WorldModelModuleOptions {
+  readonly rootDir: string;
+  readonly resolvedConfig?: WorldResolvedConfigInput;
+  readonly policyDate?: PolicyDatePort;
+}
+
+export function createWorldModelModule(options: WorldModelModuleOptions) {
+  const config = resolveWorldCorpusConfig(options.resolvedConfig);
+  const hashingPort = new AttestationSha256WorldHashingAdapter(createSha256Capability());
+  const serializer = new CanonicalJsonSerializer();
+  const markdownExtractor = new MarkdownDesignFactExtractor({ hashingPort });
+  const traceabilityFacades = config.productScopes.flatMap((scope) =>
+    config.inceptionRoots.map(
+      (inceptionRoot) =>
+        createTraceabilityModelModule(options.rootDir, {
+          pathRoots: {
+            designDocsRoot: scope.designDocsRoot,
+            inceptionRoot,
+            testRoots: config.sourceRoots.map((sourceRoot) => `${sourceRoot}/__tests__`),
+          },
+        }).worldReadFacade,
+    ),
+  );
+  const designCorpus = new DesignCorpusFactExtractor({
+    traceabilityAdapter: new TraceabilityDesignFactAdapter({
+      facade: new TraceabilityWorldReadFacadeMerger(traceabilityFacades),
+      hashingPort,
+      serializer,
+    }),
+    productExtractor: new CompositeDesignFactSource(
+      config.productScopes.map(
+        (scope) =>
+          new ProductFactExtractor({
+            rootDir: options.rootDir,
+            markdownExtractor,
+            productRoot: scope.productRoot,
+          }),
+      ),
+    ),
+    proposalExtractor: new CompositeDesignFactSource(
+      config.inceptionRoots.map(
+        (inceptionRoot) => new ProposalFactExtractor({ rootDir: options.rootDir, markdownExtractor, inceptionRoot }),
+      ),
+    ),
+    adrExtractor: new CompositeDesignFactSource(
+      config.adrRoots.map((adrRoot) => new AdrFactExtractor({ rootDir: options.rootDir, markdownExtractor, adrRoot })),
+    ),
+    unitExtractor: new CompositeDesignFactSource(
+      config.productScopes.map(
+        (scope) =>
+          new UnitFactExtractor({
+            rootDir: options.rootDir,
+            markdownExtractor,
+            unitRoot: scope.unitRoot,
+          }),
+      ),
+    ),
+  });
+  const attestationModule = createAttestationModule(options.rootDir);
+  const factSource = new AssembledWorldFactSource([
+    designCorpus,
+    ...config.sourceRoots.flatMap((sourceRoot) => [
+      new SourceMetadataFactExtractor({ rootDir: options.rootDir, hashingPort, sourceRoot }),
+      new TestReferenceSourceFactExtractor({ rootDir: options.rootDir, hashingPort, sourceRoot }),
+    ]),
+    new MatrixFactExtractor({
+      rootDir: options.rootDir,
+      hashingPort,
+      matrixPath: config.matrixPath,
+      serializer,
+    }),
+    new AttestationFactExtractor({
+      rootDir: options.rootDir,
+      hashingPort,
+      attestationPath: config.attestationPath,
+      verificationFacade: new AttestationVerificationHandlerAdapter(attestationModule.verifyAttestationHandler),
+      serializer,
+    }),
+    new IntegrityManifestFactExtractor({
+      rootDir: options.rootDir,
+      hashingPort,
+      manifestPath: config.integrityManifestPath,
+      serializer,
+    }),
+  ]);
+  const corpusConfigDigest = hashingPort.sha256(
+    serializer.serialize({
+      schemaVersion: "phasegate-world-corpus-config/v1",
+      productScopes: config.productScopes,
+      inceptionRoots: config.inceptionRoots,
+      adrRoots: config.adrRoots,
+      sourceRoots: config.sourceRoots,
+      include: config.include,
+      exclude: config.exclude,
+      inputs: {
+        matrixPath: config.matrixPath,
+        attestationPath: config.attestationPath,
+        integrityManifestPath: config.integrityManifestPath,
+      },
+    }),
+  );
+  const buildSnapshotUseCase = new BuildSnapshotUseCase({
+    factSource,
+    rootDeriver: new SnapshotRootDeriver(serializer, hashingPort),
+    serializer,
+    schemaVersion: WORLD_SNAPSHOT_SCHEMA_VERSION,
+    extractorVersion: WORLD_EXTRACTOR_VERSION,
+    corpusConfigDigest,
+  });
+  const inspectWorldUseCase = new InspectWorldUseCase({ buildSnapshot: buildSnapshotUseCase });
+  const worldSnapshotRootFacade = new WorldSnapshotRootFacade(buildSnapshotUseCase);
+  const fingerprintDeriver = new ViolationFingerprintDeriver(serializer, hashingPort);
+  const constraintRepository = new FileSystemConstraintDeclarationRepositoryAdapter({
+    rootDir: options.rootDir,
+    fileName: config.constraintsPath,
+  });
+  const rootDeriver = new SnapshotRootDeriver(serializer, hashingPort);
+  const deriveObligationsUseCase = new DeriveObligationsUseCase({
+    baselineRepository: new FileSystemAdoptionBaselineRepositoryAdapter({
+      rootDir: options.rootDir,
+      fileName: config.baselinePath,
+    }),
+    waiverRepository: new FileSystemWaiverDeclarationRepositoryAdapter({
+      rootDir: options.rootDir,
+      fileName: config.waiversPath,
+    }),
+    semanticDebtRepository: new FileSystemSemanticDebtRepositoryAdapter({
+      rootDir: options.rootDir,
+      fileName: config.debtsPath,
+    }),
+    policyInputsDigestDeriver: new PolicyInputsDigestDeriver(serializer, hashingPort),
+    evaluationIdDeriver: new SnapshotRootDeriver(serializer, hashingPort),
+    obligationDerivationService: new ObligationDerivationService(fingerprintDeriver),
+    serializer,
+    writer: new FileSystemObligationReportWriterAdapter({
+      rootDir: options.rootDir,
+      reportPath: config.obligationReportPath,
+    }),
+  });
+  const deriveWorldObligationsUseCase = new DeriveWorldObligationsUseCase({
+    buildSnapshot: buildSnapshotUseCase,
+    constraintRepository,
+    rootDeriver,
+    deriveObligations: deriveObligationsUseCase,
+    policyDate: options.policyDate ?? {
+      currentUtcDate: () => new Date().toISOString().slice(0, 10),
+    },
+    constraintConfigDigest: hashingPort.sha256(
+      serializer.serialize({
+        schemaVersion: "phasegate-world-constraint-config/v1",
+        constraintsPath: config.constraintsPath,
+      }),
+    ),
+    evaluationConfigDigest: hashingPort.sha256(
+      serializer.serialize({
+        schemaVersion: "phasegate-world-evaluation-config/v1",
+        rulesetVersion: "phasegate-world-wcr/v1",
+      }),
+    ),
+    constraintPath: config.constraintsPath,
+  });
+  const pinConstraintEndpointUseCase = new PinConstraintEndpointUseCase(buildSnapshotUseCase, constraintRepository);
+  const pinnedDesignEndpointFacade = new PinnedDesignEndpointFacade(constraintRepository);
+  const worldInspectCommandHandler = new WorldInspectCommandHandler({ inspectWorld: inspectWorldUseCase });
+  const worldPinCommandHandler = new WorldPinCommandHandler(pinConstraintEndpointUseCase);
+  const worldDeriveCommandHandler = new WorldDeriveCommandHandler(
+    deriveWorldObligationsUseCase,
+    config.obligationReportPath,
+  );
+
+  return {
+    buildSnapshotUseCase,
+    deriveObligationsUseCase,
+    deriveWorldObligationsUseCase,
+    inspectWorldUseCase,
+    pinConstraintEndpointUseCase,
+    pinnedDesignEndpointFacade,
+    worldDeriveCommandHandler,
+    worldInspectCommandHandler,
+    worldSnapshotRootFacade,
+    worldPinCommandHandler,
+  } as const;
+}