docs: reduce the transition contract to the current specification - #347
Merged
Merged
Conversation
docs/notes/app-state-transitions.md had grown into a thousand-line mix of the agreed design, ten dated implementation stages with their boundaries "at the time", and amendments appended at the end. Several statements the sections in the middle made were no longer true (the startup intent "consumed" by the first suite, the transition-driven confirmation, cached tiles overlaid with a note), and agents reading the note reproduced them. Keep sections 1–12 with their numbers, since code comments and the other docs cite §1–§9, and rewrite them to say what holds now: the coordinators and the recorded deviation from a single presentation revision (§1), the startup intent as ensure (§2), the operation observer (§3), read reasons, stale marks, the app-VPN observation and routing knowledge (§5), the measurement key and the applicability table as implemented (§6), the run coordinator's states, the three ways a suite starts and the owed confirmation (§7), the presentation, the Situation, the surfaces and the Dashboard projection (§8), what capture implements and what it still designs (§9), a new invariant I17 for projections, updated T12/T27 and new T31/T32 traces (§11), and the validation boundary with the known gaps (§12). Move sections 13–22 verbatim into app-state-transitions-history.md with their numbers, and point every reference to a moved section at the new home (observation-coordinator, diagnostics, limits, the state-refactor handoff, the diagnostics analysis, one KDoc in ConfigCoordinator). docs/README lists both.
lsposed/AGENTS.md still described DiagnosticsCache as projecting runs onto the NotRun/Running/Blocked/Failed/Ready states retired in #338; say what it projects now. observation-coordinator.md described ReadReason.Transition as the VPN transport callback, which #344 replaced with the foreground poller, two paragraphs after saying there is no such listener. The UI presentation review's status header listed decisions 2 and 6 as current although the owed confirmation superseded both; note that. The state-refactor handoff note had every item closed and was still listed as "next steps": remove it and its README entry (its cold-start measurements stay in git history).
okhsunrog
force-pushed
the
docs/transition-contract-current
branch
from
September 17, 2026 04:05
50cf30e to
ad9a941
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Make
docs/notes/app-state-transitions.mdread as the current specification instead of a thousand-line mix of the agreed design, ten dated implementation stages and amendments appended at the end, and retire the stale statements that rewrite exposed elsewhere. Several statements in the contract's middle sections were no longer true (the startup intent "consumed" by the first suite, the transition-driven confirmation, cached tiles overlaid with a note), and agents reading the note reproduced them.ensure(§2); the operation observer (§3); read reasons, stale marks, the app-VPN observation and routing knowledge (§5); the measurement key and the applicability table as implemented (§6); the run coordinator's states, the three ways a suite starts and the owed confirmation (§7); the presentation, the Situation, the surfaces and the Dashboard projection (§8); what capture implements and what it still only designs (§9); a new invariant I17 for projections; updated T12/T27 and new T31/T32 traces (§11); the validation boundary with the known gaps (§12).docs/notes/app-state-transitions-history.md, keeping their numbers, with a preface saying what they are. Every reference to a moved section points at its new home:observation-coordinator.md,diagnostics.md,limits.md, the diagnostics analysis, and one KDoc inConfigCoordinator.kt.lsposed/AGENTS.mdstill describedDiagnosticsCacheas projecting runs onto the NotRun/Running/Blocked/Failed/Ready states retired in refactor(lsposed): retire the transitional diagnostic state facade #338;observation-coordinator.mddescribedReadReason.Transitionas the VPN transport callback that fix(lsposed): track app VPN state directly #344 replaced with the poller; the UI presentation review's header listed two decisions the owed confirmation superseded. All three corrected.docs/notes/state-refactor-handoff.mdhad every item closed and was still listed as "next steps": removed with its README entry.docs/README.mdlists the contract and its history.Rebased on main after #345; describes the design as merged.