@nomix-ai/nomix-harness 0.2.4 → 0.2.6

package/dist/kernel/session-persistence-sqlite/lib/types/index.d.ts

@@ -1,63 +1,46 @@
 /**
- * SQLite durable session-persistence backend. It maps each session header and
- * event to rows, and delegates write-path orchestration to
- * {@link PersistenceCoordinator}. It has no independent per-session artifact,
- * so its locator returns `undefined`.
+ * Opt-in SQLite persistence provider. Logical sessions remain unchanged;
+ * the physical backend packs eligible chunk runs into schema-17 rows.
  * @module @nomix-ai/nomix-session-persistence-sqlite
  */
-import { Context } from '@nomix-ai/cordis';
-import z from '@nomix-ai/schemastery';
-import { SessionPersistence, type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot, type SessionInspection, type SessionPersistenceRevision as PersistenceRevision, type StoredPrefix, type StoredSuffix } from '../../../session-persistence/lib/index.js';
-import type { SessionEvent, SessionId, SessionHeader, SessionPreparation } from '../../../session/lib/index.js';
-import { type JournalMode } from './schema.ts';
+import { Context, Service } from '../../../cordis/lib/index.js';
+import z from '../../../schemastery/lib/index.mjs';
+import type { SessionEvent, SessionHeader, SessionId, SessionPreparation } from '../../../session/lib/index.js';
+import { SessionPersistence, type SessionInspection, type SessionLocation, type SessionPersistenceSnapshot } from '../../../session-persistence/lib/index.js';
+import type { JournalMode } from './schema.ts';
 export { SCHEMA_VERSION } from './schema.ts';
+/** Default wait for another SQLite connection's write reservation. */
+export declare const DEFAULT_BUSY_TIMEOUT_MS = 5000;
+/** Largest busy timeout accepted by SQLite's signed millisecond interface. */
+export declare const MAX_BUSY_TIMEOUT_MS = 2147483647;
 /** Plugin configuration. */
 export interface Config {
-    /**
-     * Filesystem path to the SQLite database file. The special value `:memory:`
-     * opens an in-process database (tests). On filesystems with POSIX modes,
-     * missing directories and databases are created owner-only; existing path
-     * modes are preserved. Filesystem setup errors other than an existing database
-     * fail initialization. The backend does not protect confidentiality or
-     * integrity when another principal can replace the database entry in its
-     * parent directory.
-     */
+    /** SQLite database path, or `:memory:` for an in-process database. */
     path: string;
-    /**
-     * SQLite `journal_mode` pragma. `wal` (the default) is the recorded
-     * durability model; pick a rollback-journal mode (`delete`/`truncate`/
-     * `persist`) on filesystems where WAL's shared-memory files do not work
-     * (network mounts). See {@link JournalMode}.
-     */
+    /** Durable SQLite journal mode; defaults to `wal`. */
     journalMode?: JournalMode;
+    /** Maximum wait for another SQLite connection's lock; defaults to 5,000 ms. */
+    busyTimeoutMs?: number;
     /** Maximum cold Session preparations retained for history-to-resume reuse. */
     preparedSessionCacheSize?: number;
     /** Fixed live-event coalescing window; not a backend completion deadline. */
     writeBatchMaxDelayMs?: number;
 }
 /**
- * The SQLite persistence backend. Load as a plugin; it registers as
- * `ctx.sessionPersistence` and (via the coordinator) installs the write-path
- * listeners. Its torn-tail marker is the seq to delete from.
+ * SQLite `SessionPersistence` provider with a schema-owned physical codec.
  */
-export declare class SqliteSessionPersistence extends SessionPersistence implements PersistenceBackend<number> {
+export declare class SqliteSessionPersistence extends SessionPersistence {
     config: Config;
     readonly supportsRawArtifacts = false;
+    readonly name = "session-persistence-sqlite";
     static inject: string[];
     static Config: z<Config>;
-    /**
-     * Backend label for the coordinator's dispose diagnostics. Intentionally
-     * shadows cordis `Service.name` (set to `'sessionPersistence'` by the base);
-     * see the JSONL backend for why this does not affect service resolution.
-     */
-    readonly name = "session-persistence-sqlite";
-    private db;
-    private storeIdentity;
-    private ready;
-    private coordinator;
+    private readonly store;
+    private readonly coordinator;
     constructor(ctx: Context, config: Config);
-    private openDb;
-    /** SQLite has one database, not an independent local artifact per session. */
+    /** Reject self-contained path and ownership failures without loading Node SQLite. */
+    protected [Service.init](): Promise<void>;
+    /** SQLite has one database, not an independent per-session artifact. */
     locate(_meta: SessionHeader): SessionLocation | undefined;
     create(meta: SessionHeader): Promise<void>;
     append(id: SessionId, events: readonly SessionEvent[]): Promise<void>;
@@ -68,49 +51,8 @@ export declare class SqliteSessionPersistence extends SessionPersistence impleme
         meta: SessionHeader;
         events: SessionEvent[];
     }>;
-    /** Read a stored prefix by id (ids are globally unique — no scope to scan). */
-    loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<number> | undefined>;
-    /** Read one row's revision without loading its events. */
-    readStoredRevision(id: SessionId, signal?: AbortSignal): Promise<PersistenceRevision | undefined>;
-    /**
-     * Seek-capable suffix read: SQL selects `seq >= fromSeq` directly, so the
-     * read scales with the suffix, not the log. Torn rows past the preserved
-     * region are dropped, never repaired (non-mutating read).
-     */
-    loadStoredFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<StoredSuffix | undefined>;
-    /**
-     * Read a session's row + ordered events into a {@link StoredPrefix}. The
-     * torn-tail marker is the seq from which a never-committed tail must be deleted
-     * (`scanRows` already returns it as `number | undefined`).
-     */
-    private readPrefix;
-    /**
-     * Durably append a batch in ONE transaction: materialize the sessions row (if
-     * lazy) and INSERT every event, or roll back entirely. The transaction is the
-     * atomicity + durability boundary, so a mid-batch failure (a UNIQUE violation
-     * on a duplicated seq) leaves the stored log untouched.
-     */
-    appendBatch(meta: SessionHeader, events: readonly SessionEvent[], isMaterialized: boolean): Promise<void>;
-    /**
-     * Make a crash repair durable in ONE transaction: DELETE the torn tail (from
-     * `tornMarker`) and INSERT the synthetic `closers`. After COMMIT the stored rows
-     * == the balanced log.
-     */
-    commitRepair(meta: SessionHeader, tornMarker: number | undefined, closers: readonly SessionEvent[]): Promise<void>;
-    /** List all materialized sessions' metadata (every row is a materialized session). */
     list(signal?: AbortSignal): Promise<SessionHeader[]>;
-    /** List metadata with a source-qualified monotonic revision per session. */
     listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>;
-    /** Close the database handle (awaited by the coordinator's dispose, post-drain). */
-    close(): Promise<void>;
-    /** Fetch a session's row, or undefined if absent. */
-    private rowFor;
-    /**
-     * Insert-or-replace a session's metadata row. The only caller is the first
-     * materializing `appendBatch`, so writing the row IS the materialization (its
-     * existence is the signal `list` reads).
-     */
-    private writeRow;
 }
 export default SqliteSessionPersistence;
 //# sourceMappingURL=index.d.ts.map

package/dist/kernel/session-persistence-sqlite/lib/types/index.js

@@ -1,127 +1,57 @@
 /**
- * SQLite durable session-persistence backend. It maps each session header and
- * event to rows, and delegates write-path orchestration to
- * {@link PersistenceCoordinator}. It has no independent per-session artifact,
- * so its locator returns `undefined`.
+ * Opt-in SQLite persistence provider. Logical sessions remain unchanged;
+ * the physical backend packs eligible chunk runs into schema-17 rows.
  * @module @nomix-ai/nomix-session-persistence-sqlite
  */
-import z from '@nomix-ai/schemastery';
-import { randomUUID } from 'node:crypto';
-import { statSync } from 'node:fs';
-import { mkdir, open } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
-import { DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS, SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator, } from '../../../session-persistence/lib/index.js';
-import { openDatabase, rowToMeta, scanRows, } from "./schema.js";
+import { Service } from '../../../cordis/lib/index.js';
+import z from '../../../schemastery/lib/index.mjs';
+import { DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS, PersistenceCoordinator, SessionPersistence, } from '../../../session-persistence/lib/index.js';
+import { SqliteStore } from "./store.js";
 export { SCHEMA_VERSION } from "./schema.js";
+/** Default wait for another SQLite connection's write reservation. */
+export const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+/** Largest busy timeout accepted by SQLite's signed millisecond interface. */
+export const MAX_BUSY_TIMEOUT_MS = 2_147_483_647;
 /**
- * Serialize an event's optional envelope fields for SQL binding. The surface
- * fields are nullable TEXT columns — null when the event has no surface
- * metadata (non-surface events, events written before surface support); the
- * ignorable marker is a nullable INTEGER column — `1` iff the envelope carries
- * `ignorable: true`.
- */
-function envelopeBindings(event) {
-    const se = event;
-    return [
-        se.sourceEventSeqs ? JSON.stringify(se.sourceEventSeqs) : null,
-        se.surfaceOp !== undefined ? JSON.stringify(se.surfaceOp) : null,
-        event.ignorable === true ? 1 : null,
-    ];
-}
-/** Build the source-qualified revision shared by full and lightweight reads. */
-function sqliteRevision(storeIdentity, row) {
-    return SessionPersistenceRevision(`${storeIdentity}:incarnation:${row.incarnation}:revision:${row.revision}`);
-}
-/**
- * Exclusively create a missing database file with owner-only permissions.
- * Existing files retain their modes, and errors other than `EEXIST` propagate.
- * `DatabaseSync` reopens by path, so this does not protect confidentiality or
- * integrity when another principal can replace the database entry in its parent
- * directory.
- */
-async function createDatabaseFile(path) {
-    try {
-        const handle = await open(path, 'wx', 0o600);
-        await handle.close();
-    }
-    catch (error) {
-        if (error.code !== 'EEXIST')
-            throw error;
-    }
-}
-/**
- * The SQLite persistence backend. Load as a plugin; it registers as
- * `ctx.sessionPersistence` and (via the coordinator) installs the write-path
- * listeners. Its torn-tail marker is the seq to delete from.
+ * SQLite `SessionPersistence` provider with a schema-owned physical codec.
  */
 export class SqliteSessionPersistence extends SessionPersistence {
     config;
     supportsRawArtifacts = false;
+    name = 'session-persistence-sqlite';
     static inject = ['sessions'];
     static Config = z.object({
         path: z.string().required(),
         journalMode: z.union(['wal', 'delete', 'truncate', 'persist']).default('wal'),
+        busyTimeoutMs: z.number().step(1).min(0).max(MAX_BUSY_TIMEOUT_MS).default(DEFAULT_BUSY_TIMEOUT_MS),
         preparedSessionCacheSize: z.number().step(1).min(1).default(DEFAULT_PREPARED_SESSION_CACHE_SIZE),
         writeBatchMaxDelayMs: z.number().step(1).min(1).max(MAX_WRITE_BATCH_DELAY_MS)
             .default(DEFAULT_WRITE_BATCH_MAX_DELAY_MS),
     });
-    /**
-     * Backend label for the coordinator's dispose diagnostics. Intentionally
-     * shadows cordis `Service.name` (set to `'sessionPersistence'` by the base);
-     * see the JSONL backend for why this does not affect service resolution.
-     */
-    name = 'session-persistence-sqlite';
-    db;
-    storeIdentity;
-    ready;
+    store;
     coordinator;
     constructor(ctx, config) {
         super(ctx);
         this.config = config;
-        // Programmatic wrappers may construct the backend without Schemastery normalization.
         const preparedSessionCacheSize = config.preparedSessionCacheSize
             ?? DEFAULT_PREPARED_SESSION_CACHE_SIZE;
         const writeBatchMaxDelayMs = config.writeBatchMaxDelayMs
             ?? DEFAULT_WRITE_BATCH_MAX_DELAY_MS;
-        // Open asynchronously so directory creation does not block plugin apply;
-        // every storage hook awaits the same readiness promise.
-        this.ready = this.openDb(config.path, config.journalMode);
-        this.coordinator = new PersistenceCoordinator(this.ctx, this, {
+        this.store = new SqliteStore({
+            path: config.path,
+            journalMode: config.journalMode ?? 'wal',
+            busyTimeoutMs: config.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS,
+        });
+        this.coordinator = new PersistenceCoordinator(this.ctx, this.store, {
             preparedSessionCacheSize,
             writeBatchMaxDelayMs,
         });
     }
-    async openDb(path, journalMode) {
-        const actual = path === ':memory:' ? path : resolve(path);
-        if (actual !== ':memory:') {
-            await mkdir(dirname(actual), { recursive: true, mode: 0o700 });
-            await createDatabaseFile(actual);
-        }
-        this.db = openDatabase(actual, journalMode);
-        try {
-            const row = this.db.prepare('SELECT store_id FROM persistence_state WHERE singleton = 1').get();
-            /* v8 ignore next -- openDatabase inserts the singleton before returning. */
-            if (row === undefined) {
-                throw new Error(`session database at "${actual}" has no store identity`);
-            }
-            if (row.store_id.length === 0) {
-                throw new Error(`session database at "${actual}" has no valid store identity`);
-            }
-            if (actual !== ':memory:') {
-                const identity = statSync(actual, { bigint: true });
-                this.storeIdentity = `file:${identity.dev}:${identity.ino}:${identity.birthtimeNs}:store:${row.store_id}`;
-            }
-            else {
-                this.storeIdentity = `memory:store:${row.store_id}`;
-            }
-        }
-        catch (error) {
-            this.db.close();
-            throw error;
-        }
+    /** Reject self-contained path and ownership failures without loading Node SQLite. */
+    async [Service.init]() {
+        await this.store.validatePath();
     }
-    // --- SessionPersistence service API (delegated to the coordinator) ---
-    /** SQLite has one database, not an independent local artifact per session. */
+    /** SQLite has one database, not an independent per-session artifact. */
     locate(_meta) {
         return undefined;
     }
@@ -143,192 +73,11 @@ export class SqliteSessionPersistence extends SessionPersistence {
     readFrom(id, fromSeq, signal) {
         return this.coordinator.readFrom(id, fromSeq, signal);
     }
-    // One method serves both public `list` and the backend hook; delegating it to
-    // the coordinator would call this hook recursively.
-    // --- PersistenceBackend hooks (the SQLite storage primitives) ---
-    /** Read a stored prefix by id (ids are globally unique — no scope to scan). */
-    loadStored(id, signal) {
-        return this.readPrefix(id, signal);
-    }
-    /** Read one row's revision without loading its events. */
-    async readStoredRevision(id, signal) {
-        signal?.throwIfAborted();
-        await this.ready;
-        signal?.throwIfAborted();
-        const row = this.rowFor(id);
-        return row === undefined ? undefined : sqliteRevision(this.storeIdentity, row);
-    }
-    /**
-     * Seek-capable suffix read: SQL selects `seq >= fromSeq` directly, so the
-     * read scales with the suffix, not the log. Torn rows past the preserved
-     * region are dropped, never repaired (non-mutating read).
-     */
-    async loadStoredFrom(id, fromSeq, signal) {
-        signal?.throwIfAborted();
-        await this.ready;
-        signal?.throwIfAborted();
-        const row = this.rowFor(id);
-        if (row === undefined)
-            return undefined;
-        const meta = rowToMeta(row);
-        const eventRows = this.db
-            .prepare('SELECT seq, type, time, data, source_event_seqs, surface_op, ignorable FROM events WHERE session_id = ? AND seq >= ? ORDER BY seq')
-            .all(id, fromSeq);
-        signal?.throwIfAborted();
-        const { preserved } = scanRows(eventRows, fromSeq);
-        return { meta, events: preserved };
-    }
-    /**
-     * Read a session's row + ordered events into a {@link StoredPrefix}. The
-     * torn-tail marker is the seq from which a never-committed tail must be deleted
-     * (`scanRows` already returns it as `number | undefined`).
-     */
-    async readPrefix(id, signal) {
-        signal?.throwIfAborted();
-        await this.ready;
-        signal?.throwIfAborted();
-        this.db.exec('BEGIN');
-        let snapshot;
-        try {
-            const row = this.rowFor(id);
-            if (row !== undefined) {
-                const eventRows = this.db
-                    .prepare('SELECT seq, type, time, data, source_event_seqs, surface_op, ignorable FROM events WHERE session_id = ? ORDER BY seq')
-                    .all(id);
-                snapshot = { row, eventRows };
-            }
-            this.db.exec('COMMIT');
-        }
-        catch (error) {
-            /* v8 ignore start -- synchronous read failures only need transaction cleanup before propagation. */
-            this.db.exec('ROLLBACK');
-            throw error;
-            /* v8 ignore stop */
-        }
-        signal?.throwIfAborted();
-        if (snapshot === undefined)
-            return undefined;
-        const { row, eventRows } = snapshot;
-        const { preserved, tornFrom } = scanRows(eventRows);
-        return {
-            meta: rowToMeta(row),
-            events: preserved,
-            revision: sqliteRevision(this.storeIdentity, row),
-            ...tornFrom !== undefined ? { tornMarker: tornFrom } : {},
-        };
-    }
-    /**
-     * Durably append a batch in ONE transaction: materialize the sessions row (if
-     * lazy) and INSERT every event, or roll back entirely. The transaction is the
-     * atomicity + durability boundary, so a mid-batch failure (a UNIQUE violation
-     * on a duplicated seq) leaves the stored log untouched.
-     */
-    async appendBatch(meta, events, isMaterialized) {
-        await this.ready;
-        const insertEvent = this.db.prepare('INSERT INTO events (session_id, seq, type, time, data, source_event_seqs, surface_op, ignorable) VALUES (?, ?, ?, ?, ?, ?, ?, ?)');
-        this.db.exec('BEGIN');
-        try {
-            if (!isMaterialized)
-                this.writeRow(meta);
-            for (const event of events) {
-                const [surfaceSeqs, surfaceOp, ignorable] = envelopeBindings(event);
-                insertEvent.run(meta.id, event.seq, event.type, event.time, JSON.stringify(event.data), surfaceSeqs, surfaceOp, ignorable);
-            }
-            this.db.prepare('UPDATE sessions SET revision = revision + 1 WHERE id = ?').run(meta.id);
-            this.db.exec('COMMIT');
-        }
-        catch (error) {
-            this.db.exec('ROLLBACK');
-            throw error;
-        }
-    }
-    /**
-     * Make a crash repair durable in ONE transaction: DELETE the torn tail (from
-     * `tornMarker`) and INSERT the synthetic `closers`. After COMMIT the stored rows
-     * == the balanced log.
-     */
-    async commitRepair(meta, tornMarker, closers) {
-        await this.ready;
-        this.db.exec('BEGIN');
-        try {
-            if (tornMarker !== undefined) {
-                this.db.prepare('DELETE FROM events WHERE session_id = ? AND seq >= ?').run(meta.id, tornMarker);
-            }
-            if (closers.length > 0) {
-                const insertEvent = this.db.prepare('INSERT INTO events (session_id, seq, type, time, data, source_event_seqs, surface_op, ignorable) VALUES (?, ?, ?, ?, ?, ?, ?, ?)');
-                for (const event of closers) {
-                    const [surfaceSeqs, surfaceOp, ignorable] = envelopeBindings(event);
-                    insertEvent.run(meta.id, event.seq, event.type, event.time, JSON.stringify(event.data), surfaceSeqs, surfaceOp, ignorable);
-                }
-            }
-            if (tornMarker !== undefined || closers.length > 0) {
-                this.db.prepare('UPDATE sessions SET revision = revision + 1 WHERE id = ?').run(meta.id);
-            }
-            this.db.exec('COMMIT');
-        }
-        catch (error) {
-            // The DELETE+INSERT cannot collide (a row at a closer's seq is preserved or
-            // deleted as torn first); this rolls back a DB-level failure (disk full,
-            // etc.), unreachable in test.
-            /* v8 ignore start */
-            this.db.exec('ROLLBACK');
-            throw error;
-            /* v8 ignore stop */
-        }
-    }
-    /** List all materialized sessions' metadata (every row is a materialized session). */
-    async list(signal) {
-        signal?.throwIfAborted();
-        await this.ready;
-        signal?.throwIfAborted();
-        const rows = this.db
-            .prepare('SELECT * FROM sessions')
-            .all();
-        signal?.throwIfAborted();
-        return rows.map(rowToMeta);
-    }
-    /** List metadata with a source-qualified monotonic revision per session. */
-    async listSnapshots(signal) {
-        signal?.throwIfAborted();
-        await this.ready;
-        signal?.throwIfAborted();
-        const rows = this.db.prepare('SELECT * FROM sessions').all();
-        signal?.throwIfAborted();
-        return rows.map(row => ({
-            header: rowToMeta(row),
-            revision: SessionPersistenceRevision(`${this.storeIdentity}:incarnation:${row.incarnation}:revision:${row.revision}`),
-        }));
-    }
-    /** Close the database handle (awaited by the coordinator's dispose, post-drain). */
-    async close() {
-        await this.ready;
-        this.db.close();
-    }
-    // --- row helpers ---
-    /** Fetch a session's row, or undefined if absent. */
-    rowFor(id) {
-        return this.db.prepare('SELECT * FROM sessions WHERE id = ?').get(id);
+    list(signal) {
+        return this.store.list(signal);
     }
-    /**
-     * Insert-or-replace a session's metadata row. The only caller is the first
-     * materializing `appendBatch`, so writing the row IS the materialization (its
-     * existence is the signal `list` reads).
-     */
-    writeRow(meta) {
-        this.db.prepare(`
-      INSERT INTO sessions
-        (id, version, created_at, cwd, parent_session, seed_length, origin, delegation_depth, agent_preset, incarnation, revision)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)
-      ON CONFLICT(id) DO UPDATE SET
-        version = excluded.version,
-        created_at = excluded.created_at,
-        cwd = excluded.cwd,
-        parent_session = excluded.parent_session,
-        seed_length = excluded.seed_length,
-        origin = excluded.origin,
-        delegation_depth = excluded.delegation_depth,
-        agent_preset = excluded.agent_preset
-    `).run(meta.id, meta.version, meta.createdAt, meta.cwd ?? null, meta.parentSession ?? null, meta.seedLength ?? null, meta.origin ?? null, meta.delegationDepth ?? null, meta.agentPreset ?? null, randomUUID());
+    listSnapshots(signal) {
+        return this.store.listSnapshots(signal);
     }
 }
 export default SqliteSessionPersistence;

package/dist/kernel/session-persistence-sqlite/lib/types/invariant.d.ts

@@ -2,7 +2,7 @@
  * Package-owned invariant companion for `@nomix-ai/nomix-session-persistence-sqlite`.
  * @module @nomix-ai/nomix-session-persistence-sqlite/invariant
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 /** Cordis companion plugin name. */
 export declare const name = "session-persistence-sqlite-invariant";
 /** Service required before the companion can reserve package ownership. */

package/dist/kernel/session-persistence-sqlite/lib/types/invariant.js

@@ -8,8 +8,8 @@ export const name = 'session-persistence-sqlite-invariant';
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants'];
 /**
- * No runtime invariant: persistence correctness requires backend round-trip and crash-tail tests;
- * this package exposes no continuously observable in-process relation.
+ * No runtime invariant: physical packing is observable only by database
+ * round-trip and row-count checks, not a continuous in-process relation.
  */
 const install = () => { };
 /**