@oomol-lab/open-flow 0.1.0-beta.76 → 0.1.0-beta.78

package/dist/common/mcp.d.ts

@@ -3,6 +3,99 @@ import { z } from 'zod';
 export declare const mcpProtocolVersion = "2026-07-28";
 export declare const mcpInstructions: string;
 export declare const mcpTools: {
+    flow_state: {
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+        inputSchema: {
+            '~standard': {
+                version: 1;
+                vendor: string;
+                jsonSchema: {
+                    input: () => Record<string, unknown>;
+                    output: () => Record<string, unknown>;
+                };
+                validate(value: unknown): {
+                    value: {
+                        scope: "draft" | "live";
+                        values?: boolean | undefined;
+                        flowId: string;
+                    };
+                } | {
+                    issues: {
+                        message: string;
+                        path: string[];
+                    }[];
+                };
+            };
+        };
+    };
+    flow_state_clear: {
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+        inputSchema: {
+            '~standard': {
+                version: 1;
+                vendor: string;
+                jsonSchema: {
+                    input: () => Record<string, unknown>;
+                    output: () => Record<string, unknown>;
+                };
+                validate(value: unknown): {
+                    value: {
+                        scope: "draft" | "live";
+                        key?: string | undefined;
+                        flowId: string;
+                    };
+                } | {
+                    issues: {
+                        message: string;
+                        path: string[];
+                    }[];
+                };
+            };
+        };
+    };
+    flow_dedupe_clear: {
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+        inputSchema: {
+            '~standard': {
+                version: 1;
+                vendor: string;
+                jsonSchema: {
+                    input: () => Record<string, unknown>;
+                    output: () => Record<string, unknown>;
+                };
+                validate(value: unknown): {
+                    value: {
+                        scope: "draft" | "live";
+                        space: string;
+                        flowId: string;
+                    };
+                } | {
+                    issues: {
+                        message: string;
+                        path: string[];
+                    }[];
+                };
+            };
+        };
+    };
     flow_canvas: {
         description: string;
         annotations: {
@@ -161,7 +254,7 @@ export declare const mcpTools: {
                     value: {
                         revision?: string | undefined;
                         query: string;
-                        type?: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow" | undefined;
+                        type?: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "skip-duplicates" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow" | undefined;
                         offset: number;
                         limit: number;
                         flowId: string;
@@ -193,7 +286,7 @@ export declare const mcpTools: {
                 };
                 validate(value: unknown): {
                     value: {
-                        type?: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow" | undefined;
+                        type?: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "skip-duplicates" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow" | undefined;
                         action?: string | undefined;
                         flowId?: string | undefined;
                     };
@@ -321,7 +414,7 @@ export declare const mcpTools: {
                         edits: ({
                             op: "node.add";
                             as: string;
-                            type: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow";
+                            type: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "skip-duplicates" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow";
                             name: string;
                             onError?: "error" | "stop" | undefined;
                             retry?: {

package/dist/common/mcp.js

@@ -8846,6 +8846,46 @@ var httpRequestConfigSchema = strictObject({
 	statusPolicy: _enum(["success", "all"]).default("success")
 });
 var httpRequestExecutorSchema = httpRequestConfigSchema.extend({ kind: literal("http-request") });
+//#endregion
+//#region src/state/common/state.ts
+var stateQuerySchema = strictObject({
+	scope: _enum(["draft", "live"]),
+	values: boolean().optional()
+});
+var stateClearSchema = strictObject({
+	scope: _enum(["draft", "live"]),
+	key: string$1().min(1).refine((key) => new TextEncoder().encode(key).length <= 256).optional()
+});
+var dedupeClearSchema = strictObject({
+	scope: _enum(["draft", "live"]),
+	space: string$1().regex(/^(flow|node:.+)$/)
+});
+var skipDuplicatesConfigSchema = strictObject({ fields: array(string$1().refine((field) => field.length > 0 && field.split(".").every((part) => part.length > 0), "Use a nonempty dot-separated field path.")).refine((fields) => new Set(fields).size === fields.length, "Identity fields must be distinct.").default([]) });
+var skipDuplicatesExecutorSchema = skipDuplicatesConfigSchema.extend({ kind: literal("skip-duplicates") });
+var flowStateViewSchema = object({
+	version: literal(1),
+	scope: _enum(["draft", "live"]),
+	limits: object({
+		maxValueBytes: number().positive(),
+		maxValues: number().int().positive(),
+		maxSpaces: number().int().positive(),
+		maxIdentities: number().positive(),
+		maxRunWrites: number().positive()
+	}),
+	values: array(object({
+		key: string$1(),
+		size: number().nonnegative(),
+		updatedAt: number(),
+		value: json$4().optional()
+	})),
+	spaces: array(object({
+		space: string$1(),
+		count: number().nonnegative(),
+		pendingCount: number().nonnegative(),
+		reservedCount: number().nonnegative(),
+		updatedAt: number()
+	}))
+});
 function checkJsonDepth(value, depth = 0) {
 	if (depth > 64) throw new TypeError("Value exceeds the maximum JSON depth.");
 	if (value != null && typeof value == "object") for (const child of Object.values(value)) checkJsonDepth(child, depth + 1);
@@ -9134,7 +9174,8 @@ var managedFields = object({
 			flowId: text,
 			revisionId: text
 		}),
-		httpRequestExecutorSchema
+		httpRequestExecutorSchema,
+		skipDuplicatesExecutorSchema
 	])
 });
 var managed = managedFields.transform(limitDecisionTask);
@@ -9404,7 +9445,8 @@ var revision = object({
 		literal(9),
 		literal(10),
 		literal(11),
-		literal(12)
+		literal(12),
+		literal(13)
 	]),
 	document,
 	modules: record$2(text, module)
@@ -9605,6 +9647,7 @@ array(union([...new Map(Object.entries(shapes).map(([kind, shape]) => [kind, sha
 	...shape
 })])).values()])).min(1);
 function checkModelVersion(content) {
+	if (content.modelVersion < 13 && Object.values(content.document.graph.nodes).some((candidateNode) => candidateNode.kind === "task" && "executor" in candidateNode.task && candidateNode.task.executor.kind === "skip-duplicates")) throw new Error("Skip Duplicates requires Flow model v13.");
 	if (content.modelVersion < 12 && Object.values(content.document.graph.nodes).some((candidateNode) => candidateNode.kind == "task" && "moduleId" in candidateNode.task && candidateNode.task.capabilities?.some((item) => item.kind == "http"))) throw new TypeError("Code HTTP access requires Flow model version 12.");
 	if (content.modelVersion < 11 && Object.values(content.document.graph.nodes).some((candidateNode) => candidateNode.kind == "task" && "executor" in candidateNode.task && candidateNode.task.executor.kind == "http-request")) throw new TypeError("HTTP Request requires Flow model version 11.");
 	if (content.modelVersion < 11 && Object.values(content.document.graph.nodes).some((candidateNode) => candidateNode.kind == "task" && ("moduleId" in candidateNode.task ? candidateNode.task.capabilities?.some((item) => item.kind == "workflow") : candidateNode.task.executor.kind == "agent" && candidateNode.task.executor.tools.some((item) => item.kind == "workflow")))) throw new TypeError("Workflow tools require Flow model version 11.");
@@ -9636,8 +9679,8 @@ function resourceNameIssue(value) {
 }
 //#endregion
 //#region src/runtime/common/engineContract.ts
-/** v9 is a single contract: the Node compatibility builtins, `context.fetch`, and no `context.egress`. */
-var currentEngineContract = "open-flow-engine/v9";
+/** 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 platformSource = (contract) => `export const engineContract = ${JSON.stringify(contract)}
@@ -9682,13 +9725,19 @@ var nodejsContract = {
 	].flatMap((name) => [name, `node:${name}`])),
 	platformSource: platformSource(nodejsEngineContract)
 };
-var currentContract = {
+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/v9") 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 {
@@ -9755,6 +9804,7 @@ var type = _enum([
 	"decision",
 	"openapi",
 	"http-request",
+	"skip-duplicates",
 	"condition",
 	"value",
 	"wait",
@@ -9885,6 +9935,7 @@ var authoringConfigurations = {
 	"connector": authoringDefinitionSchemas.connector.omit({ outputMode: true }).strict(),
 	"openapi": authoringOpenApiSchema,
 	"http-request": httpRequestConfigSchema,
+	"skip-duplicates": skipDuplicatesConfigSchema,
 	"agent": authoringDefinitionSchemas.agent.omit({
 		prompt: true,
 		tools: true
@@ -10160,11 +10211,14 @@ var controlErrorCode = {
 	triggerKeyInvalid: "trigger-key.invalid",
 	triggerKeyNotFound: "trigger-key.not-found",
 	triggerNotFound: "trigger.not-found",
+	tagInvalid: "tag.invalid",
+	tagConflict: "tag.conflict",
+	tagNotFound: "tag.not-found",
 	variableInvalid: "variable.invalid",
 	variableLimitReached: "variable.limit-reached",
 	variableNotFound: "variable.not-found"
 };
-controlErrorCode.eventSourceInvalid, controlErrorCode.eventSourceIdentityUnavailable, controlErrorCode.eventSourceNotFound, controlErrorCode.eventSourceConflict, controlErrorCode.authenticationRequired, controlErrorCode.authorizationDenied, controlErrorCode.bindingUnresolved, controlErrorCode.connectorActionNotFound, controlErrorCode.connectorAccessConflict, controlErrorCode.connectorAccessInvalid, controlErrorCode.connectorAccessRequired, controlErrorCode.connectorAccessUnsupported, controlErrorCode.connectorUnconfigured, controlErrorCode.connectorUnavailable, controlErrorCode.connectorConsoleUnconfigured, controlErrorCode.engineUnavailable, controlErrorCode.engineUnsupported, controlErrorCode.flowInvalid, controlErrorCode.flowRepairRequired, controlErrorCode.flowUpgradeRequired, controlErrorCode.flowNotFound, controlErrorCode.flowBusy, controlErrorCode.flowConflict, controlErrorCode.flowPresentationConflict, controlErrorCode.flowRevisionConflict, controlErrorCode.liveConflict, controlErrorCode.liveNotFound, controlErrorCode.pageInvalidCursor, controlErrorCode.publicationConflict, controlErrorCode.publicationNotFound, controlErrorCode.publicationUnsupported, controlErrorCode.publishOperationNotFound, controlErrorCode.routeNotFound, controlErrorCode.runConflict, controlErrorCode.runEventsExpired, controlErrorCode.runInvalid, controlErrorCode.runNotFound, controlErrorCode.runNotTerminal, controlErrorCode.runOverloaded, controlErrorCode.runWaitNotFound, controlErrorCode.triggerKeyInvalid, controlErrorCode.triggerKeyNotFound, controlErrorCode.triggerNotFound, controlErrorCode.variableInvalid, controlErrorCode.variableLimitReached, controlErrorCode.variableNotFound;
+controlErrorCode.eventSourceInvalid, controlErrorCode.eventSourceIdentityUnavailable, controlErrorCode.eventSourceNotFound, controlErrorCode.eventSourceConflict, controlErrorCode.authenticationRequired, controlErrorCode.authorizationDenied, controlErrorCode.bindingUnresolved, controlErrorCode.connectorActionNotFound, controlErrorCode.connectorAccessConflict, controlErrorCode.connectorAccessInvalid, controlErrorCode.connectorAccessRequired, controlErrorCode.connectorAccessUnsupported, controlErrorCode.connectorUnconfigured, controlErrorCode.connectorUnavailable, controlErrorCode.connectorConsoleUnconfigured, controlErrorCode.engineUnavailable, controlErrorCode.engineUnsupported, controlErrorCode.flowInvalid, controlErrorCode.flowRepairRequired, controlErrorCode.flowUpgradeRequired, controlErrorCode.flowNotFound, controlErrorCode.flowBusy, controlErrorCode.flowConflict, controlErrorCode.flowPresentationConflict, controlErrorCode.flowRevisionConflict, controlErrorCode.liveConflict, controlErrorCode.liveNotFound, controlErrorCode.pageInvalidCursor, controlErrorCode.publicationConflict, controlErrorCode.publicationNotFound, controlErrorCode.publicationUnsupported, controlErrorCode.publishOperationNotFound, controlErrorCode.routeNotFound, controlErrorCode.runConflict, controlErrorCode.runEventsExpired, controlErrorCode.runInvalid, controlErrorCode.runNotFound, controlErrorCode.runNotTerminal, controlErrorCode.runOverloaded, controlErrorCode.runWaitNotFound, controlErrorCode.triggerKeyInvalid, controlErrorCode.triggerKeyNotFound, controlErrorCode.triggerNotFound, controlErrorCode.tagInvalid, controlErrorCode.tagConflict, controlErrorCode.tagNotFound, controlErrorCode.variableInvalid, controlErrorCode.variableLimitReached, controlErrorCode.variableNotFound;
 var ApiError = class extends Error {
 	constructor(status, code, message, details) {
 		super(message);
@@ -11430,6 +11484,7 @@ function flow$1(value) {
 			publicationId: string(target.publicationId),
 			revisionId: string(target.revisionId)
 		} },
+		tagIds: source.tagIds === void 0 ? [] : strings(source.tagIds),
 		createdAt: string(source.createdAt),
 		...source.connectorTeamId == null ? {} : { connectorTeamId: string(source.connectorTeamId) },
 		draftRevisionId: string(source.draftRevisionId),
@@ -11864,6 +11919,33 @@ function randomId() {
 	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
 //#endregion
+//#region src/control/common/tags.ts
+function normalizeFlowQuery(query = {}) {
+	return {
+		query: query.query?.trim().toLowerCase() ?? "",
+		tagIds: [...new Set(query.tagIds ?? [])].toSorted(),
+		untagged: query.untagged ?? false
+	};
+}
+function decodeTag(value) {
+	const source = record(value);
+	if (source.version != 1) return invalidResponse();
+	return {
+		tagId: string(source.tagId),
+		name: string(source.name),
+		version: 1
+	};
+}
+function decodeTagListItem(value) {
+	const source = record(value);
+	const referenceCount = integer(source.referenceCount);
+	if (referenceCount < 0) return invalidResponse();
+	return {
+		...decodeTag(source),
+		referenceCount
+	};
+}
+//#endregion
 //#region src/control/common/api.ts
 function decodeRunEvent(value) {
 	const source = record(value);
@@ -11967,7 +12049,7 @@ function decodeRunEvent(value) {
 			switch (kind) {
 				case "node.started": {
 					const nodeKind = payload.nodeKind;
-					if (nodeKind !== void 0 && nodeKind !== "approval" && nodeKind !== "condition" && nodeKind !== "connector" && nodeKind !== "javascript" && nodeKind !== "decision" && nodeKind !== "openapi" && nodeKind !== "http-request" && nodeKind !== "llm" && nodeKind !== "agent" && nodeKind !== "value" && nodeKind !== "outputs" && nodeKind !== "webhook-response" && nodeKind !== "workflow" && nodeKind !== "wait") return invalidResponse();
+					if (nodeKind !== void 0 && nodeKind !== "approval" && nodeKind !== "condition" && nodeKind !== "connector" && nodeKind !== "javascript" && nodeKind !== "decision" && nodeKind !== "openapi" && nodeKind !== "http-request" && nodeKind !== "skip-duplicates" && nodeKind !== "llm" && nodeKind !== "agent" && nodeKind !== "value" && nodeKind !== "outputs" && nodeKind !== "webhook-response" && nodeKind !== "workflow" && nodeKind !== "wait") return invalidResponse();
 					return {
 						...base,
 						kind,
@@ -12094,6 +12176,10 @@ var ControlClient = class {
 	}
 	async listFlows(options = {}) {
 		const parameters = new URLSearchParams();
+		const filter = normalizeFlowQuery(options);
+		if (filter.query) parameters.set("query", filter.query);
+		if (filter.tagIds.length) parameters.set("tagIds", filter.tagIds.join(","));
+		if (filter.untagged) parameters.set("untagged", "true");
 		if (options.cursor != null) parameters.set("cursor", options.cursor);
 		if (options.limit != null) parameters.set("limit", String(options.limit));
 		if (options.includeTotal != null) parameters.set("includeTotal", String(options.includeTotal));
@@ -12183,15 +12269,18 @@ var ControlClient = class {
 				file,
 				name: options.name,
 				teamId: options.teamId,
+				tagIds: options.tagIds,
 				version: 1
 			})
 		}));
 	}
-	async createFlow(name, idempotencyKey = `flow-${randomId()}`, teamId) {
+	async createFlow(name, idempotencyKey = `flow-${randomId()}`, teamId, tagIds, initialPresentation) {
 		return flow$1(await this.request("/v1/flows", {
 			body: JSON.stringify({
 				name,
 				...teamId == null ? {} : { teamId },
+				...tagIds == null ? {} : { tagIds },
+				...initialPresentation == null ? {} : { presentation: initialPresentation },
 				version: 1
 			}),
 			headers: { "idempotency-key": idempotencyKey },
@@ -12226,15 +12315,68 @@ var ControlClient = class {
 		if (source.version != 1 || !Array.isArray(source.listeners)) return invalidResponse();
 		return source.listeners.map(errorListener);
 	}
-	async renameFlow(flowId, name) {
-		return flow$1(await this.request(`/v1/flows/${segment(flowId)}`, {
+	async listTags(signal) {
+		const source = record(await this.request("/v1/tags", { signal }));
+		if (source.version != 1 || !Array.isArray(source.tags)) return invalidResponse();
+		return {
+			tags: source.tags.map(decodeTagListItem),
+			version: 1
+		};
+	}
+	async createTag(name) {
+		return decodeTag(await this.request("/v1/tags", {
+			method: "POST",
 			body: JSON.stringify({
 				name,
 				version: 1
-			}),
-			method: "PATCH"
+			})
+		}));
+	}
+	async renameTag(tagId, name) {
+		return decodeTag(await this.request(`/v1/tags/${segment(tagId)}`, {
+			method: "PATCH",
+			body: JSON.stringify({
+				name,
+				version: 1
+			})
+		}));
+	}
+	async deleteTag(tagId) {
+		if (record(await this.request(`/v1/tags/${segment(tagId)}`, { method: "DELETE" })).version != 1) invalidResponse();
+	}
+	async setFlowTags(flowId, tagIds) {
+		return flow$1(await this.request(`/v1/flows/${segment(flowId)}/tags`, {
+			method: "PUT",
+			body: JSON.stringify({
+				tagIds,
+				version: 1
+			})
 		}));
 	}
+	async updateFlow(flowId, changes) {
+		return flow$1(await this.request(`/v1/flows/${segment(flowId)}`, {
+			method: "PATCH",
+			body: JSON.stringify({
+				...changes,
+				version: 1
+			})
+		}));
+	}
+	async getFlowState(flowId, scope, values = false) {
+		const result = flowStateViewSchema.safeParse(await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}&values=${values}`));
+		return result.success && result.data.scope === scope ? result.data : invalidResponse();
+	}
+	async clearFlowState(flowId, scope, key) {
+		const source = record(await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}${key == null ? "" : `&key=${encodeURIComponent(key)}`}`, { method: "DELETE" }));
+		if (source.version !== 1 || source.cleared !== true) invalidResponse();
+	}
+	async clearFlowDedupe(flowId, scope, space) {
+		const source = record(await this.request(`/v1/flows/${segment(flowId)}/dedupe?scope=${scope}&space=${encodeURIComponent(space)}`, { method: "DELETE" }));
+		if (source.version !== 1 || source.cleared !== true) invalidResponse();
+	}
+	async renameFlow(flowId, name) {
+		return this.updateFlow(flowId, { name });
+	}
 	async deleteFlow(flowId) {
 		return flow$1(await this.request(`/v1/flows/${segment(flowId)}`, { method: "DELETE" }));
 	}
@@ -12986,6 +13128,9 @@ function tool(description, schema, readOnly, idempotent = true) {
 	};
 }
 var mcpTools = {
+	flow_state: tool("Inspect Flow state usage, business keys and deduplication spaces. Values are omitted unless requested. Scope is required.", stateQuerySchema.extend({ flowId: flow }), true),
+	flow_state_clear: tool("Delete one business state key or clear all business values. Explicit draft/live scope is required; live changes production state immediately.", stateClearSchema.extend({ flowId: flow }), false),
+	flow_dedupe_clear: tool("Clear one deduplication space (flow or node:<id>). Explicit draft/live scope is required; live changes production history immediately.", dedupeClearSchema.extend({ flowId: flow }), false),
 	flow_canvas: tool("Broadcast a transient canvas command to connected Workbenches viewing this Flow. Success only confirms Server broadcast, not delivery or execution. No replay, session selection or Presentation save. Pan uses screen pixels (positive right/down); zoom is an absolute ratio (0.1–3); fit includes all nodes. Repeating pan moves again.", strictObject({
 		flowId: flow,
 		command: canvasCommandSchema

package/dist/common/run-events.js

@@ -54,6 +54,7 @@ var nodeKinds = /* @__PURE__ */ new Set([
 	"javascript",
 	"openapi",
 	"http-request",
+	"skip-duplicates",
 	"llm",
 	"value",
 	"wait",
@@ -80,12 +81,12 @@ function nodeKind(value) {
 function runId(event) {
 	return string(event.runId, "Runtime event runId");
 }
-function nodeContext(event, flows, platformRunId) {
+function nodeContext(event, flows, platformRunId, identify) {
 	const rawRunId = runId(event);
 	const flowId = flows.get(rawRunId);
 	if (flowId == null) throw new TypeError("Runtime node event preceded its run.started event.");
 	return {
-		executionId: projectExecutionId(platformRunId, rawRunId, string(event.jobId, "Runtime node event jobId")),
+		executionId: identify("execution", platformRunId, rawRunId, string(event.jobId, "Runtime node event jobId")),
 		flowId,
 		nodeId: string(event.nodeId, "Runtime node event nodeId"),
 		rawRunId
@@ -138,6 +139,16 @@ function createEventProjector(platformRunId, nodeFailureCodes) {
 	const jobs = /* @__PURE__ */ new Map();
 	const nodeProgressBuckets = /* @__PURE__ */ new Map();
 	const runProgressBuckets = /* @__PURE__ */ new Map();
+	const identities = /* @__PURE__ */ new Map();
+	const identify = (prefix, ...parts) => {
+		const key = JSON.stringify([prefix, ...parts]);
+		let identity = identities.get(key);
+		if (identity == null) {
+			identity = opaqueId(prefix, ...parts);
+			identities.set(key, identity);
+		}
+		return identity;
+	};
 	return async (value) => {
 		const event = object(value, "Runtime event");
 		const type = string(event.type, "Runtime event type");
@@ -156,8 +167,8 @@ function createEventProjector(platformRunId, nodeFailureCodes) {
 				kind: "run.started",
 				payload: {
 					flowId,
-					...parentRunId === void 0 ? {} : { parentScopeId: await opaqueId("scope", platformRunId, parentRunId) },
-					scopeId: await opaqueId("scope", platformRunId, rawRunId)
+					...parentRunId === void 0 ? {} : { parentScopeId: await identify("scope", platformRunId, parentRunId) },
+					scopeId: await identify("scope", platformRunId, rawRunId)
 				}
 			};
 		}
@@ -174,7 +185,7 @@ function createEventProjector(platformRunId, nodeFailureCodes) {
 				payload: {
 					flowId,
 					progress: event.progress,
-					scopeId: await opaqueId("scope", platformRunId, rawRunId)
+					scopeId: await identify("scope", platformRunId, rawRunId)
 				}
 			};
 		}
@@ -182,7 +193,7 @@ function createEventProjector(platformRunId, nodeFailureCodes) {
 			const rawRunId = runId(event);
 			if (type == "run.failed" && rawRunId == platformRunId && event.failure != null) {
 				const failure = object(event.failure, "Runtime terminal failure");
-				const context = nodeContext(failure, flows, platformRunId);
+				const context = nodeContext(failure, flows, platformRunId, identify);
 				return {
 					kind: "node.failed",
 					payload: {
@@ -200,13 +211,13 @@ function createEventProjector(platformRunId, nodeFailureCodes) {
 			return;
 		}
 		if (type == "node.started" || type == "node.progress" || type == "node.artifact" || type == "node.log" || type == "node.completed" || type == "node.failed") {
-			const context = nodeContext(event, flows, platformRunId);
+			const context = nodeContext(event, flows, platformRunId, identify);
 			const executionId = await context.executionId;
 			const payload = {
 				executionId,
 				flowId: context.flowId,
 				nodeId: context.nodeId,
-				scopeId: await opaqueId("scope", platformRunId, context.rawRunId),
+				scopeId: await identify("scope", platformRunId, context.rawRunId),
 				...event.systemOutputs === void 0 ? {} : { systemOutputs: object(event.systemOutputs, "Runtime system outputs") },
 				...event.handled === true ? { handled: true } : {}
 			};

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

@@ -1,5 +1,19 @@
 import type { CodeModule, ConnectorCapability, TaskCapability, JsonValue } from './flow-model.js';
 export { currentEngineContract, nodejsEngineContract, findEngineContract, type EngineContract } from './engine-contract.js';
+/** Serialized into the guest; keep validation and helpers self-contained. */
+export declare function createState(invoke: (kind: string, payload: JsonValue) => Promise<RuntimeCapabilityResponse>): {
+    state: Readonly<{
+        get(key: unknown): Promise<JsonValue>;
+        set(key: unknown, value: unknown): Promise<void>;
+        insert(key: unknown, value: unknown): Promise<boolean>;
+        delete(key: unknown): Promise<void>;
+        list(): Promise<string[]>;
+    }>;
+    dedupe: Readonly<{
+        insert(ids: unknown): Promise<boolean[]>;
+        has(ids: unknown): Promise<boolean[]>;
+    }>;
+};
 export type RuntimeModule = Pick<CodeModule, 'imports' | 'source'>;
 /** Snapshot a Task result before JSON transport can discard or coerce invalid values. */
 export declare function snapshotRuntimeResult(value: unknown): JsonValue | undefined;