@moo.md/hum 0.1.0 → 0.2.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 (108) hide show
  1. package/package.json +2 -2
  2. package/scripts/eval.ts +88 -50
  3. package/src/adapter-api.ts +46 -14
  4. package/src/adapters/admit.ts +2 -2
  5. package/src/adapters/argument.ts +1 -1
  6. package/src/adapters/claim.ts +18 -15
  7. package/src/adapters/claude-bg.ts +50 -27
  8. package/src/adapters/claude-p.ts +18 -23
  9. package/src/adapters/contract.ts +22 -10
  10. package/src/adapters/each-call.ts +9 -0
  11. package/src/adapters/fake.ts +6 -6
  12. package/src/adapters/git.ts +10 -18
  13. package/src/adapters/github-client.ts +102 -0
  14. package/src/adapters/github.ts +34 -142
  15. package/src/adapters/guard.ts +20 -9
  16. package/src/adapters/history.ts +12 -15
  17. package/src/adapters/item-file.ts +1 -1
  18. package/src/adapters/markdown.ts +49 -42
  19. package/src/adapters/marked.ts +6 -12
  20. package/src/adapters/model-call.ts +4 -4
  21. package/src/adapters/once.ts +5 -5
  22. package/src/adapters/owner-commit.ts +13 -11
  23. package/src/adapters/pull-requests.ts +11 -13
  24. package/src/adapters/registry.ts +7 -7
  25. package/src/adapters/roundup.ts +27 -35
  26. package/src/adapters/serial.ts +4 -5
  27. package/src/adapters/transcript.ts +13 -8
  28. package/src/cli/main.ts +1 -0
  29. package/src/cli/ops.ts +32 -14
  30. package/src/cli/service.ts +14 -8
  31. package/src/cli/setup.ts +8 -3
  32. package/src/cli/shared-watch.ts +3 -3
  33. package/src/config/checks.ts +14 -18
  34. package/src/config/machine.ts +5 -7
  35. package/src/config/refusal.ts +7 -0
  36. package/src/config/schema.ts +7 -7
  37. package/src/config/settings.ts +17 -2
  38. package/src/config/state-map.ts +5 -3
  39. package/src/decide/alignment.ts +4 -4
  40. package/src/decide/answer.ts +24 -22
  41. package/src/decide/kind.ts +1 -6
  42. package/src/decide/labels.ts +9 -9
  43. package/src/decide/merge.ts +6 -7
  44. package/src/decide/prose.ts +4 -4
  45. package/src/decide/question.ts +23 -20
  46. package/src/decide/review.ts +4 -2
  47. package/src/decide/risk.ts +25 -19
  48. package/src/decide/taste.ts +3 -3
  49. package/src/exec.ts +4 -3
  50. package/src/index.ts +14 -13
  51. package/src/loop/check-item.ts +3 -3
  52. package/src/loop/ci.ts +1 -1
  53. package/src/loop/github.ts +2 -2
  54. package/src/loop/groups.ts +13 -6
  55. package/src/loop/memory.ts +40 -28
  56. package/src/loop/notes.ts +5 -5
  57. package/src/loop/pair.ts +1 -1
  58. package/src/loop/pass.ts +18 -12
  59. package/src/loop/proof.ts +9 -7
  60. package/src/loop/prove-item.ts +1 -1
  61. package/src/loop/records.ts +12 -13
  62. package/src/loop/signals.ts +6 -6
  63. package/src/measure/inputs.ts +1 -1
  64. package/src/measure/measure.ts +4 -4
  65. package/src/measure/rate.ts +2 -0
  66. package/src/service/ci-tick.ts +2 -2
  67. package/src/service/supervise.ts +3 -2
  68. package/src/service/token.ts +3 -3
  69. package/src/service/wake.ts +2 -2
  70. package/src/service/workflows.ts +2 -2
  71. package/src/setup/propose.ts +4 -4
  72. package/src/setup/prove.ts +18 -12
  73. package/src/setup/scan.ts +31 -24
  74. package/src/setup/shipped.ts +8 -2
  75. package/src/setup/tables.ts +4 -3
  76. package/src/setup/waits.ts +9 -11
  77. package/src/setup/write.ts +17 -10
  78. package/src/slots/pool.ts +32 -24
  79. package/src/state/events.ts +1 -1
  80. package/src/state/faults.ts +13 -5
  81. package/src/state/format.ts +2 -2
  82. package/src/state/items.ts +9 -10
  83. package/src/state/open.ts +2 -2
  84. package/src/state/ops.ts +16 -10
  85. package/src/state/records.ts +5 -5
  86. package/src/state/runs.ts +33 -26
  87. package/src/state/saved.ts +44 -32
  88. package/src/status/file.ts +20 -1
  89. package/src/status/format.ts +47 -57
  90. package/src/status/sections.ts +2 -2
  91. package/src/worker/alignment-report.ts +4 -5
  92. package/src/worker/answers.ts +26 -24
  93. package/src/worker/base-check.ts +2 -2
  94. package/src/worker/kind.ts +23 -19
  95. package/src/worker/land.ts +114 -126
  96. package/src/worker/merged.ts +9 -7
  97. package/src/worker/open.ts +14 -12
  98. package/src/worker/prose-run.ts +3 -3
  99. package/src/worker/questions.ts +15 -12
  100. package/src/worker/scheduler.ts +4 -4
  101. package/src/worker/signature.ts +3 -3
  102. package/src/worker/tally.ts +0 -2
  103. package/src/worker/taste.ts +6 -15
  104. package/src/worker/thin-path.ts +148 -121
  105. package/src/worker/thread.ts +25 -0
  106. package/src/worker/worker.ts +77 -47
  107. package/surface.json +632 -2197
  108. package/src/slots/scan.ts +0 -26
package/src/slots/pool.ts CHANGED
@@ -6,7 +6,7 @@ import { hashJson } from "../config/hash.ts";
6
6
  import type { HumConfig } from "../config/schema.ts";
7
7
  import { commandTimeoutMs } from "../exec.ts";
8
8
  import type { State } from "../state/open.ts";
9
- import type { Slot } from "../state/saved.ts";
9
+ import type { FreeSlot, HeldSlot, Slot } from "../state/saved.ts";
10
10
  import { SECOND_MS } from "../time.ts";
11
11
  import { runChecks } from "../worker/checks.ts";
12
12
  import type { Checkedout, Checkout } from "../worker/thin-path.ts";
@@ -31,7 +31,7 @@ export type PoolOptions = {
31
31
  readonly base: string;
32
32
  /** The names of the runs alive outside this process; a taken slot whose item has none of them is returned. */
33
33
  readonly liveRuns?: () => Promise<ReadonlySet<string>>;
34
- readonly now?: () => number;
34
+ readonly now: () => number;
35
35
  };
36
36
 
37
37
  const nextChange = (changes: EventTarget, signal: AbortSignal | undefined): Promise<void> =>
@@ -50,7 +50,10 @@ const nextChange = (changes: EventTarget, signal: AbortSignal | undefined): Prom
50
50
  signal?.addEventListener("abort", aborted, { once: true });
51
51
  });
52
52
 
53
- const isHeld = ({ status }: Slot): boolean => status === "taken" || status === "kept";
53
+ const isHeld = (slot: Slot): slot is HeldSlot => slot.status === "taken" || slot.status === "kept";
54
+
55
+ /** The slot with no item, at a free status. */
56
+ const freed = ({ name, index, folder, lockfiles, since }: Slot, status: FreeSlot["status"]): FreeSlot => ({ name, index, folder, lockfiles, status, since });
54
57
 
55
58
  /**
56
59
  * The run slots: git worktrees of the owner's checkout, kept prepared so a run starts in one at once. A slot serves
@@ -69,7 +72,7 @@ export class SlotPool {
69
72
 
70
73
  constructor(options: PoolOptions) {
71
74
  this.#o = options;
72
- this.#now = options.now ?? Date.now;
75
+ this.#now = options.now;
73
76
  }
74
77
 
75
78
  get #settings(): HumConfig["runSlots"] {
@@ -83,10 +86,10 @@ export class SlotPool {
83
86
  .sort((a, b) => a.index - b.index);
84
87
  }
85
88
 
86
- #save(slot: Slot, patch: Partial<Slot>): Slot {
87
- const saved = { ...slot, ...patch, since: this.#now() };
89
+ #save<S extends Slot>(next: S): S {
90
+ const saved = { ...next, since: this.#now() };
88
91
 
89
- this.#o.state.slots.put(slot.name, saved);
92
+ this.#o.state.slots.put(saved.name, saved);
90
93
  this.#changes.dispatchEvent(new Event(CHANGE));
91
94
 
92
95
  return saved;
@@ -111,13 +114,13 @@ export class SlotPool {
111
114
  }
112
115
 
113
116
  #out(slot: Slot, cause: string, fix: string): void {
114
- this.#save(slot, { status: "out", item: undefined });
117
+ this.#save(freed(slot, "out"));
115
118
  this.#o.state.faults.raise({ code: SLOT_OUT_CODE, item: slot.name, cause: `${slot.name} (${slot.folder}) left the pool: ${cause}`.slice(0, CARD_OUTPUT), fix });
116
119
  }
117
120
 
118
121
  #ready(slot: Slot, lockfiles: string): void {
119
- this.#o.state.faults.clear(`${SLOT_OUT_CODE}:${slot.name}`);
120
- this.#save(slot, { status: "free", item: undefined, lockfiles });
122
+ this.#o.state.faults.clear({ code: SLOT_OUT_CODE, item: slot.name });
123
+ this.#save({ ...freed(slot, "free"), lockfiles });
121
124
  }
122
125
 
123
126
  /** Makes the slot's worktree if it is not there, runs the recipe's prepare and ready; a failure takes the slot out. */
@@ -167,8 +170,8 @@ export class SlotPool {
167
170
  await this.#check(slot, this.#settings.recipe.ready, lockfiles);
168
171
  }
169
172
 
170
- #keep(slot: Slot, cause: string, fix: string): void {
171
- this.#save(slot, { status: "kept" });
173
+ #keep(slot: HeldSlot, cause: string, fix: string): void {
174
+ this.#save({ ...slot, status: "kept" });
172
175
  this.#o.state.faults.raise({ code: SLOT_KEPT_CODE, item: slot.name, cause: `${slot.name} (${slot.folder}) stays taken: ${cause}`.slice(0, CARD_OUTPUT), fix });
173
176
  }
174
177
 
@@ -176,7 +179,7 @@ export class SlotPool {
176
179
  * Returns the slot to the pool once its branch holds no commit the remote lacks: resets it, detaches it at the base
177
180
  * and deletes the run's branch. A slot that cannot be returned stays taken with one card, and its commits are left alone.
178
181
  */
179
- async #give(slot: Slot): Promise<void> {
182
+ async #give(slot: HeldSlot): Promise<void> {
180
183
  if (this.#returning.has(slot.name)) return;
181
184
 
182
185
  this.#returning.add(slot.name);
@@ -198,8 +201,8 @@ export class SlotPool {
198
201
 
199
202
  if (branch) await git.raw(["branch", "-q", "-D", branch]);
200
203
 
201
- this.#o.state.faults.clear(`${SLOT_KEPT_CODE}:${slot.name}`);
202
- this.#save(slot, { status: "stale", item: undefined });
204
+ this.#o.state.faults.clear({ code: SLOT_KEPT_CODE, item: slot.name });
205
+ this.#save(freed(slot, "stale"));
203
206
  } catch (error) {
204
207
  this.#keep(slot, `it could not be returned: ${error instanceof Error ? error.message : String(error)}`, "Fix what git reports in the slot; hum returns the slot at its next tick.");
205
208
  } finally {
@@ -211,14 +214,14 @@ export class SlotPool {
211
214
 
212
215
  /** A taken slot with no pass in this process and no run alive for its item is returned. A run alive for it is adopted. */
213
216
  async #reclaim(): Promise<void> {
214
- const orphans = this.#slots().filter((slot) => isHeld(slot) && !this.#active.has(slot.name) && !this.#returning.has(slot.name));
217
+ const orphans = this.#slots().filter(isHeld).filter((slot) => !this.#active.has(slot.name) && !this.#returning.has(slot.name));
215
218
 
216
219
  if (orphans.length === 0) return;
217
220
 
218
221
  const alive = (await this.#o.liveRuns?.()) ?? new Set<string>();
219
222
 
220
223
  for (const slot of orphans) {
221
- const adopted = slot.item !== undefined && this.#o.state.runs.list(slot.item).some(({ name, endedAt }) => endedAt === undefined && alive.has(name));
224
+ const adopted = this.#o.state.runs.list(slot.item).some(({ name, endedAt }) => endedAt === undefined && alive.has(name));
222
225
 
223
226
  if (!adopted) await this.#give(slot);
224
227
  }
@@ -241,14 +244,14 @@ export class SlotPool {
241
244
  for (let index = 0; index < config.runners; index++) {
242
245
  const name = slotName(index);
243
246
 
244
- if (!state.slots.get(name)) this.#save({ name, index, folder: slotFolder(this.#o.repo, this.#settings.pool, name), status: "new", since: 0 }, {});
247
+ if (!state.slots.get(name)) this.#save({ name, index, folder: slotFolder(this.#o.repo, this.#settings.pool, name), status: "new", since: 0 });
245
248
  }
246
249
 
247
250
  for (const listed of this.#slots()) {
248
- const slot = recheck && listed.status === "out" ? this.#save(listed, { status: "new" }) : listed;
251
+ const slot = recheck && listed.status === "out" ? this.#save(freed(listed, "new")) : listed;
249
252
 
250
253
  await this.#settle(slot).then(
251
- () => state.faults.clear(`${SLOT_MAINTENANCE_CODE}:${slot.name}`),
254
+ () => state.faults.clear({ code: SLOT_MAINTENANCE_CODE, item: slot.name }),
252
255
  (error: Error) => this.#maintenanceFailed(slot.name, error),
253
256
  );
254
257
  }
@@ -279,29 +282,34 @@ export class SlotPool {
279
282
  }
280
283
 
281
284
  /** The slot for the item's pass: the one that already holds the item, else the first free one, waiting for a return when none is. */
282
- async #take(request: Parameters<Checkout>[0]): Promise<{ readonly slot: Slot; readonly held: boolean }> {
285
+ async #take(request: Parameters<Checkout>[0]): Promise<{ readonly slot: HeldSlot; readonly held: boolean }> {
283
286
  const { signal, item } = request;
284
287
 
285
288
  for (;;) {
286
289
  signal?.throwIfAborted();
287
290
 
288
291
  const slots = this.#slots();
289
- const held = slots.find((slot) => isHeld(slot) && slot.item === item && !this.#returning.has(slot.name));
292
+ const held = slots.filter(isHeld).find((slot) => slot.item === item && !this.#returning.has(slot.name));
290
293
  const taking = held ?? slots.find(({ status }) => status === "free");
291
294
 
292
295
  if (taking) {
293
296
  this.#active.set(taking.name, item);
294
297
 
295
- return held ? { slot: held, held: true } : { slot: this.#save(taking, { status: "taken", item }), held: false };
298
+ return held ? { slot: held, held: true } : { slot: this.#save({ ...freed(taking, "free"), status: "taken", item }), held: false };
296
299
  }
297
300
 
298
- if (slots.length === this.#o.config.runners && slots.every(({ status }) => status === "out")) throw new Error(`every run slot is out of the pool: ${this.#o.state.faults.list().filter(({ code }) => code === SLOT_OUT_CODE).map(({ cause }) => cause).join("; ")}`);
301
+ if (this.#isAllOut(slots)) throw new Error(`every run slot is out of the pool: ${this.#o.state.faults.list().filter(({ code }) => code === SLOT_OUT_CODE).map(({ cause }) => cause).join("; ")}`);
299
302
 
300
303
  this.keepReady();
301
304
  await nextChange(this.#changes, signal);
302
305
  }
303
306
  }
304
307
 
308
+ /** Whether every slot the pool runs is out, so no run can take one until the owner acts. */
309
+ #isAllOut(slots: readonly Slot[]): boolean {
310
+ return slots.length === this.#o.config.runners && slots.every(({ status }) => status === "out");
311
+ }
312
+
305
313
  /** The seam a thin-path pass takes its working copy from: a slot, at the latest base, with its own ports and database. */
306
314
  readonly checkout: Checkout = async (request): Promise<Checkedout> => {
307
315
  const { repo, base } = this.#o;
@@ -3,7 +3,7 @@ import { z } from "zod";
3
3
  import { Json } from "../config/json.ts";
4
4
  import { createOnce, listRecords, readJson, slug } from "./fs.ts";
5
5
 
6
- export const SavedEvent = z.strictObject({
6
+ export const SavedEvent = z.object({
7
7
  /** Where the event came from, such as a thread comment id: a second read of it adds nothing. */
8
8
  source: z.string().min(1),
9
9
  sourceId: z.string().min(1),
@@ -12,7 +12,13 @@ export type FaultInput = {
12
12
  readonly action?: Card["action"];
13
13
  };
14
14
 
15
- export type Outcome<T> = { readonly ok: true; readonly value: T } | { readonly ok: false; readonly fault: Card };
15
+ export type Outcome<T> = { readonly ok: true; readonly value: T } | { readonly ok: false; readonly fault: Readonly<Card> };
16
+
17
+ /** What names one card: its cause, and the item or provider it is about. */
18
+ export type FaultKey = Pick<FaultInput, "code" | "item">;
19
+
20
+ /** One card per cause and item. A card file is named by this key, so a change orphans every card on disk. */
21
+ const faultKey = ({ code, item }: FaultKey): string => (item === undefined ? code : `${code}:${item}`);
16
22
 
17
23
  /** The fault cards currently raised. One card per cause, kept in memory and, when the disk allows, on it. */
18
24
  export class Faults {
@@ -43,8 +49,8 @@ export class Faults {
43
49
  * Raises the card, or returns the one already raised for this cause. A card that cannot be
44
50
  * written because the disk is full still stands in memory, and the caller puts it in the status file.
45
51
  */
46
- raise({ code, item, cause, fix, action }: FaultInput): Card {
47
- const key = item === undefined ? code : `${code}:${item}`;
52
+ raise({ code, item, cause, fix, action }: FaultInput): Readonly<Card> {
53
+ const key = faultKey({ code, item });
48
54
  const raised = this.#cards.get(key);
49
55
 
50
56
  if (raised) return raised;
@@ -63,11 +69,13 @@ export class Faults {
63
69
  }
64
70
 
65
71
  /** Removes the card once its cause is gone. */
66
- clear(key: string): void {
72
+ clear(fault: FaultKey): void {
73
+ const key = faultKey(fault);
74
+
67
75
  if (this.#cards.delete(key)) rmSync(this.#path(key), { force: true });
68
76
  }
69
77
 
70
- list(): Card[] {
78
+ list(): Readonly<Card>[] {
71
79
  return [...this.#cards.values()].sort((a, b) => a.since - b.since || (a.key < b.key ? -1 : 1));
72
80
  }
73
81
  }
@@ -14,7 +14,7 @@ export const ENVELOPE_FORMAT = 1;
14
14
  export const Header = z.looseObject({ format: z.int().nonnegative(), engineVersion: z.string().min(1) });
15
15
 
16
16
  /** One saved item: the machine's persisted snapshot and what is needed to restore it later. */
17
- export const Envelope = z.strictObject({
17
+ export const Envelope = z.object({
18
18
  format: z.literal(ENVELOPE_FORMAT),
19
19
  engineVersion: z.string().min(1),
20
20
  itemId: z.string().min(1),
@@ -38,7 +38,7 @@ export type EnvelopeMigrations = Steps<EnvelopeJson>;
38
38
  export const ENVELOPE_MIGRATIONS: EnvelopeMigrations = {};
39
39
 
40
40
  /** True when a file was written by an engine newer than the running one, or by one whose version is unreadable. */
41
- export const isFromNewerEngine = (written: string, running: string): boolean => semver.valid(written) === null || semver.gt(written, running);
41
+ export const isFromNewerEngine = ({ written, running }: { readonly written: string; readonly running: string }): boolean => semver.valid(written) === null || semver.gt(written, running);
42
42
 
43
43
  /** The part of an envelope that names the item and its machine, enough to list what is saved without restoring it. */
44
44
  export const SavedHeader = z.looseObject({
@@ -78,7 +78,6 @@ export class Items {
78
78
 
79
79
  /** A failed write leaves the old snapshot and raises one card. */
80
80
  save(itemId: string, kind: Kind, snapshot: Json): Outcome<void> {
81
- const key = `snapshot-write-failed:${itemId}`;
82
81
  const envelope = { format: this.#format, engineVersion: this.#engineVersion, itemId, kind: kind.machine.id, machineVersion: kind.machine.version, savedAt: this.#now(), snapshot };
83
82
 
84
83
  try {
@@ -95,7 +94,7 @@ export class Items {
95
94
  };
96
95
  }
97
96
 
98
- this.#faults.clear(key);
97
+ this.#faults.clear({ code: "snapshot-write-failed", item: itemId });
99
98
 
100
99
  return { ok: true, value: undefined };
101
100
  }
@@ -122,7 +121,7 @@ export class Items {
122
121
  rmSync(this.path(itemId), { force: true });
123
122
  }
124
123
 
125
- #fault(itemId: string, code: string, cause: string, fix: string): Outcome<never> {
124
+ #fault({ itemId, code, cause, fix }: { readonly itemId: string; readonly code: string; readonly cause: string; readonly fix: string }): Outcome<never> {
126
125
  return { ok: false, fault: this.#faults.raise({ code, item: itemId, cause, fix }) };
127
126
  }
128
127
 
@@ -132,8 +131,8 @@ export class Items {
132
131
  */
133
132
  async restore(itemId: string, kind: Kind, { kindAt, sources = {}, clock }: RestoreOptions = {}): Promise<Outcome<AnyActor | undefined>> {
134
133
  const file = this.path(itemId);
135
- const unreadable = (why: string) => this.#fault(itemId, "snapshot-unreadable", `The saved state of ${itemId} at ${file} is damaged: ${why}.`, DAMAGED_FIX);
136
- const unrestorable = (why: string) => this.#fault(itemId, "snapshot-restore-error", `The saved state of ${itemId} does not restore: ${why}.`, DAMAGED_FIX);
134
+ const unreadable = (why: string) => this.#fault({ itemId, code: "snapshot-unreadable", cause: `The saved state of ${itemId} at ${file} is damaged: ${why}.`, fix: DAMAGED_FIX });
135
+ const unrestorable = (why: string) => this.#fault({ itemId, code: "snapshot-restore-error", cause: `The saved state of ${itemId} does not restore: ${why}.`, fix: DAMAGED_FIX });
137
136
  let parsed: Json;
138
137
 
139
138
  try {
@@ -143,15 +142,15 @@ export class Items {
143
142
 
144
143
  if (error instanceof SyntaxError) return unreadable(error.message);
145
144
 
146
- return this.#fault(itemId, "snapshot-unreadable", `The saved state of ${itemId} at ${file} cannot be read: ${reason(error)}.`, "Fix the file's permissions or restore it from a backup; the other items go on.");
145
+ return this.#fault({ itemId, code: "snapshot-unreadable", cause: `The saved state of ${itemId} at ${file} cannot be read: ${reason(error)}.`, fix: "Fix the file's permissions or restore it from a backup; the other items go on." });
147
146
  }
148
147
 
149
148
  const header = Header.safeParse(parsed);
150
149
 
151
150
  if (!header.success) return unreadable("it has no format or engine version");
152
151
 
153
- if (header.data.format > this.#format || isFromNewerEngine(header.data.engineVersion, this.#engineVersion)) {
154
- return this.#fault(itemId, "snapshot-from-newer-engine", `The saved state of ${itemId} was written by hum ${header.data.engineVersion}, which is newer than the running ${this.#engineVersion}.`, "Update the engine to that version or later: bun add --exact @moo.md/hum@latest.");
152
+ if (header.data.format > this.#format || isFromNewerEngine({ written: header.data.engineVersion, running: this.#engineVersion })) {
153
+ return this.#fault({ itemId, code: "snapshot-from-newer-engine", cause: `The saved state of ${itemId} was written by hum ${header.data.engineVersion}, which is newer than the running ${this.#engineVersion}.`, fix: "Update the engine to that version or later: bun add --exact @moo.md/hum@latest." });
155
154
  }
156
155
 
157
156
  let envelope: ReturnType<typeof Envelope.safeParse>;
@@ -172,12 +171,12 @@ export class Items {
172
171
  const previous = kindAt?.(machineVersion);
173
172
 
174
173
  if (!previous) {
175
- return this.#fault(itemId, "snapshot-machine-unknown", `${itemId} was saved under version ${machineVersion} of its machine, and this config holds no map from it.`, "Add a stateMap for that version to the kind file, or delete the item's saved state.");
174
+ return this.#fault({ itemId, code: "snapshot-machine-unknown", cause: `${itemId} was saved under version ${machineVersion} of its machine, and this config holds no map from it.`, fix: "Add a stateMap for that version to the kind file, or delete the item's saved state." });
176
175
  }
177
176
 
178
177
  current = await migrateSnapshot(previous, kind, snapshot, sources);
179
178
  } catch (error) {
180
- return this.#fault(itemId, "snapshot-restore-error", `${itemId} could not move from machine version ${machineVersion} to ${kind.machine.version}: ${reason(error)}.`, "Map the state in the kind's stateMap, or delete the item's saved state.");
179
+ return this.#fault({ itemId, code: "snapshot-restore-error", cause: `${itemId} could not move from machine version ${machineVersion} to ${kind.machine.version}: ${reason(error)}.`, fix: "Map the state in the kind's stateMap, or delete the item's saved state." });
181
180
  }
182
181
  }
183
182
 
package/src/state/open.ts CHANGED
@@ -21,10 +21,10 @@ export const defaultStateDir = async (cwd: string): Promise<string> => {
21
21
  return join(resolve(cwd, found.stdout.trim()), "hum");
22
22
  };
23
23
 
24
- export type StateOptions = Codec & { readonly now?: () => number };
24
+ export type StateOptions = Codec & { readonly now: () => number };
25
25
 
26
26
  /** Everything the engine saves between runs, under one folder. */
27
- export const openState = (dir: string, { now = Date.now, ...codec }: StateOptions = {}) => {
27
+ export const openState = (dir: string, { now, ...codec }: StateOptions) => {
28
28
  const faults = new Faults(join(dir, "faults"), now);
29
29
 
30
30
  return {
package/src/state/ops.ts CHANGED
@@ -3,7 +3,7 @@ import { z } from "zod";
3
3
  import { atomicWrite, createOnce, listRecords, orMissing, readJson, slug } from "./fs.ts";
4
4
 
5
5
  /** One external op of one attempt of one run of one item. */
6
- export const OpKey = z.strictObject({
6
+ export const OpKey = z.object({
7
7
  itemId: z.string().min(1),
8
8
  run: z.string().min(1),
9
9
  attempt: z.int().nonnegative(),
@@ -14,12 +14,17 @@ export type OpKey = z.infer<typeof OpKey>;
14
14
 
15
15
  const Record = OpKey.extend({ state: z.enum(["started", "done"]), at: z.int().nonnegative() });
16
16
 
17
- export type OpProvider = {
17
+ export type OpProvider<T> = {
18
18
  /** True when the provider already holds the effect of this op, found by its key. */
19
19
  readonly holds: () => Promise<boolean>;
20
- readonly run: () => Promise<void>;
20
+ readonly run: () => Promise<T>;
21
+ /** Whether the run's value finished the op; an op left unfinished runs again on the next call. Every value finishes it unless this says otherwise. */
22
+ readonly isDone?: (value: T) => boolean;
21
23
  };
22
24
 
25
+ /** `skipped` when the op was done or the provider held it; else the value its run returned. */
26
+ export type OpRun<T> = { readonly kind: "skipped" } | { readonly kind: "ran"; readonly value: T };
27
+
23
28
  /** The key is saved before the op, so a restart after a kill finds the op started and asks the provider before it runs it again. */
24
29
  export class OpKeys {
25
30
  readonly #folder: string;
@@ -53,24 +58,25 @@ export class OpKeys {
53
58
  return orMissing(() => Record.parse(readJson(this.#path(OpKey.parse(key)))).state, undefined);
54
59
  }
55
60
 
56
- /** Runs the op once per key, across restarts: `skipped` when it is done or the provider already holds it. */
57
- async once(key: OpKey, { holds, run }: OpProvider): Promise<"ran" | "skipped"> {
61
+ /** Runs the op once per key, across restarts. */
62
+ async once<T>(key: OpKey, { holds, run, isDone = () => true }: OpProvider<T>): Promise<OpRun<T>> {
58
63
  const checked = OpKey.parse(key);
59
64
  const fresh = this.#write(checked, "started", true);
60
65
 
61
66
  if (!fresh) {
62
- if (this.state(checked) === "done") return "skipped";
67
+ if (this.state(checked) === "done") return { kind: "skipped" };
63
68
 
64
69
  if (await holds()) {
65
70
  this.#write(checked, "done", false);
66
71
 
67
- return "skipped";
72
+ return { kind: "skipped" };
68
73
  }
69
74
  }
70
75
 
71
- await run();
72
- this.#write(checked, "done", false);
76
+ const value = await run();
77
+
78
+ if (isDone(value)) this.#write(checked, "done", false);
73
79
 
74
- return "ran";
80
+ return { kind: "ran", value };
75
81
  }
76
82
  }
@@ -1,10 +1,10 @@
1
1
  import { join } from "node:path";
2
2
  import { rmSync } from "node:fs";
3
- import type { z } from "zod";
3
+ import { z } from "zod";
4
4
  import { atomicWrite, listRecords, orMissing, readJson, slug } from "./fs.ts";
5
5
 
6
6
  /** One JSON file per key under a folder, written whole. The schema checks every read. */
7
- export class Records<S extends z.ZodType> {
7
+ export class Records<S extends z.core.$ZodType> {
8
8
  readonly #folder: string;
9
9
  readonly #schema: S;
10
10
 
@@ -18,11 +18,11 @@ export class Records<S extends z.ZodType> {
18
18
  }
19
19
 
20
20
  get(key: string): z.output<S> | undefined {
21
- return orMissing(() => this.#schema.parse(readJson(this.#path(key))), undefined);
21
+ return orMissing(() => z.parse(this.#schema, readJson(this.#path(key))), undefined);
22
22
  }
23
23
 
24
24
  put(key: string, value: z.input<S>): void {
25
- atomicWrite(this.#path(key), `${JSON.stringify(this.#schema.parse(value))}\n`);
25
+ atomicWrite(this.#path(key), `${JSON.stringify(z.parse(this.#schema, value))}\n`);
26
26
  }
27
27
 
28
28
  remove(key: string): void {
@@ -30,6 +30,6 @@ export class Records<S extends z.ZodType> {
30
30
  }
31
31
 
32
32
  list(): z.output<S>[] {
33
- return listRecords(this.#folder).map((file) => this.#schema.parse(readJson(file)));
33
+ return listRecords(this.#folder).map((file) => z.parse(this.#schema, readJson(file)));
34
34
  }
35
35
  }
package/src/state/runs.ts CHANGED
@@ -2,25 +2,40 @@ import { join } from "node:path";
2
2
  import { z } from "zod";
3
3
  import { atomicWrite, createOnce, listFiles, listRecords, orMissing, readJson, slug } from "./fs.ts";
4
4
 
5
- export const RunKey = z.strictObject({ itemId: z.string().min(1), run: z.string().min(1), attempt: z.int().nonnegative() });
5
+ export const RunKey = z.object({ itemId: z.string().min(1), run: z.string().min(1), attempt: z.int().nonnegative() });
6
6
 
7
7
  export type RunKey = z.infer<typeof RunKey>;
8
8
 
9
- export const RunRecord = RunKey.extend({
9
+ const BegunRecord = RunKey.extend({
10
10
  /** On the Mac the run's name is saved before launch and found by it after a crash. */
11
11
  name: z.string().min(1),
12
12
  /** The Claude session id: set ahead in CI, learned after launch on the Mac. */
13
13
  sessionId: z.string().min(1).optional(),
14
14
  savedAt: z.int().nonnegative(),
15
- /** Set when the run's outcome has been taken; a record without it is a run a restart adopts. */
16
- endedAt: z.int().nonnegative().optional(),
17
- /** The rules of memory.md the run says it applied; absent when the run was shown none. */
18
- memoryUsed: z.array(z.string()).optional(),
19
15
  });
20
16
 
17
+ /** A run whose outcome is not yet taken is one a restart adopts; an ended run carries when it ended and the memory it used. */
18
+ export const RunRecord = z.union([
19
+ BegunRecord.extend({ endedAt: z.undefined().optional() }),
20
+ BegunRecord.extend({
21
+ endedAt: z.int().nonnegative(),
22
+ /** The rules of memory.md the run says it applied; absent when the run was shown none. */
23
+ memoryUsed: z.array(z.string()).optional(),
24
+ }),
25
+ ]);
26
+
21
27
  export type RunRecord = z.infer<typeof RunRecord>;
22
28
 
23
- export type BegunRun = { readonly record: RunRecord; readonly adopted: boolean };
29
+ /** A run saved before its launch, and the two writes that follow it. */
30
+ export type BegunRun = {
31
+ readonly record: RunRecord;
32
+ /** A record was already saved for this key, so the caller adopts that run. */
33
+ readonly adopted: boolean;
34
+ /** Saves the session id once the launch has reported it. */
35
+ readonly saveSession: (sessionId: string) => RunRecord;
36
+ /** Marks the run's outcome as taken, so a restart starts a new attempt and adopts nothing. */
37
+ readonly end: (memoryUsed?: readonly string[]) => RunRecord;
38
+ };
24
39
 
25
40
  /** The run's name, then its session id, saved so a restart adopts the run and never starts it twice. */
26
41
  export class RunRecords {
@@ -41,36 +56,28 @@ export class RunRecords {
41
56
  }
42
57
 
43
58
  /** Saves the run before it launches. When one is already saved for this key, returns it unchanged, so the caller adopts it. */
44
- begin(key: RunKey, name: string, sessionId?: string): BegunRun {
59
+ begin(key: RunKey, { name, sessionId }: { readonly name: string; readonly sessionId?: string }): BegunRun {
45
60
  const record = RunRecord.parse({ ...key, name, sessionId, savedAt: this.#now() });
46
61
  const created = createOnce(this.#path(record), `${JSON.stringify(record)}\n`);
47
62
  const saved = created ? record : this.get(key);
48
63
 
49
64
  if (!saved) throw new Error(`run record for ${key.itemId} ${key.run} #${key.attempt} vanished after it was found`);
50
65
 
51
- return { record: saved, adopted: !created };
52
- }
53
-
54
- /** Saves the session id once the launch has reported it. */
55
- saveSession(key: RunKey, sessionId: string): RunRecord {
56
- const record = this.get(key);
57
-
58
- if (!record) throw new Error(`no saved run for ${key.itemId} ${key.run} #${key.attempt}; call begin before launch`);
59
-
60
- const next = RunRecord.parse({ ...record, sessionId });
61
-
62
- atomicWrite(this.#path(next), `${JSON.stringify(next)}\n`);
63
-
64
- return next;
66
+ return {
67
+ record: saved,
68
+ adopted: !created,
69
+ saveSession: (sessionId) => this.#rewrite(key, { sessionId }),
70
+ end: (memoryUsed) => this.#rewrite(key, { endedAt: this.#now(), memoryUsed: memoryUsed && [...memoryUsed] }),
71
+ };
65
72
  }
66
73
 
67
- /** Marks the run's outcome as taken, so a restart starts a new attempt and adopts nothing. */
68
- end(key: RunKey, memoryUsed?: readonly string[]): RunRecord {
74
+ /** Rewrites a begun run's record. Nothing removes a record, so one gone since `begin` saved it throws. */
75
+ #rewrite(key: RunKey, change: { readonly sessionId?: string; readonly endedAt?: number; readonly memoryUsed?: string[] }): RunRecord {
69
76
  const record = this.get(key);
70
77
 
71
- if (!record) throw new Error(`no saved run for ${key.itemId} ${key.run} #${key.attempt}; call begin before launch`);
78
+ if (!record) throw new Error(`the run record of ${key.itemId} ${key.run} #${key.attempt} is gone since begin saved it`);
72
79
 
73
- const next = RunRecord.parse({ ...record, endedAt: this.#now(), memoryUsed: memoryUsed && [...memoryUsed] });
80
+ const next = RunRecord.parse({ ...record, ...change });
74
81
 
75
82
  atomicWrite(this.#path(next), `${JSON.stringify(next)}\n`);
76
83