dsh-tower 2.0.4 → 2.1.0

package/domain/read/views.js

@@ -0,0 +1,141 @@
+// Pure read-model projections for the status/detail/diff use cases. Loading
+// state, reading the activity tail, and running Git stay in app/read.js.
+// @ts-check
+import { FINDING_STATUSES, MISSION_STATUSES } from '../mission.js'
+import { fullMission, findingSummary, taskCounts } from '../summary.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {object} input
+ * @param {TowerState} input.state
+ * @param {Mission} input.mission
+ * @param {Array<Record<string, unknown>>} input.activity
+ * @returns {object}
+ */
+export function missionDetailView({ state, mission, activity }) {
+  const branch = mission.worktree ? mission.worktree.branch : null
+  const reviews = (state.reviews ?? [])
+    .filter((review) => review.missionId === mission.id || (branch && review.branch === branch))
+    .slice()
+    .sort((left, right) => right.round - left.round)
+  const findings = (state.findings ?? []).filter((finding) => finding.missionId === mission.id)
+  const missionActivity = activity.filter((entry) => entry.missionId === mission.id)
+  return {
+    mission: fullMission(mission),
+    reviews: reviews.slice(0, 10),
+    findings: findings.slice(-10).map((finding) => findingSummary(finding)),
+    activity: missionActivity.slice(-20),
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {TowerState} input.state
+ * @param {string} input.statePath
+ * @param {Array<Record<string, unknown>>} input.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,
+  archivedMissions = 0,
+  archive = null,
+}) {
+  /** @type {Record<string, number>} */
+  const counts = {}
+  for (const status of MISSION_STATUSES) counts[status] = 0
+  for (const mission of state.missions) counts[mission.status] = (counts[mission.status] ?? 0) + 1
+  const openTasks = state.missions.reduce((sum, mission) => sum + taskCounts(mission.tasks ?? []).open, 0)
+  /** @type {Record<string, number>} */
+  const findingsByStatus = {}
+  for (const findingStatus of FINDING_STATUSES) findingsByStatus[findingStatus] = 0
+  for (const finding of state.findings ?? []) {
+    const findingStatus = finding.status ?? 'open'
+    findingsByStatus[findingStatus] = (findingsByStatus[findingStatus] ?? 0) + 1
+  }
+  return {
+    repoRoot: state.repoRoot,
+    commonDir: state.commonDir,
+    statePath,
+    base: state.base,
+    revision: state.revision,
+    towerAgentId: state.towerAgentId ?? null,
+    ownerMissing: !state.towerAgentId,
+    counts,
+    openTasks,
+    roster: (state.roster ?? []).length,
+    messages: (state.messages ?? []).length,
+    unreadTower,
+    findings: (state.findings ?? []).length,
+    findingsByStatus,
+    reviews: (state.reviews ?? []).length,
+    config: {
+      path: config.configPath ?? null,
+      repoConfigPresent: config.repoConfigPresent === true,
+      spawn: {
+        workerPreset: config.spawn?.workerPreset ?? null,
+        reviewerPreset: config.spawn?.reviewerPreset ?? null,
+      },
+    },
+    recentFindings: (state.findings ?? []).slice(-5).map((finding) => ({
+      id: finding.id,
+      type: finding.type,
+      severity: finding.severity,
+      status: finding.status ?? 'open',
+      title: finding.title,
+      missionId: finding.missionId,
+      reportedBy: finding.reportedBy,
+      at: finding.at,
+    })),
+    missions,
+    archivedMissions,
+    ...(archive ? { archive } : {}),
+    activity,
+  }
+}
+
+/**
+ * @param {unknown} maxBytes
+ * @returns {number}
+ */
+export function patchLimit(maxBytes) {
+  return Number.isInteger(maxBytes) && /** @type {number} */ (maxBytes) > 0 ? /** @type {number} */ (maxBytes) : 64 * 1024
+}
+
+/**
+ * @param {object} input
+ * @param {Mission} input.mission
+ * @param {string} input.baseTip
+ * @param {string} input.branchTip
+ * @param {string} input.mergeBase
+ * @param {string[]} input.files
+ * @param {string[]} input.commits
+ * @param {string} input.fullPatch
+ * @param {number} [input.maxBytes]
+ * @returns {object}
+ */
+export function diffView({ mission, baseTip, branchTip, mergeBase, files, commits, fullPatch, maxBytes }) {
+  const limit = patchLimit(maxBytes)
+  return {
+    missionId: mission.id,
+    branch: mission.worktree ? mission.worktree.branch : null,
+    baseTip,
+    branchTip,
+    mergeBase,
+    files,
+    commits,
+    truncated: fullPatch.length > limit,
+    patch: fullPatch.slice(0, limit),
+  }
+}

package/domain/report.js

@@ -0,0 +1,67 @@
+// Pure human-readable mission board.
+// @ts-check
+import { MISSION_STATUSES } from './mission.js'
+import { taskCounts } from './summary.js'
+
+/** @typedef {import('../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {TowerState} state
+ * @param {{ count?: number, unreadable?: boolean, message?: string } | null} [archive]
+ * @returns {string}
+ */
+export function boardMarkdown(state, archive = null) {
+  const lines = []
+  lines.push(`# Tower missions — ${state.repoRoot}`)
+  lines.push('')
+  lines.push(`Base: \`${state.base}\` · revision ${state.revision} · updated ${new Date(state.updatedAt ?? Date.now()).toISOString()}`)
+  /** @type {Record<string, number>} */
+  const counts = {}
+  for (const status of MISSION_STATUSES) counts[status] = 0
+  for (const mission of state.missions) counts[mission.status] += 1
+  lines.push('')
+  lines.push(
+    `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('')
+  lines.push('| Mission | Status | Kind | Title | Owner | Tasks (done/open/dropped) | Latest review | Merged |')
+  lines.push('|---|---|---|---|---|---|---|---|')
+  for (const mission of state.missions) {
+    const tasks = taskCounts(mission.tasks ?? [])
+    const branch = mission.worktree ? mission.worktree.branch : null
+    const reviews = branch ? (state.reviews ?? []).filter((review) => review.branch === branch) : []
+    const latest = reviews.length > 0 ? reviews.reduce((a, b) => (a.round >= b.round ? a : b)) : null
+    const reviewText = latest ? `R${latest.round} ${latest.status}/${latest.mergeVerdict}` : '—'
+    lines.push(
+      `| ${mission.id} | ${mission.status} | ${mission.kind} | ${String(mission.title).replaceAll('|', '\\|')} | ${
+        mission.owner ?? '—'
+      } | ${tasks.done}/${tasks.open}/${tasks.dropped} | ${reviewText} | ${
+        mission.mergedCommit ? mission.mergedCommit.slice(0, 8) : '—'
+      } |`,
+    )
+  }
+  if ((state.roster ?? []).length > 0) {
+    lines.push('')
+    lines.push('## Roster')
+    lines.push('')
+    lines.push('| Name | Role | Mission | State | Agent |')
+    lines.push('|---|---|---|---|---|')
+    for (const entry of state.roster ?? []) {
+      lines.push(
+        `| ${entry.name} | ${entry.role} | ${entry.missionId} | ${entry.state} | \`${entry.agentId}\` |`,
+      )
+    }
+  }
+  lines.push('')
+  return lines.join('\n')
+}

package/domain/roster.js

@@ -0,0 +1,40 @@
+// Pure roster predicates.
+// @ts-check
+
+/** @typedef {import('../types/index.js').RosterEntry} RosterEntry */
+/** @typedef {import('../types/index.js').TowerState} TowerState */
+
+/** @type {readonly string[]} */
+export const ROSTER_INACTIVE_STATES = ['retired', 'failed', 'interrupted', 'missing', 'stale', 'inactive']
+/** @type {ReadonlySet<string>} */
+export const ROSTER_INACTIVE = new Set(ROSTER_INACTIVE_STATES)
+
+/**
+ * @param {TowerState} state
+ * @param {string} missionId
+ * @returns {RosterEntry | undefined}
+ */
+export function liveWorkerEntry(state, missionId) {
+  return (state.roster ?? []).find(
+    (entry) => entry.missionId === missionId && entry.role === 'worker' && !ROSTER_INACTIVE.has(entry.state),
+  )
+}
+
+/**
+ * @param {TowerState} state
+ * @param {string} missionId
+ * @returns {RosterEntry[]}
+ */
+export function workerEntries(state, missionId) {
+  return (state.roster ?? []).filter((entry) => entry.missionId === missionId && entry.role === 'worker')
+}
+
+/**
+ * @param {TowerState} state
+ * @returns {number}
+ */
+export function countLiveWorkers(state) {
+  return (state.roster ?? []).filter(
+    (entry) => entry.role === 'worker' && !ROSTER_INACTIVE.has(entry.state) && entry.state !== 'reserved',
+  ).length
+}

package/domain/scope.js

@@ -0,0 +1,177 @@
+import { TowerToolError } from './errors.js'
+// Pure scope helpers shared by planning and gates.
+// @ts-check
+const GLOB_META = /[*?[{]/
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+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, { caseInsensitive = false } = {}) {
+  const source = foldCase(pattern, caseInsensitive)
+  let out = '^'
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index]
+    if (char === '*') {
+      if (source[index + 1] === '*') {
+        out += '.*'
+        index += 1
+      } else {
+        out += '[^/]*'
+      }
+    } else if (char === '?') {
+      out += '[^/]'
+    } else {
+      out += char.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    }
+  }
+  return new RegExp(`${out}$`)
+}
+
+/**
+ * @param {string[] | null | undefined} scope
+ * @param {string} file
+ * @param {MatchOptions} [options]
+ * @returns {boolean}
+ */
+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 (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
+}
+
+/**
+ * @param {unknown} scope
+ * @param {{ allowEmpty?: boolean }} [options]
+ * @returns {string[]}
+ */
+export function normalizeScope(scope, { allowEmpty = false } = {}) {
+  if (!Array.isArray(scope)) fail('mission scope must be an array of relative globs')
+  if (scope.length === 0 && !allowEmpty) fail('mission scope must not be empty for a build mission')
+  /** @type {string[]} */
+  const out = []
+  for (const raw of scope) {
+    if (typeof raw !== 'string' || raw.trim().length === 0) fail('scope entries must be non-empty strings')
+    const value = raw.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '').trim()
+    if (value.length === 0) fail('scope entries must be non-empty strings')
+    if (value.startsWith('/') || /^[A-Za-z]:/.test(value)) fail(`scope must be relative: ${raw}`)
+    if (value.split('/').some((part) => part === '..')) fail(`scope must not contain "..": ${raw}`)
+    if (!out.includes(value)) out.push(value)
+  }
+  return out
+}
+
+/**
+ * @param {string} pattern
+ * @returns {string}
+ */
+function scopePrefix(pattern) {
+  const index = pattern.search(GLOB_META)
+  const literal = index < 0 ? pattern : pattern.slice(0, index)
+  return literal.replace(/\/+$/, '')
+}
+
+/**
+ * @param {string[]} a
+ * @param {string[]} b
+ * @param {MatchOptions} [options]
+ * @returns {boolean}
+ */
+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)
+      if (!x || !y) return true
+      if (x === y) return true
+      if (x.startsWith(`${y}/`) || y.startsWith(`${x}/`)) return true
+    }
+  }
+  return false
+}

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
+}