@open-tomato/rafa 0.52.1 → 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.
Files changed (40) hide show
  1. package/dist/PROMPT.md +7 -0
  2. package/dist/bundled/agents/loop-implementer.md +7 -1
  3. package/dist/bundled/operators/skills/rafa-stretch-gap-log/SKILL.md +16 -0
  4. package/dist/bundled/operators/skills/rafa-stretch-pit-stop/SKILL.md +14 -8
  5. package/dist/bundled/operators/skills/rafa-stretch-sweep/SKILL.md +4 -2
  6. package/dist/cli.js +4401 -2084
  7. package/dist/config/index.js +2 -2
  8. package/dist/config/shape.d.ts +7 -5
  9. package/dist/config-registry.d.ts +5 -5
  10. package/dist/config-schema-collaborate.d.ts +85 -0
  11. package/dist/config-schema-features.d.ts +2 -2
  12. package/dist/config-schema-hints.d.ts +53 -0
  13. package/dist/config-schema-hub.d.ts +5 -4
  14. package/dist/core/command/shared-flags.d.ts +1 -1
  15. package/dist/core/config/config-schema.d.ts +1 -1
  16. package/dist/core/config/config.d.ts +1 -1
  17. package/dist/core/git/index.d.ts +12 -5
  18. package/dist/core/git/placed-line.d.ts +86 -0
  19. package/dist/effort/session-log-path.d.ts +34 -0
  20. package/dist/effort/store/answered-rows.d.ts +38 -0
  21. package/dist/effort/store/index.js +5 -3
  22. package/dist/effort/store/merge-conflicts.d.ts +8 -4
  23. package/dist/effort/store/merge-rules.d.ts +16 -5
  24. package/dist/effort/store/merge-store.d.ts +14 -3
  25. package/dist/effort/store/origins.d.ts +5 -4
  26. package/dist/effort/store/repository-facts.d.ts +147 -0
  27. package/dist/effort/store/session-row-types.d.ts +6 -1
  28. package/dist/effort/store/sqlite.d.ts +11 -6
  29. package/dist/{index-4dwaxd5r.js → index-8rr1etrx.js} +10 -3
  30. package/dist/{index-nqaqh4zz.js → index-d772zq3m.js} +44 -4
  31. package/dist/{index-m672ptpg.js → index-dj8en7fg.js} +1 -1
  32. package/dist/{index-1tdzcheq.js → index-mkhbaye7.js} +306 -43
  33. package/dist/{index-4wy2nmyt.js → index-waawdjq2.js} +140 -119
  34. package/dist/index.js +1622 -564
  35. package/dist/learning/index.js +112 -53
  36. package/dist/ports/index.d.ts +5 -5
  37. package/dist/ports/learning.d.ts +28 -2
  38. package/dist/{ready-kac4ty0p.js → ready-9e1pyxdh.js} +3 -3
  39. package/dist/utils/shell.d.ts +17 -0
  40. package/package.json +12 -5
@@ -4,9 +4,9 @@ import {
4
4
  CONFIG_TEMPLATES,
5
5
  SETTINGS,
6
6
  SETTING_NAMES
7
- } from "../index-nqaqh4zz.js";
7
+ } from "../index-d772zq3m.js";
8
8
  import"../index-jjxnyqvy.js";
9
- import"../index-m672ptpg.js";
9
+ import"../index-dj8en7fg.js";
10
10
  import"../index-fpgmdmww.js";
11
11
 
12
12
  // src/config/entry.ts
@@ -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
  *
@@ -57,7 +57,7 @@ export interface RafaConfig {
57
57
  learningBlessMinConfidence: number;
58
58
  /** The distinct sources a lesson needs to be promotable. `learning.promote.after`. */
59
59
  learningPromoteAfter: number;
60
- /** The least confidence of a promotable lesson. `learning.promote.minConfidence`. */
60
+ /** The least pooled confidence of a promotable same-action group, 0.6 by default. `learning.promote.minConfidence`. */
61
61
  learningPromoteMinConfidence: number;
62
62
  /** How commands write their output. `output.mode`. */
63
63
  outputMode: OutputMode;
@@ -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;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * The form a session row stores a log's path in.
3
+ *
4
+ * @param absolutePath - The log's absolute path, as the collector read it.
5
+ * @param home - The home directory whose projects root the path is cut against.
6
+ * @returns `<folder>/<file>` for a path under `<home>/.claude/projects/`,
7
+ * and the path unchanged for any other, a `logDir` override's included.
8
+ */
9
+ export declare function storedLogPath(absolutePath: string, home: string): string;
10
+ /**
11
+ * The stored form of a value a row already holds, whatever machine wrote it.
12
+ *
13
+ * An absolute value is cut after its last `/.claude/projects/`, so the
14
+ * home before it, on whatever machine, is dropped. The last rather than
15
+ * the first, because a folder name never holds a `/` and so never the
16
+ * marker, while a home could.
17
+ *
18
+ * @param value - A row's `filePath`, or whatever the row holds there.
19
+ * @returns The relative form for an absolute value under a projects root,
20
+ * and the value unchanged otherwise: a relative one, one outside the
21
+ * root, one whose rest is refused, and one that is not a string.
22
+ */
23
+ export declare function storedLogPathOf<T>(value: T): T | string;
24
+ /**
25
+ * The file a stored value names on this machine.
26
+ *
27
+ * @param stored - A row's stored `filePath`.
28
+ * @param home - The reading machine's home directory.
29
+ * @returns The absolute path under `<home>/.claude/projects/` for a
30
+ * relative value, the value itself for an absolute one, and `null` for a
31
+ * value refused as a relative path: empty, holding `\`, or climbing out
32
+ * of the root.
33
+ */
34
+ export declare function resolveSessionLogPath(stored: string, home: string): string | null;
@@ -0,0 +1,38 @@
1
+ /**
2
+ * The rows a backend's `read` answers, as against the rows it stores.
3
+ *
4
+ * Both backends store a row's bytes as the collector wrote them and
5
+ * never rewrite them: the store is append-only, and its bytes are what
6
+ * `keys`, the merge and the wire read. What `read` hands a caller is
7
+ * those rows passed through {@link answeredRows}, one function both
8
+ * `sqlite.ts` and `ndjson.ts` call, so the two backends' answers cannot
9
+ * drift apart.
10
+ *
11
+ * One rewrite lives here today. A session row written before the stored
12
+ * form (#1489) holds its log's absolute path in `filePath`, the writing
13
+ * machine's home directory included. Its `filePath` is answered through
14
+ * `storedLogPathOf` (`session-log-path.ts`), so an absolute value under
15
+ * a `/.claude/projects/` root, on a Linux or a macOS home alike, reads
16
+ * as the `<folder>/<file>` form a fresh collect stores. Any other value
17
+ * reads unchanged, and a row with no `filePath` at all, such as the hub
18
+ * contract's template row, is answered as it is, with no key added.
19
+ *
20
+ * A row the rewrite leaves alone is answered as the same object the
21
+ * backend parsed, and a rewritten one as a fresh copy, so no stored row
22
+ * is mutated on its way out. Commit rows hold no path and pass through.
23
+ *
24
+ * `keys` reads the key column or the key projection, never this, so
25
+ * the rewrite cannot change what a collector skips. The NDJSON
26
+ * backend's `readRows`, the raw reading `move.ts` copies a store with,
27
+ * does not pass through here either: a move carries the bytes it found.
28
+ */
29
+ import type { EffortRow, EffortRowKind } from './types.js';
30
+ /**
31
+ * The rows one kind answers from `read`, given the rows it stores.
32
+ *
33
+ * @param kind - The kind the rows were read under.
34
+ * @param rows - The rows as parsed from the store, in append order.
35
+ * @returns A fresh array in the same order, each session row's old
36
+ * absolute `filePath` answered in its stored form.
37
+ */
38
+ export declare function answeredRows<K extends EffortRowKind>(kind: K, rows: readonly EffortRow<K>[]): EffortRow<K>[];
@@ -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,12 +14,12 @@ import {
13
14
  openNdjsonStore,
14
15
  openSqliteStore,
15
16
  selectEffortStore
16
- } from "../../index-1tdzcheq.js";
17
+ } from "../../index-mkhbaye7.js";
17
18
  import {
18
19
  TRUSTED_PERMISSIONS
19
- } from "../../index-4dwaxd5r.js";
20
+ } from "../../index-8rr1etrx.js";
20
21
  import"../../index-2a7nb3an.js";
21
- import"../../index-m672ptpg.js";
22
+ import"../../index-dj8en7fg.js";
22
23
  import {
23
24
  STORE_BACKENDS
24
25
  } from "../../index-fpgmdmww.js";
@@ -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
@@ -21,10 +21,14 @@
21
21
  * `field` naming the column. Under {@link RECOMPUTED} the two values
22
22
  * are compared without the part the merge recomputes, through the
23
23
  * field's entry in {@link RECOMPUTED_COMPARISONS}: `commits.row_json`
24
- * without its `minutesSincePrevious` (`merge-commit-gaps.ts`). Equal
25
- * so, the pair is skipped and the row here kept; the gap of a commit
26
- * brought in is the merge's to rewrite, not a matched one's. Unequal,
27
- * the rows differ outside every edited field, below.
24
+ * without its `minutesSincePrevious` (`merge-commit-gaps.ts`), and
25
+ * `sessions.row_json` with its `filePath` passed through
26
+ * `storedLogPathOf` (`session-log-path.ts`), so an old row's absolute
27
+ * path and a fresh row's `<folder>/<file>` compare alike. Equal so, the
28
+ * pair is skipped and the row here kept: the gap of a commit brought in
29
+ * is the merge's to rewrite, not a matched one's, and a session's path
30
+ * is answered in its stored form by `read` whichever form the row here
31
+ * holds. Unequal, the rows differ outside every edited field, below.
28
32
  * - **Any other difference**: the incoming row is recorded with `field`
29
33
  * NULL, and the row here is left as it is, edited fields included. The
30
34
  * same `(origin_store, origin_seq)` holding different content can only
@@ -28,7 +28,9 @@
28
28
  *
29
29
  * The store is almost append-only. A column a production statement
30
30
  * changes after the insert is an edited field, and the merge has to know
31
- * which of two stores' values to keep. There are two today.
31
+ * which of two stores' values to keep, or, for a column no statement
32
+ * changes, a value two stores may hold in two forms that read alike.
33
+ * There are three today.
32
34
  * `findings.tracker_ref`, written by `writeTrackerRef`
33
35
  * (`tracker-refs.ts`) once a bug is filed, is {@link SET_ONCE}: a
34
36
  * filled value beats NULL, and two different filled values mean one
@@ -39,6 +41,13 @@
39
41
  * is rewritten by the merge itself (`merge-commit-gaps.ts`) for each
40
42
  * commit brought in and the commit after it in time, so two rows of one
41
43
  * commit that differ only in that key are the same row.
44
+ * `sessions.row_json` is {@link RECOMPUTED} too, though no statement
45
+ * rewrites it: its `filePath` is stored as `<folder>/<file>` by a fresh
46
+ * collect and as an absolute path by a row written before that form
47
+ * (#1489), and `read` answers both alike (`answered-rows.ts`). So two
48
+ * rows of one session whose `row_json` differ only in that form, with
49
+ * `filePath` passed through `storedLogPathOf` (`session-log-path.ts`),
50
+ * are the same row.
42
51
  *
43
52
  * ## What holds the registry to the schema
44
53
  *
@@ -57,9 +66,11 @@ export type MergeScope = 'merged' | 'local';
57
66
  */
58
67
  export declare const SET_ONCE = "set-once";
59
68
  /**
60
- * The merge recomputes the field from the rows it holds, so two stores'
61
- * values of it are never compared: for `commits.row_json`, its
62
- * `minutesSincePrevious` key.
69
+ * Part of the field is the merge's or the reader's to derive, so two
70
+ * stores' values of it are compared without that part: for
71
+ * `commits.row_json`, its `minutesSincePrevious` key, which the merge
72
+ * recomputes; for `sessions.row_json`, the form of its `filePath`, which
73
+ * `read` answers in the stored form either way.
63
74
  */
64
75
  export declare const RECOMPUTED = "recomputed";
65
76
  /** How a merge settles an edited field whose two stores disagree. */
@@ -69,7 +80,7 @@ export interface MergedTableRule {
69
80
  readonly scope: 'merged';
70
81
  /** The columns two rows with a NULL origin are matched by. */
71
82
  readonly identity: readonly string[];
72
- /** Every column a production statement changes after the insert, with its rule. */
83
+ /** Every column a production statement changes after the insert, or two stores may hold in two forms, with its rule. */
73
84
  readonly edited: Readonly<Record<string, EditRule>>;
74
85
  }
75
86
  /** A table that never leaves its machine. */
@@ -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
  /**