@usefragments/core 1.10.2 → 1.11.0

package/src/defineFragment.ts

@@ -1,13 +1,14 @@
 import type {
   FragmentDefinition,
   FragmentDefinitionV2,
-  CompiledFragment,
+  FragmentDefinitionV3,
+  FragmentDefinitionV3Body,
   FragmentComponent,
   BlockDefinition,
-  CompiledBlock,
   AIMetadata,
   FragmentGenerated,
 } from "./types.js";
+import type { CompiledBlock, CompiledFragment } from "./compiled-types/index.js";
 import type {
   GovernedFragmentDefinition,
   ResolvedGovernedFragmentDefinition,
@@ -15,15 +16,23 @@ import type {
 import {
   fragmentDefinitionSchema,
   fragmentDefinitionV2Schema,
+  fragmentDefinitionV3BodySchema,
   governedFragmentDefinitionSchema,
   blockDefinitionSchema,
 } from "./schema.js";
 import { resolveComponentGovernance } from "./governance.js";
 
+/**
+ * True only when an explicit govern function or governance record array is
+ * present. Optional-key sniffing (`"govern" in def`) is intentionally avoided —
+ * that was the optional-key type/runtime lie.
+ */
 function isGovernedDefinition<T>(
   def: FragmentDefinition<T> | FragmentDefinitionV2<T> | GovernedFragmentDefinition<T>
 ): def is GovernedFragmentDefinition<T> {
-  return "govern" in def || "governance" in def;
+  if (!def || typeof def !== "object") return false;
+  const record = def as Record<string, unknown>;
+  return typeof record.govern === "function" || Array.isArray(record.governance);
 }
 
 /**
@@ -33,9 +42,75 @@ function isGovernedDefinition<T>(
 function isV2Definition<T>(
   def: FragmentDefinition<T> | FragmentDefinitionV2<T> | GovernedFragmentDefinition<T>
 ): def is FragmentDefinitionV2<T> {
+  if (!def || typeof def !== "object") return false;
   return !isGovernedDefinition(def) && ("guidance" in def || "examples" in def);
 }
 
+function rejectInvalidGovernanceDiscriminants(definition: unknown): void {
+  if (!definition || typeof definition !== "object") return;
+
+  const record = definition as Record<string, unknown>;
+  const hasOwn = (key: "govern" | "governance") =>
+    Object.prototype.hasOwnProperty.call(record, key);
+  const errors: { path: string[]; message: string }[] = [];
+
+  if (hasOwn("govern") && typeof record.govern !== "function") {
+    errors.push({ path: ["govern"], message: "Expected a governance authoring function" });
+  }
+  if (hasOwn("governance") && !Array.isArray(record.governance)) {
+    errors.push({ path: ["governance"], message: "Expected an array of governance records" });
+  }
+
+  if (errors.length > 0) {
+    const name =
+      record.meta && typeof record.meta === "object" && "name" in record.meta
+        ? String((record.meta as Record<string, unknown>).name)
+        : "unknown";
+    throwInvalidFragment(name, "governed", errors);
+  }
+}
+
+/**
+ * Internal marker carried across the compiler's jiti boundary.
+ *
+ * The class deliberately stays private: callers should consume Core's public
+ * schemas, while the compiler needs a non-message-based way to distinguish a
+ * Core authoring refusal from an unrelated exception thrown by component code.
+ */
+class InvalidFragmentDefinitionError extends Error {
+  readonly code = "FUI9010";
+  readonly source = "@usefragments/core/defineFragment";
+  readonly api: "v1" | "v2" | "governed" | "v3" | "unknown";
+  readonly issues: readonly string[];
+
+  constructor(
+    name: string,
+    api: "v1" | "v2" | "governed" | "v3" | "unknown",
+    errors: { path: (string | number)[]; message: string }[]
+  ) {
+    const issues = errors
+      .map((error) => `${error.path.join(".") || "(root)"}: ${error.message}`)
+      .sort();
+    super(
+      [
+        `${InvalidFragmentDefinitionError.name}: Invalid fragment definition for "${name}":`,
+        ...issues.map((issue) => `  - ${issue}`),
+      ].join("\n")
+    );
+    this.name = InvalidFragmentDefinitionError.name;
+    this.api = api;
+    this.issues = issues;
+  }
+}
+
+function throwInvalidFragment(
+  name: string,
+  api: "v1" | "v2" | "governed" | "v3" | "unknown",
+  errors: { path: (string | number)[]; message: string }[]
+) {
+  throw new InvalidFragmentDefinitionError(name, api, errors);
+}
+
 /**
  * Normalize a v2 definition to v1 shape for downstream compatibility.
  * The build pipeline, compiler, and validators all work with v1 internally.
@@ -52,13 +127,14 @@ export function normalizeToV1<T>(def: FragmentDefinitionV2<T>): FragmentDefiniti
     };
   }
 
-  // Map _provenance → _generated (narrow source type, drop extended fields)
+  // Map _provenance → _generated (drop v2-only extended fields)
   let generated: FragmentGenerated | undefined;
   if (def._provenance) {
     generated = {
-      source: def._provenance.source === "scan" ? "ai" : def._provenance.source,
+      source: def._provenance.source,
       sourceFile: def._provenance.sourceFile,
       confidence: def._provenance.confidence,
+      verified: def._provenance.verified,
       timestamp: def._provenance.timestamp,
     };
   }
@@ -76,78 +152,53 @@ export function normalizeToV1<T>(def: FragmentDefinitionV2<T>): FragmentDefiniti
   };
 }
 
-/**
- * Define a fragment for a component.
- *
- * This is the main API for creating fragment documentation.
- * It provides runtime validation and type safety.
- *
- * Accepts both v1 and v2 shapes:
- * - v1: `{ usage, variants, ai, _generated }`
- * - v2: `{ guidance, examples, composition, _provenance }`
- *
- * @example v1
- * ```tsx
- * import { defineFragment } from '@usefragments/core';
- * import { Button } from './Button';
- *
- * export default defineFragment({
- *   component: Button,
- *   meta: {
- *     name: 'Button',
- *     description: 'Primary action trigger',
- *     category: 'actions',
- *   },
- *   usage: {
- *     when: ['User needs to trigger an action'],
- *     whenNot: ['Navigation without side effects'],
- *   },
- *   props: {
- *     variant: {
- *       type: 'enum',
- *       values: ['primary', 'secondary'],
- *       default: 'primary',
- *       description: 'Visual style',
- *     },
- *   },
- *   variants: [
- *     {
- *       name: 'Default',
- *       description: 'Default button',
- *       render: () => <Button>Click me</Button>,
- *     },
- *   ],
- * });
- * ```
- *
- * @example v2
- * ```tsx
- * import { defineFragment } from '@usefragments/core';
- * import { Card } from './Card';
- *
- * export default defineFragment({
- *   component: Card,
- *   meta: { name: 'Card', description: 'Content container', category: 'layout' },
- *   guidance: {
- *     when: ['Grouping related content'],
- *     whenNot: ['Full-page layouts'],
- *   },
- *   props: { ... },
- *   examples: [{ name: 'Default', description: 'Basic card', render: () => <Card>...</Card> }],
- *   composition: { pattern: 'compound', subComponents: ['Header', 'Body', 'Footer'] },
- * });
- * ```
- */
-export function defineFragment<TProps>(
-  definition: GovernedFragmentDefinition<TProps>
-): ResolvedGovernedFragmentDefinition<TProps>;
-export function defineFragment<TProps>(
-  definition: FragmentDefinition<TProps>
-): FragmentDefinition<TProps>;
-export function defineFragment<TProps>(
-  definition: FragmentDefinitionV2<TProps>
-): FragmentDefinitionV2<TProps>;
-export function defineFragment<TProps>(
+function defineFragmentV3<TProps>(
+  component: FragmentComponent<TProps>,
+  definition: FragmentDefinitionV3Body<TProps>
+): FragmentDefinitionV3<TProps> {
+  const result = fragmentDefinitionV3BodySchema.safeParse(definition);
+  if (!result.success) {
+    throwInvalidFragment(
+      definition?.meta?.name || "unknown",
+      "v3",
+      result.error.errors.map((e) => ({ path: e.path, message: e.message }))
+    );
+  }
+
+  const governance =
+    typeof definition.govern === "function" || Array.isArray(definition.governance)
+      ? resolveComponentGovernance({
+          component,
+          meta: {
+            name: definition.meta.name,
+            description: definition.meta.purpose,
+            category: definition.meta.category,
+            status: definition.meta.status,
+            tags: definition.meta.tags,
+            since: definition.meta.since,
+            dependencies: definition.meta.dependencies,
+            figma: definition.meta.figma,
+            figmaProps: definition.meta.figmaProps,
+          },
+          guidance: {
+            when: definition.guidance.when,
+            whenNot: definition.guidance.whenNot,
+            guidelines: definition.guidance.guidelines,
+            accessibility: definition.guidance.accessibility,
+          },
+          govern: definition.govern,
+          governance: definition.governance,
+        } as GovernedFragmentDefinition<TProps>)
+      : [];
+
+  return {
+    ...definition,
+    component,
+    governance,
+  };
+}
+
+function defineFragmentOneArg<TProps>(
   definition:
     | FragmentDefinition<TProps>
     | FragmentDefinitionV2<TProps>
@@ -156,23 +207,30 @@ export function defineFragment<TProps>(
   | FragmentDefinition<TProps>
   | FragmentDefinitionV2<TProps>
   | ResolvedGovernedFragmentDefinition<TProps> {
-  // Validate at runtime in development
-  if (process.env.NODE_ENV !== "production") {
-    const governed = isGovernedDefinition(definition);
-    const v2 = isV2Definition(definition);
-    const schema = governed
-      ? governedFragmentDefinitionSchema
-      : v2
-        ? fragmentDefinitionV2Schema
-        : fragmentDefinitionSchema;
-    const result = schema.safeParse(definition);
-    if (!result.success) {
-      const name = definition.meta?.name || "unknown";
-      const errors = result.error.errors
-        .map((e) => `  - ${e.path.join(".")}: ${e.message}`)
-        .join("\n");
-      throw new Error(`Invalid fragment definition for "${name}":\n${errors}`);
-    }
+  if (!definition || typeof definition !== "object") {
+    throwInvalidFragment("unknown", "unknown", [
+      { path: [], message: "Expected a fragment definition object" },
+    ]);
+  }
+
+  // Reserved governance keys may not fall through to the permissive legacy
+  // schemas merely because their values are malformed.
+  rejectInvalidGovernanceDiscriminants(definition);
+
+  const governed = isGovernedDefinition(definition);
+  const v2 = isV2Definition(definition);
+  const schema = governed
+    ? governedFragmentDefinitionSchema
+    : v2
+      ? fragmentDefinitionV2Schema
+      : fragmentDefinitionSchema;
+  const result = schema.safeParse(definition);
+  if (!result.success) {
+    throwInvalidFragment(
+      definition?.meta?.name || "unknown",
+      governed ? "governed" : v2 ? "v2" : "v1",
+      result.error.errors.map((e) => ({ path: e.path, message: e.message }))
+    );
   }
 
   if (isGovernedDefinition(definition)) {
@@ -186,6 +244,40 @@ export function defineFragment<TProps>(
   return definition;
 }
 
+/**
+ * Define a fragment for a component.
+ *
+ * **v3 (arity discriminant):** `defineFragment(Component, definition)` — the
+ * only v3 entry. Optional-key sniffing is not used.
+ *
+ * **v1 / v2 / governed (one argument):** preserved. Governed definitions require
+ * an actual `govern` function or `governance` array (not merely an optional key).
+ */
+export function defineFragment<C extends FragmentComponent<any>>(
+  component: C,
+  definition: FragmentDefinitionV3Body<C extends FragmentComponent<infer P> ? P : unknown>
+): FragmentDefinitionV3<C extends FragmentComponent<infer P> ? P : unknown>;
+export function defineFragment<TProps>(
+  definition: GovernedFragmentDefinition<TProps>
+): ResolvedGovernedFragmentDefinition<TProps>;
+export function defineFragment<TProps>(
+  definition: FragmentDefinition<TProps>
+): FragmentDefinition<TProps>;
+export function defineFragment<TProps>(
+  definition: FragmentDefinitionV2<TProps>
+): FragmentDefinitionV2<TProps>;
+export function defineFragment(componentOrDefinition: unknown, maybeDefinition?: unknown): unknown {
+  if (arguments.length >= 2) {
+    return defineFragmentV3(
+      componentOrDefinition as FragmentComponent,
+      maybeDefinition as FragmentDefinitionV3Body
+    );
+  }
+  return defineFragmentOneArg(
+    componentOrDefinition as FragmentDefinition | FragmentDefinitionV2 | GovernedFragmentDefinition
+  );
+}
+
 /**
  * Compile a fragment definition to JSON-serializable format.
  * Used for generating fragments.json for AI consumption.
@@ -206,12 +298,20 @@ export function compileFragment(
         relations: definition.relations,
         variants: definition.examples ?? [],
         contract: definition.contract,
+        ai: definition.composition
+          ? {
+              compositionPattern: definition.composition.pattern,
+              subComponents: definition.composition.subComponents,
+              requiredChildren: definition.composition.requiredChildren,
+              commonPatterns: definition.composition.commonPatterns,
+            }
+          : undefined,
         _generated: definition._provenance
           ? {
-              source:
-                definition._provenance.source === "scan" ? "ai" : definition._provenance.source,
+              source: definition._provenance.source,
               sourceFile: definition._provenance.sourceFile,
               confidence: definition._provenance.confidence,
+              verified: definition._provenance.verified,
               timestamp: definition._provenance.timestamp,
             }
           : undefined,
@@ -249,24 +349,19 @@ export function compileFragment(
  * wire together for common use cases.
  */
 export function defineBlock(definition: BlockDefinition): BlockDefinition {
-  if (process.env.NODE_ENV !== "production") {
-    const result = blockDefinitionSchema.safeParse(definition);
-    if (!result.success) {
-      const errors = result.error.errors
-        .map((e) => `  - ${e.path.join(".")}: ${e.message}`)
-        .join("\n");
-      throw new Error(`Invalid block definition for "${definition.name || "unknown"}":\n${errors}`);
-    }
+  const result = blockDefinitionSchema.safeParse(definition);
+  if (!result.success) {
+    const errors = result.error.errors
+      .map((e) => `${e.path.join(".") || "(root)"}: ${e.message}`)
+      .sort()
+      .map((issue) => `  - ${issue}`)
+      .join("\n");
+    throw new Error(`Invalid block definition for "${definition.name || "unknown"}":\n${errors}`);
   }
 
   return definition;
 }
 
-/**
- * @deprecated Use defineBlock instead
- */
-export const defineRecipe = defineBlock;
-
 /**
  * Compile a block definition to JSON-serializable format.
  */
@@ -282,11 +377,6 @@ export function compileBlock(definition: BlockDefinition, filePath: string): Com
   };
 }
 
-/**
- * @deprecated Use compileBlock instead
- */
-export const compileRecipe = compileBlock;
-
 /**
  * Type helper for extracting props type from a component
  */

package/src/domain-ids.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import {
+  analysisPlanIdFromDigest,
+  evaluationReceiptIdFromDigest,
+  mintEvaluationReceiptId,
+  featurePlanIdFromEntropy,
+  featureRevisionIdFromDigest,
+  parseAnalysisPlanId,
+  parseEvaluationReceiptId,
+  parseFeaturePlanId,
+  parseFeatureRevisionId,
+} from "./domain-ids.js";
+
+const DIGEST = "0123456789abcdef".repeat(4);
+
+describe("V1 domain IDs", () => {
+  it("retains the full digest in content-derived 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();
+  });
+});

package/src/domain-ids.ts

@@ -0,0 +1,106 @@
+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");
+export const digestHexSchema = digestHexStringSchema;
+
+export const analysisPlanIdStringSchema = z
+  .string()
+  .regex(/^apl_[0-9a-f]{64}$/u, "Invalid analysis plan ID");
+export const analysisPlanIdSchema = analysisPlanIdStringSchema.transform(
+  (value) => value as AnalysisPlanId
+);
+
+export const evaluationReceiptIdSchema = z
+  .string()
+  .regex(/^evr_[0-9a-f]{64}$/u, "Invalid evaluation receipt ID")
+  .transform((value) => value as EvaluationReceiptId);
+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);
+}
+
+export function analysisPlanIdFromDigest(digest: string): AnalysisPlanId {
+  return analysisPlanIdSchema.parse(`apl_${parseDigestHex(digest)}`);
+}
+
+export function evaluationReceiptIdFromDigest(digest: string): EvaluationReceiptId {
+  return evaluationReceiptIdSchema.parse(`evr_${parseDigestHex(digest)}`);
+}
+
+/**
+ * Mint a Cloud evaluation receipt id from a 64-hex digest (kernel
+ * `resultDigest` on the ingest envelope; receipt-semantic digest on the
+ * adoption envelope). Same `evr_` + 64 hex contract as
+ * `evaluationReceiptIdFromDigest`.
+ */
+export function mintEvaluationReceiptId(resultDigest: string): EvaluationReceiptId {
+  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);
+}
+
+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);
+}