docs: clarify parser ownership and reader contracts

This commit is contained in:
morluto committed 2026-11-18 22:34:45 -05:00
1 parent 2b7d54257f
commit a6469719ce
9 files changed
+58 -15

No files matched your search

+5
View File
@@ -4,6 +4,11 @@ Use the [documentation directory](../README.md) to find existing material before
adding another guide. Preserve one canonical owner for each contract or workflow;
link to that owner instead of copying its claims into several guides.
When a contract changes, update its owning page with the implementation. Check
the examples and recovery steps in related guides against the supported CLI
and MCP entry points. Link guides to the section that owns the shared behavior
so readers can reach it from the task they are performing.
## Choose a destination
| Document | Destination |
+4 -1
View File
@@ -920,7 +920,10 @@ For ZIP extraction, replace the pathname after inventory reader close while the
admitted root descriptor remains owned. Verify that identical member bytes in a
different carrier, a directory, or a missing pathname cannot switch the
materialized source. Exercise descriptor close failure and retry before output
publication.
publication. Inject a producer finalization failure after its output sink
closes and verify that the consumer observes the failure. Successful EOF
requires the producer to settle successfully, even when all output bytes have
arrived.
Use explicit abort reasons and assert their identity at admission and after
provider completion, alongside retained observations and cleanup state.
Include a physical I/O failure reused as the abort reason and genuine
+6
View File
@@ -271,6 +271,12 @@ 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.
When one operation can show partial results and another requires a complete
document, share the grammar and give each operation an explicit policy for
handling diagnostics. Preserve source spelling and offset units alongside any
normalized lookup value. Verify both operations with the same authored inputs
and independently specified expectations. See [boundary regressions](testing.md#boundary-regressions).
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.