xrpl-witness 0.1.1
Local-first, append-only event journal for human-AI work
Requires Python: >=3.11
Keywords: audit, cryptography, ed25519, event-journal, provenance

# Witness

**Status: v0.1.0 — Phase 1 complete, Phase 2A shipped**

A local-first, append-only, cryptographically verifiable event journal for human–AI work.

## What you can do today

```bash
# Generate a testimony report
witness testify --format json --emit-artifact ./output

# Verify events cryptographically
witness verify

# Include exact stored JSON for deep audits
witness testify --format json --include-events
```

**Third parties can validate testimony without Witness installed** — the JSON schema and verification rules are fully documented.

## Why it matters

Witness creates portable proof trails:
- **Deterministic**: Same inputs → same output bytes (use `--generated-at` for reproducibility)
- **Verifiable**: Ed25519 signatures + SHA-256 digests over canonical JSON
- **Portable**: Email it, attach it to tickets, check it into a repo
- **Exact**: `--include-events` embeds byte-for-byte store content

## Quickstart

```bash
# Install
pip install cryptography

# Initialize a store
witness init

# Record an event
witness record --action "example.action" --intent "Demonstrate recording"

# Generate testimony
witness testify --format md

# Verify all events
witness verify
```

## Trust model

All cryptographic operations use **canonical JSON** → **SHA-256 digests** → **Ed25519 signatures**.

See [VERIFICATION.md](VERIFICATION.md) for:
- Exact serialization rules
- Worked verification examples
- Exit codes (0 = clean, 2 = flags, 3 = crypto failure)
- Privacy notes for `--include-events`

## Stable guarantees

| Artifact | Location | Contract |
|----------|----------|----------|
| Event schema | Golden fixtures | `tests/fixtures/golden/*.json` |
| Testimony schema | `schemas/testimony.schema.v0.1.json` | JSON output structure |
| Exit codes | [VERIFICATION.md](VERIFICATION.md) | 0/2/3 semantics |
| Flags | [IMPLEMENTATION_NOTES.md](IMPLEMENTATION_NOTES.md) | 4 flag types, informational only |

## Documentation

> **Start here:** [CONTRACT.md](CONTRACT.md) — What is law vs example

| Document | Purpose |
|----------|---------|
| [CONTRACT.md](CONTRACT.md) | Normative vs example content |
| [IMPLEMENTATION_NOTES.md](IMPLEMENTATION_NOTES.md) | Locked invariants |
| [VERIFICATION.md](VERIFICATION.md) | Crypto rules + worked examples |
| [docs/](docs/README.md) | Full documentation index |

## Phase 2 status

| Track | Status |
|-------|--------|
| **2A: Testimony as Artifact** | ✅ Shipped |
| **2B: Pipelines** | ⏸️ Paused ([RFC](docs/RFC_PHASE2_PIPELINES.md)) |
| 2C–2E | Not started |

See [docs/PHASE2_STATUS.md](docs/PHASE2_STATUS.md) for details.

## Project structure

```
witness/
├── src/witness/           # Core library
│   ├── canon.py           # Canonical JSON
│   ├── crypto.py          # Ed25519 signing/verification
│   ├── storage.py         # SQLite append-only store
│   ├── timeline.py        # Flag analysis
│   ├── testify.py         # Testimony generation
│   └── cli.py             # Command-line interface
├── schemas/               # JSON schemas
├── tests/                 # Test suite (124 tests)
│   └── fixtures/golden/   # Authoritative fixtures
├── tools/                 # Verification utilities
└── docs/                  # Documentation + ADRs
```

## Philosophy

> Witness is about truthfulness, not judgment.
> Record what happened. Verify it later. Let humans decide what it means.

## License

MIT — see [LICENSE](LICENSE).