@lmzhen/dsh-evolution-merge 0.30.18 → 0.30.19

package/lib/types/doctor.js

@@ -1,31 +1,67 @@
+import { readTextOrNull } from "./domain/read-probe.js";
 /**
  * Merge doctor rows: state, pending, gate cache and staging are each probed read-only.
  * A missing file is an empty feature, not a failure; an unreadable file is a warning the
  * operator can act on. This module never repairs or writes.
  */
+import { createHash } from 'node:crypto';
+import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { probeList, readTreeLock, runsFile } from '@lmzhen/dsh-evolution-core';
-import { v2BackupPath } from "./domain/state-v3.js";
-import { loadMergeState } from "./state.js";
-import { countRows } from "./status.js";
-import { stagingRoot } from "./staging.js";
+import { migrationJournalPath, migrationReportPath, v2BackupPath } from "./domain/state-bootstrap.js";
+import { readMergeSnapshot } from "./domain/merge-snapshot.js";
 import { validateArtifacts } from "./domain/consistency.js";
 import { readJournal } from "./domain/commit-journal-store.js";
-import { loadStateSchema } from "./state.js";
+import { stagingRoot } from "./staging.js";
+import { readReconcileReport } from "./domain/reconcile.js";
 export const MERGE_DOCTOR_SCHEMA_VERSION = 3;
+/** Compose the one-line global-doctor fact from buildDoctorView + the last reconcile report. */
+export function mergeDoctorFact(view, report) {
+    const counts = view.counts;
+    const reconcileText = report === null
+        ? 'reconcile 尚未运行'
+        : report.state === 'blocked'
+            ? 'reconcile blocked ' + (report.code ?? 'merge-state-blocked')
+            : 'reconcile ' + String(report.actions.length) + ' 项动作';
+    const problems = [];
+    if (view.blocked !== undefined)
+        problems.push('state blocked ' + view.blocked.code);
+    if (view.hostOnly !== undefined)
+        problems.push('宿主数据面不可用 ' + view.hostOnly.code);
+    if (view.staging.state === 'unreadable')
+        problems.push('staging 索引不可读' + (view.staging.detail === undefined ? '' : '：' + view.staging.detail));
+    if (counts.expired > 0)
+        problems.push('expired ' + String(counts.expired));
+    const unstable = view.rows.filter(row => row.status === 'warn' || row.status === 'fail');
+    if (unstable.length > 0)
+        problems.push(unstable.map(row => row.key + '=' + row.status).join(','));
+    if (report?.state === 'blocked')
+        problems.push('reconcile blocked');
+    const latest = view.latestRun;
+    const latestText = latest === undefined ? '' : '；最近 run ' + latest.id + ' [' + latest.state + ']';
+    const detail = 'verify ' + String(counts.active.verify) + ' / pending ' + String(counts.active.pending) + ' / fuse ' + String(counts.active.fuse) + ' / skipped ' + String(counts.active.skipped) + ' / expired ' + String(counts.expired)
+        + '；staging ' + view.staging.state + ' dirs=' + String(view.staging.dirs)
+        + '；审批 ' + (view.approval.mergeApproval ? '开' : '关') + '；' + reconcileText + latestText
+        + (problems.length === 0 ? '' : '；问题：' + problems.join('；'));
+    const status = problems.length === 0
+        ? 'ok'
+        : view.blocked !== undefined || view.hostOnly !== undefined || report?.state === 'blocked' ? 'fail' : 'warn';
+    return problems.length === 0 ? { status, detail } : { status, detail, remedy: '运行 /evolution merge doctor 查看逐项；必要时 /evolution merge reconcile 收敛' };
+}
 /** Global doctor host section: a missing merge mount must fail with E-325, not render empty. */
 export function mergeDoctorAvailability(mounted) {
     return mounted ? { ok: true } : { ok: false, code: 'E-325' };
 }
 export async function mergeDoctor(io, home, configuredRoot) {
     const rows = [];
-    const loaded = await loadMergeState(io, home);
-    const counts = countRows(loaded.state.rows);
+    const snapshot = await readMergeSnapshot({ io, home, runs: [], approval: false });
+    const hasState = await io.exists(join(home, 'merge', 'merge-state.json'));
+    const counts = snapshot.doctor.counts.active;
     rows.push({
         key: 'state',
         label: '合并状态',
-        status: loaded.note === undefined ? 'ok' : 'warn',
-        detail: loaded.note ?? 'pairs ' + String(loaded.state.rows.length) + '；verify ' + String(counts.verify) + ' / pending ' + String(counts.pending) + ' / fuse ' + String(counts.fuse) + ' / skipped ' + String(counts.skipped),
+        status: snapshot.blocked === undefined || !hasState ? 'ok' : 'warn',
+        detail: snapshot.blocked === undefined ? 'pairs ' + String(snapshot.rows.length) + '；verify ' + String(counts.verify) + ' / pending ' + String(counts.pending) + ' / fuse ' + String(counts.fuse) + ' / skipped ' + String(counts.skipped) : snapshot.blocked.code + ': ' + snapshot.blocked.message,
     });
     const recoveryRuns = new Set();
     try {
@@ -42,23 +78,22 @@ export async function mergeDoctor(io, home, configuredRoot) {
         for (const name of receiptDir.value)
             receiptRuns.add(name);
     const invalid = [];
-    for (const row of loaded.state.rows) {
-        const run = row.state === 'pending' && row.runId !== undefined ? 'awaiting-approval' : row.runId === undefined ? 'none' : 'running';
-        const staging = row.stagingRef !== undefined ? 'kept' : row.state === 'fuse' ? 'missing' : 'none';
-        const phase = row.runId === undefined ? undefined : (await readJournal(io, home, row.runId))?.phase;
-        const journal = phase === undefined || phase === null ? 'none'
-            : phase === 'committed' ? 'committed'
-                : phase === 'prepared' ? 'prepared'
-                    : phase === 'rolled-back' ? 'rolled-back'
-                        : phase === 'failed' ? 'failed'
-                            : 'committing';
-        const evidence = row.runId !== undefined && receiptRuns.has(row.runId) ? 'receipt' : 'none';
-        const recovery = row.runId !== undefined && recoveryRuns.has(row.runId);
-        if (!validateArtifacts({ row: row.state, run, staging, journal, evidence, activeRuns: run === 'running' || run === 'awaiting-approval' ? 1 : 0, recovery }).ok)
-            invalid.push(row);
+    if (snapshot.blocked !== undefined)
+        invalid.push({ id: 'state', reason: snapshot.blocked.code });
+    for (const item of snapshot.rows) {
+        const row = item.row;
+        const runId = row.runId ?? (item.stage?.ref.split('/')[0]);
+        const artifactRow = row.state === 'approved' ? 'approved' : row.state === 'fuse' ? 'fuse' : row.state;
+        const run = runId === undefined ? 'none' : row.state === 'pending' ? 'awaiting-approval' : 'running';
+        const staging = item.stage === null ? (row.state === 'fuse' ? 'missing' : 'none') : item.stage.state === 'present' || item.stage.state === 'reserved' ? 'kept' : row.state === 'fuse' ? 'missing' : 'none';
+        const phase = runId === undefined ? null : await readJournal(io, home, runId);
+        const journal = phase === null ? 'none' : phase.phase === 'prepared' ? 'prepared' : phase.phase === 'target-written' || phase.phase === 'sources-archived' ? 'committing' : phase.phase === 'committed' ? 'committed' : phase.phase === 'rolled-back' ? 'rolled-back' : 'failed';
+        const evidence = runId !== undefined && await readTextOrNull(io, join(home, 'merge', 'receipts', runId + '.json')) !== null ? 'receipt' : 'none';
+        const result = validateArtifacts({ row: artifactRow, run, staging, journal, evidence, activeRuns: run === 'running' || run === 'awaiting-approval' ? 1 : 0, ...(runId !== undefined && recoveryRuns.has(runId) ? { recovery: true } : {}) });
+        if (!result.ok)
+            invalid.push({ id: row.id, reason: result.reason ?? 'not-allowed' });
     }
-    const schema = await loadStateSchema(io, home);
-    rows.push({ key: 'merge-state-v3', label: 'state schema', status: schema === 3 ? 'ok' : schema === 2 ? 'warn' : 'unknown', detail: schema === 3 ? 'schemaVersion 3' : schema === 2 ? 'schemaVersion 2；等待 v3 迁移' : 'schemaVersion 未知/不可读' });
+    rows.push({ key: 'merge-state-v3', label: 'state schema', status: snapshot.blocked === undefined ? 'ok' : 'warn', detail: snapshot.blocked === undefined ? 'schemaVersion 4' : snapshot.blocked.code });
     let quarantineCount = 0;
     try {
         const qraw = await io.readText(join(home, 'merge', 'merge-state.quarantine.json'));
@@ -73,7 +108,15 @@ export async function mergeDoctor(io, home, configuredRoot) {
     rows.push({ key: 'quarantine', label: 'quarantine', status: quarantineCount < 0 ? 'unknown' : quarantineCount === 0 ? 'ok' : 'warn', detail: quarantineCount < 0 ? 'quarantine 不可读' : quarantineCount + ' 行待人工检查' });
     const holder = await readTreeLock(io, home).catch(() => null);
     rows.push({ key: 'tree-lock', label: 'tree lock', status: holder == null ? 'ok' : 'warn', detail: holder == null ? 'free' : 'holder pid=' + String(holder.pid) + ' epoch=' + String(holder.epoch) + ' token=' + holder.token.slice(0, 8) });
-    rows.push({ key: 'backup', label: 'v2 backup', status: await io.exists(v2BackupPath(home)) ? 'ok' : 'unknown', detail: await io.exists(v2BackupPath(home)) ? 'merge-state.v2.bak.json' : 'no v2 backup (not migrated or already cleaned)' });
+    const backupPath = v2BackupPath(home);
+    const backupRaw = await readTextOrNull(io, backupPath);
+    const backupMode = await stat(backupPath).then(value => value.mode).catch(() => null);
+    const backupReadOnly = backupMode === null ? null : (backupMode & 0o200) === 0;
+    rows.push({ key: 'backup', label: 'v2 backup', status: backupRaw === null ? 'unknown' : backupReadOnly === false ? 'warn' : 'ok', detail: backupRaw === null ? 'no v2 backup (not migrated or already cleaned)' : 'merge-state.v2.bak.json sha256=' + createHash('sha256').update(backupRaw).digest('hex').slice(0, 16) + ' readonly=' + String(backupReadOnly) });
+    const journal = await readTextOrNull(io, migrationJournalPath(home));
+    const report = await readTextOrNull(io, migrationReportPath(home));
+    rows.push({ key: 'migration', label: 'state migration', status: snapshot.blocked === undefined ? (journal === null ? 'ok' : 'warn') : 'warn', detail: snapshot.blocked === undefined ? (journal === null ? (report === null ? 'ready (no migration report)' : 'ready; report present') : 'ready; migration journal pending') : snapshot.blocked.code + ': ' + snapshot.blocked.message });
+    rows.push({ key: 'staging-index', label: 'staging index', status: 'ok', detail: String(snapshot.stages.length) + ' index entries' });
     const claims = await probeList(io, join(home, 'merge', 'claims'));
     rows.push({ key: 'target-claim', label: 'target claim', status: claims.kind === 'unknown' ? 'unknown' : 'ok', detail: claims.kind === 'unknown' ? 'claims unreadable' : claims.kind === 'absent' ? 'no claims' : String(claims.value.length) + ' claim files' });
     let orphanRuns = 0;
@@ -100,7 +143,18 @@ export async function mergeDoctor(io, home, configuredRoot) {
     }
     rows.push({ key: 'runs', label: 'run owner', status: orphanRuns < 0 ? 'unknown' : orphanRuns === 0 ? 'ok' : 'warn', detail: orphanRuns < 0 ? 'runs.json unreadable' : String(runCount) + ' runs; ' + String(orphanRuns) + ' dead-owner running' });
     rows.push({ key: 'install', label: 'install form', status: io.exists === undefined ? 'unknown' : 'ok', detail: 'merge plugin loaded' });
-    rows.push({ key: 'consistency', label: '一致性', status: invalid.length === 0 ? 'ok' : 'warn', detail: invalid.length === 0 ? '无非法组合' : String(invalid.length) + ' 行需人工检查: ' + invalid.map(row => row.id).join(', ') });
+    const reconcile = await readReconcileReport(io, home);
+    rows.push({
+        key: 'reconcile',
+        label: '状态收敛',
+        status: reconcile === null ? 'unknown' : reconcile.state === 'blocked' ? 'warn' : reconcile.actions.length > 0 ? 'warn' : 'ok',
+        detail: reconcile === null
+            ? '尚无 reconcile 报告（启动或 /evolution merge reconcile 会生成）'
+            : reconcile.state === 'blocked'
+                ? 'blocked：' + (reconcile.code ?? 'merge-state-blocked') + (reconcile.message === undefined ? '' : ' — ' + reconcile.message)
+                : String(reconcile.actions.length) + ' 项动作（' + new Date(reconcile.at).toISOString() + '）' + (reconcile.actions.length === 0 ? '' : '：' + reconcile.actions.map(action => action.rowId + '=' + action.code).join(', ')),
+    });
+    rows.push({ key: 'consistency', label: '一致性', status: snapshot.blocked !== undefined ? 'blocked' : invalid.length === 0 ? 'ok' : 'warn', detail: snapshot.blocked !== undefined ? 'blocked: ' + snapshot.blocked.code : invalid.length === 0 ? '无非法组合' : String(invalid.length) + ' 行需人工检查: ' + invalid.map(row => row.id + '=' + row.reason).join(', ') });
     const modelRoot = configuredRoot?.trim() ?? '';
     if (modelRoot === '') {
         rows.push({ key: 'models', label: '合并模型', status: 'warn', detail: '未配置 mergeModelsRoot；合并扫描会 fail loud' });

package/lib/types/domain/authoring-manifest.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The round-2 JSON envelope a child writes after authoring: which files the merge left
+ * behind. Both authoring paths (same-child scan round2 and the new-child approve/resume
+ * path) parse it identically, so a declared-but-missing file fails the same way on both.
+ */
+export interface AuthoringManifest {
+    readonly target?: string;
+    readonly files: readonly string[];
+}
+/**
+ * Parse `{"target":..., "files":[...]}` from a child's final turn text.
+ * @param text - the child's answer (JSON is expected; prose is tolerated).
+ * @returns the manifest, or null when the turn carried no well-formed envelope.
+ */
+export declare function parseAuthoringManifest(text: string): AuthoringManifest | null;
+/** Files a manifest promises for a staged tree (declared list, or the tree when undeclared). */
+export declare function manifestFilesOf(manifest: AuthoringManifest | null, stagedPaths: readonly string[]): readonly string[];
+/**
+ * The first file the manifest promises but the staged tree does not contain.
+ * SKILL.md itself is always required, whether or not the manifest lists it.
+ * @param files - manifest files (see {@link manifestFilesOf}).
+ * @param stagedPaths - support-file paths actually present in the staged tree.
+ * @returns the missing path, or null when the declaration is satisfied.
+ */
+export declare function missingManifestFile(files: readonly string[], stagedPaths: readonly string[]): string | null;
+//# sourceMappingURL=authoring-manifest.d.ts.map

package/lib/types/domain/authoring-manifest.js

@@ -0,0 +1,43 @@
+/**
+ * Parse `{"target":..., "files":[...]}` from a child's final turn text.
+ * @param text - the child's answer (JSON is expected; prose is tolerated).
+ * @returns the manifest, or null when the turn carried no well-formed envelope.
+ */
+export function parseAuthoringManifest(text) {
+    try {
+        const value = JSON.parse(text);
+        if (!Array.isArray(value.files) || value.files.some(file => typeof file !== 'string'))
+            return null;
+        if (value.target !== undefined && typeof value.target !== 'string')
+            return null;
+        return { ...(typeof value.target === 'string' ? { target: value.target } : {}), files: value.files };
+    }
+    catch {
+        return null;
+    }
+}
+/** Files a manifest promises for a staged tree (declared list, or the tree when undeclared). */
+export function manifestFilesOf(manifest, stagedPaths) {
+    if (manifest !== null)
+        return manifest.files;
+    return ['SKILL.md', ...stagedPaths];
+}
+/**
+ * The first file the manifest promises but the staged tree does not contain.
+ * SKILL.md itself is always required, whether or not the manifest lists it.
+ * @param files - manifest files (see {@link manifestFilesOf}).
+ * @param stagedPaths - support-file paths actually present in the staged tree.
+ * @returns the missing path, or null when the declaration is satisfied.
+ */
+export function missingManifestFile(files, stagedPaths) {
+    if (!files.includes('SKILL.md'))
+        return 'SKILL.md';
+    for (const path of files) {
+        if (path === 'SKILL.md')
+            continue;
+        if (!stagedPaths.includes(path))
+            return path;
+    }
+    return null;
+}
+//# sourceMappingURL=authoring-manifest.js.map

package/lib/types/domain/engine-criteria.d.ts

@@ -0,0 +1,10 @@
+/** Batch 3 engine criteria projection: merge maps level/verdict/action, engine does not. */
+export interface EngineCriteria {
+    readonly decision: 'keep' | 'merge' | 'candidate';
+    readonly validation: 'not-run' | 'report-only' | 'required';
+    readonly commit: 'never' | 'if-approved' | 'required';
+    readonly archive: 'none' | 'sources';
+    readonly evidence: 'none' | 'receipt';
+}
+export declare function criteriaFrom(level: 'L0' | 'L1' | 'L2', verdict: 1 | 0 | -1, action: 'keep' | 'merge'): EngineCriteria;
+//# sourceMappingURL=engine-criteria.d.ts.map

package/lib/types/domain/engine-criteria.js

@@ -0,0 +1,11 @@
+export function criteriaFrom(level, verdict, action) {
+    const candidate = level === 'L2' && verdict !== -1;
+    return {
+        decision: action === 'keep' ? 'keep' : candidate ? 'merge' : 'candidate',
+        validation: level === 'L2' ? 'required' : 'report-only',
+        commit: candidate && action === 'merge' ? 'required' : 'never',
+        archive: candidate && action === 'merge' ? 'sources' : 'none',
+        evidence: candidate && action === 'merge' ? 'receipt' : 'none',
+    };
+}
+//# sourceMappingURL=engine-criteria.js.map

package/lib/types/domain/engine-input.d.ts

@@ -0,0 +1,10 @@
+/** OI-11 engine input allowlist: exactly modelsRoot/reportOnly/maxTokens/timeoutMs. */
+export interface EngineInput {
+    readonly modelsRoot: string;
+    readonly reportOnly: boolean;
+    readonly maxTokens: number;
+    readonly timeoutMs: number;
+}
+export declare const ENGINE_FORBIDDEN_KEYS: readonly ["offline", "auto_provision", "embed_backend", "rank_mode", "models_dir", "embedder_model", "embedder_model_last", "judge"];
+export declare function resolveEngineInput(input?: unknown): EngineInput;
+//# sourceMappingURL=engine-input.d.ts.map

package/lib/types/domain/engine-input.js

@@ -0,0 +1,26 @@
+const ALLOWED = new Set(['modelsRoot', 'reportOnly', 'maxTokens', 'timeoutMs']);
+export const ENGINE_FORBIDDEN_KEYS = ['offline', 'auto_provision', 'embed_backend', 'rank_mode', 'models_dir', 'embedder_model', 'embedder_model_last', 'judge'];
+function integer(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0)
+        throw new Error(name + ' must be a non-negative integer');
+    return value;
+}
+export function resolveEngineInput(input = {}) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input))
+        throw new Error('engine input must be an object');
+    for (const key of Object.keys(input)) {
+        if (ENGINE_FORBIDDEN_KEYS.includes(key))
+            throw new Error('engine input key is forbidden: ' + key);
+        if (!ALLOWED.has(key))
+            throw new Error('unknown engine input: ' + key);
+    }
+    const record = input;
+    if (record.modelsRoot !== undefined && typeof record.modelsRoot !== 'string')
+        throw new Error('modelsRoot must be a string');
+    if (record.reportOnly !== undefined && typeof record.reportOnly !== 'boolean')
+        throw new Error('reportOnly must be a boolean');
+    return { modelsRoot: typeof record.modelsRoot === 'string' ? record.modelsRoot : '', reportOnly: record.reportOnly === true, maxTokens: integer('maxTokens', record.maxTokens, 0), timeoutMs: integer('timeoutMs', record.timeoutMs, 0) };
+}
+//# sourceMappingURL=engine-input.js.map

package/lib/types/domain/errors.d.ts

@@ -1,12 +1,26 @@
-/** Pure merge error rendering: parameter errors are two lines, runtime/target failures three. */
+/** Pure merge error rendering: parameter errors stay one line; command failures are code/hint/next. */
 export type MergeErrorKind = 'parameter' | 'runtime' | 'target' | 'approval';
 export interface MergeError {
     readonly kind: MergeErrorKind;
     readonly code: string;
     readonly message: string;
+    /** Reader-facing explanation; defaults to the message (plus detail). */
+    readonly hint?: string;
+    /** The one next step; every runtime failure names one. */
+    readonly next?: string;
     readonly detail?: string;
     readonly stage?: string;
     readonly runId?: string;
 }
+/** Build the typed failure every command/CLI/runtime branch returns. */
+export declare function commandError(stage: string, code: string, hint: string, next: string, runId?: string): MergeError;
+/** Render a merge command failure: one line for syntax, three lines (code/hint/next) for runtime. */
 export declare function formatMergeError(error: MergeError): string;
+/** A typed failure result: `message` is the rendered three-line text, `error` keeps the fields. */
+export interface FailureResult {
+    readonly ok: false;
+    readonly message: string;
+    readonly error: MergeError;
+}
+export declare function failure(stage: string, code: string, hint: string, next: string, runId?: string): FailureResult;
 //# sourceMappingURL=errors.d.ts.map

package/lib/types/domain/errors.js

@@ -4,12 +4,31 @@ function redact(text) {
         .replace(/Bearer\s+\S+/gi, 'Bearer [redacted]')
         .replace(/(api[_-]?key\s*[:=]\s*)\S+/gi, '$1[redacted]');
 }
+/** Build the typed failure every command/CLI/runtime branch returns. */
+export function commandError(stage, code, hint, next, runId) {
+    return { kind: 'runtime', code, message: hint, hint, next, stage, ...(runId === undefined ? {} : { runId }) };
+}
+function oneLine(value) {
+    return value.replace(/\r?\n+/g, ' ').trim();
+}
+function render(error) {
+    const where = [
+        error.stage === undefined ? undefined : 'stage=' + error.stage,
+        error.runId === undefined ? undefined : 'run=' + error.runId,
+    ].filter((value) => value !== undefined).join(', ');
+    const heading = 'code: ' + error.code + (where === '' ? '' : ' (' + where + ')');
+    const hint = 'hint: ' + oneLine(error.hint ?? [error.message, error.detail].filter((value) => value !== undefined && value !== '').join(' — '));
+    const next = 'next: ' + oneLine(error.next ?? error.detail ?? 'fix the target or rerun after the cause is gone');
+    return redact([heading, hint, next].join('\n'));
+}
+/** Render a merge command failure: one line for syntax, three lines (code/hint/next) for runtime. */
 export function formatMergeError(error) {
     if (error.kind === 'parameter')
         return 'merge: ' + error.message + ' (' + error.code + ')';
-    const where = error.stage === undefined && error.runId === undefined
-        ? (error.detail ?? 'no additional detail')
-        : [error.stage === undefined ? undefined : 'stage=' + error.stage, error.runId === undefined ? undefined : 'run=' + error.runId].filter(Boolean).join(' ');
-    return redact('merge failed: ' + error.message + ' (' + error.code + ')\n' + where + '\nnext: fix the target or rerun after the cause is gone');
+    return render(error);
+}
+export function failure(stage, code, hint, next, runId) {
+    const error = commandError(stage, code, hint, next, runId);
+    return { ok: false, message: formatMergeError(error), error };
 }
 //# sourceMappingURL=errors.js.map

package/lib/types/domain/evidence-hash.d.ts

@@ -0,0 +1,3 @@
+import type { UnitEvidenceRecord } from '@lmzhen/dsh-evolution-core';
+export declare function evidenceSha256(evidence: UnitEvidenceRecord): string;
+//# sourceMappingURL=evidence-hash.d.ts.map

package/lib/types/domain/evidence-hash.js

@@ -0,0 +1,14 @@
+/** Canonical evidence JSON hash shared with core unit receipts. */
+import { createHash } from 'node:crypto';
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    const object = value;
+    return '{' + Object.keys(object).sort().map(key => JSON.stringify(key) + ':' + canonical(object[key])).join(',') + '}';
+}
+export function evidenceSha256(evidence) {
+    return createHash('sha256').update(canonical({ ...evidence, at: 0, mutations: 0 })).digest('hex');
+}
+//# sourceMappingURL=evidence-hash.js.map

package/lib/types/domain/failure-route.d.ts

@@ -20,6 +20,20 @@ export type MergeFailureRoute = {
 } | {
     readonly kind: 'runtime';
     readonly reportOnly: true;
+} | {
+    readonly kind: 'over-limit';
+    readonly reportOnly: true;
+    readonly reason: 'merge-over-limit';
+    readonly lengths: Readonly<Record<string, number>>;
 };
+export declare function routeLimitFailure(lengths: Readonly<Record<string, number>>): MergeFailureRoute;
 export declare function routeFailure(code: string): MergeFailureRoute;
+/** Batch 2 typed CAS hook; Batch 3 owns full targetRevision expiry. */
+export type CasFailureCode = 'target-changed' | 'target-taken' | 'source-changed' | 'support-changed';
+export interface CasHookResult {
+    readonly kind: 'expired';
+    readonly reason: Exclude<CasFailureCode, 'target-changed' | 'support-changed'>;
+    readonly write: false;
+}
+export declare function casExpiredHook(code: string): CasHookResult | null;
 //# sourceMappingURL=failure-route.d.ts.map

package/lib/types/domain/failure-route.js

@@ -4,7 +4,12 @@ const TARGET_TAKEN = new Set(['target-taken', 'target-exists']);
 const VALIDATION = new Set(['validation-failed', 'invalid-decision']);
 const COMMIT = new Set(['commit-failed', 'commit-refused']);
 const SCHEMA = new Set(['schema-invalid', 'schema-version']);
+export function routeLimitFailure(lengths) {
+    return { kind: 'over-limit', reportOnly: true, reason: 'merge-over-limit', lengths };
+}
 export function routeFailure(code) {
+    if (code === 'merge-over-limit')
+        return routeLimitFailure({});
     if (PARAMETER.has(code))
         return { kind: 'parameter', reportOnly: false };
     if (SOURCE_GONE.has(code))
@@ -19,4 +24,11 @@ export function routeFailure(code) {
         return { kind: 'schema', reportOnly: true };
     return { kind: 'runtime', reportOnly: true };
 }
+export function casExpiredHook(code) {
+    if (code === 'target-changed' || code === 'target-taken')
+        return { kind: 'expired', reason: 'target-taken', write: false };
+    if (code === 'source-changed' || code === 'support-changed')
+        return { kind: 'expired', reason: 'source-changed', write: false };
+    return null;
+}
 //# sourceMappingURL=failure-route.js.map

package/lib/types/domain/live-facts.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Read-time convergence facts for pending rows (FR-LIFE-14).
+ *
+ * Snapshot and reconcile must agree on WHY a pending row is no longer actionable, but no
+ * reader may write. This module is the single derivation both sides call: given the live
+ * library view it answers absent/source-gone/target-taken/source-changed, and the
+ * persisted row state is only consulted for an already-recorded expiry.
+ */
+import type { RevisionRef } from '../contracts.ts';
+import type { SkillCard } from '../skill-card.ts';
+import type { V4Row } from './row-v4.ts';
+/** Why a pending row reads as expired. `source-gone` rows are removed by reconcile. */
+export type PendingExpiryKind = 'target-taken' | 'source-changed' | 'source-gone';
+/** The live library facts the derivation needs; no io, no writes. */
+export interface LiveRowFacts {
+    readonly managed: (name: string) => boolean;
+    readonly targetRevisionRef: (name: string) => RevisionRef;
+    readonly sourceRevisionRef: (a: string, b: string) => RevisionRef;
+    readonly supportDigest: (names: readonly string[]) => string;
+}
+export declare function liveRowFactsOf(cards: readonly SkillCard[]): LiveRowFacts;
+/**
+ * The read-only expiry verdict for one row.
+ * @param row - the persisted row (only pending rows converge here).
+ * @param live - current library facts; absent means "cannot derive".
+ * @returns the expiry kind, or null when the row is still actionable.
+ */
+export declare function pendingExpiry(row: V4Row, live: LiveRowFacts | undefined): PendingExpiryKind | null;
+/** The persisted expiry kind, when the row already carries one. */
+export declare function persistedExpiry(row: V4Row): PendingExpiryKind | null;
+//# sourceMappingURL=live-facts.d.ts.map

package/lib/types/domain/live-facts.js

@@ -0,0 +1,54 @@
+import { revisionMismatch, sourceRevisionRefOf, supportDigestOf, targetRevisionRefOf } from "../revision.js";
+export function liveRowFactsOf(cards) {
+    const byName = new Map(cards.map(card => [card.name, card]));
+    return {
+        managed: name => byName.get(name)?.managed === true,
+        targetRevisionRef: name => targetRevisionRefOf(cards, name),
+        sourceRevisionRef: (a, b) => sourceRevisionRefOf(cards, a, b),
+        supportDigest: names => supportDigestOf(cards, names),
+    };
+}
+/**
+ * The read-only expiry verdict for one row.
+ * @param row - the persisted row (only pending rows converge here).
+ * @param live - current library facts; absent means "cannot derive".
+ * @returns the expiry kind, or null when the row is still actionable.
+ */
+export function pendingExpiry(row, live) {
+    if (live === undefined)
+        return null;
+    if (row.state === 'verify') {
+        return !live.managed(row.a) || !live.managed(row.b) ? 'source-gone' : null;
+    }
+    if (row.state !== 'pending' && row.state !== 'fuse' && row.state !== 'approved')
+        return null;
+    if (!live.managed(row.a) || !live.managed(row.b))
+        return 'source-gone';
+    const decision = row.decision;
+    if (row.state !== 'pending') {
+        if (revisionMismatch(decision.sourceRevisionRef, live.sourceRevisionRef(row.a, row.b)) !== null)
+            return 'source-changed';
+        if (decision.supportDigest !== undefined && decision.supportDigest !== live.supportDigest([decision.target, row.a, row.b]))
+            return 'source-changed';
+        return null;
+    }
+    if (decision.mode !== 'create-umbrella') {
+        if (!live.managed(decision.target))
+            return 'target-taken';
+    }
+    // A create-umbrella decision recorded "this name was free"; the name being taken now is
+    // the same conflict the approve precheck reports.
+    if (revisionMismatch(decision.targetRevisionRef, live.targetRevisionRef(decision.target)) !== null)
+        return 'target-taken';
+    const expectedSource = decision.sourceRevisionRef;
+    if (revisionMismatch(expectedSource, live.sourceRevisionRef(row.a, row.b)) !== null)
+        return 'source-changed';
+    if (decision.supportDigest !== undefined && decision.supportDigest !== live.supportDigest([decision.target, row.a, row.b]))
+        return 'source-changed';
+    return null;
+}
+/** The persisted expiry kind, when the row already carries one. */
+export function persistedExpiry(row) {
+    return row.state === 'pending' && row.expired !== undefined ? row.expired : null;
+}
+//# sourceMappingURL=live-facts.js.map

package/lib/types/domain/merge-limits.d.ts

@@ -0,0 +1,18 @@
+import { policyStageLimits, type SkillLimits } from '@lmzhen/dsh-evolution-core';
+export interface MergeLimitsSnapshot {
+    readonly skillLimits: SkillLimits;
+    readonly limitsDigest: string;
+}
+export declare function resolveLimitsSnapshot(policy?: Parameters<typeof policyStageLimits>[0]): MergeLimitsSnapshot;
+export declare function limitsSnapshotOf(skillLimits: SkillLimits): MergeLimitsSnapshot;
+export declare function mergeLimitFinding(path: string, limit: string, observed: number, limitValue: number): {
+    readonly rule: string;
+    readonly path: string;
+    readonly severity: 'block';
+    readonly code: 'limit';
+    readonly limit: string;
+    readonly observed: number;
+    readonly limitValue: number;
+    readonly message: string;
+};
+//# sourceMappingURL=merge-limits.d.ts.map

package/lib/types/domain/merge-limits.js

@@ -0,0 +1,22 @@
+/** One limits snapshot shared by authoring, validation and commit. */
+import { createHash } from 'node:crypto';
+import { DEFAULT_SKILL_LIMITS, policyStageLimits } from '@lmzhen/dsh-evolution-core';
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    const object = value;
+    return '{' + Object.keys(object).sort().map(key => JSON.stringify(key) + ':' + canonical(object[key])).join(',') + '}';
+}
+export function resolveLimitsSnapshot(policy) {
+    const skillLimits = { ...DEFAULT_SKILL_LIMITS, ...policyStageLimits(policy) };
+    return { skillLimits, limitsDigest: createHash('sha256').update(canonical(skillLimits)).digest('hex') };
+}
+export function limitsSnapshotOf(skillLimits) {
+    return { skillLimits, limitsDigest: createHash('sha256').update(canonical(skillLimits)).digest('hex') };
+}
+export function mergeLimitFinding(path, limit, observed, limitValue) {
+    return { rule: 'limit', path, severity: 'block', code: 'limit', limit, observed, limitValue, message: path + ' exceeds ' + limit + ' (' + String(observed) + ' > ' + String(limitValue) + ')' };
+}
+//# sourceMappingURL=merge-limits.js.map

package/lib/types/domain/merge-report.d.ts

@@ -0,0 +1,41 @@
+/** 1b-1 additive report schema; values are filled by later batches. */
+export interface MergeReportLimits {
+    readonly maxSkillFileBytes?: number;
+    readonly maxTokenBytes?: number;
+    readonly pairTimeoutMinutes?: number;
+}
+export interface MergeReportValidation {
+    readonly ok: boolean;
+    readonly errors: readonly string[];
+}
+export interface MergeReport {
+    readonly schemaVersion: 2;
+    readonly reportId: string;
+    readonly runId: string;
+    readonly pairKey: string;
+    readonly target: string;
+    readonly sourceRevisions?: Readonly<Record<string, string>>;
+    readonly targetRevision?: string;
+    readonly validation: MergeReportValidation;
+    readonly limits: MergeReportLimits;
+    readonly q09?: {
+        readonly forwardRefs: readonly string[];
+        readonly reverseRefs: readonly string[];
+        readonly orphanFiles: readonly string[];
+    };
+    readonly threat?: {
+        readonly body: string;
+        readonly source: string;
+    };
+    readonly createdAt: string;
+}
+export interface MergeReportRef {
+    readonly path: string;
+    readonly digest: string;
+    readonly writtenAt: string;
+}
+export interface MergeReportWriter {
+    write(report: MergeReport): Promise<MergeReportRef>;
+    read(runId: string): Promise<MergeReport | null>;
+}
+//# sourceMappingURL=merge-report.d.ts.map

package/lib/types/domain/merge-report.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=merge-report.js.map