Skip to content

Commit cf26a2f

Browse files
committed
docs(adr): restore ADR 0018 rules and proposal modality from review
Restore the may-not sink rule, the leave-the-machine schema rule, the await-point regression scope, the migration-order obligations, the scopeId reason, the sink-list rule and the derived-set rule. Word the proposal as proposed and link the full proposal at a pinned commit.
1 parent cd6cff5 commit cf26a2f

1 file changed

Lines changed: 20 additions & 13 deletions

File tree

‎docs/adr/0018-unified-event-journal.md‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
Proposed (2026-07-24; revised the same day after architecture review).
66
Nothing in this proposal is implemented.
7+
The [full proposal at the base commit](https://github.com/callstack/agent-device/blob/e35d0d496fb820d57d95fcad1b6b62dfa9962abb/docs/adr/0018-unified-event-journal.md) keeps the inventory and the per-step plan.
78

89
## Context
910

@@ -43,13 +44,15 @@ The contracts package would own the catalog and host-kit would own the journal r
4344
The diagnostics scope would become the single journal append point for diagnostics, agent-cost tallies, session lifecycle events, and replay traces.
4445
On append, the journal would stamp `ts`, `requestId?`, `session?`, and `command?`, redact `data`, buffer the event, and tally `phaseCounts` before offering it to sinks.
4546
Emitters would state facts without branching on consumers.
46-
No sink could write a journal-owned event that did not pass through the journal.
47+
All consumer-conditional logic would live in the sink.
48+
No sink may write an event that did not pass through the journal.
4749

4850
The existing request scope would remain, including CLI entry, daemon request handling, and fatal catch-all.
4951
Idle reap and daemon shutdown would open explicit short-lived session-scoped teardown scopes without a `requestId`.
5052
A teardown-recorded `close` action must continue to produce an `action.recorded` entry when no request is active.
5153

5254
Sinks would be explicitly registered at scope construction, with no dynamic subscription.
55+
Each entry point would list its sinks in one place, statically enumerable.
5356
The journal would invoke them synchronously in registration order.
5457
Each invocation would be best-effort: a sink error would be swallowed and must not affect the buffer, other sinks, or the request.
5558
A sink may queue its own I/O.
@@ -62,10 +65,10 @@ Only the sink list and concurrency-safe aggregation state would be shared.
6265
The `phaseCounts` tally would remain request-global so agent-cost spans shards.
6366
`updateDiagnosticsScope` would mutate only the current scope, and each mid-flight rebind would affect that shard's clone.
6467
The attempt trace binding would end with the fork; trace events with no bound destination would be dropped.
65-
This prevents cross-routing between parallel nested dispatches.
68+
This would prevent cross-routing between parallel nested dispatches.
6669

6770
Each request, teardown, and fork scope would carry a `scopeId` in its event envelope.
68-
A fork would also carry its parent's `scopeId` as `parentScopeId`.
71+
A fork would also carry its parent's `scopeId` as `parentScopeId`, so a future exporter could emit parent-child spans from envelope fields alone, without changing the envelope or emit sites.
6972
Cross-process correlation would remain `requestId`.
7073
An exporter and a W3C `traceparent`-style request metadata field are deferred to a later ADR.
7174

@@ -74,16 +77,16 @@ The proposed sinks would have these responsibilities:
7477
- The debug stream sink would preserve the existing live writer and `liveWrittenEventCount` flush watermark.
7578
- The session event log sink would consume `session-lifecycle` kinds, retain the existing presentation builders and serialized write queue, and write `events.ndjson` v1.
7679
Rotation would remain size-capped to one retained generation.
77-
The sidecar records each retained generation's first absolute line index, line count, and first-line digest.
78-
The reader verifies these values against the files before answering.
79-
The sidecar is not a cache and cannot be regenerated from entries.
80+
The retention window's sidecar, on which `events` cursor identity depends, would record each retained generation's first absolute line index, line count, and first-line digest.
81+
The reader would verify these values against the files before answering.
82+
The sidecar would not be a cache and cannot be regenerated from entries.
8083
A sink that owns the file also owns this contract.
8184
- The replay trace sink would consume `replay-trace` kinds, map legacy `type` values, and use the bound per-attempt destination in place of both append helpers.
8285
- Agent-cost would derive its existing `phaseCounts` projection from the `runner-round-trip` trait.
8386

8487
Session state remains owned by its stores.
8588
`recordActionEntry` would still push to `session.actions` first, and `action.recorded` would remain a projection of that push.
86-
The journal is observability, not a source of truth.
89+
The journal would be observability, not a source of truth.
8790
Session state, replay provenance, and repair watermarks must not be rebuilt from events.
8891

8992
### Progress and usage
@@ -92,13 +95,14 @@ Progress streaming would remain unchanged and transport-owned.
9295
Its typed wire serializer and cancellation behavior would not pass through the generic journal.
9396
If a future feature needs journal visibility, it can separately opt in to a mirror emit of a cataloged kind; the wire path must not be rerouted.
9497

98+
Anything that would leave the machine must go through the closed `UsageRecord` schema.
9599
A later opt-in usage sink would project `session-lifecycle` events into a closed `UsageRecord`.
96100
It would use an allowlist by construction, not redaction of rich data.
97101
Its fields would be command or action from the CommandDescriptor registry; `ok` or a typed error code; `durationMs`, `runnerRoundTrips`, `nodeCount`, `platform`, and `appleOs`; flag names without values; and a hashed session identity with a per-session sequence number.
98102
Positionals, selectors, labels, fill text, snapshot content, and error messages would be unrepresentable.
99103
Sequence and anti-pattern detection would be downstream, never emission-side.
100104
A local stats read would come first and opt-in export later.
101-
The sink follows the session lifecycle migration; this proposal fixes its schema discipline only.
105+
The sink would follow the session lifecycle migration; this proposal fixes its schema discipline only.
102106

103107
### Compatibility and redaction
104108

@@ -122,11 +126,11 @@ A wire name change remains a breaking change for log consumers, even though an i
122126
Reads must fail with `EVENT_LOG_CURSOR_EXPIRED` or `EVENT_LOG_WINDOW_UNVERIFIED` when they cannot place a cursor.
123127
- A multi-attempt `test` run must write each attempt trace to its own file with legacy `type` values.
124128
An unbound trace event must be dropped.
125-
A concurrent nested-action regression must run sharded attempts in parallel with nested dispatch that rebinds `session` and `logPath`, and prove shard isolation for replay traces, per-request diagnostics, and each session event log including its retained generation, without cross-writes or drops after `await` points.
129+
A concurrent nested-action regression must run sharded attempts in parallel with nested dispatch that rebinds `session` and `logPath`, and prove shard isolation for replay traces, per-request diagnostics, and each session event log including its retained generation, without cross-writes or drops, including for events emitted after `await` points.
126130
- Tests must verify sink ordering, error isolation, and parity of the runner-round-trip trait with the current literal list.
127131
- A redaction fixture must prove that sensitive `data` reaches no journal-owned output.
128132
- A type or test gate must prove every `UsageRecord` field is numeric, an enum from its owning registry, or a hash, and reject open-string fields.
129-
- A lint-style test must prohibit production derived-set selection by kind-name substrings.
133+
- Production code must not select events by kind-name substrings; a lint-style test would enforce this for the derived-set helpers.
130134
Layering checks must preserve the contracts and host-kit ownership boundary without back-edges.
131135

132136
## Alternatives considered
@@ -138,17 +142,20 @@ A wire name change remains a breaking change for log consumers, even though an i
138142
- An `EventEmitter` or pub-sub bus: rejected because implicit subscriptions hide listeners and causality.
139143
- Event sourcing: rejected because correctness would depend on telemetry and existing state owners have their own invariants.
140144
- A process-global fallback scope: rejected because it makes scope selection environment-dependent and hides missing-scope bugs.
141-
- Type phases without unifying channels: useful as a first step, but it leaves duplicate envelopes, inconsistent redaction, and three write paths.
145+
- Type phases without unifying channels: rejected as a stopping point and kept as the first migration step, because alone it leaves duplicate envelopes, inconsistent redaction, and three write paths.
142146
- Merge upload progress or app events: rejected because the former is a local byte-counter callback and the latter is a deep-link builder, not an event channel.
143147

144148
## Consequences
145149

146150
The proposed journal would support request tracing by `requestId` and teardown tracing by `session`, while progress remains observable on the wire.
147151
New observability consumers could use sinks without new vocabularies or emit sites.
148152
The migration would remove the dead `traceLogPath` option, duplicate redaction pass, and unredacted replay helper.
149-
Replay redaction is the declared visible output change.
150-
The migration is wide and adds one synchronous sink-dispatch loop per event.
153+
Replay redaction would be the declared visible output change.
154+
The migration would be wide and would add one synchronous sink-dispatch loop per event.
151155

152156
The proposed migration is incremental: catalog and typed kinds first; then the sink seam, debug stream, and agent-cost; then the session event log and teardown scopes; then the replay sink and fork isolation.
157+
Byte-compatibility fixtures would land with the sink seam, before any sink owns a write.
158+
The fork primitive would land with its concurrent-shard regression.
159+
The replay redaction change would ship with the replay sink, in one change with its fixture update and changelog entry.
153160
Each step would pass all checks when it merges and be independently useful.
154161
The `events` command would retain its paging contract, including typed cursor-expiry and window-verification errors.

0 commit comments

Comments
 (0)