Metadata-Version: 2.4
Name: tibet-pol
Version: 0.1.0
Summary: Process Integrity Checker — every step a TIBET token, every deviation an alert
Project-URL: Homepage, https://humotica.com
Project-URL: Repository, https://github.com/jaspertvdm/tibet-pol
Project-URL: Documentation, https://humotica.com/docs/tibet-pol
Project-URL: Bug Tracker, https://github.com/jaspertvdm/tibet-pol/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: audit,ci-cd,devops,integrity,process,provenance,tibet
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
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 :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
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-pol — Process Integrity Checker

> Every step a TIBET token. Every deviation an alert.
>
> *"Pol kan nooit meer vergeten een knop in te drukken."*

**tibet-pol** verifies that multi-step processes run completely and correctly. Each step produces a cryptographic [TIBET](https://pypi.org/project/tibet-core/) provenance token. If a step fails or is skipped, you know *exactly* what went wrong, when, and why.

Think of it as a **checksum for processes** — the same way you verify file integrity after download, tibet-pol verifies process integrity after execution.

## Origin Story

A Google engineer named Pol had a sync problem — his system didn't reliably track which steps had completed. After weeks in the support loop, the solution was obvious: *"Let's just count the steps."* Like checksums verify files after download/unpack/install, tibet-pol counts and verifies system tasks.

## Install

```bash
pip install tibet-pol
```

## Quick Start

### Check a process

```bash
tibet-pol check deploy.json
```

```
🔍 tibet-pol: Checking 'Server Deployment'...

  🔍 Checking: Database Migrated... ✓
  🔍 Checking: API Service Running... ✓
  🔍 Checking: Health Check Passing... ✓
  🔍 Checking: Cache Warmed... ✗ FAILED
  🔍 Checking: Monitoring Active... ✓

=======================================================
📋 TIBET-POL PROCESS INTEGRITY REPORT
   Process: Server Deployment
=======================================================

⚠️ Status: INCOMPLETE
   Checksum: 4/5 (80%)
   ├── Success: 4
   ├── Failed:  1
   ├── Blocked: 0
   └── Skipped: 0
```

### JSON output for CI/CD

```bash
tibet-pol check --json pipeline.json | jq .summary
```

```json
{
  "total": 6,
  "success": 6,
  "checksum": "6/6",
  "percentage": 100,
  "status": "COMPLETE"
}
```

Exit code 0 = COMPLETE, 1 = INCOMPLETE. Plug directly into your CI pipeline.

### Create a template

```bash
tibet-pol init my_process.json
```

### Watch mode (continuous monitoring)

```bash
tibet-pol watch deploy.json --interval 300
```

### Compare two runs

```bash
tibet-pol diff run_20260227.json run_20260228.json
```

### HTML report

```bash
tibet-pol check --save --json deploy.json > run.json
tibet-pol report run.json -o report.html
```

## Process Templates

A template is a JSON file defining steps, dependencies, and check commands:

```json
{
  "process_id": "my_deploy",
  "name": "My Deployment",
  "version": "1.0.0",
  "steps": [
    {
      "id": "db_migrated",
      "name": "Database Migrated",
      "check": "python manage.py migrate --check",
      "dependencies": [],
      "critical": true
    },
    {
      "id": "api_up",
      "name": "API Running",
      "check": "curl -sf http://localhost:8080/health",
      "dependencies": ["db_migrated"],
      "critical": true,
      "timeout_seconds": 10
    },
    {
      "id": "cache_warm",
      "name": "Cache Warmed",
      "check": "redis-cli ping",
      "dependencies": ["api_up"],
      "critical": false
    }
  ]
}
```

### Step fields

| Field | Required | Description |
|-------|----------|-------------|
| `id` | yes | Unique step identifier |
| `name` | yes | Human-readable name |
| `check` | yes | Shell command (exit 0 = success) |
| `dependencies` | no | List of step IDs that must pass first |
| `critical` | no | If true, downstream steps are blocked on failure |
| `timeout_seconds` | no | Max execution time (default: 30) |
| `intent` | no | Why this step exists (stored in TIBET token) |
| `on_failure` | no | Remediation command hint |

### Dependency resolution

Steps are executed in **topological order** based on dependencies (DAG). If a dependency fails, downstream steps are marked `BLOCKED` — not executed.

```
db_migrated ──→ api_up ──→ health_check
                  │
                  ├──→ cache_warm
                  └──→ monitoring
```

## TIBET Provenance

Every step produces a TIBET token with four provenance layers:

| Layer | Content | Example |
|-------|---------|---------|
| **ERIN** | What happened | Step ID, status, output |
| **ERAAN** | Dependencies | Which steps had to pass first |
| **EROMHEEN** | Context | Machine, timestamp, user, PID |
| **ERACHTER** | Intent | Why this step exists |

Tokens are chained — each references its parent. The full chain is an immutable audit trail of the process execution.

When `tibet-core` is installed, tokens are also registered with the TIBET Provider for cross-system provenance.

## Python API

```python
from tibet_pol import ProcessChecker, load_template

template = load_template("deploy.json")
checker = ProcessChecker(verbose=True)
result = checker.run(template)

print(result.summary)
# {'total': 5, 'success': 5, 'checksum': '5/5', 'percentage': 100, 'status': 'COMPLETE'}

# Access individual steps
for step in result.steps:
    print(f"{step.step_name}: {step.status} ({step.duration_ms}ms)")

# Full TIBET token chain
for token in result.tokens:
    print(token["token_id"], token["erin"]["status"])
```

## Example Templates

tibet-pol ships with example templates:

- **`ci_pipeline.json`** — CI/CD: checkout → deps → lint → test → build → publish
- **`server_deploy.json`** — Deploy: DB migrate → API up → health check → cache → monitoring

## Use Cases

| Scenario | Template |
|----------|----------|
| CI/CD pipeline audit | Lint → Test → Build → Sign → Publish |
| Server deployment | DB migrate → API → Health → Cache → Monitor |
| Kubernetes rollout | Image pull → Deploy → Rollout → Probes → DNS |
| Incident response | Detect → Isolate → Fix → Verify → Report |
| Data pipeline | Extract → Validate → Transform → Load → Verify |
| Server bootstrap | OS → Network → GPU → Services → APIs |

## Part of the TIBET ecosystem

| Package | Purpose |
|---------|---------|
| [`tibet-core`](https://pypi.org/project/tibet-core/) | Protocol core — zero deps |
| [`jis-core`](https://pypi.org/project/jis-core/) | Identity standard |
| [`tibet-audit`](https://pypi.org/project/tibet-audit/) | Security audit tooling |
| [`tibet-y2k38`](https://pypi.org/project/tibet-y2k38/) | Y2K38 Time Bridge |
| **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/) | IPv4/IPv6 identity overlay |
| [`tibet-twin`](https://pypi.org/project/tibet-twin/) | Digital Twin synchronicity |

## Standards

- **TIBET Protocol:** [IETF Draft](https://datatracker.ietf.org/doc/draft-vandemeent-tibet-provenance/)
- **JIS Identity:** [IETF Draft](https://datatracker.ietf.org/doc/draft-vandemeent-jis-identity/)
- **Zenodo:** [DOI Publications](https://zenodo.org/communities/humotica)

## License

MIT — Humotica AI Lab 2025-2026

## Authors

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