bareloop 0.47.1 → 0.48.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.
@@ -24,16 +24,17 @@ export function writeLedger(ledger: import("./learn.js").Ledger, home?: string):
24
24
  /**
25
25
  * Fold ONE finished run into the ledger on disk: every run's cards COUNT now, rubric jobs too (trust kept on new rows;
26
26
  * v1.112). `held` is always 0 (kept in the shape for callers). The run's health line is recorded. Never throws on a bad ledger file: it reports `problem` and writes nothing.
27
- * @param {{home?: string, runid: string, build: import('./learn.js').CardBuild, workflow: string, place: string|null, specHash: string|null, trust: 'deterministic'|'rubric', at: string, now?: Date}} o
27
+ * @param {{home?: string, runid: string, build: import('./learn.js').CardBuild, workflow: string, place: string|null, specHash: string|null, workflowKey?: string|null, trust: 'deterministic'|'rubric', at: string, now?: Date}} o
28
28
  * @returns {{wrote: boolean, counted: number, held: number, problem: string|null}}
29
29
  */
30
- export function foldRunIntoLedger({ home, runid, build, workflow, place, specHash, trust, at, now }: {
30
+ export function foldRunIntoLedger({ home, runid, build, workflow, place, specHash, workflowKey, trust, at, now }: {
31
31
  home?: string;
32
32
  runid: string;
33
33
  build: import("./learn.js").CardBuild;
34
34
  workflow: string;
35
35
  place: string | null;
36
36
  specHash: string | null;
37
+ workflowKey?: string | null;
37
38
  trust: "deterministic" | "rubric";
38
39
  at: string;
39
40
  now?: Date;
@@ -57,8 +58,8 @@ export function releaseRun({ home, runid, now }: {
57
58
  problem: string | null;
58
59
  };
59
60
  /**
60
- * The ONE setting: `learningHints` in config.json. Ships OFF (absent = off). OFF still writes the tally ($0) and the planner
61
- * is simply handed nothing, so an ON/OFF contrast has data at once. An unreadable config reads as OFF.
61
+ * The ONE setting: `learningHints` in config.json. Ships ON (hamr 2026-10-24): absent = on; only an explicit `false` turns it off. OFF still writes
62
+ * the tally ($0) and the planner is simply handed nothing. An unreadable config reads as OFF (the safe side).
62
63
  * @param {string} [home]
63
64
  * @returns {boolean}
64
65
  */
@@ -68,16 +69,17 @@ export function learningHintsOn(home?: string): boolean;
68
69
  * ledger (a rubric job's count too, trust kept). Called once from the one engine's run-end block (src/userrun.js
69
70
  * `execute`, shared by the panel, the CLI and the bundle runner), inside its own try/catch: it is a record, never a verdict,
70
71
  * and can never change a run's outcome, exit code or spend. It runs whether the hints setting is on or off.
71
- * @param {{home?: string, runid: string, events: any[], auditFiles?: string[], spec: any, specHash: string|null, workdir: string|null, trust: 'deterministic'|'rubric', now?: Date}} o
72
+ * @param {{home?: string, runid: string, events: any[], auditFiles?: string[], spec: any, specHash: string|null, workflowKey?: string|null, workdir: string|null, trust: 'deterministic'|'rubric', now?: Date}} o
72
73
  * @returns {{wrote: boolean, counted: number, held: number, problem: string|null, noise: string|null, cards: number}}
73
74
  */
74
- export function learnAtRunEnd({ home, runid, events, auditFiles, spec, specHash, workdir, trust, now }: {
75
+ export function learnAtRunEnd({ home, runid, events, auditFiles, spec, specHash, workflowKey, workdir, trust, now }: {
75
76
  home?: string;
76
77
  runid: string;
77
78
  events: any[];
78
79
  auditFiles?: string[];
79
80
  spec: any;
80
81
  specHash: string | null;
82
+ workflowKey?: string | null;
81
83
  workdir: string | null;
82
84
  trust: "deterministic" | "rubric";
83
85
  now?: Date;
@@ -91,16 +93,35 @@ export function learnAtRunEnd({ home, runid, events, auditFiles, spec, specHash,
91
93
  };
92
94
  /**
93
95
  * The block the planner is handed for this job, made ONCE at run start from the ledger as it stood — empty when the
94
- * setting is off, when there is no ledger, or when nothing is readable. The one `renderHints` render, never a second.
95
- * @param {{home?: string, spec: any, specHash: string|null, now?: Date}} o
96
+ * setting is off, when there is no ledger, or when no lesson fits; an unreadable ledger THROWS (use {@link handedHints}, which
97
+ * hands nothing and keeps the reason). The one `renderHints` render, never a second.
98
+ * @param {{home?: string, spec: any, workflowKey?: string|null, now?: Date}} o
96
99
  * @returns {{text: string, ids: string[]}|null}
97
100
  */
98
- export function hintsForRun({ home, spec, specHash, now }: {
101
+ export function hintsForRun({ home, spec, workflowKey, now }: {
99
102
  home?: string;
100
103
  spec: any;
101
- specHash: string | null;
104
+ workflowKey?: string | null;
102
105
  now?: Date;
103
106
  }): {
104
107
  text: string;
105
108
  ids: string[];
106
109
  } | null;
110
+ /**
111
+ * {@link hintsForRun} for the engine: never throws. A broken ledger hands the planner nothing and the reason comes back
112
+ * (first line, secrets masked) so the run records it beside the hints; the run itself goes on.
113
+ * @param {{home?: string, spec: any, workflowKey?: string|null, now?: Date}} o
114
+ * @returns {{hints: {text: string, ids: string[]}|null, error: string|null}}
115
+ */
116
+ export function handedHints(o: {
117
+ home?: string;
118
+ spec: any;
119
+ workflowKey?: string | null;
120
+ now?: Date;
121
+ }): {
122
+ hints: {
123
+ text: string;
124
+ ids: string[];
125
+ } | null;
126
+ error: string | null;
127
+ };
@@ -124,9 +124,10 @@ export function legDividersFor(spineRecords: any[], parts: any[]): {
124
124
  * @param {{outcome: string|null, stopReason: string|null, spentUsd: number|null, budgetUsd: number|null, lastEscalation?: any}} summary
125
125
  * @param {{died: boolean, lastThing: string|null}} death
126
126
  * @param {{resume?: {ok: boolean, why?: string}|null, destinationRefused?: string|null, moneyHalt?: boolean,
127
- * worktree?: {folder: string, repo: string, branch: string|null, exists: boolean}|null}} [o]
127
+ * worktree?: {folder: string, repo: string, branch: string|null, exists: boolean}|null, exportName?: string|null}} [o]
128
128
  * `worktree` (P6 item 1): the run's worktree in the person's repo, from {@link worktreeOfRun}; absent for every other run
129
- * @returns {{reason: string, next: string, line: string, actions: {id: string, label: string}[]}|null}
129
+ * `exportName` (PRD v1.114): the run's `job (run-N)` name; a green worktree run (a repo job) shows the export command to copy beside the merge text
130
+ * @returns {{reason: string, next: string, rows?: [string, string][], line: string, actions: {id: string, label: string}[]}|null}
130
131
  */
131
132
  export function endedFor(summary: {
132
133
  outcome: string | null;
@@ -150,9 +151,11 @@ export function endedFor(summary: {
150
151
  branch: string | null;
151
152
  exists: boolean;
152
153
  } | null;
154
+ exportName?: string | null;
153
155
  }): {
154
156
  reason: string;
155
157
  next: string;
158
+ rows?: [string, string][];
156
159
  line: string;
157
160
  actions: {
158
161
  id: string;
@@ -782,12 +785,13 @@ export function getStartFromImport(id: string, opts?: {
782
785
  * only `createPanelServer` below always supplies one.
783
786
  * @param {import('node:http').IncomingMessage} req
784
787
  * @param {import('node:http').ServerResponse} res
785
- * @param {{ home?: string, sessionsRoot?: string, version?: string, packageJsonPath?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, settingsRoutes?: ReturnType<typeof createSettingsRoutes>, runRoutes?: ReturnType<typeof createRunRoutes>, importRoutes?: ReturnType<typeof createImportRoutes>, schedules?: ReturnType<typeof createScheduleDoor> }} opts
788
+ * @param {{ home?: string, sessionsRoot?: string, version?: string, startedAt?: string, packageJsonPath?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, settingsRoutes?: ReturnType<typeof createSettingsRoutes>, runRoutes?: ReturnType<typeof createRunRoutes>, importRoutes?: ReturnType<typeof createImportRoutes>, schedules?: ReturnType<typeof createScheduleDoor> }} opts
786
789
  */
787
790
  export function handleRequest(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, opts: {
788
791
  home?: string;
789
792
  sessionsRoot?: string;
790
793
  version?: string;
794
+ startedAt?: string;
791
795
  packageJsonPath?: string;
792
796
  port: number;
793
797
  token?: string;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * One readline over `stdin`, with a LINE QUEUE: lines that arrive before the next question (piped input, a paste) wait for it instead
3
+ * of being dropped, and a closed stdin answers '' (the safe default) and never hangs.
4
+ * @param {{ stdin?: any, stdout?: any }} [io]
5
+ * @returns {{ ask: (q: string) => Promise<string>, close: () => void }}
6
+ */
7
+ export function openAsker(io?: {
8
+ stdin?: any;
9
+ stdout?: any;
10
+ }): {
11
+ ask: (q: string) => Promise<string>;
12
+ close: () => void;
13
+ };
14
+ /**
15
+ * A required prompt (hamr 2026-10-25): an empty Enter asks ONCE more; a second empty Enter gives up; `q` gives up at once. `null` = nothing was chosen
16
+ * (the caller ends its command cleanly: a plain line, nothing run, exit 0).
17
+ * @param {(q: string) => Promise<string>} ask @param {string} question
18
+ * @returns {Promise<string|null>}
19
+ */
20
+ export function askRequired(ask: (q: string) => Promise<string>, question: string): Promise<string | null>;
21
+ export function isQuit(s: string): boolean;
package/types/reuse.d.ts CHANGED
@@ -163,6 +163,9 @@ export function selectBridge({ registry, job, ask, provider, pinned, shortlist,
163
163
  forceCold?: boolean | undefined;
164
164
  exclude?: string[] | undefined;
165
165
  }): Promise<any>;
166
+ /** what the run's own spine says about a try, read back after it returns
167
+ * @param {any[]} events @returns {any} */
168
+ export function readTry(events: any[]): any;
166
169
  /**
167
170
  * Read a killed reuse run's OWN SPINE back into the state a resume continues from.
168
171
  *
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Everything knowable about a run before any number is read: green (a run that was already green at start saved no plan), a signed spec
3
+ * beside it, a repo job, a saved plan made under that spec. The one check the list and the export share, so the list never offers
4
+ * what export would refuse for one of these reasons.
5
+ * @param {any} row a run-list row @param {string} name its `job (run-N)` name
6
+ * @returns {{ ok: true, records: any[], signed: { spec: any, specHash: string }, bf: any } | { ok: false, why: string }}
7
+ */
8
+ export function checkExportable(row: any, name: string): {
9
+ ok: true;
10
+ records: any[];
11
+ signed: {
12
+ spec: any;
13
+ specHash: string;
14
+ };
15
+ bf: any;
16
+ } | {
17
+ ok: false;
18
+ why: string;
19
+ };
20
+ /**
21
+ * The green panel / run-u runs export CAN take, oldest first, as `{name, runid, job}`. A run export would refuse for a reason knowable
22
+ * here (already green with no saved plan, a rubric / page-link / folder job, no signed spec) is not listed; a number it cannot read
23
+ * (cost, time, rounds, patient) is still refused at export, in words. Rows made by `bareloop run` or a backfill are not listed.
24
+ * @param {{ home?: string }} [opts]
25
+ * @returns {{ name: string, runid: string, job: string, at: string, outcome: string, row: any }[]}
26
+ */
27
+ export function listGreenRuns(opts?: {
28
+ home?: string;
29
+ }): {
30
+ name: string;
31
+ runid: string;
32
+ job: string;
33
+ at: string;
34
+ outcome: string;
35
+ row: any;
36
+ }[];
37
+ /**
38
+ * Build the bundle for one green run. Never throws for a run it cannot export: every stop is `{ok:false, why}` in plain words.
39
+ * @param {{ name: string, outDir: string, home?: string, bareloopVersion: string, now?: () => number }} o
40
+ * @returns {{ ok: true, runid: string, job: string, name: string, dir: string, bundleHash: string } | { ok: false, why: string }}
41
+ */
42
+ export function exportRun({ name, outDir, home, bareloopVersion, now }: {
43
+ name: string;
44
+ outDir: string;
45
+ home?: string;
46
+ bareloopVersion: string;
47
+ now?: () => number;
48
+ }): {
49
+ ok: true;
50
+ runid: string;
51
+ job: string;
52
+ name: string;
53
+ dir: string;
54
+ bundleHash: string;
55
+ } | {
56
+ ok: false;
57
+ why: string;
58
+ };
@@ -0,0 +1,40 @@
1
+ /**
2
+ * `<out>/source-<seed>/<job>-bareloop/u-<runid>.jsonl` -> the two files an
3
+ * authoring session leaves BESIDE that layout — `<out>/resolved-spec.json`
4
+ * (the signed spec `--spec`/a JOBS-table row ran) and
5
+ * `<out>/source-<seed>/source.json` (the source front door's manifest) —
6
+ * verified against `src/userrun.js`'s own construction (`specWorkdir = join(into,
7
+ * 'tree')`, `spineDir = join(wd, '..', target.spine)`, both `--spec` and the
8
+ * `pulselog-person-strict` JOBS-table row read `into` the same way) and a real
9
+ * archived run (pulselog-person-live-2, run mu2p83go): `dirname(spine)` is
10
+ * `<into>/<job>-bareloop`, `dirname(dirname(spine))` is `<into>` itself
11
+ * (`source-<seed>`, carrying `source.json`), and `dirname(dirname(dirname(spine)))`
12
+ * is `<out>` (carrying `resolved-spec.json`).
13
+ *
14
+ * Only resolves when `<into>`'s own name starts with `source-` — the one
15
+ * shape marker this convention always carries — and each file is checked to
16
+ * actually exist before being handed back; any other spine layout (the bundle
17
+ * `spine.jsonl`, a JOBS-table row whose workdir has no source-seed copy, e.g.
18
+ * `litectx-u`) returns both fields `null`, never a guessed path (build spec
19
+ * item 2, 2026-09-25: "don't search the disk broadly — fall through").
20
+ * @param {string} spinePath
21
+ * @returns {{ specPath: string|null, sourceJsonPath: string|null }}
22
+ */
23
+ export function sourceNearSpine(spinePath: string): {
24
+ specPath: string | null;
25
+ sourceJsonPath: string | null;
26
+ };
27
+ /**
28
+ * The signed spec a run's LATEST leg ran under — the `resolved-spec*.json` beside the run whose hash is the one its
29
+ * latest `job-start` carries (the same lookup `resumePlanFor` does). `null` = no such file.
30
+ * @param {{ spine: string }} row
31
+ * @param {any[]} records
32
+ * @returns {{spec: any, specPath: string, specHash: string}|null}
33
+ */
34
+ export function signedSpecForRun(row: {
35
+ spine: string;
36
+ }, records: any[]): {
37
+ spec: any;
38
+ specPath: string;
39
+ specHash: string;
40
+ } | null;
@@ -88,6 +88,29 @@ export function appendNeedsRemoved(runid: string, opts?: {
88
88
  export function readNeedsRemovals(opts?: {
89
89
  home?: string;
90
90
  }): Map<string, number>;
91
+ /**
92
+ * @typedef {{ type: 'exported', runid: string, job: string, bundle: string, bundleHash: string, at: string }} ExportedRow
93
+ * RULED 2026-10-25 (PRD v1.114): `bareloop export` appends ONE of these per bundle it makes, so `bareloop run` can find the bundle by the
94
+ * run's name. Not a run, a claim or an event: {@link readRunList} ignores it (it has a `type`), so the monthly limit, the run counter and the
95
+ * scheduler never see it. Nothing is rewritten.
96
+ */
97
+ /**
98
+ * Append one {@link ExportedRow}. THROWS on IO failure.
99
+ * @param {Omit<ExportedRow, 'type'>} row
100
+ * @param {{ home?: string }} [opts]
101
+ * @returns {void}
102
+ */
103
+ export function appendExported(row: Omit<ExportedRow, "type">, opts?: {
104
+ home?: string;
105
+ }): void;
106
+ /**
107
+ * Every `exported` row, in file order (a re-export of the same run is a later row). An absent file is an empty list.
108
+ * @param {{ home?: string }} [opts]
109
+ * @returns {ExportedRow[]}
110
+ */
111
+ export function readExported(opts?: {
112
+ home?: string;
113
+ }): ExportedRow[];
91
114
  /**
92
115
  * @typedef {{ type: 'leg-start', runid: string, leg: number, pid?: number, capUsd?: number, at: string }} LegStart
93
116
  * A resumed run's NEW claim (P5-R, hamr 2026-10-02: one run, one id, one row): appended beside the run's row
@@ -206,6 +229,25 @@ export function backfillRuns(dir: string, opts?: {
206
229
  * @returns {string}
207
230
  */
208
231
  export function formatRunRow(row: RunRow): string;
232
+ /**
233
+ * @param {any} r
234
+ * @returns {number}
235
+ */
236
+ export function atMs(r: any): number;
237
+ /**
238
+ * A run's name for a person: `job (run-N)`, N from {@link runNumbers}. The ONE spelling (the panel, `bareloop export` and `bareloop run` all print it).
239
+ * @param {string} job @param {number|undefined} n
240
+ * @returns {string}
241
+ */
242
+ export function runNameOf(job: string, n: number | undefined): string;
243
+ /**
244
+ * The ONE owner of run names (P6 item 7): runs of the same job (`row.job`) are numbered oldest `at` first, 1-based
245
+ * (ties keep file order). A resume is one row, so it counts once; died and stopped runs are rows too. Every view
246
+ * reads this number — the page never counts on its own.
247
+ * @param {any[]} rows
248
+ * @returns {Map<string, number>} runid → N
249
+ */
250
+ export function runNumbers(rows: any[]): Map<string, number>;
209
251
  export const DIED_MTIME_MS: number;
210
252
  export const MAX_BACKFILL_DEPTH: 6;
211
253
  /**
@@ -248,6 +290,19 @@ export type RunEvent = {
248
290
  spendComplete?: boolean;
249
291
  leg?: number;
250
292
  };
293
+ /**
294
+ * RULED 2026-10-25 (PRD v1.114): `bareloop export` appends ONE of these per bundle it makes, so `bareloop run` can find the bundle by the
295
+ * run's name. Not a run, a claim or an event: {@link readRunList} ignores it (it has a `type`), so the monthly limit, the run counter and the
296
+ * scheduler never see it. Nothing is rewritten.
297
+ */
298
+ export type ExportedRow = {
299
+ type: "exported";
300
+ runid: string;
301
+ job: string;
302
+ bundle: string;
303
+ bundleHash: string;
304
+ at: string;
305
+ };
251
306
  /**
252
307
  * A resumed run's NEW claim (P5-R, hamr 2026-10-02: one run, one id, one row): appended beside the run's row
253
308
  * instead of a second row. {@link readRunList} folds it into the row.