@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/governance/rules/events-table.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The event catalogue - Appendix A of the design, 44 rows (governance-mode AC-15).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THIS TABLE IS THE GOLDEN SOURCE. `governance-ledger.test.ts` pins every row against
+ * the reference spec (`token-economy-rules.md` v2.0); a change here is a scoring-rule
+ * change, so it must be mirrored in the design document and the golden test in the same
+ * commit. Nothing else in the tree may hard-code a delta: settlement, RCA expansion and
+ * the inspector tool all look values up here, which is what keeps the engine's
+ * automatic events and the inspector's judgement events on ONE accounting path (I-G7).
+ *
+ * Settlement semantics (design 5.3 / RV-9):
+ *   provisional (P) - positive; held in escrow until integration passes; clawback-able.
+ *   confirmed   (C) - positive; straight into `confirmed`; not clawback-able.
+ *   immediate   (I) - positive scores go straight into `confirmed` (same as C, but the
+ *                     reference spec calls the column "Immediate"); negative scores are
+ *                     deducted from `confirmed` at once.
+ */
+export type EventRole = 'DEV' | 'REV' | 'TEST' | 'ALL';
+export type Settlement = 'provisional' | 'confirmed' | 'immediate';
+/**
+ * Who may book an event: E engine, A engine on a mechanical signature (appealable),
+ * K a claim ruled on by the inspector, S inspector judgement (evidence required),
+ * R inspector root-cause analysis expanded by the engine.
+ */
+export type Bookkeeper = 'E' | 'A' | 'K' | 'S' | 'R';
+export declare const EVENT_CODES: readonly ["D1", "D2", "D3", "D4", "D5", "D6", "D7", "D8", "D9", "D10", "D11", "D12", "D13", "D14", "D15", "D16", "D17", "D18", "R1", "R2", "R3", "R4", "R5", "R6", "R7", "R8", "R9", "R10", "R11", "R12", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T8", "T9", "T10", "C1", "C2", "C3", "C4"];
+export type EventCode = (typeof EVENT_CODES)[number];
+export interface EventDef {
+    code: EventCode;
+    role: EventRole;
+    /** The catalogue delta. C2 is -5 for everyone; the -2 relief is applied by RCA. */
+    delta: number;
+    settlement: Settlement;
+    bookers: readonly Bookkeeper[];
+    /** Short English title, ASCII. Used in ledger rows and the board. */
+    title: string;
+}
+export declare const EVENTS_TABLE: Readonly<Record<EventCode, EventDef>>;
+export declare function isEventCode(value: unknown): value is EventCode;
+export declare function eventDef(code: EventCode): EventDef;
+/** True when the inspector may book this code through `ledger_apply` (judgement events). */
+export declare function isInspectorBookable(code: EventCode): boolean;
+/** The codes `ledger_apply` accepts, in catalogue order. Used in refusal texts. */
+export declare function inspectorBookableCodes(): EventCode[];

package/dist/governance/rules/events-table.js

@@ -0,0 +1,94 @@
+/**
+ * The event catalogue - Appendix A of the design, 44 rows (governance-mode AC-15).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THIS TABLE IS THE GOLDEN SOURCE. `governance-ledger.test.ts` pins every row against
+ * the reference spec (`token-economy-rules.md` v2.0); a change here is a scoring-rule
+ * change, so it must be mirrored in the design document and the golden test in the same
+ * commit. Nothing else in the tree may hard-code a delta: settlement, RCA expansion and
+ * the inspector tool all look values up here, which is what keeps the engine's
+ * automatic events and the inspector's judgement events on ONE accounting path (I-G7).
+ *
+ * Settlement semantics (design 5.3 / RV-9):
+ *   provisional (P) - positive; held in escrow until integration passes; clawback-able.
+ *   confirmed   (C) - positive; straight into `confirmed`; not clawback-able.
+ *   immediate   (I) - positive scores go straight into `confirmed` (same as C, but the
+ *                     reference spec calls the column "Immediate"); negative scores are
+ *                     deducted from `confirmed` at once.
+ */
+export const EVENT_CODES = [
+    'D1', 'D2', 'D3', 'D4', 'D5', 'D6', 'D7', 'D8', 'D9', 'D10', 'D11', 'D12', 'D13', 'D14',
+    'D15', 'D16', 'D17', 'D18',
+    'R1', 'R2', 'R3', 'R4', 'R5', 'R6', 'R7', 'R8', 'R9', 'R10', 'R11', 'R12',
+    'T1', 'T2', 'T3', 'T4', 'T5', 'T6', 'T7', 'T8', 'T9', 'T10',
+    'C1', 'C2', 'C3', 'C4',
+];
+function def(code, role, delta, settlement, bookers, title) {
+    return { code, role, delta, settlement, bookers, title };
+}
+const ROWS = [
+    // --- Development D1-D18 ---
+    def('D1', 'DEV', 15, 'provisional', ['E'], 'review passed with no changes'),
+    def('D2', 'DEV', 5, 'provisional', ['E'], 'review passed with minor fixes'),
+    def('D3', 'DEV', 10, 'provisional', ['E'], 'all tests passed'),
+    def('D4', 'DEV', 5, 'provisional', ['E'], 'fully matches the specification'),
+    def('D5', 'DEV', -20, 'immediate', ['E'], 'code sent back for rework'),
+    def('D6', 'DEV', -40, 'immediate', ['S'], 'introduced a security vulnerability'),
+    def('D7', 'DEV', -25, 'immediate', ['E'], 'specification mismatch'),
+    def('D8', 'DEV', -30, 'immediate', ['E'], 'same problem rejected twice'),
+    def('D9', 'DEV', -20, 'immediate', ['E'], 'incomplete implementation'),
+    def('D10', 'DEV', 20, 'provisional', ['S'], 'proactive excellence'),
+    def('D11', 'DEV', -30, 'immediate', ['E'], 'skeleton submission'),
+    def('D12', 'DEV', 10, 'confirmed', ['E'], 'integration passed (own code clean)'),
+    def('D13', 'DEV', -25, 'immediate', ['R'], 'integration failure (root cause)'),
+    def('D14', 'DEV', -20, 'immediate', ['R', 'S'], 'contract violation (producer)'),
+    def('D15', 'DEV', -10, 'immediate', ['R', 'S'], 'contract violation (consumer unverified)'),
+    def('D16', 'DEV', 10, 'confirmed', ['S'], 'proactive contract verification'),
+    def('D17', 'DEV', -15, 'immediate', ['A', 'S'], 'scope narrowing'),
+    def('D18', 'DEV', 10, 'confirmed', ['S'], 'integration repair contribution'),
+    // --- Review R1-R12 ---
+    def('R1', 'REV', 10, 'provisional', ['E'], 'high quality review (no missed defects)'),
+    def('R2', 'REV', 10, 'immediate', ['E'], 'found a valid problem'),
+    def('R3', 'REV', 5, 'immediate', ['S'], 'efficient review'),
+    def('R4', 'REV', -15, 'immediate', ['K'], 'missed defect found by testing'),
+    def('R5', 'REV', -10, 'immediate', ['K', 'E'], 'false positive feedback'),
+    def('R6', 'REV', -5, 'immediate', ['S'], 'vague or unactionable feedback'),
+    def('R7', 'REV', -15, 'immediate', ['K'], 'did not flag an incomplete implementation'),
+    def('R8', 'REV', 5, 'immediate', ['S'], 'identified proactive excellence'),
+    def('R9', 'REV', -20, 'immediate', ['R'], 'missed integration compatibility'),
+    def('R10', 'REV', 10, 'confirmed', ['S'], 'performed contract verification'),
+    def('R11', 'REV', 5, 'confirmed', ['S'], 'cross-agent impact analysis'),
+    def('R12', 'REV', -10, 'immediate', ['A', 'S'], 'rubber-stamp integration check'),
+    // --- Testing T1-T10 ---
+    def('T1', 'TEST', 10, 'provisional', ['E'], 'full requirement traceability'),
+    def('T2', 'TEST', 10, 'immediate', ['K'], 'found a defect the review missed'),
+    def('T3', 'TEST', 5, 'immediate', ['S'], 'high quality test cases'),
+    def('T4', 'TEST', -15, 'immediate', ['R'], 'missed a defect found at integration'),
+    def('T5', 'TEST', -10, 'immediate', ['K', 'S'], 'false positive defect or claim'),
+    def('T6', 'TEST', -10, 'immediate', ['E'], 'incomplete requirement traceability'),
+    def('T7', 'TEST', 10, 'immediate', ['K'], 'found an incomplete implementation the review missed'),
+    def('T8', 'TEST', 10, 'confirmed', ['S'], 'wrote integration boundary tests'),
+    def('T9', 'TEST', 15, 'confirmed', ['S'], 'found an integration problem before integration'),
+    def('T10', 'TEST', -15, 'immediate', ['R'], 'did not test the integration boundary'),
+    // --- Collective C1-C4 (per active DEV/REV/TEST) ---
+    def('C1', 'ALL', 5, 'confirmed', ['E'], 'integration passed first time'),
+    def('C2', 'ALL', -5, 'immediate', ['E', 'R'], 'integration failed (first)'),
+    def('C3', 'ALL', -10, 'immediate', ['E'], 'repeated integration failure'),
+    def('C4', 'ALL', -15, 'immediate', ['R'], 'integration disaster (systemic)'),
+];
+export const EVENTS_TABLE = Object.freeze(Object.fromEntries(ROWS.map((r) => [r.code, r])));
+export function isEventCode(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(EVENTS_TABLE, value);
+}
+export function eventDef(code) {
+    return EVENTS_TABLE[code];
+}
+/** True when the inspector may book this code through `ledger_apply` (judgement events). */
+export function isInspectorBookable(code) {
+    return EVENTS_TABLE[code].bookers.includes('S');
+}
+/** The codes `ledger_apply` accepts, in catalogue order. Used in refusal texts. */
+export function inspectorBookableCodes() {
+    return EVENT_CODES.filter(isInspectorBookable);
+}

package/dist/governance/rules/failure-analysis.d.ts

@@ -0,0 +1,28 @@
+/**
+ * FailureAnalysis - what a terminated agent's successor is told (governance-mode 5.8).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * DETERMINISTIC ON PURPOSE. The analysis is built from the agent's own ledger history and
+ * a fixed code -> advice table; no model is involved. That keeps a respawn reproducible
+ * from the event log alone (I-G2) and means the successor's brief cannot be steered by a
+ * hallucinated post-mortem.
+ *
+ * Lives in its own module (not `elimination.ts`) so `ledger.ts` can build the analysis at
+ * the moment of elimination without a circular import: `elimination.ts` imports the
+ * ledger, the ledger imports this file.
+ */
+import type { AgentRecord, FailureAnalysis } from '../types.js';
+import { type EventCode } from './events-table.js';
+/** How many penalty events a successor is shown. */
+export declare const FAILURE_ANALYSIS_TOP_PENALTIES = 5;
+/**
+ * One English, ASCII advice line per NEGATIVE catalogue code. Keyed by code (not by
+ * array) so a missing entry is a compile error for the codes listed here and a test
+ * failure for any negative code added to the catalogue later.
+ */
+export declare const AVOID_ADVICE: Readonly<Record<string, string>>;
+/** Build the analysis handed to the successor of `agent`. Pure and deterministic. */
+export declare function buildFailureAnalysis(agent: AgentRecord, reason: FailureAnalysis['reason']): FailureAnalysis;
+/** Negative catalogue codes; the advice table must cover exactly these. */
+export declare function negativeEventCodes(): EventCode[];

package/dist/governance/rules/failure-analysis.js

@@ -0,0 +1,93 @@
+/**
+ * FailureAnalysis - what a terminated agent's successor is told (governance-mode 5.8).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * DETERMINISTIC ON PURPOSE. The analysis is built from the agent's own ledger history and
+ * a fixed code -> advice table; no model is involved. That keeps a respawn reproducible
+ * from the event log alone (I-G2) and means the successor's brief cannot be steered by a
+ * hallucinated post-mortem.
+ *
+ * Lives in its own module (not `elimination.ts`) so `ledger.ts` can build the analysis at
+ * the moment of elimination without a circular import: `elimination.ts` imports the
+ * ledger, the ledger imports this file.
+ */
+import { EVENTS_TABLE, isEventCode } from './events-table.js';
+/** How many penalty events a successor is shown. */
+export const FAILURE_ANALYSIS_TOP_PENALTIES = 5;
+/**
+ * One English, ASCII advice line per NEGATIVE catalogue code. Keyed by code (not by
+ * array) so a missing entry is a compile error for the codes listed here and a test
+ * failure for any negative code added to the catalogue later.
+ */
+export const AVOID_ADVICE = Object.freeze({
+    D5: 'Do not submit code that fails review; self-review against the checklist first.',
+    D6: 'Never introduce injection, unsafe deserialization or secret-handling flaws.',
+    D7: 'Implement every requirement in the spec; trace each acceptance item to code.',
+    D8: 'Do not resubmit work that repeats a finding that was already rejected.',
+    D9: 'Do not leave stubs, TODO bodies or placeholder returns in delivered code.',
+    D11: 'Never submit a skeleton; every function body must do real work.',
+    D13: 'Verify every cross-module call path before declaring the work package done.',
+    D14: 'Produce exactly what the documented contract promises; do not drift from it.',
+    D15: 'Check the producer side of every contract you consume before relying on it.',
+    D17: 'Declare and verify every shared interface; do not narrow the scope to avoid it.',
+    R4: 'Look for defects the tests will find: edge cases, error paths, boundary values.',
+    R5: 'Only flag problems that are real; verify each finding against the code.',
+    R6: 'Make each finding specific: file, issue and the exact change required.',
+    R7: 'Flag stubs and unfinished bodies explicitly instead of passing them.',
+    R9: 'Check cross-module compatibility against the contracts during every review.',
+    R12: 'Write a concrete integration assessment that cites contracts, files or signatures.',
+    T4: 'Test the defect classes that integration later exposes, not only the happy path.',
+    T5: 'Only report defects and claims you have reproduced or can evidence.',
+    T6: 'Verify every requirement in the traceability table; leave no row unverified.',
+    T10: 'Write tests for the module boundary and the contracts, not only internals.',
+    C2: 'Coordinate on interfaces early; an integration failure costs the whole team.',
+    C3: 'After a failed integration, fix the root cause at the boundary, not the symptom.',
+    C4: 'Own the integration boundary jointly; systemic failures hurt every role.',
+});
+/** Generic advice when the history holds no penalty to cite (e.g. a tail elimination). */
+const GENERIC_ADVICE = {
+    depleted: 'Keep every submission complete and correct; repeated deductions ended the run.',
+    tail: 'Raise the quality of every submission; the lowest-ranked member of a role is replaced.',
+    clawback: 'Do not let unverified work reach integration; escrowed credit can be reclaimed.',
+};
+function isPenalty(entry) {
+    return entry.delta < 0 && isEventCode(entry.code);
+}
+/**
+ * Top penalty events of `agent`: most negative first; ties keep the earlier booking.
+ * Sorting on (delta, seq, index) makes the result independent of the sort algorithm.
+ */
+function topPenaltiesOf(agent) {
+    const penalties = agent.history
+        .map((entry, index) => ({ entry, index }))
+        .filter((item) => isPenalty(item.entry));
+    penalties.sort((a, b) => a.entry.delta - b.entry.delta || a.entry.seq - b.entry.seq || a.index - b.index);
+    return penalties.slice(0, FAILURE_ANALYSIS_TOP_PENALTIES).map(({ entry }) => ({
+        code: entry.code,
+        delta: entry.delta,
+        reason: entry.reason,
+    }));
+}
+/** Advice lines for the cited codes, first-seen order, no duplicates. */
+function adviceFor(codes) {
+    const lines = [];
+    for (const code of codes) {
+        const line = AVOID_ADVICE[code];
+        if (line !== undefined && !lines.includes(line))
+            lines.push(line);
+    }
+    return lines;
+}
+/** Build the analysis handed to the successor of `agent`. Pure and deterministic. */
+export function buildFailureAnalysis(agent, reason) {
+    const topPenalties = topPenaltiesOf(agent);
+    const avoid = adviceFor(topPenalties.map((p) => p.code));
+    if (avoid.length === 0)
+        avoid.push(GENERIC_ADVICE[reason]);
+    return { agentId: agent.id, reason, topPenalties, avoid };
+}
+/** Negative catalogue codes; the advice table must cover exactly these. */
+export function negativeEventCodes() {
+    return Object.keys(EVENTS_TABLE).filter((c) => EVENTS_TABLE[c].delta < 0);
+}

package/dist/governance/rules/ledger-replay.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The ledger operation log and its replay (governance-mode 5.3 "crash-safe order", I-G2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * `events.jsonl` is the truth and `ledger.json` a checkpoint. After a crash the store
+ * rebuilds the ledger by folding the logged operations over the initial roster, which is
+ * only sound if every operation is a pure function of (state, operation). `applyOp` is that
+ * single dispatch point: the live engine and the replayer both call it, so there is no
+ * "replay variant" of any rule that could drift from the live one.
+ */
+import type { LedgerState } from '../types.js';
+import { type ClawbackRequest, type CollectiveSpec, type EliminateRequest, type LedgerEvent, type RespawnRequest, type ReverseRequest, type RosterSpec } from './ledger.js';
+export type LedgerOp = {
+    op: 'add_agent';
+    spec: RosterSpec;
+} | {
+    op: 'event';
+    event: LedgerEvent;
+} | {
+    op: 'collective';
+    spec: CollectiveSpec;
+} | {
+    op: 'incident';
+    events: LedgerEvent[];
+    clawbacks?: ClawbackRequest[];
+} | {
+    op: 'confirm_escrow';
+    phase: number;
+    at: number;
+    seq?: number;
+} | {
+    op: 'clawback';
+    request: ClawbackRequest;
+} | {
+    op: 'reverse';
+    request: ReverseRequest;
+} | {
+    op: 'eliminate';
+    request: EliminateRequest;
+} | {
+    op: 'respawn';
+    request: RespawnRequest;
+} | {
+    op: 'tail_check';
+    phase: number;
+    at: number;
+    seq?: number;
+};
+/** Fold one operation. Never mutates `state`; rejected / no-op operations return it as is. */
+export declare function applyOp(state: LedgerState, operation: LedgerOp): LedgerState;
+/** Rebuild a ledger from an initial state and its operation log. */
+export declare function replay(initial: LedgerState, operations: readonly LedgerOp[]): LedgerState;

package/dist/governance/rules/ledger-replay.js

@@ -0,0 +1,53 @@
+/**
+ * The ledger operation log and its replay (governance-mode 5.3 "crash-safe order", I-G2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * `events.jsonl` is the truth and `ledger.json` a checkpoint. After a crash the store
+ * rebuilds the ledger by folding the logged operations over the initial roster, which is
+ * only sound if every operation is a pure function of (state, operation). `applyOp` is that
+ * single dispatch point: the live engine and the replayer both call it, so there is no
+ * "replay variant" of any rule that could drift from the live one.
+ */
+import { evaluateTail } from './elimination.js';
+import { addAgent, applyCollective, applyIncident, apply, clawback, confirmEscrow, eliminate, respawn, reverseEntry, } from './ledger.js';
+/** Fold one operation. Never mutates `state`; rejected / no-op operations return it as is. */
+export function applyOp(state, operation) {
+    switch (operation.op) {
+        case 'add_agent':
+            return addAgent(state, operation.spec);
+        case 'event':
+            return apply(state, operation.event).state;
+        case 'collective':
+            return applyCollective(state, operation.spec).state;
+        case 'incident':
+            return applyIncident(state, {
+                events: operation.events,
+                ...(operation.clawbacks === undefined ? {} : { clawbacks: operation.clawbacks }),
+            }).state;
+        case 'confirm_escrow':
+            return confirmEscrow(state, operation.phase, operation.at, operation.seq).state;
+        case 'clawback':
+            return clawback(state, operation.request).state;
+        case 'reverse':
+            return reverseEntry(state, operation.request).state;
+        case 'eliminate':
+            return eliminate(state, operation.request).state;
+        case 'respawn':
+            return respawn(state, operation.request).state;
+        case 'tail_check':
+            return evaluateTail(state, {
+                phase: operation.phase,
+                at: operation.at,
+                ...(operation.seq === undefined ? {} : { seq: operation.seq }),
+            }).state;
+        default: {
+            const unreachable = operation;
+            throw new Error(`Unknown ledger op: ${JSON.stringify(unreachable)}`);
+        }
+    }
+}
+/** Rebuild a ledger from an initial state and its operation log. */
+export function replay(initial, operations) {
+    return operations.reduce(applyOp, initial);
+}

package/dist/governance/rules/ledger-state.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Ledger state helpers - construction, queries and the small pure functions the booking
+ * code in `ledger.ts` is built from (governance-mode 5.3 / 5.8).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * EVERYTHING HERE IS PURE AND TIME-FREE. No function reads a clock or a random source;
+ * `at` is always an argument. That is what lets `events.jsonl` replay rebuild a ledger
+ * byte-for-byte (I-G2).
+ *
+ * OBJECT KEY ORDER IS PART OF THE CONTRACT. The replay test compares `JSON.stringify` of
+ * two states, so records are always built through the factories below (fixed key order)
+ * and updated with spreads, which keep the original position of an existing key.
+ */
+import type { AgentRecord, EscrowEntry, LedgerEntry, LedgerState, ScoredRole, StandingLabel, StandingRow } from '../types.js';
+/** The inspector's identity. It is never a ledger entity (I-G5). */
+export declare const INSPECTOR_ID = "insp";
+export interface RosterSpec {
+    id: string;
+    role: ScoredRole;
+    generation?: number;
+}
+/** A fresh, active record. `confirmed` is explicit so respawn can start at 80. */
+export declare function createAgentRecord(spec: RosterSpec, confirmed: number): AgentRecord;
+/** Initial state: every roster member starts with `GOV_LIMITS.initialTokens` confirmed. */
+export declare function createLedger(roster: readonly RosterSpec[]): LedgerState;
+/** Add a roster member (later phases may need more DEV slots). Throws on a duplicate id. */
+export declare function addAgent(state: LedgerState, spec: RosterSpec): LedgerState;
+/** `>=80` NORMAL, `60-79` WARNING, `1-59` DANGER, `<=0` KILLED. Reads `confirmed` only. */
+export declare function labelFor(confirmed: number): StandingLabel;
+/** Active scored agents in roster order, optionally of one role. */
+export declare function activeAgents(state: LedgerState, role?: ScoredRole): AgentRecord[];
+/**
+ * Standings in roster order (stable, so the board does not reshuffle on every booking).
+ * An eliminated agent is always KILLED: a tail elimination can leave `confirmed` at 45,
+ * and a row labelled DANGER next to "eliminated" would read as a contradiction.
+ */
+export declare function standings(state: LedgerState): StandingRow[];
+/** Team health = mean `confirmed` of active agents; null when there is none. */
+export declare function teamHealth(state: LedgerState): number | null;
+/** Escrow still held for `phase`: held - released - clawed back. */
+export declare function escrowBalance(agent: AgentRecord, phase: number): number;
+/** Phases with a positive escrow balance, ascending. */
+export declare function escrowPhases(agent: AgentRecord): number[];
+/**
+ * True when `agentId` already has a booking of `code` tagged `incidentId`. Positive
+ * engine events use their incident id as an idempotency key (R1 `r1:<wp>`, R2
+ * `r2:<rejection>`), so a re-run of the settle step cannot pay twice.
+ */
+export declare function hasBooked(state: LedgerState, agentId: string, code: LedgerEntry['code'], incidentId: string): boolean;
+/** Append `entry`, folding the oldest rows once the per-agent bound is exceeded. */
+export declare function appendHistory(history: LedgerEntry[], entry: LedgerEntry): LedgerEntry[];
+/** Key of the per-(agent, incident) cumulative negative counter (I-G4). */
+export declare function incidentKey(agentId: string, incidentId: string): string;
+/** The seq an operation stamps: its own when the caller supplies one, else `state.seq + 1`. */
+export declare function stampSeq(state: LedgerState, requested: number | undefined): number;
+/** Build an entry with a fixed key order and no `undefined` members. */
+export declare function makeEntry(fields: {
+    seq: number;
+    at: number;
+    code: LedgerEntry['code'];
+    delta: number;
+    settlement: LedgerEntry['settlement'];
+    phase: number;
+    by: LedgerEntry['by'];
+    reason: string;
+    wpId?: string;
+    incidentId?: string;
+    evidence?: string;
+    capped?: {
+        requested: number;
+        applied: number;
+    };
+    confirmedAfter: number;
+    provisionalAfter: number;
+}): LedgerEntry;
+export declare function makeEscrowEntry(fields: {
+    seq: number;
+    at: number;
+    phase: number;
+    action: EscrowEntry['action'];
+    amount: number;
+    reason: string;
+    code?: EscrowEntry['code'];
+}): EscrowEntry;

package/dist/governance/rules/ledger-state.js

@@ -0,0 +1,175 @@
+/**
+ * Ledger state helpers - construction, queries and the small pure functions the booking
+ * code in `ledger.ts` is built from (governance-mode 5.3 / 5.8).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * EVERYTHING HERE IS PURE AND TIME-FREE. No function reads a clock or a random source;
+ * `at` is always an argument. That is what lets `events.jsonl` replay rebuild a ledger
+ * byte-for-byte (I-G2).
+ *
+ * OBJECT KEY ORDER IS PART OF THE CONTRACT. The replay test compares `JSON.stringify` of
+ * two states, so records are always built through the factories below (fixed key order)
+ * and updated with spreads, which keep the original position of an existing key.
+ */
+import { GOV_LIMITS, GOV_SCHEMA_VERSION } from '../limits.js';
+/** The inspector's identity. It is never a ledger entity (I-G5). */
+export const INSPECTOR_ID = 'insp';
+/** A fresh, active record. `confirmed` is explicit so respawn can start at 80. */
+export function createAgentRecord(spec, confirmed) {
+    return {
+        id: spec.id,
+        role: spec.role,
+        generation: spec.generation ?? 0,
+        confirmed,
+        provisional: 0,
+        status: 'active',
+        replacedBy: null,
+        tailStrikes: 0,
+        history: [],
+        escrowHistory: [],
+    };
+}
+function assertScorable(spec) {
+    if (spec.id === INSPECTOR_ID || spec.role === 'INSP') {
+        throw new Error(`The inspector is not a ledger entity (I-G5): refusing "${spec.id}".`);
+    }
+}
+/** Initial state: every roster member starts with `GOV_LIMITS.initialTokens` confirmed. */
+export function createLedger(roster) {
+    let state = {
+        schemaVersion: GOV_SCHEMA_VERSION,
+        seq: 0,
+        agents: {},
+        incidentNegatives: {},
+        failureAnalyses: {},
+    };
+    for (const spec of roster)
+        state = addAgent(state, spec);
+    return state;
+}
+/** Add a roster member (later phases may need more DEV slots). Throws on a duplicate id. */
+export function addAgent(state, spec) {
+    assertScorable(spec);
+    if (state.agents[spec.id] !== undefined) {
+        throw new Error(`Ledger already has an agent "${spec.id}".`);
+    }
+    const record = createAgentRecord(spec, GOV_LIMITS.initialTokens);
+    return { ...state, agents: { ...state.agents, [spec.id]: record } };
+}
+/** `>=80` NORMAL, `60-79` WARNING, `1-59` DANGER, `<=0` KILLED. Reads `confirmed` only. */
+export function labelFor(confirmed) {
+    if (confirmed >= GOV_LIMITS.labelWarnThreshold)
+        return 'NORMAL';
+    if (confirmed >= GOV_LIMITS.labelDangerThreshold)
+        return 'WARNING';
+    if (confirmed > 0)
+        return 'DANGER';
+    return 'KILLED';
+}
+/** Active scored agents in roster order, optionally of one role. */
+export function activeAgents(state, role) {
+    return Object.values(state.agents).filter((a) => a.status === 'active' && (role === undefined || a.role === role));
+}
+/**
+ * Standings in roster order (stable, so the board does not reshuffle on every booking).
+ * An eliminated agent is always KILLED: a tail elimination can leave `confirmed` at 45,
+ * and a row labelled DANGER next to "eliminated" would read as a contradiction.
+ */
+export function standings(state) {
+    return Object.values(state.agents).map((a) => ({
+        id: a.id,
+        role: a.role,
+        generation: a.generation,
+        confirmed: a.confirmed,
+        provisional: a.provisional,
+        total: a.confirmed + a.provisional,
+        label: a.status === 'eliminated' ? 'KILLED' : labelFor(a.confirmed),
+        status: a.status,
+        replacedBy: a.replacedBy,
+    }));
+}
+/** Team health = mean `confirmed` of active agents; null when there is none. */
+export function teamHealth(state) {
+    const active = activeAgents(state);
+    if (active.length === 0)
+        return null;
+    return active.reduce((sum, a) => sum + a.confirmed, 0) / active.length;
+}
+/** Escrow still held for `phase`: held - released - clawed back. */
+export function escrowBalance(agent, phase) {
+    let balance = 0;
+    for (const e of agent.escrowHistory) {
+        if (e.phase !== phase)
+            continue;
+        balance += e.action === 'held' ? e.amount : -e.amount;
+    }
+    return balance;
+}
+/** Phases with a positive escrow balance, ascending. */
+export function escrowPhases(agent) {
+    const phases = [...new Set(agent.escrowHistory.map((e) => e.phase))].sort((a, b) => a - b);
+    return phases.filter((p) => escrowBalance(agent, p) > 0);
+}
+/**
+ * True when `agentId` already has a booking of `code` tagged `incidentId`. Positive
+ * engine events use their incident id as an idempotency key (R1 `r1:<wp>`, R2
+ * `r2:<rejection>`), so a re-run of the settle step cannot pay twice.
+ */
+export function hasBooked(state, agentId, code, incidentId) {
+    const agent = state.agents[agentId];
+    if (agent === undefined)
+        return false;
+    return agent.history.some((e) => e.code === code && e.incidentId === incidentId);
+}
+/** Append `entry`, folding the oldest rows once the per-agent bound is exceeded. */
+export function appendHistory(history, entry) {
+    const next = [...history, entry];
+    const excess = next.length - GOV_LIMITS.historyPerAgent;
+    return excess > 0 ? next.slice(excess) : next;
+}
+/** Key of the per-(agent, incident) cumulative negative counter (I-G4). */
+export function incidentKey(agentId, incidentId) {
+    return `${agentId}|${incidentId}`;
+}
+/** The seq an operation stamps: its own when the caller supplies one, else `state.seq + 1`. */
+export function stampSeq(state, requested) {
+    return requested ?? state.seq + 1;
+}
+/** Build an entry with a fixed key order and no `undefined` members. */
+export function makeEntry(fields) {
+    const entry = {
+        seq: fields.seq,
+        at: fields.at,
+        code: fields.code,
+        delta: fields.delta,
+        settlement: fields.settlement,
+        phase: fields.phase,
+        by: fields.by,
+        reason: fields.reason,
+        confirmedAfter: fields.confirmedAfter,
+        provisionalAfter: fields.provisionalAfter,
+    };
+    if (fields.wpId !== undefined)
+        entry.wpId = fields.wpId;
+    if (fields.incidentId !== undefined)
+        entry.incidentId = fields.incidentId;
+    if (fields.evidence !== undefined)
+        entry.evidence = fields.evidence;
+    if (fields.capped !== undefined)
+        entry.capped = fields.capped;
+    return entry;
+}
+export function makeEscrowEntry(fields) {
+    const entry = {
+        seq: fields.seq,
+        at: fields.at,
+        phase: fields.phase,
+        action: fields.action,
+        amount: fields.amount,
+        reason: fields.reason,
+    };
+    if (fields.code !== undefined)
+        entry.code = fields.code;
+    return entry;
+}