@zq-silk/yui 0.2.0 → 0.4.2

package/dist/storage/upgrade/offlineUpgradeInventory.js

@@ -0,0 +1,315 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { scanControllerResourceInventory } from "../../controller/resourceInventoryLinux.js";
+import { STORAGE_STATE_FILE } from "../taskStore.js";
+/** Pure blocker policy shared by synthetic tests and the real read-only scan. */
+export function classifyOfflineUpgradeFacts(facts) {
+    const blockers = [];
+    for (const run of facts.runs) {
+        if (run.status !== "active")
+            continue;
+        blockers.push(identity(run, "active-run"));
+    }
+    for (const session of facts.sessions) {
+        if (session.processState === "live") {
+            blockers.push(identity(session, "native-session-live"));
+        }
+        else if (session.processState === "unknown") {
+            blockers.push(identity(session, "native-session-unknown"));
+        }
+    }
+    for (const inFlight of facts.inFlight) {
+        blockers.push(identity(inFlight, "in-flight-run"));
+    }
+    for (const completion of facts.pendingCompletions) {
+        blockers.push(identity(completion, "pending-completion"));
+    }
+    for (const lifecycle of facts.lifecycle) {
+        blockers.push(identity(lifecycle, lifecycle.reason));
+    }
+    for (const unknown of facts.unknownRuntime ?? []) {
+        blockers.push(identity(unknown, "native-session-unknown"));
+    }
+    return { total: blockers.length, blockers };
+}
+/**
+ * Re-read durable Run/RoleSessionSet/lifecycle facts and the native process
+ * inventory without mutating, stopping, acknowledging, or quarantining them.
+ */
+export async function inspectOfflineUpgradeInventory(home, environment = process.env) {
+    const inventory = await scanControllerResourceInventory({
+        currentHome: home,
+        scope: "current",
+        environment
+    });
+    const raw = readRawFacts(home, inventory);
+    return classifyOfflineUpgradeFacts(raw);
+}
+function readRawFacts(home, inventory) {
+    const runs = [];
+    const sessions = [];
+    const inFlight = [];
+    const pendingCompletions = [];
+    const lifecycle = [];
+    const unknownRuntime = [];
+    const state = readStateObject(home);
+    // Failure to enumerate processes, panes, or sockets means absence cannot be
+    // proven. Ownership-load warnings are expected for an old record shape and
+    // are handled by the raw durable scan plus unowned live-pane check below.
+    if (inventory.warnings.some(isUndeterminableNativeInventoryWarning)) {
+        unknownRuntime.push({});
+    }
+    for (const [taskId, aggregateValue] of Object.entries(record(state.tasks))) {
+        const aggregate = record(aggregateValue);
+        for (const runValue of Object.values(record(aggregate.agentRuns))) {
+            const run = record(runValue);
+            const roleName = text(run.roleName);
+            const runId = text(run.id);
+            if (roleName === undefined || runId === undefined)
+                continue;
+            runs.push({ taskId, roleName, runId, status: text(run.status) ?? "unknown" });
+        }
+        for (const [roleName, setValue] of Object.entries(record(aggregate.roleSessionSets))) {
+            collectSessionSet({
+                taskId,
+                roleName,
+                set: record(setValue),
+                inventory,
+                sessions,
+                inFlight,
+                pendingCompletions
+            });
+        }
+    }
+    for (const [roleName, setValue] of Object.entries(record(state.globalRoleSessionSets))) {
+        collectSessionSet({
+            roleName,
+            set: record(setValue),
+            inventory,
+            sessions,
+            inFlight,
+            pendingCompletions
+        });
+    }
+    for (const mailboxValue of Object.values(record(state.mailboxes))) {
+        const mailbox = record(mailboxValue);
+        const target = record(mailbox.target);
+        const kind = text(target.kind);
+        if (kind !== "role-runtime" && kind !== "global-role-runtime")
+            continue;
+        if (mailbox.pending === null && mailbox.processing === null)
+            continue;
+        lifecycle.push({
+            ...(text(target.taskId) === undefined ? {} : { taskId: text(target.taskId) }),
+            ...(text(target.roleName) === undefined ? {} : { roleName: text(target.roleName) }),
+            reason: "pending-mailbox"
+        });
+    }
+    for (let index = 0; index < countPendingInbox(home); index += 1) {
+        lifecycle.push({ reason: "pending-inbox" });
+    }
+    // Any live native pane/process the durable session sets could not identify is
+    // still a blocker: its exact owner cannot be proven stopped.
+    for (const resource of inventory.resources) {
+        if (resource.kind !== "agent-session"
+            || (resource.processes.length === 0 && resource.paneDead !== false))
+            continue;
+        const owner = resource.owner;
+        const known = sessions.some((session) => resourceMatchesSession(resource, session));
+        if (known)
+            continue;
+        const pane = parseManagedPaneTarget(resource.target);
+        sessions.push({
+            ...(owner.kind === "task-role"
+                ? { taskId: owner.taskId }
+                : pane?.taskId === undefined ? {} : { taskId: pane.taskId }),
+            roleName: owner.kind === "task-role" || owner.kind === "global-role"
+                ? owner.roleName
+                : pane?.roleName ?? "unknown",
+            ...(owner.kind === "task-role" || owner.kind === "global-role"
+                ? {
+                    ...(owner.nativeSessionId === undefined
+                        ? {}
+                        : { nativeSessionId: owner.nativeSessionId }),
+                    ...(owner.launchId === undefined ? {} : { launchId: owner.launchId })
+                }
+                : {}),
+            status: "unknown",
+            processState: "unknown",
+            history: false
+        });
+    }
+    for (let index = 0; index < runs.length; index += 1) {
+        const run = runs[index];
+        const session = activeCurrentSession(sessions, run.taskId, run.roleName);
+        if (session !== undefined) {
+            runs[index] = {
+                ...run,
+                ...(session.nativeSessionId === undefined
+                    ? {}
+                    : { nativeSessionId: session.nativeSessionId }),
+                ...(session.launchId === undefined ? {} : { launchId: session.launchId })
+            };
+        }
+    }
+    return { runs, sessions, inFlight, pendingCompletions, lifecycle, unknownRuntime };
+}
+function parseManagedPaneTarget(target) {
+    if (target === undefined)
+        return undefined;
+    const match = /^yui-[a-f0-9]{12}-(.+):([^:]+)$/u.exec(target);
+    if (match === null)
+        return undefined;
+    return match[1] === "operator"
+        ? { roleName: match[2] }
+        : { taskId: match[1], roleName: match[2] };
+}
+function isUndeterminableNativeInventoryWarning(warning) {
+    return warning.startsWith("Cannot enumerate Linux processes")
+        || warning.startsWith("Cannot inspect tmux")
+        || warning.startsWith("Cannot inspect Unix sockets");
+}
+function collectSessionSet(options) {
+    const { taskId, roleName, set, inventory } = options;
+    const currentSessions = Object.entries(record(set.sessions));
+    const activeAgentId = text(set.activeAgentId);
+    const historyValue = set.history;
+    const historySessions = Array.isArray(historyValue)
+        ? historyValue
+        : Object.values(record(historyValue));
+    for (const { history, value, active } of [
+        ...currentSessions.map(([agentId, session]) => ({
+            history: false,
+            value: session,
+            active: activeAgentId !== undefined && agentId === activeAgentId
+        })),
+        ...historySessions.map((session) => ({ history: true, value: session, active: false }))
+    ]) {
+        const session = record(value);
+        const nativeSessionId = text(session.nativeSessionId);
+        const launchId = text(session.launchId);
+        const base = {
+            ...(taskId === undefined ? {} : { taskId }),
+            roleName,
+            ...(nativeSessionId === undefined ? {} : { nativeSessionId }),
+            ...(launchId === undefined ? {} : { launchId }),
+            status: text(session.status) ?? "unknown",
+            history,
+            active
+        };
+        options.sessions.push({
+            ...base,
+            processState: processState(inventory, base)
+        });
+    }
+    const flight = record(set.inFlight);
+    const runId = text(flight.runId);
+    if (taskId !== undefined && runId !== undefined) {
+        const session = activeCurrentSession(options.sessions, taskId, roleName);
+        options.inFlight.push({
+            taskId,
+            roleName,
+            runId,
+            ...(session?.nativeSessionId === undefined
+                ? {}
+                : { nativeSessionId: session.nativeSessionId }),
+            ...(session?.launchId === undefined ? {} : { launchId: session.launchId })
+        });
+    }
+    const completion = record(set.pendingTurnCompletion);
+    const completionTask = text(completion.taskId) ?? taskId;
+    if (completionTask !== undefined && Object.keys(completion).length > 0) {
+        const completionRole = text(completion.roleName) ?? roleName;
+        const completionNativeSessionId = text(completion.nativeSessionId);
+        const completionSession = options.sessions.find((candidate) => (candidate.taskId === completionTask
+            && candidate.roleName === completionRole
+            && completionNativeSessionId !== undefined
+            && candidate.nativeSessionId === completionNativeSessionId));
+        options.pendingCompletions.push({
+            taskId: completionTask,
+            roleName: completionRole,
+            ...(text(completion.runId) === undefined ? {} : { runId: text(completion.runId) }),
+            ...(completionNativeSessionId === undefined
+                ? {}
+                : { nativeSessionId: completionNativeSessionId }),
+            ...(completionSession?.launchId === undefined
+                ? {}
+                : { launchId: completionSession.launchId })
+        });
+    }
+}
+function activeCurrentSession(sessions, taskId, roleName) {
+    const current = sessions.filter((candidate) => (candidate.taskId === taskId
+        && candidate.roleName === roleName
+        && !candidate.history));
+    return current.find(({ active }) => active === true)
+        ?? (current.length === 1 ? current[0] : undefined);
+}
+function processState(inventory, session) {
+    const matching = inventory.resources.filter((resource) => (resource.kind === "agent-session" && resourceMatchesSession(resource, session)));
+    if (matching.some((resource) => resource.processes.length > 0))
+        return "live";
+    if (matching.some((resource) => resource.paneDead === false))
+        return "unknown";
+    return "stopped";
+}
+function resourceMatchesSession(resource, session) {
+    const owner = resource.owner;
+    if (owner.kind !== "task-role" && owner.kind !== "global-role")
+        return false;
+    if (session.taskId === undefined) {
+        if (owner.kind !== "global-role")
+            return false;
+    }
+    else if (owner.kind !== "task-role" || owner.taskId !== session.taskId)
+        return false;
+    if (owner.roleName !== session.roleName)
+        return false;
+    if (session.nativeSessionId !== undefined && owner.nativeSessionId !== session.nativeSessionId) {
+        return false;
+    }
+    if (session.launchId !== undefined && owner.launchId !== session.launchId)
+        return false;
+    return true;
+}
+function readStateObject(home) {
+    const path = join(home, STORAGE_STATE_FILE);
+    if (!existsSync(path))
+        return {};
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return record(parsed);
+}
+function countPendingInbox(home) {
+    return [join(home, "runtime", "inbox"), join(home, "runtime", "inbox-invalid")]
+        .reduce((total, directory) => total + countDirectory(directory), 0);
+}
+function countDirectory(directory) {
+    try {
+        return readdirSync(directory).filter((name) => (name.endsWith(".json") || name.includes(".tmp-") || !name.startsWith("."))).length;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return 0;
+        return 1;
+    }
+}
+function identity(value, reason) {
+    return {
+        ...(value.taskId === undefined ? {} : { taskId: value.taskId }),
+        ...(value.roleName === undefined ? {} : { roleName: value.roleName }),
+        ...(value.runId === undefined ? {} : { runId: value.runId }),
+        ...(value.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: value.nativeSessionId }),
+        ...(value.launchId === undefined ? {} : { launchId: value.launchId }),
+        reason
+    };
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function text(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}

package/dist/storage/upgrade/productionMigrationRegistry.js

@@ -0,0 +1,6 @@
+/**
+ * Backward-compatible import path for the one production storage registry.
+ * Compatible loading and offline migration share the declaration graph owned by
+ * `storage/migration/productionRegistry.ts`.
+ */
+export { createProductionStorageRegistry as createProductionMigrationRegistry } from "../migration/productionRegistry.js";

package/dist/storage/upgrade/recordVersionScan.js

@@ -0,0 +1,176 @@
+/**
+ * Pure, read-only structural scan of raw `state.json`, never through the strict
+ * `parseState`/`FileTaskStore` gate. The durable manifest remains authoritative;
+ * this scanner supplies member versions and counts so callers can detect
+ * manifest/state contradictions without treating an empty locator as current.
+ * Older member versions remain version evidence rather than a strict-loader
+ * parse failure, while malformed JSON/containers/schemaVersion fields are real
+ * `CORRUPTED` evidence.
+ *
+ * The `path` for each family (from `recordVersions.ts`) is a small locator into
+ * `state.json`: segments are `/`-separated after the `state.json#/` prefix, and a
+ * `*` segment fans out over every member of the map at that level (so the locator
+ * `state.json#/tasks/{star}/workItems` visits the `workItems` map of every task,
+ * where `{star}` is a literal `*`).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { STORAGE_STATE_FILE } from "../taskStore.js";
+/**
+ * Scan per-family member versions and counts from raw `state.json`.
+ *
+ * Rules, per family, evaluated purely (no strict parser):
+ *  - family absent or empty on disk  -> latest as an internal scan sentinel,
+ *    with count zero so the manifest combiner never infers source currency;
+ *  - every member at one older/current/newer version -> report that version;
+ *  - members carrying different versions             -> corruption.
+ *
+ * A family is one durable schema boundary, so a manifest cannot make a mixed
+ * member set trustworthy by matching either its minimum or maximum. Mixed
+ * members are partial-write/corruption evidence, not a migration source version.
+ *
+ * Returns a `corruption` instead when the JSON is unparseable, the root is not an
+ * object, a path container is not the shape the locator describes, or a record is
+ * missing/has an invalid `schemaVersion`.
+ */
+export function scanSourceRecordVersions(home, latestRecord) {
+    const statePath = join(home, STORAGE_STATE_FILE);
+    if (!existsSync(statePath)) {
+        // No state.json means zero persisted members. The latest-valued scan entry
+        // is only a sentinel; counts preserve absence for the manifest combiner.
+        return {
+            record: cloneRecord(latestRecord),
+            counts: Object.fromEntries(Object.keys(latestRecord).map((kind) => [kind, 0]))
+        };
+    }
+    let root;
+    try {
+        root = JSON.parse(readFileSync(statePath, "utf8"));
+    }
+    catch (error) {
+        return corruption(`state.json is not valid JSON: ${messageOf(error)}`);
+    }
+    if (!isObject(root)) {
+        return corruption("state.json is not a JSON object.");
+    }
+    return scanRecordVersionsFromState(root, latestRecord);
+}
+/** Extract record versions from an already-parsed state snapshot, read-only. */
+export function scanRecordVersionsFromState(root, latestRecord) {
+    if (!isObject(root))
+        return corruption("state snapshot is not a JSON object.");
+    const record = {};
+    const counts = {};
+    for (const [kind, entry] of Object.entries(latestRecord)) {
+        const scan = scanFamily(root, entry.path, entry.version);
+        if ("corruption" in scan) {
+            return corruption(`record family '${kind}' (${entry.path}): ${scan.corruption}`);
+        }
+        record[kind] = { version: scan.version, path: entry.path };
+        counts[kind] = scan.count;
+    }
+    return { record, counts };
+}
+/** Resolve one family's source version from `root` following `path`. */
+function scanFamily(root, path, latestVersion) {
+    const segments = parseLocator(path);
+    if (segments === null)
+        return { corruption: `unrecognized path syntax "${path}"` };
+    // Resolve the path to the family's endpoint node(s). A `*` fans out over the
+    // members of the map at that level; an absent named key contributes nothing
+    // (that branch simply has no records), but a present-but-wrong-typed node is
+    // structural damage.
+    let nodes = [root];
+    for (const segment of segments) {
+        const next = [];
+        for (const node of nodes) {
+            if (segment === "*") {
+                if (!isObject(node))
+                    return { corruption: `expected an object to enumerate at "*"` };
+                next.push(...Object.values(node));
+            }
+            else {
+                if (!isObject(node))
+                    return { corruption: `expected an object at "${segment}"` };
+                if (!Object.hasOwn(node, segment))
+                    continue; // absent branch: no records here
+                next.push(node[segment]);
+            }
+        }
+        nodes = next;
+    }
+    // Each endpoint is either a single record (it carries `schemaVersion`, e.g.
+    // tasks/* (the StoredTask aggregate), tasks/*/task, tasks/*/brief) or a map of records (its values carry
+    // `schemaVersion`, e.g. configuredAgents, tasks/*/workItems).
+    let min = Number.POSITIVE_INFINITY;
+    let max = Number.NEGATIVE_INFINITY;
+    let count = 0;
+    for (const endpoint of nodes) {
+        if (endpoint === null || endpoint === undefined)
+            continue; // e.g. brief: null
+        if (!isObject(endpoint))
+            return { corruption: "family endpoint is not an object" };
+        if (typeof endpoint.schemaVersion === "number") {
+            const version = readSchemaVersion(endpoint);
+            if (version === null)
+                return { corruption: `record has an invalid schemaVersion` };
+            min = Math.min(min, version);
+            max = Math.max(max, version);
+            count += 1;
+            continue;
+        }
+        for (const member of Object.values(endpoint)) {
+            if (member === null)
+                continue;
+            if (!isObject(member))
+                return { corruption: "record member is not an object" };
+            const version = readSchemaVersion(member);
+            if (version === null)
+                return { corruption: "record member has a missing/invalid schemaVersion" };
+            min = Math.min(min, version);
+            max = Math.max(max, version);
+            count += 1;
+        }
+    }
+    if (count === 0)
+        return { version: latestVersion, count }; // zero-count sentinel only
+    if (min !== max) {
+        return {
+            corruption: `family contains mixed schemaVersion values ${min} and ${max}`
+        };
+    }
+    return { version: min, count };
+}
+/** Parse a `state.json#/`-prefixed locator into path segments, or `null`. */
+function parseLocator(path) {
+    const prefix = `${STORAGE_STATE_FILE}#/`;
+    if (!path.startsWith(prefix))
+        return null;
+    const body = path.slice(prefix.length);
+    if (body.length === 0)
+        return null;
+    return body.split("/");
+}
+/** A positive-integer `schemaVersion`, or `null` when missing/invalid. */
+function readSchemaVersion(record) {
+    const version = record.schemaVersion;
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1)
+        return null;
+    return version;
+}
+function cloneRecord(record) {
+    const copy = {};
+    for (const [kind, entry] of Object.entries(record)) {
+        copy[kind] = { version: entry.version, path: entry.path };
+    }
+    return copy;
+}
+function corruption(detail) {
+    return { corruption: { corrupted: true, detail } };
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/storage/upgrade/recordVersions.js

@@ -0,0 +1,159 @@
+/**
+ * The current-baseline record-axis version map.
+ *
+ * The three storage axes are `layout`, `aggregate`, and `record`. The layout and
+ * aggregate axes are scalars sourced from `storageSchema.ts`; the record axis is
+ * a `recordKind -> { version, path }` map because every record family versions
+ * independently (see the generic migration core in `../migration`).
+ *
+ * This map is a SNAPSHOT of the record families that exist on the current
+ * baseline, enumerated from their real `schemaVersion`s in `taskStore.ts` and the
+ * per-record modules. It is intentionally NOT a frozen "first release" set: as
+ * the schema evolves (a new record family, a bumped family version), this map is
+ * updated in lockstep, exactly like the scalar constants. It exists so
+ * doctor/inspect and the migration planner can reason about record families.
+ * Post-baseline record changes require an explicit adjacent registration and
+ * transform in the production migration graph.
+ */
+import { CURRENT_AGGREGATE_SCHEMA_VERSION, CURRENT_STORAGE_LAYOUT_VERSION } from "../storageVersions.js";
+import { CURRENT_AGENT_RUN_SCHEMA_VERSION, CURRENT_ACTIVE_RUN_POINTER_SCHEMA_VERSION, CURRENT_AGENT_PROFILE_SCHEMA_VERSION, CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_CONFIGURED_AGENT_SCHEMA_VERSION, CURRENT_CHANGE_SET_SCHEMA_VERSION, CURRENT_DECISION_SCHEMA_VERSION, CURRENT_EVENT_SCHEMA_VERSION, CURRENT_GLOBAL_ROLE_SCHEMA_VERSION, CURRENT_GLOBAL_ROLE_SESSION_SET_SCHEMA_VERSION, CURRENT_INPUT_REQUEST_SCHEMA_VERSION, CURRENT_INTEGRATION_ATTEMPT_SCHEMA_VERSION, CURRENT_MANAGED_WORKSPACE_SCHEMA_VERSION, CURRENT_MESSAGE_SCHEMA_VERSION, CURRENT_MILESTONE_SCHEMA_VERSION, CURRENT_PROJECT_SCHEMA_VERSION, CURRENT_REVIEW_ROUND_SCHEMA_VERSION, CURRENT_STORED_TASK_SCHEMA_VERSION, CURRENT_TASK_BRIEF_SCHEMA_VERSION, CURRENT_TASK_ROLE_SCHEMA_VERSION, CURRENT_TASK_ROLE_SESSION_SET_SCHEMA_VERSION, CURRENT_TASK_SCHEMA_VERSION, CURRENT_WORK_ITEM_SCHEMA_VERSION, CURRENT_WORK_MAILBOX_SCHEMA_VERSION } from "../taskStore.js";
+import { CURRENT_LEADER_FAILURE_SCHEMA_VERSION } from "../../scheduler/leaderFailure.js";
+import { CURRENT_OPERATOR_NOTIFICATION_SCHEMA_VERSION } from "../../scheduler/operatorNotification.js";
+function descriptor(version, path) {
+    return Object.freeze({ version, path });
+}
+/**
+ * Independent persisted-boundary contract for the direct family keys and
+ * locators. The upgrade descriptor table is checked against this contract so
+ * omitting a newly persisted family or changing a locator cannot make the
+ * scanner silently skip that family.
+ */
+const EXPECTED_DIRECT_RECORD_LOCATORS = Object.freeze({
+    config: "state.json#/config",
+    configuredAgent: "state.json#/configuredAgents",
+    project: "state.json#/projects",
+    agentProfile: "state.json#/agentProfiles",
+    globalRole: "state.json#/globalRoles",
+    globalRoleSessionSet: "state.json#/globalRoleSessionSets",
+    storedTask: "state.json#/tasks/*",
+    task: "state.json#/tasks/*/task",
+    taskBrief: "state.json#/tasks/*/brief",
+    taskRole: "state.json#/tasks/*/roles",
+    managedWorkspace: "state.json#/tasks/*/managedWorkspaces",
+    taskRoleSessionSet: "state.json#/tasks/*/roleSessionSets",
+    workItem: "state.json#/tasks/*/workItems",
+    agentRun: "state.json#/tasks/*/agentRuns",
+    reviewRound: "state.json#/tasks/*/reviewRounds",
+    changeSet: "state.json#/tasks/*/changeSets",
+    integrationAttempt: "state.json#/tasks/*/integrationAttempts",
+    activeRunPointer: "state.json#/tasks/*/activeRuns",
+    message: "state.json#/tasks/*/messages",
+    inputRequest: "state.json#/tasks/*/inputRequests",
+    decision: "state.json#/tasks/*/decisions",
+    milestone: "state.json#/tasks/*/milestones",
+    event: "state.json#/tasks/*/events",
+    leaderFailure: "state.json#/tasks/*/leaderFailure",
+    operatorNotification: "state.json#/tasks/*/operatorNotification",
+    workMailbox: "state.json#/mailboxes"
+});
+/**
+ * The one authoritative descriptor table for every direct StorageState and
+ * StoredTask record family. `path` is a logical, human-readable location of
+ * where the family's records live inside the authoritative store; the generic
+ * engine treats it as opaque. Update this table whenever a family is added or
+ * its `schemaVersion` changes — it tracks the live schema, it does not freeze
+ * it.
+ *
+ * Lazy-initialized to avoid a circular-dependency TDZ: `recordVersions.ts`
+ * imports the `CURRENT_*_SCHEMA_VERSION` constants from `taskStore.ts`, which
+ * imports `requireStorageSchema` from `storageSchema.ts`, which (via the
+ * provider pattern) depends on this module. Building the descriptors lazily
+ * means the constants are only read at runtime, after every module has loaded.
+ */
+let currentRecordDescriptors = null;
+function getCurrentRecordDescriptors() {
+    if (currentRecordDescriptors === null) {
+        currentRecordDescriptors = Object.freeze({
+            config: descriptor(CURRENT_CONFIG_SCHEMA_VERSION, "state.json#/config"),
+            configuredAgent: descriptor(CURRENT_CONFIGURED_AGENT_SCHEMA_VERSION, "state.json#/configuredAgents"),
+            project: descriptor(CURRENT_PROJECT_SCHEMA_VERSION, "state.json#/projects"),
+            agentProfile: descriptor(CURRENT_AGENT_PROFILE_SCHEMA_VERSION, "state.json#/agentProfiles"),
+            globalRole: descriptor(CURRENT_GLOBAL_ROLE_SCHEMA_VERSION, "state.json#/globalRoles"),
+            globalRoleSessionSet: descriptor(CURRENT_GLOBAL_ROLE_SESSION_SET_SCHEMA_VERSION, "state.json#/globalRoleSessionSets"),
+            // The task aggregate is itself a versioned record family. Keep this family
+            // alongside (and distinct from) the nested `task` record family: an older
+            // aggregate wrapper must be classified on the record axis before the strict
+            // loader is asked to parse its nested members.
+            storedTask: descriptor(CURRENT_STORED_TASK_SCHEMA_VERSION, "state.json#/tasks/*"),
+            task: descriptor(CURRENT_TASK_SCHEMA_VERSION, "state.json#/tasks/*/task"),
+            taskBrief: descriptor(CURRENT_TASK_BRIEF_SCHEMA_VERSION, "state.json#/tasks/*/brief"),
+            taskRole: descriptor(CURRENT_TASK_ROLE_SCHEMA_VERSION, "state.json#/tasks/*/roles"),
+            managedWorkspace: descriptor(CURRENT_MANAGED_WORKSPACE_SCHEMA_VERSION, "state.json#/tasks/*/managedWorkspaces"),
+            taskRoleSessionSet: descriptor(CURRENT_TASK_ROLE_SESSION_SET_SCHEMA_VERSION, "state.json#/tasks/*/roleSessionSets"),
+            workItem: descriptor(CURRENT_WORK_ITEM_SCHEMA_VERSION, "state.json#/tasks/*/workItems"),
+            agentRun: descriptor(CURRENT_AGENT_RUN_SCHEMA_VERSION, "state.json#/tasks/*/agentRuns"),
+            reviewRound: descriptor(CURRENT_REVIEW_ROUND_SCHEMA_VERSION, "state.json#/tasks/*/reviewRounds"),
+            changeSet: descriptor(CURRENT_CHANGE_SET_SCHEMA_VERSION, "state.json#/tasks/*/changeSets"),
+            integrationAttempt: descriptor(CURRENT_INTEGRATION_ATTEMPT_SCHEMA_VERSION, "state.json#/tasks/*/integrationAttempts"),
+            activeRunPointer: descriptor(CURRENT_ACTIVE_RUN_POINTER_SCHEMA_VERSION, "state.json#/tasks/*/activeRuns"),
+            message: descriptor(CURRENT_MESSAGE_SCHEMA_VERSION, "state.json#/tasks/*/messages"),
+            inputRequest: descriptor(CURRENT_INPUT_REQUEST_SCHEMA_VERSION, "state.json#/tasks/*/inputRequests"),
+            decision: descriptor(CURRENT_DECISION_SCHEMA_VERSION, "state.json#/tasks/*/decisions"),
+            milestone: descriptor(CURRENT_MILESTONE_SCHEMA_VERSION, "state.json#/tasks/*/milestones"),
+            event: descriptor(CURRENT_EVENT_SCHEMA_VERSION, "state.json#/tasks/*/events"),
+            leaderFailure: descriptor(CURRENT_LEADER_FAILURE_SCHEMA_VERSION, "state.json#/tasks/*/leaderFailure"),
+            operatorNotification: descriptor(CURRENT_OPERATOR_NOTIFICATION_SCHEMA_VERSION, "state.json#/tasks/*/operatorNotification"),
+            workMailbox: descriptor(CURRENT_WORK_MAILBOX_SCHEMA_VERSION, "state.json#/mailboxes")
+        });
+    }
+    return currentRecordDescriptors;
+}
+/** Kept as the public-facing name used by upgrade callers and tests. */
+const CURRENT_RECORD_VERSIONS = getCurrentRecordDescriptors;
+/** The record-axis map for the current baseline (a defensive shallow copy). */
+export function currentRecordVersions(candidate = CURRENT_RECORD_VERSIONS()) {
+    assertRecordVersionDescriptors(candidate);
+    return { ...candidate };
+}
+/**
+ * Fail closed if a record descriptor map drifts from the one authoritative
+ * table. The candidate parameter is exported so the regression suite can
+ * exercise an unchecked-family version/path drift directly; production callers
+ * use the default current descriptor table.
+ */
+export function assertRecordVersionDescriptors(candidate = CURRENT_RECORD_VERSIONS()) {
+    const expectedKinds = Object.keys(EXPECTED_DIRECT_RECORD_LOCATORS);
+    const mappedKinds = Object.keys(candidate);
+    const missing = expectedKinds.filter((kind) => !Object.hasOwn(candidate, kind));
+    const unexpected = mappedKinds.filter((kind) => !Object.hasOwn(EXPECTED_DIRECT_RECORD_LOCATORS, kind));
+    if (missing.length > 0 || unexpected.length > 0) {
+        throw new Error(`Record version map completeness drift: missing=${missing.join(",") || "none"}; `
+            + `unexpected=${unexpected.join(",") || "none"}.`);
+    }
+    const descriptors = getCurrentRecordDescriptors();
+    for (const kind of expectedKinds) {
+        const expected = descriptors[kind];
+        const expectedPath = EXPECTED_DIRECT_RECORD_LOCATORS[kind];
+        const mapped = candidate[kind];
+        if (expected === undefined
+            || mapped === undefined
+            || mapped === null
+            || mapped.version !== expected.version
+            || mapped.path !== expectedPath) {
+            throw new Error(`Record version map drift for ${kind}: expected=${String(expected?.version)}@${expectedPath}; `
+                + `actual=${String(mapped?.version)}@${String(mapped?.path)}.`);
+        }
+    }
+}
+/**
+ * The full latest-supported {@link StorageVersionState} this release understands:
+ * the scalar layout/aggregate versions plus the current record map. The engine
+ * and classifier compare a source against this to decide the four-state verdict.
+ */
+export function latestStorageVersionState(recordDescriptors = CURRENT_RECORD_VERSIONS()) {
+    return {
+        layout: CURRENT_STORAGE_LAYOUT_VERSION,
+        aggregate: CURRENT_AGGREGATE_SCHEMA_VERSION,
+        record: currentRecordVersions(recordDescriptors)
+    };
+}