@lesliechan721/aw 0.1.0-beta.8 → 0.1.0-beta.9

package/dist/src/commands/catalog-dev-source.js

@@ -1,24 +1,22 @@
 import crypto from 'node:crypto';
 import path from 'node:path';
-import { DEFAULT_CATALOG_OUTPUT_PATH, readCatalogWorkspace, resolveCatalogWorkspaceRoot, validateCatalogSnapshotComplete, } from '@lesliechan721/aw-plugin-core';
+import { DEFAULT_CATALOG_OUTPUT_PATH, readCatalogWorkspace, validateCatalogSnapshotComplete, } from '@lesliechan721/aw-plugin-core';
 import { runCatalogBuildCommand } from '../authoring/workspace-commands.js';
-import { withAwHomeMutationLock } from '../utils/aw-home-mutation-lock.js';
-import { calculateCatalogSourceIdentity } from '../utils/catalog-source-identity.js';
-import { catalogSourceCacheInternal } from '../utils/catalog-source-cache.js';
+import { readCatalogGenerationStatus } from '../utils/catalog-generation-service.js';
 import { CLI_RESERVED_IMPORTS } from '../utils/manifest.js';
 import { CATALOG_SOURCE_ID_PATTERN, isDefaultOfficialCatalogSource, readCatalogSourcesConfigSnapshot, } from '../utils/catalog-sources.js';
-import { addCatalogSourceCommand, refreshCatalogSourceCommand, removeCatalogSourceCommand, setPrimaryCatalogSourceCommand, updateCatalogSourceCommand, } from './catalog-source.js';
+import { addCatalogSourceCommand, removeCatalogSourceCommand, setPrimaryCatalogSourceCommand, updateCatalogSourceCommand, } from './catalog-source.js';
+import { syncCatalogSourceCommand } from './catalog-generation.js';
 import { getCatalogStatus } from './catalog-status.js';
+import { resolveCatalogWorkspaceRoot } from './catalog-workspace-resolution.js';
 function managedSources(sources, workspaceIdentity) {
     return sources.filter((source) => source.type === 'path'
         && source.managedBy?.kind === 'catalog-workspace'
         && source.managedBy.workspaceIdentity === workspaceIdentity);
 }
 function normalizeSuggestedSourceId(workspaceRoot) {
-    const stem = path.basename(workspaceRoot)
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/gu, '-')
-        .replace(/^-+|-+$/gu, '');
+    const stem = path.basename(workspaceRoot).toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '-').replace(/^-+|-+$/gu, '');
     const prefixed = /^[a-z]/u.test(stem) ? stem : `catalog-${stem}`;
     const basename = (prefixed || 'catalog').slice(0, 28).replace(/-+$/u, '') || 'catalog';
     return `${basename}-dev`;
@@ -34,11 +32,6 @@ export function suggestedCatalogDevSourceId(workspaceRoot, workspaceIdentity, oc
         ? suffixedSourceId(base, workspaceIdentity)
         : base;
 }
-function assertExplicitSourceId(sourceId) {
-    if (!CATALOG_SOURCE_ID_PATTERN.test(sourceId)) {
-        throw new CatalogDevSourceError('invalidSourceId', `Invalid catalog development source ID: expected ${CATALOG_SOURCE_ID_PATTERN}.`);
-    }
-}
 class CatalogDevSourceError extends Error {
     code;
     constructor(code, message) {
@@ -47,46 +40,37 @@ class CatalogDevSourceError extends Error {
         this.name = 'CatalogDevSourceError';
     }
 }
+function assertExplicitSourceId(sourceId) {
+    if (!CATALOG_SOURCE_ID_PATTERN.test(sourceId)) {
+        throw new CatalogDevSourceError('invalidSourceId', 'Invalid Catalog development source ID.');
+    }
+}
 export function createCatalogDevFailureReceipt(options) {
     const workspaceRoot = path.resolve(options.cwd, options.workspaceRoot ?? '.');
-    const snapshotPath = path.join(workspaceRoot, DEFAULT_CATALOG_OUTPUT_PATH);
     if (options.command === 'activate') {
         return {
-            receiptSchemaVersion: 1,
-            command: 'catalog:dev:activate',
-            ok: false,
-            state: 'completed',
+            receiptSchemaVersion: 2, command: 'catalog:dev:activate', ok: false, state: 'failed',
             workspaceIdentity: null,
-            snapshot: { path: snapshotPath, action: 'reused', digest: null },
-            source: {
-                id: options.sourceId ?? suggestedCatalogDevSourceId(workspaceRoot),
-                action: 'reused',
-                primary: false,
-            },
+            snapshot: { action: 'reused', digest: null },
+            source: { id: options.sourceId ?? suggestedCatalogDevSourceId(workspaceRoot), action: 'reused', primary: false },
+            active: { ready: false, snapshotDigest: null },
             recovery: ['Fix the reported problem, then rerun catalog dev activate.'],
             errors: [{ code: options.code, message: options.message }],
         };
     }
     if (options.command === 'status') {
         return {
-            receiptSchemaVersion: 1,
-            command: 'catalog:dev:status',
-            ok: false,
+            receiptSchemaVersion: 3, command: 'catalog:dev:status', ok: false, ready: false,
             workspaceIdentity: null,
-            workspaceRoot,
-            snapshot: { path: snapshotPath, state: 'absent', valid: false, digest: null },
+            snapshot: { state: 'absent', valid: false, digest: null },
             source: { exists: false, id: null, pathMatches: null, primary: null },
-            cache: { state: 'not-applicable', validatedAt: null, snapshotDigest: null },
+            active: { exists: false, ready: false, digestMatchesSnapshot: false, snapshotDigest: null },
             issues: [{ code: options.code, message: options.message, blocking: true }],
         };
     }
     return {
-        receiptSchemaVersion: 1,
-        command: 'catalog:dev:deactivate',
-        ok: false,
-        state: 'completed',
+        receiptSchemaVersion: 2, command: 'catalog:dev:deactivate', ok: false, state: 'failed',
         workspaceIdentity: null,
-        snapshotPath,
         source: { id: null, action: 'absent', previousPrimary: false },
         replacementPrimarySourceId: null,
         recovery: ['Fix the reported problem, then rerun catalog dev deactivate.'],
@@ -96,7 +80,7 @@ export function createCatalogDevFailureReceipt(options) {
 function codedFailure(error, fallbackCode) {
     return {
         code: error instanceof CatalogDevSourceError ? error.code : fallbackCode,
-        message: error instanceof Error ? error.message : String(error),
+        message: error instanceof CatalogDevSourceError ? error.message : 'The Catalog development operation failed.',
     };
 }
 async function resolveWorkspace(cwd, workspaceRoot) {
@@ -109,8 +93,8 @@ async function resolveWorkspace(cwd, workspaceRoot) {
         const workspace = await readCatalogWorkspace(resolved.workspaceRoot, { reservedImports: CLI_RESERVED_IMPORTS });
         return { resolved, workspace };
     }
-    catch (error) {
-        throw new CatalogDevSourceError('workspaceInvalid', error instanceof Error ? error.message : String(error));
+    catch {
+        throw new CatalogDevSourceError('workspaceInvalid', 'Catalog Workspace is missing or invalid.');
     }
 }
 export function catalogDevSourceError(error, fallbackCode = 'catalogDevSourceFailed') {
@@ -120,14 +104,11 @@ export async function activateCatalogDevSource(options) {
     const { resolved, workspace } = await resolveWorkspace(options.cwd, options.workspaceRoot);
     const snapshotPath = path.join(workspace.workspaceRoot, DEFAULT_CATALOG_OUTPUT_PATH);
     const staticStatus = await getCatalogStatus({
-        cwd: options.cwd,
-        workspaceRoot: workspace.workspaceRoot,
-        env: options.env,
+        cwd: options.cwd, workspaceRoot: workspace.workspaceRoot, env: options.env,
     });
     let snapshotAction = 'reused';
     let snapshotDigest = staticStatus.snapshot.snapshotDigest;
-    const shouldBuild = options.forceBuild === true || staticStatus.snapshot.state !== 'current';
-    if (shouldBuild) {
+    if (options.forceBuild === true || staticStatus.snapshot.state !== 'current') {
         try {
             await runCatalogBuildCommand({
                 workspaceRoot: workspace.workspaceRoot,
@@ -140,152 +121,111 @@ export async function activateCatalogDevSource(options) {
         }
         catch (error) {
             return {
-                receiptSchemaVersion: 1,
-                command: 'catalog:dev:activate',
-                ok: false,
-                state: 'completed',
+                receiptSchemaVersion: 2, command: 'catalog:dev:activate', ok: false, state: 'failed',
                 workspaceIdentity: workspace.workspaceIdentity,
-                snapshot: { path: snapshotPath, action: 'built', digest: null },
+                snapshot: { action: 'built', digest: null },
                 source: { id: options.sourceId ?? normalizeSuggestedSourceId(workspace.workspaceRoot), action: 'reused', primary: false },
-                recovery: ['Fix the Catalog Workspace or snapshot output, then rerun catalog dev activate.'],
+                active: { ready: false, snapshotDigest: null },
+                recovery: ['Fix the Catalog Workspace, then rerun catalog dev activate.'],
                 errors: [codedFailure(error, 'snapshotBuildFailed')],
             };
         }
     }
     let selectedId = options.sourceId ?? normalizeSuggestedSourceId(workspace.workspaceRoot);
     let sourceAction = 'reused';
+    let sourceCommitted = false;
     try {
-        const result = await withAwHomeMutationLock({
-            env: options.env,
-            action: async (awHomeMutationToken) => {
-                const configSnapshot = await readCatalogSourcesConfigSnapshot(options.env);
-                const owned = managedSources(configSnapshot.config.sources, workspace.workspaceIdentity);
-                if (owned.length > 1) {
-                    throw new CatalogDevSourceError('multipleManagedSources', `Catalog Workspace identity ${workspace.workspaceIdentity} owns multiple development sources: ${owned.map((source) => source.id).join(', ')}.`);
-                }
-                const existing = owned[0];
-                selectedId = options.sourceId ?? normalizeSuggestedSourceId(workspace.workspaceRoot);
-                if (options.sourceId !== undefined) {
-                    assertExplicitSourceId(options.sourceId);
-                    if (existing && existing.id !== options.sourceId) {
-                        throw new CatalogDevSourceError('sourceIdConflict', `Catalog Workspace already owns development source "${existing.id}"; it cannot also own "${options.sourceId}".`);
-                    }
-                    const collision = configSnapshot.config.sources.find((source) => source.id === options.sourceId);
-                    if (collision && collision !== existing) {
-                        throw new CatalogDevSourceError('sourceIdConflict', `Catalog source "${options.sourceId}" is owned by another Workspace or is foreign.`);
-                    }
-                }
-                else if (!existing && configSnapshot.config.sources.some((source) => source.id === selectedId)) {
-                    selectedId = suffixedSourceId(selectedId, workspace.workspaceIdentity);
-                    if (configSnapshot.config.sources.some((source) => source.id === selectedId)) {
-                        throw new CatalogDevSourceError('sourceIdConflict', `Deterministic Catalog development source ID "${selectedId}" is already in use.`);
-                    }
-                }
-                if (existing)
-                    selectedId = existing.id;
-                const runtime = { ...options.runtime?.sourceRuntime, awHomeMutationToken };
-                if (!existing) {
-                    sourceAction = 'added';
-                    return addCatalogSourceCommand({
-                        source: {
-                            id: selectedId,
-                            type: 'path',
-                            path: snapshotPath,
-                            primary: options.primary === true,
-                            managedBy: { kind: 'catalog-workspace', workspaceIdentity: workspace.workspaceIdentity },
-                        },
-                        cliVersion: options.cliVersion,
-                        cwd: workspace.workspaceRoot,
-                        env: options.env,
-                        runtime,
-                        managedByWorkspaceIdentity: workspace.workspaceIdentity,
-                    });
-                }
-                if (existing.path !== snapshotPath || (options.primary === true && !existing.primary)) {
-                    sourceAction = 'updated';
-                    const updated = existing.path === snapshotPath
-                        ? { errors: [] }
-                        : await updateCatalogSourceCommand({
-                            sourceId: existing.id,
-                            update: { type: 'path', path: snapshotPath },
-                            cliVersion: options.cliVersion,
-                            cwd: workspace.workspaceRoot,
-                            env: options.env,
-                            runtime,
-                            managedByWorkspaceIdentity: workspace.workspaceIdentity,
-                        });
-                    if (options.primary === true && !existing.primary) {
-                        await setPrimaryCatalogSourceCommand({
-                            sourceId: existing.id,
-                            cwd: workspace.workspaceRoot,
-                            env: options.env,
-                            runtime,
-                        });
-                    }
-                    if (existing.path !== snapshotPath)
-                        return updated;
-                    const refreshed = await refreshCatalogSourceCommand({
-                        sourceId: existing.id,
-                        cliVersion: options.cliVersion,
-                        env: options.env,
-                        runtime,
-                    });
-                    return { errors: refreshed.errors };
-                }
-                const refreshed = await refreshCatalogSourceCommand({
-                    sourceId: existing.id,
-                    cliVersion: options.cliVersion,
-                    env: options.env,
-                    runtime,
-                });
-                return { errors: refreshed.errors };
-            },
+        const configSnapshot = await readCatalogSourcesConfigSnapshot(options.env);
+        const owned = managedSources(configSnapshot.config.sources, workspace.workspaceIdentity);
+        if (owned.length > 1) {
+            throw new CatalogDevSourceError('multipleManagedSources', 'Workspace owns multiple development sources.');
+        }
+        const existing = owned[0];
+        if (options.sourceId !== undefined) {
+            assertExplicitSourceId(options.sourceId);
+            if (existing && existing.id !== options.sourceId) {
+                throw new CatalogDevSourceError('sourceIdConflict', 'Workspace already owns another development source.');
+            }
+            const collision = configSnapshot.config.sources.find((source) => source.id === options.sourceId);
+            if (collision && collision !== existing) {
+                throw new CatalogDevSourceError('sourceIdConflict', 'The selected source ID is already in use.');
+            }
+        }
+        else if (!existing && configSnapshot.config.sources.some((source) => source.id === selectedId)) {
+            selectedId = suffixedSourceId(selectedId, workspace.workspaceIdentity);
+            if (configSnapshot.config.sources.some((source) => source.id === selectedId)) {
+                throw new CatalogDevSourceError('sourceIdConflict', 'The generated development source ID is already in use.');
+            }
+        }
+        if (existing)
+            selectedId = existing.id;
+        if (!existing) {
+            sourceAction = 'added';
+            await addCatalogSourceCommand({
+                source: {
+                    id: selectedId, type: 'path', path: snapshotPath, primary: false,
+                    managedBy: { kind: 'catalog-workspace', workspaceIdentity: workspace.workspaceIdentity },
+                },
+                cliVersion: options.cliVersion, cwd: workspace.workspaceRoot, env: options.env,
+                runtime: options.runtime?.sourceRuntime,
+                managedByWorkspaceIdentity: workspace.workspaceIdentity,
+            });
+            sourceCommitted = true;
+        }
+        else if (existing.path !== snapshotPath) {
+            sourceAction = 'updated';
+            await updateCatalogSourceCommand({
+                sourceId: existing.id, update: { type: 'path', path: snapshotPath },
+                cliVersion: options.cliVersion, cwd: workspace.workspaceRoot, env: options.env,
+                runtime: options.runtime?.sourceRuntime,
+                managedByWorkspaceIdentity: workspace.workspaceIdentity,
+            });
+            sourceCommitted = true;
+        }
+        const current = (await readCatalogSourcesConfigSnapshot(options.env)).config.sources
+            .find((source) => source.id === selectedId);
+        if (options.primary === true && !current.primary) {
+            await setPrimaryCatalogSourceCommand({
+                sourceId: selectedId, cwd: workspace.workspaceRoot, env: options.env,
+                runtime: options.runtime?.sourceRuntime,
+            });
+            sourceCommitted = true;
+        }
+        await options.runtime?.beforeSync?.();
+        const synced = await syncCatalogSourceCommand({
+            sourceId: selectedId, cliVersion: options.cliVersion, env: options.env,
         });
         const configured = (await readCatalogSourcesConfigSnapshot(options.env)).config.sources
             .find((source) => source.id === selectedId);
-        const refreshErrors = result.errors.length === 0 ? [] : [{
-                code: 'sourceRefreshFailed',
-                message: result.errors.map((error) => error.message).join('; '),
-            }];
         return {
-            receiptSchemaVersion: 1,
-            command: 'catalog:dev:activate',
-            ok: refreshErrors.length === 0,
-            state: refreshErrors.length === 0 ? 'completed' : 'partial',
+            receiptSchemaVersion: 2, command: 'catalog:dev:activate', ok: true, state: 'completed',
             workspaceIdentity: workspace.workspaceIdentity,
-            snapshot: { path: snapshotPath, action: snapshotAction, digest: snapshotDigest },
+            snapshot: { action: snapshotAction, digest: snapshotDigest },
             source: { id: selectedId, action: sourceAction, primary: configured.primary },
-            recovery: refreshErrors.length === 0 ? [] : [
-                'Fix the Catalog snapshot, then rerun catalog dev activate or refresh the source.',
-            ],
-            errors: refreshErrors,
+            active: { ready: true, snapshotDigest: synced.active?.snapshotDigest ?? synced.resolution.snapshotDigest },
+            recovery: [], errors: [],
         };
     }
     catch (error) {
         return {
-            receiptSchemaVersion: 1,
-            command: 'catalog:dev:activate',
-            ok: false,
-            state: 'completed',
+            receiptSchemaVersion: 2, command: 'catalog:dev:activate', ok: false,
+            state: snapshotAction === 'built' || sourceCommitted ? 'partial' : 'failed',
             workspaceIdentity: workspace.workspaceIdentity,
-            snapshot: { path: snapshotPath, action: snapshotAction, digest: snapshotDigest },
+            snapshot: { action: snapshotAction, digest: snapshotDigest },
             source: { id: selectedId, action: sourceAction, primary: false },
-            recovery: ['The snapshot was kept. Fix the source configuration, then rerun catalog dev activate.'],
-            errors: [codedFailure(error, 'sourceConfigFailed')],
+            active: { ready: false, snapshotDigest: null },
+            recovery: ['The source configuration and snapshot were kept. Fix the problem, then rerun catalog dev activate.'],
+            errors: [codedFailure(error, sourceCommitted ? 'sourceSyncFailed' : 'sourceConfigFailed')],
         };
     }
 }
 export async function getCatalogDevSourceStatus(options) {
-    const requestedRoot = path.resolve(options.cwd, options.workspaceRoot ?? '.');
     const empty = {
-        receiptSchemaVersion: 1,
-        command: 'catalog:dev:status',
-        ok: false,
+        receiptSchemaVersion: 3, command: 'catalog:dev:status', ok: false, ready: false,
         workspaceIdentity: null,
-        workspaceRoot: requestedRoot,
-        snapshot: { path: path.join(requestedRoot, DEFAULT_CATALOG_OUTPUT_PATH), state: 'absent', valid: false, digest: null },
+        snapshot: { state: 'absent', valid: false, digest: null },
         source: { exists: false, id: null, pathMatches: null, primary: null },
-        cache: { state: 'not-applicable', validatedAt: null, snapshotDigest: null },
+        active: { exists: false, ready: false, digestMatchesSnapshot: false, snapshotDigest: null },
         issues: [],
     };
     let workspace;
@@ -293,187 +233,183 @@ export async function getCatalogDevSourceStatus(options) {
         workspace = await resolveWorkspace(options.cwd, options.workspaceRoot);
     }
     catch (error) {
-        empty.issues.push({ code: 'workspaceInvalid', message: codedFailure(error, 'workspaceInvalid').message, blocking: true });
+        empty.issues.push({ ...codedFailure(error, 'workspaceInvalid'), blocking: true });
         return empty;
     }
+    empty.workspaceIdentity = workspace.workspace.workspaceIdentity;
     const staticStatus = await getCatalogStatus({
-        cwd: options.cwd,
-        workspaceRoot: workspace.workspace.workspaceRoot,
-        env: options.env,
-    });
-    const receipt = {
-        ...empty,
-        workspaceIdentity: workspace.workspace.workspaceIdentity,
-        workspaceRoot: workspace.workspace.workspaceRoot,
-        snapshot: {
-            path: staticStatus.snapshot.path,
-            state: staticStatus.snapshot.state,
-            valid: staticStatus.snapshot.valid,
-            digest: staticStatus.snapshot.snapshotDigest,
-        },
+        cwd: options.cwd, workspaceRoot: workspace.workspace.workspaceRoot, env: options.env,
+    }).catch(() => null);
+    if (!staticStatus) {
+        empty.issues.push({ code: 'catalogStatusInvalid', message: 'Catalog snapshot status is invalid.', blocking: true });
+        return empty;
+    }
+    empty.snapshot = {
+        state: staticStatus.snapshot.state,
+        valid: staticStatus.snapshot.valid,
+        digest: staticStatus.snapshot.snapshotDigest,
     };
+    const workspaceIssues = staticStatus.issues.filter((issue) => issue.blocking);
+    empty.issues.push(...workspaceIssues.map((issue) => ({
+        code: issue.code,
+        message: 'Catalog Workspace status has a blocking issue.',
+        blocking: true,
+    })));
     if (staticStatus.snapshot.state !== 'current') {
-        receipt.issues.push({
+        empty.issues.push({
             code: `snapshot${staticStatus.snapshot.state[0].toUpperCase()}${staticStatus.snapshot.state.slice(1)}`,
-            message: `Catalog development snapshot is ${staticStatus.snapshot.state}.`,
+            message: `Catalog development snapshot is ${staticStatus.snapshot.state}.`, blocking: true,
+        });
+    }
+    const config = await readCatalogSourcesConfigSnapshot(options.env).catch(() => null);
+    if (!config) {
+        empty.issues.push({ code: 'sourceConfigInvalid', message: 'Catalog source configuration is invalid.', blocking: true });
+        return empty;
+    }
+    const owned = managedSources(config.config.sources, workspace.workspace.workspaceIdentity);
+    if (owned.length !== 1) {
+        empty.issues.push({
+            code: owned.length === 0 ? 'sourceInactive' : 'multipleManagedSources',
+            message: owned.length === 0
+                ? 'Workspace has no configured development source.'
+                : 'Workspace owns multiple development sources.',
             blocking: true,
         });
     }
-    try {
-        const config = await readCatalogSourcesConfigSnapshot(options.env);
-        const owned = managedSources(config.config.sources, workspace.workspace.workspaceIdentity);
-        if (owned.length > 1) {
-            receipt.issues.push({
-                code: 'multipleManagedSources',
-                message: `Workspace owns multiple development sources: ${owned.map((source) => source.id).join(', ')}.`,
-                blocking: true,
-            });
+    const source = owned.length === 1 ? owned[0] : null;
+    if (source) {
+        const snapshotPath = path.join(workspace.workspace.workspaceRoot, DEFAULT_CATALOG_OUTPUT_PATH);
+        const pathMatches = source.path === snapshotPath;
+        empty.source = { exists: true, id: source.id, pathMatches, primary: source.primary };
+        if (!pathMatches) {
+            empty.issues.push({ code: 'sourcePathMismatch', message: 'Managed source path does not match this Workspace.', blocking: true });
         }
-        const source = owned.length === 1 ? owned[0] : null;
-        if (!source) {
-            receipt.issues.push({ code: 'sourceInactive', message: 'Workspace has no active development source.', blocking: false });
-            const suggested = normalizeSuggestedSourceId(workspace.workspace.workspaceRoot);
-            const collision = config.config.sources.find((entry) => entry.id === suggested);
-            if (collision) {
-                receipt.issues.push({
-                    code: 'suggestedSourceIdCollision',
-                    message: `Suggested source ID "${suggested}" is owned by another Workspace or is foreign.`,
-                    blocking: false,
-                });
-            }
+        const status = await readCatalogGenerationStatus({ sourceId: source.id, env: options.env }).catch(() => null);
+        const entry = status?.sources[0];
+        const snapshotDigest = entry?.active?.snapshotDigest ?? null;
+        const digestMatchesSnapshot = snapshotDigest !== null && snapshotDigest === empty.snapshot.digest;
+        empty.active = {
+            exists: entry?.active !== undefined,
+            ready: entry?.activeReady === true,
+            digestMatchesSnapshot,
+            snapshotDigest,
+        };
+        if (!entry?.active) {
+            empty.issues.push({ code: 'activeAbsent', message: 'Development source has no Active snapshot.', blocking: true });
         }
-        else {
-            const pathMatches = source.path === receipt.snapshot.path;
-            receipt.source = { exists: true, id: source.id, pathMatches, primary: source.primary };
-            if (!pathMatches) {
-                receipt.issues.push({
-                    code: 'sourcePathMismatch',
-                    message: 'Managed development source path does not match the current Workspace snapshot.',
-                    blocking: true,
-                });
-            }
-            const sourceIdentity = await calculateCatalogSourceIdentity(source);
-            const location = catalogSourceCacheInternal.resolveCatalogSourceCacheLocation({
-                sourceId: source.id,
-                sourceIdentity,
-                env: options.env,
-            });
-            const entry = await catalogSourceCacheInternal.readCatalogSourceCache({
-                location,
-                sourceId: source.id,
-                sourceIdentity,
-                requestedRef: 'path',
-                cliVersion: options.cliVersion,
-            });
-            receipt.cache = entry ? {
-                state: entry.entryDir === location.currentDir ? 'current' : 'last-good',
-                validatedAt: entry.metadata.validatedAt,
-                snapshotDigest: entry.metadata.snapshotDigest,
-            } : { state: 'absent', validatedAt: null, snapshotDigest: null };
+        else if (!entry.activeReady) {
+            empty.issues.push({ code: entry.errorCode ?? 'activeNotReady', message: 'Development source Active snapshot is not ready.', blocking: true });
+        }
+        if (entry?.active && !digestMatchesSnapshot) {
+            empty.issues.push({ code: 'activeSnapshotDigestMismatch', message: 'Active digest does not match the Workspace snapshot.', blocking: true });
         }
     }
-    catch (error) {
-        receipt.issues.push({ code: 'sourceConfigInvalid', message: codedFailure(error, 'sourceConfigInvalid').message, blocking: true });
-    }
-    receipt.ok = !receipt.issues.some((issue) => issue.blocking);
-    return receipt;
+    empty.ok = true;
+    empty.ready = empty.snapshot.state === 'current'
+        && staticStatus.ok
+        && workspaceIssues.length === 0
+        && source !== null
+        && empty.source.pathMatches === true
+        && empty.active.ready
+        && empty.active.digestMatchesSnapshot;
+    return empty;
 }
 export async function deactivateCatalogDevSource(options) {
-    const { workspace } = await resolveWorkspace(options.cwd, options.workspaceRoot);
-    const snapshotPath = path.join(workspace.workspaceRoot, DEFAULT_CATALOG_OUTPUT_PATH);
-    const config = await readCatalogSourcesConfigSnapshot(options.env).catch((error) => {
-        throw new CatalogDevSourceError('sourceConfigInvalid', error instanceof Error ? error.message : String(error));
+    if (options.workspaceRoot !== undefined && options.sourceId !== undefined) {
+        throw new CatalogDevSourceError('invalidArguments', '--workspace-root and --source-id are mutually exclusive.');
+    }
+    const config = await readCatalogSourcesConfigSnapshot(options.env).catch(() => {
+        throw new CatalogDevSourceError('sourceConfigInvalid', 'Catalog source configuration is invalid.');
     });
-    const owned = managedSources(config.config.sources, workspace.workspaceIdentity);
-    const base = {
-        receiptSchemaVersion: 1,
-        command: 'catalog:dev:deactivate',
-        workspaceIdentity: workspace.workspaceIdentity,
-        snapshotPath,
-    };
-    if (owned.length > 1) {
-        return {
-            ...base, ok: false, state: 'completed',
-            source: { id: null, action: 'retained', previousPrimary: false },
-            replacementPrimarySourceId: null,
-            recovery: ['Resolve the duplicate managed source configuration, then rerun catalog dev deactivate.'],
-            errors: [{ code: 'multipleManagedSources', message: `Workspace owns multiple development sources: ${owned.map((source) => source.id).join(', ')}.` }],
-        };
+    let source;
+    let workspaceIdentity;
+    let workspaceRoot;
+    if (options.sourceId !== undefined) {
+        assertExplicitSourceId(options.sourceId);
+        const configuredSource = config.config.sources.find((entry) => entry.id === options.sourceId);
+        if (configuredSource?.type !== 'path' || configuredSource.managedBy?.kind !== 'catalog-workspace') {
+            throw new CatalogDevSourceError('managedSourceNotFound', 'The source is not a Workspace-managed path source.');
+        }
+        if (options.yes !== true) {
+            return {
+                receiptSchemaVersion: 2, command: 'catalog:dev:deactivate', ok: false, state: 'failed',
+                workspaceIdentity: configuredSource.managedBy.workspaceIdentity,
+                source: { id: configuredSource.id, action: 'retained', previousPrimary: configuredSource.primary },
+                replacementPrimarySourceId: null,
+                recovery: ['Rerun with --source-id and --yes.'],
+                errors: [{ code: 'confirmationRequired', message: 'Recovery by source ID requires --yes.' }],
+            };
+        }
+        source = configuredSource;
+        workspaceIdentity = configuredSource.managedBy.workspaceIdentity;
+        workspaceRoot = options.cwd;
+    }
+    else {
+        const resolved = await resolveWorkspace(options.cwd, options.workspaceRoot);
+        workspaceIdentity = resolved.workspace.workspaceIdentity;
+        workspaceRoot = resolved.workspace.workspaceRoot;
+        const owned = managedSources(config.config.sources, workspaceIdentity);
+        if (owned.length > 1) {
+            throw new CatalogDevSourceError('multipleManagedSources', 'Workspace owns multiple development sources.');
+        }
+        source = owned[0];
     }
-    const source = owned[0];
     if (!source) {
         return {
-            ...base, ok: true, state: 'completed',
-            source: { id: null, action: 'absent', previousPrimary: false },
-            replacementPrimarySourceId: null,
-            recovery: [], errors: [],
+            receiptSchemaVersion: 2, command: 'catalog:dev:deactivate', ok: true, state: 'completed',
+            workspaceIdentity, source: { id: null, action: 'absent', previousPrimary: false },
+            replacementPrimarySourceId: null, recovery: [], errors: [],
         };
     }
     let replacementPrimarySourceId = null;
     if (source.primary) {
-        const otherSources = config.config.sources.filter((entry) => entry.id !== source.id);
-        const official = otherSources.find(isDefaultOfficialCatalogSource);
-        if (official)
-            replacementPrimarySourceId = official.id;
-        else if (otherSources.length === 1)
-            replacementPrimarySourceId = otherSources[0].id;
-        else {
+        const others = config.config.sources.filter((entry) => entry.id !== source.id);
+        const requested = options.replacementPrimary === undefined
+            ? others.find(isDefaultOfficialCatalogSource)
+                ?? (others.length === 1 ? others[0] : undefined)
+            : others.find((entry) => entry.id === options.replacementPrimary);
+        if (!requested) {
             return {
-                ...base, ok: false, state: 'completed',
-                source: { id: source.id, action: 'retained', previousPrimary: true },
+                receiptSchemaVersion: 2, command: 'catalog:dev:deactivate', ok: false, state: 'failed',
+                workspaceIdentity, source: { id: source.id, action: 'retained', previousPrimary: true },
                 replacementPrimarySourceId: null,
-                recovery: ['Select a replacement primary source, then rerun catalog dev deactivate.'],
-                errors: [{
-                        code: otherSources.length === 0 ? 'replacementPrimaryUnavailable' : 'replacementPrimaryAmbiguous',
-                        message: otherSources.length === 0
-                            ? 'No replacement primary Catalog source is available.'
-                            : `Replacement primary Catalog source is ambiguous: ${otherSources.map((entry) => entry.id).join(', ')}.`,
-                    }],
+                recovery: ['Select an existing replacement primary source.'],
+                errors: [{ code: 'replacementPrimaryUnavailable', message: 'A replacement primary source is required.' }],
             };
         }
+        replacementPrimarySourceId = requested.id;
+    }
+    else if (options.replacementPrimary !== undefined) {
+        throw new CatalogDevSourceError('replacementPrimaryInvalid', '--replacement-primary requires a primary target source.');
     }
     try {
-        await withAwHomeMutationLock({
-            env: options.env,
-            action: async (awHomeMutationToken) => {
-                const lockedConfig = await readCatalogSourcesConfigSnapshot(options.env);
-                if (lockedConfig.digest !== config.digest) {
-                    throw new CatalogDevSourceError('sourceConfigChanged', 'Catalog sources config changed before development source deactivation. Rerun the command.');
-                }
-                const runtime = { ...options.runtime?.sourceRuntime, awHomeMutationToken };
-                if (replacementPrimarySourceId) {
-                    await setPrimaryCatalogSourceCommand({
-                        sourceId: replacementPrimarySourceId,
-                        cwd: workspace.workspaceRoot,
-                        env: options.env,
-                        runtime,
-                    });
-                }
-                await removeCatalogSourceCommand({
-                    sourceId: source.id,
-                    cwd: workspace.workspaceRoot,
-                    env: options.env,
-                    runtime,
-                    managedByWorkspaceIdentity: workspace.workspaceIdentity,
-                });
-            },
+        if (replacementPrimarySourceId) {
+            await setPrimaryCatalogSourceCommand({
+                sourceId: replacementPrimarySourceId, cwd: workspaceRoot, env: options.env,
+                runtime: options.runtime?.sourceRuntime,
+            });
+        }
+        await removeCatalogSourceCommand({
+            sourceId: source.id, cwd: workspaceRoot, env: options.env,
+            runtime: options.runtime?.sourceRuntime,
+            managedByWorkspaceIdentity: workspaceIdentity,
         });
         return {
-            ...base, ok: true, state: 'completed',
-            source: { id: source.id, action: 'removed', previousPrimary: source.primary },
-            replacementPrimarySourceId,
-            recovery: [], errors: [],
+            receiptSchemaVersion: 2, command: 'catalog:dev:deactivate', ok: true, state: 'completed',
+            workspaceIdentity, source: { id: source.id, action: 'removed', previousPrimary: source.primary },
+            replacementPrimarySourceId, recovery: [], errors: [],
         };
     }
     catch (error) {
         const after = await readCatalogSourcesConfigSnapshot(options.env).catch(() => null);
-        const sourceStillExists = after?.config.sources.some((entry) => entry.id === source.id) ?? true;
+        const stillExists = after?.config.sources.some((entry) => entry.id === source.id) ?? true;
         const configChanged = after !== null && after.digest !== config.digest;
         return {
-            ...base, ok: false, state: configChanged ? 'partial' : 'completed',
-            source: { id: source.id, action: sourceStillExists ? 'retained' : 'removed', previousPrimary: source.primary },
+            receiptSchemaVersion: 2, command: 'catalog:dev:deactivate', ok: false,
+            state: configChanged || !stillExists ? 'partial' : 'failed', workspaceIdentity,
+            source: { id: source.id, action: stillExists ? 'retained' : 'removed', previousPrimary: source.primary },
             replacementPrimarySourceId,
-            recovery: ['The snapshot was kept. Fix the source configuration or cache, then rerun catalog dev deactivate.'],
+            recovery: ['Fix the source configuration, then rerun catalog dev deactivate.'],
             errors: [codedFailure(error, 'sourceConfigFailed')],
         };
     }