# TODO

Post-API-simplification active issues.

Public core model is `HexFile`, `Segment`, `AddressRange`. No public CLI layer, no pipeline/flag surface, no in-memory CLI execution path.

Current parity gaps / validated divergences are tracked in [known-divergences.md](known-divergences.md).

## Verify On Reference Machine

These are contract questions, not just implementation bugs.

### `/XN` ordering

Question: should binary export preserve raw insertion order or sorted address order?

Current state:
- `HexFile` documents raw segment operations as preserving insertion order
- [`write_binary`](/Users/tomford/code/projects/h3xy/src/io/binary.rs) sorts by address before concatenation

Need:
- verify HexView behavior against the reference manual / binary
- then either document current behavior as correct or change it

### `/L` `FileOpen` path base

Question: should paths in log files resolve relative to cwd or relative to the log file location?

Current state:
- [`parse_log_commands`](/Users/tomford/code/projects/h3xy/src/ops/log.rs) preserves the literal path
- [`execute_log_commands`](/Users/tomford/code/projects/h3xy/src/ops/log.rs) later resolves through the caller/load closure, which currently makes CLI behavior cwd-relative

Need:
- verify HexView behavior
- then either keep cwd-relative resolution or make log-file-relative resolution explicit

## Needs Design / More Consideration

These are real issues, but the right fix is less mechanical.

### Ambiguous key / signature source parsing

[`src/bin/h3xy/args/signature.rs`](/Users/tomford/code/projects/h3xy/src/bin/h3xy/args/signature.rs)

`load_signature_bytes` and `load_key_material` still use `path.exists()` to choose between filesystem input and inline material.

Problem:
- cwd files can shadow intended inline input
- missing file-looking strings can be accepted as inline bytes or literal key material

Needs a decision on explicit source syntax or stricter rejection rules.

### `/DP` placement plus `/SV` hashes different images

[`src/bin/h3xy/args/signature.rs`](/Users/tomford/code/projects/h3xy/src/bin/h3xy/args/signature.rs)

`/DP` signs pre-placement bytes, then mutates the image by placing the signature. `/SV` verifies against the post-placement image.

Needs a decision:
- reject same-invocation placed `/DP` + `/SV`
- or define and implement exclusion rules for the placed signature range

### `normalized()` performance

[`src/hexfile.rs`](/Users/tomford/code/projects/h3xy/src/hexfile.rs)

Two separate costs:

1. **Redundant normalization** — a single CLI run may normalize multiple times (align, checksum, output) even when nothing changed between calls. A dirty-flag on `HexFile` (cleared on mutation, checked in `normalized()`) would skip re-work when the file is already flat.

2. **Quadratic overlap resolution** — when overlaps exist, `overlay_segment()` walks all existing segments per new segment (O(n²) in segment count, each step clones). Only fires when `has_overlap` is true; the common fast path (sort + merge adjacent) is O(n log n). Fixing this properly requires an interval-tree or byte-level merge buffer.

Likely not a problem for real firmware hex files (<100 non-overlapping segments). Revisit if profiling shows otherwise.

### Full-span `AddressRange` support

[`src/range.rs`](/Users/tomford/code/projects/h3xy/src/range.rs)
[`src/ops/filter.rs`](/Users/tomford/code/projects/h3xy/src/ops/filter.rs)
[`src/ops/checksum.rs`](/Users/tomford/code/projects/h3xy/src/ops/checksum.rs)
[`src/ops/transform.rs`](/Users/tomford/code/projects/h3xy/src/ops/transform.rs)
[`src/bin/h3xy/args/execute.rs`](/Users/tomford/code/projects/h3xy/src/bin/h3xy/args/execute.rs)

`AddressRange` currently rejects `0x00000000..=0xFFFFFFFF` because the type contract assumes `length() -> u32`. That keeps range math simple, but leaks into edge cases like `merge_ranges()`, where two adjacent valid ranges cannot be coalesced into the full span.

Follow-up redesign if/when this matters:
- decide whether the public contract should support the full span explicitly
- if yes, widen range length semantics (`u64`, `Option<u32>`, or a half-open representation)
- audit all materialization/allocation call sites that currently cast `range.length()` to `usize`

Do not treat this as just a constructor tweak; it is a small API redesign plus an allocation-behavior audit.

### Full-span materialization in sparse images

[`src/ops/filter.rs`](/Users/tomford/code/projects/h3xy/src/ops/filter.rs)
[`src/hexfile.rs`](/Users/tomford/code/projects/h3xy/src/hexfile.rs)
[`src/io/binary.rs`](/Users/tomford/code/projects/h3xy/src/io/binary.rs)
[`src/bin/h3xy/args/io.rs`](/Users/tomford/code/projects/h3xy/src/bin/h3xy/args/io.rs)

`fill_gaps`, `as_contiguous`, gap-filled binary output, and Porsche output still allocate the whole `min..=max` span.

Needs:
- explicit bounds / error behavior
- or streaming output paths for sparse images

### Forced-range checksum builds full synthetic data first

[`src/ops/checksum.rs`](/Users/tomford/code/projects/h3xy/src/ops/checksum.rs)

Forced-range checksum still constructs a whole pattern-backed segment before exclusions are applied.

Needs a more careful checksum-collection refactor.

### Move signature ops into library

[`src/bin/h3xy/args/signature.rs`](/Users/tomford/code/projects/h3xy/src/bin/h3xy/args/signature.rs)

Signing/verification logic (RSA PKCS#1/PSS, Ed25519, X.509 cert loading) currently lives in the CLI layer. The library should offer the same in-memory semantics as every other HexView operation so consumers can reproduce `/DP` and `/SV` behavior without the CLI.

Migration requires:
- library-level signature types (method enum, target enum, key source) decoupled from CLI `CliError`/`DataProcessingParams`/`SignatureVerifyParams`
- CLI layer translates its parsed args into the library types
- crypto deps (`ed25519-dalek`, `rsa`, `x509-cert`, `sha2`) move behind a cargo feature gate so non-signing consumers don't pay for them

### CLI architecture: clap + HexView compat mode

The CLI is entirely hand-rolled to match HexView's `/`-prefix syntax. This is correct for drop-in compat, but means no `--help`, no shell completions, no discoverable native args.

Future direction under consideration: `h3xy --hexview "/AR:'...' /CS1:@append" input.hex -o output.hex` — clap manages the outer shell (input, output, `--hexview`, `--help`, `--version`, future native flags), the existing hand-rolled parser handles the HexView string verbatim.

Open questions:
- should bare `/`-flags continue to work without `--hexview` for backward compat, or require the explicit mode switch?
- what native features (if any) warrant clap args beyond `--hexview`?

Deferred until more real-world usage clarifies the need.

## API Ergonomics

Keep the canonical public model as `HexFile` + `Segment` + `AddressRange`.

Possible thin ergonomic additions without introducing a second public data model:
- `HexFile::from_bytes(base, data)`
- `HexFile::extend_segments(iter)`
- `impl From<(u32, Vec<u8>)> for Segment`
- examples for parse -> mutate -> write
- examples for single-blob callers and sparse-patch callers
