@opensip-cli/session-store 0.1.0

package/dist/schema/sessions.d.ts

@@ -0,0 +1,419 @@
+/**
+ * Generic tool-run session record. Holds only columns every tool shares;
+ * per-session detail lives in {@link sessionToolPayload}. The persistence
+ * layer holds ZERO tool-specific vocabulary. (Audit 2026-05-29.)
+ */
+export declare const sessions: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "sessions";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "sessions";
+            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;
+        }>;
+        tool: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "tool";
+            tableName: "sessions";
+            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;
+        }>;
+        timestamp: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "timestamp";
+            tableName: "sessions";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timestamp_iso: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "timestamp_iso";
+            tableName: "sessions";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        completed_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "completed_at";
+            tableName: "sessions";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        completed_at_iso: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "completed_at_iso";
+            tableName: "sessions";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        cwd: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "cwd";
+            tableName: "sessions";
+            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;
+        }>;
+        recipe: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "recipe";
+            tableName: "sessions";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        score: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "score";
+            tableName: "sessions";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        passed: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "passed";
+            tableName: "sessions";
+            dataType: "boolean";
+            columnType: "SQLiteBoolean";
+            data: boolean;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        durationMs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "duration_ms";
+            tableName: "sessions";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;
+/**
+ * Sibling host-metrics record (host-owned-run-timing §5.3/§5.4). One row per
+ * session id, holding host-side overhead that is known at different times:
+ * `persistMs` after the session write, `egressMs` after post-run delivery,
+ * etc. Kept separate from the `sessions` row so late-arriving metrics are a
+ * best-effort upsert rather than a row rewrite. Hydrated back onto
+ * `StoredSession.hostMetrics`. All metrics are nullable.
+ */
+export declare const sessionHostMetrics: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "session_host_metrics";
+    schema: undefined;
+    columns: {
+        sessionId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "session_id";
+            tableName: "session_host_metrics";
+            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;
+        }>;
+        ttyBusyMs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "tty_busy_ms";
+            tableName: "session_host_metrics";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        renderMs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "render_ms";
+            tableName: "session_host_metrics";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        persistMs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "persist_ms";
+            tableName: "session_host_metrics";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        egressMs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "egress_ms";
+            tableName: "session_host_metrics";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        totalCommandMs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "total_command_ms";
+            tableName: "session_host_metrics";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;
+/**
+ * Tool-owned opaque per-session detail (audit 2026-05-29, session split).
+ *
+ * One row per session. `payload` is a JSON blob whose shape is owned and
+ * validated by the writing tool — `contracts` treats it as opaque and
+ * holds zero tool-specific (check/finding/summary) vocabulary. The
+ * dashboard, as the presentation owner, reads this payload and renders
+ * it — the same producer/consumer split used for `GraphCatalog`.
+ */
+export declare const sessionToolPayload: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "session_tool_payload";
+    schema: undefined;
+    columns: {
+        sessionId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "session_id";
+            tableName: "session_tool_payload";
+            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;
+        }>;
+        tool: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "tool";
+            tableName: "session_tool_payload";
+            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: "session_tool_payload";
+            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;
+        }, {}, {}>;
+        payload_version: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "payload_version";
+            tableName: "session_tool_payload";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;
+//# sourceMappingURL=sessions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/schema/sessions.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsBpB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS7B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAO7B,CAAC"}

package/dist/schema/sessions.js

@@ -0,0 +1,62 @@
+import { sql } from 'drizzle-orm';
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+/**
+ * Generic tool-run session record. Holds only columns every tool shares;
+ * per-session detail lives in {@link sessionToolPayload}. The persistence
+ * layer holds ZERO tool-specific vocabulary. (Audit 2026-05-29.)
+ */
+export const sessions = sqliteTable('sessions', {
+    id: text('id').primaryKey(),
+    tool: text('tool').notNull(),
+    // `timestamp`/`timestamp_iso` are the run START (host-owned-run-timing
+    // `startedAt`). The physical column names are kept as an internal migration
+    // detail; the exported contract field is `startedAt` (mapped in SessionRepo).
+    timestamp: integer('timestamp').notNull(), // startedAt ms epoch for ordering/index; see timestamp_iso for fidelity
+    timestamp_iso: text('timestamp_iso'), // startedAt original ISO string from host for replay fidelity
+    // Run COMPLETION (host-owned-run-timing `completedAt`). Nullable for
+    // legacy/pre-migration rows; the repo synthesizes startedAt + durationMs on
+    // read when absent. New writes always populate it.
+    completed_at: integer('completed_at'), // completedAt ms epoch
+    completed_at_iso: text('completed_at_iso'), // completedAt original ISO string
+    cwd: text('cwd').notNull(),
+    recipe: text('recipe'),
+    score: integer('score').notNull(),
+    passed: integer('passed', { mode: 'boolean' }).notNull(),
+    durationMs: integer('duration_ms').notNull(),
+}, (table) => [index('sessions_tool_timestamp_idx').on(table.tool, sql `${table.timestamp} DESC`)]);
+/**
+ * Sibling host-metrics record (host-owned-run-timing §5.3/§5.4). One row per
+ * session id, holding host-side overhead that is known at different times:
+ * `persistMs` after the session write, `egressMs` after post-run delivery,
+ * etc. Kept separate from the `sessions` row so late-arriving metrics are a
+ * best-effort upsert rather than a row rewrite. Hydrated back onto
+ * `StoredSession.hostMetrics`. All metrics are nullable.
+ */
+export const sessionHostMetrics = sqliteTable('session_host_metrics', {
+    sessionId: text('session_id')
+        .primaryKey()
+        .references(() => sessions.id, { onDelete: 'cascade' }),
+    ttyBusyMs: integer('tty_busy_ms'),
+    renderMs: integer('render_ms'),
+    persistMs: integer('persist_ms'),
+    egressMs: integer('egress_ms'),
+    totalCommandMs: integer('total_command_ms'),
+});
+/**
+ * Tool-owned opaque per-session detail (audit 2026-05-29, session split).
+ *
+ * One row per session. `payload` is a JSON blob whose shape is owned and
+ * validated by the writing tool — `contracts` treats it as opaque and
+ * holds zero tool-specific (check/finding/summary) vocabulary. The
+ * dashboard, as the presentation owner, reads this payload and renders
+ * it — the same producer/consumer split used for `GraphCatalog`.
+ */
+export const sessionToolPayload = sqliteTable('session_tool_payload', {
+    sessionId: text('session_id')
+        .primaryKey()
+        .references(() => sessions.id, { onDelete: 'cascade' }),
+    tool: text('tool').notNull(),
+    payload: text('payload', { mode: 'json' }).notNull(),
+    payload_version: integer('payload_version').notNull().default(1), // tool-owned payload schema version; future versions may require CLI upgrade to interpret
+});
+//# sourceMappingURL=sessions.js.map

package/dist/schema/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../src/schema/sessions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE5E;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAW,CACjC,UAAU,EACV;IACE,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC3B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE;IAC5B,uEAAuE;IACvE,4EAA4E;IAC5E,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,EAAE,wEAAwE;IACnH,aAAa,EAAE,IAAI,CAAC,eAAe,CAAC,EAAE,8DAA8D;IACpG,qEAAqE;IACrE,4EAA4E;IAC5E,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC,cAAc,CAAC,EAAE,uBAAuB;IAC9D,gBAAgB,EAAE,IAAI,CAAC,kBAAkB,CAAC,EAAE,kCAAkC;IAC9E,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE;IAC1B,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE;IACjC,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;IACxD,UAAU,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE;CAC7C,EACD,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAA,GAAG,KAAK,CAAC,SAAS,OAAO,CAAC,CAAC,CAC/F,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAAC,sBAAsB,EAAE;IACpE,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC;SAC1B,UAAU,EAAE;SACZ,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IACzD,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC;IACjC,QAAQ,EAAE,OAAO,CAAC,WAAW,CAAC;IAC9B,SAAS,EAAE,OAAO,CAAC,YAAY,CAAC;IAChC,QAAQ,EAAE,OAAO,CAAC,WAAW,CAAC;IAC9B,cAAc,EAAE,OAAO,CAAC,kBAAkB,CAAC;CAC5C,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAAC,sBAAsB,EAAE;IACpE,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC;SAC1B,UAAU,EAAE;SACZ,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IACzD,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE;IAC5B,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;IACpD,eAAe,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,0FAA0F;CAC7J,CAAC,CAAC"}

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

@@ -0,0 +1,96 @@
+/**
+ * session-payload-decode — the shared, generic decoder for a stored session's
+ * opaque `payload` blob (the inverse of each tool's `build*SessionPayload`).
+ *
+ * Session replay needs every tool (`fit`/`graph`/`sim`)
+ * to read a persisted session back into a {@link SignalEnvelope} projection. The
+ * persisted detail shares ONE structural shape — `{ summary, checks[] }`, each
+ * check a `{ checkSlug, passed, violationCount?, durationMs, findings[] }` — so
+ * the decode of THAT structure lives here once, parameterised by the few
+ * per-tool differences (error-label, whether `filePath`/`violationCount` are
+ * required, whether findings carry a metadata bag).
+ *
+ * This holds NO tool vocabulary: it does not know about fit checks, graph rules,
+ * severity→category mapping, or signal IDs. Those projections stay in each
+ * engine's `session-replay.ts` (`replaySignal`). What lives here is purely the
+ * structural shape session-store persists — a faithful counterpart to the
+ * package's opaque-payload charter: session-store owns persistence AND the
+ * structural decode for replay, while tool semantics remain in the engines.
+ *
+ * The decoder tolerates legacy payloads that lack a top-level `__version`
+ * (treated as v1 with best-effort projection). Tools should prefer their own
+ * `*ReplayFromSession` functions (which call this decoder) for full projection
+ * to their live result types; this module only gives the common structural
+ * skeleton + the detected `payloadVersion` when present.
+ */
+import type { SignalEnvelope } from '@opensip-cli/contracts';
+/** JSON-safe scalar — the metadata-value subset the persisted shape permits. */
+export type SessionPayloadScalar = string | number | boolean;
+/** A decoded finding row — the structural superset across all tools. */
+export interface DecodedSessionFinding {
+    readonly ruleId: string;
+    readonly message: string;
+    readonly severity: 'error' | 'warning';
+    readonly filePath?: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly suggestion?: string;
+    readonly metadata?: Readonly<Record<string, SessionPayloadScalar>>;
+}
+/** A decoded per-check row. */
+export interface DecodedSessionCheck {
+    readonly checkSlug: string;
+    readonly passed: boolean;
+    readonly violationCount?: number;
+    readonly durationMs: number;
+    readonly findings: readonly DecodedSessionFinding[];
+}
+/** The decoded session payload — `summary` + rule/check-grouped `checks[]`. */
+export interface DecodedSessionPayload {
+    readonly summary: SignalEnvelope['verdict']['summary'];
+    readonly checks: readonly DecodedSessionCheck[];
+    /**
+     * Detected inner `__version` from the opaque tool payload (or undefined for
+     * legacy pre-__version rows, which callers treat as v1 with projection).
+     * This is the value of the top-level numeric key if present and valid.
+     */
+    readonly payloadVersion?: number;
+}
+/** Per-tool decode options — the only points where the tools' payloads differ. */
+export interface DecodeSessionPayloadOptions {
+    /** Tool label used in error messages (e.g. `'fit'`). */
+    readonly tool: string;
+    /** When true, every finding must carry a string `filePath` (graph). */
+    readonly requireFilePath?: boolean;
+    /** When true, every check must carry a numeric `violationCount` (graph/sim). */
+    readonly requireViolationCount?: boolean;
+    /** When true, decode each finding's scalar `metadata` bag (graph). */
+    readonly allowMetadata?: boolean;
+}
+/**
+ * Decode a stored session payload into its structural {@link DecodedSessionPayload}.
+ *
+ * @param payload - the opaque `StoredSession.payload` blob.
+ * @param opts - per-tool decode options (label + required-field toggles).
+ * @returns the decoded `{ summary, checks[] }` structure, plus `payloadVersion`
+ *   (the detected inner `__version` if present and valid; undefined for legacy
+ *   payloads that pre-date the convention — callers treat missing as v1).
+ * @throws {TypeError} when `payload`/`checks`/`findings` are not the expected
+ *   object/array shapes.
+ * @throws {Error} when a required scalar field is missing or mistyped, or a
+ *   finding severity is not `error`/`warning`.
+ */
+export declare function decodeSessionPayload(payload: unknown, opts: DecodeSessionPayloadOptions): DecodedSessionPayload;
+/**
+ * Decode the `summary` verdict-counts block.
+ *
+ * @throws {Error} when the value is missing or any count is not a number.
+ */
+export declare function decodeSummary(value: unknown, label: string): SignalEnvelope['verdict']['summary'];
+/** @throws {Error} when the field is not a number. */
+export declare function numberField(source: Record<string, unknown>, field: string, label: string): number;
+/** @throws {Error} when the field is not a string. */
+export declare function stringField(source: Record<string, unknown>, field: string, label: string): string;
+/** @throws {Error} when the field is not a boolean. */
+export declare function booleanField(source: Record<string, unknown>, field: string, label: string): boolean;
+//# sourceMappingURL=session-payload-decode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-payload-decode.d.ts","sourceRoot":"","sources":["../src/session-payload-decode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,gFAAgF;AAChF,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7D,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,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,oBAAoB,CAAC,CAAC,CAAC;CACpE;AAED,+BAA+B;AAC/B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACrD;AAED,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,kFAAkF;AAClF,MAAM,WAAW,2BAA2B;IAC1C,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,gFAAgF;IAChF,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,2BAA2B,GAChC,qBAAqB,CAevB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAYjG;AAkFD,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjG;AAED,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjG;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAIT"}