@oomol-lab/open-flow 0.1.0-alpha.0

package/dist/common/run-events.d.ts

@@ -0,0 +1,9 @@
+export type ProjectedRunEvent = {
+    readonly kind: 'node.output';
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly value: unknown;
+} | {
+    readonly kind: 'node.artifact' | 'node.completed' | 'node.failed' | 'node.log' | 'node.progress' | 'node.started' | 'run.progress' | 'run.started';
+    readonly payload: Readonly<Record<string, unknown>>;
+};
+export declare function createEventProjector(platformRunId: string, nodeFailureCodes: ReadonlySet<string>): (event: unknown) => Promise<ProjectedRunEvent | undefined>;

package/dist/common/run-events.js

@@ -0,0 +1,192 @@
+//#region src/execution/common/events.ts
+var e = new TextEncoder(), t = /* @__PURE__ */ new Set([
+	"condition",
+	"connector",
+	"javascript",
+	"llm",
+	"subflow",
+	"value"
+]);
+function n(e, t) {
+	if (typeof e != "object" || !e || Array.isArray(e)) throw TypeError(`${t} must be an object.`);
+	return e;
+}
+function r(e, t) {
+	if (typeof e != "string" || e.length == 0) throw TypeError(`${t} must be a non-empty string.`);
+	return e;
+}
+function i(e, t) {
+	return e === void 0 ? void 0 : r(e, t);
+}
+function a(e) {
+	if (e !== void 0) {
+		if (!t.has(e)) throw TypeError("Runtime node.started nodeKind is invalid.");
+		return e;
+	}
+}
+function o(e) {
+	return r(e.runId, "Runtime event runId");
+}
+function s(e, t, n) {
+	let i = o(e), a = t.get(i);
+	if (a == null) throw TypeError("Runtime node event preceded its run.started event.");
+	return {
+		executionId: c("execution", n, i, r(e.jobId, "Runtime node event jobId")),
+		flowId: a,
+		nodeId: r(e.nodeId, "Runtime node event nodeId"),
+		rawRunId: i
+	};
+}
+async function c(t, ...n) {
+	let r = e.encode(JSON.stringify([
+		1,
+		t,
+		...n
+	])), i = new Uint8Array(r.byteLength);
+	return i.set(r), `${t}_${[...new Uint8Array(await crypto.subtle.digest("SHA-256", i))].slice(0, 16).map((e) => e.toString(16).padStart(2, "0")).join("")}`;
+}
+function l(e) {
+	return r(e, "Runtime event message").replace(/Bearer\s+\S+/gi, "Bearer [REDACTED]").replace(/\b(api[-_ ]?key|authorization|password|secret|token)\s*[:=]\s*\S+/gi, "$1=[REDACTED]");
+}
+function u(e, t) {
+	let n = r(e, "Runtime node.failed code");
+	if (!t.has(n)) throw TypeError("Runtime node.failed code is invalid.");
+	return n;
+}
+function d(e) {
+	let t = n(e, "Runtime ArtifactRef");
+	if (Object.keys(t).some((e) => ![
+		"kind",
+		"id",
+		"name",
+		"mediaType",
+		"size",
+		"digest"
+	].includes(e)) || t.kind != "artifact" || typeof t.id != "string" || t.id.length == 0 || typeof t.name != "string" || t.name.length == 0 || t.mediaType !== void 0 && (typeof t.mediaType != "string" || t.mediaType.length == 0) || typeof t.size != "number" || !Number.isSafeInteger(t.size) || t.size < 0 || typeof t.digest != "string" || !/^sha256:[0-9a-f]{64}$/.test(t.digest)) throw TypeError("Runtime ArtifactRef is invalid.");
+	return {
+		digest: t.digest,
+		id: t.id,
+		kind: "artifact",
+		...t.mediaType === void 0 ? {} : { mediaType: t.mediaType },
+		name: t.name,
+		size: t.size
+	};
+}
+function f(e, t) {
+	let f = /* @__PURE__ */ new Map(), p = /* @__PURE__ */ new Map(), m = /* @__PURE__ */ new Map();
+	return async (h) => {
+		let g = n(h, "Runtime event"), _ = r(g.type, "Runtime event type");
+		if (_ == "run.started") {
+			let t = o(g), n = r(g.flowId, "Runtime run.started flowId"), i = f.get(t);
+			if (i != null && i != n) throw TypeError("Runtime run identity changed its flowId.");
+			f.set(t, n);
+			let a = g.parentRunId;
+			if (a !== void 0 && (typeof a != "string" || a.length == 0)) throw TypeError("Runtime run.started parentRunId must be a non-empty string when present.");
+			return {
+				kind: "run.started",
+				payload: {
+					flowId: n,
+					...a === void 0 ? {} : { parentScopeId: await c("scope", e, a) },
+					scopeId: await c("scope", e, t)
+				}
+			};
+		}
+		if (_ == "run.progress") {
+			let t = o(g), n = f.get(t);
+			if (n == null) throw TypeError("Runtime run.progress event preceded its run.started event.");
+			if (typeof g.progress != "number" || !Number.isFinite(g.progress) || g.progress < 0 || g.progress > 100) throw TypeError("Runtime run.progress value must be between 0 and 100.");
+			let r = Math.floor(g.progress);
+			return (m.get(t) ?? -1) >= r ? void 0 : (m.set(t, r), {
+				kind: "run.progress",
+				payload: {
+					flowId: n,
+					progress: g.progress,
+					scopeId: await c("scope", e, t)
+				}
+			});
+		}
+		if (_ == "node.cache-hit" || _ == "node.preview" || _ == "run.completed" || _ == "run.failed" || _ == "run.output") {
+			o(g);
+			return;
+		}
+		if (_ == "node.started" || _ == "node.output" || _ == "node.progress" || _ == "node.artifact" || _ == "node.log" || _ == "node.completed" || _ == "node.failed") {
+			let n = s(g, f, e), o = await n.executionId, m = {
+				executionId: o,
+				flowId: n.flowId,
+				nodeId: n.nodeId,
+				scopeId: await c("scope", e, n.rawRunId)
+			};
+			switch (_) {
+				case "node.output": return {
+					kind: _,
+					payload: {
+						...m,
+						handle: r(g.handle, "Runtime node.output handle")
+					},
+					value: g.value
+				};
+				case "node.started": {
+					let e = a(g.nodeKind), t = i(g.nodeTitle, "Runtime node.started nodeTitle"), n = i(g.operation, "Runtime node.started operation");
+					return {
+						kind: _,
+						payload: {
+							...m,
+							...e === void 0 ? {} : { nodeKind: e },
+							...t === void 0 ? {} : { nodeTitle: t },
+							...n === void 0 ? {} : { operation: n }
+						}
+					};
+				}
+				case "node.progress":
+					if (typeof g.progress != "number" || !Number.isFinite(g.progress) || g.progress < 0 || g.progress > 100) throw TypeError("Runtime node.progress value must be between 0 and 100.");
+					let e = Math.floor(g.progress);
+					return (p.get(o) ?? -1) >= e ? void 0 : (p.set(o, e), {
+						kind: _,
+						payload: {
+							...m,
+							progress: g.progress
+						}
+					});
+				case "node.artifact": return {
+					kind: _,
+					payload: {
+						...m,
+						artifact: d(g.artifact)
+					}
+				};
+				case "node.log":
+					if (![
+						"debug",
+						"info",
+						"warn",
+						"error"
+					].includes(g.level)) throw TypeError("Runtime node.log level is invalid.");
+					return {
+						kind: _,
+						payload: {
+							...m,
+							level: g.level,
+							message: l(g.message)
+						}
+					};
+				case "node.completed": return {
+					kind: _,
+					payload: m
+				};
+				case "node.failed": return {
+					kind: _,
+					payload: {
+						...m,
+						error: {
+							code: u(g.code, t),
+							message: l(g.message)
+						}
+					}
+				};
+			}
+		}
+		throw TypeError(`Runtime event type ${JSON.stringify(_)} is not supported.`);
+	};
+}
+//#endregion
+export { f as createEventProjector };

package/dist/common/run-lifecycle.d.ts

@@ -0,0 +1,69 @@
+export declare const runTerminalStatuses: readonly ['canceled', 'completed', 'failed', 'indeterminate'];
+export declare const runStatuses: readonly ["canceled", "completed", "failed", "indeterminate", "queued", "running", "starting"];
+export type RunStatus = (typeof runStatuses)[number];
+export type RunTerminalStatus = (typeof runTerminalStatuses)[number];
+export type RunOperation = {
+    readonly kind: 'claim';
+} | {
+    readonly kind: 'start';
+} | {
+    readonly kind: 'commit';
+    readonly status: RunTerminalStatus;
+};
+export type RunTransition = {
+    readonly kind: 'ready';
+    readonly status: 'starting';
+} | {
+    readonly kind: 'running';
+    readonly status: 'running';
+} | {
+    readonly kind: 'terminal';
+    readonly status: RunTerminalStatus;
+} | {
+    readonly kind: 'started';
+    readonly status: 'running';
+} | {
+    readonly kind: 'already-started';
+    readonly status: 'running';
+} | {
+    readonly kind: 'committed';
+    readonly status: RunTerminalStatus;
+} | {
+    readonly kind: 'stale';
+    readonly status: RunStatus;
+};
+export type RunClaim = Extract<RunTransition, {
+    readonly kind: 'ready' | 'running' | 'terminal';
+}>;
+export type RunStart = Extract<RunTransition, {
+    readonly kind: 'already-started' | 'started' | 'stale';
+}>;
+export declare function isRunTerminal(status: RunStatus): status is RunTerminalStatus;
+export declare function transitionRun(status: RunStatus, operation: RunOperation): RunTransition;
+export type RunAcceptance = {
+    readonly created: boolean;
+    readonly kind: 'accepted';
+    readonly runId: string;
+    readonly status: RunStatus;
+} | {
+    readonly kind: 'conflict';
+};
+export interface RunObservation {
+    readonly status: RunStatus;
+    readonly terminalEvents: readonly RunTerminalStatus[];
+}
+export interface RunLifecycleHarness {
+    accept(input: {
+        readonly idempotencyKey: string;
+        readonly requestDigest: string;
+    }): Promise<RunAcceptance>;
+    claim(runId: string): Promise<RunClaim>;
+    commit(runId: string, status: RunTerminalStatus): Promise<boolean>;
+    observe(runId: string): Promise<RunObservation>;
+    start(runId: string): Promise<RunStart>;
+}
+export interface RunLifecycleConformanceCase {
+    readonly name: string;
+    verify(harness: RunLifecycleHarness): Promise<void>;
+}
+export declare const runLifecycleConformanceCases: readonly RunLifecycleConformanceCase[];

package/dist/common/run-lifecycle.js

@@ -0,0 +1,169 @@
+//#region ../../node_modules/dequal/lite/index.mjs
+var e = Object.prototype.hasOwnProperty;
+function t(n, r) {
+	var i, a;
+	if (n === r) return !0;
+	if (n && r && (i = n.constructor) === r.constructor) {
+		if (i === Date) return n.getTime() === r.getTime();
+		if (i === RegExp) return n.toString() === r.toString();
+		if (i === Array) {
+			if ((a = n.length) === r.length) for (; a-- && t(n[a], r[a]););
+			return a === -1;
+		}
+		if (!i || typeof n == "object") {
+			for (i in a = 0, n) if (e.call(n, i) && ++a && !e.call(r, i) || !(i in r) || !t(n[i], r[i])) return !1;
+			return Object.keys(r).length === a;
+		}
+	}
+	return n !== n && r !== r;
+}
+//#endregion
+//#region src/execution/common/runLifecycle.ts
+var n = [
+	"canceled",
+	"completed",
+	"failed",
+	"indeterminate"
+], r = [
+	...n,
+	"queued",
+	"running",
+	"starting"
+];
+function i(e) {
+	return e == "canceled" || e == "completed" || e == "failed" || e == "indeterminate";
+}
+function a(e, t) {
+	switch (t.kind) {
+		case "claim": switch (e) {
+			case "queued":
+			case "starting": return {
+				kind: "ready",
+				status: "starting"
+			};
+			case "running": return {
+				kind: "running",
+				status: e
+			};
+			case "canceled":
+			case "completed":
+			case "failed":
+			case "indeterminate": return {
+				kind: "terminal",
+				status: e
+			};
+		}
+		case "start": switch (e) {
+			case "starting": return {
+				kind: "started",
+				status: "running"
+			};
+			case "running": return {
+				kind: "already-started",
+				status: e
+			};
+			case "queued":
+			case "canceled":
+			case "completed":
+			case "failed":
+			case "indeterminate": return {
+				kind: "stale",
+				status: e
+			};
+		}
+		case "commit": return i(e) ? {
+			kind: "stale",
+			status: e
+		} : t.status == "canceled" || e == "running" ? {
+			kind: "committed",
+			status: t.status
+		} : {
+			kind: "stale",
+			status: e
+		};
+	}
+}
+function o(e, n, r) {
+	if (!t(e, n)) throw Error(`${r}: expected ${JSON.stringify(n)}, received ${JSON.stringify(e)}.`);
+}
+async function s(e, t = "request", n = "request-a") {
+	let r = await e.accept({
+		idempotencyKey: t,
+		requestDigest: n
+	});
+	if (r.kind != "accepted") throw Error("Run acceptance unexpectedly conflicted.");
+	return r.runId;
+}
+var c = [
+	{
+		name: "replays idempotent acceptance and rejects a conflicting request",
+		async verify(e) {
+			let t = await e.accept({
+				idempotencyKey: "same-key",
+				requestDigest: "request-a"
+			});
+			if (t.kind != "accepted") throw Error("Initial Run acceptance unexpectedly conflicted.");
+			o(t.created, !0, "Initial acceptance creation"), o(t.status, "queued", "Initial acceptance status"), o(await e.accept({
+				idempotencyKey: "same-key",
+				requestDigest: "request-a"
+			}), {
+				...t,
+				created: !1
+			}, "Idempotent replay"), o(await e.accept({
+				idempotencyKey: "same-key",
+				requestDigest: "request-b"
+			}), { kind: "conflict" }, "Conflicting replay"), o(await e.observe(t.runId), {
+				status: "queued",
+				terminalEvents: []
+			}, "Accepted Run observation");
+		}
+	},
+	{
+		name: "cancels before the start barrier and preserves one terminal",
+		async verify(e) {
+			let t = await s(e);
+			o(await e.commit(t, "canceled"), !0, "Cancellation commit"), o(await e.claim(t), a("canceled", { kind: "claim" }), "Claim after cancellation"), o(await e.commit(t, "completed"), !1, "Completion after cancellation"), o(await e.observe(t), {
+				status: "canceled",
+				terminalEvents: ["canceled"]
+			}, "Canceled Run observation");
+		}
+	},
+	{
+		name: "recovers before the start barrier without creating another Run",
+		async verify(e) {
+			let t = await s(e), n = a("queued", { kind: "claim" });
+			o(await e.claim(t), n, "Initial claim");
+			let r = a(n.status, { kind: "claim" });
+			o(await e.claim(t), r, "Recovered claim");
+			let i = a(r.status, { kind: "start" });
+			o(await e.start(t), i, "Start after recovery"), o(await e.commit(t, "completed"), !0, "Completion after recovery"), o(await e.observe(t), {
+				status: "completed",
+				terminalEvents: ["completed"]
+			}, "Recovered Run observation");
+		}
+	},
+	{
+		name: "marks recovery after the start barrier indeterminate",
+		async verify(e) {
+			let t = await s(e), n = a("queued", { kind: "claim" });
+			o(await e.claim(t), n, "Initial claim");
+			let r = a(n.status, { kind: "start" });
+			o(await e.start(t), r, "Start barrier"), o(await e.claim(t), a(r.status, { kind: "claim" }), "Claim after start barrier"), o(await e.commit(t, "indeterminate"), !0, "Indeterminate commit"), o(await e.commit(t, "completed"), !1, "Completion after indeterminate"), o(await e.observe(t), {
+				status: "indeterminate",
+				terminalEvents: ["indeterminate"]
+			}, "Indeterminate Run observation");
+		}
+	},
+	{
+		name: "allows exactly one terminal to win cancellation and completion",
+		async verify(e) {
+			let t = await s(e), n = a("queued", { kind: "claim" });
+			o(await e.claim(t), n, "Initial claim"), o(await e.start(t), a(n.status, { kind: "start" }), "Start barrier"), o((await Promise.all([e.commit(t, "canceled"), e.commit(t, "completed")])).filter(Boolean).length, 1, "Accepted terminal count");
+			let r = await e.observe(t);
+			if (r.status != "canceled" && r.status != "completed") throw Error(`Terminal race produced ${r.status}.`);
+			o(r.terminalEvents, [r.status], "Terminal race events");
+		}
+	}
+];
+//#endregion
+export { i as isRunTerminal, c as runLifecycleConformanceCases, r as runStatuses, n as runTerminalStatuses, a as transitionRun };

package/dist/common/runtime-contract.d.ts

@@ -0,0 +1,53 @@
+import type { CodeModule, JsonValue } from '../browser/project-change.js';
+export { currentEngineContract, findEngineContract, type EngineContract } from './engine-contract.js';
+export type RuntimeModule = Pick<CodeModule, 'imports' | 'source'>;
+export interface RuntimeProgram {
+    readonly engineContract: string;
+    readonly engineDigest: string;
+    readonly entryModuleId: string;
+    readonly modules: Readonly<Record<string, RuntimeModule>>;
+}
+export interface RuntimeCapabilityCall {
+    readonly invocationId: string;
+    readonly kind: string;
+    readonly payload: JsonValue;
+    readonly signal: AbortSignal;
+}
+export interface RuntimeCapabilityResponse {
+    readonly body: JsonValue;
+    readonly status: number;
+}
+export interface LlmTaskInvocation {
+    readonly input: Readonly<Record<string, JsonValue>>;
+    readonly invocationId: string;
+    readonly mode: 'chat' | 'json';
+    readonly signal: AbortSignal;
+    readonly version: 1;
+}
+export type LlmTaskResult = {
+    readonly kind: 'completed';
+    readonly value: JsonValue;
+    readonly version: 1;
+} | {
+    readonly code: 'llm.output-invalid' | 'llm.unavailable';
+    readonly kind: 'failed';
+    readonly message: string;
+    readonly version: 1;
+};
+export type InvokeLlmTask = (invocation: LlmTaskInvocation) => Promise<LlmTaskResult>;
+export interface RuntimeInvocation {
+    readonly capability: (call: RuntimeCapabilityCall) => Promise<RuntimeCapabilityResponse>;
+    readonly input: JsonValue;
+    readonly invocationId: string;
+    readonly program: RuntimeProgram;
+    readonly signal?: AbortSignal;
+}
+export interface RuntimeHarness {
+    readonly engineDigest: string;
+    invoke(invocation: RuntimeInvocation): Promise<JsonValue>;
+}
+export interface RuntimeConformanceCase {
+    readonly name: string;
+    verify(harness: RuntimeHarness): Promise<void>;
+}
+export declare const runtimeConformanceCases: readonly RuntimeConformanceCase[];

package/dist/common/runtime-contract.js

@@ -0,0 +1,151 @@
+//#region ../../node_modules/dequal/lite/index.mjs
+var e = Object.prototype.hasOwnProperty;
+function t(n, r) {
+	var i, a;
+	if (n === r) return !0;
+	if (n && r && (i = n.constructor) === r.constructor) {
+		if (i === Date) return n.getTime() === r.getTime();
+		if (i === RegExp) return n.toString() === r.toString();
+		if (i === Array) {
+			if ((a = n.length) === r.length) for (; a-- && t(n[a], r[a]););
+			return a === -1;
+		}
+		if (!i || typeof n == "object") {
+			for (i in a = 0, n) if (e.call(n, i) && ++a && !e.call(r, i) || !(i in r) || !t(n[i], r[i])) return !1;
+			return Object.keys(r).length === a;
+		}
+	}
+	return n !== n && r !== r;
+}
+//#endregion
+//#region src/execution/common/engineContract.ts
+var n = "open-flow-engine/v1", r = {
+	platformExports: /* @__PURE__ */ new Set(["engineContract", "identity"]),
+	platformModule: "open-flow:platform",
+	platformSource: `export const engineContract = ${JSON.stringify(n)}
+export function identity(value) { return value }
+`
+};
+function i(e) {
+	return e == "open-flow-engine/v1" ? r : void 0;
+}
+//#endregion
+//#region src/execution/common/runtime.ts
+function a(e, t, r = {}) {
+	return {
+		engineContract: n,
+		engineDigest: e.engineDigest,
+		entryModuleId: "main",
+		modules: {
+			...r,
+			main: {
+				imports: Object.keys(r),
+				source: t
+			}
+		}
+	};
+}
+function o(e, n, r) {
+	if (!t(e, n)) throw Error(`${r}: expected ${JSON.stringify(n)}, received ${JSON.stringify(e)}.`);
+}
+async function s(e, t, n) {
+	try {
+		await e;
+	} catch (e) {
+		if (t.test(e instanceof Error ? e.message : String(e))) return;
+		throw Error(`${n}: received ${e instanceof Error ? e.message : String(e)}.`, { cause: e });
+	}
+	throw Error(`${n}: operation unexpectedly succeeded.`);
+}
+var c = [
+	{
+		name: "loads the fixed ESM closure and platform module",
+		async verify(e) {
+			o(await e.invoke({
+				capability: async () => {
+					throw Error("Capability must not be called.");
+				},
+				input: { value: 6 },
+				invocationId: "module-closure",
+				program: a(e, "import { double } from './helper.mjs'\nimport { engineContract, identity } from 'open-flow:platform'\nexport default (input) => ({ engineContract, value: identity(double(input.value)) })", { helper: {
+					imports: [],
+					source: "export const double = (value) => value * 2"
+				} })
+			}), {
+				engineContract: n,
+				value: 12
+			}, "ESM closure result");
+		}
+	},
+	{
+		name: "rejects modules outside the fixed closure",
+		async verify(e) {
+			await s(e.invoke({
+				capability: async () => ({
+					body: null,
+					status: 200
+				}),
+				input: null,
+				invocationId: "closed-linker",
+				program: a(e, "import fs from 'node:fs'\nexport default () => fs.readFileSync('/etc/passwd', 'utf8')")
+			}), /invalid|unsupported|cannot import|not part of/i, "Closed linker");
+		}
+	},
+	{
+		name: "copies asynchronous Capability requests and responses",
+		async verify(e) {
+			let t = [];
+			o(await e.invoke({
+				capability: async (e) => (t.push(e), {
+					body: {
+						accepted: !0,
+						echoed: e.payload
+					},
+					status: 200
+				}),
+				input: { issue: 42 },
+				invocationId: "async-capability",
+				program: a(e, "export default async (input, capability) => capability.connector({ action: 'read', input })")
+			}), {
+				body: {
+					accepted: !0,
+					echoed: {
+						action: "read",
+						input: { issue: 42 }
+					}
+				},
+				status: 200
+			}, "Capability result"), o(t.map(({ invocationId: e, kind: t, payload: n }) => ({
+				invocationId: e,
+				kind: t,
+				payload: n
+			})), [{
+				invocationId: "async-capability",
+				kind: "connector",
+				payload: {
+					action: "read",
+					input: { issue: 42 }
+				}
+			}], "Capability request");
+		}
+	},
+	{
+		name: "cancels a pending Capability and the user invocation",
+		async verify(e) {
+			let t = new AbortController(), n = !1, r, i = new Promise((e) => {
+				r = e;
+			}), c = e.invoke({
+				capability: async ({ signal: e }) => (r(), await new Promise((t, r) => e.addEventListener("abort", () => {
+					n = !0, r(e.reason);
+				}, { once: !0 }))),
+				input: null,
+				invocationId: "canceled-capability",
+				program: a(e, "export default async (_input, capability) => capability.connector({ action: 'wait' })"),
+				signal: t.signal
+			});
+			await i, t.abort(/* @__PURE__ */ Error("Invocation canceled.")), await s(c, /cancel|abort|disposed/i, "Canceled invocation"), o(n, !0, "Capability cancellation");
+		}
+	}
+];
+//#endregion
+export { n as currentEngineContract, i as findEngineContract, c as runtimeConformanceCases };