@oomol-lab/open-flow 0.1.0-beta.73 → 0.1.0-beta.74

package/dist/common/poll-trigger.d.ts

@@ -1,6 +1,6 @@
 export { resolveTriggerConfig, triggerConfigValues } from './trigger-config.js';
 import type { ConnectorProxy } from './connector-proxy.js';
-import type { JsonValue, TriggerKeySnapshot, TriggerSchedule } from '../browser/flow-change.js';
+import type { JsonValue, TriggerKeySnapshot, TriggerSchedule } from './flow-change.js';
 import type { TriggerConfigOption, TriggerConfigOptionsContext } from './trigger-config-options.js';
 export declare const maximumPollCheckpointBytes: number;
 export declare const maximumPollDedupeKeyBytes = 1024;

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

@@ -1,4 +1,4 @@
-import type { JsonValue } from '../browser/flow-change.js';
+import type { JsonValue } from './flow-change.js';
 export type ResultCall = {
     readonly id: string;
     readonly kind: 'connector';
@@ -7,6 +7,10 @@ export type ResultCall = {
 } | {
     readonly id: string;
     readonly kind: 'code';
+} | {
+    readonly id: string;
+    readonly kind: 'workflow';
+    readonly flowId: string;
 };
 export interface ResultInfo {
     readonly resultId: string;
@@ -17,6 +21,9 @@ export interface ResultInfo {
         readonly action: string;
     } | {
         readonly kind: 'code';
+    } | {
+        readonly kind: 'workflow';
+        readonly flowId: string;
     };
     readonly bytes: number;
     readonly digest: string;

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

@@ -1,4 +1,4 @@
-import type { CodeModule, ConnectorCapability, JsonValue } from '../browser/flow-change.js';
+import type { CodeModule, ConnectorCapability, TaskCapability, JsonValue } from './flow-change.js';
 export { currentEngineContract, nodejsEngineContract, findEngineContract, type EngineContract } from './engine-contract.js';
 export type RuntimeModule = Pick<CodeModule, 'imports' | 'source'>;
 /** Snapshot a Task result before JSON transport can discard or coerce invalid values. */
@@ -11,6 +11,8 @@ export interface RuntimeProgram {
     readonly modules: Readonly<Record<string, RuntimeModule>>;
 }
 export interface RuntimeCapabilityCall {
+    readonly nodeId?: string;
+    readonly jobId?: string;
     readonly callId: string;
     readonly invocationId: string;
     readonly kind: string;
@@ -65,7 +67,7 @@ export interface AgentInvocation {
     };
 }
 export interface RuntimeInvocation {
-    readonly capabilities?: readonly ConnectorCapability[];
+    readonly capabilities?: readonly TaskCapability[];
     readonly capability: (call: RuntimeCapabilityCall) => Promise<RuntimeCapabilityResponse>;
     readonly input: JsonValue;
     readonly invocationId: string;
@@ -95,3 +97,7 @@ export interface DecisionTaskInvocation {
     readonly version: 1;
 }
 export type InvokeDecisionTask = (invocation: DecisionTaskInvocation) => Promise<LlmTaskResult>;
+/** Serialized into the sandbox alongside the strict JSON snapshot helper. */
+export declare function createWorkflows(invoke: (payload: JsonValue) => Promise<RuntimeCapabilityResponse>): Readonly<{
+    call(name: string, input?: Readonly<Record<string, JsonValue>>): Promise<JsonValue>;
+}>;

package/dist/common/runtime-contract.js

@@ -23,9 +23,10 @@ function dequal(foo, bar) {
 }
 //#endregion
 //#region src/execution/common/engineContract.ts
-var currentEngineContract = "open-flow-engine/v7";
-var nodejsEngineContract = "open-flow-engine/v7/nodejs-compat-v1";
+var currentEngineContract = "open-flow-engine/v8";
+var nodejsEngineContract = "open-flow-engine/v8/nodejs-compat-v1";
 var currentContract = {
+	workflowTools: true,
 	waitAutoContinue: true,
 	webhookResponses: true,
 	platformExports: /* @__PURE__ */ new Set(["engineContract", "identity"]),
@@ -67,10 +68,16 @@ export function identity(value) { return value }
 `
 };
 function findEngineContract(contract) {
-	if (contract == "open-flow-engine/v7") return currentContract;
-	if (contract == "open-flow-engine/v7/nodejs-compat-v1") return nodejsContract;
+	if (contract == "open-flow-engine/v8") return currentContract;
+	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,
+		workflowTools: false,
+		platformSource: `export const engineContract = ${JSON.stringify(contract)}\nexport function identity(value) { return value }\n`
+	};
 	if (contract == "open-flow-engine/v6" || contract == "open-flow-engine/v6/nodejs-compat-v1") return {
 		...contract == "open-flow-engine/v6" ? currentContract : nodejsContract,
+		workflowTools: false,
 		waitAutoContinue: false,
 		webhookResponses: false,
 		platformSource: `export const engineContract = ${JSON.stringify(contract)}
@@ -545,5 +552,15 @@ function resolveAction(declarations, payload) {
 		...connectionId == null ? {} : { connectionId }
 	};
 }
+/** Serialized into the sandbox alongside the strict JSON snapshot helper. */
+function createWorkflows(invoke) {
+	return Object.freeze({ async call(name, input = {}) {
+		if (typeof name != "string" || input == null || typeof input != "object" || Array.isArray(input)) throw Object.assign(/* @__PURE__ */ new Error("Workflow name and input object are required."), { code: "capability.invalid" });
+		return (await invoke({
+			name,
+			input: snapshotRuntimeResult(input)
+		})).body;
+	} });
+}
 //#endregion
-export { createActions, currentEngineContract, findEngineContract, nodejsEngineContract, nodejsRuntimeConformanceCases, resolveAction, runtimeConformanceCases, snapshotRuntimeResult };
+export { createActions, createWorkflows, currentEngineContract, findEngineContract, nodejsEngineContract, nodejsRuntimeConformanceCases, resolveAction, runtimeConformanceCases, snapshotRuntimeResult };

package/dist/common/scheduler-checkpoint.d.ts

@@ -1,4 +1,4 @@
-import type { Graph, JsonValue } from '../browser/flow-change.js';
+import type { Graph, JsonValue } from './flow-change.js';
 import type { DependenciesCheckpoint } from './scheduler-dependencies.js';
 import type { ExecutableNode } from './scheduler-node-execution.js';
 import type { AgentCheckpoint } from './runtime-contract.js';

package/dist/common/scheduler-dependencies.d.ts

@@ -1,4 +1,4 @@
-import type { Graph, JsonValue } from '../browser/flow-change.js';
+import type { Graph, JsonValue } from './flow-change.js';
 import { z } from 'zod';
 export interface DependenciesCheckpoint {
     nextId: number;

package/dist/common/scheduler-node-execution.d.ts

@@ -1,5 +1,5 @@
 import type { AgentConfig } from './flow-agent.js';
-import type { Graph, GraphNode, JsonValue, TriggerNode } from '../browser/flow-change.js';
+import type { Graph, GraphNode, JsonValue, TriggerNode } from './flow-change.js';
 import type { WebhookResponseSnapshot } from './webhook-response.js';
 import type { FlowRunCheckpoint } from './scheduler-checkpoint.js';
 import type { Dependencies } from './scheduler-dependencies.js';

package/dist/common/scheduler.d.ts

@@ -1,4 +1,4 @@
-import type { ConnectorCapability, JsonValue, WaitAction, WaitAutoContinue } from '../browser/flow-change.js';
+import type { TaskCapability, JsonValue, WaitAction, WaitAutoContinue } from './flow-change.js';
 import type { PreparedFlow } from './flow-semantics.js';
 import type { WebhookResponseSnapshot } from './webhook-response.js';
 import type { PreviousNode } from '../index.js';
@@ -132,7 +132,7 @@ interface TaskInvocationBase {
     readonly runId: string;
 }
 export type TaskInvocation = TaskInvocationBase & ({
-    readonly capabilities: readonly ConnectorCapability[];
+    readonly capabilities: readonly TaskCapability[];
     readonly moduleId: string;
     readonly getPrevious: () => readonly PreviousNode[];
 } | {

package/dist/common/scheduler.js

@@ -9672,7 +9672,7 @@ var ports = {
 	inputs: array(union([input, group])),
 	outputs: array(union([port, group]))
 };
-var capability = union([
+var connectorCapabilitySchema = union([
 	strictObject({
 		kind: literal("connector"),
 		action: text,
@@ -9704,6 +9704,15 @@ var capability = union([
 		})).optional()
 	})
 ]);
+var workflowCapabilitySchema = strictObject({
+	kind: literal("workflow"),
+	name: text,
+	flowId: text,
+	revisionId: text,
+	inputs: array(port),
+	outputs: array(port).nullable()
+});
+var capability = union([connectorCapabilitySchema, workflowCapabilitySchema]);
 var inline = object({
 	...ports,
 	name: text,
@@ -9718,6 +9727,20 @@ var agentValue = union([object({
 	input: text
 })]);
 var agentInput$1 = union([agentValue, object({ kind: literal("model") })]);
+var agentToolFields = {
+	id: text,
+	name: text,
+	description: text,
+	approval: boolean(),
+	inputs: array(input.extend({ source: agentInput$1 }))
+};
+var connectorAgentToolSchema = object({
+	...agentToolFields,
+	kind: literal("connector").optional(),
+	action: text,
+	connectionId: actionConnection.optional()
+});
+var workflowAgentToolSchema = workflowCapabilitySchema.extend(agentToolFields);
 var decisionQuestion = discriminatedUnion("type", [
 	strictObject({
 		name: text,
@@ -9786,15 +9809,7 @@ var managedFields = object({
 			model: text,
 			prompt: text,
 			maxRounds: number(),
-			tools: array(object({
-				id: text,
-				name: text,
-				description: text,
-				action: text,
-				connectionId: actionConnection.optional(),
-				approval: boolean(),
-				inputs: array(input.extend({ source: agentInput$1 }))
-			})),
+			tools: array(union([workflowAgentToolSchema, connectorAgentToolSchema])),
 			notification: object({
 				action: text,
 				connectionId: actionConnection.optional(),
@@ -10059,7 +10074,8 @@ object({
 		literal(7),
 		literal(8),
 		literal(9),
-		literal(10)
+		literal(10),
+		literal(11)
 	]),
 	document,
 	modules: record$1(text, module)
@@ -11379,7 +11395,10 @@ function agentApproval(config, checkpoint, inputs) {
 	return {
 		callId: checkpoint.callId,
 		toolId: tool.id,
-		action: tool.action,
+		...tool.kind == "workflow" ? {
+			kind: "workflow",
+			flowId: tool.flowId
+		} : { action: tool.action },
 		...tool.connectionId == null ? {} : { connectionId: tool.connectionId },
 		input: checkpoint.input
 	};

package/dist/common/trigger-catalog.d.ts

@@ -1,4 +1,4 @@
-import type { TriggerKeySnapshot } from '../browser/flow-change.js';
+import type { TriggerKeySnapshot } from './flow-change.js';
 import type { UiLanguage } from './localization.js';
 import type { TriggerKeySummary } from './control-api.js';
 export interface TriggerDisplay {

package/dist/common/trigger-config-options.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectorProxy } from './connector-proxy.js';
-import type { JsonValue } from '../browser/flow-change.js';
+import type { JsonValue } from './flow-change.js';
 export interface TriggerConfigOption {
     readonly value: string;
     readonly label: string;

package/dist/common/trigger-config.d.ts

@@ -1,4 +1,4 @@
-import type { Group, InputPort, InputValues, JsonValue } from '../browser/flow-change.js';
+import type { Group, InputPort, InputValues, JsonValue } from './flow-change.js';
 /** Deployment-bound selections owned by the Trigger configuration contract. */
 export declare function clearTriggerExternalConfig(key: string, config: InputValues): InputValues;
 export declare function triggerConfigValue(input: InputPort, config: InputValues): JsonValue | undefined;

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

@@ -1,5 +1,5 @@
-import type { JsonValue, Port, PortDefinition, TriggerNode } from '../browser/flow-change.js';
-import { webhookMethods, webhookSupportsBody } from '../browser/webhook-method.js';
+import type { JsonValue, Port, PortDefinition, TriggerNode } from './flow-change.js';
+import { webhookMethods, webhookSupportsBody } from './webhook-method.js';
 export { webhookMethods, webhookSupportsBody };
 export declare const errorOutputs: readonly Port[];
 export declare const sampleErrorOutputs: Readonly<Record<string, JsonValue>>;

package/dist/common/trigger-localization.d.ts

@@ -1,5 +1,5 @@
 import type { TriggerDisplay } from './trigger-catalog.js';
-import type { TriggerKeySnapshot } from '../browser/flow-change.js';
+import type { TriggerKeySnapshot } from './flow-change.js';
 import type { UiLanguage } from './localization.js';
 type Translations = Readonly<Record<string, Partial<TriggerDisplay>>>;
 export declare function loadTriggerTranslations(locale: UiLanguage): Promise<Translations>;

package/dist/common/webhook-response.d.ts

@@ -1,4 +1,4 @@
-import type { InputPort, JsonValue, Port, PortDefinition } from '../browser/flow-change.js';
+import type { InputPort, JsonValue, Port, PortDefinition } from './flow-change.js';
 export declare const webhookResponseTimeout: {
     readonly defaultMs: 30000;
     readonly minMs: 1000;

package/dist/common/webhook-trigger.d.ts

@@ -1,4 +1,4 @@
-import type { JsonValue, WebhookBodyField, WebhookMethod, WebhookOptions } from '../browser/flow-change.js';
+import type { JsonValue, WebhookBodyField, WebhookMethod, WebhookOptions } from './flow-change.js';
 export { webhookSupportsBody } from './trigger-contract.js';
 export { webhookResponseAllowsBody, webhookResponseTimeout } from './webhook-response.js';
 export type { WebhookResponseSnapshot } from './webhook-response.js';

package/dist/common/workflow.d.ts

@@ -1,4 +1,4 @@
-import type { TaskNode, ManagedTaskDefinition, Port, JsonValue, RevisionContent } from '../browser/flow-change.js';
+import type { TaskNode, ManagedTaskDefinition, Port, JsonValue, RevisionContent, GraphNode, WorkflowCapability, AgentWorkflowTool } from './flow-change.js';
 import { z } from 'zod';
 export interface WorkflowExecutor {
     readonly kind: 'workflow';
@@ -91,3 +91,19 @@ export declare const workflowReferencesSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type WorkflowReferences = z.infer<typeof workflowReferencesSchema>;
+/** Workflow declarations share discovery across authoring, admission and resource indexing. */
+export declare function nodeWorkflowReferences(node: GraphNode): readonly {
+    readonly target: Omit<WorkflowCapability, 'kind' | 'name'>;
+    readonly path: string;
+    readonly tool?: string;
+}[];
+export declare function workflowCapability(name: string, target: WorkflowContract | WorkflowCandidate): WorkflowCapability;
+export declare function workflowAgentTool(id: string, name: string, target: WorkflowContract | WorkflowCandidate, previous?: AgentWorkflowTool): AgentWorkflowTool;
+export declare function workflowInterfaceIssues(target: {
+    readonly revisionId: string;
+}, contract: WorkflowContract, previous?: PublishedWorkflowInterface): readonly {
+    side: 'revision';
+    field: string;
+    message: string;
+    reason: 'snapshot-missing' | 'interface-required' | 'revision-stale';
+}[];

package/dist/common/workflow.js

@@ -9621,27 +9621,8 @@ function workflowPorts(ports) {
 function workflowCompatibility(node, contract, previous) {
 	const issues = [];
 	if ("executor" in node.task && node.task.executor.kind == "workflow") {
-		const saved = node.task.executor.revisionId;
-		if (!saved) return [{
-			side: "revision",
-			field: "revisionId",
-			reason: "interface-required",
-			message: "The called workflow interface has not been loaded. Refresh the interface definition."
-		}];
-		if (saved != contract.revisionId) {
-			if (previous == null) return [{
-				side: "revision",
-				field: "revisionId",
-				reason: "snapshot-missing",
-				message: "The saved workflow interface snapshot is unavailable. Refresh the interface definition."
-			}];
-			if (!sameWorkflowInterface(previous, contract)) return [{
-				side: "revision",
-				field: "revisionId",
-				reason: "revision-stale",
-				message: "The called workflow interface has changed. Update the interface definition."
-			}];
-		}
+		const interfaceIssues = workflowInterfaceIssues(node.task.executor, contract, previous);
+		if (interfaceIssues.length) return interfaceIssues;
 	}
 	for (const port of contract.inputs) {
 		const source = node.inputs[port.handle];
@@ -9705,5 +9686,70 @@ var workflowReferencesSchema = object({
 		}).nullable()
 	}))
 });
+/** Workflow declarations share discovery across authoring, admission and resource indexing. */
+function nodeWorkflowReferences(node) {
+	if (node.kind != "task") return [];
+	if ("moduleId" in node.task) return (node.task.capabilities ?? []).flatMap((item, index) => item.kind == "workflow" ? [{
+		target: item,
+		path: `task/capabilities/${index}`,
+		tool: item.name
+	}] : []);
+	if (node.task.executor.kind == "workflow") return [{
+		target: {
+			...node.task.executor,
+			inputs: node.task.inputs.filter((port) => "handle" in port),
+			outputs: node.task.outputs.filter((port) => "handle" in port)
+		},
+		path: "task/executor"
+	}];
+	if (node.task.executor.kind == "agent") return node.task.executor.tools.flatMap((item, index) => item.kind == "workflow" ? [{
+		target: item,
+		path: `task/executor/tools/${index}`,
+		tool: item.name
+	}] : []);
+	return [];
+}
+function workflowCapability(name, target) {
+	return {
+		kind: "workflow",
+		name,
+		flowId: target.flowId,
+		revisionId: "inputs" in target ? target.revisionId : "",
+		inputs: "inputs" in target ? target.inputs : [],
+		outputs: "inputs" in target ? target.outputs : null
+	};
+}
+function workflowAgentTool(id, name, target, previous) {
+	const capability = workflowCapability(name, target);
+	return {
+		...capability,
+		id,
+		description: previous?.description ?? target.name,
+		approval: previous?.approval ?? false,
+		inputs: capability.inputs.map((port) => Object.assign({}, port, { source: previous?.inputs.find((old) => old.handle == port.handle)?.source ?? { kind: "model" } }))
+	};
+}
+function workflowInterfaceIssues(target, contract, previous) {
+	if (!target.revisionId) return [{
+		side: "revision",
+		field: "revisionId",
+		reason: "interface-required",
+		message: "The called workflow interface has not been loaded. Refresh the interface definition."
+	}];
+	if (target.revisionId == contract.revisionId) return [];
+	if (previous == null) return [{
+		side: "revision",
+		field: "revisionId",
+		reason: "snapshot-missing",
+		message: "The saved workflow interface snapshot is unavailable. Refresh the interface definition."
+	}];
+	if (!sameWorkflowInterface(previous, contract)) return [{
+		side: "revision",
+		field: "revisionId",
+		reason: "revision-stale",
+		message: "The called workflow interface has changed. Update the interface definition."
+	}];
+	return [];
+}
 //#endregion
-export { publishedWorkflowInterface, publishedWorkflowInterfaceSchema, sameWorkflowInterface, withWorkflowTask, workflowCandidate, workflowCandidateGroup, workflowCompatibility, workflowContractSchema, workflowPorts, workflowReferencesSchema, workflowSelectionTask, workflowTask };
+export { nodeWorkflowReferences, publishedWorkflowInterface, publishedWorkflowInterfaceSchema, sameWorkflowInterface, withWorkflowTask, workflowAgentTool, workflowCandidate, workflowCandidateGroup, workflowCapability, workflowCompatibility, workflowContractSchema, workflowInterfaceIssues, workflowPorts, workflowReferencesSchema, workflowSelectionTask, workflowTask };

package/dist/index.d.ts

@@ -66,7 +66,10 @@ export interface TaskLogger {
     warn(message: string, data?: unknown): void;
     error(message: string, data?: unknown): void;
 }
-export interface TaskContext<Actions extends object = Record<string, never>> {
+export interface TaskContext<Actions extends object = Record<string, never>, Workflows extends object = {
+    call: (name: never, input?: never) => Promise<never>;
+}> {
+    readonly workflows: Workflows;
     readonly actions: Actions;
     readonly signal: AbortSignal;
     readonly flowId: string;
@@ -82,6 +85,6 @@ export interface TaskContext<Actions extends object = Record<string, never>> {
     reportProgress(progress: number): Promise<void>;
 }
 export type TaskResult<Outputs extends object> = keyof Outputs extends never ? Outputs | void : Outputs;
-export interface Task<Inputs extends object = Record<string, unknown>, Outputs extends object = Record<string, unknown>, Actions extends object = Record<string, never>> {
-    (inputs: Inputs, context: TaskContext<Actions>): TaskResult<Outputs> | Promise<TaskResult<Outputs>>;
+export interface Task<Inputs extends object = Record<string, unknown>, Outputs extends object = Record<string, unknown>, Actions extends object = Record<string, never>, Workflows extends object = TaskContext['workflows']> {
+    (inputs: Inputs, context: TaskContext<Actions, Workflows>): TaskResult<Outputs> | Promise<TaskResult<Outputs>>;
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@oomol-lab/open-flow",
-  "version": "0.1.0-beta.73",
+  "version": "0.1.0-beta.74",
   "description": "TypeScript contracts and Browser runtime for Open Flow.",
-  "license": "Apache-2.0",
+  "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oomol-lab/open-flow.git",
@@ -82,12 +82,12 @@
       "import": "./dist/common/provider-triggers.js"
     },
     "./flow-authoring": {
-      "types": "./dist/browser/flow-authoring.d.ts",
-      "import": "./dist/browser/flow-authoring.js"
+      "types": "./dist/common/flow-authoring.d.ts",
+      "import": "./dist/common/flow-authoring.js"
     },
     "./flow-change": {
-      "types": "./dist/browser/flow-change.d.ts",
-      "import": "./dist/browser/flow-change.js"
+      "types": "./dist/common/flow-change.d.ts",
+      "import": "./dist/common/flow-change.js"
     },
     "./flow-encoding": {
       "types": "./dist/common/flow-encoding.d.ts",
@@ -152,6 +152,7 @@
   },
   "files": [
     "dist",
+    "src",
     "skills",
     "README.md",
     "NOTICE",

package/src/base/common/json.ts

@@ -0,0 +1,90 @@
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | JsonObject
+
+export type JsonObject = { readonly [key: string]: JsonValue }
+
+type Frame = {
+  readonly value: object
+  readonly keys: readonly (string | symbol)[]
+  readonly arrayLength: number | undefined
+  index: number
+}
+
+function hasJsonShape(root: unknown): boolean {
+  if (root === null || typeof root == 'boolean' || typeof root == 'string') return true
+  if (typeof root == 'number') return Number.isFinite(root)
+  if (typeof root != 'object') return false
+
+  const ancestors = new Set<object>()
+  const pending: Frame[] = []
+  let value = root
+
+  traversal: while (true) {
+    let keys: readonly (string | symbol)[]
+    let arrayLength: number | undefined
+    if (Array.isArray(value)) {
+      arrayLength = value.length
+      keys = Reflect.ownKeys(value)
+      if (keys.length != arrayLength + 1) return false
+    } else {
+      const prototype = Reflect.getPrototypeOf(value)
+      if (prototype != Object.prototype && prototype != null) return false
+      keys = Reflect.ownKeys(value)
+      arrayLength = undefined
+    }
+    ancestors.add(value)
+
+    let index = 0
+    while (true) {
+      if (index >= keys.length) {
+        ancestors.delete(value)
+        const parent = pending.pop()
+        if (parent === undefined) return true
+        value = parent.value
+        keys = parent.keys
+        arrayLength = parent.arrayLength
+        index = parent.index
+        continue
+      }
+
+      const key = keys[index++]!
+      if (arrayLength !== undefined) {
+        if (key == 'length') continue
+        if (typeof key != 'string') return false
+        const arrayIndex = Number(key)
+        if (!Number.isSafeInteger(arrayIndex) || arrayIndex < 0 || arrayIndex >= arrayLength || String(arrayIndex) != key) return false
+      } else if (typeof key != 'string') {
+        return false
+      }
+
+      const descriptor = Reflect.getOwnPropertyDescriptor(value, key)
+      if (descriptor?.enumerable != true || !Object.hasOwn(descriptor, 'value')) return false
+      const child: unknown = descriptor.value
+      if (child === null || typeof child == 'boolean' || typeof child == 'string') continue
+      if (typeof child == 'number') {
+        if (!Number.isFinite(child)) return false
+        continue
+      }
+      if (typeof child != 'object' || ancestors.has(child)) return false
+
+      pending.push({ value, keys, arrayLength, index })
+      value = child
+      continue traversal
+    }
+  }
+}
+
+export function isJsonValue(value: unknown): value is JsonValue {
+  try {
+    return hasJsonShape(value)
+  } catch {
+    return false
+  }
+}
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  try {
+    return value != null && typeof value == 'object' && !Array.isArray(value) && hasJsonShape(value)
+  } catch {
+    return false
+  }
+}

package/src/canvas/common/commands.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+
+export const canvasMinZoom = 0.1
+export const canvasMaxZoom = 3
+
+/** Transient operations on each connected canvas's own viewport. */
+export const canvasCommandSchema = z.discriminatedUnion('type', [
+  z.strictObject({ type: z.literal('focus'), nodeId: z.string().min(1) }),
+  z.strictObject({ type: z.literal('zoom'), zoom: z.number().min(canvasMinZoom).max(canvasMaxZoom) }),
+  z.strictObject({ type: z.literal('pan'), dx: z.number(), dy: z.number() }),
+  z.strictObject({ type: z.literal('fit') }),
+])
+
+export type CanvasCommand = z.infer<typeof canvasCommandSchema>
+export type CanvasCommandSubscriber = (execute: (command: CanvasCommand) => void) => () => void