Skip to content

Governed Home Assistant light set-state

Status: implemented Era 8 capability, default disabled.

Validation posture: Era 8 acceptance used a fake provider through the shared runtime. No credentialed live Home Assistant instance or physical device was mutated. A deployment is live-provider ready only when HOME_ASSISTANT_URL, HOME_ASSISTANT_TOKEN, the governed enable flag, and an explicit light.* target allowlist are configured and request-time inspection confirms provider and entity reachability. Repository evidence is runtime_smoke_tested, not live_external_tested.

Capability contract

  • Capability ID: governed_home_assistant_light_set_state
  • Operator outcome: inspect and explicitly set one registered Home Assistant light on or off without using a REST endpoint or infrastructure command.
  • Read-only operation: Oracle, inspect Home Assistant light <target-id>.
  • Mutation operation: Oracle, propose setting Home Assistant light <target-id> to on|off.
  • Target identity: HomeAssistantLightTargetRegistry, populated from LUNA_GOVERNED_HOME_ASSISTANT_LIGHT_TARGETS.
  • Source of truth: one exact light.* entity and its request-time provider state.
  • Proposal type: existing durable GovernedProposal with exact entity, observed state, requested state, and action identity hash-bound.
  • Approval authority: Lich, bound to proposal ID, hash, scope, actor, and expiry.
  • Validation authority: Home Assistant-specific canonical preflight over lifecycle, proposal integrity, evidence freshness, Lich authority, target registry, entity identity, and current observed state.
  • Execution authority: the existing Earthshaker provider’s fixed light.turn_on or light.turn_off call only.
  • Evidence: token-free Zeus records containing exact entity and normalized state before and after the provider call.
  • Receipt: durable completed or uncertain external-outcome receipt.
  • Rollback: compensating restoration of the observed prior state after a new Lich approval; it is not claimed as an exact external transaction reversal.
  • Restart behavior: proposal, approval, evidence, receipts, and lifecycle survive service reconstruction. Provider reachability and entity state are re-observed on continuation.
  • Oracle commands: inspect, propose, queue, validate, apply, audit, and separately approved compensation through the shared runtime.
  • Transport path: shared Runtime Kernel semantics for terminal, Discord, Web TUI, and other normalized transports.
  • Rubick posture: implementation and wiring are registered; Runtime Composition reports configured injection but does not claim live reachability without request-time evidence.
  • Meepo transitions: unchanged; the existing proposal transition matrix is used.
  • Persistence: existing SQLite governed proposal, Lich, Zeus, receipt, and rollback authorities.
  • Known limitations: configured light.* entities only; explicit on or off; no toggle, arbitrary domain, service, URL, scene, automation, cover, lock, or alarm.

Runtime configuration

The provider still requires HOME_ASSISTANT_URL and HOME_ASSISTANT_TOKEN. The token remains inside the provider and is never persisted in proposals, evidence, receipts, Oracle output, or Rubick records.

Governed execution additionally requires:

LUNA_GOVERNED_HOME_ASSISTANT_LIGHT_ENABLED=true

LUNA_GOVERNED_HOME_ASSISTANT_LIGHT_TARGETS is an explicit JSON list:

{
  "target_id": "patio.light",
  "label": "Patio light",
  "entity_id": "light.patio"
}

Aliases and conversational descriptions are not mutation authority. Unknown, ambiguous, unavailable, unsupported-state, stale-state, invalid-approval, and expired-approval requests fail closed before the POST.

External outcome semantics

After an accepted provider call, the capability reads the entity again. It claims success only when the observed state equals the approved state and after-evidence plus receipt are durable. A timeout, failed call, unavailable reconciliation, or state mismatch produces an uncertain receipt and an execution-failed lifecycle. Duplicate apply is then refused; the capability does not retry blindly.

Compensation also revalidates that the entity still has the executed state, calls only the inverse fixed on/off service, re-observes the result, and stores separate evidence and a receipt.

Operator workflow

Oracle, inspect Home Assistant light patio.light.
Oracle, propose setting Home Assistant light patio.light to on.
Oracle, show my action queue.
Oracle, validate proposal <proposal-id>.
Approve proposal <proposal-id>.
Oracle, apply approved proposal <proposal-id>.
Oracle, audit proposal <proposal-id>.
Request rollback for proposal <proposal-id>.
Approve rollback for proposal <proposal-id>.
Execute rollback for proposal <proposal-id>.

Oracle remains advisory and adapts only explicit vocabulary. Lich approves, the governed service validates and invokes the bounded provider, and Zeus owns durable evidence and receipts.