You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit cf26a2f
Browse filesBrowse the repository at this point in the historyBrowse files
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.
Copy file name to clipboardExpand all lines: docs/adr/0018-unified-event-journal.md
+20-13Lines changed: 20 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,7 @@
4
4
5
5
Proposed (2026-07-24; revised the same day after architecture review).
6
6
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.
7
8
8
9
## Context
9
10
@@ -43,13 +44,15 @@ The contracts package would own the catalog and host-kit would own the journal r
43
44
The diagnostics scope would become the single journal append point for diagnostics, agent-cost tallies, session lifecycle events, and replay traces.
44
45
On append, the journal would stamp `ts`, `requestId?`, `session?`, and `command?`, redact `data`, buffer the event, and tally `phaseCounts` before offering it to sinks.
45
46
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.
47
49
48
50
The existing request scope would remain, including CLI entry, daemon request handling, and fatal catch-all.
49
51
Idle reap and daemon shutdown would open explicit short-lived session-scoped teardown scopes without a `requestId`.
50
52
A teardown-recorded `close` action must continue to produce an `action.recorded` entry when no request is active.
51
53
52
54
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.
53
56
The journal would invoke them synchronously in registration order.
54
57
Each invocation would be best-effort: a sink error would be swallowed and must not affect the buffer, other sinks, or the request.
55
58
A sink may queue its own I/O.
@@ -62,10 +65,10 @@ Only the sink list and concurrency-safe aggregation state would be shared.
62
65
The `phaseCounts` tally would remain request-global so agent-cost spans shards.
63
66
`updateDiagnosticsScope` would mutate only the current scope, and each mid-flight rebind would affect that shard's clone.
64
67
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.
66
69
67
70
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.
69
72
Cross-process correlation would remain `requestId`.
70
73
An exporter and a W3C `traceparent`-style request metadata field are deferred to a later ADR.
71
74
@@ -74,16 +77,16 @@ The proposed sinks would have these responsibilities:
74
77
- The debug stream sink would preserve the existing live writer and `liveWrittenEventCount` flush watermark.
75
78
- The session event log sink would consume `session-lifecycle` kinds, retain the existing presentation builders and serialized write queue, and write `events.ndjson` v1.
76
79
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.
80
83
A sink that owns the file also owns this contract.
81
84
- 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.
82
85
- Agent-cost would derive its existing `phaseCounts` projection from the `runner-round-trip` trait.
83
86
84
87
Session state remains owned by its stores.
85
88
`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.
87
90
Session state, replay provenance, and repair watermarks must not be rebuilt from events.
88
91
89
92
### Progress and usage
@@ -92,13 +95,14 @@ Progress streaming would remain unchanged and transport-owned.
92
95
Its typed wire serializer and cancellation behavior would not pass through the generic journal.
93
96
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.
94
97
98
+
Anything that would leave the machine must go through the closed `UsageRecord` schema.
95
99
A later opt-in usage sink would project `session-lifecycle` events into a closed `UsageRecord`.
96
100
It would use an allowlist by construction, not redaction of rich data.
97
101
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.
98
102
Positionals, selectors, labels, fill text, snapshot content, and error messages would be unrepresentable.
99
103
Sequence and anti-pattern detection would be downstream, never emission-side.
100
104
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.
102
106
103
107
### Compatibility and redaction
104
108
@@ -122,11 +126,11 @@ A wire name change remains a breaking change for log consumers, even though an i
122
126
Reads must fail with `EVENT_LOG_CURSOR_EXPIRED` or `EVENT_LOG_WINDOW_UNVERIFIED` when they cannot place a cursor.
123
127
- A multi-attempt `test` run must write each attempt trace to its own file with legacy `type` values.
124
128
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.
126
130
- Tests must verify sink ordering, error isolation, and parity of the runner-round-trip trait with the current literal list.
127
131
- A redaction fixture must prove that sensitive `data` reaches no journal-owned output.
128
132
- 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.
130
134
Layering checks must preserve the contracts and host-kit ownership boundary without back-edges.
131
135
132
136
## Alternatives considered
@@ -138,17 +142,20 @@ A wire name change remains a breaking change for log consumers, even though an i
138
142
- An `EventEmitter` or pub-sub bus: rejected because implicit subscriptions hide listeners and causality.
139
143
- Event sourcing: rejected because correctness would depend on telemetry and existing state owners have their own invariants.
140
144
- 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.
142
146
- 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.
143
147
144
148
## Consequences
145
149
146
150
The proposed journal would support request tracing by `requestId` and teardown tracing by `session`, while progress remains observable on the wire.
147
151
New observability consumers could use sinks without new vocabularies or emit sites.
148
152
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.
151
155
152
156
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.
153
160
Each step would pass all checks when it merges and be independently useful.
154
161
The `events` command would retain its paging contract, including typed cursor-expiry and window-verification errors.
0 commit comments