Metadata-Version: 2.4
Name: jep-runtime
Version: 0.2.0
Summary: Reference runtime for Judgment Event Protocol executable accountability semantics
Author: JEP Runtime Contributors
License: MIT
Keywords: JEP,accountability,protocol,runtime,verification
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: filelock>=3.12

# JEP Reference Runtime

`jep-runtime` is a runnable reference implementation for the Judgment Event Protocol (JEP). It turns the current JEP Internet-Draft primitives — Judgment (`J`), Delegation (`D`), Termination (`T`), and Verification (`V`) — into executable accountability semantics: create an event, canonicalize it, hash it, chain it, archive it, replay it, and verify it across neutral profile adapters.

This repository is intentionally **not** an agent framework, workflow orchestrator, blockchain, consensus layer, payment executor, or production security system. Mock signatures and mock credential references are provided so protocol semantics can be tested before deployment-specific cryptography is plugged in.

## Installation and CLI migration

```sh
python -m pip install --upgrade jep-runtime
jep-runtime --help
```

Version 0.2 uses `jep-runtime`; `jep` remains owned by `jep-cli`. Python imports and existing local-runtime archives are unchanged. If version 0.1 shared an environment with `jep-cli`, upgrade this package first, then run `python -m pip install --force-reinstall jep-cli` to restore the previously shared executable.

This runtime uses its own event envelope. For signed JEP-Core-0.6 wire events use [the SDK](https://github.com/hjs-spec/sdk-py) and [API](https://github.com/hjs-spec/jep-api); do not submit local-runtime envelope fields as core top-level fields.

## Architecture

```text
+-------------------+      +------------------------+      +------------------+
| Event Runtime     | ---> | Canonicalization       | ---> | SHA-256 Hashing  |
| J / D / T / V     |      | UTF-8 sorted JSON      |      | event_hash       |
+---------+---------+      +-----------+------------+      +---------+--------+
          |                            |                             |
          v                            v                             v
+-------------------+      +------------------------+      +------------------+
| Delegation        | ---> | Append-only Archive    | ---> | Verification     |
| scoped authority  |      | JSONL import/export    |      | chain/replay     |
+---------+---------+      +-----------+------------+      +---------+--------+
          |                            |                             |
          v                            v                             v
+-------------------+      +------------------------+      +------------------+
| Profile Adapters  | ---> | Replay Engine          | ---> | Conformance      |
| OAuth/X509/DID/IAM|      | lineage graph/state    |      | vectors/report   |
+-------------------+      +------------------------+      +------------------+
```

## Runtime data flow

1. A caller creates a `JEPEvent` with the required core fields.
2. The event is canonicalized as normalized UTF-8 JSON with stable field ordering and no insignificant whitespace.
3. `event_hash = SHA256(canonical_event_without_event_hash)` is assigned once; changing a hashed event requires creating a new event.
4. New events reference `previous_event_hash`, producing an append-only event chain.
5. Delegation events carry bounded `authority_scope` and `delegation_chain` entries so authority lineage can be replayed.
6. JSONL archives append one canonical event record per line.
7. Verification recomputes hashes, validates nonce uniqueness, checks hash continuity, validates delegation scope, and invokes the configured neutral profile adapter.

## Replay flow

```text
archive.jsonl
   |
   v
import events -> verify entire chain -> replay J/D/T/V semantics
   |                  |                    |
   |                  |                    +--> termination_state
   |                  +--> tamper/nonce/profile/delegation errors
   +--> lineage_graph: hash-chain edges + delegation edges
```

Run it with:

```bash
jep-runtime replay archive.jsonl
```

The replay output is a portable event lineage graph plus authority and termination state. It is evidence reconstruction, not workflow execution.

## CLI

```bash
jep-runtime create-event --type J --actor human:alice --subject agent:planner \
  --agent-id agent:planner \
  --scope-json '{"actions":["read"],"resources":["repo:jep"]}' \
  --intent-json '{"task":"summarize JEP"}' \
  --archive archive.jsonl

jep-runtime verify event.json
jep-runtime archive-verify archive.jsonl
jep-runtime replay archive.jsonl
jep-runtime conformance-test
```

## Conformance matrix

| Capability | Runtime check |
| --- | --- |
| Canonicalization | Stable UTF-8 JSON with sorted keys and normalized strings |
| Deterministic hashing | SHA-256 over canonical event without `event_hash` |
| Delegation semantics | Parent/child scope and expiration checks |
| Verification semantics | Hash, nonce, timestamp, profile, and chain integrity checks |
| Profile compatibility | Neutral `ProfileAdapter` contract with mock OAuth/OIDC, X509, DID/VC, Local IAM labels |
| Replay correctness | Archive replay must re-verify the full chain and emit lineage graph/state |

`jep-runtime conformance-test` emits test vectors, mock signed vectors, and a compatibility report.

## Correspondence with the JEP draft

| Draft primitive / concept | Runtime implementation |
| --- | --- |
| `J` Judgment | `EventType.JUDGMENT` and `create_event("J", ...)` |
| `D` Delegation | `delegate_authority()`, scoped delegation events, `verify_delegation_chain()` |
| `T` Termination | `EventType.TERMINATION`, replayed into `termination_state` |
| `V` Verification | `verify_event()`, `verify_chain()`, `verify_replay()`, verification events |
| Replay protection | Required `nonce` and duplicate nonce validation |
| Signed/verifiable event format | Immutable hashed event model plus mock profile references |
| Optional profiles | `ProfileAdapter` interface; provider-neutral mock adapter |
| Append-only receipts | JSONL archive with chain verification on replay |

## Repository structure

```text
jep_runtime/
  core/                 # immutable event model and JSON schema generation
  events/               # event factories
  canonicalization/     # deterministic JSON + SHA-256 hashing
  delegation/           # authority propagation and scope validation
  verification/         # event, chain, replay, tamper, profile verification
  profiles/             # provider-neutral profile adapter interface and mock adapter
  archive/              # append-only JSONL archive runtime
  replay/               # lineage graph and termination replay
  conformance/          # conformance vectors and matrix
  cli/                  # jep-runtime command line entry point
  schemas/              # generated JSON schema
examples/               # example event scenarios
tests/                  # executable conformance/runtime tests
```

## Limitations

- Signatures are mock/reference only.
- Profile adapters do not verify real OAuth/OIDC, X509, DID/VC, or IAM credentials.
- No blockchain, distributed consensus, real payment execution, or production key management is included.
- The runtime enforces executable protocol invariants, not legal liability, governance policy, or workflow lifecycle orchestration.

## Runtime governance extension points

- Replace `MockProfileAdapter` with production credential adapters.
- Add signature suites while preserving the canonicalization boundary.
- Add draft-version-specific schema adapters without changing the pinned v06 J/D/T/V primitive meaning.
- Add draft-version-specific schema adapters without changing J/D/T/V primitive meaning.
- Publish conformance vectors for independent implementations.
- Add governance-specific validation modules outside the core minimal runtime.

## Runtime and verification notes

See [HARDENING.md](HARDENING.md) for supported behavior, regression checks, and compatibility boundaries.
