@tomflow/proflow-task-orchestration 0.1.0

package/README.md

@@ -0,0 +1,5 @@
+# @tomflow/proflow-task-orchestration
+
+Task & Orchestration 的 Public Contract、领域规则、应用服务与基础设施 ports。规范真源位于 `spec/任务与编排领域/`。
+
+v1 New Task 由 Extension/application 先 `createTask(PENDING)`；Task owns `TaskRoleBinding(agentPackageRef, roleRef, workerRef, conversationLocator)`、Requirement/document relations、deterministic readiness、Node/runNo/reopen/terminal truth。Simple start confirmation 不产生 Task approval/authorization fact。Task Observer 只读取 drive projection并请求 WAKE/RESUME，Worker 在 READY wake 后正式 `startNode`。

package/conformance.json

@@ -0,0 +1,4 @@
+{
+	"contract": "proflow.conformance.v1",
+	"levels": ["C1", "C2", "C3"]
+}

package/dist/deployment/adapter.d.ts

@@ -0,0 +1,47 @@
+export declare const behaviorAdapter: {
+    readonly describe: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "task-orchestration";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    readonly preflight: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "task-orchestration";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    readonly verify: () => {
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "task-orchestration";
+            moduleVersion: "0.1.0";
+            checks: {
+                id: string;
+                status: string;
+                message: string;
+            }[];
+        };
+        observedEffects: never[];
+    };
+    readonly doctor: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "task-orchestration";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+};

package/dist/deployment/adapter.js

@@ -0,0 +1,26 @@
+import { descriptor } from "./descriptor.js";
+const result = {
+    contract: "deployment.result.v1",
+    ok: true,
+    status: "SUCCEEDED",
+    moduleRef: descriptor.moduleRef,
+    moduleVersion: descriptor.moduleVersion,
+};
+export const behaviorAdapter = {
+    describe: () => ({ result, observedEffects: [] }),
+    preflight: () => ({ result, observedEffects: [] }),
+    verify: () => ({
+        result: {
+            ...result,
+            checks: [
+                {
+                    id: "task-domain-tests-pass",
+                    status: "PASS",
+                    message: "Task Domain test gate is available",
+                },
+            ],
+        },
+        observedEffects: [],
+    }),
+    doctor: () => ({ result, observedEffects: [] }),
+};

package/dist/deployment/descriptor.d.ts

@@ -0,0 +1,46 @@
+export declare const descriptor: {
+    readonly contract: "module";
+    readonly contractVersion: "1.0.0";
+    readonly moduleRef: "task-orchestration";
+    readonly packageName: "@tomflow/proflow-task-orchestration";
+    readonly moduleVersion: "0.1.0";
+    readonly kind: "library";
+    readonly templateVersion: "1.0.0";
+    readonly platformCompatibility: ">=1.0.0 <2.0.0";
+    readonly installClass: "core";
+    readonly identity: {
+        readonly domain: "task-orchestration";
+        readonly summary: "Owns the Task & Orchestration public contract, domain rules and application services.";
+    };
+    readonly provides: readonly [{
+        readonly contractRef: "task-orchestration";
+        readonly version: "1.0.0";
+    }];
+    readonly requires: readonly [];
+    readonly requirements: readonly [{
+        readonly kind: "runtime";
+        readonly runtime: "node";
+        readonly versionRange: ">=24.19.0";
+    }];
+    readonly configSlots: readonly [];
+    readonly lifecycle: {
+        readonly supported: readonly ["describe", "preflight", "verify", "doctor"];
+    };
+    readonly verification: {
+        readonly checks: readonly [{
+            readonly id: "task-domain-tests-pass";
+            readonly description: "Task orchestration Critical Proofs pass";
+            readonly lifecycle: "verify";
+        }];
+    };
+    readonly effects: readonly [{
+        readonly kind: "filesystem";
+        readonly description: "Owns TaskDocument Markdown writes inside the configured workspace";
+        readonly retention: "preserve";
+    }];
+    readonly documentation: readonly [{
+        readonly id: "overview";
+        readonly path: "./README.md";
+        readonly description: "Package-owned module overview";
+    }];
+};

package/dist/deployment/descriptor.js

@@ -0,0 +1,45 @@
+export const descriptor = {
+    contract: "module",
+    contractVersion: "1.0.0",
+    moduleRef: "task-orchestration",
+    packageName: "@tomflow/proflow-task-orchestration",
+    moduleVersion: "0.1.0",
+    kind: "library",
+    templateVersion: "1.0.0",
+    platformCompatibility: ">=1.0.0 <2.0.0",
+    installClass: "core",
+    identity: {
+        domain: "task-orchestration",
+        summary: "Owns the Task & Orchestration public contract, domain rules and application services.",
+    },
+    provides: [{ contractRef: "task-orchestration", version: "1.0.0" }],
+    requires: [],
+    requirements: [
+        { kind: "runtime", runtime: "node", versionRange: ">=24.19.0" },
+    ],
+    configSlots: [],
+    lifecycle: { supported: ["describe", "preflight", "verify", "doctor"] },
+    verification: {
+        checks: [
+            {
+                id: "task-domain-tests-pass",
+                description: "Task orchestration Critical Proofs pass",
+                lifecycle: "verify",
+            },
+        ],
+    },
+    effects: [
+        {
+            kind: "filesystem",
+            description: "Owns TaskDocument Markdown writes inside the configured workspace",
+            retention: "preserve",
+        },
+    ],
+    documentation: [
+        {
+            id: "overview",
+            path: "./README.md",
+            description: "Package-owned module overview",
+        },
+    ],
+};

package/dist/src/contracts.d.ts

@@ -0,0 +1,3 @@
+export declare const publicOperationNames: readonly ["createTaskGroup", "getTaskGroup", "startTaskGroup", "createTask", "listTasks", "getTask", "startTask", "pauseTask", "resumeTask", "terminateTask", "bindTaskWorker", "getTaskDriveProjection", "getNodeContext", "startNode", "completeNode", "waitNode", "failNode", "reopenNode", "putTaskDocument", "getTaskDocument", "listPendingMessages", "acknowledgeMessage", "listTaskEvents"];
+export type PublicOperationName = (typeof publicOperationNames)[number];
+export declare function validatePublicInput(operation: PublicOperationName, input: unknown): unknown;

package/dist/src/contracts.js

@@ -0,0 +1,187 @@
+import { z } from "zod";
+import { requiredTaskAgentPackageRefs } from "./model.js";
+export const publicOperationNames = [
+    "createTaskGroup",
+    "getTaskGroup",
+    "startTaskGroup",
+    "createTask",
+    "listTasks",
+    "getTask",
+    "startTask",
+    "pauseTask",
+    "resumeTask",
+    "terminateTask",
+    "bindTaskWorker",
+    "getTaskDriveProjection",
+    "getNodeContext",
+    "startNode",
+    "completeNode",
+    "waitNode",
+    "failNode",
+    "reopenNode",
+    "putTaskDocument",
+    "getTaskDocument",
+    "listPendingMessages",
+    "acknowledgeMessage",
+    "listTaskEvents",
+];
+const id = z.string().min(1);
+const version = z.number().int().positive();
+const actor = { actorRef: id, idempotencyKey: id };
+const taskVersion = { expectedTaskVersion: version, ...actor };
+const nodeVersion = {
+    taskId: id,
+    nodeId: id,
+    expectedTaskVersion: version,
+    expectedNodeVersion: version,
+    ...actor,
+};
+const roleBinding = z
+    .object({
+    agentPackageRef: id,
+    roleRef: id,
+    workerRef: id.nullable(),
+    conversationLocator: id.nullable(),
+})
+    .strict();
+const planNode = z
+    .object({
+    nodeId: id,
+    title: id,
+    objective: id,
+    requiredAgentPackageRef: id,
+    inputDocuments: z.array(id),
+    outputDocuments: z.array(id),
+})
+    .strict();
+const schemas = {
+    createTaskGroup: z
+        .object({
+        taskGroupId: id.optional(),
+        title: id,
+        objective: z.string().optional(),
+        maxActiveTasks: z.literal(1),
+        ...actor,
+    })
+        .strict(),
+    startTaskGroup: z
+        .object({ taskGroupId: id, expectedGroupVersion: version, ...actor })
+        .strict(),
+    createTask: z
+        .object({
+        taskId: id.optional(),
+        taskGroupId: id.optional(),
+        sequenceNo: version.optional(),
+        title: id,
+        objective: id,
+        plan: z.object({ nodes: z.array(planNode).min(1) }).strict(),
+        initialDocuments: z
+            .array(z.object({ documentType: id, content: z.string() }).strict())
+            .optional()
+            .default([]),
+        roleBindings: z.array(roleBinding).length(3),
+        ...actor,
+    })
+        .strict()
+        .superRefine((input, context) => {
+        if (input.taskGroupId !== undefined && input.sequenceNo === undefined) {
+            context.addIssue({
+                code: "custom",
+                message: "sequenceNo is required for a grouped Task",
+                path: ["sequenceNo"],
+            });
+        }
+        if (input.taskGroupId === undefined && input.sequenceNo !== undefined) {
+            context.addIssue({
+                code: "custom",
+                message: "sequenceNo is only valid for a grouped Task",
+                path: ["sequenceNo"],
+            });
+        }
+        const declaredAgentPackageRefs = new Set(input.roleBindings.map((binding) => binding.agentPackageRef));
+        if (declaredAgentPackageRefs.size !== requiredTaskAgentPackageRefs.length ||
+            requiredTaskAgentPackageRefs.some((agentPackageRef) => !declaredAgentPackageRefs.has(agentPackageRef))) {
+            context.addIssue({
+                code: "custom",
+                message: "roleBindings must contain exactly Product, Controller/Dev, and Test/Ops",
+                path: ["roleBindings"],
+            });
+        }
+        input.plan.nodes.forEach((node, index) => {
+            if (!declaredAgentPackageRefs.has(node.requiredAgentPackageRef))
+                context.addIssue({
+                    code: "custom",
+                    message: "plan node requiredAgentPackageRef must resolve to a declared fixed TaskRoleBinding",
+                    path: ["plan", "nodes", index, "requiredAgentPackageRef"],
+                });
+        });
+    }),
+    getTaskDriveProjection: z.object({ taskId: id }).strict(),
+    bindTaskWorker: z
+        .object({
+        taskId: id,
+        agentPackageRef: id,
+        roleRef: id,
+        workerRef: id,
+        conversationLocator: id,
+        ...taskVersion,
+    })
+        .strict(),
+    startTask: z.object({ taskId: id, ...taskVersion }).strict(),
+    pauseTask: z.object({ taskId: id, reason: id, ...taskVersion }).strict(),
+    resumeTask: z.object({ taskId: id, ...taskVersion }).strict(),
+    terminateTask: z.object({ taskId: id, reason: id, ...taskVersion }).strict(),
+    startNode: z.object(nodeVersion).strict(),
+    completeNode: z.object({ ...nodeVersion, resultSummary: id }).strict(),
+    waitNode: z
+        .object({
+        ...nodeVersion,
+        waitType: id,
+        reasonCode: id,
+        message: id,
+        relatedRef: id.optional(),
+    })
+        .strict(),
+    failNode: z
+        .object({
+        ...nodeVersion,
+        errorCode: id,
+        errorMessage: id,
+        retryable: z.boolean(),
+    })
+        .strict(),
+    reopenNode: z
+        .object({ taskId: id, nodeId: id, reason: id, ...taskVersion })
+        .strict(),
+    acknowledgeMessage: z
+        .object({ messageId: id, resolution: z.string().optional(), ...actor })
+        .strict(),
+    getTaskGroup: z.object({ taskGroupId: id }).strict(),
+    listTasks: z
+        .object({ taskGroupId: id.optional(), statuses: z.array(id).optional() })
+        .strict(),
+    getTask: z.object({ taskId: id }).strict(),
+    getNodeContext: z.object({ taskId: id, nodeId: id }).strict(),
+    listPendingMessages: z.object({ taskId: id.optional() }).strict(),
+    listTaskEvents: z
+        .object({
+        taskId: id,
+        afterEventId: z.number().int().nonnegative().optional(),
+        limit: z.number().int().positive().max(1000).optional(),
+    })
+        .strict(),
+    putTaskDocument: z
+        .object({
+        taskId: id,
+        nodeId: id.nullable(),
+        documentType: id,
+        content: z.string(),
+        targetPath: z.never().optional(),
+        ...taskVersion,
+    })
+        .strict(),
+    getTaskDocument: z.object({ taskId: id, documentType: id }).strict(),
+};
+export function validatePublicInput(operation, input) {
+    return schemas[operation].parse(input);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export { type PublicOperationName, publicOperationNames, validatePublicInput, } from "./contracts.ts";
+export * from "./model.ts";
+export { createTaskServices, type DocumentResult, type NodeResult, type TaskSummary, type TaskView, } from "./services.ts";
+export { assertNodeTransition, assertTaskGroupTransition, assertTaskTransition, } from "./transitions.ts";

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { publicOperationNames, validatePublicInput, } from "./contracts.js";
+export * from "./model.js";
+export { createTaskServices, } from "./services.js";
+export { assertNodeTransition, assertTaskGroupTransition, assertTaskTransition, } from "./transitions.js";

package/dist/src/model.d.ts

@@ -0,0 +1,189 @@
+export declare const requiredTaskAgentPackageRefs: readonly ["@tomflow/proflow-agent-product", "@tomflow/proflow-agent-controller-dev", "@tomflow/proflow-agent-test-ops"];
+export type TaskGroupStatus = "READY" | "ACTIVE" | "SUCCEEDED";
+export type TaskStatus = "PENDING" | "READY" | "ACTIVE" | "WAITING" | "FAILED" | "PAUSED" | "SUCCEEDED" | "TERMINATED";
+export type NodeStatus = "PENDING" | "READY" | "IN_PROGRESS" | "WAITING" | "FAILED" | "SUCCEEDED" | "TERMINATED";
+export interface TaskGroup {
+    taskGroupId: string;
+    title: string;
+    objective: string | null;
+    status: TaskGroupStatus;
+    maxActiveTasks: 1;
+    version: number;
+    createdByRef: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Task {
+    taskId: string;
+    taskGroupId: string | null;
+    sequenceNo: number | null;
+    title: string;
+    objective: string;
+    status: TaskStatus;
+    version: number;
+    planVersion: number;
+    currentNodeId: string | null;
+    createdByRef: string;
+    createdAt: string;
+    startedAt: string | null;
+    completedAt: string | null;
+    updatedAt: string;
+}
+export interface TaskNode {
+    nodeId: string;
+    taskId: string;
+    sequenceNo: number;
+    title: string;
+    objective: string;
+    status: NodeStatus;
+    version: number;
+    runNo: number;
+    requiredAgentPackageRef: string;
+    workerRef: string | null;
+    inputDocuments: string[];
+    outputDocuments: string[];
+    resultSummary: string | null;
+    errorCode: string | null;
+    errorMessage: string | null;
+    errorRetryable: boolean | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    updatedAt: string;
+}
+export interface TaskRoleBinding {
+    taskId: string;
+    agentPackageRef: string;
+    roleRef: string;
+    workerRef: string | null;
+    conversationLocator: string | null;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface NodeExecutionHistory {
+    executionId?: number;
+    taskId: string;
+    nodeId: string;
+    runNo: number;
+    workerRef: string | null;
+    finalStatus: NodeStatus;
+    resultSummary: string | null;
+    errorCode: string | null;
+    errorMessage: string | null;
+    errorRetryable: boolean | null;
+    inputDocuments: string[];
+    outputDocuments: string[];
+    startedAt: string | null;
+    endedAt: string;
+}
+export interface TaskDocument {
+    taskId: string;
+    documentType: string;
+    sourceNodeId: string | null;
+    filePath: string;
+    contentHash: string;
+    updatedByRef: string;
+    updatedAt: string;
+}
+export interface TaskMessage {
+    messageId: string;
+    taskId: string;
+    nodeId: string | null;
+    messageType: string;
+    reasonCode: string;
+    message: string;
+    relatedRef: string | null;
+    status: "PENDING" | "ACKNOWLEDGED";
+    createdByRef: string;
+    createdAt: string;
+    acknowledgedByRef: string | null;
+    acknowledgedAt: string | null;
+    resolution: string | null;
+}
+export interface TaskEvent {
+    eventId?: number;
+    taskId: string;
+    nodeId: string | null;
+    eventType: string;
+    actorRef: string;
+    taskVersion: number | null;
+    nodeVersion: number | null;
+    payload: Record<string, unknown> | null;
+    createdAt: string;
+}
+export interface IdempotencyRecord {
+    idempotencyKey: string;
+    operation: string;
+    requestHash: string;
+    responseJson: string;
+    createdAt: string;
+}
+export interface TaskRepositories {
+    taskGroups: {
+        get(id: string): TaskGroup | undefined;
+        insert(value: TaskGroup): void;
+        update(value: TaskGroup): void;
+        list(): TaskGroup[];
+    };
+    tasks: {
+        get(id: string): Task | undefined;
+        insert(value: Task): void;
+        update(value: Task): void;
+        list(groupId?: string): Task[];
+    };
+    nodes: {
+        get(id: string): TaskNode | undefined;
+        insert(value: TaskNode): void;
+        update(value: TaskNode): void;
+        listByTask(taskId: string): TaskNode[];
+    };
+    roleBindings: {
+        get(taskId: string, agentPackageRef: string): TaskRoleBinding | undefined;
+        upsert(value: TaskRoleBinding): void;
+        listByTask(taskId: string): TaskRoleBinding[];
+    };
+    executionHistory: {
+        insert(value: NodeExecutionHistory): void;
+        listByTask(taskId: string): NodeExecutionHistory[];
+    };
+    documents: {
+        get(taskId: string, type: string): TaskDocument | undefined;
+        upsert(value: TaskDocument): void;
+        listByTask(taskId: string): TaskDocument[];
+    };
+    messages: {
+        get(id: string): TaskMessage | undefined;
+        insert(value: TaskMessage): void;
+        update(value: TaskMessage): void;
+        listPending(): TaskMessage[];
+    };
+    events: {
+        insert(value: TaskEvent): void;
+        listByTask(taskId: string): TaskEvent[];
+    };
+    idempotency: {
+        get(key: string): IdempotencyRecord | undefined;
+        insert(value: IdempotencyRecord): void;
+    };
+}
+export interface TaskStore {
+    transaction<T>(work: (repositories: TaskRepositories) => T): T;
+    read<T>(work: (repositories: TaskRepositories) => T): T;
+}
+export type TaskResult<T> = {
+    contract: "task-orchestration";
+    contractVersion: "1.0.0";
+    ok: true;
+    data: T;
+} | {
+    contract: "task-orchestration";
+    contractVersion: "1.0.0";
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+        correlationId: string;
+        details?: Record<string, unknown>;
+    };
+};

package/dist/src/model.js

@@ -0,0 +1,5 @@
+export const requiredTaskAgentPackageRefs = [
+    "@tomflow/proflow-agent-product",
+    "@tomflow/proflow-agent-controller-dev",
+    "@tomflow/proflow-agent-test-ops",
+];