feat(versionresolver): support skip-forward resume for orphan ledger versions

readme.md

@@ -118,6 +118,18 @@ Each migration is a `step` with:
 
 Steps execute in **registration order**. The runner validates that the chain is contiguous: `step[N].to === step[N+1].from`. This catches gaps and overlaps at definition time, before any handler runs.
 
+#### Resume modes
+
+When `run()` reads the ledger and finds a current version, it computes a plan: the subset of steps needed to advance from `currentVersion` to `targetVersion`. Two resume modes are supported:
+
+1. **Exact resume** — `currentVersion === step.fromVersion` for some step. The normal case, where the ledger sits exactly at a step's starting point (because the previous step's `to` was written to the ledger when it completed).
+
+2. **Skip-forward resume** — `currentVersion > step.fromVersion` but `currentVersion < step.toVersion`. The **orphan case**: the ledger was stamped to an intermediate version that no registered step starts at. This typically happens when an app configures `freshInstallVersion: targetVersion` across several releases that didn't add any migrations — fresh installs get stamped to whatever `commitinfo.version` was at install time, not to the last step's `to`. When a migration is finally added, those installs have a ledger value that doesn't match any step's `from`.
+
+    In skip-forward mode, the planner picks the first step whose `toVersion > currentVersion` and runs it (and all subsequent steps) normally. The step's handler is being invoked against data that may already be partially in the target shape, so **step handlers must be idempotent** (use `$set` over `$inc`, check existence before insert, filter-based `updateMany` over cursor iteration where possible). A log line at INFO level announces when a step runs in skip-forward mode.
+
+If no step's `toVersion` is greater than `currentVersion` (the ledger is past the end of the chain), the runner throws `TARGET_NOT_REACHABLE`.
+
 ### The ledger
 
 The ledger is the source of truth for "what data version are we at, what steps have been applied, who holds the lock right now." It is persisted in one of two backends:
@@ -339,9 +351,13 @@ Another instance crashed while holding the lock. Wait for `lockTtlMs` (default 1
 
 Two adjacent steps have mismatched versions: `step[N].to !== step[N+1].from`. Steps must form a contiguous chain in registration order. Fix the version on the offending step.
 
-### `CHAIN_NOT_AT_CURRENT`
+### `CHAIN_NOT_AT_CURRENT` (legacy)
 
-The ledger says the data is at version X, but no registered step starts at X. This usually happens when you delete a step that has already been applied to production data. Either keep the step or manually update the ledger's `currentVersion`.
+Retained in the error vocabulary for backward compatibility with downstream consumers that previously branched on it, but **no longer thrown by `computePlan` in normal operation**. Prior versions of smartmigration required an exact `fromVersion === currentVersion` match when resolving the plan; the current planner supports [skip-forward resume](#resume-modes) and handles intermediate-version ledger stamps transparently.
+
+### `TARGET_NOT_REACHABLE`
+
+Either (a) a step in the plan upgrades to a version past `targetVersion` without any step ending exactly at `targetVersion`, or (b) the ledger's `currentVersion` is past the end of the registered chain but has not reached `targetVersion`. Case (a) means the chain has a mid-step that overshoots — add the missing final step or adjust `targetVersion`. Case (b) means the chain needs a new step extending it toward `targetVersion`.
 
 ### S3-only deployments and concurrent instances