From 72be66d0509216cdf5c59dc9160de493d451cb8d Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:36:51 -0500 Subject: [PATCH] docs(dev): clarify parser ownership and boundary verification --- docs/development/testing.md | 7 +++++++ docs/development/tool-design.md | 15 +++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/docs/development/testing.md b/docs/development/testing.md index 9b2ecf5e4f..d1ed09ffd3 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -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. | diff --git a/docs/development/tool-design.md b/docs/development/tool-design.md index 0ddae55c75..bbbd32daf0 100644 --- a/docs/development/tool-design.md +++ b/docs/development/tool-design.md @@ -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.