fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/video/compartment.py

@@ -0,0 +1,932 @@
+"""VideoStream & Transit Reflector Compartment (node.planes.services.video.compartment).
+
+Integrates VideoStreamPackager, TransitReflectorManager, and TransitLedgerStore
+into the MeshNode runtime:
+- Mounts `/video/streams` and `/video/live/<stream_id>/...` onto ProtocolHost.
+- Routes `https://fleetmesh.org/video-transit/1.0/*` envelopes on ProtocolRouter.
+- Evaluates Capacity shed handovers (`narrow_scope` / `amend_down` vs `restore_below`)
+  on every node tick.
+- Exposes declarative control-socket commands (`video.start_stream`, `video.status`,
+  `video.settle`, `video.ingest_segment`, `video.solicit_transit`) and the `stream`
+  CLI verb for plugin/operator dispatch.
+"""
+from __future__ import annotations
+
+import base64
+import dataclasses
+import os
+from typing import Any, Callable, Mapping, Optional
+
+from fleetmesh_core.wire.video_transit import (
+    TYPE_TRANSIT_CLOSE,
+    TYPE_TRANSIT_GRANT,
+    TYPE_TRANSIT_RECEIPT,
+    TYPE_TRANSIT_RECEIPT_ACK,
+    TYPE_TRANSIT_SOLICITATION,
+    VIDEO_TRANSIT_PIURI,
+    TransitGrantBody,
+    check_grant,
+    check_solicitation,
+    check_transit_close,
+    check_transit_receipt,
+    check_transit_receipt_ack,
+    make_transit_envelope,
+)
+from node import channels as ch_mod
+from node import metrics as mx_mod
+from node.compartment import Command, Compartment, Need, stores as st
+from node.config import parameter as par
+from node.config.parameter import ParamBlock, Parameter
+from node.protocols.p2panda.store import P2PandaLogStore
+from node.protocols.rhio.store import RhioBlobSync
+
+from .barter import BarterHookResult, BarterSettlementBridge
+from .cli import register_stream_cli
+from .ingest import LiveMediaIngestBridge
+from .ledger import TransitLedgerStore
+from .packager import VideoStreamPackager
+from .player import mount_player_routes
+from .transit import TransitReflectorManager
+
+
+@dataclasses.dataclass(frozen=True)
+class VideoConfig(ParamBlock):
+    """Configuration block for the Video Streaming & Transit Reflector compartment."""
+
+    key = 'video'
+    enabled: bool = True
+    ring_capacity: int = 256
+    default_debt_ceiling_bytes: int = 500 * 1024 * 1024
+
+    PARAMS = (
+        Parameter[bool](
+            key='enabled',
+            name='Video Streaming & Transit',
+            description='Enable live CMAF/LL-HLS packaging and Transit Reflector routing.',
+            type=bool,
+            default=True,
+            must='be a boolean',
+            live=True,
+            tags=('video', 'transit'),
+            sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST),
+        ),
+        Parameter[int](
+            key='ring_capacity',
+            name='MoQ Ring Buffer Capacity',
+            description='Maximum frames retained per stream in the real-time MoQ ring buffer.',
+            type=int,
+            default=256,
+            must='be a positive integer',
+            live=True,
+            tags=('video', 'moq'),
+            sources=(par.ARG, par.ENV, par.FILE),
+        ),
+        Parameter[int](
+            key='default_debt_ceiling_bytes',
+            name='Default Pro-Bono Transit Debt Ceiling (Bytes)',
+            description='Unsettled transit byte threshold before soft audio-only degradation.',
+            type=int,
+            default=500 * 1024 * 1024,
+            must='be a positive integer',
+            live=True,
+            tags=('video', 'accounting'),
+            sources=(par.ARG, par.ENV, par.FILE),
+        ),
+    )
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> VideoConfig:
+        if isinstance(raw, bool):
+            return cls(enabled=raw)
+        if not isinstance(raw, Mapping):
+            return cls()
+        return cls(
+            enabled=bool(raw.get('enabled', True)),
+            ring_capacity=int(raw.get('ring_capacity', cls.ring_capacity)),
+            default_debt_ceiling_bytes=int(
+                raw.get('default_debt_ceiling_bytes', cls.default_debt_ceiling_bytes)
+            ),
+        )
+
+
+class VideoTransitCompartment(Compartment):
+    """MeshNode compartment orchestrating live video packaging, transit reflection,
+    and bilateral IOU / barter settlement.
+    """
+
+    name: str = 'video'
+    optional: bool = True
+    enabled_by: Optional[str] = 'video'
+    # The three late needs below are compartments, so they are declared here:
+    # all three are core and tick before this one.
+    requires: tuple[str, ...] = ('strain', 'capacity', 'paidfetch', 'blob_replication')
+    # The utilities a transit debt can be repaid in. Optional, so they are
+    # `uses` and resolve to None when the operator has not configured them.
+    uses: tuple[str, ...] = ('compute', 'dvm')
+    reads: tuple[str, ...] = ('video',)
+    live: tuple[str, ...] = ('video',)
+    config_cls = VideoConfig
+    piuris: tuple[str, ...] = (VIDEO_TRANSIT_PIURI,)
+    cli = (('stream', register_stream_cli),)
+
+    STORES = (
+        st.Store(
+            key='recent_events',
+            description='recent video packaging and transit events, newest last',
+            kind=st.RING,
+            shape=tuple,
+            bound=128,
+        ),
+    )
+    recent_events: st.Ring[tuple[Any, ...]]
+
+    CHANNELS = (
+        ch_mod.Channel(
+            'video_grant_undelivered',
+            'A signed transit grant was recorded but could not be sent to the peer',
+            level=ch_mod.TROUBLE,
+            say='grant {grant} for {peer} is in the ledger and did not reach the peer',
+            tags=('video', 'transit'),
+        ),
+        ch_mod.Channel(
+            'video_ack_undelivered',
+            'An inbound receipt was recorded but its acknowledgement could not be sent',
+            level=ch_mod.TROUBLE,
+            say='receipt-ack for grant {grant} did not reach {peer}; it will resend',
+            tags=('video', 'transit'),
+        ),
+        ch_mod.Channel(
+            'video_store_close_failed',
+            'A video store could not be closed at shutdown',
+            level=ch_mod.TROUBLE,
+            say='video store(s) would not close: {stores}',
+            tags=('video', 'storage'),
+        ),
+        ch_mod.Channel(
+            'video_not_announced',
+            'A stream started on a node with no HTTP face, so it was not announced',
+            level=ch_mod.NOTE,
+            say='stream {stream_id} started but not announced: this node has no http face',
+            tags=('video', 'stream'),
+        ),
+        ch_mod.Channel(
+            'video_stream_started',
+            'A live video stream genesis manifest was initialized',
+            level=ch_mod.INFO,
+            say='started live stream {stream_id} ({title})',
+            tags=('video', 'stream'),
+        ),
+        ch_mod.Channel(
+            'video_segment_ingested',
+            'A CMAF / LL-HLS video segment was packaged and logged',
+            level=ch_mod.INFO,
+            say='packaged segment #{seq} for stream {stream_id} ({size} bytes)',
+            tags=('video', 'segment'),
+        ),
+        ch_mod.Channel(
+            'video_transit_handover',
+            'Capacity shed triggered or released a Transit Reflector handover',
+            level=ch_mod.INFO,
+            say='stream {stream_id} transit handover {state}',
+            tags=('video', 'transit'),
+        ),
+        ch_mod.Channel(
+            'video_transit_settled',
+            'Bilateral transit debt was reduced via bartered network utility',
+            level=ch_mod.INFO,
+            say='settled {credited_bytes} transit bytes for peer {peer} via {utility_kind}',
+            tags=('video', 'accounting'),
+        ),
+    )
+
+    METRICS = (
+        mx_mod.Metric(
+            name='video_streams_started',
+            description='Live video streams initialized on this node.',
+            kind=mx_mod.COUNTER,
+            counts='video_stream_started',
+            tags=('video', 'stream'),
+        ),
+        mx_mod.Metric(
+            name='video_segments_ingested',
+            description='Video segments packaged into RhioBaoTree and P2PandaLogStore.',
+            kind=mx_mod.COUNTER,
+            counts='video_segment_ingested',
+            tags=('video', 'segment'),
+        ),
+        mx_mod.Metric(
+            name='video_transit_handovers',
+            description='Automated capacity shed handovers to Transit Reflectors.',
+            kind=mx_mod.COUNTER,
+            counts='video_transit_handover',
+            tags=('video', 'transit'),
+        ),
+        mx_mod.Metric(
+            name='video_transit_settlements',
+            description='Bartered utility settlements applied to transit debt.',
+            kind=mx_mod.COUNTER,
+            counts='video_transit_settled',
+            tags=('video', 'accounting'),
+        ),
+    )
+
+    NEEDS = (
+        Need('blobs', 'stores.blobs'),
+        Need('ks'),
+        Need('clock'),
+        Need('dir'),
+        Need('cfg', block=VideoConfig),
+        Need('host'),
+        Need('transport'),
+        Need('capacity', late=True),
+        Need('strain', late=True),
+        Need('paid_fetch', 'paidfetch', late=True),
+        # Barter counterparties, read on the tick. These were soft reaches
+        # through the node object, which the contract refuses: a coupling
+        # nothing declares is one nobody can see.
+        Need('blob_replication', late=True),
+        Need('compute', late=True),
+        Need('dvm', late=True),
+        Need('events'),
+    )
+
+    COMMANDS = (
+        Command(
+            key='start_stream',
+            name='Start Video Stream',
+            description='initialize a new live video stream and append its p2panda genesis manifest',
+            tags=('video', 'stream'),
+            parameters=(
+                Parameter(key='stream_id', name='stream_id', description='unique stream identifier', type=str, default='', required=True),
+                Parameter(key='title', name='title', description='human-readable stream title', type=str, default='Live Stream', required=False),
+                Parameter(key='price_msat_per_mb', name='price_msat_per_mb', description='commercial price per MB in msat', type=int, default=0, required=False),
+                Parameter(key='account_fee_msat', name='account_fee_msat', description='creator P2PK fee in msat', type=int, default=0, required=False),
+            ),
+            permission='video/start_stream',
+            run='start_stream_cmd',
+            reply='{stream_id, broadcaster, title, genesis_op_id, seq_num, announcements}',
+        ),
+        Command(
+            key='status',
+            name='Video & Transit Status',
+            description='inspect active video streams, reflector sessions, and bilateral transit debt',
+            tags=('video', 'status'),
+            parameters=(
+                Parameter(key='peer', name='peer', description='optional peer pubkey filter', type=str, default='', required=False),
+            ),
+            permission='video/status',
+            run='status_cmd',
+            reply='{streams, active_streams, reflector_sessions, debts, utility_credits}',
+        ),
+        Command(
+            key='settle',
+            name='Settle Transit Debt via Barter',
+            description='credit bartered network utility (blob_shoring, verified_compute, dvm, mediation) against transit debt',
+            tags=('video', 'settle'),
+            parameters=(
+                Parameter(key='peer', name='peer', description='broadcaster peer pubkey', type=str, default='', required=True),
+                Parameter(key='utility_kind', name='utility_kind', description='blob_shoring, verified_compute, dvm, or mediation', type=str, default='blob_shoring', required=True),
+                Parameter(key='units', name='units', description='number of utility units to credit', type=int, default=1, required=True),
+                Parameter(key='grant_id', name='grant_id', description='optional grant_id to credit against', type=str, default='', required=False),
+            ),
+            permission='video/settle',
+            run='settle_cmd',
+            reply='BarterCreditRecord with updated debt status',
+        ),
+        Command(
+            key='ingest_segment',
+            name='Ingest Video Segment',
+            description='package a base64-encoded CMAF/LL-HLS media segment into RhioBaoTree and P2PandaLogStore',
+            tags=('video', 'ingest'),
+            parameters=(
+                Parameter(key='stream_id', name='stream_id', description='target stream identifier', type=str, default='', required=True),
+                Parameter(key='data_b64', name='data_b64', description='base64-encoded segment bytes', type=str, default='', required=True),
+                Parameter(key='duration_ms', name='duration_ms', description='segment duration in milliseconds', type=int, default=2000, required=False),
+                Parameter(key='is_keyframe', name='is_keyframe', description='whether segment begins with an IDR keyframe', type=bool, default=True, required=False),
+                Parameter(key='is_audio_only', name='is_audio_only', description='whether segment is an audio-only track', type=bool, default=False, required=False),
+            ),
+            permission='video/ingest_segment',
+            run='ingest_segment_cmd',
+            reply='{stream_id, segment_index, sha256, tree_root, cid, size, op_id, seq_num}',
+        ),
+        Command(
+            key='solicit_transit',
+            name='Solicit Supernode Transit Reflection',
+            description='build and optionally send a transit-solicitation for a stream',
+            tags=('video', 'transit'),
+            parameters=(
+                Parameter(key='stream_id', name='stream_id', description='stream identifier to offload', type=str, default='', required=True),
+                Parameter(key='peer', name='peer', description='optional target supernode pubkey', type=str, default='', required=False),
+                Parameter(key='mode', name='mode', description='pro-bono-barter or commercial-paid', type=str, default='pro-bono-barter', required=False),
+                Parameter(key='expected_bitrate_kbps', name='expected_bitrate_kbps', description='expected stream bitrate in kbps', type=int, default=2500, required=False),
+            ),
+            permission='video/solicit_transit',
+            run='solicit_transit_cmd',
+            reply='{solicitation, sent}',
+        ),
+    )
+
+    def __init__(
+        self,
+        blobs: Optional[Any] = None,
+        ks: Optional[Any] = None,
+        clock: Optional[Callable[[], int]] = None,
+        dir: Optional[str] = None,
+        cfg: Optional[VideoConfig] = None,
+        host: Optional[Any] = None,
+        capacity: Optional[Any] = None,
+        strain: Optional[Any] = None,
+        paid_fetch: Optional[Any] = None,
+        transport: Optional[Any] = None,
+        events: Optional[Any] = None,
+        node: Optional[Any] = None,
+    ) -> None:
+        super().__init__(node, clock)
+        # Backing fields for the write-through properties below. Set before
+        # anything that could trigger a setter.
+        self._strain: Optional[Any] = None
+        self._paid_fetch: Optional[Any] = None
+        self._events: Optional[Any] = None
+        self.blobs = blobs
+        self.ks = ks
+        self.dir = dir
+        self.cfg: VideoConfig = cfg or VideoConfig()
+        self.host = host
+        self.capacity = capacity
+        self.strain = strain
+        self.paid_fetch = paid_fetch
+        self.transport = transport
+        self.events = events
+        # Late needs: the registry sets these after assembly. Declared here so
+        # a bare suite that builds this compartment alone still has them.
+        self.blob_replication: Optional[Any] = None
+        self.compute: Optional[Any] = None
+        self.dvm: Optional[Any] = None
+
+        if dir:
+            os.makedirs(dir, exist_ok=True)
+            ledger_db = os.path.join(dir, 'video_transit_v1.db')
+            p2p_db = os.path.join(dir, 'p2panda_v1.db')
+            rhio_db = os.path.join(dir, 'rhio_v1.db')
+            rhio_cas: Optional[str] = os.path.join(dir, 'rhio_cas')
+        else:
+            ledger_db = ':memory:'
+            p2p_db = ':memory:'
+            rhio_db = ':memory:'
+            rhio_cas = None
+
+        self.p2panda_store = P2PandaLogStore(p2p_db)
+        self.rhio_store = RhioBlobSync(rhio_db, cas_dir=rhio_cas)
+        # One clock for the whole subsystem: the compartment's, so a suite that
+        # moves time moves the ledger, packager, reflector and bridges with it.
+        self.ledger = TransitLedgerStore(ledger_db, clock=self.clock)
+        self.packager = VideoStreamPackager(
+            p2panda_store=self.p2panda_store,
+            rhio_store=self.rhio_store,
+            blob_store=self.blobs,
+            strain_ledger=self.strain,
+            paid_fetch=self.paid_fetch,
+            clock=self.clock,
+        )
+        self.reflector = TransitReflectorManager(
+            ledger=self.ledger,
+            packager=self.packager,
+            ring_capacity=self.cfg.ring_capacity,
+            strain_ledger=self.strain,
+            clock=self.clock,
+        )
+        node_sk = getattr(self.ks, 'node_sk', None)
+        node_pk = getattr(self.ks, 'node_pk', None) or ('b' * 64)
+        self.ingest_bridge = LiveMediaIngestBridge(
+            packager=self.packager,
+            reflector=self.reflector,
+            broadcaster_sk=node_sk,
+            broadcaster_pk=node_pk,
+            clock=self.clock,
+        )
+        self.barter_bridge = BarterSettlementBridge(
+            ledger=self.ledger,
+            creditor_pk=node_pk,
+            blob_store=self.blobs,
+            rhio_store=self.rhio_store,
+            on_settled=self._on_auto_barter_settled,
+            clock=self.clock,
+        )
+        if events is not None:
+            self.barter_bridge.attach_event_bus(events)
+        self._received_grants: dict[str, TransitGrantBody] = {}  # not a store: active per-stream transit grants
+
+    def _on_auto_barter_settled(self, res: BarterHookResult) -> None:
+        now_val = self.clock()
+        self.recent_events.append((
+            'auto-barter-settled',
+            res['debtor'],
+            res['utility_kind'],
+            res['equivalent_transit_bytes'],
+            now_val,
+        ))
+        self.say(
+            'video_transit_settled',
+            credited_bytes=res['equivalent_transit_bytes'],
+            peer=res['debtor'][:16],
+            utility_kind=res['utility_kind'],
+        )
+
+    def mount_ingress(self, host: Any) -> None:
+        """Mount HTTP live playlist, segment, HTTP push ingest, and web player routes onto ProtocolHost."""
+        self.host = host
+        if host is not None:
+            self.packager.mount_ingress(host)
+            self.ingest_bridge.mount_http_ingest(host)
+            mount_player_routes(host, self.packager, reflector=self.reflector, ledger=self.ledger)
+
+    # The registry resolves a `late=True` need with setattr, so these setters
+    # are where a late value reaches the objects that actually hold it. This is
+    # what `bind_runtime` did when NodeApp built this compartment by hand, and
+    # what a `wire()` override would do - which check-needs refuses, rightly:
+    # one declared way in, not three.
+    @property
+    def strain(self) -> Optional[Any]:
+        return self._strain
+
+    @strain.setter
+    def strain(self, value: Optional[Any]) -> None:
+        self._strain = value
+        if value is not None:
+            if getattr(self, 'packager', None) is not None:
+                self.packager.strain_ledger = value
+            if getattr(self, 'reflector', None) is not None:
+                self.reflector.strain_ledger = value
+
+    @property
+    def paid_fetch(self) -> Optional[Any]:
+        return self._paid_fetch
+
+    @paid_fetch.setter
+    def paid_fetch(self, value: Optional[Any]) -> None:
+        self._paid_fetch = value
+        if value is not None and getattr(self, 'packager', None) is not None:
+            self.packager.paid_fetch = value
+
+    @property
+    def events(self) -> Optional[Any]:
+        return self._events
+
+    @events.setter
+    def events(self, value: Optional[Any]) -> None:
+        self._events = value
+        if value is not None and getattr(self, 'barter_bridge', None) is not None:
+            self.barter_bridge.attach_event_bus(value)
+
+    def start(self) -> None:
+        if self.host is not None:
+            self.mount_ingress(self.host)
+
+    def stop(self) -> None:
+        super().stop()
+
+    def close(self) -> None:
+        """Close the three stores, counting and saying any that will not.
+
+        This was `except Exception: pass` over all three, which is audit L5
+        verbatim - the finding that `NodeApp.close()` told nobody when a store
+        could not close. A store that will not close is a locked database or a
+        disk full at commit, and at restart it is exactly the one an operator
+        needs told about. The exception is still caught, because one store
+        failing must not leave the other two open.
+        """
+        failed: list[str] = []
+        for name in ('ledger', 'p2panda_store', 'rhio_store'):
+            st_obj = getattr(self, name, None)
+            if st_obj is None:
+                continue
+            try:
+                st_obj.close()
+            except Exception as e:
+                failed.append('%s: %s' % (name, e))
+                self.refusals.refuse('store', 'close failed', name,
+                                     {'error': '%s: %s' % (type(e).__name__, e)})
+        if failed:
+            self.say('video_store_close_failed', stores=', '.join(failed))
+
+    def state(self) -> Mapping[str, Any]:
+        return self.status_cmd()
+
+    def tick(self, now: Optional[int] = None) -> list[tuple[Any, ...]]:
+        """Evaluate capacity shed handovers and reconcile cross-compartment barter proofs."""
+        now_val = self.clock() if now is None else int(now)
+        did: list[tuple[Any, ...]] = []
+        if any((self.blob_replication, self.compute, self.dvm)):
+            settled = self.barter_bridge.reconcile_compartments(
+                blob_replication=self.blob_replication,
+                compute=self.compute,
+                dvm=self.dvm,
+                now=now_val,
+            )
+            for item in settled:
+                did.append(('video-barter-settled', item['debtor'], item['utility_kind'], item['equivalent_transit_bytes']))
+        if self.capacity is None or not self._received_grants:
+            return did
+        sk_hex = getattr(self.ks, 'node_sk', None)
+        if not sk_hex:
+            return did
+        for stream_id, grant in list(self._received_grants.items()):
+            prev_active = self.reflector.is_handover_active(stream_id)
+            window_epoch = now_val // 600
+            new_state = self.reflector.evaluate_capacity_handover(
+                self.capacity,
+                stream_id=stream_id,
+                standby_grant=grant,
+                window=window_epoch,
+                sk_hex=sk_hex,
+                now=now_val,
+            )
+            now_active = self.reflector.is_handover_active(stream_id)
+            if now_active != prev_active:
+                if new_state == 'released' and self.transport is not None:
+                    rel_pair = getattr(self.reflector, '_last_release', {}).get(stream_id)
+                    operator_peer = str(grant.get('operator', ''))
+                    sender_pk = getattr(self.ks, 'node_pk', '') or str(grant.get('broadcaster', ''))
+                    if rel_pair is not None and operator_peer:
+                        rec_msg, close_msg = rel_pair
+                        try:
+                            env_r = make_transit_envelope(
+                                TYPE_TRANSIT_RECEIPT, rec_msg, sender=sender_pk, recipient=operator_peer, created_time=now_val
+                            )
+                            self.transport.send(env_r, operator_peer, stored=False)
+                            env_c = make_transit_envelope(
+                                TYPE_TRANSIT_CLOSE, close_msg, sender=sender_pk, recipient=operator_peer, created_time=now_val
+                            )
+                            self.transport.send(env_c, operator_peer, stored=False)
+                        except Exception as e:
+                            self.refusals.refuse(
+                                'close',
+                                'not delivered',
+                                operator_peer,
+                                {'grant': grant['grant_id'], 'error': '%s: %s' % (type(e).__name__, e)},
+                            )
+                self.recent_events.append(('handover', stream_id, new_state, now_val))
+                self.say('video_transit_handover', stream_id=stream_id, state=new_state)
+                did.append(('video-handover', stream_id, new_state))
+        return did
+
+    # ---- Wire Protocol Handler (video-transit/1.0) --------------------------
+
+    def handle(self, inbound: Any) -> Optional[tuple[Any, ...]]:
+        """Handle inbound `https://fleetmesh.org/video-transit/1.0/*` messages."""
+        msg = getattr(inbound, 'message', inbound)
+        sender = getattr(inbound, 'sender', '')
+        if not isinstance(msg, Mapping):
+            return None
+        msg_type = str(msg.get('type', ''))
+        body = msg.get('body')
+        if not isinstance(body, Mapping):
+            return None
+        now_val = self.clock()
+
+        if msg_type == TYPE_TRANSIT_SOLICITATION:
+            err = check_solicitation(body)
+            if err:
+                self.refusals.refuse('solicitation', err, sender, {})
+                return ('refused', 'transit-solicitation', err)
+            sol_body: Any = body
+            op_pk = getattr(self.ks, 'node_pk', '') or sol_body['broadcaster']
+            op_sk = getattr(self.ks, 'node_sk', None)
+            if not op_sk:
+                self.refusals.refuse('solicitation', 'no signing key', sender, {})
+                return ('refused', 'transit-solicitation', 'no signing key')
+            face_url = ''
+            if self.host is not None and hasattr(self.host, 'http_url'):
+                face_url = f"{self.host.http_url}/video/live/{sol_body['stream_id']}"
+            if not face_url:
+                # A grant names where to fetch from. Without an HTTP face there
+                # is nowhere, and inventing `node.fleetmesh.local` published a
+                # host no viewer can reach - and one that mDNS may resolve to
+                # something else entirely on a LAN. Refuse, as the branch above
+                # refuses a missing signing key.
+                self.refusals.refuse('solicitation', 'no http face to reflect from', sender, {})
+                return ('refused', 'transit-solicitation', 'no http face to reflect from')
+            endpoints = [face_url]
+            grant = self.reflector.accept_solicitation(
+                sol_body,
+                operator_pk=op_pk,
+                operator_sk=op_sk,
+                reflector_endpoints=endpoints,
+                max_unsettled_transit_bytes=self.cfg.default_debt_ceiling_bytes,
+                now=now_val,
+            )
+            delivered = True
+            if self.transport is not None and sender:
+                try:
+                    env = make_transit_envelope(TYPE_TRANSIT_GRANT, grant, sender=op_pk, recipient=sender, created_time=now_val)
+                    self.transport.send(env, sender, stored=False)
+                except Exception as e:
+                    # The grant is signed and already in the ledger
+                    # (Record-Then-Answer), so it is not withdrawn - but the
+                    # peer does not have it. Reporting 'accepted' and saying
+                    # nothing left the ledger claiming a grant the other side
+                    # had never seen, with nothing for an operator to act on.
+                    delivered = False
+                    self.refusals.refuse('grant', 'not delivered', sender,
+                                         {'grant': grant['grant_id'],
+                                          'error': '%s: %s' % (type(e).__name__, e)})
+                    self.say('video_grant_undelivered', grant=grant['grant_id'][:16],
+                             peer=(sender or '')[:16])
+            self.recent_events.append(
+                ('solicitation-accepted' if delivered else 'solicitation-accepted-undelivered',
+                 sol_body['stream_id'], grant['grant_id'], now_val))
+            return ('transit-solicitation', sender, sol_body['stream_id'])
+
+        if msg_type == TYPE_TRANSIT_GRANT:
+            err = check_grant(body)
+            if err:
+                self.refusals.refuse('grant', err, sender, {})
+                return ('refused', 'transit-grant', err)
+            grant_body: Any = body
+            if sender and str(grant_body.get('operator', '')).lower() != sender.lower():
+                self.refusals.refuse('grant', 'operator does not match sender', sender, {})
+                return ('refused', 'transit-grant', 'operator does not match sender')
+            my_pk = getattr(self.ks, 'node_pk', None)
+            if my_pk and str(grant_body.get('broadcaster', '')).lower() != str(my_pk).lower():
+                self.refusals.refuse('grant', 'grant broadcaster is not this node', sender, {})
+                return ('refused', 'transit-grant', 'grant broadcaster is not this node')
+            try:
+                self.ledger.save_grant(grant_body, status='live')
+            except ValueError as e:
+                self.refusals.refuse('grant', str(e), sender, {})
+                return ('refused', 'transit-grant', str(e))
+            self._received_grants[grant_body['stream_id']] = grant_body
+            self.recent_events.append(('grant-received', grant_body['stream_id'], grant_body['grant_id'], now_val))
+            return ('transit-grant', sender, grant_body['grant_id'])
+
+        if msg_type == TYPE_TRANSIT_RECEIPT:
+            err = check_transit_receipt(body)
+            if err:
+                self.refusals.refuse('receipt', err, sender, {})
+                return ('refused', 'transit-receipt', err)
+            rec_body: Any = body
+            signer_pk = sender or getattr(self.ks, 'node_pk', '')
+            ack = self.ledger.on_inbound_receipt(signer_pk, rec_body, now=now_val)
+            if self.transport is not None and sender:
+                try:
+                    op_pk = getattr(self.ks, 'node_pk', '')
+                    env = make_transit_envelope(TYPE_TRANSIT_RECEIPT_ACK, ack, sender=op_pk, recipient=sender, created_time=now_val)
+                    self.transport.send(env, sender, stored=False)
+                except Exception as e:
+                    # The receipt was recorded; the acknowledgement was not
+                    # sent. The peer cannot tell its receipt landed, so it
+                    # resends or the chain stalls - and this said nothing.
+                    self.refusals.refuse('receipt-ack', 'not delivered', sender,
+                                         {'grant': rec_body['grant'],
+                                          'error': '%s: %s' % (type(e).__name__, e)})
+                    self.say('video_ack_undelivered', grant=str(rec_body['grant'])[:16],
+                             peer=(sender or '')[:16])
+            self.recent_events.append(('receipt', rec_body['grant'], ack['status'], now_val))
+            return ('transit-receipt', sender, ack['status'])
+
+        if msg_type == TYPE_TRANSIT_CLOSE:
+            err = check_transit_close(body)
+            if err:
+                self.refusals.refuse('close', err, sender, {})
+                return ('refused', 'transit-close', err)
+            close_body: Any = body
+            self.ledger.on_inbound_close(close_body, now=now_val)
+            self.recent_events.append(('close', close_body['stream_id'], close_body['grant'], now_val))
+            return ('transit-close', sender, close_body['grant'])
+
+        if msg_type == TYPE_TRANSIT_RECEIPT_ACK:
+            err = check_transit_receipt_ack(body)
+            if err:
+                self.refusals.refuse('receipt-ack', err, sender, {})
+                return ('refused', 'transit-receipt-ack', err)
+            ack_body: Any = body
+            self.recent_events.append(('receipt-ack', ack_body['grant'], ack_body['status'], now_val))
+            return ('transit-receipt-ack', sender, ack_body['status'])
+
+        return None
+
+    # ---- Control-Socket Command Handlers ------------------------------------
+
+    def start_stream_cmd(self, args: Mapping[str, Any]) -> Mapping[str, Any]:
+        stream_id = str(args.get('stream_id') or '').strip()
+        if not stream_id:
+            raise ValueError('stream_id is required')
+        title = str(args.get('title') or 'Live Stream')
+        price_msat = int(args.get('price_msat_per_mb') or 0)
+        account_fee = int(args.get('account_fee_msat') or 0)
+        broadcaster = getattr(self.ks, 'node_pk', None) or ('a' * 64)
+        now_val = self.clock()
+
+        genesis, op = self.packager.create_stream(
+            stream_id=stream_id,
+            broadcaster=broadcaster,
+            title=title,
+            price_msat_per_mb=price_msat,
+            account_fee_msat=account_fee,
+            now=now_val,
+        )
+        # The announcement carries the manifest URL to six protocols. With no
+        # HTTP face there is no URL to carry, and the fabricated fallback meant
+        # a faceless node advertised `node.fleetmesh.local` to every network it
+        # spoke. The stream still starts; it is simply not announced.
+        base_url = (
+            self.host.http_url
+            if (self.host is not None and hasattr(self.host, 'http_url'))
+            else ''
+        )
+        if base_url:
+            announcements = self.packager.announce_stream(stream_id, base_url=base_url)
+        else:
+            announcements = {}
+            self.say('video_not_announced', stream_id=stream_id)
+        self.recent_events.append(('stream-started', stream_id, op.id, now_val))
+        self.say('video_stream_started', stream_id=stream_id, title=title)
+        return {
+            'status': 'started',
+            'stream_id': genesis.stream_id,
+            'broadcaster': genesis.broadcaster,
+            'title': genesis.title,
+            'genesis_op_id': op.id,
+            'seq_num': op.seq_num,
+            'announcements': sorted(announcements.keys()),
+        }
+
+    TROUBLE_WINDOW: int = 900
+
+    def trouble(self) -> list[str]:
+        """What an operator has to act on, not merely what state() records.
+
+        The subsystem had no trouble() at all, so every condition below was
+        visible only to someone who read `video status` and knew to look -
+        which is audit I13 exactly: the deaf inbox was in state() and not in
+        trouble(), so health and `meshctl watch` stayed green while live wraps
+        were being lost.
+        """
+        out: list[str] = []
+        if self.packager.unpublished:
+            out.append('%d video segment(s) are in the manifest and were never published '
+                       'to the blob server, so no viewer can fetch them: %s'
+                       % (self.packager.unpublished, self.packager.last_publish_error))
+        recent = self.refusals.within(self.TROUBLE_WINDOW, self.clock())
+        undelivered = [r for r in recent if r.detail.get('grant') and 'not delivered' in r.why]
+        if undelivered:
+            out.append('%d transit message(s) recorded in the ledger never reached the peer '
+                       'in the last %ds: %s'
+                       % (len(undelivered), self.TROUBLE_WINDOW,
+                          '; '.join(sorted({(r.subject or '?')[:16] for r in undelivered}))))
+        if self.barter_bridge.skipped:
+            out.append('barter reconciliation could not credit %s: %s'
+                       % (', '.join('%d %s' % (n, k) for k, n in
+                                    sorted(self.barter_bridge.skipped.items())),
+                          '; '.join('%s: %s' % (k, v) for k, v in
+                                    sorted(self.barter_bridge.last_skip.items()))))
+        return out
+
+    def status_cmd(self, args: Optional[Mapping[str, Any]] = None) -> Mapping[str, Any]:
+        peer_filter = str((args or {}).get('peer') or '').strip() or None
+        with self.packager._lock:
+            streams = [
+                {
+                    'stream_id': sid,
+                    'broadcaster': st_rec['genesis'].broadcaster,
+                    'title': st_rec['genesis'].title,
+                    'segments_count': len(st_rec['segments']),
+                    'latest_seq': st_rec['latest_seq'],
+                    'transit_endpoints': list(st_rec['transit_endpoints']),
+                    'handover_active': self.reflector.is_handover_active(sid),
+                }
+                for sid, st_rec in self.packager._streams.items()
+            ]
+        summary = self.ledger.summary()
+        debts = (
+            [self.ledger.debt_summary(peer_filter)]
+            if peer_filter
+            else summary['debts']
+        )
+        # What the subsystem could not do, where an operator reads it. Each of
+        # these was `except Exception: pass` and so was invisible: segments in
+        # the manifest no viewer can fetch, credits a peer earned and never
+        # got, and frames a transport would not take. Present only when
+        # non-zero, so a healthy node's status stays short.
+        return {
+            'streams': streams,
+            'active_streams': len(streams),
+            'reflector_sessions': self.reflector.active_sessions(),
+            'debts': debts,
+            'utility_credits': summary['utility_credits'],
+            **({'unpublished_segments': self.packager.unpublished,
+                'last_publish_error': self.packager.last_publish_error}
+               if self.packager.unpublished else {}),
+            **({'frames_dropped': dict(self.reflector.frames_dropped)}
+               if self.reflector.frames_dropped else {}),
+            **({'barter_skipped': dict(self.barter_bridge.skipped),
+                'barter_last_skip': dict(self.barter_bridge.last_skip)}
+               if self.barter_bridge.skipped else {}),
+        }
+
+    def settle_cmd(self, args: Mapping[str, Any]) -> Mapping[str, Any]:
+        peer = str(args.get('peer') or '').strip()
+        if not peer:
+            raise ValueError('peer is required')
+        utility_kind: Any = str(args.get('utility_kind') or 'blob_shoring').strip()
+        units = int(args.get('units') or 1)
+        grant_id = str(args.get('grant_id') or '').strip() or 'manual-proof'
+        creditor = getattr(self.ks, 'node_pk', None) or ('b' * 64)
+        now_val = self.clock()
+        rec = self.ledger.credit_barter(
+            debtor=peer,
+            creditor=creditor,
+            utility_kind=utility_kind,
+            units=units,
+            proof_ref=grant_id,
+            now=now_val,
+        )
+        debt_after = self.ledger.debt_summary(peer)
+        credited_bytes = int(rec['equivalent_transit_bytes'])
+        self.recent_events.append(('settled', peer, utility_kind, credited_bytes, now_val))
+        self.say(
+            'video_transit_settled',
+            credited_bytes=credited_bytes,
+            peer=peer[:16],
+            utility_kind=utility_kind,
+        )
+        return {
+            'credit': rec,
+            'credited_bytes': credited_bytes,
+            'peer': peer,
+            'utility_kind': utility_kind,
+            'units': units,
+            'debt_after': debt_after,
+        }
+
+    def ingest_segment_cmd(self, args: Mapping[str, Any]) -> Mapping[str, Any]:
+        stream_id = str(args.get('stream_id') or '').strip()
+        data_b64 = str(args.get('data_b64') or '').strip()
+        if not stream_id or not data_b64:
+            raise ValueError('stream_id and data_b64 are required')
+        segment_bytes = base64.b64decode(data_b64)
+        duration_ms = int(args.get('duration_ms') or 2000)
+        is_keyframe = bool(args.get('is_keyframe', True))
+        is_audio_only = bool(args.get('is_audio_only', False))
+        now_val = self.clock()
+
+        entry, op, addr = self.packager.ingest_segment(
+            stream_id=stream_id,
+            segment_data=segment_bytes,
+            duration_ms=duration_ms,
+            is_keyframe=is_keyframe,
+            is_audio_only=is_audio_only,
+            now=now_val,
+        )
+        self.recent_events.append(('segment-ingested', stream_id, entry.segment_index, addr['size'], now_val))
+        self.say('video_segment_ingested', seq=entry.segment_index, stream_id=stream_id, size=addr['size'])
+        return {
+            'stream_id': stream_id,
+            'segment_index': entry.segment_index,
+            'sha256': addr['sha256'],
+            'tree_root': addr['tree_root'],
+            'cid': addr['cid'],
+            'size': addr['size'],
+            'op_id': op.id,
+            'seq_num': op.seq_num,
+        }
+
+    def solicit_transit_cmd(self, args: Mapping[str, Any]) -> Mapping[str, Any]:
+        stream_id = str(args.get('stream_id') or '').strip()
+        if not stream_id:
+            raise ValueError('stream_id is required')
+        peer = str(args.get('peer') or '').strip()
+        raw_mode = str(args.get('mode') or 'pro-bono').strip()
+        mode: Any = 'commercial' if 'commercial' in raw_mode else 'pro-bono'
+        bitrate = int(args.get('expected_bitrate_kbps') or 2500)
+        broadcaster = getattr(self.ks, 'node_pk', None) or ('a' * 64)
+        now_val = self.clock()
+
+        sol = self.reflector.build_solicitation(
+            stream_id=stream_id,
+            broadcaster=broadcaster,
+            mode=mode,
+            bitrate_kbps=bitrate,
+            now=now_val,
+        )
+        sent = False
+        if peer and self.transport is not None:
+            try:
+                env = make_transit_envelope(
+                    TYPE_TRANSIT_SOLICITATION,
+                    sol,
+                    sender=broadcaster,
+                    recipient=peer,
+                    created_time=now_val,
+                )
+                self.transport.send(env, peer, stored=False)
+                sent = True
+            except Exception:
+                sent = False
+        return {'solicitation': sol, 'sent': sent}
+
+
+__all__ = [
+    'VideoConfig',
+    'VideoTransitCompartment',
+]