@tomflow/proflow-task-orchestration 0.1.12 → 0.1.14

package/dist/src/product-document-path.d.ts

@@ -0,0 +1,2 @@
+/** Only owner-generated, flat Markdown files under the workspace are accepted. */
+export declare function productDocumentAbsolute(workspaceRoot: string, filePath: string): string;

package/dist/src/product-document-path.js

@@ -0,0 +1,24 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { resolve, sep } from "node:path";
+/** Only owner-generated, flat Markdown files under the workspace are accepted. */
+export function productDocumentAbsolute(workspaceRoot, filePath) {
+    if (!/^product-requirements\/[a-f0-9]{24}\.md$/.test(filePath))
+        throw new Error("PRODUCT_DOCUMENT_PATH_INVALID");
+    const workspace = realpathSync(workspaceRoot);
+    const directory = resolve(workspace, "product-requirements");
+    const absolute = resolve(workspace, filePath);
+    for (const path of [directory, absolute]) {
+        try {
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink() || (path === directory ? !stat.isDirectory() : !stat.isFile()))
+                throw new Error("PRODUCT_DOCUMENT_PATH_INVALID");
+            if (!realpathSync(path).startsWith(`${workspace}${sep}`))
+                throw new Error("PRODUCT_DOCUMENT_PATH_INVALID");
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+    }
+    return absolute;
+}

package/dist/src/services.d.ts

@@ -77,6 +77,7 @@ export interface CompleteNodeResult {
     nextNodeId: string | null;
 }
 export interface DocumentResult {
+    documentRef: string;
     taskId: string;
     nodeId: string | null;
     documentType: string;
@@ -84,6 +85,11 @@ export interface DocumentResult {
     contentHash: string;
     sizeBytes: number;
     taskVersion: number;
+    revision: number;
+    sourceNodeRunNo: number | null;
+    sourceDocumentRef: string | null;
+    sourceDocumentRevision: number | null;
+    updatedByRef: string;
     updatedAt: string;
     content?: string;
 }
@@ -150,10 +156,18 @@ export declare function createTaskServices(options: {
             task: Pick<Task, "taskId" | "title" | "objective" | "status" | "version">;
             node: Pick<TaskNode, "nodeId" | "title" | "objective" | "status" | "version" | "runNo" | "requiredAgentPackageRef" | "workerRef" | "inputDocuments" | "outputDocuments">;
             documents: Array<{
+                documentRef: string;
                 documentType: string;
                 path: string;
                 contentHash: string;
                 sizeBytes: number;
+                revision: number;
+                sourceNodeId: string | null;
+                sourceNodeRunNo: number | null;
+                sourceDocumentRef: string | null;
+                sourceDocumentRevision: number | null;
+                updatedByRef: string;
+                updatedAt: string;
             }>;
         }>;
         listPendingMessages: (raw: unknown) => TaskResult<{

package/dist/src/services.js

@@ -3,7 +3,7 @@ import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, rea
 import { dirname, join } from "node:path";
 import { ZodError } from "zod";
 import { validatePublicInput } from "./contracts.js";
-import { requiredTaskAgentPackageRefs } from "./model.js";
+import { requiredTaskAgentPackageRefs, taskDocumentRef } from "./model.js";
 const allowedDocumentTypes = [
     "REQUIREMENT",
     "PRD",
@@ -590,9 +590,14 @@ export function createTaskServices(options) {
                 for (const item of validated.initialDocuments) {
                     const path = relativeDocumentPath(taskId, item.documentType);
                     tx.documents.upsert({
+                        documentRef: taskDocumentRef(taskId, item.documentType),
                         taskId,
                         documentType: item.documentType,
                         sourceNodeId: null,
+                        sourceNodeRunNo: null,
+                        revision: 1,
+                        sourceDocumentRef: null,
+                        sourceDocumentRevision: null,
                         filePath: path,
                         contentHash: contentHash(item.content),
                         updatedByRef: validated.actorRef,
@@ -848,6 +853,12 @@ export function createTaskServices(options) {
                 const doc = tx.documents.get(task.taskId, type);
                 if (!doc || !existsSync(join(workspaceRoot, doc.filePath)))
                     throw new DomainError("NODE_OUTPUT_MISSING", "A required output document is missing.");
+                if (doc.documentRef !== taskDocumentRef(task.taskId, type) ||
+                    doc.sourceNodeId !== node.nodeId ||
+                    doc.sourceNodeRunNo !== node.runNo ||
+                    doc.updatedByRef !== input.actorRef ||
+                    doc.revision < 1)
+                    throw new DomainError("NODE_OUTPUT_EVIDENCE_INVALID", "A required output document is not evidence from the current Node run.");
                 if (contentHash(readFileSync(join(workspaceRoot, doc.filePath), "utf8")) !== doc.contentHash)
                     throw new DomainError("DOCUMENT_INDEX_MISMATCH", "A required output document does not match its index.");
             }
@@ -1199,10 +1210,18 @@ export function createTaskServices(options) {
                 .map((type) => tx.documents.get(task.taskId, type))
                 .filter((item) => item !== undefined)
                 .map((document) => ({
+                documentRef: document.documentRef,
                 documentType: document.documentType,
                 path: document.filePath,
                 contentHash: document.contentHash,
                 sizeBytes: statSync(join(workspaceRoot, document.filePath)).size,
+                revision: document.revision,
+                sourceNodeId: document.sourceNodeId,
+                sourceNodeRunNo: document.sourceNodeRunNo,
+                sourceDocumentRef: document.sourceDocumentRef,
+                sourceDocumentRevision: document.sourceDocumentRevision,
+                updatedByRef: document.updatedByRef,
+                updatedAt: document.updatedAt,
             }));
             return {
                 task: {
@@ -1247,6 +1266,7 @@ export function createTaskServices(options) {
             const content = readFileSync(join(workspaceRoot, document.filePath), "utf8");
             const task = requireTask(tx, input.taskId);
             return {
+                documentRef: document.documentRef,
                 taskId: input.taskId,
                 nodeId: document.sourceNodeId,
                 documentType: type,
@@ -1254,6 +1274,11 @@ export function createTaskServices(options) {
                 contentHash: document.contentHash,
                 sizeBytes: statSync(join(workspaceRoot, document.filePath)).size,
                 taskVersion: task.version,
+                revision: document.revision,
+                sourceNodeRunNo: document.sourceNodeRunNo,
+                sourceDocumentRef: document.sourceDocumentRef,
+                sourceDocumentRevision: document.sourceDocumentRevision,
+                updatedByRef: document.updatedByRef,
                 updatedAt: document.updatedAt,
                 content,
             };
@@ -1301,9 +1326,23 @@ export function createTaskServices(options) {
             const result = command("putTaskDocument", raw, (tx, validated, timestamp) => {
                 const task = requireTask(tx, validated.taskId);
                 checkVersion(task.version, validated.expectedTaskVersion, "TASK_VERSION_CONFLICT");
-                if (validated.nodeId !== null)
-                    requireNode(tx, task.taskId, validated.nodeId);
                 const validatedType = ensureType(validated.documentType);
+                let sourceNodeRunNo = null;
+                if (validated.nodeId !== null) {
+                    const producer = requireNode(tx, task.taskId, validated.nodeId);
+                    if (task.status !== "ACTIVE" ||
+                        task.currentNodeId !== producer.nodeId ||
+                        producer.status !== "IN_PROGRESS")
+                        throw new DomainError("NODE_NOT_CURRENT", "Only the current IN_PROGRESS Node may produce Task evidence.");
+                    if (!matchesWorker(validated.actorRef, producer.workerRef))
+                        throw new DomainError("WORKER_MISMATCH", "Only the bound current Worker may produce Task evidence.");
+                    if (!producer.outputDocuments.includes(validatedType))
+                        throw new DomainError("NODE_OUTPUT_DOCUMENT_NOT_DECLARED", "Document type is not declared as an output of the current Node.");
+                    sourceNodeRunNo = producer.runNo;
+                }
+                else if (task.status !== "PENDING") {
+                    throw new DomainError("TASK_INVALID_STATE", "Node-less Task documents can only be written while the Task is PENDING.");
+                }
                 const path = relativeDocumentPath(task.taskId, validatedType);
                 const staged = `${documentUpdateRecoveryPath(task.taskId, validatedType, validated.idempotencyKey)}/next.md`;
                 // BEGIN IMMEDIATE + optimistic version validation happens before the
@@ -1317,10 +1356,18 @@ export function createTaskServices(options) {
                     updatedAt: timestamp,
                 };
                 tx.tasks.update(updated);
+                const currentDocument = tx.documents.get(task.taskId, validatedType);
+                const documentRevision = (currentDocument?.revision ?? 0) + 1;
+                const documentRef = taskDocumentRef(task.taskId, validatedType);
                 tx.documents.upsert({
+                    documentRef,
                     taskId: task.taskId,
                     documentType: validatedType,
                     sourceNodeId: validated.nodeId,
+                    sourceNodeRunNo,
+                    revision: documentRevision,
+                    sourceDocumentRef: null,
+                    sourceDocumentRevision: null,
                     filePath: path,
                     contentHash: contentHash(validated.content),
                     updatedByRef: validated.actorRef,
@@ -1336,9 +1383,15 @@ export function createTaskServices(options) {
                     actorRef: validated.actorRef,
                     taskVersion: readied.version,
                     nodeVersion: null,
-                    payload: { documentType: validatedType },
+                    payload: {
+                        documentType: validatedType,
+                        documentRef,
+                        revision: documentRevision,
+                        sourceNodeRunNo,
+                    },
                 }, timestamp);
                 return {
+                    documentRef,
                     taskId: task.taskId,
                     nodeId: validated.nodeId,
                     documentType: validatedType,
@@ -1346,6 +1399,11 @@ export function createTaskServices(options) {
                     contentHash: contentHash(validated.content),
                     sizeBytes: Buffer.byteLength(validated.content),
                     taskVersion: readied.version,
+                    revision: documentRevision,
+                    sourceNodeRunNo,
+                    sourceDocumentRef: null,
+                    sourceDocumentRevision: null,
+                    updatedByRef: validated.actorRef,
                     updatedAt: timestamp,
                 };
             });
@@ -1373,31 +1431,16 @@ export function createTaskServices(options) {
                         promoteDocument(staged, relativeDocumentPath(input.taskId, type));
                 }
                 cleanupCreateStage(input.taskId);
-                const result = store.transaction((tx) => {
+                const result = store.read((tx) => {
                     requireTask(tx, input.taskId);
-                    let reconciled = 0;
-                    for (const type of allowedDocumentTypes) {
-                        const path = relativeDocumentPath(input.taskId, type);
-                        const absolute = join(workspaceRoot, path);
+                    for (const document of tx.documents.listByTask(input.taskId)) {
+                        const absolute = join(workspaceRoot, document.filePath);
                         if (!existsSync(absolute))
-                            continue;
-                        const content = readFileSync(absolute, "utf8");
-                        const current = tx.documents.get(input.taskId, type);
-                        const digest = contentHash(content);
-                        if (!current || current.contentHash !== digest) {
-                            tx.documents.upsert({
-                                taskId: input.taskId,
-                                documentType: type,
-                                sourceNodeId: current?.sourceNodeId ?? null,
-                                filePath: path,
-                                contentHash: digest,
-                                updatedByRef: input.actorRef,
-                                updatedAt: now(),
-                            });
-                            reconciled++;
-                        }
+                            throw new DomainError("DOCUMENT_INDEX_MISMATCH", "Canonical Task document is missing.");
+                        if (contentHash(readFileSync(absolute, "utf8")) !== document.contentHash)
+                            throw new DomainError("DOCUMENT_INDEX_MISMATCH", "Canonical Task document does not match durable evidence metadata.");
                     }
-                    return { reconciled };
+                    return { reconciled: 0 };
                 });
                 return success(result);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-task-orchestration",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -23,9 +23,9 @@
     "@tomflow/proflow-module-contract": "^0.1.13"
   },
   "devDependencies": {
-    "@tomflow/proflow-deployment-conformance": "^0.1.13",
+    "@tomflow/proflow-task-store-sqlite": "^0.1.13",
     "@tomflow/proflow-task-migration-runner": "^0.1.11",
-    "@tomflow/proflow-task-store-sqlite": "^0.1.12"
+    "@tomflow/proflow-deployment-conformance": "^0.1.13"
   },
   "description": "Owns the Task & Orchestration public contract, domain rules and application services.",
   "keywords": [

package/proflow.module.json

@@ -3,7 +3,7 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "task-orchestration",
 	"packageName": "@tomflow/proflow-task-orchestration",
-	"moduleVersion": "0.1.12",
+	"moduleVersion": "0.1.14",
 	"kind": "library",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",