@evomap/evolver-proxy 2.0.0-beta.0

package/dist/selfUpdate/executor.d.ts

@@ -0,0 +1,90 @@
+import { ops } from '@evomap/evolver-core';
+import { type SelfUpdateFailureCode } from './failureCodes.js';
+type DownloadedArtifact = ops.DownloadedArtifact;
+/** Structured outcome codes — reported to telemetry; the hub sees WHY an update did/didn't apply. */
+export type SelfUpdateOutcome = 'applied' | 'noop' | 'rejected_decision' | 'rejected_verification' | 'download_failed' | 'replace_failed' | 'already_in_progress' | 'disabled';
+export interface SelfUpdateResult {
+    outcome: SelfUpdateOutcome;
+    reason: string;
+    /** Fine-grained stable failure taxonomy for telemetry aggregation. */
+    failureCode?: SelfUpdateFailureCode;
+    /** The version that was (or would have been) applied. */
+    targetVersion?: string;
+    /**
+     * Which download path produced the staged binary: `'binary'` is the normal
+     * precompiled-asset happy path, `'tarball'` means the binary download failed
+     * and Channel 1b (release `.tar.gz`) fallback was used. The verifyManifest
+     * gate ran in BOTH cases, so apply-semantics are identical, but "tarball
+     * used in production" is a useful CDN/rate-limit signal for the hub.
+     * Persisted into `last_update.json` (lastUpdate.LastUpdatePayload.applied_via)
+     * on success so the hub can observe the channel directly.
+     */
+    appliedVia?: 'binary' | 'tarball';
+}
+/** The hub's force_update directive (inbound message payload). */
+export interface ForceUpdateDirective {
+    required_version?: string;
+    manifest?: unknown;
+    reason?: string;
+    release_url?: string;
+    update_channels?: readonly string[];
+    directive_id?: string;
+    deadline_ms?: number;
+    stagger_window_ms?: number;
+}
+/** Result of downloading the release for `targetVersion`: the staged path + the artifacts to verify. */
+export interface DownloadResult {
+    /** Where the new version was staged (e.g. a tmp dir). Passed to atomicReplace on success. */
+    stagedPath: string;
+    /** The downloaded artifacts (bytes or precomputed sha256) for verifyManifest. */
+    artifacts: readonly DownloadedArtifact[];
+    /**
+     * Which channel actually produced the staged bytes — defaults to `'binary'`
+     * when the precompiled asset succeeded, `'tarball'` when Channel 1b fallback
+     * (release `.tar.gz`) had to extract the binary. The executor threads this
+     * onto the SelfUpdateResult as `appliedVia` for telemetry. Optional so
+     * legacy/test seams without a notion of channels stay valid.
+     */
+    appliedVia?: 'binary' | 'tarball';
+}
+/**
+ * Injected I/O seams. Defaults are NOT provided here — the proxy bin wires real implementations (degit/tarball
+ * download, fs atomic rename, process.exit(78)); tests pass fakes. Keeping them required makes "did we actually
+ * call restart?" trivially observable in tests and stops a real restart leaking into a unit run.
+ */
+export interface SelfUpdateDeps {
+    /** Self-update policy. Only 'auto' applies; 'prompt' needs an approval path before this executor runs. */
+    policy: 'off' | 'prompt' | 'auto';
+    /** Current installed version (read from package.json by the caller). */
+    currentVersion: string;
+    /** Resolve a trusted manifest when the hub directive does not carry one. */
+    resolveManifest?: (directive: ForceUpdateDirective, currentVersion: string) => Promise<unknown> | unknown;
+    /** Download the staged release for the target version. Throws/rejects on failure. */
+    download: (targetVersion: string, directive: ForceUpdateDirective) => Promise<DownloadResult>;
+    /** Atomically replace the install tree with the staged path (preserving node_modules/.env/etc). Throws on fail. */
+    atomicReplace: (stagedPath: string) => Promise<void>;
+    /** Signal a restart so the supervisor relaunches the new version. v1 convention: process.exit(78). */
+    restart: () => void;
+    /** Optional Ed25519 public key (PEM / raw base64). When set, an unsigned/badly-signed manifest is REJECTED. */
+    publicKey?: string;
+    /** Best-effort telemetry sink for the structured outcome (never throws into the update path). */
+    onTelemetry?: (result: SelfUpdateResult) => void;
+}
+/** Test-only: reset the mutex between cases. Not part of the public update path. */
+export declare function _resetSelfUpdateMutex(): void;
+/**
+ * Execute a force_update directive end to end: decide → (mutex) → download → VERIFY → atomic replace → restart.
+ *
+ * Order is load-bearing:
+ *  1. policy off → do nothing (the default-off risk gate; a half-built channel must not auto-apply).
+ *  2. decideUpdate (pure): reject bad manifests, NOOP when already satisfied (no download, no restart).
+ *  3. mutex: exactly one execution; concurrent callers get `already_in_progress` and touch no disk.
+ *  4. download the staged release.
+ *  5. verifyManifest (pure) — THE GATE. Fail → no write, no restart, `rejected_verification`.
+ *  6. atomicReplace, then restart(). Only reached after verification passed.
+ *
+ * Never throws: every failure becomes a structured SelfUpdateResult so the daemon can report it and keep running
+ * on the old (intact) version.
+ */
+export declare function executeForceUpdate(directive: ForceUpdateDirective, deps: SelfUpdateDeps): Promise<SelfUpdateResult>;
+export {};

package/dist/selfUpdate/executor.js

@@ -0,0 +1,179 @@
+// Force-update EXECUTOR (the I/O side, ported from v1 src/forceUpdate.js executeForceUpdate). This is the only
+// place in the codebase that downloads a release, replaces files on disk, and signals a restart. Every risky
+// operation is an INJECTED seam (same IoC discipline as exec/selfPr) so tests drive it with fakes and it never
+// shells out or touches a real install tree by accident.
+//
+// THE HARD GATE (verify-before-apply, non-negotiable): after download and BEFORE any filesystem write or restart,
+// the executor calls the PURE core verifyManifest. If verification fails — bad sha256, missing/invalid signature
+// when a key is configured, anything — the executor writes NOTHING, restarts NOTHING, and returns a structured
+// failure. The old version stays intact and runnable. A compromised hub cannot turn this channel into fleet RCE.
+//
+// Concurrency: a process-level mutex guarantees that concurrent force_update messages execute the update EXACTLY
+// once. The second caller short-circuits with `already_in_progress` and performs no I/O.
+import { ops } from '@evomap/evolver-core';
+import { SELF_UPDATE_FAILURE_CODES, classifySelfUpdateError, codeForDecisionReject, } from './failureCodes.js';
+const { decideUpdate, verifyManifest } = ops;
+// Process-level mutex. Module scope is correct: there is one daemon per process, and v1's _forceUpdateInFlight had
+// the same lifetime. Guards against two force_update envelopes (or a heartbeat-driven + mailbox-driven trigger)
+// racing the same upgrade and replacing files twice / double-restarting.
+let inFlight = false;
+/** Test-only: reset the mutex between cases. Not part of the public update path. */
+export function _resetSelfUpdateMutex() {
+    inFlight = false;
+}
+function report(deps, result) {
+    try {
+        deps.onTelemetry?.(result);
+    }
+    catch {
+        /* telemetry must never break the update path */
+    }
+    return result;
+}
+/**
+ * Execute a force_update directive end to end: decide → (mutex) → download → VERIFY → atomic replace → restart.
+ *
+ * Order is load-bearing:
+ *  1. policy off → do nothing (the default-off risk gate; a half-built channel must not auto-apply).
+ *  2. decideUpdate (pure): reject bad manifests, NOOP when already satisfied (no download, no restart).
+ *  3. mutex: exactly one execution; concurrent callers get `already_in_progress` and touch no disk.
+ *  4. download the staged release.
+ *  5. verifyManifest (pure) — THE GATE. Fail → no write, no restart, `rejected_verification`.
+ *  6. atomicReplace, then restart(). Only reached after verification passed.
+ *
+ * Never throws: every failure becomes a structured SelfUpdateResult so the daemon can report it and keep running
+ * on the old (intact) version.
+ */
+export async function executeForceUpdate(directive, deps) {
+    if (deps.policy !== 'auto') {
+        return report(deps, {
+            outcome: 'disabled',
+            reason: deps.policy === 'prompt' ? 'self_update_policy_prompt_requires_approval' : 'self_update_policy_off',
+        });
+    }
+    const requiredFloor = directive.required_version !== undefined
+        ? ops.normalizeRequiredVersion(directive.required_version)
+        : undefined;
+    if (directive.required_version !== undefined && !requiredFloor) {
+        return report(deps, {
+            outcome: 'rejected_decision',
+            reason: 'required_version_invalid',
+            failureCode: SELF_UPDATE_FAILURE_CODES.BAD_REQUIRED_VERSION,
+        });
+    }
+    if (requiredFloor && ops.currentSatisfiesRequiredVersion(deps.currentVersion, requiredFloor)) {
+        return report(deps, { outcome: 'noop', reason: 'already_satisfied', targetVersion: requiredFloor });
+    }
+    let manifest = directive.manifest;
+    if (deps.resolveManifest && shouldResolveManifest(directive, manifest, Boolean(deps.publicKey))) {
+        try {
+            manifest = await deps.resolveManifest(directive, deps.currentVersion);
+        }
+        catch (err) {
+            const targetVersion = ops.normalizeRequiredVersion(directive.required_version);
+            const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED);
+            return report(deps, {
+                outcome: 'download_failed',
+                reason: `manifest_resolve_failed: ${classified.detail}`,
+                failureCode: classified.failureCode,
+                ...(targetVersion ? { targetVersion } : {}),
+            });
+        }
+    }
+    const effectiveDirective = { ...directive, manifest };
+    const decision = decideUpdate({
+        current: deps.currentVersion,
+        ...(requiredFloor ? { required: requiredFloor } : {}),
+        manifest,
+    });
+    if (decision.action === 'reject') {
+        return report(deps, {
+            outcome: 'rejected_decision',
+            reason: decision.reason,
+            failureCode: codeForDecisionReject(decision.reason),
+            ...(decision.targetVersion ? { targetVersion: decision.targetVersion } : {}),
+        });
+    }
+    if (decision.action === 'noop') {
+        return report(deps, { outcome: 'noop', reason: decision.reason, ...(decision.targetVersion ? { targetVersion: decision.targetVersion } : {}) });
+    }
+    // action === 'proceed'. Take the mutex; a concurrent force_update short-circuits here with NO I/O.
+    if (inFlight) {
+        return report(deps, { outcome: 'already_in_progress', reason: 'another_update_in_flight' });
+    }
+    inFlight = true;
+    const targetVersion = decision.targetVersion ?? manifest?.version ?? '';
+    try {
+        // 4. Download the staged release.
+        let dl;
+        try {
+            dl = await deps.download(targetVersion, effectiveDirective);
+        }
+        catch (err) {
+            const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED);
+            return report(deps, {
+                outcome: 'download_failed',
+                reason: classified.detail,
+                failureCode: classified.failureCode,
+                targetVersion,
+            });
+        }
+        // 5. THE GATE: verify the downloaded bytes against the (optionally signed) manifest BEFORE any write.
+        const verification = verifyManifest(manifest, dl.artifacts, ...(deps.publicKey ? [deps.publicKey] : []));
+        if (!verification.ok) {
+            // Verification failed → write NOTHING, restart NOTHING. Old version stays intact and runnable.
+            return report(deps, {
+                outcome: 'rejected_verification',
+                reason: verification.reason,
+                failureCode: SELF_UPDATE_FAILURE_CODES.REJECTED_VERIFICATION,
+                targetVersion,
+            });
+        }
+        // 6. Verified. Atomic replace, then signal restart. A replace failure leaves the old version intact.
+        try {
+            await deps.atomicReplace(dl.stagedPath);
+        }
+        catch (err) {
+            const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.COPY_FAILED);
+            return report(deps, {
+                outcome: 'replace_failed',
+                reason: classified.detail,
+                failureCode: classified.failureCode,
+                targetVersion,
+            });
+        }
+        const result = {
+            outcome: 'applied',
+            reason: 'verified_and_replaced',
+            targetVersion,
+            appliedVia: dl.appliedVia ?? 'binary',
+        };
+        report(deps, result);
+        deps.restart(); // v1 convention: exit(78) → supervisor relaunches the new version.
+        return result;
+    }
+    finally {
+        // Released so a later legitimate update (after a failed attempt) can proceed. On the success path the process
+        // is exiting anyway; releasing is harmless and keeps the mutex honest if restart() is a test fake that returns.
+        inFlight = false;
+    }
+}
+function shouldResolveManifest(directive, manifest, signatureRequired) {
+    if (manifest === undefined)
+        return true;
+    const hasGithubReleaseHint = typeof directive.release_url === 'string'
+        || directive.update_channels?.includes('github') === true;
+    if (!hasGithubReleaseHint)
+        return false;
+    if (signatureRequired)
+        return !hasSignedManifest(manifest);
+    return true;
+}
+function hasSignedManifest(manifest) {
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest))
+        return false;
+    const input = manifest;
+    return typeof input.signature === 'string'
+        && input.signature.length > 0
+        && input.signatureAlg === 'ed25519';
+}

package/dist/selfUpdate/failureCodes.d.ts

@@ -0,0 +1,33 @@
+export declare const SELF_UPDATE_FAILURE_CODES: Readonly<{
+    readonly INSTALL_GUARD_NAME_MISMATCH: "install_guard_name_mismatch";
+    readonly INSTALL_GUARD_UNREADABLE: "install_guard_unreadable";
+    readonly BAD_REQUIRED_VERSION: "bad_required_version";
+    readonly CURRENT_VERSION_UNPARSABLE: "current_version_unparsable";
+    readonly NPX_NOT_FOUND: "npx_not_found";
+    readonly DEGIT_TIMEOUT: "degit_timeout";
+    readonly DEGIT_FAILED: "degit_failed";
+    readonly DOWNLOAD_INCOMPLETE: "download_incomplete";
+    readonly DOWNLOADED_VERSION_MISMATCH: "downloaded_version_mismatch";
+    readonly COPY_FAILED: "copy_failed";
+    readonly ALL_CHANNELS_EXHAUSTED: "all_channels_exhausted";
+    readonly DOWNLOAD_FAILED: "download_failed";
+    readonly REJECTED_DECISION: "rejected_decision";
+    readonly REJECTED_VERIFICATION: "rejected_verification";
+    readonly REPLACE_FAILED: "replace_failed";
+    readonly FALLBACK_DOWNLOAD_FAILED: "fallback_download_failed";
+    readonly FALLBACK_EXTRACT_FAILED: "fallback_extract_failed";
+    readonly FALLBACK_MISSING_BINARY: "fallback_missing_binary";
+}>;
+export type SelfUpdateFailureCode = typeof SELF_UPDATE_FAILURE_CODES[keyof typeof SELF_UPDATE_FAILURE_CODES];
+export interface ClassifiedSelfUpdateError {
+    failureCode: SelfUpdateFailureCode;
+    detail: string;
+}
+export declare class SelfUpdateFailureError extends Error {
+    readonly failureCode: SelfUpdateFailureCode;
+    constructor(failureCode: SelfUpdateFailureCode, detail: string, options?: ErrorOptions);
+}
+export declare function selfUpdateFailure(failureCode: SelfUpdateFailureCode, detail: string, options?: ErrorOptions): SelfUpdateFailureError;
+export declare function classifySelfUpdateError(err: unknown, fallback: SelfUpdateFailureCode): ClassifiedSelfUpdateError;
+export declare function codeForDecisionReject(reason: string): SelfUpdateFailureCode;
+export declare function renderFailureError(code: SelfUpdateFailureCode | undefined, detail: string): string;

package/dist/selfUpdate/failureCodes.js

@@ -0,0 +1,84 @@
+export const SELF_UPDATE_FAILURE_CODES = Object.freeze({
+    INSTALL_GUARD_NAME_MISMATCH: 'install_guard_name_mismatch',
+    INSTALL_GUARD_UNREADABLE: 'install_guard_unreadable',
+    BAD_REQUIRED_VERSION: 'bad_required_version',
+    CURRENT_VERSION_UNPARSABLE: 'current_version_unparsable',
+    NPX_NOT_FOUND: 'npx_not_found',
+    DEGIT_TIMEOUT: 'degit_timeout',
+    DEGIT_FAILED: 'degit_failed',
+    DOWNLOAD_INCOMPLETE: 'download_incomplete',
+    DOWNLOADED_VERSION_MISMATCH: 'downloaded_version_mismatch',
+    COPY_FAILED: 'copy_failed',
+    ALL_CHANNELS_EXHAUSTED: 'all_channels_exhausted',
+    DOWNLOAD_FAILED: 'download_failed',
+    REJECTED_DECISION: 'rejected_decision',
+    REJECTED_VERIFICATION: 'rejected_verification',
+    REPLACE_FAILED: 'replace_failed',
+    // V1 telemetry convention: tarball-fallback leg surfaces as `fallback_<reason>`
+    // so the hub can distinguish primary-channel failures from Channel 1b failures
+    // without inspecting the detail string. The enum string values are the wire
+    // contract; renaming the TS identifier without renaming the value would silently
+    // break aggregation. See V1 #282.
+    FALLBACK_DOWNLOAD_FAILED: 'fallback_download_failed',
+    FALLBACK_EXTRACT_FAILED: 'fallback_extract_failed',
+    FALLBACK_MISSING_BINARY: 'fallback_missing_binary',
+});
+export class SelfUpdateFailureError extends Error {
+    failureCode;
+    constructor(failureCode, detail, options) {
+        super(detail, options);
+        this.name = 'SelfUpdateFailureError';
+        this.failureCode = failureCode;
+    }
+}
+export function selfUpdateFailure(failureCode, detail, options) {
+    return new SelfUpdateFailureError(failureCode, detail, options);
+}
+export function classifySelfUpdateError(err, fallback) {
+    if (err instanceof SelfUpdateFailureError) {
+        return { failureCode: err.failureCode, detail: err.message };
+    }
+    if (isTimeoutError(err)) {
+        return { failureCode: SELF_UPDATE_FAILURE_CODES.DEGIT_TIMEOUT, detail: errorDetail(err) };
+    }
+    return { failureCode: fallback, detail: errorDetail(err) };
+}
+export function codeForDecisionReject(reason) {
+    if (reason === 'required_version_invalid')
+        return SELF_UPDATE_FAILURE_CODES.BAD_REQUIRED_VERSION;
+    if (reason === 'current_version_invalid')
+        return SELF_UPDATE_FAILURE_CODES.CURRENT_VERSION_UNPARSABLE;
+    if (reason === 'manifest_below_required')
+        return SELF_UPDATE_FAILURE_CODES.DOWNLOADED_VERSION_MISMATCH;
+    if (reason === 'manifest_missing'
+        || reason === 'manifest_no_version'
+        || reason === 'manifest_bad_version'
+        || reason === 'manifest_no_artifacts'
+        || reason === 'manifest_bad_artifact_path'
+        || reason === 'manifest_bad_artifact_sha256') {
+        return SELF_UPDATE_FAILURE_CODES.DOWNLOAD_INCOMPLETE;
+    }
+    return SELF_UPDATE_FAILURE_CODES.REJECTED_DECISION;
+}
+export function renderFailureError(code, detail) {
+    if (!code)
+        return detail;
+    const trimmed = detail.trim();
+    return trimmed.length > 0 ? `${code}: ${trimmed}` : code;
+}
+function isTimeoutError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const input = err;
+    const code = typeof input.code === 'string' ? input.code : '';
+    if (input.name === 'AbortError' || input.killed === true || input.signal === 'SIGTERM')
+        return true;
+    if (code === 'ETIMEDOUT' || code === 'UND_ERR_HEADERS_TIMEOUT' || code === 'UND_ERR_CONNECT_TIMEOUT')
+        return true;
+    return isTimeoutError(input.cause);
+}
+function errorDetail(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}

package/dist/selfUpdate/index.d.ts

@@ -0,0 +1,5 @@
+export * from './executor.js';
+export * from './version.js';
+export * from './policy.js';
+export * from './releaseBinary.js';
+export * from './failureCodes.js';

package/dist/selfUpdate/index.js

@@ -0,0 +1,5 @@
+export * from './executor.js';
+export * from './version.js';
+export * from './policy.js';
+export * from './releaseBinary.js';
+export * from './failureCodes.js';

package/dist/selfUpdate/lastUpdate.d.ts

@@ -0,0 +1,43 @@
+import { mailbox } from '@evomap/evolver-core';
+import type { ForceUpdateDirective, SelfUpdateResult } from './executor.js';
+type MailboxStore = mailbox.MailboxStore;
+type LastUpdateStatus = 'success' | 'failed' | 'skipped' | 'pending';
+export interface LastUpdatePayload {
+    to_version: string;
+    status: LastUpdateStatus;
+    finished_at: number;
+    from_version?: string;
+    directive_id?: string;
+    error?: string;
+    /**
+     * Which download channel produced the bytes that got applied: `'binary'` is
+     * the precompiled-asset happy path, `'tarball'` means Channel 1b fallback
+     * (release `.tar.gz`) was used. Persisted on success so the hub can see
+     * "primary CDN is degraded — fallback carrying production" without having
+     * to mine telemetry. Absent on non-success or when the executor predates
+     * the appliedVia field.
+     */
+    applied_via?: 'binary' | 'tarball';
+}
+export interface LastUpdateAck {
+    ok?: boolean;
+    reason?: string;
+}
+export declare function readPendingLastUpdate(store: MailboxStore, now?: number): LastUpdatePayload | undefined;
+export declare function clearLastUpdateOnAck(store: MailboxStore, sent: LastUpdatePayload, now?: number): boolean;
+export declare function writeLastUpdate(store: MailboxStore, payload: LastUpdatePayload, now?: number): boolean;
+export declare function shouldClearForLastUpdateAck(ack: LastUpdateAck | undefined): boolean;
+export declare function isLastUpdateRelatedError(value: unknown): boolean;
+export declare function reportSelfUpdateLastUpdate(store: MailboxStore, directive: ForceUpdateDirective, result: SelfUpdateResult, opts?: {
+    fromVersion: string;
+    now?: number;
+}): boolean;
+export declare function reportPendingSelfUpdateLastUpdate(store: MailboxStore, directive: ForceUpdateDirective, opts?: {
+    fromVersion: string;
+    now?: number;
+}): boolean;
+export declare function lastUpdateFromSelfUpdateResult(directive: ForceUpdateDirective, result: SelfUpdateResult, opts: {
+    fromVersion: string;
+    now: number;
+}): LastUpdatePayload | undefined;
+export {};

package/dist/selfUpdate/lastUpdate.js

@@ -0,0 +1,195 @@
+import { hub as hubNs, mailbox, ops } from '@evomap/evolver-core';
+import { renderFailureError } from './failureCodes.js';
+const LAST_UPDATE_STATE_KEY = 'self_update:last_update';
+const FINISHED_AT_MIN_MS = 1_700_000_000_000;
+const LAST_UPDATE_TTL_MS = 7 * 24 * 60 * 60_000;
+const LAST_UPDATE_TO_VERSION_MAX = 32;
+const LAST_UPDATE_FROM_VERSION_MAX = 32;
+const LAST_UPDATE_DIRECTIVE_ID_MAX = 64;
+const LAST_UPDATE_ERROR_MAX = 1000;
+const STATUS_SET = new Set(['success', 'failed', 'skipped', 'pending']);
+export function readPendingLastUpdate(store, now = Date.now()) {
+    const raw = store.getState(LAST_UPDATE_STATE_KEY);
+    if (!raw)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        clearPendingLastUpdate(store);
+        return undefined;
+    }
+    const payload = normalizeLastUpdate(parsed);
+    if (!payload) {
+        clearPendingLastUpdate(store);
+        return undefined;
+    }
+    if (payload.finished_at >= FINISHED_AT_MIN_MS && now - payload.finished_at > LAST_UPDATE_TTL_MS) {
+        clearPendingLastUpdate(store);
+        return undefined;
+    }
+    return payload;
+}
+function clearPendingLastUpdate(store) {
+    store.setState(LAST_UPDATE_STATE_KEY, '');
+}
+export function clearLastUpdateOnAck(store, sent, now = Date.now()) {
+    const current = readPendingLastUpdate(store, now);
+    if (!current)
+        return false;
+    if (!sameIdentity(current, sent))
+        return false;
+    clearPendingLastUpdate(store);
+    return true;
+}
+export function writeLastUpdate(store, payload, now = Date.now()) {
+    const normalized = normalizeLastUpdate(payload);
+    if (!normalized)
+        return false;
+    if (normalized.status === 'skipped' || normalized.status === 'pending') {
+        const pending = readPendingLastUpdate(store, now);
+        if (pending?.status === 'success' || pending?.status === 'failed')
+            return false;
+    }
+    store.setState(LAST_UPDATE_STATE_KEY, JSON.stringify(normalized));
+    return true;
+}
+export function shouldClearForLastUpdateAck(ack) {
+    if (!ack || typeof ack !== 'object')
+        return false;
+    return ack.ok === true;
+}
+export function isLastUpdateRelatedError(value) {
+    const text = typeof value === 'string' ? value : JSON.stringify(value ?? '');
+    return /last[_\-.]?update/i.test(text);
+}
+export function reportSelfUpdateLastUpdate(store, directive, result, opts = { fromVersion: '0.0.0' }) {
+    const payload = lastUpdateFromSelfUpdateResult(directive, result, {
+        fromVersion: opts.fromVersion,
+        now: opts.now ?? Date.now(),
+    });
+    if (!payload)
+        return false;
+    return writeLastUpdate(store, payload, opts.now ?? Date.now());
+}
+export function reportPendingSelfUpdateLastUpdate(store, directive, opts = { fromVersion: '0.0.0' }) {
+    const now = opts.now ?? Date.now();
+    const toVersion = targetVersionForDirective(directive);
+    if (!toVersion)
+        return false;
+    return writeLastUpdate(store, {
+        to_version: toVersion,
+        status: 'pending',
+        finished_at: Math.max(now, FINISHED_AT_MIN_MS),
+        from_version: clampString(opts.fromVersion, LAST_UPDATE_FROM_VERSION_MAX),
+        ...(directive.directive_id ? { directive_id: String(directive.directive_id) } : {}),
+    }, now);
+}
+export function lastUpdateFromSelfUpdateResult(directive, result, opts) {
+    if (result.outcome === 'already_in_progress' || result.outcome === 'disabled')
+        return undefined;
+    const toVersion = targetVersionForReport(directive, result);
+    if (!toVersion)
+        return undefined;
+    const base = {
+        to_version: toVersion,
+        status: statusForOutcome(result.outcome),
+        finished_at: Math.max(opts.now, FINISHED_AT_MIN_MS),
+        ...(directive.directive_id ? { directive_id: String(directive.directive_id) } : {}),
+    };
+    if (base.status === 'success') {
+        return {
+            ...base,
+            from_version: clampString(opts.fromVersion, LAST_UPDATE_FROM_VERSION_MAX),
+            ...(result.appliedVia ? { applied_via: result.appliedVia } : {}),
+        };
+    }
+    if (base.status === 'failed') {
+        return {
+            ...base,
+            from_version: clampString(opts.fromVersion, LAST_UPDATE_FROM_VERSION_MAX),
+            error: clampString(hubNs.redactString(renderFailureError(result.failureCode, result.reason)), LAST_UPDATE_ERROR_MAX),
+        };
+    }
+    return base;
+}
+function statusForOutcome(outcome) {
+    if (outcome === 'applied')
+        return 'success';
+    if (outcome === 'noop')
+        return 'skipped';
+    return 'failed';
+}
+function targetVersionForReport(directive, result) {
+    const fromResult = reportableVersion(result.targetVersion);
+    if (fromResult)
+        return fromResult;
+    if (result.outcome !== 'applied' && result.outcome !== 'noop')
+        return requiredVersionForReport(directive);
+    return targetVersionForDirective(directive);
+}
+function targetVersionForDirective(directive) {
+    const manifest = directive.manifest;
+    if (manifest && typeof manifest === 'object' && !Array.isArray(manifest)) {
+        const version = concreteVersion(manifest.version);
+        if (version)
+            return version;
+    }
+    return ops.normalizeRequiredVersion(directive.required_version);
+}
+function requiredVersionForReport(directive) {
+    const normalized = ops.normalizeRequiredVersion(directive.required_version);
+    if (!normalized || normalized.length > LAST_UPDATE_TO_VERSION_MAX)
+        return undefined;
+    return normalized;
+}
+function normalizeLastUpdate(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const input = value;
+    const toVersion = concreteVersion(input['to_version']);
+    const status = typeof input['status'] === 'string' && STATUS_SET.has(input['status'])
+        ? input['status']
+        : undefined;
+    const finishedAt = typeof input['finished_at'] === 'number' && Number.isFinite(input['finished_at'])
+        ? Math.max(Math.trunc(input['finished_at']), FINISHED_AT_MIN_MS)
+        : undefined;
+    if (!toVersion || !status || finishedAt === undefined)
+        return undefined;
+    const appliedVia = input['applied_via'];
+    return {
+        to_version: toVersion,
+        status,
+        finished_at: finishedAt,
+        ...(typeof input['from_version'] === 'string' ? { from_version: clampString(input['from_version'], LAST_UPDATE_FROM_VERSION_MAX) } : {}),
+        ...(typeof input['directive_id'] === 'string' && input['directive_id'].length > 0
+            ? { directive_id: clampString(input['directive_id'], LAST_UPDATE_DIRECTIVE_ID_MAX) }
+            : {}),
+        ...(typeof input['error'] === 'string' && input['error'].length > 0
+            ? { error: clampString(hubNs.redactString(input['error']), LAST_UPDATE_ERROR_MAX) }
+            : {}),
+        ...(appliedVia === 'binary' || appliedVia === 'tarball' ? { applied_via: appliedVia } : {}),
+    };
+}
+function sameIdentity(a, b) {
+    return a.status === b.status
+        && a.finished_at === b.finished_at
+        && a.to_version === b.to_version
+        && (a.directive_id ?? '') === (b.directive_id ?? '');
+}
+function concreteVersion(value) {
+    const normalized = ops.normalizeConcreteVersion(value);
+    if (!normalized || normalized.length > LAST_UPDATE_TO_VERSION_MAX)
+        return undefined;
+    return normalized;
+}
+function reportableVersion(value) {
+    const normalized = ops.normalizeRequiredVersion(value) ?? ops.normalizeConcreteVersion(value);
+    if (!normalized || normalized.length > LAST_UPDATE_TO_VERSION_MAX)
+        return undefined;
+    return normalized;
+}
+function clampString(value, max) {
+    return value.length <= max ? value : value.slice(0, max);
+}

package/dist/selfUpdate/policy.d.ts

@@ -0,0 +1,3 @@
+export type SelfUpdatePolicy = 'off' | 'prompt' | 'auto';
+/** Resolve EVOLVER_SELF_UPDATE to a policy. Unset/unrecognized → 'off' (fail-closed). */
+export declare function resolveSelfUpdatePolicy(env?: NodeJS.ProcessEnv): SelfUpdatePolicy;

package/dist/selfUpdate/policy.js

@@ -0,0 +1,9 @@
+/** Resolve EVOLVER_SELF_UPDATE to a policy. Unset/unrecognized → 'off' (fail-closed). */
+export function resolveSelfUpdatePolicy(env = process.env) {
+    const raw = (env['EVOLVER_SELF_UPDATE'] ?? '').trim().toLowerCase();
+    if (raw === 'prompt')
+        return 'prompt';
+    if (raw === 'auto')
+        return 'auto';
+    return 'off';
+}