Discovery: 'lifecycle' names three different concepts in the domain #1782

Open
opened 2026-11-02 15:22:44 +00:00 by sam · 1 comment
Owner

From the 2026-08 architecture review follow-up (related to #1781).

What is wrong: "lifecycle" names three different concepts in the domain, so a reader can't tell what a piece solves:

  1. internal/domain/lifecycle — a generic engine registry (Engine[H]: Name/Bind/Start/Health/Stop) used by curators and memory engines; in-memory component lifecycle.
  2. identity.Lifecycle (internal/domain/identity) — an entity status field: active/suspended/retired, driven by suspend/reactivate commands.
  3. storecontract.TaskLifecycle — the store surface of the task state machine (enqueue/claim/transition/requeue), implemented in postgres and guarded by the transition table in internal/taskstate.

Wanted: distinct names per concept (e.g. engine registry stays lifecycle; the task machine is a state machine — taskstate already owns its transition table; identity's is a status), or a recorded decision if the overlap is intentional. No behavior change either way.

Done when:

  • each concept has one unambiguous name in internal/domain (or a type::decision issue records why they share one)
  • references updated; task check green
From the 2026-08 architecture review follow-up (related to #1781). **What is wrong:** "lifecycle" names three different concepts in the domain, so a reader can't tell what a piece solves: 1. `internal/domain/lifecycle` — a generic *engine registry* (`Engine[H]`: Name/Bind/Start/Health/Stop) used by curators and memory engines; in-memory component lifecycle. 2. `identity.Lifecycle` (`internal/domain/identity`) — an entity *status* field: active/suspended/retired, driven by suspend/reactivate commands. 3. `storecontract.TaskLifecycle` — the store surface of the *task state machine* (enqueue/claim/transition/requeue), implemented in postgres and guarded by the transition table in `internal/taskstate`. **Wanted:** distinct names per concept (e.g. engine registry stays `lifecycle`; the task machine is a state machine — `taskstate` already owns its transition table; identity's is a status), or a recorded decision if the overlap is intentional. No behavior change either way. **Done when:** - each concept has one unambiguous name in `internal/domain` (or a `type::decision` issue records why they share one) - references updated; `task check` green
sam added the discovery label 2026-11-02 15:23:19 +00:00
Author
Owner

Instance found while reviewing: storecontract.TaskPage (Statuses/Workflow/After/Limit) and storecontract.DispatchFilter (BindingID/CaptureID/TaskID/Limit) are the same shape — a list filter plus a limit — but named for different halves of it (page vs filter). In practice TaskPage is a filter: internal/webui/api_tasks.go:97 builds it from URL query params (taskPageFrom(q url.Values)). The proto side calls the dispatch one ListDispatchesRequest and says it "filters". So the asymmetry is accretion, not meaning. Candidate fix under this ticket: one naming scheme, e.g. *Filter + an embedded Page{Limit, After}, or rename TaskPage → TaskFilter. Go-only rename; proto wire names unaffected.

Instance found while reviewing: `storecontract.TaskPage` (Statuses/Workflow/After/Limit) and `storecontract.DispatchFilter` (BindingID/CaptureID/TaskID/Limit) are the same shape — a list filter plus a limit — but named for different halves of it (page vs filter). In practice TaskPage *is* a filter: internal/webui/api_tasks.go:97 builds it from URL query params (`taskPageFrom(q url.Values)`). The proto side calls the dispatch one `ListDispatchesRequest` and says it "filters". So the asymmetry is accretion, not meaning. Candidate fix under this ticket: one naming scheme, e.g. `*Filter` + an embedded `Page{Limit, After}`, or rename TaskPage → TaskFilter. Go-only rename; proto wire names unaffected.
sam added the medium label 2026-11-14 14:45:43 +00:00
sam added the deferred label 2026-11-15 17:26:12 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#1782