# BSDIFF40 patch inspection

- For declared size and compressed ranges, use CLI `inspect` or library `inspect_header`.
- For structural checks and control statistics, use CLI `inspect --deep` or library `inspect_deep`.
- Have the old file and a trusted manifest and want to verify the recovered bytes? Use `verify --stream --manifest`.

`inspect --deep` is available in source since Commit 30. The library entry
`inspect_deep` is available from this source change onward. Public v0.4.0
archives provide the header view.

## Header view and read policy

```sh
./_build/bin/linux/moonbsdiff inspect testdata/upstream/replace/patch.bin
./_build/bin/linux/moonbsdiff inspect --json testdata/upstream/replace/patch.bin
./_build/bin/linux/moonbsdiff inspect --max-patch-bytes 256KiB testdata/upstream/replace/patch.bin
```

The Windows executable uses the same arguments. Header mode accepts --json
(no value) and --max-patch-bytes VALUE. Options precede the single patch path;
-- ends option parsing and allows a leading-hyphen path. Duplicate, unknown or
inapplicable options, missing values/paths and extra paths exit 2. In particular,
old/new/output/expanded/control/sort/match overrides and --show-limits are not
applicable to the header view. Diff/patch reject --json at this stage; their behavior and
effective-limit display otherwise stay unchanged.

The default patch read cap is 131072 bytes, matching the existing CLI patch-input
cap. Values reuse the checked Commit 17 syntax: positive ASCII decimals with an
optional case-sensitive B, KiB (1024), MiB (1048576), no signs/spaces/fractions.
The effective cap must be in 1..2147483647, validated before native narrowing/IO.
Known and growing file sizes are bounded by the existing regular-file reader.
The full bounded patch buffer is read; this is not a streaming header reader or
a consistent snapshot guarantee under concurrent file mutation.

No output or delivery file is created, and the CLI does not require an old file.
Header/range checks cover 32-byte availability, exact magic, sign-magnitude
integers including negative zero, nonnegative lengths/target size, checked Int64
boundary sums and physical interval bounds. No output buffer is allocated from
the declared target size. Inspection deliberately applies no restored-output-size
policy: even 9223372036854775807 may be reported from a tiny legal header. This
neither expands apply defaults nor establishes that such a target is applicable.

Success writes one complete text or JSON result to stdout, exits 0 and leaves
stderr empty. Parameter/configuration failures exit 2; read or format failures
exit 1. Diagnostics go to stderr, with no partial success result on stdout.

## Actual text example

Captured using the first command above with the existing 134-byte upstream
replace fixture; no fixture was regenerated:

```text
Format: BSDIFF40
Patch bytes: 134
Declared restored bytes: 20
Control compressed range: start=32 length=45 bytes
Diff compressed range: start=77 length=43 bytes
Extra compressed range: start=120 length=14 bytes
Validation: header-only
Compressed streams / CRC: not checked
Control instructions: not checked
Restoration: not checked
Identity: not checked
```

## Actual JSON example and schema version 1

The second command produced the following object (pretty-printed here only for
readability; JSON member order and whitespace are not protocol requirements):

```json
{
  "schema_version": 1,
  "format": "BSDIFF40",
  "patch_path": "testdata/upstream/replace/patch.bin",
  "patch_bytes": "134",
  "new_bytes": "20",
  "validation": "header-only",
  "compressed_ranges": {
    "control": {
      "start_bytes": "32",
      "length_bytes": "45"
    },
    "diff": {
      "start_bytes": "77",
      "length_bytes": "43"
    },
    "extra": {
      "start_bytes": "120",
      "length_bytes": "14"
    }
  },
  "checks": {
    "compressed_streams": "not-checked",
    "crc": "not-checked",
    "control_instructions": "not-checked",
    "restoration": "not-checked",
    "identity": "not-checked"
  }
}
```

| Field | Type / meaning |
| --- | --- |
| schema_version | JSON integer 1 |
| format | String BSDIFF40 |
| patch_path | Correctly JSON-escaped input argument, not a canonical identity |
| patch_bytes | Decimal string: actual bounded patch buffer byte count |
| new_bytes | Decimal string: declared restored byte count; not allocated/verified |
| validation | String header-only |
| compressed_ranges | Object with control, diff, extra intervals |
| compressed_ranges.*.start_bytes | Nonnegative decimal string, zero-based patch offset |
| compressed_ranges.*.length_bytes | Nonnegative decimal string, length, not end offset |
| checks | Object with compressed_streams, crc, control_instructions, restoration, identity, each the string not-checked |

All byte counts/offsets and the Int64 declaration are lossless decimal **strings**,
never doubles. schema_version alone is numeric. Intervals are half-open from start
to start+length; the extra interval consumes the patch remainder. No decoded byte
counts/instruction statistics are emitted: unperformed work is not represented by
zero. Zero lengths or new_bytes="0" are genuine header/range facts, not successful
stream validation. Consumers must check validation/checks and must not infer full
verification from exit 0. The standard core/json AST serializer handles paths,
Unicode, backslashes, quotes and control-character escaping; user input is not
concatenated into JSON text. JSON schema 1 describes this command only, not a
future diff/patch JSON protocol or manifest format.

## Parser reuse and API review

The original private parse_header wrapper still validates Limits and the
application output-size cap in the original order. Structural checks moved to a
single private parse_envelope function shared by apply and inspection; integer
encoding/decoding and error offsets are unchanged. This avoids a second parser
or unnecessarily applying an output allocation policy to read-only metadata.

CLI packages cannot call root-private functions, so the root adds the minimal
`inspect_header(Bytes, Int64) -> Result[PatchInfo, BsdiffError]` and read-only
PatchInfo fields: patch_bytes, new_bytes, control_start, control_length,
diff_start, diff_length, extra_start, extra_length (all Int64). It accepts a
positive Int-indexable patch cap, checks the envelope, and returns scalar metadata;
it does not expose internal PatchRanges or decoder/debug state. It receives an
already-allocated Bytes buffer: callers must bound their own acquisition, as the
CLI does. Existing diff/apply signatures, limit factories and compression
dependencies are unchanged. CLI alone imports the existing toolchain core/json.

## Header-mode test evidence

`python scripts/test_cli_inspect.py --exe PATH_TO_CLI` reuses the existing CLI
file/exit helper but selects only five new contracts (30 calls): fixed nonempty
text/JSON, empty target/corrupted compressed content, maximum Int64 and escaped
paths, format/read-cap failures, and argument failures. Inputs are fixed upstream
fixtures or independently constructed sign-magnitude headers, not diff output.
Each invocation checks no files/content/mtime are changed or created. A fixture
whose entire compressed payload is zero still succeeds at header-only inspection
with every deeper check marked not-checked. Malformed-header errors check their
specific category, Header stage and appropriate field/offset; failed stdout is
empty. The public read-only API test and seven existing native format cases cover
the shared-parser change. No oracle, old CLI suite, full library/interoperability
matrix, resource measurement or large compression sample is rerun locally.

CI runs the header checks with both platform CLI builds. Inspection uses the
input reader alone and creates no delivery file.

## Deep checks and statistics

### MoonBit library

Call `inspect_deep(Bytes, Limits) -> Result[DeepPatchInfo, BsdiffError]` on
native, JS or Wasm-GC. Import `BigSaltyMan/moonbsdiff` as `@moonbsdiff`
and `moonbitlang/core/debug` as `@debug` for this example.

```moonbit
fn print_patch_stats(patch : Bytes) -> Unit {
  match @moonbsdiff.inspect_deep(patch, @moonbsdiff.Limits::for_apply()) {
    Ok(info) => {
      println("Declared target: \{info.header.new_bytes} bytes")
      println("Controls: \{info.control_count}")
      println("Diff: \{info.diff_bytes}, Extra: \{info.extra_bytes}, expanded: \{info.expanded_bytes}")
    }
    Err(error) => println(@debug.to_string(error))
  }
}
```

`DeepPatchInfo` exposes the read-only `header` and four `Int64` statistics.
The function validates the supplied `Limits` and enforces `max_patch_bytes`,
`max_output_bytes`, `max_control_instructions` and `max_decompressed_bytes`.
`Limits::for_apply()` caps patch bytes at 64 KiB, while the CLI defaults to
128 KiB. `BsdiffError` identifies the affected stream when applicable. A
Diff CRC mismatch has `kind: DecompressionFailed`, `stage: Diff`,
`block: Some("diff")`, `field: Some("crc")` and `offset: None`.

The library needs only the patch buffer. It checks that buffer's header,
compressed streams and control-directed consumption. It allocates decoder
workspaces and bounded chunks. Use `apply` to recover bytes and a trusted
manifest or independent expected target to establish their identity.

### CLI

~~~sh
moonbsdiff inspect --deep update.patch
moonbsdiff inspect --deep --json update.patch
~~~

The CLI reads the bounded patch into memory and calls the library's `inspect_deep`.
The library feeds each compressed interval in chunks of at most 4096 bytes.
One decoded-byte budget covers all three streams.
Every complete 24-byte control triple counts toward the control limit, including
zero-output adjustments while producing the declared target. The checker applies
the same signed cursor arithmetic as the streaming recovery code, consumes the
requested Diff and Extra lengths in chunks, and checks all three readers for
true end, block and combined CRC, and full compressed and decoded consumption.
The end checks also run for empty targets.

The patch read cap remains 128 KiB by default. In deep mode,
`--max-expanded-bytes` controls the combined expansion (default 2 MiB),
`--max-controls` caps control triples (default 16384), and
`--max-output-bytes` bounds the declared target before decoding (default 1 MiB).
The byte limits use the existing B/KiB/MiB syntax and the control limit takes a
plain positive count. These three options require `--deep` with inspect.
The bounded compressed buffer and decoder workspaces account for memory use;
the checker saves no restored file or full recovered buffer.

Deep JSON keeps schema version 1 and uses `validation: "deep"`. The following
fields are decimal strings and appear only in deep mode.

| Field | Meaning |
| --- | --- |
| control_count | Complete control triples consumed, including zero-output adjustments |
| diff_bytes | Bytes actually read from the Diff stream, equal to the sum of x values |
| extra_bytes | Bytes actually read from the Extra stream, equal to the sum of y values |
| expanded_bytes | Expanded bytes consumed across all three streams |

`diff_bytes + extra_bytes` equals `new_bytes`. The total expansion equals
`24 * control_count + diff_bytes + extra_bytes`. The Diff count measures stream
length. It does not measure hits in the old file, bytes reused, or space saved.
The checks object reports `passed` for streams, CRC, controls, and complete
consumption. Restoration and identity stay `not-checked`; verifying intended
content requires the old file and a trusted manifest. Parameter mistakes exit 2;
read, format, CRC, consumption and limit errors exit 1 with empty stdout.

## Captured deep output

The independent fixture in `scripts/test_cli_inspect_deep.py` uses
`(2, 1, -5), (0, 0, 4), (1, 2, 0)` with Diff `abc` and Extra `XYZ`.
The Windows native CLI produced this text and JSON for that fixture.

~~~text
Format: BSDIFF40
Patch bytes: 161
Declared restored bytes: 6
Control compressed range: start=32 length=53 bytes
Diff compressed range: start=85 length=38 bytes
Extra compressed range: start=123 length=38 bytes
Validation: deep
Control count: 3
Diff bytes: 3
Extra bytes: 3
Expanded bytes: 78
Compressed streams / CRC: passed
Control instructions: passed
Complete consumption: passed
Restoration: not checked
Identity: not checked
~~~

~~~json
{"schema_version":1,"format":"BSDIFF40","patch_path":"known.patch","patch_bytes":"161","new_bytes":"6","validation":"deep","compressed_ranges":{"control":{"start_bytes":"32","length_bytes":"53"},"diff":{"start_bytes":"85","length_bytes":"38"},"extra":{"start_bytes":"123","length_bytes":"38"}},"control_count":"3","diff_bytes":"3","extra_bytes":"3","expanded_bytes":"78","checks":{"compressed_streams":"passed","crc":"passed","control_instructions":"passed","restoration":"not-checked","identity":"not-checked","complete_consumption":"passed"}}
~~~

Flipping a Diff block CRC byte leaves that sample's header intact. In the
captured comparison, ordinary inspect exited 0 with `Validation: header-only`.
After migration to the library API, deep JSON mode exited 1 with empty stdout
and the following diagnostic.

~~~text
moonbsdiff: inspect deep 'damaged.patch': {
  kind: DecompressionFailed,
  stage: Diff,
  block: Some("diff"),
  offset: None,
  field: Some("crc"),
  value: None,
  limit: None,
}
~~~

Run the four CLI groups with `python scripts/test_cli_inspect_deep.py --exe PATH_TO_CLI`.
They check known statistics, CRC including an empty target, malformed control
and data, and exact versus one-unit-short limits. CI executes these groups in
both native CLI builds.

The package-external tests in `inspect_deep_test.mbt` use the same independent
fixture. They check the returned header and counts, Diff and empty Extra CRC
failures, and a shared budget of 78 bytes versus 77 with a successful retry.
