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
@@ -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",
+6
View File
@@ -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).
+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.
+14 -4
View File
@@ -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
+6 -3
View File
@@ -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
+6 -4
View File
@@ -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