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

package/dist/src/commands/catalog-publish.js

@@ -1,42 +1,29 @@
 import crypto from 'node:crypto';
+import os from 'node:os';
 import path from 'node:path';
 import fs from 'fs-extra';
-import { resolveCatalogWorkspaceRoot, validatePublishedCatalogSnapshot, } from '@lesliechan721/aw-plugin-core';
-import { disposeCatalogPublicationInspection, parseRemoteRefs, prepareCatalogPublicationInspection, publicationGit, publicationGitExit, } from './catalog-publication-inspection.js';
+import { validatePublishedCatalogSnapshot } from '@lesliechan721/aw-plugin-core';
+import { disposeCatalogPublicationInspection, inspectCatalogPublicationLiveContext, parseRemoteRefs, prepareCatalogPublicationInspection, publicationGit, publicationGitExit, readCatalogPublicationBranchState, } from './catalog-publication-inspection.js';
+import { catalogPublicationJournalPath, catalogPublicationPlanDigest, catalogPublicationRepositoryName, catalogPublicationRepositoryPath, readCatalogPublicationJournal, writeCatalogPublicationJournalAtomic, } from './catalog-publication-journal.js';
 import { resolveCatalogPublicationTarget, } from './catalog-publication-target.js';
+import { resolveCatalogWorkspaceRoot, } from './catalog-workspace-resolution.js';
+export { catalogPublicationPlanDigest, parseCatalogPublicationJournal, } from './catalog-publication-journal.js';
 export { safeRemoteIdentity, sanitizedGitEnvironment } from './catalog-publication-inspection.js';
-function digest(value) {
-    return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
-}
-function canonicalJson(value) {
-    if (Array.isArray(value))
-        return `[${value.map(canonicalJson).join(',')}]`;
-    if (value !== null && typeof value === 'object') {
-        const record = value;
-        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
-    }
-    return JSON.stringify(value);
-}
-export function catalogPublicationDescriptorDigest(descriptor) {
-    return digest(canonicalJson(descriptor));
-}
-async function writeJsonAtomic(filePath, value, exclusive) {
-    await fs.ensureDir(path.dirname(filePath));
-    const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${crypto.randomUUID()}.tmp`);
-    await fs.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
-    try {
-        if (exclusive) {
-            await fs.link(temporary, filePath);
-            await fs.remove(temporary);
-        }
-        else {
-            await fs.rename(temporary, filePath);
+async function assertPublicationStatePathSafe(workspaceRoot) {
+    for (const candidate of [
+        path.join(workspaceRoot, '.aw'),
+        path.join(workspaceRoot, '.aw', 'publish'),
+    ]) {
+        if (!(await fs.pathExists(candidate)))
+            continue;
+        const stats = await fs.lstat(candidate);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            throw new Error('Catalog publication state path must contain only regular local directories.');
         }
     }
-    catch (error) {
-        await fs.remove(temporary);
-        throw error;
-    }
+}
+function sameDescriptor(left, right) {
+    return catalogPublicationPlanDigest(left) === catalogPublicationPlanDigest(right);
 }
 async function clearWorktree(repositoryRoot) {
     for (const name of await fs.readdir(repositoryRoot)) {
@@ -54,46 +41,45 @@ async function assertNoGitAttributes(root, relative = '') {
             await assertNoGitAttributes(root, child);
     }
 }
-async function assertSnapshotBinding(snapshotRoot, descriptor) {
-    const [stats, validation, ledgerBytes] = await Promise.all([
+async function assertSnapshotBinding(snapshotRoot, descriptor, display) {
+    const [stats, validation] = await Promise.all([
         fs.lstat(snapshotRoot),
         validatePublishedCatalogSnapshot(snapshotRoot),
-        fs.readFile(path.join(snapshotRoot, 'plugin-release-ledger.json')),
     ]);
     if (!stats.isDirectory() || stats.isSymbolicLink()) {
         throw new Error('Prepared Catalog snapshot must be a regular local directory.');
     }
     const release = validation.manifest.release;
-    if (validation.manifest.catalogVersion !== descriptor.catalogVersion
-        || validation.manifest.channel !== descriptor.channel
+    if (validation.manifest.catalogVersion !== display.catalogVersion
+        || validation.manifest.channel !== display.channel
+        || validation.manifest.entries.length !== display.pluginCount
         || validation.snapshotDigest !== descriptor.snapshotDigest
         || release.state !== 'published'
-        || release.sourceHead !== descriptor.sourceHead
-        || release.contentDigest !== descriptor.contentDigest
-        || release.planId !== descriptor.planId
-        || digest(ledgerBytes) !== descriptor.ledgerDigest) {
-        throw new Error('Prepared Catalog descriptor, snapshot, ledger, or plan identity changed.');
+        || release.sourceHead !== descriptor.sourceHead) {
+        throw new Error('Prepared Catalog descriptor, snapshot, or plan identity changed.');
     }
     await assertNoGitAttributes(snapshotRoot);
 }
-async function publishCatalogPublicationPreparation(options) {
-    const { preparation: inspection, descriptor, snapshotRoot } = options;
-    const { temporaryRoot, repositoryRoot, repoRoot, sourceHead, remote, branch, branchRef, tag, tagRef, fetchUrl, pushUrl, safeFetchUrl, safePushUrl, remoteIdentityDigest, parent, attemptPath, env, } = inspection;
-    if (catalogPublicationDescriptorDigest(inspection.descriptor)
-        !== catalogPublicationDescriptorDigest(descriptor)) {
-        throw new Error('Catalog publication descriptor changed after preparation.');
-    }
-    if (!inspection.tagAvailable) {
-        throw new Error(`Remote Catalog tag ${tag} already exists. Increase the Catalog version.`);
-    }
-    if (!inspection.attemptAvailable || await fs.pathExists(attemptPath)) {
-        throw new Error(`Catalog ${descriptor.catalogVersion} already has an attempted publication record. `
-            + 'Run aw catalog version <higher> before publishing again.');
-    }
-    if (!(await publicationGitExit(repoRoot, ['check-ignore', '-q', attemptPath], env))) {
-        throw new Error('Catalog publish state under .aw/publish must be ignored by Git. Add .aw/ to .gitignore.');
+function displayFromPreparation(preparation) {
+    return {
+        catalogVersion: preparation.prepared.catalogVersion,
+        channel: preparation.prepared.channel,
+        pluginCount: preparation.prepared.pluginNames.length,
+    };
+}
+function assertLiveContextMatchesDescriptor(context, descriptor) {
+    if (context.workspaceIdentity !== descriptor.workspaceIdentity
+        || context.sourceHead !== descriptor.sourceHead
+        || context.remoteName !== descriptor.remote.name
+        || context.remoteIdentityDigest !== descriptor.remote.identityDigest
+        || context.branch !== descriptor.branch
+        || context.tag !== descriptor.tag) {
+        throw new Error('Catalog publication identity changed. Increase the Catalog version and create a new plan.');
     }
-    await assertSnapshotBinding(snapshotRoot, descriptor);
+}
+async function createPublicationCommit(preparation, descriptor, snapshotRoot, display) {
+    const { repositoryRoot, parent, tag, env } = preparation;
+    await assertSnapshotBinding(snapshotRoot, descriptor, display);
     if (parent) {
         await publicationGit(repositoryRoot, [
             'checkout', '--quiet', '--detach', 'refs/aw/catalog-parent',
@@ -106,11 +92,13 @@ async function publishCatalogPublicationPreparation(options) {
     }
     await clearWorktree(repositoryRoot);
     await fs.copy(snapshotRoot, repositoryRoot, { dereference: false });
-    await publicationGit(repositoryRoot, ['add', '--force', '--all'], env, 'publicationCommitFailed', 'Could not stage the Catalog publication tree.');
+    await publicationGit(repositoryRoot, [
+        'add', '--force', '--all',
+    ], env, 'publicationCommitFailed', 'Could not stage the Catalog publication tree.');
     await publicationGit(repositoryRoot, [
         '-c', 'user.name=AW Catalog Publisher',
         '-c', 'user.email=catalog-publisher@agent-workflows.invalid',
-        'commit', '--quiet', '-m', `Catalog ${descriptor.catalogVersion}`,
+        'commit', '--quiet', '-m', `Catalog ${display.catalogVersion}`,
     ], env, 'publicationCommitFailed', 'Could not create the Catalog publication commit.');
     const commit = await publicationGit(repositoryRoot, [
         'rev-parse', 'HEAD',
@@ -123,152 +111,539 @@ async function publishCatalogPublicationPreparation(options) {
     if ((parent && (parents.length !== 1 || parents[0] !== parent)) || (!parent && parents.length !== 0)) {
         throw new Error('Catalog publication commit has an invalid parent.');
     }
-    const verificationRoot = path.join(temporaryRoot, 'verification');
+    const verificationRoot = path.join(preparation.temporaryRoot, 'verification');
     await fs.ensureDir(verificationRoot);
     await publicationGit(repositoryRoot, [
         '--work-tree', verificationRoot, 'checkout', '--quiet', commit, '--', '.',
     ], env, 'publicationCommitFailed', 'Could not verify the Catalog publication commit tree.');
-    await assertSnapshotBinding(verificationRoot, descriptor);
+    await assertSnapshotBinding(verificationRoot, descriptor, display);
     await publicationGit(repositoryRoot, [
         '-c', 'user.name=AW Catalog Publisher',
         '-c', 'user.email=catalog-publisher@agent-workflows.invalid',
-        'tag', '--annotate', tag, '--message', `Catalog ${descriptor.catalogVersion}`,
+        'tag', '--annotate', tag, '--message', `Catalog ${display.catalogVersion}`,
     ], env, 'publicationCommitFailed', 'Could not create the annotated Catalog tag.');
-    const liveHead = await publicationGit(repoRoot, [
-        'rev-parse', '--verify', 'HEAD',
-    ], env, 'sourceDrift', 'Could not recheck the source Git HEAD.');
-    const liveStatus = await publicationGit(repoRoot, [
-        'status', '--porcelain=v1', '--untracked-files=all', '--ignore-submodules=none',
-    ], env, 'sourceDrift', 'Could not recheck the source worktree.');
-    if (liveHead !== sourceHead || liveStatus !== '') {
-        throw new Error('Source HEAD or worktree changed before Catalog publication.');
-    }
-    let liveFetchUrl;
-    let livePushUrl;
-    if (descriptor.remote.name === null) {
-        liveFetchUrl = fetchUrl;
-        livePushUrl = pushUrl;
+    return commit;
+}
+async function remoteRefState(cwd, remote, branchRef, tagRef, env) {
+    const refs = parseRemoteRefs(await publicationGit(cwd, [
+        'ls-remote', remote, branchRef, tagRef, `${tagRef}^{}`,
+    ], env, 'remoteReadFailed', 'Could not inspect the Catalog publication remote.'));
+    const tagPresent = refs.has(tagRef) || refs.has(`${tagRef}^{}`);
+    return {
+        branchCommit: refs.get(branchRef) ?? null,
+        tagCommit: refs.get(`${tagRef}^{}`) ?? null,
+        tagPresent,
+        tagAnnotated: refs.has(tagRef) && refs.has(`${tagRef}^{}`),
+    };
+}
+function assertReconciliableRemoteState(state, journal) {
+    const branchAtExpected = state.branchCommit === journal.expectedCommit;
+    const branchAtParent = state.branchCommit === journal.descriptor.parent;
+    const tagAtExpected = state.tagAnnotated && state.tagCommit === journal.expectedCommit;
+    const tagAbsent = !state.tagPresent;
+    if ((branchAtExpected && tagAtExpected)
+        || (branchAtParent && tagAbsent)
+        || (branchAtExpected && tagAbsent)
+        || (branchAtParent && tagAtExpected))
+        return;
+    throw new Error(`Catalog ${journal.display.catalogVersion} remote refs conflict with the prepared plan. Increase the Catalog version.`);
+}
+const PERSISTED_REPOSITORY_CONFIG = new Map([
+    ['core.repositoryformatversion', new Set(['0'])],
+    ['core.filemode', new Set(['true', 'false'])],
+    ['core.bare', new Set(['false'])],
+    ['core.logallrefupdates', new Set(['true'])],
+    ['core.ignorecase', new Set(['true'])],
+    ['core.precomposeunicode', new Set(['true'])],
+    ['core.hookspath', new Set([os.devNull])],
+    ['core.symlinks', new Set(['true'])],
+]);
+const REQUIRED_PERSISTED_REPOSITORY_CONFIG = [
+    'core.repositoryformatversion',
+    'core.filemode',
+    'core.bare',
+    'core.logallrefupdates',
+    'core.hookspath',
+    'core.symlinks',
+];
+async function assertRegularGitDirectory(root) {
+    const stats = await fs.lstat(root);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error('Pending Catalog publication Git directory is unsafe.');
     }
-    else {
-        [liveFetchUrl, livePushUrl] = await Promise.all([
-            publicationGit(repoRoot, ['remote', 'get-url', descriptor.remote.name], env, 'remoteDrift', 'Could not recheck the Catalog publication remote configuration.'),
-            publicationGit(repoRoot, ['remote', 'get-url', '--push', descriptor.remote.name], env, 'remoteDrift', 'Could not recheck the Catalog publication remote configuration.'),
+}
+async function assertRegularGitFile(filePath) {
+    const stats = await fs.lstat(filePath);
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+        throw new Error('Pending Catalog publication Git control file is unsafe.');
+    }
+}
+async function assertGitTreeContainsOnlyLocalFiles(root) {
+    for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+        const child = path.join(root, entry.name);
+        const stats = await fs.lstat(child);
+        if (stats.isSymbolicLink()) {
+            throw new Error('Pending Catalog publication Git data must not contain symbolic links.');
+        }
+        if (stats.isDirectory()) {
+            await assertGitTreeContainsOnlyLocalFiles(child);
+        }
+        else if (!stats.isFile()) {
+            throw new Error('Pending Catalog publication Git data must contain only regular local files.');
+        }
+    }
+}
+async function assertPathMissing(filePath) {
+    try {
+        await fs.lstat(filePath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    throw new Error('Pending Catalog publication repository must not use alternate object stores.');
+}
+async function validatePersistentRepositoryControlState(repositoryRoot, env) {
+    const gitRoot = path.join(repositoryRoot, '.git');
+    const configPath = path.join(gitRoot, 'config');
+    await assertRegularGitDirectory(gitRoot);
+    await assertRegularGitFile(configPath);
+    await assertRegularGitFile(path.join(gitRoot, 'HEAD'));
+    await assertRegularGitFile(path.join(gitRoot, 'index'));
+    await assertRegularGitDirectory(path.join(gitRoot, 'objects'));
+    await assertRegularGitDirectory(path.join(gitRoot, 'refs'));
+    await assertPathMissing(path.join(gitRoot, 'objects', 'info', 'alternates'));
+    await assertPathMissing(path.join(gitRoot, 'objects', 'info', 'http-alternates'));
+    await assertGitTreeContainsOnlyLocalFiles(gitRoot);
+    const entries = (await publicationGit(repositoryRoot, [
+        'config', '--file', configPath, '--no-includes', '--null', '--list',
+    ], env, 'pendingRepositoryInvalid', 'Pending Catalog publication config is damaged.'))
+        .split('\0')
+        .filter(Boolean);
+    const seen = new Set();
+    for (const entry of entries) {
+        const separator = entry.indexOf('\n');
+        if (separator <= 0)
+            throw new Error('Pending Catalog publication config is damaged.');
+        const key = entry.slice(0, separator).toLowerCase();
+        const value = entry.slice(separator + 1);
+        if (seen.has(key) || !PERSISTED_REPOSITORY_CONFIG.get(key)?.has(value)) {
+            throw new Error('Pending Catalog publication config contains unsafe local settings.');
+        }
+        seen.add(key);
+    }
+    if (REQUIRED_PERSISTED_REPOSITORY_CONFIG.some((key) => !seen.has(key))) {
+        throw new Error('Pending Catalog publication config is incomplete.');
+    }
+}
+async function validatePersistentRepository(repositoryRoot, journal, env) {
+    const version = journal.display.catalogVersion;
+    let stats;
+    try {
+        stats = await fs.lstat(repositoryRoot);
+    }
+    catch (error) {
+        throw new Error(`Catalog ${version} pending publication repository is missing or damaged. Increase the Catalog version.`, { cause: error });
+    }
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`Catalog ${version} pending publication repository is missing or damaged. Increase the Catalog version.`);
+    }
+    try {
+        await validatePersistentRepositoryControlState(repositoryRoot, env);
+        const [head, tagCommit, tagType, remotes, parents] = await Promise.all([
+            publicationGit(repositoryRoot, ['rev-parse', '--verify', 'HEAD'], env, 'pendingRepositoryInvalid', 'Pending Catalog publication repository is damaged.'),
+            publicationGit(repositoryRoot, ['rev-parse', `${journal.descriptor.tag}^{commit}`], env, 'pendingRepositoryInvalid', 'Pending Catalog publication tag is damaged.'),
+            publicationGit(repositoryRoot, ['cat-file', '-t', `refs/tags/${journal.descriptor.tag}`], env, 'pendingRepositoryInvalid', 'Pending Catalog publication tag is damaged.'),
+            publicationGit(repositoryRoot, ['remote'], env, 'pendingRepositoryInvalid', 'Pending Catalog publication repository is damaged.'),
+            publicationGit(repositoryRoot, ['show', '-s', '--format=%P', journal.expectedCommit], env, 'pendingRepositoryInvalid', 'Pending Catalog publication commit is damaged.'),
         ]);
+        const parentList = parents.split(/\s+/u).filter(Boolean);
+        if (head !== journal.expectedCommit
+            || tagCommit !== journal.expectedCommit
+            || tagType !== 'tag'
+            || remotes !== ''
+            || (journal.descriptor.parent === null
+                ? parentList.length !== 0
+                : parentList.length !== 1 || parentList[0] !== journal.descriptor.parent))
+            throw new Error('Pending Catalog publication repository identity changed.');
+        const verificationRoot = path.join(path.dirname(repositoryRoot), `.${path.basename(repositoryRoot)}.${crypto.randomUUID()}.verify`);
+        try {
+            await fs.ensureDir(verificationRoot);
+            await publicationGit(repositoryRoot, [
+                '--work-tree', verificationRoot, 'checkout', '--quiet', journal.expectedCommit, '--', '.',
+            ], env, 'pendingRepositoryInvalid', 'Pending Catalog publication commit tree is damaged.');
+            await assertSnapshotBinding(verificationRoot, journal.descriptor, journal.display);
+        }
+        finally {
+            await fs.remove(verificationRoot);
+        }
+    }
+    catch (error) {
+        throw new Error(`Catalog ${version} pending publication repository is missing or damaged. Increase the Catalog version.`, { cause: error });
+    }
+}
+async function persistRepository(preparation, finalPath, journal) {
+    const parent = path.dirname(finalPath);
+    await fs.ensureDir(parent);
+    const staging = path.join(parent, `.${path.basename(finalPath)}.${crypto.randomUUID()}.tmp`);
+    try {
+        await publicationGit(preparation.repositoryRoot, [
+            'remote', 'remove', 'publish',
+        ], preparation.env, 'temporaryRepositoryFailed', 'Could not seal the publication repository.');
+        await fs.copy(preparation.repositoryRoot, staging, { dereference: false, errorOnExist: true });
+        await validatePersistentRepository(staging, journal, preparation.env);
+        await fs.rename(staging, finalPath);
     }
-    if (digest(JSON.stringify({ fetchUrl: liveFetchUrl, pushUrl: livePushUrl })) !== remoteIdentityDigest) {
-        throw new Error('Catalog remote configuration changed during preparation.');
+    finally {
+        await fs.remove(staging);
+    }
+}
+function receiptBase(context, journal, resolution) {
+    const repositoryPath = journal.repository === null
+        ? null
+        : path.join(path.dirname(catalogPublicationJournalPath(context.catalogWorkspaceRoot, journal.display.catalogVersion)), journal.repository);
+    return {
+        ok: true,
+        workspaceRoot: context.catalogWorkspaceRoot,
+        workspaceRootResolvedFrom: resolution.workspaceRootResolvedFrom ?? 'explicit',
+        workspaceIdentity: journal.descriptor.workspaceIdentity,
+        catalogVersion: journal.display.catalogVersion,
+        channel: journal.display.channel,
+        remote: context.remote,
+        remoteResolvedFrom: resolution.remoteResolvedFrom ?? 'explicit',
+        remoteUrl: context.safeFetchUrl,
+        fetchUrl: context.safeFetchUrl,
+        pushUrl: context.safePushUrl,
+        branch: journal.descriptor.branch,
+        branchResolvedFrom: resolution.branchResolvedFrom ?? 'explicit',
+        parent: journal.descriptor.parent,
+        tag: journal.descriptor.tag,
+        expectedCommit: journal.expectedCommit,
+        sourceHead: journal.descriptor.sourceHead,
+        pluginCount: journal.display.pluginCount,
+        snapshotDigest: journal.descriptor.snapshotDigest,
+        planDigest: journal.planDigest,
+        descriptor: journal.descriptor,
+        journalPath: catalogPublicationJournalPath(context.catalogWorkspaceRoot, journal.display.catalogVersion),
+        repositoryPath,
+    };
+}
+async function readExistingPlan(context, resolution) {
+    await assertPublicationStatePathSafe(context.catalogWorkspaceRoot);
+    const journalPath = catalogPublicationJournalPath(context.catalogWorkspaceRoot, context.catalogVersion);
+    const repositoryPath = catalogPublicationRepositoryPath(context.catalogWorkspaceRoot, context.catalogVersion);
+    const journal = await readCatalogPublicationJournal(journalPath, context.catalogVersion);
+    if (!journal) {
+        if (await fs.pathExists(repositoryPath)) {
+            throw new Error(`Catalog ${context.catalogVersion} pending publication journal is missing. Increase the Catalog version.`);
+        }
+        return null;
     }
-    const liveRefs = parseRemoteRefs(await publicationGit(repositoryRoot, [
-        'ls-remote', 'publish', branchRef, tagRef, `${tagRef}^{}`,
-    ], env, 'remoteDrift', 'Could not recheck the Catalog publication remote.'));
-    if ((liveRefs.get(branchRef) ?? null) !== parent || liveRefs.has(tagRef) || liveRefs.has(`${tagRef}^{}`)) {
-        throw new Error('Catalog remote changed during preparation. Increase the Catalog version before publishing again.');
+    assertLiveContextMatchesDescriptor(context, journal.descriptor);
+    if (journal.state !== 'published') {
+        await validatePersistentRepository(repositoryPath, journal, context.env);
     }
-    if (await fs.pathExists(attemptPath)) {
-        throw new Error(`Catalog ${descriptor.catalogVersion} already has an attempted publication record. `
-            + 'Run aw catalog version <higher> before publishing again.');
+    const state = await remoteRefState(context.repoRoot, context.pushUrl, context.branchRef, context.tagRef, context.env);
+    if (journal.state === 'published'
+        && (state.branchCommit !== journal.expectedCommit
+            || !state.tagAnnotated
+            || state.tagCommit !== journal.expectedCommit)) {
+        throw new Error(`Catalog ${journal.display.catalogVersion} published journal conflicts with remote refs. Increase the Catalog version.`);
     }
-    await options.beforeRemoteWrite?.();
-    const attempted = {
+    assertReconciliableRemoteState(state, journal);
+    return {
+        command: 'catalog:publish:plan',
+        state: journal.state,
+        ...receiptBase(context, journal, resolution),
+    };
+}
+async function persistNewPlan(options) {
+    const { preparation, descriptor, snapshotRoot, resolution } = options;
+    await assertPublicationStatePathSafe(preparation.catalogWorkspaceRoot);
+    if (!sameDescriptor(preparation.descriptor, descriptor)) {
+        throw new Error('Catalog publication descriptor changed during preparation.');
+    }
+    const display = displayFromPreparation(preparation);
+    const journalPath = catalogPublicationJournalPath(preparation.catalogWorkspaceRoot, display.catalogVersion);
+    const repositoryPath = catalogPublicationRepositoryPath(preparation.catalogWorkspaceRoot, display.catalogVersion);
+    if (!(await publicationGitExit(preparation.repoRoot, ['check-ignore', '-q', journalPath], preparation.env))) {
+        throw new Error('Catalog publish state under .aw/publish must be ignored by Git. Add .aw/ to .gitignore.');
+    }
+    if (await fs.pathExists(journalPath) || await fs.pathExists(repositoryPath)) {
+        throw new Error(`Catalog ${display.catalogVersion} already has publication state. Use its existing plan or increase the Catalog version.`);
+    }
+    if (!preparation.tagAvailable) {
+        throw new Error(`Remote Catalog tag ${descriptor.tag} already exists. Increase the Catalog version.`);
+    }
+    const expectedCommit = await createPublicationCommit(preparation, descriptor, snapshotRoot, display);
+    const context = await inspectCatalogPublicationLiveContext({
+        workspaceRoot: preparation.catalogWorkspaceRoot,
+        ...(descriptor.remote.name === null ? { remoteUrl: preparation.pushUrl } : { remote: descriptor.remote.name }),
+        branch: descriptor.branch,
+        env: preparation.env,
+    });
+    assertLiveContextMatchesDescriptor(context, descriptor);
+    const liveRefs = await remoteRefState(preparation.repositoryRoot, 'publish', preparation.branchRef, preparation.tagRef, preparation.env);
+    if (liveRefs.branchCommit !== descriptor.parent || liveRefs.tagPresent) {
+        throw new Error(`Catalog ${display.catalogVersion} remote changed during plan creation. Increase the Catalog version.`);
+    }
+    const journal = {
         schemaVersion: 1,
-        state: 'attempted',
-        workspaceIdentity: descriptor.workspaceIdentity,
-        catalogVersion: descriptor.catalogVersion,
-        sourceHead,
-        remote: { name: descriptor.remote.name, identityDigest: remoteIdentityDigest },
-        branch,
-        parent,
-        tag,
-        snapshotDigest: descriptor.snapshotDigest,
-        contentDigest: descriptor.contentDigest,
-        planId: descriptor.planId,
-        descriptorDigest: catalogPublicationDescriptorDigest(descriptor),
-        attemptedAt: new Date().toISOString(),
+        state: 'prepared',
+        planDigest: catalogPublicationPlanDigest(descriptor),
+        descriptor,
+        expectedCommit,
+        repository: catalogPublicationRepositoryName(display.catalogVersion),
+        display,
+        preparedAt: new Date().toISOString(),
     };
+    await persistRepository(preparation, repositoryPath, journal);
     try {
-        await writeJsonAtomic(attemptPath, attempted, true);
+        await writeCatalogPublicationJournalAtomic(journalPath, journal, true);
     }
     catch (error) {
         if (error.code === 'EEXIST') {
-            throw new Error(`Catalog ${descriptor.catalogVersion} already has an attempted publication record. `
-                + 'Run aw catalog version <higher> before publishing again.');
+            throw new Error(`Catalog ${display.catalogVersion} publication journal already exists. Use its plan or increase the Catalog version.`);
         }
         throw error;
     }
+    return {
+        command: 'catalog:publish:plan',
+        state: 'prepared',
+        ...receiptBase(context, journal, resolution),
+    };
+}
+export async function persistCatalogPublicationPlan(options) {
+    return persistNewPlan({
+        preparation: options.preparation,
+        descriptor: options.descriptor ?? options.preparation.descriptor,
+        snapshotRoot: options.snapshotRoot ?? options.preparation.prepared.outputRoot,
+        resolution: options,
+    });
+}
+export async function prepareCatalogPublicationPlan(options) {
+    const context = await inspectCatalogPublicationLiveContext(options);
+    const existing = await readExistingPlan(context, options);
+    if (existing)
+        return existing;
+    const initialState = await remoteRefState(context.repoRoot, context.pushUrl, context.branchRef, context.tagRef, context.env);
+    if (initialState.tagPresent) {
+        throw new Error(`Remote Catalog tag ${context.tag} already exists. Increase the Catalog version.`);
+    }
+    if (initialState.branchCommit !== null) {
+        const branchState = await readCatalogPublicationBranchState({
+            workspaceRoot: context.catalogWorkspaceRoot,
+            ...(options.remoteUrl === undefined ? { remote: options.remote } : { remoteUrl: options.remoteUrl }),
+            branch: context.branch,
+            env: options.env,
+        });
+        if (branchState?.version === context.catalogVersion) {
+            throw new Error(`Remote Catalog branch already contains version ${context.catalogVersion} without its journal. Increase the Catalog version.`);
+        }
+    }
+    const preparation = await prepareCatalogPublicationInspection(options);
     try {
-        await publicationGit(repositoryRoot, [
-            'push', '--atomic', `--force-with-lease=${branchRef}:${parent ?? ''}`,
-            'publish', `${commit}:${branchRef}`, `${tagRef}:${tagRef}`,
-        ], env, 'publicationUncertain', `Catalog atomic push failed or its result is uncertain. Do not retry ${descriptor.catalogVersion}; increase the Catalog version.`);
+        return await persistNewPlan({
+            preparation,
+            descriptor: preparation.descriptor,
+            snapshotRoot: preparation.prepared.outputRoot,
+            resolution: options,
+        });
     }
-    catch {
-        throw new Error(`Catalog atomic push failed or its result is uncertain. Do not retry ${descriptor.catalogVersion}; run aw catalog version <higher>.`);
+    finally {
+        await disposeCatalogPublicationInspection(preparation);
+    }
+}
+async function markUncertain(journalPath, journal) {
+    const uncertain = {
+        schemaVersion: 1,
+        state: 'uncertain',
+        planDigest: journal.planDigest,
+        descriptor: journal.descriptor,
+        expectedCommit: journal.expectedCommit,
+        repository: journal.repository,
+        display: journal.display,
+        preparedAt: journal.preparedAt,
+        uncertainAt: new Date().toISOString(),
+    };
+    await writeCatalogPublicationJournalAtomic(journalPath, uncertain);
+    return uncertain;
+}
+export async function applyCatalogPublicationPlan(options) {
+    if (!/^sha256:[0-9a-f]{64}$/u.test(options.expectedPlanDigest)) {
+        throw new Error('Catalog publish apply requires --expected-plan-digest from catalog publish plan.');
+    }
+    const context = await inspectCatalogPublicationLiveContext(options);
+    await assertPublicationStatePathSafe(context.catalogWorkspaceRoot);
+    const journalPath = catalogPublicationJournalPath(context.catalogWorkspaceRoot, context.catalogVersion);
+    const repositoryPath = catalogPublicationRepositoryPath(context.catalogWorkspaceRoot, context.catalogVersion);
+    let journal = await readCatalogPublicationJournal(journalPath, context.catalogVersion);
+    if (!journal) {
+        const state = await remoteRefState(context.repoRoot, context.pushUrl, context.branchRef, context.tagRef, context.env);
+        const branchState = state.branchCommit === null
+            ? null
+            : await readCatalogPublicationBranchState({
+                workspaceRoot: context.catalogWorkspaceRoot,
+                ...(options.remoteUrl === undefined ? { remote: options.remote } : { remoteUrl: options.remoteUrl }),
+                branch: context.branch,
+                env: options.env,
+            });
+        if (state.tagPresent
+            || await fs.pathExists(repositoryPath)
+            || branchState?.version === context.catalogVersion) {
+            throw new Error(`Catalog ${context.catalogVersion} publication state is missing while the version is occupied. Increase the Catalog version.`);
+        }
+        throw new Error(`Catalog ${context.catalogVersion} has no prepared publication plan. Run catalog publish plan.`);
     }
-    const publishedRefs = parseRemoteRefs(await publicationGit(repositoryRoot, [
-        'ls-remote', 'publish', branchRef, tagRef, `${tagRef}^{}`,
-    ], env, 'publicationUncertain', `Catalog publication result is uncertain. Do not retry ${descriptor.catalogVersion}; increase the Catalog version.`));
-    if (publishedRefs.get(branchRef) !== commit || publishedRefs.get(`${tagRef}^{}`) !== commit) {
-        throw new Error(`Catalog publication result is uncertain. Do not retry ${descriptor.catalogVersion}; run aw catalog version <higher>.`);
+    if (journal.planDigest !== options.expectedPlanDigest) {
+        throw new Error(`Catalog ${context.catalogVersion} plan does not match the authorized digest. Increase the Catalog version for a different plan.`);
     }
-    await writeJsonAtomic(attemptPath, {
-        ...attempted,
+    assertLiveContextMatchesDescriptor(context, journal.descriptor);
+    if (journal.state === 'published') {
+        const state = await remoteRefState(context.repoRoot, context.pushUrl, context.branchRef, context.tagRef, context.env);
+        if (state.branchCommit !== journal.expectedCommit || !state.tagAnnotated || state.tagCommit !== journal.expectedCommit) {
+            throw new Error(`Catalog ${context.catalogVersion} published journal conflicts with remote refs. Increase the Catalog version.`);
+        }
+        if (await fs.pathExists(repositoryPath)) {
+            try {
+                await validatePersistentRepository(repositoryPath, {
+                    schemaVersion: 1,
+                    state: 'prepared',
+                    planDigest: journal.planDigest,
+                    descriptor: journal.descriptor,
+                    expectedCommit: journal.expectedCommit,
+                    repository: catalogPublicationRepositoryName(context.catalogVersion),
+                    display: journal.display,
+                    preparedAt: journal.preparedAt,
+                }, context.env);
+                await fs.remove(repositoryPath);
+            }
+            catch {
+                // Published remote refs are authoritative. Leave unrecognized local residue for safe manual cleanup.
+            }
+        }
+        return {
+            command: 'catalog:publish:apply',
+            state: 'published',
+            commit: journal.expectedCommit,
+            reconciliation: 'already-published',
+            ...receiptBase(context, journal, options),
+        };
+    }
+    await validatePersistentRepository(repositoryPath, journal, context.env);
+    let state = await remoteRefState(repositoryPath, context.pushUrl, context.branchRef, context.tagRef, context.env);
+    assertReconciliableRemoteState(state, journal);
+    let reconciliation;
+    const branchAtExpected = state.branchCommit === journal.expectedCommit;
+    const tagAtExpected = state.tagAnnotated && state.tagCommit === journal.expectedCommit;
+    if (branchAtExpected && tagAtExpected) {
+        reconciliation = 'already-remote';
+    }
+    else {
+        await options.beforeRemoteWrite?.();
+        const writeContext = await inspectCatalogPublicationLiveContext(options);
+        assertLiveContextMatchesDescriptor(writeContext, journal.descriptor);
+        await validatePersistentRepository(repositoryPath, journal, writeContext.env);
+        state = await remoteRefState(repositoryPath, writeContext.pushUrl, writeContext.branchRef, writeContext.tagRef, writeContext.env);
+        assertReconciliableRemoteState(state, journal);
+        try {
+            if (state.branchCommit === journal.expectedCommit
+                && state.tagAnnotated
+                && state.tagCommit === journal.expectedCommit) {
+                reconciliation = 'already-remote';
+            }
+            else if (state.branchCommit === journal.descriptor.parent && !state.tagPresent) {
+                reconciliation = 'atomic';
+                await publicationGit(repositoryPath, [
+                    'push', '--atomic',
+                    `--force-with-lease=${writeContext.branchRef}:${journal.descriptor.parent ?? ''}`,
+                    writeContext.pushUrl,
+                    `${journal.expectedCommit}:${writeContext.branchRef}`,
+                    `${writeContext.tagRef}:${writeContext.tagRef}`,
+                ], writeContext.env, 'publicationUncertain', 'Catalog atomic push failed or its result is uncertain.');
+            }
+            else if (state.branchCommit === journal.expectedCommit && !state.tagPresent) {
+                reconciliation = 'tag';
+                await publicationGit(repositoryPath, [
+                    'push', writeContext.pushUrl, `${writeContext.tagRef}:${writeContext.tagRef}`,
+                ], writeContext.env, 'publicationUncertain', 'Catalog tag push failed or its result is uncertain.');
+            }
+            else {
+                reconciliation = 'branch';
+                await publicationGit(repositoryPath, [
+                    'push', `--force-with-lease=${writeContext.branchRef}:${journal.descriptor.parent ?? ''}`,
+                    writeContext.pushUrl, `${journal.expectedCommit}:${writeContext.branchRef}`,
+                ], writeContext.env, 'publicationUncertain', 'Catalog branch push failed or its result is uncertain.');
+            }
+        }
+        catch (error) {
+            journal = await markUncertain(journalPath, journal);
+            throw new Error(`Catalog ${context.catalogVersion} publication result is uncertain. Retry apply with the same plan digest.`, { cause: error });
+        }
+        try {
+            state = await remoteRefState(repositoryPath, context.pushUrl, context.branchRef, context.tagRef, context.env);
+        }
+        catch (error) {
+            journal = await markUncertain(journalPath, journal);
+            throw new Error(`Catalog ${context.catalogVersion} publication result is uncertain. Retry apply with the same plan digest.`, { cause: error });
+        }
+        if (state.branchCommit !== journal.expectedCommit || !state.tagAnnotated || state.tagCommit !== journal.expectedCommit) {
+            journal = await markUncertain(journalPath, journal);
+            throw new Error(`Catalog ${context.catalogVersion} publication result is uncertain. Retry apply with the same plan digest.`);
+        }
+    }
+    const published = {
+        schemaVersion: 1,
         state: 'published',
-        commit,
+        planDigest: journal.planDigest,
+        descriptor: journal.descriptor,
+        expectedCommit: journal.expectedCommit,
+        repository: null,
+        display: journal.display,
+        preparedAt: journal.preparedAt,
         publishedAt: new Date().toISOString(),
-    }, false);
+    };
+    await writeCatalogPublicationJournalAtomic(journalPath, published);
+    await fs.remove(repositoryPath);
     return {
-        command: 'catalog:publish',
-        ok: true,
-        workspaceRoot: inspection.catalogWorkspaceRoot,
-        workspaceRootResolvedFrom: options.workspaceRootResolvedFrom ?? 'explicit',
-        workspaceIdentity: descriptor.workspaceIdentity,
-        catalogVersion: descriptor.catalogVersion,
-        channel: descriptor.channel,
-        remote,
-        remoteResolvedFrom: options.remoteResolvedFrom ?? 'explicit',
-        remoteUrl: safeFetchUrl,
-        fetchUrl: safeFetchUrl,
-        pushUrl: safePushUrl,
-        branch,
-        branchResolvedFrom: options.branchResolvedFrom ?? 'explicit',
-        parent,
-        tag,
-        commit,
-        sourceHead,
-        pluginCount: descriptor.pluginNames.length,
-        snapshotDigest: descriptor.snapshotDigest,
-        planId: descriptor.planId,
-        descriptorDigest: catalogPublicationDescriptorDigest(descriptor),
+        command: 'catalog:publish:apply',
+        state: 'published',
+        commit: published.expectedCommit,
+        reconciliation,
+        ...receiptBase(context, published, options),
     };
 }
-export async function publishPreparedCatalogPublication(options) {
-    const inspection = await prepareCatalogPublicationInspection({
-        workspaceRoot: options.workspaceRoot,
+export async function runCatalogPublishPlanCommand(options) {
+    const workspace = await resolveCatalogWorkspaceRoot({
+        cwd: options.cwd,
+        ...(options.workspaceRoot === undefined ? {} : { explicitRoot: options.workspaceRoot }),
+        mode: 'existing',
+    });
+    const target = await resolveCatalogPublicationTarget({
+        workspaceRoot: workspace.workspaceRoot,
         remote: options.remote,
-        remoteUrl: options.remoteUrl,
         branch: options.branch,
         env: options.env,
-        failOnUnavailable: true,
+        requireRemote: true,
+    });
+    return prepareCatalogPublicationPlan({
+        workspaceRoot: workspace.workspaceRoot,
+        remote: target.remote,
+        branch: target.branch,
+        env: options.env,
+        workspaceRootResolvedFrom: workspace.workspaceRootResolvedFrom,
+        remoteResolvedFrom: target.remoteResolvedFrom,
+        branchResolvedFrom: target.branchResolvedFrom,
     });
-    try {
-        return await publishCatalogPublicationPreparation({
-            preparation: inspection,
-            descriptor: options.descriptor,
-            snapshotRoot: options.snapshotRoot,
-            beforeRemoteWrite: options.beforeRemoteWrite,
-        });
-    }
-    finally {
-        await disposeCatalogPublicationInspection(inspection);
-    }
 }
-export async function runCatalogPublishCommand(options) {
+export async function runCatalogPublishApplyCommand(options) {
     if (options.json && !options.yes)
-        throw new Error('Catalog publish with --json requires --yes.');
+        throw new Error('Catalog publish apply with --json requires --yes.');
     if (!options.interactive && !options.yes)
-        throw new Error('Non-interactive Catalog publish requires --yes.');
-    if (!/^sha256:[0-9a-f]{64}$/u.test(options.expectedDescriptorDigest ?? '')) {
-        throw new Error('Catalog publish requires --expected-descriptor-digest from a successful publication preflight.');
+        throw new Error('Non-interactive Catalog publish apply requires --yes.');
+    if (!/^sha256:[0-9a-f]{64}$/u.test(options.expectedPlanDigest ?? '')) {
+        throw new Error('Catalog publish apply requires --expected-plan-digest from catalog publish plan.');
     }
     const workspace = await resolveCatalogWorkspaceRoot({
         cwd: options.cwd,
@@ -282,61 +657,43 @@ export async function runCatalogPublishCommand(options) {
         env: options.env,
         requireRemote: true,
     });
-    const inspection = await prepareCatalogPublicationInspection({
-        workspaceRoot: workspace.workspaceRoot,
-        remote: target.remote,
-        branch: target.branch,
-        env: options.env,
-        failOnUnavailable: true,
-    });
-    try {
-        const preparedDescriptorDigest = catalogPublicationDescriptorDigest(inspection.descriptor);
-        if (options.expectedDescriptorDigest !== preparedDescriptorDigest) {
-            throw new Error('Catalog publication descriptor does not match the authorized preflight. Run preflight and authorize the current exact identity.');
-        }
-        if (!(await publicationGitExit(inspection.repoRoot, ['check-ignore', '-q', inspection.attemptPath], inspection.env))) {
-            throw new Error('Catalog publish state under .aw/publish must be ignored by Git. Add .aw/ to .gitignore.');
-        }
-        if (!options.yes) {
-            options.io.stderr([
-                `Workspace identity: ${inspection.descriptor.workspaceIdentity}`,
-                `Source HEAD: ${inspection.sourceHead}`,
-                `Catalog: ${inspection.descriptor.catalogVersion} (${inspection.descriptor.channel})`,
-                `Remote: ${inspection.remote}`,
-                `Fetch URL: ${inspection.safeFetchUrl}`,
-                `Push URL: ${inspection.safePushUrl}`,
-                `Branch: ${inspection.branchRef}`,
-                `Parent: ${inspection.parent ?? '<root>'}`,
-                `Tag: ${inspection.tagRef}`,
-                `Snapshot digest: ${inspection.descriptor.snapshotDigest}`,
-                `Plan ID: ${inspection.descriptor.planId}`,
-                `Descriptor digest: ${preparedDescriptorDigest}`,
-                `Plugins: ${inspection.descriptor.pluginNames.length}`,
-                'One atomic push will publish the branch and annotated tag.',
-            ].join('\n') + '\n');
-            if (!options.confirm || !(await options.confirm('Publish this Catalog snapshot?'))) {
-                options.io.stderr('Catalog publication cancelled.\n');
-                return null;
-            }
-        }
-        return await publishCatalogPublicationPreparation({
-            preparation: inspection,
-            descriptor: inspection.descriptor,
-            snapshotRoot: inspection.prepared.outputRoot,
+    if (!options.yes) {
+        const plan = await prepareCatalogPublicationPlan({
+            workspaceRoot: workspace.workspaceRoot,
+            remote: target.remote,
+            branch: target.branch,
+            env: options.env,
             workspaceRootResolvedFrom: workspace.workspaceRootResolvedFrom,
             remoteResolvedFrom: target.remoteResolvedFrom,
             branchResolvedFrom: target.branchResolvedFrom,
         });
+        options.io.stderr([
+            `Workspace identity: ${plan.workspaceIdentity}`,
+            `Source HEAD: ${plan.sourceHead}`,
+            `Remote: ${plan.remote}`,
+            `Fetch URL: ${plan.fetchUrl}`,
+            `Push URL: ${plan.pushUrl}`,
+            `Branch: refs/heads/${plan.branch}`,
+            `Parent: ${plan.parent ?? '<root>'}`,
+            `Tag: refs/tags/${plan.tag}`,
+            `Snapshot digest: ${plan.snapshotDigest}`,
+            `Expected commit: ${plan.expectedCommit}`,
+            `Plan digest: ${plan.planDigest}`,
+        ].join('\n') + '\n');
+        if (!options.confirm || !(await options.confirm('Apply this Catalog publication plan?'))) {
+            options.io.stderr('Catalog publication cancelled.\n');
+            return null;
+        }
     }
-    catch (error) {
-        const message = (error instanceof Error ? error.message : String(error))
-            .replaceAll(inspection.temporaryRoot, '<temporary Catalog state>')
-            .replaceAll(inspection.fetchUrl, inspection.safeFetchUrl)
-            .replaceAll(inspection.pushUrl, inspection.safePushUrl);
-        throw new Error(message);
-    }
-    finally {
-        await disposeCatalogPublicationInspection(inspection);
-    }
+    return applyCatalogPublicationPlan({
+        workspaceRoot: workspace.workspaceRoot,
+        remote: target.remote,
+        branch: target.branch,
+        expectedPlanDigest: options.expectedPlanDigest,
+        env: options.env,
+        workspaceRootResolvedFrom: workspace.workspaceRootResolvedFrom,
+        remoteResolvedFrom: target.remoteResolvedFrom,
+        branchResolvedFrom: target.branchResolvedFrom,
+    });
 }
 //# sourceMappingURL=catalog-publish.js.map