@zq-silk/yui 0.10.0 → 0.11.0

package/dist/execution/executionGroup.js

@@ -1,13 +1,34 @@
 import { isDeepStrictEqual } from "node:util";
-import { requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
+import { requireIdentity, requirePositiveInteger, requireText, requireTimestamp } from "../domain/validation.js";
+import { validateContextSnapshotRef } from "../context/contextSnapshot.js";
 import { validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
 /** The one execution abstraction used by both the one-lane and panel paths. */
 export const EXECUTION_GROUP_SCHEMA_VERSION = 1;
 export const EXECUTION_LANE_SCHEMA_VERSION = 1;
+export const WORK_ITEM_EXPLORATION_MODES = [
+    "parallel-diverse",
+    "ensemble-replicated",
+    "adversarial",
+    "adaptive-exploration"
+];
+export const WORK_ITEM_EXECUTION_MODES = [
+    "single",
+    ...WORK_ITEM_EXPLORATION_MODES
+];
+export const WORK_ITEM_EXPLORATION_STAGES = [
+    "plan",
+    "generate",
+    "compare",
+    "synthesize",
+    "verify",
+    "resolve"
+];
 export function createExecutionGroup(id, taskId, input, now) {
     const timestamp = now.toISOString();
+    const groupId = requireIdentity(id, "ExecutionGroup id");
+    const normalizedTaskId = requireIdentity(taskId, "Task id");
     const strategy = normalizeStrategy(input.strategy ?? { mode: "fixed", count: 1 });
-    const target = validateExecutionTarget(input.target, taskId);
+    const target = validateExecutionTarget(input.target, normalizedTaskId);
     const laneInputs = input.lanes === undefined
         ? [{ roleName: input.roleName ?? "leader" }]
         : input.lanes;
@@ -23,11 +44,14 @@ export function createExecutionGroup(id, taskId, input, now) {
     const lanes = laneInputs.map((lane, index) => createLane(`${id}-lane-${lane.id ?? index + 1}`, id, lane, index + 1, timestamp));
     return validateExecutionGroup({
         schemaVersion: EXECUTION_GROUP_SCHEMA_VERSION,
-        id: requireIdentity(id, "ExecutionGroup id"),
-        taskId: requireIdentity(taskId, "Task id"),
+        id: groupId,
+        taskId: normalizedTaskId,
         purpose: validatePurpose(input.purpose),
         strategy,
         target,
+        ...(input.stage === undefined
+            ? {}
+            : { stage: validateExecutionStageContext(input.stage, normalizedTaskId, groupId, strategy) }),
         lanes,
         createdAt: timestamp,
         updatedAt: timestamp
@@ -85,6 +109,7 @@ export function assertExecutionGroupTransition(existing, candidate) {
         || existing.purpose !== candidate.purpose
         || !isDeepStrictEqual(existing.strategy, candidate.strategy)
         || !isDeepStrictEqual(existing.target, candidate.target)
+        || !isDeepStrictEqual(existing.stage, candidate.stage)
         || existing.createdAt !== candidate.createdAt) {
         throw new Error(`ExecutionGroup identity or target changed: ${existing.id}.`);
     }
@@ -136,6 +161,7 @@ export function updateExecutionLane(group, laneId, patch, now) {
         ...(patch.sessionId === undefined ? {} : { sessionId: requireIdentity(patch.sessionId, "Session id") }),
         ...(patch.reviewRoundId === undefined ? {} : { reviewRoundId: requireIdentity(patch.reviewRoundId, "ReviewRound id") }),
         ...(patch.workspace === undefined ? {} : { workspace: validateLaneWorkspace(patch.workspace) }),
+        ...(patch.directive === undefined ? {} : { directive: requireText(patch.directive, "ExecutionLane directive") }),
         status,
         updatedAt: timestamp,
         ...(terminal && existing.endedAt === undefined ? { endedAt: timestamp } : {})
@@ -147,9 +173,9 @@ export function updateExecutionLane(group, laneId, patch, now) {
     });
 }
 /**
- * Reopens a failed/yielded lane for an explicit WorkItem retry.  The lane
- * keeps its identity and frozen Group target, while the previous result stays
- * in the event/Candidate history rather than being silently overwritten.
+ * Reopens only a failed Lane for an explicit WorkItem retry. Completed and
+ * yielded results are immutable reusable outputs; retrying them would erase
+ * the Group's durable evidence instead of recovering unfinished work.
  */
 export function restartExecutionLane(group, laneId, patch, now) {
     validateExecutionGroup(group);
@@ -160,8 +186,8 @@ export function restartExecutionLane(group, laneId, patch, now) {
     const existing = group.lanes.find((lane) => lane.id === id);
     if (existing === undefined)
         throw new Error(`ExecutionLane not found: ${group.id}/${id}.`);
-    if (!isTerminalLane(existing.status)) {
-        throw new Error(`ExecutionLane is not retryable: ${group.id}/${id}.`);
+    if (existing.status !== "failed") {
+        throw new Error(`Only failed ExecutionLanes can start a new AgentRun: ${group.id}/${id}.`);
     }
     const timestamp = now.toISOString();
     const { result: _result, endedAt: _endedAt, ...base } = existing;
@@ -172,6 +198,7 @@ export function restartExecutionLane(group, laneId, patch, now) {
         ...(patch.sessionId === undefined ? {} : { sessionId: requireIdentity(patch.sessionId, "Session id") }),
         ...(patch.reviewRoundId === undefined ? {} : { reviewRoundId: requireIdentity(patch.reviewRoundId, "ReviewRound id") }),
         ...(patch.workspace === undefined ? {} : { workspace: validateLaneWorkspace(patch.workspace) }),
+        ...(patch.directive === undefined ? {} : { directive: requireText(patch.directive, "ExecutionLane directive") }),
         status: "running",
         updatedAt: timestamp
     };
@@ -181,6 +208,42 @@ export function restartExecutionLane(group, laneId, patch, now) {
         updatedAt: timestamp
     });
 }
+/**
+ * Reopen a failed execution Lane without starting its next Run when Resource
+ * Broker capacity is unavailable. The failed attempt remains in AgentRun
+ * history; the Lane freezes the next launch input until ordinary dispatch can
+ * admit it.
+ */
+export function queueExecutionLaneRetry(group, laneId, patch, now) {
+    validateExecutionGroup(group);
+    if (group.purpose !== "execution") {
+        throw new Error(`Only WorkItem ExecutionLanes can queue a retry: ${group.id}/${laneId}.`);
+    }
+    if (group.resolution !== undefined) {
+        throw new Error(`ExecutionGroup is already resolved: ${group.id}.`);
+    }
+    const existing = group.lanes.find((lane) => lane.id === laneId);
+    if (existing === undefined)
+        throw new Error(`ExecutionLane not found: ${group.id}/${laneId}.`);
+    if (existing.status !== "failed") {
+        throw new Error(`Only a failed ExecutionLane can queue a retry: ${group.id}/${laneId}.`);
+    }
+    const timestamp = now.toISOString();
+    const { runId: _runId, sessionId: _sessionId, result: _result, endedAt: _endedAt, ...base } = existing;
+    const next = {
+        ...base,
+        effective: validateEffectiveLaunchSnapshot(patch.effective),
+        ...(patch.workspace === undefined ? {} : { workspace: validateLaneWorkspace(patch.workspace) }),
+        directive: requireText(patch.directive, "ExecutionLane directive"),
+        status: "pending",
+        updatedAt: timestamp
+    };
+    return validateExecutionGroup({
+        ...group,
+        lanes: group.lanes.map((lane) => lane.id === laneId ? next : lane),
+        updatedAt: timestamp
+    });
+}
 /**
  * Resets a terminal Reviewer Lane to pending without replacing its ExecutionGroup.
  * The old AgentRun remains the attempt trail; clearing the Lane's Run/session and
@@ -225,6 +288,46 @@ export function recordExecutionLaneResult(group, laneId, result, status, now) {
         updatedAt: timestamp
     });
 }
+/**
+ * Stop only work that has never started. Running Lanes retain their exact Run
+ * and Session; the Resource Broker never kills a straggler merely to save
+ * budget. Skipped Lanes are terminal but never usable Candidate inputs.
+ */
+export function skipPendingExecutionLanes(group, laneIds, summary, now) {
+    validateExecutionGroup(group);
+    if (group.purpose !== "execution") {
+        throw new Error("Only WorkItem ExecutionLanes can be skipped by resource policy.");
+    }
+    if (group.resolution !== undefined) {
+        throw new Error(`ExecutionGroup is already resolved: ${group.id}.`);
+    }
+    const selected = new Set(laneIds.map((id) => requireIdentity(id, "ExecutionLane id")));
+    if (selected.size === 0)
+        return group;
+    const reason = requireText(summary, "ExecutionLane skip summary");
+    for (const laneId of selected) {
+        const lane = group.lanes.find(({ id }) => id === laneId);
+        if (lane === undefined)
+            throw new Error(`ExecutionLane not found: ${group.id}/${laneId}.`);
+        if (lane.status !== "pending" || lane.runId !== undefined) {
+            throw new Error(`Only an unstarted pending ExecutionLane can be skipped: ${group.id}/${laneId}.`);
+        }
+    }
+    const timestamp = now.toISOString();
+    return validateExecutionGroup({
+        ...group,
+        lanes: group.lanes.map((lane) => selected.has(lane.id)
+            ? {
+                ...lane,
+                status: "skipped",
+                result: { summary: reason },
+                updatedAt: timestamp,
+                endedAt: timestamp
+            }
+            : lane),
+        updatedAt: timestamp
+    });
+}
 export function resolveExecutionGroup(group, input, now) {
     validateExecutionGroup(group);
     if (group.resolution !== undefined) {
@@ -250,6 +353,12 @@ export function resolveExecutionGroup(group, input, now) {
     })) {
         throw new Error(`ExecutionGroup accept selects a Lane without usable terminal output: ${group.id}.`);
     }
+    if (input.decision === "accept" && group.stage?.resources !== undefined) {
+        const usable = group.lanes.filter(({ status }) => (status === "yielded" || status === "completed")).length;
+        if (usable < group.stage.resources.quorum) {
+            throw new Error(`ExecutionGroup quorum is not met: ${usable}/${group.stage.resources.quorum} usable Lanes.`);
+        }
+    }
     if (selected.some((id) => !group.lanes.some((lane) => lane.id === id))) {
         throw new Error(`Execution resolution selects an unknown Lane: ${group.id}.`);
     }
@@ -278,15 +387,21 @@ export function summarizeExecutionGroup(group) {
         groupId: group.id,
         purpose: group.purpose,
         strategy: group.strategy,
+        ...(group.stage === undefined ? {} : { stage: group.stage }),
         laneCount: group.lanes.length,
         activeLaneCount,
         terminalLaneCount,
         failedLaneCount: group.lanes.filter(({ status }) => status === "failed").length,
+        skippedLaneCount: group.lanes.filter(({ status }) => status === "skipped").length,
         openHighPriorityFindingIds: openHighPriorityFindingIds(group),
         laneSummaries: group.lanes.map((lane) => ({
             laneId: lane.id,
             roleName: lane.roleName,
             ordinal: lane.ordinal,
+            ...(lane.runId === undefined ? {} : { runId: lane.runId }),
+            ...(lane.sessionId === undefined ? {} : { sessionId: lane.sessionId }),
+            ...(lane.effective === undefined ? {} : { effective: lane.effective }),
+            ...(lane.directive === undefined ? {} : { directive: lane.directive }),
             status: lane.status,
             ...(lane.result === undefined ? {} : {
                 summary: lane.result.summary,
@@ -314,6 +429,12 @@ export function validateExecutionGroup(group) {
     validatePurpose(group.purpose);
     normalizeStrategy(group.strategy);
     validateExecutionTarget(group.target, taskId);
+    if (group.stage !== undefined) {
+        if (group.purpose !== "execution" || group.target.kind !== "work-item") {
+            throw new Error("Only a WorkItem ExecutionGroup can carry exploration stage context.");
+        }
+        validateExecutionStageContext(group.stage, taskId, group.id, group.strategy);
+    }
     if (!Array.isArray(group.lanes) || group.lanes.length === 0) {
         throw new Error("ExecutionGroup requires at least one Lane.");
     }
@@ -349,6 +470,96 @@ export function validateExecutionGroup(group) {
     requireTimestamp(group.updatedAt, "ExecutionGroup updatedAt");
     return group;
 }
+export function validateExecutionStageContext(stage, taskId, executionGroupId, strategy) {
+    if (stage === null || typeof stage !== "object" || stage.schemaVersion !== 1) {
+        throw new Error("Execution stage context must use schemaVersion 1.");
+    }
+    if (!WORK_ITEM_EXPLORATION_MODES.includes(stage.mode)) {
+        throw new Error("Execution stage mode must be an exploration mode.");
+    }
+    if (!WORK_ITEM_EXPLORATION_STAGES.includes(stage.stage)) {
+        throw new Error("Execution stage is invalid.");
+    }
+    requirePositiveInteger(stage.round, "Execution stage round");
+    requirePositiveInteger(stage.stageAttempt, "Execution stage attempt");
+    requirePositiveInteger(stage.maxRounds, "Execution stage max rounds");
+    if (stage.round > stage.maxRounds) {
+        throw new Error("Execution stage round exceeds maxRounds.");
+    }
+    if (stage.budget === null || typeof stage.budget !== "object") {
+        throw new Error("Execution stage budget is required.");
+    }
+    requirePositiveInteger(stage.budget.maxLanes, "Execution stage max Lanes");
+    requirePositiveInteger(stage.budget.maxAttempts, "Execution stage max attempts");
+    if (stage.budget.maxTokens !== undefined) {
+        requirePositiveInteger(stage.budget.maxTokens, "Execution stage max tokens");
+    }
+    if (stage.budget.maxToolCalls !== undefined) {
+        requirePositiveInteger(stage.budget.maxToolCalls, "Execution stage max tool calls");
+    }
+    if (stage.budget.maxWallClockSeconds !== undefined) {
+        requirePositiveInteger(stage.budget.maxWallClockSeconds, "Execution stage max wall-clock seconds");
+    }
+    if (stage.stageAttempt > stage.budget.maxAttempts) {
+        throw new Error("Execution stage attempt exceeds its budget.");
+    }
+    const capacity = strategy.mode === "fixed" ? strategy.count : strategy.max;
+    if (stage.budget.maxLanes !== capacity) {
+        throw new Error("Execution stage Lane budget must match its Group strategy capacity.");
+    }
+    if (stage.resources !== undefined) {
+        if (stage.resources === null
+            || typeof stage.resources !== "object"
+            || stage.resources.schemaVersion !== 1) {
+            throw new Error("Execution stage resource policy must use schemaVersion 1.");
+        }
+        if (stage.budget.maxTokens === undefined
+            || stage.budget.maxToolCalls === undefined
+            || stage.budget.maxWallClockSeconds === undefined) {
+            throw new Error("A resource-scheduled Execution stage requires token, tool-call and wall-clock budgets.");
+        }
+        requirePositiveInteger(stage.resources.quorum, "Execution stage quorum");
+        if (stage.resources.quorum > stage.budget.maxLanes) {
+            throw new Error("Execution stage quorum exceeds its Lane budget.");
+        }
+        requireTimestamp(stage.resources.deadlineAt, "Execution stage deadline");
+        requirePositiveInteger(stage.resources.stragglerAfterSeconds, "Execution stage straggler threshold");
+        if (!Number.isSafeInteger(stage.resources.minimumMarginalValuePercent)
+            || stage.resources.minimumMarginalValuePercent < 0
+            || stage.resources.minimumMarginalValuePercent > 100) {
+            throw new Error("Execution stage minimum marginal value must be an integer from 0 to 100.");
+        }
+    }
+    const snapshot = validateContextSnapshotRef(stage.contextSnapshotRef);
+    if (snapshot.taskId !== taskId
+        || snapshot.scope !== "stage"
+        || snapshot.scopeRef !== executionGroupId) {
+        throw new Error("Execution stage ContextSnapshot does not match its Group.");
+    }
+    if (!Array.isArray(stage.parentResults)) {
+        throw new Error("Execution stage parentResults are invalid.");
+    }
+    const parents = new Set();
+    for (const parent of stage.parentResults) {
+        const groupId = requireIdentity(parent.executionGroupId, "Parent ExecutionGroup id");
+        const laneId = requireIdentity(parent.executionLaneId, "Parent ExecutionLane id");
+        if (!/^[0-9a-f]{64}$/u.test(parent.resultDigest)) {
+            throw new Error("Parent ExecutionLane result digest must be SHA-256 hex.");
+        }
+        const key = `${groupId}\0${laneId}`;
+        if (parents.has(key)) {
+            throw new Error(`Execution stage parent result is duplicated: ${groupId}/${laneId}.`);
+        }
+        parents.add(key);
+    }
+    if (stage.convergence !== undefined
+        && (stage.convergence === null
+            || typeof stage.convergence !== "object"
+            || stage.convergence.schemaVersion !== 1)) {
+        throw new Error("Candidate convergence policy must use schemaVersion 1.");
+    }
+    return stage;
+}
 export function validateExecutionLane(lane, group) {
     if (lane.schemaVersion !== EXECUTION_LANE_SCHEMA_VERSION) {
         throw new Error("ExecutionLane must use schemaVersion 1.");
@@ -361,7 +572,10 @@ export function validateExecutionLane(lane, group) {
         if (group.purpose === "review" && lane.reviewRoundId === undefined) {
             // A review lane may be pending before its ReviewRound is dispatched, but
             // it must acquire that identity before it can run.
-            if (lane.status === "running" || lane.status === "completed" || lane.status === "failed") {
+            if (lane.status === "running"
+                || lane.status === "completed"
+                || lane.status === "failed"
+                || lane.status === "skipped") {
                 throw new Error(`Running Reviewer Lane requires a ReviewRound: ${lane.id}.`);
             }
         }
@@ -378,9 +592,19 @@ export function validateExecutionLane(lane, group) {
         requireIdentity(lane.reviewRoundId, "ReviewRound id");
     if (lane.workspace !== undefined)
         validateLaneWorkspace(lane.workspace);
-    if (!["pending", "running", "yielded", "completed", "failed"].includes(lane.status)) {
+    if (lane.directive !== undefined)
+        requireText(lane.directive, "ExecutionLane directive");
+    if (!["pending", "running", "yielded", "completed", "failed", "skipped"].includes(lane.status)) {
         throw new Error(`ExecutionLane status is invalid: ${String(lane.status)}.`);
     }
+    if (lane.status === "skipped") {
+        if (group !== undefined && group.purpose !== "execution") {
+            throw new Error(`Only WorkItem ExecutionLanes can be skipped: ${lane.id}.`);
+        }
+        if (lane.runId !== undefined || lane.sessionId !== undefined) {
+            throw new Error(`Skipped ExecutionLane must never have started: ${lane.id}.`);
+        }
+    }
     if (lane.result !== undefined)
         validateLaneResult(lane.result);
     requireTimestamp(lane.createdAt, "ExecutionLane createdAt");
@@ -407,6 +631,7 @@ function createLane(id, groupId, input, ordinal, timestamp) {
         ...(input.sessionId === undefined ? {} : { sessionId: requireIdentity(input.sessionId, "Session id") }),
         ...(input.reviewRoundId === undefined ? {} : { reviewRoundId: requireIdentity(input.reviewRoundId, "ReviewRound id") }),
         ...(input.workspace === undefined ? {} : { workspace: validateLaneWorkspace(input.workspace) }),
+        ...(input.directive === undefined ? {} : { directive: requireText(input.directive, "ExecutionLane directive") }),
         status: "pending",
         createdAt: timestamp,
         updatedAt: timestamp
@@ -549,6 +774,9 @@ function assertExecutionLaneTransition(existing, candidate, groupId, groupPurpos
     if (isTerminalLane(existing.status)) {
         if (isDeepStrictEqual(existing, candidate))
             return;
+        if (existing.status === "skipped") {
+            throw new Error(`Skipped ExecutionLane is immutable: ${existing.id}.`);
+        }
         if (groupPurpose === "review"
             && candidate.status === "pending"
             && candidate.effective === undefined
@@ -559,6 +787,17 @@ function assertExecutionLaneTransition(existing, candidate, groupId, groupPurpos
             && isDeepStrictEqual(existing.workspace, candidate.workspace)) {
             return;
         }
+        if (groupPurpose === "execution"
+            && existing.status === "failed"
+            && candidate.status === "pending"
+            && candidate.effective !== undefined
+            && candidate.runId === undefined
+            && candidate.sessionId === undefined
+            && candidate.result === undefined
+            && candidate.endedAt === undefined
+            && candidate.directive !== undefined) {
+            return;
+        }
         if (candidate.status !== "running"
             || candidate.runId === undefined
             || candidate.runId === existing.runId) {
@@ -569,7 +808,7 @@ function assertExecutionLaneTransition(existing, candidate, groupId, groupPurpos
     if (existing.status === "running" && candidate.status === "pending") {
         throw new Error(`Running ExecutionLane cannot return to pending: ${existing.id}.`);
     }
-    for (const key of ["effective", "runId", "sessionId", "workspace"]) {
+    for (const key of ["effective", "runId", "sessionId", "workspace", "directive"]) {
         if (existing[key] !== undefined
             && !isDeepStrictEqual(existing[key], candidate[key])) {
             throw new Error(`ExecutionLane ${key} changed without retry: ${existing.id}.`);
@@ -598,7 +837,10 @@ function validatePurpose(purpose) {
     return purpose;
 }
 function isTerminalLane(status) {
-    return status === "yielded" || status === "completed" || status === "failed";
+    return status === "yielded"
+        || status === "completed"
+        || status === "failed"
+        || status === "skipped";
 }
 function positiveInteger(value, label) {
     if (!Number.isSafeInteger(value) || value < 1)