Metadata-Version: 2.4
Name: tibet-twin
Version: 0.1.0
Summary: Digital Twin Synchronicity Guard — deterministic sync verification between physical and virtual systems with TIBET provenance
Project-URL: Homepage, https://humotica.com
Project-URL: Repository, https://github.com/jaspertvdm/tibet-twin
Project-URL: Documentation, https://humotica.com/docs/tibet-twin
Project-URL: Bug Tracker, https://github.com/jaspertvdm/tibet-twin/issues
Project-URL: TIBET Protocol, https://pypi.org/project/tibet-core/
Project-URL: JIS Identity, https://pypi.org/project/jis-core/
Project-URL: IETF TIBET Draft, https://datatracker.ietf.org/doc/draft-vandemeent-tibet-provenance/
Project-URL: IETF JIS Draft, https://datatracker.ietf.org/doc/draft-vandemeent-jis-identity/
Author-email: "J. van de Meent" <jasper@humotica.com>, "R. AI" <root_idd@humotica.nl>
Maintainer-email: Humotica AI Lab <ai@humotica.nl>
License: MIT
License-File: LICENSE
Keywords: digital-twin,industry-4.0,iot,safety,scada,synchronicity,tibet
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
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: Topic :: Scientific/Engineering
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: tibet-core>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: rich>=13.0.0; extra == 'full'
Description-Content-Type: text/markdown

# tibet-twin — Digital Twin Synchronicity Guard

> No action without proven synchronization.
>
> Every deviation is an alert. Every decision is a TIBET token.

**tibet-twin** ensures physical and virtual systems are synchronized before allowing any action. When a digital twin's view of reality diverges from actual sensor data, tibet-twin **blocks** the action and creates a [TIBET](https://pypi.org/project/tibet-core/) audit trail.

## The Deadly Scenario

Factories and ports build digital twins — virtual 3D copies of physical machines. But there's always latency between the physical sensor and the virtual model.

```
[Physical Crane]                    [Digital Twin]
  sensor: FAULT t=14:32:01.003       status: OK t=14:32:00.500
        |                                  |
        └──── tibet-twin compares ─────────┘
              Δt = 503ms, status ≠ sync
              → BLOCK action
              → TIBET token: audit trail
```

If the digital twin authorizes a "move left" command while the physical crane has a fault... people die.

## Install

```bash
pip install tibet-twin
```

## Quick Start

```python
from tibet_twin import SyncGuard, PhysicalState, TwinState

guard = SyncGuard(max_drift_ms=200)  # Port crane: max 200ms drift

# Physical crane reports: FAULT
guard.update_physical("crane-01", PhysicalState(
    device_id="crane-01",
    timestamp="2026-02-27T14:32:01.003+00:00",
    values={"position_x": 12.5, "load_kg": 2500.0},
    status="fault",
))

# Digital twin still thinks: OK
guard.update_twin("crane-01", TwinState(
    device_id="crane-01",
    timestamp="2026-02-27T14:32:00.500+00:00",
    values={"position_x": 12.5, "load_kg": 2500.0},
    status="operational",
))

decision = guard.check("crane-01", intent="move_left")
print(decision.blocked)  # True
print(decision.reason)   # "BLOCKED: status mismatch: physical=fault, twin=operational"
```

### Demo

```bash
tibet-twin demo        # Interactive crane safety demo
tibet-twin info        # The deadly scenario explained
tibet-twin profiles    # Industry profiles with sync thresholds
```

## Why TIBET Is Unique Here

Other synchronization systems check: **"Is the data there?"**

tibet-twin checks:
1. **Is it the right data?** (value comparison)
2. **From the right device?** (JIS identity)
3. **At the right time?** (temporal drift)
4. **Does the intent match the state?** (TIBET provenance)

All four must pass. One failure = BLOCK.

## Industry Profiles

| Profile | Sector | Max Drift | Safety Critical | Example Assets |
|---------|--------|-----------|----------------|----------------|
| `port` | Maritime | 200ms | Yes | Container cranes, AGVs |
| `manufacturing` | Factory | 100ms | Yes | CNC, robot arms (KUKA/ABB) |
| `energy` | Power Grid | 500ms | Yes | Wind turbines, substations |
| `steel` | Heavy Industry | 300ms | Yes | Blast furnaces, hot strip mills |
| `semiconductor` | Chip Fab | 50ms | Yes | ASML EUV, etch tools |
| `building` | Smart Building | 5000ms | No | HVAC, fire detection |

```bash
tibet-twin profiles --json
```

## TIBET Provenance

Every sync decision creates a TIBET token:

| Layer | Content |
|-------|---------|
| **ERIN** | Decision (allowed/blocked, drift, value deltas) |
| **ERAAN** | Device JIS identity, parent tokens |
| **EROMHEEN** | Guard node, timestamp, environment |
| **ERACHTER** | Intent (what action was attempted), safety flag |

The token chain is an immutable safety audit trail. When an inspector asks "was the twin in sync when the crane moved?" — the TIBET chain proves it.

## Python API

```python
from tibet_twin import SyncGuard, PhysicalState, TwinState

guard = SyncGuard(
    max_drift_ms=200,
    value_tolerances={
        "crane-01": {"position_x": 0.5, "load_kg": 100.0},
    },
)

# Update states continuously
guard.update_physical("crane-01", PhysicalState(...))
guard.update_twin("crane-01", TwinState(...))

# Check before every action
decision = guard.check("crane-01", intent="move_left")
if decision.blocked:
    handle_block(decision)
else:
    execute_action()

# Audit trail
for token in guard.export_audit():
    print(token["erin"]["details"]["reason"])

# Status
print(guard.status())
# {'checks': 150, 'allowed': 142, 'blocked': 8, 'block_rate': 5.3}
```

## Part of the TIBET ecosystem

| Package | Purpose |
|---------|---------|
| [`tibet-core`](https://pypi.org/project/tibet-core/) | Protocol core |
| [`tibet-y2k38`](https://pypi.org/project/tibet-y2k38/) | Y2K38 Time Bridge |
| [`tibet-pol`](https://pypi.org/project/tibet-pol/) | Process Integrity Checker |
| [`tibet-pqc`](https://pypi.org/project/tibet-pqc/) | Post-Quantum Crypto Router |
| [`tibet-overlay`](https://pypi.org/project/tibet-overlay/) | Identity Overlay |
| **tibet-twin** | Digital Twin Guard |

## License

MIT — Humotica AI Lab 2025-2026

## Authors

- **J. van de Meent** — jasper@humotica.com
- **R. AI (Root AI)** — root_idd@humotica.nl
