create-principles-disciple 1.132.5 → 1.133.0

package/dist/update/release-manager-authority.js

@@ -31,14 +31,28 @@
  * activation rollout opens the `shadow_mode_read_only` gate (its own go/no-go);
  * until then these kinds explicitly fall back to the legacy console updater —
  * TEMPORARY migration debt per ADR-0024 D-1, not a supported long-term state.
+ *
+ * PRI-698 Phase 1: `apply-full` (full-runtime update) is served by the real
+ * ReleaseManager.apply() orchestration (installer + journal) and reports the
+ * same base readiness as `check`. The CONSOLE additionally gates the routing
+ * behind the `release_manager_write_authority` flag (default off) — flag-off
+ * dispatches fall back explicitly with `release_manager_write_disabled`.
+ * `apply` (the plugin-diff mechanism, which the ReleaseManager does not
+ * implement) and `rollback` (Phase 2 — must prove same-version restore first)
+ * stay structurally not-ready with explicit reasons.
  */
 import * as fs from 'node:fs';
 import { ReleaseManager, ReleaseManagerError, } from './release-manager.js';
 import { InstallLayoutError, resolvePdHomePaths } from './install-layout.js';
 /** Mutation kinds the console MutationController routes (PRI-659 contract). */
 export const RELEASE_MANAGER_AUTHORITY_KINDS = ['check', 'apply', 'apply-full', 'rollback'];
-/** Structural gate: activation/rollback arrive with the Phase 4 transaction rollout. */
-const ACTIVATION_AVAILABLE = false;
+/**
+ * Structural gate for the kinds whose write path does not exist yet:
+ * `rollback` arrives with the Phase 2 restore migration; `apply` (plugin
+ * diff) is not a ReleaseManager mechanism at all. `apply-full` left this
+ * gate in PRI-698 Phase 1.
+ */
+const ROLLBACK_AVAILABLE = false;
 /**
  * Probe the transactions directory WITHOUT writing: an existing directory must
  * be writable (the journal is a mandatory mutation contract, ADR-0024 D-2), a
@@ -95,15 +109,18 @@ export function createReleaseManagerAuthority(options) {
         },
         apply: {
             ready: false,
-            reasons: ACTIVATION_AVAILABLE ? baseReasons : [...baseReasons, 'rollback_not_available'],
+            reasons: ROLLBACK_AVAILABLE ? baseReasons : [...baseReasons, 'rollback_not_available'],
         },
+        // PRI-698 Phase 1: the full-runtime write path exists (ReleaseManager.apply
+        // → installer → journal). Console routing is additionally flag-gated
+        // (`release_manager_write_authority`, default off).
         'apply-full': {
-            ready: false,
-            reasons: ACTIVATION_AVAILABLE ? baseReasons : [...baseReasons, 'rollback_not_available'],
+            ready: baseReady,
+            reasons: baseReasons,
         },
         rollback: {
             ready: false,
-            reasons: ACTIVATION_AVAILABLE ? baseReasons : [...baseReasons, 'rollback_not_available'],
+            reasons: ROLLBACK_AVAILABLE ? baseReasons : [...baseReasons, 'rollback_not_available'],
         },
     };
     return { manager, installStatus, kinds };
@@ -111,15 +128,26 @@ export function createReleaseManagerAuthority(options) {
 /**
  * Map a ReleaseManager refusal onto the console's explicit-fallback reason
  * vocabulary (rc-9: degradation must be observable with a stable reason).
+ * `transactionOpened` passes through the PRI-698 default-on safety net
+ * semantics: false ⇒ the refusal happened before any side effect, so the
+ * console may fall back to the legacy updater with an explicit reason; true
+ * ⇒ runtime-side effects may exist and the refusal must surface as a
+ * failure, never as a fallback.
  */
 export function mapReleaseManagerErrorToFallback(error) {
     if (error instanceof ReleaseManagerError) {
-        return { reason: error.reason, message: error.message, nextAction: error.nextAction };
+        return {
+            reason: error.reason,
+            message: error.message,
+            nextAction: error.nextAction,
+            transactionOpened: error.transactionOpened,
+        };
     }
     return {
         reason: 'release_manager_check_failed',
         message: error instanceof Error ? error.message : String(error),
         nextAction: null,
+        transactionOpened: false,
     };
 }
 //# sourceMappingURL=release-manager-authority.js.map

package/dist/update/release-manager-authority.js.map

@@ -1 +1 @@
-{"version":3,"file":"release-manager-authority.js","sourceRoot":"","sources":["../../src/update/release-manager-authority.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"release-manager-authority.js","sourceRoot":"","sources":["../../src/update/release-manager-authority.ts"],"names":[],"mappings":"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"}

package/dist/update/release-manager.d.ts

@@ -3,9 +3,18 @@
  *
  * External surface is intentionally small: inspect / check / apply /
  * rollback. The module hides metadata validation, download, extraction,
- * staging, probes, journaling, host control, rollback, and cleanup. In this
- * phase (shadow mode) apply/rollback refuse read-only: activation lands with
- * the transaction state machine, never by loosening this gate.
+ * staging, probes, journaling, host control, rollback, and cleanup.
+ *
+ * PRI-698 Phase 1: `apply()` is the update ORCHESTRATOR. It acquires the
+ * signed release payload into the staging area (apply-payload.ts) and hands
+ * deployment to the installer — the only direct artifact deployment authority
+ * (ADR-0024 §2.1) — as ONE journaled transaction (planned → downloaded →
+ * verified by this module; staged → probed → activated → confirmed by the
+ * installer's existing cycle, same journal file). This module performs ZERO
+ * deployment-side filesystem mutation: no writes under `~/.pd/runtime` or the
+ * host extension directories ever originate here. `rollback()` still refuses:
+ * rollback migration is Phase 2 and must prove same-version restore before it
+ * replaces the legacy rollback.
  *
  * Every refusal carries a stable reason and an Owner-visible next action
  * (rc-9) and is computed BEFORE any installation state is mutated.
@@ -13,12 +22,23 @@
 import { resolveTrustedReleaseTarget, type TrustedReleaseTarget } from './trust-metadata.js';
 import { buildReleaseMetadata } from './release-metadata.js';
 import { type ReleasePolicyDecision } from './release-policy.js';
+import type { Language } from '../i18n.js';
+import type { HostTarget } from '../installers/index.js';
 import type { ReleaseChannelName } from './product-identity.js';
-export type ReleaseManagerReason = 'shadow_mode_read_only' | 'bootstrap_not_installed' | 'metadata_refresh_failed' | 'release_metadata_unavailable' | 'release_metadata_invalid' | 'active_record_corrupt';
+export type ReleaseManagerReason = 'shadow_mode_read_only' | 'bootstrap_not_installed' | 'metadata_refresh_failed' | 'release_metadata_unavailable' | 'release_metadata_invalid' | 'active_record_corrupt' | 'legacy_layout_not_supported' | 'journal_unavailable' | 'apply_failed';
 export declare class ReleaseManagerError extends Error {
     readonly reason: ReleaseManagerReason;
     readonly nextAction: string;
-    constructor(reason: ReleaseManagerReason, message: string, nextAction: string);
+    /**
+     * PRI-698 Phase 1 default-on safety net: true when the refusal happened
+     * AFTER the apply transaction was opened (planned journaled) — runtime
+     * state may include staging writes and a terminal journal tail. False for
+     * pre-transaction refusals (layout, metadata, journal-unavailable): the
+     * caller can safely fall back to the legacy updater with an explicit
+     * reason, because zero side effects exist.
+     */
+    readonly transactionOpened: boolean;
+    constructor(reason: ReleaseManagerReason, message: string, nextAction: string, transactionOpened?: boolean);
 }
 export type InstallationLayout = 'dual-slot' | 'legacy-overlay' | 'none';
 export interface InstallStatus {
@@ -55,6 +75,25 @@ export interface UpdateCheck {
         readonly note: string | null;
     };
 }
+/** Caller-supplied deployment context for apply() (PRI-698 Phase 1). */
+export interface ApplyOptions {
+    /** Workspace the installer re-run operates on (console passes its own). */
+    readonly workspaceDir: string;
+    /** Installer language; defaults to 'zh' (the installer's default locale). */
+    readonly language?: Language;
+    /** Host installers to run; defaults to 'openclaw' (matches the legacy full-update sync). */
+    readonly host?: HostTarget;
+}
+export type ApplyOutcome = {
+    readonly kind: 'applied';
+    readonly productVersion: string;
+    readonly transactionId: string;
+    readonly journalPath: string;
+} | {
+    readonly kind: 'no_update';
+    /** Why nothing was applied (policy refusal reason or already-current note). */
+    readonly note: string;
+};
 export interface ReleaseManagerOptions {
     readonly pdHome: string;
     readonly metadataBaseUrl: string;
@@ -83,8 +122,37 @@ export declare class ReleaseManager {
     constructor(options: ReleaseManagerOptions);
     inspect(): InstallStatus;
     check(channel: ReleaseChannelName): Promise<UpdateCheck>;
-    apply(): Promise<never>;
+    /**
+     * PRI-698 Phase 1: the update orchestrator. Readiness → signed candidate
+     * resolution → payload acquisition into staging (journaled) → deployment
+     * through the installer (the only direct artifact deployment authority,
+     * ADR-0024 §2.1) as ONE transaction. Every failure leaves the runtime on
+     * the previous release and the journal at a terminal state.
+     */
+    apply(options: ApplyOptions): Promise<ApplyOutcome>;
     rollback(): Promise<never>;
+    /**
+     * Resolve + digest-verify + cache the signed channel document (shared by
+     * check() and apply(); writes stay inside the RM-owned channels cache).
+     */
+    private refreshSignedChannel;
+    /**
+     * evaluateReleaseAdvancement with the ACTIVE release's own metadata as the
+     * current state when a dual-slot installation records one (shared by
+     * check() and apply()).
+     */
+    private evaluateCandidateDecision;
+    /**
+     * The release metadata document names the bytes to deploy. check() only
+     * evaluates already-cached documents; apply() is the "transactional updater"
+     * that finally downloads it: TUF target `releases/<releaseId>/metadata.json`
+     * (Phase 1 convention, custom identity {releaseId, channel, platform:
+     * 'metadata'}) fetched digest-verified into the releases cache, then read
+     * back through the SAME strict validation path (identity + expiry + channel
+     * digest binding). A pre-seeded local document is still accepted unchanged,
+     * so check()-time behavior is untouched.
+     */
+    private ensureReleaseMetadataDocument;
     private legacyOverlayMarker;
     private readChannelMetadataPayload;
     private readActiveReleaseMetadata;

package/dist/update/release-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"release-manager.d.ts","sourceRoot":"","sources":["../../src/update/release-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"release-manager.d.ts","sourceRoot":"","sources":["../../src/update/release-manager.ts"],"names":[],"mappings":"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"}

package/dist/update/release-manager.js

@@ -3,13 +3,23 @@
  *
  * External surface is intentionally small: inspect / check / apply /
  * rollback. The module hides metadata validation, download, extraction,
- * staging, probes, journaling, host control, rollback, and cleanup. In this
- * phase (shadow mode) apply/rollback refuse read-only: activation lands with
- * the transaction state machine, never by loosening this gate.
+ * staging, probes, journaling, host control, rollback, and cleanup.
+ *
+ * PRI-698 Phase 1: `apply()` is the update ORCHESTRATOR. It acquires the
+ * signed release payload into the staging area (apply-payload.ts) and hands
+ * deployment to the installer — the only direct artifact deployment authority
+ * (ADR-0024 §2.1) — as ONE journaled transaction (planned → downloaded →
+ * verified by this module; staged → probed → activated → confirmed by the
+ * installer's existing cycle, same journal file). This module performs ZERO
+ * deployment-side filesystem mutation: no writes under `~/.pd/runtime` or the
+ * host extension directories ever originate here. `rollback()` still refuses:
+ * rollback migration is Phase 2 and must prove same-version restore before it
+ * replaces the legacy rollback.
  *
  * Every refusal carries a stable reason and an Owner-visible next action
  * (rc-9) and is computed BEFORE any installation state is mutated.
  */
+import { randomUUID } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -18,16 +28,89 @@ import { parseChannelMetadata } from './channel-metadata.js';
 import { buildReleaseMetadata, isReleaseMetadataExpired, parseReleaseMetadata, verifyReleaseMetadataIdentity, } from './release-metadata.js';
 import { evaluateReleaseAdvancement, } from './release-policy.js';
 import { readBootstrapManifest, readInstallConfig, resolvePdHomePaths, } from './install-layout.js';
-import { readActiveRecord, TransactionJournalError } from './transaction-journal.js';
+import { appendJournalTransition, readActiveRecord, TransactionJournalError, } from './transaction-journal.js';
+import { downloadReleaseAsset, extractAndVerifyReleaseAsset, ApplyPayloadError } from './apply-payload.js';
 export class ReleaseManagerError extends Error {
     reason;
     nextAction;
-    constructor(reason, message, nextAction) {
+    /**
+     * PRI-698 Phase 1 default-on safety net: true when the refusal happened
+     * AFTER the apply transaction was opened (planned journaled) — runtime
+     * state may include staging writes and a terminal journal tail. False for
+     * pre-transaction refusals (layout, metadata, journal-unavailable): the
+     * caller can safely fall back to the legacy updater with an explicit
+     * reason, because zero side effects exist.
+     */
+    transactionOpened;
+    // eslint-disable-next-line @typescript-eslint/max-params -- (reason, message, nextAction, transactionOpened) mirrors the four fields of the refusal contract; the 4th is an optional PRI-698 default-on safety-net marker
+    constructor(reason, message, nextAction, transactionOpened = false) {
         super(message);
         this.name = 'ReleaseManagerError';
         this.reason = reason;
         this.nextAction = nextAction;
+        this.transactionOpened = transactionOpened;
+    }
+}
+/** Terminal journal states (mirrors transaction-journal.ts TERMINAL_STATES semantics). */
+const APPLY_TERMINAL_STATES = new Set([
+    'confirmed', 'rolled_back', 'refused', 'failed',
+]);
+/**
+ * Append one transition to the apply transaction's journal file (journal-first
+ * append+fsync, same discipline and format as the installer's writer — one
+ * JSONL file per transaction under ~/.pd/transactions/, ADR-0024 D-2/D-6).
+ * The installer continues THIS file when it takes over deployment.
+ */
+function appendApplyTransition(journal, to, detail) {
+    appendJournalTransition(journal.journalPath, {
+        at: new Date().toISOString(),
+        from: journal.lastState,
+        to,
+        transactionId: journal.transactionId,
+        releaseId: journal.releaseId,
+        productVersion: journal.productVersion,
+        releaseMetadataDigest: journal.releaseMetadataDigest,
+        releaseMetadataDigestSource: journal.releaseMetadataDigestSource,
+        generation: journal.generation,
+        detail,
+    });
+    journal.lastState = to;
+}
+/**
+ * Close the apply transaction with a terminal `failed` state when the flow
+ * dies before the installer reached one. The installer's own catch path
+ * appends rolled_back/failed for failures inside deployment; this covers
+ * acquisition-phase failures and unexpected throws so a journal never ends
+ * mid-chain (the strict reader rejects transitions after a terminal state,
+ * and a non-terminal tail means "unfinished" for Phase 3 recovery).
+ * The append itself is best-effort: if even the failure record cannot be
+ * written, the on-disk journal stays where it stopped and the thrown error
+ * still reports the failure (observable degradation, rc-9).
+ */
+function ensureTerminalFailed(journal, detail) {
+    if (journal.lastState !== null && APPLY_TERMINAL_STATES.has(journal.lastState))
+        return;
+    try {
+        appendApplyTransition(journal, 'failed', detail);
+    }
+    catch (appendError) {
+        // Tier-2 degradation (same policy as installer.ts): the transaction stays
+        // partially journaled; the backup/restore safety net inside the installer
+        // does not depend on the journal.
+        void appendError;
+    }
+}
+function toReleaseManagerError(error) {
+    if (error instanceof ReleaseManagerError)
+        return error;
+    if (error instanceof ApplyPayloadError) {
+        return new ReleaseManagerError(error.reason, error.message, error.nextAction);
     }
+    if (error instanceof ReleaseTrustError) {
+        return new ReleaseManagerError('metadata_refresh_failed', error.message, error.nextAction);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return new ReleaseManagerError('apply_failed', `Release application failed: ${message}`, 'The runtime was left on the previous release (installer backup/restore). Retry the update; if it fails again, run the official installer to repair.');
 }
 /**
  * Single authority for active.json: the transaction journal's strict reader
@@ -97,6 +180,150 @@ export class ReleaseManager {
     async check(channel) {
         const now = this.options.now ?? (() => new Date());
         const status = this.inspect();
+        const { channelMetadata, trustedTarget } = await this.refreshSignedChannel(channel);
+        const releaseMetadata = this.readReleaseMetadataDocument(channelMetadata, now);
+        const decision = this.evaluateCandidateDecision({ channelMetadata, releaseMetadata, status, now: now() });
+        const candidate = {
+            productVersion: releaseMetadata.productVersion,
+            releaseId: releaseMetadata.releaseId,
+            publicationSequence: releaseMetadata.publicationSequence,
+            assets: releaseMetadata.assets.map((asset) => ({
+                platform: asset.platform,
+                arch: asset.arch,
+                nodeAbi: asset.nodeAbi,
+            })),
+        };
+        const shadowComparison = await this.compareWithLegacyUpdater(status, decision, candidate.productVersion);
+        return {
+            channel,
+            candidate,
+            decision,
+            trustedTarget,
+            shadowComparison,
+        };
+    }
+    /**
+     * PRI-698 Phase 1: the update orchestrator. Readiness → signed candidate
+     * resolution → payload acquisition into staging (journaled) → deployment
+     * through the installer (the only direct artifact deployment authority,
+     * ADR-0024 §2.1) as ONE transaction. Every failure leaves the runtime on
+     * the previous release and the journal at a terminal state.
+     */
+    async apply(options) {
+        const status = this.inspect();
+        if (status.layout === 'none') {
+            throw new ReleaseManagerError('bootstrap_not_installed', 'No PD installation was found under this PD home; there is nothing to update.', 'Run the official installer (npx create-principles-disciple) first.');
+        }
+        if (status.layout === 'legacy-overlay') {
+            throw new ReleaseManagerError('legacy_layout_not_supported', 'This installation uses the legacy overlay layout, which the transactional updater does not serve.', 'Run the official installer once to migrate into the dual-slot layout; the current updater continues to serve this installation until then.');
+        }
+        // Pre-transaction resolution phase: no side effects have happened, so any
+        // refusal here is a clean, unjournaled refusal — still mapped onto the
+        // typed ReleaseManagerError contract (rc-9), never a raw transport error.
+        let channelMetadata;
+        let releaseMetadata;
+        try {
+            const { channelMetadata: refreshedChannel } = await this.refreshSignedChannel(status.channel);
+            channelMetadata = refreshedChannel;
+            releaseMetadata = await this.ensureReleaseMetadataDocument(channelMetadata);
+        }
+        catch (error) {
+            throw toReleaseManagerError(error);
+        }
+        const now = this.options.now ?? (() => new Date());
+        const decision = this.evaluateCandidateDecision({ channelMetadata, releaseMetadata, status, now: now() });
+        if (!decision.allowed) {
+            return { kind: 'no_update', note: `${decision.reason}: ${decision.message}` };
+        }
+        const transactionId = `update-${Date.now()}-${randomUUID().slice(0, 8)}`;
+        const journalPath = path.join(this.paths.transactionsDir, `${transactionId}.jsonl`);
+        const journal = {
+            transactionId,
+            journalPath,
+            releaseId: releaseMetadata.releaseId,
+            productVersion: releaseMetadata.productVersion,
+            releaseMetadataDigest: releaseMetadata.metadataDigest,
+            releaseMetadataDigestSource: 'signed_channel',
+            generation: (status.generation ?? 0) + 1,
+            degraded: false,
+            lastState: null,
+        };
+        // Journal-first (ADR-0024 D-2, installer Tier-1 policy): record the
+        // transaction BEFORE the first side effect. If even 'planned' cannot be
+        // written, refuse with zero side effects.
+        try {
+            appendApplyTransition(journal, 'planned', `host=${options.host ?? 'openclaw'} mode=smart source=release-manager`);
+        }
+        catch (error) {
+            throw new ReleaseManagerError('journal_unavailable', `The transaction journal could not be written — refusing to update unjournaled (ADR-0024 D-2): ${error instanceof Error ? error.message : String(error)}`, 'Resolve write access to ~/.pd/transactions (disk space / permissions), then retry. No changes were made.');
+        }
+        try {
+            const { install } = await import('../installer.js');
+            const downloaded = await downloadReleaseAsset({
+                paths: this.paths,
+                metadataBaseUrl: this.options.metadataBaseUrl,
+                fetcher: this.options.fetcher,
+                releaseMetadata,
+                channel: status.channel,
+                transactionId,
+            });
+            appendApplyTransition(journal, 'downloaded', `artifact sha256=${downloaded.trustedTarget.artifactSha256} target=${downloaded.trustedTarget.targetPath}`);
+            const { payloadDir } = await extractAndVerifyReleaseAsset({
+                transactionDir: downloaded.transactionDir,
+                archivePath: downloaded.archivePath,
+            });
+            appendApplyTransition(journal, 'verified', 'release-asset preflight passed (identity + whole-payload digest)');
+            // Deployment is the installer's job, byte for byte the same cycle a
+            // manual run performs: digest preflight → backup rename-swap → component
+            // deploy → console probe → host installers → commit (backup cleanup).
+            // The transaction handle keeps ONE journal file for the whole update.
+            const installResult = await install({
+                language: options.language ?? 'zh',
+                mode: 'smart',
+                workspaceDir: options.workspaceDir,
+                channels: [],
+                overwriteConfig: false,
+                host: options.host ?? 'openclaw',
+                stopGateway: true,
+            }, payloadDir, { quiet: true, nonInteractive: true }, journal);
+            if (!installResult.success) {
+                ensureTerminalFailed(journal, `installer reported failure before deploying (no runtime mutation): ${installResult.error ?? installResult.reason ?? 'unknown'}`);
+                throw new ReleaseManagerError('apply_failed', `The installer refused or failed the update: ${installResult.error ?? installResult.reason ?? 'unknown'}`, installResult.nextAction ?? 'The runtime is unchanged. Resolve the reported cause and retry.');
+            }
+            if (journal.lastState !== 'confirmed') {
+                // rc-7: never claim success from a non-terminal journal — the state
+                // the installer left behind is what recovery will reason about.
+                ensureTerminalFailed(journal, `installer reported success but the transaction ended at '${journal.lastState ?? 'nothing'}'`);
+                throw new ReleaseManagerError('apply_failed', `The installer reported success but the transaction journal ended at '${journal.lastState ?? 'nothing'}' instead of 'confirmed'.`, 'Treat the update as NOT applied. Inspect the transaction journal and re-run the installer to reach a consistent state.');
+            }
+            return {
+                kind: 'applied',
+                productVersion: releaseMetadata.productVersion,
+                transactionId,
+                journalPath,
+            };
+        }
+        catch (error) {
+            ensureTerminalFailed(journal, `update failed at '${journal.lastState ?? 'planned'}': ${error instanceof Error ? error.message : String(error)}`);
+            // The transaction was opened (planned journaled): mark the refusal so
+            // the caller knows runtime-side effects may exist (staging writes +
+            // terminal journal tail) and must NOT auto-fallback to the legacy
+            // updater over it.
+            const mapped = toReleaseManagerError(error);
+            throw mapped.transactionOpened
+                ? mapped
+                : new ReleaseManagerError(mapped.reason, mapped.message, mapped.nextAction, true);
+        }
+    }
+    async rollback() {
+        void this.paths; // reserved: Phase 2 rollback drives this.paths / this.options
+        throw new ReleaseManagerError('shadow_mode_read_only', 'Rollback is not enabled yet: the ReleaseManager runs in read-only shadow mode while the transactional activation system is brought up.', 'Continue using the current update path. Rollback arrives with the dual-slot transaction rollout.');
+    }
+    /**
+     * Resolve + digest-verify + cache the signed channel document (shared by
+     * check() and apply(); writes stay inside the RM-owned channels cache).
+     */
+    async refreshSignedChannel(channel) {
         const channelTargetPath = `channels/${channel}.json`;
         let trustedTarget;
         try {
@@ -124,16 +351,21 @@ export class ReleaseManager {
             destinationPath: path.join(this.paths.channelsDir, `${channel}.json`),
             fetcher: this.options.fetcher,
         });
-        const channelMetadata = this.readChannelMetadataPayload(channel);
-        const releaseMetadata = this.readReleaseMetadataDocument(channelMetadata, now);
-        // Current state for the advancement policy comes from the ACTIVE release's
-        // own metadata when a dual-slot installation exists.
+        return { channelMetadata: this.readChannelMetadataPayload(channel), trustedTarget };
+    }
+    /**
+     * evaluateReleaseAdvancement with the ACTIVE release's own metadata as the
+     * current state when a dual-slot installation records one (shared by
+     * check() and apply()).
+     */
+    evaluateCandidateDecision(input) {
+        const { channelMetadata, releaseMetadata, status, now } = input;
         let decision = evaluateReleaseAdvancement({
             channel: channelMetadata,
             candidate: releaseMetadata,
             current: null,
             bootstrapVersion: status.bootstrapVersion ?? '0.0.0',
-            now: now(),
+            now,
         });
         if (status.releaseId !== null && status.productVersion !== null) {
             const activeMetadata = this.readActiveReleaseMetadata(status.releaseId);
@@ -149,36 +381,40 @@ export class ReleaseManager {
                         previouslyConfirmedReleaseIds: [status.releaseId],
                     },
                     bootstrapVersion: status.bootstrapVersion ?? '0.0.0',
-                    now: now(),
+                    now,
                 });
             }
         }
-        const candidate = {
-            productVersion: releaseMetadata.productVersion,
-            releaseId: releaseMetadata.releaseId,
-            publicationSequence: releaseMetadata.publicationSequence,
-            assets: releaseMetadata.assets.map((asset) => ({
-                platform: asset.platform,
-                arch: asset.arch,
-                nodeAbi: asset.nodeAbi,
-            })),
-        };
-        const shadowComparison = await this.compareWithLegacyUpdater(status, decision, candidate.productVersion);
-        return {
-            channel,
-            candidate,
-            decision,
-            trustedTarget,
-            shadowComparison,
-        };
-    }
-    async apply() {
-        void this.paths; // reserved: Phase 4 activation drives this.paths / this.options
-        throw new ReleaseManagerError('shadow_mode_read_only', 'Release application is not enabled yet: the ReleaseManager runs in read-only shadow mode while the transactional activation system is brought up.', 'Continue using the current update path. Activation arrives with the dual-slot transaction rollout; this refusal protects against hybrid installations.');
+        return decision;
     }
-    async rollback() {
-        void this.paths; // reserved: Phase 4 rollback drives this.paths / this.options
-        throw new ReleaseManagerError('shadow_mode_read_only', 'Rollback is not enabled yet: the ReleaseManager runs in read-only shadow mode while the transactional activation system is brought up.', 'Continue using the current update path. Rollback arrives with the dual-slot transaction rollout.');
+    /**
+     * The release metadata document names the bytes to deploy. check() only
+     * evaluates already-cached documents; apply() is the "transactional updater"
+     * that finally downloads it: TUF target `releases/<releaseId>/metadata.json`
+     * (Phase 1 convention, custom identity {releaseId, channel, platform:
+     * 'metadata'}) fetched digest-verified into the releases cache, then read
+     * back through the SAME strict validation path (identity + expiry + channel
+     * digest binding). A pre-seeded local document is still accepted unchanged,
+     * so check()-time behavior is untouched.
+     */
+    async ensureReleaseMetadataDocument(channel) {
+        const now = this.options.now ?? (() => new Date());
+        try {
+            return this.readReleaseMetadataDocument(channel, now);
+        }
+        catch (error) {
+            if (!(error instanceof ReleaseManagerError) || error.reason !== 'release_metadata_unavailable') {
+                throw error;
+            }
+            await downloadTrustedReleasePayload({
+                metadataDir: this.paths.trustDir,
+                metadataBaseUrl: this.options.metadataBaseUrl,
+                targetPath: `releases/${channel.releaseId}/metadata.json`,
+                destinationPath: path.join(this.paths.releasesDir, channel.releaseId, 'metadata.json'),
+                fetcher: this.options.fetcher,
+            });
+            return this.readReleaseMetadataDocument(channel, now);
+        }
     }
     legacyOverlayMarker() {
         const openclawRoot = this.options.openclawHome