dsh-tower 2.0.4 → 2.1.0

package/domain/state/migrations.js

@@ -0,0 +1,145 @@
+// State-schema migrations (#72).
+//
+// The state file is a durable contract, so a version move is a migration, never
+// a corruption. This module is the single place a future version is added: bump
+// `SCHEMA_VERSION` in `../mission.js`, append one `{ from, to, migrate }` entry
+// here, and every load path picks it up.
+//
+// Each `migrate` is a pure function: it receives a parsed document and returns a
+// new one. It must not read the filesystem, mutate its argument, read the clock,
+// or throw for data it can normalise. A step that throws becomes
+// `[tower:state-migration-failed]` and the original file is left byte-identical.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { SCHEMA_VERSION } from '../mission.js'
+
+/** @typedef {{ from: number, to: number, migrate: (state: Record<string, any>) => Record<string, any> }} StateMigration */
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * v1 -> v2. Documents written before the current schema can omit `revision` and
+ * a mission's `tasks`/`deps` arrays; v2's structural contract requires them.
+ * The step only backfills absent values and never drops data.
+ * @param {Record<string, any>} state
+ * @returns {Record<string, any>}
+ */
+export function migrateV1ToV2(state) {
+  const next = { ...state }
+  if (!Number.isInteger(next.revision) || next.revision < 0) next.revision = 0
+  next.missions = (Array.isArray(next.missions) ? next.missions : []).map((mission) => {
+    if (!isPlainObject(mission)) return mission
+    return {
+      ...mission,
+      tasks: Array.isArray(mission.tasks) ? mission.tasks : [],
+      deps: Array.isArray(mission.deps) ? mission.deps : [],
+    }
+  })
+  return next
+}
+
+/**
+ * v2 -> v3. Scope matching gained a detected case mode (#90). Older documents
+ * never recorded one, and a migration must not read the filesystem, so the
+ * field is backfilled as `null` ("not detected"). Comparison then keeps the
+ * safe exact default until the next `tower_init` probes the checkout.
+ * @param {Record<string, any>} state
+ * @returns {Record<string, any>}
+ */
+export function migrateV2ToV3(state) {
+  if (state.caseInsensitive !== undefined) return state
+  return { ...state, caseInsensitive: null }
+}
+
+/** Ordered registry: entry 0 moves 1 -> 2, entry 1 moves 2 -> 3, and so on. */
+export const STATE_MIGRATIONS = Object.freeze([
+  Object.freeze({ from: 1, to: 2, migrate: migrateV1ToV2 }),
+  Object.freeze({ from: 2, to: 3, migrate: migrateV2ToV3 }),
+])
+
+/**
+ * The ordered steps needed to move `from` to `to`, or null when the gap cannot
+ * be crossed. `[]` means the document is already at `to`; a downgrade is never
+ * expressed as a chain.
+ *
+ * @param {unknown} from
+ * @param {number} [to]
+ * @param {readonly StateMigration[]} [migrations]
+ * @returns {StateMigration[] | null}
+ */
+export function migrationChain(from, to = SCHEMA_VERSION, migrations = STATE_MIGRATIONS) {
+  if (!Number.isInteger(from) || /** @type {number} */ (from) < 1) return null
+  if (!Number.isInteger(to) || to < 1) return null
+  if (from === to) return []
+  if (/** @type {number} */ (from) > to) return null
+  const chain = []
+  let version = /** @type {number} */ (from)
+  while (version < to) {
+    const step = migrations.find((entry) => entry.from === version)
+    if (!step || !Number.isInteger(step.to) || step.to <= version) return null
+    chain.push(step)
+    version = step.to
+  }
+  return version === to ? chain : null
+}
+
+/**
+ * Apply the registry to a parsed document. Pure: the input object is never
+ * touched and the returned document has the target `schemaVersion`.
+ *
+ * @param {Record<string, any>} state
+ * @param {{ statePath?: string, to?: number, migrations?: readonly StateMigration[] }} [options]
+ * @returns {{ state: Record<string, any>, from: number, to: number, steps: Array<{ from: number, to: number }> }}
+ */
+export function migrateState(state, options = {}) {
+  const where = options.statePath ? ` at ${options.statePath}` : ''
+  const to = options.to ?? SCHEMA_VERSION
+  const migrations = options.migrations ?? STATE_MIGRATIONS
+  const from = state?.schemaVersion
+  const chain = migrationChain(from, to, migrations)
+  if (!chain || chain.length === 0) {
+    throw new TowerToolError(
+      'state-version-unsupported',
+      `tower state schemaVersion ${String(from)}${where} cannot be migrated to ${to}`,
+      {
+        nextAction: `upgrade dsh-tower when the state was written by a newer release; otherwise restore a state.json this build can read (schemaVersion ${SCHEMA_VERSION})`,
+      },
+    )
+  }
+  /** @type {Record<string, any>} */
+  let current = state
+  /** @type {Array<{ from: number, to: number }>} */
+  const steps = []
+  for (const step of chain) {
+    /** @type {Record<string, any>} */
+    let next
+    try {
+      next = step.migrate(current)
+    } catch (error) {
+      throw new TowerToolError(
+        'state-migration-failed',
+        `state migration v${step.from} -> v${step.to} failed${where}: ${String(error?.message ?? error)}`,
+        {
+          cause: error,
+          nextAction: 'the original state.json was not modified; inspect the pre-migration backup state.json.v<N>.bak and report this failure',
+        },
+      )
+    }
+    if (!isPlainObject(next)) {
+      throw new TowerToolError(
+        'state-migration-failed',
+        `state migration v${step.from} -> v${step.to} returned ${next === null ? 'null' : typeof next}${where}`,
+        { nextAction: 'the original state.json was not modified; report this migration bug' },
+      )
+    }
+    current = { ...next, schemaVersion: step.to }
+    steps.push({ from: step.from, to: step.to })
+  }
+  return { state: current, from: /** @type {number} */ (from), to, steps }
+}

package/domain/state/schema.js

@@ -0,0 +1,239 @@
+// Declarative state-file schema (#56 P4).
+//
+// `StateSchema` describes the structural contract of
+// `<git-common-dir>/dsh-tower/state.json`. Object schemas allow additional
+// properties on purpose: state files are forward/backward compatible and legacy
+// rows carry extra fields. Semantic policy (uniqueness, status/verdict
+// vocabularies, review exemption, worktree records and the revision counter)
+// lives in `./semantics.js`, so this module remains a pure declaration.
+// @ts-check
+import { Type } from '@sinclair/typebox'
+import { Value } from '@sinclair/typebox/value'
+import { SCHEMA_VERSION } from '../mission.js'
+
+const optional = { additionalProperties: true }
+
+const NonNegativeInteger = Type.Integer({ minimum: 0 })
+
+const WorktreeSchema = Type.Object({}, optional)
+
+const MissionSchema = Type.Object(
+  {
+    id: Type.String(),
+    status: Type.Optional(Type.String()),
+    tasks: Type.Array(Type.Unknown()),
+    deps: Type.Array(Type.Unknown()),
+    references: Type.Optional(Type.Array(Type.Unknown())),
+    reviewPolicy: Type.Optional(Type.String()),
+    testRuns: Type.Optional(Type.Array(Type.Unknown())),
+    worktree: Type.Optional(Type.Union([WorktreeSchema, Type.Null()])),
+  },
+  optional,
+)
+
+const RosterEntrySchema = Type.Object(
+  {
+    name: Type.String(),
+    agentId: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  },
+  optional,
+)
+
+const ReviewSchema = Type.Object(
+  {
+    id: Type.String(),
+    status: Type.Optional(Type.String()),
+    mergeVerdict: Type.Optional(Type.String()),
+  },
+  optional,
+)
+
+const FindingSchema = Type.Object(
+  {
+    id: Type.String(),
+    status: Type.Optional(Type.String()),
+  },
+  optional,
+)
+
+const MessageSchema = Type.Object(
+  {
+    id: Type.String(),
+    to: Type.String(),
+    readBy: Type.Array(Type.Unknown()),
+  },
+  optional,
+)
+
+/** Structural contract for one persisted Tower state document. */
+export const StateSchema = Type.Object(
+  {
+    schemaVersion: Type.Literal(SCHEMA_VERSION),
+    revision: Type.Optional(Type.Number()),
+    base: Type.Optional(Type.String()),
+    repoRoot: Type.Optional(Type.String()),
+    commonDir: Type.Optional(Type.String()),
+    createdAt: Type.Optional(Type.Number()),
+    updatedAt: Type.Optional(Type.Number()),
+    dirtyBase: Type.Optional(Type.Boolean()),
+    // Detected once at tower_init (#90). `null` means "not detected yet": the
+    // v2 -> v3 migration backfills it without touching the filesystem.
+    caseInsensitive: Type.Optional(Type.Union([Type.Boolean(), Type.Null()])),
+    towerAgentId: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    snapshotCommit: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    snapshotRef: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    missions: Type.Array(MissionSchema),
+    roster: Type.Optional(Type.Array(RosterEntrySchema)),
+    reviews: Type.Optional(Type.Array(ReviewSchema)),
+    findings: Type.Optional(Type.Array(FindingSchema)),
+    messages: Type.Optional(Type.Array(MessageSchema)),
+    batches: Type.Optional(Type.Array(Type.Unknown())),
+    legacySnapshots: Type.Optional(Type.Array(Type.Unknown())),
+    legacyMaps: Type.Optional(Type.Array(Type.Unknown())),
+    deliveries: Type.Optional(Type.Array(Type.Unknown())),
+    mergeIntent: Type.Optional(Type.Union([Type.Object({}, optional), Type.Null()])),
+    rebaseIntent: Type.Optional(Type.Union([Type.Object({}, optional), Type.Null()])),
+    messageSeq: Type.Optional(NonNegativeInteger),
+    reviewSeq: Type.Optional(NonNegativeInteger),
+    findingSeq: Type.Optional(NonNegativeInteger),
+    batchSeq: Type.Optional(NonNegativeInteger),
+    deliverySeq: Type.Optional(NonNegativeInteger),
+  },
+  optional,
+)
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** @type {readonly string[]} */
+const ARRAY_KEYS = ['batches', 'legacySnapshots', 'legacyMaps', 'deliveries']
+/** @type {readonly string[]} */
+const SEQUENCE_KEYS = ['messageSeq', 'reviewSeq', 'findingSeq', 'batchSeq', 'deliverySeq']
+
+/**
+ * Reproduce the historical `[tower:state-corrupt]` diagnostics for the
+ * structural failures the schema rejects. Keeping them in the state vocabulary
+ * (rather than exposing TypeBox paths) keeps operator-facing messages stable.
+ * @param {Record<string, any>} state
+ * @param {string} where
+ * @returns {string | null}
+ */
+function firstShapeMessage(state, where) {
+  if (state.schemaVersion !== SCHEMA_VERSION) {
+    return `unsupported tower state schemaVersion ${state.schemaVersion}${where}`
+  }
+  if (!Array.isArray(state.missions)) return `tower state has no missions array${where}`
+  for (const mission of state.missions) {
+    if (!isPlainObject(mission) || typeof mission.id !== 'string') return `mission entry without id${where}`
+    const id = mission.id
+    if (!Array.isArray(mission.tasks)) return `mission ${id} has no tasks array${where}`
+    if (!Array.isArray(mission.deps)) return `mission ${id} has no deps array${where}`
+    if (mission.references !== undefined && !Array.isArray(mission.references)) {
+      return `mission ${id} has no references array${where}`
+    }
+    if (mission.reviewPolicy !== undefined && typeof mission.reviewPolicy !== 'string') {
+      return `mission ${id} has unknown reviewPolicy ${mission.reviewPolicy}${where}`
+    }
+    if (mission.testRuns !== undefined && !Array.isArray(mission.testRuns)) {
+      return `mission ${id} has no testRuns array${where}`
+    }
+    if (mission.worktree !== undefined && mission.worktree !== null && !isPlainObject(mission.worktree)) {
+      return `mission ${id} has an invalid worktree record${where}`
+    }
+  }
+  for (const key of ['base', 'repoRoot', 'commonDir']) {
+    if (state[key] !== undefined && typeof state[key] !== 'string') return `tower state ${key} is not a string${where}`
+  }
+  for (const key of ['createdAt', 'updatedAt']) {
+    if (state[key] !== undefined && typeof state[key] !== 'number') {
+      return `tower state ${key} is not a number${where}`
+    }
+  }
+  if (state.dirtyBase !== undefined && typeof state.dirtyBase !== 'boolean') {
+    return `tower state dirtyBase is not a boolean${where}`
+  }
+  if (state.caseInsensitive !== undefined && state.caseInsensitive !== null && typeof state.caseInsensitive !== 'boolean') {
+    return `tower state caseInsensitive is not a boolean${where}`
+  }
+  for (const key of ['towerAgentId', 'snapshotCommit', 'snapshotRef']) {
+    if (state[key] !== undefined && state[key] !== null && typeof state[key] !== 'string') {
+      return `tower state ${key} is not a string or null${where}`
+    }
+  }
+  if (state.revision !== undefined && typeof state.revision !== 'number') {
+    return `tower state revision is not a non-negative integer${where}`
+  }
+  for (const key of ARRAY_KEYS) {
+    if (state[key] !== undefined && !Array.isArray(state[key])) return `tower state ${key} is not an array${where}`
+  }
+  for (const key of SEQUENCE_KEYS) {
+    if (state[key] !== undefined && !(Number.isInteger(state[key]) && state[key] >= 0)) {
+      return `tower state ${key} is not a non-negative integer${where}`
+    }
+  }
+  if (state.mergeIntent !== undefined && state.mergeIntent !== null && !isPlainObject(state.mergeIntent)) {
+    return `tower state mergeIntent is not an object${where}`
+  }
+  if (state.rebaseIntent !== undefined && state.rebaseIntent !== null && !isPlainObject(state.rebaseIntent)) {
+    return `tower state rebaseIntent is not an object${where}`
+  }
+  if (state.roster !== undefined) {
+    if (!Array.isArray(state.roster)) return `tower state roster is not an array${where}`
+    for (const entry of state.roster) {
+      if (!isPlainObject(entry) || typeof entry.name !== 'string') return `invalid roster entry${where}`
+      if (entry.agentId !== undefined && entry.agentId !== null && typeof entry.agentId !== 'string') {
+        return `invalid roster entry${where}`
+      }
+    }
+  }
+  if (state.messages !== undefined) {
+    if (!Array.isArray(state.messages)) return `tower state messages is not an array${where}`
+    for (const message of state.messages) {
+      if (!isPlainObject(message) || typeof message.id !== 'string' || typeof message.to !== 'string') {
+        return `invalid message entry${where}`
+      }
+      if (!Array.isArray(message.readBy)) return `message ${message.id} has no readBy array${where}`
+    }
+  }
+  if (state.findings !== undefined) {
+    if (!Array.isArray(state.findings)) return `tower state findings is not an array${where}`
+    for (const finding of state.findings) {
+      if (!isPlainObject(finding) || typeof finding.id !== 'string') return `invalid finding entry${where}`
+      if (finding.status !== undefined && typeof finding.status !== 'string') {
+        return `finding ${finding.id} has unknown status ${finding.status}${where}`
+      }
+    }
+  }
+  if (state.reviews !== undefined) {
+    if (!Array.isArray(state.reviews)) return `tower state reviews is not an array${where}`
+    for (const review of state.reviews) {
+      if (!isPlainObject(review) || typeof review.id !== 'string') return `invalid review entry${where}`
+      if (review.status !== undefined && typeof review.status !== 'string') {
+        return `review ${review.id} has unknown status ${review.status}${where}`
+      }
+      if (review.mergeVerdict !== undefined && typeof review.mergeVerdict !== 'string') {
+        return `review ${review.id} has unknown merge verdict ${review.mergeVerdict}${where}`
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Pure structural check. Returns the legacy diagnostic, or null when the state
+ * satisfies `StateSchema`. `where` is the already-formatted " at <path>" suffix.
+ * @param {unknown} state
+ * @param {string} [where]
+ * @returns {string | null}
+ */
+export function stateShapeError(state, where = '') {
+  if (!isPlainObject(state)) return `tower state is not an object${where}`
+  if (Value.Check(StateSchema, state)) return null
+  const record = /** @type {Record<string, any>} */ (state)
+  return firstShapeMessage(record, where) ?? `tower state does not match the state schema${where}`
+}

package/domain/state/semantics.js

@@ -0,0 +1,117 @@
+// Semantic state-file checks (#56 P4).
+//
+// `stateShapeError` proves the structural contract; this module owns the policy
+// the shape cannot express: unique ids, status/verdict vocabularies, the review
+// exemption, roster/agent uniqueness, worktree records and the revision
+// counter. Messages keep the historical `[tower:state-corrupt]` wording.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { FINDING_STATUSES, MERGE_VERDICTS, MISSION_STATUSES, REVIEW_STATUS_RE } from '../mission.js'
+
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('state-corrupt', message)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * A worktree record may omit legacy fields, but every field it carries must
+ * keep its documented type.
+ * @param {Record<string, any>} mission
+ * @param {string} where
+ * @returns {void}
+ */
+function assertWorktreeRecord(mission, where) {
+  const worktree = mission.worktree
+  if (worktree === undefined || worktree === null) return
+  const invalid = !isPlainObject(worktree) || ['path', 'branch', 'baseCommit', 'realPath'].some(
+    (key) => worktree[key] !== undefined && typeof worktree[key] !== 'string',
+  ) || (worktree.createdAt !== undefined && typeof worktree.createdAt !== 'number')
+  if (invalid) fail(`mission ${mission.id} has an invalid worktree record${where}`)
+}
+
+/**
+ * @param {unknown} state
+ * @param {string} where
+ * @returns {TowerState}
+ */
+export function assertStateSemantics(state, where) {
+  const record = /** @type {Record<string, any>} */ (state)
+  if (record.revision !== undefined && (!Number.isInteger(record.revision) || record.revision < 0)) {
+    fail(`tower state revision is not a non-negative integer${where}`)
+  }
+  const missionIds = new Set()
+  for (const mission of record.missions) {
+    if (missionIds.has(mission.id)) fail(`duplicate mission id ${mission.id}${where}`)
+    missionIds.add(mission.id)
+    if (!MISSION_STATUSES.includes(mission.status)) {
+      fail(`mission ${mission.id} has unknown status ${mission.status}${where}`)
+    }
+    if (mission.reviewPolicy !== undefined && !['required-clean', 'none'].includes(mission.reviewPolicy)) {
+      fail(`mission ${mission.id} has unknown reviewPolicy ${mission.reviewPolicy}${where}`)
+    }
+    if (mission.reviewPolicy === 'none' && !String(mission.reviewExemptionReason ?? '').trim()) {
+      fail(`mission ${mission.id} has reviewPolicy none without a reason${where}`)
+    }
+    assertWorktreeRecord(mission, where)
+  }
+  if (record.roster !== undefined) {
+    const names = new Set()
+    const agents = new Set()
+    for (const entry of record.roster) {
+      const reserved = entry?.state === 'reserved'
+      if (!entry || typeof entry.name !== 'string' || (!reserved && typeof entry.agentId !== 'string')) {
+        fail(`invalid roster entry${where}`)
+      }
+      if (names.has(entry.name)) fail(`duplicate roster name ${entry.name}${where}`)
+      if (typeof entry.agentId === 'string') {
+        if (agents.has(entry.agentId)) fail(`duplicate roster agent ${entry.agentId}${where}`)
+        agents.add(entry.agentId)
+      }
+      names.add(entry.name)
+    }
+  }
+  if (record.messages !== undefined) {
+    const ids = new Set()
+    for (const message of record.messages) {
+      if (ids.has(message.id)) fail(`duplicate message id ${message.id}${where}`)
+      ids.add(message.id)
+    }
+  }
+  if (record.findings !== undefined) {
+    const ids = new Set()
+    for (const finding of record.findings) {
+      if (ids.has(finding.id)) fail(`duplicate finding id ${finding.id}${where}`)
+      ids.add(finding.id)
+      if (finding.status !== undefined && !FINDING_STATUSES.includes(finding.status)) {
+        fail(`finding ${finding.id} has unknown status ${finding.status}${where}`)
+      }
+    }
+  }
+  if (record.reviews !== undefined) {
+    const ids = new Set()
+    for (const review of record.reviews) {
+      if (ids.has(review.id)) fail(`duplicate review id ${review.id}${where}`)
+      ids.add(review.id)
+      if (!REVIEW_STATUS_RE.test(String(review.status))) {
+        fail(`review ${review.id} has unknown status ${review.status}${where}`)
+      }
+      if (!MERGE_VERDICTS.includes(review.mergeVerdict)) {
+        fail(`review ${review.id} has unknown merge verdict ${review.mergeVerdict}${where}`)
+      }
+    }
+  }
+  return /** @type {TowerState} */ (record)
+}

package/domain/state.js

@@ -0,0 +1,183 @@
+// Pure state-file validation and migration decisions (#56 P4, #72).
+//
+// The structural contract lives in `state/schema.js` (TypeBox), the policy
+// checks in `state/semantics.js`, and the version registry in
+// `state/migrations.js`. This module stays the public entry point so every
+// app/tool import of `domain/state.js` is unchanged.
+//
+// `validateState` proves a document matches the *current* schema.
+// `prepareState` is the load-path decision: it inspects the version, applies the
+// ordered migration registry, then validates the target schema. Both are pure;
+// the side effects (backup, write, activity) live in `lib/stateFile.js`.
+// @ts-check
+import { TowerToolError } from './errors.js'
+import { SCHEMA_VERSION } from './mission.js'
+import { migrationChain, migrateState } from './state/migrations.js'
+import { stateShapeError } from './state/schema.js'
+import { assertStateSemantics } from './state/semantics.js'
+
+/** @typedef {import('../types/index.js').TowerState} TowerState */
+/** @typedef {{ from: number, to: number }} MigrationStep */
+/** @typedef {import('./state/migrations.js').StateMigration} StateMigration */
+
+export { StateSchema, stateShapeError } from './state/schema.js'
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Classify a document's `schemaVersion` without throwing. This is the read path
+ * doctor uses, so it must stay usable on a repository that cannot load.
+ * @param {unknown} state
+ * @param {string} [statePath]
+ * @param {readonly StateMigration[]} [migrations] registry to classify against
+ * @returns {{
+ *   status: 'current'|'migratable'|'newer'|'unmigratable'|'invalid',
+ *   currentVersion: number|null,
+ *   supportedVersion: number,
+ *   migrations: MigrationStep[],
+ *   message?: string,
+ * }}
+ */
+export function inspectStateVersion(state, statePath, migrations) {
+  const where = statePath ? ` at ${statePath}` : ''
+  if (!isPlainObject(state)) {
+    return {
+      status: 'invalid',
+      currentVersion: null,
+      supportedVersion: SCHEMA_VERSION,
+      migrations: [],
+      message: `tower state is not an object${where}`,
+    }
+  }
+  const version = /** @type {Record<string, any>} */ (state).schemaVersion
+  if (!Number.isInteger(version) || version < 1) {
+    return {
+      status: 'invalid',
+      currentVersion: null,
+      supportedVersion: SCHEMA_VERSION,
+      migrations: [],
+      message: `tower state has no usable schemaVersion (${JSON.stringify(version)})${where}`,
+    }
+  }
+  if (version === SCHEMA_VERSION) {
+    return { status: 'current', currentVersion: version, supportedVersion: SCHEMA_VERSION, migrations: [] }
+  }
+  if (version > SCHEMA_VERSION) {
+    return { status: 'newer', currentVersion: version, supportedVersion: SCHEMA_VERSION, migrations: [] }
+  }
+  const chain = migrationChain(version, SCHEMA_VERSION, migrations)
+  if (!chain) {
+    return { status: 'unmigratable', currentVersion: version, supportedVersion: SCHEMA_VERSION, migrations: [] }
+  }
+  return {
+    status: 'migratable',
+    currentVersion: version,
+    supportedVersion: SCHEMA_VERSION,
+    migrations: chain.map((step) => ({ from: step.from, to: step.to })),
+  }
+}
+
+/**
+ * @param {{ status: string, currentVersion: number|null, supportedVersion: number, message?: string }} info
+ * @param {string} [statePath]
+ * @returns {TowerToolError}
+ */
+function versionError(info, statePath) {
+  const where = statePath ? ` at ${statePath}` : ''
+  if (info.status === 'newer') {
+    return new TowerToolError(
+      'state-version-unsupported',
+      `tower state${where} has schemaVersion ${info.currentVersion}, but this build supports ${info.supportedVersion}: it was written by a newer dsh-tower and will not be downgraded`,
+      {
+        nextAction: `upgrade dsh-tower to a release that supports state schemaVersion ${info.currentVersion}; the file was left untouched`,
+      },
+    )
+  }
+  if (info.status === 'migratable') {
+    return new TowerToolError(
+      'state-version-unsupported',
+      `tower state${where} has schemaVersion ${info.currentVersion}; load it through the state loader to migrate it to ${info.supportedVersion}`,
+      { nextAction: 'call any tower tool; mutations apply the migration under the state lock' },
+    )
+  }
+  if (info.status === 'unmigratable') {
+    return new TowerToolError(
+      'state-version-unsupported',
+      `tower state${where} has schemaVersion ${info.currentVersion}, which has no migration to ${info.supportedVersion}`,
+      {
+        nextAction: `restore a state.json written by dsh-tower ${info.supportedVersion}; this build will not guess at an unknown schema`,
+      },
+    )
+  }
+  return new TowerToolError('state-corrupt', info.message ?? `tower state is not usable${where}`)
+}
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('state-corrupt', message)
+}
+
+/**
+ * Prove a document matches the current schema. Any other version is rejected
+ * with a version error rather than corruption; the load path migrates first.
+ * @param {unknown} state
+ * @param {string} [statePath]
+ * @returns {TowerState}
+ */
+export function validateState(state, statePath) {
+  const info = inspectStateVersion(state, statePath)
+  if (info.status !== 'current') throw versionError(info, statePath)
+  const where = statePath ? ` at ${statePath}` : ''
+  const shapeError = stateShapeError(state, where)
+  if (shapeError) fail(shapeError)
+  return assertStateSemantics(state, where)
+}
+
+/**
+ * The pure load-path decision: migrate an older document through the registry,
+ * validate the result against the target schema, then report what happened. The
+ * returned state is the validated migrated document; the caller decides whether
+ * to persist it (only while holding the state lock).
+ *
+ * @param {unknown} state
+ * @param {string} [statePath]
+ * @param {{ migrations?: readonly StateMigration[] }} [options]
+ * @returns {{ state: TowerState, from: number, to: number, migrated: MigrationStep[], changed: boolean }}
+ */
+export function prepareState(state, statePath, options = {}) {
+  const info = inspectStateVersion(state, statePath, options.migrations)
+  if (info.status === 'current') {
+    return {
+      state: validateState(state, statePath),
+      from: SCHEMA_VERSION,
+      to: SCHEMA_VERSION,
+      migrated: [],
+      changed: false,
+    }
+  }
+  if (info.status !== 'migratable') throw versionError(info, statePath)
+  const outcome = migrateState(/** @type {Record<string, any>} */ (state), {
+    statePath,
+    to: info.supportedVersion,
+    migrations: options.migrations,
+  })
+  // Validation runs on the *target* document: a shape that was invalid under
+  // the old schema (a missing `tasks` array, say) may be valid after a backfill,
+  // and validating the target is what proves the migration did its job.
+  return {
+    state: validateState(outcome.state, statePath),
+    from: outcome.from,
+    to: outcome.to,
+    migrated: outcome.steps,
+    changed: true,
+  }
+}