docs: write the invariants the removed notes file held into docs/ - #15
Merged
Merged
Conversation
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.
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.
When the working-notes file stopped being tracked (#9), the invariants it
recorded were meant to move into
docs/. Stage A4 (#13) was closed withoutdoing that. An audit of twelve load-bearing rules against
docs/found sixwith no statement there at all — not the three first reported.
switchLocked's ordering rule)design.mddesign.md1/ratedesign.mdUndefined, or a policy the cache does not hold, means no change (previously only a comment inside the illustrative adapter skeleton)design.mdAdvice:Epochscounts reporting epochs, not ticks; measurements start over on a role change; ties break by policy typeadvisor-mode.mdKeys()is not portable: 2Q returns frequent-then-recent, ARC recent-then-frequentpolicies.mdThe ordering claims were checked against golang-lru's source: 2Q's
Keysappends its recent list to its frequent one, ARC's appends
t2tot1.Stale names left by #14
The three-phase epoch left the old function name in four places:
docs/design.md's architecture sketch still readrunEpoch -> selectPolicyLocked, andstability.goplus one test commentreferred to a function that no longer exists. That test comment also said the
parked epoch goroutine held the cache mutex; it now holds
banditMuand nocache lock.
Not in this change
AdaptedCache.Keysis documented as "oldest first", which the table aboveshows is false for 2Q and ARC, and
enforceCapacityLockedremoveskeys[0]onthat 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