@usefragments/core 1.4.0 → 1.5.1

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-DxdJV6lx.js';
+export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-B88uR3Zq.js';
 import 'zod';
 import './topology/index.js';
 import './types-xJ2xyp_G.js';

package/dist/registry.d.ts

@@ -216,7 +216,7 @@ declare const registryComponentSchema: z.ZodObject<{
     componentId: string;
     name: string;
     publicRef: string;
-    tier: "custom" | "utility" | "composition" | "core";
+    tier: "core" | "custom" | "utility" | "composition";
     examples: unknown[];
     files: {
         path: string;
@@ -264,7 +264,7 @@ declare const registryComponentSchema: z.ZodObject<{
     provenance?: Record<string, unknown> | undefined;
     category?: string | undefined;
     contract?: unknown;
-    tier?: "custom" | "utility" | "composition" | "core" | undefined;
+    tier?: "core" | "custom" | "utility" | "composition" | undefined;
     examples?: unknown[] | undefined;
     styleFiles?: string[] | undefined;
     tokenDependencies?: string[] | undefined;
@@ -498,7 +498,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "custom" | "utility" | "composition" | "core";
+        tier: "core" | "custom" | "utility" | "composition";
         examples: unknown[];
         files: {
             path: string;
@@ -546,7 +546,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "custom" | "utility" | "composition" | "core" | undefined;
+        tier?: "core" | "custom" | "utility" | "composition" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -611,7 +611,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "custom" | "utility" | "composition" | "core";
+        tier: "core" | "custom" | "utility" | "composition";
         examples: unknown[];
         files: {
             path: string;
@@ -713,7 +713,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "custom" | "utility" | "composition" | "core" | undefined;
+        tier?: "core" | "custom" | "utility" | "composition" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -971,7 +971,7 @@ declare const registryManifestSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "custom" | "utility" | "composition" | "core";
+        tier: "core" | "custom" | "utility" | "composition";
         examples: unknown[];
         files: {
             path: string;
@@ -1019,7 +1019,7 @@ declare const registryManifestSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "custom" | "utility" | "composition" | "core" | undefined;
+        tier?: "core" | "custom" | "utility" | "composition" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -1086,7 +1086,7 @@ declare const registryManifestSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "custom" | "utility" | "composition" | "core";
+        tier: "core" | "custom" | "utility" | "composition";
         examples: unknown[];
         files: {
             path: string;
@@ -1189,7 +1189,7 @@ declare const registryManifestSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "custom" | "utility" | "composition" | "core" | undefined;
+        tier?: "core" | "custom" | "utility" | "composition" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -1450,7 +1450,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "custom" | "utility" | "composition" | "core";
+            tier: "core" | "custom" | "utility" | "composition";
             examples: unknown[];
             files: {
                 path: string;
@@ -1498,7 +1498,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "custom" | "utility" | "composition" | "core" | undefined;
+            tier?: "core" | "custom" | "utility" | "composition" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;
@@ -1565,7 +1565,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "custom" | "utility" | "composition" | "core";
+            tier: "core" | "custom" | "utility" | "composition";
             examples: unknown[];
             files: {
                 path: string;
@@ -1668,7 +1668,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "custom" | "utility" | "composition" | "core" | undefined;
+            tier?: "core" | "custom" | "utility" | "composition" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;
@@ -1773,7 +1773,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "custom" | "utility" | "composition" | "core";
+            tier: "core" | "custom" | "utility" | "composition";
             examples: unknown[];
             files: {
                 path: string;
@@ -1886,7 +1886,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "custom" | "utility" | "composition" | "core" | undefined;
+            tier?: "core" | "custom" | "utility" | "composition" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;
@@ -1979,7 +1979,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "custom" | "utility" | "composition" | "core";
+            tier: "core" | "custom" | "utility" | "composition";
             examples: unknown[];
             files: {
                 path: string;
@@ -2092,7 +2092,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "custom" | "utility" | "composition" | "core" | undefined;
+            tier?: "core" | "custom" | "utility" | "composition" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;

package/dist/schemas/index.d.ts

@@ -1,3 +1,3 @@
 import 'zod';
 export { LegacySeverityLevel, Severity, SeverityLevel, legacySeverityLevelSchema, severityLevelSchema, severitySchema } from '../severity.js';
-export { b as AGENT_FORMAT_SCHEMA_VERSION, c as AgentErrorEnvelope, A as AgentFormat, d as AgentOutput, Q as FactEvidence, R as FactLocation, F as Finding, a as FindingFix, f as FindingReplaceClassTokenFix, g as FindingReplaceComponentFix, h as FindingReplaceImportFix, i as FindingReplacePropValueFix, j as FindingReplaceStyleValueFix, k as Fix, G as GovernanceVerdict, l as GovernanceVerdictMetadata, S as SuppressionDirective, V as ValidatorResult, n as Violation, o as agentErrorEnvelopeSchema, T as agentFindingSchema, p as agentFormatSchema, q as agentIntegritySchema, r as agentOutputSchema, U as agentPlanSchema, t as factEvidenceSchema, u as factLocationSchema, v as findingFixSchema, w as findingReplaceClassTokenFixSchema, x as findingReplaceComponentFixSchema, y as findingReplaceImportFixSchema, z as findingReplacePropValueFixSchema, B as findingReplaceStyleValueFixSchema, C as findingSchema, D as fixSchema, H as governanceVerdictMetadataSchema, J as governanceVerdictSchema, K as normalizeFinding, L as normalizeSeverity, M as normalizeViolation, N as suppressionDirectiveSchema, O as validatorResultSchema, P as violationSchema } from '../index-0lmh0Lbo.js';
+export { b as AGENT_FORMAT_SCHEMA_VERSION, c as AgentErrorEnvelope, A as AgentFormat, d as AgentOutput, Q as FactEvidence, R as FactLocation, F as Finding, a as FindingFix, f as FindingReplaceClassTokenFix, g as FindingReplaceComponentFix, h as FindingReplaceImportFix, i as FindingReplacePropValueFix, j as FindingReplaceStyleValueFix, k as Fix, G as GovernanceVerdict, l as GovernanceVerdictMetadata, S as SuppressionDirective, V as ValidatorResult, n as Violation, o as agentErrorEnvelopeSchema, T as agentFindingSchema, p as agentFormatSchema, q as agentIntegritySchema, r as agentOutputSchema, U as agentPlanSchema, t as factEvidenceSchema, u as factLocationSchema, v as findingFixSchema, w as findingReplaceClassTokenFixSchema, x as findingReplaceComponentFixSchema, y as findingReplaceImportFixSchema, z as findingReplacePropValueFixSchema, B as findingReplaceStyleValueFixSchema, C as findingSchema, D as fixSchema, H as governanceVerdictMetadataSchema, J as governanceVerdictSchema, K as normalizeFinding, L as normalizeSeverity, M as normalizeViolation, N as suppressionDirectiveSchema, O as validatorResultSchema, P as violationSchema } from '../index-DbkPE46t.js';

package/dist/schemas/index.js

@@ -24,7 +24,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "../chunk-57QDBEHQ.js";
+} from "../chunk-ZHS52OT4.js";
 import {
   legacySeverityLevelSchema,
   severityLevelSchema,

package/dist/test-utils.d.ts

@@ -1,4 +1,4 @@
-import { C as CompiledBlock, b as CompiledFragment } from './governance-DxdJV6lx.js';
+import { C as CompiledBlock, b as CompiledFragment } from './governance-B88uR3Zq.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/package.json

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

package/src/agent-format.test.ts

@@ -232,6 +232,7 @@ describe("buildAgentFormat", () => {
         scope: { method: "full", gitOk: true },
         engineVersion: `sha256:${"b".repeat(64)}`,
         scopeHash: "c".repeat(64),
+        inputsHash: "e".repeat(64),
         inputFilesHash: "d".repeat(64),
       },
       verdict: { exitCode: 0, reasons: [], gatingFindingCount: 0 },

package/src/canonical-bridge.ts

@@ -0,0 +1,46 @@
+import type { ContractCanonicalMappingInput } from "./contract/preimage.js";
+import type { CanonicalBridgeV1 } from "./governance.js";
+import { ownedImportMatchesRoot } from "./package-identity-match.js";
+
+export function canonicalBridgeUnderlyingKey(input: {
+  packageName: string;
+  exportName: string;
+}): string {
+  return `${input.packageName}\u0000${input.exportName}`;
+}
+
+export function canonicalBridgeContractMappings(
+  bridges: readonly CanonicalBridgeV1[] | undefined
+): ContractCanonicalMappingInput[] {
+  return (bridges ?? []).map((bridge) => ({
+    component: `${bridge.underlying.packageName}#${bridge.underlying.exportName}`,
+    canonical: bridge.local.componentKey,
+    status: "confirmed",
+    importPath: bridge.local.moduleSpecifier,
+    bridge: {
+      underlyingPackageName: bridge.underlying.packageName,
+      underlyingExportName: bridge.underlying.exportName,
+      localComponentKey: bridge.local.componentKey,
+      localExportName: bridge.local.exportName,
+      implementationFiles: [...bridge.local.implementationFiles],
+      decisionSource: bridge.decision.source,
+    },
+  }));
+}
+
+export function canonicalBridgeMatchesUnderlyingImport(
+  bridge: CanonicalBridgeV1,
+  source: string,
+  imported: string
+): boolean {
+  if (!ownedImportMatchesRoot(source, bridge.underlying.packageName)) return false;
+  if (source === bridge.underlying.packageName) {
+    return imported === bridge.underlying.exportName;
+  }
+  const subpath = source.slice(bridge.underlying.packageName.length + 1);
+  const leaf = subpath.split("/").at(-1);
+  return (
+    leaf === bridge.underlying.exportName &&
+    (imported === "default" || imported === bridge.underlying.exportName)
+  );
+}

package/src/canonical-direction.ts

@@ -0,0 +1,118 @@
+import type { CanonicalSource } from "./governance.js";
+import type { FactIndex } from "./facts/index.js";
+import { ownedImportMatchesRoot } from "./package-identity-match.js";
+
+export interface CanonicalDirectionConflict {
+  packageName: string;
+  exportName: string;
+  wrapperComponentKey: string;
+  wrapperFile: string;
+  wrapperExportName: string;
+  state: "unresolved" | "sanctioned";
+}
+
+/**
+ * Project exact, source-backed conflicts between an exported local wrapper and
+ * an npm canonical export. Name similarity, prop overlap, and mixed render
+ * trees are deliberately insufficient: this projection can deactivate policy.
+ */
+export function projectCanonicalDirectionConflicts(
+  ix: FactIndex,
+  canonicalSources: readonly CanonicalSource[]
+): CanonicalDirectionConflict[] {
+  const npmSources = canonicalSources.filter(
+    (source): source is Extract<CanonicalSource, { kind: "npm" }> => source.kind === "npm"
+  );
+  if (npmSources.length === 0) return [];
+
+  const identityByComponent = new Map(
+    ix.byKind("component_identity").map((identity) => [identity.componentKey, identity])
+  );
+  const conflicts: CanonicalDirectionConflict[] = [];
+
+  for (const definition of ix.byKind("component_definition")) {
+    if (!definition.exported || definition.renderRoot.resolution !== "canonical") continue;
+    const target = npmTarget(definition.renderRoot.canonical, npmSources);
+    if (!target) continue;
+
+    const identity = identityByComponent.get(definition.componentKey);
+    if (
+      identity?.decisionId &&
+      decisionTargetsExport(identity.canonicalTarget, target.exportName)
+    ) {
+      if (identity.state === "shadow") continue;
+      if (identity.state === "variant" && identity.confidence === "confirmed") {
+        conflicts.push({
+          ...target,
+          wrapperComponentKey: definition.componentKey,
+          wrapperFile: definition.file,
+          wrapperExportName: definition.exportName,
+          state: "sanctioned",
+        });
+        continue;
+      }
+    }
+
+    conflicts.push({
+      ...target,
+      wrapperComponentKey: definition.componentKey,
+      wrapperFile: definition.file,
+      wrapperExportName: definition.exportName,
+      state: "unresolved",
+    });
+  }
+
+  return conflicts.sort(
+    (left, right) =>
+      left.packageName.localeCompare(right.packageName) ||
+      left.exportName.localeCompare(right.exportName) ||
+      left.wrapperComponentKey.localeCompare(right.wrapperComponentKey)
+  );
+}
+
+export function canonicalDirectionConflictsTarget(
+  conflicts: readonly CanonicalDirectionConflict[],
+  importPath: string | undefined,
+  exportName: string
+): boolean {
+  if (!importPath) return false;
+  return conflicts.some(
+    (conflict) =>
+      ownedImportMatchesRoot(importPath, conflict.packageName) && conflict.exportName === exportName
+  );
+}
+
+function npmTarget(
+  canonicalTarget: string,
+  sources: readonly Extract<CanonicalSource, { kind: "npm" }>[]
+): { packageName: string; exportName: string } | null {
+  const separator = canonicalTarget.lastIndexOf("#");
+  if (separator <= 0 || separator === canonicalTarget.length - 1) return null;
+  const importPath = canonicalTarget.slice(0, separator);
+  const imported = canonicalTarget
+    .slice(separator + 1)
+    .split(".")
+    .at(-1);
+  if (!imported) return null;
+
+  for (const source of sources) {
+    if (!ownedImportMatchesRoot(importPath, source.specifier)) continue;
+    const subpath = packageSubpath(importPath, source.specifier);
+    const exportName =
+      imported === "default" ? subpath.split("/").filter(Boolean).at(-1) : imported;
+    if (!exportName) continue;
+    if (source.exclude?.includes(exportName)) continue;
+    if (source.include && !source.include.includes(exportName)) continue;
+    return { packageName: source.specifier, exportName };
+  }
+  return null;
+}
+
+function packageSubpath(importPath: string, packageName: string): string {
+  return importPath === packageName ? "" : importPath.slice(packageName.length + 1);
+}
+
+function decisionTargetsExport(target: string | undefined, exportName: string): boolean {
+  if (!target) return true;
+  return target === exportName || target.split("#").at(-1)?.split(".").at(-1) === exportName;
+}

package/src/codes/codes.ts

@@ -108,6 +108,15 @@ export const CODES = [
     fixAvailable: false,
     evidenceRequired: true,
   }),
+  ruleCode({
+    code: "FUI1007",
+    ruleId: "components/shadow-component",
+    category: "canonical-usage",
+    defaultSeverity: "moderate",
+    title: "Component shadows a canonical primitive",
+    lifecycle: "experimental",
+    evidenceRequired: true,
+  }),
   code({
     code: "FUI2001",
     ruleId: "tokens/require-design-tokens",
@@ -255,6 +264,15 @@ export const CODES = [
     lifecycle: "experimental",
     evidenceRequired: true,
   }),
+  ruleCode({
+    code: "FUI2017",
+    ruleId: "tokens/upstream-drift",
+    category: "tokens",
+    defaultSeverity: "moderate",
+    title: "Local token differs from its declared upstream source",
+    lifecycle: "experimental",
+    evidenceRequired: true,
+  }),
   ruleCode({
     code: "FUI3001",
     ruleId: "a11y/required-accessible-name",

package/src/conform.ts

@@ -20,6 +20,11 @@ export interface ConformInput {
   filename?: string;
   /** deterministic (default) applies safe edits; none returns findings only. */
   apply?: "deterministic" | "none";
+  /** Explicit request to consolidate a known shadow into its canonical root. */
+  shadowConsolidation?: {
+    shadow: string;
+    canonicalTarget?: string;
+  };
 }
 
 export interface ConformLocation {

package/src/contract/preimage.test.ts

@@ -162,6 +162,46 @@ describe("§3 proposed mappings are not identity", () => {
   });
 });
 
+describe("confirmed canonical bridge identity", () => {
+  const bridgeMapping = {
+    component: "@mui/material#Button",
+    canonical: "src/components/Button.tsx#Button",
+    status: "confirmed" as const,
+    importPath: "@/components",
+    bridge: {
+      underlyingPackageName: "@mui/material",
+      underlyingExportName: "Button",
+      localComponentKey: "src/components/Button.tsx#Button",
+      localExportName: "Button",
+      implementationFiles: ["src/components/Button.tsx"],
+      decisionSource: "authored" as const,
+    },
+  };
+
+  it("moves only canonicalMap when enforcement changes, not when provenance changes", () => {
+    const base = projectContractPreimage({ canonicalMappings: [bridgeMapping] });
+    const changedEnforcement = projectContractPreimage({
+      canonicalMappings: [
+        {
+          ...bridgeMapping,
+          bridge: { ...bridgeMapping.bridge, implementationFiles: ["src/ui/Button.tsx"] },
+        },
+      ],
+    });
+    const changedProvenance = projectContractPreimage({
+      canonicalMappings: [
+        {
+          ...bridgeMapping,
+          bridge: { ...bridgeMapping.bridge, decisionSource: "migration" as const },
+        },
+      ],
+    });
+
+    expect(diffContractDomains(base, changedEnforcement)).toEqual(["canonicalMap"]);
+    expect(changedProvenance).toEqual(base);
+  });
+});
+
 describe("§4 domain diff names what moved", () => {
   it("confirming a mapping + adding a composition rule changes canonicalMap and policy", () => {
     const preimageBase = projectContractPreimage(catalogFixtureA);

package/src/contract/preimage.ts

@@ -87,6 +87,15 @@ export interface ContractCanonicalMappingInput {
   status: CanonicalMappingStatus;
   /** Local/offline canonical import target, when the mapping is config-authored. */
   importPath?: string;
+  /** Confirmed package-to-local relation metadata. Absent for legacy mappings. */
+  bridge?: {
+    underlyingPackageName: string;
+    underlyingExportName: string;
+    localComponentKey: string;
+    localExportName: string;
+    implementationFiles: readonly string[];
+    decisionSource: "authored" | "migration";
+  };
   /** Explicit raw element or semantic resolutions covered by a local declaration. */
   resolves?: readonly {
     tag: string;
@@ -253,6 +262,17 @@ function projectCanonicalMap(
         importPath: mapping.importPath
           ? projectV1OwnedImportIdentity(mapping.importPath)
           : undefined,
+        bridge: mapping.bridge
+          ? {
+              underlyingPackageName: projectV1OwnedImportIdentity(
+                mapping.bridge.underlyingPackageName
+              ),
+              underlyingExportName: mapping.bridge.underlyingExportName,
+              localComponentKey: projectV1OwnedComponentId(mapping.bridge.localComponentKey),
+              localExportName: mapping.bridge.localExportName,
+              implementationFiles: [...mapping.bridge.implementationFiles].sort(),
+            }
+          : undefined,
         resolves: mapping.resolves ? sortCanonical(mapping.resolves) : undefined,
         propMapping: mapping.propMapping
           ? sortCanonical(

package/src/effective-governance-inputs.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+
+import { compileEffectiveGovernanceInputs } from "./effective-governance-inputs.js";
+
+function fixture() {
+  return compileEffectiveGovernanceInputs({
+    policySource: "config",
+    configPath: "./fragments.config.ts",
+    configDigest: "a".repeat(64),
+    policy: {
+      canonicalBridges: [
+        {
+          underlying: { packageName: "@mui/material", exportName: "Button" },
+          local: {
+            componentKey: "src/components/Button.tsx#Button",
+            moduleSpecifier: "@/components/Button",
+            exportName: "Button",
+            implementationFiles: ["src/components/Button.tsx"],
+          },
+          decision: { state: "confirmed", source: "authored" },
+        },
+      ],
+    },
+    componentDefinitionFiles: ["src/components/Button.tsx"],
+    tokens: { declared: [], loadedDefinitions: 0, diagnostics: [] },
+    eligibility: { include: ["src/**/*.tsx"], exclude: ["src/**/*.stories.tsx"] },
+  });
+}
+
+describe("compileEffectiveGovernanceInputs", () => {
+  it("normalizes operational inputs into a separate stable identity", () => {
+    const first = fixture();
+    const second = fixture();
+    expect(first).toEqual(second);
+    expect(first.inputsHash).toMatch(/^[a-f0-9]{64}$/u);
+    expect(first.config.path).toBe("fragments.config.ts");
+  });
+
+  it("moves inputsHash for config/source state without changing contract identity here", () => {
+    const first = fixture();
+    const next = compileEffectiveGovernanceInputs({
+      policySource: first.policySource,
+      configPath: first.config.path,
+      configDigest: "b".repeat(64),
+      policy: { canonicalBridges: first.components.canonicalBridges },
+      componentDefinitionFiles: first.components.definitionFiles,
+      tokens: { declared: [], loadedDefinitions: 0, diagnostics: [] },
+      eligibility: first.eligibility,
+    });
+    expect(next.inputsHash).not.toBe(first.inputsHash);
+  });
+});

package/src/effective-governance-inputs.ts

@@ -0,0 +1,106 @@
+import { canonicalPreimage, contractHash } from "./contract/hash.js";
+import type { GovernanceConfig } from "./governance.js";
+import type { TokenCatalog } from "./token-types.js";
+
+export const EFFECTIVE_GOVERNANCE_INPUTS_SCHEMA = "effective-governance-inputs:v1" as const;
+
+export interface EffectiveGovernanceInputsSourceState {
+  declared: readonly string[];
+  loadedDefinitions: number;
+  diagnostics: readonly string[];
+  catalog?: TokenCatalog;
+}
+
+export interface CompileEffectiveGovernanceInputsOptions {
+  policySource: "config" | "preset" | "fallback" | "none";
+  configPath: string | null;
+  configDigest: string | null;
+  policy: GovernanceConfig | undefined;
+  componentDefinitionFiles: readonly string[];
+  tokens: EffectiveGovernanceInputsSourceState;
+  eligibility: {
+    include: readonly string[];
+    exclude: readonly string[];
+  };
+}
+
+export interface EffectiveGovernanceInputs {
+  schema: typeof EFFECTIVE_GOVERNANCE_INPUTS_SCHEMA;
+  policySource: CompileEffectiveGovernanceInputsOptions["policySource"];
+  config: { path: string | null; digest: string | null };
+  components: {
+    canonicalSources: NonNullable<GovernanceConfig["canonicalSources"]>;
+    canonicalBridges: NonNullable<GovernanceConfig["canonicalBridges"]>;
+    definitionFiles: string[];
+  };
+  tokens: {
+    declared: string[];
+    loadedDefinitions: number;
+    diagnostics: string[];
+    catalog?: TokenCatalog;
+  };
+  eligibility: { include: string[]; exclude: string[] };
+  inputsHash: string;
+}
+
+/**
+ * Compile one deterministic, post-authority account of the operational inputs
+ * available to governance consumers. This is deliberately distinct from FCID
+ * (enforced contract identity) and scopeHash (the files selected for one Run).
+ */
+export function compileEffectiveGovernanceInputs(
+  options: CompileEffectiveGovernanceInputsOptions
+): EffectiveGovernanceInputs {
+  const projection = {
+    schema: EFFECTIVE_GOVERNANCE_INPUTS_SCHEMA,
+    policySource: options.policySource,
+    config: {
+      path: options.configPath ? normalizePath(options.configPath) : null,
+      digest: options.configDigest,
+    },
+    components: {
+      canonicalSources: sortRecords(options.policy?.canonicalSources ?? []),
+      canonicalBridges: sortRecords(options.policy?.canonicalBridges ?? []),
+      definitionFiles: normalizePaths(options.componentDefinitionFiles),
+    },
+    tokens: {
+      declared: normalizePaths(options.tokens.declared),
+      loadedDefinitions: options.tokens.loadedDefinitions,
+      diagnostics: [...options.tokens.diagnostics].sort(),
+      ...(options.tokens.catalog
+        ? {
+            catalog: {
+              ...options.tokens.catalog,
+              configuredSources: normalizePaths(options.tokens.catalog.configuredSources),
+              parsedSources: normalizePaths(options.tokens.catalog.parsedSources),
+              definitions: sortRecords(options.tokens.catalog.definitions),
+              diagnostics: sortRecords(options.tokens.catalog.diagnostics),
+              references: sortRecords(options.tokens.catalog.references),
+              ...(options.tokens.catalog.sourceStates
+                ? { sourceStates: sortRecords(options.tokens.catalog.sourceStates) }
+                : {}),
+            },
+          }
+        : {}),
+    },
+    eligibility: {
+      include: normalizePaths(options.eligibility.include),
+      exclude: normalizePaths(options.eligibility.exclude),
+    },
+  };
+  return { ...projection, inputsHash: contractHash(projection) };
+}
+
+function normalizePaths(values: readonly string[]): string[] {
+  return [...new Set(values.map(normalizePath))].sort();
+}
+
+function normalizePath(value: string): string {
+  return value.replace(/\\/gu, "/").replace(/^\.\//u, "");
+}
+
+function sortRecords<T>(values: readonly T[]): T[] {
+  return [...values].sort((left, right) =>
+    canonicalPreimage(left).localeCompare(canonicalPreimage(right))
+  );
+}