@cspeach/cli 1.0.0 → 1.1.1

package/dist/rewind/candidates.js

@@ -0,0 +1,194 @@
+/**
+ * Rewind data layer (pure) — UX Wave 3, Task 1.
+ *
+ * Answers the question that powers the "undo for your SAP system" feature:
+ * *which of this session's successful writes can be rolled back, and to what
+ * prior state?* It joins the session's write tool-calls with the Rule-7
+ * snapshots taken just before each write.
+ *
+ * Pure module: no fs, no network. The snapshot list arrives as an argument
+ * (from `snapshots.list()`), so this function is trivially testable and can
+ * run anywhere.
+ *
+ * Scope (binding, from the Task-1 brief):
+ *   - Five write tools qualify: sap_set_source, sap_update_method,
+ *     sap_set_class_include, sap_create_object, sap_delete_object.
+ *   - Only successful (`is_error: false`) AND completed (`completed: true`)
+ *     calls count — pending entries and failures are ignored.
+ *   - Newest write first; deduped per (object, objType) keeping the NEWEST
+ *     write for that object.
+ *   - The restore point is the newest snapshot taken strictly BEFORE that
+ *     write (snapshot timestamp < write completed_at).
+ *   - sap_create_object ⇒ not restorable (no prior state; restore of a create
+ *     would be a delete, out of v1 scope) + a display `reason`.
+ *   - sap_delete_object ⇒ restorable when a pre-delete snapshot exists (the
+ *     snapshot IS the prior source; the executor recreates it).
+ */
+/** The five write tools whose effects can (potentially) be rewound. */
+const WRITE_TOOLS = new Set([
+    'sap_set_source',
+    'sap_update_method',
+    'sap_set_class_include',
+    'sap_create_object',
+    'sap_delete_object',
+]);
+/** Tools whose object is always a class, identified via className/class_name
+ *  (they carry no explicit `type` arg — the type is implicitly CLAS). */
+const IMPLICIT_CLASS_TOOLS = new Set([
+    'sap_update_method',
+    'sap_set_class_include',
+]);
+/**
+ * Collect this session's rewindable writes, newest-first, one per object.
+ *
+ * @param toolCalls    the session's tool-call ledger (SessionState.toolCalls)
+ * @param snapshotList all snapshots from snapshots.list() (no filter)
+ */
+export function collectRewindCandidates(toolCalls, snapshotList) {
+    // 1. Keep only successful, completed calls to the five write tools that
+    //    carry a resolvable object identity.
+    const writes = [];
+    for (const call of toolCalls) {
+        if (!call.completed || call.is_error)
+            continue;
+        if (!WRITE_TOOLS.has(call.tool))
+            continue;
+        const identity = extractIdentity(call.tool, call.args);
+        if (!identity)
+            continue;
+        writes.push({
+            call,
+            object: identity.object,
+            objType: identity.objType,
+            at: Date.parse(call.completed_at),
+        });
+    }
+    // 2. Newest write first.
+    writes.sort((a, b) => b.at - a.at);
+    // 3. Dedupe per (object, objType): the first survivor is the newest write.
+    const seen = new Set();
+    const candidates = [];
+    for (const w of writes) {
+        const key = `${w.objType}|${w.object}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const snap = newestSnapshotBefore(snapshotList, w.objType, w.object, w.at);
+        const isCreate = w.call.tool === 'sap_create_object';
+        // Creates force snapshotId/snapshotAt to null even when an older snapshot
+        // for the same (type, name) exists. Deliberate v1 scope, NOT a bug: in a
+        // delete→recreate-same-session sequence the recreate (newest write) wins
+        // the dedupe, so the pre-delete restore point is hidden — restoring
+        // pre-delete source onto a freshly created object is a cross-lifecycle
+        // rollback v1 does not attempt. Tasks 2/3: do not "fix" this.
+        const candidate = {
+            object: w.object,
+            objType: w.objType,
+            writeTool: w.call.tool,
+            writtenAt: w.call.completed_at,
+            snapshotId: isCreate ? null : (snap ? snap.id : null),
+            snapshotAt: isCreate ? null : (snap ? normalizeSnapshotTimestamp(snap.timestamp) : null),
+            restorable: !isCreate && snap !== null,
+        };
+        if (isCreate)
+            candidate.reason = 'created this session — no prior state';
+        // T1 (rider c) — mine the recreate package for delete-restores only.
+        if (w.call.tool === 'sap_delete_object') {
+            const pkg = harvestCreatePackage(toolCalls, w.objType, w.object, w.at);
+            if (pkg)
+                candidate.package = pkg;
+        }
+        candidates.push(candidate);
+    }
+    return candidates;
+}
+/**
+ * Resolve (object, objType) from a write tool's recorded args.
+ *
+ * Mirrors the retry-key heuristic (name/type with object_name/object_type
+ * alternates). The class-scoped tools are handled tool-conditionally for
+ * self-documentation: only sap_update_method (class_name) and
+ * sap_set_class_include (className) consult the class-name fields, and
+ * their type is implicitly CLAS (their schemas carry no `type` arg).
+ * Returns null when no object name can be resolved.
+ */
+function extractIdentity(tool, rawArgs) {
+    const args = (rawArgs ?? {});
+    if (IMPLICIT_CLASS_TOOLS.has(tool)) {
+        const object = pickString(args, 'className') ?? pickString(args, 'class_name');
+        return object ? { object: object.toUpperCase(), objType: 'CLAS' } : null;
+    }
+    const object = pickString(args, 'name') ?? pickString(args, 'object_name');
+    if (!object)
+        return null;
+    const objType = pickString(args, 'type') ?? pickString(args, 'object_type');
+    if (!objType)
+        return null;
+    return { object: object.toUpperCase(), objType: objType.toUpperCase() };
+}
+/**
+ * T1 (rider c) — newest package from a successful sap_create_object of the
+ * same (type, name) completed strictly before the delete. Chronological ledger
+ * scan; returns undefined when this session never created the object.
+ */
+function harvestCreatePackage(toolCalls, objType, object, beforeEpoch) {
+    let best;
+    for (const call of toolCalls) {
+        if (!call.completed || call.is_error)
+            continue;
+        if (call.tool !== 'sap_create_object')
+            continue;
+        const id = extractIdentity('sap_create_object', call.args);
+        if (!id || id.objType !== objType || id.object !== object)
+            continue;
+        const at = Date.parse(call.completed_at);
+        if (!Number.isFinite(at) || at >= beforeEpoch)
+            continue;
+        const pkg = pickString((call.args ?? {}), 'package');
+        if (!pkg)
+            continue;
+        if (!best || at > best.at)
+            best = { at, pkg };
+    }
+    return best?.pkg;
+}
+/** Newest snapshot for (type, name) taken strictly before `beforeEpoch`. */
+function newestSnapshotBefore(snapshotList, objType, object, beforeEpoch) {
+    let best = null;
+    let bestEpoch = -Infinity;
+    for (const s of snapshotList) {
+        if (s.type.toUpperCase() !== objType)
+            continue;
+        if (s.name.toUpperCase() !== object)
+            continue;
+        const epoch = snapshotEpoch(s.timestamp);
+        if (!Number.isFinite(epoch))
+            continue;
+        if (epoch >= beforeEpoch)
+            continue; // must be strictly before the write
+        if (epoch > bestEpoch) {
+            bestEpoch = epoch;
+            best = s;
+        }
+    }
+    return best;
+}
+/**
+ * SnapshotEntry.timestamp is `new Date().toISOString().replace(/[:.]/g, '-')`
+ * (sap-client/src/safety/snapshots.ts), i.e. `YYYY-MM-DDTHH-MM-SS-mmmZ`. Turn
+ * it back into a real ISO string for display / parsing.
+ */
+function normalizeSnapshotTimestamp(mangled) {
+    const m = /^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/.exec(mangled);
+    if (!m)
+        return mangled; // unexpected format — return as-is rather than lie
+    return `${m[1]}T${m[2]}:${m[3]}:${m[4]}.${m[5]}Z`;
+}
+/** Epoch millis for a (possibly dash-mangled) snapshot timestamp. */
+function snapshotEpoch(mangled) {
+    return Date.parse(normalizeSnapshotTimestamp(mangled));
+}
+function pickString(args, key) {
+    const v = args[key];
+    return typeof v === 'string' && v.length > 0 ? v : null;
+}

package/dist/rewind/cli.js

@@ -0,0 +1,137 @@
+/**
+ * Rewind wiring — UX Wave 3 / Task 3. Three exports:
+ *
+ *   - buildRestoreDeps(): the ONE shared RestoreDeps builder used by BOTH the
+ *     Ink panel-restore path (repl.tsx) and the classic list path below. It
+ *     resolves the transport PER-CANDIDATE at restore time (rider a — owning-TR
+ *     override wins over the session transport, mirroring sap_set_source) and
+ *     threads the alias auto_approve policy (rider b) so the modal's risk label
+ *     is true.
+ *   - executeRestore(): the shared restore leg — single-flight reserve (a
+ *     restore counts as BUSY: submits become steering, dispatches queue),
+ *     deps assembly, the gated executor, and outcome printing. Catches every
+ *     throw (defense in depth for review I2) so a network drop mid-pipeline
+ *     prints the partial receipt + error instead of crashing the process.
+ *   - runClassicRewind(): the non-Ink `/rewind` — a numbered inquirer list +
+ *     confirm, reusing the identical candidate collector and executeRestore.
+ */
+import chalk from 'chalk';
+import { select, confirm } from '@inquirer/prompts';
+import { snapshots } from '@cspeach/sap-client';
+import { collectRewindCandidates } from './candidates.js';
+import { restoreSnapshot } from './restore.js';
+import { hhmm, rewindRowLabel, packageUnknown } from './format.js';
+// Pure singleton emitter (no Ink) — safe in the classic path. In classic mode
+// nothing consults isBusy() during an awaited builtin, so the reserve is a
+// no-op there; in Ink it is the whole point (see executeRestore).
+import { turnStatusEmitter } from '../ui/turn-status-emitter.js';
+import { resolveWriteTransport } from '../tools/transport-resolution.js';
+import { renderPerChangeApproval } from '../approvals/render.js';
+import { withInquirer } from '../repl/inquirer-guard.js';
+import { inquirerTheme } from '../repl/inquirer-theme.js';
+/**
+ * Assemble RestoreDeps for one candidate. Resolves the write transport against
+ * the owning-transport ledger (rider a) and threads the alias auto_approve
+ * policy (rider b). Called once per restore so a per-object owning-TR override
+ * is always honoured.
+ */
+export async function buildRestoreDeps(c, w) {
+    const sap = w.cfg.sap[w.alias];
+    const resolved = await resolveWriteTransport(w.toolCtx, c.objType, c.object, w.suppliedTransport);
+    return {
+        adt: w.adt,
+        cfgWriteMode: w.cfg.write_mode,
+        role: sap?.role,
+        transport: resolved.transport,
+        autoApprovePolicy: sap?.auto_approve ?? 'never',
+        requestApproval: w.requestApproval,
+        log: w.log,
+    };
+}
+/**
+ * The shared restore leg (review I1a + I2 + M4). Both surfaces funnel here:
+ *
+ *  - I1(a): turnStatusEmitter.reserve() is held for the FULL duration — the
+ *    pre-approval window (transport lookup, snapshot read, current-source
+ *    read), the pending approval modal, and the post-approval pipeline. While
+ *    held, isBusy() is true, so a footer submit becomes queued steering and no
+ *    turn can dispatch mid-restore (the model could otherwise write over the
+ *    object we are restoring). release() in finally — a thrown pipeline can
+ *    never wedge the session busy.
+ *  - I2 (defense in depth): restoreSnapshot itself now catches its pipeline
+ *    awaits, but ANY residual throw (deps assembly, a future refactor) lands
+ *    in the catch below and prints the partial receipt context + error instead
+ *    of escaping to the process-level uncaughtException exit.
+ *  - M4: a declined approval prints a calm '↩ rewind cancelled' line — the
+ *    user said no; nothing failed.
+ */
+export async function executeRestore(c, w, print) {
+    turnStatusEmitter.reserve();
+    try {
+        const deps = await buildRestoreDeps(c, w);
+        const r = await restoreSnapshot(c, deps);
+        if (r.ok) {
+            print(chalk.green(`✓ restored ${c.objType}/${c.object}`));
+        }
+        else if (r.error === 'declined') {
+            print(chalk.dim(`↩ rewind cancelled — approval declined`));
+        }
+        else {
+            print(chalk.red(`✗ rewind failed — ${r.error ?? 'unknown'}`));
+        }
+    }
+    catch (err) {
+        // Partial receipt lines already streamed via deps.log — close honestly.
+        const msg = err instanceof Error ? err.message : String(err);
+        print(chalk.red(`✗ rewind failed — ${msg}`));
+    }
+    finally {
+        turnStatusEmitter.release();
+    }
+}
+/**
+ * Classic-mode `/rewind`: numbered list → inquirer select (non-restorable rows
+ * disabled) → confirm → gated restore → receipt. Same candidates + executor as
+ * the Ink panel; only the surface differs.
+ */
+export async function runClassicRewind(ctx) {
+    const snapshotList = await snapshots.list();
+    const candidates = collectRewindCandidates(ctx.toolCalls, snapshotList);
+    if (candidates.length === 0) {
+        ctx.print(chalk.dim('no restorable writes this session'));
+        return;
+    }
+    const CANCEL = '__cspeach_rewind_cancel__';
+    const choices = candidates.map((c, i) => ({
+        name: `${String(i + 1).padStart(2)}. ${rewindRowLabel(c)}`
+            + (packageUnknown(c) ? '  (package unknown — restore may fail)' : ''),
+        value: String(i),
+        disabled: c.restorable ? false : 'no restore point',
+    }));
+    choices.push({ name: 'Cancel', value: CANCEL, disabled: false });
+    const pick = await withInquirer(() => select({
+        message: 'Rewind which write?',
+        theme: inquirerTheme,
+        choices,
+    }));
+    if (typeof pick !== 'string' || pick === CANCEL)
+        return;
+    const chosen = candidates[Number(pick)];
+    if (!chosen || !chosen.restorable)
+        return;
+    const proceed = await withInquirer(() => confirm({
+        message: `Restore ${chosen.object} to snapshot ${hhmm(chosen.snapshotAt)}? This runs the write gates.`,
+        default: false,
+    }));
+    if (!proceed)
+        return;
+    await executeRestore(chosen, {
+        adt: ctx.adt,
+        cfg: ctx.cfg,
+        alias: ctx.alias,
+        toolCtx: ctx.toolCtx,
+        suppliedTransport: ctx.suppliedTransport,
+        requestApproval: (change, risk, transport) => renderPerChangeApproval(change, risk, transport),
+        log: (line) => ctx.print(chalk.dim(line)),
+    }, ctx.print);
+}

package/dist/rewind/format.js

@@ -0,0 +1,27 @@
+/**
+ * Pure row/label formatters shared by the Ink RewindPanel and the classic
+ * inquirer list (rewind/cli.ts). Kept ink-free so importing it from the
+ * classic path does not drag React/Ink into a non-TTY process.
+ */
+/** UTC HH:MM from an ISO timestamp — deterministic (write & snapshot times are
+ *  both UTC 'Z', so relative sense is preserved without a TZ dependency). */
+export function hhmm(iso) {
+    if (!iso)
+        return '??:??';
+    const m = /T(\d{2}):(\d{2})/.exec(iso);
+    return m ? `${m[1]}:${m[2]}` : '??:??';
+}
+/** Row label without glyph / selection styling. Restorable rows carry the
+ *  snapshot time; non-restorable rows carry the reason. */
+export function rewindRowLabel(c) {
+    const tool = c.writeTool.replace(/^sap_/, '');
+    const base = `${c.object} (${c.objType}) · ${tool} · ${hhmm(c.writtenAt)}`;
+    if (c.restorable)
+        return `${base} · snapshot ${hhmm(c.snapshotAt)}`;
+    return `${base} — ${c.reason ?? 'no restore point'}`;
+}
+/** True when a restorable delete has no recreate package to fall back on —
+ *  the restore may fail on the real system's empty-package rejection. */
+export function packageUnknown(c) {
+    return c.restorable && c.writeTool === 'sap_delete_object' && !c.package;
+}

package/dist/rewind/restore.js

@@ -0,0 +1,245 @@
+/**
+ * Restore executor — UX Wave 3, Task 2. The gated, harness-driven write that
+ * makes "undo for your SAP system" real.
+ *
+ * A restore IS a write to a live SAP system, so it runs the FULL safety ladder
+ * — the harness-side twin of the `sap_set_source` tool's gate pipeline
+ * (cspeach-cli/src/tools/sap-write.ts). Same AdtClient calls, same order:
+ *
+ *   getEffectiveWriteMode clamp   (advisory-only ⇒ blocked, NO prompt)
+ *     → snapshots.read (restore source)
+ *     → adt.getSource (current source; 404 tolerated ⇒ delete-restore)
+ *     → deps.requestApproval (synthetic Change + riskFloor)   ← the gate
+ *     → snapshots.take (Rule 7: snapshot CURRENT before overwrite)
+ *     → [adt.createObject when current===null]  ← delete-restore create-first
+ *     → adt.setSource (write the snapshot content)
+ *     → verifySyntax  (Rule 10: syntax errors ⇒ STOP, object left inactive)
+ *     → adt.activate + verifyActive  (Rule 10: confirm active)
+ *
+ * Pure orchestration over INJECTED deps — no model turn, no approval mechanics
+ * of its own. It never imports the approvalEmitter or inquirer: the caller
+ * (Task 3) injects `requestApproval`, which bridges to the Ink emitter or the
+ * classic prompt. That keeps this module fully unit-testable and guarantees a
+ * declined approval provably writes nothing.
+ */
+import { snapshots, SapError } from '@cspeach/sap-client';
+import { getEffectiveWriteMode } from '../repl/mode-cycle.js';
+import { effectiveRisk } from '../approvals/risk-floor.js';
+import { verifySyntax, verifyActive } from '../tools/verify.js';
+import { renderDiff } from '../repl/diff-display.js';
+/** Compact single-line failure text for receipts / error envelopes. */
+function shortError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Restore an object to the source captured in a prior snapshot, through the
+ * full write-safety ladder. Returns `{ ok, steps, error? }`; on any stop
+ * before the write, nothing has been written to SAP.
+ */
+export async function restoreSnapshot(c, deps) {
+    const steps = [];
+    const record = (line) => {
+        steps.push(line);
+        deps.log(line);
+    };
+    // ── Step 1: Effective-mode clamp FIRST — before any prompt or read ────────
+    // A prd ceiling (or an explicit advisory-only config/session mode) forbids
+    // writes entirely. Restore is a write, so it is blocked by policy with no
+    // approval prompt shown. Mirrors approval.ts's advisory short-circuit.
+    if (getEffectiveWriteMode(deps.cfgWriteMode, deps.role) === 'advisory-only') {
+        return { ok: false, steps, error: 'write mode is advisory-only — restore blocked (policy)' };
+    }
+    // Defensive guard: a non-restorable candidate has no restore point. Task 3
+    // only offers restorable rows, but never trust the caller with a live write.
+    if (c.snapshotId === null) {
+        return { ok: false, steps, error: 'no snapshot to restore from' };
+    }
+    // ── Step 2: Read the snapshot source (the content we will restore) ────────
+    let snapshotSource;
+    try {
+        snapshotSource = await snapshots.read(c.objType, c.object, c.snapshotId);
+    }
+    catch (err) {
+        return { ok: false, steps, error: `could not read snapshot: ${shortError(err)}` };
+    }
+    // ── Step 3: Read current source — tolerate a genuine 404 (delete-restore) ─
+    // A 404 means the object was deleted this session; current = null and we
+    // will recreate it. Any OTHER read failure is NOT proof of absence — stop
+    // rather than blindly treat it as a create.
+    let currentSource;
+    try {
+        currentSource = await deps.adt.getSource(c.objType, c.object);
+    }
+    catch (err) {
+        if (err instanceof SapError && err.httpStatus === 404) {
+            currentSource = null;
+        }
+        else {
+            return { ok: false, steps, error: `could not read current source: ${shortError(err)}` };
+        }
+    }
+    // ── Step 4: Approval — the gate. Synthetic Change + riskFloor path ────────
+    // op is 'create' when the object is gone (delete-restore), else 'modify'.
+    // The diff is built with the SAME builder the update-method preview uses
+    // (repl/diff-display.renderDiff → `diff` createPatch), current → snapshot.
+    const op = currentSource === null ? 'create' : 'modify';
+    const change = {
+        op,
+        object: c.object,
+        type: c.objType,
+        diff: renderDiff(currentSource ?? '', snapshotSource, {
+            label: `${c.objType}/${c.object}`,
+            syntaxHighlight: false,
+        }),
+        // package is unknown at rewind time (the snapshot store carries no package,
+        // and a deleted object cannot be re-read for it) — omit per the Change
+        // contract (the approval box drops the segment rather than showing a stub).
+    };
+    // Risk via the same effectiveRisk path approval.ts uses. Rider (b): the
+    // alias's real auto_approve policy is threaded in (default 'never', exactly
+    // as approval.ts does with sapCfg?.auto_approve ?? 'never') so the modal's
+    // risk label is true for this system. sapAlias is unused by effectiveRisk.
+    const riskCtx = { sapAlias: '', autoApprovePolicy: deps.autoApprovePolicy ?? 'never' };
+    const risk = effectiveRisk('medium', [change], riskCtx);
+    const outcome = await deps.requestApproval(change, risk, deps.transport);
+    if (!outcome.approved) {
+        // Declined ⇒ provably nothing written: we return before any take/write.
+        return { ok: false, steps, error: 'declined' };
+    }
+    // ── Step 5: Rule 7 — snapshot CURRENT before we overwrite it ──────────────
+    // Skip only when the object is gone (nothing to snapshot). The reason tag
+    // 'before_rewind' distinguishes these from ordinary 'before_write' snaps.
+    if (currentSource !== null) {
+        try {
+            await snapshots.take(c.objType, c.object, currentSource, 'before_rewind');
+        }
+        catch (err) {
+            return { ok: false, steps, error: `snapshot before restore failed: ${shortError(err)}` };
+        }
+        record('① snapshot ✓');
+    }
+    else {
+        record('① snapshot — skipped (object was deleted this session)');
+    }
+    // ── Step 6: Write the snapshot source — create-first for delete-restore ───
+    // sap_set_source's write path is a single adt.setSource call (lock→PUT→unlock
+    // handled inside the client). For a deleted object we must recreate the shell
+    // first, then write the source. Rider (c): the package is harvested from this
+    // session's own sap_create_object (candidate.package); when absent, createObject
+    // gets '' and a real system rejects the empty package — the pipeline stops here
+    // with an honest error (the panel warns before the user ever gets this far).
+    if (currentSource === null) {
+        let created;
+        try {
+            created = await deps.adt.createObject(c.objType, c.object, c.package ?? '', 'Restored via CSPeach rewind', deps.transport);
+        }
+        catch (err) {
+            record('② written ✗');
+            return { ok: false, steps, error: `recreate failed: ${shortError(err)}` };
+        }
+        if (created.status !== 'created') {
+            record('② written ✗');
+            return { ok: false, steps, error: `recreate failed: ${created.error ?? `HTTP ${created.httpStatus}`}` };
+        }
+    }
+    let writeResult;
+    try {
+        writeResult = await deps.adt.setSource(c.objType, c.object, snapshotSource, deps.transport);
+    }
+    catch (err) {
+        record('② written ✗');
+        return { ok: false, steps, error: `write failed: ${shortError(err)}` };
+    }
+    // setSource RETURNS (does not throw) on HTTP 4xx — check the return value,
+    // exactly as sap_set_source does.
+    if (writeResult.error || (writeResult.writeStatus !== undefined && writeResult.writeStatus >= 400)) {
+        const detail = writeResult.error ?? `HTTP ${writeResult.writeStatus}`;
+        record('② written ✗');
+        return { ok: false, steps, error: `write failed: ${detail}` };
+    }
+    record('② written ✓');
+    // ── Step 7: Syntax check (Rule 10) — errors ⇒ STOP, do NOT activate ───────
+    // I2 (review): the raw post-write awaits used to escape — a network drop here
+    // became an unhandled rejection → process exit AFTER '② written ✓' with no
+    // receipt, so the user could not tell whether the restore landed. Every
+    // post-write await is now caught and reported with an honest step line: the
+    // WRITE HAPPENED; only the verification/activation call failed to run.
+    let syntax;
+    try {
+        syntax = await verifySyntax(deps.adt, c.object, c.objType);
+    }
+    catch (err) {
+        record(`③ syntax — check failed to run: ${shortError(err)}`);
+        return {
+            ok: false,
+            steps,
+            error: `snapshot source was written, but the syntax check failed to run: ${shortError(err)} — `
+                + `${c.objType}/${c.object} is NOT activated; verify it manually.`,
+        };
+    }
+    if (!syntax.ok) {
+        record('③ syntax ✗');
+        return {
+            ok: false,
+            steps,
+            error: `snapshot source restored but has syntax errors — ${c.objType}/${c.object} is now INACTIVE. `
+                + `Fix or re-restore before use. ${syntax.errors.join('; ')}`,
+        };
+    }
+    record('③ syntax ✓');
+    // ── Step 8: Activate + verify (Rule 10) ───────────────────────────────────
+    let activation;
+    try {
+        activation = await deps.adt.activate(c.objType, c.object);
+    }
+    catch (err) {
+        record(`④ activate — call failed: ${shortError(err)}`);
+        return {
+            ok: false,
+            steps,
+            error: `snapshot source was written and syntax-checked, but the activation call failed: ${shortError(err)} — `
+                + `${c.objType}/${c.object} is likely INACTIVE; activate it manually.`,
+        };
+    }
+    if (!activation.success) {
+        record('④ activated ✗');
+        const detail = activation.messages.map((m) => m.shortText).filter(Boolean).join('; ');
+        return {
+            ok: false,
+            steps,
+            error: `restored but activation failed — ${c.objType}/${c.object} is INACTIVE.${detail ? ' ' + detail : ''}`,
+        };
+    }
+    record('④ activated ✓');
+    // verifyActive catches its own inactiveObjects() failure (returns
+    // verifyError) — but wrap anyway so no future refactor can leak a throw
+    // past the receipt.
+    let active;
+    try {
+        active = await verifyActive(deps.adt, c.object, c.objType);
+    }
+    catch (err) {
+        active = { active: false, verifyError: shortError(err) };
+    }
+    if (active.verifyError) {
+        // Post-check itself failed — never claim success we could not confirm.
+        record('⑤ verify ✗');
+        return {
+            ok: false,
+            steps,
+            error: `restored and activation reported success, but could not verify active state: ${active.verifyError}`,
+        };
+    }
+    if (!active.active) {
+        // Silent activation failure — object still in the inactive list.
+        record('⑤ verify ✗');
+        return {
+            ok: false,
+            steps,
+            error: `activation reported success but ${c.objType}/${c.object} is still inactive`,
+        };
+    }
+    record('⑤ verified ✓');
+    return { ok: true, steps };
+}