Merge pull request #9 from LessUp/architecture-deepening-20260531

docs(arch): contract inventory, ADRs, metadata module, and golden tests

Author: LessUp

CONTEXT.md

@@ -207,6 +207,12 @@ Go 语言实现的共享工具模块，位于 `algorithms/shared/go/codec/`：
 - `openspec/specs/core-architecture/spec.md` - 核心架构规范
 - `openspec/specs/encoding-project/spec.md` - 项目需求规范
 - `openspec/specs/cross-language-testing/spec.md` - 测试规范
+- `docs/architecture/contract-inventory.md` - 架构合同清单（2026-05-31 存档）
+- `docs/adr/0001-validation-metadata-module-shape.md` - 验证元数据模块形状决策
+- `docs/adr/0002-semantic-error-alignment-across-languages.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 模式迁移路径决策
 
 ## 文档术语表
 

algorithms/shared/go/codec/frequency_golden_test.go

@@ -0,0 +1,104 @@
+// Byte-exact golden tests for the shared Frequency Table wire format.
+//
+// These tests pin the exact bytes emitted by WriteFrequenciesToBytes / AppendFrequencies
+// so that refactors that silently change endianness, field order, or count encoding
+// will fail immediately rather than silently producing incompatible output.
+//
+// Wire format (from contract-inventory.md § Binary format and Frequency Table facts):
+//   count     : uint32 little-endian  -- number of frequency entries
+//   freq[0]   : uint32 little-endian
+//   ...
+//   freq[n-1] : uint32 little-endian
+package codec
+
+import (
+	"bytes"
+	"testing"
+)
+
+// TestGolden_WriteFrequenciesToBytes_Empty verifies that an empty table encodes
+// as exactly 4 zero bytes (count=0 in little-endian).
+// Wire: 00 00 00 00
+func TestGolden_WriteFrequenciesToBytes_Empty(t *testing.T) {
+	var out []byte
+	WriteFrequenciesToBytes(&out, nil)
+	want := []byte{0x00, 0x00, 0x00, 0x00}
+	if !bytes.Equal(out, want) {
+		t.Errorf("empty table: got %x, want %x", out, want)
+	}
+}
+
+// TestGolden_WriteFrequenciesToBytes_SingleEntry verifies count=1 then value=1.
+// Wire: 01 00 00 00  01 00 00 00
+func TestGolden_WriteFrequenciesToBytes_SingleEntry(t *testing.T) {
+	var out []byte
+	WriteFrequenciesToBytes(&out, []uint32{1})
+	want := []byte{
+		0x01, 0x00, 0x00, 0x00, // count = 1
+		0x01, 0x00, 0x00, 0x00, // freq[0] = 1
+	}
+	if !bytes.Equal(out, want) {
+		t.Errorf("single-entry table: got %x, want %x", out, want)
+	}
+}
+
+// TestGolden_WriteFrequenciesToBytes_ThreeEntries verifies count=3 then each value.
+// Wire: 03 00 00 00  01 00 00 00  02 00 00 00  03 00 00 00
+func TestGolden_WriteFrequenciesToBytes_ThreeEntries(t *testing.T) {
+	var out []byte
+	WriteFrequenciesToBytes(&out, []uint32{1, 2, 3})
+	want := []byte{
+		0x03, 0x00, 0x00, 0x00, // count = 3
+		0x01, 0x00, 0x00, 0x00, // freq[0] = 1
+		0x02, 0x00, 0x00, 0x00, // freq[1] = 2
+		0x03, 0x00, 0x00, 0x00, // freq[2] = 3
+	}
+	if !bytes.Equal(out, want) {
+		t.Errorf("three-entry table: got %x, want %x", out, want)
+	}
+}
+
+// TestGolden_WriteFrequenciesToBytes_MaxU32 verifies that u32::MAX is preserved.
+// Wire: 01 00 00 00  FF FF FF FF
+func TestGolden_WriteFrequenciesToBytes_MaxU32(t *testing.T) {
+	var out []byte
+	WriteFrequenciesToBytes(&out, []uint32{^uint32(0)})
+	want := []byte{
+		0x01, 0x00, 0x00, 0x00, // count = 1
+		0xFF, 0xFF, 0xFF, 0xFF, // freq[0] = 0xFFFFFFFF
+	}
+	if !bytes.Equal(out, want) {
+		t.Errorf("max u32 entry: got %x, want %x", out, want)
+	}
+}
+
+// TestGolden_WriteFrequenciesToBytes_Count256 verifies multi-byte count encoding.
+// count=256 must encode as 00 01 00 00 in little-endian.
+func TestGolden_WriteFrequenciesToBytes_Count256(t *testing.T) {
+	freq := make([]uint32, 256)
+	var out []byte
+	WriteFrequenciesToBytes(&out, freq)
+	wantCountBytes := []byte{0x00, 0x01, 0x00, 0x00}
+	if !bytes.Equal(out[:4], wantCountBytes) {
+		t.Errorf("count=256 field: got %x, want %x", out[:4], wantCountBytes)
+	}
+	wantLen := 4 + 256*4
+	if len(out) != wantLen {
+		t.Errorf("total length: got %d, want %d", len(out), wantLen)
+	}
+}
+
+// TestGolden_AppendFrequencies_PreservesLeadingBytes verifies that AppendFrequencies
+// appends to (not replaces) an existing byte slice.
+func TestGolden_AppendFrequencies_PreservesLeadingBytes(t *testing.T) {
+	out := []byte{0xDE, 0xAD}
+	AppendFrequencies(&out, []uint32{5})
+	want := []byte{
+		0xDE, 0xAD, // original prefix
+		0x01, 0x00, 0x00, 0x00, // count = 1
+		0x05, 0x00, 0x00, 0x00, // freq[0] = 5
+	}
+	if !bytes.Equal(out, want) {
+		t.Errorf("AppendFrequencies: got %x, want %x", out, want)
+	}
+}

algorithms/shared/rust/tests/frequency_golden.rs

@@ -0,0 +1,151 @@
+// Byte-exact golden tests for the shared Frequency Table wire format.
+//
+// These tests pin the exact bytes emitted by write_frequencies so that
+// refactors that silently change endianness, field order, or count encoding
+// will fail immediately rather than silently producing incompatible output.
+//
+// Wire format (from contract-inventory.md § Binary format and Frequency Table facts):
+//   count     : uint32 little-endian  -- number of frequency entries
+//   freq[0]   : uint32 little-endian
+//   ...
+//   freq[n-1] : uint32 little-endian
+//
+// The exact 257-symbol layout used by Huffman, Arithmetic, and Range algorithms
+// is not tested here because it depends on input data; instead we test the
+// wire-format primitives with small, hand-computed vectors.
+
+use compresskit_codec::codec::frequency::{read_frequencies_exact, write_frequencies};
+
+// ---------------------------------------------------------------------------
+// Golden byte vectors (hand-computed, do not edit without updating comments)
+// ---------------------------------------------------------------------------
+
+/// write_frequencies([]) must produce count=0 encoded as 4 little-endian zero bytes.
+/// Wire: 00 00 00 00
+#[test]
+fn golden_write_empty_table() {
+    let freq: Vec<u32> = vec![];
+    let mut out = Vec::new();
+    write_frequencies(&mut out, &freq);
+    assert_eq!(
+        out,
+        vec![0x00, 0x00, 0x00, 0x00],
+        "empty frequency table must encode as 4-byte LE zero count"
+    );
+}
+
+/// write_frequencies([1]) must produce count=1 then value=1, each as 4 LE bytes.
+/// Wire: 01 00 00 00  01 00 00 00
+#[test]
+fn golden_write_single_entry() {
+    let freq: Vec<u32> = vec![1];
+    let mut out = Vec::new();
+    write_frequencies(&mut out, &freq);
+    assert_eq!(
+        out,
+        vec![
+            0x01, 0x00, 0x00, 0x00, // count = 1
+            0x01, 0x00, 0x00, 0x00, // freq[0] = 1
+        ],
+        "single-entry table wire bytes mismatch"
+    );
+}
+
+/// write_frequencies([1, 2, 3]) must produce count=3 then each value as 4 LE bytes.
+/// Wire: 03 00 00 00  01 00 00 00  02 00 00 00  03 00 00 00
+#[test]
+fn golden_write_three_entries() {
+    let freq: Vec<u32> = vec![1, 2, 3];
+    let mut out = Vec::new();
+    write_frequencies(&mut out, &freq);
+    assert_eq!(
+        out,
+        vec![
+            0x03, 0x00, 0x00, 0x00, // count = 3
+            0x01, 0x00, 0x00, 0x00, // freq[0] = 1
+            0x02, 0x00, 0x00, 0x00, // freq[1] = 2
+            0x03, 0x00, 0x00, 0x00, // freq[2] = 3
+        ],
+        "three-entry table wire bytes mismatch"
+    );
+}
+
+/// Max u32 value must be preserved exactly in the wire format.
+/// Wire: 01 00 00 00  FF FF FF FF
+#[test]
+fn golden_write_max_u32_entry() {
+    let freq: Vec<u32> = vec![u32::MAX];
+    let mut out = Vec::new();
+    write_frequencies(&mut out, &freq);
+    assert_eq!(
+        out,
+        vec![
+            0x01, 0x00, 0x00, 0x00, // count = 1
+            0xFF, 0xFF, 0xFF, 0xFF, // freq[0] = u32::MAX
+        ],
+        "max u32 entry wire bytes mismatch"
+    );
+}
+
+/// Multi-byte count value: 256 entries.
+/// Wire: 00 01 00 00  (count=256 LE)  followed by 256 * 4 bytes.
+#[test]
+fn golden_write_256_entries_count_encoding() {
+    let freq: Vec<u32> = vec![0u32; 256];
+    let mut out = Vec::new();
+    write_frequencies(&mut out, &freq);
+    // Only check the first 4 bytes (count field).
+    assert_eq!(
+        &out[..4],
+        &[0x00, 0x01, 0x00, 0x00],
+        "count=256 must encode as 00 01 00 00 in little-endian"
+    );
+    assert_eq!(out.len(), 4 + 256 * 4, "total length must be 4 + 256*4");
+}
+
+// ---------------------------------------------------------------------------
+// Round-trip tests: write then read_frequencies_exact must recover original data
+// ---------------------------------------------------------------------------
+
+#[test]
+fn roundtrip_three_entries_via_exact_reader() {
+    let original: Vec<u32> = vec![7, 11, 13];
+    let mut out = Vec::new();
+    write_frequencies(&mut out, &original);
+
+    let mut pos = 0;
+    let recovered = read_frequencies_exact(
+        &out,
+        &mut pos,
+        3,
+        "truncated count",
+        "truncated entries",
+        "invalid count",
+    )
+    .expect("read_frequencies_exact must succeed on valid data");
+
+    assert_eq!(recovered, original, "round-trip must recover original frequencies");
+    assert_eq!(pos, out.len(), "reader must consume all bytes");
+}
+
+#[test]
+fn roundtrip_exact_reader_rejects_count_mismatch() {
+    let freq: Vec<u32> = vec![1, 2, 3];
+    let mut out = Vec::new();
+    write_frequencies(&mut out, &freq);
+
+    let mut pos = 0;
+    let result = read_frequencies_exact(
+        &out,
+        &mut pos,
+        4, // wrong expected count
+        "truncated count",
+        "truncated entries",
+        "invalid count",
+    );
+
+    assert!(
+        result.is_err(),
+        "read_frequencies_exact must reject count mismatch"
+    );
+}

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/0002-semantic-error-alignment-across-languages.md

@@ -0,0 +1,38 @@
+# ADR 0002: Semantic error alignment across languages
+
+Date: 2026-05-31  
+Status: Accepted
+
+## Context
+
+The three language implementations expose the same seven semantic error kinds (`BUF_TOO_SMALL`, `ERR_TRUNCATED`, `ERR_CORRUPT`, `ERR_INVALID_STATE`, `ERR_SIZE_LIMIT`, `ERR_VERSION_UNSUPPORTED`, `ERR_UNKNOWN_ALGO`) but through structurally different APIs:
+
+- **Go**: `ErrorKind` enum + `CodecError` struct + sentinel errors + `errors.Is` mapping (plus `KindIO` for wrapped I/O)
+- **Rust**: `CodecError` enum with `Display` + helper mapping from `io::Error`
+- **C++**: `StatusCode` inside `Result<T>`; CLI returns boolean success/failure
+
+Some algorithm-level direct APIs still map errors through local messages before the shared codec adapter normalizes them (Range Rust, RLE Rust, Range Go).
+
+The `contract-inventory.md` notes that structural API identity across languages is explicitly **not** the goal.
+
+## Decision
+
+Align at the **semantic** level only:
+
+1. The seven canonical error kinds listed in `CONTEXT.md` are the normative contract. Each language must be able to produce and identify each kind.
+2. Language-idiomatic representations (enum, struct, sentinel, Result type) are preserved. No forced structural uniformity.
+3. Algorithm-level error messages flowing to CLI output must be English and actionable (OpenSpec requirement). Internal mapping paths may remain language-local provided the final kind is correct.
+4. A shared cross-language contract test (see ADR phase-2 deliverables) verifies that encode/decode round-trips produce the correct kind on corruption, truncation, size-limit, and invalid-state inputs.
+
+## Constraints
+
+- Changing the public streaming/buffer API error kind semantics or lifecycle requires an OpenSpec change.
+- Go `KindIO` is a Go-local extension, not a cross-language contract; it must not appear in conformance test assertions.
+
+## Consequences
+
+**Positive**: Each language stays idiomatic; shared tests pin semantic equivalence; algorithm-level mapping quirks are explicitly tolerated while remaining testable.
+
+**Negative**: Developers must understand that identical code structure is not the goal; code review must check semantic equivalence rather than structural similarity.
+
+**Deferred**: Whether `KindIO` should be formally excluded from the CONTEXT vocabulary, or documented as Go-only, is a minor cleanup deferred to documentation alignment (Todo 8 / ADR 0002 amendment).

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.