@moo.md/hum 0.3.0 → 0.4.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 (67) hide show
  1. package/defaults/hum.json +5 -0
  2. package/defaults/roles/build.md +1 -1
  3. package/defaults/roles/fix.md +1 -1
  4. package/npm-shrinkwrap.json +3297 -0
  5. package/package.json +6 -2
  6. package/release.json +3 -0
  7. package/schema/hum.schema.json +47 -7
  8. package/scripts/eval.ts +21 -5
  9. package/src/adapter-api.ts +3 -1
  10. package/src/adapters/claude-bg.ts +2 -2
  11. package/src/adapters/claude-p.ts +44 -18
  12. package/src/adapters/contract.ts +12 -0
  13. package/src/adapters/fake.ts +5 -0
  14. package/src/adapters/git.ts +61 -9
  15. package/src/adapters/github-client.ts +15 -0
  16. package/src/adapters/github-commits.ts +84 -0
  17. package/src/adapters/github.ts +9 -0
  18. package/src/adapters/guard.ts +1 -0
  19. package/src/adapters/item-file.ts +1 -1
  20. package/src/adapters/markdown.ts +10 -1
  21. package/src/adapters/pull-requests.ts +8 -8
  22. package/src/adapters/registry.ts +3 -6
  23. package/src/adapters/roundup.ts +3 -0
  24. package/src/bytes.ts +1 -0
  25. package/src/cli/service.ts +176 -29
  26. package/src/cli/setup.ts +4 -5
  27. package/src/config/checks.ts +21 -50
  28. package/src/config/load.ts +2 -3
  29. package/src/config/machine.ts +29 -0
  30. package/src/config/refusal.ts +5 -6
  31. package/src/config/schema.ts +23 -7
  32. package/src/config/wake-job.ts +6 -2
  33. package/src/decide/risk.ts +2 -2
  34. package/src/exec.ts +10 -0
  35. package/src/index.ts +1 -1
  36. package/src/loop/records.ts +8 -1
  37. package/src/measure/rate.ts +14 -0
  38. package/src/publish/bundle.ts +128 -0
  39. package/src/publish/handoff.ts +107 -0
  40. package/src/publish/handover.ts +182 -0
  41. package/src/publish/intents.ts +61 -0
  42. package/src/publish/publisher.ts +259 -0
  43. package/src/publish/wake.ts +78 -0
  44. package/src/service/ci-state.ts +99 -0
  45. package/src/service/plugins.ts +137 -0
  46. package/src/service/wake.ts +3 -1
  47. package/src/service/workflows.ts +122 -28
  48. package/src/setup/propose.ts +17 -4
  49. package/src/setup/prove.ts +3 -3
  50. package/src/setup/write.ts +2 -2
  51. package/src/state/items.ts +17 -8
  52. package/src/state/open.ts +20 -6
  53. package/src/state/records.ts +7 -0
  54. package/src/state/runs.ts +5 -0
  55. package/src/state/saved.ts +17 -2
  56. package/src/worker/base-check.ts +41 -13
  57. package/src/worker/checks.ts +3 -2
  58. package/src/worker/evidence.ts +72 -0
  59. package/src/worker/kind.ts +4 -7
  60. package/src/worker/land.ts +173 -81
  61. package/src/worker/merged.ts +20 -8
  62. package/src/worker/open.ts +33 -17
  63. package/src/worker/questions.ts +16 -8
  64. package/src/worker/signed-push.ts +167 -0
  65. package/src/worker/thin-path.ts +245 -133
  66. package/src/worker/worker.ts +50 -9
  67. package/surface.json +185 -56
@@ -6,7 +6,7 @@ export type Problem =
6
6
  | { readonly problem: "event-without-source"; readonly event: string; readonly source: string | undefined }
7
7
  | { readonly problem: "event-without-handler"; readonly event: string }
8
8
  | { readonly problem: "run-and-owner-wait"; readonly kind: string; readonly state: string }
9
- | { readonly problem: "missing-hope-skill"; readonly skill: string; readonly role: string }
9
+ | { readonly problem: "missing-skill"; readonly skill: string; readonly role: string }
10
10
  | { readonly problem: "unknown-state"; readonly kind: string; readonly state: string; readonly why: string }
11
11
  | { readonly problem: "unknown-run-source"; readonly kind: string; readonly state: string; readonly src: string }
12
12
  | { readonly problem: "tier-table-gap"; readonly kind: string; readonly purpose: string; readonly level: string; readonly size: string }
@@ -16,7 +16,7 @@ export type Problem =
16
16
  | { readonly problem: "path-without-proof"; readonly glob: string; readonly level: string }
17
17
  | { readonly problem: "overlapping-prefixes"; readonly run: string; readonly claim: string }
18
18
  | { readonly problem: "wake-env-taken"; readonly name: string }
19
- | { readonly problem: "wake-outlasts-app-token"; readonly minutes: number; readonly tokenMinutes: number };
19
+ | { readonly problem: "merge-margin-fills-token-hour"; readonly minutes: number; readonly tokenMinutes: number };
20
20
 
21
21
  /** A config change the engine will not take. The caller keeps the last good config. */
22
22
  export type Refusal =
@@ -40,7 +40,7 @@ const DESCRIPTIONS = {
40
40
  p.source === undefined ? `event "${p.event}" is waited on but declared nowhere` : `event "${p.event}" has no source: "${p.source}" is not a part or role`,
41
41
  "event-without-handler": (p) => `event "${p.event}" has no handler in any kind`,
42
42
  "run-and-owner-wait": (p) => `${p.kind}: state "${p.state}" starts a run and waits on the owner`,
43
- "missing-hope-skill": (p) => `role "${p.role}" names hope skill "${p.skill}", which hope's installed copy lacks`,
43
+ "missing-skill": (p) => `role "${p.role}" names skill "${p.skill}", which no installed plugin has`,
44
44
  "unknown-state": (p) => `${p.kind}: ${p.why} names state "${p.state}", which does not exist`,
45
45
  "unknown-run-source": (p) => `${p.kind}: state "${p.state}" invokes "${p.src}", which is neither a role nor a part`,
46
46
  "tier-table-gap": (p) => `${p.kind}: no tier for purpose "${p.purpose}", level "${p.level}", size "${p.size}"`,
@@ -49,9 +49,8 @@ const DESCRIPTIONS = {
49
49
  "unknown-level": (p) => `risk level "${p.level}" is not in levels`,
50
50
  "path-without-proof": (p) => `path "${p.glob}" is at level "${p.level}", whose release waits for proof, and names no proof for every kind`,
51
51
  "overlapping-prefixes": (p) => `the run branch prefix "${p.run}" and the claim prefix "${p.claim}" overlap: one starts with the other`,
52
- "wake-env-taken": (p) => `ciEnv sets ${p.name}, which the CI wake job sets itself`,
53
- "wake-outlasts-app-token": (p) =>
54
- `ciWakeTimeoutMinutes is ${p.minutes}, and the token a GitHub App mints lasts ${p.tokenMinutes} minutes: a longer wake loses GitHub before it ends`,
52
+ "wake-env-taken": (p) => `ciEnv sets ${p.name}, which the CI wake's jobs set themselves`,
53
+ "merge-margin-fills-token-hour": (p) => `ciMergeMarginMinutes is ${p.minutes}, and the token a GitHub App mints lasts ${p.tokenMinutes} minutes: publish would never have time left to merge`,
55
54
  } as const satisfies Describe;
56
55
 
57
56
  // SAFETY: each description is keyed by the problem name it reads, so the lookup by `problem.problem` takes its own variant.
@@ -23,6 +23,12 @@ export const FIXED_PARTS = [
23
23
  ] as const;
24
24
 
25
25
  export const PURPOSES = ["plan", "build", "fix", "review"] as const;
26
+
27
+ /** The integration slots `hum.json` `integrations` names, each to an adapter. */
28
+ export const SLOTS = ["work-source", "questions", "answers", "release"] as const;
29
+
30
+ export type Slot = (typeof SLOTS)[number];
31
+
26
32
  export const SIZES = ["small", "medium", "large"] as const;
27
33
  const TIERS = ["light", "standard", "top"] as const;
28
34
  export const EFFORTS = ["low", "medium", "high"] as const;
@@ -202,19 +208,24 @@ const Shipped = z.object({
202
208
  restartBackoff: backoff.describe("The pause before the service's first restart of a crashed worker, doubled each crash up to the longest pause."),
203
209
  restartDelaySeconds: seconds.describe("Seconds the service manager waits before it starts a failed start script again."),
204
210
  pullRequestToken: PullRequestToken.describe(
205
- "Where a CI run's GitHub token comes from: { from: 'secret', secret } names a repository secret that holds a fine-grained token; { from: 'app', clientIdSecret, privateKeySecret } names the two secrets a GitHub App mints a token from each run, with the workflow's own permissions. clientIdSecret holds the App's client ID or its older App ID: the action that mints the token reads either as the same input. A pull request opened with the workflow token starts no workflows, so its required checks never run; one opened with this token does. A CI run falls back to the workflow token while the secret, or the client ID secret, is unset.",
211
+ "Where a CI run's GitHub token comes from: { from: 'secret', secret } names a repository secret that holds a fine-grained token; { from: 'app', clientIdSecret, privateKeySecret } names the two secrets a GitHub App mints a token from each run, with the workflow's own permissions. clientIdSecret holds the App's client ID or its older App ID: the action that mints the token reads either as the same input. A pull request opened with the workflow token starts no workflows, so its required checks never run; one opened with this token does. A CI run falls back to the workflow token while the secret is unset; a wake whose App secrets are unset stops with an error.",
206
212
  ),
207
- ciWakeTimeoutMinutes: count.describe("Minutes a CI wake may run before GitHub stops it."),
213
+ ciWakeTimeoutMinutes: count.describe("Minutes the CI wake's work job, which runs the runs, may run before GitHub stops it; the two jobs that hold GitHub's token stop within its hour."),
214
+ ciOutboxMaxMegabytes: count.describe("Megabytes of a CI work job's outbox, its bundles and its state, past which publish refuses the whole wake before any write."),
215
+ ciUsageLimitMaxHours: count.describe("Hours from now past which publish cuts the reset time of a usage limit a CI work job reports, so no work job can hold hum's runs longer than Claude's own limit window."),
216
+ followUpsPerPass: count.describe("Follow-up items one pass may file; publish refuses a pass that files more, and each one it files counts against the daily question cap."),
217
+ publishTreeMaxMegabytes: count.describe("Megabytes of the tree a pass's branch holds, past which publish refuses the pass before it checks the branch out."),
218
+ ciMergeMarginMinutes: count.describe("Minutes of the GitHub App token's hour publish keeps in hand: past the rest, it saves a landing and leaves its merge to the next wake."),
208
219
  ciRunner: Runner.describe(
209
- "What the CI wake job runs on, as a workflow's runs-on holds it: one runner label, a list of labels the runner must carry all of, or { group, labels } for a runner group. On a public repo, a runner GitHub does not host keeps what a wake leaves on it, and setup asks before it writes one.",
220
+ "What each job of the CI wake runs on, as a workflow's runs-on holds it: one runner label, a list of labels the runner must carry all of, or { group, labels } for a runner group. On a public repo, a runner GitHub does not host keeps what a job leaves on it, and setup asks before it writes one.",
210
221
  ),
211
222
  ciContainer: Container.nullable().describe(
212
- "The container the CI wake job runs in: its image, or { image, credentials: { username, password }, env, ports, volumes, options } as a workflow's container holds them, or null to run on the runner itself. The image needs git, node and npm; a container that runs as root needs IS_SANDBOX=1 in ciEnv, or Claude Code refuses to skip its permission prompts.",
223
+ "The container each job of the CI wake runs in: its image, or { image, credentials: { username, password }, env, ports, volumes, options } as a workflow's container holds them, or null to run on the runner itself. The image needs git, node and npm; a container that runs as root needs IS_SANDBOX=1 in ciEnv, or Claude Code refuses to skip its permission prompts.",
213
224
  ),
214
225
  ciEnv: z
215
226
  .record(envName, z.string())
216
227
  .describe(
217
- "Env the CI wake job sets, such as a gateway's settings; a value may be a workflow expression. A value that reads a secret reaches only the step that runs hum; every other value reaches every step, the installs too. A name the job sets itself, such as GH_TOKEN, is refused.",
228
+ "Env the CI wake's jobs set, such as a gateway's settings; a value may be a workflow expression. A value that reads a secret reaches only the steps that run hum; every other value reaches every step, the installs too. A name the jobs set themselves, such as GH_TOKEN, is refused.",
218
229
  ),
219
230
  ciClaudeAuth: z
220
231
  .enum(CLAUDE_AUTHS)
@@ -352,11 +363,11 @@ export const HumConfig = z.strictObject({
352
363
  safety: z.record(z.string(), z.unknown()).optional(),
353
364
  dailyQuestionCap: z.number().int().positive().optional(),
354
365
  /** Adapter slot → adapter name. */
355
- integrations: z.record(name, name).optional(),
366
+ integrations: z.partialRecord(z.enum(SLOTS), name).optional(),
356
367
  /** The day `claude setup-token` made the CI token. Setup records it; the engine warns 30 days before the year ends. */
357
368
  ciToken: z.strictObject({ setUp: z.iso.date() }).optional(),
358
369
  /** No default: a commit is credited to whichever account lists its email, so only the owner's own is safe. */
359
- commitIdentity: commitIdentity.describe("The owner's own name and email: the author and committer of every commit hum makes. Setup writes them from git config; hum ships none."),
370
+ commitIdentity: commitIdentity.describe("The owner's own name and email: the author and committer of every commit hum makes with git. Where the base requires signed commits, GitHub makes the commits and credits them to the account of the token hum writes with: the owner's own on a Mac; in CI, the GitHub App's bot or the account whose token pullRequestToken names. Setup writes them from git config; hum ships none."),
360
371
  ...withShippedDefaults(Shipped.shape),
361
372
  });
362
373
 
@@ -475,6 +486,11 @@ export const OWNER_CHANGEABLE = {
475
486
  "restart backoff": "restartBackoff",
476
487
  "restart delay": "restartDelaySeconds",
477
488
  "CI wake timeout": "ciWakeTimeoutMinutes",
489
+ "CI outbox cap": "ciOutboxMaxMegabytes",
490
+ "CI usage limit cap": "ciUsageLimitMaxHours",
491
+ "follow-ups per pass": "followUpsPerPass",
492
+ "publish tree cap": "publishTreeMaxMegabytes",
493
+ "CI merge margin": "ciMergeMarginMinutes",
478
494
  "pull request token": "pullRequestToken",
479
495
  "CI runner": "ciRunner",
480
496
  "CI container": "ciContainer",
@@ -3,12 +3,12 @@ import type { HumConfig } from "./schema.ts";
3
3
  /** The secret Claude Code's OAuth token is stored in, under the env name Claude Code reads it from. */
4
4
  export const CLAUDE_TOKEN = "CLAUDE_CODE_OAUTH_TOKEN";
5
5
 
6
- /** The env the wake job sets itself. */
6
+ /** The env the wake's jobs set themselves. */
7
7
  export const WAKE_ENV = {
8
8
  claudeToken: CLAUDE_TOKEN,
9
9
  githubToken: "GH_TOKEN",
10
10
  event: "HUM_EVENT",
11
- /** Whether the App's client ID secret is set, because a step's `if` cannot read a secret. */
11
+ /** Whether both of the App's secrets are set, because a step's `if` cannot read a secret. */
12
12
  hasApp: "HUM_HAS_APP",
13
13
  gitName: "HUM_GIT_NAME",
14
14
  gitEmail: "HUM_GIT_EMAIL",
@@ -16,6 +16,10 @@ export const WAKE_ENV = {
16
16
  gitCredentialHelper: "HUM_GIT_CREDENTIAL_HELPER",
17
17
  /** Git's own name for the file `git config --global` writes: the job points it into the runner's temp folder. */
18
18
  gitConfig: "GIT_CONFIG_GLOBAL",
19
+ /** What gather settled, from its job outputs, for the publish job. */
20
+ gathered: "HUM_GATHERED",
21
+ /** The workflow's own token, with which the publish job reads the outbox artifact's size before it downloads it. */
22
+ actionsToken: "HUM_ACTIONS_TOKEN",
19
23
  } as const;
20
24
 
21
25
  /** The env names the wake job sets itself, which `ciEnv` may not set. */
@@ -2,8 +2,8 @@ import { quantile } from "simple-statistics";
2
2
  import { z } from "zod";
3
3
  import type { HumConfig, Launch, Level, PathRule } from "../config/schema.ts";
4
4
 
5
- /** What only the owner changes: hum's own config, the owner's adapters and the CI workflows. */
6
- const OWN_PATHS = [".hum/**", "adapters/**", ".github/workflows/**"] as const;
5
+ /** What only the owner changes: hum's own config, the owner's adapters, the CI workflows, and Claude Code's project settings, whose plugins and hooks load in every run. */
6
+ const OWN_PATHS = [".hum/**", "adapters/**", ".github/workflows/**", ".claude/**"] as const;
7
7
 
8
8
  /** What hum reads from a change's diff. */
9
9
  export const Change = z
package/src/exec.ts CHANGED
@@ -6,6 +6,16 @@ import { SECOND_MS } from "./time.ts";
6
6
  /** A process environment: the root reads `process.env` once and hands it down. */
7
7
  export type Env = Readonly<Record<string, string | undefined>>;
8
8
 
9
+ /** The GitHub tokens hum pushes and calls GitHub with. A comment can steer a run, and a run writes the code the checks run, so neither holds one. */
10
+ const GITHUB_TOKENS = ["GH_TOKEN", "GITHUB_TOKEN"] as const;
11
+
12
+ /**
13
+ * The environment as a run and the repo's checks get it: everything but the GitHub tokens, which only hum itself uses.
14
+ * tinyexec starts every child from `process.env` and lays this over it, so a token is kept out by naming it with no
15
+ * value, which the runtime drops; leaving the name out would let `process.env` put it back.
16
+ */
17
+ export const withoutGitHubTokens = (env: Env) => ({ ...env, ...Object.fromEntries(GITHUB_TOKENS.map((name) => [name, undefined])) });
18
+
9
19
  /** A command ran past its limit and was told to stop. */
10
20
  export class CommandTimedOut extends Error {
11
21
  override name = "CommandTimedOut";
package/src/index.ts CHANGED
@@ -15,7 +15,7 @@ export { Json } from "./config/json.ts";
15
15
 
16
16
  export {
17
17
  type Config,
18
- listHopeSkills,
18
+ listPluginSkills,
19
19
  loadConfig,
20
20
  type LoadOptions,
21
21
  type RawConfig,
@@ -51,7 +51,14 @@ export const PossibleRepeat = z.object({ a: name, b: name, models: z.array(name)
51
51
  export type PossibleRepeat = z.infer<typeof PossibleRepeat>;
52
52
 
53
53
  /** A merged change: what the measure counts. */
54
- export const Merge = z.object({ item: name, sha: name, at: time, paths: z.array(name) });
54
+ export const Merge = z.object({
55
+ item: name,
56
+ sha: name,
57
+ at: time,
58
+ paths: z.array(name),
59
+ /** The repo's checks have run on the base since it merged; a merge saved before hum checked the base counts as checked. */
60
+ baseChecked: z.boolean().default(true),
61
+ });
55
62
 
56
63
  export type Merge = z.infer<typeof Merge>;
57
64
 
@@ -1,2 +1,16 @@
1
+ import type { Boundary } from "../config/schema.ts";
2
+
1
3
  /** The share of measured cases a model got right; none when nothing was measured, so no rate stands in for a measurement. */
2
4
  export const rateOf = (right: number, measured: number): number | undefined => (measured === 0 ? undefined : right / measured);
5
+
6
+ const RATE_DIGITS = 2;
7
+
8
+ /**
9
+ * The owner's measured rates with one pooled rate set at `boundary`, under the model as the owner names it and under
10
+ * each model id that answered while it was measured. Trust compares the ids a call's answer names, which an alias
11
+ * such as `haiku` never is, and the pre-call checks read the name in the owner's settings.
12
+ */
13
+ export const withRate = <M extends Partial<Record<Boundary, Readonly<Record<string, number>>>>>(measured: M, { boundary, model, answered, rate }: { readonly boundary: Boundary; readonly model: string; readonly answered: readonly string[]; readonly rate: number }): M => ({
14
+ ...measured,
15
+ [boundary]: { ...measured[boundary], ...Object.fromEntries([model, ...answered].map((id) => [id, Number(rate.toFixed(RATE_DIGITS))])) },
16
+ });
@@ -0,0 +1,128 @@
1
+ import { type Git, type GitIdentity, PATCH } from "../adapters/git.ts";
2
+
3
+ /** Where publish keeps the refs it read from an outbox's bundle, apart from every ref of its own. */
4
+ export const OUTBOX_REFS = "refs/hum/outbox/";
5
+
6
+ /** The ref an item's evidence is kept on; its tip is one commit with no parent. */
7
+ export const EVIDENCE_REFS = "refs/hum/evidence/";
8
+
9
+ /** What publish trusts a bundle against: what gather handed on and the config at gather's base. */
10
+ export type BundleTrust = {
11
+ /** The base commit gather saw. */
12
+ readonly base: string;
13
+ /** The hum branch heads gather put in the inbox. */
14
+ readonly heads: readonly string[];
15
+ /** The owner's commitIdentity in the config at `base`. */
16
+ readonly identity: GitIdentity;
17
+ /** The branch prefixes hum writes, from the config at `base`: run branches and the owner's own. */
18
+ readonly branchPrefixes: readonly string[];
19
+ /** The base's rules require signed commits, so a branch goes through GitHub's API, which carries no file mode or link. */
20
+ readonly signs: boolean;
21
+ };
22
+
23
+ /** A bundle's refs as the work job named them, each at its tip. */
24
+ export type BundleRefs = ReadonlyMap<string, string>;
25
+
26
+ export type BundleCheck = { readonly ok: true; readonly refs: BundleRefs } | { readonly ok: false; readonly why: string };
27
+
28
+ const FIELD = "\u001f";
29
+
30
+ /** One new commit: its sha, its parents, its author and its committer. */
31
+ const COMMIT_FORMAT = ["%H", "%P", "%an", "%ae", "%cn", "%ce"].join("%x1f");
32
+
33
+ /** The one file mode GitHub's API writes. A link, a submodule or an executable bit comes back as another tree. */
34
+ const API_MODE = "100644";
35
+
36
+ const DELETED = "D";
37
+
38
+ const isAllowedRef = (ref: string, { branchPrefixes }: BundleTrust): boolean => ref.startsWith(EVIDENCE_REFS) || branchPrefixes.some((prefix) => ref.startsWith(`refs/heads/${prefix}`));
39
+
40
+ const refsOf = async (git: Git, bundle: string): Promise<Map<string, string>> =>
41
+ new Map(
42
+ (await git.raw(["bundle", "list-heads", bundle]))
43
+ .split("\n")
44
+ .filter(Boolean)
45
+ .map((line) => {
46
+ const [sha = "", ref = ""] = line.split(" ");
47
+
48
+ return [ref, sha] as const;
49
+ }),
50
+ );
51
+
52
+ type NewCommit = { readonly sha: string; readonly parents: readonly string[]; readonly author: string; readonly committer: string };
53
+
54
+ /** The commits the tips reach that neither gather's base nor an inbox head reaches. */
55
+ const newCommits = async (git: Git, tips: readonly string[], trust: BundleTrust): Promise<NewCommit[]> =>
56
+ (await git.raw(["log", `--format=${COMMIT_FORMAT}`, ...tips, "--not", trust.base, ...trust.heads]))
57
+ .split("\n")
58
+ .filter(Boolean)
59
+ .map((line) => {
60
+ const [sha = "", parents = "", authorName, authorEmail, committerName, committerEmail] = line.split(FIELD);
61
+
62
+ return { sha, parents: parents.split(" ").filter(Boolean), author: `${authorName} <${authorEmail}>`, committer: `${committerName} <${committerEmail}>` };
63
+ });
64
+
65
+ /**
66
+ * Why the commits break the owner's rules: each is by commitIdentity, and each parent is another new commit, gather's
67
+ * base or an inbox head. Only an evidence ref's tip has no parent. The identity check stops a commit made under the
68
+ * wrong name by mistake; a hostile work job writes any name it likes, so the walls against it are the ref check and
69
+ * publish placing the change from its own diff and config.
70
+ */
71
+ const commitFault = (commits: readonly NewCommit[], evidenceTips: ReadonlySet<string>, trust: BundleTrust): string | undefined => {
72
+ const owner = `${trust.identity.name} <${trust.identity.email}>`;
73
+ const known = new Set([trust.base, ...trust.heads, ...commits.map(({ sha }) => sha)]);
74
+
75
+ for (const { sha, parents, author, committer } of commits) {
76
+ if (author !== owner || committer !== owner) return `commit ${sha} is by ${author}, committed by ${committer}, not by commitIdentity ${owner}`;
77
+
78
+ if (parents.length === 0 && !evidenceTips.has(sha)) return `commit ${sha} has no parent and is no evidence ref's tip`;
79
+
80
+ const stranger = parents.find((parent) => !known.has(parent));
81
+
82
+ if (stranger !== undefined) return `commit ${sha} grows from ${stranger}, which is neither the base gather saw nor a hum branch it handed on`;
83
+ }
84
+
85
+ return undefined;
86
+ };
87
+
88
+ /** The first path a branch changes, against where it left gather's base, that GitHub's API cannot carry. */
89
+ const uncarried = async (git: Git, tip: string, base: string): Promise<string | undefined> => {
90
+ const from = (await git.raw(["merge-base", tip, base])).trim();
91
+ const fields = (await git.raw(["diff", "--raw", "--no-abbrev", "--no-renames", "-z", ...PATCH, from, tip])).split("\0").filter(Boolean);
92
+
93
+ return fields.flatMap((meta, at) => {
94
+ const [, mode = "", , , status = ""] = meta.split(" ");
95
+
96
+ return at % 2 === 0 && status !== DELETED && mode !== API_MODE ? [`${fields[at + 1] ?? ""} (mode ${mode})`] : [];
97
+ })[0];
98
+ };
99
+
100
+ /**
101
+ * Reads an outbox's bundle into publish's repo under `OUTBOX_REFS` and checks it before any write: every ref is one
102
+ * hum writes, every object passes git's own check, every new commit is by commitIdentity and grows from gather's base
103
+ * or a hum branch it handed on, and on a base that requires signed commits no branch changes a mode GitHub's API
104
+ * cannot carry. The repo must already hold gather's base and heads.
105
+ */
106
+ export const checkBundle = async (git: Git, bundle: string, trust: BundleTrust): Promise<BundleCheck> => {
107
+ const verified = await git.run(["bundle", "verify", "-q", bundle]);
108
+
109
+ if (verified.code !== 0) return { ok: false, why: `the bundle does not verify against what gather handed on: ${verified.stderr.trim()}` };
110
+
111
+ const refs = await refsOf(git, bundle);
112
+ const foreign = [...refs.keys()].find((ref) => !isAllowedRef(ref, trust));
113
+
114
+ if (foreign !== undefined) return { ok: false, why: `the bundle names ${foreign}, which is no ref hum writes` };
115
+
116
+ await git.raw(["-c", "transfer.fsckObjects=true", "fetch", "-q", "--no-tags", bundle, ...[...refs.keys()].map((ref) => `+${ref}:${OUTBOX_REFS}${ref.slice("refs/".length)}`)]);
117
+
118
+ const evidenceTips = new Set([...refs].flatMap(([ref, sha]) => (ref.startsWith(EVIDENCE_REFS) ? [sha] : [])));
119
+ const fault = commitFault(await newCommits(git, [...refs.values()], trust), evidenceTips, trust);
120
+
121
+ if (fault !== undefined) return { ok: false, why: fault };
122
+
123
+ const branches = [...refs].filter(([ref]) => !ref.startsWith(EVIDENCE_REFS));
124
+ const carried = trust.signs ? await Promise.all(branches.map(async ([ref, tip]) => ({ ref, path: await uncarried(git, tip, trust.base) }))) : [];
125
+ const refused = carried.find(({ path }) => path !== undefined);
126
+
127
+ return refused ? { ok: false, why: `${refused.ref} changes ${refused.path}, which a commit through GitHub's API cannot carry` } : { ok: true, refs };
128
+ };
@@ -0,0 +1,107 @@
1
+ import { copyFileSync, mkdirSync } from "node:fs";
2
+ import { dirname } from "node:path";
3
+ import { savedLimitUntil, settleLimit } from "../adapters/limit.ts";
4
+ import { nextStates, reachedFrom } from "../config/machine.ts";
5
+ import { type Config } from "../config/load.ts";
6
+ import { type Kind, OWNER_WAIT_TAG } from "../config/schema.ts";
7
+ import type { State } from "../state/open.ts";
8
+ import type { Spent } from "../state/saved.ts";
9
+ import { queuedKey } from "../worker/questions.ts";
10
+ import { OWNER_APPROVAL } from "../decide/merge.ts";
11
+ import { SNAPSHOT_CARDS } from "../state/items.ts";
12
+
13
+ /** Where publish found an item's saved machine state before the work job ran, and whether the owner had answered. */
14
+ export type InboxItem = {
15
+ readonly item: string;
16
+ readonly kind: Kind;
17
+ /** The machine's state in the inbox, or undefined when the item had none. */
18
+ readonly at: string | undefined;
19
+ /** The inbox thread holds the owner's answer to the wait the item is in. */
20
+ readonly answered: boolean;
21
+ };
22
+
23
+ const isOwnerWait = (kind: Kind, state: string): boolean => kind.machine.states[state]?.tags?.includes(OWNER_WAIT_TAG) ?? false;
24
+
25
+ /**
26
+ * The states one pass may carry an item to from where the inbox saved it: through every transition of its kind's
27
+ * machine, past the owner's wait it starts in only with the owner's answer, and never past another owner's wait.
28
+ */
29
+ export const passReach = ({ kind, at, answered }: Omit<InboxItem, "item">): ReadonlySet<string> => {
30
+ const start = at ?? kind.machine.initial;
31
+
32
+ return reachedFrom(start, nextStates(kind), (state) => !isOwnerWait(kind, state) || (state === start && answered));
33
+ };
34
+
35
+ /** The rank of a kind's floor among the levels; a kind with no floor ranks lowest. */
36
+ const floorRank = (config: Config, kind: string): number => {
37
+ const floor = config.hum.kindFloors[kind];
38
+
39
+ return floor === undefined ? -1 : config.hum.levels.findIndex(({ name }) => name === floor);
40
+ };
41
+
42
+ /** Why a work job may not move an item from one kind to another: it names the kind the item has, or one whose risk floor is lower. */
43
+ export const kindMoveFault = (config: Config, { from, to }: { readonly from: string; readonly to: string }): string | undefined => {
44
+ if (to === from) return `it moves the item to ${to}, the kind it already has`;
45
+
46
+ return floorRank(config, to) < floorRank(config, from) ? `it moves the item from ${from} to ${to}, whose risk floor is lower` : undefined;
47
+ };
48
+
49
+ /**
50
+ * An item's spend as publish takes it from a work job: the total only rises, and the count toward the kind's cap
51
+ * starts afresh only where the owner answered.
52
+ */
53
+ const raisedSpend = (held: Spent | undefined, worked: Spent, answered: boolean): Spent => {
54
+ const total = Math.max(held?.total ?? 0, worked.total);
55
+ const base = held?.base ?? 0;
56
+
57
+ return { item: worked.item, total, base: answered ? Math.min(Math.max(base, worked.base), total) : base };
58
+ };
59
+
60
+ /** The cards a work job raises on an item that publish shows: those of its saved state, never one with an action. */
61
+ const WORK_CARD_CODES: ReadonlySet<string> = new Set(Object.values(SNAPSHOT_CARDS));
62
+
63
+ /**
64
+ * Takes into publish's state what a work job wrote for one item it ran, and nothing else: the item's machine state
65
+ * when it is one a pass can reach from the inbox's, its runs, its spend where it raises publish's, its plan, whose
66
+ * models land reads beside the ones the config gives the plan run, its pull request text, its proof,
67
+ * the questions it queued, never offering the owner's approval, its choices, its events, its saved state's cards with
68
+ * no action, and the usage limit cut to `usageLimitMaxMs` from now. Landings, verdicts, merges, learned rules, kinds,
69
+ * answers and op keys stay as publish has them. Returns why the machine state was refused, or nothing once all is taken.
70
+ */
71
+ export const takeWorkRecords = (work: State, into: State, inbox: InboxItem, limits: { readonly now: number; readonly usageLimitMaxMs: number }): string | undefined => {
72
+ const { item, kind } = inbox;
73
+ const saved = work.items.saved().find(({ itemId }) => itemId === item);
74
+
75
+ if (saved !== undefined) {
76
+ if (saved.kind !== kind.machine.id || saved.machineVersion !== kind.machine.version) return `the work job saved ${item} under ${saved.kind}@${saved.machineVersion}, not ${kind.machine.id}@${kind.machine.version}`;
77
+
78
+ if (saved.state === undefined || !passReach(inbox).has(saved.state)) return `no pass takes ${item} from ${inbox.at ?? kind.machine.initial} to ${saved.state ?? "a nested state"}`;
79
+
80
+ mkdirSync(dirname(into.items.path(item)), { recursive: true });
81
+ copyFileSync(work.items.path(item), into.items.path(item));
82
+ } else into.items.remove(item);
83
+
84
+ for (const record of work.runs.list(item)) into.runs.keep(record);
85
+
86
+ const worked = work.spent.get(item);
87
+
88
+ if (worked !== undefined) into.spent.put(item, raisedSpend(into.spent.get(item), worked, inbox.answered));
89
+
90
+ work.plans.copyTo(into.plans, item);
91
+ work.pullRequests.copyTo(into.pullRequests, item);
92
+ work.proofs.copyTo(into.proofs, item);
93
+
94
+ for (const queued of work.questions.list().filter((queued) => queued.item === item && queued.askedAt === undefined)) into.questions.put(queuedKey(queued), { ...queued, options: queued.options?.filter((option) => option !== OWNER_APPROVAL) });
95
+
96
+ for (const choice of work.choices.list().filter((choice) => choice.item === item)) into.choices.put(`${item}@${choice.text}`, choice);
97
+
98
+ for (const event of work.events.list(item)) into.events.add(event);
99
+
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
+
102
+ const until = savedLimitUntil(work);
103
+
104
+ if (until > 0) settleLimit(into, { kind: "limited", until: Math.min(until, limits.now + limits.usageLimitMaxMs) });
105
+
106
+ return undefined;
107
+ };
@@ -0,0 +1,182 @@
1
+ import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
+ import { basename, join } from "node:path";
3
+ import { z } from "zod";
4
+ import { type ClaimResult, Holder, Item, ItemId, type Questions, type WorkSource } from "../adapter-api.ts";
5
+ import { gitIn } from "../adapters/git.ts";
6
+ import type { ThinResult } from "../worker/thin-path.ts";
7
+ import type { BaseCheck } from "../worker/base-check.ts";
8
+ import { Intent } from "./intents.ts";
9
+
10
+ const text = z.string().min(1);
11
+
12
+ const sha = z.string().regex(/^[0-9a-f]{40}$/);
13
+
14
+ /** Where an inbox or outbox keeps the state folder, beside its JSON file. */
15
+ const STATE_FOLDER = "state";
16
+
17
+ const INBOX_FILE = "inbox.json";
18
+
19
+ const OUTBOX_FILE = "outbox.json";
20
+
21
+ /**
22
+ * What gather settled for a wake, which publish trusts and reads from gather's own job outputs, never from an
23
+ * artifact the work job could replace: who claimed, the base and hum branch heads it saw, the items it claimed, and
24
+ * the state commit it saved.
25
+ */
26
+ export const Gathered = z.strictObject({
27
+ holder: Holder,
28
+ base: text,
29
+ baseSha: sha,
30
+ /** Each hum branch gather saw, at its head. */
31
+ heads: z.record(text, sha),
32
+ claimed: z.array(ItemId),
33
+ /** The state commit gather saved, which publish must find still there and replaces; absent when it saved none. */
34
+ stateRead: sha.optional(),
35
+ });
36
+
37
+ export type Gathered = z.infer<typeof Gathered>;
38
+
39
+ /** What gather hands the work job, which holds no token: what it settled, and each item it claimed as it read it last. */
40
+ export const Inbox = z.strictObject({ gathered: Gathered, items: z.array(Item) });
41
+
42
+ export type Inbox = z.infer<typeof Inbox>;
43
+
44
+ /** A pass's result as the work job reports it; publish alone merges or lands, so it takes neither from the work job. */
45
+ const WorkResult = z.discriminatedUnion("outcome", [
46
+ z.strictObject({ outcome: z.enum(["lost", "waiting"]), item: text }),
47
+ z.strictObject({ outcome: z.literal("moved"), item: text, kind: text }),
48
+ z.strictObject({ outcome: z.enum(["asked", "stuck", "review"]), item: text, detail: z.string().optional() }),
49
+ z.strictObject({ outcome: z.literal("limited"), item: text, until: z.int().nonnegative() }),
50
+ z.strictObject({ outcome: z.literal("held"), item: text, why: z.string() }),
51
+ ]);
52
+
53
+ export type WorkResult = z.infer<typeof WorkResult>;
54
+
55
+ const BUNDLE_NAME = /^[\w.-]+\.bundle$/;
56
+
57
+ /** One pass the work job ran: its item, its result, what it asks publish to do and the bundle file it made. */
58
+ const OutboxPass = z.strictObject({ item: ItemId, result: WorkResult, intents: z.array(Intent), bundle: z.string().regex(BUNDLE_NAME).optional() });
59
+
60
+ /** The repo's checks the work job ran on gather's base for the merges no check had covered: their failure, absent when they passed. */
61
+ const BaseCheckReport = z.strictObject({ items: z.array(ItemId).min(1), failure: z.string().optional() });
62
+
63
+ export const OutboxFile = z.strictObject({ passes: z.array(OutboxPass), baseCheck: BaseCheckReport.optional() });
64
+
65
+ type OutboxFile = z.infer<typeof OutboxFile>;
66
+
67
+ const readOutboxFile = (folder: string): OutboxFile => {
68
+ const file = join(folder, OUTBOX_FILE);
69
+
70
+ return existsSync(file) ? OutboxFile.parse(JSON.parse(readFileSync(file, "utf8"))) : { passes: [] };
71
+ };
72
+
73
+ const writeOutboxFile = (folder: string, outbox: z.input<typeof OutboxFile>): void => {
74
+ mkdirSync(folder, { recursive: true });
75
+ writeFileSync(join(folder, OUTBOX_FILE), `${JSON.stringify(OutboxFile.parse(outbox))}\n`);
76
+ };
77
+
78
+ export type OutboxPass = z.infer<typeof OutboxPass>;
79
+
80
+ /** Writes the inbox, with a copy of the state folder, into `folder`. */
81
+ export const writeInbox = (folder: string, inbox: Inbox, stateDir: string): void => {
82
+ mkdirSync(folder, { recursive: true });
83
+ writeFileSync(join(folder, INBOX_FILE), `${JSON.stringify(Inbox.parse(inbox))}\n`);
84
+ cpSync(stateDir, join(folder, STATE_FOLDER), { recursive: true });
85
+ };
86
+
87
+ /** The inbox in `folder`, its state folder copied to `stateDir`. */
88
+ export const readInbox = (folder: string, stateDir: string): Inbox => {
89
+ const inbox = Inbox.parse(JSON.parse(readFileSync(join(folder, INBOX_FILE), "utf8")));
90
+
91
+ if (existsSync(join(folder, STATE_FOLDER))) cpSync(join(folder, STATE_FOLDER), stateDir, { recursive: true });
92
+
93
+ return inbox;
94
+ };
95
+
96
+ const refused = (what: string): never => {
97
+ throw new Error(`the work job's ${what}, so this wake publishes nothing`);
98
+ };
99
+
100
+ export type WorkIntegrations = { readonly workSource: WorkSource; readonly questions: Questions };
101
+
102
+ /** The integrations a work job runs on: the inbox's reads, its claims as gather took them, and no write at all. */
103
+ export const inboxIntegrations = (inbox: Inbox, now: () => number): WorkIntegrations => {
104
+ const items = new Map(inbox.items.map((item) => [item.id, item]));
105
+
106
+ const claimed = async (id: ItemId, _holder: Holder, ttlMs: number): Promise<ClaimResult> => ({ won: items.has(id), claim: { item: id, holder: inbox.gathered.holder, expiresAt: now() + ttlMs } });
107
+
108
+ const writes = async (): Promise<never> => refused("integrations take no write: a pass writes through its outbox");
109
+
110
+ return {
111
+ workSource: {
112
+ listReady: async () => inbox.items.map(({ id, title }) => ({ id, title })),
113
+ read: async (id) => items.get(id) ?? refused(`inbox holds no item ${id}`),
114
+ claim: claimed,
115
+ renew: claimed,
116
+ comment: writes,
117
+ fileFollowUp: writes,
118
+ finish: writes,
119
+ },
120
+ questions: { ask: writes, decide: writes },
121
+ };
122
+ };
123
+
124
+ /** Adds a pass to the outbox in `folder`, its bundle moved beside it. */
125
+ export const writePass = (folder: string, { item, result, intents, bundle }: { readonly item: string; readonly result: ThinResult; readonly intents: readonly z.input<typeof Intent>[]; readonly bundle: string | undefined }): void => {
126
+ const outbox = readOutboxFile(folder);
127
+ const kept = bundle === undefined ? undefined : `${item}-${outbox.passes.length}.bundle`;
128
+
129
+ mkdirSync(folder, { recursive: true });
130
+
131
+ if (bundle !== undefined && kept !== undefined) cpSync(bundle, join(folder, kept));
132
+
133
+ writeOutboxFile(folder, { ...outbox, passes: [...outbox.passes, { item, result: WorkResult.parse(result), intents: [...intents], bundle: kept }] });
134
+ };
135
+
136
+ /** Puts the base check the work job ran into the outbox in `folder`. */
137
+ export const writeBaseCheck = (folder: string, { items, failure }: BaseCheck): void => writeOutboxFile(folder, { ...readOutboxFile(folder), baseCheck: { items: [...items], failure } });
138
+
139
+ export type ReadOutbox = { readonly passes: readonly OutboxPass[]; readonly baseCheck: BaseCheck | undefined; readonly stateDir: string; readonly bundleOf: (pass: OutboxPass) => string | undefined };
140
+
141
+ /** Ends the work job's outbox: an empty one where nothing was written, and a copy of its state folder for publish to take its own records from. */
142
+ export const writeOutboxState = (folder: string, stateDir: string): void => {
143
+ writeOutboxFile(folder, readOutboxFile(folder));
144
+
145
+ if (existsSync(stateDir)) cpSync(stateDir, join(folder, STATE_FOLDER), { recursive: true });
146
+ };
147
+
148
+ /**
149
+ * The outbox in `folder`, refused whole before any write when it is larger than `maxBytes`, fails its schema, names a
150
+ * bundle outside the folder or an item gather did not claim. Its state folder is the work job's, which publish reads
151
+ * only through `takeWorkRecords`.
152
+ */
153
+ export const readOutbox = (folder: string, { maxBytes, claimed }: { readonly maxBytes: number; readonly claimed: ReadonlySet<string> }): ReadOutbox => {
154
+ const size = sizeOf(folder);
155
+
156
+ if (size > maxBytes) refused(`outbox holds ${size} bytes, over the ${maxBytes} bytes publish reads`);
157
+
158
+ const { passes, baseCheck } = OutboxFile.parse(JSON.parse(readFileSync(join(folder, OUTBOX_FILE), "utf8")));
159
+ const stranger = passes.find(({ item }) => !claimed.has(item));
160
+
161
+ if (stranger !== undefined) refused(`outbox names ${stranger.item}, which gather did not claim`);
162
+
163
+ return { passes, baseCheck, stateDir: join(folder, STATE_FOLDER), bundleOf: (pass) => pass.bundle && join(folder, basename(pass.bundle)) };
164
+ };
165
+
166
+ /** The bytes of every file under `folder`, links not followed. */
167
+ const sizeOf = (folder: string): number =>
168
+ [...new Bun.Glob("**").scanSync({ cwd: folder, onlyFiles: true, dot: true, followSymlinks: false })].reduce((total, file) => total + lstatSync(join(folder, file)).size, 0);
169
+
170
+ /**
171
+ * A bare repo of the checkout with the base and each hum branch at the commits gather saw: the remote a work job's runs
172
+ * clone, so they start where publish checks them from. A commit the checkout lacks throws.
173
+ */
174
+ export const workRemote = async ({ checkout, gathered, folder, timeoutMs }: { readonly checkout: string; readonly gathered: Gathered; readonly folder: string; readonly timeoutMs: number }): Promise<string> => {
175
+ await gitIn(checkout, { timeoutMs }).raw(["clone", "--bare", "-q", checkout, folder]);
176
+
177
+ const git = gitIn(folder, { timeoutMs });
178
+
179
+ for (const [branch, at] of [[gathered.base, gathered.baseSha], ...Object.entries(gathered.heads)] as const) await git.raw(["update-ref", `refs/heads/${branch}`, at]);
180
+
181
+ return folder;
182
+ };