@tomflow/proflow-task-orchestration 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @tomflow/proflow-task-orchestration
 
+## 0.1.13
+
+### Patch Changes
+
+- test(release): align current task and role contracts
+
+## 0.1.12
+
+### Patch Changes
+
+- Prune empty Task-level document recovery directories after recovery journals converge so durable recovery leaves no orphan filesystem residue.
+
+- Harden Task-scoped Worker identity and generation semantics so reopened or invalidated executions cannot reuse stale Worker/conversation ownership or a previously consumed run generation.
+
 ## 0.1.11
 
 ### Patch Changes

package/dist/deployment/adapter.d.ts

@@ -4,7 +4,7 @@ declare const success: () => {
         readonly ok: true;
         readonly status: "SUCCEEDED";
         readonly moduleRef: "task-orchestration";
-        readonly moduleVersion: "0.1.11";
+        readonly moduleVersion: "0.1.13";
     };
     observedEffects: string[];
 };
@@ -17,7 +17,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "task-orchestration";
-            moduleVersion: "0.1.11";
+            moduleVersion: "0.1.13";
             data: {
                 setupStatus: "READY";
                 runtimeStatus: "NOT_APPLICABLE";
@@ -32,7 +32,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "task-orchestration";
-            moduleVersion: "0.1.11";
+            moduleVersion: "0.1.13";
             data: {
                 docs: string;
             };

package/dist/deployment/descriptor.d.ts

@@ -3,7 +3,7 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "task-orchestration";
     readonly packageName: "@tomflow/proflow-task-orchestration";
-    readonly moduleVersion: "0.1.11";
+    readonly moduleVersion: "0.1.13";
     readonly kind: "library";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";

package/dist/deployment/descriptor.js

@@ -3,7 +3,7 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "task-orchestration",
     packageName: "@tomflow/proflow-task-orchestration",
-    moduleVersion: "0.1.11",
+    moduleVersion: "0.1.13",
     kind: "library",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/dist/src/contracts.js

@@ -98,6 +98,14 @@ const schemas = {
                 path: ["sequenceNo"],
             });
         }
+        input.roleBindings.forEach((binding, index) => {
+            if (binding.workerRef !== null || binding.conversationLocator !== null)
+                context.addIssue({
+                    code: "custom",
+                    message: "createTask roleBindings must start with workerRef and conversationLocator unset",
+                    path: ["roleBindings", index],
+                });
+        });
         const declaredAgentPackageRefs = new Set(input.roleBindings.map((binding) => binding.agentPackageRef));
         if (declaredAgentPackageRefs.size !== requiredTaskAgentPackageRefs.length ||
             requiredTaskAgentPackageRefs.some((agentPackageRef) => !declaredAgentPackageRefs.has(agentPackageRef))) {

package/dist/src/index.d.ts

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

package/dist/src/index.js

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

package/dist/src/phase4-continuation-services.d.ts

@@ -0,0 +1,127 @@
+import type { CampaignAuthorization, ProductCampaign, ProductDocument, ProductIntent } from "./phase4-model.ts";
+import type { Task, TaskResult } from "./model.ts";
+import { createTaskServices as createPhase4TaskServices, type DocumentResult, type NodeResult, type TaskSummary, type TaskView } from "./phase4-services.ts";
+export type { DocumentResult, NodeResult, TaskSummary, TaskView } from "./phase4-services.ts";
+type ServiceOptions = Parameters<typeof createPhase4TaskServices>[0];
+type AuthorizationProjection = Pick<CampaignAuthorization, "authorizationRef" | "version">;
+type ContinuationProjection = {
+    campaign: ProductCampaign;
+    intent: ProductIntent | null;
+    task: {
+        taskId: string;
+        status: Task["status"];
+        version: number;
+    } | null;
+    authorization: AuthorizationProjection | null;
+    requirementRevision: number | null;
+    nextAction: "NONE" | "PROVISION" | "TRANSFER_REQUIREMENT" | "CONSIDER_START" | "PRODUCT_REVIEW_REQUIRED";
+};
+type ProductDocumentRead = ProductDocument & {
+    content: string;
+};
+export declare function createTaskServices(options: ServiceOptions): {
+    documents: {
+        putTaskDocument: (raw: unknown) => TaskResult<DocumentResult>;
+        reconcileDocumentIndex: (input: {
+            taskId: string;
+            actorRef: string;
+        }) => TaskResult<{
+            reconciled: number;
+        }>;
+    };
+    commands: {
+        createTaskGroup: (raw: unknown) => TaskResult<import("./model.ts").TaskGroup>;
+        startTaskGroup: (raw: unknown) => TaskResult<import("./model.ts").TaskGroup & {
+            firstEligibleTaskId: string | null;
+        }>;
+        createTask: (raw: unknown) => TaskResult<import("./services.ts").CreateTaskResult>;
+        bindTaskWorker: (raw: unknown) => TaskResult<import("./services.ts").BindTaskWorkerResult>;
+        pauseTask: (raw: unknown) => TaskResult<Task>;
+        resumeTask: (raw: unknown) => TaskResult<Task>;
+        terminateTask: (raw: unknown) => TaskResult<Task>;
+        startNode: (raw: unknown) => TaskResult<NodeResult>;
+        completeNode: (raw: unknown) => TaskResult<import("./services.ts").CompleteNodeResult>;
+        waitNode: (raw: unknown) => TaskResult<Task>;
+        failNode: (raw: unknown) => TaskResult<Task>;
+        reopenNode: (raw: unknown) => TaskResult<NodeResult & {
+            currentNodeId: string;
+        }>;
+        acknowledgeMessage: (raw: unknown) => TaskResult<import("./model.ts").TaskMessage>;
+        createCampaignAuthorization: (raw: unknown) => TaskResult<{
+            campaign: ProductCampaign;
+            authorization: CampaignAuthorization;
+        }>;
+        revokeCampaignAuthorization: (raw: unknown) => TaskResult<CampaignAuthorization>;
+        submitProductTaskIntent: (raw: unknown) => TaskResult<{
+            intentRef: string;
+            campaignRef: string | null;
+            taskId: string;
+            status: Task["status"];
+            version: number;
+            roleBindings: Array<{
+                agentPackageRef: string;
+                roleRef: string;
+                workerRef: null;
+                conversationLocator: null;
+            }>;
+        }>;
+        transferProductIntentToTask: (raw: unknown) => TaskResult<TaskView>;
+        recordProductGapReview: (raw: unknown) => TaskResult<import("./phase4-model.ts").ProductGapReview>;
+        recordProductGoalSatisfied: (raw: unknown) => TaskResult<ProductCampaign>;
+        startTask: (raw: unknown) => TaskResult<TaskView>;
+        putProductDocument: (raw: unknown) => TaskResult<ProductDocumentRead>;
+    };
+    queries: {
+        getTaskGroup: (raw: unknown) => TaskResult<import("./model.ts").TaskGroup & {
+            currentTaskId: string | null;
+            tasks: Task[];
+        }>;
+        listTasks: (raw: unknown) => TaskResult<{
+            tasks: TaskSummary[];
+        }>;
+        getTask: (raw: unknown) => TaskResult<TaskView>;
+        getTaskDriveProjection: (raw: unknown) => TaskResult<{
+            taskId: string;
+            taskStatus: Task["status"];
+            taskVersion: number;
+            terminal: boolean;
+            currentNode: {
+                nodeId: string;
+                status: import("./model.ts").NodeStatus;
+                version: number;
+                runNo: number;
+                requiredAgentPackageRef: string;
+            } | null;
+            roleBinding: {
+                agentPackageRef: string;
+                roleRef: string;
+                workerRef: string | null;
+                conversationLocator: string | null;
+            } | null;
+            canDrive: boolean;
+            blockedReason: string | null;
+            resumeSignalRef: string | null;
+        }>;
+        getNodeContext: (raw: unknown) => TaskResult<{
+            task: Pick<Task, "taskId" | "title" | "objective" | "status" | "version">;
+            node: Pick<import("./model.ts").TaskNode, "nodeId" | "title" | "objective" | "status" | "version" | "runNo" | "requiredAgentPackageRef" | "workerRef" | "inputDocuments" | "outputDocuments">;
+            documents: Array<{
+                documentType: string;
+                path: string;
+                contentHash: string;
+                sizeBytes: number;
+            }>;
+        }>;
+        listPendingMessages: (raw: unknown) => TaskResult<{
+            messages: import("./model.ts").TaskMessage[];
+        }>;
+        listTaskEvents: (raw: unknown) => TaskResult<{
+            events: import("./model.ts").TaskEvent[];
+        }>;
+        getTaskDocument: (raw: unknown) => TaskResult<DocumentResult>;
+        getProductCampaign: (raw: unknown) => TaskResult<ProductCampaign>;
+        getCampaignAuthorization: (raw: unknown) => TaskResult<CampaignAuthorization>;
+        getProductDocument: (raw: unknown) => TaskResult<ProductDocumentRead>;
+        getProductContinuationProjection: (raw: unknown) => TaskResult<ContinuationProjection>;
+    };
+};

package/dist/src/phase4-continuation-services.js

@@ -0,0 +1,296 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import { productDocumentAbsolute as safeProductDocumentAbsolute } from "./product-document-path.js";
+import { ZodError } from "zod";
+import { validatePublicInput } from "./phase4-contracts.js";
+import { createTaskServices as createPhase4TaskServices, } from "./phase4-services.js";
+class ProjectionError extends Error {
+    code;
+    retryable;
+    constructor(code, retryable = false) {
+        super(code);
+        this.code = code;
+        this.retryable = retryable;
+    }
+}
+const success = (data) => ({
+    contract: "task-orchestration",
+    contractVersion: "1.0.0",
+    ok: true,
+    data,
+});
+const failure = (error) => ({
+    contract: "task-orchestration",
+    contractVersion: "1.0.0",
+    ok: false,
+    error: {
+        code: error instanceof ProjectionError
+            ? error.code
+            : error instanceof ZodError
+                ? "INVALID_REQUEST"
+                : "INTERNAL_ERROR",
+        message: error instanceof Error ? error.message : "unexpected error",
+        retryable: error instanceof ProjectionError ? error.retryable : false,
+        correlationId: `corr-${randomUUID()}`,
+    },
+});
+function ownerStore(store) {
+    const candidate = store;
+    if (typeof candidate.phase4Read !== "function" ||
+        typeof candidate.phase4Transaction !== "function")
+        throw new ProjectionError("PHASE4_OWNER_STORE_REQUIRED");
+    return candidate;
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value !== null && typeof value === "object")
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => [key, canonical(item)]));
+    return value;
+}
+function requestHash(value) {
+    return `sha256:${createHash("sha256")
+        .update(JSON.stringify(canonical(value)))
+        .digest("hex")}`;
+}
+function contentHash(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function productDocumentPath(documentRef) {
+    return `product-requirements/${createHash("sha256")
+        .update(documentRef)
+        .digest("hex")
+        .slice(0, 24)}.md`;
+}
+function productDocumentAbsolute(workspaceRoot, filePath) {
+    try {
+        return safeProductDocumentAbsolute(workspaceRoot, filePath);
+    }
+    catch {
+        throw new ProjectionError("PRODUCT_DOCUMENT_PATH_INVALID");
+    }
+}
+function atomicWrite(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.tmp-${randomUUID()}`;
+    try {
+        writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
+function readProductDocumentContent(workspaceRoot, document) {
+    const absolute = productDocumentAbsolute(workspaceRoot, document.filePath);
+    if (!existsSync(absolute))
+        throw new ProjectionError("PRODUCT_DOCUMENT_NOT_FOUND");
+    const content = readFileSync(absolute, "utf8");
+    if (contentHash(content) !== document.contentHash)
+        throw new ProjectionError("PRODUCT_DOCUMENT_INDEX_MISMATCH");
+    return content;
+}
+export function createTaskServices(options) {
+    const base = createPhase4TaskServices(options);
+    const store = ownerStore(options.store);
+    const now = options.now ?? (() => new Date().toISOString());
+    const putProductDocument = (raw) => {
+        let input;
+        try {
+            input = validatePublicInput("putProductDocument", raw);
+        }
+        catch (error) {
+            return failure(error);
+        }
+        let writtenPath;
+        let previousContent;
+        let previousExisted = false;
+        try {
+            return store.phase4Transaction((tx) => {
+                const fingerprint = requestHash(input);
+                const prior = tx.idempotency.get(input.idempotencyKey);
+                if (prior) {
+                    if (prior.operation !== "putProductDocument" ||
+                        prior.requestHash !== fingerprint)
+                        throw new ProjectionError("IDEMPOTENCY_CONFLICT");
+                    return JSON.parse(prior.responseJson);
+                }
+                if (input.actorRef !== `product-discussion:${input.discussionRef}`)
+                    throw new ProjectionError("PRODUCT_DISCUSSION_MISMATCH");
+                const campaign = tx.productCampaigns.get(input.campaignRef);
+                if (!campaign)
+                    throw new ProjectionError("PRODUCT_CAMPAIGN_NOT_FOUND");
+                if (campaign.status !== "OPEN")
+                    throw new ProjectionError("PRODUCT_CAMPAIGN_CLOSED");
+                if (campaign.discussionRef !== input.discussionRef)
+                    throw new ProjectionError("PRODUCT_DISCUSSION_MISMATCH");
+                const current = tx.productDocuments.get(input.documentRef);
+                if (input.expectedRevision === 0) {
+                    if (current)
+                        throw new ProjectionError("PRODUCT_DOCUMENT_REVISION_CONFLICT", true);
+                }
+                else {
+                    if (!current)
+                        throw new ProjectionError("PRODUCT_DOCUMENT_NOT_FOUND");
+                    if (current.intentRef !== null)
+                        throw new ProjectionError("PRODUCT_DOCUMENT_ALREADY_BOUND");
+                    if (current.campaignRef !== input.campaignRef ||
+                        current.documentType !== input.documentType)
+                        throw new ProjectionError("PRODUCT_DOCUMENT_SCOPE_MISMATCH");
+                    if (current.revision !== input.expectedRevision)
+                        throw new ProjectionError("PRODUCT_DOCUMENT_REVISION_CONFLICT", true);
+                    readProductDocumentContent(options.workspaceRoot, current);
+                }
+                const filePath = current?.filePath ?? productDocumentPath(input.documentRef);
+                const absolute = productDocumentAbsolute(options.workspaceRoot, filePath);
+                previousExisted = existsSync(absolute);
+                previousContent = previousExisted ? readFileSync(absolute, "utf8") : undefined;
+                if (!current &&
+                    previousExisted &&
+                    previousContent !== undefined &&
+                    contentHash(previousContent) !== contentHash(input.content))
+                    throw new ProjectionError("PRODUCT_DOCUMENT_ORPHAN_CONFLICT");
+                atomicWrite(absolute, input.content);
+                writtenPath = absolute;
+                const document = {
+                    documentRef: input.documentRef,
+                    campaignRef: input.campaignRef,
+                    intentRef: null,
+                    documentType: input.documentType,
+                    filePath,
+                    contentHash: contentHash(input.content),
+                    revision: input.expectedRevision + 1,
+                    updatedByRef: input.actorRef,
+                    updatedAt: now(),
+                };
+                try {
+                    if (current)
+                        tx.productDocuments.update(document);
+                    else
+                        tx.productDocuments.insert(document);
+                }
+                catch (error) {
+                    if (error instanceof Error &&
+                        error.message === "PRODUCT_DOCUMENT_REVISION_CONFLICT")
+                        throw new ProjectionError("PRODUCT_DOCUMENT_REVISION_CONFLICT", true);
+                    throw error;
+                }
+                const result = success({ ...document, content: input.content });
+                tx.idempotency.insert({
+                    idempotencyKey: input.idempotencyKey,
+                    operation: "putProductDocument",
+                    requestHash: fingerprint,
+                    responseJson: JSON.stringify(result),
+                    createdAt: now(),
+                });
+                return result;
+            });
+        }
+        catch (error) {
+            if (writtenPath) {
+                try {
+                    if (previousExisted && previousContent !== undefined)
+                        atomicWrite(writtenPath, previousContent);
+                    else
+                        rmSync(writtenPath, { force: true });
+                }
+                catch {
+                    return failure(new ProjectionError("PRODUCT_DOCUMENT_RECOVERY_REQUIRED"));
+                }
+            }
+            return failure(error);
+        }
+    };
+    const getProductDocument = (raw) => {
+        try {
+            const input = validatePublicInput("getProductDocument", raw);
+            return success(store.phase4Read((tx) => {
+                const document = tx.productDocuments.get(input.documentRef);
+                if (!document)
+                    throw new ProjectionError("PRODUCT_DOCUMENT_NOT_FOUND");
+                const campaign = tx.productCampaigns.get(document.campaignRef);
+                if (document.campaignRef !== input.campaignRef || campaign?.discussionRef !== input.discussionRef)
+                    throw new ProjectionError("PRODUCT_DISCUSSION_MISMATCH");
+                return {
+                    ...document,
+                    content: readProductDocumentContent(options.workspaceRoot, document),
+                };
+            }));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    };
+    const getProductContinuationProjection = (raw) => {
+        try {
+            const input = validatePublicInput("getProductContinuationProjection", raw);
+            const ownerFacts = store.phase4Read((tx) => {
+                const taskLink = input.taskId ? tx.taskProductLinks.get(input.taskId) : undefined;
+                if (input.taskId && !taskLink?.campaignRef)
+                    throw new ProjectionError("PRODUCT_CAMPAIGN_NOT_FOUND");
+                if (input.campaignRef !== undefined &&
+                    taskLink?.campaignRef !== undefined &&
+                    taskLink.campaignRef !== null &&
+                    taskLink.campaignRef !== input.campaignRef)
+                    throw new ProjectionError("PRODUCT_CAMPAIGN_TASK_MISMATCH");
+                const campaignRef = input.campaignRef ?? taskLink?.campaignRef;
+                if (!campaignRef)
+                    throw new ProjectionError("PRODUCT_CAMPAIGN_NOT_FOUND");
+                const campaign = tx.productCampaigns.get(campaignRef);
+                if (!campaign)
+                    throw new ProjectionError("PRODUCT_CAMPAIGN_NOT_FOUND");
+                const authorization = campaign.status === "OPEN"
+                    ? tx.campaignAuthorizations
+                        .listByCampaign(campaignRef)
+                        .filter((candidate) => candidate.revokedAt === null &&
+                        candidate.discussionRef === campaign.discussionRef &&
+                        candidate.goalRevision === campaign.goalRevision)
+                        .at(-1) ?? null
+                    : null;
+                return { campaignRef, authorization };
+            });
+            const baseResult = base.queries.getProductContinuationProjection({
+                campaignRef: ownerFacts.campaignRef,
+                ...(input.taskId ? { taskId: input.taskId } : {}),
+            });
+            if (!baseResult.ok)
+                return baseResult;
+            const requirementRevision = baseResult.data.intent
+                ? store.phase4Read((tx) => tx.productDocuments
+                    .listByIntent(baseResult.data.intent?.intentRef ?? "")
+                    .filter((document) => document.documentType === "REQUIREMENT")
+                    .sort((left, right) => left.revision - right.revision)
+                    .at(-1)?.revision ?? null)
+                : null;
+            return success({
+                ...baseResult.data,
+                authorization: ownerFacts.authorization
+                    ? {
+                        authorizationRef: ownerFacts.authorization.authorizationRef,
+                        version: ownerFacts.authorization.version,
+                    }
+                    : null,
+                requirementRevision,
+            });
+        }
+        catch (error) {
+            return failure(error);
+        }
+    };
+    return {
+        ...base,
+        commands: {
+            ...base.commands,
+            putProductDocument,
+        },
+        queries: {
+            ...base.queries,
+            getProductDocument,
+            getProductContinuationProjection,
+        },
+    };
+}

package/dist/src/phase4-contracts.d.ts

@@ -0,0 +1,5 @@
+export declare const phase4OperationNames: readonly ["createCampaignAuthorization", "getProductCampaign", "getCampaignAuthorization", "revokeCampaignAuthorization", "putProductDocument", "getProductDocument", "submitProductTaskIntent", "transferProductIntentToTask", "recordProductGapReview", "recordProductGoalSatisfied", "getProductContinuationProjection"];
+export type Phase4OperationName = (typeof phase4OperationNames)[number];
+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", "createCampaignAuthorization", "getProductCampaign", "getCampaignAuthorization", "revokeCampaignAuthorization", "putProductDocument", "getProductDocument", "submitProductTaskIntent", "transferProductIntentToTask", "recordProductGapReview", "recordProductGoalSatisfied", "getProductContinuationProjection"];
+export type PublicOperationName = (typeof publicOperationNames)[number];
+export declare function validatePublicInput(operation: PublicOperationName, input: unknown): unknown;