@moo.md/hum 0.1.0 → 0.3.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 (112) hide show
  1. package/defaults/hum.json +9 -2
  2. package/package.json +2 -2
  3. package/schema/hum.schema.json +208 -7
  4. package/scripts/eval.ts +88 -50
  5. package/src/adapter-api.ts +46 -14
  6. package/src/adapters/admit.ts +2 -2
  7. package/src/adapters/argument.ts +1 -1
  8. package/src/adapters/claim.ts +18 -15
  9. package/src/adapters/claude-bg.ts +50 -27
  10. package/src/adapters/claude-p.ts +18 -23
  11. package/src/adapters/contract.ts +22 -10
  12. package/src/adapters/each-call.ts +9 -0
  13. package/src/adapters/fake.ts +6 -6
  14. package/src/adapters/git.ts +10 -18
  15. package/src/adapters/github-client.ts +102 -0
  16. package/src/adapters/github.ts +61 -146
  17. package/src/adapters/guard.ts +20 -9
  18. package/src/adapters/history.ts +12 -15
  19. package/src/adapters/item-file.ts +1 -1
  20. package/src/adapters/markdown.ts +49 -42
  21. package/src/adapters/marked.ts +6 -12
  22. package/src/adapters/model-call.ts +4 -4
  23. package/src/adapters/once.ts +5 -5
  24. package/src/adapters/owner-commit.ts +13 -11
  25. package/src/adapters/pull-requests.ts +11 -13
  26. package/src/adapters/registry.ts +9 -8
  27. package/src/adapters/roundup.ts +27 -35
  28. package/src/adapters/serial.ts +4 -5
  29. package/src/adapters/transcript.ts +13 -8
  30. package/src/cli/main.ts +1 -0
  31. package/src/cli/ops.ts +32 -14
  32. package/src/cli/service.ts +14 -8
  33. package/src/cli/setup.ts +22 -7
  34. package/src/cli/shared-watch.ts +3 -3
  35. package/src/config/checks.ts +27 -18
  36. package/src/config/machine.ts +5 -7
  37. package/src/config/migrate.ts +5 -2
  38. package/src/config/refusal.ts +15 -2
  39. package/src/config/schema.ts +74 -12
  40. package/src/config/settings.ts +17 -2
  41. package/src/config/state-map.ts +5 -3
  42. package/src/config/wake-job.ts +74 -0
  43. package/src/decide/alignment.ts +4 -4
  44. package/src/decide/answer.ts +24 -22
  45. package/src/decide/kind.ts +1 -6
  46. package/src/decide/labels.ts +9 -9
  47. package/src/decide/merge.ts +6 -7
  48. package/src/decide/prose.ts +4 -4
  49. package/src/decide/question.ts +23 -20
  50. package/src/decide/review.ts +4 -2
  51. package/src/decide/risk.ts +25 -19
  52. package/src/decide/taste.ts +3 -3
  53. package/src/exec.ts +4 -3
  54. package/src/index.ts +14 -13
  55. package/src/loop/check-item.ts +3 -3
  56. package/src/loop/ci.ts +1 -1
  57. package/src/loop/github.ts +2 -2
  58. package/src/loop/groups.ts +13 -6
  59. package/src/loop/memory.ts +40 -28
  60. package/src/loop/notes.ts +5 -5
  61. package/src/loop/pair.ts +1 -1
  62. package/src/loop/pass.ts +18 -12
  63. package/src/loop/proof.ts +9 -7
  64. package/src/loop/prove-item.ts +1 -1
  65. package/src/loop/records.ts +12 -13
  66. package/src/loop/signals.ts +6 -6
  67. package/src/measure/inputs.ts +1 -1
  68. package/src/measure/measure.ts +4 -4
  69. package/src/measure/rate.ts +2 -0
  70. package/src/service/ci-tick.ts +2 -2
  71. package/src/service/supervise.ts +3 -2
  72. package/src/service/token.ts +3 -3
  73. package/src/service/wake.ts +2 -2
  74. package/src/service/workflows.ts +165 -48
  75. package/src/setup/propose.ts +78 -7
  76. package/src/setup/prove.ts +18 -12
  77. package/src/setup/scan.ts +91 -28
  78. package/src/setup/shipped.ts +8 -2
  79. package/src/setup/tables.ts +22 -3
  80. package/src/setup/waits.ts +9 -11
  81. package/src/setup/write.ts +67 -27
  82. package/src/slots/pool.ts +32 -24
  83. package/src/state/events.ts +1 -1
  84. package/src/state/faults.ts +13 -5
  85. package/src/state/format.ts +2 -2
  86. package/src/state/items.ts +9 -10
  87. package/src/state/open.ts +2 -2
  88. package/src/state/ops.ts +16 -10
  89. package/src/state/records.ts +5 -5
  90. package/src/state/runs.ts +33 -26
  91. package/src/state/saved.ts +44 -32
  92. package/src/status/file.ts +20 -1
  93. package/src/status/format.ts +47 -57
  94. package/src/status/sections.ts +2 -2
  95. package/src/worker/alignment-report.ts +4 -5
  96. package/src/worker/answers.ts +26 -24
  97. package/src/worker/base-check.ts +2 -2
  98. package/src/worker/kind.ts +23 -19
  99. package/src/worker/land.ts +114 -126
  100. package/src/worker/merged.ts +9 -7
  101. package/src/worker/open.ts +14 -12
  102. package/src/worker/prose-run.ts +3 -3
  103. package/src/worker/questions.ts +15 -12
  104. package/src/worker/scheduler.ts +4 -4
  105. package/src/worker/signature.ts +3 -3
  106. package/src/worker/tally.ts +0 -2
  107. package/src/worker/taste.ts +6 -15
  108. package/src/worker/thin-path.ts +148 -121
  109. package/src/worker/thread.ts +25 -0
  110. package/src/worker/worker.ts +77 -47
  111. package/surface.json +1091 -2251
  112. package/src/slots/scan.ts +0 -26
@@ -7,8 +7,9 @@ import { type Config, loadConfig, type RawConfig, readConfigDir } from "../confi
7
7
  import { hashJson } from "../config/hash.ts";
8
8
  import { Json } from "../config/json.ts";
9
9
  import { migrateConfig } from "../config/migrate.ts";
10
- import type { Refusal, Result } from "../config/refusal.ts";
11
- import { Kind, READABLE_SCHEMA_VERSIONS, SCHEMA_VERSION } from "../config/schema.ts";
10
+ import { noGitIdentity, type Refusal, type Result } from "../config/refusal.ts";
11
+ import { type HumConfig, Kind, READABLE_SCHEMA_VERSIONS, SCHEMA_VERSION } from "../config/schema.ts";
12
+ import { isGitHubHosted } from "../config/wake-job.ts";
12
13
  import { ciWorkflows } from "../service/workflows.ts";
13
14
  import { renderUnit, type UnitKind } from "../service/unit.ts";
14
15
  import { atomicWrite } from "../state/fs.ts";
@@ -28,6 +29,8 @@ export const SetupAnswers = z.strictObject({
28
29
  waitHours: z.record(z.string(), z.number().positive()).default({}),
29
30
  /** The schema version the writing skill produces; a newer one than this engine reads is refused. */
30
31
  schemaVersion: z.int().optional(),
32
+ /** Set only after the owner said yes: CI wakes may run on a runner GitHub does not host although anyone may comment on the repo. */
33
+ ownRunnerOnPublicRepo: z.literal(true).optional(),
31
34
  });
32
35
 
33
36
  export type SetupAnswers = z.infer<typeof SetupAnswers>;
@@ -41,39 +44,54 @@ export type SetupEnv = {
41
44
  readonly runtime?: { readonly bun: string; readonly path: string };
42
45
  /** The owner's name and email as git config holds them: the identity hum.json takes unless it names one already. */
43
46
  readonly gitIdentity: GitIdentityRead;
47
+ /** Whether anyone may read and comment on the repo, as GitHub says; left out where nothing could say. */
48
+ readonly isPublicRepo?: boolean;
44
49
  };
45
50
 
46
51
  export type SetupResult = { readonly ok: true; readonly written: readonly string[]; readonly config: Config } | { readonly ok: false; readonly refusal: Refusal };
47
52
 
48
53
  const UPDATE_ENGINE = "Update the engine: bun add --exact @moo.md/hum@latest.";
49
54
 
50
- /** Refuses a schema the installed engine does not read, whether the existing file has it or the writer would produce it. */
51
- const schemaRefusal = (existing: Json | undefined, target: number): Refusal | undefined => {
52
- if (!READABLE_SCHEMA_VERSIONS.includes(target)) {
53
- return {
54
- code: "unknown-schema-version",
55
- found: target,
56
- readable: READABLE_SCHEMA_VERSIONS,
57
- message: `Setup would write hum.json schemaVersion ${target}, and this engine reads ${READABLE_SCHEMA_VERSIONS.join(", ")}. ${UPDATE_ENGINE} Nothing was written.`,
58
- };
59
- }
55
+ /** Refuses answers written for a schema the installed engine does not read. */
56
+ const targetRefusal = (target: number): Refusal | undefined =>
57
+ READABLE_SCHEMA_VERSIONS.includes(target)
58
+ ? undefined
59
+ : {
60
+ code: "unknown-schema-version",
61
+ found: target,
62
+ readable: READABLE_SCHEMA_VERSIONS,
63
+ message: `Setup would write hum.json schemaVersion ${target}, and this engine reads ${READABLE_SCHEMA_VERSIONS.join(", ")}. ${UPDATE_ENGINE} Nothing was written.`,
64
+ };
60
65
 
61
- const migrated = existing === undefined ? undefined : migrateConfig(existing);
62
-
63
- return migrated && !migrated.ok ? { ...migrated.refusal, message: `${migrated.refusal.message} Nothing was written.` } : undefined;
66
+ /**
67
+ * A wake runs an agent that holds the owner's secrets. On a runner GitHub does not host, what a wake leaves behind
68
+ * stays on the machine, and on a public repo more people reach what starts a wake. So the owner says yes to the two
69
+ * together, and a repo whose visibility nothing could read counts as public.
70
+ */
71
+ const ownRunnerRefusal = ({ runPlaces, ciRunner }: HumConfig, answers: SetupAnswers, isPublicRepo: boolean | undefined): Refusal | undefined =>
72
+ !runPlaces.includes("ci") || isGitHubHosted(ciRunner) || isPublicRepo === false || answers.ownRunnerOnPublicRepo === true
73
+ ? undefined
74
+ : {
75
+ code: "own-runner-on-public-repo",
76
+ message: `ciRunner names a runner GitHub does not host, and this repo ${isPublicRepo ? "is public" : "may be public: gh could not say"}. A wake there runs an agent with your secrets on a machine that keeps what the wake leaves. Name a runner GitHub hosts, or ask the owner and set "ownRunnerOnPublicRepo": true in the answers. Nothing was written.`,
77
+ };
78
+
79
+ /** Settings migrated to the schema this engine writes, so the repo's file and the answers merge at one version; refused at a schema it does not read. */
80
+ const atCurrentSchema = (hum: Json): Result<Readonly<Record<string, Json>>> => {
81
+ const migrated = migrateConfig(hum);
82
+
83
+ return migrated.ok ? migrated : { ok: false, refusal: { ...migrated.refusal, message: `${migrated.refusal.message} Nothing was written.` } };
64
84
  };
65
85
 
66
- const noGitIdentity = (missing: readonly string[]): Refusal => ({
67
- code: "no-git-identity",
68
- missing,
69
- message: `hum commits as you, and git config holds no ${missing.join(" or ")}. Set ${missing.length === 1 ? "it" : "each"}, then run setup again: ${missing.map((key) => `git config --global ${key} "<yours>"`).join("; ")}. Nothing was written.`,
70
- });
71
-
72
86
  /** The identity hum.json already holds, else the one git config holds, else the refusal that says what to set. */
73
87
  const identityOf = (hum: Readonly<Record<string, Json>>, git: GitIdentityRead): Result<Json> => {
74
88
  if (hum.commitIdentity !== undefined) return { ok: true, value: hum.commitIdentity };
75
89
 
76
- return git.found ? { ok: true, value: asJson(git.identity) } : { ok: false, refusal: noGitIdentity(git.missing) };
90
+ if (git.found) return { ok: true, value: asJson(git.identity) };
91
+
92
+ const refusal = noGitIdentity(git.missing);
93
+
94
+ return { ok: false, refusal: { ...refusal, message: `${refusal.message} Nothing was written.` } };
77
95
  };
78
96
 
79
97
  const readExisting = (repo: string): RawConfig | undefined => (existsSync(join(repo, ".hum", "hum.json")) ? readConfigDir(join(repo, ".hum")) : undefined);
@@ -101,25 +119,39 @@ const asJson = (value: Kind | Readonly<Record<string, Json>>): Json => Json.pars
101
119
  */
102
120
  export const writeSetup = (repo: string, answers: SetupAnswers, env: SetupEnv): SetupResult => {
103
121
  const existing = readExisting(repo);
104
- const refused = schemaRefusal(existing?.hum, answers.schemaVersion ?? SCHEMA_VERSION);
122
+ const target = answers.schemaVersion ?? SCHEMA_VERSION;
123
+ const refused = targetRefusal(target);
105
124
 
106
125
  if (refused) return { ok: false, refusal: refused };
107
126
 
108
127
  const shipped = shippedRaw();
109
128
  const base = existing ?? shipped;
129
+ const fromRepo = atCurrentSchema(base.hum);
130
+
131
+ if (!fromRepo.ok) return fromRepo;
132
+
133
+ const answered = atCurrentSchema({ ...answers.hum, schemaVersion: target });
134
+
135
+ if (!answered.ok) return answered;
136
+
110
137
  const shippedHum = HumObject.parse(shipped.hum);
111
- const given = { ...HumObject.parse(base.hum), ...answers.hum };
138
+ const given = { ...fromRepo.value, ...answered.value };
112
139
  const identity = identityOf(given, env.gitIdentity);
113
140
 
114
141
  if (!identity.ok) return identity;
115
142
 
116
143
  const hum = { ...given, commitIdentity: identity.value };
117
- const kinds = Object.fromEntries(Object.entries(withTimeouts(parseKinds(base), answers.waitHours)).map(([name, kind]) => [name, asJson(kind)]));
144
+ const timed = withTimeouts(parsedKinds(base), answers.waitHours);
145
+ const kinds = Object.fromEntries(Object.entries(base.kinds).map(([name, file]) => [name, timed[name] ? asJson(timed[name]) : file]));
118
146
  const roles = { ...shipped.roles, ...existing?.roles };
119
147
  const loaded = loadConfig({ hum: asJson(hum), kinds, roles }, { env: { hopeSkills: env.hopeSkills } });
120
148
 
121
149
  if (!loaded.ok) return { ok: false, refusal: loaded.refusal };
122
150
 
151
+ const ownRunner = ownRunnerRefusal(loaded.value.hum, answers, env.isPublicRepo);
152
+
153
+ if (ownRunner) return { ok: false, refusal: ownRunner };
154
+
123
155
  const files = [
124
156
  { path: join(repo, ".hum", "hum.json"), text: jsonText(ownerKeys(hum, shippedHum)) },
125
157
  ...Object.entries(kinds).map(([name, kind]) => ({ path: join(repo, ".hum", "kinds", `${name}.json`), text: jsonText(kind) })),
@@ -135,7 +167,15 @@ export const writeSetup = (repo: string, answers: SetupAnswers, env: SetupEnv):
135
167
  return { ok: true, written: files.map(({ path }) => path), config: loaded.value };
136
168
  };
137
169
 
138
- const parseKinds = (raw: RawConfig): Record<string, Kind> => Object.fromEntries(Object.entries(raw.kinds).map(([name, file]) => [name, Kind.parse(file)]));
170
+ /** The kind files that parse. One that does not stays as it is, so the config check refuses it by name. */
171
+ const parsedKinds = (raw: RawConfig): Record<string, Kind> =>
172
+ Object.fromEntries(
173
+ Object.entries(raw.kinds).flatMap(([name, file]) => {
174
+ const kind = Kind.safeParse(file);
175
+
176
+ return kind.success ? [[name, kind.data]] : [];
177
+ }),
178
+ );
139
179
 
140
180
  const serviceFile = (repo: string, config: Config, env: SetupEnv): FileToWrite => {
141
181
  const kind: UnitKind = (env.platform ?? process.platform) === "darwin" ? "launchd" : "systemd";
@@ -157,5 +197,5 @@ const serviceFile = (repo: string, config: Config, env: SetupEnv): FileToWrite =
157
197
  };
158
198
  };
159
199
 
160
- /** The answers file the skill writes: `{ "hum": {...}, "waitHours": {...}, "schemaVersion": 1 }`. */
200
+ /** The answers file the skill writes: `{ "hum": {...}, "waitHours": {...}, "schemaVersion": 2 }`, with `"ownRunnerOnPublicRepo": true` once the owner agreed to it. */
161
201
  export const readAnswers = (file: string): SetupAnswers => SetupAnswers.parse(JSON.parse(readFileSync(file, "utf8")));
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
  }