@sigloch/graph-api-core 2.1.0 → 3.1.0

package/dist/audit.d.ts

@@ -40,6 +40,41 @@ export interface AuditEntry {
      * at exactly the records it affected.
      */
     rulesetVersion?: string;
+    /**
+     * PROVENANCE (CR-GC-354) — the four fields that make a record answer the base question
+     * of an audit trail: WHO, with WHICH PROMPT, reached WHICH RESULT. The result half was
+     * always there; these are the other two.
+     *
+     * All four are DERIVED at the recording site, never self-declared by the consumer.
+     * `consumerId` is the counter-example that motivated this: it IS a self-declared field
+     * and 40% of the records carry its anonymous default. A prompt a model writes about
+     * itself is a paraphrase — it already contains the interpretation a later consumer
+     * would want to predict — so it is worthless as provenance.
+     *
+     * Session this record was written in — groups the records of ONE conversation.
+     * Assigned by the recording host, not accepted from the caller.
+     */
+    sessionId?: string;
+    /**
+     * The LLM that emitted the commands (e.g. the executor's configured model). The
+     * dimension rule calibration breaks down by ("R-01 dominated rejections: Haiku 26/29,
+     * Opus 17/18, devstral 10/23") and the one a client-side transcript cannot supply for
+     * a local or third-party model, because no transcript exists there.
+     */
+    model?: string;
+    /**
+     * The triggering prompt VERBATIM, truncated by the recording host's policy (the
+     * contract states that it is truncated, the host states where).
+     *
+     * Same absence asymmetry as `rulesPassed`: a missing field means NOT RECORDED, never
+     * "empty prompt". A consumer must not read absence as "no prompt was given".
+     */
+    intent?: string;
+    /**
+     * `true` when `intent` was truncated. Present only in that case — no silent cut, and
+     * no `false` noise on the overwhelming majority of records that fit.
+     */
+    intentTruncated?: boolean;
 }
 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/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, UC_RULES, FC_RULES, SC_RULES, CR_RULES, AO_RULES, FM_RULES, VIEW_RULES, AF_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
@@ -68,7 +68,6 @@ export function projectToOntologyGraph(graph) {
 const GATING_PREFIXES = ['R-', 'RD-', 'MT-'];
 const SE_RULE_DEFS = [
     ...V3_RULES,
-    ...MT_RULES,
     ...UC_RULES,
     ...FC_RULES,
     ...SC_RULES,
@@ -78,23 +77,45 @@ const SE_RULE_DEFS = [
     ...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,
-        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,
-    })),
-}));
+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.
@@ -108,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.1.0",
+  "version": "3.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": "^3.2.0",
+    "@sigloch/contracts": "^4.1.0",
     "zod": "^4.3.6"
   },
   "license": "MIT",