import {ResolvedInput} from './canonical.zena'; import {InputDelta} from './delta.zena'; import {Fingerprint} from './fingerprint.zena'; import {OutputManifest} from './manifest.zena'; /** The stable identity of a step across runs. */ export class StepKey(value: String) /** A step input: a named leaf value, a lazy leaf set, or a dependency on another step. */ export sealed class InputRef { case LeafInput, LeafSet, StepOutputs, StepOrder } /** * A named leaf input. The host resolves the name to a fingerprint at * run time; for a build system a leaf is a file, for other hosts it can * be anything fingerprintable. */ export final class LeafInput(name: String) extends InputRef /** * A named set of leaf inputs resolved lazily once this step's * dependencies have settled. For a build system, this expands and * hashes input globs after upstream steps have written generated files * into the workspace. Each `(name, fingerprint)` pair enters the cache * key in the `leaf:` namespace, just like `LeafInput`. */ export final class LeafSet( name: String, resolve: () => Future>, ) extends InputRef /** * A dependency on another step: an ordering edge in the graph. For a * task dependency this contributes the producing step's output * manifest to the cache key; for a service dependency it contributes * the service's identity fingerprint and requires the service to be * ready while the dependent runs. */ export final class StepOutputs(step: StepKey) extends InputRef /** * An ordering-only dependency on another step (such as wireit's * `"cascade": false`). Like `StepOutputs`, the engine waits for a task * dependency to succeed (or skips on failure) and starts and holds a * service dependency while this step executes, without adding the * upstream step's manifest or identity fingerprint to this step's * cache key. */ export final class StepOrder(step: StepKey) extends InputRef /** * What a task step's run callback receives. When the last recorded run * had the same config fingerprint, the engine supplies the input delta * against it; the callback may then regenerate only the stale outputs * and carry the rest of the previous manifest over unchanged (the * engine verifies the carry-over against the dependency records). */ export class RunContext { /** * Changed/added/removed inputs since the last recorded run, or null * when no usable history exists (first run, or the step's config * changed) — then the step must run from scratch. */ delta: InputDelta?; /** The last recorded run's manifest, when `delta` is non-null. */ previous: OutputManifest?; /** * Previous outputs invalidated by the delta, per their dependency * records. Null exactly when `delta` is null. */ staleOutputs: Array?; /** * This run's resolved inputs (`leaf:`, `step:`, `service:`), * allowing group or fileset steps to forward input fingerprints. */ inputs: Array; new( delta: InputDelta? = null, previous: OutputManifest? = null, staleOutputs: Array? = null, inputs: Array? = null, ) : delta = delta, previous = previous, staleOutputs = staleOutputs, inputs = inputs ?? new GrowableArray(); } /** What a service step's start callback receives. */ export class ServiceContext { } /** * A running service, as seen by the engine. The host's start callback * returns one; the engine calls `stop` when the service's last * dependent has settled (or when a pinned watch session ends). */ export interface ServiceHandle { isAlive(): boolean; stop(): Future; } /** * A node in the graph: a task that runs to completion, or a service * that stays up while dependents need it. */ export sealed class Step { case TaskStep, ServiceStep key: StepKey; /** * Covers everything that affects the step's behavior other than its * inputs: the command line, rule parameters, rule version. */ config: Fingerprint; inputs: Array; new(this.key, this.config, this.inputs); } /** * A unit of work: runs to completion and produces an output manifest. * The run callback is supplied by the host and performs all I/O; the * library only decides whether and when to invoke it. */ export final class TaskStep extends Step { run: (ctx: RunContext) => Future; new(key: StepKey, config: Fingerprint, inputs: Array, this.run) : super(key, config, inputs); } /** * A step that stays running instead of completing. `start` resolves * when the service is ready to serve dependents. The engine starts a * service only when a dependent actually executes (fresh and * cache-restored dependents never demand it) and stops it when its * last dependent settles. */ export final class ServiceStep extends Step { start: (ctx: ServiceContext) => Future; new(key: StepKey, config: Fingerprint, inputs: Array, this.start) : super(key, config, inputs); }