@thinair/factory 0.1.120 → 0.1.128

package/README.md

@@ -32,7 +32,12 @@ bunx @thinair/factory load .
 
 ## Check it
 
-`load` checks the folder and prints the program as JSON:
+`check` checks the folder and prints the Load as JSON, including its program,
+findings and holes. `load` uses the same gate and output:
+
+```sh
+bunx @thinair/factory check .
+```
 
 1. the folder's shape;
 2. the import rule: factory code imports only the authoring modules below,
@@ -73,6 +78,22 @@ import change from "./stages/change";
   stages: [change],
 ```
 
+## Declare a builder lifecycle
+
+A stage that creates an agent Run can declare `lifecycle: ticketLifecycle()`:
+
+```ts
+import { ticketLifecycle } from "@thinair/factory/domain/lifecycles/ticket";
+// In the stage settings:
+// lifecycle: ticketLifecycle(),
+```
+
+Its ticket follows Inbox, Ready, Running, Asking, Review, Merged or Dropped.
+The stage's `together` groups follow the framework Run lifecycle by default;
+`runs: runLifecycle({ bootingGuardMillis: 300_000 })` customizes its boot guard.
+The package includes these machine definitions and their XState authoring
+libraries. Thinair owns observing events and running the lifecycle host.
+
 ## What factory code imports
 
 - `@thinair/factory/domain/system-elements/factory`
@@ -88,6 +109,10 @@ import change from "./stages/change";
 - `@thinair/factory/domain/system-elements/hole`
 - `@thinair/factory/domain/system-elements/compose`
 - `@thinair/factory/domain/step`
+- `@thinair/factory/domain/ticket-state`
+- `@thinair/factory/domain/lifecycles/lifecycle`
+- `@thinair/factory/domain/lifecycles/ticket`
+- `@thinair/factory/domain/lifecycles/run`
 
 `@thinair/factory/domain/system-elements/program` and
 `@thinair/factory/domain/load` hold the schemas of a program and of a load,

package/cli/load.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { access, mkdir, readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import { access, mkdir, mkdtemp, readdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -19,6 +19,7 @@ import { templateFiles } from "./template";
  *
  *   init [dir] [--framework <spec>]   write the blank factory template
  *   load [tree] [--framework <x.y.z>] load once; print the Load as JSON
+ *   check [tree] [--framework <x.y.z>] check once with the same load gate
  *   dev --factory <id> [--tree <dir>] load on every save and post each load
  *
  * A load: snapshot → shape → the factory-code lint → bundle ∥ type check →
@@ -190,20 +191,27 @@ const lint = Effect.fn("factory.load.lint")(function* (tree: string, paths: Read
 });
 
 /** The type check: bun's checker, with the folder's own tsconfig. */
-const typecheck = Effect.fn("factory.load.type")(function* (tree: string) {
-  const ran = yield* runCommand(process.execPath, ["check", "--no-pretty", "-p", tree], { cwd: tree, guardMillis: TYPE_GUARD_MILLIS });
-  if (ran.timedOut) return [finding("type", `The type check ran past its runaway guard of ${TYPE_GUARD_MILLIS / 1000} s and was stopped.`)];
-  if (ran.code !== 0 && ran.code !== 1) return yield* new FactoryLoadFailed({ message: `bun check failed (${ran.code}): ${ran.stderr.slice(0, 500)}` });
-  const found = `${ran.stdout}\n${ran.stderr}`.split("\n").flatMap((line) => {
-    const match = /^(.+?)\((\d+),\d+\): error (TS\d+): (.*)$/u.exec(line.trim());
-    return match === null ? [] : [finding("type", `${match[3]}: ${match[4]}`, {
-      file: path.relative(tree, path.resolve(tree, match[1]!)).split(path.sep).join("/"),
-      line: Number(match[2]),
-    })];
-  });
-  if (ran.code === 1 && found.length === 0) return [finding("type", `The type check failed: ${`${ran.stdout}\n${ran.stderr}`.trim().slice(0, 500)}`)];
-  return found;
-});
+const typecheck = Effect.fn("factory.load.type")((tree: string, cache: string) => Effect.acquireUseRelease(
+  Effect.tryPromise({ try: () => mkdtemp(path.join(cache, "checker-")), catch: failed("Could not create the typecheck folder.") }),
+  (cwd) => Effect.gen(function* () {
+    // Bun resolves package scripts before built-ins. This private package has no scripts or check file, so the
+    // consumer's check script (including one that calls this loader) can never replace or recurse into the checker.
+    yield* Effect.tryPromise({ try: () => writeFile(path.join(cwd, "package.json"), "{}\n"), catch: failed("Could not isolate the typecheck.") });
+    const ran = yield* runCommand(process.execPath, ["check", "--no-pretty", "--threads=1", "-p", tree], { cwd, guardMillis: TYPE_GUARD_MILLIS });
+    if (ran.timedOut) return [finding("type", `The type check ran past its runaway guard of ${TYPE_GUARD_MILLIS / 1000} s and was stopped.`)];
+    if (ran.code !== 0 && ran.code !== 1) return yield* new FactoryLoadFailed({ message: `bun check failed (${ran.code}): ${ran.stderr.slice(0, 500)}` });
+    const found = `${ran.stdout}\n${ran.stderr}`.split("\n").flatMap((line) => {
+      const match = /^(.+?)\((\d+),\d+\): error (TS\d+): (.*)$/u.exec(line.trim());
+      return match === null ? [] : [finding("type", `${match[3]}: ${match[4]}`, {
+        file: path.relative(tree, path.resolve(cwd, match[1]!)).split(path.sep).join("/"),
+        line: Number(match[2]),
+      })];
+    });
+    if (ran.code === 1 && found.length === 0) return [finding("type", `The type check failed: ${`${ran.stdout}\n${ran.stderr}`.trim().slice(0, 500)}`)];
+    return found;
+  }),
+  (cwd) => Effect.promise(() => rm(cwd, { recursive: true, force: true })),
+));
 
 type BunBuild = (options: Readonly<{
   entrypoints: ReadonlyArray<string>; outdir: string; naming: string; target: "bun"; format: "esm"; sourcemap: "inline"; metafile: true; packages: "external"; throw: false;
@@ -322,7 +330,7 @@ export const loadFactory = Effect.fn("factory.load")(function* (input: Readonly<
   yield* Effect.tryPromise({ try: () => mkdir(cache, { recursive: true }), catch: failed(`Could not make the loader's cache at ${cache}.`) });
   const packages = Object.keys(dependencies).filter((name) => name !== "@thinair/factory");
   findings.push(...yield* timed(steps, "lint", lint(tree, snapshot.paths, packages, cache)));
-  const [bundled, types] = yield* Effect.all([timed(steps, "bundle", bundle(tree, snapshot.key, cache)), timed(steps, "type", typecheck(tree))], { concurrency: 2 });
+  const [bundled, types] = yield* Effect.all([timed(steps, "bundle", bundle(tree, snapshot.key, cache)), timed(steps, "type", typecheck(tree, cache))], { concurrency: 2 });
   findings.push(...bundled.findings, ...types);
 
   let program: Program | null = null;
@@ -420,6 +428,7 @@ export const watchFactory = Effect.fn("factory.dev")(function* (input: Readonly<
 const USAGE = `thinair-factory: the factory loader
   init [dir] [--framework <spec>]   write the blank factory template (dir: factory)
   load [tree] [--framework <x.y.z>] load once and print the Load as JSON (tree: .)
+  check [tree] [--framework <x.y.z>] check once; same findings and exit codes as load
   dev --factory <id> [--tree <dir>] load on every save and post each load
 `;
 
@@ -437,7 +446,7 @@ const main = Effect.fn("factory.cli")(function* (argv: ReadonlyArray<string>) {
     process.stderr.write(`Wrote ${made.files.join(", ")} to ${made.directory}. Next: bun install there, then load.\n`);
     return 0;
   }
-  if (command === "load") {
+  if (command === "load" || command === "check") {
     const framework = flag(args, "--framework");
     const load = yield* loadFactory({ tree: positional(args)[0] ?? ".", ...(framework === undefined ? {} : { framework }) });
     process.stdout.write(`${JSON.stringify(Schema.encodeSync(LoadJson)(load))}\n`);

package/cli/template.ts

@@ -50,7 +50,7 @@ true: repositories, stages of work, jobs, agents, the fleet and standing
 goals. \`@thinair/factory\` compiles it to one program; the factory's
 \`.factory\` File runs it.
 
-- \`bunx @thinair/factory load .\` checks it and prints the program.
+- \`bunx @thinair/factory check .\` checks it and prints findings and the program.
 - \`bunx @thinair/factory dev --factory <id>\` reloads it on every save.
 
 Factory code imports only the authoring modules of \`@thinair/factory\` and

package/domain/lifecycles/lifecycle.ts

@@ -0,0 +1,12 @@
+import type { AnyStateMachine, StateValue } from "xstate";
+
+/**
+ * A lifecycle as the host runs it: its machine, and the state an open record re-enters from what is observed (null
+ * for the machine's own initial state, with its entry actions and timers).
+ */
+export interface Lifecycle<Observed> {
+  readonly name: string;
+  readonly machine: AnyStateMachine;
+  readonly enter: (observed: Observed) => Readonly<{ value: StateValue; context: Readonly<Record<string, unknown>> }> | null;
+}
+

package/domain/lifecycles/run.ts

@@ -0,0 +1,175 @@
+import { setupEffect } from "@xstate/effect";
+import { Schema } from "effect";
+import type { Lifecycle } from "./lifecycle";
+
+/*
+ * The framework's Run lifecycle (the design's 3.2, 5.3 and 8.3). A Run is one `together` group: a ticket's repository
+ * copy and the agent session that works in it, admitted whole and placed member by member. Its states:
+ *
+ *   admitting → booting (copy → session) → working ⇄ asking → proposed
+ *                                     ↘ failed (the booting runaway guard)        any → stopped (Disarm, or unwanted)
+ *
+ * Every event is an observation of the Run's members, the session and the switch, with an observation key the host
+ * keeps once taken: `LOST{member, epoch}` is taken once, so the Run never loops back on it. The session's asks are
+ * read from the session (its Agent Note), never written as acts. A proposal is the one outward finalizer: it runs
+ * only from `proposed`, never from `stopped`.
+ */
+
+export const RUN_STATES = ["admitting", "booting", "working", "asking", "proposed", "stopped", "ended", "failed"] as const;
+export const RunState = Schema.Literals(RUN_STATES);
+export type RunState = typeof RunState.Type;
+/** A Run in one of these is over: its members stop with `rest`. */
+export const RUN_ENDINGS = ["proposed", "stopped", "ended", "failed"] as const satisfies ReadonlyArray<RunState>;
+export const runEnded = (state: string) => (RUN_ENDINGS as ReadonlyArray<string>).includes(state.split(".")[0] ?? "");
+/** The top state of a flattened value: `booting.copy` is `booting`. */
+export const runStateOf = (value: string): RunState => {
+  const top = value.split(".")[0] ?? "";
+  return (RUN_STATES as ReadonlyArray<string>).includes(top) ? (top as RunState) : "admitting";
+};
+
+const Member = Schema.Literals(["copy", "session"]);
+
+export const RunEvents = {
+  /** Placement admitted the whole group. */
+  ADMITTED: Schema.Struct({}),
+  /** The copy is cloned and ready, at this epoch of its attempt. */
+  COPY_READY: Schema.Struct({ epoch: Schema.Number }),
+  /** The session's turn started on the copy, at this epoch of its attempt. */
+  SESSION_STARTED: Schema.Struct({ epoch: Schema.Number }),
+  /** The session asked its person: an open Agent Note of its own. */
+  ASKED: Schema.Struct({ note: Schema.String }),
+  /** Its note was answered, or closed. */
+  ANSWERED: Schema.Struct({ note: Schema.String }),
+  /** The session handed in its work from its own branch. */
+  PROPOSED: Schema.Struct({ branch: Schema.String, title: Schema.String }),
+  /** A member's machine or process went away at this epoch: the plane binds it again. */
+  LOST: Schema.Struct({ member: Member, epoch: Schema.Number }),
+  /** The factory was Disarmed. */
+  DISARMED: Schema.Struct({}),
+  /** Its ticket no longer wants it. */
+  STOP: Schema.Struct({ why: Schema.String }),
+  /** The session ended its work without a proposal. */
+  ENDED: Schema.Struct({ why: Schema.String }),
+};
+
+/** What a Run asks to be done outward, as its acts: a proposal from its own branch, or a wake to the owner. */
+export const RunAct = Schema.Union([
+  Schema.TaggedStruct("Propose", { branch: Schema.String, title: Schema.String }),
+  Schema.TaggedStruct("Wake", { to: Schema.Literal("owner"), text: Schema.String }),
+]);
+export type RunAct = typeof RunAct.Type;
+
+export const RunContext = Schema.Struct({
+  copyEpoch: Schema.NullOr(Schema.Number),
+  sessionEpoch: Schema.NullOr(Schema.Number),
+  note: Schema.NullOr(Schema.String),
+  proposal: Schema.NullOr(Schema.Struct({ branch: Schema.String, title: Schema.String })),
+  why: Schema.NullOr(Schema.String),
+});
+export type RunContext = typeof RunContext.Type;
+
+const EMPTY: RunContext = { copyEpoch: null, sessionEpoch: null, note: null, proposal: null, why: null };
+
+/** The settings a factory may give its Runs. Changing one changes the lifecycle's version. */
+export type RunSettings = Readonly<{
+  /** How long a Run may boot before it fails: a runaway guard, never a speed check. */
+  bootingGuardMillis?: number;
+}>;
+
+/** The default booting guard: a fresh clone and a first turn take minutes, never this long. */
+export const BOOTING_GUARD_MILLIS = 30 * 60_000;
+
+/** What the pass observed of a Run, for re-entering it under a new version of its lifecycle. */
+export type RunObserved = Readonly<{
+  armed: boolean;
+  admitted: boolean;
+  copy: Readonly<{ ready: boolean; epoch: number | null }>;
+  session: Readonly<{ started: boolean; epoch: number | null; asking: string | null }>;
+  proposal: Readonly<{ branch: string; title: string }> | null;
+}>;
+
+const machineOf = (guard: number) => setupEffect({
+  schemas: { context: RunContext, events: RunEvents, emitted: { act: Schema.Struct({ act: RunAct }) } },
+}).createMachine({
+  id: "run",
+  context: EMPTY,
+  initial: "admitting",
+  on: {
+    DISARMED: ({ context }) => ({ target: ".stopped", context: { ...context, why: "The factory was Disarmed." } }),
+    STOP: ({ context, event }) => ({ target: ".stopped", context: { ...context, why: event.why } }),
+  },
+  states: {
+    admitting: { on: { ADMITTED: { target: "booting" } } },
+    booting: {
+      initial: "copy",
+      after: { [guard]: { target: "failed" } },
+      on: {
+        // A member lost while booting is placed again inside booting: the guard keeps its deadline.
+        LOST: ({ context, event }) => ({ target: ".copy", context: { ...context, ...(event.member === "copy" ? { copyEpoch: null } : { sessionEpoch: null }) } }),
+      },
+      states: {
+        // A copy bound again after a loss, with its session still up, goes straight back: to its ask, if one is open.
+        copy: { on: { COPY_READY: ({ context, event }) => ({
+          target: context.sessionEpoch === null ? "session" : context.note !== null ? "#run.asking" : "#run.working", context: { ...context, copyEpoch: event.epoch },
+        }) } },
+        session: { on: { SESSION_STARTED: ({ context, event }) => ({ target: "#run.working", context: { ...context, sessionEpoch: event.epoch } }) } },
+      },
+    },
+    working: {
+      on: {
+        ASKED: ({ context, event }) => ({ target: "asking", context: { ...context, note: event.note } }),
+        PROPOSED: ({ context, event }) => ({ target: "proposed", context: { ...context, proposal: { branch: event.branch, title: event.title } } }),
+        ENDED: ({ context, event }) => ({ target: "ended", context: { ...context, why: event.why } }),
+        // Only the member's current attempt: a loss of an older epoch was handled when it happened.
+        LOST: ({ context, event }) => (event.member === "copy" ? context.copyEpoch : context.sessionEpoch) === event.epoch
+          ? { target: "booting", context: { ...context, ...(event.member === "copy" ? { copyEpoch: null } : { sessionEpoch: null }) } }
+          : undefined,
+      },
+    },
+    asking: {
+      on: {
+        ANSWERED: ({ context, event }) => event.note === context.note ? { target: "working", context: { ...context, note: null } } : undefined,
+        PROPOSED: ({ context, event }) => ({ target: "proposed", context: { ...context, note: null, proposal: { branch: event.branch, title: event.title } } }),
+        ENDED: ({ context, event }) => ({ target: "ended", context: { ...context, why: event.why } }),
+        // Its open ask is kept: once the member is back, the Run is asking again.
+        LOST: ({ context, event }) => (event.member === "copy" ? context.copyEpoch : context.sessionEpoch) === event.epoch
+          ? { target: "booting", context: { ...context, ...(event.member === "copy" ? { copyEpoch: null } : { sessionEpoch: null }) } }
+          : undefined,
+      },
+    },
+    proposed: {
+      type: "final",
+      entry: ({ context }, enq) => {
+        if (context.proposal !== null) enq.emit({ type: "act", act: { _tag: "Propose", branch: context.proposal.branch, title: context.proposal.title } });
+      },
+    },
+    stopped: { type: "final" },
+    ended: { type: "final" },
+    failed: {
+      type: "final",
+      entry: (_args, enq) => { enq.emit({ type: "act", act: { _tag: "Wake", to: "owner", text: `A run could not boot within ${Math.round(guard / 60_000)} minutes and stopped. Its copy and conversation are kept.` } }); },
+    },
+  },
+});
+
+export type RunMachine = ReturnType<typeof machineOf>;
+
+/** The state an open Run re-enters from what is observed, under a new version of its lifecycle. */
+const enter = (observed: RunObserved) => {
+  const context: RunContext = { ...EMPTY, copyEpoch: observed.copy.ready ? observed.copy.epoch : null, sessionEpoch: observed.session.started ? observed.session.epoch : null };
+  if (observed.proposal !== null) return { value: "proposed", context: { ...context, proposal: observed.proposal } };
+  if (!observed.armed) return { value: "stopped", context: { ...context, why: "The factory was Disarmed." } };
+  if (observed.session.started && observed.session.asking !== null) return { value: "asking", context: { ...context, note: observed.session.asking } };
+  if (observed.session.started) return { value: "working", context };
+  if (observed.copy.ready) return { value: { booting: "session" }, context };
+  if (observed.admitted) return { value: { booting: "copy" }, context };
+  return null;
+};
+
+/** A Run lifecycle. `runLifecycle()` is the framework's; settings give another version of it. */
+export const runLifecycle = (settings: RunSettings = {}): Lifecycle<RunObserved> & Readonly<{ settings: RunSettings }> => ({
+  name: "run",
+  machine: machineOf(settings.bootingGuardMillis ?? BOOTING_GUARD_MILLIS),
+  enter,
+  settings,
+});

package/domain/lifecycles/ticket.ts

@@ -0,0 +1,97 @@
+import { setupEffect } from "@xstate/effect";
+import { Schema } from "effect";
+import type { TicketState } from "../ticket-state";
+import type { Lifecycle } from "./lifecycle";
+
+/*
+ * The framework's ticket lifecycle (the design's 3.2 `fix`, 5.1): Inbox → Ready → Running ⇄ Asking → Review → Merged.
+ * Its states are the product's ticket states, so its `stateOf` is the state itself.
+ *
+ * People and agents never write a ticket's state. `factory.ticket.move` posts a move, which the engine hands this
+ * lifecycle as `MOVE`; the ticket's Runs are observed as `RUN_*`; a merged proposal as `MERGED`. Each is an
+ * observation with a key, taken once.
+ */
+
+export const TICKET_LIFECYCLE_STATES = ["Inbox", "Ready", "Running", "Asking", "Review", "Merged", "Dropped"] as const satisfies ReadonlyArray<TicketState>;
+type LifecycleState = (typeof TICKET_LIFECYCLE_STATES)[number];
+const MoveTarget = Schema.Literals(["Inbox", "Ready", "Review", "Merged", "Dropped"]);
+
+export const TicketEvents = {
+  /** A person or an agent moved it (`factory.ticket.move`). */
+  MOVE: Schema.Struct({ to: MoveTarget }),
+  /** One of its Runs started, asked, went back to work, proposed, stopped or ended. */
+  RUN_STARTED: Schema.Struct({ run: Schema.String }),
+  RUN_ASKING: Schema.Struct({ run: Schema.String }),
+  RUN_WORKING: Schema.Struct({ run: Schema.String }),
+  RUN_PROPOSED: Schema.Struct({ run: Schema.String }),
+  RUN_STOPPED: Schema.Struct({ run: Schema.String }),
+  RUN_ENDED: Schema.Struct({ run: Schema.String, why: Schema.String }),
+  /** Its proposal merged. */
+  MERGED: Schema.Struct({}),
+};
+
+const TicketContext = Schema.Struct({ run: Schema.NullOr(Schema.String) });
+
+const machine = setupEffect({ schemas: { context: TicketContext, events: TicketEvents } }).createMachine({
+  id: "ticket",
+  context: { run: null },
+  initial: "Inbox",
+  states: {
+    Inbox: {
+      on: { MOVE: ({ event }) => event.to === "Ready" ? { target: "Ready" } : event.to === "Dropped" ? { target: "Dropped" } : undefined },
+    },
+    Ready: {
+      on: {
+        RUN_STARTED: ({ event }) => ({ target: "Running", context: { run: event.run } }),
+        MOVE: ({ event }) => event.to === "Inbox" ? { target: "Inbox" } : event.to === "Dropped" ? { target: "Dropped" } : undefined,
+      },
+    },
+    Running: {
+      on: {
+        RUN_ASKING: ({ context, event }) => event.run === context.run ? { target: "Asking" } : undefined,
+        RUN_PROPOSED: ({ context, event }) => event.run === context.run ? { target: "Review" } : undefined,
+        RUN_STOPPED: ({ context, event }) => event.run === context.run ? { target: "Ready", context: { run: null } } : undefined,
+        // A Run that ended without a proposal (it failed to boot, or its session stopped) waits for a person in Inbox.
+        RUN_ENDED: ({ context, event }) => event.run === context.run ? { target: "Inbox", context: { run: null } } : undefined,
+        MOVE: ({ event }) => event.to === "Inbox" ? { target: "Inbox" } : event.to === "Dropped" ? { target: "Dropped" } : undefined,
+      },
+    },
+    Asking: {
+      on: {
+        RUN_WORKING: ({ context, event }) => event.run === context.run ? { target: "Running" } : undefined,
+        RUN_PROPOSED: ({ context, event }) => event.run === context.run ? { target: "Review" } : undefined,
+        RUN_STOPPED: ({ context, event }) => event.run === context.run ? { target: "Ready", context: { run: null } } : undefined,
+        RUN_ENDED: ({ context, event }) => event.run === context.run ? { target: "Inbox", context: { run: null } } : undefined,
+        MOVE: ({ event }) => event.to === "Dropped" ? { target: "Dropped" } : undefined,
+      },
+    },
+    Review: {
+      on: {
+        MERGED: { target: "Merged" },
+        MOVE: ({ event }) => event.to === "Ready" ? { target: "Ready", context: { run: null } } : event.to === "Merged" ? { target: "Merged" }
+          : event.to === "Dropped" ? { target: "Dropped" } : undefined,
+      },
+    },
+    Merged: { type: "final" },
+    Dropped: { type: "final" },
+  },
+});
+
+/** What the pass observed of a ticket: its row's state, and its open Run. */
+export type TicketObserved = Readonly<{ state: TicketState; run: string | null }>;
+
+const isLifecycleState = (state: string): state is LifecycleState => (TICKET_LIFECYCLE_STATES as ReadonlyArray<string>).includes(state);
+
+/** The ticket re-enters the state its row holds: a new ticket the state it was filed in. */
+const enter = (observed: TicketObserved) => ({ value: isLifecycleState(observed.state) ? observed.state : "Inbox", context: { run: observed.run } });
+
+/** A ticket's state from its lifecycle's: the product's ticket states, one for one. */
+export const ticketStateOf = (value: string): TicketState => {
+  const top = value.split(".")[0] ?? "";
+  return isLifecycleState(top) ? top : "Inbox";
+};
+
+export type TicketLifecycle = Lifecycle<TicketObserved> & Readonly<{ stateOf: (value: string) => TicketState }>;
+
+/** The framework's ticket lifecycle. */
+export const ticketLifecycle = (): TicketLifecycle => ({ name: "ticket", machine, enter, stateOf: ticketStateOf });

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

@@ -29,6 +29,10 @@ export const AUTHORING_MODULES = [
   "@thinair/factory/domain/system-elements/hole",
   "@thinair/factory/domain/system-elements/compose",
   "@thinair/factory/domain/step",
+  "@thinair/factory/domain/ticket-state",
+  "@thinair/factory/domain/lifecycles/lifecycle",
+  "@thinair/factory/domain/lifecycles/ticket",
+  "@thinair/factory/domain/lifecycles/run",
 ] as const;
 export type AuthoringModule = (typeof AUTHORING_MODULES)[number];
 

package/domain/system-elements/repository.ts

@@ -15,6 +15,8 @@ export const PullRequestFact = Schema.Struct({
   number: Schema.Int.check(Schema.isGreaterThan(0)),
   head: Commit,
   base: Schema.String,
+  /** The observed base commit: selection is against this exact tree, never a moving branch. */
+  baseCommit: Schema.optionalKey(Commit),
   branch: Schema.String,
   state: Schema.Literals(["open", "closed", "merged"]),
   draft: Schema.Boolean,

package/domain/system-elements/stage.ts

@@ -1,4 +1,6 @@
 import { Schema } from "effect";
+import { TICKET_STATES } from "../ticket-state";
+import type { Lifecycle } from "../lifecycles/lifecycle";
 import type { Out, Question, Seen, TicketView, Work } from "./compose";
 import { AUTHORED, authoredHead, head, Name, Ref, type Authored, type Encoder, type LiveRows, type Slot } from "./node";
 
@@ -8,9 +10,21 @@ import { AUTHORED, authoredHead, head, Name, Ref, type Authored, type Encoder, t
  * and returns what should exist now: wanted jobs and services, child
  * tickets, pins, judgments and acts. Compose may want only the jobs the
  * stage lists, and types enforce it. A stage's ticket state comes from its
- * verdict, or from its lifecycle when it has one.
+ * verdict, or from its lifecycle when it has one: a typed `stateOf` maps each
+ * of the lifecycle's states to one of the product's ticket states, checked at
+ * load. The Runs its `together` groups make follow the framework's Run
+ * lifecycle, or the one `runs` gives (another version of it).
  */
 
+/** A ticket lifecycle as a stage declares it: the machine, and the product state of each of its states. */
+export type StageTicketLifecycle = Lifecycle<never> & Readonly<{ stateOf: (value: string) => string }>;
+/** A Run lifecycle as a stage declares it. */
+export type StageRunLifecycle = Lifecycle<never>;
+
+/** The states a lifecycle's machine has at its top. */
+const statesOf = (lifecycle: Lifecycle<never>): ReadonlyArray<string> =>
+  Object.keys((lifecycle.machine as unknown as Readonly<{ root: Readonly<{ states: Readonly<Record<string, unknown>> }> }>).root.states);
+
 export const Node = Schema.TaggedStruct("Stage", {
   ...head,
   /** The only jobs and services compose may want. */
@@ -19,6 +33,10 @@ export const Node = Schema.TaggedStruct("Stage", {
   children: Schema.Array(Ref("Stage")),
   /** Questions compose may ask the judge, each a choice one of its services offers. */
   questions: Schema.Record(Name, Ref("Service")),
+  /** Its tickets' lifecycle, by its states; absent when its verdict decides their state. */
+  lifecycle: Schema.optionalKey(Schema.Struct({ name: Schema.String, states: Schema.Array(Schema.String) })),
+  /** The Run lifecycle its `together` groups follow, when it gives its own. */
+  runs: Schema.optionalKey(Schema.Struct({ name: Schema.String, states: Schema.Array(Schema.String) })),
 });
 export type Node = typeof Node.Type;
 
@@ -27,6 +45,10 @@ export interface AuthoredStage<N extends string = string, Spec = any, W extends
   readonly jobs: ReadonlyArray<W>;
   readonly children: ReadonlyArray<C>;
   readonly questions: Readonly<Record<string, Question<unknown>>>;
+  /** Its tickets' lifecycle; null when its verdict decides their state. */
+  readonly lifecycle: StageTicketLifecycle | null;
+  /** The Run lifecycle its groups follow; null for the framework's. */
+  readonly runs: StageRunLifecycle | null;
   readonly compose: (ticket: TicketView<Spec>, seen: Seen<W>) => ReadonlyArray<Out<W, C>>;
 }
 export type AnyStage = AuthoredStage<string, any, any, any>;
@@ -38,6 +60,10 @@ export const stage = <const N extends string, Spec, const W extends ReadonlyArra
   jobs?: W;
   children?: C;
   questions?: Readonly<Record<string, Question<any>>>;
+  /** Its tickets' lifecycle: `ticketLifecycle()` from `@thinair/factory/domain/lifecycles/ticket`. */
+  lifecycle?: StageTicketLifecycle;
+  /** Its Runs' lifecycle: `runLifecycle({ ... })` from `@thinair/factory/domain/lifecycles/run`. */
+  runs?: StageRunLifecycle;
   compose: (ticket: TicketView<Spec>, seen: Seen<W[number]>) => ReadonlyArray<Out<W[number], C[number]>>;
 }>): AuthoredStage<N, Spec, W[number], C[number]> => ({
   [AUTHORED]: authoredHead("Stage", name, true),
@@ -45,6 +71,8 @@ export const stage = <const N extends string, Spec, const W extends ReadonlyArra
   jobs: settings.jobs ?? [],
   children: settings.children ?? [],
   questions: settings.questions ?? {},
+  lifecycle: settings.lifecycle ?? null,
+  runs: settings.runs ?? null,
   compose: settings.compose,
 });
 
@@ -57,8 +85,20 @@ export const make = (authored: AnyStage, encoder: Encoder) => ({
     if (!authored.jobs.includes(question.service)) encoder.problem(`Question ${name} asks ${question.service[AUTHORED].name}, which this stage does not list in its jobs.`);
     return [name, encoder.ref("Service", question.service)];
   })),
+  ...(authored.lifecycle == null ? {} : { lifecycle: lifecycleOf(authored.lifecycle, encoder) }),
+  ...(authored.runs == null ? {} : { runs: { name: authored.runs.name, states: [...statesOf(authored.runs)] } }),
 });
 
+/** A ticket lifecycle's states, each checked to map to one of the product's ticket states. */
+const lifecycleOf = (lifecycle: StageTicketLifecycle, encoder: Encoder) => {
+  const states = statesOf(lifecycle);
+  for (const state of states) {
+    const product = lifecycle.stateOf(state);
+    if (!(TICKET_STATES as ReadonlyArray<string>).includes(product)) encoder.problem(`Its lifecycle's state ${state} maps to ${product}, which is not a ticket state.`);
+  }
+  return { name: lifecycle.name, states: [...states] };
+};
+
 /** Its tickets by state. */
 export const live = (node: Node, rows: LiveRows) => {
   const byState: Record<string, number> = {};

package/domain/ticket-state.ts

@@ -0,0 +1,5 @@
+import { Schema } from "effect";
+
+export const TICKET_STATES = ["Inbox", "Ready", "Running", "Asking", "Review", "Merged", "Shipped", "Waiting", "Dropped"] as const;
+export const TicketState = Schema.Literals(TICKET_STATES);
+export type TicketState = typeof TicketState.Type;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinair/factory",
-  "version": "0.1.120",
+  "version": "0.1.128",
   "description": "The Thinair factory SDK: the language a factory's code is written in, and the loader that checks it.",
   "license": "Apache-2.0",
   "type": "module",
@@ -21,13 +21,19 @@
     "./domain/system-elements/hole": "./domain/system-elements/hole.ts",
     "./domain/system-elements/compose": "./domain/system-elements/compose.ts",
     "./domain/step": "./domain/step.ts",
+    "./domain/ticket-state": "./domain/ticket-state.ts",
+    "./domain/lifecycles/lifecycle": "./domain/lifecycles/lifecycle.ts",
+    "./domain/lifecycles/ticket": "./domain/lifecycles/ticket.ts",
+    "./domain/lifecycles/run": "./domain/lifecycles/run.ts",
     "./domain/system-elements/program": "./domain/system-elements/program.ts",
     "./domain/load": "./domain/load.ts",
     "./cli/load": "./cli/load.ts"
   },
   "dependencies": {
     "effect": "4.0.0-rc.117",
-    "oxlint": "1.88.0"
+    "oxlint": "1.88.0",
+    "xstate": "6.0.0-alpha.66",
+    "@xstate/effect": "0.1.0-alpha.7"
   },
   "engines": {
     "bun": ">=1.4.3"