process-graph 1.1.1 → 1.3.0

package/README.md

@@ -40,24 +40,26 @@ deriveStatuses(model, { submit: "done" }, facts); // Map { "submit" => "done", "
 
 The package is built from the repository's internal packages, which are bundled into it and not published on their own; each internal package's README documents its functions and rules. Each subpath loads only the code it reaches.
 
-| Import                               | What it is                                                                                                                                                                         | Runs in               |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
-| `process-graph`                      | The model (`defineModel`, `parseModel`, `validate`), its projections and inverses, and the reasoning over a run (statuses, ready set, blocked-by, impact, what-if, critical path). | Browser, Worker, Node |
-| `process-graph/layout`               | `layout`: positions for a projected flowchart, swimlane or state machine, in the model's `views` shape, through elkjs.                                                             | Browser, Worker, Node |
-| `process-graph/source/github`        | The `GraphSource` port (contract, schemas, router, pagination and an in-memory fake) and the GitHub issues adapter, `createGitHubIssuesSource`.                                    | Browser, Worker, Node |
-| `process-graph/source/github/node`   | `githubTokenFromEnvironment`: a token port reading `GITHUB_TOKEN` or the GitHub CLI's token.                                                                                       | Node                  |
-| `process-graph/store`                | The `GraphStore` port (contract, schemas, router, change feed, structural queries and an in-memory fake) and the SQLite store over any Drizzle SQLite database.                    | Browser, Worker, Node |
-| `process-graph/store/node`           | `openNodeGraphStore`: the SQLite store on Node's built-in `node:sqlite`.                                                                                                           | Node                  |
-| `process-graph/store/wasm`           | `connectGraphStore`: connects a page to the store a dedicated worker serves.                                                                                                       | Browser               |
-| `process-graph/store/wasm/worker`    | `serveGraphStoreInWorker`: serves the store from a dedicated worker on SQLite wasm and OPFS, shared between tabs with no special headers.                                          | Dedicated worker      |
-| `process-graph/react`                | Headless React hooks and unstyled components: follow a stored model, derive its run, project, filter and select.                                                                   | Browser               |
-| `process-graph/ui`                   | Styled components over `process-graph/react`, the SVG sequence diagram and the theme contract with light and dark themes.                                                          | Browser               |
-| `process-graph/ui/style.css`         | The compiled styles for `process-graph/ui`.                                                                                                                                        | Browser               |
-| `process-graph/react-flow`           | React Flow views of a flowchart, swimlane or state machine, laid out by `process-graph/layout`.                                                                                    | Browser               |
-| `process-graph/react-flow/style.css` | The compiled styles for `process-graph/react-flow`, React Flow's own included.                                                                                                     | Browser               |
-| `process-graph/cli`                  | The command line as a library: `runCli` over injected ports, `nodePorts` for a Node process, and each command's operation returning plain data.                                    | Node                  |
-
-`zod` and `trilean`, which the root entry needs, are dependencies. The libraries only other subpaths need are optional peer dependencies, so installing `process-graph` for its root entry pulls in nothing else; install the peers of each subpath you import beside it:
+| Import                               | What it is                                                                                                                                                                                          | Runs in               |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| `process-graph`                      | The model (`defineModel`, `parseModel`, `validate`), its projections and inverses, and the reasoning over a run (statuses, ready set, blocked-by, impact, what-if, critical path).                  | Browser, Worker, Node |
+| `process-graph/layout`               | `layout`: positions for a projected flowchart, swimlane or state machine, in the model's `views` shape, through elkjs.                                                                              | Browser, Worker, Node |
+| `process-graph/source/github`        | The `GraphSource` port (contract, schemas, router, pagination and an in-memory fake) and the GitHub issues adapter, `createGitHubIssuesSource`.                                                     | Browser, Worker, Node |
+| `process-graph/source/github/node`   | `githubTokenFromEnvironment`: a token port reading `GITHUB_TOKEN` or the GitHub CLI's token.                                                                                                        | Node                  |
+| `process-graph/store`                | The `GraphStore` port (contract, schemas, router, change feed, structural queries and an in-memory fake) and the SQLite store over any Drizzle SQLite database.                                     | Browser, Worker, Node |
+| `process-graph/store/node`           | `openNodeGraphStore`: the SQLite store on Node's built-in `node:sqlite`; `prepareDataFile`: makes its data file and directory private before it opens.                                              | Node                  |
+| `process-graph/store/wasm`           | `connectGraphStore`: connects a page to the store a dedicated worker serves.                                                                                                                        | Browser               |
+| `process-graph/store/wasm/worker`    | `serveGraphStoreInWorker`: serves the store from a dedicated worker on SQLite wasm and OPFS, shared between tabs with no special headers.                                                           | Dedicated worker      |
+| `process-graph/react`                | Headless React hooks and unstyled components: follow a stored model, derive its run, project, filter and select.                                                                                    | Browser               |
+| `process-graph/ui`                   | Styled components over `process-graph/react`, the SVG sequence diagram and the theme contract with light and dark themes.                                                                           | Browser               |
+| `process-graph/ui/theme`             | The theme contract `vars`, `lightTheme`, `darkTheme`, `lightValues` and `darkValues` without the components, for a Vanilla Extract stylesheet that themes `process-graph/ui` without loading React. | Any                   |
+| `process-graph/ui/style.css`         | The compiled styles for `process-graph/ui`.                                                                                                                                                         | Browser               |
+| `process-graph/react-flow`           | React Flow views of a flowchart, swimlane or state machine, laid out by `process-graph/layout`.                                                                                                     | Browser               |
+| `process-graph/react-flow/style.css` | The compiled styles for `process-graph/react-flow`, React Flow's own included.                                                                                                                      | Browser               |
+| `process-graph/cli`                  | The command line as a library: `runCli` over injected ports, `nodePorts` for a Node process, each command's operation returning plain data, and `version`, this package's own.                      | Node                  |
+| `process-graph/package.json`         | The package's manifest, for reading its version or anything else it declares.                                                                                                                       | Any                   |
+
+`zod` and `trilean`, which the root entry needs, are dependencies; a project with an install age gate exempts `trilean` and `trilean-regex` beside `process-graph` (see [Install](../../../README.md#install)). The libraries only other subpaths need are optional peer dependencies, so installing `process-graph` for its root entry pulls in nothing else; install the peers of each subpath you import beside it:
 
 | Subpath             | Peer dependencies                                                            |
 | ------------------- | ---------------------------------------------------------------------------- |
@@ -69,10 +71,11 @@ The package is built from the repository's internal packages, which are bundled
 | `store/wasm/worker` | `@orpc/contract`, `@orpc/server`, `drizzle-orm`, `@sqlite.org/sqlite-wasm`   |
 | `react`             | `react`                                                                      |
 | `ui`                | `react`, `@vanilla-extract/recipes`, `@vanilla-extract/css` (types)          |
+| `ui/theme`          | `@vanilla-extract/css` (types)                                               |
 | `react-flow`        | `react`, `react-dom`, `@xyflow/react`, `elkjs`, `@vanilla-extract/recipes`   |
 | `cli` and the bin   | `commander`, `@orpc/client`, `@orpc/contract`, `@orpc/server`, `drizzle-orm` |
 
-The versions are the ones `package.json` declares under `peerDependencies`.
+The versions are the ones `package.json` declares under `peerDependencies`. A peer with a stable version is a caret range whose floor is the version this package is tested against, so any later compatible release satisfies it. The oRPC packages, `drizzle-orm` and `@sqlite.org/sqlite-wasm` are prereleases, which have no compatible-range semantics (a range on one admits only later prereleases of the same version, which may break anything), so each is declared at the exact version tested.
 
 With Vite, exclude `@sqlite.org/sqlite-wasm` from dependency pre-bundling (`optimizeDeps.exclude`), since it loads its `.wasm` file relative to itself. A worker module serving the browser store is one call:
 

package/dist/bin.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { t as exitCodes } from "./exit-codes-0ultCqdS.js";
+import { t as version } from "./version-Dagrkvwt.js";
 import { readFileSync } from "node:fs";
 //#region src/missing-peers.ts
 /**
@@ -66,7 +67,7 @@ const manifest = new URL("../package.json", import.meta.url);
 const declaredPeers = () => {
 	const parsed = JSON.parse(readFileSync(manifest, "utf8"));
 	if (typeof parsed !== "object" || parsed === null || !("peerDependencies" in parsed) || typeof parsed.peerDependencies !== "object" || parsed.peerDependencies === null) throw new Error(`${manifest.pathname} declares no peerDependencies`);
-	return new Map(Object.entries(parsed.peerDependencies).flatMap(([name, version]) => typeof version === "string" ? [[name, version]] : []));
+	return new Map(Object.entries(parsed.peerDependencies).flatMap(([name, specifier]) => typeof specifier === "string" ? [[name, specifier]] : []));
 };
 /** Whether a package resolves from this bin's own location, as the command line's imports would. Only a package that is not installed counts as missing; any other resolution error is the import's to report. */
 const resolves = (name) => {
@@ -83,10 +84,10 @@ 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 { runProcess } = await import("./dist-81kTKnMq.js");
 	process.exitCode = await runProcess({
 		name: "process-graph",
-		version: packageVersion(manifest)
+		version
 	});
 }
 //#endregion

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 { 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 "./index-CptUHq6F.js";
-import { A as Flowchart, E as Swimlane, M as Handoff, g as SequenceDiagram, x as StateMachine } from "./index-CoA6vXqe.js";
+import { A as Facts, B as Status, _ as StatusRule, k as FactRecord, m as IncomingBasis, p as ArtefactBasis } from "./index-D4CnOhNf.js";
+import { A as Transition, C as EventDef, D as Participant, I as OverlayStatus, K as IdSpace, S as Element, _ as Model, o as Overlay, q as OpenIds, x as ArtefactDef } from "./index-Dvz_I_uQ.js";
+import { C as Gap, n as GraphqlFetch, t as GitHubTokenPort, v as GraphSourceClient } from "./graphql-BE7xm5dB.js";
+import { ut as GraphStoreClient } from "./index-CR8xUK3S.js";
+import "./index-hri2a13-.js";
+import { A as Flowchart, E as Swimlane, M as Handoff, g as SequenceDiagram, x as StateMachine } from "./index-D06bcdfw.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;
@@ -117,13 +118,17 @@ interface NodePortsOptions {
   readonly env?: Readonly<Record<string, string | undefined>>;
   /** The home directory the default data path falls back on; the user's when absent. */
   readonly home?: string;
+  /**
+   * A data file the host owns, such as one under its own home directory. It becomes the default data path in place of `PROCESS_GRAPH_DATA` and the XDG data file, and it gets the treatment the command line gives its own XDG data file: its directory, and any missing directories above it, are created readable by the owner only and kept that way, the database is created owner-only before SQLite opens it, and an existing store others can read is narrowed, with a warning on standard error (see `prepareDataFile` in `process-graph/store/node`). A path given with `--data` still wins, and is treated as the user's. The XDG data file when absent.
+   */
+  readonly dataPath?: string;
   /** Supplies GitHub tokens; `GITHUB_TOKEN` or the GitHub CLI's token (`githubTokenFromEnvironment`) when absent. */
   readonly token?: GitHubTokenPort;
   /** How requests reach GitHub; the global `fetch` when absent. */
   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;
@@ -149,7 +154,7 @@ export declare const defaultDataPath: (env: Readonly<Record<string, string | und
  */
 export declare const packageVersion: (manifest: URL) => string;
 /**
- * The ports for a Node process: the SQLite store over `node:sqlite` (creating the data file's directory when needed), the GitHub issues source for `github:` scopes, the file system and the process's streams.
+ * The ports for a Node process: the SQLite store over `node:sqlite` (creating the data file's directory when needed, private when the command line or the host owns it), the GitHub issues source for `github:` scopes, the file system and the process's streams.
  * @param options - Replacements for any of the defaults.
  * @returns The ports.
  */
@@ -162,20 +167,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 +408,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. */
@@ -431,6 +489,30 @@ interface SyncRequest {
   /** A cursor from an interrupted sync: the first source's sync continues after it. */
   readonly after?: string;
 }
+/** Where a sync a source interrupted carries on, as data a host acts on; the command line renders it as the commands to run. */
+interface SyncInterruption {
+  /** The request that continues the failing source: its scopes, after the cursor of the last page read from it, or from the start when none was read. */
+  readonly resume: SyncRequest;
+  /** The scopes of the sources after the failing one, which were not read; sync them afresh once `resume` has finished. */
+  readonly remaining: readonly string[];
+  /** Whether pages read before the failure were written to the model. */
+  readonly saved: boolean;
+}
+/**
+ * Thrown by `sync` when a source fails part way. Its exit status and message are the source's failure, classified as `failureOf` classifies it; its cause is the error underneath that failure, such as the token port's own error; and what to run next is data, in `resume` and `remaining`, never text.
+ */
+export declare class SyncInterruptedError extends CliError implements SyncInterruption {
+  readonly resume: SyncRequest;
+  readonly remaining: readonly string[];
+  readonly saved: boolean;
+  /**
+   * @param exitCode - The exit status the source's failure maps to.
+   * @param message - The source's failure.
+   * @param interruption - Where the sync carries on.
+   * @param options - The underlying error, kept as the cause.
+   */
+  constructor(exitCode: CliError["exitCode"], message: string, interruption: SyncInterruption, options?: ErrorOptions);
+}
 /** What a sync wrote. */
 interface SyncResult {
   readonly modelId: string;
@@ -446,12 +528,12 @@ interface SyncResult {
 /**
  * Reads every page of the scopes from their sources and merges them into the session's model in one write, creating the model when the store has none. Records already in the model are replaced by identifier and the rest are kept, so syncing again refreshes what changed.
  *
- * When a source fails part way, the pages read before the failure are still written, and the error says how to resume: the failing source's scopes with `--after` and the cursor of its last page read.
+ * When a source fails part way, the pages read before the failure are still written, and the error carries where to carry on: the request that resumes the failing source after the cursor of its last page read, and the scopes of the sources not reached.
  * @param session - The store and model.
  * @param sources - The source for each identifier prefix.
  * @param request - The scopes, and a cursor to resume after.
  * @returns What was written, and the gaps the sources reported.
- * @throws CliError with `usage` for a scope with no source prefix, a prefix no source serves, or `after` with scopes of more than one source; and with the source's failure, the resume command added, when a source refuses the sync.
+ * @throws CliError with `usage` for a scope with no source prefix, a prefix no source serves, or `after` with scopes of more than one source; and SyncInterruptedError, with the source's failure and where to carry on, when a source fails part way.
  */
 export declare const sync: (session: GraphSession, sources: SourceLookup, request: SyncRequest) => Promise<SyncResult>;
 //#endregion
@@ -509,4 +591,8 @@ 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 };
+//#region src/version.d.ts
+/** The version of the installed `process-graph` package, as its manifest names it. The bundler writes it in when the package is built, so reading it touches no file. */
+export declare const version: string;
+//#endregion
+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, SyncInterruption, SyncRequest, SyncResult, ValidateResult, ValidationIssue, ViewName, WhyLink, WhyResult, Written };

package/dist/cli.js

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

@@ -0,0 +1,95 @@
+import { t as createSqliteGraphStore } from "./store-DKzvLGgl.js";
+import { sql } from "drizzle-orm";
+import { DatabaseSync } from "node:sqlite";
+import { drizzle } from "drizzle-orm/node-sqlite";
+import { chmodSync, closeSync, mkdirSync, openSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+//#region ../../adapters/graph/sqlite-node/dist/open.js
+/** The path `node:sqlite` reads as a private database in memory rather than a file. */
+const inMemory = ":memory:";
+/**
+* Opens a graph store on a SQLite database file, creating the file when it does not exist. The schema is migrated on the store's first operation.
+*
+* A file database is switched to write-ahead logging, so readers in other processes (a command line beside a server) are not blocked by a writer. Each process's change feed sees only its own writes.
+* @param path - The database file, or `":memory:"` for a private database that lives as long as the store.
+* @param options - `node:sqlite` options passed through unchanged, such as `timeout` for how long a write waits for another process's lock.
+* @returns The store, its database and a way to close it.
+*/
+const openNodeGraphStore = (path, options = {}) => {
+	const client = new DatabaseSync(path, options);
+	const db = drizzle({ client });
+	if (path !== inMemory) db.run(sql`PRAGMA journal_mode = WAL`);
+	return {
+		store: createSqliteGraphStore({ db }),
+		db,
+		close: () => {
+			client.close();
+		}
+	};
+};
+//#endregion
+//#region ../../adapters/graph/sqlite-node/dist/data-file.js
+/** The data directory's mode: only its owner may list or enter it, since the store holds synced work (titles, relationships) that other users on the host must not read. */
+const privateDirectoryMode = 448;
+/** The data file's mode: only its owner may read or write it. SQLite creates the `-wal` and `-shm` files beside it with the same mode on Unix. */
+const privateFileMode = 384;
+/** The permission bits of a file mode, without its type. */
+const permissionBits = 511;
+/** The bits that give the file's group or anyone else any access. */
+const groupAndOtherBits = 63;
+/** The SQLite files a store at `path` uses: the database and its write-ahead log and shared-memory index. */
+const storeFiles = (path) => [
+	path,
+	`${path}-wal`,
+	`${path}-shm`
+];
+/** Whether an error is the file system's report that a path does not exist, or already does. */
+const hasCode = (error, code) => error instanceof Error && "code" in error && error.code === code;
+/**
+* Narrows a path's mode to `mode` when its group or others have any access.
+* @param path - The path.
+* @param mode - The private mode it should have.
+* @returns Whether the mode was changed; `false` too when the path does not exist.
+*/
+const tighten = (path, mode) => {
+	let current;
+	try {
+		current = statSync(path).mode & permissionBits;
+	} catch (error) {
+		if (hasCode(error, "ENOENT")) return false;
+		throw error;
+	}
+	if ((current & groupAndOtherBits) === 0) return false;
+	chmodSync(path, mode);
+	return true;
+};
+/**
+* Makes a data file ready for `openNodeGraphStore` to open, so a store holding synced work is never readable by other users on the host. Call it before opening the store; it does not open the database itself.
+*
+* The directory is created when missing (with any missing parents), with `privateDirectoryMode` when it is the caller's own. The database file is created with `privateFileMode` when missing, before SQLite opens it, so the file and the `-wal` and `-shm` files SQLite derives from it are never readable by others, whatever the umask. A file that already exists is left alone unless the directory is the caller's own; there, an existing directory or store file (database, `-wal` or `-shm`) that group or others can read is narrowed to the private mode. On Windows, where file modes mean nothing, only the directory is created.
+* @param path - The database file; not `":memory:"`, which has no file.
+* @param options - Whether the caller owns the directory, and the platform.
+* @returns One warning line naming what was narrowed, for the caller to show, or nothing when nothing was.
+* @throws Error from the file system when the directory or file cannot be created or its mode read or changed.
+*/
+const prepareDataFile = (path, options) => {
+	const directory = dirname(path);
+	if (options.platform === "win32") {
+		mkdirSync(directory, { recursive: true });
+		return [];
+	}
+	mkdirSync(directory, options.ownsDirectory ? {
+		recursive: true,
+		mode: 448
+	} : { recursive: true });
+	try {
+		closeSync(openSync(path, "wx", 384));
+	} catch (error) {
+		if (!hasCode(error, "EEXIST")) throw error;
+	}
+	if (!options.ownsDirectory) return [];
+	const narrowed = [...tighten(directory, 448) ? [directory] : [], ...storeFiles(path).filter((file) => tighten(file, 384))];
+	return narrowed.length === 0 ? [] : [`made ${narrowed.join(", ")} readable by its owner only, since other users could read the synced work in it`];
+};
+//#endregion
+export { openNodeGraphStore as i, privateDirectoryMode as n, privateFileMode as r, prepareDataFile as t };

package/dist/dist-81kTKnMq.js

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