phasegate 0.229.0 → 0.254.0

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,
+    });
+  }
+}

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

@@ -0,0 +1,144 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-296, WI-297
+
+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;
+}
+
+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("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 };
+  }
+}