Merge branch 'master' of github.com:LessUp/compress-kit

Integrate PR #9 architecture-deepening artifacts (ADRs 0001/0003/0004/0005,
validation metadata module) into the C++17-only tree.

Drop ADR 0002 (cross-language semantic error alignment) and
docs/architecture/contract-inventory.md: both depend on the removed Go/Rust
implementations and no longer apply after the C++17-only streamline.

Resolve CONTEXT.md "参考资料" section: keep ADR references that still exist,
drop the 0002 link and the deleted openspec/ spec links.

Resolve docs/en/architecture/index.md CLI section: keep the C++17-only
single-binary contract (`./build/<algo>_cpp`), drop the multi-language
`--lang` and `<algo>_<lang>` invocations.

Update tests/metadata.py to LANGUAGE_ORDER = ("cpp",) to match the
C++17-only tree.

make test && make lint pass.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: LessUp

CONTEXT.md

@@ -181,6 +181,13 @@ C++ 实现的共享工具模块，位于 `algorithms/shared/cpp/`：
 | CHANGELOG.md | 用户可见变更 | 用户 |
 | CONTEXT.md | 领域词汇 | 贡献者/AI |
 
+## 参考资料
+
+- `docs/adr/0001-validation-metadata-module-shape.md` - 验证元数据模块形状决策
+- `docs/adr/0003-range-coder-corpus-cap-policy.md` - Range Coder 语料库上限策略决策
+- `docs/adr/0004-rle-buffered-streaming-stance.md` - RLE 缓冲流式语义决策
+- `docs/adr/0005-range-cpp-bench-mode-migration-path.md` - Range C++ bench 模式迁移路径决策
+
 ## 文档术语表
 
 本文节定义 Git Pages 文档（VitePress）中的术语翻译规范。

docs/adr/0001-validation-metadata-module-shape.md

@@ -0,0 +1,36 @@
+# ADR 0001: Validation metadata module shape
+
+Date: 2026-05-31  
+Status: Accepted
+
+## Context
+
+Conformance, CLI smoke, test-data generation, and benchmark orchestration scripts each hardcode overlapping facts: algorithm names, binary paths, file extensions, corpus names, Range corpus caps, benchmark dataset choices, language ordering, and report schema fields. This duplication causes drift when adding algorithms, adjusting corpus policy, or changing binary paths.
+
+Current consumers and their metadata shapes are recorded in `docs/architecture/contract-inventory.md` (§ Validation and test metadata consumers, § Benchmark metadata consumers).
+
+## Decision
+
+Introduce a single versioned Python metadata module (`tests/metadata.py` or similar) that exposes:
+
+- Algorithm registry: name, extension, binary paths per language
+- Corpus registry: corpus names, sizes, generation parameters, eligibility flags
+- Range corpus cap: explicit named constant with documented rationale
+- Benchmark job registry: per-algorithm selected input file
+- Report schema: field names and ordering for benchmark JSON output
+
+Conformance, smoke, test-data, and benchmark runners become thin adapters over this module. The module is versioned with a `METADATA_VERSION` string; consumers assert the version they were tested against.
+
+## Constraints
+
+- This change does **not** alter algorithm/language matrix, corpus eligibility rules, Range cap value, or benchmark schema: it only consolidates existing facts.
+- Any intentional change to Range cap policy, corpus eligibility, or conformance matrix requires an OpenSpec change first (see `docs/architecture/contract-inventory.md` § OpenSpec-triggering decisions).
+- Python module must remain compatible with the existing `uv`/`python3` invocation patterns in the Makefile.
+
+## Consequences
+
+**Positive**: Single source of truth for test/bench metadata; adding an algorithm or corpus file requires one edit instead of many; Range cap policy is explicit and findable.
+
+**Negative**: Additional indirection layer; scripts must import the module, requiring Python path management.
+
+**Deferred**: Deciding whether the metadata module is the right place to record Range cap policy permanently, or whether that policy should move into OpenSpec. Record that decision in ADR 0003 before migrating.

docs/adr/0003-range-coder-corpus-cap-policy.md

@@ -0,0 +1,39 @@
+# ADR 0003: Range Coder corpus cap policy
+
+Date: 2026-05-31  
+Status: Accepted
+
+## Context
+
+The Range Coder has a known large-file decode performance problem. The conformance matrix currently skips corpus files over **100 KiB** with reason code `range_coder_corpus_cap_100_kib`. This cap is hardcoded in `tests/conformance/run_decode_matrix.py` and documented in:
+
+- `tests/conformance/README.md` (workaround note)
+- `docs/en/algorithms/range.md` (known issue section)
+- `algorithms/range/benchmark/bench.py` (benchmark default input note)
+
+The cap value and its rationale have never been formally recorded as a policy decision.
+
+## Decision
+
+The 100 KiB conformance skip cap is **retained as-is** and recorded here as a deliberate policy rather than an incidental constant.
+
+Rationale:
+- The underlying performance issue is a known limitation documented in OpenSpec (`openspec/specs/cross-language-testing/spec.md`).
+- Fixing the performance issue requires a non-trivial algorithm change that may affect binary format or cross-language behavior, triggering a new OpenSpec change.
+- Raising the cap without fixing the root cause would cause CI to hang or time out, which is worse than an explicit skip.
+
+The cap is **not permanent**. If the performance issue is resolved, the cap can be raised or removed, but doing so changes test-gate semantics and therefore requires an OpenSpec change before implementation.
+
+## Constraints
+
+- Do not silently raise, lower, or remove the cap without an OpenSpec change.
+- Do not treat the cap value (100 KiB) as canonical in user-facing docs; document it as "current workaround" to preserve flexibility.
+- When the metadata module (ADR 0001) is implemented, the cap must appear as a named constant with this ADR reference.
+
+## Consequences
+
+**Positive**: Policy is now explicit and findable; reviewers know the cap is intentional; future removal has a clear trigger condition.
+
+**Negative**: The known limitation persists; Range Coder is under-tested on real-world corpus sizes.
+
+**Deferred**: Root-cause fix for Range Coder large-file performance. That work requires a separate OpenSpec proposal and is out of scope for this architecture deepening cycle.

docs/adr/0004-rle-buffered-streaming-stance.md

@@ -0,0 +1,38 @@
+# ADR 0004: RLE buffered streaming stance
+
+Date: 2026-05-31  
+Status: Accepted
+
+## Context
+
+RLE is naturally streamable: each `(count, value)` pair is independent and requires no look-ahead beyond the current run. However, the current Go and Rust RLE adapters use buffered streaming wrappers (`BufferedEncoder`/`BufferedDecoder`) that collect the full input before processing, identical to the static-model algorithms (Huffman, Arithmetic, Range).
+
+From `contract-inventory.md` (§ Buffer and streaming contract):
+
+> Flush is a no-op for buffered static-model algorithms until `Finish`; RLE is currently also buffered in Go/Rust adapters despite being naturally streamable.
+
+The C++ RLE implementation reads/writes file streams incrementally but is wrapped through the C++ buffer adapter for the CLI layer.
+
+## Decision
+
+**Retain buffered semantics for RLE** in all three languages as the documented contract for this product version.
+
+Rationale:
+- RLE shares the same `BufferedEncoder`/`BufferedDecoder` lifecycle as the other three algorithms; making it the only algorithm with true incremental streaming would create a two-tier streaming contract that complicates cross-language conformance tests.
+- The performance benefit of incremental RLE streaming is not material for the current corpus sizes (up to 10 MiB).
+- Implementing true incremental streaming for RLE would require a new streaming adapter path across all three languages — a significant scope increase.
+
+The buffered semantic is **explicitly documented** rather than left implicit. API callers must not assume that `Process` writes any output before `Finish` is called.
+
+## Constraints
+
+- Do not change RLE's public streaming lifecycle behavior without an OpenSpec change (it is part of the public streaming/buffer API contract).
+- If a future OpenSpec change introduces true incremental streaming for RLE, the conformance test suite must be updated to assert per-chunk output behavior.
+
+## Consequences
+
+**Positive**: Consistent lifecycle across all four algorithms; simpler conformance tests; explicit stance eliminates future confusion.
+
+**Negative**: RLE cannot be used for low-latency or memory-constrained streaming use cases; that limitation is now documented.
+
+**Deferred**: True incremental RLE streaming as a future feature, subject to a new OpenSpec change.

docs/adr/0005-range-cpp-bench-mode-migration-path.md

@@ -0,0 +1,47 @@
+# ADR 0005: Range C++ bench mode migration path
+
+Date: 2026-05-31  
+Status: Accepted
+
+## Context
+
+The public CLI contract for all production binaries is:
+
+```
+<binary> <encode|decode> <input> <output>
+```
+
+Range C++ is the only exception: its production binary also accepts:
+
+```
+<binary> bench [size_bytes] [iterations]
+```
+
+This is documented in `contract-inventory.md` (§ CLI contract and exceptions) and recorded in `algorithms/range/cpp/main.cpp:378-415`.
+
+The `bench` mode is used by `algorithms/range/benchmark/bench.py` for micro-benchmarking. It is a **shipped CLI behavior** even though it conflicts with the unified CLI adapter shape.
+
+## Decision
+
+The `bench` mode is **retained without change** in the current release cycle. This ADR records the migration path for when it is eventually removed.
+
+### Migration path (to be executed in a future cycle with an OpenSpec change)
+
+1. Open an OpenSpec change to officially deprecate the `bench` subcommand from the production Range C++ binary.
+2. Move benchmark behavior to a separate binary or script (e.g., `algorithms/range/benchmark/bench_driver` or extend `algorithms/range/benchmark/bench.py` to drive encoding/decoding directly).
+3. Update `algorithms/range/benchmark/bench.py` to use the new driver.
+4. Update CLI smoke tests to assert that `bench` is no longer a valid mode in the production binary.
+5. Remove the `bench` branch from `algorithms/range/cpp/main.cpp`.
+
+### Current constraints
+
+- Do not silently remove `bench` mode before the above steps; it is a shipped behavior even if undocumented in the primary contract.
+- CLI smoke tests currently test the `<encode|decode|invalid_mode>` contract; they do not assert that `bench` is **absent**. This is intentional until the migration is approved.
+
+## Consequences
+
+**Positive**: Migration path is explicit; no accidental removal; future reviewer knows the intent.
+
+**Negative**: Range C++ production binary continues to violate the unified CLI contract until the migration is executed.
+
+**Deferred**: Actual migration work. Requires a new OpenSpec change proposal before any code change.

tests/metadata.py

@@ -0,0 +1,204 @@
+"""CompressKit test and benchmark metadata module.
+
+Single source of truth for algorithm registry, corpus registry, Range corpus cap,
+benchmark job registry, and report schema.  Conformance, smoke, test-data, and
+benchmark scripts are thin adapters over this module.
+
+Design decision: docs/adr/0001-validation-metadata-module-shape.md
+Range corpus cap decision: docs/adr/0003-range-coder-corpus-cap-policy.md
+
+Consumers must assert the version they depend on:
+
+    import metadata
+    assert metadata.METADATA_VERSION == "1.0"
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Version
+# ---------------------------------------------------------------------------
+
+METADATA_VERSION = "1.0"
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+
+ROOT = Path(__file__).resolve().parent.parent
+TESTS_DIR = ROOT / "tests"
+DATA_DIR = TESTS_DIR / "data"
+SCRIPTS_DIR = ROOT / "scripts"
+REPORTS_DIR = ROOT / "reports"
+DOCS_DATA_DIR = ROOT / "docs" / ".vitepress" / "data"
+
+# ---------------------------------------------------------------------------
+# Algorithm and binary registry
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BinaryEntry:
+    language: str
+    path: Path
+
+
+@dataclass(frozen=True)
+class AlgorithmEntry:
+    """One algorithm supported by CompressKit."""
+
+    name: str
+    """Canonical lower-case algorithm name (e.g. 'huffman')."""
+
+    extension: str
+    """File extension used for encoded output (e.g. 'huf')."""
+
+    binaries: tuple[BinaryEntry, ...]
+    """Shipped binaries, in display order (cpp)."""
+
+    benchmark_input: str
+    """Corpus file name used as the benchmark input for this algorithm."""
+
+    benchmark_driver: Path
+    """Path to the per-algorithm benchmark driver script."""
+
+
+ALGORITHMS: tuple[AlgorithmEntry, ...] = (
+    AlgorithmEntry(
+        name="huffman",
+        extension="huf",
+        binaries=(
+            BinaryEntry("cpp", ROOT / "algorithms/huffman/cpp/huffman_cpp"),
+            BinaryEntry("go", ROOT / "algorithms/huffman/go/huffman_go"),
+            BinaryEntry("rust", ROOT / "algorithms/huffman/rust/huffman_rust"),
+        ),
+        benchmark_input="textlike_10MiB.bin",
+        benchmark_driver=ROOT / "algorithms/huffman/benchmark/bench.py",
+    ),
+    AlgorithmEntry(
+        name="arithmetic",
+        extension="aenc",
+        binaries=(
+            BinaryEntry("cpp", ROOT / "algorithms/arithmetic/cpp/arithmetic_cpp"),
+            BinaryEntry("go", ROOT / "algorithms/arithmetic/go/arithmetic_go"),
+            BinaryEntry("rust", ROOT / "algorithms/arithmetic/rust/arithmetic_rust"),
+        ),
+        benchmark_input="textlike_10MiB.bin",
+        benchmark_driver=ROOT / "algorithms/arithmetic/benchmark/bench.py",
+    ),
+    AlgorithmEntry(
+        name="range",
+        extension="rcnc",
+        binaries=(
+            BinaryEntry("cpp", ROOT / "algorithms/range/cpp/rangecoder_cpp"),
+            BinaryEntry("go", ROOT / "algorithms/range/go/rangecoder_go"),
+            BinaryEntry("rust", ROOT / "algorithms/range/rust/target/release/rangecoder"),
+        ),
+        benchmark_input="small_dictionary_like.bin",
+        benchmark_driver=ROOT / "algorithms/range/benchmark/bench.py",
+    ),
+    AlgorithmEntry(
+        name="rle",
+        extension="rle",
+        binaries=(
+            BinaryEntry("cpp", ROOT / "algorithms/rle/cpp/rle_cpp"),
+            BinaryEntry("go", ROOT / "algorithms/rle/go/rle_go"),
+            BinaryEntry("rust", ROOT / "algorithms/rle/rust/rle_rust"),
+        ),
+        benchmark_input="repetitive_10MiB.bin",
+        benchmark_driver=ROOT / "algorithms/rle/benchmark/bench.py",
+    ),
+)
+
+ALGORITHM_ORDER: tuple[str, ...] = tuple(a.name for a in ALGORITHMS)
+LANGUAGE_ORDER: tuple[str, ...] = ("cpp",)
+
+# ---------------------------------------------------------------------------
+# Corpus registry
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CorpusEntry:
+    """A test corpus file under tests/data/."""
+
+    name: str
+    """File name (e.g. 'empty.bin')."""
+
+    is_large: bool = False
+    """If True, only included when --include-large is passed to conformance."""
+
+
+CORPUS: tuple[CorpusEntry, ...] = (
+    CorpusEntry("empty.bin"),
+    CorpusEntry("single_byte.bin"),
+    CorpusEntry("alternating.bin"),
+    CorpusEntry("small_dictionary_like.bin"),
+    CorpusEntry("random_1MiB.bin", is_large=True),
+    CorpusEntry("random_10MiB.bin", is_large=True),
+    CorpusEntry("repetitive_10MiB.bin", is_large=True),
+    CorpusEntry("textlike_10MiB.bin", is_large=True),
+)
+
+DEFAULT_CORPUS: tuple[str, ...] = tuple(c.name for c in CORPUS if not c.is_large)
+LARGE_CORPUS: tuple[str, ...] = tuple(c.name for c in CORPUS if c.is_large)
+
+# ---------------------------------------------------------------------------
+# Range corpus cap
+#
+# See docs/adr/0003-range-coder-corpus-cap-policy.md for the policy decision.
+# Do NOT change this value without an OpenSpec change.
+# ---------------------------------------------------------------------------
+
+RANGE_CORPUS_CAP_BYTES: int = 100 * 1024  # 100 KiB
+RANGE_CORPUS_CAP_REASON: str = "range_coder_corpus_cap_100_kib"
+
+# ---------------------------------------------------------------------------
+# Benchmark report schema
+#
+# Field names used in benchmark JSON output.  Changing these breaks the docs
+# page that consumes benchmarks.json.
+# ---------------------------------------------------------------------------
+
+BENCHMARK_REPORT_FIELDS: tuple[str, ...] = (
+    "algorithm",
+    "language",
+    "dataset",
+    "encodeTime",
+    "decodeTime",
+    "encodeSpeed",
+    "decodeSpeed",
+    "compressionRatio",
+    "throughput",
+)
+
+# ---------------------------------------------------------------------------
+# Convenience accessors
+# ---------------------------------------------------------------------------
+
+
+def algorithm_by_name(name: str) -> AlgorithmEntry:
+    """Return the AlgorithmEntry for *name*, raising KeyError if not found."""
+    for algo in ALGORITHMS:
+        if algo.name == name:
+            return algo
+    raise KeyError(f"unknown algorithm: {name!r}")
+
+
+def all_binaries() -> list[tuple[str, str, Path]]:
+    """Return [(algorithm_name, language, binary_path)] for all shipped binaries."""
+    return [
+        (algo.name, binary.language, binary.path)
+        for algo in ALGORITHMS
+        for binary in algo.binaries
+    ]
+
+
+def corpus_files(include_large: bool = False) -> tuple[str, ...]:
+    """Return corpus file names eligible for conformance testing."""
+    if include_large:
+        return tuple(c.name for c in CORPUS)
+    return DEFAULT_CORPUS