@open-tomato/rafa 0.53.0 → 0.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,7 +4,7 @@ import {
4
4
  CONFIG_TEMPLATES,
5
5
  SETTINGS,
6
6
  SETTING_NAMES
7
- } from "../index-78zcdjf5.js";
7
+ } from "../index-d772zq3m.js";
8
8
  import"../index-jjxnyqvy.js";
9
9
  import"../index-dj8en7fg.js";
10
10
  import"../index-fpgmdmww.js";
@@ -21,10 +21,10 @@
21
21
  *
22
22
  * This module declares core's own top-level keys, the keys of
23
23
  * `packages/rafa/src/core/config/core-section.ts`, and composes {@link ConfigShape}
24
- * from them and the interface each of the thirteen section files
25
- * (`src/config-schema-*.ts`) exports for the keys it writes: `HubShape`
26
- * for `hub`, `ReleaseShape` for `pr` and `release`, and so on, each
27
- * extended by {@link ConfigShape}. A namespace two packages share is a
24
+ * from them and the interface each of the sixteen section files
25
+ * (`packages/rafa/src/config-schema-*.ts`) exports for the keys it
26
+ * writes: `HubShape` for `hub`, `ReleaseShape` for `pr` and `release`,
27
+ * and so on, each extended by {@link ConfigShape}. A namespace two packages share is a
28
28
  * named interface here holding core's keys and extending the part each
29
29
  * section exports as an interface of its own: {@link LoopShape} extends
30
30
  * `LoopRetriesShape`, `LoopContinueShape` and `WrapUpShape`,
@@ -48,8 +48,10 @@
48
48
  import type { BoardProjectLimitsShape } from '@open-tomato/rafa/config-schema-board-project';
49
49
  import type { BugsShape } from '@open-tomato/rafa/config-schema-bugs';
50
50
  import type { ChecksShape } from '@open-tomato/rafa/config-schema-checks';
51
+ import type { CollaborateShape } from '@open-tomato/rafa/config-schema-collaborate';
51
52
  import type { ErrorsShape } from '@open-tomato/rafa/config-schema-errors';
52
53
  import type { FeaturesShape } from '@open-tomato/rafa/config-schema-features';
54
+ import type { HintsShape } from '@open-tomato/rafa/config-schema-hints';
53
55
  import type { HubShape } from '@open-tomato/rafa/config-schema-hub';
54
56
  import type { IssuesShape } from '@open-tomato/rafa/config-schema-issues';
55
57
  import type { LoggerShape } from '@open-tomato/rafa/config-schema-logger';
@@ -129,7 +131,7 @@ export interface DangerousShape extends ReleaseDangerousShape {
129
131
  readonly selfUpdateDuringLoop: boolean;
130
132
  }
131
133
  /** The nested file shape: core's keys, and each section's; see the module note. */
132
- export interface ConfigShape extends BugsShape, ChecksShape, ErrorsShape, FeaturesShape, HubShape, IssuesShape, LoggerShape, ReleaseShape, TestsShape, TriageShape {
134
+ export interface ConfigShape extends BugsShape, ChecksShape, CollaborateShape, ErrorsShape, FeaturesShape, HintsShape, HubShape, IssuesShape, LoggerShape, ReleaseShape, TestsShape, TriageShape {
133
135
  /** `version`: the config format's version. */
134
136
  readonly version: ConfigVersion;
135
137
  /** `store`: the effort store's backend. */
@@ -1,14 +1,14 @@
1
1
  /**
2
- * The registry: the fifteen sections of the config schema, handed to
2
+ * The registry: the seventeen sections of the config schema, handed to
3
3
  * core when {@link registerCoreConfigSections} is called, and the merged schema read off
4
4
  * them, {@link SETTINGS}, {@link CONFIG_DEFAULTS}, {@link SETTING_NAMES},
5
5
  * {@link SETTING_BY_KEY}, {@link SECTIONS} and {@link knownKeysAbove}.
6
6
  *
7
7
  * Core declares the section contract (`packages/rafa/src/core/config/section.ts`) and
8
8
  * names no section. This module, outside `packages/rafa/src/core/`, is the one place
9
- * the fifteen are listed, {@link CONFIG_SECTIONS}: core's own
10
- * (`CORE_SECTION`) and the fourteen files `config-schema-*.ts` that
11
- * each export one, under `src/` (ten) or, for four, under `packages/rafa/src/`.
9
+ * the seventeen are listed, {@link CONFIG_SECTIONS}: core's own
10
+ * (`CORE_SECTION`) and the sixteen files `config-schema-*.ts` under
11
+ * `packages/rafa/src/` that each export one.
12
12
  *
13
13
  * Importing it registers nothing. {@link registerCoreConfigSections}
14
14
  * calls `registerConfigSections` once, with that list cut into the runs
@@ -86,7 +86,7 @@
86
86
  * `src/index.ts` publishes this module's {@link CONFIG_DEFAULTS}.
87
87
  */
88
88
  import type { ConfigSection, ConfigSetting, RafaConfig, SettingSpec } from '@open-tomato/rafa/core/config';
89
- /** The fifteen sections, core's first, in the order they are registered. */
89
+ /** The seventeen sections, core's first, in the order they are registered. */
90
90
  export declare const CONFIG_SECTIONS: readonly ConfigSection[];
91
91
  /**
92
92
  * The hook `loadConfig` calls with every config it resolves: it hands
@@ -0,0 +1,85 @@
1
+ /**
2
+ * The `collaborate` section of the config schema: the one key a project
3
+ * sets to report a gap or a bug on the board of a tool it consumes,
4
+ * `collaborate.rafa`, with its field, its default, its spec and its
5
+ * reader, and {@link collaborateTarget}, which answers the board a
6
+ * `--upstream=<tool>` names. {@link COLLABORATE_SECTION} hands them to
7
+ * core as one `ConfigSection`, package `collaborate`, and the
8
+ * `declare module` below adds {@link CollaborateSettings} to
9
+ * `RafaConfig`. {@link CollaborateShape} holds the keys a file writes,
10
+ * which `src/config/shape.ts` composes into `ConfigShape`, the nested
11
+ * file shape. `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
12
+ * spread {@link COLLABORATE_DEFAULTS} and {@link COLLABORATE_SETTINGS}.
13
+ *
14
+ * The section sits in a module of its own, as `config-schema-hub.ts`
15
+ * does, and every rule `config.ts` and `section.ts` state about a KEY
16
+ * holds here, as every rule `config-sections.ts` states about a VALUE
17
+ * does: nothing is coerced.
18
+ *
19
+ * ## The key
20
+ *
21
+ * `.rafa/specs/rafa-751-report-rafa-gaps-bugs.md` names it:
22
+ * `collaborate.rafa: <owner>/<name>`, the repository whose board
23
+ * `rafa issue create`, `rafa issue comment` and `rafa issue list` reach
24
+ * under `--upstream=rafa`. Four readings this module makes:
25
+ *
26
+ * - It defaults to NULL, meaning "nobody has said", as `hub.url`
27
+ * does, and null keeps reporting upstream off: no default
28
+ * repository is one this module could spell for every team.
29
+ * - Its value is one `owner/name`, the pattern
30
+ * `packages/rafa-board/src/board/repository.ts` holds a board's
31
+ * `nameWithOwner` to: two parts, each holding no `/` and no
32
+ * whitespace. A non-string, a blank string, `rafa`,
33
+ * `open-tomato/rafa/x` and `open tomato/rafa` are each refused at
34
+ * load, the refusal naming `collaborate.rafa`. The pattern is
35
+ * spelled again here rather than imported: core does not depend on
36
+ * `rafa-board`.
37
+ * - Only `rafa` is read under `collaborate`. Any other key under it,
38
+ * `collaborate.bun` included, names no setting and is warned about
39
+ * as the loader warns about every unknown key; a later tool's key
40
+ * arrives with the code that reads it.
41
+ * - It is not a `CommandLineSetting`: where a project may report is
42
+ * the project's word, and `--upstream` names a tool, never a board.
43
+ */
44
+ import type { ConfigSection, SettingSpec } from './core/config/index.js';
45
+ import type { Reader } from './core/config/sections.js';
46
+ declare module './core/config/config-schema.js' {
47
+ /** The `collaborate` section's fields, added to core's. */
48
+ interface RafaConfig extends CollaborateSettings {
49
+ }
50
+ }
51
+ /** The `collaborate` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
52
+ export interface CollaborateShape {
53
+ readonly collaborate: {
54
+ readonly rafa: string;
55
+ };
56
+ }
57
+ /** The `collaborate` section's settings, resolved. */
58
+ export interface CollaborateSettings {
59
+ /**
60
+ * The `owner/name` of the repository a rafa gap or bug is reported
61
+ * on, or null when nobody has said and reporting upstream is off.
62
+ * `collaborate.rafa`.
63
+ */
64
+ collaborateRafa: string | null;
65
+ }
66
+ /** A tool a key under `collaborate` names, as `--upstream=<tool>` spells it. */
67
+ export type CollaborateTool = 'rafa';
68
+ /** Every tool a key under `collaborate` names, in the order the section reads them. */
69
+ export declare const COLLABORATE_TOOLS: readonly CollaborateTool[];
70
+ /** The `collaborate` section's defaults: every key absent, read as null. */
71
+ export declare const COLLABORATE_DEFAULTS: Readonly<CollaborateSettings>;
72
+ /** Accepts one `owner/name`, kept as written; see the module note. */
73
+ export declare const collaborateRepository: Reader<string>;
74
+ /** The `collaborate` section's specs, spread into `SETTINGS`. */
75
+ export declare const COLLABORATE_SETTINGS: {
76
+ readonly [K in keyof CollaborateSettings]: SettingSpec<K>;
77
+ };
78
+ /** The `collaborate` section: its one setting and its default, with no check. */
79
+ export declare const COLLABORATE_SECTION: ConfigSection;
80
+ /**
81
+ * The `owner/name` the resolved config names for `tool`, or null when
82
+ * its key is absent, so reporting upstream to it is off. A setting left
83
+ * out of `config` reads as its default, null.
84
+ */
85
+ export declare function collaborateTarget(config: Partial<CollaborateSettings>, tool: CollaborateTool): string | null;
@@ -6,9 +6,9 @@
6
6
  * below adds {@link FeaturesSettings} to `RafaConfig`.
7
7
  * {@link FeaturesShape} holds the keys a file writes, which
8
8
  * `src/config/shape.ts` composes into `ConfigShape`, the nested file
9
- * shape. `config-registry.ts` registers the section fourteenth in
9
+ * shape. `config-registry.ts` registers the section fifteenth in
10
10
  * `CONFIG_SECTIONS`, and its `CONFIG_DEFAULTS` and `SETTINGS` spread the
11
- * objects below last, after the `checks` section.
11
+ * objects below after the `checks` section and ahead of the `hints` one.
12
12
  *
13
13
  * ## The keys
14
14
  *
@@ -0,0 +1,53 @@
1
+ /**
2
+ * The `hints` section of the config schema: one switch, `hints.skills`,
3
+ * saying whether a step rafa hands over is followed by the skill case
4
+ * that explains it. {@link HINTS_SECTION} hands it to core as one
5
+ * `ConfigSection`, package `hints`, and the `declare module` below adds
6
+ * {@link HintsSettings} to `RafaConfig`. {@link HintsShape} holds the key
7
+ * a file writes, which `src/config/shape.ts` composes into
8
+ * `ConfigShape`, the nested file shape. `config-registry.ts` registers
9
+ * the section sixteenth and last in `CONFIG_SECTIONS`, and its
10
+ * `CONFIG_DEFAULTS` and `SETTINGS` spread the objects below last, after
11
+ * the `features` section.
12
+ *
13
+ * ## The key
14
+ *
15
+ * `hints.skills` is read with core's `flag`, so it takes `true` or
16
+ * `false` and refuses anything else, a quoted `"true"` included, naming
17
+ * the key. It defaults to `false`: a step reads as it did before the key
18
+ * existed, and a project opts in. When it is `true`, a `Next:` step of
19
+ * `rafa release tag`, `rafa release settle` or `rafa release publish`
20
+ * whose case has a file under `.claude/skills/rafa-release/` is followed
21
+ * by one indented line, `skill: rafa-release › <case>`. It is not a
22
+ * `CommandLineSetting`, as no boolean `release` key is.
23
+ *
24
+ * The section holds the switch and nothing that reads it: the release
25
+ * steps read the setting off the resolved `RafaConfig`.
26
+ */
27
+ import type { ConfigSection, SettingSpec } from './core/config/index.js';
28
+ declare module './core/config/config-schema.js' {
29
+ /** The `hints` section's fields, added to core's. */
30
+ interface RafaConfig extends HintsSettings {
31
+ }
32
+ }
33
+ /** The `hints` keys as a file writes them. */
34
+ export interface HintsShape {
35
+ /** The `hints` keys. */
36
+ readonly hints: {
37
+ /** `hints.skills`: whether a handed-over step names the skill case that explains it. */
38
+ readonly skills: boolean;
39
+ };
40
+ }
41
+ /** The `hints` section's settings, resolved. */
42
+ export interface HintsSettings {
43
+ /** Whether a handed-over step is followed by its skill case line. `hints.skills`. */
44
+ hintsSkills: boolean;
45
+ }
46
+ /** What the `hints` settings resolve to when no layer names them: no skill line. */
47
+ export declare const HINTS_DEFAULTS: Readonly<HintsSettings>;
48
+ /** The `hints` section's setting specs, in the order they are reported. */
49
+ export declare const HINTS_SETTINGS: {
50
+ readonly [K in keyof HintsSettings]: SettingSpec<K>;
51
+ };
52
+ /** The `hints` section: the one switch, with its default and no check. */
53
+ export declare const HINTS_SECTION: ConfigSection;
@@ -28,10 +28,11 @@
28
28
  * `effort.sync: service`), `hub.tokenSecret` (the secret store name of
29
29
  * the token, never the token) and `hub.timeout` (default `3s`, from `1s`
30
30
  * to `30s`, `0` and negative values refused). The server's keys,
31
- * `hub.repository`, `hub.port`, `hub.storePath` and `hub.auth.cacheFor`,
32
- * are read by `packages/rafa-hub/` from its own file and are not keys
33
- * here: in a project's file they are unknown keys, warned about and
34
- * acted on by nothing. Five readings the spec leaves to this module:
31
+ * `hub.repository`, `hub.port`, `hub.storePath`, `hub.auth.cacheFor`,
32
+ * `hub.store.sqliteLibrary` and `hub.index.rebuildAfterPush`, are read by
33
+ * `packages/rafa-hub/` from its own file and are not keys here: in a
34
+ * project's file they are unknown keys, warned about and acted on by
35
+ * nothing. Five readings the spec leaves to this module:
35
36
  *
36
37
  * - `hub.url` and `hub.tokenSecret` default to NULL, meaning "nobody
37
38
  * has said", as `pr.base` does: no default address or secret name
@@ -7,7 +7,7 @@
7
7
  * `loop start`. They belong to four features, and three of them are
8
8
  * declared in a declarations file (`packages/rafa-pr/src/commands/pr/declarations.ts`,
9
9
  * `packages/rafa-board/src/commands/issue/declarations.ts`), which imports core's entries
10
- * alone and no module under `src/`. So the flag lives here, where every
10
+ * and, for issue, its two sibling files, and no module under `src/`. So the flag lives here, where every
11
11
  * one of the six can reach it, and each declares this value itself
12
12
  * rather than a copy its tests would have to hold equal.
13
13
  *
@@ -100,7 +100,7 @@
100
100
  * `section.ts` (`activeSettings()`) and take each default from
101
101
  * `activeDefaults()`, so a layer and a resolution hold every registered
102
102
  * setting, in registration order. `src/config-registry.ts`, outside
103
- * `packages/rafa/src/core/`, registers the fourteen sections when its
103
+ * `packages/rafa/src/core/`, registers the seventeen sections when its
104
104
  * `registerCoreConfigSections` is called; a process that has not called
105
105
  * it reads no setting at all, where the
106
106
  * literal this loop replaced held every setting whatever was registered.
@@ -1,6 +1,6 @@
1
1
  /**
2
- * The barrel over git: every name `git.ts`, `commit.ts` and
3
- * `gh-runner.ts` export but one, and nothing else.
2
+ * The barrel over git: every name `git.ts`, `commit.ts`,
3
+ * `gh-runner.ts` and `placed-line.ts` export but one, and nothing else.
4
4
  *
5
5
  * A file outside `packages/rafa/src/core/` imports this file and never the two behind
6
6
  * it (`scripts/survey/core-barrels.ts` measures that, and
@@ -19,7 +19,12 @@
19
19
  * each step;
20
20
  * - `gh-runner.ts`: the type of the runner every `gh` command goes
21
21
  * through and what one command answers, types alone, imported by
22
- * nothing.
22
+ * nothing;
23
+ * - `placed-line.ts`: a printed step placed where it must run, the
24
+ * command alone in its own checkout and `cd <checkout> && <command>`
25
+ * elsewhere, with the top-level read it is placed by. It imports
26
+ * `git.ts` for a type and `packages/rafa/src/utils/shell.ts`, which
27
+ * imports nothing, for `shellQuote`.
23
28
  *
24
29
  * ## The one name the two files share
25
30
  *
@@ -79,12 +84,14 @@
79
84
  * barrels spell theirs. No name here is part of the published surface:
80
85
  * `src/index.ts` re-exports nothing from this file.
81
86
  *
82
- * `index.test.ts` holds the list to the two files: every name either
83
- * exports is here once, as the same binding, `GitRunner` as the type
87
+ * `index.test.ts` holds the list to the files behind it: every name one
88
+ * of them exports is here once, as the same binding, `GitRunner` as the type
84
89
  * `git.ts` declares, and no other name is here.
85
90
  */
86
91
  export type { GhResult, GhRunner } from './gh-runner.js';
87
92
  export type { GitResult, GitRunner, WorkingTreeStatus } from './git.js';
93
+ export type { PlaceAnswer, PlacedLine, PlaceSeams, UnplacedLine } from './placed-line.js';
88
94
  export type { CommitAttempt, CommitMessage, CommitOptions, CommitOutcome, CommitStep, CommitType, CommitTypeRule, DerivedSubject, GitRunResult, SubjectOptions, } from './commit.js';
89
95
  export { createGitRunner, gitSaid, parseWorkingTree, unquoteGitPath } from './git.js';
96
+ export { placeLine, readTopLevel } from './placed-line.js';
90
97
  export { buildCommitMessage, COMMIT_TYPE_RULES, commitArgs, commitTaskWork, DEFAULT_COMMIT_TYPE, deriveCommitSubject, FALLBACK_DESCRIPTION, firstClause, headShaArgs, inferCommitType, MAX_MESSAGE_CHARS, MAX_SUBJECT_LENGTH, normaliseTaskText, spawnGit, stageAllArgs, stagedChangesArgs, } from './commit.js';
@@ -0,0 +1,86 @@
1
+ /**
2
+ * A printed step placed where it must run: the command alone when the
3
+ * reader already stands in the checkout it needs, and
4
+ * `cd <checkout> && <command>` when they do not.
5
+ *
6
+ * A step a command prints after its own run is a line the reader
7
+ * copies or clicks, and it runs in the directory the command ran in.
8
+ * When that directory's git top level is the checkout the step needs,
9
+ * a `cd` in front would be noise; when it is another one, the step
10
+ * without it runs in the wrong checkout. So the line carries the `cd`
11
+ * exactly when the two differ.
12
+ *
13
+ * The helper knows nothing of the subject whose steps it places. The
14
+ * caller names the command, the checkout it must run in, and two seams:
15
+ * the top-level read of the directory the command ran in
16
+ * ({@link readTopLevel} over a {@link GitRunner} is the reading a
17
+ * caller passes in production) and the check that a path is there.
18
+ *
19
+ * ## The three readings that are not "the same place"
20
+ *
21
+ * - A different top level: the prefix.
22
+ * - A top-level read git did not answer (not a repository, git not
23
+ * spawned): the prefix too. The line then runs wherever it is
24
+ * clicked, which is the point of the prefix, and leaving it out
25
+ * would bet the step on a place nobody read.
26
+ * - A checkout path that is not there, as `git worktree list` still
27
+ * lists a worktree whose folder was removed: no line at all. The
28
+ * answer is `unplaced`, and the caller prints its own fallback, such
29
+ * as a `git switch` to the branch, since a `cd` into a missing
30
+ * folder fails before the command runs.
31
+ *
32
+ * The missing path is checked first, so a missing checkout answers
33
+ * `unplaced` whatever the top level reads.
34
+ *
35
+ * ## How two paths are compared
36
+ *
37
+ * Both are compared after `path.resolve`, which drops a trailing slash
38
+ * and `.` segments, and nothing more: no symlink is followed. Git
39
+ * prints both the top level (`git rev-parse --show-toplevel`) and the
40
+ * worktree paths (`git worktree list --porcelain`) with symlinks
41
+ * resolved, so two readings of git agree without it. A checkout that is
42
+ * not plain shell text is quoted with {@link shellQuote}.
43
+ */
44
+ import type { GitRunner } from './git.js';
45
+ /** The seams {@link placeLine} reads the two places through. */
46
+ export interface PlaceSeams {
47
+ /**
48
+ * The git top level of the directory the command ran in, or null when
49
+ * git did not answer.
50
+ */
51
+ readonly readTopLevel: () => string | null;
52
+ /** True when `path` is there on disk. */
53
+ readonly pathExists: (path: string) => boolean;
54
+ }
55
+ /** The line a step prints, placed where it must run. */
56
+ export interface PlacedLine {
57
+ readonly kind: 'placed';
58
+ /** The command alone, or `cd <checkout> && <command>`. */
59
+ readonly line: string;
60
+ }
61
+ /** No line: the checkout is not there, so the caller prints its own fallback. */
62
+ export interface UnplacedLine {
63
+ readonly kind: 'unplaced';
64
+ /** The checkout path that was not there. */
65
+ readonly checkout: string;
66
+ }
67
+ /** What {@link placeLine} answers. */
68
+ export type PlaceAnswer = PlacedLine | UnplacedLine;
69
+ /**
70
+ * `command` placed to run in `checkout`; see the module note.
71
+ *
72
+ * @param command - The command as the reader would type it in the checkout.
73
+ * @param checkout - The checkout the command must run in.
74
+ * @param seams - The top-level read and the path check.
75
+ * @returns The placed line, or `unplaced` when `checkout` is not there.
76
+ */
77
+ export declare function placeLine(command: string, checkout: string, seams: PlaceSeams): PlaceAnswer;
78
+ /**
79
+ * The git top level of the directory `git` was made for, read with
80
+ * `git rev-parse --show-toplevel`, or null when git did not answer or
81
+ * printed nothing.
82
+ *
83
+ * @param git - The runner of the directory the command ran in.
84
+ * @returns The top level's absolute path, or null.
85
+ */
86
+ export declare function readTopLevel(git: GitRunner): string | null;
@@ -1,6 +1,7 @@
1
1
  // @bun
2
2
  import {
3
3
  EFFORT_KEY_PROJECTIONS,
4
+ WIRE_CONTRACT_VERSION,
4
5
  WIRE_FORMAT,
5
6
  WIRE_VERSION,
6
7
  WireExportRefusal,
@@ -13,10 +14,10 @@ import {
13
14
  openNdjsonStore,
14
15
  openSqliteStore,
15
16
  selectEffortStore
16
- } from "../../index-anvmm83x.js";
17
+ } from "../../index-mkhbaye7.js";
17
18
  import {
18
19
  TRUSTED_PERMISSIONS
19
- } from "../../index-rkrsdes6.js";
20
+ } from "../../index-8rr1etrx.js";
20
21
  import"../../index-2a7nb3an.js";
21
22
  import"../../index-dj8en7fg.js";
22
23
  import {
@@ -35,6 +36,7 @@ export {
35
36
  WireExportRefusal,
36
37
  WIRE_VERSION,
37
38
  WIRE_FORMAT,
39
+ WIRE_CONTRACT_VERSION,
38
40
  TRUSTED_PERMISSIONS,
39
41
  STORE_BACKENDS,
40
42
  EFFORT_KEY_PROJECTIONS
@@ -66,9 +66,20 @@
66
66
  * `merge-conflicts.ts`) settles each matched pair and records in
67
67
  * `merge_conflicts` what no rule settles, the commit gaps of each commit
68
68
  * brought in and of the commit after it are recomputed
69
- * (`recomputeCommitGaps`, `merge-commit-gaps.ts`), and one `merges` row
70
- * records the merge: its id, the other store's id, when, and the rows
71
- * added, skipped and in conflict over every merged table.
69
+ * (`recomputeCommitGaps`, `merge-commit-gaps.ts`), the supersedes the
70
+ * readings brought in call for are written (`writeSupersedes`,
71
+ * `repository-facts.ts`), and one `merges` row records the merge: its
72
+ * id, the other store's id, when, and the rows added, skipped and in
73
+ * conflict over every merged table.
74
+ *
75
+ * The supersedes are the last step before that row, for the facts of
76
+ * the rows the union added to each table of `REPOSITORY_FACTS`, today
77
+ * `plan_ci`, and never for a fact no added reading reaches. A
78
+ * supersede the other store brought is one the union added already, so
79
+ * the writer absorbs it or finds its reading superseded and writes
80
+ * nothing twice. The rows it writes count as rows added to
81
+ * `reading_supersedes`, in that table's `added` and in `rowsAdded`, so
82
+ * the `merges` row and the count check below both hold them.
72
83
  *
73
84
  * The live store is then attached, and every table both files hold,
74
85
  * the log apart, must hold its live row count plus the rows the merge
@@ -64,9 +64,10 @@
64
64
  * The tables a merge unions, each carrying `origin_store` and
65
65
  * `origin_seq`: since migration `row-origins` for the twelve tables
66
66
  * older than it, and from the migration that creates it for
67
- * `stale_docs` and `bug_routes`. A production insert that writes a new
68
- * row into one of them is stamped. Three inserts carry rows that exist
69
- * already and leave the pair as the row holds it:
67
+ * `stale_docs`, `bug_routes` and `reading_supersedes`. A production
68
+ * insert that writes a new row into one of them is stamped. Three
69
+ * inserts carry rows that exist already and leave the pair as the row
70
+ * holds it:
70
71
  * the copy in `fix-schema.ts`, column for column from the live store;
71
72
  * the union in `merge-union.ts`, which gives another store's row a new
72
73
  * local `seq` and keeps its origin; and the restore in
@@ -76,7 +77,7 @@
76
77
  * and `merge_conflicts` are the store's own bookkeeping and carry no
77
78
  * origin.
78
79
  */
79
- export declare const ORIGIN_TABLES: readonly ["sessions", "commits", "findings", "blockers", "out_of_scope_bugs", "report_absences", "task_reports", "preflight", "dispatches", "changes", "skill_invocations", "plan_ci", "stale_docs", "bug_routes"];
80
+ export declare const ORIGIN_TABLES: readonly ["sessions", "commits", "findings", "blockers", "out_of_scope_bugs", "report_absences", "task_reports", "preflight", "dispatches", "changes", "skill_invocations", "plan_ci", "stale_docs", "bug_routes", "reading_supersedes"];
80
81
  /** One of the {@link ORIGIN_TABLES}. */
81
82
  export type OriginTable = typeof ORIGIN_TABLES[number];
82
83
  /**
@@ -0,0 +1,147 @@
1
+ /**
2
+ * Repository facts: the readings of a shared source that two stores can
3
+ * both hold, and the supersedes that make two readings of one fact
4
+ * count once.
5
+ *
6
+ * A port and the hub can each read the same pull request's checks on
7
+ * the same head, so a merge of their stores holds two `plan_ci` rows that
8
+ * say one thing. Neither row is wrong and neither is dropped: the second
9
+ * is superseded by a row of `reading_supersedes`, never by a flag on the
10
+ * reading, and every reader that counts facts reads through those rows.
11
+ *
12
+ * ## The registry
13
+ *
14
+ * {@link REPOSITORY_FACTS} lists every table whose rows are readings of
15
+ * a shared source, beside `MERGE_RULES` (`merge-rules.ts`). An entry
16
+ * declares only its fact columns, the columns whose values are what the
17
+ * reading says, and its time column, when the reading was taken. Its
18
+ * identity, the columns that name one reading, is the table's
19
+ * `MERGE_RULES` identity and is never spelled twice.
20
+ *
21
+ * | Table | Facts | Time |
22
+ * | --- | --- | --- |
23
+ * | `plan_ci` | `pr`, `head_sha`, `verdict`, `failing` | `read_at` |
24
+ *
25
+ * ## The rule
26
+ *
27
+ * {@link SAME_FACT_RULE}, `same-fact@1`: two readings of one table are
28
+ * one fact when their fact columns are equal, two NULLs counting as
29
+ * equal; the canonical reading is the one with the earliest reading
30
+ * time. Two readings at one time are ordered by their key, so every
31
+ * store picks the same canonical one. For `plan_ci` the time is part of
32
+ * the identity, so two readings with one `pr`, `head_sha` and `read_at`
33
+ * are one row already and never meet that tie.
34
+ *
35
+ * ## A reading's key
36
+ *
37
+ * {@link readingKey} names a reading by its table's identity, as the
38
+ * JSON array of the identity values in `MERGE_RULES` order:
39
+ * `[7,"3f2a…","2026-11-08T10:00:00.000Z"]` for a `plan_ci` row. Never by
40
+ * the origin pair, which a reading an older runtime wrote does not hold.
41
+ * An identity value is text, a finite number or NULL; any other value is
42
+ * refused, since JSON would not spell it back.
43
+ *
44
+ * ## Writing supersedes
45
+ *
46
+ * {@link writeSupersedes} is handed the keys of the readings a write or
47
+ * a merge touched. For each fact they reach it reads every reading of
48
+ * that fact, takes the canonical one, and gives every other reading that
49
+ * is not yet the `superseded_key` of a row of that table and rule one
50
+ * row naming the canonical reading. So a late reading older than the
51
+ * canonical one adds a row superseding the old canonical reading, and
52
+ * the rows the old one already canonicalised are left to the reader's
53
+ * chain. Each insert is stamped (`stampedValues`, `origins.ts`) and
54
+ * absorbed on the table's identity (`reading_supersedes_by_fact`), so a
55
+ * port and the hub that write one supersede write one row.
56
+ *
57
+ * The writer opens no transaction of its own: a merge calls it as its
58
+ * last step inside the transaction of the union, and a reading's writer
59
+ * inside its own, so the readings and their supersedes land together.
60
+ * It never rescans a table it was not handed keys of.
61
+ *
62
+ * ## Reading facts
63
+ *
64
+ * {@link readRepositoryFacts} answers one {@link RepositoryFact} per
65
+ * fact of a table: its canonical reading, `sightings` (how many readings
66
+ * it superseded, so two readings of one fact answer one sighting), the
67
+ * origins that read it, and `lastSighting`, the latest reading time over
68
+ * all its readings, the canonical one included. Each reading follows its
69
+ * supersede rows to the reading no row of the rule supersedes, the
70
+ * earliest one first where a reading has two; a row naming a reading the
71
+ * store does not hold is not followed, and a chain that comes back to a
72
+ * reading it passed, which the writer never writes, ends at the earliest
73
+ * reading of that loop. The reader trusts the rows: what they join is
74
+ * one fact, as the writer that wrote them read it.
75
+ *
76
+ * A reading no supersede names stands as a fact of its own, as a
77
+ * reading written before the writer ran does. Nothing here matches
78
+ * readings at read time.
79
+ */
80
+ import type { Database, SQLQueryBindings } from 'bun:sqlite';
81
+ /** One {@link REPOSITORY_FACTS} entry: what a reading says, and when it was read. */
82
+ export interface RepositoryFactColumns {
83
+ /** The columns whose values are the fact; equal in all of them, two readings are one fact. */
84
+ readonly facts: readonly string[];
85
+ /** The column holding when the reading was taken, as ISO 8601 text. */
86
+ readonly time: string;
87
+ }
88
+ /** Every table whose rows are readings of a shared source, by name. */
89
+ export declare const REPOSITORY_FACTS: Readonly<Record<string, RepositoryFactColumns>>;
90
+ /** The rule every supersede here is written under, as `reading_supersedes.rule` holds it. */
91
+ export declare const SAME_FACT_RULE = "same-fact@1";
92
+ /** One reading of a repository fact, as the reader answers it. */
93
+ export interface FactReading {
94
+ /** The reading's key, see {@link readingKey}. */
95
+ readonly key: string;
96
+ /** The fact columns' values, by column name. */
97
+ readonly fact: Readonly<Record<string, SQLQueryBindings>>;
98
+ /** When it was read. */
99
+ readonly time: string;
100
+ /** The store that wrote it, or null for a row with no origin pair. */
101
+ readonly origin: string | null;
102
+ }
103
+ /** One fact of a table, every reading of it counted once. */
104
+ export interface RepositoryFact {
105
+ /** The reading table. */
106
+ readonly table: string;
107
+ /** The earliest reading, the one its supersede chains end at. */
108
+ readonly canonical: FactReading;
109
+ /** How many readings the canonical one supersedes. */
110
+ readonly sightings: number;
111
+ /** The distinct origin stores of its readings, sorted; a reading with no origin adds none. */
112
+ readonly origins: readonly string[];
113
+ /** The latest reading time over all its readings, the canonical one included. */
114
+ readonly lastSighting: string;
115
+ }
116
+ /** A row as the readings query answers it. */
117
+ type StoredRow = Readonly<Record<string, SQLQueryBindings>>;
118
+ /**
119
+ * The key of one reading of `table`: the JSON array of its identity
120
+ * values in `MERGE_RULES` order. Throws for a table with no
121
+ * {@link REPOSITORY_FACTS} entry and for an identity value that is not
122
+ * text, a finite number or NULL. See the module note.
123
+ */
124
+ export declare function readingKey(table: string, row: StoredRow): string;
125
+ /**
126
+ * Writes the supersedes the readings of `table` named by `touchedKeys`
127
+ * call for, and answers how many rows it added: for each fact they
128
+ * reach, one row per reading of it that is not its canonical one and
129
+ * not yet superseded under {@link SAME_FACT_RULE}. A key named twice, or
130
+ * two keys of one fact, write that fact's rows once.
131
+ *
132
+ * Throws for a table with no {@link REPOSITORY_FACTS} entry, a key that
133
+ * is not a JSON array of the table's identity values, and a key naming
134
+ * no reading the store holds: each is a caller's fault, and the caller's
135
+ * transaction takes back what was written. See the module note.
136
+ */
137
+ export declare function writeSupersedes(db: Database, table: string, touchedKeys: readonly string[]): number;
138
+ /**
139
+ * Every fact of `table`, each reading counted once: one
140
+ * {@link RepositoryFact} per reading the supersede chains end at, in the
141
+ * order of their canonical readings' time, then key.
142
+ *
143
+ * Throws for a table with no {@link REPOSITORY_FACTS} entry. See the
144
+ * module note for how a chain is followed.
145
+ */
146
+ export declare function readRepositoryFacts(db: Database, table: string): RepositoryFact[];
147
+ export {};
@@ -52,7 +52,7 @@
52
52
  * implicit one. That is a declaration, not a repair: measured on SQLite
53
53
  * 3.51.0, a `VACUUM` left implicit rowids where they were as well.
54
54
  *
55
- * The file holds seventeen tables that are not kinds. Six are filled from
55
+ * The file holds eighteen tables that are not kinds. Six are filled from
56
56
  * task reports: `findings`, `blockers`, `out_of_scope_bugs` and
57
57
  * `changes`, one per list a report carries, `report_absences`, one row
58
58
  * per task session whose output held no report to read, and
@@ -65,10 +65,12 @@
65
65
  * six are, one row per documentation line a report named as stale;
66
66
  * `stale-docs.ts` writes it and holds its row type. A twelfth,
67
67
  * `bug_routes`, holds one row per `out_of_scope_bugs` entry the triage
68
- * step routed; `bug-routes.ts` writes it and holds its row type. The
69
- * thirteenth is `schema_migrations`, the migration log, which only
70
- * `bring-forward.ts` writes; the section on bringing a store forward
71
- * says what it holds. The last four are the store's own identity and
68
+ * step routed; `bug-routes.ts` writes it and holds its row type. A
69
+ * thirteenth, `reading_supersedes`, holds one row per reading of a
70
+ * shared source that another reading of the same fact supersedes;
71
+ * `repository-facts.ts` writes and reads it. The fourteenth is `schema_migrations`, the
72
+ * migration log, which only `bring-forward.ts` writes; the section on
73
+ * bringing a store forward says what it holds. The last four are the store's own identity and
72
74
  * merge trail: `store_meta`, `store_replaced`, `merges` and
73
75
  * `merge_conflicts`. The port's row map names none of them, and
74
76
  * nothing in this module reads or writes them. `findings.ts` writes the