Add a New Layer to a Substrate

Use this guide when an existing substrate needs an additional lamina and matching modulation behavior.

Example scenario

You currently have:

1. AgenticLamina
2. CortexLamina
3. SensoryMotorCortexLamina
4. SensoryCortexLamina

You want to add a new layer, for example ObservabilityLamina, plus the modulator support that makes it useful at runtime.

Steps

1) Insert the lamina where the behavior belongs

Add the new lamina between parent and child where behavior belongs.

Example:

1. AgenticLamina
2. CortexLamina
3. ObservabilityLamina
4. SensoryMotorCortexLamina
5. SensoryCortexLamina

2) Add or extend a synthesizer for the new modulator

The new layer should read a modulator that is produced by a synthesizer in response to a Neuromodulators fanout request originating from RAS:

class ObservabilitySynthesizer(Synthesizer):
    def __init__(self, neuromodulators: NeuromodulatorsForSynthesizer) -> None:
        self._neuromodulators = neuromodulators

    def can_handle(self, modulator_name: str) -> bool:
        return modulator_name == "observability"

    def synthesize(self, request: ModulatorRequest) -> ModulatorResult:
        modulator = ObservabilityModulator(enabled=True)
        artifact_ref = self._neuromodulators.add("observability", modulator)
        return ModulatorSuccess(
            request_id=request.payload.request_id,
            synthesizer_id="observability-synthesizer",
            artifact_ref=artifact_ref,
        )

3) Preserve identity from the existing cocktail

Do not create a new runtime identity in the inserted layer.

4) Update launch wiring only

Only change package launch wiring to register the new synthesizer with Neuromodulators or request the new modulator through RAS. Do not change adapter or launcher contracts.

Launch wiring should also ensure RAS resolves the returned artifact-ref through Neuromodulators before updating the cocktail.

5) Add regression tests

Add tests to assert:

1. New modulator requests are satisfied by the intended synthesizer.
2. Output runtime still satisfies Substrate handle/lifecycle contract.
3. Existing behavior remains intact.

Verification sequence

flowchart LR
    A[launch(domain)] --> B[RAS]
    B --> C[Neuromodulators request]
    C --> D[Fanout ModulatorRequest]
    D --> E[Observability Synthesizer]
    E --> F[Neuromodulators store and respond]
    F --> G[RAS resolve artifact-ref]
    G --> H[ModulatorCocktail]
    H --> I[Substrate Runtime]

Guardrails

1. Do not move modulation logic into launcher or adapter.
2. Do not hard-code synthesizer ownership rules into RAS.
3. Do not mutate domain input while satisfying modulator requests.
4. Keep launch signature unchanged.