docs(dev): clarify parser ownership and boundary verification

This commit is contained in:
morluto committed 2026-11-18 21:36:51 -05:00
1 parent b1a390fcee
commit 72be66d050
2 files changed
+22

No files matched your search

+7
View File
@@ -737,6 +737,13 @@ consumers. Add [lifecycle regressions](#lifecycle-regressions) when resource
ownership or finalization changes; a single malformed fixture cannot establish
the whole contract.
When consolidating interpretation across consumers, use the same authored
input and an independently specified expected fact at the boundary where
each consumer previously made its own decision. Allow differences in
recovery or display when those belong to the consumer. For generated
installers and verifiers, exercise the emitted artifact in its supported
runtime so the test covers the code that actually receives the input.
| Failure class | Regression that catches it |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Format assumptions | Pair valid padding, offsets, or names containing delimiters with malformed input. Identify the producer revision when behavior varies by version; an unrelated runtime API's range is not an on-disk format limit. |
+15
View File
@@ -262,6 +262,21 @@ activation independently of readiness. An owned registration may be disabled
or stale; unresolved ownership remains unknown. Consumers use those facts
instead of reclassifying the raw command.
Keep the reader's observation independent of the operation that needs it.
For example, the Evidence file reader can recognize the shape of an
analysis snapshot before authenticating it. Import and comparison can
recommend different next steps while reporting the same observed kind.
The reader also retains disagreements in the input. If two observed header
fields conflict, carry that uncertainty forward before projecting the fields
into a single value. A command launcher likewise needs the parser's token
boundaries so an option value cannot select a transport mode.
Give each nested parser the admitted extent of its containing record.
Retain the source offset and the reason when a field is malformed or its
encoding is unsupported. A stream may need more bytes to complete a frame.
A completed artifact with the same missing bytes has truncated data. Carry
that distinction into coverage and preserve any independently observed facts.
When consumers in different runtimes receive raw input independently, reuse
the same reader where the runtime is available. If separate implementations
are needed, prefer generating them from one authored set of parsing rules.