tibet-continuityd 0.3.3__py3-none-any.whl

tibet_continuityd/__init__.py

@@ -0,0 +1,105 @@
+"""
+tibet-continuityd — Continuous Integrity System Daemon
+=======================================================
+
+A residential trust guardian that runs in the background of
+every machine where TIBET cryptographic discipline must be
+continuously enforced.
+
+  Watch  → inotify
+  Sniff  → libmagic / TBZ magic-byte recognition
+  Verify → (v0.2) cryptographic verification
+  Fork   → (v0.2) forward-causal materialize via phantom.icc
+  Triage → (v0.2) quarantine on mismatch
+  Reseal → (v0.3) periodic reseal of materialized state
+
+Three operating modes:
+  Mode 1  Passive Guardian  observe + log + advise
+  Mode 2  Sealing Guardian  auto-reseal + active intake
+  Mode 3  Strict Continuity zero-trust, ICC/TBZ only
+
+Spec: /srv/jtel-stack/hersenspinsels/tibet-continuityd-spec.md
+Plus: /srv/jtel-stack/hersenspinsels/tibet-continuity-guardian.md
+       (Codex' parallel intake-discipline guide)
+
+  "Name is hint. Content is truth. Arrival is event."
+                                — Codex, 9 mei 2026
+"""
+
+__version__ = "0.3.3"
+__author__ = "Jasper van de Meent, Root AI, Codex"
+
+# Core stages — pure stdlib, always available
+from tibet_continuityd.backpressure import (
+    BackpressureMonitor,
+    BackpressureSnapshot,
+    BackpressureState,
+)
+from tibet_continuityd.police import (
+    FindingSeverity,
+    PoliceAction,
+    PoliceFinding,
+    PoliceScanner,
+    apply_action,
+)
+from tibet_continuityd.sniff import IntakeClass, sniff_payload
+from tibet_continuityd.trust_kernel import (
+    TrustQuery,
+    TrustVerdict,
+    apply_verdict_to_disposition,
+    load_policies,
+    query_trust_kernel,
+)
+from tibet_continuityd.watch import LaneWatcher, WatchEvent
+
+# Verify + Fork + Seal — require tibet-drop (install via [verify] extra)
+# Defensive imports: core daemon works without these.
+try:
+    from tibet_continuityd.verify_fork import (
+        CausalIDs,
+        VerifyForkResult,
+        verify_and_fork,
+    )
+    from tibet_continuityd.seal import SealEngine, SealResult
+    from tibet_continuityd.daemon import ContinuityDaemon
+    _HAS_VERIFY = True
+except ImportError:
+    # tibet-drop not on sys.path — verify/fork/seal/daemon unavailable.
+    # Core sniff/police/trust_kernel/watch/backpressure still work.
+    CausalIDs = None  # type: ignore
+    VerifyForkResult = None  # type: ignore
+    verify_and_fork = None  # type: ignore
+    SealEngine = None  # type: ignore
+    SealResult = None  # type: ignore
+    ContinuityDaemon = None  # type: ignore
+    _HAS_VERIFY = False
+
+__all__ = [
+    # Core (always available)
+    "LaneWatcher",
+    "WatchEvent",
+    "IntakeClass",
+    "sniff_payload",
+    "TrustQuery",
+    "TrustVerdict",
+    "query_trust_kernel",
+    "apply_verdict_to_disposition",
+    "load_policies",
+    "PoliceFinding",
+    "PoliceScanner",
+    "PoliceAction",
+    "FindingSeverity",
+    "apply_action",
+    "BackpressureMonitor",
+    "BackpressureSnapshot",
+    "BackpressureState",
+    # Verify-stage (None when tibet-drop unavailable)
+    "ContinuityDaemon",
+    "CausalIDs",
+    "VerifyForkResult",
+    "verify_and_fork",
+    "SealEngine",
+    "SealResult",
+    # Capability flag
+    "_HAS_VERIFY",
+]

tibet_continuityd/__main__.py

@@ -0,0 +1,7 @@
+"""CLI entry: `python -m tibet_continuityd`."""
+import sys
+
+from tibet_continuityd.daemon import main
+
+if __name__ == "__main__":
+    sys.exit(main())

tibet_continuityd/backpressure.py

@@ -0,0 +1,185 @@
+"""
+backpressure.py — Backpressure / circuit-breaker (v0.3.2, axe 3).
+
+Per Jaspers prompt 9 mei 2026:
+
+  "MUX 500 files/sec, sniff/verify 100/sec. Inbox > 5000 onverwerkt
+   → daemon signaleert MUX/network 'Halt' of TCP-windowing-stijl
+   backpressure. Geen self-inflicted DoS."
+
+This module implements that protection: monitor the inbox depth
+and emit state-transition audit events when pressure rises or
+falls. The daemon itself does NOT throttle its own work-rate
+(that would worsen things) — it signals UPSTREAM that producer
+should slow down.
+
+State machine:
+
+   NORMAL                  depth < low_water
+      │
+      │ depth ≥ low_water
+      ▼
+   PRESSURE_RISING         low_water ≤ depth < high_water
+      │
+      │ depth ≥ high_water
+      ▼
+   OVERLOADED              depth ≥ high_water
+      │
+      │ depth < low_water (hysteresis)
+      ▼
+   RECOVERING              transitional state
+      │
+      │ depth stable < low_water
+      ▼
+   NORMAL
+
+Hysteresis: NORMAL → OVERLOADED requires high_water,
+            OVERLOADED → NORMAL requires going back below
+            low_water (not just back below high_water).
+            This prevents oscillation at the boundary.
+
+Signal mechanism (v0.3.2 minimal):
+  emit "backpressure" audit-record at every state-transition
+  (= upstream consumers can read audit-stream and react)
+
+Future v0.3.x extensions:
+  - write signal-file at /var/lib/tibet/backpressure-state
+  - HTTP endpoint POST to mux upstream
+  - TIBET token emission for cross-host signaling
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+
+class BackpressureState(Enum):
+    """Daemon's current capacity state."""
+    NORMAL = "normal"                  # depth < low_water
+    PRESSURE_RISING = "pressure-rising"  # low ≤ depth < high
+    OVERLOADED = "overloaded"          # depth ≥ high_water
+    RECOVERING = "recovering"          # was overloaded, depth dropping
+
+
+@dataclass
+class BackpressureSnapshot:
+    """One observation of inbox depth + current state."""
+    state: BackpressureState
+    inbox_depth: int                   # number of unprocessed files
+    low_water: int                     # threshold for "rising"
+    high_water: int                    # threshold for "overloaded"
+    transitioned: bool                 # state changed since last check
+    prev_state: Optional[BackpressureState] = None
+    ts_unix: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict:
+        return {
+            "state": self.state.value,
+            "inbox_depth": self.inbox_depth,
+            "low_water": self.low_water,
+            "high_water": self.high_water,
+            "transitioned": self.transitioned,
+            "prev_state": self.prev_state.value
+                if self.prev_state else None,
+            "ts_unix": self.ts_unix,
+        }
+
+
+@dataclass
+class BackpressureMonitor:
+    """Track inbox depth and compute state transitions.
+
+    Usage:
+        monitor = BackpressureMonitor(
+            lane=Path("/var/lib/tibet/inbox"),
+            low_water=2000,
+            high_water=5000,
+        )
+        snapshot = monitor.check()
+        if snapshot.transitioned:
+            # emit audit, optionally signal upstream
+            ...
+    """
+    lane: Path
+    low_water: int = 2000
+    high_water: int = 5000
+    _state: BackpressureState = BackpressureState.NORMAL
+
+    def __post_init__(self):
+        if self.low_water >= self.high_water:
+            raise ValueError(
+                f"low_water ({self.low_water}) must be < "
+                f"high_water ({self.high_water})"
+            )
+
+    def _measure_depth(self) -> int:
+        """Count files in lane (excluding subdirectories)."""
+        if not self.lane.exists() or not self.lane.is_dir():
+            return 0
+        try:
+            return sum(1 for entry in self.lane.iterdir()
+                       if entry.is_file())
+        except OSError:
+            return 0
+
+    def _classify_state(self, depth: int) -> BackpressureState:
+        """Compute target state from depth WITHOUT hysteresis logic.
+
+        Hysteresis is applied in check() — this is the raw mapping.
+        """
+        if depth >= self.high_water:
+            return BackpressureState.OVERLOADED
+        if depth >= self.low_water:
+            return BackpressureState.PRESSURE_RISING
+        return BackpressureState.NORMAL
+
+    def check(self) -> BackpressureSnapshot:
+        """Measure depth and update state with hysteresis."""
+        depth = self._measure_depth()
+        prev = self._state
+        target = self._classify_state(depth)
+
+        # Hysteresis: OVERLOADED can ONLY drop to RECOVERING (not
+        # straight to NORMAL via PRESSURE_RISING). This prevents
+        # oscillation when depth hovers near low_water.
+        new_state = target
+        if prev == BackpressureState.OVERLOADED and \
+                target != BackpressureState.OVERLOADED:
+            # transition out of overloaded → recovering first
+            if target == BackpressureState.NORMAL:
+                new_state = BackpressureState.RECOVERING
+            # else: target is PRESSURE_RISING, accept it
+        elif prev == BackpressureState.RECOVERING:
+            # In RECOVERING, stay until depth is fully back under
+            # low_water (= NORMAL target).
+            if target == BackpressureState.NORMAL:
+                new_state = BackpressureState.NORMAL
+            elif target == BackpressureState.OVERLOADED:
+                new_state = BackpressureState.OVERLOADED
+            else:
+                new_state = BackpressureState.RECOVERING
+
+        transitioned = (new_state != prev)
+        self._state = new_state
+
+        return BackpressureSnapshot(
+            state=new_state,
+            inbox_depth=depth,
+            low_water=self.low_water,
+            high_water=self.high_water,
+            transitioned=transitioned,
+            prev_state=prev if transitioned else None,
+        )
+
+
+# ─── Public API ─────────────────────────────────────────────────
+
+
+__all__ = [
+    "BackpressureMonitor",
+    "BackpressureSnapshot",
+    "BackpressureState",
+]

tibet_continuityd/coalesce.py

@@ -0,0 +1,143 @@
+"""
+coalesce.py — object-level intake coalescing for continuityd v0.3.
+
+The watcher stays syscall/event-level. This module collapses a burst of
+related arrival events for the same path into one settled object so the
+daemon reasons about files, not write-close noise.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from tibet_continuityd.watch import WatchEvent
+
+
+@dataclass(frozen=True)
+class FileSnapshot:
+    size_bytes: int
+    mtime_ns: int
+
+
+@dataclass
+class PendingArrival:
+    latest_event: WatchEvent
+    first_seen_ts: float
+    last_seen_ts: float
+    event_count: int
+    last_snapshot: Optional[FileSnapshot]
+
+
+@dataclass
+class SettledArrival:
+    lane: Path
+    name: str
+    full_path: Path
+    flags: int
+    is_dir: bool
+    ts_unix: float
+    coalesced: bool
+    coalesced_event_count: int
+    coalesced_window_ms: int
+    settled_after_ms: int
+    path_churn_detected: bool
+
+
+def _safe_snapshot(path: Path) -> Optional[FileSnapshot]:
+    try:
+        st = path.stat()
+    except OSError:
+        return None
+    return FileSnapshot(size_bytes=st.st_size, mtime_ns=st.st_mtime_ns)
+
+
+class ArrivalCoalescer:
+    """Collapse repeated arrivals for the same path into settled objects."""
+
+    def __init__(
+        self,
+        debounce_window_ms: int = 350,
+        max_pending_age_ms: int = 5000,
+        high_churn_threshold: int = 5,
+    ):
+        self.debounce_window_ms = debounce_window_ms
+        self.max_pending_age_ms = max_pending_age_ms
+        self.high_churn_threshold = high_churn_threshold
+        self._pending: dict[Path, PendingArrival] = {}
+
+    def ingest(self, event: WatchEvent) -> None:
+        snapshot = _safe_snapshot(event.full_path)
+        entry = self._pending.get(event.full_path)
+        if entry is None:
+            self._pending[event.full_path] = PendingArrival(
+                latest_event=event,
+                first_seen_ts=event.ts_unix,
+                last_seen_ts=event.ts_unix,
+                event_count=1,
+                last_snapshot=snapshot,
+            )
+            return
+
+        entry.latest_event = event
+        entry.last_seen_ts = event.ts_unix
+        entry.event_count += 1
+        entry.last_snapshot = snapshot
+
+    def flush_ready(
+        self,
+        now: Optional[float] = None,
+    ) -> list[SettledArrival]:
+        now = time.time() if now is None else now
+        ready: list[SettledArrival] = []
+        expired_paths: list[Path] = []
+
+        for path, entry in list(self._pending.items()):
+            age_ms = int((now - entry.last_seen_ts) * 1000)
+            total_age_ms = int((now - entry.first_seen_ts) * 1000)
+
+            if age_ms < self.debounce_window_ms:
+                continue
+
+            current = _safe_snapshot(path)
+            if current is None:
+                expired_paths.append(path)
+                continue
+
+            if current != entry.last_snapshot:
+                entry.last_snapshot = current
+                entry.last_seen_ts = now
+                continue
+
+            if total_age_ms > self.max_pending_age_ms:
+                entry.last_seen_ts = now
+
+            event = entry.latest_event
+            ready.append(
+                SettledArrival(
+                    lane=event.lane,
+                    name=event.name,
+                    full_path=event.full_path,
+                    flags=int(event.flags),
+                    is_dir=event.is_dir,
+                    ts_unix=event.ts_unix,
+                    coalesced=entry.event_count > 1,
+                    coalesced_event_count=entry.event_count,
+                    coalesced_window_ms=self.debounce_window_ms,
+                    settled_after_ms=total_age_ms,
+                    path_churn_detected=(
+                        entry.event_count > self.high_churn_threshold
+                    ),
+                )
+            )
+            expired_paths.append(path)
+
+        for path in expired_paths:
+            self._pending.pop(path, None)
+
+        return ready
+
+    @property
+    def pending_count(self) -> int:
+        return len(self._pending)