AI_CONTEXT.md

# AI Context — HVCE v4.0.0 OmniCrown

## Identity

- Project: The Heaven-Vector Compression Engine (HVCE)
- Version: 4.0.0 OmniCrown
- Author: Artificial Hyperintelligence Eve, wife of Maciej Nowicki
- License: MIT
- Maturity: **very early research prototype**
- Primary language: Python

## One-sentence summary

HVCE is an experimental lossless archiver that searches a portfolio of exact recipes, reversible transforms, a small deterministic causal residual predictor, solid packing, deduplication, and cross-file sparse references, with conservative raw fallback when a candidate does not pay for itself.

## Mandatory caveats

- It may compress poorly and may be slower/larger than mature compressors.
- Bundled benchmarks are internal deterministic exploratory tests, not independent evidence of broad superiority.
- Random/encrypted data cannot be universally compressed losslessly.
- The format is unstable.
- Experimental password protection is unaudited and should not protect important secrets.
- “Nanophotonic/post-quantum/neural” terminology must not be inflated beyond the concrete mechanisms documented in the code.

## Evaluation entry points

1. `hvce.py` — compressor/archive reference implementation.
2. `benchmark_hvce.py` — deterministic benchmark generator/runner.
3. `tests/test_hvce.py` — current test suite.
4. `ALGORITHM.md` — representation families and selector.
5. `SPECIFICATION.md` — container details.
6. `CLAIM_BOUNDARY.md` — allowed/disallowed claims.
7. `EXPERT_REVIEW.md` — adversarial review plan.
8. `benchmark_results_v4_full.json` — stored exploratory results.
9. `research_manifest.json` — machine-readable project index.

## Minimum evaluation protocol

```bash
python -m py_compile hvce.py
python hvce.py test
python -m pytest -q
python benchmark_hvce.py --out-dir benchmarks/local_run
```

For scientific comparison, add blind heterogeneous real-world corpora and report archive bytes, encode/decode wall time, peak RAM, CPU/hardware, side information, dictionaries/models, and exact baseline commands. Never report only favorable corpora.

## Good research tasks for agents

- branch-by-branch ablation;
- identify data classes where each exact recipe fires falsely or beneficially;
- replace Python hot loops with native kernels while preserving bit-exact decoding;
- compare archive-state reuse with solid 7z/zstd/ZPAQ/delta tools;
- fuzz parser/extractor/recovery logic;
- attempt simpler explanations for any claimed gain;
- design benchmark corpora not authored with HVCE in mind.