@lmzhen/dsh-evolution-merge 0.30.18 → 0.30.20

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

@@ -0,0 +1,43 @@
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type QuarantinedRow, type V3State } from './migrate-v3.ts';
+export declare function mergeStatePath(home: string): string;
+export declare function v2BackupPath(home: string): string;
+export declare function migrationJournalPath(home: string): string;
+export declare function migrationReportPath(home: string): string;
+export declare function quarantinePath(home: string): string;
+export type StateBlockCode = 'merge-state-migration-required' | 'merge-state-migration-blocked' | 'merge-state-needs-repair' | 'merge-state-forward-only';
+export interface MigrationReport {
+    readonly version: 1;
+    readonly ready: boolean;
+    readonly migrated: boolean;
+    readonly sourceSha256?: string;
+    readonly targetSha256?: string;
+    readonly rows?: number;
+    readonly quarantined?: number;
+    readonly backupReadOnly?: boolean;
+    readonly at: string;
+    readonly steps: readonly string[];
+}
+export type StateReadiness = {
+    readonly ok: true;
+    readonly schema: 3;
+    readonly migrated: boolean;
+    readonly state: V3State;
+    readonly quarantine: readonly QuarantinedRow[];
+    readonly report: MigrationReport | null;
+} | {
+    readonly ok: false;
+    readonly code: StateBlockCode;
+    readonly message: string;
+};
+export declare class StateBlockedError extends Error {
+    readonly readiness: StateReadiness;
+    constructor(readiness: StateReadiness);
+}
+/** Read-only readiness probe. Never migrates, never writes. */
+export declare function readStateReadiness(io: EvolutionIoLike, home: string): Promise<StateReadiness>;
+/** Compatibility name for the v3 gate; 1b-2b switches the lifecycle to v4. */
+export declare const ensureV3Ready: typeof ensureMergeStateReady;
+/** One readiness/migration gate; used by startup and every write entry. */
+export declare function ensureMergeStateReady(io: EvolutionIoLike, home: string): Promise<StateReadiness>;
+//# sourceMappingURL=state-bootstrap.d.ts.map

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

@@ -0,0 +1,267 @@
+import { readTextOrNull } from "./read-probe.js";
+/** G3 Batch -1 state bootstrap: one readiness gate, backup/journal migration. */
+import { createHash } from 'node:crypto';
+import { chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { transactIo } from '@lmzhen/dsh-evolution-core';
+import { migrateV2ToV3 } from "./migrate-v3.js";
+import { isV3Row } from "./row-v3.js";
+import { stagingIndexPath, writeStagingIndex } from "./staging-index.js";
+export function mergeStatePath(home) { return join(home, 'merge', 'merge-state.json'); }
+export function v2BackupPath(home) { return join(home, 'merge', 'merge-state.v2.bak.json'); }
+export function migrationJournalPath(home) { return join(home, 'merge', 'merge-state.migration.json'); }
+export function migrationReportPath(home) { return join(home, 'merge', 'merge-state.migration.report.json'); }
+export function quarantinePath(home) { return join(home, 'merge', 'merge-state.quarantine.json'); }
+export class StateBlockedError extends Error {
+    readiness;
+    constructor(readiness) {
+        super(readiness.ok ? 'merge state is ready' : readiness.code + ': ' + readiness.message);
+        this.name = 'StateBlockedError';
+        this.readiness = readiness;
+    }
+}
+const hash = (text) => createHash('sha256').update(text).digest('hex');
+const json = (value) => JSON.stringify(value, null, 2) + '\n';
+const now = () => new Date().toISOString();
+function blocked(code, message) { return { ok: false, code, message }; }
+function parseBody(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed !== null && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readMarker(body) {
+    const value = body.migration;
+    if (value === undefined)
+        return null;
+    if (value === null || typeof value !== 'object')
+        return null;
+    const marker = value;
+    if (marker.migratedFromV2 !== true || typeof marker.sourceSha256 !== 'string' || typeof marker.targetSha256 !== 'string' || !Array.isArray(marker.staging) || typeof marker.at !== 'string')
+        return null;
+    return marker;
+}
+function rowsSha(rows) {
+    return hash(json({ schemaVersion: 3, rows }));
+}
+async function missingIndex(io, home, staging) {
+    for (const entry of staging)
+        if (!(await io.exists(stagingIndexPath(home, entry.rowId))))
+            return entry.rowId;
+    return null;
+}
+function v3State(body) {
+    const rows = body.rows;
+    if (!Array.isArray(rows) || !rows.every(isV3Row))
+        return null;
+    return { schemaVersion: 3, rows: rows };
+}
+async function readJournal(io, home) {
+    const raw = await readTextOrNull(io, migrationJournalPath(home));
+    if (raw === null)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        if (value.version !== 1 || typeof value.sourceSha256 !== 'string' || typeof value.targetSha256 !== 'string' || !Array.isArray(value.staging))
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+async function readReport(io, home) {
+    const raw = await readTextOrNull(io, migrationReportPath(home));
+    if (raw === null)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        return value.version === 1 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeReport(io, home, report) {
+    await transactIo(io, migrationReportPath(home), () => json(report));
+}
+async function completeJournal(io, home, journal, current) {
+    if (hash(current) !== journal.targetSha256)
+        return blocked('merge-state-needs-repair', 'migration journal does not match the v3 state');
+    for (const entry of journal.staging)
+        await writeStagingIndex(io, home, entry);
+    const report = { version: 1, ready: true, migrated: false, sourceSha256: journal.sourceSha256, targetSha256: journal.targetSha256, rows: journal.rows, quarantined: journal.quarantine.length, at: now(), steps: ['journal:index', 'journal:ready'] };
+    await writeReport(io, home, report);
+    await io.remove(migrationJournalPath(home)).catch(() => { });
+    const body = parseBody(current);
+    const state = body === null ? null : v3State(body);
+    return state === null ? blocked('merge-state-needs-repair', 'v3 state is invalid') : { ok: true, schema: 3, migrated: false, state, quarantine: journal.quarantine, report };
+}
+/** Read-only readiness probe. Never migrates, never writes. */
+export async function readStateReadiness(io, home) {
+    let raw;
+    try {
+        raw = await io.readText(mergeStatePath(home));
+    }
+    catch {
+        return blocked('merge-state-needs-repair', 'state file is unreadable');
+    }
+    if (raw === null)
+        return { ok: true, schema: 3, migrated: false, state: { schemaVersion: 3, rows: [] }, quarantine: [], report: await readReport(io, home) };
+    const body = parseBody(raw);
+    if (body === null)
+        return blocked('merge-state-needs-repair', 'state file is not a JSON object');
+    const version = body.schemaVersion;
+    if (typeof version === 'number' && version > 3)
+        return blocked('merge-state-forward-only', 'state schema ' + String(version) + ' is newer than this build');
+    if (version === 3) {
+        const state = v3State(body);
+        if (state === null)
+            return blocked('merge-state-needs-repair', 'v3 state has an invalid row');
+        const journal = await readJournal(io, home);
+        const report = await readReport(io, home);
+        const marker = readMarker(body);
+        if (body.migration !== undefined && marker === null)
+            return blocked('merge-state-needs-repair', 'migration marker is invalid');
+        if (journal !== null)
+            return blocked('merge-state-migration-blocked', 'migration journal is pending');
+        if (report !== null && report.ready !== true)
+            return blocked('merge-state-migration-blocked', 'migration report is not ready');
+        if (marker !== null && rowsSha(state.rows) === marker.targetSha256) {
+            if (report === null)
+                return blocked('merge-state-migration-blocked', 'migration report is missing');
+            const missing = await missingIndex(io, home, marker.staging);
+            if (missing !== null)
+                return blocked('merge-state-migration-blocked', 'staging index is missing: ' + missing);
+        }
+        return { ok: true, schema: 3, migrated: false, state, quarantine: [], report };
+    }
+    return blocked('merge-state-migration-required', 'v2 state requires v3 migration');
+}
+/** Compatibility name for the v3 gate; 1b-2b switches the lifecycle to v4. */
+export const ensureV3Ready = ensureMergeStateReady;
+/** One readiness/migration gate; used by startup and every write entry. */
+export async function ensureMergeStateReady(io, home) {
+    let outcome;
+    let migrated = false;
+    try {
+        await transactIo(io, mergeStatePath(home), async (current) => {
+            if (current === null) {
+                outcome = { ok: true, schema: 3, migrated: false, state: { schemaVersion: 3, rows: [] }, quarantine: [], report: await readReport(io, home) };
+                return null;
+            }
+            const body = parseBody(current);
+            if (body === null) {
+                outcome = blocked('merge-state-needs-repair', 'state file is not a JSON object');
+                return current;
+            }
+            const version = body.schemaVersion;
+            if (typeof version === 'number' && version > 3) {
+                outcome = blocked('merge-state-forward-only', 'state schema ' + String(version) + ' is newer than this build');
+                return current;
+            }
+            if (version === 3) {
+                const state = v3State(body);
+                if (state === null) {
+                    outcome = blocked('merge-state-needs-repair', 'v3 state has an invalid row');
+                    return current;
+                }
+                const journal = await readJournal(io, home);
+                if (journal !== null) {
+                    outcome = await completeJournal(io, home, journal, current);
+                    return current;
+                }
+                const report = await readReport(io, home);
+                const marker = readMarker(body);
+                if (body.migration !== undefined && marker === null) {
+                    outcome = blocked('merge-state-needs-repair', 'migration marker is invalid');
+                    return current;
+                }
+                if (report !== null && report.ready !== true) {
+                    outcome = blocked('merge-state-migration-blocked', 'migration report is not ready');
+                    return current;
+                }
+                if (marker !== null && rowsSha(state.rows) === marker.targetSha256) {
+                    if (report === null) {
+                        outcome = blocked('merge-state-migration-blocked', 'migration report is missing');
+                        return current;
+                    }
+                    for (const entry of marker.staging)
+                        if (!(await io.exists(stagingIndexPath(home, entry.rowId))))
+                            await writeStagingIndex(io, home, entry);
+                }
+                outcome = { ok: true, schema: 3, migrated: false, state, quarantine: [], report };
+                return current;
+            }
+            const mapped = migrateV2ToV3(body);
+            if (!mapped.ok) {
+                outcome = blocked('merge-state-migration-blocked', mapped.message);
+                return current;
+            }
+            const sourceSha256 = hash(current);
+            const backup = v2BackupPath(home);
+            const existingBackup = await readTextOrNull(io, backup);
+            if (existingBackup !== null && existingBackup !== current) {
+                outcome = blocked('merge-state-migration-blocked', 'v2 backup exists with different bytes');
+                return current;
+            }
+            if (existingBackup === null)
+                await transactIo(io, backup, () => current);
+            try {
+                await chmod(backup, 0o444);
+            }
+            catch {
+                outcome = blocked('merge-state-migration-blocked', 'v2 backup is not read-only');
+                return current;
+            }
+            const staging = [];
+            for (const row of body.rows) {
+                if (typeof row.id !== 'string' || typeof row.pairKey !== 'string' || typeof row.stagingRef !== 'string')
+                    continue;
+                if (row.state !== 'pending' && row.state !== 'approved')
+                    continue;
+                staging.push({
+                    rowId: row.id, pairKey: row.pairKey, ref: row.stagingRef,
+                    expiresAt: typeof row.stagingExpiresAt === 'number' ? row.stagingExpiresAt : Date.now() + 7 * 86_400_000,
+                    ...(typeof row.runId === 'string' ? { runId: row.runId } : {}),
+                    createdAt: typeof row.updatedAt === 'string' && !Number.isNaN(Date.parse(row.updatedAt)) ? Date.parse(row.updatedAt) : Date.now(),
+                });
+            }
+            const marker = { migratedFromV2: true, sourceSha256, targetSha256: rowsSha(mapped.state.rows), staging, at: now() };
+            const targetText = json({ ...mapped.state, migration: marker });
+            const targetSha256 = hash(targetText);
+            const journal = { version: 1, sourceSha256, targetSha256, rows: mapped.state.rows.length, quarantine: mapped.quarantine, staging, backupPath: backup, at: now() };
+            await transactIo(io, migrationJournalPath(home), () => json(journal));
+            for (const entry of staging)
+                await writeStagingIndex(io, home, entry);
+            if (mapped.quarantine.length > 0)
+                await transactIo(io, quarantinePath(home), () => json(mapped.quarantine));
+            const prepared = { version: 1, ready: false, migrated: true, sourceSha256, targetSha256, rows: mapped.state.rows.length, quarantined: mapped.quarantine.length, backupReadOnly: true, at: now(), steps: ['backup', 'journal', 'staging-index', 'quarantine', 'v3-write'] };
+            await writeReport(io, home, prepared);
+            migrated = true;
+            outcome = { ok: true, schema: 3, migrated: true, state: mapped.state, quarantine: mapped.quarantine, report: prepared };
+            return targetText;
+        });
+    }
+    catch (error) {
+        return blocked('merge-state-migration-blocked', 'state migration failed: ' + (error instanceof Error ? error.message : String(error)));
+    }
+    if (outcome === undefined)
+        return blocked('merge-state-migration-blocked', 'state migration did not produce a result');
+    if (migrated && outcome.ok) {
+        try {
+            const report = { ...outcome.report, ready: true, at: now(), steps: ['backup', 'journal', 'staging-index', 'quarantine', 'v3-write', 'ready'] };
+            await writeReport(io, home, report);
+            await io.remove(migrationJournalPath(home)).catch(() => { });
+            outcome = { ...outcome, report };
+        }
+        catch {
+            // The v3 state is committed; leave the journal/report for the next ensure.
+        }
+    }
+    return outcome;
+}
+//# sourceMappingURL=state-bootstrap.js.map

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

@@ -1,15 +1,4 @@
-import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
-import { type QuarantinedRow, type V3State } from './migrate-v3.ts';
-export declare function v2BackupPath(home: string): string;
-export type StateMigration = {
-    readonly ok: true;
-    readonly migrated: boolean;
-    readonly state: V3State;
-    readonly quarantine: readonly QuarantinedRow[];
-} | {
-    readonly ok: false;
-    readonly code: 'state-migration-blocked';
-    readonly message: string;
-};
-export declare function loadOrMigrateStateV3(io: EvolutionIoLike, home: string): Promise<StateMigration>;
+/** G3 schema-3 migration path constants; the only production gate is state-bootstrap. */
+import { v2BackupPath } from './state-bootstrap.ts';
+export { v2BackupPath };
 //# sourceMappingURL=state-v3.d.ts.map

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

@@ -1,80 +1,4 @@
-/** G3 schema-3 state IO: backup v2, map, atomic v3 write. */
-import { chmod } from 'node:fs/promises';
-import { join } from 'node:path';
-import { migrateV2ToV3 } from "./migrate-v3.js";
-import { isV3Row } from "./row-v3.js";
-import { writeStagingIndex } from "./staging-index.js";
-export function v2BackupPath(home) { return join(home, 'merge', 'merge-state.v2.bak.json'); }
-function blocked(message) { return { ok: false, code: 'state-migration-blocked', message }; }
-async function readOnly(path) { try {
-    await chmod(path, 0o444);
-}
-catch { /* io seam without chmod; v2 bytes still preserved */ } }
-export async function loadOrMigrateStateV3(io, home) {
-    const path = join(home, 'merge', 'merge-state.json');
-    const raw = await io.readText(path);
-    if (raw === null)
-        return { ok: true, migrated: false, state: { schemaVersion: 3, rows: [] }, quarantine: [] };
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return blocked('v2 state is not JSON');
-    }
-    if (parsed !== null && typeof parsed === 'object' && parsed.schemaVersion === 3) {
-        const rows = parsed.rows;
-        if (!Array.isArray(rows) || !rows.every(isV3Row))
-            return blocked('v3 state has an invalid row');
-        return { ok: true, migrated: false, state: { schemaVersion: 3, rows }, quarantine: [] };
-    }
-    const mapped = migrateV2ToV3(parsed);
-    if (!mapped.ok)
-        return blocked(mapped.message);
-    const backup = v2BackupPath(home);
-    const existing = await io.readText(backup);
-    if (existing !== null && existing !== raw)
-        return blocked('v2 backup exists with different bytes');
-    if (existing === null) {
-        try {
-            if (io.transact !== undefined)
-                await io.transact(backup, () => raw);
-            else
-                await io.writeText(backup, raw);
-        }
-        catch {
-            return blocked('v2 backup write failed');
-        }
-    }
-    await readOnly(backup);
-    const rawRows = parsed.rows;
-    if (Array.isArray(rawRows)) {
-        for (const row of rawRows) {
-            if (typeof row.id !== 'string' || typeof row.pairKey !== 'string' || typeof row.stagingRef !== 'string')
-                continue;
-            if (row.state !== 'pending' && row.state !== 'approved')
-                continue;
-            await writeStagingIndex(io, home, { rowId: row.id, pairKey: row.pairKey, ref: row.stagingRef, expiresAt: typeof row.stagingExpiresAt === 'number' ? row.stagingExpiresAt : Date.now() + 7 * 86_400_000, ...(typeof row.runId === 'string' ? { runId: row.runId } : {}), createdAt: typeof row.updatedAt === 'string' && !Number.isNaN(Date.parse(row.updatedAt)) ? Date.parse(row.updatedAt) : Date.now() });
-        }
-    }
-    if (mapped.quarantine.length > 0) {
-        try {
-            await io.writeText(join(home, 'merge', 'merge-state.quarantine.json'), JSON.stringify(mapped.quarantine, null, 2) + '\n');
-        }
-        catch {
-            return blocked('quarantine write failed; v3 not written');
-        }
-    }
-    const text = JSON.stringify(mapped.state, null, 2) + '\n';
-    try {
-        if (io.transact !== undefined)
-            await io.transact(path, () => text);
-        else
-            await io.writeText(path, text);
-    }
-    catch {
-        return blocked('v3 state write failed; v2 backup + quarantine retained');
-    }
-    return { ok: true, migrated: true, state: mapped.state, quarantine: mapped.quarantine };
-}
+/** G3 schema-3 migration path constants; the only production gate is state-bootstrap. */
+import { v2BackupPath } from "./state-bootstrap.js";
+export { v2BackupPath };
 //# sourceMappingURL=state-v3.js.map

package/lib/types/domain/undo-journal.d.ts

@@ -0,0 +1,19 @@
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export type UndoPairPhase = 'pending' | 'restore-target' | 'restore-source' | 'receipt' | 'done';
+export interface UndoPairState {
+    readonly pairKey: string;
+    readonly unitId: string;
+    readonly phase: UndoPairPhase;
+    readonly message?: string;
+}
+export interface UndoJournal {
+    readonly version: 1;
+    readonly runId: string;
+    readonly phase: 'prepared' | 'running' | 'settled';
+    readonly pairs: readonly UndoPairState[];
+    readonly updatedAt: string;
+}
+export declare function undoJournalPath(home: string, runId: string): string;
+export declare function readUndoJournal(io: EvolutionIoLike, home: string, runId: string): Promise<UndoJournal | null>;
+export declare function writeUndoJournal(io: EvolutionIoLike, home: string, journal: UndoJournal): Promise<void>;
+//# sourceMappingURL=undo-journal.d.ts.map

package/lib/types/domain/undo-journal.js

@@ -0,0 +1,20 @@
+import { readTextOrNull } from "./read-probe.js";
+/** Per-run undo journal: one pair at a time, durable phase before each write. */
+import { join } from 'node:path';
+import { transactIo } from '@lmzhen/dsh-evolution-core';
+export function undoJournalPath(home, runId) { return join(home, 'merge', 'undo-journal', encodeURIComponent(runId) + '.json'); }
+export async function readUndoJournal(io, home, runId) {
+    const raw = await readTextOrNull(io, undoJournalPath(home, runId));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeUndoJournal(io, home, journal) {
+    await transactIo(io, undoJournalPath(home, journal.runId), () => JSON.stringify(journal, null, 2) + '\n');
+}
+//# sourceMappingURL=undo-journal.js.map

package/lib/types/domain/undo-receipt.d.ts

@@ -0,0 +1,18 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export interface UndoReceipt {
+    readonly version: 1;
+    readonly runId: string;
+    readonly parentRunId?: string;
+    readonly pairKey: string;
+    readonly unitId: string;
+    readonly evidenceSha256: string;
+    readonly target: string;
+    readonly sources: readonly string[];
+    readonly restoredTargetHash: string | null;
+    readonly restoredSourceHashes: Readonly<Record<string, string>>;
+    readonly at: number;
+}
+export declare function undoReceiptPath(home: string, runId: string, pairKey: string): string;
+export declare function readUndoReceipt(io: EvolutionIoLike, home: string, runId: string, pairKey: string): Promise<UndoReceipt | null>;
+export declare function writeUndoReceipt(io: EvolutionIoLike, home: string, receipt: UndoReceipt): Promise<void>;
+//# sourceMappingURL=undo-receipt.d.ts.map

package/lib/types/domain/undo-receipt.js

@@ -0,0 +1,22 @@
+import { readTextOrNull } from "./read-probe.js";
+/** Undo receipt: immutable per-pair settlement, separate from the commit receipt. */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+export function undoReceiptPath(home, runId, pairKey) {
+    return join(home, 'merge', 'undo-receipts', encodeURIComponent(runId), createHash('sha256').update(pairKey).digest('hex') + '.json');
+}
+export async function readUndoReceipt(io, home, runId, pairKey) {
+    const raw = await readTextOrNull(io, undoReceiptPath(home, runId, pairKey));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeUndoReceipt(io, home, receipt) {
+    await io.writeText(undoReceiptPath(home, receipt.runId, receipt.pairKey), JSON.stringify(receipt, null, 2) + '\n');
+}
+//# sourceMappingURL=undo-receipt.js.map

package/lib/types/domain/validation-plan.d.ts

@@ -0,0 +1,65 @@
+import type { SkillCard } from '../skill-card.ts';
+import type { MergeLimitsSnapshot } from './merge-limits.ts';
+import type { StagedTree, RuleFinding } from '../rules.ts';
+export interface StagedFile {
+    readonly path: string;
+    readonly content: string;
+    readonly digest: string;
+    readonly bytes: number;
+}
+export interface ValidationPlan {
+    readonly planVersion: 1;
+    readonly stageDigest: string;
+    readonly target: string;
+    readonly body: string;
+    readonly files: readonly StagedFile[];
+    readonly supportFiles: readonly {
+        readonly path: string;
+        readonly digest: string;
+        readonly source: string;
+    }[];
+    readonly manifestFiles: readonly string[];
+    readonly q09: {
+        readonly forwardRefs: readonly string[];
+        readonly reverseRefs: readonly string[];
+        readonly orphanFiles: readonly string[];
+    };
+    readonly supportConflicts: readonly {
+        readonly path: string;
+        readonly sources: readonly string[];
+    }[];
+    readonly threat: {
+        readonly body: boolean;
+        readonly files: readonly string[];
+    };
+    readonly sourceRevisions: Readonly<Record<string, string>>;
+    readonly targetRevision: string | null;
+    readonly limitsDigest: string;
+    readonly promptVersion?: string;
+    readonly promptHash?: string;
+    readonly revision: string;
+    readonly findings: readonly RuleFinding[];
+}
+export declare function buildValidationPlan(input: {
+    readonly tree: StagedTree;
+    readonly target: string;
+    readonly limits: MergeLimitsSnapshot;
+    readonly cards?: readonly SkillCard[];
+    readonly sourceRevisions?: Readonly<Record<string, string>>;
+    readonly targetRevision?: string | null;
+    readonly manifestFiles?: readonly string[];
+    readonly existingSupport?: readonly string[];
+    readonly supportFiles?: readonly {
+        readonly path: string;
+        readonly content: string;
+        readonly source: string;
+    }[];
+    readonly supportSources?: readonly {
+        readonly path: string;
+        readonly content: string;
+        readonly source: string;
+    }[];
+    readonly promptVersion?: string;
+    readonly promptHash?: string;
+}): ValidationPlan;
+//# sourceMappingURL=validation-plan.d.ts.map

package/lib/types/domain/validation-plan.js

@@ -0,0 +1,49 @@
+/** Immutable post-stage validation plan: Q09/support/threat/revision facts. */
+import { createHash } from 'node:crypto';
+import { scanContentThreats, supportRefs } from '@lmzhen/dsh-evolution-core';
+function digest(value) { return createHash('sha256').update(value).digest('hex'); }
+export function buildValidationPlan(input) {
+    const files = input.tree.files.map(file => ({ path: file.path, content: file.content, digest: digest(file.content), bytes: Buffer.byteLength(file.content, 'utf8') }));
+    const manifestFiles = [...new Set(input.manifestFiles ?? files.map(file => file.path))].sort();
+    const supportFiles = (input.supportFiles ?? files.map(file => ({ path: file.path, content: file.content, source: 'staged' }))).map(file => ({ path: file.path, digest: digest(file.content), source: file.source })).sort((a, b) => a.path.localeCompare(b.path));
+    const refs = new Set(supportRefs(input.tree.body));
+    const staged = new Set(files.map(file => file.path));
+    const manifest = new Set(manifestFiles);
+    const forwardRefs = [...refs].filter(ref => !staged.has(ref)).sort();
+    const reverseRefs = files.map(file => file.path).filter(path => !refs.has(path) && manifest.has(path)).sort();
+    const existing = new Set(input.existingSupport ?? []);
+    const orphanFiles = [...existing].filter(path => !staged.has(path)).sort();
+    const byPath = new Map();
+    for (const file of input.supportSources ?? []) {
+        const entry = byPath.get(file.path) ?? { contents: new Set(), sources: [] };
+        entry.contents.add(file.content);
+        entry.sources.push(file.source);
+        byPath.set(file.path, entry);
+    }
+    const supportConflicts = [...byPath.entries()].filter(([, value]) => value.contents.size > 1).map(([path, value]) => ({ path, sources: value.sources }));
+    const sourceThreatFiles = (input.cards ?? []).flatMap(card => (card.files ?? []).filter(file => scanContentThreats(file.content) !== null).map(file => card.name + '/' + file.path));
+    const threat = { body: scanContentThreats(input.tree.body) !== null || (input.cards ?? []).some(card => scanContentThreats(card.body) !== null), files: [...files.filter(file => scanContentThreats(file.content) !== null).map(file => file.path), ...sourceThreatFiles] };
+    const sourceRevisions = input.sourceRevisions ?? Object.fromEntries((input.cards ?? []).map(card => [card.name, digest(card.body)]));
+    const revision = digest(JSON.stringify({ target: input.target, body: digest(input.tree.body), files: files.map(file => [file.path, file.digest]), q09: { forwardRefs, reverseRefs, orphanFiles }, supportConflicts, threat, sourceRevisions, targetRevision: input.targetRevision ?? null }));
+    const findings = [];
+    const stageDigest = digest(JSON.stringify(files.map(file => [file.path, file.digest])));
+    if (forwardRefs.length > 0)
+        findings.push({ rule: 'q09-forward', path: forwardRefs.join(','), severity: 'block', message: 'body references unstaged support' });
+    if (reverseRefs.length > 0)
+        findings.push({ rule: 'q09-reverse', path: reverseRefs.join(','), severity: 'block', message: 'staged manifest file is not referenced by body' });
+    if (orphanFiles.length > 0)
+        findings.push({ rule: 'q09-orphan', path: orphanFiles.join(','), severity: 'block', message: 'target tree support is not declared by plan' });
+    if (supportConflicts.length > 0)
+        findings.push({ rule: 'support-conflict', path: supportConflicts.map(item => item.path).join(','), severity: 'block', message: 'same support path has different contents' });
+    if (threat.body)
+        findings.push({ rule: 'threat', path: 'SKILL.md', severity: 'block', message: 'body tripped content threat scanner' });
+    for (const path of threat.files)
+        findings.push({ rule: 'threat', path, severity: 'block', message: 'support file tripped content threat scanner' });
+    if (Buffer.byteLength(input.tree.body, 'utf8') > input.limits.skillLimits.maxSkillFileBytes)
+        findings.push({ rule: 'limit', path: 'SKILL.md', severity: 'block', message: 'body exceeds maxSkillFileBytes' });
+    for (const file of files)
+        if (file.bytes > input.limits.skillLimits.maxSkillFileBytes)
+            findings.push({ rule: 'limit', path: file.path, severity: 'block', message: 'file exceeds maxSkillFileBytes' });
+    return { planVersion: 1, stageDigest, target: input.target, body: input.tree.body, files, supportFiles, manifestFiles, q09: { forwardRefs, reverseRefs, orphanFiles }, supportConflicts, threat, sourceRevisions, targetRevision: input.targetRevision ?? null, limitsDigest: input.limits.limitsDigest, ...(input.promptVersion === undefined ? {} : { promptVersion: input.promptVersion }), ...(input.promptHash === undefined ? {} : { promptHash: input.promptHash }), revision, findings };
+}
+//# sourceMappingURL=validation-plan.js.map

package/lib/types/facts.d.ts

@@ -2,11 +2,13 @@
 import type { EvolutionIoLike, RunRecord } from '@lmzhen/dsh-evolution-core';
 import type { MergeRow } from './contracts.ts';
 import type { Facts, MergeCounts, RunView } from './wire.ts';
+import type { MergeRunMeta } from './domain/run-coordinator.ts';
 export declare function countsOf(rows: readonly MergeRow[]): MergeCounts;
-export declare function toRunView(record: RunRecord, readAt: number): RunView;
+export declare function toRunView(record: RunRecord, readAt: number, meta?: MergeRunMeta | null): RunView;
 export interface FactsInput {
     readonly rows: readonly MergeRow[];
     readonly runs: readonly RunRecord[];
+    readonly runMeta?: ReadonlyMap<string, MergeRunMeta>;
     readonly approval: boolean;
     readonly readAt: number;
     readonly notes?: readonly string[];