Skip to content

docs: reduce the transition contract to the current specification - #347

Merged
okhsunrog merged 2 commits into
mainfrom
docs/transition-contract-current
Sep 17, 2026
Merged

okhsunrog merged 2 commits into
mainfrom
docs/transition-contract-current

Conversation

@okhsunrog

@okhsunrog okhsunrog commented Sep 17, 2026

Copy link
Copy Markdown
Owner

Make docs/notes/app-state-transitions.md read 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.

  • Sections 1–12 keep their numbers, because code comments and the other docs cite §1–§9, and are rewritten to 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 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).
  • Sections 13–22 move verbatim into 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 in ConfigCoordinator.kt.
  • Stale statements elsewhere: lsposed/AGENTS.md still described DiagnosticsCache as projecting runs onto the NotRun/Running/Blocked/Failed/Ready states retired in refactor(lsposed): retire the transitional diagnostic state facade #338; observation-coordinator.md described ReadReason.Transition as 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.md had every item closed and was still listed as "next steps": removed with its README entry. docs/README.md lists the contract and its history.

Rebased on main after #345; describes the design as merged.

@github-actions github-actions Bot added area:lsposed LSPosed module and the Android app area:docs Documentation only labels Sep 17, 2026
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
okhsunrog force-pushed the docs/transition-contract-current branch from 50cf30e to ad9a941 Compare September 17, 2026 04:05
@okhsunrog
okhsunrog merged commit 3a2f66d into main Sep 17, 2026
19 of 20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:docs Documentation only area:lsposed LSPosed module and the Android app

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant