docs(governance): Stage 1 ADR collision freeze + dual-pack serve boundary
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)
This commit is contained in:
Shay
parent
6ffea249ec
commit
8494a239e4
6 changed files with 267 additions and 24 deletions
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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/<pack_id>/`, 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/<pack_id>/` 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`
|
||||
75
docs/adr/MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md
Normal file
75
docs/adr/MASTER-BLUEPRINT-2026-07-20-ADR-MAPPING.md
Normal file
|
|
@ -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/<pack_id>/` | **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
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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/<pack_id>/` | **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`
|
||||
|
|
|
|||
117
tests/test_pack_draft_serve_boundary.py
Normal file
117
tests/test_pack_draft_serve_boundary.py
Normal file
|
|
@ -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/<pack_id>/`` 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/<id>."""
|
||||
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
|
||||
Loading…
Reference in a new issue