@venn-lang/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# @venn-lang/runtime
+
+> Executes a parsed Venn document: the scheduler, the plugin registry, the event stream.
+
+`@venn-lang/core` turns source into an AST. This package walks it. It builds the registry of verbs the
+loaded plugins contribute, expands decorators, opens the scopes, runs flows and steps in the order
+the language says, and emits one ordered stream of envelopes describing what happened.
+
+It performs no I/O of its own. Every effect leaves through a port the host bound at startup, so the
+package never imports `node:*` and runs unchanged in a Web Worker. The CLI and the language server
+are both built on it.
+
+## Usage
+
+```ts
+import { createTestHost } from "@venn-lang/contracts";
+import { parse } from "@venn-lang/core";
+import { defineAction, definePlugin } from "@venn-lang/sdk";
+import { createMemorySink, createRunner } from "@venn-lang/runtime";
+
+const echo = definePlugin({
+  name: "@test/echo",
+  version: "0.0.0",
+  namespace: "test",
+  actions: [defineAction({ name: "echo", run: (_ctx, input) => ({ status: input.args[0] }) })],
+});
+
+const source = `flow "F" {
+  step "S" {
+    let res = test.echo 200
+    expect res.status == 200
+  }
+}`;
+
+const sink = createMemorySink();
+const runner = createRunner({ host: createTestHost(), plugins: [echo], sink });
+
+const result = await runner.run(parse(source).ast);
+result.passed; // 1
+sink.envelopes.map((envelope) => envelope.kind); // run.started … run.finished
+```
+
+`createRunner` negotiates plugins and wires ports once; the returned `Runner` is reused per run.
+
+## API
+
+### Running
+
+| Export | What it does |
+| --- | --- |
+| `createRunner(args)` | Builds the registry, the port resolver and the decorator source, and returns a `Runner`. Throws `VN2010` when a plugin needs a capability the host does not offer. |
+| `Runner` | `run(document)` runs every `flow` (test mode); `script(document)` executes the top-level statements top to bottom (script mode). Both return a `RunResult`. |
+| `RunnerArgs` | `host`, `plugins`, `sink`, plus optional `ports`, `uri`, `filter`, `bail`, `env`, `cleanup`, and the import-graph fields `modules`, `moduleFragments`, `moduleDecos`. |
+| `RunResult` | `run` (the run id), `passed`, `failed`, `problems` (what decorators refused before anything ran) and `exitCode` when the program called `exit`. |
+| `resolveImports(args)` | Walks the import graph from one document, parsing each `.vn` file it reaches. Returns the exported fragments and decos, every `use`d package, the loaded npm modules and the parsed modules themselves. Cycles are skipped, not looped. |
+| `collectUses(document, into)` | Adds the packages a document `use`s to a set. |
+| `ModuleIo`, `NpmModules`, `ResolvedImports` | How a host reads source (`read`, `resolve`), how it loads an installed package, and what the walk produced. |
+
+### Plugins and types
+
+| Export | What it does |
+| --- | --- |
+| `buildRegistry({ plugins, caps })` | Checks every plugin's `requires` against the host capabilities, then indexes its actions, matchers and namespace. |
+| `Registry` | Resolves `namespace.action`, a matcher by name, whether a namespace exists, the namespace a package contributes, and the full action list. |
+| `ResolvedAction`, `ResolvedMatcher` | An action or matcher paired with the plugin that owns it. |
+| `builtinDecorators` | The decorators the language ships with: `@skip`, `@only`, `@serial`, `@tags`, `@timeout`, `@retry`, `@lock`, `@flaky`. |
+| `createDecoratorSource(plugins)` | The built-ins plus every plugin decorator. A plugin's decorator of the same name wins on purpose. |
+| `createTypeCatalog(plugins)` | Turns what plugins publish (`typeDefs`, action `signature`s) into the `TypeCatalog` the checker asks. Names are qualified once here: a plugin says `Request`, a flow writes `http.Request`. |
+
+### Events
+
+| Export | What it does |
+| --- | --- |
+| `EventSink` | One method, `emit(envelope)`. The destination of the stream. |
+| `createMemorySink()` | The test double: keeps every envelope on `.envelopes`. |
+| `createNdjsonSink({ write })` | One JSON envelope per line. `write` is injected, so the sink stays neutral. |
+| `EventSinkPort` | The port descriptor, `venn.port.event-sink`, version 1. |
+| `createEmitter({ sink, run, clock })` | The single place `seq` increments and `ts` is stamped. |
+| `newRunId({ clock, random })` | Mints a run id from the host clock and random source. |
+
+### Ports, scopes and cleanup
+
+| Export | What it does |
+| --- | --- |
+| `createPortResolver({ bindings, caps })` | Resolves a `Port<T>` to the bound implementation, running capability and shape negotiation. Throws `VN7002` when nothing is bound. |
+| `PortBinding` | A port paired with the implementation a host chose. |
+| `createScope(parent?)` | A lexical scope. `lookup` falls back to the parent, `set` writes locally, `child()` nests. Bindings live in cells, so a compiled function addresses a free name once. |
+| `createCleanupList()` | The runtime's own `CleanupSink` for a host that does not bring one. `close()` runs the entries newest first and survives one that throws. |
+| `Cleanup`, `CleanupList`, `CleanupSink` | What a run registers on the way out, and who owns running it. |
+| `collectFragments(document)` | The document's `fragment` declarations, by name. |
+| `matchesTitle(title, needle)` | Case-insensitive containment. Absent needle matches everything. |
+| `RunFilter` | `tags`, `flow`, `step`: which flows and steps a run includes. |
+
+### Static checks
+
+| Export | What it does |
+| --- | --- |
+| `checkDocument(args)` | Resolves every action, matcher, fragment and `env` read in a parsed document, returning `Problem`s with source spans instead of failures mid-run. |
+| `checkImports({ document, uri, graph })` | Every imported name checked against what the named file published, with `VN2009` and a note saying whether it is private or absent. |
+| `checkFragmentCall(call, ctx)` | Reports a `fragment` invoked for a value (`VN3013`), suggesting `run name(…)`. Used inside `checkDocument`. |
+| `CheckArgs` | `document`, `registry`, `fragments`, plus optional `uri` and the `env` names `venn.toml` declares. |
+
+The codes `checkDocument` raises: `VN2003` unknown action, `VN2004` unknown matcher, `VN2005`
+unknown fragment, `VN2006` undeclared `env` variable, `VN2007` namespace used without `use`,
+`VN2008` a verb named but never called, `VN3013` a fragment called for a value, plus unknown option
+keys from the action's own parameter schema.
+
+## What the scheduler runs
+
+Test mode walks the document: suite `setup`, then one full pass per `matrix` variant, then
+`teardown`. Each pass binds `env` and the variant, runs the top-level statements, then the flows with
+`beforeEach` and `afterEach` around each one. Script mode runs the same top-level statements as the
+program itself, top to bottom, and hands `teardown` and `defer` to the host's cleanup sink, because a
+program that serves outlives its last line.
+
+Inside a flow the scheduler handles steps and groups, `if`/`else`, `forEach`, `repeat`, `while`,
+`try`/`catch`/`finally`, `run <fragment>(…)`, `defer`, `on failure`/`on success`, and the prelude
+verbs `print`, `log`, `wait`, `skip`, `fail`, `exit`.
+
+```ruby
+@tags(smoke)
+@retry(2, { backoff: 500ms, factor: 2 })
+flow "checkout" {
+  parallel { concurrency: 2 } {
+    step "cart"  { expect true }
+    step "stock" { expect true }
+  }
+}
+```
+
+`parallel` takes `concurrency` (a worker pool) and `onError: "collect"`, which lets every branch
+finish instead of cancelling the siblings at the first failure. `race` runs its branches until the
+first settles and aborts the rest; a cancelled branch stops at its next statement boundary, and an
+action that wants to be interrupted sooner listens to `ctx.signal`.
+
+Decorators run before the scheduler sees anything: what it walks is the tree expansion left, not the
+one the parser produced. `@timeout` and `@retry` wrap a flow or step body, `@lock("name")` and
+`@serial` take a named mutex from the host lock provider, `@skip` and `@only` gate what runs, and
+`@flaky(ratio)` is settled once at the end of the run so the verdict does not depend on the order
+iterations happened to fail in.
+
+## The event stream
+
+Everything a reporter or a UI shows derives from the envelope stream: `seq` is monotonic per run,
+`ts` comes from the host clock, and the kinds are `run.started`, `run.finished`, `flow.started`,
+`flow.finished`, `flow.retrying`, `step.started`, `step.finished`, `action.started`,
+`action.finished`, `expect.passed`, `expect.failed` and `log`. A failed expectation carries a whole
+`Problem`, code and span included, never a flattened string.
+
+`EventSink` is a port: `createMemorySink` and `createNdjsonSink` are its two implementations, and
+both run the same conformance suite, which pins that envelopes arrive in `seq` order.
+
+## See also
+
+- [`@venn-lang/core`](../core) parses and checks; it produces the document this package runs.
+- [`@venn-lang/sdk`](../sdk) defines the plugins, actions and matchers the registry ingests.
+- [`@venn-lang/contracts`](../contracts) supplies the `Host`, the ports and the capability negotiation.
+- [`@venn-lang/cli`](../cli) assembles a Node host and drives the runner.

package/dist/index.d.ts

@@ -0,0 +1,453 @@
+import { Call, CellEnv, DecoratorDefinition, DecoratorSource, Document, Envelope, EventData, EventKind, FragmentDecl, ImportedDeco, NodePath, Problem, RunId, TypeCatalog } from "@venn-lang/core";
+import { AnyPort, Clock, Host, HostCapability, Port, Random } from "@venn-lang/contracts";
+import { ActionDefinition, MatcherDefinition, PluginDefinition } from "@venn-lang/sdk";
+//#region src/registry/registry.types.d.ts
+/** An action together with the plugin that owns it. */
+interface ResolvedAction {
+  plugin: PluginDefinition;
+  action: ActionDefinition;
+}
+/** A matcher together with the plugin that owns it. */
+interface ResolvedMatcher {
+  plugin: PluginDefinition;
+  matcher: MatcherDefinition;
+}
+/** Resolves `namespace.action`, matchers, and namespaces from ingested plugins. */
+interface Registry {
+  action(args: {
+    namespace: string;
+    name: string;
+  }): ResolvedAction | undefined;
+  matcher(name: string): ResolvedMatcher | undefined;
+  hasNamespace(namespace: string): boolean;
+  /** The namespace a package contributes, for `use "venn/http" as h`. */
+  namespaceOf(pkg: string): string | undefined;
+  /** Every action, for binding namespaces as values in the evaluator scope. */
+  actions(): readonly {
+    namespace: string;
+    name: string;
+    action: ActionDefinition;
+  }[];
+}
+//#endregion
+//#region src/registry/build-registry.d.ts
+/**
+ * Ingest plugins after negotiating each plugin's capabilities against the host.
+ *
+ * @param args.plugins The plugins to index, in load order; later ones win a clash.
+ * @param args.caps The capabilities this host offers.
+ * @returns A registry resolving actions, matchers and namespaces.
+ * @throws VennError `VN2010` when a plugin requires a capability the host lacks.
+ */
+declare function buildRegistry(args: {
+  plugins: readonly PluginDefinition[];
+  caps: readonly HostCapability[];
+}): Registry;
+//#endregion
+//#region src/check/check.types.d.ts
+/** Inputs to a static name-resolution pass over a parsed document. */
+interface CheckArgs {
+  document: Document;
+  registry: Registry;
+  fragments: ReadonlySet<string>;
+  uri?: string;
+  /**
+   * The variables `venn.toml` declares. Omit it when they are unknown: an
+   * undeclared-variable error is only worth raising when the declaration list is
+   * trustworthy.
+   */
+  env?: readonly string[];
+}
+/** Everything a per-node check needs, resolved once per document. */
+interface CheckContext {
+  registry: Registry;
+  fragments: ReadonlySet<string>;
+  aliases: ReadonlyMap<string, string>;
+  /** Namespaces this file actually brought in with `use`. */
+  imported: ReadonlySet<string>;
+  /** Names this file binds: callable, but their methods cannot be verified. */
+  bound: ReadonlySet<string>;
+  /** Declared `env` variables, or undefined when the manifest could not be read. */
+  env?: ReadonlySet<string>;
+  uri: string;
+}
+//#endregion
+//#region src/check/check-document.d.ts
+/**
+ * Statically resolve every action, matcher and fragment reference in a parsed
+ * document. The errors the runner would otherwise raise mid-run are surfaced all
+ * at once, each with its source span.
+ *
+ * @param args Document, registry, known fragments and the declared `env` names.
+ * @returns One `Problem` per unresolved reference; empty when the document is clean.
+ */
+declare function checkDocument(args: CheckArgs): Problem[];
+//#endregion
+//#region src/check/check-fragment-call.d.ts
+/**
+ * Refuse a fragment called as though it were a function.
+ *
+ * The two look alike where they are written but are different kinds of thing: a
+ * `fn` gives back a value, a `fragment` gives back steps, and steps are recorded
+ * in the report, can fail and belong to a flow. So a fragment is invoked with
+ * `run`. `run entrar(…)` never reaches here: its target is a name, not an
+ * expression.
+ *
+ * @param call The call expression to inspect.
+ * @param ctx The document's resolved check context.
+ * @returns A `VN3013` problem, or `undefined` when the callee is not a fragment.
+ */
+declare function checkFragmentCall(call: Call, ctx: CheckContext): Problem | undefined;
+//#endregion
+//#region src/eventsink/event-sink.types.d.ts
+/** The destination of the event stream. Everything the UI shows derives from it. */
+interface EventSink {
+  emit(envelope: Envelope): void;
+}
+/** An EventSink that also retains every envelope (the test double). */
+interface MemorySink extends EventSink {
+  readonly envelopes: readonly Envelope[];
+}
+//#endregion
+//#region src/eventsink/event-sink.port.d.ts
+/**
+ * The port every run event is written to. Bound at startup by whoever assembles
+ * the host: the CLI binds NDJSON on stdout, tests bind the memory double.
+ */
+declare const EventSinkPort: Port<EventSink>;
+//#endregion
+//#region src/eventsink/memory-sink.d.ts
+/**
+ * In-memory sink (the test double): keeps every envelope for assertions.
+ *
+ * @returns A sink whose `envelopes` array grows in emission order.
+ */
+declare function createMemorySink(): MemorySink;
+//#endregion
+//#region src/eventsink/ndjson-sink.d.ts
+/**
+ * NDJSON sink: one JSON envelope per line. The `write` sink is injected (the CLI
+ * passes stdout) so this file stays neutral and needs no `node:*`.
+ *
+ * @param args.write Receives each line, newline included.
+ * @returns A sink that serialises every envelope it is given.
+ */
+declare function createNdjsonSink(args: {
+  write: (line: string) => void;
+}): EventSink;
+//#endregion
+//#region src/emit/emitter.types.d.ts
+/** The single place `seq` increments and `ts` is stamped. Handlers emit only here. */
+interface Emitter {
+  emit<K extends EventKind>(args: {
+    kind: K;
+    data: EventData[K];
+    node?: NodePath;
+  }): void;
+}
+//#endregion
+//#region src/emit/create-emitter.d.ts
+/** Build the sole emitter: it owns `seq` and stamps `ts` from the runner's clock. */
+declare function createEmitter(args: {
+  sink: EventSink;
+  run: RunId;
+  clock: Clock;
+}): Emitter;
+//#endregion
+//#region src/emit/run-id.d.ts
+/**
+ * Mint a run id from the host clock and random source, so a seeded run is
+ * reproducible. Real ULID minting comes later.
+ */
+declare function newRunId(args: {
+  clock: Clock;
+  random: Random;
+}): RunId;
+//#endregion
+//#region src/scope/scope.types.d.ts
+/**
+ * A lexical scope: the evaluator's env plus mutation and nesting.
+ *
+ * A `CellEnv`, so a closure defined here can address its free names once and
+ * read them by index afterwards instead of walking the chain per call.
+ */
+interface Scope extends CellEnv {
+  set(name: string, value: unknown): void;
+  child(): Scope;
+}
+//#endregion
+//#region src/scope/create-scope.d.ts
+/**
+ * Create a scope; `lookup` falls back to the parent, `set` writes locally.
+ *
+ * @param parent The enclosing scope, or nothing for a root scope.
+ */
+declare function createScope(parent?: Scope): Scope;
+//#endregion
+//#region src/scheduler/bind-imports.d.ts
+/** The files an import graph reached, and how one file names another. */
+interface ImportGraph {
+  modules: ReadonlyMap<string, Document>;
+  resolve: (from: string, spec: string) => string;
+  /** What each npm specifier loaded to, already a value. */
+  npm?: ReadonlyMap<string, Record<string, unknown>>;
+}
+//#endregion
+//#region src/scheduler/cleanup.types.d.ts
+/** Something a run opened, and how to give it back. */
+type Cleanup = () => Promise<void>;
+/**
+ * Where a run registers what it opened, for whoever owns the process.
+ *
+ * The runtime does not decide when a program ends: a served program ends when
+ * the machine says so, and only the host hears that. So the run says what has to
+ * happen on the way out, and the host says when.
+ */
+interface CleanupSink {
+  add(cleanup: Cleanup): unknown;
+}
+/** A sink that also runs what it collected, newest first. */
+interface CleanupList extends CleanupSink {
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/scheduler/filter.types.d.ts
+/** Which flows and steps a run includes. Absent fields mean "no restriction". */
+interface RunFilter {
+  /** Keep flows carrying at least one of these `@tags`. */
+  tags?: readonly string[];
+  /** Keep flows whose title contains this text, case-insensitively. */
+  flow?: string;
+  /** Keep steps whose title contains this text, case-insensitively. */
+  step?: string;
+}
+//#endregion
+//#region src/scheduler/collect.d.ts
+/** Index the document's fragments by name for `run`. */
+declare function collectFragments(doc: Document): Map<string, FragmentDecl>;
+//#endregion
+//#region src/scheduler/create-cleanup-list.d.ts
+/**
+ * The runtime's own sink, for a host that does not bring one.
+ *
+ * Closing runs newest first and survives a cleanup that throws: a program on its
+ * way out still has to hand back everything else it was holding.
+ */
+declare function createCleanupList(): CleanupList;
+//#endregion
+//#region src/scheduler/filter.d.ts
+/** A title matches when the needle is absent, or contained case-insensitively. */
+declare function matchesTitle(title: string, needle: string | undefined): boolean;
+//#endregion
+//#region src/check/check-imports.d.ts
+/**
+ * Check every name a file imports against what the file it names publishes.
+ * Otherwise a misspelt import stays quietly `undefined` until something calls
+ * it, and the run blames the call site rather than the import.
+ *
+ * @param args The importing document, its URI, and the resolved import graph.
+ * @returns One `VN2009` problem per name the target does not publish.
+ */
+declare function checkImports(args: {
+  document: Document;
+  uri: string;
+  graph: ImportGraph;
+}): Problem[];
+//#endregion
+//#region src/decorators/builtin-decorators.d.ts
+/**
+ * The decorators the language ships with, written the same way anyone else's
+ * are. They go through the same expansion as a plugin decorator and leave
+ * metadata on the node, because `@retry(2)` says something the grammar has no
+ * other word for. Keeping them here rather than as special cases in the
+ * scheduler is what makes the built-ins a stdlib instead of reserved words.
+ */
+declare const builtinDecorators: readonly DecoratorDefinition[];
+//#endregion
+//#region src/decorators/create-decorator-source.d.ts
+/**
+ * Every decorator this run understands: the ones the language ships with, plus
+ * whatever the loaded plugins contribute.
+ *
+ * A plugin's decorator overrides a built-in of the same name on purpose. The
+ * built-ins are a stdlib, not a reserved word list, and a project that wants its
+ * own `@retry` is entitled to it.
+ *
+ * @param plugins The plugins loaded for this run, in load order.
+ * @returns A source that looks a decorator up by name.
+ */
+declare function createDecoratorSource(plugins: readonly PluginDefinition[]): DecoratorSource;
+//#endregion
+//#region src/ports/port-resolver.types.d.ts
+/** A port paired with the implementation a host/CLI chose to bind. */
+interface PortBinding {
+  port: AnyPort;
+  impl: unknown;
+}
+/** Resolves a port descriptor to its bound, negotiated implementation. */
+interface PortResolver {
+  resolve<T>(port: Port<T>): T;
+}
+//#endregion
+//#region src/ports/create-port-resolver.d.ts
+/**
+ * Resolve ports from a set of bindings, running capability and shape negotiation
+ * at the moment of resolution.
+ *
+ * @param args.bindings Every port the host chose to bind, with its implementation.
+ * @param args.caps What this host offers, checked against each port's `requires`.
+ * @returns A resolver whose `resolve` throws `VN7002` when the port is unbound,
+ * and whatever `bindPort` raises when the capability or shape check fails.
+ */
+declare function createPortResolver(args: {
+  bindings: readonly PortBinding[];
+  caps: readonly HostCapability[];
+}): PortResolver;
+//#endregion
+//#region src/run/runner.types.d.ts
+/** What one run reports back to the host that asked for it. */
+interface RunResult {
+  run: RunId;
+  /** What the decorators refused before a statement ran. */
+  problems?: Problem[];
+  passed: number;
+  failed: number;
+  /**
+   * What `exit` asked the host to end with, absent if nothing called it. It
+   * overrides the tally on purpose: `exit 0` is a clean ending, `exit 3` is a
+   * failure the program named itself.
+   */
+  exitCode?: number;
+}
+/** The level-2 embedding API (§18): a host owns the process and drives runs. */
+interface Runner {
+  /** Test mode: collect and run every `flow`, reporting each. */
+  run(document: Document): Promise<RunResult>;
+  /** Script mode: execute the file's top-level statements, top to bottom. */
+  script(document: Document): Promise<RunResult>;
+}
+/** Everything {@link Runner} needs, settled once and reused for every run. */
+interface RunnerArgs {
+  host: Host;
+  plugins: readonly PluginDefinition[];
+  sink: EventSink;
+  ports?: readonly PortBinding[];
+  uri?: string;
+  /** Which flows and steps to include (`--tags`, `--flow`, `--step`). */
+  filter?: RunFilter;
+  /** Stop after the first flow that fails. */
+  bail?: boolean;
+  env?: Record<string, unknown>;
+  moduleFragments?: Map<string, FragmentDecl>;
+  /**
+   * The files the import graph reached, so a `pub fn` can be called with the
+   * module it was written in around it. Without this the name resolves and the
+   * call fails on its first line.
+   */
+  modules?: ImportGraph;
+  /** The `pub deco`s the imported files exported, so `@name` resolves across a file. */
+  moduleDecos?: Map<string, ImportedDeco>;
+  /**
+   * Where a script-mode program registers what it opened. The host owns when a
+   * program ends, so the host owns this list; without one the run keeps its own
+   * and nothing closes until the process does.
+   */
+  cleanup?: CleanupSink;
+}
+//#endregion
+//#region src/run/create-runner.d.ts
+/**
+ * Build a runner: negotiate plugins and wire ports once, then reuse them for
+ * every run.
+ *
+ * @param args The host, the plugins, the event sink and the per-run options.
+ * @returns A runner exposing test mode (`run`) and script mode (`script`).
+ * @throws VennError `VN2010` when a plugin requires a capability the host lacks.
+ */
+declare function createRunner(args: RunnerArgs): Runner;
+//#endregion
+//#region src/run/resolve-imports.d.ts
+/** Read source by URI and resolve a specifier relative to a base URI. */
+interface ModuleIo {
+  read: (uri: string) => Promise<string>;
+  resolve: (base: string, spec: string) => string;
+}
+/**
+ * Loading a package that was installed rather than written here.
+ *
+ * Kept apart from {@link ModuleIo} because the two answer different questions:
+ * one reads `.vn` source to be parsed, the other hands back a module that is
+ * already a value. A host without one simply has no packages, which is the state
+ * of every run in a Web Worker and not an error.
+ */
+interface NpmModules {
+  load(spec: string): Promise<Record<string, unknown> | undefined>;
+}
+/** What a run needs from the files it reaches: their fragments, decos and plugins. */
+interface ResolvedImports {
+  fragments: Map<string, FragmentDecl>;
+  /** The `pub deco`s reachable through the import graph, with the file each came from. */
+  decos: Map<string, ImportedDeco>;
+  /** Every package `use`d anywhere in the graph, so only those need loading. */
+  packages: Set<string>;
+  /**
+   * What each npm specifier loaded to, by the name that was written.
+   *
+   * Loaded here, before anything runs, because binding a scope cannot wait: by
+   * the time a name is looked up the module has to already be a value.
+   */
+  npm: Map<string, Record<string, unknown>>;
+  /**
+   * Every module reached, parsed, keyed by its resolved URI.
+   *
+   * Carried whole rather than reduced to a list of exported names, because a
+   * `pub fn` is a closure over the file it was written in: it calls that file's
+   * private helpers and reads that file's globals. Handing over the function
+   * without the place it came from produces something that resolves and then
+   * fails on its first line.
+   */
+  modules: Map<string, Document>;
+}
+/**
+ * Walk the import graph from one document, parsing every `.vn` file it reaches
+ * and loading every package it names. A file already seen is skipped, so a cycle
+ * ends rather than loops. A file that cannot be read is skipped in silence:
+ * whoever tried to read it reports the failure.
+ *
+ * @param args The entry document, its URI, the source reader and the optional
+ * package loader.
+ * @returns The exported fragments and decos, the packages, the loaded npm
+ * modules and every parsed document, keyed by resolved URI.
+ */
+declare function resolveImports(args: {
+  document: Document;
+  uri: string;
+  io: ModuleIo;
+  /** Absent when the host has no way to load one: a Worker, most tests. */
+  npm?: NpmModules;
+}): Promise<ResolvedImports>;
+/**
+ * Add the packages a file declares with `use` to `into`. Collected across the
+ * whole graph: a fragment imported from elsewhere calls the verbs *its* file
+ * asked for.
+ *
+ * @param document The file to read `use` declarations from.
+ * @param into The accumulating set of package specifiers, mutated in place.
+ */
+declare function collectUses(document: Document, into: Set<string>): void;
+//#endregion
+//#region src/types/create-type-catalog.d.ts
+/**
+ * Turn what the loaded plugins publish into what the checker can ask.
+ *
+ * This is the seam the core deliberately does not cross: `@venn-lang/core` knows
+ * nothing about plugins and gets told. Names are qualified here, once: a plugin
+ * says `Request` and a flow writes `http.Request`.
+ *
+ * @param plugins The plugins loaded for this run.
+ * @returns A catalog answering a type name or an action's signature.
+ */
+declare function createTypeCatalog(plugins: readonly PluginDefinition[]): TypeCatalog;
+//#endregion
+export { type CheckArgs, type Cleanup, type CleanupList, type CleanupSink, type Emitter, type EventSink, EventSinkPort, type MemorySink, type ModuleIo, type NpmModules, type PortBinding, type PortResolver, type Registry, type ResolvedAction, type ResolvedImports, type ResolvedMatcher, type RunFilter, type RunResult, type Runner, type RunnerArgs, type Scope, buildRegistry, builtinDecorators, checkDocument, checkFragmentCall, checkImports, collectFragments, collectUses, createCleanupList, createDecoratorSource, createEmitter, createMemorySink, createNdjsonSink, createPortResolver, createRunner, createScope, createTypeCatalog, matchesTitle, newRunId, resolveImports };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/registry/registry.types.ts","../src/registry/build-registry.ts","../src/check/check.types.ts","../src/check/check-document.ts","../src/check/check-fragment-call.ts","../src/eventsink/event-sink.types.ts","../src/eventsink/event-sink.port.ts","../src/eventsink/memory-sink.ts","../src/eventsink/ndjson-sink.ts","../src/emit/emitter.types.ts","../src/emit/create-emitter.ts","../src/emit/run-id.ts","../src/scope/scope.types.ts","../src/scope/create-scope.ts","../src/scheduler/bind-imports.ts","../src/scheduler/cleanup.types.ts","../src/scheduler/filter.types.ts","../src/scheduler/collect.ts","../src/scheduler/create-cleanup-list.ts","../src/scheduler/filter.ts","../src/check/check-imports.ts","../src/decorators/builtin-decorators.ts","../src/decorators/create-decorator-source.ts","../src/ports/port-resolver.types.ts","../src/ports/create-port-resolver.ts","../src/run/runner.types.ts","../src/run/create-runner.ts","../src/run/resolve-imports.ts","../src/types/create-type-catalog.ts"],"mappings":";;;;;UAGiB;EACf,QAAQ;EACR,QAAQ;;;UAIO;EACf,QAAQ;EACR,SAAS;;;UAIM;EACf,OAAO;IAAQ;IAAmB;MAAiB;EACnD,QAAQ,eAAe;EACvB,aAAa;;EAEb,YAAY;;EAEZ;IAAsB;IAAmB;IAAc,QAAQ;;;;;;;;;;;;;iBCVjD,cAAc;EAC5B,kBAAkB;EAClB,eAAe;IACb;;;;UCXa;EACf,UAAU;EACV,UAAU;EACV,WAAW;EACX;;;;;;EAMA;;;UAIe;EACf,UAAU;EACV,WAAW;EACX,SAAS;;EAET,UAAU;;EAEV,OAAO;;EAEP,MAAM;EACN;;;;;;;;;;;;iBCSc,cAAc,MAAM,YAAY;;;;;;;;;;;;;;;;iBCpBhC,kBAAkB,MAAM,MAAM,KAAK,eAAe;;;;UCdjD;EACf,KAAK,UAAU;;;UAIA,mBAAmB;WACzB,oBAAoB;;;;;;;;cCFlB,eAAe,KAAK;;;;;;;;iBCCjB,oBAAoB;;;;;;;;;;iBCCpB,iBAAiB;EAAQ,QAAQ;IAA0B;;;;UCN1D;EACf,KAAK,UAAU,WAAW;IAAQ,MAAM;IAAG,MAAM,UAAU;IAAI,OAAO;;;;;;iBCExD,cAAc;EAAQ,MAAM;EAAW,KAAK;EAAO,OAAO;IAAU;;;;;;;iBCCpE,SAAS;EAAQ,OAAO;EAAO,QAAQ;IAAW;;;;;;;;;UCCjD,cAAc;EAC7B,IAAI,cAAc;EAClB,SAAS;;;;;;;;;iBCsDK,YAAY,SAAS,QAAQ;;;;UCrD5B;EACf,SAAS,oBAAoB;EAC7B,UAAU,cAAc;;EAExB,MAAM,oBAAoB;;;;;KCdhB,gBAAgB;;;;;;;;UASX;EACf,IAAI,SAAS;;;UAIE,oBAAoB;EACnC,SAAS;;;;;UCfM;;EAEf;;EAEA;;EAEA;;;;;iBCac,iBAAiB,KAAK,WAAW,YAAY;;;;;;;;;iBCZ7C,qBAAqB;;;;iBCPrB,aAAa,eAAe;;;;;;;;;;;iBCqB5B,aAAa;EAC3B,UAAU;EACV;EACA,OAAO;IACL;;;;;;;;;;cCbS,4BAA4B;;;;;;;;;;;;;;iBCEzB,sBAAsB,kBAAkB,qBAAqB;;;;UCZ5D;EACf,MAAM;EACN;;;UAIe;EACf,QAAQ,GAAG,MAAM,KAAK,KAAK;;;;;;;;;;;;;iBCEb,mBAAmB;EACjC,mBAAmB;EACnB,eAAe;IACb;;;;UCNa;EACf,KAAK;;EAEL,WAAW;EACX;EACA;;;;;;EAMA;;;UAIe;;EAEf,IAAI,UAAU,WAAW,QAAQ;;EAEjC,OAAO,UAAU,WAAW,QAAQ;;;UAIrB;EACf,MAAM;EACN,kBAAkB;EAClB,MAAM;EACN,iBAAiB;EACjB;;EAEA,SAAS;;EAET;EACA,MAAM;EACN,kBAAkB,YAAY;;;;;;EAM9B,UAAU;;EAEV,cAAc,YAAY;;;;;;EAM1B,UAAU;;;;;;;;;;;;iBCzBI,aAAa,MAAM,aAAa;;;;UCnB/B;EACf,OAAO,gBAAgB;EACvB,UAAU,cAAc;;;;;;;;;;UAWT;EACf,KAAK,eAAe,QAAQ;;;UAIb;EACf,WAAW,YAAY;;EAEvB,OAAO,YAAY;;EAEnB,UAAU;;;;;;;EAOV,KAAK,YAAY;;;;;;;;;;EAUjB,SAAS,YAAY;;;;;;;;;;;;;iBAcD,eAAe;EACnC,UAAU;EACV;EACA,IAAI;;EAEJ,MAAM;IACJ,QAAQ;;;;;;;;;iBA4BI,YAAY,UAAU,UAAU,MAAM;;;;;;;;;;;;;iBCjFtC,kBAAkB,kBAAkB,qBAAqB"}