@opensip-cli/graph 0.1.0

package/dist/persistence/catalog-repo.js

@@ -0,0 +1,229 @@
+/**
+ * CatalogRepo — SQLite-backed graph catalog at parity with v1's
+ * single-JSON-file shape.
+ *
+ * v1 stored the catalog as `<runtime>/cache/graph/catalog.json`. v2
+ * stores it in `graph_catalog` row 1, lifting the cache-validity
+ * fields (language, cacheKey, filesFingerprint) into typed columns so
+ * the orchestrator can fingerprint-mismatch without parsing the full
+ * payload. The catalog perf follow-up plan normalizes the payload
+ * into per-function/occurrence/edge tables and pushes dashboard view
+ * derivations into SQL.
+ */
+import { logger } from '@opensip-cli/core';
+import { requireDrizzleDataStore, } from '@opensip-cli/datastore';
+import { sql } from 'drizzle-orm';
+import { graphCatalog, graphShardFragment } from './schema.js';
+const MODULE_NAME = 'graph:catalog-repo';
+/**
+ * SQLite/Drizzle-backed repository for the graph catalog and its per-shard
+ * fragments. Owns the `graph_catalog` row plus the `graph_shard_fragment`
+ * table; all reads/writes are synchronous (better-sqlite3). The orchestrator
+ * uses it to persist whole catalogs and incremental shard fragments, and to
+ * fingerprint-match for cache validity without parsing the full payload.
+ */
+export class CatalogRepo {
+    datastore;
+    constructor(datastore) {
+        this.datastore = requireDrizzleDataStore(datastore);
+    }
+    /**
+     * Replace the catalog with a fresh value. Mirrors v1's atomic
+     * tmp-file + rename write — the upsert is a single statement, and
+     * SQLite's transaction semantics guarantee no torn reads.
+     */
+    replaceAll(catalog) {
+        try {
+            const filesFingerprint = catalog.filesFingerprint ?? '';
+            const payload = {
+                version: catalog.version,
+                tool: catalog.tool,
+                language: catalog.language,
+                builtAt: catalog.builtAt,
+                cacheKey: catalog.cacheKey,
+                filesFingerprint: catalog.filesFingerprint,
+                resolutionMode: catalog.resolutionMode,
+                functions: catalog.functions,
+                // Carries through whatever the caller attached; `undefined` when none
+                // (a lean run) so the key is omitted from the persisted JSON.
+                reExports: catalog.reExports,
+                features: catalog.features,
+            };
+            this.datastore.db
+                .insert(graphCatalog)
+                .values({
+                id: 1,
+                language: catalog.language,
+                cacheKey: catalog.cacheKey,
+                filesFingerprint,
+                builtAt: catalog.builtAt,
+                payload,
+            })
+                .onConflictDoUpdate({
+                target: graphCatalog.id,
+                set: {
+                    language: sql `excluded.language`,
+                    cacheKey: sql `excluded.cache_key`,
+                    filesFingerprint: sql `excluded.files_fingerprint`,
+                    builtAt: sql `excluded.built_at`,
+                    payload: sql `excluded.payload`,
+                },
+            })
+                .run();
+            logger.info({
+                evt: 'graph.catalog.write.complete',
+                module: MODULE_NAME,
+                msg: 'Catalog written',
+                functions: Object.keys(catalog.functions).length,
+            });
+        }
+        catch (error) {
+            /* v8 ignore start */
+            logger.error({
+                evt: 'graph.catalog.write.error',
+                module: MODULE_NAME,
+                msg: 'Failed to write catalog',
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+            /* v8 ignore stop */
+        }
+    }
+    /**
+     * Load the full catalog. Returns `null` on cache miss (no row).
+     * Reconstructs the legacy `Catalog` shape from the JSON payload at
+     * parity — view derivations under
+     * `packages/contracts/src/persistence/dashboard/code-paths/` consume
+     * the same shape they always have.
+     */
+    loadFullCatalog() {
+        try {
+            const row = this.datastore.db
+                .select()
+                .from(graphCatalog)
+                .where(sql `id = 1`)
+                .get();
+            if (!row) {
+                logger.info({
+                    evt: 'graph.catalog.read.miss',
+                    module: MODULE_NAME,
+                    reason: 'empty-catalog',
+                });
+                return null;
+            }
+            const payload = row.payload;
+            logger.info({
+                evt: 'graph.catalog.read.hit',
+                module: MODULE_NAME,
+                functions: Object.keys(payload.functions).length,
+            });
+            return {
+                version: payload.version,
+                tool: payload.tool,
+                language: payload.language,
+                builtAt: payload.builtAt,
+                cacheKey: payload.cacheKey,
+                filesFingerprint: payload.filesFingerprint,
+                resolutionMode: payload.resolutionMode,
+                functions: payload.functions,
+                reExports: payload.reExports,
+                features: payload.features,
+            };
+        }
+        catch (error) {
+            /* v8 ignore start */
+            logger.error({
+                evt: 'graph.catalog.read.error',
+                module: MODULE_NAME,
+                msg: 'Failed to read catalog',
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+            /* v8 ignore stop */
+        }
+    }
+    /**
+     * Read the catalog as the cross-tool {@link GraphCatalog} contract —
+     * the shape the report renderer and graph contribution depend on.
+     * This is the supported cross-tool read path: it lets fitness drop its
+     * raw-SQL `SELECT … FROM graph_catalog` (audit 2026-05-29, H1). The
+     * internal `Catalog` is structurally assignable to the GraphCatalog
+     * contract, so this is a plain widening — no cast — verified by the
+     * compiler at this boundary, where graph owns both types.
+     */
+    loadCatalogContract() {
+        return this.loadFullCatalog();
+    }
+    /**
+     * True iff a catalog row exists. Used by the orchestrator to short-
+     * circuit fingerprint mismatch checks when nothing is cached.
+     */
+    hasAnyCatalog() {
+        const row = this.datastore.db.select({ id: graphCatalog.id }).from(graphCatalog).limit(1).get();
+        return row !== undefined;
+    }
+    // ── Per-shard fragment cache (plan #2 — sharded build) ──────────
+    /**
+     * Persist one shard's `ShardBuildResult`, replacing any prior row for
+     * the same shard id. The validity keys (`cache_key`, `shard_fingerprint`)
+     * are lifted from the result so a reuse check needs no payload parse.
+     */
+    upsertShardFragment(result) {
+        this.datastore.db
+            .insert(graphShardFragment)
+            .values({
+            shardId: result.shardId,
+            language: result.fragment.language,
+            cacheKey: result.fragment.cacheKey,
+            shardFingerprint: result.fingerprint,
+            payload: result,
+        })
+            .onConflictDoUpdate({
+            target: graphShardFragment.shardId,
+            set: {
+                language: sql `excluded.language`,
+                cacheKey: sql `excluded.cache_key`,
+                shardFingerprint: sql `excluded.shard_fingerprint`,
+                payload: sql `excluded.payload`,
+            },
+        })
+            .run();
+    }
+    /**
+     * Load a shard fragment ONLY if it is still valid — both the shard's
+     * cache key (tsconfig/version/mode) and its files fingerprint must match
+     * the current run. Returns `null` on miss or staleness, signalling the
+     * orchestrator to re-run that shard's worker. No parse happens here
+     * beyond the JSON payload of a single valid shard.
+     */
+    loadValidShardFragment(shardId, expectedCacheKey, expectedFingerprint) {
+        const row = this.datastore.db
+            .select()
+            .from(graphShardFragment)
+            .where(sql `shard_id = ${shardId}`)
+            .get();
+        if (!row)
+            return null;
+        if (row.cacheKey !== expectedCacheKey || row.shardFingerprint !== expectedFingerprint) {
+            return null;
+        }
+        return row.payload;
+    }
+    /**
+     * Drop fragment rows for shards no longer present in the current build
+     * (e.g. a package was removed). Keeps the per-shard cache from
+     * accumulating stale rows. No-op when `keepShardIds` is empty.
+     */
+    pruneShardFragmentsExcept(keepShardIds) {
+        if (keepShardIds.length === 0)
+            return;
+        const separator = sql `, `;
+        const placeholders = keepShardIds.map((id) => sql `${id}`);
+        const keepList = sql.join(placeholders, separator);
+        this.datastore.db
+            .delete(graphShardFragment)
+            .where(sql `shard_id NOT IN (${keepList})`)
+            .run();
+    }
+}
+//# sourceMappingURL=catalog-repo.js.map

package/dist/persistence/catalog-repo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-repo.js","sourceRoot":"","sources":["../../src/persistence/catalog-repo.ts"],"names":[],"mappings":"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"}

package/dist/persistence/schema.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Catalog single-row store (id = 1).
+ *
+ * v1 stored the full Catalog object as a streamed JSON file at
+ * `paths.graphCatalogPath`. v2 stores it as one row whose `payload`
+ * column holds the same JSON, with the metadata fields (language,
+ * cache_key, files_fingerprint, built_at) lifted out for cheap
+ * fingerprint-mismatch checks without parsing the full payload.
+ *
+ * The catalog payload remains a single document at parity. The
+ * follow-up `graph-catalog-perf` plan normalizes this into per-
+ * function / per-occurrence / per-edge tables and pushes view
+ * derivations down into SQL.
+ */
+export declare const graphCatalog: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "graph_catalog";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "graph_catalog";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        language: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "language";
+            tableName: "graph_catalog";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        cacheKey: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "cache_key";
+            tableName: "graph_catalog";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        filesFingerprint: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "files_fingerprint";
+            tableName: "graph_catalog";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        builtAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "built_at";
+            tableName: "graph_catalog";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        payload: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "payload";
+            tableName: "graph_catalog";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: unknown;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;
+/**
+ * Per-shard catalog fragment store (plan #2 — sharded build).
+ *
+ * One row per shard (keyed by `shard_id`), holding that shard's
+ * serialized `ShardBuildResult` (fragment + boundary calls + parse
+ * errors). A fragment is valid for incremental reuse only when BOTH its
+ * `cache_key` (the shard's tsconfig/version/mode key) and its
+ * `shard_fingerprint` (mtime+size over the shard's files) match the
+ * current run — the same validity discipline as the full-catalog path.
+ * On a rebuild, shards whose fingerprint matches load their fragment with
+ * no parse; only changed shards re-run a worker.
+ *
+ * Schema note (flagged in the plan for a data-layer pass): this is a
+ * draft — table-vs-column, stale-row retention, and a build-scoped sweep
+ * are deferred. Replacement is per-shard upsert; stale rows for shards no
+ * longer present are pruned by the orchestrator after a build.
+ */
+export declare const graphShardFragment: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "graph_shard_fragment";
+    schema: undefined;
+    columns: {
+        shardId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "shard_id";
+            tableName: "graph_shard_fragment";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        language: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "language";
+            tableName: "graph_shard_fragment";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        cacheKey: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "cache_key";
+            tableName: "graph_shard_fragment";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        shardFingerprint: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "shard_fingerprint";
+            tableName: "graph_shard_fragment";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        payload: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "payload";
+            tableName: "graph_shard_fragment";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: unknown;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/persistence/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/persistence/schema.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAOvB,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAM7B,CAAC"}

package/dist/persistence/schema.js

@@ -0,0 +1,53 @@
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+// ADR-0036: the graph baseline tables (`graph_baseline_signals` /
+// `graph_baseline_meta`) moved to the generic host-owned `tool_baseline_entries`
+// / `tool_baseline_meta` pair in `@opensip-cli/datastore`. The DROP migration
+// for the old tables is generated in this plan's P4 (one migration drops all three
+// per-tool baseline tables at once, after fitness also re-points).
+/**
+ * Catalog single-row store (id = 1).
+ *
+ * v1 stored the full Catalog object as a streamed JSON file at
+ * `paths.graphCatalogPath`. v2 stores it as one row whose `payload`
+ * column holds the same JSON, with the metadata fields (language,
+ * cache_key, files_fingerprint, built_at) lifted out for cheap
+ * fingerprint-mismatch checks without parsing the full payload.
+ *
+ * The catalog payload remains a single document at parity. The
+ * follow-up `graph-catalog-perf` plan normalizes this into per-
+ * function / per-occurrence / per-edge tables and pushes view
+ * derivations down into SQL.
+ */
+export const graphCatalog = sqliteTable('graph_catalog', {
+    id: integer('id').primaryKey(),
+    language: text('language').notNull(),
+    cacheKey: text('cache_key').notNull(),
+    filesFingerprint: text('files_fingerprint').notNull(),
+    builtAt: text('built_at').notNull(),
+    payload: text('payload', { mode: 'json' }).notNull(),
+});
+/**
+ * Per-shard catalog fragment store (plan #2 — sharded build).
+ *
+ * One row per shard (keyed by `shard_id`), holding that shard's
+ * serialized `ShardBuildResult` (fragment + boundary calls + parse
+ * errors). A fragment is valid for incremental reuse only when BOTH its
+ * `cache_key` (the shard's tsconfig/version/mode key) and its
+ * `shard_fingerprint` (mtime+size over the shard's files) match the
+ * current run — the same validity discipline as the full-catalog path.
+ * On a rebuild, shards whose fingerprint matches load their fragment with
+ * no parse; only changed shards re-run a worker.
+ *
+ * Schema note (flagged in the plan for a data-layer pass): this is a
+ * draft — table-vs-column, stale-row retention, and a build-scoped sweep
+ * are deferred. Replacement is per-shard upsert; stale rows for shards no
+ * longer present are pruned by the orchestrator after a build.
+ */
+export const graphShardFragment = sqliteTable('graph_shard_fragment', {
+    shardId: text('shard_id').primaryKey(),
+    language: text('language').notNull(),
+    cacheKey: text('cache_key').notNull(),
+    shardFingerprint: text('shard_fingerprint').notNull(),
+    payload: text('payload', { mode: 'json' }).notNull(),
+});
+//# sourceMappingURL=schema.js.map

package/dist/persistence/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/persistence/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAErE,kEAAkE;AAClE,iFAAiF;AACjF,8EAA8E;AAC9E,mFAAmF;AACnF,mEAAmE;AAEnE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC,eAAe,EAAE;IACvD,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC9B,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE;IACpC,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE;IACrC,gBAAgB,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC,OAAO,EAAE;IACrD,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE;IACnC,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;CACrD,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAAC,sBAAsB,EAAE;IACpE,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,UAAU,EAAE;IACtC,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE;IACpC,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE;IACrC,gBAAgB,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC,OAAO,EAAE;IACrD,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;CACrD,CAAC,CAAC"}

package/dist/persistence/session-payload.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Graph-owned session payload (audit 2026-05-29, session split; extended
+ * 2026-05-29 to carry per-rule detail for the Code Paths session view;
+ * rebuilt from `Signal[]` directly in ADR-0011 Phase 5 — no `CliOutput`).
+ *
+ * `contracts` stores per-session detail as an opaque JSON blob and holds
+ * zero tool vocabulary. Graph owns its own payload shape here, derived
+ * straight from the run's `Signal[]`. The Code Paths → Sessions subtab
+ * renders a per-rule detail panel, so the payload carries rule-grouped
+ * detail (`summary` + `checks[]` of rule-grouped findings).
+ *
+ * The detail shape (`summary` + `checks[]` of rule-grouped findings) is the
+ * dashboard's structural session-detail contract, consumed by the shared
+ * `renderDetail` in @opensip-cli/dashboard. These types are graph-local
+ * structural mirrors (not the retired `contracts` `CheckOutput`/
+ * `FindingOutput`): the dashboard reads `checkSlug`/`passed`/`durationMs` and
+ * each finding's `severity`/`message`/`filePath`/`line`/`suggestion`/`metadata`
+ * structurally.
+ *
+ * Rule-ID vocabulary: `checkSlug` is the ENGINE slug (`graph:<rule>`), NOT the
+ * OpenSIP-mapped rule ID the envelope/SARIF surfaces use. The dashboard's
+ * per-rule metric columns (`RULE_METRIC_COLUMNS`) are keyed on engine slugs,
+ * so the session detail stays in engine vocabulary (built upstream of the
+ * envelope's Option-A remap).
+ */
+import type { Signal } from '@opensip-cli/core';
+/** Two-level severity the dashboard buckets on (`critical|high → error`). */
+export type GraphFindingSeverity = 'error' | 'warning';
+/** JSON-safe scalar — the metadata-value subset the persisted shape permits. */
+export type JsonScalar = string | number | boolean;
+/** A persisted finding row — the structural subset the dashboard renders. */
+export interface GraphSessionFinding {
+    readonly ruleId: string;
+    readonly message: string;
+    readonly severity: GraphFindingSeverity;
+    readonly filePath: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly suggestion?: string;
+    readonly metadata?: Readonly<Record<string, JsonScalar>>;
+}
+/** A persisted per-rule detail row — the structural subset the dashboard renders. */
+export interface GraphSessionCheck {
+    readonly checkSlug: string;
+    readonly passed: boolean;
+    readonly violationCount: number;
+    readonly findings: readonly GraphSessionFinding[];
+    readonly durationMs: number;
+}
+/**
+ * Opaque-to-contracts detail blob written for every `graph` session.
+ *
+ * `checks` is graph's rule-grouped detail: one entry per EVALUATED rule (a rule
+ * that emitted no signal is a PASS with zero findings), each carrying its
+ * findings. The dashboard's shared session-detail renderer reads `summary` and
+ * `checks` structurally.
+ */
+export interface GraphSessionPayload {
+    /** Inner version per the payload schema evolution convention (v1 shape). */
+    readonly __version: 1;
+    readonly summary: {
+        /** Total rules evaluated (one `checks[]` row each; clean rules included). */
+        readonly total: number;
+        /** Rules with no error-severity signal (a clean run = all rules passed). */
+        readonly passed: number;
+        /** Rules with ≥1 error-severity signal. */
+        readonly failed: number;
+        /** Error-severity (critical|high) signal count. */
+        readonly errors: number;
+        /** Warning-severity (medium|low) signal count. */
+        readonly warnings: number;
+    };
+    readonly checks: readonly GraphSessionCheck[];
+}
+/**
+ * Build the graph session payload directly from the run's `Signal[]`.
+ *
+ * Groups by ENGINE `ruleId` into the dashboard's rule-grouped detail
+ * (`checks[]`), collapsing the 4-level signal severity to the dashboard's
+ * two-level `error`/`warning` bucket. Per-rule `passed` follows fit's
+ * semantics (warnings alone do not fail a rule). Persists the full detail
+ * (no cap) — the datastore is a rebuildable local cache.
+ *
+ * `evaluatedRuleSlugs` is the full set of rules the run evaluated (engine
+ * slugs). Every evaluated rule gets a `checks[]` row — a rule that emitted NO
+ * signal is a PASS with zero findings — so a CLEAN run still shows its complete
+ * rule list, exactly the way fitness shows every check (not just the failing
+ * ones). When omitted (e.g. unit tests), only rules that fired are listed,
+ * preserving the prior behaviour.
+ *
+ * @param signals - the run's raw engine signals.
+ * @param evaluatedRuleSlugs - engine slugs of every rule the run evaluated.
+ * @returns the opaque detail blob persisted for this graph session.
+ */
+export declare function buildGraphSessionPayload(signals: readonly Signal[], evaluatedRuleSlugs?: readonly string[]): GraphSessionPayload;
+//# sourceMappingURL=session-payload.d.ts.map

package/dist/persistence/session-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-payload.d.ts","sourceRoot":"","sources":["../../src/persistence/session-payload.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,6EAA6E;AAC7E,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvD,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEnD,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;CAC1D;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE;QAChB,6EAA6E;QAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,4EAA4E;QAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,2CAA2C;QAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,mDAAmD;QACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,kDAAkD;QAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC/C;AAsBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,kBAAkB,GAAE,SAAS,MAAM,EAAO,GACzC,mBAAmB,CAqDrB"}