@lmzhen/dsh-evolution-merge 0.48.0 → 0.49.0

package/lib/index.js

@@ -4874,6 +4874,48 @@ async function resolveBody(io, home, ref, rowBody) {
 	return await rowBody();
 }
 //#endregion
+//#region lib/types/domain/state-migrate.js
+/**
+* Migrate v1/v2/v3 merge state to v4. v4 is a no-op; forward-only/needs-repair are reported
+* before attempting anything, so a newer state is never overwritten.
+* @param io - the evolution IO seam.
+* @param home - the evolution home.
+* @param fence - optional home write fence used by the host.
+* @returns the migration outcome.
+*/
+async function migrateMergeStateToV4(io, home, fence) {
+	const v4 = await readV4Readiness(io, home);
+	if (v4.ok) return {
+		ok: true,
+		migrated: false
+	};
+	if (v4.code === "merge-state-forward-only" || v4.code === "merge-state-needs-repair") return {
+		ok: false,
+		code: v4.code,
+		message: v4.message
+	};
+	const v3 = await ensureMergeStateReady(io, home, fence);
+	if (!v3.ok) return {
+		ok: false,
+		code: v3.code,
+		message: v3.message
+	};
+	const normalized = await normalizePairLedger(io, home);
+	if (!normalized.ok) return {
+		ok: false,
+		code: "merge-state-needs-repair",
+		message: normalized.message ?? "v3->v4 normalize failed"
+	};
+	return normalized.backupRef === void 0 ? {
+		ok: true,
+		migrated: normalized.migrated
+	} : {
+		ok: true,
+		migrated: normalized.migrated,
+		backupRef: normalized.backupRef
+	};
+}
+//#endregion
 //#region lib/types/domain/evidence-hash.js
 /** Canonical evidence JSON hash shared with core unit receipts. */
 function canonical(value) {
@@ -10461,37 +10503,27 @@ function apply(ctx, rawConfig = {}) {
 		if (registry === void 0) return;
 		const io = evolutionIoAdapter(() => registry.provider());
 		const home = evolutionHome();
+		const homeFence = ctx.get("evolutionMutationAuthority")?.homeFence;
 		const ready = (async () => {
-			const v4 = await readV4Readiness(io, home);
-			if (v4.ok) return {
+			const migration = await migrateMergeStateToV4(io, home, homeFence);
+			if (!migration.ok) return migration;
+			const loaded = await loadMergeState(io, home);
+			return {
 				ok: true,
 				schema: 3,
-				migrated: false,
+				migrated: migration.migrated,
 				state: {
 					schemaVersion: 3,
-					rows: (await loadMergeState(io, home)).state.rows.map(legacyToV3).filter((row) => row !== null)
+					rows: loaded.state.rows.map(legacyToV3).filter((row) => row !== null)
 				},
 				quarantine: [],
 				report: null
 			};
-			const state = await ensureMergeStateReady(io, home, ctx.get("evolutionMutationAuthority")?.homeFence);
-			if (!state.ok) return v4.code === "merge-state-forward-only" || v4.code === "merge-state-needs-repair" ? {
-				ok: false,
-				code: v4.code,
-				message: v4.message
-			} : state;
-			const normalized = await normalizePairLedger(io, home);
-			return normalized.ok ? state : {
-				ok: false,
-				code: "merge-state-needs-repair",
-				message: normalized.message ?? "v4 normalize failed"
-			};
 		})().catch((error) => ({
 			ok: false,
 			code: "merge-state-migration-blocked",
 			message: error instanceof Error ? error.message : String(error)
 		}));
-		const homeFence = ctx.get("evolutionMutationAuthority")?.homeFence;
 		const runs = newRunRegistry({
 			io,
 			home,

package/lib/types/domain/state-migrate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The one v2/v3→v4 migration seam. The startup gate and the operator CLI both call this,
+ * so a backup/journal fix in one path cannot drift from the other.
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+/** Outcome of the one-time migration. */
+export type MigrateToV4Result = {
+    readonly ok: true;
+    readonly migrated: boolean;
+    readonly backupRef?: string;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
+/**
+ * Migrate v1/v2/v3 merge state to v4. v4 is a no-op; forward-only/needs-repair are reported
+ * before attempting anything, so a newer state is never overwritten.
+ * @param io - the evolution IO seam.
+ * @param home - the evolution home.
+ * @param fence - optional home write fence used by the host.
+ * @returns the migration outcome.
+ */
+export declare function migrateMergeStateToV4(io: EvolutionIoLike, home: string, fence?: {
+    run<T>(body: () => Promise<T>): Promise<T>;
+}): Promise<MigrateToV4Result>;
+//# sourceMappingURL=state-migrate.d.ts.map

package/lib/types/domain/state-migrate.js

@@ -0,0 +1,29 @@
+import { ensureMergeStateReady } from "./state-bootstrap.js";
+import { normalizePairLedger } from "./pair-ledger.js";
+import { readV4Readiness } from "./schema4.js";
+/**
+ * Migrate v1/v2/v3 merge state to v4. v4 is a no-op; forward-only/needs-repair are reported
+ * before attempting anything, so a newer state is never overwritten.
+ * @param io - the evolution IO seam.
+ * @param home - the evolution home.
+ * @param fence - optional home write fence used by the host.
+ * @returns the migration outcome.
+ */
+export async function migrateMergeStateToV4(io, home, fence) {
+    const v4 = await readV4Readiness(io, home);
+    if (v4.ok)
+        return { ok: true, migrated: false };
+    if (v4.code === 'merge-state-forward-only' || v4.code === 'merge-state-needs-repair') {
+        return { ok: false, code: v4.code, message: v4.message };
+    }
+    const v3 = await ensureMergeStateReady(io, home, fence);
+    if (!v3.ok)
+        return { ok: false, code: v3.code, message: v3.message };
+    const normalized = await normalizePairLedger(io, home);
+    if (!normalized.ok)
+        return { ok: false, code: 'merge-state-needs-repair', message: normalized.message ?? 'v3->v4 normalize failed' };
+    return normalized.backupRef === undefined
+        ? { ok: true, migrated: normalized.migrated }
+        : { ok: true, migrated: normalized.migrated, backupRef: normalized.backupRef };
+}
+//# sourceMappingURL=state-migrate.js.map

package/lib/types/index.js

@@ -8,7 +8,7 @@ import { authorityFrom, createSubagentChannel, evolutionHome, evolutionIoAdapter
 import { newSkillLibrary } from '@lmzhen/dsh-evolution-core/skills';
 import { registerHostRoutes } from '@lmzhen/dsh-evolution-core/http-routes';
 import { loadMergeState } from "./state.js";
-import { pairLedger, normalizePairLedger } from "./domain/pair-ledger.js";
+import { pairLedger } from "./domain/pair-ledger.js";
 import { legacyToV3 } from "./domain/row-v3-bridge.js";
 import { readV4Readiness } from "./domain/schema4.js";
 import { readMergeSnapshot } from "./domain/merge-snapshot.js";
@@ -27,7 +27,7 @@ import { buildDoctorView } from "./surface/merge-view.js";
 import { mergeDoctorFact } from "./doctor.js";
 import { commandError, formatMergeError } from "./domain/errors.js";
 import { resolveBody } from "./surface/body.js";
-import { ensureMergeStateReady } from "./domain/state-bootstrap.js";
+import { migrateMergeStateToV4 } from "./domain/state-migrate.js";
 import { recoverCommitUnits } from "./recovery-coordinator.js";
 import { pairKey, rowIdOf } from "./contracts.js";
 import { makeMergeRoutes } from "./merge-routes.js";
@@ -171,19 +171,14 @@ export function apply(ctx, rawConfig = {}) {
             return;
         const io = evolutionIoAdapter(() => registry.provider());
         const home = evolutionHome();
+        const homeFence = ctx.get('evolutionMutationAuthority')?.homeFence;
         const ready = (async () => {
-            const v4 = await readV4Readiness(io, home);
-            if (v4.ok) {
-                const loaded = await loadMergeState(io, home);
-                return { ok: true, schema: 3, migrated: false, state: { schemaVersion: 3, rows: loaded.state.rows.map(legacyToV3).filter((row) => row !== null) }, quarantine: [], report: null };
-            }
-            const state = await ensureMergeStateReady(io, home, ctx.get('evolutionMutationAuthority')?.homeFence);
-            if (!state.ok)
-                return v4.code === 'merge-state-forward-only' || v4.code === 'merge-state-needs-repair' ? { ok: false, code: v4.code, message: v4.message } : state;
-            const normalized = await normalizePairLedger(io, home);
-            return normalized.ok ? state : { ok: false, code: 'merge-state-needs-repair', message: normalized.message ?? 'v4 normalize failed' };
+            const migration = await migrateMergeStateToV4(io, home, homeFence);
+            if (!migration.ok)
+                return migration;
+            const loaded = await loadMergeState(io, home);
+            return { ok: true, schema: 3, migrated: migration.migrated, state: { schemaVersion: 3, rows: loaded.state.rows.map(legacyToV3).filter((row) => row !== null) }, quarantine: [], report: null };
         })().catch(error => ({ ok: false, code: 'merge-state-migration-blocked', message: error instanceof Error ? error.message : String(error) }));
-        const homeFence = ctx.get('evolutionMutationAuthority')?.homeFence;
         const runs = newRunRegistry({ io, home, warn: (message) => { ctx.logger.warn(message); }, ...(homeFence === undefined ? {} : { fence: homeFence }) });
         ctx.effect(() => {
             const host = ctx;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-merge",
   "description": "Skill auto-merge domain: screening, two-round authoring, queues and commit orchestration (community build)",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "publishConfig": {
     "access": "public"
   },
@@ -13,6 +13,9 @@
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
+  "bin": {
+    "dsh-evolution-merge-migrate": "scripts/merge-migrate.mjs"
+  },
   "exports": {
     ".": {
       "types": "./lib/types/index.d.ts",
@@ -26,6 +29,9 @@
     "lib/**/*.js",
     "lib/types/**/*.d.ts",
     "data/**/*",
+    "scripts/merge-migrate.mjs",
+    "scripts/merge-restore.mjs",
+    "scripts/merge-backup.mjs",
     "package.json"
   ],
   "license": "MIT",
@@ -34,9 +40,9 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.5",
-    "@lmzhen/dsh-evolution-core": "^0.48.0",
-    "@lmzhen/dsh-evolution-commands": "^0.48.0",
-    "@lmzhen/dsh-evolution-merge-engine": "0.48.0"
+    "@lmzhen/dsh-evolution-core": "^0.49.0",
+    "@lmzhen/dsh-evolution-commands": "^0.49.0",
+    "@lmzhen/dsh-evolution-merge-engine": "0.49.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5"

package/scripts/merge-backup.mjs

@@ -0,0 +1,31 @@
+import { createHash } from 'node:crypto'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+const args = new Map()
+for (let i = 2; i < process.argv.length; i += 2) args.set(process.argv[i], process.argv[i + 1])
+const home = args.get('--home')
+const out = args.get('--out')
+if (!home || !out) { console.error('usage: node scripts/merge-backup.mjs --home <home> --out <dir> [--quiesce <json>]'); process.exit(2) }
+const quiesce = args.get('--quiesce')
+if (!quiesce) { console.error('backup refused: --quiesce <json> required (stop plugin or fence writer)'); process.exit(2) }
+try { if (JSON.parse(readFileSync(quiesce, 'utf8')).stopped !== true) { console.error('backup refused: writer not stopped'); process.exit(3) } } catch { console.error('backup refused: unreadable quiesce marker'); process.exit(3) }
+const sha = file => createHash('sha256').update(readFileSync(file)).digest('hex')
+const roots = ['merge/merge-state.json', 'runs.json', 'merge/receipts', 'merge/journals', 'merge/runs', 'merge/snapshots']
+const files = []
+function walk(path) {
+  if (!existsSync(path)) return
+  const stat = statSync(path)
+  if (stat.isDirectory()) { for (const name of readdirSync(path)) walk(join(path, name)); return }
+  const rel = relative(home, path).replace(/\\/g, '/')
+  files.push({ path: rel, bytes: stat.size, sha256: sha(path) })
+}
+for (const root of roots) walk(join(home, root))
+mkdirSync(out, { recursive: true })
+for (const file of files) {
+  const target = join(out, file.path)
+  mkdirSync(dirname(target), { recursive: true })
+  copyFileSync(join(home, file.path), target)
+}
+const manifest = { schemaVersion: 1, createdAt: new Date().toISOString(), home, quiesce: { path: quiesce, sha256: sha(quiesce) }, files }
+writeFileSync(join(out, 'backup-manifest.json'), JSON.stringify(manifest, null, 2) + '\n')
+console.log('MERGE BACKUP OK files=' + files.length + ' out=' + out)

package/scripts/merge-migrate.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * One-time merge state migration: v1/v2 -> v3 -> v4, with a home-level lock.
+ *
+ * The runtime used to do v2->v3 on mount and v3->v4 on the first write. That left the old
+ * readers in the hot path and gave an operator no backup/dry-run/restore story. This CLI is
+ * the explicit entry: it reuses the SAME domain migrations (ensureMergeStateReady and
+ * normalizePairLedger), so it cannot drift from the runtime.
+ *
+ * Usage:
+ *   merge-migrate --home <dir> [--dry-run] [--apply] [--restore <backup-dir>] [--json]
+ *
+ * Stop every host that has this home open before --apply/--restore: the lock only serializes
+ * this CLI, not a mounted plugin.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = dirname(fileURLToPath(import.meta.url))
+const argv = process.argv.slice(2)
+const value = (flag) => {
+  const index = argv.indexOf(flag)
+  return index >= 0 ? argv[index + 1] : undefined
+}
+const homeArg = value('--home')
+if (homeArg === undefined || homeArg === '') {
+  console.error('usage: merge-migrate --home <dir> [--dry-run] [--apply] [--restore <backup-dir>] [--json]')
+  process.exit(2)
+}
+const home = resolve(homeArg)
+const apply = argv.includes('--apply')
+const restoreAt = argv.indexOf('--restore')
+const restore = restoreAt >= 0 ? argv[restoreAt + 1] : undefined
+if (restoreAt >= 0 && (restore === undefined || restore === '' || restore.startsWith('--'))) {
+  console.error('usage: merge-migrate --home <dir> [--dry-run] [--apply] [--restore <backup-dir>] [--json]')
+  process.exit(2)
+}
+const dryRun = argv.includes('--dry-run') || (!apply && restoreAt < 0)
+const asJson = argv.includes('--json')
+const lockDir = join(home, 'merge', '.migrate-lock')
+const LOCK_TTL_MS = 60 * 60 * 1000
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error?.code === 'EPERM'
+  }
+}
+
+function acquireLock() {
+  mkdirSync(join(home, 'merge'), { recursive: true })
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      mkdirSync(lockDir)
+      writeFileSync(join(lockDir, 'owner.json'), JSON.stringify({ pid: process.pid, at: new Date().toISOString() }) + '\n')
+      return
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      let owner = null
+      try { owner = JSON.parse(readFileSync(join(lockDir, 'owner.json'), 'utf8')) } catch { /* stale/incomplete */ }
+      const age = Date.now() - statSync(lockDir).mtimeMs
+      if (owner !== null && pidAlive(owner.pid) && age < LOCK_TTL_MS) {
+        const failure = { ok: false, code: 'migration-locked', message: 'another process owns ' + lockDir + ' (pid ' + String(owner.pid) + ')' }
+        if (asJson) console.log(JSON.stringify(failure, null, 2))
+        else console.error('merge-migrate: ' + failure.message)
+        process.exit(3)
+      }
+      rmSync(lockDir, { recursive: true, force: true })
+    }
+  }
+  throw new Error('could not acquire ' + lockDir)
+}
+
+if (restore !== undefined && restore !== '') {
+  if (dryRun && !apply) {
+    const report = { ok: true, dryRun: true, restore }
+    if (asJson) console.log(JSON.stringify(report, null, 2))
+    else console.log('DRY RUN: would restore ' + restore + ' into ' + home + ' (stop the host first)')
+    process.exit(0)
+  }
+  acquireLock()
+  let restoreStatus = 1
+  try {
+    const result = spawnSync(process.execPath, [join(scriptDir, 'merge-restore.mjs'), '--home', home, '--backup', restore], { stdio: 'inherit' })
+    restoreStatus = result.status ?? 1
+  } finally {
+    rmSync(lockDir, { recursive: true, force: true })
+  }
+  process.exit(restoreStatus)
+}
+
+async function inspect() {
+  let raw = null
+  try { raw = readFileSync(join(home, 'merge', 'merge-state.json'), 'utf8') } catch { /* unreadable is reported below */ }
+  let schema = null
+  let rows = 0
+  try {
+    const parsed = raw === null ? null : JSON.parse(raw)
+    schema = parsed?.schemaVersion ?? null
+    rows = Array.isArray(parsed?.rows) ? parsed.rows.length : 0
+  } catch { /* malformed is a blocker */ }
+  const v4 = schema === 4
+    ? { ok: true, rows }
+    : { ok: false, code: 'merge-state-migration-required', message: 'state is not v4' }
+  const v3 = schema === 3
+    ? { ok: true, rows }
+    : { ok: false, code: 'merge-state-migration-required', message: 'state is not v3 readable' }
+  return { home, state: { present: raw !== null, schema, rows }, v4, v3 }
+}
+
+if (dryRun && !apply) {
+  const report = { ok: true, dryRun: true, ...await inspect() }
+  if (asJson) console.log(JSON.stringify(report, null, 2))
+  else console.log('DRY RUN ' + JSON.stringify(report.state) + ' v4=' + JSON.stringify(report.v4) + ' v3=' + JSON.stringify(report.v3))
+  process.exit(0)
+}
+
+const core = await import('@lmzhen/dsh-evolution-core')
+const io = core.nodeEvolutionIo()
+const { migrateMergeStateToV4 } = await import('../lib/types/domain/state-migrate.js')
+const { readV4Readiness } = await import('../lib/types/domain/schema4.js')
+
+acquireLock()
+let exitCode = 0
+try {
+  const before = await inspect()
+  const beforeV4 = await readV4Readiness(io, home)
+  if (before.state.schema === 4 && beforeV4.ok) {
+    const report = { ok: true, applied: false, reason: 'already-v4', before }
+    if (asJson) console.log(JSON.stringify(report, null, 2))
+    else console.log('MIGRATE OK already v4 rows=' + String(beforeV4.state.rows.length))
+  } else {
+    const backupDir = value('--backup') ?? join(home, 'merge', '.backup', 'pre-migrate-' + new Date().toISOString().replace(/[:.]/g, '-'))
+    const quiesce = join(home, 'merge', '.migrate-quiesce.json')
+    writeFileSync(quiesce, JSON.stringify({ stopped: true, at: new Date().toISOString() }) + '\n')
+    try {
+      const backedUp = spawnSync(process.execPath, [join(scriptDir, 'merge-backup.mjs'), '--home', home, '--out', backupDir, '--quiesce', quiesce], { stdio: 'inherit' })
+      if (backedUp.status !== 0) throw new Error('backup failed with exit ' + String(backedUp.status))
+    } finally {
+      rmSync(quiesce, { force: true })
+    }
+    const migration = await migrateMergeStateToV4(io, home)
+    if (!migration.ok) throw new Error(migration.code + ': ' + migration.message)
+    const after = await inspect()
+    const afterV4 = await readV4Readiness(io, home)
+    if (!afterV4.ok) throw new Error(afterV4.code + ': ' + afterV4.message)
+    const report = { ok: true, applied: true, migrated: migration.migrated, backupRef: migration.backupRef, backupDir, before, after }
+    if (asJson) console.log(JSON.stringify(report, null, 2))
+    else console.log('MIGRATE OK v2/v3 -> v4 rows=' + String(afterV4.state.rows.length) + ' backup=' + backupDir + (migration.backupRef === undefined ? '' : ' pre1b=' + migration.backupRef))
+  }
+} catch (error) {
+  const failure = { ok: false, code: 'migration-failed', message: error instanceof Error ? error.message : String(error) }
+  if (asJson) console.log(JSON.stringify(failure, null, 2))
+  else console.error('merge-migrate: ' + failure.message)
+  exitCode = 1
+} finally {
+  rmSync(lockDir, { recursive: true, force: true })
+}
+process.exit(exitCode)

package/scripts/merge-restore.mjs

@@ -0,0 +1,36 @@
+import { createHash } from 'node:crypto'
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs'
+import { dirname, join, resolve, sep } from 'node:path'
+import { tmpdir } from 'node:os'
+const args = new Map()
+for (let i = 2; i < process.argv.length; i += 2) args.set(process.argv[i], process.argv[i + 1])
+const home = args.get('--home')
+const backup = args.get('--backup')
+if (!home || !backup) { console.error('usage: node scripts/merge-restore.mjs --home <home> --backup <dir>'); process.exit(2) }
+const manifest = JSON.parse(readFileSync(join(backup, 'backup-manifest.json'), 'utf8'))
+const sha = file => createHash('sha256').update(readFileSync(file)).digest('hex')
+const safe = rel => { const target = resolve(home, rel); const base = resolve(home) + sep; if (!target.startsWith(base)) throw new Error('unsafe backup path: ' + rel); return target }
+for (const file of manifest.files) {
+  const source = join(backup, file.path)
+  if (!existsSync(source)) throw new Error('missing backup file: ' + file.path)
+  if (sha(source) !== file.sha256 || statSync(source).size !== file.bytes) throw new Error('backup hash mismatch: ' + file.path)
+  safe(file.path)
+}
+const temp = mkdtempSync(join(tmpdir(), 'dsh-merge-restore-'))
+try {
+  for (const file of manifest.files) {
+    const source = join(backup, file.path)
+    const staged = join(temp, file.path)
+    mkdirSync(dirname(staged), { recursive: true })
+    copyFileSync(source, staged)
+  }
+  for (const file of manifest.files) {
+    const target = safe(file.path)
+    mkdirSync(dirname(target), { recursive: true })
+    if (existsSync(target)) renameSync(target, target + '.pre-restore')
+    copyFileSync(join(temp, file.path), target)
+  }
+  console.log('MERGE RESTORE OK files=' + manifest.files.length)
+} finally {
+  rmSync(temp, { recursive: true, force: true })
+}