@aragon-agent/cli 0.6.43 → 0.6.45

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

@@ -0,0 +1,228 @@
+/**
+ * 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 type { AgentRecord, FailureAnalysis, LedgerEntry, LedgerState } from '../types.js';
+import { type EventCode, type EventDef, type Settlement } from './events-table.js';
+export * from './ledger-state.js';
+/** C2 for an agent that is not the primary cause of the failed integration (5.7). */
+export declare const C2_RELIEF_DELTA = -2;
+/** One booking request. `delta` is never supplied: it comes from the catalogue. */
+export interface LedgerEvent {
+    code: EventCode;
+    agentId: string;
+    at: number;
+    phase: number;
+    by: LedgerEntry['by'];
+    reason: string;
+    wpId?: string;
+    incidentId?: string;
+    evidence?: string;
+    /** C2 only: book the relieved -2 instead of -5 (non-primary agent). */
+    relief?: boolean;
+    /** Stored-event seq to stamp; absent => `state.seq + 1`. */
+    seq?: number;
+}
+export type RejectCode = 'INSPECTOR_NOT_SCORED' | 'UNKNOWN_CODE' | 'UNKNOWN_AGENT' | 'AGENT_ELIMINATED' | 'ROLE_MISMATCH' | 'RELIEF_NOT_ALLOWED';
+export interface Rejection {
+    code: RejectCode;
+    message: string;
+}
+export interface ApplyOutcome {
+    /** The new state; the INPUT state, untouched, when the event was rejected. */
+    state: LedgerState;
+    booked: boolean;
+    rejected?: Rejection;
+    entry?: LedgerEntry;
+    /** Magnitude trimmed by the event limit, the incident cap or the floor at 0. */
+    clipped: number;
+    /** True when this booking depleted `confirmed` and removed the agent (KILL). */
+    eliminated: boolean;
+}
+export interface ApplyOptions {
+    /**
+     * Catalogue override, for tests only (a settlement value outside the three known ones
+     * must make `apply` throw, and the real table cannot hold one). Production callers
+     * never pass it.
+     */
+    catalogue?: Readonly<Record<string, EventDef>>;
+}
+export type Pool = 'provisional' | 'confirmed' | 'deduct';
+/**
+ * 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 declare function settlementPool(settlement: Settlement, delta: number): Pool;
+/** Order in which one incident's events are applied so a cap truncates the right one. */
+export declare function incidentPriority(code: EventCode): number;
+/**
+ * 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 declare function apply(state: LedgerState, event: LedgerEvent, options?: ApplyOptions): ApplyOutcome;
+/** Apply a list in order; a rejected event is skipped (its outcome says why). */
+export declare function applyAll(state: LedgerState, events: readonly LedgerEvent[], options?: ApplyOptions): {
+    state: LedgerState;
+    outcomes: ApplyOutcome[];
+};
+export interface CollectiveSpec {
+    code: 'C1' | 'C2' | 'C3' | 'C4';
+    at: number;
+    phase: number;
+    by: LedgerEntry['by'];
+    reason: string;
+    incidentId?: string;
+    wpId?: string;
+    seq?: number;
+    /** Restrict to these ids (the phase's members); absent => every active scored agent. */
+    participants?: readonly string[];
+    /** C2 only: agents that get the relieved -2 (everyone who is not a primary). */
+    reliefIds?: readonly string[];
+}
+/**
+ * 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 declare function expandCollective(state: LedgerState, spec: CollectiveSpec): LedgerEvent[];
+export declare function applyCollective(state: LedgerState, spec: CollectiveSpec): {
+    state: LedgerState;
+    outcomes: ApplyOutcome[];
+};
+export interface EscrowReleaseOutcome {
+    state: LedgerState;
+    released: Array<{
+        agentId: string;
+        amount: number;
+    }>;
+}
+/**
+ * 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 declare function confirmEscrow(state: LedgerState, phase: number, at: number, seqOverride?: number): EscrowReleaseOutcome;
+export interface ClawbackRequest {
+    agentId: string;
+    phase: number;
+    reason: string;
+    incidentId?: string;
+    at: number;
+    by?: LedgerEntry['by'];
+    seq?: number;
+}
+export interface ClawbackOutcome {
+    state: LedgerState;
+    /** Escrow actually reclaimed (positive number). */
+    clawed: number;
+    /** Escrow that existed for the phase before the cap was applied. */
+    requested: number;
+    capped: boolean;
+}
+/**
+ * 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 declare function clawback(state: LedgerState, request: ClawbackRequest): ClawbackOutcome;
+export interface IncidentInput {
+    events: readonly LedgerEvent[];
+    clawbacks?: readonly ClawbackRequest[];
+}
+export interface IncidentOutcome {
+    state: LedgerState;
+    outcomes: ApplyOutcome[];
+    clawbacks: ClawbackOutcome[];
+}
+/**
+ * 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 declare function applyIncident(state: LedgerState, input: IncidentInput): IncidentOutcome;
+export interface ReverseRequest {
+    agentId: string;
+    code: EventCode;
+    wpId?: string;
+    at: number;
+    reason: string;
+    seq?: number;
+}
+export interface ReverseOutcome {
+    state: LedgerState;
+    reversed: boolean;
+    entry?: LedgerEntry;
+}
+/**
+ * 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 declare function reverseEntry(state: LedgerState, request: ReverseRequest): ReverseOutcome;
+export interface EliminateRequest {
+    agentId: string;
+    reason: FailureAnalysis['reason'];
+    at: number;
+    seq?: number;
+}
+export interface EliminateOutcome {
+    state: LedgerState;
+    eliminated: boolean;
+    analysis: FailureAnalysis | null;
+}
+/**
+ * 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 declare function eliminate(state: LedgerState, request: EliminateRequest): EliminateOutcome;
+export interface RespawnRequest {
+    agentId: string;
+    phase: number;
+    at: number;
+    seq?: number;
+}
+export interface RespawnOutcome {
+    state: LedgerState;
+    successor: AgentRecord | null;
+    analysis: FailureAnalysis | null;
+}
+/** `dev2` -> `dev2-r1` -> `dev2-r2`: the suffix tracks the generation. */
+export declare function successorId(predecessor: AgentRecord): string;
+/**
+ * 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 declare function respawn(state: LedgerState, request: RespawnRequest): RespawnOutcome;