docs(managed): align normalized CIL claims with shipped v1 semantics

This commit is contained in:
N0zoM1z0
2026-07-17 22:03:36 +08:00
parent 4847fc4fc1
commit 3f788e9065
19 changed files with 183 additions and 48 deletions
+59 -11
View File
@@ -104,8 +104,50 @@ EncBaseId because ECMA-335 metadata does not require those bit patterns.
- row/heap/body locations expressed as typed file offsets, RVAs, or CIL
offsets;
- exact raw bytes or bounded value digest;
- method body, normalized CIL, locals, exception-region, and generic-context
commitments where applicable.
- raw CIL digest plus separately reported method-header, locals-token, and
exception-region observations where available;
- a deterministic v1 decoded-instruction-tuple digest for completely decoded
CIL, with the limitations below.
### Shipped decoded-CIL fingerprint v1
`inspect_managed_members` exposes two method CIL hashes with different byte
boundaries:
| Field | Shipped v1 input | Excluded from the digest |
| ---------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `il_sha256` | The exact `il_size` raw CIL bytes after the tiny or fat method header | Method header, locals signature blob, alignment, and extra sections including exception clauses |
| `normalized_il_sha256` | UTF-8 `JSON.stringify` output for the instruction-order array of `[opcode, operand_kind, operand]` tuples | Instruction offsets except projected scalar branch targets, switch targets, resolved metadata/string identities, method header, locals, and exception regions |
The normalized field is available only when the entire CIL stream decodes with
status `present`. A partial, malformed, absent, or over-limit body reports
`null`. The containing member result's `schema_version: 1` scopes the tuple
format; v1 does not expose a separate algorithm-version field.
Tuple operands use these exact projections:
- operand-free instructions: `none` and `null`;
- metadata and user-string operands: the build-local token as lowercase
`0x`-prefixed eight-digit hexadecimal;
- scalar branches: the target CIL byte offset as a decimal string;
- `switch`: the case count as a decimal string, without target offsets;
- signed integer and variable operands: decimal strings; floating-point
operands: JavaScript's `String` representation of the decoded IEEE value.
Opcode names retain short/long forms and prefix opcodes. This makes v1 a
reproducible decoded-tuple fingerprint, not a canonical semantic CIL identity:
it does not resolve tokens across MVIDs, does not commit full control flow or
exception semantics, and does not replace the raw CIL digest. Cross-build
comparison uses the value only as one unique-only structural tier and reports
ambiguity when that evidence is insufficient. A future normalized-CIL v2 must
have an explicit algorithm version, canonical token/literal identities,
complete branch and switch targets, and explicit locals/exception semantics.
For example, a decoded `nop; ret` body serializes exactly as
`[["nop","none",null],["ret","none",null]]` and has v1 digest
`5e5fad7741cb44bca3a4f045546b7449990da343f612f5f34c0ca30e9eee0636`.
This vector specifies the tuple order, `null` handling, absence of whitespace,
UTF-8 encoding, and lowercase hexadecimal output.
### Epistemic commitment
@@ -163,7 +205,8 @@ bounded set of observations needed to investigate a proposition:
- exact strings, numeric constants, enum-like values, and serialization keys;
- branch, switch, exception, loop, call, and field-flow shape;
- construction and generic-instantiation sites;
- exact body and normalized-CIL commitments;
- raw CIL and decoded-tuple-v1 commitments, plus separate header, locals, and
exception observations;
- callers, callees, shared fields, and competing candidates; and
- limitations from reflection, dynamic dispatch, generated code, protection,
native transitions, or incomplete coverage.
@@ -174,12 +217,14 @@ turn that role into the method's durable identity.
Cross-version matching is two-stage:
1. Exact identity requires compatible artifact/module commitments and an exact
entity/body identity.
2. Structural identity compares schema-versioned signatures, normalized CIL,
APIs, constants, and bounded graph context. It reports all candidates at the
winning score and remains ambiguous when the evidence does not distinguish
them.
1. Exact identity requires compatible artifact/module commitments and exact
raw CIL identity; v1 does not expose a standalone complete-method-body
digest.
2. Structural identity compares schema-versioned signatures, the limited v1
decoded-CIL tuple fingerprint, constants, and bounded shape context. It
reports all candidates at the winning score and remains ambiguous when the
evidence does not distinguish them. The v1 digest does not itself remap
metadata tokens.
Tokens are always remapped through observed structure. A caller cannot carry
`0x06001234` into a new MVID and assume it names the same method.
@@ -330,7 +375,8 @@ manifest supplies those fields. It then pages each declared MethodDef token
directly by row, so selected methods do not need to appear in the first member
page of a large application. `il_length` remains accepted as a legacy alias for
`il_size`; optional `il_sha256` locks the exact raw CIL bytes in addition to
REA's schema-versioned normalized instruction digest.
REA's member-result-v1 decoded-instruction-tuple digest. That normalized field
has the v1 limits documented above and is not a complete semantic CIL identity.
The optional `application_graph` block reuses those exact-build method
commitments. For each referenced MethodDef token, the verifier builds a bounded
@@ -378,7 +424,9 @@ The managed-code track advances as reviewable pull requests:
1. accepted evidence/provider boundary (this document and ADR);
2. read-only artifact triage and exact identity (shipped);
3. bounded metadata, signatures, method bodies, and normalized CIL (shipped);
3. bounded metadata, signatures, method bodies, raw CIL hashes, and the limited
decoded-instruction-tuple fingerprint v1 (shipped; normalized-CIL v2
semantics remain planned);
4. obfuscation-resistant slices and cross-version comparison (shipped for
static member observations);
5. decompiler reconstruction import (shipped as analyst inference; REA does