Substrate Core Contracts

This reference describes the public API in cerebel-substrate-core.

Public exports

Runtime contracts:

1. SubstrateLifecycleState
2. SubstrateHandle
3. Substrate
4. SubstrateLauncher

Launch-domain contracts:

1. LauncherBackend
2. SubstrateLifecyclePolicy
3. SubstrateLaunchTarget
4. SubstrateLaunch
5. SubstrateDomain
6. SubstrateRef

Enums

LauncherBackend

Accepted values:

1. inprocess
2. shell
3. container
4. remote

Meaning: execution backend used by launcher infrastructure to invoke package launch target.

SubstrateLifecyclePolicy

Accepted values:

1. dynamic
2. static

Meaning: orchestration lifecycle mode for a substrate domain entry.

SubstrateLifecycleState

Accepted values:

1. starting
2. ready
3. degraded
4. stopped

Meaning: observed runtime lifecycle state of a launched substrate instance.

Models

SubstrateLaunchTarget

Fields:

Field	Type	Required	Constraints
module-path	str	yes	non-empty
symbol-name	str	yes	non-empty

Purpose: import target that resolves the package launch callable.

SubstrateLaunch

Fields:

Field	Type	Required
launcher	LauncherBackend	yes
target	SubstrateLaunchTarget	yes

SubstrateDomain

Fields:

Field	Type	Required	Constraints
kind	str	yes	non-empty
definition-id	str	yes	non-empty
description	str	yes	non-empty
lifecycle-policy	SubstrateLifecyclePolicy	yes	enum
launch	SubstrateLaunch	yes	strict object
metadata	mapping	no	defaults to {}
body	str	no	defaults to “”

SubstrateRef

Fields:

Field	Type	Required	Constraints
definition-id	str	yes	non-empty
ref	str	yes	non-empty

SubstrateHandle

Fields:

Field	Type	Required
definition_id	str	yes
instance_id	str	yes
healthy	bool	yes
lifecycle_state	SubstrateLifecycleState	yes

Behavior:

1. strict extra field rejection
2. frozen model
3. id property aliases instance_id

Runtime base class

Substrate

Constructor:

def __init__(self, *, definition_id: str, instance_id: str | None = None) -> None

Abstract method:

def handle(self) -> SubstrateHandle

Runtime methods:

1. health() -> bool
2. readiness() -> bool
3. shutdown() -> None

Readiness rule:

1. true only when healthy is true and lifecycle state is ready.

Shutdown rule:

1. shutdown sets healthy false and lifecycle state stopped.

Launcher interface

SubstrateLauncher

Launch signature:

def launch(self, domain: SubstrateDomain) -> Substrate

Contract:

1. accepts one substrate-domain config object
2. returns one instantiated substrate runtime

Validation behavior

All domain contracts are strict and frozen:

1. unknown fields rejected
2. required text fields must be non-blank
3. enum values must match exactly