# Runtime State Engine and State Change Journal

The Runtime State Engine is the Runtime-owned description and query layer for
Runtime state surfaces. It identifies which module owns a surface, where the
current implementation stores it, whether it is canonical truth or a derived
projection, and whether it affects Runtime Health or the Runtime Action Panel.

The State Change Journal records that a source-of-truth surface changed. It is
not the source of truth. Runtime Health snapshots remain the canonical dashboard
read model, and source modules remain authoritative for their domains.

## Contract

State change records use `runtime-state-change-v1`.

Required fields:

- `schema_version`
- `event_id`
- `sequence`
- `occurred_at`
- `source`
- `surface`
- `change_type`
- `aggregate_type`
- `aggregate_id`
- `changed_surfaces`
- `severity`
- `snapshot_hint`
- `mutates_authority_state`

Optional fields:

- `artifact_ref`
- `correlation_id`
- `causation_id`
- `metadata`

Metadata is bounded and redacted. Secrets, tokens, credentials, approval
secrets, and authorization material must not be written to the journal.

## Boundaries

- The journal is an index/notification aid, not canonical state truth.
- The action timeline remains the audit/timeline surface. It should not be
repurposed as the state-change journal unless audit boundedness and authority
semantics are preserved by design.
- Runtime Health remains a derived snapshot from Runtime-owned state surfaces.
- Socket.IO remains invalidation-only. Socket bridges may consume journal events
  and tell admin clients to refetch GraphQL/Runtime snapshots.
- `.tmp` paths may remain physical storage during migration. They are not the
  conceptual Runtime state API.

## Runtime API

Use these Runtime API/CLI surfaces:

```sh
node ai/runtime/dist/cli.js runtime state-surfaces --json
node ai/runtime/dist/cli.js runtime state-journal --json
node ai/runtime/dist/cli.js runtime state-journal-status --json
node ai/runtime/dist/cli.js runtime state-journal-record --surface runtime_work_session --change-type heartbeat --json
node ai/runtime/dist/cli.js runtime state-journal-validate --json
node ai/runtime/dist/cli.js runtime state-journal-compact --json
```

## Migration Policy

Migrate narrow non-authority state first. Authority-adjacent state such as
approvals, dispatcher results, lifecycle transitions, and leases may emit
journal events only when the owning mutation path is clear and the event write
does not change authority behavior.

File watchers remain compatibility fallback until journal coverage is proven for
the corresponding surface.