@soulcraft/cor 3.0.0-rc.1

package/dist/migration/MigrationCoordinator.js

@@ -0,0 +1,249 @@
+/**
+ * @module migration/MigrationCoordinator
+ * @description The cor-side driver of the #18 whole-brain 7.x → 8.0 upgrade — a
+ * **coordinated migration lock**. When cor opens a LARGE brain whose derived-index
+ * epoch is stale (drifted or absent; see {@link module:migration/indexEpochGuard}),
+ * the correct-and-clean upgrade is a BLOCKING one: rebuild every derived index
+ * (metadata LSM, DiskANN vector, graph adjacency) from the canonical records to a
+ * known-good state BEFORE serving — never serve a half-built or stale index. That
+ * decision (David, 2026-07-01) replaced the earlier "no-freeze background swap":
+ * no-freeze's availability is illusory (it serves degraded/half-built results),
+ * and *unknown/halfway states are more dangerous than a clean block*.
+ *
+ * ## The lock, coordinated with Brainy
+ *
+ * cor sets a lock the instant it detects a large stale brain; Brainy holds every
+ * public read AND write behind that lock (its `isMigrating()` gate, rc.9) and maps
+ * the lock to an HTTP-503-style readiness signal, so nothing observes a partial
+ * result and no write reaches a half-built index. The rebuild runs asynchronously
+ * — the LOCK, not a synchronous init hang, is what serializes access — and when
+ * all three indexes are rebuilt-from-canonical + the version marker is stamped,
+ * cor clears the lock and Brainy releases the queued operations against a fully
+ * correct brain. One invariant: *the brain is not readable/writable until all
+ * three indexes are rebuilt + stamped.*
+ *
+ * Brainy feature-detects three optional provider methods; every cor derived-index
+ * provider delegates them to the single coordinator so the answer is consistent
+ * across all three: {@link MigrationCoordinator#isMigrating} (the lock signal),
+ * {@link MigrationCoordinator#whenMigrationComplete} (the no-poll wait Brainy
+ * `Promise.race`s against its bounded timeout), and
+ * {@link MigrationCoordinator#migrationStatus} (the progress cor owns, which Brainy
+ * relays verbatim into `getIndexStatus().migration`).
+ *
+ * ## Failure is a locked-with-error state, never a half-served one
+ *
+ * If a rebuild throws, the coordinator KEEPS the brain locked (so Brainy never
+ * releases reads onto a half-built index) and rejects {@link
+ * MigrationCoordinator#whenMigrationComplete} with a loud, actionable error — the
+ * same "blocking beats halfway" principle applied to the failure path. A restart
+ * re-detects the drift and re-runs the idempotent in-place rebuild, so a transient
+ * hiccup self-heals; genuinely-corrupt canonical data stays safely blocked with a
+ * pointer to the offline `scripts/migrate-cortex-2x-to-3x.mjs` escape hatch.
+ *
+ * The rebuild is IN-PLACE (no shadow directories, no serve-from-canonical, no
+ * concurrent-write reconciliation) precisely because everything is locked: no live
+ * index is read while it is being rebuilt.
+ */
+import { prodLog } from '@soulcraft/brainy/internals';
+import { writeBrainFormat } from '@soulcraft/brainy/brain-format';
+/**
+ * @description Drives the #18 coordinated blocking migration and answers the three
+ * Brainy-feature-detected lock methods. One instance per brain, created in the
+ * plugin's `activate` closure and shared by all three derived-index providers.
+ *
+ * @example
+ * const coordinator = new MigrationCoordinator(storage, {
+ *   metadata: () => metadataIndexInstance,
+ *   vector: () => vectorInstance,
+ *   graph: () => graphEngine,
+ * })
+ * // ...in metadata init(), on a large stale brain:
+ * coordinator.start()          // flips isMigrating() true synchronously, rebuilds async
+ */
+export class MigrationCoordinator {
+    storage;
+    providers;
+    /**
+     * `idle` before/without a migration; `migrating` while rebuilding; `done` once
+     * stamped; `failed` when a rebuild threw. `failed` reads as LOCKED (see
+     * {@link isMigrating}) so Brainy never releases reads onto a half-built index.
+     */
+    state = 'idle';
+    status = null;
+    completePromise = null;
+    resolveComplete = null;
+    rejectComplete = null;
+    failure = null;
+    /**
+     * @param storage - The brain's storage adapter — passed to `writeBrainFormat`
+     *   as the final stamp step (Brainy's own `dataFormat`/`indexEpoch` constants;
+     *   cor never authors the format string).
+     * @param providers - Lazy resolvers for the three derived-index providers.
+     */
+    constructor(storage, providers) {
+        this.storage = storage;
+        this.providers = providers;
+    }
+    /**
+     * @description The lock signal Brainy gates every public read AND write on.
+     * `true` while migrating OR after a failure (a failed migration stays LOCKED so
+     * Brainy never serves the half-built index — a restart re-runs the idempotent
+     * rebuild).
+     * @returns `true` when the brain must not be read from or written to.
+     */
+    isMigrating() {
+        return this.state === 'migrating' || this.state === 'failed';
+    }
+    /**
+     * @description Resolves when the migration completes (lock clears), or REJECTS
+     * with the loud failure error if it failed. Used internally by {@link start} (the
+     * already-migrating idempotency path) and by tests as the completion signal.
+     *
+     * Brainy does NOT call this: rc.9 dropped the provider-level `whenMigrationComplete`
+     * hook and polls `isMigrating()` at 250 ms instead (the event-driven variant
+     * busy-spun with mixed providers). `getIndexStatus().migrating` is the readiness
+     * signal, and a blocked op waits out the lock up to `migrationWaitTimeoutMs` before
+     * a retryable `MigrationInProgressError`.
+     * @returns A promise that settles when the lock is released or the migration fails.
+     */
+    whenMigrationComplete() {
+        if (this.state === 'done')
+            return Promise.resolve();
+        if (this.state === 'failed') {
+            return Promise.reject(this.failure ?? new Error('migration failed'));
+        }
+        if (!this.completePromise) {
+            // idle and not yet started — a wait registered before start() still settles.
+            this.completePromise = new Promise((resolve, reject) => {
+                this.resolveComplete = resolve;
+                this.rejectComplete = reject;
+            });
+        }
+        return this.completePromise;
+    }
+    /**
+     * @description The structured progress Brainy relays into
+     * `getIndexStatus().migration`. `null` unless a migration is in flight.
+     * @returns The current {@link MigrationStatus}, or `null`.
+     */
+    migrationStatus() {
+        // Report during 'migrating' (rebuild progress) AND 'failed' — so a brain
+        // hard-locked by a failed migration surfaces WHY (phase: 'failed' + which index)
+        // via getIndexStatus().migration, not just `migrating: true` with no reason.
+        // Null when idle / done.
+        return this.state === 'migrating' || this.state === 'failed'
+            ? this.status
+            : null;
+    }
+    /**
+     * @description Kick the coordinated blocking rebuild. Flips {@link isMigrating}
+     * to `true` **synchronously** (so Brainy sees the lock the instant the triggering
+     * `init()` returns), then runs the rebuild asynchronously — the LOCK, not this
+     * promise, is what serializes reads/writes, so callers do NOT await this.
+     * Idempotent: calling it again while already migrating returns the in-flight
+     * completion promise without starting a second rebuild.
+     * @returns The completion promise (settles when the lock clears or the migration fails).
+     */
+    start() {
+        // Already migrating → return the in-flight completion (no second rebuild).
+        if (this.state === 'migrating')
+            return this.whenMigrationComplete();
+        // Already migrated + stamped → no-op. (A re-open won't reach here — the epoch
+        // is current — but guard defensively against a double start() re-running the
+        // whole rebuild and re-stamping.)
+        if (this.state === 'done')
+            return Promise.resolve();
+        // Fresh run — 'idle', or the RETRY path after a prior 'failed' (the epoch was
+        // never stamped, so a re-open re-detects drift). run() NULLS the completion
+        // triplet when it settles, so `this.completePromise` here is either null (→ a
+        // fresh promise below) or a still-pending pre-start wait we reuse.
+        this.state = 'migrating';
+        this.failure = null;
+        this.status = { phase: 'starting' };
+        // Reuse a wait registered before start(); otherwise create the promise now.
+        if (!this.completePromise) {
+            this.completePromise = new Promise((resolve, reject) => {
+                this.resolveComplete = resolve;
+                this.rejectComplete = reject;
+            });
+        }
+        // The lock is already set above (synchronous); run the rebuild in the background.
+        void this.run();
+        return this.completePromise;
+    }
+    /**
+     * The async body: rebuild metadata → vector → graph from canonical, verify by
+     * stamping (the marker certifies all three; Brainy withholds its own stamp while
+     * we are migrating), then clear the lock. Any throw leaves the brain LOCKED and
+     * rejects the completion promise.
+     */
+    async run() {
+        const startedAt = Date.now();
+        // Track the index being rebuilt so a failure can report WHICH one failed.
+        let currentIndex;
+        try {
+            const steps = [
+                ['metadata', this.providers.metadata()],
+                ['vector', this.providers.vector()],
+                ['graph', this.providers.graph()],
+            ];
+            for (const [index, provider] of steps) {
+                // A resolver may return undefined (e.g. a provider a cloud adapter never
+                // engages) — skip it rather than fail the whole upgrade.
+                if (!provider)
+                    continue;
+                currentIndex = index;
+                this.status = { phase: 'rebuilding', index };
+                prodLog.info(`[Cor] migration: rebuilding ${index} index from canonical records…`);
+                await provider.rebuild();
+                prodLog.info(`[Cor] migration: ${index} index rebuilt`);
+            }
+            // Stamp LAST — Brainy's own dataFormat + indexEpoch constants, written via
+            // the exported writer (no brain handle, no hardcoded '8.0'). The marker
+            // advancing is what certifies all three indexes are current; a crash before
+            // this leaves it stale → the next open re-detects drift → idempotent re-run.
+            // `writeRawObject` is on the concrete BaseStorage (used by the generational
+            // record layer for `_system/` artifacts), not the public `StorageAdapter`
+            // type — the same structural cast readOnDiskBrainFormat uses for the read side.
+            await writeBrainFormat(this.storage);
+            const elapsedMs = Date.now() - startedAt;
+            this.state = 'done';
+            this.status = null;
+            prodLog.info(`[Cor] migration complete (${elapsedMs} ms) — brain upgraded to 8.0 across all 3 derived indexes`);
+            // Clear the completion triplet THEN settle it: a subsequent run (retry path)
+            // must get a fresh promise + resolvers, never this already-settled one. The
+            // callers that hold the returned promise still settle (they reference the
+            // object, not the field); post-settle whenMigrationComplete() answers from
+            // `state`, so nulling the field is safe.
+            const resolve = this.resolveComplete;
+            this.completePromise = null;
+            this.resolveComplete = null;
+            this.rejectComplete = null;
+            resolve?.();
+        }
+        catch (error) {
+            // Keep the brain LOCKED on failure: releasing reads onto a half-built index
+            // would surface stale/partial results with no signal — worse than a clear
+            // block. Surface loudly; a restart re-detects the drift and re-runs the
+            // idempotent in-place rebuild (a transient hiccup self-heals; genuinely
+            // corrupt canonical data stays safely blocked).
+            this.failure = error instanceof Error ? error : new Error(String(error));
+            this.state = 'failed';
+            this.status = { phase: 'failed', index: currentIndex };
+            prodLog.error(`[Cor] migration FAILED — the brain stays locked (unmigrated) rather than ` +
+                `serve a half-built index. Restart to retry the automatic upgrade, or run ` +
+                `scripts/migrate-cortex-2x-to-3x.mjs for an offline migration. Cause: ` +
+                `${this.failure.message}`);
+            // Clear the completion triplet THEN reject it (see the success path) so the
+            // RETRY after this failure gets a fresh promise. Until that retry's start()
+            // resets `state`, whenMigrationComplete() rejects from the 'failed' state +
+            // the retained `this.failure`, not from this (now-detached) promise.
+            const reject = this.rejectComplete;
+            this.completePromise = null;
+            this.resolveComplete = null;
+            this.rejectComplete = null;
+            reject?.(this.failure);
+        }
+    }
+}
+//# sourceMappingURL=MigrationCoordinator.js.map

package/dist/migration/indexEpochGuard.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @module migration/indexEpochGuard
+ * @description Read-side of the 7.x → 8.0 whole-brain auto-migration (#18) —
+ * the open-time epoch-drift detection cor performs on its own derived indexes
+ * (Adaptive DiskANN vectors, the LSM metadata postings, the graph adjacency
+ * trees).
+ *
+ * ## The handshake cor binds against
+ *
+ * Brainy 8.0 persists a tiny version-handshake marker at
+ * `_system/brain-format.json` (`{ dataFormat, indexEpoch }`). `indexEpoch` is a
+ * SHARED, lockstep-bumped integer that Brainy and cor advance TOGETHER on any
+ * coordinated release whose on-disk derived-index format changes. On open,
+ * Brainy compares the on-disk `indexEpoch` against its compiled
+ * `EXPECTED_INDEX_EPOCH`; a mismatch — or an absent marker (a pre-handshake 7.x
+ * brain, or a brand-new store) — means every derived index on disk predates
+ * this build and must be rebuilt from the canonical records.
+ *
+ * cor cannot reach Brainy's value: `brain.formatInfo()` is a brain method, and
+ * cor's providers receive only the storage adapter. cor also cannot import
+ * Brainy's `brainFormat` module (it is not in Brainy's public exports). So cor
+ * reads the same marker off storage directly and compiles its OWN
+ * {@link COR_EXPECTED_INDEX_EPOCH}.
+ *
+ * ## Lockstep contract — DO NOT bump unilaterally
+ *
+ * {@link COR_EXPECTED_INDEX_EPOCH} MUST equal Brainy's `EXPECTED_INDEX_EPOCH`
+ * (the constant declared at `@soulcraft/brainy/dist/storage/brainFormat.d.ts:69`
+ * — value `1`, the 8.0 GA baseline). The two are a duplicated constant on
+ * purpose: cor has no compile-time dependency on Brainy's marker module, so the
+ * value lives here too. NEVER advance one side alone. It advances only on a
+ * coordinated brainy+cor release whose on-disk derived-index format actually
+ * changed, and both projects ship the SAME new value in the same release — so a
+ * brain written by either side is recognised as current by the other, and a
+ * brain written by an older build of either side is recognised as stale and
+ * rebuilt.
+ *
+ * ## What this module does NOT do
+ *
+ * It performs read-side detection only — reading the marker, classifying drift,
+ * sizing the brain, and resolving the auto-migrate policy. The actual rebuild
+ * of a SMALL brain is driven by Brainy's `rebuildIndexesIfNeeded` (which calls
+ * each cor provider's `rebuild()` from canonical and re-stamps the marker). The
+ * non-blocking background build-new → verify → swap for a LARGE brain is the
+ * rc.8 increment (it needs Brainy's deference hook + a stamp method that are not
+ * yet shipped) and lives nowhere in this module.
+ */
+import type { StorageAdapter } from '@soulcraft/brainy';
+/**
+ * @description The derived-index format epoch this cor build expects on disk.
+ * SHARED and lockstep-bumped with Brainy's `EXPECTED_INDEX_EPOCH`
+ * (`@soulcraft/brainy` → `storage/brainFormat`, value `1` — the 8.0 GA
+ * baseline). Advance it (in BOTH projects, to the same value, in one
+ * coordinated release) ONLY on a change to the on-disk format of any derived
+ * index — never on one side alone. An on-disk `indexEpoch` that differs from
+ * this — or an absent marker — means the derived indexes predate this build and
+ * are stale.
+ */
+export declare const COR_EXPECTED_INDEX_EPOCH = 1;
+/**
+ * @description Storage-root-relative path of the version-handshake marker.
+ * Mirrors Brainy's `BRAIN_FORMAT_PATH` (the constant is not exported from
+ * Brainy, so it is re-declared here — a stable on-disk path).
+ */
+export declare const BRAIN_FORMAT_PATH = "_system/brain-format.json";
+/**
+ * @description Default brain-size boundary (canonical noun count) above which a
+ * 7.x → 8.0 migration is treated as a LARGE brain. Mirrors Brainy's
+ * `AUTO_REBUILD_THRESHOLD` (10000): below it Brainy auto-rebuilds all derived
+ * indexes inline on open; at or above it Brainy defers to lazy first-query
+ * rebuilds. cor uses the SAME boundary so the two agree on which brains take the
+ * small (Brainy-driven) versus large (cor-owned, rc.8 background-swap) path.
+ * Overridable via the `COR_LARGE_BRAIN_THRESHOLD` env var.
+ */
+export declare const COR_LARGE_BRAIN_THRESHOLD_DEFAULT = 10000;
+/**
+ * @description The parsed shape of `_system/brain-format.json` — the same two
+ * fields Brainy's `BrainFormat` carries.
+ */
+export interface OnDiskBrainFormat {
+    /** Brainy-owned data-layer version string (e.g. `'8.0'`). */
+    dataFormat: string;
+    /** Shared, lockstep-bumped derived-index format epoch (e.g. `1`). */
+    indexEpoch: number;
+}
+/**
+ * @description Read the on-disk version-handshake marker, reimplementing
+ * Brainy's `readBrainFormat` validation so cor classifies drift identically
+ * without importing Brainy's (non-exported) marker module. Returns `null` when
+ * the marker is absent (a pre-handshake 7.x brain, or a brand-new store) OR
+ * malformed (not an object, missing either field, or a non-finite epoch) — a
+ * corrupt marker forces a safe rebuild rather than trusting a bad epoch.
+ *
+ * Storage that does not implement `readRawObject` (a non-`BaseStorage` adapter)
+ * is treated as having no marker — the cloud/JS path cor never accelerates.
+ *
+ * @param storage - The brain's storage adapter (raw-object surface accessed via
+ *   a structural cast — `readRawObject` is on `BaseStorage`, not the
+ *   `StorageAdapter` type).
+ * @returns The parsed {@link OnDiskBrainFormat}, or `null`.
+ * @example
+ * const onDisk = await readOnDiskBrainFormat(storage)
+ * const stale = isEpochStale(onDisk)
+ */
+export declare function readOnDiskBrainFormat(storage: StorageAdapter): Promise<OnDiskBrainFormat | null>;
+/**
+ * @description Classify the on-disk marker as stale (derived indexes predate
+ * this build) or current. Stale when the marker is absent ({@link
+ * readOnDiskBrainFormat} returned `null`) OR its `indexEpoch` differs from
+ * {@link COR_EXPECTED_INDEX_EPOCH}.
+ *
+ * @param onDisk - The result of {@link readOnDiskBrainFormat}.
+ * @returns `true` when a derived-index rebuild is required.
+ */
+export declare function isEpochStale(onDisk: OnDiskBrainFormat | null): boolean;
+/**
+ * @description Resolve the large-brain boundary, honouring the
+ * `COR_LARGE_BRAIN_THRESHOLD` env override (a non-negative finite integer);
+ * falls back to {@link COR_LARGE_BRAIN_THRESHOLD_DEFAULT} when unset or
+ * unparseable.
+ *
+ * @returns The canonical noun count at or above which a migration is LARGE.
+ */
+export declare function resolveLargeBrainThreshold(): number;
+/**
+ * @description Size the brain by its canonical noun count, via
+ * `getNouns({ pagination: { limit: 1 } }).totalCount` — the same one-row probe
+ * Brainy's `rebuildIndexesIfNeeded` uses to decide small-versus-large. A
+ * storage error (or a missing `totalCount`) reports `0`, which classifies the
+ * brain as small and lets Brainy's path drive — the conservative default that
+ * never throws the loud large-brain migration error on an unreadable probe.
+ *
+ * @param storage - The brain's storage adapter.
+ * @returns The canonical noun count (`0` when unknown).
+ */
+export declare function detectBrainSize(storage: StorageAdapter): Promise<number>;
+/**
+ * @description Resolve the auto-migrate policy from the environment.
+ * `config.autoMigrate` is unreachable from a cor provider (the provider receives
+ * only storage, not the brain config), so the policy is an env var:
+ * `COR_AUTO_MIGRATE`. Defaults to `true` (migrate automatically). Only the
+ * explicit opt-outs `'false'` / `'0'` (case-insensitive, trimmed) disable it —
+ * any other value (or unset) is `true`.
+ *
+ * @returns `true` when cor should migrate automatically; `false` when the
+ *   operator has opted out and wants the loud {@link IndexMigrationRequiredError}
+ *   on a large stale brain.
+ */
+export declare function resolveAutoMigrate(): boolean;
+/**
+ * @description Thrown from `MetadataIndexManager.init()` when a LARGE brain
+ * carries stale (drifted or absent) derived-index epoch state on disk AND
+ * auto-migrate is disabled ({@link resolveAutoMigrate} is `false`). Modeled on
+ * `MetadataIndexLegacyJsonStateDetected`: it is loud and pre-serve — a service
+ * that refuses to start is recoverable, whereas serving on indexes that predate
+ * this build would surface stale/empty results with no signal. Catchable for
+ * callers that prefer a one-shot warning, but the default (uncaught) is the
+ * right behaviour for production.
+ */
+export declare class IndexMigrationRequiredError extends Error {
+    readonly name = "IndexMigrationRequiredError";
+}
+//# sourceMappingURL=indexEpochGuard.d.ts.map

package/dist/migration/indexEpochGuard.js

@@ -0,0 +1,202 @@
+/**
+ * @module migration/indexEpochGuard
+ * @description Read-side of the 7.x → 8.0 whole-brain auto-migration (#18) —
+ * the open-time epoch-drift detection cor performs on its own derived indexes
+ * (Adaptive DiskANN vectors, the LSM metadata postings, the graph adjacency
+ * trees).
+ *
+ * ## The handshake cor binds against
+ *
+ * Brainy 8.0 persists a tiny version-handshake marker at
+ * `_system/brain-format.json` (`{ dataFormat, indexEpoch }`). `indexEpoch` is a
+ * SHARED, lockstep-bumped integer that Brainy and cor advance TOGETHER on any
+ * coordinated release whose on-disk derived-index format changes. On open,
+ * Brainy compares the on-disk `indexEpoch` against its compiled
+ * `EXPECTED_INDEX_EPOCH`; a mismatch — or an absent marker (a pre-handshake 7.x
+ * brain, or a brand-new store) — means every derived index on disk predates
+ * this build and must be rebuilt from the canonical records.
+ *
+ * cor cannot reach Brainy's value: `brain.formatInfo()` is a brain method, and
+ * cor's providers receive only the storage adapter. cor also cannot import
+ * Brainy's `brainFormat` module (it is not in Brainy's public exports). So cor
+ * reads the same marker off storage directly and compiles its OWN
+ * {@link COR_EXPECTED_INDEX_EPOCH}.
+ *
+ * ## Lockstep contract — DO NOT bump unilaterally
+ *
+ * {@link COR_EXPECTED_INDEX_EPOCH} MUST equal Brainy's `EXPECTED_INDEX_EPOCH`
+ * (the constant declared at `@soulcraft/brainy/dist/storage/brainFormat.d.ts:69`
+ * — value `1`, the 8.0 GA baseline). The two are a duplicated constant on
+ * purpose: cor has no compile-time dependency on Brainy's marker module, so the
+ * value lives here too. NEVER advance one side alone. It advances only on a
+ * coordinated brainy+cor release whose on-disk derived-index format actually
+ * changed, and both projects ship the SAME new value in the same release — so a
+ * brain written by either side is recognised as current by the other, and a
+ * brain written by an older build of either side is recognised as stale and
+ * rebuilt.
+ *
+ * ## What this module does NOT do
+ *
+ * It performs read-side detection only — reading the marker, classifying drift,
+ * sizing the brain, and resolving the auto-migrate policy. The actual rebuild
+ * of a SMALL brain is driven by Brainy's `rebuildIndexesIfNeeded` (which calls
+ * each cor provider's `rebuild()` from canonical and re-stamps the marker). The
+ * non-blocking background build-new → verify → swap for a LARGE brain is the
+ * rc.8 increment (it needs Brainy's deference hook + a stamp method that are not
+ * yet shipped) and lives nowhere in this module.
+ */
+// brainy rc.8 exports the shared epoch constant. Import it as the SINGLE SOURCE
+// OF TRUTH rather than duplicating the literal here — the two can no longer drift.
+import { EXPECTED_INDEX_EPOCH } from '@soulcraft/brainy/brain-format';
+/**
+ * @description The derived-index format epoch this cor build expects on disk.
+ * SHARED and lockstep-bumped with Brainy's `EXPECTED_INDEX_EPOCH`
+ * (`@soulcraft/brainy` → `storage/brainFormat`, value `1` — the 8.0 GA
+ * baseline). Advance it (in BOTH projects, to the same value, in one
+ * coordinated release) ONLY on a change to the on-disk format of any derived
+ * index — never on one side alone. An on-disk `indexEpoch` that differs from
+ * this — or an absent marker — means the derived indexes predate this build and
+ * are stale.
+ */
+export const COR_EXPECTED_INDEX_EPOCH = EXPECTED_INDEX_EPOCH;
+/**
+ * @description Storage-root-relative path of the version-handshake marker.
+ * Mirrors Brainy's `BRAIN_FORMAT_PATH` (the constant is not exported from
+ * Brainy, so it is re-declared here — a stable on-disk path).
+ */
+export const BRAIN_FORMAT_PATH = '_system/brain-format.json';
+/**
+ * @description Default brain-size boundary (canonical noun count) above which a
+ * 7.x → 8.0 migration is treated as a LARGE brain. Mirrors Brainy's
+ * `AUTO_REBUILD_THRESHOLD` (10000): below it Brainy auto-rebuilds all derived
+ * indexes inline on open; at or above it Brainy defers to lazy first-query
+ * rebuilds. cor uses the SAME boundary so the two agree on which brains take the
+ * small (Brainy-driven) versus large (cor-owned, rc.8 background-swap) path.
+ * Overridable via the `COR_LARGE_BRAIN_THRESHOLD` env var.
+ */
+export const COR_LARGE_BRAIN_THRESHOLD_DEFAULT = 10000;
+/**
+ * @description Read the on-disk version-handshake marker, reimplementing
+ * Brainy's `readBrainFormat` validation so cor classifies drift identically
+ * without importing Brainy's (non-exported) marker module. Returns `null` when
+ * the marker is absent (a pre-handshake 7.x brain, or a brand-new store) OR
+ * malformed (not an object, missing either field, or a non-finite epoch) — a
+ * corrupt marker forces a safe rebuild rather than trusting a bad epoch.
+ *
+ * Storage that does not implement `readRawObject` (a non-`BaseStorage` adapter)
+ * is treated as having no marker — the cloud/JS path cor never accelerates.
+ *
+ * @param storage - The brain's storage adapter (raw-object surface accessed via
+ *   a structural cast — `readRawObject` is on `BaseStorage`, not the
+ *   `StorageAdapter` type).
+ * @returns The parsed {@link OnDiskBrainFormat}, or `null`.
+ * @example
+ * const onDisk = await readOnDiskBrainFormat(storage)
+ * const stale = isEpochStale(onDisk)
+ */
+export async function readOnDiskBrainFormat(storage) {
+    const reader = storage;
+    if (typeof reader.readRawObject !== 'function')
+        return null;
+    let raw;
+    try {
+        raw = await reader.readRawObject(BRAIN_FORMAT_PATH);
+    }
+    catch {
+        // A read error during the probe is treated as "no marker": we cannot read
+        // it, so the safe default (drift → rebuild) applies rather than erroring on
+        // a transient storage hiccup at every open.
+        return null;
+    }
+    if (raw === null || raw === undefined || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    if (typeof obj.dataFormat !== 'string' ||
+        typeof obj.indexEpoch !== 'number' ||
+        !Number.isFinite(obj.indexEpoch)) {
+        return null;
+    }
+    return { dataFormat: obj.dataFormat, indexEpoch: obj.indexEpoch };
+}
+/**
+ * @description Classify the on-disk marker as stale (derived indexes predate
+ * this build) or current. Stale when the marker is absent ({@link
+ * readOnDiskBrainFormat} returned `null`) OR its `indexEpoch` differs from
+ * {@link COR_EXPECTED_INDEX_EPOCH}.
+ *
+ * @param onDisk - The result of {@link readOnDiskBrainFormat}.
+ * @returns `true` when a derived-index rebuild is required.
+ */
+export function isEpochStale(onDisk) {
+    return onDisk === null || onDisk.indexEpoch !== COR_EXPECTED_INDEX_EPOCH;
+}
+/**
+ * @description Resolve the large-brain boundary, honouring the
+ * `COR_LARGE_BRAIN_THRESHOLD` env override (a non-negative finite integer);
+ * falls back to {@link COR_LARGE_BRAIN_THRESHOLD_DEFAULT} when unset or
+ * unparseable.
+ *
+ * @returns The canonical noun count at or above which a migration is LARGE.
+ */
+export function resolveLargeBrainThreshold() {
+    const raw = process.env.COR_LARGE_BRAIN_THRESHOLD;
+    if (raw === undefined)
+        return COR_LARGE_BRAIN_THRESHOLD_DEFAULT;
+    const n = Number(raw.trim());
+    return Number.isFinite(n) && n >= 0 ? n : COR_LARGE_BRAIN_THRESHOLD_DEFAULT;
+}
+/**
+ * @description Size the brain by its canonical noun count, via
+ * `getNouns({ pagination: { limit: 1 } }).totalCount` — the same one-row probe
+ * Brainy's `rebuildIndexesIfNeeded` uses to decide small-versus-large. A
+ * storage error (or a missing `totalCount`) reports `0`, which classifies the
+ * brain as small and lets Brainy's path drive — the conservative default that
+ * never throws the loud large-brain migration error on an unreadable probe.
+ *
+ * @param storage - The brain's storage adapter.
+ * @returns The canonical noun count (`0` when unknown).
+ */
+export async function detectBrainSize(storage) {
+    try {
+        const probe = await storage.getNouns({
+            pagination: { limit: 1 },
+        });
+        return probe?.totalCount ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * @description Resolve the auto-migrate policy from the environment.
+ * `config.autoMigrate` is unreachable from a cor provider (the provider receives
+ * only storage, not the brain config), so the policy is an env var:
+ * `COR_AUTO_MIGRATE`. Defaults to `true` (migrate automatically). Only the
+ * explicit opt-outs `'false'` / `'0'` (case-insensitive, trimmed) disable it —
+ * any other value (or unset) is `true`.
+ *
+ * @returns `true` when cor should migrate automatically; `false` when the
+ *   operator has opted out and wants the loud {@link IndexMigrationRequiredError}
+ *   on a large stale brain.
+ */
+export function resolveAutoMigrate() {
+    const raw = process.env.COR_AUTO_MIGRATE;
+    if (raw === undefined)
+        return true;
+    const normalized = raw.trim().toLowerCase();
+    return !(normalized === 'false' || normalized === '0');
+}
+/**
+ * @description Thrown from `MetadataIndexManager.init()` when a LARGE brain
+ * carries stale (drifted or absent) derived-index epoch state on disk AND
+ * auto-migrate is disabled ({@link resolveAutoMigrate} is `false`). Modeled on
+ * `MetadataIndexLegacyJsonStateDetected`: it is loud and pre-serve — a service
+ * that refuses to start is recoverable, whereas serving on indexes that predate
+ * this build would surface stale/empty results with no signal. Catchable for
+ * callers that prefer a one-shot warning, but the default (uncaught) is the
+ * right behaviour for production.
+ */
+export class IndexMigrationRequiredError extends Error {
+    name = 'IndexMigrationRequiredError';
+}
+//# sourceMappingURL=indexEpochGuard.js.map