Migration/ravel from mncs 20260803 182840

ARCHITECTURE_GAPS.md

@@ -0,0 +1,37 @@
+# What prevented RAVEL from being a unified architecture
+
+RAVEL 0.1 unified exact routing, retrieval, compressed experts, and conditional inference. RAVEL-T 0.2 added recursive expert birth and training. Those versions were still components rather than an architecture because the learned unit did not also own representation, reconstruction, action-conditioned prediction, temporal memory, planning, continual adaptation, retirement, checkpoint identity, and rollback equivalence.
+
+RAVEL-U 0.3 closes that bounded architectural gap. One expert now simultaneously acts as:
+
+- a retrieval key;
+- a compressed representation of a state region;
+- a reconstruction program;
+- a classifier;
+- an action-conditioned next-state predictor;
+- a node in learned temporal memory;
+- a planning destination;
+- a training and replay shard;
+- a lineage-bearing lifecycle object; and
+- a measured unit of computational cost.
+
+The same expert population builds the exact routing lattice, receives training assignments, identifies unresolved error, creates children, compiles its transition graph, supplies plans, adapts to semantic drift, and retires low-utility duplicate children. RAVEL 0.3 intended checkpoint restoration to reproduce both identity and behavior, but its digest and checksum were incomplete. RAVEL 0.4 supplies complete-field canonical identity, restored measurement comparison, and corruption tests.
+
+## Intentionally external
+
+RAVEL is not made safer or more complete by allowing the recursive execution plane to rewrite everything. The following remain outside its authority:
+
+- raw modality adapters and data acquisition;
+- intended-use and prohibited-use policy;
+- evaluator, seeds, partitions, thresholds, and promotion decision;
+- authorization for external effects;
+- protected evidence custody;
+- release signing and deployment;
+- rollback approval; and
+- formal MNCS or MNCDS status.
+
+These are control surfaces, not missing intelligence components. Moving them into the recursive model would remove the independent boundary needed to evaluate, contain, replace, or retire it.
+
+## Remaining scale gaps
+
+RAVEL-U is a deterministic synthetic mechanism proof. It does not yet establish learned tokenization, language or multimodal generation, stochastic world modeling, gradient-scale optimization, distributed execution, long-horizon credit assignment, causal identification, protected real-data generalization, adversarial robustness, or production safety. Those are the next experimental domains, not hidden claims of this capsule.

CONTRACT.md

@@ -0,0 +1,42 @@
+# RAVEL 0.1 readable contract
+
+## Intended use
+
+RAVEL 0.1 is a research component for exact conditional dispatch over a generated store of quantized experts. It tests whether a machine-generated routing lattice can reduce expert evaluations on familiar inputs while preserving the result of a complete reference scan.
+
+## Input and reference behavior
+
+A query contains eight signed 8-bit values. The declared in-domain range is `[-64, 63]` in every dimension.
+
+For every expert, the reference computes squared Euclidean distance between the query and expert centroid. It selects the minimum distance, resolving equal distances in favor of the lower expert identifier. It executes the selected expert as an integer dot product plus bias.
+
+## Candidate authority
+
+The candidate retrieves 24 generated experts from one lattice cell. It may return without a complete scan only when the routed winner's distance is strictly lower than the precomputed minimum possible distance of every excluded expert.
+
+Equality is not accepted. Uncertain or out-of-domain requests must scan every excluded expert before returning.
+
+Candidate output must exactly match the reference for expert identity, distance, and execution score.
+
+## Invariants
+
+1. Routing uncertainty never counts as success.
+2. Out-of-domain values force fallback.
+3. Each expert is evaluated at most once per query.
+4. Candidate work is bounded between 24 and 256 expert evaluations.
+5. Tie behavior is deterministic and reference-equivalent.
+6. The complete oracle remains available as rollback.
+
+## Development gates
+
+On the declared familiar workload:
+
+- zero output mismatches;
+- at least 95% certified routes; and
+- no more than 32 mean expert evaluations.
+
+The uniform control workload requires exactness but does not require acceleration. Refusing unjustified shortcuts is expected.
+
+## Claim boundary
+
+This experiment is not a trained foundation model, production inference server, proof of generalization, or formal MNCS/MNCDS claim. Formal status remains `UNKNOWN` until independent protected evaluation and lifecycle evidence exist.

MIGRATION_ORIGIN.md

@@ -0,0 +1,21 @@
+# Migration origin
+
+The standalone RAVEL repository was extracted from:
+
+- Source repository: `epi13/machine-native-complexity-standard`
+- Source commit: `c521d47441905b36fc581a1c10e88282c6163f09`
+- Historical subtree: `case-studies/ravel/`
+
+The former RAVEL subtree was imported with its filtered Git history.
+
+The following research tracks originally lived outside the RAVEL subtree and
+were imported separately from the same source commit:
+
+- `docs/recursive-architecture-research.md`
+- `docs/recursive-experience-substrate.md`
+- `studies/recursive-architecture-comparison/`
+- `studies/recursive-experience-substrate/`
+
+The new standalone repository README and architectural documents remain the
+current project-level authority. The former MNCS RAVEL landing page is retained
+at `docs/HISTORICAL_RAVEL_README.md`.

Makefile

@@ -0,0 +1,218 @@
+CC ?= cc
+SAN_CC ?= clang
+CFLAGS ?= -std=c11 -O3 -Wall -Wextra -Werror -pedantic
+LDLIBS ?= -lm
+
+.PHONY: test evidence training-test training-evidence training-check unified-test unified-evidence unified-check 0.4-evidence 0.4-check 0.4-manifest-negative-test 0.4-checkpoint-test 0.4-lineage-test 0.4-negative-test 0.4-compiler-matrix 0.4-sanitizers 0.4-runtime 0.5-test 0.5-evidence 0.5-check 0.5-development-gates 0.5-negative-test 0.5-manifest-negative-test 0.5-compiler-matrix 0.5-sanitizers 0.5-runtime 0.5-clean all clean
+
+test: ravel
+	./ravel >/dev/null
+
+evidence: ravel
+	@tmp=$$(mktemp); \
+	trap 'rm -f "$$tmp"' EXIT; \
+	if ./ravel > "$$tmp"; then \
+		mv "$$tmp" evidence-actual.json; \
+	else \
+		cp "$$tmp" evidence-actual.json; \
+		exit 1; \
+	fi
+
+training-test: ravel_train
+	./ravel_train >/dev/null
+
+training-evidence: ravel_train
+	@tmp=$$(mktemp); \
+	trap 'rm -f "$$tmp"' EXIT; \
+	./ravel_train > "$$tmp"; \
+	mv "$$tmp" training-evidence.json
+
+training-check: ravel_train
+	@tmp=$$(mktemp); \
+	trap 'rm -f "$$tmp"' EXIT; \
+	./ravel_train > "$$tmp"; \
+	diff -u training-evidence.json "$$tmp"
+
+unified-test: ravel_unified_bin
+	./ravel_unified_bin >/dev/null
+
+unified-evidence: ravel_unified_bin
+	@tmp=$$(mktemp); \
+	trap 'rm -f "$$tmp"' EXIT; \
+	./ravel_unified_bin > "$$tmp"; \
+	mv "$$tmp" unified-evidence.json
+
+unified-check: ravel_unified_bin
+	@tmp=$$(mktemp); \
+	trap 'rm -f "$$tmp"' EXIT; \
+	if ./ravel_unified_bin > "$$tmp" && diff -u unified-evidence.json "$$tmp"; then \
+		rm -f unified-actual.json; \
+	else \
+		cp "$$tmp" unified-actual.json; \
+		exit 1; \
+	fi
+
+0.4-evidence: ravel_0_4_bin
+	python3 tools/ravel_0_4_evidence.py generate --binary ./ravel_0_4_bin
+
+0.4-check: ravel_0_4_bin
+	python3 tools/ravel_0_4_evidence.py verify --binary ./ravel_0_4_bin --diagnostics-dir diagnostics
+	python3 tools/ravel_source_digest.py verify \
+		--spec ravel-0.4-source-manifest-spec.json \
+		--manifest ravel-0.4-source-manifest.json \
+		--assurance ravel-0.4-assurance-case.json
+
+0.4-manifest-negative-test:
+	@tmp=$$(mktemp -d); \
+	trap 'rm -rf "$$tmp"' EXIT; \
+	cp -a . "$$tmp/ravel"; \
+	cd "$$tmp/ravel"; \
+	verify='python3 tools/ravel_source_digest.py verify --spec ravel-0.4-source-manifest-spec.json --manifest ravel-0.4-source-manifest.json --assurance ravel-0.4-assurance-case.json'; \
+	$$verify >/dev/null; \
+	cp RAVEL_0_4_CONTRACT.md contract.saved; \
+	printf '\nmutation\n' >> RAVEL_0_4_CONTRACT.md; \
+	if $$verify >/dev/null 2>&1; then exit 1; fi; \
+	mv contract.saved RAVEL_0_4_CONTRACT.md; \
+	cp ravel-0.4-source-manifest.json manifest.saved; \
+	python3 -c 'import json; p="ravel-0.4-source-manifest.json"; r=json.load(open(p)); r["ordered_files"].pop(); json.dump(r,open(p,"w"))'; \
+	if $$verify >/dev/null 2>&1; then exit 1; fi; \
+	cp manifest.saved ravel-0.4-source-manifest.json; \
+	python3 -c 'import json; p="ravel-0.4-source-manifest.json"; r=json.load(open(p)); r["ordered_files"][0],r["ordered_files"][1]=r["ordered_files"][1],r["ordered_files"][0]; json.dump(r,open(p,"w"))'; \
+	if $$verify >/dev/null 2>&1; then exit 1; fi; \
+	cp manifest.saved ravel-0.4-source-manifest.json; \
+	mkdir -p ravel_0_4; \
+	printf 'unexpected\n' > ravel_0_4/unexpected.inc; \
+	if $$verify >/dev/null 2>&1; then exit 1; fi; \
+	rm -rf ravel_0_4; \
+	cp ravel-0.4-assurance-case.json assurance.saved; \
+	python3 -c 'import json; p="ravel-0.4-assurance-case.json"; r=json.load(open(p)); r["implementation"]["source_digest"]="0"*64; json.dump(r,open(p,"w"))'; \
+	if $$verify >/dev/null 2>&1; then exit 1; fi; \
+	mv assurance.saved ravel-0.4-assurance-case.json
+
+0.4-checkpoint-test: ravel_0_4_bin
+	@tmp=$$(mktemp); \
+	trap 'rm -f "$$tmp"' EXIT; \
+	./ravel_0_4_bin > "$$tmp"; \
+	python3 -c 'import json,sys; r=json.load(open(sys.argv[1])); assert all(t["checkpoint_verification"]["complete_behavior_match"] and all(t["checkpoint_verification"]["mutations"].values()) for t in r["trials"])' "$$tmp"
+
+0.4-lineage-test: ravel_0_4_bin
+	@tmp=$$(mktemp); \
+	trap 'rm -f "$$tmp"' EXIT; \
+	./ravel_0_4_bin > "$$tmp"; \
+	python3 -c 'import json,sys; r=json.load(open(sys.argv[1])); assert all(all(t["lineage_invariants"].values()) for t in r["trials"])' "$$tmp"
+
+0.4-negative-test: ravel_0_4_bin
+	@tmp=$$(mktemp); \
+	trap 'rm -f "$$tmp"' EXIT; \
+	./ravel_0_4_bin > "$$tmp"; \
+	python3 -c 'import json,sys; r=json.load(open(sys.argv[1])); assert all(v["pass"] for v in r["negative_tests"].values())' "$$tmp"
+
+0.4-compiler-matrix:
+	@set -eu; \
+	for compiler in gcc clang; do \
+		if command -v "$$compiler" >/dev/null 2>&1; then \
+			for optimization in 0 3; do \
+				binary=$$(mktemp); output=$$(mktemp); \
+				"$$compiler" -std=c11 "-O$$optimization" -Wall -Wextra -Werror -pedantic ravel_0_4.c -lm -o "$$binary"; \
+				"$$binary" > "$$output"; \
+				diff -u ravel-0.4-raw-observations.json "$$output"; \
+				rm -f "$$binary" "$$output"; \
+			done; \
+		fi; \
+	done
+
+0.4-sanitizers:
+	@set -eu; \
+	command -v "$(SAN_CC)" >/dev/null 2>&1 || { echo "sanitizer compiler unavailable: $(SAN_CC)" >&2; exit 1; }; \
+	binary=$$(mktemp); output=$$(mktemp); \
+	trap 'rm -f "$$binary" "$$output"' EXIT; \
+	$(SAN_CC) -std=c11 -O1 -g -Wall -Wextra -Werror -pedantic \
+		-fsanitize=address,undefined -fno-omit-frame-pointer \
+		ravel_0_4.c -lm -o "$$binary"; \
+	ASAN_OPTIONS=detect_leaks=1 UBSAN_OPTIONS=halt_on_error=1 "$$binary" > "$$output"; \
+	diff -u ravel-0.4-raw-observations.json "$$output"
+
+0.4-runtime: ravel_0_4_bin
+	python3 tools/ravel_0_4_evidence.py runtime --binary ./ravel_0_4_bin --runs 3
+
+0.5-test: ravel_0_5_bin
+	@tmp=$$(mktemp); \
+	trap 'rm -f "$$tmp"' EXIT; \
+	./ravel_0_5_bin --self-test > "$$tmp"; \
+	python3 -c 'import json,sys; r=json.load(open(sys.argv[1])); assert r["schema"] == "ravel-self-test-observations/0.5"; assert all(v["observed"] for v in r["fixtures"].values())' "$$tmp"
+
+0.5-evidence: ravel_0_5_bin
+	python3 tools/ravel_0_5_evidence.py generate --binary ./ravel_0_5_bin
+
+0.5-check: ravel_0_5_bin
+	python3 tools/ravel_0_5_evidence.py verify --binary ./ravel_0_5_bin --diagnostics-dir diagnostics-0.5
+	python3 tools/ravel_0_5_source_digest.py verify \
+		--spec ravel-0.5-source-manifest-spec.json \
+		--manifest ravel-0.5-source-and-execution-manifest.json \
+		--assurance ravel-0.5-assurance-case.json
+
+0.5-development-gates:
+	python3 tools/ravel_0_5_evidence.py development-gates
+
+0.5-negative-test: ravel_0_5_bin
+	$(MAKE) 0.5-test
+	python3 tools/ravel_0_5_evidence.py mutation-tests
+	python3 -c 'import json; r=json.load(open("ravel-0.5-negative-evidence.json")); assert r["all_negative_tests_pass"]; assert len(r["tests"]) == len(set(r["tests"]))'
+
+0.5-manifest-negative-test:
+	python3 tools/ravel_0_5_evidence.py manifest-negative-tests
+
+0.5-compiler-matrix:
+	@set -eu; \
+	for compiler in gcc clang; do \
+		if command -v "$$compiler" >/dev/null 2>&1; then \
+			for optimization in 0 3; do \
+				binary=$$(mktemp); \
+				trap 'rm -f "$$binary"' EXIT; \
+				"$$compiler" -std=c11 "-O$$optimization" -Wall -Wextra -Werror -pedantic ravel_0_5.c -lm -o "$$binary"; \
+				python3 tools/ravel_0_5_evidence.py verify --binary "$$binary" --diagnostics-dir diagnostics-0.5; \
+				rm -f "$$binary"; \
+				trap - EXIT; \
+			done; \
+		fi; \
+	done
+
+0.5-sanitizers:
+	@set -eu; \
+	command -v "$(SAN_CC)" >/dev/null 2>&1 || { echo "sanitizer compiler unavailable: $(SAN_CC)" >&2; exit 1; }; \
+	binary=$$(mktemp); \
+	trap 'rm -f "$$binary"' EXIT; \
+	$(SAN_CC) -std=c11 -O1 -g -Wall -Wextra -Werror -pedantic \
+		-fsanitize=address,undefined -fno-omit-frame-pointer \
+		ravel_0_5.c -lm -o "$$binary"; \
+	ASAN_OPTIONS=detect_leaks=1 UBSAN_OPTIONS=halt_on_error=1 \
+		python3 tools/ravel_0_5_evidence.py verify --binary "$$binary" --diagnostics-dir diagnostics-0.5
+
+0.5-runtime: ravel_0_5_bin
+	python3 tools/ravel_0_5_evidence.py runtime --binary ./ravel_0_5_bin --runs 3
+
+0.5-clean:
+	rm -f ravel_0_5_bin
+	rm -rf diagnostics-0.5
+
+all: test training-check unified-check 0.4-check 0.5-check
+
+ravel: ravel.c
+	$(CC) $(CFLAGS) $< -o $@
+
+ravel_train: ravel_train.c
+	$(CC) $(CFLAGS) $< $(LDLIBS) -o $@
+
+ravel_unified_bin: ravel_unified.c ravel_unified/00_core.inc ravel_unified/10_route.inc ravel_unified/20_train.inc ravel_unified/30_eval.inc
+	$(CC) $(CFLAGS) ravel_unified.c $(LDLIBS) -o $@
+
+ravel_0_4_bin: ravel_0_4.c
+	$(CC) $(CFLAGS) ravel_0_4.c $(LDLIBS) -o $@
+
+ravel_0_5_bin: ravel_0_5.c
+	$(CC) $(CFLAGS) ravel_0_5.c $(LDLIBS) -o $@
+
+clean:
+	rm -f ravel ravel_train ravel_unified_bin ravel_0_4_bin ravel_0_5_bin
+	rm -f evidence-actual.json unified-actual.json ravel-unified-checkpoint.bin ravel-0.4-checkpoint.bin
+	rm -rf diagnostics

RAVEL_0_4_CONTRACT.md

@@ -0,0 +1,68 @@
+# RAVEL 0.4 evidence-hardening contract
+
+## Intended use
+
+RAVEL 0.4 evaluates the existing bounded recursive-expert mechanism under
+deterministic synthetic drift. It is an assurance repair, not a foundation-model
+or production architecture claim.
+
+## Dataset authority
+
+Every trial has six disjoint, seed-addressed inputs:
+
+1. base training observations;
+2. base holdout observations;
+3. drift adaptation training observations;
+4. untouched drift holdout observations;
+5. original-task retention holdout observations; and
+6. planning cases.
+
+The drift holdout is never passed to expert birth selection, refinement,
+retirement, threshold selection, topology selection, replay selection, or model
+selection. The source and evaluator make those operations separate calls.
+
+## Exact routing
+
+Routing may return early only when the routed best distance is strictly lower
+than the lower bound for every excluded expert. Equality, malformed data, and
+out-of-domain observations cannot certify a shortcut. Valid uncertain
+observations fall back to complete scan. Ties choose the lower expert identity.
+
+## Canonical checkpoint
+
+The checkpoint is not a C memory image. It contains:
+
+- an eight-byte magic identifier;
+- a big-endian schema version and declared dimensions and topology limits;
+- a big-endian payload length;
+- a SHA-256 payload digest; and
+- a canonical payload using explicit integer widths and signed Q20 fixed-point
+  values for retained real-valued fields.
+
+The payload covers expert count, epoch, active and lifecycle status, keys,
+reconstruction vectors, action-conditioned prediction vectors, label and action
+counts, selected labels, usage/error statistics, retained reconstruction and
+prediction statistics, generation, lineage, compiled transition graph, and the
+complete routing lattice. Restoration rejects unsupported dimensions or
+versions, malformed fields, truncation, oversized payloads, reordered data,
+unexpected trailing bytes, invalid graph/routing identities, and digest
+mismatch.
+
+Restored behavior is compared over classification, reconstruction and
+prediction totals, transition predictions, routing certification and
+complete-oracle agreement, planning, model topology, lineage, and the complete
+reported evaluation record.
+
+## Planning measurements
+
+Planning reports path found, exact world-state target reached, goal expert
+reached, executed path length, calculable optimal path length, regret, graph
+disconnection, transition-model error, and state aliasing separately.
+Goal-expert equivalence is never named exact success.
+
+## Development disposition
+
+Each trial evaluates every preregistered hard gate. The global development
+result is `PASS` only when all eight frozen trials pass. Failures remain evidence
+and do not change formal status. Formal MNCS and MNCDS status remain `UNKNOWN`;
+promotion remains unauthorized.