@sigloch/graph-api-core 5.3.0 → 5.4.0

package/dist/browser.d.ts

@@ -13,6 +13,8 @@
  */
 export { findRoot } from './find-root.js';
 export type { RootQueryGraph } from './find-root.js';
+export { impactSlice } from './impact-slice.js';
+export type { ImpactSlice, ImpactSliceNode, ImpactRole } from './impact-slice.js';
 export { SE_DESCRIPTOR, createSeDescriptor, projectToOntologyGraph, fromOntologyGraph } from './se-descriptor.js';
 export { FormatECodec } from './format-e-codec.js';
 export { isValidTrace, tracePatternsOf } from './types.js';

package/dist/browser.js

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

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

@@ -18,8 +18,20 @@ export declare class FormatECodec {
     parse(input: string, options?: {
         resolveType?: (uid: string) => string | undefined;
     }): FormatEDiff;
-    /** Serialize a Graph to Format E text. */
-    serialize(graph: Graph): string;
+    /**
+     * Serialize a Graph to Format E text.
+     *
+     * CR-GC-373: `options.omitProvenance` is the **agent view** — provenance attributes
+     * (`created_at`, `updated_at`, `ranAt` inside `testRefs` entries, `weight` at its
+     * default 1) are dropped; everything that is work instruction (`codeRef`, `realRef`,
+     * `testRefs` file/tool/level, `kinds`, `constraint`, `zodDefinition`, `status`) stays.
+     * NOT a second codec: the default stays complete — round-trip is the contract, the
+     * agent view the exception. Measured on the CR-GC-114 job slice: 18% of the text was
+     * pure timestamps.
+     */
+    serialize(graph: Graph, options?: {
+        omitProvenance?: boolean;
+    }): string;
     private parseNodeLine;
     private parseEdgeLine;
     private parseMerge;

package/dist/format-e-codec.js

@@ -149,8 +149,19 @@ export class FormatECodec {
         }
         return { operations, errors };
     }
-    /** Serialize a Graph to Format E text. */
-    serialize(graph) {
+    /**
+     * Serialize a Graph to Format E text.
+     *
+     * CR-GC-373: `options.omitProvenance` is the **agent view** — provenance attributes
+     * (`created_at`, `updated_at`, `ranAt` inside `testRefs` entries, `weight` at its
+     * default 1) are dropped; everything that is work instruction (`codeRef`, `realRef`,
+     * `testRefs` file/tool/level, `kinds`, `constraint`, `zodDefinition`, `status`) stays.
+     * NOT a second codec: the default stays complete — round-trip is the contract, the
+     * agent view the exception. Measured on the CR-GC-114 job slice: 18% of the text was
+     * pure timestamps.
+     */
+    serialize(graph, options = {}) {
+        const omit = options.omitProvenance === true;
         const lines = [];
         if (graph.nodes.length > 0) {
             lines.push('## Nodes');
@@ -169,18 +180,21 @@ export class FormatECodec {
                 lines.push(`### ${type}`);
                 for (const node of byType.get(type) ?? []) {
                     const descr = node.description ? `|${node.description}` : '';
-                    const attrs = this.serializeAttrs(node.attributes);
-                    lines.push(`+ ${node.uid}${descr}${attrs}`);
+                    const nodeAttrs = omit ? stripNodeProvenance(node.attributes) : node.attributes;
+                    lines.push(`+ ${node.uid}${descr}${this.serializeAttrs(nodeAttrs)}`);
                     // 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));
+                    lines.push(...this.structuredAttrLines(nodeAttrs));
                 }
             }
         }
         if (graph.edges.length > 0) {
             lines.push('');
             lines.push('## Edges');
-            lines.push(...this.serializeEdges(graph.edges));
+            const edges = omit
+                ? graph.edges.map(e => ({ ...e, attributes: stripEdgeProvenance(e.attributes) }))
+                : graph.edges;
+            lines.push(...this.serializeEdges(edges));
         }
         return lines.join('\n');
     }
@@ -408,3 +422,27 @@ export class FormatECodec {
         return desc?.arrows[0] ?? edgeType.toLowerCase();
     }
 }
+// ---------------------------------------------------------------------------
+// CR-GC-373: agent-view provenance filters (pure — never mutate the input graph)
+// ---------------------------------------------------------------------------
+const PROVENANCE_KEYS = new Set(['created_at', 'updated_at']);
+/** Drop created_at/updated_at; inside testRefs entries additionally ranAt. */
+function stripNodeProvenance(attrs) {
+    const out = {};
+    for (const [k, v] of Object.entries(attrs)) {
+        if (PROVENANCE_KEYS.has(k))
+            continue;
+        if (k === 'testRefs' && Array.isArray(v)) {
+            out[k] = v.map(entry => entry != null && typeof entry === 'object' && !Array.isArray(entry)
+                ? Object.fromEntries(Object.entries(entry).filter(([ek]) => ek !== 'ranAt'))
+                : entry);
+            continue;
+        }
+        out[k] = v;
+    }
+    return out;
+}
+/** Drop created_at/updated_at and the default weight 1 (a non-default weight stays). */
+function stripEdgeProvenance(attrs) {
+    return Object.fromEntries(Object.entries(attrs).filter(([k, v]) => !PROVENANCE_KEYS.has(k) && !(k === 'weight' && Number(v) === 1)));
+}

package/dist/impact-slice.d.ts

@@ -0,0 +1,57 @@
+/**
+ * impactSlice — THE directed impact traversal (CR-GC-365, Weg b).
+ *
+ * One definition of "blast radius", two readers: graphcode's `graph_impact`
+ * (MCP surface, agent) and graph-view-edit's ImpactMap (viewer). Before this,
+ * the MCP side ran a directed incoming Kuzu query while the viewer ran its own
+ * undirected frontier-BFS in the browser — what the human saw was a superset
+ * in direction and a subset in depth of what the agent got, computed from a
+ * different source.
+ *
+ * Semantics (node-equal to the former Kuzu query `(m)-[*1..depth]->(root)`,
+ * direction 'in' — conformance-tested against KuzuAdapter.getSubgraph):
+ *
+ *  - Traversal is DIRECTED INCOMING: dependents, i.e. nodes with a directed
+ *    path INTO a seed of length <= depth (who breaks if the seed changes).
+ *    `distance` is the shortest such path length (0 = seed).
+ *
+ *  - Roles per SPIKE-GC-minimal-whitebox §8 (`seed | whitebox | blackbox`):
+ *      seed      distance 0 — the changeset,
+ *      whitebox  distance 1..depth — full node (description, attributes),
+ *      blackbox  distance depth+1 — the frontier ONE step beyond the request:
+ *                identity only (uid/type/name), description and attributes
+ *                stripped. The cut is materialized in the artifact, not merely
+ *                meant in a renderer; the ring is also the honest
+ *                "+"-affordance: a bigger slice (same function, depth+1) opens
+ *                exactly these nodes.
+ *
+ *  - Edges only when BOTH ends lie in the slice (§8 — no edges into nothing).
+ *
+ * Pure function over a loaded Graph — no store handle, browser-safe (exported
+ * from `./browser.js` too). Seeds not present in the graph are dropped; no
+ * present seed yields an empty slice, never a full dump.
+ *
+ * @author andreas@siglochconsulting
+ */
+import type { Graph, GraphEdge, GraphNode } from './types.js';
+export type ImpactRole = 'seed' | 'whitebox' | 'blackbox';
+/** A slice node: the graph node plus its role and BFS distance from the changeset. */
+export type ImpactSliceNode = GraphNode & {
+    role: ImpactRole;
+    distance: number;
+};
+export interface ImpactSlice {
+    /** The seeds actually present in the graph (order of first mention, deduped). */
+    seeds: string[];
+    /** The requested traversal depth (whitebox horizon; blackbox ring sits at depth+1). */
+    depth: number;
+    /** Slice nodes in the graph's node order — blackbox nodes carry identity only. */
+    nodes: ImpactSliceNode[];
+    /** Induced edges: kept iff both endpoints are in the slice. */
+    edges: GraphEdge[];
+}
+/**
+ * Compute the impact slice of `seedIds` over a loaded graph: directed incoming
+ * BFS to `depth` (whitebox) plus the materialized blackbox ring at depth+1.
+ */
+export declare function impactSlice(graph: Graph, seedIds: readonly string[], depth: number): ImpactSlice;

package/dist/impact-slice.js

@@ -0,0 +1,49 @@
+/**
+ * Compute the impact slice of `seedIds` over a loaded graph: directed incoming
+ * BFS to `depth` (whitebox) plus the materialized blackbox ring at depth+1.
+ */
+export function impactSlice(graph, seedIds, depth) {
+    const present = new Set(graph.nodes.map((n) => n.uid));
+    const seeds = [...new Set(seedIds)].filter((id) => present.has(id));
+    // Reverse adjacency: an edge source depends on its target, so traversal
+    // walks target -> source (incoming). Dangling edge ends are ignored.
+    const dependents = new Map();
+    for (const e of graph.edges) {
+        if (!present.has(e.sourceId) || !present.has(e.targetId))
+            continue;
+        const list = dependents.get(e.targetId);
+        if (list)
+            list.push(e.sourceId);
+        else
+            dependents.set(e.targetId, [e.sourceId]);
+    }
+    // BFS out to depth+1: shortest incoming-path distance per reached node.
+    const distance = new Map(seeds.map((s) => [s, 0]));
+    let frontier = seeds;
+    for (let d = 1; d <= depth + 1 && frontier.length > 0; d++) {
+        const next = [];
+        for (const uid of frontier) {
+            for (const dep of dependents.get(uid) ?? []) {
+                if (!distance.has(dep)) {
+                    distance.set(dep, d);
+                    next.push(dep);
+                }
+            }
+        }
+        frontier = next;
+    }
+    const roleOf = (d) => (d === 0 ? 'seed' : d <= depth ? 'whitebox' : 'blackbox');
+    const nodes = [];
+    for (const n of graph.nodes) {
+        const d = distance.get(n.uid);
+        if (d === undefined)
+            continue;
+        const role = roleOf(d);
+        nodes.push(role === 'blackbox'
+            ? { ...n, description: undefined, attributes: {}, role, distance: d }
+            : { ...n, role, distance: d });
+    }
+    const inSlice = new Set(nodes.map((n) => n.uid));
+    const edges = graph.edges.filter((e) => inSlice.has(e.sourceId) && inSlice.has(e.targetId));
+    return { seeds, depth, nodes, edges };
+}

package/dist/index.d.ts

@@ -25,5 +25,7 @@ export type { GraphApiConfig } from './factory.js';
 export { SE_DESCRIPTOR, createSeDescriptor, projectToOntologyGraph, fromOntologyGraph } from './se-descriptor.js';
 export { findRoot } from './find-root.js';
 export type { RootQueryGraph } from './find-root.js';
+export { impactSlice } from './impact-slice.js';
+export type { ImpactSlice, ImpactSliceNode, ImpactRole } from './impact-slice.js';
 export { applyEdgeOps, updateEdge, mergeNodes } from './edge-ops.js';
 export type { EdgeIdentity, UpdateEdgeSet, UpdateEdgeResult, MergeNodesResult, EdgeOp, } from './edge-ops.js';

package/dist/index.js

@@ -22,6 +22,9 @@ export { createGraphApi } from './factory.js';
 export { SE_DESCRIPTOR, createSeDescriptor, projectToOntologyGraph, fromOntologyGraph } from './se-descriptor.js';
 // Root-Suche — strukturelle Wurzel (SYS ohne eingehende compose), statt UID-Hardcode
 export { findRoot } from './find-root.js';
+// The shared directed impact traversal (CR-GC-365 b) — one definition for
+// graphcode's graph_impact and graph-view-edit's ImpactMap.
+export { impactSlice } from './impact-slice.js';
 // Edge ops — update-edge (flip/retype) + merge-nodes, shared by GraphService.mutate()
 // and the graphcode Apply-Gate (CR-198)
 export { applyEdgeOps, updateEdge, mergeNodes } from './edge-ops.js';

package/dist/rule-engine.d.ts

@@ -1,6 +1,7 @@
 /**
  * Pluggable rule engine for graph validation.
  */
+import type { MetricPolicy } from '@sigloch/contracts/se';
 import type { Graph } from './types.js';
 export interface RuleViolation {
     ruleId: string;
@@ -36,17 +37,31 @@ export interface Rule {
      * everywhere it is displayed.
      */
     gating?: boolean;
-    evaluate: (graph: Graph) => RuleViolation[];
+    /**
+     * `policy` (CR-GC-402) overrides the threshold set this rule was BOUND with at
+     * descriptor construction, for this call only. Omitted = judge with the bound one,
+     * the pre-existing behaviour; a rule with no threshold ignores the argument.
+     */
+    evaluate: (graph: Graph, policy?: MetricPolicy) => RuleViolation[];
 }
 export interface RuleEngine {
     readonly version: string;
     register(rules: Rule[]): void;
-    evaluate(graph: Graph): RuleViolation[];
+    evaluate(graph: Graph, policy?: MetricPolicy): RuleViolation[];
 }
 export declare class DefaultRuleEngine implements RuleEngine {
     readonly version: string;
     private rules;
     constructor(version?: string);
     register(rules: Rule[]): void;
-    evaluate(graph: Graph): RuleViolation[];
+    /**
+     * CR-GC-402: `policy` is passed THROUGH to every rule instead of each rule judging
+     * with whatever policy the descriptor was built with. A consumer that registers the
+     * published `SE_DESCRIPTOR.rules` (which are bound to `DEFAULT_METRIC_POLICY`) but
+     * holds its own `graphcode.config.jsonc` could otherwise not judge with its own
+     * thresholds — the gve dashboard reported MT-01 on a repo whose config had switched
+     * it off, and disagreed with the host over the same graph. Omitting the argument
+     * keeps the bound policy, so no existing caller changes behaviour.
+     */
+    evaluate(graph: Graph, policy?: MetricPolicy): RuleViolation[];
 }

package/dist/rule-engine.js

@@ -7,14 +7,23 @@ export class DefaultRuleEngine {
     register(rules) {
         this.rules.push(...rules);
     }
-    evaluate(graph) {
+    /**
+     * CR-GC-402: `policy` is passed THROUGH to every rule instead of each rule judging
+     * with whatever policy the descriptor was built with. A consumer that registers the
+     * published `SE_DESCRIPTOR.rules` (which are bound to `DEFAULT_METRIC_POLICY`) but
+     * holds its own `graphcode.config.jsonc` could otherwise not judge with its own
+     * thresholds — the gve dashboard reported MT-01 on a repo whose config had switched
+     * it off, and disagreed with the host over the same graph. Omitting the argument
+     * keeps the bound policy, so no existing caller changes behaviour.
+     */
+    evaluate(graph, policy) {
         const violations = [];
         for (const rule of this.rules) {
             // 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))
+            for (const v of rule.evaluate(graph, policy))
                 violations.push(stamp ? { ...v, ...stamp } : v);
         }
         return violations;

package/dist/se-descriptor.d.ts

@@ -14,7 +14,14 @@ import type { Graph, OntologyDescriptor } from './types.js';
 /**
  * Project an ontology-agnostic Graph (nodes/edges) onto the SE OntologyGraph
  * (elements/traces) that contracts/se rules evaluate against. Type-specific
- * attributes (asil/method/kinds/status) are lifted out of `attributes`.
+ * attributes (method/kinds/status) are lifted out of `attributes`.
+ *
+ * CR-SM-294 hat `asil` aus der Ontologie entfernt (0 von 305 MOD trugen es, R-03 war sein
+ * einziger Leser). Die Spalte stand hier weiter und hob einen Schluessel heraus, den keine
+ * Regel mehr liest — gefunden erst vom Release-Zug, weil `npm test` gegen ein `dist/` von
+ * VOR der Streichung lief und nur ein frisches `tsc` darueber bricht. Ein Graph, der das
+ * Feld noch traegt, behaelt es im freien `attributes`-Sack; es ist nur keine typisierte
+ * Spalte mehr.
  */
 export declare function projectToOntologyGraph(graph: Graph): OntologyGraph;
 /**

package/dist/se-descriptor.js

@@ -13,7 +13,14 @@ import { ElementType, TraceType, TRACE_PATTERNS, V3_RULES, MT_RULES, UC_RULES, F
 /**
  * Project an ontology-agnostic Graph (nodes/edges) onto the SE OntologyGraph
  * (elements/traces) that contracts/se rules evaluate against. Type-specific
- * attributes (asil/method/kinds/status) are lifted out of `attributes`.
+ * attributes (method/kinds/status) are lifted out of `attributes`.
+ *
+ * CR-SM-294 hat `asil` aus der Ontologie entfernt (0 von 305 MOD trugen es, R-03 war sein
+ * einziger Leser). Die Spalte stand hier weiter und hob einen Schluessel heraus, den keine
+ * Regel mehr liest — gefunden erst vom Release-Zug, weil `npm test` gegen ein `dist/` von
+ * VOR der Streichung lief und nur ein frisches `tsc` darueber bricht. Ein Graph, der das
+ * Feld noch traegt, behaelt es im freien `attributes`-Sack; es ist nur keine typisierte
+ * Spalte mehr.
  */
 export function projectToOntologyGraph(graph) {
     const elements = graph.nodes.map((n) => ({
@@ -24,7 +31,6 @@ export function projectToOntologyGraph(graph) {
         status: n.attributes?.status ?? 'draft',
         created_at: n.createdAt ?? '',
         updated_at: n.updatedAt,
-        asil: n.attributes?.asil,
         method: n.attributes?.method,
         kinds: n.attributes?.kinds,
         attributes: n.attributes,
@@ -140,14 +146,17 @@ const SE_RULE_DEFS = [
     ...VIEW_RULES,
     ...AF_RULES,
 ];
-function adapt(def, evaluate) {
-    // (evaluate is already policy-bound by the caller — see seRules below)
+function adapt(def, evaluate, boundPolicy) {
     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) => ({
+        // CR-GC-402: the CALLER's policy wins for this evaluation, the descriptor's bound
+        // one is the fallback. Without this the threshold was frozen at construction, so a
+        // consumer of the published `SE_DESCRIPTOR` judged with `DEFAULT_METRIC_POLICY` no
+        // matter what its own config said (the MT-01 split between host and dashboard).
+        evaluate: (graph, policy) => evaluate(projectToOntologyGraph(graph), policy ?? boundPolicy).map((v) => ({
             ruleId: v.rule_id,
             ruleName: def.name,
             severity: v.severity,
@@ -175,9 +184,14 @@ function adapt(def, evaluate) {
  *
  * A `null` threshold means measure, don't judge: the rule stays registered and simply
  * reports nothing.
+ *
+ * CR-GC-402: `policy` is the BOUND value — the one that judges when a caller names none.
+ * `DefaultRuleEngine.evaluate(graph, policy)` may override it per call, which is what lets
+ * a consumer of the published descriptor judge with its own `graphcode.config.jsonc`
+ * instead of silently with the default.
  */
 function seRules(policy) {
-    return [...SE_RULE_DEFS, ...MT_RULES].map((def) => adapt(def, (g) => def.evaluate(g, policy)));
+    return [...SE_RULE_DEFS, ...MT_RULES].map((def) => adapt(def, (g, p) => def.evaluate(g, p), 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/graph-api-core",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@sigloch/contracts": ">=5 <10",
+    "@sigloch/contracts": ">=10 <11",
     "kuzu-wasm": "^0.11.3"
   },
   "peerDependenciesMeta": {
@@ -52,7 +52,7 @@
     }
   },
   "devDependencies": {
-    "@sigloch/contracts": ">=6 <10",
+    "@sigloch/contracts": ">=10 <11",
     "kuzu-wasm": "^0.11.3"
   }
 }