bareloop 0.47.1 → 0.49.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 (47) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/README.md +16 -9
  3. package/bareloop.context.md +70 -46
  4. package/bin/bareloop.mjs +2 -0
  5. package/package.json +3 -3
  6. package/src/bundle.js +36 -9
  7. package/src/bundleref.js +103 -0
  8. package/src/bundlerun.js +134 -17
  9. package/src/cli.js +138 -144
  10. package/src/config.js +1 -1
  11. package/src/draftspend.js +88 -34
  12. package/src/facts.js +1 -1
  13. package/src/interviewrun.js +11 -11
  14. package/src/invoke.js +3 -2
  15. package/src/launcher.js +122 -12
  16. package/src/learn.js +34 -20
  17. package/src/learnstore.js +30 -14
  18. package/src/pagedropwords.js +1 -0
  19. package/src/pagedry.js +77 -6
  20. package/src/pagemap.js +17 -3
  21. package/src/pagerules.js +2 -1
  22. package/src/panel/authorsession.js +7 -13
  23. package/src/panel/index.html +30 -7
  24. package/src/panel/runroutes.js +28 -14
  25. package/src/panel/server.js +69 -118
  26. package/src/prompts.js +50 -0
  27. package/src/reuse.js +1 -1
  28. package/src/runexport.js +162 -0
  29. package/src/runfiles.js +65 -0
  30. package/src/runlist.js +72 -0
  31. package/src/userrun.js +17 -13
  32. package/types/bundle.d.ts +16 -0
  33. package/types/bundleref.d.ts +63 -0
  34. package/types/bundlerun.d.ts +10 -3
  35. package/types/cli.d.ts +2 -1
  36. package/types/draftspend.d.ts +7 -23
  37. package/types/launcher.d.ts +67 -2
  38. package/types/learn.d.ts +29 -15
  39. package/types/learnstore.d.ts +31 -10
  40. package/types/pagedry.d.ts +26 -0
  41. package/types/pagemap.d.ts +1 -0
  42. package/types/panel/server.d.ts +7 -3
  43. package/types/prompts.d.ts +21 -0
  44. package/types/reuse.d.ts +3 -0
  45. package/types/runexport.d.ts +58 -0
  46. package/types/runfiles.d.ts +40 -0
  47. package/types/runlist.d.ts +55 -0
package/types/learn.d.ts CHANGED
@@ -181,13 +181,14 @@ export function foldCards(cards: Card[]): Card[][];
181
181
  * @property {string[]} runIds
182
182
  * @property {string} firstSeen
183
183
  * @property {string} lastSeen
184
- * @property {string|null} specHash the signed hash the lesson was last seen under (a workflow row of another hash is never matched or read)
184
+ * @property {string|null} specHash the signed hash the lesson was last seen under (a record only; the job version is `workflowKey`)
185
+ * @property {string|null} [workflowKey] the workflow key (Reuse's rule: caps, time, source, destination, inputs and model do not move it) the lesson was last seen under; a workflow row of another key is never matched or read. Absent on rows an older version wrote: those match any version
185
186
  * @property {string} key check + sorted kinds (job-independent); information only since R2 removed the check-wide set-aside
186
187
  */
187
188
  /**
188
189
  * @typedef {object} Pending
189
190
  * @property {string} runid @property {string} at @property {string} workflow @property {string|null} place
190
- * @property {string|null} specHash @property {Card[]} cards
191
+ * @property {string|null} specHash @property {string|null} [workflowKey] @property {Card[]} cards
191
192
  */
192
193
  /**
193
194
  * @typedef {object} Ledger
@@ -209,20 +210,21 @@ export function lessonOf(c: Card): string;
209
210
  *
210
211
  * +1 per RUN per row: the run's own cards are folded into lessons first, and a row whose `runIds` already holds the
211
212
  * run id is never counted twice (a resumed run, one id, never double counts) but IS refreshed: the resumed leg's card
212
- * replaces the sample, lesson, key, lastSeen, hash and place (a leg-1 NEVER FIXED row becomes the leg-2 FIXED one). A
213
+ * replaces the sample, lesson, key, lastSeen, hash, key and place (a leg-1 NEVER FIXED row becomes the leg-2 FIXED one). A
213
214
  * matching lesson replaces the row's sample, bumps the model count and appends the run id (a row last seen 56+ days ago counts +1 and is read again);
214
215
  * otherwise it opens a new row at count 1. NEVER FIXED cards count like FIXED ones (RULING 3). A workflow row of
215
- * another signed hash is never matched here: the new version opens its own rows. Nothing is ever deleted or stamped.
216
+ * another workflow key is never matched here: the new version opens its own rows. Nothing is ever deleted or stamped.
216
217
  * @param {Ledger} ledger
217
- * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, trust: 'deterministic'|'rubric', now: Date}} o
218
+ * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, workflowKey?: string|null, trust: 'deterministic'|'rubric', now: Date}} o
218
219
  * @returns {Ledger}
219
220
  */
220
- export function countLedger(ledger: Ledger, { runid, cards, workflow, place, specHash, trust, now }: {
221
+ export function countLedger(ledger: Ledger, { runid, cards, workflow, place, specHash, workflowKey, trust, now }: {
221
222
  runid: string;
222
223
  cards: Card[];
223
224
  workflow: string;
224
225
  place: string | null;
225
226
  specHash: string | null;
227
+ workflowKey?: string | null;
226
228
  trust: "deterministic" | "rubric";
227
229
  now: Date;
228
230
  }): Ledger;
@@ -238,15 +240,16 @@ export function climb(rows: Row[]): Row[];
238
240
  * Hold a run's cards until a human Accept. NO LONGER CALLED for new runs (v1.112: a rubric run's lessons count at run
239
241
  * end); kept so a hold already in a ledger file still has a writer for tests and a reader in {@link releasePending}. Pure.
240
242
  * @param {Ledger} ledger
241
- * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, at: string}} o
243
+ * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, workflowKey?: string|null, at: string}} o
242
244
  * @param {Date} now @returns {Ledger}
243
245
  */
244
- export function holdPending(ledger: Ledger, { runid, cards, workflow, place, specHash, at }: {
246
+ export function holdPending(ledger: Ledger, { runid, cards, workflow, place, specHash, workflowKey, at }: {
245
247
  runid: string;
246
248
  cards: Card[];
247
249
  workflow: string;
248
250
  place: string | null;
249
251
  specHash: string | null;
252
+ workflowKey?: string | null;
250
253
  at: string;
251
254
  }, now: Date): Ledger;
252
255
  /**
@@ -286,30 +289,36 @@ export function saidLine(said: string[]): string | undefined;
286
289
  * derived HERE by {@link climb} over the rows not decayed at `now` only; the stored level is never read.
287
290
  * Order: this job's, then this place's, then all-jobs LAST (R2: climbing wins, so an all-jobs hint only uses leftover
288
291
  * room); inside each level highest count first (ties: most recent lastSeen, then id), so the order is total and stable.
289
- * @param {Ledger} ledger @param {{workflow: string, place: string|null, specHash?: string|null, now: Date}} o
292
+ * @param {Ledger} ledger @param {{workflow: string, place: string|null, workflowKey?: string|null, now: Date}} o
290
293
  * @returns {Row[]}
291
294
  */
292
- export function readableRows(ledger: Ledger, { workflow, place, specHash, now }: {
295
+ export function readableRows(ledger: Ledger, { workflow, place, workflowKey, now }: {
293
296
  workflow: string;
294
297
  place: string | null;
295
- specHash?: string | null;
298
+ workflowKey?: string | null;
296
299
  now: Date;
297
300
  }): Row[];
298
301
  /**
299
302
  * THE one render: the block the PLANNER reads at draft and at the first replan. Byte-for-byte reproducible from the
300
303
  * ledger as it stood. Stops at 2,000 characters; a hint is added whole or not at all; nothing readable -> empty text.
301
- * @param {Ledger} ledger @param {{workflow: string, place: string|null, specHash?: string|null, now: Date}} o
304
+ * @param {Ledger} ledger @param {{workflow: string, place: string|null, workflowKey?: string|null, now: Date}} o
302
305
  * @returns {{text: string, ids: string[]}}
303
306
  */
304
307
  export function renderHints(ledger: Ledger, o: {
305
308
  workflow: string;
306
309
  place: string | null;
307
- specHash?: string | null;
310
+ workflowKey?: string | null;
308
311
  now: Date;
309
312
  }): {
310
313
  text: string;
311
314
  ids: string[];
312
315
  };
316
+ /**
317
+ * The one plain-words line for a learnings file that could not be read (the Audit prints it; the spine keeps the full
318
+ * reason). The person's home folder is written `~`, so the line stays short and the file can still be found.
319
+ * @param {string} reason @param {string} [userHome] defaults to the OS home @returns {string}
320
+ */
321
+ export function hintsErrorLine(reason: string, userHome?: string): string;
313
322
  /**
314
323
  * Split a block {@link renderHints} wrote back into its hints. The ONLY reader of that text: it lives beside the
315
324
  * writer ({@link hintText}, {@link lessonOf}) and a test renders real blocks and parses them back. A hint it cannot
@@ -348,7 +357,7 @@ export function keyOfCard(c: {
348
357
  kinds: string[];
349
358
  }): string;
350
359
  export function isDecayed(r: Row, now: Date): boolean;
351
- export function otherJobVersion(r: Row, workflow: string, specHash: string | null): boolean;
360
+ export function otherJobVersion(r: Row, workflow: string, workflowKey: string | null | undefined): boolean;
352
361
  /**
353
362
  * PROPOSED header (hamr to confirm). States what the block is, where it came from, and that it is not an order.
354
363
  */
@@ -491,9 +500,13 @@ export type Row = {
491
500
  firstSeen: string;
492
501
  lastSeen: string;
493
502
  /**
494
- * the signed hash the lesson was last seen under (a workflow row of another hash is never matched or read)
503
+ * the signed hash the lesson was last seen under (a record only; the job version is `workflowKey`)
495
504
  */
496
505
  specHash: string | null;
506
+ /**
507
+ * the workflow key (Reuse's rule: caps, time, source, destination, inputs and model do not move it) the lesson was last seen under; a workflow row of another key is never matched or read. Absent on rows an older version wrote: those match any version
508
+ */
509
+ workflowKey?: string | null | undefined;
497
510
  /**
498
511
  * check + sorted kinds (job-independent); information only since R2 removed the check-wide set-aside
499
512
  */
@@ -505,6 +518,7 @@ export type Pending = {
505
518
  workflow: string;
506
519
  place: string | null;
507
520
  specHash: string | null;
521
+ workflowKey?: string | null | undefined;
508
522
  cards: Card[];
509
523
  };
510
524
  export type Ledger = {
@@ -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
+ };
@@ -33,5 +33,31 @@ export function dryReadPhrases(text: string, facts: KeptFact[]): Promise<{
33
33
  dropped: Dropped[];
34
34
  reads: Record<string, number>;
35
35
  }>;
36
+ /**
37
+ * The candidate lines of a kept time fact: a LOOSE finder (it only collects). Every page line where a kept label word has a clock time anywhere
38
+ * after it; the value is that line's first time after the label. Whether the run's checker can read it is not decided here.
39
+ * @param {string} text @param {KeptFact} k @returns {{quote: string, value: string}[]}
40
+ */
41
+ export function timeCandidateLines(text: string, k: KeptFact): {
42
+ quote: string;
43
+ value: string;
44
+ }[];
45
+ /**
46
+ * The same "can it read" for TIME facts (F236: the label "Departure time" sat on a page that writes "Departure time:", the colon right after it, so
47
+ * no time could ever be read after the label, and the fact was signed anyway). Each candidate line of a kept time fact is graded as an HONEST claim
48
+ * (quote = that line, value = its first time after the label) by the real `gradeStep`, signed like a run would sign it (name, shape, anchor = the
49
+ * primary label; no window, as dryReadMoney leaves the limits out). A fact with no green line is dropped whole as `reads-no-time`.
50
+ * No counts, no pass bar. A time fact with no label word has nothing to anchor a read to (a run could not sign it either), so it passes through untouched.
51
+ * Facts of other shapes pass through untouched. It catches an IMPOSSIBLE label only: a label that reads a WRONG time is kept (left to the person at Accept).
52
+ * @param {string} text the frozen page text @param {KeptFact[]} facts what the money dry read kept
53
+ * @returns {Promise<{facts: KeptFact[], dropped: Dropped[], reads: Record<string, number>, results: Record<string, number>}>}
54
+ * `reads` / `results` = candidate lines the checker read / found, per fact name (for tests and reports; no verdict derives from the numbers)
55
+ */
56
+ export function dryReadTimes(text: string, facts: KeptFact[]): Promise<{
57
+ facts: KeptFact[];
58
+ dropped: Dropped[];
59
+ reads: Record<string, number>;
60
+ results: Record<string, number>;
61
+ }>;
36
62
  export type KeptFact = import("./pagerules.js").KeptFact;
37
63
  export type Dropped = import("./pagerules.js").Dropped;
@@ -139,6 +139,7 @@ export const MAP_UNREADABLE: "The AI's answer about the page was not readable tw
139
139
  export const DROP_IT: "drop it";
140
140
  export function isDropIt(text: unknown): boolean;
141
141
  export function isAgree(text: unknown): boolean;
142
+ export function stripAgreeLead(text: string): string;
142
143
  /**
143
144
  * `reading` = the plain words an `agree` writes as a `~` rule (a reading ask only)
144
145
  */
@@ -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.