docs: clarify parser coverage and verification ownership

This commit is contained in:
morluto committed 2026-11-19 19:42:28 -05:00
1 parent 0be83b62fc
commit 5664a6fbd4
15 files changed
+119 -115

No files matched your search

+2 -1
View File
@@ -35,7 +35,8 @@ Unblob. FFS file and section discovery applies to FFS2 and FFS3 volumes.
Volumes with other file-system GUIDs retain their header and extent, with the
body reported as unparsed. REA checks the volume header and block map against
the declared volume extent. FFS traversal accounts for volume extensions and
retains valid files after an unusable file header. Malformed FV extension
retains later files when the observed header or state establishes the next
file boundary. Otherwise the remaining bytes stay unparsed. Malformed FV extension
entries and conflicts between `UsedSize` and the claimed erased tail appear as
volume-scoped gaps. Readable FFS files remain selectable. A truncated file body
does not receive a verified checksum verdict. For a file without a body
@@ -214,8 +214,9 @@ candidates. A boundary nested inside another expression or compound assignment
does not establish a direct result binding.
The query declares backward provenance, forward influence, callers, or
ownership and can restrict admitted relation kinds. REA returns every matching
seed and the complete reachable subgraph; callers do not choose node, relation,
depth, function, module, seed-match, or page budgets.
seed and its complete reachable subgraph within the admitted graph. Callers
do not choose node, relation, depth, function, module, seed-match, or page
budgets. Extraction limits and unknowns can still leave coverage partial.
The extractor covers lexical definitions and reads, literal seeds, static
property slots, object reads/writes/spreads/destructuring, closure captures,
@@ -241,6 +242,14 @@ assignment. Computed method keys belong to the enclosing callable; parameter
defaults and method bodies belong to the method. Uncertain later property reads
remain opt-in through `include_ambiguous_dynamic_edges`.
Destructuring retains dependencies from the source slots proved at the time
of the read. A later write does not replace an earlier proved dependency.
A numeric key in an object pattern selects a named property directly.
Nested array patterns can preserve dependencies for later bindings when
element selection is known and iterator closing cannot invoke a return hook.
Holes, accessors, and unknown iteration keep the affected dependencies
uncertain.
Binary, logical, unary, template, conditional, and sequence expressions retain
`influences` edges from supported immediate inputs to the result, then to a
direct declaration, assignment, call argument, or return. These are static
@@ -248,7 +257,8 @@ dependencies, not aliases or proof that the expression executed; conditional
operands and logical-assignment writes carry `conditional: true`. Unsupported
operand dependencies, unmodeled receiving containers, dynamic call results,
and sequence side effects remain unknown. An applicable
unknown makes the trace status `partial` even when a seed was found. Literal
unknown makes the trace status `partial` when no applicable ambiguity takes
precedence, even when a seed was found. Literal
operator operands, direct call arguments and directly returned scalar literals
can also be seeds. Older graphs that only recorded a call-site literal remain
searchable. The offered per-file node capacity also bounds the producer's
@@ -318,7 +328,9 @@ behavioral absence.
Semantic relations use static-inference authority. `resolved` means the static
target identity was unique within admitted analysis; it does not mean the path
executed. Candidate edges are excluded by default, require explicit opt-in, and
keep the result ambiguous. Runtime Evidence can later corroborate an exact
keep the result ambiguous. An exact edge may still be present when other
possible dependencies make the overall trace ambiguous. Runtime Evidence can
later corroborate an exact
mapped candidate, but structural reachability, semantic influence, runtime
observation, and causal proof remain separate claims.
@@ -521,9 +533,10 @@ properties. Dynamic child writes such as `copy[key].value = 2` remain conservati
about which original slot was selected. Object rest
excludes consumed keys, array rest excludes the consumed prefix for known
arrays, and later explicit data properties and methods replace earlier object
spread references. A known array prefix does not expose values from a following
spread. Accessors, custom or uncertain iteration, unknown computed keys, and
unknown spread lengths retain conservative uncertainty.
spread references. A bounded dense inline array spread can supply exact slots
and keep the positions of later elements known. Accessors, sparse or unknown
spread sources, custom or uncertain iteration, and unknown computed keys keep
the affected reads uncertain.
Getter-local aliases of `this`, including direct destructuring and assignments,
retain their receiver when a returned shared reference is written. These writes
invalidate the earlier literal instead of claiming the getter executed or the
@@ -545,8 +558,8 @@ Writes through an object getter's returned receiver retain that uncertainty
when the object is an array element, nested inside mixed object/array
containers, or assigned to a previously declared identifier. Saving the getter
result in an alias does not make its old field values immutable. Known array
indices include holes; an element after a spread has only a minimum possible
index. For these returned-reference writes, unrelated properties and known
indices include holes. After a spread with unknown length, a later element
has only a minimum possible index. For these returned-reference writes, unrelated properties and known
array prefixes remain precise. Accessor applicability uses the shared object
reference owner for literal definition order, own-property shadowing, known
array elements and explicit literal prototypes. Getter invocation effects
+7 -6
View File
@@ -29,12 +29,13 @@ requires an absolute filesystem path and preserves that exact selection:
The inline Evidence result contains the artifact path, SHA-256, and byte length.
`identity` reports `id`, `version`, `authors`, and `description` as present in
the `.nuspec` metadata. For authors and description, NuGet indexes the first
nonempty leaf with a matching local name, ignoring case. The package ID and
version use their case-sensitive names in the metadata namespace. Missing
fields are `null`. The `.nuspec` and OPC
relationships go through XML end-of-line handling, as NuGet's reader applies
it: CRLF and lone CR read as LF. When no `.nuspec` can be
the `.nuspec` metadata. Authors and description follow NuGet's first eligible
leaf rule with case-insensitive local names. Empty leaves and ordinary
whitespace-only leaves are skipped. Whitespace preserved by CDATA or
`xml:space` can occupy the first slot and yield `null` even when a later leaf
has text. The package ID and version use their case-sensitive names in the
metadata namespace. Missing fields are `null`. In the `.nuspec` and OPC
relationships, XML end-of-line handling maps CRLF and lone CR to LF. When no `.nuspec` can be
selected, `identity` is `null`.
`license` reports the `.nuspec` license element: `type` is `expression` or
+14 -11
View File
@@ -36,7 +36,9 @@ decoded as `normal`, as specified.
file offset, size, and type byte. Root-folder, volume, and file-entry items
are decoded when those layouts match documented shell-item headers, including
the 8.3 short name on a file entry. Every other item is `raw` with a SHA-256
of its payload. Unknown items are not guessed.
of its payload. An invalid item extent, missing TerminalID, or bytes after the
TerminalID make coverage partial. Earlier items remain available, and parsing
resumes at the declared end of the list when that extent fits the file.
`link_info` reports volume drive type, serial, label, local base path, and
common network relative link names, with Unicode variants when the header
@@ -61,9 +63,9 @@ birth-droid GUIDs. Version-1 UUID MAC and timestamp values are labelled
`evidence_kind: "derived"`. `KnownFolderDataBlock` and `SpecialFolderDataBlock`
keep their folder identifiers. `ConsoleFEDataBlock` keeps the code page.
`PropertyStoreDataBlock` and unrecognized signatures stay raw with SHA-256.
Unknown signatures are listed and are not dropped. Decoded fixed-size blocks
with a mismatched length are retained as raw payload hashes and reported as
partial. Later blocks remain readable at their declared offsets.
Decoded fixed-size blocks with a mismatched length retain raw payload hashes
and make coverage partial. Later blocks remain readable when the declared
block extent fits the file.
When `HasExpString`, `HasDarwinID`, `HasExpIcon`, or `RunWithShimLayer`
declares a block, the terminal record lets REA report a missing block and mark
coverage partial. If parsing stops before the terminal, an unseen block remains
@@ -92,9 +94,10 @@ extension. Raw fields and artifact identity are preserved. The code page in a
ConsoleFE block describes the console and does not establish the original
system ANSI encoding for these paths.
An unreadable declared `LinkInfo` target path leaves the target extension
unknown and prevents a mismatch claim, unless another complete target matches
the icon.
An unreadable LinkInfo target or rejected environment target leaves the target
extension unknown. An independently established full-path match still gives
`false` for `icon_location_differs_from_target`. Without such a match, the
comparison remains unknown.
A missing optional section is observed absence of that structure. It is not
proof the shortcut never carried that data in another container.
@@ -109,10 +112,10 @@ Malformed `HeaderSize` or `LinkCLSID`, and exhausted budgets, fail without
partial success. Truncation after a valid header, ExtraData size overruns, and
odd Unicode lengths return partial coverage with `coverage.failing_offset`.
A LinkInfo, VolumeID, or network-name string offset that points inside its
structure header or outside its structure is reported at the offset field itself,
so every issue offset lies inside the file. A `LinkInfoHeaderSize` below 0x1C
does not shrink the mandatory 28-byte header, so an offset in that header is
still reported at the offset field and the path stays unreadable.
structure header or outside its structure is reported at the offset field.
A `LinkInfoHeaderSize` below 0x1C does not shrink the mandatory 28-byte
header, so an offset in that header is still reported at the offset field
and the path stays unreadable.
Coverage is never `complete` when issues are present.
A PropertyStoreDataBlock shorter than 12 bytes or a ShimDataBlock shorter than
136 bytes makes coverage partial. The report retains the block's signature,
+8 -6
View File
@@ -234,17 +234,17 @@ is `--source-map-bytes 8388608`; the other local flags are
`--source-map-section-depth` and `--source-map-codec-heap-mib`.
`analyze-web-bundle` instead offers `--source-map-fetch-bytes` and the shared
output/record/depth flags. Raising only `decoded_records` does not raise the
independent row or segment budgets. Failed local decoding returns no partial
point evidence; completed browser map observations retain their existing
partial/unknown semantics. Wait for retained cleanup to settle before retrying.
independent row or segment budgets. A failure before local decoding produces
a valid report leaves point evidence unavailable. Cancellation or incomplete
cleanup after decoding can retain the finished report in partial Evidence.
Wait for retained cleanup to settle before retrying.
## Verification
## Browser collection results
Browser bundle collection uses absolute section offsets for nested inline maps.
If caller cancellation stops browser map fetching after some items complete,
the failed bundle request retains those items with the captured page in partial
Evidence and marks bundle analysis `not_performed`. This is distinct from the
local source-map decoder's failure semantics above.
Evidence and marks bundle analysis `not_performed`.
An enclosing column offset contributes only when the nested section starts on
that enclosing section's first generated line. Parent boundaries still constrain
preceding browser mappings when a nested section starts with a gap or has no
@@ -290,6 +290,8 @@ source-map decoding, and retains the same
completed-body identity. Successful and partial maps keep their full original
text, including BOM and XSSI framing; only their parsing view removes it.
## Verification
Focused tests cover duplicate mappings, indexed offsets/overlap/local indexes,
32-bit VLQ overflow, nullable content, UTF-16/CRLF positions, immutable artifact
identity, cancellation, late output closure, cleanup failures, SDK schemas and