@thinair/factory 0.0.0-stage → 0.1.124

package/domain/system-elements/node.ts

@@ -0,0 +1,189 @@
+import { Schema } from "effect";
+
+/*
+ * What every node of a factory program shares: its tag, its id, where it was
+ * made, its digest, and typed references to other nodes. A program is a
+ * graph: each node is stored once under its id, and every edge is a Ref.
+ *
+ * Authored values are what factory code builds with the constructors
+ * (`stage(...)`, `job(...)`, `hole(...)`). Each carries a head under one
+ * well-known symbol, so the encoder reads it the same from any copy of this
+ * package. Encoding turns them into nodes and their links into Refs.
+ *
+ * This file and every file beside it import only `effect`: factory code
+ * imports them, and they are published as `@thinair/factory`.
+ */
+
+export const TAGS = ["Factory", "Repository", "Source", "Rule", "Stage", "Job", "Service", "Pool", "Agent", "Goal", "Hole"] as const;
+export const Tag = Schema.Literals(TAGS);
+export type Tag = typeof Tag.Type;
+
+/** The tags a Ref points at. A Hole stands in for one of them until it is built. */
+export const NODE_TAGS = ["Factory", "Repository", "Source", "Rule", "Stage", "Job", "Service", "Pool", "Agent", "Goal"] as const;
+export const NodeTag = Schema.Literals(NODE_TAGS);
+export type NodeTag = typeof NodeTag.Type;
+
+type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+/** Proof: the Ref tags are every tag but Hole. */
+export const nodeTagsAreTagsWithoutHole: Same<NodeTag, Exclude<Tag, "Hole">> = true;
+
+const NAME = "[a-z0-9]+(?:[.-][a-z0-9]+)*";
+
+/** A name an author gives a node: lowercase words and digits joined by dashes or dots. */
+export const Name = Schema.String.check(Schema.isPattern(new RegExp(`^${NAME}$`, "u")), Schema.isMaxLength(64));
+
+/** `<lowercase tag>:<name>`, as `stage:change`. A Hole keeps the id of the node it stands for. */
+export const NodeId = Schema.String.check(
+  Schema.isPattern(new RegExp(`^(?:${NODE_TAGS.map((tag) => tag.toLowerCase()).join("|")}):${NAME}$`, "u")),
+  Schema.isMaxLength(80),
+).pipe(Schema.brand("NodeId"));
+export type NodeId = typeof NodeId.Type;
+
+export const nodeId = (tag: NodeTag, name: string): NodeId => `${tag.toLowerCase()}:${name}` as NodeId;
+
+/** The root's name: a factory has no name in code; its File names it. */
+export const ROOT_NAME = "root";
+export const ROOT_ID = nodeId("Factory", ROOT_NAME);
+
+/** Where a node was made: a file relative to the factory folder, and a line. */
+export const SourceAt = Schema.Struct({
+  file: Schema.String.check(Schema.isMinLength(1)),
+  line: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+});
+export type SourceAt = typeof SourceAt.Type;
+
+/** A SHA-256, in lowercase hex. */
+export const Digest = Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/u)).pipe(Schema.brand("Digest"));
+export type Digest = typeof Digest.Type;
+
+/** A reference to a node of tag T, or to a Hole that expects one. */
+export const Ref = <const T extends NodeTag>(to: T) => Schema.TaggedStruct("Ref", { to: Schema.Literal(to), id: NodeId });
+export interface Ref<T extends NodeTag> {
+  readonly _tag: "Ref";
+  readonly to: T;
+  readonly id: NodeId;
+}
+export const AnyRef = Schema.TaggedStruct("Ref", { to: NodeTag, id: NodeId });
+
+/** The fields every node has besides its tag. The digest covers what it is, not where it was made. */
+export const head = { id: NodeId, at: SourceAt, digest: Digest } as const;
+
+// Authored values.
+
+/** The key of an authored value's head. `Symbol.for`, so every copy of this package reads it. */
+export const AUTHORED: unique symbol = Symbol.for("@thinair/factory/authored");
+
+/** Where an authored value was made, as the runtime saw it: an absolute file. */
+export type MadeAt = Readonly<{ file: string; line: number }>;
+
+export type Head<T extends Tag, N extends string = string> = Readonly<{
+  tag: T;
+  name: N;
+  at: MadeAt | null;
+  /** It holds code (compose, a step, a route): its digest covers the import closure of its file. */
+  code: boolean;
+}>;
+
+export interface Authored<T extends Tag, N extends string = string> {
+  readonly [AUTHORED]: Head<T, N>;
+}
+
+/** A Hole planned where a node of tag T will go. */
+export interface HoleFor<T extends NodeTag, N extends string = string> {
+  readonly [AUTHORED]: Head<"Hole", N> & Readonly<{ expects: T }>;
+}
+
+/** What a place for a node of tag T accepts: the node, or a Hole planned in its place. */
+export type Slot<T extends NodeTag> = Authored<T> | HoleFor<T>;
+
+/** A kind of fact a repository or a source posts, with its value's schema. Rules listen on it. */
+export interface FactKind<A> {
+  readonly from: Authored<"Repository"> | Authored<"Source">;
+  /** camelCase, unique in its repository or source: `pullRequest`. */
+  readonly kind: string;
+  readonly schema: Schema.Codec<A, any, never, never>;
+}
+export const FactKindName = Schema.String.check(Schema.isPattern(/^[a-z][A-Za-z0-9]{0,63}$/u));
+
+export const isAuthored = (value: unknown): value is Authored<Tag> =>
+  typeof value === "object" && value !== null && AUTHORED in value;
+
+export const headOf = (value: Authored<Tag>): Head<Tag> & Readonly<{ expects?: NodeTag }> => value[AUTHORED];
+
+/** The id an authored value encodes to: a Hole's is the id of the node it stands for. */
+export const idOf = (value: Authored<Tag>): NodeId => {
+  const made = headOf(value);
+  return nodeId(made.tag === "Hole" ? (made.expects ?? "Factory") : made.tag, made.name);
+};
+
+/** A Ref to an authored node, without encoding it. */
+export const refTo = <T extends NodeTag>(to: T, value: Slot<T>): Ref<T> => ({ _tag: "Ref", to, id: idOf(value) });
+
+/** The head of a new authored value, with where its constructor was called from. */
+export const authoredHead = <T extends Tag, N extends string>(tag: T, name: N, code: boolean): Head<T, N> =>
+  ({ tag, name, at: madeAt(), code });
+
+/** `at /abs/file.ts:12:3`, `at fn (/abs/file.ts:12:3)` or `at file:///abs/file.ts:12:3`. */
+const FRAME = /\(?((?:file:\/\/)?\/[^():]+|[A-Za-z]:[\\/][^():]+):(\d+):\d+\)?\s*$/u;
+
+const directoryOf = (file: string) => file.slice(0, Math.max(file.lastIndexOf("/"), file.lastIndexOf("\\")));
+
+/**
+ * The first caller outside this folder: the factory file whose constructor
+ * call made the value. Every constructor lives beside this file, so frames
+ * in this folder are the framework's own.
+ */
+const madeAt = (): MadeAt | null => {
+  const frames = (new Error().stack ?? "").split("\n").slice(1).flatMap((line): MadeAt[] => {
+    const match = FRAME.exec(line);
+    if (match === null) return [];
+    const raw = match[1]!;
+    const file = raw.startsWith("file://") ? decodeURIComponent(raw.slice("file://".length)) : raw;
+    return [{ file, line: Number(match[2]) }];
+  });
+  const own = frames[0];
+  if (own === undefined) return null;
+  const framework = directoryOf(own.file);
+  return frames.find((frame) => directoryOf(frame.file) !== framework) ?? null;
+};
+
+// Engine meanings.
+
+/** Which engine gives a tag its meaning: the plane, the factory VM, or neither. */
+export type Owner = "plane" | "vm" | "none";
+
+/** What a tag's make() may ask while it encodes one authored value. */
+export interface Encoder {
+  /** The Ref to a node it holds, encoding that node once. */
+  readonly ref: <T extends NodeTag>(to: T, value: Slot<T>) => Ref<T>;
+  /** A problem with this node's settings, pinned to it. */
+  readonly problem: (message: string) => void;
+}
+
+/** The rows a floor reads, by the node each belongs to. The records name their nodes by id. */
+export const LiveRows = Schema.Struct({
+  tickets: Schema.Array(Schema.Struct({ id: Schema.String, stage: NodeId, goal: Schema.NullOr(NodeId), state: Schema.String })),
+  jobs: Schema.Array(Schema.Struct({
+    id: Schema.String,
+    node: NodeId,
+    state: Schema.Literals(["waiting", "bound", "running", "succeeded", "failed", "stopped"]),
+    machine: Schema.NullOr(Schema.String),
+  })),
+  machines: Schema.Array(Schema.Struct({ pool: NodeId, machine: Schema.String, ready: Schema.Boolean })),
+  facts: Schema.Array(Schema.Struct({ from: NodeId, kind: Schema.String, key: Schema.String, at: Schema.String })),
+});
+export type LiveRows = typeof LiveRows.Type;
+
+/** A node's settings: everything make() decides, without its tag, id, place or digest. */
+export type SettingsOf<N> = N extends unknown ? Omit<N, "_tag" | "id" | "at" | "digest"> : never;
+
+/**
+ * One tag's definition: its node's schema, how an authored value becomes its
+ * settings, its live read (a data-element), and the engine that owns it.
+ */
+export type Definition<T extends Tag> = Readonly<{
+  Node: Readonly<{ Type: Readonly<{ _tag: T }> }>;
+  make: (authored: never, encoder: Encoder) => object;
+  live: (node: never, rows: LiveRows) => unknown;
+  owner: Owner;
+}>;

package/domain/system-elements/pool.ts

@@ -0,0 +1,63 @@
+import { Schema } from "effect";
+import { AUTHORED, authoredHead, head, type Authored, type LiveRows } from "./node";
+
+/*
+ * A pool names a provider and an optional narrowing, nothing else.
+ * `pool.macs()` means every Mac that granted this factory `work`. Room, os,
+ * arch, VMs, identities and reserve come only from each machine's facts, so
+ * two factories never give placement two truths about one machine. The
+ * plane gives pools their meaning: its executors.
+ */
+
+export const PROVIDERS = ["macs", "thinair-cloud", "namespace", "github-actions"] as const;
+export const Provider = Schema.Literals(PROVIDERS);
+export type Provider = typeof Provider.Type;
+
+export const Os = Schema.Literals(["mac", "linux", "windows"]);
+export type Os = typeof Os.Type;
+export const Arch = Schema.Literals(["arm64", "x64"]);
+export type Arch = typeof Arch.Type;
+
+/** An empty list means any. */
+export const Narrowing = Schema.Struct({ os: Schema.Array(Os), arch: Schema.Array(Arch) });
+export type Narrowing = typeof Narrowing.Type;
+
+export const Node = Schema.TaggedStruct("Pool", { ...head, provider: Provider, ...Narrowing.fields });
+export type Node = typeof Node.Type;
+
+export interface AuthoredPool<P extends Provider = Provider> extends Authored<"Pool", P> {
+  readonly provider: P;
+  readonly os: ReadonlyArray<Os>;
+  readonly arch: ReadonlyArray<Arch>;
+}
+
+type Narrow = Readonly<{ os?: ReadonlyArray<Os>; arch?: ReadonlyArray<Arch> }>;
+
+const made = <const P extends Provider>(provider: P, narrow: Narrow | undefined): AuthoredPool<P> => ({
+  [AUTHORED]: authoredHead("Pool", provider, false),
+  provider,
+  os: narrow?.os ?? [],
+  arch: narrow?.arch ?? [],
+});
+
+/** The pools a factory can name. Each is named after its provider: `pool:macs`. */
+export const pool = {
+  /** Every Mac that granted this factory `work`. */
+  macs: (narrow?: Narrow) => made("macs", narrow),
+  /** Thinair Cloud VMs, on Thinair Computer Inc's account. */
+  thinairCloud: (narrow?: Narrow) => made("thinair-cloud", narrow),
+  /** Namespace instances, with the Profile's key. */
+  namespace: (narrow?: Narrow) => made("namespace", narrow),
+  /** GitHub Actions runners, dispatched with the Agents App. */
+  githubActions: (narrow?: Narrow) => made("github-actions", narrow),
+};
+
+export const make = (authored: AuthoredPool) => ({ provider: authored.provider, os: [...authored.os], arch: [...authored.arch] });
+
+/** The machines placement can use now, from their own facts. */
+export const live = (node: Node, rows: LiveRows) => {
+  const machines = rows.machines.filter((machine) => machine.pool === node.id);
+  return { machines: machines.map(({ machine, ready }) => ({ machine, ready })), ready: machines.filter((machine) => machine.ready).length };
+};
+
+export const owner = "plane" as const;

package/domain/system-elements/program.ts

@@ -0,0 +1,123 @@
+import { Schema } from "effect";
+import * as agent from "./agent";
+import * as factory from "./factory";
+import * as goal from "./goal";
+import * as hole from "./hole";
+import * as job from "./job";
+import { NodeId, ROOT_ID, type NodeTag, type Ref } from "./node";
+import * as pool from "./pool";
+import * as repository from "./repository";
+import * as rule from "./rule";
+import * as service from "./service";
+import * as source from "./source";
+import * as stage from "./stage";
+
+/*
+ * The language: a factory's code compiles to one Program. It is pure data,
+ * versioned, and decoded at every boundary: the loader encodes it, the plane
+ * stores it by revision, the factory VM runs it and the Frame draws it.
+ *
+ * It is a graph, not a tree. Stages share jobs; rules, agents and stages
+ * point at each other. Every node is stored once under its id, and every
+ * edge is a typed Ref. A node's digest covers what it is (its settings, and
+ * the import closure of its file when it holds code), never the nodes it
+ * refers to: editing a job redraws that job, not every stage that holds it.
+ *
+ * `version` is the language. A break bumps it, with a decode migration.
+ */
+
+export const LANGUAGE_VERSION = 1;
+
+export const Node = Schema.Union([
+  factory.Node, repository.Node, source.Node, rule.Node, stage.Node, job.Node, service.Node, pool.Node, agent.Node, goal.Node, hole.Node,
+]);
+export type Node = typeof Node.Type;
+
+/** A `@thinair/factory` version: plain semver, with an optional prerelease. */
+export const FrameworkVersion = Schema.String.check(Schema.isPattern(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u));
+
+export const Program = Schema.Struct({
+  version: Schema.Literal(LANGUAGE_VERSION),
+  /** The `@thinair/factory` version the code was loaded with. */
+  framework: FrameworkVersion,
+  /** The Factory node. */
+  root: NodeId,
+  /** Every node exactly once. Edges are Refs inside settings. */
+  nodes: Schema.Record(NodeId, Node),
+});
+export type Program = typeof Program.Type;
+
+/** The program as JSON: the form every boundary carries. */
+export const ProgramJson = Schema.toCodecJson(Program);
+
+/** Every Ref inside a node's settings, in order: the floor's belts. */
+export const edgesOf = (node: Node): ReadonlyArray<Ref<NodeTag>> => {
+  const edges: Array<Ref<NodeTag>> = [];
+  const walk = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item);
+    } else if (typeof value === "object" && value !== null) {
+      const record = value as Readonly<Record<string, unknown>>;
+      if (record["_tag"] === "Ref" && typeof record["id"] === "string" && typeof record["to"] === "string") edges.push(record as unknown as Ref<NodeTag>);
+      else for (const [key, item] of Object.entries(record)) if (key !== "at") walk(item);
+    }
+  };
+  for (const [key, value] of Object.entries(node)) if (key !== "at" && key !== "id" && key !== "digest") walk(value);
+  return edges;
+};
+
+/** A problem with the graph itself, pinned to a node. */
+export type GraphProblem = Readonly<{ node: NodeId; message: string }>;
+
+/**
+ * The value checks every program passes before it runs: the root is a
+ * Factory, every node sits under its own id, and every Ref resolves to a
+ * node of its tag or a Hole that expects one.
+ */
+export const graphProblems = (program: Program): ReadonlyArray<GraphProblem> => {
+  const problems: GraphProblem[] = [];
+  const root = program.nodes[program.root];
+  if (root === undefined || root._tag !== "Factory" || program.root !== ROOT_ID)
+    problems.push({ node: program.root, message: `The root must be the factory itself (${ROOT_ID}), made by defineFactory in factory.ts.` });
+  for (const [id, node] of Object.entries(program.nodes) as Array<[NodeId, Node]>) {
+    if (node.id !== id) problems.push({ node: id, message: `The node under ${id} names itself ${node.id}.` });
+    for (const edge of edgesOf(node)) {
+      const target = program.nodes[edge.id];
+      if (target === undefined) problems.push({ node: id, message: `It refers to ${edge.id}, which the program does not hold.` });
+      else if (target._tag !== edge.to && !(target._tag === "Hole" && target.expects === edge.to))
+        problems.push({ node: id, message: `It refers to ${edge.id} as a ${edge.to}, but that node is a ${target._tag === "Hole" ? `hole for a ${target.expects}` : target._tag}.` });
+    }
+  }
+  return problems;
+};
+
+/** The holes still to build, by the tag each expects, then by id. */
+export const holesOf = (program: Program): ReadonlyArray<Readonly<{ expects: NodeTag; id: NodeId }>> =>
+  (Object.values(program.nodes) as Node[])
+    .flatMap((node) => (node._tag === "Hole" ? [{ expects: node.expects, id: node.id }] : []))
+    .sort((left, right) => left.expects.localeCompare(right.expects) || left.id.localeCompare(right.id));
+
+export type NodeDiff = Readonly<{ added: ReadonlyArray<NodeId>; removed: ReadonlyArray<NodeId>; changed: ReadonlyArray<NodeId> }>;
+
+/**
+ * The approvals a new program loosens against the one that runs: each the running root declares that the new root
+ * drops or asks of someone else. Such a revision waits for the owner's own press before it runs.
+ */
+export const loosenedApprovals = (running: Program | null, next: Program): ReadonlyArray<string> => {
+  const before = running?.nodes[running.root];
+  const after = next.nodes[next.root];
+  if (before?._tag !== "Factory") return [];
+  const kept = after?._tag === "Factory" ? after.approvals : {};
+  return Object.entries(before.approvals).filter(([name, approval]) => kept[name]?.by !== approval.by).map(([name]) => name).sort();
+};
+
+/** What changed between two programs, node by node, by digest. A filled hole is one change in place. */
+export const nodeDiff = (before: Program | null, after: Program): NodeDiff => {
+  const old = before?.nodes ?? {};
+  const ids = (nodes: Readonly<Record<string, Node>>) => Object.keys(nodes).sort() as NodeId[];
+  return {
+    added: ids(after.nodes).filter((id) => old[id] === undefined),
+    removed: ids(old).filter((id) => after.nodes[id] === undefined),
+    changed: ids(after.nodes).filter((id) => old[id] !== undefined && (old[id]._tag !== after.nodes[id]!._tag || old[id].digest !== after.nodes[id]!.digest)),
+  };
+};

package/domain/system-elements/registry.ts

@@ -0,0 +1,173 @@
+import { Result, Schema } from "effect";
+import * as agent from "./agent";
+import * as factory from "./factory";
+import * as goal from "./goal";
+import * as hole from "./hole";
+import * as job from "./job";
+import {
+  headOf, idOf, isAuthored, Name, nodeId, ROOT_ID,
+  type Definition, type Encoder, type MadeAt, type NodeId, type NodeTag, type Ref, type SourceAt, type Tag,
+} from "./node";
+import * as pool from "./pool";
+import { graphProblems, LANGUAGE_VERSION, Program, type Node } from "./program";
+import * as repository from "./repository";
+import * as rule from "./rule";
+import * as service from "./service";
+import * as source from "./source";
+import * as stage from "./stage";
+
+/*
+ * One definition per tag: its node, make, live and owner. A new tag does not
+ * compile until its definition exists here, and each engine's registry is
+ * exhaustive over the tags it owns: the plane over PlaneTag, the factory VM
+ * over VmTag. Nothing is discovered from folders.
+ *
+ * The encoder turns authored values into a Program: it walks from the root,
+ * stores each node once under its id (interning), and writes every link as
+ * a Ref. The same id with different content is a problem pinned to that id.
+ */
+
+export const definitions = {
+  Factory: factory,
+  Repository: repository,
+  Source: source,
+  Rule: rule,
+  Stage: stage,
+  Job: job,
+  Service: service,
+  Pool: pool,
+  Agent: agent,
+  Goal: goal,
+  Hole: hole,
+} satisfies { readonly [T in Tag]: Definition<T> };
+
+type OwnerOf<T extends Tag> = (typeof definitions)[T]["owner"];
+/** The tags the plane gives a meaning: the repository watcher and the executors. */
+export type PlaneTag = { [T in Tag]: OwnerOf<T> extends "plane" ? T : never }[Tag];
+/** The tags the factory VM gives a meaning: everything a pass runs. */
+export type VmTag = { [T in Tag]: OwnerOf<T> extends "vm" ? T : never }[Tag];
+
+/** Proof: no tag has two engine meanings. */
+export const planeAndVmAreDisjoint: [Extract<PlaneTag, VmTag>] extends [never] ? true : false = true;
+
+/** Where the encoder found a problem: a node when it knows one, and where it was made. */
+export type EncodeProblem = Readonly<{ node: NodeId | null; at: SourceAt | null; message: string }>;
+
+/** A file of the factory folder: its content digest and the files it imports, both relative to the folder. */
+export type FileFacts = Readonly<{ digest: string; imports: ReadonlyArray<string> }>;
+
+export type EncodeOptions = Readonly<{
+  /** The factory folder, absolute: where made-at paths are made relative to. */
+  tree: string;
+  /** The `@thinair/factory` version doing the encoding. */
+  framework: string;
+  /** SHA-256 of a text, in lowercase hex. */
+  hash: (text: string) => string;
+  /** The folder's import graph, by relative path. Without it, digests cover settings only. */
+  files: Readonly<Record<string, FileFacts>>;
+}>;
+
+export type Encoded = Readonly<{ program: Program | null; problems: ReadonlyArray<EncodeProblem> }>;
+
+/** JSON with keys sorted at every level: two values are the same when this is. */
+const canonicalJson = (value: unknown): string => JSON.stringify(value, (_key, item: unknown) =>
+  item !== null && typeof item === "object" && !Array.isArray(item)
+    ? Object.fromEntries(Object.entries(item as Record<string, unknown>).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)))
+    : item);
+
+type Draft = Readonly<{ node: Readonly<Record<string, unknown>> & { readonly at: SourceAt }; code: boolean; content: string }>;
+
+/** Encode a factory's root, as `factory.ts` exports it, into its Program. */
+export const encodeFactory = (root: unknown, options: EncodeOptions): Encoded => {
+  const problems: EncodeProblem[] = [];
+  const drafts = new Map<NodeId, Draft>();
+  const encodedValues = new Map<object, NodeId>();
+  const visiting = new Set<object>();
+  let broken = false;
+
+  const tree = options.tree.replace(/[\\/]+$/u, "");
+  const sourceAt = (at: MadeAt | null): SourceAt => {
+    if (at === null) return { file: "factory.ts", line: 1 };
+    const file = at.file.split("\\").join("/");
+    return { file: file.startsWith(`${tree}/`) ? file.slice(tree.length + 1) : file, line: Math.max(1, at.line) };
+  };
+
+  const encode = <T extends NodeTag>(to: T, value: unknown, from: Readonly<{ node: NodeId; at: SourceAt }> | null): Ref<T> => {
+    if (!isAuthored(value)) {
+      broken = true;
+      problems.push({ node: from?.node ?? null, at: from?.at ?? null, message: `A ${to} goes here, but this value was not made by a factory constructor.` });
+      return { _tag: "Ref", to, id: nodeId(to, "not-a-node") };
+    }
+    const made = headOf(value);
+    const at = sourceAt(made.at);
+    const id = idOf(value);
+    const ref: Ref<T> = { _tag: "Ref", to, id };
+    if (made.tag !== to && !(made.tag === "Hole" && made.expects === to)) {
+      broken = true;
+      problems.push({ node: from?.node ?? id, at: from?.at ?? at, message: `A ${to} goes here, but ${id} is ${made.tag === "Hole" ? `a hole for a ${made.expects}` : `a ${made.tag}`}.` });
+      return ref;
+    }
+    if (encodedValues.has(value) || visiting.has(value)) return ref;
+    if (Result.isFailure(Schema.decodeUnknownResult(Name)(made.name))) {
+      broken = true;
+      problems.push({ node: null, at, message: `"${made.name}" is not a ${made.tag === "Hole" ? made.expects : made.tag} name: use lowercase words and digits joined by dashes or dots, at most 64 characters.` });
+      return ref;
+    }
+    visiting.add(value);
+    const encoder: Encoder = {
+      ref: (tag, slot) => encode(tag, slot, { node: id, at }),
+      problem: (message) => problems.push({ node: id, at, message }),
+    };
+    const settings = (definitions[made.tag] as Definition<Tag>).make(value as never, encoder);
+    visiting.delete(value);
+    encodedValues.set(value, id);
+    const node = { _tag: made.tag, id, at, ...settings };
+    const content = canonicalJson({ ...node, at: undefined });
+    const first = drafts.get(id);
+    if (first === undefined) drafts.set(id, { node, code: made.code, content });
+    else if (first.content !== content)
+      problems.push({ node: id, at, message: `Two different nodes are named ${id}: one made at ${first.node.at.file}:${first.node.at.line}, one here. Rename one, or make them the same.` });
+    return ref;
+  };
+
+  if (!isAuthored(root) || headOf(root).tag !== "Factory") {
+    problems.push({ node: null, at: { file: "factory.ts", line: 1 }, message: "factory.ts's default export is the factory: export default defineFactory({ ... })." });
+    return { program: null, problems };
+  }
+  encode("Factory", root, null);
+  if (broken) return { program: null, problems };
+
+  // A node's digest covers its content and, when it holds code, the import closure of its file,
+  // stopping at files that make other nodes: those nodes have digests of their own.
+  const madeIn = new Set([...drafts.values()].map((draft) => draft.node.at.file));
+  const closures = new Map<string, string>();
+  const closureOf = (start: string): string => {
+    const known = closures.get(start);
+    if (known !== undefined) return known;
+    if (options.files[start] === undefined) return "";
+    const seen = new Set<string>();
+    const pending = [start];
+    while (pending.length > 0) {
+      const file = pending.pop()!;
+      if (seen.has(file)) continue;
+      seen.add(file);
+      for (const imported of options.files[file]?.imports ?? [])
+        if (options.files[imported] !== undefined && !(imported !== start && madeIn.has(imported))) pending.push(imported);
+    }
+    const closure = options.hash([...seen].sort().map((file) => `${file} ${options.files[file]!.digest}`).join("\n"));
+    closures.set(start, closure);
+    return closure;
+  };
+  const nodes: Record<string, unknown> = {};
+  for (const [id, draft] of [...drafts].sort(([left], [right]) => (left < right ? -1 : 1)))
+    nodes[id] = { ...draft.node, digest: options.hash(`${draft.content}\n${draft.code ? closureOf(draft.node.at.file) : ""}`) };
+
+  const decoded = Schema.decodeUnknownResult(Program)({ version: LANGUAGE_VERSION, framework: options.framework, root: ROOT_ID, nodes });
+  if (Result.isFailure(decoded)) {
+    problems.push({ node: null, at: null, message: `The program does not decode: ${decoded.failure.message}` });
+    return { program: null, problems };
+  }
+  for (const problem of graphProblems(decoded.success))
+    problems.push({ node: problem.node, at: (decoded.success.nodes[problem.node] as Node | undefined)?.at ?? null, message: problem.message });
+  return { program: decoded.success, problems };
+};

package/domain/system-elements/repository.ts

@@ -0,0 +1,79 @@
+import { Schema } from "effect";
+import { AUTHORED, authoredHead, head, type Authored, type FactKind, type LiveRows } from "./node";
+
+/*
+ * A repository the factory builds. It owns its GitHub facts; there is no
+ * separate GitHub source. `web.facts.pullRequest`, `.mergeGroup` and
+ * `.head` are typed, and rules listen on them. The plane's repository
+ * watcher gives it its meaning.
+ */
+
+/** A git commit: 40 or 64 hex characters. */
+export const Commit = Schema.String.check(Schema.isPattern(/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u));
+
+export const PullRequestFact = Schema.Struct({
+  number: Schema.Int.check(Schema.isGreaterThan(0)),
+  head: Commit,
+  base: Schema.String,
+  branch: Schema.String,
+  state: Schema.Literals(["open", "closed", "merged"]),
+  draft: Schema.Boolean,
+  title: Schema.String,
+});
+export type PullRequestFact = typeof PullRequestFact.Type;
+export const MergeGroupFact = Schema.Struct({ head: Commit, base: Schema.String });
+export type MergeGroupFact = typeof MergeGroupFact.Type;
+/** A branch's head, keyed by the branch. */
+export const HeadFact = Schema.Struct({ branch: Schema.String, commit: Commit });
+export type HeadFact = typeof HeadFact.Type;
+
+export const Node = Schema.TaggedStruct("Repository", {
+  ...head,
+  /** `owner/name` on GitHub. */
+  github: Schema.String.check(Schema.isPattern(/^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/u)),
+  base: Schema.String.check(Schema.isMinLength(1)),
+  devcontainer: Schema.NullOr(Schema.String),
+});
+export type Node = typeof Node.Type;
+
+export interface AuthoredRepository<N extends string = string> extends Authored<"Repository", N> {
+  readonly github: string;
+  readonly base: string;
+  readonly devcontainer: string | null;
+  readonly facts: Readonly<{
+    pullRequest: FactKind<PullRequestFact>;
+    mergeGroup: FactKind<MergeGroupFact>;
+    head: FactKind<HeadFact>;
+  }>;
+}
+
+/** `repository("web", { github: "acme/website", base: "main" })`. */
+export const repository = <const N extends string>(name: N, settings: Readonly<{ github: string; base: string; devcontainer?: string }>): AuthoredRepository<N> => {
+  const made = {
+    [AUTHORED]: authoredHead("Repository", name, false),
+    github: settings.github,
+    base: settings.base,
+    devcontainer: settings.devcontainer ?? null,
+  };
+  const from: Authored<"Repository"> = made;
+  return Object.assign(made, {
+    facts: {
+      pullRequest: { from, kind: "pullRequest", schema: PullRequestFact },
+      mergeGroup: { from, kind: "mergeGroup", schema: MergeGroupFact },
+      head: { from, kind: "head", schema: HeadFact },
+    },
+  });
+};
+
+export const make = (authored: AuthoredRepository) => ({ github: authored.github, base: authored.base, devcontainer: authored.devcontainer });
+
+/** Its newest facts: the base's head and the open pull requests the watcher saw. */
+export const live = (node: Node, rows: LiveRows) => {
+  const facts = rows.facts.filter((fact) => fact.from === node.id);
+  return {
+    head: facts.filter((fact) => fact.kind === "head" && fact.key === node.base).at(-1)?.at ?? null,
+    pullRequests: new Set(facts.filter((fact) => fact.kind === "pullRequest").map((fact) => fact.key)).size,
+  };
+};
+
+export const owner = "plane" as const;