@moo.md/hum 0.0.0-stage → 0.1.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 (150) hide show
  1. package/defaults/hum.json +321 -0
  2. package/defaults/kinds/check.json +183 -0
  3. package/defaults/kinds/docs.json +151 -0
  4. package/defaults/kinds/feature.json +202 -0
  5. package/defaults/kinds/fix.json +183 -0
  6. package/defaults/kinds/hotfix.json +164 -0
  7. package/defaults/roles/build.md +3 -0
  8. package/defaults/roles/fix.md +1 -0
  9. package/defaults/roles/plan.md +3 -0
  10. package/defaults/roles/review.md +3 -0
  11. package/evals/alignment/RESULTS.md +8 -0
  12. package/evals/alignment/cases.jsonl +128 -0
  13. package/evals/alignment/sample.jsonl +20 -0
  14. package/evals/kind/RESULTS.md +5 -0
  15. package/evals/kind/cases.jsonl +24 -0
  16. package/evals/plan-outcome/RESULTS.md +4 -0
  17. package/evals/plan-outcome/cases.jsonl +12 -0
  18. package/evals/repeat-pair/RESULTS.md +4 -0
  19. package/evals/repeat-pair/cases.jsonl +51 -0
  20. package/evals/reply-option/RESULTS.md +3 -0
  21. package/evals/reply-option/cases.jsonl +45 -0
  22. package/evals/review-verdict/RESULTS.md +4 -0
  23. package/evals/review-verdict/cases.jsonl +12 -0
  24. package/package.json +88 -4
  25. package/schema/hum.schema.json +1355 -0
  26. package/scripts/eval.ts +244 -0
  27. package/src/adapter-api.ts +134 -0
  28. package/src/adapters/admit.ts +111 -0
  29. package/src/adapters/argument.ts +11 -0
  30. package/src/adapters/claim.ts +93 -0
  31. package/src/adapters/claude-bg.ts +392 -0
  32. package/src/adapters/claude-p.ts +599 -0
  33. package/src/adapters/contract.ts +231 -0
  34. package/src/adapters/fake.ts +157 -0
  35. package/src/adapters/git.ts +156 -0
  36. package/src/adapters/github.ts +479 -0
  37. package/src/adapters/guard.ts +152 -0
  38. package/src/adapters/history.ts +215 -0
  39. package/src/adapters/item-file.ts +102 -0
  40. package/src/adapters/limit.ts +67 -0
  41. package/src/adapters/markdown.ts +365 -0
  42. package/src/adapters/marked.ts +127 -0
  43. package/src/adapters/model-call.ts +75 -0
  44. package/src/adapters/once.ts +45 -0
  45. package/src/adapters/owner-commit.ts +60 -0
  46. package/src/adapters/pull-requests.ts +253 -0
  47. package/src/adapters/registry.ts +156 -0
  48. package/src/adapters/roundup.ts +293 -0
  49. package/src/adapters/serial.ts +22 -0
  50. package/src/adapters/transcript.ts +99 -0
  51. package/src/cli/commands.ts +46 -0
  52. package/src/cli/main.ts +8 -0
  53. package/src/cli/ops.ts +224 -0
  54. package/src/cli/service.ts +156 -0
  55. package/src/cli/setup.ts +141 -0
  56. package/src/cli/shared-watch.ts +127 -0
  57. package/src/config/change.ts +54 -0
  58. package/src/config/checks.ts +217 -0
  59. package/src/config/git-ref-name.d.ts +3 -0
  60. package/src/config/hash.ts +6 -0
  61. package/src/config/json.ts +6 -0
  62. package/src/config/load.ts +88 -0
  63. package/src/config/machine.ts +20 -0
  64. package/src/config/migrate.ts +61 -0
  65. package/src/config/refusal.ts +58 -0
  66. package/src/config/schema.ts +465 -0
  67. package/src/config/settings.ts +6 -0
  68. package/src/config/state-map.ts +76 -0
  69. package/src/decide/alignment.ts +79 -0
  70. package/src/decide/answer.ts +131 -0
  71. package/src/decide/kind.ts +39 -0
  72. package/src/decide/labels.ts +137 -0
  73. package/src/decide/merge.ts +102 -0
  74. package/src/decide/prose.ts +109 -0
  75. package/src/decide/question.ts +159 -0
  76. package/src/decide/review.ts +10 -0
  77. package/src/decide/risk.ts +216 -0
  78. package/src/decide/taste.ts +37 -0
  79. package/src/exec.ts +85 -0
  80. package/src/index.ts +200 -0
  81. package/src/loop/breaks.ts +8 -0
  82. package/src/loop/check-item.ts +76 -0
  83. package/src/loop/ci.ts +8 -0
  84. package/src/loop/github.ts +81 -0
  85. package/src/loop/groups.ts +108 -0
  86. package/src/loop/memory.ts +70 -0
  87. package/src/loop/notes.ts +76 -0
  88. package/src/loop/pair.ts +39 -0
  89. package/src/loop/pass.ts +99 -0
  90. package/src/loop/proof.ts +85 -0
  91. package/src/loop/prove-item.ts +33 -0
  92. package/src/loop/records.ts +75 -0
  93. package/src/loop/signals.ts +130 -0
  94. package/src/measure/inputs.ts +28 -0
  95. package/src/measure/measure.ts +68 -0
  96. package/src/service/cards.ts +24 -0
  97. package/src/service/ci-tick.ts +28 -0
  98. package/src/service/launchd.ts +16 -0
  99. package/src/service/supervise.ts +145 -0
  100. package/src/service/systemd.ts +44 -0
  101. package/src/service/token.ts +21 -0
  102. package/src/service/unit.ts +29 -0
  103. package/src/service/wake.ts +30 -0
  104. package/src/service/workflows.ts +97 -0
  105. package/src/setup/propose.ts +120 -0
  106. package/src/setup/prove.ts +216 -0
  107. package/src/setup/scan.ts +186 -0
  108. package/src/setup/scratch.ts +81 -0
  109. package/src/setup/shipped.ts +15 -0
  110. package/src/setup/tables.ts +101 -0
  111. package/src/setup/waits.ts +58 -0
  112. package/src/setup/write.ts +161 -0
  113. package/src/slots/env.ts +42 -0
  114. package/src/slots/pool.ts +329 -0
  115. package/src/slots/scan.ts +26 -0
  116. package/src/slots/worktree.ts +17 -0
  117. package/src/state/events.ts +52 -0
  118. package/src/state/faults.ts +73 -0
  119. package/src/state/format.ts +50 -0
  120. package/src/state/fs.ts +100 -0
  121. package/src/state/items.ts +195 -0
  122. package/src/state/open.ts +80 -0
  123. package/src/state/ops.ts +76 -0
  124. package/src/state/records.ts +35 -0
  125. package/src/state/runs.ts +99 -0
  126. package/src/state/saved.ts +119 -0
  127. package/src/status/file.ts +49 -0
  128. package/src/status/format.ts +132 -0
  129. package/src/status/sections.ts +14 -0
  130. package/src/status/version.ts +2 -0
  131. package/src/time.ts +7 -0
  132. package/src/worker/alignment-report.ts +18 -0
  133. package/src/worker/answers.ts +153 -0
  134. package/src/worker/base-check.ts +45 -0
  135. package/src/worker/checks.ts +40 -0
  136. package/src/worker/kind.ts +68 -0
  137. package/src/worker/land.ts +509 -0
  138. package/src/worker/lifecycle.ts +97 -0
  139. package/src/worker/merged.ts +29 -0
  140. package/src/worker/open.ts +100 -0
  141. package/src/worker/prose-run.ts +56 -0
  142. package/src/worker/questions.ts +89 -0
  143. package/src/worker/scheduler.ts +135 -0
  144. package/src/worker/signature.ts +41 -0
  145. package/src/worker/tally.ts +25 -0
  146. package/src/worker/taste.ts +38 -0
  147. package/src/worker/thin-path.ts +886 -0
  148. package/src/worker/worker.ts +750 -0
  149. package/surface.json +8787 -0
  150. package/README.md +0 -3
@@ -0,0 +1,195 @@
1
+ import { rmSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { type AnyActor, type AnyActorLogic } from "xstate";
4
+ import { restoreActor } from "xstate/persist";
5
+ import { Json } from "../config/json.ts";
6
+ import { climb } from "../config/migrate.ts";
7
+ import { migrateSnapshot } from "../config/state-map.ts";
8
+ import { kindMachine } from "../config/machine.ts";
9
+ import type { Kind } from "../config/schema.ts";
10
+ import { type Faults, type Outcome } from "./faults.ts";
11
+ import { atomicWrite, isMissing, listRecords, readJson, slug } from "./fs.ts";
12
+ import {
13
+ ENGINE_VERSION,
14
+ Envelope,
15
+ EnvelopeJson,
16
+ ENVELOPE_FORMAT,
17
+ ENVELOPE_MIGRATIONS,
18
+ type EnvelopeMigrations,
19
+ Header,
20
+ isFromNewerEngine,
21
+ SavedHeader,
22
+ } from "./format.ts";
23
+
24
+ type ActorClock = NonNullable<Parameters<typeof restoreActor>[2]>["clock"];
25
+
26
+ /** What the engine writes and reads as the envelope; tests set another to play a different release. */
27
+ export type Codec = {
28
+ readonly engineVersion?: string;
29
+ readonly format?: number;
30
+ readonly migrations?: EnvelopeMigrations;
31
+ };
32
+
33
+ export type RestoreOptions = {
34
+ /** The earlier version of the kind, by machine version, for a snapshot saved under it. */
35
+ readonly kindAt?: (machineVersion: string) => Kind | undefined;
36
+ readonly sources?: Readonly<Record<string, AnyActorLogic>>;
37
+ readonly clock?: ActorClock;
38
+ };
39
+
40
+ /** An item with a saved snapshot, from the envelope header. */
41
+ export type SavedSnapshot = {
42
+ readonly itemId: string;
43
+ readonly kind: string;
44
+ readonly machineVersion: string;
45
+ readonly savedAt: number;
46
+ /** The machine's state, when it is a plain state name. */
47
+ readonly state: string | undefined;
48
+ };
49
+
50
+ /** The snapshot of a running item actor, as the JSON `saveItem` writes. */
51
+ export const persistedSnapshot = (actor: AnyActor): Json => Json.parse(JSON.parse(JSON.stringify(actor.getPersistedSnapshot())));
52
+
53
+ const reason = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
54
+
55
+ const DAMAGED_FIX = "Restore the file from a backup, or delete it to start the item over; the other items go on.";
56
+
57
+ /** Per-item snapshots under `items/`. Every failure becomes one fault card; nothing is thrown for bad data. */
58
+ export class Items {
59
+ readonly #folder: string;
60
+ readonly #faults: Faults;
61
+ readonly #now: () => number;
62
+ readonly #engineVersion: string;
63
+ readonly #format: number;
64
+ readonly #migrations: EnvelopeMigrations;
65
+
66
+ constructor(folder: string, faults: Faults, now: () => number, { engineVersion = ENGINE_VERSION, format = ENVELOPE_FORMAT, migrations = ENVELOPE_MIGRATIONS }: Codec = {}) {
67
+ this.#folder = folder;
68
+ this.#faults = faults;
69
+ this.#now = now;
70
+ this.#engineVersion = engineVersion;
71
+ this.#format = format;
72
+ this.#migrations = migrations;
73
+ }
74
+
75
+ path(itemId: string): string {
76
+ return join(this.#folder, `${slug(itemId)}.json`);
77
+ }
78
+
79
+ /** A failed write leaves the old snapshot and raises one card. */
80
+ save(itemId: string, kind: Kind, snapshot: Json): Outcome<void> {
81
+ const key = `snapshot-write-failed:${itemId}`;
82
+ const envelope = { format: this.#format, engineVersion: this.#engineVersion, itemId, kind: kind.machine.id, machineVersion: kind.machine.version, savedAt: this.#now(), snapshot };
83
+
84
+ try {
85
+ atomicWrite(this.path(itemId), `${JSON.stringify(envelope)}\n`);
86
+ } catch (error) {
87
+ return {
88
+ ok: false,
89
+ fault: this.#faults.raise({
90
+ code: "snapshot-write-failed",
91
+ item: itemId,
92
+ cause: `The state of ${itemId} could not be saved: ${reason(error)}. The last saved state is kept.`,
93
+ fix: "Free disk space where hum keeps its state; the next change saves it again.",
94
+ }),
95
+ };
96
+ }
97
+
98
+ this.#faults.clear(key);
99
+
100
+ return { ok: true, value: undefined };
101
+ }
102
+
103
+ /** The items with a saved snapshot, read from each envelope header. A damaged file is left to `restore`, which raises its card. */
104
+ saved(): SavedSnapshot[] {
105
+ return listRecords(this.#folder).flatMap((file) => {
106
+ try {
107
+ const header = SavedHeader.safeParse(readJson(file));
108
+
109
+ if (!header.success) return [];
110
+
111
+ const { itemId, kind, machineVersion, savedAt, snapshot } = header.data;
112
+
113
+ return [{ itemId, kind, machineVersion, savedAt, state: snapshot.value }];
114
+ } catch {
115
+ return [];
116
+ }
117
+ });
118
+ }
119
+
120
+ /** Removes an item's snapshot once the item has finished. */
121
+ remove(itemId: string): void {
122
+ rmSync(this.path(itemId), { force: true });
123
+ }
124
+
125
+ #fault(itemId: string, code: string, cause: string, fix: string): Outcome<never> {
126
+ return { ok: false, fault: this.#faults.raise({ code, item: itemId, cause, fix }) };
127
+ }
128
+
129
+ /**
130
+ * Reads the item's snapshot and restores its actor, not started. Returns `undefined` when nothing is saved.
131
+ * A snapshot that cannot be restored stays on disk, and the caller starts nothing for that item.
132
+ */
133
+ async restore(itemId: string, kind: Kind, { kindAt, sources = {}, clock }: RestoreOptions = {}): Promise<Outcome<AnyActor | undefined>> {
134
+ 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);
137
+ let parsed: Json;
138
+
139
+ try {
140
+ parsed = readJson(file);
141
+ } catch (error) {
142
+ if (isMissing(error)) return { ok: true, value: undefined };
143
+
144
+ if (error instanceof SyntaxError) return unreadable(error.message);
145
+
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.");
147
+ }
148
+
149
+ const header = Header.safeParse(parsed);
150
+
151
+ if (!header.success) return unreadable("it has no format or engine version");
152
+
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.");
155
+ }
156
+
157
+ let envelope: ReturnType<typeof Envelope.safeParse>;
158
+
159
+ try {
160
+ envelope = Envelope.safeParse(climb(EnvelopeJson.parse(parsed), header.data.format, this.#format, this.#migrations, "format"));
161
+ } catch (error) {
162
+ return unreadable(reason(error));
163
+ }
164
+
165
+ if (!envelope.success) return unreadable(envelope.error.message);
166
+
167
+ const { snapshot, machineVersion } = envelope.data;
168
+ let current = snapshot;
169
+
170
+ if (machineVersion !== kind.machine.version) {
171
+ try {
172
+ const previous = kindAt?.(machineVersion);
173
+
174
+ 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.");
176
+ }
177
+
178
+ current = await migrateSnapshot(previous, kind, snapshot, sources);
179
+ } 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.");
181
+ }
182
+ }
183
+
184
+ try {
185
+ // SAFETY: the snapshot is JSON the machine's own schema validates; xstate reports a bad one as an 'error' status, checked below.
186
+ const restored = current as never;
187
+ const actor = restoreActor(kindMachine(kind, sources), restored, clock ? { clock } : undefined);
188
+ const status = actor.getSnapshot();
189
+
190
+ return status.status === "error" ? unrestorable(reason(status.error)) : { ok: true, value: actor };
191
+ } catch (error) {
192
+ return unrestorable(reason(error));
193
+ }
194
+ }
195
+ }
@@ -0,0 +1,80 @@
1
+ import { join, resolve } from "node:path";
2
+ import { gitIn } from "../adapters/git.ts";
3
+ import { Kind } from "../config/schema.ts";
4
+ import { SHIPPED_COMMAND_TIMEOUT_MS } from "../exec.ts";
5
+ import { EventLog } from "./events.ts";
6
+ import { Faults } from "./faults.ts";
7
+ import { type Codec, Items } from "./items.ts";
8
+ import { Break, Merge, PossibleRepeat, Proof, RepeatGroup, ReviewNote } from "../loop/records.ts";
9
+ import { Choice } from "../status/format.ts";
10
+ import { OpKeys } from "./ops.ts";
11
+ import { Records } from "./records.ts";
12
+ import { RunRecords } from "./runs.ts";
13
+ import { ItemKind, Landing, Learned, Limit, Parked, QueuedQuestion, ReadyList, SavedPlan, SettledAnswer, Slot, Spent, Verdict } from "./saved.ts";
14
+
15
+ /** On the Mac and in a clone, state lives in the repo's git common dir, so every worktree shares it. */
16
+ export const defaultStateDir = async (cwd: string): Promise<string> => {
17
+ const found = await gitIn(cwd, { timeoutMs: SHIPPED_COMMAND_TIMEOUT_MS }).run(["rev-parse", "--git-common-dir"]);
18
+
19
+ if (found.code !== 0) throw new Error(`${cwd} is not inside a git repository: ${found.stderr.trim()}`);
20
+
21
+ return join(resolve(cwd, found.stdout.trim()), "hum");
22
+ };
23
+
24
+ export type StateOptions = Codec & { readonly now?: () => number };
25
+
26
+ /** Everything the engine saves between runs, under one folder. */
27
+ export const openState = (dir: string, { now = Date.now, ...codec }: StateOptions = {}) => {
28
+ const faults = new Faults(join(dir, "faults"), now);
29
+
30
+ return {
31
+ dir,
32
+ /** The one status file for the repo. */
33
+ statusPath: join(dir, "status.json"),
34
+ /** The worker's heartbeat, one file the service unit reads. */
35
+ heartbeatPath: join(dir, "heartbeat.json"),
36
+ /** The answer hook drops one file here per posted answer; its content is the item id. */
37
+ inbox: join(dir, "inbox"),
38
+ /** A background run's Stop hook drops one file here per stop: the run's session id and transcript path. */
39
+ stops: join(dir, "stops"),
40
+ faults,
41
+ items: new Items(join(dir, "items"), faults, now, codec),
42
+ events: new EventLog(join(dir, "events"), now),
43
+ ops: new OpKeys(join(dir, "ops"), now),
44
+ runs: new RunRecords(join(dir, "runs"), now),
45
+ parked: new Records(join(dir, "parked"), Parked),
46
+ spent: new Records(join(dir, "spent"), Spent),
47
+ /** Earlier kinds by `<machine id>@<version>`, for `items.restore`. */
48
+ kinds: new Records(join(dir, "kinds"), Kind),
49
+ limit: new Records(join(dir, "limit"), Limit),
50
+ ready: new Records(join(dir, "ready"), ReadyList),
51
+ /** The run slots, by name. */
52
+ slots: new Records(join(dir, "slots"), Slot),
53
+ landings: new Records(join(dir, "landings"), Landing),
54
+ /** Path rules by glob. */
55
+ learned: new Records(join(dir, "learned"), Learned),
56
+ /** Each item's kind, by item id. */
57
+ itemKinds: new Records(join(dir, "item-kinds"), ItemKind),
58
+ plans: new Records(join(dir, "plans"), SavedPlan),
59
+ verdicts: new Records(join(dir, "verdicts"), Verdict),
60
+ /** Questions by item, waiting for room under the daily cap or asked within the day. */
61
+ questions: new Records(join(dir, "questions"), QueuedQuestion),
62
+ /** Choices made without the owner, by item and time. */
63
+ choices: new Records(join(dir, "choices"), Choice),
64
+ /** Each answer's disposition, by item and ordinal. */
65
+ answers: new Records(join(dir, "answers"), SettledAnswer),
66
+ /** Review notes, by source and source id. */
67
+ notes: new Records(join(dir, "notes"), ReviewNote),
68
+ /** Notes that state one rule, by the key of the first. */
69
+ repeats: new Records(join(dir, "repeats"), RepeatGroup),
70
+ possibleRepeats: new Records(join(dir, "possible-repeats"), PossibleRepeat),
71
+ /** Merged changes, by item. */
72
+ merges: new Records(join(dir, "merges"), Merge),
73
+ /** Tests of the base that failed after a merge, by item. */
74
+ breaks: new Records(join(dir, "breaks"), Break),
75
+ /** What proving a check item cost, by item. */
76
+ proofs: new Records(join(dir, "proofs"), Proof),
77
+ };
78
+ };
79
+
80
+ export type State = ReturnType<typeof openState>;
@@ -0,0 +1,76 @@
1
+ import { join } from "node:path";
2
+ import { z } from "zod";
3
+ import { atomicWrite, createOnce, listRecords, orMissing, readJson, slug } from "./fs.ts";
4
+
5
+ /** One external op of one attempt of one run of one item. */
6
+ export const OpKey = z.strictObject({
7
+ itemId: z.string().min(1),
8
+ run: z.string().min(1),
9
+ attempt: z.int().nonnegative(),
10
+ op: z.string().min(1),
11
+ });
12
+
13
+ export type OpKey = z.infer<typeof OpKey>;
14
+
15
+ const Record = OpKey.extend({ state: z.enum(["started", "done"]), at: z.int().nonnegative() });
16
+
17
+ export type OpProvider = {
18
+ /** True when the provider already holds the effect of this op, found by its key. */
19
+ readonly holds: () => Promise<boolean>;
20
+ readonly run: () => Promise<void>;
21
+ };
22
+
23
+ /** 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
+ export class OpKeys {
25
+ readonly #folder: string;
26
+ readonly #now: () => number;
27
+
28
+ constructor(folder: string, now: () => number) {
29
+ this.#folder = folder;
30
+ this.#now = now;
31
+ }
32
+
33
+ #path(key: OpKey): string {
34
+ return join(this.#folder, `${slug(JSON.stringify([key.itemId, key.run, key.attempt, key.op]))}.json`);
35
+ }
36
+
37
+ #write(key: OpKey, state: "started" | "done", create: boolean): boolean {
38
+ const text = `${JSON.stringify({ ...key, state, at: this.#now() })}\n`;
39
+
40
+ if (create) return createOnce(this.#path(key), text);
41
+
42
+ atomicWrite(this.#path(key), text);
43
+
44
+ return true;
45
+ }
46
+
47
+ /** Every op saved. */
48
+ list(): z.infer<typeof Record>[] {
49
+ return listRecords(this.#folder).map((file) => Record.parse(readJson(file)));
50
+ }
51
+
52
+ state(key: OpKey): "started" | "done" | undefined {
53
+ return orMissing(() => Record.parse(readJson(this.#path(OpKey.parse(key)))).state, undefined);
54
+ }
55
+
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"> {
58
+ const checked = OpKey.parse(key);
59
+ const fresh = this.#write(checked, "started", true);
60
+
61
+ if (!fresh) {
62
+ if (this.state(checked) === "done") return "skipped";
63
+
64
+ if (await holds()) {
65
+ this.#write(checked, "done", false);
66
+
67
+ return "skipped";
68
+ }
69
+ }
70
+
71
+ await run();
72
+ this.#write(checked, "done", false);
73
+
74
+ return "ran";
75
+ }
76
+ }
@@ -0,0 +1,35 @@
1
+ import { join } from "node:path";
2
+ import { rmSync } from "node:fs";
3
+ import type { z } from "zod";
4
+ import { atomicWrite, listRecords, orMissing, readJson, slug } from "./fs.ts";
5
+
6
+ /** One JSON file per key under a folder, written whole. The schema checks every read. */
7
+ export class Records<S extends z.ZodType> {
8
+ readonly #folder: string;
9
+ readonly #schema: S;
10
+
11
+ constructor(folder: string, schema: S) {
12
+ this.#folder = folder;
13
+ this.#schema = schema;
14
+ }
15
+
16
+ #path(key: string): string {
17
+ return join(this.#folder, `${slug(key)}.json`);
18
+ }
19
+
20
+ get(key: string): z.output<S> | undefined {
21
+ return orMissing(() => this.#schema.parse(readJson(this.#path(key))), undefined);
22
+ }
23
+
24
+ put(key: string, value: z.input<S>): void {
25
+ atomicWrite(this.#path(key), `${JSON.stringify(this.#schema.parse(value))}\n`);
26
+ }
27
+
28
+ remove(key: string): void {
29
+ rmSync(this.#path(key), { force: true });
30
+ }
31
+
32
+ list(): z.output<S>[] {
33
+ return listRecords(this.#folder).map((file) => this.#schema.parse(readJson(file)));
34
+ }
35
+ }
@@ -0,0 +1,99 @@
1
+ import { join } from "node:path";
2
+ import { z } from "zod";
3
+ import { atomicWrite, createOnce, listFiles, listRecords, orMissing, readJson, slug } from "./fs.ts";
4
+
5
+ export const RunKey = z.strictObject({ itemId: z.string().min(1), run: z.string().min(1), attempt: z.int().nonnegative() });
6
+
7
+ export type RunKey = z.infer<typeof RunKey>;
8
+
9
+ export const RunRecord = RunKey.extend({
10
+ /** On the Mac the run's name is saved before launch and found by it after a crash. */
11
+ name: z.string().min(1),
12
+ /** The Claude session id: set ahead in CI, learned after launch on the Mac. */
13
+ sessionId: z.string().min(1).optional(),
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
+ });
20
+
21
+ export type RunRecord = z.infer<typeof RunRecord>;
22
+
23
+ export type BegunRun = { readonly record: RunRecord; readonly adopted: boolean };
24
+
25
+ /** The run's name, then its session id, saved so a restart adopts the run and never starts it twice. */
26
+ export class RunRecords {
27
+ readonly #folder: string;
28
+ readonly #now: () => number;
29
+
30
+ constructor(folder: string, now: () => number) {
31
+ this.#folder = folder;
32
+ this.#now = now;
33
+ }
34
+
35
+ #path(key: RunKey): string {
36
+ return join(this.#folder, slug(key.itemId), `${slug(`${key.run}\u0000${key.attempt}`)}.json`);
37
+ }
38
+
39
+ get(key: RunKey): RunRecord | undefined {
40
+ return orMissing(() => RunRecord.parse(readJson(this.#path(RunKey.parse(key)))), undefined);
41
+ }
42
+
43
+ /** 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 {
45
+ const record = RunRecord.parse({ ...key, name, sessionId, savedAt: this.#now() });
46
+ const created = createOnce(this.#path(record), `${JSON.stringify(record)}\n`);
47
+ const saved = created ? record : this.get(key);
48
+
49
+ if (!saved) throw new Error(`run record for ${key.itemId} ${key.run} #${key.attempt} vanished after it was found`);
50
+
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;
65
+ }
66
+
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 {
69
+ const record = this.get(key);
70
+
71
+ if (!record) throw new Error(`no saved run for ${key.itemId} ${key.run} #${key.attempt}; call begin before launch`);
72
+
73
+ const next = RunRecord.parse({ ...record, endedAt: this.#now(), memoryUsed: memoryUsed && [...memoryUsed] });
74
+
75
+ atomicWrite(this.#path(next), `${JSON.stringify(next)}\n`);
76
+
77
+ return next;
78
+ }
79
+
80
+ /** The item's run of this purpose that was begun and never ended: the one a restart adopts. */
81
+ unended(itemId: string, run: string): RunRecord | undefined {
82
+ return this.list(itemId).find((record) => record.run === run && record.endedAt === undefined);
83
+ }
84
+
85
+ /** Every item's saved runs, oldest first. */
86
+ all(): RunRecord[] {
87
+ return listFiles(this.#folder)
88
+ .flatMap(listRecords)
89
+ .map((file) => RunRecord.parse(readJson(file)))
90
+ .sort((a, b) => a.savedAt - b.savedAt);
91
+ }
92
+
93
+ /** The item's saved runs, oldest first. */
94
+ list(itemId: string): RunRecord[] {
95
+ return listRecords(join(this.#folder, slug(itemId)))
96
+ .map((file) => RunRecord.parse(readJson(file)))
97
+ .sort((a, b) => a.savedAt - b.savedAt || a.attempt - b.attempt);
98
+ }
99
+ }
@@ -0,0 +1,119 @@
1
+ import { z } from "zod";
2
+ import { AlignmentAnswer } from "../decide/alignment.ts";
3
+ import { Cite, PlanFile } from "../decide/prose.ts";
4
+
5
+ const name = z.string().min(1);
6
+ const time = z.int().nonnegative();
7
+
8
+ /** Why an item sits out: it ended stuck, or its change waits for the owner's review. Until the owner acts, no run starts for it. */
9
+ export const Parked = z.strictObject({ item: name, why: z.enum(["stuck", "review"]), cause: name, since: time });
10
+
11
+ export type Parked = z.infer<typeof Parked>;
12
+
13
+ /** Tokens an item has spent over all its runs. The cap counts those after `base`, the total when the owner last answered. */
14
+ export const Spent = z.strictObject({ item: name, total: time, base: time });
15
+
16
+ export type Spent = z.infer<typeof Spent>;
17
+
18
+ /** Until when every run is held. Saved so a restart makes no call before it. */
19
+ export const Limit = z.strictObject({ until: time });
20
+
21
+ /** The ids a provider last listed as ready, so a restart still sees an empty list that contradicts them. */
22
+ export const ReadyList = z.strictObject({ ids: z.array(name) });
23
+
24
+ /** A finished change on its way to the base: what its diff showed, so a retry lands it again without a run. */
25
+ export const Landing = z.strictObject({
26
+ item: name,
27
+ branch: name,
28
+ since: time,
29
+ change: z.strictObject({ paths: z.array(name), size: z.int().nonnegative(), loosened: z.boolean(), pinChanged: z.boolean() }),
30
+ /** The commit the change ends at, before hum marks the item done: what a review reads. */
31
+ head: name,
32
+ /** The owner approved this change in its review state, before it was saved. */
33
+ ownerApproved: z.boolean(),
34
+ /** The alignment call's grades, or why it abstained; made once per change. */
35
+ alignment: z.union([z.strictObject({ graded: AlignmentAnswer }), z.strictObject({ abstained: name })]).optional(),
36
+ });
37
+
38
+ export type Landing = z.infer<typeof Landing>;
39
+
40
+ /** A path rule the owner's answer made, committed on the base; the view lists it with an undo. */
41
+ export const Learned = z.strictObject({ glob: name, level: name, item: name, commit: name, pull: name.optional(), at: time });
42
+
43
+ export type Learned = z.infer<typeof Learned>;
44
+
45
+ /** The model ids that answered a model-judgment call; the measured record decides later whether they count. */
46
+ const models = z.array(name);
47
+
48
+ /** An item's kind, decided once: named by its source, picked by the model call, or the fallback when the call abstained. */
49
+ export const ItemKind = z.discriminatedUnion("from", [
50
+ z.strictObject({ item: name, kind: name, from: z.literal("source") }),
51
+ z.strictObject({ item: name, kind: name, from: z.literal("model") }),
52
+ z.strictObject({ item: name, kind: name, from: z.literal("fallback"), why: name }),
53
+ ]);
54
+
55
+ export type ItemKind = z.infer<typeof ItemKind>;
56
+
57
+ /** The plan a plan run made ready, saved with its hash so later runs read it unchanged. */
58
+ export const SavedPlan = z.strictObject({ item: name, plan: PlanFile, hash: name, models });
59
+
60
+ export type SavedPlan = z.infer<typeof SavedPlan>;
61
+
62
+ /** A fresh review run's verdict on the change that ends at `head`. */
63
+ export const Verdict = z.strictObject({ item: name, head: name, event: name, reason: z.string(), cites: z.array(Cite), models });
64
+
65
+ export type Verdict = z.infer<typeof Verdict>;
66
+
67
+ /** A question the run asked, waiting for room under the daily cap until `askedAt` is set; `askedAt` stays to count the day. */
68
+ export const QueuedQuestion = z.strictObject({
69
+ item: name,
70
+ text: name,
71
+ options: z.array(name).optional(),
72
+ detail: z.string().optional(),
73
+ /** The index of the item's best priority label; no label is last. */
74
+ priority: z.int().nonnegative(),
75
+ /** The files the item declares it touches; none declared means it clashes with every item. */
76
+ footprint: z.array(name).optional(),
77
+ queuedAt: time,
78
+ askedAt: time.optional(),
79
+ });
80
+
81
+ export type QueuedQuestion = z.infer<typeof QueuedQuestion>;
82
+
83
+ /** What became of one answer on an item's thread, saved before its reply is posted. */
84
+ export const SettledAnswer = z.strictObject({
85
+ item: name,
86
+ /** The answer's number among the thread's answers and replies from people. */
87
+ ordinal: z.int().positive(),
88
+ text: name,
89
+ /** The option the answer picked, when it picked one. */
90
+ option: name.optional(),
91
+ source: z.enum(["marker", "free", "first-word", "model", "none-of-these", "abstained"]),
92
+ disposition: z.enum(["applied", "held", "dropped"]),
93
+ why: name,
94
+ at: time,
95
+ });
96
+
97
+ export type SettledAnswer = z.infer<typeof SettledAnswer>;
98
+
99
+ /**
100
+ * Where a run slot stands: made and not yet ready, ready, taken by an item's pass, returned and waiting to be
101
+ * refreshed, kept because its branch holds a commit the remote lacks, or out of the pool.
102
+ */
103
+ export const SLOT_STATUSES = ["new", "free", "stale", "taken", "kept", "out"] as const;
104
+
105
+ /** A prewarmed worktree of the owner's checkout that background runs work in. */
106
+ export const Slot = z.strictObject({
107
+ name,
108
+ /** Which block of ports, among the slots, is this slot's. */
109
+ index: z.int().nonnegative(),
110
+ folder: name,
111
+ status: z.enum(SLOT_STATUSES),
112
+ /** The item whose pass holds the slot; set while it is taken or kept. */
113
+ item: name.optional(),
114
+ /** The hash of the lockfiles the slot's dependencies were last installed from. */
115
+ lockfiles: name.optional(),
116
+ since: time,
117
+ });
118
+
119
+ export type Slot = z.infer<typeof Slot>;
@@ -0,0 +1,49 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { atomicWrite, isMissing, orMissing } from "../state/fs.ts";
3
+ import { emptyStatus, Heartbeat, Status } from "./format.ts";
4
+
5
+ export type StatusRead =
6
+ | { readonly ok: true; readonly status: Status }
7
+ | { readonly ok: false; readonly reason: "missing" | "unreadable"; readonly message: string };
8
+
9
+ /** The engine's one write of the status file. Validates first, then writes atomically, so no reader sees a part. */
10
+ export const writeStatus = (path: string, status: Status): void => {
11
+ atomicWrite(path, `${JSON.stringify(Status.parse(status))}\n`);
12
+ };
13
+
14
+ export const readStatus = (path: string): StatusRead => {
15
+ try {
16
+ const parsed = Status.safeParse(JSON.parse(readFileSync(path, "utf8")));
17
+
18
+ return parsed.success
19
+ ? { ok: true, status: parsed.data }
20
+ : { ok: false, reason: "unreadable", message: `${path} does not hold a status file this engine reads: ${parsed.error.message}` };
21
+ } catch (error) {
22
+ if (error instanceof Error && isMissing(error)) return { ok: false, reason: "missing", message: `${path} does not exist` };
23
+
24
+ return { ok: false, reason: "unreadable", message: `${path} cannot be read: ${error instanceof Error ? error.message : "unknown error"}` };
25
+ }
26
+ };
27
+
28
+ /** The worker's one write of its heartbeat each tick. */
29
+ export const writeHeartbeat = (path: string, heartbeat: Heartbeat): void => {
30
+ atomicWrite(path, `${JSON.stringify(Heartbeat.parse(heartbeat))}\n`);
31
+ };
32
+
33
+ export const readHeartbeat = (path: string): Heartbeat | undefined => {
34
+ return orMissing(() => {
35
+ const parsed = Heartbeat.safeParse(JSON.parse(readFileSync(path, "utf8")));
36
+
37
+ return parsed.success ? parsed.data : undefined;
38
+ }, undefined);
39
+ };
40
+
41
+ /**
42
+ * The service unit's write of the fault cards while no worker writes them. The status file's other fields
43
+ * stay as they were, `writtenAt` included, so a dead worker still reads as stale.
44
+ */
45
+ export const writeCards = (path: string, cards: Status["cards"], engineVersion: string, now: number): void => {
46
+ const read = readStatus(path);
47
+
48
+ writeStatus(path, { ...(read.ok ? read.status : emptyStatus(engineVersion, now)), cards });
49
+ };