@open-tomato/rafa 0.45.0 → 0.46.0

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

@@ -0,0 +1,305 @@
+/**
+ * The store's own identity row: reading what `store_meta` records,
+ * minting a new origin into it on a writing open that needs one,
+ * settling on that mint which ids `store_replaced` holds, and rotating
+ * the store's generation on every writing open and on every rebuild
+ * that keeps the store's origin.
+ *
+ * ## What a writing open writes
+ *
+ * `withSqliteStore` (`sqlite.ts`) calls {@link settleStoreIdentity}
+ * after `bringForward`, so the table and its `generation` column exist,
+ * and before any caller reads or writes. `decideStoreIdentity`
+ * (`store-identity.ts`) makes the decision: a `read` open answers
+ * `none` and this module neither reads the row, observes the file nor
+ * touches the side record, so a read writes nothing. A `write` open
+ * reads the row, observes the host, the real path, the file's device
+ * and inode and the side record's generation, and mints when the row is
+ * absent, any of the three facts moved, or the row holds a generation
+ * the side record does not. A row's generation is read as NULL when its
+ * store has no `generation` column yet, and a NULL one is judged by the
+ * three facts alone.
+ *
+ * Every writing open then takes the write lock with `BEGIN IMMEDIATE`,
+ * reads the row and decides again under it, since another process may
+ * have minted or rotated the same file while this one waited, and
+ * writes a new random generation (`newGeneration`, a UUID) in that
+ * transaction: on a keep, into `store_meta.generation`; on a mint, into
+ * the new row (`id = 1`) with the new origin. Either way it then writes
+ * the same generation to the side record (`store-generation.ts`),
+ * `<real path of the store file>.generation` beside it, and commits. So
+ * a store written without a generation keeps its origin on its first
+ * write and holds one after it, two processes that open one unminted
+ * store at once record one origin, and a copy of the file, which
+ * carries the row and leaves the side record behind, mints on its first
+ * write once the original has been written since the copy was taken.
+ *
+ * The row is written first and the side record second, both before the
+ * commit, because a writer that waits for the lock decides only once it
+ * holds it and so always sees the two agree. A side record that fails
+ * to write throws and rolls the row back. A crash after the side
+ * record's rename and before the commit leaves the side record one
+ * rotation ahead of the row; the next writing open mints once, which is
+ * safe, and keeps on the write after. A side record restored from
+ * before the last write is one rotation behind and mints the same way.
+ *
+ * What the generation does not catch: a restore of the store's whole
+ * directory, the store file and its side record together, brings back a
+ * row and a side record that agree. When the file comes back at its old
+ * inode, as a `cp` over the existing file writes it, all three facts
+ * match as well and nothing mints; the merge's collision check is what
+ * catches that copy afterwards.
+ *
+ * ## The project a mint records
+ *
+ * `store_meta.project_root_commit` is `NOT NULL`. The project is read
+ * through git in the store file's directory (`readProjectIdentity`), so
+ * `<root>/.rafa/effort/` and a copy under `<root>/.rafa/scratch/` both
+ * name the project they sit in. When git finds no root commit there, a
+ * mint takes the project the row already records, since a copy moved
+ * outside its checkout is still that project's store. When neither
+ * names one, as for a store under `tmpdir()` outside any repository
+ * with commits, nothing is written and the outcome is `no-project`: the
+ * store stays unminted, no generation is written to the row or the side
+ * record, and the next writing open asks again. That costs the git
+ * reads on each such open and loses no origin, since an unminted store
+ * stamps none. Git is only asked on a mint, never on a write that keeps
+ * the origin, and before the lock is taken: under it, git is asked only
+ * for a store that came due a mint while this open waited.
+ *
+ * ## The ids a mint replaces
+ *
+ * `store_meta` holds one row, so a mint writes the new origin over the
+ * old one. A claim names the id of the store that made it, and a store
+ * file given a new device or inode under its own host and path is still
+ * this device's store. So a mint settles `store_replaced`
+ * (`store-replaced.ts`) by its reasons, in the transaction that writes
+ * the new row:
+ *
+ *   - `file`, `generation`, or both: the host and the path were kept.
+ *     One host and one path hold one store file at a time, so this is
+ *     the device's own store, moved or rolled back. The outgoing id is
+ *     recorded with the time the new row takes as `minted_at`, read from
+ *     the clock once, and every id recorded before it stays. `generation`
+ *     alone is what a crash between the side record's rename and the
+ *     commit leaves, and both together what a backup renamed back over
+ *     the store after a write leaves.
+ *   - `host` or `path` among them, whatever else moved: the file is a
+ *     copy, and a copy carries the original's table inside it. The table
+ *     is emptied and the outgoing id is not recorded, so a copy inherits
+ *     no claim.
+ *   - `unminted`: no id is outgoing, and nothing is written.
+ *
+ * A write that keeps the origin, and a mint that knows no project and
+ * writes nothing, leave the table as it was. The record and the row
+ * commit together: a side record that fails to write rolls both back.
+ *
+ * `withSqliteStore` settles after `bringForward`, which has applied
+ * `store-replaced` by then, so the table is there on every writing open.
+ * A mint that keeps the host and the path over a store without it
+ * throws SQLite's `no such table: store_replaced` and writes nothing,
+ * since an id that cannot be kept is not reported as kept. A mint an
+ * older runtime made recorded nothing, and neither did any mint from
+ * before the table: those ids are in no store.
+ *
+ * ## Device and inode as SQLite integers
+ *
+ * Both are unsigned 64-bit values, and SQLite's INTEGER is signed.
+ * Measured with Bun 1.4.2: binding `2n ** 63n` raises nothing and
+ * stores `-9223372036854775808`, and a plain read would answer a
+ * rounded number. So {@link toStoredInteger} writes the two's
+ * complement explicitly, the row is read through `CAST(… AS TEXT)`,
+ * and {@link fromStoredInteger} turns it back unsigned. Every value
+ * below 2^63 is written and read as itself.
+ *
+ * ## Carrying the identity onto a file that replaces the store
+ *
+ * A rebuild beside the store (`rebuild-aside.ts`) builds a parallel file
+ * that holds the store's own `store_meta` row, since `store_meta` is
+ * `local` in `MERGE_RULES`, and then renames it over the store. The
+ * renamed file has the store's path and host and the parallel file's
+ * inode, so its next writing open would mint although it is the same
+ * store. {@link carryStoreIdentity} runs before that rename. It reads
+ * the live file's row and asks `decideStoreIdentity` what a write to the
+ * live file would do. Only on a keep does it write the parallel file's
+ * own device and inode, and a new generation (`newGeneration`), into the
+ * parallel file's row, and it answers that generation in `carried`.
+ * `swapIn` then writes it to the live store's side record immediately
+ * before the rename. After the rename the parallel file sits at the live
+ * path beside that side record, so all three facts and the generation
+ * agree and the next writing open keeps the origin.
+ *
+ * The generation rotates on the carry, rather than staying the one the
+ * live side record held, so that nothing the rebuild leaves behind
+ * matches the side record afterwards. The backup and the replaced live
+ * file both hold the old generation in their rows: either renamed back
+ * over the store mints on its first write, even when it lands on an
+ * inode number the host reused. A rename that fails after the side
+ * record was written leaves the live file holding the old generation
+ * beside the new one, so it mints once on its next write, the safe
+ * side, and keeps on the write after. A parallel file whose
+ * `store_meta` has no `generation` column, as for a store written
+ * before `store-meta-generation`, is given its device and inode only;
+ * `carried` then holds a null generation and nothing is written to the
+ * side record, and the renamed file is judged by the three facts alone.
+ *
+ * Every other answer carries nothing, so the renamed file mints on its
+ * next write, which is the safe side. That covers a live file with no
+ * `store_meta` table or no row (an unminted store has no origin to
+ * carry), a live file that would mint itself (another host, path,
+ * device or inode, or a row generation its side record does not hold),
+ * and a parallel file whose row is not the live store's. On each of
+ * them the parallel file's row is still given a fresh random generation
+ * (`newGeneration`), where it has a row and a `generation` column, and
+ * the answer reports it in `spoiled`; nothing else in the row changes
+ * and nothing is written to the side record. Without it, the renamed
+ * file would hold the generation the side record holds, since the
+ * parallel file is built from the live one, and would be judged by the
+ * three facts alone; a file that lands at the path on the inode number
+ * its row names, which a host that reuses a freed number can give it,
+ * would then keep an origin that was due a mint. With the fresh
+ * generation the side record does not hold it, and the renamed file
+ * mints however the inode numbers fall. The row is never given a null
+ * generation, which would be judged by the three facts alone as well. A
+ * parallel file with no row or no `generation` column is left
+ * untouched, and `spoiled` is null. A write to the
+ * live store between the side record's write and the rename rotates the
+ * side record past the generation carried, so the renamed file mints as
+ * well. A write between the carry and the side record's write is
+ * overwritten in the side record by the generation carried, so the
+ * renamed file keeps the origin; the rows such a write adds were never
+ * in the parallel file, as for any write after the rebuild began.
+ */
+import type { StoreAccess } from './schema-plan.js';
+import type { MintReason, ProjectIdentity, RecordedIdentity } from './store-identity.js';
+import { Database } from 'bun:sqlite';
+/**
+ * What a store open reads the machine and the clock through. Every
+ * field falls back to the real one; tests pass the host id and the
+ * project and never read this machine's.
+ */
+export interface StoreIdentitySeams {
+    /** The host id. `readHostId` when absent. */
+    readonly readHostId?: () => string;
+    /** The project of the repository holding `dir`. `readProjectIdentity` when absent. */
+    readonly readProject?: (dir: string) => ProjectIdentity;
+    /** A new store id. `crypto.randomUUID` when absent. */
+    readonly newStoreId?: () => string;
+    /** A new generation. `crypto.randomUUID` when absent. */
+    readonly newGeneration?: () => string;
+    /** The time a mint records, in the row and for the id it replaces. `new Date()` when absent. */
+    readonly now?: () => Date;
+}
+/** The whole `store_meta` row. */
+export interface StoreMeta extends RecordedIdentity {
+    /** The project's smallest root commit. */
+    readonly projectRootCommit: string;
+    /** Its normalised `origin` remote, or null when it had none. */
+    readonly projectRemote: string | null;
+    /** The device the file was on, unsigned. */
+    readonly fileDev: bigint;
+    /** The file's inode, unsigned. */
+    readonly fileIno: bigint;
+    /** When the origin was minted, as an ISO string. */
+    readonly mintedAt: string;
+}
+/** What {@link settleStoreIdentity} did. */
+export type IdentityOutcome = 
+/** A read: nothing was read, observed or written. */
+{
+    readonly action: 'none';
+}
+/** A write to the store its origin was minted for: only a new generation written. */
+ | {
+    readonly action: 'keep';
+    readonly storeId: string;
+}
+/** A write that recorded the new origin `storeId` and a new generation, and settled `store_replaced`. */
+ | {
+    readonly action: 'mint';
+    readonly storeId: string;
+    readonly reasons: readonly MintReason[];
+}
+/** A write that was due a mint and wrote nothing, knowing no project. */
+ | {
+    readonly action: 'no-project';
+    readonly reasons: readonly MintReason[];
+};
+/** An unsigned 64-bit value as the signed INTEGER SQLite stores. */
+export declare function toStoredInteger(value: bigint): bigint;
+/** The unsigned value {@link toStoredInteger} stored as `text`. */
+export declare function fromStoredInteger(text: string): bigint;
+/**
+ * The `store_meta` row of the store `db` holds, or null when it holds
+ * none. The generation is null for a row whose store has no
+ * `generation` column yet, as for one written before it.
+ */
+export declare function readStoreMeta(db: Database): StoreMeta | null;
+/**
+ * Settles the identity of the store at `path`, open as `db`, for an open
+ * with `access`: nothing on a read; on a write, under the write lock,
+ * the recorded origin kept for the same file or a new one minted for an
+ * unminted store or a copy, and a new generation written to the row and
+ * the side record either way. A mint over a recorded origin also
+ * settles `store_replaced`: the outgoing id recorded when the host and
+ * the path were kept, the table emptied when either moved. See the
+ * module note.
+ */
+export declare function settleStoreIdentity(db: Database, path: string, access: StoreAccess, seams?: StoreIdentitySeams): IdentityOutcome;
+/**
+ * What {@link carryStoreIdentity} did. Every answer but `carried` reports
+ * in `spoiled` the fresh generation it wrote into the parallel file's
+ * row, the only thing it wrote there, or null when that file holds no
+ * `store_meta` row with a `generation` column and nothing was written.
+ */
+export type CarryOutcome = 
+/** The live file holds no `store_meta` table. */
+{
+    readonly action: 'no-table';
+    readonly spoiled: string | null;
+}
+/** The live file's `store_meta` holds no row: an unminted store. */
+ | {
+    readonly action: 'no-row';
+    readonly spoiled: string | null;
+}
+/** A write to the live file would mint, for `reasons`. */
+ | {
+    readonly action: 'mint';
+    readonly reasons: readonly MintReason[];
+    readonly spoiled: string | null;
+}
+/** The parallel file holds no `store_meta` row of the live store's id. */
+ | {
+    readonly action: 'other-row';
+    readonly spoiled: string | null;
+}
+/**
+ * The parallel file's row now records its own device and inode and the
+ * new `generation`, which the side record has yet to be given; null when
+ * its `store_meta` has no `generation` column, so none was written.
+ */
+ | {
+    readonly action: 'carried';
+    readonly storeId: string;
+    readonly generation: string | null;
+};
+/**
+ * Carries the identity of the live store at `livePath` onto the file at
+ * `parallelPath` that is about to be renamed over it. When
+ * `decideStoreIdentity('write', …)` answers keep for the live file and
+ * the parallel file holds a row of the live store's id, the parallel
+ * file's own device and inode and a new generation from
+ * `seams.newGeneration` (`crypto.randomUUID` when absent) are written
+ * into that row, and its store id, path, host and every other column are
+ * kept. The answer `carried` holds that generation, which the caller
+ * writes to the live store's side record immediately before the rename
+ * (`swapIn`, `rebuild-aside.ts`); this function writes no side record.
+ * On every other answer a new generation from the same seam is written
+ * into the parallel file's row, where it has one with a `generation`
+ * column, and nothing else, and the answer reports it in `spoiled`. The
+ * host id is read through `seams.readHostId` (`readHostId` when absent).
+ * Throws the filesystem's own error, which names the path, when either
+ * file does not exist. See the module note.
+ */
+export declare function carryStoreIdentity(livePath: string, parallelPath: string, seams?: StoreIdentitySeams): CarryOutcome;

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

@@ -0,0 +1,72 @@
+/**
+ * The ids a store carried before its present one: reading the table
+ * `store_replaced`, recording one id into it with the time it was
+ * replaced, and emptying it.
+ *
+ * ## What the table holds
+ *
+ * Migration `store-replaced` creates `store_replaced`, one row per id:
+ * `store_id`, its primary key, and `replaced_at`, an ISO string. Like
+ * `store_meta` it is SQLite-only, outside the port's row map, and
+ * `local` in `MERGE_RULES`, so it never leaves the machine. A store
+ * file found under the host and path its `store_meta` row names is this
+ * device's own store, moved or rolled back, and a claim made under an
+ * id held here is still this device's.
+ *
+ * ## What this module does not decide
+ *
+ * It reads and writes rows and nothing else. Which mint records the
+ * outgoing id and which one empties the table is the caller's decision,
+ * as is the transaction either write runs in: every function takes the
+ * open handle and begins none of its own, so a write made inside the
+ * caller's transaction commits or rolls back with it. No function opens
+ * a store; a caller passes the handle `withSqliteStore` (`sqlite.ts`)
+ * gave it.
+ *
+ * ## A store without the table
+ *
+ * A store an older runtime left has no `store_replaced`.
+ * {@link readReplacedStoreIds}
+ * answers none for it, the same answer as for an empty table, and
+ * creates nothing. {@link clearReplacedStoreIds} writes nothing to it,
+ * since a table that does not exist already holds no id.
+ * {@link recordReplacedStoreId} is the one that throws there, with
+ * SQLite's own `no such table: store_replaced`: an id that cannot be
+ * kept is not reported as kept.
+ *
+ * ## An id recorded twice
+ *
+ * The id is the primary key. Recording one the table already holds
+ * adds no row and keeps the time first recorded, because that is when
+ * the store stopped carrying the id.
+ */
+import type { Database } from 'bun:sqlite';
+/** One id a store carried before its present one. */
+export interface ReplacedStoreId {
+    /** The id the store carried. */
+    readonly storeId: string;
+    /** When the store stopped carrying it, as an ISO string. */
+    readonly replacedAt: string;
+}
+/**
+ * The ids the store `db` holds replaced, each with the time it was
+ * replaced, the earliest first and by id within one instant. Answers
+ * none for a store without the table and for one with it empty, and
+ * writes nothing either way.
+ */
+export declare function readReplacedStoreIds(db: Database): readonly ReplacedStoreId[];
+/**
+ * Records that the store `db` holds stopped carrying `storeId` at
+ * `replacedAt`, written as an ISO string. An id the table already holds
+ * keeps its first time and adds no row. Throws, writing nothing, when
+ * the id is empty or the time is no valid date, and throws SQLite's own
+ * error when the store has no `store_replaced` table. Begins no
+ * transaction; see the module note.
+ */
+export declare function recordReplacedStoreId(db: Database, storeId: string, replacedAt: Date): void;
+/**
+ * Removes every row of `store_replaced` from the store `db` holds and
+ * keeps the table. Writes nothing to a store without the table, and
+ * does not create it. Begins no transaction; see the module note.
+ */
+export declare function clearReplacedStoreIds(db: Database): void;

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

@@ -0,0 +1,223 @@
+/**
+ * The effort store's port: the contract both backends implement, and
+ * the one value they share.
+ *
+ * The sibling's store was bound to one file and one key projection per
+ * instance. This port is parameterised by row kind instead, per the
+ * spec's signature, so one store holds every kind and each call names
+ * the kind it acts on. Left there, that would reopen the failure the
+ * binding existed to prevent: a collector skipping by one projection of
+ * a row while the append dedupes by another, so work is read again or
+ * rows are duplicated, and both look like a store that is working. So
+ * the projection is not the caller's to pass. No method takes one;
+ * {@link EFFORT_KEY_PROJECTIONS} is a closed record a backend reads for
+ * `keys` and `append` alike.
+ *
+ * ## What every backend owes
+ *
+ * These are the sibling's NDJSON store's rules, carried over unchanged
+ * in behaviour, and the SQLite backend owes them too, so that nothing a
+ * caller typed against {@link EffortStore} relies on holds for one
+ * backend and not the other.
+ *
+ *   - Append-only. Nothing a store holds is rewritten or removed.
+ *   - `keys` is read back from the rows, never from a sidecar index,
+ *     which would be a second authority free to disagree with them. A
+ *     stored row with no key contributes nothing, rather than a
+ *     placeholder every other keyless row would collide with.
+ *   - `append` adds only the rows whose key is not already held,
+ *     whether it is held in storage or earlier in the same batch.
+ *   - A row with no key REFUSES the whole batch: the append throws
+ *     before anything is written. Such a row could never be
+ *     deduplicated, so appending it would duplicate it on every run.
+ *   - Writing nothing writes NOTHING. An append left with no row to add
+ *     creates no file and no directory, and `read` and `keys` on a
+ *     store that does not exist answer empty and create nothing either:
+ *     absence is the first-run case. Only absence is absorbed. A store
+ *     that exists and cannot be read throws, so it cannot pass for an
+ *     empty one and have everything appended again.
+ *
+ * ## What the port leaves out
+ *
+ * Readings only one storage format can make, such as the NDJSON line
+ * arithmetic, its unparsed-line count, or the newline it writes ahead
+ * of a partial last line, are not the port's. A backend reports those
+ * on a wider type of its own; {@link AppendResult} and `read` carry
+ * only what both backends can answer.
+ *
+ * There is no `close`, because the spec's port has no lifecycle method.
+ * A backend acquires and releases what it needs within each call; a
+ * handle held across calls would have no owner to release it.
+ *
+ * The port is synchronous because both backends can be. The sibling's
+ * NDJSON store reads and appends through `node:fs`'s synchronous calls,
+ * and `bun:sqlite`'s `run` and `all` return plain values rather than
+ * promises, measured on bun 1.3.14.
+ */
+import type { CommitStats } from './commit-stats.js';
+import type { PlanStubMatch } from './plan-stubs.js';
+import type { SessionKind, SessionStats } from './session-row-types.js';
+/**
+ * Where a session ran, as its row records it.
+ *
+ * `local` is the only member in this phase, and the collector writes it
+ * on every row. The spec reserves `remote` for phase 6, the phase that
+ * brings the remote transport, and the member joins this union then and
+ * not before: a union holding it now would let a row of this phase
+ * claim a mode no session of this phase can have.
+ */
+export type SessionMode = 'local';
+/**
+ * One stats row widened with what attribution answered and with the
+ * mode the session ran in — the row the collector's session half writes.
+ *
+ * Declared here rather than beside the collector that builds it, so the
+ * port depends only on the modules the row is made of and never on its
+ * own caller. `effort/collect.ts` re-exports it.
+ *
+ * Attribution reaches the row field by field, and one of its answers
+ * stays off it: `issueIdentifierSource`, where the identifier was read.
+ * The reconciled schema names the identifier alone.
+ *
+ * {@link SessionEffortRow.mode} and {@link SessionEffortRow.issueIdentifier}
+ * are the reconciled schema's widening, and a row collected before it
+ * carries neither. An append-only store never rewrites such a row, and
+ * the sibling's own store is made of them: measured on 2026-09-11, not
+ * one of its session rows carries either field. The row type is the
+ * port's assertion over a row read back, as it is for every other
+ * field, so a reader of that store meets the two fields ABSENT, which
+ * is neither `local` nor null.
+ */
+export interface SessionEffortRow extends SessionStats {
+    /** What the session was dispatched to do. */
+    kind: SessionKind;
+    /** Where the session ran: `local`, on every row of this phase. */
+    mode: SessionMode;
+    /** The modal branch of the session's records, or null. */
+    branch: string | null;
+    /** Records carrying it, and how many distinct branches were seen. */
+    branchRecordCount: number;
+    distinctBranchCount: number;
+    /** The branch split; the stub is not yet a plan stub. */
+    branchType: string | null;
+    branchStub: string | null;
+    /** The resolved plan, or null — never the branch stub as a fallback. */
+    planStub: string | null;
+    planStubMatch: PlanStubMatch;
+    /**
+     * The issue the session resolved to, upper-cased, or null — never the
+     * branch stub as a fallback. Read from the resolved plan stub, else
+     * from the whole branch name, by `effort/attribution.ts`.
+     */
+    issueIdentifier: string | null;
+    /** The dispatched task sentence, for a task session only. */
+    taskText: string | null;
+    /** Index of the enqueue among parsed records, or null if none. */
+    enqueueRecordIndex: number | null;
+    /** File size at collection; short of the file means a frozen row. */
+    sizeBytes: number;
+    /** File mtime at collection, ISO 8601. */
+    modifiedAt: string;
+    /**
+     * The worktree the session ran in, as an absolute path, or null for a
+     * session of the main checkout. A row collected before the field
+     * carries it ABSENT, as the module note says of `mode`; the SQLite
+     * backend's `worktree` column (migration `session-worktree`) reads
+     * NULL for both.
+     */
+    worktree: string | null;
+}
+/**
+ * One commit's row: the commit parser's answer, stored as parsed.
+ *
+ * An alias rather than a widening. The commit half appends exactly
+ * what `effort/commits.ts` answers, so the row is declared there.
+ */
+export type CommitEffortRow = CommitStats;
+/**
+ * The row each kind stores — the closed set every per-kind record in
+ * this module is typed against.
+ *
+ * A type alias rather than an interface, on purpose. An interface can
+ * be widened from outside this file by declaration merging and a type
+ * alias cannot: measured, a module augmentation re-declaring an alias
+ * is refused as a duplicate identifier, where the same merge into an
+ * interface compiles silently. A kind therefore enters the store here
+ * or nowhere, and entering it here is a compile error until
+ * {@link EFFORT_KEY_PROJECTIONS} names its key.
+ */
+export type EffortRowByKind = {
+    sessions: SessionEffortRow;
+    commits: CommitEffortRow;
+};
+/** The row kinds a store holds. */
+export type EffortRowKind = keyof EffortRowByKind;
+/** The row one kind stores. */
+export type EffortRow<K extends EffortRowKind> = EffortRowByKind[K];
+/** What one append did. */
+export interface AppendResult {
+    /**
+     * The file the append targeted, whether or not anything was written
+     * to it: the kind's own file, or one shared by every kind, as the
+     * backend lays its store out.
+     */
+    path: string;
+    /** Rows appended. Zero writes nothing and creates nothing. */
+    appended: number;
+    /**
+     * Rows whose key was already held, in storage or earlier in the
+     * batch. A batch that was not refused has no third outcome, so
+     * `appended + skipped` is its length.
+     */
+    skipped: number;
+}
+/**
+ * An effort store holding every row kind, under the rules in the
+ * module note.
+ *
+ * Property signatures rather than method signatures, as the sibling's
+ * store interface spelled its own. TypeScript compares a method's
+ * parameters bivariantly and a function-typed property's strictly, so
+ * a backend whose `keys` accepted only one of the kinds compiles
+ * against a method signature and is refused against this one.
+ */
+export interface EffortStore {
+    /**
+     * Appends the rows of one kind the store does not already hold.
+     *
+     * Throws, having written nothing, when any row of the batch carries
+     * no key under {@link EFFORT_KEY_PROJECTIONS}.
+     */
+    append: <K extends EffortRowKind>(kind: K, rows: readonly EffortRow<K>[]) => AppendResult;
+    /**
+     * The keys one kind already holds, which is what a collector skips.
+     * Read back from the rows, into a fresh set the caller owns.
+     */
+    keys: (kind: EffortRowKind) => Set<string>;
+    /** Every row one kind holds, in the order they were appended. */
+    read: <K extends EffortRowKind>(kind: K) => EffortRow<K>[];
+}
+/** Each kind's key projection, typed against that kind's own row. */
+export type EffortKeyProjections = {
+    readonly [K in EffortRowKind]: (row: EffortRow<K>) => string | null;
+};
+/**
+ * The key each kind is deduplicated by: `sessions` by session id,
+ * `commits` by sha.
+ *
+ * Closed over {@link EffortRowByKind}. A kind added there without a key
+ * here is a compile error, and so is a projection reading a field its
+ * kind's row does not carry. A backend answers `keys` and dedupes an
+ * `append` through this one record, with no projection of its own to
+ * substitute, and that is what keeps the set a collector skips by and
+ * the set an append dedupes by the same set.
+ *
+ * A projection answers null for a row that carries no key: the field
+ * absent, not a string, or empty. That puts the keyless rule a batch
+ * is refused by in one place too. The check is made on the value
+ * rather than trusted to the row's type, because a row read back from
+ * storage is only as typed as the file it came from. Only the empty
+ * string is empty — a key is not trimmed — which is the sibling store's
+ * rule, so the two agree on every stored row's key.
+ */
+export declare const EFFORT_KEY_PROJECTIONS: EffortKeyProjections;

package/dist/errors/codes.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Cause codes: the `<family>:<leaf>` names of known error contexts, and
+ * the checks every list of them passes (#949).
+ *
+ * A code marks which gate tripped: the family names the gate or tool
+ * (`git`, `tsc`, `fs`), the leaf the condition. Two bugs sharing a code
+ * may still fail in different things, so a code raises a match score and
+ * never decides it.
+ *
+ * Every family holds `<family>:new-context` without declaring it, for a
+ * cause no leaf fits yet; `unknown:new-context` is the last resort when
+ * even the family is unknown. Both reserved words are refused as declared
+ * leaves, and `unknown` as a declared family, so a listed code always
+ * names a real context. `context/error-codes.md` is the page for the list.
+ */
+/** How loud an error of the code is. */
+export type ErrorLevel = 'error' | 'warn';
+/** Every level, in the order a refusal names them. */
+export declare const ERROR_LEVELS: readonly ErrorLevel[];
+/** One known error context. */
+export interface ErrorCodeEntry {
+    /** `<family>:<leaf>`, both kebab-case. */
+    readonly code: string;
+    /** One line: what the context is. */
+    readonly description: string;
+    /** The recommended next action. */
+    readonly hint: string;
+    /** How loud an error of the code is. */
+    readonly level: ErrorLevel;
+    /**
+     * The version or issue that added the code. rafa's own list always
+     * names it ({@link defineErrorCodes} refuses an entry without one); a
+     * project's entry may leave it out.
+     */
+    readonly since?: string;
+    /** The spelling an older per-module union gives the same context. */
+    readonly legacy?: string;
+}
+/** A declarable code: kebab family, colon, kebab leaf. */
+export declare const CODE_PATTERN: RegExp;
+/** The leaf every family holds for a cause no leaf fits yet. */
+export declare const NEW_CONTEXT_LEAF = "new-context";
+/** The family of the last resort, and a leaf no entry may take. */
+export declare const UNKNOWN_FAMILY = "unknown";
+/** The part of `code` before its colon. */
+export declare function familyOf(code: string): string;
+/** Why `code` cannot be declared, or null when it can. */
+export declare function codeProblem(code: string): string | null;
+/**
+ * `entries`, frozen, once each passes the shape check and no code is
+ * declared twice. Throws a `TypeError` naming the first fault: the list
+ * is source, so a fault is a build error, never a reading to recover.
+ */
+export declare function defineErrorCodes(entries: readonly ErrorCodeEntry[]): readonly ErrorCodeEntry[];
+/** True for a declared code, a declared family's new-context, or `unknown:new-context`. */
+export declare function isKnownCode(code: string, entries: readonly ErrorCodeEntry[]): boolean;