@lmzhen/dsh-evolution-merge 0.30.23 → 0.30.25

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

package/lib/types/kernel/model.js

@@ -0,0 +1,5 @@
+export const TERMINAL_STATES = ['closed', 'expired', 'cancelled', 'committed', 'undone', 'superseded'];
+export const ACTIVE_STATES = ['candidate', 'deciding', 'pending', 'approved', 'authoring', 'staged', 'committing', 'unknown'];
+export const ALL_STATES = [...ACTIVE_STATES, ...TERMINAL_STATES];
+export const CLOSED_REASONS = ['keep', 'reject', 'over-limit'];
+//# sourceMappingURL=model.js.map

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

@@ -0,0 +1,28 @@
+/** Pure projection over the ledger. One expired predicate, one queue mapping. */
+import type { PairSnapshot } from './model.ts';
+import type { LedgerState } from './ledger.ts';
+import type { UnitSnapshot } from './unit.ts';
+export type ProjectionQueue = 'verify' | 'pending' | 'fuse' | 'skipped';
+export interface RowProjection {
+    readonly id: string;
+    readonly pairKey: string;
+    readonly state: PairSnapshot['state'];
+    readonly queue: ProjectionQueue | null;
+    readonly expired: boolean;
+    readonly version: number;
+}
+export interface ProjectionCounts {
+    readonly active: Readonly<Record<ProjectionQueue, number>>;
+    readonly expired: number;
+}
+export interface MergeProjection {
+    readonly seq: number;
+    readonly rows: readonly RowProjection[];
+    readonly units: readonly UnitSnapshot[];
+    readonly counts: ProjectionCounts;
+}
+export declare function queueOf(pair: PairSnapshot): ProjectionQueue | null;
+export declare function isExpired(pair: PairSnapshot, now: number): boolean;
+export declare function project(state: LedgerState, now: number): MergeProjection;
+export declare function projectionJson(projection: MergeProjection): string;
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/kernel/projection.js

@@ -0,0 +1,44 @@
+export function queueOf(pair) {
+    switch (pair.state) {
+        case 'candidate':
+        case 'deciding': return 'verify';
+        case 'pending': return 'pending';
+        case 'approved':
+        case 'authoring':
+        case 'staged':
+        case 'committing':
+        case 'unknown':
+        case 'failed': return 'fuse';
+        case 'closed': return 'skipped';
+        case 'expired': return 'skipped';
+        default: return null;
+    }
+}
+export function isExpired(pair, now) {
+    if (pair.state === 'expired')
+        return true;
+    if (pair.expiresAt === undefined)
+        return false;
+    if (pair.state !== 'pending' && pair.state !== 'staged')
+        return false;
+    return pair.expiresAt <= now;
+}
+export function project(state, now) {
+    const counts = { active: { verify: 0, pending: 0, fuse: 0, skipped: 0 }, expired: 0 };
+    const rows = [];
+    for (const pair of [...state.pairs.values()].sort((left, right) => left.id.localeCompare(right.id))) {
+        const expired = isExpired(pair, now);
+        const queue = queueOf(pair);
+        rows.push({ id: pair.id, pairKey: pair.pairKey, state: pair.state, queue, expired, version: pair.version });
+        if (expired)
+            counts.expired += 1;
+        else if (queue !== null)
+            counts.active[queue] += 1;
+    }
+    const units = [...state.units.values()].sort((left, right) => left.unitId.localeCompare(right.unitId));
+    return { seq: state.seq, rows, units, counts };
+}
+export function projectionJson(projection) {
+    return JSON.stringify(projection);
+}
+//# sourceMappingURL=projection.js.map