tines/docs/superpowers/plans/2026-10-20-tines-core-1-0.md

# tines-core 1.0 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Ship `tines-core` 1.0.0: a versioned wire format, a frozen minimal public API, a settled `Store` trait, a reserved signature slot, and evidence (fuzzing, pinned vectors, MSRV, semver-checks) that the untrusted-input and compatibility promises hold.

**Architecture:** 1.0 adds nothing to the exchange's behaviour; it removes, hides, pins, documents and reserves. Two wire-format changes (a version byte, then the `Observation` reshape) plus a `Store` trait extension and four core-hardening fixes, each landed as an independently green, committed task on top of `master` (`aedb802`).

**Tech Stack:** Rust 2021, `#![no_std]` + optional `alloc`, `postcard`, `heapless`, `blake2`, `serde`, `proptest`, cargo-fuzz (nightly), cargo-msrv, cargo-semver-checks.

**Spec:** `docs/superpowers/specs/2026-10-18-tines-1-0-design.md` (approved; decisions F and G added 2026-10-20, G amended after review) — the plan argues from the spec, so the spec travels with it; executors read both. Review: `HANDOFF.md`.

## Global Constraints

Every task's requirements implicitly include this section.

- `tines-core` stays `#![no_std]`; `alloc` an optional default-on feature; `--no-default-features` builds for `thumbv7em-none-eabihf`. No async/threads/I/O/panics on untrusted input; wire frames are untrusted, malformed bytes become `Err`/a counted drop, never a panic.
- `Addr` is never mapped to `NodeId` by core.
- **Identity hash never changes**: `id()` reads `dest.map(|d| d.to)` and is byte-for-byte the 0.x hash; the pinned vector (below) carries over unchanged. `sig` is excluded from the id.
- Exact values: `MAX_TOPIC=64`, `MAX_PAYLOAD=1024`, `MAX_PEERS=8`, `SUMMARY_BYTES=512`, `BLOOM_K=3`, `SUMMARY_INTERVAL_MS=2000`, `REASSEMBLY_TIMEOUT_MS=5000`, `SEND_QUEUE_CAP=256`, `MAX_FRAME=1500`, `ACK_IDS_CAP=90`, `EVENT_QUEUE_CAP=64`, `BCAST_SENT_CAP=256`, `ACK_BUFFER_CAP=256`, `MAX_SIG=64`, `MAX_FRAGMENTS=64` (pub(crate)), `FRAG_OVERHEAD` (currently 64, becomes 65 in Task 1, private in Task 5), `SUMMARY_OVERHEAD` (private, currently 24, becomes 25 in Task 1).
- Decisions already made (do not reopen): D1 reserve signature slot; D2 `Dest` replaces `to`+`lifetime_ms`; D3 drop-and-report; D4 only `tines-core` goes 1.0; D5 no store migration (old logs refused, wiped); Q1 `MAX_SIG=64`; Q2 coverage = whole observation + `version`+`algo`; Q3 malformed reported like version mismatch; R1 drop reports carry transport `Addr`; R2 drops counted by `(Addr, reason)`, not queued; R3 `MAX_FRAME=1500` stays; R4 `observed_at` = observer's wall-clock ms since Unix epoch; F `Store::flush` + `Node::flush(now)` replaces `store_mut`; G age across downtime via a wall-clock marker, **as amended twice on 2026-10-20**: the store opens *before* trusted time (`LogStore::open(path, now)`, unchanged), with everything already in the log **quarantined** until `LogStore::set_wall_clock(wall_now: u64, now)` runs the downtime fold. Trusted time comes from the robot's own RTC/GPS, else from a peer's observation (`observed_at + age_ms`, smallest `age_ms` wins), else the robot's own fail-safe (outside tines). The marker's wall time is derived (`wall_at_set + (now − tick_at_set)`). This supersedes "open only once trusted time exists".
- `tines-ros2` is not in the default gate (its `ros2` feature is off); verify any change touching `tines-ros2` with `docker build -f Dockerfile.ros2 -t tines-ros2-check .` (cached image exists).
- **Gate:** run `sh scripts/ci.sh` verbatim and require it green at every commit — it runs `cargo fmt --all -- --check`, then clippy/doc/test for the whole workspace, then the no-`alloc` clippy/doc/test matrix for `tines-core` (`sh scripts/check-no-std.sh`). Do not substitute the individual steps for the script.
- House rule: primary branch is `master`; land by rebase + fast-forward. Commit messages use the conventional prefix shown in each task; license Apache-2.0, copyright "K. Isom".
- Execution: local `ornith-1.5-35b-a3b` subagents, reviews run sequentially (single-GPU llama-server). When a task touches `tines-ros2`, its final step is the Docker build, not a plain `cargo check`.

## Review Focus

The six failure modes the spec implies but no single task's tests exercise, most likely to bite first:

1. **A frame with the wrong version byte** (un-updated or foreign peer) must be dropped *and reported* as `VersionMismatch { version }`, never silently swallowed and never folded into `Malformed`. An *empty* frame is `Malformed` (there is no version to mismatch). → pinned in Task 2.
2. **A frame whose `from` changes within one contact** must be dropped as `IdentityChanged` and the peer's addressed mail must *not* be handed over to the new identity. → pinned in Task 9.
3. **A signature with an unknown algorithm id, or the wrong length for a known one** — the first must be carried and forwarded untouched; the second (and `algo = 0` and `version = 0`) is `Malformed`, including when the observation is rebuilt from fragments. → pinned in Task 4.
4. **Held data must not leak before the fold, and unknown downtime must take the safe path.**
   - Before `set_wall_clock`, a quarantined observation must not appear in a summary, a custody offer or a belief, and a quarantined addressed duplicate must not be acked.
   - When the downtime is unknown (no marker, a marker without wall time, or a wall clock that went backwards), held addressed messages expire (a directive that may have outlived `lifetime_ms` is never delivered), and held broadcasts are floored at `unknown_downtime_age_ms`. Neither is delivered as-is.
   - → pinned in Task 10.
5. **A valid frame with trailing bytes** must be rejected as `Malformed` (canonical decode), and a frame whose decode finds the `from` field missing must not panic. → pinned in Task 9.
6. **Every frame must fit `mtu()`** after the +1 version byte and the +67-byte signature — swept across MTUs from the BLE floor (`MIN_MTU = 23`) to `MAX_FRAME`, with an oversized observation given up cleanly as `TooLarge`, never sent truncated. → pinned in Task 4.

---

## File Map (decomposition locked in)

- `tines-core/src/wire.rs` — envelope encode/decode, `frame_sender`; `Frame`/`WireError` become private in Task 5.
- `tines-core/src/observation.rs` — `Observation`, `Dest`, `Signature`, `SigAlgo`, `NodeId`, `ObservationId`, `Tick`, `Topic`, `Payload`.
- `tines-core/src/consts.rs` — `WIRE_VERSION` + the wire/local split.
- `tines-core/src/exchange.rs` — drop counters, `NodeEvent`, peer pinning, hardening. Stays private (`pub(crate)` from Task 5).
- `tines-core/src/node.rs` — `Node` facade: `flush(now)`, `drain_events -> NodeEvent`.
- `tines-core/src/store.rs` — `Store` trait: `is_empty`, `flush`; the `store_conformance` module.
- `tines-core/src/lib.rs` — the 1.0 public surface + `#![deny(missing_docs)]`.
- `tines-core/tests/vectors.rs` — pinned identity + golden wire vectors.
- `tines-store/src/log.rs` — format v2 + wall-clock marker + quarantine + `set_wall_clock` downtime fold.
- `tines-sim/src/capped.rs` — the `CappedStore` wrapper (every `Store` change goes through it).
- `tines/src/ipc.rs`, `tines-ros2/src/node.rs` — host consumers of `NodeEvent`/`flush`/`observed_at`.
- `tines-bt/src/transport.rs` — `frame_sender` import site.
- `fuzz/` — cargo-fuzz target (outside the workspace).

---

### Task 1: Wire envelope — `WIRE_VERSION` byte

**Files:**
- Modify: `tines-core/src/consts.rs` (add `WIRE_VERSION`)
- Modify: `tines-core/src/wire.rs` (encode/decode prepend+check the byte; `frame_sender` becomes version-aware; update the golden Summary vector; keep the pre-change Summary bytes as a 0.x-rejection vector)
- Modify: `tines-core/src/exchange.rs` (`SUMMARY_OVERHEAD` 24 → 25)
- Modify: `tines-core/src/frag.rs` (`FRAG_OVERHEAD` 64 → 65)
- Modify: `tines-bt/tests/transport.rs`, `tines-bt/tests/adv.rs` (the `frame(from, payload)` helpers prepend `WIRE_VERSION`)

**Interfaces:**
- Produces: `pub const WIRE_VERSION: u8 = 4;` (decided: 4 is the first value in 4–0x7F, a single-byte postcard tag, ≥ the 0.x tags 0–3); `WireError` gains `VersionMismatch { version: u8 }`; `frame_sender(bytes: &[u8]) -> Option<NodeId>` now skips *two* leading bytes (version + variant tag) and returns `None` when `bytes[0] != WIRE_VERSION`.

- [ ] **Step 1: Write the failing tests**

In `tines-core/src/wire.rs` (mod tests): `encode_prepends_version_byte` (encode a Summary, assert `buf[0] == WIRE_VERSION` *and* `Frame::decode(&buf[..n])` round-trips — do **not** decode `&buf[1..]`, which is missing the version byte); `decode_wrong_version_is_mismatch` (a frame with `buf[0] = WIRE_VERSION + 1` returns `Err(WireError::VersionMismatch { version })`); `decode_empty_is_malformed` (`Frame::decode(&[])` returns `Err(WireError::Malformed)`, not a panic and not `VersionMismatch { version: 0 }`); `rejects_0x_frame` (the pre-change 0.x Summary golden bytes — captured from the current `summary_golden_vector` literal before editing it — are rejected as `VersionMismatch { version: 0 }`); `frame_sender_skips_version_and_tag` (bytes `[WIRE_VERSION, 0, from..]` yields `Some(from)`); `frame_sender_wrong_version_is_none` (`[WIRE_VERSION+1, 0, from..]` → `None`).

- [ ] **Step 2: Run, expect failure** — `cargo test -p tines-core wire` fails on the new names/behaviour.

- [ ] **Step 3: Implement** — add `WIRE_VERSION`; in `Frame::encode` write `out[0] = WIRE_VERSION` then postcard into `out[1..]` (return `1 + len`, `TooLarge` if `out.len() < 1 + len`); in `Frame::decode` check `bytes.is_empty()` → `Malformed`, then `bytes[0] != WIRE_VERSION` → `Err(VersionMismatch { version: bytes[0] })`, then postcard the remainder (the empty-remainder/canonical check is *not* yet enforced — that is Task 9); rewrite `frame_sender` to `ENVELOPE_OVERHEAD = 2`.

- [ ] **Step 4: Run, expect pass** — `cargo test -p tines-core` green; then update the tines-bt test helpers and re-run `cargo test -p tines-bt`.

- [ ] **Step 5: Commit** — `git commit -m "feat(core): WIRE_VERSION byte on every frame"`.

### Task 2: Drop reporting — `NodeEvent` and the drop counter table (§1, §3 events)

**Files:**
- Modify: `tines-core/src/exchange.rs` (rename `ConfidenceEvent` → `NodeEvent<A>`; add `DropReason`, the counter table, the overflow counter; report drops in `on_frame`; `drain_events` returns `NodeEvent`)
- Modify: `tines-core/src/node.rs` (`drain_events` signature)
- Modify: `tines-core/src/lib.rs` (export `NodeEvent`, `DropReason`; drop `ConfidenceEvent`)
- Modify: `tines-core/src/consts.rs` (`DROP_TABLE_CAP`)
- Modify: `tines/src/ipc.rs` (map `NodeEvent::Delivered` into `EventOut`; log `NodeEvent::Dropped` to stderr)
- Modify: `tines-ros2/src/node.rs` + `lib.rs` (match `NodeEvent`; fix the doc-comment links to `ConfidenceEvent`)

**Interfaces:**
- Consumes: `WireError::VersionMismatch` (Task 1).
- Produces: `#[non_exhaustive] pub enum NodeEvent<A> { Delivered { peer: NodeId, id: ObservationId }, Dropped { addr: Option<A>, reason: DropReason, count: u32 } }`; `#[non_exhaustive] pub enum DropReason { VersionMismatch { version: u8 }, Malformed }` (`IdentityChanged` arrives in Task 9); `pub const DROP_TABLE_CAP: usize = 32;` (local const); `Node::drain_events(&mut self) -> heapless::Vec<NodeEvent<T::Addr>, { EVENT_QUEUE_CAP + DROP_TABLE_CAP + 1 }>`. Decided: the return buffer is sized `EVENT_QUEUE_CAP + DROP_TABLE_CAP + 1` (64 Delivered + 32 counted Drops + 1 overflow slot) so drops always have room; the table itself is `DROP_TABLE_CAP`, so a drop counter that would exceed the buffer is impossible.

- [ ] **Step 1: Write the failing tests** — in `exchange.rs` (mod tests): `version_mismatch_is_counted` (drive one frame with a bad version byte from `addr`, drain, assert exactly one `Dropped { addr: Some(addr), reason: VersionMismatch{..}, count: 1 }`); `malformed_is_counted` (garbage bytes → `Dropped { reason: Malformed }`); `same_drop_increments_count` (two bad frames → one `Dropped` with `count: 2`, drained once); `drops_do_not_evict_delivered` (fill the event queue with `Delivered`, add a `Dropped`, assert all `Delivered` still present and the `Dropped` is reported); `overflow_counter_has_no_addr` (drive > `DROP_TABLE_CAP` distinct `(addr, reason)` pairs, assert the last is reported with `addr: None`); `expired_addressed_is_not_a_drop` (an addressed observation that arrives already past its `lifetime_ms` produces *no* `Dropped`).

- [ ] **Step 2: Run, expect failure** — `cargo test -p tines-core exchange` fails on `NodeEvent`/`DropReason` names.

- [ ] **Step 3: Implement** — rename to `NodeEvent<A>` (two variants above); add the counter table (fixed `heapless::Vec<(A, DropReason, u32), DROP_TABLE_CAP>` or equivalent) + one `Option<(DropReason, u32)>` overflow slot; in `on_frame`, replace the `Err(_) => return None` arm with a version-mismatch vs malformed branch that bumps the table; `drain_events` returns queued `Delivered` first, then one `Dropped` per nonzero counter (resetting it). Expired addressed observations are dropped by policy in `accept`/`reject`, *not* counted.

- [ ] **Step 4: Run, expect pass** — `cargo test -p tines-core`, then `cargo test -p tines`, then `docker build -f Dockerfile.ros2 -t tines-ros2-check .` (tines-ros2 consumers).

- [ ] **Step 5: Commit** — `git commit -m "feat(core): NodeEvent with counted drop reporting"`.

### Task 3: `Dest` — the addressing reshape (§2) + the log format bump (D5)

**Files:**
- Modify: `tines-core/src/observation.rs` (`Dest`; `Observation.dest` replaces `to`/`lifetime_ms`; `id()`; `aged()`; constructors `broadcast`/`addressed`/`with_observed_at`; the `age_ms` lower-bound and `observed_at` rustdoc; update the module's own tests)
- Modify: `tines-core/src/node.rs` (`observe`/`observe_to` build via `dest`; `belief` reads `dest`), `store.rs` (docs), `mem_store.rs`, `exchange.rs` (every `obs.to`/`obs.lifetime_ms` → `obs.dest`; `reject`), `wire.rs` (`Obs` variant + tests)
- Modify: `tines-store/src/log.rs` (bump `format_version`; refuse the old version on open)
- Modify: `tines-store/tests/persistence.rs` (move `old_format_is_refused` here from Task 10)
- Modify: `tines-sim/src/capped.rs` (re-verify it compiles), `tines-sim/src/sim.rs`/`world.rs` (any `to:`/`lifetime_ms:` construction), `tines/src/ipc.rs`, `tines-ros2/src/node.rs`

**Interfaces:**
- Consumes: nothing new.
- Produces: `#[non_exhaustive] pub struct Dest { pub to: NodeId, pub lifetime_ms: u64 }`; `Observation { pub observer, pub seq, pub age_ms, pub observed_at, pub topic, pub payload, pub dest: Option<Dest> }` (`sig` is added by Task 4 — this task's `Observation` has no `sig` field yet); `Observation::broadcast(observer, seq, topic, payload) -> Observation`, `Observation::addressed(observer, seq, topic, payload, to, lifetime_ms) -> Observation`, `Observation::with_observed_at(mut self, at: u64) -> Observation`. `tines-store`'s `format_version` is bumped here (D5: old logs are refused, not migrated).

- [ ] **Step 1: Write the failing tests** — in `observation.rs`: `dest_invariant_by_type` (an addressed observation *always* has `dest: Some`); `id_reads_dest_to` (`obs(7,0,None,Some([2;16]),Some(100)).id() == obs(7,0,None,Some([2;16]),Some(200)).id()` — lifetime still not part of identity — and the pinned `id_known_vector` value is unchanged); `constructors_set_age_zero` (`broadcast`/`addressed` produce `age_ms == 0` and the right `dest`); `with_observed_at_sets_field`. In `tines-store/tests/persistence.rs`: `old_format_is_refused` (a v1 log → `Err` naming the fix; moved from Task 10, since the encoding changes here).

- [ ] **Step 2: Run, expect failure** — `cargo test -p tines-core observation` fails on `dest`.

- [ ] **Step 3: Implement** — mechanical: `dest: Option<Dest>` replaces `to: Option<NodeId>` + `lifetime_ms: Option<u64>`; `id()` folds `self.dest.map(|d| d.to)` (marker bytes unchanged); `reject` becomes `obs.dest.is_some_and(|d| obs.age_ms > d.lifetime_ms)` (the malformed-pair branch and its tests are deleted); write the two rustdoc items now — `age_ms` is a lower bound (it counts time on running clocks only; power-off time is recovered on store open, crash time is bounded by the host flush cadence, in-flight time is negligible) and points to `observed_at`, and `observed_at` is the observer's wall-clock time in ms since the Unix epoch (UTC), `None` if the observer has no trusted clock, never changed by relays. Bump `tines-store`'s `format_version` and make `open` refuse any older version. Update every downstream read/construct; `cargo check --workspace` and fix all fallout.

- [ ] **Step 4: Run, expect pass** — `cargo test --workspace` green; `cargo build --workspace` green.

- [ ] **Step 5: Commit** — `git commit -m "feat(core): Dest type replaces to + lifetime_ms"`.

### Task 4: `Signature` + `SigAlgo` — the reserved slot (§2a)

**Files:**
- Modify: `tines-core/src/observation.rs` (`Signature`, `SigAlgo`, `Observation.sig`, `MAX_SIG`; the "signing and verification arrive in 1.1" rustdoc)
- Modify: `tines-core/src/consts.rs` (`MAX_SIG = 64` in the wire group)
- Modify: `tines-core/src/wire.rs` (`Obs`/`Frag` encode/decode of `sig`; the golden Obs vector)
- Modify: `tines-core/tests/vectors.rs` (golden Obs vector, both the Ed25519-shaped and unknown-algo cases)

**Interfaces:**
- Consumes: `Observation` (Task 3).
- Produces: `pub const MAX_SIG: usize = 64;`; `#[non_exhaustive] pub struct Signature { pub version: u8, pub algo: SigAlgo, pub bytes: heapless::Vec<u8, MAX_SIG> }`; `#[non_exhaustive] #[repr(u8)] pub enum SigAlgo { Ed25519 = 1, Unknown(u8) }` (decided: catch-all is `Unknown(u8)`); `algo` serializes as a raw `u8` on the wire, *not* a postcard enum tag. The rustdoc for `Signature`, `SigAlgo` and `Observation::sig` says "signing and verification arrive in 1.1" in those words.

- [ ] **Step 1: Write the failing tests** — in `wire.rs`/`vectors.rs`: `obs_roundtrip_with_ed25519_signature` (an `Observation` carrying `Signature { version: 1, algo: Ed25519, bytes: 64 bytes }` decodes equal); `obs_roundtrip_with_unknown_algo` (`algo: Unknown(7)`, short bytes, decodes and is *forwarded*, not rejected); `algo_zero_is_malformed` (`algo: Unknown(0)` → `Malformed`); `version_zero_is_malformed` (`version: 0` → `Malformed`); `raw_one_decodes_to_ed25519` (a wire `algo` byte `1` decodes to `SigAlgo::Ed25519`, never `Unknown(1)`); `ed25519_wrong_length_is_malformed` (`algo: Ed25519`, 63 bytes → `Malformed`); `sig_excluded_from_id` (two observations identical except `sig` share one `id()`); `reassembled_bad_signature_is_malformed` (an observation whose fragments reassemble to a bad-signature `Observation` is rejected as `Malformed`, not accepted); `fragmentation_fits_mtu_sweep` (Review Focus #6 — see below).

  `fragmentation_fits_mtu_sweep`: for `mtu` in `MIN_MTU(=23)..=MAX_FRAME`, a maximum-size signed observation (full `MAX_PAYLOAD` + 64-byte signature) must either fragment into ≤ `MAX_FRAGMENTS` (64) frames each ≤ `mtu`, or — below the threshold (~85 bytes) — be given up cleanly (`SendError::TooLarge` / `ObserveError::TooLarge`), never emitted oversized.

- [ ] **Step 2: Run, expect failure** — tests fail on missing `Signature`/`SigAlgo`.

- [ ] **Step 3: Implement** — the types above; `sig: Option<Signature>` on `Observation` (no public setter in 1.0; core's decode sets it); wire: `algo` as raw `u8` (custom `Serialize`/`Deserialize` or a `#[serde(with = "…")]` module that writes the `repr(u8)` discriminant; `Unknown(n)` writes `n`); `version = 0` **and** `algo = 0` and a wrong length for `Ed25519` are `Malformed`; `id()` ignores `sig`; the same decode-level checks run on observations rebuilt from fragments.

- [ ] **Step 4: Run, expect pass** — `cargo test -p tines-core` green; pin the golden Obs vector.

- [ ] **Step 5: Commit** — `git commit -m "feat(core): reserved Signature slot on Observation"`.

### Task 5: Public API narrowing (§3)

**Files:**
- Modify: `tines-core/src/lib.rs` (the 1.0 export list; `mod wire;` private, `pub use wire::frame_sender;`)
- Modify: `tines-core/src/wire.rs`, `exchange.rs`, `frag.rs`, `bloom.rs` (mark the non-API items `pub(crate)`)
- Modify: `tines-core/src/observation.rs`, `store.rs`, `transport.rs`, `node.rs` (add `#[non_exhaustive]` where §3 requires)
- Modify: `tines-sim/src/world.rs` (fix the `[`Exchange`]` doc link), `tines-bt/src/transport.rs` (import `tines_core::frame_sender`)
- Modify: `tines-bt/tests/transport.rs`, `adv.rs` (import path)

**Interfaces:**
- Consumes: all prior types.
- Produces: the exact §3 public list. `Frame`, `WireError`, `Exchange`, `Peer`, `InFlight`, `Bloom` (and its `salt` field), `Reassembler`, `fragment`, `FRAG_OVERHEAD` are `pub(crate)`. `#[non_exhaustive]` on `ObserveError`, `StoreError`, `SendError`, `Event`, `NodeEvent`, `DropReason`, `SigAlgo`, `Observation`, `Dest`, `Signature`, `TrimPolicy`. `pub use wire::frame_sender;` at crate root (decided over keeping `wire` public).

- [ ] **Step 1: Write the failing tests** — a compile-time doc/export check: in `tines-core/tests/public_api.rs` (or the `conformance` feature), a `pub use`-only probe that `use`s each item on the §3 public list and asserts nothing; the *failing* signal is `cargo check -p tines-core` (private items are no longer importable — existing external callers break, which the plan fixes in this task).

- [ ] **Step 2: Run, expect failure** — `cargo check --workspace` fails on `tines-sim`/`tines-bt` importing now-private items.

- [ ] **Step 3: Implement** — apply `pub(crate)`/`pub` and `#[non_exhaustive]` exactly per §3; fix the two external doc-link/import sites; run `cargo doc --workspace --no-deps` to confirm no broken private-link warnings.

- [ ] **Step 4: Run, expect pass** — `cargo check --workspace` + `cargo test --workspace` green.

- [ ] **Step 5: Commit** — `git commit -m "refactor(core): narrow the 1.0 public API"`.

### Task 6: The `Store` trait, settled (§4)

**Files:**
- Modify: `tines-core/src/store.rs` (`is_empty` default, `flush` default, release docs, new `store_conformance` module behind a `conformance` feature)
- Modify: `tines-core/src/node.rs` (`flush(now)` replaces `store_mut`)
- Modify: `tines-core/Cargo.toml` (`conformance` feature)
- Modify: `tines-store/src/log.rs` (implement `flush`), `tines-sim/src/capped.rs` (delegate/implement `is_empty`/`flush`), `tines/src/ipc.rs` (call `node.flush(now)` in `poll_exchange`, around line 214)

**Interfaces:**
- Consumes: nothing new.
- Produces: `Store::is_empty(&self) -> bool` (default `self.len() == 0`; drop the `len_without_is_empty` allow); `Store::flush(&mut self, now: Tick) -> Result<(), StoreError>` (default `Ok(())`); `Node::flush(&mut self, now: Tick) -> Result<(), StoreError>`; `Node::store_mut` removed. A `conformance` feature gating `tines_core::store_conformance` — a `no_std`-clean module of functions that take a backend factory (not a `tines-core/tests/` file), so they can build observations with `sig` set from inside the crate; each function exercises one property (dedupe, age lineage, saturating ticks, release-surviving-`get`, `sig` round-trip, trim order, no tombstones, idempotent `flush`). `MemStore`, `LogStore` (a fresh file per case) and `CappedStore` call the module from their own crates.

- [ ] **Step 1: Write the failing tests** — the `store_conformance` module itself, with one function per property; then wire `MemStore`, `tines_store::LogStore` and `tines_sim::CappedStore` to it from their own crates.

- [ ] **Step 2: Run, expect failure** — `cargo test -p tines-core --features conformance` fails on `flush`/`is_empty`/`store_conformance`.

- [ ] **Step 3: Implement** — trait defaults; `Node::flush(now)` delegating to `Store::flush`; `LogStore::flush(&mut self, now)` writing a `Record::Clock` with the *caller's* `now` (fixing F18's stale-marker tick); delete `store_mut`; update `poll_exchange` in `tines/src/ipc.rs` to `node.flush(clock.now())`.

- [ ] **Step 4: Run, expect pass** — `cargo test --workspace` + `docker build -f Dockerfile.ros2 -t tines-ros2-check .`.

- [ ] **Step 5: Commit** — `git commit -m "feat(core): settle the Store trait (flush, is_empty, conformance suite)"`.

### Task 7: Constants — wire vs local split (§5)

**Files:**
- Modify: `tines-core/src/consts.rs` (re-group + document each const as wire or local)
- Modify: `AGENTS.md` (the constant list shows the split)

**Interfaces:**
- Produces: `consts.rs` split into two documented groups — wire (frozen for v1: `MAX_TOPIC`, `MAX_PAYLOAD`, `MAX_FRAME`, `SUMMARY_BYTES`, `ACK_IDS_CAP`, `MAX_SIG`, `BLOOM_K`, and the private `MAX_FRAGMENTS`) vs local (`MAX_PEERS`, `SEND_QUEUE_CAP`, `ACK_BUFFER_CAP`, `BCAST_SENT_CAP`, `EVENT_QUEUE_CAP`, `SUMMARY_INTERVAL_MS`, `REASSEMBLY_TIMEOUT_MS`, `DROP_TABLE_CAP`).

- [ ] **Step 1: No new tests** — this task only re-documents; the test is `cargo doc --workspace --no-deps` staying clean and the AGENTS.md list matching `consts.rs`.

- [ ] **Step 2: Implement** — move + document per §5's rule ("wire if changing it changes how a v1 peer decodes or interprets a frame").

- [ ] **Step 3: Verify** — `cargo test --workspace` green (no behaviour change).

- [ ] **Step 4: Commit** — `git commit -m "docs(core): split wire vs local constants"`.

### Task 8: Bounce-table overflow, pinned (§6)

**Files:**
- Modify: `tines-sim/src/sim.rs`, `tines-sim/tests/props.rs` (a property driving the table past `SEND_QUEUE_CAP`)

**Interfaces:**
- Consumes: the exchange's bounce table (unchanged).
- Produces: a proptest that floods > `SEND_QUEUE_CAP` distinct observations across `MAX_PEERS` peers and asserts the "always ≥ 1 holder" invariant and that the custody cursor still gives every candidate a turn.

- [ ] **Step 1: Write the failing test** — `tines-sim/tests/props.rs::bounce_overflow_keeps_a_holder` (drive custody past capacity; assert ≥1 holder for each id and no candidate starved).

- [ ] **Step 2: Run, expect pass or a real finding** — this pins behaviour; if it fails, the finding is the deliverable (do not "fix" by weakening the invariant).

- [ ] **Step 3: Implement any needed fix** — only if the property exposes a genuine ≥1-holder violation; §6 says the current drop-oldest design is already safe, so expect pass-as-is.

- [ ] **Step 4: Commit** — `git commit -m "test(sim): pin bounce-table overflow behaviour"`.

### Task 9: Core hardening — F6, F8, F9, F13 (§10)

**Files:**
- Modify: `tines-core/src/exchange.rs` (peer `id` pinning; idle eviction; summary replay limit; drop-oldest events; pending-ack purge; canonical decode)
- Modify: `tines-core/src/consts.rs` (`PEER_IDLE_MS = 30000`, local)

**Interfaces:**
- Consumes: `NodeEvent`, `DropReason` (Task 2).
- Produces: `DropReason::IdentityChanged`; `pub const PEER_IDLE_MS: u64 = 30_000;`.

- [ ] **Step 1: Write the failing tests** — `id_changes_are_dropped_as_identity_changed` (frame 1 sets `peer.id = A`, frame 2 claims `from = B` → dropped, counted `IdentityChanged`, and B receives no addressed mail); `idle_peer_is_evicted` (a peer with no inbound frame for > `PEER_IDLE_MS` is removed as if `Lost`); `replayed_summary_is_ignored` (two summaries from one peer within `SUMMARY_INTERVAL_MS` → the second is not acted on and produces no re-send); `events_drop_oldest` (overflow the event queue → the *oldest* `Delivered` is gone, newest retained); `lost_peer_purges_pending_acks` (pending acks to a removed peer are cleared); `trailing_bytes_is_malformed` (valid frame + one trailing byte → `Malformed`, Review Focus #5).

- [ ] **Step 2: Run, expect failure** — each test fails against current behaviour.

- [ ] **Step 3: Implement** — F6: first decoded frame pins `peer.id`, later `from` mismatch → `IdentityChanged` drop (reset on `Contact`/`Lost`); F8: track last-inbound tick, evict at `PEER_IDLE_MS`; F9: at most one summary per peer per `SUMMARY_INTERVAL_MS`, and skip already-sent ids on rebuild; F13: `events.push` drops the oldest (remove(0)), purge acks on `Lost`/evict, `take_from_bytes` + empty-remainder check.

- [ ] **Step 4: Run, expect pass** — `cargo test -p tines-core` + full `sh scripts/ci.sh`.

- [ ] **Step 5: Commit** — `git commit -m "fix(core): peer pinning, idle eviction, replay and queue hardening"`.

### Task 10: tines-store quarantine, wall-clock marker and downtime fold (§9, decision G as amended)

**Files:**
- Modify: `tines-store/src/log.rs` (quarantine of held observations; `set_wall_clock`; wall-clock marker with derived wall time; downtime fold; addressed expiry; broadcast floor; fold report)
- Modify: `tines-store/tests/persistence.rs` (quarantine and downtime tests)

**Interfaces:**
- Consumes: `Observation` with `observed_at` (Task 3), `Store::flush(now)` (Task 6), the `format_version` bump (Task 3).
- Produces:
  - `LogStore::open(path: &Path, now: Tick)` keeps its signature. Every observation already in the log is quarantined.
  - While quarantined, an observation is:
    - left out of `for_each_broadcast_id`, `for_each_addressed_id` and `for_each_topic`;
    - reported `true` by `is_released` if addressed;
    - not trimmed on its age;
    - still reported by `contains`, so dedupe works.
  - `LogStore::set_wall_clock(&mut self, wall_now: u64, now: Tick) -> FoldReport`. It runs once (a second call is a no-op), folds the downtime, lifts the quarantine, and starts wall time for markers.
  - `FoldReport { downtime_ms: Option<u64>, expired_addressed: usize, floored_broadcasts: usize }`. It's also printed once on stderr and readable afterwards, like `skipped_records`.
  - `Record::Clock` gains `wall: Option<u64>`. After `set_wall_clock` it is `wall_at_set + (now − tick_at_set)`; before, `None`.
  - A `LogStore` option `unknown_downtime_age_ms`.
- **Downtime known:** the last marker has a wall time, and `wall_now` ≥ it. Every quarantined observation's age gains the wall time elapsed since that marker, minus the ticks already counted since this open (saturating).
- **Downtime unknown:** no marker, a marker without wall time, or a marker ahead of `wall_now`. Quarantined addressed observations get an age past `lifetime_ms`, and quarantined broadcasts get `max(age, unknown_downtime_age_ms)`.

- [ ] **Step 1: Write the failing tests**
  - `held_is_quarantined_until_wall_clock`: reopen a log holding a broadcast and an addressed observation. Before `set_wall_clock`, neither is visited by `for_each_broadcast_id`, `for_each_addressed_id` or `for_each_topic`; the addressed one is `is_released`; both are `contains`. After it, they're all visible.
  - `quarantined_addressed_duplicate_not_acked`: an exchange-level test with `LogStore` (or in `tines-sim` through a quarantining wrapper). A peer offers a duplicate of a quarantined addressed observation, and no `Ack` comes back.
  - `new_inserts_not_quarantined`: an observation inserted after `open` is visible at once and isn't changed by the fold.
  - `downtime_known_advances_ages`: marker at wall 1000; reopen; `set_wall_clock(2000, …)` adds 1000 to every held age (saturating), less any ticks already counted since open.
  - `downtime_unknown_expires_addressed` (no marker) and `marker_without_wall_is_unknown`: held addressed observations are never delivered, and the report counts them.
  - `downtime_unknown_floors_broadcasts`: a held broadcast's age is raised to `unknown_downtime_age_ms`.
  - `clock_went_backwards_is_unknown`: marker wall time ahead of `wall_now`.
  - `marker_wall_time_is_derived`: `set_wall_clock(W, T)`, then `flush(T+5000)` writes a marker carrying W+5000. A flush before `set_wall_clock` writes `wall: None`.
  - `set_wall_clock_runs_once`: a second call changes nothing.
  - `fold_reported_once`: the `FoldReport` is printed once, and readable afterwards.

- [ ] **Step 2: Run, expect failure** — `cargo test -p tines-store`.

- [ ] **Step 3: Implement** — per §9 as amended. The quarantine is a per-entry flag set at load and cleared by the fold; it isn't persisted. Whether quarantined entries count towards `trim`'s `max_count` is the builder's call, with one rule: untrusted ages must never cause fresher data to be trimmed in their place.

- [ ] **Step 4: Run, expect pass** — `cargo test -p tines-store`, then `sh scripts/ci.sh`.

- [ ] **Step 5: Commit** — `git commit -m "feat(store): quarantine held observations until a wall-clock downtime fold"`.

### Task 10b: Hosts — trusted time, time from peers, `observed_at` (§9, decision G as amended)

**Files:**
- Modify: `tines/src/clock.rs` (`HostClock` gains trusted wall time), `tines/src/main.rs`, `tines/src/ipc.rs`
- Modify: `tines-ros2/src/node.rs`

**Interfaces:**
- Consumes: `LogStore::set_wall_clock` (Task 10).
- Produces, in both hosts:
  - **Open at once.** `LogStore::open(path, now)` at startup, as today. The robot runs tines immediately.
  - **Trusted time, in this order:**
    1. A local source. A config flag (`trusted_clock: "system"`) says the system clock is trusted, meaning an RTC or a GPS/NTP-disciplined clock. This is config, not detection, and the docs say so.
    2. Otherwise, a peer. After each `poll`, scan the observations stored *since this open* for the one carrying `observed_at` with the smallest `age_ms`. The estimate is `observed_at + age_ms + (now − tick it was stored)`, which is never later than the true time, because age is a lower bound. Quarantined data is invisible to the scan, so only this boot's observations count.
    3. Otherwise, stay quarantined. The robot's own fail-safe is outside tines: log once that tines is waiting for trusted time, and keep running.
  - The first trusted time calls `set_wall_clock(wall, now)` once and anchors `HostClock`'s wall time: wall at set + ticks since.
  - From then on, every observation the host makes carries `observed_at = Some(HostClock wall ms)`. Before trusted time it stays `None` (R4).

- [ ] **Step 1: Write the failing tests** (in `tines`, over the existing in-memory transport)
  - `observe_has_observed_at_after_trusted_time`: with `trusted_clock` set, an IPC `Observe` produces an observation with `observed_at = Some(_)`.
  - `observe_has_no_observed_at_before_trusted_time`: without it, `None`.
  - `time_from_peer`: instance A has trusted time and observes; instance B has none and a log holding a quarantined observation. After an exchange, B's `set_wall_clock` has run with an estimate within one poll interval of A's wall time (A's `observed_at + age_ms`), and B's held observation is visible.
  - `smallest_age_wins`: given two received observations with `observed_at`, the estimate comes from the one with the smaller `age_ms`.

- [ ] **Step 2: Run, expect failure.**

- [ ] **Step 3: Implement** — `HostClock` wall anchor; the trusted-time state machine (waiting → set) in the service's poll loop and in `TinesNode::poll`; the `trusted_clock` config field; `observed_at` on every observe once trusted. `unknown_downtime_age_ms` is a host config field passed to `LogStore`. It must be below the trim `max_age_ms`, but the trim defaults are still empty (host hardening), so note in the host docs that this check waits for host hardening.

- [ ] **Step 4: Run, expect pass** — `cargo test -p tines`, `sh scripts/ci.sh`, then `docker build -f Dockerfile.ros2 -t tines-ros2-check .`.

- [ ] **Step 5: Commit** — `git commit -m "feat(hosts): trusted wall time from the system clock or a peer; set observed_at"`.

### Task 11: Evidence — pinned vectors + MSRV (§7)

**Files:**
- Create: `tines-core/tests/vectors.rs` (consolidate `id_known_vector` + the golden wire vectors)
- Modify: `tines-core/Cargo.toml` (`rust-version` on `tines-core` only), `scripts/ci.sh` (MSRV job building only `tines-core`)

**Interfaces:**
- Consumes: final wire encodings (Tasks 1–4).
- Produces: `tines-core/tests/vectors.rs` with the identity vector (unchanged value) + one golden encoding per `Frame` variant including the version byte + the Ed25519/unknown-algo Obs vectors + the 0.x-shaped frame rejected as version mismatch; `rust-version` set on `tines-core` only (the host crates' deps — bluer, tokio, rclrs — need newer Rust; do **not** claim tines-core's MSRV for them); a CI job building/testing `tines-core` alone on that MSRV.

- [ ] **Step 1: Write the failing tests** — move the existing vectors in (the `id_known_vector` and the golden encodings); add the missing golden encodings and the 0.x-rejection vector.

- [ ] **Step 2: Run, expect pass** — `cargo test -p tines-core vectors` green.

- [ ] **Step 3: Implement** — find MSRV with `cargo msrv` searching up to the pinned toolchain (1.99; a `repr(u8)` enum with a data-carrying variant like `SigAlgo` needs ≥ 1.66, and dependencies set their own floors — don't guess the range); set `rust-version`; add the CI job.

- [ ] **Step 4: Commit** — `git commit -m "test(core): pinned vectors + MSRV gate"`.

### Task 12: Evidence — fuzz harness + proptest twin (§7)

**Files:**
- Create: `fuzz/` (cargo-fuzz, outside the workspace, nightly), `fuzz/Cargo.toml`, `fuzz/fuzz_targets/node.rs`
- Modify: `tines-core/tests/` (the proptest stable twin of the same harness)
- Modify: `.github/workflows/` (scheduled fuzz job)

**Interfaces:**
- Consumes: `Node`, `MemStore`, a scripted `Transport`.
- Produces: a fuzz target whose input decodes into `Contact`/`Lost`/`Frame(bytes)`/`Tick(delta, may go backwards)`/`observe` steps; an adversarial-peer mode building well-formed frames (chosen summary bits, Obs/Frag ids/observers/ages/lifetimes, acks for sent/unsent ids, conflicting fragments, changing `from`) from many addresses beyond `MAX_PEERS`; post-step checks (no panic, ≤ `mtu()`, no addressed stored past lifetime, drop counts reconcile, signatures round-trip). A proptest twin with a bounded case count runs in the normal suite.

  Adversarial mode must *also* check the §10 properties: the peer table recovers after a flood from more than `MAX_PEERS` addresses; output per received summary is bounded and repeating a summary does not re-send; a NodeId never changes within a contact; the event queue drops the oldest; an ack is sent only for an observation that was stored (F1).

- [ ] **Step 1: Write the harness** — the twin first (it runs in CI); then the fuzz target wrapping it.

- [ ] **Step 2: Run** — `cargo test -p tines-core` (twin green); a short `cargo fuzz run node -- -max_total_time=60` sanity run (full 24 CPU-hour budget is release-time, §"Done means").

- [ ] **Step 3: Commit** — `git commit -m "test(core): fuzz harness and proptest twin"` (committing the corpus too).

### Task 13: Docs, compatibility policy, and the 1.0.0 release (§8, "Done means")

**Files:**
- Modify: `README.md` (a "Stability" section with §8; switch the `TrimPolicy` example to `TrimPolicy::default()` + field assignment, since the struct is now `#[non_exhaustive]`), `CHANGELOG.md` (1.0.0 entry), `AGENTS.md` (spec list + trait extension rule + wire/local split), `tines-core/src/lib.rs` (`#![deny(missing_docs)]` + document the remaining items), `THREAT_MODEL.md` (mark F6/F8/F9/F13 fixed with SHAs; update F18 — Task 6 fixed its stale clock-marker tick; add a finding for peer-derived time: unauthenticated until 1.1, a forged time ahead only expires early, behind takes the unknown path, but the robot's own `observed_at` stamps are wrong until a local source corrects them), `Cargo.toml` + dependent crates (`tines-core` → 1.0.0, hosts depend on `"1"`)

**Interfaces:**
- Consumes: everything above.
- Produces: README §8; CHANGELOG 1.0.0 listing every 0.3 break; `#![deny(missing_docs)]` with zero missing items (recount — the spec's "26" predates the fleet fixes); `THREAT_MODEL.md` marks F6/F8/F9/F13 fixed (and updates F18); `tines-core` at 1.0.0 with `tines-store`/`tines-bt`/`tines-ros2`/`tines` depending on `"1"`.

- [ ] **Step 1: Write the failing test** — `cargo doc --workspace --no-deps` under `#![deny(missing_docs)]` (it fails until every public item is documented).

- [ ] **Step 2: Implement** — the docs; the release bump.

- [ ] **Step 3: Verify** — `sh scripts/ci.sh` green; `THREAT_MODEL.md` marks F6/F8/F9/F13 fixed with commit SHAs.

- [ ] **Step 4: Commit** — `git commit -m "release(core): tines-core 1.0.0"`.

  **Publishing is Kyle's step** (it is outward-facing). The `cargo-semver-checks` gate is *not* added here: before 1.0.0 is published the only baseline is 0.2.1, and the check fails on every intended break. It is a follow-up commit *after* publishing, turning `cargo-semver-checks` against the published 1.0.0 on in `scripts/ci.sh`.