fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/video/packager.py

@@ -0,0 +1,847 @@
+"""Live CMAF / LL-HLS Packager, p2panda Manifest Engine & RhioBaoTree Verification (Phase 2).
+
+Stores video segments across BlobStore and RhioBlobSync with 1024-byte chunked
+Bao Merkle tree roots, appends cryptographic manifest operations to P2PandaLogStore,
+renders dynamic HLS/LL-HLS `.m3u8` playlists, projects stream announcements across
+all 6 protocols via ProtocolTranslator, and enforces commercial settlement via
+PaidFetch dual-item HTTP 402 or CrossProtocolSettlementGateway token buckets.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import threading
+import time
+import urllib.parse
+from typing import Any, Callable, Mapping, Optional, Sequence, TypedDict
+
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+from fleetmesh_core.identity.cid import sha256_to_cid
+from fleetmesh_core.wire.cbor import cbor_decode, cbor_encode
+from fleetmesh_core.wire.interfaces import ProtocolHostRouter
+from fleetmesh_core.wire.p2panda import P2PandaOperation, validate_operation_chain
+from fleetmesh_core.wire.video_transit import (
+    VideoSegmentEntry,
+    VideoStreamGenesis,
+)
+from node.planes.services.gateway.settle import CrossProtocolSettlementGateway
+from node.planes.services.gateway.translate import ProtocolTranslator, UnifiedPost
+from node.protocols.p2panda.identity import P2PandaIdentityAdapter
+from node.protocols.p2panda.store import P2PandaLogStore
+from node.protocols.rhio.store import RhioBaoTree, RhioBlobSync
+from node.planes.services.video.timed_segments import stamp_capture_time
+
+
+class StreamStateRecord(TypedDict):
+    stream_id: str
+    author_key: str
+    genesis: VideoStreamGenesis
+    segments: list[VideoSegmentEntry]
+    next_segment_index: int
+    transit_endpoints: list[str]
+    latest_op_id: str
+    latest_seq: int
+    verified_up_to: int
+
+
+class SegmentMultiAddress(TypedDict):
+    sha256: str
+    tree_root: str
+    cid: str
+    size: int
+    blossom_path: str
+    rhio_path: str
+    atproto_path: str
+
+
+class VideoStreamPackager:
+    """Packages CMAF / LL-HLS segments into content-addressed storage and
+    maintains tamper-evident p2panda manifest operation logs.
+    """
+
+    def __init__(
+        self,
+        p2panda_store: Optional[P2PandaLogStore] = None,
+        rhio_store: Optional[RhioBlobSync] = None,
+        blob_store: Optional[Any] = None,
+        identity: Optional[P2PandaIdentityAdapter] = None,
+        strain_ledger: Optional[Any] = None,
+        paid_fetch: Optional[Any] = None,
+        clock: Optional[Callable[[], int]] = None,
+        settlement_gateway: Optional[CrossProtocolSettlementGateway] = None,
+    ) -> None:
+        # An injected clock, defaulting to wall time, so a suite can move time
+        # at the boundaries this code decides on. The compartment passes its own.
+        self._clock: Callable[[], int] = clock or (lambda: int(time.time()))
+        # Segments stored in the CAS but not published to the blob server.
+        # This was `except Exception: pass`, so a segment was in the manifest
+        # and unfetchable by any viewer, and nothing said so.
+        self.unpublished: int = 0
+        self.last_publish_error: str = ''
+        self.p2panda_store = p2panda_store or P2PandaLogStore(':memory:')
+        self.rhio_store = rhio_store or RhioBlobSync(':memory:')
+        self.blob_store = blob_store
+        self.identity = identity or P2PandaIdentityAdapter(
+            private_key=ed25519.Ed25519PrivateKey.generate()
+        )
+        self.strain_ledger = strain_ledger
+        self.paid_fetch = paid_fetch
+        self.settlement_gateway = settlement_gateway
+
+        self._lock = threading.RLock()
+        self._streams: dict[str, StreamStateRecord] = {}
+        self._stream_keys: dict[str, ed25519.Ed25519PrivateKey] = {}
+
+    def _signing_key_for_stream(self, stream_id: str) -> tuple[ed25519.Ed25519PrivateKey, str]:
+        """Use a deterministic per-stream Ed25519 subkey so each stream has its own
+        independent p2panda operation log starting at seq_num == 0.
+        """
+        with self._lock:
+            if stream_id not in self._stream_keys:
+                priv_key = getattr(self.identity, '_private_key', None)
+                base_raw = (
+                    priv_key.private_bytes_raw()
+                    if priv_key is not None
+                    else self.identity.author_id.encode('utf-8')
+                )
+                seed = hashlib.sha256(base_raw + b':' + stream_id.encode('utf-8')).digest()
+                self._stream_keys[stream_id] = ed25519.Ed25519PrivateKey.from_private_bytes(seed)
+            sk = self._stream_keys[stream_id]
+            pk_hex = sk.public_key().public_bytes_raw().hex()
+            return sk, pk_hex
+
+    # ---- Storage & Multi-Protocol Content Addressing ------------------------
+
+    def store_segment_bytes(self, data: bytes) -> SegmentMultiAddress:
+        """Store a segment in RhioBlobSync (computing Bao Merkle tree root) and
+        mirror into BlobStore if attached. Returns all multi-protocol addresses.
+        """
+        sha256_hex, tree_root, size = self.rhio_store.store_blob(data)
+        if self.blob_store is not None and hasattr(self.blob_store, 'put'):
+            try:
+                self.blob_store.put(data)
+            except Exception as e:
+                # The segment is in the CAS and will be in the manifest, but
+                # no viewer can fetch it. Counted, not discarded.
+                self.unpublished += 1
+                self.last_publish_error = '%s: %s' % (type(e).__name__, e)
+        cid_str = sha256_to_cid(sha256_hex)
+        return {
+            'sha256': sha256_hex,
+            'tree_root': tree_root,
+            'cid': cid_str,
+            'size': size,
+            'blossom_path': f'/{sha256_hex}.m4s',
+            'rhio_path': f'/rhio/blobs/{sha256_hex}',
+            'atproto_path': f'/cid/{cid_str}',
+        }
+
+    def get_segment_bytes(self, sha256_hex: str) -> Optional[bytes]:
+        clean = sha256_hex.lower().strip()
+        if clean.endswith('.m4s'):
+            clean = clean[:-4]
+        elif clean.endswith('.mp4'):
+            clean = clean[:-4]
+        blob = self.rhio_store.get_blob(clean)
+        if blob is None and self.blob_store is not None and hasattr(self.blob_store, 'get'):
+            try:
+                blob = self.blob_store.get(clean)
+            except Exception:
+                blob = None
+        return blob
+
+    # ---- Bao 1024-Byte Sub-Segment Verification & Strain Penalty ------------
+
+    def compute_subchunk_leaves(self, segment_data: bytes) -> tuple[str, list[str]]:
+        """Return (tree_root, leaf_hashes_hex) for 1024-byte slices of a segment."""
+        root, leaves = RhioBaoTree.compute_tree(segment_data)
+        return root, [leaf.hex() for leaf in leaves]
+
+    def verify_subchunk(
+        self,
+        chunk_data: bytes,
+        expected_leaf_hash: str,
+        peer: Optional[str] = None,
+    ) -> bool:
+        """Verify a single 1024-byte slice against its expected Bao leaf hash.
+        Penalizes offending peer in StrainLedger immediately upon mismatch.
+        """
+        computed = hashlib.sha256(b'\x00' + chunk_data).hexdigest()
+        ok = computed.lower() == expected_leaf_hash.lower()
+        if not ok and peer and self.strain_ledger is not None:
+            if hasattr(self.strain_ledger, 'record'):
+                self.strain_ledger.record('corrupt_chunk', peer=peer)
+        return ok
+
+    def verify_segment(
+        self,
+        segment_data: bytes,
+        expected_tree_root: str,
+        peer: Optional[str] = None,
+    ) -> bool:
+        """Verify an entire segment against its Bao Merkle tree root."""
+        ok = RhioBaoTree.verify(segment_data, expected_tree_root)
+        if not ok and peer and self.strain_ledger is not None:
+            if hasattr(self.strain_ledger, 'record'):
+                self.strain_ledger.record('corrupt_chunk', peer=peer)
+        return ok
+
+    # ---- Stream Lifecycle & p2panda Manifest Operations ---------------------
+
+    def create_stream(
+        self,
+        stream_id: str,
+        broadcaster: str,
+        title: str = 'Live Stream',
+        codecs: Sequence[str] = ('avc1.64001f', 'mp4a.40.2'),
+        target_duration_ms: int = 2000,
+        part_target_duration_ms: int = 500,
+        init_segment: Optional[bytes] = None,
+        transit_endpoints: Sequence[str] = (),
+        price_msat_per_mb: int = 0,
+        account_fee_msat: int = 0,
+        now: Optional[int] = None,
+        log_key: Optional[ed25519.Ed25519PrivateKey] = None,
+        genesis_extensions: Optional[Mapping[str, Any]] = None,
+    ) -> tuple[VideoStreamGenesis, P2PandaOperation]:
+        """Initialize a new video stream and append its genesis operation (seq_num == 0)
+        to P2PandaLogStore.
+
+        `log_key` signs the stream's log in place of the node-derived subkey, so whoever holds
+        it (the broadcaster, a failover node) writes the same log. If that log already exists,
+        the stream resumes it instead of forking a second genesis; an ended log is refused.
+        `genesis_extensions` are merged into the genesis header, and so covered by its signature.
+        """
+        now_val = self._clock() if now is None else int(now)
+        init_sha256 = ''
+        init_tree_root = ''
+        init_size = 0
+        if init_segment is not None:
+            addr = self.store_segment_bytes(init_segment)
+            init_sha256 = addr['sha256']
+            init_tree_root = addr['tree_root']
+            init_size = addr['size']
+            if hasattr(self.rhio_store, 'claim_blob'):
+                self.rhio_store.claim_blob(
+                    init_tree_root,
+                    {'identity_id': broadcaster.lower(), 'did': f'did:nostr:{broadcaster.lower()}', 'handle': ''},
+                    sha256_hex=init_sha256,
+                    size=init_size,
+                    kind='video',
+                    mime_type='video/mp4',
+                    visibility='public',
+                )
+
+        genesis = VideoStreamGenesis(
+            stream_id=stream_id,
+            broadcaster=broadcaster.lower(),
+            title=title,
+            codecs=tuple(codecs),
+            target_duration_ms=int(target_duration_ms),
+            part_target_duration_ms=int(part_target_duration_ms),
+            init_sha256=init_sha256,
+            init_tree_root=init_tree_root,
+            init_size=init_size,
+            transit_endpoints=tuple(transit_endpoints),
+            price_msat_per_mb=int(price_msat_per_mb),
+            account_fee_msat=int(account_fee_msat),
+            created_at=now_val,
+        )
+
+        if log_key is not None:
+            with self._lock:
+                self._stream_keys[stream_id] = log_key
+        sk, pk_hex = self._signing_key_for_stream(stream_id)
+        latest = self.p2panda_store.get_latest_operation(pk_hex)
+        next_segment_index = 0
+        if latest is not None:
+            if (latest.header.extensions or {}).get('kind') == 'video.end':
+                raise ValueError(f'The log for stream {stream_id} has ended; start a new log key')
+            op = self.p2panda_store.get_operation_by_seq(pk_hex, 0) or latest
+            if latest.seq_num > 0 and latest.body:
+                try:
+                    last_body, _ = cbor_decode(latest.body)
+                    next_segment_index = int(last_body.get('segment_index', -1)) + 1
+                except Exception:
+                    next_segment_index = 0
+        else:
+            op = P2PandaOperation.create(
+                public_key=pk_hex,
+                body=genesis.to_cbor(),
+                seq_num=0,
+                backlink=None,
+                timestamp=now_val,
+                private_key=sk,
+                extensions={**dict(genesis_extensions or {}), 'stream_id': stream_id, 'kind': 'video.genesis'},
+            )
+            self.p2panda_store.append_operation(op, verify_chain=True)
+            latest = op
+
+        with self._lock:
+            self._streams[stream_id] = {
+                'stream_id': stream_id,
+                'author_key': pk_hex,
+                'genesis': genesis,
+                'segments': [],
+                'next_segment_index': next_segment_index,
+                'transit_endpoints': list(transit_endpoints),
+                'latest_op_id': latest.id,
+                'latest_seq': latest.seq_num,
+                'verified_up_to': latest.seq_num,
+            }
+        return genesis, op
+
+    def end_stream(self, stream_id: str, now: Optional[int] = None) -> P2PandaOperation:
+        """Append the signed `video.end` operation that closes the stream's log. Idempotent."""
+        with self._lock:
+            if stream_id not in self._streams:
+                raise KeyError(f"Unknown stream_id: {stream_id}")
+            state = self._streams[stream_id]
+            latest = self.p2panda_store.get_latest_operation(state['author_key'])
+            if latest is not None and (latest.header.extensions or {}).get('kind') == 'video.end':
+                return latest
+            now_val = max(self._clock() if now is None else int(now), state['genesis'].created_at)
+            if latest is not None:
+                now_val = max(now_val, latest.header.timestamp)
+            sk, pk_hex = self._signing_key_for_stream(stream_id)
+            next_seq = state['latest_seq'] + 1
+            body = cbor_encode({
+                'type': 'video.end', 'stream_id': stream_id,
+                'final_segment_seq': state['latest_seq'], 'ended_at': now_val,
+            }, canonical=True)
+            op = P2PandaOperation.create(
+                public_key=pk_hex,
+                body=body,
+                seq_num=next_seq,
+                backlink=state['latest_op_id'],
+                timestamp=now_val,
+                private_key=sk,
+                extensions={'stream_id': stream_id, 'kind': 'video.end'},
+            )
+            self.p2panda_store.append_operation(op, verify_chain=True)
+            state['latest_op_id'] = op.id
+            state['latest_seq'] = next_seq
+            state['verified_up_to'] = next_seq
+            return op
+
+    def checkpoint_and_prune(self, stream_id: str, keep_ops: int, *, min_batch: int = 256, now: Optional[int] = None) -> Optional[P2PandaOperation]:
+        """Bound a long-running log: keep its genesis and newest `keep_ops` ops, and prune the rest
+        behind a signed `video.checkpoint` op.
+
+        The checkpoint names the last pruned op (`through_op_id`, which the first kept op backlinks
+        to) and a sha256 over the pruned op ids, so the kept log still verifies as one signed chain
+        and anyone holding the pruned ops can check them against it. Runs only once `min_batch`
+        ops are prunable, so a busy stream does not checkpoint on every segment.
+        """
+        with self._lock:
+            if stream_id not in self._streams:
+                raise KeyError(f"Unknown stream_id: {stream_id}")
+            state = self._streams[stream_id]
+            author = state['author_key']
+            latest = self.p2panda_store.get_latest_operation(author)
+            if latest is None or (latest.header.extensions or {}).get('kind') == 'video.end':
+                return None
+            cut = state['latest_seq'] - max(1, int(keep_ops))
+            oldest = self.p2panda_store.get_log(author, from_seq=1, limit=1)
+            if not oldest or cut - oldest[0].seq_num + 1 < max(1, int(min_batch)):
+                return None
+            through = self.p2panda_store.get_operation_by_seq(author, cut)
+            if through is None:
+                return None
+            digest = hashlib.sha256()
+            seq = oldest[0].seq_num
+            while seq <= cut:
+                batch = self.p2panda_store.get_log(author, from_seq=seq, limit=500)
+                if not batch:
+                    break
+                for op in batch:
+                    if op.seq_num <= cut:
+                        digest.update(bytes.fromhex(op.id))
+                seq = batch[-1].seq_num + 1
+            now_val = max(self._clock() if now is None else int(now), latest.header.timestamp)
+            sk, pk_hex = self._signing_key_for_stream(stream_id)
+            body = cbor_encode({
+                'type': 'video.checkpoint', 'stream_id': stream_id, 'pruned_from_seq': oldest[0].seq_num,
+                'through_seq': cut, 'through_op_id': through.id, 'pruned_ops_sha256': digest.hexdigest(),
+            }, canonical=True)
+            op = P2PandaOperation.create(
+                public_key=pk_hex, body=body, seq_num=state['latest_seq'] + 1, backlink=state['latest_op_id'],
+                timestamp=now_val, private_key=sk, extensions={'stream_id': stream_id, 'kind': 'video.checkpoint'},
+            )
+            self.p2panda_store.append_operation(op, verify_chain=True)
+            state['latest_op_id'] = op.id
+            state['latest_seq'] = op.seq_num
+            state['verified_up_to'] = op.seq_num
+            with self.p2panda_store._lock:
+                with self.p2panda_store.transaction() as cur:
+                    cur.execute(
+                        'DELETE FROM p2panda_operations WHERE author = ? AND seq_num > 0 AND seq_num <= ?',
+                        (author.lower(), cut),
+                    )
+            return op
+
+    def export_stream_log(self, author_key: str, page: int = 500) -> list[dict[str, Any]]:
+        """Every operation in a stream log, oldest first, as `{op_id, header, body_hex}`."""
+        out: list[dict[str, Any]] = []
+        seq = 0
+        while True:
+            batch = self.p2panda_store.get_log(author_key, from_seq=seq, limit=page)
+            out.extend({'op_id': op.id, 'header': op.header.to_dict(), 'body_hex': op.body.hex() if op.body else ''} for op in batch)
+            if len(batch) < page:
+                return out
+            seq = batch[-1].seq_num + 1
+
+    def ingest_segment(
+        self,
+        stream_id: str,
+        segment_data: bytes,
+        duration_ms: int = 2000,
+        part_index: int = 0,
+        is_keyframe: bool = True,
+        is_audio_only: bool = False,
+        discontinuity: bool = False,
+        now: Optional[int] = None,
+        captured_us: Optional[int] = None,
+    ) -> tuple[VideoSegmentEntry, P2PandaOperation, SegmentMultiAddress]:
+        """Store a CMAF segment or LL-HLS part and append a signed operation
+        to the stream's p2panda manifest log.
+
+        A *captured* segment (`captured_us`: its capture time, UTC microseconds) is stored with that time
+        inside its own bytes (`timed_segments.stamp_capture_time`), so the fiber carries its moment and its
+        address covers it. Re-aired segments (playlists, ad breaks) are passed without one.
+        """
+        with self._lock:
+            if stream_id not in self._streams:
+                raise KeyError(f"Unknown stream_id: {stream_id}")
+            state = self._streams[stream_id]
+            now_val = max(self._clock() if now is None else int(now), state['genesis'].created_at)
+
+            if captured_us is not None:
+                segment_data = stamp_capture_time(segment_data, int(captured_us))
+            addr = self.store_segment_bytes(segment_data)
+            if hasattr(self.rhio_store, 'claim_blob'):
+                self.rhio_store.claim_blob(
+                    addr['tree_root'],
+                    {'identity_id': state['genesis'].broadcaster, 'did': f"did:nostr:{state['genesis'].broadcaster}", 'handle': ''},
+                    sha256_hex=addr['sha256'],
+                    size=addr['size'],
+                    kind='video',
+                    mime_type='video/mp4',
+                    visibility='public',
+                )
+            next_seg_idx = max(state['next_segment_index'], len(state['segments']))
+            if state['segments']:
+                next_seg_idx = max(next_seg_idx, state['segments'][-1].segment_index + 1)
+            seg_index = next_seg_idx
+            state['next_segment_index'] = seg_index + 1
+            entry = VideoSegmentEntry(
+                stream_id=stream_id,
+                segment_index=seg_index,
+                part_index=int(part_index),
+                duration_ms=int(duration_ms),
+                sha256=addr['sha256'],
+                tree_root=addr['tree_root'],
+                size=addr['size'],
+                is_keyframe=bool(is_keyframe),
+                is_audio_only=bool(is_audio_only),
+                discontinuity=bool(discontinuity),
+                transit_endpoints=tuple(state['transit_endpoints']),
+                published_at=now_val,
+            )
+
+            sk, pk_hex = self._signing_key_for_stream(stream_id)
+            next_seq = state['latest_seq'] + 1
+            op = P2PandaOperation.create(
+                public_key=pk_hex,
+                body=entry.to_cbor(),
+                seq_num=next_seq,
+                backlink=state['latest_op_id'],
+                timestamp=now_val,
+                private_key=sk,
+                extensions={'stream_id': stream_id, 'kind': 'video.segment'},
+            )
+            self.p2panda_store.append_operation(op, verify_chain=True)
+
+            state['segments'].append(entry)
+            state['latest_op_id'] = op.id
+            state['latest_seq'] = next_seq
+            state['verified_up_to'] = next_seq
+            return entry, op, addr
+
+    def update_transit_endpoints(
+        self,
+        stream_id: str,
+        transit_endpoints: Sequence[str],
+    ) -> list[str]:
+        """Update active Transit Reflector endpoints for a stream."""
+        with self._lock:
+            if stream_id not in self._streams:
+                raise KeyError(f"Unknown stream_id: {stream_id}")
+            self._streams[stream_id]['transit_endpoints'] = list(transit_endpoints)
+            return list(self._streams[stream_id]['transit_endpoints'])
+
+    def verify_stream_log(self, stream_id: str) -> tuple[bool, Optional[str], list[P2PandaOperation]]:
+        """Fetch all operations for `stream_id` from P2PandaLogStore and verify
+        the complete cryptographic operation chain.
+        """
+        with self._lock:
+            if stream_id not in self._streams:
+                raise KeyError(f"Unknown stream_id: {stream_id}")
+            author_key = self._streams[stream_id]['author_key']
+        ops = self.p2panda_store.get_log(author_key, from_seq=0, limit=10000)
+        ok, err = validate_operation_chain(ops)
+        if ok and ops:
+            with self._lock:
+                if stream_id in self._streams:
+                    self._streams[stream_id]['verified_up_to'] = ops[-1].seq_num
+        return ok, err, ops
+
+    def render_m3u8(
+        self,
+        stream_id: str,
+        window_size: int = 6,
+        audio_only: bool = False,
+    ) -> str:
+        """Dynamically render a standards-compliant HLS / LL-HLS `.m3u8` playlist
+        directly from verified operations in P2PandaLogStore.
+        """
+        with self._lock:
+            if stream_id not in self._streams:
+                raise KeyError(f"Unknown stream_id: {stream_id}")
+            state = self._streams[stream_id]
+            author_key = state['author_key']
+            verified_up_to = state['verified_up_to']
+            latest_seq = state['latest_seq']
+            active_endpoints = list(state['transit_endpoints'])
+            mem_genesis = state['genesis']
+            mem_segments = list(state['segments'])
+
+        store_seq = self.p2panda_store.get_latest_seq(author_key)
+        if store_seq >= 0 and store_seq == verified_up_to and verified_up_to == latest_seq:
+            genesis = mem_genesis
+            segments = [seg for seg in mem_segments if not audio_only or seg.is_audio_only]
+        else:
+            ok, err, ops = self.verify_stream_log(stream_id)
+            if not ok or not ops:
+                raise ValueError(f"Cannot render m3u8 for unverified stream {stream_id}: {err}")
+
+            genesis_op = ops[0]
+            if genesis_op.body is None:
+                raise ValueError("Genesis operation missing body")
+            genesis = VideoStreamGenesis.from_cbor(genesis_op.body)
+
+            segments = []
+            for op in ops[1:]:
+                if op.body is not None:
+                    decoded, _ = cbor_decode(op.body)
+                    if isinstance(decoded, Mapping) and decoded.get('type') == 'video.segment':
+                        seg = VideoSegmentEntry.from_dict(decoded)
+                        if not audio_only or seg.is_audio_only:
+                            segments.append(seg)
+
+        total_segs = len(segments)
+        start_idx = max(0, total_segs - window_size)
+        window_segs = segments[start_idx:]
+        media_seq = window_segs[0].segment_index if window_segs else 0
+        target_dur = max(1, math.ceil(genesis.target_duration_s))
+
+        lines = [
+            '#EXTM3U',
+            '#EXT-X-VERSION:7',
+            f'#EXT-X-TARGETDURATION:{target_dur}',
+            f'#EXT-X-MEDIA-SEQUENCE:{media_seq}',
+            f'#EXT-X-PART-INF:PART-TARGET={genesis.part_target_duration_s:.3f}',
+            f'#EXT-X-FLEETMESH-STREAM-ID:{genesis.stream_id}',
+            f'#EXT-X-FLEETMESH-BROADCASTER:{genesis.broadcaster}',
+        ]
+        init_sha = genesis.init_sha256 or mem_genesis.init_sha256
+        init_root = genesis.init_tree_root or mem_genesis.init_tree_root
+        if init_sha:
+            lines.append(
+                f'#EXT-X-MAP:URI="{init_sha}.mp4",BAO-ROOT="{init_root}"'
+            )
+        for ep in active_endpoints:
+            lines.append(f'#EXT-X-FLEETMESH-TRANSIT:URI="{ep}"')
+
+        for seg in window_segs:
+            if seg.discontinuity:
+                lines.append('#EXT-X-DISCONTINUITY')
+            lines.append(f'#EXT-X-FLEETMESH-BAO-ROOT:{seg.tree_root}')
+            ind_attr = ',INDEPENDENT=YES' if seg.is_keyframe else ''
+            lines.append(
+                f'#EXT-X-PART:DURATION={seg.duration_s:.3f},URI="{seg.sha256}.m4s"{ind_attr}'
+            )
+            lines.append(f'#EXTINF:{seg.duration_s:.3f},')
+            lines.append(f'{seg.sha256}.m4s')
+
+        return '\n'.join(lines) + '\n'
+
+    # ---- Cross-Protocol Stream Announcements --------------------------------
+
+    def announce_stream(
+        self,
+        stream_id: str,
+        base_url: str,
+        protocols: Sequence[str] = ('nostr', 'atproto', 'activitypub', 'ssb', 'p2panda', 'rhio'),
+    ) -> dict[str, Mapping[str, Any]]:
+        """Project a canonical stream announcement across all active protocols
+        via ProtocolTranslator.
+
+        `base_url` is required and has no default. It used to default to a
+        made-up `node.fleetmesh.local` address, so a node without an HTTP face
+        announced a manifest URL no viewer could reach to all six protocols -
+        and an mDNS `.local` name may resolve to another machine entirely on a
+        LAN. A caller with no face must not announce at all.
+        """
+        with self._lock:
+            if stream_id not in self._streams:
+                raise KeyError(f"Unknown stream_id: {stream_id}")
+            genesis = self._streams[stream_id]['genesis']
+
+        manifest_url = f"{base_url.rstrip('/')}/video/live/{stream_id}/index.m3u8"
+        parsed_host = urllib.parse.urlparse(base_url).hostname or ''
+        env_domain = os.environ.get('MESHTUBE_DOMAIN', '').strip().strip('/')
+        ap_domain = env_domain or (parsed_host if parsed_host not in ('0.0.0.0', '127.0.0.1', 'localhost', '') else 'meshtube.live')
+        post = UnifiedPost(
+            text=f"Live Broadcast: {genesis.title} ({manifest_url})",
+            author=genesis.broadcaster,
+            created_at=genesis.created_at,
+            attachments=[manifest_url],
+            tags=['live', 'video', 'fleetmesh'],
+            extra={'stream_id': stream_id},
+        )
+        announcements: dict[str, Mapping[str, Any]] = {}
+        for proto in protocols:
+            kwargs: dict[str, str] = {}
+            if proto == 'nostr':
+                kwargs['pubkey'] = genesis.broadcaster
+            elif proto == 'activitypub':
+                kwargs['domain'] = ap_domain
+            elif proto == 'rhio':
+                kwargs['subject'] = f'fleetmesh.video.{stream_id}'
+            announcements[proto] = ProtocolTranslator.from_unified(proto, post, **kwargs)
+        return announcements
+
+    # ---- ProtocolHost HTTP Ingress Mounting ---------------------------------
+
+    def mount_ingress(self, host: ProtocolHostRouter) -> None:
+        """Mount live video manifest and segment routes onto ProtocolHostRouter."""
+        from node.transport import ws
+
+        def _handle_streams(conn: Any, req: Any) -> bool:
+            with self._lock:
+                items = [
+                    {
+                        'stream_id': sid,
+                        'broadcaster': st['genesis'].broadcaster,
+                        'title': st['genesis'].title,
+                        'segments_count': len(st['segments']),
+                        'latest_seq': st['latest_seq'],
+                        'transit_endpoints': list(st['transit_endpoints']),
+                    }
+                    for sid, st in self._streams.items()
+                ]
+            body = json.dumps({'streams': items, 'count': len(items)}).encode('utf-8')
+            ws.http_response(conn, '200 OK', body, 'application/json')
+            return True
+
+        def _handle_live(conn: Any, req: Any) -> bool:
+            uri = getattr(req, 'path', '')
+            parsed = urllib.parse.urlparse(uri)
+            route_path = parsed.path
+            qparams = urllib.parse.parse_qs(parsed.query)
+
+            prefix = '/video/live/'
+            if not route_path.startswith(prefix):
+                return False
+            tail = route_path[len(prefix):].strip('/')
+            parts = tail.split('/')
+            if len(parts) < 2:
+                ws.http_response(conn, '400 Bad Request', b'{"error":"invalid_stream_route"}', 'application/json')
+                return True
+
+            stream_id, resource = parts[0], parts[1]
+            with self._lock:
+                state = self._streams.get(stream_id)
+            if state is None:
+                ws.http_response(conn, '404 Not Found', b'{"error":"stream_not_found"}', 'application/json')
+                return True
+
+            # 1. Playlist request (.m3u8)
+            if resource.endswith('.m3u8'):
+                audio_only = qparams.get('audio_only', ['0'])[0] == '1'
+                try:
+                    playlist = self.render_m3u8(stream_id, audio_only=audio_only)
+                    ws.http_response(
+                        conn,
+                        '200 OK',
+                        playlist.encode('utf-8'),
+                        'application/vnd.apple.mpegurl',
+                    )
+                except Exception as e:
+                    ws.http_response(
+                        conn,
+                        '500 Internal Server Error',
+                        json.dumps({'error': str(e)}).encode('utf-8'),
+                        'application/json',
+                    )
+                return True
+
+            # 2. Segment request (<sha256>.m4s or <sha256>.mp4)
+            is_origin_pull = qparams.get('origin', ['0'])[0] == '1'
+            active_reflectors = state['transit_endpoints']
+            if active_reflectors and not is_origin_pull:
+                # Capacity shed handover active: redirect viewer to Transit Reflector
+                target_url = f"{active_reflectors[0].rstrip('/')}/{resource}"
+                ws.http_response(
+                    conn,
+                    '307 Temporary Redirect',
+                    json.dumps({'redirect': target_url}).encode('utf-8'),
+                    'application/json',
+                    headers={'Location': target_url},
+                )
+                return True
+
+            clean_hash = resource.split('.')[0].lower()
+            with self._lock:
+                known_hashes = {s.sha256.lower() for s in state['segments']}
+                if state['genesis'].init_sha256:
+                    known_hashes.add(state['genesis'].init_sha256.lower())
+            if known_hashes and clean_hash not in known_hashes:
+                ws.http_response(conn, '404 Not Found', b'{"error":"segment_not_found"}', 'application/json')
+                return True
+
+            blob = self.get_segment_bytes(resource)
+            if blob is None:
+                ws.http_response(conn, '404 Not Found', b'{"error":"segment_not_found"}', 'application/json')
+                return True
+
+            headers_raw = getattr(req, 'headers', {})
+            cashu_token = (
+                headers_raw.get(b'x-cashu', b'').decode('utf-8', errors='ignore').strip()
+                or headers_raw.get('x-cashu', '')
+                or headers_raw.get('X-Cashu', '')
+            )
+            viewer_peer = (
+                headers_raw.get(b'x-fleetmesh-peer', b'').decode('utf-8', errors='ignore').strip()
+                or 'anonymous'
+            )
+
+            # Commercial Settlement Path A: PaidFetch dual-item 402 (operator NUT-03 + creator NUT-11)
+            genesis = state['genesis']
+            if self.paid_fetch is not None and (genesis.price_msat_per_mb > 0 or genesis.account_fee_msat > 0):
+                fetcher_id = None if viewer_peer == 'anonymous' else viewer_peer
+                stat_doc = {'sha256': clean_hash, 'size': len(blob), 'type': 'video/iso.segment'}
+                import inspect
+                quote_params = inspect.signature(self.paid_fetch.quote).parameters
+                uses_stat_sig = 'stat' in quote_params
+                if not cashu_token:
+                    if uses_stat_sig:
+                        quote = self.paid_fetch.quote(stat_doc, fetcher_id, genesis.broadcaster)
+                    else:
+                        quote = self.paid_fetch.quote(
+                            sha256=clean_hash,
+                            size=len(blob),
+                            content_type='video/iso.segment',
+                            fetcher=fetcher_id,
+                            account=genesis.broadcaster,
+                            account_msat=genesis.account_fee_msat,
+                        )
+                    if quote is not None:
+                        q_body = quote.body() if callable(getattr(quote, 'body', None)) else getattr(quote, 'body', {})
+                        ws.http_response(
+                            conn,
+                            '402 Payment Required',
+                            json.dumps(q_body).encode('utf-8'),
+                            'application/json',
+                            headers=quote.headers(),
+                        )
+                        return True
+                else:
+                    if uses_stat_sig:
+                        quote = self.paid_fetch.quote(stat_doc, fetcher_id, genesis.broadcaster)
+                        if quote is not None:
+                            tokens = [t.strip() for t in str(cashu_token).split(',') if t.strip()]
+                            verdict = self.paid_fetch.settle(quote, tokens)
+                            if not hasattr(verdict, 'amount_msat') and not getattr(verdict, 'ok', False):
+                                ws.http_response(
+                                    conn,
+                                    '402 Payment Required',
+                                    json.dumps({'error': getattr(verdict, 'reason', 'unpaid')}).encode('utf-8'),
+                                    'application/json',
+                                    headers=quote.headers(),
+                                )
+                                return True
+                    else:
+                        verdict = self.paid_fetch.settle(
+                            sha256=clean_hash,
+                            size=len(blob),
+                            content_type='video/iso.segment',
+                            header=cashu_token,
+                            fetcher=fetcher_id,
+                            account=genesis.broadcaster,
+                            account_msat=genesis.account_fee_msat,
+                        )
+                        if not getattr(verdict, 'ok', False):
+                            quote = getattr(verdict, 'quote', None)
+                            extra = quote.headers() if quote is not None else {}
+                            ws.http_response(
+                                conn,
+                                '402 Payment Required',
+                                json.dumps({'error': getattr(verdict, 'reason', 'unpaid')}).encode('utf-8'),
+                                'application/json',
+                                headers=extra,
+                            )
+                            return True
+
+            # Commercial Settlement Path B: CrossProtocolSettlementGateway TokenBucket
+            elif self.settlement_gateway is not None:
+                if cashu_token:
+                    try:
+                        self.settlement_gateway.settle_cashu('video', viewer_peer, cashu_token)
+                    except Exception as e:
+                        ws.http_response(
+                            conn,
+                            '402 Payment Required',
+                            json.dumps({'error': str(e)}).encode('utf-8'),
+                            'application/json',
+                        )
+                        return True
+                allowed, challenge = self.settlement_gateway.check_access('video', viewer_peer, cost=1)
+                if not allowed and challenge is not None:
+                    _code, ch_headers, ch_body = challenge.to_http_402()
+                    ws.http_response(
+                        conn,
+                        '402 Payment Required',
+                        ch_body,
+                        'application/json',
+                        headers=dict(ch_headers),
+                    )
+                    return True
+
+            meta = self.rhio_store.get_blob_meta(clean_hash) if hasattr(self.rhio_store, 'get_blob_meta') else None
+            if meta is not None and meta.get('tree_root'):
+                tree_root = str(meta['tree_root'])
+            else:
+                tree_root, _ = RhioBaoTree.compute_tree(blob)
+            ws.http_response(
+                conn,
+                '200 OK',
+                blob,
+                'video/iso.segment',
+                headers={'X-Bao-Tree-Root': tree_root},
+            )
+            return True
+
+        host.mount_route('/video/streams', _handle_streams, methods=('GET',), owner='video')
+        host.mount_route('/video/live', _handle_live, methods=('GET',), owner='video')
+
+
+__all__ = [
+    'StreamStateRecord',
+    'SegmentMultiAddress',
+    'VideoStreamPackager',
+]