ADR-050: Definition/Instance Duality and Two-Tier Instance Layering¶

1. Context¶

ADR-036 layered the instance state (ResourceState → TimedResourceState → concrete) and ADR-047 gave us one reconcile loop. But the platform also has a large definition side — the legacy .NET Track Manager, Session Manager, and Pod Manager all express a definition → instance duality (SessionType → Session, PodDefinition → Pod, Track → … → Form). Today LCM models only a few of these (SessionDefinition, PodDefinition) ad hoc, with no shared base, and treats every runtime resource as timed — even automation outputs (Job, Report) that have no schedule of their own.

We need (a) one definition base mirroring the one instance base, and (b) a clean split between timed and untimed instances.

2. Decision¶

2.1 Two parallel families¶

Generalise onto two bases in lcm_core:

• ResourceDefinition — type metadata: type_key, version, provisioning_source, optional authorization_policy_id, a lifecycle template, child requirements/selectors, a definition_status, and (for synced content) a sync_status. Definitions are the catalogue; they do not reconcile against infrastructure.
• ResourceInstance — a running thing: status + desired_status, state_history, an instantiated lifecycle, owner_id, children. Its behaviour is to reconcile toward desired_status.

classDiagram
    class ResourceDefinition {
        +str type_key
        +str version
        +str provisioning_source
        +str~None authorization_policy_id
        +dict lifecycle_template
        +list child_requirements
        +str definition_status
        +str~None sync_status
    }
    class ResourceInstance {
        +str id
        +str resource_type
        +str definition_ref
        +str status
        +str~None desired_status
        +str owner_id
        +list state_history
        +reconcile()
    }
    class TimedResource {
        +dict timeslot
        +dict lifecycle
    }
    ResourceDefinition ..> ResourceInstance : instantiates
    ResourceInstance <|-- TimedResource
    ResourceInstance <|.. Job : untimed
    ResourceInstance <|.. Report : untimed
    TimedResource <|.. Session
    TimedResource <|.. SessionPart
    TimedResource <|.. PodInstance
    TimedResource <|.. Host

2.2 Two-tier instance layering¶

ResourceInstance (L1) carries lifecycle + reconciliation but no Timeslot. TimedResource (L2) adds the Timeslot (and TimedResourceState of ADR-036). The split decides where each resource sits:

2.3 Catalogue → runtime map¶

Device / DeviceDefinition are deferred (out of scope this round).

3. Consequences¶

Positive — one definition base + one instance base; a single mental model (definition instantiates instance); untimed automation no longer forced into a timeslot; aligns the reconcile loop (ADR-047) with both timed and untimed instances.

Negative / trade-offs — two base classes to maintain; the L1/L2 split must be enforced so untimed instances are not accidentally scheduled.

Persistence — both bases are state-based Neuroglia aggregates (MotorRepository + state_version); see ADR-051.

4. Related¶

• resource-model.md — instance side.
• definition-catalog-model.md — definition side.