<!-- Generated by scripts/gen-docs.ts from the TSDoc in src/. Do not edit by hand. -->

# `flow/check-run`

Source: [`src/flow/check-run.ts`](https://github.com/AI-for-dev/combo/blob/main/src/flow/check-run.ts)

The run stage of validation: a checked flow held to the project it is about
to run in, still before the first spawn.

What the flow stage cannot know is here: the working tree, the ports the
launch hands over, and whether somebody is there. A flow valid on its own may
be refused on one project, since a check script belongs to the project,
and a commit, a copy or a read of `diff` needs a repository. With nobody
there, a flow that could reach a question nobody can leave unanswered is
refused now rather than failed there, behind a `choice` too: whether a case
is taken is only known once the run has spent what came before it. Every
rule reads the flows called too, where the call stands: a callee acts in
its caller's tree, through the same ports.
What passes is a `CheckedRun`, which carries the tree and ports it was
checked against, so a flow checked for one project cannot run in another.

## `CheckedRun`

*type*

```typescript
export type CheckedRun = RunStage & {
	/** The flow, as the flow stage checked it. */
	readonly flow: CheckedFlow;
	/**
	 * Each check script's content by its path, read here: what runs is what was
	 * read before the first spawn, whatever an agent does to the file after.
	 */
	readonly scripts: ReadonlyMap<string, string>;
	readonly [checked]: true;
};
```

A checked flow that passed the run stage too. Only `checkRun` makes one, and it is what `runFlow` takes.

## `checkRun`

*function*

```typescript
export async function checkRun(flow: CheckedFlow, stage: RunStage, read?: ReadonlyMap<string, string>): Promise<CheckRun> { /* … */ }
```

`flow` held to `stage`. A missing port, a missing script and a tree that is
no repository are each reported once, at the first node needing it. Given
`read`, each script's content is taken from there instead of the disk: a
resume runs the scripts its run started with.

## `CheckRun`

*type*

```typescript
export type CheckRun = { readonly ok: true; readonly run: CheckedRun } | { readonly ok: false; readonly faults: readonly Fault[] };
```

A checked run, or every fault that refused it.

## `FlowPorts`

*type*

```typescript
export type FlowPorts = {
	/** Puts an `ask` node's question to the person. */
	readonly ask?: AskUser;
	/** Runs a `check` node's script. */
	readonly check?: CheckScript;
	/** Commits, reads `diff`, and makes and lands the copies of a `copies: true` block. */
	readonly git?: GitPort;
};
```

How a run reaches the world. A node whose port is absent refuses the run; without `ask`, nobody is there.

## `RunStage`

*type*

```typescript
export type RunStage = {
	/** The working tree, at the repository root: a check's path starts there. */
	readonly cwd: string;
	/** How the run reaches the world; a node whose port is absent refuses it. */
	readonly ports: FlowPorts;
	/** Whether a person can answer. With no `ask` port, nobody can, whatever this says. */
	readonly somebodyThere: boolean;
};
```

What a launch says about where it runs.