@venn-lang/contracts 0.1.0

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","names":[],"sources":["../src/conformance/expect-venn-error.ts","../src/ports/clock/clock.suite.ts","../src/ports/file-system/file-system.suite.ts","../src/ports/lock-provider/lock-provider.suite.ts","../src/ports/manifest-provider/manifest.suite.ts","../src/ports/process-provider/process-provider.suite.ts","../src/ports/random/random.suite.ts","../src/ports/secret-provider/secret-provider.suite.ts","../src/ports/signal-source/signal-source.suite.ts"],"sourcesContent":["import { expect } from \"vitest\";\n\n/**\n * Asserts that an async operation rejects with a `VennError` whose `.code`\n * matches.\n *\n * Suites assert on the code and never on the message, so wording can be\n * improved without breaking a conformance run.\n *\n * @param args.op - the operation expected to reject.\n * @param args.code - pattern the error code must match, e.g. `/^VN8/`.\n */\nexport async function expectVennError(args: {\n  op: () => Promise<unknown>;\n  code: RegExp;\n}): Promise<void> {\n  await expect(args.op()).rejects.toMatchObject({ code: expect.stringMatching(args.code) });\n}\n","import { describe, expect, it } from \"vitest\";\nimport type { ConformanceSpec } from \"../../conformance/index.js\";\nimport type { Clock } from \"./clock.types.js\";\n\n/** The {@link Clock} TCK. Both the system and virtual clocks satisfy it. */\nexport function clockConformance(spec: ConformanceSpec<Clock>): void {\n  describe(`Clock · ${spec.name}`, () => {\n    it(\"now() is non-decreasing\", async () => {\n      const clock = await spec.factory();\n      const first = clock.now();\n      expect(clock.now()).toBeGreaterThanOrEqual(first);\n    });\n\n    it(\"sleep advances now() by about the requested delay\", async () => {\n      const clock = await spec.factory();\n      const before = clock.now();\n      await clock.sleep(20);\n      // A real timer may fire a millisecond or two early, so the bound is loose.\n      // What must never happen is returning wildly short.\n      expect(clock.now()).toBeGreaterThanOrEqual(before + 18);\n    });\n  });\n}\n","import { fc, test } from \"@fast-check/vitest\";\nimport { describe, expect, it } from \"vitest\";\nimport { type ConformanceSpec, expectVennError } from \"../../conformance/index.js\";\nimport type { FileSystem } from \"./file-system.types.js\";\n\n/** The {@link FileSystem} TCK. Real and double both run it. */\nexport function fileSystemConformance(spec: ConformanceSpec<FileSystem>): void {\n  describe(`FileSystem · ${spec.name}`, () => {\n    it(\"read returns exactly the bytes written\", async () => {\n      const fs = await spec.factory();\n      const bytes = new Uint8Array([1, 2, 3, 4]);\n      await fs.write(\"a.bin\", bytes);\n      expect(await fs.read(\"a.bin\")).toEqual(bytes);\n    });\n\n    it(\"reading a missing path fails with VN8, never a raw error\", async () => {\n      const fs = await spec.factory();\n      await expectVennError({ op: () => fs.read(\"missing.bin\"), code: /^VN8/ });\n    });\n\n    it(\"exists reflects write then remove\", async () => {\n      const fs = await spec.factory();\n      await fs.write(\"k.bin\", new Uint8Array([0]));\n      expect(await fs.exists(\"k.bin\")).toBe(true);\n      await fs.remove(\"k.bin\");\n      expect(await fs.exists(\"k.bin\")).toBe(false);\n    });\n\n    /**\n     * Bounded in both draws and payload, because `node-fs` runs this against a\n     * real disk. Twenty-five draws demonstrate last-write-wins as well as\n     * fast-check's default hundred, and the raised timeout means a loaded\n     * machine reports a slow disk rather than a failure.\n     */\n    test.prop([fc.uint8Array({ maxLength: 4096 })], { numRuns: 25 })(\n      \"write is last-write-wins\",\n      async (bytes) => {\n        const fs = await spec.factory();\n        await fs.write(\"k.bin\", new Uint8Array([9]));\n        await fs.write(\"k.bin\", bytes);\n        expect(await fs.read(\"k.bin\")).toEqual(bytes);\n      },\n      20_000,\n    );\n\n    /**\n     * A workspace's `members = [\"packages/*\"]` rests on listing, so the two\n     * implementations have to agree about it. The double has no directories at\n     * all, only paths, which is exactly why this is asked of both.\n     */\n    it(\"lists what a directory holds, one level deep\", async () => {\n      const fs = await spec.factory();\n      await fs.write(\"pkg/a/venn.toml\", new Uint8Array([1]));\n      await fs.write(\"pkg/b/venn.toml\", new Uint8Array([1]));\n      await fs.write(\"pkg/top.txt\", new Uint8Array([1]));\n\n      const names = (await fs.list(\"pkg\")).map((entry) => entry.name).sort();\n      expect(names).toEqual([\"a\", \"b\", \"top.txt\"]);\n    });\n\n    it(\"says which of them hold more\", async () => {\n      const fs = await spec.factory();\n      await fs.write(\"root/inside/deep.txt\", new Uint8Array([1]));\n      await fs.write(\"root/flat.txt\", new Uint8Array([1]));\n\n      const found = await fs.list(\"root\");\n      expect(found.find((entry) => entry.name === \"inside\")?.directory).toBe(true);\n      expect(found.find((entry) => entry.name === \"flat.txt\")?.directory).toBe(false);\n    });\n\n    /** Asking what is inside something that holds nothing has an answer. */\n    it(\"reads a path that is not a directory as empty\", async () => {\n      const fs = await spec.factory();\n      expect(await fs.list(\"nao/existe\")).toEqual([]);\n    });\n  });\n}\n","import { describe, expect, it } from \"vitest\";\nimport type { ConformanceSpec } from \"../../conformance/index.js\";\nimport type { LockProvider } from \"./lock-provider.types.js\";\n\n/**\n * The {@link LockProvider} TCK. Acquiring, releasing and acquiring again must\n * not deadlock, which is the one law the fake and the real mutex share.\n */\nexport function lockProviderConformance(spec: ConformanceSpec<LockProvider>): void {\n  describe(`LockProvider · ${spec.name}`, () => {\n    it(\"acquire returns a release, and re-acquiring after release works\", async () => {\n      const lock = await spec.factory();\n      const release = await lock.acquire(\"k\");\n      release();\n      const again = await lock.acquire(\"k\");\n      again();\n      expect(typeof again).toBe(\"function\");\n    });\n  });\n}\n","import { describe, expect, it } from \"vitest\";\nimport type { ConformanceSpec } from \"../../conformance/index.js\";\nimport type { ManifestProvider } from \"./manifest.types.js\";\n\n/**\n * The {@link ManifestProvider} TCK. Whatever the source, `load()` returns a\n * manifest with a name and an env map, never a partial one.\n */\nexport function manifestProviderConformance(\n  spec: ConformanceSpec<ManifestProvider> & { expectedName: string },\n): void {\n  describe(`ManifestProvider · ${spec.name}`, () => {\n    it(\"loads a manifest with a name and env map\", async () => {\n      const manifest = (await spec.factory()).load();\n      expect(manifest.name).toBe(spec.expectedName);\n      expect(typeof manifest.env).toBe(\"object\");\n    });\n  });\n}\n","import { describe, expect, it } from \"vitest\";\nimport type { ConformanceSpec } from \"../../conformance/index.js\";\nimport type { ProcessProvider, SpawnArgs } from \"./process-provider.types.js\";\n\n/**\n * The {@link ProcessProvider} TCK.\n *\n * Each implementation is asked to run something that says a known thing and\n * ends with a known code. *What* it is asked to run differs, since a fake has\n * no shell and the real one has no script, but the answer must not.\n */\nexport function processProviderConformance(\n  spec: ConformanceSpec<ProcessProvider> & {\n    runs: SpawnArgs;\n    expected: { code: number; output: string };\n  },\n): void {\n  describe(`ProcessProvider · ${spec.name}`, () => {\n    it(\"waits for the command and reports how it ended\", async () => {\n      const proc = await spec.factory();\n\n      const result = await proc.spawn(spec.runs).wait();\n\n      expect(result.code).toBe(spec.expected.code);\n      expect(result.output).toContain(spec.expected.output);\n    });\n\n    /** Half a minute of silence reads as a command that has hung. */\n    it(\"streams what the command writes, as it writes it\", async () => {\n      const proc = await spec.factory();\n      const seen: string[] = [];\n\n      await proc.spawn({ ...spec.runs, onOutput: (chunk) => seen.push(chunk) }).wait();\n\n      expect(seen.join(\"\")).toContain(spec.expected.output);\n    });\n\n    it(\"hands back a handle that can be asked to stop\", async () => {\n      const proc = await spec.factory();\n      const handle = proc.spawn(spec.runs);\n\n      expect(typeof handle.pid).toBe(\"number\");\n      expect(() => handle.kill()).not.toThrow();\n    });\n  });\n}\n","import { describe, expect, it } from \"vitest\";\nimport type { ConformanceSpec } from \"../../conformance/index.js\";\nimport type { Random } from \"./random.types.js\";\n\n/** The {@link Random} TCK: the range laws both seeded and fixed satisfy. */\nexport function randomConformance(spec: ConformanceSpec<Random>): void {\n  describe(`Random · ${spec.name}`, () => {\n    it(\"next() stays within [0, 1)\", async () => {\n      const random = await spec.factory();\n      for (let i = 0; i < 100; i++) {\n        const value = random.next();\n        expect(value).toBeGreaterThanOrEqual(0);\n        expect(value).toBeLessThan(1);\n      }\n    });\n\n    it(\"int(min, max) stays within the inclusive range\", async () => {\n      const random = await spec.factory();\n      for (let i = 0; i < 100; i++) {\n        const value = random.int(3, 7);\n        expect(value).toBeGreaterThanOrEqual(3);\n        expect(value).toBeLessThanOrEqual(7);\n      }\n    });\n  });\n}\n","import { describe, expect, it } from \"vitest\";\nimport type { ConformanceSpec } from \"../../conformance/index.js\";\nimport type { SecretProvider } from \"./secret-provider.types.js\";\n\n/** A secret the implementation under test is known to hold. */\nexport type KnownSecret = { name: string; raw: string };\n\n/**\n * The {@link SecretProvider} TCK. The redaction law is the load-bearing one:\n * an implementation that leaks through `JSON.stringify` fails here.\n */\nexport function secretProviderConformance(\n  spec: ConformanceSpec<SecretProvider> & { known: KnownSecret },\n): void {\n  describe(`SecretProvider · ${spec.name}`, () => {\n    it(\"reveals the known secret\", async () => {\n      const secrets = await spec.factory();\n      expect(secrets.get(spec.known.name)?.reveal()).toBe(spec.known.raw);\n    });\n\n    it(\"never leaks the raw value through serialization\", async () => {\n      const secrets = await spec.factory();\n      const secret = secrets.get(spec.known.name);\n      expect(JSON.stringify(secret)).not.toContain(spec.known.raw);\n      expect(String(secret)).not.toContain(spec.known.raw);\n    });\n  });\n}\n","import { describe, expect, it } from \"vitest\";\nimport type { SignalSource, SystemSignal } from \"./signal-source.types.js\";\n\n/** How a suite delivers a signal to the implementation it is testing. */\nexport interface SignalSpec {\n  name: string;\n  factory(): SignalSource;\n  /** Deliver `signal` the way this implementation really receives one. */\n  raise(args: { source: SignalSource; signal: SystemSignal }): void;\n  /** The signal this implementation can be asked to deliver here. */\n  delivers: SystemSignal;\n  /** A second signal, subscribed to but never raised, to prove they stay apart. */\n  other: SystemSignal;\n}\n\n/**\n * The {@link SignalSource} TCK. The process and the fake both run it, because a\n * double that delivers differently is a test that lies about shutdown.\n */\nexport function signalSourceConformance(spec: SignalSpec): void {\n  describe(`SignalSource · ${spec.name}`, () => {\n    const listen = () => {\n      const source = spec.factory();\n      const seen: SystemSignal[] = [];\n      return { source, seen, raise: () => spec.raise({ source, signal: spec.delivers }) };\n    };\n\n    it(\"calls the handler with the signal that arrived\", () => {\n      const { source, seen, raise } = listen();\n      const off = source.on(spec.delivers, (signal) => seen.push(signal));\n\n      raise();\n      off();\n\n      expect(seen).toEqual([spec.delivers]);\n    });\n\n    it(\"calls every handler waiting on that signal\", () => {\n      const { source, seen, raise } = listen();\n      const first = source.on(spec.delivers, () => seen.push(spec.delivers));\n      const second = source.on(spec.delivers, () => seen.push(spec.delivers));\n\n      raise();\n      first();\n      second();\n\n      expect(seen).toHaveLength(2);\n    });\n\n    it(\"leaves other signals alone\", () => {\n      const { source, seen, raise } = listen();\n      const off = source.on(spec.other, (signal) => seen.push(signal));\n\n      raise();\n      off();\n\n      expect(seen).toEqual([]);\n    });\n\n    it(\"stops delivering once unsubscribed, and unsubscribing twice is harmless\", () => {\n      const { source, seen, raise } = listen();\n      const off = source.on(spec.delivers, (signal) => seen.push(signal));\n\n      off();\n      off();\n      raise();\n\n      expect(seen).toEqual([]);\n    });\n\n    // A signal is not a one-shot: a program that ignores the second Ctrl+C is a\n    // program the user cannot get out of.\n    it(\"keeps delivering while the subscription lives\", () => {\n      const { source, seen, raise } = listen();\n      const off = source.on(spec.delivers, (signal) => seen.push(signal));\n\n      raise();\n      raise();\n      off();\n\n      expect(seen).toEqual([spec.delivers, spec.delivers]);\n    });\n  });\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@venn-lang/contracts",
+  "version": "0.1.0",
+  "description": "The ports the Venn core runs on, their implementations, and the host that carries them.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "ports",
+    "adapters",
+    "conformance"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/contracts#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/contracts"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "development": "./src/node.ts",
+      "types": "./dist/node.d.mts",
+      "import": "./dist/node.mjs",
+      "default": "./dist/node.mjs"
+    },
+    "./testing": {
+      "development": "./src/testing.ts",
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@fast-check/vitest": ">=0.4.0",
+    "vitest": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@fast-check/vitest": "^0.4.1",
+    "@types/node": "^24",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "peerDependenciesMeta": {
+    "@fast-check/vitest": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/capabilities/host-capability.ts

@@ -0,0 +1,18 @@
+/**
+ * Every capability a Host may expose. A port or plugin declares which it
+ * requires, a host advertises which it provides, and negotiation compares the
+ * two before anything binds.
+ */
+export const ALL_CAPABILITIES = [
+  "fs",
+  "process",
+  "net",
+  "clock",
+  "random",
+  "secrets",
+  "log",
+  "io",
+] as const;
+
+/** One capability name, drawn from {@link ALL_CAPABILITIES}. */
+export type HostCapability = (typeof ALL_CAPABILITIES)[number];

package/src/capabilities/index.ts

@@ -0,0 +1,2 @@
+export type { HostCapability } from "./host-capability.js";
+export { ALL_CAPABILITIES } from "./host-capability.js";

package/src/conformance/expect-venn-error.ts

@@ -0,0 +1,18 @@
+import { expect } from "vitest";
+
+/**
+ * Asserts that an async operation rejects with a `VennError` whose `.code`
+ * matches.
+ *
+ * Suites assert on the code and never on the message, so wording can be
+ * improved without breaking a conformance run.
+ *
+ * @param args.op - the operation expected to reject.
+ * @param args.code - pattern the error code must match, e.g. `/^VN8/`.
+ */
+export async function expectVennError(args: {
+  op: () => Promise<unknown>;
+  code: RegExp;
+}): Promise<void> {
+  await expect(args.op()).rejects.toMatchObject({ code: expect.stringMatching(args.code) });
+}

package/src/conformance/harness.types.ts

@@ -0,0 +1,14 @@
+/**
+ * Builds a fresh implementation for a single conformance run.
+ *
+ * Called once per test rather than once per suite, so no test can observe state
+ * another test left behind.
+ */
+export type PortFactory<T> = () => T | Promise<T>;
+
+/** One implementation under test. */
+export interface ConformanceSpec<T> {
+  /** Shown in the test name, e.g. "memory" or "node". */
+  readonly name: string;
+  readonly factory: PortFactory<T>;
+}

package/src/conformance/index.ts

@@ -0,0 +1,2 @@
+export { expectVennError } from "./expect-venn-error.js";
+export type { ConformanceSpec, PortFactory } from "./harness.types.js";

package/src/dotenv/dotenv-files.ts

@@ -0,0 +1,30 @@
+// biome-ignore-all lint/suspicious/noTemplateCurlyInString: ${name} is a placeholder in a path, not a JavaScript template.
+
+/**
+ * The dotenv files read when `venn.toml` does not name its own.
+ *
+ * The order is the precedence, lowest first: what everyone shares, then what
+ * this environment adds, then what this machine keeps to itself. The `.local`
+ * ones are what a `.gitignore` is for.
+ */
+export const DOTENV_CONVENTION: readonly string[] = [
+  ".env",
+  ".env.${name}",
+  ".env.local",
+  ".env.${name}.local",
+];
+
+/**
+ * Which files to read, in order, for one environment.
+ *
+ * The runner and the editor both ask this, so they cannot disagree about where
+ * a value lives.
+ *
+ * @param args.configured - `[env] files` from `venn.toml`. Empty or absent
+ * falls back to {@link DOTENV_CONVENTION}.
+ * @param args.name - the selected environment, substituted for `${name}`.
+ */
+export function dotenvFiles(args: { configured?: readonly string[]; name: string }): string[] {
+  const names = args.configured?.length ? args.configured : DOTENV_CONVENTION;
+  return names.map((each) => each.replaceAll("${name}", args.name));
+}

package/src/dotenv/index.ts

@@ -0,0 +1,2 @@
+export { DOTENV_CONVENTION, dotenvFiles } from "./dotenv-files.js";
+export { parseDotenv } from "./parse-dotenv.js";

package/src/dotenv/parse-dotenv.ts

@@ -0,0 +1,34 @@
+/**
+ * Read a `.env` file: `NAME=value`, one per line.
+ *
+ * Deliberately small. It understands comments, blank lines, an `export `
+ * prefix, and quotes around a value that needs them. No variable expansion:
+ * `${OTHER}` is left alone, because Venn already interpolates in its own
+ * strings and two syntaxes for one idea is how people get surprised.
+ *
+ * @returns every name found, later lines winning over earlier ones.
+ */
+export function parseDotenv(content: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of content.split(/\r?\n/)) {
+    const entry = readLine(line);
+    if (entry) out[entry.name] = entry.value;
+  }
+  return out;
+}
+
+const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/;
+
+function readLine(line: string): { name: string; value: string } | undefined {
+  if (/^\s*(#|$)/.test(line)) return undefined;
+  const match = LINE.exec(line);
+  if (!match?.[1]) return undefined;
+  return { name: match[1], value: unquote((match[2] ?? "").trim()) };
+}
+
+/** A quoted value keeps its spaces and its `#`; an unquoted one stops at a comment. */
+function unquote(raw: string): string {
+  const quoted = /^(['"])([\s\S]*)\1$/.exec(raw);
+  if (quoted) return quoted[2] as string;
+  return (raw.split(" #")[0] ?? "").trim();
+}

package/src/errors/contract-codes.ts

@@ -0,0 +1,37 @@
+import type { HostCapability } from "../capabilities/index.js";
+import { VennError } from "./venn-error.js";
+
+/** VN2010: a port requires capabilities the host does not provide. */
+export function hostMissingCapability(args: {
+  portId: string;
+  missing: readonly HostCapability[];
+  present: readonly HostCapability[];
+}): VennError {
+  const message =
+    `Port "${args.portId}" requires capability ${quote(args.missing)}, ` +
+    `which this host does not provide. Present: ${list(args.present)}.`;
+  return new VennError({ code: "VN2010", message, detail: { ...args } });
+}
+
+/** VN2011: an implementation is missing one or more methods the port declares. */
+export function portShapeMismatch(args: { portId: string; missing: readonly string[] }): VennError {
+  const message = `Implementation of "${args.portId}" is missing method(s): ${args.missing.join(", ")}.`;
+  return new VennError({ code: "VN2011", message, detail: { ...args } });
+}
+
+/** VN2012: code reached a capability the host declared unavailable. */
+export function capabilityUnavailable(args: {
+  capability: HostCapability;
+  method: string;
+}): VennError {
+  const message = `Capability "${args.capability}" is not available on this host (called "${args.method}").`;
+  return new VennError({ code: "VN2012", message, detail: { ...args } });
+}
+
+function quote(caps: readonly string[]): string {
+  return caps.map((c) => `"${c}"`).join(", ");
+}
+
+function list(caps: readonly string[]): string {
+  return caps.length === 0 ? "(none)" : caps.join(", ");
+}

package/src/errors/index.ts

@@ -0,0 +1,7 @@
+export {
+  capabilityUnavailable,
+  hostMissingCapability,
+  portShapeMismatch,
+} from "./contract-codes.js";
+export type { VennErrorDetail } from "./venn-error.js";
+export { VennError } from "./venn-error.js";

package/src/errors/venn-error.ts

@@ -0,0 +1,20 @@
+/** Structured, serializable, redaction-safe detail attached to a {@link VennError}. */
+export type VennErrorDetail = Readonly<Record<string, unknown>>;
+
+/**
+ * The single error type that crosses a contracts boundary.
+ *
+ * Every failure carries a stable `VNxxxx` code, so conformance suites assert on
+ * `.code` and never on prose. Messages stay free to improve.
+ */
+export class VennError extends Error {
+  readonly code: string;
+  readonly detail: VennErrorDetail | undefined;
+
+  constructor(args: { code: string; message: string; detail?: VennErrorDetail }) {
+    super(args.message);
+    this.name = "VennError";
+    this.code = args.code;
+    this.detail = args.detail;
+  }
+}

package/src/host/create-host.ts

@@ -0,0 +1,16 @@
+import { createTestHost } from "./create-test-host.js";
+import { createWorkerHost } from "./create-worker-host.js";
+
+/**
+ * The neutral host assemblers.
+ *
+ * `node` is deliberately absent: it pulls `node:*`, so it lives behind
+ * `@venn-lang/contracts/node` as `createNodeHost` and this entry stays Worker-safe.
+ */
+export const createHost: {
+  readonly worker: typeof createWorkerHost;
+  readonly test: typeof createTestHost;
+} = {
+  worker: createWorkerHost,
+  test: createTestHost,
+};

package/src/host/create-node-host.ts

@@ -0,0 +1,29 @@
+import { ALL_CAPABILITIES } from "../capabilities/index.js";
+import { createConsoleLogger } from "../logger/index.js";
+import { createSystemClock } from "../ports/clock/index.js";
+import { createNodeFs } from "../ports/file-system/node-fs.js";
+import { createInProcessLock } from "../ports/lock-provider/index.js";
+import { createNodeSpawn } from "../ports/process-provider/node-spawn.js";
+import { createSeededRandom } from "../ports/random/index.js";
+import { createEnvSecrets } from "../ports/secret-provider/index.js";
+import type { Host } from "./host.types.js";
+
+/**
+ * Host for the CLI: the real file system, secrets from the environment, and
+ * every capability.
+ *
+ * @param args.root - where relative paths resolve. Defaults to the process's
+ * current directory.
+ */
+export function createNodeHost(args: { root?: string } = {}): Host {
+  return {
+    fs: createNodeFs({ root: args.root }),
+    proc: createNodeSpawn(),
+    clock: createSystemClock(),
+    random: createSeededRandom({ seed: 1 }),
+    secrets: createEnvSecrets(),
+    log: createConsoleLogger(),
+    lock: createInProcessLock(),
+    caps: ALL_CAPABILITIES,
+  };
+}

package/src/host/create-test-host.ts

@@ -0,0 +1,28 @@
+import { ALL_CAPABILITIES } from "../capabilities/index.js";
+import { createMemoryLogger } from "../logger/index.js";
+import { createVirtualClock } from "../ports/clock/index.js";
+import { createMemoryFs } from "../ports/file-system/index.js";
+import { createInProcessLock } from "../ports/lock-provider/index.js";
+import { createFakeProcess } from "../ports/process-provider/index.js";
+import { createSeededRandom } from "../ports/random/index.js";
+import { createMemorySecrets } from "../ports/secret-provider/index.js";
+import type { Host } from "./host.types.js";
+
+/**
+ * A host of doubles, every capability granted. The default for tests.
+ *
+ * @param overrides - replaces individual members, e.g. a real clock.
+ */
+export function createTestHost(overrides: Partial<Host> = {}): Host {
+  return {
+    fs: createMemoryFs(),
+    proc: createFakeProcess(),
+    clock: createVirtualClock(),
+    random: createSeededRandom({ seed: 1 }),
+    secrets: createMemorySecrets({ values: {} }),
+    log: createMemoryLogger(),
+    lock: createInProcessLock(),
+    caps: ALL_CAPABILITIES,
+    ...overrides,
+  };
+}

package/src/host/create-worker-host.ts

@@ -0,0 +1,32 @@
+import { createMemoryLogger } from "../logger/index.js";
+import { createSystemClock } from "../ports/clock/index.js";
+import { createMemoryFs } from "../ports/file-system/index.js";
+import { createInProcessLock } from "../ports/lock-provider/index.js";
+import type { ProcessProvider } from "../ports/process-provider/index.js";
+import { ProcessProviderPort } from "../ports/process-provider/index.js";
+import { createSeededRandom } from "../ports/random/index.js";
+import { createMemorySecrets } from "../ports/secret-provider/index.js";
+import type { Host } from "./host.types.js";
+import { unavailable } from "./unavailable.js";
+
+/**
+ * Host for a Web Worker: an in-memory file system, no `process`, no `net`.
+ *
+ * `proc` is a stand-in whose every method throws VN2012, so reaching for a
+ * subprocess in the editor fails with a diagnostic instead of a `TypeError`.
+ */
+export function createWorkerHost(): Host {
+  return {
+    fs: createMemoryFs(),
+    proc: unavailable<ProcessProvider>({
+      capability: "process",
+      methods: ProcessProviderPort.methods,
+    }),
+    clock: createSystemClock(),
+    random: createSeededRandom({ seed: 1 }),
+    secrets: createMemorySecrets({ values: {} }),
+    log: createMemoryLogger(),
+    lock: createInProcessLock(),
+    caps: ["fs", "clock", "random", "secrets", "log"],
+  };
+}

package/src/host/host.types.ts

@@ -0,0 +1,26 @@
+import type { HostCapability } from "../capabilities/index.js";
+import type { Logger } from "../logger/index.js";
+import type { Clock } from "../ports/clock/index.js";
+import type { FileSystem } from "../ports/file-system/index.js";
+import type { LockProvider } from "../ports/lock-provider/index.js";
+import type { ProcessProvider } from "../ports/process-provider/index.js";
+import type { Random } from "../ports/random/index.js";
+import type { SecretProvider } from "../ports/secret-provider/index.js";
+
+/**
+ * Everything the core is allowed to reach: assembled at the entry point, then
+ * passed inward. The core receives this and imports nothing else.
+ *
+ * Three assemblers build one: `createHost.worker`, `createHost.test`, and
+ * `createNodeHost` from `@venn-lang/contracts/node`.
+ */
+export interface Host {
+  readonly fs: FileSystem;
+  readonly proc: ProcessProvider;
+  readonly clock: Clock;
+  readonly random: Random;
+  readonly secrets: SecretProvider;
+  readonly log: Logger;
+  readonly lock: LockProvider;
+  readonly caps: readonly HostCapability[];
+}

package/src/host/index.ts

@@ -0,0 +1,5 @@
+export { createHost } from "./create-host.js";
+export { createTestHost } from "./create-test-host.js";
+export { createWorkerHost } from "./create-worker-host.js";
+export type { Host } from "./host.types.js";
+export { unavailable } from "./unavailable.js";

package/src/host/unavailable.ts

@@ -0,0 +1,23 @@
+import type { HostCapability } from "../capabilities/index.js";
+import { capabilityUnavailable } from "../errors/index.js";
+
+/**
+ * A stand-in for a port the host cannot provide, such as `process` in a Worker.
+ *
+ * @param args.capability - the capability the host lacks, named in the error.
+ * @param args.methods - the port's declared methods, usually `SomePort.methods`.
+ * @returns an object shaped like `T` whose every method throws VN2012 when
+ * called, rather than failing as a `TypeError` mid-run.
+ */
+export function unavailable<T>(args: {
+  capability: HostCapability;
+  methods: readonly string[];
+}): T {
+  const bag: Record<string, unknown> = {};
+  for (const method of args.methods) {
+    bag[method] = () => {
+      throw capabilityUnavailable({ capability: args.capability, method });
+    };
+  }
+  return bag as T;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// @venn-lang/contracts: the neutral core. Everything reachable from here is
+// Worker-safe. Implementations backed by `node:*` live behind the "./node"
+// subpath, conformance suites behind "./testing".
+export * from "./capabilities/index.js";
+export { DOTENV_CONVENTION, dotenvFiles, parseDotenv } from "./dotenv/index.js";
+export * from "./errors/index.js";
+export * from "./host/index.js";
+export * from "./logger/index.js";
+export * from "./port/index.js";
+export * from "./ports/index.js";

package/src/logger/console-logger.ts

@@ -0,0 +1,12 @@
+import type { Logger } from "./logger.types.js";
+
+/** Logger backed by the global console, so it works in a Worker and in Node. */
+export function createConsoleLogger(): Logger {
+  return {
+    log(entry) {
+      const line = `[${entry.level}] ${entry.message}`;
+      if (entry.level === "error") console.error(line);
+      else console.log(line);
+    },
+  };
+}

package/src/logger/index.ts

@@ -0,0 +1,3 @@
+export { createConsoleLogger } from "./console-logger.js";
+export type { LogEntry, Logger, LogLevel, MemoryLogger } from "./logger.types.js";
+export { createMemoryLogger } from "./memory-logger.js";

package/src/logger/logger.types.ts

@@ -0,0 +1,18 @@
+/** How loudly one entry asks to be heard. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+/** One line of log, as data rather than as formatted text. */
+export interface LogEntry {
+  readonly level: LogLevel;
+  readonly message: string;
+}
+
+/** The minimal structured logger a host exposes. */
+export interface Logger {
+  log(entry: LogEntry): void;
+}
+
+/** A {@link Logger} that also retains what it was given, for assertions. */
+export interface MemoryLogger extends Logger {
+  readonly entries: readonly LogEntry[];
+}

package/src/logger/memory-logger.ts

@@ -0,0 +1,12 @@
+import type { LogEntry, MemoryLogger } from "./logger.types.js";
+
+/** The double: keeps every entry in `entries` instead of printing it. */
+export function createMemoryLogger(): MemoryLogger {
+  const entries: LogEntry[] = [];
+  return {
+    entries,
+    log(entry) {
+      entries.push(entry);
+    },
+  };
+}

package/src/node.ts

@@ -0,0 +1,8 @@
+// @venn-lang/contracts/node: the corner backed by `node:*`. Only Node consumers (the
+// CLI) import this; the main entry stays neutral so it runs in a Web Worker.
+
+export { createNodeHost } from "./host/create-node-host.js";
+export { type ConsoleStreams, createNodeConsole } from "./ports/console/node-console.js";
+export { createNodeFs } from "./ports/file-system/node-fs.js";
+export { createNodeSpawn } from "./ports/process-provider/node-spawn.js";
+export { createNodeSignals, isKnownSignal } from "./ports/signal-source/node-signals.js";

package/src/port/assert-capabilities.ts

@@ -0,0 +1,18 @@
+import type { HostCapability } from "../capabilities/index.js";
+import { hostMissingCapability } from "../errors/index.js";
+import { missingCapabilities } from "./missing-capabilities.js";
+import type { Port } from "./port.types.js";
+
+/**
+ * Checks the host against what the port requires.
+ *
+ * @throws VennError VN2010 when a required capability is absent.
+ */
+export function assertCapabilities<T>(args: {
+  port: Port<T>;
+  caps: readonly HostCapability[];
+}): void {
+  const missing = missingCapabilities({ requires: args.port.requires, caps: args.caps });
+  if (missing.length === 0) return;
+  throw hostMissingCapability({ portId: args.port.id, missing, present: args.caps });
+}

package/src/port/assert-port-shape.ts

@@ -0,0 +1,18 @@
+import { portShapeMismatch } from "../errors/index.js";
+import type { Port } from "./port.types.js";
+
+/**
+ * Checks the implementation against the methods the port declares.
+ *
+ * @throws VennError VN2011 when a declared method is missing or is not callable.
+ */
+export function assertPortShape<T>(args: { port: Port<T>; impl: unknown }): void {
+  const missing = missingMethods(args.port, args.impl);
+  if (missing.length === 0) return;
+  throw portShapeMismatch({ portId: args.port.id, missing });
+}
+
+function missingMethods<T>(port: Port<T>, impl: unknown): readonly string[] {
+  const bag = impl as Record<string, unknown> | null | undefined;
+  return port.methods.filter((m) => typeof bag?.[m] !== "function");
+}

package/src/port/bind-port.ts

@@ -0,0 +1,28 @@
+import type { HostCapability } from "../capabilities/index.js";
+import { assertCapabilities } from "./assert-capabilities.js";
+import { assertPortShape } from "./assert-port-shape.js";
+import type { Port } from "./port.types.js";
+
+/**
+ * The single loader entry. Negotiates capabilities, checks the implementation's
+ * shape, then hands it back typed as `T`.
+ *
+ * Both checks run before anything is bound, so a mismatch is reported at start
+ * up rather than as a `TypeError` in the middle of a test.
+ *
+ * @param args.port - the descriptor to bind against.
+ * @param args.impl - the candidate implementation, untrusted.
+ * @param args.caps - the capabilities the host advertises.
+ * @returns `args.impl` typed as `T`.
+ * @throws VennError VN2010 when the host lacks a required capability, VN2011
+ * when the implementation is missing a declared method.
+ */
+export function bindPort<T>(args: {
+  port: Port<T>;
+  impl: unknown;
+  caps: readonly HostCapability[];
+}): T {
+  assertCapabilities({ port: args.port, caps: args.caps });
+  assertPortShape({ port: args.port, impl: args.impl });
+  return args.impl as T;
+}

package/src/port/index.ts

@@ -0,0 +1,5 @@
+export { assertCapabilities } from "./assert-capabilities.js";
+export { assertPortShape } from "./assert-port-shape.js";
+export { bindPort } from "./bind-port.js";
+export { missingCapabilities } from "./missing-capabilities.js";
+export type { AnyPort, Port } from "./port.types.js";