bareloop 0.55.0 → 0.56.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 (56) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/bareloop.context.md +4 -2
  3. package/package.json +2 -2
  4. package/src/authorflow.js +141 -264
  5. package/src/authoring.js +2 -3
  6. package/src/authorjob.js +117 -88
  7. package/src/authorreadout.js +9 -15
  8. package/src/authorrun.js +13 -4
  9. package/src/behaviour.js +14 -0
  10. package/src/blockasks.js +43 -0
  11. package/src/checkblock.js +772 -0
  12. package/src/checklist.js +128 -0
  13. package/src/checkpick.js +30 -312
  14. package/src/checkwords.js +3 -1
  15. package/src/declaredclose.js +30 -1
  16. package/src/destpoint.js +3 -1
  17. package/src/draftspend.js +46 -0
  18. package/src/facts.js +8 -1
  19. package/src/fitcheck.js +5 -3
  20. package/src/pagemap.js +15 -3
  21. package/src/panel/authorroutes.js +15 -3
  22. package/src/panel/authorsession.js +133 -46
  23. package/src/panel/index.html +194 -22
  24. package/src/panel/jobplan.js +85 -33
  25. package/src/panel/server.js +52 -7
  26. package/src/pickrecord.js +19 -1
  27. package/src/placerule.js +355 -0
  28. package/src/promptregisters.js +11 -0
  29. package/src/questionbox.js +112 -0
  30. package/src/rowedit.js +115 -0
  31. package/src/rubricstep.js +212 -125
  32. package/src/run.js +10 -2
  33. package/src/userrun.js +46 -1
  34. package/types/authorflow.d.ts +32 -139
  35. package/types/authorjob.d.ts +24 -6
  36. package/types/authorreadout.d.ts +4 -10
  37. package/types/behaviour.d.ts +12 -0
  38. package/types/blockasks.d.ts +37 -0
  39. package/types/checkblock.d.ts +361 -0
  40. package/types/checklist.d.ts +134 -0
  41. package/types/checkpick.d.ts +3 -140
  42. package/types/declaredclose.d.ts +4 -0
  43. package/types/destpoint.d.ts +2 -0
  44. package/types/draftspend.d.ts +21 -0
  45. package/types/fitcheck.d.ts +7 -1
  46. package/types/pagemap.d.ts +4 -0
  47. package/types/panel/authorsession.d.ts +13 -2
  48. package/types/panel/jobgrid.d.ts +8 -8
  49. package/types/panel/jobplan.d.ts +48 -10
  50. package/types/panel/server.d.ts +14 -13
  51. package/types/pickrecord.d.ts +12 -0
  52. package/types/placerule.d.ts +194 -0
  53. package/types/questionbox.d.ts +87 -0
  54. package/types/rowedit.d.ts +32 -0
  55. package/types/rubricstep.d.ts +91 -48
  56. package/types/run.d.ts +10 -1
@@ -186,6 +186,10 @@ export const DECLARED_GENRES: readonly string[];
186
186
  * channel of its own.
187
187
  */
188
188
  export const CLOSE_DECL_FIELDS: readonly string[];
189
+ /** the fields of a row of the one check list that the signed close carries (`closeDecl.list`); the row's own words are never signed */
190
+ export const SIGNED_ROW_FIELDS: readonly string[];
191
+ /** the states a signed row may end in */
192
+ export const SIGNED_STATES: readonly string[];
189
193
  /** what a stored calibration set carries, ENUMERATED: the frozen cases and the judge
190
194
  * tier that graded them. Both are inside the spec, so `jobSpecHash` covers both — which
191
195
  * is the whole mechanism behind "a judge-model bump forces a full recalibration"
@@ -79,6 +79,8 @@ export function runDestPoint({ jobLines, files, destination, provider, maxTokens
79
79
  export const DEST_CALL_LABEL: "dest-point";
80
80
  export const DEST_SYSTEM: "You read the numbered lines of a code job. You never invent words: every file path you name must be copied, character for character, from the job line that holds it.";
81
81
  export function destQuestionText(p: DestPoint, destination: string): string;
82
+ /** the answer words the question ends with (said once, here; the panel's question box shows the question without them and has the buttons instead) */
83
+ export const DEST_ANSWER: " Type yes to set it, or no to keep it as it is.";
82
84
  export function yesNoOf(text: unknown): "yes" | "no" | null;
83
85
  export type DestPoint = {
84
86
  line: number;
@@ -104,6 +104,27 @@ export function readDraftChecks(dir: string): {
104
104
  text: string;
105
105
  by: "agent" | "you";
106
106
  }[];
107
+ /**
108
+ * The suggested checks code could not build, one plain sentence each (the last `draft-notbuilt` line of the log): the Audit's draft lines. `[]` when there are none.
109
+ * @param {string} dir
110
+ * @returns {{line: number, text: string}[]}
111
+ */
112
+ export function readDraftNotBuilt(dir: string): {
113
+ line: number;
114
+ text: string;
115
+ }[];
116
+ /**
117
+ * The check list's rows as the drafting ended (draft log `ledger` rows of phase `final`, the last one per key): each row's own words, so the Job tab can name a
118
+ * Not checked row in the person's words. `null` when the session has no readable log or no final row (a CLI run, an imported run, a deleted session). Never throws.
119
+ * @param {string} dir
120
+ * @returns {{key: string, rowKind: string, words: string[], state: string}[]|null}
121
+ */
122
+ export function readDraftLedger(dir: string): {
123
+ key: string;
124
+ rowKind: string;
125
+ words: string[];
126
+ state: string;
127
+ }[] | null;
107
128
  /**
108
129
  * The DRAFTING PART of a run (hamr 2026-10-06, option A): the first part of the run's views, built from the session's
109
130
  * drafting log. `null` when the run did not come out of a panel session, or the log carries no metered call (a Reuse
@@ -95,14 +95,20 @@ export function notFoundList(notFound: {
95
95
  line: number;
96
96
  ask: string;
97
97
  }[]): string;
98
- export function fitQuestionText({ found, total, notFound }: {
98
+ export function fitQuestionText({ found, total, notFound, foundAsks }: {
99
99
  found: number;
100
100
  total: number;
101
101
  notFound: {
102
102
  line: number;
103
103
  ask: string;
104
104
  }[];
105
+ foundAsks?: {
106
+ line: number;
107
+ ask: string;
108
+ }[];
105
109
  }): string;
110
+ /** the answer words the question ends with (said once, here; the panel's question box shows the question without them and has the buttons instead) */
111
+ export const FIT_ANSWER: " Type go on to keep drafting, or anything else to stop and change the job or the page.";
106
112
  export type FitAsk = {
107
113
  line: number;
108
114
  ask: string;
@@ -141,6 +141,10 @@ export const DROP_IT: "drop it";
141
141
  export function isDropIt(text: unknown): boolean;
142
142
  export function isAgree(text: unknown): boolean;
143
143
  export function stripAgreeLead(text: string): string;
144
+ export function readingTail(n: number): string;
145
+ export function cantCheckTail(n: number): string;
146
+ export function readingQuestion(n: number, rule: string, reading: string): string;
147
+ export function cantCheckQuestion(n: number, rule: string): string;
144
148
  /**
145
149
  * `reading` = the plain words an `agree` writes as a `~` rule (a reading ask only)
146
150
  */
@@ -14,7 +14,7 @@ export function advanceSteps(steps: StepLine[], id: string, detail?: string, lab
14
14
  * The confirm turn's plan as a chat message (P7): a STRUCTURED `{role:'bot', kind:'plan', plan}` the page draws with the
15
15
  * same renderer the Job tab uses — each numbered job line, its `~` rule, its drafted checks folded; the AI's own "not
16
16
  * checked"; the always-on guards. `questions` (what the plan still asks) ride inside the plan. One owner of the shape.
17
- * @param {{goal?: string, checks?: string[], checkItems?: {text: string, fromLine: number[]|null}[], notChecked?: string[], questions?: string[], protections?: string[], signedFacts?: string[], ticketFilter?: any, picked?: {line: number, text: string}[]}} p the confirm turn's plan
17
+ * @param {{goal?: string, checks?: string[], checkItems?: {text: string, fromLine: number[]|null, by?: 'agent'|'you'|'default'|null, key?: string}[], notChecked?: string[], notCheckedBy?: Record<string, 'you'|'agent'|'default'>, suggested?: {key: string, line: number, text: string}[], editable?: boolean, questions?: string[], protections?: string[], signedFacts?: string[], ticketFilter?: any, picked?: {line: number, text: string}[]}} p the confirm turn's plan
18
18
  * @param {{n: number, text: string, rule: string}[]|null} jobLines
19
19
  * @returns {{role: 'bot', kind: 'plan', text: string, plan: ReturnType<typeof planFromConfirm> & {goal: string, questions: string[]}}}
20
20
  */
@@ -24,8 +24,17 @@ export function planMessage(p: {
24
24
  checkItems?: {
25
25
  text: string;
26
26
  fromLine: number[] | null;
27
+ by?: "agent" | "you" | "default" | null;
28
+ key?: string;
27
29
  }[];
28
30
  notChecked?: string[];
31
+ notCheckedBy?: Record<string, "you" | "agent" | "default">;
32
+ suggested?: {
33
+ key: string;
34
+ line: number;
35
+ text: string;
36
+ }[];
37
+ editable?: boolean;
29
38
  questions?: string[];
30
39
  protections?: string[];
31
40
  signedFacts?: string[];
@@ -206,7 +215,7 @@ export function validateJobCard(card: any, opts?: {
206
215
  * `signPrepare()` are the only ways in.
207
216
  * @param {any} card the validated job card (see {@link validateJobCard})
208
217
  * @param {{env?: Record<string,string|undefined>, sessionsRoot?: string, home?: string, timeoutMs?: number,
209
- * scout?: any, generate?: Function, pickGenerate?: Function|null, carryFrom?: string, carryKind?: string, confirmGenerate?: Function, authorFn?: Function,
218
+ * scout?: any, generate?: Function, pickGenerate?: Function|null, ledgerGenerate?: Function|null, editGenerate?: Function|null, carryFrom?: string, carryKind?: string, confirmGenerate?: Function, authorFn?: Function,
210
219
  * prepareSigningFn?: Function, npmCiFn?: Function, lookFn?: Function|null, fitFn?: Function|null, destFn?: Function|null, fetchUrl?: (url: string) => Promise<{ok: true, text: string, url: string}|{ok: false, error: string}>, draftThinking?: "on"|"off", reuse?: {spec: any, workflowKey: string}, schedule?: import('../trigger.js').Trigger|null, flow?: {flowType: 'plain'|'mcp'|'tickets', pick: {server: string, tools: string[]}|null}}} [deps] `scout`..`prepareSigningFn` are
211
220
  * TEST SEAMS ONLY — see the note just above where each is read, below. `reuse` (Reuse workflow) is NOT a seam: the
212
221
  * caller (`/api/author/start`) sets it only when the server's own same-job rule held.
@@ -220,6 +229,8 @@ export function createSession(card: any, deps?: {
220
229
  scout?: any;
221
230
  generate?: Function;
222
231
  pickGenerate?: Function | null;
232
+ ledgerGenerate?: Function | null;
233
+ editGenerate?: Function | null;
223
234
  carryFrom?: string;
224
235
  carryKind?: string;
225
236
  confirmGenerate?: Function;
@@ -75,7 +75,7 @@ export function buildJobGrid({ entries, scheduleLine }: {
75
75
  anyway: boolean;
76
76
  name: string;
77
77
  ref: string;
78
- bucket: "done" | "stop" | "skip" | "wait";
78
+ bucket: "done" | "skip" | "stop" | "wait";
79
79
  status: {
80
80
  key: string;
81
81
  sign: string;
@@ -111,7 +111,7 @@ export function buildJobGrid({ entries, scheduleLine }: {
111
111
  anyway: boolean;
112
112
  name: string;
113
113
  ref: string;
114
- bucket: "done" | "stop" | "skip" | "wait";
114
+ bucket: "done" | "skip" | "stop" | "wait";
115
115
  status: {
116
116
  key: string;
117
117
  sign: string;
@@ -151,7 +151,7 @@ export function buildJobGrid({ entries, scheduleLine }: {
151
151
  anyway: boolean;
152
152
  name: string;
153
153
  ref: string;
154
- bucket: "done" | "stop" | "skip" | "wait";
154
+ bucket: "done" | "skip" | "stop" | "wait";
155
155
  status: {
156
156
  key: string;
157
157
  sign: string;
@@ -187,7 +187,7 @@ export function buildJobGrid({ entries, scheduleLine }: {
187
187
  anyway: boolean;
188
188
  name: string;
189
189
  ref: string;
190
- bucket: "done" | "stop" | "skip" | "wait";
190
+ bucket: "done" | "skip" | "stop" | "wait";
191
191
  status: {
192
192
  key: string;
193
193
  sign: string;
@@ -227,7 +227,7 @@ export function buildJobGrid({ entries, scheduleLine }: {
227
227
  anyway: boolean;
228
228
  name: string;
229
229
  ref: string;
230
- bucket: "done" | "stop" | "skip" | "wait";
230
+ bucket: "done" | "skip" | "stop" | "wait";
231
231
  status: {
232
232
  key: string;
233
233
  sign: string;
@@ -263,7 +263,7 @@ export function buildJobGrid({ entries, scheduleLine }: {
263
263
  anyway: boolean;
264
264
  name: string;
265
265
  ref: string;
266
- bucket: "done" | "stop" | "skip" | "wait";
266
+ bucket: "done" | "skip" | "stop" | "wait";
267
267
  status: {
268
268
  key: string;
269
269
  sign: string;
@@ -303,7 +303,7 @@ export function buildJobGrid({ entries, scheduleLine }: {
303
303
  anyway: boolean;
304
304
  name: string;
305
305
  ref: string;
306
- bucket: "done" | "stop" | "skip" | "wait";
306
+ bucket: "done" | "skip" | "stop" | "wait";
307
307
  status: {
308
308
  key: string;
309
309
  sign: string;
@@ -339,7 +339,7 @@ export function buildJobGrid({ entries, scheduleLine }: {
339
339
  anyway: boolean;
340
340
  name: string;
341
341
  ref: string;
342
- bucket: "done" | "stop" | "skip" | "wait";
342
+ bucket: "done" | "skip" | "stop" | "wait";
343
343
  status: {
344
344
  key: string;
345
345
  sign: string;
@@ -5,26 +5,25 @@
5
5
  * @returns {'machine check'|'judge'|null}
6
6
  */
7
7
  export function checkClassOfKind(kind: unknown): "machine check" | "judge" | null;
8
- /**
9
- * The `~` rules of one job line, each on its own (the page draws one `~` row per rule): the line's own `rules` array when it
10
- * has one (a rule may itself contain "; "), else the joined `rule` split on "; " (an older line that saved only the join).
11
- * @param {any} l @returns {string[]}
12
- */
13
- export function rulesOfLine(l: any): string[];
14
8
  /**
15
9
  * The plan of a SIGNED spec. With `jobLines`, each stage lands under EACH line its `fromLine` array names (a stage with none is
16
10
  * a mandatory guard: "Always checked"), `closeDecl.refused` reasons land under their line, and `closeDecl.notes` are the
17
11
  * drafter's own "not checked" words. Without `jobLines` (a spec that predates the job block) the signed goal sentence is
18
12
  * line 1 and every stage name is a check under it — `older: true`.
13
+ * `ledger` = the draft log's final check-list rows (`readDraftLedger`), the words a Not checked row is named by; absent (no draft log) a row is named from its key.
19
14
  * @param {any} spec
15
+ * @param {{key: string, words: string[]}[]|null} [ledger]
20
16
  * @returns {JobPlan}
21
17
  */
22
- export function planFromSpec(spec: any): JobPlan;
18
+ export function planFromSpec(spec: any, ledger?: {
19
+ key: string;
20
+ words: string[];
21
+ }[] | null): JobPlan;
23
22
  /**
24
23
  * The plan of the confirm turn, before anything is drafted: the person's own job lines, the model's checks under the
25
24
  * line each names, its own "not checked" words, and the real protections (code-owned) as "Always checked".
26
25
  * @param {{n: number, text: string, rule: string, rules?: string[]}[]|null|undefined} jobLines
27
- * @param {{checkItems?: {text: string, fromLine: number[]|null, by?: 'agent'|'you'|null}[], checks?: string[], notChecked?: string[], protections?: string[], signedFacts?: string[], ticketFilter?: any, picked?: {line: number, text: string}[]}} plan
26
+ * @param {{checkItems?: {text: string, fromLine: number[]|null, by?: 'agent'|'you'|'default'|null, key?: string}[], checks?: string[], notChecked?: string[], protections?: string[], signedFacts?: string[], ticketFilter?: any, picked?: {line: number, text: string}[], notCheckedBy?: Record<string, 'you'|'agent'|'default'>, suggested?: {key: string, line: number, text: string}[], editable?: boolean}} plan
28
27
  * `signedFacts` = the names of the facts the look signs (so an S1 copy of a signed fact reads as a note, not Not checked)
29
28
  * @returns {JobPlan}
30
29
  */
@@ -37,7 +36,8 @@ export function planFromConfirm(jobLines: {
37
36
  checkItems?: {
38
37
  text: string;
39
38
  fromLine: number[] | null;
40
- by?: "agent" | "you" | null;
39
+ by?: "agent" | "you" | "default" | null;
40
+ key?: string;
41
41
  }[];
42
42
  checks?: string[];
43
43
  notChecked?: string[];
@@ -48,11 +48,42 @@ export function planFromConfirm(jobLines: {
48
48
  line: number;
49
49
  text: string;
50
50
  }[];
51
+ notCheckedBy?: Record<string, "you" | "agent" | "default">;
52
+ suggested?: {
53
+ key: string;
54
+ line: number;
55
+ text: string;
56
+ }[];
57
+ editable?: boolean;
51
58
  }): JobPlan;
59
+ /**
60
+ * The Audit's check list (hamr ruling A, 2026-11-13): the SAME sections as the card, read from the SAME model (`plan` = {@link planFromSpec}'s, plus `guards` = the
61
+ * code-owned protections the confirm card shows), each row with its tag and, after the run, its result. A check's result is the recorded verdict of its own signed stage
62
+ * (`results`: stage name to passed), never re-derived; a row no verdict was recorded for says so. A Not checked row's result is "not checked" (its reason is in its words).
63
+ * The write fence is enforced per write by the gate, so its row reads the gate's own record of THIS run (hamr ruling A, 2026-11-13): `blocked` = the write/edit attempts the gate denied
64
+ * (`held · N writes blocked`), or `null` when the run's gate record is missing (said in plain words, never "held").
65
+ * @param {JobPlan} plan @param {string[]} guards @param {Map<string, boolean>|null} results @param {number|null} [blocked]
66
+ * @returns {{checks: AuditRow[], notChecked: AuditRow[], always: AuditRow[]}}
67
+ */
68
+ export function auditChecksOf(plan: JobPlan, guards: string[], results: Map<string, boolean> | null, blocked?: number | null): {
69
+ checks: AuditRow[];
70
+ notChecked: AuditRow[];
71
+ always: AuditRow[];
72
+ };
73
+ /** the words of a row the run recorded no verdict for: never "passed" */
74
+ export const AUDIT_NO_RESULT: "no result recorded";
75
+ export type AuditRow = {
76
+ text: string;
77
+ by: "agent" | "you" | "default" | null;
78
+ result: "passed" | "failed" | "none" | "not-checked" | "held" | "record-missing";
79
+ word?: string;
80
+ };
52
81
  export type PlanCheck = {
53
82
  name: string;
54
83
  cls: "machine check" | "judge" | null;
55
- by?: "agent" | "you" | null;
84
+ by?: "agent" | "you" | "default" | null;
85
+ key?: string;
86
+ stage?: string;
56
87
  };
57
88
  export type PlanLine = {
58
89
  n: number;
@@ -73,4 +104,11 @@ export type JobPlan = {
73
104
  older: boolean;
74
105
  goal?: string;
75
106
  ticketFilter?: string;
107
+ notCheckedBy?: Record<string, "you" | "agent" | "default">;
108
+ suggested?: {
109
+ key: string;
110
+ line: number;
111
+ text: string;
112
+ }[];
113
+ editable?: boolean;
76
114
  };
@@ -361,7 +361,7 @@ export function getJobGrid(runid: string, opts?: {
361
361
  anyway: boolean;
362
362
  name: string;
363
363
  ref: string;
364
- bucket: "done" | "stop" | "skip" | "wait";
364
+ bucket: "done" | "skip" | "stop" | "wait";
365
365
  status: {
366
366
  key: string;
367
367
  sign: string;
@@ -397,7 +397,7 @@ export function getJobGrid(runid: string, opts?: {
397
397
  anyway: boolean;
398
398
  name: string;
399
399
  ref: string;
400
- bucket: "done" | "stop" | "skip" | "wait";
400
+ bucket: "done" | "skip" | "stop" | "wait";
401
401
  status: {
402
402
  key: string;
403
403
  sign: string;
@@ -437,7 +437,7 @@ export function getJobGrid(runid: string, opts?: {
437
437
  anyway: boolean;
438
438
  name: string;
439
439
  ref: string;
440
- bucket: "done" | "stop" | "skip" | "wait";
440
+ bucket: "done" | "skip" | "stop" | "wait";
441
441
  status: {
442
442
  key: string;
443
443
  sign: string;
@@ -473,7 +473,7 @@ export function getJobGrid(runid: string, opts?: {
473
473
  anyway: boolean;
474
474
  name: string;
475
475
  ref: string;
476
- bucket: "done" | "stop" | "skip" | "wait";
476
+ bucket: "done" | "skip" | "stop" | "wait";
477
477
  status: {
478
478
  key: string;
479
479
  sign: string;
@@ -513,7 +513,7 @@ export function getJobGrid(runid: string, opts?: {
513
513
  anyway: boolean;
514
514
  name: string;
515
515
  ref: string;
516
- bucket: "done" | "stop" | "skip" | "wait";
516
+ bucket: "done" | "skip" | "stop" | "wait";
517
517
  status: {
518
518
  key: string;
519
519
  sign: string;
@@ -549,7 +549,7 @@ export function getJobGrid(runid: string, opts?: {
549
549
  anyway: boolean;
550
550
  name: string;
551
551
  ref: string;
552
- bucket: "done" | "stop" | "skip" | "wait";
552
+ bucket: "done" | "skip" | "stop" | "wait";
553
553
  status: {
554
554
  key: string;
555
555
  sign: string;
@@ -589,7 +589,7 @@ export function getJobGrid(runid: string, opts?: {
589
589
  anyway: boolean;
590
590
  name: string;
591
591
  ref: string;
592
- bucket: "done" | "stop" | "skip" | "wait";
592
+ bucket: "done" | "skip" | "stop" | "wait";
593
593
  status: {
594
594
  key: string;
595
595
  sign: string;
@@ -625,7 +625,7 @@ export function getJobGrid(runid: string, opts?: {
625
625
  anyway: boolean;
626
626
  name: string;
627
627
  ref: string;
628
- bucket: "done" | "stop" | "skip" | "wait";
628
+ bucket: "done" | "skip" | "stop" | "wait";
629
629
  status: {
630
630
  key: string;
631
631
  sign: string;
@@ -763,11 +763,6 @@ export function getRunResult(runid: string, opts?: {
763
763
  ask: string;
764
764
  };
765
765
  } | {
766
- runid: string;
767
- lines: any[];
768
- pages: string[];
769
- pageNote: string | null;
770
- notChecked: string[];
771
766
  readNotes: string[];
772
767
  door: {
773
768
  head: "waiting for you";
@@ -786,6 +781,12 @@ export function getRunResult(runid: string, opts?: {
786
781
  more: number;
787
782
  moreText: string | null;
788
783
  } | null;
784
+ notCheckedBy?: Record<string, "you" | "agent" | "default"> | undefined;
785
+ runid: string;
786
+ lines: any[];
787
+ pages: string[];
788
+ pageNote: string | null;
789
+ notChecked: string[];
789
790
  } | null;
790
791
  /**
791
792
  * `GET /api/runs/:runid/download?i=<n>` — delivered file `n` (an index into the run's own `destination-written` list), or why not. The path is
@@ -66,6 +66,18 @@ export function matchRecord(entries: Entry[], lines: {
66
66
  * @param {string} file @returns {Entry[]|null}
67
67
  */
68
68
  export function readRecordFile(file: string): Entry[] | null;
69
+ /**
70
+ * The Drop/Add choices a draft's person made on the confirm card (hamr 2026-11-13, N-2), carried the same way as the picks: tied to the line's words and the row's own name, never to a number.
71
+ * @param {string} file @returns {{lineWords: string, occurrence: number, tail: string, choice: string}[]|null}
72
+ */
73
+ export function readRowChoices(file: string): {
74
+ lineWords: string;
75
+ occurrence: number;
76
+ tail: string;
77
+ choice: string;
78
+ }[] | null;
79
+ /** write a part of the record without losing the other: `patch` is `{picks}` or `{rowChoices}` @param {string} file @param {Record<string, any>} patch */
80
+ export function writeRecordPart(file: string, patch: Record<string, any>): void;
69
81
  /** the record's file, inside a drafting session folder only (never a run folder) */
70
82
  export const RECORD_FILE: "picks-record.json";
71
83
  /** the exact words a kept pick is marked with in the draft log, the Audit and the plan card (M10 am17 (6)) */
@@ -0,0 +1,194 @@
1
+ /**
2
+ * @typedef {{kind: 'headingBetween'|'headingDateAfter', prefix: string, end: string, shape: string, skip: string[]}} PlaceRule
3
+ * @typedef {{found: true, value: string, lineIndex: number}|{found: false, reason: string}} PlaceRead
4
+ */
5
+ /**
6
+ * Why a rule is not a legal place rule, or null when it is. Pure.
7
+ * @param {unknown} rule @returns {string|null}
8
+ */
9
+ export function placeRuleProblem(rule: unknown): string | null;
10
+ /**
11
+ * Heading lines at the rule's level: lines outside ``` / ~~~ fences that start with the level mark (for example "## "). Pure.
12
+ * @param {string} text @param {string} prefix @returns {{i: number, line: string}[]}
13
+ */
14
+ export function levelLines(text: string, prefix: string): {
15
+ i: number;
16
+ line: string;
17
+ }[];
18
+ /**
19
+ * The mixed-level guard: every non-fenced heading line is scanned; semver-carrying headings at MORE THAN ONE level mean mixed. A heading with no
20
+ * semver (a "# Changelog" title, "### Fixed") is ignored. It only ever turns a read into not found, never into a value.
21
+ * @param {string} text @returns {boolean}
22
+ */
23
+ export function mixedLevels(text: string): boolean;
24
+ /**
25
+ * Read one rule against one input text: the run-start function, code only. A rule that is not legal throws (the signed spec was validated, so a bad one
26
+ * is a defect, never a read).
27
+ * @param {PlaceRule} rule @param {string} text @returns {PlaceRead}
28
+ */
29
+ export function readPlace(rule: PlaceRule, text: string): PlaceRead;
30
+ /**
31
+ * Fit a place rule to a fact's own words, by CODE, at drafting. The words must be exactly one version (X.Y.Z) or exactly one ISO date; the frozen
32
+ * candidates are walked in order, and the first whose strict first-heading read on the input's own text returns exactly those words wins. Null =
33
+ * no fit (a version and a date together, any other words, another date form, a mixed-level file, no text, or no candidate reading them): the caller
34
+ * refuses the words as week-only exactly as before. Only the two kinds are handled. Pure.
35
+ * @param {string} words @param {string|null|undefined} text
36
+ * @returns {PlaceRule|null}
37
+ */
38
+ export function fitPlaceRule(words: string, text: string | null | undefined): PlaceRule | null;
39
+ /**
40
+ * STRIP (P1b, hamr 2026-11-11): the words of a phrase fact that are a piece of the newest release heading ("## [0.54.1]", "[0.54.1] -", "0.54.1",
41
+ * "2026-11-04", "## [0.54.1] - 2026-11-04") are stripped by code to their value(s). The words hold exactly one version (X.Y.Z, an optional leading v) and/or
42
+ * exactly one ISO date and nothing else but heading marks; each value is fitted with {@link fitPlaceRule} on the input's own text, and when both are
43
+ * present both must sit on the SAME first release heading line. Returns the values (version first) each with its rule, or null: two versions, two dates,
44
+ * any other word, another date form, a value that is not at the first release heading, no text. Pure.
45
+ * @param {string} words @param {string|null|undefined} text
46
+ * @returns {{kind: 'version'|'date', value: string, rule: PlaceRule}[]|null}
47
+ */
48
+ export function fitPlacePhrase(words: string, text: string | null | undefined): {
49
+ kind: "version" | "date";
50
+ value: string;
51
+ rule: PlaceRule;
52
+ }[] | null;
53
+ /**
54
+ * @typedef {{key: string, name: string, source: string, stage: number, part: number, fact: number, place: PlaceRule, phrase: string}} PlaceFact
55
+ */
56
+ /**
57
+ * Every place-rule fact of a spec, in stage / part / fact order. The key is the stage's name and the fact's name (both stable across the runs of one
58
+ * workflow), so an earlier run's record finds the same fact. Pure.
59
+ * @param {any} spec @returns {PlaceFact[]}
60
+ */
61
+ export function placeFactsOf(spec: any): PlaceFact[];
62
+ /**
63
+ * A copy of the spec with each place fact's phrase replaced by the value the run read. The input spec is never touched (the signed spec and its hash
64
+ * stay as signed); the copy is for this run's planner and close only. A key with no value is left as the signed drafting words.
65
+ * @param {any} spec @param {Record<string, string>} values place-fact key to the value read @returns {any}
66
+ */
67
+ export function bindPlaceValues(spec: any, values: Record<string, string>): any;
68
+ /**
69
+ * The value the drafting words themselves hold for this rule: the first version for headingBetween, the first ISO date for headingDateAfter. Null when
70
+ * the words hold none. Used as "last read" when no earlier run has one.
71
+ * @param {PlaceRule} rule @param {string} words @returns {string|null}
72
+ */
73
+ export function valueInWords(rule: PlaceRule, words: string): string | null;
74
+ /**
75
+ * Re-read EVERY place fact against the run's own input text, one by one, before any spend. A row is same / new / notfound. Any notfound stops the run;
76
+ * otherwise the run proceeds with the new words.
77
+ * @param {{fact: PlaceFact, text: string|null, was: string|null}[]} items `text` null = the input could not be read
78
+ * @returns {{proceed: boolean, rows: {key: string, name: string, kind: string, found: boolean, value: string|null, was: string|null, reason: string|null}[], values: Record<string, string>}}
79
+ */
80
+ export function readPlaceRules(items: {
81
+ fact: PlaceFact;
82
+ text: string | null;
83
+ was: string | null;
84
+ }[]): {
85
+ proceed: boolean;
86
+ rows: {
87
+ key: string;
88
+ name: string;
89
+ kind: string;
90
+ found: boolean;
91
+ value: string | null;
92
+ was: string | null;
93
+ reason: string | null;
94
+ }[];
95
+ values: Record<string, string>;
96
+ };
97
+ /**
98
+ * The words of the $0 stop, plain words from code. Every rule is listed, found or not: "<name>: found <value>" (with "(was <last>)" when the value is
99
+ * new) or "<name>: not found (<plain reason>)", then the closing line. The reasons come only from the closed list.
100
+ * @param {{name: string, found: boolean, value: string|null, was: string|null, reason: string|null}[]} rows @returns {string}
101
+ */
102
+ export function stopWords(rows: {
103
+ name: string;
104
+ found: boolean;
105
+ value: string | null;
106
+ was: string | null;
107
+ reason: string | null;
108
+ }[]): string;
109
+ /**
110
+ * The values of the LAST `place-rules` record in a run's own events (key to value): what a RESUME of that run rebinds, since a resume does not re-read. Null when
111
+ * there is no record, or any of its rows was not found.
112
+ * @param {any[]} events @returns {Record<string, string>|null}
113
+ */
114
+ export function placeValuesOfEvents(events: any[]): Record<string, string> | null;
115
+ /**
116
+ * What the newest EARLIER run of the same workflow read, per fact key: "last read". `rows` are the run list's rows (file order, oldest first). Candidates are
117
+ * the rows of the same job, newest first, at most {@link LAST_READ_LOOK} of them; the first whose spine holds a `place-rules` record of the same workflow key
118
+ * answers. An unreadable spine is skipped. Empty when there is none (the caller falls back to the drafting words).
119
+ * @param {{rows: {runid: string, job: string, spine: string}[], job: string, workflowKey: string, runid: string}} o @returns {Record<string, string>}
120
+ */
121
+ export function lastPlaceRead({ rows, job, workflowKey, runid }: {
122
+ rows: {
123
+ runid: string;
124
+ job: string;
125
+ spine: string;
126
+ }[];
127
+ job: string;
128
+ workflowKey: string;
129
+ runid: string;
130
+ }): Record<string, string>;
131
+ /**
132
+ * The Audit lines of a run's `place-rules` record, in plain words from code: "<name>: <value>" (with "(was <last>)" when the value is new) or
133
+ * "<name>: not found (<reason>)". Null when the run has no record.
134
+ * @param {any[]} events @returns {string[]|null}
135
+ */
136
+ export function placeRuleLines(events: any[]): string[] | null;
137
+ /** the two rule kinds on the menu: the version in a heading, and the date on the same heading line */
138
+ export const PLACE_KINDS: readonly string[];
139
+ /** the end-of-line end mark */
140
+ export const EOL: "$EOL";
141
+ /** the field a place rule may carry */
142
+ export const PLACE_FIELDS: readonly string[];
143
+ /** the closed list of reasons a read can end not found */
144
+ export const PLACE_REASONS: readonly string[];
145
+ /** plain words for each reason, from code (the person never reads a raw code) */
146
+ export const PLAIN_REASONS: Readonly<{
147
+ 'mixed-levels': "the file writes its version headings at more than one level";
148
+ 'no-heading-line': "the file has no heading at the level the rule reads";
149
+ 'first-heading-mismatch': "the newest heading does not start the way the rule says";
150
+ 'end-mark-missing': "the newest heading does not have the mark the rule reads up to";
151
+ 'capture-not-shape': "the newest heading does not carry a version number";
152
+ 'only-skipped-headings': "the file has only an Unreleased heading and no release after it";
153
+ 'no-date-on-line': "the newest heading line carries no date";
154
+ 'no-file': "the input could not be read";
155
+ 'empty-text': "the input is empty";
156
+ }>;
157
+ /** the frozen candidate list: 9 prefixes crossed with 3 ends, prefix-major (27) */
158
+ export const PLACE_CANDIDATES: readonly Readonly<{
159
+ prefix: string;
160
+ end: string;
161
+ }>[];
162
+ /** the end of the stop words: what the person can do, and that nothing ran or was spent */
163
+ export const STOP_TAIL: "Reuse workflow and adjust the rules, or check the input. The run did not start. Nothing spent.";
164
+ /** the plain words of the door's refusal when a place-rule run has no record of the values it read */
165
+ export const NO_PLACE_RECORD_WORDS: "This run has no record of the values it read, so it cannot be checked again. Use Reuse workflow.";
166
+ /** the spine event a run writes, once, after job-start */
167
+ export const PLACE_EVENT: "place-rules";
168
+ /** how many earlier runs of the job are looked at for "last read" */
169
+ export const LAST_READ_LOOK: 25;
170
+ export type PlaceRule = {
171
+ kind: "headingBetween" | "headingDateAfter";
172
+ prefix: string;
173
+ end: string;
174
+ shape: string;
175
+ skip: string[];
176
+ };
177
+ export type PlaceRead = {
178
+ found: true;
179
+ value: string;
180
+ lineIndex: number;
181
+ } | {
182
+ found: false;
183
+ reason: string;
184
+ };
185
+ export type PlaceFact = {
186
+ key: string;
187
+ name: string;
188
+ source: string;
189
+ stage: number;
190
+ part: number;
191
+ fact: number;
192
+ place: PlaceRule;
193
+ phrase: string;
194
+ };