From a6469719ce640ad792302b047e006dcfd123c7f2 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:34:03 -0500 Subject: [PATCH] docs: clarify parser ownership and reader contracts --- docs/.vitepress/documentation.ts | 5 +++++ docs/desktop-application-state.md | 6 ++++++ docs/development/documentation.md | 5 +++++ docs/development/testing.md | 5 ++++- docs/development/tool-design.md | 6 ++++++ docs/getting-started/cli.md | 18 ++++++++++++++---- docs/guides/android/android-analysis.md | 9 ++++++--- .../android/apktool-resource-analysis.md | 9 ++++++--- docs/reference/mcp-contracts.md | 10 ++++++---- 9 files changed, 58 insertions(+), 15 deletions(-) diff --git a/docs/.vitepress/documentation.ts b/docs/.vitepress/documentation.ts index 1f56d0cae9..2d2dfd0990 100644 --- a/docs/.vitepress/documentation.ts +++ b/docs/.vitepress/documentation.ts @@ -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", diff --git a/docs/desktop-application-state.md b/docs/desktop-application-state.md index 82cc57b213..05013c21dc 100644 --- a/docs/desktop-application-state.md +++ b/docs/desktop-application-state.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). diff --git a/docs/development/documentation.md b/docs/development/documentation.md index c65efbf314..bb8817f979 100644 --- a/docs/development/documentation.md +++ b/docs/development/documentation.md @@ -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 | diff --git a/docs/development/testing.md b/docs/development/testing.md index d1ed09ffd3..0f038d1624 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -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 diff --git a/docs/development/tool-design.md b/docs/development/tool-design.md index bbbd32daf0..41fad0be33 100644 --- a/docs/development/tool-design.md +++ b/docs/development/tool-design.md @@ -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. diff --git a/docs/getting-started/cli.md b/docs/getting-started/cli.md index d643eacf4a..f2627eca78 100644 --- a/docs/getting-started/cli.md +++ b/docs/getting-started/cli.md @@ -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 diff --git a/docs/guides/android/android-analysis.md b/docs/guides/android/android-analysis.md index 51f9ddbdda..e094508c2b 100644 --- a/docs/guides/android/android-analysis.md +++ b/docs/guides/android/android-analysis.md @@ -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 `` 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 diff --git a/docs/guides/android/apktool-resource-analysis.md b/docs/guides/android/apktool-resource-analysis.md index 49a0a22f22..2060ef4b64 100644 --- a/docs/guides/android/apktool-resource-analysis.md +++ b/docs/guides/android/apktool-resource-analysis.md @@ -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 `` in no + namespace. Only its direct `` children in no namespace contribute + entries. Escaped entities stay escaped, and entries containing nested markup (``, ``) are counted as unparsed rather than flattened — the limitation names the examined count. Malformed XML and a wrong document root are whole-document projection diff --git a/docs/reference/mcp-contracts.md b/docs/reference/mcp-contracts.md index 4258f41fd4..33c92964d2 100644 --- a/docs/reference/mcp-contracts.md +++ b/docs/reference/mcp-contracts.md @@ -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