@open-tomato/rafa 0.45.0 → 0.46.0

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

@@ -0,0 +1,340 @@
+/**
+ * The effort store's SQLite backend: the port over `bun:sqlite`, with
+ * every kind in one file.
+ *
+ * ## Layout
+ *
+ * One file, `effort.sqlite`, in the directory the NDJSON backend's
+ * files live in, which `effortStoreDir` (`location.ts`) spells once for
+ * both: `.rafa/effort/` (`EFFORT_STORE_DIR` in `ndjson-files.ts`),
+ * ignored by the project's `.gitignore` entry for `.rafa/`, or the
+ * directory `RAFA_EFFORT_DIR` names, which moves both backends together.
+ * The two backends can therefore hold a store side by side, and
+ * neither is committed unless the project sets `tracking.all`.
+ *
+ * One table per kind, named for the kind and keyed by the key the
+ * NDJSON rows are deduplicated by. Each table has these five columns,
+ * and `sessions` a sixth:
+ *
+ *   - `seq`, the order the row was appended in.
+ *   - The kind's key, filled from {@link EFFORT_KEY_PROJECTIONS}:
+ *     `session_id` for `sessions` and `sha` for `commits`, the names the
+ *     reference schema gives the same two keys. It is `NOT NULL` and
+ *     `UNIQUE` and refuses an empty string, so no stored row lacks one.
+ *   - `row_json`, the row itself.
+ *   - `origin_store` and `origin_seq`, the store's origin and the row's
+ *     own `seq`, which the append stamps as every production insert
+ *     does (`origins.ts`), NULL in both on a store with no origin.
+ *   - `worktree`, on `sessions` alone, the row's `worktree` field
+ *     repeated from `row_json` (migration `session-worktree`), NULL for
+ *     a session of the main checkout and for a row without the field.
+ *
+ * The row is stored whole, as the JSON text the NDJSON backend writes
+ * as a line, and read back through `JSON.parse` as that backend reads
+ * its lines. Both backends make the same pair of calls on the same row,
+ * so a row read from one is byte-identical to its counterpart in the
+ * other by construction, which is what the parity test holds them to.
+ * The row is not spread over a column per field. A session row carries
+ * open-keyed histograms (records by type, branch, entrypoint, effort
+ * and model) that no fixed column set can hold, and a row rebuilt from
+ * columns would have to reproduce the collector's field order to come
+ * out byte-identical. The key is the one field SQLite has to see,
+ * because the uniqueness constraint on it is what deduplicates.
+ * `worktree` is repeated beside it only so a query can read it; `read`
+ * still answers the row from `row_json`, so both backends' rows stay
+ * byte-identical.
+ *
+ * `seq` is an `INTEGER PRIMARY KEY`, SQLite's alias for the rowid, so
+ * the append order is a column the schema declares rather than an
+ * implicit one. That is a declaration, not a repair: measured on SQLite
+ * 3.51.0, a `VACUUM` left implicit rowids where they were as well.
+ *
+ * The file holds seventeen tables that are not kinds. Six are filled from
+ * task reports: `findings`, `blockers`, `out_of_scope_bugs` and
+ * `changes`, one per list a report carries, `report_absences`, one row
+ * per task session whose output held no report to read, and
+ * `task_reports`, one row per task session whose output carried one,
+ * holding its status. Four are filled from no report: `preflight`, one
+ * row per item a run's preflight checked, `dispatches`, one row per task
+ * session the loop spawned, `skill_invocations`, one row per skill a
+ * session invoked, and `plan_ci`, one row per reading of a plan's CI.
+ * An eleventh, `stale_docs`, is filled from task reports as the first
+ * six are, one row per documentation line a report named as stale;
+ * `stale-docs.ts` writes it and holds its row type. A twelfth,
+ * `bug_routes`, holds one row per `out_of_scope_bugs` entry the triage
+ * step routed; `bug-routes.ts` writes it and holds its row type. The
+ * thirteenth is `schema_migrations`, the migration log, which only
+ * `bring-forward.ts` writes; the section on bringing a store forward
+ * says what it holds. The last four are the store's own identity and
+ * merge trail: `store_meta`, `store_replaced`, `merges` and
+ * `merge_conflicts`. The port's row map names none of them, and
+ * nothing in this module reads or writes them. `findings.ts` writes the
+ * first, `triage.ts` the next two, `changes.ts` the fourth,
+ * `absences.ts` the fifth, `reports.ts` the sixth, `preflight.ts` the
+ * seventh, `dispatches.ts` the eighth, `skill-invocations.ts` the ninth
+ * and `plan-ci.ts` the tenth. `tracker-refs.ts` writes the first as
+ * well, setting a filed issue's reference on a row and inserting the
+ * row when there is none. `findings.ts`, `triage.ts`, `changes.ts`,
+ * `stale-docs.ts`, `preflight.ts` and `skill-invocations.ts` write through
+ * {@link writeSqliteStore}, as an append does, so a write left with
+ * nothing to insert still meets the schema check. `absences.ts` always
+ * has its one row and opens {@link withSqliteStore} directly, as
+ * `tracker-refs.ts` does with the one row it places. `reports.ts`
+ * always has its one row too, and passes {@link writeSqliteStore} a
+ * count of one, which opens the store as that direct call does, and so
+ * do `dispatches.ts` and `plan-ci.ts`. Each table is opened, brought
+ * forward and closed as every kind's table is. Each writer says why its
+ * tables have a column per field and their own deduplication keys,
+ * where a kind has `row_json` and one key.
+ *
+ * ## The port's rules, as they come out here
+ *
+ *   - Append-only. `append` inserts, and nothing here updates or
+ *     deletes a row.
+ *   - `keys` is read back from the rows. It answers each stored row's
+ *     key column, which is the column the uniqueness constraint dedupes
+ *     by, so the set a collector skips by and the set an append dedupes
+ *     by are one set. The key field inside `row_json` is read by
+ *     neither.
+ *   - Duplicate suppression covers the batch as well as the disk. The
+ *     batch is inserted under `ON CONFLICT (<key>) DO NOTHING`, so a key
+ *     repeated within it conflicts with the row its first occurrence
+ *     inserted, and the first occurrence stays, as in the NDJSON file.
+ *     That form rather than `INSERT OR IGNORE`, because measured,
+ *     `OR IGNORE` also swallows a `NOT NULL` violation as a skipped row,
+ *     where the upsert form absorbs the key conflict and throws on
+ *     anything else.
+ *   - The batch is checked before the store is opened. Every key is
+ *     projected and every row serialised first, so a refused batch, or
+ *     a row `JSON.stringify` throws on, leaves the file byte-identical,
+ *     and on a store that does not exist yet leaves no file and no
+ *     directory. A batch that passes is inserted in one transaction,
+ *     and lands whole or not at all.
+ *   - Writing nothing writes NOTHING, and still checks the schema. An
+ *     empty batch on a store that does not exist opens nothing. On a
+ *     store that exists it opens the store, through
+ *     {@link writeSqliteStore}, so an empty append is brought forward,
+ *     or refused, as a batch with rows is, and inserts nothing. An
+ *     empty append, or one whose every row is already held, leaves a
+ *     current store's bytes identical, measured, where an append that
+ *     adds a row changes them.
+ *   - Absence is the first-run case. `read`, `keys` and an empty append
+ *     answer empty for a store with no file, without opening one, and
+ *     only an append with a row to add opens the store with SQLite's
+ *     create flag. Measured, an open without that flag refuses a missing
+ *     file with `SQLITE_CANTOPEN` and creates nothing.
+ *   - A store that exists and cannot be read throws. Measured, a
+ *     directory at the path refuses to open (`SQLITE_CANTOPEN`), and a
+ *     file that is not a database refuses its first statement
+ *     (`SQLITE_NOTADB`). A zero-byte file is an empty database to
+ *     SQLite, and is what a run killed between creating the file and
+ *     its first commit leaves, so it reads as an empty store and is
+ *     given the schema.
+ *
+ * ## What does not carry over from the NDJSON backend
+ *
+ * There is no partial last line to tolerate. SQLite commits a
+ * transaction whole or not at all (measured, a throw inside one rolls
+ * back its rows and its schema changes alike), so a run killed
+ * mid-append leaves no half-row. Nor can any append write a `row_json`
+ * that is not a JSON object, so `read` throws on one rather than
+ * skipping it. The NDJSON reader tolerates a malformed line because of
+ * a failure mode this store does not have; carried over, the tolerance
+ * would only hide a row written from outside.
+ *
+ * A key holding a lone UTF-16 surrogate REFUSES its batch here, where
+ * the NDJSON backend would store it. `JSON.stringify` escapes a lone
+ * surrogate, so the row would survive in `row_json`, but the key column
+ * is bound as UTF-8 text, and bun converts a lone surrogate lossily.
+ * Measured: `ab\uD800cd` comes back as `ab\u{10063}d`, the very text a
+ * genuine astral character binds to, so two distinct keys would share
+ * one row and the second would be dropped as a duplicate. A key the
+ * store cannot deduplicate by refuses its batch, which is the port's
+ * rule for a keyless row. The collectors' keys are log file basenames
+ * and hex shas, so this guards against a key they are not expected to
+ * produce.
+ *
+ * The journal stays SQLite's default rollback journal, measured as
+ * `delete` on a fresh store, with nothing left beside the file once a
+ * call returns. The reference switches to the write-ahead log. Under
+ * WAL a committed row can sit in the `-wal` file rather than in the
+ * store, so the store file's bytes would stop being the store, and
+ * comparing them, which is how a refused batch is shown to have written
+ * nothing, would stop meaning anything. Measured on macOS, where bun
+ * uses Apple's SQLite, a WAL store also leaves its `-wal` and `-shm`
+ * files behind after a close.
+ *
+ * Every call opens the store, does its work and closes it before
+ * returning, because the port has no `close`. Measured, thirty
+ * open-append-close cycles left no descriptor on the file open, where
+ * one open connection holds one. Every open sets `PRAGMA busy_timeout`
+ * to `effort.busyTimeoutMs`, read off `activeStoreSettings`
+ * (`settings.ts`) at each open and five seconds by default, so a call
+ * that finds another process holding the write lock waits up to that
+ * long for its turn and throws `SQLITE_BUSY` past it. Measured without
+ * it, an open that found a migration pending while another process held
+ * the lock threw `SQLITE_BUSY` at once.
+ *
+ * ## Bringing a store forward
+ *
+ * The schema's history, `SQLITE_MIGRATIONS`, lives in `./migrations.ts`,
+ * whose module note says what each named entry declares. It and its
+ * length, `SQLITE_SCHEMA_VERSION`, are re-exported here. Every call
+ * opens the store through {@link withSqliteStore}, which hands it to
+ * `bringForward` (`bring-forward.ts`) before any read or write. Each
+ * caller states its access: `keys`, `read` and every reader outside the
+ * port open for a `read`, and every writer, an empty write included,
+ * for a `write`. `planSchema` (`schema-plan.ts`) decides from the
+ * store's migration log, and `bringForward`'s module note says what is
+ * written and when. As it comes out here:
+ *
+ *   - A store with nothing to adopt or apply is used as it is. A read
+ *     of one writes nothing and takes no lock, so a read-only call
+ *     leaves a current store's bytes identical.
+ *   - A store a release before the log wrote, at a `user_version` from
+ *     1 to 13 with no `schema_migrations`, is adopted on its first open,
+ *     a read included, since adoption counts as a write. A fresh or
+ *     zero-byte file is given every migration.
+ *   - A development build (`bun src/rafa.ts`, a checkout's
+ *     `dist/cli.js`, `bun test`) adopts or applies only over a store
+ *     under the temporary directory or `RAFA_EFFORT_DIR`. Over any
+ *     other it throws `DevelopmentBuildRefusedError`
+ *     (`development-build.ts`) before any write, naming a live loop
+ *     recorded on the store, while a store with nothing pending is used
+ *     as it is.
+ *   - Whatever is pending is applied under `BEGIN IMMEDIATE`, after a
+ *     second plan under that lock. Measured in `sqlite.test.ts`: two
+ *     processes that open one fresh store at once both wait for the
+ *     lock, one applies every migration and the other finds nothing
+ *     pending and writes no row.
+ *   - A store `planSchema` refuses throws `SchemaRefusedError`, whose
+ *     message ends with the one command to run next, and no byte is
+ *     written. A store logging a migration this rafa does not know,
+ *     which breaks only older writers, is read and refused a write.
+ *   - Once the store is brought forward, a write open mints its origin
+ *     into `store_meta` when it holds none or is a copy
+ *     (`store-meta.ts`). A read open never touches that row, so a read
+ *     of a current store still writes nothing, minted or not.
+ *
+ * {@link migrateSchema} counts the history by position and keeps no
+ * log. No open and no command goes through it; `fix-schema.ts` builds
+ * its rebuild through `bringForward`, and tests plant pre-log stores
+ * with it.
+ */
+import type { SqliteMigration } from './migrations.js';
+import type { StoreAccess } from './schema-plan.js';
+import type { StoreIdentitySeams } from './store-meta.js';
+import type { EffortRowKind, EffortStore } from './types.js';
+import { Database } from 'bun:sqlite';
+export { SQLITE_MIGRATIONS, SQLITE_SCHEMA_VERSION } from './migrations.js';
+/** The store's file name, inside the directory `effortStoreDir` answers. */
+export declare const SQLITE_STORE_FILE_NAME = "effort.sqlite";
+/**
+ * The file the SQLite store lives in under one repo root, whether or
+ * not it exists yet: in `RAFA_EFFORT_DIR` when it is set, and under
+ * `<root>/.rafa/effort` otherwise (`location.ts`). Every kind's table,
+ * and every table the report writers fill, sit in it.
+ */
+export declare function sqliteStorePath(repoRoot: string): string;
+/**
+ * A lone UTF-16 surrogate: a high half with no low half after it, or a
+ * low half with no high half before it. There is no `u` flag, so the
+ * pattern reads code units, which is the level a lone half exists at.
+ * Nor is there a `g` flag, so `test` keeps no state between calls.
+ *
+ * Exported for the report writers, whose text lands in this file too.
+ */
+export declare const LONE_SURROGATE: RegExp;
+/**
+ * The pre-log way of bringing a database forward, which no open and no
+ * command takes: it writes no migration log, which is what lets a test
+ * plant a store as a release before the log left it.
+ *
+ * Brings a database's schema up to the last version a migrations array
+ * holds: the store's own history unless another is passed, which is
+ * what lets the version arithmetic be driven with a history of any
+ * length. `path` is what a refusal names the database as.
+ *
+ * Every pending migration runs in one `BEGIN IMMEDIATE` transaction,
+ * and the version is read again once the write lock is held, since
+ * another process may have migrated the store in the meantime. A
+ * failure anywhere leaves the database at the version it was found at,
+ * with nothing half-applied. A database already at the last version
+ * takes no lock and is not written to.
+ *
+ * Two databases are refused, and neither is written to:
+ *
+ *   - One already past the array's last version. A newer rafa wrote
+ *     it, and this one can neither vouch for its schema nor write rows
+ *     the newer one expects.
+ *   - One a migration fails on, such as a version-0 file that already
+ *     holds a table named for a kind. The migrations create their
+ *     tables without the `IF NOT EXISTS` the reference uses, so a table
+ *     nobody migrated is refused rather than adopted with a layout
+ *     nobody chose. Measured, the refusal leaves the file
+ *     byte-identical.
+ */
+export declare function migrateSchema(db: Database, path: string, migrations?: readonly SqliteMigration[]): void;
+/**
+ * Refuses a test process opening a store outside the temporary
+ * directory before anything is made (`guardTestProcess`, `location.ts`),
+ * then opens the store at `path`, sets its busy timeout to the active
+ * `effort.busyTimeoutMs` (`settings.ts`), brings its schema
+ * forward through `bringForward` for an open with `access`, settles its
+ * identity through `settleStoreIdentity` (`store-meta.ts`), hands it to
+ * `use`, and closes it whatever `use` did. A refused store throws
+ * `SchemaRefusedError` before `use` runs. Only a caller with a row to
+ * add passes `create`, and only then is the directory made.
+ *
+ * `access` is `write` for every caller that may write, whether or not
+ * it ends up writing, and `read` for one that only reads. A read can
+ * still write the store, when it adopts one or applies what is pending;
+ * the module note says when. Only a write mints: it records a new
+ * origin in `store_meta` when the store holds none or is a copy, and a
+ * read never reads or writes that row. `identity` is what the mint
+ * reads the host, the project and the clock through; every caller but
+ * a test leaves it out.
+ *
+ * Exported so the tables outside the port are opened, brought forward
+ * and closed exactly as every kind's is. A write that can be left with
+ * nothing to insert goes through {@link writeSqliteStore} instead.
+ */
+export declare function withSqliteStore<T>(path: string, access: StoreAccess, create: boolean, use: (db: Database) => T, identity?: StoreIdentitySeams): T;
+/**
+ * The one path every write that can be left with nothing to insert
+ * takes, whatever its batch size, so no writer can skip the schema
+ * check by having nothing to insert.
+ *
+ * With rows to insert, it opens the store, creating the file and its
+ * directory when absent, and answers what `insert` answers. With none,
+ * it still opens a store that exists for a write, so `bringForward`
+ * brings it forward or refuses it as it would for a write with rows,
+ * and it answers `empty` without calling `insert`. Only an empty write on a
+ * store that does not exist opens nothing, creating no file and no
+ * directory: the branch `read` and `keys` take on an absent store.
+ *
+ * `rowCount` counts what is left to insert once the caller has checked
+ * its batch. The check comes before this call, so a refused batch opens
+ * nothing.
+ */
+export declare function writeSqliteStore<T>(path: string, rowCount: number, empty: T, insert: (db: Database) => T): T;
+/**
+ * The SQLite backend's surface: the port, plus the one reading the
+ * NDJSON backend also makes, so a caller holding either can find the
+ * file a kind lives in.
+ */
+export interface SqliteEffortStore extends EffortStore {
+    /**
+     * The file one kind lives in, whether or not it exists yet. For this
+     * backend it is the same file for every kind.
+     */
+    path: (kind: EffortRowKind) => string;
+}
+/**
+ * Opens the SQLite store under one repo root.
+ *
+ * Opening touches nothing on disk. Each call opens the file afresh,
+ * brings its schema forward and closes it before returning, which is
+ * why the port has no `close` for this backend to need.
+ */
+export declare function openSqliteStore(repoRoot: string): SqliteEffortStore;

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

@@ -0,0 +1,17 @@
+/** What follows the store file's name in its side record's name. */
+export declare const STORE_GENERATION_SUFFIX = ".generation";
+/** The side record's path for the store file at `storePath`: the same path with `.generation` appended. */
+export declare function storeGenerationPath(storePath: string): string;
+/**
+ * The generation in the side record of the store file at `storePath`,
+ * trimmed, or null when the record is absent or empty. Throws the
+ * filesystem's error for any other failure to read it.
+ */
+export declare function readStoreGeneration(storePath: string): string | null;
+/**
+ * Writes `generation` to the side record of the store file at
+ * `storePath` through a temporary file and a rename. Throws, with the
+ * temporary file removed, when the generation is refused or the write
+ * or rename fails.
+ */
+export declare function writeStoreGeneration(storePath: string, generation: string): void;

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

@@ -0,0 +1,220 @@
+/**
+ * Which store a row came from: the facts a writing open compares to
+ * tell whether this file is still the store its origin was minted for,
+ * the generation that tells it whether this is the file last written,
+ * and the decision whether to mint a new one.
+ *
+ * ## The origin is the store, never the machine
+ *
+ * A row's origin pair is `(origin_store, origin_seq)`. Two stores that
+ * stamp one `origin_store` write colliding pairs as soon as both count
+ * past the rows they share, so a store that is a copy of another must
+ * stamp a new one. The rule every check here follows: **minting a new
+ * origin is always safe, and missing a copy is not.** An extra origin
+ * only adds a store id; a missed copy lets two stores write the same
+ * pairs. So each doubt resolves towards minting.
+ *
+ * ## The three facts
+ *
+ * `store_meta` records three facts when the origin is minted, and
+ * {@link decideStoreIdentity} mints again when a writing open finds any
+ * one of them different:
+ *
+ *   - The **host id** ({@link readHostId}). A store opened on another
+ *     machine is a copy.
+ *   - The store file's **absolute path**, read through its real path
+ *     ({@link readStoreFileFacts}), so a symlinked spelling of the same
+ *     file is the same path. A store copied to another path is a copy.
+ *   - Its **file identity**, device and inode. A `.bak` renamed back
+ *     over the store has the path and the host and a new inode, so it
+ *     is caught; the host id alone would miss it.
+ *
+ * A store renamed away and back to its own path keeps all three, and
+ * its origin. A store `rafa effort copy` builds is a new file and gets
+ * a new origin, which is harmless. The file `fix-schema`, `migrate` and
+ * `rafa effort merge` swap in is new as well, but the swap carries the
+ * store's identity onto it before the rename (`carryStoreIdentity`,
+ * `store-meta.ts`), so it keeps the origin. The backup the swap writes
+ * is the copy: it has an inode of its own and names the original's, so
+ * renamed back over the store it mints.
+ *
+ * Two copies these facts cannot see, measured on 2026-09-29 on tmpfs:
+ * a `.bak` restored with `cp` over the existing file is written into
+ * the old inode, so all three facts match; and a disk cloned whole
+ * matches all three as well. The generation below catches the first
+ * once the store was written after the `.bak` was taken. The merge
+ * catches what is left afterwards, since one origin pair holding two
+ * contents can only come from a missed copy.
+ *
+ * ## The generation
+ *
+ * `store_meta.generation` holds a generation, and the side record
+ * beside the store's real path (`store-generation.ts`) holds one too.
+ * A copy of the store file carries the row and leaves the side record
+ * behind, so {@link observeStore} reads the side record with the three
+ * facts, and {@link decideStoreIdentity} mints with the reason
+ * `generation` when the row holds a generation and the side record
+ * holds another or none. That holds whatever the inode, so it reaches
+ * a file the three facts call the same: a row one generation behind
+ * its side record mints with the host, path, device and inode all
+ * unchanged.
+ *
+ * A row whose generation is NULL was written by a runtime that did not
+ * know the column, or minted before any open wrote one. Its generation
+ * proves nothing, so the three facts alone judge it, and a side record
+ * beside it changes nothing. This module only decides: writing a new
+ * generation to the row and the side record is the caller's.
+ *
+ * ## The host id is a keyed hash
+ *
+ * `/etc/machine-id` on Linux, the `IOPlatformUUID` that
+ * `ioreg -rd1 -c IOPlatformExpertDevice` prints on macOS, and
+ * `os.hostname()` anywhere else or when the platform's own source says
+ * nothing. `machine-id(5)` asks that the id never be used directly, only
+ * through a keyed hash under an application-specific key, and a store
+ * travels to other devices, so the host id is {@link hostIdFrom}: an
+ * HMAC-SHA256 of the source name and the value. The hash keeps the
+ * sources apart, so a hostname can never equal a machine id.
+ *
+ * ## The project identity
+ *
+ * {@link readProjectIdentity} reads the root commit and the `origin`
+ * remote, which a merge compares to refuse two stores of different
+ * projects. The remote is stored normalised (`normalizeRemote`), which
+ * strips any credentials a URL carries and makes the spellings two
+ * checkouts use for one repository equal. Neither is a copy fact: a
+ * remote added later is the same store.
+ *
+ * ## A read decides nothing
+ *
+ * An open that only reads never mints, and never asks for the facts:
+ * `decideStoreIdentity` takes them as a function it calls on a write
+ * alone, so a read spawns no `ioreg`, stats nothing and writes nothing.
+ */
+import type { StoreAccess } from './schema-plan.js';
+import type { GitRunner } from '../../core/git/index.js';
+/** Which source a host id was derived from. */
+export type HostIdSource = 'machine-id' | 'platform-uuid' | 'hostname';
+/** What {@link readHostId} reads the machine through. */
+export interface HostIdSeams {
+    /** `process.platform`'s spelling. `os.platform()` when absent. */
+    readonly platform?: string;
+    /** The Linux machine id, or null when there is none. */
+    readonly readMachineId?: () => string | null;
+    /** The macOS platform UUID, or null when there is none. */
+    readonly readPlatformUuid?: () => string | null;
+    /** The hostname, the fallback. `os.hostname()` when absent. */
+    readonly readHostname?: () => string;
+}
+/**
+ * The host id stored for `value` read from `source`: the hex
+ * HMAC-SHA256 of `<source>:<value>` under this module's key. Never the
+ * value itself; see the module note.
+ */
+export declare function hostIdFrom(source: HostIdSource, value: string): string;
+/**
+ * The `IOPlatformUUID` value in `ioreg -rd1 -c IOPlatformExpertDevice`
+ * output, or null when no line carries one.
+ */
+export declare function parseIoregPlatformUuid(output: string): string | null;
+/**
+ * This machine's host id: from the machine id on Linux, the platform
+ * UUID on macOS, the hostname otherwise or when that source answers
+ * nothing. Tests pass every seam and never read the real machine.
+ */
+export declare function readHostId(seams?: HostIdSeams): string;
+/** Where the store file is and which file it is. */
+export interface StoreFileFacts {
+    /** The file's real path: absolute, with every symlink resolved. */
+    readonly storePath: string;
+    /** The device the file is on. A bigint, so no inode is rounded. */
+    readonly fileDev: bigint;
+    /** The file's inode on that device. */
+    readonly fileIno: bigint;
+}
+/**
+ * The absolute path and file identity of the store file at `path`.
+ * Throws the filesystem's own error, which names the path, when the
+ * file does not exist.
+ */
+export declare function readStoreFileFacts(path: string): StoreFileFacts;
+/** What a writing open observes: the three facts and the side record's generation. */
+export interface StoreIdentityFacts extends StoreFileFacts {
+    /** {@link readHostId}'s answer. */
+    readonly hostId: string;
+    /** The generation in the side record beside the store's real path, or null when it has none. */
+    readonly generation: string | null;
+}
+/**
+ * The facts of the store file at `path`, with the host id `readHost`
+ * answers ({@link readHostId} when absent) and the generation the side
+ * record beside its real path holds.
+ */
+export declare function observeStore(path: string, readHost?: () => string): StoreIdentityFacts;
+/**
+ * The identity a store recorded when its origin was minted. The device
+ * and inode may come back from SQLite as numbers.
+ */
+export interface RecordedIdentity {
+    /** The origin the store stamps on the rows it writes. */
+    readonly storeId: string;
+    /** The host id it was minted on. */
+    readonly hostId: string;
+    /** The absolute path it was minted at. */
+    readonly storePath: string;
+    /** The device its file was on. */
+    readonly fileDev: bigint | number;
+    /** Its file's inode. */
+    readonly fileIno: bigint | number;
+    /**
+     * The generation last written into the row, or null for a row written
+     * by a runtime before the `generation` column, which only the three
+     * facts judge.
+     */
+    readonly generation: string | null;
+}
+/**
+ * Why a writing open mints: the store holds no identity yet, the host,
+ * the path or the file (device or inode) differs from the one recorded,
+ * or the row holds a generation the side record does not.
+ */
+export type MintReason = 'unminted' | 'host' | 'path' | 'file' | 'generation';
+/** What a store open does about its identity. */
+export type IdentityDecision = 
+/** A read: nothing is minted, compared or observed. */
+{
+    readonly action: 'none';
+}
+/** A write to the store the origin was minted for: stamp `storeId`. */
+ | {
+    readonly action: 'keep';
+    readonly storeId: string;
+}
+/** A write that must mint a new origin and record `facts`. */
+ | {
+    readonly action: 'mint';
+    readonly reasons: readonly MintReason[];
+    readonly facts: StoreIdentityFacts;
+};
+/**
+ * What an open with `access` does about the store's identity, given the
+ * identity it `recorded` (null when it holds none). A read answers
+ * `none` without calling `observe`. A write observes the store once and
+ * mints when nothing is recorded, any of the three facts moved, or the
+ * row holds a generation the side record does not; it keeps the
+ * recorded origin otherwise.
+ */
+export declare function decideStoreIdentity(access: StoreAccess, recorded: RecordedIdentity | null, observe: () => StoreIdentityFacts): IdentityDecision;
+/** The project a store belongs to, as a merge compares it. */
+export interface ProjectIdentity {
+    /** The smallest root commit of `HEAD`, or null outside a repository with commits. */
+    readonly rootCommit: string | null;
+    /** `origin`'s URL, normalised and without credentials, or null when there is none. */
+    readonly remote: string | null;
+}
+/**
+ * The project identity of the repository holding `dir`, read through
+ * `git` (a runner in `dir` when absent). Never throws: a part git
+ * cannot read is null.
+ */
+export declare function readProjectIdentity(dir: string, git?: GitRunner): ProjectIdentity;