@paraharness/sqlite 0.0.0-stage → 0.1.0

package/dist/stores/sqlite-lesson-store.js

@@ -0,0 +1,121 @@
+import PQueue from 'p-queue';
+import { openSqliteConnection } from '../ddl/internal/open-sqlite-connection.js';
+import { admitLessonInSqlite, markLessonSignalEmittedInSqlite, queryLessonCandidatesInSqlite, recordLessonOutcomesInSqlite, retireLessonsInSqlite, syncLessonEpochsInSqlite, } from './internal/sqlite-lesson-ops.js';
+/**
+ * WAL-mode SQLite implementation of the `@paraharness/core` `LessonStore` runtime port.
+ *
+ * Persists distilled empirical lessons, computes normalized candidate relevance $R(L, Q) \in [0, 1]$,
+ * tracks 4-state execution outcomes, synchronizes creation epochs, and enforces signal cooldowns.
+ */
+export class SqliteLessonStore {
+    /** Underlying `better-sqlite3` database connection. */
+    db;
+    /** Single-concurrency FIFO queue serializing asynchronous store operations. */
+    queue = new PQueue({ concurrency: 1 });
+    /**
+     * Initializes a `SqliteLessonStore` against a SQLite file path, `:memory:`, or existing `Database` handle.
+     *
+     * Applies WAL-mode PRAGMAs and idempotent lesson store DDL statements on initialization.
+     *
+     * @param {string | Database.Database} uriOrDb - SQLite database URI or open `better-sqlite3` handle.
+     */
+    constructor(uriOrDb) {
+        this.db = openSqliteConnection(uriOrDb);
+    }
+    /**
+     * Queries non-retired candidate lessons relevant to `req.queryText` and `req.partitions`.
+     *
+     * Populates `relevanceScore` in `[0, 1]` on each returned `LessonRecord`.
+     *
+     * @param {QueryLessonCandidatesParams} req - Search query and active partitions.
+     *
+     * @returns {Promise<readonly LessonRecord[]>} Candidate lesson records with `relevanceScore` populated.
+     */
+    queryCandidates(req) {
+        return this.queue.add(() => queryLessonCandidatesInSqlite(this.db, req));
+    }
+    /**
+     * Persists a newly distilled lesson into the store and returns its assigned `lessonId`.
+     *
+     * Deduplicates identical `(partition, directive)` entries and records `epochAtCreation` and `createdByRunId`.
+     *
+     * @param {AdmitLessonParams} lesson - Lesson definition to admit.
+     *
+     * @returns {Promise<string>} Newly assigned or content-addressed `lessonId`.
+     */
+    admit(lesson) {
+        return this.queue.add(() => this.db.transaction(() => admitLessonInSqlite(this.db, lesson))());
+    }
+    /**
+     * Appends deduplicated step execution outcomes to the specified lessons and returns their updated records.
+     *
+     * Increments `totalCleanPasses` or `totalViolated` and updates each lesson's `recentOutcomes` window.
+     *
+     * @param {readonly LessonOutcomeEntryParams[]} outcomes - Batch of `(lessonId, outcome)` pairs.
+     *
+     * @returns {Promise<readonly LessonRecord[]>} Updated lesson records reflecting the recorded outcomes.
+     */
+    recordOutcomes(outcomes) {
+        return this.queue.add(() => this.db.transaction(() => recordLessonOutcomesInSqlite(this.db, outcomes))());
+    }
+    /**
+     * Aligns `epochAtCreation` for lessons created by `runIds` when their topology overlays commit to the base store.
+     *
+     * Prevents lessons authored in a run that also updated a partition's contract from being falsely penalized for epoch drift.
+     *
+     * @param {readonly string[]}           runIds        - Run IDs whose topology overlays were committed.
+     * @param {ReadonlyMap<string, number>} updatedEpochs - Map of `partitionId` to newly committed base epoch.
+     *
+     * @returns {Promise<void>} Resolves when creation epochs are synchronized.
+     */
+    syncCreationEpochsForRuns(runIds, updatedEpochs) {
+        return this.queue.add(() => {
+            this.db.transaction(() => syncLessonEpochsInSqlite(this.db, runIds, updatedEpochs))();
+        });
+    }
+    /**
+     * Records the ISO-8601 timestamp when a promotion signal was emitted for `lessonId`.
+     *
+     * Persists the timestamp in `signalLastEmittedAt[signalId]` to enforce `cooldownHours` across restarts.
+     *
+     * @param {string} lessonId  - Identifier of the lesson that triggered the signal.
+     * @param {string} signalId  - Identifier of the emitted signal.
+     * @param {string} emittedAt - ISO-8601 timestamp string of the emission.
+     *
+     * @returns {Promise<void>} Resolves when the cooldown timestamp is persisted.
+     */
+    markSignalEmitted(lessonId, signalId, emittedAt) {
+        return this.queue.add(() => {
+            this.db.transaction(() => {
+                markLessonSignalEmittedInSqlite(this.db, { lessonId, signalId, emittedAt });
+            })();
+        });
+    }
+    /**
+     * Permanently retires lessons that breached violation or low clean-pass-rate thresholds.
+     *
+     * Excludes retired lessons from all subsequent `queryCandidates()` recalls.
+     *
+     * @param {readonly string[]} lessonIds - Identifiers of lessons to retire.
+     *
+     * @returns {Promise<void>} Resolves when all specified lessons are retired.
+     */
+    retire(lessonIds) {
+        return this.queue.add(() => {
+            this.db.transaction(() => {
+                retireLessonsInSqlite(this.db, lessonIds);
+            })();
+        });
+    }
+    /**
+     * Closes the underlying `better-sqlite3` database connection.
+     *
+     * Releases file descriptors and WAL shared-memory locks held by this store instance.
+     *
+     * @returns {void} Returns nothing once the connection is closed.
+     */
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=sqlite-lesson-store.js.map

package/dist/stores/sqlite-lesson-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-lesson-store.js","sourceRoot":"","sources":["../../src/stores/sqlite-lesson-store.ts"],"names":[],"mappings":"AAEA,OAAO,MAAM,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAGL,mBAAmB,EACnB,+BAA+B,EAC/B,6BAA6B,EAC7B,4BAA4B,EAC5B,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,iCAAiC,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IAC5B,uDAAuD;IACtC,EAAE,CAAoB;IACvC,+EAA+E;IAC9D,KAAK,GAAG,IAAI,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC;IAExD;;;;;;OAMG;IACH,YAAY,OAAmC;QAC7C,IAAI,CAAC,EAAE,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,GAAgC;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,6BAA6B,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAyB;QAC7B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IACjG,CAAC;IAED;;;;;;;;OAQG;IACH,cAAc,CAAC,QAA6C;QAC1D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CACzB,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,4BAA4B,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,EAAE,CAC7E,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;IACH,yBAAyB,CACvB,MAAyB,EACzB,aAA0C;QAE1C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YACzB,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,wBAAwB,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC;QACxF,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,QAAgB,EAAE,QAAgB,EAAE,SAAiB;QACrE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YACzB,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE;gBACvB,+BAA+B,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;YAC9E,CAAC,CAAC,EAAE,CAAC;QACP,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,SAA4B;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YACzB,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE;gBACvB,qBAAqB,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;YAC5C,CAAC,CAAC,EAAE,CAAC;QACP,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK;QACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;CACF"}

package/dist/stores/sqlite-topology-store.d.ts

@@ -0,0 +1,112 @@
+import type { CommitRunOverlayResult, TopologyPartitionState, TopologyStore } from '@paraharness/core';
+import type Database from 'better-sqlite3';
+import { type ResetRunOverlayOptions } from './internal/sqlite-topology-overlay-ops.js';
+/**
+ * WAL-mode SQLite implementation of the `@paraharness/core` `TopologyStore` runtime port.
+ *
+ * Manages canonical base partition contracts alongside per-run Copy-on-Write overlays,
+ * stacked prerequisite synchronization, step/run-scoped resets, and 3-way overlay commits.
+ */
+export declare class SqliteTopologyStore implements TopologyStore {
+    /** Underlying `better-sqlite3` database connection. */
+    private readonly db;
+    /** Single-concurrency FIFO queue serializing asynchronous store operations. */
+    private readonly queue;
+    /**
+     * Initializes a `SqliteTopologyStore` against a SQLite file path, `:memory:`, or existing `Database` handle.
+     *
+     * Applies WAL-mode PRAGMAs and idempotent topology DDL statements on initialization.
+     *
+     * @param {string | Database.Database} uriOrDb - SQLite database URI or open `better-sqlite3` handle.
+     */
+    constructor(uriOrDb: string | Database.Database);
+    /**
+     * Loads the partition state map for `runId` (merging any uncommitted per-run CoW overlay over the base store).
+     *
+     * Pins each partition's initial `baseContractTextAtAcquire` when `runId` first inspects the partition.
+     *
+     * @param {string} [runId] - Optional active flow run identifier.
+     *
+     * @returns {Promise<ReadonlyMap<string, TopologyPartitionState>>} Map of `partitionId` to partition state.
+     */
+    getPartitions(runId?: string): Promise<ReadonlyMap<string, TopologyPartitionState>>;
+    /**
+     * Writes a contract update to `runId`'s isolated Copy-on-Write overlay.
+     *
+     * Increments the partition's overlay epoch at most once per `(runId, partitionId)` unless reset
+     * by `resetRunOverlay()`, and tags the mutation with `stepExecId` for step-scoped rollback.
+     *
+     * @param {string} runId           - Active flow run identifier.
+     * @param {string} partitionId     - Target partition identifier.
+     * @param {string} newContractText - Updated contract text.
+     * @param {string} [stepExecId]    - Optional active step execution identifier.
+     *
+     * @returns {Promise<{ readonly newEpoch: number }>} Updated overlay epoch for `partitionId`.
+     */
+    updateContract(runId: string, partitionId: string, newContractText: string, stepExecId?: string): Promise<{
+        readonly newEpoch: number;
+    }>;
+    /**
+     * Merges prerequisite runs' `ACTIVE` or `SEALED_UNMERGED` overlays into `targetRunId`'s overlay.
+     *
+     * Advances `targetRunId`'s 3-way merge-base text for each absorbed partition so stacked PRs
+     * never false-conflict when committed sequentially.
+     *
+     * @param {string}            targetRunId        - Dependent run absorbing the prerequisite overlays.
+     * @param {readonly string[]} prerequisiteRunIds - Prerequisite run identifiers to merge from.
+     *
+     * @returns {Promise<void>} Resolves once prerequisite overlays are merged.
+     */
+    syncRunOverlays(targetRunId: string, prerequisiteRunIds: readonly string[]): Promise<void>;
+    /**
+     * Resets uncommitted overlay mutations for `runId` at either the `'step'` or `'run'` scope.
+     *
+     * Preserves completed step mutations when `scope === 'step'` and rolls back the entire run overlay when `scope === 'run'`.
+     *
+     * @param {string}                 runId  - Target flow run identifier.
+     * @param {ResetRunOverlayOptions} [opts] - Reset scope options.
+     *
+     * @returns {Promise<void>} Resolves once matching uncommitted overlay mutations are rolled back.
+     */
+    resetRunOverlay(runId: string, opts?: ResetRunOverlayOptions): Promise<void>;
+    /**
+     * Transitions `runId`'s overlay to `SEALED_UNMERGED` upon flow exit `'done'` when awaiting an external merge signal.
+     *
+     * Allows dependent stacked runs to absorb the sealed overlay via `syncRunOverlays` without polluting the base store.
+     *
+     * @param {string} runId - Completed flow run identifier.
+     *
+     * @returns {Promise<void>} Resolves once the overlay is sealed.
+     */
+    sealRunOverlay(runId: string): Promise<void>;
+    /**
+     * Atomically commits `runId`'s overlay (and any absorbed ancestor/prerequisite `SEALED_UNMERGED` overlays)
+     * to the base store using a 3-way merge against `baseContractTextAtAcquire`.
+     *
+     * Allocates monotonic base epoch numbers at commit time and returns the committed run IDs and updated epochs.
+     *
+     * @param {string} runId - Flow run identifier whose changes landed.
+     *
+     * @returns {Promise<CommitRunOverlayResult>} Committed run IDs and newly allocated base epoch numbers.
+     */
+    commitRunOverlay(runId: string): Promise<CommitRunOverlayResult>;
+    /**
+     * Discards `runId`'s overlay when a run fails, a PR closes unmerged, or `maxSealedAgeHours` expires.
+     *
+     * Removes all uncommitted or sealed overlay rows for `runId` without modifying the base store.
+     *
+     * @param {string} runId - Flow run identifier whose overlay should be discarded.
+     *
+     * @returns {Promise<void>} Resolves once the overlay is removed.
+     */
+    discardRunOverlay(runId: string): Promise<void>;
+    /**
+     * Closes the underlying `better-sqlite3` database connection.
+     *
+     * Releases file descriptors and WAL shared-memory locks held by this store instance.
+     *
+     * @returns {void} Returns nothing once the connection is closed.
+     */
+    close(): void;
+}
+//# sourceMappingURL=sqlite-topology-store.d.ts.map

package/dist/stores/sqlite-topology-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-topology-store.d.ts","sourceRoot":"","sources":["../../src/stores/sqlite-topology-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAQ3C,OAAO,EACL,KAAK,sBAAsB,EAK5B,MAAM,2CAA2C,CAAC;AAEnD;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACvD,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAoB;IACvC,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IAExD;;;;;;OAMG;gBACS,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ;IAI/C;;;;;;;;OAQG;IACH,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAMnF;;;;;;;;;;;;OAYG;IACH,cAAc,CACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAQzC;;;;;;;;;;OAUG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1F;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5E;;;;;;;;OAQG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5C;;;;;;;;;OASG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAMhE;;;;;;;;OAQG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/C;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/stores/sqlite-topology-store.js

@@ -0,0 +1,137 @@
+import PQueue from 'p-queue';
+import { openSqliteConnection } from '../ddl/internal/open-sqlite-connection.js';
+import { commitOverlayThreeWayMerge, discardOverlayForRun, sealOverlayForRun, } from './internal/sqlite-topology-commit-ops.js';
+import { getPartitionsWithOverlay, resetOverlayByScope, syncPrerequisiteOverlays, updateContractInOverlay, } from './internal/sqlite-topology-overlay-ops.js';
+/**
+ * WAL-mode SQLite implementation of the `@paraharness/core` `TopologyStore` runtime port.
+ *
+ * Manages canonical base partition contracts alongside per-run Copy-on-Write overlays,
+ * stacked prerequisite synchronization, step/run-scoped resets, and 3-way overlay commits.
+ */
+export class SqliteTopologyStore {
+    /** Underlying `better-sqlite3` database connection. */
+    db;
+    /** Single-concurrency FIFO queue serializing asynchronous store operations. */
+    queue = new PQueue({ concurrency: 1 });
+    /**
+     * Initializes a `SqliteTopologyStore` against a SQLite file path, `:memory:`, or existing `Database` handle.
+     *
+     * Applies WAL-mode PRAGMAs and idempotent topology DDL statements on initialization.
+     *
+     * @param {string | Database.Database} uriOrDb - SQLite database URI or open `better-sqlite3` handle.
+     */
+    constructor(uriOrDb) {
+        this.db = openSqliteConnection(uriOrDb);
+    }
+    /**
+     * Loads the partition state map for `runId` (merging any uncommitted per-run CoW overlay over the base store).
+     *
+     * Pins each partition's initial `baseContractTextAtAcquire` when `runId` first inspects the partition.
+     *
+     * @param {string} [runId] - Optional active flow run identifier.
+     *
+     * @returns {Promise<ReadonlyMap<string, TopologyPartitionState>>} Map of `partitionId` to partition state.
+     */
+    getPartitions(runId) {
+        return this.queue.add(() => this.db.transaction(() => getPartitionsWithOverlay(this.db, runId))());
+    }
+    /**
+     * Writes a contract update to `runId`'s isolated Copy-on-Write overlay.
+     *
+     * Increments the partition's overlay epoch at most once per `(runId, partitionId)` unless reset
+     * by `resetRunOverlay()`, and tags the mutation with `stepExecId` for step-scoped rollback.
+     *
+     * @param {string} runId           - Active flow run identifier.
+     * @param {string} partitionId     - Target partition identifier.
+     * @param {string} newContractText - Updated contract text.
+     * @param {string} [stepExecId]    - Optional active step execution identifier.
+     *
+     * @returns {Promise<{ readonly newEpoch: number }>} Updated overlay epoch for `partitionId`.
+     */
+    updateContract(runId, partitionId, newContractText, stepExecId) {
+        return this.queue.add(() => this.db.transaction(() => updateContractInOverlay(this.db, { runId, partitionId, newContractText, stepExecId }))());
+    }
+    /**
+     * Merges prerequisite runs' `ACTIVE` or `SEALED_UNMERGED` overlays into `targetRunId`'s overlay.
+     *
+     * Advances `targetRunId`'s 3-way merge-base text for each absorbed partition so stacked PRs
+     * never false-conflict when committed sequentially.
+     *
+     * @param {string}            targetRunId        - Dependent run absorbing the prerequisite overlays.
+     * @param {readonly string[]} prerequisiteRunIds - Prerequisite run identifiers to merge from.
+     *
+     * @returns {Promise<void>} Resolves once prerequisite overlays are merged.
+     */
+    syncRunOverlays(targetRunId, prerequisiteRunIds) {
+        return this.queue.add(() => {
+            this.db.transaction(() => syncPrerequisiteOverlays(this.db, targetRunId, prerequisiteRunIds))();
+        });
+    }
+    /**
+     * Resets uncommitted overlay mutations for `runId` at either the `'step'` or `'run'` scope.
+     *
+     * Preserves completed step mutations when `scope === 'step'` and rolls back the entire run overlay when `scope === 'run'`.
+     *
+     * @param {string}                 runId  - Target flow run identifier.
+     * @param {ResetRunOverlayOptions} [opts] - Reset scope options.
+     *
+     * @returns {Promise<void>} Resolves once matching uncommitted overlay mutations are rolled back.
+     */
+    resetRunOverlay(runId, opts) {
+        return this.queue.add(() => {
+            this.db.transaction(() => resetOverlayByScope(this.db, runId, opts))();
+        });
+    }
+    /**
+     * Transitions `runId`'s overlay to `SEALED_UNMERGED` upon flow exit `'done'` when awaiting an external merge signal.
+     *
+     * Allows dependent stacked runs to absorb the sealed overlay via `syncRunOverlays` without polluting the base store.
+     *
+     * @param {string} runId - Completed flow run identifier.
+     *
+     * @returns {Promise<void>} Resolves once the overlay is sealed.
+     */
+    sealRunOverlay(runId) {
+        return this.queue.add(() => {
+            sealOverlayForRun(this.db, runId);
+        });
+    }
+    /**
+     * Atomically commits `runId`'s overlay (and any absorbed ancestor/prerequisite `SEALED_UNMERGED` overlays)
+     * to the base store using a 3-way merge against `baseContractTextAtAcquire`.
+     *
+     * Allocates monotonic base epoch numbers at commit time and returns the committed run IDs and updated epochs.
+     *
+     * @param {string} runId - Flow run identifier whose changes landed.
+     *
+     * @returns {Promise<CommitRunOverlayResult>} Committed run IDs and newly allocated base epoch numbers.
+     */
+    commitRunOverlay(runId) {
+        return this.queue.add(() => this.db.transaction(() => commitOverlayThreeWayMerge(this.db, runId))());
+    }
+    /**
+     * Discards `runId`'s overlay when a run fails, a PR closes unmerged, or `maxSealedAgeHours` expires.
+     *
+     * Removes all uncommitted or sealed overlay rows for `runId` without modifying the base store.
+     *
+     * @param {string} runId - Flow run identifier whose overlay should be discarded.
+     *
+     * @returns {Promise<void>} Resolves once the overlay is removed.
+     */
+    discardRunOverlay(runId) {
+        return this.queue.add(() => {
+            discardOverlayForRun(this.db, runId);
+        });
+    }
+    /**
+     * Closes the underlying `better-sqlite3` database connection.
+     *
+     * Releases file descriptors and WAL shared-memory locks held by this store instance.
+     *
+     * @returns {void} Returns nothing once the connection is closed.
+     */
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=sqlite-topology-store.js.map

package/dist/stores/sqlite-topology-store.js.map

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

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@paraharness/sqlite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "WAL-mode SQLite runtime drivers for Paraharness LedgerStore, Copy-on-Write TopologyStore, LessonStore, and global rules sources.",
+  "keywords": [
+    "paraharness",
+    "sqlite",
+    "better-sqlite3",
+    "ledger",
+    "topology",
+    "lessons",
+    "ai-agents"
+  ],
+  "author": "Tornike Tsomaia",
+  "license": "MIT",
+  "homepage": "https://paraharness.github.io/paraharness/modules/_paraharness_sqlite.html",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paraharness/paraharness.git",
+    "directory": "packages/sqlite"
+  },
+  "bugs": {
+    "url": "https://github.com/paraharness/paraharness/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@dagrejs/graphlib": "^4.0.7",
+    "better-sqlite3": "^12.8.0",
+    "minisearch": "^7.2.0",
+    "node-diff3": "^3.2.1",
+    "p-queue": "^9.1.0",
+    "zod": "^4.6.7",
+    "@paraharness/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^22.9.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.0"
+  },
+  "typedocOptions": {
+    "entryPoints": [
+      "src/index.ts"
+    ],
+    "tsconfig": "tsconfig.build.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint \"{src,test}/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config ../../vitest.config.ts --dir . --passWithNoTests"
+  }
 }