@cortexkit/antigravity-auth-core 3.0.14 → 3.0.16

package/dist/account-migration.js

@@ -59,14 +59,94 @@ export function decodeAccountStorePointer(value, legacyPath) {
         throw new AccountMigrationError('pointer directory basename differs from its derived generation');
     return { schemaVersion: 1, id, directoryBasename: basename(paths.storeDir) };
 }
-async function readPointer(legacyPath) {
+/** Decodes either pointer schema; schema 1 keeps `decodeAccountStorePointer`'s exact rules. */
+export function decodeAccountStorePointerRecord(value, legacyPath) {
+    if (object(value, 'pointer').schemaVersion !== 2)
+        return decodeAccountStorePointer(value, legacyPath);
+    const raw = exact(value, ['schemaVersion', 'id', 'directoryBasename', 'relocatedTo'], 'forward');
+    const id = text(raw.id, UUID, 'forward source generation');
+    const paths = generationPaths(legacyPath, id);
+    if (raw.directoryBasename !== basename(paths.storeDir))
+        throw new AccountMigrationError('forward directory basename differs from its derived generation');
+    const target = exact(raw.relocatedTo, ['legacyPath', 'id'], 'forward target');
+    if (typeof target.legacyPath !== 'string')
+        throw new AccountMigrationError('forward target path is invalid');
+    const targetId = text(target.id, UUID, 'forward target generation');
+    const targetPaths = generationPaths(target.legacyPath, targetId);
+    if (sameFilesystemPath(targetPaths.legacyPath, legacyPath))
+        throw new AccountMigrationError('forward names its own anchor');
+    return {
+        schemaVersion: 2,
+        id,
+        directoryBasename: basename(paths.storeDir),
+        relocatedTo: {
+            legacyPath: targetPaths.legacyPath,
+            id: targetId,
+        },
+    };
+}
+async function readPointerRecord(legacyPath) {
     const logical = resolveAccountStorePaths(legacyPath);
     if (await exists(logical.storeDir))
         throw new AccountMigrationError('foreign logical store directory is not pointer authority');
     const path = accountStorePointerPath(legacyPath);
     if (!(await exists(path)))
         return undefined;
-    return decodeAccountStorePointer(jsonBytes(await secureRead(path)), legacyPath);
+    return decodeAccountStorePointerRecord(jsonBytes(await secureRead(path)), legacyPath);
+}
+/**
+ * The schema-1 pointer for operations that work on the generation published
+ * at this anchor. A forward refuses them: this build only reads a moved
+ * store (through `readAccountStoreBinding`) and never migrates, initializes,
+ * publishes over or writes beside one.
+ */
+async function readPointer(legacyPath) {
+    const record = await readPointerRecord(legacyPath);
+    if (record?.schemaVersion === 2)
+        throw new AccountMigrationError(`the account store moved to ${record.relocatedTo.legacyPath}; this operation does not follow a moved store`);
+    return record;
+}
+/**
+ * The anchor a forward leads to. The new anchor's pointer must publish
+ * exactly the generation the forward names; anything else (no pointer, a
+ * different generation, a second forward) refuses, because binding there
+ * would either serve the wrong store or report "no accounts" and let a login
+ * create a second store.
+ */
+async function forwardTarget(legacyPath, forward) {
+    const target = forward.relocatedTo.legacyPath;
+    const published = await readPointerRecord(target);
+    if (published?.schemaVersion !== 1 || published.id !== forward.relocatedTo.id)
+        throw new AccountMigrationError(`the forwarding pointer ${accountStorePointerPath(legacyPath)} names generation ${forward.relocatedTo.id}, which ${accountStorePointerPath(target)} does not publish`);
+    return target;
+}
+/**
+ * Resolves the caller's anchor to the one that holds the store: follows a
+ * schema-2 forward one step to the anchor it names, after checking that
+ * anchor still publishes the forwarded generation. Reads only; it writes
+ * nothing at either anchor.
+ */
+export async function resolveAccountStoreAnchor(legacyPath, options = {}) {
+    resolveAccountStorePaths(legacyPath);
+    const pointer = accountStorePointerPath(legacyPath);
+    for (const alternative of options.alternatives ?? []) {
+        if (sameFilesystemPath(alternative, legacyPath))
+            continue;
+        const other = accountStorePointerPath(alternative);
+        if ((await exists(pointer)) && (await exists(other)))
+            throw new AccountMigrationError(`account store pointers exist at both ${pointer} and ${other}; refusing to choose between them`);
+    }
+    const record = await readPointerRecord(legacyPath);
+    if (record?.schemaVersion !== 2)
+        return { legacyPath };
+    const named = record.relocatedTo.legacyPath;
+    if (options.relocatedAnchor !== undefined &&
+        !sameFilesystemPath(options.relocatedAnchor, named))
+        throw new AccountMigrationError(`the forwarding pointer ${pointer} names ${named}, but this process keeps the account store at ${options.relocatedAnchor}`);
+    return {
+        legacyPath: await forwardTarget(legacyPath, record),
+        forwardedFrom: legacyPath,
+    };
 }
 export async function resolvePublishedAccountStorePaths(legacyPath) {
     const pointer = await readPointer(legacyPath);
@@ -354,7 +434,9 @@ export function decodeAccountStoreGeneration(value) {
     ], 'generation');
     if (raw.schemaVersion !== 1 ||
         typeof raw.legacyPath !== 'string' ||
-        (raw.sourceKind !== 'file' && raw.sourceKind !== 'absent'))
+        (raw.sourceKind !== 'file' &&
+            raw.sourceKind !== 'absent' &&
+            raw.sourceKind !== 'generation'))
         throw new AccountMigrationError('generation schema is invalid');
     const id = text(raw.id, UUID, 'generation id');
     const paths = generationPaths(raw.legacyPath, id);
@@ -462,6 +544,7 @@ export function decodeAccountMigrationJournal(value) {
         'retiredSha256',
         'rollback',
         'cancelled',
+        'relocation',
     ], 'journal');
     if (raw.schemaVersion !== 1)
         throw new AccountMigrationError('unsupported journal schema');
@@ -481,12 +564,16 @@ export function decodeAccountMigrationJournal(value) {
     if (phase === undefined)
         throw new AccountMigrationError('journal phase is invalid');
     const sourceKind = raw.sourceKind;
-    if (sourceKind !== 'file' && sourceKind !== 'absent')
+    if (sourceKind !== 'file' &&
+        sourceKind !== 'absent' &&
+        sourceKind !== 'generation')
         throw new AccountMigrationError('journal source kind is invalid');
-    const sourceSha256 = sourceKind === 'file'
+    // A moved store keeps the same two hashes as a pool-file source: its
+    // snapshot of the old generation's files and its capture file.
+    const sourceSha256 = sourceKind !== 'absent'
         ? text(raw.sourceSha256, SHA256, 'journal.sourceSha256')
         : undefined;
-    const captureSha256 = sourceKind === 'file'
+    const captureSha256 = sourceKind !== 'absent'
         ? text(raw.captureSha256, SHA256, 'journal.captureSha256')
         : undefined;
     if (sourceKind === 'absent' && Object.hasOwn(raw, 'captureSha256'))
@@ -511,7 +598,7 @@ export function decodeAccountMigrationJournal(value) {
         sourceVersion !== 4)
         throw new AccountMigrationError('manifest source version is invalid');
     if ((sourceKind === 'file' && sourceVersion === null) ||
-        (sourceKind === 'absent' && sourceVersion !== null))
+        (sourceKind !== 'file' && sourceVersion !== null))
         throw new AccountMigrationError('manifest version differs from source kind');
     if (!finite(m.normalizationClock) || !finite(m.effectiveActiveIndex))
         throw new AccountMigrationError('manifest clock or cursor is invalid');
@@ -549,6 +636,15 @@ export function decodeAccountMigrationJournal(value) {
             }) ||
             manifest.effectiveActiveIndex !== 0))
         throw new AccountMigrationError('absent-source manifest must be explicitly empty with no invented cursors');
+    // A move copies the store's own files; its journal carries no rows and so
+    // no refresh token. The moved rows are listed in `relocation.rows`.
+    if (sourceKind === 'generation' &&
+        (accounts.length ||
+            !isDeepStrictEqual(encodeRoutingSettings(manifest.routing), {
+                schemaVersion: 1,
+            }) ||
+            manifest.effectiveActiveIndex !== 0))
+        throw new AccountMigrationError('moved-store manifest must be explicitly empty');
     const effective = accounts.length
         ? Math.max(0, Math.min(manifest.routing.activeIndex ?? 0, accounts.length - 1))
         : 0;
@@ -606,6 +702,33 @@ export function decodeAccountMigrationJournal(value) {
         throw new AccountMigrationError('absent source cannot claim retired bytes');
     if (retiredSha256 !== undefined && retiredSha256 !== sourceSha256)
         throw new AccountMigrationError('retired bytes are not associated with source');
+    const relocation = decodeRelocation(raw, sourceKind, paths.legacyPath);
+    if (sourceKind === 'generation') {
+        // The moved store's retirement is the forward at the old anchor, not a
+        // retired pool-file copy or a checked absence.
+        if (retiredSha256 !== undefined)
+            throw new AccountMigrationError('moved source cannot claim retired pool-file bytes');
+        if (relocation === undefined)
+            throw new AccountMigrationError('moved source lacks its relocation evidence');
+        if (operation === 'rollback')
+            throw new AccountMigrationError('a moved account store is not rolled back; move it back first with `antigravity-auth store relocate --back --offline`');
+        if (relocation.sourceForwarded && !relocation.sourceTombstoned)
+            throw new AccountMigrationError('source forward precedes its management tombstone');
+        if ((relocation.sourceTombstoned || relocation.sourceForwarded) &&
+            (!verification || (phase !== 'retire' && phase !== 'activate')))
+            throw new AccountMigrationError('source tombstone or forward precedes durable verification');
+        if (status === 'active' && !relocation.sourceForwarded)
+            throw new AccountMigrationError('active moved store lacks its source forward');
+        if (phase === 'activate' && !relocation.sourceForwarded)
+            throw new AccountMigrationError('moved-store activation lacks its source forward');
+    }
+    // What retired the source: the retired pool-file copy, the checked
+    // absence of a pool file, or the forward that replaced the old pointer.
+    const retirementRecorded = sourceKind === 'file'
+        ? retiredSha256 !== undefined
+        : sourceKind === 'absent'
+            ? raw.sourceAbsenceVerified === true
+            : relocation?.sourceForwarded === true;
     let rollback;
     if (Object.hasOwn(raw, 'rollback')) {
         const r = exact(raw.rollback, ['id', 'snapshotSha256', 'exportSha256', 'rows', 'successorInactive'], 'rollback');
@@ -643,18 +766,12 @@ export function decodeAccountMigrationJournal(value) {
         (retiredSha256 !== undefined || raw.sourceAbsenceVerified === true) &&
         (!verification || (phase !== 'retire' && phase !== 'activate')))
         throw new AccountMigrationError('retirement association precedes durable verification');
-    if (operation === 'migrate' &&
-        phase === 'activate' &&
-        (sourceKind === 'file'
-            ? retiredSha256 === undefined
-            : raw.sourceAbsenceVerified !== true))
+    if (operation === 'migrate' && phase === 'activate' && !retirementRecorded)
         throw new AccountMigrationError('activation lacks its actual source retirement association');
     if (status === 'active' &&
         (operation !== 'migrate' ||
             phase !== 'activate' ||
-            (sourceKind === 'file'
-                ? retiredSha256 === undefined
-                : raw.sourceAbsenceVerified !== true) ||
+            !retirementRecorded ||
             rollback !== undefined ||
             cancelled))
         throw new AccountMigrationError('active receipt is incomplete');
@@ -662,10 +779,7 @@ export function decodeAccountMigrationJournal(value) {
         throw new AccountMigrationError('rollback lacks its current-credential snapshot');
     if (operation === 'rollback' &&
         !cancelled &&
-        (verification === undefined ||
-            (sourceKind === 'file'
-                ? retiredSha256 === undefined
-                : raw.sourceAbsenceVerified !== true)))
+        (verification === undefined || !retirementRecorded))
         throw new AccountMigrationError('rollback lacks the original verified retirement');
     if (status === 'inactive' &&
         !cancelled &&
@@ -697,6 +811,56 @@ export function decodeAccountMigrationJournal(value) {
         ...(retiredSha256 === undefined ? {} : { retiredSha256 }),
         ...(rollback === undefined ? {} : { rollback }),
         ...(cancelled ? { cancelled: true } : {}),
+        ...(relocation === undefined ? {} : { relocation }),
+    };
+}
+/** Decodes `relocation`, which only a moved store's journal may carry. */
+function decodeRelocation(raw, sourceKind, legacyPath) {
+    if (!Object.hasOwn(raw, 'relocation'))
+        return undefined;
+    if (sourceKind !== 'generation')
+        throw new AccountMigrationError('only a moved store records relocation evidence');
+    const r = exact(raw.relocation, ['source', 'rows', 'sourceTombstoned', 'sourceForwarded'], 'relocation');
+    const s = exact(r.source, [
+        'legacyPath',
+        'storeDir',
+        'journalId',
+        'configSha256',
+        'stateSha256',
+        'statePresent',
+    ], 'relocation source');
+    if (typeof s.legacyPath !== 'string')
+        throw new AccountMigrationError('relocation source path is invalid');
+    const journalId = text(s.journalId, UUID, 'relocation source journal');
+    const source = generationPaths(s.legacyPath, journalId);
+    if (s.storeDir !== source.storeDir)
+        throw new AccountMigrationError('relocation source association differs');
+    if (sameFilesystemPath(source.legacyPath, legacyPath))
+        throw new AccountMigrationError('relocation source and target share one anchor');
+    if (typeof s.statePresent !== 'boolean')
+        throw new AccountMigrationError('relocation state presence is invalid');
+    if (!s.statePresent && Object.hasOwn(s, 'stateSha256'))
+        throw new AccountMigrationError('absent source state cannot claim a file hash');
+    const rows = list(r.rows, 'relocation rows').map((id) => text(id, UUID, 'relocation row id'));
+    if (new Set(rows).size !== rows.length)
+        throw new AccountMigrationError('relocation rows are duplicated');
+    if (typeof r.sourceTombstoned !== 'boolean' ||
+        typeof r.sourceForwarded !== 'boolean')
+        throw new AccountMigrationError('relocation progress flags are invalid');
+    return {
+        source: {
+            legacyPath: source.legacyPath,
+            storeDir: source.storeDir,
+            journalId,
+            configSha256: text(s.configSha256, SHA256, 'relocation config hash'),
+            ...(s.statePresent
+                ? { stateSha256: text(s.stateSha256, SHA256, 'relocation state hash') }
+                : {}),
+            statePresent: s.statePresent,
+        },
+        rows,
+        sourceTombstoned: r.sourceTombstoned,
+        sourceForwarded: r.sourceForwarded,
     };
 }
 function pendingLockFailure(modules, error) {
@@ -1046,6 +1210,8 @@ async function verifyCopies(paths, journal, retired) {
     if (digest(capture) !== journal.captureSha256 ||
         !isDeepStrictEqual(jsonBytes(capture), captureJson(journal)))
         throw new AccountMigrationError('journal differs from its exclusive capture snapshot');
+    if (journal.sourceKind === 'generation')
+        return verifyRelocationSnapshot(backup, journal);
     // Original backup JSON and the captured time reproduce the expected import.
     // Compare that value with the journal without changing its selected rows, clock,
     // source positions or UUID mapping.
@@ -1068,8 +1234,67 @@ function captureJson(journal) {
         sourceSha256: journal.sourceSha256,
         manifest: manifestJson(journal.manifest),
         mapping: journal.mapping,
+        ...(journal.relocation === undefined
+            ? {}
+            : { relocation: { source: journal.relocation.source } }),
+    };
+}
+function base64Bytes(value, path) {
+    if (typeof value !== 'string')
+        throw new AccountMigrationError(`${path} is invalid`);
+    const bytes = Buffer.from(value, 'base64');
+    // Only canonical base64 round-trips; anything else could hide extra bytes.
+    if (bytes.toString('base64') !== value)
+        throw new AccountMigrationError(`${path} is not canonical base64`);
+    return bytes;
+}
+export function decodeRelocationSnapshot(value) {
+    const raw = exact(value, ['config', 'state', 'journal'], 'moved snapshot');
+    return {
+        config: base64Bytes(raw.config, 'moved snapshot config'),
+        ...(Object.hasOwn(raw, 'state')
+            ? { state: base64Bytes(raw.state, 'moved snapshot state') }
+            : {}),
+        journal: base64Bytes(raw.journal, 'moved snapshot journal'),
     };
 }
+/**
+ * Ties a moved store's source snapshot to its journal: the copied files hash
+ * to `relocation.source`, the copied journal is the active source generation
+ * it names, and the copied config carries that generation's own settings
+ * key. The live old generation is not compared: it gains a management
+ * tombstone after the copy, and it is no longer served.
+ *
+ * Binding a copy at another anchor is sound because the store's files hold
+ * no location. The common-auth "Store portability" contract (common-auth
+ * `docs/adoption-inventory.md` at 672f6265, pinned by its
+ * `test/store/store-portability.test.ts`) states that `config.json` and
+ * `state.json` record no path, folder or file identity, or host identity,
+ * and that a byte copy of both taken under the store's save locks opens
+ * elsewhere as the same pool. Lock and sidecar files are not part of that
+ * contract, and neither is any in-memory state kept by the process that
+ * opened the old files; nothing here relies on either.
+ */
+function verifyRelocationSnapshot(backup, journal) {
+    const source = journal.relocation?.source;
+    if (source === undefined)
+        throw new AccountMigrationError('moved source lacks its relocation evidence');
+    const snapshot = decodeRelocationSnapshot(jsonBytes(backup));
+    if (digest(snapshot.config) !== source.configSha256 ||
+        (snapshot.state !== undefined) !== source.statePresent ||
+        (snapshot.state !== undefined &&
+            digest(snapshot.state) !== source.stateSha256))
+        throw new AccountMigrationError('moved source snapshot differs from its recorded hashes');
+    const copied = decodeAccountMigrationJournal(jsonBytes(snapshot.journal));
+    if (copied.id !== source.journalId ||
+        copied.legacyPath !== source.legacyPath ||
+        copied.storeDir !== source.storeDir ||
+        copied.status !== 'active')
+        throw new AccountMigrationError('moved source snapshot is not the active source generation');
+    const config = object(jsonBytes(snapshot.config), 'moved source config');
+    if (!isDeepStrictEqual(decodeAccountStoreGeneration(config[ACCOUNT_STORE_GENERATION_SETTINGS_KEY]), generationJson(copied)))
+        throw new AccountMigrationError('moved source snapshot belongs to another generation');
+}
 async function synchronizedSnapshot(paths, boundary) {
     await syncFile(paths.configPath);
     const statePresent = await exists(paths.statePath);
@@ -1153,7 +1378,7 @@ function receipt(journal) {
         storeDir: journal.storeDir,
         sourceKind: journal.sourceKind,
         durability: journal.verification?.durability ?? accountMigrationDurability(),
-        restartRequired: journal.sourceKind === 'file' || journal.operation === 'rollback',
+        restartRequired: journal.sourceKind !== 'absent' || journal.operation === 'rollback',
     };
 }
 async function currentSuccessor(store, paths, journal) {
@@ -1246,40 +1471,15 @@ async function trustedCurrentGeneration(store, paths, journal) {
 /** A bound result establishes completed-generation ownership for repository recovery, not readiness to select or route credentials. */
 export async function readAccountStoreBinding(legacyPath, modules, now, expectedGeneration) {
     try {
-        const paths = await resolvePublishedAccountStorePaths(legacyPath);
-        if (!paths)
-            return (await exists(legacyPath))
-                ? { status: 'pending' }
-                : { status: 'initialization-required' };
-        const journal = await readJournal(paths);
-        if (!journal)
-            throw new AccountMigrationError('published binding journal missing');
-        if (expectedGeneration !== undefined && journal.id !== expectedGeneration)
-            throw new AccountMigrationError('bound repository generation differs from pointer');
-        if (journal.status === 'pending')
-            return {
-                status: 'pending',
-                phase: journal.phase,
-                operation: journal.operation,
-            };
-        if (journal.status === 'inactive')
-            return { status: 'inactive', id: journal.id };
-        if (await exists(legacyPath))
-            throw new AccountMigrationError('legacy source was recreated after activation');
-        await verifyCopies(paths, journal, true);
-        const settings = await trustedCurrentGeneration(openAdmissionStore(modules, paths, now), paths, journal);
-        const pending = settings[MANAGEMENT_SETTINGS_KEY];
-        if (pending !== undefined) {
-            const record = object(pending, 'repository management');
-            if (record.kind === 'migration')
-                return { status: 'pending', phase: 'activate', operation: 'migrate' };
-            if (record.kind !== 'clear' && record.kind !== 'replace-pool')
-                throw new AccountMigrationError('unknown management owner prevents binding');
-            // Ownership permits opening these physical paths. The repository must then
-            // validate and resume its own strict clear/replace journal; this binding
-            // neither validates that operation nor grants credential-serving readiness.
+        // A forward at this anchor leads one step to the anchor the store moved
+        // to; the bound paths are then the moved generation's own.
+        const record = await readPointerRecord(legacyPath);
+        if (record?.schemaVersion === 2) {
+            if (await exists(legacyPath))
+                throw new AccountMigrationError(`a pool file reappeared at ${legacyPath} after the account store moved to ${record.relocatedTo.legacyPath}`);
+            return await bindPublishedGeneration(await forwardTarget(legacyPath, record), modules, now, expectedGeneration, legacyPath);
         }
-        return { status: 'bound', receipt: receipt(journal), paths };
+        return await bindPublishedGeneration(legacyPath, modules, now, expectedGeneration);
     }
     catch (error) {
         return {
@@ -1290,6 +1490,84 @@ export async function readAccountStoreBinding(legacyPath, modules, now, expected
         };
     }
 }
+/**
+ * A moved generation binds only while the old anchor still forwards to
+ * exactly it. A pointer set back to schema 1 there, a missing forward, or a
+ * forward to another generation refuses: either store could then be the
+ * one a build writes to, and neither is chosen by age.
+ */
+async function assertSourceForwarded(journal, forwardedFrom) {
+    const source = journal.relocation?.source;
+    if (source === undefined)
+        throw new AccountMigrationError('moved source lacks its relocation evidence');
+    const pointer = accountStorePointerPath(source.legacyPath);
+    if (forwardedFrom !== undefined && forwardedFrom !== source.legacyPath)
+        throw new AccountMigrationError(`the forwarding pointer ${accountStorePointerPath(forwardedFrom)} leads to a store moved from ${source.legacyPath}`);
+    if (await exists(source.legacyPath))
+        throw new AccountMigrationError(`a pool file reappeared at ${source.legacyPath} after the account store moved to ${journal.legacyPath}`);
+    const record = await readPointerRecord(source.legacyPath);
+    if (record === undefined)
+        throw new AccountMigrationError(`the forwarding pointer ${pointer} to the moved account store at ${journal.storeDir} is missing; restore it`);
+    if (record.schemaVersion === 1)
+        throw new AccountMigrationError(`the account store in ${dirname(source.legacyPath)} was reactivated: ${pointer} publishes generation ${record.id} while the moved store at ${journal.storeDir} is active; restore the forwarding pointer, or run \`antigravity-auth store relocate\``);
+    if (record.id !== source.journalId ||
+        record.relocatedTo.legacyPath !== journal.legacyPath ||
+        record.relocatedTo.id !== journal.id)
+        throw new AccountMigrationError(`the forwarding pointer ${pointer} names another store than the moved account store at ${journal.storeDir}`);
+}
+async function bindPublishedGeneration(legacyPath, modules, now, expectedGeneration, forwardedFrom) {
+    const paths = await resolvePublishedAccountStorePaths(legacyPath);
+    if (!paths) {
+        if (forwardedFrom !== undefined)
+            throw new AccountMigrationError('forwarded anchor publishes no generation');
+        return (await exists(legacyPath))
+            ? { status: 'pending' }
+            : { status: 'initialization-required' };
+    }
+    const journal = await readJournal(paths);
+    if (!journal)
+        throw new AccountMigrationError('published binding journal missing');
+    if (expectedGeneration !== undefined && journal.id !== expectedGeneration)
+        throw new AccountMigrationError('bound repository generation differs from pointer');
+    if (forwardedFrom !== undefined && journal.sourceKind !== 'generation')
+        throw new AccountMigrationError(`the forwarding pointer ${accountStorePointerPath(forwardedFrom)} leads to a store that was not moved there`);
+    // An unfinished move is finished by the build that started it; this build
+    // neither resumes it nor serves either store meanwhile.
+    if (journal.sourceKind === 'generation' && journal.status === 'pending')
+        throw new AccountMigrationError(`a move of the account store to ${journal.storeDir} is unfinished; finish it with the version that started it`);
+    if (journal.status === 'pending')
+        return {
+            status: 'pending',
+            phase: journal.phase,
+            operation: journal.operation,
+        };
+    if (journal.status === 'inactive')
+        return { status: 'inactive', id: journal.id };
+    if (await exists(legacyPath))
+        throw new AccountMigrationError('legacy source was recreated after activation');
+    await verifyCopies(paths, journal, true);
+    if (journal.sourceKind === 'generation')
+        await assertSourceForwarded(journal, forwardedFrom);
+    const settings = await trustedCurrentGeneration(openAdmissionStore(modules, paths, now), paths, journal);
+    const pending = settings[MANAGEMENT_SETTINGS_KEY];
+    if (pending !== undefined) {
+        const record = object(pending, 'repository management');
+        // Only a store move writes a migration record owned by another
+        // generation: it blocks the old generation once the copy is taken.
+        // Reaching it here means this anchor's pointer was set back from the
+        // forward to the old generation.
+        if (record.kind === 'migration' && record.id !== journal.id)
+            throw new AccountMigrationError(`the account store at ${paths.storeDir} was moved to generation ${String(record.id)}, but ${accountStorePointerPath(legacyPath)} publishes the old store again; restore the forwarding pointer, or run \`antigravity-auth store relocate\``);
+        if (record.kind === 'migration')
+            return { status: 'pending', phase: 'activate', operation: 'migrate' };
+        if (record.kind !== 'clear' && record.kind !== 'replace-pool')
+            throw new AccountMigrationError('unknown management owner prevents binding');
+        // Ownership permits opening these physical paths. The repository must then
+        // validate and resume its own strict clear/replace journal; this binding
+        // neither validates that operation nor grants credential-serving readiness.
+    }
+    return { status: 'bound', receipt: receipt(journal), paths };
+}
 /** Serving requires healthy current rows and no repository management work. Binding alone is insufficient. */
 export async function readAccountStoreAdmission(legacyPath, modules, now, expectedGeneration) {
     const binding = await readAccountStoreBinding(legacyPath, modules, now, expectedGeneration);
@@ -1623,6 +1901,8 @@ export function createAccountMigrationFactory(modules) {
                     const existing = await readJournal(paths);
                     if (!existing)
                         throw new AccountMigrationError('published generation journal missing');
+                    if (existing.sourceKind === 'generation')
+                        throw new AccountMigrationError('a moved account store is finished by `antigravity-auth store relocate`, not by migrate');
                     if (existing.status === 'inactive') {
                         previous = existing;
                         await modules.fs.withLock(paths.configPath, {
@@ -1812,6 +2092,11 @@ export function createAccountRollbackFactory(modules) {
             throw new AccountMigrationError('stopped processes and timers must be explicitly confirmed');
         try {
             return await withParentTopology(modules, options.legacyPath, async () => {
+                // A moved store is rolled back from its pool file only after it was
+                // moved back to this anchor; this build never does either.
+                const record = await readPointerRecord(options.legacyPath);
+                if (record?.schemaVersion === 2)
+                    throw new AccountMigrationError(`the account store moved to ${record.relocatedTo.legacyPath}; move it back with \`antigravity-auth store relocate --back --offline\` before rolling it back`);
                 const paths = await resolvePublishedAccountStorePaths(options.legacyPath);
                 if (!paths)
                     throw new AccountMigrationError('rollback requires a published generation');
@@ -1824,6 +2109,8 @@ export function createAccountRollbackFactory(modules) {
                     const initialJournal = await readJournal(paths);
                     if (!initialJournal)
                         throw new AccountMigrationError('rollback requires an owned migration generation');
+                    if (initialJournal.sourceKind === 'generation')
+                        throw new AccountMigrationError(`this account store was moved here from ${initialJournal.relocation?.source.legacyPath}; move it back with \`antigravity-auth store relocate --back --offline\` before rolling it back`);
                     let journal = initialJournal;
                     const store = openMigrationStore(modules, paths, options.now, writeObserver(paths, lease, options.onBoundary));
                     if (journal.status === 'inactive') {