@lmzhen/dsh-evolution-merge 0.30.24 → 0.30.27

package/lib/types/host-capabilities.js

@@ -0,0 +1,24 @@
+/**
+ * The host's data-plane capability as ONE value shared by snapshot, doctor, HTTP and run preflight.
+ * The probe is injected so the Cordis wiring stays in index.ts; a rejected probe is the same E-323
+ * answer as an unavailable one, never an unhandled promise.
+ * @module @lmzhen/dsh-evolution-merge
+ */
+/**
+ * Wrap one probe with the shared error normalization.
+ * @param probe - the platform-specific availability check.
+ * @returns the capability value consumed by snapshot and runtime.
+ */
+export function createHostCapabilities(probe) {
+    return {
+        hostOnly: async () => {
+            try {
+                return await probe();
+            }
+            catch (error) {
+                return { code: 'E-323', detail: error instanceof Error ? error.message : String(error) };
+            }
+        },
+    };
+}
+//# sourceMappingURL=host-capabilities.js.map

package/lib/types/index.js

@@ -31,6 +31,7 @@ import { pairKey, rowIdOf } from "./contracts.js";
 import { makeMergeRoutes } from "./merge-routes.js";
 import { createMergeCommand, runMergeCommand } from "./merge-command.js";
 import { createMergeRuntime } from "./runtime.js";
+import { createHostCapabilities } from "./host-capabilities.js";
 import { resolveMergeParams } from "./params.js";
 import { subagentChannelAdapter } from "./adapters/channel.js";
 import { StageToolRegistry } from "./stage-tool-registry.js";
@@ -214,6 +215,8 @@ export function apply(ctx, rawConfig = {}) {
                     const cleanup = await cleanupStage(io, home, Date.now(), new Map(v4.state.rows.map(row => [row.id, { state: row.state }])));
                     if (cleanup.expired.length > 0 || cleanup.removed.length > 0)
                         ctx.logger.info('merge stage cleanup: ' + String(cleanup.expired.length) + ' expired, ' + String(cleanup.removed.length) + ' removed, ' + String(cleanup.orphans.length) + ' orphan(s)');
+                    if (cleanup.failures.length > 0)
+                        ctx.logger.warn('merge stage cleanup failed for ' + String(cleanup.failures.length) + ' path(s): ' + cleanup.failures.map(item => item.path + '=' + item.message).join('; '));
                     // Reconcile is the one row-state convergence writer; startup simply invokes it.
                     // A live library is only supplied when it is non-empty (an empty/unreadable list
                     // must never authorize source-gone removal).
@@ -230,7 +233,12 @@ export function apply(ctx, rawConfig = {}) {
                 }
             })().catch((error) => { ctx.logger.warn('merge recovery failed: ' + (error instanceof Error ? error.message : String(error))); });
         }).catch((error) => { ctx.logger.warn('merge state readiness failed: ' + (error instanceof Error ? error.message : String(error))); });
-        const channel = subagentChannelAdapter(createSubagentChannel(ctx));
+        const platformChannel = createSubagentChannel(ctx);
+        const channel = subagentChannelAdapter(platformChannel);
+        const hostCapabilities = createHostCapabilities(async () => {
+            const state = await platformChannel.prepare({ kind: 'reviewer', allow: ['skill'] });
+            return state.kind === 'unavailable' ? { code: 'E-323', detail: state.reason } : undefined;
+        });
         const stage = new StageToolRegistry();
         const engineInput = resolveEngineInput({ modelsRoot: params.mergeModelsRoot });
         const engineConfig = engineConfigFromRoot(engineInput.modelsRoot);
@@ -273,7 +281,7 @@ export function apply(ctx, rawConfig = {}) {
         });
         source = {
             async snapshot() {
-                return await readMergeSnapshot({ io, home, runs: runs.runs('merge'), approval: params.mergeApproval, platformWrite, live: async () => liveRowFactsOf(await readSkillCards(skills)), history: async () => {
+                return await readMergeSnapshot({ io, home, runs: runs.runs('merge'), approval: params.mergeApproval, platformWrite, hostOnly: hostCapabilities.hostOnly, live: async () => liveRowFactsOf(await readSkillCards(skills)), history: async () => {
                         const items = new Map();
                         const receipts = [...await readCommitReceipts(io, home)].sort((a, b) => a.at - b.at);
                         const generationOf = new Map(receipts.map((receipt, index) => [receipt.runId, index + 1]));
@@ -318,7 +326,9 @@ export function apply(ctx, rawConfig = {}) {
             return;
         const runtime = createMergeRuntime({
             io, home, registry: runs, skills, now: () => Date.now(), params, platformWrite,
+            ...(defaultModel === undefined ? {} : { model: defaultModel.currentSelection().model }),
             channel, parent: undefined, allow: ['merge_stage'], timeoutMinutes: params.mergeRunTimeoutMinutes,
+            hostCapabilities,
             isBlocked: async (name) => {
                 const curator = ctx.get('evolutionCurator');
                 return (await curator?.isBlocked?.(name)) === true;

package/lib/types/kernel/adapter-v4.d.ts

@@ -0,0 +1,12 @@
+import type { V4Row } from '../domain/row-v4.ts';
+import type { PairSnapshot } from './model.ts';
+export interface V4AdapterResult {
+    readonly snapshot: PairSnapshot;
+    readonly warnings: readonly string[];
+}
+export declare function fromV4Row(row: V4Row): V4AdapterResult;
+export declare function fromV4Rows(rows: readonly V4Row[]): {
+    readonly snapshots: readonly PairSnapshot[];
+    readonly warnings: readonly string[];
+};
+//# sourceMappingURL=adapter-v4.d.ts.map

package/lib/types/kernel/adapter-v4.js

@@ -0,0 +1,54 @@
+function decisionOf(row) {
+    return { target: row.target, sources: row.decision.sources, ...(row.decision.rationale === undefined ? {} : { rationale: row.decision.rationale }) };
+}
+function failureOfRow(failure) {
+    const known = new Set(['source-gone', 'source-changed', 'target-taken', 'validation-failed', 'commit-failed', 'schema-invalid', 'timeout', 'capability-missing', 'runtime']);
+    const code = known.has(failure.code) ? failure.code : 'runtime';
+    return { code, stage: failure.stage === 'screening' ? 'screen' : failure.stage === 'decide' ? 'decide' : failure.stage === 'author' ? 'author' : failure.stage === 'validate' ? 'validate' : 'commit', retryable: failure.retryable, reportOnly: true, userMessageKey: 'failure.' + code, detail: failure.message };
+}
+function closedReasonOf(row) {
+    if (row.reason.includes('merge-over-limit') || row.reason.includes('over-limit'))
+        return 'over-limit';
+    return row.origin === 'human' ? 'reject' : 'keep';
+}
+export function fromV4Row(row) {
+    const warnings = [];
+    const base = { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, version: row.version, createdAt: row.createdAt, updatedAt: row.updatedAt, origin: row.origin, attempts: row.attempts, ...(row.runId === undefined ? {} : { runId: row.runId }) };
+    if (row.failure !== undefined) {
+        warnings.push('row carries failure; kernel state=failed (current row state=' + row.state + ')');
+        return { snapshot: { ...base, state: 'failed', failure: failureOfRow(row.failure) }, warnings };
+    }
+    if (row.state === 'verify') {
+        return { snapshot: { ...base, state: row.verifySubState === 'screened' ? 'deciding' : 'candidate' }, warnings };
+    }
+    if (row.state === 'pending') {
+        if (row.expired !== undefined) {
+            warnings.push('pending expired without a timestamp; kernel state=expired');
+            return { snapshot: { ...base, state: 'expired', target: row.target, decision: decisionOf(row), approval: 'on' }, warnings };
+        }
+        return { snapshot: { ...base, state: 'pending', target: row.target, decision: decisionOf(row), approval: 'on' }, warnings };
+    }
+    if (row.state === 'approved')
+        return { snapshot: { ...base, state: 'approved', target: row.target, decision: decisionOf(row), approval: 'off' }, warnings };
+    if (row.state === 'fuse') {
+        warnings.push('current fuse row has no stagingRef; kernel state=authoring');
+        return { snapshot: { ...base, state: 'authoring', target: row.target, decision: decisionOf(row), approval: 'off' }, warnings };
+    }
+    if (row.expiredAt !== undefined) {
+        warnings.push('skipped-expired row maps to closed+expiresAt, not a failure');
+        return { snapshot: { ...base, state: 'closed', closedReason: closedReasonOf(row), expiresAt: row.expiredAt }, warnings };
+    }
+    return { snapshot: { ...base, state: 'closed', closedReason: closedReasonOf(row) }, warnings };
+}
+export function fromV4Rows(rows) {
+    const snapshots = [];
+    const warnings = [];
+    for (const row of rows) {
+        const result = fromV4Row(row);
+        snapshots.push(result.snapshot);
+        for (const warning of result.warnings)
+            warnings.push(row.id + ': ' + warning);
+    }
+    return { snapshots, warnings };
+}
+//# sourceMappingURL=adapter-v4.js.map

package/lib/types/kernel/failure.d.ts

@@ -0,0 +1,8 @@
+/** Pure failure taxonomy: the ONE place a code becomes a route. */
+import type { ClosedReason, Failure, FailureCode } from './model.ts';
+export declare function failureOf(code: FailureCode, detail?: string): Failure;
+/** Only policy closures are closed; failures never map here. */
+export declare function closedReasonFor(code: string): ClosedReason | undefined;
+export declare function isFailureRoute(reportOnly: boolean): boolean;
+export declare const FAILURE_CODES: readonly FailureCode[];
+//# sourceMappingURL=failure.d.ts.map

package/lib/types/kernel/failure.js

@@ -0,0 +1,33 @@
+const TABLE = {
+    'bad-pair': { stage: 'command', retryable: true, reportOnly: false, userMessageKey: 'failure.bad-pair' },
+    'bad-target': { stage: 'command', retryable: true, reportOnly: false, userMessageKey: 'failure.bad-target' },
+    'bad-flag': { stage: 'command', retryable: true, reportOnly: false, userMessageKey: 'failure.bad-flag' },
+    'source-gone': { stage: 'decide', retryable: true, reportOnly: true, userMessageKey: 'failure.source-gone' },
+    'source-changed': { stage: 'commit', retryable: true, reportOnly: true, userMessageKey: 'failure.source-changed' },
+    'target-taken': { stage: 'commit', retryable: false, reportOnly: true, userMessageKey: 'failure.target-taken' },
+    'validation-failed': { stage: 'validate', retryable: true, reportOnly: true, userMessageKey: 'failure.validation' },
+    'commit-failed': { stage: 'commit', retryable: false, reportOnly: true, userMessageKey: 'failure.commit' },
+    'schema-invalid': { stage: 'schema', retryable: false, reportOnly: true, userMessageKey: 'failure.schema' },
+    timeout: { stage: 'run', retryable: true, reportOnly: true, userMessageKey: 'failure.timeout' },
+    'capability-missing': { stage: 'surface', retryable: false, reportOnly: false, userMessageKey: 'failure.capability' },
+    runtime: { stage: 'run', retryable: true, reportOnly: true, userMessageKey: 'failure.runtime' },
+};
+export function failureOf(code, detail) {
+    const spec = TABLE[code];
+    return { code, stage: spec.stage, retryable: spec.retryable, reportOnly: spec.reportOnly, userMessageKey: spec.userMessageKey, ...(detail === undefined ? {} : { detail }) };
+}
+/** Only policy closures are closed; failures never map here. */
+export function closedReasonFor(code) {
+    if (code === 'merge-over-limit')
+        return 'over-limit';
+    if (code === 'keep')
+        return 'keep';
+    if (code === 'reject')
+        return 'reject';
+    return undefined;
+}
+export function isFailureRoute(reportOnly) {
+    return reportOnly;
+}
+export const FAILURE_CODES = Object.keys(TABLE);
+//# sourceMappingURL=failure.js.map

package/lib/types/kernel/index.d.ts

@@ -0,0 +1,9 @@
+export * from './model.ts';
+export * from './failure.ts';
+export * from './machine.ts';
+export * from './unit.ts';
+export * from './ledger.ts';
+export * from './projection.ts';
+export * from './recovery.ts';
+export * from './invariants.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/kernel/index.js

@@ -0,0 +1,9 @@
+export * from "./model.js";
+export * from "./failure.js";
+export * from "./machine.js";
+export * from "./unit.js";
+export * from "./ledger.js";
+export * from "./projection.js";
+export * from "./recovery.js";
+export * from "./invariants.js";
+//# sourceMappingURL=index.js.map

package/lib/types/kernel/invariants.d.ts

@@ -0,0 +1,4 @@
+/** Pure invariant checks over one pair snapshot. */
+import { type PairSnapshot } from './model.ts';
+export declare function checkPair(snapshot: PairSnapshot): string[];
+//# sourceMappingURL=invariants.d.ts.map

package/lib/types/kernel/invariants.js

@@ -0,0 +1,47 @@
+/** Pure invariant checks over one pair snapshot. */
+import { CLOSED_REASONS } from "./model.js";
+export function checkPair(snapshot) {
+    const problems = [];
+    if (snapshot.id.length === 0)
+        problems.push('id is empty');
+    if (snapshot.pairKey.length === 0)
+        problems.push('pairKey is empty');
+    if (snapshot.a.length === 0 || snapshot.b.length === 0)
+        problems.push('a/b is empty');
+    if (!Number.isInteger(snapshot.version) || snapshot.version < 0)
+        problems.push('version must be a non-negative integer');
+    if (snapshot.attempts < 0)
+        problems.push('attempts must be non-negative');
+    if (snapshot.state === 'closed') {
+        if (snapshot.closedReason === undefined || !CLOSED_REASONS.includes(snapshot.closedReason))
+            problems.push('closed requires closedReason in ' + CLOSED_REASONS.join('/'));
+        if (snapshot.failure !== undefined)
+            problems.push('closed must not carry a failure');
+    }
+    if (snapshot.state === 'failed') {
+        if (snapshot.failure === undefined)
+            problems.push('failed requires a failure');
+        if (snapshot.closedReason !== undefined)
+            problems.push('failed must not carry closedReason');
+    }
+    if (snapshot.state === 'committed') {
+        if (snapshot.receipt === undefined)
+            problems.push('committed requires a receipt');
+        if (snapshot.failure !== undefined)
+            problems.push('committed must not carry a failure');
+        if (snapshot.unitId === undefined)
+            problems.push('committed requires unitId');
+    }
+    if (snapshot.state === 'committing' && snapshot.unitId === undefined)
+        problems.push('committing requires unitId');
+    if (snapshot.state === 'staged' && (snapshot.stageRef === undefined || snapshot.stageRef.length === 0))
+        problems.push('staged requires stageRef');
+    if ((snapshot.state === 'pending' || snapshot.state === 'approved') && snapshot.decision === undefined)
+        problems.push(snapshot.state + ' requires a decision');
+    if ((snapshot.state === 'pending' || snapshot.state === 'approved') && snapshot.target === undefined)
+        problems.push(snapshot.state + ' requires a target');
+    if (snapshot.state === 'committed' && snapshot.receipt !== undefined && snapshot.receipt.unitId !== snapshot.unitId)
+        problems.push('receipt.unitId must equal unitId');
+    return problems;
+}
+//# sourceMappingURL=invariants.js.map

package/lib/types/kernel/ledger.d.ts

@@ -0,0 +1,46 @@
+/** Pure append-only ledger and deterministic fold. No IO. */
+import type { PairEvent, PairSnapshot } from './model.ts';
+import { type UnitEvent, type UnitSnapshot } from './unit.ts';
+export type LedgerEntry = {
+    readonly seq: number;
+    readonly at: string;
+    readonly type: 'pair-created';
+    readonly snapshot: PairSnapshot;
+} | {
+    readonly seq: number;
+    readonly at: string;
+    readonly type: 'pair-transition';
+    readonly pairId: string;
+    readonly expectedVersion: number;
+    readonly event: PairEvent;
+} | {
+    readonly seq: number;
+    readonly at: string;
+    readonly type: 'unit-created';
+    readonly snapshot: UnitSnapshot;
+} | {
+    readonly seq: number;
+    readonly at: string;
+    readonly type: 'unit-transition';
+    readonly unitId: string;
+    readonly expectedVersion: number;
+    readonly event: UnitEvent;
+};
+export interface LedgerState {
+    readonly seq: number;
+    readonly pairs: ReadonlyMap<string, PairSnapshot>;
+    readonly units: ReadonlyMap<string, UnitSnapshot>;
+}
+export type FoldResult = {
+    readonly ok: true;
+    readonly state: LedgerState;
+} | {
+    readonly ok: false;
+    readonly seq: number;
+    readonly message: string;
+};
+export declare function emptyLedger(): LedgerState;
+export declare function fold(entries: readonly LedgerEntry[]): FoldResult;
+/** Deterministic projection bytes for replay-equality tests. */
+export declare function ledgerProjectionJson(state: LedgerState): string;
+//# sourceMappingURL=ledger.d.ts.map

package/lib/types/kernel/ledger.js

@@ -0,0 +1,62 @@
+import { transition as transitionPair } from "./machine.js";
+import { checkPair } from "./invariants.js";
+import { checkUnit, transitionUnit } from "./unit.js";
+export function emptyLedger() {
+    return { seq: 0, pairs: new Map(), units: new Map() };
+}
+export function fold(entries) {
+    let state = emptyLedger();
+    for (const entry of entries) {
+        if (!Number.isInteger(entry.seq) || entry.seq !== state.seq + 1)
+            return { ok: false, seq: entry.seq, message: 'expected seq ' + String(state.seq + 1) + ', got ' + String(entry.seq) };
+        if (entry.type === 'pair-created') {
+            if (state.pairs.has(entry.snapshot.id))
+                return { ok: false, seq: entry.seq, message: 'duplicate pair ' + entry.snapshot.id };
+            const problems = checkPair(entry.snapshot);
+            if (problems.length > 0)
+                return { ok: false, seq: entry.seq, message: 'pair invalid: ' + problems.join('; ') };
+            state = { ...state, seq: entry.seq, pairs: new Map(state.pairs).set(entry.snapshot.id, entry.snapshot) };
+            continue;
+        }
+        if (entry.type === 'pair-transition') {
+            const current = state.pairs.get(entry.pairId);
+            if (current === undefined)
+                return { ok: false, seq: entry.seq, message: 'pair not found: ' + entry.pairId };
+            const moved = transitionPair(current, entry.event, entry.expectedVersion);
+            if (!moved.ok)
+                return { ok: false, seq: entry.seq, message: moved.message };
+            const problems = checkPair(moved.snapshot);
+            if (problems.length > 0)
+                return { ok: false, seq: entry.seq, message: 'pair invalid after transition: ' + problems.join('; ') };
+            state = { ...state, seq: entry.seq, pairs: new Map(state.pairs).set(entry.pairId, moved.snapshot) };
+            continue;
+        }
+        if (entry.type === 'unit-created') {
+            if (state.units.has(entry.snapshot.unitId))
+                return { ok: false, seq: entry.seq, message: 'duplicate unit ' + entry.snapshot.unitId };
+            const problems = checkUnit(entry.snapshot);
+            if (problems.length > 0)
+                return { ok: false, seq: entry.seq, message: 'unit invalid: ' + problems.join('; ') };
+            state = { ...state, seq: entry.seq, units: new Map(state.units).set(entry.snapshot.unitId, entry.snapshot) };
+            continue;
+        }
+        const current = state.units.get(entry.unitId);
+        if (current === undefined)
+            return { ok: false, seq: entry.seq, message: 'unit not found: ' + entry.unitId };
+        const moved = transitionUnit(current, entry.event, entry.expectedVersion);
+        if (!moved.ok)
+            return { ok: false, seq: entry.seq, message: moved.message };
+        const problems = checkUnit(moved.snapshot);
+        if (problems.length > 0)
+            return { ok: false, seq: entry.seq, message: 'unit invalid after transition: ' + problems.join('; ') };
+        state = { ...state, seq: entry.seq, units: new Map(state.units).set(entry.unitId, moved.snapshot) };
+    }
+    return { ok: true, state };
+}
+/** Deterministic projection bytes for replay-equality tests. */
+export function ledgerProjectionJson(state) {
+    const pairs = [...state.pairs.values()].sort((left, right) => left.id.localeCompare(right.id));
+    const units = [...state.units.values()].sort((left, right) => left.unitId.localeCompare(right.unitId));
+    return JSON.stringify({ seq: state.seq, pairs, units });
+}
+//# sourceMappingURL=ledger.js.map

package/lib/types/kernel/machine.d.ts

@@ -0,0 +1,13 @@
+/** Pure pair state machine. Every legal transition is explicit; no IO. */
+import type { PairEvent, PairSnapshot } from './model.ts';
+export type TransitionErrorCode = 'illegal-transition' | 'version-conflict' | 'invalid-event';
+export type TransitionResult = {
+    readonly ok: true;
+    readonly snapshot: PairSnapshot;
+} | {
+    readonly ok: false;
+    readonly code: TransitionErrorCode;
+    readonly message: string;
+};
+export declare function transition(snapshot: PairSnapshot, event: PairEvent, expectedVersion: number): TransitionResult;
+//# sourceMappingURL=machine.d.ts.map

package/lib/types/kernel/machine.js

@@ -0,0 +1,108 @@
+function fail(code, message) {
+    return { ok: false, code, message };
+}
+function clean(snapshot) {
+    const { failure, closedReason, ...rest } = snapshot;
+    void failure;
+    void closedReason;
+    return rest;
+}
+function next(snapshot, state, at, patch = {}) {
+    return { ...clean(snapshot), state, version: snapshot.version + 1, updatedAt: at, ...patch };
+}
+function requireText(value, field) {
+    return value === undefined || value.length === 0 ? fail('invalid-event', field + ' is required') : null;
+}
+export function transition(snapshot, event, expectedVersion) {
+    if (snapshot.version !== expectedVersion)
+        return fail('version-conflict', 'expected ' + String(expectedVersion) + ', got ' + String(snapshot.version));
+    const at = event.at;
+    switch (event.type) {
+        case 'screen':
+            return snapshot.state === 'candidate' ? { ok: true, snapshot: next(snapshot, 'deciding', at) } : fail('illegal-transition', 'screen from ' + snapshot.state);
+        case 'decide': {
+            if (snapshot.state !== 'deciding')
+                return fail('illegal-transition', 'decide from ' + snapshot.state);
+            if (event.decision === 'keep')
+                return { ok: true, snapshot: next(snapshot, 'closed', at, { closedReason: 'keep', origin: 'agent' }) };
+            const missing = requireText(event.target, 'target');
+            if (missing !== null)
+                return missing;
+            const decision = { target: event.target, sources: [snapshot.a, snapshot.b] };
+            const patch = { decision, target: event.target, approval: event.approval, ...(event.runId === undefined ? {} : { runId: event.runId }) };
+            return { ok: true, snapshot: next(snapshot, event.approval === 'on' ? 'pending' : 'approved', at, patch) };
+        }
+        case 'approve':
+            return snapshot.state === 'pending' ? { ok: true, snapshot: next(snapshot, 'approved', at) } : fail('illegal-transition', 'approve from ' + snapshot.state);
+        case 'reject':
+            return snapshot.state === 'pending' ? { ok: true, snapshot: next(snapshot, 'closed', at, { closedReason: 'reject', origin: 'human' }) } : fail('illegal-transition', 'reject from ' + snapshot.state);
+        case 'author-start':
+            return snapshot.state === 'approved' ? { ok: true, snapshot: next(snapshot, 'authoring', at) } : fail('illegal-transition', 'author-start from ' + snapshot.state);
+        case 'staged': {
+            if (snapshot.state !== 'authoring')
+                return fail('illegal-transition', 'staged from ' + snapshot.state);
+            const missing = requireText(event.stageRef, 'stageRef');
+            return missing ?? { ok: true, snapshot: next(snapshot, 'staged', at, { stageRef: event.stageRef }) };
+        }
+        case 'commit-start': {
+            if (snapshot.state !== 'staged')
+                return fail('illegal-transition', 'commit-start from ' + snapshot.state);
+            const missing = requireText(event.unitId, 'unitId');
+            return missing ?? { ok: true, snapshot: next(snapshot, 'committing', at, { unitId: event.unitId }) };
+        }
+        case 'commit-succeeded':
+            if (snapshot.state !== 'committing')
+                return fail('illegal-transition', 'commit-succeeded from ' + snapshot.state);
+            if (event.receipt.unitId.length === 0)
+                return fail('invalid-event', 'receipt.unitId is required');
+            return { ok: true, snapshot: next(snapshot, 'committed', at, { unitId: event.receipt.unitId, receipt: event.receipt }) };
+        case 'commit-failed':
+            return snapshot.state === 'committing' ? { ok: true, snapshot: next(snapshot, 'failed', at, { failure: event.failure }) } : fail('illegal-transition', 'commit-failed from ' + snapshot.state);
+        case 'commit-unknown':
+            return snapshot.state === 'committing' ? { ok: true, snapshot: next(snapshot, 'unknown', at) } : fail('illegal-transition', 'commit-unknown from ' + snapshot.state);
+        case 'recover': {
+            if (snapshot.state !== 'unknown')
+                return fail('illegal-transition', 'recover from ' + snapshot.state);
+            if (event.outcome === 'committed') {
+                if (event.receipt === undefined || event.receipt.unitId.length === 0)
+                    return fail('invalid-event', 'receipt is required for recovered commit');
+                return { ok: true, snapshot: next(snapshot, 'committed', at, { unitId: event.receipt.unitId, receipt: event.receipt }) };
+            }
+            if (event.outcome === 'failed') {
+                if (event.failure === undefined)
+                    return fail('invalid-event', 'failure is required for recovered failure');
+                return { ok: true, snapshot: next(snapshot, 'failed', at, { failure: event.failure }) };
+            }
+            return { ok: true, snapshot: next(snapshot, 'cancelled', at) };
+        }
+        case 'close':
+            if (event.reason !== 'over-limit')
+                return fail('invalid-event', 'close only accepts over-limit; keep/reject belong to decide/reject');
+            return snapshot.state === 'authoring' || snapshot.state === 'staged'
+                ? { ok: true, snapshot: next(snapshot, 'closed', at, { closedReason: event.reason }) }
+                : fail('illegal-transition', 'close from ' + snapshot.state);
+        case 'expire':
+            return snapshot.state === 'pending' || snapshot.state === 'staged'
+                ? { ok: true, snapshot: next(snapshot, 'expired', at) }
+                : fail('illegal-transition', 'expire from ' + snapshot.state);
+        case 'cancel':
+            return ['candidate', 'deciding', 'pending', 'approved', 'authoring', 'staged', 'unknown'].includes(snapshot.state)
+                ? { ok: true, snapshot: next(snapshot, 'cancelled', at) }
+                : fail('illegal-transition', 'cancel from ' + snapshot.state);
+        case 'fail':
+            return ['candidate', 'deciding', 'pending', 'approved', 'authoring', 'staged'].includes(snapshot.state)
+                ? { ok: true, snapshot: next(snapshot, 'failed', at, { failure: event.failure }) }
+                : fail('illegal-transition', 'fail from ' + snapshot.state);
+        case 'retry':
+            return snapshot.state === 'failed'
+                ? { ok: true, snapshot: next(snapshot, 'candidate', at, { attempts: snapshot.attempts + 1 }) }
+                : fail('illegal-transition', 'retry from ' + snapshot.state);
+        case 'undo':
+            return snapshot.state === 'committed' ? { ok: true, snapshot: next(snapshot, 'undone', at) } : fail('illegal-transition', 'undo from ' + snapshot.state);
+        case 'supersede':
+            return snapshot.state === 'undone' ? fail('illegal-transition', 'supersede from undone') : { ok: true, snapshot: next(snapshot, 'superseded', at) };
+        default:
+            return fail('invalid-event', 'unknown event');
+    }
+}
+//# sourceMappingURL=machine.js.map

package/lib/types/kernel/model.d.ts

@@ -0,0 +1,154 @@
+/** Pure merge-kernel model. No IO, no host, no clock. */
+export type PairState = 'candidate' | 'deciding' | 'pending' | 'approved' | 'authoring' | 'staged' | 'committing' | 'committed' | 'closed' | 'expired' | 'failed' | 'cancelled' | 'undone' | 'superseded' | 'unknown';
+export type ClosedReason = 'keep' | 'reject' | 'over-limit';
+export type ApprovalState = 'on' | 'off';
+export type FailureStage = 'command' | 'screen' | 'decide' | 'author' | 'validate' | 'commit' | 'run' | 'surface' | 'schema';
+export type FailureCode = 'bad-pair' | 'bad-target' | 'bad-flag' | 'source-gone' | 'source-changed' | 'target-taken' | 'validation-failed' | 'commit-failed' | 'schema-invalid' | 'timeout' | 'capability-missing' | 'runtime';
+export interface Failure {
+    readonly code: FailureCode;
+    readonly stage: FailureStage;
+    readonly retryable: boolean;
+    readonly reportOnly: boolean;
+    readonly userMessageKey: string;
+    readonly detail?: string;
+}
+export interface MergeDecision {
+    readonly target: string;
+    readonly sources: readonly string[];
+    readonly rationale?: string;
+}
+export interface CommitReceipt {
+    readonly unitId: string;
+    readonly evidenceSha256: string;
+    readonly targetRevision?: string;
+    readonly sourceRevisions?: Readonly<Record<string, string>>;
+}
+export type RunState = 'queued' | 'screening' | 'deciding' | 'awaiting-approval' | 'authoring' | 'committing' | 'settled' | 'failed' | 'cancelled' | 'recovering';
+export interface SkillSnapshot {
+    readonly name: string;
+    readonly revision: string;
+    readonly protection?: 'managed' | 'bundled' | 'hub' | 'pinned' | 'protected' | 'unknown';
+}
+export interface Candidate {
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly evidenceSeq: readonly number[];
+    readonly score?: number;
+}
+export interface RunSnapshot {
+    readonly id: string;
+    readonly state: RunState;
+    readonly version: number;
+    readonly pairs: readonly string[];
+    readonly startedAt: string;
+    readonly updatedAt: string;
+}
+export interface UnitEffect {
+    readonly kind: 'skill' | 'usage' | 'staging' | 'report';
+    readonly ref: string;
+}
+export interface UnitPlan {
+    readonly unitId: string;
+    readonly pairKey: string;
+    readonly target: string;
+    readonly sources: readonly string[];
+    readonly effects: readonly UnitEffect[];
+}
+export interface PairSnapshot {
+    readonly id: string;
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly state: PairState;
+    readonly version: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly origin?: 'agent' | 'human' | 'system';
+    readonly runId?: string;
+    readonly target?: string;
+    readonly decision?: MergeDecision;
+    readonly approval?: ApprovalState;
+    readonly failure?: Failure;
+    readonly closedReason?: ClosedReason;
+    readonly stageRef?: string;
+    readonly unitId?: string;
+    readonly expiresAt?: number;
+    readonly receipt?: CommitReceipt;
+    readonly attempts: number;
+}
+export type PairEvent = {
+    readonly type: 'screen';
+    readonly at: string;
+} | {
+    readonly type: 'decide';
+    readonly at: string;
+    readonly decision: 'merge' | 'keep';
+    readonly approval: ApprovalState;
+    readonly target?: string;
+    readonly runId?: string;
+} | {
+    readonly type: 'approve';
+    readonly at: string;
+} | {
+    readonly type: 'reject';
+    readonly at: string;
+} | {
+    readonly type: 'author-start';
+    readonly at: string;
+} | {
+    readonly type: 'staged';
+    readonly at: string;
+    readonly stageRef: string;
+} | {
+    readonly type: 'commit-start';
+    readonly at: string;
+    readonly unitId: string;
+} | {
+    readonly type: 'commit-succeeded';
+    readonly at: string;
+    readonly receipt: CommitReceipt;
+} | {
+    readonly type: 'commit-failed';
+    readonly at: string;
+    readonly failure: Failure;
+} | {
+    readonly type: 'commit-unknown';
+    readonly at: string;
+    readonly reason: string;
+} | {
+    readonly type: 'recover';
+    readonly at: string;
+    readonly outcome: 'committed' | 'failed' | 'cancelled';
+    readonly receipt?: CommitReceipt;
+    readonly failure?: Failure;
+} | {
+    readonly type: 'close';
+    readonly at: string;
+    readonly reason: ClosedReason;
+} | {
+    readonly type: 'expire';
+    readonly at: string;
+    readonly reason: 'pending-ttl' | 'staging-ttl';
+} | {
+    readonly type: 'cancel';
+    readonly at: string;
+} | {
+    readonly type: 'fail';
+    readonly at: string;
+    readonly failure: Failure;
+} | {
+    readonly type: 'retry';
+    readonly at: string;
+} | {
+    readonly type: 'undo';
+    readonly at: string;
+} | {
+    readonly type: 'supersede';
+    readonly at: string;
+};
+export declare const TERMINAL_STATES: readonly PairState[];
+export declare const ACTIVE_STATES: readonly PairState[];
+export declare const ALL_STATES: readonly PairState[];
+export declare const CLOSED_REASONS: readonly ClosedReason[];
+//# sourceMappingURL=model.d.ts.map