Definition & Catalogue Model¶

Every runtime resource is created from a ResourceDefinition. This page describes the definition side of the resource model: where definitions come from (the two provisioning sources), the content-authoring taxonomy that supplies exam content, the catalogue / config plane of static reference data, and the authorization policy model that guards both. See ADR-051, ADR-052 and ADR-053.

Two provisioning sources¶

A definition's provisioning_source is the single switch that decides whether it reconciles:

The model's only asymmetry. seed definitions are inert reference data: a ResourceDefinition with definition_status = published and no reconciliation. content_package definitions are synced (not provisioned). Within the taxonomy, the Form is the one node that actually reconciles — the form-controller owns its sync loop (ADR-059); the surrounding Track/Exam/Module/Formset nodes are inert catalogue metadata.

stateDiagram-v2
    [*] --> Draft : created (synced from package)
    Draft --> Published : publish (content validated)
    Published --> Deprecated : superseded by newer version
    Published --> Published : re-sync (sync_status updated)
    Deprecated --> [*]
    note right of Published
        Only content_package definitions
        have this lifecycle. seed definitions
        are static config (no lifecycle).
    end note

Content-authoring taxonomy¶

Exam content is authored as a strict, versioned taxonomy (ported from the legacy Track Manager domain). Every node is a content_package ResourceDefinition; ids are deterministic slugs derived from the parent chain, which makes re-sync idempotent (a duplicate id is a conflict, not a new node).

erDiagram
    Track ||--o{ TrackItem : "canonical items"
    Track ||--o{ Exam : "versions"
    Exam ||--o| Blueprint : "active revision"
    Blueprint ||--o{ BlueprintNode : "topic tree"
    BlueprintNode ||--o{ BlueprintNode : "parent of"
    Exam ||--o{ Module : "split into"
    Module ||--o{ Formset : "groups"
    Formset ||--o{ Form : "versions"
    Form ||--o{ FormItem : "composed of"
    Form ||--o| PodDefinition : "optional pod (ADR-059)"
    TrackItem ||--o| FormItem : "realized by"
    FormItem }o--o{ BlueprintNode : "tagged with"
    SessionPart }o--|| Form : "delivers (by FQN)"
    Track }o--o| AuthorizationPolicy : "guarded by"
    Exam }o--o| AuthorizationPolicy : "guarded by"
    Form }o--o| AuthorizationPolicy : "guarded by"
    AuthorizationPolicy ||--o{ AuthorizationRequirement : "contains"

Form qualified name (FQN). A Form is addressed across services by its FQN — the six-token path through the taxonomy ({Type} {Level} {Acronym} v{version} {module} {form}). This is the key a PartDefinition selects by pattern.

Form delivery — the synced unit, no timed instance¶

A Form is authored content that syncs (ADR-059): it is the single content_package resource that reconciles (owns sync_status + the RustFS bytes) and carries an optional PodDefinition ref — a self-contained content + optional pod deliverable. It generalises the legacy LabletDefinition (single-part) to every use-case.

It is delivered by a SessionPart (the timed runtime instance) which selects the Form by FQN and inherits its optional pod. The Form lives on the catalogue / sync plane, so there is no separate timed Form instance in the runtime tree — the part is the runtime that delivers the form. Per-part automation (JobDefinition, ReportDefinition) travels with the same content package and drives the part's workflow lifecycle phases (collect / grade / report).

Catalogue / config plane¶

Reference data that has no timeslot and no reconciliation is modelled as seed ResourceDefinitions in a uniform catalogue. They are configuration the runtime reads, never resources the runtime drives:

Authorization model¶

Per-resource authorization is ported from the legacy domains as first-class definitions (AuthorizationPolicy + embedded AuthorizationRequirements). Keycloak/OIDC remains the authentication layer; the policy model adds fine-grained authorization filtering on top of it.

• An AuthorizationPolicy is a named, seed-provisioned ResourceDefinition composed of requirements. Any definition or resource may reference one via authorization_policy_id.
• An AuthorizationRequirement is one of two shapes:
• Claim — a claim_type (regex-capable) + optional claim_value. The value may be a JQ runtime expression evaluated against the entity under check (e.g. "the user's track claim must equal this track's id"). Absence ⇒ existence check only.
• Composite — All or Any over nested requirements (recursive).

Evaluation filters results rather than hard-failing, and admin principals bypass all checks (mirrors the legacy …ForCurrentUser queries):

flowchart TB
    U[ClaimsPrincipal] --> A{IsAdmin?}
    A -- yes --> G[Grant / include]
    A -- no --> P{Resource has authorization_policy_id?}
    P -- no --> G
    P -- yes --> L[Load AuthorizationPolicy]
    L --> R{Evaluate each requirement}
    R --> T{Requirement type}
    T -- Claim --> CV["Resolve claim value (JQ runtime expr, entity params)"]
    CV --> CM{User has matching claim?}
    T -- Composite --> CC{Condition}
    CC -- All --> ALL[every child passes]
    CC -- Any --> ANY[at least one child passes]
    CM -- yes --> G
    CM -- no --> D[Deny / filter out]
    ALL --> G
    ANY --> G

Persistence¶

Like every aggregate in LCM, definitions are state-based: a Neuroglia AggregateRoot whose state is persisted by a MotorRepository with state_version (not EventStore). The legacy event-sourced behaviour is preserved as @dispatch reducers over domain events; only the persistence differs. See ADR-051.

Where definitions are reconciled¶

See ADR-054 for the controller topology.

Related¶

• resource-model.md — the instance side (ResourceInstance / TimedResource).
• session-model.md — how a SessionPart selects and delivers a Form.
• unified-resource-management.md — resource lifecycle vs job automation.