@zq-silk/yui 0.13.7 → 0.13.9

package/dist/storage/migration/productionRegistry.js

@@ -51,6 +51,8 @@ const AGENT_RUN_CONTEXT_PROTOCOL_FROM_VERSION = 7;
 const AGENT_RUN_CONTEXT_PROTOCOL_TO_VERSION = 8;
 const AGENT_RUN_RETRY_EPISODE_FROM_VERSION = 8;
 const AGENT_RUN_RETRY_EPISODE_TO_VERSION = 9;
+const AGENT_RUN_ERROR_FACTS_FROM_VERSION = 9;
+const AGENT_RUN_ERROR_FACTS_TO_VERSION = 10;
 const MESSAGE_WAKE_POLICY_FROM_VERSION = 2;
 const MESSAGE_WAKE_POLICY_TO_VERSION = 3;
 const REVIEW_ROUND_FROM_VERSION = 2;
@@ -99,16 +101,28 @@ const RELEASE_WORKFLOW_FROM_VERSION = 0;
 const RELEASE_WORKFLOW_TO_VERSION = 1;
 const WORK_MAILBOX_FROM_VERSION = 1;
 const WORK_MAILBOX_TO_VERSION = 2;
+const HOST_OWNED_WORK_MAILBOX_FROM_VERSION = 2;
+const HOST_OWNED_WORK_MAILBOX_TO_VERSION = 3;
+const TASK_ROLE_FROM_VERSION = 3;
+const TASK_ROLE_TO_VERSION = 4;
 const TASK_ROLE_SESSION_SET_FROM_VERSION = 4;
 const TASK_ROLE_SESSION_SET_TO_VERSION = 5;
 const STRUCTURED_PROVIDER_SESSION_SET_FROM_VERSION = 5;
 const STRUCTURED_PROVIDER_SESSION_SET_TO_VERSION = 6;
+const AGENT_FIRST_SESSION_SET_FROM_VERSION = 6;
+const AGENT_FIRST_SESSION_SET_TO_VERSION = 7;
+const UNIFIED_TASK_SESSION_SET_FROM_VERSION = 7;
+const UNIFIED_TASK_SESSION_SET_TO_VERSION = 8;
+const UNIFIED_GLOBAL_SESSION_SET_FROM_VERSION = 3;
+const UNIFIED_GLOBAL_SESSION_SET_TO_VERSION = 4;
 const PUBLICATION_REFERENCE_FROM_VERSION = 0;
 const PUBLICATION_REFERENCE_TO_VERSION = 1;
 const CONFIG_FROM_VERSION = 1;
 const CONFIG_TO_VERSION = 2;
 const CONFIG_REVIEW_CONTROLS_FROM_VERSION = 2;
 const CONFIG_REVIEW_CONTROLS_TO_VERSION = 3;
+const CONFIG_AGENT_RECOVERY_FROM_VERSION = 3;
+const CONFIG_AGENT_RECOVERY_TO_VERSION = 4;
 /**
  * Build the authoritative production graph. Transition intent and executable
  * transforms are registered together here; compatible loading and offline
@@ -159,6 +173,7 @@ export function createProductionStorageRegistry() {
         .registerOfflineMigration(projectOwnershipStep())
         .registerOfflineMigration(configV2Step())
         .registerOfflineMigration(configReviewControlsRemovalStep())
+        .registerOfflineMigration(configAgentRecoveryStep())
         .registerCompatible(projectKnowledgeProposalsStep())
         .registerCompatible(projectLifecycleStep())
         .registerOfflineMigration(taskWorkspaceIdentityStep())
@@ -179,6 +194,7 @@ export function createProductionStorageRegistry() {
         .registerOfflineMigration(recordFamilyStep("agentRun", AGENT_RUN_OPTIONAL_FIELDS_FROM_VERSION, AGENT_RUN_OPTIONAL_FIELDS_TO_VERSION, "agentRuns"))
         .registerOfflineMigration(agentRunContextProtocolStep())
         .registerOfflineMigration(agentRunRetryEpisodeStep())
+        .registerOfflineMigration(agentRunErrorFactsStep())
         .registerOfflineMigration(messageWakePolicyStep())
         .registerOfflineMigration(recordFamilyStep("reviewRound", REVIEW_ROUND_FROM_VERSION, REVIEW_ROUND_TO_VERSION, "reviewRounds"))
         .registerOfflineMigration(recordFamilyStep("reviewRound", REVIEW_ROUND_GIT_SNAPSHOT_FROM_VERSION, REVIEW_ROUND_GIT_SNAPSHOT_TO_VERSION, "reviewRounds"))
@@ -203,12 +219,71 @@ export function createProductionStorageRegistry() {
         .registerOfflineMigration(capabilityGrantIntroductionStep())
         .registerOfflineMigration(releaseWorkflowIntroductionStep())
         .registerOfflineMigration(workMailboxV2Step())
+        .registerOfflineMigration(hostOwnedWorkMailboxStep())
+        .registerOfflineMigration(agentRunOwnedTaskRoleStep())
         .registerOfflineMigration(taskRoleSessionSetV5Step())
         .registerOfflineMigration(structuredProviderSessionSetV6Step())
+        .registerOfflineMigration(agentFirstSessionSetV7Step())
+        .registerOfflineMigration(unifiedTaskSessionSetStep())
+        .registerOfflineMigration(unifiedGlobalSessionSetStep())
         .registerOfflineMigration(publicationReferenceIntroductionStep());
     assertRegistryCoversBaselineToCurrent(registry);
     return registry;
 }
+/** Removes the independently writable Role runtime projection; AgentRun owns workflow activity. */
+function agentRunOwnedTaskRoleStep() {
+    return {
+        axis: "record",
+        recordKind: "taskRole",
+        fromVersion: TASK_ROLE_FROM_VERSION,
+        toVersion: TASK_ROLE_TO_VERSION,
+        preconditions: requireTaskRoleV3Family,
+        transform: migrateTaskRoleV3ToV4,
+        declaredEffects: []
+    };
+}
+function requireTaskRoleV3Family(snapshot) {
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (versions.taskRole !== TASK_ROLE_FROM_VERSION) {
+        throw new Error(`Record taskRole migration requires manifest version ${TASK_ROLE_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    for (const [taskId, rawAggregate] of Object.entries(tasks)) {
+        const aggregate = asObject(rawAggregate, `Task aggregate ${taskId}`);
+        const roles = asObject(aggregate.roles, `Task Roles ${taskId}`);
+        for (const [roleName, rawRole] of Object.entries(roles)) {
+            const role = asObject(rawRole, `Task Role ${taskId}/${roleName}`);
+            if (role.schemaVersion !== TASK_ROLE_FROM_VERSION) {
+                throw new Error(`Task Role ${taskId}/${roleName} must use schemaVersion ${TASK_ROLE_FROM_VERSION}.`);
+            }
+        }
+    }
+}
+function migrateTaskRoleV3ToV4(snapshot) {
+    requireTaskRoleV3Family(snapshot);
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...versions, taskRole: TASK_ROLE_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = Object.fromEntries(Object.entries(tasks).map(([taskId, rawAggregate]) => {
+        const aggregate = asObject(rawAggregate, `Task aggregate ${taskId}`);
+        const roles = asObject(aggregate.roles, `Task Roles ${taskId}`);
+        const nextRoles = Object.fromEntries(Object.entries(roles).map(([roleName, rawRole]) => {
+            const role = asObject(rawRole, `Task Role ${taskId}/${roleName}`);
+            const { status: _status, ...retained } = role;
+            void _status;
+            return [roleName, { ...retained, schemaVersion: TASK_ROLE_TO_VERSION }];
+        }));
+        return [taskId, { ...aggregate, roles: nextRoles }];
+    }));
+    return { schemaManifest, state: { ...snapshot.state, tasks: nextTasks } };
+}
 function configV2Step() {
     return {
         axis: "record",
@@ -319,6 +394,53 @@ function migrateConfigV2ToV3(snapshot) {
         }
     };
 }
+/** Removes Core-owned Provider retry policy; recovery is chosen from AgentError facts. */
+function configAgentRecoveryStep() {
+    return {
+        axis: "record",
+        recordKind: "config",
+        fromVersion: CONFIG_AGENT_RECOVERY_FROM_VERSION,
+        toVersion: CONFIG_AGENT_RECOVERY_TO_VERSION,
+        preconditions: requireConfigV3,
+        transform: migrateConfigV3ToV4,
+        declaredEffects: []
+    };
+}
+function requireConfigV3(snapshot) {
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (versions.config !== CONFIG_AGENT_RECOVERY_FROM_VERSION) {
+        throw new Error(`Record config migration requires manifest version ${CONFIG_AGENT_RECOVERY_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const config = asObject(snapshot.state.config, "Yui config");
+    if (config.schemaVersion !== CONFIG_AGENT_RECOVERY_FROM_VERSION) {
+        throw new Error(`Yui config must use schemaVersion ${CONFIG_AGENT_RECOVERY_FROM_VERSION} before migration.`);
+    }
+}
+function migrateConfigV3ToV4(snapshot) {
+    requireConfigV3(snapshot);
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...versions, config: CONFIG_AGENT_RECOVERY_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const config = asObject(snapshot.state.config, "Yui config");
+    const { providerRetryMode: _mode, providerRetryAdapters: _adapters, providerRetryDelaysSeconds: _delays, providerRetryMaxWindowSeconds: _window, ...retained } = config;
+    void _mode;
+    void _adapters;
+    void _delays;
+    void _window;
+    return {
+        schemaManifest,
+        state: {
+            ...snapshot.state,
+            config: { ...retained, schemaVersion: CONFIG_AGENT_RECOVERY_TO_VERSION }
+        }
+    };
+}
 function workItemExecutionGroupHistoryStep() {
     return {
         axis: "record",
@@ -2185,6 +2307,46 @@ function migrateAgentRunsToRetryEpisodes(snapshot) {
     }
     return { schemaManifest, state: { ...snapshot.state, tasks: nextTasks } };
 }
+/** Deletes the retired retry episode; an AgentRun now records scheduling only. */
+function agentRunErrorFactsStep() {
+    return {
+        axis: "record",
+        recordKind: "agentRun",
+        fromVersion: AGENT_RUN_ERROR_FACTS_FROM_VERSION,
+        toVersion: AGENT_RUN_ERROR_FACTS_TO_VERSION,
+        preconditions: (snapshot) => requireRecordFamilyVersion(snapshot, "agentRun", AGENT_RUN_ERROR_FACTS_FROM_VERSION, "agentRuns"),
+        transform: migrateAgentRunsToErrorFacts,
+        declaredEffects: []
+    };
+}
+function migrateAgentRunsToErrorFacts(snapshot) {
+    requireRecordFamilyVersion(snapshot, "agentRun", AGENT_RUN_ERROR_FACTS_FROM_VERSION, "agentRuns");
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...versions, agentRun: AGENT_RUN_ERROR_FACTS_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        const records = asObject(task.agentRuns ?? {}, `agentRun map ${taskId}`);
+        const nextRecords = {};
+        for (const [runId, rawRecord] of Object.entries(records)) {
+            const record = asObject(rawRecord, `agentRun ${taskId}/${runId}`);
+            const { providerRetry: _retry, ...retained } = record;
+            void _retry;
+            nextRecords[runId] = {
+                ...retained,
+                schemaVersion: AGENT_RUN_ERROR_FACTS_TO_VERSION
+            };
+        }
+        nextTasks[taskId] = { ...task, agentRuns: nextRecords };
+    }
+    return { schemaManifest, state: { ...snapshot.state, tasks: nextTasks } };
+}
 function requiredMigrationPositiveInteger(value, label) {
     if (!Number.isSafeInteger(value) || value < 1) {
         throw new Error(`${label} must be a positive integer.`);
@@ -2623,6 +2785,77 @@ function migrateWorkMailboxV1ToV2(snapshot) {
         state: { ...snapshot.state, mailboxes: nextMailboxes }
     };
 }
+/** A Host launch reservation belongs to the Role owner and launchId, never a Run. */
+function hostOwnedWorkMailboxStep() {
+    return {
+        axis: "record",
+        recordKind: "workMailbox",
+        fromVersion: HOST_OWNED_WORK_MAILBOX_FROM_VERSION,
+        toVersion: HOST_OWNED_WORK_MAILBOX_TO_VERSION,
+        preconditions: requireWorkMailboxV2Family,
+        transform: migrateWorkMailboxV2ToV3,
+        declaredEffects: []
+    };
+}
+function requireWorkMailboxV2Family(snapshot) {
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (versions.workMailbox !== HOST_OWNED_WORK_MAILBOX_FROM_VERSION) {
+        throw new Error(`Record workMailbox migration requires manifest version ${HOST_OWNED_WORK_MAILBOX_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const mailboxes = asObject(snapshot.state.mailboxes, "state mailboxes");
+    for (const [key, rawMailbox] of Object.entries(mailboxes)) {
+        const mailbox = asObject(rawMailbox, `WorkMailbox ${key}`);
+        if (mailbox.schemaVersion !== HOST_OWNED_WORK_MAILBOX_FROM_VERSION) {
+            throw new Error(`WorkMailbox ${key} must use schemaVersion ${HOST_OWNED_WORK_MAILBOX_FROM_VERSION}.`);
+        }
+    }
+}
+function migrateWorkMailboxV2ToV3(snapshot) {
+    requireWorkMailboxV2Family(snapshot);
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...versions, workMailbox: HOST_OWNED_WORK_MAILBOX_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const mailboxes = asObject(snapshot.state.mailboxes, "state mailboxes");
+    const nextMailboxes = {};
+    for (const [key, rawMailbox] of Object.entries(mailboxes)) {
+        const mailbox = asObject(rawMailbox, `WorkMailbox ${key}`);
+        const target = asObject(mailbox.target, `WorkMailbox ${key} target`);
+        const processing = mailbox.processing === null
+            ? null
+            : asObject(mailbox.processing, `WorkMailbox ${key} processing`);
+        const batch = processing === null
+            ? null
+            : asObject(processing.batch, `WorkMailbox ${key} processing batch`);
+        const lifecycleReservation = (target.kind === "role-runtime"
+            || target.kind === "global-role-runtime")
+            && Array.isArray(batch?.reasons)
+            && batch.reasons.includes("runtime-launch-reserved");
+        const nextProcessing = processing === null
+            ? null
+            : lifecycleReservation
+                ? (() => {
+                    const { executionRef: _run, ...retained } = processing;
+                    void _run;
+                    return retained;
+                })()
+                : processing;
+        nextMailboxes[key] = {
+            ...mailbox,
+            schemaVersion: HOST_OWNED_WORK_MAILBOX_TO_VERSION,
+            processing: nextProcessing
+        };
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, mailboxes: nextMailboxes }
+    };
+}
 /**
  * v1 used `processing` for both internal/initial dispatch ownership and later
  * model input.  A crashed later input may already have reached the provider;
@@ -2718,6 +2951,248 @@ function structuredProviderSessionSetV6Step() {
         declaredEffects: []
     };
 }
+/**
+ * A Provider binding describes one reusable Conversation. Run correlation now
+ * belongs to the concrete Provider Turn instead of making the Conversation a
+ * second writable projection of the current AgentRun.
+ */
+function agentFirstSessionSetV7Step() {
+    return {
+        axis: "record",
+        recordKind: "taskRoleSessionSet",
+        fromVersion: AGENT_FIRST_SESSION_SET_FROM_VERSION,
+        toVersion: AGENT_FIRST_SESSION_SET_TO_VERSION,
+        preconditions: requireTaskRoleSessionSetV6Family,
+        transform: migrateTaskRoleSessionSetV6ToV7,
+        declaredEffects: []
+    };
+}
+function requireTaskRoleSessionSetV6Family(snapshot) {
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (versions.taskRoleSessionSet !== AGENT_FIRST_SESSION_SET_FROM_VERSION) {
+        throw new Error(`Record taskRoleSessionSet migration requires manifest version ${AGENT_FIRST_SESSION_SET_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    for (const [taskId, rawAggregate] of Object.entries(tasks)) {
+        const aggregate = asObject(rawAggregate, `Task aggregate ${taskId}`);
+        const sets = asObject(aggregate.roleSessionSets, `Task Role session sets ${taskId}`);
+        for (const [roleName, rawSet] of Object.entries(sets)) {
+            const set = asObject(rawSet, `Task Role session set ${taskId}/${roleName}`);
+            if (set.schemaVersion !== AGENT_FIRST_SESSION_SET_FROM_VERSION) {
+                throw new Error(`Task Role session set ${taskId}/${roleName} must use schemaVersion ${AGENT_FIRST_SESSION_SET_FROM_VERSION}.`);
+            }
+            if (set.providerBinding !== null) {
+                const binding = asObject(set.providerBinding, `Provider Binding ${taskId}/${roleName}`);
+                if (binding.schemaVersion !== 2 || typeof binding.runId !== "string") {
+                    throw new Error(`Provider Binding ${taskId}/${roleName} must use schemaVersion 2.`);
+                }
+            }
+        }
+    }
+}
+function migrateTaskRoleSessionSetV6ToV7(snapshot) {
+    requireTaskRoleSessionSetV6Family(snapshot);
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: {
+            ...versions,
+            taskRoleSessionSet: AGENT_FIRST_SESSION_SET_TO_VERSION
+        }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawAggregate] of Object.entries(tasks)) {
+        const aggregate = asObject(rawAggregate, `Task aggregate ${taskId}`);
+        const rawSets = asObject(aggregate.roleSessionSets, `Task Role session sets ${taskId}`);
+        const nextSets = {};
+        for (const [roleName, rawSet] of Object.entries(rawSets)) {
+            const set = asObject(rawSet, `Task Role session set ${taskId}/${roleName}`);
+            let providerBinding = null;
+            if (set.providerBinding !== null) {
+                const binding = asObject(set.providerBinding, `Provider Binding ${taskId}/${roleName}`);
+                const { runId, ...conversation } = binding;
+                providerBinding = {
+                    ...conversation,
+                    schemaVersion: 3,
+                    turn: binding.turn === null
+                        ? null
+                        : { ...asObject(binding.turn, `Provider Turn ${taskId}/${roleName}`), runId }
+                };
+            }
+            nextSets[roleName] = {
+                ...set,
+                schemaVersion: AGENT_FIRST_SESSION_SET_TO_VERSION,
+                providerBinding
+            };
+        }
+        nextTasks[taskId] = { ...aggregate, roleSessionSets: nextSets };
+    }
+    return { schemaManifest, state: { ...snapshot.state, tasks: nextTasks } };
+}
+/** Session stores existence only; Host readiness and Turn activity are runtime facts. */
+function unifiedTaskSessionSetStep() {
+    return {
+        axis: "record",
+        recordKind: "taskRoleSessionSet",
+        fromVersion: UNIFIED_TASK_SESSION_SET_FROM_VERSION,
+        toVersion: UNIFIED_TASK_SESSION_SET_TO_VERSION,
+        preconditions: requireTaskRoleSessionSetV7Family,
+        transform: migrateTaskRoleSessionSetV7ToV8,
+        declaredEffects: []
+    };
+}
+function requireTaskRoleSessionSetV7Family(snapshot) {
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (versions.taskRoleSessionSet !== UNIFIED_TASK_SESSION_SET_FROM_VERSION) {
+        throw new Error(`Record taskRoleSessionSet migration requires manifest version ${UNIFIED_TASK_SESSION_SET_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    for (const [taskId, rawAggregate] of Object.entries(tasks)) {
+        const aggregate = asObject(rawAggregate, `Task aggregate ${taskId}`);
+        const sets = asObject(aggregate.roleSessionSets, `Task Role session sets ${taskId}`);
+        for (const [roleName, rawSet] of Object.entries(sets)) {
+            const set = asObject(rawSet, `Task Role session set ${taskId}/${roleName}`);
+            if (set.schemaVersion !== UNIFIED_TASK_SESSION_SET_FROM_VERSION) {
+                throw new Error(`Task Role session set ${taskId}/${roleName} must use schemaVersion ${UNIFIED_TASK_SESSION_SET_FROM_VERSION}.`);
+            }
+        }
+    }
+}
+function migrateTaskRoleSessionSetV7ToV8(snapshot) {
+    requireTaskRoleSessionSetV7Family(snapshot);
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: {
+            ...versions,
+            taskRoleSessionSet: UNIFIED_TASK_SESSION_SET_TO_VERSION
+        }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawAggregate] of Object.entries(tasks)) {
+        const aggregate = asObject(rawAggregate, `Task aggregate ${taskId}`);
+        const sets = asObject(aggregate.roleSessionSets, `Task Role session sets ${taskId}`);
+        const nextSets = {};
+        for (const [roleName, rawSet] of Object.entries(sets)) {
+            const set = asObject(rawSet, `Task Role session set ${taskId}/${roleName}`);
+            const sessions = migrateRoleAgentSessionMap(set.sessions, `Task Role sessions ${taskId}/${roleName}`);
+            const history = set.history === undefined
+                ? undefined
+                : migrateRoleAgentSessionArray(set.history, `Task Role session history ${taskId}/${roleName}`);
+            nextSets[roleName] = {
+                ...set,
+                schemaVersion: UNIFIED_TASK_SESSION_SET_TO_VERSION,
+                sessions,
+                ...(history === undefined ? {} : { history })
+            };
+        }
+        nextTasks[taskId] = { ...aggregate, roleSessionSets: nextSets };
+    }
+    return { schemaManifest, state: { ...snapshot.state, tasks: nextTasks } };
+}
+function unifiedGlobalSessionSetStep() {
+    return {
+        axis: "record",
+        recordKind: "globalRoleSessionSet",
+        fromVersion: UNIFIED_GLOBAL_SESSION_SET_FROM_VERSION,
+        toVersion: UNIFIED_GLOBAL_SESSION_SET_TO_VERSION,
+        preconditions: requireGlobalRoleSessionSetV3Family,
+        transform: migrateGlobalRoleSessionSetV3ToV4,
+        declaredEffects: []
+    };
+}
+function requireGlobalRoleSessionSetV3Family(snapshot) {
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (versions.globalRoleSessionSet !== UNIFIED_GLOBAL_SESSION_SET_FROM_VERSION) {
+        throw new Error(`Record globalRoleSessionSet migration requires manifest version ${UNIFIED_GLOBAL_SESSION_SET_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const sets = asObject(snapshot.state.globalRoleSessionSets, "Global Role session sets");
+    for (const [roleName, rawSet] of Object.entries(sets)) {
+        const set = asObject(rawSet, `Global Role session set ${roleName}`);
+        if (set.schemaVersion !== UNIFIED_GLOBAL_SESSION_SET_FROM_VERSION) {
+            throw new Error(`Global Role session set ${roleName} must use schemaVersion ${UNIFIED_GLOBAL_SESSION_SET_FROM_VERSION}.`);
+        }
+    }
+}
+function migrateGlobalRoleSessionSetV3ToV4(snapshot) {
+    requireGlobalRoleSessionSetV3Family(snapshot);
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: {
+            ...versions,
+            globalRoleSessionSet: UNIFIED_GLOBAL_SESSION_SET_TO_VERSION
+        }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const sets = asObject(snapshot.state.globalRoleSessionSets, "Global Role session sets");
+    const nextSets = {};
+    for (const [roleName, rawSet] of Object.entries(sets)) {
+        const set = asObject(rawSet, `Global Role session set ${roleName}`);
+        const history = set.history === undefined
+            ? undefined
+            : migrateRoleAgentSessionMap(set.history, `Global Role session history ${roleName}`);
+        nextSets[roleName] = {
+            ...set,
+            schemaVersion: UNIFIED_GLOBAL_SESSION_SET_TO_VERSION,
+            sessions: migrateRoleAgentSessionMap(set.sessions, `Global Role sessions ${roleName}`),
+            ...(history === undefined ? {} : { history })
+        };
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, globalRoleSessionSets: nextSets }
+    };
+}
+function migrateRoleAgentSessionMap(value, label) {
+    const sessions = asObject(value, label);
+    return Object.fromEntries(Object.entries(sessions).map(([key, session]) => [
+        key,
+        migrateRoleAgentSessionV3(session, `${label}/${key}`)
+    ]));
+}
+function migrateRoleAgentSessionArray(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array.`);
+    return value.map((session, index) => migrateRoleAgentSessionV3(session, `${label}/${String(index)}`));
+}
+function migrateRoleAgentSessionV3(value, label) {
+    const session = asObject(value, label);
+    if (session.schemaVersion !== 3) {
+        throw new Error(`${label} must use schemaVersion 3.`);
+    }
+    const status = session.status;
+    if (status !== "reserved"
+        && status !== "ready"
+        && status !== "running"
+        && status !== "stopped"
+        && status !== "broken") {
+        throw new Error(`${label} has an invalid Session status.`);
+    }
+    const { status: _status, ...retained } = session;
+    void _status;
+    return {
+        ...retained,
+        schemaVersion: 4,
+        status: status === "stopped" || status === "broken" ? "ended" : "active",
+        ...(status === "stopped"
+            ? { endReason: "stopped" }
+            : status === "broken" ? { endReason: "failed" } : {})
+    };
+}
 function requireTaskRoleSessionSetV5Family(snapshot) {
     const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
     if (versions.taskRoleSessionSet !== STRUCTURED_PROVIDER_SESSION_SET_FROM_VERSION) {

package/dist/storage/sqliteSchema.js

@@ -27,7 +27,7 @@ export const SQLITE_LAYOUT_VERSION = 7;
 /** The aggregate version of the normalized SQLite schema. */
 export const SQLITE_AGGREGATE_VERSION = 1;
 /** The current schema migration version. */
-export const SQLITE_SCHEMA_VERSION = 17;
+export const SQLITE_SCHEMA_VERSION = 18;
 /** Telemetry retention bounds (§4.4). Open question 3 in §11; defaults from the design. */
 export const TELEMETRY_KEEP_PER_GENERATION = 200;
 export const TELEMETRY_RUN_CAP = 50_000;
@@ -934,6 +934,57 @@ CREATE TABLE IF NOT EXISTS context_snapshots (
 CREATE UNIQUE INDEX IF NOT EXISTS idx_context_snapshots_scope_sequence
   ON context_snapshots(task_id, scope, COALESCE(scope_ref, ''), sequence);
 `;
+/**
+ * Migration 18: align the current-Session hot projection with Session v4.
+ *
+ * Session existence now has one lifecycle: active or ended. Ended Sessions do
+ * not belong in this bounded projection, so row presence itself means active;
+ * the projection carries no independently writable lifecycle status. Host
+ * cleanup is derived solely from whether the Session still names a Host
+ * activation. Valid earlier live rows are projected into that contract;
+ * terminal broken rows disappear with the rest of ended Session history.
+ */
+const MIGRATION_18_SQL = `
+DROP INDEX idx_runtime_session_cleanup_required;
+ALTER TABLE runtime_session_candidates RENAME TO runtime_session_candidates_v11;
+
+CREATE TABLE runtime_session_candidates (
+  scope               TEXT NOT NULL CHECK (scope IN ('task','global')),
+  task_id             TEXT NOT NULL,
+  role_name           TEXT NOT NULL,
+  agent_id            TEXT NOT NULL,
+  adapter_id          TEXT NOT NULL,
+  native_session_id   TEXT NOT NULL,
+  launch_id           TEXT,
+  session_updated_at  TEXT NOT NULL,
+  cleanup_required    INTEGER NOT NULL CHECK (cleanup_required IN (0,1)),
+  PRIMARY KEY (scope, task_id, role_name),
+  CHECK (
+    (scope = 'task' AND length(task_id) > 0)
+    OR (scope = 'global' AND task_id = '')
+  ),
+  CHECK (
+    cleanup_required = CASE WHEN launch_id IS NOT NULL THEN 1 ELSE 0 END
+  )
+);
+
+INSERT INTO runtime_session_candidates (
+  scope, task_id, role_name, agent_id, adapter_id, native_session_id,
+  launch_id, session_updated_at, cleanup_required
+)
+SELECT
+  scope, task_id, role_name, agent_id, adapter_id, native_session_id,
+  launch_id, session_updated_at,
+  CASE WHEN launch_id IS NOT NULL THEN 1 ELSE 0 END
+FROM runtime_session_candidates_v11
+WHERE status IN ('reserved','ready','running');
+
+DROP TABLE runtime_session_candidates_v11;
+
+CREATE INDEX idx_runtime_session_cleanup_required
+  ON runtime_session_candidates(scope, task_id, role_name)
+  WHERE cleanup_required = 1;
+`;
 /**
  * The single forward migration history for current SQLite Homes. New durable
  * layout, aggregate, and record changes belong here and must be expressible as
@@ -957,7 +1008,8 @@ const MIGRATIONS = [
     { version: 14, axis: "record", recordKind: "workMailbox", sql: MIGRATION_14_SQL },
     { version: 15, axis: "record", recordKind: "publicationReference", sql: MIGRATION_15_SQL },
     { version: 16, axis: "record", recordKind: "taskWake", sql: MIGRATION_16_SQL },
-    { version: 17, axis: "record", recordKind: "contextSnapshot", sql: MIGRATION_17_SQL }
+    { version: 17, axis: "record", recordKind: "contextSnapshot", sql: MIGRATION_17_SQL },
+    { version: 18, axis: "layout", sql: MIGRATION_18_SQL }
 ];
 /** Current hot-path indexes whose absence would invalidate a current Home. */
 const REQUIRED_SCHEMA_INDEXES = [