feat(storage): index exact content references

experiments/perception/LAB_E50_REPORT_2026-07-29.md

@@ -0,0 +1,78 @@
+# LAB E50 · exact-content reference index
+
+Date: 2026-07-29
+
+Status: accepted non-destructive reference index only
+
+Immutable result:
+`e50-content-reference-index-c10c5ed7345a4f23d46ed0f132d54c378433aa4351e14375805cfe3e28878c81`
+
+## Task
+
+E44 measured exact duplication across the 14 admitted E30–E40 result and
+package roots. E50 converts that measurement into a deterministic logical
+reference index without changing the existing evidence files.
+
+E50 does not:
+
+- delete, rewrite, move, hard-link or copy an existing artifact;
+- reclaim physical storage;
+- authorize a storage migration or new database;
+- weaken source digest, path or root-identity verification;
+- grant command, navigation or safety authority.
+
+## Immutable input
+
+The sole measurement input is E44 result
+`e44-data-amplification-89791978894ec785009e5b76c9325de4d9e910237af57476c9331eb47a8ccca4`.
+E50 requires the same 14 labelled roots, reproduces every E44 catalog digest
+and reproduces the exact E44 analysis SHA-256 before it writes an index.
+
+## Method
+
+Every logical file is addressed by its exact SHA-256 and byte length. One
+canonical locator is selected per digest by the frozen policy
+`prefer-non-package-then-lexical/v1`; every other logical path to the same
+content becomes an `exact-reference`.
+
+The persisted locators contain a root label, root basename and relative path,
+not an absolute host path. Resolution requires an explicit trusted-root map and
+fails closed when the root name, member path, regular-file status, byte length
+or SHA-256 no longer matches. Symlinks and path traversal are rejected.
+
+## Result
+
+| Measurement | Value |
+| --- | ---: |
+| Admitted roots | 14 |
+| Logical references | 2,962 |
+| Canonical content objects | 1,029 |
+| Exact duplicate references | 1,933 |
+| Duplicate content groups | 967 |
+| Logical bytes | 525,471,092 |
+| Addressable unique bytes | 312,753,179 |
+| Exact duplicate bytes | 212,717,913 |
+| Amplification | 1.680146× |
+
+The immutable index contains one canonical reference for every content object.
+All 2,962 logical paths remain addressable.
+
+## Product projection
+
+The existing `Здоровье данных` surface reads the latest valid E50 result and
+reports the active reference index, logical-path count, canonical-content
+count, duplicate-reference count and measured duplicate bytes. It does not
+present the measured reserve as reclaimed disk space.
+
+## Decision
+
+The exact-content reference layer is accepted. Namespace-level deduplication is
+implemented and independently resolvable, while all historical evidence
+remains byte-for-byte in place.
+
+Physical reclamation remains false. A future producer may adopt verified
+reference resolution only through a separately reviewed migration that
+preserves immutable evidence, rollback and consumer compatibility. Existing
+artifacts are not retroactively converted.
+
+Navigation, safety and command authority remain false.

experiments/perception/run_e50_content_reference_index.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Build a non-destructive exact-content reference index from accepted E44 roots."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from k1link.compute.e50_content_reference_index import (
+    build_e50_content_reference_index,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--e44-result", type=Path, required=True)
+    parser.add_argument(
+        "--artifact-root",
+        action="append",
+        required=True,
+        metavar="LABEL=PATH",
+    )
+    parser.add_argument("--output-root", type=Path, required=True)
+    args = parser.parse_args()
+    roots: dict[str, Path] = {}
+    for value in args.artifact_root:
+        label, separator, raw_path = value.partition("=")
+        if not separator or label in roots:
+            parser.error("--artifact-root must be a unique LABEL=PATH")
+        roots[label] = Path(raw_path)
+    result = build_e50_content_reference_index(
+        e44_result_root=args.e44_result,
+        artifact_roots=roots,
+        output_root=args.output_root,
+    )
+    print(
+        json.dumps(
+            {
+                "result_id": result.result_id,
+                "result_root": str(result.result_root),
+                "metrics": result.report["metrics"],
+                "decision": result.report["decision"],
+            },
+            ensure_ascii=False,
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())