Process Intelligence Event Contract

A tool-neutral event contract and reference analyzer for turning workflow traces into measurable, auditable process intelligence.

Created by Tristan Springmeyer (@tristan-nextcz) and organization-owned by Next Citizen LLC for durable governance.

The contract captures enough structure to answer practical operating questions:

1. Where does work spend time?
2. Which activities fail or repeat?
3. Where do handoffs occur?
4. Which system or actor produced each observation?
5. What evidence supports the event?

It is deliberately smaller than a process-mining platform. Teams can emit the contract from existing systems, inspect it as JSON Lines, and validate the trace before choosing a visualization, analytics, or automation layer.

Quick start

Analyze the included service-request trace with Python 3.11 or later:

python3 scripts/analyze.py examples/service-requests.jsonl
python3 -m unittest discover -s tests

No third-party packages are required.

Event model

Each line is one immutable process observation:

{
  "event_version": "0.1",
  "event_id": "evt-sr-100-validate-complete-2",
  "case_id": "sr-100",
  "activity": "validate request",
  "lifecycle": "complete",
  "occurred_at": "2026-07-27T09:18:00Z",
  "sequence": 6,
  "actor": {
    "kind": "agent",
    "id": "validation-service"
  },
  "system": "request-hub",
  "correlation_id": "corr-sr-100",
  "parent_event_id": "evt-sr-100-validate-start-2",
  "evidence": [
    {
      "kind": "receipt",
      "locator": "request-hub://sr-100/validation/2"
    }
  ],
  "attributes": {
    "rule_set": "standard-v3"
  }
}

The canonical schema is schemas/process-event.schema.json.

Lifecycle

The reference analyzer recognizes:

start -> complete | fail | cancel

It also accepts standalone decision and handoff events. A terminal activity event must pair with an earlier unmatched start for the same case and activity. Repeated starts after an activity has already closed are counted as rework.

Derived evidence

The analyzer reports:

• event and case counts;
• closed and in-flight activity instances;
• complete, failed, and cancelled outcomes;
• average and median cycle time;
• activity-level duration ranking;
• repeated activity instances and cases with rework; and
• decisions and handoffs.

These are observations from the supplied trace, not claims about process causality. A slow activity is a place to investigate, not proof of the root cause.

Validation rules

Beyond field validation, the reference implementation checks that:

• event identifiers are unique;
• sequence numbers and timestamps do not move backward within a case;
• a case keeps one correlation identifier;
• parent events exist earlier in the same case;
• terminal activity events close an unmatched start; and
• attributes contain only JSON scalar values.

Why a contract

Process intelligence becomes useful when operating evidence can cross system boundaries without losing meaning. A stable event contract separates:

• instrumentation from visualization;
• observation from inference;
• workflow state from presentation; and
• measured friction from the decision about what to change.

That makes a pilot easier to inspect, compare, govern, and scale.

Related work

• Agentic Context Contract defines bounded objective, source authority, action authority, and exit evidence for agent work.
• Agent Bridge provides local-first, evidence-oriented coordination across coding-agent tools.

License

MIT