@venn-lang/runtime 0.1.0

package/src/decorators/builtin-decorators.ts

@@ -0,0 +1,87 @@
+import type { DecoratorDefinition, ExpandContext } from "@venn-lang/core";
+import type { RetrySpec } from "../scheduler/annotations.js";
+
+/** Where each of these may sit. Named once, so a wrong target is caught, not ignored. */
+const RUNNABLE = ["FlowDecl", "StepDecl", "GroupDecl"] as const;
+
+/**
+ * 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.
+ */
+export const builtinDecorators: readonly DecoratorDefinition[] = [
+  flag("skip", "Do not run this."),
+  flag("only", "Run this and nothing beside it."),
+  flag("serial", "Never run this alongside another flow."),
+  {
+    name: "tags",
+    doc: "Label this for `--tags`.",
+    targets: [...RUNNABLE],
+    expand: (ctx) =>
+      ctx.meta(
+        "tags",
+        ctx.args.map(String).filter((tag) => tag !== ""),
+      ),
+  },
+  {
+    name: "timeout",
+    doc: "Give up after this long.",
+    targets: [...RUNNABLE],
+    expand: (ctx) => ctx.meta("timeout", durationMs(ctx.args[0])),
+  },
+  {
+    name: "retry",
+    doc: "Run again on failure, up to n times.",
+    targets: [...RUNNABLE],
+    expand: (ctx) => ctx.meta("retry", retryOf(ctx)),
+  },
+  {
+    name: "lock",
+    doc: "Hold this name for the duration; nothing else holding it runs.",
+    targets: [...RUNNABLE],
+    expand: (ctx) => ctx.meta("lock", ctx.args[0] === undefined ? undefined : String(ctx.args[0])),
+  },
+  {
+    name: "flaky",
+    doc: "Tolerate failures up to this ratio.",
+    targets: [...RUNNABLE],
+    expand: (ctx) => ctx.meta("flaky", ratioOf(ctx.args[0])),
+  },
+];
+
+/** A decorator with nothing to say beyond having been written. */
+function flag(name: string, doc: string): DecoratorDefinition {
+  return {
+    name,
+    doc,
+    targets: [...RUNNABLE],
+    expand: (ctx) => ctx.meta(name, true),
+  };
+}
+
+function retryOf(ctx: ExpandContext): RetrySpec {
+  const opts = asRecord(ctx.args[1]);
+  return {
+    attempts: Math.max(0, Math.floor(Number(ctx.args[0]) || 0)),
+    backoffMs: durationMs(opts.backoff) ?? 0,
+    factor: Number(opts.factor ?? 1) || 1,
+  };
+}
+
+/** A bare `@flaky` tolerates everything; a number is the ratio it tolerates. */
+function ratioOf(value: unknown): number {
+  if (value === undefined) return 1;
+  return typeof value === "number" ? value : 0;
+}
+
+function durationMs(value: unknown): number | undefined {
+  if (typeof value === "number") return value;
+  const duration = value as { kind?: string; ms?: number };
+  return duration?.kind === "duration" ? duration.ms : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : {};
+}

package/src/decorators/create-decorator-source.ts

@@ -0,0 +1,25 @@
+import type { DecoratorDefinition, DecoratorSource } from "@venn-lang/core";
+import type { PluginDefinition } from "@venn-lang/sdk";
+import { builtinDecorators } from "./builtin-decorators.js";
+
+/**
+ * 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.
+ */
+export function createDecoratorSource(plugins: readonly PluginDefinition[]): DecoratorSource {
+  const byName = new Map<string, DecoratorDefinition>();
+  for (const decorator of builtinDecorators) byName.set(decorator.name, decorator);
+  for (const plugin of plugins) {
+    for (const decorator of plugin.decorators ?? []) {
+      byName.set(decorator.name, decorator as DecoratorDefinition);
+    }
+  }
+  return { get: (name) => byName.get(name) };
+}

package/src/decorators/index.ts

@@ -0,0 +1,2 @@
+export { builtinDecorators } from "./builtin-decorators.js";
+export { createDecoratorSource } from "./create-decorator-source.js";

package/src/emit/create-emitter.ts

@@ -0,0 +1,16 @@
+import type { Clock } from "@venn-lang/contracts";
+import type { Envelope, RunId } from "@venn-lang/core";
+import type { EventSink } from "../eventsink/index.js";
+import type { Emitter } from "./emitter.types.js";
+
+/** Build the sole emitter: it owns `seq` and stamps `ts` from the runner's clock. */
+export function createEmitter(args: { sink: EventSink; run: RunId; clock: Clock }): Emitter {
+  let seq = 0;
+  return {
+    emit: ({ kind, data, node }) => {
+      seq += 1;
+      const ts = new Date(args.clock.now()).toISOString();
+      args.sink.emit({ seq, ts, run: args.run, kind, node, data } as Envelope);
+    },
+  };
+}

package/src/emit/emitter.types.ts

@@ -0,0 +1,6 @@
+import type { EventData, EventKind, NodePath } from "@venn-lang/core";
+
+/** The single place `seq` increments and `ts` is stamped. Handlers emit only here. */
+export interface Emitter {
+  emit<K extends EventKind>(args: { kind: K; data: EventData[K]; node?: NodePath }): void;
+}

package/src/emit/index.ts

@@ -0,0 +1,3 @@
+export { createEmitter } from "./create-emitter.js";
+export type { Emitter } from "./emitter.types.js";
+export { newRunId } from "./run-id.js";

package/src/emit/run-id.ts

@@ -0,0 +1,11 @@
+import type { Clock, Random } from "@venn-lang/contracts";
+import type { RunId } from "@venn-lang/core";
+
+/**
+ * Mint a run id from the host clock and random source, so a seeded run is
+ * reproducible. Real ULID minting comes later.
+ */
+export function newRunId(args: { clock: Clock; random: Random }): RunId {
+  const rand = Math.floor(args.random.next() * 1e9).toString(36);
+  return `run-${args.clock.now().toString(36)}-${rand}` as RunId;
+}

package/src/eventsink/event-sink.port.ts

@@ -0,0 +1,13 @@
+import type { Port } from "@venn-lang/contracts";
+import type { EventSink } from "./event-sink.types.js";
+
+/**
+ * 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.
+ */
+export const EventSinkPort: Port<EventSink> = {
+  id: "venn.port.event-sink",
+  version: 1,
+  requires: [],
+  methods: ["emit"],
+};

package/src/eventsink/event-sink.types.ts

@@ -0,0 +1,11 @@
+import type { Envelope } from "@venn-lang/core";
+
+/** The destination of the event stream. Everything the UI shows derives from it. */
+export interface EventSink {
+  emit(envelope: Envelope): void;
+}
+
+/** An EventSink that also retains every envelope (the test double). */
+export interface MemorySink extends EventSink {
+  readonly envelopes: readonly Envelope[];
+}

package/src/eventsink/index.ts

@@ -0,0 +1,4 @@
+export { EventSinkPort } from "./event-sink.port.js";
+export type { EventSink, MemorySink } from "./event-sink.types.js";
+export { createMemorySink } from "./memory-sink.js";
+export { createNdjsonSink } from "./ndjson-sink.js";

package/src/eventsink/memory-sink.ts

@@ -0,0 +1,17 @@
+import type { Envelope } from "@venn-lang/core";
+import type { MemorySink } from "./event-sink.types.js";
+
+/**
+ * In-memory sink (the test double): keeps every envelope for assertions.
+ *
+ * @returns A sink whose `envelopes` array grows in emission order.
+ */
+export function createMemorySink(): MemorySink {
+  const envelopes: Envelope[] = [];
+  return {
+    envelopes,
+    emit: (envelope) => {
+      envelopes.push(envelope);
+    },
+  };
+}

package/src/eventsink/ndjson-sink.ts

@@ -0,0 +1,14 @@
+import type { EventSink } from "./event-sink.types.js";
+
+/**
+ * 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.
+ */
+export function createNdjsonSink(args: { write: (line: string) => void }): EventSink {
+  return {
+    emit: (envelope) => args.write(`${JSON.stringify(envelope)}\n`),
+  };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// @venn-lang/runtime: the registry and the sequential runner. Depends only on core,
+// contracts and sdk (types); no concrete node impls, no `node:*`.
+
+export * from "./check/index.js";
+export * from "./decorators/index.js";
+export * from "./emit/index.js";
+export * from "./eventsink/index.js";
+export * from "./ports/index.js";
+export * from "./registry/index.js";
+export * from "./run/index.js";
+export type { Cleanup, CleanupList, CleanupSink, RunFilter } from "./scheduler/index.js";
+export { collectFragments, createCleanupList, matchesTitle } from "./scheduler/index.js";
+export * from "./scope/index.js";
+export * from "./types/index.js";

package/src/ports/create-port-resolver.ts

@@ -0,0 +1,39 @@
+import { bindPort, type HostCapability, type Port, VennError } from "@venn-lang/contracts";
+import type { PortBinding, PortResolver } from "./port-resolver.types.js";
+
+/**
+ * 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.
+ */
+export function createPortResolver(args: {
+  bindings: readonly PortBinding[];
+  caps: readonly HostCapability[];
+}): PortResolver {
+  const byId = new Map(args.bindings.map((binding) => [binding.port.id, binding] as const));
+  return {
+    resolve: <T>(port: Port<T>): T =>
+      resolveOne({ port, binding: byId.get(port.id), caps: args.caps }),
+  };
+}
+
+function resolveOne<T>(args: {
+  port: Port<T>;
+  binding: PortBinding | undefined;
+  caps: readonly HostCapability[];
+}): T {
+  if (!args.binding) throw unbound(args.port.id);
+  return bindPort({ port: args.port, impl: args.binding.impl, caps: args.caps });
+}
+
+function unbound(id: string): VennError {
+  return new VennError({
+    code: "VN7002",
+    message: `No implementation bound for port "${id}".`,
+    detail: { port: id },
+  });
+}

package/src/ports/index.ts

@@ -0,0 +1,2 @@
+export { createPortResolver } from "./create-port-resolver.js";
+export type { PortBinding, PortResolver } from "./port-resolver.types.js";

package/src/ports/port-resolver.types.ts

@@ -0,0 +1,12 @@
+import type { AnyPort, Port } from "@venn-lang/contracts";
+
+/** A port paired with the implementation a host/CLI chose to bind. */
+export interface PortBinding {
+  port: AnyPort;
+  impl: unknown;
+}
+
+/** Resolves a port descriptor to its bound, negotiated implementation. */
+export interface PortResolver {
+  resolve<T>(port: Port<T>): T;
+}

package/src/registry/build-registry.ts

@@ -0,0 +1,76 @@
+import { type HostCapability, missingCapabilities, VennError } from "@venn-lang/contracts";
+import type { ActionDefinition, PluginDefinition } from "@venn-lang/sdk";
+import type { Registry, ResolvedAction, ResolvedMatcher } from "./registry.types.js";
+
+/**
+ * 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.
+ */
+export function buildRegistry(args: {
+  plugins: readonly PluginDefinition[];
+  caps: readonly HostCapability[];
+}): Registry {
+  for (const plugin of args.plugins) assertPluginCaps({ plugin, caps: args.caps });
+  return indexPlugins(args.plugins);
+}
+
+function assertPluginCaps(args: {
+  plugin: PluginDefinition;
+  caps: readonly HostCapability[];
+}): void {
+  const missing = missingCapabilities({ requires: args.plugin.requires ?? [], caps: args.caps });
+  if (missing.length === 0) return;
+  const list = missing.map((cap) => `"${cap}"`).join(", ");
+  throw new VennError({
+    code: "VN2010",
+    message: `Plugin "${args.plugin.name}" requires capability ${list}, absent from this host.`,
+    detail: { plugin: args.plugin.name, missing },
+  });
+}
+
+function indexPlugins(plugins: readonly PluginDefinition[]): Registry {
+  const actions = new Map<string, ResolvedAction>();
+  const matchers = new Map<string, ResolvedMatcher>();
+  const namespaces = new Set<string>();
+  const packages = new Map<string, string>();
+  for (const plugin of plugins) addPlugin({ plugin, actions, matchers, namespaces, packages });
+  return {
+    action: ({ namespace, name }) => actions.get(`${namespace}.${name}`),
+    matcher: (name) => matchers.get(name),
+    hasNamespace: (namespace) => namespaces.has(namespace),
+    namespaceOf: (pkg) => packages.get(pkg),
+    actions: () => listActions(actions),
+  };
+}
+
+function listActions(
+  actions: Map<string, ResolvedAction>,
+): { namespace: string; name: string; action: ActionDefinition }[] {
+  return [...actions].map(([key, resolved]) => ({
+    namespace: key.slice(0, key.indexOf(".")),
+    name: key.slice(key.indexOf(".") + 1),
+    action: resolved.action,
+  }));
+}
+
+function addPlugin(args: {
+  plugin: PluginDefinition;
+  actions: Map<string, ResolvedAction>;
+  matchers: Map<string, ResolvedMatcher>;
+  namespaces: Set<string>;
+  packages: Map<string, string>;
+}): void {
+  const { plugin, actions, matchers, namespaces, packages } = args;
+  namespaces.add(plugin.namespace);
+  packages.set(plugin.name, plugin.namespace);
+  for (const action of plugin.actions ?? []) {
+    actions.set(`${plugin.namespace}.${action.name}`, { plugin, action });
+  }
+  for (const matcher of plugin.matchers ?? []) {
+    matchers.set(matcher.name, { plugin, matcher });
+  }
+}

package/src/registry/index.ts

@@ -0,0 +1,2 @@
+export { buildRegistry } from "./build-registry.js";
+export type { Registry, ResolvedAction, ResolvedMatcher } from "./registry.types.js";

package/src/registry/registry.types.ts

@@ -0,0 +1,24 @@
+import type { ActionDefinition, MatcherDefinition, PluginDefinition } from "@venn-lang/sdk";
+
+/** An action together with the plugin that owns it. */
+export interface ResolvedAction {
+  plugin: PluginDefinition;
+  action: ActionDefinition;
+}
+
+/** A matcher together with the plugin that owns it. */
+export interface ResolvedMatcher {
+  plugin: PluginDefinition;
+  matcher: MatcherDefinition;
+}
+
+/** Resolves `namespace.action`, matchers, and namespaces from ingested plugins. */
+export 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 }[];
+}

package/src/run/create-runner.ts

@@ -0,0 +1,103 @@
+import {
+  type Document,
+  expand,
+  type FragmentDecl,
+  type Problem,
+  type RunId,
+} from "@venn-lang/core";
+import { createActionContext } from "../context/index.js";
+import { createDecoratorSource } from "../decorators/index.js";
+import { createEmitter, newRunId } from "../emit/index.js";
+import { createPortResolver } from "../ports/index.js";
+import { buildRegistry } from "../registry/index.js";
+import {
+  absorbExit,
+  collectAliases,
+  collectConfig,
+  collectFragments,
+  createCleanupList,
+  type Engine,
+  runDocument,
+  runScript,
+} from "../scheduler/index.js";
+import type { Runner, RunnerArgs, RunOnceInput, RunResult } from "./runner.types.js";
+
+/**
+ * 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.
+ */
+export function createRunner(args: RunnerArgs): Runner {
+  const registry = buildRegistry({ plugins: args.plugins, caps: args.host.caps });
+  const resolver = createPortResolver({ bindings: args.ports ?? [], caps: args.host.caps });
+  const decorators = createDecoratorSource(args.plugins);
+  const drive = (walk: Walk) => (document: Document) => {
+    // Decorators run first, on every path: what the scheduler walks is the tree
+    // they left, not the one the parser produced.
+    const expansion = expand({ document, decorators, uri: args.uri, imported: args.moduleDecos });
+    return runOnce({ args, registry, resolver, document }, walk, expansion.problems);
+  };
+  return { run: drive(runDocument), script: drive(runScript) };
+}
+
+type Walk = (engine: Engine, document: Document) => Promise<void>;
+
+async function runOnce(input: RunOnceInput, walk: Walk, problems: Problem[]): Promise<RunResult> {
+  const run = newRunId({ clock: input.args.host.clock, random: input.args.host.random });
+  const engine = buildEngine(input, run);
+  // The walk absorbs an `exit` of its own so the run still ends tidily; this is
+  // the backstop for one thrown where no walk was left to absorb it.
+  await absorbExit(engine, () => walk(engine, input.document));
+  return {
+    run,
+    problems,
+    passed: engine.result.passed,
+    failed: engine.result.failed,
+    exitCode: engine.exit,
+  };
+}
+
+function buildEngine(input: RunOnceInput, run: RunId): Engine {
+  const { args, registry } = input;
+  return {
+    registry,
+    emitter: createEmitter({ sink: args.sink, run, clock: args.host.clock }),
+    clock: args.host.clock,
+    lock: args.host.lock,
+    uri: args.uri ?? "memory://inline.vn",
+    result: { passed: 0, failed: 0 },
+    flaky: new Map(),
+    filter: args.filter ?? {},
+    bail: args.bail,
+    cleanup: args.cleanup ?? createCleanupList(),
+    ...documentParts(input),
+  };
+}
+
+/** Everything derived from the document being run: config, fragments, aliases. */
+function documentParts(input: RunOnceInput) {
+  const { args, registry, resolver, document } = input;
+  const env = args.env ?? {};
+  const config = collectConfig(document, env);
+  return {
+    ctx: createActionContext({ host: args.host, ports: resolver, config }),
+    fragments: mergeFragments(collectFragments(document), args.moduleFragments),
+    imports: args.modules,
+    aliases: collectAliases(document, registry),
+    env,
+  };
+}
+
+/** Local fragments take precedence over imported ones of the same name. */
+function mergeFragments(
+  local: Map<string, FragmentDecl>,
+  imported: Map<string, FragmentDecl> | undefined,
+): Map<string, FragmentDecl> {
+  if (!imported) return local;
+  const merged = new Map(imported);
+  for (const [name, fragment] of local) merged.set(name, fragment);
+  return merged;
+}

package/src/run/index.ts

@@ -0,0 +1,4 @@
+export { createRunner } from "./create-runner.js";
+export type { ModuleIo, NpmModules, ResolvedImports } from "./resolve-imports.js";
+export { collectUses, resolveImports } from "./resolve-imports.js";
+export type { Runner, RunnerArgs, RunResult } from "./runner.types.js";