repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(leaks): plan durable lifecycle phase

8e122cc8eaa9ff05bb9d412cabf401720a0ca754

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

docs/super/plans/2026-07-17-leaks-detector-reliability-phase-2-durable-lifecycle.md

Added
new file mode 100644
1 +# Leaks Reliability Phase 2 Durable Lifecycle Implementation Plan
3 +**Goal:** Make every provider-visible placeholder durably authenticated before emission and hydrate tools only from the active session branch.
5 +**Architecture:** `PlaceholderStore` owns one active generation, HMAC32 formatting, AES-GCM records, branch reconstruction, and unresolved-token inspection. `LeaksEngine` fails open when persistence cannot authorize a mapping. `pi.ts` supplies synchronous custom-entry appends, rebuilds on session lifecycle events, emits sanitized diagnostics, and blocks every tool when traversal is incomplete or an unknown placeholder remains.
7 +**Tech stack:** TypeScript, Node crypto, Pi custom session entries, Vitest, fast-check.
9 +## Task 1: Versioned persistence primitives
11 +- Add generation and mapping record types.
12 +- Replace legacy HMAC12 generation with V1 HMAC32 placeholders.
13 +- Derive HMAC and AES-GCM keys with HKDF.
14 +- Encrypt mapping values with authenticated generation and placeholder metadata.
15 +- Test canonical records, ciphertext authentication, collisions, caps, and append failure.
17 +## Task 2: Active-branch reconstruction
19 +- Rebuild only from `getBranch()` custom entries.
20 +- Select the last generation and following mappings for that generation.
21 +- Ignore unsupported versions with warnings and disable new redaction.
22 +- Disable new redaction on corrupt, conflicting, or undecryptable records while retaining authenticated mappings.
23 +- Test resume, sibling exclusion, navigation before generation, and detector changes.
25 +## Task 3: Persist-before-redact engine integration
27 +- Configure the engine with the active generation and append callback.
28 +- Leave values visible when generation creation, encryption, append, collision, or capacity fails.
29 +- Make `/leaks clear` append and activate a new generation.
30 +- Keep status counters and warnings accurate.
32 +## Task 4: Strict recursive hydration boundary
34 +- Hydrate known placeholders in strings at any nesting point.
35 +- Detect current and legacy unknown placeholder tokens after hydration.
36 +- Block every built-in and custom tool on unknown tokens, cycles, unsupported objects, or depth overflow.
37 +- Include only tool name, safe path, and placeholder label in diagnostics.
38 +- Restore assistant messages and tool results symmetrically.
40 +## Task 5: Lifecycle hooks and diagnostics
42 +- Rebuild on `session_start` and `session_tree` before further work.
43 +- Notify once when restart durability is unavailable for in-memory sessions.
44 +- Route sanitized diagnostics to `ctx.ui.notify` or stderr with `[leaks]` outside UI mode.
45 +- Test reload, clear, tree, fork-style copied branches, stale contexts, and print/JSON diagnostics.
47 +## Task 6: Model properties and verification
49 +- Add model-based generation, mapping, clear, branch, corruption, and hydration properties.
50 +- Run `mise run fmt`, `mise run lint`, `mise run check`, `mise run test`, and `mise run fuzz`.
51 +- Request code review and fix Critical/Important findings before Phase 3.