@tea-agent/loop-agent 0.42.0-next.1 → 0.42.0-next.10

package/dist/workflows/dag/frontend-shape.js

@@ -0,0 +1,435 @@
+/**
+ * Frontend task shape routing (M7) and shape-transition capsules.
+ *
+ * Pure and independent of the M4 risk classifier and the runtime branch
+ * control. The shape functions here are deterministic (no I/O, no model, no
+ * side effects). This module is the generation-time authority for frontend
+ * task-shape routing; `init-hybrid.ts` must consume it directly and must not
+ * import the closeout renderer.
+ */
+import { createHash } from "node:crypto";
+import { z } from "zod";
+/** Fixture-only node counts. They are NOT the authoritative 15/13/11
+ * topology: split-required has no count. */
+export const FRONTEND_SHAPE_NODE_COUNTS = {
+    micro: 7,
+    small: 10,
+    standard: 11,
+    high: 11,
+};
+const SHAPE_ESCALATION_PATTERNS = [
+    { id: "auth-permission", re: /\bauth\b|\bpermission\b|\brbac\b|登录|权限|\bjwt\b|\bsession\b/i },
+    { id: "sensitive-action", re: /\bpayment\b|delete\s+account|支付|删除用户|\bdestructive\b/i },
+    { id: "ssr-boundary", re: /\bssr\b|\brsc\b|server\s+component|\bhydration\b|server-client/i },
+    { id: "new-route", re: /new\s+route|新增路由|createBrowserRouter|add\s+route/i },
+    { id: "shared-public-api", re: /public\s+api|shared\s+component|公共组件|破坏性|breaking\s+change/i },
+    { id: "schema-api-change", re: /\bopenapi\b|graphql\s+schema|api\s+contract|接口变更|schema\s+change/i },
+    { id: "new-dependency", re: /new\s+dependency|add\s+dependency|npm\s+install|新增依赖/i },
+    { id: "cross-domain-paths", re: /多个领域|cross-module|multiple\s+packages/i },
+];
+const SHAPE_SMALL_PATTERNS = [
+    { id: "single-component", re: /single\s+component|单一组件|局部样式|style\s+tweak|css\s+only|文案|copy\s+change/i },
+    { id: "no-remote", re: /no\s+api|无\s*api|无\s*接口|本地状态|local\s+state\s+only|pure\s+ui/i },
+];
+const SHAPE_SPLIT_REQUIRED_PATTERN = /拆分|split\s+(?:requirement|task|需求)|large\s+requirement|大型需求|多步骤需求/i;
+/**
+ * Negative phrasing the contract model routinely echoes as a disposition
+ * statement ("无需任务拆分" / "不需要拆分" / "no split needed"). These must
+ * NOT count as split-required signals — otherwise every contract that says it
+ * does NOT need a split false-escalates to `large-requirement-split`.
+ */
+const SHAPE_SPLIT_REQUIRED_NEGATION = /(?:无需|不需要|不用|无须|无)\s*(?:任务|需求)?\s*拆分|no\s+split|not\s+split|no\s+requirement\s+split|don'?t\s+split/i;
+const EXECUTABLE_SHAPE_RANK = {
+    micro: 0,
+    small: 1,
+    standard: 2,
+    high: 3,
+};
+function pathSpreadScore(paths) {
+    const tops = new Set(paths
+        .map((p) => p.replace(/\\/g, "/").split("/").filter(Boolean)[0] ?? "")
+        .filter(Boolean));
+    return tops.size;
+}
+function collectEscalationSignals(blob, supervised) {
+    const signals = [];
+    for (const pattern of SHAPE_ESCALATION_PATTERNS) {
+        if (pattern.re.test(blob))
+            signals.push(pattern.id);
+    }
+    if (supervised)
+        signals.push("supervised-profile");
+    if (SHAPE_SPLIT_REQUIRED_PATTERN.test(blob) &&
+        !SHAPE_SPLIT_REQUIRED_NEGATION.test(blob)) {
+        signals.push("large-requirement-split");
+    }
+    return [...new Set(signals)];
+}
+function resolveBaselineFrontendTaskShape(input) {
+    const blob = [
+        input.requirementMarkdown ?? "",
+        input.constraintMarkdown ?? "",
+        (input.allowedPaths ?? []).join("\n"),
+    ].join("\n");
+    const profile = (input.governanceProfile ?? "").toLowerCase();
+    const supervised = profile === "supervised" ||
+        profile.includes("supervised") ||
+        /\bsupervised\b/i.test(blob);
+    const escalationSignals = collectEscalationSignals(blob, supervised);
+    const smallHits = [];
+    for (const pattern of SHAPE_SMALL_PATTERNS) {
+        if (pattern.re.test(blob))
+            smallHits.push(pattern.id);
+    }
+    const paths = input.allowedPaths ?? [];
+    const spread = pathSpreadScore(paths);
+    const concentrated = spread <= 1 && paths.length <= 4;
+    const hasApiSignal = /\b(api|fetch|axios|graphql|endpoint|远程|接口)\b/i.test(blob) &&
+        !(/(?:^|[^\w])(?:no\s+api|not-needed)(?:$|[^\w])/i.test(blob) ||
+            /无\s*api|无\s*接口/i.test(blob));
+    const complexity = (input.complexity ?? "").toLowerCase();
+    // split-required wins over everything: it is a termination/escalation
+    // signal, not an executable topology.
+    if (input.splitSignal.splitRequired) {
+        return {
+            shape: "split-required",
+            signals: [...new Set([...escalationSignals, "split-required"])],
+            rejectedSignals: smallHits.map((id) => `small:${id}:blocked-by-split-required`),
+            reason: "split-required signal present: terminate/escalate before planning or writing",
+        };
+    }
+    if (supervised) {
+        const shape = escalationSignals.filter((s) => s !== "supervised-profile").length > 0
+            ? "high"
+            : "standard";
+        return {
+            shape,
+            signals: escalationSignals,
+            rejectedSignals: smallHits.map((id) => `small:${id}:blocked-by-supervised`),
+            reason: shape === "high"
+                ? `high escalation under supervised: ${escalationSignals.join(", ")}`
+                : "supervised profile forces full gates (standard minimum)",
+        };
+    }
+    if (escalationSignals.length > 0) {
+        return {
+            shape: "high",
+            signals: escalationSignals,
+            rejectedSignals: smallHits.map((id) => `small:${id}:blocked-by-escalation`),
+            reason: `escalation signals present: ${escalationSignals.join(", ")}`,
+        };
+    }
+    // micro: the smallest possible change — explicit micro complexity, no API
+    // signal, no escalation, concentrated paths.
+    if ((complexity === "micro" || complexity === "trivial") &&
+        concentrated &&
+        !hasApiSignal) {
+        return {
+            shape: "micro",
+            signals: smallHits.length > 0 ? smallHits : ["micro-scope"],
+            rejectedSignals: [],
+            reason: "micro scope: trivial single-file change without remote API",
+        };
+    }
+    // small: no escalation, no supervised, small keywords, concentrated paths,
+    // no remote API signal.
+    if (smallHits.length > 0 &&
+        concentrated &&
+        !hasApiSignal &&
+        (complexity === "small" || complexity === "low")) {
+        return {
+            shape: "small",
+            signals: smallHits,
+            rejectedSignals: [],
+            reason: `small signals without escalation: ${smallHits.join(", ")}`,
+        };
+    }
+    const rejected = smallHits.map((id) => `small:${id}:blocked-by-${hasApiSignal ? "api-signal" : "path-spread"}`);
+    return {
+        shape: "standard",
+        signals: ["default-standard"],
+        rejectedSignals: rejected,
+        reason: smallHits.length > 0
+            ? hasApiSignal
+                ? "small keywords present but API/remote signals require standard topology"
+                : "small keywords present but path spread requires standard topology"
+            : "ambiguous or standard frontend work; default standard topology",
+    };
+}
+function reshapeFloorShape(capsule) {
+    if (capsule.requestedMinimumRisk === "high")
+        return "high";
+    if (capsule.requestedMinimumSize === "standard")
+        return "standard";
+    if (capsule.requestedMinimumRisk === "standard")
+        return "standard";
+    return "small";
+}
+function raiseExecutableShape(baseline, floor) {
+    if (baseline === "split-required")
+        return "split-required";
+    return EXECUTABLE_SHAPE_RANK[baseline] >= EXECUTABLE_SHAPE_RANK[floor]
+        ? baseline
+        : floor;
+}
+/**
+ * Route a frontend task into one of five shapes. Pure and independent of the
+ * M4 risk classifier and the runtime branch control. Escalation signals
+ * (high-risk keywords, supervised profile, cross-domain, large requirement
+ * split) always raise the shape above `small` or produce `split-required` —
+ * they are never silently swallowed. A verified shape-transition capsule, when
+ * present, outranks natural-language keywords and complexity but never lowers
+ * an already-higher executable baseline.
+ */
+export function resolveFrontendTaskShape(input) {
+    const capsule = input.shapeTransitionCapsule != null
+        ? parseFrontendShapeTransitionCapsule(input.shapeTransitionCapsule)
+        : undefined;
+    if (capsule) {
+        if (!input.taskId || !input.sourceDigest) {
+            throw new Error("shape transition capsule requires matching taskId and sourceDigest");
+        }
+        if (capsule.taskId !== input.taskId ||
+            capsule.sourceDigest !== input.sourceDigest) {
+            throw new Error("shape transition capsule task/source binding mismatch");
+        }
+    }
+    const baseline = resolveBaselineFrontendTaskShape(input);
+    if (!capsule)
+        return baseline;
+    if (capsule.kind === "split") {
+        return {
+            shape: "split-required",
+            signals: [...new Set([...baseline.signals, "shape-transition-split"])],
+            rejectedSignals: baseline.rejectedSignals,
+            reason: `shape transition capsule split: ${capsule.splitProposalRef}`,
+        };
+    }
+    const floor = reshapeFloorShape(capsule);
+    const shape = raiseExecutableShape(baseline.shape, floor);
+    return {
+        shape,
+        signals: [
+            ...new Set([
+                ...baseline.signals,
+                ...capsule.escalationSignals,
+                "shape-transition-reshape",
+            ]),
+        ],
+        rejectedSignals: baseline.rejectedSignals,
+        reason: shape === baseline.shape
+            ? baseline.reason
+            : `shape transition capsule reshape floor ${floor} raised ${baseline.shape}`,
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Frozen topology binding and runtime escalation evaluation           *
+ * ------------------------------------------------------------------ */
+export const FRONTEND_TOPOLOGY_BINDING_SCHEMA_VERSION = 1;
+/** Freeze capability from the generated canonical task set. Node complexity
+ * is deliberately excluded: Standard and High share the same full topology. */
+export function buildFrontendTopologyBinding(taskIds) {
+    const canonicalTaskIds = [...new Set(taskIds)].sort();
+    const capability = canonicalTaskIds.includes("frontend-design-review-pi")
+        ? "full"
+        : "small";
+    const descriptor = {
+        schemaVersion: FRONTEND_TOPOLOGY_BINDING_SCHEMA_VERSION,
+        capability,
+        taskIds: canonicalTaskIds,
+    };
+    return {
+        ...descriptor,
+        canonicalDigest: sha256Utf8(JSON.stringify(sortKeysDeep(descriptor))),
+    };
+}
+export function assertFrontendTopologyBinding(binding, taskIds) {
+    if (!binding)
+        throw new Error("frontend topology binding is missing");
+    const expected = buildFrontendTopologyBinding(taskIds);
+    if (binding.schemaVersion !== expected.schemaVersion ||
+        binding.capability !== expected.capability ||
+        binding.canonicalDigest !== expected.canonicalDigest ||
+        !stringArraysEqual(binding.taskIds, expected.taskIds)) {
+        throw new Error("frontend topology binding drifted from immutable DagSpec tasks");
+    }
+    return binding;
+}
+/** Runtime-only fact derivation. This intentionally does not call the
+ * generation-time `resolveFrontendTaskShape` router. */
+export function deriveFrontendRuntimeShapeFacts(input) {
+    const blob = [
+        input.requirementMarkdown ?? "",
+        input.constraintMarkdown ?? "",
+        (input.allowedPaths ?? []).join("\n"),
+    ].join("\n");
+    const supervised = /\bsupervised\b/i.test(blob);
+    const escalationSignals = collectEscalationSignals(blob, supervised);
+    const paths = input.allowedPaths ?? [];
+    const hasApiSignal = /\b(api|fetch|axios|graphql|endpoint|远程|接口)\b/i.test(blob) &&
+        !(/(?:^|[^\w])(?:no\s+api|not-needed)(?:$|[^\w])/i.test(blob) ||
+            /无\s*api|无\s*接口/i.test(blob));
+    const requiresFull = escalationSignals.length > 0 || pathSpreadScore(paths) > 1 || hasApiSignal;
+    return {
+        splitRequired: input.splitRequired,
+        escalationSignals,
+        minimumTopologyCapability: requiresFull ? "full" : "small",
+    };
+}
+/** Compare committed runtime facts with the generation-frozen topology. */
+export function evaluateFrontendShapeEscalation(input) {
+    if (input.splitRequired) {
+        return {
+            outcome: "split-required",
+            reason: "runtime facts require splitting before downstream dispatch",
+        };
+    }
+    if (input.minimumTopologyCapability === "full" &&
+        input.currentTopologyCapability === "small") {
+        return {
+            outcome: "reshape-required",
+            reason: `runtime facts require full frontend topology${input.escalationSignals.length > 0 ? `: ${input.escalationSignals.join(", ")}` : ""}`,
+        };
+    }
+    return {
+        outcome: "continue",
+        reason: input.escalationSignals.length > 0
+            ? `frozen topology already covers runtime risk signals: ${input.escalationSignals.join(", ")}`
+            : "frozen topology satisfies committed runtime facts",
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Shape transition capsule (§7.1 fields; runtime five-tier mapping)   *
+ * ------------------------------------------------------------------ */
+const hash64 = z.string().regex(/^[a-f0-9]{64}$/);
+const committedIdList = z.array(z.string().min(1)).min(1);
+const frontendShapeTransitionCapsuleBaseFields = {
+    schemaVersion: z.literal(1),
+    taskId: z.string().min(1),
+    parentRunId: z.string().min(1),
+    sourceDigest: hash64,
+    fromShapeDigest: hash64,
+    shapeFactsDigest: hash64,
+    committedFactIds: committedIdList,
+    evidenceRefs: committedIdList,
+    committedAt: z.string().datetime(),
+    capsuleDigest: hash64,
+};
+export const frontendShapeTransitionReshapeCapsuleSchema = z
+    .object({
+    ...frontendShapeTransitionCapsuleBaseFields,
+    kind: z.literal("reshape"),
+    requestedMinimumSize: z.enum(["small", "standard"]),
+    requestedMinimumRisk: z.enum(["low", "standard", "high"]),
+    escalationSignals: z.array(z.string().min(1)),
+})
+    .strict();
+export const frontendShapeTransitionSplitCapsuleSchema = z
+    .object({
+    ...frontendShapeTransitionCapsuleBaseFields,
+    kind: z.literal("split"),
+    splitProposalRef: z.string().min(1),
+    splitProposalDigest: hash64,
+    requirementCoverageDigest: hash64,
+})
+    .strict();
+export const frontendShapeTransitionCapsuleSchema = z.discriminatedUnion("kind", [
+    frontendShapeTransitionReshapeCapsuleSchema,
+    frontendShapeTransitionSplitCapsuleSchema,
+]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function dedupeSortStrings(values) {
+    return [...new Set(values)].sort();
+}
+function stringArraysEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sortKeysDeep(item));
+    }
+    if (isPlainObject(value)) {
+        const keys = Object.keys(value).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+        const out = {};
+        for (const key of keys) {
+            out[key] = sortKeysDeep(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+function sha256Utf8(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function computeCapsuleDigest(fields) {
+    const { capsuleDigest: _ignored, ...rest } = fields;
+    return sha256Utf8(JSON.stringify(sortKeysDeep(rest)));
+}
+function requireNonEmptyStringArray(value, field) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`${field} must be a non-empty array of committed facts`);
+    }
+    if (!value.every((entry) => typeof entry === "string" && entry.length > 0)) {
+        throw new Error(`${field} must contain only non-empty strings`);
+    }
+    return value;
+}
+function normalizeCapsuleRecord(input) {
+    const next = {
+        ...input,
+        committedFactIds: dedupeSortStrings(requireNonEmptyStringArray(input.committedFactIds, "committedFactIds")),
+        evidenceRefs: dedupeSortStrings(requireNonEmptyStringArray(input.evidenceRefs, "evidenceRefs")),
+    };
+    if (next.kind === "reshape") {
+        const signals = next.escalationSignals;
+        if (signals === undefined) {
+            next.escalationSignals = [];
+        }
+        else if (!Array.isArray(signals)) {
+            throw new Error("escalationSignals must be a string array");
+        }
+        else {
+            next.escalationSignals = dedupeSortStrings(signals.map((entry) => {
+                if (typeof entry !== "string") {
+                    throw new Error("escalationSignals must contain only strings");
+                }
+                return entry;
+            }));
+        }
+    }
+    return next;
+}
+export function computeFrontendShapeSourceDigest(input) {
+    return sha256Utf8(JSON.stringify(sortKeysDeep({
+        constraintMarkdown: input.constraintMarkdown ?? "",
+        requirementMarkdown: input.requirementMarkdown,
+    })));
+}
+export function buildFrontendShapeTransitionCapsule(input) {
+    if (!isPlainObject(input)) {
+        throw new Error("FrontendShapeTransitionCapsule input must be an object");
+    }
+    const { capsuleDigest: _ignored, ...rest } = input;
+    const normalized = normalizeCapsuleRecord(rest);
+    return frontendShapeTransitionCapsuleSchema.parse({
+        ...normalized,
+        capsuleDigest: computeCapsuleDigest(normalized),
+    });
+}
+export function parseFrontendShapeTransitionCapsule(value) {
+    const parsed = frontendShapeTransitionCapsuleSchema.parse(value);
+    const normalized = normalizeCapsuleRecord(parsed);
+    if (!stringArraysEqual(parsed.committedFactIds, normalized.committedFactIds) ||
+        !stringArraysEqual(parsed.evidenceRefs, normalized.evidenceRefs) ||
+        (parsed.kind === "reshape" &&
+            !stringArraysEqual(parsed.escalationSignals, normalized.escalationSignals))) {
+        throw new Error("FrontendShapeTransitionCapsule arrays must use canonical sorted unique representation");
+    }
+    const expected = computeCapsuleDigest(normalized);
+    if (parsed.capsuleDigest !== expected) {
+        throw new Error("capsuleDigest does not match canonical fields");
+    }
+    return parsed;
+}

package/dist/workflows/dag/frontend-source-fidelity-ledger.js

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+import { parseLedgerJson, validateRequirementLedger, } from "../../task/source-prepare/ledger.js";
+import { isDagSourceBindingV2 } from "./types.js";
+/**
+ * Validate the semantic source-fidelity ledger binding for a canonical frontend
+ * contract. This is deliberately shared: the compatibility prewrite gate may
+ * report a structured prewrite failure, while the generated production DAG
+ * must deny writer admission on exactly the same evidence.
+ */
+export async function checkFrontendSourceFidelityLedger(input) {
+    const { binding } = input;
+    if (!isDagSourceBindingV2(binding)) {
+        return { ok: true, failureCode: null, failureReason: null, ledger: null };
+    }
+    const absolute = resolveDagTaskSourcePath({
+        workspaceRoot: input.workspaceRoot,
+        taskId: binding.taskId,
+        sourcePath: binding.ledgerPath,
+    });
+    let raw;
+    try {
+        raw = await readFile(absolute, "utf8");
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-missing",
+            failureReason: `frontend source fidelity ledger missing: ${binding.ledgerPath} (${error instanceof Error ? error.message : String(error)})`,
+            ledger: null,
+        };
+    }
+    const actualSha = createHash("sha256").update(raw).digest("hex");
+    if (actualSha !== binding.ledgerSha256) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-stale",
+            failureReason: `frontend source fidelity ledger stale or tampered: ${binding.ledgerPath} (bound ${binding.ledgerSha256}, observed ${actualSha})`,
+            ledger: null,
+        };
+    }
+    let ledger;
+    try {
+        ledger = parseLedgerJson(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-stale",
+            failureReason: `frontend source fidelity ledger is not a valid v1 ledger: ${error instanceof Error ? error.message : String(error)}`,
+            ledger: null,
+        };
+    }
+    if (ledger.inputDigest !== binding.inputDigest) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-stale",
+            failureReason: `frontend source fidelity ledger inputDigest mismatch: bound ${binding.inputDigest}, ledger ${ledger.inputDigest}`,
+            ledger,
+        };
+    }
+    const validation = validateRequirementLedger(ledger);
+    const firstError = (code) => validation.find((error) => error.code === code)?.message ?? null;
+    const invalid = (failureCode, failureReason) => ({ ok: false, failureCode, failureReason, ledger });
+    if (ledger.stats.unresolvedCount > 0 || validation.some((e) => e.code === "SOURCE_FIDELITY_UNRESOLVED")) {
+        return invalid("source-fidelity-unresolved", firstError("SOURCE_FIDELITY_UNRESOLVED") ?? `frontend source fidelity ledger has ${ledger.stats.unresolvedCount} unresolved fragment(s)`);
+    }
+    if (ledger.stats.conflictCount > 0 || validation.some((e) => e.code === "SOURCE_FIDELITY_CONFLICT")) {
+        return invalid("source-fidelity-conflict", firstError("SOURCE_FIDELITY_CONFLICT") ?? `frontend source fidelity ledger has ${ledger.stats.conflictCount} conflict(s)`);
+    }
+    if (ledger.stats.highRiskUncoveredCount > 0 || validation.some((e) => e.code === "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED")) {
+        return invalid("source-fidelity-high-risk-uncovered", firstError("SOURCE_FIDELITY_HIGH_RISK_UNCOVERED") ?? `frontend source fidelity ledger has ${ledger.stats.highRiskUncoveredCount} high-risk uncovered fragment(s)`);
+    }
+    const notCoveredError = validation.find((e) => e.code === "SOURCE_FIDELITY_REQUIREMENT_NOT_COVERED");
+    if (notCoveredError) {
+        return invalid("source-fidelity-requirement-not-covered", notCoveredError.message);
+    }
+    const refInvalidError = validation.find((e) => e.code === "SOURCE_FIDELITY_SOURCE_REF_INVALID" || e.code === "SOURCE_FIDELITY_FRAGMENT_INVALID");
+    if (refInvalidError) {
+        return invalid("source-fidelity-source-ref-invalid", refInvalidError.message);
+    }
+    const ledgerIds = new Set(ledger.canonicalRequirements.map((requirement) => requirement.id));
+    const contractIds = new Set(input.contractRequirements.map((r) => r.id));
+    const uncoveredRequirements = [...ledgerIds].filter((id) => !contractIds.has(id));
+    if (uncoveredRequirements.length > 0) {
+        return invalid("source-fidelity-requirement-not-covered", `frontend contract requirements do not cover ledger canonical requirement ids: ${uncoveredRequirements.join(", ")}`);
+    }
+    const fragmentById = new Map(ledger.fragments.map((fragment) => [fragment.id, fragment]));
+    for (const requirement of input.contractRequirements) {
+        if (!ledgerIds.has(requirement.id))
+            continue;
+        const declared = requirement.sourceFragmentIds ?? [];
+        if (declared.length === 0) {
+            return invalid("source-fidelity-source-ref-invalid", `frontend contract requirement ${requirement.id} lacks sourceFragmentIds for the bound ledger`);
+        }
+        const boundFragments = new Set(ledger.canonicalRequirements.find((r) => r.id === requirement.id)?.sourceFragmentIds ?? []);
+        for (const fragmentId of declared) {
+            if (!fragmentById.has(fragmentId)) {
+                return invalid("source-fidelity-source-ref-invalid", `frontend contract requirement ${requirement.id} references unknown fragment ${fragmentId}`);
+            }
+            if (!boundFragments.has(fragmentId)) {
+                return invalid("source-fidelity-source-ref-invalid", `frontend contract requirement ${requirement.id} declares fabricated fragment reference ${fragmentId} (not bound in ledger)`);
+            }
+        }
+    }
+    return { ok: true, failureCode: null, failureReason: null, ledger };
+}