@venn-lang/artifacts 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,125 @@
+# @venn-lang/artifacts
+
+> The `artifacts` namespace: record the traces, videos, HARs and screenshots a run produces.
+
+A flow that fails is only useful if you can see what it left behind. This plugin gives a run three
+verbs for filing artifacts and hands every one of them to the `ArtifactStore` port, so where the
+bytes actually live is a decision the host makes at startup and not something baked into the
+language.
+
+## Install
+
+Nothing to install. `@venn-lang/artifacts` is part of the standard library, and the CLI and the language
+server both load [`@venn-lang/stdlib`](../stdlib), which lists every stdlib plugin. A file reaches the
+namespace with one line.
+
+```ruby
+use "venn/artifacts"
+```
+
+## Usage
+
+```ruby
+module demo.checkout
+
+use "venn/artifacts"
+use "venn/assert"
+
+afterEach { artifacts.flush }
+
+flow "Checkout" {
+  step "place the order" {
+    expect true
+  }
+
+  on failure {
+    artifacts.save "trace" "video" "har"
+  }
+}
+```
+
+## Verbs
+
+| Verb | Call | Result |
+| --- | --- | --- |
+| `artifacts.save` | `artifacts.save "trace" "video" "har"` | `list<artifacts.ArtifactRef>`, one ref per kind |
+| `artifacts.flush` | `artifacts.flush` | the refs stored since the last flush, now drained |
+| `artifacts.attach` | `artifacts.attach "report.html" { kind: "report", size: 2048 }` | one `artifacts.ArtifactRef` |
+
+`artifacts.save` takes as many kinds as you hand it. The vocabulary has no variadic, so the verb is
+declared with `restArg`: the first argument says what a kind is and the ones past it are left
+unchecked, which is better than describing them wrongly. Both call spellings work, with spaces in
+the bareword form and commas inside brackets:
+
+```ruby
+artifacts.save "trace" "video" "har"
+artifacts.save("trace", "video", "har")
+```
+
+`artifacts.attach` names the artifact positionally; `kind` (default `"attachment"`) and `size` are
+options. `flush` drains the pending buffer and leaves the stored refs in place, so calling it twice
+in a row returns an empty list the second time.
+
+## The type it publishes
+
+`artifacts.ArtifactRef` is a record of `name: string`, `kind: string` and an optional
+`size: number`. It is what every verb hands back, and what hover and completion in the editor read.
+
+## The ArtifactStore port
+
+| | |
+| --- | --- |
+| id | `venn.port.artifact-store` |
+| version | 1 |
+| requires | `fs` |
+| methods | `put`, `get`, `list`, `flush` |
+
+Two implementations ship together, which is what makes this a port rather than a module with a good
+interface:
+
+- `createMemoryArtifactStore()` keeps a `Map` of stored refs plus a pending buffer. This is the one
+  [`@venn-lang/stdlib`](../stdlib) binds, so the verbs work offline.
+- `createRealArtifactStore()` is a stub. Every call throws a `VennError` with code `VN8090`, because
+  this repository is the language and ships no real storage backend.
+
+Both run the same conformance suite, `artifactStoreConformance` in
+`src/store/artifact-store.suite.ts`. A third implementation is one file, one line in the local
+`index.ts` and one line in the test.
+
+The port lists `flush` among its methods on purpose. A method the descriptor leaves out is a method
+nobody checks at load time, and it would surface as a `TypeError` mid-run instead of a legible
+`VN2011` before anything starts.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `artifactsPlugin` | The plugin definition: namespace `artifacts`, `requires: ["fs"]`. Also the default export. |
+| `ArtifactStorePort` | The port descriptor. |
+| `ArtifactStore` | The port interface: `put`, `get`, `list`, `flush`. |
+| `createMemoryArtifactStore()` | The in-memory double. |
+| `createRealArtifactStore()` | The real store, stubbed to throw `VN8090`. |
+| `ArtifactRef` | The TypeScript type: `{ name, kind, size? }`. |
+| `ArtifactRefSchema` | The Zod schema registered as the plugin's nominal `ArtifactRef` type. |
+| `artifactsTypeDefs` | The `TypeSpec` for `artifacts.ArtifactRef`, which the checker and the LSP read. |
+
+Binding a different store means one entry in the runner's port list:
+
+```ts
+import { ArtifactStorePort, createMemoryArtifactStore } from "@venn-lang/artifacts";
+import { createRunner } from "@venn-lang/runtime";
+
+const runner = createRunner({
+  host,
+  plugins,
+  sink,
+  uri,
+  ports: [{ port: ArtifactStorePort, impl: createMemoryArtifactStore() }],
+});
+```
+
+## See also
+
+- [`@venn-lang/sdk`](../sdk) for `definePlugin` and `defineAction`.
+- [`@venn-lang/contracts`](../contracts) for `Port`, `assertPortShape` and `VennError`.
+- [`@venn-lang/notify`](../std-notify) for telling someone about a run that failed.

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import { PluginDefinition, ZodType } from "@venn-lang/sdk";
+import { TypeSpec } from "@venn-lang/types";
+import { Port } from "@venn-lang/contracts";
+//#region src/plugin.d.ts
+/**
+ * The `@venn-lang/artifacts` plugin. Registers the `artifacts` namespace: the
+ * `save`, `flush` and `attach` verbs and the nominal `artifacts.ArtifactRef`
+ * type. Requires the `fs` capability, since the store writes to disk.
+ */
+declare const artifactsPlugin: PluginDefinition;
+//#endregion
+//#region src/types/artifact-ref.types.d.ts
+/**
+ * The receipt for a stored artifact: a trace, a video, a HAR, a screenshot.
+ * `kind` names the category. `size` is the byte count, absent until known.
+ */
+interface ArtifactRef {
+  name: string;
+  kind: string;
+  size?: number;
+}
+//#endregion
+//#region src/types/artifact-ref.schema.d.ts
+/** Runtime validator for the nominal `artifacts.ArtifactRef` type. */
+declare const ArtifactRefSchema: ZodType<ArtifactRef>;
+//#endregion
+//#region src/types/type-defs.d.ts
+/**
+ * The types `@venn-lang/artifacts` publishes to the checker, under the `artifacts`
+ * namespace. Kept as data, and mirroring `artifact-ref.types.ts` by hand, so a
+ * generator reading the emitted `.d.ts` can replace this file unnoticed.
+ */
+declare const artifactsTypeDefs: Readonly<Record<string, TypeSpec>>;
+//#endregion
+//#region src/store/artifact-store.types.d.ts
+/**
+ * Keeps references to what a run produced.
+ *
+ * `put`, `get` and `list` address the stored set. `flush` drains the pending
+ * buffer accumulated since the last flush, leaving the stored set untouched.
+ */
+interface ArtifactStore {
+  /** Stores a ref and queues it for the next flush. Returns the ref as stored. */
+  put(ref: ArtifactRef): Promise<ArtifactRef>;
+  get(name: string): Promise<ArtifactRef | undefined>;
+  list(): Promise<readonly ArtifactRef[]>;
+  flush(): Promise<readonly ArtifactRef[]>;
+}
+//#endregion
+//#region src/store/artifact-store.port.d.ts
+/**
+ * The port the `artifacts` verbs reach through to keep what a run produced.
+ * Requires the `fs` capability, so a host without it fails to load the plugin
+ * rather than failing mid-run.
+ */
+declare const ArtifactStorePort: Port<ArtifactStore>;
+//#endregion
+//#region src/store/memory-store.d.ts
+/**
+ * The in-memory `ArtifactStore` used by tests and by hosts without a disk.
+ *
+ * @returns a fresh store; nothing is shared between calls.
+ */
+declare function createMemoryArtifactStore(): ArtifactStore;
+//#endregion
+//#region src/store/real-store.d.ts
+/**
+ * The disk-backed `ArtifactStore`. Not wired up in this build.
+ *
+ * @returns a store whose every method throws, so the gap is a legible failure
+ * rather than a silent no-op.
+ * @throws {VennError} `VN8090` on any call.
+ */
+declare function createRealArtifactStore(): ArtifactStore;
+//#endregion
+export { type ArtifactRef, ArtifactRefSchema, type ArtifactStore, ArtifactStorePort, artifactsPlugin, artifactsPlugin as default, artifactsTypeDefs, createMemoryArtifactStore, createRealArtifactStore };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/plugin.ts","../src/types/artifact-ref.types.ts","../src/types/artifact-ref.schema.ts","../src/types/type-defs.ts","../src/store/artifact-store.types.ts","../src/store/artifact-store.port.ts","../src/store/memory-store.ts","../src/store/real-store.ts"],"mappings":";;;;;;;;;cASa,iBAAiB;;;;;;;UCLb;EACf;EACA;EACA;;;;;cCHW,mBAAmB,QAAQ;;;;;;;;cCG3B,mBAAmB,SAAS,eAAe;;;;;;;;;UCCvC;;EAEf,IAAI,KAAK,cAAc,QAAQ;EAC/B,IAAI,eAAe,QAAQ;EAC3B,QAAQ,iBAAiB;EACzB,SAAS,iBAAiB;;;;;;;;;cCLf,mBAAmB,KAAK;;;;;;;;iBCArB,6BAA6B;;;;;;;;;;iBCE7B,2BAA2B"}

package/dist/index.js

@@ -0,0 +1,195 @@
+import { arg, defineAction, definePlugin, restArg, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { VennError } from "@venn-lang/contracts";
+//#region src/store/artifact-store.port.ts
+/**
+* The port the `artifacts` verbs reach through to keep what a run produced.
+* Requires the `fs` capability, so a host without it fails to load the plugin
+* rather than failing mid-run.
+*/
+const ArtifactStorePort = {
+	id: "venn.port.artifact-store",
+	version: 1,
+	requires: ["fs"],
+	methods: [
+		"put",
+		"get",
+		"list",
+		"flush"
+	]
+};
+//#endregion
+//#region src/store/memory-store.ts
+/**
+* The in-memory `ArtifactStore` used by tests and by hosts without a disk.
+*
+* @returns a fresh store; nothing is shared between calls.
+*/
+function createMemoryArtifactStore() {
+	const stored = /* @__PURE__ */ new Map();
+	let pending = [];
+	return {
+		async put(ref) {
+			stored.set(ref.name, ref);
+			pending.push(ref);
+			return ref;
+		},
+		async get(name) {
+			return stored.get(name);
+		},
+		async list() {
+			return [...stored.values()];
+		},
+		async flush() {
+			const drained = pending;
+			pending = [];
+			return drained;
+		}
+	};
+}
+//#endregion
+//#region src/store/real-store.ts
+/**
+* The disk-backed `ArtifactStore`. Not wired up in this build.
+*
+* @returns a store whose every method throws, so the gap is a legible failure
+* rather than a silent no-op.
+* @throws {VennError} `VN8090` on any call.
+*/
+function createRealArtifactStore() {
+	return {
+		put: async () => notImplemented(),
+		get: async () => notImplemented(),
+		list: async () => notImplemented(),
+		flush: async () => notImplemented()
+	};
+}
+function notImplemented() {
+	throw new VennError({
+		code: "VN8090",
+		message: "The artifact store is not implemented in this build."
+	});
+}
+/**
+* `artifacts.attach "screenshot.png" { kind: "image", size: 4096 }`.
+*
+* Files one already existing artifact under a name so the report can show it.
+* `kind` defaults to `attachment` and `size` stays absent when not given.
+*
+* @returns the stored `artifacts.ArtifactRef`.
+*/
+const attachAction = defineAction({
+	name: "attach",
+	doc: "Attach an artifact by name, with an optional kind and size.",
+	params: z.object({
+		kind: z.string().optional(),
+		size: z.number().optional()
+	}).optional(),
+	args: [arg("name", t.string, "What to file it under.")],
+	result: t.ref("artifacts.ArtifactRef"),
+	run: (ctx, input) => ctx.port(ArtifactStorePort).put(buildRef(input))
+});
+function buildRef(input) {
+	const params = input.params ?? {};
+	return {
+		name: String(input.args[0] ?? ""),
+		kind: params.kind ?? "attachment",
+		size: params.size
+	};
+}
+//#endregion
+//#region src/actions/flush.ts
+/**
+* `artifacts.flush`.
+*
+* Persists everything buffered since the last flush and empties the buffer.
+* Stored refs survive; only the pending queue is drained.
+*
+* @returns the list of `artifacts.ArtifactRef` that were written out.
+*/
+const flushAction = defineAction({
+	name: "flush",
+	doc: "Flush pending artifacts, returning the refs that were drained.",
+	result: t.list(t.ref("artifacts.ArtifactRef")),
+	run: (ctx) => ctx.port(ArtifactStorePort).flush()
+});
+//#endregion
+//#region src/actions/save.ts
+/**
+* `artifacts.save trace video har`.
+*
+* Each positional argument names a kind of artifact to keep from this run. One
+* ref is stored per kind, in the order given.
+*
+* @returns the list of stored `artifacts.ArtifactRef`, one per kind.
+*/
+const saveAction = defineAction({
+	name: "save",
+	doc: "Store one artifact per positional kind ref and return the stored refs.",
+	args: [restArg("kinds", t.string, "One or more kinds to store, as positional arguments.")],
+	result: t.list(t.ref("artifacts.ArtifactRef")),
+	run: async (ctx, input) => {
+		const store = ctx.port(ArtifactStorePort);
+		return Promise.all(input.args.map((kind) => store.put(toRef(kind))));
+	}
+});
+function toRef(kind) {
+	const name = String(kind);
+	return {
+		name,
+		kind: name
+	};
+}
+//#endregion
+//#region src/actions/index.ts
+/** Every verb in the `artifacts` namespace, in the order the plugin registers them. */
+const artifactsActions = [
+	saveAction,
+	flushAction,
+	attachAction
+];
+//#endregion
+//#region src/types/artifact-ref.schema.ts
+/** Runtime validator for the nominal `artifacts.ArtifactRef` type. */
+const ArtifactRefSchema = z.object({
+	name: z.string(),
+	kind: z.string(),
+	size: z.number().optional()
+});
+//#endregion
+//#region src/types/type-defs.ts
+/**
+* The types `@venn-lang/artifacts` publishes to the checker, under the `artifacts`
+* namespace. Kept as data, and mirroring `artifact-ref.types.ts` by hand, so a
+* generator reading the emitted `.d.ts` can replace this file unnoticed.
+*/
+const artifactsTypeDefs = { 
+/**
+* The receipt for a stored artifact: a trace, a video, a HAR, a screenshot.
+* `size` is absent until the store knows how many bytes it kept.
+*/
+ArtifactRef: t.record({
+	name: t.string,
+	kind: t.string,
+	size: t.number
+}, { optional: ["size"] }) };
+//#endregion
+//#region src/plugin.ts
+/**
+* The `@venn-lang/artifacts` plugin. Registers the `artifacts` namespace: the
+* `save`, `flush` and `attach` verbs and the nominal `artifacts.ArtifactRef`
+* type. Requires the `fs` capability, since the store writes to disk.
+*/
+const artifactsPlugin = definePlugin({
+	name: "venn/artifacts",
+	version: "0.0.0",
+	namespace: "artifacts",
+	requires: ["fs"],
+	actions: artifactsActions,
+	types: { ArtifactRef: ArtifactRefSchema },
+	typeDefs: artifactsTypeDefs
+});
+//#endregion
+export { ArtifactRefSchema, ArtifactStorePort, artifactsPlugin, artifactsPlugin as default, artifactsTypeDefs, createMemoryArtifactStore, createRealArtifactStore };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/store/artifact-store.port.ts","../src/store/memory-store.ts","../src/store/real-store.ts","../src/actions/attach.ts","../src/actions/flush.ts","../src/actions/save.ts","../src/actions/index.ts","../src/types/artifact-ref.schema.ts","../src/types/type-defs.ts","../src/plugin.ts"],"sourcesContent":["import type { Port } from \"@venn-lang/contracts\";\nimport type { ArtifactStore } from \"./artifact-store.types.js\";\n\n/**\n * The port the `artifacts` verbs reach through to keep what a run produced.\n * Requires the `fs` capability, so a host without it fails to load the plugin\n * rather than failing mid-run.\n */\nexport const ArtifactStorePort: Port<ArtifactStore> = {\n  id: \"venn.port.artifact-store\",\n  version: 1,\n  requires: [\"fs\"],\n  // List every method an action reaches for. An omission is not checked at load\n  // time, so it surfaces as a TypeError mid-run instead of a legible VN2011.\n  methods: [\"put\", \"get\", \"list\", \"flush\"],\n};\n","import type { ArtifactRef } from \"../types/index.js\";\nimport type { ArtifactStore } from \"./artifact-store.types.js\";\n\n/**\n * The in-memory `ArtifactStore` used by tests and by hosts without a disk.\n *\n * @returns a fresh store; nothing is shared between calls.\n */\nexport function createMemoryArtifactStore(): ArtifactStore {\n  const stored = new Map<string, ArtifactRef>();\n  let pending: ArtifactRef[] = [];\n  return {\n    async put(ref) {\n      stored.set(ref.name, ref);\n      pending.push(ref);\n      return ref;\n    },\n    async get(name) {\n      return stored.get(name);\n    },\n    async list() {\n      return [...stored.values()];\n    },\n    async flush() {\n      const drained = pending;\n      pending = [];\n      return drained;\n    },\n  };\n}\n","import { VennError } from \"@venn-lang/contracts\";\nimport type { ArtifactStore } from \"./artifact-store.types.js\";\n\n/**\n * The disk-backed `ArtifactStore`. Not wired up in this build.\n *\n * @returns a store whose every method throws, so the gap is a legible failure\n * rather than a silent no-op.\n * @throws {VennError} `VN8090` on any call.\n */\nexport function createRealArtifactStore(): ArtifactStore {\n  return {\n    put: async () => notImplemented(),\n    get: async () => notImplemented(),\n    list: async () => notImplemented(),\n    flush: async () => notImplemented(),\n  };\n}\n\nfunction notImplemented(): never {\n  throw new VennError({\n    code: \"VN8090\",\n    message: \"The artifact store is not implemented in this build.\",\n  });\n}\n","import { type ActionDefinition, type ActionInput, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { ArtifactStorePort } from \"../store/index.js\";\nimport type { ArtifactRef } from \"../types/index.js\";\n\nconst attachParams = z.object({ kind: z.string().optional(), size: z.number().optional() });\n\n/**\n * `artifacts.attach \"screenshot.png\" { kind: \"image\", size: 4096 }`.\n *\n * Files one already existing artifact under a name so the report can show it.\n * `kind` defaults to `attachment` and `size` stays absent when not given.\n *\n * @returns the stored `artifacts.ArtifactRef`.\n */\nexport const attachAction: ActionDefinition = defineAction({\n  name: \"attach\",\n  doc: \"Attach an artifact by name, with an optional kind and size.\",\n  params: attachParams.optional(),\n  args: [arg(\"name\", t.string, \"What to file it under.\")],\n  result: t.ref(\"artifacts.ArtifactRef\"),\n  run: (ctx, input) => ctx.port(ArtifactStorePort).put(buildRef(input)),\n});\n\nfunction buildRef(input: ActionInput<unknown>): ArtifactRef {\n  const params = (input.params ?? {}) as { kind?: string; size?: number };\n  return {\n    name: String(input.args[0] ?? \"\"),\n    kind: params.kind ?? \"attachment\",\n    size: params.size,\n  };\n}\n","import { type ActionDefinition, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { ArtifactStorePort } from \"../store/index.js\";\n\n/**\n * `artifacts.flush`.\n *\n * Persists everything buffered since the last flush and empties the buffer.\n * Stored refs survive; only the pending queue is drained.\n *\n * @returns the list of `artifacts.ArtifactRef` that were written out.\n */\nexport const flushAction: ActionDefinition = defineAction({\n  name: \"flush\",\n  doc: \"Flush pending artifacts, returning the refs that were drained.\",\n  result: t.list(t.ref(\"artifacts.ArtifactRef\")),\n  run: (ctx) => ctx.port(ArtifactStorePort).flush(),\n});\n","import { type ActionDefinition, defineAction, restArg } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { ArtifactStorePort } from \"../store/index.js\";\nimport type { ArtifactRef } from \"../types/index.js\";\n\n/**\n * `artifacts.save trace video har`.\n *\n * Each positional argument names a kind of artifact to keep from this run. One\n * ref is stored per kind, in the order given.\n *\n * @returns the list of stored `artifacts.ArtifactRef`, one per kind.\n */\nexport const saveAction: ActionDefinition = defineAction({\n  name: \"save\",\n  doc: \"Store one artifact per positional kind ref and return the stored refs.\",\n  // The vocabulary has no variadic, so `restArg` types the first kind and\n  // leaves the rest unchecked. Better an unchecked argument than a wrong type.\n  args: [restArg(\"kinds\", t.string, \"One or more kinds to store, as positional arguments.\")],\n  result: t.list(t.ref(\"artifacts.ArtifactRef\")),\n  run: async (ctx, input) => {\n    const store = ctx.port(ArtifactStorePort);\n    return Promise.all(input.args.map((kind) => store.put(toRef(kind))));\n  },\n});\n\nfunction toRef(kind: unknown): ArtifactRef {\n  const name = String(kind);\n  return { name, kind: name };\n}\n","import type { ActionDefinition } from \"@venn-lang/sdk\";\nimport { attachAction } from \"./attach.js\";\nimport { flushAction } from \"./flush.js\";\nimport { saveAction } from \"./save.js\";\n\n/** Every verb in the `artifacts` namespace, in the order the plugin registers them. */\nexport const artifactsActions: ActionDefinition[] = [saveAction, flushAction, attachAction];\n","import { type ZodType, z } from \"@venn-lang/sdk\";\nimport type { ArtifactRef } from \"./artifact-ref.types.js\";\n\n/** Runtime validator for the nominal `artifacts.ArtifactRef` type. */\nexport const ArtifactRefSchema: ZodType<ArtifactRef> = z.object({\n  name: z.string(),\n  kind: z.string(),\n  size: z.number().optional(),\n});\n","import { type TypeSpec, t } from \"@venn-lang/types\";\n\n/**\n * The types `@venn-lang/artifacts` publishes to the checker, under the `artifacts`\n * namespace. Kept as data, and mirroring `artifact-ref.types.ts` by hand, so a\n * generator reading the emitted `.d.ts` can replace this file unnoticed.\n */\nexport const artifactsTypeDefs: Readonly<Record<string, TypeSpec>> = {\n  /**\n   * The receipt for a stored artifact: a trace, a video, a HAR, a screenshot.\n   * `size` is absent until the store knows how many bytes it kept.\n   */\n  ArtifactRef: t.record({ name: t.string, kind: t.string, size: t.number }, { optional: [\"size\"] }),\n};\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { artifactsActions } from \"./actions/index.js\";\nimport { ArtifactRefSchema, artifactsTypeDefs } from \"./types/index.js\";\n\n/**\n * The `@venn-lang/artifacts` plugin. Registers the `artifacts` namespace: the\n * `save`, `flush` and `attach` verbs and the nominal `artifacts.ArtifactRef`\n * type. Requires the `fs` capability, since the store writes to disk.\n */\nexport const artifactsPlugin: PluginDefinition = definePlugin({\n  name: \"venn/artifacts\",\n  version: \"0.0.0\",\n  namespace: \"artifacts\",\n  requires: [\"fs\"],\n  actions: artifactsActions,\n  types: { ArtifactRef: ArtifactRefSchema },\n  typeDefs: artifactsTypeDefs,\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@venn-lang/artifacts",
+  "version": "0.1.0",
+  "description": "The artifacts namespace: record the traces, videos, HARs and screenshots a run produces.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "artifacts"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-artifacts#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-artifacts"
+  },
+  "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/attach.ts

@@ -0,0 +1,32 @@
+import { type ActionDefinition, type ActionInput, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { ArtifactStorePort } from "../store/index.js";
+import type { ArtifactRef } from "../types/index.js";
+
+const attachParams = z.object({ kind: z.string().optional(), size: z.number().optional() });
+
+/**
+ * `artifacts.attach "screenshot.png" { kind: "image", size: 4096 }`.
+ *
+ * Files one already existing artifact under a name so the report can show it.
+ * `kind` defaults to `attachment` and `size` stays absent when not given.
+ *
+ * @returns the stored `artifacts.ArtifactRef`.
+ */
+export const attachAction: ActionDefinition = defineAction({
+  name: "attach",
+  doc: "Attach an artifact by name, with an optional kind and size.",
+  params: attachParams.optional(),
+  args: [arg("name", t.string, "What to file it under.")],
+  result: t.ref("artifacts.ArtifactRef"),
+  run: (ctx, input) => ctx.port(ArtifactStorePort).put(buildRef(input)),
+});
+
+function buildRef(input: ActionInput<unknown>): ArtifactRef {
+  const params = (input.params ?? {}) as { kind?: string; size?: number };
+  return {
+    name: String(input.args[0] ?? ""),
+    kind: params.kind ?? "attachment",
+    size: params.size,
+  };
+}

package/src/actions/flush.ts

@@ -0,0 +1,18 @@
+import { type ActionDefinition, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { ArtifactStorePort } from "../store/index.js";
+
+/**
+ * `artifacts.flush`.
+ *
+ * Persists everything buffered since the last flush and empties the buffer.
+ * Stored refs survive; only the pending queue is drained.
+ *
+ * @returns the list of `artifacts.ArtifactRef` that were written out.
+ */
+export const flushAction: ActionDefinition = defineAction({
+  name: "flush",
+  doc: "Flush pending artifacts, returning the refs that were drained.",
+  result: t.list(t.ref("artifacts.ArtifactRef")),
+  run: (ctx) => ctx.port(ArtifactStorePort).flush(),
+});

package/src/actions/index.ts

@@ -0,0 +1,7 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+import { attachAction } from "./attach.js";
+import { flushAction } from "./flush.js";
+import { saveAction } from "./save.js";
+
+/** Every verb in the `artifacts` namespace, in the order the plugin registers them. */
+export const artifactsActions: ActionDefinition[] = [saveAction, flushAction, attachAction];

package/src/actions/save.ts

@@ -0,0 +1,30 @@
+import { type ActionDefinition, defineAction, restArg } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { ArtifactStorePort } from "../store/index.js";
+import type { ArtifactRef } from "../types/index.js";
+
+/**
+ * `artifacts.save trace video har`.
+ *
+ * Each positional argument names a kind of artifact to keep from this run. One
+ * ref is stored per kind, in the order given.
+ *
+ * @returns the list of stored `artifacts.ArtifactRef`, one per kind.
+ */
+export const saveAction: ActionDefinition = defineAction({
+  name: "save",
+  doc: "Store one artifact per positional kind ref and return the stored refs.",
+  // The vocabulary has no variadic, so `restArg` types the first kind and
+  // leaves the rest unchecked. Better an unchecked argument than a wrong type.
+  args: [restArg("kinds", t.string, "One or more kinds to store, as positional arguments.")],
+  result: t.list(t.ref("artifacts.ArtifactRef")),
+  run: async (ctx, input) => {
+    const store = ctx.port(ArtifactStorePort);
+    return Promise.all(input.args.map((kind) => store.put(toRef(kind))));
+  },
+});
+
+function toRef(kind: unknown): ArtifactRef {
+  const name = String(kind);
+  return { name, kind: name };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * `@venn-lang/artifacts`: the verbs that record what a run left behind (traces,
+ * videos, HARs, screenshots) and the `ArtifactStore` port that keeps them.
+ */
+
+export { artifactsPlugin, artifactsPlugin as default } from "./plugin.js";
+export * from "./store/index.js";
+export * from "./types/index.js";

package/src/plugin.ts

@@ -0,0 +1,18 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { artifactsActions } from "./actions/index.js";
+import { ArtifactRefSchema, artifactsTypeDefs } from "./types/index.js";
+
+/**
+ * The `@venn-lang/artifacts` plugin. Registers the `artifacts` namespace: the
+ * `save`, `flush` and `attach` verbs and the nominal `artifacts.ArtifactRef`
+ * type. Requires the `fs` capability, since the store writes to disk.
+ */
+export const artifactsPlugin: PluginDefinition = definePlugin({
+  name: "venn/artifacts",
+  version: "0.0.0",
+  namespace: "artifacts",
+  requires: ["fs"],
+  actions: artifactsActions,
+  types: { ArtifactRef: ArtifactRefSchema },
+  typeDefs: artifactsTypeDefs,
+});

package/src/store/artifact-store.port.ts

@@ -0,0 +1,16 @@
+import type { Port } from "@venn-lang/contracts";
+import type { ArtifactStore } from "./artifact-store.types.js";
+
+/**
+ * The port the `artifacts` verbs reach through to keep what a run produced.
+ * Requires the `fs` capability, so a host without it fails to load the plugin
+ * rather than failing mid-run.
+ */
+export const ArtifactStorePort: Port<ArtifactStore> = {
+  id: "venn.port.artifact-store",
+  version: 1,
+  requires: ["fs"],
+  // List every method an action reaches for. An omission is not checked at load
+  // time, so it surfaces as a TypeError mid-run instead of a legible VN2011.
+  methods: ["put", "get", "list", "flush"],
+};

package/src/store/artifact-store.types.ts

@@ -0,0 +1,15 @@
+import type { ArtifactRef } from "../types/index.js";
+
+/**
+ * Keeps references to what a run produced.
+ *
+ * `put`, `get` and `list` address the stored set. `flush` drains the pending
+ * buffer accumulated since the last flush, leaving the stored set untouched.
+ */
+export interface ArtifactStore {
+  /** Stores a ref and queues it for the next flush. Returns the ref as stored. */
+  put(ref: ArtifactRef): Promise<ArtifactRef>;
+  get(name: string): Promise<ArtifactRef | undefined>;
+  list(): Promise<readonly ArtifactRef[]>;
+  flush(): Promise<readonly ArtifactRef[]>;
+}

package/src/store/index.ts

@@ -0,0 +1,4 @@
+export { ArtifactStorePort } from "./artifact-store.port.js";
+export type { ArtifactStore } from "./artifact-store.types.js";
+export { createMemoryArtifactStore } from "./memory-store.js";
+export { createRealArtifactStore } from "./real-store.js";

package/src/store/memory-store.ts

@@ -0,0 +1,30 @@
+import type { ArtifactRef } from "../types/index.js";
+import type { ArtifactStore } from "./artifact-store.types.js";
+
+/**
+ * The in-memory `ArtifactStore` used by tests and by hosts without a disk.
+ *
+ * @returns a fresh store; nothing is shared between calls.
+ */
+export function createMemoryArtifactStore(): ArtifactStore {
+  const stored = new Map<string, ArtifactRef>();
+  let pending: ArtifactRef[] = [];
+  return {
+    async put(ref) {
+      stored.set(ref.name, ref);
+      pending.push(ref);
+      return ref;
+    },
+    async get(name) {
+      return stored.get(name);
+    },
+    async list() {
+      return [...stored.values()];
+    },
+    async flush() {
+      const drained = pending;
+      pending = [];
+      return drained;
+    },
+  };
+}

package/src/store/real-store.ts

@@ -0,0 +1,25 @@
+import { VennError } from "@venn-lang/contracts";
+import type { ArtifactStore } from "./artifact-store.types.js";
+
+/**
+ * The disk-backed `ArtifactStore`. Not wired up in this build.
+ *
+ * @returns a store whose every method throws, so the gap is a legible failure
+ * rather than a silent no-op.
+ * @throws {VennError} `VN8090` on any call.
+ */
+export function createRealArtifactStore(): ArtifactStore {
+  return {
+    put: async () => notImplemented(),
+    get: async () => notImplemented(),
+    list: async () => notImplemented(),
+    flush: async () => notImplemented(),
+  };
+}
+
+function notImplemented(): never {
+  throw new VennError({
+    code: "VN8090",
+    message: "The artifact store is not implemented in this build.",
+  });
+}

package/src/types/artifact-ref.schema.ts

@@ -0,0 +1,9 @@
+import { type ZodType, z } from "@venn-lang/sdk";
+import type { ArtifactRef } from "./artifact-ref.types.js";
+
+/** Runtime validator for the nominal `artifacts.ArtifactRef` type. */
+export const ArtifactRefSchema: ZodType<ArtifactRef> = z.object({
+  name: z.string(),
+  kind: z.string(),
+  size: z.number().optional(),
+});

package/src/types/artifact-ref.types.ts

@@ -0,0 +1,9 @@
+/**
+ * The receipt for a stored artifact: a trace, a video, a HAR, a screenshot.
+ * `kind` names the category. `size` is the byte count, absent until known.
+ */
+export interface ArtifactRef {
+  name: string;
+  kind: string;
+  size?: number;
+}

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export { ArtifactRefSchema } from "./artifact-ref.schema.js";
+export type { ArtifactRef } from "./artifact-ref.types.js";
+export { artifactsTypeDefs } from "./type-defs.js";

package/src/types/type-defs.ts

@@ -0,0 +1,14 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The types `@venn-lang/artifacts` publishes to the checker, under the `artifacts`
+ * namespace. Kept as data, and mirroring `artifact-ref.types.ts` by hand, so a
+ * generator reading the emitted `.d.ts` can replace this file unnoticed.
+ */
+export const artifactsTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /**
+   * The receipt for a stored artifact: a trace, a video, a HAR, a screenshot.
+   * `size` is absent until the store knows how many bytes it kept.
+   */
+  ArtifactRef: t.record({ name: t.string, kind: t.string, size: t.number }, { optional: ["size"] }),
+};