@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

package/lib/types/scan-run.js

@@ -2,10 +2,14 @@
  * The scan pair loop. Registry/report lifecycle stays in withMergeRun; this module owns
  * candidate → round1 → pending/fuse → commit transitions and returns the report draft.
  */
-import { pairKey, } from "./contracts.js";
-import { transition } from "./coordinator.js";
-import { dropRow, loadMergeState, upsertRow } from "./state.js";
-import { recordPair } from "./domain/pair-index-store.js";
+import { pairKey, rowIdOf, } from "./contracts.js";
+import { loadMergeState } from "./state.js";
+import { pairLedger } from "./domain/pair-ledger.js";
+import { presentStage, dropStage } from "./domain/stage-aggregate.js";
+import { recordPair } from "./domain/run-coordinator.js";
+import { v4ToLegacy } from "./domain/row-v4.js";
+import { criteriaFrom } from "./domain/engine-criteria.js";
+import { withDecisionRevisions } from "./revision.js";
 const isAborted = (signal) => signal.aborted;
 function at(now) {
     return new Date(now()).toISOString();
@@ -45,8 +49,10 @@ export async function runScan(options) {
     const startedAt = options.startedAt ?? options.now();
     const timeoutMs = (options.timeoutMinutes ?? 0) > 0 ? options.timeoutMinutes * 60_000 : 0;
     const pairs = [];
+    const degradedNotes = [];
     const totals = { merged: 0, kept: 0, pending: 0, failed: 0 };
     const remaining = [];
+    const finalizeRows = [];
     let stopReason = 'completed';
     for (let index = 0; index < candidates.length; index += 1) {
         if (isAborted(options.signal)) {
@@ -63,28 +69,37 @@ export async function runScan(options) {
         await stage('decide', { done: index, total: candidates.length });
         let row;
         try {
-            const created = transition(undefined, { type: 'candidate', a: candidate.a, b: candidate.b, at: at(options.now) });
-            if (!created.ok || created.row === null)
-                throw new Error(created.ok ? 'candidate row missing' : created.message);
-            row = options.runId === undefined ? created.row : { ...created.row, runId: options.runId };
+            const key = pairKey(candidate.a, candidate.b);
+            const atNow = at(options.now);
+            row = { id: rowIdOf(key), pairKey: key, a: candidate.a, b: candidate.b, state: 'verify', queue: 'verify', createdAt: atNow, updatedAt: atNow, ...(options.runId === undefined ? {} : { runId: options.runId }) };
             const before = (await loadMergeState(options.io, options.home)).state.rows.find(item => item.pairKey === row.pairKey);
             if (before?.state === 'verify' && before.runId !== undefined && before.runId !== options.runId
                 && (await options.isOwnerActive?.(before.runId)) === true) {
                 continue;
             }
-            const placed = await upsertRow(options.io, options.home, options.now, row, 'verify', before?.updatedAt ?? null);
-            if (!placed.ok && before?.state === 'skipped') {
-                const restored = transition(before, { type: 'restore', at: at(options.now) });
-                if (!restored.ok || restored.row === null)
-                    throw new Error('cannot restore skipped pair');
-                const persisted = await upsertRow(options.io, options.home, options.now, restored.row, 'any', before.updatedAt);
-                if (!persisted.ok)
-                    throw new Error('pair changed while restoring skipped row');
-                row = restored.row;
-            }
-            else if (!placed.ok) {
-                throw new Error('pair already in ' + placed.current.state);
-            }
+            const status = await pairLedger(options.io, options.home).transact(tx => {
+                const current = tx.rows().find(item => item.pairKey === row.pairKey);
+                if (current !== undefined && current.state !== 'verify' && current.state !== 'skipped')
+                    return 'conflict:' + current.state;
+                if (current?.state === 'skipped') {
+                    const removed = tx.transition(current.id, { type: 'restored' }, current.version);
+                    if (!removed.ok)
+                        return 'restore-failed';
+                }
+                if (current?.state === 'verify')
+                    return 'existing';
+                const made = tx.createVerify({
+                    id: current?.id ?? rowIdOf(row.pairKey), pairKey: row.pairKey, a: row.a, b: row.b,
+                    version: 0, createdAt: at(options.now), updatedAt: at(options.now), origin: 'agent',
+                    state: 'verify', verifySubState: 'unverified', attempts: 0,
+                    ...(row.runId === undefined ? {} : { runId: row.runId }),
+                });
+                return made.ok ? 'created' : 'invalid:' + made.code;
+            });
+            if (status.startsWith('conflict:'))
+                throw new Error('pair already in ' + status.slice(9));
+            if (status === 'restore-failed' || status.startsWith('invalid:'))
+                throw new Error('cannot place verify row: ' + status);
         }
         catch (error) {
             totals.failed += 1;
@@ -94,6 +109,15 @@ export async function runScan(options) {
             });
             continue;
         }
+        if (options.ports.resolve !== undefined && !(await options.ports.resolve(candidate))) {
+            await pairLedger(options.io, options.home).transact(tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                return current === undefined ? false : tx.remove(row.id, 'superseded', undefined, current.version).ok;
+            });
+            pairs.push(pairOf(row, candidate, 'failed', { failure: { stage: 'decide', code: 'source-gone', message: 'source skill disappeared before round1', retryable: false, retryFrom: 'none' } }));
+            totals.failed += 1;
+            continue;
+        }
         let round1;
         try {
             round1 = await options.ports.round1(candidate, options.signal);
@@ -107,23 +131,43 @@ export async function runScan(options) {
             break;
         }
         if (round1.kind === 'failed') {
-            const next = transition(row, { type: 'round1-fail', failure: round1.failure ?? failureOf('decide', 'round1 failed'), at: at(options.now) });
-            if (next.ok && next.row !== null) {
-                row = next.row;
-                await upsertRow(options.io, options.home, options.now, row);
+            if (round1.degraded !== undefined)
+                degradedNotes.push(...round1.degraded);
+            const failure = round1.failure ?? failureOf('decide', 'round1 failed');
+            const projected = await pairLedger(options.io, options.home).transact(tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined)
+                    return null;
+                const moved = tx.transition(row.id, { type: 'failed', failure }, current.version);
+                return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
+            });
+            if (projected === null) {
+                pairs.push(pairOf(row, candidate, 'failed', { failure: failureOf('decide', 'row changed before failure record') }));
+                totals.failed += 1;
+                continue;
             }
-            pairs.push(pairOf(row, candidate, 'failed', { failure: round1.failure ?? failureOf('decide', 'round1 failed') }));
+            row = projected;
+            pairs.push(pairOf(row, candidate, 'failed', { failure }));
             totals.failed += 1;
             continue;
         }
         if (round1.kind === 'keep') {
-            const next = transition(row, { type: 'round1-keep', at: at(options.now) });
-            if (next.ok && next.row !== null) {
-                row = next.row;
-                await upsertRow(options.io, options.home, options.now, row);
-                await recordPair(options.io, options.home, { pairKey: row.pairKey, runId: row.runId ?? 'merge', result: 'kept' });
+            const projected = await pairLedger(options.io, options.home).transact(tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined)
+                    return null;
+                const keepReason = round1.decision?.rationale?.trim();
+                const moved = tx.transition(row.id, { type: 'skipped', ...(keepReason === undefined || keepReason === '' ? { reason: 'kept' } : { reason: keepReason }), origin: 'agent' }, current.version);
+                return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
+            });
+            if (projected === null) {
+                pairs.push(pairOf(row, candidate, 'failed', { failure: failureOf('decide', 'row changed before keep record') }));
+                totals.failed += 1;
+                continue;
             }
-            pairs.push(pairOf(row, candidate, 'kept', round1.decision === undefined ? {} : { decision: round1.decision }));
+            row = projected;
+            await recordPair(options.io, options.home, { pairKey: row.pairKey, runId: row.runId ?? 'merge', result: 'kept' });
+            pairs.push(pairOf(row, candidate, 'kept', { ...(round1.decision === undefined ? {} : { decision: round1.decision }), ...(round1.usage === undefined ? {} : { usage: round1.usage }) }));
             totals.kept += 1;
             continue;
         }
@@ -132,30 +176,74 @@ export async function runScan(options) {
             totals.failed += 1;
             continue;
         }
+        const mergeDecision = options.cards !== undefined ? withDecisionRevisions(round1.decision, options.cards, row.a, row.b) : round1.decision;
         if (options.approval) {
-            const next = transition(row, { type: 'round1-merge', approval: 'on', decision: round1.decision, ...(round1.sourceRevision === undefined ? {} : { sourceRevision: round1.sourceRevision }), ...(round1.targetRevision === undefined ? {} : { targetRevision: round1.targetRevision }), at: at(options.now) });
-            if (next.ok && next.row !== null) {
-                row = next.row;
-                await upsertRow(options.io, options.home, options.now, row);
+            const event = { type: 'verify-passed', decision: mergeDecision, target: mergeDecision.target, ...(round1.sourceRevision === undefined ? {} : { sourceRevision: round1.sourceRevision }), ...(mergeDecision.promptVersion === undefined ? {} : { promptVersion: mergeDecision.promptVersion }), ...(mergeDecision.promptHash === undefined ? {} : { promptHash: mergeDecision.promptHash }) };
+            const projected = await pairLedger(options.io, options.home).transact(tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined)
+                    return null;
+                const moved = tx.transition(row.id, event, current.version);
+                return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
+            });
+            if (projected === null) {
+                pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failureOf('decide', 'row changed before pending record') }));
+                totals.failed += 1;
+                continue;
             }
-            pairs.push(pairOf(row, candidate, 'pending', { decision: round1.decision }));
+            row = projected;
+            pairs.push(pairOf(row, candidate, 'pending', { decision: mergeDecision }));
             totals.pending += 1;
             continue;
         }
-        const fuse = transition(row, { type: 'round1-merge', approval: 'off', decision: round1.decision, ...(round1.stagingRef === undefined ? {} : { stagingRef: round1.stagingRef }), ...(round1.stagingExpiresAt === undefined ? {} : { stagingExpiresAt: round1.stagingExpiresAt }), at: at(options.now) });
-        if (!fuse.ok || fuse.row === null) {
-            pairs.push(pairOf(row, candidate, 'failed', { decision: round1.decision, failure: failureOf('decide', 'cannot enter fuse') }));
+        const approved = await pairLedger(options.io, options.home).transact(tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            if (current === undefined)
+                return null;
+            const moved = tx.transition(row.id, { type: 'auto-approved', decision: mergeDecision, target: mergeDecision.target, ...(row.runId === undefined ? {} : { runId: row.runId }) }, current.version);
+            return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
+        });
+        if (approved === null) {
+            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failureOf('author', 'row changed before approve record') }));
             totals.failed += 1;
             continue;
         }
-        row = fuse.row;
-        await upsertRow(options.io, options.home, options.now, row);
-        if (isAborted(options.signal)) {
-            const cancelled = transition(row, { type: 'round2-cancel', at: at(options.now) });
-            if (cancelled.ok && cancelled.row !== null) {
-                row = cancelled.row;
-                await upsertRow(options.io, options.home, options.now, row);
+        row = approved;
+        let stageEntry;
+        if (options.ports.stage !== undefined) {
+            const staged = await options.ports.stage(row, mergeDecision);
+            if (!staged.ok) {
+                pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failureOf('author', staged.message) }));
+                totals.failed += 1;
+                continue;
             }
+            stageEntry = staged.entry;
+        }
+        const fused = await pairLedger(options.io, options.home).transact(tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            if (current === undefined)
+                return null;
+            const moved = tx.transition(row.id, { type: 'staged' }, current.version);
+            return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
+        });
+        if (fused === null) {
+            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failureOf('author', 'row changed before staging record') }));
+            totals.failed += 1;
+            continue;
+        }
+        row = fused;
+        if (stageEntry !== undefined)
+            await presentStage(options.io, options.home, stageEntry);
+        if (isAborted(options.signal)) {
+            const projected = await pairLedger(options.io, options.home).transact(tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined)
+                    return null;
+                const moved = tx.transition(row.id, { type: 'skipped', reason: 'cancelled' }, current.version);
+                return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
+            });
+            if (projected !== null)
+                row = projected;
             stopReason = 'cancelled';
             remaining.push(...candidates.slice(index).map(candidate => ({ pairKey: pairKey(candidate.a, candidate.b), queue: 'fuse' })));
             break;
@@ -163,33 +251,85 @@ export async function runScan(options) {
         await stage('author', { done: index, total: candidates.length });
         let round2;
         try {
-            round2 = await options.ports.round2(row, round1.decision, options.signal);
+            round2 = await options.ports.round2(row, mergeDecision, options.signal);
         }
         catch (error) {
             round2 = { kind: 'failed', failure: failureOf('author', error) };
         }
         if (round2.kind === 'merged') {
-            const success = transition(row, { type: 'round2-success', at: at(options.now) });
-            if (success.ok)
-                await dropRow(options.io, options.home, options.now, row.id);
-            pairs.push(pairOf(row, candidate, 'merged', {
-                decision: round1.decision,
-                ...(round2.unitId === undefined ? {} : { unitId: round2.unitId }),
-                ...(round2.target === undefined ? {} : { target: round2.target }),
-                archived: round2.archived ?? [],
-            }));
+            finalizeRows.push({ id: row.id, unitId: round2.unitId ?? 'unknown', evidenceSha256: round2.evidenceSha256 ?? 'unknown' });
+            pairs.push({ ...pairOf(row, candidate, 'merged', {
+                    decision: mergeDecision,
+                    ...(round2.unitId === undefined ? {} : { unitId: round2.unitId }),
+                    ...(round2.target === undefined ? {} : { target: round2.target }),
+                    ...(round2.usage === undefined ? {} : { usage: round2.usage }),
+                    ...(round2.lengths === undefined ? {} : { lengths: round2.lengths }),
+                    archived: round2.archived ?? [],
+                }), ...(round2.validationPlan === undefined ? {} : { validationPlan: round2.validationPlan }) });
             totals.merged += 1;
             continue;
         }
         const failed = round2.failure ?? failureOf('author', 'round2 failed');
-        const next = transition(row, { type: 'round2-fail', failure: failed, at: at(options.now) });
-        if (next.ok && next.row !== null) {
-            row = next.row;
-            await upsertRow(options.io, options.home, options.now, row);
+        if (failed.code === 'merge-over-limit' || failed.code === 'limit' || failed.code === 'merge-validation') {
+            const reason = failed.code === 'merge-validation' ? 'validation-failed' : 'merge-over-limit';
+            const skipped = await pairLedger(options.io, options.home).transact(tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                return current === undefined ? false : tx.transition(row.id, { type: 'skipped', reason, origin: 'system', skipSource: 'system' }, current.version).ok;
+            });
+            if (skipped)
+                await dropStage(options.io, options.home, row.id);
+            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failed }));
+            totals.failed += 1;
+            continue;
+        }
+        if (failed.code === 'target-changed' || failed.code === 'target-taken' || failed.code === 'source-changed' || failed.code === 'support-changed' || failed.code === 'source-gone') {
+            const code = failed.code === 'target-changed' ? 'target-taken' : failed.code === 'support-changed' ? 'source-changed' : failed.code;
+            await pairLedger(options.io, options.home).transact(tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined)
+                    return false;
+                if (code === 'source-gone')
+                    return tx.remove(row.id, 'superseded', undefined, current.version).ok;
+                return tx.transition(row.id, { type: 'skipped', reason: code, origin: 'system', skipSource: 'system' }, current.version).ok;
+            });
+            await dropStage(options.io, options.home, row.id);
+            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: { ...failed, code, retryable: false, retryFrom: 'none' } }));
+            totals.failed += 1;
+            continue;
+        }
+        const terminal = failed.code === 'commit-failed' || failed.code === 'validation-failed' || failed.code === 'merge-validation';
+        const projected = terminal ? null : await pairLedger(options.io, options.home).transact(tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            if (current === undefined)
+                return null;
+            const moved = tx.transition(row.id, { type: 'failed', failure: failed }, current.version);
+            return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
+        });
+        if (projected === null && terminal) {
+            await pairLedger(options.io, options.home).transact(tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                return current === undefined ? false : tx.remove(row.id, 'superseded', undefined, current.version).ok;
+            });
+            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failed }));
+            totals.failed += 1;
+            continue;
+        }
+        if (projected === null) {
+            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failureOf('author', 'row changed before failure record') }));
+            totals.failed += 1;
+            continue;
         }
-        pairs.push(pairOf(row, candidate, 'failed', { decision: round1.decision, failure: failed }));
+        row = projected;
+        pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failed }));
         totals.failed += 1;
     }
+    const selectionReportOnly = candidates.reportOnly ?? [];
+    const selectionReportOnlyPairs = selectionReportOnly.flatMap(raw => {
+        const value = raw;
+        if (typeof value.a !== 'string' || typeof value.b !== 'string')
+            return [];
+        return [{ id: '', pairKey: typeof value.pairKey === 'string' ? value.pairKey : pairKey(value.a, value.b), a: value.a, b: value.b, queue: 'verify', candidate: { a: value.a, b: value.b }, outcome: 'kept', archived: [], ...(value.gate === undefined ? {} : { gate: value.gate }) }];
+    });
     return {
         stopReason,
         scope: {
@@ -198,8 +338,26 @@ export async function runScan(options) {
         },
         pairs,
         totals,
-        notes: [...(options.notes ?? [])],
+        notes: [...(options.notes ?? []), ...degradedNotes],
+        reportOnly: [...pairs.filter(pair => pair.outcome === 'kept' || pair.gate?.level === 'L0' || pair.gate?.level === 'L1'), ...selectionReportOnlyPairs],
+        validationFailures: pairs.filter(pair => pair.failure !== undefined && (pair.failure.stage === 'validate' || pair.failure.code === 'merge-validation' || pair.failure.code === 'merge-over-limit')),
+        archived: [...new Set(pairs.flatMap(pair => pair.archived))],
+        ...(pairs.find(pair => pair.outcome === 'merged' && pair.unitId !== undefined) === undefined ? {} : { commit: (() => { const pair = pairs.find(item => item.outcome === 'merged' && item.unitId !== undefined); return { ...(pair.unitId === undefined ? {} : { unitId: pair.unitId }), ...(pair.target === undefined ? {} : { target: pair.target.actual ?? pair.target.requested }), ...(pair.target === undefined ? {} : { created: pair.target.created }) }; })() }),
+        ...(pairs.every(pair => pair.usage === undefined) ? {} : { usage: { inputTokens: pairs.reduce((sum, pair) => sum + (pair.usage?.inputTokens ?? 0), 0), outputTokens: pairs.reduce((sum, pair) => sum + (pair.usage?.outputTokens ?? 0), 0), totalTokens: pairs.reduce((sum, pair) => sum + (pair.usage?.totalTokens ?? 0), 0), costCny: pairs.reduce((sum, pair) => sum + (pair.usage?.costCny ?? 0), 0) } }),
+        timing: { screeningMs: 0, gateMs: 0, agentMs: Math.max(0, options.now() - startedAt), commitMs: 0 },
+        criteria: pairs.map(pair => pair.criteria ?? criteriaFrom(pair.gate?.level ?? 'L2', pair.gate?.verdict ?? 0, pair.decision?.shouldMerge === true ? 'merge' : 'keep')),
         ...(remaining.length === 0 ? {} : { remaining }),
+        ...(finalizeRows.length === 0 ? {} : { finalize: async () => {
+                for (const item of finalizeRows) {
+                    const removed = await pairLedger(options.io, options.home).transact(tx => {
+                        const current = tx.rows().find(entry => entry.id === item.id);
+                        return current === undefined ? true : tx.remove(item.id, 'committed', { unitId: item.unitId, evidenceSha256: item.evidenceSha256 }, current.version).ok;
+                    });
+                    if (!removed)
+                        throw new Error('row changed before commit record: ' + item.id);
+                    await dropStage(options.io, options.home, item.id);
+                }
+            } })
     };
 }
 //# sourceMappingURL=scan-run.js.map

package/lib/types/screening-port.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The real screening port: lexical floor + optional C3 proposal + optional L0–L2 gate.
+ * Each stage is independently testable; this file only composes their frozen contracts.
+ */
+import { type MergeCandidate } from './contracts.ts';
+import { type SkillCard, type ScreeningOptions } from './screening.ts';
+import { type ModelPort } from './propose.ts';
+import type { GateCache, GateModelPort } from './ladder.ts';
+export interface ScreeningForRunOptions extends Omit<BuildScreeningOptions, 'signal'> {
+    readonly runSeed: string;
+}
+export interface BuildScreeningOptions {
+    readonly cards: readonly SkillCard[];
+    readonly signal: AbortSignal;
+    readonly lexical?: ScreeningOptions;
+    readonly propose?: {
+        readonly model: ModelPort;
+        readonly shardSize?: number;
+        readonly maxPairs?: number;
+    };
+    readonly gate?: {
+        readonly model: GateModelPort;
+        readonly modelName: string;
+        readonly runSeed: string;
+        readonly cache?: GateCache;
+        readonly auditRate?: number;
+    };
+}
+export interface ScreeningPortStats {
+    readonly lexical: number;
+    readonly proposed: number;
+    readonly candidates: number;
+    readonly kept: number;
+    readonly dropped: number;
+    readonly gateCalls: number;
+    readonly gateErrors: number;
+    readonly shards: number;
+}
+export interface ScreeningPortResult {
+    readonly candidates: readonly MergeCandidate[];
+    readonly stats: ScreeningPortStats;
+    readonly degraded: readonly string[];
+}
+export declare function buildScreeningCandidates(options: BuildScreeningOptions): Promise<ScreeningPortResult>;
+/** Build the run-scoped screening function; the run id seeds the 10% audit. */
+export declare function createScreeningForRun(options: ScreeningForRunOptions): (signal: AbortSignal) => Promise<readonly MergeCandidate[]>;
+//# sourceMappingURL=screening-port.d.ts.map

package/lib/types/screening-port.js

@@ -0,0 +1,93 @@
+/**
+ * The real screening port: lexical floor + optional C3 proposal + optional L0–L2 gate.
+ * Each stage is independently testable; this file only composes their frozen contracts.
+ */
+import { pairKey } from "./contracts.js";
+import { lexicalCandidates } from "./screening.js";
+import { proposePairs } from "./propose.js";
+import { filterCandidates } from "./gate-filter.js";
+export async function buildScreeningCandidates(options) {
+    const lexical = lexicalCandidates(options.cards, options.lexical);
+    const merged = new Map();
+    for (const candidate of lexical.candidates)
+        merged.set(pairKey(candidate.a, candidate.b), candidate);
+    const degraded = [];
+    let proposed = 0;
+    let shards = 0;
+    if (options.propose !== undefined) {
+        const proposal = await proposePairs(options.cards, options.propose.model, {
+            signal: options.signal,
+            ...(options.propose.shardSize === undefined ? {} : { shardSize: options.propose.shardSize }),
+            ...(options.propose.maxPairs === undefined ? {} : { maxPairs: options.propose.maxPairs }),
+        });
+        proposed = proposal.candidates.length;
+        shards = proposal.shards;
+        degraded.push(...proposal.degraded);
+        for (const candidate of proposal.candidates) {
+            const key = pairKey(candidate.a, candidate.b);
+            const existing = merged.get(key);
+            if (existing === undefined) {
+                merged.set(key, candidate);
+                continue;
+            }
+            const arms = [...new Set([...(existing.arms ?? []), ...(candidate.arms ?? [])])];
+            merged.set(key, {
+                ...existing,
+                ...(candidate.reason === undefined || existing.reason !== undefined ? {} : { reason: candidate.reason }),
+                ...(arms.length === 0 ? {} : { arms }),
+            });
+        }
+    }
+    let candidates = [...merged.values()].sort((left, right) => (right.score ?? 0) - (left.score ?? 0)
+        || left.a.localeCompare(right.a)
+        || left.b.localeCompare(right.b));
+    let kept = candidates.length;
+    let dropped = 0;
+    let gateCalls = 0;
+    let gateErrors = 0;
+    if (options.gate !== undefined) {
+        const facts = options.cards.map(card => ({ name: card.name, description: card.description, body: card.body }));
+        const filtered = await filterCandidates(candidates, {
+            facts,
+            model: options.gate.model,
+            modelName: options.gate.modelName,
+            signal: options.signal,
+            runSeed: options.gate.runSeed,
+            ...(options.gate.cache === undefined ? {} : { cache: options.gate.cache }),
+            ...(options.gate.auditRate === undefined ? {} : { auditRate: options.gate.auditRate }),
+        });
+        candidates = filtered.kept.map(decision => decision.candidate);
+        kept = filtered.kept.length;
+        dropped = filtered.dropped.length;
+        gateCalls = filtered.calls;
+        gateErrors = filtered.errors.length;
+        for (const error of filtered.errors)
+            degraded.push('gate error: ' + error.candidate.a + ' + ' + error.candidate.b + ': ' + error.message);
+    }
+    return {
+        candidates,
+        stats: {
+            lexical: lexical.candidates.length,
+            proposed,
+            candidates: merged.size,
+            kept,
+            dropped,
+            gateCalls,
+            gateErrors,
+            shards,
+        },
+        degraded,
+    };
+}
+/** Build the run-scoped screening function; the run id seeds the 10% audit. */
+export function createScreeningForRun(options) {
+    const gate = options.gate === undefined ? undefined : { ...options.gate, runSeed: options.runSeed };
+    return async (signal) => (await buildScreeningCandidates({
+        cards: options.cards,
+        signal,
+        ...(options.lexical === undefined ? {} : { lexical: options.lexical }),
+        ...(options.propose === undefined ? {} : { propose: options.propose }),
+        ...(gate === undefined ? {} : { gate }),
+    })).candidates;
+}
+//# sourceMappingURL=screening-port.js.map

package/lib/types/screening.d.ts

@@ -0,0 +1,30 @@
+import type { MergeCandidate } from './contracts.ts';
+export interface SkillCard {
+    readonly name: string;
+    readonly description: string;
+    readonly body: string;
+}
+export interface ScreeningOptions {
+    /** Body Jaccard at/above this is a candidate on its own. */
+    readonly bodyGate?: number;
+    /** Description Jaccard at/above this is a candidate when the body also clears minAffinity. */
+    readonly summaryGate?: number;
+    /** Minimum body affinity for a summary-led candidate. */
+    readonly minAffinity?: number;
+    /** Upper bound after sorting by score; absent = no cap. */
+    readonly maxCandidates?: number;
+}
+export interface ScreeningStats {
+    readonly skills: number;
+    readonly filtered: number;
+    readonly candidates: number;
+}
+export interface ScreeningResult {
+    readonly candidates: readonly MergeCandidate[];
+    readonly stats: ScreeningStats;
+}
+/** Shannon entropy over characters; a cheap prefilter signal, not a name-quality judge. */
+export declare function nameEntropy(name: string): number;
+export declare function prefilter(cards: readonly SkillCard[]): readonly SkillCard[];
+export declare function lexicalCandidates(cards: readonly SkillCard[], options?: ScreeningOptions): ScreeningResult;
+//# sourceMappingURL=screening.d.ts.map

package/lib/types/screening.js

@@ -0,0 +1,75 @@
+/**
+ * Deterministic candidate screening: name prefilter + lexical affinity.
+ *
+ * The semantic proposer (C3) is a separate port; this module is the zero-cost floor that
+ * must work without a model. It reuses core `vocabulary`/`affinity` so drift/dedup and
+ * merge screening share one tokenizer.
+ */
+import { affinity, vocabulary } from '@lmzhen/dsh-evolution-core';
+/** Shannon entropy over characters; a cheap prefilter signal, not a name-quality judge. */
+export function nameEntropy(name) {
+    if (name === '')
+        return 0;
+    const counts = new Map();
+    for (const char of name)
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const p = count / name.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+const MIN_NAME_ENTROPY = 1.5;
+const MIN_NAME_LENGTH = 6;
+export function prefilter(cards) {
+    return cards.filter((card) => {
+        const name = card.name.trim();
+        if (name.length < MIN_NAME_LENGTH)
+            return false;
+        if (nameEntropy(name) < MIN_NAME_ENTROPY)
+            return false;
+        return card.body.trim() !== '' || card.description.trim() !== '';
+    });
+}
+function sortedPair(a, b) {
+    return a < b ? [a, b] : [b, a];
+}
+export function lexicalCandidates(cards, options = {}) {
+    const bodyGate = options.bodyGate ?? 0.9;
+    const summaryGate = options.summaryGate ?? 0.5;
+    const minAffinity = options.minAffinity ?? 0.3;
+    const eligible = prefilter(cards);
+    const vectors = eligible.map(card => ({
+        card,
+        summary: vocabulary(card.description),
+        body: vocabulary(card.body),
+    }));
+    const candidates = [];
+    for (let i = 0; i < vectors.length; i += 1) {
+        for (let j = i + 1; j < vectors.length; j += 1) {
+            const left = vectors[i];
+            const right = vectors[j];
+            if (left === undefined || right === undefined)
+                continue;
+            const summary = affinity(left.summary, right.summary);
+            const body = affinity(left.body, right.body);
+            const arms = [];
+            if (body >= bodyGate)
+                arms.push('body');
+            if (summary >= summaryGate && body >= minAffinity)
+                arms.push('summary');
+            if (arms.length === 0)
+                continue;
+            const [a, b] = sortedPair(left.card.name, right.card.name);
+            candidates.push({ a, b, score: Math.max(body, summary), arms, source: 'lexical' });
+        }
+    }
+    candidates.sort((left, right) => (right.score ?? 0) - (left.score ?? 0) || left.a.localeCompare(right.a) || left.b.localeCompare(right.b));
+    const capped = options.maxCandidates === undefined ? candidates : candidates.slice(0, options.maxCandidates);
+    return {
+        candidates: capped,
+        stats: { skills: cards.length, filtered: cards.length - eligible.length, candidates: capped.length },
+    };
+}
+//# sourceMappingURL=screening.js.map

package/lib/types/stage-tool-registry.d.ts

@@ -9,6 +9,13 @@ export declare class StageToolRegistry {
     bind(childId: string, context: StageToolContext): void;
     unbind(childId: string): void;
     clear(): void;
+    /** Diagnostic view for a refused tool call; names only, no content. */
+    snapshot(exec: unknown): {
+        readonly childId?: string;
+        readonly bound: number;
+        readonly authors: number;
+        readonly keys: readonly string[];
+    };
     resolve(exec: unknown): StageToolContext | undefined;
 }
 //# sourceMappingURL=stage-tool-registry.d.ts.map