@zq-silk/yui 0.14.0 → 0.14.2

package/dist/context/turnInputContract.js

@@ -1,4 +1,4 @@
-import { normalizedUniqueIdentities, requireIdentity, requireText } from "../domain/validation.js";
+import { normalizedUniqueText, requireIdentity, requireText } from "../domain/validation.js";
 import { validateContextSnapshotRef } from "./contextSnapshot.js";
 export const TURN_INPUT_PROTOCOL_VERSION = 1;
 export const TURN_INPUT_PROTOCOL = "yui-turn/v1";
@@ -106,7 +106,7 @@ function normalizeInput(input) {
     const snapshot = input.contextSnapshotRef === undefined
         ? undefined
         : validateContextSnapshotRef(input.contextSnapshotRef);
-    const deltaRefIds = normalizedUniqueIdentities(input.deltaRefIds, "Turn input delta ref");
+    const deltaRefIds = normalizedUniqueText(input.deltaRefIds, "Turn input delta ref");
     if (deltaRefIds.length > TURN_INPUT_MAX_DELTAS) {
         throw new Error(`Turn input supports at most ${TURN_INPUT_MAX_DELTAS} delta refs.`);
     }
@@ -175,7 +175,8 @@ function normalizeSubject(subject) {
         "workItemId",
         "reviewRoundId",
         "executionGroupId",
-        "executionLaneId"
+        "executionLaneId",
+        "sourceExecutionGroupId"
     ];
     if (Object.keys(normalized).some((key) => !allowed.includes(key))) {
         throw new Error("Turn input subject contains an unknown field.");
@@ -183,9 +184,15 @@ function normalizeSubject(subject) {
     if ((normalized.executionGroupId === undefined) !== (normalized.executionLaneId === undefined)) {
         throw new Error("Turn input execution lineage is incomplete.");
     }
+    if (normalized.sourceExecutionGroupId !== undefined
+        && ((normalized.workItemId === undefined && normalized.reviewRoundId === undefined)
+            || normalized.executionGroupId !== undefined)) {
+        throw new Error("Turn input source ExecutionGroup requires a WorkItem or Review main subject.");
+    }
     if (normalized.taskId === undefined
         && (normalized.workItemId !== undefined || normalized.reviewRoundId !== undefined
-            || normalized.executionGroupId !== undefined)) {
+            || normalized.executionGroupId !== undefined
+            || normalized.sourceExecutionGroupId !== undefined)) {
         throw new Error("Turn input child subject requires a Task id.");
     }
     return Object.freeze(normalized);

package/dist/context/wakeNotification.js

@@ -28,17 +28,24 @@ export function buildTaskWakeEnvelope(reader, request) {
     }
     const fromTime = Date.parse(request.fromCursor);
     const events = reader.listEvents(request.taskId);
+    const deltaEvents = events.filter((record) => Date.parse(record.createdAt) > fromTime);
+    const turns = operationalTaskRecords(reader.listTurns(request.taskId), events, "turn");
+    const referencedTurnIds = referencedWakeTurnIds(turns, events, deltaEvents);
+    const changedTurnIds = new Set([
+        ...turns
+            .filter((record) => Date.parse(record.createdAt) > fromTime)
+            .map(({ id }) => id),
+        ...referencedTurnIds
+    ]);
     const counts = {
-        events: events
-            .filter((record) => Date.parse(record.createdAt) > fromTime).length,
+        events: deltaEvents.length,
         messages: operationalTaskRecords(reader.listMessages(request.taskId), events, "message")
             .filter((record) => Date.parse(record.createdAt) > fromTime).length,
-        turns: operationalTaskRecords(reader.listTurns(request.taskId), events, "turn")
-            .filter((record) => Date.parse(record.createdAt) > fromTime).length
+        turns: changedTurnIds.size
     };
     const activeReviews = reader.listReviewRounds(request.taskId).filter((round) => ((round.scope ?? "work-item") === "task"
         && (round.status === "pending" || round.status === "running")));
-    const reviewOrientation = activeReviews.slice(0, 3).map((round) => {
+    const renderReviewOrientation = (limit) => activeReviews.slice(0, limit).map((round) => {
         const projects = round.taskCandidate?.projects ?? [];
         const heads = projects.slice(0, 2).map(({ projectId, commit }) => (`${projectId}@${commit.slice(0, 12)}`)).join("+");
         return `${round.id}/${round.reviewerRoleName}`
@@ -47,36 +54,91 @@ export function buildTaskWakeEnvelope(reader, request) {
             + `@${heads || round.reviewBaseCommit.slice(0, 12)}`
             + `${projects.length > 2 ? `+${projects.length - 2}` : ""}`;
     }).join(", ");
-    const lines = [
-        `Wake: ${request.wakeId} — delta since ${request.fromCursor}`,
-        `  Reasons: ${renderReasons(request.reasons)}`,
-        `  Changed: ${counts.events} events, ${counts.messages} messages, ${counts.turns} Turns`
-            + ` → yui task wake show ${request.taskId} ${request.wakeId}`,
-        `  Active Task Reviews: ${activeReviews.length === 0
-            ? "none"
-            : `${reviewOrientation}${activeReviews.length > 3 ? `, … (+${activeReviews.length - 3})` : ""}`}`,
-        `Full context: yui task context ${request.taskId}`
-    ];
-    const body = lines.join("\n");
-    const totalBytes = byteLength(body) + 1;
-    if (totalBytes > WAKE_ENVELOPE_HARD_BYTES) {
-        throw new Error(`Wake envelope ${request.wakeId} exceeds the structural hard budget of`
-            + ` ${WAKE_ENVELOPE_HARD_BYTES} bytes (${totalBytes}).`);
+    const render = (reasonLimit, resultTurnLimit, reviewLimit) => {
+        const reviewOrientation = renderReviewOrientation(reviewLimit);
+        return [
+            `Wake: ${request.wakeId} — delta since ${request.fromCursor}`,
+            `  Reasons: ${renderReasons(request.reasons, reasonLimit)}`,
+            `  Changed: ${counts.events} events, ${counts.messages} messages, ${counts.turns} Turns`
+                + ` → yui task wake show ${request.taskId} ${request.wakeId}`,
+            `  Result Turns: ${renderResultTurns(request.taskId, referencedTurnIds, resultTurnLimit)}`,
+            `  Active Task Reviews: ${activeReviews.length === 0
+                ? "none"
+                : reviewLimit === 0
+                    ? `${activeReviews.length} → yui task context ${request.taskId}`
+                    : `${reviewOrientation}${activeReviews.length > reviewLimit
+                        ? `, … (+${activeReviews.length - reviewLimit})`
+                        : ""}`}`,
+            `Full context: yui task context ${request.taskId}`
+        ].join("\n");
+    };
+    let reasonLimit = Math.min(REASON_DISPLAY_LIMIT, request.reasons.length);
+    let resultTurnLimit = Math.min(4, referencedTurnIds.length);
+    let reviewLimit = Math.min(3, activeReviews.length);
+    let body = render(reasonLimit, resultTurnLimit, reviewLimit);
+    while (byteLength(body) + 1 > WAKE_ENVELOPE_HARD_BYTES) {
+        if (resultTurnLimit > 0)
+            resultTurnLimit -= 1;
+        else if (reasonLimit > 0)
+            reasonLimit -= 1;
+        else if (reviewLimit > 0)
+            reviewLimit -= 1;
+        else
+            break;
+        body = render(reasonLimit, resultTurnLimit, reviewLimit);
     }
+    if (byteLength(body) + 1 > WAKE_ENVELOPE_HARD_BYTES) {
+        body = fitUtf8([
+            `Wake: ${request.wakeId}`,
+            `Inspect: yui task wake show ${request.taskId} ${request.wakeId}`,
+            `Full context: yui task context ${request.taskId}`
+        ].join("\n"), WAKE_ENVELOPE_HARD_BYTES - 1);
+    }
+    const totalBytes = byteLength(body) + 1;
     return Object.freeze({
         taskId: request.taskId,
         wakeId: request.wakeId,
         fromCursor: request.fromCursor,
+        referencedTurnIds: Object.freeze(referencedTurnIds),
         totalBytes,
         text: `${body}\n`
     });
 }
-function renderReasons(reasons) {
-    const selected = reasons.slice(0, REASON_DISPLAY_LIMIT);
+export function referencedWakeTurnIds(turns, allEvents, terminalEvents) {
+    const turnsById = new Map(operationalTaskRecords(turns, allEvents, "turn").map((turn) => [turn.id, turn]));
+    return [...new Set(terminalEvents.flatMap((event) => {
+            if (!["turn.completed", "turn.failed", "turn.cancelled"].includes(event.type))
+                return [];
+            const turnId = event.payload.turnId;
+            return turnId !== undefined && turnsById.has(turnId) ? [turnId] : [];
+        }))];
+}
+function renderReasons(reasons, limit) {
+    if (limit === 0)
+        return `${reasons.length} reason tags`;
+    const selected = reasons.slice(0, limit);
     const elided = reasons.length - selected.length;
     const rendered = selected.map(renderWakeReason).join(", ");
     return elided === 0 ? rendered : `${rendered}, … (+${elided} more)`;
 }
+function renderResultTurns(taskId, turnIds, limit) {
+    if (turnIds.length === 0)
+        return "none";
+    if (limit === 0)
+        return `${turnIds.length} → inspect the wake delta`;
+    return `${turnIds.slice(0, limit)
+        .map((turnId) => `${turnId} → yui task turn show ${taskId}/${turnId}`)
+        .join(", ")}${turnIds.length > limit ? `, … (+${turnIds.length - limit})` : ""}`;
+}
+function fitUtf8(value, maxBytes) {
+    let fitted = "";
+    for (const character of value) {
+        if (byteLength(fitted) + byteLength(character) > maxBytes)
+            break;
+        fitted += character;
+    }
+    return fitted;
+}
 function byteLength(value) {
     return Buffer.byteLength(value, "utf8");
 }

package/dist/controller/agentRuntimeObserver.js

@@ -102,7 +102,7 @@ export class AgentRuntimeObserver {
                         ? tokenObservationIdentity("baseline", fence, source.sourceId, baselineKey)
                         : usageObservationIdentity(fence, source.sourceId, latestOccurrence);
                     this.inbox.enqueueObservation(createRuntimeObservation({
-                        schemaVersion: 2,
+                        schemaVersion: 4,
                         eventId: identity.eventId,
                         semanticKey: identity.semanticKey,
                         kind: "activity.observed",
@@ -137,7 +137,7 @@ export class AgentRuntimeObserver {
             const health = JSON.stringify([sample.status, sample.detail ?? null]);
             if (state.health !== health) {
                 this.inbox.enqueueObservation(createRuntimeObservation({
-                    schemaVersion: 2,
+                    schemaVersion: 4,
                     eventId: observationId("health", fence, source.sourceId, health),
                     semanticKey: observationId("health", fence, source.sourceId, health),
                     kind: "observer.health",
@@ -183,7 +183,7 @@ export class AgentRuntimeObserver {
             usages.forEach((occurrence, usageIndex) => {
                 const identity = usageObservationIdentity(fence, source.sourceId, occurrence);
                 this.inbox.enqueueObservation(createRuntimeObservation({
-                    schemaVersion: 2,
+                    schemaVersion: 4,
                     eventId: identity.eventId,
                     semanticKey: identity.semanticKey,
                     kind: "activity.observed",
@@ -213,7 +213,7 @@ export class AgentRuntimeObserver {
             });
             if (activityChanged && state.cursor !== undefined) {
                 this.inbox.enqueueObservation(createRuntimeObservation({
-                    schemaVersion: 2,
+                    schemaVersion: 4,
                     eventId: observationId("activity", fence, source.sourceId, sample.activityId),
                     semanticKey: observationId("activity", fence, source.sourceId, sample.activityId),
                     kind: "activity.observed",
@@ -297,7 +297,7 @@ export class AgentRuntimeObserver {
                     continue;
                 }
                 const fence = accepted.fence;
-                const generation = taskObservations.filter((observation) => (sessionGenerationFenceMatches(fence, observation.fence)
+                const generation = taskObservations.filter((observation) => (sessionRuntimeGenerationFenceMatches(fence, observation.fence)
                     && observation.payload.sourceId === source.sourceId));
                 const persistedUsage = generation.filter((observation) => (observation.kind === "activity.observed"
                     && observation.payload.usage !== undefined)).at(-1);
@@ -316,8 +316,7 @@ export class AgentRuntimeObserver {
                         fence.turnId,
                         fence.agentId,
                         fence.driverId,
-                        fence.launchId,
-                        fence.sessionGenerationId,
+                        fence.runtimeGenerationId,
                         fence.nativeSessionId,
                         source.sourceId
                     ]),
@@ -463,21 +462,19 @@ function tokenObservationId(kind, fence, sourceId, value) {
         fence.roleName,
         fence.agentId,
         fence.driverId,
-        fence.launchId,
-        fence.sessionGenerationId,
+        fence.runtimeGenerationId,
         fence.nativeSessionId ?? null,
         sourceId,
         value
     ])).digest("hex")}`;
 }
-function sessionGenerationFenceMatches(expected, actual) {
+function sessionRuntimeGenerationFenceMatches(expected, actual) {
     for (const field of [
         "taskId",
         "roleName",
         "agentId",
         "driverId",
-        "launchId",
-        "sessionGenerationId",
+        "runtimeGenerationId",
         "nativeSessionId"
     ]) {
         if (expected[field] !== actual[field])

package/dist/controller/clientRuntime.js

@@ -88,7 +88,7 @@ export async function ensureFileTaskController(home, options = {}) {
 }
 /** Start and await readiness for a captured Controller identity. */
 export async function ensureFileTaskControllerIdentity(home, identity, options = {}) {
-    assertExpectedControllerLaunchIdentity(identity);
+    assertExpectedControllerRuntimeGenerationIdentity(identity);
     const status = await ensureFileTaskController(home, {
         ...options,
         expectedVersion: identity.version
@@ -102,36 +102,36 @@ export async function ensureFileTaskControllerIdentity(home, identity, options =
     const actual = await call(home, "controller.identity", {}, {
         timeoutMs: options.requestTimeoutMs
     });
-    assertControllerLaunchIdentity(actual, identity);
+    assertControllerRuntimeGenerationIdentity(actual, identity);
     return status;
 }
-function assertExpectedControllerLaunchIdentity(identity) {
+function assertExpectedControllerRuntimeGenerationIdentity(identity) {
     if (typeof identity.executablePath !== "string"
         || identity.executablePath.length === 0
         || !Array.isArray(identity.args)
         || identity.args.some((arg) => typeof arg !== "string")
         || typeof identity.version !== "string"
         || identity.version.length === 0) {
-        throw new Error("Expected Controller launch identity is malformed; refusing to start or accept a Controller.");
+        throw new Error("Expected Controller runtime generation identity is malformed; refusing to start or accept a Controller.");
     }
 }
-function assertControllerLaunchIdentity(actual, expected) {
+function assertControllerRuntimeGenerationIdentity(actual, expected) {
     if (!isJsonRecord(actual)) {
-        throw new Error("Authenticated Controller launch identity is malformed; refusing to accept readiness.");
+        throw new Error("Authenticated Controller runtime generation identity is malformed; refusing to accept readiness.");
     }
     const actualArgs = actual.args;
     if (typeof actual.executablePath !== "string"
         || !Array.isArray(actualArgs)
         || actualArgs.some((arg) => typeof arg !== "string")
         || typeof actual.version !== "string") {
-        throw new Error("Authenticated Controller launch identity is malformed; refusing to accept readiness.");
+        throw new Error("Authenticated Controller runtime generation identity is malformed; refusing to accept readiness.");
     }
     const argsMatch = actualArgs.length === expected.args.length
         && actualArgs.every((arg, index) => arg === expected.args[index]);
     if (actual.executablePath !== expected.executablePath
         || !argsMatch
         || actual.version !== expected.version) {
-        throw new Error("Authenticated Controller launch identity does not match the captured executable, argv, and version; refusing readiness.");
+        throw new Error("Authenticated Controller runtime generation identity does not match the captured executable, argv, and version; refusing readiness.");
     }
 }
 function assertCompatibleControllerStatus(status, expectedVersion) {
@@ -479,7 +479,7 @@ export class FileTaskWorkflowRuntime {
             agentId: input.agentId,
             adapterId: input.adapterId,
             nativeSessionId: input.nativeSessionId,
-            ...(input.launchId === undefined ? {} : { launchId: input.launchId }),
+            ...(input.runtimeGenerationId === undefined ? {} : { runtimeGenerationId: input.runtimeGenerationId }),
             sessionUpdatedAt: input.sessionUpdatedAt
         });
         if (target === null) {
@@ -563,7 +563,7 @@ export class FileTaskWorkflowRuntime {
         if (blockers.length === 0)
             return;
         throw new WorkspaceCleanupBlockedError("physical-resource-live", `task:${taskId}`, true, `Task archive blocked: ${blockers.length} owned physical resource(s) still live: `
-            + blockers.map((entry) => (`${entry.owner.roleName}/${entry.launchId}`
+            + blockers.map((entry) => (`${entry.owner.roleName}/${entry.runtimeGenerationId}`
                 + ` (pid ${entry.physical?.alive === true ? entry.physical.pid : "?"})`)).join("; "));
     }
     async stopGlobalRoleSession(roleName) {
@@ -622,10 +622,10 @@ export class FileTaskWorkflowRuntime {
         if (termination.outcome !== "stop-confirmed") {
             throw new Error(`Role runtime cleanup could not prove physical exit: ${runtimeOwnerLabel(candidate.owner)}; `
                 + termination.remaining
-                    .map(({ record, detail }) => `${record.launchId}: ${detail}`)
+                    .map(({ record, detail }) => `${record.runtimeGenerationId}: ${detail}`)
                     .join("; "));
         }
-        if (candidate.owner.scope === "task" && candidate.launchId !== undefined) {
+        if (candidate.owner.scope === "task" && candidate.runtimeGenerationId !== undefined) {
             const isolation = new FileTaskRuntimeIsolation({
                 runtimeRoot: `${this.home}.task-runtimes`,
                 controlPlane: {
@@ -637,7 +637,7 @@ export class FileTaskWorkflowRuntime {
             });
             isolation.cleanupTaskLaunch({
                 taskId: candidate.owner.taskId,
-                launchId: candidate.launchId,
+                runtimeGenerationId: candidate.runtimeGenerationId,
                 reason: this.store.getTask(candidate.owner.taskId)?.status === "completed"
                     ? "completion"
                     : "interruption"

package/dist/controller/controller.js

@@ -97,7 +97,7 @@ export async function runControllerSchedulerPass(store, delivery, now, workspace
             : [])));
         // Phase-one Leader Turns did not exist at the pass's liveness boundary.
         // Keep every newly claimed Turn outside destructive absence decisions until
-        // a later pass can observe its stable provider/session generation.
+        // a later pass can observe its stable provider/runtime generation.
         for (const result of initialWakeupResults) {
             if (result.turnId !== undefined
                 && store.getActiveTurn(result.taskId, "leader")?.id === result.turnId) {
@@ -220,7 +220,7 @@ async function processSelectedRoleRuntimeCleanups(store, delivery, lifecycleHost
                 }
                 if (target.kind === "role-runtime") {
                     const session = store.getRoleSession(target.taskId, target.roleName);
-                    const reservedLaunchId = isRuntimeLaunchReservation(mailbox.processing)
+                    const reservedRuntimeGenerationId = isRuntimeLaunchReservation(mailbox.processing)
                         ? mailbox.processing.batchId
                         : undefined;
                     // A failed fresh-Conversation launch can leave two exact resource
@@ -228,19 +228,19 @@ async function processSelectedRoleRuntimeCleanups(store, delivery, lifecycleHost
                     // replacement reservation. They are not competing authorities. The
                     // owner-wide stop has already proven physical zero, so clean both
                     // exact launch roots idempotently before settling the mailbox.
-                    const launchIds = new Set([
-                        reservedLaunchId,
-                        session?.launchId
-                    ].filter((launchId) => launchId !== undefined));
+                    const runtimeGenerationIds = new Set([
+                        reservedRuntimeGenerationId,
+                        session?.runtimeGenerationId
+                    ].filter((runtimeGenerationId) => runtimeGenerationId !== undefined));
                     if (lifecycleHost.cleanupTaskLaunch !== undefined) {
                         const task = store.getTask(target.taskId);
                         const reason = task?.status === "completed"
                             ? "completion"
                             : "interruption";
-                        for (const launchId of launchIds) {
+                        for (const runtimeGenerationId of runtimeGenerationIds) {
                             lifecycleHost.cleanupTaskLaunch({
                                 taskId: target.taskId,
-                                launchId,
+                                runtimeGenerationId,
                                 reason
                             });
                         }
@@ -338,7 +338,7 @@ async function reconcileDormantRuntimeOwners(store, delivery, lifecycleHost, sco
     for (const candidate of candidates) {
         if (byOwner.get(runtimeOwnerIdentity(candidate.owner))?.state
             === "stopped") {
-            if (candidate.launchId !== undefined) {
+            if (candidate.runtimeGenerationId !== undefined) {
                 // The exact launch-owned resources must settle through the durable
                 // cleanup lane before its Host fact is detached. The resumable Session
                 // remains active; the candidate is the CAS fence against a concurrent
@@ -1600,9 +1600,9 @@ export class FileTaskController {
             taskId: failure.taskId,
             roleName: failure.roleName,
             turnId: failure.turnId,
-            ...(failure.launchId === undefined
+            ...(failure.runtimeGenerationId === undefined
                 ? {}
-                : { launchId: failure.launchId })
+                : { runtimeGenerationId: failure.runtimeGenerationId })
         });
         if (!this.#stopped)
             this.signal(key);