Skip to content

Commit 0d83062

Browse files
committed
docs(adr): state the attempted flush and field conditions in ADR 0010
withDiagnosticsScope (packages/host-kit/src/internal/diagnostics.ts) runs no finalizer. Only finalizeThrownRequestError (request-router.ts) flushes, and it is reached by thrown errors alone: the token refusal in runRequestWithinScope is a returned normalizeError output without context, and flushDiagnosticsToSessionFile returns no record for zero events or a write failure, so an in-scope thrown error can still omit logPath. State that a thrown request error attempts one forced flush, diagnosticId requires an active scope, logPath appears only when the flush produces a file, and returned or pre-scope failures may omit both fields. The remote logPathUnavailable rule and the no-secrets rule are unchanged. Follow-up qualification on discussion_r4306650954.
1 parent 278baaa commit 0d83062

1 file changed

Lines changed: 9 additions & 6 deletions

File tree

‎docs/adr/0010-error-system.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
- If the per-code default hint would mislead, supply a hint. If the default suffices, omit the hint.
1717
- When you wrap an error, preserve an existing hint and the cause chain.
1818
- Every consumer surface must carry at least code, message, and hint. Rehydration helpers copy all fields.
19-
- A failed request inside a request diagnostics scope always flushes diagnostics. A failure before that scope opens may omit `diagnosticId` and `logPath`. Messages must not embed raw stderr dumps or secrets.
19+
- Thrown request errors attempt one final diagnostics flush. `diagnosticId` requires an active request diagnostics scope, and `logPath` appears only when that flush produces a file. Returned or pre-scope failures may omit both fields. Messages must not embed raw stderr dumps or secrets.
2020

2121
## Context
2222

@@ -78,11 +78,14 @@ Nothing documented the conventions, so each new site decided them again.
7878
- Events timeline.
7979
Rehydration helpers (`throwDaemonError`, `toDaemonHttpRpcError`) copy all fields.
8080
`NormalizedError` hoists the typed signals, so `--json` consumers see them.
81-
6. **Observability.** A failed request inside a request diagnostics scope always flushes diagnostics.
82-
Inside that scope on the local machine, the error carries a `diagnosticId` and an ndjson `logPath`.
83-
The router opens the scope at `handleRequestOnLedger` (`packages/daemon/src/server/request-router.ts`).
84-
A failure before it opens, such as malformed RPC method params rejected in
85-
`packages/daemon/src/server/http/http-rpc-methods.ts`, returns an envelope that omits both fields.
81+
6. **Observability.** Thrown request errors reach `finalizeThrownRequestError`
82+
(`packages/daemon/src/server/request-router.ts`), which emits a `request_failed` diagnostic and attempts one forced
83+
flush. It attaches a `diagnosticId` only when a request diagnostics scope is active, and an ndjson
84+
`logPath` only when that flush produces a file; the flush returns no record for zero events or a write failure.
85+
`withDiagnosticsScope` itself runs no finalizer.
86+
A returned (not thrown) failure, such as the token refusal in `runRequestWithinScope`, and a pre-scope
87+
failure, such as malformed RPC method params rejected in
88+
`packages/daemon/src/server/http/http-rpc-methods.ts`, omit both fields.
8689
On a remote path, the client keeps only a `logPath` it can open.
8790
When it cannot produce one, `logPathUnavailable` replaces `logPath` and names the reason (#1801).
8891
Daemon-side diagnostics are under the session state dir.

0 commit comments

Comments
 (0)