@open-tomato/rafa 0.45.0 → 0.46.0

package/dist/effort/store/ndjson-files.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The store directory, relative to the repo root.
+ *
+ * Spelled once on purpose — see the module note. `join` rather than a
+ * literal so the separator is the platform's, which keeps a path built
+ * here comparable to one a caller built with `join` of its own.
+ */
+export declare const EFFORT_STORE_DIR: string;
+/** The row kinds the collector writes, one store file each. */
+export type EffortRowKind = 'sessions' | 'commits';
+/** What one read of a store file found. */
+export interface StoreReadResult<T> {
+    /** Every plain-object line, in the order it was appended. */
+    rows: T[];
+    /** Lines the file held, excluding the trailing newline's empty tail. */
+    lineCount: number;
+    /** Lines that produced no row: blank, malformed, or not an object. */
+    unparsedLineCount: number;
+}
+/** What one append did. */
+export interface AppendResult {
+    /** The file written, whether or not anything was written to it. */
+    path: string;
+    /** Rows appended. Zero writes nothing and creates no file. */
+    appended: number;
+    /** Rows whose key was already held, on disk or earlier in the batch. */
+    skipped: number;
+    /**
+     * True when the file did not end in a newline and this append wrote
+     * one before its first row. The partial line is left in place and
+     * reads as unparsed forever, which is what makes the row it half
+     * held get collected again.
+     */
+    separatedPartialLine: boolean;
+}
+/** A store bound to one file and one key projection. */
+export interface EffortStore<T> {
+    /** The file this store reads and appends to. */
+    readonly path: string;
+    /** Every row currently on disk, with the line arithmetic. */
+    readRows: () => StoreReadResult<T>;
+    /** The keys already held — what a collector skips. */
+    collectedKeys: () => Set<string>;
+    /** Appends the rows this store does not already hold. */
+    append: (rows: readonly T[]) => AppendResult;
+}
+/** The name of one row kind's store file, without its directory. */
+export declare function effortStoreFileName(kind: EffortRowKind): string;
+/**
+ * Resolves one store file under a repo root, always under
+ * {@link EFFORT_STORE_DIR}. The NDJSON backend resolves its files
+ * through `store/location.ts` instead, which `RAFA_EFFORT_DIR` can move.
+ */
+export declare function effortStorePath(repoRoot: string, kind: EffortRowKind): string;
+/**
+ * Parses store text into rows.
+ *
+ * The trailing empty element a final newline produces is dropped —
+ * exactly one, so a genuinely blank last line is still counted.
+ * Everything else that yields no row is counted as unparsed, which is
+ * what keeps `rows + unparsed === lineCount` exact and makes a
+ * truncated final line visible instead of silent.
+ *
+ * Splitting on `/\r?\n/` rather than the bare newline is currently
+ * UNOBSERVABLE and kept anyway. Measured: the bare split leaves a
+ * carriage return on the end of every line and every case still
+ * passes, because `JSON.parse` tolerates trailing whitespace and a
+ * lone `\r` trims to empty. That equivalence is two downstream
+ * tolerances rather than a property of this function, and the next
+ * check added here — a length test, a prefix test — would silently
+ * depend on neither having changed. Taking the carriage return off at
+ * the split is what keeps that from mattering.
+ *
+ * The `T` is the caller's assertion. The only structural check made
+ * here is that the line parsed to a plain object.
+ */
+export declare function parseStoreText<T>(text: string | null): StoreReadResult<T>;
+/** Reads every row a store file holds, with its line arithmetic. */
+export declare function readStoreRows<T>(path: string): StoreReadResult<T>;
+/**
+ * Projects rows onto their keys.
+ *
+ * A row whose key is absent or empty contributes nothing rather than
+ * seeding the set with a placeholder every other keyless row would
+ * then collide with. {@link appendRows} refuses to write one in the
+ * first place; this tolerates the ones a hand-edited store might hold.
+ */
+export declare function keysOfRows<T>(rows: readonly T[], keyOf: (row: T) => string | null | undefined): Set<string>;
+/** The keys a store file already holds — what a collector skips. */
+export declare function collectedKeys<T>(path: string, keyOf: (row: T) => string | null | undefined): Set<string>;
+/**
+ * Appends the rows a store file does not already hold.
+ *
+ * The batch is key-validated before anything is opened, so a keyless
+ * row leaves the file untouched rather than half-appended. Rows are
+ * serialised one per line: `JSON.stringify` escapes a newline inside
+ * a string value, so no row content can ever split a line in two.
+ *
+ * Writing nothing writes NOTHING — no file, no directory, no trailing
+ * newline. An empty first collect leaves no trace, which is the only
+ * answer consistent with a store whose absence means "empty".
+ */
+export declare function appendRows<T>(path: string, rows: readonly T[], keyOf: (row: T) => string | null | undefined): AppendResult;
+/**
+ * Binds a store file to the key projection it is deduplicated by.
+ *
+ * The binding is the point rather than the ergonomics. Incrementality
+ * fails silently when the set a collector SKIPS by and the set an
+ * append DEDUPES by are built from two different projections of a
+ * row — the collector re-reads work it already holds, or the store
+ * grows a duplicate per run, and both look like a store that is
+ * simply working. One `keyOf` per store makes that unrepresentable.
+ */
+export declare function openEffortStore<T>(path: string, keyOf: (row: T) => string | null | undefined): EffortStore<T>;

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

@@ -0,0 +1,116 @@
+/**
+ * The origin pair a production insert stamps on a new row it writes:
+ * `origin_store`, the store id `store_meta` records, and `origin_seq`,
+ * the row's own `seq`. An insert that carries a row over from another
+ * store or file keeps the pair that row holds; {@link ORIGIN_TABLES}
+ * names the three.
+ *
+ * ## One counter, not two
+ *
+ * `origin_seq` is the row's local `seq` at insert, never a second
+ * counter. So a store that mints a new origin, being a copy, keeps
+ * counting `seq` from the rows it holds, and its first row under the
+ * new origin carries the next `seq` rather than 1. Two stores that
+ * share rows then disagree on `origin_store` for everything written
+ * after the copy, which is what keeps their pairs apart.
+ *
+ * Every stamped insert names `seq` itself, as `COALESCE(MAX(seq), 0) + 1`
+ * over its own table, and writes that same value into `origin_seq`, so
+ * the two cannot differ. SQLite would pick the same rowid for an
+ * `INTEGER PRIMARY KEY` left out, but only while the largest rowid is
+ * below 2^63 - 1: measured with Bun 1.4.2, a row inserted after one
+ * at `9223372036854775807` got `4005337119280845049`, a random pick
+ * no `MAX(seq)` read beforehand predicts. Both subqueries sit in the one
+ * `INSERT` statement, which SQLite runs atomically under the write lock
+ * it takes, so a row inserted by another process cannot land between
+ * the reading of `MAX(seq)` and the insert. Nothing here reads a row
+ * back or updates one after the insert.
+ *
+ * ## Where the origin comes from
+ *
+ * The insert reads `store_id` from `store_meta` (`id = 1`) in the same
+ * statement. `withSqliteStore` settles the store's identity before any
+ * writer runs (`store-meta.ts`), so on a `write` open the row holds the
+ * origin this very file was minted for: the one recorded, kept, or the
+ * one just minted for a copy. A store with no `store_meta` row, as one
+ * under `tmpdir()` outside any repository with commits is left, stamps
+ * NULL in both columns, as a runtime before `row-origins` does. It
+ * never stamps a `seq` without a store: a pair is both or neither.
+ *
+ * ## No trigger, and no `UPDATE`
+ *
+ * A trigger filling the columns would break `writers` as
+ * `classifyMigration` reads it, since an older runtime's insert would
+ * fire it. A second statement updating the pair after the insert would
+ * be a production `UPDATE … SET origin_store` that the merge's registry
+ * would have to give a rule. The pair is therefore written by the
+ * insert's own column list, which {@link STAMPED_COLUMNS} and
+ * {@link stampedValues} spell for every writer alike.
+ *
+ * ## Readers
+ *
+ * No reader filters on either column, so a row an older runtime
+ * inserts, NULL in both, is read as every stamped row is. The partial
+ * unique index `<table>_by_origin` covers only rows whose
+ * `origin_store` is not NULL, so any number of such rows coexist.
+ *
+ * A reader that answers rows in order and may run over a merged store
+ * sorts by {@link ACROSS_STORES_ORDER}, which names both columns. `seq`
+ * alone cannot be that order: a merge inserts the other store's rows
+ * under new local `seq` values after its own, so the two sides of one
+ * merge would read the same rows in two orders.
+ */
+/**
+ * The tables a merge unions, each carrying `origin_store` and
+ * `origin_seq`: since migration `row-origins` for the twelve tables
+ * older than it, and from the migration that creates it for
+ * `stale_docs` and `bug_routes`. A production insert that writes a new
+ * row into one of them is stamped. Three inserts carry rows that exist
+ * already and leave the pair as the row holds it:
+ * the copy in `fix-schema.ts`, column for column from the live store;
+ * the union in `merge-union.ts`, which gives another store's row a new
+ * local `seq` and keeps its origin; and the restore in
+ * `fixture-extract.ts`, which builds a store from an extract's rows.
+ * `origins.test.ts` reads every insert from source and spells both
+ * lists. `schema_migrations`, `store_meta`, `store_replaced`, `merges`
+ * and `merge_conflicts` are the store's own bookkeeping and carry no
+ * origin.
+ */
+export declare const ORIGIN_TABLES: readonly ["sessions", "commits", "findings", "blockers", "out_of_scope_bugs", "report_absences", "task_reports", "preflight", "dispatches", "changes", "skill_invocations", "plan_ci", "stale_docs", "bug_routes"];
+/** One of the {@link ORIGIN_TABLES}. */
+export type OriginTable = typeof ORIGIN_TABLES[number];
+/**
+ * The `ORDER BY` terms of a reader that answers the rows of a table
+ * with `collected_at` in the same order on every store holding them:
+ * the write's time first, then the origin pair, then the local `seq`.
+ *
+ *   - `collected_at` orders rows written at different times, whichever
+ *     store wrote them and whichever side ran a merge.
+ *   - The origin pair breaks a tie. One write stamps every row it
+ *     inserts with one time, and `origin_seq` is the `seq` each row got
+ *     in the store that wrote it, so one device's rows of one write keep
+ *     the order that device appended them in, on any store, and two
+ *     devices' rows at one time are ordered by their `origin_store`.
+ *   - `seq` breaks what remains: rows with a NULL origin, which SQLite
+ *     sorts before every origin. Among those at one time the order is
+ *     the store's own append order, which is not the same on both sides
+ *     of a merge.
+ *
+ * A clock that goes backwards reorders rows here; the append order no
+ * longer wins over the stamp.
+ */
+export declare const ACROSS_STORES_ORDER = "collected_at, origin_store, origin_seq, seq";
+/**
+ * The columns a stamped insert names after its own, in the order
+ * {@link stampedValues} answers their values.
+ */
+export declare const STAMPED_COLUMNS = "seq, origin_store, origin_seq";
+/**
+ * The SQL values of {@link STAMPED_COLUMNS} for an insert into `table`:
+ * the next `seq`, the store's origin, and that `seq` again as
+ * `origin_seq` when the store has an origin, NULL beside a NULL origin.
+ *
+ * `table` is interpolated into the SQL, which is safe because the type
+ * admits only the names in {@link ORIGIN_TABLES}.
+ */
+export declare function stampedValues(table: OriginTable): string;

package/dist/effort/store/plan-stubs.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Branch and plan-stub resolution: how a branch name splits into a type
+ * and a stub, how plan stubs are read out of a directory listing, and
+ * how a branch stub resolves against them.
+ *
+ * Moved down from `src/effort/attribution.ts`, which attributes a
+ * session to its plan, issue and task text and re-exports these names
+ * under the same names: the store's row types (`types.ts`) and its plan
+ * CI reader (`plan-ci.ts`) need the resolution but not the session
+ * attribution, so they import it here and the store imports nothing
+ * above core for it. The module note of `attribution.ts` still explains
+ * why a branch stub is not a plan stub and why the queue id is matched
+ * whole.
+ */
+/** One branch name split into the two parts attribution reads. */
+export interface BranchAttribution {
+    /** The branch as recorded, trimmed, or null when there was none. */
+    branch: string | null;
+    /** The segment before the first slash, or null when there is none. */
+    type: string | null;
+    /** The segment after it, or null when the branch carries no stub. */
+    stub: string | null;
+}
+/**
+ * How a session was matched to a plan.
+ *
+ * `stamped` is the only member that does not come from a branch name:
+ * the loop writes the stub into every prompt it dispatches, so it is
+ * read back directly and outranks the branch. The rest describe the
+ * branch-stub path, which is the fallback for a session recorded
+ * before stamping existed, or one the loop did not dispatch.
+ */
+export type PlanStubMatch = 'stamped' | 'exact' | 'queue-id' | 'none' | 'ambiguous';
+/** The plan a branch stub resolved to, and how it got there. */
+export interface PlanStubResolution {
+    /** The resolved plan stub, or null unless the match is decisive. */
+    stub: string | null;
+    match: PlanStubMatch;
+    /**
+     * Every plan stub the queue id reached. One member on a `queue-id`
+     * match, the branch stub itself on an `exact` one, and the whole
+     * contested set on an `ambiguous` one — which is what makes an
+     * ambiguity reportable rather than merely refused.
+     */
+    candidates: readonly string[];
+}
+/**
+ * Splits a branch name into its type prefix and its plan stub.
+ *
+ * A name with no slash has no stub — that is the `main` and `pw-align`
+ * case and it is the expected answer, not a degraded one. A stub that
+ * would itself contain a slash is refused for a narrower reason: no
+ * plan file can be named after it, `plan.ts` writing
+ * `PLAN-<stub>.md` into one flat directory.
+ */
+export declare function attributeBranch(branch: string | null | undefined): BranchAttribution;
+/**
+ * Reads plan stubs out of a directory listing.
+ *
+ * Takes names rather than a directory so the naming convention lives in
+ * one place while the read stays with the caller — the plans directory,
+ * `plan.dir`, is untracked by default and can be absent entirely, which
+ * is the caller's problem to report and not this module's to guess at.
+ *
+ * Duplicates are collapsed: two listings concatenated would otherwise
+ * make every queue-id match ambiguous against a stub and itself.
+ */
+export declare function planStubsFromFileNames(fileNames: readonly string[]): string[];
+/** The leading queue id of a stub, or null when it carries none. */
+export declare function queueIdOf(stub: string | null | undefined): string | null;
+/**
+ * Resolves a branch stub against the known plan stubs.
+ *
+ * Exact first, then a queue id that reaches exactly one plan. Anything
+ * else answers `none` or `ambiguous` with its candidates — a report
+ * would rather show an unattributed bucket than attribute a plan's
+ * spend to the wrong plan.
+ */
+export declare function resolvePlanStub(branchStub: string | null | undefined, planStubs: readonly string[]): PlanStubResolution;

package/dist/effort/store/rebuild-aside.d.ts

@@ -0,0 +1,172 @@
+/**
+ * The build-aside convention: a SQLite store is never changed in place.
+ * A new file is built beside it, checked, and swapped in behind a
+ * backup of the whole store, or deleted under a dry run.
+ *
+ * ## The steps
+ *
+ * 1. Refuse while a rollback journal or write-ahead log sits beside the
+ *    store ({@link refuseInFlight}): either means a write in flight or
+ *    interrupted, and a file built from the store then would miss it.
+ * 2. Refuse when the parallel file or the backup is already there
+ *    ({@link rebuildAside}), so two runs never overwrite each other.
+ * 3. Build the parallel file. What goes into it is the caller's: the
+ *    repair (`fix-schema.ts`) brings a fresh file to this rafa's
+ *    migrations through the log-aware apply and copies the known tables
+ *    into it, and the forward move (`migrate.ts`) writes the store out
+ *    with `VACUUM INTO` and applies its pending migrations there, and
+ *    the merge (`merge-store.ts`) writes the store out the same way and
+ *    unions another store's rows into it. The caller checks it with
+ *    {@link checkedCounts}, every table's row count against the
+ *    store's plus the rows the caller says it added, and
+ *    {@link refuseCorrupt}, SQLite's `integrity_check`.
+ * 4. Any failure while building removes the parallel file and its
+ *    journal, and leaves the store untouched.
+ * 5. Under a dry run the parallel file is then deleted, so the run can
+ *    be repeated and leaves the directory as it found it. Otherwise the
+ *    parallel file is swapped in ({@link swapIn}) in four steps:
+ *    a. The store is written out to the backup with `VACUUM INTO` on a
+ *       read-only connection (`vacuumInto`, `copy.ts`), and the backup
+ *       is flushed with `fsync`, since SQLite's documentation says
+ *       `VACUUM INTO` does not sync the file it writes.
+ *    b. The store's identity is carried onto the parallel file
+ *       (`carryStoreIdentity`, `store-meta.ts`): when a write to the
+ *       live store would keep its origin, the parallel file's row is
+ *       given the parallel file's own device and inode and a new
+ *       generation. Otherwise nothing is carried: the parallel file's
+ *       row is given only a fresh generation the side record does not
+ *       hold, and the swapped-in store mints on its next write.
+ *    c. When the carry answered `carried` with a generation, that
+ *       generation is written to the store's side record
+ *       (`writeStoreGeneration`, `store-generation.ts`), immediately
+ *       before the rename. A carry onto a file with no `generation`
+ *       column answers none, and this step is skipped.
+ *    d. The parallel file is renamed over the store, which replaces it
+ *       in one step.
+ *
+ * ## A failed swap
+ *
+ * The store's file is only read until the rename, and a rename that
+ * fails replaces nothing, so a failure at any of the four steps leaves
+ * the store's file as it was. The swap then deletes nothing: it throws a
+ * {@link SwapFailure} naming the step, the rebuilt file and the backup,
+ * and leaves both beside the store. After a failed backup the backup
+ * may be partial or absent; after a failed carry, side record write or
+ * rename it holds the whole store. A run with another stamp names other
+ * files, so it never overwrites either.
+ *
+ * The side record is the one thing beside the store a swap writes
+ * before the rename. A side record write that fails leaves the record
+ * as it was (`writeStoreGeneration` replaces it whole or not at all), so
+ * the store keeps its origin on its next write. A rename that fails
+ * after it leaves the store's file holding the old generation beside a
+ * side record holding the new one, so the store mints once on its next
+ * write, which is the safe side, and keeps that id on the write after.
+ *
+ * ## The backup is a copy, and takes a new origin
+ *
+ * The backup holds every row the store held, with its schema and
+ * `user_version`, but it is a new file: its bytes need not equal the
+ * original's, and it has an inode of its own, since it was written while
+ * the original still existed. Its `store_meta` row still names the
+ * original's inode, so a backup renamed back over the store mints a new
+ * origin on its next writing open, as any restored copy must
+ * (`store-identity.ts`). It holds the generation the side record held
+ * before the swap, which the swap rotated past, so it mints even when
+ * the host gives it back the original's inode number. The swapped-in
+ * file keeps the store's origin, since the carry recorded the inode the
+ * rename brings to the store's path and the generation the swap wrote to
+ * its side record.
+ *
+ * The caller names both files, so each command keeps its own spelling
+ * of them beside the store. The checks work over a handle the caller
+ * opened; the swap opens the store read-only for the backup and the
+ * parallel file for the carry.
+ */
+import type { CarryOutcome } from './store-meta.js';
+import type { Database } from 'bun:sqlite';
+/** A build-aside step refused before the live store was changed. */
+export declare class RebuildRefusal extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** A table with the rows it holds. */
+export interface TableRows {
+    readonly table: string;
+    readonly rows: number;
+}
+/** A name quoted as an SQL identifier. */
+export declare function quoted(name: string): string;
+/** One count query's answer. */
+export declare function count(db: Database, sql: string): number;
+/** Refuses while a journal or log beside `path` says a write is in flight or was interrupted. */
+export declare function refuseInFlight(path: string): void;
+/**
+ * Every table in `tables` with its rows in `main`, refusing one whose
+ * count differs from the same table in the attached `original` schema
+ * plus the rows `added` names for it, none for a table it does not name.
+ * A repair or a migration adds none; a merge names what it inserted.
+ */
+export declare function checkedCounts(db: Database, tables: readonly string[], original: string, added?: Readonly<Record<string, number>>): TableRows[];
+/** Refuses a rebuilt file SQLite does not vouch for. */
+export declare function refuseCorrupt(db: Database): void;
+/** A step of {@link swapIn}, in the order it runs them. */
+export type SwapStep = 'backup' | 'carry' | 'record' | 'rename';
+/** The files one swap works with. */
+interface SwapFiles {
+    readonly path: string;
+    readonly parallelPath: string;
+    readonly backupPath: string;
+}
+/**
+ * A swap that failed before the rename replaced the store: the store is
+ * unchanged, and the rebuilt file and whatever the backup step wrote
+ * are left beside it. The failure the step threw is the `cause`.
+ */
+export declare class SwapFailure extends RebuildRefusal {
+    readonly step: SwapStep;
+    readonly parallelPath: string;
+    readonly backupPath: string;
+    constructor(step: SwapStep, files: SwapFiles, cause: unknown);
+}
+/** The four steps of a swap, which {@link swapIn} runs in this order. */
+export interface SwapSteps {
+    /** Writes the store at `path` out to `backupPath`. */
+    readonly backup: (path: string, backupPath: string) => void;
+    /** Carries the identity of the store at `path` onto the file at `parallelPath`, answering what it wrote. */
+    readonly carry: (path: string, parallelPath: string) => CarryOutcome;
+    /** Writes `generation` to the side record of the store at `path`. */
+    readonly record: (path: string, generation: string) => void;
+    /** Renames `parallelPath` over `path`. */
+    readonly rename: (parallelPath: string, path: string) => void;
+}
+/**
+ * Swaps the parallel file in over the store at `path`: writes the
+ * backup, carries the store's identity, writes the generation the carry
+ * answered to the store's side record when it answered `carried` with
+ * one, and renames the parallel file over the store. A failed step
+ * throws a {@link SwapFailure} and leaves the store's file unchanged, and
+ * the backup and the parallel file where they are. `steps` replaces any
+ * of the four, so a test can fail one. See the module note.
+ */
+export declare function swapIn(path: string, parallelPath: string, backupPath: string, steps?: Partial<SwapSteps>): void;
+/** What one build-aside run is handed. */
+export interface RebuildAsideOptions<Built> {
+    /** The live store's file. */
+    readonly path: string;
+    /** The file built beside it. */
+    readonly parallelPath: string;
+    /** Where the backup of the store is written when the rebuild is swapped in. */
+    readonly backupPath: string;
+    /** Build and check, then delete the parallel file instead of swapping it in. */
+    readonly dryRun: boolean;
+    /** Builds and checks the parallel file, throwing to refuse it. */
+    readonly build: (parallelPath: string) => Built;
+}
+/** What the build answered, and where the backup was written: null under a dry run. */
+export interface RebuildAsideResult<Built> {
+    readonly built: Built;
+    readonly backupPath: string | null;
+}
+/** Runs the build-aside steps around `options.build`. See the module note. */
+export declare function rebuildAside<Built>(options: RebuildAsideOptions<Built>): RebuildAsideResult<Built>;
+export {};

package/dist/effort/store/schema-plan.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The compatibility decision: whether this rafa may use a store, given
+ * the named migrations the store holds and the ones this build knows.
+ *
+ * {@link planSchema} is a pure function over plain values. It imports
+ * nothing from `bun:sqlite` or `sqlite.ts`, so the decision never
+ * depends on the backend that holds the store. The caller reads the
+ * store's migration log and `user_version` and passes them in. It
+ * answers either "use", with what an open has to adopt and apply and
+ * the `user_version` the store ends at, or "refuse", with one of the
+ * seven {@link RefusalReason}s.
+ *
+ * ## How it decides
+ *
+ * A store with no log is a store a release before the log wrote, and
+ * its `user_version` counts the legacy entries it holds. From 1 to
+ * {@link LEGACY_GATE_OPEN} it is adopted: those entries are recorded
+ * with this build's checksums, which match what ran because a shipped
+ * entry is frozen. A version of 0 is a fresh store. Anything else was
+ * written by no released rafa.
+ *
+ * A store with a log is judged from the log, never from a number. A
+ * logged id this build knows must carry the checksum this build holds.
+ * A logged id this build does not know is read by its `breaks`:
+ * nothing lets this rafa use the store as it is; `writers` lets it
+ * read and refuses a write; `readers`, or a word this rafa does not
+ * know, refuses the store. An open that has migrations to apply writes
+ * the store, whatever its caller asked for, so it counts as a write
+ * here too.
+ *
+ * A pending migration this build knows is applied late when it is
+ * additive, which is how two branches that each append one merge in
+ * either order. A pending breaking migration applies only in order,
+ * and only through `rafa effort migrate`.
+ *
+ * The seven rows are tried in {@link REFUSAL_REASONS} order and the
+ * first that matches decides. Every refusal's message ends with its
+ * {@link SchemaRefusal.nextStep}, the one command to run next.
+ */
+import type { MigrationSpec, SqliteMigration } from './migrations.js';
+/** Whether an open reads the store only, or also writes it. */
+export type StoreAccess = 'read' | 'write';
+/** Who asks: an ordinary open, or `rafa effort migrate`. */
+export type SchemaCaller = 'open' | 'migrate';
+/** A migration this build knows, with the checksum of its body. */
+export interface CatalogueEntry extends MigrationSpec {
+    /** Lowercase sha256 hex of the body the backend runs. */
+    readonly sha256: string;
+}
+/** One row of a store's migration log, as the caller read it. */
+export interface LoggedMigration {
+    readonly id: string;
+    readonly sha256: string;
+    /** The words recorded, which may include one this rafa does not know. */
+    readonly breaks: readonly string[];
+    readonly appliedAt: string;
+    readonly appliedBy: string;
+}
+/** What the caller read from the store before any write. */
+export interface StoreSchema {
+    /** The store's path, as every refusal names it. */
+    readonly path: string;
+    /** `PRAGMA user_version`: the legacy gate, or a pre-log store's count. */
+    readonly userVersion: number;
+    /** The migration log in apply order, or null when the store has none. */
+    readonly log: readonly LoggedMigration[] | null;
+}
+/** The seven reasons a store is refused, in the order they are tried. */
+export declare const REFUSAL_REASONS: readonly ["pre-log-unreleased", "gate-mismatch", "edited", "unknown-breaks-readers", "unknown-breaks-writers", "breaking-out-of-order", "breaking-pending"];
+/** Why this rafa refuses a store. */
+export type RefusalReason = typeof REFUSAL_REASONS[number];
+/** This rafa may use the store once it has adopted and applied what is listed. */
+export interface SchemaUse {
+    readonly verdict: 'use';
+    /** Legacy entries a log-less store holds, to be logged without running. */
+    readonly adopted: readonly CatalogueEntry[];
+    /** Entries to apply, in catalogue order. */
+    readonly pending: readonly CatalogueEntry[];
+    /** Logged migrations this build does not know; each is additive, or breaks writers only on a read. */
+    readonly unknown: readonly LoggedMigration[];
+    /** The `user_version` the store holds once everything listed is applied. */
+    readonly gate: number;
+}
+/** This rafa refuses the store, and says why and what to run next. */
+export interface SchemaRefusal {
+    readonly verdict: 'refuse';
+    readonly reason: RefusalReason;
+    /** The refusal text, ending with `Next safe step: <nextStep>`. */
+    readonly message: string;
+    /** The one command to run next. */
+    readonly nextStep: string;
+}
+/** What {@link planSchema} answers. */
+export type SchemaPlan = SchemaUse | SchemaRefusal;
+/** A migration's SQL entries with the checksums {@link planSchema} compares. */
+export declare function sqliteCatalogue(migrations: readonly SqliteMigration[]): readonly CatalogueEntry[];
+/**
+ * Decide whether this rafa may use `store` with this build's
+ * `catalogue`, for an open with `access` from `caller`. The module note
+ * says how.
+ */
+export declare function planSchema(store: StoreSchema, catalogue: readonly CatalogueEntry[], access: StoreAccess, caller: SchemaCaller): SchemaPlan;

package/dist/effort/store/session-row-types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The session row's own types: what a session was dispatched to do and
+ * the stats accumulated over its log.
+ *
+ * Moved down from `src/effort/classify.ts` (`SessionKind`) and
+ * `src/effort/session-log.ts` (`SessionStats` and the
+ * `SessionUsageTotals` it names), which classify and read session logs
+ * and re-export these names under the same names: the store's row types
+ * (`types.ts`) need the shapes but not the classifier or the reader, so
+ * they import them here and the store imports nothing above core for
+ * them. The module notes of `classify.ts` and `session-log.ts` still
+ * describe how each value is derived from a log.
+ */
+/** What a session was dispatched to do. */
+export type SessionKind = 'task' | 'plan-generation' | 'wrap-up' | 'ci-repair' | 'search' | 'other';
+/**
+ * Every numeric counter under a record's `message.usage`, summed over
+ * the whole session. Names are the camelCase of the wire spelling;
+ * the two `ephemeral*` members are the `cache_creation` split and the
+ * two `*Requests` members the `server_tool_use` one.
+ */
+export interface SessionUsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+    ephemeral1hInputTokens: number;
+    ephemeral5mInputTokens: number;
+    webSearchRequests: number;
+    webFetchRequests: number;
+    thinkingTokens: number;
+}
+/** One accumulated stats row per session log. */
+export interface SessionStats {
+    /** Log basename without its extension, which is the session uuid. */
+    sessionId: string;
+    /** The path the row was accumulated from. */
+    filePath: string;
+    /** Non-empty lines read. */
+    lineCount: number;
+    /** Lines that parsed to a JSON object. */
+    recordCount: number;
+    /** Lines that did not — malformed JSON, or JSON that is not an object. */
+    unparsedLineCount: number;
+    /** Records by top-level `type`; an absent type is keyed as `unknown`. */
+    recordTypeCounts: Record<string, number>;
+    /** Records with `type: assistant`, which are the billable turns. */
+    assistantRecordCount: number;
+    /** Earliest and latest `timestamp` by instant, not by file order. */
+    firstTimestamp: string | null;
+    lastTimestamp: string | null;
+    /** Records per top-level `gitBranch`, the plan-attribution field. */
+    gitBranchCounts: Record<string, number>;
+    /** Records per `entrypoint`; separates loop from hand-driven traffic. */
+    entrypointCounts: Record<string, number>;
+    /** Records per top-level `effort`; what a session actually ran at. */
+    effortCounts: Record<string, number>;
+    /** Records carrying `isSidechain: true`, which are subagent turns. */
+    sidechainRecordCount: number;
+    /** Records per `message.model`. */
+    modelCounts: Record<string, number>;
+    /** Summed `message.usage` counters. */
+    usage: SessionUsageTotals;
+}

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

@@ -0,0 +1,13 @@
+/** What every effort store open reads. */
+export interface StoreSettings {
+    /** How long an open waits for another process's write lock, in ms. */
+    readonly busyTimeoutMs: number;
+}
+/**
+ * Sets the settings every later open reads; `null` puts the default
+ * back. Throws a `RangeError`, setting nothing, for a busy timeout
+ * outside the whole numbers the config accepts.
+ */
+export declare function setActiveStoreSettings(settings: StoreSettings | null): void;
+/** The settings every open reads now; see the module note. */
+export declare function activeStoreSettings(): StoreSettings;