reconciliation-models

Prior Art: Registry/Command vs Desired-State Reconciliation Models

Research note supporting the workspace state-management decision: the host filesystem is authoritative, the desktop keeps a *registry* (tracking index + desktop-only annotations), sync is level-triggered snapshots converging the record toward the world, and host mutations are one-shot durable commands in an outbox — deliberately *not* Kubernetes-style spec/status convergence. All claims below are from primary sources (official docs, specs, man pages), linked inline. Researched 2026-08-03.

> **Update 2026-08-05:** the durable-command outbox described here was itself retired. > Host mutations are now plain fail-fast RPC verbs (ADR 0005) and offline deletion is a > client-side tombstone converged by an entity-generic reconcile sweep (ADR 0006). The > registry/snapshot half of this note stands; read the outbox references as historical.

1. Kubernetes spec/status

Source: [API conventions, "Spec and Status"](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status) unless noted.

• `spec` is "a complete description of the desired state", persisted with the object;

`status` "summarizes the current state of the object in the system" and its fields "should be the most recent observations of actual state".

• Ownership is enforced structurally: spec and status "can (and usually should) have

distinct authorization scopes" — users get write access to spec, controllers get read-only spec and full write on status. PUT/POST "MUST ignore the `status` values"; a `/status` subresource MUST exist for system components to write status.

• Direction of reconciliation: "Over time the system will work to bring the `status` into

line with the `spec`" — the world is driven toward the record, the inverse of emdash's registry.

• Level-based, not edge-based: the system drives toward the most recent spec "regardless

of previous versions", explicitly "not required to 'touch base'" at intermediate values. Restated later: "The system is level-based rather than edge-triggered, and should assume an Open World." Emdash's snapshot sync borrows exactly this property (missed intermediate states don't matter), just pointed the other way.

• The record is existence-authoritative: "If the specification is deleted, the object will

be purged from the system." Deleting the record deletes the world — again inverted from emdash, where deleting the world updates the record.

• Controllers are control loops that "watch the state of your cluster, then make or request

changes", each trying "to move the current cluster state closer to the desired state" ([Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)). This is why out-of-band deletion of a controller-managed object (e.g. a ReplicaSet's Pod) is repaired by recreation: the desired state still exists in the record.

• `observedGeneration` in status lets clients check whether the acting component has seen

the latest spec — a record-side freshness marker emdash doesn't need because it has no standing spec.

Deletion and GC ([Finalizers](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/), [Garbage Collection](https://kubernetes.io/docs/concepts/architecture/garbage-collection/)):

• Deletion is itself declarative: DELETE sets `metadata.deletionTimestamp`, returns HTTP

202, and the object "remains in a terminating state" until every key in `metadata.finalizers` is removed by its owning controller; only then is the object actually deleted. Once `deletionTimestamp` is set, finalizers may be removed but not added, and "you can not resurrect this object".

• `ownerReferences` drive cascading GC: "Kubernetes checks for and deletes objects that no

longer have owner references". Foreground deletion blocks the owner on dependents with `blockOwnerDeletion=true`; background deletion (the default) deletes the owner immediately and GCs dependents later; orphaning is an explicit opt-out.

**Assumptions the model bakes in:** a single writer owns desired state (spec authz scope); controllers are always-on and colocated with the API server holding truth (deletion *cannot complete* until a controller processes finalizers — a crashed controller wedges deletion, per the finalizers doc's "stuck in a deleting state" warning); and the stored record is authoritative for both existence and intent. None of these hold for emdash: users mutate host filesystems directly, hosts are intermittently connected, and the host — not the desktop DB — is truth.

2. Terraform state + config

Sources: [State](https://developer.hashicorp.com/terraform/language/state), [Purpose of State](https://developer.hashicorp.com/terraform/language/state/purpose), [terraform refresh](https://developer.hashicorp.com/terraform/cli/commands/refresh), [Import](https://developer.hashicorp.com/terraform/language/import), [terraform state rm](https://developer.hashicorp.com/terraform/cli/commands/state/rm), [removed block](https://developer.hashicorp.com/terraform/language/block/removed).

• What state is FOR: "The primary purpose of Terraform state is to store bindings between

objects in a remote system and resource instances declared in your configuration" — a mapping/registry, not the desired state itself. It also stores metadata (e.g. the last known dependency order so deleted config can still be destroyed correctly) and "a cache of the attribute values for all resources … done only as a performance improvement" (Purpose page). Terraform "expects a one-to-one mapping between configured resource instances and remote objects" (State page).

• Refresh converges state toward reality: "Prior to any operation, Terraform does a refresh

to update the state with the real infrastructure" (State page); `terraform refresh` "reads the current settings from all managed remote objects and updates the Terraf