@open-tomato/rafa 0.45.0 → 0.46.0

package/dist/effort/store/merge-rules.d.ts

@@ -0,0 +1,82 @@
+/**
+ * What a merge of two effort stores does with each table: the registry
+ * every table of the SQLite store has an entry in.
+ *
+ * ## Scope
+ *
+ * A `merged` table travels: a merge unions its rows from both stores,
+ * one copy of each identity. Each carries `origin_store` and
+ * `origin_seq`, since migration `row-origins` or, for a table created
+ * after it, from its own migration, with the partial unique index
+ * `<table>_by_origin` over the pair, and is one of the
+ * `ORIGIN_TABLES` (`origins.ts`). A `local` table never leaves its
+ * machine: the migration log, the store's identity row, the ids it
+ * replaced and the merge trail describe this one file, and a merge neither reads them from the
+ * other store nor writes them from it.
+ *
+ * ## Identity
+ *
+ * The columns that make two rows of a merged table the same row, for a
+ * row whose origin is NULL, as every row written before `row-origins`
+ * or by an older runtime is. A UUID `id` where the table has one, the
+ * session id for sessions and dispatches, the sha for commits, and the
+ * natural key the table's own UNIQUE constraint or index names for the
+ * rest. Two NULLs in an identity column count as equal, as the
+ * `ifnull` of `skill_invocations_by_use` counts them.
+ *
+ * ## Edited fields
+ *
+ * The store is almost append-only. A column a production statement
+ * changes after the insert is an edited field, and the merge has to know
+ * which of two stores' values to keep. There are two today.
+ * `findings.tracker_ref`, written by `writeTrackerRef`
+ * (`tracker-refs.ts`) once a bug is filed, is {@link SET_ONCE}: a
+ * filled value beats NULL, and two different filled values mean one
+ * finding was filed twice, which the merge keeps in `merge_conflicts`.
+ * A reference that supersedes another is a row of its own, never a new
+ * value of this field; the `findings` entry says how.
+ * `commits.row_json` is {@link RECOMPUTED}: its `minutesSincePrevious`
+ * is rewritten by the merge itself (`merge-commit-gaps.ts`) for each
+ * commit brought in and the commit after it in time, so two rows of one
+ * commit that differ only in that key are the same row.
+ *
+ * ## What holds the registry to the schema
+ *
+ * `merge-rules.sweep.test.ts` reads a store brought through every migration
+ * and fails on a table with no entry, an entry with no table, a merged
+ * table without both origin columns and their partial unique index, an
+ * identity or edited column the table lacks, and a production edit of a
+ * merged table's column that has no rule here. A migration that adds a
+ * table therefore adds its entry in the same commit.
+ */
+/** Whether a merge unions a table's rows or leaves the table on its machine. */
+export type MergeScope = 'merged' | 'local';
+/**
+ * A filled value beats NULL, and two different filled values are both
+ * kept, the incoming one as a conflict.
+ */
+export declare const SET_ONCE = "set-once";
+/**
+ * The merge recomputes the field from the rows it holds, so two stores'
+ * values of it are never compared: for `commits.row_json`, its
+ * `minutesSincePrevious` key.
+ */
+export declare const RECOMPUTED = "recomputed";
+/** How a merge settles an edited field whose two stores disagree. */
+export type EditRule = typeof SET_ONCE | typeof RECOMPUTED;
+/** A table a merge unions. */
+export interface MergedTableRule {
+    readonly scope: 'merged';
+    /** The columns two rows with a NULL origin are matched by. */
+    readonly identity: readonly string[];
+    /** Every column a production statement changes after the insert, with its rule. */
+    readonly edited: Readonly<Record<string, EditRule>>;
+}
+/** A table that never leaves its machine. */
+export interface LocalTableRule {
+    readonly scope: 'local';
+}
+/** One table's entry in {@link MERGE_RULES}. */
+export type MergeRule = MergedTableRule | LocalTableRule;
+/** Every table of the SQLite store, by name, and what a merge does with it. */
+export declare const MERGE_RULES: Readonly<Record<string, MergeRule>>;

package/dist/effort/store/merge-store.d.ts

@@ -0,0 +1,211 @@
+/**
+ * The merge `rafa effort merge` runs: another device's store file
+ * unioned into this store, built beside it, checked, and swapped in
+ * behind a whole-file backup.
+ *
+ * ## What it refuses
+ *
+ * Every refusal comes before anything is built or copied, so both files
+ * keep their bytes. In the order they are asked:
+ *
+ *   - A project whose `store` is `ndjson`: its sessions and commits are
+ *     NDJSON, which carries no origin, so a merge needs the SQLite
+ *     backend. The text names {@link MOVE_TO_SQLITE}. The backend is the
+ *     caller's resolved config, never read here.
+ *   - A store file absent on either side, and a journal or write-ahead
+ *     log beside either one (`refuseInFlight`, `rebuild-aside.ts`).
+ *   - A damaged other file: one SQLite cannot open as a database, or
+ *     whose `integrity_check` answers anything but `ok`. A plain file
+ *     copy taken during a write holds a half-written page; a copy made
+ *     by `rafa effort copy` is consistent.
+ *   - A store on either side that `planSchema` (`schema-plan.ts`) will
+ *     not let this rafa write, with the plan's own text.
+ *   - Another project's store: both stores name a project, and their
+ *     root commits differ. The project of each is the one its
+ *     `store_meta` row records; this store, when it has not been
+ *     minted, takes the one git reads in its directory. A side that
+ *     names none, such as a store only an older runtime wrote, cannot
+ *     be told apart and is merged, and the `merges` row then names no
+ *     other store.
+ *
+ * Two more are asked only of a swap, since a dry run reads the stores
+ * and deletes what it builds, as `effort migrate`'s is:
+ *
+ *   - From a development build, over a store it does not own, with
+ *     `refuseUnownedDevelopmentWrite`'s text (`development-build.ts`).
+ *     What it names is what the swap records: the migrations this store
+ *     has pending, then `merges`, the table the merge writes its row to.
+ *   - While a loop record under the store's project reads `running` or
+ *     `paused` with its pid alive (`liveLoop`, `migrate.ts`): renaming
+ *     the store under a loop loses what the loop writes. The record
+ *     whose session id `sessionId` names is passed: it is the run
+ *     pulling at the end of its own task, between task sessions, so
+ *     nothing of its own writes into the store under the swap. It is
+ *     matched by session id, never by pid, so a second live record
+ *     sharing that pid is still refused.
+ *
+ * ## The other store
+ *
+ * It is only ever read. It is opened `{ readonly: true }` when it holds
+ * every migration this rafa knows. When it lacks some, it is written
+ * out with `VACUUM INTO` (`vacuumInto`, `copy.ts`) to a directory of
+ * its own under the temporary directory, that copy is brought forward
+ * (`bringForward`, `builtAside`), and the copy is what the union reads;
+ * the directory is removed once the merge ends, refused or not. A store
+ * logging a migration this rafa does not know adds columns the union
+ * refuses (`UnionSchemaMismatch`, `merge-union.ts`), and that refusal
+ * is passed on.
+ *
+ * ## The build
+ *
+ * The parallel file, `<store>.merge-<stamp>`, is this store written out
+ * by `vacuumInto` and brought forward there with `builtAside`, each new
+ * log row naming this runtime (`appliedByName`). In one transaction on
+ * it, the union (`unionStores`) inserts every unmatched row of each
+ * merged table, the conflict step (`settleMatches`,
+ * `merge-conflicts.ts`) settles each matched pair and records in
+ * `merge_conflicts` what no rule settles, the commit gaps of each commit
+ * brought in and of the commit after it are recomputed
+ * (`recomputeCommitGaps`, `merge-commit-gaps.ts`), and one `merges` row
+ * records the merge: its id, the other store's id, when, and the rows
+ * added, skipped and in conflict over every merged table.
+ *
+ * The live store is then attached, and every table both files hold,
+ * the log apart, must hold its live row count plus the rows the merge
+ * added to it (`checkedCounts`): the rows added to each merged table,
+ * one row in `merges`, and one in `merge_conflicts` per conflict. A
+ * merged table's fills and gap rewrites change no count. SQLite's
+ * `integrity_check` must answer `ok`, and `planSchema` must find the
+ * file one this rafa uses as it is (`refuseUnusable`, `fix-schema.ts`).
+ *
+ * Under `dryRun` the parallel file is then deleted, and the answer says
+ * what the merge would have done. Otherwise the parallel file is
+ * swapped in (`swapIn`, `rebuild-aside.ts`): this store is written out
+ * to `<store>.before-merge-<stamp>.bak` with `VACUUM INTO`, its identity
+ * is carried onto the parallel file (`carryStoreIdentity`,
+ * `store-meta.ts`), and the parallel file is renamed into its place.
+ *
+ * ## The store keeps its id
+ *
+ * `store_meta` is `local` in `MERGE_RULES`, so the parallel file holds
+ * this store's own row and never the other store's. The carry gives it
+ * the device, inode and generation the rename brings to this store's
+ * path, so the merged store keeps this store's origin, and the rows it
+ * writes next carry the same store id. A store whose next write would
+ * have minted anyway, being a copy already, is carried nothing and
+ * mints on its first write after the swap.
+ *
+ * The backup holds every row the original held, and restoring it is
+ * renaming it back. It is a copy with an inode of its own, so once
+ * renamed back over the store its first writing open mints a new
+ * origin, as any restored copy must (`store-identity.ts`).
+ *
+ * ## What the counts leave out
+ *
+ * An unmatched incoming row the union could not insert, because it
+ * collides with a row here on another UNIQUE key, is answered per table
+ * as `collided` and kept in the other file only: it is neither added,
+ * skipped nor recorded, since `merge_conflicts` names a local row and
+ * the union does not know which one it collided with.
+ *
+ * It opens both stores itself rather than through `withSqliteStore`, so
+ * it runs the test guard (`guardTestProcess`, `location.ts`) itself,
+ * over both paths, before it reads anything.
+ */
+import type { DevelopmentProbe } from './development-build.js';
+import type { SqliteMigration } from './migrations.js';
+import type { ProjectIdentity } from './store-identity.js';
+import type { StoreBackend } from '../../core/config/sections.js';
+import { RebuildRefusal } from './rebuild-aside.js';
+/** The command that moves an NDJSON project's rows into the SQLite store. */
+export declare const MOVE_TO_SQLITE = "rafa effort move --to=sqlite";
+/** Why a merge was refused before anything was built. */
+export type MergeRefusalReason = 
+/** The project's `store` is `ndjson`. */
+'ndjson'
+/** A store file is absent. */
+ | 'missing'
+/** The other file is no SQLite database, or fails `integrity_check`. */
+ | 'damaged'
+/** A store's schema is one this rafa will not write. */
+ | 'schema'
+/** The two stores name different projects. */
+ | 'other-project'
+/** A loop records to this store. */
+ | 'live-loop';
+/** A merge refused before either store was changed. */
+export declare class MergeRefusal extends RebuildRefusal {
+    readonly reason: MergeRefusalReason;
+    constructor(reason: MergeRefusalReason, message: string);
+}
+/** What the run did. */
+export type MergeStatus = 
+/** Under `dryRun`: the merged store was built, checked and deleted. */
+'would-merge'
+/** The merged store was swapped in and the original kept as a backup. */
+ | 'merged';
+/** What the merge did with one merged table's incoming rows. */
+export interface TableMerge {
+    readonly table: string;
+    /** Rows inserted with a new local `seq`. */
+    readonly added: number;
+    /** Matched rows left with equal content, fills included. */
+    readonly skipped: number;
+    /** `merge_conflicts` rows recorded. */
+    readonly inConflict: number;
+    /** Set-once fields this store took from the other. */
+    readonly filled: number;
+    /** Unmatched rows another UNIQUE key refused; see the module note. */
+    readonly collided: number;
+}
+/** The outcome of one run. */
+export interface MergeResult {
+    /** This store's file. */
+    readonly path: string;
+    /** The other store's file. */
+    readonly otherPath: string;
+    readonly status: MergeStatus;
+    /** The `merges.id` the merge recorded. */
+    readonly mergeId: string;
+    /** The other store's id, or null when it was never minted. */
+    readonly otherStore: string | null;
+    /** What the other store's copy was brought forward through; empty when it was read as it is. */
+    readonly otherBroughtForward: readonly string[];
+    /** One entry per merged table, in `MERGE_RULES` order. */
+    readonly tables: readonly TableMerge[];
+    readonly rowsAdded: number;
+    readonly rowsSkipped: number;
+    readonly rowsInConflict: number;
+    /** Commit rows whose gap was rewritten. */
+    readonly gapsRewritten: number;
+    /** Where the original went, for `merged` only. */
+    readonly backupPath: string | null;
+}
+/** What one run is handed; the {@link DevelopmentProbe} fields say which build runs and which stores it owns. */
+export interface MergeOptions extends DevelopmentProbe {
+    /** This store's file. */
+    readonly path: string;
+    /** The other store's file, only ever read. */
+    readonly otherPath: string;
+    /** The project's resolved `store` backend. */
+    readonly backend: StoreBackend;
+    /** Build and check the merged store, then delete it instead of swapping it in. */
+    readonly dryRun: boolean;
+    /** Names the parallel and backup files, so two runs never collide. */
+    readonly stamp: string;
+    /** The catalogue both stores are brought to: this build's unless a test passes another. */
+    readonly migrations?: readonly SqliteMigration[];
+    /** The clock `merged_at` and new log rows read. */
+    readonly now?: () => Date;
+    /** A new merge id; `crypto.randomUUID` when absent. */
+    readonly newMergeId?: () => string;
+    /** The project of the repository holding `dir`, for an unminted store; `readProjectIdentity` when absent. */
+    readonly readProject?: (dir: string) => ProjectIdentity;
+    /**
+     * The session id of the loop run merging, whose own live record the
+     * live-loop guard passes; absent or null for a caller that is no run.
+     */
+    readonly sessionId?: string | null;
+}
+/** Merges the store at `options.otherPath` into the one at `options.path`. See the module note. */
+export declare function mergeStore(options: MergeOptions): MergeResult;

package/dist/effort/store/merge-union.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The union at the heart of a merge: every row of each `merged` table in
+ * another store that matches no row here is inserted here, so the two
+ * stores' rows end up in this one, one copy of each.
+ *
+ * ## Matching
+ *
+ * An incoming row is looked up here in two steps, and the first to find
+ * a row wins:
+ *
+ * 1. **The origin pair.** An incoming row whose `origin_store` and
+ *    `origin_seq` are both set matches the row here holding the same
+ *    pair. The pair is unique wherever it is set (`<table>_by_origin`),
+ *    so at most one row answers.
+ * 2. **Identity.** Otherwise the row matches the row here holding the
+ *    same values in the table's identity columns from `MERGE_RULES`
+ *    (`merge-rules.ts`): `session_id` for sessions and dispatches, `sha`
+ *    for commits, `id` for the UUID tables, `(pr, head_sha, read_at)`
+ *    for `plan_ci`. Two NULLs count as equal, as `IS` compares them.
+ *
+ * Step 2 is what a row with a NULL origin, on either side, is matched
+ * by. It also runs when both rows carry a pair and the pairs differ,
+ * because every identity is a UNIQUE key of its table: a commit two
+ * devices collected from one pushed history holds one sha under two
+ * origins, and the table could not hold both. Such a match, and one on
+ * a pair whose two rows differ, is what the merge's conflict step reads
+ * the {@link UnionMatch} list for; the union itself compares no content.
+ *
+ * ## Inserting
+ *
+ * An unmatched row is inserted with a new local `seq`, named in the
+ * insert as `COALESCE(MAX(seq), 0) + 1` for the reason `origins.ts`
+ * gives, and every other column as the other store holds it: its origin
+ * pair unchanged, NULL staying NULL. Rows go in in the other store's
+ * `seq` order, and each lookup reads the rows inserted before it, so two
+ * rows of one identity in the other store land as one.
+ *
+ * An unmatched row can still collide with a row here on one of the
+ * table's other UNIQUE keys, such as `findings_by_artifact`, when one
+ * report was stored under two UUIDs. Nothing in `MERGE_RULES` says which
+ * row that is, so the row is not inserted and is returned as a
+ * {@link UnionCollision}; the union goes on with the next row.
+ *
+ * ## What it refuses
+ *
+ * Both stores must hold the same columns in every merged table, which
+ * the merge sees to by bringing both to the same migrations first. A
+ * column one side lacks would be dropped from every row copied or read
+ * as NULL, so the union checks every table before it inserts anything
+ * and throws {@link UnionSchemaMismatch} naming the columns. The inserts
+ * run in one transaction on `local`; `other` is only read.
+ */
+import type { Database } from 'bun:sqlite';
+/** Which of the two lookups found an incoming row's match. */
+export type MatchedBy = 'origin' | 'identity';
+/** An incoming row that matched a row already here, which the union left alone. */
+export interface UnionMatch {
+    /** The local row's `seq`. */
+    readonly localSeq: number;
+    /** The incoming row's `seq` in the other store. */
+    readonly incomingSeq: number;
+    readonly by: MatchedBy;
+}
+/** An unmatched incoming row the table refused on another of its UNIQUE keys. */
+export interface UnionCollision {
+    /** The incoming row's `seq` in the other store. */
+    readonly incomingSeq: number;
+    /** SQLite's own message, naming the key. */
+    readonly reason: string;
+}
+/** What the union did with one merged table. */
+export interface TableUnion {
+    readonly table: string;
+    /** The local `seq` of each row inserted, in insert order. */
+    readonly added: readonly number[];
+    readonly matched: readonly UnionMatch[];
+    readonly collided: readonly UnionCollision[];
+}
+/** The two stores disagree on the columns of a merged table. */
+export declare class UnionSchemaMismatch extends Error {
+    constructor(message: string);
+}
+/** The columns of `table` other than `seq`, in table order. */
+export declare function carriedColumns(db: Database, table: string): string[];
+/**
+ * Inserts into `local` every row of each merged table of `other` that
+ * matches no row of `local`, as the module note says, and answers what
+ * it did with each table, in `MERGE_RULES` order. Throws
+ * {@link UnionSchemaMismatch}, having inserted nothing, when the two
+ * stores hold different columns in any merged table.
+ */
+export declare function unionStores(local: Database, other: Database): TableUnion[];

package/dist/effort/store/migrate.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The forward move `rafa effort migrate` runs: a SQLite store's pending
+ * migrations, breaking ones included, applied to a copy built beside it,
+ * checked, and swapped in behind a whole-file backup.
+ *
+ * ## What it applies
+ *
+ * The decision is `planSchema`'s (`schema-plan.ts`), asked for a write
+ * by the `migrate` caller, the one caller a pending breaking migration
+ * does not refuse. The store's `user_version` and migration log are read
+ * on a read-only connection, so a store with nothing to write keeps its
+ * bytes.
+ *
+ *   - A store with nothing to adopt or apply is `current`, and left alone.
+ *   - A store `planSchema` refuses is refused with the plan's own text,
+ *     which ends with the command to run next. `breaking-pending` never
+ *     comes back, since this is the caller it names.
+ *   - Otherwise the store is brought forward aside: adopted when it has
+ *     no log, then every pending migration applied in catalogue order.
+ *
+ * ## The build
+ *
+ * The parallel file, `<store>.migrate-<stamp>`, is the live store written
+ * out by `VACUUM INTO` on a read-only connection (`vacuumInto`,
+ * `copy.ts`), which keeps `user_version` and the log. It is brought
+ * forward there by the log-aware apply (`bringForward`,
+ * `bring-forward.ts`) as the `migrate` caller, each row's `applied_by`
+ * naming this runtime (`appliedByName`, `development-build.ts`). The live
+ * store is then attached, and the row count of every table both files
+ * hold, the log apart, must equal the live one (`checkedCounts`): a
+ * breaking table rebuild that lost a row is refused there. SQLite's
+ * `integrity_check` must answer `ok`, and `planSchema` must find the file
+ * one this rafa uses as it is (`refuseUnusable`, `fix-schema.ts`).
+ *
+ * Under `dryRun` the parallel file is then deleted. Otherwise the live
+ * store is written out to `<store>.before-<id>-<stamp>.bak` with
+ * `VACUUM INTO`, its identity is carried onto the parallel file
+ * (`carryStoreIdentity`, `store-meta.ts`), and the parallel file is
+ * renamed into its place. `<id>` is the first migration applied, or
+ * `schema_migrations` when the run only adopts the store.
+ *
+ * The migrated store keeps the live store's origin, so the rows it
+ * writes next carry the same store id; a store whose next write would
+ * have minted anyway is carried nothing and mints after the swap. The
+ * backup holds every row the original held, and restoring it is
+ * renaming it back. It is a copy with an inode of its own, so once
+ * renamed back over the store its first writing open mints a new
+ * origin (`store-identity.ts`).
+ *
+ * Those steps, from the in-flight refusal to the swap and the removal of
+ * the parallel file on any failure, are `rebuild-aside.ts`'s, the same
+ * convention `fix-schema.ts` runs with its own file names.
+ *
+ * ## When the swap is refused
+ *
+ * Both refusals come before anything is built, and leave the directory
+ * as it was. A dry run is asked neither, since it only reads the store
+ * and deletes what it writes.
+ *
+ *   - From a development build, unless the store is one it owns: under
+ *     the temporary directory or `RAFA_EFFORT_DIR`, which is where a copy
+ *     `rafa effort copy` made sits. The question and its text are
+ *     `refuseUnownedDevelopmentWrite`'s, the one every open asks.
+ *   - While a loop record under the store's project root reads `running`
+ *     or `paused` with its pid alive (`readSessions`,
+ *     `packages/rafa/src/core/loop/sessions.ts`): renaming the store under a loop loses
+ *     what it writes. The spec's text names the first breaking migration:
+ *     `REFUSED — migration <id> breaks older runtimes, and loop <sessionId>
+ *     (pid <pid>, plan <stub>) is running on this store. Nothing was
+ *     migrated. Finish or stop that loop, then run it again.` With only
+ *     additive migrations pending it names the loop and the lost writes
+ *     instead. A store that is not a project's own `.rafa/effort/` file,
+ *     a copy, is named by no loop record, since `loop start` refuses to
+ *     run with `RAFA_EFFORT_DIR` set.
+ *
+ * It opens the store itself rather than through `withSqliteStore`, so it
+ * runs the test guard (`guardTestProcess`, `location.ts`) itself, before
+ * it reads or makes anything.
+ */
+import type { DevelopmentProbe } from './development-build.js';
+import type { SqliteMigration } from './migrations.js';
+import type { TableRows } from './rebuild-aside.js';
+import type { LoggedMigration } from './schema-plan.js';
+import type { SessionRecord } from '../../core/loop/index.js';
+/** What the run found, and what it did about it. */
+export type MigrateStatus = 
+/** No store file: nothing to migrate, and none is created. */
+'missing'
+/** Nothing to adopt or apply: nothing to migrate. */
+ | 'current'
+/** Under `dryRun`: the migrated store was built, checked and deleted. */
+ | 'would-migrate'
+/** The migrated store was swapped in and the original kept as a backup. */
+ | 'migrated';
+/** The outcome of one run. */
+export interface MigrateResult {
+    /** The live store's file. */
+    readonly path: string;
+    readonly status: MigrateStatus;
+    /** The live store's `user_version`, or null when there is no file. */
+    readonly storeVersion: number | null;
+    /** Whether the live store held a migration log. */
+    readonly logged: boolean;
+    /** What the run records: `schema_migrations` first when it adopts, then each pending id. */
+    readonly applying: readonly string[];
+    /** The pending ids that break older runtimes, in catalogue order. */
+    readonly breaking: readonly string[];
+    /** Logged migrations this rafa does not know; each is one this rafa uses the store through. */
+    readonly unknown: readonly LoggedMigration[];
+    /** Who the new log rows name as applying them. */
+    readonly appliedBy: string;
+    /** The `user_version` the migrated store holds, or null when nothing was built. */
+    readonly userVersion: number | null;
+    /** Every table both files hold, with the rows each holds; empty when nothing was built. */
+    readonly counted: readonly TableRows[];
+    /** Where the original went, for `migrated` only. */
+    readonly backupPath: string | null;
+}
+/** What one run is handed; the {@link DevelopmentProbe} fields say which build runs and which stores it owns. */
+export interface MigrateOptions extends DevelopmentProbe {
+    /** The live store's file. */
+    readonly path: string;
+    /** Build and check the migrated store, then delete it instead of swapping it in. */
+    readonly dryRun: boolean;
+    /** Names the parallel and backup files, so two runs never collide. */
+    readonly stamp: string;
+    /** The catalogue to migrate to: this build's unless a test passes a synthetic tail. */
+    readonly migrations?: readonly SqliteMigration[];
+    /** The clock the new log rows' `applied_at` is read from. */
+    readonly now?: () => Date;
+}
+/** A run refused before the live store was changed: the build-aside steps' refusal. */
+export { RebuildRefusal as MigrateRefusal } from './rebuild-aside.js';
+/**
+ * The first loop record under the store's project root that reads
+ * `running` or `paused`, if any, passing the record whose session id is
+ * `ownSessionId`: the run asking, which a pull at the end of its own task
+ * names (`merge-store.ts`). A record is passed by its session id alone,
+ * never by its pid, so another live record sharing the caller's pid is
+ * still answered. Records that cannot be read refuse, the text ending
+ * with `nothingDone`, the caller's sentence for what it left undone; the
+ * merge asks this too, and only the merge names a session id.
+ */
+export declare function liveLoop(path: string, options: DevelopmentProbe, nothingDone?: string, ownSessionId?: string | null): SessionRecord | undefined;
+/** Migrates the store at `options.path`. See the module note. */
+export declare function migrateStore(options: MigrateOptions): MigrateResult;

package/dist/effort/store/migrations.d.ts

@@ -0,0 +1,92 @@
+/** What an older runtime can no longer do once a migration has run. */
+export type MigrationBreak = 'readers' | 'writers';
+/** Why a breaking migration breaks, and what prepared the way for it. */
+export interface MigrationContract {
+    /**
+     * The id of the additive migration that shipped the new shape in an
+     * earlier release, or null when no expand step was needed.
+     */
+    readonly expand: string | null;
+    /** Why the change cannot be additive. */
+    readonly why: string;
+}
+/** A migration as rafa decides about it, whatever backend runs it. */
+export interface MigrationSpec {
+    /** Kebab-case and unique for all time: the key a store records it by. */
+    readonly id: string;
+    /** `[]` for an additive migration; otherwise what it breaks. */
+    readonly breaks: readonly MigrationBreak[];
+    /** Present exactly when `breaks` is not empty. */
+    readonly contract?: MigrationContract;
+}
+/** The one migration type that carries SQL. */
+export interface SqliteMigration extends MigrationSpec {
+    /** DDL only, frozen once shipped; `migrations.lock.json` holds its sha256. */
+    readonly sql: string;
+}
+/**
+ * The `user_version` a store holds while every migration it has applied
+ * is additive: the length of the history 0.23.0 to 0.24.1 hold, and so
+ * the last version those releases accept.
+ */
+export declare const LEGACY_GATE_OPEN = 13;
+/**
+ * The `user_version` a store holds once a breaking migration is applied:
+ * past any version a pre-log release counts to, so every such release
+ * refuses the store.
+ */
+export declare const LEGACY_GATE_CLOSED = 1000;
+/**
+ * The schema's history, by name. This module's note says why an entry
+ * is frozen, what its `breaks` declares, and who still reads the first
+ * thirteen by position.
+ */
+export declare const SQLITE_MIGRATIONS: readonly SqliteMigration[];
+/**
+ * The length of the history. `migrateSchema` in `sqlite.ts`, which
+ * tests plant pre-log stores with, brings a store to this
+ * `user_version` and refuses one past it, as the pre-log releases do.
+ */
+export declare const SQLITE_SCHEMA_VERSION: number;
+/**
+ * The `user_version` a store is given when it holds `applied`. The
+ * value is {@link LEGACY_GATE_OPEN} when every entry declares no
+ * `breaks`, and {@link LEGACY_GATE_CLOSED} otherwise. Any word counts
+ * as a break, including one this rafa does not know, because a pre-log
+ * release can use the store only when nothing in it breaks.
+ */
+export declare function legacyGate(applied: readonly {
+    readonly breaks: readonly string[];
+}[]): number;
+/** The sha256 of a migration's SQL, as lowercase hex over its UTF-8 bytes. */
+export declare function migrationChecksum(migration: Pick<SqliteMigration, 'sql'>): string;
+/** The lock file's shape: each migration's sha256, keyed by its id. */
+export type MigrationLock = Readonly<Record<string, string>>;
+/** One way the migrations and their lock disagree. */
+export type LockMismatch = 
+/** The entry's SQL hashes to something other than its lock line. */
+{
+    readonly kind: 'edited';
+    readonly id: string;
+    readonly locked: string;
+    readonly computed: string;
+}
+/** The entry has no lock line. */
+ | {
+    readonly kind: 'unlocked';
+    readonly id: string;
+    readonly computed: string;
+}
+/** The lock line has no entry, so a migration was removed or renamed. */
+ | {
+    readonly kind: 'missing';
+    readonly id: string;
+    readonly locked: string;
+};
+/**
+ * Every way `migrations` and `lock` disagree. Entries come first, in
+ * array order, followed by the lock lines that no entry matches, in
+ * lock order. An empty answer means the lock holds exactly these
+ * entries, each with the checksum of its SQL.
+ */
+export declare function lockMismatches(migrations: readonly SqliteMigration[], lock: MigrationLock): readonly LockMismatch[];