fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/video/ledger.py

@@ -0,0 +1,705 @@
+"""Bilateral Transit IOU Ledger & Barter Settlement (Phase 4).
+
+Implements Record-Then-Answer persistence for `video-transit/1.0` grants,
+cumulative hash-chained receipts (`transit_bytes_out`), gap-tolerant receipt
+verification, soft debt ceilings (`degraded-audio-only`), and bartered network
+utility credits (Blob Shoring, Verified Compute / DVM, and DIDComm Mediation).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from typing import Any, Callable, Literal, Mapping, Optional, Sequence, TypedDict
+
+from fleetmesh_core.accounting import accounting
+from node.compartment.schema import Column, Index, Table
+from node.storage import SqliteStore
+from fleetmesh_core.wire.video_transit import (
+    COUNTER_TRANSIT_BYTES_OUT,
+    TransitAckStatus,
+    TransitGrantBody,
+    TransitMode,
+    TransitReceiptAckBody,
+    TransitReceiptBody,
+    check_grant,
+    check_transit_close,
+    check_transit_receipt,
+    receipt_link,
+    register_video_transit_checks,
+    sign_transit_grant,
+    sign_transit_receipt,
+    verify_transit_grant,
+    verify_transit_receipt,
+)
+
+UtilityKind = Literal['blob_shoring', 'verified_compute', 'dvm', 'mediation']
+VALID_UTILITY_KINDS: tuple[str, ...] = ('blob_shoring', 'verified_compute', 'dvm', 'mediation')
+
+# Default conversion rates from bartered network utility units to transit bytes
+DEFAULT_UTILITY_BYTES_RATES: Mapping[str, int] = {
+    'blob_shoring': 1,                  # 1 byte shored = 1 byte transit credit
+    'verified_compute': 1024,           # 1 compute fuel unit = 1 KB transit credit
+    'dvm': 1024 * 1024,                 # 1 DVM job unit = 1 MB transit credit
+    'mediation': 4096,                  # 1 mediated envelope byte/msg unit = 4 KB transit credit
+}
+
+
+class BarterCreditRow(TypedDict):
+    credit_id: str
+    debtor: str
+    creditor: str
+    utility_kind: str
+    units: int
+    equivalent_transit_bytes: int
+    proof_ref: str
+    created_at: int
+
+
+class DebtSummary(TypedDict):
+    debtor: str
+    gross_transit_bytes: int
+    bartered_bytes: int
+    cashu_settled_bytes: int
+    unsettled_bytes: int
+    max_unsettled_transit_bytes: int
+    degraded_audio_only: bool
+
+
+class OutboundChainState(TypedDict):
+    grant_id: str
+    window: int
+    seq: int
+    prev: str
+    heads: list[str]
+    sent_at: int
+    last_bytes_out: int
+
+
+_GRANT_COLS = ('grant_id, stream_id, broadcaster, operator, window_seconds, '
+               'receipt_cadence_seconds, max_unsettled_transit_bytes, mode, '
+               'reflector_endpoints_json, status, created_at, sig')
+_CHAIN_COLS = 'grant_id, window, seq, prev, heads_json, sent_at, last_bytes_out'
+_CREDIT_COLS = ('credit_id, debtor, creditor, utility_kind, units, '
+                'equivalent_transit_bytes, proof_ref, created_at')
+"""The column orders the positional reads below depend on.
+
+The selects said `SELECT *` and the rows were read by name through a
+`sqlite3.Row` factory - which is one of the driver leaks the dialect layer
+exists to remove, since a second driver has its own row type. The orders are
+written down once here instead.
+"""
+
+
+class TransitLedgerStore(SqliteStore):
+    """Transit grants, receipt chains and bartered utility repayments.
+
+    `DURABILITY = 'commit'` is declared, not decorative: this store holds
+    bilateral hash-chained IOUs, and `record_outbound_receipt` commits the
+    chain advance *before* the receipt goes on the wire - Record-Then-Answer.
+    The class docstring claimed that durability while the store declared no
+    class at all and was not a `BaseStore`, which is the shape of defect R0
+    (I15) was: a meter whose state was asserted durable, lost across a
+    restart, and cost a peer its standing. Naming it is what lets
+    test_durability_boundary hold it to the claim.
+
+    A `SqliteStore` rather than a hand-rolled connection, so the base owns the
+    connection, the lock, the per-store schema version, transaction control and
+    the dialect - see docs/storage-backends.md.
+    """
+
+    DURABILITY = 'commit'
+
+    SCHEMA = (
+        Table('transit_grants', (
+            Column('grant_id', 'TEXT', primary_key=True),
+            Column('stream_id', 'TEXT', not_null=True),
+            Column('broadcaster', 'TEXT', not_null=True),
+            Column('operator', 'TEXT', not_null=True),
+            Column('window_seconds', 'INTEGER', not_null=True),
+            Column('receipt_cadence_seconds', 'INTEGER', not_null=True),
+            Column('max_unsettled_transit_bytes', 'INTEGER', not_null=True),
+            Column('mode', 'TEXT', not_null=True),
+            Column('reflector_endpoints_json', 'TEXT', not_null=True),
+            Column('status', 'TEXT', not_null=True),
+            Column('created_at', 'INTEGER', not_null=True),
+            Column('sig', 'TEXT', not_null=True),
+        )),
+        Table('transit_chains_out', (
+            Column('grant_id', 'TEXT', not_null=True),
+            Column('window', 'INTEGER', not_null=True),
+            Column('seq', 'INTEGER', not_null=True),
+            Column('prev', 'TEXT', not_null=True),
+            Column('heads_json', 'TEXT', not_null=True),
+            Column('sent_at', 'INTEGER', not_null=True),
+            Column('last_bytes_out', 'INTEGER', not_null=True),
+        ), primary_key=('grant_id', 'window')),
+        Table('transit_receipts_in', (
+            Column('grant_id', 'TEXT', not_null=True),
+            Column('window', 'INTEGER', not_null=True),
+            Column('seq', 'INTEGER', not_null=True),
+            Column('head', 'TEXT', not_null=True),
+            Column('broadcaster', 'TEXT', not_null=True),
+            Column('transit_bytes_out', 'INTEGER', not_null=True),
+            Column('body_json', 'TEXT', not_null=True),
+            Column('received_at', 'INTEGER', not_null=True),
+        ), primary_key=('grant_id', 'window', 'seq')),
+        Table('transit_barter_credits', (
+            Column('credit_id', 'TEXT', primary_key=True),
+            Column('debtor', 'TEXT', not_null=True),
+            Column('creditor', 'TEXT', not_null=True),
+            Column('utility_kind', 'TEXT', not_null=True),
+            Column('units', 'INTEGER', not_null=True),
+            Column('equivalent_transit_bytes', 'INTEGER', not_null=True),
+            Column('proof_ref', 'TEXT', not_null=True),
+            Column('created_at', 'INTEGER', not_null=True),
+        ), indices=(
+            Index('idx_transit_barter_debtor', ('debtor',)),
+        )),
+    )
+
+    def __init__(self, db_path: str = ':memory:',
+                 clock: Optional[Callable[[], int]] = None) -> None:
+        register_video_transit_checks()
+        # An injected clock, defaulting to wall time. The money path - windows,
+        # receipt cadence, debt ceilings - is decided at time boundaries, and a
+        # direct time.time() makes those boundaries untestable. The compartment
+        # passes its own clock down, so a suite that moves the clock moves this too.
+        self._clock: Callable[[], int] = clock or (lambda: int(time.time()))
+        self.findings: list[tuple[str, int, str, str]] = []
+        self.receipt_gaps: list[tuple[str, int, int, int, int]] = []
+        super().__init__(db_path)
+
+    def close(self) -> None:
+        super().close()
+
+    # ---- Grant Issuance & Storage -------------------------------------------
+
+    def issue_grant(
+        self,
+        stream_id: str,
+        broadcaster: str,
+        operator_pk: str,
+        operator_sk: str,
+        window_seconds: int = 600,
+        receipt_cadence_seconds: int = 60,
+        max_unsettled_transit_bytes: int = 500 * 1024 * 1024,
+        reflector_endpoints: Sequence[str] = (),
+        mode: TransitMode = 'pro-bono',
+        now: Optional[int] = None,
+    ) -> TransitGrantBody:
+        """Create, sign, and durably commit a transit grant before wire emission."""
+        now_val = self._clock() if now is None else int(now)
+        seed = f"{stream_id}:{broadcaster.lower()}:{operator_pk.lower()}:{now_val}".encode('utf-8')
+        grant_id = hashlib.sha256(seed).hexdigest()
+        unsigned: TransitGrantBody = {
+            'grant_id': grant_id,
+            'stream_id': stream_id,
+            'broadcaster': broadcaster.lower(),
+            'operator': operator_pk.lower(),
+            'window_seconds': int(window_seconds),
+            'receipt_cadence_seconds': int(receipt_cadence_seconds),
+            'max_unsettled_transit_bytes': int(max_unsettled_transit_bytes),
+            'reflector_endpoints': list(reflector_endpoints),
+            'mode': mode,
+            'at': now_val,
+        }
+        signed = sign_transit_grant(unsigned, operator_sk)
+        self.save_grant(signed)
+        return signed
+
+    def save_grant(self, grant: TransitGrantBody, status: str = 'live') -> None:
+        """Persist a verified TransitGrantBody to SQLite."""
+        why = check_grant(grant)
+        if why is not None:
+            raise ValueError(f"Invalid transit grant: {why}")
+        operator_pk = grant.get('operator', '')
+        if not verify_transit_grant(grant, operator_pk):
+            raise ValueError("Transit grant signature verification failed")
+
+        with self._lock:
+            self.execute(
+                """
+                INSERT OR REPLACE INTO transit_grants (
+                    grant_id, stream_id, broadcaster, operator,
+                    window_seconds, receipt_cadence_seconds, max_unsettled_transit_bytes,
+                    mode, reflector_endpoints_json, status, created_at, sig
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    grant['grant_id'],
+                    grant['stream_id'],
+                    grant['broadcaster'].lower(),
+                    grant['operator'].lower(),
+                    int(grant['window_seconds']),
+                    int(grant['receipt_cadence_seconds']),
+                    int(grant['max_unsettled_transit_bytes']),
+                    grant.get('mode', 'pro-bono'),
+                    json.dumps(list(grant.get('reflector_endpoints', []))),
+                    status,
+                    int(grant.get('at', self._clock())),
+                    grant['sig'],
+                ),
+            )
+            self.commit()
+
+    def get_grant(self, grant_id: str) -> Optional[TransitGrantBody]:
+        with self._lock:
+            row = self._one(
+                'SELECT ' + _GRANT_COLS + ' FROM transit_grants WHERE grant_id = ?',
+                (grant_id,),
+            )
+            if row is None:
+                return None
+            mode_val: TransitMode = 'commercial' if row[7] == 'commercial' else 'pro-bono'
+            return {
+                'grant_id': str(row[0]),
+                'stream_id': str(row[1]),
+                'broadcaster': str(row[2]),
+                'operator': str(row[3]),
+                'window_seconds': int(row[4]),
+                'receipt_cadence_seconds': int(row[5]),
+                'max_unsettled_transit_bytes': int(row[6]),
+                'mode': mode_val,
+                'reflector_endpoints': list(json.loads(row[8])),
+                'at': int(row[10]),
+                'sig': str(row[11]),
+            }
+
+    def close_grant(self, grant_id: str) -> None:
+        with self._lock:
+            self.execute(
+                "UPDATE transit_grants SET status = 'closed' WHERE grant_id = ?",
+                (grant_id,),
+            )
+            self.commit()
+
+    # ---- Record-Then-Answer Outbound Receipt Chain --------------------------
+
+    def get_outbound_chain(self, grant_id: str, window: int) -> Optional[OutboundChainState]:
+        with self._lock:
+            row = self._one(
+                'SELECT ' + _CHAIN_COLS + ' FROM transit_chains_out WHERE grant_id = ? AND window = ?',
+                (grant_id, int(window)),
+            )
+            if row is None:
+                return None
+            return {
+                'grant_id': str(row[0]),
+                'window': int(row[1]),
+                'seq': int(row[2]),
+                'prev': str(row[3]),
+                'heads': list(json.loads(row[4])),
+                'sent_at': int(row[5]),
+                'last_bytes_out': int(row[6]),
+            }
+
+    def record_outbound_receipt(
+        self,
+        grant_id: str,
+        stream_id: str,
+        window: int,
+        transit_bytes_out: int,
+        sk_hex: str,
+        now: Optional[int] = None,
+    ) -> tuple[TransitReceiptBody, str]:
+        """Produce, sign, and durably persist the next cumulative TransitReceiptBody
+        in the hash chain BEFORE it is emitted on the wire (Record-Then-Answer).
+        """
+        now_val = self._clock() if now is None else int(now)
+        with self._lock:
+            state = self.get_outbound_chain(grant_id, window)
+            if state is None:
+                seq = 0
+                prev = accounting.ZERO
+                heads: list[str] = []
+                last_bytes = 0
+            else:
+                seq = state['seq']
+                prev = state['prev']
+                heads = list(state['heads'])
+                last_bytes = state['last_bytes_out']
+
+            if transit_bytes_out < last_bytes:
+                raise ValueError(
+                    f"Cumulative transit_bytes_out cannot decrease ({transit_bytes_out} < {last_bytes})"
+                )
+
+            unsigned: TransitReceiptBody = {
+                'grant': grant_id,
+                'stream_id': stream_id,
+                'window': int(window),
+                'seq': seq,
+                'prev': prev,
+                'counters': {COUNTER_TRANSIT_BYTES_OUT: int(transit_bytes_out)},
+                'at': now_val,
+            }
+            signed = sign_transit_receipt(unsigned, sk_hex)
+            head = receipt_link(signed)
+            heads.append(head)
+
+            # Record-Then-Answer: commit chain advancement to SQLite BEFORE returning
+            self.execute(
+                """
+                INSERT OR REPLACE INTO transit_chains_out (
+                    grant_id, window, seq, prev, heads_json, sent_at, last_bytes_out
+                ) VALUES (?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    grant_id,
+                    int(window),
+                    seq + 1,
+                    head,
+                    json.dumps(heads),
+                    now_val,
+                    int(transit_bytes_out),
+                ),
+            )
+            self.commit()
+            return signed, head
+
+    # ---- Inbound Receipt Verification & Gap-Tolerant Chain Intake -----------
+
+    def get_inbound_receipts(self, grant_id: str, window: int) -> list[TransitReceiptBody]:
+        with self._lock:
+            rows = self.execute(
+                'SELECT body_json FROM transit_receipts_in WHERE grant_id = ? AND window = ? ORDER BY seq ASC',
+                (grant_id, int(window)),
+            ).fetchall()
+            out: list[TransitReceiptBody] = []
+            for r in rows:
+                out.append(json.loads(r[0]))
+            return out
+
+    def on_inbound_receipt(
+        self,
+        signer_pubkey: str,
+        body: Mapping[str, Any],
+        now: Optional[int] = None,
+    ) -> TransitReceiptAckBody:
+        """Validate and record an inbound TransitReceiptBody.
+
+        Enforces:
+        - Door shape check (`check_transit_receipt`)
+        - Schnorr signature verification (`verify_transit_receipt`)
+        - Gap tolerance vs. rewrite detection (matching `budget/receipts.py`)
+        - Monotonic cumulative `transit_bytes_out` counters
+        - Soft debt ceiling evaluation (`degraded-audio-only` when unsettled debt
+          reaches `max_unsettled_transit_bytes`).
+        """
+        now_val = self._clock() if now is None else int(now)
+        why = check_transit_receipt(body)
+        if why is not None:
+            seq_raw = body.get('seq') if isinstance(body, Mapping) else 0
+            seq_val = seq_raw if isinstance(seq_raw, int) and not isinstance(seq_raw, bool) else 0
+            return {
+                'grant': str(body.get('grant', accounting.ZERO)),
+                'seq': seq_val,
+                'head': accounting.ZERO,
+                'status': 'divergent',
+                'unsettled_bytes': 0,
+            }
+
+        grant_id = str(body['grant'])
+        window = int(body['window'])
+        seq = int(body['seq'])
+        grant = self.get_grant(grant_id)
+        if grant is None:
+            return {
+                'grant': grant_id,
+                'seq': seq,
+                'head': accounting.ZERO,
+                'status': 'divergent',
+                'unsettled_bytes': 0,
+            }
+
+        broadcaster = grant['broadcaster']
+        with self._lock:
+            chain = self.get_inbound_receipts(grant_id, window)
+            expected_seq = int(chain[-1]['seq']) + 1 if chain else 0
+            expected_prev = receipt_link(chain[-1]) if chain else accounting.ZERO
+            problems: list[str] = []
+
+            if signer_pubkey.strip().lower() != broadcaster.strip().lower():
+                problems.append('receipt signer does not match grant broadcaster')
+            elif not verify_transit_receipt(body, broadcaster):
+                problems.append('no valid signature over receipt chain link')
+
+            gap = 0
+            if seq < expected_seq:
+                problems.append(f'seq {seq}, expected {expected_seq} or later (rewrite attempt)')
+            elif seq > expected_seq:
+                gap = seq - expected_seq
+
+            if not gap and body.get('prev') != expected_prev:
+                problems.append('prev does not chain')
+
+            new_bytes = int(body['counters'][COUNTER_TRANSIT_BYTES_OUT])
+            if chain:
+                prev_bytes = int(chain[-1]['counters'].get(COUNTER_TRANSIT_BYTES_OUT, 0))
+                if new_bytes < prev_bytes:
+                    problems.append(f'counter {COUNTER_TRANSIT_BYTES_OUT} went backwards ({new_bytes} < {prev_bytes})')
+
+            if problems:
+                self.findings.append((signer_pubkey.lower(), window, 'S2', 'transit receipt chain: ' + '; '.join(problems)))
+                summary = self.debt_summary(broadcaster, grant_id)
+                return {
+                    'grant': grant_id,
+                    'seq': seq,
+                    'head': expected_prev,
+                    'status': 'divergent',
+                    'unsettled_bytes': summary['unsettled_bytes'],
+                }
+
+            if gap > 0:
+                self.receipt_gaps.append((signer_pubkey.lower(), window, expected_seq, seq, now_val))
+
+            head = receipt_link(body)
+            self.execute(
+                """
+                INSERT OR REPLACE INTO transit_receipts_in (
+                    grant_id, window, seq, head, broadcaster, transit_bytes_out, body_json, received_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    grant_id,
+                    window,
+                    seq,
+                    head,
+                    broadcaster.lower(),
+                    new_bytes,
+                    json.dumps(dict(body), sort_keys=True),
+                    now_val,
+                ),
+            )
+            self.commit()
+
+            summary = self.debt_summary(broadcaster, grant_id)
+            status: TransitAckStatus = (
+                'degraded-audio-only' if summary['degraded_audio_only'] else 'accepted'
+            )
+            return {
+                'grant': grant_id,
+                'seq': seq,
+                'head': head,
+                'status': status,
+                'unsettled_bytes': summary['unsettled_bytes'],
+            }
+
+    def on_inbound_close(
+        self,
+        body: Mapping[str, Any],
+        now: Optional[int] = None,
+    ) -> TransitReceiptAckBody:
+        """Validate a TransitCloseBody and close the grant if final head matches."""
+        why = check_transit_close(body)
+        if why is not None:
+            return {
+                'grant': str(body.get('grant', accounting.ZERO)),
+                'seq': 0,
+                'head': accounting.ZERO,
+                'status': 'divergent',
+                'unsettled_bytes': 0,
+            }
+        grant_id = str(body['grant'])
+        window = int(body['window'])
+        grant = self.get_grant(grant_id)
+        with self._lock:
+            chain = self.get_inbound_receipts(grant_id, window)
+            head = receipt_link(chain[-1]) if chain else accounting.ZERO
+            is_final = body.get('final_receipt_head') == head
+            if is_final:
+                self.close_grant(grant_id)
+            broadcaster = grant['broadcaster'] if grant else ''
+            summary = self.debt_summary(broadcaster, grant_id) if broadcaster else {
+                'unsettled_bytes': 0,
+            }
+            return {
+                'grant': grant_id,
+                'seq': len(chain),
+                'head': head,
+                'status': 'final' if is_final else 'accepted',
+                'unsettled_bytes': int(summary['unsettled_bytes']),
+            }
+
+    # ---- Bartered Network Utility & Debt Accounting -------------------------
+
+    def credit_barter(
+        self,
+        debtor: str,
+        creditor: str,
+        utility_kind: UtilityKind,
+        units: int,
+        proof_ref: str,
+        equivalent_transit_bytes: Optional[int] = None,
+        now: Optional[int] = None,
+    ) -> BarterCreditRow:
+        """Credit bartered network utility (Blob Shoring, Verified Compute, DVM,
+        or DIDComm Mediation) against a debtor's unsettled transit IOU balance.
+        """
+        if utility_kind not in VALID_UTILITY_KINDS:
+            raise ValueError(f"Unknown utility_kind: {utility_kind!r}")
+        if units <= 0:
+            raise ValueError(f"units must be positive, got {units}")
+
+        now_val = self._clock() if now is None else int(now)
+        if equivalent_transit_bytes is None:
+            rate = DEFAULT_UTILITY_BYTES_RATES.get(utility_kind, 1)
+            equiv_bytes = int(units) * rate
+        else:
+            equiv_bytes = int(equivalent_transit_bytes)
+
+        seed = f"{debtor.lower()}:{creditor.lower()}:{utility_kind}:{proof_ref}".encode('utf-8')
+        credit_id = hashlib.sha256(seed).hexdigest()
+
+        row: BarterCreditRow = {
+            'credit_id': credit_id,
+            'debtor': debtor.lower(),
+            'creditor': creditor.lower(),
+            'utility_kind': utility_kind,
+            'units': int(units),
+            'equivalent_transit_bytes': equiv_bytes,
+            'proof_ref': proof_ref,
+            'created_at': now_val,
+        }
+        with self._lock:
+            self.execute(
+                """
+                INSERT OR REPLACE INTO transit_barter_credits (
+                    credit_id, debtor, creditor, utility_kind,
+                    units, equivalent_transit_bytes, proof_ref, created_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    row['credit_id'],
+                    row['debtor'],
+                    row['creditor'],
+                    row['utility_kind'],
+                    row['units'],
+                    row['equivalent_transit_bytes'],
+                    row['proof_ref'],
+                    row['created_at'],
+                ),
+            )
+            self.commit()
+        return row
+
+    def list_barter_credits(self, debtor: str) -> list[BarterCreditRow]:
+        with self._lock:
+            rows = self._all(
+                'SELECT ' + _CREDIT_COLS + ' FROM transit_barter_credits '
+                'WHERE debtor = ? ORDER BY created_at ASC',
+                (debtor.lower(),),
+            )
+            return [
+                {
+                    'credit_id': str(r[0]),
+                    'debtor': str(r[1]),
+                    'creditor': str(r[2]),
+                    'utility_kind': str(r[3]),
+                    'units': int(r[4]),
+                    'equivalent_transit_bytes': int(r[5]),
+                    'proof_ref': str(r[6]),
+                    'created_at': int(r[7]),
+                }
+                for r in rows
+            ]
+
+    def gross_transit_bytes(self, debtor: str, grant_id: Optional[str] = None) -> int:
+        """Sum the maximum cumulative `transit_bytes_out` per (grant_id, window) for a debtor."""
+        with self._lock:
+            if grant_id is not None:
+                rows = self.execute(
+                    """
+                    SELECT MAX(transit_bytes_out) AS win_max
+                    FROM transit_receipts_in
+                    WHERE broadcaster = ? AND grant_id = ?
+                    GROUP BY grant_id, window
+                    """,
+                    (debtor.lower(), grant_id),
+                ).fetchall()
+            else:
+                rows = self.execute(
+                    """
+                    SELECT MAX(transit_bytes_out) AS win_max
+                    FROM transit_receipts_in
+                    WHERE broadcaster = ?
+                    GROUP BY grant_id, window
+                    """,
+                    (debtor.lower(),),
+                ).fetchall()
+            return sum(int(r[0] or 0) for r in rows)
+
+    def total_bartered_bytes(self, debtor: str) -> int:
+        with self._lock:
+            row = self.execute(
+                'SELECT COALESCE(SUM(equivalent_transit_bytes), 0) AS total FROM transit_barter_credits WHERE debtor = ?',
+                (debtor.lower(),),
+            ).fetchone()
+            return int(row[0]) if row is not None else 0
+
+    def debt_summary(self, debtor: str, grant_id: Optional[str] = None) -> DebtSummary:
+        """Calculate gross transit bytes, bartered credits, unsettled debt, and
+        whether soft debt degradation (`degraded_audio_only`) is active.
+        """
+        gross = self.gross_transit_bytes(debtor, grant_id=grant_id)
+        bartered = self.total_bartered_bytes(debtor)
+        unsettled = max(0, gross - bartered)
+
+        ceiling = 0
+        if grant_id is not None:
+            grant = self.get_grant(grant_id)
+            if grant is not None:
+                ceiling = int(grant['max_unsettled_transit_bytes'])
+        else:
+            with self._lock:
+                row = self.execute(
+                    'SELECT COALESCE(MAX(max_unsettled_transit_bytes), 0) AS cap FROM transit_grants WHERE broadcaster = ?',
+                    (debtor.lower(),),
+                ).fetchone()
+                ceiling = int(row[0]) if row is not None else 0
+
+        degraded = bool(ceiling > 0 and unsettled >= ceiling)
+        return {
+            'debtor': debtor.lower(),
+            'gross_transit_bytes': gross,
+            'bartered_bytes': bartered,
+            'cashu_settled_bytes': 0,
+            'unsettled_bytes': unsettled,
+            'max_unsettled_transit_bytes': ceiling,
+            'degraded_audio_only': degraded,
+        }
+
+    def summary(self) -> dict[str, list[Any]]:
+        """Return a summary of all known debtors and barter credit rows."""
+        with self._lock:
+            rows = self.execute(
+                """
+                SELECT DISTINCT broadcaster AS debtor FROM transit_grants
+                UNION
+                SELECT DISTINCT broadcaster AS debtor FROM transit_receipts_in
+                UNION
+                SELECT DISTINCT debtor FROM transit_barter_credits
+                ORDER BY debtor ASC
+                """
+            ).fetchall()
+            debtors = [str(r[0]) for r in rows if r[0]]
+            debts = [self.debt_summary(d) for d in debtors]
+            credits: list[BarterCreditRow] = []
+            for d in debtors:
+                credits.extend(self.list_barter_credits(d))
+            return {
+                'debts': debts,
+                'utility_credits': credits,
+            }
+
+
+__all__ = [
+    'UtilityKind',
+    'VALID_UTILITY_KINDS',
+    'DEFAULT_UTILITY_BYTES_RATES',
+    'BarterCreditRow',
+    'DebtSummary',
+    'OutboundChainState',
+    'TransitLedgerStore',
+]