@sigloch/graph-api-core 1.0.0 → 2.1.0

package/dist/audit.d.ts

@@ -18,6 +18,28 @@ export interface AuditEntry {
     result: 'applied' | 'rejected' | 'partial';
     violations?: RuleViolation[];
     graphVersion: number;
+    /**
+     * The POSITIVE half of the finding (CR-GC-314): rule IDs that were evaluated for this
+     * mutation and returned nothing.
+     *
+     * `violations` records only what went wrong, so an accepted mutation leaves an empty
+     * field — and "rule R-18 checked this edit and passed it" is not recoverable from
+     * "no violation". A later learning mechanism can learn from the first statement and
+     * nothing at all from the second; that asymmetry is the whole reason this field exists.
+     *
+     * Rule IDs only, never rule text (REQ-A04). Optional and purely additive: an entry
+     * written before this field means "not recorded", NOT "passed nothing" — a consumer
+     * must not read absence as an empty pass set (REQ-A05). Old records are deliberately
+     * not back-filled: reconstructing them would evaluate against a rule version that did
+     * not hold at mutation time, which is itself a provenance violation.
+     */
+    rulesPassed?: string[];
+    /**
+     * Version of the rule set this mutation was evaluated against (REQ-A02) — read from
+     * the loaded package, never from config, so a rule-set change is visible in the trail
+     * at exactly the records it affected.
+     */
+    rulesetVersion?: string;
 }
 export interface AuditLog {
     record(entry: AuditEntry): Promise<void>;

package/dist/rule-engine.d.ts

@@ -12,11 +12,30 @@ export interface RuleViolation {
     fixHint?: string;
     /** Carried from the contracts rule: candidate_targets / existing_traces context for fix automation. */
     context?: unknown;
+    /**
+     * Stamped by the engine from the rule that produced this violation (CR-GC-312).
+     * `false` = visible but not gate-relevant. Absent means gating, so every existing
+     * consumer keeps its behaviour without reading the field.
+     */
+    gating?: boolean;
 }
 export interface Rule {
     id: string;
     name: string;
     severity: 'error' | 'warning' | 'info';
+    /**
+     * May an `error` from this rule BLOCK a write? (CR-GC-312) Default `true`.
+     *
+     * Severity says how bad a finding is; this says whether the gate acts on it. The
+     * two are separate because a rule family can be correct and worth surfacing long
+     * before a repo has paid off its backlog — switching one on would otherwise freeze
+     * every write on debt the writer did not create. Set `false` to surface a rule in
+     * `evaluate`/readiness while it is still being worked down, then promote it.
+     *
+     * NOT a severity downgrade: the violation keeps `severity: 'error'` and reads as one
+     * everywhere it is displayed.
+     */
+    gating?: boolean;
     evaluate: (graph: Graph) => RuleViolation[];
 }
 export interface RuleEngine {

package/dist/rule-engine.js

@@ -10,7 +10,12 @@ export class DefaultRuleEngine {
     evaluate(graph) {
         const violations = [];
         for (const rule of this.rules) {
-            violations.push(...rule.evaluate(graph));
+            // CR-GC-312: stamp `gating` from the rule so a consumer's gate can filter
+            // without a second lookup into the catalog. Only stamped when the rule opts
+            // OUT — an absent field means gating, the pre-existing behaviour.
+            const stamp = rule.gating === false ? { gating: false } : undefined;
+            for (const v of rule.evaluate(graph))
+                violations.push(stamp ? { ...v, ...stamp } : v);
         }
         return violations;
     }

package/dist/se-descriptor.js

@@ -9,7 +9,7 @@
  *   - Graph (nodes/edges)        ⟷  OntologyGraph (elements/traces)
  *   - RuleViolation (ruleId/…)   ⟷  contracts RuleViolation (rule_id/…)
  */
-import { ElementType, TraceType, TRACE_PATTERNS, V3_RULES, MT_RULES, ONTOLOGY_VERSION, } from '@sigloch/contracts/se';
+import { ElementType, TraceType, TRACE_PATTERNS, V3_RULES, MT_RULES, UC_RULES, FC_RULES, SC_RULES, CR_RULES, AO_RULES, FM_RULES, VIEW_RULES, AF_RULES, ONTOLOGY_VERSION, } from '@sigloch/contracts/se';
 /**
  * Project an ontology-agnostic Graph (nodes/edges) onto the SE OntologyGraph
  * (elements/traces) that contracts/se rules evaluate against. Type-specific
@@ -45,16 +45,44 @@ export function projectToOntologyGraph(graph) {
 /**
  * The contracts/se rule catalog, adapted to graph-api-core's Rule shape.
  *
- * V3_RULES + MT_RULES (CR-SM-222): the architecture metrics lived in contracts since
- * K2 but ran only in aimpro's `evaluateAllRules`, so the governed repos (graphcode,
- * graph-view-edit) never saw them. Same adapter, no fork — they inherit by
- * consuming this descriptor. MT severities are warning/info, so they stay advisory
- * in graphcode's gate.
+ * CR-GC-312: this used to be `[...V3_RULES, ...MT_RULES]` — two of the twelve families
+ * contracts exports. Everything else (UC, FC, SC, CR, AO, FM, VIEW, AF) was written,
+ * versioned and shipped, and then evaluated by nobody: consumers register exactly
+ * `SE_DESCRIPTOR.rules`, so ten families were dead weight in the package. Measured on
+ * graphcode's SSOT the day this was found: 2 violations reported, 276 findable — among
+ * them `CR-R02` ("done but no commitRef", 91×), precisely the graph-vs-reality check
+ * the repo believed it had. A use case with no operational chain went unflagged for
+ * weeks because `UC-03`/`FC-02` existed and never ran.
+ *
+ * Two families stay out on purpose:
+ *   - BQ/ND are the CODING profile (`getRuleDefsForProfile('coding')`), not SE.
+ *   - RC (conformance) needs `CodeFacts` from a repo checkout, which this package has
+ *     no access to; graphcode evaluates those itself in `src/conformance.ts`.
+ *
+ * `gating` (see `Rule`) is what makes the switch-on safe. V3/MT keep their gate power;
+ * the newly wired families are advisory until a repo has worked its backlog down —
+ * otherwise the 114 pre-existing errors in graphcode's own graph would block every
+ * write on debt the writer did not create. Promotion is a per-family decision, not a
+ * side effect of being registered.
  */
-const SE_RULES = [...V3_RULES, ...MT_RULES].map((def) => ({
+const GATING_PREFIXES = ['R-', 'RD-', 'MT-'];
+const SE_RULE_DEFS = [
+    ...V3_RULES,
+    ...MT_RULES,
+    ...UC_RULES,
+    ...FC_RULES,
+    ...SC_RULES,
+    ...CR_RULES,
+    ...AO_RULES,
+    ...FM_RULES,
+    ...VIEW_RULES,
+    ...AF_RULES,
+];
+const SE_RULES = SE_RULE_DEFS.map((def) => ({
     id: def.id,
     name: def.name,
     severity: def.severity,
+    gating: GATING_PREFIXES.some((p) => def.id.startsWith(p)),
     evaluate: (graph) => def.evaluate(projectToOntologyGraph(graph)).map((v) => ({
         ruleId: v.rule_id,
         ruleName: def.name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/graph-api-core",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,7 +21,7 @@
     "prepublishOnly": "npm run build && npm run test"
   },
   "dependencies": {
-    "@sigloch/contracts": "^1.0.0",
+    "@sigloch/contracts": "^3.2.0",
     "zod": "^4.3.6"
   },
   "license": "MIT",