@usefragments/core 1.0.0

package/src/contract/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Frontend Contract — the versioned, content-addressed artifact that is both
+ * served to the agent at generation time and enforced in CI. This barrel
+ * exposes the cross-runtime hashing keystone (the FCID), the unified preimage
+ * projection that defines what the contract IS, the shared pin formatter, and
+ * the committed reference catalog (`catalog-fixture-a`).
+ */
+export { canonicalPreimage, contractHash, sha256Hex } from "./hash.js";
+export {
+  CONTRACT_DOMAINS,
+  CONTRACT_PREIMAGE_SCHEMA,
+  contractComponentsFromFragments,
+  contractPolicyFromGovernanceConfig,
+  diffContractDomains,
+  projectContractPreimage,
+} from "./preimage.js";
+export type {
+  CanonicalMappingStatus,
+  ContractCanonicalMappingInput,
+  ContractCatalogInput,
+  ContractComponentInput,
+  ContractDomain,
+  ContractPolicyInput,
+  ContractPreimage,
+  ContractPropMappingInput,
+  ContractTokenInput,
+  ContractWaiverInput,
+} from "./preimage.js";
+export {
+  AGENT_CONTEXT_RELATIVE_PATH,
+  formatStampHeader,
+  formatStampPin,
+  formatStampVersionHash,
+  parseContractStamp,
+  serializeContractStamp,
+} from "./stamp.js";
+export type { ContractStampPin, ContractStampRecord } from "./stamp.js";
+export {
+  catalogFixtureA,
+  catalogFixtureAContractPayload,
+  catalogFixtureATokensDtcg,
+  CATALOG_FIXTURE_A_FCID,
+} from "./fixture.js";

package/src/contract/preimage.test.ts

@@ -0,0 +1,254 @@
+/**
+ * Contract-identity ACCEPTANCE §1–§4 (apps/cloud/docs/contract-identity).
+ * `catalog-fixture-a` + golden fcid live in `fixture.ts`; the Cloud-side parity
+ * half of §1 imports the same constants.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  CATALOG_FIXTURE_A_FCID,
+  catalogFixtureA,
+  catalogFixtureAContractPayload,
+} from "./fixture.js";
+import { contractHash } from "./hash.js";
+import {
+  type ContractCatalogInput,
+  type ContractComponentInput,
+  type ContractTokenInput,
+  contractComponentsFromFragments,
+  diffContractDomains,
+  projectContractPreimage,
+} from "./preimage.js";
+import { formatStampPin } from "./stamp.js";
+
+function fcidOf(catalog: ContractCatalogInput): string {
+  return contractHash(projectContractPreimage(catalog));
+}
+
+describe("§1 byte parity — one fixture, one hash, every runtime", () => {
+  it("hashes catalog-fixture-a to the committed golden fcid", () => {
+    expect(fcidOf(catalogFixtureA)).toBe(CATALOG_FIXTURE_A_FCID);
+  });
+
+  it("is independent of adapter iteration order", () => {
+    const reordered: ContractCatalogInput = {
+      ...catalogFixtureA,
+      components: [...(catalogFixtureA.components ?? [])].reverse().map((component) => ({
+        ...component,
+        props: component.props ? [...component.props].reverse() : undefined,
+      })),
+      tokens: [...(catalogFixtureA.tokens ?? [])].reverse(),
+      canonicalMappings: [...(catalogFixtureA.canonicalMappings ?? [])].reverse(),
+    };
+    expect(fcidOf(reordered)).toBe(CATALOG_FIXTURE_A_FCID);
+  });
+
+  it("hashes the empty catalog deterministically too", () => {
+    expect(fcidOf({})).toMatch(/^[0-9a-f]{64}$/);
+    expect(fcidOf({})).toBe(fcidOf({ components: [], tokens: [], policy: null }));
+  });
+
+  it("the payload companion assembles to the fixture's components domain", () => {
+    // Guards the Cloud parity materials: editing `catalogFixtureA` without its
+    // payload-shaped companion (or vice versa) fails here, in core, before the
+    // Convex test ever runs.
+    expect(
+      fcidOf({
+        ...catalogFixtureA,
+        components: contractComponentsFromFragments(catalogFixtureAContractPayload.fragments),
+      })
+    ).toBe(CATALOG_FIXTURE_A_FCID);
+  });
+});
+
+describe("§2 enforced-only — prose doesn't move the hash, enforcement does", () => {
+  it("(a) display-data edits leave the identity unchanged", () => {
+    // Adapters may pass wider objects (enrichment descriptions, docs URLs…);
+    // the projection's pick-list is the enforced-only boundary.
+    const withProseEdits: ContractCatalogInput = {
+      ...catalogFixtureA,
+      components: (catalogFixtureA.components ?? []).map(
+        (component) =>
+          ({
+            ...component,
+            description: "A lovingly rewritten description",
+            docsUrl: "https://usefragments.com/docs/button",
+          }) as ContractComponentInput
+      ),
+      tokens: (catalogFixtureA.tokens ?? []).map(
+        (token) => ({ ...token, description: "now with prose" }) as ContractTokenInput
+      ),
+    };
+    expect(fcidOf(withProseEdits)).toBe(CATALOG_FIXTURE_A_FCID);
+  });
+
+  it("(b) confirming a mapping changes the identity — and only the canonicalMap domain", () => {
+    const withConfirmedMapping: ContractCatalogInput = {
+      ...catalogFixtureA,
+      canonicalMappings: (catalogFixtureA.canonicalMappings ?? []).map((mapping) =>
+        mapping.status === "proposed" ? { ...mapping, status: "confirmed" as const } : mapping
+      ),
+    };
+    expect(fcidOf(withConfirmedMapping)).not.toBe(CATALOG_FIXTURE_A_FCID);
+    expect(
+      diffContractDomains(
+        projectContractPreimage(catalogFixtureA),
+        projectContractPreimage(withConfirmedMapping)
+      )
+    ).toEqual(["canonicalMap"]);
+  });
+});
+
+describe("§3 proposed mappings are not identity", () => {
+  it("adding a new proposed mapping leaves the fcid unchanged", () => {
+    const withNewProposedMapping: ContractCatalogInput = {
+      ...catalogFixtureA,
+      canonicalMappings: [
+        ...(catalogFixtureA.canonicalMappings ?? []),
+        { component: "AppButton", canonical: "Button", status: "proposed" as const },
+      ],
+    };
+    expect(fcidOf(withNewProposedMapping)).toBe(CATALOG_FIXTURE_A_FCID);
+  });
+});
+
+describe("§4 domain diff names what moved", () => {
+  it("confirming a mapping + adding a composition rule changes canonicalMap and policy", () => {
+    const preimageBase = projectContractPreimage(catalogFixtureA);
+    const vNext: ContractCatalogInput = {
+      ...catalogFixtureA,
+      canonicalMappings: (catalogFixtureA.canonicalMappings ?? []).map((mapping) =>
+        mapping.status === "proposed" ? { ...mapping, status: "confirmed" as const } : mapping
+      ),
+      policy: {
+        ...catalogFixtureA.policy,
+        compositionPatterns: [
+          ...(catalogFixtureA.policy?.compositionPatterns ?? []),
+          { id: "dialog-structure", region: "Dialog", require: ["Dialog.Title"] },
+        ],
+      },
+    };
+    const preimageNext = projectContractPreimage(vNext);
+    expect(diffContractDomains(preimageBase, preimageNext).sort()).toEqual([
+      "canonicalMap",
+      "policy",
+    ]);
+  });
+
+  it("identical preimages diff to nothing", () => {
+    const preimage = projectContractPreimage(catalogFixtureA);
+    expect(diffContractDomains(preimage, projectContractPreimage(catalogFixtureA))).toEqual([]);
+  });
+});
+
+describe("fcid-preimage:v1 package identity compatibility", () => {
+  it("keeps old/new owned canonical-map imports byte-identical", () => {
+    const historical: ContractCatalogInput = {
+      canonicalMappings: [
+        {
+          component: "button",
+          canonical: "Button",
+          status: "confirmed",
+          importPath: "@fragments-sdk/ui",
+        },
+      ],
+    };
+    const current: ContractCatalogInput = {
+      canonicalMappings: [
+        {
+          component: "button",
+          canonical: "Button",
+          status: "confirmed",
+          importPath: "@usefragments/ui",
+        },
+      ],
+    };
+    expect(projectContractPreimage(current)).toEqual(projectContractPreimage(historical));
+    expect(fcidOf(current)).toBe(fcidOf(historical));
+  });
+
+  it("projects only typed policy identity fields and leaves provenance/repository bytes alone", () => {
+    const historical: ContractCatalogInput = {
+      policy: {
+        rules: {
+          canonicalSources: [{ kind: "npm", specifier: "@fragments-sdk/ui" }],
+          importRule: {
+            kind: "jsx.importPath.prefer",
+            from: "@fragments-sdk/ui/legacy",
+            to: "@fragments-sdk/ui",
+          },
+          match: { componentId: "@fragments-sdk/ui#Button" },
+          implementationProvenance: "@repo/cloud-ui",
+          repository: "fragments-sdk/fragments",
+          generated_by: "@fragments-sdk/ui",
+        },
+      },
+    };
+    const current: ContractCatalogInput = {
+      policy: {
+        rules: {
+          canonicalSources: [{ kind: "npm", specifier: "@usefragments/ui" }],
+          importRule: {
+            kind: "jsx.importPath.prefer",
+            from: "@usefragments/ui/legacy",
+            to: "@usefragments/ui",
+          },
+          match: { componentId: "@usefragments/ui#Button" },
+          implementationProvenance: "@repo/cloud-ui",
+          repository: "fragments-sdk/fragments",
+          // A generic marker is not an npm-identity field and must not be
+          // normalized just because its value resembles a package.
+          generated_by: "@fragments-sdk/ui",
+        },
+      },
+    };
+    expect(projectContractPreimage(current)).toEqual(projectContractPreimage(historical));
+
+    const changedMarker: ContractCatalogInput = {
+      policy: {
+        rules: {
+          ...(current.policy?.rules ?? {}),
+          generated_by: "@usefragments/ui",
+        },
+      },
+    };
+    expect(projectContractPreimage(changedMarker).domains.policy).not.toBe(
+      projectContractPreimage(current).domains.policy
+    );
+  });
+
+  it("does not normalize third-party package identities", () => {
+    const acme = projectContractPreimage({
+      canonicalMappings: [
+        {
+          component: "button",
+          canonical: "Button",
+          status: "confirmed",
+          importPath: "@acme/ui",
+        },
+      ],
+    });
+    const other = projectContractPreimage({
+      canonicalMappings: [
+        {
+          component: "button",
+          canonical: "Button",
+          status: "confirmed",
+          importPath: "@other/ui",
+        },
+      ],
+    });
+    expect(acme.domains.canonicalMap).not.toBe(other.domains.canonicalMap);
+  });
+});
+
+describe("formatStampPin", () => {
+  it("renders the display convention: version + abbreviated fcid", () => {
+    expect(
+      formatStampPin({
+        contractVersion: 12,
+        fcid: "a3f9e21b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b785",
+      })
+    ).toBe("contract v12 · a3f9e21");
+  });
+});

package/src/contract/preimage.ts

@@ -0,0 +1,365 @@
+/**
+ * Frontend Contract preimage — the projection that defines what the contract IS.
+ *
+ * The FCID used to be a hash of the raw `code-contracts` artifact payload. That
+ * conflated identity with display: a copy-edit to a component description moved
+ * the hash, and tokens / canonical mappings / policy — the things gates actually
+ * enforce — were not part of identity at all. This module widens the preimage to
+ * the full enforcement surface as ONE shared projection, imported by both Cloud
+ * (mint) and the CLI (reportedHash). Neither side may reimplement it: parity is
+ * a property of the shared import, not a test you can fail.
+ *
+ * Enforced-only is implemented structurally: {@link projectContractPreimage}
+ * copies an explicit pick-list of fields per domain. Anything an adapter passes
+ * beyond that list (descriptions, docs URLs, timestamps, heuristic signals)
+ * never reaches the hash. Proposed canonical mappings are excluded for the same
+ * reason — they cannot block, so they are not identity; confirmation is the
+ * moment a mapping enters the contract.
+ *
+ * The preimage itself is the record of four domain sub-hashes, so
+ * `contractHash(preimage)` is the fcid and a domain diff is a four-string
+ * compare — no deep structural diffing. Determinism (key sorting, undefined
+ * dropping, number normalization) is inherited from `canonicalPreimage`; this
+ * module adds element-level sorting for the arrays it owns and nothing else.
+ *
+ * Runtime-portable by construction: no Node APIs, no Convex imports, no React.
+ */
+import type { GovernanceConfig } from "../governance.js";
+import { projectV1OwnedComponentId, projectV1OwnedImportIdentity } from "../package-identity.js";
+import { canonicalPreimage, contractHash } from "./hash.js";
+
+// ---------------------------------------------------------------------------
+// Domains
+// ---------------------------------------------------------------------------
+
+/**
+ * The fixed domain enum. Adding a domain is a spine change (update
+ * `01-architecture.md` first); never rename — deprecate and alias.
+ */
+export const CONTRACT_DOMAINS = ["components", "tokens", "canonicalMap", "policy"] as const;
+
+export type ContractDomain = (typeof CONTRACT_DOMAINS)[number];
+
+// ---------------------------------------------------------------------------
+// Catalog input — the neutral shape adapters assemble
+// ---------------------------------------------------------------------------
+
+/**
+ * One component's enforcement identity. Props are the *name* membership surface
+ * (what unknown-prop checks today); prop types/defaults are not enforced by the
+ * rules engine, so they are not identity — enforced-only cuts both ways.
+ */
+export interface ContractComponentInput {
+  name: string;
+  /** Parent component name when this is a subcomponent (compound identity). */
+  parentName?: string;
+  /** Prop names the component accepts. */
+  props?: readonly string[];
+  /**
+   * The per-component enforcement contract as authored (bans, a11y rules,
+   * required compound children). Passed through whole — it is enforcement data
+   * by definition.
+   */
+  contract?: unknown;
+  /** Required compound-children names, when the structure is declared. */
+  compoundChildren?: readonly string[];
+}
+
+export interface ContractTokenInput {
+  name: string;
+  value: string | number;
+  type?: string;
+}
+
+export type CanonicalMappingStatus = "confirmed" | "proposed" | "unknown";
+
+export interface ContractPropMappingInput {
+  rawProp: string;
+  canonicalProp: string;
+  valueMap?: Readonly<Record<string, string>>;
+}
+
+export interface ContractCanonicalMappingInput {
+  /** The raw/source component the mapping covers. */
+  component: string;
+  /** The canonical component it maps to. */
+  canonical: string;
+  status: CanonicalMappingStatus;
+  /** Local/offline canonical import target, when the mapping is config-authored. */
+  importPath?: string;
+  /** Explicit raw element or semantic resolutions covered by a local declaration. */
+  resolves?: readonly {
+    tag: string;
+    role?: string;
+    inputType?: string;
+  }[];
+  propMapping?: readonly ContractPropMappingInput[];
+}
+
+/**
+ * An authored waiver record. Hashed as data — including `expiresOn` as a plain
+ * date string. Expiry *evaluation* happens at enforcement time and must never
+ * change the fcid (no time-dependent hashing).
+ */
+export interface ContractWaiverInput {
+  id: string;
+  /** The diagnostic code or rule the waiver suppresses. */
+  target: string;
+  reason: string;
+  /** YYYY-MM-DD, treated as opaque data. */
+  expiresOn?: string;
+}
+
+/**
+ * Active policy: everything that changes what a gate would allow or deny.
+ * Waivers live here (spine open question 1, resolved): a waiver changes what
+ * blocks, so it is enforcement-relevant.
+ */
+export interface ContractPolicyInput {
+  rules?: Readonly<Record<string, unknown>>;
+  codes?: Readonly<Record<string, unknown>>;
+  compositionPatterns?: readonly unknown[];
+  waivers?: readonly ContractWaiverInput[];
+}
+
+/**
+ * The neutral catalog shape both adapters (Cloud mint, CLI scan) assemble.
+ * Adapters gather data; the projection owns all normalization — element order,
+ * optional fields, and display-data stripping never reach the hash.
+ */
+export interface ContractCatalogInput {
+  components?: readonly ContractComponentInput[];
+  tokens?: readonly ContractTokenInput[];
+  canonicalMappings?: readonly ContractCanonicalMappingInput[];
+  policy?: ContractPolicyInput | null;
+}
+
+// ---------------------------------------------------------------------------
+// Preimage
+// ---------------------------------------------------------------------------
+
+export const CONTRACT_PREIMAGE_SCHEMA = "fcid-preimage:v1" as const;
+
+/**
+ * The hashed identity record: four domain sub-hashes plus the projection schema
+ * version (so an intentional projection change mints a new fcid). The fcid is
+ * `contractHash(preimage)` — hash of the domain hashes, per the spine pipeline.
+ */
+export interface ContractPreimage {
+  schema: typeof CONTRACT_PREIMAGE_SCHEMA;
+  domains: Record<ContractDomain, string>;
+}
+
+/**
+ * Sort projected elements by their canonical serialization: total, deterministic,
+ * and independent of adapter iteration order, without per-type comparators.
+ */
+function sortCanonical<T>(items: readonly T[]): T[] {
+  return items
+    .map((item) => ({ item, key: canonicalPreimage(item) }))
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+    .map(({ item }) => item);
+}
+
+function projectComponents(components: readonly ContractComponentInput[] | undefined): unknown {
+  return sortCanonical(
+    (components ?? []).map((component) => ({
+      name: component.name,
+      parentName: component.parentName,
+      props: component.props ? [...component.props].sort() : undefined,
+      contract: component.contract,
+      compoundChildren: component.compoundChildren
+        ? [...component.compoundChildren].sort()
+        : undefined,
+    }))
+  );
+}
+
+function projectTokens(tokens: readonly ContractTokenInput[] | undefined): unknown {
+  return sortCanonical(
+    (tokens ?? []).map((token) => ({
+      name: token.name,
+      value: token.value,
+      type: token.type,
+    }))
+  );
+}
+
+function projectCanonicalMap(
+  mappings: readonly ContractCanonicalMappingInput[] | undefined
+): unknown {
+  return sortCanonical(
+    (mappings ?? [])
+      .filter((mapping) => mapping.status === "confirmed")
+      .map((mapping) => ({
+        component: mapping.component,
+        canonical: mapping.canonical,
+        importPath: mapping.importPath
+          ? projectV1OwnedImportIdentity(mapping.importPath)
+          : undefined,
+        resolves: mapping.resolves ? sortCanonical(mapping.resolves) : undefined,
+        propMapping: mapping.propMapping
+          ? sortCanonical(
+              mapping.propMapping.map((entry) => ({
+                rawProp: entry.rawProp,
+                canonicalProp: entry.canonicalProp,
+                valueMap: entry.valueMap,
+              }))
+            )
+          : undefined,
+      }))
+  );
+}
+
+/**
+ * Project only structured npm-identity fields inside policy material. This is
+ * deliberately key- and record-aware: arbitrary strings, repository names,
+ * provenance, product markers, and third-party package values retain their
+ * original bytes.
+ */
+function projectV1PolicyMaterial(value: unknown, key?: string): unknown {
+  if (typeof value === "string") {
+    if (key === "specifier" || key === "importPath") {
+      return projectV1OwnedImportIdentity(value);
+    }
+    if (key === "componentId") {
+      return projectV1OwnedComponentId(value);
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => projectV1PolicyMaterial(entry));
+  }
+  if (!value || typeof value !== "object") return value;
+
+  const record = value as Readonly<Record<string, unknown>>;
+  const isImportPathRule = record.kind === "jsx.importPath.prefer";
+  return Object.fromEntries(
+    Object.entries(record).map(([field, fieldValue]) => {
+      if (
+        isImportPathRule &&
+        (field === "from" || field === "to") &&
+        typeof fieldValue === "string"
+      ) {
+        return [field, projectV1OwnedImportIdentity(fieldValue)];
+      }
+      return [field, projectV1PolicyMaterial(fieldValue, field)];
+    })
+  );
+}
+
+function projectPolicy(policy: ContractPolicyInput | null | undefined): unknown {
+  if (!policy) return null;
+  return {
+    rules: projectV1PolicyMaterial(policy.rules),
+    codes: policy.codes,
+    compositionPatterns: policy.compositionPatterns
+      ? sortCanonical(policy.compositionPatterns)
+      : undefined,
+    waivers: policy.waivers
+      ? sortCanonical(
+          policy.waivers.map((waiver) => ({
+            id: waiver.id,
+            target: waiver.target,
+            reason: waiver.reason,
+            expiresOn: waiver.expiresOn,
+          }))
+        )
+      : undefined,
+  };
+}
+
+/**
+ * Project a catalog onto the contract preimage: four enforced-only domain
+ * bodies, each hashed independently. `contractHash(projectContractPreimage(x))`
+ * is the fcid.
+ */
+export function projectContractPreimage(catalog: ContractCatalogInput): ContractPreimage {
+  return {
+    schema: CONTRACT_PREIMAGE_SCHEMA,
+    domains: {
+      components: contractHash(projectComponents(catalog.components)),
+      tokens: contractHash(projectTokens(catalog.tokens)),
+      canonicalMap: contractHash(projectCanonicalMap(catalog.canonicalMappings)),
+      policy: contractHash(projectPolicy(catalog.policy)),
+    },
+  };
+}
+
+/**
+ * Name the domains whose identity differs between two preimages — a four-string
+ * compare, no structural diffing. Returned in fixed {@link CONTRACT_DOMAINS}
+ * order. Staleness checks compare these, never whole fcids.
+ */
+export function diffContractDomains(a: ContractPreimage, b: ContractPreimage): ContractDomain[] {
+  return CONTRACT_DOMAINS.filter((domain) => a.domains[domain] !== b.domains[domain]);
+}
+
+/**
+ * Map defineFragment-shaped records — the `code-contracts` payload's
+ * `fragments` array (Cloud mint) or the CLI's loaded fragment definitions —
+ * onto their enforcement identity. The one shared mapping is what keeps the
+ * two adapters from drifting into a second "catalog → preimage"
+ * implementation: both sides gather fragments however they like, then this
+ * picks the identity fields. Records without a string `meta.name` are skipped
+ * (no identity to hash).
+ */
+/**
+ * The enforced-only slice of a resolved CLI governance config — the fields
+ * that change what a scan allows or denies. CI gate options, agent repair
+ * order, and runner config change how/when gates run, not what they enforce,
+ * so they are not identity. This pick-list lives here, beside the projection,
+ * so adapters cannot drift into private enforced-only boundaries: a new
+ * enforcement field on {@link GovernanceConfig} is added to the contract in
+ * exactly one place.
+ */
+export function contractPolicyFromGovernanceConfig(
+  config: GovernanceConfig | null | undefined
+): ContractPolicyInput | null {
+  if (!config) return null;
+  return {
+    rules: {
+      severity: config.severity,
+      rules: config.rules,
+      scales: config.scales,
+      styles: config.styles,
+      jsx: config.jsx,
+      tailwind: config.tailwind,
+      components: config.components,
+      overrides: config.overrides,
+    },
+    codes: config.codes as Readonly<Record<string, unknown>> | undefined,
+    compositionPatterns: config.compositionPatterns as readonly unknown[] | undefined,
+  };
+}
+
+export function contractComponentsFromFragments(
+  fragments: readonly unknown[]
+): ContractComponentInput[] {
+  const components: ContractComponentInput[] = [];
+  for (const candidate of fragments) {
+    const fragment = candidate as {
+      meta?: { name?: unknown; parentComponentName?: unknown };
+      props?: Record<string, unknown>;
+      contract?: unknown;
+      structure?: { compoundChildren?: unknown };
+    } | null;
+    const name = fragment?.meta?.name;
+    if (typeof name !== "string" || !name) continue;
+    const parentName = fragment?.meta?.parentComponentName;
+    const rawChildren = fragment?.structure?.compoundChildren;
+    const compoundChildren = Array.isArray(rawChildren)
+      ? rawChildren
+          .map((child) => (child as { name?: unknown } | null)?.name)
+          .filter((childName): childName is string => typeof childName === "string")
+      : undefined;
+    components.push({
+      name,
+      parentName: typeof parentName === "string" ? parentName : undefined,
+      props: Object.keys(fragment?.props ?? {}),
+      contract: fragment?.contract,
+      compoundChildren,
+    });
+  }
+  return components;
+}