@forgezero/agent 0.1.0 → 0.1.9

package/README.md

@@ -78,13 +78,56 @@ sync       what changed since a cursor
 held       what this guest is holding, by name only
 ```
 
+The vault socket never accepts commands or deployment definitions. Deployment
+enters through the root-only control socket or the signed outbound claim path,
+then the deployment manager validates the checked-in definition and submits it
+to the common keyed queue. Keeping execution off the vault socket prevents a
+compromised application from turning secret-read access into a local shell.
+
 `attest` **refuses** when no source is configured rather than returning
 something attestation-shaped. An operator who believes they have an attestation
 when nothing produced one is worse off than one told plainly it is unavailable.
 
-Full documentation: **https://forgezero.net/docs/agent**
+## Deployment definitions
+
+A repository may commit `.fz/deploy.yaml` with its own roles, prerequisite
+checks, commands, and the exact secret names each step needs. ForgeZero does not
+choose a tenant's database, framework, or deploy shape. The agent validates the
+file before executing any command, prepares only the selected role, and gives a
+step only the vault values it explicitly names. `await` returns the complete
+pipeline result; no polling service or persistent queue is required.
+
+The daemon owns source checkout and command execution. On a platform node it
+watches the configured branch after bootstrap, resolves every change to an
+exact commit, and writes `pending` then `running` before submitting that commit
+to the keyed queue. A restart in either state resumes the exact commit; only an
+awaited successful pipeline writes `deployed`. Tenant nodes receive the same
+exact-commit request from the signed API claim path.
+
+An operator may also force a deployment and await the complete result over the
+private control socket:
+
+```bash
+fz-agent deploy --revision=<full-40-character-commit> --coordinator
+fz-agent status
+fz-agent pause
+fz-agent pause-key --key=project:production
+fz-agent stop-key --key=project:production   # running finishes; pending work is removed
+fz-agent start-key --key=project:production
+fz-agent cancel --id=q_42
+```
+
+The node seed and read-only Git private key are loaded with
+`LoadCredentialEncrypted=`. Their encrypted, host-bound blobs persist under
+`/etc/forgezero/creds`; decrypted values exist only in the service's private
+`$CREDENTIALS_DIRECTORY`. Platform bootstrap has no second clone/build path.
+Bootstrap records the forge's SSH host key during the attended access check;
+the daemon uses `StrictHostKeyChecking=yes` and never accepts a new host key by
+itself.
+
+Full documentation: **https://www.forgezero.net/docs/agent**
 
 ## Licence
 
-MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
 deploys.

package/dist/attestation-client.d.ts

@@ -0,0 +1,22 @@
+import type { NodeKeyPair } from '@forgezero/runtime/identity';
+import type { AttestationSource } from './socket';
+import { type SignedNodeHttpOptions } from './signed-node-http';
+export interface NodeAttestationOptions extends SignedNodeHttpOptions {
+    keys: NodeKeyPair;
+    source: AttestationSource;
+    intervalMs?: number;
+    /** Defaults to true. Set false after an explicitly awaited first attestation. */
+    immediate?: boolean;
+    setTimer?: (callback: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    onEvent?: (event: string, detail?: unknown) => void;
+}
+/** One challenge, one PSP report, one signed presentation. */
+export declare function attestNodeOnce(options: NodeAttestationOptions): Promise<{
+    measurement: string;
+    ageMs: number;
+}>;
+/** Re-attest without overlap; shutdown waits for the in-flight PSP/KDS round trip. */
+export declare function startNodeAttestation(options: NodeAttestationOptions): {
+    stop(): Promise<void>;
+};

package/dist/attestation-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/compute.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Guest lifecycle on a machine — ours or a tenant's, identically.
+ *
+ * ## Why each guest is its own systemd unit
+ *
+ * The obvious shape is for the agent to launch qemu and keep track of it. That
+ * makes every guest a CHILD of the agent, and it means upgrading the agent —
+ * `systemctl restart fz-agent` — kills every tenant compute on the box. A host
+ * you cannot patch without an outage is a host that does not get patched.
+ *
+ * So the agent never owns a running guest. It writes a unit, asks systemd to
+ * start it, and walks away. systemd owns the process, restarts it after a host
+ * reboot, and survives the agent being replaced underneath it.
+ *
+ * ## Why the inventory lives on the root host
+ *
+ * The API is authoritative for what SHOULD exist. The host is authoritative for
+ * what DOES. Those disagree during an outage, a partial provision, or an
+ * operator's manual `kill` — and the host's answer is the one that matters when
+ * somebody is about to overwrite a disk.
+ *
+ * Persisting it here also means the host can bring its guests back with no
+ * control plane at all: the units are on disk, systemd starts them, and the
+ * platform reconciles later. A machine that needs the API to boot its tenants'
+ * computes is a machine that takes them down with it.
+ */
+export interface GuestSpec {
+    /** Stable name. Becomes the unit name, so it must be a valid identifier. */
+    name: string;
+    vcpu: number;
+    /** Exclusive host CPUs assigned to this guest's whole QEMU service. */
+    allowedCpus?: string;
+    /** NUMA memory nodes paired with allowedCpus, when the host exposes them. */
+    allowedMemoryNodes?: string;
+    memoryGib: number;
+    /** Block device or image path. Raw LVM on our metal; a file is allowed. */
+    disk: string;
+    /** cloud-init seed, attached read-only. */
+    seed: string;
+    bridge: string;
+    mac: string;
+    /** Stable tap owned by this unit. Required when egress is shaped. */
+    tap?: string;
+    /** Sustained guarantee and borrowable ceiling, in Mbit/s. */
+    egress?: {
+        guaranteedMbps: number;
+        burstMbps: number;
+    };
+    /**
+     * SEV-SNP, when the host can prove it.
+     *
+     * `cbitpos` is a property of the CPU, not a preference — it is read from the
+     * host at enrolment and carried here, because guessing it produces a guest
+     * that boots without memory encryption while claiming to have it.
+     */
+    confidential?: {
+        cbitpos: number;
+        reducedPhysBits: number;
+        policy: string;
+    };
+    consoleLog?: string;
+}
+export declare class ComputeError extends Error {
+    readonly code: 'BAD_NAME' | 'BAD_SPEC';
+    constructor(code: 'BAD_NAME' | 'BAD_SPEC', message: string);
+}
+export declare const unitName: (name: string) => string;
+/** The qemu command, as an argv array. Never a shell string. */
+export declare function qemuArgv(spec: GuestSpec): string[];
+/**
+ * The unit file.
+ *
+ * `Restart=always` is the point of using systemd at all: a guest that dies at
+ * 3am comes back without anybody being paged, and a host reboot brings every
+ * tenant's compute up in the same state it was in.
+ */
+export declare function guestUnit(spec: GuestSpec): string;
+export interface RunningGuest {
+    name: string;
+    pid: number;
+    disks: string[];
+}
+/**
+ * What is ACTUALLY running, read from process arguments.
+ *
+ * Not from libvirt, and not from the inventory. SEV-SNP guests are launched
+ * with raw qemu because libvirt on most hosts cannot express `sev-snp-guest`,
+ * so `virsh list` reports an empty machine while three confidential guests are
+ * running — and an operator who trusts it will overwrite their disks. That is
+ * not hypothetical; it is how this function came to exist.
+ */
+export declare function parseCensus(psOutput: string): RunningGuest[];
+/** Whether a device is in use by any running guest. */
+export declare const deviceInUse: (census: RunningGuest[], device: string) => boolean;
+/**
+ * Rate-limit a guest's egress on its tap device.
+ *
+ * Without this every guest can saturate the host's whole uplink — 25 Gb/s on
+ * our metal — so one tenant's runaway job starves the other guests and the
+ * hypervisor with them. It is also what makes bandwidth SELLABLE: a compute
+ * plan cannot state a number the machine does not enforce.
+ *
+ * Shaped on EGRESS only. Ingress arrives whether we want it or not; policing it
+ * at the tap drops packets that already crossed the expensive link, which costs
+ * the same and adds retransmits. Ingress belongs upstream, at the edge.
+ *
+ * The tap receives packets emitted by the guest, so the limiter belongs on the
+ * tap's INGRESS hook. A root qdisc there shapes traffic going into the guest and
+ * looks correct in `tc` while enforcing the opposite direction.
+ *
+ * The guaranteed rate is a placement promise: the host reserves enough uplink
+ * for every admitted guest. The per-tap policer enforces the burst ceiling.
+ */
+export declare function shapeEgressCommands(tap: string, mbps: number, burstMbps?: number): string[];
+/**
+ * The same contract as `shapeEgressCommands`, expressed without a shell for a
+ * systemd guest unit. Every argument is generated from validated numbers and a
+ * validated device name; no tenant-controlled command text is evaluated.
+ */
+export declare function shapeEgressUnitDirectives(tap: string, guaranteedMbps: number, burstMbps: number): string[];
+/** The tap a guest's NIC is attached to, from the census. */
+export declare const tapFor: (guestIndex: number) => string;

package/dist/compute.js

@@ -0,0 +1,150 @@
+// src/compute.ts
+class ComputeError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ComputeError";
+  }
+}
+var NAME = /^[a-z][a-z0-9-]{1,30}[a-z0-9]$/;
+var unitName = (name) => {
+  if (!NAME.test(name)) {
+    throw new ComputeError("BAD_NAME", `"${name}" is not a usable guest name — lower case, digits and hyphens, 3-32 characters.`);
+  }
+  return `forgezero-guest@${name}.service`;
+};
+function qemuArgv(spec) {
+  if (spec.vcpu < 1 || spec.memoryGib < 1) {
+    throw new ComputeError("BAD_SPEC", "a guest needs at least 1 vCPU and 1 GiB");
+  }
+  const argv = [
+    "/usr/bin/qemu-system-x86_64",
+    "-name",
+    spec.name,
+    "-accel",
+    "kvm",
+    "-cpu",
+    "host",
+    "-m",
+    `${spec.memoryGib}G`,
+    "-smp",
+    String(spec.vcpu)
+  ];
+  if (spec.confidential) {
+    const { cbitpos, reducedPhysBits, policy } = spec.confidential;
+    argv.push("-machine", `q35,confidential-guest-support=snp,memory-backend=ram`, "-object", `memory-backend-memfd,id=ram,size=${spec.memoryGib}G,share=true`, "-object", `sev-snp-guest,id=snp,cbitpos=${cbitpos},reduced-phys-bits=${reducedPhysBits},policy=${policy}`, "-bios", "/usr/share/ovmf/OVMF.fd");
+  } else {
+    argv.push("-machine", "q35");
+  }
+  argv.push("-drive", `file=${spec.disk},format=raw,if=none,id=disk0,cache=none,aio=native`, "-device", "virtio-blk-pci,drive=disk0,iommu_platform=on", "-drive", `file=${spec.seed},format=raw,if=none,id=seed0,readonly=on`, "-device", "virtio-blk-pci,drive=seed0,iommu_platform=on", "-netdev", spec.tap ? `tap,id=net0,ifname=${spec.tap},script=no,downscript=no` : `bridge,id=net0,br=${spec.bridge}`, "-device", `virtio-net-pci,netdev=net0,mac=${spec.mac},iommu_platform=on`, "-display", "none");
+  if (spec.consoleLog)
+    argv.push("-serial", `file:${spec.consoleLog}`);
+  return argv;
+}
+function guestUnit(spec) {
+  const argv = qemuArgv(spec).map((part) => /[\s"']/.test(part) ? JSON.stringify(part) : part).join(" ");
+  if (spec.egress && !spec.tap) {
+    throw new ComputeError("BAD_SPEC", "shaped egress needs a stable tap device");
+  }
+  const tapSetup = spec.tap ? [
+    `ExecStartPre=-/usr/sbin/ip link del ${spec.tap}`,
+    `ExecStartPre=/usr/sbin/ip tuntap add dev ${spec.tap} mode tap`,
+    `ExecStartPre=/usr/sbin/ip link set ${spec.tap} master ${spec.bridge}`,
+    `ExecStartPre=/usr/sbin/ip link set ${spec.tap} up`,
+    ...spec.egress ? shapeEgressUnitDirectives(spec.tap, spec.egress.guaranteedMbps, spec.egress.burstMbps) : [],
+    `ExecStopPost=-/usr/sbin/ip link del ${spec.tap}`
+  ].join(`
+`) : "";
+  return `[Unit]
+Description=ForgeZero guest ${spec.name}
+Documentation=https://www.forgezero.net
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+Slice=forgezero-guests.slice
+${tapSetup}
+ExecStart=${argv}
+Restart=always
+RestartSec=5
+${spec.allowedCpus ? `AllowedCPUs=${spec.allowedCpus}
+` : ""}${spec.allowedMemoryNodes ? `AllowedMemoryNodes=${spec.allowedMemoryNodes}
+` : ""}# The affinity belongs to the unit rather than only QEMU's vCPU threads. Its
+# emulator and IO threads can otherwise run on a different tenant's cores.
+# The agent is NOT the parent. Restarting or upgrading fz-agent must never stop
+# a tenant's compute, which is the whole reason this is a unit rather than a
+# child process.
+KillMode=mixed
+TimeoutStopSec=120
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function parseCensus(psOutput) {
+  const guests = [];
+  for (const line of psOutput.split(`
+`)) {
+    const trimmed = line.trim();
+    if (!trimmed || !trimmed.includes("qemu-system"))
+      continue;
+    const pid = Number(trimmed.split(/\s+/)[0]);
+    const name = /-name\s+([^\s]+)/.exec(trimmed)?.[1];
+    if (!Number.isFinite(pid) || !name)
+      continue;
+    const disks = [...trimmed.matchAll(/file=([^,\s]+)/g)].map((match) => match[1]);
+    guests.push({ name, pid, disks });
+  }
+  return guests;
+}
+var deviceInUse = (census, device) => census.some((guest) => guest.disks.includes(device));
+function shapeEgressCommands(tap, mbps, burstMbps = mbps * 2) {
+  if (!/^[a-z][a-z0-9]{0,14}$/.test(tap)) {
+    throw new ComputeError("BAD_SPEC", `"${tap}" is not a device name`);
+  }
+  if (mbps <= 0)
+    return [
+      `tc qdisc del dev ${tap} root 2>/dev/null || true`,
+      `tc qdisc del dev ${tap} ingress 2>/dev/null || true`
+    ];
+  const ceiling = `${Math.floor(Math.max(burstMbps, mbps))}mbit`;
+  return [
+    `tc qdisc del dev ${tap} root 2>/dev/null || true`,
+    `tc qdisc del dev ${tap} ingress 2>/dev/null || true`,
+    `tc qdisc add dev ${tap} handle ffff: ingress`,
+    `tc filter add dev ${tap} parent ffff: protocol all u32 match u32 0 0 action police rate ${ceiling} burst 16mb conform-exceed drop`
+  ];
+}
+function shapeEgressUnitDirectives(tap, guaranteedMbps, burstMbps) {
+  if (!/^[a-z][a-z0-9]{0,14}$/.test(tap)) {
+    throw new ComputeError("BAD_SPEC", `"${tap}" is not a device name`);
+  }
+  if (!Number.isInteger(guaranteedMbps) || guaranteedMbps < 0 || !Number.isInteger(burstMbps) || burstMbps < guaranteedMbps) {
+    throw new ComputeError("BAD_SPEC", "egress rates must be whole numbers and burst must cover the guarantee");
+  }
+  const clear = [
+    `ExecStartPre=-/usr/sbin/tc qdisc del dev ${tap} root`,
+    `ExecStartPre=-/usr/sbin/tc qdisc del dev ${tap} ingress`
+  ];
+  if (guaranteedMbps === 0)
+    return clear;
+  return [
+    ...clear,
+    `ExecStartPre=/usr/sbin/tc qdisc add dev ${tap} handle ffff: ingress`,
+    `ExecStartPre=/usr/sbin/tc filter add dev ${tap} parent ffff: protocol all u32 match u32 0 0 action police rate ${burstMbps}mbit burst 16mb conform-exceed drop`
+  ];
+}
+var tapFor = (guestIndex) => `tap${guestIndex}`;
+export {
+  unitName,
+  tapFor,
+  shapeEgressUnitDirectives,
+  shapeEgressCommands,
+  qemuArgv,
+  parseCensus,
+  guestUnit,
+  deviceInUse,
+  ComputeError
+};

package/dist/compute.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/control.d.ts

@@ -0,0 +1,57 @@
+import { type Server } from 'node:net';
+import type { DeploymentManager, DeploymentRequest, DeploymentResult } from './deployment';
+export declare const DEFAULT_CONTROL_SOCKET = "/run/forgezero/control.sock";
+export type ControlRequest = {
+    op: 'deploy';
+    request?: DeploymentRequest;
+} | {
+    op: 'status';
+} | {
+    op: 'pause';
+} | {
+    op: 'resume';
+} | {
+    op: 'pause-key';
+    key: string;
+} | {
+    op: 'resume-key';
+    key: string;
+} | {
+    op: 'stop-key';
+    key: string;
+} | {
+    op: 'start-key';
+    key: string;
+} | {
+    op: 'cancel';
+    id: string;
+};
+export type ControlResponse = {
+    ok: true;
+    op: 'deploy';
+    taskId: string;
+    result: DeploymentResult;
+} | {
+    ok: true;
+    op: 'status';
+    queue: ReturnType<DeploymentManager['snapshot']>;
+} | {
+    ok: true;
+    op: Exclude<ControlRequest['op'], 'deploy' | 'status' | 'stop-key'>;
+    changed: boolean;
+} | {
+    ok: true;
+    op: 'stop-key';
+    changed: boolean;
+    removed: number;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export declare function handleControl(manager: DeploymentManager, request: ControlRequest): Promise<ControlResponse>;
+/** Root/operator control is deliberately separate from the tenant vault socket. */
+export declare function startControlServer(manager: DeploymentManager, socketPath?: string): Server;
+export declare function requestControl(request: ControlRequest, socketPath?: string): Promise<ControlResponse>;

package/dist/control.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/definition.d.ts

@@ -0,0 +1,34 @@
+import type { Pipeline, PipelineStep } from './pipeline';
+export declare const PIPELINE_VERSION: 1;
+export interface SoftwareRequirement {
+    name: string;
+    check: string;
+    install: string;
+}
+export interface PipelineRole {
+    name: string;
+    count: number;
+    software: readonly SoftwareRequirement[];
+}
+export interface DeployStep extends PipelineStep {
+    phase: 'build' | 'release' | 'migrate' | 'health';
+    /** The coordinator runs this on one selected node, never on every replica. */
+    once?: boolean;
+    /** Run only when every named non-secret deployment coordinate has this value. */
+    when?: Readonly<Record<string, string>>;
+}
+export interface DeployDefinition {
+    version: typeof PIPELINE_VERSION;
+    name: string;
+    requireAttestation?: boolean;
+    roles: readonly PipelineRole[];
+    steps: readonly DeployStep[];
+}
+export declare class DefinitionError extends Error {
+    constructor(message: string);
+}
+/** Validate parsed YAML before any command from it is allowed to run. */
+export declare function parseDeployDefinition(value: unknown): DeployDefinition;
+export declare function phasePipeline(definition: DeployDefinition, phase: DeployStep['phase']): Pipeline;
+/** Turn one role's declared software checks into the same executable pipeline shape. */
+export declare function prerequisitePipeline(definition: DeployDefinition, roleName: string): Pipeline;

package/dist/definition.js

@@ -0,0 +1,159 @@
+// src/definition.ts
+var PIPELINE_VERSION = 1;
+
+class DefinitionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DefinitionError";
+  }
+}
+var record = (value, where) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new DefinitionError(`${where} must be an object.`);
+  }
+  return value;
+};
+var text = (value, where) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new DefinitionError(`${where} must be a non-empty string.`);
+  }
+  return value;
+};
+var exactKeys = (value, allowed, where) => {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0)
+    throw new DefinitionError(`${where} contains unknown field(s): ${unknown.join(", ")}.`);
+};
+var RESERVED_STEP_ENV = new Set([
+  "PATH",
+  "HOME",
+  "SHELL",
+  "PWD",
+  "BUN_INSTALL",
+  "NODE_OPTIONS",
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "GIT_SSH",
+  "GIT_SSH_COMMAND"
+]);
+function parseDeployDefinition(value) {
+  const root = record(value, "pipeline");
+  exactKeys(root, ["version", "name", "requireAttestation", "roles", "steps"], "pipeline");
+  if (root.version !== PIPELINE_VERSION) {
+    throw new DefinitionError(`pipeline.version must be ${PIPELINE_VERSION}.`);
+  }
+  if (!Array.isArray(root.roles) || root.roles.length === 0) {
+    throw new DefinitionError("pipeline.roles must contain at least one role.");
+  }
+  if (!Array.isArray(root.steps) || root.steps.length === 0) {
+    throw new DefinitionError("pipeline.steps must contain at least one step.");
+  }
+  const roles = root.roles.map((raw, index) => {
+    const role = record(raw, `roles[${index}]`);
+    exactKeys(role, ["name", "count", "software"], `roles[${index}]`);
+    const count = Number(role.count);
+    if (!Number.isSafeInteger(count) || count < 1) {
+      throw new DefinitionError(`roles[${index}].count must be a positive integer.`);
+    }
+    if (!Array.isArray(role.software)) {
+      throw new DefinitionError(`roles[${index}].software must be an array.`);
+    }
+    return {
+      name: text(role.name, `roles[${index}].name`),
+      count,
+      software: role.software.map((rawSoftware, softwareIndex) => {
+        const software = record(rawSoftware, `roles[${index}].software[${softwareIndex}]`);
+        exactKeys(software, ["name", "check", "install"], `roles[${index}].software[${softwareIndex}]`);
+        return {
+          name: text(software.name, `roles[${index}].software[${softwareIndex}].name`),
+          check: text(software.check, `roles[${index}].software[${softwareIndex}].check`),
+          install: text(software.install, `roles[${index}].software[${softwareIndex}].install`)
+        };
+      })
+    };
+  });
+  if (new Set(roles.map((role) => role.name)).size !== roles.length) {
+    throw new DefinitionError("pipeline.roles must have unique names.");
+  }
+  const phases = new Set(["build", "release", "migrate", "health"]);
+  const steps = root.steps.map((raw, index) => {
+    const step = record(raw, `steps[${index}]`);
+    exactKeys(step, ["name", "run", "phase", "secrets", "once", "always", "timeoutMs", "when"], `steps[${index}]`);
+    const phase = text(step.phase, `steps[${index}].phase`);
+    if (!phases.has(phase))
+      throw new DefinitionError(`steps[${index}].phase is not supported.`);
+    if (step.secrets !== undefined && (!Array.isArray(step.secrets) || step.secrets.some((name) => typeof name !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(name)))) {
+      throw new DefinitionError(`steps[${index}].secrets must contain names only.`);
+    }
+    if (Array.isArray(step.secrets) && new Set(step.secrets).size !== step.secrets.length) {
+      throw new DefinitionError(`steps[${index}].secrets must not contain duplicates.`);
+    }
+    if (Array.isArray(step.secrets) && step.secrets.some((name) => RESERVED_STEP_ENV.has(String(name)))) {
+      throw new DefinitionError(`steps[${index}].secrets may not replace process-control environment variables.`);
+    }
+    const timeoutMs = step.timeoutMs === undefined ? undefined : Number(step.timeoutMs);
+    if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 86400000)) {
+      throw new DefinitionError(`steps[${index}].timeoutMs must be an integer from 1 to 86400000.`);
+    }
+    let when;
+    if (step.when !== undefined) {
+      const conditions = record(step.when, `steps[${index}].when`);
+      when = {};
+      for (const [name, expected] of Object.entries(conditions)) {
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(name) || typeof expected !== "string" || expected.length === 0) {
+          throw new DefinitionError(`steps[${index}].when must map environment names to non-empty strings.`);
+        }
+        when[name] = expected;
+      }
+      if (Object.keys(when).length === 0)
+        throw new DefinitionError(`steps[${index}].when must not be empty.`);
+    }
+    return {
+      name: text(step.name, `steps[${index}].name`),
+      run: text(step.run, `steps[${index}].run`),
+      phase,
+      secrets: step.secrets,
+      once: step.once === true,
+      always: step.always === true,
+      timeoutMs,
+      when
+    };
+  });
+  if (new Set(steps.map((step) => step.name)).size !== steps.length) {
+    throw new DefinitionError("pipeline.steps must have unique names.");
+  }
+  return {
+    version: PIPELINE_VERSION,
+    name: text(root.name, "pipeline.name"),
+    requireAttestation: root.requireAttestation === true,
+    roles,
+    steps
+  };
+}
+function phasePipeline(definition, phase) {
+  return {
+    name: `${definition.name}:${phase}`,
+    requireAttestation: definition.requireAttestation,
+    steps: definition.steps.filter((step) => step.phase === phase)
+  };
+}
+function prerequisitePipeline(definition, roleName) {
+  const role = definition.roles.find((candidate) => candidate.name === roleName);
+  if (!role)
+    throw new DefinitionError(`pipeline role does not exist: ${roleName}.`);
+  return {
+    name: `${definition.name}:prerequisites:${role.name}`,
+    requireAttestation: definition.requireAttestation,
+    steps: role.software.map((software) => ({
+      name: `prepare ${software.name}`,
+      run: `${software.check} >/dev/null 2>&1 || { ${software.install}; ${software.check}; }`
+    }))
+  };
+}
+export {
+  prerequisitePipeline,
+  phasePipeline,
+  parseDeployDefinition,
+  PIPELINE_VERSION,
+  DefinitionError
+};

package/dist/definition.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deployment-pull.d.ts

@@ -0,0 +1,60 @@
+import type { NodeKeyPair } from '@forgezero/runtime/identity';
+import type { DeploymentManager, DeploymentResult } from './deployment';
+export interface RemoteDeploymentClaim {
+    runKey: string;
+    pipelineKey: string;
+    revision: string;
+    claimToken: string;
+    claimExpiresAtTs: number;
+    attempt: number;
+    source: {
+        repository: string;
+        branch: string;
+        role: string;
+        knownHosts?: string;
+    };
+}
+export interface DeploymentPullOptions {
+    apiUrl: string;
+    nodeKey: string;
+    keys: NodeKeyPair;
+    manager?: DeploymentManager;
+    /** Automatic computes construct one manager from the server-owned source coordinates. */
+    managerFor?: (claim: RemoteDeploymentClaim) => DeploymentManager;
+    fetch?: (input: URL, init: RequestInit) => Promise<Response>;
+    intervalMs?: number;
+    /** Concurrent claim workers. Same-key execution still serializes in the manager queue. */
+    parallelism?: number;
+    requestTimeoutMs?: number;
+    completionAttempts?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    renewRetryMs?: number;
+    setTimer?: (callback: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    onEvent?: (event: string, detail?: unknown) => void;
+}
+export type PullResult = {
+    status: 'idle';
+} | {
+    status: 'deployed';
+    claim: RemoteDeploymentClaim;
+    result: DeploymentResult;
+} | {
+    status: 'failed';
+    claim: RemoteDeploymentClaim;
+    reason: string;
+};
+/** Claim at most one job and await its exact deployment result before reporting. */
+export declare function pullDeploymentOnce(options: DeploymentPullOptions): Promise<PullResult>;
+/**
+ * Bounded outbound intake for the deployment manager.
+ *
+ * Claim workers may receive different pipeline keys concurrently. Managers
+ * still own execution ordering: a single pipeline key is serial even when two
+ * of its claims were fetched by different workers.
+ */
+export declare function startDeploymentPull(options: DeploymentPullOptions): {
+    stop(): Promise<void>;
+    readonly active: boolean;
+};

package/dist/deployment-pull.test.d.ts

@@ -0,0 +1 @@
+export {};