@sigloch/contracts 0.7.0

package/dist/se/rules.js

@@ -0,0 +1,854 @@
+/**
+ * SE Rules — declarative config table + evaluation (version: see RULES_VERSION in ./index.ts).
+ * R-07/R-09/R-13 removed (CR-180), RD-01..03 added.
+ * @sigloch/contracts/se — single source of truth for SE validation rules.
+ */
+import { z } from 'zod/v4';
+import { ElementType, TraceType, TestRefSchema, CodeRefSchema, SchemaRefSchema } from './ontology.js';
+import { isValidTrace } from './meta-model.js';
+export const RuleSeverity = z.enum(['error', 'warning', 'info']);
+/** Candidate target for resolving a violation (e.g. a REQ to satisfy, a TEST to link). */
+export const ViolationCandidate = z.object({
+    id: z.string(),
+    type: ElementType,
+    name: z.string(),
+});
+/** Graph context attached to a violation — enables prompt generation without extra DB queries. */
+export const ViolationContext = z.object({
+    element_type: ElementType.optional(),
+    element_name: z.string().optional(),
+    candidate_targets: z.array(ViolationCandidate).optional(),
+    existing_traces: z.array(z.object({
+        target: z.string(),
+        type: TraceType,
+    })).optional(),
+    parent_module: z.string().optional(),
+    current_description: z.string().optional(),
+});
+export const RuleViolation = z.object({
+    rule_id: z.string(),
+    severity: RuleSeverity,
+    element_id: z.string(),
+    message: z.string(),
+    fix_hint: z.string().optional(),
+    context: ViolationContext.optional(),
+});
+// ---------------------------------------------------------------------------
+// Graph lookup helpers (shared across rules)
+// ---------------------------------------------------------------------------
+/** Find the MOD a FUNC/SCHEMA is allocated to. */
+function findParentModule(graph, elementId) {
+    const trace = graph.traces.find(t => t.source === elementId && t.type === 'allocate');
+    return trace?.target;
+}
+/** Get all outgoing traces of a given type from an element. */
+function outgoingTraces(graph, elementId, traceType) {
+    return graph.traces.filter(t => t.source === elementId && (!traceType || t.type === traceType));
+}
+/** Tokenize id/name/description into a lowercase token set (drops tokens < 3 chars). */
+function overlapTokens(...parts) {
+    return new Set(parts
+        .filter((p) => !!p)
+        .join(' ')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(t => t.length >= 3));
+}
+/**
+ * Map elements to ViolationCandidate format. When `ref` is given, rank candidates
+ * by id/name/description token overlap with `ref` (descending) so the most relevant
+ * target is first — e.g. REQ-bootstrap → TEST-bootstrap (CR-GC-203 item 3). Ranking
+ * is a hint, not an auto-link; semantic confirmation stays with the caller.
+ */
+function toCandidates(elements, ref) {
+    if (!ref)
+        return elements.map(e => ({ id: e.id, type: e.type, name: e.name }));
+    const refTokens = overlapTokens(ref.id, ref.name, ref.description);
+    const score = (e) => {
+        let n = 0;
+        for (const tok of overlapTokens(e.id, e.name, e.description))
+            if (refTokens.has(tok))
+                n++;
+        return n;
+    };
+    return [...elements]
+        .sort((a, b) => score(b) - score(a))
+        .map(e => ({ id: e.id, type: e.type, name: e.name }));
+}
+// ---------------------------------------------------------------------------
+// R-01: Every REQ must have at least one verify trace
+// ---------------------------------------------------------------------------
+function reqMustHaveVerification(graph) {
+    const reqs = graph.elements.filter(e => e.type === 'REQ');
+    const tests = graph.elements.filter(e => e.type === 'TEST');
+    return reqs
+        .filter(req => !graph.traces.some(t => t.target === req.id && t.type === 'verify'))
+        .map(req => ({
+        rule_id: 'R-01',
+        severity: 'error',
+        element_id: req.id,
+        message: `${req.id} has no verification trace`,
+        fix_hint: 'Link a TEST element via verify trace',
+        context: {
+            element_type: req.type,
+            element_name: req.name,
+            candidate_targets: toCandidates(tests, req),
+            current_description: req.description,
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// R-02: Every FUNC must satisfy at least one REQ
+// ---------------------------------------------------------------------------
+function funcMustSatisfyReq(graph) {
+    const funcs = graph.elements.filter(e => e.type === 'FUNC');
+    const allReqs = graph.elements.filter(e => e.type === 'REQ');
+    return funcs
+        .filter(fn => !graph.traces.some(t => t.source === fn.id && t.type === 'satisfy'))
+        .map(fn => {
+        const modId = findParentModule(graph, fn.id);
+        // Candidate REQs: same module's other FUNCs satisfy these, or constraints referencing this func
+        const siblingReqs = modId
+            ? graph.traces
+                .filter(t => t.type === 'allocate' && t.target === modId && t.source !== fn.id)
+                .flatMap(t => graph.traces.filter(st => st.source === t.source && st.type === 'satisfy'))
+                .map(st => graph.elements.find(e => e.id === st.target))
+                .filter((e) => !!e)
+            : [];
+        // Also include constraints whose description mentions this func's name
+        const namePattern = fn.name.toLowerCase();
+        const matchingConstraints = allReqs.filter(r => r.kinds?.includes('non-functional') && r.description.toLowerCase().includes(namePattern));
+        const candidates = [...new Map([...siblingReqs, ...matchingConstraints, ...allReqs].map(e => [e.id, e])).values()];
+        return {
+            rule_id: 'R-02',
+            severity: 'warning',
+            element_id: fn.id,
+            message: `${fn.id} does not satisfy any requirement`,
+            fix_hint: 'Link to a REQ via satisfy trace',
+            context: {
+                element_type: fn.type,
+                element_name: fn.name,
+                parent_module: modId,
+                existing_traces: outgoingTraces(graph, fn.id).map(t => ({ target: t.target, type: t.type })),
+                candidate_targets: toCandidates(candidates, fn),
+            },
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// R-03: ASIL isolation
+// ---------------------------------------------------------------------------
+function asilIsolation(graph) {
+    const violations = [];
+    const modules = graph.elements.filter(e => e.type === 'MOD');
+    for (const mod of modules) {
+        const allocated = graph.traces
+            .filter(t => t.target === mod.id && t.type === 'allocate')
+            .map(t => graph.elements.find(e => e.id === t.source))
+            .filter((e) => !!e);
+        const hasD = allocated.some(e => e.asil === 'D');
+        const hasQM = allocated.some(e => e.asil === 'QM');
+        if (hasD && hasQM) {
+            const dFuncs = allocated.filter(e => e.asil === 'D');
+            const qmFuncs = allocated.filter(e => e.asil === 'QM');
+            violations.push({
+                rule_id: 'R-03',
+                severity: 'error',
+                element_id: mod.id,
+                message: `${mod.id} mixes ASIL-D and ASIL-QM functions`,
+                fix_hint: 'Separate ASIL-D functions into isolated module',
+                context: {
+                    element_type: mod.type,
+                    element_name: mod.name,
+                    candidate_targets: toCandidates([...dFuncs, ...qmFuncs]),
+                },
+            });
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// R-04: Max module size
+// ---------------------------------------------------------------------------
+function maxModuleSize(graph) {
+    const modules = graph.elements.filter(e => e.type === 'MOD');
+    const violations = [];
+    for (const mod of modules) {
+        const allocatedIds = graph.traces.filter(t => t.target === mod.id && t.type === 'allocate').map(t => t.source);
+        const allocated = allocatedIds.map(id => graph.elements.find(e => e.id === id)).filter((e) => !!e);
+        const funcCount = allocated.length;
+        if (funcCount <= 8)
+            continue;
+        // Count crossing flows: io paths from FUNCs in this module to FUNCs in other modules
+        const funcIds = new Set(allocatedIds);
+        const crossings = graph.traces.filter(t => {
+            if (t.type !== 'io')
+                return false;
+            const srcIn = funcIds.has(t.source);
+            const tgtIn = funcIds.has(t.target);
+            return (srcIn && !tgtIn) || (!srcIn && tgtIn);
+        }).length;
+        if (funcCount > 12 && crossings === 0) {
+            violations.push({
+                rule_id: 'R-04',
+                severity: 'info',
+                element_id: mod.id,
+                message: `${mod.id} has ${funcCount} functions but 0 crossings (cohesive, just large)`,
+                fix_hint: 'Consider splitting if complexity grows',
+                context: { element_type: mod.type, element_name: mod.name, candidate_targets: toCandidates(allocated) },
+            });
+        }
+        else if (funcCount > 12 && crossings > 0) {
+            violations.push({
+                rule_id: 'R-04',
+                severity: 'warning',
+                element_id: mod.id,
+                message: `${mod.id} has ${funcCount} functions and ${crossings} crossing flows (split recommended)`,
+                fix_hint: 'Split module into smaller units to reduce coupling',
+                context: { element_type: mod.type, element_name: mod.name, candidate_targets: toCandidates(allocated) },
+            });
+        }
+        else if (funcCount > 8 && crossings > 2) {
+            violations.push({
+                rule_id: 'R-04',
+                severity: 'warning',
+                element_id: mod.id,
+                message: `${mod.id} has ${funcCount} functions and ${crossings} crossing flows (high coupling)`,
+                fix_hint: 'Reduce crossing flows or split module',
+                context: { element_type: mod.type, element_name: mod.name, candidate_targets: toCandidates(allocated) },
+            });
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// R-05: Every TEST must verify at least one REQ
+// ---------------------------------------------------------------------------
+function testMustVerifyReq(graph) {
+    const tests = graph.elements.filter(e => e.type === 'TEST');
+    const allReqs = graph.elements.filter(e => e.type === 'REQ');
+    return tests
+        .filter(test => !graph.traces.some(t => t.source === test.id && t.type === 'verify'))
+        .map(test => ({
+        rule_id: 'R-05',
+        severity: 'warning',
+        element_id: test.id,
+        message: `${test.id} does not verify any requirement`,
+        fix_hint: 'Link to a REQ via verify trace',
+        context: {
+            element_type: test.type,
+            element_name: test.name,
+            candidate_targets: toCandidates(allReqs),
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// R-06: DELETED — replaced by type-specific rules R-14..R-17 (CR-117)
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// R-07: DELETED — absorbed into BQ-07 (CR-180)
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// R-08: Bidirectional trace consistency
+// ---------------------------------------------------------------------------
+function traceConsistency(graph) {
+    return graph.traces
+        .filter(t => t.category !== 'audit')
+        .filter(t => {
+        const sourceExists = graph.elements.some(e => e.id === t.source);
+        const targetExists = graph.elements.some(e => e.id === t.target);
+        return !sourceExists || !targetExists;
+    })
+        .map(t => ({
+        rule_id: 'R-08',
+        severity: 'error',
+        element_id: t.source,
+        message: `Trace ${t.source}→${t.target} references non-existent element`,
+    }));
+}
+// ---------------------------------------------------------------------------
+// R-09: DELETED — superseded by RD-01..RD-03 (CR-180)
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// R-10: FLOW completeness — a FLOW needs BOTH a producer (incoming io) and a
+// consumer (outgoing io). Direction-blind coverage let source-less flows pass
+// as dead ports (CR-201, graph-view-edit CR-GVE-159/-163): FLOW-graph-model had
+// two outgoing io edges but no producer and stayed green. Same rule-id (same
+// concern, stricter check — no parallel path); up to two warnings per FLOW.
+// ---------------------------------------------------------------------------
+function flowCompleteness(graph) {
+    const flows = graph.elements.filter(e => e.type === 'FLOW');
+    // Producers/consumers of a FLOW are FUNCs or ACTORs (io endpoints on the
+    // upstream/downstream side); UC may consume too. Offer both as candidates.
+    const sources = graph.elements.filter(e => e.type === 'FUNC' || e.type === 'ACTOR');
+    const io = graph.traces.filter(t => t.type === 'io');
+    const violations = [];
+    for (const f of flows) {
+        const ctx = { element_type: f.type, element_name: f.name, candidate_targets: toCandidates(sources) };
+        if (!io.some(t => t.target === f.id)) {
+            violations.push({
+                rule_id: 'R-10',
+                severity: 'warning',
+                element_id: f.id,
+                message: `${f.id} has no producer (incoming io)`,
+                fix_hint: 'Link a FUNC or ACTOR as the source via io trace',
+                context: ctx,
+            });
+        }
+        if (!io.some(t => t.source === f.id)) {
+            violations.push({
+                rule_id: 'R-10',
+                severity: 'warning',
+                element_id: f.id,
+                message: `${f.id} has no consumer (outgoing io)`,
+                fix_hint: 'Link a FUNC, ACTOR, or UC as the target via io trace',
+                context: ctx,
+            });
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// R-11: REMOVED — superseded by SC-02 (identical check, better severity).
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// R-12: Circular dependency detection
+// ---------------------------------------------------------------------------
+function noDirectCircular(graph) {
+    const violations = [];
+    for (const t of graph.traces) {
+        if (graph.traces.some(other => other.source === t.target && other.target === t.source && other.type === t.type)) {
+            violations.push({
+                rule_id: 'R-12',
+                severity: 'warning',
+                element_id: t.source,
+                message: `Circular ${t.type} between ${t.source} and ${t.target}`,
+            });
+        }
+    }
+    const seen = new Set();
+    return violations.filter(v => {
+        const key = v.message;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+// ---------------------------------------------------------------------------
+// R-13: DELETED — superseded by RD-01 (CR-180)
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// RD-01: Unresolved requirement (leaf REQ without satisfy)
+// ---------------------------------------------------------------------------
+function unresolvedRequirement(graph) {
+    const reqs = graph.elements.filter(e => e.type === 'REQ');
+    // Leaf REQs: no compose→REQ children
+    const leafReqs = reqs.filter(req => !graph.traces.some(t => t.source === req.id && t.type === 'compose' &&
+        graph.elements.some(e => e.id === t.target && e.type === 'REQ')));
+    return leafReqs
+        .filter(req => !graph.traces.some(t => t.target === req.id && t.type === 'satisfy'))
+        .map(req => ({
+        rule_id: 'RD-01',
+        severity: 'warning',
+        element_id: req.id,
+        message: `${req.id} is a leaf REQ with no satisfy trace (unresolved)`,
+        fix_hint: 'Add satisfy trace from FUNC, FCHAIN, MOD, or SYS',
+        context: {
+            element_type: req.type,
+            element_name: req.name,
+            // CR-GC-203 item 3: rank the potential satisfiers by overlap with this REQ.
+            candidate_targets: toCandidates(graph.elements.filter(e => e.type === 'FUNC' || e.type === 'FCHAIN' || e.type === 'MOD' || e.type === 'SYS'), req),
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// RD-02: Decomposition consistency (parent REQ should not have FUNC satisfy)
+// ---------------------------------------------------------------------------
+function decompositionConsistency(graph) {
+    const reqs = graph.elements.filter(e => e.type === 'REQ');
+    const parentReqs = reqs.filter(req => graph.traces.some(t => t.source === req.id && t.type === 'compose' &&
+        graph.elements.some(e => e.id === t.target && e.type === 'REQ')));
+    return parentReqs
+        .filter(req => graph.traces.some(t => t.target === req.id && t.type === 'satisfy' &&
+        graph.elements.some(e => e.id === t.source && e.type === 'FUNC')))
+        .map(req => ({
+        rule_id: 'RD-02',
+        severity: 'warning',
+        element_id: req.id,
+        message: `${req.id} has sub-REQs but also a direct FUNC satisfy (should only have origin traces)`,
+        fix_hint: 'Remove FUNC→satisfy from parent REQ; only children should be directly satisfied',
+        context: { element_type: req.type, element_name: req.name },
+    }));
+}
+// ---------------------------------------------------------------------------
+// RD-03: No premature decomposition (all children same satisfy target)
+// ---------------------------------------------------------------------------
+function noPrematureDecomposition(graph) {
+    const reqs = graph.elements.filter(e => e.type === 'REQ');
+    const parentReqs = reqs.filter(req => graph.traces.some(t => t.source === req.id && t.type === 'compose' &&
+        graph.elements.some(e => e.id === t.target && e.type === 'REQ')));
+    return parentReqs
+        .filter(parent => {
+        const childIds = graph.traces
+            .filter(t => t.source === parent.id && t.type === 'compose' &&
+            graph.elements.some(e => e.id === t.target && e.type === 'REQ'))
+            .map(t => t.target);
+        if (childIds.length < 2)
+            return false;
+        const satisfyTargets = childIds.map(cid => graph.traces.filter(t => t.source !== cid && t.target === cid && t.type === 'satisfy').map(t => t.source));
+        // All children satisfied by the same single source
+        const allSame = satisfyTargets.every(targets => targets.length === 1 && targets[0] === satisfyTargets[0]?.[0]);
+        return allSame && satisfyTargets[0]?.length === 1;
+    })
+        .map(req => ({
+        rule_id: 'RD-03',
+        severity: 'info',
+        element_id: req.id,
+        message: `${req.id} children all have the same satisfy target — decomposition may be unnecessary`,
+        fix_hint: 'Consider merging sub-REQs back into parent if they share the same verifiable level',
+        context: { element_type: req.type, element_name: req.name },
+    }));
+}
+// ---------------------------------------------------------------------------
+// R-14: UC must have at least 1 compose trace (→ FCHAIN or REQ) (CR-117)
+// ---------------------------------------------------------------------------
+function ucMustHaveCompose(graph) {
+    const ucs = graph.elements.filter(e => e.type === 'UC');
+    return ucs
+        .filter(uc => !graph.traces.some(t => t.source === uc.id && t.type === 'compose'))
+        .map(uc => ({
+        rule_id: 'R-14',
+        severity: 'warning',
+        element_id: uc.id,
+        message: `${uc.id} has no compose traces (no scenarios or requirements)`,
+        fix_hint: 'Add FCHAIN or REQ via compose trace',
+        context: {
+            element_type: uc.type,
+            element_name: uc.name,
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// R-15: FCHAIN must have at least 1 compose trace (→ FUNC) (CR-117)
+// ---------------------------------------------------------------------------
+function fchainMustHaveCompose(graph) {
+    const fchains = graph.elements.filter(e => e.type === 'FCHAIN');
+    const funcs = graph.elements.filter(e => e.type === 'FUNC');
+    return fchains
+        .filter(fc => !graph.traces.some(t => t.source === fc.id && t.type === 'compose'))
+        .map(fc => ({
+        rule_id: 'R-15',
+        severity: 'warning',
+        element_id: fc.id,
+        message: `${fc.id} has no compose traces (no functions in chain)`,
+        fix_hint: 'Add FUNC elements via compose trace',
+        context: {
+            element_type: fc.type,
+            element_name: fc.name,
+            candidate_targets: toCandidates(funcs),
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// R-16: ACTOR must have at least 1 io trace (CR-117)
+// ---------------------------------------------------------------------------
+function actorMustHaveTrace(graph) {
+    const actors = graph.elements.filter(e => e.type === 'ACTOR');
+    return actors
+        .filter(a => !graph.traces.some(t => (t.source === a.id || t.target === a.id) && t.type === 'io'))
+        .map(a => ({
+        rule_id: 'R-16',
+        severity: 'warning',
+        element_id: a.id,
+        message: `${a.id} has no io traces (disconnected actor)`,
+        fix_hint: 'Link to a UC or FLOW via io trace',
+        context: {
+            element_type: a.type,
+            element_name: a.name,
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// R-17: SYS must have at least 1 compose trace (CR-117)
+// ---------------------------------------------------------------------------
+function sysMustHaveCompose(graph) {
+    const systems = graph.elements.filter(e => e.type === 'SYS');
+    return systems
+        .filter(sys => !graph.traces.some(t => t.source === sys.id && t.type === 'compose'))
+        .map(sys => ({
+        rule_id: 'R-17',
+        severity: 'warning',
+        element_id: sys.id,
+        message: `${sys.id} has no compose traces (empty system)`,
+        fix_hint: 'Add UC, REQ, or MOD via compose trace',
+        context: {
+            element_type: sys.type,
+            element_name: sys.name,
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// MS-01: Milestone without scope — no CRs assigned via CR→MS [relation]
+// (CR-207: scope = CRs pointing to this MS, not compose children)
+// ---------------------------------------------------------------------------
+function msEmptyScope(graph) {
+    const milestones = graph.elements.filter(e => e.type === 'MS');
+    return milestones
+        .filter(ms => {
+        // Check: any CR → MS [relation] trace?
+        const hasCr = graph.traces.some(t => t.type === 'relation' && t.target === ms.id &&
+            graph.elements.some(e => e.id === t.source && e.type === 'CR'));
+        // Fallback: legacy compose traces still count
+        const hasCompose = graph.traces.some(t => t.source === ms.id && t.type === 'compose');
+        return !hasCr && !hasCompose;
+    })
+        .map(ms => ({
+        rule_id: 'MS-01',
+        severity: 'warning',
+        element_id: ms.id,
+        message: `${ms.id} has no CRs assigned (empty milestone scope)`,
+        fix_hint: 'Add CR→MS [relation] traces to assign change requests to this milestone',
+        context: { element_type: ms.type, element_name: ms.name },
+    }));
+}
+// ---------------------------------------------------------------------------
+// MS-02: Milestone depends-on dangling target
+// ---------------------------------------------------------------------------
+function msDanglingDependency(graph) {
+    const msIds = new Set(graph.elements.filter(e => e.type === 'MS').map(e => e.id));
+    return graph.traces
+        .filter(t => t.type === 'relation' && t.label === 'depends-on' && msIds.has(t.source))
+        .filter(t => !msIds.has(t.target))
+        .map(t => ({
+        rule_id: 'MS-02',
+        severity: 'error',
+        element_id: t.source,
+        message: `${t.source} depends on non-existent milestone ${t.target}`,
+        fix_hint: 'Fix the depends-on relation target to reference an existing MS element',
+    }));
+}
+// ---------------------------------------------------------------------------
+// R-18: Valid trace pattern (CR-GC-205 Item 1) — every modeling trace's
+// source/target element-type pair must be a valid TRACE_PATTERN. Lifts pair-
+// legality from a consumer-local validator (graphcode codec.validate) into the
+// one engine, so EVERY consumer running evaluateRules() enforces it and it shows
+// up in readiness. Referential integrity (dangling endpoint) stays R-08's job —
+// here we only judge pairs whose endpoints both resolve. Audit traces are exempt.
+// ---------------------------------------------------------------------------
+function validTracePattern(graph) {
+    const typeById = new Map(graph.elements.map(e => [e.id, e.type]));
+    return graph.traces
+        .filter(t => t.category !== 'audit')
+        .filter(t => {
+        const src = typeById.get(t.source);
+        const tgt = typeById.get(t.target);
+        if (!src || !tgt)
+            return false; // dangling endpoint → R-08, not R-18
+        return !isValidTrace({ source: src, target: tgt, type: t.type, label: t.label });
+    })
+        .map(t => ({
+        rule_id: 'R-18',
+        severity: 'error',
+        element_id: t.source,
+        message: `Invalid trace ${t.source} -${t.type}-> ${t.target}: ` +
+            `${typeById.get(t.source)} → ${typeById.get(t.target)} is not a valid ${t.type} pattern`,
+        fix_hint: 'Use a trace type whose TRACE_PATTERNS allows this source/target element-type pair',
+    }));
+}
+// ---------------------------------------------------------------------------
+// R-19: Runnable TEST binding (CR-GC-205 Item 4) — a TEST that is not explicitly
+// concept-only (attributes.concept === true) should carry a valid testRef runnable
+// binding so the deduced selective test set is trustworthy. WARNING (a completeness
+// signal like R-05, not a hard gate): a freshly-spec'd TEST is legitimately concept-
+// level until implemented, and the no-phantom-file guarantee is enforced separately
+// by the consumer's export materialization (every testRef.file is scaffolded). File
+// EXISTENCE is out of scope here (rules are pure, no I/O); this guards presence/shape
+// only and surfaces an unbound runnable TEST in rules_evaluate / readiness.
+// ---------------------------------------------------------------------------
+function testMustHaveRunnableBinding(graph) {
+    return graph.elements
+        .filter(e => e.type === 'TEST')
+        .filter(e => e.attributes?.concept !== true) // concept-only TESTs are exempt
+        .filter(e => !TestRefSchema.safeParse(e.attributes?.testRef).success)
+        .map(test => ({
+        rule_id: 'R-19',
+        severity: 'warning',
+        element_id: test.id,
+        message: `${test.id} is a runnable TEST without a valid testRef binding`,
+        fix_hint: 'Add attributes.testRef {file, case?, tool, level?}, or set attributes.concept:true if it has no run artifact yet',
+        context: { element_type: test.type, element_name: test.name },
+    }));
+}
+// ---------------------------------------------------------------------------
+// R-20: FUNC code binding (CR-GC-205 Item 5, extended by CR-210) — a FUNC that
+// is not explicitly concept-only (attributes.concept === true) or externally
+// realized (attributes.external === true) counts as BOUND when it EITHER carries
+// a valid codeRef {file, symbol} OR is a blackbox parent whose compose→FUNC
+// children are ALL (recursively) bound — the parent is realized by its children
+// (e.g. FUNC-gesture-capture, gve CR-GVE-150). A partially-bound parent fires
+// R-20 naming the still-unbound leaves in the fix_hint, so drift on a child is
+// enforced at the parent too (before CR-210 the parent was blanket-exempt and
+// structurally unprovable). WARNING (a completeness signal like R-19, not a hard
+// gate). Symbol RESOLUTION stays out of scope (rules are pure, no I/O — that is
+// RC-01's job); this guards presence/shape only. Cycle-safe.
+// ---------------------------------------------------------------------------
+function funcMustHaveCodeBinding(graph) {
+    const funcById = new Map(graph.elements.filter(e => e.type === 'FUNC').map(e => [e.id, e]));
+    const composeFuncChildren = (id) => graph.traces
+        .filter(t => t.source === id && t.type === 'compose' && funcById.has(t.target))
+        .map(t => t.target);
+    const hasCodeRef = (el) => CodeRefSchema.safeParse(el.attributes?.codeRef).success;
+    const isExempt = (el) => el.attributes?.concept === true || el.attributes?.external === true;
+    // A FUNC is bound iff it is exempt, has a codeRef, or is a parent whose
+    // compose→FUNC children are all bound (recursive, cycle-safe).
+    const isBound = (id, stack) => {
+        const el = funcById.get(id);
+        if (!el)
+            return false;
+        if (isExempt(el) || hasCodeRef(el))
+            return true;
+        const children = composeFuncChildren(id);
+        if (children.length === 0)
+            return false;
+        if (stack.has(id))
+            return true; // cycle: assume in-progress node holds → terminate
+        stack.add(id);
+        const bound = children.every(c => isBound(c, stack));
+        stack.delete(id);
+        return bound;
+    };
+    // Unbound compose-descendants that actually need realizing (unbound leaves,
+    // recursing through unbound parents) — the actionable fix targets for a parent.
+    const collectUnboundLeaves = (id, acc, stack) => {
+        if (stack.has(id))
+            return;
+        stack.add(id);
+        for (const c of composeFuncChildren(id)) {
+            const el = funcById.get(c);
+            if (isExempt(el) || hasCodeRef(el))
+                continue;
+            const grandchildren = composeFuncChildren(c);
+            if (grandchildren.length === 0)
+                acc.add(c);
+            else
+                collectUnboundLeaves(c, acc, stack);
+        }
+        stack.delete(id);
+    };
+    const violations = [];
+    for (const fn of funcById.values()) {
+        if (isExempt(fn))
+            continue;
+        if (isBound(fn.id, new Set()))
+            continue;
+        const children = composeFuncChildren(fn.id);
+        if (children.length > 0) {
+            // Parent with at least one still-unbound child.
+            const leaves = new Set();
+            collectUnboundLeaves(fn.id, leaves, new Set());
+            const leafList = [...leaves];
+            violations.push({
+                rule_id: 'R-20',
+                severity: 'warning',
+                element_id: fn.id,
+                message: `${fn.id} is not fully realized — unbound compose ${leafList.length === 1 ? 'child' : 'children'}: ${leafList.join(', ')}`,
+                fix_hint: `Realize the leaves ${leafList.join(', ')} (graph_realize) — the parent inherits their binding`,
+                context: { element_type: fn.type, element_name: fn.name },
+            });
+        }
+        else {
+            violations.push({
+                rule_id: 'R-20',
+                severity: 'warning',
+                element_id: fn.id,
+                message: `${fn.id} is a FUNC without a valid codeRef binding`,
+                fix_hint: 'Add attributes.codeRef {file, symbol, lang?}, or set attributes.concept:true (spec-only) / attributes.external:true (realized in another package)',
+                context: { element_type: fn.type, element_name: fn.name },
+            });
+        }
+    }
+    return violations;
+}
+/** All rules — see RULES_VERSION in ./index.ts (R-06/R-07/R-09/R-11/R-13/R-24/R-25 removed, R-14..R-23/R-26/RD-01..03/MS-01..02 added) */
+// ---------------------------------------------------------------------------
+// R-21: Every FUNC↔FUNC connection must be covered by an integration test.
+//       A connection is FUNC ─io→ FLOW ─io→ FUNC. It is covered iff both
+//       endpoints share an FCHAIN that owns a verifying integration test
+//       (TEST ─verify→ REQ ←satisfy─ FCHAIN). Unit tests (FUNC→REQ) and UC
+//       acceptance tests do NOT cover the interface between two functions —
+//       CR-GC-240 folded "integration" onto the UC level, leaving FUNC↔FUNC
+//       wiring unverified; this rule closes that gap edge-granularly.
+// ---------------------------------------------------------------------------
+function fchainMustHaveIntegrationTest(graph) {
+    const typeOf = new Map(graph.elements.map(e => [e.id, e.type]));
+    const isFunc = (id) => typeOf.get(id) === 'FUNC';
+    const io = graph.traces.filter(t => t.type === 'io');
+    // FUNC↔FUNC connections via the FLOW hop: (producer FUNC) → FLOW → (consumer FUNC).
+    const connections = [];
+    for (const e of graph.elements) {
+        if (e.type !== 'FLOW')
+            continue;
+        const producers = io.filter(t => t.target === e.id && isFunc(t.source)).map(t => t.source);
+        const consumers = io.filter(t => t.source === e.id && isFunc(t.target)).map(t => t.target);
+        for (const p of producers)
+            for (const c of consumers)
+                if (p !== c)
+                    connections.push([p, c]);
+    }
+    if (connections.length === 0)
+        return [];
+    // FUNC → set of FCHAINs composing it.
+    const chainsOfFunc = new Map();
+    for (const t of graph.traces) {
+        if (t.type === 'compose' && typeOf.get(t.source) === 'FCHAIN' && isFunc(t.target)) {
+            (chainsOfFunc.get(t.target) ?? chainsOfFunc.set(t.target, new Set()).get(t.target)).add(t.source);
+        }
+    }
+    // FCHAINs whose satisfy-REQ is verified by a TEST = chains with an integration test.
+    const verifiedReqs = new Set(graph.traces.filter(t => t.type === 'verify').map(t => t.target));
+    const testedChains = new Set();
+    for (const t of graph.traces) {
+        if (t.type === 'satisfy' && typeOf.get(t.source) === 'FCHAIN' && verifiedReqs.has(t.target)) {
+            testedChains.add(t.source);
+        }
+    }
+    const violations = [];
+    const seen = new Set();
+    for (const [p, c] of connections) {
+        const shared = [...(chainsOfFunc.get(p) ?? [])].filter(ch => chainsOfFunc.get(c)?.has(ch));
+        if (shared.some(ch => testedChains.has(ch)))
+            continue;
+        const anchor = shared[0] ?? p;
+        const key = `${anchor}|${p}>${c}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const anchorEl = graph.elements.find(e => e.id === anchor);
+        violations.push({
+            rule_id: 'R-21',
+            severity: 'warning',
+            element_id: anchor,
+            message: shared.length > 0
+                ? `${anchor} has no integration test covering connection ${p} → ${c}`
+                : `connection ${p} → ${c} is in no FCHAIN with an integration test`,
+            fix_hint: 'Group both FUNCs in an FCHAIN and verify an FCHAIN-satisfied REQ with an integration TEST',
+            context: { element_type: anchorEl?.type, element_name: anchorEl?.name },
+        });
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// R-22: FUNC must be allocated to a MOD (CR-202) — every function lives on a
+// module. An unallocated FUNC is a model bug: structure views that nest via
+// allocate silently drop it (gve renders it under SYS as a workaround). Pattern
+// analogous to R-02/funcMustSatisfyReq; allocation (FUNC→MOD) and satisfaction
+// (FUNC→REQ) are orthogonal, so this is its own rule. Cross-module composite
+// allocation (parent on MOD-A, child on MOD-B) is coupling info, NOT an error —
+// deliberately not checked (CR-GVE-173/174).
+// ---------------------------------------------------------------------------
+function funcMustBeAllocated(graph) {
+    const funcs = graph.elements.filter(e => e.type === 'FUNC');
+    const mods = graph.elements.filter(e => e.type === 'MOD');
+    const modIds = new Set(mods.map(m => m.id));
+    return funcs
+        .filter(fn => !graph.traces.some(t => t.source === fn.id && t.type === 'allocate' && modIds.has(t.target)))
+        .map(fn => ({
+        rule_id: 'R-22',
+        severity: 'warning',
+        element_id: fn.id,
+        message: `${fn.id} is not allocated to any module`,
+        fix_hint: 'Link to a MOD via allocate trace',
+        context: {
+            element_type: fn.type,
+            element_name: fn.name,
+            candidate_targets: toCandidates(mods, fn),
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// R-23: MOD must have an allocated FUNC (CR-208) — the MOD-side complement of
+// R-22. R-04 only checks the upper bound (>8 FUNCs); nothing checks the lower.
+// An empty module is a legal intermediate state in the model (the view no longer
+// suppresses it, CR-GVE-188) — so the quality signal belongs in the rules, not
+// the view. Mirrors the empty-container rules R-14/R-16/R-17. Not merged with
+// R-22: one rule per element perspective (like R-01 REQ-side beside R-02/R-05).
+// ---------------------------------------------------------------------------
+function modMustHaveAllocatedFunc(graph) {
+    const mods = graph.elements.filter(e => e.type === 'MOD');
+    const funcs = graph.elements.filter(e => e.type === 'FUNC');
+    const modIds = new Set(mods.map(m => m.id));
+    const unallocatedFuncs = funcs.filter(fn => !graph.traces.some(t => t.source === fn.id && t.type === 'allocate' && modIds.has(t.target)));
+    return mods
+        .filter(mod => !graph.traces.some(t => t.target === mod.id && t.type === 'allocate' &&
+        graph.elements.some(e => e.id === t.source && e.type === 'FUNC')))
+        .map(mod => ({
+        rule_id: 'R-23',
+        severity: 'warning',
+        element_id: mod.id,
+        message: `${mod.id} has no allocated FUNC`,
+        fix_hint: 'Allocate a FUNC via allocate trace or remove the module',
+        context: {
+            element_type: mod.type,
+            element_name: mod.name,
+            candidate_targets: toCandidates(unallocatedFuncs, mod),
+        },
+    }));
+}
+// R-24/R-25: DELETED (CR-228) — they guarded `REQ ─allocate→ MOD`, a pattern the
+// meta-model no longer sanctions. A MOD does not own a REQ; physical NFRs use
+// MOD→satisfy→REQ, behavioral NFRs FCHAIN→satisfy→REQ. R-18 now flags any residual
+// REQ→MOD allocate edge as an invalid trace pattern.
+// ---------------------------------------------------------------------------
+// R-26: SCHEMA schemaRef presence (CR-211) — a SCHEMA that is not explicitly
+// concept-only or external should carry a valid schemaRef {file, symbol} so its
+// Zod definition is machine-resolvable (RC-03 then checks it resolves, RC-04 that
+// it is parsed at the interface). WARNING, not error: the 9 currently-unbound
+// SCHEMAs on the reference model must not turn readiness red before any binding
+// exists — the presence signal mirrors R-20 (codeRef) / R-19 (testRef). Symbol
+// RESOLUTION is out of scope here (pure, no I/O — that is RC-03's job).
+// ---------------------------------------------------------------------------
+function schemaMustHaveSchemaRef(graph) {
+    return graph.elements
+        .filter(e => e.type === 'SCHEMA')
+        .filter(e => e.attributes?.concept !== true && e.attributes?.external !== true)
+        .filter(e => !SchemaRefSchema.safeParse(e.attributes?.schemaRef).success)
+        .map(sc => ({
+        rule_id: 'R-26',
+        severity: 'warning',
+        element_id: sc.id,
+        message: `${sc.id} is a SCHEMA without a valid schemaRef binding`,
+        fix_hint: 'Add attributes.schemaRef {file, symbol, lang?}, or set attributes.concept:true (spec-only) / attributes.external:true (foreign-API contract)',
+        context: { element_type: sc.type, element_name: sc.name },
+    }));
+}
+export const V3_RULES = [
+    { id: 'R-01', name: 'REQ must have verification', severity: 'error', evaluate: reqMustHaveVerification },
+    { id: 'R-02', name: 'FUNC must satisfy REQ', severity: 'warning', evaluate: funcMustSatisfyReq },
+    { id: 'R-03', name: 'ASIL isolation', severity: 'error', evaluate: asilIsolation },
+    { id: 'R-04', name: 'Max module size', severity: 'warning', evaluate: maxModuleSize },
+    { id: 'R-05', name: 'TEST must verify REQ', severity: 'warning', evaluate: testMustVerifyReq },
+    { id: 'R-14', name: 'UC must have compose', severity: 'warning', evaluate: ucMustHaveCompose },
+    { id: 'R-15', name: 'FCHAIN must have compose', severity: 'warning', evaluate: fchainMustHaveCompose },
+    { id: 'R-16', name: 'ACTOR must have io', severity: 'warning', evaluate: actorMustHaveTrace },
+    { id: 'R-17', name: 'SYS must have compose', severity: 'warning', evaluate: sysMustHaveCompose },
+    { id: 'R-08', name: 'Trace consistency', severity: 'error', evaluate: traceConsistency },
+    { id: 'R-10', name: 'FLOW completeness', severity: 'warning', evaluate: flowCompleteness },
+    { id: 'R-12', name: 'No circular dependencies', severity: 'warning', evaluate: noDirectCircular },
+    { id: 'R-18', name: 'Valid trace pattern', severity: 'error', evaluate: validTracePattern },
+    { id: 'R-19', name: 'Runnable TEST binding', severity: 'warning', evaluate: testMustHaveRunnableBinding },
+    { id: 'R-20', name: 'FUNC code binding', severity: 'warning', evaluate: funcMustHaveCodeBinding },
+    { id: 'R-21', name: 'FUNC↔FUNC connection needs integration test', severity: 'warning', evaluate: fchainMustHaveIntegrationTest },
+    { id: 'R-22', name: 'FUNC must be allocated to MOD', severity: 'warning', evaluate: funcMustBeAllocated },
+    { id: 'R-23', name: 'MOD must have allocated FUNC', severity: 'warning', evaluate: modMustHaveAllocatedFunc },
+    { id: 'R-26', name: 'SCHEMA must have schemaRef', severity: 'warning', evaluate: schemaMustHaveSchemaRef },
+    { id: 'RD-01', name: 'Unresolved requirement', severity: 'warning', evaluate: unresolvedRequirement },
+    { id: 'RD-02', name: 'Decomposition consistency', severity: 'warning', evaluate: decompositionConsistency },
+    { id: 'RD-03', name: 'No premature decomposition', severity: 'info', evaluate: noPrematureDecomposition },
+    { id: 'MS-01', name: 'Milestone empty scope', severity: 'warning', evaluate: msEmptyScope },
+    { id: 'MS-02', name: 'Milestone dangling dependency', severity: 'error', evaluate: msDanglingDependency },
+];
+/** Run all rules against a graph */
+export function evaluateRules(graph) {
+    return V3_RULES.flatMap(rule => rule.evaluate(graph));
+}