@tomflow/proflow-task-orchestration 0.1.11 → 0.1.13

package/dist/src/phase4-services.js

@@ -0,0 +1,809 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { productDocumentAbsolute } from "./product-document-path.js";
+import { ZodError } from "zod";
+import { validatePublicInput } from "./phase4-contracts.js";
+import { requiredTaskAgentPackageRefs } from "./model.js";
+import { createTaskServices as createLegacyTaskServices, } from "./services.js";
+class Phase4DomainError extends Error {
+    code;
+    retryable;
+    details;
+    constructor(code, message = code, retryable = false, details) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.details = details;
+    }
+}
+const success = (data) => ({
+    contract: "task-orchestration",
+    contractVersion: "1.0.0",
+    ok: true,
+    data,
+});
+const failure = (error) => {
+    const domain = error instanceof Phase4DomainError ? error : undefined;
+    return {
+        contract: "task-orchestration",
+        contractVersion: "1.0.0",
+        ok: false,
+        error: {
+            code: domain?.code ??
+                (error instanceof ZodError ? "INVALID_REQUEST" : "INTERNAL_ERROR"),
+            message: domain?.message ??
+                (error instanceof Error ? error.message : "unexpected error"),
+            retryable: domain?.retryable ?? false,
+            correlationId: `corr-${randomUUID()}`,
+            ...(domain?.details === undefined ? {} : { details: domain.details }),
+        },
+    };
+};
+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;
+}
+const stableJson = (value) => JSON.stringify(canonical(value));
+const hash = (value) => `sha256:${createHash("sha256").update(stableJson(value)).digest("hex")}`;
+const contentHash = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+const same = (left, right) => stableJson(left) === stableJson(right);
+function subsetOf(candidate, boundary) {
+    if (same(candidate, boundary))
+        return true;
+    if (Array.isArray(candidate) && Array.isArray(boundary))
+        return candidate.every((item) => boundary.some((allowed) => same(item, allowed)));
+    if (candidate !== null &&
+        boundary !== null &&
+        typeof candidate === "object" &&
+        typeof boundary === "object" &&
+        !Array.isArray(candidate) &&
+        !Array.isArray(boundary)) {
+        const allowed = boundary;
+        return Object.entries(candidate).every(([key, value]) => key in allowed && subsetOf(value, allowed[key]));
+    }
+    return false;
+}
+function findCost(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    for (const [key, item] of Object.entries(value)) {
+        if (key.toLowerCase() === "cost")
+            return item;
+        const nested = findCost(item);
+        if (nested !== undefined)
+            return nested;
+    }
+    return undefined;
+}
+const requiresZeroCost = (constraints) => {
+    const cost = findCost(constraints);
+    return cost === 0 || cost === "0";
+};
+function ownerStore(store) {
+    const candidate = store;
+    if (typeof candidate.phase4Transaction !== "function" ||
+        typeof candidate.phase4Read !== "function")
+        throw new Phase4DomainError("PHASE4_OWNER_STORE_REQUIRED", "Task Store does not expose Phase4 owner transactions.");
+    return candidate;
+}
+function checkVersion(actual, expected, code) {
+    if (actual !== expected)
+        throw new Phase4DomainError(code, "Version does not match.", true, {
+            expected,
+            actual,
+        });
+}
+function requireCampaign(tx, campaignRef) {
+    const value = tx.productCampaigns.get(campaignRef);
+    if (!value)
+        throw new Phase4DomainError("PRODUCT_CAMPAIGN_NOT_FOUND");
+    return value;
+}
+function requireIntent(tx, intentRef) {
+    const value = tx.productIntents.get(intentRef);
+    if (!value)
+        throw new Phase4DomainError("PRODUCT_INTENT_NOT_FOUND");
+    return value;
+}
+function requireAuthorization(tx, authorizationRef) {
+    const value = tx.campaignAuthorizations.get(authorizationRef);
+    if (!value)
+        throw new Phase4DomainError("CAMPAIGN_AUTHORIZATION_NOT_FOUND");
+    return value;
+}
+function requireTask(tx, taskId) {
+    const value = tx.tasks.get(taskId);
+    if (!value)
+        throw new Phase4DomainError("TASK_NOT_FOUND", `Task ${taskId} was not found.`);
+    return value;
+}
+function assertProductActor(actorRef, discussionRef) {
+    if (actorRef !== `product-discussion:${discussionRef}`)
+        throw new Phase4DomainError("PRODUCT_DISCUSSION_MISMATCH");
+}
+function assertGrantActor(actorRef) {
+    if (!actorRef.startsWith("human:") && !actorRef.startsWith("trusted:"))
+        throw new Phase4DomainError("TASK_START_AUTHORITY_INVALID");
+}
+function assertContinuationActor(actorRef) {
+    if (actorRef !== "platform:campaign-continuation")
+        throw new Phase4DomainError("TASK_START_AUTHORITY_INVALID");
+}
+function readinessBlockedReason(tx, task, workspaceRoot) {
+    const requirement = tx.documents.get(task.taskId, "REQUIREMENT");
+    if (!requirement)
+        return "TASK_REQUIREMENT_REQUIRED";
+    const absolute = join(workspaceRoot, requirement.filePath);
+    if (!existsSync(absolute))
+        return "TASK_REQUIREMENT_REQUIRED";
+    if (contentHash(readFileSync(absolute, "utf8")) !== requirement.contentHash)
+        return "TASK_DOCUMENT_INDEX_MISMATCH";
+    const bindings = tx.roleBindings.listByTask(task.taskId);
+    if (bindings.length !== requiredTaskAgentPackageRefs.length)
+        return "TASK_ROLE_BINDING_REQUIRED";
+    for (const packageRef of requiredTaskAgentPackageRefs) {
+        const binding = bindings.find((item) => item.agentPackageRef === packageRef);
+        if (!binding)
+            return "TASK_ROLE_BINDING_REQUIRED";
+        if (binding.workerRef === null || binding.conversationLocator === null)
+            return "TASK_ROLE_BINDING_INCOMPLETE";
+    }
+    if (tx.nodes
+        .listByTask(task.taskId)
+        .some((node) => !requiredTaskAgentPackageRefs.includes(node.requiredAgentPackageRef)))
+        return "TASK_NODE_AGENT_PACKAGE_INVALID";
+    if (task.taskGroupId !== null) {
+        const group = tx.taskGroups.get(task.taskGroupId);
+        if (group?.status !== "ACTIVE")
+            return "TASK_GROUP_NOT_ACTIVE";
+        const siblings = tx.tasks.list(task.taskGroupId);
+        if (siblings.some((item) => (item.sequenceNo ?? 0) < (task.sequenceNo ?? 0) && item.status !== "SUCCEEDED"))
+            return "PREDECESSOR_NOT_SUCCEEDED";
+        if (siblings.some((item) => item.taskId !== task.taskId &&
+            ["READY", "ACTIVE", "WAITING", "FAILED", "PAUSED"].includes(item.status)))
+            return "TASK_GROUP_BUSY";
+    }
+    return null;
+}
+function taskView(tx, task, workspaceRoot) {
+    return {
+        taskId: task.taskId,
+        taskGroupId: task.taskGroupId,
+        sequenceNo: task.sequenceNo,
+        title: task.title,
+        objective: task.objective,
+        status: task.status,
+        version: task.version,
+        planVersion: task.planVersion,
+        currentNodeId: task.currentNodeId,
+        nodes: tx.nodes.listByTask(task.taskId).map((node) => ({
+            nodeId: node.nodeId,
+            title: node.title,
+            status: node.status,
+            runNo: node.runNo,
+            requiredAgentPackageRef: node.requiredAgentPackageRef,
+            workerRef: node.workerRef,
+            version: node.version,
+        })),
+        roleBindings: tx.roleBindings.listByTask(task.taskId).map((binding) => ({
+            agentPackageRef: binding.agentPackageRef,
+            roleRef: binding.roleRef,
+            workerRef: binding.workerRef,
+            conversationLocator: binding.conversationLocator,
+        })),
+        pendingMessages: tx.messages
+            .listPending()
+            .filter((message) => message.taskId === task.taskId),
+        readiness: {
+            ready: task.status === "READY" &&
+                readinessBlockedReason(tx, task, workspaceRoot) === null,
+        },
+    };
+}
+export function createTaskServices(options) {
+    const legacy = createLegacyTaskServices(options);
+    const store = ownerStore(options.store);
+    const now = options.now ?? (() => new Date().toISOString());
+    const createId = options.createId ?? ((prefix) => `${prefix}-${randomUUID()}`);
+    function command(operation, raw, work) {
+        try {
+            const input = validatePublicInput(operation, raw);
+            return store.phase4Transaction((tx) => {
+                const requestHash = hash(input);
+                const prior = tx.idempotency.get(input.idempotencyKey);
+                if (prior) {
+                    if (prior.operation !== operation || prior.requestHash !== requestHash)
+                        throw new Phase4DomainError("IDEMPOTENCY_CONFLICT");
+                    return JSON.parse(prior.responseJson);
+                }
+                const timestamp = now();
+                const result = success(work(tx, input, timestamp));
+                tx.idempotency.insert({
+                    idempotencyKey: input.idempotencyKey,
+                    operation,
+                    requestHash,
+                    responseJson: JSON.stringify(result),
+                    createdAt: timestamp,
+                });
+                return result;
+            });
+        }
+        catch (error) {
+            return failure(error);
+        }
+    }
+    function query(operation, raw, work) {
+        try {
+            const input = validatePublicInput(operation, raw);
+            return success(store.phase4Read((tx) => work(tx, input)));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    }
+    const createCampaignAuthorization = (raw) => command("createCampaignAuthorization", raw, (tx, input, timestamp) => {
+        assertGrantActor(input.actorRef);
+        if (!requiresZeroCost(input.constraints))
+            throw new Phase4DomainError("CAMPAIGN_CONSTRAINT_VIOLATION");
+        let campaign = tx.productCampaigns.get(input.campaignRef);
+        if (!campaign) {
+            campaign = {
+                campaignRef: input.campaignRef,
+                discussionRef: input.discussionRef,
+                goalRevision: input.goalRevision,
+                goalSummary: input.goalSummary,
+                scope: input.scope,
+                constraints: input.constraints,
+                status: "OPEN",
+                version: 1,
+                createdByRef: input.actorRef,
+                createdAt: timestamp,
+                closedAt: null,
+                closureSummary: null,
+            };
+            tx.productCampaigns.insert(campaign);
+        }
+        else {
+            if (campaign.status !== "OPEN")
+                throw new Phase4DomainError("PRODUCT_CAMPAIGN_CLOSED");
+            if (campaign.discussionRef !== input.discussionRef ||
+                campaign.goalRevision !== input.goalRevision)
+                throw new Phase4DomainError("CAMPAIGN_GOAL_REVISION_MISMATCH");
+            if (!subsetOf(input.scope, campaign.scope))
+                throw new Phase4DomainError("CAMPAIGN_SCOPE_VIOLATION");
+            if (!same(input.constraints, campaign.constraints))
+                throw new Phase4DomainError("CAMPAIGN_CONSTRAINT_VIOLATION");
+        }
+        const authorizationRef = input.authorizationRef ??
+            createId(`authorization-${input.campaignRef.replaceAll(/[^A-Za-z0-9_-]/g, "-")}`);
+        if (tx.campaignAuthorizations.get(authorizationRef))
+            throw new Phase4DomainError("PRODUCT_INTENT_CONFLICT");
+        const authorization = {
+            authorizationRef,
+            campaignRef: campaign.campaignRef,
+            discussionRef: campaign.discussionRef,
+            goalRevision: campaign.goalRevision,
+            goalSummary: campaign.goalSummary,
+            scope: input.scope,
+            constraints: input.constraints,
+            version: 1,
+            createdByRef: input.actorRef,
+            createdAt: timestamp,
+            revokedAt: null,
+            revokedByRef: null,
+            revokeReason: null,
+        };
+        tx.campaignAuthorizations.insert(authorization);
+        return { campaign, authorization };
+    });
+    const revokeCampaignAuthorization = (raw) => command("revokeCampaignAuthorization", raw, (tx, input, timestamp) => {
+        assertGrantActor(input.actorRef);
+        const authorization = requireAuthorization(tx, input.authorizationRef);
+        checkVersion(authorization.version, input.expectedAuthorizationVersion, "CAMPAIGN_AUTHORIZATION_VERSION_CONFLICT");
+        if (authorization.revokedAt !== null)
+            throw new Phase4DomainError("CAMPAIGN_AUTHORIZATION_REVOKED");
+        const updated = {
+            ...authorization,
+            version: authorization.version + 1,
+            revokedAt: timestamp,
+            revokedByRef: input.actorRef,
+            revokeReason: input.reason,
+        };
+        tx.campaignAuthorizations.update(updated);
+        return updated;
+    });
+    const submitProductTaskIntent = (raw) => command("submitProductTaskIntent", raw, (tx, input, timestamp) => {
+        assertProductActor(input.actorRef, input.discussionRef);
+        if (input.campaignRef !== undefined) {
+            const campaign = requireCampaign(tx, input.campaignRef);
+            if (campaign.status !== "OPEN")
+                throw new Phase4DomainError("PRODUCT_CAMPAIGN_CLOSED");
+            checkVersion(campaign.version, input.expectedCampaignVersion, "PRODUCT_CAMPAIGN_VERSION_CONFLICT");
+            if (campaign.discussionRef !== input.discussionRef ||
+                campaign.goalRevision !== input.goalRevision)
+                throw new Phase4DomainError("CAMPAIGN_GOAL_REVISION_MISMATCH");
+            if (!subsetOf(input.scope, campaign.scope))
+                throw new Phase4DomainError("PRODUCT_INTENT_SCOPE_VIOLATION");
+            if (!same(input.constraints, campaign.constraints))
+                throw new Phase4DomainError("CAMPAIGN_CONSTRAINT_VIOLATION");
+        }
+        if (input.productDocuments.length > 0 && input.campaignRef === undefined)
+            throw new Phase4DomainError("PRODUCT_DOCUMENT_NOT_FOUND");
+        for (const supplied of input.productDocuments) {
+            const document = tx.productDocuments.get(supplied.documentRef);
+            if (!document)
+                throw new Phase4DomainError("PRODUCT_DOCUMENT_NOT_FOUND");
+            if (document.campaignRef !== input.campaignRef ||
+                (document.intentRef !== null && document.intentRef !== input.intentRef) ||
+                document.documentType !== supplied.documentType || document.filePath !== supplied.filePath ||
+                document.contentHash !== supplied.contentHash || document.revision !== supplied.revision)
+                throw new Phase4DomainError("PRODUCT_DOCUMENT_SCOPE_MISMATCH");
+            let absolute;
+            try {
+                absolute = productDocumentAbsolute(options.workspaceRoot, document.filePath);
+            }
+            catch {
+                throw new Phase4DomainError("PRODUCT_DOCUMENT_PATH_INVALID");
+            }
+            if (!existsSync(absolute) || contentHash(readFileSync(absolute, "utf8")) !== document.contentHash)
+                throw new Phase4DomainError("PRODUCT_DOCUMENT_INDEX_MISMATCH");
+        }
+        const existing = tx.productIntents.get(input.intentRef);
+        if (existing) {
+            const bindings = existing.materializedTaskId
+                ? tx.roleBindings.listByTask(existing.materializedTaskId)
+                : [];
+            const compatible = existing.materializedTaskId !== null &&
+                existing.campaignRef === (input.campaignRef ?? null) &&
+                existing.discussionRef === input.discussionRef &&
+                existing.goalRevision === input.goalRevision &&
+                existing.intentRevision === input.intentRevision &&
+                existing.predecessorTaskId === (input.predecessorTaskId ?? null) &&
+                existing.title === input.title &&
+                existing.objective === input.objective &&
+                same(existing.scope, input.scope) &&
+                same(existing.constraints, input.constraints) &&
+                same(existing.plan, input.plan) &&
+                bindings.length === input.roleBindings.length &&
+                input.roleBindings.every((binding) => bindings.some((current) => current.agentPackageRef === binding.agentPackageRef &&
+                    current.roleRef === binding.roleRef));
+            if (!compatible || !existing.materializedTaskId)
+                throw new Phase4DomainError("PRODUCT_INTENT_CONFLICT");
+            const existingTask = requireTask(tx, existing.materializedTaskId);
+            return {
+                intentRef: existing.intentRef,
+                campaignRef: existing.campaignRef,
+                taskId: existingTask.taskId,
+                status: existingTask.status,
+                version: existingTask.version,
+                roleBindings: bindings.map((binding) => ({
+                    agentPackageRef: binding.agentPackageRef,
+                    roleRef: binding.roleRef,
+                    workerRef: null,
+                    conversationLocator: null,
+                })),
+            };
+        }
+        if (input.predecessorTaskId !== undefined) {
+            if (input.campaignRef === undefined)
+                throw new Phase4DomainError("PRODUCT_INTENT_PREDECESSOR_INVALID");
+            const predecessor = requireTask(tx, input.predecessorTaskId);
+            const predecessorLink = tx.taskProductLinks.get(predecessor.taskId);
+            if (!["SUCCEEDED", "TERMINATED"].includes(predecessor.status) ||
+                predecessorLink?.campaignRef !== input.campaignRef ||
+                !predecessorLink.sourceProductIntentRef)
+                throw new Phase4DomainError("PRODUCT_INTENT_PREDECESSOR_INVALID");
+            const review = tx.productGapReviews.getByIntent(predecessorLink.sourceProductIntentRef);
+            if (!review || review.taskId !== predecessor.taskId)
+                throw new Phase4DomainError("PRODUCT_GAP_REVIEW_REQUIRED");
+            if (tx.productIntents
+                .listByCampaign(input.campaignRef)
+                .some((candidate) => candidate.intentRef !== input.intentRef &&
+                candidate.predecessorTaskId === predecessor.taskId))
+                throw new Phase4DomainError("PRODUCT_INTENT_CONFLICT");
+        }
+        const taskId = `task-${createHash("sha256")
+            .update(`${input.intentRef}\0${input.intentRevision}`)
+            .digest("hex")
+            .slice(0, 24)}`;
+        if (tx.tasks.get(taskId))
+            throw new Phase4DomainError("PRODUCT_INTENT_CONFLICT");
+        const materializedTask = {
+            taskId,
+            taskGroupId: null,
+            sequenceNo: null,
+            title: input.title,
+            objective: input.objective,
+            status: "PENDING",
+            version: 1,
+            planVersion: 1,
+            currentNodeId: null,
+            createdByRef: input.actorRef,
+            createdAt: timestamp,
+            startedAt: null,
+            completedAt: null,
+            updatedAt: timestamp,
+        };
+        tx.tasks.insert(materializedTask);
+        input.plan.nodes.forEach((node, index) => tx.nodes.insert({
+            nodeId: node.nodeId,
+            taskId,
+            sequenceNo: index + 1,
+            title: node.title,
+            objective: node.objective,
+            status: "PENDING",
+            version: 1,
+            runNo: 1,
+            requiredAgentPackageRef: node.requiredAgentPackageRef,
+            workerRef: null,
+            inputDocuments: node.inputDocuments,
+            outputDocuments: node.outputDocuments,
+            resultSummary: null,
+            errorCode: null,
+            errorMessage: null,
+            errorRetryable: null,
+            startedAt: null,
+            completedAt: null,
+            updatedAt: timestamp,
+        }));
+        for (const binding of input.roleBindings)
+            tx.roleBindings.upsert({
+                taskId,
+                agentPackageRef: binding.agentPackageRef,
+                roleRef: binding.roleRef,
+                workerRef: null,
+                conversationLocator: null,
+                version: 1,
+                createdAt: timestamp,
+                updatedAt: timestamp,
+            });
+        const intent = {
+            intentRef: input.intentRef,
+            campaignRef: input.campaignRef ?? null,
+            discussionRef: input.discussionRef,
+            goalRevision: input.goalRevision,
+            intentRevision: input.intentRevision,
+            predecessorTaskId: input.predecessorTaskId ?? null,
+            title: input.title,
+            objective: input.objective,
+            scope: input.scope,
+            constraints: input.constraints,
+            plan: input.plan,
+            materializedTaskId: taskId,
+            version: 1,
+            createdByRef: input.actorRef,
+            createdAt: timestamp,
+            materializedAt: timestamp,
+        };
+        tx.productIntents.insert(intent);
+        tx.taskProductLinks.set({
+            taskId,
+            sourceProductIntentRef: intent.intentRef,
+            campaignRef: intent.campaignRef,
+        });
+        for (const document of input.productDocuments)
+            tx.productDocuments.bindIntent({
+                documentRef: document.documentRef,
+                intentRef: input.intentRef,
+                expectedRevision: document.revision,
+            });
+        return {
+            intentRef: intent.intentRef,
+            campaignRef: intent.campaignRef,
+            taskId,
+            status: materializedTask.status,
+            version: materializedTask.version,
+            roleBindings: input.roleBindings.map((binding) => ({
+                ...binding,
+                workerRef: null,
+                conversationLocator: null,
+            })),
+        };
+    });
+    const transferProductIntentToTask = (raw) => command("transferProductIntentToTask", raw, (tx, input, timestamp) => {
+        assertContinuationActor(input.actorRef);
+        const intent = requireIntent(tx, input.intentRef);
+        checkVersion(intent.version, input.expectedIntentVersion, "PRODUCT_INTENT_REVISION_CONFLICT");
+        const current = requireTask(tx, input.taskId);
+        checkVersion(current.version, input.expectedTaskVersion, "TASK_VERSION_CONFLICT");
+        if (current.status !== "PENDING")
+            throw new Phase4DomainError("TASK_INVALID_STATE");
+        const link = tx.taskProductLinks.get(current.taskId);
+        if (intent.materializedTaskId !== current.taskId ||
+            link?.sourceProductIntentRef !== intent.intentRef ||
+            link.campaignRef !== intent.campaignRef)
+            throw new Phase4DomainError("PRODUCT_INTENT_TASK_MISMATCH");
+        const bindings = tx.roleBindings.listByTask(current.taskId);
+        if (bindings.length !== requiredTaskAgentPackageRefs.length ||
+            bindings.some((binding) => binding.workerRef === null || binding.conversationLocator === null))
+            throw new Phase4DomainError("TASK_ROLE_BINDING_INCOMPLETE");
+        const requirements = tx.productDocuments
+            .listByIntent(intent.intentRef)
+            .filter((document) => document.documentType === "REQUIREMENT");
+        if (requirements.length !== 1)
+            throw new Phase4DomainError(requirements.length === 0
+                ? "PRODUCT_DOCUMENT_NOT_FOUND"
+                : "PRODUCT_DOCUMENT_AMBIGUOUS");
+        const requirement = requirements[0];
+        if (!requirement)
+            throw new Phase4DomainError("PRODUCT_DOCUMENT_NOT_FOUND");
+        const absolute = join(options.workspaceRoot, requirement.filePath);
+        if (!existsSync(absolute) ||
+            contentHash(readFileSync(absolute, "utf8")) !== requirement.contentHash)
+            throw new Phase4DomainError("PRODUCT_DOCUMENT_INDEX_MISMATCH");
+        tx.documents.upsert({
+            taskId: current.taskId,
+            documentType: "REQUIREMENT",
+            sourceNodeId: null,
+            filePath: requirement.filePath,
+            contentHash: requirement.contentHash,
+            updatedByRef: input.actorRef,
+            updatedAt: timestamp,
+        });
+        const advancedIntent = {
+            ...intent,
+            version: intent.version + 1,
+        };
+        tx.productIntents.update(advancedIntent);
+        const blockedReason = readinessBlockedReason(tx, current, options.workspaceRoot);
+        if (blockedReason !== null)
+            throw new Phase4DomainError("TASK_BLOCKED", blockedReason);
+        const updated = {
+            ...current,
+            status: "READY",
+            version: current.version + 1,
+            updatedAt: timestamp,
+        };
+        tx.tasks.update(updated);
+        tx.events.insert({
+            taskId: updated.taskId,
+            nodeId: null,
+            eventType: "PRODUCT_REQUIREMENT_TRANSFERRED",
+            actorRef: input.actorRef,
+            taskVersion: updated.version,
+            nodeVersion: null,
+            payload: {
+                intentRef: intent.intentRef,
+                productDocumentRef: requirement.documentRef,
+            },
+            createdAt: timestamp,
+        });
+        return taskView(tx, updated, options.workspaceRoot);
+    });
+    const recordProductGapReview = (raw) => command("recordProductGapReview", raw, (tx, input, timestamp) => {
+        assertProductActor(input.actorRef, input.discussionRef);
+        const campaign = requireCampaign(tx, input.campaignRef);
+        if (campaign.status !== "OPEN")
+            throw new Phase4DomainError("PRODUCT_CAMPAIGN_CLOSED");
+        if (campaign.discussionRef !== input.discussionRef)
+            throw new Phase4DomainError("PRODUCT_DISCUSSION_MISMATCH");
+        const intent = requireIntent(tx, input.intentRef);
+        if (intent.goalRevision !== campaign.goalRevision)
+            throw new Phase4DomainError("CAMPAIGN_GOAL_REVISION_MISMATCH");
+        checkVersion(intent.version, input.expectedIntentVersion, "PRODUCT_INTENT_REVISION_CONFLICT");
+        const current = requireTask(tx, input.taskId);
+        checkVersion(current.version, input.terminalTaskVersion, "TASK_VERSION_CONFLICT");
+        const link = tx.taskProductLinks.get(current.taskId);
+        if (!["SUCCEEDED", "TERMINATED"].includes(current.status) ||
+            intent.campaignRef !== campaign.campaignRef ||
+            intent.discussionRef !== input.discussionRef ||
+            intent.materializedTaskId !== current.taskId ||
+            link?.sourceProductIntentRef !== intent.intentRef ||
+            link.campaignRef !== campaign.campaignRef)
+            throw new Phase4DomainError("PRODUCT_REVIEW_TASK_MISMATCH");
+        if (tx.productGapReviews.getByIntent(intent.intentRef))
+            throw new Phase4DomainError("PRODUCT_GAP_ALREADY_REVIEWED");
+        const priorSameGap = tx.productGapReviews
+            .listByCampaign(campaign.campaignRef)
+            .filter((review) => review.gapIdentity === input.gapIdentity);
+        if (priorSameGap.length > 0) {
+            const knownEvidence = new Set(priorSameGap.flatMap((review) => review.progressEvidenceRefs));
+            if (!input.progressEvidenceRefs.some((ref) => !knownEvidence.has(ref)))
+                throw new Phase4DomainError("PRODUCT_GAP_NO_PROGRESS");
+        }
+        const review = {
+            reviewRef: `product-review:${campaign.campaignRef}:${current.taskId}:${current.version}`,
+            campaignRef: campaign.campaignRef,
+            intentRef: intent.intentRef,
+            taskId: current.taskId,
+            discussionRef: input.discussionRef,
+            gapIdentity: input.gapIdentity,
+            progressEvidenceRefs: [...new Set(input.progressEvidenceRefs)],
+            terminalTaskVersion: current.version,
+            createdByRef: input.actorRef,
+            createdAt: timestamp,
+        };
+        tx.productGapReviews.insert(review);
+        tx.productIntents.update({
+            ...intent,
+            version: intent.version + 1,
+        });
+        return review;
+    });
+    const recordProductGoalSatisfied = (raw) => command("recordProductGoalSatisfied", raw, (tx, input, timestamp) => {
+        assertProductActor(input.actorRef, input.discussionRef);
+        const campaign = requireCampaign(tx, input.campaignRef);
+        checkVersion(campaign.version, input.expectedCampaignVersion, "PRODUCT_CAMPAIGN_VERSION_CONFLICT");
+        if (campaign.status !== "OPEN")
+            throw new Phase4DomainError("PRODUCT_CAMPAIGN_CLOSED");
+        if (campaign.discussionRef !== input.discussionRef ||
+            campaign.goalRevision !== input.goalRevision)
+            throw new Phase4DomainError("CAMPAIGN_GOAL_REVISION_MISMATCH");
+        const current = requireTask(tx, input.taskId);
+        checkVersion(current.version, input.terminalTaskVersion, "TASK_VERSION_CONFLICT");
+        const link = tx.taskProductLinks.get(current.taskId);
+        if (!["SUCCEEDED", "TERMINATED"].includes(current.status) ||
+            link?.campaignRef !== campaign.campaignRef ||
+            !link.sourceProductIntentRef)
+            throw new Phase4DomainError("PRODUCT_REVIEW_TASK_MISMATCH");
+        const intent = requireIntent(tx, link.sourceProductIntentRef);
+        if (intent.discussionRef !== input.discussionRef ||
+            intent.goalRevision !== campaign.goalRevision ||
+            intent.materializedTaskId !== current.taskId)
+            throw new Phase4DomainError("PRODUCT_REVIEW_TASK_MISMATCH");
+        if (tx.productIntents
+            .listByCampaign(campaign.campaignRef)
+            .some((candidate) => candidate.predecessorTaskId === current.taskId))
+            throw new Phase4DomainError("PRODUCT_REVIEW_ALREADY_CONTINUED");
+        // A terminal Task is evidence for review, not proof that all Campaign
+        // work has stopped. Closure must not strand another durable Task.
+        for (const candidate of tx.productIntents.listByCampaign(campaign.campaignRef)) {
+            if (!candidate.materializedTaskId ||
+                !["SUCCEEDED", "TERMINATED"].includes(requireTask(tx, candidate.materializedTaskId).status))
+                throw new Phase4DomainError("PRODUCT_CAMPAIGN_TASKS_NONTERMINAL");
+        }
+        const updated = {
+            ...campaign,
+            status: "CLOSED",
+            version: campaign.version + 1,
+            closedAt: timestamp,
+            closureSummary: input.closureSummary,
+        };
+        tx.productCampaigns.update(updated);
+        return updated;
+    });
+    const startTask = (raw) => {
+        let input;
+        try {
+            input = validatePublicInput("startTask", raw);
+        }
+        catch (error) {
+            return failure(error);
+        }
+        const authority = input.startAuthority;
+        if (authority === undefined || authority.type === "HUMAN_CONFIRMATION") {
+            const { startAuthority: _ignored, ...legacyInput } = input;
+            return legacy.commands.startTask(legacyInput);
+        }
+        const campaignAuthority = authority;
+        return command("startTask", input, (tx, validated, timestamp) => {
+            assertContinuationActor(validated.actorRef);
+            const current = requireTask(tx, validated.taskId);
+            checkVersion(current.version, validated.expectedTaskVersion, "TASK_VERSION_CONFLICT");
+            if (current.status !== "READY")
+                throw new Phase4DomainError("TASK_INVALID_STATE");
+            const blockedReason = readinessBlockedReason(tx, current, options.workspaceRoot);
+            if (blockedReason !== null)
+                throw new Phase4DomainError("TASK_BLOCKED", blockedReason);
+            const link = tx.taskProductLinks.get(current.taskId);
+            if (!link?.campaignRef || !link.sourceProductIntentRef)
+                throw new Phase4DomainError("TASK_START_AUTHORITY_INVALID");
+            const campaign = requireCampaign(tx, link.campaignRef);
+            checkVersion(campaign.version, campaignAuthority.expectedCampaignVersion, "PRODUCT_CAMPAIGN_VERSION_CONFLICT");
+            if (campaign.status !== "OPEN")
+                throw new Phase4DomainError("PRODUCT_CAMPAIGN_CLOSED");
+            const authorization = requireAuthorization(tx, campaignAuthority.authorizationRef);
+            checkVersion(authorization.version, campaignAuthority.expectedAuthorizationVersion, "CAMPAIGN_AUTHORIZATION_VERSION_CONFLICT");
+            if (authorization.revokedAt !== null)
+                throw new Phase4DomainError("CAMPAIGN_AUTHORIZATION_REVOKED");
+            if (authorization.campaignRef !== campaign.campaignRef)
+                throw new Phase4DomainError("TASK_START_AUTHORITY_INVALID");
+            const intent = tx.productIntents.get(link.sourceProductIntentRef);
+            if (!intent || intent.materializedTaskId !== current.taskId)
+                throw new Phase4DomainError("TASK_START_AUTHORITY_INVALID");
+            if (intent.goalRevision !== campaign.goalRevision ||
+                authorization.goalRevision !== campaign.goalRevision)
+                throw new Phase4DomainError("CAMPAIGN_GOAL_REVISION_MISMATCH");
+            if (!subsetOf(intent.scope, campaign.scope) ||
+                !subsetOf(intent.scope, authorization.scope))
+                throw new Phase4DomainError("CAMPAIGN_SCOPE_VIOLATION");
+            if (!same(intent.constraints, campaign.constraints) ||
+                !same(intent.constraints, authorization.constraints) ||
+                !requiresZeroCost(intent.constraints))
+                throw new Phase4DomainError("CAMPAIGN_CONSTRAINT_VIOLATION");
+            const first = tx.nodes.listByTask(current.taskId)[0];
+            if (!first)
+                throw new Phase4DomainError("TASK_PLAN_EMPTY");
+            tx.nodes.update({
+                ...first,
+                status: "READY",
+                version: first.version + 1,
+                updatedAt: timestamp,
+            });
+            const updated = {
+                ...current,
+                status: "ACTIVE",
+                version: current.version + 1,
+                currentNodeId: first.nodeId,
+                startedAt: timestamp,
+                updatedAt: timestamp,
+            };
+            tx.tasks.update(updated);
+            tx.events.insert({
+                taskId: current.taskId,
+                nodeId: null,
+                eventType: "TASK_STARTED",
+                actorRef: validated.actorRef,
+                taskVersion: updated.version,
+                nodeVersion: null,
+                payload: {
+                    startAuthority: "CAMPAIGN_AUTHORIZATION",
+                    authorizationRef: authorization.authorizationRef,
+                },
+                createdAt: timestamp,
+            });
+            return taskView(tx, updated, options.workspaceRoot);
+        });
+    };
+    const commands = {
+        ...legacy.commands,
+        createCampaignAuthorization,
+        revokeCampaignAuthorization,
+        submitProductTaskIntent,
+        transferProductIntentToTask,
+        recordProductGapReview,
+        recordProductGoalSatisfied,
+        startTask,
+    };
+    const queries = {
+        ...legacy.queries,
+        getProductCampaign: (raw) => query("getProductCampaign", raw, (tx, input) => requireCampaign(tx, input.campaignRef)),
+        getCampaignAuthorization: (raw) => query("getCampaignAuthorization", raw, (tx, input) => requireAuthorization(tx, input.authorizationRef)),
+        getProductContinuationProjection: (raw) => query("getProductContinuationProjection", raw, (tx, input) => {
+            const campaign = requireCampaign(tx, input.campaignRef);
+            const intents = tx.productIntents.listByCampaign(campaign.campaignRef);
+            const intent = (input.taskId
+                ? intents.find((candidate) => candidate.materializedTaskId === input.taskId)
+                : intents.at(-1)) ?? null;
+            const current = intent?.materializedTaskId
+                ? tx.tasks.get(intent.materializedTaskId) ?? null
+                : null;
+            let nextAction = "NONE";
+            if (campaign.status === "OPEN" && current) {
+                if (["SUCCEEDED", "TERMINATED"].includes(current.status)) {
+                    const continued = intents.some((candidate) => candidate.predecessorTaskId === current.taskId);
+                    // Catch-up scans include historical Tasks. A successor already owns
+                    // continuation; re-reviewing its predecessor rolls discussion context back.
+                    if (!continued)
+                        nextAction = "PRODUCT_REVIEW_REQUIRED";
+                }
+                else if (current.status === "PENDING") {
+                    const bindings = tx.roleBindings.listByTask(current.taskId);
+                    const complete = bindings.length === requiredTaskAgentPackageRefs.length &&
+                        bindings.every((binding) => binding.workerRef !== null && binding.conversationLocator !== null);
+                    if (!complete)
+                        nextAction = "PROVISION";
+                    else if (!tx.documents.get(current.taskId, "REQUIREMENT"))
+                        nextAction = "TRANSFER_REQUIREMENT";
+                }
+                if (current.status === "READY")
+                    nextAction = "CONSIDER_START";
+            }
+            return {
+                campaign,
+                intent,
+                task: current
+                    ? { taskId: current.taskId, status: current.status, version: current.version }
+                    : null,
+                nextAction,
+            };
+        }),
+    };
+    return { commands, queries, documents: legacy.documents };
+}