Pet epics

Document version	Date	Summary
v7	2026-07-24	Archive the completed v0.2.0 epics and open the next release map
v8	2026-07-25	Define the v0.3.0 embedded firmware foundation and project UX epics
v9	2026-07-25	Add v0.3.0 release verification and hardening as the final epic
v10	2026-07-27	Complete E17 after accepting the v0.3.0 architecture and release scope
v11	2026-07-27	Record completion of E18, E19, and E20
v12	2026-07-27	Clarify the T-Display family and selected S3 variant contract
v13	2026-07-28	Record completion of E21
v14	2026-07-28	Record completion of E22
v15	2026-08-01	Archive the completed v0.3.0 epics and open the next release map
v16	2026-08-02	Define the v0.4.0 local persistence foundation epics
v17	2026-08-03	Bring the wall-clock stamp and bounded absence into v0.4.0 scope

Status: Draft

Current release: v0.4.0

Related documents: Product specification, milestones, general architecture, and the release archives for v0.1.0, v0.2.0, and v0.3.0.

1. Purpose

This document defines the product and engineering outcomes required by each epic.

An epic belongs to one release and contains multiple PBIs. An epic describes a verifiable outcome rather than a source directory, implementation phase, or team activity.

Epic identifiers are permanent and are not reused. Future releases continue the sequence instead of restarting at E01.

2. Epic completion rules

An epic is completed only when:

all child PBIs are completed
all epic completion criteria are satisfied
required tests pass
accepted architecture decisions are reflected in code and documentation
new limitations are recorded in known-limitations.md
deferred defects are recorded in bugs.md
architecture deviations are documented
verified support claims are not broader than the available evidence

An epic must not be marked completed because its main implementation exists while tests or required documentation remain unfinished.

3. Archived releases

Completed v0.1.0 epics are archived in release v0.1.0. That archive holds E01 through E07 with their full outcomes, scope, and completion criteria.

Completed v0.2.0 epics are archived in release v0.2.0. That archive holds E08 through E16 with their full outcomes, scope, and completion criteria.

Completed v0.3.0 epics are archived in release v0.3.0. That archive holds E17 through E23 with their full outcomes, scope, and completion criteria.

Epic identifiers continue from E24. They are permanent and are not reused, so a future release never restarts the sequence.

4. Release v0.4.0 epic map

Epic	Title	Status	Primary outcome
`E24`	v0.4.0 architecture and release scope	Completed	The save format, validation, storage boundary, host policy, and support-claim limits for v0.4.0 are documented and accepted
`E25`	Core save format and encoder	Completed	Pet Core encodes a world into a versioned, integrity-checked payload in caller-owned storage without naming a platform interface
`E26`	Core load validation and restore	Completed	Pet Core accepts a valid payload and rejects every malformed one without touching the destination world
`E27`	Storage boundary and desktop implementation	Completed	A frontend-neutral storage contract carries payloads to and from a platform, with a hosted implementation and a test double over it
`E28`	Application persistence options	Completed	The desktop and headless applications save and restore a world when an operator supplies a path, and report failures through the existing diagnostic contract
`E29`	Release verification and hardening	Completed	The release meets its round-trip, rejection, allocation, boundary, limitation, and support-claim evidence requirements

The release goal and expected capabilities are recorded in milestones. The concrete architecture is recorded in architecture for v0.4.0. PBIs for this release start at PBI-086.

4.1 Dependency view

flowchart TD
    E24[E24 Architecture and scope]
    E25[E25 Save format and encoder]
    E26[E26 Load validation and restore]
    E27[E27 Storage boundary]
    E28[E28 Application options]
    E29[E29 Release verification]

    E24 --> E25
    E24 --> E26
    E24 --> E27
    E24 --> E28
    E24 --> E29
    E25 --> E26
    E26 --> E28
    E27 --> E28
    E25 --> E29
    E26 --> E29
    E27 --> E29
    E28 --> E29

E25 comes before E26 because the encoder settles the byte layout that the decoder validates against, and a decoder written first would be validating a format that does not exist yet. E27 depends only on E24 because the storage contract carries bytes without interpreting them, so it needs the architecture boundary rather than the format. E28 depends on both E26 and E27 because an application option is the first place where a payload and a platform meet. E29 is the release-level convergence point.

Testing is not deferred to E29. Every implementation epic includes its own tests and evidence. E29 adds release-level integration, the final gates, the support-claim review, the limitation status review, and documentation hardening.

5. E24: v0.4.0 architecture and release scope [+]

Release: v0.4.0

Status: Completed

Dependencies: None

5.1 Outcome

The release architecture defines the save payload format, the validation rules, the ownership split between Core and storage, the host policy for when persistence happens, the compatibility promise for the first format version, and the support-claim limits for v0.4.0.

The result is an accepted implementation plan that can guide PBIs without letting a file format, a platform file interface, or a convenience feature define Core behaviour.

5.2 In scope

arch-v0.4.0.md
the save payload format and its version identity
the validation rules and the rejection order
the Core and storage ownership split
the storage contract boundary
the host policy that persistence is operator-driven
the compatibility promise for format version 1
the wall-clock stamp and the bounded absence semantics
embedded storage claim limits

5.3 Out of scope

implementing the encoder, the decoder, or the storage component
implementing application options
implementing a non-volatile storage path
deciding a second format version
identity, maturity, adapter, and networking work

5.4 Completion criteria

arch-v0.4.0.md exists and follows the version architecture policy
the format table, the validation rules, and the rejection order are recorded
the Core, storage, and host responsibilities are separated without overlap
the compatibility promise for format version 1 is stated rather than implied
the treatment of time spent outside the process is decided and recorded with its reason
a host with no absolute time source stays supported by the decided treatment
the support matrix distinguishes hosted file evidence from embedded and device evidence
open decisions are named for PBI or later-release resolution

5.5 Traceability

SPEC-FR-037: local persistence
SPEC-FR-038: state validation
SPEC-FR-039: format identification
SPEC-FR-042: device independent identity
SPEC-NFR-006: maintainability
SPEC-FR-015: session continuity
SPEC-FR-016: safe clock anomalies
SPEC-NFR-007: compatibility awareness
LIM-014: what an absence does not yet change beyond the world clock
ADR-012: the wall-clock stamp and the bounded absence
arch-v0.4.0: sections 1, 2, 4, 5, 8, 9, 10, and 11

6. E25: Core save format and encoder [+]

Release: v0.4.0

Status: Completed

Dependencies: E24

6.1 Outcome

Pet Core turns a valid world into a complete payload in caller-owned storage, using an explicit little-endian encoding that no compiler layout decision can reach.

The result is the durable artefact of this release. Every later reader, on any platform, reads what this epic defines.

6.2 In scope

include/pet/save.h and its implementation
PET_SAVE_FORMAT_VERSION and PET_SAVE_CAPACITY
the magic value, the header, the field order, and the field widths
the wall-clock save stamp field and its unknown value
the integrity check over the payload
pet_world_save with capacity, null, and invalid-world handling
an ADR for the format, the integrity check, and the compatibility promise
encoder tests over the complete supported state

6.3 Out of scope

decoding and validating a payload
any file, path, stream, or platform interface
a second format version and any migration behaviour
deriving, correcting, or validating the wall-clock stamp the host supplies
compressing, encrypting, or signing a payload

6.4 Completion criteria

a world is encoded field by field, with no structure storage copied into the payload
the payload carries the magic value, the format version, and the integrity check
every payload of format version 1 has the same documented length
a capacity below that length is rejected before anything is written
an invalid source world is rejected and produces no payload
the operation performs no dynamic allocation and retains no caller pointer
the encoder matches the format table in the version architecture
the format decision is recorded in an ADR

6.5 Traceability

SPEC-FR-037: local persistence
SPEC-FR-039: format identification
SPEC-NFR-001: portability
SPEC-NFR-002: resource awareness
arch-v0.4.0: sections 5.2, 8.3, and 8.4

7. E26: Core load validation and restore [+]

Release: v0.4.0

Status: Completed

Dependencies: E24, E25

7.1 Outcome

Pet Core accepts a payload only when every structural and semantic rule holds, and a rejected payload leaves the destination world byte for byte unchanged.

The result is the guarantee that makes persistence safe to build on. A restored world is either the world that was saved or no change at all.

7.2 In scope

pet_world_load and the decoder
the rejection order for magic, version, length, integrity, fields, and world invariants
the bounded absence derived from the two wall-clock values
building and validating a candidate world before assignment
deriving the initialised marker rather than decoding it
deterministic round-trip tests over the complete supported state
rejection tests over every documented failure class
the public error surface for an unsupported format version

7.3 Out of scope

reading a payload from anywhere
accepting a format version other than the first
repairing, migrating, or partially accepting a payload
reporting platform failures

7.4 Completion criteria

7.5 Traceability

SPEC-FR-037: local persistence
SPEC-FR-038: state validation
SPEC-FR-015: session continuity
SPEC-FR-016: safe clock anomalies
SPEC-NFR-002: resource awareness
SPEC-NFR-004: robustness
ADR-012: the wall-clock stamp and the bounded absence
arch-v0.4.0: sections 5.2, 6.2, 6.3, 8.1, and 8.3

8. E27: Storage boundary and desktop implementation [+]

Release: v0.4.0

Status: Completed

Dependencies: E24

8.1 Outcome

A frontend-neutral storage contract carries a payload to and from a platform without inspecting it, with a hosted implementation over the standard C file operations and a test double over memory.

The result is the boundary a later non-volatile implementation fills without redesigning anything above it.

8.2 In scope

components/storage with its contract header and build file
the read and write operations and their outcome values
pet_storage_stdio under the PET_STORAGE_STDIO build selection, off for cross builds
writing through a temporary file beside the target followed by replacement
a TODO comment carrying the technical reason wherever an unverified platform path remains
the memory test double and contract tests over it
implementation tests including replacement and a failed write
embedded build evidence for the contract with no implementation selected
an ADR for the write and replacement strategy
correcting the stale @file path in components/assets/src/desktop/reader_stdio.c

8.3 Out of scope

interpreting, validating, or repairing a payload
choosing a location, a file name, or a discovery rule
a non-volatile or embedded implementation
a remove or exists operation without a host that needs one
concurrent access, locking, and multi-process safety

8.4 Completion criteria

the contract carries bytes without inspecting them and owns no format knowledge
the hosted implementation is a build selection that defaults off for a cross build
a write does not modify the target until a complete temporary file exists
a failed write leaves any previous payload intact
the unverified replacement fallback is marked with a TODO carrying its reason
the memory double satisfies the same contract tests as the hosted implementation
the embedded build compiles the contract with no implementation selected
the write and replacement decision is recorded in an ADR

8.5 Traceability

SPEC-FR-037: local persistence
SPEC-NFR-001: portability
SPEC-NFR-003: testability
SPEC-NFR-006: maintainability
arch-v0.4.0: sections 5.3, 5.4, 5.5, 8.7, and 8.9

9. E28: Application persistence options [+]

Release: v0.4.0

Status: Completed

Dependencies: E24, E26, E27

9.1 Outcome

The desktop and headless applications restore a world before a run and save one after it, but only when an operator supplies a path.

The result is the first end-to-end persistence evidence, produced without giving a reference application a session continuity policy that the real product frontend has not decided yet.

9.2 In scope

explicit load and save options on both applications
argument parsing in the headless application, which has none today
a load that replaces initialisation rather than following it
failure reporting through the existing app diagnostic ranges
a process-level round trip used as release evidence
option parsing and diagnostic mapping tests

9.3 Out of scope

automatic load, automatic save, and periodic autosave
a default path, an implied file name, and any discovery rule
prompting, recovery flows, and user-facing error text beyond the diagnostic contract
persistence in the firmware application
changes to the SDL frontend

9.4 Completion criteria

neither application reads or writes a payload when its option is absent
a requested load that cannot be satisfied is a startup failure rather than a silent new world
a restored world replaces initialisation rather than overwriting an initialised world
save and load failures map to the documented diagnostic ranges
a headless run that saves and a later run that loads report the same state
the desktop application still starts a new world when no option is supplied
no default save location is introduced

9.5 Traceability

SPEC-FR-037: local persistence
SPEC-NFR-003: testability
SPEC-NFR-004: robustness
arch-v0.4.0: sections 5.6, 6.4, 8.5, and 8.11

10. E29: Release verification and hardening [+]

Release: v0.4.0

Status: Completed

Dependencies: E24, E25, E26, E27, E28

10.1 Outcome

The release is verified as a whole, its evidence is recorded, and every claim it makes is bounded by what was actually run.

10.2 In scope

the audit gate over the supported compositions from a clean tree
allocation probe coverage over the enlarged public surface
the Core symbol scan against file and allocation dependencies
include and embedded boundary checks over the new component
the ESP-IDF build with the storage contract compiled and no implementation selected
new limitations for embedded storage, absent time handling, and session continuity
the support matrix and the release evidence file
documentation hardening across the architecture, limitations, and version records

10.3 Out of scope

new product behaviour
new platform support
unrelated refactoring
resolving limitations that the release did not own

10.4 Completion criteria

the audit gate passes from a clean tree over the headless and desktop compositions
the allocation probe exercises both new public operations and reports no allocation
the Core archive names no file or allocation dependency
the embedded build compiles the storage contract with no implementation selected
the process-level round trip is recorded as release evidence
new limitations are recorded with owners and linked to future work
support claims match executed evidence and no Windows claim changes
the version architecture reflects the implemented system
all v0.4.0 exit criteria in milestones are satisfied

10.5 Traceability

SPEC-NFR-002: resource awareness
SPEC-NFR-004: robustness
SPEC-NFR-007: compatibility awareness
LIM-003: allocation probe depth
LIM-013: embedded asset storage, as the neighbouring embedded gap
arch-v0.4.0: sections 7.2, 8.8, 10, and 11

11. Crosscutting rules

The following rules apply to every epic:

code and developer documentation use British English
Core code uses ISO C99
public domain identifiers use the pet prefix
no hidden global mutable world is introduced
time and randomness remain explicit
tests are implemented with the behaviour they verify
invalid public input must not partially mutate authoritative state
no frontend, adapter, storage, or networking dependency enters the Core
implementation remains within the assigned epic and PBI scope
deferred work is recorded instead of being hidden in comments

12. PBI preparation rules

The next planning document is 03-pbis.md.

PBIs derived from these epics must:

belong to exactly one epic
produce one reviewable outcome
include explicit in scope and out of scope boundaries
include testable acceptance criteria
identify dependencies
link to relevant architecture sections
identify required verification commands or evidence
avoid combining implementation, unrelated refactoring, and future feature work

A PBI set should cover its epic completely before later epic implementation PBIs are marked ready.

my little airport =)

Explorer

Pet epics

1. Purpose

2. Epic completion rules

3. Archived releases

4. Release v0.4.0 epic map

4.1 Dependency view

5. E24: v0.4.0 architecture and release scope [+]

5.1 Outcome

5.2 In scope

5.3 Out of scope

5.4 Completion criteria

5.5 Traceability

6. E25: Core save format and encoder [+]

6.1 Outcome

6.2 In scope

6.3 Out of scope

6.4 Completion criteria

6.5 Traceability

7. E26: Core load validation and restore [+]

7.1 Outcome

7.2 In scope

7.3 Out of scope

7.4 Completion criteria

7.5 Traceability

8. E27: Storage boundary and desktop implementation [+]

8.1 Outcome

8.2 In scope

8.3 Out of scope

8.4 Completion criteria

8.5 Traceability

9. E28: Application persistence options [+]

9.1 Outcome

9.2 In scope

9.3 Out of scope

9.4 Completion criteria

9.5 Traceability

10. E29: Release verification and hardening [+]

10.1 Outcome

10.2 In scope

10.3 Out of scope

10.4 Completion criteria

10.5 Traceability

11. Crosscutting rules

12. PBI preparation rules

13. References

Graph View

Table of Contents