Metadata-Version: 2.4
Name: tibet-cascade
Version: 0.2.0
Summary: Cascade Logging for TIBET — causal observability across JIS, TIBET, cap-bus, ping, continuity, Phantom, and evidence lanes.
Project-URL: Homepage, https://humotica.com
Project-URL: Repository, https://github.com/Humotica/tibet-cascade
Project-URL: Documentation, https://humotica.com/docs/tibet-cascade
Author-email: Jasper van de Meent <jasper@humotica.com>, Root AI <root_idd@humotica.nl>
License: MIT
Keywords: audit,cascade-logging,causal-trace,jis,observability,provenance,tibet
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: jis-core>=0.4.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tibet-core>=0.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: textual>=1.0.0; extra == 'full'
Provides-Extra: tui
Requires-Dist: textual>=1.0.0; extra == 'tui'
Description-Content-Type: text/markdown

# tibet-cascade

Cascade Logging for TIBET.

`tibet-cascade` is the observability layer for causal logging across the stack:

```text
JIS claim/bind/FIR-A
-> TIBET token
-> cap-bus event
-> gateway verdict
-> ping/overlay/network state
-> continuityd arrival/resume
-> Phantom fork/resume
-> audit/evidence/report
```

It does not replace `tibet-tail`, `tibet-trail`, `tibet-ping`, or `tibet-pol`.
It correlates them.

## Armed, wired, muted

A cascade viewer is only worth what its producers put in it, so this package never
shows the switch on its own. Every source reports in one of three states, and the
middle one is the point:

| state | meaning |
|---|---|
| `wired` | this source has actually emitted — with a count and how long ago |
| `armed` | recording is switched on, but **no producer has ever emitted here** |
| `muted` | switched off; nothing from this source is recorded |

Between 0.1.x and 0.2.0 every source in this package printed a green `on` while
nothing in the whole stack called `emit` at all. That is the failure mode a viewer
must not have: a quiet system and an unwired viewer looked identical, and the
instrument reported the wish instead of the wire. `doctor`, `list`, `watch` and
`logger status` now all say which of the two you are looking at.

Two consequences worth knowing:

- **Recording is the default.** An absent `loggers.json` means every source records,
  and an unknown source records. The file holds deliberate mutes, not permissions.
- **A muted source refuses out loud.** `tibet-cascade emit` into a muted source prints
  why and exits `2`; it never silently swallows what you asked it to record.

## Emitting from your own code

```python
import tibet_cascade

tibet_cascade.emit(
    "device-link", "pairing.challenge", "challenge minted",
    subject="jasper2.aint", cascade_id=fork_id, refs={"fork_id": fork_id},
)
```

`emit()` never raises and honours the mute switch — a full disk or a read-only home
returns `None`. Observability that can break the thing it observes is worse than none.
Pass the same `cascade_id` through a chain of events to make them one causal thread,
and `parent_id` to say which event came from which.

## Install

```bash
pip install tibet-cascade
```

Bootstrap-or-die dependencies are mandatory:

- `tibet-core>=0.5.0`
- `jis-core>=0.4.0`

## Commands

```bash
tibet-cascade doctor
tibet-cascade watch
tibet-cascade trace --id <cascade-or-token-id>
tibet-cascade logger on jis-core
tibet-cascade logger off tibet-core
tibet-cascade logger status
tibet-cascade ping --instance phone
tibet-cascade caps --read
tibet-cascade token --trace <token-id>
```

Default event file:

```text
~/.tibet/cascade/events.jsonl
```

Override with:

```bash
TIBET_CASCADE_JSONL=/path/to/events.jsonl tibet-cascade watch
```

## Event Shape

```json
{
  "ts": "2026-06-07T21:55:00Z",
  "cascade_id": "cas_...",
  "event_id": "evt_...",
  "parent_id": "evt_...",
  "source": "jis-core",
  "kind": "identity.claim",
  "subject": "jis:...",
  "level": "INFO",
  "summary": "claim accepted",
  "refs": {
    "tibet_token": "...",
    "cap_event": "...",
    "trace": "..."
  },
  "data": {}
}
```

## Stack Area

`observability`

Related packages:

- `tibet-tail`: live event stream
- `tibet-trail`: provenance trail reader
- `tibet-ping`: liveness and network probe
- `tibet-pol`: process and posture observer
- `tibet-cascade`: causal correlation cockpit
