@usefragments/core 2.0.2 → 2.1.0

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-hOPXGbbs.js';
+import { F as FragmentDefinition } from './source-identity-DvOBz2yJ.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-hOPXGbbs.js';
+import './source-identity-DvOBz2yJ.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/package.json

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

package/src/conform.ts

@@ -11,6 +11,11 @@
  * surface agree on one shape without duplication.
  */
 
+import type {
+  ContractComponentSource,
+  ContractComponentExport,
+} from "./contract/source-identity.js";
+
 export type ConformConfidence = "high" | "medium" | "low";
 
 export interface ConformInput {
@@ -82,6 +87,9 @@ export interface ConformPropMapping {
 }
 
 export interface ConformComponentMapping {
+  /** Portable authority, interpreted only under the context's generation marker. */
+  source?: ContractComponentSource;
+  exportAddresses?: readonly ContractComponentExport[];
   /**
    * Canonical primitive name, e.g. "Button". This is the JSX identifier the
    * conform engine rewrites toward.
@@ -158,6 +166,8 @@ export interface ConformToken {
  * each surface (cloud from Convex, CLI from local config, MCP from a bundle).
  */
 export interface DesignSystemContext {
+  /** Additive generation boundary; unmarked contexts retain legacy behavior. */
+  sourceIdentitySchema?: "component-source:v1";
   designSystemName?: string;
   tokens: ConformToken[];
   /** Confirmed canonical component replacements for this tenant. */

package/src/contract/index.ts

@@ -12,6 +12,10 @@ export {
   CONTRACT_ENFORCEMENT_FIELDS,
   CONTRACT_PREIMAGE_CAPABILITY_HEADER,
   CONTRACT_PREIMAGE_SCHEMA,
+  CONTRACT_PREIMAGE_SCHEMA_V2,
+  CONTRACT_PREIMAGE_CAPABILITIES,
+  SUPPORTED_CONTRACT_PREIMAGE_SCHEMAS,
+  isSupportedContractPreimageSchema,
   ContractCatalogValidationError,
   contractComponentsFromFragments,
   contractPolicyFromGovernanceConfig,
@@ -31,6 +35,7 @@ export type {
   ContractIdentityPin,
   ContractPolicyInput,
   ContractPreimage,
+  ContractPreimageSchema,
   ContractPropMappingInput,
   ContractTokenInput,
   ContractWaiverInput,
@@ -67,3 +72,22 @@ export type {
   FragmentsManifestPattern,
   FragmentsManifestPrimitive,
 } from "./manifest.js";
+
+export {
+  contractComponentSourceKey,
+  approvedComponentGovernanceByteLimit,
+  APPROVED_COMPONENT_GOVERNANCE_LEGACY_MAX_BYTES,
+  APPROVED_COMPONENT_GOVERNANCE_QUALIFIED_MAX_BYTES,
+  contractSourceFromFragment,
+  normalizeContractComponentSource,
+  normalizeContractSourcePath,
+  contractComponentsFromFragmentsV2,
+  projectContractPreimageV2,
+} from "./source-identity.js";
+export type {
+  ContractComponentSource,
+  ContractComponentExport,
+  ContractComponentInputV2,
+  ContractCanonicalMappingInputV2,
+  ContractCatalogInputV2,
+} from "./source-identity.js";

package/src/contract/preimage.ts

@@ -24,6 +24,7 @@
  *
  * Runtime-portable by construction: no Node APIs, no Convex imports, no React.
  */
+import type { ContractComponentSource } from "./source-identity.js";
 import type { ComponentGovernanceRecord, GovernanceConfig } from "../governance.js";
 import { resolveGovernanceRecordsForIdentity } from "../governance.js";
 import { projectV1OwnedComponentId, projectV1OwnedImportIdentity } from "../package-identity.js";
@@ -110,6 +111,8 @@ export interface ContractPropMappingInput {
 }
 
 export interface ContractCanonicalMappingInput {
+  /** Source-qualified identity, required by the V2 projection; ignored by immutable V1. */
+  source?: ContractComponentSource;
   /** The raw/source component the mapping covers. */
   component: string;
   /** The canonical component it maps to. */
@@ -190,6 +193,17 @@ export class ContractCatalogValidationError extends TypeError {
 // ---------------------------------------------------------------------------
 
 export const CONTRACT_PREIMAGE_SCHEMA = "fcid-preimage:v1" as const;
+export const CONTRACT_PREIMAGE_SCHEMA_V2 = "fcid-preimage:v2" as const;
+export const SUPPORTED_CONTRACT_PREIMAGE_SCHEMAS = [
+  CONTRACT_PREIMAGE_SCHEMA_V2,
+  CONTRACT_PREIMAGE_SCHEMA,
+] as const;
+export type ContractPreimageSchema = (typeof SUPPORTED_CONTRACT_PREIMAGE_SCHEMAS)[number];
+export const CONTRACT_PREIMAGE_CAPABILITIES = SUPPORTED_CONTRACT_PREIMAGE_SCHEMAS.join(", ");
+
+export function isSupportedContractPreimageSchema(value: unknown): value is ContractPreimageSchema {
+  return value === CONTRACT_PREIMAGE_SCHEMA || value === CONTRACT_PREIMAGE_SCHEMA_V2;
+}
 /** Request header used by clients that can verify and consume this preimage. */
 export const CONTRACT_PREIMAGE_CAPABILITY_HEADER = "X-Fragments-Contract-Preimage" as const;
 
@@ -199,7 +213,7 @@ export const CONTRACT_PREIMAGE_CAPABILITY_HEADER = "X-Fragments-Contract-Preimag
  * `contractHash(preimage)` — hash of the domain hashes, per the spine pipeline.
  */
 export interface ContractPreimage {
-  schema: typeof CONTRACT_PREIMAGE_SCHEMA;
+  schema: ContractPreimageSchema;
   domains: Record<ContractDomain, string>;
 }
 
@@ -226,7 +240,7 @@ const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/u;
  */
 export function verifiedContractPreimageFromPin(pin: ContractIdentityPin): ContractPreimage | null {
   if (
-    pin.preimageSchema !== CONTRACT_PREIMAGE_SCHEMA ||
+    !isSupportedContractPreimageSchema(pin.preimageSchema) ||
     !SHA256_HEX_PATTERN.test(pin.contractHash) ||
     !pin.domainHashes ||
     typeof pin.domainHashes !== "object"
@@ -251,7 +265,7 @@ export function verifiedContractPreimageFromPin(pin: ContractIdentityPin): Contr
   }
 
   const preimage: ContractPreimage = {
-    schema: CONTRACT_PREIMAGE_SCHEMA,
+    schema: pin.preimageSchema,
     domains: domains as Record<ContractDomain, string>,
   };
   return contractHash(preimage) === pin.contractHash ? preimage : null;

package/src/contract/source-identity.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, it } from "vitest";
+import { contractHash } from "./hash.js";
+import { catalogFixtureA, CATALOG_FIXTURE_A_FCID } from "./fixture.js";
+import {
+  CONTRACT_PREIMAGE_SCHEMA_V2,
+  projectContractPreimage,
+  verifiedContractPreimageFromPin,
+} from "./preimage.js";
+import {
+  approvedComponentGovernanceByteLimit,
+  contractComponentsFromFragmentsV2,
+  contractComponentSourceKey,
+  projectContractPreimageV2,
+} from "./source-identity.js";
+
+const fragments = [
+  {
+    meta: { name: "Button" },
+    filePath: "first/Button.tsx",
+    props: { label: { required: true } },
+    exports: [{ exportedAs: "Button", filePath: "first/index.ts" }],
+  },
+  {
+    meta: { name: "Button" },
+    filePath: "second/Button.tsx",
+    props: { href: { required: true } },
+    exports: [{ exportedAs: "Button", filePath: "second/index.ts" }],
+  },
+];
+const components = () => contractComponentsFromFragmentsV2(fragments);
+
+describe("source-qualified contract identity", () => {
+  it("retains both same-name components and is independent of collection order", () => {
+    const projected = projectContractPreimageV2({ components: components() });
+    expect(projected.schema).toBe(CONTRACT_PREIMAGE_SCHEMA_V2);
+    expect(projected).toEqual(projectContractPreimageV2({ components: components().reverse() }));
+    expect(contractHash(projected)).not.toBe(
+      contractHash(projectContractPreimageV2({ components: components().slice(0, 1) }))
+    );
+    expect(
+      new Set(components().map((entry) => contractComponentSourceKey(entry.source))).size
+    ).toBe(2);
+  });
+  it("leaves every V1 fixture byte and duplicate guard intact", () => {
+    expect(contractHash(projectContractPreimage(catalogFixtureA))).toBe(CATALOG_FIXTURE_A_FCID);
+    expect(() => projectContractPreimage({ components: components() })).toThrow(/duplicate/);
+  });
+  it("hashes source and exported module provenance", () => {
+    const baseline = projectContractPreimageV2({ components: components() });
+    const moved = components();
+    moved[0]!.source = { kind: "repository", path: "third/Button.tsx", symbol: "Button" };
+    expect(projectContractPreimageV2({ components: moved })).not.toEqual(baseline);
+    const reexported = components();
+    reexported[0]!.exports = [{ kind: "repository", path: "third/index.ts", exportName: "Button" }];
+    expect(projectContractPreimageV2({ components: reexported })).not.toEqual(baseline);
+  });
+  it("rejects duplicate definitions and competing owners of one export", () => {
+    expect(() =>
+      projectContractPreimageV2({ components: [components()[0]!, components()[0]!] })
+    ).toThrow(/duplicate source identity/);
+    const conflicting = components();
+    conflicting[1]!.exports = conflicting[0]!.exports;
+    expect(() => projectContractPreimageV2({ components: conflicting })).toThrow(
+      /conflicting owners/
+    );
+  });
+  it("qualifies same-name canonical mappings and rejects source ambiguity", () => {
+    const mappings = components().map((entry) => ({
+      component: "Button",
+      source: entry.source,
+      canonical: "Button",
+      status: "confirmed" as const,
+    }));
+    const projected = projectContractPreimageV2({
+      components: components(),
+      canonicalMappings: mappings,
+    });
+    expect(projected).toEqual(
+      projectContractPreimageV2({ components: components(), canonicalMappings: mappings.reverse() })
+    );
+    expect(() =>
+      projectContractPreimageV2({ canonicalMappings: [mappings[0]!, mappings[0]!] })
+    ).toThrow(/duplicate confirmed source/);
+    expect(() =>
+      projectContractPreimageV2({
+        canonicalMappings: [
+          { component: "Button", canonical: "Button", status: "confirmed" } as never,
+        ],
+      })
+    ).toThrow(/source/);
+  });
+  it.each([
+    "/checkout/Button.tsx",
+    "../Button.tsx",
+    "C:\\repo\\Button.tsx",
+    "src/../../Button.tsx",
+  ])("rejects non-portable source %s", (path) => {
+    expect(() =>
+      contractComponentsFromFragmentsV2([{ meta: { name: "Button" }, filePath: path }])
+    ).toThrow(/source/);
+  });
+  it("normalizes equivalent relative paths without case-folding distinct files", () => {
+    const key = (path: string) =>
+      contractComponentSourceKey({ kind: "repository", path, symbol: "Button" });
+    expect(key("./src/ui/../Button.tsx")).toBe(key("src\\Button.tsx"));
+    expect(key("src/Button.tsx")).not.toBe(key("src/button.tsx"));
+  });
+  it("verifies V2 pins and refuses unknown or mismatched generations", () => {
+    const preimage = projectContractPreimageV2({ components: components() });
+    const pin = {
+      contractHash: contractHash(preimage),
+      preimageSchema: preimage.schema,
+      domainHashes: preimage.domains,
+    };
+    expect(verifiedContractPreimageFromPin(pin)).toEqual(preimage);
+    expect(
+      verifiedContractPreimageFromPin({ ...pin, preimageSchema: "fcid-preimage:v1" })
+    ).toBeNull();
+    expect(
+      verifiedContractPreimageFromPin({ ...pin, preimageSchema: "fcid-preimage:v99" })
+    ).toBeNull();
+  });
+});
+
+it.each([
+  "/checkout/private/Button.tsx",
+  "../Button.tsx",
+  "file:///Users/person/Button.tsx",
+  "@scope",
+  "@scope/pkg/../secret",
+  "pkg//Button",
+  "pkg?query",
+  "pkg\\Button",
+])("rejects a non-package address %s in sources and exports", (importPath) => {
+  expect(() =>
+    contractComponentSourceKey({ kind: "package", importPath, exportName: "Button" })
+  ).toThrow(/public package import/);
+  expect(() =>
+    projectContractPreimageV2({
+      components: [
+        { ...components()[0]!, exports: [{ kind: "package", importPath, exportName: "Button" }] },
+      ],
+    })
+  ).toThrow(/public package import/);
+});
+
+it("accepts package subpaths and canonicalizes the owned package address", () => {
+  const key = (importPath: string) =>
+    contractComponentSourceKey({ kind: "package", importPath, exportName: "Button" });
+  expect(key("@mui/material/Button")).toContain("@mui/material/Button");
+  expect(key("@fragments-sdk/ui/button")).toBe(key("@usefragments/ui/button"));
+});
+
+it.each([
+  ["fcid-preimage:v1", undefined, 512 * 1024],
+  ["fcid-preimage:v2", "component-source:v1", 6 * 1024 * 1024],
+  ["fcid-preimage:v1", "component-source:v1", null],
+  ["fcid-preimage:v2", undefined, null],
+  ["fcid-preimage:v2", "component-source:v2", null],
+  ["fcid-preimage:v3", "component-source:v1", null],
+  [null, null, null],
+])(
+  "selects approved envelope capacity only for consistent generations (%s / %s)",
+  (schema, marker, limit) => {
+    expect(approvedComponentGovernanceByteLimit(schema, marker)).toBe(limit);
+  }
+);

package/src/contract/source-identity.ts

@@ -0,0 +1,303 @@
+import { canonicalizeOwnedImport } from "../package-identity.js";
+import { canonicalPreimage, contractHash } from "./hash.js";
+import {
+  CONTRACT_PREIMAGE_SCHEMA,
+  CONTRACT_PREIMAGE_SCHEMA_V2,
+  ContractCatalogValidationError,
+  contractComponentsFromFragments,
+  projectContractPreimage,
+  type ContractCanonicalMappingInput,
+  type ContractCatalogInput,
+  type ContractComponentInput,
+  type ContractPreimage,
+} from "./preimage.js";
+
+export const APPROVED_COMPONENT_GOVERNANCE_LEGACY_MAX_BYTES = 512 * 1024;
+export const APPROVED_COMPONENT_GOVERNANCE_QUALIFIED_MAX_BYTES = 6 * 1024 * 1024;
+
+/** Expanded portable capacity requires the enclosing FCID and component generation to agree. */
+export function approvedComponentGovernanceByteLimit(
+  expectedPreimageSchema: unknown,
+  sourceIdentitySchema: unknown
+): number | null {
+  if (expectedPreimageSchema === CONTRACT_PREIMAGE_SCHEMA && sourceIdentitySchema === undefined) {
+    return APPROVED_COMPONENT_GOVERNANCE_LEGACY_MAX_BYTES;
+  }
+  if (
+    expectedPreimageSchema === CONTRACT_PREIMAGE_SCHEMA_V2 &&
+    sourceIdentitySchema === "component-source:v1"
+  ) {
+    return APPROVED_COMPONENT_GOVERNANCE_QUALIFIED_MAX_BYTES;
+  }
+  return null;
+}
+
+/** A portable address; authorization remains pinned to the enclosing contract. */
+export type ContractComponentSource =
+  | { kind: "repository"; path: string; symbol: string }
+  | { kind: "package"; importPath: string; exportName: string };
+
+export type ContractComponentExport =
+  | { kind: "repository"; path: string; exportName: string }
+  | { kind: "package"; importPath: string; exportName: string };
+
+export interface ContractComponentInputV2 extends ContractComponentInput {
+  source: ContractComponentSource;
+  exports?: readonly ContractComponentExport[];
+}
+
+export interface ContractCanonicalMappingInputV2 extends ContractCanonicalMappingInput {
+  source: ContractComponentSource;
+}
+
+export interface ContractCatalogInputV2 extends Omit<
+  ContractCatalogInput,
+  "components" | "canonicalMappings"
+> {
+  components?: readonly ContractComponentInputV2[];
+  canonicalMappings?: readonly ContractCanonicalMappingInputV2[];
+}
+
+export function normalizeContractSourcePath(value: string): string {
+  const path = value.trim().replace(/\\/gu, "/");
+  if (!path || path.startsWith("/") || /^[a-z]:/iu.test(path) || path.includes("\0")) {
+    throw new ContractCatalogValidationError(["source: expected a repository-relative path"]);
+  }
+  const segments: string[] = [];
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      if (!segments.length) {
+        throw new ContractCatalogValidationError(["source: path escapes the repository"]);
+      }
+      segments.pop();
+    } else segments.push(part);
+  }
+  if (!segments.length) {
+    throw new ContractCatalogValidationError(["source: expected a component file"]);
+  }
+  return segments.join("/");
+}
+
+function requiredString(value: unknown, field: string): string {
+  if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
+    throw new ContractCatalogValidationError([`${field}: expected a non-empty string`]);
+  }
+  return value.trim();
+}
+
+function normalizePublicPackageImport(value: unknown): string {
+  const specifier = requiredString(value, "source.importPath");
+  const parts = specifier.split("/");
+  const rootLength = specifier.startsWith("@") ? 2 : 1;
+  if (
+    parts.length < rootLength ||
+    parts.some((part, index) => {
+      const name = index === 0 && rootLength === 2 ? part.slice(1) : part;
+      return !name || name === "." || name === ".." || !/^[a-z0-9_~.-]+$/iu.test(name);
+    }) ||
+    parts[0]!.startsWith(".")
+  ) {
+    throw new ContractCatalogValidationError([
+      "source.importPath: expected a public package import or subpath",
+    ]);
+  }
+  return canonicalizeOwnedImport(specifier);
+}
+
+export function normalizeContractComponentSource(
+  value: ContractComponentSource
+): ContractComponentSource {
+  if (value?.kind === "repository") {
+    return {
+      kind: "repository",
+      path: normalizeContractSourcePath(requiredString(value.path, "source.path")),
+      symbol: requiredString(value.symbol, "source.symbol"),
+    };
+  }
+  if (value?.kind === "package") {
+    return {
+      kind: "package",
+      importPath: normalizePublicPackageImport(value.importPath),
+      exportName: requiredString(value.exportName, "source.exportName"),
+    };
+  }
+  throw new ContractCatalogValidationError(["source: expected repository or package identity"]);
+}
+
+export function contractComponentSourceKey(source: ContractComponentSource): string {
+  return canonicalPreimage(normalizeContractComponentSource(source));
+}
+
+interface ComponentGuidance {
+  name: string;
+  source?: ContractComponentSource;
+  exportAddresses?: readonly ContractComponentExport[];
+}
+
+/** Public addresses proven by the exact component source, never package display metadata. */
+export function contractComponentExportAddresses(
+  component: ComponentGuidance
+): Array<{ importPath: string; exportName: string }> {
+  const addresses =
+    component.source?.kind === "package"
+      ? [component.source]
+      : (component.exportAddresses ?? []).filter(
+          (address): address is Extract<ContractComponentExport, { kind: "package" }> =>
+            address.kind === "package"
+        );
+  return [
+    ...new Map(
+      addresses.map((address) => [
+        contractComponentSourceKey(address),
+        { importPath: canonicalizeOwnedImport(address.importPath), exportName: address.exportName },
+      ])
+    ).values(),
+  ];
+}
+
+/** Existing replacement syntax supports a unique named JSX component binding. */
+export function contractComponentReplacementImport(
+  component: ComponentGuidance
+): { importPath: string; exportName: string } | undefined {
+  const addresses = contractComponentExportAddresses(component);
+  const named = addresses.filter((address) => address.exportName === component.name);
+  const usable = (name: string) => /^[A-Za-z_$][\w$]*$/.test(name) && !/^[a-z]/.test(name);
+  if (named.length === 1 && usable(named[0]!.exportName)) return named[0];
+  if (addresses.length === 1 && usable(addresses[0]!.exportName)) return addresses[0];
+  return undefined;
+}
+
+function normalizedExport(value: ContractComponentExport): ContractComponentExport {
+  if (value?.kind === "repository") {
+    return {
+      kind: "repository",
+      path: normalizeContractSourcePath(requiredString(value.path, "exports.path")),
+      exportName: requiredString(value.exportName, "exports.exportName"),
+    };
+  }
+  if (value?.kind === "package") {
+    return normalizeContractComponentSource(value) as ContractComponentExport;
+  }
+  throw new ContractCatalogValidationError(["exports: expected repository or package identity"]);
+}
+
+function stableOrder<T>(values: readonly T[]): T[] {
+  return [...values].sort((a, b) => {
+    const left = canonicalPreimage(a);
+    const right = canonicalPreimage(b);
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+}
+
+/** V1 remains immutable. V2 scopes the same enforcement projection by source. */
+export function projectContractPreimageV2(catalog: ContractCatalogInputV2): ContractPreimage {
+  const componentsSeen = new Set<string>();
+  const exportOwners = new Map<string, string>();
+  const components = (catalog.components ?? []).map((component) => {
+    const source = normalizeContractComponentSource(component.source);
+    const key = contractComponentSourceKey(source);
+    if (componentsSeen.has(key)) {
+      throw new ContractCatalogValidationError([`components: duplicate source identity ${key}`]);
+    }
+    componentsSeen.add(key);
+    const exports = new Map<string, ContractComponentExport>();
+    for (const raw of component.exports ?? []) {
+      const entry = normalizedExport(raw);
+      const alias = canonicalPreimage(entry);
+      const owner = exportOwners.get(alias);
+      if (owner && owner !== key) {
+        throw new ContractCatalogValidationError([`exports: conflicting owners for ${alias}`]);
+      }
+      exportOwners.set(alias, key);
+      exports.set(alias, entry);
+    }
+    return {
+      source,
+      exports: stableOrder([...exports.values()]),
+      enforcement: projectContractPreimage({ components: [component] }).domains.components,
+    };
+  });
+  const mappingsSeen = new Set<string>();
+  const mappings = (catalog.canonicalMappings ?? []).flatMap((mapping) => {
+    // Validate proposed records too; their authority is still excluded by V1.
+    const enforcement = projectContractPreimage({ canonicalMappings: [mapping] }).domains
+      .canonicalMap;
+    const source = normalizeContractComponentSource(mapping.source);
+    if (mapping.status !== "confirmed") return [];
+    const key = contractComponentSourceKey(source);
+    if (mappingsSeen.has(key)) {
+      throw new ContractCatalogValidationError([
+        `canonicalMappings: duplicate confirmed source ${key}`,
+      ]);
+    }
+    mappingsSeen.add(key);
+    return [{ source, enforcement }];
+  });
+  const shared = projectContractPreimage({ tokens: catalog.tokens, policy: catalog.policy });
+  return {
+    schema: CONTRACT_PREIMAGE_SCHEMA_V2,
+    domains: {
+      ...shared.domains,
+      components: contractHash(stableOrder(components)),
+      canonicalMap: contractHash(stableOrder(mappings)),
+    },
+  };
+}
+
+/** Normalize one persisted fragment without using its display name as its address. */
+export function contractSourceFromFragment(
+  fragment: unknown,
+  packageName?: string
+): ContractComponentSource {
+  const row = fragment as Record<string, unknown>;
+  if (!row || typeof row !== "object") {
+    throw new ContractCatalogValidationError(["component: expected an object"]);
+  }
+  if (row.source) return normalizeContractComponentSource(row.source as ContractComponentSource);
+  const meta = row.meta as { name?: unknown } | undefined;
+  const name = requiredString(row.exportName ?? meta?.name, "component export");
+  const path = row.sourcePath ?? row.filePath;
+  if (typeof path === "string" && path.trim()) {
+    return normalizeContractComponentSource({ kind: "repository", path, symbol: name });
+  }
+  const importPath = row.importPath ?? row.packageName ?? packageName;
+  return normalizeContractComponentSource({
+    kind: "package",
+    importPath: requiredString(importPath, "component source"),
+    exportName: name,
+  });
+}
+
+export function contractComponentsFromFragmentsV2(
+  fragments: readonly unknown[],
+  packageName?: string
+): ContractComponentInputV2[] {
+  return fragments.map((fragment) => {
+    const [component] = contractComponentsFromFragments([fragment]);
+    if (!component) throw new ContractCatalogValidationError(["component: missing name"]);
+    const source = contractSourceFromFragment(fragment, packageName);
+    const row = fragment as { exports?: unknown };
+    const exports: ContractComponentExport[] = [];
+    if (Array.isArray(row.exports)) {
+      for (const raw of row.exports) {
+        const entry = raw as { exportedAs?: unknown; filePath?: unknown; importPath?: unknown };
+        const exportName = requiredString(entry.exportedAs, "exports.exportedAs");
+        if (typeof entry.importPath === "string") {
+          exports.push(
+            normalizedExport({ kind: "package", importPath: entry.importPath, exportName })
+          );
+        } else if (source.kind === "repository") {
+          exports.push(
+            normalizedExport({
+              kind: "repository",
+              path: typeof entry.filePath === "string" ? entry.filePath : source.path,
+              exportName,
+            })
+          );
+        } else exports.push({ ...source, exportName });
+      }
+    }
+    return { ...component, source, exports };
+  });
+}