From 8494a239e4c92f0f4f24e12b5cfcbb59eecfdd8b Mon Sep 17 00:00:00 2001 From: Shay Date: Mon, 20 Jul 2026 13:43:25 -0700 Subject: [PATCH] docs(governance): Stage 1 ADR collision freeze + dual-pack serve boundary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reconcile Master Blueprint ADR-0240–0253 titles with the live Accepted registry without renumbering history. Claim ADR-0253 for the freeze policy itself; reserve 0254–0261 for Blueprint gaps. Document packs/data vs packs/he|grc dual boundary and pin serve isolation in smoke/packs suites. [Verification]: Smoke 180 passed (includes 4 dual-pack boundary pins) --- core/cli_test.py | 3 + ...nt-adr-collision-and-dual-pack-boundary.md | 40 ++++++ ...MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md | 75 +++++++++++ docs/adr/README.md | 11 ++ packs/README.md | 45 ++++--- tests/test_pack_draft_serve_boundary.py | 117 ++++++++++++++++++ 6 files changed, 267 insertions(+), 24 deletions(-) create mode 100644 docs/adr/ADR-0253-master-blueprint-adr-collision-and-dual-pack-boundary.md create mode 100644 docs/adr/MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md create mode 100644 tests/test_pack_draft_serve_boundary.py diff --git a/core/cli_test.py b/core/cli_test.py index 1e207bf1..7dc239d2 100644 --- a/core/cli_test.py +++ b/core/cli_test.py @@ -44,6 +44,8 @@ TEST_SUITES: dict[str, tuple[str, ...]] = { # the falsifiability claim blocks-on-regression rather than # detect-after-merge. "tests/test_pack_measurements_phase2.py", + # ADR-0253 dual-pack boundary — draft he/grc trees must not be serve imports. + "tests/test_pack_draft_serve_boundary.py", ), "runtime": ( "tests/test_chat_runtime.py", @@ -75,6 +77,7 @@ TEST_SUITES: dict[str, tuple[str, ...]] = { "tests/test_teaching_coverage_cli.py", ), "packs": ( + "tests/test_pack_draft_serve_boundary.py", "tests/test_core_semantic_seed_pack.py", "tests/test_adr_0127_pack_ratification.py", "tests/test_frame_registry_load.py", diff --git a/docs/adr/ADR-0253-master-blueprint-adr-collision-and-dual-pack-boundary.md b/docs/adr/ADR-0253-master-blueprint-adr-collision-and-dual-pack-boundary.md new file mode 100644 index 00000000..d55c0745 --- /dev/null +++ b/docs/adr/ADR-0253-master-blueprint-adr-collision-and-dual-pack-boundary.md @@ -0,0 +1,40 @@ +# ADR-0253: Master Blueprint ADR Collision Resolution & Dual-Pack Boundary + +**Status**: Accepted (Stage 1 governance freeze) +**Date**: 2026-07-20 +**Deciders**: CORE engineering (Master Convergence Stage 1) +**Related**: `docs/adr/MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md`, Master Architectural Specification 2026-07-20 + +## Context + +The Master Blueprint §3.2 lists ADRs 0240–0253 with intent titles that **collide by number** with the repository’s already-Accepted ADR-0246 through ADR-0252 (and with other live 0240–0245 titles). Overwriting Accepted history is forbidden by repository governance and by the Stage 1 program rule. + +Separately, language packs exist as both: + +- **compiled runtime artifacts** under `packs/data//`, and +- **source/draft trees** such as `packs/he`, `packs/grc`, `packs/en`, `packs/el`. + +Serve paths must not treat draft source trees as importable authority. + +## Decision + +1. **ID history is immutable.** Accepted ADR numbers keep their live titles and scopes. Blueprint intent titles never renumber Accepted ADRs. +2. **Mapping is the reconciliation surface.** The file + `docs/adr/MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md` + is the authoritative Blueprint-ID → repository-home table (Covered / Partial / Gap / reserved new IDs 0254–0261). +3. **This ADR-0253 number is claimed for governance freeze**, not for the Blueprint’s “Holonomy Primacy Rust SIMD” title. That Blueprint intent is reserved as **ADR-0261** if implemented later. +4. **Dual-pack boundary** + - Runtime serve/load of language packs uses `packs.compiler` → `packs/data//` only. + - `packs/he`, `packs/grc`, and peer source trees are draft/source material; they are not serve-import authority. + - Architecture tests pin that serve-entry modules do not import `packs.he` / `packs.grc` as packages for serving. + +## Consequences + +- Stage 3/4 Blueprint work must open **new** ADR numbers (0254+) or amend the correct existing owner ADR — never 0246–0252 renames. +- CI fails if draft HE/GRC package imports appear on the serve import graph. +- Documentation that cites Blueprint ADR numbers for convergence work must also cite this mapping. + +## Validation + +- `tests/test_pack_draft_serve_boundary.py` +- Mapping file present and linked from `docs/adr/README.md` diff --git a/docs/adr/MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md b/docs/adr/MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md new file mode 100644 index 00000000..153260cc --- /dev/null +++ b/docs/adr/MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md @@ -0,0 +1,75 @@ +# Master Blueprint ADR Mapping (2026-07-20) + +**Status**: Governing mapping for the Master Architectural Specification & System Convergence Blueprint (2026-07-20) +**Policy**: Do **not** overwrite, renumber, or falsify Accepted ADR-0246 through ADR-0252. +**Authority**: This mapping reconciles Blueprint §3.2 titles with the live `docs/adr/` registry. + +## Collision rule + +The Blueprint lists ADR-0240–0253 with intent titles that **collide by number** with already-Accepted repository ADRs (especially 0246–0252). Repository history wins for IDs. Blueprint *decisions* land as: + +1. **Covered** — mapped to an existing Accepted ADR (or AGENTS.md / runtime_contracts) that already carries the intent; or +2. **Amended** — small amendment to the correct existing ADR when scope already owns the decision; or +3. **Newly allocated** — next free ADR number (starting ADR-0253+) for Blueprint intents with no home. + +## Registry truth (live Accepted / Proposed) + +| ID | Live title (repository) | Live status | +|----|-------------------------|-------------| +| 0240 | Analogical Transfer Validation Harness + Biography Holonomy Blade | Proposed | +| 0241 | Wave-Field Driven Hyperbolic Atlas and Resonant Algebraic Cognition | Accepted | +| 0242 | Deterministic Fibonacci Operators and Evidence-Gated Optimization | Accepted | +| 0243 | Wave-Field Cognitive Lifecycle | Accepted | +| 0244 | Wave-Field Identity Manifold and Inalienable Geometric Alignment | Accepted | +| 0245 | CGA Unification — Mechanical Sympathy, Boundary Rigor | Accepted | +| 0246 | Induced Identity Action and Path Integrity | Accepted | +| 0247 | Multi-Port Residual Protocol | Accepted | +| 0248 | Integrity-Coordinated Handoffs | Accepted | +| 0249 | Reader→Hamiltonian Compiler | Accepted | +| 0250 | Tier-2 Multi-Entity Arithmetic | Accepted | +| 0251 | Reader-Arc Recalibration | Partial / decision §§1–4 | +| 0252 | CORE Problem-Solving Paradigm | Accepted | +| 0253 | *(was vacant; reserved for governance — see below)* | — | + +## Blueprint intent → home + +| Blueprint ID / title (intent) | Resolution | Home in repository | +|-------------------------------|------------|--------------------| +| BP-0240 Cl(4,1) Conformal Wave-Field Sovereignty & Pipeline Integration | **Covered (multi-home)** | `AGENTS.md` invariants + ADR-0241 + ADR-0244 + cognitive pipeline contracts; do not steal ADR-0240 number from biography harness | +| BP-0241 Holographic Standing-Wave Storage & Resonant Recall | **Covered** | ADR-0241 (live title differs; wave/resonant substrate) + holographic vault research quarantine | +| BP-0242 Deterministic Fibonacci Operators & Bounded Local Search | **Covered** | ADR-0242 | +| BP-0243 Wave-Field Cognitive Lifecycle & Multimodal Ingress | **Covered** | ADR-0243 | +| BP-0244 Wave-Field Identity Manifold & Gram Subspace Projection | **Covered** | ADR-0244 | +| BP-0245 CGA Unification, PyO3 Fast-Paths, f64→f32 Boundary | **Covered** | ADR-0245 | +| BP-0246 Smith Chart Conformal Interconnect Grammar | **Gap / new allocation** | Not ADR-0246 (that ID is Induced Identity Action). Allocate **ADR-0254** if/when interconnect grammar is implemented | +| BP-0247 Multi-Step Inductive Closure & Conformal Atom Unification | **Gap / Stage 3** | Not ADR-0247 (Multi-Port Residual). Partial telemetry in `CognitiveTurnPipeline._proof_atom`. Allocate **ADR-0255** for full fixed-point closure | +| BP-0248 Fail-Closed Hebrew Root-Sense Ambiguity Policy | **Gap / Stage 3–4** | Not ADR-0248 (Integrity Handoffs). Allocate **ADR-0256** | +| BP-0249 Active Dual-Correction Backpressure Signaling | **Partial cover** | Backpressure types live under `core/cognition/backpressure.py`; not ADR-0249 (Reader compiler). Map intent to existing backpressure module; new ADR **0257** only if policy must be re-decided | +| BP-0250 Autonomous Geometric Promotion SPECULATIVE→COHERENT | **Covered (vault)** | `vault/store.py` promotion + `teaching.epistemic.EpistemicStatus`; not ADR-0250 (Tier-2 arithmetic). Document in vault/teaching ADRs; optional **ADR-0258** if geometric promotion conditions need a dedicated decision | +| BP-0251 Delta-CRDT Vault Serialization & 256-bit Digest Integrity | **Partial cover** | Digests: `multivector_content_digest` / vault metadata; CRDT claims must not overwrite ADR-0251. Allocate **ADR-0259** only if Delta-CRDT is newly decided | +| BP-0252 Low-Discrepancy Mode Centroid Sunflower Allocator | **Gap** | Not ADR-0252 (Problem-Solving Paradigm). Allocate **ADR-0260** if implemented | +| BP-0253 Holonomy Primacy Enforcement in Rust PyO3 SIMD Kernels | **Gap** | No live ADR-0253 holonomy doc. Allocate **ADR-0261** for holonomy/Rust primacy if needed | + +## Governance ADRs allocated by Stage 1 + +| New ID | Title | Purpose | +|--------|-------|---------| +| **ADR-0253** | Master Blueprint ADR Collision Resolution & Dual-Pack Boundary | This freeze: mapping policy + dual-pack serve isolation (does **not** claim Blueprint holonomy content) | + +Numbers **0254–0261** are **reserved** for Blueprint intents listed as Gap above; they are not materialised until the owning stage implements them. + +## Dual-pack boundary (summary) + +| Tree | Role | Serve authority | +|------|------|-----------------| +| `packs/data//` | **Compiled runtime** language packs (manifest + lexicon + checksums) | **Yes** — via `packs.compiler.load_pack` | +| `packs/he`, `packs/grc`, `packs/en`, `packs/el`, … | **Source / draft** language material (morphology, lemmas, probes) | **No** as Python import for serve; compile into `packs/data` first | +| `packs/safety`, `packs/identity`, `packs/ethics`, … | Governance/style modality packs | Serve via dedicated loaders | + +Enforcement: architecture test `tests/test_pack_draft_serve_boundary.py`. + +## Non-goals + +- Renaming or rewriting Accepted ADR-0246–0252 bodies to match Blueprint titles +- Claiming Stage 3/4 decisions complete by documentation alone +- Force-fitting Blueprint numbers onto Accepted history diff --git a/docs/adr/README.md b/docs/adr/README.md index fa203864..7582807f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -8,3 +8,14 @@ references. Runtime execution contracts live in `docs/specs/runtime_contracts.md`; ADRs may cite that spec when a decision adds or changes a runtime invariant. + +## Master Blueprint ADR mapping (2026-07-20) + +The Master Architectural Specification lists ADR-0240–0253 with titles that +**collide by number** with Accepted repository ADRs (especially 0246–0252). + +- **Do not renumber or overwrite Accepted ADRs.** +- Authoritative reconciliation: + [`MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md`](./MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md) +- Governance freeze decision: + [`ADR-0253-master-blueprint-adr-collision-and-dual-pack-boundary.md`](./ADR-0253-master-blueprint-adr-collision-and-dual-pack-boundary.md) diff --git a/packs/README.md b/packs/README.md index 2fd4f5c6..23560dc0 100644 --- a/packs/README.md +++ b/packs/README.md @@ -1,35 +1,32 @@ # Runtime Pack Artifacts -`packs/` contains ratified runtime pack artifacts and their narrow loaders: -safety, identity, ethics, register, anchor-lens, modality packs, source-language -packs, primitives, and companion validators. +`packs/` holds runtime pack **artifacts**, **source language trees**, and **compilers/loaders**. -This directory is not interchangeable with `packs/`: +## Dual-pack boundary (ADR-0253 / Master Blueprint Stage 1) -- `packs/` stores runtime governance/style/safety/modality artifacts and source - pack material such as `packs/en`, `packs/he`, `packs/grc`, and `packs/el`. -- `packs/` stores linguistic pack schemas, compilers, loaders, and - reviewed semantic pack data under `packs/data/`. -- `core_ingest/` prepares external candidate pressure; it does not ratify or - rewrite these packs. +| Path | Role | Serve / runtime authority | +|------|------|---------------------------| +| `packs/data//` | **Compiled runtime** language packs (`manifest.json`, `lexicon.jsonl`, checksummed companions) | **Yes** — only via `packs.compiler.load_pack` / `load_pack_entries` | +| `packs/he`, `packs/grc`, `packs/en`, `packs/el`, … | **Source / draft** language material (lemmas, morphology, probes, pack.toml) | **No** — not importable serve authority; compile into `packs/data` first | +| `packs/safety`, `packs/identity`, `packs/ethics`, `packs/register`, `packs/anchor_lens`, modality packs | Governance / style / modality artifacts | Yes — via their dedicated loaders | +| `packs/primitives`, `packs/schema.py`, `packs/compiler.py`, `packs/loader.py` | Schemas, compilers, loaders | Tooling / load path only | -Mutation rule: durable pack changes must be reviewed or proof-carrying and -must use the relevant validator/ratification lane. Do not add ad hoc runtime -pack writes. +**Hard rule:** Durable pack mutation is reviewed or proof-carrying. Do not write ad hoc runtime pack files from serve. +## Compilers (two different boundaries) -# Language Packs +| Compiler | Consumes | Produces | +|----------|----------|----------| +| `packs.compiler` | Reviewed pack data under `packs/data` | Runtime vocab / manifold structures | +| `core_ingest.compiler` | External candidate pressure | Validation reports + provisional learning artifacts | -`packs/` owns reviewed language-pack loading and compilation. It turns -pack manifests, lexicon rows, morphology, grammar attractors, and alignment -metadata into runtime vocab/manifold structures. +The shared word “compiler” means deterministic lowering across a trust boundary; source material and outputs differ. -This compiler is distinct from `core_ingest.compiler`: +## Mutation -- `packs.compiler` consumes reviewed pack data and builds linguistic - runtime structures. -- `core_ingest.compiler` consumes external candidate pressure and produces - validation reports plus provisional learning artifacts. +Durable changes must use the relevant validator/ratification lane. Session or speculative state must not masquerade as compiled pack COHERENT authority. -The shared word "compiler" means "deterministic lowering across a boundary"; -the source material, trust boundary, and output structures are different. +## Validation + +Architecture pin: `tests/test_pack_draft_serve_boundary.py` +Mapping: `docs/adr/MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md` diff --git a/tests/test_pack_draft_serve_boundary.py b/tests/test_pack_draft_serve_boundary.py new file mode 100644 index 00000000..f5333a10 --- /dev/null +++ b/tests/test_pack_draft_serve_boundary.py @@ -0,0 +1,117 @@ +"""Architecture pin: draft language-pack trees are not serve import authority. + +ADR-0253 / Master Blueprint Stage 1 dual-pack boundary: + +* Runtime language packs load from ``packs/data//`` via + ``packs.compiler.load_pack``. +* Source trees ``packs/he``, ``packs/grc`` (and peers) are draft material; + serve entrypoints must not import them as Python packages. + +This is a static + process probe — not a substitute for compile-time validation. +""" + +from __future__ import annotations + +import ast +import subprocess +import sys +from pathlib import Path + +import pytest + +_ROOT = Path(__file__).resolve().parents[1] + +# Draft/source language trees — not compiled runtime authority. +_DRAFT_PACK_MODULES = frozenset( + { + "packs.he", + "packs.grc", + "packs.en", + "packs.el", + } +) + +# Serve-adjacent entry modules that must not import draft pack packages. +_SERVE_ENTRY_FILES = ( + _ROOT / "chat" / "runtime.py", + _ROOT / "core" / "cognition" / "pipeline.py", + _ROOT / "core" / "cli.py", +) + + +def _module_imports(path: Path) -> set[str]: + tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path)) + found: set[str] = set() + for node in ast.walk(tree): + if isinstance(node, ast.Import): + for alias in node.names: + found.add(alias.name) + elif isinstance(node, ast.ImportFrom) and node.module: + found.add(node.module) + return found + + +def test_serve_entry_files_do_not_import_draft_language_pack_packages(): + offenders: list[str] = [] + for path in _SERVE_ENTRY_FILES: + assert path.is_file(), f"missing serve entry {path}" + imports = _module_imports(path) + for draft in _DRAFT_PACK_MODULES: + if draft in imports or any( + imp == draft or imp.startswith(draft + ".") for imp in imports + ): + offenders.append(f"{path.relative_to(_ROOT)} imports {draft}") + assert not offenders, "draft pack imports on serve entries:\n" + "\n".join(offenders) + + +def test_compiler_load_pack_resolves_under_packs_data_only(): + """``_load_pack_cached`` must root pack_dir at packs/data/.""" + compiler_path = _ROOT / "packs" / "compiler.py" + src = compiler_path.read_text(encoding="utf-8") + assert 'Path(__file__).parent / "data"' in src + assert "def load_pack(" in src + # No alternate root that points at packs/he or packs/grc as compiled home. + tree = ast.parse(src) + for node in ast.walk(tree): + if isinstance(node, ast.Constant) and isinstance(node.value, str): + # Allow incidental strings in comments/docs only via absence of + # path construction to /he/ or /grc/ as pack_dir — checked below. + pass + # Explicit: load path construction uses data/, not he/ or grc/. + assert '/ "he"' not in src and "/ 'he'" not in src + assert '/ "grc"' not in src and "/ 'grc'" not in src + + +def test_import_chat_runtime_does_not_load_draft_he_grc_modules(): + """Process probe: serve import must not pull packs.he / packs.grc into sys.modules.""" + banned = sorted(_DRAFT_PACK_MODULES) + probe = ( + "import importlib, sys, json;" + "importlib.import_module('chat.runtime');" + f"banned={banned!r};" + "leaked=sorted(m for m in sys.modules for b in banned " + "if m==b or m.startswith(b+'.'));" + "print(json.dumps(leaked))" + ) + result = subprocess.run( + [sys.executable, "-c", probe], + cwd=str(_ROOT), + capture_output=True, + text=True, + env={"PYTHONPATH": str(_ROOT), "PATH": ""}, + check=False, + ) + assert result.returncode == 0, f"probe failed: {result.stderr[-2000:]}" + import json as _json + + leaked = _json.loads(result.stdout.strip().splitlines()[-1]) + assert leaked == [], f"serve process loaded draft pack modules: {leaked}" + + +def test_mapping_document_exists_and_forbids_overwrite_policy(): + mapping = _ROOT / "docs" / "adr" / "MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md" + assert mapping.is_file() + text = mapping.read_text(encoding="utf-8") + assert "Do **not** overwrite" in text or "Do not overwrite" in text + assert "ADR-0246" in text and "Induced Identity Action" in text + assert "packs/data" in text