phasegate 0.229.0 → 0.264.0

package/scripts/harness/world-model/domain/services/policy-inputs-digest-deriver.ts

@@ -0,0 +1,66 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-295
+
+import type { AdoptionBaseline, SemanticDebtDeclaration, WorldWaiver } from "../entities/control-declarations.js";
+import type { WorldHashingPort } from "../ports/world-hashing-port.js";
+import type { Sha256Digest } from "../value-objects/sha256-digest.js";
+import type { CanonicalJsonObject, CanonicalJsonSerializer } from "./canonical-json-serializer.js";
+
+export interface PolicyInputsDigestInput {
+  readonly baseline: AdoptionBaseline | null;
+  readonly waivers: readonly WorldWaiver[];
+  readonly semanticDebts: readonly SemanticDebtDeclaration[];
+  readonly policyAsOfDate: string | null;
+}
+
+export interface PolicyInputsDigestDerivation {
+  readonly digest: Sha256Digest;
+  readonly preimage: CanonicalJsonObject;
+  readonly canonicalBytes: Uint8Array;
+  readonly resolvedPolicyAsOfDate: string | null;
+}
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const requireCalendarDate = (value: string | null): string => {
+  if (value === null) throw new Error("policyAsOfDate is required when waivers exist");
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) throw new Error("policyAsOfDate must be YYYY-MM-DD");
+  const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+  if (
+    date.getUTCFullYear() !== Number(match[1]) ||
+    date.getUTCMonth() !== Number(match[2]) - 1 ||
+    date.getUTCDate() !== Number(match[3])
+  ) {
+    throw new Error("policyAsOfDate must be a valid calendar date");
+  }
+  return value;
+};
+
+export class PolicyInputsDigestDeriver {
+  constructor(
+    private readonly serializer: CanonicalJsonSerializer,
+    private readonly hashingPort: WorldHashingPort,
+  ) {}
+
+  derive(input: PolicyInputsDigestInput): PolicyInputsDigestDerivation {
+    const waivers = [...input.waivers].sort((left, right) => compareStrings(left.waiverId, right.waiverId));
+    const semanticDebts = [...input.semanticDebts].sort((left, right) => compareStrings(left.debtId, right.debtId));
+    const resolvedPolicyAsOfDate = waivers.length === 0 ? null : requireCalendarDate(input.policyAsOfDate);
+    const preimage: CanonicalJsonObject = {
+      schemaVersion: "phasegate-world-policy-inputs/v1",
+      adoptionBaseline: input.baseline?.toCanonicalValue() ?? null,
+      waivers: waivers.map((waiver) => waiver.toCanonicalValue()),
+      semanticDebts: semanticDebts.map((debt) => debt.toCanonicalValue()),
+      policyAsOfDate: resolvedPolicyAsOfDate,
+    };
+    const canonicalBytes = this.serializer.serialize(preimage);
+    return Object.freeze({
+      digest: this.hashingPort.sha256(canonicalBytes),
+      preimage: Object.freeze(preimage),
+      canonicalBytes,
+      resolvedPolicyAsOfDate,
+    });
+  }
+}

package/scripts/harness/world-model/domain/services/snapshot-root-deriver.ts

@@ -0,0 +1,218 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+import type { Edge } from "../entities/edge.js";
+import type { ExtractionDiagnostic } from "../entities/extraction-diagnostic.js";
+import { Snapshot } from "../entities/snapshot.js";
+import type { WorldNode } from "../entities/world-node.js";
+import type { WorldHashingPort } from "../ports/world-hashing-port.js";
+import { EvaluationId } from "../value-objects/evaluation-id.js";
+import type { Sha256Digest } from "../value-objects/sha256-digest.js";
+import type { WorldNodeId } from "../value-objects/world-node-id.js";
+import type { CanonicalJsonObject, CanonicalJsonSerializer } from "./canonical-json-serializer.js";
+
+export interface CorpusRootInput {
+  readonly schemaVersion: string;
+  readonly extractorVersion: string;
+  readonly corpusConfigDigest: Sha256Digest;
+  readonly nodes: readonly WorldNode[];
+  readonly edges: readonly Edge[];
+  readonly extractionDiagnostics: readonly ExtractionDiagnostic[];
+}
+
+export interface CanonicalDeclaration {
+  readonly id: WorldNodeId;
+  readonly value: CanonicalJsonObject;
+}
+
+export interface ConstraintRootInput {
+  readonly schemaVersion: string;
+  readonly rulesetVersion: string;
+  readonly constraintConfigDigest: Sha256Digest;
+  readonly constraints: readonly CanonicalDeclaration[];
+  readonly explicitClaims: readonly CanonicalDeclaration[];
+  readonly aliases: readonly CanonicalDeclaration[];
+  readonly declarationDiagnostics: readonly ExtractionDiagnostic[];
+}
+
+export interface EvaluationIdInput {
+  readonly schemaVersion: string;
+  readonly rulesetVersion: string;
+  readonly corpusRoot: Sha256Digest;
+  readonly constraintRoot: Sha256Digest;
+  readonly evaluationConfigDigest: Sha256Digest;
+  readonly policyInputsDigest: Sha256Digest;
+}
+
+export interface RootDerivation {
+  readonly root: Sha256Digest;
+  readonly canonicalBytes: Uint8Array;
+}
+
+export interface EvaluationIdDerivation {
+  readonly evaluationId: EvaluationId;
+  readonly canonicalBytes: Uint8Array;
+}
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const compareTuples = (left: readonly string[], right: readonly string[]): number => {
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const compared = compareStrings(left[index] ?? "", right[index] ?? "");
+    if (compared !== 0) {
+      return compared;
+    }
+  }
+  return 0;
+};
+
+const assertVersion = (name: string, value: string): void => {
+  if (value.trim().length === 0) {
+    throw new Error(`${name} must not be empty`);
+  }
+};
+
+export class SnapshotRootDeriver {
+  constructor(
+    private readonly serializer: CanonicalJsonSerializer,
+    private readonly hashingPort: WorldHashingPort,
+  ) {}
+
+  private sortedNodes(input: readonly WorldNode[]): readonly WorldNode[] {
+    return [...input].sort((left, right) => compareStrings(left.id.toString(), right.id.toString()));
+  }
+
+  private sortedEdges(input: readonly Edge[]): readonly Edge[] {
+    return [...input].sort((left, right) =>
+      compareTuples(
+        [left.edgeType.toString(), left.from.toString(), left.to.toString(), this.serializer.stringify(left.qualifier)],
+        [
+          right.edgeType.toString(),
+          right.from.toString(),
+          right.to.toString(),
+          this.serializer.stringify(right.qualifier),
+        ],
+      ),
+    );
+  }
+
+  private sortedDiagnostics(input: readonly ExtractionDiagnostic[]): readonly ExtractionDiagnostic[] {
+    return [...input].sort((left, right) =>
+      compareTuples(
+        [
+          left.code,
+          left.nodeId?.toString() ?? "",
+          left.path?.toString() ?? "",
+          String(left.line ?? 0).padStart(10, "0"),
+          this.serializer.stringify(left.payload),
+        ],
+        [
+          right.code,
+          right.nodeId?.toString() ?? "",
+          right.path?.toString() ?? "",
+          String(right.line ?? 0).padStart(10, "0"),
+          this.serializer.stringify(right.payload),
+        ],
+      ),
+    );
+  }
+
+  private corpusProjection(input: CorpusRootInput): {
+    readonly nodes: readonly WorldNode[];
+    readonly edges: readonly Edge[];
+    readonly diagnostics: readonly ExtractionDiagnostic[];
+    readonly value: CanonicalJsonObject;
+  } {
+    assertVersion("schemaVersion", input.schemaVersion);
+    assertVersion("extractorVersion", input.extractorVersion);
+    const nodes = this.sortedNodes(input.nodes);
+    const edges = this.sortedEdges(input.edges);
+    const diagnostics = this.sortedDiagnostics(input.extractionDiagnostics);
+    return {
+      nodes,
+      edges,
+      diagnostics,
+      value: {
+        corpusConfigDigest: input.corpusConfigDigest.toString(),
+        edges: edges.map((edge) => edge.toCanonicalValue()),
+        extractionDiagnostics: diagnostics.map((diagnostic) => diagnostic.toCanonicalValue()),
+        extractorVersion: input.extractorVersion,
+        nodes: nodes.map((node) => node.toCanonicalValue()),
+        schemaVersion: input.schemaVersion,
+      },
+    };
+  }
+
+  deriveCorpusRoot(input: CorpusRootInput): RootDerivation {
+    const projection = this.corpusProjection(input);
+    const canonicalBytes = this.serializer.serialize(projection.value);
+    return Object.freeze({
+      root: this.hashingPort.sha256(canonicalBytes),
+      canonicalBytes,
+    });
+  }
+
+  buildSnapshot(input: CorpusRootInput): Snapshot {
+    const projection = this.corpusProjection(input);
+    const canonicalBytes = this.serializer.serialize(projection.value);
+    const corpusRoot = this.hashingPort.sha256(canonicalBytes);
+    return Snapshot.create({
+      schemaVersion: input.schemaVersion,
+      extractorVersion: input.extractorVersion,
+      corpusConfigDigest: input.corpusConfigDigest,
+      nodes: projection.nodes,
+      edges: projection.edges,
+      extractionDiagnostics: projection.diagnostics,
+      corpusRoot,
+      canonicalBytes,
+    });
+  }
+
+  private sortedDeclarations(declarations: readonly CanonicalDeclaration[]): readonly CanonicalDeclaration[] {
+    return [...declarations].sort((left, right) => compareStrings(left.id.toString(), right.id.toString()));
+  }
+
+  deriveConstraintRoot(input: ConstraintRootInput): RootDerivation {
+    assertVersion("schemaVersion", input.schemaVersion);
+    assertVersion("rulesetVersion", input.rulesetVersion);
+    const toValue = (declaration: CanonicalDeclaration): CanonicalJsonObject => ({
+      id: declaration.id.toString(),
+      value: declaration.value,
+    });
+    const projection: CanonicalJsonObject = {
+      aliases: this.sortedDeclarations(input.aliases).map(toValue),
+      constraintConfigDigest: input.constraintConfigDigest.toString(),
+      constraints: this.sortedDeclarations(input.constraints).map(toValue),
+      declarationDiagnostics: this.sortedDiagnostics(input.declarationDiagnostics).map((diagnostic) =>
+        diagnostic.toCanonicalValue(),
+      ),
+      explicitClaims: this.sortedDeclarations(input.explicitClaims).map(toValue),
+      rulesetVersion: input.rulesetVersion,
+      schemaVersion: input.schemaVersion,
+    };
+    const canonicalBytes = this.serializer.serialize(projection);
+    return Object.freeze({
+      root: this.hashingPort.sha256(canonicalBytes),
+      canonicalBytes,
+    });
+  }
+
+  deriveEvaluationId(input: EvaluationIdInput): EvaluationIdDerivation {
+    assertVersion("schemaVersion", input.schemaVersion);
+    assertVersion("rulesetVersion", input.rulesetVersion);
+    const projection: CanonicalJsonObject = {
+      constraintRoot: input.constraintRoot.toString(),
+      corpusRoot: input.corpusRoot.toString(),
+      evaluationConfigDigest: input.evaluationConfigDigest.toString(),
+      policyInputsDigest: input.policyInputsDigest.toString(),
+      rulesetVersion: input.rulesetVersion,
+      schemaVersion: input.schemaVersion,
+    };
+    const canonicalBytes = this.serializer.serialize(projection);
+    return Object.freeze({
+      evaluationId: EvaluationId.fromDigest(this.hashingPort.sha256(canonicalBytes)),
+      canonicalBytes,
+    });
+  }
+}

package/scripts/harness/world-model/domain/services/text-content-normalizer.ts

@@ -0,0 +1,30 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+import { ExtractionDiagnostic } from "../entities/extraction-diagnostic.js";
+
+export type TextNormalizationResult =
+  | { readonly ok: true; readonly text: string; readonly bytes: Uint8Array }
+  | { readonly ok: false; readonly diagnostic: ExtractionDiagnostic };
+
+export class TextContentNormalizer {
+  normalize(bytes: Uint8Array): TextNormalizationResult {
+    try {
+      const decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+      const text = decoded.replace(/\r\n?/g, "\n");
+      return Object.freeze({
+        ok: true,
+        text,
+        bytes: new TextEncoder().encode(text),
+      });
+    } catch {
+      return Object.freeze({
+        ok: false,
+        diagnostic: ExtractionDiagnostic.create({
+          code: "invalid-utf8",
+          payload: { byteLength: bytes.byteLength },
+        }),
+      });
+    }
+  }
+}

package/scripts/harness/world-model/domain/services/violation-fingerprint-deriver.ts

@@ -0,0 +1,183 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-295, WI-296
+
+import type { WorldHashingPort } from "../ports/world-hashing-port.js";
+import { ViolationFingerprint } from "../value-objects/violation-fingerprint.js";
+import type { CanonicalJsonObject, CanonicalJsonSerializer } from "./canonical-json-serializer.js";
+import type { ConstraintFindingDto, EndpointResolutionDto } from "./constraint-evaluator.js";
+
+export interface ViolationFingerprintDerivation {
+  readonly fingerprint: ViolationFingerprint;
+  readonly preimage: CanonicalJsonObject;
+  readonly canonicalBytes: Uint8Array;
+}
+
+const pinOf = (endpoint: EndpointResolutionDto | null): CanonicalJsonObject | null =>
+  endpoint === null ? null : { nodeId: endpoint.declaredNodeId, contentDigest: endpoint.pinnedDigest };
+
+const subjectRole = (finding: ConstraintFindingDto): "claimant" | "premise" | "both" | "declaration" | "global" => {
+  if (finding.endpoint !== null) return finding.endpoint;
+  if (finding.ruleId === "WCR-001") return "declaration";
+  if (
+    finding.ruleId === "WCR-006" ||
+    finding.ruleId === "WCR-007" ||
+    (finding.ruleId === "WCR-008" && finding.factType === "content-equals")
+  ) {
+    return "both";
+  }
+  return "global";
+};
+
+const subjectOf = (finding: ConstraintFindingDto): CanonicalJsonObject => {
+  const endpointRole = subjectRole(finding);
+  const globalNodeId =
+    endpointRole === "global" && typeof finding.evidence.nodeId === "string" ? finding.evidence.nodeId : undefined;
+  const ids =
+    endpointRole === "claimant"
+      ? [finding.claimant?.declaredNodeId]
+      : endpointRole === "premise"
+        ? [finding.premise?.declaredNodeId]
+        : endpointRole === "both" || endpointRole === "global"
+          ? [globalNodeId, finding.claimant?.declaredNodeId, finding.premise?.declaredNodeId]
+          : [];
+  return {
+    endpointRole,
+    nodeIds: [...new Set(ids.filter((value): value is string => value !== undefined))].sort(),
+  };
+};
+
+const endpointFor = (finding: ConstraintFindingDto): EndpointResolutionDto | null =>
+  finding.endpoint === "claimant" ? finding.claimant : finding.endpoint === "premise" ? finding.premise : null;
+
+const expectedObserved = (
+  finding: ConstraintFindingDto,
+): { readonly expected: CanonicalJsonObject; readonly observed: CanonicalJsonObject } => {
+  const endpoint = endpointFor(finding);
+  switch (finding.ruleId) {
+    case "WCR-001":
+      return {
+        expected: { declarationAdmission: "well-formed" },
+        observed: {
+          declaredConstraintId:
+            typeof finding.evidence.declaredConstraintId === "string" ? finding.evidence.declaredConstraintId : null,
+        },
+      };
+    case "WCR-002":
+    case "WCR-003":
+      return {
+        expected: {
+          contentDigest: endpoint?.pinnedDigest ?? null,
+          nodeId: endpoint?.declaredNodeId ?? null,
+          presence: "resolved",
+        },
+        observed: {
+          baselineCandidateCount:
+            typeof finding.evidence.baselineCandidateCount === "number"
+              ? finding.evidence.baselineCandidateCount
+              : null,
+          candidateCount: endpoint?.candidateCount ?? 0,
+          currentDigest: endpoint?.currentDigest ?? null,
+          status: endpoint?.status ?? "missing",
+        },
+      };
+    case "WCR-004":
+      return {
+        expected: { aliasResolution: "single-hop-resolved" },
+        observed: {
+          aliasCount: typeof finding.evidence.aliasCount === "number" ? finding.evidence.aliasCount : null,
+          aliasTarget: typeof finding.evidence.aliasTarget === "string" ? finding.evidence.aliasTarget : null,
+          aliasTargets: Array.isArray(finding.evidence.aliasTargets) ? [...finding.evidence.aliasTargets].sort() : [],
+          resolutionStatus: endpoint?.status ?? "invalid-alias",
+          targetCandidateCount:
+            typeof finding.evidence.targetCandidateCount === "number" ? finding.evidence.targetCandidateCount : null,
+        },
+      };
+    case "WCR-005":
+      return {
+        expected: {
+          candidateCount: 1,
+          nodeId:
+            endpoint?.declaredNodeId ?? (typeof finding.evidence.nodeId === "string" ? finding.evidence.nodeId : null),
+        },
+        observed: {
+          candidateContentDigests:
+            endpoint !== null
+              ? [...endpoint.candidateContentDigests].sort()
+              : Array.isArray(finding.evidence.candidateContentDigests)
+                ? finding.evidence.candidateContentDigests
+                    .filter((value): value is string => typeof value === "string")
+                    .sort()
+                : [],
+          candidateCount:
+            endpoint?.candidateCount ??
+            (typeof finding.evidence.candidateCount === "number" ? finding.evidence.candidateCount : 0),
+          resolution: typeof finding.evidence.resolution === "string" ? finding.evidence.resolution : null,
+        },
+      };
+    case "WCR-006":
+    case "WCR-007":
+      return {
+        expected: {
+          claimantNodeId: finding.claimant?.declaredNodeId ?? null,
+          factType: finding.factType,
+          premiseNodeId: finding.premise?.declaredNodeId ?? null,
+          relationSource: "constraint-declaration",
+        },
+        observed: { relationPresent: false },
+      };
+    case "WCR-008":
+      if (finding.endpoint !== null) {
+        return {
+          expected: {
+            contentDigest: endpoint?.pinnedDigest ?? null,
+            nodeId: endpoint?.declaredNodeId ?? null,
+          },
+          observed: {
+            contentDigest: endpoint?.currentDigest ?? null,
+            resolvedNodeId: endpoint?.resolvedNodeId ?? null,
+          },
+        };
+      }
+      return {
+        expected: { relation: "current endpoint digests are equal" },
+        observed: {
+          claimantDigest: finding.claimant?.currentDigest ?? null,
+          premiseDigest: finding.premise?.currentDigest ?? null,
+        },
+      };
+    default:
+      return { expected: {}, observed: {} };
+  }
+};
+
+export class ViolationFingerprintDeriver {
+  constructor(
+    private readonly serializer: CanonicalJsonSerializer,
+    private readonly hashingPort: WorldHashingPort,
+  ) {}
+
+  derive(finding: ConstraintFindingDto, rulesetVersion: string): ViolationFingerprintDerivation {
+    if (rulesetVersion.trim().length === 0) throw new Error("rulesetVersion must be non-empty");
+    const evidence = expectedObserved(finding);
+    const preimage: CanonicalJsonObject = {
+      schemaVersion: "phasegate-world-violation-fingerprint/v1",
+      rulesetVersion,
+      ruleId: finding.ruleId,
+      constraintId: finding.constraintId,
+      factType: finding.factType,
+      subject: subjectOf(finding),
+      claimantPin: pinOf(finding.claimant),
+      premisePin: pinOf(finding.premise),
+      expected: evidence.expected,
+      observed: evidence.observed,
+    };
+    const canonicalBytes = this.serializer.serialize(preimage);
+    const digest = this.hashingPort.sha256(canonicalBytes);
+    return Object.freeze({
+      fingerprint: ViolationFingerprint.create(`pgw:v1:violation-fingerprint:${digest.toString()}`),
+      preimage: Object.freeze(preimage),
+      canonicalBytes,
+    });
+  }
+}

package/scripts/harness/world-model/domain/value-objects/artifact-kind.ts

@@ -0,0 +1,58 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+export type ArtifactKindValue = "design-document" | "source" | "generated-artifact" | "external-declaration";
+
+const VALUES: readonly ArtifactKindValue[] = [
+  "design-document",
+  "source",
+  "generated-artifact",
+  "external-declaration",
+];
+
+export class InvalidArtifactKindError extends Error {
+  constructor(value: string) {
+    super(`Invalid World artifact kind: "${value}"`);
+    this.name = "InvalidArtifactKindError";
+  }
+}
+
+export class ArtifactKind {
+  readonly value: ArtifactKindValue;
+
+  private constructor(value: ArtifactKindValue) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static parse(value: string): ArtifactKind {
+    if (!VALUES.includes(value as ArtifactKindValue)) {
+      throw new InvalidArtifactKindError(value);
+    }
+    return new ArtifactKind(value as ArtifactKindValue);
+  }
+
+  static designDocument(): ArtifactKind {
+    return new ArtifactKind("design-document");
+  }
+
+  static source(): ArtifactKind {
+    return new ArtifactKind("source");
+  }
+
+  static generatedArtifact(): ArtifactKind {
+    return new ArtifactKind("generated-artifact");
+  }
+
+  static externalDeclaration(): ArtifactKind {
+    return new ArtifactKind("external-declaration");
+  }
+
+  equals(other: ArtifactKind): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}

package/scripts/harness/world-model/domain/value-objects/change-provenance.ts

@@ -0,0 +1,137 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-293
+
+import type { Snapshot } from "../entities/snapshot.js";
+import type { WorldNode } from "../entities/world-node.js";
+import type { CanonicalJsonObject } from "../services/canonical-json-serializer.js";
+import type { Sha256Digest } from "./sha256-digest.js";
+import type { WorldNodeId } from "./world-node-id.js";
+
+export type ChangedCandidateKind = "added" | "removed" | "modified" | "candidate-cardinality-changed";
+
+export interface ChangedCandidate {
+  readonly nodeId: WorldNodeId;
+  readonly changeKind: ChangedCandidateKind;
+  readonly baselineDigest: Sha256Digest | null;
+  readonly currentDigest: Sha256Digest | null;
+  readonly baselineLocators: readonly string[];
+  readonly currentLocators: readonly string[];
+}
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const locatorFor = (node: WorldNode): string => {
+  if (node.projection.type === "artifact" || node.projection.type === "source-file") {
+    return node.projection.pathKey;
+  }
+  if (node.projection.type === "fragment") {
+    return node.projection.artifactId;
+  }
+  return node.id.toString();
+};
+
+const groupNodes = (nodes: readonly WorldNode[]): Map<string, readonly WorldNode[]> => {
+  const mutable = new Map<string, WorldNode[]>();
+  for (const node of nodes) {
+    const key = node.id.toString();
+    const current = mutable.get(key) ?? [];
+    current.push(node);
+    mutable.set(key, current);
+  }
+  return new Map(
+    [...mutable].map(([key, values]) => [
+      key,
+      Object.freeze(
+        [...values].sort((left, right) =>
+          compareStrings(
+            `${left.contentDigest.toString()}\0${locatorFor(left)}`,
+            `${right.contentDigest.toString()}\0${locatorFor(right)}`,
+          ),
+        ),
+      ),
+    ]),
+  );
+};
+
+const signature = (nodes: readonly WorldNode[]): string =>
+  nodes.map((node) => `${node.contentDigest.toString()}\0${locatorFor(node)}`).join("\u0001");
+
+const candidateFor = (
+  nodeId: WorldNodeId,
+  baselineNodes: readonly WorldNode[],
+  currentNodes: readonly WorldNode[],
+): ChangedCandidate | null => {
+  let changeKind: ChangedCandidateKind;
+  if (baselineNodes.length === 0) {
+    changeKind = "added";
+  } else if (currentNodes.length === 0) {
+    changeKind = "removed";
+  } else if (baselineNodes.length !== currentNodes.length) {
+    changeKind = "candidate-cardinality-changed";
+  } else if (signature(baselineNodes) !== signature(currentNodes)) {
+    changeKind = "modified";
+  } else {
+    return null;
+  }
+  return Object.freeze({
+    nodeId,
+    changeKind,
+    baselineDigest: baselineNodes.length === 1 ? baselineNodes[0].contentDigest : null,
+    currentDigest: currentNodes.length === 1 ? currentNodes[0].contentDigest : null,
+    baselineLocators: Object.freeze([...new Set(baselineNodes.map(locatorFor))].sort(compareStrings)),
+    currentLocators: Object.freeze([...new Set(currentNodes.map(locatorFor))].sort(compareStrings)),
+  });
+};
+
+export class ChangeProvenance {
+  readonly baselineSnapshotId: WorldNodeId | null;
+  readonly baselineCorpusRoot: Sha256Digest | null;
+  readonly currentSnapshotId: WorldNodeId;
+  readonly currentCorpusRoot: Sha256Digest;
+  readonly changedCandidates: readonly ChangedCandidate[];
+
+  private constructor(
+    baselineSnapshot: Snapshot | null,
+    currentSnapshot: Snapshot,
+    changedCandidates: readonly ChangedCandidate[],
+  ) {
+    this.baselineSnapshotId = baselineSnapshot?.id ?? null;
+    this.baselineCorpusRoot = baselineSnapshot?.corpusRoot ?? null;
+    this.currentSnapshotId = currentSnapshot.id;
+    this.currentCorpusRoot = currentSnapshot.corpusRoot;
+    this.changedCandidates = changedCandidates;
+    Object.freeze(this);
+  }
+
+  static between(baselineSnapshot: Snapshot | null, currentSnapshot: Snapshot): ChangeProvenance {
+    const baselineGroups = groupNodes(baselineSnapshot?.nodes ?? []);
+    const currentGroups = groupNodes(currentSnapshot.nodes);
+    const ids = [...new Set([...baselineGroups.keys(), ...currentGroups.keys()])].sort(compareStrings);
+    const changedCandidates = ids.flatMap((id) => {
+      const baselineNodes = baselineGroups.get(id) ?? [];
+      const currentNodes = currentGroups.get(id) ?? [];
+      const sample = currentNodes[0] ?? baselineNodes[0];
+      const candidate = candidateFor(sample.id, baselineNodes, currentNodes);
+      return candidate === null ? [] : [candidate];
+    });
+    return new ChangeProvenance(baselineSnapshot, currentSnapshot, Object.freeze(changedCandidates));
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      baselineCorpusRoot: this.baselineCorpusRoot?.toString() ?? null,
+      baselineSnapshotId: this.baselineSnapshotId?.toString() ?? null,
+      changedCandidates: this.changedCandidates.map((candidate) => ({
+        baselineDigest: candidate.baselineDigest?.toString() ?? null,
+        baselineLocators: candidate.baselineLocators,
+        changeKind: candidate.changeKind,
+        currentDigest: candidate.currentDigest?.toString() ?? null,
+        currentLocators: candidate.currentLocators,
+        nodeId: candidate.nodeId.toString(),
+      })),
+      currentCorpusRoot: this.currentCorpusRoot.toString(),
+      currentSnapshotId: this.currentSnapshotId.toString(),
+    };
+  }
+}