@huynle/hub 0.6.1 → 0.7.2

package/packages/cli/src/bootstrap/profiles/drift.ts

@@ -0,0 +1,286 @@
+// Managed-field drift detection. Hub owns exactly the fields its plans set: each merge-config pointer, its mcp
+// registration, and the files it writes (write-file, install-service). Nothing else in a config is hub's.
+//
+// For each managed field, detection compares three states:
+//   applied   what the last apply set: the applied plan's value, counted only when its journal entry is "done"
+//   desired   what the fresh plan (for the current profile) sets
+//   current   what is there: the snapshot's file digests, plus observed values for config fields. When a file's
+//             digest still equals what the journal says hub left, the applied values are known to be current.
+// and gives one status:
+//   in-sync       current equals desired
+//   missing       absent and hub never set it: hub may set it
+//   outdated      still exactly hub's applied value, but hub now wants another: hub may update it
+//   user-changed  anything else (changed, removed, or a value the user had before hub): reported, never overwritten
+//   retired       hub set it before but no longer manages it: left in place, reported
+//   unobserved    the current state is unknown (no observation, file not discovered): reported, never repaired
+//
+// detectDrift is pure and never writes. Reports carry digests of current values, never the values themselves, so a
+// user's secret in a field hub happens to manage cannot leak into a report. driftRepairs turns a report into the
+// minimal lossless actions for the repairable fields only, pinned to the file's current digest.
+import {
+  canonicalJSON,
+  Checker,
+  digestOf,
+  ok,
+  planDigest,
+  resolvePathRef,
+  validateDiscoverySnapshot,
+  validateJournal,
+  validateSetupPlan,
+  type Action,
+  type DiscoverySnapshot,
+  type FileState,
+  type HarnessID,
+  type Json,
+  type PathRef,
+  type Precondition,
+  type Result,
+  type SetupPlan,
+  type TransactionJournal,
+} from "../contracts/index.ts"
+
+export type ManagedFieldType = "config-value" | "array-entry" | "mcp-registration" | "file"
+
+/** One field hub owns, as a plan sets it. */
+export interface ManagedField {
+  /** "<root>:<rel>#<pointer>" for config fields, "<root>:<rel>" for files, "mcp:<harness>/<name>" for registrations. */
+  readonly key: string
+  readonly type: ManagedFieldType
+  readonly actionID: string
+  readonly path: PathRef
+  /** Config fields: the RFC 6901 pointer as the plan sets it ("/x/-" appends to the array at "/x"). */
+  readonly pointer?: string
+  /** Config fields: the value hub sets. */
+  readonly value?: Json
+  /** Files: the content digest hub writes. */
+  readonly sha256?: string
+  readonly registration?: { readonly harness: HarnessID; readonly name: string }
+}
+
+export type DriftStatus = "in-sync" | "missing" | "outdated" | "user-changed" | "retired" | "unobserved"
+
+export interface FieldDrift {
+  readonly key: string
+  readonly actionID: string
+  readonly path: PathRef
+  readonly pointer?: string
+  readonly status: DriftStatus
+  /** Whether hub may change it (missing, or outdated and replaceable by a set). */
+  readonly repairable: boolean
+  /** Digest of the current value or file; null when absent; omitted when unobserved. Never the value itself. */
+  readonly currentDigest?: string | null
+}
+
+export interface DriftReport {
+  /** Desired fields in plan order, then retired ones. */
+  readonly fields: readonly FieldDrift[]
+  /** The fields the user changed: reported, never overwritten. */
+  readonly userChanged: readonly FieldDrift[]
+  /** Files hub wrote that changed since (by anyone; user edits to unmanaged fields show up only here). */
+  readonly changedSinceApply: readonly PathRef[]
+  readonly inSync: boolean
+  /** Always zero: detection never writes. */
+  readonly writes: 0
+}
+
+/**
+ * What a reader saw (data, read by the caller; this module never reads). For an append pointer ("/plugin/-"),
+ * observe the array it appends to ("/plugin").
+ */
+export type ObservedField =
+  | { readonly path: PathRef; readonly pointer: string; readonly state: "absent" }
+  | { readonly path: PathRef; readonly pointer: string; readonly state: "value"; readonly value: Json }
+
+export interface ObservedRegistration {
+  readonly harness: HarnessID
+  readonly name: string
+  /** ours: this hubctl's mcp subcommand. foreign: a server with that name that is not hubctl's. */
+  readonly state: "ours" | "absent" | "foreign"
+}
+
+export interface Observation {
+  readonly fields?: readonly ObservedField[]
+  readonly registrations?: readonly ObservedRegistration[]
+}
+
+export interface DriftInput {
+  /** The plan for the current profile and snapshot. */
+  readonly desired: SetupPlan
+  readonly snapshot: DiscoverySnapshot
+  /** The last apply: its plan and journal (only entries that are "done" count as hub's). */
+  readonly applied?: { readonly plan: SetupPlan; readonly journal: TransactionJournal }
+  readonly observed?: Observation
+}
+
+const pathKey = (p: PathRef) => `${p.root}:${p.rel}`
+const samePath = (a: PathRef, b: PathRef) => a.root === b.root && a.rel === b.rel
+const same = (a: unknown, b: unknown) => canonicalJSON(a) === canonicalJSON(b)
+
+/** Every field a plan sets, in plan order. */
+export function managedFields(plan: SetupPlan): ManagedField[] {
+  return plan.actions.flatMap((action): ManagedField[] => {
+    switch (action.kind) {
+      case "merge-config":
+        return action.set.map((s) => ({
+          key: `${pathKey(action.path)}#${s.pointer}`,
+          type: s.pointer.endsWith("/-") ? "array-entry" : "config-value",
+          actionID: action.id,
+          path: action.path,
+          pointer: s.pointer,
+          value: s.value,
+        }))
+      case "register-mcp-server":
+        return [{ key: `mcp:${action.harness}/${action.name}`, type: "mcp-registration", actionID: action.id, path: action.path, registration: { harness: action.harness, name: action.name } }]
+      case "write-file":
+      case "install-service":
+        return [{ key: pathKey(action.path), type: "file", actionID: action.id, path: action.path, sha256: action.sha256 }]
+      default:
+        return []
+    }
+  })
+}
+
+/** The file's digest as discovered: null when it does not exist, undefined when discovery did not look at it. */
+function discoveredDigest(snapshot: DiscoverySnapshot, path: PathRef): string | null | undefined {
+  const abs = resolvePathRef(path, snapshot.roots)
+  if (!abs.ok) return undefined
+  const found = snapshot.configs.find((c) => c.path === abs.value)
+  return found ? found.sha256 : undefined
+}
+
+function validate(input: DriftInput): Result<DriftInput> {
+  const c = new Checker()
+  c.merge("/desired", validateSetupPlan(input.desired))
+  c.merge("/snapshot", validateDiscoverySnapshot(input.snapshot))
+  if (input.applied) {
+    c.merge("/applied/plan", validateSetupPlan(input.applied.plan))
+    c.merge("/applied/journal", validateJournal(input.applied.journal))
+  }
+  if (c.issues.length > 0) return c.result(input)
+  const host = input.snapshot.host.fingerprint
+  if (input.desired.hostFingerprint !== host) c.add("/desired/hostFingerprint", "inconsistent", "the plan is for another host")
+  if (input.applied) {
+    if (input.applied.journal.hostFingerprint !== host || input.applied.plan.hostFingerprint !== host) c.add("/applied/journal/hostFingerprint", "inconsistent", "that history is another host's")
+    if (input.applied.journal.planDigest !== planDigest(input.applied.plan)) c.add("/applied/journal/planDigest", "inconsistent", "the journal records another plan")
+  }
+  return c.result(input)
+}
+
+type Current = { readonly known: false } | { readonly known: true; readonly absent: true } | { readonly known: true; readonly absent: false; readonly value: Json }
+const UNKNOWN: Current = { known: false }
+const ABSENT: Current = { known: true, absent: true }
+const present = (value: Json): Current => ({ known: true, absent: false, value })
+
+export function detectDrift(input: DriftInput): Result<DriftReport> {
+  const checked = validate(input)
+  if (!checked.ok) return checked
+  const { desired, snapshot, observed = {} } = input
+
+  // Hub's applied fields: only actions whose journal entry is done.
+  const done = new Set((input.applied?.journal.entries ?? []).filter((e) => e.status === "done").map((e) => e.actionID))
+  const applied = new Map<string, ManagedField>()
+  if (input.applied) for (const f of managedFields(input.applied.plan)) if (done.has(f.actionID)) applied.set(f.key, f)
+
+  // What hub left in each file (the newest done entry per path).
+  const left = new Map<string, { path: PathRef; after: FileState }>()
+  for (const e of input.applied?.journal.entries ?? []) if (e.status === "done" && e.path && e.after) left.set(pathKey(e.path), { path: e.path, after: e.after })
+  const untouched = (path: PathRef) => {
+    const was = left.get(pathKey(path))
+    const now = discoveredDigest(snapshot, path)
+    return was !== undefined && now !== undefined && (was.after.exists ? now === was.after.sha256 : now === null)
+  }
+  const changedSinceApply = [...left.values()].filter(({ path }) => discoveredDigest(snapshot, path) !== undefined && !untouched(path)).map(({ path }) => path)
+
+  const observedAt = (path: PathRef, pointer: string): Current => {
+    const o = observed.fields?.find((f) => samePath(f.path, path) && f.pointer === pointer)
+    if (!o) return UNKNOWN
+    return o.state === "absent" ? ABSENT : present(o.value)
+  }
+
+  const judge = (f: ManagedField, a: ManagedField | undefined): Omit<FieldDrift, "key" | "actionID" | "path" | "pointer"> => {
+    const userOr = (missing: boolean, currentDigest: string | null) => (missing ? { status: "missing" as const, repairable: true, currentDigest } : { status: "user-changed" as const, repairable: false, currentDigest })
+    switch (f.type) {
+      case "file": {
+        const now = discoveredDigest(snapshot, f.path)
+        if (now === undefined) return { status: "unobserved", repairable: false }
+        if (now === f.sha256) return { status: "in-sync", repairable: false, currentDigest: now }
+        if (a && now === a.sha256) return { status: "outdated", repairable: true, currentDigest: now }
+        return userOr(now === null && !a, now)
+      }
+      case "config-value": {
+        let cur = observedAt(f.path, f.pointer!)
+        if (!cur.known && a && untouched(f.path)) cur = present(a.value!)
+        if (!cur.known) return { status: "unobserved", repairable: false }
+        if (cur.absent) return userOr(!a, null)
+        const currentDigest = digestOf(cur.value)
+        if (same(cur.value, f.value)) return { status: "in-sync", repairable: false, currentDigest }
+        if (a && same(cur.value, a.value)) return { status: "outdated", repairable: true, currentDigest }
+        return { status: "user-changed", repairable: false, currentDigest }
+      }
+      case "array-entry": {
+        let cur = observedAt(f.path, f.pointer!.slice(0, -2))
+        if (!cur.known && a && untouched(f.path)) cur = present([a.value!])
+        if (!cur.known) return { status: "unobserved", repairable: false }
+        if (cur.absent) return userOr(!a, null)
+        const currentDigest = digestOf(cur.value)
+        if (!Array.isArray(cur.value)) return { status: "user-changed", repairable: false, currentDigest }
+        const has = (v: unknown) => (cur.value as Json[]).some((item) => same(item, v))
+        if (has(f.value)) return { status: "in-sync", repairable: false, currentDigest }
+        // An append cannot replace hub's older entry, so an outdated entry is reported, not appended next to it.
+        if (a && has(a.value)) return { status: "outdated", repairable: false, currentDigest }
+        return userOr(!a, currentDigest)
+      }
+      case "mcp-registration": {
+        const reg = f.registration!
+        const o = observed.registrations?.find((r) => r.harness === reg.harness && r.name === reg.name)
+        const state = o?.state ?? (a && untouched(f.path) ? "ours" : undefined)
+        if (state === undefined) return { status: "unobserved", repairable: false }
+        if (state === "ours") return { status: "in-sync", repairable: false, currentDigest: digestOf(state) }
+        return userOr(state === "absent" && !a, digestOf(state))
+      }
+    }
+  }
+
+  const describe = (f: ManagedField) => ({ key: f.key, actionID: f.actionID, path: f.path, ...(f.pointer !== undefined ? { pointer: f.pointer } : {}) })
+  const wanted = managedFields(desired)
+  const fields: FieldDrift[] = [
+    ...wanted.map((f) => ({ ...describe(f), ...judge(f, applied.get(f.key)) })),
+    ...[...applied.values()].filter((a) => !wanted.some((f) => f.key === a.key)).map((a): FieldDrift => ({ ...describe(a), status: "retired", repairable: false })),
+  ]
+  return ok({ fields, userChanged: fields.filter((f) => f.status === "user-changed"), changedSinceApply, inSync: fields.every((f) => f.status === "in-sync"), writes: 0 })
+}
+
+/** The file's current state as a merge precondition, or undefined when discovery did not see the file. */
+function preconditionNow(snapshot: DiscoverySnapshot, path: PathRef): Precondition | undefined {
+  const now = discoveredDigest(snapshot, path)
+  if (now === undefined) return undefined
+  return now === null ? { exists: false } : { exists: true, sha256: now }
+}
+
+/**
+ * The actions that bring hub's repairable fields back to the desired state, and nothing else: a merge sets only
+ * its repairable pointers (losslessly, pinned to the file's current digest), a registration or file is redone only
+ * when it is repairable. Fields the user changed are never in it.
+ */
+export function driftRepairs(report: DriftReport, desired: SetupPlan, snapshot: DiscoverySnapshot): Action[] {
+  const repairable = new Set(report.fields.filter((f) => f.repairable).map((f) => f.key))
+  return desired.actions.flatMap((action): Action[] => {
+    const fields = managedFields({ ...desired, actions: [action] })
+    switch (action.kind) {
+      case "merge-config": {
+        const set = action.set.filter((_, i) => repairable.has(fields[i]!.key))
+        const precondition = preconditionNow(snapshot, action.path)
+        return set.length > 0 && precondition ? [{ ...action, set, precondition }] : []
+      }
+      case "register-mcp-server": {
+        const precondition = preconditionNow(snapshot, action.path)
+        return repairable.has(fields[0]!.key) && precondition ? [{ ...action, precondition }] : []
+      }
+      case "write-file":
+      case "install-service":
+        return repairable.has(fields[0]!.key) ? [action] : []
+      default:
+        return []
+    }
+  })
+}

package/packages/cli/src/bootstrap/profiles/history.ts

@@ -0,0 +1,263 @@
+// Rollback history, derived only from the contract's transaction journals (and, when available, the plans they
+// record by digest). Each record lists what one apply on this host owned: per entry its class, path and before/
+// after digests and modes, never contents and never credentials. Harness installs are annotated with the pinned
+// version they installed and the version they replaced, so "what is installed" and "what a rollback restores" come
+// from the history rather than a guess. v1.1 layout: each version has its own directory (a rolled-back install is
+// removed) and select-harness-version switches the `current` link (a rolled-back select restores the previous link,
+// so the version it records as `previous` is current again).
+//
+// rollbackTo plans undoing every transaction after a target, newest first, with the contract's recovery rules
+// (recoveryDecision) per entry. It simulates the file states as it goes: undoing a newer change to a file yields
+// the state the older change left, so chained changes resolve correctly. A user edit is kept and reported as a
+// conflict (so are older changes to that file). A cleared credential's next state cannot be predicted, so older
+// changes to that file are kept as conflicts too. The plan itself writes nothing.
+import {
+  Checker,
+  EMBEDDED_ASSETS,
+  fail,
+  ok,
+  planDigest,
+  recoveryDecision,
+  validateJournal,
+  validateSetupPlan,
+  type ActionKind,
+  type EntryClass,
+  type FileState,
+  type HarnessID,
+  type InstallHarness,
+  type JournalEntry,
+  type SelectHarnessVersion,
+  type ServiceID,
+  type ServiceManagerID,
+  type PathRef,
+  type RecoveryDecision,
+  type Result,
+  type SetupPlan,
+  type TransactionJournal,
+} from "../contracts/index.ts"
+
+/** One owned change, as the journal records it (digests and modes only). */
+export interface OwnedChange {
+  readonly seq: number
+  readonly actionID: string
+  readonly kind: ActionKind
+  readonly class: EntryClass
+  readonly path?: PathRef
+  readonly before: FileState
+  readonly after?: FileState
+  /** Whether a backup of `before` exists (credentials never have one). */
+  readonly backup: boolean
+  readonly status: JournalEntry["status"]
+}
+
+export interface HarnessInstallRecord {
+  readonly harness: HarnessID
+  readonly version: string
+  /** The pinned artifact digest. */
+  readonly sha256: string
+  /** The version it replaced (what a rollback restores). */
+  readonly previous?: { readonly version: string; readonly sha256: string }
+  readonly status: JournalEntry["status"]
+}
+
+export type TransactionOutcome = "committed" | "rolled-back" | "failed" | "interrupted"
+
+export interface TransactionRecord {
+  readonly txID: string
+  readonly planDigest: string
+  readonly outcome: TransactionOutcome
+  readonly startedAt: number
+  readonly updatedAt: number
+  readonly changes: readonly OwnedChange[]
+  /** Harness installs whose plan is known (an install without its plan has no version to report). */
+  readonly harnesses: readonly HarnessInstallRecord[]
+}
+
+export interface HistoryContext {
+  /** This host's fingerprint: other hosts' journals (a shared home) are refused. */
+  readonly hostFingerprint: string
+  /** Plans the journals applied, matched by digest. */
+  readonly plans?: readonly SetupPlan[]
+}
+
+const OUTCOME: Readonly<Record<TransactionJournal["state"], TransactionOutcome>> = {
+  committed: "committed",
+  "rolled-back": "rolled-back",
+  failed: "failed",
+  prepared: "interrupted",
+  applying: "interrupted",
+  "rolling-back": "interrupted",
+}
+
+const byTime = (a: TransactionJournal, b: TransactionJournal) => a.startedAt - b.startedAt || (a.txID < b.txID ? -1 : a.txID > b.txID ? 1 : 0)
+
+/** Validates the journals (and plans) and returns them oldest first. */
+function checkedJournals(journals: readonly unknown[], context: HistoryContext): Result<{ journals: TransactionJournal[]; plans: Map<string, SetupPlan> }> {
+  const c = new Checker()
+  journals.forEach((j, i) => c.merge(`/journals/${i}`, validateJournal(j)))
+  ;(context.plans ?? []).forEach((p, i) => c.merge(`/plans/${i}`, validateSetupPlan(p)))
+  if (c.issues.length > 0) return c.result(undefined)
+  const valid = journals as TransactionJournal[]
+  const seen = new Set<string>()
+  valid.forEach((j, i) => {
+    if (j.hostFingerprint !== context.hostFingerprint) c.add(`/journals/${i}/hostFingerprint`, "inconsistent", "that journal is another host's")
+    if (seen.has(j.txID)) c.add(`/journals/${i}/txID`, "duplicate", `duplicate transaction ${j.txID}`)
+    seen.add(j.txID)
+  })
+  if (c.issues.length > 0) return c.result(undefined)
+  const plans = new Map((context.plans ?? []).map((p) => [planDigest(p), p]))
+  return ok({ journals: [...valid].sort(byTime), plans })
+}
+
+function installAction(plan: SetupPlan | undefined, actionID: string): InstallHarness | undefined {
+  return plan?.actions.find((a): a is InstallHarness => a.kind === "install-harness" && a.id === actionID)
+}
+
+/** The plan action whose rollback brings back a previous harness version: a v1.1 select, or a v1.0 in-place install. */
+function restoringAction(plan: SetupPlan | undefined, entry: JournalEntry): InstallHarness | SelectHarnessVersion | undefined {
+  if (entry.kind !== "install-harness" && entry.kind !== "select-harness-version") return undefined
+  return plan?.actions.find((a): a is InstallHarness | SelectHarnessVersion => a.kind === entry.kind && a.id === entry.actionID)
+}
+
+function record(journal: TransactionJournal, plan: SetupPlan | undefined): TransactionRecord {
+  const harnesses = journal.entries.flatMap((e): HarnessInstallRecord[] => {
+    const action = e.kind === "install-harness" ? installAction(plan, e.actionID) : undefined
+    if (!action) return []
+    return [{ harness: action.harness, version: action.version, sha256: action.sha256, ...(action.previous ? { previous: action.previous } : {}), status: e.status }]
+  })
+  return {
+    txID: journal.txID,
+    planDigest: journal.planDigest,
+    outcome: OUTCOME[journal.state],
+    startedAt: journal.startedAt,
+    updatedAt: journal.updatedAt,
+    changes: journal.entries.map((e) => ({
+      seq: e.seq,
+      actionID: e.actionID,
+      kind: e.kind,
+      class: e.class,
+      ...(e.path ? { path: e.path } : {}),
+      before: e.before,
+      ...(e.after ? { after: e.after } : {}),
+      backup: e.backup !== undefined,
+      status: e.status,
+    })),
+    harnesses,
+  }
+}
+
+/** This host's transactions, oldest first. */
+export function rollbackHistory(journals: readonly unknown[], context: HistoryContext): Result<TransactionRecord[]> {
+  const checked = checkedJournals(journals, context)
+  if (!checked.ok) return checked
+  return ok(checked.value.journals.map((j) => record(j, checked.value.plans.get(j.planDigest))))
+}
+
+export interface InstalledHarness {
+  readonly version: string
+  readonly sha256: string
+  /** The transaction that installed it. */
+  readonly txID: string
+}
+
+/** The pinned version hub last installed of each harness, from committed transactions only. */
+export function installedHarnesses(history: readonly TransactionRecord[]): Partial<Record<HarnessID, InstalledHarness>> {
+  const installed: Partial<Record<HarnessID, InstalledHarness>> = {}
+  for (const tx of history) {
+    if (tx.outcome !== "committed") continue
+    for (const h of tx.harnesses) if (h.status === "done") installed[h.harness] = { version: h.version, sha256: h.sha256, txID: tx.txID }
+  }
+  return installed
+}
+
+/**
+ * v1.1: the digest of each service unit hub installed and still owns for `manager`, from committed transactions
+ * (newest wins; a later removal drops it). Profile downgrades remove a unit only while it is exactly this.
+ */
+export function installedServiceUnits(history: readonly TransactionRecord[], manager: ServiceManagerID): Partial<Record<ServiceID, string>> {
+  const byFile = new Map(Object.values(EMBEDDED_ASSETS).filter((a) => a.manager === manager).map((a) => [a.installAs, a.service]))
+  const root = manager === "launchd" ? "launch-agents" : "systemd-user"
+  const units: Partial<Record<ServiceID, string>> = {}
+  for (const tx of history) {
+    if (tx.outcome !== "committed") continue
+    for (const change of tx.changes) {
+      if (change.status !== "done" || change.path?.root !== root) continue
+      const service = byFile.get(change.path.rel)
+      if (!service) continue
+      if (change.kind === "install-service" && change.after?.exists && change.after.sha256) units[service] = change.after.sha256
+      if (change.kind === "remove-service") delete units[service]
+    }
+  }
+  return units
+}
+
+export interface RollbackStep {
+  readonly txID: string
+  readonly seq: number
+  readonly actionID: string
+  readonly class: EntryClass
+  readonly path?: PathRef
+  readonly decision: RecoveryDecision
+  /** For a harness restored from its backup: the version that comes back. */
+  readonly restores?: { readonly harness: HarnessID; readonly version: string; readonly sha256: string }
+}
+
+export interface RollbackPlan {
+  /** Newest transaction first; each transaction's entries newest first. */
+  readonly steps: readonly RollbackStep[]
+  /** Steps that keep a user edit (reported, never overwritten). */
+  readonly conflicts: readonly RollbackStep[]
+  /** True when nothing had to be kept: the target state is fully restored. */
+  readonly complete: boolean
+  /** Always zero: this is a plan. */
+  readonly writes: 0
+}
+
+const pathKey = (p: PathRef) => `${p.root}:${p.rel}`
+
+/**
+ * Plans rolling this host back to just after `target` (a committed transaction), or to before every recorded
+ * transaction when `target` is undefined. `stateOf` reports each entry's file as it is now.
+ */
+export function rollbackTo(journals: readonly unknown[], target: string | undefined, stateOf: (entry: JournalEntry) => FileState, context: HistoryContext): Result<RollbackPlan> {
+  const checked = checkedJournals(journals, context)
+  if (!checked.ok) return checked
+  const ordered = checked.value.journals
+  let start = 0
+  if (target !== undefined) {
+    const at = ordered.findIndex((j) => j.txID === target)
+    if (at < 0) return fail("/target", "invalid_value", `no transaction ${target} on this host`)
+    if (ordered[at]!.state !== "committed") return fail("/target", "invalid_value", `${target} did not commit; roll back to a committed transaction`)
+    start = at + 1
+  }
+
+  // Simulated state per path; null: unpredictable (a credential was cleared).
+  const predicted = new Map<string, FileState | null>()
+  const steps: RollbackStep[] = []
+  for (const journal of ordered.slice(start).reverse()) {
+    if (journal.state === "rolled-back") continue
+    const plan = checked.value.plans.get(journal.planDigest)
+    for (const entry of [...journal.entries].reverse()) {
+      const key = entry.path ? pathKey(entry.path) : undefined
+      const known = key !== undefined && predicted.has(key) ? predicted.get(key)! : stateOf(entry)
+      const decision: RecoveryDecision = known === null && entry.class !== "external" ? "keep-user-edit" : recoveryDecision(entry, known ?? { exists: false })
+      if (key !== undefined) {
+        if (decision === "restore-backup") predicted.set(key, entry.before)
+        else if (decision === "remove-created") predicted.set(key, { exists: false })
+        else if (decision === "clear-credential") predicted.set(key, null)
+      }
+      const action = decision === "restore-backup" ? restoringAction(plan, entry) : undefined
+      steps.push({
+        txID: journal.txID,
+        seq: entry.seq,
+        actionID: entry.actionID,
+        class: entry.class,
+        ...(entry.path ? { path: entry.path } : {}),
+        decision,
+        ...(action?.previous ? { restores: { harness: action.harness, ...action.previous } } : {}),
+      })
+    }
+  }
+  const conflicts = steps.filter((s) => s.decision === "keep-user-edit")
+  return ok({ steps, conflicts, complete: conflicts.length === 0, writes: 0 })
+}

package/packages/cli/src/bootstrap/profiles/index.ts

@@ -0,0 +1,11 @@
+// Bootstrap profiles: versioned profile documents, the built-in catalog, profile → desired state, an audit-only
+// verification mode, managed-field drift, rollback history and upgrade/downgrade planning. Everything here is a
+// pure function over the contract documents (packages/cli/src/bootstrap/contracts): snapshots, plans, journals and
+// verified manifests in, reports and typed actions out. Nothing here reads or writes the machine.
+export * from "./versions.ts"
+export * from "./catalog.ts"
+export * from "./desired.ts"
+export * from "./audit.ts"
+export * from "./drift.ts"
+export * from "./history.ts"
+export * from "./upgrade.ts"