@aragon-agent/cli 0.6.44 → 0.6.46

package/dist/governance/rules/ledger.js

@@ -0,0 +1,560 @@
+/**
+ * The Ledger - the ONE accounting path (governance-mode 5.3 / 5.8 / 5.10, I-G7).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * Engine-booked events (settlement, RCA expansion, claim rulings) and inspector-booked
+ * events (`ledger_apply`) all arrive here as a `LedgerEvent`, are looked up in the same
+ * catalogue and are held to the same per-event and per-incident limits. There is no second
+ * way to change a balance, which is what makes the audit trail believable.
+ *
+ * EVERY FUNCTION IS PURE AND DETERMINISTIC (I-G2). A function takes a `LedgerState` and
+ * returns a NEW one; it never mutates its input, never reads a clock and never draws a
+ * random number - `at` travels inside the event. Replaying the stored event list therefore
+ * reproduces the checkpoint byte-for-byte. `governance-ledger.test.ts` proves it with a
+ * seeded random-sequence property test run on deep-frozen states.
+ *
+ * KILL READS `confirmed` ONLY (I-G3). A clawback shrinks `provisional`, so a primary DEV
+ * can lose most of their TOTAL without being eliminated; only a depleted `confirmed`
+ * pool, or the tail rule, removes an agent.
+ *
+ * Related modules: `ledger-state.ts` (construction + queries), `failure-analysis.ts`
+ * (successor brief), `ledger-replay.ts` (op log), `elimination.ts` (tail rule).
+ */
+import { GOV_LIMITS } from '../limits.js';
+import { EVENTS_TABLE, } from './events-table.js';
+import { buildFailureAnalysis } from './failure-analysis.js';
+import { INSPECTOR_ID, activeAgents, appendHistory, escrowBalance, escrowPhases, incidentKey, makeEntry, makeEscrowEntry, stampSeq, } from './ledger-state.js';
+export * from './ledger-state.js';
+/** C2 for an agent that is not the primary cause of the failed integration (5.7). */
+export const C2_RELIEF_DELTA = -2;
+// ---------------------------------------------------------------------------
+// Settlement routing
+// ---------------------------------------------------------------------------
+/**
+ * Which pool a booking lands in. EXHAUSTIVE over the three settlements, with a throwing
+ * default: a silent fallthrough into "some pool" would corrupt balances with no trace.
+ *
+ *  - provisional + positive -> escrow (clawback-able).
+ *  - confirmed / immediate + positive -> `confirmed` (RV-9: an "immediate" reward is
+ *    credited at once; the only difference from escrow is that it cannot be clawed back).
+ *  - any negative -> deducted from `confirmed`, whatever the label says.
+ *
+ * The switch runs BEFORE the sign test so an invalid label fails even on a zero delta.
+ */
+export function settlementPool(settlement, delta) {
+    let credit;
+    switch (settlement) {
+        case 'provisional':
+            credit = 'provisional';
+            break;
+        case 'confirmed':
+        case 'immediate':
+            credit = 'confirmed';
+            break;
+        default: {
+            const unreachable = settlement;
+            throw new Error(`Unknown settlement "${String(unreachable)}": cannot route a booking.`);
+        }
+    }
+    return delta < 0 ? 'deduct' : credit;
+}
+/** Order in which one incident's events are applied so a cap truncates the right one. */
+export function incidentPriority(code) {
+    switch (code) {
+        case 'D13':
+        case 'R9':
+        case 'T4':
+        case 'T10':
+            return 0;
+        case 'D14':
+            return 1;
+        case 'D15':
+            return 2;
+        case 'C2':
+        case 'C3':
+        case 'C4':
+            return 3;
+        default:
+            return 4;
+    }
+}
+// ---------------------------------------------------------------------------
+// apply
+// ---------------------------------------------------------------------------
+function reject(code, message) {
+    return { code, message };
+}
+function lookupDef(event, options) {
+    const table = options.catalogue ?? EVENTS_TABLE;
+    return Object.prototype.hasOwnProperty.call(table, event.code) ? table[event.code] : undefined;
+}
+/** Refusals that depend on the event and roster only; never throws. */
+function screenEvent(state, event, def) {
+    if (event.agentId === INSPECTOR_ID) {
+        return reject('INSPECTOR_NOT_SCORED', 'The inspector is not in the ledger (I-G5).');
+    }
+    if (def === undefined)
+        return reject('UNKNOWN_CODE', `Unknown event code "${event.code}".`);
+    const agent = state.agents[event.agentId];
+    if (agent === undefined)
+        return reject('UNKNOWN_AGENT', `No agent "${event.agentId}".`);
+    if (agent.status !== 'active') {
+        return reject('AGENT_ELIMINATED', `Agent "${agent.id}" has been eliminated.`);
+    }
+    if (def.role !== 'ALL' && def.role !== agent.role) {
+        return reject('ROLE_MISMATCH', `${def.code} applies to ${def.role}, not ${agent.role}.`);
+    }
+    if (event.relief === true && def.code !== 'C2') {
+        return reject('RELIEF_NOT_ALLOWED', 'Only C2 has a relieved (-2) variant.');
+    }
+    return undefined;
+}
+function clampPerEvent(delta) {
+    return Math.min(GOV_LIMITS.maxSingleReward, Math.max(GOV_LIMITS.maxSingleDeduction, delta));
+}
+/** Trim a deduction so the (agent, incident) running total never passes -50 (I-G4). */
+function capByIncident(state, target, delta) {
+    if (delta >= 0 || target.incidentId === undefined)
+        return delta;
+    const used = state.incidentNegatives[incidentKey(target.agentId, target.incidentId)] ?? 0;
+    return Math.max(delta, GOV_LIMITS.maxIncidentNegative - used);
+}
+/** Move `delta` into its pool; the floor keeps `confirmed` from going below zero. */
+function bookDelta(agent, pool, delta) {
+    switch (pool) {
+        case 'provisional':
+            return { confirmed: agent.confirmed, provisional: agent.provisional + delta, applied: delta };
+        case 'confirmed':
+            return { confirmed: agent.confirmed + delta, provisional: agent.provisional, applied: delta };
+        case 'deduct': {
+            const confirmed = Math.max(0, agent.confirmed + delta);
+            return { confirmed, provisional: agent.provisional, applied: confirmed - agent.confirmed };
+        }
+    }
+}
+/** Unary minus that never yields -0 (Object.is distinguishes it; JSON hides it). */
+function negate(value) {
+    return value === 0 ? 0 : -value;
+}
+function putAgent(state, agent, seq) {
+    return {
+        ...state,
+        seq: Math.max(state.seq, seq),
+        agents: { ...state.agents, [agent.id]: agent },
+    };
+}
+function rejectedOutcome(state, rejection) {
+    return { state, booked: false, rejected: rejection, clipped: 0, eliminated: false };
+}
+function buildEventEntry(event, def, seq, booking, requested) {
+    const capped = booking.applied === requested ? undefined : { requested, applied: booking.applied };
+    return makeEntry({
+        seq,
+        at: event.at,
+        code: def.code,
+        delta: booking.applied,
+        settlement: def.settlement,
+        phase: event.phase,
+        by: event.by,
+        reason: event.reason,
+        wpId: event.wpId,
+        incidentId: event.incidentId,
+        evidence: event.evidence,
+        capped,
+        confirmedAfter: booking.confirmed,
+        provisionalAfter: booking.provisional,
+    });
+}
+function recordIncidentNegative(state, target, applied) {
+    if (applied >= 0 || target.incidentId === undefined)
+        return state.incidentNegatives;
+    const key = incidentKey(target.agentId, target.incidentId);
+    return { ...state.incidentNegatives, [key]: (state.incidentNegatives[key] ?? 0) + applied };
+}
+/**
+ * Book one event.
+ *
+ * Order of operations (each step can only SHRINK the magnitude): catalogue delta ->
+ * per-event limit (+20 / -40) -> incident cap (-50 cumulative) -> floor at 0. The entry
+ * records `capped: { requested, applied }` whenever any step trimmed the amount, so the
+ * inspector can say why a figure is smaller than the catalogue's.
+ */
+export function apply(state, event, options = {}) {
+    const def = lookupDef(event, options);
+    const rejection = screenEvent(state, event, def);
+    if (rejection !== undefined)
+        return rejectedOutcome(state, rejection);
+    const eventDef = def;
+    const agent = state.agents[event.agentId];
+    const requested = event.relief === true ? C2_RELIEF_DELTA : eventDef.delta;
+    const wanted = capByIncident(state, event, clampPerEvent(requested));
+    const pool = settlementPool(eventDef.settlement, wanted);
+    const booking = bookDelta(agent, pool, wanted);
+    const seq = stampSeq(state, event.seq);
+    const entry = buildEventEntry(event, eventDef, seq, booking, requested);
+    const escrow = pool === 'provisional' && booking.applied > 0
+        ? [
+            ...agent.escrowHistory,
+            makeEscrowEntry({
+                seq,
+                at: event.at,
+                phase: event.phase,
+                action: 'held',
+                amount: booking.applied,
+                code: eventDef.code,
+                reason: event.reason,
+            }),
+        ]
+        : agent.escrowHistory;
+    const updated = {
+        ...agent,
+        confirmed: booking.confirmed,
+        provisional: booking.provisional,
+        history: appendHistory(agent.history, entry),
+        escrowHistory: escrow,
+    };
+    let next = putAgent(state, updated, seq);
+    next = { ...next, incidentNegatives: recordIncidentNegative(state, event, booking.applied) };
+    const depleted = updated.confirmed <= 0;
+    if (depleted)
+        next = eliminateInState(next, event.agentId, 'depleted', event.at, seq);
+    return {
+        state: next,
+        booked: true,
+        entry,
+        clipped: Math.abs(requested - booking.applied),
+        eliminated: depleted,
+    };
+}
+/** Apply a list in order; a rejected event is skipped (its outcome says why). */
+export function applyAll(state, events, options = {}) {
+    const outcomes = [];
+    let current = state;
+    for (const event of events) {
+        const outcome = apply(current, event, options);
+        outcomes.push(outcome);
+        current = outcome.state;
+    }
+    return { state: current, outcomes };
+}
+/**
+ * Expand a collective event into one `LedgerEvent` per ACTIVE scored agent, in roster
+ * order. The inspector is never present because it is never in `state.agents`.
+ */
+export function expandCollective(state, spec) {
+    const only = spec.participants === undefined ? undefined : new Set(spec.participants);
+    const relief = new Set(spec.reliefIds ?? []);
+    return activeAgents(state)
+        .filter((a) => only === undefined || only.has(a.id))
+        .map((a) => {
+        const event = {
+            code: spec.code,
+            agentId: a.id,
+            at: spec.at,
+            phase: spec.phase,
+            by: spec.by,
+            reason: spec.reason,
+        };
+        if (spec.wpId !== undefined)
+            event.wpId = spec.wpId;
+        if (spec.incidentId !== undefined)
+            event.incidentId = spec.incidentId;
+        if (spec.seq !== undefined)
+            event.seq = spec.seq;
+        if (spec.code === 'C2' && relief.has(a.id))
+            event.relief = true;
+        return event;
+    });
+}
+export function applyCollective(state, spec) {
+    return applyAll(state, expandCollective(state, spec));
+}
+/**
+ * Integration passed: move every active agent's remaining escrow for `phase` into
+ * `confirmed`. Whatever a clawback already took is gone, so only the unreclaimed balance
+ * is released. An eliminated agent's escrow was forfeited when it was removed.
+ */
+export function confirmEscrow(state, phase, at, seqOverride) {
+    const seq = stampSeq(state, seqOverride);
+    const released = [];
+    let next = state;
+    for (const agent of activeAgents(state)) {
+        const amount = escrowBalance(agent, phase);
+        if (amount <= 0)
+            continue;
+        const confirmed = agent.confirmed + amount;
+        const provisional = agent.provisional - amount;
+        const reason = `Escrow for phase ${phase + 1} released after integration`;
+        const entry = makeEntry({
+            seq,
+            at,
+            code: 'ESCROW_RELEASE',
+            delta: amount,
+            settlement: 'escrow_release',
+            phase,
+            by: 'engine',
+            reason,
+            confirmedAfter: confirmed,
+            provisionalAfter: provisional,
+        });
+        const record = {
+            ...agent,
+            confirmed,
+            provisional,
+            history: appendHistory(agent.history, entry),
+            escrowHistory: [
+                ...agent.escrowHistory,
+                makeEscrowEntry({ seq, at, phase, action: 'released', amount, reason }),
+            ],
+        };
+        next = putAgent(next, record, seq);
+        released.push({ agentId: agent.id, amount });
+    }
+    return { state: next, released };
+}
+/**
+ * Integration failed: reclaim the culprit's escrow for `phase`. The amount counts against
+ * the same (agent, incident) -50 cap as the deductions and is applied LAST, so the cap
+ * truncates the clawback rather than the D13/D14/D15 the inspector asked for.
+ * Only `provisional` shrinks: `confirmed` (and so KILL) is untouched (I-G3).
+ */
+export function clawback(state, request) {
+    const agent = state.agents[request.agentId];
+    const none = { state, clawed: 0, requested: 0, capped: false };
+    if (agent === undefined || agent.status !== 'active')
+        return none;
+    const balance = escrowBalance(agent, request.phase);
+    if (balance <= 0)
+        return none;
+    const target = { agentId: agent.id, incidentId: request.incidentId };
+    // abs, not unary minus: a fully capped clawback must be +0, never the JSON-invisible -0.
+    const clawed = Math.abs(capByIncident(state, target, -balance));
+    const seq = stampSeq(state, request.seq);
+    const provisional = agent.provisional - clawed;
+    const entry = makeEntry({
+        seq,
+        at: request.at,
+        code: 'CLAWBACK',
+        delta: negate(clawed),
+        settlement: 'clawback',
+        phase: request.phase,
+        by: request.by ?? 'engine',
+        reason: request.reason,
+        incidentId: request.incidentId,
+        capped: clawed === balance ? undefined : { requested: -balance, applied: negate(clawed) },
+        confirmedAfter: agent.confirmed,
+        provisionalAfter: provisional,
+    });
+    const record = {
+        ...agent,
+        provisional,
+        history: appendHistory(agent.history, entry),
+        escrowHistory: clawed > 0
+            ? [
+                ...agent.escrowHistory,
+                makeEscrowEntry({
+                    seq,
+                    at: request.at,
+                    phase: request.phase,
+                    action: 'clawed_back',
+                    amount: clawed,
+                    reason: request.reason,
+                }),
+            ]
+            : agent.escrowHistory,
+    };
+    let next = putAgent(state, record, seq);
+    next = { ...next, incidentNegatives: recordIncidentNegative(state, target, negate(clawed)) };
+    return { state: next, clawed, requested: balance, capped: clawed !== balance };
+}
+/**
+ * Apply one incident in the priority order D13 -> D14/D15 -> C2/C3/C4 -> clawback
+ * (5.3), so a cap that bites trims the LAST thing in that chain. Stable within a rank.
+ */
+export function applyIncident(state, input) {
+    const ordered = input.events
+        .map((event, index) => ({ event, index, rank: incidentPriority(event.code) }))
+        .sort((a, b) => a.rank - b.rank || a.index - b.index)
+        .map((item) => item.event);
+    const { state: afterEvents, outcomes } = applyAll(state, ordered);
+    let current = afterEvents;
+    const clawbacks = [];
+    for (const request of input.clawbacks ?? []) {
+        const outcome = clawback(current, request);
+        clawbacks.push(outcome);
+        current = outcome.state;
+    }
+    return { state: current, outcomes, clawbacks };
+}
+function reversalMarker(original) {
+    return `reverses:${original.seq}:${original.code}`;
+}
+/** The newest un-reversed negative entry of `code` (for `wpId` when given). */
+function findReversible(agent, request) {
+    const done = new Set(agent.history.filter((e) => e.evidence?.startsWith('reverses:')).map((e) => e.evidence));
+    for (let i = agent.history.length - 1; i >= 0; i--) {
+        const e = agent.history[i];
+        if (e.code !== request.code || e.delta >= 0 || done.has(reversalMarker(e)))
+            continue;
+        if (request.wpId !== undefined && e.wpId !== request.wpId)
+            continue;
+        return e;
+    }
+    return undefined;
+}
+/**
+ * Credit back the newest un-reversed deduction of `code`: the AC-24 "withdraw undoes the
+ * D5". It re-credits exactly what was DEDUCTED (a capped D5 is refunded at its capped
+ * amount) and is itself a ledger row, so the audit trail shows both halves. Does nothing
+ * when the original has been folded out of the bounded history.
+ */
+export function reverseEntry(state, request) {
+    const agent = state.agents[request.agentId];
+    if (agent === undefined || agent.status !== 'active')
+        return { state, reversed: false };
+    const original = findReversible(agent, request);
+    if (original === undefined)
+        return { state, reversed: false };
+    const amount = -original.delta;
+    const seq = stampSeq(state, request.seq);
+    const confirmed = agent.confirmed + amount;
+    const entry = makeEntry({
+        seq,
+        at: request.at,
+        code: original.code,
+        delta: amount,
+        settlement: 'immediate',
+        phase: original.phase,
+        by: 'engine',
+        reason: `Reversal of #${original.seq} ${original.code}: ${request.reason}`,
+        wpId: original.wpId,
+        incidentId: original.incidentId,
+        evidence: reversalMarker(original),
+        confirmedAfter: confirmed,
+        provisionalAfter: agent.provisional,
+    });
+    const record = {
+        ...agent,
+        confirmed,
+        history: appendHistory(agent.history, entry),
+    };
+    let next = putAgent(state, record, seq);
+    if (original.incidentId !== undefined) {
+        const key = incidentKey(agent.id, original.incidentId);
+        const used = state.incidentNegatives[key] ?? 0;
+        next = { ...next, incidentNegatives: { ...next.incidentNegatives, [key]: used + amount } };
+    }
+    return { state: next, reversed: true, entry };
+}
+// ---------------------------------------------------------------------------
+// Elimination and respawn
+// ---------------------------------------------------------------------------
+/** Forfeit any remaining escrow: an eliminated agent can never be paid it out. */
+function forfeitEscrow(agent, at, seq) {
+    const phases = escrowPhases(agent);
+    if (phases.length === 0)
+        return agent;
+    const reason = 'Escrow forfeited on elimination';
+    const escrow = [...agent.escrowHistory];
+    let total = 0;
+    for (const phase of phases) {
+        const amount = escrowBalance(agent, phase);
+        total += amount;
+        escrow.push(makeEscrowEntry({ seq, at, phase, action: 'clawed_back', amount, reason }));
+    }
+    const entry = makeEntry({
+        seq,
+        at,
+        code: 'CLAWBACK',
+        delta: -total,
+        settlement: 'clawback',
+        phase: phases[phases.length - 1],
+        by: 'engine',
+        reason,
+        confirmedAfter: agent.confirmed,
+        provisionalAfter: agent.provisional - total,
+    });
+    return {
+        ...agent,
+        provisional: agent.provisional - total,
+        history: appendHistory(agent.history, entry),
+        escrowHistory: escrow,
+    };
+}
+function eliminateInState(state, agentId, reason, at, seq) {
+    const agent = state.agents[agentId];
+    const analysis = buildFailureAnalysis(agent, reason);
+    const forfeited = forfeitEscrow(agent, at, seq);
+    const record = { ...forfeited, status: 'eliminated', eliminatedReason: reason };
+    const next = putAgent(state, record, seq);
+    return { ...next, failureAnalyses: { ...next.failureAnalyses, [agentId]: analysis } };
+}
+/**
+ * Remove an active agent (tail rule or an explicit clawback decision). KILL by depletion
+ * happens inside `apply`; this is the entry point for the other two reasons. A no-op for
+ * an unknown or already-eliminated id, so replaying it twice is harmless.
+ */
+export function eliminate(state, request) {
+    const agent = state.agents[request.agentId];
+    if (agent === undefined || agent.status !== 'active') {
+        return { state, eliminated: false, analysis: null };
+    }
+    const seq = stampSeq(state, request.seq);
+    const next = eliminateInState(state, request.agentId, request.reason, request.at, seq);
+    return {
+        state: next,
+        eliminated: true,
+        analysis: next.failureAnalyses[request.agentId],
+    };
+}
+/** `dev2` -> `dev2-r1` -> `dev2-r2`: the suffix tracks the generation. */
+export function successorId(predecessor) {
+    return `${predecessor.id.replace(/-r\d+$/, '')}-r${predecessor.generation + 1}`;
+}
+/**
+ * Replace an eliminated agent with a fresh identity at `GOV_LIMITS.respawnTokens`
+ * (all confirmed, no escrow). The successor inherits NO code - only the predecessor's
+ * `FailureAnalysis`, returned for the brief. Subagent labels are capped at 12 characters,
+ * so an over-long id is a bug in the roster naming and throws.
+ */
+export function respawn(state, request) {
+    const old = state.agents[request.agentId];
+    const none = { state, successor: null, analysis: null };
+    if (old === undefined || old.status !== 'eliminated' || old.replacedBy !== null)
+        return none;
+    const id = successorId(old);
+    if (id.length > 12)
+        throw new Error(`Respawn id "${id}" exceeds 12 characters.`);
+    if (state.agents[id] !== undefined)
+        return none;
+    const seq = stampSeq(state, request.seq);
+    const entry = makeEntry({
+        seq,
+        at: request.at,
+        code: 'RESPAWN',
+        delta: GOV_LIMITS.respawnTokens,
+        settlement: 'confirmed',
+        phase: request.phase,
+        by: 'engine',
+        reason: `Respawned as the successor of ${old.id}`,
+        confirmedAfter: GOV_LIMITS.respawnTokens,
+        provisionalAfter: 0,
+    });
+    const successor = {
+        id,
+        role: old.role,
+        generation: old.generation + 1,
+        confirmed: GOV_LIMITS.respawnTokens,
+        provisional: 0,
+        status: 'active',
+        replacedBy: null,
+        tailStrikes: 0,
+        history: [entry],
+        escrowHistory: [],
+    };
+    const retired = { ...old, replacedBy: id };
+    const next = putAgent(putAgent(state, retired, seq), successor, seq);
+    const analysis = state.failureAnalyses[old.id] ?? buildFailureAnalysis(old, old.eliminatedReason ?? 'depleted');
+    return { state: next, successor, analysis };
+}

package/dist/governance/rules/rca.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Root-cause attribution -> ledger events (governance-mode 5.7).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * The inspector reports WHO and HOW (a structured `RcaInput`); the engine owns the
+ * ARITHMETIC. That split is the point: the model supplies judgement it can justify from
+ * the code, and cannot mistype a figure, forget the C2 relief or double-count a cap.
+ * `expandRca` is pure - it returns events plus clawback requests in priority order, and
+ * the caller books them through `applyIncident` so the single-incident -50 cap truncates
+ * the right row (D13 -> D14/D15 -> C2/C3/C4 -> clawback).
+ */
+import type { LedgerEntry, LedgerState, RcaInput } from '../types.js';
+import type { ClawbackRequest, IncidentOutcome, LedgerEvent } from './ledger.js';
+type Attribution = RcaInput['attributions'][number];
+type Level = Attribution['level'];
+/** Recorded in the report; contributing agents carry weight but no event of their own. */
+export declare const RCA_WEIGHTS: Readonly<Record<Level, number>>;
+export interface RcaContext {
+    state: LedgerState;
+    phase: number;
+    at: number;
+    /** Shared by every event of the incident: the cap is per (agent, incident). */
+    incidentId: string;
+    /** Fix cycles consumed in this phase; >= 3 adds C3 for everyone. */
+    fixCycles: number;
+    by: LedgerEntry['by'];
+    /** The phase's members; absent => every active scored agent. */
+    participants?: readonly string[];
+    wpId?: string;
+}
+export interface RcaWeight {
+    agentId: string;
+    level: Level;
+    weight: number;
+}
+export interface RcaExpansion {
+    /** True when `boundary` is false: an individual bug, so no integration events at all. */
+    individualDefect: boolean;
+    /** In application order. Book with `applyIncident` together with `clawbacks`. */
+    events: LedgerEvent[];
+    clawbacks: ClawbackRequest[];
+    weights: RcaWeight[];
+    /** Attributions that could not be applied, each with the reason. */
+    skipped: string[];
+    /** Human-readable plan, one line per decision. ASCII. */
+    breakdown: string[];
+}
+/**
+ * Expand a structured RCA into ledger events (5.7 step 3):
+ *
+ *  - primary DEV -> D13 -25, plus D14 -20 (producer) and/or D15 -10 (consumer_unverified);
+ *  - oversight -> R9 -20 (review_integration), T4 -15 (test_defect), T10 -15
+ *    (test_boundary); a missing `miss` defaults by role (REV R9, TEST T10);
+ *  - contributing -> reported with weight 0.3, no event of its own;
+ *  - everyone active -> C2 -5 (-2 for non-primary) or, when systemic, C4 -15 instead;
+ *  - fix cycles >= 3 -> C3 -10 for everyone;
+ *  - every primary has the phase's escrow clawed back.
+ *
+ * `boundary = false` is an individual bug: nothing is booked.
+ */
+export declare function expandRca(rca: RcaInput, ctx: RcaContext): RcaExpansion;
+/**
+ * Report lines AFTER booking: what the cap actually did. The inspector must state any
+ * `capped` row in the settle summary (AC-17), so the engine hands it ready-made text.
+ */
+export declare function summarizeIncident(outcome: IncidentOutcome): string[];
+export {};