@venn-lang/mock 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,115 @@
+# @venn-lang/mock
+
+> The `mock` namespace: named mocks, HTTP interceptors, feature flags and a virtual clock.
+
+Eight verbs writing to one in-process state object. There is no port and no network here: the whole
+package is a typed way to record what a run should pretend is true, and a way to read that record
+back from TypeScript.
+
+## Install
+
+The package ships with the stdlib, so the CLI already loads it. Inside a `.vn` file, bring the
+namespace in with `use`:
+
+```ruby
+use "venn/mock"
+```
+
+## Usage
+
+```ruby
+module demo.checkout
+
+use "venn/mock"
+
+setup {
+  mock.start "payments" { from: "./mocks/stripe.yaml" }
+  mock.intercept "POST" "**/charge" { respond: { status: 201, body: { id: "ch_1" } } }
+  mock.flag "new-checkout"
+  mock.flag "rollout" { value: 0.5 }
+}
+
+teardown { mock.reset }
+
+flow "Checkout" {
+  step "hold time still" {
+    mock.clock.freeze 2026-07-23T12:00:00Z
+    let now = mock.clock.advance 1h
+    expect now > 0
+  }
+}
+```
+
+## Verbs
+
+| Verb | Positional arguments | Options | Result |
+| --- | --- | --- | --- |
+| `mock.start` | `name: string` | `from` | `mock.Mock` |
+| `mock.stop` | none | none | `void` |
+| `mock.intercept` | `method: string`, `url: string` | `respond` | `mock.Interceptor` |
+| `mock.respond` | `status: number`, `body: dynamic` | `status`, `body` | `mock.Response` |
+| `mock.clock.freeze` | `at: string \| number \| instant` | none | `number`, epoch ms |
+| `mock.clock.advance` | `by: string \| number \| duration` | none | `number`, the new virtual now |
+| `mock.flag` | `name: string` | `value` | `dynamic`, the value that was set |
+| `mock.reset` | none | none | `void` |
+
+Notes that matter in practice:
+
+- `mock.stop` clears the registered mocks and interceptors but leaves flags and the clock alone.
+  `mock.reset` clears everything, including the frozen instant.
+- `mock.flag "x"` with no `value` sets the flag to `true`.
+- `mock.respond` accepts its two values positionally or by name, so
+  `mock.respond 201 { body: { ok: true } }` and `mock.respond { status: 201, body: { ok: true } }`
+  record the same thing. The `respond` option of `mock.intercept` takes either a full
+  `{ status, body }` map or a bare value, which is wrapped as a `200`.
+- The clock verbs read the language's own literals. `mock.clock.freeze 2026-07-23T12:00:00Z` and
+  `mock.clock.advance 1h` pass an instant and a duration value, not strings, and both are understood.
+  An ISO string or a raw millisecond count works too.
+- Freezing records the instant in mock state. It does not drive the host clock, and no other stdlib
+  plugin reads the interceptors yet: the state is a record, and TypeScript is what reads it.
+- Option names come from each verb's schema, so a typo is `VN3001` with a "did you mean" hint before
+  the flow runs.
+
+## Types
+
+| Name | Shape |
+| --- | --- |
+| `mock.Mock` | `{ name: string, from?: string }` |
+| `mock.Interceptor` | `{ method: string, path: string, respond: mock.Response }` |
+| `mock.Response` | `{ status: number, body: dynamic }` |
+
+## Reading the state back
+
+Every verb reads and writes one process-wide `MockState`. A test that drives the plugin from
+TypeScript inspects it directly:
+
+```ts
+import { getMockState, resetMockState } from "@venn-lang/mock";
+
+resetMockState();
+// ... run the flow ...
+const state = getMockState();
+state.flags.get("new-checkout"); // true
+state.intercepts[0]?.respond; // { status: 201, body: { id: "ch_1" } }
+state.frozenInstant; // epoch ms, or undefined while the clock is live
+```
+
+`resetMockState()` replaces the shared state with a fresh one, which is exactly what the
+`mock.reset` verb does. Call it in a `beforeEach` so one test's flags never reach the next.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `mockPlugin` (also the default export) | The `PluginDefinition`: namespace `mock`, no required capability, eight actions. |
+| `mockActions` | The action list, in registration order. |
+| `getMockState()` | The process-wide `MockState` the verbs read and write. |
+| `resetMockState()` | Replaces it with a fresh, empty state. |
+| `createMockState()` | Builds a fresh, empty state without touching the shared one. |
+| `MockState`, `NamedMock`, `Interceptor`, `MockResponse` | Types only. |
+
+## See also
+
+- [`@venn-lang/http`](../std-http), whose verbs the interceptors are written for.
+- [`@venn-lang/data`](../std-data), for deterministic fake values.
+- [`@venn-lang/sdk`](../sdk), `defineAction` / `definePlugin`.

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { ActionDefinition, PluginDefinition } from "@venn-lang/sdk";
+//#region src/actions/index.d.ts
+/** Every verb in the `mock` namespace, in the order the editor lists them. */
+declare const mockActions: ActionDefinition[];
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `mock` plugin: in-process mocking, feature flags and a virtual clock.
+ *
+ * Everything it does happens in memory, so it needs no host capability and
+ * opens no socket. It publishes `mock.Mock`, `mock.Interceptor` and
+ * `mock.Response` so a flow can name what its verbs hand back.
+ */
+declare const mockPlugin: PluginDefinition;
+//#endregion
+//#region src/state/mock-state.types.d.ts
+/** A canned response an interceptor replies with. */
+interface MockResponse {
+  status: number;
+  body: unknown;
+}
+/** A registered interception: match a method and a path pattern, reply with `respond`. */
+interface Interceptor {
+  method: string;
+  path: string;
+  respond: MockResponse;
+}
+/** A named mock service, optionally seeded from a source such as an OpenAPI file. */
+interface NamedMock {
+  name: string;
+  from?: string;
+}
+/** The in-process, mutable state the `mock` namespace reads and writes. */
+interface MockState {
+  mocks: Map<string, NamedMock>;
+  intercepts: Interceptor[];
+  flags: Map<string, unknown>;
+  /** Virtual "now" in epoch ms once frozen; `undefined` while the clock is live. */
+  frozenInstant?: number;
+}
+//#endregion
+//#region src/state/create-mock-state.d.ts
+/**
+ * Builds an empty mock state: no mocks, no interceptors, no flags, clock live.
+ *
+ * @returns A state nothing else holds. `getMockState` returns the shared one
+ * the verbs actually read.
+ */
+declare function createMockState(): MockState;
+//#endregion
+//#region src/state/shared-state.d.ts
+/**
+ * The mock state every `mock` verb reads and writes.
+ *
+ * One state per process, so everything running in that process sees the same
+ * mocks, flags and clock.
+ *
+ * @returns The live state. It is mutable: writing to it is how the verbs work.
+ */
+declare function getMockState(): MockState;
+/**
+ * Replaces the shared state with an empty one. Backs `mock.reset`, and lets a
+ * test start from a known state.
+ *
+ * Callers holding the object from a previous {@link getMockState} keep the old
+ * one, which no verb reads any more.
+ */
+declare function resetMockState(): void;
+//#endregion
+export { type Interceptor, type MockResponse, type MockState, type NamedMock, createMockState, mockPlugin as default, mockPlugin, getMockState, mockActions, resetMockState };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/actions/index.ts","../src/plugin.ts","../src/state/mock-state.types.ts","../src/state/create-mock-state.ts","../src/state/shared-state.ts"],"mappings":";;;cAOa,aAAa;;;;;;;;;;cCIb,YAAY;;;;UCVR;EACf;EACA;;;UAIe;EACf;EACA;EACA,SAAS;;;UAIM;EACf;EACA;;;UAIe;EACf,OAAO,YAAY;EACnB,YAAY;EACZ,OAAO;;EAEP;;;;;;;;;;iBCjBc,mBAAmB;;;;;;;;;;;iBCKnB,gBAAgB;;;;;;;;iBAWhB"}

package/dist/index.js

@@ -0,0 +1,280 @@
+import { Duration, arg, defineAction, definePlugin, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+//#region src/state/create-mock-state.ts
+/**
+* Builds an empty mock state: no mocks, no interceptors, no flags, clock live.
+*
+* @returns A state nothing else holds. `getMockState` returns the shared one
+* the verbs actually read.
+*/
+function createMockState() {
+	return {
+		mocks: /* @__PURE__ */ new Map(),
+		intercepts: [],
+		flags: /* @__PURE__ */ new Map(),
+		frozenInstant: void 0
+	};
+}
+//#endregion
+//#region src/state/shared-state.ts
+let shared = createMockState();
+/**
+* The mock state every `mock` verb reads and writes.
+*
+* One state per process, so everything running in that process sees the same
+* mocks, flags and clock.
+*
+* @returns The live state. It is mutable: writing to it is how the verbs work.
+*/
+function getMockState() {
+	return shared;
+}
+/**
+* Replaces the shared state with an empty one. Backs `mock.reset`, and lets a
+* test start from a known state.
+*
+* Callers holding the object from a previous {@link getMockState} keep the old
+* one, which no verb reads any more.
+*/
+function resetMockState() {
+	shared = createMockState();
+}
+//#endregion
+//#region src/actions/clock-actions.ts
+/**
+* `mock.clock.freeze("2026-01-01T00:00:00Z")`: pin virtual time to an instant.
+*
+* The instant is only recorded in mock state. It does not drive the host clock,
+* so a verb that asks the host what time it is still gets the real answer.
+*/
+const clockFreeze = defineAction({
+	name: "clock.freeze",
+	doc: "Freeze virtual time at the given instant (recorded in mock state only, for now).",
+	args: [arg("at", t.union(t.string, t.number, t.instant), "The instant to hold time at.")],
+	result: t.number,
+	run: (_ctx, input) => freezeClock(input)
+});
+function freezeClock(input) {
+	const instant = toInstant(input.args[0]);
+	getMockState().frozenInstant = instant;
+	return instant;
+}
+function toInstant(value) {
+	if (typeof value === "number") return value;
+	const epochMs = instantValue(value);
+	if (epochMs !== void 0) return epochMs;
+	const ms = Date.parse(String(value));
+	return Number.isNaN(ms) ? 0 : ms;
+}
+/**
+* `mock.clock.advance("1h")`: move the stored virtual time forward by a span.
+*
+* Advancing an unfrozen clock counts from the epoch, since there is no instant
+* to move from.
+*/
+const clockAdvance = defineAction({
+	name: "clock.advance",
+	doc: "Advance the frozen virtual time by a duration, e.g. mock.clock.advance(\"1h\").",
+	args: [arg("by", t.union(t.string, t.number, t.duration), "How far to move time forward.")],
+	result: t.number,
+	run: (_ctx, input) => advanceClock(input)
+});
+function advanceClock(input) {
+	const state = getMockState();
+	const next = (state.frozenInstant ?? 0) + durationMs(input);
+	state.frozenInstant = next;
+	return next;
+}
+function durationMs(input) {
+	const params = input.params ?? {};
+	const given = input.args[0] ?? params.by;
+	const ms = durationValue(given);
+	if (ms !== void 0) return ms;
+	const parsed = Duration.safeParse(given);
+	return parsed.success ? parsed.data : 0;
+}
+/**
+* The number inside a unit value, when the argument is one.
+*
+* `1h` and `2026-07-23T12:00:00Z` reach an action as `{ kind, ms }` and
+* `{ kind, epochMs }`, the language's own literals rather than strings. Without
+* this unwrapping they parse to `NaN` and the clock silently sits at the epoch.
+*/
+function durationValue(value) {
+	const unit = value;
+	return unit?.kind === "duration" ? unit.ms ?? 0 : void 0;
+}
+function instantValue(value) {
+	const unit = value;
+	return unit?.kind === "instant" ? unit.epochMs ?? 0 : void 0;
+}
+//#endregion
+//#region src/actions/flag-actions.ts
+/**
+* `mock.flag("new-checkout", { value: "b" })`: set a feature flag.
+*
+* The flag's value is an option rather than a second positional argument, so
+* the common case, turning a flag on, reads as `mock.flag("new-checkout")`.
+*/
+const flag = defineAction({
+	name: "flag",
+	doc: "Set a feature flag; the value comes from opts or defaults to true.",
+	params: z.object({ value: z.unknown().optional() }).optional(),
+	args: [arg("name", t.string, "Which flag. Its value is an option, true by default.")],
+	result: t.dynamic,
+	run: (_ctx, input) => setFlag(input)
+});
+function setFlag(input) {
+	const params = input.params ?? {};
+	const name = String(input.args[0] ?? "");
+	const value = params.value ?? true;
+	getMockState().flags.set(name, value);
+	return value;
+}
+//#endregion
+//#region src/actions/intercept-actions.ts
+/**
+* `mock.intercept("POST", "/charge", { respond })`: catch a request matching a
+* method and a path pattern, and answer it with a canned reply.
+*
+* A `respond` that is not already a response is taken as the body, with status
+* 200, so a plain map can be handed straight in.
+*/
+const intercept = defineAction({
+	name: "intercept",
+	doc: "Register an interceptor, e.g. mock.intercept(\"POST\", \"**/charge\", { respond }).",
+	params: z.object({ respond: z.unknown().optional() }).optional(),
+	args: [arg("method", t.string, "Which verb to catch: `GET`, `POST`, `*` for any."), arg("url", t.string, "Which URL to catch. A pattern is allowed.")],
+	result: t.ref("mock.Interceptor"),
+	run: (_ctx, input) => registerIntercept(input)
+});
+function registerIntercept(input) {
+	const params = input.params ?? {};
+	const entry = {
+		method: String(input.args[0] ?? "GET"),
+		path: String(input.args[1] ?? ""),
+		respond: toResponse(params.respond)
+	};
+	getMockState().intercepts.push(entry);
+	return entry;
+}
+/** `mock.respond(status, { body })`: build a canned reply for an interceptor. */
+const respond = defineAction({
+	name: "respond",
+	doc: "Build a canned response for an interceptor.",
+	params: z.object({
+		status: z.number().optional(),
+		body: z.unknown().optional()
+	}).optional(),
+	args: [arg("status", t.number, "The status code to answer with."), arg("body", t.dynamic, "What to answer with. A map or list is sent as JSON.")],
+	result: t.ref("mock.Response"),
+	run: (_ctx, input) => buildResponse(input)
+});
+function buildResponse(input) {
+	const params = input.params ?? {};
+	return {
+		status: input.args[0] === void 0 ? params.status ?? 200 : Number(input.args[0]),
+		body: params.body ?? input.args[1] ?? null
+	};
+}
+function toResponse(value) {
+	if (isResponse(value)) return value;
+	return {
+		status: 200,
+		body: value ?? null
+	};
+}
+function isResponse(value) {
+	return typeof value === "object" && value !== null && "status" in value && "body" in value;
+}
+//#endregion
+//#region src/actions/lifecycle-actions.ts
+/**
+* `mock.start("payments", { from: "openapi.yaml" })`: register a named mock
+* service. Starting a name twice replaces the earlier registration.
+*/
+const start = defineAction({
+	name: "start",
+	doc: "Register a named mock service.",
+	params: z.object({ from: z.string().optional() }).optional(),
+	args: [arg("name", t.string, "What to call this mock, so it can be reached later.")],
+	result: t.ref("mock.Mock"),
+	run: (_ctx, input) => startMock(input)
+});
+function startMock(input) {
+	const params = input.params ?? {};
+	const name = String(input.args[0] ?? "");
+	const mock = {
+		name,
+		from: params.from
+	};
+	getMockState().mocks.set(name, mock);
+	return mock;
+}
+/** `mock.stop()`: clear the active mocks and interceptors. Flags and clock survive. */
+const stop = defineAction({
+	name: "stop",
+	doc: "Clear all registered mocks and interceptors.",
+	result: t.void,
+	run: () => stopMocks()
+});
+function stopMocks() {
+	const state = getMockState();
+	state.mocks.clear();
+	state.intercepts.length = 0;
+}
+//#endregion
+//#region src/actions/index.ts
+/** Every verb in the `mock` namespace, in the order the editor lists them. */
+const mockActions = [
+	start,
+	stop,
+	intercept,
+	respond,
+	clockFreeze,
+	clockAdvance,
+	flag,
+	defineAction({
+		name: "reset",
+		doc: "Reset all mock state to empty.",
+		result: t.void,
+		run: () => resetMockState()
+	})
+];
+//#endregion
+//#region src/plugin.ts
+/**
+* The `mock` plugin: in-process mocking, feature flags and a virtual clock.
+*
+* Everything it does happens in memory, so it needs no host capability and
+* opens no socket. It publishes `mock.Mock`, `mock.Interceptor` and
+* `mock.Response` so a flow can name what its verbs hand back.
+*/
+const mockPlugin = definePlugin({
+	name: "venn/mock",
+	version: "0.0.0",
+	namespace: "mock",
+	actions: mockActions,
+	typeDefs: {
+		/** A registered mock service. `from` names what it was seeded from. */
+		Mock: t.record({
+			name: t.string,
+			from: t.string
+		}, { optional: ["from"] }),
+		/** One registered interception: what to match, and what to answer with. */
+		Interceptor: t.record({
+			method: t.string,
+			path: t.string,
+			respond: t.ref("mock.Response")
+		}),
+		/** A canned reply. The body is whatever the flow put there. */
+		Response: t.record({
+			status: t.number,
+			body: t.dynamic
+		})
+	}
+});
+//#endregion
+export { createMockState, mockPlugin as default, mockPlugin, getMockState, mockActions, resetMockState };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/state/create-mock-state.ts","../src/state/shared-state.ts","../src/actions/clock-actions.ts","../src/actions/flag-actions.ts","../src/actions/intercept-actions.ts","../src/actions/lifecycle-actions.ts","../src/actions/index.ts","../src/types.ts","../src/plugin.ts"],"sourcesContent":["import type { MockState } from \"./mock-state.types.js\";\n\n/**\n * Builds an empty mock state: no mocks, no interceptors, no flags, clock live.\n *\n * @returns A state nothing else holds. `getMockState` returns the shared one\n * the verbs actually read.\n */\nexport function createMockState(): MockState {\n  return {\n    mocks: new Map(),\n    intercepts: [],\n    flags: new Map(),\n    frozenInstant: undefined,\n  };\n}\n","import { createMockState } from \"./create-mock-state.js\";\nimport type { MockState } from \"./mock-state.types.js\";\n\nlet shared: MockState = createMockState();\n\n/**\n * The mock state every `mock` verb reads and writes.\n *\n * One state per process, so everything running in that process sees the same\n * mocks, flags and clock.\n *\n * @returns The live state. It is mutable: writing to it is how the verbs work.\n */\nexport function getMockState(): MockState {\n  return shared;\n}\n\n/**\n * Replaces the shared state with an empty one. Backs `mock.reset`, and lets a\n * test start from a known state.\n *\n * Callers holding the object from a previous {@link getMockState} keep the old\n * one, which no verb reads any more.\n */\nexport function resetMockState(): void {\n  shared = createMockState();\n}\n","import {\n  type ActionDefinition,\n  type ActionInput,\n  arg,\n  Duration,\n  defineAction,\n} from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { getMockState } from \"../state/index.js\";\n\n/**\n * `mock.clock.freeze(\"2026-01-01T00:00:00Z\")`: pin virtual time to an instant.\n *\n * The instant is only recorded in mock state. It does not drive the host clock,\n * so a verb that asks the host what time it is still gets the real answer.\n */\nexport const clockFreeze: ActionDefinition = defineAction({\n  name: \"clock.freeze\",\n  doc: \"Freeze virtual time at the given instant (recorded in mock state only, for now).\",\n  args: [arg(\"at\", t.union(t.string, t.number, t.instant), \"The instant to hold time at.\")],\n  result: t.number,\n  run: (_ctx, input) => freezeClock(input),\n});\n\nfunction freezeClock(input: ActionInput<unknown>): number {\n  const instant = toInstant(input.args[0]);\n  getMockState().frozenInstant = instant;\n  return instant;\n}\n\nfunction toInstant(value: unknown): number {\n  if (typeof value === \"number\") return value;\n  const epochMs = instantValue(value);\n  if (epochMs !== undefined) return epochMs;\n  const ms = Date.parse(String(value));\n  return Number.isNaN(ms) ? 0 : ms;\n}\n\n/**\n * `mock.clock.advance(\"1h\")`: move the stored virtual time forward by a span.\n *\n * Advancing an unfrozen clock counts from the epoch, since there is no instant\n * to move from.\n */\nexport const clockAdvance: ActionDefinition = defineAction({\n  name: \"clock.advance\",\n  doc: 'Advance the frozen virtual time by a duration, e.g. mock.clock.advance(\"1h\").',\n  args: [arg(\"by\", t.union(t.string, t.number, t.duration), \"How far to move time forward.\")],\n  result: t.number,\n  run: (_ctx, input) => advanceClock(input),\n});\n\nfunction advanceClock(input: ActionInput<unknown>): number {\n  const state = getMockState();\n  const next = (state.frozenInstant ?? 0) + durationMs(input);\n  state.frozenInstant = next;\n  return next;\n}\n\nfunction durationMs(input: ActionInput<unknown>): number {\n  const params = (input.params ?? {}) as { by?: unknown };\n  const given = input.args[0] ?? params.by;\n  const ms = durationValue(given);\n  if (ms !== undefined) return ms;\n  const parsed = Duration.safeParse(given);\n  return parsed.success ? parsed.data : 0;\n}\n\n/**\n * The number inside a unit value, when the argument is one.\n *\n * `1h` and `2026-07-23T12:00:00Z` reach an action as `{ kind, ms }` and\n * `{ kind, epochMs }`, the language's own literals rather than strings. Without\n * this unwrapping they parse to `NaN` and the clock silently sits at the epoch.\n */\nfunction durationValue(value: unknown): number | undefined {\n  const unit = value as { kind?: string; ms?: number } | null | undefined;\n  return unit?.kind === \"duration\" ? (unit.ms ?? 0) : undefined;\n}\n\nfunction instantValue(value: unknown): number | undefined {\n  const unit = value as { kind?: string; epochMs?: number } | null | undefined;\n  return unit?.kind === \"instant\" ? (unit.epochMs ?? 0) : undefined;\n}\n","import { type ActionDefinition, type ActionInput, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { getMockState } from \"../state/index.js\";\n\n/**\n * `mock.flag(\"new-checkout\", { value: \"b\" })`: set a feature flag.\n *\n * The flag's value is an option rather than a second positional argument, so\n * the common case, turning a flag on, reads as `mock.flag(\"new-checkout\")`.\n */\nexport const flag: ActionDefinition = defineAction({\n  name: \"flag\",\n  doc: \"Set a feature flag; the value comes from opts or defaults to true.\",\n  params: z.object({ value: z.unknown().optional() }).optional(),\n  args: [arg(\"name\", t.string, \"Which flag. Its value is an option, true by default.\")],\n  result: t.dynamic,\n  run: (_ctx, input) => setFlag(input),\n});\n\nfunction setFlag(input: ActionInput<unknown>): unknown {\n  const params = (input.params ?? {}) as { value?: unknown };\n  const name = String(input.args[0] ?? \"\");\n  const value = params.value ?? true;\n  getMockState().flags.set(name, value);\n  return value;\n}\n","import { type ActionDefinition, type ActionInput, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { getMockState, type Interceptor, type MockResponse } from \"../state/index.js\";\n\n/**\n * `mock.intercept(\"POST\", \"/charge\", { respond })`: catch a request matching a\n * method and a path pattern, and answer it with a canned reply.\n *\n * A `respond` that is not already a response is taken as the body, with status\n * 200, so a plain map can be handed straight in.\n */\nexport const intercept: ActionDefinition = defineAction({\n  name: \"intercept\",\n  doc: 'Register an interceptor, e.g. mock.intercept(\"POST\", \"**/charge\", { respond }).',\n  params: z.object({ respond: z.unknown().optional() }).optional(),\n  args: [\n    arg(\"method\", t.string, \"Which verb to catch: `GET`, `POST`, `*` for any.\"),\n    arg(\"url\", t.string, \"Which URL to catch. A pattern is allowed.\"),\n  ],\n  result: t.ref(\"mock.Interceptor\"),\n  run: (_ctx, input) => registerIntercept(input),\n});\n\nfunction registerIntercept(input: ActionInput<unknown>): Interceptor {\n  const params = (input.params ?? {}) as { respond?: unknown };\n  const entry: Interceptor = {\n    method: String(input.args[0] ?? \"GET\"),\n    path: String(input.args[1] ?? \"\"),\n    respond: toResponse(params.respond),\n  };\n  getMockState().intercepts.push(entry);\n  return entry;\n}\n\n/** `mock.respond(status, { body })`: build a canned reply for an interceptor. */\nexport const respond: ActionDefinition = defineAction({\n  name: \"respond\",\n  doc: \"Build a canned response for an interceptor.\",\n  params: z.object({ status: z.number().optional(), body: z.unknown().optional() }).optional(),\n  // Status and body may arrive positionally or by name, and `run` reads\n  // whichever came. The name wins for the body, the position wins for the status.\n  args: [\n    arg(\"status\", t.number, \"The status code to answer with.\"),\n    arg(\"body\", t.dynamic, \"What to answer with. A map or list is sent as JSON.\"),\n  ],\n  result: t.ref(\"mock.Response\"),\n  run: (_ctx, input) => buildResponse(input),\n});\n\nfunction buildResponse(input: ActionInput<unknown>): MockResponse {\n  const params = (input.params ?? {}) as { status?: number; body?: unknown };\n  const status = input.args[0] === undefined ? (params.status ?? 200) : Number(input.args[0]);\n  return { status, body: params.body ?? input.args[1] ?? null };\n}\n\nfunction toResponse(value: unknown): MockResponse {\n  if (isResponse(value)) return value;\n  return { status: 200, body: value ?? null };\n}\n\nfunction isResponse(value: unknown): value is MockResponse {\n  return typeof value === \"object\" && value !== null && \"status\" in value && \"body\" in value;\n}\n","import { type ActionDefinition, type ActionInput, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { getMockState, type NamedMock, resetMockState } from \"../state/index.js\";\n\n/**\n * `mock.start(\"payments\", { from: \"openapi.yaml\" })`: register a named mock\n * service. Starting a name twice replaces the earlier registration.\n */\nexport const start: ActionDefinition = defineAction({\n  name: \"start\",\n  doc: \"Register a named mock service.\",\n  params: z.object({ from: z.string().optional() }).optional(),\n  args: [arg(\"name\", t.string, \"What to call this mock, so it can be reached later.\")],\n  result: t.ref(\"mock.Mock\"),\n  run: (_ctx, input) => startMock(input),\n});\n\nfunction startMock(input: ActionInput<unknown>): NamedMock {\n  const params = (input.params ?? {}) as { from?: string };\n  const name = String(input.args[0] ?? \"\");\n  const mock: NamedMock = { name, from: params.from };\n  getMockState().mocks.set(name, mock);\n  return mock;\n}\n\n/** `mock.stop()`: clear the active mocks and interceptors. Flags and clock survive. */\nexport const stop: ActionDefinition = defineAction({\n  name: \"stop\",\n  doc: \"Clear all registered mocks and interceptors.\",\n  result: t.void,\n  run: () => stopMocks(),\n});\n\nfunction stopMocks(): void {\n  const state = getMockState();\n  state.mocks.clear();\n  state.intercepts.length = 0;\n}\n\n/** `mock.reset()`: clear every piece of mock state, the flags and the clock included. */\nexport const reset: ActionDefinition = defineAction({\n  name: \"reset\",\n  doc: \"Reset all mock state to empty.\",\n  result: t.void,\n  run: () => resetMockState(),\n});\n","import type { ActionDefinition } from \"@venn-lang/sdk\";\nimport { clockAdvance, clockFreeze } from \"./clock-actions.js\";\nimport { flag } from \"./flag-actions.js\";\nimport { intercept, respond } from \"./intercept-actions.js\";\nimport { reset, start, stop } from \"./lifecycle-actions.js\";\n\n/** Every verb in the `mock` namespace, in the order the editor lists them. */\nexport const mockActions: ActionDefinition[] = [\n  start,\n  stop,\n  intercept,\n  respond,\n  clockFreeze,\n  clockAdvance,\n  flag,\n  reset,\n];\n","import { type TypeSpec, t } from \"@venn-lang/types\";\n\n/**\n * The types `@venn-lang/mock` publishes: `mock.Mock`, `mock.Interceptor` and\n * `mock.Response`.\n *\n * They mirror `state/mock-state.types.ts` by hand, dropping the prefix the\n * namespace already supplies (`NamedMock` becomes `Mock`). Change one side and\n * the other has to follow.\n */\nexport const mockTypeDefs: Readonly<Record<string, TypeSpec>> = {\n  /** A registered mock service. `from` names what it was seeded from. */\n  Mock: t.record({ name: t.string, from: t.string }, { optional: [\"from\"] }),\n  /** One registered interception: what to match, and what to answer with. */\n  Interceptor: t.record({\n    method: t.string,\n    path: t.string,\n    respond: t.ref(\"mock.Response\"),\n  }),\n  /** A canned reply. The body is whatever the flow put there. */\n  Response: t.record({ status: t.number, body: t.dynamic }),\n};\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { mockActions } from \"./actions/index.js\";\nimport { mockTypeDefs } from \"./types.js\";\n\n/**\n * The `mock` plugin: in-process mocking, feature flags and a virtual clock.\n *\n * Everything it does happens in memory, so it needs no host capability and\n * opens no socket. It publishes `mock.Mock`, `mock.Interceptor` and\n * `mock.Response` so a flow can name what its verbs hand back.\n */\nexport const mockPlugin: PluginDefinition = definePlugin({\n  name: \"venn/mock\",\n  version: \"0.0.0\",\n  namespace: \"mock\",\n  actions: mockActions,\n  typeDefs: mockTypeDefs,\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@venn-lang/mock",
+  "version": "0.1.0",
+  "description": "The mock namespace: named mocks, HTTP interceptors, feature flags and a virtual clock.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "mock"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-mock#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-mock"
+  },
+  "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"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/contracts": "0.1.0",
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/clock-actions.ts

@@ -0,0 +1,84 @@
+import {
+  type ActionDefinition,
+  type ActionInput,
+  arg,
+  Duration,
+  defineAction,
+} from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { getMockState } from "../state/index.js";
+
+/**
+ * `mock.clock.freeze("2026-01-01T00:00:00Z")`: pin virtual time to an instant.
+ *
+ * The instant is only recorded in mock state. It does not drive the host clock,
+ * so a verb that asks the host what time it is still gets the real answer.
+ */
+export const clockFreeze: ActionDefinition = defineAction({
+  name: "clock.freeze",
+  doc: "Freeze virtual time at the given instant (recorded in mock state only, for now).",
+  args: [arg("at", t.union(t.string, t.number, t.instant), "The instant to hold time at.")],
+  result: t.number,
+  run: (_ctx, input) => freezeClock(input),
+});
+
+function freezeClock(input: ActionInput<unknown>): number {
+  const instant = toInstant(input.args[0]);
+  getMockState().frozenInstant = instant;
+  return instant;
+}
+
+function toInstant(value: unknown): number {
+  if (typeof value === "number") return value;
+  const epochMs = instantValue(value);
+  if (epochMs !== undefined) return epochMs;
+  const ms = Date.parse(String(value));
+  return Number.isNaN(ms) ? 0 : ms;
+}
+
+/**
+ * `mock.clock.advance("1h")`: move the stored virtual time forward by a span.
+ *
+ * Advancing an unfrozen clock counts from the epoch, since there is no instant
+ * to move from.
+ */
+export const clockAdvance: ActionDefinition = defineAction({
+  name: "clock.advance",
+  doc: 'Advance the frozen virtual time by a duration, e.g. mock.clock.advance("1h").',
+  args: [arg("by", t.union(t.string, t.number, t.duration), "How far to move time forward.")],
+  result: t.number,
+  run: (_ctx, input) => advanceClock(input),
+});
+
+function advanceClock(input: ActionInput<unknown>): number {
+  const state = getMockState();
+  const next = (state.frozenInstant ?? 0) + durationMs(input);
+  state.frozenInstant = next;
+  return next;
+}
+
+function durationMs(input: ActionInput<unknown>): number {
+  const params = (input.params ?? {}) as { by?: unknown };
+  const given = input.args[0] ?? params.by;
+  const ms = durationValue(given);
+  if (ms !== undefined) return ms;
+  const parsed = Duration.safeParse(given);
+  return parsed.success ? parsed.data : 0;
+}
+
+/**
+ * The number inside a unit value, when the argument is one.
+ *
+ * `1h` and `2026-07-23T12:00:00Z` reach an action as `{ kind, ms }` and
+ * `{ kind, epochMs }`, the language's own literals rather than strings. Without
+ * this unwrapping they parse to `NaN` and the clock silently sits at the epoch.
+ */
+function durationValue(value: unknown): number | undefined {
+  const unit = value as { kind?: string; ms?: number } | null | undefined;
+  return unit?.kind === "duration" ? (unit.ms ?? 0) : undefined;
+}
+
+function instantValue(value: unknown): number | undefined {
+  const unit = value as { kind?: string; epochMs?: number } | null | undefined;
+  return unit?.kind === "instant" ? (unit.epochMs ?? 0) : undefined;
+}

package/src/actions/flag-actions.ts

@@ -0,0 +1,26 @@
+import { type ActionDefinition, type ActionInput, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { getMockState } from "../state/index.js";
+
+/**
+ * `mock.flag("new-checkout", { value: "b" })`: set a feature flag.
+ *
+ * The flag's value is an option rather than a second positional argument, so
+ * the common case, turning a flag on, reads as `mock.flag("new-checkout")`.
+ */
+export const flag: ActionDefinition = defineAction({
+  name: "flag",
+  doc: "Set a feature flag; the value comes from opts or defaults to true.",
+  params: z.object({ value: z.unknown().optional() }).optional(),
+  args: [arg("name", t.string, "Which flag. Its value is an option, true by default.")],
+  result: t.dynamic,
+  run: (_ctx, input) => setFlag(input),
+});
+
+function setFlag(input: ActionInput<unknown>): unknown {
+  const params = (input.params ?? {}) as { value?: unknown };
+  const name = String(input.args[0] ?? "");
+  const value = params.value ?? true;
+  getMockState().flags.set(name, value);
+  return value;
+}

package/src/actions/index.ts

@@ -0,0 +1,17 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+import { clockAdvance, clockFreeze } from "./clock-actions.js";
+import { flag } from "./flag-actions.js";
+import { intercept, respond } from "./intercept-actions.js";
+import { reset, start, stop } from "./lifecycle-actions.js";
+
+/** Every verb in the `mock` namespace, in the order the editor lists them. */
+export const mockActions: ActionDefinition[] = [
+  start,
+  stop,
+  intercept,
+  respond,
+  clockFreeze,
+  clockAdvance,
+  flag,
+  reset,
+];

package/src/actions/intercept-actions.ts

@@ -0,0 +1,63 @@
+import { type ActionDefinition, type ActionInput, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { getMockState, type Interceptor, type MockResponse } from "../state/index.js";
+
+/**
+ * `mock.intercept("POST", "/charge", { respond })`: catch a request matching a
+ * method and a path pattern, and answer it with a canned reply.
+ *
+ * A `respond` that is not already a response is taken as the body, with status
+ * 200, so a plain map can be handed straight in.
+ */
+export const intercept: ActionDefinition = defineAction({
+  name: "intercept",
+  doc: 'Register an interceptor, e.g. mock.intercept("POST", "**/charge", { respond }).',
+  params: z.object({ respond: z.unknown().optional() }).optional(),
+  args: [
+    arg("method", t.string, "Which verb to catch: `GET`, `POST`, `*` for any."),
+    arg("url", t.string, "Which URL to catch. A pattern is allowed."),
+  ],
+  result: t.ref("mock.Interceptor"),
+  run: (_ctx, input) => registerIntercept(input),
+});
+
+function registerIntercept(input: ActionInput<unknown>): Interceptor {
+  const params = (input.params ?? {}) as { respond?: unknown };
+  const entry: Interceptor = {
+    method: String(input.args[0] ?? "GET"),
+    path: String(input.args[1] ?? ""),
+    respond: toResponse(params.respond),
+  };
+  getMockState().intercepts.push(entry);
+  return entry;
+}
+
+/** `mock.respond(status, { body })`: build a canned reply for an interceptor. */
+export const respond: ActionDefinition = defineAction({
+  name: "respond",
+  doc: "Build a canned response for an interceptor.",
+  params: z.object({ status: z.number().optional(), body: z.unknown().optional() }).optional(),
+  // Status and body may arrive positionally or by name, and `run` reads
+  // whichever came. The name wins for the body, the position wins for the status.
+  args: [
+    arg("status", t.number, "The status code to answer with."),
+    arg("body", t.dynamic, "What to answer with. A map or list is sent as JSON."),
+  ],
+  result: t.ref("mock.Response"),
+  run: (_ctx, input) => buildResponse(input),
+});
+
+function buildResponse(input: ActionInput<unknown>): MockResponse {
+  const params = (input.params ?? {}) as { status?: number; body?: unknown };
+  const status = input.args[0] === undefined ? (params.status ?? 200) : Number(input.args[0]);
+  return { status, body: params.body ?? input.args[1] ?? null };
+}
+
+function toResponse(value: unknown): MockResponse {
+  if (isResponse(value)) return value;
+  return { status: 200, body: value ?? null };
+}
+
+function isResponse(value: unknown): value is MockResponse {
+  return typeof value === "object" && value !== null && "status" in value && "body" in value;
+}

package/src/actions/lifecycle-actions.ts

@@ -0,0 +1,46 @@
+import { type ActionDefinition, type ActionInput, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { getMockState, type NamedMock, resetMockState } from "../state/index.js";
+
+/**
+ * `mock.start("payments", { from: "openapi.yaml" })`: register a named mock
+ * service. Starting a name twice replaces the earlier registration.
+ */
+export const start: ActionDefinition = defineAction({
+  name: "start",
+  doc: "Register a named mock service.",
+  params: z.object({ from: z.string().optional() }).optional(),
+  args: [arg("name", t.string, "What to call this mock, so it can be reached later.")],
+  result: t.ref("mock.Mock"),
+  run: (_ctx, input) => startMock(input),
+});
+
+function startMock(input: ActionInput<unknown>): NamedMock {
+  const params = (input.params ?? {}) as { from?: string };
+  const name = String(input.args[0] ?? "");
+  const mock: NamedMock = { name, from: params.from };
+  getMockState().mocks.set(name, mock);
+  return mock;
+}
+
+/** `mock.stop()`: clear the active mocks and interceptors. Flags and clock survive. */
+export const stop: ActionDefinition = defineAction({
+  name: "stop",
+  doc: "Clear all registered mocks and interceptors.",
+  result: t.void,
+  run: () => stopMocks(),
+});
+
+function stopMocks(): void {
+  const state = getMockState();
+  state.mocks.clear();
+  state.intercepts.length = 0;
+}
+
+/** `mock.reset()`: clear every piece of mock state, the flags and the clock included. */
+export const reset: ActionDefinition = defineAction({
+  name: "reset",
+  doc: "Reset all mock state to empty.",
+  result: t.void,
+  run: () => resetMockState(),
+});

package/src/index.ts

@@ -0,0 +1,8 @@
+// The `mock` namespace: named mock services, HTTP interceptors, feature flags
+// and a virtual clock, all in-process. State lives in one shared MockState the
+// actions read and write; tests reach it through getMockState(). No network,
+// no port.
+
+export { mockActions } from "./actions/index.js";
+export { mockPlugin, mockPlugin as default } from "./plugin.js";
+export * from "./state/index.js";

package/src/plugin.ts

@@ -0,0 +1,18 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { mockActions } from "./actions/index.js";
+import { mockTypeDefs } from "./types.js";
+
+/**
+ * The `mock` plugin: in-process mocking, feature flags and a virtual clock.
+ *
+ * Everything it does happens in memory, so it needs no host capability and
+ * opens no socket. It publishes `mock.Mock`, `mock.Interceptor` and
+ * `mock.Response` so a flow can name what its verbs hand back.
+ */
+export const mockPlugin: PluginDefinition = definePlugin({
+  name: "venn/mock",
+  version: "0.0.0",
+  namespace: "mock",
+  actions: mockActions,
+  typeDefs: mockTypeDefs,
+});

package/src/state/create-mock-state.ts

@@ -0,0 +1,16 @@
+import type { MockState } from "./mock-state.types.js";
+
+/**
+ * Builds an empty mock state: no mocks, no interceptors, no flags, clock live.
+ *
+ * @returns A state nothing else holds. `getMockState` returns the shared one
+ * the verbs actually read.
+ */
+export function createMockState(): MockState {
+  return {
+    mocks: new Map(),
+    intercepts: [],
+    flags: new Map(),
+    frozenInstant: undefined,
+  };
+}

package/src/state/index.ts

@@ -0,0 +1,3 @@
+export { createMockState } from "./create-mock-state.js";
+export type { Interceptor, MockResponse, MockState, NamedMock } from "./mock-state.types.js";
+export { getMockState, resetMockState } from "./shared-state.js";

package/src/state/mock-state.types.ts

@@ -0,0 +1,27 @@
+/** A canned response an interceptor replies with. */
+export interface MockResponse {
+  status: number;
+  body: unknown;
+}
+
+/** A registered interception: match a method and a path pattern, reply with `respond`. */
+export interface Interceptor {
+  method: string;
+  path: string;
+  respond: MockResponse;
+}
+
+/** A named mock service, optionally seeded from a source such as an OpenAPI file. */
+export interface NamedMock {
+  name: string;
+  from?: string;
+}
+
+/** The in-process, mutable state the `mock` namespace reads and writes. */
+export interface MockState {
+  mocks: Map<string, NamedMock>;
+  intercepts: Interceptor[];
+  flags: Map<string, unknown>;
+  /** Virtual "now" in epoch ms once frozen; `undefined` while the clock is live. */
+  frozenInstant?: number;
+}

package/src/state/shared-state.ts

@@ -0,0 +1,27 @@
+import { createMockState } from "./create-mock-state.js";
+import type { MockState } from "./mock-state.types.js";
+
+let shared: MockState = createMockState();
+
+/**
+ * The mock state every `mock` verb reads and writes.
+ *
+ * One state per process, so everything running in that process sees the same
+ * mocks, flags and clock.
+ *
+ * @returns The live state. It is mutable: writing to it is how the verbs work.
+ */
+export function getMockState(): MockState {
+  return shared;
+}
+
+/**
+ * Replaces the shared state with an empty one. Backs `mock.reset`, and lets a
+ * test start from a known state.
+ *
+ * Callers holding the object from a previous {@link getMockState} keep the old
+ * one, which no verb reads any more.
+ */
+export function resetMockState(): void {
+  shared = createMockState();
+}

package/src/types.ts

@@ -0,0 +1,22 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The types `@venn-lang/mock` publishes: `mock.Mock`, `mock.Interceptor` and
+ * `mock.Response`.
+ *
+ * They mirror `state/mock-state.types.ts` by hand, dropping the prefix the
+ * namespace already supplies (`NamedMock` becomes `Mock`). Change one side and
+ * the other has to follow.
+ */
+export const mockTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /** A registered mock service. `from` names what it was seeded from. */
+  Mock: t.record({ name: t.string, from: t.string }, { optional: ["from"] }),
+  /** One registered interception: what to match, and what to answer with. */
+  Interceptor: t.record({
+    method: t.string,
+    path: t.string,
+    respond: t.ref("mock.Response"),
+  }),
+  /** A canned reply. The body is whatever the flow put there. */
+  Response: t.record({ status: t.number, body: t.dynamic }),
+};