Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

docs: clarify parser authority and compatibility evidence

morlutoa281455f0b83
diff --git a/docs/testing.md b/docs/testing.md
index 4fc5755f9..d48e058ba 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 ab4417e9f..96b5f9677 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