Project artifacts

The stage-level files that sit alongside the atomic artifacts: the vocabulary they are written in, what was assumed, and what is still open.

Glossary

Terms

Baseline overhead: The idle footprint of a candidate runtime or application shell running an empty do-nothing application, before any pet logic is added. The figure CON-001 uses to exclude runtimes, because it is a floor that pet-code optimisation cannot lower. Also: empty-shell baseline.
Care loop: The four owner interactions that maintain the pet — feed, play, clean, and put to sleep — taken together as the interaction the accessibility and cross-platform targets are measured against.
Committed state: A persisted pet state whose write completed in full, leaving the file complete and internally consistent as written. Committed status is established at write time; integrity validation at read is how a reader confirms it, not what creates it. A state whose write was interrupted is never committed, regardless of what bytes reached disk. Also: committed save, last committed save.
Core pet-simulation function: The set of behaviours the pet cannot exist without — launch, offline-elapsed decay, the four care interactions, mood expression, health progression, persistence and recovery. The scope CON-002’s offline boundary binds; explicitly opt-in extras such as telemetry fall outside it. Also: core loop.
Decay: The reduction of a pet’s stat values over elapsed real time, applied whether or not the application was running. Also: stat decay.
Default pet: The pet state the application initializes when no committed state is available — a pet at health status Healthy, in the Awake state, with every pet stat at its configuration-defined starting value, no sleep-entry timestamp, and no accumulated care or lifecycle history. It is the state FR-010 and FR-012 produce, and the outcome NFR-004’s measure is written to exclude wherever a committed state survived.
Disposition: What the system does with a pet’s accumulated state once that pet has reached the terminal end-of-life status — retain it permanently, archive it, or clear it and start a fresh pet. The undecided subject of Q-2.
Health status: The pet’s position on the neglect progression, distinct from its stat values — Healthy, Sick, or the terminal end-of-life status. Stat values vary gradually as they decay and are restored by care actions; health status is a discrete label that advances only under sustained neglect and is never restored by a single care action. Also: Healthy, Sick.
Idle footprint: The CPU and resident-memory consumption of the application while in the idle steady state. Also: idle budget.
Idle steady state: The application running with the pet alive and the window open, receiving no owner input and with no care action in progress; the operating mode NFR-002’s footprint budget is measured in.
Integrity validation: The check applied to a save file when it is read, to establish that it is complete and internally consistent before its contents are treated as a committed state. A file that cannot be read, is truncated, or fails the check does not pass validation. The mechanism is implementation-defined and depends on the storage format (Q-4).
Last-saved timestamp: The wall-clock timestamp written into a pet state at the moment of its save, dating that write. It is the origin FR-002 measures the offline-elapsed interval from and the field that identifies which committed state a launch restored. Also: last-save timestamp, last committed save’s timestamp.
Local data directory: The single per-platform directory the application owns for its own persisted files; the save file’s expected storage location sits within it, and the quarantine location is a separate location alongside it. The concrete path is platform-specific and is resolved in the platform-adapter layer. Also: application data directory.
Mood expression: The pet’s displayed emotional state, selected by FR-007 from the mood-threshold band containing the pet’s lowest stat value. Distinct from health status — mood expression tracks current stat values and moves freely in both directions with care and decay, whereas health status advances only under sustained neglect.
Mood-threshold band: One of a set of stat-value ranges that determines which mood expression is displayed for the pet at a given moment.
Neglect period: The span of unbroken time a pet must remain in the sick state with at least one pet stat left below its neglect threshold, unremedied, before it reaches the terminal end-of-life status. It is the Sick-to-terminal instance of the sustained-neglect duration. Its numeric value is unfixed pending decay-curve tuning (Q-1). Also: further defined duration.
Neglect threshold: The stat value at or below which a single pet stat counts as neglected, evaluated independently per stat. Crossing it is FR-009’s notification trigger and starts the clock on a sustained-neglect duration; being raised back above it stops that clock for that stat alone. Each stat has its own threshold value, unfixed pending Q-1.
Pet stat: One of exactly three integer-valued care values on a single shared scale — hunger, happiness, and hygiene — each of which decays with elapsed wall-clock time, is raised by its corresponding care action, and has its own neglect threshold. Also: stat, stats.
Pet state: The complete set of values the application persists for a single pet and restores at launch — every pet stat value, the health status, the Awake/Sleeping state field, and the sleep-entry timestamp where the pet is Sleeping, together with the last-saved timestamp that dates the write. It is what FR-001 persists in full, what a committed state contains, and what a default pet is one particular instance of. Also: pet’s state, the current pet state.
Pet-state evaluation: An occasion on which the system reads the current wall clock and re-derives the pet’s state from it — applying elapsed decay, advancing health status, and testing the wake deadline. It occurs at launch and, while the application is running, on the implementation’s own cadence; no requirement in this set fixes that cadence (Q-10). Also: pet-state check, neglect-progression check.
Platform-adapter layer: The single named module that holds every platform-specific behaviour (data directory paths, clock access, native notifications, accessibility integration), so the rest of the codebase stays platform-agnostic.
Quarantine: Moving an unreadable or corrupt save file aside — preserved, not deleted — so a fresh default pet can start without the bad file being retried or silently overwritten. The quarantine location is the separate local storage location the file is moved to. Also: quarantine location.
Reference decay model: An executable specification of the intended decay curve, kept independent of the production implementation and used as the correctness oracle for FR-002 and NFR-001 while the balance values remain open.
Reference machine: The single agreed baseline hardware and OS specification against which idle CPU and memory footprint are measured. Not the owner’s machine — a fixed measurement target so footprint figures are comparable between builds and between candidate runtimes. The specification itself is not yet recorded (Q-5). Also: reference spec.
Reference progression model: The authoritative specification of health-status transitions under sustained neglect — which threshold breaches count, how long each must persist, and the resulting Healthy/Sick/terminal sequence. It is the test oracle for FR-008 and is distinct from the reference decay model, which specifies stat-value curves over elapsed time and says nothing about health status. Also: progression model.
Sleep duration: The span of elapsed wall-clock time, measured from the pet’s sleep-entry timestamp, after which the pet returns to the Awake state. It is FR-011’s entire wake trigger. Its numeric value is unfixed pending Q-1. The interval is computed under the non-positive-interval rule FR-002 applies, and FR-011 additionally re-bases the sleep-entry timestamp to the current time at any evaluation where that interval computes as non-positive, so the deadline is re-anchored rather than deferred.
Sleep-entry timestamp: The wall-clock timestamp recorded when a pet enters the Sleeping state, persisted as part of pet state and used as the origin from which the sleep duration is measured. FR-011 re-bases it to the current time at any evaluation where the interval since it computes as non-positive. It is absent while the pet is Awake. Also: sleep-entry time.
Sleeping state: A discrete pet state entered by the sleep care action and exited when the defined sleep duration has elapsed, distinct from Awake — the pet’s default state, which it occupies at all times other than while sleeping. The Sleeping state does not alter stat decay. Also: Awake, Awake state.
Soft reset: One candidate disposition for a terminal pet — the owner is given a fresh default pet rather than the terminal state being permanent. Named in Q-2 as a possibility under consideration, not as a chosen behaviour.
Stat unit: One increment on the pet’s stat scale — the unit in which NFR-001’s +/-1 decay tolerance is expressed. Applies uniformly to every stat in the pet’s stat set, whose membership and names are fixed by the Pet stat entry.
Sustained-neglect duration: The span of unbroken time at least one pet stat must remain below its neglect threshold before health status advances one step. Two instances exist — Healthy to Sick, and Sick to the terminal end-of-life status (the latter is the Neglect period). Both values are unfixed pending Q-1.
Terminal end-of-life status: The final health status a pet reaches after sustained unremedied neglect, at the end of the Healthy to Sick to terminal progression. Named neutrally because what follows it — permanence or a soft reset — is an open product question (Q-2) that no requirement in this set answers. Also: terminal status, death.

Assumptions

A-1: A single local desktop owner per installation. No multi-user, account, server, or operator role applies anywhere in the set.
A-2: The pet has exactly three care stats — hunger, happiness and hygiene — each integer-valued on a single shared scale, bounded to a defined min/max, and raised by its corresponding care action by a fixed configuration-defined increment capped at the maximum. The source context named four interactions and “stat thresholds” generically but never named the stats or their mapping to actions.
A-3: Quarantining an unreadable save file means moving or renaming it to a separate local location, not deleting it, so it stays available for diagnosis and cannot collide with the newly written default-pet save.
A-4: A colorblind-safe palette plus shape and text redundancy is sufficient for v1; a user-tunable palette is out of scope, so no requirement demands one.
A-5: The reference decay model and all balance values are placeholders pending Q-1, and are referenced as an oracle rather than hardcoded in any requirement.
A-6: A non-positive elapsed interval between two wall-clock readings is handled by one of two rules depending on what the interval feeds. Where it drives a quantity it is clamped to zero elapsed time (FR-002, for decay). Where it drives a deadline the origin timestamp is additionally re-based to the current time (FR-011, for the wake deadline), because clamping alone defers a deadline without bound rather than bounding it.
A-7: The platform exposes a wall clock whose backward movement is observable to the application as a non-positive interval, rather than silently smoothing it into a slow-forward clock. Both rules in A-6 trigger on observing that non-positive interval, so an OS that smooths defeats both.
A-8: The pet leaves the Sleeping state on elapsed sleep duration rather than by an owner-initiated wake action. The source context fixes the interaction set at four actions and says nothing about how sleep ends; a fifth owner action would exceed that set.
A-9: The mood display reduces the three stats to a single band by taking the lowest stat value. The source context states no reduction rule; FR-007 fixes it normatively because a mean would let one critically low stat hide behind healthy ones.
A-10: Neglect progression is driven by at least one stat below its own threshold, not by all stats simultaneously. Inferred from the per-stat threshold semantics in FR-009 and carried consistently into FR-008 and BR-001.
A-11: The source context’s 200 fault-injection trials are apportioned as 100 missing-save and 100 corrupted-save trials — a partition, not a duplication, so neither FR-010 nor FR-012 over-claims the original budget.
A-12: Energy is not a pet stat. No requirement reads or writes it; it was vestigial vocabulary and has been removed rather than justified by inventing energy-consumption and energy-restoration rules.
A-13: CON-001’s 40% headroom allowance is an engineering judgement, not a stated or measured figure. It exists because a screen with no allowance would admit a shell consuming almost the whole budget while empty, making NFR-002 unachievable before any pet code is written. To be re-derived against real measurement once Q-4 and Q-5 close.
A-14: NFR-009’s 250 ms p95 budget assumes a whole launch should land inside roughly one second to read as uninterrupted, and that decay should be a minor share of that. The apportionment is reasoned, not elicited; if a total launch budget is ever stated, the figure should be re-derived from it.
A-15: NFR-004’s discriminating measure assumes single-generation retention is sufficient, because atomic commit means an interrupted write never replaces the already-committed file. Residual gap — a file validly committed and damaged afterwards by media- or filesystem-level corruption has no prior generation and resolves to quarantine plus a default pet. Tracked as Q-9.
A-16: NFR-008’s 5x scaling ratio is calibrated against a tick-loop failure mode, which at 30-day-versus-1-hour arms would show roughly 720x. The 5x ceiling is a deliberately generous band that rejects that shape without over-constraining a closed-form implementation carrying fixed per-call overhead.
A-17: The offline-decay computation is reachable as an independently invocable unit — a function from starting pet state and elapsed interval to decayed pet state — separately from the launch sequence that calls it. NFR-008’s measure is only executable if it can be called and repeated without starting the application. A testability constraint on the design, cheap to honour, but an assumption rather than a given.
A-18: NFR-008’s measure is assumed to run under a harness-level wall-clock timeout. A tick-loop implementation makes the measurement slow rather than failing, so a timeout converts that runtime blowup into a prompt failure signal. A harness-construction concern, not a change to the requirement.
A-19: Care reminders delivered through the host operating system’s local notification service count as fully offline and do not violate CON-002, even where that OS service can deliver over a network for other applications.
A-20: Telemetry the owner has explicitly opted into falls outside core pet-simulation function and is therefore not a CON-002 violation. The offline boundary binds the core loop, not an opt-in extra.
A-21: Each target platform provides a usable native notification API and a native accessibility API, so no target needs a bespoke assistive-technology implementation.
A-22: The Pet state glossary entry is the single maintained enumeration of what the application persists. FR-001’s completeness property (“0 fields absent”) is decidable only against it, which makes the glossary normative rather than explanatory — a requirement introducing a new persisted field updates that entry rather than every fit criterion that would otherwise enumerate.
A-23: A pet-state evaluation occurs while the application is running, on the implementation’s own cadence. FR-007’s mood update, FR-008’s neglect progression and FR-011’s wake all presuppose one, and no requirement asserts or bounds it. Tracked as Q-10.
A-24: The old set’s cap on decay at “the configured maximum offline interval” is not carried forward into this set. Its stated rationale — “uncapped decay over very long absences would guarantee death regardless of intent” — does not transfer to this set’s neglect model. Decay magnitude is already scale-bounded independent of any cap (A-2’s min/max bound on every pet stat, reinforced by FR-002 AC-2’s requirement that even a 30-day interval decay without error or overflow), and health-status progression toward the terminal status is driven by sustained below-threshold duration per stat (FR-008), not by accumulated decay magnitude — so a magnitude cap would not change whether or when an absence reaches the terminal status. A long, closed-app absence in which a stat crosses its neglect threshold and stays unremedied for the defined duration is exactly the “sustained, unremedied neglect” BR-001 already treats as legitimate causation, as distinct from the “elapsed time alone” cause BR-001 rules out; capping decay would not prevent that outcome, and reinstating a cap purely to blunt it would work against BR-001’s own rationale for why the terminal status must carry real stakes. Residual concern about unbounded computation cost over very long intervals is covered separately by NFR-008’s scaling bound and the closed-form assumption (A-16, A-18), not by a decay cap. Whether offline elapsed time is reconstructed retrospectively against the neglect-duration clock, versus accruing only while the app is running, is a detail of the pet-state-evaluation mechanism already tracked at Q-10, not a separate gap.

Dependencies

D-1: A reference decay model must exist as an executable oracle independent of the production implementation — stat curves over elapsed time, the oracle for FR-002 and NFR-001.
D-2: A reference progression model must exist as a separate executable oracle — health-status transitions under sustained neglect, the oracle for FR-008. Distinct from D-1, which says nothing about health status.
D-3: Platform-native accessibility stacks and screen readers (UI Automation/NVDA on Windows, NSAccessibility/VoiceOver on macOS, AT-SPI/Orca on Linux) are required to verify NFR-003 on each target.
D-4: An OS-level network capture facility is required to verify NFR-005’s zero-outbound-connection assertion.
D-5: A fault-injection harness able to kill the process at randomized points, including mid-write, is required for NFR-004, FR-010 and FR-012.
D-6: CI runners for all three desktop operating systems are required for NFR-006’s “passes unmodified on all three” measure.
D-7: OS per-process CPU and RSS accounting is required to verify NFR-002.
D-8: An automated accessibility scanner appropriate to the eventual UI technology is required for NFR-003’s zero-critical-violations measure; the choice depends on the still-open runtime decision (Q-4).
D-9: A recorded reference-machine specification (Q-5) is a hard precondition for verifying NFR-002’s and NFR-009’s absolute figures, and CON-001’s exclusion screen inherits it. NFR-008 deliberately does not depend on Q-5 and is the only time-behaviour target executable before it closes.
D-10: CON-001 makes Q-4 (runtime selection) unresolvable until Q-5 (reference machine) is answered, since no candidate may be recorded as passing or failing the exclusion screen before then. A scheduling dependency between two engineering-owned questions, surfaced rather than resolved.
D-11: Q-1 supplies every balance value the set defers — the feed/play/clean increments, the mood-threshold band boundaries, each stat’s own neglect threshold, both sustained-neglect durations (Healthy-to-Sick and Sick-to-terminal), and the sleep duration. Every fit criterion referencing a “defined” value is unconstructible until Q-1 lands.
D-12: Neither BR-001 nor BR-002 can leave low confidence until product resolves Q-2. BR-002 is scoped explicitly to the interim and should be revisited — replaced or retired — the moment Q-2 lands.
D-13: Q-3 fixes the v1 test-matrix and acceptance scope. CON-003’s design boundary holds regardless of the answer.
D-14: Q-4 fixes the concrete local-storage mechanism and file format underlying FR-001, FR-012 and the Integrity validation definition.
D-15: Q-7 is the tracking artifact for the Maintainability deferral. Until it is answered the set carries no explicit modularity or modifiability target beyond NFR-006’s platform-seam measure and NFR-007’s analysability support.
D-16: CON-002 and CON-003 together depend on each target platform exposing a local notification service and an assistive-technology API that function with no network connection. Believed true of all three; not verified, Linux desktop environments especially.

Open Questions

Q-1: What is the exact decay-curve and balance tuning — rates, thresholds, increments, both sustained-neglect durations, and the sleep duration? (owner: product/design)
Q-2: Is the terminal end-of-life status permanent, or a configurable soft reset? No requirement in this set answers it; FR-008, BR-001 and BR-002 all deliberately decline to. A candidate constraint on the answer, recorded but not asserted: whether a disposition must be surfaced to the owner. (owner: product)
Q-3: Which platforms ship in v1 — all three, or Windows-first? (owner: product)
Q-4: Which framework/runtime is chosen given the footprint constraint (Electron vs Tauri vs native)? Note D-10 — this cannot be closed before Q-5. (owner: engineering)
Q-5: What is the reference-machine specification against which the idle-footprint budget and launch-latency figures are measured? Surfaced by the critique; NFR-002, NFR-009 and CON-001 all name it normatively and none can be executed until it is recorded. (owner: engineering)
Q-6: What are the release, auto-update and rollback strategies for desktop distribution? Recorded as a deferral rather than an inapplicability, and the tracking artifact for the Deployability gap. (owner: engineering)
Q-7: Should v1 carry explicit maintainability targets (modularity / modifiability), given that Q-1’s decay-balance tuning is a live, ongoing loop? (owner: engineering)
Q-8: Should the Sleeping state be rendered to the owner? Sleep is currently owner-imperceptible across the whole set — FR-006 is authored honestly on that basis and held at low confidence. (owner: product)
Q-9: Should committed saves be retained for two generations, to survive post-commit media corruption? See A-15 — the residual gap NFR-004 does not claim to cover. (owner: engineering)
Q-10: How often does the running application re-evaluate pet state, and what bounds that interval? Nothing in the set establishes that a pet-state evaluation occurs while the application is running — FR-007, FR-008 and FR-011 all presuppose one; none asserts one exists or bounds its cadence. FR-011’s backward-clock bound is therefore relative to an event of unbounded arrival, so “bounded, and never stranded” is only as strong as a cadence no requirement fixes. Not raised as a defect against FR-011: the gap sits identically under FR-011 AC-1/AC-2 and FR-008, so amending FR-011 would repair one of three sites. NFR-002’s idle-CPU budget constrains the cadence from the other side. (owner: engineering)

Recommendations recorded, not authored

R-1: Two-generation retention of committed saves (tracked as Q-9). NFR-004’s measure is satisfiable by atomic commit alone and does not cover a file committed validly then damaged by media-level corruption. Not a hole in BR-002 — BR-002 forbids the system discarding state, and a failing disk is not the system acting. Stands on cost/benefit; needs a functional home plus an FR-012 fallback clause.
R-2: Owner visibility of a terminal-pet disposition. Deliberately removed from BR-002’s normative statement because requiring it would pre-commit Q-2 — it would rule out a silent soft reset, which Q-2 may legitimately choose. Recorded as a candidate constraint on Q-2’s answer.
R-3: A set-wide wall-clock interval rule. Would need to carry BOTH rules in A-6 plus a discriminator (clamp where the interval feeds a quantity whose non-advance is safe; re-base the origin where it feeds a deadline whose non-arrival is the hazard). A clamp-only set-wide rule would have propagated FR-011’s defect to every future deadline. Not proposed as an artifact — it needs a home nothing in the current set provides.
R-4: FR-001 fit-criterion wording. “Equal to their pre-close values” is measured at restore, before launch-time decay (FR-002) and wake re-evaluation (FR-011) are applied — the only reading under which FR-001 and FR-002 have ever been consistent. The critic judged this not a defect and explicitly directed that no revise round be spawned for it. If FR-001 is ever reopened, fold in “as restored, before launch-time decay and wake evaluation are applied”.