@zq-silk/yui 0.14.0 → 0.14.2

package/dist/execution/workItemExecution.js

@@ -0,0 +1,454 @@
+import { isDeepStrictEqual } from "node:util";
+import { normalizedUniqueIdentities, normalizedUniqueText, requireIdentity, requirePositiveInteger, requireText, requireTimestamp } from "../domain/validation.js";
+import { validateContextSnapshotRef } from "../context/contextSnapshot.js";
+import { validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
+import { MAX_SYNTHESIS_SOURCE_TURNS } from "../context/sourceTurnContext.js";
+export const WORK_ITEM_EXECUTION_GROUP_SCHEMA_VERSION = 2;
+export const WORK_ITEM_EXECUTION_LANE_SCHEMA_VERSION = 2;
+export const WORK_ITEM_EXECUTION_ASSIGNMENT_SCHEMA_VERSION = 1;
+export const MINIMUM_WORK_ITEM_SYNTHESIS_RESULTS = 2;
+export const EXECUTION_GROUP_SCHEMA_VERSION = WORK_ITEM_EXECUTION_GROUP_SCHEMA_VERSION;
+export const EXECUTION_LANE_SCHEMA_VERSION = WORK_ITEM_EXECUTION_LANE_SCHEMA_VERSION;
+export const EXECUTION_ASSIGNMENT_SCHEMA_VERSION = WORK_ITEM_EXECUTION_ASSIGNMENT_SCHEMA_VERSION;
+export const MINIMUM_SYNTHESIS_RESULTS = MINIMUM_WORK_ITEM_SYNTHESIS_RESULTS;
+export const MAXIMUM_SYNTHESIS_RESULTS = MAX_SYNTHESIS_SOURCE_TURNS;
+export function createWorkItemExecutionAssignment(input) {
+    return validateWorkItemExecutionAssignment({
+        schemaVersion: WORK_ITEM_EXECUTION_ASSIGNMENT_SCHEMA_VERSION,
+        ...input
+    });
+}
+export function createReviewExecutionAssignment(input) {
+    return validateReviewExecutionAssignment({
+        schemaVersion: EXECUTION_ASSIGNMENT_SCHEMA_VERSION,
+        ...input
+    });
+}
+export function createExecutionGroup(id, taskId, assignment, laneInputs, now) {
+    if (laneInputs.length < MINIMUM_SYNTHESIS_RESULTS) {
+        throw new Error("A replicated ExecutionGroup requires at least two Lanes.");
+    }
+    if (laneInputs.length > MAXIMUM_SYNTHESIS_RESULTS) {
+        throw new Error(`A replicated ExecutionGroup supports at most ${MAXIMUM_SYNTHESIS_RESULTS} Lanes.`);
+    }
+    const groupId = requireIdentity(id, "ExecutionGroup id");
+    const normalizedTaskId = requireIdentity(taskId, "Task id");
+    const frozenAssignment = validateExecutionAssignment(assignment);
+    if (frozenAssignment.taskId !== normalizedTaskId) {
+        throw new Error("ExecutionGroup Assignment belongs to another Task.");
+    }
+    const timestamp = now.toISOString();
+    return validateExecutionGroup({
+        schemaVersion: EXECUTION_GROUP_SCHEMA_VERSION,
+        id: groupId,
+        taskId: normalizedTaskId,
+        assignment: frozenAssignment,
+        lanes: laneInputs.map((lane, index) => ({
+            schemaVersion: EXECUTION_LANE_SCHEMA_VERSION,
+            id: `${groupId}-lane-${index + 1}`,
+            groupId,
+            ordinal: index + 1,
+            roleName: lane.roleName,
+            ...(lane.effective === undefined ? {} : { effective: lane.effective }),
+            ...(lane.workspace === undefined ? {} : { workspace: lane.workspace }),
+            ...(lane.currentTurnId === undefined ? {} : { currentTurnId: lane.currentTurnId }),
+            disposition: "open",
+            createdAt: timestamp,
+            updatedAt: timestamp
+        })),
+        createdAt: timestamp,
+        updatedAt: timestamp
+    });
+}
+export function createWorkItemExecutionGroup(id, taskId, assignment, laneInputs, now) {
+    const group = createExecutionGroup(id, taskId, assignment, laneInputs, now);
+    return validateWorkItemExecutionGroup(group);
+}
+export function updateExecutionLane(group, laneId, patch, now) {
+    validateExecutionGroup(group);
+    const index = group.lanes.findIndex(({ id }) => id === laneId);
+    if (index < 0)
+        throw new Error(`ExecutionGroup Lane not found: ${laneId}.`);
+    const current = group.lanes[index];
+    if (current.disposition !== "open") {
+        throw new Error(`Terminal ExecutionLane is immutable: ${laneId}.`);
+    }
+    const disposition = patch.disposition ?? current.disposition;
+    const currentTurnId = patch.currentTurnId ?? current.currentTurnId;
+    const successfulTurnId = patch.successfulTurnId ?? current.successfulTurnId;
+    const effective = patch.effective ?? current.effective;
+    const workspace = patch.workspace ?? current.workspace;
+    if ((effective === undefined) !== (workspace === undefined)) {
+        throw new Error("ExecutionLane launch facts are incomplete.");
+    }
+    if (disposition === "succeeded") {
+        if (successfulTurnId === undefined || successfulTurnId !== currentTurnId) {
+            throw new Error("A succeeded Lane must identify its current successful Turn.");
+        }
+    }
+    else if (successfulTurnId !== undefined) {
+        throw new Error("Only a succeeded Lane may identify a successful Turn.");
+    }
+    const timestamp = now.toISOString();
+    const updated = {
+        ...current,
+        ...(effective === undefined ? {} : { effective }),
+        ...(workspace === undefined ? {} : { workspace }),
+        ...(currentTurnId === undefined ? {} : { currentTurnId }),
+        ...(successfulTurnId === undefined ? {} : { successfulTurnId }),
+        disposition,
+        updatedAt: timestamp,
+        ...(disposition === "open" ? {} : { endedAt: timestamp })
+    };
+    const candidate = validateExecutionGroup({
+        ...group,
+        lanes: group.lanes.map((lane, laneIndex) => laneIndex === index ? updated : lane),
+        updatedAt: timestamp
+    });
+    assertExecutionGroupTransition(group, candidate);
+    return candidate;
+}
+export function updateWorkItemExecutionLane(group, laneId, patch, now) {
+    return validateWorkItemExecutionGroup(updateExecutionLane(group, laneId, patch, now));
+}
+/**
+ * Reopen only failed Lanes for an explicit retry of the same semantic
+ * execution. Successful results remain settled, while each failed Lane
+ * returns to the same state produced by a naturally failed Turn: open and
+ * still pointing at the failed attempt that dispatch must replace.
+ *
+ * This is the sole terminal-to-open Lane transition. Normal Lane updates keep
+ * terminal records immutable.
+ */
+export function retryFailedExecutionLanes(group, now) {
+    validateExecutionGroup(group);
+    if (!group.lanes.some(({ disposition }) => disposition === "failed"))
+        return group;
+    const timestamp = now.toISOString();
+    return validateExecutionGroup({
+        ...group,
+        lanes: group.lanes.map((lane) => {
+            if (lane.disposition !== "failed")
+                return lane;
+            const { endedAt: _endedAt, ...retryable } = lane;
+            return {
+                ...retryable,
+                disposition: "open",
+                updatedAt: timestamp
+            };
+        }),
+        updatedAt: timestamp
+    });
+}
+export function validateWorkItemExecutionAssignment(assignment) {
+    rejectUnknownFields(assignment, [
+        "schemaVersion",
+        "input",
+        "objective",
+        "acceptance",
+        "contextSnapshotRef",
+        "taskId",
+        "workItemId",
+        "workItemRevision",
+        "projects",
+        "dependencyFacts"
+    ], "WorkItem ExecutionAssignment");
+    if (assignment.schemaVersion !== WORK_ITEM_EXECUTION_ASSIGNMENT_SCHEMA_VERSION) {
+        throw new Error("WorkItem ExecutionAssignment schemaVersion is invalid.");
+    }
+    requireText(assignment.input, "ExecutionAssignment input");
+    requireText(assignment.objective, "ExecutionAssignment objective");
+    normalizedUniqueText(assignment.acceptance, "ExecutionAssignment acceptance criterion");
+    validateContextSnapshotRef(assignment.contextSnapshotRef);
+    requireIdentity(assignment.taskId, "ExecutionAssignment Task id");
+    requireIdentity(assignment.workItemId, "ExecutionAssignment WorkItem id");
+    requirePositiveInteger(assignment.workItemRevision, "ExecutionAssignment WorkItem revision");
+    if (!Array.isArray(assignment.projects)) {
+        throw new Error("ExecutionAssignment projects are invalid.");
+    }
+    const projectIds = assignment.projects.map((project) => {
+        rejectUnknownFields(project, [
+            "projectId",
+            "baseCommit"
+        ], "ExecutionAssignment Project base");
+        const { projectId, baseCommit } = project;
+        requireIdentity(projectId, "ExecutionAssignment Project id");
+        requireCommit(baseCommit, "ExecutionAssignment Project base commit");
+        return projectId;
+    });
+    normalizedUniqueIdentities(projectIds, "ExecutionAssignment Project");
+    if (!Array.isArray(assignment.dependencyFacts)) {
+        throw new Error("ExecutionAssignment dependency facts are invalid.");
+    }
+    const dependencyIds = assignment.dependencyFacts.map((dependency) => {
+        rejectUnknownFields(dependency, [
+            "workItemId",
+            "revision"
+        ], "ExecutionAssignment dependency fact");
+        const { workItemId, revision } = dependency;
+        requireIdentity(workItemId, "ExecutionAssignment dependency WorkItem id");
+        requirePositiveInteger(revision, "ExecutionAssignment dependency revision");
+        return workItemId;
+    });
+    normalizedUniqueIdentities(dependencyIds, "ExecutionAssignment dependency WorkItem");
+    return assignment;
+}
+export function validateReviewExecutionAssignment(assignment) {
+    rejectUnknownFields(assignment, [
+        "schemaVersion",
+        "input",
+        "objective",
+        "acceptance",
+        "contextSnapshotRef",
+        "taskId",
+        "reviewRoundId",
+        "reviewBaseCommit",
+        "scope",
+        "workItemId",
+        "candidateId",
+        "projects"
+    ], "Review ExecutionAssignment");
+    if (assignment.schemaVersion !== EXECUTION_ASSIGNMENT_SCHEMA_VERSION) {
+        throw new Error("Review ExecutionAssignment schemaVersion is invalid.");
+    }
+    requireText(assignment.input, "ExecutionAssignment input");
+    requireText(assignment.objective, "ExecutionAssignment objective");
+    normalizedUniqueText(assignment.acceptance, "ExecutionAssignment acceptance criterion");
+    validateContextSnapshotRef(assignment.contextSnapshotRef);
+    requireIdentity(assignment.taskId, "ExecutionAssignment Task id");
+    requireIdentity(assignment.reviewRoundId, "ExecutionAssignment ReviewRound id");
+    requireCommit(assignment.reviewBaseCommit, "ExecutionAssignment Review base commit");
+    if (assignment.scope !== "work-item" && assignment.scope !== "task") {
+        throw new Error("Review ExecutionAssignment scope is invalid.");
+    }
+    if (assignment.scope === "work-item") {
+        requireIdentity(assignment.workItemId ?? "", "ExecutionAssignment WorkItem id");
+        requireIdentity(assignment.candidateId ?? "", "ExecutionAssignment Candidate id");
+    }
+    else if (assignment.workItemId !== undefined || assignment.candidateId !== undefined) {
+        throw new Error("A Task Review ExecutionAssignment cannot identify a WorkItem Candidate.");
+    }
+    validateExecutionProjects(assignment.projects);
+    return assignment;
+}
+export function validateExecutionAssignment(assignment) {
+    return "reviewRoundId" in assignment
+        ? validateReviewExecutionAssignment(assignment)
+        : validateWorkItemExecutionAssignment(assignment);
+}
+export function validateExecutionGroup(group) {
+    rejectUnknownFields(group, [
+        "schemaVersion",
+        "id",
+        "taskId",
+        "assignment",
+        "lanes",
+        "createdAt",
+        "updatedAt"
+    ], "ExecutionGroup");
+    if (group.schemaVersion !== EXECUTION_GROUP_SCHEMA_VERSION) {
+        throw new Error("ExecutionGroup schemaVersion is invalid.");
+    }
+    requireIdentity(group.id, "ExecutionGroup id");
+    requireIdentity(group.taskId, "ExecutionGroup Task id");
+    const assignment = validateExecutionAssignment(group.assignment);
+    if (assignment.taskId !== group.taskId) {
+        throw new Error("ExecutionGroup Assignment Task does not match its Group.");
+    }
+    if (!Array.isArray(group.lanes) || group.lanes.length < MINIMUM_SYNTHESIS_RESULTS) {
+        throw new Error("A replicated ExecutionGroup requires at least two Lanes.");
+    }
+    if (group.lanes.length > MAXIMUM_SYNTHESIS_RESULTS) {
+        throw new Error(`A replicated ExecutionGroup supports at most ${MAXIMUM_SYNTHESIS_RESULTS} Lanes.`);
+    }
+    const ids = new Set();
+    const roles = new Set();
+    const assignmentProjectIds = assignment.projects.map(({ projectId }) => projectId).sort();
+    group.lanes.forEach((lane, index) => {
+        validateWorkItemExecutionLane(lane, group.id, index + 1);
+        if (lane.workspace !== undefined && (!isDeepStrictEqual([...lane.workspace.writableProjectIds].sort(), assignmentProjectIds) || !isDeepStrictEqual([...lane.effective.writeProjectIds].sort(), assignmentProjectIds))) {
+            throw new Error(`ExecutionLane Project scope differs from its Assignment: ${lane.id}.`);
+        }
+        if (ids.has(lane.id))
+            throw new Error(`ExecutionGroup Lane is duplicated: ${lane.id}.`);
+        if (roles.has(lane.roleName)) {
+            throw new Error(`ExecutionGroup Lane Role is duplicated: ${lane.roleName}.`);
+        }
+        ids.add(lane.id);
+        roles.add(lane.roleName);
+    });
+    requireTimestamp(group.createdAt, "ExecutionGroup createdAt");
+    requireTimestamp(group.updatedAt, "ExecutionGroup updatedAt");
+    if (Date.parse(group.updatedAt) < Date.parse(group.createdAt)) {
+        throw new Error("ExecutionGroup updatedAt precedes createdAt.");
+    }
+    return group;
+}
+export function validateWorkItemExecutionGroup(group) {
+    validateExecutionGroup(group);
+    validateWorkItemExecutionAssignment(group.assignment);
+    if (group.lanes.some(({ effective, workspace }) => (effective === undefined || workspace === undefined))) {
+        throw new Error("A WorkItem ExecutionGroup requires prepared Lane launch facts.");
+    }
+    return group;
+}
+export function assertWorkItemExecutionGroupTransition(existing, candidate) {
+    validateWorkItemExecutionGroup(existing);
+    validateWorkItemExecutionGroup(candidate);
+    assertExecutionGroupTransition(existing, candidate);
+}
+export function assertExecutionGroupTransition(existing, candidate) {
+    validateExecutionGroup(existing);
+    validateExecutionGroup(candidate);
+    if (isDeepStrictEqual(existing, candidate))
+        return;
+    if (existing.id !== candidate.id
+        || existing.taskId !== candidate.taskId
+        || existing.createdAt !== candidate.createdAt
+        || !isDeepStrictEqual(existing.assignment, candidate.assignment)
+        || existing.lanes.length !== candidate.lanes.length) {
+        throw new Error(`ExecutionGroup identity or Assignment changed: ${existing.id}.`);
+    }
+    if (Date.parse(candidate.updatedAt) < Date.parse(existing.updatedAt)) {
+        throw new Error(`ExecutionGroup time moved backwards: ${existing.id}.`);
+    }
+    existing.lanes.forEach((lane, index) => {
+        const next = candidate.lanes[index];
+        const launchFactsChanged = lane.effective === undefined
+            ? (next.effective === undefined) !== (next.workspace === undefined)
+            : !isDeepStrictEqual(lane.effective, next.effective)
+                || !isDeepStrictEqual(lane.workspace, next.workspace);
+        if (lane.id !== next.id
+            || lane.groupId !== next.groupId
+            || lane.ordinal !== next.ordinal
+            || lane.roleName !== next.roleName
+            || lane.createdAt !== next.createdAt
+            || launchFactsChanged) {
+            throw new Error(`ExecutionLane identity changed: ${lane.id}.`);
+        }
+        if (lane.disposition !== "open" && !isDeepStrictEqual(lane, next)) {
+            throw new Error(`Terminal ExecutionLane is immutable: ${lane.id}.`);
+        }
+    });
+}
+export function workItemExecutionGroupSettled(group) {
+    validateWorkItemExecutionGroup(group);
+    return executionGroupSettled(group);
+}
+export function executionGroupSettled(group) {
+    validateExecutionGroup(group);
+    return group.lanes.every(({ disposition }) => disposition !== "open");
+}
+export function summarizeExecutionGroup(group) {
+    validateExecutionGroup(group);
+    return {
+        groupId: group.id,
+        kind: "replicated",
+        laneCount: group.lanes.length,
+        openLaneCount: group.lanes.filter(({ disposition }) => disposition === "open").length,
+        succeededLaneCount: group.lanes.filter(({ disposition }) => disposition === "succeeded").length,
+        failedLaneCount: group.lanes.filter(({ disposition }) => disposition === "failed").length,
+        laneSummaries: group.lanes.map((lane) => ({
+            laneId: lane.id,
+            roleName: lane.roleName,
+            ordinal: lane.ordinal,
+            disposition: lane.disposition,
+            ...(lane.currentTurnId === undefined ? {} : { currentTurnId: lane.currentTurnId }),
+            ...(lane.successfulTurnId === undefined ? {} : { successfulTurnId: lane.successfulTurnId }),
+            ...(lane.effective === undefined ? {} : { effective: lane.effective })
+        }))
+    };
+}
+function validateExecutionProjects(projects) {
+    if (!Array.isArray(projects) || projects.length === 0) {
+        throw new Error("ExecutionAssignment projects are invalid.");
+    }
+    const projectIds = projects.map((project) => {
+        rejectUnknownFields(project, [
+            "projectId",
+            "baseCommit"
+        ], "ExecutionAssignment Project base");
+        const { projectId, baseCommit } = project;
+        requireIdentity(projectId, "ExecutionAssignment Project id");
+        requireCommit(baseCommit, "ExecutionAssignment Project base commit");
+        return projectId;
+    });
+    normalizedUniqueIdentities(projectIds, "ExecutionAssignment Project");
+    return projects;
+}
+function validateWorkItemExecutionLane(lane, groupId, ordinal) {
+    rejectUnknownFields(lane, [
+        "schemaVersion",
+        "id",
+        "groupId",
+        "ordinal",
+        "roleName",
+        "effective",
+        "workspace",
+        "currentTurnId",
+        "successfulTurnId",
+        "disposition",
+        "createdAt",
+        "updatedAt",
+        "endedAt"
+    ], "WorkItem ExecutionLane");
+    if (lane.schemaVersion !== WORK_ITEM_EXECUTION_LANE_SCHEMA_VERSION) {
+        throw new Error("WorkItem ExecutionLane schemaVersion is invalid.");
+    }
+    requireIdentity(lane.id, "ExecutionLane id");
+    if (lane.groupId !== groupId)
+        throw new Error("ExecutionLane Group does not match.");
+    if (lane.ordinal !== ordinal)
+        throw new Error("ExecutionLane ordinal is invalid.");
+    requireIdentity(lane.roleName, "ExecutionLane Role name");
+    if ((lane.effective === undefined) !== (lane.workspace === undefined)) {
+        throw new Error("ExecutionLane launch facts are incomplete.");
+    }
+    if (lane.effective !== undefined && lane.workspace !== undefined) {
+        validateEffectiveLaunchSnapshot(lane.effective);
+        rejectUnknownFields(lane.workspace, [
+            "root",
+            "writableProjectIds"
+        ], "ExecutionLane workspace");
+        requireText(lane.workspace.root, "ExecutionLane workspace root");
+        normalizedUniqueIdentities(lane.workspace.writableProjectIds, "ExecutionLane writable Project");
+    }
+    if (lane.currentTurnId !== undefined && lane.effective === undefined) {
+        throw new Error("A dispatched ExecutionLane requires launch facts.");
+    }
+    if (lane.currentTurnId !== undefined)
+        requireIdentity(lane.currentTurnId, "ExecutionLane current Turn id");
+    if (lane.successfulTurnId !== undefined)
+        requireIdentity(lane.successfulTurnId, "ExecutionLane successful Turn id");
+    if (!["open", "succeeded", "failed"].includes(lane.disposition)) {
+        throw new Error(`ExecutionLane disposition is invalid: ${String(lane.disposition)}.`);
+    }
+    if (lane.disposition === "succeeded") {
+        if (lane.currentTurnId === undefined || lane.successfulTurnId !== lane.currentTurnId) {
+            throw new Error("A succeeded Lane must identify its current successful Turn.");
+        }
+    }
+    else if (lane.successfulTurnId !== undefined) {
+        throw new Error("Only a succeeded Lane may identify a successful Turn.");
+    }
+    requireTimestamp(lane.createdAt, "ExecutionLane createdAt");
+    requireTimestamp(lane.updatedAt, "ExecutionLane updatedAt");
+    if (lane.disposition === "open") {
+        if (lane.endedAt !== undefined)
+            throw new Error("An open ExecutionLane cannot have endedAt.");
+    }
+    else {
+        requireTimestamp(lane.endedAt ?? "", "ExecutionLane endedAt");
+    }
+}
+function rejectUnknownFields(value, allowed, label) {
+    const unknown = Object.keys(value).filter((field) => !allowed.includes(field));
+    if (unknown.length > 0)
+        throw new Error(`${label} has unknown fields: ${unknown.join(", ")}.`);
+}
+function requireCommit(value, label) {
+    const normalized = requireText(value, label);
+    if (!/^[0-9a-f]{40}$/u.test(normalized))
+        throw new Error(`${label} is invalid.`);
+    return normalized;
+}