@thinair/factory 0.0.0-stage → 0.1.124

package/domain/step.ts

@@ -0,0 +1,70 @@
+import { Context, Effect, Schema } from "effect";
+
+/*
+ * The only holes a job's step may use. A step is
+ * `Effect<Out, StepFailed | Lost, Machine | Store>`: it checks out a commit on the
+ * machine its attempt is bound to, runs commands there, and keeps bytes in
+ * the content store. Every outward write (publish, push, merge) is an act,
+ * never a step.
+ *
+ * Keys are the framework's, not the author's: a command's identity is
+ * H(job id, job digest, epoch, label), so a step that runs again after its
+ * VM restarts adopts the same command. Secrets are names; the executor binds
+ * them into that command's environment and the values never come back.
+ * Hole calls fail only with Lost (the machine or its link went away), which
+ * means "retry elsewhere". StepFailed and defects are red and final.
+ */
+
+/** A checked-out commit on the bound machine. */
+export const Tree = Schema.Struct({ path: Schema.String, commit: Schema.String });
+export type Tree = typeof Tree.Type;
+
+/** What a command did: plain data, no methods. */
+export const Ran = Schema.Struct({
+  exit: Schema.Int,
+  seconds: Schema.Number,
+  /** The last lines of its output. */
+  tail: Schema.String,
+  /** Where its whole log is kept: a content key. */
+  log: Schema.String,
+});
+export type Ran = typeof Ran.Type;
+
+/** A content-store key: the digest of the bytes. */
+export const ContentKey = Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/u)).pipe(Schema.brand("ContentKey"));
+export type ContentKey = typeof ContentKey.Type;
+
+/** The machine or its link went away: the attempt is retried elsewhere. */
+export class Lost extends Schema.TaggedError<Lost>()("Lost", { message: Schema.String }) {}
+
+/** The step's own red result: final, never retried. */
+export class StepFailed extends Schema.TaggedError<StepFailed>()("StepFailed", { summary: Schema.String, log: Schema.String }) {}
+
+export type RunOptions = Readonly<{
+  cwd: string;
+  argv: ReadonlyArray<string>;
+  /** Names of secrets the executor binds into this command's environment. */
+  secrets: ReadonlyArray<string>;
+}>;
+
+/** The machine this attempt is bound to. */
+export class Machine extends Context.Service<Machine, {
+  /** The executor brings the commit: a bundle, never a token. */
+  readonly checkout: (commit: string) => Effect.Effect<Tree, Lost>;
+  /** `label` is a literal, unique in the step: with the attempt it names the command. */
+  readonly run: (label: string, options: RunOptions) => Effect.Effect<Ran, Lost>;
+}>()("@thinair/factory/domain/step/Machine") {}
+
+/** The content store: create-only, by digest. */
+export class Store extends Context.Service<Store, {
+  readonly put: (bytes: Uint8Array) => Effect.Effect<ContentKey, Lost>;
+  readonly get: (key: ContentKey) => Effect.Effect<Uint8Array, Lost>;
+}>()("@thinair/factory/domain/step/Store") {}
+
+/** A step: the only imperative code in a factory. A Lost from a hole passes through: the engine retries it elsewhere. */
+export type Step<In, Out> = (input: In) => Effect.Effect<Out, StepFailed | Lost, Machine | Store>;
+
+/** Something a machine provides, matched against its facts: `capability("vms")`. */
+export const Capability = Schema.String.check(Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/u)).pipe(Schema.brand("Capability"));
+export type Capability = typeof Capability.Type;
+export const capability = (name: string): Capability => name as Capability;

package/domain/system-elements/agent.ts

@@ -0,0 +1,41 @@
+import { Schema } from "effect";
+import { AUTHORED, authoredHead, head, type Authored, type LiveRows } from "./node";
+
+/*
+ * An agent of this factory: its instructions (a Markdown file in the factory
+ * folder) and the engine it thinks with. Its conversations live in the
+ * factory's File and are named "<agent> · <factory>". Where it works is a
+ * Run's business, never the agent's.
+ */
+
+export const Engine = Schema.Literals(["claude", "codex", "any"]);
+export type Engine = typeof Engine.Type;
+
+export const Node = Schema.TaggedStruct("Agent", {
+  ...head,
+  /** Its instructions: a `.md` path relative to the factory folder. */
+  instructions: Schema.String.check(Schema.isPattern(/^(?!\/)(?!.*\.\.\/).+\.md$/u)),
+  engine: Engine,
+});
+export type Node = typeof Node.Type;
+
+export interface AuthoredAgent<N extends string = string> extends Authored<"Agent", N> {
+  readonly instructions: string;
+  readonly engine: Engine;
+}
+
+/** `agent("web", { instructions: "agents/web.md" })`. */
+export const agent = <const N extends string>(name: N, settings: Readonly<{ instructions: string; engine?: Engine }>): AuthoredAgent<N> => ({
+  [AUTHORED]: authoredHead("Agent", name, false),
+  instructions: settings.instructions,
+  engine: settings.engine ?? "any",
+});
+
+export const make = (authored: AuthoredAgent) => ({ instructions: authored.instructions, engine: authored.engine });
+
+/** The sessions it has up now, across the factory's Runs. */
+export const live = (node: Node, rows: LiveRows) => ({
+  sessions: rows.jobs.filter((row) => row.node === node.id && row.state === "running").length,
+});
+
+export const owner = "none" as const;

package/domain/system-elements/app-shape.ts

@@ -0,0 +1,88 @@
+/*
+ * The shape of a factory app: the `factory/` folder in the repository it
+ * builds. It sits outside the pnpm workspace, pins `@thinair/factory`, and
+ * imports only the authoring modules below and its own npm packages, never
+ * the host repository. The load gate owns this shape, its lint and its
+ * reachability, the same for live, preview and the PR self-check.
+ *
+ *   factory/
+ *     factory.ts      export default defineFactory({ ... }): the one root
+ *     package.json    pins @thinair/factory and effect
+ *     tsconfig.json   bun.lock  README.md  .gitignore
+ *     repositories/ intake/ stages/ jobs/ fleet/ agents/ lifecycles/
+ *                     one default export per .ts file, each a node;
+ *                     agents/ also holds their instructions (.md)
+ */
+
+/** The modules factory code may import from `@thinair/factory`. Nothing else of the framework is its to reach. */
+export const AUTHORING_MODULES = [
+  "@thinair/factory/domain/system-elements/factory",
+  "@thinair/factory/domain/system-elements/repository",
+  "@thinair/factory/domain/system-elements/source",
+  "@thinair/factory/domain/system-elements/rule",
+  "@thinair/factory/domain/system-elements/stage",
+  "@thinair/factory/domain/system-elements/job",
+  "@thinair/factory/domain/system-elements/service",
+  "@thinair/factory/domain/system-elements/pool",
+  "@thinair/factory/domain/system-elements/agent",
+  "@thinair/factory/domain/system-elements/goal",
+  "@thinair/factory/domain/system-elements/hole",
+  "@thinair/factory/domain/system-elements/compose",
+  "@thinair/factory/domain/step",
+] as const;
+export type AuthoringModule = (typeof AUTHORING_MODULES)[number];
+
+/** The folders whose `.ts` files are members: one default export each, a node. */
+export const MEMBER_FOLDERS = ["repositories", "intake", "stages", "jobs", "fleet", "agents", "lifecycles"] as const;
+
+/** The files at the folder's top, besides the member folders. */
+export const ROOT_FILES = ["factory.ts", "package.json", "tsconfig.json", "bun.lock", "README.md", ".gitignore"] as const;
+export const REQUIRED_FILES = ["factory.ts", "package.json", "tsconfig.json"] as const;
+
+/** What the loader never reads: installed packages and the loader's own cache live there. */
+export const IGNORED_FOLDERS = ["node_modules"] as const;
+
+/**
+ * Whether the loader reads a file of the folder, by its path relative to it: never what sits in an ignored folder or
+ * `.git`, and no dot entry but `.gitignore`. The plane fetches the same files a loader reads, so both name one folder.
+ */
+export const isLoadedPath = (path: string): boolean =>
+  path.split("/").every((part) => part !== "" && part !== ".git" && !(IGNORED_FOLDERS as ReadonlyArray<string>).includes(part) && (!part.startsWith(".") || part === ".gitignore"));
+
+/**
+ * The content key of a factory folder: the framework that loads it and every file it reads, each by the SHA-256 of
+ * its bytes. The same files under the same framework give the same key. `hash` is SHA-256 to hex.
+ */
+export const folderKey = (framework: string, digests: Readonly<Record<string, string>>, hash: (text: string) => string): string =>
+  hash(`${framework}\n${Object.keys(digests).sort().map((file) => `${file} ${digests[file]}`).join("\n")}`);
+
+export type ShapeProblem = Readonly<{ path: string; message: string }>;
+
+const isMemberFile = (path: string) => path.endsWith(".ts") && !path.endsWith(".d.ts");
+
+/** Check the folder's file list (paths relative to it, `/`-separated) against the app shape. */
+export const appShapeProblems = (paths: ReadonlyArray<string>): ReadonlyArray<ShapeProblem> => {
+  const problems: ShapeProblem[] = [];
+  const present = new Set(paths);
+  for (const required of REQUIRED_FILES)
+    if (!present.has(required)) problems.push({ path: required, message: `A factory folder has ${required}.` });
+  for (const path of paths) {
+    const [top, ...rest] = path.split("/");
+    if (rest.length === 0) {
+      if (!(ROOT_FILES as ReadonlyArray<string>).includes(path))
+        problems.push({ path, message: `Not part of a factory app: the top of factory/ holds ${ROOT_FILES.join(", ")} and the folders ${MEMBER_FOLDERS.join(", ")}.` });
+      continue;
+    }
+    if (!(MEMBER_FOLDERS as ReadonlyArray<string>).includes(top!)) {
+      problems.push({ path, message: `Not part of a factory app: its folders are ${MEMBER_FOLDERS.join(", ")}.` });
+      continue;
+    }
+    if (!isMemberFile(path) && !(top === "agents" && path.endsWith(".md")))
+      problems.push({ path, message: `${top}/ holds TypeScript members${top === "agents" ? " and their instructions (.md)" : ""} only.` });
+  }
+  return problems;
+};
+
+/** The files the factory-code lint holds to one default export: factory.ts and every member. */
+export const memberFiles = (paths: ReadonlyArray<string>): ReadonlyArray<string> =>
+  paths.filter((path) => path === "factory.ts" || ((MEMBER_FOLDERS as ReadonlyArray<string>).includes(path.split("/")[0]!) && path.includes("/") && isMemberFile(path)));

package/domain/system-elements/compose.ts

@@ -0,0 +1,211 @@
+import { Schema } from "effect";
+import type { AuthoredAgent } from "./agent";
+import type { AnyJob, JobOutput } from "./job";
+import { AnyRef, Ref, type FactKind } from "./node";
+import type { AuthoredRepository } from "./repository";
+import type { AnyService } from "./service";
+import type { AnyStage, StageSpec } from "./stage";
+
+/*
+ * The per-pass language: what a stage's compose and a rule's route return,
+ * and what they may read. It is closed.
+ *
+ * Out, children: want(work, input), together(...), child(stage, key, spec),
+ *   done(note), hold(reason): what should exist now; owned, and collected
+ *   when no longer wanted.
+ * Out, engine requests: pin(name, value) writes a pin once; judge(question)
+ *   asks the judge once and composes this ticket again in the same pass.
+ * Act, one-time and outward: wake, checkRun, mergePullRequest, post, call.
+ *   They go through the act outbox, keyed, with a lease, settled by reading.
+ * Seen, read only: output, verdict, ticket, children, fact, judged, pinned,
+ *   lifecycle. App-specific questions become facts or job outputs.
+ *
+ * A rule routes one fact: it returns ticket(stage, key, spec) to file or
+ * update a ticket, and acts.
+ */
+
+/** What a stage may want: a batch job or a service. */
+export type Work = AnyJob | AnyService;
+
+declare const PHANTOM: unique symbol;
+/** The types a value carries for compose and nothing else. */
+export interface Carries<In, Out> {
+  readonly [PHANTOM]?: Readonly<{ input: In; output: Out }>;
+}
+export type InputOf<W> = W extends Carries<infer In, unknown> ? In : never;
+export type OutputOf<W> = W extends Carries<unknown, infer Out> ? Out : never;
+
+// Out: children.
+
+export interface Want<W extends Work = Work> {
+  readonly _tag: "Want";
+  readonly work: W;
+  readonly input: InputOf<W>;
+}
+/** Want this job or service, with this input: it exists while a pass wants it. */
+export const want = <W extends Work>(work: W, input: InputOf<W>): Want<W> => ({ _tag: "Want", work, input });
+
+/**
+ * One Run: admitted whole or not at all. Its members are placed separately
+ * and may land on different machines. A later member may take an earlier
+ * one's output as a value: `together(want(copy, { base }), (repository) =>
+ * want(coder, { agent, brief, repository }))`.
+ */
+export interface Together<W extends Work = Work> {
+  readonly _tag: "Together";
+  readonly first: Want<W>;
+  /** The next member, from the first one's output. */
+  readonly next: ((output: never) => Want<W>) | null;
+}
+export function together<A extends Work, B extends Work>(first: Want<A>, next: (output: OutputOf<A>) => Want<B>): Together<A | B>;
+export function together<W extends Work>(first: Want<W>): Together<W>;
+export function together(first: Want, next?: (output: never) => Want): Together {
+  return { _tag: "Together", first, next: next ?? null };
+}
+
+/** A ticket owned by this one: its stage, its key, its spec. */
+export interface Child<S extends AnyStage = AnyStage> {
+  readonly _tag: "Child";
+  readonly stage: S;
+  readonly key: string;
+  readonly spec: StageSpec<S>;
+}
+export const child = <S extends AnyStage>(stage: S, key: string, spec: StageSpec<S>): Child<S> => ({ _tag: "Child", stage, key, spec });
+
+export interface Done { readonly _tag: "Done"; readonly note: string }
+/** This ticket's work is done. */
+export const done = (note: string): Done => ({ _tag: "Done", note });
+
+export interface Hold { readonly _tag: "Hold"; readonly reason: string }
+/** This ticket waits, and says why. */
+export const hold = (reason: string): Hold => ({ _tag: "Hold", reason });
+
+// Out: engine requests.
+
+export interface Pin { readonly _tag: "Pin"; readonly name: string; readonly value: Schema.Json }
+/** Write a pin once. A status rewrite never drops it. */
+export const pin = (name: string, value: Schema.Json): Pin => ({ _tag: "Pin", name, value });
+
+/** A question the judge answers from a legal set code computes; the safe default is the first. */
+export interface Question<A> {
+  readonly _tag: "Question";
+  readonly name: string;
+  readonly service: AnyService;
+  readonly legal: ReadonlyArray<A>;
+}
+export interface Judge { readonly _tag: "Judge"; readonly question: Question<unknown> }
+/** Ask once, while compose waits; the ticket composes again when it is answered. */
+export const judge = <A>(question: Question<A>): Judge => ({ _tag: "Judge", question: question as Question<unknown> });
+
+export type Judgment<A> = Readonly<{ _tag: "Pending" }> | Readonly<{ _tag: "Judged"; value: A }>;
+
+// Acts.
+
+export interface Wake {
+  readonly _tag: "Wake";
+  readonly target: AuthoredAgent | "proposer" | "owner";
+  readonly text: string;
+}
+/** Wake an agent, the run that proposed this ticket's change, or the owner. */
+export const wake = (target: AuthoredAgent | "proposer" | "owner", text: string): Wake => ({ _tag: "Wake", target, text });
+
+export const Verdict = Schema.Union([
+  Schema.TaggedStruct("Running", {}),
+  Schema.TaggedStruct("Green", {}),
+  Schema.TaggedStruct("Red", { summary: Schema.String }),
+]);
+export type Verdict = typeof Verdict.Type;
+
+export interface CheckRun {
+  readonly _tag: "CheckRun";
+  readonly repository: AuthoredRepository;
+  readonly head: string;
+  readonly verdict: Verdict;
+}
+/** Post a check run on this head. */
+export const checkRun = (repository: AuthoredRepository, head: string, verdict: Verdict): CheckRun => ({ _tag: "CheckRun", repository, head, verdict });
+
+export interface MergePullRequest { readonly _tag: "MergePullRequest"; readonly repository: AuthoredRepository; readonly pullRequest: number }
+/** Merge through the repository's merge queue. A run never merges its own ticket's pull request. */
+export const mergePullRequest = (repository: AuthoredRepository, pullRequest: number): MergePullRequest =>
+  ({ _tag: "MergePullRequest", repository, pullRequest });
+
+export interface Post<A = unknown> { readonly _tag: "Post"; readonly fact: FactKind<A>; readonly key: string; readonly value: A }
+/** Post a fact of one of the factory's sources, by its key. */
+export const post = <A>(fact: FactKind<A>, key: string, value: A): Post<A> => ({ _tag: "Post", fact, key, value });
+
+export interface Call { readonly _tag: "Call"; readonly connection: string; readonly tool: string; readonly args: Schema.Json }
+/** Call a tool of one of the Profile's connections. */
+export const call = (input: Readonly<{ connection: string; tool: string; args?: Schema.Json }>): Call =>
+  ({ _tag: "Call", connection: input.connection, tool: input.tool, args: input.args ?? {} });
+
+export type Act = Wake | CheckRun | MergePullRequest | Post | Call;
+
+/** What a stage's compose returns: children of its own jobs and stages, engine requests and acts. */
+export type Out<W extends Work = Work, C extends AnyStage = AnyStage> = Want<W> | Together<W> | Child<C> | Done | Hold | Pin | Judge | Act;
+
+// Rules.
+
+/** File a ticket of this stage under this key, or update the one that has it. */
+export interface Ticket<S extends AnyStage = AnyStage> {
+  readonly _tag: "Ticket";
+  readonly stage: S;
+  readonly key: string;
+  readonly spec: StageSpec<S>;
+}
+export const ticket = <S extends AnyStage>(stage: S, key: string, spec: StageSpec<S>): Ticket<S> => ({ _tag: "Ticket", stage, key, spec });
+
+/** What a rule's route returns. */
+export type RuleOut<S extends AnyStage = AnyStage> = Ticket<S> | Act;
+
+// Seen.
+
+/** A ticket as compose reads it. */
+export type TicketView<Spec = unknown> = Readonly<{ id: string; key: string; state: string; spec: Spec }>;
+
+/** What compose may read: nothing else. */
+export interface Seen<W extends Work = Work> {
+  /** This ticket. */
+  readonly ticket: TicketView;
+  /** The output of a job run with this input, from a receipt or this ticket's own jobs. */
+  readonly output: <J extends W & AnyJob>(job: J, input: InputOf<J>) => JobOutput<J> | undefined;
+  /** Passes from receipts and failures from this ticket's own jobs. */
+  readonly verdict: (wants: ReadonlyArray<Want<W> | Together<W>>) => Verdict;
+  readonly children: <S extends AnyStage>(stage: S) => ReadonlyArray<TicketView<StageSpec<S>>>;
+  readonly fact: <A>(kind: FactKind<A>, key: string) => A | undefined;
+  readonly judged: <A>(question: Question<A>) => Judgment<A>;
+  readonly pinned: (name: string) => Schema.Json | undefined;
+  readonly lifecycle: Readonly<{ matches: (state: string) => boolean }>;
+}
+
+/** What a rule may read while it routes one fact. */
+export interface RuleSeen {
+  readonly ticket: <S extends AnyStage>(stage: S, key: string) => TicketView<StageSpec<S>> | undefined;
+  readonly fact: <A>(kind: FactKind<A>, key: string) => A | undefined;
+}
+
+// Records: the outputs as the engine stores them, with Refs.
+
+const Work_ = Schema.Union([Ref("Job"), Ref("Service")]);
+
+export const WantRecord = Schema.TaggedStruct("Want", { work: Work_, input: Schema.Json });
+export const OutRecord = Schema.Union([
+  WantRecord,
+  Schema.TaggedStruct("Together", { members: Schema.Array(WantRecord) }),
+  Schema.TaggedStruct("Child", { stage: Ref("Stage"), key: Schema.String, spec: Schema.Json }),
+  Schema.TaggedStruct("Done", { note: Schema.String }),
+  Schema.TaggedStruct("Hold", { reason: Schema.String }),
+  Schema.TaggedStruct("Pin", { name: Schema.String, value: Schema.Json }),
+  Schema.TaggedStruct("Judge", { question: Schema.String, service: Ref("Service") }),
+]);
+export type OutRecord = typeof OutRecord.Type;
+
+export const ActRecord = Schema.Union([
+  Schema.TaggedStruct("Wake", { target: Schema.Union([Ref("Agent"), Schema.Literals(["proposer", "owner"])]), text: Schema.String }),
+  Schema.TaggedStruct("CheckRun", { repository: Ref("Repository"), head: Schema.String, verdict: Verdict }),
+  Schema.TaggedStruct("MergePullRequest", { repository: Ref("Repository"), pullRequest: Schema.Int }),
+  Schema.TaggedStruct("Post", { from: AnyRef, kind: Schema.String, key: Schema.String, value: Schema.Json }),
+  Schema.TaggedStruct("Call", { connection: Schema.String, tool: Schema.String, args: Schema.Json }),
+]);
+export type ActRecord = typeof ActRecord.Type;
+

package/domain/system-elements/factory.ts

@@ -0,0 +1,61 @@
+import { Schema } from "effect";
+import { AUTHORED, authoredHead, head, Name, Ref, ROOT_NAME, type Authored, type Encoder, type LiveRows, type Slot } from "./node";
+
+/*
+ * The root: `export default defineFactory({ ... })` in `factory/factory.ts`.
+ * What it lists runs and shows; nothing else does. It has no name and no
+ * Profile: the File's name and Profile are the factory's, so the code in git
+ * works for a copy. It holds no money guard: billing owns the runaway guard.
+ */
+
+/** Who an approval waits for: a contract migration waits for the owner's own press. */
+export const Approval = Schema.Struct({ by: Schema.Literal("owner") });
+export type Approval = typeof Approval.Type;
+export const approval = (by: Approval["by"]): Approval => ({ by });
+
+export const Node = Schema.TaggedStruct("Factory", {
+  ...head,
+  repositories: Schema.Array(Ref("Repository")),
+  sources: Schema.Array(Ref("Source")),
+  rules: Schema.Array(Ref("Rule")),
+  stages: Schema.Array(Ref("Stage")),
+  fleet: Schema.Array(Ref("Pool")),
+  agents: Schema.Array(Ref("Agent")),
+  goals: Schema.Array(Ref("Goal")),
+  approvals: Schema.Record(Name, Approval),
+});
+export type Node = typeof Node.Type;
+
+export type FactoryLists = Readonly<{
+  repositories?: ReadonlyArray<Slot<"Repository">>;
+  sources?: ReadonlyArray<Slot<"Source">>;
+  rules?: ReadonlyArray<Slot<"Rule">>;
+  stages?: ReadonlyArray<Slot<"Stage">>;
+  fleet?: ReadonlyArray<Slot<"Pool">>;
+  agents?: ReadonlyArray<Slot<"Agent">>;
+  goals?: ReadonlyArray<Slot<"Goal">>;
+  approvals?: Readonly<Record<string, Approval>>;
+}>;
+
+export interface AuthoredFactory extends Authored<"Factory", typeof ROOT_NAME>, FactoryLists {}
+
+export const defineFactory = (lists: FactoryLists): AuthoredFactory => ({ [AUTHORED]: authoredHead("Factory", ROOT_NAME, false), ...lists });
+
+export const make = (authored: AuthoredFactory, encoder: Encoder) => ({
+  repositories: (authored.repositories ?? []).map((node) => encoder.ref("Repository", node)),
+  sources: (authored.sources ?? []).map((node) => encoder.ref("Source", node)),
+  rules: (authored.rules ?? []).map((node) => encoder.ref("Rule", node)),
+  stages: (authored.stages ?? []).map((node) => encoder.ref("Stage", node)),
+  fleet: (authored.fleet ?? []).map((node) => encoder.ref("Pool", node)),
+  agents: (authored.agents ?? []).map((node) => encoder.ref("Agent", node)),
+  goals: (authored.goals ?? []).map((node) => encoder.ref("Goal", node)),
+  approvals: { ...authored.approvals },
+});
+
+/** Open tickets and running work across the factory. */
+export const live = (_node: Node, rows: LiveRows) => ({
+  tickets: rows.tickets.length,
+  running: rows.jobs.filter((job) => job.state === "running").length,
+});
+
+export const owner = "none" as const;

package/domain/system-elements/goal.ts

@@ -0,0 +1,37 @@
+import { Result, Schema } from "effect";
+import { AUTHORED, authoredHead, head, Ref, type Authored, type Encoder, type LiveRows } from "./node";
+import type { AnyStage, StageSpec } from "./stage";
+
+/*
+ * A standing goal: one ticket of a stage, under a fixed key, that the
+ * factory keeps open while the program lists it. `goal(mainGreen,
+ * "main-green", { branch: "main" })` keeps main green. A goal the program no
+ * longer lists is closed.
+ */
+
+export const Node = Schema.TaggedStruct("Goal", { ...head, stage: Ref("Stage"), spec: Schema.Json });
+export type Node = typeof Node.Type;
+
+export interface AuthoredGoal<N extends string = string, S extends AnyStage = AnyStage> extends Authored<"Goal", N> {
+  readonly stage: S;
+  readonly spec: StageSpec<S>;
+}
+
+export const goal = <const S extends AnyStage, const N extends string>(stage: S, name: N, spec: StageSpec<S>): AuthoredGoal<N, S> => ({
+  [AUTHORED]: authoredHead("Goal", name, false),
+  stage,
+  spec,
+});
+
+export const make = (authored: AuthoredGoal, encoder: Encoder) => {
+  const encoded = Schema.encodeUnknownResult(Schema.toCodecJson(authored.stage.spec))(authored.spec);
+  if (Result.isFailure(encoded)) encoder.problem(`Its spec is not a spec of ${authored.stage[AUTHORED].name}: ${encoded.failure.message}`);
+  return { stage: encoder.ref("Stage", authored.stage), spec: Result.isSuccess(encoded) ? (encoded.success as Schema.Json) : null };
+};
+
+/** Its ticket's state, while the goal holds. */
+export const live = (node: Node, rows: LiveRows) => ({
+  state: rows.tickets.find((ticket) => ticket.goal === node.id)?.state ?? null,
+});
+
+export const owner = "vm" as const;

package/domain/system-elements/hole.ts

@@ -0,0 +1,25 @@
+import { Schema } from "effect";
+import { AUTHORED, authoredHead, head, NodeTag, type HoleFor, type LiveRows } from "./node";
+
+/*
+ * A Hole: a part still to build. `hole("Pool", "macs")` plans a pool where
+ * one will go; the floor draws it dashed amber, "to build". It keeps the id
+ * of the node it stands for (`pool:macs`), so filling it is one change in
+ * place and every Ref to it still holds. The engine skips holes, and types
+ * already stop compose from wanting one.
+ */
+
+export const Node = Schema.TaggedStruct("Hole", { ...head, expects: NodeTag });
+export type Node = typeof Node.Type;
+
+/** Plan a node of tag `expects`, named `name`, to build later. */
+export const hole = <const T extends Exclude<NodeTag, "Factory">, const N extends string>(expects: T, name: N): HoleFor<T, N> => ({
+  [AUTHORED]: { ...authoredHead("Hole", name, false), expects },
+});
+
+export const make = (planned: HoleFor<NodeTag>) => ({ expects: planned[AUTHORED].expects });
+
+/** A hole has nothing live: nothing runs in it. */
+export const live = (_node: Node, _rows: LiveRows) => null;
+
+export const owner = "none" as const;

package/domain/system-elements/job.ts

@@ -0,0 +1,78 @@
+import { Schema } from "effect";
+import { Capability, type Step } from "../step";
+import type { Carries } from "./compose";
+import { AUTHORED, authoredHead, head, type Authored, type LiveRows } from "./node";
+import { Arch, Os } from "./pool";
+
+/*
+ * A batch job: a step that runs once per input, on a machine placement
+ * picks. Its receipt key is H(job digest, key(input)): changing the step's
+ * code gives new keys, and the same key again is reused. A job declares what
+ * it needs; it never names a machine.
+ */
+
+/** Admission order: urgent, then check, build, agent, background. */
+export const JobClass = Schema.Literals(["urgent", "check", "build", "background"]);
+export type JobClass = typeof JobClass.Type;
+
+/** What a job needs from a machine. A missing os or arch means any; placement picks. */
+export const Needs = Schema.Struct({
+  cores: Schema.optionalKey(Schema.Number.check(Schema.isGreaterThan(0))),
+  memoryGiB: Schema.optionalKey(Schema.Number.check(Schema.isGreaterThan(0))),
+  os: Schema.optionalKey(Schema.Array(Os)),
+  arch: Schema.optionalKey(Schema.Array(Arch)),
+  /** Capabilities, matched against each machine's `provides` facts. */
+  uses: Schema.optionalKey(Schema.Array(Capability)),
+});
+export type Needs = typeof Needs.Type;
+
+/** How a Disarm stops it: `kill` stops it now; `hold` lets an act already claimed settle and starts nothing new. */
+export const JobStop = Schema.Literals(["kill", "hold"]);
+export type JobStop = typeof JobStop.Type;
+
+export const Node = Schema.TaggedStruct("Job", { ...head, class: JobClass, needs: Needs, stop: JobStop });
+export type Node = typeof Node.Type;
+
+export interface AuthoredJob<N extends string = string, In = any, Out = any> extends Authored<"Job", N>, Carries<In, Out> {
+  readonly class: JobClass;
+  readonly input: Schema.Codec<In, any, never, never>;
+  readonly output: Schema.Codec<Out, any, never, never>;
+  /** The part of the receipt key the author chooses: the content the result depends on. */
+  readonly key: (input: In) => string;
+  readonly needs: Needs;
+  readonly stop: JobStop;
+  readonly step: Step<In, Out>;
+}
+export type AnyJob = AuthoredJob<string, any, any>;
+export type JobOutput<J> = J extends AuthoredJob<string, any, infer Out> ? Out : never;
+
+/** `job("typecheck", { class, input, output, key, needs, stop, step })`. */
+export const job = <const N extends string, In, Out>(name: N, settings: Readonly<{
+  class: JobClass;
+  input: Schema.Codec<In, any, never, never>;
+  output: Schema.Codec<Out, any, never, never>;
+  key: (input: In) => string;
+  needs?: Needs;
+  stop?: JobStop;
+  step: Step<In, Out>;
+}>): AuthoredJob<N, In, Out> => ({
+  [AUTHORED]: authoredHead("Job", name, true),
+  class: settings.class,
+  input: settings.input,
+  output: settings.output,
+  key: settings.key,
+  needs: settings.needs ?? {},
+  stop: settings.stop ?? "kill",
+  step: settings.step,
+});
+
+export const make = (authored: AnyJob) => ({ class: authored.class, needs: authored.needs, stop: authored.stop });
+
+/** Its attempts by state: what the floor counts on its housing. */
+export const live = (node: Node, rows: LiveRows) => {
+  const jobs = rows.jobs.filter((row) => row.node === node.id);
+  const count = (state: (typeof jobs)[number]["state"]) => jobs.filter((row) => row.state === state).length;
+  return { waiting: count("waiting") + count("bound"), running: count("running"), succeeded: count("succeeded"), failed: count("failed") };
+};
+
+export const owner = "vm" as const;