@usefragments/core 1.11.0 → 2.0.1

package/dist/preview-runtime.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { V as VariantRenderOptions, b as VariantLoader } from './governance-BAsy1k2H.js';
+import { V as VariantRenderOptions, b as VariantLoader } from './governance-hOPXGbbs.js';
 import 'zod';
 import './topology/index.js';
 

package/dist/react-types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType, ReactNode, JSX } from 'react';
-export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-BAsy1k2H.js';
+export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-hOPXGbbs.js';
 import 'zod';
 import './topology/index.js';
 

package/dist/schemas/index.js

@@ -24,7 +24,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "../chunk-RPSEABY3.js";
+} from "../chunk-QPOKQ5H6.js";
 import "../chunk-EIYNNS77.js";
 import "../chunk-PWIJMOI4.js";
 import "../chunk-JNBFJ34I.js";

package/dist/storyAdapter.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode, ComponentType } from 'react';
 import { isExportStory as isExportStory$1, storyNameFromExport as storyNameFromExport$1, toId as toId$1 } from '@storybook/csf';
-import { F as FragmentDefinition } from './governance-BAsy1k2H.js';
+import { F as FragmentDefinition } from './governance-hOPXGbbs.js';
 import 'zod';
 import './topology/index.js';
 

package/dist/test-utils.d.ts

@@ -1,6 +1,6 @@
 import { CompiledBlock, CompiledFragment } from './compiled-types/index.js';
 import './types-xJ2xyp_G.js';
-import './governance-BAsy1k2H.js';
+import './governance-hOPXGbbs.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/dist/topology/index.d.ts

@@ -6,7 +6,7 @@
  * preview, cross-repo reconciliation) import it; none reimplements glob/area
  * logic. Pure and browser-safe — no Node, no parser deps.
  *
- * See `apps/cloud/docs/topology/01-architecture.md §1`.
+ * See `docs/fragments-v1/ARCHITECTURE.md §1`.
  */
 type AreaCriticality = "low" | "medium" | "high" | "revenue" | "regulated";
 interface Area {

package/dist/topology/index.js

@@ -1,6 +1,6 @@
 import {
   resolveArea
-} from "../chunk-3LLRNCPX.js";
+} from "../chunk-MZ2FS7U4.js";
 export {
   resolveArea
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/core",
-  "version": "1.11.0",
+  "version": "2.0.1",
   "license": "MIT",
   "description": "Core types, schemas, and runtime API for Fragments component definitions",
   "author": "Conan McNicholl",

package/src/approved-contract-tokens.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import {
+  APPROVED_CONTRACT_TOKEN_MAX_NAMES,
+  APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH,
+  isApprovedContractTokenNames,
+} from "./approved-contract-tokens.js";
+import { parseComponentGovernancePolicyJson } from "./governance.js";
+
+describe("approved token transport", () => {
+  it("distinguishes absent authority from an explicitly empty vocabulary", () => {
+    expect(isApprovedContractTokenNames(undefined)).toBe(false);
+    expect(isApprovedContractTokenNames(null)).toBe(false);
+    expect(isApprovedContractTokenNames([])).toBe(true);
+    expect(isApprovedContractTokenNames(["--approved"])).toBe(true);
+  });
+  it("enforces the same bounded vocabulary on every consumer", () => {
+    expect(isApprovedContractTokenNames(Array(APPROVED_CONTRACT_TOKEN_MAX_NAMES).fill("--x"))).toBe(
+      true
+    );
+    expect(
+      isApprovedContractTokenNames(Array(APPROVED_CONTRACT_TOKEN_MAX_NAMES + 1).fill("--x"))
+    ).toBe(false);
+    expect(
+      isApprovedContractTokenNames(["--" + "x".repeat(APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH - 2)])
+    ).toBe(true);
+    expect(
+      isApprovedContractTokenNames(["--" + "x".repeat(APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH - 1)])
+    ).toBe(false);
+    expect(isApprovedContractTokenNames(["--"])).toBe(false);
+    expect(isApprovedContractTokenNames(["local-token"])).toBe(false);
+  });
+});
+
+it("normalizes supported policy envelopes without treating malformed authority as empty rules", () => {
+  for (const payload of ["[]", '{"governance":[]}', '{"rules":[]}'])
+    expect(parseComponentGovernancePolicyJson(payload)).toEqual([]);
+  for (const payload of ["null", "{}", "[{}]", "invalid", '{"governance":false}'])
+    expect(parseComponentGovernancePolicyJson(payload)).toBeNull();
+});

package/src/approved-contract-tokens.ts

@@ -0,0 +1,18 @@
+/** Portable bounds shared by contract authoring and first-party policy clients. */
+export const APPROVED_CONTRACT_TOKEN_MAX_NAMES = 10_000;
+export const APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH = 512;
+
+/** Empty is authored absence; missing is unavailable authority. */
+export function isApprovedContractTokenNames(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length <= APPROVED_CONTRACT_TOKEN_MAX_NAMES &&
+    value.every(
+      (name) =>
+        typeof name === "string" &&
+        name.startsWith("--") &&
+        name.length > 2 &&
+        name.length <= APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH
+    )
+  );
+}

package/src/canonical-source.ts

@@ -0,0 +1,41 @@
+import type { CanonicalSource } from "./governance.js";
+
+/** Export filters narrow source ownership; an empty include approves nothing. */
+export function canonicalSourceIncludesExport(source: CanonicalSource, name: string): boolean {
+  const role = name.split(".").at(-1) ?? name;
+  const matches = (names: readonly string[]) => names.includes(name) || names.includes(role);
+  return (
+    !matches(source.exclude ?? []) && (source.include === undefined || matches(source.include))
+  );
+}
+
+/** Filesystem ownership only. Package import specifiers are not local paths. */
+export function canonicalSourceContainsFile(source: CanonicalSource, file: string): boolean {
+  const root =
+    source.kind === "directory"
+      ? source.path
+      : source.kind === "registry"
+        ? source.installPath
+        : source.implementationPath;
+  if (!root) return false;
+  const normalize = (value: string) =>
+    value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+  const normalizedRoot = normalize(root);
+  const normalizedFile = normalize(file);
+  return (
+    normalizedRoot === "." ||
+    normalizedFile === normalizedRoot ||
+    normalizedFile.startsWith(`${normalizedRoot}/`)
+  );
+}
+
+export function isCanonicalSourceDefinition(
+  file: string,
+  exportName: string,
+  sources: readonly CanonicalSource[]
+): boolean {
+  return sources.some(
+    (source) =>
+      canonicalSourceContainsFile(source, file) && canonicalSourceIncludesExport(source, exportName)
+  );
+}

package/src/codes/__tests__/codes.test.ts

@@ -29,6 +29,10 @@ const SUBSYSTEM_EMITTED_CODES = [
   // extracted component, is refused before any rule has a contract to run on.
   "FUI9010",
   "FUI9011",
+  // Emitted by Cloud's machine contract write path (CLI route + MCP tool) when
+  // the workspace plan does not include contract writes from machines; the CLI
+  // relays it. Not a rule.
+  "FUI9012",
   // Emitted by tokens/css-vars-must-be-defined when the rule is active but the
   // resolved contract vocabulary is empty — a config-level inert diagnostic,
   // not a second rule id in RULES.

package/src/codes/codes.ts

@@ -557,6 +557,16 @@ export const CODES = [
     fixAvailable: false,
     evidenceRequired: false,
   }),
+  code({
+    code: "FUI9012",
+    ruleId: "contract/write-not-entitled",
+    category: "system",
+    defaultSeverity: "critical",
+    title: "Contract write requires a paid workspace",
+    lifecycle: "experimental",
+    fixAvailable: false,
+    evidenceRequired: false,
+  }),
 ] as const satisfies readonly FuiCode[];
 
 export const byCode: ReadonlyMap<string, FuiCode> = new Map(

package/src/domain-ids.test.ts

@@ -3,12 +3,8 @@ import {
   analysisPlanIdFromDigest,
   evaluationReceiptIdFromDigest,
   mintEvaluationReceiptId,
-  featurePlanIdFromEntropy,
-  featureRevisionIdFromDigest,
   parseAnalysisPlanId,
   parseEvaluationReceiptId,
-  parseFeaturePlanId,
-  parseFeatureRevisionId,
 } from "./domain-ids.js";
 
 const DIGEST = "0123456789abcdef".repeat(4);
@@ -18,35 +14,22 @@ describe("V1 domain IDs", () => {
     expect(analysisPlanIdFromDigest(DIGEST)).toBe(`apl_${DIGEST}`);
     expect(evaluationReceiptIdFromDigest(DIGEST)).toBe(`evr_${DIGEST}`);
     expect(mintEvaluationReceiptId(DIGEST)).toBe(`evr_${DIGEST}`);
-    expect(featureRevisionIdFromDigest(DIGEST)).toBe(`fpr_${DIGEST}`);
-  });
-
-  it("keeps feature workflow identity opaque and exactly 128-bit", () => {
-    const entropy = "00112233445566778899aabbccddeeff";
-    expect(featurePlanIdFromEntropy(entropy)).toBe(`fpl_${entropy}`);
   });
 
   it.each([
     [parseAnalysisPlanId, `apl_${DIGEST}`],
     [parseEvaluationReceiptId, `evr_${DIGEST}`],
-    [parseFeatureRevisionId, `fpr_${DIGEST}`],
-    [parseFeaturePlanId, "fpl_00112233445566778899aabbccddeeff"],
   ] as const)("round-trips a valid ID", (parse, value) => {
     expect(parse(value)).toBe(value);
   });
 
-  it.each([
-    `apl_${DIGEST.slice(0, -1)}`,
-    `apl_${DIGEST.toUpperCase()}`,
-    `evr_${DIGEST}extra`,
-    `fpr_${DIGEST.slice(0, 32)}`,
-    "fpl_00112233445566778899AABBCCDDEEFF",
-  ])("rejects truncated, uppercase, or extended IDs: %s", (value) => {
-    expect(() => {
-      if (value.startsWith("apl_")) parseAnalysisPlanId(value);
-      else if (value.startsWith("evr_")) parseEvaluationReceiptId(value);
-      else if (value.startsWith("fpr_")) parseFeatureRevisionId(value);
-      else parseFeaturePlanId(value);
-    }).toThrow();
-  });
+  it.each([`apl_${DIGEST.slice(0, -1)}`, `apl_${DIGEST.toUpperCase()}`, `evr_${DIGEST}extra`])(
+    "rejects truncated, uppercase, or extended IDs: %s",
+    (value) => {
+      expect(() => {
+        if (value.startsWith("apl_")) parseAnalysisPlanId(value);
+        else if (value.startsWith("evr_")) parseEvaluationReceiptId(value);
+      }).toThrow();
+    }
+  );
 });

package/src/domain-ids.ts

@@ -1,23 +1,15 @@
 import { z } from "zod";
 
 const FULL_DIGEST_PATTERN = /^[0-9a-f]{64}$/u;
-const WORKFLOW_ENTROPY_PATTERN = /^[0-9a-f]{32}$/u;
 
 export declare const analysisPlanIdBrand: unique symbol;
 export declare const evaluationReceiptIdBrand: unique symbol;
-export declare const featurePlanIdBrand: unique symbol;
-export declare const featureRevisionIdBrand: unique symbol;
 
 export type DigestHex = string;
 export type AnalysisPlanId = `apl_${string}` & { readonly [analysisPlanIdBrand]: void };
 export type EvaluationReceiptId = `evr_${string}` & {
   readonly [evaluationReceiptIdBrand]: void;
 };
-export type FeaturePlanId = `fpl_${string}` & { readonly [featurePlanIdBrand]: void };
-export type FeatureRevisionId = `fpr_${string}` & {
-  readonly [featureRevisionIdBrand]: void;
-};
-
 export const digestHexStringSchema = z
   .string()
   .regex(FULL_DIGEST_PATTERN, "Expected 64 lowercase hexadecimal characters");
@@ -38,20 +30,6 @@ export const evaluationReceiptIdStringSchema = z
   .string()
   .regex(/^evr_[0-9a-f]{64}$/u, "Invalid evaluation receipt ID");
 
-export const featurePlanIdStringSchema = z
-  .string()
-  .regex(/^fpl_[0-9a-f]{32}$/u, "Invalid feature plan ID");
-export const featurePlanIdSchema = featurePlanIdStringSchema.transform(
-  (value) => value as FeaturePlanId
-);
-
-export const featureRevisionIdStringSchema = z
-  .string()
-  .regex(/^fpr_[0-9a-f]{64}$/u, "Invalid feature revision ID");
-export const featureRevisionIdSchema = featureRevisionIdStringSchema.transform(
-  (value) => value as FeatureRevisionId
-);
-
 export function parseDigestHex(value: string): DigestHex {
   return digestHexSchema.parse(value);
 }
@@ -74,21 +52,6 @@ export function mintEvaluationReceiptId(resultDigest: string): EvaluationReceipt
   return evaluationReceiptIdFromDigest(resultDigest);
 }
 
-export function featureRevisionIdFromDigest(digest: string): FeatureRevisionId {
-  return featureRevisionIdSchema.parse(`fpr_${parseDigestHex(digest)}`);
-}
-
-/**
- * Construct a stable feature-workflow ID from 128 bits supplied by the caller.
- * Core deliberately owns neither a clock nor a random-number generator.
- */
-export function featurePlanIdFromEntropy(entropyHex: string): FeaturePlanId {
-  if (!WORKFLOW_ENTROPY_PATTERN.test(entropyHex)) {
-    throw new TypeError("Feature plan entropy must be exactly 128-bit lowercase hexadecimal");
-  }
-  return featurePlanIdSchema.parse(`fpl_${entropyHex}`);
-}
-
 export function parseAnalysisPlanId(value: string): AnalysisPlanId {
   return analysisPlanIdSchema.parse(value);
 }
@@ -96,11 +59,3 @@ export function parseAnalysisPlanId(value: string): AnalysisPlanId {
 export function parseEvaluationReceiptId(value: string): EvaluationReceiptId {
   return evaluationReceiptIdSchema.parse(value);
 }
-
-export function parseFeaturePlanId(value: string): FeaturePlanId {
-  return featurePlanIdSchema.parse(value);
-}
-
-export function parseFeatureRevisionId(value: string): FeatureRevisionId {
-  return featureRevisionIdSchema.parse(value);
-}

package/src/evaluation/evaluate.ts

@@ -303,7 +303,7 @@ function evaluateV2(rawInput: EvaluationInputV2): EvaluationResultV2 {
       : coverageSummary.requiredByState.analyzed === coverageSummary.requiredRegions
         ? "complete"
         : "incomplete";
-  const integrity = {
+  const integrity: EvaluationResultV2["integrity"] = {
     fcidVerified: compatibilityResult.integrity.fcidVerified === true,
     analysisPlanVerified: true,
     factIntegrity: input.integrity.facts.state,
@@ -324,9 +324,7 @@ function evaluateV2(rawInput: EvaluationInputV2): EvaluationResultV2 {
     verdict = "indeterminate";
   }
 
-  const inputDigest = sha256Hex(
-    canonicalPreimage(normalizeInputV2ForDigest(input, coverageSummary))
-  );
+  const inputDigest = evaluationInputDigestV2(input);
   const partial = {
     schemaVersion: 2 as const,
     verdict,
@@ -340,12 +338,24 @@ function evaluateV2(rawInput: EvaluationInputV2): EvaluationResultV2 {
     coverageSummary,
     integrity,
   };
-  const resultDigest = sha256Hex(
-    canonicalPreimage({ schema: "evaluation-result:v2", ...partial, inputDigest })
-  );
+  const resultDigest = evaluationResultDigestV2({ ...partial, inputDigest });
   return evaluationResultV2Schema.parse({ ...partial, inputDigest, resultDigest });
 }
 
+/** Hash captured input identity without re-running the rule engine. */
+export function evaluationInputDigestV2(input: EvaluationInputV2): string {
+  return sha256Hex(
+    canonicalPreimage(
+      normalizeInputV2ForDigest(input, deriveCoverageSummaryV1(input.analysisPlan, input.coverage))
+    )
+  );
+}
+
+/** Validate stored result identity using the same algorithm as evaluation. */
+export function evaluationResultDigestV2(result: Omit<EvaluationResultV2, "resultDigest">): string {
+  return sha256Hex(canonicalPreimage({ schema: "evaluation-result:v2", ...result }));
+}
+
 function normalizeInputV2ForDigest(
   input: EvaluationInputV2,
   coverageSummary: ReturnType<typeof deriveCoverageSummaryV1>

package/src/evaluation/evaluation-v2-receipt-v1.test.ts

@@ -9,6 +9,8 @@ import { repositoryBindingDigestV1 } from "../repository-binding.js";
 import {
   EVALUATOR_VERSION_V2,
   evaluate,
+  evaluationInputDigestV2,
+  evaluationResultDigestV2,
   evaluationInputV2Schema,
   evaluationReceiptDigestV1,
   evaluationReceiptMintInputV1Schema,
@@ -550,6 +552,18 @@ describe("EvaluationResultV2", () => {
 });
 
 describe("evaluate V2", () => {
+  it("validates stored semantic digests without a second evaluation", () => {
+    const input = evaluationInput();
+    const result = evaluate(input);
+    const { resultDigest, ...semantic } = result;
+    expect(evaluationInputDigestV2(input)).toBe(result.inputDigest);
+    expect(evaluationResultDigestV2(semantic)).toBe(resultDigest);
+    expect(evaluationResultDigestV2({ ...semantic, verdict: "block" })).not.toBe(resultDigest);
+    expect(evaluationInputDigestV2({ ...input, evaluatedAt: input.evaluatedAt + 1 })).not.toBe(
+      result.inputDigest
+    );
+  });
+
   it("produces the checked-in deterministic pass result for complete healthy evidence", () => {
     const result = evaluate(evaluationInput());
 
@@ -741,14 +755,12 @@ describe("EvaluationReceiptV1", () => {
       resultDigest: A,
       evaluatorVersion: "evaluation-kernel:v2",
     } satisfies EvaluationReceiptMintInputV1;
-    if (false) {
-      // @ts-expect-error Source-verified trust is derived with provider proof by the application.
-      const sourceVerifiedMintInput: EvaluationReceiptMintInputV1 = {
-        ...external,
-        trust: "source_verified",
-      };
-      void sourceVerifiedMintInput;
-    }
+    // @ts-expect-error Source-verified trust is derived with provider proof by the application.
+    const sourceVerifiedMintInput: EvaluationReceiptMintInputV1 = {
+      ...external,
+      trust: "source_verified",
+    };
+    void sourceVerifiedMintInput;
     expect(evaluationReceiptMintInputV1Schema.parse(external)).toEqual(external);
     expect(() =>
       evaluationReceiptMintInputV1Schema.parse({ ...external, authority: "enforcement_eligible" })

package/src/evaluation/index.ts

@@ -3,7 +3,7 @@
  * Adapters: `packages/cli/src/govern/evaluation.ts` and
  * `apps/cloud/src/lib/govern/evaluation-adapter.ts`.
  */
-export { evaluate } from "./evaluate.js";
+export { evaluate, evaluationInputDigestV2, evaluationResultDigestV2 } from "./evaluate.js";
 export { EVALUATOR_VERSION, EVALUATOR_VERSION_V2 } from "./types.js";
 export {
   EVALUATION_MAX_FINDINGS_V2,

package/src/facts/builders.ts

@@ -122,6 +122,7 @@ export function makeComponentDefinitionFact(input: {
   componentKey: string;
   renderRoot: ComponentDefinitionFact["renderRoot"];
   propSurface: string[];
+  location?: FactLocation;
   stylingChannel?: ComponentDefinitionFact["stylingChannel"];
 }): ComponentDefinitionFact {
   return {
@@ -134,6 +135,7 @@ export function makeComponentDefinitionFact(input: {
     componentKey: input.componentKey,
     renderRoot: input.renderRoot,
     propSurface: [...input.propSurface],
+    ...(input.location ? { location: { ...input.location } } : {}),
     ...(input.stylingChannel ? { stylingChannel: { ...input.stylingChannel } } : {}),
   };
 }
@@ -664,6 +666,7 @@ export function makeUsageNodeFact(input: {
 export function makeUsageComponentFact(input: {
   nodeId: FactId;
   componentId: ComponentId;
+  definitionKey?: string;
 }): UsageComponentFact {
   return {
     id: factId("usage_component", {
@@ -673,6 +676,7 @@ export function makeUsageComponentFact(input: {
     kind: "usage_component",
     nodeId: input.nodeId,
     componentId: input.componentId,
+    ...(input.definitionKey ? { definitionKey: input.definitionKey } : {}),
   };
 }
 

package/src/facts/fact-index.ts

@@ -87,6 +87,10 @@ function logicalFactForComparison(fact: Fact): Record<string, unknown> {
     const { location: _location, sourceNames: _sourceNames, ...logicalFact } = fact;
     return logicalFact;
   }
+  if (fact.kind === "component_definition") {
+    const { location: _location, ...logicalFact } = fact;
+    return { ...logicalFact, componentId: logicalComponentId(fact.componentId) };
+  }
   if (fact.kind === "jsx_import_path_preferred") {
     return {
       ...fact,

package/src/facts/facts.test.ts

@@ -549,6 +549,76 @@ describe("FactIndex — query layer", () => {
     expect(ix.get(first.id)).toEqual(first);
   });
 
+  it.each(["missing-first", "missing-second", "moved"] as const)(
+    "coalesces component definitions when only their evidence region differs (%s)",
+    (mode) => {
+      const onConflict = vi.fn();
+      const onDuplicate = vi.fn();
+      const ix = new FactIndex({ onConflict, onDuplicate });
+      const definition = {
+        file: "src/Button.tsx",
+        exportName: "Button",
+        exported: true,
+        componentKey: "src/Button.tsx#Button",
+        renderRoot: { resolution: "intrinsic", tag: "button" } as const,
+        propSurface: ["disabled"],
+      };
+      const first = makeComponentDefinitionFact({
+        ...definition,
+        ...(mode !== "missing-first"
+          ? { location: { file: definition.file, line: 2, column: 0, endLine: 4, endColumn: 1 } }
+          : {}),
+      });
+      const second = makeComponentDefinitionFact({
+        ...definition,
+        ...(mode !== "missing-second"
+          ? { location: { file: definition.file, line: 6, column: 0, endLine: 8, endColumn: 1 } }
+          : {}),
+      });
+
+      ix.addMany([first, second]);
+
+      expect(onConflict).not.toHaveBeenCalled();
+      expect(onDuplicate).toHaveBeenCalledTimes(1);
+      expect(onDuplicate).toHaveBeenCalledWith({ kept: first, duplicate: second });
+      expect(ix.byKind("component_definition")).toEqual([first]);
+    }
+  );
+
+  it.each([
+    { renderRoot: { resolution: "intrinsic", tag: "a" } as const },
+    { propSurface: ["disabled", "href"] },
+    { exported: false },
+  ])("retains component-definition conflicts for material changes: %j", (change) => {
+    const onConflict = vi.fn();
+    const onDuplicate = vi.fn();
+    const ix = new FactIndex({ onConflict, onDuplicate });
+    const definition = {
+      file: "src/Button.tsx",
+      exportName: "Button",
+      exported: true,
+      componentKey: "src/Button.tsx#Button",
+      renderRoot: { resolution: "intrinsic", tag: "button" } as const,
+      propSurface: ["disabled"],
+    };
+    const first = makeComponentDefinitionFact(definition);
+    const second = makeComponentDefinitionFact({
+      ...definition,
+      ...change,
+      location: { file: definition.file, line: 2, column: 0, endLine: 4, endColumn: 1 },
+    });
+
+    ix.addMany([first, second]);
+
+    expect(onConflict).toHaveBeenCalledTimes(1);
+    expect(onConflict).toHaveBeenCalledWith(expect.stringContaining("conflicting facts"), {
+      kept: first,
+      skipped: second,
+    });
+    expect(onDuplicate).not.toHaveBeenCalled();
+    expect(ix.byKind("component_definition")).toEqual([first]);
+  });
+
   it("includes token-definition provenance in logical conflict reports", () => {
     const onConflict = vi.fn();
     const ix = new FactIndex({ onConflict });

package/src/facts/types.ts

@@ -317,6 +317,8 @@ export interface UsageComponentFact extends BaseFact {
   kind: "usage_component";
   nodeId: FactId;
   componentId: ComponentId;
+  /** Exact local definition resolved from source, separate from catalog/policy identity. */
+  definitionKey?: string;
 }
 
 export interface UsageImportFact extends BaseFact {
@@ -688,6 +690,8 @@ export interface ComponentDefinitionFact extends BaseFact {
   componentKey: string;
   renderRoot: ComponentDefinitionRenderRoot;
   propSurface: string[];
+  /** Implementation region, used to scope exemptions; never part of fact identity. */
+  location?: FactLocation;
   stylingChannel?: {
     module: string;
     ownsVisualRole: boolean;

package/src/governance.ts

@@ -172,6 +172,24 @@ export const componentGovernanceRecordSchema = z.discriminatedUnion("kind", [
 
 export const componentGovernanceRecordsSchema = z.array(componentGovernanceRecordSchema);
 
+/** Parse portable component policy records; malformed authority is unavailable, never empty. */
+export function parseComponentGovernancePolicyJson(
+  policyJson: string
+): ComponentGovernanceRecord[] | null {
+  try {
+    const parsed: unknown = JSON.parse(policyJson);
+    const record =
+      parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : null;
+    const candidate = Array.isArray(parsed) ? parsed : (record?.governance ?? record?.rules);
+    const result = componentGovernanceRecordsSchema.safeParse(candidate);
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+
 const componentPolicyMatchSchema = z
   .object({
     componentKey: z.string().min(1).optional(),