docs/RETINA.md

RETINA

Runtime Environment Transduction, Inference & Native Adaptation

RETINA is SignalMesh's normalization membrane between ingestion and execution.

Its invariant is simple:

thing + desired affordance -> Environment DNA -> resolve -> gaps -> RTENV recipe -> probe -> verified capability

What RETINA owns

RETINA identifies a thing, gathers evidence, extrapolates the affordances required for the requested experience, resolves those requirements against the current host and mesh, and emits the smallest environment recipe necessary to make the affordance real.

RETINA does not assume a container, language VM, GPU, local process, or LLM is required. Existing capabilities are preferred. Missing requirements are explicit gaps rather than excuses to synthesize an entire replacement environment.

Contracts

signalmesh.retina.v1

Environment DNA contains:

• thing identity/fingerprint
• desired experience/mode
• evidence
• explicit requirements
• resolved host/mesh bindings
• unresolved capability gaps

signalmesh.rtenv.v1

RTENV is a recipe, not necessarily a container. It contains the resolved bindings, unresolved gaps, insulation policy, and a mandatory proof requirement.

A runtime is not considered a mesh capability merely because it started. It becomes one only after its requested affordance is probed successfully.

Relationship to existing SignalMesh pieces

• Ingestion exposes a thing to RETINA; ingestion does not imply storage.
• Atlas / mesh coordinates can satisfy existing capability requirements.
• Forge should receive required DNA - resolvable DNA, not the entire original task.
• MPort exposes a verified affordance through a stable callable membrane.
• GridStack composes verified affordances rather than vaguely defined tools.
• SLM Orchestra / residents consume those affordances; they are not required for transduction itself.
• .fq may express the desired experience that constrains Environment DNA.

Healing

Healing is environment recomposition, not blind process retry.

A failed probe produces evidence. RETINA may use that evidence to refine DNA, choose an allowed alternative, resolve a different existing capability, or hand a precise remaining gap to Forge. The recomposed environment must then be probed again.

First implementation

core/retina.py implements the first evidence-bound core:

1. transduce() — Thing + desired mode -> Environment DNA.
2. host_capabilities() — cheap host capability observation.
3. resolve() — match DNA against host + supplied mesh capabilities.
4. compose() — produce a minimal RTENV recipe.
5. pipeline() — deterministic end-to-end contract without executing the thing.

The next integration boundary is capability discovery from the live mesh and a verified RTENV materializer/probe loop. That layer must reuse existing execution/Forge surfaces rather than duplicate them inside RETINA.