Metadata-Version: 2.4
Name: jep-runtime
Version: 0.3.1
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 companion runtime envelope. For signed JEP Core 0.7 wire events use [the SDK](https://github.com/hjs-spec/sdk-py) and [API](https://github.com/hjs-spec/jep-api). Runtime-only fields such as `nonce`, `previous_event_hash`, `delegation_chain`, `authority_scope`, and `verification_state` are profile/runtime state and MUST NOT be presented as JEP Core top-level requirements.

## 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 local runtime `JEPEvent` envelope. This envelope is not the JEP Core wire object.
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 and applies runtime-profile checks such as nonce uniqueness, hash continuity, delegation scope, and profile identity. These are companion runtime rules, not intrinsic JEP Core checks.

## 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 |
| Runtime replay profile | Runtime-envelope `nonce` and duplicate nonce validation; not a JEP Core requirement |
| Core relation | Companion runtime envelope; use JEP SDK/API for JEP Core 0.7 wire events |
| 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

The local reference profile binds every supplied credential to `event.actor`
through `ProfileAdapter.resolve_identity`; lookup failures fail closed. Delegation
helpers accept the delegating actor's `credential_reference` explicitly and never
copy the parent actor's credential. Mock events without credentials remain mock.

A `T` ends its subject's authority within that session, including observed
descendant delegations. Later `J`/`D` use or re-grant in that session is rejected,
and replay removes the revoked authority while retaining all evidence nodes.
`V` evidence can still be recorded. A new session has independent termination
state. This is a local runtime profile rule; deployment trust policy must still
establish who may issue a grant or termination.

- 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 its declared companion-profile/runtime invariants. JEP Core itself does not define this runtime's authority graph, termination cascade, hash-chain, or nonce state. The runtime does not determine legal liability, governance policy, factual truth, or external effect.

## Runtime governance extension points

- Replace `MockProfileAdapter` with production credential adapters.
- Add signature suites while preserving the canonicalization boundary.
- Add explicit wire adapters for JEP Core revisions without redefining Core J/D/T/V semantics.
- 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.
