dsh-tower 2.1.0-beta.1 → 2.1.0

package/domain/missions/lifecycle.js

@@ -169,8 +169,9 @@ export function applyMissionUpdate({ mission, state, input, config }) {
     const others = state.missions.filter(
       (entry) => entry.id !== mission.id && !TERMINAL.has(entry.status) && entry.kind !== 'survey',
     )
+    const caseInsensitive = state.caseInsensitive === true
     for (const other of others) {
-      if (mission.kind !== 'survey' && scopesOverlap(scope, other.scope)) {
+      if (mission.kind !== 'survey' && scopesOverlap(scope, other.scope, { caseInsensitive })) {
         fail(`widened scope overlaps mission ${other.id}; retire it or add an explicit ordering`)
       }
     }

package/domain/planning.js

@@ -85,11 +85,14 @@ function assertAcyclic(missions) {
 /**
  * Kimi-style heuristic: overlapping build scopes are serialized by an
  * auto-added dependency. It is conservative, not a proof of disjointness.
+ * `caseInsensitive` is the checkout's detected mode (#90); on such a filesystem
+ * `src/Api/**` and `src/api/**` are the same real files and must serialise.
  * @param {Mission[]} newMissions
  * @param {Mission[]} existingMissions
+ * @param {{ caseInsensitive?: boolean }} [options]
  * @returns {void}
  */
-function addAutoDeps(newMissions, existingMissions) {
+function addAutoDeps(newMissions, existingMissions, { caseInsensitive = false } = {}) {
   const openExisting = existingMissions.filter((mission) => !isTerminal(mission.status))
   const all = [...existingMissions, ...newMissions]
   /** @type {Map<string, Mission>} */
@@ -100,7 +103,7 @@ function addAutoDeps(newMissions, existingMissions) {
       const earlier = newMissions[i]
       const later = newMissions[j]
       if (earlier.kind === 'survey' || later.kind === 'survey') continue
-      if (!scopesOverlap(earlier.scope, later.scope)) continue
+      if (!scopesOverlap(earlier.scope, later.scope, { caseInsensitive })) continue
       if (hasDependencyPath(byId, later.id, earlier.id)) continue
       addDependency(later, earlier.id)
     }
@@ -108,7 +111,7 @@ function addAutoDeps(newMissions, existingMissions) {
     if (mission.kind === 'survey') continue
     for (const other of openExisting) {
       if (other.kind === 'survey') continue
-      if (!scopesOverlap(mission.scope, other.scope)) continue
+      if (!scopesOverlap(mission.scope, other.scope, { caseInsensitive })) continue
       if (hasDependencyPath(byId, mission.id, other.id)) continue
       addDependency(mission, other.id)
     }

package/domain/read/views.js

@@ -38,9 +38,20 @@ export function missionDetailView({ state, mission, activity }) {
  * @param {number} input.unreadTower
  * @param {object} input.config
  * @param {object[]} input.missions enriched mission views
+ * @param {number | null} [input.archivedMissions] archived mission count, or null when unreadable
+ * @param {object} [input.archive] archive index view/diagnostic
  * @returns {object}
  */
-export function statusView({ state, statePath, activity, unreadTower, config = {}, missions }) {
+export function statusView({
+  state,
+  statePath,
+  activity,
+  unreadTower,
+  config = {},
+  missions,
+  archivedMissions = 0,
+  archive = null,
+}) {
   /** @type {Record<string, number>} */
   const counts = {}
   for (const status of MISSION_STATUSES) counts[status] = 0
@@ -88,6 +99,8 @@ export function statusView({ state, statePath, activity, unreadTower, config = {
       at: finding.at,
     })),
     missions,
+    archivedMissions,
+    ...(archive ? { archive } : {}),
     activity,
   }
 }

package/domain/report.js

@@ -7,9 +7,10 @@ import { taskCounts } from './summary.js'
 
 /**
  * @param {TowerState} state
+ * @param {{ count?: number, unreadable?: boolean, message?: string } | null} [archive]
  * @returns {string}
  */
-export function boardMarkdown(state) {
+export function boardMarkdown(state, archive = null) {
   const lines = []
   lines.push(`# Tower missions — ${state.repoRoot}`)
   lines.push('')
@@ -23,6 +24,13 @@ export function boardMarkdown(state) {
     `Missions: ${state.missions.length} · ` +
       MISSION_STATUSES.map((status) => `${status} ${counts[status]}`).join(' · '),
   )
+  if (archive) {
+    lines.push(
+      archive.unreadable === true
+        ? `Archived: unreadable (${archive.message ?? 'archive index could not be read'})`
+        : `Archived: ${archive.count ?? 0} terminal mission(s) in archive/ (not listed; use tower_status includeArchived)`,
+    )
+  }
   const openFindings = (state.findings ?? []).filter((finding) => !['fixed', 'wontfix'].includes(finding.status ?? 'open'))
   lines.push(`Findings: ${openFindings.length} open of ${(state.findings ?? []).length}`)
   lines.push('')

package/domain/scope.js

@@ -11,16 +11,32 @@ function fail(message) {
   throw new TowerToolError('invalid-argument', message)
 }
 
+/** @typedef {{ caseInsensitive?: boolean }} MatchOptions */
+
+/**
+ * Case folding is a comparison decision, not a normalisation: the stored scope
+ * text keeps the operator's casing, and callers supply the checkout's detected
+ * mode (#90).
+ * @param {string} value
+ * @param {boolean} caseInsensitive
+ * @returns {string}
+ */
+function foldCase(value, caseInsensitive) {
+  return caseInsensitive ? value.toLowerCase() : value
+}
+
 /**
  * @param {string} pattern
+ * @param {MatchOptions} [options]
  * @returns {RegExp}
  */
-function globToRegExp(pattern) {
+function globToRegExp(pattern, { caseInsensitive = false } = {}) {
+  const source = foldCase(pattern, caseInsensitive)
   let out = '^'
-  for (let index = 0; index < pattern.length; index += 1) {
-    const char = pattern[index]
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index]
     if (char === '*') {
-      if (pattern[index + 1] === '*') {
+      if (source[index + 1] === '*') {
         out += '.*'
         index += 1
       } else {
@@ -38,20 +54,73 @@ function globToRegExp(pattern) {
 /**
  * @param {string[] | null | undefined} scope
  * @param {string} file
+ * @param {MatchOptions} [options]
  * @returns {boolean}
  */
-export function fileInScope(scope, file) {
-  return (scope ?? []).some((pattern) => globToRegExp(pattern).test(file))
+export function fileInScope(scope, file, { caseInsensitive = false } = {}) {
+  const target = foldCase(file, caseInsensitive)
+  return (scope ?? []).some((pattern) => globToRegExp(pattern, { caseInsensitive }).test(target))
 }
 
+/**
+ * The first scope entry that would match `file` if case were folded, or null.
+ * Only used to explain a rejection on a case-sensitive checkout; it never
+ * widens the acceptance test (#90).
+ * @param {string[] | null | undefined} scope
+ * @param {string} file
+ * @returns {string | null}
+ */
+export function caseInsensitiveScopeMatch(scope, file) {
+  const target = file.toLowerCase()
+  return (scope ?? []).find((pattern) => globToRegExp(pattern, { caseInsensitive: true }).test(target)) ?? null
+}
+
+/**
+ * The comparison the helpers use for a detected mode. `null`/`undefined` (a
+ * legacy state that predates detection) keeps the safe, exact default.
+ * @param {unknown} caseInsensitive
+ * @returns {'case-insensitive' | 'case-sensitive'}
+ */
+export function comparisonMode(caseInsensitive) {
+  return caseInsensitive === true ? 'case-insensitive' : 'case-sensitive'
+}
+
+// Mission titles are printable Unicode, not printable ASCII (#88). The hazards
+// the old ASCII range stood in for are made explicit: control/format/surrogate
+// code points, bidi overrides, zero-width characters, and unbounded length.
+const TITLE_MAX_LENGTH = 120
+// U+202A..U+202E (embedding/override) and U+2066..U+2069 (isolate/override).
+const BIDI_OVERRIDE = /[\u202A-\u202E\u2066-\u2069]/
+// U+200B..U+200D (zero-width space/non-joiner/joiner) and U+FEFF (BOM/ZWNBSP).
+const ZERO_WIDTH = /[\u200B-\u200D\uFEFF]/
+// Unicode "Other": controls (Cc), format (Cf), unassigned (Cn), private use
+// (Co) and surrogates (Cs). With the `u` flag a lone surrogate matches Cs,
+// while a valid surrogate pair is one printable code point.
+const CONTROL_OR_FORMAT = /\p{C}/u
+
 /**
  * @param {unknown} title
  * @returns {string}
  */
 export function validateTitle(title) {
   if (typeof title !== 'string' || title.trim().length === 0) fail('mission title is required')
-  if (!/^[\x20-\x7E]+$/.test(title)) fail(`mission title must be printable ASCII: ${JSON.stringify(title)}`)
-  return title.trim()
+  if (BIDI_OVERRIDE.test(title)) {
+    fail(`mission title must not contain bidi override characters (U+202A-U+202E, U+2066-U+2069): ${JSON.stringify(title)}`)
+  }
+  if (ZERO_WIDTH.test(title)) {
+    fail(`mission title must not contain zero-width characters (U+200B-U+200D, U+FEFF): ${JSON.stringify(title)}`)
+  }
+  if (CONTROL_OR_FORMAT.test(title)) {
+    fail(`mission title must not contain control, format, or surrogate characters: ${JSON.stringify(title)}`)
+  }
+  const normalized = title.trim().normalize('NFC')
+  // Count Unicode code points, not UTF-16 units, so astral characters (emoji)
+  // count as one character and the bound is script-independent.
+  const length = [...normalized].length
+  if (length > TITLE_MAX_LENGTH) {
+    fail(`mission title must be at most ${TITLE_MAX_LENGTH} characters after NFC normalization (got ${length})`)
+  }
+  return normalized
 }
 
 /**
@@ -88,11 +157,14 @@ function scopePrefix(pattern) {
 /**
  * @param {string[]} a
  * @param {string[]} b
+ * @param {MatchOptions} [options]
  * @returns {boolean}
  */
-export function scopesOverlap(a, b) {
-  for (const pa of a) {
-    for (const pb of b) {
+export function scopesOverlap(a, b, { caseInsensitive = false } = {}) {
+  for (const rawA of a) {
+    for (const rawB of b) {
+      const pa = foldCase(rawA, caseInsensitive)
+      const pb = foldCase(rawB, caseInsensitive)
       if (pa === pb) return true
       const x = scopePrefix(pa)
       const y = scopePrefix(pb)

package/domain/state/archive.js

@@ -0,0 +1,257 @@
+// Terminal-mission archive decisions (#73).
+//
+// A finished mission keeps its tasks, reviews, findings and completion report,
+// but every mutation rewrites the whole state document. Archiving moves that
+// history into `<git-common-dir>/dsh-tower/archive/` and leaves only an index
+// entry behind, so state.json grows with active work rather than with the
+// repository's total history.
+//
+// This module is pure: it declares the archive document contract, selects what
+// is eligible under the configured policy, and builds the records. Reading and
+// writing the files, and the lock that makes them atomic with state.json, live
+// in `lib/archive.js` and `app/archive.js`.
+// @ts-check
+import { isTerminal } from '../mission.js'
+
+/** @typedef {import('../../types/index.js').Finding} Finding */
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').Review} Review */
+/** @typedef {import('../../types/index.js').TowerConfig} TowerConfig */
+
+/** The archive document version. It is independent of `SCHEMA_VERSION`. */
+export const ARCHIVE_VERSION = 1
+
+export const DAY_MS = 24 * 60 * 60 * 1000
+
+/** @typedef {{ archivedAt: number, archivedYear: number }} ArchiveMeta */
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * A worktree is still live until teardown records its removal. Archiving a
+ * mission whose worktree exists would lose the only record of where it is.
+ * @param {Mission} mission
+ * @returns {boolean}
+ */
+export function hasLiveWorktree(mission) {
+  const record = /** @type {Record<string, any>} */ (mission)
+  return Boolean(record.worktree) && !record.worktreeRemovedAt
+}
+
+/**
+ * When the mission became terminal. Missing timestamps are treated as ancient
+ * so a legacy terminal mission does not stay hot forever; the threshold is
+ * still explicit in config.
+ * @param {Mission} mission
+ * @returns {number}
+ */
+export function terminalTimestamp(mission) {
+  const record = /** @type {Record<string, any>} */ (mission)
+  for (const value of [record.mergedAt, record.abandonedAt, record.updatedAt]) {
+    if (typeof value === 'number' && Number.isFinite(value)) return value
+  }
+  return 0
+}
+
+/**
+ * Select the terminal missions the policy wants moved out of state.json.
+ *
+ * Eligibility:
+ *   - status is `merged` or `abandoned` (terminal);
+ *   - the worktree is gone (never provisioned, or removed by teardown);
+ *   - the caller did not protect it (open batch members, live agents).
+ *
+ * Triggers:
+ *   - `force` archives every eligible mission (tower_teardown);
+ *   - otherwise a mission older than `afterDays` is archived, and when the hot
+ *     terminal count exceeds `maxMissions`, the oldest eligible missions are
+ *     archived until the count fits the cap.
+ *
+ * @param {Mission[]} missions
+ * @param {Partial<TowerConfig['archive']>} [policy]
+ * @param {{ now?: number, force?: boolean, protectedIds?: Iterable<string> }} [options]
+ * @returns {Mission[]}
+ */
+export function selectForArchive(missions, policy = {}, options = {}) {
+  if (policy?.enabled === false) return []
+  const now = Number.isFinite(options.now) ? /** @type {number} */ (options.now) : Date.now()
+  const protectedIds = new Set(options.protectedIds ?? [])
+  const afterDays = Number.isFinite(policy?.afterDays) ? /** @type {number} */ (policy.afterDays) : 30
+  const maxMissions = Number.isFinite(policy?.maxMissions) ? /** @type {number} */ (policy.maxMissions) : 100
+  const eligible = missions.filter(
+    (mission) => isTerminal(mission.status) && !hasLiveWorktree(mission) && !protectedIds.has(mission.id),
+  )
+  if (eligible.length === 0) return []
+  if (options.force === true) return eligible
+
+  const selected = new Set()
+  const cutoff = now - Math.max(0, afterDays) * DAY_MS
+  for (const mission of eligible) {
+    if (terminalTimestamp(mission) <= cutoff) selected.add(mission.id)
+  }
+  if (eligible.length > maxMissions) {
+    const oldest = [...eligible].sort((left, right) => terminalTimestamp(left) - terminalTimestamp(right))
+    for (let index = 0; index < oldest.length - maxMissions; index += 1) selected.add(oldest[index].id)
+  }
+  return missions.filter((mission) => selected.has(mission.id))
+}
+
+/**
+ * Review records that belong to one mission, by id or by its branch.
+ * @param {Mission} mission
+ * @param {Review[] | null | undefined} reviews
+ * @returns {Review[]}
+ */
+export function linkedReviews(mission, reviews) {
+  const branch = /** @type {Record<string, any>} */ (mission).worktree?.branch ?? null
+  return (reviews ?? []).filter(
+    (review) => review.missionId === mission.id || (branch !== null && review.branch === branch),
+  )
+}
+
+/**
+ * @param {Mission} mission
+ * @param {Finding[] | null | undefined} findings
+ * @returns {Finding[]}
+ */
+export function linkedFindings(mission, findings) {
+  return (findings ?? []).filter((finding) => finding.missionId === mission.id)
+}
+
+/**
+ * Closed findings are historical; open/triaged findings stay in state.json so
+ * `tower_findings` keeps showing actionable work even after its mission is
+ * archived. The archive entry still carries a snapshot of every linked finding.
+ * @param {Finding} finding
+ * @returns {boolean}
+ */
+export function isClosedFinding(finding) {
+  return finding.status === 'fixed' || finding.status === 'wontfix'
+}
+
+/** UTC year used for `archive/<year>.json`. @param {number} now @returns {number} */
+export function archiveYearFor(now) {
+  return new Date(now).getUTCFullYear()
+}
+
+/**
+ * The compact entry written to `archive/index.json` (and referenced by
+ * `tower_status`). It carries enough fields to keep ordering, dependency
+ * lookups and mission-id allocation working without loading a year file.
+ * @param {Mission} mission
+ * @param {ArchiveMeta} meta
+ * @returns {Record<string, any>}
+ */
+export function archiveIndexEntry(mission, meta) {
+  const record = /** @type {Record<string, any>} */ (mission)
+  const branch = record.worktree?.branch ?? record.branch ?? null
+  return {
+    id: mission.id,
+    title: String(record.title ?? mission.id),
+    status: mission.status,
+    kind: record.kind ?? 'build',
+    scope: Array.isArray(record.scope) ? record.scope : [],
+    deps: Array.isArray(record.deps) ? record.deps : [],
+    owner: record.owner ?? null,
+    branch,
+    mergedCommit: record.mergedCommit ?? null,
+    mergedAt: record.mergedAt ?? null,
+    updatedAt: record.updatedAt ?? null,
+    archivedAt: meta.archivedAt,
+    archivedYear: meta.archivedYear,
+  }
+}
+
+/**
+ * A full archived record. It nests the untouched mission and its linked
+ * reviews/findings so `tower_status missionId` can reproduce the detail view.
+ * @param {Mission} mission
+ * @param {ArchiveMeta & { reviews?: Review[], findings?: Finding[] }} meta
+ * @returns {Record<string, any>}
+ */
+export function archivedEntry(mission, meta) {
+  return {
+    ...archiveIndexEntry(mission, meta),
+    mission,
+    reviews: meta.reviews ?? [],
+    findings: meta.findings ?? [],
+  }
+}
+
+/**
+ * Strip the full payload before writing the index.
+ * @param {Record<string, any>} entry
+ * @returns {Record<string, any>}
+ */
+export function indexEntryFromArchived(entry) {
+  const { mission: _mission, reviews: _reviews, findings: _findings, ...index } = entry
+  return index
+}
+
+/**
+ * Dedupe entries by id, keeping the first occurrence. Archiving is idempotent:
+ * a crash between writing a year file and writing state.json is retried on the
+ * next mutation and must not create a second record.
+ * @template {{ id?: unknown }} T
+ * @param {T[]} entries
+ * @returns {T[]}
+ */
+export function dedupeById(entries) {
+  const seen = new Set()
+  const out = []
+  for (const entry of entries) {
+    const id = entry?.id
+    if (typeof id !== 'string' || seen.has(id)) continue
+    seen.add(id)
+    out.push(entry)
+  }
+  return out
+}
+
+/**
+ * Validate an archive document. Returns the diagnostic string, or null when the
+ * document is structurally usable. A truncated or foreign archive must degrade
+ * to a diagnostic in status/doctor, never to a thrown state-corrupt error.
+ * @param {unknown} document
+ * @param {'index'|'year'} kind
+ * @param {string} [where]
+ * @returns {string | null}
+ */
+export function archiveDocumentError(document, kind, where = '') {
+  if (!isPlainObject(document)) return `tower archive ${kind} is not an object${where}`
+  const record = /** @type {Record<string, any>} */ (document)
+  if (record.archiveVersion !== ARCHIVE_VERSION) {
+    return `tower archive ${kind} has unsupported archiveVersion ${JSON.stringify(record.archiveVersion)}${where}`
+  }
+  if (!Array.isArray(record.missions)) return `tower archive ${kind} has no missions array${where}`
+  const ids = new Set()
+  for (const entry of record.missions) {
+    if (!isPlainObject(entry) || typeof entry.id !== 'string') {
+      return `tower archive ${kind} has an entry without id${where}`
+    }
+    if (ids.has(entry.id)) return `tower archive ${kind} has duplicate mission ${entry.id}${where}`
+    ids.add(entry.id)
+    if (typeof entry.status !== 'string') return `tower archive ${kind} entry ${entry.id} has no status${where}`
+    if (kind === 'year') {
+      if (!isPlainObject(entry.mission) || entry.mission.id !== entry.id) {
+        return `tower archive ${kind} entry ${entry.id} has no full mission${where}`
+      }
+      if (entry.reviews !== undefined && !Array.isArray(entry.reviews)) {
+        return `tower archive ${kind} entry ${entry.id} has no reviews array${where}`
+      }
+      if (entry.findings !== undefined && !Array.isArray(entry.findings)) {
+        return `tower archive ${kind} entry ${entry.id} has no findings array${where}`
+      }
+    }
+    if (kind === 'index' && (!Number.isInteger(entry.archivedYear) || entry.archivedYear < 1970)) {
+      return `tower archive ${kind} entry ${entry.id} has no archivedYear${where}`
+    }
+  }
+  return null
+}

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

@@ -76,6 +76,9 @@ export const StateSchema = Type.Object(
     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()])),
@@ -154,6 +157,9 @@ function firstShapeMessage(state, 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}`