process-graph 1.1.0 → 1.2.0

package/dist/bin.js

@@ -83,7 +83,7 @@ if (missing.length > 0) {
 	process.stderr.write(missingPeersMessage(missing, declaredPeers(), process.env.npm_config_user_agent));
 	process.exitCode = exitCodes.missingPeers;
 } else {
-	const { packageVersion, runProcess } = await import("./dist-IjrgWhHQ.js");
+	const { packageVersion, runProcess } = await import("./dist-Cw63tKU9.js");
 	process.exitCode = await runProcess({
 		name: "process-graph",
 		version: packageVersion(manifest)

package/dist/cli.d.ts

@@ -1,9 +1,10 @@
-import { F as Status, _ as StatusRule, k as Facts, m as IncomingBasis, p as ArtefactBasis } from "./index-CCfe0csl.js";
+import { A as Facts, B as Status, _ as StatusRule, k as FactRecord, m as IncomingBasis, p as ArtefactBasis } from "./index-BH1aFqkJ.js";
 import { E as Participant, F as OverlayStatus, G as IdSpace, K as OpenIds, S as EventDef, a as Overlay, b as ArtefactDef, g as Model, k as Transition, x as Element } from "./index-CmZOswkx.js";
 import { C as Gap, n as GraphqlFetch, t as GitHubTokenPort, v as GraphSourceClient } from "./graphql-C1j5wQFz.js";
-import { Q as GraphStoreClient } from "./index-DhbvDgK4.js";
+import { ut as GraphStoreClient } from "./index-DxWOY8f9.js";
 import "./index-CptUHq6F.js";
 import { A as Flowchart, E as Swimlane, M as Handoff, g as SequenceDiagram, x as StateMachine } from "./index-CoA6vXqe.js";
+import { ComputedValue } from "trilean";
 //#region ../graph-cli/dist/exit-codes.d.ts
 /**
  * The exit status of every command, by meaning. A script tells the outcomes apart without reading the output: a model with problems is not a failure to run, and neither is an element that does not exist.
@@ -61,7 +62,7 @@ interface CliPorts {
    * @param signal - Aborts the read.
    */
   readonly readFile: (path: string, signal: AbortSignal | undefined) => Promise<string>;
-  /** The facts that decision conditions read, and which input artefacts are provided. */
+  /** Facts the host supplies for decision conditions and input artefacts. The model's stored fact record (what `set artefact` and `set fact` recorded) answers first; these answer whatever it does not. */
   readonly facts: Facts;
   /** Aborts every store and source call a command makes. */
   readonly signal: AbortSignal | undefined;
@@ -123,7 +124,7 @@ interface NodePortsOptions {
   readonly fetch?: GraphqlFetch;
   /** The clock, in milliseconds since the epoch, for a rate limit's retry time; `Date.now` when absent. */
   readonly now?: () => number;
-  /** The facts decision conditions read and which input artefacts are provided; nothing is known when absent. */
+  /** Facts the host supplies for decision conditions and input artefacts, answering whatever the model's stored fact record does not; nothing more is known when absent. */
   readonly facts?: Facts;
   /** Aborts every store and source call. */
   readonly signal?: AbortSignal;
@@ -162,20 +163,29 @@ export declare const nodePorts: (options?: NodePortsOptions) => CliPorts;
 export declare const runProcess: (identity: ProgramIdentity) => Promise<ExitCode>;
 //#endregion
 //#region ../graph-cli/dist/session.d.ts
-/** What every operation works against: one model in one store, the facts its conditions read, and the signal that aborts its calls. */
+/** What every operation works against: one model in one store, the facts a host supplies for its conditions, and the signal that aborts its calls. */
 interface GraphSession {
   readonly store: GraphStoreClient;
   /** The name the model is filed under in the store. */
   readonly modelId: string;
+  /** Facts the host supplies, consulted for whatever the model's stored fact record does not answer (see `runFacts`). */
   readonly facts: Facts;
   readonly signal: AbortSignal | undefined;
 }
-/** A stored model and its run state, as an operation reads them. */
+/** A stored model, its run state and its fact record, as an operation reads them. */
 interface StoredRun {
   readonly revision: number;
   readonly model: Model<OpenIds>;
   readonly overlay: Overlay<OpenIds>;
+  readonly facts: FactRecord;
 }
+/**
+ * The facts a run's reasoning reads: the model's stored fact record first, then the session's own facts for every key the record does not answer. What `set artefact` and `set fact` record therefore overrides a host's facts only where it says something.
+ * @param session - The session, whose facts the host supplied.
+ * @param run - The stored run.
+ * @returns The `Facts` port for graph-domain.
+ */
+export declare const runFacts: (session: GraphSession, run: StoredRun) => Facts;
 /** An element as commands report it: its identifier and its human label. */
 interface ElementSummary {
   readonly id: string;
@@ -394,6 +404,50 @@ interface SetResult extends Written {
  * @throws CliError with `notFound` when the model or the element does not exist.
  */
 export declare const setState: (session: GraphSession, id: string, state: OverlayStatus) => Promise<SetResult>;
+/** What can be recorded about an artefact: `provided`, known not provided (`absent`), or `unknown`, which forgets whatever was recorded. */
+export declare const artefactStates: readonly ["provided", "absent", "unknown"];
+/** One of `artefactStates`. */
+type ArtefactState = (typeof artefactStates)[number];
+/** The state an artefact was given. */
+interface SetArtefactResult extends Written {
+  readonly artefact: string;
+  readonly state: ArtefactState;
+}
+/**
+ * Records whether an artefact of the session's model is provided, so a consumer of an input no activity produces can become ready, or forgets it with `unknown`.
+ * @param session - The store and model.
+ * @param id - The artefact.
+ * @param state - `provided`, `absent` or `unknown`.
+ * @returns The artefact, its new state and the revision the change took.
+ * @throws CliError with `notFound` when the model or the artefact does not exist.
+ */
+export declare const setArtefact: (session: GraphSession, id: string, state: ArtefactState) => Promise<SetArtefactResult>;
+/** The value a named fact was given, or `unknown` when it was forgotten. */
+interface SetFactResult extends Written {
+  readonly fact: string;
+  readonly value: ComputedValue | "unknown";
+}
+/**
+ * Records a named fact's value for the session's model, so every condition reading that name evaluates against it, or forgets it with `unknown`, so those conditions are indeterminate again.
+ * @param session - The store and model.
+ * @param name - The fact's name, the key a condition's `reference` node gives.
+ * @param value - Its trilean value, or `unknown`.
+ * @returns The fact, its new value and the revision the change took.
+ * @throws CliError with `notFound` when the model does not exist.
+ */
+export declare const setFact: (session: GraphSession, name: string, value: ComputedValue | "unknown") => Promise<SetFactResult>;
+/** The session's model's fact record. */
+interface FactsResult {
+  readonly revision: number;
+  readonly facts: FactRecord;
+}
+/**
+ * Reads what is recorded about the session's model's run: which artefacts are provided or absent, and each named fact's value.
+ * @param session - The store and model.
+ * @returns The fact record and the model's revision.
+ * @throws CliError with `notFound` when the model does not exist.
+ */
+export declare const factsOf: (session: GraphSession) => Promise<FactsResult>;
 //#endregion
 //#region ../graph-cli/dist/validate.d.ts
 /** One problem with a model. */
@@ -509,4 +563,4 @@ export declare const stateMachineToDot: <I extends IdSpace>(view: StateMachine<I
  */
 export declare const sequenceToDot: <I extends IdSpace>(view: SequenceDiagram<I>, participantLabel: (participant: I["actor"]) => string) => string;
 //#endregion
-export type { Addition, BlockedResult, CliPorts, CyclesResult, ElementStatus, ElementSummary, ExitCode, Failure, FormatName, GraphSession, HandoffsResult, ImpactResult, NodePortsOptions, OpenedStore, PathResult, ProgramIdentity, ProjectedView, ReadyResult, SetResult, ShowRequest, ShowResult, SourceLookup, StoredRun, SyncRequest, SyncResult, ValidateResult, ValidationIssue, ViewName, WhyLink, WhyResult, Written };
+export type { Addition, ArtefactState, BlockedResult, CliPorts, CyclesResult, ElementStatus, ElementSummary, ExitCode, FactsResult, Failure, FormatName, GraphSession, HandoffsResult, ImpactResult, NodePortsOptions, OpenedStore, PathResult, ProgramIdentity, ProjectedView, ReadyResult, SetArtefactResult, SetFactResult, SetResult, ShowRequest, ShowResult, SourceLookup, StoredRun, SyncRequest, SyncResult, ValidateResult, ValidationIssue, ViewName, WhyLink, WhyResult, Written };

package/dist/cli.js

@@ -1,3 +1,3 @@
 import { t as exitCodes } from "./exit-codes-0ultCqdS.js";
-import { A as add, C as blocked, D as path, E as impactOf, F as failureOf, M as findRun, N as loadRun, O as ready, P as CliError, S as swimlaneToMermaid, T as handoffsOf, _ as stateMachineToDot, a as defaultModelId, b as sequenceToMermaid, c as validateStored, d as formatNames, f as project, g as sequenceToDot, h as flowchartToDot, i as runProcess, j as setState, k as why, l as sync, m as viewNames, n as nodePorts, o as runCli, p as show, r as packageVersion, s as validateDocument, t as defaultDataPath, u as emit, v as swimlaneToDot, w as cycles, x as stateMachineToMermaid, y as flowchartToMermaid } from "./dist-HLlW8vgT.js";
-export { CliError, add, blocked, cycles, defaultDataPath, defaultModelId, emit, exitCodes, failureOf, findRun, flowchartToDot, flowchartToMermaid, formatNames, handoffsOf, impactOf, loadRun, nodePorts, packageVersion, path, project, ready, runCli, runProcess, sequenceToDot, sequenceToMermaid, setState, show, stateMachineToDot, stateMachineToMermaid, swimlaneToDot, swimlaneToMermaid, sync, validateDocument, validateStored, viewNames, why };
+import { A as add, B as failureOf, C as blocked, D as path, E as impactOf, F as setState, I as findRun, L as loadRun, M as factsOf, N as setArtefact, O as ready, P as setFact, R as runFacts, S as swimlaneToMermaid, T as handoffsOf, _ as stateMachineToDot, a as defaultModelId, b as sequenceToMermaid, c as validateStored, d as formatNames, f as project, g as sequenceToDot, h as flowchartToDot, i as runProcess, j as artefactStates, k as why, l as sync, m as viewNames, n as nodePorts, o as runCli, p as show, r as packageVersion, s as validateDocument, t as defaultDataPath, u as emit, v as swimlaneToDot, w as cycles, x as stateMachineToMermaid, y as flowchartToMermaid, z as CliError } from "./dist-BxHnxpcT.js";
+export { CliError, add, artefactStates, blocked, cycles, defaultDataPath, defaultModelId, emit, exitCodes, factsOf, failureOf, findRun, flowchartToDot, flowchartToMermaid, formatNames, handoffsOf, impactOf, loadRun, nodePorts, packageVersion, path, project, ready, runCli, runFacts, runProcess, sequenceToDot, sequenceToMermaid, setArtefact, setFact, setState, show, stateMachineToDot, stateMachineToMermaid, swimlaneToDot, swimlaneToMermaid, sync, validateDocument, validateStored, viewNames, why };

package/dist/{control-aDk9560d.js → control-DiygoEhm.js}

@@ -1,3 +1,4 @@
+import { createSyncEvaluator } from "trilean";
 //#region ../../core/graph/dag/dist/errors.js
 /**
 * Thrown when an operation that is only defined on an acyclic graph is given one that contains a cycle.
@@ -233,6 +234,167 @@ function assertAcyclic(dag) {
 	if (cycles.length > 0) throw new CycleError(cycles);
 }
 //#endregion
+//#region ../../core/graph/domain/dist/facts.js
+/** The only field of a reserved key. Keys that carry it are resolved from the overlay, so a `Facts` implementation must not use it. */
+const elementField = "$element";
+/**
+* Builds the reserved key that reads another element's run state inside a condition. It resolves to the text `"done"` or `"open"`, and is not found (so the condition is indeterminate) when the overlay says `"unknown"` or the id is not an element of the model.
+*
+* The value is the overlay's own state, not the derived status: a condition therefore never depends on the derivation that evaluates it, and cannot form a cycle.
+* @param id - The element whose state is read.
+* @returns A key to put in a trilean `reference` node.
+*/
+const elementStatusKey = (id) => ({ [elementField]: id });
+/** The only field of the key the package puts to the port to ask whether an input artefact is provided. */
+const artefactField = "$artefact";
+/**
+* Builds the key the package asks the facts port when it needs to know whether an artefact has been provided from outside the process. An artefact is provided exactly when the port answers `{ found: true }` with the boolean `true`; a not-found or `false` answer means it is not.
+*
+* A provided artefact satisfies every consumer, whether or not an activity also produces it.
+* @param id - The artefact.
+* @returns The key the port is asked.
+*/
+const artefactKey = (id) => ({ [artefactField]: id });
+/**
+* Whether the facts port reports an artefact as provided.
+* @param facts - The injected source of facts.
+* @param id - The artefact.
+*/
+const isProvided = (facts, id) => {
+	const answer = facts(artefactKey(id));
+	return answer.found && answer.value.kind === "boolean" && answer.value.value;
+};
+/** A record that knows nothing: no artefact is provided and every named fact is unknown. */
+const emptyFactRecord = {
+	artefacts: {},
+	values: {}
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The artefact id an `artefactKey` key names, or `undefined` for any other key. */
+const artefactOf = (key) => {
+	if (!isRecord(key) || Object.keys(key).length !== 1) return;
+	const id = key[artefactField];
+	return typeof id === "string" ? id : void 0;
+};
+/**
+* Adapts a fact record to the `Facts` port. A string key is a named fact, answered with its value when the record holds it; a key built by `artefactKey` is answered with the boolean the record holds for that artefact; every other key, and any name or artefact the record does not hold, is not found.
+* @param record - What is known.
+* @returns A `Facts` port reading the record.
+*/
+const factsFrom = (record) => {
+	const values = new Map(Object.entries(record.values));
+	const artefacts = new Map(Object.entries(record.artefacts));
+	return (key) => {
+		if (typeof key === "string") {
+			const value = values.get(key);
+			return value === void 0 ? { found: false } : {
+				found: true,
+				value
+			};
+		}
+		const id = artefactOf(key);
+		const provided = id === void 0 ? void 0 : artefacts.get(id);
+		return provided === void 0 ? { found: false } : {
+			found: true,
+			value: {
+				kind: "boolean",
+				value: provided
+			}
+		};
+	};
+};
+/**
+* The named facts a condition reads: the string key of every `reference` node in it, each once, in the order first met walking the tree depth first. Reserved keys and other non-string keys are not names, so they are left out, and a reference's own key is never searched for further references.
+* @param condition - A trilean predicate or expression, such as a transition's `condition`.
+* @returns The names, each once.
+*/
+const factNamesIn = (condition) => {
+	const names = /* @__PURE__ */ new Set();
+	const pending = [condition];
+	for (let node = pending.pop(); node !== void 0; node = pending.pop()) if (Array.isArray(node)) {
+		const items = node;
+		pending.push(...[...items].reverse());
+	} else if (typeof node === "object" && node !== null) {
+		if ("kind" in node && node.kind === "reference" && "key" in node) {
+			if (typeof node.key === "string") names.add(node.key);
+		} else {
+			const fields = Object.values(node);
+			pending.push(...[...fields].reverse());
+		}
+	}
+	return [...names];
+};
+/**
+* Layers facts ports: each key is answered by the first port that finds it, so an earlier port overrides a later one only where it knows the answer.
+* @param ports - The ports, most authoritative first.
+* @returns A `Facts` port that is not found only when no port finds the key.
+*/
+const layeredFacts = (...ports) => (key) => {
+	for (const port of ports) {
+		const answer = port(key);
+		if (answer.found) return answer;
+	}
+	return { found: false };
+};
+/**
+* Thrown when a condition uses a node whose evaluation needs a table or a collection from the facts port, which answers single keys only.
+*/
+var UnsupportedConditionError = class extends Error {
+	/** The kind of reference the condition used. */
+	reference;
+	/**
+	* @param reference - The unsupported kind of reference.
+	*/
+	constructor(reference) {
+		super(`A condition uses a ${reference} reference, which the Facts port does not answer: it resolves single keys only`);
+		this.name = "UnsupportedConditionError";
+		this.reference = reference;
+	}
+};
+const evaluator = createSyncEvaluator({});
+/**
+* Evaluates every transition's condition.
+*
+* A definite true is `taken`, a definite false is `not-taken` and an indeterminate result is `indeterminate`. A transition without a condition is `taken`. Conditions are evaluated for every transition regardless of the state of its source.
+* @param model - The model whose transitions are evaluated.
+* @param overlay - Run state, read by `elementStatusKey` references.
+* @param facts - The injected source of facts.
+* @returns The outcome of every transition, in transition order.
+* @throws UnsupportedConditionError when a condition contains a `lookup`, `some`, `every` or fold node.
+*/
+const evaluateBranches = (model, overlay, facts) => {
+	const elementIds = new Set(model.elements.map(({ id }) => id));
+	const overlayOf = new Map(Object.entries(overlay));
+	const resolvers = {
+		resolveValue: (key) => {
+			if (!isRecord(key) || !(elementField in key)) return facts(key);
+			const id = key[elementField];
+			if (typeof id !== "string" || !elementIds.has(id)) return { found: false };
+			const state = overlayOf.get(id);
+			if (state === "unknown") return { found: false };
+			return {
+				found: true,
+				value: {
+					kind: "text",
+					value: state === "done" ? "done" : "open"
+				}
+			};
+		},
+		resolveLookup: () => {
+			throw new UnsupportedConditionError("lookup");
+		},
+		resolveCollection: () => {
+			throw new UnsupportedConditionError("collection");
+		}
+	};
+	return new Map(model.transitions.map(({ id, condition }) => {
+		if (condition === void 0) return [id, "taken"];
+		const result = evaluator.evaluatePredicate(condition, void 0, resolvers);
+		if (result.status === "indeterminate") return [id, "indeterminate"];
+		return [id, result.value ? "taken" : "not-taken"];
+	}));
+};
+//#endregion
 //#region ../../core/graph/domain/dist/control.js
 /**
 * Builds the dependency graph over every element, leaving out the transitions in `excluded`. A node needs the source of each remaining incoming transition and, for an activity, the producer of each artefact it consumes.
@@ -291,4 +453,4 @@ const controlDag = (model) => buildControl(model, new Set(loopTransitions(model)
 */
 const illegalCycles = (model) => findCycles(controlDag(model));
 //#endregion
-export { findCycles as a, descendantsOf as c, lookup as d, CycleError as f, assertAcyclic as i, assembleDag as l, illegalCycles as n, stronglyConnectedComponents as o, UnknownNodeError as p, loopTransitions as r, ancestorsOf as s, controlDag as t, buildDag as u };
+export { UnknownNodeError as S, descendantsOf as _, artefactKey as a, lookup as b, evaluateBranches as c, isProvided as d, layeredFacts as f, ancestorsOf as g, stronglyConnectedComponents as h, UnsupportedConditionError as i, factNamesIn as l, findCycles as m, illegalCycles as n, elementStatusKey as o, assertAcyclic as p, loopTransitions as r, emptyFactRecord as s, controlDag as t, factsFrom as u, assembleDag as v, CycleError as x, buildDag as y };

package/dist/{dist-HLlW8vgT.js → dist-BxHnxpcT.js}

@@ -1,13 +1,13 @@
 import { a as validateOverlay, d as overlayStatuses, f as participantKinds } from "./schema-CVnS6HiX.js";
 import { t as validate } from "./validate-DF3mQZww.js";
 import { n as parseModel, t as ModelParseError } from "./parse-CuipC_2K.js";
-import { _ as toSwimlane, b as handoffs, c as deriveStatuses, g as toStateMachine, i as readySet, m as toSequence, n as criticalPath, r as impact, s as explainStatus, t as blockedBy, y as toFlowchart } from "./queries-CCexJAE2.js";
-import { f as CycleError, n as illegalCycles, p as UnknownNodeError } from "./control-aDk9560d.js";
+import { c as deriveStatuses, f as toStateMachine, g as handoffs, h as toFlowchart, i as readySet, n as criticalPath, p as toSwimlane, r as impact, s as explainStatus, t as blockedBy, u as toSequence } from "./queries-C8kIDRiY.js";
+import { S as UnknownNodeError, f as layeredFacts, n as illegalCycles, u as factsFrom, x as CycleError } from "./control-DiygoEhm.js";
 import { l as assembleSync, t as createGitHubIssuesSource, u as createGraphSourceRouter } from "./source-DRDpEA8Q.js";
 import { t as githubTokenFromEnvironment } from "./node-AchI1T-K.js";
-import { f as emptyModel } from "./store-BcR70CaO.js";
-import { t as createGraphStoreRouter } from "./router-D4gtTlXm.js";
-import { t as openNodeGraphStore } from "./open-CyRXJ4bt.js";
+import { g as emptyModel } from "./store-BJILV4JS.js";
+import { t as createGraphStoreRouter } from "./router-DvGGLnNt.js";
+import { t as openNodeGraphStore } from "./open-BF-UHqeW.js";
 import { t as exitCodes } from "./exit-codes-0ultCqdS.js";
 import { ORPCError, createRouterClient } from "@orpc/server";
 import { Argument, Command, CommanderError, Option } from "commander";
@@ -95,6 +95,13 @@ const failureOf = (error) => {
 //#endregion
 //#region ../graph-cli/dist/session.js
 /**
+* The facts a run's reasoning reads: the model's stored fact record first, then the session's own facts for every key the record does not answer. What `set artefact` and `set fact` record therefore overrides a host's facts only where it says something.
+* @param session - The session, whose facts the host supplied.
+* @param run - The stored run.
+* @returns The `Facts` port for graph-domain.
+*/
+const runFacts = (session, run) => layeredFacts(factsFrom(run.facts), session.facts);
+/**
 * The oRPC client options carrying the session's signal. The key is left out when there is no signal, since the options type does not accept an explicit `undefined`.
 * @param signal - The signal, if any.
 */
@@ -110,7 +117,8 @@ const findRun = async (session) => {
 		return {
 			revision: stored.revision,
 			model: stored.model,
-			overlay: stored.overlay
+			overlay: stored.overlay,
+			facts: stored.facts
 		};
 	} catch (error) {
 		if (error instanceof ORPCError && error.code === "NOT_FOUND") return;
@@ -212,6 +220,74 @@ const setState = async (session, id, state) => {
 		revision
 	};
 };
+/** What can be recorded about an artefact: `provided`, known not provided (`absent`), or `unknown`, which forgets whatever was recorded. */
+const artefactStates = [
+	"provided",
+	"absent",
+	"unknown"
+];
+/**
+* Records whether an artefact of the session's model is provided, so a consumer of an input no activity produces can become ready, or forgets it with `unknown`.
+* @param session - The store and model.
+* @param id - The artefact.
+* @param state - `provided`, `absent` or `unknown`.
+* @returns The artefact, its new state and the revision the change took.
+* @throws CliError with `notFound` when the model or the artefact does not exist.
+*/
+const setArtefact = async (session, id, state) => {
+	const { model } = await loadRun(session);
+	if (!model.artefacts.some((artefact) => artefact.id === id)) throw new CliError(exitCodes.notFound, `no artefact "${id}" in the model`);
+	const options = callOptions(session.signal);
+	const { revision } = state === "unknown" ? await session.store.v1.facts.clear({
+		modelId: session.modelId,
+		facts: { artefacts: [id] }
+	}, options) : await session.store.v1.facts.set({
+		modelId: session.modelId,
+		facts: { artefacts: { [id]: state === "provided" } }
+	}, options);
+	return {
+		artefact: id,
+		state,
+		revision
+	};
+};
+/**
+* Records a named fact's value for the session's model, so every condition reading that name evaluates against it, or forgets it with `unknown`, so those conditions are indeterminate again.
+* @param session - The store and model.
+* @param name - The fact's name, the key a condition's `reference` node gives.
+* @param value - Its trilean value, or `unknown`.
+* @returns The fact, its new value and the revision the change took.
+* @throws CliError with `notFound` when the model does not exist.
+*/
+const setFact = async (session, name, value) => {
+	await loadRun(session);
+	const options = callOptions(session.signal);
+	const { revision } = value === "unknown" ? await session.store.v1.facts.clear({
+		modelId: session.modelId,
+		facts: { values: [name] }
+	}, options) : await session.store.v1.facts.set({
+		modelId: session.modelId,
+		facts: { values: { [name]: value } }
+	}, options);
+	return {
+		fact: name,
+		value,
+		revision
+	};
+};
+/**
+* Reads what is recorded about the session's model's run: which artefacts are provided or absent, and each named fact's value.
+* @param session - The store and model.
+* @returns The fact record and the model's revision.
+* @throws CliError with `notFound` when the model does not exist.
+*/
+const factsOf = async (session) => {
+	const { revision, facts } = await loadRun(session);
+	return {
+		revision,
+		facts
+	};
+};
 //#endregion
 //#region ../graph-cli/dist/queries.js
 /** Each element counts as one step, so the critical path is the longest chain of elements. */
@@ -221,8 +297,9 @@ const stepWeight = 1;
 * @param session - The store, model and facts.
 */
 const ready = async (session) => {
-	const { model, overlay } = await loadRun(session);
-	return { elements: summarise(model, readySet(model, overlay, session.facts)) };
+	const run = await loadRun(session);
+	const { model, overlay } = run;
+	return { elements: summarise(model, readySet(model, overlay, runFacts(session, run))) };
 };
 const statusOf = (statuses, summary) => {
 	const status = statuses.get(summary.id);
@@ -238,15 +315,17 @@ const statusOf = (statuses, summary) => {
 * @param id - The element asked about.
 */
 const blocked = async (session, id) => {
-	const { model, overlay } = await loadRun(session);
+	const run = await loadRun(session);
+	const { model, overlay } = run;
+	const facts = runFacts(session, run);
 	const element = requireElement(model, id);
-	const statuses = deriveStatuses(model, overlay, session.facts);
+	const statuses = deriveStatuses(model, overlay, facts);
 	return {
 		element: statusOf(statuses, {
 			id,
 			label: labelOf(element)
 		}),
-		blockedBy: summarise(model, blockedBy(model, overlay, session.facts, id))
+		blockedBy: summarise(model, blockedBy(model, overlay, facts, id))
 	};
 };
 /**
@@ -255,15 +334,17 @@ const blocked = async (session, id) => {
 * @param id - The element asked about.
 */
 const impactOf = async (session, id) => {
-	const { model, overlay } = await loadRun(session);
+	const run = await loadRun(session);
+	const { model, overlay } = run;
+	const facts = runFacts(session, run);
 	const element = requireElement(model, id);
-	const statuses = deriveStatuses(model, overlay, session.facts);
+	const statuses = deriveStatuses(model, overlay, facts);
 	return {
 		element: statusOf(statuses, {
 			id,
 			label: labelOf(element)
 		}),
-		impacted: summarise(model, impact(model, overlay, session.facts, id))
+		impacted: summarise(model, impact(model, overlay, facts, id))
 	};
 };
 /**
@@ -271,8 +352,9 @@ const impactOf = async (session, id) => {
 * @param session - The store, model and facts.
 */
 const path = async (session) => {
-	const { model, overlay } = await loadRun(session);
-	const found = criticalPath(model, overlay, session.facts, () => stepWeight);
+	const run = await loadRun(session);
+	const { model, overlay } = run;
+	const found = criticalPath(model, overlay, runFacts(session, run), () => stepWeight);
 	return {
 		path: summarise(model, found.path),
 		weight: found.weight
@@ -300,9 +382,10 @@ const handoffsOf = async (session) => {
 * @param id - The element asked about.
 */
 const why = async (session, id) => {
-	const { model, overlay } = await loadRun(session);
+	const run = await loadRun(session);
+	const { model, overlay } = run;
 	requireElement(model, id);
-	const explained = explainStatus(model, overlay, session.facts, id);
+	const explained = explainStatus(model, overlay, runFacts(session, run), id);
 	const chain = explained.chain.map((link) => ({
 		id: link.element,
 		label: labelOf(requireElement(model, link.element)),
@@ -375,6 +458,17 @@ const renderWhy = (result) => {
 const renderAdded = (kind, id, written) => lines([`added ${kind} ${id} at revision ${String(written.revision)}`]);
 /** `set`: the element's new run state and the revision it took. */
 const renderSet = (result) => lines([`set ${result.element} to ${result.state} at revision ${String(result.revision)}`]);
+/** A fact's value as the command line reads it back: a boolean or number as written, text as it is, and the other kinds as their JSON. */
+const valueText = (value) => {
+	if (value.kind === "boolean" || value.kind === "number") return value.kind === "number" && value.unit !== void 0 ? JSON.stringify(value) : String(value.value);
+	return value.kind === "text" ? value.value : JSON.stringify(value);
+};
+/** `set artefact`: the artefact's new state and the revision it took. */
+const renderSetArtefact = (result) => lines([`set artefact ${result.artefact} to ${result.state} at revision ${String(result.revision)}`]);
+/** `set fact`: the fact's new value and the revision it took. */
+const renderSetFact = (result) => lines([`set fact ${result.fact} to ${result.value === "unknown" ? "unknown" : valueText(result.value)} at revision ${String(result.revision)}`]);
+/** `facts`: each recorded artefact as `artefact`, its id and `provided` or `absent`, then each named fact as `fact`, its name and its value, each sorted by id or name. */
+const renderFacts = (result) => lines([...Object.entries(result.facts.artefacts).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([id, provided]) => `artefact\t${id}\t${provided ? "provided" : "absent"}`), ...Object.entries(result.facts.values).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([name, value]) => `fact\t${name}\t${valueText(value)}`)]);
 /** `sync`: what was written, then each gap as its reason, target and message. */
 const renderSync = (result) => lines([`synced ${String(result.activities)} activities, ${String(result.transitions)} transitions and ${String(result.participants)} participants into "${result.modelId}" at revision ${String(result.revision)}`, ...result.gaps.map((gap) => `gap\t${gap.reason}\t${gap.target}\t${gap.message}`)]);
 /** `validate`: `valid`, or each issue as its code, its JSON pointer when it has one, and its message. */
@@ -962,12 +1056,42 @@ const readGlobals = (command, ports) => {
 		json: json === true
 	};
 };
+/** Narrows a variadic option's values, which commander gives as an untyped array, to the strings they are. */
+const isText = (value) => typeof value === "string";
 const isOneOf = (values, value) => values.some((candidate) => candidate === value);
 /** Reads an option whose choices commander has already checked, narrowing it to its type. */
 const choice = (values, value, name) => {
 	if (!isOneOf(values, value)) throw new Error(`--${name} was not checked against its choices`);
 	return value;
 };
+/** The word that forgets a named fact rather than giving it a value. */
+const unknownValue = "unknown";
+/** A number as JSON writes one, so a value that reads as a number is never also meant as text. */
+const jsonNumber = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/u;
+/**
+* Reads a fact's value from the command line: `true` and `false` are booleans, `unknown` forgets the fact, a JSON number is a number, and anything else is text; `--text` reads the value as text whatever it looks like.
+* @param value - The value as given.
+* @param asText - Whether `--text` was given.
+* @returns The trilean value, or `unknown`.
+*/
+const factValueOf = (value, asText) => {
+	if (asText) return {
+		kind: "text",
+		value
+	};
+	if (value === unknownValue) return unknownValue;
+	if (value === "true" || value === "false") return {
+		kind: "boolean",
+		value: value === "true"
+	};
+	return jsonNumber.test(value) ? {
+		kind: "number",
+		value: Number(value)
+	} : {
+		kind: "text",
+		value
+	};
+};
 /**
 * Runs the command line with the given arguments, writing only through the ports, and resolves with the exit status. It never exits the process or reads its arguments itself, so a test or a host program such as Switchboard runs it as a function.
 * @param args - The arguments after the program name, such as `["ready", "--json"]`.
@@ -1131,15 +1255,17 @@ const runCli = async (args, ports, identity) => {
 			}
 		}, "participant");
 	});
-	addCommand.command("activity").description("add an activity: a step of work").argument("<id>", "its identifier").argument("<label>", "its label").option("--actor <participant>", "the role or system that does it").action(async (id, label, options, command) => {
-		const { actor } = options;
+	addCommand.command("activity").description("add an activity: a step of work").argument("<id>", "its identifier").argument("<label>", "its label").option("--actor <participant>", "the role or system that does it").option("--consumes <artefact...>", "the artefacts it needs before it can start").option("--produces <artefact...>", "the artefacts it makes").action(async (id, label, options, command) => {
+		const { actor, consumes, produces } = options;
 		await added(command, {
 			kind: "element",
 			record: {
 				kind: "activity",
 				id,
 				label,
-				...typeof actor === "string" ? { actor } : {}
+				...typeof actor === "string" ? { actor } : {},
+				...Array.isArray(consumes) ? { consumes: consumes.filter(isText) } : {},
+				...Array.isArray(produces) ? { produces: produces.filter(isText) } : {}
 			}
 		}, "activity");
 	});
@@ -1202,7 +1328,7 @@ const runCli = async (args, ports, identity) => {
 			}
 		}, "transition");
 	});
-	program.command("set").description("set an element's run state").argument("<id>", "the element").addArgument(new Argument("<state>", "its run state").choices(overlayStatuses)).action(async (id, state, _options, command) => {
+	const setCommand = program.command("set").description("set an element's run state; set artefact and set fact record what is known from outside the process").argument("<id>", "the element").addArgument(new Argument("<state>", "its run state").choices(overlayStatuses)).action(async (id, state, _options, command) => {
 		const status = choice(overlayStatuses, state, "state");
 		await withSession(async (session) => {
 			const result = await setState(session, id, status);
@@ -1212,6 +1338,35 @@ const runCli = async (args, ports, identity) => {
 			};
 		})(command);
 	});
+	setCommand.command("artefact").description("record whether an artefact is provided, so work consuming it can start; unknown forgets it").argument("<id>", "the artefact").addArgument(new Argument("<state>", "whether it is provided").choices(artefactStates)).action(async (id, state, _options, command) => {
+		const provision = choice(artefactStates, state, "state");
+		await withSession(async (session) => {
+			const result = await setArtefact(session, id, provision);
+			return {
+				json: result,
+				text: renderSetArtefact(result)
+			};
+		})(command);
+	});
+	setCommand.command("fact").description("record the value of a named fact that decision conditions read; unknown forgets it").argument("<name>", "the fact's name, as a condition's reference gives it").argument("<value>", "true, false, unknown, a number, or any other text").option("--text", "read the value as text, even true, false or a number").action(async (name, value, options, command) => {
+		const parsed = factValueOf(value, options.text === true);
+		await withSession(async (session) => {
+			const result = await setFact(session, name, parsed);
+			return {
+				json: result,
+				text: renderSetFact(result)
+			};
+		})(command);
+	});
+	program.command("facts").description("list what is recorded about the run: each artefact provided or absent, and each named fact's value").action(async (_options, command) => {
+		await withSession(async (session) => {
+			const result = await factsOf(session);
+			return {
+				json: result,
+				text: renderFacts(result)
+			};
+		})(command);
+	});
 	program.command("validate").description("check the stored model, or a model file, for problems; exits with the invalid model status when there are any").argument("[file]", "a model as JSON, checked instead of the stored model").action(async (file, _options, command) => {
 		const outcome = (result) => ({
 			json: result,
@@ -1385,4 +1540,4 @@ const runProcess = async (identity) => {
 	return runCli(process.argv.slice(2), nodePorts({ signal: controller.signal }), identity);
 };
 //#endregion
-export { add as A, blocked as C, path as D, impactOf as E, failureOf as F, findRun as M, loadRun as N, ready as O, CliError as P, swimlaneToMermaid as S, handoffsOf as T, stateMachineToDot as _, defaultModelId as a, sequenceToMermaid as b, validateStored as c, formatNames as d, project as f, sequenceToDot as g, flowchartToDot as h, runProcess as i, setState as j, why as k, sync as l, viewNames as m, nodePorts as n, runCli as o, show as p, packageVersion as r, validateDocument as s, defaultDataPath as t, emit as u, swimlaneToDot as v, cycles as w, stateMachineToMermaid as x, flowchartToMermaid as y };
+export { add as A, failureOf as B, blocked as C, path as D, impactOf as E, setState as F, findRun as I, loadRun as L, factsOf as M, setArtefact as N, ready as O, setFact as P, runFacts as R, swimlaneToMermaid as S, handoffsOf as T, stateMachineToDot as _, defaultModelId as a, sequenceToMermaid as b, validateStored as c, formatNames as d, project as f, sequenceToDot as g, flowchartToDot as h, runProcess as i, artefactStates as j, why as k, sync as l, viewNames as m, nodePorts as n, runCli as o, show as p, packageVersion as r, validateDocument as s, defaultDataPath as t, emit as u, swimlaneToDot as v, cycles as w, stateMachineToMermaid as x, flowchartToMermaid as y, CliError as z };

package/dist/dist-Cw63tKU9.js

@@ -0,0 +1,3 @@
+import "./exit-codes-0ultCqdS.js";
+import { i as runProcess, r as packageVersion } from "./dist-BxHnxpcT.js";
+export { packageVersion, runProcess };