1. The digital twin
-
Stable record pointers. An application-assigned id (
rec_NNNNNN) is what retrieval hands to the model, what the model cites back, and what cross-module references use — identity stays stable across turns, across days, and across the client/server boundary. - Relational spine, JSONB leaves. Typed columns for everything queried or joined; a GIN-indexed semantic-tag array for retrieval; JSONB for the open-ended per-category long tail. Schema evolution without migration, with every index-bearing predicate still in a real column.
- Time modeled for lay speech. A record carries an absolute time where one exists, otherwise an age-anchor pair plus the owner’s own phrasing — a kitten-era event and a dated event live on one timeline without either being forced into the other’s representation.
2. Symptom model: two orthogonal axes
The core entity holds both a single-day observation and a multi-day episode, distinguished by lifecycle state — a course is what a day becomes, not a different kind of object.
- Type axis. 19 closed body-system categories. A category names a body system, not a verdict.
- Polarity axis. Three independently sourced judgments — the owner’s explicit assertion, a pure function of the structured fields, and the extraction model’s own reading — resolved by a database-generated column: any-abnormal-wins, and all-null resolves to abnormal (a false alarm, never a missed finding). Source attribution survives, so post-hoc analysis can ask which channel mislabels.
- Normal findings are first-class data. “His stool looked fine today” writes a normal row — including during an open episode, where a normal day is diagnostically meaningful. Tri-state booleans and an explicit “not observed” enum member throughout the field schemas are what make pertinent negatives representable at all: “I checked his gums, they’re pink” ≠ “I didn’t look”.
- Episode layer. An open course carries a per-day trajectory (onset / worsening / improving / unchanged / normal) and an append-only per-statement log — because a merged field-wise view has no unit for “one statement”, and three sentences about one ear in one day would otherwise collapse into a superposition true at no single moment.
-
Lifecycle floors. Transitions (
active → passive → closed, plusdormant) use model-proposed horizons clamped by floors the model cannot override: a minimum observation window, and a rule that a chronic course may go passive but never auto-closes.
3. Conversational pipeline: extraction ≠ routing
An earlier single extraction call both decomposed the utterance and decided where each piece belonged. Under load it fragmented observations, dropped bare answers, and guessed at times. The current design gives the model only the first job. Every extracted entry lands in an append-only observation ledger, and code decides materialization:
- Today → folds into the daily record.
- Past → becomes a history record on the twin.
- Ambiguous → triggers exactly one clarifying question; if still unanswered by the deadline it is materialized with an explicit null onset plus the owner’s original phrasing, for the nightly round to adjudicate. Dates are never fabricated to fill a slot.
Time is two independent axes — “is this happening today” versus “since when” — which is what allows the router to be deterministic. The burden of proof sits on the past side, so “he’s still sneezing, it started Tuesday” routes as an ordinary today-record carrying a three-day-old onset.
4. Three time scales
| loop | period | job |
|---|---|---|
| turn | seconds | extract, route to ledger, retrieve, respond |
| round server-side, per pet-local day | nightly | merge yesterday’s rows into courses; emit a diagnosis frame (current + append-only log); adjudicate leftover ambiguous entries; run lifecycle transitions; seed tomorrow’s follow-up agenda |
| longitudinal | weeks–months | steady-state profile re-measurement, version-to-version drift, assessment staleness (§5) |
The round is idempotent and catch-up-capable, guarded by a lease against concurrent execution; client-side execution exists only as a degraded fallback.
5. The steady-state profile, and staleness by construction
Each animal has a versioned normal-activity profile — its own steady state (stool frequency and form, intake, activity) — archived exactly once per re-measurement session, so two versions can be compared.
It is deliberately not a per-day comparator. Daily judgment runs on discrete rules with no “normal range” and no weighted deviation score; an earlier design that scored each day against a fitted normal was abandoned. Two scoped exceptions survive:
- body-condition score compares against its own previous value;
- the frequency axis reads two baseline fields for a relative call, falling back to absolute thresholds when the baseline is unavailable.
The profile’s real job is longitudinal: version-to-version drift — continuous fields at ≥30%, food ≥25%; ordinal fields by rank distance.
Drift feeds the persisted health assessment, which is keyed by a hash over its own inputs — and those inputs are restricted to the persistent portrait: banded age rather than exact, chronic background rather than active courses, long-term medication, the profile and its drift. Nothing transient enters, so the hash does not churn daily. There is no “refresh the assessment” code path at all:
re-measuring archives a version → drift becomes computable → the hash changes → the assessment reads as stale and offers regeneration, user-triggered rather than silently spending a model call.
Staleness is a derived property, not an event someone has to remember to fire.
6. Memory: three tiers with explicit expiry
- Working set. A bounded recent-turn window, plus retrieved records that hold survival reasons rather than timestamps — a semantic reason expires after 3 turns without renewed relevance, a structural reason when its parent leaves the set. An item is evicted only when all its reasons expire (cascade eviction), leaving a tombstone stub that keeps it cheaply re-retrievable and keeps the model aware something was set down, not never known.
-
Task memory. Open questions — the thing a health assistant most easily loses — live in
per-topic drawers keyed by set-membership over general intent, not by verbatim strings (which rebuilt
the container every turn and let questions silently evaporate). They are closed by question id
at the earliest point the evidence exists, and aged mechanically to
dormant: demoted without being deleted. The countervailing “interrogates the user” risk is handled by a hard deterministic cap on how many questions may reach the response prompt — the guard placed where it is mechanically checkable, not as a soft instruction. - Durable memory. The twin itself, plus a fact ledger of ruled-out and settled items injected into both chat and the nightly round to prevent re-asking. Nothing is carried forward in the context window; each turn re-assembles what it needs through a semantic catalog and content expander over the twin.