Skip to content

docs: write the invariants the removed notes file held into docs/ - #15

Merged
sshaplygin merged 1 commit into
mainfrom
v04/a4-docs-invariants
Sep 13, 2026
Merged

sshaplygin merged 1 commit into
mainfrom
v04/a4-docs-invariants

Conversation

@sshaplygin

Copy link
Copy Markdown
Owner

When the working-notes file stopped being tracked (#9), the invariants it
recorded were meant to move into docs/. Stage A4 (#13) was closed without
doing that. An audit of twelve load-bearing rules against docs/ found six
with no statement there at all
— not the three first reported.

Invariant Now in
Every mutation of a policy happens while it is not the active one (switchLocked's ordering rule) design.md
A gradual window has three roles, not two — the source is neither active nor a shadow design.md
Sampled counts are never scaled back up by 1/rate design.md
A selection naming Undefined, or a policy the cache does not hold, means no change (previously only a comment inside the illustrative adapter skeleton) design.md
Advice: Epochs counts reporting epochs, not ticks; measurements start over on a role change; ties break by policy type advisor-mode.md
The order of Keys() is not portable: 2Q returns frequent-then-recent, ARC recent-then-frequent policies.md

The ordering claims were checked against golang-lru's source: 2Q's Keys
appends its recent list to its frequent one, ARC's appends t2 to t1.

Stale names left by #14

The three-phase epoch left the old function name in four places:
docs/design.md's architecture sketch still read
runEpoch -> selectPolicyLocked, and stability.go plus one test comment
referred to a function that no longer exists. That test comment also said the
parked epoch goroutine held the cache mutex; it now holds banditMu and no
cache lock.

Not in this change

AdaptedCache.Keys is documented as "oldest first", which the table above
shows is false for 2Q and ARC, and enforceCapacityLocked removes keys[0] on
that assumption. That is a code fix with a test, and it belongs to the next
stage (the Keys() order canary), not to a documentation change.

Verification

internal links in docs/ and README.md   49 checked, 0 broken (fenced code excluded)
gofmt / go vet                          clean
go test -race -count=3 (touched tests)  ok
make all                                Release checks passed

When the working-notes file stopped being tracked, the invariants it
recorded were meant to move into docs/. Stage A4 was closed without doing
that. An audit of twelve load-bearing rules against docs/ found six with no
statement there at all, not the three first reported:

  - every mutation of a policy happens while it is not the active one
    (switchLocked's ordering rule)                         -> design.md
  - a gradual window has three roles, not two: the source is neither
    active nor a shadow                                    -> design.md
  - sampled counts are never scaled back up by 1/rate      -> design.md
  - a selection naming Undefined, or a policy the cache does not hold,
    means no change -- previously only a comment inside the illustrative
    adapter skeleton                                       -> design.md
  - Advice: Epochs counts reporting epochs rather than ticks; a policy's
    measurements start over when it changes role; ties break by policy
    type                                                   -> advisor-mode.md
  - the order of Keys() is not portable: 2Q returns frequent-then-recent,
    ARC recent-then-frequent                               -> policies.md

The ordering claims were checked against golang-lru's source: 2Q's Keys
appends recent to frequent, ARC's appends t2 to t1.

The rewrite of the epoch into three phases left the old function name
behind in four places. docs/design.md's architecture sketch still showed
runEpoch -> selectPolicyLocked, and stability.go and one test comment
referred to a function that no longer exists. The test comment also said
the parked epoch goroutine held the cache mutex; it now holds banditMu and
no cache lock.

Verified: every internal link in docs/ and README.md resolves (49 checked,
fenced code excluded), gofmt and go vet clean, make all passes across
every module.
@sshaplygin
sshaplygin merged commit 4cd4c47 into main Sep 13, 2026
25 checks passed
@sshaplygin
sshaplygin deleted the v04/a4-docs-invariants branch September 13, 2026 01:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant