Skip to content

Pre-implementation design review

Status: reviewed and corrected, 10 November 2026. This is a specification review; runtime guarantees remain subject to implementation and the release tests below.

The review covers standalone idle, Redis recovery, optional navigation integration and consistency across the programme, APIs and test plans. Both libraries remain independently usable. No application flow, ticket or deployment is a library release dependency.

Findings and corrections

Finding Correction Required implementation evidence
Session/key reuse could let delayed work affect a new activity Fresh activity_id, expected-generation guards, guarded session replacement and tombstones Same-key ABA and stale touch/clear tests
Standalone examples depended on an external session without defining ownership Idle-owned session factory plus explicit external SessionAuthority Handler-only example without FSM/nav; fixed absolute expiry
Reusing one update ID for several mutations could deduplicate the wrong operation Stable substep IDs and canonical-input fingerprints; payload mismatch is an error Repeat same request, mismatch payload and delayed replay
Stale-control promise exceeded reply/command transport capabilities Strict prompt binding only for token-bearing controls; current-activity semantics for text/commands Delayed reply/command tests and unknown-delivery tests
Accepted ordinary input was reserved before knowing whether the handler succeeded Supersede on explicit successful activity under full-handler coordination Failed input preserves grace; successful input supersedes once
Recovery retention was incorrectly counted against user session lifetime Separate logical expiry and physical retention; inspect eligibility before questions Short-lived session with long receipt retention
Late send receipts could extend grace Anchor to validated server delivery time or conservative request-start time Receipt delayed past grace; no renewed response window
Navigation promised recovery but exposed only a final commit Prepare/checkpoint/lookup/complete contracts and effect-stage recording No send before durable prepare; unknown render never blindly repeated
Atomic integration could erase its own operation or diverge revisions Operation-scoped staged replacement, adapter-owned writer, explicit mapping rules Continue/restore staging, background render and activity mapping
Idle expiry/clear could delete retained navigation Independent component retention and generation-scoped cleanup Exempt view survives idle clear; old reply tray cannot overwrite new UI
Lease renewal and final acknowledgement checks were insufficient Every worker write checks live ownership; late renewal cannot resurrect a lease Paused worker, late receipt and expired renewal tests
Job lease was confused with conversation lock lifetime Verify/renew both resources; reject unsafe isolation defaults Disabled FSM isolation, short lock TTL and child-task tests
Reconciliation could not discover a missing due entry Explicit live/expiry indexes with bounded cursors; administrative fallback for index loss Lost due entry repaired; missing membership reported honestly
Atomic Redis scripts were treated as rollback transactions Validate before writes, distinguish runtime inconsistency, NOSCRIPT and unknown execution Script error, SCRIPT FLUSH, connection loss and noeviction profile
Idempotent abandonment was incorrectly generalized to all UI restoration Per-effect receipts and EFFECT_UNKNOWN/QUARANTINED outcomes Crash inside custom adapter; no whole-adapter replay
Replica-local enablement and policy changes could reinterpret active work Versioned manifest, frozen active policy snapshots and explicit migration/drain Mixed rollout versions and disable/re-enable races

Guarantees and limits

The backend conditionally commits state and schedules work atomically within its supported storage profile. It does not transact with Telegram, an application database or separately owned FSM data. Application effects need stage idempotency and business-version fencing. Redis data loss can remove the evidence needed for deduplication; a lease cannot stop a Telegram request already in flight.

Unknown delivery, unsupported persisted versions and exhausted retries stay visible instead of being silently retried or dropped. Recovery must distinguish a known unsent stage from an unknown effect. Memory provides the same live-process state semantics with no restart durability.

Redis execution and script-cache corrections follow the primary transaction documentation and Lua documentation. Lock integration was checked against the aiogram FSM middleware; exact supported versions still require integration tests.

Implementation entry gate

Before implementing side effects, complete M0 with executable model fixtures for the corrected transitions and public error/result types. Then follow each package's memory, Redis and optional-adapter work packages. Standalone releases have no dependency on completion of the optional adapter.

Documentation checks verify rendering, links, code-block syntax and consistency; they do not substitute for the real-Redis concurrency, injected crash, dispatcher integration and manual Telegram-client tests specified in storage and verification.