@usefragments/core 1.10.2 → 1.11.0

package/src/feature-plan/feature-plan-v1.test.ts

@@ -0,0 +1,529 @@
+import { describe, expect, it } from "vitest";
+import { featurePlanIdFromEntropy } from "../domain-ids.js";
+import {
+  agentFeatureContextV1Schema,
+  approvedFeatureManifestV1Schema,
+  buildApprovedFeatureManifestV1,
+  buildFeatureProposalV1,
+  featureProposalV1Schema,
+  parseApprovedFeatureManifestV1,
+  parseFeatureProposalV1,
+  type ApprovedFeatureManifestInputV1,
+  type FeatureProposalInputV1,
+} from "./index.js";
+
+const A = "a".repeat(64);
+const B = "b".repeat(64);
+const C = "c".repeat(64);
+const D = "d".repeat(64);
+const PLAN_ID = featurePlanIdFromEntropy("00112233445566778899aabbccddeeff");
+
+function proposalInput(overrides: Partial<FeatureProposalInputV1> = {}): FeatureProposalInputV1 {
+  return {
+    schemaVersion: 1,
+    kind: "proposal",
+    planId: PLAN_ID,
+    pins: {
+      bindingId: "binding_1",
+      grounding: {
+        sourceCommitId: "head-sha",
+        analysisPlanDigest: A,
+        contextSliceDigest: B,
+      },
+      authority: {
+        fcid: C,
+        contractArtifactDigest: D,
+        analysisObligationsDigest: A,
+      },
+      evidenceDigest: B,
+    },
+    placement: {
+      targetKind: "page",
+      targetRef: "settings/notifications",
+      routeRef: "/settings/notifications",
+      parentSlotRef: "WorkspacePage.content",
+      evidenceRefIds: ["source-shell"],
+    },
+    componentUses: [
+      {
+        useId: "switch",
+        componentId: "Switch",
+        importPath: "@usefragments/ui",
+        purpose: "Toggle notification preference",
+        props: { size: "md", disabled: false },
+        evidenceRefIds: ["contract-switch", "source-form"],
+      },
+    ],
+    tokenUses: [
+      {
+        useId: "section-gap",
+        tokenId: "--fui-space-3",
+        role: "gap",
+        evidenceRefIds: ["contract-space"],
+      },
+    ],
+    patternUses: [
+      {
+        useId: "settings-row",
+        patternId: "cloud.settings-row",
+        patternRevisionDigest: A,
+        status: "approved_guidance",
+        disposition: "reuse",
+        evidenceRefIds: ["source-form"],
+      },
+    ],
+    layout: {
+      concerns: [
+        {
+          concern: "outer_inline_spacing",
+          ownerLayer: "application_shell",
+          ownerRef: "WorkspacePage",
+          childAction: "consume",
+          evidenceRefIds: ["source-shell"],
+        },
+        {
+          concern: "child_gap",
+          ownerLayer: "section",
+          ownerRef: "NotificationPreferencesSection",
+          childAction: "own",
+          tokenRef: "--fui-space-3",
+          evidenceRefIds: ["contract-space"],
+        },
+      ],
+    },
+    responsive: [
+      {
+        decisionId: "responsive-row",
+        source: "observed",
+        breakpointRef: "$fui-breakpoint-md",
+        behavior: "Stack label and control below md",
+        evidenceRefIds: ["source-form"],
+      },
+    ],
+    scenarios: [
+      {
+        scenarioId: "save-error",
+        viewportRef: "mobile",
+        dataState: "error",
+        interactionState: "saving",
+        acceptanceIds: ["A2"],
+      },
+    ],
+    gaps: [
+      {
+        gapId: "inline-field",
+        capability: "Inline labelled boolean field",
+        required: false,
+        disposition: "local_composition",
+        reason: "Reuse the existing settings-row composition",
+        evidenceRefIds: ["source-form"],
+      },
+    ],
+    acceptance: [
+      {
+        acceptanceId: "A1",
+        statement: "Owner saves a preference and reload sees it",
+        proof: "integration",
+        required: true,
+        evidenceRefIds: ["user-intent"],
+      },
+      {
+        acceptanceId: "A2",
+        statement: "A failed save restores the prior value",
+        proof: "browser",
+        required: true,
+        evidenceRefIds: ["user-intent"],
+      },
+    ],
+    questions: [
+      {
+        decisionId: "save-model",
+        kind: "reuse",
+        question: "Save immediately or as a section?",
+        options: [
+          { optionId: "immediate", label: "Immediately", consequence: "Matches current settings" },
+          { optionId: "section", label: "Save section", consequence: "Adds dirty state" },
+        ],
+        recommendedOptionId: "immediate",
+        required: true,
+        evidenceRefIds: ["source-form"],
+      },
+    ],
+    evidenceRefs: [
+      {
+        evidenceId: "user-intent",
+        kind: "user_intent",
+        authority: "user_asserted",
+        ref: "intent:settings-notifications",
+        digest: A,
+      },
+      {
+        evidenceId: "source-shell",
+        kind: "source",
+        authority: "source_observed",
+        ref: "apps/cloud/src/WorkspacePage.tsx:1",
+        digest: B,
+      },
+      {
+        evidenceId: "source-form",
+        kind: "source",
+        authority: "source_observed",
+        ref: "apps/cloud/src/SettingsRow.tsx:1",
+        digest: C,
+      },
+      {
+        evidenceId: "contract-switch",
+        kind: "contract",
+        authority: "contract_approved",
+        ref: "component:Switch",
+        digest: D,
+      },
+      {
+        evidenceId: "contract-space",
+        kind: "contract",
+        authority: "contract_approved",
+        ref: "token:--fui-space-3",
+        digest: A,
+      },
+    ],
+    ...overrides,
+  };
+}
+
+function manifestInput(
+  overrides: Partial<ApprovedFeatureManifestInputV1> = {}
+): ApprovedFeatureManifestInputV1 {
+  const proposal = buildFeatureProposalV1(proposalInput());
+  return {
+    schemaVersion: 1,
+    kind: "approved_manifest",
+    planId: proposal.planId,
+    parentRevisionDigest: proposal.revisionDigest,
+    proposalRevisionDigest: proposal.revisionDigest,
+    pins: proposal.pins,
+    validatedGrounding: { ...proposal.pins.grounding },
+    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,
+    evidenceRefs: proposal.evidenceRefs,
+    decisions: [{ decisionId: "save-model", selectedOptionId: "immediate" }],
+    approval: {
+      approverUserId: "user_1",
+      decisionDigest: D,
+      approvedAt: "2026-09-01T12:00:00.000Z",
+    },
+    ...overrides,
+  };
+}
+
+describe("FeatureProposalV1", () => {
+  it("has a checked-in stable revision digest", () => {
+    const proposal = buildFeatureProposalV1(proposalInput());
+    expect(proposal.revisionDigest).toBe(
+      "a0e17ecec3c2a88ed421bd1102c1a806be34887f8e053b7236cd5e9551fd0cf7"
+    );
+    expect(proposal.revisionId).toBe(`fpr_${proposal.revisionDigest}`);
+    expect(parseFeatureProposalV1(proposal)).toEqual(proposal);
+  });
+
+  it("normalizes set-like order but preserves decision-option order", () => {
+    const first = buildFeatureProposalV1(proposalInput());
+    const reordered = buildFeatureProposalV1(
+      proposalInput({
+        evidenceRefs: [...proposalInput().evidenceRefs].reverse(),
+        componentUses: proposalInput().componentUses.map((use) => ({
+          ...use,
+          evidenceRefIds: [...use.evidenceRefIds].reverse(),
+          props: { disabled: false, size: "md" },
+        })),
+        acceptance: [...proposalInput().acceptance].reverse(),
+        layout: { concerns: [...proposalInput().layout.concerns].reverse() },
+      })
+    );
+    expect(reordered.revisionDigest).toBe(first.revisionDigest);
+
+    const optionsReordered = buildFeatureProposalV1(
+      proposalInput({
+        questions: proposalInput().questions.map((question) => ({
+          ...question,
+          options: [...question.options].reverse(),
+        })),
+      })
+    );
+    expect(optionsReordered.revisionDigest).not.toBe(first.revisionDigest);
+  });
+
+  it("uses locale-independent Unicode ordering for canonical feature records", () => {
+    const unicodeEvidence = [
+      {
+        evidenceId: "unicode-ä",
+        kind: "source" as const,
+        authority: "source_observed" as const,
+        ref: "src/ä.tsx:1",
+        digest: A,
+      },
+      {
+        evidenceId: "unicode-z",
+        kind: "source" as const,
+        authority: "source_observed" as const,
+        ref: "src/z.tsx:1",
+        digest: B,
+      },
+    ];
+    const first = buildFeatureProposalV1(
+      proposalInput({ evidenceRefs: [...proposalInput().evidenceRefs, ...unicodeEvidence] })
+    );
+    const reordered = buildFeatureProposalV1(
+      proposalInput({
+        evidenceRefs: [...proposalInput().evidenceRefs, ...unicodeEvidence].reverse(),
+      })
+    );
+    expect(
+      first.evidenceRefs
+        .map((evidence) => evidence.evidenceId)
+        .filter((evidenceId) => evidenceId.startsWith("unicode-"))
+    ).toEqual(["unicode-z", "unicode-ä"]);
+    expect(reordered.revisionDigest).toBe(first.revisionDigest);
+  });
+
+  it("changes identity for authority, layout, and workflow changes", () => {
+    const first = buildFeatureProposalV1(proposalInput());
+    expect(
+      buildFeatureProposalV1(
+        proposalInput({ pins: { ...proposalInput().pins, evidenceDigest: C } })
+      ).revisionDigest
+    ).not.toBe(first.revisionDigest);
+    expect(
+      buildFeatureProposalV1(
+        proposalInput({
+          layout: {
+            concerns: proposalInput().layout.concerns.map((row) =>
+              row.concern === "child_gap"
+                ? { ...row, ownerLayer: "pattern" as const, ownerRef: "cloud.settings-row" }
+                : row
+            ),
+          },
+        })
+      ).revisionDigest
+    ).not.toBe(first.revisionDigest);
+    expect(
+      buildFeatureProposalV1(
+        proposalInput({ planId: featurePlanIdFromEntropy("ffeeddccbbaa99887766554433221100") })
+      ).revisionDigest
+    ).not.toBe(first.revisionDigest);
+  });
+
+  it("rejects unknown fields, dangling evidence, invalid gaps, and duplicate layout owners", () => {
+    expect(() =>
+      featureProposalV1Schema.parse({ ...buildFeatureProposalV1(proposalInput()), extra: true })
+    ).toThrow();
+    expect(() =>
+      buildFeatureProposalV1(
+        proposalInput({ placement: { ...proposalInput().placement, evidenceRefIds: ["missing"] } })
+      )
+    ).toThrow();
+    expect(() =>
+      buildFeatureProposalV1(
+        proposalInput({
+          componentUses: [
+            {
+              ...proposalInput().componentUses[0],
+              props: { label: "x".repeat(33 * 1024) },
+            },
+          ],
+        })
+      )
+    ).toThrow();
+    expect(() =>
+      buildFeatureProposalV1(
+        proposalInput({
+          gaps: [{ ...proposalInput().gaps[0], disposition: "invent" as never }],
+        })
+      )
+    ).toThrow();
+    expect(() =>
+      buildFeatureProposalV1(
+        proposalInput({
+          layout: {
+            concerns: [
+              ...proposalInput().layout.concerns,
+              { ...proposalInput().layout.concerns[0], ownerRef: "FeaturePage" },
+            ],
+          },
+        })
+      )
+    ).toThrow();
+  });
+});
+
+describe("ApprovedFeatureManifestV1", () => {
+  it("pins approved choices and excludes approvedAt from semantic identity", () => {
+    const manifest = buildApprovedFeatureManifestV1(manifestInput());
+    expect(manifest.revisionDigest).toBe(
+      "2b9eb1d40d853cd47412d811526eaaba6aaaa7cb855778d08fa1d4acd930bcaa"
+    );
+    expect(parseApprovedFeatureManifestV1(manifest)).toEqual(manifest);
+    const laterTimestamp = buildApprovedFeatureManifestV1(
+      manifestInput({
+        approval: { ...manifestInput().approval, approvedAt: "2026-09-02T12:00:00.000Z" },
+      })
+    );
+    expect(laterTimestamp.revisionDigest).toBe(manifest.revisionDigest);
+    const differentChoice = buildApprovedFeatureManifestV1(
+      manifestInput({ decisions: [{ decisionId: "save-model", selectedOptionId: "section" }] })
+    );
+    expect(differentChoice.revisionDigest).not.toBe(manifest.revisionDigest);
+  });
+
+  it("blocks required unresolved/proposed gaps and dangling override decisions", () => {
+    expect(() =>
+      buildApprovedFeatureManifestV1(
+        manifestInput({
+          gaps: [
+            {
+              ...manifestInput().gaps[0],
+              required: true,
+              disposition: "unresolved",
+            },
+          ],
+        })
+      )
+    ).toThrow();
+    expect(() =>
+      buildApprovedFeatureManifestV1(
+        manifestInput({
+          gaps: [
+            {
+              ...manifestInput().gaps[0],
+              required: true,
+              disposition: "proposed_contract_addition",
+              proposedContractCandidateId: "candidate-field-row",
+            },
+          ],
+        })
+      )
+    ).toThrow();
+    expect(() =>
+      buildApprovedFeatureManifestV1(
+        manifestInput({
+          layout: {
+            concerns: manifestInput().layout.concerns.map((row) =>
+              row.concern === "child_gap"
+                ? { ...row, childAction: "override" as const, overrideDecisionId: "missing" }
+                : row
+            ),
+          },
+        })
+      )
+    ).toThrow();
+  });
+
+  it("allows compatible re-grounding to a newer source and exact analysis plan", () => {
+    const advanced = buildApprovedFeatureManifestV1(
+      manifestInput({
+        validatedGrounding: {
+          sourceCommitId: "next-head-sha",
+          analysisPlanDigest: C,
+          contextSliceDigest: manifestInput().pins.grounding.contextSliceDigest,
+        },
+      })
+    );
+    expect(advanced.validatedGrounding).toMatchObject({
+      sourceCommitId: "next-head-sha",
+      analysisPlanDigest: C,
+    });
+    expect(() =>
+      buildApprovedFeatureManifestV1(
+        manifestInput({
+          validatedGrounding: {
+            ...manifestInput().validatedGrounding,
+            contextSliceDigest: D,
+          },
+        })
+      )
+    ).toThrow(/material context/u);
+  });
+
+  it.each(["observed", "candidate", "deprecated"] as const)(
+    "prevents a %s pattern from becoming an approved reusable claim",
+    (status) => {
+      expect(() =>
+        buildApprovedFeatureManifestV1(
+          manifestInput({
+            patternUses: [
+              {
+                ...manifestInput().patternUses[0],
+                status,
+                disposition: "reuse",
+              },
+            ],
+          })
+        )
+      ).toThrow(/may be reused/u);
+    }
+  );
+
+  it.each(["approved_guidance", "contract_canonical"] as const)(
+    "allows a %s pattern to be reused",
+    (status) => {
+      expect(
+        buildApprovedFeatureManifestV1(
+          manifestInput({
+            patternUses: [{ ...manifestInput().patternUses[0], status, disposition: "reuse" }],
+          })
+        ).patternUses[0]
+      ).toMatchObject({ status, disposition: "reuse" });
+    }
+  );
+
+  it("validates the bounded agent projection", () => {
+    const manifest = buildApprovedFeatureManifestV1(manifestInput());
+    const context = {
+      schemaVersion: 1 as const,
+      planId: manifest.planId,
+      manifestDigest: manifest.revisionDigest,
+      pins: manifest.pins,
+      validatedGrounding: manifest.validatedGrounding,
+      target: manifest.placement,
+      componentUses: manifest.componentUses,
+      tokenUses: manifest.tokenUses,
+      patternUses: manifest.patternUses,
+      layout: manifest.layout,
+      responsive: manifest.responsive,
+      scenarios: manifest.scenarios,
+      acceptedGaps: manifest.gaps,
+      acceptance: manifest.acceptance,
+      decisions: manifest.decisions,
+      relevantFiles: ["apps/cloud/src/settings.tsx"],
+      commands: ["pnpm test"],
+    };
+    expect(agentFeatureContextV1Schema.parse(context)).toEqual(context);
+    expect(() =>
+      agentFeatureContextV1Schema.parse({
+        ...context,
+        commands: ["x".repeat(70 * 1024)],
+      })
+    ).toThrow();
+    expect(() =>
+      agentFeatureContextV1Schema.parse({
+        ...context,
+        relevantFiles: ["/tmp/customer-source.tsx"],
+      })
+    ).toThrow();
+  });
+
+  it("keeps the stored manifest validator strict", () => {
+    expect(() =>
+      approvedFeatureManifestV1Schema.parse({
+        ...buildApprovedFeatureManifestV1(manifestInput()),
+        actorEmail: "not-in-authority-record@example.com",
+      })
+    ).toThrow();
+  });
+});

package/src/feature-plan/index.ts

@@ -0,0 +1,65 @@
+export {
+  AGENT_FEATURE_CONTEXT_MAX_BYTES_V1,
+  FEATURE_PLAN_MAX_ACCEPTANCE_ITEMS_V1,
+  FEATURE_PLAN_MAX_DECISIONS_V1,
+  FEATURE_PLAN_MAX_EVIDENCE_REFS_V1,
+  FEATURE_PLAN_MAX_GAPS_V1,
+  FEATURE_PLAN_MAX_SCENARIOS_V1,
+  FEATURE_PLAN_MAX_TEXT_BYTES_V1,
+  FEATURE_PLAN_MAX_USES_PER_KIND_V1,
+  approvedFeatureManifestInputV1Schema,
+  approvedFeatureManifestV1Schema,
+  capabilityGapV1Schema,
+  componentUseDecisionV1Schema,
+  decisionRequestV1Schema,
+  decisionResolutionV1Schema,
+  evidenceRefV1Schema,
+  featureAcceptanceItemV1Schema,
+  featurePinsV1Schema,
+  featureProposalInputV1Schema,
+  featureProposalV1Schema,
+  gapDispositionV1Schema,
+  layoutConcernV1Schema,
+  layoutOwnershipV1Schema,
+  patternStatusV1Schema,
+  patternUseDecisionV1Schema,
+  placementDecisionV1Schema,
+  responsiveDecisionV1Schema,
+  scenarioRequirementV1Schema,
+  tokenUseDecisionV1Schema,
+} from "./types.js";
+export type {
+  AgentFeatureContextV1,
+  ApprovedFeatureManifestInputV1,
+  ApprovedFeatureManifestV1,
+  CapabilityGapV1,
+  ComponentUseDecisionV1,
+  DecisionRequestV1,
+  DecisionResolutionV1,
+  EvidenceRefV1,
+  FeatureAcceptanceItemV1,
+  FeaturePinsV1,
+  FeatureProposalInputV1,
+  FeatureProposalV1,
+  GapDispositionV1,
+  LayoutConcernV1,
+  LayoutOwnershipV1,
+  PatternStatusV1,
+  PatternUseDecisionV1,
+  PlacementDecisionV1,
+  ResponsiveDecisionV1,
+  ScenarioRequirementV1,
+  TokenUseDecisionV1,
+} from "./types.js";
+export {
+  agentFeatureContextV1Schema,
+  approvedFeatureManifestRevisionDigestV1,
+  buildApprovedFeatureManifestV1,
+  buildFeatureProposalV1,
+  featureProposalRevisionDigestV1,
+  normalizeApprovedFeatureManifestInputV1,
+  normalizeFeatureProposalInputV1,
+  parseAgentFeatureContextV1,
+  parseApprovedFeatureManifestV1,
+  parseFeatureProposalV1,
+} from "./digest.js";