From d28531a1a48c73955a1be60c06869cfa3247930b Mon Sep 17 00:00:00 2001 From: epi13 Date: Sun, 30 Aug 2026 10:58:52 -0800 Subject: [PATCH] Document one-step distilled micro-provider architecture --- docs/ARCHITECTURE.md | 30 ++++++ docs/LEARNED_MICRO_PROVIDERS.md | 41 ++++++++ docs/MNCS_NATIVE_TRAINING_PIPELINE.md | 36 +++++++ docs/ROADMAP.md | 4 +- .../0003-one-step-distilled-specialists.md | 99 +++++++++++++++++++ 5 files changed, 209 insertions(+), 1 deletion(-) create mode 100644 docs/decisions/0003-one-step-distilled-specialists.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 10cd72e..1803b2d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -71,6 +71,36 @@ admitted provider reusable, while its placement policy may select CPU, full CUDA sequential CPU offload. The latter keeps weights in system RAM and temporarily executes modules on CUDA; it does not reload a provider for each query. Placement decisions are resource-accounted and diagnostic, never evaluator decisions. +#### One-step distilled specialists + +A one-step distilled specialist is a training and deployment pattern for a learned +micro-provider, not a new authority plane or evaluator. A bounded iterative teacher—such +as a larger model, a multi-pass analyzer, or an expensive optimizer—may produce candidate +traces for a narrow question. After those traces are independently checked, a compact +student can learn: + +```text +identity-bound snapshot + query + constraints + | + v + one learned forward pass + | + v +structured proposal / diagnostic score + confidence + abstention +``` + +"One step" bounds learned inference after snapshot construction; it does not remove +deterministic preprocessing, policy validation, Forge probes, or escalation. It is +appropriate when a rich input representation strongly constrains the answer. The +iterative path remains the fallback for novelty, ambiguity, long-horizon work, or +abstention. + +The teacher supplies candidate training behavior, not truth. MNEL records teacher, +student, distillation, feature, calibration, artifact, and evaluation identities, and +measures end-to-end snapshot cost, cold/warm latency, useful downstream probes, transfer, +and abstention. The student remains diagnostic-only until a separately governed consumer +admits it; it cannot issue evaluator results, conformance, promotion, or permissions. + ### Bounded Forge-oriented diagnostic lifecycle diff --git a/docs/LEARNED_MICRO_PROVIDERS.md b/docs/LEARNED_MICRO_PROVIDERS.md index 5281c16..34e140b 100644 --- a/docs/LEARNED_MICRO_PROVIDERS.md +++ b/docs/LEARNED_MICRO_PROVIDERS.md @@ -124,6 +124,47 @@ A learned ranking router may later order already-compatible declarations, but it expand authority, access hidden partitions, bypass cost ceilings, or invoke an undeclared provider. +## One-step/distilled specialists + +One-step distillation is a provider pattern that compresses a bounded iterative procedure +into one learned forward pass over a prepared, identity-bound representation. The +iterative procedure may be a general-model interaction, a multi-pass analyzer, a search +or optimization loop, or another expensive teacher. The student is useful when the +snapshot, query, and constraints already narrow the valid answer space. + +The pattern is: + +```text +teacher: rich snapshot + bounded question + -> iterative candidate trace + -> independent checks / useful labels +student: rich snapshot + bounded question + constraints + -> one forward pass + -> structured proposal, score, or next-probe ranking + -> calibrated confidence or ABSTAIN +``` + +The one-pass boundary applies to learned inference after feature and snapshot +construction. It does not remove deterministic normalization, schema and policy checks, +Forge verification, or escalation. A student must retain the iterative or general-model +path as a fallback for novelty, ambiguity, long-horizon work, and out-of-distribution +inputs. + +This is not a new architecture family in the catalog. It is a deployment and training +pattern that can apply to a transition predictor, graph model, sequence model, anomaly +detector, pair model, tabular model, or bounded router. The teacher's output is a +candidate training target, not an authority claim; teacher traces must retain their +identities and any independent evaluator or witness evidence. The student's declaration +and observation must additionally identify the teacher/procedure, distillation transform, +target interpretation, fallback, calibration, and abstention policy. + +Admission should compare the student with the iterative teacher, a deterministic or +classical baseline, and a no-distillation control under equal budgets. It should report +end-to-end snapshot construction separately from one-pass inference, along with cold and +warm latency, useful confirmed Forge probes, calibration, abstention, out-of-distribution +behavior, hidden transfer, and false accepts. A lower forward-pass latency is not a +system-level win if representation construction, escalation, or verification erases it. + ## Deterministic matching and diversity selection A query declares one or more uncertainty classes and may constrain artifact types, diff --git a/docs/MNCS_NATIVE_TRAINING_PIPELINE.md b/docs/MNCS_NATIVE_TRAINING_PIPELINE.md index ccee75e..1da683a 100644 --- a/docs/MNCS_NATIVE_TRAINING_PIPELINE.md +++ b/docs/MNCS_NATIVE_TRAINING_PIPELINE.md @@ -337,6 +337,42 @@ mnel.train That creates an opportunity for resident micro-models whose training and execution are both lightweight, reproducible, and deeply integrated with MNCS evidence. +### Distillation and one-step inference + +For a narrow MNEL specialist, distillation may turn an expensive iterative teacher into a +single learned forward pass: + +```text +teacher: identity-bound evidence + bounded question + -> multi-step reasoning, analysis, search, or optimization + -> candidate trace +student: same declared input envelope + -> one learned forward pass + -> structured output + calibration + abstention +``` + +This is an execution property of the student, not a claim that the student has recovered +the teacher's reasoning or that one pass is sufficient for every input. Snapshot +construction, feature extraction, normalization, schema validation, deterministic policy, +Forge probes, and escalation remain separate operations. + +An MNCS-owned training graph should represent the distillation boundary explicitly: + +- teacher model or procedure identity and version; +- eligible teacher traces and source observation identities; +- target construction and distillation-transform identity; +- student architecture, objective, initialization, and resource envelope; +- calibration, abstention threshold, fallback, and escalation policy; +- independent evaluation, hidden-transfer, and no-distillation control identities; +- checkpoint, quantization, packaging, and final artifact identities; and +- lineage edges connecting the deployed student to its source evidence. + +Teacher outputs are candidate targets, not automatically true labels. Independent witnesses, +evaluators, and hard gates retain their existing authority. MNEL owns the provider's +declaration, study, diagnostic observation, and routing/escalation contract; MNCS should +eventually own the canonical training semantics and lineage for the distillation itself. +Until then, an external trainer may execute an MNCS-described run as a backend adapter. + ## Language stress-test value Building this pipeline should be treated as a deliberate stress test for `mncs-language` diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index bc3bce0..a6fbd14 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -93,7 +93,9 @@ otherwise the study records unavailable rather than estimating; - non-Rust native exception studies with benchmark and threat-review identities; - hidden-transfer admission, quarantine, retirement, and rollback workflows; -- optional small proposer-model distillation from verified traces. +- optional small proposer-model distillation from verified traces, including one-step + students measured against iterative teachers, deterministic baselines, and explicit + abstention/escalation paths. ## 0.5 — MNCS Fabric execution diff --git a/docs/decisions/0003-one-step-distilled-specialists.md b/docs/decisions/0003-one-step-distilled-specialists.md new file mode 100644 index 0000000..4ea2020 --- /dev/null +++ b/docs/decisions/0003-one-step-distilled-specialists.md @@ -0,0 +1,99 @@ +# ADR 0003: One-step distilled specialists for bounded micro-providers + +- **Status:** Accepted +- **Date:** 2026-08-30 +- **Scope:** MNEL learned micro-providers and the MNCS-native training/lineage boundary + +## Context + +MNEL already treats small, task-specific learned providers as bounded cognitive +components. Some useful provider tasks are currently performed by an expensive +iterative procedure: a larger model may reason over a structured snapshot, an analyzer +may make several passes, or an optimizer may search a bounded space. Repeating that +procedure for every similar query can dominate latency and resource use even when the +input representation and constraints strongly narrow the answer. + +The one-step idea is to use the iterative procedure as a teacher, retain its candidate +traces and independent evidence, and distill a compact student that emits the bounded +result in one learned forward pass. The student should expose a structured output, +calibrated confidence, and explicit abstention so it can escalate when the one-pass +approximation is not justified. + +The key placement question is whether this belongs in MNEL, MNCS, Forge, or Fabric. +It crosses those boundaries, but it is not a new execution authority or conformance +mechanism. + +## Decision + +MNEL adopts one-step distilled specialists as a documented provider pattern. + +1. **MNEL owns the operational provider surface.** It declares the task, input snapshot, + output contract, teacher/procedure identity, distillation transform, calibration, + abstention, fallback, study controls, diagnostic observation, and routing/escalation + behavior. +2. **The student is a learned micro-provider, not a new catalog family.** The pattern can + apply to transition, graph, sequence, pair, anomaly, tabular, or routing providers. + Catalog selection remains deterministic-first and capability-bound. +3. **One step means one learned forward pass after representation construction.** + Snapshot construction, feature extraction, normalization, schema/policy checks, Forge + probes, and escalation are outside that bound. +4. **The teacher provides candidate behavior, not truth.** Teacher traces are training + evidence or candidate targets. Independent witnesses, evaluators, and hard gates + retain authority over claims and outcomes. +5. **Abstention is mandatory.** Novel, ambiguous, unsupported, long-horizon, or + out-of-distribution inputs must escalate to the teacher, an ordinary model, a + deterministic path, or an explicit `UNKNOWN` result. +6. **Admission is evidence-based.** A student must be compared with its iterative teacher, + a deterministic/classical baseline, and a no-distillation control under equal budgets. + Admission studies must measure end-to-end snapshot cost, cold/warm latency, useful + downstream probe yield, calibration, false accepts, abstention, and hidden transfer. +7. **MNCS owns the eventual training semantics and lineage.** The canonical training + graph should record source evidence, teacher/procedure, target construction, student + configuration, optimization, checkpointing, evaluation, packaging, and deployment + identities. External trainers may serve as execution backends while that semantic + contract is being implemented. +8. **Forge, Fabric, Harness, and Control retain their existing boundaries.** Forge verifies + bounded claims and operating-envelope failures; Fabric executes and reports factual + placement/residency; Harness/Control govern use and escalation. None treats student + output as conformance, evaluator, permission, or promotion authority. + +## Consequences + +### Positive + +- Repeated bounded reasoning can move to a low-latency, resident specialist. +- The iterative teacher remains available as a correctness and novelty fallback. +- The architecture makes the speed claim measurable at system level instead of only at + model forward-pass level. +- Teacher, student, distillation, and lineage identities remain auditable. +- The pattern can be applied across heterogeneous provider architectures without making + them interchangeable. + +### Costs and limitations + +- Distillation can memorize teacher errors or reduce coverage on rare cases. +- A one-pass student may hide useful intermediate signals needed for attribution. +- Snapshot construction and verification may dominate the actual inference savings. +- Teacher traces, independent checks, calibration, transfer studies, and controls add + data and operational cost. +- The pattern is not appropriate for open-ended generation, weakly constrained inputs, + or tasks whose correctness requires unbounded interaction. + +## Implementation and review requirements + +Future implementations must: + +- preserve the `diagnostic-only` authority and existing `PASS`/`FAIL`/`UNKNOWN` separation; +- retain teacher traces, source evidence, counterexamples, abstentions, and rejected + students rather than collapsing them into a score; +- bind model, feature, snapshot, distillation, calibration, runtime, and artifact identities; +- keep the teacher/fallback path available during shadow and governed deployment; +- evaluate with hidden transfer and a no-distillation control before direct routing; and +- document any claim of one-step with the exact measured boundary and excluded costs. + +This ADR does not add a runtime dependency, change the v1 ABI, or claim that a one-step +student currently improves MNEL. It records where the idea belongs and the evidence +required before implementation or promotion. + +See [MNEL architecture](../ARCHITECTURE.md), [learned micro-provider registry](../LEARNED_MICRO_PROVIDERS.md), +and [MNCS-native training pipeline](../MNCS_NATIVE_TRAINING_PIPELINE.md).