@moo.md/hum 0.4.1 → 0.6.1

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 (48) hide show
  1. package/defaults/hum.json +39 -12
  2. package/npm-shrinkwrap.json +2 -2
  3. package/package.json +2 -1
  4. package/release.json +1 -1
  5. package/schema/hum.schema.json +63 -17
  6. package/scripts/eval.ts +58 -27
  7. package/src/adapters/claude-p.ts +7 -0
  8. package/src/adapters/model-call.ts +8 -4
  9. package/src/adapters/pull-requests.ts +11 -7
  10. package/src/cli/setup.ts +13 -18
  11. package/src/config/json.ts +3 -0
  12. package/src/config/migrate.ts +11 -0
  13. package/src/config/schema.ts +21 -6
  14. package/src/decide/alignment.ts +1 -1
  15. package/src/decide/merge.ts +21 -1
  16. package/src/decide/prose.ts +12 -2
  17. package/src/decide/risk.ts +1 -0
  18. package/src/loop/breaks.ts +17 -0
  19. package/src/loop/notes.ts +2 -2
  20. package/src/loop/pair.ts +2 -2
  21. package/src/loop/pass.ts +6 -3
  22. package/src/loop/records.ts +24 -1
  23. package/src/loop/signals.ts +2 -2
  24. package/src/measure/cases.ts +102 -0
  25. package/src/measure/inputs.ts +15 -1
  26. package/src/measure/judges.ts +52 -0
  27. package/src/measure/measure.ts +22 -3
  28. package/src/measure/rate.ts +9 -6
  29. package/src/measure/remeasure.ts +31 -0
  30. package/src/publish/handoff.ts +1 -1
  31. package/src/service/workflows.ts +4 -2
  32. package/src/setup/write.ts +2 -4
  33. package/src/state/events.ts +201 -19
  34. package/src/state/format.ts +9 -2
  35. package/src/state/item-log.ts +133 -0
  36. package/src/state/items.ts +6 -5
  37. package/src/state/open.ts +7 -2
  38. package/src/state/runs.ts +5 -0
  39. package/src/state/saved.ts +7 -2
  40. package/src/status/format.ts +12 -3
  41. package/src/worker/land.ts +36 -15
  42. package/src/worker/merged.ts +18 -8
  43. package/src/worker/open.ts +5 -1
  44. package/src/worker/prose-run.ts +6 -2
  45. package/src/worker/signature.ts +11 -5
  46. package/src/worker/thin-path.ts +69 -53
  47. package/src/worker/worker.ts +82 -12
  48. package/surface.json +969 -151
@@ -95,7 +95,7 @@ export const takeWorkRecords = (work: State, into: State, inbox: InboxItem, limi
95
95
 
96
96
  for (const choice of work.choices.list().filter((choice) => choice.item === item)) into.choices.put(`${item}@${choice.text}`, choice);
97
97
 
98
- for (const event of work.events.list(item)) into.events.add(event);
98
+ work.events.copyTo(into.events, item);
99
99
 
100
100
  for (const { code, cause, fix } of work.faults.list().filter((card) => card.item === item && WORK_CARD_CODES.has(card.code))) into.faults.raise({ code, item, cause, fix });
101
101
 
@@ -1,5 +1,4 @@
1
1
  import { Document, visit } from "yaml";
2
- import { CLAUDE_FLOOR } from "../adapters/claude-p.ts";
3
2
  import type { HumConfig, PullRequestToken } from "../config/schema.ts";
4
3
  import { APP_TOKEN_ACTION, APP_TOKEN_MINUTES, CLAUDE_TOKEN, readsSecrets, secretsNamed, TRUSTED_ASSOCIATIONS, WAKE_ENV as ENV, WORKFLOW_FILES } from "../config/wake-job.ts";
5
4
  import { ENGINE_VERSION } from "../state/format.ts";
@@ -19,6 +18,9 @@ const WAKE_PATH = `./.github/workflows/${WORKFLOW_FILES.wake}`;
19
18
  /** The Bun that builds the workflows is the one the owner's repo runs, so CI installs with the same lockfile reader. */
20
19
  const BUN_VERSION = Bun.version;
21
20
 
21
+ /** The Claude Code every job installs. `hum plugins` adds each marketplace the repo declares at a commit SHA, which Claude Code clones from 2.1.325 on, as its release notes say. */
22
+ const CLAUDE_VERSION = "2.1.325";
23
+
22
24
  /**
23
25
  * Each action the workflows run, at the one commit its release is. A tag can move to code that then holds the App's
24
26
  * private key and every secret of the job; a commit cannot. The release rides beside the commit as a comment.
@@ -197,7 +199,7 @@ const PUBLISHED_HUM = `@moo.md/hum@${ENGINE_VERSION}`;
197
199
  /** The tools every job installs at exact versions, each with the one install script that fetches its native binary. */
198
200
  const TOOLS = [
199
201
  { spec: `bun@${BUN_VERSION}`, folder: "bun", script: "install.js" },
200
- { spec: `@anthropic-ai/claude-code@${CLAUDE_FLOOR}`, folder: "@anthropic-ai/claude-code", script: "install.cjs" },
202
+ { spec: `@anthropic-ai/claude-code@${CLAUDE_VERSION}`, folder: "@anthropic-ai/claude-code", script: "install.cjs" },
201
203
  ] as const;
202
204
 
203
205
  /**
@@ -5,7 +5,7 @@ import { z } from "zod";
5
5
  import type { GitIdentityRead } from "../adapters/git.ts";
6
6
  import { type Config, loadConfig, type RawConfig, readConfigDir } from "../config/load.ts";
7
7
  import { hashJson } from "../config/hash.ts";
8
- import { Json } from "../config/json.ts";
8
+ import { asJson, Json } from "../config/json.ts";
9
9
  import { migrateConfig } from "../config/migrate.ts";
10
10
  import { noGitIdentity, type Refusal, type Result } from "../config/refusal.ts";
11
11
  import { type HumConfig, Kind, READABLE_SCHEMA_VERSIONS, SCHEMA_VERSION } from "../config/schema.ts";
@@ -111,8 +111,6 @@ const STRUCTURAL = new Set<string>(STRUCTURE);
111
111
  const ownerKeys = (hum: Readonly<Record<string, Json>>, shipped: Readonly<Record<string, Json>>): Record<string, Json> =>
112
112
  Object.fromEntries(Object.entries(hum).filter(([key, value]) => STRUCTURAL.has(key) || hashJson(value) !== hashJson(shipped[key] ?? null)));
113
113
 
114
- const asJson = (value: Kind | Readonly<Record<string, Json>>): Json => Json.parse(JSON.parse(JSON.stringify(value)));
115
-
116
114
  /**
117
115
  * Writes `.hum/` and the service files from the owner's answers, or writes nothing: the config must pass every check
118
116
  * with every wait timed out, and must be a schema the installed engine reads (and the one already in the repo).
@@ -197,5 +195,5 @@ const serviceFile = (repo: string, config: Config, env: SetupEnv): FileToWrite =
197
195
  };
198
196
  };
199
197
 
200
- /** The answers file the skill writes: `{ "hum": {...}, "waitHours": {...}, "schemaVersion": 2 }`, with `"ownRunnerOnPublicRepo": true` once the owner agreed to it. */
198
+ /** The answers file the skill writes: `{ "hum": {...}, "waitHours": {...}, "schemaVersion": <the schema version> }`, with `"ownRunnerOnPublicRepo": true` once the owner agreed to it. */
201
199
  export const readAnswers = (file: string): SetupAnswers => SetupAnswers.parse(JSON.parse(readFileSync(file, "utf8")));
@@ -1,52 +1,234 @@
1
1
  import { join } from "node:path";
2
2
  import { z } from "zod";
3
+ import { hashJson } from "../config/hash.ts";
3
4
  import { Json } from "../config/json.ts";
5
+ import { climb, type Steps } from "../config/migrate.ts";
6
+ import { DONE_BY } from "../decide/merge.ts";
7
+ import type { Faults, Outcome } from "./faults.ts";
8
+ import { ENGINE_VERSION, isNewerThan, UPDATE_ENGINE } from "./format.ts";
4
9
  import { createOnce, listRecords, readJson, slug } from "./fs.ts";
10
+ import { SNAPSHOT_CARDS } from "./items.ts";
5
11
 
6
- export const SavedEvent = z.object({
7
- /** Where the event came from, such as a thread comment id: a second read of it adds nothing. */
8
- source: z.string().min(1),
9
- sourceId: z.string().min(1),
10
- itemId: z.string().min(1),
11
- type: z.string().min(1),
12
- receivedAt: z.int().nonnegative(),
13
- payload: Json,
12
+ /** The record shape this engine writes to an item's log. A change here is public surface: every later engine reads each format an earlier one wrote. */
13
+ export const LOG_FORMAT = 1;
14
+
15
+ const name = z.string().min(1);
16
+ const count = z.int().nonnegative();
17
+ const models = z.array(name);
18
+
19
+ /** A log record as its file holds it, at any format. */
20
+ const LogRecord = z.record(z.string(), Json);
21
+
22
+ type LogRecord = z.infer<typeof LogRecord>;
23
+
24
+ /**
25
+ * One step per earlier format, each rewriting a record at that format into the next one's shape, with no clock and no
26
+ * I/O. Format 0 is every record hum wrote before 0.5.0, an `answered` or a `merged` with no format and no engine: it
27
+ * reads as format 1 unchanged.
28
+ */
29
+ const LOG_MIGRATIONS: Steps<LogRecord> = {
30
+ 0: (record) => record,
31
+ };
32
+
33
+ /** What every format of a record carries: enough to place it in its log, and to refuse one from a newer engine before reading the rest. */
34
+ const Placed = z.looseObject({
35
+ format: z.int().nonnegative().default(0),
36
+ engineVersion: name.optional(),
37
+ source: name,
38
+ sourceId: name,
39
+ itemId: name,
40
+ receivedAt: count,
41
+ seq: count.optional(),
14
42
  });
15
43
 
44
+ type Placed = z.infer<typeof Placed>;
45
+
46
+ /**
47
+ * A model run's answer as the log keeps it: a finished run's report, or the tokens a run spent before the item's cap
48
+ * stopped it. The log owns this shape, so a change to the runner's own type leaves format 1 as it is.
49
+ */
50
+ export const KeptOutcome = z.discriminatedUnion("kind", [
51
+ z.object({
52
+ kind: z.literal("finished"),
53
+ subtype: name,
54
+ isError: z.boolean(),
55
+ sessionId: name.optional(),
56
+ text: z.string(),
57
+ structured: Json.optional(),
58
+ tokens: count,
59
+ cacheReadTokens: count,
60
+ plugins: z.array(name),
61
+ keySource: name.optional(),
62
+ models,
63
+ }),
64
+ z.object({ kind: z.literal("over-cap"), tokens: count }),
65
+ ]);
66
+
67
+ export type KeptOutcome = z.infer<typeof KeptOutcome>;
68
+
69
+ /** A plan or review run's pick as the log keeps it: the event, how sure the run was, why, and what it cited, planned, asked or split into. */
70
+ const KeptPick = z.object({
71
+ event: name,
72
+ sure: z.boolean(),
73
+ reason: z.string(),
74
+ cites: z.array(z.object({ file: name, line: z.int().positive() })),
75
+ plan: z.object({ summary: name, steps: z.array(name), paths: z.array(name) }).optional(),
76
+ question: z.string().optional(),
77
+ parts: z.array(name),
78
+ });
79
+
80
+ const grade = z.enum(["sound", "partial", "concern"]);
81
+
82
+ /** What a judge picked for the item: a plan or review run's pick and the models that answered it, or the alignment call's grades or why it abstained. A review and the alignment call judge the change that ends at `head`. */
83
+ const Picked = z.discriminatedUnion("judge", [
84
+ z.object({ judge: z.literal("plan"), pick: KeptPick, models }),
85
+ z.object({ judge: z.literal("review"), head: name, pick: KeptPick, models }),
86
+ z.object({ judge: z.literal("alignment"), head: name, alignment: z.union([z.object({ graded: z.object({ alignment: grade, verification: grade }) }), z.object({ abstained: name })]) }),
87
+ ]);
88
+
89
+ const envelope = {
90
+ format: z.literal(LOG_FORMAT),
91
+ /** The engine that wrote the record; one from before hum 0.5.0 names none. */
92
+ engineVersion: name.optional(),
93
+ /** Where the event came from, such as a thread comment id: a second read of it adds nothing. */
94
+ source: name,
95
+ sourceId: name,
96
+ itemId: name,
97
+ receivedAt: count,
98
+ /** The event's place in its item's log. An event saved before hum kept places has none, and comes first, by when it arrived. */
99
+ seq: count.optional(),
100
+ };
101
+
102
+ /** The version of the item's kind machine the record was made under. */
103
+ const machineVersion = name;
104
+
105
+ /** A log record at this engine's format: where it came from, its place, and, by type, the fact it keeps. Each type names something that happened. The log owns every shape here. */
106
+ export const SavedEvent = z.discriminatedUnion("type", [
107
+ z.object({ ...envelope, machineVersion, type: z.literal("machine-started"), payload: z.object({ afresh: z.boolean() }) }),
108
+ z.object({ ...envelope, machineVersion, type: z.literal("model-answered"), payload: z.object({ run: name, attempt: count, question: name.optional(), outcome: KeptOutcome }) }),
109
+ z.object({ ...envelope, type: z.literal("picked"), payload: Picked }),
110
+ z.object({ ...envelope, type: z.literal("landing-found"), payload: z.object({ head: name, doneBy: z.enum(DONE_BY) }) }),
111
+ z.object({ ...envelope, type: z.literal("answered"), payload: z.object({}) }),
112
+ z.object({ ...envelope, type: z.literal("merged"), payload: z.object({}) }),
113
+ ]);
114
+
16
115
  export type SavedEvent = z.infer<typeof SavedEvent>;
17
116
 
18
- export type NewEvent = Omit<SavedEvent, "receivedAt">;
117
+ /** What the log stamps on each record it saves. */
118
+ type Stamped = "format" | "engineVersion" | "receivedAt" | "seq";
119
+
120
+ /** An event as its writer gives it. One with no `sourceId` is keyed by its content and the place it takes in its item's log. */
121
+ export type NewEvent = { [Type in SavedEvent["type"]]: Omit<Extract<SavedEvent, { type: Type }>, Stamped | "sourceId"> & { readonly sourceId?: string } }[SavedEvent["type"]];
122
+
123
+ /** A record found in an item's log, with what places it. */
124
+ type Found = { readonly record: LogRecord; readonly placed: Placed };
19
125
 
20
- /** Every event is saved before anything acts on it, keyed by source, so reading one twice adds nothing. */
126
+ /** What the owner does about a log record this engine cannot read. */
127
+ const DAMAGED_RECORD_FIX = "Restore the record from a backup, or delete it; the other items go on.";
128
+
129
+ /**
130
+ * Every event is saved before anything acts on it, keyed by source, so reading one twice adds nothing; each new one
131
+ * takes the next place in its item's log. A record a newer engine wrote, or one this engine cannot read, is never
132
+ * read: it raises one card for its item.
133
+ */
21
134
  export class EventLog {
22
135
  readonly #folder: string;
23
136
  readonly #now: () => number;
137
+ readonly #faults: Faults;
138
+ readonly #engineVersion: string;
24
139
 
25
- constructor(folder: string, now: () => number) {
140
+ constructor(folder: string, now: () => number, faults: Faults, engineVersion: string = ENGINE_VERSION) {
26
141
  this.#folder = folder;
27
142
  this.#now = now;
143
+ this.#faults = faults;
144
+ this.#engineVersion = engineVersion;
28
145
  }
29
146
 
30
147
  #path({ itemId, source, sourceId }: Pick<SavedEvent, "itemId" | "source" | "sourceId">): string {
31
148
  return join(this.#folder, slug(itemId), `${slug(`${source}\u0000${sourceId}`)}.json`);
32
149
  }
33
150
 
34
- /** Saves the event. `added` is false when this source and id are already in the log. */
35
- add(event: NewEvent): { readonly added: boolean; readonly event: SavedEvent } {
36
- const saved = SavedEvent.parse({ ...event, receivedAt: this.#now() });
151
+ #nextPlace(itemId: string): number {
152
+ return listRecords(join(this.#folder, slug(itemId))).length;
153
+ }
154
+
155
+ #found(record: LogRecord): Found {
156
+ return { record, placed: Placed.parse(record) };
157
+ }
158
+
159
+ /** Why this engine refuses the record, when a newer one wrote it. */
160
+ #refusal({ placed }: Found): string | undefined {
161
+ if (!isNewerThan(placed, { format: LOG_FORMAT, engineVersion: this.#engineVersion })) return undefined;
162
+
163
+ return `The log of ${placed.itemId} holds a record hum ${placed.engineVersion ?? "of an unknown version"} wrote in format ${placed.format}; the running ${this.#engineVersion} reads up to format ${LOG_FORMAT}.`;
164
+ }
165
+
166
+ /** The record in this engine's format, climbed from the one it was written in. */
167
+ #current({ record, placed }: Found) {
168
+ return SavedEvent.safeParse(climb(record, placed.format, LOG_FORMAT, LOG_MIGRATIONS, "format"));
169
+ }
170
+
171
+ /** An item's records as their files hold them, in the order its log took them. */
172
+ #records(itemId: string): Found[] {
173
+ return listRecords(join(this.#folder, slug(itemId)))
174
+ .map((file) => this.#found(LogRecord.parse(readJson(file))))
175
+ .sort(({ placed: a }, { placed: b }) => (a.seq ?? -1) - (b.seq ?? -1) || a.receivedAt - b.receivedAt || (a.sourceId < b.sourceId ? -1 : 1));
176
+ }
177
+
178
+ /** Saves the event at the end of its item's log. `added` is false when this source and id are already in the log. */
179
+ add({ sourceId, ...event }: NewEvent): { readonly added: boolean; readonly event: SavedEvent } {
180
+ const seq = this.#nextPlace(event.itemId);
181
+ const saved = SavedEvent.parse({ ...event, sourceId: sourceId ?? hashJson({ type: event.type, payload: event.payload, seq }), format: LOG_FORMAT, engineVersion: this.#engineVersion, receivedAt: this.#now(), seq });
37
182
  const added = createOnce(this.#path(saved), `${JSON.stringify(saved)}\n`);
38
183
 
39
184
  return added ? { added, event: saved } : { added, event: this.get(saved) };
40
185
  }
41
186
 
187
+ /** Copies an item's records into another log as their writers wrote them, each at the next place there; a record already there stays. */
188
+ copyTo(into: EventLog, itemId: string): void {
189
+ for (const { record, placed } of this.#records(itemId)) createOnce(into.#path(placed), `${JSON.stringify({ ...record, seq: into.#nextPlace(itemId) })}\n`);
190
+ }
191
+
192
+ /** One record; one a newer engine wrote, or one this engine cannot read, throws. */
42
193
  get(key: Pick<SavedEvent, "itemId" | "source" | "sourceId">): SavedEvent {
43
- return SavedEvent.parse(readJson(this.#path(key)));
194
+ const found = this.#found(LogRecord.parse(readJson(this.#path(key))));
195
+ const refusal = this.#refusal(found);
196
+
197
+ if (refusal !== undefined) throw new Error(refusal);
198
+
199
+ const current = this.#current(found);
200
+
201
+ if (!current.success) throw current.error;
202
+
203
+ return current.data;
204
+ }
205
+
206
+ /** An item's events in the order its log took them, or one card when a newer engine wrote any of them or this engine cannot read one. */
207
+ read(itemId: string): Outcome<SavedEvent[]> {
208
+ const found = this.#records(itemId);
209
+ const refusal = found.map((each) => this.#refusal(each)).find((cause) => cause !== undefined);
210
+
211
+ if (refusal !== undefined) return { ok: false, fault: this.#faults.raise({ code: SNAPSHOT_CARDS.newerEngine, item: itemId, cause: refusal, fix: UPDATE_ENGINE }) };
212
+
213
+ const events: SavedEvent[] = [];
214
+
215
+ for (const each of found) {
216
+ const current = this.#current(each);
217
+
218
+ if (!current.success) return { ok: false, fault: this.#faults.raise({ code: SNAPSHOT_CARDS.unreadable, item: itemId, cause: `The log of ${itemId} holds a record from ${each.placed.source} that hum cannot read: ${z.prettifyError(current.error)}`, fix: DAMAGED_RECORD_FIX }) };
219
+
220
+ events.push(current.data);
221
+ }
222
+
223
+ return { ok: true, value: events };
44
224
  }
45
225
 
46
- /** An item's events in the order they arrived. */
226
+ /** As `read`, for a caller past a `read` that let the item go on: a record from a newer engine, or one this engine cannot read, throws. */
47
227
  list(itemId: string): SavedEvent[] {
48
- return listRecords(join(this.#folder, slug(itemId)))
49
- .map((file) => SavedEvent.parse(readJson(file)))
50
- .sort((a, b) => a.receivedAt - b.receivedAt || (a.sourceId < b.sourceId ? -1 : 1));
228
+ const log = this.read(itemId);
229
+
230
+ if (!log.ok) throw new Error(log.fault.cause);
231
+
232
+ return log.value;
51
233
  }
52
234
  }
@@ -37,8 +37,15 @@ export type EnvelopeMigrations = Steps<EnvelopeJson>;
37
37
  /** One entry per earlier format, from format 0 up. Empty while format 1 is the first shipped. */
38
38
  export const ENVELOPE_MIGRATIONS: EnvelopeMigrations = {};
39
39
 
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, running }: { readonly written: string; readonly running: string }): boolean => semver.valid(written) === null || semver.gt(written, running);
40
+ /** What the owner does about a file a newer engine wrote. */
41
+ export const UPDATE_ENGINE = "Update the engine to that version or later: bun add --exact @moo.md/hum@latest.";
42
+
43
+ /** A file's format and the engine that wrote it; a file from before engines were recorded names none. */
44
+ type Written = { readonly format: number; readonly engineVersion?: string | undefined };
45
+
46
+ /** True when a file's format is newer than the running engine reads, or a newer engine, or one whose version is unreadable, wrote it. */
47
+ export const isNewerThan = ({ format, engineVersion }: Written, running: { readonly format: number; readonly engineVersion: string }): boolean =>
48
+ format > running.format || (engineVersion !== undefined && (semver.valid(engineVersion) === null || semver.gt(engineVersion, running.engineVersion)));
42
49
 
43
50
  /** The part of an envelope that names the item and its machine, enough to list what is saved without restoring it. */
44
51
  export const SavedHeader = z.looseObject({
@@ -0,0 +1,133 @@
1
+ import { isPaused, type RunOutcome } from "../adapters/claude-p.ts";
2
+ import { hashJson } from "../config/hash.ts";
3
+ import { asJson, type Json } from "../config/json.ts";
4
+ import type { PURPOSES } from "../config/schema.ts";
5
+ import type { DoneBy } from "../decide/merge.ts";
6
+ import { SPLIT } from "../decide/prose.ts";
7
+ import { type EventLog, KeptOutcome, type NewEvent, type SavedEvent } from "./events.ts";
8
+ import type { BegunRun, RunKey, RunRecords } from "./runs.ts";
9
+
10
+ /** A record of one type, as the log keeps it. */
11
+ type Entry<Type extends SavedEvent["type"]> = Extract<SavedEvent, { readonly type: Type }>;
12
+
13
+ /** What a judge picked for the item, as the log keeps it. */
14
+ export type Picked = Entry<"picked">["payload"];
15
+
16
+ /** The item whose machine a pass starts, and the version of its kind machine. */
17
+ type MachineOf = { readonly itemId: string; readonly machineVersion: string };
18
+
19
+ /**
20
+ * A pass starts the item's machine over from its initial state; a pass that restores a saved wait starts none. A pass
21
+ * starts it afresh when nothing saved is left to go on from, and no answer kept before then stands for a run after it.
22
+ */
23
+ export const machineStarted = ({ itemId, machineVersion, afresh }: MachineOf & { readonly afresh: boolean }): NewEvent => ({ source: "machine", itemId, machineVersion, type: "machine-started", payload: { afresh } });
24
+
25
+ /** The owner's answer on the item's thread, keyed by when it came, so every read of it adds one entry. */
26
+ export const ownerAnswered = (itemId: string, at: number): NewEvent => ({ source: "thread", sourceId: `answer:${at}`, itemId, type: "answered", payload: {} });
27
+
28
+ /** What one model run is asked, and whether an answer the log keeps to the same question stands in for running it. */
29
+ export type Ask = {
30
+ readonly key: RunKey;
31
+ readonly launch: { readonly name: string; readonly sessionId?: string };
32
+ /** The version of the item's kind machine the run is made under. */
33
+ readonly machineVersion: string;
34
+ /** What the run is asked, given only for a run whose answer is all it does: a kept answer to it is read back, and nothing runs. */
35
+ readonly question?: Json;
36
+ };
37
+
38
+ /** A kept answer as the run's outcome; JSON keeps no key whose value is undefined. */
39
+ const outcomeOf = (kept: KeptOutcome): RunOutcome => (kept.kind === "finished" ? { ...kept, sessionId: kept.sessionId, structured: kept.structured, keySource: kept.keySource } : kept);
40
+
41
+ /**
42
+ * A model run's outcome. The run is saved as begun before it starts, and an outcome that answers, as a finished run or
43
+ * one past its cap does, is kept in the item's log under the run's key before this returns, so the caller ends the
44
+ * run's record after it, and a run that starts again under the same key keeps nothing more. A kept answer to the same
45
+ * question stands in for the run: `run` is not called. A run that ends with no answer (a limit, a hold or a stop)
46
+ * keeps nothing, and its next call runs again.
47
+ */
48
+ export const answerOnce = async (
49
+ { events, runs }: { readonly events: EventLog; readonly runs: RunRecords },
50
+ { key, launch, machineVersion, question }: Ask,
51
+ run: (begun: BegunRun) => Promise<RunOutcome>,
52
+ ): Promise<{ readonly begun: BegunRun; readonly outcome: RunOutcome }> => {
53
+ const begun = runs.begin(key, launch);
54
+ const asked = question === undefined ? undefined : hashJson({ run: key.run, question });
55
+ const kept = asked === undefined ? undefined : foldItem(events.list(key.itemId)).answers[asked];
56
+
57
+ if (kept) return { begun, outcome: outcomeOf(kept) };
58
+
59
+ const outcome = await run(begun);
60
+
61
+ if (!isPaused(outcome)) {
62
+ events.add({ itemId: key.itemId, source: "model", sourceId: `${key.run}#${key.attempt}`, machineVersion, type: "model-answered", payload: { run: key.run, attempt: key.attempt, question: asked, outcome: KeptOutcome.parse(asJson(outcome)) } });
63
+ }
64
+
65
+ return { begun, outcome };
66
+ };
67
+
68
+ /** Each judge's latest pick. */
69
+ type Picks = { readonly [Judge in Picked["judge"]]?: Extract<Picked, { judge: Judge }> };
70
+
71
+ /** An item's state from its log alone: the same log always folds the same. */
72
+ export type ItemFold = {
73
+ /** The fix runs whose answer the log keeps since the owner last answered. */
74
+ readonly fixRuns: number;
75
+ /** The answers kept since the item last started afresh and the owner last answered, by the question each answered. */
76
+ readonly answers: Readonly<Record<string, KeptOutcome>>;
77
+ readonly picks: Picks;
78
+ /** How the change that ends at `head` reaches done if it merges as landing last found it; absent where landing never judged it. */
79
+ readonly landing?: Entry<"landing-found">["payload"];
80
+ readonly merged: boolean;
81
+ };
82
+
83
+ /** The run purpose whose answers the fix cap counts. */
84
+ const FIX = "fix" satisfies (typeof PURPOSES)[number];
85
+
86
+ /** The fold after a kept answer: a fix run's answer counts toward the cap, and an answer to a question stands for the next run asked it. */
87
+ const withAnswer = (fold: ItemFold, { run, question, outcome }: Entry<"model-answered">["payload"]): ItemFold => ({
88
+ ...fold,
89
+ fixRuns: fold.fixRuns + Number(run === FIX),
90
+ answers: question === undefined ? fold.answers : { ...fold.answers, [question]: outcome },
91
+ });
92
+
93
+ const stepItem = (fold: ItemFold, entry: SavedEvent): ItemFold => {
94
+ switch (entry.type) {
95
+ case "machine-started":
96
+ return entry.payload.afresh ? { ...fold, answers: {} } : fold;
97
+ case "model-answered":
98
+ return withAnswer(fold, entry.payload);
99
+ case "picked":
100
+ return { ...fold, picks: { ...fold.picks, [entry.payload.judge]: entry.payload } };
101
+ case "landing-found":
102
+ return { ...fold, landing: entry.payload };
103
+ case "answered":
104
+ return { ...fold, fixRuns: 0, answers: {} };
105
+ case "merged":
106
+ return { ...fold, merged: true };
107
+ }
108
+ };
109
+
110
+ /** An item's facts from its log alone: no model is asked and no effect runs. */
111
+ export const foldItem = (events: readonly SavedEvent[]): ItemFold => events.reduce(stepItem, { fixRuns: 0, answers: {}, picks: {}, merged: false });
112
+
113
+ /** Appends the fact unless the item's last fact of its kind is the same JSON, so a fact read back or a step retried adds nothing. */
114
+ const keepChanged = (events: EventLog, fact: NewEvent, last: NewEvent["payload"] | undefined): void => {
115
+ if (last !== undefined && hashJson(asJson(last)) === hashJson(asJson(fact.payload))) return;
116
+
117
+ events.add(fact);
118
+ };
119
+
120
+ /** Appends a judge's pick for the item, unless it is that judge's last pick again. */
121
+ export const keepPick = (events: EventLog, { itemId, pick }: { readonly itemId: string; readonly pick: Picked }): void =>
122
+ keepChanged(events, { source: "judge", itemId, type: "picked", payload: pick }, foldItem(events.list(itemId)).picks[pick.judge]);
123
+
124
+ /** Appends how the change that ends at `head` reaches done if it merges as landing found it, unless the log last held the same. */
125
+ export const keepLanding = (events: EventLog, { itemId, head, doneBy }: { readonly itemId: string; readonly head: string; readonly doneBy: DoneBy }): void =>
126
+ keepChanged(events, { source: "landing", itemId, type: "landing-found", payload: { head, doneBy } }, foldItem(events.list(itemId)).landing);
127
+
128
+ /** How the item reached done, once its change merged: split by its plan run's last pick, else as landing last found its change; unknown where landing never judged it. */
129
+ export const doneByOf = ({ merged, picks, landing }: ItemFold): DoneBy | undefined => {
130
+ if (!merged) return undefined;
131
+
132
+ return picks.plan?.pick.event === SPLIT ? "split" : landing?.doneBy;
133
+ };
@@ -2,7 +2,7 @@ import { rmSync } from "node:fs";
2
2
  import { join } from "node:path";
3
3
  import { type AnyActor, type AnyActorLogic } from "xstate";
4
4
  import { restoreActor } from "xstate/persist";
5
- import { Json } from "../config/json.ts";
5
+ import { asJson, type Json } from "../config/json.ts";
6
6
  import { climb } from "../config/migrate.ts";
7
7
  import { migrateSnapshot } from "../config/state-map.ts";
8
8
  import { kindMachine } from "../config/machine.ts";
@@ -17,8 +17,9 @@ import {
17
17
  ENVELOPE_MIGRATIONS,
18
18
  type EnvelopeMigrations,
19
19
  Header,
20
- isFromNewerEngine,
20
+ isNewerThan,
21
21
  SavedHeader,
22
+ UPDATE_ENGINE,
22
23
  } from "./format.ts";
23
24
 
24
25
  type ActorClock = NonNullable<Parameters<typeof restoreActor>[2]>["clock"];
@@ -48,7 +49,7 @@ export type SavedSnapshot = {
48
49
  };
49
50
 
50
51
  /** 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
+ export const persistedSnapshot = (actor: AnyActor): Json => asJson(actor.getPersistedSnapshot());
52
53
 
53
54
  const reason = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
54
55
 
@@ -158,8 +159,8 @@ export class Items {
158
159
 
159
160
  if (!header.success) return unreadable("it has no format or engine version");
160
161
 
161
- if (header.data.format > this.#format || isFromNewerEngine({ written: header.data.engineVersion, running: this.#engineVersion })) {
162
- return this.#fault({ itemId, code: SNAPSHOT_CARDS.newerEngine, 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." });
162
+ if (isNewerThan(header.data, { format: this.#format, engineVersion: this.#engineVersion })) {
163
+ return this.#fault({ itemId, code: SNAPSHOT_CARDS.newerEngine, cause: `The saved state of ${itemId} was written by hum ${header.data.engineVersion}, which is newer than the running ${this.#engineVersion}.`, fix: UPDATE_ENGINE });
163
164
  }
164
165
 
165
166
  let envelope: ReturnType<typeof Envelope.safeParse>;
package/src/state/open.ts CHANGED
@@ -5,8 +5,9 @@ import { SHIPPED_COMMAND_TIMEOUT_MS } from "../exec.ts";
5
5
  import { EventLog } from "./events.ts";
6
6
  import { Faults } from "./faults.ts";
7
7
  import { type Codec, Items } from "./items.ts";
8
- import { Break, Merge, PossibleRepeat, Proof, RepeatGroup, ReviewNote } from "../loop/records.ts";
8
+ import { Break, BrokenCommit, Merge, PossibleRepeat, Proof, RepeatGroup, ReviewNote } from "../loop/records.ts";
9
9
  import { Choice } from "../status/format.ts";
10
+ import { MergedCase } from "../measure/cases.ts";
10
11
  import { OpKeys } from "./ops.ts";
11
12
  import { Records } from "./records.ts";
12
13
  import { RunRecords } from "./runs.ts";
@@ -49,7 +50,7 @@ export const openState = (dir: string, { now, ...codec }: StateOptions) => {
49
50
  stops: join(dir, STOPS_DIR),
50
51
  faults,
51
52
  items: new Items(join(dir, "items"), faults, now, codec),
52
- events: new EventLog(join(dir, "events"), now),
53
+ events: new EventLog(join(dir, "events"), now, faults, codec.engineVersion),
53
54
  ops: new OpKeys(join(dir, "ops"), now),
54
55
  runs: new RunRecords(join(dir, "runs"), now),
55
56
  parked: new Records(join(dir, "parked"), Parked),
@@ -86,8 +87,12 @@ export const openState = (dir: string, { now, ...codec }: StateOptions) => {
86
87
  merges: new Records(join(dir, "merges"), Merge),
87
88
  /** Tests of the base that failed after a merge, by item. */
88
89
  breaks: new Records(join(dir, "breaks"), Break),
90
+ /** The label git's rule gives each commit on the base that broke, by sha. */
91
+ labels: new Records(join(dir, "labels"), BrokenCommit),
89
92
  /** What proving a check item cost, by item. */
90
93
  proofs: new Records(join(dir, "proofs"), Proof),
94
+ /** The labelled case each merged item gives the judges its change was put to, by item. */
95
+ cases: new Records(join(dir, "cases"), MergedCase),
91
96
  };
92
97
  };
93
98
 
package/src/state/runs.ts CHANGED
@@ -94,6 +94,11 @@ export class RunRecords {
94
94
  return this.list(itemId).find((record) => record.run === run && record.endedAt === undefined);
95
95
  }
96
96
 
97
+ /** The key the item's next run of this purpose takes: the begun run a restart adopts, else a new attempt. */
98
+ keyFor(itemId: string, run: string): RunKey {
99
+ return { itemId, run, attempt: this.unended(itemId, run)?.attempt ?? this.list(itemId).length };
100
+ }
101
+
97
102
  /** Every item's saved runs, oldest first. */
98
103
  all(): RunRecord[] {
99
104
  return listFiles(this.#folder)
@@ -23,6 +23,9 @@ export const Limit = z.object({ until: time });
23
23
  /** The ids a provider last listed as ready, so a restart still sees an empty list that contradicts them. */
24
24
  export const ReadyList = z.object({ ids: z.array(name) });
25
25
 
26
+ /** The alignment call's grades, or why it abstained. */
27
+ export const Alignment = z.union([z.object({ graded: AlignmentAnswer }), z.object({ abstained: name })]);
28
+
26
29
  /** A finished change on its way to the base: what its diff showed, so a retry lands it again without a run. */
27
30
  export const Landing = z.object({
28
31
  item: name,
@@ -35,8 +38,10 @@ export const Landing = z.object({
35
38
  lostRaces: z.int().nonnegative().default(0),
36
39
  /** The change's patch id against the base: the same change rebased keeps its landing. */
37
40
  patch: z.string().optional(),
38
- /** The alignment call's grades, or why it abstained; made once per change. */
39
- alignment: z.union([z.object({ graded: AlignmentAnswer }), z.object({ abstained: name })]).optional(),
41
+ /** Made once per change. */
42
+ alignment: Alignment.optional(),
43
+ /** The run branch's commits past the base, oldest first, hum's done mark among them: what a push puts on the base. Absent on a landing saved before hum kept them. */
44
+ commits: z.array(name).optional(),
40
45
  });
41
46
 
42
47
  export type Landing = z.infer<typeof Landing>;
@@ -60,19 +60,28 @@ export type Choice = z.infer<typeof Choice>;
60
60
  /** A path rule the owner's answer added, with the command that takes it back. */
61
61
  const LearnedRule = z.object({ glob: name, level: name, item: name, at: time, undo: Action });
62
62
 
63
+ const count = z.int().check(z.nonnegative());
64
+
63
65
  const PerMerge = z.object({
64
- merges: z.int().check(z.nonnegative()),
66
+ merges: count,
65
67
  /** Items that never merged in the window; their costs are in the numbers. */
66
- abandoned: z.int().check(z.nonnegative()),
68
+ abandoned: count,
67
69
  notes: z.number().check(z.nonnegative()),
68
70
  questions: z.number().check(z.nonnegative()),
69
71
  tokens: z.number().check(z.nonnegative()),
70
72
  });
71
73
 
72
- /** Per merged change over the last `window` merged changes, and over each path's own last `window`. */
74
+ /** The merged changes that reached done one way, over that way's own last `window`, and how many of them a later change reverted or fixed. */
75
+ const DoneByBreaks = z.object({ doneBy: name, merges: count, reverted: count, fixed: count });
76
+
77
+ /**
78
+ * Per merged change over the last `window` merged changes, and over each path's own last `window`; then the breaks
79
+ * of each way of reaching done, which a status file an older engine wrote lacks.
80
+ */
73
81
  export const Measure = z.extend(PerMerge, {
74
82
  window: z.int().check(z.positive()),
75
83
  byPath: z.array(z.extend(PerMerge, { glob: name })),
84
+ byDoneBy: z._default(z.array(DoneByBreaks), []),
76
85
  });
77
86
 
78
87
  export type Measure = z.infer<typeof Measure>;