Metadata-Version: 2.4
Name: governed-event
Version: 0.1.0
Summary: Governed Event Envelope (GEE) v0.1 + API-E Workflow Provenance Ontology v0.1.
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/governancecommons/governed-event
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-ulid
Requires-Dist: base58
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# governed-event

Governed Event Envelope v0.1 + API-E Workflow Provenance Ontology. **Apache 2.0.**

GEE is a portable, interoperable record structure for governed events across any operational namespace. It answers the questions every audit trail needs answered — when, where, who, under what authority, about what, with what result — in a single, tamper-evident, version-stamped record.

API-E is a workflow provenance ontology built on top of GEE, defining how work moves through priority (Eisenhower), intake, action, and storage lifecycle decisions.

---

## Depends on

[governancecommons/time-loc](https://github.com/governancecommons/time-loc) — every GEE record embeds a complete time.loc record as its mandatory temporal-spatial anchor. Copies of `time_loc.py` and `time_loc_compact.py` are vendored in `python/` for standalone use.

---

## Specs

| Spec | File |
| --- | --- |
| Governed Event Envelope v0.1 | [spec/governed-event-envelope-v0.1.md](spec/governed-event-envelope-v0.1.md) |
| API-E Workflow Provenance Ontology v0.1 | [spec/api-e-workflow-provenance-v0.1.md](spec/api-e-workflow-provenance-v0.1.md) |

Governed by [eco](https://github.com/governancecommons) PASS 0051.01 and PASS 0052.01.

---

## Python reference implementation

### Dependencies

```
pip install python-ulid base58
```

### Produce a governed event

```python
import sys
sys.path.insert(0, "python")  # if running from repo root

from governed_event import produce

# state_transition in the api_e namespace
event = produce(
    system_namespace="api_e",
    ontology_version="api-e/0.1",
    event_type="state_transition",
    actor_id="human:jj-ervin",
    actor_type="human",
    authority_basis="human_direct",
    subject="task:PROJ-2026-047",
    outcome="success",
    geo_city="Longview",
    geo_region="WA",
    geo_country="US",
    geo_source="declared",
    previous_state="aligned",
    new_state="actions",
)
print(event.to_dict())
```

### Validate a record

```python
from governed_event_validator import validate_governed_event_v0_1, validate_and_annotate

record = event.to_dict()
violations = validate_governed_event_v0_1(record)
if violations:
    print("invalid:", violations)
else:
    print("valid")

# Or annotate the record with a validation block
annotated = validate_and_annotate(record)
print(annotated["validation"])
```

### Validate an API-E record's transition

```python
from governed_event_api_e_validator import validate_api_e_v0_1, transition_warnings

# Run GEE structural validation first, then API-E transition validity
record = event.to_dict()
violations = validate_governed_event_v0_1(record) + validate_api_e_v0_1(record)
if violations:
    print("invalid:", violations)
else:
    print("valid — warnings:", transition_warnings(record))
```

---

## Event-type profiles

| event_type | Use | Required conditional fields |
| --- | --- | --- |
| state_transition | Move between states | previous_state, new_state |
| priority_decision | Record rationale for a priority decision | decision_rationale |
| pipeline_move | Move through intake stages | previous_state, new_state |
| archive_event | Storage lifecycle event | storage_target, retention_class |
| agent_action | Autonomous/delegated agent action | policy_context (when autonomous/delegated) |
| observation | Capture a signal before commitment | none |
| handoff_event | Transfer of work or authority | source_actor, target_actor, handoff_basis |

---

## API-E namespace

API-E records are GEE records with:

```yaml
system_namespace: api_e
ontology_version: api-e/0.1
envelope_version: governed-event/0.1
```

API-E defines four workflow layers:

| Layer | Values |
| --- | --- |
| eisenhower | do, decide, delegate, delete |
| intake | intake, interpret, integrate, initiate |
| action | aligned, actions, activities, archived |
| para | projects, areas, resources, archives |

See [spec/api-e-workflow-provenance-v0.1.md](spec/api-e-workflow-provenance-v0.1.md) for transition rules.

---

## Files

| File | Description |
| --- | --- |
| `spec/governed-event-envelope-v0.1.md` | GEE v0.1 specification |
| `spec/api-e-workflow-provenance-v0.1.md` | API-E v0.1 ontology specification |
| `python/governed_event.py` | Producer — frozen dataclass + `produce()` factory |
| `python/governed_event_validator.py` | GEE structural validator — returns list of violation strings |
| `python/governed_event_api_e_validator.py` | API-E validator — namespace, layer vocabulary, transition validity per PASS 0052.01 |
| `python/test_governed_event_api_e_validator.py` | API-E validator transition tests |
| `python/governed_event_schema.json` | JSON Schema draft-07 |
| `python/governed_event_examples.json` | Canonical examples (one per event-type profile) |
| `python/time_loc.py` | Vendored from governancecommons/time-loc |
| `python/time_loc_compact.py` | Vendored from governancecommons/time-loc |

---

## License

Apache 2.0 — see [LICENSE](LICENSE).

Copyright 2026 Osprey Strategic Holdings LLC.
