diff --git a/docs/testing.md b/docs/testing.md index 4fc5755f99..d48e058ba3 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -277,6 +277,15 @@ distinct pair that would collapse if representation tags or scope were lost. For learned identifiers, cover conflicting pairs and reused values in different collections; mappings must remain one-to-one within their declared scope. +For format compatibility, identify the producer revision that establishes each +rule. Include an accepted boundary case beside the rejected case so a stricter +parser cannot pass by refusing both. Keep source-derived behavior, synthetic +fixtures, and executed producer or runtime oracles distinct in validation +reports. A fixture accepted by REA proves its reader behavior; it does not prove +that a real loader accepts the artifact. If multiple producer revisions share a +format identifier but differ in behavior, record that ambiguity rather than +using one installed version as an oracle for all of them. + Packed bridge validation uses Python's standard-library AST and tar readers with `-I -S`: caller-local modules, `PYTHONPATH`, and site startup hooks must not replace those readers or execute during validation. Controlled `ast.py` diff --git a/docs/tool-design.md b/docs/tool-design.md index ab4417e9f3..96b5f96774 100644 --- a/docs/tool-design.md +++ b/docs/tool-design.md @@ -78,6 +78,24 @@ satisfy. A plan without execution does not establish runtime behavior. ceiling and its recovery as described in [admission limits and recovery](design/limits-and-recovery.md). +### Interpret boundary facts once + +The format or protocol reader owns interpretation. Pass its parsed facts and +explicit uncertainty to consumers; do not make adapters reparse display text, +reconstruct omitted values, or infer success from missing diagnostics. + +Keep format recognition separate from provider admission. A recognizable header +can supply useful observations while later structure remains unresolved or a +provider cannot accept the artifact. Report the reason at the affected boundary +without erasing earlier observations or labeling unresolved input malformed. + +Derive validation from the field's own format and revision. A runtime API's +narrower argument range need not constrain a wider on-disk field. A shared layout, +magic, or version label need not identify every constructor or equality rule. +When supported producer revisions differ, retain what the input establishes and +state what it cannot distinguish. Static inspection does not establish that the +artifact can execute successfully. + ## Own the lifecycle For tools that acquire resources, identify the owner and the observations that