@usefragments/core 1.10.2 → 1.11.0

package/src/facts/facts.test.ts

@@ -153,6 +153,21 @@ describe("fact IR — content-addressed IDs", () => {
     expect(a).toBe(b);
   });
 
+  it("rejects circular and runtime-only fact identity values deterministically", () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+
+    expect(() => factId("component", circular)).toThrow(
+      "Circular fact identity value at (root).i.self"
+    );
+    expect(() => factId("component", { componentId: () => "Button" })).toThrow(
+      "Unsupported fact identity value at (root).i.componentId: function"
+    );
+    expect(() => factId("component", { confidence: Number.NaN })).toThrow(
+      "Unsupported fact identity value at (root).i.confidence: non-finite number"
+    );
+  });
+
   it("keys definition and identity facts by the portable componentKey", () => {
     const first = makeComponentDefinitionFact({
       file: "src/a/Button.tsx",

package/src/facts/ids.ts

@@ -22,15 +22,58 @@ import type { ComponentId, FactId } from "./types.js";
 // ---------------------------------------------------------------------------
 
 export function canonicalJson(value: unknown): string {
+  return canonicalJsonValue(value, new Set<object>(), "(root)");
+}
+
+function canonicalJsonValue(value: unknown, ancestors: Set<object>, path: string): string {
   if (value === undefined) return "null";
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`Unsupported fact identity value at ${path}: non-finite number`);
+    }
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined) {
+      throw new TypeError(`Unsupported fact identity value at ${path}: number`);
+    }
+    return serialized;
+  }
+  if (typeof value !== "object") {
+    throw new TypeError(`Unsupported fact identity value at ${path}: ${typeof value}`);
+  }
   if (Array.isArray(value)) {
-    return `[${value.map(canonicalJson).join(",")}]`;
+    if (ancestors.has(value)) throw new TypeError(`Circular fact identity value at ${path}`);
+    ancestors.add(value);
+    try {
+      return `[${value
+        .map((entry, index) => canonicalJsonValue(entry, ancestors, `${path}[${index}]`))
+        .join(",")}]`;
+    } finally {
+      ancestors.delete(value);
+    }
   }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    const objectType = prototype?.constructor?.name ?? "unknown";
+    throw new TypeError(`Unsupported fact identity object at ${path}: ${objectType}`);
+  }
+  if (ancestors.has(value)) throw new TypeError(`Circular fact identity value at ${path}`);
+  ancestors.add(value);
   const entries = Object.entries(value as Record<string, unknown>)
     .filter(([, v]) => v !== undefined)
     .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+  try {
+    return `{${entries
+      .map(
+        ([key, entry]) =>
+          `${JSON.stringify(key)}:${canonicalJsonValue(entry, ancestors, `${path}.${key}`)}`
+      )
+      .join(",")}}`;
+  } finally {
+    ancestors.delete(value);
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/facts/index.ts

@@ -72,8 +72,21 @@ export type {
   TailwindTokenResolvedFact,
   TailwindValue,
   ThemeDeclarationFact,
+  CanonicalFactConflictV1,
+  CanonicalFactConflictValueV1,
+  CanonicalFactIntegrityV1,
 } from "./types.js";
 
+export {
+  CANONICAL_FACT_MAX_CONFLICTS_V1,
+  CANONICAL_FACT_MAX_PROVENANCE_PER_VALUE_V1,
+  CANONICAL_FACT_MAX_VALUES_PER_CONFLICT_V1,
+  canonicalFactConflictV1Schema,
+  canonicalFactConflictValueV1Schema,
+  canonicalFactIntegrityV1Schema,
+  normalizeCanonicalFactIntegrityV1,
+} from "./integrity.js";
+
 export { componentId, asComponentId, factId, hash64Hex, canonicalJson } from "./ids.js";
 
 export {
@@ -122,7 +135,7 @@ export {
 } from "./builders.js";
 
 export { FactIndex, matchesGlob } from "./fact-index.js";
-export type { FactConflict, FactEvidence } from "./fact-index.js";
+export type { FactConflict, FactDuplicate, FactEvidence } from "./fact-index.js";
 
 export { compileGlobalGovernanceFacts, compileComponentFacts } from "./compile.js";
 export { projectSupersededImportPathPreferences } from "./compile.js";

package/src/facts/integrity.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import { compareCanonicalStrings } from "../contract/hash.js";
+import { digestHexStringSchema } from "../domain-ids.js";
+import type { CanonicalFactIntegrityV1 } from "./types.js";
+
+export const CANONICAL_FACT_MAX_CONFLICTS_V1 = 1_000;
+export const CANONICAL_FACT_MAX_VALUES_PER_CONFLICT_V1 = 64;
+export const CANONICAL_FACT_MAX_PROVENANCE_PER_VALUE_V1 = 1_000;
+
+const boundedString = z.string().min(1).max(4_096);
+const unique = (values: readonly string[]): boolean => new Set(values).size === values.length;
+const provenance = z
+  .array(boundedString)
+  .min(1)
+  .max(CANONICAL_FACT_MAX_PROVENANCE_PER_VALUE_V1)
+  .refine(unique, "provenance values must be unique");
+
+export const canonicalFactConflictValueV1Schema = z
+  .object({
+    valueDigest: digestHexStringSchema,
+    factIds: provenance,
+    totalFactIdCount: z.number().int().positive().optional(),
+    analyzerIds: provenance,
+    totalAnalyzerIdCount: z.number().int().positive().optional(),
+    evidenceRefs: provenance,
+    totalEvidenceRefCount: z.number().int().positive().optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    for (const [path, total, retained] of [
+      ["totalFactIdCount", value.totalFactIdCount, value.factIds.length],
+      ["totalAnalyzerIdCount", value.totalAnalyzerIdCount, value.analyzerIds.length],
+      ["totalEvidenceRefCount", value.totalEvidenceRefCount, value.evidenceRefs.length],
+    ] as const) {
+      if (total !== undefined && total < retained) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [path],
+          message: `${path} cannot be smaller than retained provenance`,
+        });
+      }
+    }
+  });
+
+export const canonicalFactConflictV1Schema = z
+  .object({
+    canonicalKey: boundedString,
+    factKind: boundedString,
+    state: z.literal("conflict"),
+    values: z
+      .array(canonicalFactConflictValueV1Schema)
+      .min(2)
+      .max(CANONICAL_FACT_MAX_VALUES_PER_CONFLICT_V1)
+      .refine(
+        (values) => new Set(values.map((value) => value.valueDigest)).size === values.length,
+        "conflict values must have distinct material digests"
+      ),
+    totalValueCount: z.number().int().min(2).optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.totalValueCount !== undefined && value.totalValueCount < value.values.length) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["totalValueCount"],
+        message: "totalValueCount cannot be smaller than retained values",
+      });
+    }
+  });
+
+export const canonicalFactIntegrityV1Schema = z.union([
+  z
+    .object({
+      state: z.literal("healthy"),
+      coalescedDuplicateCount: z.number().int().nonnegative(),
+    })
+    .strict(),
+  z
+    .object({
+      state: z.literal("conflict"),
+      coalescedDuplicateCount: z.number().int().nonnegative(),
+      conflicts: z
+        .array(canonicalFactConflictV1Schema)
+        .min(1)
+        .max(CANONICAL_FACT_MAX_CONFLICTS_V1)
+        .refine(
+          (conflicts) =>
+            new Set(conflicts.map((conflict) => conflict.canonicalKey)).size === conflicts.length,
+          "canonical conflict keys must be unique"
+        ),
+      totalConflictCount: z.number().int().positive().optional(),
+    })
+    .strict()
+    .superRefine((value, context) => {
+      if (
+        value.totalConflictCount !== undefined &&
+        value.totalConflictCount < value.conflicts.length
+      ) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["totalConflictCount"],
+          message: "totalConflictCount cannot be smaller than retained conflicts",
+        });
+      }
+    }),
+]);
+
+const sorted = (values: readonly string[]): string[] => [...values].sort();
+
+export function normalizeCanonicalFactIntegrityV1(value: unknown): CanonicalFactIntegrityV1 {
+  const parsed = canonicalFactIntegrityV1Schema.parse(value);
+  if (parsed.state === "healthy") return parsed;
+  return {
+    ...parsed,
+    totalConflictCount: parsed.totalConflictCount ?? parsed.conflicts.length,
+    conflicts: parsed.conflicts
+      .map((conflict) => ({
+        ...conflict,
+        totalValueCount: conflict.totalValueCount ?? conflict.values.length,
+        values: conflict.values
+          .map((entry) => ({
+            ...entry,
+            factIds: sorted(entry.factIds),
+            totalFactIdCount: entry.totalFactIdCount ?? entry.factIds.length,
+            analyzerIds: sorted(entry.analyzerIds),
+            totalAnalyzerIdCount: entry.totalAnalyzerIdCount ?? entry.analyzerIds.length,
+            evidenceRefs: sorted(entry.evidenceRefs),
+            totalEvidenceRefCount: entry.totalEvidenceRefCount ?? entry.evidenceRefs.length,
+          }))
+          .sort((left, right) => compareCanonicalStrings(left.valueDigest, right.valueDigest)),
+      }))
+      .sort((left, right) => compareCanonicalStrings(left.canonicalKey, right.canonicalKey)),
+  };
+}

package/src/facts/types.ts

@@ -160,6 +160,11 @@ export interface StyleFontSizeScaleFact extends BaseFact, PolicyFactExcludes {
 export interface StyleCssVarsMustBeDefinedFact extends BaseFact, PolicyFactExcludes {
   kind: "style_css_vars_must_be_defined";
   severity: GovernanceSeverity;
+  /**
+   * Repo-relative path of the resolved fragments config, when the scan knows
+   * it. Omitted from fact identity — same policy, different config filename.
+   */
+  configPath?: string;
 }
 
 /**
@@ -758,3 +763,34 @@ export type FactKind = Fact["kind"];
 
 /** Narrows a Fact union by kind. */
 export type FactOfKind<K extends FactKind> = Extract<Fact, { kind: K }>;
+
+// ---------------------------------------------------------------------------
+// V1 canonical integrity vocabulary (additive; current FactIndex is unchanged)
+// ---------------------------------------------------------------------------
+
+export interface CanonicalFactConflictValueV1 {
+  valueDigest: string;
+  factIds: string[];
+  totalFactIdCount?: number;
+  analyzerIds: string[];
+  totalAnalyzerIdCount?: number;
+  evidenceRefs: string[];
+  totalEvidenceRefCount?: number;
+}
+
+export interface CanonicalFactConflictV1 {
+  canonicalKey: string;
+  factKind: string;
+  state: "conflict";
+  values: CanonicalFactConflictValueV1[];
+  totalValueCount?: number;
+}
+
+export type CanonicalFactIntegrityV1 =
+  | { state: "healthy"; coalescedDuplicateCount: number }
+  | {
+      state: "conflict";
+      coalescedDuplicateCount: number;
+      conflicts: CanonicalFactConflictV1[];
+      totalConflictCount?: number;
+    };

package/src/feature-plan/digest.ts

@@ -0,0 +1,217 @@
+import { canonicalPreimage, compareCanonicalStrings, sha256Hex } from "../contract/hash.js";
+import { featureRevisionIdFromDigest, type DigestHex } from "../domain-ids.js";
+import {
+  AGENT_FEATURE_CONTEXT_MAX_BYTES_V1,
+  agentFeatureContextV1Schema as structuralAgentFeatureContextV1Schema,
+  approvedFeatureManifestInputV1Schema,
+  approvedFeatureManifestV1Schema,
+  featureProposalInputV1Schema,
+  featureProposalV1Schema,
+  type AgentFeatureContextV1,
+  type ApprovedFeatureManifestInputV1,
+  type ApprovedFeatureManifestV1,
+  type FeatureProposalInputV1,
+  type FeatureProposalV1,
+} from "./types.js";
+
+const sortedUnique = (values: readonly string[]): string[] => [...new Set(values)].sort();
+
+function normalizeEvidenceRefs<T extends { evidenceRefIds: string[] }>(row: T): T {
+  return { ...row, evidenceRefIds: sortedUnique(row.evidenceRefIds) };
+}
+
+function normalizeCommon<
+  T extends {
+    placement: FeatureProposalInputV1["placement"];
+    componentUses: FeatureProposalInputV1["componentUses"];
+    tokenUses: FeatureProposalInputV1["tokenUses"];
+    patternUses: FeatureProposalInputV1["patternUses"];
+    layout: FeatureProposalInputV1["layout"];
+    responsive: FeatureProposalInputV1["responsive"];
+    scenarios: FeatureProposalInputV1["scenarios"];
+    gaps: FeatureProposalInputV1["gaps"];
+    acceptance: FeatureProposalInputV1["acceptance"];
+    evidenceRefs: FeatureProposalInputV1["evidenceRefs"];
+  },
+>(value: T): T {
+  return {
+    ...value,
+    placement: normalizeEvidenceRefs(value.placement),
+    componentUses: value.componentUses
+      .map(normalizeEvidenceRefs)
+      .sort((left, right) => compareCanonicalStrings(left.useId, right.useId)),
+    tokenUses: value.tokenUses
+      .map(normalizeEvidenceRefs)
+      .sort((left, right) => compareCanonicalStrings(left.useId, right.useId)),
+    patternUses: value.patternUses
+      .map(normalizeEvidenceRefs)
+      .sort((left, right) => compareCanonicalStrings(left.useId, right.useId)),
+    layout: {
+      concerns: value.layout.concerns
+        .map(normalizeEvidenceRefs)
+        .sort((left, right) => compareCanonicalStrings(left.concern, right.concern)),
+    },
+    responsive: value.responsive
+      .map(normalizeEvidenceRefs)
+      .sort((left, right) => compareCanonicalStrings(left.decisionId, right.decisionId)),
+    scenarios: value.scenarios
+      .map((scenario) => ({ ...scenario, acceptanceIds: sortedUnique(scenario.acceptanceIds) }))
+      .sort((left, right) => compareCanonicalStrings(left.scenarioId, right.scenarioId)),
+    gaps: value.gaps
+      .map(normalizeEvidenceRefs)
+      .sort((left, right) => compareCanonicalStrings(left.gapId, right.gapId)),
+    acceptance: value.acceptance
+      .map(normalizeEvidenceRefs)
+      .sort((left, right) => compareCanonicalStrings(left.acceptanceId, right.acceptanceId)),
+    evidenceRefs: [...value.evidenceRefs].sort((left, right) =>
+      compareCanonicalStrings(left.evidenceId, right.evidenceId)
+    ),
+  };
+}
+
+export function normalizeFeatureProposalInputV1(
+  value: FeatureProposalInputV1
+): FeatureProposalInputV1 {
+  const parsed = featureProposalInputV1Schema.parse(value);
+  return normalizeCommon({
+    ...parsed,
+    questions: parsed.questions
+      .map((question) => ({ ...normalizeEvidenceRefs(question), options: [...question.options] }))
+      .sort((left, right) => compareCanonicalStrings(left.decisionId, right.decisionId)),
+  }) as FeatureProposalInputV1;
+}
+
+function proposalProjection(proposal: FeatureProposalInputV1): Record<string, unknown> {
+  return {
+    schema: "feature-revision.v1",
+    kind: proposal.kind,
+    planId: proposal.planId,
+    parentRevisionDigest: proposal.parentRevisionDigest,
+    pins: proposal.pins,
+    placement: proposal.placement,
+    componentUses: proposal.componentUses,
+    tokenUses: proposal.tokenUses,
+    patternUses: proposal.patternUses,
+    layout: proposal.layout,
+    responsive: proposal.responsive,
+    scenarios: proposal.scenarios,
+    gaps: proposal.gaps,
+    acceptance: proposal.acceptance,
+    questions: proposal.questions,
+    evidenceRefs: proposal.evidenceRefs,
+  };
+}
+
+export function featureProposalRevisionDigestV1(value: FeatureProposalInputV1): DigestHex {
+  const proposal = normalizeFeatureProposalInputV1(value);
+  return sha256Hex(canonicalPreimage(proposalProjection(proposal)));
+}
+
+export function buildFeatureProposalV1(value: FeatureProposalInputV1): FeatureProposalV1 {
+  const proposal = normalizeFeatureProposalInputV1(value);
+  const revisionDigest = sha256Hex(canonicalPreimage(proposalProjection(proposal)));
+  return featureProposalV1Schema.parse({
+    ...proposal,
+    revisionId: featureRevisionIdFromDigest(revisionDigest),
+    revisionDigest,
+  }) as FeatureProposalV1;
+}
+
+export function parseFeatureProposalV1(value: unknown): FeatureProposalV1 {
+  const parsed = featureProposalV1Schema.parse(value);
+  const { revisionId, revisionDigest, ...input } = parsed;
+  const rebuilt = buildFeatureProposalV1(input as FeatureProposalInputV1);
+  if (revisionId !== rebuilt.revisionId || revisionDigest !== rebuilt.revisionDigest) {
+    throw new TypeError("Feature proposal derived identity does not match its semantic projection");
+  }
+  return rebuilt;
+}
+
+export function normalizeApprovedFeatureManifestInputV1(
+  value: ApprovedFeatureManifestInputV1
+): ApprovedFeatureManifestInputV1 {
+  const parsed = approvedFeatureManifestInputV1Schema.parse(value);
+  return normalizeCommon({
+    ...parsed,
+    decisions: [...parsed.decisions].sort((left, right) =>
+      compareCanonicalStrings(left.decisionId, right.decisionId)
+    ),
+    approval: { ...parsed.approval },
+    validatedGrounding: { ...parsed.validatedGrounding },
+  }) as ApprovedFeatureManifestInputV1;
+}
+
+function manifestProjection(manifest: ApprovedFeatureManifestInputV1): Record<string, unknown> {
+  return {
+    schema: "feature-revision.v1",
+    kind: manifest.kind,
+    planId: manifest.planId,
+    parentRevisionDigest: manifest.parentRevisionDigest,
+    proposalRevisionDigest: manifest.proposalRevisionDigest,
+    pins: manifest.pins,
+    validatedGrounding: manifest.validatedGrounding,
+    placement: manifest.placement,
+    componentUses: manifest.componentUses,
+    tokenUses: manifest.tokenUses,
+    patternUses: manifest.patternUses,
+    layout: manifest.layout,
+    responsive: manifest.responsive,
+    scenarios: manifest.scenarios,
+    gaps: manifest.gaps,
+    acceptance: manifest.acceptance,
+    evidenceRefs: manifest.evidenceRefs,
+    decisions: manifest.decisions,
+    approval: {
+      approverUserId: manifest.approval.approverUserId,
+      decisionDigest: manifest.approval.decisionDigest,
+      expiresAt: manifest.approval.expiresAt,
+    },
+  };
+}
+
+export function approvedFeatureManifestRevisionDigestV1(
+  value: ApprovedFeatureManifestInputV1
+): DigestHex {
+  const manifest = normalizeApprovedFeatureManifestInputV1(value);
+  return sha256Hex(canonicalPreimage(manifestProjection(manifest)));
+}
+
+export function buildApprovedFeatureManifestV1(
+  value: ApprovedFeatureManifestInputV1
+): ApprovedFeatureManifestV1 {
+  const manifest = normalizeApprovedFeatureManifestInputV1(value);
+  const revisionDigest = sha256Hex(canonicalPreimage(manifestProjection(manifest)));
+  return approvedFeatureManifestV1Schema.parse({
+    ...manifest,
+    revisionId: featureRevisionIdFromDigest(revisionDigest),
+    revisionDigest,
+  }) as ApprovedFeatureManifestV1;
+}
+
+export function parseApprovedFeatureManifestV1(value: unknown): ApprovedFeatureManifestV1 {
+  const parsed = approvedFeatureManifestV1Schema.parse(value);
+  const { revisionId, revisionDigest, ...input } = parsed;
+  const rebuilt = buildApprovedFeatureManifestV1(input as ApprovedFeatureManifestInputV1);
+  if (revisionId !== rebuilt.revisionId || revisionDigest !== rebuilt.revisionDigest) {
+    throw new TypeError(
+      "Approved manifest derived identity does not match its semantic projection"
+    );
+  }
+  return rebuilt;
+}
+
+export const agentFeatureContextV1Schema = structuralAgentFeatureContextV1Schema.superRefine(
+  (value, context) => {
+    const bytes = new TextEncoder().encode(canonicalPreimage(value)).byteLength;
+    if (bytes > AGENT_FEATURE_CONTEXT_MAX_BYTES_V1) {
+      context.addIssue({
+        code: "custom",
+        message: `Agent feature context exceeds ${AGENT_FEATURE_CONTEXT_MAX_BYTES_V1} UTF-8 bytes`,
+      });
+    }
+  }
+);
+
+export function parseAgentFeatureContextV1(value: unknown): AgentFeatureContextV1 {
+  return agentFeatureContextV1Schema.parse(value) as AgentFeatureContextV1;
+}