elsa-core/specs/001-shell-reload-api/data-model.md

Data Model: Shell Reload API Endpoints

Entity: Shell Reload Command

• Purpose: Represents an administrative request to refresh shell runtime state.
• Fields:
  • Scope: All or Targeted.
  • RequestedShellId: optional shell identifier; required when scope is Targeted.
  • RequestedAt: execution timestamp captured for result reporting and diagnostics.
• Validation rules:
  • RequestedShellId is required for targeted commands.
  • Shell identifiers are matched case-insensitively to align with ShellId semantics in CShells.

Entity: Shell Reload Result

• Purpose: Represents the top-level outcome returned by either reload endpoint.
• Fields:
  • Status: one of Completed, Partial, Failed, Busy, NotFound, or RequestedShellFailed.
  • RequestedShellId: optional shell identifier echoed for targeted requests.
  • Shells: collection of Shell Reload Item Result records for each affected shell.
  • ReloadedAt: timestamp indicating when the orchestration completed.
• Validation rules:
  • Shells must be populated for Completed, Partial, and RequestedShellFailed outcomes.
  • RequestedShellId must be populated for Targeted requests.

Entity: Shell Reload Item Result

• Purpose: Describes the shell-level result used to explain a full or targeted reload outcome.
• Fields:
  • ShellId: shell identifier.
  • Outcome: one of Reloaded, Unchanged, Removed, InvalidConfiguration, Unknown, or Skipped.
  • Requested: boolean indicating whether this item is the caller’s explicitly requested shell.
  • Message: optional human-readable detail describing why the shell remained unchanged or failed.
• Validation rules:
  • Each ShellId appears at most once per response.
  • Requested is true for at most one item.

Entity: Shell Reload Scope Snapshot

• Purpose: Internal planning concept representing the latest provider settings compared with the current cache before orchestration runs.
• Fields:
  • CurrentShellIds: current in-memory shell identifiers from the settings cache.
  • LatestShellSettings: latest shell settings from the provider.
  • MissingShellIds: current shells absent from the latest provider view.
• Why it matters: The orchestration needs this snapshot to distinguish updates, additions, removals, unknown shell requests, and unchanged shells.

State Transitions

Full Reload Command

Pending → Completed when all affected shells refresh successfully.

Pending → Partial when at least one shell refreshes successfully and at least one shell remains unchanged because of invalid configuration or a shell-specific failure.

Pending → Busy when another reload is already in progress.

Pending → Failed when the shell settings provider cannot supply usable configuration for the operation.

Targeted Reload Command

Pending → NotFound when the requested shell ID does not exist in the authoritative configuration view.

Pending → Busy when another reload is already in progress.

Pending → Completed when the current full-reload fallback completes and the requested shell refreshes successfully.

Pending → RequestedShellFailed when the fallback full reload updates some shells but the requested shell remains unchanged because its updated configuration could not be applied.

Pending → Failed when the shell settings provider cannot supply usable configuration for the operation.