@zq-silk/yui 0.13.9 → 0.14.0

package/dist/context/{runContextPack.js → turnContextPack.js}

@@ -1,13 +1,12 @@
-import { rejectedYieldAttemptFromTaskEvent, RUN_YIELD_REJECTED_EVENT } from "../run/rejectedYieldAttempt.js";
 import { operationalTaskRecords } from "../task/taskRecordRetirement.js";
 import { TASK_COMPLETION_PUBLISHED_TREE_AUTHORIZED_EVENT } from "../task/publicationReference.js";
-import { RUN_BOOTSTRAP_MAX_DELTAS } from "./runContextContract.js";
+import { TURN_INPUT_MAX_DELTAS } from "./turnInputContract.js";
 import { contextContentDigest, contextSnapshotRef, createContextSnapshot, validateContextSnapshot } from "./contextSnapshot.js";
-export const RUN_CONTEXT_PACK_SCHEMA_VERSION = 1;
-export const RUN_CONTEXT_PACK_MAX_REFS = 256;
-export const RUN_CONTEXT_PACK_MAX_BYTES = 8 * 1024 * 1024;
-export const RUN_CONTEXT_EXPAND_MAX_BYTES = 4 * 1024 * 1024;
-export function freezeRunContextSnapshot(store, run, now, frozenBy = "controller", baselineRef) {
+export const TURN_CONTEXT_PACK_SCHEMA_VERSION = 1;
+export const TURN_CONTEXT_PACK_MAX_REFS = 256;
+export const TURN_CONTEXT_PACK_MAX_BYTES = 8 * 1024 * 1024;
+export const TURN_CONTEXT_EXPAND_MAX_BYTES = 4 * 1024 * 1024;
+export function freezeTurnContextSnapshot(store, run, now, frozenBy = "controller", baselineRef) {
     if (baselineRef !== undefined) {
         const baseline = store.getContextSnapshot(run.taskId, baselineRef.id);
         if (baseline === null
@@ -18,10 +17,10 @@ export function freezeRunContextSnapshot(store, run, now, frozenBy = "controller
             || baseline.scope !== "stage"
             || baselineRef.scope !== baseline.scope
             || baseline.scopeRef !== baselineRef.scopeRef) {
-            throw new Error(`Run Context baseline is missing or drifted: ${baselineRef.id}.`);
+            throw new Error(`Turn Context baseline is missing or drifted: ${baselineRef.id}.`);
         }
         validateContextSnapshot(baseline);
-        const overlays = collectRunContextOverlays(store, run);
+        const overlays = collectTurnContextOverlays(store, run);
         const resources = [...new Map([...baseline.resources, ...overlays].map((entry) => [
                 contextRefIdentity(entry.ref),
                 entry
@@ -77,7 +76,7 @@ export function freezeRunContextSnapshot(store, run, now, frozenBy = "controller
 }
 /**
  * Freeze the shared, role-neutral ContextSnapshot anchored by one WorkItem
- * exploration stage Group. AgentRun snapshots remain role-specific; this
+ * exploration stage Group. Turn snapshots remain role-specific; this
  * record is the durable stage baseline and derives from a fresh WorkItem
  * snapshot so the Group never depends on ambient latest state.
  */
@@ -102,7 +101,7 @@ export function freezeExecutionStageContextSnapshot(store, input, now) {
     for (const binding of task.projectBindings) {
         const project = store.getProject(binding.projectId);
         if (project === null)
-            throw new Error(`Run Project not found: ${binding.projectId}.`);
+            throw new Error(`Turn Project not found: ${binding.projectId}.`);
         const { knowledge, ...projectPolicy } = project;
         materialized.push(materialize("L1", "project-policy", project.id, projectPolicy));
         for (const entry of knowledge.filter(({ status }) => status === "active")) {
@@ -217,27 +216,27 @@ export function contextSnapshotDeltaRefIds(store, snapshot) {
             || before.store !== ref.store
             || before.layer !== ref.layer;
     }).map(({ refId }) => refId);
-    return Object.freeze([...new Set(changed)].sort().slice(0, RUN_BOOTSTRAP_MAX_DELTAS));
+    return Object.freeze([...new Set(changed)].sort().slice(0, TURN_INPUT_MAX_DELTAS));
 }
-export function buildRunContextPack(store, taskId, runId) {
-    const run = requireExactRun(store, taskId, runId);
+export function buildTurnContextPack(store, taskId, turnId) {
+    const run = requireExactTurn(store, taskId, turnId);
     const current = collectAuthorizedContext(store, run);
     let pointers = current.map(({ ref }) => ref);
     let snapshotRef;
-    if (run.assignment.contextSnapshotRef !== undefined) {
-        const expected = run.assignment.contextSnapshotRef;
+    if (run.inputs[0].input.contextSnapshotRef !== undefined) {
+        const expected = run.inputs[0].input.contextSnapshotRef;
         const snapshot = store.getContextSnapshot(taskId, expected.id);
         if (snapshot === null)
-            throw new Error(`Run Context Snapshot is missing: ${expected.id}.`);
+            throw new Error(`Turn Context Snapshot is missing: ${expected.id}.`);
         validateContextSnapshot(snapshot);
         if (snapshot.digest !== expected.digest || snapshot.taskId !== taskId) {
-            throw new Error(`Run Context Snapshot identity drifted: ${expected.id}.`);
+            throw new Error(`Turn Context Snapshot identity drifted: ${expected.id}.`);
         }
         pointers = snapshot.refs;
         snapshotRef = contextSnapshotRef(snapshot);
     }
-    if (pointers.length > RUN_CONTEXT_PACK_MAX_REFS) {
-        throw new Error(`Run Context exceeds ${RUN_CONTEXT_PACK_MAX_REFS} authorized refs.`);
+    if (pointers.length > TURN_CONTEXT_PACK_MAX_REFS) {
+        throw new Error(`Turn Context exceeds ${TURN_CONTEXT_PACK_MAX_REFS} authorized refs.`);
     }
     const view = contextView(run);
     const writableProjectIds = writableProjects(store, run, view);
@@ -248,10 +247,10 @@ export function buildRunContextPack(store, taskId, runId) {
         digest: ref.digest
     }));
     const body = {
-        schemaVersion: RUN_CONTEXT_PACK_SCHEMA_VERSION,
+        schemaVersion: TURN_CONTEXT_PACK_SCHEMA_VERSION,
         identity: Object.freeze({
             taskId,
-            runId,
+            turnId: turnId,
             roleName: run.roleName,
             purpose: run.purpose,
             agentId: run.effective.agentId,
@@ -259,27 +258,27 @@ export function buildRunContextPack(store, taskId, runId) {
             workspace: run.effective.workspace.root
         }),
         ...(snapshotRef === undefined ? {} : { snapshot: snapshotRef }),
-        assignment: run.assignment,
+        input: run.inputs[0].input,
         authority: Object.freeze({ view, readableRefs: pointers, writableProjectIds }),
         pointers,
         summaries,
-        deltas: pointers.filter((ref) => run.assignment.deltaRefIds.includes(ref.refId)),
+        deltas: pointers.filter((ref) => run.inputs[0].input.deltaRefIds.includes(ref.refId)),
         completion: Object.freeze({
             allowedActions: completionActions(view),
-            exactRunRef: `${taskId}/${runId}`
+            exactTurnRef: `${taskId}/${turnId}`
         })
     };
     const digest = contextContentDigest(body);
     const preliminaryBytes = Buffer.byteLength(JSON.stringify({ ...body, digest }), "utf8");
-    if (preliminaryBytes > RUN_CONTEXT_PACK_MAX_BYTES) {
-        throw new Error(`Run Context Pack exceeds ${RUN_CONTEXT_PACK_MAX_BYTES} bytes.`);
+    if (preliminaryBytes > TURN_CONTEXT_PACK_MAX_BYTES) {
+        throw new Error(`Turn Context Pack exceeds ${TURN_CONTEXT_PACK_MAX_BYTES} bytes.`);
     }
     const pack = Object.freeze({
         ...body,
         budget: Object.freeze({
-            maxRefs: RUN_CONTEXT_PACK_MAX_REFS,
+            maxRefs: TURN_CONTEXT_PACK_MAX_REFS,
             returnedRefs: pointers.length,
-            maxBytes: RUN_CONTEXT_PACK_MAX_BYTES,
+            maxBytes: TURN_CONTEXT_PACK_MAX_BYTES,
             returnedBytes: preliminaryBytes,
             truncated: false
         }),
@@ -287,24 +286,24 @@ export function buildRunContextPack(store, taskId, runId) {
     });
     return pack;
 }
-export function expandRunContextRef(store, taskId, runId, refId, refStore) {
-    const pack = buildRunContextPack(store, taskId, runId);
+export function expandTurnContextRef(store, taskId, turnId, refId, refStore) {
+    const pack = buildTurnContextPack(store, taskId, turnId);
     const authorized = pack.pointers.filter((ref) => (ref.refId === refId && (refStore === undefined || ref.store === refStore)));
     const selector = refStore === undefined ? refId : `${refStore}/${refId}`;
     if (authorized.length !== 1) {
-        throw new Error(`Run Context ref is not uniquely authorized: ${selector}.`);
+        throw new Error(`Turn Context ref is not uniquely authorized: ${selector}.`);
     }
-    const run = requireExactRun(store, taskId, runId);
-    const snapshotRef = run.assignment.contextSnapshotRef;
+    const run = requireExactTurn(store, taskId, turnId);
+    const snapshotRef = run.inputs[0].input.contextSnapshotRef;
     const materialized = snapshotRef === undefined
         ? collectAuthorizedContext(store, run).find(({ ref }) => (contextRefIdentity(ref) === contextRefIdentity(authorized[0])))
         : store.getContextSnapshot(taskId, snapshotRef.id)?.resources.find(({ ref }) => (contextRefIdentity(ref) === contextRefIdentity(authorized[0])));
     if (materialized === undefined || materialized.ref.digest !== authorized[0].digest) {
-        throw new Error(`Run Context ref is unavailable or drifted: ${selector}.`);
+        throw new Error(`Turn Context ref is unavailable or drifted: ${selector}.`);
     }
     const bytes = Buffer.byteLength(JSON.stringify(materialized.value), "utf8");
-    if (bytes > RUN_CONTEXT_EXPAND_MAX_BYTES) {
-        throw new Error(`Run Context expansion exceeds ${RUN_CONTEXT_EXPAND_MAX_BYTES} bytes.`);
+    if (bytes > TURN_CONTEXT_EXPAND_MAX_BYTES) {
+        throw new Error(`Turn Context expansion exceeds ${TURN_CONTEXT_EXPAND_MAX_BYTES} bytes.`);
     }
     return Object.freeze({
         ref: materialized.ref,
@@ -312,21 +311,21 @@ export function expandRunContextRef(store, taskId, runId, refId, refStore) {
         digest: contextContentDigest({ ref: materialized.ref, value: materialized.value })
     });
 }
-/** Fail-closed delta cursor resolution for one immutable Run lineage. */
-export function buildRunContextDelta(store, taskId, runId, after) {
-    const pack = buildRunContextPack(store, taskId, runId);
+/** Fail-closed delta cursor resolution for one immutable Turn lineage. */
+export function buildTurnContextDelta(store, taskId, turnId, after) {
+    const pack = buildTurnContextPack(store, taskId, turnId);
     if (after === pack.digest || after === pack.snapshot?.digest) {
         return Object.freeze({ schemaVersion: 1, after, cursor: pack.digest, refs: [] });
     }
-    const run = requireExactRun(store, taskId, runId);
-    const snapshotRef = run.assignment.contextSnapshotRef;
+    const run = requireExactTurn(store, taskId, turnId);
+    const snapshotRef = run.inputs[0].input.contextSnapshotRef;
     const snapshot = snapshotRef === undefined
         ? null
         : store.getContextSnapshot(taskId, snapshotRef.id);
     const parentDigest = snapshot?.parentRef?.digest;
     if (!((parentDigest !== undefined && after === parentDigest)
         || (parentDigest === undefined && after === "none"))) {
-        throw new Error("Run Context delta cursor is outside the frozen Snapshot lineage.");
+        throw new Error("Turn Context delta cursor is outside the frozen Snapshot lineage.");
     }
     return Object.freeze({
         schemaVersion: 1,
@@ -335,10 +334,10 @@ export function buildRunContextDelta(store, taskId, runId, after) {
         refs: pack.deltas
     });
 }
-function requireExactRun(store, taskId, runId) {
-    const run = store.getAgentRun(taskId, runId);
-    if (run === null || run.taskId !== taskId || run.id !== runId) {
-        throw new Error(`Agent Run not found: ${taskId}/${runId}.`);
+function requireExactTurn(store, taskId, turnId) {
+    const run = store.getTurn(taskId, turnId);
+    if (run === null || run.taskId !== taskId || run.id !== turnId) {
+        throw new Error(`Turn not found: ${taskId}/${turnId}.`);
     }
     return run;
 }
@@ -352,18 +351,18 @@ function collectAuthorizedContext(store, run) {
     if (brief !== null && view === "leader") {
         result.push(materialize("L2", "task-brief", task.id, brief));
     }
-    result.push(...collectRunContextOverlays(store, run));
+    result.push(...collectTurnContextOverlays(store, run));
     if (run.workItemId !== undefined) {
         const item = store.getWorkItem(task.id, run.workItemId);
         if (item === null)
-            throw new Error(`Run WorkItem not found: ${run.workItemId}.`);
+            throw new Error(`Turn WorkItem not found: ${run.workItemId}.`);
         result.push(materialize("L3", "work-item", item.id, item));
         if (view === "worker") {
             for (const dependencyId of item.dependsOn) {
                 const dependency = store.getWorkItem(task.id, dependencyId);
                 if (dependency === null
                     || (dependency.status !== "completed" && dependency.status !== "retired")) {
-                    throw new Error(`Run WorkItem dependency is not accepted: ${dependencyId}.`);
+                    throw new Error(`Turn WorkItem dependency is not accepted: ${dependencyId}.`);
                 }
                 if (dependency.status === "retired")
                     continue;
@@ -374,7 +373,7 @@ function collectAuthorizedContext(store, run) {
     if (run.reviewRoundId !== undefined) {
         const round = store.getReviewRound(task.id, run.reviewRoundId);
         if (round === null)
-            throw new Error(`Run ReviewRound not found: ${run.reviewRoundId}.`);
+            throw new Error(`Turn ReviewRound not found: ${run.reviewRoundId}.`);
         result.push(materialize("L3", "review-round", round.id, round));
         for (const finding of store.listReviewFindings(task.id).filter((candidate) => (candidate.firstReviewRoundId === round.id
             || candidate.lastReviewRoundId === round.id
@@ -385,7 +384,7 @@ function collectAuthorizedContext(store, run) {
     for (const binding of task.projectBindings) {
         const project = store.getProject(binding.projectId);
         if (project === null)
-            throw new Error(`Run Project not found: ${binding.projectId}.`);
+            throw new Error(`Turn Project not found: ${binding.projectId}.`);
         const { knowledge, ...projectPolicy } = project;
         result.push(materialize("L1", "project-policy", project.id, projectPolicy));
         for (const entry of knowledge.filter(({ status }) => status === "active")) {
@@ -409,8 +408,8 @@ function collectAuthorizedContext(store, run) {
         for (const finding of store.listReviewFindings(task.id)) {
             result.push(materialize("L3", "review-finding", finding.id, finding));
         }
-        for (const agentRun of operationalTaskRecords(store.listAgentRuns(task.id), events, "agent-run").slice(-24)) {
-            result.push(materialize("L4", "agent-run", agentRun.id, agentRun));
+        for (const turn of operationalTaskRecords(store.listTurns(task.id), events, "turn").slice(-24)) {
+            result.push(materialize("L4", "turn", turn.id, turn));
         }
         for (const message of operationalTaskRecords(store.listMessages(task.id), events, "message").slice(-16)) {
             result.push(materialize("L4", "task-message", message.id, message));
@@ -427,20 +426,6 @@ function collectAuthorizedContext(store, run) {
         for (const event of publishedTreeAuthorizations.reverse().slice(-16)) {
             result.push(materialize("L4", "task-event", event.id, event));
         }
-        for (const event of events.filter(({ type }) => (type === RUN_YIELD_REJECTED_EVENT)).slice(-16)) {
-            result.push(materialize("L4", "task-event", event.id, event));
-            const attempt = rejectedYieldAttemptFromTaskEvent(event);
-            if (attempt === null)
-                continue;
-            const rejectedRun = store.getAgentRun(task.id, attempt.runId);
-            if (rejectedRun !== null) {
-                result.push(materialize("L4", "agent-run", rejectedRun.id, rejectedRun));
-            }
-            const rejectedRound = store.getReviewRound(task.id, attempt.reviewRoundId);
-            if (rejectedRound !== null) {
-                result.push(materialize("L3", "review-round", rejectedRound.id, rejectedRound));
-            }
-        }
         for (const request of store.listOpenInputRequests([task.id])) {
             result.push(materialize("L4", "input-request", request.id, request));
         }
@@ -449,10 +434,10 @@ function collectAuthorizedContext(store, run) {
     return [...unique.values()].sort((left, right) => (contextRefIdentity(left.ref).localeCompare(contextRefIdentity(right.ref))));
 }
 /** Lane-specific context that may be layered over an immutable stage base. */
-function collectRunContextOverlays(store, run) {
+function collectTurnContextOverlays(store, run) {
     const role = store.getRole(run.taskId, run.roleName);
     if (role === null)
-        throw new Error(`Run Role not found: ${run.taskId}/${run.roleName}.`);
+        throw new Error(`Turn Role not found: ${run.taskId}/${run.roleName}.`);
     return [
         materialize("L1", "role-profile", role.name, {
             name: role.name,
@@ -514,10 +499,10 @@ function writableProjects(store, run, view) {
 }
 function completionActions(view) {
     if (view === "leader")
-        return Object.freeze(["yield", "complete-task", "request-input"]);
+        return Object.freeze(["finish-turn", "complete-task", "request-input"]);
     if (view === "reviewer")
-        return Object.freeze(["checkpoint", "yield-review"]);
+        return Object.freeze(["checkpoint", "finish-turn"]);
     if (view === "operator")
         return Object.freeze(["answer-input", "recover"]);
-    return Object.freeze(["checkpoint", "yield"]);
+    return Object.freeze(["checkpoint", "finish-turn"]);
 }

package/dist/context/turnInputContract.js

@@ -0,0 +1,204 @@
+import { normalizedUniqueIdentities, 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";
+export const TURN_INPUT_MAX_BYTES = 4 * 1024;
+export const TURN_INPUT_MAX_DELTAS = 16;
+export const YUI_TURN_INPUT_CHANNELS = [
+    "user-message",
+    "input-response",
+    "task-dispatch",
+    "workitem-dispatch",
+    "leader-wakeup",
+    "leader-forced-wakeup"
+];
+export function createTurnInput(input) {
+    const common = normalizeInput(input);
+    return Object.freeze({
+        schemaVersion: TURN_INPUT_PROTOCOL_VERSION,
+        ...common,
+        ...(input.directive === undefined
+            ? {}
+            : { directive: requireText(input.directive, "Turn input directive") })
+    });
+}
+export function validateTurnInput(value) {
+    if (value.schemaVersion !== TURN_INPUT_PROTOCOL_VERSION) {
+        throw new Error("Turn input must use schemaVersion 1.");
+    }
+    const normalized = createTurnInput(value);
+    if (JSON.stringify(normalized) !== JSON.stringify(value)) {
+        throw new Error("Turn input is not canonical.");
+    }
+    return value;
+}
+export function createTurnInputEnvelope(context, input) {
+    validateTurnInput(input);
+    const normalized = normalizeEnvelopeContext(context, input);
+    return Object.freeze({
+        protocol: TURN_INPUT_PROTOCOL,
+        turnId: normalized.turnId,
+        source: input.source,
+        roleName: normalized.roleName,
+        purpose: normalized.purpose,
+        subject: normalized.subject,
+        ...(input.contextSnapshotRef === undefined
+            ? {}
+            : { contextSnapshotRef: input.contextSnapshotRef }),
+        deltaRefIds: input.deltaRefIds
+    });
+}
+export function validateTurnInputEnvelope(value) {
+    if (value.protocol !== TURN_INPUT_PROTOCOL) {
+        throw new Error("Turn input protocol is unsupported.");
+    }
+    normalizeEnvelope(value);
+    const serialized = serializeTurnInputEnvelope(value);
+    if (Buffer.byteLength(serialized, "utf8") > TURN_INPUT_MAX_BYTES) {
+        throw new Error("Turn input envelope exceeds its protocol byte limit.");
+    }
+    return value;
+}
+export function serializeTurnInputEnvelope(value) {
+    if (value.protocol !== TURN_INPUT_PROTOCOL) {
+        throw new Error("Turn input protocol is unsupported.");
+    }
+    const normalized = normalizeEnvelope(value);
+    const subject = Object.entries(normalized.subject)
+        .map(([key, id]) => `${key}:${id}`)
+        .join(",");
+    const snapshot = normalized.contextSnapshotRef;
+    const lines = [
+        "Yui Turn input. Follow the Session Manifest and injected Skills.",
+        `${normalized.subject.taskId === undefined ? "" : `task=${normalized.subject.taskId} `}turn=${normalized.turnId} role=${normalized.roleName}`,
+        `source=${normalized.source.type}/${normalized.source.channel} purpose=${normalized.purpose} subject=${subject || "global"} snapshot=${snapshot === undefined ? "none" : `${snapshot.id}@${snapshot.digest}`}`,
+        normalized.deltaRefIds.length === 0
+            ? "delta=none"
+            : `delta=${normalized.deltaRefIds.join(",")}`,
+        "Load the exact Turn context before acting; fail closed if it is unavailable or mismatched."
+    ];
+    const serialized = lines.join("\n");
+    if (Buffer.byteLength(serialized, "utf8") > TURN_INPUT_MAX_BYTES) {
+        throw new Error("Turn input envelope exceeds its protocol byte limit.");
+    }
+    return serialized;
+}
+/**
+ * Bounded infrastructure-recovery input for an already-submitted Turn. It resumes
+ * the provider-native transcript after Host/child replacement and never
+ * replays the Assignment or its directive.
+ */
+export function serializeTurnHostRecoveryEnvelope(value) {
+    const normalized = normalizeEnvelope(value);
+    const serialized = [
+        "Yui Host recovery for an existing Turn.",
+        `${normalized.subject.taskId === undefined ? "" : `task=${normalized.subject.taskId} `}turn=${normalized.turnId} role=${normalized.roleName}`,
+        "Resume the same native conversation from its latest durable state. Do not repeat completed work or replay the original input.",
+        "Load the exact Turn context or delta only if needed, then continue the same Turn."
+    ].join("\n");
+    if (Buffer.byteLength(serialized, "utf8") > TURN_INPUT_MAX_BYTES) {
+        throw new Error("Turn Host recovery envelope exceeds its protocol byte limit.");
+    }
+    return serialized;
+}
+function normalizeInput(input) {
+    const source = normalizeSource(input.source);
+    const snapshot = input.contextSnapshotRef === undefined
+        ? undefined
+        : validateContextSnapshotRef(input.contextSnapshotRef);
+    const deltaRefIds = normalizedUniqueIdentities(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.`);
+    }
+    return {
+        source,
+        ...(snapshot === undefined ? {} : { contextSnapshotRef: snapshot }),
+        deltaRefIds
+    };
+}
+function normalizeEnvelopeContext(context, input) {
+    const normalized = normalizeEnvelope({
+        protocol: TURN_INPUT_PROTOCOL,
+        turnId: context.turnId,
+        source: input.source,
+        roleName: context.roleName,
+        purpose: context.purpose,
+        subject: context.subject,
+        ...(input.contextSnapshotRef === undefined
+            ? {}
+            : { contextSnapshotRef: input.contextSnapshotRef }),
+        deltaRefIds: input.deltaRefIds
+    });
+    return {
+        turnId: normalized.turnId,
+        roleName: normalized.roleName,
+        purpose: normalized.purpose,
+        subject: normalized.subject
+    };
+}
+function normalizeEnvelope(input) {
+    if (!["execution", "review", "global"].includes(input.purpose)) {
+        throw new Error("Turn input purpose is invalid.");
+    }
+    const normalizedInput = normalizeInput(input);
+    const subject = normalizeSubject(input.subject);
+    if (normalizedInput.contextSnapshotRef !== undefined
+        && normalizedInput.contextSnapshotRef.taskId !== subject.taskId) {
+        throw new Error("Turn input Context Snapshot belongs to another Task.");
+    }
+    if (input.purpose !== "global" && subject.taskId === undefined) {
+        throw new Error("A Task Turn input requires a Task subject.");
+    }
+    if (input.purpose === "review" && subject.reviewRoundId === undefined) {
+        throw new Error("A review Turn input requires a ReviewRound subject.");
+    }
+    return {
+        protocol: TURN_INPUT_PROTOCOL,
+        turnId: requireIdentity(input.turnId, "Turn input Turn id"),
+        source: normalizedInput.source,
+        roleName: requireIdentity(input.roleName, "Turn input Role name"),
+        purpose: input.purpose,
+        subject,
+        ...(normalizedInput.contextSnapshotRef === undefined
+            ? {}
+            : { contextSnapshotRef: normalizedInput.contextSnapshotRef }),
+        deltaRefIds: normalizedInput.deltaRefIds
+    };
+}
+function normalizeSubject(subject) {
+    const normalized = Object.fromEntries(Object.entries(subject).map(([key, value]) => [
+        key,
+        requireIdentity(value, `Turn input ${key}`)
+    ]));
+    const allowed = [
+        "taskId",
+        "workItemId",
+        "reviewRoundId",
+        "executionGroupId",
+        "executionLaneId"
+    ];
+    if (Object.keys(normalized).some((key) => !allowed.includes(key))) {
+        throw new Error("Turn input subject contains an unknown field.");
+    }
+    if ((normalized.executionGroupId === undefined) !== (normalized.executionLaneId === undefined)) {
+        throw new Error("Turn input execution lineage is incomplete.");
+    }
+    if (normalized.taskId === undefined
+        && (normalized.workItemId !== undefined || normalized.reviewRoundId !== undefined
+            || normalized.executionGroupId !== undefined)) {
+        throw new Error("Turn input child subject requires a Task id.");
+    }
+    return Object.freeze(normalized);
+}
+function normalizeSource(source) {
+    if (source.type === "yui" && YUI_TURN_INPUT_CHANNELS.includes(source.channel)) {
+        return Object.freeze({ type: "yui", channel: source.channel });
+    }
+    if (source.type === "user" && source.channel === "direct") {
+        return Object.freeze({ type: "user", channel: "direct" });
+    }
+    if (source.type === "provider" && source.channel === "goal-continuation") {
+        return Object.freeze({ type: "provider", channel: "goal-continuation" });
+    }
+    throw new Error("Turn input source is invalid.");
+}

package/dist/context/wakeNotification.js

@@ -33,7 +33,7 @@ export function buildTaskWakeEnvelope(reader, request) {
             .filter((record) => Date.parse(record.createdAt) > fromTime).length,
         messages: operationalTaskRecords(reader.listMessages(request.taskId), events, "message")
             .filter((record) => Date.parse(record.createdAt) > fromTime).length,
-        runs: operationalTaskRecords(reader.listAgentRuns(request.taskId), events, "agent-run")
+        turns: operationalTaskRecords(reader.listTurns(request.taskId), events, "turn")
             .filter((record) => Date.parse(record.createdAt) > fromTime).length
     };
     const activeReviews = reader.listReviewRounds(request.taskId).filter((round) => ((round.scope ?? "work-item") === "task"
@@ -50,7 +50,7 @@ export function buildTaskWakeEnvelope(reader, request) {
     const lines = [
         `Wake: ${request.wakeId} — delta since ${request.fromCursor}`,
         `  Reasons: ${renderReasons(request.reasons)}`,
-        `  Changed: ${counts.events} events, ${counts.messages} messages, ${counts.runs} runs`
+        `  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"

package/dist/controller/agentRuntimeObserver.js

@@ -5,7 +5,7 @@ const DEFAULT_MAX_CONCURRENT_SAMPLES = 8;
 const MAX_CONCURRENT_SAMPLES = 64;
 /**
  * Controller-owned, provider-independent sampler. Drivers own source parsing;
- * this component owns active-Run discovery, cursor lifetime, canonical event
+ * this component owns active-Turn discovery, cursor lifetime, canonical event
  * creation, and low-latency mailbox wakes.
  */
 export class AgentRuntimeObserver {
@@ -73,7 +73,7 @@ export class AgentRuntimeObserver {
             if (state.usage === undefined) {
                 // Cumulative counters need a lower bound. An exact initial sample
                 // proves the complete Session-generation history even when the
-                // current Run resumed that Session, so preserve every occurrence and
+                // current Turn resumed that Session, so preserve every occurrence and
                 // anchor it at zero. A partial sample cannot prove the omitted request
                 // boundaries; retain its latest total as a partial baseline, plus the
                 // smallest ordered witness if the visible counter already rolled back.
@@ -239,8 +239,8 @@ export class AgentRuntimeObserver {
     activeSources() {
         const result = [];
         const indexedTaskIds = this.store.listActiveTaskIds?.();
-        // FileTaskStore remains a development/compatibility fallback. The normal
-        // Controller store is SQLite and must discover only its indexed hot set.
+        // Stores without the indexed projection remain useful for deterministic
+        // tests. The production SQLite store discovers only its indexed hot set.
         const activeTasks = indexedTaskIds === undefined
             ? this.store.listTasks().filter((task) => (task.status === "active" && task.executionGate.state === "enabled"))
             : [...new Set(indexedTaskIds)]
@@ -251,43 +251,43 @@ export class AgentRuntimeObserver {
                 && task.executionGate.state === "enabled"));
         for (const task of activeTasks) {
             // A Task still incurs one O(E) event projection. Group those observations
-            // by Run and sort each group once so every active Run can reuse the same
+            // by Turn and sort each group once so every active Turn can reuse the same
             // ordered slice instead of repeatedly filtering/sorting all E events.
-            const observationsByRunId = new Map();
+            const observationsByTurnId = new Map();
             const taskObservations = [];
             for (const event of this.store.listEvents(task.id)) {
                 const observation = runtimeObservationFromTaskEvent(event);
-                const runId = observation?.fence.runId;
-                if (observation === null || runId === undefined)
+                const turnId = observation?.fence.turnId;
+                if (observation === null || turnId === undefined)
                     continue;
                 taskObservations.push(observation);
-                const grouped = observationsByRunId.get(runId);
+                const grouped = observationsByTurnId.get(turnId);
                 if (grouped === undefined) {
-                    observationsByRunId.set(runId, [observation]);
+                    observationsByTurnId.set(turnId, [observation]);
                 }
                 else {
                     grouped.push(observation);
                 }
             }
-            for (const observations of observationsByRunId.values()) {
+            for (const observations of observationsByTurnId.values()) {
                 observations.sort(compareObservations);
             }
             taskObservations.sort(compareObservations);
-            for (const run of this.store.listAgentRuns(task.id)) {
+            for (const run of this.store.listTurns(task.id)) {
                 if (run.status !== "active"
-                    || this.store.getActiveAgentRun(task.id, run.roleName)?.id !== run.id)
+                    || this.store.getActiveTurn(task.id, run.roleName)?.id !== run.id)
                     continue;
-                const observations = observationsByRunId.get(run.id) ?? [];
+                const observations = observationsByTurnId.get(run.id) ?? [];
                 const accepted = observations
                     .filter((observation) => observation.kind === "turn.accepted"
-                    && observation.fence.runId === run.id
+                    && observation.fence.turnId === run.id
                     && observation.fence.roleName === run.roleName
                     && observation.fence.agentId === run.effective.agentId
                     && observation.payload.observerSource !== undefined)
                     .at(-1);
                 const source = accepted?.payload.observerSource;
                 if (accepted === undefined || source === undefined
-                    || accepted.fence.taskId === undefined || accepted.fence.runId === undefined)
+                    || accepted.fence.taskId === undefined || accepted.fence.turnId === undefined)
                     continue;
                 try {
                     if (this.drivers.require(accepted.fence.driverId).runtime.observer === undefined)
@@ -313,7 +313,7 @@ export class AgentRuntimeObserver {
                     key: JSON.stringify([
                         fence.taskId,
                         fence.roleName,
-                        fence.runId,
+                        fence.turnId,
                         fence.agentId,
                         fence.driverId,
                         fence.launchId,
@@ -374,7 +374,7 @@ function sampleConcurrency(value) {
     if (!Number.isSafeInteger(resolved)
         || resolved < 1
         || resolved > MAX_CONCURRENT_SAMPLES) {
-        throw new Error(`Agent runtime observer maxConcurrentSamples must be between 1 and ${MAX_CONCURRENT_SAMPLES}.`);
+        throw new Error(`AgentRuntime observer maxConcurrentSamples must be between 1 and ${MAX_CONCURRENT_SAMPLES}.`);
     }
     return resolved;
 }