@open-tomato/rafa 0.44.0 → 0.46.0

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

@@ -0,0 +1,214 @@
+/**
+ * The findings writer: one row in the store's `findings` table for each
+ * entry of a task report's findings list.
+ *
+ * A task session ends its output with a `rafa:report` block,
+ * `parseReport` reads its findings list entry for entry, and
+ * {@link writeFindings} stores it. Each row is the `Sighting` a later
+ * phase promotes instincts from, and what the loop renders
+ * `progress.txt` from at dispatch.
+ *
+ * ## The row
+ *
+ * | Column | From |
+ * | --- | --- |
+ * | `id` | generated, `randomUUID` unless a seam replaces it |
+ * | `session_id`, `plan_stub`, `task_line` | the dispatch |
+ * | `kind`, `trigger`, `what`, `cause`, `resolution`, `artifact`, `signal` | the report entry, as parsed |
+ * | `outcome` | the loop: `done`, `blocked` or `failed` |
+ * | `tracker_ref` | null on every row this writer writes; `tracker-refs.ts` sets it |
+ * | `collected_at` | the write's time, ISO 8601, one per write |
+ * | `origin_store`, `origin_seq` | the store's origin and the row's own `seq`, NULL in both when unminted (`origins.ts`) |
+ *
+ * `seq` comes first, the append order, as in every table of the store.
+ * An entry's `extras` are not stored: the table has a column for each
+ * field the report defines, and none for a key it does not.
+ *
+ * ## Where the table lives, and why it is not a kind
+ *
+ * In the SQLite store's file, created by the second entry of
+ * `SQLITE_MIGRATIONS` and written through `writeSqliteStore`, as every
+ * kind's append is. It is written there whichever backend the `store`
+ * setting selects: the NDJSON backend has no findings file. The table
+ * stays outside the port's row map on purpose, because a finding breaks
+ * three things the port holds of a kind:
+ *
+ *   - A kind is deduplicated by one key, which is also what a collector
+ *     skips by. A finding is deduplicated by one of two keys, and nothing
+ *     collects it.
+ *   - A kind's row is stored whole as JSON, so both backends hold it
+ *     byte for byte. A finding has a column per field, which is what the
+ *     spec names and what a query filters on.
+ *   - A kind's row is the same however often it is collected. A finding
+ *     row carries a generated id and the time it was written.
+ *
+ * ## Deduplication
+ *
+ * Within one session, an entry duplicates an earlier one when it carries
+ * the same `artifact`, or, carrying none, the same `trigger` and `what`.
+ * The earlier row stays, whether it is on disk or earlier in the same
+ * write, and nothing of the later entry is kept: two entries differing
+ * only in `resolution` are one row.
+ *
+ *   - The match is exact: byte for byte, no trimming, no case folding.
+ *     `artifact` is the string a recurrence is matched on, and a looser
+ *     match here would merge findings the report kept apart.
+ *   - An entry with an artifact never duplicates one without, even with
+ *     the same trigger and what. Each is keyed by its own rule, and the
+ *     two keys never meet.
+ *   - The scope is the SESSION, never the table. Promotion keys on one
+ *     artifact sighted by different tasks or sessions, and phase 1
+ *     comments on the issue a recurrence in a later task already filed.
+ *     A table-wide dedupe would keep one row per artifact ever, and
+ *     nothing could recur. Within a session, a report written twice
+ *     writes its rows once.
+ *
+ * Two partial unique indexes enforce it, one per rule, and the insert
+ * names both as conflict targets. Measured with bun 1.3.14 on SQLite
+ * 3.51.0:
+ *
+ *   - A target has to repeat its index's `WHERE`. Without it the insert
+ *     throws `ON CONFLICT clause does not match any PRIMARY KEY or UNIQUE
+ *     constraint`.
+ *   - Only those two conflicts are absorbed. An id generated twice
+ *     throws `UNIQUE constraint failed: findings.id` and rolls the whole
+ *     write back, where a bare `ON CONFLICT DO NOTHING` would drop the
+ *     second entry as if it were a duplicate.
+ *
+ * ## What is refused, and at which level
+ *
+ * The loop's own inputs refuse the WHOLE write: an empty session id, an
+ * outcome outside {@link FINDING_OUTCOMES}, or dispatch text holding a
+ * lone UTF-16 surrogate. The write throws before the store is opened,
+ * so it leaves no file behind and changes no byte of one that exists.
+ * Code supplies these, and a wrong one is a bug to surface, not a row to
+ * store. The check runs even when the findings list is empty.
+ *
+ * A report ENTRY is refused alone, and the rest are written. A model
+ * wrote the entries, and one it got wrong must not cost the findings it
+ * got right. That is where this writer departs from the port, which
+ * refuses a whole batch for one keyless row. A refused entry is never
+ * stored, and is answered in {@link FindingsWriteResult.rejected}:
+ *
+ *   - `unstorable-field`: a value `parseReport` never answers. A text
+ *     field that is not a string, is blank, or holds a lone UTF-16
+ *     surrogate, or a kind or signal outside its closed set. A blank key
+ *     would merge every blank one, and a lone surrogate is bound lossily
+ *     (see `sqlite.ts`), merging distinct keys.
+ *   - `unkeyed`: no artifact, and no trigger or no what. Nothing could
+ *     deduplicate the row, so every rewrite would add it again.
+ *
+ * The table refuses those rows itself, through its CHECK constraints, so
+ * a row written from outside cannot hold what this writer rejects. The
+ * kind and signal sets are spelled in the migration, which never changes
+ * once shipped: widening either is a new migration, and the suite pins
+ * the migration's sets to `FINDING_KINDS` and `FINDING_SIGNALS`.
+ *
+ * `outcome` has no CHECK. The spec adds the CI verdict to it once one is
+ * known, and SQLite cannot change a CHECK in place: measured, `ALTER
+ * TABLE ... ADD CHECK` is a syntax error, so a widened set would mean
+ * rebuilding the table. The closed set is enforced here instead.
+ *
+ * ## Writing nothing writes nothing, and still checks the schema
+ *
+ * A write left with no entry to insert, because the list was empty or
+ * every entry was refused, inserts no row. On a store that does not
+ * exist it opens nothing, and creates no file and no directory. On one
+ * that exists it still opens the store, through `writeSqliteStore`, so
+ * the schema check runs as it does for a write with rows: a store past
+ * this rafa's version is refused with no byte changed, one below it is
+ * brought forward, and one already at this version changes no byte.
+ */
+import type { ReportFinding } from '../../report/parse.js';
+/**
+ * What the loop made of a task, as its findings rows record it. The
+ * report's own `status` is the session's claim; this is the loop's.
+ */
+export declare const FINDING_OUTCOMES: readonly ["done", "blocked", "failed"];
+/** One of the loop's outcomes. */
+export type FindingOutcome = (typeof FINDING_OUTCOMES)[number];
+/** The dispatch a report came from. */
+export interface FindingsDispatch {
+    /** The task session's id. Non-empty: it scopes deduplication. */
+    readonly sessionId: string;
+    /** The plan's stub, or null when the dispatch resolved none. */
+    readonly planStub: string | null;
+    /** The task line, as the dispatch quoted it. */
+    readonly taskLine: string;
+}
+/** One write: a report's findings, where they came from, and the outcome. */
+export interface FindingsWrite {
+    readonly dispatch: FindingsDispatch;
+    readonly outcome: FindingOutcome;
+    /** The report's findings list, as `parseReport` answers it. */
+    readonly findings: readonly ReportFinding[];
+}
+/** Seams for the two values a write generates. */
+export interface FindingsWriterSeams {
+    /** The write's time. Called once per write. Defaults to the clock. */
+    readonly now?: () => Date;
+    /** One row's id. Called once per stored entry. Defaults to `randomUUID`. */
+    readonly newId?: () => string;
+}
+/** Why one entry was not written. */
+export type FindingRejectionReason = 
+/** A field holds a value `parseReport` never answers. */
+'unstorable-field'
+/** No artifact, and no trigger or no what, to deduplicate it by. */
+ | 'unkeyed';
+/** One entry that was not written, and why. */
+export interface FindingRejection {
+    /** The entry's index in the findings list. */
+    readonly index: number;
+    readonly reason: FindingRejectionReason;
+    /** The field at fault, by its report key, or null for `unkeyed`. */
+    readonly field: string | null;
+    /** One sentence for an operator to read. */
+    readonly text: string;
+}
+/** What one write did. */
+export interface FindingsWriteResult {
+    /** The store's file, whether or not anything was written to it. */
+    readonly path: string;
+    /** Rows written. */
+    readonly appended: number;
+    /** Entries the session already held, on disk or earlier in the write. */
+    readonly skipped: number;
+    /**
+     * Entries refused, in list order. With these, `appended + skipped +
+     * rejected.length` is the findings list's length.
+     */
+    readonly rejected: readonly FindingRejection[];
+}
+/**
+ * A value as a refusal quotes it. Never serialises an object. Exported
+ * for the triage writer, so its refusals quote a value the same way.
+ */
+export declare function describeValue(value: unknown): string;
+/**
+ * Why a text value cannot be stored, or null when it is null or can be.
+ * Exported for the triage writer, whose text fields are held to it.
+ */
+export declare function textProblem(value: unknown): string | null;
+/**
+ * Throws unless a dispatch and an outcome can be stored on every row of
+ * one write. `subject` names the write in the refusal: `findings` here.
+ *
+ * Exported for the triage writer, so every table one report fills
+ * refuses a dispatch by the same rule and in the same words. A writer
+ * whose table has no outcome column passes null, and only the dispatch
+ * is checked; `changes.ts` is the one that does.
+ */
+export declare function checkDispatch(subject: string, dispatch: FindingsDispatch, outcome: FindingOutcome | null): void;
+/**
+ * Writes one report's findings for one dispatch, one row per entry the
+ * session does not already hold.
+ *
+ * Throws, having opened nothing, when the dispatch or the outcome cannot
+ * be stored. Throws the store's own refusal of a schema past this rafa's
+ * version whenever the store exists, even with nothing to insert. An
+ * entry that cannot be stored is left out and answered in `rejected`,
+ * and the others are written. See the module note for the dedupe rule
+ * and each refusal.
+ */
+export declare function writeFindings(repoRoot: string, write: FindingsWrite, seams?: FindingsWriterSeams): FindingsWriteResult;

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

@@ -0,0 +1,184 @@
+/**
+ * The repair `rafa effort fix-schema` runs: a SQLite store this rafa
+ * refuses, rebuilt at the migrations this rafa knows beside the live
+ * file, checked, and swapped in with the original kept as a backup.
+ *
+ * ## Which stores it repairs
+ *
+ * The decision is `planSchema`'s (`schema-plan.ts`), asked for a write
+ * from an ordinary open, as `rafa effort schema` asks it: a runtime that
+ * reads and writes the store is refused whatever a read alone would be.
+ * The store's `user_version` and migration log are read on a read-only
+ * connection, so a store that needs no repair keeps its bytes.
+ *
+ *   - A store the plan lets this rafa use is left alone: `current` when
+ *     nothing is to be adopted or applied, `behind` when the next
+ *     ordinary open brings it forward. A store logging migrations this
+ *     rafa does not know, each additive, is one of these, since this
+ *     rafa already reads and writes through them.
+ *   - Five refusals are repaired by a rebuild ({@link REPAIRABLE_REASONS}):
+ *     `pre-log-unreleased`, a store a branch build migrated past the
+ *     legacy entries with no log; `gate-mismatch`, a logged store a
+ *     build older than the log migrated; `edited`, a logged checksum
+ *     this rafa holds otherwise; and `unknown-breaks-readers` and
+ *     `unknown-breaks-writers`, a logged migration this rafa does not
+ *     know which breaks it.
+ *   - The other two, `breaking-out-of-order` and `breaking-pending`, are
+ *     about migrations this rafa knows and has not applied, which a
+ *     rebuild at those same migrations does not answer. They are refused
+ *     with the plan's own text, which ends with the command to run next.
+ *
+ * Installing a rafa that knows the store's migrations comes first
+ * wherever it can: a rebuild leaves what only the newer schema holds in
+ * the backup.
+ *
+ * ## The rebuild
+ *
+ * A parallel file, `<store>.fix-<stamp>`, is brought to this rafa's
+ * migrations by the log-aware apply (`bringForward`, `bring-forward.ts`),
+ * so it holds exactly the tables this rafa writes and a migration log
+ * with a row for every id this rafa knows, each `applied_by` naming this
+ * runtime ({@link appliedByName}: its version, with `+dev:<checkout>`
+ * for a development build). The live store is attached, and every table
+ * the parallel file holds, the log apart, is filled from the live table
+ * of the same name over the columns the parallel table has. A table or
+ * column this rafa does not know is not copied, and is reported as left
+ * behind with how many rows or values it held. So are the unknown
+ * migrations the live log names: they stay in the backup only, since an
+ * object copied into the rebuild with no log row would make the release
+ * that ships its migration fail on `CREATE TABLE`. The rebuild is
+ * refused when the live store lacks a table or a column this rafa
+ * knows, since copying around it would lose what this rafa writes.
+ *
+ * The parallel file is checked before anything else happens: the row
+ * count of every table copied must equal the live one, SQLite's
+ * `integrity_check` must answer `ok`, and `planSchema` must find it a
+ * store this rafa uses as it is. Under `dryRun` it is then deleted, so a
+ * dry run can be repeated and leaves the directory as it found it.
+ * Otherwise the live store is written out to
+ * `<store>.v<user_version>-<stamp>.bak` with `VACUUM INTO`, its identity
+ * is carried onto the parallel file (`carryStoreIdentity`,
+ * `store-meta.ts`), and the parallel file is renamed into its place.
+ * The rebuild keeps the live store's origin, so the rows it writes next
+ * carry the same store id; a store whose next write would have minted
+ * anyway is carried nothing and mints after the swap. The backup holds
+ * the whole original, left-behind data included, and restoring it is
+ * renaming it back. It is a copy with an inode of its own, so once
+ * renamed back over the store its first writing open mints a new
+ * origin (`store-identity.ts`).
+ *
+ * The live file is only ever read. A rollback journal or write-ahead log
+ * beside it means a write in flight or interrupted, so the repair is
+ * refused while either is there. Any failure while building removes the
+ * parallel file and leaves the live one untouched.
+ *
+ * Those steps, from the in-flight refusal to the swap, are the
+ * build-aside convention of `rebuild-aside.ts`, which this module runs
+ * with its own file names and its own build. `SchemaFixRefusal` is that
+ * module's `RebuildRefusal` under the name the command catches.
+ *
+ * ## A development build never swaps
+ *
+ * A development build (`readRuntimeIdentity`,
+ * `packages/rafa/src/core/runtime/identity.ts`) builds, checks and deletes a rebuild
+ * under `dryRun`, and is refused the swap before anything is built: its
+ * migrations may be a branch's, which no installed runtime knows. The
+ * parallel file is brought forward with `builtAside`, so the open's own development-build question, which
+ * would refuse a file in the project's store directory, is not asked of
+ * it; this refusal is that question, asked of the swap.
+ *
+ * It opens the store itself rather than through `withSqliteStore`, so it
+ * runs the test guard (`guardTestProcess`, `location.ts`) itself too,
+ * before it reads or makes anything.
+ */
+import type { SqliteMigration } from './migrations.js';
+import type { TableRows } from './rebuild-aside.js';
+import type { LoggedMigration, StoreSchema } from './schema-plan.js';
+import type { RuntimeIdentity } from '../../core/runtime/index.js';
+import { Database } from 'bun:sqlite';
+/** What the repair found, and what it did about it. */
+export type FixSchemaStatus = 
+/** No store file: nothing to repair, and none is created. */
+'missing'
+/** This rafa uses it as it is: nothing to repair. */
+ | 'current'
+/** This rafa uses it once the next ordinary open brings it forward: nothing to repair. */
+ | 'behind'
+/** Refused for a reason a rebuild repairs, under `dryRun`: the rebuild was made, checked and deleted. */
+ | 'would-rebuild'
+/** Refused for a reason a rebuild repairs: the rebuild was swapped in and the original kept as a backup. */
+ | 'rebuilt';
+/** The `planSchema` refusals a rebuild at this rafa's migrations repairs, in the order they are tried. */
+export declare const REPAIRABLE_REASONS: readonly ['pre-log-unreleased', 'gate-mismatch', 'edited', 'unknown-breaks-readers', 'unknown-breaks-writers'];
+/** A refusal a rebuild repairs. */
+export type RepairReason = typeof REPAIRABLE_REASONS[number];
+/** A table the rebuild copies, with the rows it holds. */
+export type KeptTable = TableRows;
+/** A table only the newer schema knows, with the rows the backup keeps. */
+export interface LeftTable {
+    readonly table: string;
+    readonly rows: number;
+}
+/** A column only the newer schema knows, with its non-null values the backup keeps. */
+export interface LeftColumn {
+    readonly table: string;
+    readonly column: string;
+    readonly values: number;
+}
+/** The outcome of one repair. */
+export interface FixSchemaResult {
+    /** The live store's file. */
+    readonly path: string;
+    readonly status: FixSchemaStatus;
+    /** The live store's `user_version`, or null when there is no file. */
+    readonly storeVersion: number | null;
+    /** Whether the live store holds a migration log. */
+    readonly logged: boolean;
+    /** The refusal a rebuild repairs, or null when the store needs none. */
+    readonly reason: RepairReason | null;
+    /** That refusal's text without its way out, since the repair is that way out, or null. */
+    readonly refusal: string | null;
+    /** The ids this rafa knows, in catalogue order: the ones a rebuild logs. */
+    readonly known: readonly string[];
+    /** Who a rebuild's log rows name as applying them. */
+    readonly appliedBy: string;
+    /** What the next ordinary open records, for `behind`: the log first when it adopts, then each pending id. */
+    readonly pending: readonly string[];
+    /**
+     * Logged migrations this rafa does not know. For `current` and
+     * `behind` each is one this rafa uses the store through; for a
+     * rebuild they stay in the backup only.
+     */
+    readonly unknown: readonly LoggedMigration[];
+    /** Every table copied; empty unless a rebuild was made. */
+    readonly kept: readonly KeptTable[];
+    readonly leftTables: readonly LeftTable[];
+    readonly leftColumns: readonly LeftColumn[];
+    /** Where the original went, for `rebuilt` only. */
+    readonly backupPath: string | null;
+}
+/** What one repair is handed. */
+export interface FixSchemaOptions {
+    /** The live store's file. */
+    readonly path: string;
+    /** Build and check the rebuild, then delete it instead of swapping it in. */
+    readonly dryRun: boolean;
+    /** Names the parallel and backup files, so two runs never collide. */
+    readonly stamp: string;
+    /** The migrations to rebuild at: this build's unless another list is passed. */
+    readonly migrations?: readonly SqliteMigration[];
+    /** Which build runs; `readRuntimeIdentity()` by default. */
+    readonly identity?: RuntimeIdentity;
+    /** The clock a rebuild's `applied_at` is read from. */
+    readonly now?: () => Date;
+}
+/** A repair refused before the live store was changed: the build-aside steps' refusal. */
+export { RebuildRefusal as SchemaFixRefusal } from './rebuild-aside.js';
+/** The user tables one attached schema holds, by name, the migration log apart. */
+export declare function tableNames(db: Database, schema: string): string[];
+/** The file's `user_version` and migration log, read on a read-only connection. */
+export declare function readOnlySchema(path: string): StoreSchema;
+/** Refuses a rebuild `planSchema` would not let this rafa use as it is. */
+export declare function refuseUnusable(db: Database, parallelPath: string, migrations: readonly SqliteMigration[]): void;
+/** Repairs the store at `options.path`. See the module note. */
+export declare function fixStoreSchema(options: FixSchemaOptions): FixSchemaResult;

package/dist/effort/store/index.js

@@ -1,7 +1,5 @@
 // @bun
 import {
-  EFFORT_KEY_PROJECTIONS,
-  TRUSTED_PERMISSIONS,
   WIRE_FORMAT,
   WIRE_VERSION,
   WireExportRefusal,
@@ -12,14 +10,19 @@ import {
   materialiseWirePayload,
   mergeStore,
   openNdjsonStore,
-  openSqliteStore,
   selectEffortStore
-} from "../../index-6q30dtgm.js";
+} from "../../index-jh1r4kcn.js";
+import {
+  EFFORT_KEY_PROJECTIONS,
+  TRUSTED_PERMISSIONS,
+  openSqliteStore
+} from "../../index-cy98y87p.js";
+import"../../index-2a7nb3an.js";
+import"../../index-gvek4r8m.js";
 import {
   STORE_BACKENDS
-} from "../../index-cknayrpc.js";
-import"../../index-nv34ptht.js";
-import"../../index-hf2k497d.js";
+} from "../../index-ykggr043.js";
+import"../../index-z1w83f81.js";
 export {
   selectEffortStore,
   openSqliteStore,

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

@@ -0,0 +1,44 @@
+/** The variable that moves the store of one command line. */
+export declare const EFFORT_DIR_VARIABLE = "RAFA_EFFORT_DIR";
+/** The variable that marks a process as a test's, whatever its entry. */
+export declare const TEST_PROCESS_VARIABLE = "RAFA_TEST";
+/** An environment, as `process.env` holds one. */
+export type StoreEnvironment = Readonly<Record<string, string | undefined>>;
+/** What the test guard reads about the process it runs in. */
+export interface TestProbe {
+    /** The entry file, `Bun.main` by default. */
+    readonly main: string;
+    /** The environment, `process.env` by default. */
+    readonly env: StoreEnvironment;
+    /** The temporary directory, `tmpdir()` by default. */
+    readonly tempDir: string;
+}
+/**
+ * The directory `RAFA_EFFORT_DIR` names, or null when it is unset or
+ * empty. Throws when it is relative, or names the store under
+ * `repoRoot`; see the module note.
+ */
+export declare function readEffortDirOverride(repoRoot: string, env?: StoreEnvironment): string | null;
+/**
+ * The directory both backends keep the store under `repoRoot` in:
+ * `RAFA_EFFORT_DIR` when it is set, and `<root>/.rafa/effort` otherwise.
+ * Throws as {@link readEffortDirOverride} does.
+ */
+export declare function effortStoreDir(repoRoot: string, env?: StoreEnvironment): string;
+/**
+ * True for a test process: an entry file ending in `.test.ts`, or
+ * `RAFA_TEST` set to exactly `1`.
+ */
+export declare function isTestProcess(main?: string, env?: StoreEnvironment): boolean;
+/**
+ * True when `path` is the temporary directory `tempDir` or lies under
+ * it, as spelled or with both resolved to their real paths; a `path`
+ * not made yet resolves through its nearest existing ancestor.
+ */
+export declare function isUnderTempDir(path: string, tempDir?: string): boolean;
+/**
+ * Throws when a test process opens a store at `path` outside the
+ * temporary directory, and does nothing otherwise. Called before any
+ * file or directory is made; see the module note.
+ */
+export declare function guardTestProcess(path: string, probe?: TestProbe): void;

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

@@ -0,0 +1,68 @@
+/**
+ * The merge's commit gaps: once the union (`merge-union.ts`) has brought
+ * another store's commits in, each one's `minutesSincePrevious` and that
+ * of the commit right after it in time are recomputed from the
+ * timestamps the store holds.
+ *
+ * ## Why only those rows
+ *
+ * A commit's gap is the minutes since the commit before it in time
+ * (`assignElapsedMinutes`, `src/effort/commits.ts`), measured with
+ * {@link minutesBetween}. A commit brought in between two commits here
+ * changes exactly two gaps: its own, which the other store measured
+ * against its own neighbours, and that of the commit after it, which now
+ * follows it rather than the commit before it. Every other gap keeps its
+ * predecessor. So each commit brought in touches at most two rows, and a
+ * row two of them name is written once. Where the store held the gaps a
+ * full recompute over its commits gives, it holds them over the union
+ * afterwards too; a gap a collection measured over a narrower range,
+ * such as the null of an incremental run's first commit, is left as it
+ * was unless a commit brought in lands right before it.
+ *
+ * There is no git call: the order and every gap come from the
+ * `timestamp` in each row's `row_json`.
+ *
+ * ## The order
+ *
+ * Commits are ordered by `Date.parse` of their timestamp, as
+ * `assignElapsedMinutes` orders them, and two at the same instant by
+ * sha, so a merge run from either side orders a tie alike. A row whose
+ * `row_json` does not parse, or whose timestamp does not, is left out of
+ * the order as `assignElapsedMinutes` leaves it out: it is no one's
+ * predecessor, and one brought in takes a null gap. The first commit in
+ * the order takes null.
+ *
+ * ## The write
+ *
+ * The gap lives inside `row_json`, so a recompute rewrites that column,
+ * `JSON.stringify` of the row with the one key replaced, which keeps the
+ * row's other keys and their order. A row whose gap already reads the
+ * recomputed value is not written. `MERGE_RULES` (`merge-rules.ts`)
+ * declares `commits.row_json` edited under {@link RECOMPUTED} for this
+ * statement, and `merge-conflicts.ts` compares two rows of one commit
+ * without the gap through {@link withoutGap}.
+ */
+import type { Database } from 'bun:sqlite';
+/** The key of `commits.row_json` a merge recomputes. */
+export declare const GAP_FIELD = "minutesSincePrevious";
+/** One commit row whose gap the recompute rewrote. */
+export interface GapRewrite {
+    readonly seq: number;
+    readonly sha: string;
+    readonly before: number | null;
+    readonly after: number | null;
+}
+/**
+ * `row_json` without its gap, for comparing two rows of one commit:
+ * the text unchanged when it is not a JSON object.
+ */
+export declare function withoutGap(rowJson: string): string;
+/**
+ * Recomputes, in `db`, the gap of each commit whose local `seq` is in
+ * `inserted` and of the commit right after it in time, as the module
+ * note says, in one transaction. Answers each row it rewrote, in time
+ * order; a row whose gap was already right, or whose `row_json` is not
+ * a JSON object, is not written and not answered. A `seq` no commit
+ * holds is ignored.
+ */
+export declare function recomputeCommitGaps(db: Database, inserted: readonly number[]): GapRewrite[];

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

@@ -0,0 +1,91 @@
+/**
+ * The merge's second step: each pair of rows the union matched
+ * (`merge-union.ts`) is compared, an edited field the two stores
+ * disagree on is settled by its rule, and any difference no rule settles
+ * is recorded in `merge_conflicts`, both rows kept.
+ *
+ * ## Comparing a pair
+ *
+ * The two rows are compared on every column but `seq` and the origin
+ * pair. `seq` is local order, and the pair may differ in a match on
+ * identity by design: a row with a NULL origin on one side, or a commit
+ * two devices collected under an origin each, is the same row.
+ *
+ * - **Equal** content: nothing is written, and the pair is skipped.
+ * - **Differing only in edited fields** (`MERGE_RULES`, `merge-rules.ts`):
+ *   each field follows its rule. Under {@link SET_ONCE} a filled value
+ *   beats NULL from either side: NULL here takes the other store's value,
+ *   and a value here is kept against NULL there; the pair is then
+ *   skipped. Two different filled values mean one finding was filed
+ *   twice: the value here is kept, and the incoming row is recorded with
+ *   `field` naming the column. Under {@link RECOMPUTED} the two values
+ *   are compared without the part the merge recomputes, through the
+ *   field's entry in {@link RECOMPUTED_COMPARISONS}: `commits.row_json`
+ *   without its `minutesSincePrevious` (`merge-commit-gaps.ts`). Equal
+ *   so, the pair is skipped and the row here kept; the gap of a commit
+ *   brought in is the merge's to rewrite, not a matched one's. Unequal,
+ *   the rows differ outside every edited field, below.
+ * - **Any other difference**: the incoming row is recorded with `field`
+ *   NULL, and the row here is left as it is, edited fields included. The
+ *   same `(origin_store, origin_seq)` holding different content can only
+ *   come from a copy the open did not catch, such as a cloned disk, and
+ *   one UUID holding different content is as unexplained.
+ *
+ * A recorded conflict keeps the incoming row as the JSON of all its
+ * columns, its `seq` in the other store and its origin pair included,
+ * beside the local row's `seq`. Nothing blocks on it: the next pair is
+ * compared. A merge run again meets the same pair and records it again
+ * under its own merge id.
+ *
+ * ## The fill statements
+ *
+ * A fill is an `UPDATE` of a merged table, which `merge-rules.sweep.test.ts`
+ * reads from source and holds to `MERGE_RULES`; it can only read a
+ * statement whose table and column are spelled out. So each set-once
+ * field has its statement in {@link SET_ONCE_FILLS}, and a set-once
+ * field `MERGE_RULES` gains without one there makes the settling throw.
+ *
+ * The union's collisions, rows it refused on another UNIQUE key, are
+ * not matches and are not read here.
+ */
+import type { TableUnion } from './merge-union.js';
+import type { Database } from 'bun:sqlite';
+/** The merge these conflicts are recorded under. */
+export interface ConflictTrail {
+    /** The `merges.id` of the merge. */
+    readonly mergeId: string;
+    /** When the conflicts are recorded, as an ISO timestamp. */
+    readonly recordedAt: string;
+}
+/** An edited field this store took from the other store. */
+export interface FieldFill {
+    readonly localSeq: number;
+    readonly field: string;
+}
+/** A pair recorded in `merge_conflicts`. */
+export interface RecordedConflict {
+    readonly localSeq: number;
+    /** The incoming row's `seq` in the other store. */
+    readonly incomingSeq: number;
+    /** The edited field whose two values differ, or null when the rows differ outside every edited field. */
+    readonly field: string | null;
+}
+/** What the conflict step did with one merged table's matched pairs. */
+export interface TableSettlement {
+    readonly table: string;
+    /** The local `seq` of each pair left with equal content, before or after its fills. */
+    readonly skipped: readonly number[];
+    readonly filled: readonly FieldFill[];
+    readonly conflicts: readonly RecordedConflict[];
+}
+/** The statement filling one set-once field of a row left NULL, by `<table>.<column>`. */
+export declare const SET_ONCE_FILLS: Readonly<Record<string, string>>;
+/** The comparable form of one recomputed field's value, by `<table>.<column>`. */
+export declare const RECOMPUTED_COMPARISONS: Readonly<Record<string, (value: string) => string>>;
+/**
+ * Settles every pair `unions` matched, as the module note says: fills
+ * the set-once fields `local` holds NULL in, and records each conflict
+ * in `local`'s `merge_conflicts` under `trail`, in one transaction.
+ * `other` is only read. Answers one entry per union entry, in its order.
+ */
+export declare function settleMatches(local: Database, other: Database, unions: readonly TableUnion[], trail: ConflictTrail): TableSettlement[];