@zq-silk/yui 0.2.0 → 0.4.2

package/dist/storage/upgrade/homeClassification.js

@@ -0,0 +1,156 @@
+/**
+ * Four-state classification of a real Yui Home.
+ *
+ * This layers real, I/O-based corruption detection onto the pure WI-3
+ * classifier. It reports exactly one shared product state — current,
+ * compatible-old, migration-required, or unsupported — together with the
+ * on-disk layout and aggregate versions and, when the store cannot be used, the
+ * incompatible component (layout vs aggregate).
+ *
+ * Corruption is only ever reported from a *real* structural failure: a
+ * `state.json` that is not parseable / not shaped like the record locators
+ * describe / carries a record with an invalid `schemaVersion`, a broken reference
+ * graph (detected by the strict loader once every axis is already current), or a
+ * `schema.json` manifest that is not valid. It is never inferred from version
+ * magnitude. An older or newer version — on ANY axis, including a single older
+ * record family — is a version verdict (`COMPATIBLE` for an all-compatible path,
+ * `MIGRATABLE` for an offline path, otherwise `NEEDS_NEW_VERSION`), never
+ * `CORRUPTED`. An older Home without a complete declared path fails closed with
+ * a precise missing declaration/step reason.
+ *
+ * The three axes are independent: record versions come from the durable
+ * manifest and raw `state.json` is traversed structurally only to verify that
+ * non-empty families agree. This keeps a record-only-older Home on its version
+ * axis without letting an empty target family masquerade as current.
+ */
+import { classifyStorage } from "../migration/index.js";
+import { inspectStorageSchema } from "../storageSchema.js";
+import { FileTaskStore, StorageRecordError } from "../taskStore.js";
+import { inspectSourceVersionState } from "./homeMigrationTarget.js";
+/**
+ * Classify a real Home. Reads `schema.json` (and, for a current Home,
+ * `state.json` through the strict loader) read-only; never mutates the Home.
+ */
+export function classifyHome(options) {
+    const { home, registry, latest } = options;
+    const schema = inspectStorageSchema(home);
+    const base = {
+        latestLayoutVersion: latest.layout,
+        latestAggregateVersion: latest.aggregate
+    };
+    if (schema.status === "uninitialized") {
+        return {
+            ...base,
+            classification: { verdict: "USABLE", status: "current" },
+            uninitialized: true
+        };
+    }
+    if (schema.status === "invalid") {
+        // A malformed manifest is real structural damage, not a version verdict.
+        return {
+            ...base,
+            classification: {
+                verdict: "CORRUPTED",
+                status: "unsupported",
+                detail: `Storage schema manifest is invalid: ${schema.detail}`
+            }
+        };
+    }
+    // Read all three durable axes read-only, then structurally cross-check raw
+    // state.json without invoking the strict current loader. Version differences
+    // remain version facts; manifest/state contradictions surface as corruption.
+    const inspected = inspectSourceVersionState(home, latest);
+    if ("corruption" in inspected) {
+        return {
+            ...base,
+            classification: {
+                verdict: "CORRUPTED",
+                status: "unsupported",
+                detail: inspected.corruption.detail
+            },
+            layoutVersion: schema.currentLayoutVersion,
+            aggregateVersion: schema.currentAggregateSchemaVersion,
+            ...(incompatibleComponentOf(schema) === undefined
+                ? {}
+                : { incompatibleComponent: incompatibleComponentOf(schema) })
+        };
+    }
+    const source = inspected.source;
+    // The reference graph can only be validated by the strict loader, which only
+    // understands the current versions. So run it exactly when every axis is
+    // already current (the plan would be a no-op); a throw there is genuine
+    // structural/reference corruption, never a version mismatch. An older/newer
+    // axis skips the loader and is decided purely by the planner below.
+    //
+    // Crucially, the strict loader is ONLY invoked when the manifest itself is
+    // `current`. An `unsupported` manifest (e.g. a pre-baseline Home with no
+    // recordVersions field) must never reach FileTaskStore: requireStorageSchema
+    // would throw StorageSchemaError, which doctor/upgrade must surface as a
+    // structured NEEDS_NEW_VERSION verdict, not as an invalid/corruption error.
+    const corruption = (schema.status === "current" && isFullyCurrent(source, latest))
+        ? detectCurrentHomeCorruption(home)
+        : undefined;
+    const classification = classifyStorage(registry, source, latest, corruption);
+    return {
+        ...base,
+        classification,
+        layoutVersion: schema.currentLayoutVersion,
+        aggregateVersion: schema.currentAggregateSchemaVersion,
+        ...(incompatibleComponentOf(schema) === undefined
+            ? {}
+            : { incompatibleComponent: incompatibleComponentOf(schema) })
+    };
+}
+/**
+ * Load a Home whose every axis is already current through the strict
+ * `FileTaskStore` gate to detect real structural/reference corruption. This is
+ * only ever called when the source equals `latest` across all three axes, so a
+ * version error cannot occur here and any throw is genuine corruption (bad
+ * record shape, a broken reference graph).
+ */
+function detectCurrentHomeCorruption(home) {
+    try {
+        const store = new FileTaskStore(home);
+        store.getConfig();
+        store.listTasks();
+        store.listProjects();
+        store.listConfiguredAgents();
+        store.listWorkMailboxes();
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof StorageRecordError) {
+            return { corrupted: true, detail: error.message };
+        }
+        // A non-record error (e.g. an unexpected I/O fault) is surfaced, not
+        // silently swallowed as "usable".
+        throw error;
+    }
+}
+/** True when the source is already at `latest` on every axis (a no-op plan). */
+function isFullyCurrent(source, latest) {
+    if (source.layout !== latest.layout || source.aggregate !== latest.aggregate) {
+        return false;
+    }
+    // Every family shared by source and target must already match; a family
+    // present on only one side is a difference the planner reasons about, not a
+    // "current" match, so it is not fully current.
+    const kinds = new Set([
+        ...Object.keys(source.record),
+        ...Object.keys(latest.record)
+    ]);
+    for (const kind of kinds) {
+        const from = source.record[kind]?.version;
+        const to = latest.record[kind]?.version;
+        if (from !== to)
+            return false;
+    }
+    return true;
+}
+function incompatibleComponentOf(schema) {
+    return schema.status === "unsupported" ? schema.incompatibleComponent : undefined;
+}
+/** A structural corruption check over an already-read snapshot (for tests/reports). */
+export function snapshotHasState(snapshot) {
+    return snapshot.state !== null;
+}