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

package/dist/common/flow-state.js

@@ -5603,6 +5603,30 @@ function dequal(foo, bar) {
 //#endregion
 //#region src/state/common/conformance.ts
 var stateConformanceCases = [
+	{
+		name: "reads selected State keys in input order with missing, falsy and independent values",
+		async verify(harness) {
+			if (!dequal(await harness.run(`export default async (_, context) => {
+        await context.state.set('object', { nested: [1] });
+        await context.state.set('zero', 0);
+        await context.state.set('false', false);
+        await context.state.set('empty', '');
+        const values = await context.state.get(['false', 'missing', 'object', 'zero', 'empty']);
+        values[2].nested.push(2);
+        return {result: {values, retained: await context.state.get('object'), zero: await context.state.get('zero')}};
+      }`), {
+				values: [
+					false,
+					null,
+					{ nested: [1, 2] },
+					0,
+					""
+				],
+				retained: { nested: [1] },
+				zero: 0
+			})) throw new Error("State batch reads must preserve order, missing keys and independent JSON values.");
+		}
+	},
 	{
 		name: "skips composite identities across successful Runs without depending on field order",
 		async verify(harness) {
@@ -5700,13 +5724,22 @@ var stateConformanceCases = [
 ];
 //#endregion
 //#region src/state/common/state.ts
+var stateReadLimits = {
+	maxKeys: 16,
+	maxBytes: 1048576
+};
+var keySchema = string().min(1).refine((value) => new TextEncoder().encode(value).length <= 256);
 var stateQuerySchema = strictObject({
 	scope: _enum(["draft", "live"]),
-	values: boolean().optional()
+	values: literal(false).optional()
+});
+var stateReadSchema = strictObject({
+	scope: _enum(["draft", "live"]),
+	keys: array(keySchema).min(1).max(stateReadLimits.maxKeys).refine((keys) => new Set(keys).size === keys.length, "State keys must be distinct.")
 });
 var stateClearSchema = strictObject({
 	scope: _enum(["draft", "live"]),
-	key: string().min(1).refine((key) => new TextEncoder().encode(key).length <= 256).optional()
+	key: keySchema.optional()
 });
 var dedupeClearSchema = strictObject({
 	scope: _enum(["draft", "live"]),
@@ -5776,11 +5809,10 @@ var flowStateViewSchema = object({
 		maxIdentities: number().positive(),
 		maxRunWrites: number().positive()
 	}),
-	values: array(object({
+	values: array(strictObject({
 		key: string(),
 		size: number().nonnegative(),
-		updatedAt: number(),
-		value: json().optional()
+		updatedAt: number()
 	})),
 	spaces: array(object({
 		space: string(),
@@ -5790,5 +5822,16 @@ var flowStateViewSchema = object({
 		updatedAt: number()
 	}))
 });
+var flowStateValuesSchema = object({
+	version: literal(1),
+	scope: _enum(["draft", "live"]),
+	values: array(strictObject({
+		key: keySchema,
+		value: json()
+	})).min(1).max(stateReadLimits.maxKeys)
+}).refine((response) => {
+	const encoder = new TextEncoder();
+	return response.values.reduce((bytes, item) => bytes + (item.value === null ? 0 : encoder.encode(JSON.stringify(item.value)).byteLength), 0) <= stateReadLimits.maxBytes;
+}, "State values exceed the 1 MiB read limit.");
 //#endregion
-export { StateError, dedupeClearSchema, dedupeIdentities, flowStateViewSchema, hashIdentities, skipDuplicatesConfigSchema, skipDuplicatesExecutorSchema, skipDuplicatesIdentities, skipDuplicatesTask, stateClearSchema, stateConformanceCases, stateKey, stateQuerySchema };
+export { StateError, dedupeClearSchema, dedupeIdentities, flowStateValuesSchema, flowStateViewSchema, hashIdentities, skipDuplicatesConfigSchema, skipDuplicatesExecutorSchema, skipDuplicatesIdentities, skipDuplicatesTask, stateClearSchema, stateConformanceCases, stateKey, stateQuerySchema, stateReadLimits, stateReadSchema };

package/dist/common/mcp.d.ts

@@ -22,7 +22,38 @@ export declare const mcpTools: {
                 validate(value: unknown): {
                     value: {
                         scope: "draft" | "live";
-                        values?: boolean | undefined;
+                        values?: false | undefined;
+                        flowId: string;
+                    };
+                } | {
+                    issues: {
+                        message: string;
+                        path: string[];
+                    }[];
+                };
+            };
+        };
+    };
+    flow_state_read: {
+        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";
+                        keys: string[];
                         flowId: string;
                     };
                 } | {

package/dist/common/mcp.js

@@ -8848,13 +8848,22 @@ var httpRequestConfigSchema = strictObject({
 var httpRequestExecutorSchema = httpRequestConfigSchema.extend({ kind: literal("http-request") });
 //#endregion
 //#region src/state/common/state.ts
+var stateReadLimits = {
+	maxKeys: 16,
+	maxBytes: 1048576
+};
+var keySchema = string$1().min(1).refine((value) => new TextEncoder().encode(value).length <= 256);
 var stateQuerySchema = strictObject({
 	scope: _enum(["draft", "live"]),
-	values: boolean().optional()
+	values: literal(false).optional()
+});
+var stateReadSchema = strictObject({
+	scope: _enum(["draft", "live"]),
+	keys: array(keySchema).min(1).max(stateReadLimits.maxKeys).refine((keys) => new Set(keys).size === keys.length, "State keys must be distinct.")
 });
 var stateClearSchema = strictObject({
 	scope: _enum(["draft", "live"]),
-	key: string$1().min(1).refine((key) => new TextEncoder().encode(key).length <= 256).optional()
+	key: keySchema.optional()
 });
 var dedupeClearSchema = strictObject({
 	scope: _enum(["draft", "live"]),
@@ -8872,11 +8881,10 @@ var flowStateViewSchema = object({
 		maxIdentities: number().positive(),
 		maxRunWrites: number().positive()
 	}),
-	values: array(object({
+	values: array(strictObject({
 		key: string$1(),
 		size: number().nonnegative(),
-		updatedAt: number(),
-		value: json$4().optional()
+		updatedAt: number()
 	})),
 	spaces: array(object({
 		space: string$1(),
@@ -8886,6 +8894,17 @@ var flowStateViewSchema = object({
 		updatedAt: number()
 	}))
 });
+var flowStateValuesSchema = object({
+	version: literal(1),
+	scope: _enum(["draft", "live"]),
+	values: array(strictObject({
+		key: keySchema,
+		value: json$4()
+	})).min(1).max(stateReadLimits.maxKeys)
+}).refine((response) => {
+	const encoder = new TextEncoder();
+	return response.values.reduce((bytes, item) => bytes + (item.value === null ? 0 : encoder.encode(JSON.stringify(item.value)).byteLength), 0) <= stateReadLimits.maxBytes;
+}, "State values exceed the 1 MiB read limit.");
 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);
@@ -12362,10 +12381,22 @@ var ControlClient = class {
 			})
 		}));
 	}
-	async getFlowState(flowId, scope, values = false) {
-		const result = flowStateViewSchema.safeParse(await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}&values=${values}`));
+	async getFlowState(flowId, scope) {
+		const result = flowStateViewSchema.safeParse(await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}`));
 		return result.success && result.data.scope === scope ? result.data : invalidResponse();
 	}
+	async getFlowStateValues(flowId, scope, keys, signal) {
+		const result = flowStateValuesSchema.safeParse(await this.request(`/v1/flows/${segment(flowId)}/state/read`, {
+			method: "POST",
+			body: JSON.stringify({
+				version: 1,
+				scope,
+				keys
+			}),
+			signal
+		}));
+		return result.success && result.data.scope === scope && result.data.values.length === keys.length && result.data.values.every((item, index) => item.key === keys[index]) ? 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();
@@ -13128,7 +13159,8 @@ 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: tool("Inspect Flow state usage, business key metadata and deduplication spaces. Never returns values. Scope is required.", stateQuerySchema.extend({ flowId: flow }), true),
+	flow_state_read: tool("Read values for 1–16 distinct named State keys in one explicit scope. Values are returned in request order; missing keys return null. The combined stored JSON limit is 1 MiB; oversized reads fail without partial results.", stateReadSchema.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({

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

@@ -3,7 +3,10 @@ export { currentEngineContract, nodejsEngineContract, findEngineContract, type E
 /** 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>;
+        get: {
+            (key: string): Promise<JsonValue>;
+            (keys: readonly string[]): Promise<JsonValue[]>;
+        };
         set(key: unknown, value: unknown): Promise<void>;
         insert(key: unknown, value: unknown): Promise<boolean>;
         delete(key: unknown): Promise<void>;

package/dist/common/runtime-contract.js

@@ -120,11 +120,18 @@ function createState(invoke) {
 		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;
 	};
+	async function get(key) {
+		if (Array.isArray(key)) {
+			if (key.length === 0 || key.length > 16) throw invalid("State reads require 1 to 16 keys.");
+			const keys = Array.from(key, keyOf);
+			if (new Set(keys).size !== keys.length) throw invalid("State keys must be distinct.");
+			return (await invoke("state.get", { key: keys })).body.values;
+		}
+		return (await invoke("state.get", { key: keyOf(key) })).body.value;
+	}
 	return {
 		state: Object.freeze({
-			async get(key) {
-				return (await invoke("state.get", { key: keyOf(key) })).body.value;
-			},
+			get,
 			async set(key, value) {
 				await invoke("state.set", {
 					key: keyOf(key),
@@ -454,6 +461,46 @@ async function rejects(operation, pattern, message) {
 	throw new Error(`${message}: operation unexpectedly succeeded.`);
 }
 var runtimeConformanceCases = [
+	{
+		name: "reads multiple State keys in one Host call while preserving input order",
+		async verify(harness) {
+			const calls = [];
+			equal(await harness.invoke({
+				input: null,
+				invocationId: "state-batch-read",
+				capability: async ({ kind, payload }) => {
+					calls.push({
+						kind,
+						payload
+					});
+					return {
+						status: 200,
+						body: { values: [
+							0,
+							null,
+							false,
+							""
+						] }
+					};
+				},
+				program: program(harness, `export default async (_, context) => context.state.get(['zero', 'missing', 'false', 'empty'])`)
+			}), [
+				0,
+				null,
+				false,
+				""
+			], "State batch values");
+			equal(calls, [{
+				kind: "state.get",
+				payload: { key: [
+					"zero",
+					"missing",
+					"false",
+					"empty"
+				] }
+			}], "State batch dispatch");
+		}
+	},
 	{
 		name: "cancels detached State work when its Task finishes",
 		async verify(harness) {
@@ -498,12 +545,20 @@ var runtimeConformanceCases = [
           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))]) {
+          for (const call of [
+            () => context.state.get(''), () => context.state.get('x'.repeat(257)),
+            () => context.state.get([]), () => context.state.get(['x', 'x']),
+            () => context.state.get(Array.from({length: 17}, (_, index) => String(index))),
+            () => context.state.get(['']), () => context.state.get(['汉'.repeat(86)]),
+            () => context.state.get(new Array(1)), () => context.state.get(null), () => context.state.get(),
+            () => 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");
+			}), Array.from({ length: 22 }, () => "capability.invalid"), "State boundary validation");
 			equal(calls, 0, "State invalid dispatch");
 		}
 	},

package/dist/common/scheduler.js

@@ -9535,13 +9535,24 @@ var httpRequestExecutorSchema = strictObject({
 	]).default("auto"),
 	statusPolicy: _enum(["success", "all"]).default("success")
 }).extend({ kind: literal("http-request") });
+//#endregion
+//#region src/state/common/state.ts
+var stateReadLimits = {
+	maxKeys: 16,
+	maxBytes: 1048576
+};
+var keySchema = string$1().min(1).refine((value) => new TextEncoder().encode(value).length <= 256);
+strictObject({
+	scope: _enum(["draft", "live"]),
+	values: literal(false).optional()
+});
 strictObject({
 	scope: _enum(["draft", "live"]),
-	values: boolean().optional()
+	keys: array(keySchema).min(1).max(stateReadLimits.maxKeys).refine((keys) => new Set(keys).size === keys.length, "State keys must be distinct.")
 });
 strictObject({
 	scope: _enum(["draft", "live"]),
-	key: string$1().min(1).refine((key) => new TextEncoder().encode(key).length <= 256).optional()
+	key: keySchema.optional()
 });
 strictObject({
 	scope: _enum(["draft", "live"]),
@@ -9558,11 +9569,10 @@ object({
 		maxIdentities: number().positive(),
 		maxRunWrites: number().positive()
 	}),
-	values: array(object({
+	values: array(strictObject({
 		key: string$1(),
 		size: number().nonnegative(),
-		updatedAt: number(),
-		value: json$1().optional()
+		updatedAt: number()
 	})),
 	spaces: array(object({
 		space: string$1(),
@@ -9572,6 +9582,17 @@ object({
 		updatedAt: number()
 	}))
 });
+object({
+	version: literal(1),
+	scope: _enum(["draft", "live"]),
+	values: array(strictObject({
+		key: keySchema,
+		value: json$1()
+	})).min(1).max(stateReadLimits.maxKeys)
+}).refine((response) => {
+	const encoder = new TextEncoder();
+	return response.values.reduce((bytes, item) => bytes + (item.value === null ? 0 : encoder.encode(JSON.stringify(item.value)).byteLength), 0) <= stateReadLimits.maxBytes;
+}, "State values exceed the 1 MiB read limit.");
 //#endregion
 //#region src/flow/common/retry.ts
 var retryNodeTypes = [

package/dist/index.d.ts

@@ -104,6 +104,7 @@ export interface TaskContext<Actions extends object = Record<string, never>, Wor
     readonly blockId: string;
     readonly state: {
         get(key: string): Promise<JsonValue | null>;
+        get(keys: readonly string[]): Promise<(JsonValue | null)[]>;
         set(key: string, value: JsonValue): Promise<void>;
         insert(key: string, value: Exclude<JsonValue, null>): Promise<boolean>;
         delete(key: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-flow",
-  "version": "0.1.0-beta.78",
+  "version": "0.1.0-beta.79",
   "description": "TypeScript contracts and Browser runtime for Open Flow.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

package/src/control/common/api.ts

@@ -1,8 +1,8 @@
 import type { CanvasCommand } from '../../canvas/common/commands.ts'
-import type { FlowStateView, StateScope } from '../../state/common/state.ts'
+import type { FlowStateValues, FlowStateView, StateScope } from '../../state/common/state.ts'
 
 import { currentEngineContract } from '../../runtime/common/engineContract.ts'
-import { flowStateViewSchema } from '../../state/common/state.ts'
+import { flowStateValuesSchema, flowStateViewSchema } from '../../state/common/state.ts'
 import { workflowContractSchema, workflowReferencesSchema } from '../../workflow/common/workflow.ts'
 export type { CanvasCommand, CanvasCommandSubscriber } from '../../canvas/common/commands.ts'
 import type { LiveDetails } from './liveDetails.ts'
@@ -1017,11 +1017,23 @@ export class ControlClient {
     return flow(await this.request(`/v1/flows/${segment(flowId)}`, { method: 'PATCH', body: JSON.stringify({ ...changes, version: 1 }) }))
   }
 
-  async getFlowState(flowId: string, scope: StateScope, values = false): Promise<FlowStateView> {
-    const result = flowStateViewSchema.safeParse(await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}&values=${values}`))
+  async getFlowState(flowId: string, scope: StateScope): Promise<FlowStateView> {
+    const result = flowStateViewSchema.safeParse(await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}`))
     return result.success && result.data.scope === scope ? result.data : invalidResponse()
   }
 
+  async getFlowStateValues(flowId: string, scope: StateScope, keys: readonly string[], signal?: AbortSignal): Promise<FlowStateValues> {
+    const result = flowStateValuesSchema.safeParse(
+      await this.request(`/v1/flows/${segment(flowId)}/state/read`, { method: 'POST', body: JSON.stringify({ version: 1, scope, keys }), signal }),
+    )
+    return result.success &&
+      result.data.scope === scope &&
+      result.data.values.length === keys.length &&
+      result.data.values.every((item, index) => item.key === keys[index])
+      ? result.data
+      : invalidResponse()
+  }
+
   async clearFlowState(flowId: string, scope: StateScope, key?: string): Promise<void> {
     const source = record(
       await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}${key == null ? '' : `&key=${encodeURIComponent(key)}`}`, { method: 'DELETE' }),

package/src/control/common/conformance.ts

@@ -205,6 +205,37 @@ function liveRunRequest(harness: ControlApiConformanceHarness, publicationId: st
 }
 
 export const controlApiConformanceCases: readonly ControlApiConformanceCase[] = [
+  {
+    name: 'reads State metadata and bounded explicit keys without scope-wide value retrieval',
+    async verify(harness) {
+      const api = new ControlClient((url, init) => harness.request(new Request(new URL(url, harness.origin), init)))
+      const flow = await api.createFlow('State reads')
+      equal((await api.getFlowState(flow.flowId, 'draft')).values, [], 'New Flow State metadata')
+      equal(
+        await api.getFlowStateValues(flow.flowId, 'live', ['second', 'first']),
+        {
+          version: 1,
+          scope: 'live',
+          values: [
+            { key: 'second', value: null },
+            { key: 'first', value: null },
+          ],
+        },
+        'Missing named State keys',
+      )
+      const metadata = await request(harness, `/v1/flows/${flow.flowId}/state?scope=draft&values=false`)
+      await json(metadata, 200, 'Legacy metadata-only query')
+      equal(metadata.headers.get('cache-control'), 'no-store', 'State metadata cache policy')
+      await error(await request(harness, `/v1/flows/${flow.flowId}/state?scope=draft&values=true`), 400, 'flow.invalid', 'Scope-wide State values')
+      for (const input of [{ scope: 'draft', keys: [] }, { keys: ['key'] }, { scope: 'draft', keys: Array.from({ length: 17 }, (_, index) => String(index)) }])
+        await error(
+          await request(harness, `/v1/flows/${flow.flowId}/state/read`, { method: 'POST', body: JSON.stringify({ version: 1, ...input }) }),
+          400,
+          'flow.invalid',
+          'Invalid named State read',
+        )
+    },
+  },
   {
     name: 'imports workflow files atomically and exports a new unpublished draft with its Presentation',
     async verify(harness) {

package/src/control/common/mcp.ts

@@ -5,7 +5,7 @@ import { canvasCommandSchema } from '../../canvas/common/commands.ts'
 import { runStatuses } from '../../execution/common/runLifecycle.ts'
 import { waitCommentSchema } from '../../execution/common/wait.ts'
 import { resourceNameIssue } from '../../flow/common/change.ts'
-import { stateQuerySchema, stateClearSchema, dedupeClearSchema } from '../../state/common/state.ts'
+import { stateQuerySchema, stateReadSchema, stateClearSchema, dedupeClearSchema } from '../../state/common/state.ts'
 import { authoringReadSchema, authoringSearchSchema, authoringRequestSchema, authoringSchemaQuery } from './authoringSchema.ts'
 import { resultQuerySchema } from './resultQuery.ts'
 
@@ -52,10 +52,15 @@ function tool<Args>(description: string, schema: z.ZodType<Args>, readOnly: bool
 
 export const mcpTools = {
   flow_state: tool(
-    'Inspect Flow state usage, business keys and deduplication spaces. Values are omitted unless requested. Scope is required.',
+    'Inspect Flow state usage, business key metadata and deduplication spaces. Never returns values. Scope is required.',
     stateQuerySchema.extend({ flowId: flow }),
     true,
   ),
+  flow_state_read: tool(
+    'Read values for 1–16 distinct named State keys in one explicit scope. Values are returned in request order; missing keys return null. The combined stored JSON limit is 1 MiB; oversized reads fail without partial results.',
+    stateReadSchema.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 }),

package/src/control/common/requests.ts

@@ -10,6 +10,7 @@ import { decodeDraftOperations, draftOperationsSchema } from './draftOperations.
 export { decodeDraftOperations, draftOperationsSchema, resolveDraftOperations, type DraftOperation } from './draftOperations.ts'
 import { z } from 'zod'
 import { resourceNameIssue } from '../../flow/common/change.ts'
+import { stateReadSchema } from '../../state/common/state.ts'
 import { createEventSourceSchema, updateEventSourceSchema, eventSourceRevisionSchema } from './eventSourceSchemas.ts'
 
 export const waitActionBodySchema: { parse(value: unknown): { comment?: string | null } } = z.strictObject({ comment: waitCommentSchema })
@@ -23,6 +24,7 @@ const tagName = id.transform((name) => name.trim()).refine((name) => resourceNam
 const inputs = z.record(z.string(), z.record(z.string(), json))
 const trigger = z.strictObject({ nodeId: id, outputs: z.record(z.string(), json) })
 const schemas = {
+  readFlowState: stateReadSchema.extend({ version }),
   canvas: z.strictObject({ command: canvasCommandSchema, version }),
   authoringCheck: authoringCheckSchema,
   authoringEdit: authoringRequestSchema,
@@ -78,6 +80,7 @@ function decoder<Value>(schema: z.ZodType<Value>): (value: unknown) => Value {
 }
 
 export const controlRequests = {
+  readFlowState: decoder(schemas.readFlowState),
   canvas: decoder(schemas.canvas),
   authoringCheck: decoder(schemas.authoringCheck),
   authoringEdit: decoder(schemas.authoringEdit),

package/src/runtime/common/runtime.ts

@@ -27,11 +27,20 @@ export function createState(invoke: (kind: string, payload: JsonValue) => Promis
       throw invalid('Identities must be strings or finite numbers.')
     return ids
   }
+  function get(key: string): Promise<JsonValue>
+  function get(keys: readonly string[]): Promise<JsonValue[]>
+  async function get(key: unknown) {
+    if (Array.isArray(key)) {
+      if (key.length === 0 || key.length > 16) throw invalid('State reads require 1 to 16 keys.')
+      const keys = Array.from(key, keyOf)
+      if (new Set(keys).size !== keys.length) throw invalid('State keys must be distinct.')
+      return ((await invoke('state.get', { key: keys })).body as { values: JsonValue[] }).values
+    }
+    return ((await invoke('state.get', { key: keyOf(key) })).body as { value: JsonValue }).value
+  }
   return {
     state: Object.freeze({
-      async get(key: unknown) {
-        return ((await invoke('state.get', { key: keyOf(key) })).body as { value: JsonValue }).value
-      },
+      get,
       async set(key: unknown, value: unknown) {
         await invoke('state.set', { key: keyOf(key), value: valueOf(value) })
       },
@@ -443,6 +452,23 @@ async function rejects(operation: Promise<unknown>, pattern: RegExp, message: st
 }
 
 export const runtimeConformanceCases: readonly RuntimeConformanceCase[] = [
+  {
+    name: 'reads multiple State keys in one Host call while preserving input order',
+    async verify(harness) {
+      const calls: { kind: string; payload: JsonValue }[] = []
+      const result = await harness.invoke({
+        input: null,
+        invocationId: 'state-batch-read',
+        capability: async ({ kind, payload }) => {
+          calls.push({ kind, payload })
+          return { status: 200, body: { values: [0, null, false, ''] } }
+        },
+        program: program(harness, `export default async (_, context) => context.state.get(['zero', 'missing', 'false', 'empty'])`),
+      })
+      equal(result, [0, null, false, ''], 'State batch values')
+      equal(calls, [{ kind: 'state.get', payload: { key: ['zero', 'missing', 'false', 'empty'] } }], 'State batch dispatch')
+    },
+  },
   {
     name: 'cancels detached State work when its Task finishes',
     async verify(harness) {
@@ -492,7 +518,15 @@ export const runtimeConformanceCases: readonly RuntimeConformanceCase[] = [
           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))]) {
+          for (const call of [
+            () => context.state.get(''), () => context.state.get('x'.repeat(257)),
+            () => context.state.get([]), () => context.state.get(['x', 'x']),
+            () => context.state.get(Array.from({length: 17}, (_, index) => String(index))),
+            () => context.state.get(['']), () => context.state.get(['汉'.repeat(86)]),
+            () => context.state.get(new Array(1)), () => context.state.get(null), () => context.state.get(),
+            () => 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;
@@ -501,7 +535,7 @@ export const runtimeConformanceCases: readonly RuntimeConformanceCase[] = [
       })
       equal(
         result,
-        Array.from({ length: 14 }, () => 'capability.invalid'),
+        Array.from({ length: 22 }, () => 'capability.invalid'),
         'State boundary validation',
       )
       equal(calls, 0, 'State invalid dispatch')

package/src/state/common/conformance.ts

@@ -12,6 +12,22 @@ export interface StateConformanceHarness {
 }
 
 export const stateConformanceCases: readonly { name: string; verify(harness: StateConformanceHarness): Promise<void> }[] = [
+  {
+    name: 'reads selected State keys in input order with missing, falsy and independent values',
+    async verify(harness) {
+      const result = await harness.run(`export default async (_, context) => {
+        await context.state.set('object', { nested: [1] });
+        await context.state.set('zero', 0);
+        await context.state.set('false', false);
+        await context.state.set('empty', '');
+        const values = await context.state.get(['false', 'missing', 'object', 'zero', 'empty']);
+        values[2].nested.push(2);
+        return {result: {values, retained: await context.state.get('object'), zero: await context.state.get('zero')}};
+      }`)
+      if (!dequal(result, { values: [false, null, { nested: [1, 2] }, 0, ''], retained: { nested: [1] }, zero: 0 }))
+        throw new Error('State batch reads must preserve order, missing keys and independent JSON values.')
+    },
+  },
   {
     name: 'skips composite identities across successful Runs without depending on field order',
     async verify(harness) {