android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/validation/semantic-area-graph.js

@@ -0,0 +1,1431 @@
+import { createHash } from "node:crypto";
+const REFERENCE_SHAPED_TEXT = /^(?:condition|fact):/u;
+class SemanticProjectionReferenceError extends Error {
+  path;
+  constructor(path, message) {
+    super(message);
+    this.name = "SemanticProjectionReferenceError";
+    this.path = path;
+  }
+}
+function normalizeString(value) {
+  return value.replace(/\r\n?/gu, "\n").normalize("NFC");
+}
+function normalizeJson(value) {
+  if (value === null) return null;
+  if (typeof value === "string") return normalizeString(value);
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("Semantic projection accepts finite JSON numbers");
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeJson(item));
+  }
+  if (typeof value === "object") {
+    const normalized = {};
+    for (const key of Object.keys(value).sort()) {
+      const child = value[key];
+      if (child !== undefined) {
+        normalized[key] = normalizeJson(child);
+      }
+    }
+    return normalized;
+  }
+  throw new TypeError(
+    `Semantic projection accepts JSON values, got ${typeof value}`,
+  );
+}
+function stableStringify(value) {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+  const objectValue = value;
+  return `{${Object.keys(objectValue)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(objectValue[key])}`)
+    .join(",")}}`;
+}
+function fingerprint(value) {
+  return createHash("sha256")
+    .update(stableStringify(value), "utf8")
+    .digest("hex");
+}
+function sortedValues(values) {
+  return [...values].sort((left, right) =>
+    stableStringify(left).localeCompare(stableStringify(right), "en"),
+  );
+}
+function sortedStrings(values) {
+  return [...values]
+    .map(normalizeString)
+    .sort((left, right) => left.localeCompare(right, "en"));
+}
+function supportedValue(value, scope) {
+  if (value.status === "unresolved") {
+    return { status: "unresolved" };
+  }
+  return {
+    status: "resolved",
+    value: normalizeJson(value.value),
+    ...(scope === "complete" ? { confidence: value.confidence } : {}),
+  };
+}
+function isReferenceMetadataKey(key) {
+  return (
+    new Set([
+      "id",
+      "ownerKey",
+      "componentKey",
+      "elementKey",
+      "callbackKey",
+      "fromCallbackKey",
+      "toCallbackKey",
+      "hostKey",
+      "contentKeys",
+      "initialContentKey",
+      "effectKey",
+      "targetKey",
+      "stateKey",
+      "conditionKeys",
+      "relatedKeys",
+      "diagnosticIds",
+    ]).has(key) || /(?:Ref|Refs)$/u.test(key)
+  );
+}
+function semanticData(value) {
+  if (value === null) return null;
+  if (
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    typeof value === "number"
+  ) {
+    return normalizeJson(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => semanticData(item));
+  }
+  if (typeof value !== "object") {
+    return normalizeJson(value);
+  }
+  const result = {};
+  for (const key of Object.keys(value).sort()) {
+    if (isReferenceMetadataKey(key)) continue;
+    const child = value[key];
+    if (child !== undefined) result[key] = semanticData(child);
+  }
+  return result;
+}
+function conditionPredicate(data) {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    return semanticData(data);
+  }
+  const record = data;
+  const preferredKeys = [
+    "expressionAnchor",
+    "expression",
+    "predicate",
+    "description",
+    "plainLanguage",
+  ];
+  for (const key of preferredKeys) {
+    if (record[key] !== undefined) {
+      return semanticData(record[key]);
+    }
+  }
+  return semanticData(data);
+}
+function conditionValue(refOrLiteral, sourceFactById, scope, path) {
+  const fact = sourceFactById.get(refOrLiteral);
+  if (fact) {
+    if (fact.kind !== "condition") {
+      throw new SemanticProjectionReferenceError(
+        path,
+        `Condition reference resolves to ${fact.kind}, not condition`,
+      );
+    }
+    return {
+      status: "resolved",
+      predicate:
+        scope === "complete"
+          ? semanticData(fact.data)
+          : conditionPredicate(fact.data),
+    };
+  }
+  if (REFERENCE_SHAPED_TEXT.test(refOrLiteral)) {
+    throw new SemanticProjectionReferenceError(
+      path,
+      "Condition reference does not resolve in the companion Source Facts",
+    );
+  }
+  return {
+    status: "literal",
+    value: normalizeString(refOrLiteral),
+  };
+}
+function conditionValues(values, sourceFactById, scope, path) {
+  return sortedValues(
+    values.map((value, index) =>
+      conditionValue(value, sourceFactById, scope, `${path}/${index}`),
+    ),
+  );
+}
+function entityKey(kind, id) {
+  return `${kind}\u0000${id}`;
+}
+function semanticIssue(code, path, message) {
+  return { code, path, message };
+}
+class Projector {
+  graph;
+  source;
+  scope;
+  sourceFactById;
+  unresolvedById;
+  nodes = new Map();
+  adjacency = new Map();
+  fingerprints;
+  constructor(input, scope) {
+    this.graph = input.areaGraph;
+    this.source = input.sourceFacts;
+    this.scope = scope;
+    this.sourceFactById = new Map(
+      input.sourceFacts.facts.map((fact) => [fact.id, fact]),
+    );
+    this.unresolvedById = new Map(
+      input.areaGraph.unresolved.map((item) => [item.id, item]),
+    );
+    this.registerNodes();
+    this.registerRelationships();
+    this.fingerprints = this.refineFingerprints();
+  }
+  project() {
+    const pathById = new Map(
+      this.graph.paths.map((path, index) => [
+        path.id,
+        this.pathRecord(path, `/paths/${index}`),
+      ]),
+    );
+    const unresolvedRecords = this.graph.unresolved.map((item, index) =>
+      this.unresolvedSummary(
+        item,
+        this.ownerReference(item.ownerRef, `/unresolved/${index}/ownerRef`),
+      ),
+    );
+    const unresolvedRef = (ref, path) => {
+      const item = this.unresolvedById.get(ref);
+      if (!item) {
+        throw new SemanticProjectionReferenceError(
+          path,
+          "Unresolved reference does not resolve in Area Graph",
+        );
+      }
+      return {
+        entity: "unresolved",
+        fingerprint: fingerprint(
+          this.unresolvedSummary(
+            item,
+            this.ownerReference(item.ownerRef, `${path}/ownerRef`),
+          ),
+        ),
+      };
+    };
+    const unresolvedRefs = (refs, path) =>
+      sortedValues(
+        refs.map((ref, index) => unresolvedRef(ref, `${path}/${index}`)),
+      );
+    return {
+      projectionVersion: "1",
+      scope: this.scope,
+      areas: sortedValues(
+        this.graph.areas.map((area, index) => ({
+          fingerprint: this.reference("area", area.id, `/areas/${index}/id`),
+          ...this.areaIntrinsic(area, `/areas/${index}`),
+          controls: sortedValues(
+            area.controlRefs.map((ref, refIndex) =>
+              this.reference(
+                "control",
+                ref,
+                `/areas/${index}/controlRefs/${refIndex}`,
+              ),
+            ),
+          ),
+          canonicalPath:
+            area.canonicalPathRef === undefined
+              ? null
+              : this.pathReference(
+                  area.canonicalPathRef,
+                  pathById,
+                  `/areas/${index}/canonicalPathRef`,
+                ),
+          unresolved: unresolvedRefs(
+            area.unresolvedRefs,
+            `/areas/${index}/unresolvedRefs`,
+          ),
+        })),
+      ),
+      controls: sortedValues(
+        this.graph.controls.map((control, index) => ({
+          fingerprint: this.reference(
+            "control",
+            control.id,
+            `/controls/${index}/id`,
+          ),
+          ...this.controlIntrinsic(control, `/controls/${index}`),
+          area: this.reference(
+            "area",
+            control.areaRef,
+            `/controls/${index}/areaRef`,
+          ),
+          actions: sortedValues(
+            control.actionRefs.map((ref, refIndex) =>
+              this.reference(
+                "action",
+                ref,
+                `/controls/${index}/actionRefs/${refIndex}`,
+              ),
+            ),
+          ),
+          unresolved: unresolvedRefs(
+            control.unresolvedRefs,
+            `/controls/${index}/unresolvedRefs`,
+          ),
+        })),
+      ),
+      actions: sortedValues(
+        this.graph.actions.map((action, index) => ({
+          fingerprint: this.reference(
+            "action",
+            action.id,
+            `/actions/${index}/id`,
+          ),
+          ...this.actionIntrinsic(action, `/actions/${index}`),
+          control: this.reference(
+            "control",
+            action.controlRef,
+            `/actions/${index}/controlRef`,
+          ),
+          effects: sortedValues(
+            action.effectRefs.map((ref, refIndex) =>
+              this.reference(
+                "effect",
+                ref,
+                `/actions/${index}/effectRefs/${refIndex}`,
+              ),
+            ),
+          ),
+        })),
+      ),
+      effects: sortedValues(
+        this.graph.effects.map((effect, index) => ({
+          fingerprint: this.reference(
+            "effect",
+            effect.id,
+            `/effects/${index}/id`,
+          ),
+          ...this.effectIntrinsic(effect, `/effects/${index}`),
+          action: this.reference(
+            "action",
+            effect.actionRef,
+            `/effects/${index}/actionRef`,
+          ),
+          unresolved: unresolvedRefs(
+            effect.unresolvedRefs ?? [],
+            `/effects/${index}/unresolvedRefs`,
+          ),
+        })),
+      ),
+      edges: sortedValues(
+        this.graph.edges.map((edge, index) => ({
+          fingerprint: this.reference("edge", edge.id, `/edges/${index}/id`),
+          ...this.edgeIntrinsic(edge, `/edges/${index}`),
+          sourceArea: this.reference(
+            "area",
+            edge.sourceAreaRef,
+            `/edges/${index}/sourceAreaRef`,
+          ),
+          control: this.reference(
+            "control",
+            edge.controlRef,
+            `/edges/${index}/controlRef`,
+          ),
+          action: this.reference(
+            "action",
+            edge.actionRef,
+            `/edges/${index}/actionRef`,
+          ),
+          target:
+            "status" in edge.target
+              ? {
+                  status: "unresolved",
+                  unresolved: unresolvedRef(
+                    edge.target.unresolvedRef,
+                    `/edges/${index}/target/unresolvedRef`,
+                  ),
+                }
+              : {
+                  status: "resolved",
+                  kind: edge.target.kind,
+                  ref: this.reference(
+                    edge.target.kind === "area" ? "area" : "external",
+                    edge.target.ref,
+                    `/edges/${index}/target/ref`,
+                  ),
+                },
+        })),
+      ),
+      externalEndpoints: sortedValues(
+        this.graph.externalEndpoints.map((endpoint, index) => ({
+          fingerprint: this.reference(
+            "external",
+            endpoint.id,
+            `/externalEndpoints/${index}/id`,
+          ),
+          ...this.externalIntrinsic(endpoint),
+          unresolved: unresolvedRefs(
+            endpoint.unresolvedRefs,
+            `/externalEndpoints/${index}/unresolvedRefs`,
+          ),
+        })),
+      ),
+      entryPoints: sortedValues(
+        this.graph.entryPoints.map((entry, index) => ({
+          fingerprint: this.reference(
+            "entry",
+            entry.id,
+            `/entryPoints/${index}/id`,
+          ),
+          ...this.entryIntrinsic(entry, `/entryPoints/${index}`),
+          roots: sortedValues(
+            entry.rootAreaRefs.map((ref, refIndex) =>
+              this.reference(
+                "area",
+                ref,
+                `/entryPoints/${index}/rootAreaRefs/${refIndex}`,
+              ),
+            ),
+          ),
+          launcherArea:
+            entry.launcherAreaRef === undefined
+              ? null
+              : this.reference(
+                  "area",
+                  entry.launcherAreaRef,
+                  `/entryPoints/${index}/launcherAreaRef`,
+                ),
+        })),
+      ),
+      paths: sortedValues([...pathById.values()]),
+      unresolved: sortedValues(unresolvedRecords),
+    };
+  }
+  registerNodes() {
+    const register = (kind, id, intrinsic) => {
+      const key = entityKey(kind, id);
+      if (this.nodes.has(key)) {
+        throw new SemanticProjectionReferenceError(
+          "/",
+          `Duplicate ${kind} ID prevents semantic projection`,
+        );
+      }
+      this.nodes.set(key, { kind, id, intrinsic });
+      this.adjacency.set(key, []);
+    };
+    this.graph.areas.forEach((area, index) =>
+      register("area", area.id, this.areaIntrinsic(area, `/areas/${index}`)),
+    );
+    this.graph.controls.forEach((control, index) =>
+      register(
+        "control",
+        control.id,
+        this.controlIntrinsic(control, `/controls/${index}`),
+      ),
+    );
+    this.graph.actions.forEach((action, index) =>
+      register(
+        "action",
+        action.id,
+        this.actionIntrinsic(action, `/actions/${index}`),
+      ),
+    );
+    this.graph.effects.forEach((effect, index) =>
+      register(
+        "effect",
+        effect.id,
+        this.effectIntrinsic(effect, `/effects/${index}`),
+      ),
+    );
+    this.graph.edges.forEach((edge, index) =>
+      register("edge", edge.id, this.edgeIntrinsic(edge, `/edges/${index}`)),
+    );
+    this.graph.externalEndpoints.forEach((endpoint) =>
+      register("external", endpoint.id, this.externalIntrinsic(endpoint)),
+    );
+    this.graph.entryPoints.forEach((entry, index) =>
+      register(
+        "entry",
+        entry.id,
+        this.entryIntrinsic(entry, `/entryPoints/${index}`),
+      ),
+    );
+  }
+  registerRelationships() {
+    const connect = (
+      sourceKind,
+      sourceId,
+      relation,
+      targetKind,
+      targetId,
+      path,
+    ) => {
+      const sourceKey = entityKey(sourceKind, sourceId);
+      const targetKey = entityKey(targetKind, targetId);
+      if (!this.nodes.has(sourceKey) || !this.nodes.has(targetKey)) {
+        throw new SemanticProjectionReferenceError(
+          path,
+          `Relationship ${sourceKind}→${targetKind} contains a missing entity`,
+        );
+      }
+      this.adjacency.get(sourceKey)?.push({ relation, targetKey });
+    };
+    const pair = (
+      leftKind,
+      leftId,
+      leftRelation,
+      rightKind,
+      rightId,
+      rightRelation,
+      path,
+    ) => {
+      connect(leftKind, leftId, leftRelation, rightKind, rightId, path);
+      connect(rightKind, rightId, rightRelation, leftKind, leftId, path);
+    };
+    this.graph.controls.forEach((control, index) =>
+      pair(
+        "area",
+        control.areaRef,
+        "owns-control",
+        "control",
+        control.id,
+        "owned-by-area",
+        `/controls/${index}/areaRef`,
+      ),
+    );
+    this.graph.actions.forEach((action, index) =>
+      pair(
+        "control",
+        action.controlRef,
+        "owns-action",
+        "action",
+        action.id,
+        "owned-by-control",
+        `/actions/${index}/controlRef`,
+      ),
+    );
+    this.graph.effects.forEach((effect, index) =>
+      pair(
+        "action",
+        effect.actionRef,
+        "owns-effect",
+        "effect",
+        effect.id,
+        "owned-by-action",
+        `/effects/${index}/actionRef`,
+      ),
+    );
+    this.graph.edges.forEach((edge, index) => {
+      pair(
+        "area",
+        edge.sourceAreaRef,
+        "outgoing-edge",
+        "edge",
+        edge.id,
+        "source-area",
+        `/edges/${index}/sourceAreaRef`,
+      );
+      pair(
+        "control",
+        edge.controlRef,
+        "emits-edge",
+        "edge",
+        edge.id,
+        "edge-control",
+        `/edges/${index}/controlRef`,
+      );
+      pair(
+        "action",
+        edge.actionRef,
+        "emits-edge",
+        "edge",
+        edge.id,
+        "edge-action",
+        `/edges/${index}/actionRef`,
+      );
+      if (!("status" in edge.target)) {
+        pair(
+          edge.target.kind === "area" ? "area" : "external",
+          edge.target.ref,
+          "incoming-edge",
+          "edge",
+          edge.id,
+          "edge-target",
+          `/edges/${index}/target/ref`,
+        );
+      }
+    });
+    this.graph.entryPoints.forEach((entry, entryIndex) => {
+      entry.rootAreaRefs.forEach((areaRef, rootIndex) =>
+        pair(
+          "entry",
+          entry.id,
+          "root-area",
+          "area",
+          areaRef,
+          "rooted-by-entry",
+          `/entryPoints/${entryIndex}/rootAreaRefs/${rootIndex}`,
+        ),
+      );
+    });
+  }
+  refineFingerprints() {
+    let structuralColors = new Map(
+      [...this.nodes].map(([key, node]) => [
+        key,
+        fingerprint({ entity: node.kind, intrinsic: node.intrinsic }),
+      ]),
+    );
+    // One round propagates meaning across one relationship. Using the entity
+    // count covers every simple path in this finite graph while keeping the
+    // same round count for ID-renamed isomorphic artifacts.
+    for (let round = 0; round < Math.max(1, this.nodes.size); round += 1) {
+      structuralColors = new Map(
+        [...this.nodes].map(([key, node]) => {
+          const neighbors = sortedValues(
+            (this.adjacency.get(key) ?? []).map((neighbor) => ({
+              relation: neighbor.relation,
+              fingerprint:
+                structuralColors.get(neighbor.targetKey) ??
+                "missing-semantic-neighbor",
+            })),
+          );
+          return [
+            key,
+            fingerprint({
+              entity: node.kind,
+              intrinsic: node.intrinsic,
+              neighbors,
+            }),
+          ];
+        }),
+      );
+    }
+    const semanticColors = new Map();
+    const intrinsic = (kind, id) => {
+      const node = this.nodes.get(entityKey(kind, id));
+      if (!node) {
+        throw new SemanticProjectionReferenceError(
+          "/",
+          `Missing ${kind} while constructing semantic references`,
+        );
+      }
+      return node.intrinsic;
+    };
+    const knownSemanticColor = (kind, id, path) => {
+      const color = semanticColors.get(entityKey(kind, id));
+      if (!color) {
+        throw new SemanticProjectionReferenceError(
+          path,
+          `Missing ${kind} while constructing semantic references`,
+        );
+      }
+      return color;
+    };
+    const selectColors = (kind, identities) => {
+      const bases = identities.map((identity) => ({
+        id: identity.id,
+        base: fingerprint({
+          entity: kind,
+          semanticIdentity: identity.value,
+        }),
+      }));
+      const frequencies = new Map();
+      for (const item of bases) {
+        frequencies.set(item.base, (frequencies.get(item.base) ?? 0) + 1);
+      }
+      for (const item of bases) {
+        const key = entityKey(kind, item.id);
+        const selected =
+          frequencies.get(item.base) === 1
+            ? item.base
+            : structuralColors.get(key);
+        if (!selected) {
+          throw new SemanticProjectionReferenceError(
+            "/",
+            `Missing structural ${kind} fingerprint`,
+          );
+        }
+        semanticColors.set(key, selected);
+      }
+    };
+    // Most UI entities have an unambiguous name/owner identity. Use that
+    // local identity so one mismatch yields a focused diff. Only collisions
+    // (for example, two same-name Areas) fall back to the graph-neighborhood
+    // color above, preventing them from being exchanged silently.
+    selectColors(
+      "area",
+      this.graph.areas.map((area) => ({
+        id: area.id,
+        value: intrinsic("area", area.id),
+      })),
+    );
+    selectColors(
+      "external",
+      this.graph.externalEndpoints.map((endpoint) => ({
+        id: endpoint.id,
+        value: intrinsic("external", endpoint.id),
+      })),
+    );
+    selectColors(
+      "control",
+      this.graph.controls.map((control, index) => ({
+        id: control.id,
+        value: {
+          intrinsic: intrinsic("control", control.id),
+          area: knownSemanticColor(
+            "area",
+            control.areaRef,
+            `/controls/${index}/areaRef`,
+          ),
+        },
+      })),
+    );
+    selectColors(
+      "action",
+      this.graph.actions.map((action, index) => ({
+        id: action.id,
+        value: {
+          intrinsic: intrinsic("action", action.id),
+          control: knownSemanticColor(
+            "control",
+            action.controlRef,
+            `/actions/${index}/controlRef`,
+          ),
+        },
+      })),
+    );
+    selectColors(
+      "effect",
+      this.graph.effects.map((effect, index) => ({
+        id: effect.id,
+        value: {
+          intrinsic: intrinsic("effect", effect.id),
+          action: knownSemanticColor(
+            "action",
+            effect.actionRef,
+            `/effects/${index}/actionRef`,
+          ),
+        },
+      })),
+    );
+    selectColors(
+      "entry",
+      this.graph.entryPoints.map((entry, index) => ({
+        id: entry.id,
+        value: {
+          intrinsic: intrinsic("entry", entry.id),
+          roots: sortedStrings(
+            entry.rootAreaRefs.map((areaRef, rootIndex) =>
+              knownSemanticColor(
+                "area",
+                areaRef,
+                `/entryPoints/${index}/rootAreaRefs/${rootIndex}`,
+              ),
+            ),
+          ),
+        },
+      })),
+    );
+    selectColors(
+      "edge",
+      this.graph.edges.map((edge, index) => ({
+        id: edge.id,
+        value: {
+          intrinsic: intrinsic("edge", edge.id),
+          sourceArea: knownSemanticColor(
+            "area",
+            edge.sourceAreaRef,
+            `/edges/${index}/sourceAreaRef`,
+          ),
+          control: knownSemanticColor(
+            "control",
+            edge.controlRef,
+            `/edges/${index}/controlRef`,
+          ),
+          action: knownSemanticColor(
+            "action",
+            edge.actionRef,
+            `/edges/${index}/actionRef`,
+          ),
+          target:
+            "status" in edge.target
+              ? { status: "unresolved" }
+              : {
+                  status: "resolved",
+                  kind: edge.target.kind,
+                  fingerprint: knownSemanticColor(
+                    edge.target.kind === "area" ? "area" : "external",
+                    edge.target.ref,
+                    `/edges/${index}/target/ref`,
+                  ),
+                },
+        },
+      })),
+    );
+    return semanticColors;
+  }
+  reference(kind, id, path) {
+    const value = this.fingerprints.get(entityKey(kind, id));
+    if (!value) {
+      throw new SemanticProjectionReferenceError(
+        path,
+        `${kind} reference does not resolve in Area Graph`,
+      );
+    }
+    return { entity: kind, fingerprint: value };
+  }
+  ownerReference(ref, path) {
+    for (const kind of [
+      "area",
+      "control",
+      "action",
+      "effect",
+      "edge",
+      "external",
+      "entry",
+    ]) {
+      if (this.fingerprints.has(entityKey(kind, ref))) {
+        return this.reference(kind, ref, path);
+      }
+    }
+    const fact = this.sourceFactById.get(ref);
+    if (fact) {
+      return this.sourceFactReference(fact);
+    }
+    throw new SemanticProjectionReferenceError(
+      path,
+      "Unresolved owner does not resolve in Area Graph or Source Facts",
+    );
+  }
+  unresolvedLinks(refs, path) {
+    return sortedValues(
+      refs.map((ref, index) => {
+        const unresolved = this.unresolvedById.get(ref);
+        if (!unresolved) {
+          throw new SemanticProjectionReferenceError(
+            `${path}/${index}`,
+            "Unresolved reference does not resolve in Area Graph",
+          );
+        }
+        return {
+          entity: "unresolved",
+          fingerprint: fingerprint(
+            this.unresolvedSummary(
+              unresolved,
+              this.ownerReference(
+                unresolved.ownerRef,
+                `${path}/${index}/ownerRef`,
+              ),
+            ),
+          ),
+        };
+      }),
+    );
+  }
+  sourceFactReference(fact) {
+    return {
+      entity: "source-fact",
+      kind: fact.kind,
+      fingerprint: this.sourceFactFingerprint(fact),
+    };
+  }
+  sourceFactFingerprint(fact) {
+    return fingerprint({
+      kind: fact.kind,
+      data: semanticData(fact.data),
+    });
+  }
+  semanticEmbeddedValue(value) {
+    if (typeof value === "string") {
+      for (const kind of [
+        "area",
+        "control",
+        "action",
+        "effect",
+        "edge",
+        "external",
+        "entry",
+      ]) {
+        if (this.fingerprints.has(entityKey(kind, value))) {
+          return this.reference(kind, value, "/unresolved/candidate");
+        }
+      }
+      const fact = this.sourceFactById.get(value);
+      if (fact) return this.sourceFactReference(fact);
+      const unresolved = this.unresolvedById.get(value);
+      if (unresolved) {
+        return {
+          entity: "unresolved",
+          fieldPath: normalizeString(unresolved.fieldPath).replace(/^\/+/u, ""),
+          reasonCode: normalizeString(unresolved.reasonCode),
+        };
+      }
+      return this.semanticReferenceText(value);
+    }
+    if (value === null) return null;
+    if (typeof value === "boolean" || typeof value === "number") {
+      return normalizeJson(value);
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => this.semanticEmbeddedValue(item));
+    }
+    if (typeof value === "object") {
+      const result = {};
+      for (const key of Object.keys(value).sort()) {
+        const child = value[key];
+        if (child !== undefined) {
+          result[key] = this.semanticEmbeddedValue(child);
+        }
+      }
+      return result;
+    }
+    return normalizeJson(value);
+  }
+  semanticReferenceText(value) {
+    let normalized = normalizeString(value);
+    const replacements = [];
+    for (const kind of [
+      "area",
+      "control",
+      "action",
+      "effect",
+      "edge",
+      "external",
+      "entry",
+    ]) {
+      for (const node of this.nodes.values()) {
+        if (node.kind !== kind) continue;
+        const color = this.fingerprints.get(entityKey(kind, node.id));
+        if (color) {
+          replacements.push([node.id, `<semantic-${kind}:${color}>`]);
+        }
+      }
+    }
+    for (const fact of this.source.facts) {
+      replacements.push([
+        fact.id,
+        `<semantic-source-fact:${this.sourceFactFingerprint(fact)}>`,
+      ]);
+    }
+    for (const item of this.graph.unresolved) {
+      replacements.push([
+        item.id,
+        `<semantic-unresolved:${normalizeString(item.reasonCode)}:` +
+          `${normalizeString(item.fieldPath).replace(/^\/+/u, "")}>`,
+      ]);
+    }
+    replacements.sort((left, right) => right[0].length - left[0].length);
+    for (const [producerId, semanticRef] of replacements) {
+      normalized = normalized.split(producerId).join(semanticRef);
+    }
+    return normalized;
+  }
+  unresolvedSummary(item, owner) {
+    return {
+      owner,
+      fieldPath: normalizeString(item.fieldPath).replace(/^\/+/u, ""),
+      reasonCode: normalizeString(item.reasonCode),
+      ...(this.scope === "complete"
+        ? {
+            message: this.semanticReferenceText(item.message),
+            candidates: sortedValues(
+              item.candidates.map((candidate) => ({
+                value: this.semanticEmbeddedValue(candidate.value),
+                ...(candidate.note === undefined
+                  ? {}
+                  : {
+                      note: this.semanticReferenceText(candidate.note),
+                    }),
+              })),
+            ),
+            impact: sortedStrings(
+              item.impact.map((impact) => this.semanticReferenceText(impact)),
+            ),
+          }
+        : {}),
+    };
+  }
+  areaIntrinsic(area, path) {
+    return {
+      kind: normalizeString(area.kind),
+      name: supportedValue(area.name, this.scope),
+      conditions: conditionValues(
+        area.conditions,
+        this.sourceFactById,
+        this.scope,
+        `${path}/conditions`,
+      ),
+      ...(this.scope === "complete"
+        ? {
+            descriptionFacts: sortedValues(
+              area.descriptionFacts.map((description) => ({
+                kind: normalizeString(description.kind),
+                value: supportedValue(description.value, this.scope),
+              })),
+            ),
+          }
+        : {}),
+    };
+  }
+  controlIntrinsic(control, path) {
+    return {
+      kind: normalizeString(control.kind),
+      name: supportedValue(control.name, this.scope),
+      enabled:
+        control.enabled === undefined
+          ? null
+          : supportedValue(control.enabled, this.scope),
+      visibilityConditions: conditionValues(
+        control.visibilityConditions,
+        this.sourceFactById,
+        this.scope,
+        `${path}/visibilityConditions`,
+      ),
+      enabledConditions: conditionValues(
+        control.enabledConditions,
+        this.sourceFactById,
+        this.scope,
+        `${path}/enabledConditions`,
+      ),
+    };
+  }
+  actionIntrinsic(action, path) {
+    return {
+      trigger: normalizeString(action.trigger),
+      preconditions: conditionValues(
+        action.preconditionRefs,
+        this.sourceFactById,
+        this.scope,
+        `${path}/preconditionRefs`,
+      ),
+      preconditionAlternatives: sortedValues(
+        (action.preconditionAlternatives ?? []).map((alternative, index) =>
+          conditionValues(
+            alternative.conditionRefs,
+            this.sourceFactById,
+            this.scope,
+            `${path}/preconditionAlternatives/${index}/conditionRefs`,
+          ),
+        ),
+      ),
+    };
+  }
+  effectIntrinsic(effect, path) {
+    return {
+      kind: normalizeString(effect.kind),
+      conditionAlternatives: sortedValues(
+        (effect.conditionAlternatives ?? []).map((alternative, index) =>
+          conditionValues(
+            alternative.conditionRefs,
+            this.sourceFactById,
+            this.scope,
+            `${path}/conditionAlternatives/${index}/conditionRefs`,
+          ),
+        ),
+      ),
+      stateKey:
+        effect.stateKey === undefined
+          ? null
+          : supportedValue(effect.stateKey, this.scope),
+      value:
+        effect.value === undefined
+          ? null
+          : supportedValue(effect.value, this.scope),
+      ...(this.scope === "complete"
+        ? { description: supportedValue(effect.description, this.scope) }
+        : {}),
+    };
+  }
+  edgeIntrinsic(edge, path) {
+    return {
+      conditions: conditionValues(
+        edge.conditions,
+        this.sourceFactById,
+        this.scope,
+        `${path}/conditions`,
+      ),
+      preconditions: conditionValues(
+        edge.preconditions,
+        this.sourceFactById,
+        this.scope,
+        `${path}/preconditions`,
+      ),
+      conditionAlternatives: sortedValues(
+        (edge.conditionAlternatives ?? []).map((alternative, index) =>
+          conditionValues(
+            alternative.conditionRefs,
+            this.sourceFactById,
+            this.scope,
+            `${path}/conditionAlternatives/${index}/conditionRefs`,
+          ),
+        ),
+      ),
+      targetStatus: "status" in edge.target ? "unresolved" : edge.target.kind,
+    };
+  }
+  externalIntrinsic(endpoint) {
+    return {
+      kind: normalizeString(endpoint.kind),
+      name: supportedValue(endpoint.name, this.scope),
+      presentation: endpoint.presentation ?? null,
+      intentAction:
+        endpoint.intentAction === undefined
+          ? null
+          : supportedValue(endpoint.intentAction, this.scope),
+      mimeType:
+        endpoint.mimeType === undefined
+          ? null
+          : supportedValue(endpoint.mimeType, this.scope),
+      uri:
+        endpoint.uri === undefined
+          ? null
+          : supportedValue(endpoint.uri, this.scope),
+    };
+  }
+  entryIntrinsic(entry, path) {
+    return {
+      kind: normalizeString(entry.kind),
+      category: entry.category,
+      startupRole: entry.startupRole ?? null,
+      conditions: conditionValues(
+        entry.conditions,
+        this.sourceFactById,
+        this.scope,
+        `${path}/conditions`,
+      ),
+      preconditions: conditionValues(
+        entry.preconditions ?? entry.conditions,
+        this.sourceFactById,
+        this.scope,
+        `${path}/preconditions`,
+      ),
+    };
+  }
+  pathRecord(pathValue, path) {
+    return {
+      kind: pathValue.kind,
+      reachability: pathValue.reachability,
+      targetArea: this.reference(
+        "area",
+        pathValue.targetAreaRef,
+        `${path}/targetAreaRef`,
+      ),
+      rootEntry:
+        pathValue.rootEntryRef === undefined
+          ? null
+          : this.reference(
+              "entry",
+              pathValue.rootEntryRef,
+              `${path}/rootEntryRef`,
+            ),
+      preconditions: conditionValues(
+        pathValue.preconditions,
+        this.sourceFactById,
+        this.scope,
+        `${path}/preconditions`,
+      ),
+      steps: pathValue.steps.map((step, index) => ({
+        edge: this.reference(
+          "edge",
+          step.edgeRef,
+          `${path}/steps/${index}/edgeRef`,
+        ),
+        sourceArea: this.reference(
+          "area",
+          step.sourceAreaRef,
+          `${path}/steps/${index}/sourceAreaRef`,
+        ),
+        control: this.reference(
+          "control",
+          step.controlRef,
+          `${path}/steps/${index}/controlRef`,
+        ),
+        action: this.reference(
+          "action",
+          step.actionRef,
+          `${path}/steps/${index}/actionRef`,
+        ),
+        targetArea: this.reference(
+          "area",
+          step.targetAreaRef,
+          `${path}/steps/${index}/targetAreaRef`,
+        ),
+      })),
+      ...(this.scope === "complete"
+        ? {
+            selectionReasons: sortedStrings(pathValue.selectionReasons),
+          }
+        : {}),
+      unresolved: this.unresolvedLinks(
+        pathValue.unresolvedRefs,
+        `${path}/unresolvedRefs`,
+      ),
+    };
+  }
+  pathReference(id, pathById, path) {
+    const record = pathById.get(id);
+    if (!record) {
+      throw new SemanticProjectionReferenceError(
+        path,
+        "Canonical path reference does not resolve in Area Graph",
+      );
+    }
+    return { entity: "path", fingerprint: fingerprint(record) };
+  }
+}
+/**
+ * Removes producer IDs, evidence/support references and raw identity anchors,
+ * then reconstructs references from semantic fingerprints. Array
+ * multiplicity is retained and path steps remain ordered.
+ *
+ * This is intentionally not a replacement for schema/reference validation or
+ * byte-for-byte GT compatibility. Validate each side with the validator that
+ * owns that artifact version before comparing. The comparator itself checks
+ * every reference it must dereference, without imposing newer policy
+ * invariants on a frozen older oracle.
+ */
+export function projectAreaGraphSemantics(input, options = {}) {
+  const scope = options.scope ?? "complete";
+  if (input.areaGraph.caseId !== input.sourceFacts.caseId) {
+    throw new SemanticProjectionReferenceError(
+      "/caseId",
+      "Area Graph and Source Facts caseId differ",
+    );
+  }
+  return new Projector(input, scope).project();
+}
+function summarized(value) {
+  const serialized = stableStringify(value);
+  return serialized.length <= 800
+    ? serialized
+    : `${serialized.slice(0, 797)}...`;
+}
+function compareCollection(expected, actual) {
+  const frequencies = (values) => {
+    const result = new Map();
+    for (const value of values) {
+      const key = stableStringify(value);
+      const prior = result.get(key);
+      result.set(key, {
+        value,
+        count: (prior?.count ?? 0) + 1,
+      });
+    }
+    return result;
+  };
+  const expectedByValue = frequencies(expected);
+  const actualByValue = frequencies(actual);
+  let differenceCount = 0;
+  const missingRecords = [];
+  const unexpectedRecords = [];
+  for (const [key, expectedEntry] of expectedByValue) {
+    const actualCount = actualByValue.get(key)?.count ?? 0;
+    const missing = Math.max(0, expectedEntry.count - actualCount);
+    if (missing === 0) continue;
+    differenceCount += missing;
+    missingRecords.push({ value: expectedEntry.value, count: missing });
+  }
+  for (const [key, actualEntry] of actualByValue) {
+    const expectedCount = expectedByValue.get(key)?.count ?? 0;
+    const unexpected = Math.max(0, actualEntry.count - expectedCount);
+    if (unexpected === 0) continue;
+    differenceCount += unexpected;
+    unexpectedRecords.push({
+      value: actualEntry.value,
+      count: unexpected,
+    });
+  }
+  return {
+    differenceCount,
+    expectedCount: expected.length,
+    actualCount: actual.length,
+    missing: missingRecords,
+    unexpected: unexpectedRecords,
+  };
+}
+/**
+ * Compares two graph/path artifacts without requiring their declared IDs to
+ * match. A result can pass only when every projected record and its
+ * multiplicity match; equal entity counts alone are insufficient.
+ */
+export function compareAreaGraphSemantics(expected, actual, options = {}) {
+  const issues = [];
+  const maxIssues = options.maxIssues ?? 200;
+  if (!Number.isSafeInteger(maxIssues) || maxIssues <= 0) {
+    throw new RangeError("maxIssues must be a positive safe integer");
+  }
+  for (const [side, input] of [
+    ["expected", expected],
+    ["actual", actual],
+  ]) {
+    if (input.areaGraph.caseId !== input.sourceFacts.caseId) {
+      issues.push(
+        semanticIssue(
+          "SEMANTIC_CASE_MISMATCH",
+          `/${side}/caseId`,
+          "Area Graph and Source Facts caseId differ",
+        ),
+      );
+    }
+  }
+  if (issues.length > 0) {
+    return { ok: false, issues };
+  }
+  let expectedProjection;
+  let actualProjection;
+  try {
+    expectedProjection = projectAreaGraphSemantics(expected, options);
+  } catch (error) {
+    if (error instanceof SemanticProjectionReferenceError) {
+      return {
+        ok: false,
+        issues: [
+          semanticIssue(
+            "SEMANTIC_EXPECTED_PROJECTION_INVALID",
+            `/expected${error.path}`,
+            error.message,
+          ),
+        ],
+      };
+    }
+    throw error;
+  }
+  try {
+    actualProjection = projectAreaGraphSemantics(actual, options);
+  } catch (error) {
+    if (error instanceof SemanticProjectionReferenceError) {
+      return {
+        ok: false,
+        issues: [
+          semanticIssue(
+            "SEMANTIC_ACTUAL_PROJECTION_INVALID",
+            `/actual${error.path}`,
+            error.message,
+          ),
+        ],
+      };
+    }
+    throw error;
+  }
+  const collections = [
+    "areas",
+    "controls",
+    "actions",
+    "effects",
+    "edges",
+    "externalEndpoints",
+    "entryPoints",
+    "paths",
+    "unresolved",
+  ];
+  const collectionResults = collections.map((collection) => ({
+    collection,
+    difference: compareCollection(
+      expectedProjection[collection],
+      actualProjection[collection],
+    ),
+  }));
+  const differenceCount = collectionResults.reduce(
+    (sum, result) => sum + result.difference.differenceCount,
+    0,
+  );
+  const differingCollections = collectionResults.filter(
+    (result) => result.difference.differenceCount > 0,
+  );
+  const desiredDiagnostics = differingCollections.reduce(
+    (sum, result) =>
+      sum +
+      1 +
+      result.difference.missing.length +
+      result.difference.unexpected.length,
+    0,
+  );
+  const truncated = desiredDiagnostics > maxIssues;
+  const detailLimit = truncated && maxIssues > 1 ? maxIssues - 1 : maxIssues;
+  // Emit one summary for every collection before record examples. Even a
+  // large Area mismatch therefore cannot hide whether paths also differ.
+  for (const { collection, difference } of differingCollections) {
+    if (issues.length >= detailLimit) break;
+    const missingCount = difference.missing.reduce(
+      (sum, item) => sum + item.count,
+      0,
+    );
+    const unexpectedCount = difference.unexpected.reduce(
+      (sum, item) => sum + item.count,
+      0,
+    );
+    issues.push(
+      semanticIssue(
+        "SEMANTIC_COLLECTION_DIFFERENT",
+        `/${collection}`,
+        `Expected ${difference.expectedCount}, actual ${difference.actualCount}; ` +
+          `missing ${missingCount}, unexpected ${unexpectedCount}`,
+      ),
+    );
+  }
+  for (const { collection, difference } of differingCollections) {
+    for (const item of difference.missing) {
+      if (issues.length >= detailLimit) break;
+      issues.push(
+        semanticIssue(
+          "SEMANTIC_MISSING",
+          `/${collection}`,
+          `Missing ${item.count} semantic record(s): ${summarized(item.value)}`,
+        ),
+      );
+    }
+    for (const item of difference.unexpected) {
+      if (issues.length >= detailLimit) break;
+      issues.push(
+        semanticIssue(
+          "SEMANTIC_UNEXPECTED",
+          `/${collection}`,
+          `Unexpected ${item.count} semantic record(s): ${summarized(item.value)}`,
+        ),
+      );
+    }
+    if (issues.length >= detailLimit) break;
+  }
+  if (truncated && maxIssues > 1) {
+    issues.push(
+      semanticIssue(
+        "SEMANTIC_DIAGNOSTICS_TRUNCATED",
+        "/",
+        "Additional semantic differences were omitted by maxIssues",
+      ),
+    );
+  }
+  return {
+    ok: differenceCount === 0,
+    issues,
+  };
+}