From f887c6c1fbe7d6f49a665e1cc34b194306af9491 Mon Sep 17 00:00:00 2001 From: epi13 Date: Sat, 1 Aug 2026 21:06:24 -0800 Subject: [PATCH 1/7] docs: reorganize RAVEL landing page --- case-studies/ravel/README.md | 337 +++++++++++++---------------------- 1 file changed, 125 insertions(+), 212 deletions(-) diff --git a/case-studies/ravel/README.md b/case-studies/ravel/README.md index 2936950..a677e96 100644 --- a/case-studies/ravel/README.md +++ b/case-studies/ravel/README.md @@ -1,232 +1,145 @@ # RAVEL — Recursive Adaptive Vector Execution Lattice -RAVEL is a machine-native research architecture that treats AI/ML as one combined problem of routing, retrieval, compression, representation, training state, temporal memory, planning, lifecycle, and bounded computation. - -Its foundational claim is that a model, memory store, router, trainer, world model, planner, and compute scheduler should not be separate systems. A stored expert should simultaneously be a retrieval key, compressed representation, executable predictor, training shard, transition-memory node, planning destination, lineage object, and measured unit of computation. - -Human readability is relocated into contracts, evaluator authority, evidence, provenance, and rollback. The 0.3 split C translation unit is maintained source: no reproducible higher-level generator was included in the repository or reviewed pull-request history. - -## RAVEL 0.1 — exact conditional inference - -The first capsule generates 256 quantized experts and retrieves 24 candidates per familiar query. A strict lower-bound certificate permits early return only when every excluded expert is provably unable to win. Otherwise execution becomes the complete oracle. - -| Workload | Queries | Mismatches | Certified rate | Mean experts | Reduction | -|---|---:|---:|---:|---:|---:| -| Familiar | 100,000 | 0 | 100.000% | 24.000 | 90.625% | -| Uniform control | 25,000 | 0 | 2.236% | 250.812 | 2.026% | - -## RAVEL-T 0.2 — recursive training - -The current experts build the exact router; routed assignments update the experts; unresolved error ranks overloaded shards; bounded splits compile children; child lineage rebuilds the next router. - -| Implementation | Holdout accuracy | Mean experts | Training evaluations | -|---|---:|---:|---:| -| RAVEL-T recursive 8→64 | 100.000% | 8.000 | 4,144,248 | -| Fixed eight-expert | 22.461% | 8.000 | 3,538,944 | -| Flat 64-expert | 100.000% | 64.000 | 87,031,808 | - -## RAVEL-U 0.3 — unified architecture - -RAVEL-U closes the component gap. One expert population now owns: - -- retrieval and exact conditional compute; -- compressed state representation and reconstruction; -- label prediction; -- action-conditioned next-observation prediction; -- temporal-memory graph compilation; -- bounded planning over the learned graph; -- error-driven expert birth; -- replay-backed continual adaptation; -- low-utility child retirement; and -- checkpoint identity and behavioral rollback verification. - -The synthetic world contains 64 states, four actions, eight labels, and eight-dimensional observations. Semantic drift changes both observations and labels for 16 states. The frozen model is evaluated before adaptation, then RAVEL proposes 24 drift experts, retires eight low-utility duplicates, rebuilds the router and transition graph, and re-evaluates drift, retention, planning, and checkpoint behavior. - -### Unified development result - -| Measure | Result | -|---|---:| -| Base holdout accuracy | 96.826% | -| Static model on semantic drift | 71.899% | -| Adapted model on semantic drift | 100.000% | -| Original-task retention after adaptation | 96.704% | -| Adapted transition accuracy | 99.292% | -| Adapted planning target success | 505 / 512 | -| Routed-versus-complete mismatches | 0 | -| Mean routed experts | 8.000 | -| Adaptation births / retirements | 24 / 8 | -| Checkpoint identity and evaluation match | PASS | - -The expert is now simultaneously a key, representation, decoder, classifier, world-model fragment, transition node, replay shard, planning node, lineage object, and compute unit. See `ARCHITECTURE_GAPS.md` for what was missing and why raw modality adapters, use policy, protected evaluation, external effects, and promotion authority intentionally remain outside the recursive surface. - -The historical `100.000%` adapted drift value above was measured on the same -`adapt_set` used for adaptation. It is an adaptation-training observation, not -an untouched drift-holdout result. Likewise, the historical planning -`exact_goals` field measured goal-expert equivalence rather than exact -world-state equality. RAVEL 0.4 preserves these facts instead of relabeling the -0.3 evidence. - -## RAVEL 0.4 — evidence hardening - -RAVEL 0.4 repairs assurance rather than expanding the architecture. It adds: - -- disjoint base training, base holdout, drift adaptation training, untouched - drift holdout, original-task retention holdout, and planning inputs; -- eight frozen seeds covering separated, overlapping, noisy, label-drift, - observation-drift, transition-drift, combined, and ambiguous regimes; -- canonical big-endian Q20 checkpoints with a versioned header and SHA-256 - payload identity instead of raw C memory images; -- complete restored classification, reconstruction, prediction, transition, - routing, planning, topology, lineage, and reported-metric comparison; -- deliberate field, payload, truncation, append, schema, and substitution - checkpoint mutations; -- exact-state planning measurements distinct from goal-expert equivalence; -- reconstruction and next-observation prediction gates; -- five bounded baselines, five ablations, negative/adversarial tests, aggregate - variance, and preserved failures; and -- an ordered, script-generated source manifest and assurance digest. - -The frozen 0.4 experiment records development `FAIL`; no seeds, regimes, or -gates were removed to obtain a favorable result. See -`RAVEL_0_4_RESULTS.md` for generated per-trial failures and aggregates, and -`ravel-0.4-assurance-case.json` for the bounded assurance disposition. - -## RAVEL 0.5 — adaptive-mechanism correction - -RAVEL 0.5 keeps the 0.4 evidence package immutable and corrects the mechanism -and assurance split. The C harness now emits raw integer observations and -integrity facts only. A separate Python evaluator verifies the frozen trial and -partition matrix, derives every metric and hard gate, and rejects executable -verdicts, malformed records, contradictions, and mutations. - -Mechanism changes include deterministic stratified replay, anchored base -experts, optional objective-tested births and retirements, eight normalized -residual channels, support-bearing top-two transitions, unknown unsupported -actions, retirement safety checks, and alias-aware belief-set planning. -Comparisons add matched work, expert count, and capacity, while retaining the -0.4 baselines and ablations. - -The one-shot 0.5 final validation used 32 fresh trials: four seeds for each of -the eight frozen regime families. Execution integrity is `PASS`; 24 trials -passed and eight failed, so the frozen all-trials development result is -`FAIL`. All separated, overlap, noise, and observation-drift trials passed. -Failures remained in label gain (three trials), transition prediction retention -(one), combined exact planning (one), and ambiguous belief/planning or -efficiency (three). These failures were not used to change the mechanism, -seeds, regimes, or gates. - -The candidate improved mean drift-holdout accuracy over the matched-compute -fixed-topology comparison while using fewer mean training evaluations, but the -complete paired Pareto results are mixed. No superiority claim is made. See -`RAVEL_0_5_RESULTS.md`, `RAVEL_0_5_POSTMORTEM.md`, and -`ravel-0.5-assurance-case.json`. - -## RAVEL 0.6 — preregistered future development - -RAVEL 0.6 is a clean new epoch preregistered before implementation. It binds -the immutable 0.5 candidate and evidence as a failed development baseline and -uses the published label-gain, prediction-retention, combined-planning, -ambiguous-planning/efficiency, mixed-Pareto, and assurance findings only as -permitted cross-epoch design input. - -The narrow hypothesis concerns retention-constrained adaptation for label and -combined observation/label drift. The planned policy combines stratified -replay protection, objective-tested updates, and transition-support -preservation. Development, selection, retention, transition-retention, -planning, and future final partitions have distinct identities. Development -and selection seeds are distinct from every 0.5 final seed. Future final seed -material is intentionally absent and may be obtained only after candidate -freeze, preferably from an external custodian. - -No 0.6 mechanism has been implemented, selected, frozen, or evaluated. -Development and final results, protected custody, independent evaluation, and -formal MNCS/MNCDS status are all `UNKNOWN`; promotion is unauthorized. See -`RAVEL_0_6_SCOPE.md`, `RAVEL_0_6_PREREGISTRATION.md`, and -`ravel-0.6-preregistration.json`. - -## Run +RAVEL is a machine-native research architecture that treats routing, retrieval, +representation, training state, temporal memory, planning, lifecycle, and bounded +computation as one connected mechanism. + +This directory contains several historical and active research epochs. The files +are intentionally evidence-heavy, and some frozen artifacts must retain their +existing paths and identities. The navigation layer below separates the project +by purpose without rewriting or relocating those historical records. + +> **Current status:** RAVEL 0.4 and 0.5 retain development `FAIL` results. RAVEL +> 0.6 is preregistered and has a reproducible candidate-001 derivation, but it has +> not been selected, finally evaluated, independently attested, or authorized for +> promotion. Formal MNCS and MNCDS status remain `UNKNOWN`. + +## Start here + +| Goal | Entry point | +|---|---| +| Understand the project at a glance | [Version history](docs/VERSION_HISTORY.md) | +| Find source, contracts, evidence, and plans | [Project map](docs/PROJECT_MAP.md) | +| Understand what each evidence file proves | [Evidence guide](docs/EVIDENCE_GUIDE.md) | +| Browse the RAVEL documentation set | [Documentation hub](docs/README.md) | +| Understand evaluator and generation scripts | [Tooling guide](tools/README.md) | +| Review the architectural idea and exclusions | [Architecture gaps](ARCHITECTURE_GAPS.md) | +| Continue bounded 0.6 development | [RAVEL 0.6 next steps](RAVEL_0_6_NEXT_STEPS.md) | + +## Project shape + +```text +case-studies/ravel/ +├── README.md # landing page +├── docs/ # human navigation and explanatory guides +├── tools/ # evaluators, evidence builders, and digest tools +├── ravel_unified/ # maintained 0.3 split implementation units +├── ravel*.c # versioned mechanism implementations +├── *_CONTRACT.md # readable behavioral authority +├── RAVEL_* # results, postmortems, scopes, and plans +├── ravel-*.json # protocols, observations, manifests, and assurance +└── Makefile # local build, verification, and evidence targets +``` + +The top-level RAVEL directory remains partly flat on purpose. Versioned source, +preregistrations, observations, manifests, and assurance records are linked by +exact filenames and digests. Moving them merely for appearance could invalidate +historical identity or make prior evidence harder to reproduce. New explanatory +documentation belongs under `docs/`; executable support tooling belongs under +`tools/`. + +## Epoch status + +| Epoch | Primary purpose | Preserved status | +|---|---|---| +| RAVEL 0.1 | Exact conditional inference | Favorable bounded development observation | +| RAVEL-T 0.2 | Recursive training and expert birth | Favorable bounded development observation | +| RAVEL-U 0.3 | Unified expert architecture | Favorable historical observations with documented evaluation caveats | +| RAVEL 0.4 | Evidence and checkpoint hardening | Development `FAIL` — 0 of 8 frozen trials passed all gates | +| RAVEL 0.5 | Mechanism correction and evaluator separation | Development `FAIL` — 24 of 32 trials passed; all-trials gate failed | +| RAVEL 0.6 | Retention-constrained adaptation epoch | Preregistered; candidate-001 derivation prepared; selection and final evaluation `UNKNOWN` | + +Detailed results, limitations, and links are collected in +[docs/VERSION_HISTORY.md](docs/VERSION_HISTORY.md). + +## Common verification commands + +From the repository root: ```bash -make test -make training-check -make unified-check -make 0.4-check -make 0.5-check -make ravel-0.6-preregistration-check +make ravel-test +make ravel-training-check +make ravel-unified-check +make ravel-0.4-check +make ravel-0.5-check ``` -To rewrite repository-visible development evidence: +From this directory: ```bash -make evidence -make training-evidence -make unified-evidence -make 0.4-evidence -make 0.5-evidence +make all +make 0.4-compiler-matrix +make 0.4-sanitizers +make 0.5-negative-test +make 0.5-manifest-negative-test +make 0.5-compiler-matrix +make 0.5-sanitizers ``` -Requirements: a C11 compiler, the C math library, and Make. - -## Files - -- `ravel.c`, `CONTRACT.md`, `evidence.json` — exact conditional inference; -- `ravel_train.c`, `TRAINING_CONTRACT.md`, `training-*.json` — recursive training; -- `ravel_unified.c` and `ravel_unified/*.inc` — maintained 0.3 split C source; -- `ARCHITECTURE_GAPS.md` — architectural audit and intentional external boundary; -- `UNIFIED_CONTRACT.md` — unified readable authority and gates; -- `unified-preregistration.json` — frozen protocol; -- `unified-evidence.json` — deterministic observations; -- `unified-threat-model.json` — threats and residual UNKNOWNs; and -- `unified-assurance-case.json` — historical bounded non-promotion record; -- `ravel_0_4.c` and `RAVEL_0_4_CONTRACT.md` — hardened maintained execution and - readable authority; -- `ravel-0.4-preregistration.json` — frozen seeds, regimes, partitions, and gates; -- `ravel-0.4-raw-observations.json`, `ravel-0.4-trial-evidence.json`, and - `ravel-0.4-negative-evidence.json` — executable raw and derived evidence; -- `ravel-0.4-source-manifest.json` — ordered implementation identity; and -- `ravel-0.4-assurance-case.json` — historical 0.4 non-promotion record; -- `ravel_0_5.c`, `RAVEL_0_5_CONTRACT.md`, and - `ravel-0.5-preregistration.json` — maintained 0.5 mechanism and frozen - authority; -- `tools/ravel_0_5_evaluator.py` and `tools/ravel_0_5_evidence.py` — - independent derivation and deterministic evidence tooling; -- `ravel-0.5-raw-observations.json`, `ravel-0.5-trial-evidence.json`, and - `ravel-0.5-negative-evidence.json` — raw and independently derived 0.5 - records; and -- `ravel-0.5-source-and-execution-manifest.json` and - `ravel-0.5-assurance-case.json` — bound build/source identity and current - bounded non-promotion record; and -- `ravel-0.5-runtime-observations.json` — host-specific, non-normative timing - observations; canonical comparisons use deterministic operation counts; and -- `RAVEL_0_6_SCOPE.md`, `RAVEL_0_6_PREREGISTRATION.md`, - `ravel-0.6-preregistration.json`, `ravel-0.6-threat-model.json`, - `ravel-0.6-development-record.json`, and `ravel-0.6-limitations.md` — a new - preregistered epoch with no implementation or evaluation claim. +Commands ending in `-check`, `-test`, `-compiler-matrix`, or `-sanitizers` are +verification-oriented. Commands ending in `-evidence` or `-runtime` can rewrite +repository-visible development records; review [tools/README.md](tools/README.md) +before using them. -## MNCS boundary +Requirements vary by epoch but generally include a C11 compiler, Python 3, the C +math library, and Make. -- **Human control plane:** intended use, event contract, external authority, limits, gates, and exclusions. -- **Machine execution plane:** expert keys, decoders, classifiers, next-state programs, router, transition graph, topology, replay assignments, and lineage. -- **Evidence plane:** exact-oracle agreement, accuracy, reconstruction, prediction, transition, planning, lifecycle, checkpoint, checksums, and limitations. -- **Development-control plane:** fixed seeds, partitions, birth and retirement budgets, immutable thresholds, and non-promotion fields. -- **Operational-control plane:** complete-scan fallback, checkpoint restoration, model identity, and replacement of maintained execution source. +## Reading order for each epoch -Historical RAVEL 0.1–0.3 studies recorded favorable development observations. -RAVEL 0.4 records development `FAIL` with zero of eight trials passing. RAVEL -0.5 records development `FAIL` with 24 of 32 trials passing. Formal MNCS and -MNCDS status remain `UNKNOWN`. RAVEL 0.6 is preregistered future work whose -implementation and evaluation remain `UNKNOWN`. Promotion is unauthorized -pending independent protected real-data evaluation, adversarial -continual-learning studies, learned modality adapters, cross-host reproduction, -accelerator and distributed evidence, and operational release controls. +For version 0.4 or later, use this order: + +1. scope or preregistration; +2. readable contract; +3. maintained or generated mechanism source; +4. raw observations; +5. evaluator-derived trial and negative evidence; +6. source/execution manifest; +7. assurance case; +8. generated results and postmortem; +9. next-epoch development plan. + +This order keeps protocol, implementation, observations, interpretation, and +claim authority separate. + +## MNCS boundary + +- **Human control plane:** intended use, event contract, external authority, + limits, gates, and exclusions. +- **Machine execution plane:** expert keys, decoders, classifiers, next-state + programs, router, transition graph, topology, replay assignments, and lineage. +- **Evidence plane:** oracle agreement, accuracy, reconstruction, prediction, + transition, planning, lifecycle, checkpoint, checksums, and limitations. +- **Development-control plane:** fixed seeds, partitions, candidate limits, + immutable thresholds, and non-promotion fields. +- **Operational-control plane:** complete-scan fallback, checkpoint restoration, + model identity, source replacement, and rollback behavior. ## Claim boundary RAVEL is a bounded deterministic research study with both favorable and -unfavorable results. It does not establish general intelligence, -foundation-model performance, language or multimodal generation, causal -reasoning, real-data generalization, production safety, or formal conformance. +unfavorable results. It does not establish general intelligence, foundation-model +performance, language or multimodal generation, causal reasoning, real-data +generalization, production safety, independent evaluation, protected custody, or +formal conformance. + +Historical RAVEL 0.1–0.3 studies recorded favorable development observations. +RAVEL 0.4 and 0.5 preserve failed frozen development outcomes. RAVEL 0.6 remains +a development epoch. Promotion is unauthorized pending appropriate external, +protected, and independently evaluated evidence. ## Origin -The name, architecture, algorithms, and initial implementations were created by **GPT-5.6 Thinking** in response to Alexander Collamore's challenge to design an AI/ML foundation that fully embraces Machine-Native Complexity. Alexander Collamore is the repository steward. +The name, architecture, algorithms, and initial implementations were created by +**GPT-5.6 Thinking** in response to Alexander Collamore's challenge to design an +AI/ML foundation that fully embraces Machine-Native Complexity. Alexander +Collamore is the repository steward. From 23607285a973778aa80fd8508189ca002a4d4d1b Mon Sep 17 00:00:00 2001 From: epi13 Date: Sat, 1 Aug 2026 21:06:32 -0800 Subject: [PATCH 2/7] docs: add RAVEL documentation hub --- case-studies/ravel/docs/README.md | 38 +++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 case-studies/ravel/docs/README.md diff --git a/case-studies/ravel/docs/README.md b/case-studies/ravel/docs/README.md new file mode 100644 index 0000000..31953f2 --- /dev/null +++ b/case-studies/ravel/docs/README.md @@ -0,0 +1,38 @@ +# RAVEL documentation hub + +This directory is the human-navigation layer for the RAVEL case study. It does +not replace versioned contracts, preregistrations, raw observations, manifests, +or assurance records in the parent directory. + +## Guides + +- [Version history](VERSION_HISTORY.md) — what changed in each epoch, preserved + results, and current development status. +- [Project map](PROJECT_MAP.md) — where to find implementations, contracts, + evidence, manifests, plans, and tooling. +- [Evidence guide](EVIDENCE_GUIDE.md) — how the evidence layers relate and what + conclusions they do and do not support. + +## Authoritative material remains versioned + +Use the guides above to locate the authoritative files, then read those files +directly. In particular: + +- Markdown contracts define readable behavioral authority; +- preregistration JSON defines frozen protocol and gates; +- C source defines the maintained mechanism for its epoch; +- raw observation JSON records executable output; +- evaluator-derived evidence records interpretation of those observations; +- source and execution manifests bind identity; +- assurance cases state the bounded disposition and unresolved limitations. + +Documentation may summarize those records but must not silently upgrade their +claims. + +## Placement rule + +Add explanatory, cross-version, or navigational material here. Keep executable +support scripts under `../tools/`. Keep version-bound contracts, source, +preregistrations, observations, manifests, and assurance records in their +existing versioned locations unless a new epoch explicitly defines a different +layout and identity scheme. From 5b495fd1e0720b5644e540a16692273d1af86a92 Mon Sep 17 00:00:00 2001 From: epi13 Date: Sat, 1 Aug 2026 21:06:52 -0800 Subject: [PATCH 3/7] docs: add RAVEL project map --- case-studies/ravel/docs/PROJECT_MAP.md | 141 +++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 case-studies/ravel/docs/PROJECT_MAP.md diff --git a/case-studies/ravel/docs/PROJECT_MAP.md b/case-studies/ravel/docs/PROJECT_MAP.md new file mode 100644 index 0000000..6185ce5 --- /dev/null +++ b/case-studies/ravel/docs/PROJECT_MAP.md @@ -0,0 +1,141 @@ +# RAVEL project map + +RAVEL is organized by evidence role and research epoch. The parent directory is +partly flat because historical evidence binds exact paths, filenames, ordering, +and digests. This guide provides logical grouping without relocating frozen +artifacts. + +## 1. Landing and cross-version orientation + +| File | Purpose | +|---|---| +| `README.md` | Main entry point, status summary, commands, and claim boundary | +| `docs/README.md` | Documentation hub | +| `docs/VERSION_HISTORY.md` | Cross-version development history | +| `docs/EVIDENCE_GUIDE.md` | Evidence-layer and claim interpretation | +| `ARCHITECTURE_GAPS.md` | Why 0.3 unified previously separate mechanism roles and what remained external | + +## 2. Mechanism implementations + +| Epoch | Implementation | +|---|---| +| 0.1 | `ravel.c` | +| 0.2 | `ravel_train.c` | +| 0.3 | `ravel_unified.c` plus `ravel_unified/*.inc` | +| 0.4 | `ravel_0_4.c` | +| 0.5 | `ravel_0_5.c` | +| 0.6 | Reproducible development source derived by `tools/ravel_0_6_seed_candidate.py`; no selected or final implementation is claimed | + +Generated binaries such as `ravel`, `ravel_train`, `ravel_unified_bin`, +`ravel_0_4_bin`, and `ravel_0_5_bin` are build outputs and are removed by the +local clean targets. + +## 3. Readable behavioral authority + +| Epoch | Contract or authority | +|---|---| +| 0.1 | `CONTRACT.md` | +| 0.2 | `TRAINING_CONTRACT.md` | +| 0.3 | `UNIFIED_CONTRACT.md` | +| 0.4 | `RAVEL_0_4_CONTRACT.md` | +| 0.5 | `RAVEL_0_5_CONTRACT.md` | +| 0.6 | `RAVEL_0_6_SCOPE.md` and `RAVEL_0_6_PREREGISTRATION.md` | + +Contracts explain expected behavior, limits, gates, and exclusions. They are not +substitutes for raw observations or source identity. + +## 4. Protocol and preregistration + +Common protocol files include: + +- `unified-preregistration.json` for the historical unified study; +- `ravel-0.4-preregistration.json` for the frozen 0.4 matrix; +- `ravel-0.5-preregistration.json` for the frozen 0.5 matrix; and +- `ravel-0.6-preregistration.json` for the new preregistered epoch. + +The 0.6 support set also includes: + +- `ravel-0.6-threat-model.json`; +- `ravel-0.6-development-record.json`; +- `ravel-0.6-limitations.md`; and +- `RAVEL_0_6_NEXT_STEPS.md`. + +Preregistration files define what may be changed, which partitions and seeds are +permitted, how candidates are identified, and how results are derived. + +## 5. Raw observations and derived evidence + +### Historical studies + +- `evidence.json` and `evidence-actual.json` — 0.1 expected and local actual + output. +- `training-*.json` — 0.2 protocol and evidence records. +- `unified-evidence.json` — deterministic 0.3 observations. +- `unified-threat-model.json` and `unified-assurance-case.json` — historical + threats and bounded disposition. + +### RAVEL 0.4 + +- `ravel-0.4-raw-observations.json` — direct executable output; +- `ravel-0.4-trial-evidence.json` — derived per-trial evidence; +- `ravel-0.4-negative-evidence.json` — mutation and adversarial evidence; +- `RAVEL_0_4_RESULTS.md` — generated human-readable results; and +- `ravel-0.4-assurance-case.json` — bounded non-promotion disposition. + +### RAVEL 0.5 + +- `ravel-0.5-raw-observations.json` — direct executable output; +- `ravel-0.5-trial-evidence.json` — evaluator-derived trial evidence; +- `ravel-0.5-negative-evidence.json` — evaluator and mutation evidence; +- `ravel-0.5-runtime-observations.json` — host-specific, non-normative timing; +- `RAVEL_0_5_RESULTS.md` — generated human-readable results; +- `RAVEL_0_5_POSTMORTEM.md` — retained failure analysis; and +- `ravel-0.5-assurance-case.json` — bounded non-promotion disposition. + +Read [EVIDENCE_GUIDE.md](EVIDENCE_GUIDE.md) before comparing these layers. + +## 6. Source and execution identity + +| Epoch | Identity records | +|---|---| +| 0.4 | `ravel-0.4-source-manifest-spec.json` and `ravel-0.4-source-manifest.json` | +| 0.5 | `ravel-0.5-source-manifest-spec.json` and `ravel-0.5-source-and-execution-manifest.json` | + +Digest tools under `tools/` validate ordered source identity and assurance-case +bindings. These records are why appearance-only file moves can be semantically +material. + +## 7. Evaluators and support tooling + +See [`../tools/README.md`](../tools/README.md) for script-level detail. + +The main categories are: + +- evidence generation and verification; +- independent metric and gate derivation; +- source and execution digest verification; +- runtime observation capture; +- mutation and negative testing; and +- bounded 0.6 candidate source derivation. + +## 8. Build and verification entry points + +The local `Makefile` exposes version-specific targets. The repository root +`Makefile` forwards the most important checks under names such as: + +- `ravel-test`; +- `ravel-training-check`; +- `ravel-unified-check`; +- `ravel-0.4-check`; and +- `ravel-0.5-check`. + +Use verification targets before any target that rewrites evidence. + +## 9. Where new work belongs + +- Cross-version explanation or navigation: `docs/`. +- Evaluator, digest, mutation, or derivation script: `tools/`. +- New epoch source, contract, preregistration, and evidence: use a clearly + versioned identity and document the complete lifecycle before adding files. +- Historical frozen artifacts: do not rename, regroup, or rewrite merely for + visual consistency. From 66142e09d2d402ca0ca7c88a81d47ee2fe188f3f Mon Sep 17 00:00:00 2001 From: epi13 Date: Sat, 1 Aug 2026 21:07:15 -0800 Subject: [PATCH 4/7] docs: explain RAVEL evidence layers --- case-studies/ravel/docs/EVIDENCE_GUIDE.md | 145 ++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 case-studies/ravel/docs/EVIDENCE_GUIDE.md diff --git a/case-studies/ravel/docs/EVIDENCE_GUIDE.md b/case-studies/ravel/docs/EVIDENCE_GUIDE.md new file mode 100644 index 0000000..3a5fbaf --- /dev/null +++ b/case-studies/ravel/docs/EVIDENCE_GUIDE.md @@ -0,0 +1,145 @@ +# RAVEL evidence guide + +RAVEL separates protocol, implementation, observations, interpretation, identity, +and authority. A file that reports a passing check does not automatically prove +that the mechanism passed its frozen study or that the study has independent or +protected evidence. + +## Evidence layers + +### 1. Scope and preregistration + +Examples: `RAVEL_0_6_SCOPE.md`, `RAVEL_0_6_PREREGISTRATION.md`, and +`ravel-0.6-preregistration.json`. + +These files define the question, candidate limits, partitions, seeds, gates, +change rules, and claim boundaries before evaluation. They establish the +protocol, not the outcome. + +### 2. Readable contract + +Examples: `RAVEL_0_4_CONTRACT.md` and `RAVEL_0_5_CONTRACT.md`. + +The contract explains required behavior and limits in human-readable form. It is +an authority surface for review, but it does not prove the source implements the +contract. + +### 3. Mechanism source + +Examples: `ravel_0_4.c` and `ravel_0_5.c`. + +The maintained source defines the executable mechanism. For a generated 0.6 +candidate, the generator, frozen input identity, transformation rules, and output +identity are all part of the implementation story. + +### 4. Raw observations + +Examples: `ravel-0.4-raw-observations.json` and +`ravel-0.5-raw-observations.json`. + +These records should contain facts emitted by the executable, such as counts, +checksums, predictions, topology, resource measurements, and integrity facts. +They should not silently declare their own authoritative verdict when an +external evaluator is responsible for deriving it. + +### 5. Evaluator-derived evidence + +Examples: `ravel-0.5-trial-evidence.json` and +`ravel-0.5-negative-evidence.json`. + +The evaluator checks the frozen matrix, validates record structure, derives +metrics, applies hard gates, rejects contradictions, and preserves failures. The +evaluator can establish whether the supplied observations satisfy the declared +protocol; it cannot establish protected custody or organizational independence +merely because it is a separate program. + +### 6. Source and execution identity + +Examples: `ravel-0.4-source-manifest.json` and +`ravel-0.5-source-and-execution-manifest.json`. + +These records bind ordered files, digests, compiler or execution details, and +other identity facts. They answer which implementation and execution surface the +evidence refers to. They are why renaming or moving frozen files may be a +material change rather than harmless cleanup. + +### 7. Assurance case + +Examples: `ravel-0.4-assurance-case.json` and +`ravel-0.5-assurance-case.json`. + +The assurance case combines the available facts into a bounded disposition. It +should retain limitations, `UNKNOWN` conditions, failed gates, and explicit +non-promotion fields. + +### 8. Human-readable results and postmortems + +Examples: `RAVEL_0_4_RESULTS.md`, `RAVEL_0_5_RESULTS.md`, and +`RAVEL_0_5_POSTMORTEM.md`. + +These files explain the evidence to readers. They are useful summaries, but the +underlying JSON and source identities remain the auditable basis. + +### 9. Runtime observations + +Example: `ravel-0.5-runtime-observations.json`. + +Wall-clock timing is host-specific and non-normative. Deterministic expert, +operation, or evaluation counts are the canonical work measures unless a +separate protocol explicitly defines cross-host performance evidence. + +## Distinct result questions + +RAVEL reports several different questions that must not be collapsed: + +| Question | Typical value | +|---|---| +| Did the executable run and produce structurally valid observations? | execution integrity | +| Did a trial satisfy every frozen mechanism gate? | per-trial result | +| Did every required trial satisfy the aggregate rule? | development result | +| Is the source and execution identity complete and verified? | identity assurance | +| Was evaluation protected from the developer and independently operated? | custody and independence | +| Does the package satisfy formal MNCS or MNCDS requirements? | formal status | +| Is release or promotion authorized? | governance disposition | + +A `PASS` in one row does not imply `PASS` in another. + +## Preserved RAVEL outcomes + +- RAVEL 0.4: execution produced evidence, but zero of eight frozen trials passed + all gates; development result `FAIL`. +- RAVEL 0.5: execution integrity `PASS`; 24 of 32 trials passed; the all-trials + development result remains `FAIL`. +- RAVEL 0.6: preregistered development and candidate preparation exist, but + selection, future-final evaluation, protected custody, independent operation, + formal conformance, and promotion remain `UNKNOWN` or unauthorized. + +## What repository-local evidence cannot manufacture + +Repository-local source, hashes, signatures, containers, test runners, and +separate evaluator programs cannot by themselves establish: + +- protection from a user with root or repository administration access; +- future-final seed secrecy from the developer; +- organizational independence; +- independent custody or witness authority; +- uncontaminated real-world data; +- production safety or operational readiness; or +- governance approval. + +Those claims require external facts and actors, not stronger wording around +local files. + +## Review checklist + +Before accepting a RAVEL result or modifying the directory, verify: + +1. the exact epoch and candidate identity; +2. the applicable preregistration and contract; +3. whether the source is maintained or generated; +4. whether raw observations are unchanged and complete; +5. which evaluator derived the result; +6. whether negative and mutation evidence is retained; +7. whether manifests bind every required file and execution fact; +8. whether failures and `UNKNOWN` conditions remain visible; and +9. whether the proposed change affects a frozen identity or claim boundary. From 569e5e2b3b715353332911c14e13dc9311ba3ac9 Mon Sep 17 00:00:00 2001 From: epi13 Date: Sat, 1 Aug 2026 21:07:39 -0800 Subject: [PATCH 5/7] docs: add RAVEL version history --- case-studies/ravel/docs/VERSION_HISTORY.md | 173 +++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 case-studies/ravel/docs/VERSION_HISTORY.md diff --git a/case-studies/ravel/docs/VERSION_HISTORY.md b/case-studies/ravel/docs/VERSION_HISTORY.md new file mode 100644 index 0000000..deea0e2 --- /dev/null +++ b/case-studies/ravel/docs/VERSION_HISTORY.md @@ -0,0 +1,173 @@ +# RAVEL version history + +This document gives a concise reading path across the RAVEL epochs. It preserves +the published outcomes and points to the version-bound files that carry the +actual contracts, observations, and dispositions. + +## RAVEL 0.1 — exact conditional inference + +**Question:** Can a quantized expert router return early only when excluded +experts are provably unable to win, while falling back to the complete oracle +otherwise? + +**Primary files:** `ravel.c`, `CONTRACT.md`, and `evidence.json`. + +The study generated 256 experts and retrieved 24 candidates per familiar query. +Historical development observations reported zero mismatches, complete +certification on the familiar workload, and a mean of 24 evaluated experts. +Uniform control queries frequently required fallback toward the complete scan. + +**Status:** favorable bounded development observation; not formal conformance or +production evidence. + +## RAVEL-T 0.2 — recursive training + +**Question:** Can routed assignments, unresolved error, bounded splits, and child +lineage recursively build a more capable expert population? + +**Primary files:** `ravel_train.c`, `TRAINING_CONTRACT.md`, and the +`training-*.json` records. + +The recursive 8-to-64 study historically reached the same reported holdout +accuracy as the flat 64-expert comparison while using substantially fewer +training evaluations. The fixed eight-expert comparison retained lower reported +accuracy. + +**Status:** favorable bounded development observation; not a general training or +continual-learning claim. + +## RAVEL-U 0.3 — unified architecture + +**Question:** Can one expert population simultaneously own retrieval, +representation, classification, action-conditioned prediction, transition +memory, bounded planning, adaptation, retirement, lineage, and checkpoint +identity? + +**Primary files:** `ravel_unified.c`, `ravel_unified/*.inc`, +`UNIFIED_CONTRACT.md`, `unified-preregistration.json`, +`unified-evidence.json`, `unified-threat-model.json`, and +`unified-assurance-case.json`. + +The synthetic world contained 64 states, four actions, eight labels, and +8-dimensional observations. Historical development output reported strong base +accuracy, complete adapted-set drift accuracy, high transition accuracy, bounded +planning success, exact routed-versus-complete agreement, and checkpoint +restoration agreement. + +Two caveats are preserved: + +- the historical adapted drift value was measured on the same `adapt_set` used + for adaptation rather than an untouched drift holdout; and +- the historical `exact_goals` field measured goal-expert equivalence rather + than exact world-state equality. + +**Status:** favorable historical observations with known evaluation limitations. + +## RAVEL 0.4 — evidence hardening + +**Question:** What happens when partitions, checkpoint encoding, negative tests, +planning measurements, baselines, ablations, and source identity are hardened +without removing unfavorable cases? + +**Primary files:** + +- `ravel_0_4.c`; +- `RAVEL_0_4_CONTRACT.md`; +- `ravel-0.4-preregistration.json`; +- `ravel-0.4-raw-observations.json`; +- `ravel-0.4-trial-evidence.json`; +- `ravel-0.4-negative-evidence.json`; +- `ravel-0.4-source-manifest.json`; +- `ravel-0.4-assurance-case.json`; and +- `RAVEL_0_4_RESULTS.md`. + +RAVEL 0.4 introduced disjoint training, adaptation, holdout, retention, and +planning partitions; canonical checkpoint encoding; complete restored-behavior +comparison; mutation fixtures; exact-state planning; additional gates; +comparison systems; and ordered source identity. + +All eight frozen trials failed at least one required gate. No seeds, regimes, or +gates were removed to improve the result. + +**Status:** development `FAIL` — 0 of 8 trials passed all gates. + +## RAVEL 0.5 — mechanism correction and evaluator separation + +**Question:** Can mechanism changes and an independently written evaluator close +the most important 0.4 defects without weakening the frozen evidence boundary? + +**Primary files:** + +- `ravel_0_5.c`; +- `RAVEL_0_5_CONTRACT.md`; +- `ravel-0.5-preregistration.json`; +- `tools/ravel_0_5_evaluator.py`; +- `tools/ravel_0_5_evidence.py`; +- `ravel-0.5-raw-observations.json`; +- `ravel-0.5-trial-evidence.json`; +- `ravel-0.5-negative-evidence.json`; +- `ravel-0.5-source-and-execution-manifest.json`; +- `ravel-0.5-assurance-case.json`; +- `RAVEL_0_5_RESULTS.md`; and +- `RAVEL_0_5_POSTMORTEM.md`. + +Mechanism changes included stratified replay, anchored base experts, +objective-tested lifecycle changes, normalized residual channels, +support-bearing top-two transitions, explicit unknown actions, retirement safety, +and belief-set planning. The C executable emitted raw observations while the +Python evaluator derived metrics and gates. + +The frozen 32-trial validation produced execution integrity `PASS`; 24 trials +passed and eight failed. Failures remained in label gain, transition prediction +retention, combined exact planning, and ambiguous belief/planning or efficiency. +The all-trials requirement therefore failed. + +The candidate improved some paired means relative to matched comparisons, but +the Pareto results were mixed and no superiority claim was made. + +**Status:** development `FAIL` — 24 of 32 trials passed; aggregate all-trials gate +failed. + +## RAVEL 0.6 — preregistered retention-constrained development + +**Question:** Can retention-constrained adaptation improve label and combined +drift while preserving original-task and transition support under an explicitly +separated development and selection lifecycle? + +**Primary files:** + +- `RAVEL_0_6_SCOPE.md`; +- `RAVEL_0_6_PREREGISTRATION.md`; +- `ravel-0.6-preregistration.json`; +- `ravel-0.6-threat-model.json`; +- `ravel-0.6-development-record.json`; +- `ravel-0.6-limitations.md`; +- `tools/ravel_0_6_seed_candidate.py`; and +- `RAVEL_0_6_NEXT_STEPS.md`. + +The epoch was preregistered before implementation. Development, selection, +retention, transition-retention, planning, and future-final partitions have +distinct identities. Future-final seed material is intentionally absent. + +Candidate-001 can now be derived reproducibly from the exact frozen 0.5 source. +The derivation corrects two bounded issues: + +1. planning traverses both supported transition targets rather than only slot + zero; and +2. a newly born adaptation expert receives support only from its spawning event + rather than inheriting unrelated empirical support from its parent. + +This is development preparation only. Candidate-001 has not been selected, +frozen as final, independently evaluated, or promotion-authorized. + +**Status:** preregistered development; selection, future-final evaluation, +protected custody, independent operation, formal MNCS/MNCDS status, and promotion +remain `UNKNOWN` or unauthorized. + +## Cross-version claim boundary + +RAVEL shows how a machine-native architecture and its evidence system can evolve +through explicit epochs while preserving failed results and historical caveats. +It does not establish general intelligence, language-model performance, +real-world generalization, production safety, protected evaluation, or formal +conformance. From 1096f1591d3a8676d282d052a34dae8736e77968 Mon Sep 17 00:00:00 2001 From: epi13 Date: Sat, 1 Aug 2026 21:07:55 -0800 Subject: [PATCH 6/7] docs: add RAVEL tooling guide --- case-studies/ravel/tools/README.md | 109 +++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 case-studies/ravel/tools/README.md diff --git a/case-studies/ravel/tools/README.md b/case-studies/ravel/tools/README.md new file mode 100644 index 0000000..4096709 --- /dev/null +++ b/case-studies/ravel/tools/README.md @@ -0,0 +1,109 @@ +# RAVEL tooling guide + +The scripts in this directory build, verify, mutate, digest, and summarize RAVEL +evidence. They are support tools, not automatic sources of independent custody, +organizational independence, or promotion authority. + +## Tool categories + +| Tool | Role | +|---|---| +| `ravel_0_4_evidence.py` | Generate, verify, and record bounded 0.4 evidence and runtime observations | +| `ravel_source_digest.py` | Verify ordered 0.4 source identity and assurance bindings | +| `ravel_0_5_evaluator.py` | Independently derive 0.5 metrics and hard gates from raw observations | +| `ravel_0_5_evidence.py` | Orchestrate 0.5 generation, verification, mutation tests, development gates, manifest tests, and runtime capture | +| `ravel_0_5_source_digest.py` | Verify 0.5 source and execution identity | +| `ravel_0_6_seed_candidate.py` | Derive bounded 0.6 candidate-001 development source from an exact SHA-256-bound 0.5 input | + +Other support modules in this directory should follow the same separation: +mechanism execution emits facts; evaluators derive results; digest tools bind +identity; orchestration scripts do not silently expand claims. + +## Verification before generation + +Prefer read-only or temporary-output targets first: + +```bash +make 0.4-check +make 0.4-manifest-negative-test +make 0.4-checkpoint-test +make 0.4-lineage-test +make 0.4-negative-test + +make 0.5-test +make 0.5-check +make 0.5-development-gates +make 0.5-negative-test +make 0.5-manifest-negative-test +``` + +The compiler-matrix and sanitizer targets add useful implementation checks: + +```bash +make 0.4-compiler-matrix +make 0.4-sanitizers +make 0.5-compiler-matrix +make 0.5-sanitizers +``` + +## Targets that rewrite evidence + +The following targets may replace repository-visible development records: + +```bash +make 0.4-evidence +make 0.4-runtime +make 0.5-evidence +make 0.5-runtime +``` + +Run them only when intentionally updating the applicable epoch. Review the full +diff, confirm the candidate and source identity, and preserve failed or +`UNKNOWN` results. + +## RAVEL 0.5 authority split + +The 0.5 C executable should emit raw integer observations and integrity facts. It +must not declare the authoritative development verdict. The Python evaluator: + +- validates the frozen trial and partition matrix; +- rejects missing, duplicated, malformed, contradictory, or substituted data; +- derives metrics from raw facts; +- applies each hard gate independently; +- preserves all failed trials and reason codes; and +- generates human-readable results from canonical evidence. + +A separate program is useful for authority separation, but repository-local +separation alone is not organizational independence or protected evaluation. + +## RAVEL 0.6 candidate derivation + +`ravel_0_6_seed_candidate.py` is deliberately narrow. It: + +- requires the exact frozen 0.5 source digest; +- applies only declared transformations; +- requires each transformation to match exactly once; +- produces deterministic development source; +- supports read-only checking; and +- does not claim selection, final evaluation, or promotion. + +The current candidate-001 corrections expand planning traversal to all declared +transition slots and remove inherited empirical support from adaptation births. +See `../RAVEL_0_6_NEXT_STEPS.md` for the remaining lifecycle and evidence work. + +## Adding or changing a tool + +A tooling change should state: + +1. which epoch and candidate it applies to; +2. whether it reads or writes evidence; +3. which inputs and executable identities it binds; +4. whether it emits facts or derives verdicts; +5. which malformed or adversarial inputs it rejects; +6. whether its output is deterministic; +7. whether the change invalidates prior manifests or assurance records; and +8. which claims remain outside repository-local authority. + +Do not reuse final observations as same-candidate repair input, weaken gates after +observing outcomes, discard failed records, or convert missing external evidence +into `PASS`. From 2dc719e3ecbd9278cb10c0150ae8b2c0db21a3ce Mon Sep 17 00:00:00 2001 From: epi13 Date: Sat, 1 Aug 2026 21:08:31 -0800 Subject: [PATCH 7/7] docs: update RAVEL case-study range --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d7f301b..1296ae0 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ or offline MNCS/MNCDS validation and cannot create independent or protected evid - [Multilingual Stream](case-studies/multilingual-stream/README.md) — shared C11/Rust contract. - [Go Gateway](case-studies/go-gateway/README.md) — bounded concurrency and cancellation. - [Composed Gateway](case-studies/composed-gateway/README.md) — C11 FFI, generated Go bindings, Go orchestration, Rust authority, recovery, measurement, custody, claim readiness, and portable physical-host reproduction. -- [Remote Water Control](case-studies/remote-water-control/README.md), [RAVEL 0.1–0.5](case-studies/ravel/README.md), and [dSense](case-studies/dsense-desk-pet/README.md) — additional bounded studies with explicit non-promotion boundaries. +- [Remote Water Control](case-studies/remote-water-control/README.md), [RAVEL 0.1–0.6](case-studies/ravel/README.md), and [dSense](case-studies/dsense-desk-pet/README.md) — additional bounded studies with explicit non-promotion boundaries. ## Current claim boundary @@ -119,4 +119,4 @@ external-actor limits. - `docs/` — documentation. - `rfcs/` — governance proposals, including RFC 0006, RFC 0007, and RFC 0008. -Read `CONTRIBUTING.md`, `GOVERNANCE.md`, and the RFC process before proposing normative changes. +Read `CONTRIBUTING.md`, `GOVERNANCE.md`, and the RFC process before proposing normative changes. \ No newline at end of file