@sigloch/graph-api-core 2.0.0 → 3.0.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/browser.d.ts

@@ -13,7 +13,7 @@
  */
 export { findRoot } from './find-root.js';
 export type { RootQueryGraph } from './find-root.js';
-export { SE_DESCRIPTOR, projectToOntologyGraph } from './se-descriptor.js';
+export { SE_DESCRIPTOR, createSeDescriptor, projectToOntologyGraph } from './se-descriptor.js';
 export { FormatECodec } from './format-e-codec.js';
 export { isValidTrace, tracePatternsOf } from './types.js';
 export type { GraphNode, GraphEdge, Graph } from './types.js';

package/dist/browser.js

@@ -12,6 +12,6 @@
  * @author andreas@siglochconsulting
  */
 export { findRoot } from './find-root.js';
-export { SE_DESCRIPTOR, projectToOntologyGraph } from './se-descriptor.js';
+export { SE_DESCRIPTOR, createSeDescriptor, projectToOntologyGraph } from './se-descriptor.js';
 export { FormatECodec } from './format-e-codec.js';
 export { isValidTrace, tracePatternsOf } from './types.js';

package/dist/format-e-codec.d.ts

@@ -38,6 +38,21 @@ export declare class FormatECodec {
      *   `localeCompare`, which is locale-dependent.
      */
     private serializeEdges;
+    /**
+     * CR-GC-334: an object attribute has no place in the inline block — `[k:v,k:v]` splits on
+     * commas, and `String({…})` produced the literal `[object Object]`, i.e. the binding was
+     * destroyed on write. Structured values therefore go to `@key {json}` follow-lines
+     * (`structuredAttrLines`), which `parse()` hydrates back into objects.
+     *
+     * EDGES keep the inline block (they must stay single-line, see `serializeEdges`), so an
+     * object on an EDGE is JSON-stringified inline — legible, but it round-trips only while it
+     * contains no comma. No edge in the SE ontology carries a structured attribute today; if one
+     * ever does, the inline block is the thing to replace, not this escape.
+     */
     private serializeAttrs;
+    /** CR-GC-334: object/array attributes as `@key {json}` lines below the node entry. */
+    private structuredAttrLines;
+    /** Inline block for an EDGE — structured values stringified, see `serializeAttrs`. */
+    private serializeEdgeAttrs;
     private edgeTypeToArrow;
 }

package/dist/format-e-codec.js

@@ -7,6 +7,7 @@
  * family (`TYPE-slug`, `Name.TypeAbbr.Counter`, `cand_<hex>`); typing by spelling made
  * every foreign convention fail silently instead of loudly.
  */
+import { hydrateAttrValue } from '@sigloch/contracts/se';
 import { isValidTrace, tracePatternsOf } from './types.js';
 // ---------------------------------------------------------------------------
 // Regex patterns
@@ -73,7 +74,11 @@ export class FormatECodec {
                 if (lastOp && (lastOp.type === 'add_node' || lastOp.type === 'update_node' || lastOp.type === 'strict_add_node')) {
                     if (!lastOp.attributes)
                         lastOp.attributes = {};
-                    lastOp.attributes[attrMatch[1]] = attrMatch[2].trim();
+                    // CR-GC-334: `serialize()` writes objects as `@key {json}`, so `parse()` must read
+                    // them back as objects. Kept as a string, `realRef`/`testRef` fail their schema and
+                    // the element reads as UNBOUND — R-19/R-20 fired on every node authored through this
+                    // path. Same rule as the contracts parser, imported, not re-implemented.
+                    lastOp.attributes[attrMatch[1]] = hydrateAttrValue(attrMatch[2].trim());
                 }
                 else {
                     errors.push(`@attribute line without preceding node: "${line}"`);
@@ -166,6 +171,9 @@ export class FormatECodec {
                     const descr = node.description ? `|${node.description}` : '';
                     const attrs = this.serializeAttrs(node.attributes);
                     lines.push(`+ ${node.uid}${descr}${attrs}`);
+                    // CR-GC-334: realRef/testRef & friends as @key {json} — the inline block above
+                    // cannot carry them, and dropping them here is what made bindings vanish.
+                    lines.push(...this.structuredAttrLines(node.attributes));
                 }
             }
         }
@@ -327,7 +335,7 @@ export class FormatECodec {
         const entries = [];
         const groups = new Map();
         for (const edge of edges) {
-            const attrs = this.serializeAttrs(edge.attributes);
+            const attrs = this.serializeEdgeAttrs(edge.attributes);
             if (attrs) {
                 entries.push({ sourceId: edge.sourceId, edgeType: edge.edgeType, targets: [edge.targetId], attrs });
                 continue;
@@ -352,13 +360,38 @@ export class FormatECodec {
             || cmp(a.attrs, b.attrs));
         return entries.map(e => `+ ${e.sourceId} -${this.edgeTypeToArrow(e.edgeType)}-> ${e.targets.join(', ')}${e.attrs}`);
     }
+    /**
+     * CR-GC-334: an object attribute has no place in the inline block — `[k:v,k:v]` splits on
+     * commas, and `String({…})` produced the literal `[object Object]`, i.e. the binding was
+     * destroyed on write. Structured values therefore go to `@key {json}` follow-lines
+     * (`structuredAttrLines`), which `parse()` hydrates back into objects.
+     *
+     * EDGES keep the inline block (they must stay single-line, see `serializeEdges`), so an
+     * object on an EDGE is JSON-stringified inline — legible, but it round-trips only while it
+     * contains no comma. No edge in the SE ontology carries a structured attribute today; if one
+     * ever does, the inline block is the thing to replace, not this escape.
+     */
     serializeAttrs(attrs) {
-        const entries = Object.entries(attrs).filter(([, v]) => v != null && v !== '');
+        const entries = Object.entries(attrs).filter(([, v]) => v != null && v !== '' && typeof v !== 'object');
         if (entries.length === 0)
             return '';
         const pairs = entries.map(([k, v]) => `${k}:${String(v)}`);
         return ` [${pairs.join(',')}]`;
     }
+    /** CR-GC-334: object/array attributes as `@key {json}` lines below the node entry. */
+    structuredAttrLines(attrs) {
+        return Object.entries(attrs)
+            .filter(([, v]) => v != null && typeof v === 'object')
+            .map(([k, v]) => `@${k} ${JSON.stringify(v)}`);
+    }
+    /** Inline block for an EDGE — structured values stringified, see `serializeAttrs`. */
+    serializeEdgeAttrs(attrs) {
+        const entries = Object.entries(attrs).filter(([, v]) => v != null && v !== '');
+        if (entries.length === 0)
+            return '';
+        const pairs = entries.map(([k, v]) => `${k}:${typeof v === 'object' ? JSON.stringify(v) : String(v)}`);
+        return ` [${pairs.join(',')}]`;
+    }
     edgeTypeToArrow(edgeType) {
         // Use first defined arrow alias
         const desc = this.ontology.edgeTypes[edgeType];

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { MemoryAdapter } from './memory-adapter.js';
 export type { TransportAdapter, TransportConfig } from './transport-adapter.js';
 export { createGraphApi } from './factory.js';
 export type { GraphApiConfig } from './factory.js';
-export { SE_DESCRIPTOR, projectToOntologyGraph } from './se-descriptor.js';
+export { SE_DESCRIPTOR, createSeDescriptor, projectToOntologyGraph } from './se-descriptor.js';
 export { findRoot } from './find-root.js';
 export type { RootQueryGraph } from './find-root.js';
 export { applyEdgeOps, updateEdge, mergeNodes } from './edge-ops.js';

package/dist/index.js

@@ -19,7 +19,7 @@ export { MemoryAdapter } from './memory-adapter.js';
 // Factory
 export { createGraphApi } from './factory.js';
 // SE OntologyDescriptor (derived from @sigloch/contracts/se) [CR-195a]
-export { SE_DESCRIPTOR, projectToOntologyGraph } from './se-descriptor.js';
+export { SE_DESCRIPTOR, createSeDescriptor, projectToOntologyGraph } from './se-descriptor.js';
 // Root-Suche — strukturelle Wurzel (SYS ohne eingehende compose), statt UID-Hardcode
 export { findRoot } from './find-root.js';
 // Edge ops — update-edge (flip/retype) + merge-nodes, shared by GraphService.mutate()

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.d.ts

@@ -9,7 +9,7 @@
  *   - Graph (nodes/edges)        ⟷  OntologyGraph (elements/traces)
  *   - RuleViolation (ruleId/…)   ⟷  contracts RuleViolation (rule_id/…)
  */
-import { type OntologyGraph } from '@sigloch/contracts/se';
+import { type MetricPolicy, type OntologyGraph } from '@sigloch/contracts/se';
 import type { Graph, OntologyDescriptor } from './types.js';
 /**
  * Project an ontology-agnostic Graph (nodes/edges) onto the SE OntologyGraph
@@ -21,4 +21,13 @@ export declare function projectToOntologyGraph(graph: Graph): OntologyGraph;
  * Canonical SE OntologyDescriptor (ontology + V3 rules + MT metrics), version-pinned
  * to contracts/se ONTOLOGY_VERSION. Plug into GraphService / FormatECodec.
  */
+export declare function createSeDescriptor(policy: MetricPolicy): OntologyDescriptor;
+/**
+ * The descriptor for a host without its own metric policy — judged with contracts'
+ * `DEFAULT_METRIC_POLICY`, which is a named, grep-able value, not a hidden fallback.
+ *
+ * A host that holds a configuration builds its own with `createSeDescriptor(policy)`
+ * and must then use only that one; two descriptors in one process would be the two
+ * thresholds CR-SM-233 removed.
+ */
 export declare const SE_DESCRIPTOR: OntologyDescriptor;

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, DEFAULT_METRIC_POLICY, } 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,28 +45,77 @@ 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) => ({
-    id: def.id,
-    name: def.name,
-    severity: def.severity,
-    evaluate: (graph) => def.evaluate(projectToOntologyGraph(graph)).map((v) => ({
-        ruleId: v.rule_id,
-        ruleName: def.name,
-        severity: v.severity,
-        message: v.message,
-        elementId: v.element_id,
-        // CR-GC-203 item 1: carry the fix-context through instead of discarding it,
-        // so rules_get_violations hands the agent candidates + a hint, not just a message.
-        fixHint: v.fix_hint,
-        context: v.context,
-    })),
-}));
+const GATING_PREFIXES = ['R-', 'RD-', 'MT-'];
+const SE_RULE_DEFS = [
+    ...V3_RULES,
+    ...UC_RULES,
+    ...FC_RULES,
+    ...SC_RULES,
+    ...CR_RULES,
+    ...AO_RULES,
+    ...FM_RULES,
+    ...VIEW_RULES,
+    ...AF_RULES,
+];
+function adapt(def, evaluate) {
+    // (evaluate is already policy-bound by the caller — see seRules below)
+    return {
+        id: def.id,
+        name: def.name,
+        severity: def.severity,
+        gating: GATING_PREFIXES.some((p) => def.id.startsWith(p)),
+        evaluate: (graph) => evaluate(projectToOntologyGraph(graph)).map((v) => ({
+            ruleId: v.rule_id,
+            ruleName: def.name,
+            severity: v.severity,
+            message: v.message,
+            elementId: v.element_id,
+            // CR-GC-203 item 1: carry the fix-context through instead of discarding it,
+            // so rules_get_violations hands the agent candidates + a hint, not just a message.
+            fixHint: v.fix_hint,
+            context: v.context,
+        })),
+    };
+}
+/**
+ * Every rule bound to the judging policy (CR-SM-233, extended by CR-SM-236).
+ *
+ * A threshold is input, not a constant, and it therefore cannot live in a descriptor
+ * constant: a host that configures the value (graphcode's `graphcode.config.jsonc`,
+ * CR-GC-329) would otherwise judge against its own number while the gate judged against
+ * a second one baked in here.
+ *
+ * CR-SM-236 removed the former split into a policy-free `SE_RULES` constant plus a
+ * policy-bound metric list. MT-01/MT-02 stopped being the only rules with a threshold
+ * (CR-01, FM-03 and R-04 joined them), so a policy-free rule constant had become a
+ * second, silently-judging path — exactly what CR-SM-233 set out to remove.
+ *
+ * A `null` threshold means measure, don't judge: the rule stays registered and simply
+ * reports nothing.
+ */
+function seRules(policy) {
+    return [...SE_RULE_DEFS, ...MT_RULES].map((def) => adapt(def, (g) => def.evaluate(g, policy)));
+}
 // `label` is the node-table identifier (kuzu table name) — must be a valid
 // identifier, so it's the ElementType key (SYS, UC, …), not the human
 // ELEMENT_DESCRIPTIONS text which would break DDL.
@@ -80,13 +129,24 @@ const edgeTypes = Object.fromEntries(TraceType.options.map((tt) => {
  * Canonical SE OntologyDescriptor (ontology + V3 rules + MT metrics), version-pinned
  * to contracts/se ONTOLOGY_VERSION. Plug into GraphService / FormatECodec.
  */
-export const SE_DESCRIPTOR = {
-    name: 'se',
-    version: ONTOLOGY_VERSION,
-    nodeTypes,
-    edgeTypes,
-    // CR-GC-247: TRACE_PATTERNS is the trace-legality SSOT; validPairs above is kept
-    // only for Format-E arrow/menu enumeration. isValidTrace validates against these.
-    patterns: TRACE_PATTERNS,
-    rules: SE_RULES,
-};
+export function createSeDescriptor(policy) {
+    return {
+        name: 'se',
+        version: ONTOLOGY_VERSION,
+        nodeTypes,
+        edgeTypes,
+        // CR-GC-247: TRACE_PATTERNS is the trace-legality SSOT; validPairs above is kept
+        // only for Format-E arrow/menu enumeration. isValidTrace validates against these.
+        patterns: TRACE_PATTERNS,
+        rules: seRules(policy),
+    };
+}
+/**
+ * The descriptor for a host without its own metric policy — judged with contracts'
+ * `DEFAULT_METRIC_POLICY`, which is a named, grep-able value, not a hidden fallback.
+ *
+ * A host that holds a configuration builds its own with `createSeDescriptor(policy)`
+ * and must then use only that one; two descriptors in one process would be the two
+ * thresholds CR-SM-233 removed.
+ */
+export const SE_DESCRIPTOR = createSeDescriptor(DEFAULT_METRIC_POLICY);

package/dist/types.d.ts

@@ -113,7 +113,7 @@ export interface FormatEOperation {
     description?: string;
     /**
      * BOK-CR-026: `unknown`, not `string` — object-valued bindings (`realRef`,
-     * `testRef`) must survive a Format-E mutation as objects, or the element reads as
+     * `testRefs`) must survive a Format-E mutation as objects/arrays, or the element reads as
      * unbound. GraphService already handled them as unknown internally; this is the
      * public type catching up (a plain `@key value` line still yields a string).
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/graph-api-core",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,11 +21,11 @@
     "prepublishOnly": "npm run build && npm run test"
   },
   "dependencies": {
-    "@sigloch/contracts": "^2.0.0",
+    "@sigloch/contracts": "^4.0.0",
     "zod": "^4.3.6"
   },
   "license": "MIT",
-  "description": "Framework-agnostic graph engine core — ontology-typed nodes/traces, rule evaluation, views",
+  "description": "Framework-agnostic graph engine core \u2014 ontology-typed nodes/traces, rule evaluation, views",
   "author": "sigloch-consulting",
   "repository": {
     "type": "git",