@aiwg/cli 2026.8.19 → 2026.8.20

package/THIRD_PARTY_NOTICES.md

@@ -28,6 +28,18 @@ npm ls @fortemi/core @bytecask/core
 
 Each installed dependency package includes its own `LICENSE` and `package.json`. To inspect the exact source reference for a different resolved version, run `npm view @fortemi/core@<version> repository license` or `npm view @bytecask/core@<version> repository license`.
 
+## Unified Harness Protocol schema
+
+- Vendored file: `schemas/uhp/uhp-2026-08-11.schema.json`
+- Upstream: <https://github.com/HarnessRouter/harnessrouter/blob/db78b957492766a5a5c76bc9981a9234f4546f5f/protocol/schema/uhp-2026-08-11.schema.json>
+- Protocol version: `2026-08-11`
+- Upstream license: Apache-2.0
+- Vendored SHA-256: `c9a22b0e4752bfe407c08930dec9b4f1f6aaa862878c4e540a75274241b31c3a`
+
+The schema is vendored unchanged to make UHP fixture and compatibility tests
+offline and version-pinned. AIWG's experimental client does not imply UHP
+server conformance.
+
 ## Distribution boundary
 
 The `aiwg` and `@aiwg/cli` npm archives do not copy Fortemi or Bytecask object code into their own tarballs. npm resolves those packages separately during installation. AIWG does, however, intentionally import Fortemi in-process at runtime, so separate archive delivery is not by itself a legal conclusion about whether execution forms a combined work.

package/dist/src/api/index.d.ts

@@ -15,5 +15,7 @@ export * from '../security/artifact-attestation.js';
 export * from '../providers/transformation-receipt.js';
 export * from '../providers/transformation-receipt-integration.js';
 export * from '../marketplace/artifact-attestation.js';
+export * from '../uhp/index.js';
+export * from '../mission-protocol/index.js';
 export { ARTIFACT_TRUST_ROOT_MEDIA_TYPE, ARTIFACT_TRUST_ROOT_SCHEMA_VERSION, ARTIFACT_TRUST_STATE_SCHEMA_VERSION, bootstrapTrustRoot, parseTrustRoot, parseTrustState, readTrustState, validateTrustRoot, validateTrustState, verifyRootTransition, writeTrustState, channelStateKey, canonicalJson, dssePae, publicKeyFingerprint, sha256, type ArtifactTrustRoot, type ArtifactTrustState, type RootBootstrapResult, type RootTransitionResult, type ArtifactTrustPolicySettings, type TrustedChannelState, } from '../security/artifact-trust.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/api/index.js

@@ -15,5 +15,7 @@ export * from '../security/artifact-attestation.js';
 export * from '../providers/transformation-receipt.js';
 export * from '../providers/transformation-receipt-integration.js';
 export * from '../marketplace/artifact-attestation.js';
+export * from '../uhp/index.js';
+export * from '../mission-protocol/index.js';
 export { ARTIFACT_TRUST_ROOT_MEDIA_TYPE, ARTIFACT_TRUST_ROOT_SCHEMA_VERSION, ARTIFACT_TRUST_STATE_SCHEMA_VERSION, bootstrapTrustRoot, parseTrustRoot, parseTrustState, readTrustState, validateTrustRoot, validateTrustState, verifyRootTransition, writeTrustState, channelStateKey, canonicalJson, dssePae, publicKeyFingerprint, sha256, } from '../security/artifact-trust.js';
 //# sourceMappingURL=index.js.map

package/dist/src/artifacts/backend-runtime.js

@@ -0,0 +1,26 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createGraphBackend } from './graph-backend.js';
+import { loadGraphIndexFile } from './index-reader.js';
+import { getGraphIndexDir, loadGlobalGraphConfigs, loadUserGraphConfigs, resolveGraphBackendType } from './types.js';
+export function configuredGraphBackend(cwd, graph) {
+    loadUserGraphConfigs(cwd);
+    loadGlobalGraphConfigs();
+    return resolveGraphBackendType(graph);
+}
+export async function openGraphBackend(cwd, graph) {
+    const type = configuredGraphBackend(cwd, graph);
+    const persistentPath = type === 'sqlite' ? path.join(getGraphIndexDir(cwd, graph), 'graph.db') : undefined;
+    const legacy = loadGraphIndexFile(cwd, 'dependencies.json', graph);
+    if (!legacy && (!persistentPath || !fs.existsSync(persistentPath))) {
+        throw new Error(`No artifact index found for graph '${graph}'. Run \`aiwg index build --graph ${graph}\` first.`);
+    }
+    if (persistentPath)
+        fs.mkdirSync(path.dirname(persistentPath), { recursive: true });
+    const backend = await createGraphBackend(type, persistentPath);
+    if (legacy && (type !== 'sqlite' || backend.nodeCount() === 0))
+        backend.deserialize(legacy);
+    return { backend, type, persistentPath };
+}
+export async function closeGraphBackend(active) { await active?.backend.close?.(); }
+//# sourceMappingURL=backend-runtime.js.map

package/dist/src/artifacts/backends/sqlite-backend.js

@@ -3,8 +3,9 @@
  *
  * Optional implementation of GraphBackend using better-sqlite3.
  * Provides persistent on-disk storage, native SQL set operations
- * (INTERSECT/EXCEPT/UNION), recursive CTE traversal, and cross-graph
- * federation via ATTACH DATABASE.
+ * (INTERSECT/EXCEPT/UNION), recursive CTE traversal, and transactional
+ * row reconciliation. Cross-graph ATTACH federation is intentionally not
+ * exposed because its trust, lifecycle, and snapshot boundary is undefined.
  *
  * Enable with: aiwg features install sqlite
  *
@@ -14,6 +15,16 @@
  */
 import { normalizeEdges } from '../types.js';
 import { requireFeaturePackage } from '../../features/runtime.js';
+const SCHEMA_VERSION = 1;
+const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+export class SqliteBusyError extends Error {
+    code = 'AIWG_SQLITE_BUSY';
+    constructor(operation, cause) {
+        super(`sqlite backend remained busy while ${operation} after bounded waiting`);
+        this.name = 'SqliteBusyError';
+        this.cause = cause;
+    }
+}
 /**
  * SQLite-backed graph with persistent storage and native SQL operations.
  *
@@ -23,24 +34,49 @@ import { requireFeaturePackage } from '../../features/runtime.js';
 export class SqliteGraphBackend {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     db;
+    busyTimeoutMs;
     /**
      * Create a new SQLite graph backend.
      *
      * @param dbPath - Path to the SQLite database file. Use ':memory:' for in-memory.
      */
-    constructor(dbPath = ':memory:') {
+    constructor(dbPath = ':memory:', options = {}) {
+        this.busyTimeoutMs = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
         try {
             const Database = requireFeaturePackage('better-sqlite3');
-            this.db = new Database(dbPath);
+            this.db = new Database(dbPath, { timeout: this.busyTimeoutMs });
         }
         catch {
             throw new Error('sqlite backend is unavailable; run `aiwg features install sqlite`');
         }
-        this.db.pragma('journal_mode = WAL');
-        this.initSchema();
+        this.assertSafeSqliteVersion();
+        const requestedJournal = dbPath === ':memory:' ? 'memory' : 'wal';
+        const actualJournal = String(this.db.pragma(`journal_mode = ${requestedJournal}`, { simple: true })).toLowerCase();
+        if (actualJournal !== requestedJournal) {
+            this.db.close();
+            throw new Error(`sqlite backend requested journal_mode=${requestedJournal} but received ${actualJournal}`);
+        }
+        this.db.pragma(`synchronous = ${options.synchronous ?? 'NORMAL'}`);
+        this.db.pragma('wal_autocheckpoint = 1000');
+        this.migrateSchema();
+    }
+    assertSafeSqliteVersion() {
+        const version = String(this.db.prepare('SELECT sqlite_version() AS version').get().version);
+        if (!isWalResetSafeVersion(version)) {
+            this.db.close();
+            throw new Error(`sqlite backend requires a WAL-reset-safe SQLite build (3.44.6, 3.50.7, or >=3.51.3); found ${version}`);
+        }
     }
-    initSchema() {
-        this.db.exec(`
+    migrateSchema() {
+        const current = Number(this.db.pragma('user_version', { simple: true }));
+        if (current > SCHEMA_VERSION) {
+            this.db.close();
+            throw new Error(`sqlite graph schema ${current} is newer than supported schema ${SCHEMA_VERSION}`);
+        }
+        if (current === SCHEMA_VERSION)
+            return;
+        this.db.transaction(() => {
+            this.db.exec(`
       CREATE TABLE IF NOT EXISTS nodes (
         id       TEXT PRIMARY KEY,
         type     TEXT,
@@ -61,23 +97,22 @@ export class SqliteGraphBackend {
 
       CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target, edge_type);
       CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source, edge_type);
-    `);
+      CREATE INDEX IF NOT EXISTS idx_nodes_type_phase ON nodes(type, phase, id);
+      `);
+            this.db.pragma(`user_version = ${SCHEMA_VERSION}`);
+        })();
     }
     // --- Mutation ---
     addNode(id, attrs) {
-        const existing = this.db.prepare('SELECT attrs FROM nodes WHERE id = ?').get(id);
-        if (!existing) {
-            this.db.prepare('INSERT INTO nodes (id, attrs) VALUES (?, ?)').run(id, JSON.stringify(attrs ?? {}));
-        }
-        else if (attrs) {
-            const merged = { ...JSON.parse(existing.attrs), ...attrs };
-            this.db.prepare('UPDATE nodes SET attrs = ? WHERE id = ?').run(JSON.stringify(merged), id);
-        }
+        this.withBusyContext('adding a node', () => this.upsertNode(id, attrs));
     }
     addEdge(source, target, type = 'depends-on', attrs) {
-        this.addNode(source);
-        this.addNode(target);
-        this.db.prepare('INSERT OR IGNORE INTO edges (source, target, edge_type, attrs) VALUES (?, ?, ?, ?)').run(source, target, type, JSON.stringify(attrs ?? {}));
+        this.withBusyContext('adding an edge', () => this.db.transaction(() => {
+            this.upsertNode(source);
+            this.upsertNode(target);
+            this.db.prepare(`INSERT INTO edges (source, target, edge_type, attrs) VALUES (?, ?, ?, ?)
+         ON CONFLICT(source, target, edge_type) DO UPDATE SET attrs = excluded.attrs`).run(source, target, type, JSON.stringify(attrs ?? {}));
+        })());
     }
     // --- Query ---
     hasNode(id) {
@@ -98,6 +133,21 @@ export class SqliteGraphBackend {
     nodes() {
         return this.db.prepare('SELECT id FROM nodes').all().map((r) => r.id);
     }
+    queryNodes(filters) {
+        const clauses = [];
+        const values = [];
+        if (filters.type !== undefined) {
+            clauses.push('type = ?');
+            values.push(filters.type);
+        }
+        if (filters.phase !== undefined) {
+            clauses.push('phase = ?');
+            values.push(filters.phase);
+        }
+        const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+        return this.db.prepare(`SELECT id FROM nodes ${where} ORDER BY id`).all(...values)
+            .map((row) => row.id);
+    }
     // --- Traversal ---
     neighbors(nodeId, direction, edgeType) {
         const results = new Set();
@@ -127,15 +177,37 @@ export class SqliteGraphBackend {
     intersection(setA, setB) {
         if (setA.length === 0 || setB.length === 0)
             return [];
-        const b = new Set(setB);
-        return setA.filter(x => b.has(x));
+        return this.sqlSetOperation(setA, setB, 'INTERSECT');
     }
     difference(setA, setB) {
-        const b = new Set(setB);
-        return setA.filter(x => !b.has(x));
+        if (setA.length === 0)
+            return [];
+        return this.sqlSetOperation(setA, setB, 'EXCEPT');
     }
     union(setA, setB) {
-        return [...new Set([...setA, ...setB])];
+        return this.sqlSetOperation(setA, setB, 'UNION');
+    }
+    /** Bounded recursive traversal with deterministic ordering and optional edge filtering. */
+    traverse(nodeId, direction, maxDepth, edgeType) {
+        if (!Number.isInteger(maxDepth) || maxDepth < 1 || maxDepth > 100) {
+            throw new Error('sqlite traversal maxDepth must be an integer from 1 through 100');
+        }
+        const from = direction === 'out' ? 'source' : 'target';
+        const to = direction === 'out' ? 'target' : 'source';
+        const rows = this.db.prepare(`
+      WITH RECURSIVE walk(id, depth, visited) AS (
+        SELECT ?, 0, char(31) || ? || char(31)
+        UNION ALL
+        SELECT e.${to}, walk.depth + 1, walk.visited || e.${to} || char(31)
+        FROM walk JOIN edges e ON e.${from} = walk.id
+        WHERE walk.depth < ?
+          AND (? IS NULL OR e.edge_type = ?)
+          AND instr(walk.visited, char(31) || e.${to} || char(31)) = 0
+      )
+      SELECT id, MIN(depth) AS depth FROM walk WHERE depth > 0
+      GROUP BY id ORDER BY depth, id
+    `).all(nodeId, nodeId, maxDepth, edgeType ?? null, edgeType ?? null);
+        return rows.map((row) => row);
     }
     // --- Persistence ---
     serialize() {
@@ -156,13 +228,18 @@ export class SqliteGraphBackend {
         return result;
     }
     deserialize(data) {
-        // Clear existing data
-        this.db.exec('DELETE FROM edges; DELETE FROM nodes;');
+        this.reconcile(data);
+    }
+    /** Transactionally applies a full desired graph and removes stale rows. */
+    reconcile(data) {
         const insertNode = this.db.prepare('INSERT OR IGNORE INTO nodes (id) VALUES (?)');
         const insertEdge = this.db.prepare('INSERT OR IGNORE INTO edges (source, target, edge_type) VALUES (?, ?, ?)');
         const runBatch = this.db.transaction(() => {
+            const desiredNodes = new Set();
+            const desiredEdges = new Set();
             // Add all nodes
             for (const id of Object.keys(data)) {
+                desiredNodes.add(id);
                 insertNode.run(id);
             }
             // Add edges from upstream relationships
@@ -170,16 +247,53 @@ export class SqliteGraphBackend {
                 const upEdges = normalizeEdges(node.upstream);
                 for (const edge of upEdges) {
                     insertNode.run(edge.path); // Ensure referenced nodes exist
+                    desiredNodes.add(edge.path);
+                    desiredEdges.add(`${edge.path}\0${id}\0${edge.type}`);
                     insertEdge.run(edge.path, id, edge.type);
                 }
                 const downEdges = normalizeEdges(node.downstream);
                 for (const edge of downEdges) {
                     insertNode.run(edge.path);
+                    desiredNodes.add(edge.path);
+                    desiredEdges.add(`${id}\0${edge.path}\0${edge.type}`);
                     insertEdge.run(id, edge.path, edge.type);
                 }
             }
+            for (const edge of this.db.prepare('SELECT source, target, edge_type FROM edges').all()) {
+                if (!desiredEdges.has(`${edge.source}\0${edge.target}\0${edge.edge_type}`)) {
+                    this.db.prepare('DELETE FROM edges WHERE source=? AND target=? AND edge_type=?')
+                        .run(edge.source, edge.target, edge.edge_type);
+                }
+            }
+            for (const { id } of this.db.prepare('SELECT id FROM nodes').all()) {
+                if (!desiredNodes.has(id))
+                    this.db.prepare('DELETE FROM nodes WHERE id=?').run(id);
+            }
         });
-        runBatch();
+        this.withBusyContext('reconciling graph rows', runBatch);
+    }
+    schemaVersion() {
+        return Number(this.db.pragma('user_version', { simple: true }));
+    }
+    engineVersion() {
+        return String(this.db.prepare('SELECT sqlite_version() AS version').get().version);
+    }
+    journalMode() {
+        return String(this.db.pragma('journal_mode', { simple: true })).toLowerCase();
+    }
+    walMetrics() {
+        const row = this.db.pragma('wal_checkpoint(NOOP)')[0] ?? {};
+        return {
+            busy: Number(row.busy ?? 0),
+            logFrames: Number(row.log ?? 0),
+            checkpointedFrames: Number(row.checkpointed ?? 0),
+        };
+    }
+    checkpoint(mode = 'PASSIVE') {
+        this.withBusyContext('checkpointing the WAL', () => this.db.pragma(`wal_checkpoint(${mode})`));
+    }
+    async backup(destination) {
+        await this.db.backup(destination);
     }
     nodeCount() {
         return this.db.prepare('SELECT COUNT(*) as c FROM nodes').get().c;
@@ -194,5 +308,67 @@ export class SqliteGraphBackend {
     close() {
         this.db.close();
     }
+    upsertNode(id, attrs) {
+        const existing = this.db.prepare('SELECT attrs FROM nodes WHERE id = ?').get(id);
+        const merged = { ...(existing ? JSON.parse(existing.attrs) : {}), ...(attrs ?? {}) };
+        this.db.prepare(`
+      INSERT INTO nodes (id, type, phase, title, summary, checksum, attrs)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        type=excluded.type, phase=excluded.phase, title=excluded.title,
+        summary=excluded.summary, checksum=excluded.checksum, attrs=excluded.attrs
+    `).run(id, stringAttr(merged, 'type'), stringAttr(merged, 'phase'), stringAttr(merged, 'title'), stringAttr(merged, 'summary'), stringAttr(merged, 'checksum'), JSON.stringify(merged));
+    }
+    sqlSetOperation(setA, setB, operation) {
+        const rows = this.db.prepare(`
+      SELECT value AS id FROM json_each(?)
+      ${operation}
+      SELECT value AS id FROM json_each(?)
+      ORDER BY id
+    `).all(JSON.stringify(setA), JSON.stringify(setB));
+        return rows.map((row) => row.id);
+    }
+    withBusyContext(operation, fn) {
+        const deadline = Date.now() + this.busyTimeoutMs;
+        let backoffMs = 2;
+        for (;;) {
+            try {
+                return fn();
+            }
+            catch (error) {
+                const code = error.code;
+                if (!code?.startsWith('SQLITE_BUSY') && !code?.startsWith('SQLITE_LOCKED'))
+                    throw error;
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    throw new SqliteBusyError(operation, error);
+                const delay = Math.min(backoffMs, remaining, 100);
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay);
+                backoffMs = Math.min(backoffMs * 2, 100);
+            }
+        }
+    }
+}
+function stringAttr(attrs, key) {
+    return typeof attrs[key] === 'string' ? attrs[key] : null;
+}
+export function isWalResetSafeVersion(version) {
+    const parts = version.split('.').map(Number);
+    if (parts.length !== 3 || parts.some(part => !Number.isInteger(part) || part < 0))
+        return false;
+    const [major, minor, patch] = parts;
+    if (major !== 3)
+        return major > 3;
+    if (minor === 44)
+        return patch >= 6;
+    if (minor === 50)
+        return patch >= 7;
+    if (minor < 51)
+        return false;
+    if (minor === 51)
+        return patch >= 3;
+    if (minor === 52)
+        return false; // withdrawn upstream
+    return minor >= 53;
 }
 //# sourceMappingURL=sqlite-backend.js.map

package/dist/src/artifacts/dep-graph.js

@@ -9,8 +9,9 @@
  * @tests @test/unit/artifacts/dep-graph.test.ts
  */
 import { normalizeEdges } from './types.js';
-import { loadDependencyGraph, loadGraphIndexFile } from './index-reader.js';
+import { loadDependencyGraph } from './index-reader.js';
 import { buildFortemiCoreDependencyGraph } from './fortemi-core-query-adapter.js';
+import { closeGraphBackend, openGraphBackend } from './backend-runtime.js';
 /**
  * Traverse the dependency graph in one direction
  *
@@ -70,6 +71,7 @@ function flattenResults(results) {
 export async function showDeps(cwd, artifactPath, options = {}) {
     const { direction = 'both', depth = 3, json = false, graph: graphType, edgeType, backend = 'fortemi-core' } = options;
     let depGraph = null;
+    let graphBackend;
     if (backend === 'fortemi-core') {
         const loaded = buildFortemiCoreDependencyGraph(cwd, graphType ?? 'project');
         if (!loaded.graph) {
@@ -86,7 +88,14 @@ export async function showDeps(cwd, artifactPath, options = {}) {
         depGraph = loaded.graph;
     }
     else if (graphType) {
-        depGraph = loadGraphIndexFile(cwd, 'dependencies.json', graphType);
+        const active = await openGraphBackend(cwd, graphType);
+        graphBackend = active.type;
+        try {
+            depGraph = active.backend.serialize();
+        }
+        finally {
+            await closeGraphBackend(active);
+        }
         if (!depGraph) {
             console.error(`Error: No artifact index found for graph '${graphType}'.`);
             console.log("Run 'aiwg index build' first to create the index.");
@@ -98,9 +107,21 @@ export async function showDeps(cwd, artifactPath, options = {}) {
         const graphTypes = ['project', 'codebase'];
         const merged = {};
         for (const g of graphTypes) {
-            const partial = loadGraphIndexFile(cwd, 'dependencies.json', g);
-            if (partial)
-                Object.assign(merged, partial);
+            try {
+                const active = await openGraphBackend(cwd, g);
+                try {
+                    Object.assign(merged, active.backend.serialize());
+                }
+                finally {
+                    await closeGraphBackend(active);
+                }
+            }
+            catch (error) {
+                // Missing optional graph data is ignorable; unavailable configured
+                // backends are actionable and must not silently fall back to JSON.
+                if (error.message.includes('backend is unavailable'))
+                    throw error;
+            }
         }
         if (Object.keys(merged).length > 0) {
             depGraph = merged;
@@ -132,6 +153,7 @@ export async function showDeps(cwd, artifactPath, options = {}) {
         console.log(JSON.stringify({
             artifact: artifactPath,
             backend,
+            ...(graphBackend ? { graphBackend } : {}),
             direction,
             depth,
             upstream: flattenResults(upstreamResults),

package/dist/src/artifacts/graph-backend.js

@@ -20,7 +20,7 @@
  * @returns A new GraphBackend instance
  * @throws Error if the requested backend's dependencies are not installed
  */
-export async function createGraphBackend(type = 'json') {
+export async function createGraphBackend(type = 'json', persistentPath) {
     switch (type) {
         case 'json': {
             const { JsonGraphBackend } = await import('./backends/json-backend.js');
@@ -38,7 +38,7 @@ export async function createGraphBackend(type = 'json') {
         case 'sqlite': {
             try {
                 const { SqliteGraphBackend } = await import('./backends/sqlite-backend.js');
-                return new SqliteGraphBackend();
+                return new SqliteGraphBackend(persistentPath);
             }
             catch {
                 throw new Error('sqlite backend is unavailable; run `aiwg features install sqlite`');

package/dist/src/artifacts/graph-query.js

@@ -9,8 +9,8 @@
  * @tests @test/unit/artifacts/graph-query.test.ts
  */
 import { normalizeEdges } from './types.js';
-import { loadGraphIndexFile } from './index-reader.js';
 import { buildFortemiCoreDependencyGraph } from './fortemi-core-query-adapter.js';
+import { closeGraphBackend, openGraphBackend } from './backend-runtime.js';
 /**
  * Get neighbors of a node in a dependency graph.
  *
@@ -84,18 +84,13 @@ export function setDifference(a, b) {
     const setB = new Set(b);
     return a.filter(x => !setB.has(x));
 }
-/**
- * Load a dependency graph for a given graph type
- */
-function loadGraph(cwd, graphType) {
-    return loadGraphIndexFile(cwd, 'dependencies.json', graphType);
-}
 /**
  * Execute the `neighbors` subcommand
  */
 export async function showNeighbors(cwd, options) {
     const { graph: graphType, node, direction = 'both', edgeType, json = false, backend = 'fortemi-core' } = options;
     let graph = null;
+    let graphBackend;
     if (backend === 'fortemi-core') {
         const loaded = buildFortemiCoreDependencyGraph(cwd, graphType);
         if (!loaded.graph) {
@@ -112,7 +107,14 @@ export async function showNeighbors(cwd, options) {
         graph = loaded.graph;
     }
     else {
-        graph = loadGraph(cwd, graphType);
+        const active = await openGraphBackend(cwd, graphType);
+        graphBackend = active.type;
+        try {
+            graph = active.backend.serialize();
+        }
+        finally {
+            await closeGraphBackend(active);
+        }
     }
     if (!graph) {
         console.error(`Error: No index found for graph '${graphType}'.`);
@@ -137,6 +139,7 @@ export async function showNeighbors(cwd, options) {
         console.log(JSON.stringify({
             graph: graphType,
             backend,
+            ...(graphBackend ? { graphBackend } : {}),
             node: resolved,
             direction,
             edgeType: edgeType ?? null,
@@ -165,6 +168,7 @@ export async function showNeighbors(cwd, options) {
 export async function executeSetQuery(cwd, options) {
     const { graph: graphType, op, nodeA, nodeB, direction = 'in', edgeType, json = false, backend = 'fortemi-core' } = options;
     let graph = null;
+    let graphBackend;
     if (backend === 'fortemi-core') {
         const loaded = buildFortemiCoreDependencyGraph(cwd, graphType);
         if (!loaded.graph) {
@@ -181,7 +185,14 @@ export async function executeSetQuery(cwd, options) {
         graph = loaded.graph;
     }
     else {
-        graph = loadGraph(cwd, graphType);
+        const active = await openGraphBackend(cwd, graphType);
+        graphBackend = active.type;
+        try {
+            graph = active.backend.serialize();
+        }
+        finally {
+            await closeGraphBackend(active);
+        }
     }
     if (!graph) {
         console.error(`Error: No index found for graph '${graphType}'.`);
@@ -215,6 +226,7 @@ export async function executeSetQuery(cwd, options) {
         console.log(JSON.stringify({
             graph: graphType,
             backend,
+            ...(graphBackend ? { graphBackend } : {}),
             op,
             nodeA: resolvedA,
             nodeB: resolvedB,

package/dist/src/artifacts/index-builder.js

@@ -1077,6 +1077,20 @@ export async function buildIndex(cwd, options = {}) {
     writeIndexFile(effectiveOutputCwd, 'metadata.json', index, indexOutputDir);
     writeIndexFile(effectiveOutputCwd, 'tags.json', tagIndex, indexOutputDir);
     writeIndexFile(effectiveOutputCwd, 'dependencies.json', depGraph, indexOutputDir);
+    // Materialize the configured backend and always retain dependencies.json as
+    // the stable compatibility/export contract.
+    const { createGraphBackend } = await import('./graph-backend.js');
+    const { resolveGraphBackendType } = await import('./types.js');
+    const backendType = resolveGraphBackendType(graph);
+    const persistentPath = backendType === 'sqlite' ? path.join(indexOutputDir, 'graph.db') : undefined;
+    let selectedBackend;
+    try {
+        selectedBackend = await createGraphBackend(backendType, persistentPath);
+        selectedBackend.deserialize(depGraph);
+    }
+    finally {
+        await selectedBackend?.close?.();
+    }
     // Update and persist the checksum manifest for faster future builds (#794).
     // The next manifest contains entries for every file we processed this build.
     // Files that disappeared from disk are pruned; the resulting manifest is
@@ -1118,6 +1132,7 @@ export async function buildIndex(cwd, options = {}) {
         byType,
         tagDistribution: tagDist,
         graphMetrics: {
+            backend: backendType,
             totalEdges,
             markdownLinkEdges: markdownLinkEdgeCount,
             ...(citationMetrics ? {

package/dist/src/artifacts/index-status.js

@@ -18,7 +18,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { GRAPH_CONFIGS, BUILTIN_GRAPH_CONFIGS, getGraphIndexDir, getProjectIndexRoot, loadGlobalGraphConfigs, loadUserGraphConfigs, } from './types.js';
+import { GRAPH_CONFIGS, BUILTIN_GRAPH_CONFIGS, getGraphIndexDir, getProjectIndexRoot, loadGlobalGraphConfigs, loadUserGraphConfigs, resolveGraphBackendType, } from './types.js';
 import { getFortemiCoreSyncStatus, } from './fortemi-core-sync.js';
 function readBuiltMeta(indexDir) {
     try {
@@ -62,6 +62,7 @@ export function collectIndexStatus(cwd, nowMs) {
         }
         graphs.push({
             name,
+            backend: resolveGraphBackendType(name),
             origin: name in BUILTIN_GRAPH_CONFIGS ? 'builtin' : 'registered',
             shared: config.shared,
             defaultBuild: config.defaultBuild,
@@ -131,6 +132,7 @@ export async function showIndexStatus(cwd, opts = {}) {
         'GRAPH'.padEnd(22) +
         'ORIGIN'.padEnd(12) +
         'STATE'.padEnd(10) +
+        'BACKEND'.padEnd(12) +
         'ENTRIES'.padEnd(9) +
         'AGE'.padEnd(10) +
         'LOCATION');
@@ -145,6 +147,7 @@ export async function showIndexStatus(cwd, opts = {}) {
             g.name.padEnd(22) +
             g.origin.padEnd(12) +
             state.padEnd(10) +
+            g.backend.padEnd(12) +
             String(g.entries ?? '—').padEnd(9) +
             age.padEnd(10) +
             shortenPath(g.location, cwd));

package/dist/src/artifacts/stats.js

@@ -7,7 +7,7 @@
  * @source @src/artifacts/types.ts
  * @tests @test/unit/artifacts/stats.test.ts
  */
-import { GRAPH_CONFIGS, loadGlobalGraphConfigs, loadUserGraphConfigs } from './types.js';
+import { GRAPH_CONFIGS, loadGlobalGraphConfigs, loadUserGraphConfigs, resolveGraphBackendType } from './types.js';
 import { loadIndexStats, loadGraphIndexFile } from './index-reader.js';
 import { collectGraphIndexFiles, indexPathFor } from './index-files.js';
 /** Calculate coverage over the same current file set used by the index builder. */
@@ -71,6 +71,7 @@ export async function showStats(cwd, options = {}) {
             const coverage = await calculateCoverage(cwd, s, type);
             combined[type] = {
                 ...s,
+                backend: resolveGraphBackendType(type),
                 coverage,
             };
         }
@@ -91,6 +92,7 @@ async function renderStats(cwd, stats, options, graphType) {
         const coverage = await calculateCoverage(cwd, stats, graphType);
         console.log(JSON.stringify({
             ...stats,
+            backend: resolveGraphBackendType(graphType),
             coverage,
         }, null, 2));
         return;
@@ -101,6 +103,7 @@ async function renderStats(cwd, stats, options, graphType) {
     console.log(`Index version: ${stats.version}`);
     console.log(`Last built:    ${stats.builtAt}`);
     console.log(`Build time:    ${stats.buildTimeMs}ms`);
+    console.log(`Graph backend: ${resolveGraphBackendType(graphType)}`);
     console.log('');
     // By phase
     console.log('Artifacts by Phase:');