@zq-silk/yui 0.14.1 → 0.15.0

package/dist/controller/structuredProviderObservation.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { callController } from "../core/controllerClient.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
 import { standardAgentError } from "../runtime/agentError.js";
+import { transportAgentResult } from "../domain/agentResultTransport.js";
 import { createRuntimeObservation, runtimeObservationSemanticKey } from "../runtime/runtimeObservation.js";
 import { runtimeLifecycleSignalKey } from "../runtime/lifecycleReservation.js";
 import { isForeignHandoverLockHeld } from "../release/runtimeRelease.js";
@@ -28,8 +29,7 @@ export async function publishStructuredProviderStarted(input) {
             roleName: fence.roleName,
             agentId: fence.agentId,
             driverId: driver.id,
-            launchId: fence.launchId,
-            sessionGenerationId: fence.launchId,
+            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: input.started.conversationId,
             activationId: requireIdentity(input.activationId, "Provider Activation id"),
             nativeSessionId: input.started.nativeSessionId,
@@ -56,8 +56,7 @@ export async function publishStructuredProviderAccepted(input) {
         ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
         agentId: fence.agentId,
         driverId: driver.id,
-        launchId: fence.launchId,
-        sessionGenerationId: fence.launchId,
+        runtimeGenerationId: fence.runtimeGenerationId,
         conversationId: input.receipt.conversationId,
         activationId: requireIdentity(input.activationId, "Provider Activation id"),
         nativeSessionId: input.receipt.nativeSessionId,
@@ -107,8 +106,7 @@ export async function publishStructuredProviderOpened(input) {
         ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
         agentId: fence.agentId,
         driverId: driver.id,
-        launchId: fence.launchId,
-        sessionGenerationId: fence.launchId,
+        runtimeGenerationId: fence.runtimeGenerationId,
         conversationId: input.conversationId,
         activationId: requireIdentity(input.activationId, "Provider Activation id"),
         nativeSessionId: input.nativeSessionId,
@@ -153,8 +151,7 @@ export async function publishStructuredProviderGoal(input) {
             roleName: fence.roleName,
             agentId: fence.agentId,
             driverId: driver.id,
-            launchId: fence.launchId,
-            sessionGenerationId: fence.launchId,
+            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: input.conversationId,
             activationId: requireIdentity(input.activationId, "Provider Activation id"),
             nativeSessionId: input.conversationId
@@ -180,8 +177,7 @@ export async function publishStructuredConversationRecoverability(input) {
         ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
         agentId: fence.agentId,
         driverId: driver.id,
-        launchId: fence.launchId,
-        sessionGenerationId: fence.launchId,
+        runtimeGenerationId: fence.runtimeGenerationId,
         conversationId: input.conversationId,
         activationId: requireIdentity(input.activationId, "Provider Activation id"),
         nativeSessionId: input.conversationId,
@@ -224,10 +220,13 @@ export async function publishStructuredProviderTerminal(input) {
     const kind = input.terminal.status === "completed"
         ? "turn.completed"
         : input.terminal.status === "cancelled" ? "turn.cancelled" : "turn.failed";
+    const transported = transportAgentResult(input.terminal.output);
     const payload = kind === "turn.completed"
         ? {
             ...(input.terminal.input === undefined ? {} : { input: input.terminal.input }),
-            ...(input.terminal.summary === undefined ? {} : { summary: input.terminal.summary })
+            ...(transported.status === "completed"
+                ? { output: transported.output }
+                : { resultTransportDiagnostic: transported.diagnostic })
         }
         : kind === "turn.failed"
             ? {
@@ -263,8 +262,7 @@ export async function publishStructuredProviderTerminal(input) {
             ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
             agentId: fence.agentId,
             driverId: driver.id,
-            launchId: fence.launchId,
-            sessionGenerationId: fence.launchId,
+            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: input.terminal.conversationId,
             activationId: requireIdentity(input.activationId, "Provider Activation id"),
             nativeSessionId: input.terminal.nativeSessionId,
@@ -290,8 +288,7 @@ export async function publishStructuredProviderActivationTerminal(input) {
             ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
             agentId: fence.agentId,
             driverId: driver.id,
-            launchId: fence.launchId,
-            sessionGenerationId: fence.launchId,
+            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: requireIdentity(input.conversationId, "Provider Conversation id"),
             activationId: requireIdentity(input.activationId, "Provider Activation id"),
             nativeSessionId: requireIdentity(input.nativeSessionId, "native Session id"),
@@ -311,7 +308,7 @@ function observation(input) {
         payload: input.payload ?? {}
     };
     return createRuntimeObservation({
-        schemaVersion: 2,
+        schemaVersion: 4,
         eventId,
         semanticKey: runtimeObservationSemanticKey(partial),
         kind: input.kind,

package/dist/coordination/workMailboxQueue.js

@@ -1,4 +1,11 @@
 import { completeProcessing, consumePendingBatch, createWorkMailbox, enqueueSignal, mailboxBatches, mailboxEntityRefKey } from "./workMailbox.js";
+const LEGACY_ROLE_TURN_DISPATCH_REASONS = new Set([
+    "turn-dispatched",
+    "turn-retried",
+    "review-requested",
+    "workitem-synthesis-ready",
+    "review-synthesis-ready"
+]);
 /** Atomically useful when called inside the caller's TaskStore transaction. */
 export function enqueueWork(store, target, reason, occurredAt, refs = [], metadata = {}) {
     const mailbox = store.getWorkMailbox(target) ?? createWorkMailbox(target);
@@ -11,6 +18,106 @@ export function enqueueWork(store, target, reason, occurredAt, refs = [], metada
     store.saveWorkMailbox(queued);
     return queued;
 }
+/**
+ * The sole ordinary Role Turn wake shape. The Turn is durable execution
+ * authority; this signal only asks the Controller to deliver that exact Turn.
+ * Leader is deliberately excluded because its Role mailbox is reserved for
+ * semantic event wakes and force-steer batches. A Leader active Turn is
+ * selected directly from durable state by its targeted Controller pass.
+ */
+export function enqueueRoleTurnDispatch(store, input) {
+    if (input.roleName === "leader")
+        return null;
+    return enqueueWork(store, roleTurnTarget(input), input.reason, input.occurredAt, [roleTurnRef(input)], {
+        source: "turn-dispatch",
+        dedupeKey: roleTurnDispatchDedupeKey(input)
+    });
+}
+/**
+ * Captures only the mailbox prefix that contains one exact Role Turn dispatch.
+ * A later signal may append while Provider delivery is in flight; its suffix
+ * remains pending when this token is settled.
+ */
+export function captureRoleTurnDispatch(mailbox, input) {
+    if (input.roleName === "leader"
+        || mailbox === null
+        || mailbox.target.kind !== "role"
+        || mailbox.target.taskId !== input.taskId
+        || mailbox.target.roleName !== input.roleName) {
+        return null;
+    }
+    const exactRef = roleTurnRef(input);
+    if (mailbox.processing?.executionRef !== undefined
+        && mailboxEntityRefKey(mailbox.processing.executionRef) === mailboxEntityRefKey(exactRef)) {
+        return {
+            kind: "processing",
+            batchId: mailbox.processing.batchId
+        };
+    }
+    const pending = mailbox.pending;
+    if (pending === null)
+        return null;
+    const dedupeKey = roleTurnDispatchDedupeKey(input);
+    if (mailbox.recentDedupeKeys.includes(dedupeKey))
+        return null;
+    const keyIndex = pending.dedupeKeys.indexOf(dedupeKey);
+    if (keyIndex >= 0 && pending.dedupeKeys.length === pending.requestCount) {
+        const turnSequence = pending.fromSequence + keyIndex;
+        if (turnSequence <= pending.toSequence) {
+            return {
+                kind: "pending",
+                fromSequence: pending.fromSequence,
+                toSequence: turnSequence
+            };
+        }
+    }
+    // Valid earlier dispatches used sequence-generated dedupe keys and could
+    // include a companion WorkItem ref. Consume that complete legacy batch once
+    // the exact Turn reaches an accepted or terminal boundary.
+    if (pending.requestCount === 1
+        && pending.sources.length === 1
+        && pending.sources[0] === "yui"
+        && pending.reasons.some((reason) => LEGACY_ROLE_TURN_DISPATCH_REASONS.has(reason))
+        && pending.refs.some((ref) => (mailboxEntityRefKey(ref) === mailboxEntityRefKey(exactRef)))) {
+        return {
+            kind: "pending",
+            fromSequence: pending.fromSequence,
+            toSequence: pending.toSequence
+        };
+    }
+    return null;
+}
+/**
+ * Settles one exact ordinary Role Turn dispatch. Provider acceptance is the
+ * normal boundary; terminalization calls the same operation for conclusively
+ * unaccepted and valid earlier dispatches.
+ */
+export function settleRoleTurnDispatch(store, input, expected) {
+    if (expected === null)
+        return "absent";
+    const target = roleTurnTarget(input);
+    const mailbox = store.getWorkMailbox(target);
+    const current = captureRoleTurnDispatch(mailbox, input);
+    if (current === null || mailbox === null)
+        return "absent";
+    if (expected !== undefined && !sameRoleTurnDispatchToken(current, expected)) {
+        return "state-changed";
+    }
+    const token = expected ?? current;
+    if (token.kind === "processing") {
+        if (mailbox.processing?.batchId !== token.batchId)
+            return "state-changed";
+        store.saveWorkMailbox(completeProcessing(mailbox, token.batchId));
+        return "settled";
+    }
+    if (mailbox.pending === null
+        || mailbox.pending.fromSequence !== token.fromSequence
+        || mailbox.pending.toSequence < token.toSequence) {
+        return "state-changed";
+    }
+    store.saveWorkMailbox(consumePendingBatch(mailbox, token));
+    return "settled";
+}
 /** Completes only the batch owned by the matching durable execution. */
 export function completeWorkExecution(store, target, executionRef) {
     const mailbox = store.getWorkMailbox(target);
@@ -76,6 +183,31 @@ export function settleExactWorkExecution(store, target, executionRef) {
 function timestamp(value) {
     return value instanceof Date ? value.toISOString() : value;
 }
+function roleTurnTarget(input) {
+    return {
+        kind: "role",
+        taskId: input.taskId,
+        roleName: input.roleName
+    };
+}
+function roleTurnRef(input) {
+    return {
+        type: "turn",
+        taskId: input.taskId,
+        id: input.turnId
+    };
+}
+function roleTurnDispatchDedupeKey(input) {
+    return `role-turn:${input.taskId}:${input.roleName}:${input.turnId}`;
+}
+function sameRoleTurnDispatchToken(left, right) {
+    return left.kind === right.kind
+        && (left.kind === "pending"
+            ? right.kind === "pending"
+                && left.fromSequence === right.fromSequence
+                && left.toSequence === right.toSequence
+            : right.kind === "processing" && left.batchId === right.batchId);
+}
 function targetLabel(target) {
     switch (target.kind) {
         case "operator": return "operator";

package/dist/core/controllerServer.js

@@ -400,8 +400,8 @@ async function routeRequest(socket, line, token, dispatcher, stop, status, telem
                 homeFilesystemId,
                 controllerInstanceId,
                 version: YUI_VERSION,
-                storageLayoutVersion: yuiVersionIdentity().storageLayoutVersion,
-                aggregateSchemaVersion: yuiVersionIdentity().aggregateSchemaVersion,
+                storageVersion: yuiVersionIdentity().storageVersion,
+                minimumStorageVersion: yuiVersionIdentity().minimumStorageVersion,
                 ...(status === undefined ? {} : { runtime: status(telemetry) })
             }
         });
@@ -593,6 +593,7 @@ function parseBeginHandoverParams(value) {
     }
     const fromReleaseId = record.fromReleaseId;
     if (fromReleaseId !== undefined
+        && fromReleaseId !== null
         && (typeof fromReleaseId !== "string" || fromReleaseId.length > 256)) {
         return null;
     }
@@ -674,7 +675,7 @@ export function buildRuntimeIdentityReceipt(input) {
         }
     })();
     return Object.freeze({
-        schemaVersion: 1,
+        schemaVersion: 2,
         version: YUI_VERSION,
         executablePath: process.execPath,
         args: process.argv.slice(1),
@@ -684,8 +685,8 @@ export function buildRuntimeIdentityReceipt(input) {
         cliRealpath: controllerCliRealpath(),
         controllerRealpath: realpathSync(fileURLToPath(import.meta.url)),
         controllerProtocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
-        storageLayoutVersion: yuiVersionIdentity().storageLayoutVersion,
-        aggregateSchemaVersion: yuiVersionIdentity().aggregateSchemaVersion,
+        storageVersion: yuiVersionIdentity().storageVersion,
+        minimumStorageVersion: yuiVersionIdentity().minimumStorageVersion,
         storageBackend: input.storageBackend,
         workerEnabled: input.workerEnabled,
         pid: process.pid,

package/dist/doctor/doctor.js

@@ -34,7 +34,7 @@ export const STORAGE_DOCTOR_CHECK_NAMES = Object.freeze([
  * healthy only when schema, compatibility, and state are all `ok`. Any
  * `unsupported` (version mismatch / needs-new-version), `invalid` (corrupted /
  * unreadable), or `missing` (uninitialized) storage check is blocking — even
- * though `yui doctor` itself exits 0.
+ * and the machine-readable command exits non-zero.
  */
 export function summarizeStorageHealth(checks) {
     const names = new Set(STORAGE_DOCTOR_CHECK_NAMES);
@@ -56,14 +56,16 @@ export function buildDoctorReport(env, executor) {
 }
 /**
  * Read the physical-backend facts for a Home (Issue 01 observability). Every
- * field is best-effort read-only evidence: an unreadable database or manifest
- * yields `null` for that field, and the `storage state` check reports the
- * structural problem separately.
+ * field is best-effort read-only evidence: an unreadable database yields
+ * `null` for that field, and the `storage state` check reports the structural
+ * problem separately.
  */
 function inspectStorageDetails(home, env) {
     const schema = inspectStorageSchema(home);
-    const logicalLayout = schema.status === "current" || schema.status === "unsupported"
-        ? schema.currentLayoutVersion
+    const storageVersion = schema.status === "current"
+        || schema.status === "upgradeable"
+        || schema.status === "unsupported"
+        ? schema.currentVersion
         : null;
     const authoritativeBackend = "sqlite";
     const dbPath = join(home, CURRENT_DATABASE_FILENAME);
@@ -88,7 +90,8 @@ function inspectStorageDetails(home, env) {
         }
     }
     return {
-        logicalLayout,
+        storageVersion,
+        minimumSupportedVersion: schema.minimumSupportedVersion,
         authoritativeBackend,
         databasePath,
         journalMode,
@@ -216,13 +219,22 @@ function checkSchema(state) {
             return {
                 name: "storage schema",
                 status: "ok",
-                detail: `current=${state.currentVersion} latest=${state.latestVersion}`
+                detail: `current=${state.currentVersion} latest=${state.latestVersion} `
+                    + `minimum=${state.minimumSupportedVersion}`
+            };
+        case "upgradeable":
+            return {
+                name: "storage schema",
+                status: "unsupported",
+                detail: `current=${state.currentVersion} latest=${state.latestVersion} `
+                    + `minimum=${state.minimumSupportedVersion} migration=available`
             };
         case "unsupported":
             return {
                 name: "storage schema",
                 status: "unsupported",
-                detail: `current=${state.currentVersion} latest=${state.latestVersion} direction=${state.direction}`
+                detail: `current=${state.currentVersion} latest=${state.latestVersion} `
+                    + `minimum=${state.minimumSupportedVersion} direction=${state.direction}`
             };
         case "invalid":
             return { name: "storage schema", status: "invalid", detail: state.detail };
@@ -251,9 +263,20 @@ function inspectCompatibility(home, homeCheck, schema) {
             check: {
                 name,
                 status: "unsupported",
-                detail: `unsupported contract: ${schema.incompatibleComponent} is ${schema.direction} `
-                    + `(current=${schema.currentVersion}, required=${schema.latestVersion}). `
-                    + "Preserve this Home and initialize a new Home."
+                detail: `storage version is ${schema.direction} `
+                    + `(current=${schema.currentVersion}, supported=`
+                    + `${schema.minimumSupportedVersion}..${schema.latestVersion}).`
+            }
+        };
+    }
+    if (schema.status === "upgradeable") {
+        return {
+            storageStatus: "upgradeable",
+            check: {
+                name,
+                status: "unsupported",
+                detail: `migration available from ${schema.currentVersion} to ${schema.latestVersion}; `
+                    + "run `yui upgrade` or `yui update`."
             }
         };
     }
@@ -262,8 +285,8 @@ function inspectCompatibility(home, homeCheck, schema) {
         check: {
             name,
             status: "ok",
-            detail: `current layout=${schema.currentLayoutVersion}/${schema.latestLayoutVersion} `
-                + `aggregate=${schema.currentAggregateSchemaVersion}/${schema.latestAggregateSchemaVersion}`
+            detail: `current=${schema.currentVersion}/${schema.latestVersion} `
+                + `minimum=${schema.minimumSupportedVersion}`
         }
     };
 }

package/dist/domain/agentResultTransport.js

@@ -0,0 +1,60 @@
+export const MAX_TURN_RESULT_OUTPUT_BYTES = 512 * 1024;
+export const MAX_TURN_FAILURE_DIAGNOSTIC_BYTES = 16 * 1024;
+/**
+ * Validate only the transport envelope of an Agent result. The accepted text
+ * remains byte-for-byte unchanged; missing or untransportable text becomes a
+ * Core-owned failed outcome so the exact Turn can still terminalize.
+ */
+export function transportAgentResult(value) {
+    if (typeof value !== "string") {
+        return {
+            status: "failed",
+            diagnostic: "Provider terminal event did not include an Agent result.",
+            failureReason: "missing-result"
+        };
+    }
+    if (value.includes("\0")) {
+        return {
+            status: "failed",
+            diagnostic: "Provider terminal event included an Agent result with an invalid NUL byte.",
+            failureReason: "missing-result"
+        };
+    }
+    if (value.trim().length === 0) {
+        return {
+            status: "failed",
+            diagnostic: "Provider terminal event included an empty Agent result.",
+            failureReason: "missing-result"
+        };
+    }
+    const bytes = Buffer.byteLength(value, "utf8");
+    if (bytes > MAX_TURN_RESULT_OUTPUT_BYTES) {
+        return {
+            status: "failed",
+            diagnostic: `Provider Agent result is ${bytes} bytes and exceeds the ${MAX_TURN_RESULT_OUTPUT_BYTES}-byte durable result limit; the result was not stored.`,
+            failureReason: "missing-result"
+        };
+    }
+    return { status: "completed", output: value };
+}
+/**
+ * Bound Core-owned failure diagnostics without rejecting a terminal event.
+ * This is intentionally separate from Agent result transport: successful
+ * Agent text is either retained exactly or rejected as a whole, never
+ * truncated. Provider/Core diagnostics may be clipped because they are only
+ * operational context for a failed Turn.
+ */
+export function boundedTurnFailureDiagnostic(value, fallback = "Provider reported a failed Agent Turn.") {
+    const candidate = typeof value === "string" && value.trim().length > 0
+        ? value
+        : fallback;
+    const safe = candidate.replaceAll("\0", "\uFFFD");
+    if (Buffer.byteLength(safe, "utf8") <= MAX_TURN_FAILURE_DIAGNOSTIC_BYTES) {
+        return safe;
+    }
+    const prefix = Buffer
+        .from(safe, "utf8")
+        .subarray(0, MAX_TURN_FAILURE_DIAGNOSTIC_BYTES)
+        .toString("utf8");
+    return prefix.endsWith("\uFFFD") ? prefix.slice(0, -1) : prefix;
+}