@sigloch/graph-api-core 4.0.0 → 5.1.0

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

@@ -23,6 +23,12 @@ export declare class FormatECodec {
     private parseNodeLine;
     private parseEdgeLine;
     private parseMerge;
+    /**
+     * CR-SM-251: derselbe Hydrations-Ort wie beim `@key value`-Pfad. Vorher war dies der einzige
+     * Pfad OHNE Hydration — hart auf `Record<string, string>` typisiert, womit `[concept:true]`
+     * als String "true" ankam und jede `=== true`-Ausnahme wirkungslos blieb (CR-GC-334 hatte
+     * genau diese Doppelung schon einmal fuer Objekte aufgeloest, nur eine Zeile weiter oben).
+     */
     private parseInlineAttrs;
     /**
      * CR-SM-215: fan-out serialization — edges sharing `(sourceId, edgeType)` collapse

package/dist/format-e-codec.js

@@ -7,7 +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 { hydrateAttrValue, attributeTypeOf } from '@sigloch/contracts/se';
 import { isValidTrace, tracePatternsOf } from './types.js';
 // ---------------------------------------------------------------------------
 // Regex patterns
@@ -78,7 +78,7 @@ export class FormatECodec {
                     // 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());
+                    lastOp.attributes[attrMatch[1]] = hydrateAttrValue(attrMatch[2].trim(), attributeTypeOf(lastOp.elementType, attrMatch[1]));
                 }
                 else {
                     errors.push(`@attribute line without preceding node: "${line}"`);
@@ -197,7 +197,7 @@ export class FormatECodec {
         const attrMatch = INLINE_ATTRS_RE.exec(rest);
         if (attrMatch) {
             mainPart = rest.slice(0, attrMatch.index).trim();
-            inlineAttrs = this.parseInlineAttrs(attrMatch[1]);
+            inlineAttrs = this.parseInlineAttrs(attrMatch[1], nodeType);
         }
         // Split uid|description
         const pipeIdx = mainPart.indexOf('|');
@@ -237,6 +237,9 @@ export class FormatECodec {
         const action = OP_PREFIX[opChar] ?? 'add';
         // Extract inline attributes from the line
         let mainPart = rest;
+        // CR-SM-251: Kanten-Attribute (cardinality/constraint/notes) sind Strings und bleiben es —
+        // `attributeTypeOf` kennt nur Element-Attribute, ohne Typ faellt die Hydrierung auf String
+        // zurueck. Der Typ ist trotzdem `unknown`, damit hier kein zweiter Hydrations-Pfad entsteht.
         let inlineAttrs;
         const attrMatch = INLINE_ATTRS_RE.exec(rest);
         if (attrMatch) {
@@ -308,12 +311,19 @@ export class FormatECodec {
             sourceIds: parts,
         });
     }
-    parseInlineAttrs(raw) {
+    /**
+     * CR-SM-251: derselbe Hydrations-Ort wie beim `@key value`-Pfad. Vorher war dies der einzige
+     * Pfad OHNE Hydration — hart auf `Record<string, string>` typisiert, womit `[concept:true]`
+     * als String "true" ankam und jede `=== true`-Ausnahme wirkungslos blieb (CR-GC-334 hatte
+     * genau diese Doppelung schon einmal fuer Objekte aufgeloest, nur eine Zeile weiter oben).
+     */
+    parseInlineAttrs(raw, nodeType) {
         const attrs = {};
         for (const pair of raw.split(',')) {
             const colonIdx = pair.indexOf(':');
             if (colonIdx > 0) {
-                attrs[pair.slice(0, colonIdx).trim()] = pair.slice(colonIdx + 1).trim();
+                const key = pair.slice(0, colonIdx).trim();
+                attrs[key] = hydrateAttrValue(pair.slice(colonIdx + 1).trim(), attributeTypeOf(nodeType, key));
             }
         }
         return attrs;

package/dist/kuzu/graph-cypher-engine.d.ts

@@ -0,0 +1,51 @@
+/**
+ * GraphCypherEngine — thin adapter over kuzu-wasm.
+ *
+ * Lifecycle:
+ *   const e = new GraphCypherEngine();
+ *   await e.init(ontology);
+ *   await e.loadGraph(graph);    // idempotent DROP + CREATE
+ *   const r = await e.query(cypher);
+ *   await e.destroy();
+ *
+ * Engine choice is isolated here so a future swap (kuzu fork, server-side
+ * Cypher) does not break consumers.
+ */
+import type { Graph, OntologyDescriptor } from '../types.js';
+import { type GeneratedSchema } from './schema-generator.js';
+import type { GraphCypherEngineOptions, QueryResultRows } from './types.js';
+export declare class GraphCypherEngine {
+    private readonly options;
+    private kuzu;
+    private db;
+    private connection;
+    private schema;
+    private ontology;
+    constructor(options?: GraphCypherEngineOptions);
+    /**
+     * Initialize kuzu, declare schema. Idempotent for the same OntologyDescriptor.
+     */
+    init(ontology: OntologyDescriptor): Promise<void>;
+    /**
+     * Full DROP + CREATE of all graph data. Cheap (<50 ms) at workshop scale
+     * (<500 nodes) and removes any need for incremental sync logic.
+     */
+    loadGraph(graph: Graph): Promise<void>;
+    /**
+     * Run an ad-hoc Cypher query and return rows as plain JS objects.
+     * BigInt values (from kuzu aggregates like count) are coerced to Number.
+     */
+    query(cypher: string): Promise<QueryResultRows>;
+    /**
+     * Run a write/DDL statement (no rows expected). Throws on Cypher error.
+     * Used by the KuzuAdapter for incremental MERGE/SET/DELETE mutations.
+     */
+    exec(cypher: string): Promise<void>;
+    /** Generated schema (label/table maps) — needed by adapters for type↔label mapping. */
+    get generatedSchema(): GeneratedSchema;
+    destroy(): Promise<void>;
+    private execRaw;
+    private ensureReady;
+}
+export declare function stringifyProps(props: Record<string, string>): string;
+export declare function escapeString(v: string): string;

package/dist/kuzu/graph-cypher-engine.js

@@ -0,0 +1,244 @@
+/**
+ * GraphCypherEngine — thin adapter over kuzu-wasm.
+ *
+ * Lifecycle:
+ *   const e = new GraphCypherEngine();
+ *   await e.init(ontology);
+ *   await e.loadGraph(graph);    // idempotent DROP + CREATE
+ *   const r = await e.query(cypher);
+ *   await e.destroy();
+ *
+ * Engine choice is isolated here so a future swap (kuzu fork, server-side
+ * Cypher) does not break consumers.
+ */
+import { generateSchema } from './schema-generator.js';
+async function loadKuzu() {
+    // Node path: sync nodejs variant. Detect Node by checking for `process.versions.node`.
+    const isNode = typeof process !== 'undefined' && !!process.versions?.node;
+    if (isNode) {
+        // CommonJS require keeps vitest happy and avoids ESM-export issues
+        // with the kuzu-wasm `./nodejs/sync` subpath.
+        const { createRequire } = await import('node:module');
+        const req = createRequire(import.meta.url);
+        const kuzu = req('kuzu-wasm/nodejs/sync');
+        if (kuzu.init)
+            await kuzu.init();
+        return kuzu;
+    }
+    // Browser path: default async ESM build.
+    const mod = await import('kuzu-wasm');
+    const kuzu = (mod.default ?? mod);
+    if (kuzu.init)
+        await kuzu.init();
+    return kuzu;
+}
+export class GraphCypherEngine {
+    options;
+    kuzu = null;
+    db = null;
+    connection = null;
+    schema = null;
+    ontology = null;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Initialize kuzu, declare schema. Idempotent for the same OntologyDescriptor.
+     */
+    async init(ontology) {
+        if (this.connection && this.ontology?.version === ontology.version
+            && this.ontology.name === ontology.name) {
+            return;
+        }
+        await this.destroy();
+        this.kuzu = await loadKuzu();
+        this.db = new this.kuzu.Database(this.options.path ?? ':memory:');
+        this.connection = new this.kuzu.Connection(this.db);
+        this.schema = generateSchema(ontology, this.options);
+        this.ontology = ontology;
+        for (const ddl of this.schema.ddl) {
+            // Idempotent so a persistent DB can be re-opened (tables already exist).
+            await this.execRaw(idempotentDdl(ddl));
+        }
+    }
+    /**
+     * Full DROP + CREATE of all graph data. Cheap (<50 ms) at workshop scale
+     * (<500 nodes) and removes any need for incremental sync logic.
+     */
+    async loadGraph(graph) {
+        this.ensureReady();
+        const schema = this.schema;
+        // Wipe: kuzu has no TRUNCATE in 0.11.x, but `MATCH (n) DETACH DELETE n`
+        // clears everything in one statement. (Tested in the empirical probe.)
+        await this.execRaw('MATCH (n) DETACH DELETE n');
+        // Insert nodes — grouped by label so we issue one CREATE per node (kuzu
+        // accepts batched CREATE in 0.11.x but parameter binding for STRING is the
+        // cleaner path; we'll prepare per label later if perf demands).
+        for (const node of graph.nodes) {
+            const label = schema.nodeLabelByKey.get(node.type);
+            if (!label) {
+                console.warn(`[graph-api-core/kuzu] Unknown node type "${node.type}" for uid ${node.uid} — skipped`);
+                continue;
+            }
+            const cols = schema.nodePropsByLabel.get(label);
+            const props = {
+                uid: node.uid,
+                name: node.name ?? '',
+                description: node.description ?? '',
+            };
+            for (const key of cols.slice(3)) {
+                const v = node.attributes?.[key];
+                if (v !== undefined && v !== null)
+                    props[key] = String(v);
+            }
+            await this.execRaw(`CREATE (:${label} ${stringifyProps(props)})`);
+        }
+        // Insert edges — kuzu requires labeled endpoints in CREATE patterns,
+        // so we resolve each endpoint's label from the loaded node set first.
+        const uidToLabel = new Map();
+        for (const node of graph.nodes) {
+            const label = schema.nodeLabelByKey.get(node.type);
+            if (label)
+                uidToLabel.set(node.uid, label);
+        }
+        for (const edge of graph.edges) {
+            const table = schema.edgeTableByKey.get(edge.edgeType);
+            if (!table) {
+                console.warn(`[graph-api-core/kuzu] Unknown edge type "${edge.edgeType}" — skipped`);
+                continue;
+            }
+            const fromLabel = uidToLabel.get(edge.sourceId);
+            const toLabel = uidToLabel.get(edge.targetId);
+            if (!fromLabel || !toLabel) {
+                console.warn(`[graph-api-core/kuzu] Edge "${edge.sourceId} -${edge.edgeType}-> ${edge.targetId}" ` +
+                    `references unknown node(s) — skipped`);
+                continue;
+            }
+            const edgeProps = {};
+            for (const key of schema.edgePropsByTable.get(table) ?? []) {
+                const v = edge.attributes?.[key];
+                if (v !== undefined && v !== null)
+                    edgeProps[key] = String(v);
+            }
+            const propsClause = Object.keys(edgeProps).length > 0
+                ? ` ${stringifyProps(edgeProps)}`
+                : '';
+            await this.execRaw(`MATCH (s:${fromLabel} {uid: ${escapeString(edge.sourceId)}}), ` +
+                `(t:${toLabel} {uid: ${escapeString(edge.targetId)}}) ` +
+                `CREATE (s)-[:${table}${propsClause}]->(t)`);
+        }
+    }
+    /**
+     * Run an ad-hoc Cypher query and return rows as plain JS objects.
+     * BigInt values (from kuzu aggregates like count) are coerced to Number.
+     */
+    async query(cypher) {
+        this.ensureReady();
+        const t0 = performance.now();
+        const result = await Promise.resolve(this.connection.query(cypher));
+        if (!result.isSuccess()) {
+            const msg = result.getErrorMessage();
+            try {
+                result.close?.();
+            }
+            catch { /* noop */ }
+            throw new Error(`Cypher error: ${msg}`);
+        }
+        const columns = await Promise.resolve(result.getColumnNames());
+        const rawRows = await Promise.resolve(result.getAllObjects());
+        const rows = rawRows.map(coerceRow);
+        try {
+            result.close?.();
+        }
+        catch { /* noop */ }
+        const ms = Math.round((performance.now() - t0) * 10) / 10;
+        return { rows, columns, ms };
+    }
+    /**
+     * Run a write/DDL statement (no rows expected). Throws on Cypher error.
+     * Used by the KuzuAdapter for incremental MERGE/SET/DELETE mutations.
+     */
+    async exec(cypher) {
+        this.ensureReady();
+        await this.execRaw(cypher);
+    }
+    /** Generated schema (label/table maps) — needed by adapters for type↔label mapping. */
+    get generatedSchema() {
+        this.ensureReady();
+        return this.schema;
+    }
+    async destroy() {
+        try {
+            this.db?.close?.();
+        }
+        catch { /* noop */ }
+        this.connection = null;
+        this.db = null;
+        this.kuzu = null;
+        this.schema = null;
+        this.ontology = null;
+    }
+    // -- internals --
+    async execRaw(cypher) {
+        const result = await Promise.resolve(this.connection.query(cypher));
+        if (!result.isSuccess()) {
+            const msg = result.getErrorMessage();
+            try {
+                result.close?.();
+            }
+            catch { /* noop */ }
+            throw new Error(`Cypher error in "${cypher.slice(0, 80)}": ${msg}`);
+        }
+        try {
+            result.close?.();
+        }
+        catch { /* noop */ }
+    }
+    ensureReady() {
+        if (!this.connection || !this.schema) {
+            throw new Error('GraphCypherEngine: call init(ontology) before use');
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+function coerceRow(row) {
+    const out = {};
+    for (const [k, v] of Object.entries(row)) {
+        out[k] = coerceValue(v);
+    }
+    return out;
+}
+function coerceValue(v) {
+    if (typeof v === 'bigint')
+        return Number(v);
+    if (Array.isArray(v))
+        return v.map(coerceValue);
+    if (v && typeof v === 'object') {
+        // kuzu wraps numeric results from aggregates as boxed Number objects.
+        // Unbox them so consumers can do `r.rows[0].c === 2` not `Number(r.rows[0].c) === 2`.
+        if (v instanceof Number)
+            return Number(v);
+        if (v instanceof String)
+            return String(v);
+        if (v instanceof Boolean)
+            return Boolean(v);
+        return coerceRow(v);
+    }
+    return v;
+}
+export function stringifyProps(props) {
+    const parts = Object.entries(props).map(([k, v]) => `${k}: ${escapeString(v)}`);
+    return `{${parts.join(', ')}}`;
+}
+export function escapeString(v) {
+    return `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/**
+ * Insert `IF NOT EXISTS` into a `CREATE NODE/REL TABLE` statement so DDL can be
+ * replayed against a persistent DB whose tables already exist (no-op then).
+ */
+function idempotentDdl(ddl) {
+    return ddl.replace(/^CREATE (NODE|REL) TABLE (?!IF NOT EXISTS)/, 'CREATE $1 TABLE IF NOT EXISTS ');
+}

package/dist/kuzu/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @sigloch/graph-api-core/kuzu
+ * In-process Cypher engine and store over kuzu-wasm.
+ *
+ * Deliberately NOT re-exported from the package root: only this subpath pulls
+ * kuzu-wasm, so a consumer that needs the ontology types alone (./browser) never
+ * loads the WASM binary. kuzu-wasm is an optional peerDependency (CR-SM-248).
+ */
+export { GraphCypherEngine } from './graph-cypher-engine.js';
+export { KuzuAdapter } from './kuzu-adapter.js';
+export type { KuzuAdapterOptions } from './kuzu-adapter.js';
+export { generateSchema } from './schema-generator.js';
+export type { GeneratedSchema } from './schema-generator.js';
+export type { GraphCypherEngineOptions, QueryResultRows } from './types.js';

package/dist/kuzu/index.js

@@ -0,0 +1,11 @@
+/**
+ * @sigloch/graph-api-core/kuzu
+ * In-process Cypher engine and store over kuzu-wasm.
+ *
+ * Deliberately NOT re-exported from the package root: only this subpath pulls
+ * kuzu-wasm, so a consumer that needs the ontology types alone (./browser) never
+ * loads the WASM binary. kuzu-wasm is an optional peerDependency (CR-SM-248).
+ */
+export { GraphCypherEngine } from './graph-cypher-engine.js';
+export { KuzuAdapter } from './kuzu-adapter.js';
+export { generateSchema } from './schema-generator.js';

package/dist/kuzu/kuzu-adapter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * KuzuAdapter — StorageAdapter over Kuzu.
+ *
+ * Persistent and incremental: mutations are MERGE/SET/DELETE statements against
+ * a live Kuzu DB — no DROP+CREATE per write (unlike GraphCypherEngine.loadGraph,
+ * which is kept for full-reload consumers). Pass an on-disk `path` to survive a
+ * process restart; the default `:memory:` is for tests/short-lived sessions.
+ *
+ * Kuzu is "just another adapter" behind the existing storage-adapter.ts contract
+ * (bok §6, 2yR-35 C7). Schema (node tables / rel tables) is derived from the
+ * OntologyDescriptor via the shared schema-generator.
+ */
+import type { StorageAdapter } from '../storage-adapter.js';
+import type { GraphNode, GraphEdge, Graph, GraphScope, OntologyDescriptor } from '../types.js';
+import type { GraphCypherEngineOptions } from './types.js';
+export interface KuzuAdapterOptions extends GraphCypherEngineOptions {
+    /** Ontology whose node/edge types define the Kuzu schema (node + rel tables). */
+    ontology: OntologyDescriptor;
+}
+export declare class KuzuAdapter implements StorageAdapter {
+    readonly name = "kuzu";
+    private readonly engine;
+    private readonly ontology;
+    /** kuzu label → ontology node-type key (inverse of schema.nodeLabelByKey). */
+    private readonly labelToType;
+    /** kuzu rel table → ontology edge-type key (inverse of schema.edgeTableByKey). */
+    private readonly tableToEdgeType;
+    constructor(options: KuzuAdapterOptions);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    loadGraph(_scope: GraphScope): Promise<Graph>;
+    saveNodes(nodes: GraphNode[]): Promise<void>;
+    deleteNodes(uids: string[]): Promise<void>;
+    saveEdges(edges: GraphEdge[]): Promise<void>;
+    /** uid → kuzu label for the given uids (one query). Missing uids are absent. */
+    private resolveLabels;
+    deleteEdges(keys: Array<{
+        sourceId: string;
+        targetId: string;
+        edgeType: string;
+    }>): Promise<void>;
+    getNode(uid: string): Promise<GraphNode | null>;
+    getSubgraph(root: string, depth: number, direction?: 'out' | 'in' | 'both'): Promise<Graph>;
+    stats(): Promise<{
+        nodeCount: number;
+        edgeCount: number;
+    }>;
+    isHealthy(): Promise<boolean>;
+    private toNode;
+    private toEdge;
+}

package/dist/kuzu/kuzu-adapter.js

@@ -0,0 +1,312 @@
+/**
+ * KuzuAdapter — StorageAdapter over Kuzu.
+ *
+ * Persistent and incremental: mutations are MERGE/SET/DELETE statements against
+ * a live Kuzu DB — no DROP+CREATE per write (unlike GraphCypherEngine.loadGraph,
+ * which is kept for full-reload consumers). Pass an on-disk `path` to survive a
+ * process restart; the default `:memory:` is for tests/short-lived sessions.
+ *
+ * Kuzu is "just another adapter" behind the existing storage-adapter.ts contract
+ * (bok §6, 2yR-35 C7). Schema (node tables / rel tables) is derived from the
+ * OntologyDescriptor via the shared schema-generator.
+ */
+import { GraphCypherEngine, escapeString } from './graph-cypher-engine.js';
+/** Parse the lossless `attrs_json` catch-all column back into an attributes object. */
+function parseAttrsJson(raw) {
+    if (typeof raw !== 'string' || raw === '')
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+export class KuzuAdapter {
+    name = 'kuzu';
+    engine;
+    ontology;
+    /** kuzu label → ontology node-type key (inverse of schema.nodeLabelByKey). */
+    labelToType = new Map();
+    /** kuzu rel table → ontology edge-type key (inverse of schema.edgeTableByKey). */
+    tableToEdgeType = new Map();
+    constructor(options) {
+        this.ontology = options.ontology;
+        this.engine = new GraphCypherEngine({
+            path: options.path ?? ':memory:',
+            extraNodeProps: options.extraNodeProps,
+            extraEdgeProps: options.extraEdgeProps,
+        });
+    }
+    async initialize() {
+        await this.engine.init(this.ontology);
+        const schema = this.engine.generatedSchema;
+        this.labelToType.clear();
+        for (const [key, label] of schema.nodeLabelByKey)
+            this.labelToType.set(label, key);
+        this.tableToEdgeType.clear();
+        for (const [key, table] of schema.edgeTableByKey)
+            this.tableToEdgeType.set(table, key);
+    }
+    async shutdown() {
+        await this.engine.destroy();
+    }
+    // -- CRUD ------------------------------------------------------------------
+    async loadGraph(_scope) {
+        const nodeRows = await this.engine.query('MATCH (n) RETURN n');
+        const nodes = nodeRows.rows.map(r => this.toNode(r.n));
+        const edgeRows = await this.engine.query('MATCH (s)-[r]->(t) RETURN s.uid AS src, t.uid AS tgt, r AS rel');
+        const edges = edgeRows.rows.map(r => this.toEdge(r));
+        return { nodes, edges };
+    }
+    async saveNodes(nodes) {
+        const schema = this.engine.generatedSchema;
+        // Group by kuzu label: one UNWIND-batched MERGE per label instead of one
+        // engine round-trip per node (CR-GC-120). Each MERGE pattern needs a concrete
+        // label, so the grouping is by label.
+        const byLabel = new Map();
+        for (const node of nodes) {
+            const label = schema.nodeLabelByKey.get(node.type);
+            if (!label) {
+                console.warn(`[kuzu-adapter] Unknown node type "${node.type}" for uid ${node.uid} — skipped`);
+                continue;
+            }
+            (byLabel.get(label) ?? byLabel.set(label, []).get(label)).push(node);
+        }
+        for (const [label, group] of byLabel) {
+            // Extra (declared) props are queryable columns. Old per-row path SET only
+            // the props that were present, leaving absent ones untouched. To keep that
+            // idempotent semantic in a single batched statement, every row carries the
+            // SAME key set (homogeneous map list — kuzu requires it) using NULL for
+            // absent props, and the SET uses coalesce(row.k, n.k) so NULL preserves the
+            // existing column value (exact equivalent of the old omit-if-absent path).
+            const declaredExtra = (schema.nodePropsByLabel.get(label) ?? [])
+                .filter(p => p !== 'uid' && p !== 'name' && p !== 'description');
+            // Only project extra columns that ANY row in the group actually sets. A prop
+            // absent across the whole group is never referenced (identical to the old
+            // per-row path that omitted absent props) — and skipping it avoids a needless
+            // per-row coalesce read/write, the dominant cost at scale (CR-GC-120).
+            const extraProps = declaredExtra.filter(key => group.some(n => n.attributes?.[key] !== undefined && n.attributes?.[key] !== null));
+            const rows = group.map(node => {
+                const cells = [
+                    `uid: ${escapeString(node.uid)}`,
+                    `name: ${escapeString(node.name ?? '')}`,
+                    `description: ${escapeString(node.description ?? '')}`,
+                ];
+                for (const key of extraProps) {
+                    const v = node.attributes?.[key];
+                    cells.push(`${key}: ${v === undefined || v === null ? 'NULL' : escapeString(String(v))}`);
+                }
+                cells.push(`attrs_json: ${escapeString(JSON.stringify(node.attributes ?? {}))}`);
+                return `{${cells.join(', ')}}`;
+            });
+            const sets = [
+                'n.name = row.name',
+                'n.description = row.description',
+                // coalesce: a row that lacks this prop (NULL) preserves the existing column,
+                // matching the old omit-if-absent idempotency for partial updates.
+                ...extraProps.map(k => `n.${k} = coalesce(row.${k}, n.${k})`),
+                'n.attrs_json = row.attrs_json',
+            ];
+            await this.engine.exec(`UNWIND [${rows.join(', ')}] AS row ` +
+                `MERGE (n:${label} {uid: row.uid}) SET ${sets.join(', ')}`);
+        }
+    }
+    async deleteNodes(uids) {
+        for (const uid of uids) {
+            await this.engine.exec(`MATCH (n {uid: ${escapeString(uid)}}) DETACH DELETE n`);
+        }
+    }
+    async saveEdges(edges) {
+        if (edges.length === 0)
+            return;
+        const schema = this.engine.generatedSchema;
+        // Multi-pair rel tables (e.g. compose: PR→C, C→C) need labeled endpoints in
+        // CREATE/MERGE — kuzu rejects rels bound by multiple node labels otherwise.
+        const endpointUids = new Set();
+        for (const e of edges) {
+            endpointUids.add(e.sourceId);
+            endpointUids.add(e.targetId);
+        }
+        const labelOf = await this.resolveLabels([...endpointUids]);
+        // Group by (table, sLabel, tLabel): the MERGE pattern needs concrete endpoint
+        // labels, so each distinct triple is one UNWIND-batched statement instead of
+        // one MATCH+MERGE round-trip per edge (CR-GC-120).
+        const groups = new Map();
+        for (const edge of edges) {
+            const table = schema.edgeTableByKey.get(edge.edgeType);
+            if (!table) {
+                console.warn(`[kuzu-adapter] Unknown edge type "${edge.edgeType}" — skipped`);
+                continue;
+            }
+            const sLabel = labelOf.get(edge.sourceId);
+            const tLabel = labelOf.get(edge.targetId);
+            if (!sLabel || !tLabel) {
+                console.warn(`[kuzu-adapter] Edge "${edge.sourceId} -${edge.edgeType}-> ${edge.targetId}" ` +
+                    'references unknown node(s) — skipped');
+                continue;
+            }
+            const gkey = `${table}\u0000${sLabel}\u0000${tLabel}`;
+            let g = groups.get(gkey);
+            if (!g) {
+                g = { table, sLabel, tLabel, edges: [] };
+                groups.set(gkey, g);
+            }
+            g.edges.push(edge);
+        }
+        for (const { table, sLabel, tLabel, edges: group } of groups.values()) {
+            // attrs_json always present; declared extra props use NULL + coalesce so an
+            // absent prop preserves the existing column (identical to the old per-edge
+            // omit-if-absent SET). Homogeneous map list is required by kuzu.
+            const declaredExtra = schema.edgePropsByTable.get(table) ?? [];
+            // Project only extra columns set by some edge in the group (see saveNodes).
+            const extraProps = declaredExtra.filter(key => group.some(e => e.attributes?.[key] !== undefined && e.attributes?.[key] !== null));
+            const rows = group.map(edge => {
+                const cells = [
+                    `s: ${escapeString(edge.sourceId)}`,
+                    `t: ${escapeString(edge.targetId)}`,
+                ];
+                for (const key of extraProps) {
+                    const v = edge.attributes?.[key];
+                    cells.push(`${key}: ${v === undefined || v === null ? 'NULL' : escapeString(String(v))}`);
+                }
+                cells.push(`attrs_json: ${escapeString(JSON.stringify(edge.attributes ?? {}))}`);
+                return `{${cells.join(', ')}}`;
+            });
+            const sets = [
+                ...extraProps.map(k => `r.${k} = coalesce(row.${k}, r.${k})`),
+                'r.attrs_json = row.attrs_json',
+            ];
+            await this.engine.exec(`UNWIND [${rows.join(', ')}] AS row ` +
+                `MATCH (s:${sLabel} {uid: row.s}), (t:${tLabel} {uid: row.t}) ` +
+                `MERGE (s)-[r:${table}]->(t) SET ${sets.join(', ')}`);
+        }
+    }
+    /** uid → kuzu label for the given uids (one query). Missing uids are absent. */
+    async resolveLabels(uids) {
+        const map = new Map();
+        if (uids.length === 0)
+            return map;
+        const inList = uids.map(escapeString).join(', ');
+        const r = await this.engine.query(`MATCH (n) WHERE n.uid IN [${inList}] RETURN n.uid AS uid, label(n) AS lbl`);
+        for (const row of r.rows)
+            map.set(String(row.uid), String(row.lbl));
+        return map;
+    }
+    async deleteEdges(keys) {
+        const schema = this.engine.generatedSchema;
+        for (const key of keys) {
+            const table = schema.edgeTableByKey.get(key.edgeType);
+            if (!table)
+                continue;
+            await this.engine.exec(`MATCH (s {uid: ${escapeString(key.sourceId)}})-[r:${table}]->` +
+                `(t {uid: ${escapeString(key.targetId)}}) DELETE r`);
+        }
+    }
+    // -- Query -----------------------------------------------------------------
+    async getNode(uid) {
+        const r = await this.engine.query(`MATCH (n {uid: ${escapeString(uid)}}) RETURN n`);
+        if (r.rows.length === 0)
+            return null;
+        return this.toNode(r.rows[0].n);
+    }
+    async getSubgraph(root, depth, direction = 'out') {
+        const rootEsc = escapeString(root);
+        const nodeMap = new Map();
+        const rootRow = await this.engine.query(`MATCH (n {uid: ${rootEsc}}) RETURN n`);
+        for (const row of rootRow.rows) {
+            const n = this.toNode(row.n);
+            nodeMap.set(n.uid, n);
+        }
+        if (depth > 0) {
+            // Direction defines what "reachable" means:
+            //   out  → root's dependencies        : (root)-[*1..d]->(m)
+            //   in   → root's dependents / impact  : (m)-[*1..d]->(root)
+            //   both → union of in + out
+            const patterns = [];
+            if (direction === 'out' || direction === 'both') {
+                patterns.push(`MATCH (root {uid: ${rootEsc}})-[*1..${depth}]->(m) RETURN DISTINCT m`);
+            }
+            if (direction === 'in' || direction === 'both') {
+                patterns.push(`MATCH (m)-[*1..${depth}]->(root {uid: ${rootEsc}}) RETURN DISTINCT m`);
+            }
+            for (const cypher of patterns) {
+                const reach = await this.engine.query(cypher);
+                for (const row of reach.rows) {
+                    const n = this.toNode(row.m);
+                    nodeMap.set(n.uid, n);
+                }
+            }
+        }
+        // Induced edges: keep edges whose endpoints are both in the subgraph node set.
+        const edges = [];
+        if (nodeMap.size > 0) {
+            const inList = [...nodeMap.keys()].map(escapeString).join(', ');
+            const edgeRows = await this.engine.query(`MATCH (s)-[r]->(t) WHERE s.uid IN [${inList}] AND t.uid IN [${inList}] ` +
+                'RETURN s.uid AS src, t.uid AS tgt, r AS rel');
+            for (const row of edgeRows.rows)
+                edges.push(this.toEdge(row));
+        }
+        return { nodes: [...nodeMap.values()], edges };
+    }
+    // -- Meta ------------------------------------------------------------------
+    async stats() {
+        const n = await this.engine.query('MATCH (n) RETURN count(n) AS c');
+        const e = await this.engine.query('MATCH ()-[r]->() RETURN count(r) AS c');
+        return {
+            nodeCount: Number(n.rows[0]?.c ?? 0),
+            edgeCount: Number(e.rows[0]?.c ?? 0),
+        };
+    }
+    async isHealthy() {
+        try {
+            await this.engine.query('RETURN 1 AS ok');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // -- internals -------------------------------------------------------------
+    toNode(n) {
+        const label = String(n._label);
+        // attrs_json is the lossless source of truth; declared columns are a fallback
+        // (legacy rows) and never override a value already present in the blob.
+        const attributes = parseAttrsJson(n.attrs_json);
+        for (const [k, v] of Object.entries(n)) {
+            if (k.startsWith('_') || k === 'uid' || k === 'name' || k === 'description' || k === 'attrs_json')
+                continue;
+            if (v !== null && v !== undefined && v !== '' && attributes[k] === undefined)
+                attributes[k] = v;
+        }
+        const node = {
+            uid: String(n.uid),
+            type: this.labelToType.get(label) ?? label,
+            name: n.name == null ? '' : String(n.name),
+            attributes,
+        };
+        if (n.description != null && n.description !== '')
+            node.description = String(n.description);
+        return node;
+    }
+    toEdge(row) {
+        const rel = row.rel;
+        const table = String(rel._label);
+        const attributes = parseAttrsJson(rel.attrs_json);
+        for (const [k, v] of Object.entries(rel)) {
+            if (k.startsWith('_') || k === 'attrs_json')
+                continue;
+            if (v !== null && v !== undefined && v !== '' && attributes[k] === undefined)
+                attributes[k] = v;
+        }
+        return {
+            sourceId: String(row.src),
+            targetId: String(row.tgt),
+            edgeType: this.tableToEdgeType.get(table) ?? table,
+            attributes,
+        };
+    }
+}

package/dist/kuzu/schema-generator.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Generate kuzu DDL from a sigloch OntologyDescriptor.
+ *
+ * Each NodeTypeDescriptor becomes one `CREATE NODE TABLE`. Each
+ * EdgeTypeDescriptor becomes one `CREATE REL TABLE` with all valid
+ * (sourceType, targetType) pairs declared via kuzu's multi-pair syntax.
+ *
+ * Property model:
+ * - Every node table has: `uid STRING PRIMARY KEY`, `name STRING`, `description STRING`
+ * - Plus a configurable set of extra props (also STRING — pragmatic; kuzu has
+ *   no schemaless properties) — these stay individually queryable in Cypher.
+ * - Plus `attrs_json STRING`: a catch-all on every node AND rel table holding the
+ *   FULL attribute set as serialized JSON. The adapter writes/reads it so NO
+ *   attribute is lost on a store round-trip (lossless SSOT — created_at, kinds,
+ *   arrays/objects, edge labels). Declared extra props remain the queryable
+ *   projection; `attrs_json` is the source of truth on read.
+ */
+import type { OntologyDescriptor } from '@sigloch/graph-api-core';
+import type { GraphCypherEngineOptions } from './types.js';
+export interface GeneratedSchema {
+    /** Ordered list of `CREATE NODE TABLE` / `CREATE REL TABLE` statements. */
+    ddl: string[];
+    /** Label-by-typeKey lookup for the loader (e.g. `OU → OrgUnit`). */
+    nodeLabelByKey: Map<string, string>;
+    /** Edge-table-name by edgeType key (kebab keys map 1:1 to table names). */
+    edgeTableByKey: Map<string, string>;
+    /** Allowed property keys per node label. */
+    nodePropsByLabel: Map<string, string[]>;
+    /** Allowed property keys per edge table. */
+    edgePropsByTable: Map<string, string[]>;
+}
+export declare function generateSchema(ontology: OntologyDescriptor, options?: GraphCypherEngineOptions): GeneratedSchema;

package/dist/kuzu/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Public types of @sigloch/graph-api-core/kuzu.
+ * Intentionally engine-agnostic so kuzu-wasm can be swapped later.
+ */
+export interface GraphCypherEngineOptions {
+    /**
+     * Kuzu database path. `:memory:` (default) or empty → ephemeral in-memory DB.
+     * A real on-disk directory makes the graph persistent across process restarts
+     * (the kuzu-wasm nodejs build uses NODERAWFS — the path maps to the real FS).
+     */
+    path?: string;
+    /**
+     * Property keys on nodes that should be pre-declared as queryable columns
+     * (STRING type). Anything not in this list lands in `attrs_json` and is not
+     * directly query-able with `n.foo`. Defaults to the keys commonly referenced
+     * by ontoagent workshop CQs.
+     */
+    extraNodeProps?: string[];
+    /**
+     * Property keys on edges that should be queryable. Defaults to the
+     * CR-007-reserved keys (`cardinality`, `constraint`, `notes`).
+     */
+    extraEdgeProps?: string[];
+}
+export interface QueryResultRows {
+    rows: Record<string, unknown>[];
+    columns: string[];
+    /** Wall-clock execution time in milliseconds (rounded to 0.1). */
+    ms: number;
+}

package/dist/kuzu/types.js

@@ -0,0 +1,5 @@
+/**
+ * Public types of @sigloch/graph-api-core/kuzu.
+ * Intentionally engine-agnostic so kuzu-wasm can be swapped later.
+ */
+export {};

package/dist/storage-adapter.d.ts

@@ -1,5 +1,5 @@
 /**
- * StorageAdapter interface — implemented by KuzuAdapter (@sigloch/graph-cypher-wasm), the one production store (Kuzu-only, 2yR-SSOT §Verriegelte Entscheidungen #3).
+ * StorageAdapter interface — implemented by KuzuAdapter (./kuzu), the one production store (Kuzu-only, 2yR-SSOT §Verriegelte Entscheidungen #3).
  */
 import type { GraphNode, GraphEdge, Graph, GraphScope } from './types.js';
 export interface StorageAdapter {

package/dist/test-fixtures.d.ts

@@ -1,7 +1,7 @@
 /**
  * Format-E test fixtures shipped with @sigloch/graph-api-core.
  *
- * Purpose: every consumer package (graph-renderer, graph-cypher-wasm,
+ * Purpose: every consumer package (graph-renderer, kuzu,
  * ontoagent-app, aise, flowground, …) loads these same fixtures in its test
  * setup. Round-trip equality across consumers fences off Format-E drift sigloch-wide.
  *

package/dist/test-fixtures.js

@@ -1,7 +1,7 @@
 /**
  * Format-E test fixtures shipped with @sigloch/graph-api-core.
  *
- * Purpose: every consumer package (graph-renderer, graph-cypher-wasm,
+ * Purpose: every consumer package (graph-renderer, kuzu,
  * ontoagent-app, aise, flowground, …) loads these same fixtures in its test
  * setup. Round-trip equality across consumers fences off Format-E drift sigloch-wide.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/graph-api-core",
-  "version": "4.0.0",
+  "version": "5.1.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,8 @@
     ".": "./dist/index.js",
     "./browser": "./dist/browser.js",
     "./testing": "./dist/testing/index.js",
-    "./test-fixtures": "./dist/test-fixtures.js"
+    "./test-fixtures": "./dist/test-fixtures.js",
+    "./kuzu": "./dist/kuzu/index.js"
   },
   "scripts": {
     "build": "rm -rf dist && tsc",
@@ -21,11 +22,10 @@
     "prepublishOnly": "npm run build && npm run test"
   },
   "dependencies": {
-    "@sigloch/contracts": "^5.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 — ontology-typed nodes/traces, rule evaluation, views, and the embedded Kuzu store (./kuzu)",
   "author": "sigloch-consulting",
   "repository": {
     "type": "git",
@@ -41,5 +41,18 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "@sigloch/contracts": ">=5 <7",
+    "kuzu-wasm": "^0.11.3"
+  },
+  "peerDependenciesMeta": {
+    "kuzu-wasm": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@sigloch/contracts": "^6.0.0",
+    "kuzu-wasm": "^0.11.3"
   }
 }