@fuzdev/fuz_gitops 0.72.0 → 0.73.0

package/dist/multi_repo_publisher.js

@@ -2,16 +2,36 @@ import { TaskError } from '@fuzdev/gro';
 import { join } from 'node:path';
 import { styleText as st } from 'node:util';
 import { update_package_json } from './dependency_updater.js';
-import { validate_dependency_graph } from './graph_validation.js';
-import { needs_update, is_breaking_change, detect_bump_type } from './version_utils.js';
+import { generate_publishing_plan, } from './publishing_plan.js';
 import { default_gitops_operations } from './operations_defaults.js';
-import { GITOPS_MAX_ITERATIONS_DEFAULT, GITOPS_NPM_WAIT_TIMEOUT_DEFAULT, } from './gitops_constants.js';
-import { install_with_cache_healing } from './npm_install_helpers.js';
+import { GITOPS_NPM_WAIT_TIMEOUT_DEFAULT } from './gitops_constants.js';
 import { summarize_events, } from './publishing_event.js';
 import { capture_handler, multi_handler, } from './publishing_event_handler.js';
 export const publish_repos = async (repos, options) => {
+    const { log, ops = default_gitops_operations } = options;
+    // Convenience entry: generate the plan, then execute it. Callers that already hold a
+    // plan (e.g. to display and confirm it first) call `execute_publishing_plan` directly,
+    // so the plan is generated exactly once per command.
+    const plan = await generate_publishing_plan(repos, { log, ops: ops.changeset });
+    return execute_publishing_plan(repos, plan, options);
+};
+/**
+ * Executes a frozen publishing plan in a single linear pass — the "dumb executor" half of
+ * the zap model. The plan is the single source of truth; this re-derives nothing.
+ *
+ * Fails loud when the plan couldn't be fully computed (`plan.errors`): a wetrun aborts
+ * before any side effect, a dry run still reports the partial cascade but returns
+ * `ok: false`. This is the single error gate — `--no-plan` can't bypass it.
+ */
+export const execute_publishing_plan = async (repos, plan, options) => {
     const start_time = Date.now();
-    const { wetrun, update_deps, log, ops = default_gitops_operations } = options;
+    const { wetrun, log, ops = default_gitops_operations } = options;
+    // Fail loud on an incomplete plan. Executing one with errors would silently skip the
+    // affected packages. A wetrun aborts before touching npm or git; a dry run proceeds
+    // (no side effects) but the result is not ok (see the summary below).
+    if (wetrun && plan.errors.length > 0) {
+        throw new TaskError(`Cannot publish — the plan has ${plan.errors.length} error(s):\n  ${plan.errors.join('\n  ')}`);
+    }
     // Capture every event for the result; also forward to the caller's sink if provided.
     const capture = capture_handler();
     const events_handler = options.events ? multi_handler([options.events, capture]) : capture;
@@ -40,262 +60,220 @@ export const publish_repos = async (repos, options) => {
     else {
         log?.info('⏭️  Skipping preflight checks (dry run)');
     }
-    // Build dependency graph and validate
-    const { publishing_order: order } = validate_dependency_graph(repos, {
-        log,
-        throw_on_prod_cycles: true,
-        log_cycles: true,
-        log_order: true,
-    });
+    // The plan already validated the dependency graph and resolved the full cascade
+    // (explicit changesets, bump escalations, and auto-generated changesets) — execute its
+    // frozen topological order directly, re-deriving nothing.
+    const order = plan.publishing_order;
+    const plan_changes = new Map(plan.version_changes.map((vc) => [vc.package_name, vc]));
+    if (order.length > 0) {
+        log?.info(`  Publishing order: ${order.join(' → ')}`);
+    }
     emit({ event: 'run_started', wetrun, total: order.length });
     const published = new Map();
     const failed = new Map();
     const changed_repos = new Set(); // Track repos with any changes for selective deployment
-    const skipped_packages = new Set(); // dedupe the package_skipped event across iterations
-    // Fixed-point iteration: keep publishing until no new changesets are created
-    // This handles transitive dependency updates (auto-generated changesets)
-    let iteration = 0;
-    let converged = false;
-    while (!converged && iteration < GITOPS_MAX_ITERATIONS_DEFAULT) {
-        iteration++;
-        emit({ event: 'iteration_started', iteration, max: GITOPS_MAX_ITERATIONS_DEFAULT });
-        log?.info(st('cyan', `\n🚀 ${wetrun ? 'Publishing' : 'Dry run'} iteration ${iteration}/${GITOPS_MAX_ITERATIONS_DEFAULT}...\n`));
-        // Track if any packages were published in this iteration
-        let published_in_iteration = false;
-        let published_count = 0;
-        // Track repos changed in THIS iteration only (for batch install)
-        const changed_in_iteration = new Set();
-        // Phase 1: Publish each package and immediately update dependents
-        for (let i = 0; i < order.length; i++) {
-            const pkg_name = order[i];
-            const repo = repos.find((r) => r.library.name === pkg_name);
-            if (!repo)
-                continue;
-            // Skip if already published in a previous iteration
-            if (published.has(pkg_name)) {
-                continue;
-            }
-            // Check for changesets (both dry and real runs)
-            const has_result = await ops.changeset.has_changesets({ repo });
-            if (!has_result.ok) {
-                // Failed to check changesets
-                const err = new Error(`Failed to check changesets: ${has_result.message}`);
+    // Name → repo index, built once to avoid repeated linear scans of `repos`.
+    const repo_by_name = new Map(repos.map((r) => [r.library.name, r]));
+    log?.info(st('cyan', `\n🚀 ${wetrun ? 'Publishing' : 'Dry run'}...\n`));
+    // Phase 1: one linear pass over the plan's topological order. The plan already
+    // resolved the full cascade, and publishing a package immediately rewrites every
+    // dependent's package.json and creates its auto-changeset — so by the time the pass
+    // reaches any package, all its dependencies have published and its changeset exists.
+    // No fixed-point loop is needed: a single pass converges by construction.
+    for (let i = 0; i < order.length; i++) {
+        const pkg_name = order[i];
+        const planned = plan_changes.get(pkg_name);
+        // Not in the plan = no changesets and no dependency updates = nothing to publish.
+        if (!planned) {
+            emit({ event: 'package_skipped', name: pkg_name, reason: 'no changesets' });
+            log?.info(st('yellow', `  ⚠️  Skipping ${pkg_name} - no changesets`));
+            continue;
+        }
+        const repo = repo_by_name.get(pkg_name);
+        if (!repo)
+            continue;
+        // An earlier publish may have rewritten this package's dependency ranges. No install is
+        // needed here: `gro publish` runs its own install (which self-heals npm's stale-cache
+        // ETARGET), so the package's freshly-rewritten deps are installed and healed as part of
+        // publishing it.
+        try {
+            // 1. Publish this package (real publish or dry-run prediction)
+            log?.info(st('dim', `  [${i + 1}/${order.length}] ${wetrun ? 'Publishing' : 'Would publish'} ${pkg_name}...`));
+            const version = await publish_single_repo(repo, options, ops, planned);
+            // Fail loud on drift: a real publish that lands a version the plan didn't predict
+            // is an invariant violation, not a routine failure. Abort and leave the dirty
+            // state in place — re-running re-plans from the current state (the just-published
+            // package no longer has changesets, so it drops out of the new plan).
+            if (wetrun && version.new_version !== planned.to) {
+                const err = new Error(`Plan drift for ${pkg_name}: published ${version.new_version} but the plan predicted ${planned.to}. ` +
+                    `Aborting — re-run 'gro gitops_publish --wetrun' to re-plan from the current state.`);
                 failed.set(pkg_name, err);
-                emit({ event: 'package_failed', name: pkg_name, error: err.message, code: 'dependency' });
+                emit({ event: 'package_failed', name: pkg_name, error: err.message, code: 'drift' });
                 log?.error(st('red', `  ❌ ${err.message}`));
                 break;
             }
-            if (!has_result.value) {
-                // Skip packages without changesets
-                // In real publish: They might get auto-changesets during dependency updates
-                // In dry run: We can't simulate auto-changesets, so just skip
-                // Emit once per package — the loop revisits no-changeset packages each iteration
-                if (!skipped_packages.has(pkg_name)) {
-                    skipped_packages.add(pkg_name);
-                    emit({ event: 'package_skipped', name: pkg_name, reason: 'no changesets' });
-                }
-                if (!wetrun) {
-                    // Silent skip in dry run - plan shows which packages get auto-changesets
-                    continue;
-                }
-                else {
-                    log?.info(st('yellow', `  ⚠️  Skipping ${pkg_name} - no changesets`));
-                    continue;
-                }
-            }
-            try {
-                // 1. Publish this package
-                log?.info(st('dim', `  [${i + 1}/${order.length}] ${wetrun ? 'Publishing' : 'Would publish'} ${pkg_name}...`));
-                const version = await publish_single_repo(repo, options, ops);
-                published.set(pkg_name, version);
-                changed_repos.add(pkg_name); // Mark as changed for deployment
-                // Note: don't add to changed_in_iteration - published packages don't need install
-                // (their dependencies didn't change, only their version)
-                published_in_iteration = true;
-                published_count++;
-                emit({
-                    event: 'package_completed',
-                    name: pkg_name,
-                    old_version: version.old_version,
-                    new_version: version.new_version,
-                    bump_type: version.bump_type,
-                    breaking: version.breaking,
-                    commit: version.commit,
-                    tag: version.tag,
+            published.set(pkg_name, version);
+            changed_repos.add(pkg_name); // Mark as changed for deployment
+            emit({
+                event: 'package_completed',
+                name: pkg_name,
+                old_version: version.old_version,
+                new_version: version.new_version,
+                bump_type: version.bump_type,
+                breaking: version.breaking,
+                commit: version.commit,
+                tag: version.tag,
+            });
+            log?.info(wetrun
+                ? st('green', `  ✅ Published ${pkg_name}@${version.new_version}`)
+                : st('cyan', `  ◇ Would publish ${pkg_name}@${version.new_version}`));
+            if (wetrun) {
+                // 2. Wait for this package to be available on NPM
+                log?.info(`  ⏳ Waiting for ${pkg_name}@${version.new_version} on NPM...`);
+                const wait_result = await ops.npm.wait_for_package({
+                    pkg: pkg_name,
+                    version: version.new_version,
+                    wait_options: {
+                        max_attempts: 30,
+                        initial_delay: 1000,
+                        max_delay: 60000,
+                        timeout: options.max_wait ?? GITOPS_NPM_WAIT_TIMEOUT_DEFAULT,
+                    },
+                    log,
                 });
-                log?.info(wetrun
-                    ? st('green', `  ✅ Published ${pkg_name}@${version.new_version}`)
-                    : st('cyan', `  ◇ Would publish ${pkg_name}@${version.new_version}`));
-                if (wetrun) {
-                    // 2. Wait for this package to be available on NPM
-                    log?.info(`  ⏳ Waiting for ${pkg_name}@${version.new_version} on NPM...`);
-                    const wait_result = await ops.npm.wait_for_package({
-                        pkg: pkg_name,
-                        version: version.new_version,
-                        wait_options: {
-                            max_attempts: 30,
-                            initial_delay: 1000,
-                            max_delay: 60000,
-                            timeout: options.max_wait ?? GITOPS_NPM_WAIT_TIMEOUT_DEFAULT,
-                        },
-                        log,
-                    });
-                    if (!wait_result.ok) {
-                        // Handle inline (don't throw into the generic catch): the npm-wait failure
-                        // carries a typed `timeout` signal, so we know this is a network failure
-                        // without sniffing the message.
-                        const err = new Error(`Failed to wait for package: ${wait_result.message}${wait_result.timeout ? ' (timeout)' : ''}`);
-                        failed.set(pkg_name, err);
-                        emit({ event: 'package_failed', name: pkg_name, error: err.message, code: 'network' });
-                        log?.error(st('red', `  ❌ Failed to publish ${pkg_name}: ${err.message}`));
-                        break; // fail fast
+                if (!wait_result.ok) {
+                    // Handle inline (don't throw into the generic catch): the npm-wait failure
+                    // carries a typed `timeout` signal, so we know this is a network failure
+                    // without sniffing the message.
+                    const err = new Error(`Failed to wait for package: ${wait_result.message}${wait_result.timeout ? ' (timeout)' : ''}`);
+                    failed.set(pkg_name, err);
+                    emit({ event: 'package_failed', name: pkg_name, error: err.message, code: 'network' });
+                    log?.error(st('red', `  ❌ Failed to publish ${pkg_name}: ${err.message}`));
+                    break; // fail fast
+                }
+                emit({ event: 'npm_waited', name: pkg_name, version: version.new_version });
+                // 3. Update every dependent the plan says has a prod/peer dep on this package.
+                // This rewrites their package.json ranges and creates their auto-changeset,
+                // which a later step of this same pass publishes. The dependent is queued for
+                // a single install just before it publishes (see the top of the loop).
+                const dependent_updates = group_dependency_updates(plan.dependency_updates, published, (update) => update.updated_dependency === pkg_name &&
+                    (update.type === 'dependencies' || update.type === 'peerDependencies'));
+                for (const [dependent_name, updates] of dependent_updates) {
+                    const dependent_repo = repo_by_name.get(dependent_name);
+                    if (!dependent_repo)
+                        continue;
+                    // A dependent republishes iff the plan gave it a version change. Private packages
+                    // are excluded from the plan's version changes, so they take the update-only-leaf
+                    // path: rewrite + commit their dependency ranges with NO changeset and NO
+                    // publish/npm-wait. Publishable dependents get an auto-changeset and republish in
+                    // turn — `gro publish` installs + heals their rewritten deps when it reaches them.
+                    const republishes = plan_changes.has(dependent_name);
+                    for (const [dep_name, dep_version] of updates) {
+                        log?.info(`    Updating ${dependent_name}'s dependency on ${dep_name}`);
+                        emit({
+                            event: 'dependency_updated',
+                            dependent: dependent_name,
+                            dependency: dep_name,
+                            version: dep_version,
+                            dep_type: dependency_update_type(plan, dependent_name, dep_name),
+                            creates_changeset: republishes,
+                        });
+                    }
+                    changed_repos.add(dependent_name); // Mark as changed for deployment
+                    if (republishes) {
+                        await update_package_json(dependent_repo, updates, {
+                            strategy: options.version_strategy || 'caret',
+                            published_versions: published, // creates the auto-changeset
+                            log,
+                            git_ops: ops.git,
+                            fs_ops: ops.fs,
+                        });
                     }
-                    // 3. Update all repos that have prod/peer deps on this package
-                    if (update_deps) {
-                        for (const dependent_repo of repos) {
-                            const updates = new Map();
-                            // Check prod dependencies
-                            if (dependent_repo.dependencies?.has(pkg_name)) {
-                                const current = dependent_repo.dependencies.get(pkg_name);
-                                if (needs_update(current, version.new_version)) {
-                                    updates.set(pkg_name, version.new_version);
-                                }
-                            }
-                            // Check peer dependencies
-                            if (dependent_repo.peer_dependencies?.has(pkg_name)) {
-                                const current = dependent_repo.peer_dependencies.get(pkg_name);
-                                if (needs_update(current, version.new_version)) {
-                                    updates.set(pkg_name, version.new_version);
-                                }
-                            }
-                            // Apply updates if any
-                            if (updates.size > 0) {
-                                log?.info(`    Updating ${dependent_repo.library.name}'s dependency on ${pkg_name}`);
-                                emit({
-                                    event: 'dependency_updated',
-                                    dependent: dependent_repo.library.name,
-                                    dependency: pkg_name,
-                                    version: version.new_version,
-                                });
-                                changed_repos.add(dependent_repo.library.name); // Mark as changed for deployment
-                                changed_in_iteration.add(dependent_repo.library.name); // Track for batch install
-                                await update_package_json(dependent_repo, updates, {
-                                    strategy: options.version_strategy || 'caret',
-                                    published_versions: published,
-                                    log,
-                                    git_ops: ops.git,
-                                });
-                            }
-                        }
+                    else {
+                        // update-only leaf: rewrite ranges + commit, no changeset (it won't republish)
+                        await update_package_json(dependent_repo, updates, {
+                            strategy: options.version_strategy || 'caret',
+                            log,
+                            git_ops: ops.git,
+                            fs_ops: ops.fs,
+                        });
                     }
                 }
             }
-            catch (error) {
-                const err = error instanceof Error ? error : new Error(String(error));
-                failed.set(pkg_name, err);
-                emit({
-                    event: 'package_failed',
-                    name: pkg_name,
-                    error: err.message,
-                    // TODO: emit a precise code once the npm/process ops return typed errors —
-                    // today a publish-step cause lives in unstructured stderr, so use the honest
-                    // coarse bucket rather than guessing 'auth'/'network'/'build' from the message.
-                    code: 'publish',
-                });
-                log?.error(st('red', `  ❌ Failed to publish ${pkg_name}: ${err.message}`));
-                break; // Always fail fast on error
-            }
-        }
-        // Phase 1b: Batch install dependencies for repos with updated package.json
-        // This ensures workspace stays consistent before next iteration
-        if (wetrun && !options.skip_install && changed_in_iteration.size > 0) {
-            log?.info(st('cyan', '\n📦 Installing dependencies for updated repos...\n'));
-            for (const [name, err] of await install_repos(changed_in_iteration, repos, ops, emit, log)) {
-                failed.set(name, err);
-            }
-        }
-        // Log iteration summary
-        if (published_count > 0) {
-            log?.info(st('dim', `\nIteration ${iteration}: ${published_count} package(s) ${wetrun ? 'published' : 'would be published'}\n`));
         }
-        emit({
-            event: 'iteration_finished',
-            iteration,
-            published_count,
-            converged: !published_in_iteration,
-        });
-        // Check for convergence: no packages published in this iteration
-        if (!published_in_iteration) {
-            converged = true;
-            log?.info(st('green', wetrun
-                ? `\n✓ Converged after ${iteration} iteration(s) - no new changesets\n`
-                : `\n✓ Dry run complete after ${iteration} iteration(s)\n`));
-        }
-        else if (iteration === GITOPS_MAX_ITERATIONS_DEFAULT) {
-            // Count packages that still have changesets (not yet published)
-            const pending_count = order.length - published.size;
-            const estimated_iterations = Math.ceil(pending_count / 2); // Rough estimate
-            log?.warn(st('yellow', `\n⚠️  Reached maximum iterations (${GITOPS_MAX_ITERATIONS_DEFAULT}) without full convergence\n` +
-                `    ${pending_count} package(s) may still have changesets to process\n` +
-                `    Estimated ${estimated_iterations} more iteration(s) needed - run 'gro gitops_publish' again\n`));
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            failed.set(pkg_name, err);
+            emit({
+                event: 'package_failed',
+                name: pkg_name,
+                error: err.message,
+                // TODO: emit a precise code once the npm/process ops return typed errors —
+                // today a publish-step cause lives in unstructured stderr, so use the honest
+                // coarse bucket rather than guessing 'auth'/'network'/'build' from the message.
+                code: 'publish',
+            });
+            log?.error(st('red', `  ❌ Failed to publish ${pkg_name}: ${err.message}`));
+            break; // Always fail fast on error
         }
     }
     // Phase 2: Update all dev dependencies (can have cycles)
-    // Dev dep changes require deployment even without version bumps (rebuild needed)
-    const dev_updated_repos = new Set();
-    if (update_deps && published.size > 0 && wetrun) {
-        log?.info(st('cyan', '\n🔄 Updating dev dependencies...\n'));
-        for (const repo of repos) {
-            const dev_updates = new Map();
-            // Check dev dependencies only
-            if (repo.dev_dependencies) {
-                for (const [dep_name, current_version] of repo.dev_dependencies) {
-                    const published_version = published.get(dep_name);
-                    if (published_version && needs_update(current_version, published_version.new_version)) {
-                        dev_updates.set(dep_name, published_version.new_version);
-                    }
-                }
-            }
-            if (dev_updates.size > 0) {
-                log?.info(`  Updating ${dev_updates.size} dev dependencies in ${repo.library.name}`);
-                for (const [dep_name, dep_version] of dev_updates) {
-                    emit({
-                        event: 'dependency_updated',
-                        dependent: repo.library.name,
-                        dependency: dep_name,
-                        version: dep_version,
-                    });
-                }
-                changed_repos.add(repo.library.name); // Mark as changed for deployment
-                dev_updated_repos.add(repo.library.name); // Track for batch install
-                await update_package_json(repo, dev_updates, {
-                    strategy: options.version_strategy || 'caret',
-                    published_versions: published,
-                    log,
-                    git_ops: ops.git,
+    // Dev dep changes require deployment even without version bumps (rebuild needed).
+    // Sourced from the plan's dependency updates so the publisher derives nothing itself.
+    // Only package.json is rewritten + committed here — no install. These repos don't run
+    // `gro publish`; their `node_modules` is refreshed (and ETARGET-healed) by gro the next
+    // time they build/deploy/sync, so the executor never runs a bare `npm install` itself.
+    if (published.size > 0 && wetrun) {
+        const dev_updates_by_repo = group_dependency_updates(plan.dependency_updates, published, (update) => update.type === 'devDependencies');
+        if (dev_updates_by_repo.size > 0) {
+            log?.info(st('cyan', '\n🔄 Updating dev dependencies...\n'));
+        }
+        for (const [repo_name, dev_updates] of dev_updates_by_repo) {
+            const repo = repo_by_name.get(repo_name);
+            if (!repo)
+                continue;
+            log?.info(`  Updating ${dev_updates.size} dev dependencies in ${repo_name}`);
+            for (const [dep_name, dep_version] of dev_updates) {
+                emit({
+                    event: 'dependency_updated',
+                    dependent: repo_name,
+                    dependency: dep_name,
+                    version: dep_version,
+                    dep_type: 'dev',
+                    creates_changeset: false, // dev-dep updates redeploy without republishing
                 });
             }
-        }
-    }
-    // Phase 2b: Install dev dependencies for repos with dev dep updates
-    if (wetrun && !options.skip_install && dev_updated_repos.size > 0) {
-        log?.info(st('cyan', '\n📦 Installing dev dependencies for updated repos...\n'));
-        for (const [name, err] of await install_repos(dev_updated_repos, repos, ops, emit, log)) {
-            failed.set(name, err);
+            changed_repos.add(repo_name); // Mark as changed for deployment
+            // No `published_versions` here on purpose: a dev-dep bump updates and commits
+            // package.json but must NOT generate a changeset — dev-only changes redeploy
+            // (rebuild) without republishing, so they shouldn't bump the next release.
+            await update_package_json(repo, dev_updates, {
+                strategy: options.version_strategy || 'caret',
+                log,
+                git_ops: ops.git,
+                fs_ops: ops.fs,
+            });
         }
     }
     // Phase 3: Deploy repos with changes (optional)
-    // Deploys only repos that were: published, had prod/peer deps updated, or had dev deps updated
+    // Deploys only repos that were: published, had prod/peer deps updated, or had dev deps updated.
+    // Iterate `changed_repos` (insertion order) rather than `repos` order so deploys run in
+    // dependency order — and so the `--preview` side-effect list matches this exactly.
     if (options.deploy && wetrun) {
-        const repos_to_deploy = repos.filter((r) => changed_repos.has(r.library.name));
+        const repos_to_deploy = Array.from(changed_repos)
+            .map((name) => repo_by_name.get(name))
+            .filter((r) => r !== undefined);
         log?.info(st('cyan', `\n🚢 Deploying ${repos_to_deploy.length}/${repos.length} repos with changes...\n`));
         for (const repo of repos_to_deploy) {
             try {
                 emit({ event: 'deploy_started', name: repo.library.name });
                 log?.info(`  Deploying ${repo.library.name}...`);
+                // Build fresh (no --no-build): a deployed site bundles its dependencies, so it
+                // must be rebuilt against the versions this run just published — the preflight
+                // build ran against the old versions, before the cascade rewrote package.json.
                 const deploy_result = await ops.process.spawn({
                     cmd: 'gro',
-                    args: ['deploy', '--no-build'],
+                    args: ['deploy'],
                     cwd: repo.repo_dir,
                 });
                 if (deploy_result.ok) {
@@ -316,7 +294,7 @@ export const publish_repos = async (repos, options) => {
     }
     // Summary
     const duration = Date.now() - start_time;
-    const ok = failed.size === 0;
+    const ok = failed.size === 0 && plan.errors.length === 0;
     const summary = summarize_events(capture.events, duration);
     log?.info(st('cyan', `\n📋 ${wetrun ? 'Publishing' : 'Dry Run'} Summary\n`));
     log?.info(`  Duration: ${(duration / 1000).toFixed(1)}s`);
@@ -324,10 +302,29 @@ export const publish_repos = async (repos, options) => {
     if (failed.size > 0) {
         log?.info(`  Failed: ${failed.size} packages`);
     }
+    // Surface plan diagnostics (a wetrun with errors threw above; this is mainly the dry run
+    // and non-blocking warnings) so an audit of the cascade sees them.
+    if (plan.warnings.length > 0) {
+        log?.warn(st('yellow', `  ⚠️  Plan warnings: ${plan.warnings.length}`));
+        for (const warning of plan.warnings)
+            log?.warn(st('yellow', `     - ${warning}`));
+    }
+    if (plan.errors.length > 0) {
+        log?.error(st('red', `  ❌ Plan errors: ${plan.errors.length}`));
+        for (const plan_error of plan.errors)
+            log?.error(st('red', `     - ${plan_error}`));
+    }
     if (ok) {
-        log?.info(st('green', wetrun
-            ? '\n✨ All packages published successfully!\n'
-            : `\n✨ Dry run complete — ${published.size} package(s) would be published. Re-run with --wetrun to publish.\n`));
+        if (wetrun) {
+            log?.info(st('green', '\n✨ All packages published successfully!\n'));
+        }
+        else {
+            log?.info(st('green', `\n✨ Dry run complete — ${published.size} package(s) would be published. Re-run with --wetrun to publish.`));
+            // The dry run is driven by the same plan as `gro gitops_plan`, so this
+            // count includes bump escalations and auto-generated changesets — it
+            // matches `gro gitops_plan` exactly (the full cascade).
+            log?.info(st('dim', 'This matches `gro gitops_plan` (the full cascade).\n'));
+        }
     }
     else {
         log?.error(st('red', wetrun
@@ -342,41 +339,34 @@ export const publish_repos = async (repos, options) => {
         duration,
         events: capture.events,
         summary,
+        plan_errors: plan.errors,
+        plan_warnings: plan.warnings,
     };
 };
 /**
  * Publishes a single repo using `gro publish`.
  *
- * Dry run mode: Predicts version from changesets without side effects.
- * Real mode: Runs `gro publish --no-build` (builds already validated in preflight),
- * reads new version from `package.json`, and returns metadata.
+ * Dry run mode: reports the precomputed plan entry without side effects.
+ * Real mode: runs `gro publish --no-build` (builds already validated in preflight),
+ * reads the new version from `package.json`, and returns it alongside the plan's
+ * predicted bump metadata. The caller compares the read-back version to the plan to
+ * detect drift.
  *
- * @throws {Error} if changeset prediction fails (dry run) or publish fails (real)
+ * @throws {Error} if the publish, version read-back, or commit-hash lookup fails
  */
-const publish_single_repo = async (repo, options, ops = default_gitops_operations) => {
-    const { wetrun, log } = options;
-    const old_version = repo.library.package_json.version || '0.0.0';
+const publish_single_repo = async (repo, options, ops, planned) => {
+    const { wetrun } = options;
     if (!wetrun) {
-        // In dry run, predict version from changesets
-        const prediction = await ops.changeset.predict_next_version({ repo, log });
-        if (!prediction) {
-            // No changesets found, skip this repo
-            throw new Error(`No changesets found for ${repo.library.name}`);
-        }
-        if (!prediction.ok) {
-            // Error reading changesets
-            throw new Error(`Failed to predict version: ${prediction.message}`);
-        }
-        const { version: new_version, bump_type } = prediction;
-        const breaking = is_breaking_change(old_version, bump_type);
+        // Dry run reports the precomputed plan — the single source of truth for the
+        // cascade (explicit changesets, bump escalations, and auto-generated changesets).
         return {
             name: repo.library.name,
-            old_version,
-            new_version,
-            bump_type,
-            breaking,
+            old_version: planned.from,
+            new_version: planned.to,
+            bump_type: planned.bump_type,
+            breaking: planned.breaking,
             commit: 'simulated',
-            tag: `v${new_version}`,
+            tag: `v${planned.to}`,
         };
     }
     // Run gro publish with --no-build (builds were validated in preflight checks)
@@ -396,50 +386,52 @@ const publish_single_repo = async (repo, options, ops = default_gitops_operation
     }
     const package_json = JSON.parse(content_result.value);
     const new_version = package_json.version;
-    // Determine bump type and if it's breaking
-    const bump_type = detect_bump_type(old_version, new_version);
-    const breaking = is_breaking_change(old_version, bump_type);
     // Get actual commit hash
     const commit_result = await ops.git.current_commit_hash({ cwd: repo.repo_dir });
     if (!commit_result.ok) {
         throw new Error(`Failed to get commit hash: ${commit_result.message}`);
     }
     const commit = commit_result.value;
+    // Bump metadata comes from the plan (the single source of truth); the caller
+    // fail-louds if `new_version` diverges from the plan's prediction.
     return {
         name: repo.library.name,
-        old_version,
+        old_version: planned.from,
         new_version,
-        bump_type,
-        breaking,
+        bump_type: planned.bump_type,
+        breaking: planned.breaking,
         commit,
         tag: `v${new_version}`,
     };
 };
 /**
- * Installs dependencies for each named repo (with cache healing), emitting install
- * events and logging progress. A failed install doesn't stop the batch — failures are
- * collected and returned so the caller can fold them into the run's failures.
+ * Groups dependency updates by dependent package — `dependent → (dependency → new
+ * version)`, the shape `update_package_json` consumes. Restricted by `predicate` (e.g.
+ * prod/peer for a given package, or all dev deps) and to dependencies that actually
+ * published this run, so a failed/aborted publish never propagates to its dependents.
  */
-const install_repos = async (names, repos, ops, emit, log) => {
-    const failures = new Map();
-    for (const name of names) {
-        const repo = repos.find((r) => r.library.name === name);
-        if (!repo)
+export const group_dependency_updates = (updates, published, predicate) => {
+    const by_repo = new Map();
+    for (const update of updates) {
+        if (!predicate(update))
             continue;
-        try {
-            emit({ event: 'install_started', name });
-            log?.info(`  Installing ${name}...`);
-            await install_with_cache_healing(repo, ops, log);
-            emit({ event: 'install_completed', name });
-            log?.info(st('green', `  ✅ Installed ${name}`));
-        }
-        catch (error) {
-            const err = error instanceof Error ? error : new Error(String(error));
-            failures.set(name, err);
-            emit({ event: 'install_failed', name, error: err.message });
-            log?.error(st('red', `  ❌ Failed to install ${name}: ${err.message}`));
-            // continue with other installs instead of breaking
+        const published_dep = published.get(update.updated_dependency);
+        if (!published_dep)
+            continue;
+        let repo_updates = by_repo.get(update.dependent_package);
+        if (!repo_updates) {
+            repo_updates = new Map();
+            by_repo.set(update.dependent_package, repo_updates);
         }
+        repo_updates.set(update.updated_dependency, published_dep.new_version);
     }
-    return failures;
+    return by_repo;
 };
+/** The dep_type tag for a prod/peer dependency-update event — `peer` if the edge is a peer
+ * dependency, else `prod`. Mirrors `derive_publish_steps`' classification so the executor's
+ * event stream and the preview agree. */
+const dependency_update_type = (plan, dependent, dependency) => plan.dependency_updates.some((u) => u.dependent_package === dependent &&
+    u.updated_dependency === dependency &&
+    u.type === 'peerDependencies')
+    ? 'peer'
+    : 'prod';