create-principles-disciple 1.133.13 → 1.134.1

package/codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/codex-adapter",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Codex CLI host adapter for Principles Disciple — implements HostAdapter interface for OpenAI Codex CLI's stdin/stdout JSON hook model (ADR-0020).",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,7 +32,8 @@
   },
   "dependencies": {
     "@principles/core": "file:../core",
-    "@principles/host-runtime": "file:../host-runtime"
+    "@principles/host-runtime": "file:../host-runtime",
+    "@principles/install-layout": "file:../install-layout"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",

package/console/dist/server/routes/update.js

@@ -10,7 +10,9 @@ import { migrateLegacyExtensionBackups, reservePdBackupDestination, resolvePdBac
 import { resolveExtensionsDir, resolveUpdateLayout, resolvePluginDir, resolveCanonicalRuntimeRoot, readCurrentVersion, } from '../utils/installed-layout.js';
 import { ActivationCompatibilityReadModel, isFeatureEnabled } from '@principles/core/runtime-v2';
 import { collectFileDepLinkSpecs } from '../utils/update-links.js';
+import { runPostUpdateCliSmoke } from '../utils/cli-smoke.js';
 import { updateMutationController, LEGACY_MUTATION_AUTHORITY, RELEASE_MANAGER_AUTHORITY, MUTATION_KINDS, } from '../update/mutation-controller.js';
+import { runLegacyJournaledMutation } from '../update/legacy-mutation-journal.js';
 import { loadPdConfig, computeFlagsFromLoadResult } from '../config/pd-config-store.js';
 /**
  * Legacy rule contract preflight (2026-08-19): refuse to swap the runtime
@@ -48,6 +50,10 @@ const WORKSPACE_FILES = ['AGENTS.md', 'SOUL.md', 'USER.md', 'CLAUDE.md'];
 // .node addons locked by the gateway/console processes (EPERM on copyfile),
 // npm symlinks/junctions, and thousands of regenerable files.
 const SKIP_DIRS = new Set(['node_modules']);
+// Full-update backups extend the existing plugin backup with sibling code
+// trees. Dependency directories stay in place (native modules may be loaded).
+const RUNTIME_BACKUP_DIR = '.runtime-components';
+const BACKUP_SKIP_DIRS = new Set(['node_modules', RUNTIME_BACKUP_DIR]);
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -222,6 +228,58 @@ function copyFileTo(src, dest) {
         fs.mkdirSync(dir, { recursive: true });
     fs.copyFileSync(src, dest);
 }
+function runtimeComponents(layout) {
+    return {
+        console: layout.consoleDir,
+        'pd-cli': layout.pdCliDir,
+        'host-runtime': layout.hostRuntimeDir,
+        'install-layout': layout.installLayoutDir,
+        core: layout.coreDir,
+        plugin: layout.pluginDir,
+        'release-manager': layout.releaseManagerDir,
+        ...(layout.codexAdapterDir ? { 'codex-adapter': layout.codexAdapterDir } : {}),
+    };
+}
+/** Resolve a backup entry under the backup root, refusing escapes — the
+ * component names recorded in components.json are untrusted runtime data
+ * (rc-1/rc-2), so every join into the backup tree is boundary-checked. */
+function backupEntryPath(root, name) {
+    const target = path.resolve(root, name);
+    if (target === root || !target.startsWith(root + path.sep)) {
+        throw new Error(`Runtime backup entry "${name}" escapes the backup root`);
+    }
+    return target;
+}
+function backupRuntimeComponents(layout, backupDir) {
+    const root = path.join(backupDir, RUNTIME_BACKUP_DIR);
+    fs.mkdirSync(root, { recursive: true });
+    const present = [];
+    for (const [name, dir] of Object.entries(runtimeComponents(layout))) {
+        if (name === 'plugin' || !fs.existsSync(dir))
+            continue;
+        copyDirRecursive(dir, backupEntryPath(root, name), BACKUP_SKIP_DIRS);
+        present.push(name);
+    }
+    // Written last: a partial backup must never be accepted as recoverable.
+    fs.writeFileSync(path.join(root, 'components.json'), JSON.stringify(present));
+}
+function restoreRuntimeComponents(layout, backupDir) {
+    const root = path.join(backupDir, RUNTIME_BACKUP_DIR);
+    if (!fs.existsSync(root))
+        return false; // Historical plugin-only backup.
+    const present = JSON.parse(fs.readFileSync(path.join(root, 'components.json'), 'utf8'));
+    const components = runtimeComponents(layout);
+    if (!Array.isArray(present) || present.some((name) => typeof name !== 'string' || name === 'plugin' || !Object.hasOwn(components, name)
+        || !fs.existsSync(backupEntryPath(root, name)))) {
+        throw new Error('Runtime backup is incomplete or incompatible with this installation');
+    }
+    for (const [name, dir] of Object.entries(components)) {
+        if (name === 'plugin' || !present.includes(name))
+            continue;
+        copyDirRecursive(backupEntryPath(root, name), dir, BACKUP_SKIP_DIRS);
+    }
+    return true;
+}
 // --- Plugin skill-language preservation (PR #1332 companion) -----------------
 // OpenClaw publishes plugin skills by directory name (first declaration
 // wins, same-name roots only warn — no locale mechanism), so a manifest must
@@ -748,7 +806,11 @@ async function doRollbackUpdate(options, workspaceDir) {
         // dependencies. Instead, overwrite from backup: modified files (dist/,
         // package.json, etc.) get the backup version, while node_modules/console/
         // core/ (not in the backup) are left untouched.
-        copyDirRecursive(backupDir, targetDir);
+        const layout = resolveUpdateLayout();
+        const fullBackup = layout && path.resolve(layout.pluginDir) === path.resolve(targetDir)
+            ? restoreRuntimeComponents(layout, backupDir)
+            : false;
+        copyDirRecursive(backupDir, targetDir, BACKUP_SKIP_DIRS);
         // Keep the OpenClaw extension copy in sync with the restored canonical
         // plugin (CP-5 invariant from the 2026-09-05 investigation): OpenClaw
         // loads ~/.openclaw/extensions/principles-disciple, so a rollback that
@@ -758,9 +820,29 @@ async function doRollbackUpdate(options, workspaceDir) {
         const openClawPluginCopy = path.join(resolveExtensionsDir(), 'principles-disciple');
         let extCopySynced = false;
         if (path.resolve(openClawPluginCopy) !== path.resolve(targetDir) && fs.existsSync(openClawPluginCopy)) {
-            copyDirRecursive(backupDir, openClawPluginCopy);
+            copyDirRecursive(backupDir, openClawPluginCopy, BACKUP_SKIP_DIRS);
             extCopySynced = true;
         }
+        if (fullBackup && layout) {
+            const smoke = runPostUpdateCliSmoke(layout.pdCliDir);
+            if (!smoke.ok) {
+                // rc-9: a failed rollback must be observable in history, like every
+                // other failure path — not just in the HTTP response.
+                appendUpdateHistory(workspaceDir, {
+                    fromVersion: 'rolled-back',
+                    toVersion: readCurrentVersion(targetDir) ?? 'unknown',
+                    success: false,
+                    kind: 'failure',
+                    backupPath: backupDir,
+                });
+                return {
+                    success: false,
+                    message: `Runtime backup restored but pd CLI still fails to start: ${smoke.error}`,
+                    reason: 'rollback_cli_smoke_failed',
+                    nextAction: 'Keep the backup and use the official installer pinned to the previous installer release to repair dependencies before restarting Console.',
+                };
+            }
+        }
         // Record rollback history
         appendUpdateHistory(workspaceDir, {
             fromVersion: 'rolled-back',
@@ -771,9 +853,11 @@ async function doRollbackUpdate(options, workspaceDir) {
         });
         return {
             success: true,
-            message: extCopySynced
-                ? 'Rollback completed successfully (OpenClaw extension copy restored too). Note: only the plugin was rolled back; console/core/host-runtime/pd-cli keep the upgraded version. For a full step-back, re-run the official installer pinned to the older release.'
-                : 'Rollback completed successfully. Note: only the plugin was rolled back; console/core/host-runtime/pd-cli keep the upgraded version. For a full step-back, re-run the official installer pinned to the older release.',
+            message: fullBackup
+                ? 'Runtime components restored and pd CLI startup verified. Restart Console to load the restored code.'
+                : extCopySynced
+                    ? 'Rollback completed successfully (OpenClaw extension copy restored too). Note: only the plugin was rolled back; console/core/host-runtime/pd-cli keep the upgraded version. For a full step-back, re-run the official installer pinned to the older release.'
+                    : 'Rollback completed successfully. Note: only the plugin was rolled back; console/core/host-runtime/pd-cli keep the upgraded version. For a full step-back, re-run the official installer pinned to the older release.',
         };
     }
     catch (error) {
@@ -997,19 +1081,9 @@ function ensureRuntimeResolutionLinks(layout, tempDir) {
     ];
     // Data-driven pass: derive links from the STAGED component manifests (see
     // the comment above — staged, never the deployed pre-update manifests).
-    const stagedComponents = [
-        { manifestDir: path.join(tempDir, 'console'), deployedDir: layout.consoleDir },
-        { manifestDir: path.join(tempDir, 'pd-cli'), deployedDir: layout.pdCliDir },
-        { manifestDir: path.join(tempDir, 'host-runtime'), deployedDir: layout.hostRuntimeDir },
-        { manifestDir: path.join(tempDir, 'install-layout'), deployedDir: layout.installLayoutDir },
-        { manifestDir: path.join(tempDir, 'core'), deployedDir: layout.coreDir },
-        { manifestDir: path.join(tempDir, 'plugin'), deployedDir: layout.pluginDir },
-        // PRI-672: staged release-manager component (npm name
-        // create-principles-disciple). Its staged manifest carries the
-        // file:../install-layout ref, and the staged console's manifest carries
-        // file:../release-manager — both derive their resolution links here.
-        { manifestDir: path.join(tempDir, 'release-manager'), deployedDir: layout.releaseManagerDir },
-    ];
+    const stagedComponents = Object.entries(runtimeComponents(layout)).map(([name, deployedDir]) => ({
+        manifestDir: path.join(tempDir, name), deployedDir,
+    }));
     const readStagedDependencies = (manifestDir) => {
         try {
             const pkgPath = path.join(manifestDir, 'package.json');
@@ -1262,9 +1336,8 @@ async function doInlineFullUpdate(workspaceDir) {
         // 2026-09-05 install/upgrade investigation). The backup excludes
         // node_modules (same SKIP_DIRS contract as /apply), and the backup dir
         // is recorded in update-history (success AND failure) so the rollback
-        // handler can find it. Console self-update owns the console dir backup;
-        // core/host-runtime/pd-cli are plain dist overlays re-fetched on any
-        // next update, so only the version authority (plugin) is backed up.
+        // handler can find it. Include every sibling code tree: a plugin-only
+        // rollback cannot repair a CLI/adapter import failure after an update.
         // R5 (review): reservePdBackupDestination creates the directory BEFORE
         // the copy — a mid-copy failure must not leave backupPath pointing at a
         // partial backup (a later /rollback would happily restore the fragment).
@@ -1275,6 +1348,7 @@ async function doInlineFullUpdate(workspaceDir) {
             const backupDest = reservePdBackupDestination(path.basename(extDir));
             try {
                 copyDirRecursive(extDir, backupDest, SKIP_DIRS);
+                backupRuntimeComponents(layout, backupDest);
             }
             catch (backupError) {
                 try {
@@ -1306,6 +1380,23 @@ async function doInlineFullUpdate(workspaceDir) {
                 fs.existsSync(path.join(releaseManagerSrc, 'dist'))) {
                 copyDirRecursive(releaseManagerSrc, layout.releaseManagerDir, SKIP_DIRS);
             }
+            // PRI-711: same PRI-561 ordering for codex-adapter — pd-cli's eager
+            // import graph statically resolves it, so an updated pd-cli paired with
+            // a stale deployed adapter is exactly the generation drift that bricked
+            // the 1.231.2 update (health-codex imported symbols the deployed
+            // adapter happened to carry; the next API addition would not). The
+            // copy keeps the deployed node_modules (SKIP_DIRS), so its resolution
+            // links survive; the data-driven pass below re-derives them anyway.
+            // Skipped when the running console resolves a one-generation-old
+            // install-layout without codexAdapterDir — that generation also lacks
+            // the derivation entry, mirroring the old no-op behavior (rc-9).
+            const codexAdapterDest = layout.codexAdapterDir;
+            if (codexAdapterDest !== undefined &&
+                fs.existsSync(path.join(tempDir, 'codex-adapter')) &&
+                fs.existsSync(path.join(tempDir, 'codex-adapter', 'package.json')) &&
+                fs.existsSync(path.join(tempDir, 'codex-adapter', 'dist'))) {
+                copyDirRecursive(path.join(tempDir, 'codex-adapter'), codexAdapterDest, SKIP_DIRS);
+            }
             const { error: linkError, quarantined } = ensureRuntimeResolutionLinks(layout, tempDir);
             reconciledQuarantine = quarantined;
             if (linkError) {
@@ -1382,12 +1473,32 @@ async function doInlineFullUpdate(workspaceDir) {
         if (tempDir && fs.existsSync(tempDir)) {
             fs.rmSync(tempDir, { recursive: true, force: true });
         }
-        // 6.5 Discard the quarantined stale dependency copies — the canonical
-        // components are in place now (PRI-665). Both the success return and the
-        // version-drift failure return flow through here with files already
-        // swapped, so restoring the stale copies would re-break resolution.
-        if (reconciledQuarantine.length > 0) {
-            cleanupQuarantined(reconciledQuarantine);
+        // 6.8 PRI-711: post-apply CLI smoke. The swap and link steps above are
+        // data-driven but not self-proving — run the updated CLI once and refuse
+        // to record a success if the eager import graph is broken (see
+        // runPostUpdateCliSmoke for the three precedents this catches). The
+        // backup recorded below keeps the failure recoverable via /rollback.
+        const smoke = runPostUpdateCliSmoke(layout.pdCliDir);
+        if (!smoke.ok) {
+            restoreQuarantined(reconciledQuarantine);
+            reconciledQuarantine = [];
+            const failedVersion = readCurrentVersion(extDir) ?? toVersion ?? 'unknown';
+            appendUpdateHistory(workspaceDir, {
+                fromVersion,
+                toVersion: failedVersion,
+                success: false,
+                kind: 'failure',
+                ...(pluginBackupDir ? { backupPath: pluginBackupDir } : {}),
+            });
+            return {
+                success: false,
+                message: `Update applied but the updated pd CLI fails to start: ${smoke.error}`,
+                reason: 'post_update_cli_smoke_failed',
+                nextAction: pluginBackupDir
+                    ? 'Restore the backup recorded in update history (backupPath), then report the stderr above. The console must be restarted before further use.'
+                    : 'Report the stderr above; no backup was reserved for this update. The console must be restarted before further use.',
+                requiresRestart: false,
+            };
         }
         // 7. Version-advance check (drift guard). The full update installs the
         // plugin bundled inside the installer. If the installer is stale (its
@@ -1399,6 +1510,8 @@ async function doInlineFullUpdate(workspaceDir) {
         const newVersion = readCurrentVersion(extDir) ?? toVersion ?? 'unknown';
         const installedExpectedRelease = newVersion === stagedVersion;
         if (!installedExpectedRelease) {
+            restoreQuarantined(reconciledQuarantine);
+            reconciledQuarantine = [];
             // Files were already rewritten to the same (or lower) version. Record a
             // FAILED history entry so the operator sees why, and return a structured
             // error with nextAction.
@@ -1425,6 +1538,10 @@ async function doInlineFullUpdate(workspaceDir) {
             kind: 'update',
             ...(pluginBackupDir ? { backupPath: pluginBackupDir } : {}),
         });
+        // The quarantined pre-update copies are discarded on success; no reset of
+        // the variable is needed here — the return below cannot re-enter the
+        // catch (CodeQL js/useless-assignment-to-local, PR #1580 review).
+        cleanupQuarantined(reconciledQuarantine);
         return {
             success: true,
             message: depsChanged
@@ -1540,7 +1657,26 @@ function legacyCheckMutation(req, res, ctx) {
         }
     })();
 }
+/**
+ * PRI-709 P0-3 (ADR-0024 D-2): the shared installation root that owns the
+ * transaction journal. Legacy console mutations journal to the SAME place as
+ * the installer and the ReleaseManager — never a console-private ledger.
+ */
+function resolvePdHome() {
+    return path.join(os.homedir(), '.pd');
+}
+/**
+ * A runtime mutation that ran without journal evidence is a governance gap,
+ * not a mutation failure: it is reported loud (rc-9) and the mutation result
+ * is still served. Blocking the Owner's update here would be worse than an
+ * unaudited one — but the gap must never be silent.
+ */
+function logLegacyJournalGap(kind, reason) {
+    console.warn(`[update] Runtime mutation "${kind}" completed WITHOUT journal evidence (${reason}). `
+        + 'ADR-0024 D-2 requires every runtime mutation to be auditable; this is usually a missing create-principles-disciple install surface.');
+}
 function legacyApplyMutation(req, res, ctx) {
+    const pdHome = resolvePdHome();
     return (async () => {
         const pluginDir = resolvePluginDir(ctx.workspaceDir);
         if (req.method !== 'POST') {
@@ -1578,11 +1714,12 @@ function legacyApplyMutation(req, res, ctx) {
                 sendBadRequest(res, 'targetDir must be within workspace or extensions directory');
                 return;
             }
-            const result = await doApplyUpdate({
-                targetDir,
-                mergeStrategy,
-                createBackup,
-            }, ctx.workspaceDir);
+            // ADR-0024 D-2 (PRI-709 P0-3): every runtime mutation is journaled.
+            // `planned` lands after all request validation, so a rejected request
+            // leaves no transaction behind.
+            const { result, journal } = await runLegacyJournaledMutation({ kind: 'apply', pdHome, pluginDir }, () => doApplyUpdate({ targetDir, mergeStrategy, createBackup }, ctx.workspaceDir));
+            if (!journal.journaled)
+                logLegacyJournalGap('apply', journal.reason);
             sendSuccess(res, result);
         }
         catch (err) {
@@ -1595,6 +1732,7 @@ function legacyApplyMutation(req, res, ctx) {
     })();
 }
 function legacyRollbackMutation(req, res, ctx) {
+    const pdHome = resolvePdHome();
     return (async () => {
         const pluginDir = resolvePluginDir(ctx.workspaceDir);
         if (req.method !== 'POST') {
@@ -1626,7 +1764,12 @@ function legacyRollbackMutation(req, res, ctx) {
                 sendBadRequest(res, 'backupDir must be within the workspace, extensions directory, or PD backups directory');
                 return;
             }
-            const result = await doRollbackUpdate({ targetDir, backupDir }, ctx.workspaceDir);
+            // ADR-0024 D-2 (PRI-709 P0-3): a rollback is a forward transition to a
+            // known-good deployment, not an undo of this transaction — that is why
+            // the terminal state is `confirmed`, not `rolled_back`.
+            const { result, journal } = await runLegacyJournaledMutation({ kind: 'rollback', pdHome, pluginDir }, () => doRollbackUpdate({ targetDir, backupDir }, ctx.workspaceDir));
+            if (!journal.journaled)
+                logLegacyJournalGap('rollback', journal.reason);
             sendSuccess(res, result);
         }
         catch (err) {
@@ -1639,13 +1782,17 @@ function legacyRollbackMutation(req, res, ctx) {
     })();
 }
 function legacyApplyFullMutation(req, res, ctx) {
+    const pdHome = resolvePdHome();
     return (async () => {
         if (req.method !== 'POST') {
             sendMethodNotAllowed(res);
             return;
         }
+        const pluginDir = resolvePluginDir(ctx.workspaceDir);
         try {
-            const result = await doInlineFullUpdate(ctx.workspaceDir);
+            const { result, journal } = await runLegacyJournaledMutation({ kind: 'apply-full', pdHome, pluginDir }, () => doInlineFullUpdate(ctx.workspaceDir));
+            if (!journal.journaled)
+                logLegacyJournalGap('apply-full', journal.reason);
             sendSuccess(res, result);
         }
         catch (err) {

package/console/dist/server/update/legacy-mutation-journal.d.ts

@@ -0,0 +1,118 @@
+/**
+ * PRI-709 P0-3 — journal coverage for the legacy console updater (ADR-0024 D-2).
+ *
+ * PRI-698 Phase 0 Audit finding F-3: the console updater performed runtime
+ * mutations with **zero** journal writes. Under ADR-0024 D-2 an unjournaled
+ * runtime mutation is the one thing that must never happen, so the legacy
+ * updater had to be brought under the SAME journal as the installer and the
+ * ReleaseManager before the legacy path can be retired.
+ *
+ * Design rules (all load-bearing):
+ *
+ * - **No new journal implementation.** This module reuses
+ *   `create-principles-disciple`'s `transaction-journal` — one JSONL file per
+ *   transaction under `~/.pd/transactions/`, append + fsync, strict reader.
+ *   Nothing here parses, formats or rotates journals.
+ * - **The ReleaseManager path is never double-journaled.** ReleaseManager
+ *   `apply-full` orchestrates the installer, which journals the whole
+ *   lifecycle; the console dispatch for that path never reaches the legacy
+ *   handlers this module wraps. When the ReleaseManager explicitly falls back
+ *   to legacy, the legacy handler is the ONLY writer — one transaction per
+ *   mutation, whichever authority served it.
+ * - **Explicit degradation, never a blocked mutation.** The journal module is
+ *   loaded dynamically: the console runs in installations where the
+ *   create-principles-disciple dist may be absent (the same delivery-surface
+ *   gap the ReleaseManager authority loader already handles). A missing module
+ *   is reported and the mutation proceeds unjournaled — refusing the Owner's
+ *   update would be worse than an unaudited one, and the gap is observable.
+ * - **No fabricated digests.** The legacy updater does not verify signed
+ *   release metadata, so its digest provenance is `fallback`: a synthetic
+ *   sha256 over a literal marker, readable but explicitly NOT verifiable. It
+ *   never claims `manifest` / `signed_channel` it cannot back.
+ *
+ * Transition strategy for legacy kinds:
+ *
+ *   apply / apply-full / rollback:  `planned` → `confirmed` | `failed`
+ *
+ * `planned` is appended immediately before the mutation (after all request
+ * validation, so rejected requests leave no transaction); `confirmed` or
+ * `failed` after it. `rolled_back` is NOT used for the rollback kind — a
+ * rollback restores a previous deployment and is itself a forward transition
+ * to a known-good state, whereas `rolled_back` means "this transaction was
+ * undone".
+ *
+ * Two documented trade-offs (PRI-709 review, deliberate):
+ *
+ * - **`generation` stays at the standalone default `1`.** Legacy console
+ *   transactions do not participate in the dual-slot generation lineage — they
+ *   never move the active record — so recording a real `active.json.generation
+ *   + 1` would CLAIM a lineage the console does not actually advance. Recovery
+ *   is unaffected either way: `recoverUnfinishedTransaction` keys on
+ *   `activeRecord.transactionId`, which a console transaction never matches, so
+ *   it resolves to "the previously confirmed release stands".
+ * - **The legacy path leaves `active.json` untouched.** The legacy updater
+ *   replaces the runtime without the installer's dual-slot swap, so after a
+ *   legacy `apply-full` the active record describes the PREVIOUS deployment.
+ *   Making the console a second writer of the deployment identity would be a
+ *   worse violation (one source of truth); the honest fix is retiring the
+ *   legacy path (ADR-0024 D-1), which is exactly what this journal coverage
+ *   unblocks.
+ */
+import type { ReleaseMetadataDigestSource, TransactionState } from 'create-principles-disciple/dist/update/transaction-journal.js';
+/** Journal kinds the legacy console updater performs. */
+export type LegacyMutationKind = 'apply' | 'apply-full' | 'rollback';
+export interface LegacyMutationJournal {
+    readonly transactionId: string;
+    readonly journalPath: string;
+    readonly releaseId: string;
+    readonly productVersion: string;
+    readonly releaseMetadataDigest: string;
+}
+export type LegacyJournalStatus = {
+    readonly journaled: true;
+    readonly journal: LegacyMutationJournal;
+} | {
+    readonly journaled: false;
+    readonly reason: string;
+};
+/** Journal port — the real implementation is the shared transaction journal. */
+export interface LegacyJournalPort {
+    appendJournalTransition(journalPath: string, transition: {
+        readonly at: string;
+        readonly from: TransactionState | null;
+        readonly to: TransactionState;
+        readonly transactionId: string;
+        readonly releaseId: string;
+        readonly productVersion: string;
+        readonly releaseMetadataDigest: string;
+        readonly releaseMetadataDigestSource: ReleaseMetadataDigestSource;
+        readonly generation: number;
+        readonly detail?: string;
+    }): void;
+}
+export interface LegacyJournalOptions {
+    /** `~/.pd` — the shared installation root (ADR-0023). */
+    readonly pdHome: string;
+    /** Installed runtime plugin dir; identity source of what is deployed. */
+    readonly pluginDir: string;
+    readonly kind: LegacyMutationKind;
+    readonly now?: () => Date;
+    /** Test seam; defaults to the dynamically imported shared journal. */
+    readonly journal?: LegacyJournalPort;
+}
+/**
+ * Open one legacy transaction and append `planned` before the mutation runs.
+ */
+export declare function openLegacyMutationJournal(options: LegacyJournalOptions): Promise<LegacyJournalStatus>;
+/**
+ * Runs a legacy mutation under one journal transaction.
+ *
+ * `planned` is written before `run()`; `confirmed` / `failed` after — decided
+ * by BOTH the thrown/not-thrown boundary and the updater's `success` result
+ * shape (see `toLegacyMutationOutcome`). A journal failure never changes the
+ * mutation's outcome — it is reported alongside it.
+ */
+export declare function runLegacyJournaledMutation<T>(options: LegacyJournalOptions, run: () => Promise<T>): Promise<{
+    readonly result: T;
+    readonly journal: LegacyJournalStatus;
+}>;