@paraharness/sqlite 0.0.0-stage → 0.2.0

package/dist/stores/internal/sqlite-suspended-fork-row.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Raw SQLite row shape for `harness_suspended_forks`.
+ *
+ * Maps snake_case columns for suspended fork persistence, filtering, and recursive epoch resolution.
+ */
+export interface SqliteSuspendedForkRow {
+    /** Monotonic `${forkId}#${suspensionEpoch}` identifier. */
+    readonly suspended_fork_id: string;
+    /** Logical fork identifier. */
+    readonly fork_id: string;
+    /** Positive integer suspension epoch. */
+    readonly suspension_epoch: number;
+    /** Enclosing flow run identifier. */
+    readonly run_id: string;
+    /** Parent step execution identifier. */
+    readonly parent_step_exec_id: string;
+    /** Full JSON-serialized `SuspendedForkRecord`. */
+    readonly record_json: string;
+    /** Resolution status (`'RESUMED' | 'ABORTED' | null`). */
+    readonly resolution_status: string | null;
+}
+//# sourceMappingURL=sqlite-suspended-fork-row.d.ts.map

package/dist/stores/internal/sqlite-suspended-fork-row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-suspended-fork-row.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-suspended-fork-row.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C"}

package/dist/stores/internal/sqlite-suspended-fork-row.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sqlite-suspended-fork-row.js.map

package/dist/stores/internal/sqlite-suspended-fork-row.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-suspended-fork-row.js","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-suspended-fork-row.ts"],"names":[],"mappings":""}

package/dist/stores/internal/sqlite-topology-base-row.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Raw SQLite row shape for `harness_topology_base`.
+ *
+ * Maps canonical base partition state columns for `SqliteTopologyStore`.
+ */
+export interface SqliteTopologyBaseRow {
+    /** Logical partition identifier. */
+    readonly partition_id: string;
+    /** Monotonic base epoch integer. */
+    readonly epoch: number;
+    /** Canonical contract text in the base store. */
+    readonly contract_text: string;
+    /** ISO-8601 timestamp of the last base update. */
+    readonly updated_at: string;
+    /** Run ID that most recently committed a mutation to this partition, or `null`. */
+    readonly last_mutated_by_run_id: string | null;
+}
+//# sourceMappingURL=sqlite-topology-base-row.d.ts.map

package/dist/stores/internal/sqlite-topology-base-row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-topology-base-row.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-topology-base-row.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,oCAAoC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CAChD"}

package/dist/stores/internal/sqlite-topology-base-row.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sqlite-topology-base-row.js.map

package/dist/stores/internal/sqlite-topology-base-row.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-topology-base-row.js","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-topology-base-row.ts"],"names":[],"mappings":""}

package/dist/stores/internal/sqlite-topology-commit-ops.d.ts

@@ -0,0 +1,37 @@
+import type { CommitRunOverlayResult } from '@paraharness/core';
+import type Database from 'better-sqlite3';
+/**
+ * Transitions `runId`'s overlay rows to `status = 'SEALED_UNMERGED'` (`SPEC.md` §3.3).
+ *
+ * Allows dependent stacked runs to absorb the sealed overlay via `syncRunOverlays` without polluting the base store.
+ *
+ * @param {Database.Database} db    - Active SQLite database handle.
+ * @param {string}            runId - Completed flow run identifier.
+ *
+ * @returns {void} Returns nothing once the overlay is sealed.
+ */
+export declare function sealOverlayForRun(db: Database.Database, runId: string): void;
+/**
+ * Atomically commits `runId`'s overlay (and any absorbed `SEALED_UNMERGED` prerequisite overlays)
+ * into `harness_topology_base` using a 3-way contract text merge (`SPEC.md` §3.3).
+ *
+ * Allocates `base.epoch = currentBase.epoch + 1` monotonically and returns `{ committedRunIds, updatedEpochs }`.
+ *
+ * @param {Database.Database} db    - Active SQLite database handle.
+ * @param {string}            runId - Flow run identifier whose overlay is committing.
+ *
+ * @returns {CommitRunOverlayResult} Committed run identifiers and newly allocated base epochs.
+ */
+export declare function commitOverlayThreeWayMerge(db: Database.Database, runId: string): CommitRunOverlayResult;
+/**
+ * Discards all uncommitted or sealed overlay rows for `runId` without modifying `harness_topology_base`.
+ *
+ * Used when a run fails, triggers `discardOnSignal`, or exceeds `maxSealedAgeHours`.
+ *
+ * @param {Database.Database} db    - Active SQLite database handle.
+ * @param {string}            runId - Flow run identifier whose overlay should be discarded.
+ *
+ * @returns {void} Returns nothing once the overlay is removed.
+ */
+export declare function discardOverlayForRun(db: Database.Database, runId: string): void;
+//# sourceMappingURL=sqlite-topology-commit-ops.d.ts.map

package/dist/stores/internal/sqlite-topology-commit-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-topology-commit-ops.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-topology-commit-ops.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAO3C;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAI5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,MAAM,GACZ,sBAAsB,CAoBxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAE/E"}

package/dist/stores/internal/sqlite-topology-commit-ops.js

@@ -0,0 +1,58 @@
+import { collectCommittedSqliteRunIds, mergeAndCommitSqliteOverlayRow, } from './sqlite-topology-overlay-commit.js';
+/**
+ * Transitions `runId`'s overlay rows to `status = 'SEALED_UNMERGED'` (`SPEC.md` §3.3).
+ *
+ * Allows dependent stacked runs to absorb the sealed overlay via `syncRunOverlays` without polluting the base store.
+ *
+ * @param {Database.Database} db    - Active SQLite database handle.
+ * @param {string}            runId - Completed flow run identifier.
+ *
+ * @returns {void} Returns nothing once the overlay is sealed.
+ */
+export function sealOverlayForRun(db, runId) {
+    db.prepare("UPDATE harness_topology_overlays SET status = 'SEALED_UNMERGED', updated_at = ? WHERE run_id = ?").run(new Date().toISOString(), runId);
+}
+/**
+ * Atomically commits `runId`'s overlay (and any absorbed `SEALED_UNMERGED` prerequisite overlays)
+ * into `harness_topology_base` using a 3-way contract text merge (`SPEC.md` §3.3).
+ *
+ * Allocates `base.epoch = currentBase.epoch + 1` monotonically and returns `{ committedRunIds, updatedEpochs }`.
+ *
+ * @param {Database.Database} db    - Active SQLite database handle.
+ * @param {string}            runId - Flow run identifier whose overlay is committing.
+ *
+ * @returns {CommitRunOverlayResult} Committed run identifiers and newly allocated base epochs.
+ */
+export function commitOverlayThreeWayMerge(db, runId) {
+    const overlayRows = db
+        .prepare('SELECT * FROM harness_topology_overlays WHERE run_id = ? AND (mutated_in_run = 1 OR has_uncommitted_changes = 1) ORDER BY partition_id ASC')
+        .all(runId);
+    const committedRunIds = collectCommittedSqliteRunIds(db, runId, overlayRows);
+    const updatedEpochs = new Map();
+    for (const ovRow of overlayRows) {
+        const newBaseEpoch = mergeAndCommitSqliteOverlayRow(db, ovRow, runId);
+        updatedEpochs.set(ovRow.partition_id, newBaseEpoch);
+    }
+    const deleteStmt = db.prepare('DELETE FROM harness_topology_overlays WHERE run_id = ?');
+    for (const committedId of committedRunIds) {
+        deleteStmt.run(committedId);
+    }
+    return Object.freeze({
+        committedRunIds,
+        updatedEpochs,
+    });
+}
+/**
+ * Discards all uncommitted or sealed overlay rows for `runId` without modifying `harness_topology_base`.
+ *
+ * Used when a run fails, triggers `discardOnSignal`, or exceeds `maxSealedAgeHours`.
+ *
+ * @param {Database.Database} db    - Active SQLite database handle.
+ * @param {string}            runId - Flow run identifier whose overlay should be discarded.
+ *
+ * @returns {void} Returns nothing once the overlay is removed.
+ */
+export function discardOverlayForRun(db, runId) {
+    db.prepare('DELETE FROM harness_topology_overlays WHERE run_id = ?').run(runId);
+}
+//# sourceMappingURL=sqlite-topology-commit-ops.js.map

package/dist/stores/internal/sqlite-topology-commit-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-topology-commit-ops.js","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-topology-commit-ops.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,qCAAqC,CAAC;AAG7C;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAqB,EAAE,KAAa;IACpE,EAAE,CAAC,OAAO,CACR,kGAAkG,CACnG,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CACxC,EAAqB,EACrB,KAAa;IAEb,MAAM,WAAW,GAAG,EAAE;SACnB,OAAO,CACN,4IAA4I,CAC7I;SACA,GAAG,CAAC,KAAK,CAA+B,CAAC;IAC5C,MAAM,eAAe,GAAG,4BAA4B,CAAC,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;IAC7E,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,YAAY,GAAG,8BAA8B,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACtE,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IACtD,CAAC;IACD,MAAM,UAAU,GAAG,EAAE,CAAC,OAAO,CAAC,wDAAwD,CAAC,CAAC;IACxF,KAAK,MAAM,WAAW,IAAI,eAAe,EAAE,CAAC;QAC1C,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAyB;QAC3C,eAAe;QACf,aAAa;KACd,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAAqB,EAAE,KAAa;IACvE,EAAE,CAAC,OAAO,CAAC,wDAAwD,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAClF,CAAC"}

package/dist/stores/internal/sqlite-topology-overlay-commit.d.ts

@@ -0,0 +1,25 @@
+import type Database from 'better-sqlite3';
+import type { SqliteTopologyOverlayRow } from './sqlite-topology-overlay-row.js';
+/**
+ * Collects all run IDs (`runId` plus any absorbed `SEALED_UNMERGED` prerequisite run IDs)
+ * whose overlays are being committed together in a single `commitRunOverlay` transaction.
+ *
+ * @param {Database.Database}                 db          - Active SQLite database handle.
+ * @param {string}                            runId       - Primary committing flow run identifier.
+ * @param {readonly SqliteTopologyOverlayRow[]} overlayRows - Modified overlay rows for `runId`.
+ *
+ * @returns {readonly string[]} Frozen list of committed run identifiers.
+ */
+export declare function collectCommittedSqliteRunIds(db: Database.Database, runId: string, overlayRows: readonly SqliteTopologyOverlayRow[]): readonly string[];
+/**
+ * Merges a single `SqliteTopologyOverlayRow` into `harness_topology_base` via 3-way merge
+ * and allocates a monotonically increasing base epoch (`currentBase.epoch + 1`).
+ *
+ * @param {Database.Database}        db    - Active SQLite database handle.
+ * @param {SqliteTopologyOverlayRow} ovRow - Overlay partition row to merge and commit.
+ * @param {string}                   runId - Committing flow run identifier.
+ *
+ * @returns {number} Newly allocated canonical base epoch for `ovRow.partition_id`.
+ */
+export declare function mergeAndCommitSqliteOverlayRow(db: Database.Database, ovRow: SqliteTopologyOverlayRow, runId: string): number;
+//# sourceMappingURL=sqlite-topology-overlay-commit.d.ts.map

package/dist/stores/internal/sqlite-topology-overlay-commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-topology-overlay-commit.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-topology-overlay-commit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAGjF;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,SAAS,wBAAwB,EAAE,GAC/C,SAAS,MAAM,EAAE,CAenB;AAED;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,wBAAwB,EAC/B,KAAK,EAAE,MAAM,GACZ,MAAM,CAiBR"}

package/dist/stores/internal/sqlite-topology-overlay-commit.js

@@ -0,0 +1,51 @@
+import { threeWayMergeContract } from './three-way-merge-contract.js';
+/**
+ * Collects all run IDs (`runId` plus any absorbed `SEALED_UNMERGED` prerequisite run IDs)
+ * whose overlays are being committed together in a single `commitRunOverlay` transaction.
+ *
+ * @param {Database.Database}                 db          - Active SQLite database handle.
+ * @param {string}                            runId       - Primary committing flow run identifier.
+ * @param {readonly SqliteTopologyOverlayRow[]} overlayRows - Modified overlay rows for `runId`.
+ *
+ * @returns {readonly string[]} Frozen list of committed run identifiers.
+ */
+export function collectCommittedSqliteRunIds(db, runId, overlayRows) {
+    const committedSet = new Set();
+    const selectSealedStmt = db.prepare("SELECT 1 AS found FROM harness_topology_overlays WHERE run_id = ? AND status = 'SEALED_UNMERGED' LIMIT 1");
+    for (const ovRow of overlayRows) {
+        const absorbedIds = JSON.parse(ovRow.absorbed_run_ids_json);
+        for (const absorbedId of absorbedIds) {
+            if (selectSealedStmt.get(absorbedId) !== undefined) {
+                committedSet.add(absorbedId);
+            }
+        }
+    }
+    committedSet.add(runId);
+    return Object.freeze(Array.from(committedSet));
+}
+/**
+ * Merges a single `SqliteTopologyOverlayRow` into `harness_topology_base` via 3-way merge
+ * and allocates a monotonically increasing base epoch (`currentBase.epoch + 1`).
+ *
+ * @param {Database.Database}        db    - Active SQLite database handle.
+ * @param {SqliteTopologyOverlayRow} ovRow - Overlay partition row to merge and commit.
+ * @param {string}                   runId - Committing flow run identifier.
+ *
+ * @returns {number} Newly allocated canonical base epoch for `ovRow.partition_id`.
+ */
+export function mergeAndCommitSqliteOverlayRow(db, ovRow, runId) {
+    const baseRow = db
+        .prepare('SELECT * FROM harness_topology_base WHERE partition_id = ?')
+        .get(ovRow.partition_id);
+    const currentBaseEpoch = baseRow?.epoch ?? 0;
+    const currentBaseText = baseRow?.contract_text ?? '';
+    const acquireBase = currentBaseText === ovRow.initial_base_contract_text
+        ? ovRow.initial_base_contract_text
+        : ovRow.base_contract_text_at_acquire;
+    const mergedText = threeWayMergeContract(acquireBase, currentBaseText, ovRow.contract_text);
+    const newBaseEpoch = currentBaseEpoch + 1;
+    const now = new Date().toISOString();
+    db.prepare('INSERT OR REPLACE INTO harness_topology_base (partition_id, epoch, contract_text, updated_at, last_mutated_by_run_id) VALUES (?, ?, ?, ?, ?)').run(ovRow.partition_id, newBaseEpoch, mergedText, now, ovRow.last_mutated_by_run_id ?? runId);
+    return newBaseEpoch;
+}
+//# sourceMappingURL=sqlite-topology-overlay-commit.js.map

package/dist/stores/internal/sqlite-topology-overlay-commit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-topology-overlay-commit.js","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-topology-overlay-commit.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAC1C,EAAqB,EACrB,KAAa,EACb,WAAgD;IAEhD,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,MAAM,gBAAgB,GAAG,EAAE,CAAC,OAAO,CACjC,0GAA0G,CAC3G,CAAC;IACF,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,qBAAqB,CAAa,CAAC;QACxE,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;YACrC,IAAI,gBAAgB,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,SAAS,EAAE,CAAC;gBACnD,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IACD,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,8BAA8B,CAC5C,EAAqB,EACrB,KAA+B,EAC/B,KAAa;IAEb,MAAM,OAAO,GAAG,EAAE;SACf,OAAO,CAAC,4DAA4D,CAAC;SACrE,GAAG,CAAC,KAAK,CAAC,YAAY,CAAsC,CAAC;IAChE,MAAM,gBAAgB,GAAG,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC;IAC7C,MAAM,eAAe,GAAG,OAAO,EAAE,aAAa,IAAI,EAAE,CAAC;IACrD,MAAM,WAAW,GACf,eAAe,KAAK,KAAK,CAAC,0BAA0B;QAClD,CAAC,CAAC,KAAK,CAAC,0BAA0B;QAClC,CAAC,CAAC,KAAK,CAAC,6BAA6B,CAAC;IAC1C,MAAM,UAAU,GAAG,qBAAqB,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5F,MAAM,YAAY,GAAG,gBAAgB,GAAG,CAAC,CAAC;IAC1C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,EAAE,CAAC,OAAO,CACR,8IAA8I,CAC/I,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,CAAC,sBAAsB,IAAI,KAAK,CAAC,CAAC;IAChG,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/stores/internal/sqlite-topology-overlay-ops.d.ts

@@ -0,0 +1,61 @@
+import type { TopologyPartitionState } from '@paraharness/core';
+import type Database from 'better-sqlite3';
+import type { UpdateContractInOverlayParams } from './update-contract-in-overlay-params.js';
+/**
+ * Options for resetting uncommitted overlay mutations in `resetRunOverlay`.
+ */
+export interface ResetRunOverlayOptions {
+    /** Rollback granularity (`'step'` for a single step execution or `'run'` for the entire run overlay). */
+    readonly scope?: 'step' | 'run';
+    /** Target `stepExecId` when `scope === 'step'`. */
+    readonly stepExecId?: string;
+}
+/**
+ * Loads the partition graph for `runId` (merging any uncommitted CoW overlay over `harness_topology_base`).
+ *
+ * Pins `base_contract_text_at_acquire` when `runId` first inspects each base partition (`SPEC.md` §3.3).
+ *
+ * @param {Database.Database} db      - Active SQLite database handle.
+ * @param {string}            [runId] - Optional active flow run identifier.
+ *
+ * @returns {ReadonlyMap<string, TopologyPartitionState>} Partition state map keyed by `partitionId`.
+ */
+export declare function getPartitionsWithOverlay(db: Database.Database, runId?: string): ReadonlyMap<string, TopologyPartitionState>;
+/**
+ * Writes a contract update to `params.runId`'s isolated CoW overlay and increments `epoch` at most once per `(runId, partitionId)`.
+ *
+ * Tags the mutation with `params.stepExecId` so `resetOverlayByScope` can roll back individual steps (`SPEC.md` §3.3).
+ *
+ * @param {Database.Database}             db     - Active SQLite database handle.
+ * @param {UpdateContractInOverlayParams} params - Contract update parameters.
+ *
+ * @returns {{ readonly newEpoch: number }} Updated overlay epoch for `params.partitionId`.
+ */
+export declare function updateContractInOverlay(db: Database.Database, params: UpdateContractInOverlayParams): {
+    readonly newEpoch: number;
+};
+/**
+ * Merges `ACTIVE` or `SEALED_UNMERGED` prerequisite overlays into `targetRunId`'s overlay (`SPEC.md` §3.3).
+ *
+ * Preserves `lastMutatedByRunId` and advances `targetRunId`'s `base_contract_text_at_acquire` to the prerequisite's `contract_text`.
+ *
+ * @param {Database.Database} db                 - Active SQLite database handle.
+ * @param {string}            targetRunId        - Dependent run absorbing the prerequisite overlays.
+ * @param {readonly string[]} prerequisiteRunIds - Prerequisite run IDs to merge from.
+ *
+ * @returns {void} Returns nothing once prerequisite overlays are absorbed.
+ */
+export declare function syncPrerequisiteOverlays(db: Database.Database, targetRunId: string, prerequisiteRunIds: readonly string[]): void;
+/**
+ * Resets uncommitted overlay mutations for `runId` at either the `'step'` or `'run'` scope (`SPEC.md` §3.3).
+ *
+ * Reverts only `opts.stepExecId` mutations when `scope === 'step'`, or reverts the entire run overlay to its baseline when `scope === 'run'`.
+ *
+ * @param {Database.Database}      db     - Active SQLite database handle.
+ * @param {string}                 runId  - Target flow run identifier.
+ * @param {ResetRunOverlayOptions} [opts] - Reset scope options.
+ *
+ * @returns {void} Returns nothing once the overlay reset is committed.
+ */
+export declare function resetOverlayByScope(db: Database.Database, runId: string, opts?: ResetRunOverlayOptions): void;
+//# sourceMappingURL=sqlite-topology-overlay-ops.d.ts.map

package/dist/stores/internal/sqlite-topology-overlay-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-topology-overlay-ops.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-topology-overlay-ops.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAQ3C,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,wCAAwC,CAAC;AAE5F;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,yGAAyG;IACzG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,CAAC,EAAE,MAAM,GACb,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CA4D7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,6BAA6B,GACpC;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CA6C/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,SAAS,MAAM,EAAE,GACpC,IAAI,CA0CN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,sBAAsB,GAC5B,IAAI,CA6CN"}

package/dist/stores/internal/sqlite-topology-overlay-ops.js

@@ -0,0 +1,156 @@
+import { computeSyncedSqliteOverlayValues, resolveNextSqliteAcquireBase, } from './sqlite-topology-overlay-sync.js';
+/**
+ * Loads the partition graph for `runId` (merging any uncommitted CoW overlay over `harness_topology_base`).
+ *
+ * Pins `base_contract_text_at_acquire` when `runId` first inspects each base partition (`SPEC.md` §3.3).
+ *
+ * @param {Database.Database} db      - Active SQLite database handle.
+ * @param {string}            [runId] - Optional active flow run identifier.
+ *
+ * @returns {ReadonlyMap<string, TopologyPartitionState>} Partition state map keyed by `partitionId`.
+ */
+export function getPartitionsWithOverlay(db, runId) {
+    const baseRows = db
+        .prepare('SELECT * FROM harness_topology_base ORDER BY partition_id ASC')
+        .all();
+    const partitions = new Map();
+    for (const baseRow of baseRows) {
+        partitions.set(baseRow.partition_id, Object.freeze({
+            partitionId: baseRow.partition_id,
+            epoch: baseRow.epoch,
+            contractText: baseRow.contract_text,
+            updatedAt: baseRow.updated_at,
+            lastMutatedByRunId: baseRow.last_mutated_by_run_id ?? undefined,
+        }));
+    }
+    if (runId === undefined) {
+        return partitions;
+    }
+    const overlayRows = db
+        .prepare('SELECT * FROM harness_topology_overlays WHERE run_id = ? ORDER BY partition_id ASC')
+        .all(runId);
+    const overlayPartitions = new Set();
+    for (const ovRow of overlayRows) {
+        overlayPartitions.add(ovRow.partition_id);
+        if (ovRow.has_uncommitted_changes === 1 || ovRow.mutated_in_run === 1) {
+            partitions.set(ovRow.partition_id, Object.freeze({
+                partitionId: ovRow.partition_id,
+                epoch: ovRow.epoch,
+                contractText: ovRow.contract_text,
+                updatedAt: ovRow.updated_at,
+                lastMutatedByRunId: ovRow.last_mutated_by_run_id ?? undefined,
+            }));
+        }
+    }
+    const pinStmt = db.prepare("INSERT OR IGNORE INTO harness_topology_overlays (run_id, partition_id, epoch, contract_text, base_contract_text_at_acquire, initial_base_contract_text, baseline_contract_text, baseline_epoch, baseline_last_mutated_by_run_id, mutated_in_run, has_uncommitted_changes, last_mutated_by_run_id, status, updated_at, absorbed_run_ids_json, step_mutations_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 0, ?, 'ACTIVE', ?, '[]', '[]')");
+    for (const baseRow of baseRows) {
+        if (!overlayPartitions.has(baseRow.partition_id)) {
+            pinStmt.run(runId, baseRow.partition_id, baseRow.epoch, baseRow.contract_text, baseRow.contract_text, baseRow.contract_text, baseRow.contract_text, baseRow.epoch, baseRow.last_mutated_by_run_id, baseRow.last_mutated_by_run_id, baseRow.updated_at);
+        }
+    }
+    return partitions;
+}
+/**
+ * Writes a contract update to `params.runId`'s isolated CoW overlay and increments `epoch` at most once per `(runId, partitionId)`.
+ *
+ * Tags the mutation with `params.stepExecId` so `resetOverlayByScope` can roll back individual steps (`SPEC.md` §3.3).
+ *
+ * @param {Database.Database}             db     - Active SQLite database handle.
+ * @param {UpdateContractInOverlayParams} params - Contract update parameters.
+ *
+ * @returns {{ readonly newEpoch: number }} Updated overlay epoch for `params.partitionId`.
+ */
+export function updateContractInOverlay(db, params) {
+    const baseRow = db
+        .prepare('SELECT * FROM harness_topology_base WHERE partition_id = ?')
+        .get(params.partitionId);
+    const ovRow = db
+        .prepare('SELECT * FROM harness_topology_overlays WHERE run_id = ? AND partition_id = ?')
+        .get(params.runId, params.partitionId);
+    const now = new Date().toISOString();
+    const baseEpoch = baseRow?.epoch ?? 0;
+    const baseText = baseRow?.contract_text ?? '';
+    const baseLastRun = baseRow?.last_mutated_by_run_id ?? null;
+    const currentEpoch = ovRow !== undefined ? ovRow.epoch : baseEpoch;
+    const alreadyMutated = ovRow !== undefined && ovRow.mutated_in_run === 1;
+    const newEpoch = alreadyMutated ? currentEpoch : currentEpoch + 1;
+    const history = ovRow !== undefined
+        ? JSON.parse(ovRow.step_mutations_json)
+        : [];
+    history.push({
+        stepExecId: params.stepExecId ?? null,
+        prevContractText: ovRow !== undefined ? ovRow.contract_text : baseText,
+        prevEpoch: currentEpoch,
+        prevMutatedInRun: ovRow !== undefined ? ovRow.mutated_in_run : 0,
+        prevHasUncommittedChanges: ovRow !== undefined ? ovRow.has_uncommitted_changes : 0,
+        prevLastMutatedByRunId: ovRow !== undefined ? ovRow.last_mutated_by_run_id : baseLastRun,
+    });
+    const acquireBase = resolveNextSqliteAcquireBase(ovRow, baseText);
+    db.prepare("INSERT OR REPLACE INTO harness_topology_overlays (run_id, partition_id, epoch, contract_text, base_contract_text_at_acquire, initial_base_contract_text, baseline_contract_text, baseline_epoch, baseline_last_mutated_by_run_id, mutated_in_run, has_uncommitted_changes, last_mutated_by_run_id, status, updated_at, absorbed_run_ids_json, step_mutations_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 1, ?, 'ACTIVE', ?, ?, ?)").run(params.runId, params.partitionId, newEpoch, params.newContractText, acquireBase, ovRow !== undefined ? ovRow.initial_base_contract_text : baseText, ovRow !== undefined ? ovRow.baseline_contract_text : baseText, ovRow !== undefined ? ovRow.baseline_epoch : baseEpoch, ovRow !== undefined ? ovRow.baseline_last_mutated_by_run_id : baseLastRun, params.runId, now, ovRow !== undefined ? ovRow.absorbed_run_ids_json : '[]', JSON.stringify(history));
+    return Object.freeze({ newEpoch });
+}
+/**
+ * Merges `ACTIVE` or `SEALED_UNMERGED` prerequisite overlays into `targetRunId`'s overlay (`SPEC.md` §3.3).
+ *
+ * Preserves `lastMutatedByRunId` and advances `targetRunId`'s `base_contract_text_at_acquire` to the prerequisite's `contract_text`.
+ *
+ * @param {Database.Database} db                 - Active SQLite database handle.
+ * @param {string}            targetRunId        - Dependent run absorbing the prerequisite overlays.
+ * @param {readonly string[]} prerequisiteRunIds - Prerequisite run IDs to merge from.
+ *
+ * @returns {void} Returns nothing once prerequisite overlays are absorbed.
+ */
+export function syncPrerequisiteOverlays(db, targetRunId, prerequisiteRunIds) {
+    const now = new Date().toISOString();
+    const selectPrereqStmt = db.prepare("SELECT * FROM harness_topology_overlays WHERE run_id = ? AND status IN ('ACTIVE', 'SEALED_UNMERGED') AND (mutated_in_run = 1 OR has_uncommitted_changes = 1)");
+    const selectTargetStmt = db.prepare('SELECT * FROM harness_topology_overlays WHERE run_id = ? AND partition_id = ?');
+    const upsertStmt = db.prepare('INSERT OR REPLACE INTO harness_topology_overlays (run_id, partition_id, epoch, contract_text, base_contract_text_at_acquire, initial_base_contract_text, baseline_contract_text, baseline_epoch, baseline_last_mutated_by_run_id, mutated_in_run, has_uncommitted_changes, last_mutated_by_run_id, status, updated_at, absorbed_run_ids_json, step_mutations_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?)');
+    for (const prereqRunId of prerequisiteRunIds) {
+        const prereqRows = selectPrereqStmt.all(prereqRunId);
+        for (const prereqRow of prereqRows) {
+            const targetRow = selectTargetStmt.get(targetRunId, prereqRow.partition_id);
+            const synced = computeSyncedSqliteOverlayValues({
+                targetRunId,
+                prereqRunId,
+                prereqRow,
+                targetRow,
+            });
+            upsertStmt.run(targetRunId, prereqRow.partition_id, synced.nextEpoch, synced.mergedContractText, synced.nextAcquireBase, synced.initialBase, prereqRow.contract_text, synced.nextEpoch, prereqRow.last_mutated_by_run_id, synced.mutatedInRun, synced.nextLastMutatedBy, synced.status, now, synced.absorbedRunIdsJson, synced.stepMutationsJson);
+        }
+    }
+}
+/**
+ * Resets uncommitted overlay mutations for `runId` at either the `'step'` or `'run'` scope (`SPEC.md` §3.3).
+ *
+ * Reverts only `opts.stepExecId` mutations when `scope === 'step'`, or reverts the entire run overlay to its baseline when `scope === 'run'`.
+ *
+ * @param {Database.Database}      db     - Active SQLite database handle.
+ * @param {string}                 runId  - Target flow run identifier.
+ * @param {ResetRunOverlayOptions} [opts] - Reset scope options.
+ *
+ * @returns {void} Returns nothing once the overlay reset is committed.
+ */
+export function resetOverlayByScope(db, runId, opts) {
+    const rows = db
+        .prepare('SELECT * FROM harness_topology_overlays WHERE run_id = ?')
+        .all(runId);
+    const now = new Date().toISOString();
+    if (opts?.scope === 'step' && opts.stepExecId !== undefined) {
+        for (const row of rows) {
+            const history = JSON.parse(row.step_mutations_json);
+            const firstMatchIdx = history.findIndex((entry) => entry.stepExecId === opts.stepExecId);
+            const restoreTarget = firstMatchIdx >= 0 ? history[firstMatchIdx] : undefined;
+            if (restoreTarget !== undefined) {
+                const remaining = history.slice(0, firstMatchIdx);
+                db.prepare('UPDATE harness_topology_overlays SET contract_text = ?, epoch = ?, mutated_in_run = ?, has_uncommitted_changes = ?, last_mutated_by_run_id = ?, step_mutations_json = ?, updated_at = ? WHERE run_id = ? AND partition_id = ?').run(restoreTarget.prevContractText, restoreTarget.prevEpoch, restoreTarget.prevMutatedInRun, restoreTarget.prevHasUncommittedChanges, restoreTarget.prevLastMutatedByRunId, JSON.stringify(remaining), now, runId, row.partition_id);
+            }
+        }
+        return;
+    }
+    for (const row of rows) {
+        const hasSyncedBaseline = row.baseline_contract_text !== row.initial_base_contract_text ||
+            row.absorbed_run_ids_json !== '[]';
+        db.prepare("UPDATE harness_topology_overlays SET contract_text = ?, epoch = ?, mutated_in_run = 0, has_uncommitted_changes = ?, last_mutated_by_run_id = ?, step_mutations_json = '[]', updated_at = ? WHERE run_id = ? AND partition_id = ?").run(row.baseline_contract_text, row.baseline_epoch, hasSyncedBaseline ? 1 : 0, row.baseline_last_mutated_by_run_id, now, runId, row.partition_id);
+    }
+}
+//# sourceMappingURL=sqlite-topology-overlay-ops.js.map

package/dist/stores/internal/sqlite-topology-overlay-ops.js.map

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

package/dist/stores/internal/sqlite-topology-overlay-row.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Raw SQLite row shape for `harness_topology_overlays`.
+ *
+ * Tracks per-run Copy-on-Write partition overlays, pinned 3-way merge baselines, and step mutation history.
+ */
+export interface SqliteTopologyOverlayRow {
+    /** Active or sealed flow run identifier. */
+    readonly run_id: string;
+    /** Logical partition identifier. */
+    readonly partition_id: string;
+    /** Current overlay epoch number. */
+    readonly epoch: number;
+    /** Current overlay contract text. */
+    readonly contract_text: string;
+    /** Pinned 3-way merge-base contract text (advanced on `syncRunOverlays`). */
+    readonly base_contract_text_at_acquire: string;
+    /** Initial canonical base contract text when the overlay chain was first acquired. */
+    readonly initial_base_contract_text: string;
+    /** Run-start or synced-prerequisite baseline contract text for `scope: 'run'` resets. */
+    readonly baseline_contract_text: string;
+    /** Run-start or synced-prerequisite baseline epoch for `scope: 'run'` resets. */
+    readonly baseline_epoch: number;
+    /** Run-start or synced-prerequisite `last_mutated_by_run_id` for `scope: 'run'` resets. */
+    readonly baseline_last_mutated_by_run_id: string | null;
+    /** `1` if `updateContract` was already called in `run_id` since the last reset, `0` otherwise. */
+    readonly mutated_in_run: number;
+    /** `1` if the overlay carries uncommitted or absorbed prerequisite changes, `0` if purely pinned on read. */
+    readonly has_uncommitted_changes: number;
+    /** Run ID that most recently mutated this partition in the overlay lineage, or `null`. */
+    readonly last_mutated_by_run_id: string | null;
+    /** Overlay lifecycle status (`'ACTIVE' | 'SEALED_UNMERGED'`). */
+    readonly status: string;
+    /** ISO-8601 timestamp of the latest overlay update. */
+    readonly updated_at: string;
+    /** JSON-serialized `string[]` of prerequisite run IDs absorbed via `syncRunOverlays`. */
+    readonly absorbed_run_ids_json: string;
+    /** JSON-serialized `SqliteOverlayStepMutationEntry[]` for step-scoped rollback. */
+    readonly step_mutations_json: string;
+}
+//# sourceMappingURL=sqlite-topology-overlay-row.d.ts.map

package/dist/stores/internal/sqlite-topology-overlay-row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-topology-overlay-row.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-topology-overlay-row.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,6BAA6B,EAAE,MAAM,CAAC;IAC/C,sFAAsF;IACtF,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;IAC5C,yFAAyF;IACzF,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,iFAAiF;IACjF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,+BAA+B,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,kGAAkG;IAClG,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,6GAA6G;IAC7G,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,0FAA0F;IAC1F,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,mFAAmF;IACnF,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC"}

package/dist/stores/internal/sqlite-topology-overlay-row.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sqlite-topology-overlay-row.js.map

package/dist/stores/internal/sqlite-topology-overlay-row.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-topology-overlay-row.js","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-topology-overlay-row.ts"],"names":[],"mappings":""}

package/dist/stores/internal/sqlite-topology-overlay-sync.d.ts

@@ -0,0 +1,72 @@
+import type { SqliteTopologyOverlayRow } from './sqlite-topology-overlay-row.js';
+/**
+ * Parameters for computing a merged SQLite overlay row when absorbing a prerequisite run's overlay.
+ */
+export interface ComputeSyncedSqliteOverlayParams {
+    /** Dependent run identifier absorbing the prerequisite overlay. */
+    readonly targetRunId: string;
+    /** Prerequisite run identifier being absorbed. */
+    readonly prereqRunId: string;
+    /** Prerequisite run's active or sealed overlay row. */
+    readonly prereqRow: SqliteTopologyOverlayRow;
+    /** Target run's existing overlay row for the same partition, if any. */
+    readonly targetRow: SqliteTopologyOverlayRow | undefined;
+}
+/**
+ * Computed column values for upserting an absorbed prerequisite overlay into `targetRunId`'s overlay.
+ */
+export interface SyncedSqliteOverlayValuesOptions {
+    /** Merged overlay epoch (`max(target.epoch, prereq.epoch)`). */
+    readonly nextEpoch: number;
+    /** 3-way merged contract text. */
+    readonly mergedContractText: string;
+    /** Updated `base_contract_text_at_acquire` for subsequent 3-way commit merges. */
+    readonly nextAcquireBase: string;
+    /** Preserved initial base contract text when `targetRunId` first acquired the partition. */
+    readonly initialBase: string;
+    /** Run identifier credited with the latest contract mutation. */
+    readonly nextLastMutatedBy: string | null;
+    /** JSON array of absorbed prerequisite run identifiers. */
+    readonly absorbedRunIdsJson: string;
+    /** Flag (`0` or `1`) indicating whether `targetRunId` itself mutated this partition. */
+    readonly mutatedInRun: number;
+    /** Overlay lifecycle status (`'ACTIVE'` or `'SEALED_UNMERGED'`). */
+    readonly status: string;
+    /** JSON-serialized step mutation rollback log. */
+    readonly stepMutationsJson: string;
+}
+/**
+ * Parameters for resolving a single field when folding a prerequisite overlay into a target overlay in SQLite.
+ */
+export interface ResolveSyncedSqliteOverlayFieldParams {
+    /** Prerequisite run's overlay row being absorbed. */
+    readonly prereqRow: SqliteTopologyOverlayRow;
+    /** Target run's existing overlay row, if any. */
+    readonly targetRow: SqliteTopologyOverlayRow | undefined;
+    /** Whether `prereqRow` already absorbed `targetRunId` (stacked child fold). */
+    readonly isStackedChildFold: boolean;
+}
+/**
+ * Resolves the `base_contract_text_at_acquire` value to persist when updating a partition contract in an overlay.
+ *
+ * Preserves `ovRow.base_contract_text_at_acquire` when already mutated in the current run,
+ * uses `ovRow.baseline_contract_text` on the first mutation after a prerequisite sync,
+ * or falls back to `baseText` when creating a fresh overlay row.
+ *
+ * @param {SqliteTopologyOverlayRow | undefined} ovRow    - Existing overlay row for `(runId, partitionId)`, if any.
+ * @param {string}                               baseText - Canonical base contract text.
+ *
+ * @returns {string} Acquire-base contract text to store on the overlay row.
+ */
+export declare function resolveNextSqliteAcquireBase(ovRow: SqliteTopologyOverlayRow | undefined, baseText: string): string;
+/**
+ * Computes the merged overlay state when synchronizing `params.prereqRow` into `params.targetRunId`.
+ *
+ * Performs a 3-way contract merge when `targetRow` also mutated the partition and unions absorbed run IDs.
+ *
+ * @param {ComputeSyncedSqliteOverlayParams} params - Target and prerequisite overlay rows.
+ *
+ * @returns {SyncedSqliteOverlayValuesOptions} Computed column values for upserting the target overlay row.
+ */
+export declare function computeSyncedSqliteOverlayValues(params: ComputeSyncedSqliteOverlayParams): SyncedSqliteOverlayValuesOptions;
+//# sourceMappingURL=sqlite-topology-overlay-sync.d.ts.map

package/dist/stores/internal/sqlite-topology-overlay-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-topology-overlay-sync.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/sqlite-topology-overlay-sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAGjF;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,wBAAwB,CAAC;IAC7C,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,wBAAwB,GAAG,SAAS,CAAC;CAC1D;AAED;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kCAAkC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,kFAAkF;IAClF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,2DAA2D;IAC3D,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,wFAAwF;IACxF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,qCAAqC;IACpD,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,wBAAwB,CAAC;IAC7C,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,wBAAwB,GAAG,SAAS,CAAC;IACzD,+EAA+E;IAC/E,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,wBAAwB,GAAG,SAAS,EAC3C,QAAQ,EAAE,MAAM,GACf,MAAM,CAQR;AA4CD;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,gCAAgC,GACvC,gCAAgC,CAgDlC"}