Skip to content

Commit bd4fd68

Browse files
committed
docs(adr): accept existing old-reader errors in ADR 0020
An old reader cannot learn a new error from a later codec. The traced path already fails before platform execution with SESSION_NOT_FOUND or COMMAND_FAILED (generic-route-runtime-missing), wrapped as REPLAY_DIVERGENCE. The proposal now accepts these errors for old readers and keeps INVALID_ARGS for readers that ship with the fragment codec. Decided with the maintainer.
1 parent e32a686 commit bd4fd68

1 file changed

Lines changed: 6 additions & 5 deletions

File tree

‎docs/adr/0020-composable-recorded-fragments.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ Consequently, the design must solve four boundaries together:
6969
A new reader consumes that guard during preflight.
7070
An old reader treats the guard as an unknown action.
7171
The required safety property is failure before platform execution, before a root `open` or any known prefix.
72-
The current request path does not prove an `INVALID_ARGS` format rejection; see Annotation compatibility and versioning.
72+
An old reader fails with its existing errors, not `INVALID_ARGS`; see Annotation compatibility and versioning.
7373
Other fragment metadata and references remain reserved comments.
7474
Thus old readers ignore those annotations, and do not silently flatten the composition.
7575
7. **Native fragment repair is explicit re-recording.**
@@ -101,7 +101,7 @@ But these invariants are fixed:
101101
A composed native parent uses the corresponding `composition-v1` guard as its first executable line, before root `open` or any `include`.
102102
An old reader parses either guard as an unknown action.
103103
The required safety property is failure before platform execution.
104-
The current request path returns session-dependent errors; see Annotation compatibility and versioning for the evidence gap.
104+
An old reader returns its existing, session-dependent errors; see Annotation compatibility and versioning.
105105
The fragment has no `open`, `close`, or hidden launch action.
106106
The writer always emits the effective `context platform` and `target`.
107107
A parser rejects a fragment that is missing either constraint.
@@ -546,12 +546,13 @@ These are responses for the guard request, not the outer replay response.
546546
The replay adapter wraps this dispatch failure as `REPLAY_DIVERGENCE`.
547547
The replay engine stops at the failed action before a later root `open`, known prefix, or expanded child body.
548548

549-
**Open evidence gap:** this trace proves failure before platform execution for an unknown guard that reaches generic dispatch.
550-
It does not prove the specified `INVALID_ARGS` format rejection for old readers.
549+
This trace proves failure before platform execution for an unknown guard that reaches generic dispatch.
551550
Admission can resolve a device for lock and provider selection; that resolution reads the device inventory and runs no command.
552551
This trace does not cover failures during admission.
553552
A new fragment codec cannot change an old reader's behavior.
554-
**Maintainer question:** should the old-reader contract accept these existing errors, or retain `INVALID_ARGS` as an unresolved requirement?
553+
Thus the old-reader contract accepts these existing errors: `SESSION_NOT_FOUND`, or `COMMAND_FAILED` with reason `generic-route-runtime-missing`, wrapped as `REPLAY_DIVERGENCE`.
554+
The contract does not require `INVALID_ARGS` from an old reader.
555+
A reader that ships with the fragment codec would refuse an unknown or malformed guard with `INVALID_ARGS` during source preflight.
555556
An old reader that gets an unguarded legacy `.ad` retains its existing behavior.
556557
This includes the possibility that it executes a known prefix before a later unknown command.
557558
That legacy case is explicitly outside the v1 composed-artifact acceptance contract, and it is not safety evidence.

0 commit comments

Comments
 (0)