@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/analysis_emit.ts

@@ -0,0 +1,150 @@
+/**
+ * analysis_emit.ts — turns a round's surviving findings into what lands
+ * locally: owner-first arrivals on existing roadmaps, and at most one new
+ * central roadmap with every other finding as a phase.
+ *
+ * Owner-first is the growth cap: a finding whose subject already has a
+ * roadmap becomes a step plus an `Arrivals:` line there, so a round adds at
+ * most one file to the estate. New roadmaps land `ready`, except above the
+ * harvest intake limit, where they land `draft` and the run says so in one
+ * line. Nothing here validates or writes; `analysis_validate.ts` gates the
+ * result before anything leaves the machine.
+ */
+import type { EvidenceTier } from './analysis_ledger.js';
+
+/** More `ready` roadmaps than this at 0 ticked steps make a new roadmap land `draft`. */
+export const INTAKE_LIMIT = 8;
+
+export interface FindingStep {
+    text: string;
+    verify: string;
+}
+
+export interface Finding {
+    id: string;
+    title: string;
+    claim: string;
+    anchor: string;
+    tier: EvidenceTier;
+    steps: FindingStep[];
+    /** Slug (without `road-to-`) of the roadmap that already owns the subject. */
+    owner?: string;
+    blocked_until?: string;
+}
+
+export interface EmittedRoadmap {
+    slug: string;
+    status: 'ready' | 'draft';
+    body: string;
+}
+
+export interface Arrival {
+    slug: string;
+    finding_id: string;
+    step: string;
+    arrivals_line: string;
+}
+
+export interface EmitResult {
+    roadmaps: EmittedRoadmap[];
+    arrivals: Arrival[];
+    estate_delta: number;
+    status_note: string | null;
+}
+
+export interface EmitInput {
+    roundId: string;
+    date: string;
+    slug: string;
+    findings: readonly Finding[];
+    readyAtZero: number;
+    intakeLimit?: number;
+    /** The phase number an arrival opens in its owner roadmap; needed when any finding has an owner. */
+    ownerNextPhase?: (slug: string) => number | null;
+}
+
+function stepLines(n: string, step: FindingStep): string {
+    return `- [ ] **${n} ${step.text}.**\n      verify: ${step.verify}`;
+}
+
+function phaseHeading(i: number, f: Finding): string {
+    return `Phase ${String(i + 1)} — ${f.title}`;
+}
+
+function roadmapBody(input: EmitInput, findings: readonly Finding[], status: 'ready' | 'draft'): string {
+    const phases = findings.map((f, i) => {
+        const steps = f.steps.map((s, k) => stepLines(`${String(i + 1)}.${String(k + 1)}`, s)).join('\n');
+        const blocked = f.blocked_until === undefined ? '' : `> Blocked until ${f.blocked_until}.\n\n`;
+        return `## ${phaseHeading(i, f)}\n\n${f.claim} Evidence (${f.tier}): \`${f.anchor}\`.\n\n${blocked}${steps}\n`;
+    });
+    const risks = findings.map(
+        (f, i) =>
+            `| ${String(i + 1)} | ${f.title} not delivered | implementation | The claim at \`${f.anchor}\` still holds after the phase | each step carries its \`verify:\` line | ${phaseHeading(i, f)} |`,
+    );
+    const acs = findings.map(
+        (f, i) => `- [ ] AC-${String(i + 1)} — ${f.title}: the claim of Phase ${String(i + 1)} no longer holds at the tree.`,
+    );
+    return [
+        '---',
+        'complexity: lightweight',
+        `status: ${status}`,
+        'execution:',
+        '  mode: phase-checkpoints',
+        '---',
+        `# Road to ${input.slug.replace(/-/g, ' ')}`,
+        '',
+        `> **Source:** analysis round \`${input.roundId}\` (${input.date}).`,
+        '',
+        '## Goal',
+        '',
+        `Every finding of round \`${input.roundId}\` below is resolved against the tree.`,
+        '',
+        ...phases,
+        '## Risk Register',
+        `<!-- risk-review: v1 | reviewed: ${input.date} | reviewer: claude/host -->`,
+        '',
+        '| Rank | Item | Risk type | Description | Mitigation | Anchored under |',
+        '|------|------|-----------|-------------|------------|----------------|',
+        ...risks,
+        '',
+        '## Acceptance Criteria',
+        '',
+        ...acs,
+        '',
+    ].join('\n');
+}
+
+export function emitRound(input: EmitInput): EmitResult {
+    const limit = input.intakeLimit ?? INTAKE_LIMIT;
+    const owned = input.findings.filter((f) => f.owner !== undefined);
+    const fresh = input.findings.filter((f) => f.owner === undefined);
+
+    const arrivals = owned.map((f) => {
+        const slug = f.owner as string;
+        // A literal placeholder would land in the owner roadmap as its step id.
+        const phase = input.ownerNextPhase?.(slug) ?? null;
+        if (phase === null || !Number.isInteger(phase) || phase < 1) {
+            throw new Error(`analysis_emit: no next phase number for owner roadmap road-to-${slug} (finding ${f.id})`);
+        }
+        return {
+            slug,
+            finding_id: f.id,
+            step: f.steps.map((s, k) => stepLines(`${String(phase)}.${String(k + 1)}`, s)).join('\n'),
+            arrivals_line: `> **Arrivals:** latest \`${input.roundId}\` (${input.date}) — ${f.id}`,
+        };
+    });
+
+    if (fresh.length === 0) return { roadmaps: [], arrivals, estate_delta: 0, status_note: null };
+
+    const draft = input.readyAtZero > limit;
+    const status = draft ? 'draft' : 'ready';
+    const status_note = draft
+        ? `draft: ${String(input.readyAtZero)} ready roadmaps sit at 0 ticked steps, above the intake limit of ${String(limit)}`
+        : null;
+    return {
+        roadmaps: [{ slug: input.slug, status, body: roadmapBody(input, fresh, status) }],
+        arrivals,
+        estate_delta: 1,
+        status_note,
+    };
+}

package/src/scripts/analysis_exchange.ts

@@ -0,0 +1,186 @@
+/**
+ * analysis_exchange.ts — the exchange that deepens instead of agreeing. Each
+ * analyst receives the others' finals relabelled A/B/C and runs three
+ * reconcile loops: Inventory (every foreign claim checked at the pin),
+ * Cross-exam (the disputed claims, quoted verbatim) and Converge (a
+ * disagreement ledger over its own claims).
+ *
+ * Facts are settled by the tree: only `executed` and `read` evidence settles a
+ * claim, so three `claimed` votes against it leave it unsettled. The synthesis
+ * must give every minority finding a reasoned disposition — the existing
+ * `auditMinorityRetention` is the judge, and a minority it cannot find is a
+ * silent drop.
+ */
+import {
+    buildCrossExamPrompt,
+    crossExamNamesClaim,
+    selectCrossExamTarget,
+    type DisputedClaim,
+} from './ai_council/cross_exam.js';
+import { auditMinorityRetention, type RetentionFailure } from './ai_council/minority_retention.js';
+import { TOP_TIERS, type EvidenceTier } from './analysis_ledger.js';
+
+export const EXCHANGE_LOOPS = ['inventory', 'cross-exam', 'converge'] as const;
+
+export type InventoryVerdict = 'still-true' | 'never-true' | 'unverifiable';
+export type Settlement = 'still-true' | 'never-true' | 'contested' | 'unsettled';
+
+export interface Claim {
+    id: string;
+    analyst_id: string;
+    /** Verbatim, as the analyst wrote it. */
+    text: string;
+}
+
+export interface InventoryRow {
+    claim_id: string;
+    verdict: InventoryVerdict;
+    tier: EvidenceTier;
+    /** The reader's own position, verbatim; quoted as the counter-claim in a cross-exam. */
+    position: string;
+}
+
+export interface LedgerEntry {
+    claim_id: string;
+    foreign: InventoryVerdict;
+    settled: Settlement;
+    label: string;
+}
+
+export class ExchangeError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'ExchangeError';
+    }
+}
+
+export function relabel(analysts: readonly string[]): Map<string, string> {
+    return new Map(analysts.map((id, i) => [id, String.fromCharCode(65 + i)]));
+}
+
+export function inventoryGaps(reader: string, claims: readonly Claim[], rows: readonly InventoryRow[]): string[] {
+    const checked = new Set(rows.map((r) => r.claim_id));
+    return claims.filter((c) => c.analyst_id !== reader && !checked.has(c.id)).map((c) => `${reader} did not check ${c.id}`);
+}
+
+export function settleClaim(rows: readonly InventoryRow[]): Settlement {
+    const top = rows.filter((r) => TOP_TIERS.includes(r.tier));
+    const holds = top.some((r) => r.verdict === 'still-true');
+    const fails = top.some((r) => r.verdict === 'never-true');
+    if (holds && fails) return 'contested';
+    if (fails) return 'never-true';
+    if (holds) return 'still-true';
+    return 'unsettled';
+}
+
+function rowsFor(claimId: string, inventories: Readonly<Record<string, readonly InventoryRow[]>>): Array<[string, InventoryRow]> {
+    const out: Array<[string, InventoryRow]> = [];
+    for (const [reader, rows] of Object.entries(inventories)) {
+        for (const r of rows) if (r.claim_id === claimId) out.push([reader, r]);
+    }
+    return out;
+}
+
+export function crossExamCandidates(
+    claims: readonly Claim[],
+    inventories: Readonly<Record<string, readonly InventoryRow[]>>,
+    labels: ReadonlyMap<string, string>,
+): DisputedClaim[] {
+    const out: DisputedClaim[] = [];
+    for (const claim of claims) {
+        const dissent = rowsFor(claim.id, inventories).find(([, r]) => r.verdict !== 'still-true');
+        if (dissent === undefined) continue;
+        const [reader, r] = dissent;
+        const base = {
+            id: claim.id,
+            kind: r.verdict === 'never-true' ? ('conflicting-pair' as const) : ('disputed-finding' as const),
+            assertedBy: labels.get(claim.analyst_id) ?? '?',
+            claim: claim.text,
+            disputedBy: labels.get(reader) ?? '?',
+        };
+        out.push(r.position.length > 0 ? { ...base, counterClaim: r.position } : base);
+    }
+    return out;
+}
+
+export interface MinorityFinding {
+    claim_id: string;
+    /** Distinctive phrases; a synthesis naming none of them did not engage the finding. */
+    anchors: string[];
+}
+
+export interface MinorityAudit {
+    silent_drops: string[];
+    unresolved: Array<{ claim_id: string; failures: RetentionFailure[] }>;
+}
+
+export function auditSynthesis(synthesis: string, minorities: readonly MinorityFinding[]): MinorityAudit {
+    const audit: MinorityAudit = { silent_drops: [], unresolved: [] };
+    for (const m of minorities) {
+        const verdict = auditMinorityRetention(synthesis, {
+            id: m.claim_id,
+            permanent: false,
+            question: m.claim_id,
+            // The audit reads only the anchors; which side is right is what the exchange is deciding.
+            ground_truth: 'minority',
+            minority: { member: m.claim_id, answer: '', anchors: m.anchors },
+            majority: [],
+        });
+        if (verdict.failures.includes('minority-silently-dropped')) audit.silent_drops.push(m.claim_id);
+        else if (!verdict.passed) audit.unresolved.push({ claim_id: m.claim_id, failures: [...verdict.failures] });
+    }
+    return audit;
+}
+
+export interface ExchangeRecord {
+    labels: Record<string, string>;
+    loops: typeof EXCHANGE_LOOPS;
+    targets: Array<{ target: DisputedClaim; prompt: string }>;
+    ledgers: Record<string, LedgerEntry[]>;
+    minority_audit: MinorityAudit;
+}
+
+export function buildExchange(input: {
+    analysts: readonly string[];
+    claims: readonly Claim[];
+    inventories: Readonly<Record<string, readonly InventoryRow[]>>;
+    maxTargets: number;
+    synthesis: string;
+    minorities: readonly MinorityFinding[];
+}): ExchangeRecord {
+    const gaps = input.analysts.flatMap((a) => inventoryGaps(a, input.claims, input.inventories[a] ?? []));
+    if (gaps.length > 0) throw new ExchangeError(`inventory incomplete: ${gaps.join('; ')}`);
+    const labels = relabel(input.analysts);
+
+    const pool = crossExamCandidates(input.claims, input.inventories, labels);
+    const targets: Array<{ target: DisputedClaim; prompt: string }> = [];
+    while (targets.length < input.maxTargets) {
+        const target = selectCrossExamTarget(pool);
+        if (target === null) break;
+        pool.splice(pool.indexOf(target), 1);
+        const prompt = buildCrossExamPrompt(target);
+        if (!crossExamNamesClaim(prompt, target)) throw new ExchangeError(`cross-exam prompt for ${target.id} lost the claim`);
+        targets.push({ target, prompt });
+    }
+
+    const ledgers: Record<string, LedgerEntry[]> = {};
+    for (const analyst of input.analysts) {
+        ledgers[analyst] = input.claims
+            .filter((c) => c.analyst_id === analyst)
+            .flatMap((c) => {
+                const rows = rowsFor(c.id, input.inventories);
+                const settled = settleClaim(rows.map(([, r]) => r));
+                return rows
+                    .filter(([, r]) => r.verdict !== 'still-true')
+                    .map(([reader, r]) => ({ claim_id: c.id, foreign: r.verdict, settled, label: labels.get(reader) ?? '?' }));
+            });
+    }
+
+    return {
+        labels: Object.fromEntries(labels),
+        loops: EXCHANGE_LOOPS,
+        targets,
+        ledgers,
+        minority_audit: auditSynthesis(input.synthesis, input.minorities),
+    };
+}

package/src/scripts/analysis_gate.ts

@@ -0,0 +1,158 @@
+/**
+ * analysis_gate.ts — the council as judge of what stays contested after an
+ * exchange, then the gain gate that decides whether one more round is offered.
+ *
+ * Order is the substance: the round cap first — a capped gate never evaluates
+ * the predicate, so its `stop` is null — then `evaluateStop`, which refuses to
+ * stop on agreement before anti-conformity repair ran, and only then the offer.
+ * Until calibration exists, an offer needs named open items whose executable
+ * verification plans fit the remaining budget together, admitted in input
+ * order; `scoreNextCall` is computed only for an offer, as an estimate that
+ * never decides. The owner is
+ * asked once, with a gain band and its reasons, only when the council splits
+ * or the round exceeds the ceiling.
+ */
+import { evaluateStop, type StopInputs, type StopVerdict } from './ai_council/argument_exhaustion.js';
+import { scoreNextCall, type NextCallInputs, type NextCallScore } from './ai_council/information_gain.js';
+import { EVIDENCE_TIERS, type EvidenceTier } from './analysis_ledger.js';
+
+export const MAX_ROUNDS = 3;
+export const OWNER_OPTIONS = ['one more', 'focused on the named items', 'stop'] as const;
+
+export interface Seat {
+    member: string;
+    provider: string;
+    status: 'ok' | 'failed';
+}
+
+/** Quorum is two answering seats from two providers; anything less is said, never hidden. */
+export function councilVoice(seats: readonly Seat[]): 'quorum' | 'single-voice' {
+    const ok = seats.filter((s) => s.status === 'ok');
+    return ok.length >= 2 && new Set(ok.map((s) => s.provider)).size >= 2 ? 'quorum' : 'single-voice';
+}
+
+export interface ConflictSide {
+    position: string;
+    tier: EvidenceTier;
+    critical?: boolean;
+}
+
+export interface Conflict {
+    id: string;
+    /** A safety or data-integrity question, where a critical dissent outweighs a majority. */
+    safety: boolean;
+    /** Non-empty: a conflict with no side is not a conflict, and is refused. */
+    sides: readonly [ConflictSide, ...ConflictSide[]];
+}
+
+export type ConflictResolution =
+    | { resolution: 'by-tier' | 'critical-dissent'; winner: number }
+    | { resolution: 'named'; winner: null };
+
+export function resolveConflict(c: Conflict): ConflictResolution {
+    // The tuple type is the compile-time half; this is the half for parsed JSON.
+    if ((c.sides as readonly ConflictSide[]).length === 0) throw new RangeError(`conflict ${c.id} has no sides`);
+    if (c.safety) {
+        const critical = c.sides.findIndex((s) => s.critical === true);
+        if (critical >= 0) return { resolution: 'critical-dissent', winner: critical };
+    }
+    const rank = (t: EvidenceTier): number => EVIDENCE_TIERS.indexOf(t);
+    const best = Math.min(...c.sides.map((s) => rank(s.tier)));
+    const atBest = c.sides.map((s, i) => [s, i] as const).filter(([s]) => rank(s.tier) === best);
+    const positions = new Set(atBest.map(([s]) => s.position));
+    if (positions.size > 1) return { resolution: 'named', winner: null };
+    const first = atBest[0];
+    if (first === undefined) throw new RangeError(`conflict ${c.id} has no side at its best tier`);
+    return { resolution: 'by-tier', winner: first[1] };
+}
+
+export interface OpenItem {
+    id: string;
+    kind: 'conflict' | 'claimed-high-impact';
+    plan?: { executable: boolean; estimated_tokens: number; step: string };
+}
+
+export interface GainBand {
+    level: 'low' | 'medium' | 'high';
+    reasons: string[];
+}
+
+export interface GateInput {
+    roundsCompleted: number;
+    items: OpenItem[];
+    remainingTokens: number;
+    stop: StopInputs;
+    nextCall?: NextCallInputs;
+}
+
+export interface GateResult {
+    offer: boolean;
+    reason: 'round-cap' | 'exhausted' | 'no-plannable-item' | 'offer';
+    settleable: string[];
+    /** Null when the round cap decided before the predicate ran. */
+    stop: StopVerdict | null;
+    estimate: NextCallScore | null;
+    band: GainBand | null;
+}
+
+function bandFor(items: readonly OpenItem[]): GainBand {
+    const level = items.length >= 3 ? 'high' : items.length === 2 ? 'medium' : 'low';
+    return { level, reasons: items.map((i) => `${i.id}: ${i.plan?.step ?? ''}`) };
+}
+
+/** Items admitted in input order while their plans fit the budget together, not each alone. */
+function admitWithinBudget(items: readonly OpenItem[], remainingTokens: number): OpenItem[] {
+    const admitted: OpenItem[] = [];
+    let spent = 0;
+    for (const i of items) {
+        if (i.plan === undefined || !i.plan.executable) continue;
+        if (spent + i.plan.estimated_tokens > remainingTokens) continue;
+        spent += i.plan.estimated_tokens;
+        admitted.push(i);
+    }
+    return admitted;
+}
+
+export function evaluateGate(input: GateInput): GateResult {
+    const none = (reason: GateResult['reason'], stop: StopVerdict | null): GateResult => ({
+        offer: false,
+        reason,
+        settleable: [],
+        stop,
+        estimate: null,
+        band: null,
+    });
+    if (input.roundsCompleted >= MAX_ROUNDS) return none('round-cap', null);
+    const stop = evaluateStop(input.stop);
+    if (stop.stop) return none('exhausted', stop);
+    const settleable = admitWithinBudget(input.items, input.remainingTokens);
+    if (settleable.length === 0) return none('no-plannable-item', stop);
+    const estimate = input.nextCall === undefined ? null : scoreNextCall(input.nextCall);
+    return { offer: true, reason: 'offer', settleable: settleable.map((i) => i.id), stop, estimate, band: bandFor(settleable) };
+}
+
+export type CouncilCall = 'one-more' | 'focused' | 'stop' | 'split';
+
+export type RoundDecision =
+    | { decided_by: 'none' }
+    | { decided_by: 'council'; decision: Exclude<CouncilCall, 'split'> }
+    | {
+          decided_by: 'owner';
+          question: { items: string[]; cost_tokens: number; band: GainBand; options: typeof OWNER_OPTIONS };
+      };
+
+export function decideNextRound(input: {
+    gate: GateResult;
+    council: CouncilCall;
+    roundTokens: number;
+    ceilingTokens: number;
+}): RoundDecision {
+    if (!input.gate.offer || input.gate.band === null) return { decided_by: 'none' };
+    if (input.council === 'split' || input.roundTokens > input.ceilingTokens) {
+        return {
+            decided_by: 'owner',
+            question: { items: input.gate.settleable, cost_tokens: input.roundTokens, band: input.gate.band, options: OWNER_OPTIONS },
+        };
+    }
+    return { decided_by: 'council', decision: input.council };
+}

package/src/scripts/analysis_inbox_final.ts

@@ -0,0 +1,173 @@
+/**
+ * analysis_inbox_final.ts — what makes `analyze:inbox` the final stage of the
+ * analysis doors (step 3.4, ADR-288 D1).
+ *
+ * - `roundUnion`: one round is the runtime round folder plus the owner's drops,
+ *   read as one set; lineage comes from the round's manifest, not from
+ *   filenames; an opaque round id skips the Phase 1 rename.
+ * - `directiveBinding`: which turns bind, by provenance.
+ * - `convergenceRow`: the final Convergence loop names every binding directive
+ *   it checked, or it is refused.
+ * - `planLanes` / `foldLaneLedgers`: a round above the slicing size runs as
+ *   parallel lanes, each with its own census and point ledger, folded once.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { isOpaqueRoundId } from './_lib/source_shape.js';
+import { DROPS_REL } from './analysis_analysts.js';
+import { RUN_STATE_FILE, RUNS_REL } from './analysis_run.js';
+
+/**
+ * ADR-288 D9: the inbox's default batch threshold. Adoption rate fell as round
+ * size rose over five consecutive rounds, and this is where it was cut.
+ */
+export const INBOX_LANE_MAX_BYTES = 400_000;
+export const INBOX_LANE_MAX_TOPICS = 5;
+export const ROUND_MANIFEST = 'manifest.json';
+
+export class InboxFinalError extends Error {}
+
+export interface RoundFile {
+    rel: string;
+    origin: 'runtime' | 'drop';
+}
+
+export interface RoundUnion {
+    files: RoundFile[];
+    lineage: Record<string, string[]>;
+    renameBeforeTriage: boolean;
+}
+
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const BOOKKEEPING = new Set([RUN_STATE_FILE, ROUND_MANIFEST]);
+
+function listFiles(projectRoot: string, rel: string): string[] {
+    const dir = path.join(projectRoot, rel);
+    if (!fs.existsSync(dir)) return [];
+    const out: string[] = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.name.startsWith('.')) continue;
+        const r = `${rel}/${entry.name}`;
+        if (entry.isDirectory()) out.push(...listFiles(projectRoot, r));
+        else if (entry.isFile()) out.push(r);
+    }
+    return out;
+}
+
+export function roundUnion(projectRoot: string, roundId: string): RoundUnion {
+    if (!SEGMENT.test(roundId) || roundId.includes('..')) {
+        throw new InboxFinalError(`round id ${JSON.stringify(roundId)} is not a single folder name`);
+    }
+    const runtimeRel = `${RUNS_REL}/${roundId}`;
+    const runtime = listFiles(projectRoot, runtimeRel)
+        .filter((r) => !BOOKKEEPING.has(r.slice(runtimeRel.length + 1)))
+        .map((rel): RoundFile => ({ rel, origin: 'runtime' }));
+    const drops = listFiles(projectRoot, `${DROPS_REL}/${roundId}`).map((rel): RoundFile => ({ rel, origin: 'drop' }));
+    let lineage: Record<string, string[]> = {};
+    const manifest = path.join(projectRoot, runtimeRel, ROUND_MANIFEST);
+    if (fs.existsSync(manifest)) {
+        let data: { lineage?: unknown };
+        try {
+            data = JSON.parse(fs.readFileSync(manifest, 'utf8')) as { lineage?: unknown };
+        } catch (err) {
+            throw new InboxFinalError(`${ROUND_MANIFEST} is not readable JSON (${err instanceof Error ? err.message : String(err)})`);
+        }
+        const raw = data.lineage ?? {};
+        const isMap = typeof raw === 'object' && raw !== null && !Array.isArray(raw);
+        if (!isMap || !Object.values(raw).every((v) => Array.isArray(v) && v.every((x) => typeof x === 'string'))) {
+            throw new InboxFinalError(`${ROUND_MANIFEST} carries a lineage that is not a map of file lists`);
+        }
+        lineage = raw as Record<string, string[]>;
+    }
+    return { files: [...runtime, ...drops], lineage, renameBeforeTriage: !isOpaqueRoundId(roundId) };
+}
+
+export interface Directive {
+    id: string;
+    role: 'user' | 'assistant';
+    provenance: 'current-session' | 'transcript-structured' | 'transcript-recovered';
+    text: string;
+    /** Another input that contradicts this one, when there is one. */
+    contradictedBy?: string;
+}
+
+/** `binds` constrains the run; `batch` joins the owner's post-action batch (step 2.7); `claim` is verified like any claim. */
+export function directiveBinding(d: Directive): 'binds' | 'batch' | 'claim' {
+    if (d.role !== 'user') return 'claim';
+    if (d.provenance === 'current-session') return 'binds';
+    if (d.provenance === 'transcript-structured') return d.contradictedBy === undefined ? 'binds' : 'batch';
+    return 'batch';
+}
+
+export interface DirectiveCheck {
+    directive: string;
+    roadmap: string;
+    verdict: 'honoured' | 'violated' | 'not-applicable';
+    evidence: string;
+}
+
+export interface ConvergenceRow {
+    lens: 'convergence';
+    directives_checked: string[];
+    violated: string[];
+    checks: DirectiveCheck[];
+}
+
+export function convergenceRow(directives: readonly Directive[], checks: readonly DirectiveCheck[]): ConvergenceRow {
+    const binding = directives.filter((d) => directiveBinding(d) === 'binds').map((d) => d.id);
+    const checked = new Set(checks.filter((c) => c.evidence.trim() !== '').map((c) => c.directive));
+    const missing = binding.filter((id) => !checked.has(id));
+    if (missing.length > 0) throw new InboxFinalError(`final Convergence loop left binding directive(s) unchecked: ${missing.join(', ')}`);
+    const violated = [...new Set(checks.filter((c) => c.verdict === 'violated').map((c) => c.directive))];
+    return { lens: 'convergence', directives_checked: binding, violated, checks: [...checks] };
+}
+
+export interface Lane {
+    lane: string;
+    topics: string[];
+}
+
+/** First-fit by size into lanes under both thresholds; one lane when the round fits. */
+export function planLanes(topics: ReadonlyArray<{ topic: string; bytes: number }>): Lane[] {
+    const lanes: Array<Lane & { bytes: number }> = [];
+    for (const t of [...topics].sort((a, b) => b.bytes - a.bytes || a.topic.localeCompare(b.topic))) {
+        const fit = lanes.find((l) => l.topics.length < INBOX_LANE_MAX_TOPICS && l.bytes + t.bytes <= INBOX_LANE_MAX_BYTES);
+        if (fit !== undefined) {
+            fit.topics.push(t.topic);
+            fit.bytes += t.bytes;
+        } else {
+            lanes.push({ lane: '', topics: [t.topic], bytes: t.bytes });
+        }
+    }
+    return lanes.map((l, i) => ({ lane: `L${i + 1}`, topics: l.topics }));
+}
+
+export interface LaneLedger {
+    lane: string;
+    /** The lane's own anchor census — the denominator its reading cannot shrink. */
+    census: number;
+    points: Array<{ id: string; disposition: string }>;
+}
+
+export function foldLaneLedgers(lanes: readonly LaneLedger[]): { lanes: number; census: number; points: number } {
+    const laneIds = new Set<string>();
+    const pointLane = new Map<string, string>();
+    for (const l of lanes) {
+        if (!(l.census > 0) || !Array.isArray(l.points)) {
+            throw new InboxFinalError(`lane ${l.lane} has no census or no point ledger of its own; a fold without one loses that lane`);
+        }
+        if (laneIds.has(l.lane)) throw new InboxFinalError(`lane ${l.lane} appears twice; its census would be counted twice`);
+        laneIds.add(l.lane);
+        for (const p of l.points) {
+            const other = pointLane.get(p.id);
+            if (other !== undefined) throw new InboxFinalError(`point ${p.id} sits in lanes ${other} and ${l.lane}; a topic belongs to one lane`);
+            pointLane.set(p.id, l.lane);
+        }
+    }
+    return {
+        lanes: lanes.length,
+        census: lanes.reduce((n, l) => n + l.census, 0),
+        points: lanes.reduce((n, l) => n + l.points.length, 0),
+    };
+}