Reconciliation

Reconciliation is the heart of the intended Hostwright release. It should be boring: deterministic, observable, and hard to corrupt. Phase 2 does not run this loop yet; it only validates a manifest and renders a non-mutating manifest-level plan.

The intended loop

load desired state from the state store
observe runtime state through the RuntimeAdapter
build a runtime snapshot with timestamps
compare desired state to observed state
produce a deterministic diff
produce an ordered action plan
validate safety gates
persist plan and intent
apply actions idempotently
record events and status transitions
observe again

The diff and the plan must become first-class artifacts. Today, hostwright plan does not observe Apple container and does not compute real runtime actions.

Dry-run and apply

• plan today validates the manifest and prints a non-mutating manifest-level plan. Nothing in the runtime changes.
• plan later must compute real desired-vs-observed drift after read-only runtime observation exists.
• apply later must run the plan, persisting intent before each mutation and the result immediately after.

Because intent must be persisted before mutation, the future apply design needs SQLite operation records before runtime mutation begins.

Idempotency

Applying a converged state should be a no-op once apply exists. The rules that make this safe:

• Creating an already-correct container is a no-op or a clear “already converged” result.
• Starting an already-running container is not an error.
• Stopping an already-stopped container is safe.
• Deleting a missing Hostwright-owned container is safe.
• Resources created out-of-band are never deleted without ownership proof.

Drift

Drift is the gap between what you declared and what is running. Real drift detection is planned after read-only runtime observation. Current hostwright status is manifest-level only and must not be read as service health or runtime state.

Events

Every meaningful runtime step must eventually emit a structured event so failures are explainable after the fact:

Event {
  type: planned | applied | failed | health_changed
        | drift_detected | restarted | cleaned
  severity: info | warning | error
  project, service?, instance?
  message, runtimeRef?, timestamp, correlationID
}

Open questions

• Should rollback for a partial apply be automatic, manual, or plan-only by default?
• How aggressively should the loop re-reconcile on drift versus waiting for an explicit apply?