process-graph 1.2.0 → 1.4.0

package/README.md

@@ -40,24 +40,27 @@ 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, each projected view as Mermaid, DOT or JSON text (`viewText`), 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/sync`                 | `syncScopes`: syncs sources into a store page by page, relations included, resumable from a checkpoint and narrowed by a typed filter.                                                                                                            | Browser, Worker, Node |
+| `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                                                            |
 | ------------------- | ---------------------------------------------------------------------------- |
@@ -67,12 +70,14 @@ The package is built from the repository's internal packages, which are bundled
 | `store/node`        | `drizzle-orm`                                                                |
 | `store/wasm`        | `@orpc/client`                                                               |
 | `store/wasm/worker` | `@orpc/contract`, `@orpc/server`, `drizzle-orm`, `@sqlite.org/sqlite-wasm`   |
+| `sync`              | `@orpc/client`                                                               |
 | `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:
 
@@ -117,7 +122,7 @@ Run without them, the bin starts nothing: it names the missing peers and the com
 
 ## What is exported, and under which name
 
-The root entry exports the model, projection and domain layers flat, under their own names, and the DAG layer as the namespace `dag`, in its entirety: `dag.buildDag`, `dag.topologicalLayers`, `dag.criticalPath`, `dag.CycleError` and the rest. The DAG layer is namespaced because its `criticalPath` has the same name as the domain's, which answers a different question (the heaviest chain through the work still ahead of a run, not through a bare node set). The whole layer is namespaced rather than only the colliding name, so a name added to a layer later cannot start colliding silently.
+The root entry exports the model, projection, export and domain layers flat, under their own names, and the DAG layer as the namespace `dag`, in its entirety: `dag.buildDag`, `dag.topologicalLayers`, `dag.criticalPath`, `dag.CycleError` and the rest. The DAG layer is namespaced because its `criticalPath` has the same name as the domain's, which answers a different question (the heaviest chain through the work still ahead of a run, not through a bare node set). The whole layer is namespaced rather than only the colliding name, so a name added to a layer later cannot start colliding silently.
 
 - A name is never shadowed. Two layers exporting the same name on one entry point is a compile error, and the unit tests compare each entry point's runtime exports with the layers it carries.
 - Types follow the same rule as values: a model, projection or domain type is a flat import, a DAG type is `dag.Dag` and so on.

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-DMNBcTZ-.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-Cw63tKU9.js");
+	const { runProcess } = await import("./dist-DipyhCvb.js");
 	process.exitCode = await runProcess({
 		name: "process-graph",
-		version: packageVersion(manifest)
+		version
 	});
 }
 //#endregion

package/dist/cli.d.ts

@@ -1,9 +1,12 @@
-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 { 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 { 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, S as Element, _ as Model, o as Overlay, q as OpenIds, x as ArtefactDef } from "./index-Dvz_I_uQ.js";
+import { P as SyncFilter, b as Gap, h as GraphSourceClient } from "./index-Cs1CWlEg.js";
+import { ut as GraphStoreClient } from "./index-CR8xUK3S.js";
+import { n as GraphqlFetch, t as GitHubTokenPort } from "./graphql-3DSUSUvL.js";
+import "./index-Cp5selgs.js";
+import { F as Handoff, N as Flowchart, k as Swimlane, w as StateMachine, y as SequenceDiagram } from "./index-4f4PVH7K.js";
+import { n as SourceLookup } from "./index-DoMIav3D.js";
+import { a as flowchartToMermaid, c as swimlaneToMermaid, i as swimlaneToDot, n as sequenceToDot, o as sequenceToMermaid, r as stateMachineToDot, s as stateMachineToMermaid, t as flowchartToDot } from "./index-Bb90VKMc.js";
 import { ComputedValue } from "trilean";
 //#region ../graph-cli/dist/exit-codes.d.ts
 /**
@@ -118,6 +121,10 @@ 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. */
@@ -150,7 +157,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.
  */
@@ -259,6 +266,22 @@ interface WhyResult {
   /** The element, then every unfinished need reached from it, in model order. */
   readonly chain: readonly WhyLink[];
 }
+/** An element of a hierarchy walk, with how many `child-of` relations away it is. */
+interface HierarchyLink extends ElementSummary {
+  readonly distance: number;
+}
+/** An element's sub-tasks: the elements related to it by `child-of`. */
+interface ChildrenResult {
+  readonly element: ElementSummary;
+  /** Its direct children, in model order. */
+  readonly children: readonly ElementSummary[];
+}
+/** What an element is a sub-task of, up to the top of its hierarchy. */
+interface AncestorsResult {
+  readonly element: ElementSummary;
+  /** Its parent, its parent's parent and so on, nearest first, each once with the fewest relations it takes to reach it. */
+  readonly ancestors: readonly HierarchyLink[];
+}
 /**
  * The elements that are ready: not done, with every live need done.
  * @param session - The store, model and facts.
@@ -297,13 +320,27 @@ export declare const handoffsOf: (session: GraphSession) => Promise<HandoffsResu
  * @param id - The element asked about.
  */
 export declare const why: (session: GraphSession, id: string) => Promise<WhyResult>;
+/**
+ * An element's direct sub-tasks, from the `child-of` relations a sync keeps, as the store's hierarchy query answers.
+ * @param session - The store and model.
+ * @param id - The element asked about.
+ * @throws CliError with `notFound` when the model or the element does not exist.
+ */
+export declare const children: (session: GraphSession, id: string) => Promise<ChildrenResult>;
+/**
+ * The elements an element is a sub-task of, nearest first, from the `child-of` relations a sync keeps, as the store's hierarchy query answers.
+ * @param session - The store and model.
+ * @param id - The element asked about.
+ * @throws CliError with `notFound` when the model or the element does not exist.
+ */
+export declare const ancestors: (session: GraphSession, id: string) => Promise<AncestorsResult>;
 //#endregion
 //#region ../graph-cli/dist/show.d.ts
 /** The views `show` draws, as named on the command line. */
 export declare const viewNames: readonly ["flowchart", "swimlane", "state", "sequence"];
 /** One of the views `show` draws. */
 type ViewName = (typeof viewNames)[number];
-/** The formats `show` writes. */
+/** The formats `show` writes, graph-export's, with JSON named first. */
 export declare const formatNames: readonly ["json", "mermaid", "dot"];
 /** One of the formats `show` writes. */
 type FormatName = (typeof formatNames)[number];
@@ -344,13 +381,13 @@ type ShowResult = ProjectedView & {
  */
 export declare const project: (model: Model<OpenIds>, request: Pick<ShowRequest, "view" | "subject" | "scenario">) => ProjectedView;
 /**
- * Writes a projected view as Mermaid or DOT source.
+ * Writes a projected view as Mermaid or DOT source, or as JSON, through graph-export's `viewText`, the writer the web app's downloads use too.
  * @param model - The model, for participant labels.
  * @param projected - The view.
- * @param format - `mermaid` or `dot`.
- * @returns The diagram source.
+ * @param format - `mermaid`, `dot` or `json`.
+ * @returns The text.
  */
-export declare const emit: (model: Model<OpenIds>, projected: ProjectedView, format: Exclude<FormatName, "json">) => string;
+export declare const emit: (model: Model<OpenIds>, projected: ProjectedView, format: FormatName) => string;
 /**
  * Draws the session's model as a view in a format.
  * @param session - The store and model.
@@ -476,91 +513,66 @@ export declare const validateStored: (session: GraphSession) => Promise<Validate
 export declare const validateDocument: (text: string) => ValidateResult;
 //#endregion
 //#region ../graph-cli/dist/sync.d.ts
-/** Finds the source that serves scopes with an identifier prefix, such as `github`. */
-type SourceLookup = (prefix: string) => GraphSourceClient | undefined;
 /** What to sync. */
 interface SyncRequest {
   /** Source-qualified scope identifiers, such as `github:owner` or `github:owner/repo`, read in order. */
   readonly scopes: readonly string[];
-  /** A cursor from an interrupted sync: the first source's sync continues after it. */
+  /** A cursor from an interrupted sync: the first source's sync continues after it. It is valid only with the filter it was issued under. */
   readonly after?: string;
+  /** Narrows and orders what each scope lists, on the source's side. */
+  readonly filter?: SyncFilter;
+}
+/** 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 and the sync's filter, 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, under the same filter, 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;
-  /** The revision the write took. */
+  /** The revision the last write took. */
   readonly revision: number;
-  /** The participants, activities and transitions written, each identifier counted once. */
+  /** The participants, activities, transitions and relations written, each counted once. */
   readonly participants: number;
   readonly activities: number;
   readonly transitions: number;
+  readonly relations: number;
   /** The parts of the scope the sources could not read, in the order they were met. */
   readonly gaps: readonly Gap[];
 }
 /**
- * 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.
+ * Reads every page of the scopes from their sources and merges each into the session's model as it is read, creating the model when the store has none: participants, bound activities, transitions, relations (sub-issues, assignees, repository membership) and run state. 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 already 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.
+ * @param request - The scopes, a cursor to resume after, and a filter.
  * @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
-//#region ../graph-cli/dist/emit/mermaid.d.ts
-/**
- * A flowchart as a Mermaid `flowchart`, top to bottom. Nodes are declared in the view's order, then edges, each with its guard as the edge label.
- * @param view - The projected flowchart.
- * @returns Mermaid source, ending with a line break.
- */
-export declare const flowchartToMermaid: <I extends IdSpace>(view: Flowchart<I>) => string;
-/**
- * A swimlane as a Mermaid `flowchart`, left to right, with one subgraph per lane in the view's lane order (an empty lane is an empty subgraph, so it stays visible) and nodes with no actor outside every lane. Hand-offs, the edges that change lane, are drawn thick.
- * @param view - The projected swimlane.
- * @returns Mermaid source, ending with a line break.
- */
-export declare const swimlaneToMermaid: <I extends IdSpace>(view: Swimlane<I>) => string;
-/**
- * A state machine as a Mermaid `stateDiagram-v2`. Initial and final pseudo-states are Mermaid's `[*]`; every other state is declared with its label. Each transition carries its event, guard and effect.
- * @param view - The projected state machine.
- * @returns Mermaid source, ending with a line break.
- */
-export declare const stateMachineToMermaid: <I extends IdSpace>(view: StateMachine<I>) => string;
-/**
- * A sequence diagram as a Mermaid `sequenceDiagram`. Lifelines are declared in order of first appearance, labelled through `participantLabel`; messages follow in scenario order, wrapped in the fragments the projection drew (`alt` operands separated by `else`, `par` operands by `and`), each operand headed by its guard.
- * @param view - The projected sequence diagram.
- * @param participantLabel - The label of a lifeline's participant.
- * @returns Mermaid source, ending with a line break.
- */
-export declare const sequenceToMermaid: <I extends IdSpace>(view: SequenceDiagram<I>, participantLabel: (participant: I["actor"]) => string) => string;
-//#endregion
-//#region ../graph-cli/dist/emit/dot.d.ts
-/**
- * A flowchart as a Graphviz `digraph`, top to bottom. Nodes are named by their model identifiers, so the DOT source reads back to the model directly.
- * @param view - The projected flowchart.
- * @returns DOT source, ending with a line break.
- */
-export declare const flowchartToDot: <I extends IdSpace>(view: Flowchart<I>) => string;
-/**
- * A swimlane as a Graphviz `digraph`, left to right, with one `cluster` subgraph per lane in the view's lane order and nodes with no actor outside every lane. An empty lane holds one invisible point so Graphviz still draws it. Hand-offs, the edges that change lane, are drawn bold.
- * @param view - The projected swimlane.
- * @returns DOT source, ending with a line break.
- */
-export declare const swimlaneToDot: <I extends IdSpace>(view: Swimlane<I>) => string;
-/**
- * A state machine as a Graphviz `digraph`, left to right. Each transition is labelled with its event, guard and effect.
- * @param view - The projected state machine.
- * @returns DOT source, ending with a line break.
- */
-export declare const stateMachineToDot: <I extends IdSpace>(view: StateMachine<I>) => string;
-/**
- * A sequence diagram as a Graphviz `digraph`. DOT has no sequence notation, so the diagram is drawn as a grid: a column per lifeline, headed by its participant's label, with one row per message in scenario order. Each message is an arrow across its row, numbered by its step and prefixed with the fragments around it (operator and guard, outermost first), since DOT cannot draw a box around arrows.
- * @param view - The projected sequence diagram.
- * @param participantLabel - The label of a lifeline's participant.
- * @returns DOT source, ending with a line break.
- */
-export declare const sequenceToDot: <I extends IdSpace>(view: SequenceDiagram<I>, participantLabel: (participant: I["actor"]) => string) => string;
+//#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, SyncRequest, SyncResult, ValidateResult, ValidationIssue, ViewName, WhyLink, WhyResult, Written };
+export { type Addition, type AncestorsResult, type ArtefactState, type BlockedResult, type ChildrenResult, type CliPorts, type CyclesResult, type ElementStatus, type ElementSummary, type ExitCode, type FactsResult, type Failure, type FormatName, type GraphSession, type HandoffsResult, type HierarchyLink, type ImpactResult, type NodePortsOptions, type OpenedStore, type PathResult, type ProgramIdentity, type ProjectedView, type ReadyResult, type SetArtefactResult, type SetFactResult, type SetResult, type ShowRequest, type ShowResult, type SourceLookup, type StoredRun, type SyncInterruption, type SyncRequest, type SyncResult, type ValidateResult, type ValidationIssue, type ViewName, type WhyLink, type WhyResult, type Written, flowchartToDot, flowchartToMermaid, sequenceToDot, sequenceToMermaid, stateMachineToDot, stateMachineToMermaid, swimlaneToDot, swimlaneToMermaid };

package/dist/cli.js

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