mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 13:12:26 +00:00
docs: clarify parser ownership and reader contracts
This commit is contained in:
1 parent
2b7d54257f
commit
a6469719ce
9 files changed
+58
-15
No files matched your search
@@ -368,6 +368,11 @@ export const documentationSections = [
|
||||
{
|
||||
text: "Development and verification",
|
||||
items: [
|
||||
{
|
||||
text: "Documentation ownership and authoring",
|
||||
source: "development/documentation.md",
|
||||
route: "/development/documentation",
|
||||
},
|
||||
{
|
||||
text: "Settings and recovery",
|
||||
source: "design/limits-and-recovery.md",
|
||||
|
||||
@@ -156,6 +156,12 @@ Text views decode UTF-8 or strictly valid UTF-16 with a leading byte-order
|
||||
mark. UTF-16 containing a NUL character stays binary. These rules also apply
|
||||
to documents inside gzip and ZIP files and to the exported task verifier.
|
||||
|
||||
Keyfile views trim keys and skip spaces or tabs immediately after the first
|
||||
`=`. The rest of the value is preserved, including trailing whitespace and
|
||||
any additional `=` characters. Entries before the first group use the empty
|
||||
group name. Repeated groups share one view, and the last value for a key in
|
||||
that group wins. Capture and the exported verifier apply the same rules.
|
||||
|
||||
A gzip file is read as the document inside it; see
|
||||
[compressed documents](#compressed-documents).
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -918,6 +918,16 @@ the original observation through `evidence_links` and reports that the
|
||||
provider was not rerun. The original and its available source records remain
|
||||
in the investigation bundle.
|
||||
|
||||
### Use snapshot Evidence in file-based workflows
|
||||
|
||||
Open the matching target with the saved provider and analysis profile, supplying
|
||||
the snapshot as `snapshot_path` to `open_binary`. Then call
|
||||
`export_evidence_bundle` in that MCP session. Use the resulting standalone
|
||||
Evidence bundle with file-based comparison or inspection. When a reader
|
||||
recognizes a snapshot in an Evidence file slot, its diagnostic identifies
|
||||
the observed artifact kind. Restoring the snapshot validates its contents and
|
||||
checks its binding to the target, provider and profile.
|
||||
|
||||
## Import, export and compare Evidence
|
||||
|
||||
Evidence records retain artifact identity, source locations, observations,
|
||||
@@ -946,9 +956,8 @@ records, or one opaque change when you pair them. Use `compare-artifacts`,
|
||||
described at the end of this section, to compare their contents.
|
||||
|
||||
If a selected file looks like an analysis snapshot, comparison reports the
|
||||
wrong artifact kind. To compare its Evidence, restore the snapshot with its
|
||||
matching target, provider and analysis profile, then export a standalone
|
||||
Evidence bundle from that session.
|
||||
wrong artifact kind. Follow the [snapshot Evidence workflow](#use-snapshot-evidence-in-file-based-workflows)
|
||||
to export its Evidence for comparison.
|
||||
|
||||
`--record_pairs` accepts an inline JSON array or the path to a local JSON
|
||||
file containing that array, matching MCP `compare_bundles.record_pairs`. For a
|
||||
@@ -1002,7 +1011,8 @@ from the bundle for every supported view kind. Bundles exported from MCP work
|
||||
for these commands. Its inline source form cannot also select a bundle.
|
||||
An `evidence-file` source accepts a standalone Evidence record or a bundle.
|
||||
When either file input resembles an analysis snapshot, the error identifies
|
||||
the snapshot and directs you to export session Evidence.
|
||||
the snapshot. Follow the [snapshot Evidence workflow](#use-snapshot-evidence-in-file-based-workflows)
|
||||
to export session Evidence.
|
||||
A missing ID is refused with `details.reason: "missing"`;
|
||||
supplying a bundle does not make incompatible Evidence valid for a workflow.
|
||||
`compare-managed-members` keeps its two assembly paths and the
|
||||
|
||||
@@ -43,7 +43,11 @@ unverified.
|
||||
`inspect_android_package` also returns a static inventory of declared
|
||||
activities, aliases, services, receivers and providers from the decoded
|
||||
manifest. The binary XML decoder preserves component class spelling, including
|
||||
`$` in nested classes, without applying JADX class aliases. `declared_name`
|
||||
`$` in nested classes, without applying JADX class aliases. The component
|
||||
inventory and [Apktool metadata](apktool-resource-analysis.md) read the same
|
||||
decoded manifest structure. The document root must be `<manifest>` in no
|
||||
namespace, and the package comes from its unqualified `package` attribute.
|
||||
A missing or empty attribute leaves the package unknown. `declared_name`
|
||||
preserves the decoded source attribute; `name` resolves a
|
||||
relative name only when the manifest package is known and the resolved copy
|
||||
fits the UTF-8 byte budget. An unresolved package or exhausted name budget
|
||||
@@ -63,8 +67,7 @@ references are not expanded at this parser boundary. Repeated inherited
|
||||
values share one inventory-wide byte budget.
|
||||
Provider `android:readPermission` and `android:writePermission` overrides are
|
||||
not projected as separate fields; their presence marks the inventory partial
|
||||
and is called out in `limitations`. Relative component names are not resolved
|
||||
against a manifest package with surrounding whitespace.
|
||||
and is called out in `limitations`.
|
||||
Class-name segments follow DEX `SimpleName` characters, including a leading
|
||||
digit or hyphen, rather than Java source identifier rules. Relative-name
|
||||
expansion does not prove class existence, DEX-version compatibility or runtime
|
||||
|
||||
@@ -125,8 +125,9 @@ and response transport capacity still apply.
|
||||
`access_denied`, while a missing or non-regular selected path reports
|
||||
`invalid_request` with the rejected `path` field.
|
||||
- **Metadata comes from apktool.yml as apktool printed it.** Version codes
|
||||
keep their own spelling (`'7'` versus `7`); `package_name` is read from
|
||||
the decoded manifest, not inferred.
|
||||
keep their own spelling (`'7'` versus `7`). The `package_name` field
|
||||
follows the [decoded manifest rules](android-analysis.md#manifest-component-projection)
|
||||
and preserves the decoded attribute value.
|
||||
The `version: 2.9.0`-or-later header that Apktool 2.9+ and 3 emit selects
|
||||
their single-line string dialect: literal hashes, single quotes, empty
|
||||
strings, and the text `null` stay part of the value; producer backslashes
|
||||
@@ -138,7 +139,9 @@ and response transport capacity still apply.
|
||||
and [string escape owner](https://github.com/iBotPeaches/Apktool/blob/18b5e99cb56ff9451e8aa55b065dcf5bbd616975/brut.j.yaml/src/main/java/brut/yaml/YamlStringEscapeUtils.java#L55-L116).
|
||||
- **The manifest is the decoded text**, bounded at 512 KiB and reported as
|
||||
truncated when larger.
|
||||
- **Strings are projected verbatim.** Escaped entities stay escaped, and
|
||||
- **Strings are projected verbatim.** The root must be `<resources>` in no
|
||||
namespace. Only its direct `<string>` children in no namespace contribute
|
||||
entries. Escaped entities stay escaped, and
|
||||
entries containing nested markup (`<b>`, `<xliff:g>`) are counted as
|
||||
unparsed rather than flattened — the limitation names the examined count.
|
||||
Malformed XML and a wrong document root are whole-document projection
|
||||
|
||||
@@ -35,10 +35,12 @@ with a source that `inspect_analysis_view` also accepts:
|
||||
this session, or `{"kind": "evidence-file", "path": "/absolute/evidence.json"}`
|
||||
for a saved record or bundle. Add `evidence_id` to select one record from a
|
||||
bundle that holds more than one. Complete inline Evidence is still accepted as
|
||||
the third form. The comparison cites the records that the sources resolve to,
|
||||
so all three forms give the same comparison Evidence. A retained reference that
|
||||
the session cannot resolve is refused with `evidence_integrity_mismatch` and
|
||||
`details.reason: "missing"`.
|
||||
the third form. For Evidence stored in a snapshot, follow the
|
||||
[snapshot Evidence workflow](../getting-started/cli.md#use-snapshot-evidence-in-file-based-workflows)
|
||||
before selecting the exported file. The comparison cites the records that the
|
||||
sources resolve to, so all three forms give the same comparison Evidence. A
|
||||
retained reference that the session cannot resolve is refused with
|
||||
`evidence_integrity_mismatch` and `details.reason: "missing"`.
|
||||
|
||||
`compare_artifacts` can also resolve an artifact summary to its exact retained
|
||||
parent in the session, or from the authenticated bundle containing a file-selected
|
||||
|
||||
Reference in new issue
Block a user