@requence/task 0.8.2-edge.1151 → 0.8.2-edge.1155

package/build/types/helpers/src/protocol/command.d.ts

@@ -1,9 +1,798 @@
 import { z } from 'zod/v4';
+import { type InputTreeList, type TreeList } from './treeNodes.ts';
 export declare const abortCommandSchema: z.ZodObject<{
     type: z.ZodLiteral<"ABORT">;
     reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type AbortCommand = z.infer<typeof abortCommandSchema>;
+/**
+ * "Re-announce this task's state" (issue #136).
+ *
+ * A caller that owns a row for the task — `ui/backend` — has seen no update for
+ * it long past the point where one was due, and cannot tell from its own state
+ * whether the task is running with a lost `TASK_START` or was never registered
+ * at all. This asks the only party that knows. The answer is an UPDATE, never a
+ * reply: a re-announced `TASK_START` when the machine is there, a `TASK_ERROR`
+ * when it is not — so every status change keeps travelling the one path
+ * (operator → update → monitor).
+ *
+ * A command rather than a direct publish into `operator.shards` (which is how
+ * the operator's own progress watchdog pokes a shard owner): a tenant may only
+ * write to its own exchange, and that exchange is bound into the shard family
+ * already. Riding the tenant exchange also puts the poke BEHIND this task's own
+ * CREATE in the same shard's FIFO — but that orders DELIVERY, not handling: the
+ * shard consumer has up to `PREFETCH` deliveries in handlers at once, so the
+ * poke can still be ANSWERED while the CREATE it is asking about is mid-flight
+ * (issue #140). The operator closes that gap itself: its consumer backs off a
+ * reconcile whose task has a CREATE in a handler on the same instance
+ * (`packages/operator/src/consumers/tasks.ts`).
+ */
+export declare const reconcileCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"RECONCILE">;
+}, z.core.$strip>;
+export type ReconcileCommand = z.infer<typeof reconcileCommandSchema>;
+/**
+ * The CREATE command, parameterised by HOW its tree gets validated.
+ *
+ * Validating a `treeList` is the single most expensive thing either end of this
+ * wire does — measured ~4 s for a 300 kB tree with 23 references — so both ends
+ * splice a content-hashed memo in here: the operator on receipt (#132),
+ * `task-builder` before it publishes (#138), through the one cache in
+ * `../treeListCache.ts`. Everything else about a CREATE is the same on both
+ * sides. The plain `createCommandSchema` below, with no memo at all, is what
+ * anyone else validating a CREATE gets.
+ *
+ * A parameter rather than two schemas, because the rest of the command must NOT
+ * be duplicated: a second copy of this transform would go on accepting fields
+ * the other one has started to reject, and — since the caller hashes exactly
+ * what it is handed here — a drifting `allowMultipleOutputs` would key the cache
+ * on something other than what it stores. One shape, two tree parsers.
+ */
+export declare function createCommandSchemaWith(parseTreeList: (treeList: InputTreeList) => TreeList): z.ZodPipe<z.ZodObject<{
+    type: z.ZodLiteral<"CREATE">;
+    treeList: z.ZodObject<{
+        tree: z.ZodObject<{
+            nodes: z.ZodArray<z.ZodAny>;
+            edges: z.ZodArray<z.ZodAny>;
+        }, z.core.$strip>;
+        references: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+        schemas: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, z.core.$strip>;
+    input: z.ZodOptional<z.ZodAny>;
+    options: z.ZodObject<{
+        maxExecutions: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        mode: z.ZodDefault<z.ZodEnum<{
+            CONTINUOUS: "CONTINUOUS";
+            LINEAR: "LINEAR";
+        }>>;
+        priority: z.ZodDefault<z.ZodInt>;
+        uploadUrl: z.ZodOptional<z.ZodString>;
+        streamUrl: z.ZodOptional<z.ZodString>;
+        maxPayloadSize: z.ZodOptional<z.ZodNumber>;
+        maxFileSize: z.ZodOptional<z.ZodNumber>;
+        continuous: z.ZodDefault<z.ZodObject<{
+            maxReconnects: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        referencedBy: z.ZodOptional<z.ZodObject<{
+            rootTaskId: z.ZodUUID;
+            taskId: z.ZodUUID;
+            nodeId: z.ZodUUID;
+            messageId: z.ZodUUID;
+            epoch: z.ZodOptional<z.ZodUUID>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+    type: "CREATE";
+    input?: any;
+    options: {
+        maxExecutions: number;
+        mode: "CONTINUOUS" | "LINEAR";
+        priority: number;
+        uploadUrl?: string | undefined;
+        streamUrl?: string | undefined;
+        maxPayloadSize?: number | undefined;
+        maxFileSize?: number | undefined;
+        continuous: {
+            maxReconnects: number;
+        };
+        referencedBy?: {
+            rootTaskId: string;
+            taskId: string;
+            nodeId: string;
+            messageId: string;
+            epoch?: string | undefined;
+        } | undefined;
+    };
+    treeList: {
+        tree: {
+            nodes: ({
+                id: string;
+                type: "entry";
+                alias?: string | undefined;
+                inputSchema: import("json-schema").JSONSchema7;
+            } | {
+                outputs: {
+                    name: string | null;
+                    schema: import("json-schema").JSONSchema7 | null;
+                }[];
+                id: string;
+                type: "service";
+                alias?: string | undefined;
+                inputSchema: {
+                    type: "null";
+                } | ({
+                    type: "object";
+                } & import("json-schema").JSONSchema7) | ({
+                    $ref: string;
+                } & import("json-schema").JSONSchema7) | ({
+                    oneOf: ({
+                        type: "null";
+                    } | ({
+                        type: "object";
+                    } & import("json-schema").JSONSchema7) | ({
+                        $ref: string;
+                    } & import("json-schema").JSONSchema7))[];
+                } & import("json-schema").JSONSchema7);
+                name: string;
+                version: string;
+                configuration?: any;
+                configurationSchema: import("json-schema").JSONSchema7;
+                ttl?: number | undefined;
+                retry: number;
+                retryDelay?: number | undefined;
+                mode: "CONTINUOUS" | "LINEAR";
+                privileged: boolean;
+                wireCodec?: "json" | "msgpack" | undefined;
+                wireCodecReason?: "fleet-capable" | "missing-capability" | "no-replicas" | "presence-unavailable" | "replicas-unaccounted" | undefined;
+                configurationServices?: {
+                    outputs: {
+                        name: string | null;
+                        schema: import("json-schema").JSONSchema7 | null;
+                    }[];
+                    id: string;
+                    type: "service";
+                    alias?: string | undefined;
+                    inputSchema: {
+                        type: "null";
+                    } | ({
+                        type: "object";
+                    } & import("json-schema").JSONSchema7) | ({
+                        $ref: string;
+                    } & import("json-schema").JSONSchema7) | ({
+                        oneOf: ({
+                            type: "null";
+                        } | ({
+                            type: "object";
+                        } & import("json-schema").JSONSchema7) | ({
+                            $ref: string;
+                        } & import("json-schema").JSONSchema7))[];
+                    } & import("json-schema").JSONSchema7);
+                    name: string;
+                    version: string;
+                    configuration?: any;
+                    configurationSchema: import("json-schema").JSONSchema7;
+                    ttl?: number | undefined;
+                    retry: number;
+                    retryDelay?: number | undefined;
+                    mode: "CONTINUOUS" | "LINEAR";
+                    privileged: boolean;
+                    wireCodec?: "json" | "msgpack" | undefined;
+                    wireCodecReason?: "fleet-capable" | "missing-capability" | "no-replicas" | "presence-unavailable" | "replicas-unaccounted" | undefined;
+                    configurationServices?: /*elided*/ any[] | undefined;
+                }[] | undefined;
+            } | {
+                outputs: {
+                    name: string | null;
+                    schema: import("json-schema").JSONSchema7 | null;
+                }[];
+                id: string;
+                type: "logic";
+                alias?: string | undefined;
+                script: string;
+                concurrency: boolean;
+                language: "javascript" | "python" | "typescript";
+                maxExecutionTime: number;
+            } | {
+                id: string;
+                type: "or";
+                alias?: string | undefined;
+            } | {
+                outputs: {
+                    name: string | null;
+                    schema: import("json-schema").JSONSchema7 | null;
+                }[];
+                id: string;
+                type: "reference";
+                alias?: string | undefined;
+                reference: string;
+                enabled: boolean;
+                inputSchema: {
+                    type: "null";
+                } | ({
+                    type: "object";
+                } & import("json-schema").JSONSchema7) | ({
+                    $ref: string;
+                } & import("json-schema").JSONSchema7) | ({
+                    oneOf: ({
+                        type: "null";
+                    } | ({
+                        type: "object";
+                    } & import("json-schema").JSONSchema7) | ({
+                        $ref: string;
+                    } & import("json-schema").JSONSchema7))[];
+                } & import("json-schema").JSONSchema7);
+            } | {
+                id: string;
+                type: "exit";
+                alias?: string | undefined;
+                inputSchema?: import("json-schema").JSONSchema7 | undefined;
+            } | {
+                id: string;
+                type: "comment";
+                text: string;
+                alias?: string | undefined;
+            })[];
+            edges: {
+                id: string;
+                source: string;
+                sourceHandle: string | null;
+                target: string;
+            }[];
+        };
+        references?: {
+            id: string;
+            options: {
+                maxExecutions: number;
+                mode: "CONTINUOUS" | "LINEAR";
+            };
+            tree: {
+                nodes: ({
+                    id: string;
+                    type: "entry";
+                    alias?: string | undefined;
+                    inputSchema: import("json-schema").JSONSchema7;
+                } | {
+                    outputs: {
+                        name: string | null;
+                        schema: import("json-schema").JSONSchema7 | null;
+                    }[];
+                    id: string;
+                    type: "service";
+                    alias?: string | undefined;
+                    inputSchema: {
+                        type: "null";
+                    } | ({
+                        type: "object";
+                    } & import("json-schema").JSONSchema7) | ({
+                        $ref: string;
+                    } & import("json-schema").JSONSchema7) | ({
+                        oneOf: ({
+                            type: "null";
+                        } | ({
+                            type: "object";
+                        } & import("json-schema").JSONSchema7) | ({
+                            $ref: string;
+                        } & import("json-schema").JSONSchema7))[];
+                    } & import("json-schema").JSONSchema7);
+                    name: string;
+                    version: string;
+                    configuration?: any;
+                    configurationSchema: import("json-schema").JSONSchema7;
+                    ttl?: number | undefined;
+                    retry: number;
+                    retryDelay?: number | undefined;
+                    mode: "CONTINUOUS" | "LINEAR";
+                    privileged: boolean;
+                    wireCodec?: "json" | "msgpack" | undefined;
+                    wireCodecReason?: "fleet-capable" | "missing-capability" | "no-replicas" | "presence-unavailable" | "replicas-unaccounted" | undefined;
+                    configurationServices?: {
+                        outputs: {
+                            name: string | null;
+                            schema: import("json-schema").JSONSchema7 | null;
+                        }[];
+                        id: string;
+                        type: "service";
+                        alias?: string | undefined;
+                        inputSchema: {
+                            type: "null";
+                        } | ({
+                            type: "object";
+                        } & import("json-schema").JSONSchema7) | ({
+                            $ref: string;
+                        } & import("json-schema").JSONSchema7) | ({
+                            oneOf: ({
+                                type: "null";
+                            } | ({
+                                type: "object";
+                            } & import("json-schema").JSONSchema7) | ({
+                                $ref: string;
+                            } & import("json-schema").JSONSchema7))[];
+                        } & import("json-schema").JSONSchema7);
+                        name: string;
+                        version: string;
+                        configuration?: any;
+                        configurationSchema: import("json-schema").JSONSchema7;
+                        ttl?: number | undefined;
+                        retry: number;
+                        retryDelay?: number | undefined;
+                        mode: "CONTINUOUS" | "LINEAR";
+                        privileged: boolean;
+                        wireCodec?: "json" | "msgpack" | undefined;
+                        wireCodecReason?: "fleet-capable" | "missing-capability" | "no-replicas" | "presence-unavailable" | "replicas-unaccounted" | undefined;
+                        configurationServices?: any[] | undefined;
+                    }[] | undefined;
+                } | {
+                    outputs: {
+                        name: string | null;
+                        schema: import("json-schema").JSONSchema7 | null;
+                    }[];
+                    id: string;
+                    type: "logic";
+                    alias?: string | undefined;
+                    script: string;
+                    concurrency: boolean;
+                    language: "javascript" | "python" | "typescript";
+                    maxExecutionTime: number;
+                } | {
+                    id: string;
+                    type: "or";
+                    alias?: string | undefined;
+                } | {
+                    outputs: {
+                        name: string | null;
+                        schema: import("json-schema").JSONSchema7 | null;
+                    }[];
+                    id: string;
+                    type: "reference";
+                    alias?: string | undefined;
+                    reference: string;
+                    enabled: boolean;
+                    inputSchema: {
+                        type: "null";
+                    } | ({
+                        type: "object";
+                    } & import("json-schema").JSONSchema7) | ({
+                        $ref: string;
+                    } & import("json-schema").JSONSchema7) | ({
+                        oneOf: ({
+                            type: "null";
+                        } | ({
+                            type: "object";
+                        } & import("json-schema").JSONSchema7) | ({
+                            $ref: string;
+                        } & import("json-schema").JSONSchema7))[];
+                    } & import("json-schema").JSONSchema7);
+                } | {
+                    id: string;
+                    type: "exit";
+                    alias?: string | undefined;
+                    inputSchema?: import("json-schema").JSONSchema7 | undefined;
+                } | {
+                    id: string;
+                    type: "comment";
+                    text: string;
+                    alias?: string | undefined;
+                })[];
+                edges: {
+                    id: string;
+                    source: string;
+                    sourceHandle: string | null;
+                    target: string;
+                }[];
+            };
+        }[] | undefined;
+        schemas?: Record<string, import("json-schema").JSONSchema7> | undefined;
+    };
+}, {
+    type: "CREATE";
+    treeList: {
+        tree: {
+            nodes: any[];
+            edges: any[];
+        };
+        references?: any[] | undefined;
+        schemas?: Record<string, any> | undefined;
+    };
+    input?: any;
+    options: {
+        maxExecutions: number;
+        mode: "CONTINUOUS" | "LINEAR";
+        priority: number;
+        uploadUrl?: string | undefined;
+        streamUrl?: string | undefined;
+        maxPayloadSize?: number | undefined;
+        maxFileSize?: number | undefined;
+        continuous: {
+            maxReconnects: number;
+        };
+        referencedBy?: {
+            rootTaskId: string;
+            taskId: string;
+            nodeId: string;
+            messageId: string;
+            epoch?: string | undefined;
+        } | undefined;
+    };
+}>>;
+/**
+ * The same command, for a tree parser that yields to the event loop (#134).
+ *
+ * A separate factory rather than one that takes either kind, because the two
+ * cannot share a call site: zod only awaits a transform whose RETURN is a
+ * promise, so the async arm has to be an `async` transform — and that makes the
+ * whole schema `parseAsync`-only, which the sync side must not become. Both
+ * memoizing callers are on this arm now (#138 moved `task-builder` over, which
+ * cost it nothing: `publishTask` was already `async`); the sync arm is the
+ * `commandSchema` union and anyone validating a CREATE without a cache. What
+ * they share is everything that defines the command: one envelope, one
+ * validation input.
+ */
+export declare function createCommandSchemaWithAsync(parseTreeList: (treeList: InputTreeList) => Promise<TreeList>): z.ZodPipe<z.ZodObject<{
+    type: z.ZodLiteral<"CREATE">;
+    treeList: z.ZodObject<{
+        tree: z.ZodObject<{
+            nodes: z.ZodArray<z.ZodAny>;
+            edges: z.ZodArray<z.ZodAny>;
+        }, z.core.$strip>;
+        references: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+        schemas: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, z.core.$strip>;
+    input: z.ZodOptional<z.ZodAny>;
+    options: z.ZodObject<{
+        maxExecutions: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        mode: z.ZodDefault<z.ZodEnum<{
+            CONTINUOUS: "CONTINUOUS";
+            LINEAR: "LINEAR";
+        }>>;
+        priority: z.ZodDefault<z.ZodInt>;
+        uploadUrl: z.ZodOptional<z.ZodString>;
+        streamUrl: z.ZodOptional<z.ZodString>;
+        maxPayloadSize: z.ZodOptional<z.ZodNumber>;
+        maxFileSize: z.ZodOptional<z.ZodNumber>;
+        continuous: z.ZodDefault<z.ZodObject<{
+            maxReconnects: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        referencedBy: z.ZodOptional<z.ZodObject<{
+            rootTaskId: z.ZodUUID;
+            taskId: z.ZodUUID;
+            nodeId: z.ZodUUID;
+            messageId: z.ZodUUID;
+            epoch: z.ZodOptional<z.ZodUUID>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+    type: "CREATE";
+    input?: any;
+    options: {
+        maxExecutions: number;
+        mode: "CONTINUOUS" | "LINEAR";
+        priority: number;
+        uploadUrl?: string | undefined;
+        streamUrl?: string | undefined;
+        maxPayloadSize?: number | undefined;
+        maxFileSize?: number | undefined;
+        continuous: {
+            maxReconnects: number;
+        };
+        referencedBy?: {
+            rootTaskId: string;
+            taskId: string;
+            nodeId: string;
+            messageId: string;
+            epoch?: string | undefined;
+        } | undefined;
+    };
+    treeList: {
+        tree: {
+            nodes: ({
+                id: string;
+                type: "entry";
+                alias?: string | undefined;
+                inputSchema: import("json-schema").JSONSchema7;
+            } | {
+                outputs: {
+                    name: string | null;
+                    schema: import("json-schema").JSONSchema7 | null;
+                }[];
+                id: string;
+                type: "service";
+                alias?: string | undefined;
+                inputSchema: {
+                    type: "null";
+                } | ({
+                    type: "object";
+                } & import("json-schema").JSONSchema7) | ({
+                    $ref: string;
+                } & import("json-schema").JSONSchema7) | ({
+                    oneOf: ({
+                        type: "null";
+                    } | ({
+                        type: "object";
+                    } & import("json-schema").JSONSchema7) | ({
+                        $ref: string;
+                    } & import("json-schema").JSONSchema7))[];
+                } & import("json-schema").JSONSchema7);
+                name: string;
+                version: string;
+                configuration?: any;
+                configurationSchema: import("json-schema").JSONSchema7;
+                ttl?: number | undefined;
+                retry: number;
+                retryDelay?: number | undefined;
+                mode: "CONTINUOUS" | "LINEAR";
+                privileged: boolean;
+                wireCodec?: "json" | "msgpack" | undefined;
+                wireCodecReason?: "fleet-capable" | "missing-capability" | "no-replicas" | "presence-unavailable" | "replicas-unaccounted" | undefined;
+                configurationServices?: {
+                    outputs: {
+                        name: string | null;
+                        schema: import("json-schema").JSONSchema7 | null;
+                    }[];
+                    id: string;
+                    type: "service";
+                    alias?: string | undefined;
+                    inputSchema: {
+                        type: "null";
+                    } | ({
+                        type: "object";
+                    } & import("json-schema").JSONSchema7) | ({
+                        $ref: string;
+                    } & import("json-schema").JSONSchema7) | ({
+                        oneOf: ({
+                            type: "null";
+                        } | ({
+                            type: "object";
+                        } & import("json-schema").JSONSchema7) | ({
+                            $ref: string;
+                        } & import("json-schema").JSONSchema7))[];
+                    } & import("json-schema").JSONSchema7);
+                    name: string;
+                    version: string;
+                    configuration?: any;
+                    configurationSchema: import("json-schema").JSONSchema7;
+                    ttl?: number | undefined;
+                    retry: number;
+                    retryDelay?: number | undefined;
+                    mode: "CONTINUOUS" | "LINEAR";
+                    privileged: boolean;
+                    wireCodec?: "json" | "msgpack" | undefined;
+                    wireCodecReason?: "fleet-capable" | "missing-capability" | "no-replicas" | "presence-unavailable" | "replicas-unaccounted" | undefined;
+                    configurationServices?: /*elided*/ any[] | undefined;
+                }[] | undefined;
+            } | {
+                outputs: {
+                    name: string | null;
+                    schema: import("json-schema").JSONSchema7 | null;
+                }[];
+                id: string;
+                type: "logic";
+                alias?: string | undefined;
+                script: string;
+                concurrency: boolean;
+                language: "javascript" | "python" | "typescript";
+                maxExecutionTime: number;
+            } | {
+                id: string;
+                type: "or";
+                alias?: string | undefined;
+            } | {
+                outputs: {
+                    name: string | null;
+                    schema: import("json-schema").JSONSchema7 | null;
+                }[];
+                id: string;
+                type: "reference";
+                alias?: string | undefined;
+                reference: string;
+                enabled: boolean;
+                inputSchema: {
+                    type: "null";
+                } | ({
+                    type: "object";
+                } & import("json-schema").JSONSchema7) | ({
+                    $ref: string;
+                } & import("json-schema").JSONSchema7) | ({
+                    oneOf: ({
+                        type: "null";
+                    } | ({
+                        type: "object";
+                    } & import("json-schema").JSONSchema7) | ({
+                        $ref: string;
+                    } & import("json-schema").JSONSchema7))[];
+                } & import("json-schema").JSONSchema7);
+            } | {
+                id: string;
+                type: "exit";
+                alias?: string | undefined;
+                inputSchema?: import("json-schema").JSONSchema7 | undefined;
+            } | {
+                id: string;
+                type: "comment";
+                text: string;
+                alias?: string | undefined;
+            })[];
+            edges: {
+                id: string;
+                source: string;
+                sourceHandle: string | null;
+                target: string;
+            }[];
+        };
+        references?: {
+            id: string;
+            options: {
+                maxExecutions: number;
+                mode: "CONTINUOUS" | "LINEAR";
+            };
+            tree: {
+                nodes: ({
+                    id: string;
+                    type: "entry";
+                    alias?: string | undefined;
+                    inputSchema: import("json-schema").JSONSchema7;
+                } | {
+                    outputs: {
+                        name: string | null;
+                        schema: import("json-schema").JSONSchema7 | null;
+                    }[];
+                    id: string;
+                    type: "service";
+                    alias?: string | undefined;
+                    inputSchema: {
+                        type: "null";
+                    } | ({
+                        type: "object";
+                    } & import("json-schema").JSONSchema7) | ({
+                        $ref: string;
+                    } & import("json-schema").JSONSchema7) | ({
+                        oneOf: ({
+                            type: "null";
+                        } | ({
+                            type: "object";
+                        } & import("json-schema").JSONSchema7) | ({
+                            $ref: string;
+                        } & import("json-schema").JSONSchema7))[];
+                    } & import("json-schema").JSONSchema7);
+                    name: string;
+                    version: string;
+                    configuration?: any;
+                    configurationSchema: import("json-schema").JSONSchema7;
+                    ttl?: number | undefined;
+                    retry: number;
+                    retryDelay?: number | undefined;
+                    mode: "CONTINUOUS" | "LINEAR";
+                    privileged: boolean;
+                    wireCodec?: "json" | "msgpack" | undefined;
+                    wireCodecReason?: "fleet-capable" | "missing-capability" | "no-replicas" | "presence-unavailable" | "replicas-unaccounted" | undefined;
+                    configurationServices?: {
+                        outputs: {
+                            name: string | null;
+                            schema: import("json-schema").JSONSchema7 | null;
+                        }[];
+                        id: string;
+                        type: "service";
+                        alias?: string | undefined;
+                        inputSchema: {
+                            type: "null";
+                        } | ({
+                            type: "object";
+                        } & import("json-schema").JSONSchema7) | ({
+                            $ref: string;
+                        } & import("json-schema").JSONSchema7) | ({
+                            oneOf: ({
+                                type: "null";
+                            } | ({
+                                type: "object";
+                            } & import("json-schema").JSONSchema7) | ({
+                                $ref: string;
+                            } & import("json-schema").JSONSchema7))[];
+                        } & import("json-schema").JSONSchema7);
+                        name: string;
+                        version: string;
+                        configuration?: any;
+                        configurationSchema: import("json-schema").JSONSchema7;
+                        ttl?: number | undefined;
+                        retry: number;
+                        retryDelay?: number | undefined;
+                        mode: "CONTINUOUS" | "LINEAR";
+                        privileged: boolean;
+                        wireCodec?: "json" | "msgpack" | undefined;
+                        wireCodecReason?: "fleet-capable" | "missing-capability" | "no-replicas" | "presence-unavailable" | "replicas-unaccounted" | undefined;
+                        configurationServices?: any[] | undefined;
+                    }[] | undefined;
+                } | {
+                    outputs: {
+                        name: string | null;
+                        schema: import("json-schema").JSONSchema7 | null;
+                    }[];
+                    id: string;
+                    type: "logic";
+                    alias?: string | undefined;
+                    script: string;
+                    concurrency: boolean;
+                    language: "javascript" | "python" | "typescript";
+                    maxExecutionTime: number;
+                } | {
+                    id: string;
+                    type: "or";
+                    alias?: string | undefined;
+                } | {
+                    outputs: {
+                        name: string | null;
+                        schema: import("json-schema").JSONSchema7 | null;
+                    }[];
+                    id: string;
+                    type: "reference";
+                    alias?: string | undefined;
+                    reference: string;
+                    enabled: boolean;
+                    inputSchema: {
+                        type: "null";
+                    } | ({
+                        type: "object";
+                    } & import("json-schema").JSONSchema7) | ({
+                        $ref: string;
+                    } & import("json-schema").JSONSchema7) | ({
+                        oneOf: ({
+                            type: "null";
+                        } | ({
+                            type: "object";
+                        } & import("json-schema").JSONSchema7) | ({
+                            $ref: string;
+                        } & import("json-schema").JSONSchema7))[];
+                    } & import("json-schema").JSONSchema7);
+                } | {
+                    id: string;
+                    type: "exit";
+                    alias?: string | undefined;
+                    inputSchema?: import("json-schema").JSONSchema7 | undefined;
+                } | {
+                    id: string;
+                    type: "comment";
+                    text: string;
+                    alias?: string | undefined;
+                })[];
+                edges: {
+                    id: string;
+                    source: string;
+                    sourceHandle: string | null;
+                    target: string;
+                }[];
+            };
+        }[] | undefined;
+        schemas?: Record<string, import("json-schema").JSONSchema7> | undefined;
+    };
+}, {
+    type: "CREATE";
+    treeList: {
+        tree: {
+            nodes: any[];
+            edges: any[];
+        };
+        references?: any[] | undefined;
+        schemas?: Record<string, any> | undefined;
+    };
+    input?: any;
+    options: {
+        maxExecutions: number;
+        mode: "CONTINUOUS" | "LINEAR";
+        priority: number;
+        uploadUrl?: string | undefined;
+        streamUrl?: string | undefined;
+        maxPayloadSize?: number | undefined;
+        maxFileSize?: number | undefined;
+        continuous: {
+            maxReconnects: number;
+        };
+        referencedBy?: {
+            rootTaskId: string;
+            taskId: string;
+            nodeId: string;
+            messageId: string;
+            epoch?: string | undefined;
+        } | undefined;
+    };
+}>>;
 export declare const createCommandSchema: z.ZodPipe<z.ZodObject<{
     type: z.ZodLiteral<"CREATE">;
     treeList: z.ZodObject<{
@@ -14,7 +803,7 @@ export declare const createCommandSchema: z.ZodPipe<z.ZodObject<{
         references: z.ZodOptional<z.ZodArray<z.ZodAny>>;
         schemas: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     }, z.core.$strip>;
-    input: z.ZodAny;
+    input: z.ZodOptional<z.ZodAny>;
     options: z.ZodObject<{
         maxExecutions: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         mode: z.ZodDefault<z.ZodEnum<{
@@ -39,7 +828,7 @@ export declare const createCommandSchema: z.ZodPipe<z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodTransform<{
     type: "CREATE";
-    input: any;
+    input?: any;
     options: {
         maxExecutions: number;
         mode: "CONTINUOUS" | "LINEAR";
@@ -349,7 +1138,7 @@ export declare const createCommandSchema: z.ZodPipe<z.ZodObject<{
         references?: any[] | undefined;
         schemas?: Record<string, any> | undefined;
     };
-    input: any;
+    input?: any;
     options: {
         maxExecutions: number;
         mode: "CONTINUOUS" | "LINEAR";
@@ -371,9 +1160,54 @@ export declare const createCommandSchema: z.ZodPipe<z.ZodObject<{
     };
 }>>;
 export type CreateCommand = z.infer<typeof createCommandSchema>;
+/**
+ * A viewer drove a service-provided surface (#104).
+ *
+ * A command rather than a result, because there is no service process behind a
+ * click: ui/backend holds no capability of the service's, opens no connection on
+ * its behalf and composes no service-protocol message — it forwards *which
+ * handler, with what*, and the operator publishes the invocation. It travels the
+ * one channel ui/backend already has to the operator, so it hashes onto the
+ * task's own shard and cannot overtake or be overtaken by that task's other
+ * commands (knowledge/task-sharding.md).
+ *
+ * `nodeId` — not a message id — is what names the service the handler belongs
+ * to. The pair `(name, version)` is read off the node, and the node is the only
+ * one of the two that a **durable** handler can still be resolved through: it
+ * outlives the message that published the render, which is the whole point of
+ * being durable.
+ *
+ * The handler reference travels verbatim, exactly as the render carried it out
+ * (#103): its `lifetime` is what decides whether the operator publishes to the
+ * version's handler queue or to one connection's backchannel, and the browser
+ * never sees either — it names a props path, and ui/backend resolves it against
+ * what it stored.
+ */
+export declare const invokeSurfaceHandlerCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"INVOKE_SURFACE_HANDLER">;
+    nodeId: z.ZodUUID;
+    surface: z.ZodUUID;
+    handler: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        __REQUENCE_type: z.ZodLiteral<"RequenceHandler">;
+        lifetime: z.ZodLiteral<"durable">;
+        uiId: z.ZodString;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+    }, z.core.$strip>, z.ZodObject<{
+        __REQUENCE_type: z.ZodLiteral<"RequenceHandler">;
+        lifetime: z.ZodLiteral<"connection">;
+        uiId: z.ZodString;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        connectionId: z.ZodString;
+        handlerId: z.ZodUUID;
+    }, z.core.$strip>], "lifetime">;
+    arg: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type InvokeSurfaceHandlerCommand = z.infer<typeof invokeSurfaceHandlerCommandSchema>;
 export declare const commandSchema: z.ZodUnion<readonly [z.ZodObject<{
     type: z.ZodLiteral<"ABORT">;
     reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"RECONCILE">;
 }, z.core.$strip>, z.ZodPipe<z.ZodObject<{
     type: z.ZodLiteral<"CREATE">;
     treeList: z.ZodObject<{
@@ -384,7 +1218,7 @@ export declare const commandSchema: z.ZodUnion<readonly [z.ZodObject<{
         references: z.ZodOptional<z.ZodArray<z.ZodAny>>;
         schemas: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     }, z.core.$strip>;
-    input: z.ZodAny;
+    input: z.ZodOptional<z.ZodAny>;
     options: z.ZodObject<{
         maxExecutions: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         mode: z.ZodDefault<z.ZodEnum<{
@@ -409,7 +1243,7 @@ export declare const commandSchema: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodTransform<{
     type: "CREATE";
-    input: any;
+    input?: any;
     options: {
         maxExecutions: number;
         mode: "CONTINUOUS" | "LINEAR";
@@ -719,7 +1553,7 @@ export declare const commandSchema: z.ZodUnion<readonly [z.ZodObject<{
         references?: any[] | undefined;
         schemas?: Record<string, any> | undefined;
     };
-    input: any;
+    input?: any;
     options: {
         maxExecutions: number;
         mode: "CONTINUOUS" | "LINEAR";
@@ -739,7 +1573,25 @@ export declare const commandSchema: z.ZodUnion<readonly [z.ZodObject<{
             epoch?: string | undefined;
         } | undefined;
     };
-}>>]>;
+}>>, z.ZodObject<{
+    type: z.ZodLiteral<"INVOKE_SURFACE_HANDLER">;
+    nodeId: z.ZodUUID;
+    surface: z.ZodUUID;
+    handler: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        __REQUENCE_type: z.ZodLiteral<"RequenceHandler">;
+        lifetime: z.ZodLiteral<"durable">;
+        uiId: z.ZodString;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+    }, z.core.$strip>, z.ZodObject<{
+        __REQUENCE_type: z.ZodLiteral<"RequenceHandler">;
+        lifetime: z.ZodLiteral<"connection">;
+        uiId: z.ZodString;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        connectionId: z.ZodString;
+        handlerId: z.ZodUUID;
+    }, z.core.$strip>], "lifetime">;
+    arg: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>]>;
 export type Command = z.infer<typeof commandSchema>;
 export type CommandInput = z.input<typeof commandSchema>;
 //# sourceMappingURL=command.d.ts.map