@oomol-lab/open-flow 0.1.0-beta.75 → 0.1.0-beta.77

package/dist/common/runtime-contract.js

@@ -22,22 +22,25 @@ function dequal(foo, bar) {
 	return foo !== foo && bar !== bar;
 }
 //#endregion
-//#region src/execution/common/engineContract.ts
-var currentEngineContract = "open-flow-engine/v8";
+//#region src/runtime/common/engineContract.ts
+/** v10 adds persistent Flow State to the published v9 Node compatibility and fetch contract. */
+var currentEngineContract = "open-flow-engine/v10";
+/** The published v8 Node compatibility contract, retained for existing Publications and Runs. */
 var nodejsEngineContract = "open-flow-engine/v8/nodejs-compat-v1";
-var currentContract = {
+var platformSource = (contract) => `export const engineContract = ${JSON.stringify(contract)}
+export function identity(value) { return value }
+`;
+var v8Contract = {
 	workflowTools: true,
 	httpRequests: true,
 	waitAutoContinue: true,
 	webhookResponses: true,
 	platformExports: /* @__PURE__ */ new Set(["engineContract", "identity"]),
 	platformModule: "open-flow:platform",
-	platformSource: `export const engineContract = ${JSON.stringify(currentEngineContract)}
-export function identity(value) { return value }
-`
+	platformSource: platformSource("open-flow-engine/v8")
 };
 var nodejsContract = {
-	...currentContract,
+	...v8Contract,
 	builtinModules: new Set([
 		"assert",
 		"assert/strict",
@@ -64,32 +67,94 @@ var nodejsContract = {
 		"util",
 		"zlib"
 	].flatMap((name) => [name, `node:${name}`])),
-	platformSource: `export const engineContract = ${JSON.stringify(nodejsEngineContract)}
-export function identity(value) { return value }
-`
+	platformSource: platformSource(nodejsEngineContract)
+};
+var v9Contract = {
+	...nodejsContract,
+	codeFetch: true,
+	platformSource: platformSource("open-flow-engine/v9")
+};
+var currentContract = {
+	...v9Contract,
+	flowState: true,
+	platformSource: platformSource(currentEngineContract)
 };
 function findEngineContract(contract) {
-	if (contract == "open-flow-engine/v8") return currentContract;
+	if (contract == "open-flow-engine/v10") return currentContract;
+	if (contract == "open-flow-engine/v9") return v9Contract;
+	if (contract == "open-flow-engine/v8") return v8Contract;
 	if (contract == "open-flow-engine/v8/nodejs-compat-v1") return nodejsContract;
 	if (contract == "open-flow-engine/v7" || contract == "open-flow-engine/v7/nodejs-compat-v1") return {
-		...contract.endsWith("/nodejs-compat-v1") ? nodejsContract : currentContract,
+		...contract.endsWith("/nodejs-compat-v1") ? nodejsContract : v8Contract,
 		workflowTools: false,
 		httpRequests: false,
-		platformSource: `export const engineContract = ${JSON.stringify(contract)}\nexport function identity(value) { return value }\n`
+		platformSource: platformSource(contract)
 	};
 	if (contract == "open-flow-engine/v6" || contract == "open-flow-engine/v6/nodejs-compat-v1") return {
-		...contract == "open-flow-engine/v6" ? currentContract : nodejsContract,
+		...contract == "open-flow-engine/v6" ? v8Contract : nodejsContract,
 		workflowTools: false,
 		httpRequests: false,
 		waitAutoContinue: false,
 		webhookResponses: false,
-		platformSource: `export const engineContract = ${JSON.stringify(contract)}
-export function identity(value) { return value }
-`
+		platformSource: platformSource(contract)
 	};
 }
 //#endregion
-//#region src/execution/common/runtime.ts
+//#region src/runtime/common/runtime.ts
+/** Serialized into the guest; keep validation and helpers self-contained. */
+function createState(invoke) {
+	const invalid = (message) => Object.assign(new TypeError(message), { code: "capability.invalid" });
+	const keyOf = (key) => {
+		if (typeof key !== "string" || key.length === 0 || new TextEncoder().encode(key).length > 256) throw invalid("State keys require 1 to 256 UTF-8 bytes.");
+		return key;
+	};
+	const valueOf = (value) => {
+		if (value === void 0) throw invalid("State values must be JSON.");
+		try {
+			return snapshotRuntimeResult({ value }).value;
+		} catch {
+			throw invalid("State values must be JSON.");
+		}
+	};
+	const idsOf = (ids) => {
+		if (!Array.isArray(ids) || !Array.from(ids).every((id) => typeof id === "string" || typeof id === "number" && Number.isFinite(id))) throw invalid("Identities must be strings or finite numbers.");
+		return ids;
+	};
+	return {
+		state: Object.freeze({
+			async get(key) {
+				return (await invoke("state.get", { key: keyOf(key) })).body.value;
+			},
+			async set(key, value) {
+				await invoke("state.set", {
+					key: keyOf(key),
+					value: valueOf(value)
+				});
+			},
+			async insert(key, value) {
+				if (value === null) throw invalid("State insert does not accept null.");
+				return (await invoke("state.insert", {
+					key: keyOf(key),
+					value: valueOf(value)
+				})).body.inserted;
+			},
+			async delete(key) {
+				await invoke("state.delete", { key: keyOf(key) });
+			},
+			async list() {
+				return (await invoke("state.list", {})).body.keys;
+			}
+		}),
+		dedupe: Object.freeze({
+			async insert(ids) {
+				return (await invoke("dedupe.insert", { ids: idsOf(ids) })).body.inserted;
+			},
+			async has(ids) {
+				return (await invoke("dedupe.has", { ids: idsOf(ids) })).body.present;
+			}
+		})
+	};
+}
 /** Snapshot a Task result before JSON transport can discard or coerce invalid values. */
 function snapshotRuntimeResult(value) {
 	const parents = /* @__PURE__ */ new Set();
@@ -105,18 +170,18 @@ function snapshotRuntimeResult(value) {
 	};
 	return value === void 0 ? void 0 : copy(value, 0);
 }
-var nodejsRuntimeConformanceCases = [{
-	name: "supports Node builtin imports and asynchronous virtual file operations",
-	async verify(harness) {
-		equal(await harness.invoke({
-			capability: async () => ({
-				body: null,
-				status: 403
-			}),
-			input: null,
-			invocationId: "nodejs-files",
-			program: {
-				...program(harness, `import assert from 'node:assert/strict';
+var nodejsRuntimeConformanceCases = [
+	{
+		name: "supports Node builtin imports and asynchronous virtual file operations",
+		async verify(harness) {
+			equal(await harness.invoke({
+				capability: async () => ({
+					body: null,
+					status: 403
+				}),
+				input: null,
+				invocationId: "nodejs-files",
+				program: program(harness, `import assert from 'node:assert/strict';
 import { Buffer } from 'node:buffer'; import path from 'node:path'; import fs from 'node:fs/promises';
 export default async () => {
   const file = path.join('/tmp', 'conformance.txt');
@@ -125,26 +190,24 @@ export default async () => {
   assert.equal(text, '你好');
   await fs.unlink(file);
   return { text, bytes: Buffer.byteLength(text) };
-}`),
-				engineContract: nodejsEngineContract
-			}
-		}), {
-			text: "你好",
-			bytes: 6
-		}, "Node virtual files");
-	}
-}, {
-	name: "preserves abort reasons and cancels Promise timers",
-	async verify(harness) {
-		equal(await harness.invoke({
-			capability: async () => ({
-				body: null,
-				status: 403
-			}),
-			input: null,
-			invocationId: "nodejs-abort",
-			program: {
-				...program(harness, `import { setTimeout } from 'node:timers/promises';
+}`)
+			}), {
+				text: "你好",
+				bytes: 6
+			}, "Node virtual files");
+		}
+	},
+	{
+		name: "preserves abort reasons and cancels Promise timers",
+		async verify(harness) {
+			equal(await harness.invoke({
+				capability: async () => ({
+					body: null,
+					status: 403
+				}),
+				input: null,
+				invocationId: "nodejs-abort",
+				program: program(harness, `import { setTimeout } from 'node:timers/promises';
 export default async () => {
   const controller = new AbortController(); const reason = { message: 'stop' };
   const combined = AbortSignal.any([controller.signal]);
@@ -154,15 +217,216 @@ export default async () => {
   try { await pending; return false; } catch (error) {
     return { sameReason: combined.reason === reason && thrown === reason, name: error.name };
   }
-}`),
-				engineContract: nodejsEngineContract
-			}
-		}), {
-			sameReason: true,
-			name: "AbortError"
-		}, "Node cancellation");
+}`)
+			}), {
+				sameReason: true,
+				name: "AbortError"
+			}, "Node cancellation");
+		}
+	},
+	nodejsCase("resolves prefixed and bare builtin names to the same module and shares globals with their modules", `import { Buffer } from 'node:buffer'; import bare from 'buffer'; import processModule from 'node:process';
+import { URL as ImportedURL, URLSearchParams as ImportedParams } from 'node:url'; import { ReadableStream as ImportedStream } from 'node:stream/web';
+export default () => ({ buffer: Buffer === bare.Buffer && Buffer === globalThis.Buffer, process: process === processModule,
+  url: URL === ImportedURL && URLSearchParams === ImportedParams, stream: ReadableStream === ImportedStream,
+  cwd: process.cwd(), env: Object.keys(process.env) })`, {
+		buffer: true,
+		process: true,
+		url: true,
+		stream: true,
+		cwd: "/tmp",
+		env: []
+	}),
+	nodejsCase("supports events, string decoding, paths, query strings, URLs and promisify", `import { EventEmitter } from 'node:events'; import { StringDecoder } from 'node:string_decoder'; import { Buffer } from 'node:buffer';
+import path from 'node:path'; import qs from 'node:querystring'; import { promisify } from 'node:util';
+export default async () => {
+  const emitter = new EventEmitter(); let count = 0; emitter.once('value', (x) => (count += x)); emitter.emit('value', 7); emitter.emit('value', 9);
+  const decoder = new StringDecoder('utf8'); const bytes = Buffer.from('你好');
+  const incremental = new TextDecoder(); const partial = incremental.decode(new Uint8Array([0xe4, 0xbd]), { stream: true });
+  const url = new URL('../文件?a=1', 'https://example.com/a/b'); url.searchParams.append('b', 'x y');
+  return { count, text: decoder.write(bytes.subarray(0, 2)) + decoder.end(bytes.subarray(2)), partial, rest: incremental.decode(new Uint8Array([0xa0])),
+    path: path.join('/tmp', 'a', '..', 'b'), query: qs.parse('a=1&a=2').a, url: url.href, canParse: URL.canParse('not a url'),
+    value: await promisify((callback) => callback(null, 42))() };
+}`, {
+		count: 7,
+		text: "你好",
+		partial: "",
+		rest: "你",
+		path: "/tmp/b",
+		query: ["1", "2"],
+		url: "https://example.com/%E6%96%87%E4%BB%B6?a=1&b=x+y",
+		canParse: false,
+		value: 42
+	}),
+	nodejsCase("encodes Buffers and computes hashes, HMACs, gzip and random values", `import { Buffer } from 'node:buffer'; import { createHash, createHmac, randomBytes } from 'node:crypto'; import { gzipSync, gunzipSync, deflateRawSync, inflateRawSync } from 'node:zlib';
+export default () => ({ hex: Buffer.from('你好').toString('hex'), base64: Buffer.from('abc').toString('base64'), latin1: Buffer.from([0xe9]).toString('latin1'),
+  utf16: Buffer.from('a', 'utf16le').length, hash: createHash('sha256').update('a').update('bc').digest('hex'),
+  md5: createHash('md5').update('abc').digest('base64'), hmac: createHmac('sha256', 'key').update('message').digest('hex'),
+  gzip: gunzipSync(gzipSync(Buffer.from('你好'))).toString(), raw: inflateRawSync(deflateRawSync('raw')).toString(),
+  random: randomBytes(12).length, uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(crypto.randomUUID()),
+  values: crypto.getRandomValues(new Uint8Array(4)).length })`, {
+		hex: "e4bda0e5a5bd",
+		base64: "YWJj",
+		latin1: "é",
+		utf16: 2,
+		hash: "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+		md5: "kAFQmDzST7DWlj99KOF/cg==",
+		hmac: "6e9ef29b75fffc5b7abae527d58fdadb2fe42e7219011976917343065f58ed4a",
+		gzip: "你好",
+		raw: "raw",
+		random: 12,
+		uuid: true,
+		values: 4
+	}),
+	nodejsCase("provides an invocation-local filesystem with Node error codes", `import fs from 'node:fs'; import fsp from 'node:fs/promises';
+export default async () => {
+  await fsp.mkdir('/tmp/nested', { recursive: true });
+  fs.writeFileSync('/tmp/nested/data', '你好');
+  const handle = await fsp.open('/tmp/nested/data', 'r'); const data = await handle.readFile('utf8'); await handle.close();
+  await fsp.rename('/tmp/nested/data', '/tmp/nested/moved');
+  let missing; try { fs.readFileSync('/etc/passwd'); } catch (error) { missing = error.code; }
+  return { data, size: fs.statSync('/tmp/nested/moved').size, entries: fs.readdirSync('/tmp/nested'), missing };
+}`, {
+		data: "你好",
+		size: 6,
+		entries: ["moved"],
+		missing: "ENOENT"
+	}),
+	nodejsCase("runs timers, Node streams, pipelines and Web Streams", `import { setTimeout as delay } from 'node:timers/promises'; import { Readable, Writable } from 'node:stream'; import { pipeline } from 'node:stream/promises';
+export default async () => {
+  let count = 0; const timer = setInterval(() => { count++; clearInterval(timer) }, 1); const removed = setTimeout(() => { count += 100 }, 1); clearTimeout(removed);
+  await delay(10);
+  const data = []; for await (const chunk of Readable.from(['a', 'b'])) data.push(chunk);
+  let piped = ''; await pipeline(Readable.from(['x', 'y']), new Writable({ write(chunk, _encoding, callback) { piped += chunk.toString(); callback() } }));
+  const reader = new ReadableStream({ start(controller) { controller.enqueue('web'); controller.close() } }).getReader();
+  return { count, data, piped, web: (await reader.read()).value };
+}`, {
+		count: 1,
+		data: ["a", "b"],
+		piped: "xy",
+		web: "web"
+	}),
+	nodejsCase("supports AbortSignal timeout and pre-aborted signals", `import { setTimeout as delay } from 'node:timers/promises';
+export default async () => { const timeout = AbortSignal.timeout(1); await delay(10); return { timeout: timeout.reason.name, aborted: AbortSignal.abort().aborted } }`, {
+		timeout: "TimeoutError",
+		aborted: true
+	}),
+	nodejsCase("encodes and decodes text larger than one builtin transfer and creates many decoders", `export default () => {
+  const text = '你😀a'.repeat(400000); const bytes = new TextEncoder().encode(text);
+  const decoder = new TextDecoder(); let streamed = '';
+  for (let offset = 0; offset < bytes.length; offset += 1000003) streamed += decoder.decode(bytes.subarray(offset, offset + 1000003), { stream: true });
+  streamed += decoder.decode();
+  let decoded = 0; for (let index = 0; index < 300; index++) decoded += new TextDecoder().decode(new Uint8Array([0x61])).length;
+  return { bytes: bytes.length, whole: new TextDecoder().decode(bytes) === text, streamed: streamed === text, decoded };
+}`, {
+		bytes: 32e5,
+		whole: true,
+		streamed: true,
+		decoded: 300
+	}),
+	{
+		name: "isolates files, globals and builtin module state between Task invocations",
+		async verify(harness) {
+			const invoke = async (invocationId, source) => await harness.invoke({
+				capability: async () => ({
+					body: null,
+					status: 403
+				}),
+				input: null,
+				invocationId,
+				program: program(harness, source)
+			});
+			await invoke("nodejs-isolation-write", `import fs from 'node:fs'; import crypto from 'node:crypto';
+export default () => { fs.writeFileSync('/tmp/marker', 'x'); URL.prototype.taskMarker = true; crypto.constants.taskMarker = true; globalThis.taskMarker = true }`);
+			equal(await invoke("nodejs-isolation-read", `import fs from 'node:fs'; import crypto from 'node:crypto';
+export default () => ({ file: fs.existsSync('/tmp/marker'), url: 'taskMarker' in URL.prototype, module: 'taskMarker' in crypto.constants, global: 'taskMarker' in globalThis })`), {
+				file: false,
+				url: false,
+				module: false,
+				global: false
+			}, "Task isolation");
+		}
 	}
-}];
+];
+/** Reference Artifact Host for the guest chunk protocol; deployments own storage, identity and limits. */
+function artifactHost() {
+	const chunkBytes = 524288;
+	const uploads = /* @__PURE__ */ new Map();
+	const artifacts = /* @__PURE__ */ new Map();
+	const kinds = [];
+	let nextUpload = 0;
+	const capability = async (call) => {
+		kinds.push(call.kind);
+		const payload = call.payload;
+		if (call.kind == "artifact.write") {
+			const upload = typeof payload.upload == "string" ? payload.upload : `u${++nextUpload}`;
+			uploads.set(upload, [...uploads.get(upload) ?? [], decodeBase64(payload.data)]);
+			return {
+				body: { upload },
+				status: 200
+			};
+		}
+		if (call.kind == "artifact.put") {
+			const parts = [...typeof payload.upload == "string" ? uploads.get(payload.upload) ?? [] : [], decodeBase64(payload.data)];
+			const bytes = new Uint8Array(parts.reduce((size, part) => size + part.length, 0));
+			parts.reduce((offset, part) => (bytes.set(part, offset), offset + part.length), 0);
+			const id = `a${artifacts.size + 1}`;
+			artifacts.set(id, bytes);
+			return {
+				body: {
+					kind: "artifact",
+					id,
+					name: payload.name,
+					size: bytes.length,
+					digest: artifactDigest(id),
+					...payload.mediaType == null ? {} : { mediaType: payload.mediaType }
+				},
+				status: 200
+			};
+		}
+		if (call.kind == "artifact.read") {
+			const bytes = artifacts.get(String(payload.id));
+			const offset = Number(payload.offset);
+			return {
+				body: {
+					data: encodeBase64(bytes.subarray(offset, offset + chunkBytes)),
+					size: bytes.length
+				},
+				status: 200
+			};
+		}
+		throw new Error(`Unexpected Capability ${call.kind}.`);
+	};
+	return {
+		capability,
+		digest: artifactDigest,
+		kinds: () => kinds
+	};
+}
+function decodeBase64(text) {
+	return Uint8Array.from(atob(String(text)), (character) => character.charCodeAt(0));
+}
+function encodeBase64(bytes) {
+	return btoa(Array.from(bytes, (byte) => String.fromCharCode(byte)).join(""));
+}
+function artifactDigest(id) {
+	return `sha256:${id.slice(1).padStart(64, "0")}`;
+}
+function nodejsCase(name, source, expected) {
+	return {
+		name,
+		async verify(harness) {
+			equal(await harness.invoke({
+				capability: async () => ({
+					body: null,
+					status: 403
+				}),
+				input: null,
+				invocationId: `nodejs-${name}`,
+				program: program(harness, source)
+			}), expected, name);
+		}
+	};
+}
 function program(harness, source, modules = {}) {
 	return {
 		engineContract: currentEngineContract,
@@ -190,6 +454,59 @@ async function rejects(operation, pattern, message) {
 	throw new Error(`${message}: operation unexpectedly succeeded.`);
 }
 var runtimeConformanceCases = [
+	{
+		name: "cancels detached State work when its Task finishes",
+		async verify(harness) {
+			let aborted = false;
+			equal(await harness.invoke({
+				input: null,
+				invocationId: "state-detached",
+				capability: async ({ signal }) => await new Promise((resolve) => {
+					signal.addEventListener("abort", () => {
+						aborted = true;
+						resolve({
+							status: 200,
+							body: null
+						});
+					}, { once: true });
+				}),
+				program: program(harness, `export default async (_, context) => {
+          void context.state.set('detached', 1);
+          await new Promise(resolve => setTimeout(resolve, 20));
+          return null;
+        }`)
+			}), null, "Detached State Task result");
+			equal(aborted, true, "Detached State cancellation");
+		}
+	},
+	{
+		name: "rejects non-JSON State values and invalid identities before Host dispatch",
+		async verify(harness) {
+			let calls = 0;
+			equal(await harness.invoke({
+				input: null,
+				invocationId: "state-invalid",
+				capability: async () => {
+					calls += 1;
+					return {
+						status: 200,
+						body: null
+					};
+				},
+				program: program(harness, `export default async (_, context) => {
+          const cyclic = {}; cyclic.self = cyclic;
+          const invalid = [undefined, NaN, Infinity, new Date(), { x: undefined }, cyclic, [undefined], { x: () => 1 }];
+          const errors = [];
+          for (const value of invalid) { try { await context.state.set('key', value); errors.push('accepted'); } catch (e) { errors.push(e.code); } }
+          for (const call of [() => context.state.get(''), () => context.state.get('x'.repeat(257)), () => context.state.insert('x', null), () => context.dedupe.insert([NaN]), () => context.dedupe.has([null]), () => context.dedupe.insert(new Array(1))]) {
+            try { await call(); errors.push('accepted'); } catch (e) { errors.push(e.code); }
+          }
+          return errors;
+        }`)
+			}), Array.from({ length: 14 }, () => "capability.invalid"), "State boundary validation");
+			equal(calls, 0, "State invalid dispatch");
+		}
+	},
 	{
 		name: "rejects Task results that JSON transport would discard or coerce",
 		async verify(harness) {
@@ -359,8 +676,8 @@ export default (input) => ({ engineContract, value: identity(double(input.value)
 				}),
 				input: null,
 				invocationId: "closed-linker",
-				program: program(harness, `import fs from 'node:fs'
-export default () => fs.readFileSync('/etc/passwd', 'utf8')`)
+				program: program(harness, `import { execSync } from 'node:child_process'
+export default () => execSync('cat /etc/passwd').toString()`)
 			}), /invalid|unsupported|cannot import|not part of/i, "Closed linker");
 		}
 	},
@@ -369,6 +686,11 @@ export default () => fs.readFileSync('/etc/passwd', 'utf8')`)
 		async verify(harness) {
 			const calls = [];
 			equal(await harness.invoke({
+				capabilities: [{
+					kind: "connector",
+					action: "example.read",
+					connections: []
+				}],
 				capability: async (call) => {
 					calls.push(call);
 					return {
@@ -381,16 +703,13 @@ export default () => fs.readFileSync('/etc/passwd', 'utf8')`)
 				},
 				input: { issue: 42 },
 				invocationId: "async-capability",
-				program: program(harness, `export default async (input, capability) => capability.artifact.put({ action: 'read', input })`)
+				program: program(harness, `export default async (input, context) => context.actions.example.read(input)`)
 			}), {
-				body: {
-					accepted: true,
-					echoed: {
-						action: "read",
-						input: { issue: 42 }
-					}
-				},
-				status: 200
+				accepted: true,
+				echoed: {
+					action: "example.read",
+					input: { issue: 42 }
+				}
 			}, "Capability result");
 			equal(calls.map(({ invocationId, kind, payload }) => ({
 				invocationId,
@@ -398,14 +717,150 @@ export default () => fs.readFileSync('/etc/passwd', 'utf8')`)
 				payload
 			})), [{
 				invocationId: "async-capability",
-				kind: "artifact.put",
+				kind: "connector",
 				payload: {
-					action: "read",
+					action: "example.read",
 					input: { issue: 42 }
 				}
 			}], "Capability request");
 		}
 	},
+	{
+		name: "stores and reads Artifacts through bounded chunks",
+		async verify(harness) {
+			const host = artifactHost();
+			const value = await harness.invoke({
+				capability: host.capability,
+				input: null,
+				invocationId: "artifact-roundtrip",
+				program: program(harness, `export default async (_input, context) => {
+  const large = new Uint8Array(1200 * 1024).map((_, index) => index % 251)
+  const text = await context.artifact.put('你好', { name: 'greeting.txt', mediaType: 'text/plain' })
+  const binary = await context.artifact.put(large, { name: 'data.bin' })
+  const empty = await context.artifact.put(new Uint8Array(0), { name: 'empty' })
+  const read = await context.artifact.open(binary)
+  return { text, binary, empty, greeting: new TextDecoder().decode(await context.artifact.open(text)),
+    same: read.length == large.length && read.every((byte, index) => byte == large[index]), emptyLength: (await context.artifact.open(empty)).length }
+}`)
+			});
+			const ref = (id, name, size, mediaType) => ({
+				kind: "artifact",
+				id,
+				name,
+				size,
+				digest: host.digest(id),
+				...mediaType == null ? {} : { mediaType }
+			});
+			equal(value, {
+				text: ref("a1", "greeting.txt", 6, "text/plain"),
+				binary: ref("a2", "data.bin", 1228800),
+				empty: ref("a3", "empty", 0),
+				greeting: "你好",
+				same: true,
+				emptyLength: 0
+			}, "Artifact roundtrip");
+			equal(host.kinds(), [
+				"artifact.put",
+				"artifact.write",
+				"artifact.write",
+				"artifact.put",
+				"artifact.put",
+				"artifact.read",
+				"artifact.read",
+				"artifact.read",
+				"artifact.read",
+				"artifact.read"
+			], "Artifact chunks");
+		}
+	},
+	{
+		name: "rejects invalid Artifact arguments before Host dispatch",
+		async verify(harness) {
+			const host = artifactHost();
+			equal(await harness.invoke({
+				capability: host.capability,
+				input: null,
+				invocationId: "artifact-invalid",
+				program: program(harness, `export default async (_input, context) => {
+  const codes = []
+  for (const call of [() => context.artifact.put({}, { name: 'x' }), () => context.artifact.put('x', {}), () => context.artifact.put('x', { name: 'x', mediaType: 1 }), () => context.artifact.open({ id: 'a1' })]) {
+    try { await call() } catch (error) { codes.push(error.code) }
+  }
+  return codes
+}`)
+			}), Array.from({ length: 4 }, () => "capability.invalid"), "Artifact validation");
+			equal(host.kinds(), [], "Artifact dispatch");
+		}
+	},
+	{
+		name: "calls declared HTTP hosts through context.fetch",
+		async verify(harness) {
+			const calls = [];
+			equal(await harness.invoke({
+				capability: async (call) => {
+					calls.push({
+						kind: call.kind,
+						payload: call.payload
+					});
+					return {
+						status: 200,
+						body: {
+							status: 201,
+							statusText: "Created",
+							url: "https://api.example.com/items?q=1",
+							headers: [
+								["content-type", "application/json"],
+								["x-tag", "a"],
+								["x-tag", "b"]
+							],
+							body: btoa("{\"id\":7}")
+						}
+					};
+				},
+				input: null,
+				invocationId: "code-fetch",
+				program: program(harness, `export default async (_input, context) => {
+  const response = await context.fetch(new URL('https://api.example.com/items?q=1'), { method: 'post', headers: [['X-Trace', '1']], body: '{"name":"a"}' })
+  const json = await response.json()
+  let reused; try { await response.text() } catch (error) { reused = error instanceof TypeError }
+  const codes = []
+  for (const call of [() => context.fetch('https://api.example.com', { method: 'TRACE' }), () => context.fetch('https://api.example.com', { body: 'x' }),
+    () => context.fetch('https://api.example.com', { method: 'POST', body: {} }), () => context.fetch('https://api.example.com', { headers: { 'bad header': 'x' } }),
+    () => context.fetch('https://api.example.com', { method: 'PUT', body: new Uint8Array(1024 * 1024 + 1) })]) {
+    try { await call() } catch (error) { codes.push(error.code) }
+  }
+  return { status: response.status, ok: response.ok, statusText: response.statusText, url: response.url, redirected: response.redirected, json, reused,
+    tag: response.headers.get('X-Tag'), has: response.headers.has('content-type'), names: [...response.headers.keys()], codes, egress: typeof context.egress }
+}`)
+			}), {
+				status: 201,
+				ok: true,
+				statusText: "Created",
+				url: "https://api.example.com/items?q=1",
+				redirected: false,
+				json: { id: 7 },
+				reused: true,
+				tag: "a, b",
+				has: true,
+				names: [
+					"content-type",
+					"x-tag",
+					"x-tag"
+				],
+				codes: Array.from({ length: 5 }, () => "capability.invalid"),
+				egress: "undefined"
+			}, "Fetch response");
+			equal(calls, [{
+				kind: "http.fetch",
+				payload: {
+					url: "https://api.example.com/items?q=1",
+					method: "POST",
+					headers: [["x-trace", "1"], ["content-type", "text/plain;charset=UTF-8"]],
+					body: btoa("{\"name\":\"a\"}")
+				}
+			}], "Fetch request");
+		}
+	},
 	{
 		name: "returns final outputs without exposing intermediate output capability",
 		async verify(harness) {
@@ -555,6 +1010,196 @@ function resolveAction(declarations, payload) {
 		...connectionId == null ? {} : { connectionId }
 	};
 }
+/**
+* Serialized into the sandbox before the Capability helpers that use it; keep it self-contained. Encodes in guest
+* JavaScript, because Node compatibility `atob`/`btoa` route through bounded Host primitives.
+*/
+function createBase64() {
+	const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+	const values = (/* @__PURE__ */ new Uint8Array(128)).fill(255);
+	for (let index = 0; index < 64; index++) values[alphabet.charCodeAt(index)] = index;
+	return Object.freeze({
+		encode(bytes) {
+			const parts = [];
+			for (let start = 0; start < bytes.length; start += 24576) {
+				let text = "";
+				for (let index = start; index < Math.min(start + 24576, bytes.length); index += 3) {
+					const value = bytes[index] << 16 | (bytes[index + 1] ?? 0) << 8 | (bytes[index + 2] ?? 0);
+					text += alphabet[value >> 18] + alphabet[value >> 12 & 63] + (index + 1 < bytes.length ? alphabet[value >> 6 & 63] : "=") + (index + 2 < bytes.length ? alphabet[value & 63] : "=");
+				}
+				parts.push(text);
+			}
+			return parts.join("");
+		},
+		decode(text) {
+			if (typeof text != "string" || text.length % 4 != 0) throw new TypeError("Base64 content is invalid.");
+			const padding = text.endsWith("==") ? 2 : text.endsWith("=") ? 1 : 0;
+			const bytes = new Uint8Array(text.length / 4 * 3 - padding);
+			for (let index = 0, offset = 0; index < text.length; index += 4) {
+				const digits = [
+					0,
+					1,
+					2,
+					3
+				].map((position) => {
+					const code = text.charCodeAt(index + position);
+					if (code == 61 && index + position >= text.length - padding) return 0;
+					const value = code < 128 ? values[code] : 255;
+					if (value == 255) throw new TypeError("Base64 content is invalid.");
+					return value;
+				});
+				const value = digits[0] << 18 | digits[1] << 12 | digits[2] << 6 | digits[3];
+				if (offset < bytes.length) bytes[offset++] = value >> 16;
+				if (offset < bytes.length) bytes[offset++] = value >> 8 & 255;
+				if (offset < bytes.length) bytes[offset++] = value & 255;
+			}
+			return bytes;
+		}
+	});
+}
+/**
+* Serialized into the sandbox; keep it self-contained. Transfers bytes as base64 chunks through
+* `artifact.write`, `artifact.put` and `artifact.read` so each Capability message stays bounded.
+*/
+function createArtifacts(invoke, { decode, encode } = createBase64()) {
+	const chunkBytes = 524288;
+	const invalid = (message) => Object.assign(new TypeError(message), { code: "capability.invalid" });
+	return Object.freeze({
+		async put(data, options) {
+			const settings = options;
+			if (settings == null || typeof settings != "object" || typeof settings.name != "string" || settings.name.length == 0) throw invalid("Artifact name is required.");
+			if (settings.mediaType !== void 0 && typeof settings.mediaType != "string") throw invalid("Artifact mediaType must be a string.");
+			const bytes = typeof data == "string" ? new TextEncoder().encode(data) : data instanceof Uint8Array ? data : void 0;
+			if (bytes == null) throw invalid("Artifact data must be a string or Uint8Array.");
+			const tail = bytes.length == 0 ? 0 : Math.floor((bytes.length - 1) / chunkBytes) * chunkBytes;
+			let upload;
+			for (let offset = 0; offset < tail; offset += chunkBytes) upload = (await invoke("artifact.write", {
+				...upload === void 0 ? {} : { upload },
+				data: encode(bytes.subarray(offset, offset + chunkBytes))
+			})).body?.upload;
+			return (await invoke("artifact.put", {
+				...upload === void 0 ? {} : { upload },
+				name: settings.name,
+				...settings.mediaType === void 0 ? {} : { mediaType: settings.mediaType },
+				data: encode(bytes.subarray(tail))
+			})).body;
+		},
+		async open(ref) {
+			const artifact = ref;
+			if (artifact == null || typeof artifact != "object" || artifact.kind != "artifact" || typeof artifact.id != "string") throw invalid("An ArtifactRef is required.");
+			const parts = [];
+			let offset = 0;
+			let size = 0;
+			do {
+				const body = (await invoke("artifact.read", {
+					id: artifact.id,
+					offset
+				})).body;
+				const part = decode(body?.data);
+				if (typeof body?.size != "number" || !Number.isSafeInteger(body.size) || part.length == 0 && offset < body.size) throw new TypeError("Artifact content is invalid.");
+				size = body.size;
+				parts.push(part);
+				offset += part.length;
+			} while (offset < size);
+			const bytes = new Uint8Array(offset);
+			let position = 0;
+			for (const part of parts) {
+				bytes.set(part, position);
+				position += part.length;
+			}
+			return bytes;
+		}
+	});
+}
+/**
+* Serialized into the sandbox; keep it self-contained. `context.fetch` sends one `http.fetch` Capability call per request.
+* The Host authorizes the URL against the node's `http` Capability, does not follow redirects and adds no credentials.
+* Request and response bodies are limited to 1 MiB; the response is a read-only subset of the Fetch `Response`.
+*/
+function createFetch(invoke, { decode, encode } = createBase64()) {
+	const maximumBytes = 1048576;
+	const methods = /* @__PURE__ */ new Set([
+		"GET",
+		"HEAD",
+		"POST",
+		"PUT",
+		"PATCH",
+		"DELETE",
+		"OPTIONS"
+	]);
+	const invalid = (message) => Object.assign(new TypeError(message), { code: "capability.invalid" });
+	const headerList = (value) => {
+		if (value == null) return [];
+		const pairs = typeof value[Symbol.iterator] == "function" ? Array.from(value, (pair) => {
+			if (!Array.isArray(pair) || pair.length != 2) throw invalid("Headers must be name/value pairs.");
+			return pair;
+		}) : typeof value == "object" ? Object.entries(value) : void 0;
+		if (pairs == null) throw invalid("Headers must be an object or name/value pairs.");
+		return pairs.map(([name, text]) => {
+			if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(String(name))) throw invalid(`Invalid header name "${String(name)}".`);
+			return [String(name).toLowerCase(), String(text)];
+		});
+	};
+	return async function fetch(input, init = {}) {
+		const options = init ?? {};
+		if (typeof options != "object") throw invalid("Fetch options must be an object.");
+		const url = String(input instanceof Object && "href" in input ? input.href : input);
+		const method = String(options.method ?? "GET").toUpperCase();
+		if (!methods.has(method)) throw invalid(`Unsupported HTTP method "${method}".`);
+		const headers = headerList(options.headers);
+		const body = options.body == null ? void 0 : typeof options.body == "string" ? new TextEncoder().encode(options.body) : options.body instanceof Uint8Array ? options.body : options.body instanceof ArrayBuffer ? new Uint8Array(options.body) : void 0;
+		if (options.body != null && body == null) throw invalid("Fetch body must be a string, Uint8Array or ArrayBuffer.");
+		if (body != null && (method == "GET" || method == "HEAD")) throw invalid(`A ${method} request cannot have a body.`);
+		if (body != null && body.length > maximumBytes) throw invalid("Fetch request body exceeds 1 MiB.");
+		if (typeof options.body == "string" && !headers.some(([name]) => name == "content-type")) headers.push(["content-type", "text/plain;charset=UTF-8"]);
+		const signal = options.signal;
+		if (signal?.aborted) throw signal.reason;
+		const request = invoke("http.fetch", {
+			url,
+			method,
+			headers,
+			...body == null ? {} : { body: encode(body) }
+		});
+		const result = (signal?.addEventListener == null ? await request : await Promise.race([request, new Promise((_, reject) => signal.addEventListener("abort", () => reject(signal.reason), { once: true }))])).body;
+		if (result == null || typeof result.status != "number" || typeof result.url != "string" || typeof result.body != "string" || !Array.isArray(result.headers) || result.headers.some((pair) => !Array.isArray(pair) || typeof pair[0] != "string" || typeof pair[1] != "string")) throw new TypeError("The HTTP response is invalid.");
+		const status = result.status;
+		const entries = result.headers;
+		const content = decode(result.body);
+		let used = false;
+		const consume = () => {
+			if (used) throw new TypeError("Response body has already been used.");
+			used = true;
+			return content.slice();
+		};
+		const responseHeaders = Object.freeze({
+			get: (name) => {
+				const values = entries.filter(([key]) => key == String(name).toLowerCase()).map(([, value]) => value);
+				return values.length == 0 ? null : values.join(", ");
+			},
+			has: (name) => entries.some(([key]) => key == String(name).toLowerCase()),
+			entries: () => entries.map(([name, value]) => [name, value])[Symbol.iterator](),
+			keys: () => entries.map(([name]) => name)[Symbol.iterator](),
+			values: () => entries.map(([, value]) => value)[Symbol.iterator](),
+			forEach: (callback) => entries.forEach(([name, value]) => callback(value, name)),
+			[Symbol.iterator]: () => entries.map(([name, value]) => [name, value])[Symbol.iterator]()
+		});
+		return Object.freeze({
+			status,
+			statusText: typeof result.statusText == "string" ? result.statusText : "",
+			ok: status >= 200 && status < 300,
+			redirected: false,
+			url: result.url,
+			headers: responseHeaders,
+			get bodyUsed() {
+				return used;
+			},
+			bytes: async () => consume(),
+			arrayBuffer: async () => consume().buffer,
+			text: async () => new TextDecoder().decode(consume()),
+			json: async () => JSON.parse(new TextDecoder().decode(consume()))
+		});
+	};
+}
 /** Serialized into the sandbox alongside the strict JSON snapshot helper. */
 function createWorkflows(invoke) {
 	return Object.freeze({ async call(name, input = {}) {
@@ -566,4 +1211,4 @@ function createWorkflows(invoke) {
 	} });
 }
 //#endregion
-export { createActions, createWorkflows, currentEngineContract, findEngineContract, nodejsEngineContract, nodejsRuntimeConformanceCases, resolveAction, runtimeConformanceCases, snapshotRuntimeResult };
+export { createActions, createArtifacts, createBase64, createFetch, createState, createWorkflows, currentEngineContract, findEngineContract, nodejsEngineContract, nodejsRuntimeConformanceCases, resolveAction, runtimeConformanceCases, snapshotRuntimeResult };