@soulcraft/cor 3.0.0-rc.1

package/dist/license/onlineValidator.js

@@ -0,0 +1,225 @@
+/**
+ * Online license heartbeat (v2)
+ *
+ * Background check against Portal API for:
+ * - Status-based subscription state (active, past_due, canceled, etc.)
+ * - Key renewal (subscription renewed, fresh JWT cached in memory)
+ * - Server-driven check intervals via nextCheckSeconds
+ *
+ * No signature verification here — that's in Rust.
+ * Default 24h heartbeat interval, 14-day grace period.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { API_URL, CACHE_DIR, HEARTBEAT_FILE, GRACE_PERIOD_DAYS, DEFAULT_CHECK_INTERVAL_MS, ONLINE_VALIDATION_TIMEOUT_MS, } from './constants.js';
+function getDefaultCacheDir() {
+    return join(process.cwd(), CACHE_DIR);
+}
+function getDefaultCachePath() {
+    return join(process.cwd(), CACHE_DIR, HEARTBEAT_FILE);
+}
+/**
+ * Read the heartbeat cache from disk. Returns null if not found or unreadable.
+ */
+export async function readHeartbeatCache() {
+    return readHeartbeatCacheAt(getDefaultCachePath());
+}
+/**
+ * Check if a grace period start timestamp is expired (> GRACE_PERIOD_DAYS old).
+ */
+export function isGracePeriodExpired(gracePeriodStart) {
+    const start = new Date(gracePeriodStart);
+    if (isNaN(start.getTime()))
+        return false;
+    const elapsedMs = Date.now() - start.getTime();
+    return elapsedMs >= GRACE_PERIOD_DAYS * 24 * 60 * 60 * 1000;
+}
+/**
+ * Perform background heartbeat check.
+ *
+ * Call this after successful Rust validation. Non-blocking (fire and forget).
+ * Returns a warning string if the user should be notified.
+ * Returns degrade: true if the license is suspended or the grace period has expired.
+ *
+ * @param token - License key token
+ * @param options.forceCheck - Skip interval check, always call API (use at process startup)
+ */
+export async function performHeartbeat(token, options) {
+    const cachePath = getDefaultCachePath();
+    const cacheDir = getDefaultCacheDir();
+    const cache = await readHeartbeatCacheAt(cachePath);
+    const forceCheck = options?.forceCheck ?? false;
+    // Old cache format (has revoked boolean, no status field) is treated as stale
+    const isDue = forceCheck || cache === null || !cache.status || isHeartbeatDue(cache);
+    if (!isDue) {
+        // Not due for a network check — return cached grace state
+        if (cache?.status === 'suspended') {
+            return { degrade: true };
+        }
+        if (cache?.gracePeriodStart) {
+            return checkGracePeriod(cache.gracePeriodStart, cache.status);
+        }
+        return {};
+    }
+    // Perform the network check
+    try {
+        const response = await callApi(token);
+        return await handleResponse(response, cacheDir, cachePath, cache);
+    }
+    catch {
+        // Network error — use cached state, don't block
+        if (cache?.status === 'suspended') {
+            return { degrade: true };
+        }
+        if (cache?.gracePeriodStart) {
+            return checkGracePeriod(cache.gracePeriodStart, cache.status);
+        }
+        return {};
+    }
+}
+function isHeartbeatDue(cache) {
+    // Use server-driven next check time if available
+    if (cache.nextCheckAt) {
+        const nextCheck = new Date(cache.nextCheckAt);
+        if (!isNaN(nextCheck.getTime())) {
+            return Date.now() >= nextCheck.getTime();
+        }
+    }
+    // Fallback: DEFAULT_CHECK_INTERVAL_MS from lastCheck
+    const lastCheck = new Date(cache.lastCheck);
+    if (isNaN(lastCheck.getTime()))
+        return true;
+    return Date.now() - lastCheck.getTime() >= DEFAULT_CHECK_INTERVAL_MS;
+}
+async function callApi(token) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), ONLINE_VALIDATION_TIMEOUT_MS);
+    try {
+        const response = await fetch(API_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ licenseKey: token }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`API returned ${response.status}`);
+        }
+        return (await response.json());
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function handleResponse(response, cacheDir, cachePath, existingCache) {
+    // 1. Cache renewed key in memory FIRST — before any status handling
+    if (response.renewedKey) {
+        const { updateCachedToken } = await import('../license.js');
+        updateCachedToken(response.renewedKey);
+    }
+    const now = new Date().toISOString();
+    const nextCheckAt = response.nextCheckSeconds
+        ? new Date(Date.now() + response.nextCheckSeconds * 1000).toISOString()
+        : undefined;
+    const status = response.status;
+    // 2. Dispatch on status
+    switch (status) {
+        case 'active': {
+            await writeHeartbeatCache(cachePath, { lastCheck: now, nextCheckAt, status });
+            return {};
+        }
+        case 'past_due': {
+            await writeHeartbeatCache(cachePath, { lastCheck: now, nextCheckAt, status });
+            return {
+                warning: response.warning ??
+                    'Subscription payment is past due. Please update your payment method at soulcraft.com/account',
+            };
+        }
+        case 'key_revoked': {
+            const gracePeriodStart = existingCache?.gracePeriodStart ?? now;
+            await writeHeartbeatCache(cachePath, { lastCheck: now, nextCheckAt, status, gracePeriodStart });
+            return checkGracePeriod(gracePeriodStart, status);
+        }
+        case 'canceled': {
+            const gracePeriodStart = existingCache?.gracePeriodStart ?? now;
+            await writeHeartbeatCache(cachePath, { lastCheck: now, nextCheckAt, status, gracePeriodStart });
+            return checkGracePeriod(gracePeriodStart, status);
+        }
+        case 'expired': {
+            const gracePeriodStart = existingCache?.gracePeriodStart ?? now;
+            await writeHeartbeatCache(cachePath, { lastCheck: now, nextCheckAt, status, gracePeriodStart });
+            return checkGracePeriod(gracePeriodStart, status);
+        }
+        case 'not_found': {
+            const gracePeriodStart = existingCache?.gracePeriodStart ?? now;
+            await writeHeartbeatCache(cachePath, { lastCheck: now, nextCheckAt, status, gracePeriodStart });
+            return checkGracePeriod(gracePeriodStart, status);
+        }
+        case 'suspended': {
+            // Immediate degrade — no grace period
+            await writeHeartbeatCache(cachePath, { lastCheck: now, nextCheckAt, status });
+            return {
+                degrade: true,
+                warning: 'License suspended. Compute acceleration disabled. Contact support at soulcraft.com/support',
+            };
+        }
+        default: {
+            // Unknown status — treat as active if valid, else start grace period
+            if (response.valid) {
+                await writeHeartbeatCache(cachePath, { lastCheck: now, nextCheckAt, status: status ?? 'active' });
+                return {};
+            }
+            const gracePeriodStart = existingCache?.gracePeriodStart ?? now;
+            await writeHeartbeatCache(cachePath, { lastCheck: now, nextCheckAt, status, gracePeriodStart });
+            return checkGracePeriod(gracePeriodStart, status);
+        }
+    }
+}
+function checkGracePeriod(gracePeriodStart, status) {
+    const start = new Date(gracePeriodStart);
+    if (isNaN(start.getTime())) {
+        return { warning: 'License validation failed. Please check your license at soulcraft.com/account' };
+    }
+    const elapsed = Date.now() - start.getTime();
+    const elapsedDays = elapsed / (1000 * 60 * 60 * 24);
+    const daysRemaining = Math.ceil(GRACE_PERIOD_DAYS - elapsedDays);
+    if (daysRemaining <= 0) {
+        return { degrade: true };
+    }
+    const dayStr = daysRemaining === 1 ? 'day' : 'days';
+    const actionMsg = statusToActionMessage(status);
+    return { warning: `${actionMsg} Grace period: ${daysRemaining} ${dayStr} remaining.` };
+}
+function statusToActionMessage(status) {
+    switch (status) {
+        case 'key_revoked':
+            return 'License key revoked. Get a new key at soulcraft.com/account.';
+        case 'canceled':
+            return 'Subscription canceled. Renew at soulcraft.com/account.';
+        case 'expired':
+            return 'Subscription expired. Renew at soulcraft.com/account.';
+        case 'not_found':
+            return 'License key not found. Your key may be corrupted. Check soulcraft.com/account.';
+        default:
+            return 'License lapsed. Renew at soulcraft.com/account.';
+    }
+}
+async function readHeartbeatCacheAt(path) {
+    try {
+        const content = await readFile(path, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeHeartbeatCache(path, cache) {
+    try {
+        const dir = join(path, '..');
+        await mkdir(dir, { recursive: true });
+        await writeFile(path, JSON.stringify(cache, null, 2), 'utf-8');
+    }
+    catch {
+        // Silently fail if filesystem is read-only
+    }
+}
+//# sourceMappingURL=onlineValidator.js.map

package/dist/license/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared types for license validation (v2)
+ */
+/** Result of license validation */
+export interface LicenseResult {
+    valid: boolean;
+    tier: 'free' | 'pro' | 'enterprise' | 'internal';
+    email: string;
+    expiresAt: number;
+    error?: string;
+}
+/** License details from Portal validation response */
+export interface OnlineValidationLicense {
+    tier: string;
+    product: string;
+    email: string;
+    expiresAt: string | null;
+}
+/** Response from Portal validation API (heartbeat) */
+export interface OnlineValidationResponse {
+    /** Whether the license key is valid */
+    valid: boolean;
+    /**
+     * License status from Portal:
+     * "active" | "past_due" | "key_revoked" | "canceled" | "suspended" | "not_found" | "expired"
+     */
+    status?: string;
+    /** Error message if invalid */
+    error?: string;
+    /** Warning message (e.g. for past_due) */
+    warning?: string;
+    /** License details when valid */
+    license?: OnlineValidationLicense;
+    /** Renewed license key (if subscription renewed, write to disk) */
+    renewedKey?: string;
+    /** Server-suggested seconds until next check */
+    nextCheckSeconds?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/license/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for license validation (v2)
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/license.d.ts

@@ -0,0 +1,64 @@
+/**
+ * License validation for @soulcraft/cor v2
+ *
+ * Sources, in precedence order:
+ *   1. COR_LICENSE_KEY env var (legacy CORTEX_LICENSE_KEY honored) — lets a
+ *      deploy inject the key without writing a file: CI, immutable container
+ *      images, serverless, and secrets managers (Vault / GCP Secret Manager).
+ *   2. .soulcraft.json in the project root.
+ * Either source may hold a full JWT or a short activation code (CO-XXXX-XXXX);
+ * a short code is exchanged for a JWT via the API on first use and cached in
+ * memory for the process lifetime.
+ */
+export interface LicenseResult {
+    valid: boolean;
+    tier: 'free' | 'pro' | 'enterprise' | 'internal';
+    email: string;
+    expiresAt: number;
+    error?: string;
+}
+/**
+ * Update the in-memory cached token. Called by the heartbeat when the server
+ * issues a renewedKey — no file write needed.
+ */
+export declare function updateCachedToken(jwt: string): void;
+/**
+ * Test whether a string is a short activation code (CX-XXXX-XXXX).
+ */
+export declare function isShortCode(value: string): boolean;
+/**
+ * Read the project config file (.soulcraft.json).
+ * Returns an empty object if the file doesn't exist or can't be parsed.
+ */
+export declare function readConfig(): Promise<Record<string, string>>;
+/**
+ * Write keys to .soulcraft.json, merging with any existing content.
+ * Uses an atomic tmp → rename write to avoid partial writes.
+ */
+export declare function writeConfig(config: Record<string, string>): Promise<void>;
+/**
+ * Exchange a short activation code for a JWT via the API.
+ * Returns the JWT string, or null on any error (network, invalid code, etc.).
+ */
+export declare function exchangeShortCode(code: string): Promise<string | null>;
+/**
+ * Read the license token, performing short code exchange if needed.
+ *
+ * Sources (in precedence order):
+ * 1. In-memory cache (set by updateCachedToken after heartbeat renewal)
+ * 2. COR_LICENSE_KEY env var (legacy CORTEX_LICENSE_KEY honored) — 12-factor
+ *    injection for CI / immutable images / serverless / secrets managers
+ * 3. .soulcraft.json in process.cwd() (`cor` key, legacy `cortex` fallback)
+ *
+ * The value from either external source may be a short code (exchanged for a
+ * JWT) or a full JWT (used directly).
+ */
+export declare function readLicenseToken(): Promise<string | null>;
+/**
+ * Validate the Soulcraft Cor license.
+ *
+ * Returns a LicenseResult with tier info. Free tier is always valid (no key needed).
+ * Pro/Enterprise/Internal require a valid Ed25519-signed JWT key.
+ */
+export declare function validateLicense(): Promise<LicenseResult>;
+//# sourceMappingURL=license.d.ts.map

package/dist/license.js

@@ -0,0 +1,165 @@
+/**
+ * License validation for @soulcraft/cor v2
+ *
+ * Sources, in precedence order:
+ *   1. COR_LICENSE_KEY env var (legacy CORTEX_LICENSE_KEY honored) — lets a
+ *      deploy inject the key without writing a file: CI, immutable container
+ *      images, serverless, and secrets managers (Vault / GCP Secret Manager).
+ *   2. .soulcraft.json in the project root.
+ * Either source may hold a full JWT or a short activation code (CO-XXXX-XXXX);
+ * a short code is exchanged for a JWT via the API on first use and cached in
+ * memory for the process lifetime.
+ */
+import { readFile, writeFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONFIG_FILE, EXCHANGE_URL, SHORT_CODE_PATTERN, ONLINE_VALIDATION_TIMEOUT_MS, } from './license/constants.js';
+const FREE = { valid: false, tier: 'free', email: '', expiresAt: 0 };
+/** In-memory cache for the exchanged JWT (process lifetime) */
+let cachedToken = null;
+/**
+ * Update the in-memory cached token. Called by the heartbeat when the server
+ * issues a renewedKey — no file write needed.
+ */
+export function updateCachedToken(jwt) {
+    cachedToken = jwt;
+}
+/**
+ * Test whether a string is a short activation code (CX-XXXX-XXXX).
+ */
+export function isShortCode(value) {
+    return SHORT_CODE_PATTERN.test(value);
+}
+/**
+ * Read the project config file (.soulcraft.json).
+ * Returns an empty object if the file doesn't exist or can't be parsed.
+ */
+export async function readConfig() {
+    try {
+        const content = await readFile(join(process.cwd(), CONFIG_FILE), 'utf-8');
+        const parsed = JSON.parse(content);
+        if (typeof parsed === 'object' && parsed !== null) {
+            return parsed;
+        }
+    }
+    catch {
+        // Missing or malformed config — treat as empty
+    }
+    return {};
+}
+/**
+ * Write keys to .soulcraft.json, merging with any existing content.
+ * Uses an atomic tmp → rename write to avoid partial writes.
+ */
+export async function writeConfig(config) {
+    const configPath = join(process.cwd(), CONFIG_FILE);
+    const tmpPath = `${configPath}.tmp`;
+    const existing = await readConfig();
+    const merged = { ...existing, ...config };
+    await writeFile(tmpPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+    await rename(tmpPath, configPath);
+}
+/**
+ * Exchange a short activation code for a JWT via the API.
+ * Returns the JWT string, or null on any error (network, invalid code, etc.).
+ */
+export async function exchangeShortCode(code) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), ONLINE_VALIDATION_TIMEOUT_MS);
+    // Allow tests to override the exchange URL via environment variable
+    // (COR_TEST_EXCHANGE_URL; legacy CORTEX_TEST_EXCHANGE_URL still honored).
+    const exchangeUrl = process.env.COR_TEST_EXCHANGE_URL ?? process.env.CORTEX_TEST_EXCHANGE_URL ?? EXCHANGE_URL;
+    try {
+        const response = await fetch(exchangeUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ code }),
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        return data.licenseKey ?? data.token ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Resolve a raw license value (from the env var or the config file) into a
+ * usable JWT: a short activation code is exchanged for a JWT (and cached); a
+ * full JWT is used directly (and cached). Returns null if a short-code
+ * exchange fails.
+ */
+async function resolveTokenValue(value) {
+    if (isShortCode(value)) {
+        const jwt = await exchangeShortCode(value);
+        if (jwt) {
+            cachedToken = jwt;
+            return jwt;
+        }
+        // Exchange failed — no token available
+        return null;
+    }
+    // Direct JWT (or legacy sc_cortex_ token)
+    cachedToken = value;
+    return value;
+}
+/**
+ * Read the license token, performing short code exchange if needed.
+ *
+ * Sources (in precedence order):
+ * 1. In-memory cache (set by updateCachedToken after heartbeat renewal)
+ * 2. COR_LICENSE_KEY env var (legacy CORTEX_LICENSE_KEY honored) — 12-factor
+ *    injection for CI / immutable images / serverless / secrets managers
+ * 3. .soulcraft.json in process.cwd() (`cor` key, legacy `cortex` fallback)
+ *
+ * The value from either external source may be a short code (exchanged for a
+ * JWT) or a full JWT (used directly).
+ */
+export async function readLicenseToken() {
+    if (cachedToken)
+        return cachedToken;
+    // Env var wins over the file so a deployment can inject the key without
+    // writing .soulcraft.json. Trimmed because secrets managers and `$(cat …)`
+    // often append a trailing newline.
+    const envValue = (process.env.COR_LICENSE_KEY ?? process.env.CORTEX_LICENSE_KEY)?.trim();
+    if (envValue)
+        return resolveTokenValue(envValue);
+    const config = await readConfig();
+    // Dual-read during the cortex→cor rename: prefer the new `cor` key, fall back
+    // to the legacy `cortex` key so already-deployed .soulcraft.json keeps working.
+    const value = config.cor ?? config.cortex;
+    if (!value)
+        return null;
+    return resolveTokenValue(value);
+}
+/**
+ * Validate the Soulcraft Cor license.
+ *
+ * Returns a LicenseResult with tier info. Free tier is always valid (no key needed).
+ * Pro/Enterprise/Internal require a valid Ed25519-signed JWT key.
+ */
+export async function validateLicense() {
+    const token = await readLicenseToken();
+    if (!token)
+        return FREE;
+    try {
+        const { loadNativeModule } = await import('./native/index.js');
+        const native = loadNativeModule();
+        const result = native.validateLicenseKey(token);
+        return {
+            valid: result.valid,
+            tier: result.tier,
+            email: result.email,
+            expiresAt: result.expiresAt,
+            error: result.error ?? undefined,
+        };
+    }
+    catch {
+        return { ...FREE, error: 'native module unavailable' };
+    }
+}
+//# sourceMappingURL=license.js.map

package/dist/migration/MigrationCoordinator.d.ts

@@ -0,0 +1,171 @@
+/**
+ * @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 type { StorageAdapter } from '@soulcraft/brainy';
+/** The three derived indexes cor rebuilds from canonical, in rebuild order. */
+export type MigrationIndexKind = 'metadata' | 'vector' | 'graph';
+/**
+ * @description Structured migration progress. cor owns every field; Brainy relays
+ * it verbatim into `getIndexStatus().migration` (Brainy adds `startedAt`/`elapsedMs`
+ * from when it first observed the lock). Every field is optional so a coarse
+ * "which index is rebuilding" answer is valid before per-entity counts arrive.
+ */
+export interface MigrationStatus {
+    /** Coarse stage, e.g. `'rebuilding'` / `'starting'` / `'failed'`. */
+    phase?: string;
+    /** Which derived index is rebuilding right now. */
+    index?: MigrationIndexKind;
+    /** 0–100 completion of the current index (omitted when the total is unknown). */
+    percent?: number;
+    /** Entities rebuilt into the current index so far. */
+    entitiesDone?: number;
+    /** Total entities the current index rebuild will process. */
+    entitiesTotal?: number;
+}
+/**
+ * @description The single capability the coordinator needs from each derived-index
+ * provider: a from-canonical rebuild. cor's three providers already rebuild from
+ * canonical (`#74` cursor-paginated / OOM-safe at any scale) with a no-argument
+ * `rebuild()` (the vector wrapper's optional-options overload is assignable to
+ * this). Per-entity progress — `migrationStatus().percent`/`entitiesDone` — is an
+ * additive follow-up that threads a callback through the rebuild cursors; it does
+ * NOT change this contract (those status fields are already optional), so the
+ * coordinator reports at the phase (per-index) granularity today.
+ */
+export interface MigratableProvider {
+    rebuild(): Promise<void>;
+}
+/** Lazy resolvers for the three provider instances (they are constructed by
+ * Brainy's provider factories after the coordinator, so they are read on demand —
+ * the same lazy-capture pattern the plugin uses for the id-mapper resolver). A
+ * resolver returning `undefined` (e.g. a provider a cloud adapter never engages)
+ * is skipped, not an error. */
+export interface MigrationProviders {
+    metadata: () => MigratableProvider | undefined;
+    vector: () => MigratableProvider | undefined;
+    graph: () => MigratableProvider | undefined;
+}
+/**
+ * @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 declare class MigrationCoordinator {
+    private readonly storage;
+    private readonly 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.
+     */
+    private state;
+    private status;
+    private completePromise;
+    private resolveComplete;
+    private rejectComplete;
+    private failure;
+    /**
+     * @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: StorageAdapter, providers: MigrationProviders);
+    /**
+     * @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(): boolean;
+    /**
+     * @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(): Promise<void>;
+    /**
+     * @description The structured progress Brainy relays into
+     * `getIndexStatus().migration`. `null` unless a migration is in flight.
+     * @returns The current {@link MigrationStatus}, or `null`.
+     */
+    migrationStatus(): MigrationStatus | 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(): Promise<void>;
+    /**
+     * 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.
+     */
+    private run;
+}
+//# sourceMappingURL=MigrationCoordinator.d.ts.map