Skip to content

docs(decisions): ADR 0033 (Proposed) — idle-time auto-compaction design at the plan gate (#99) - #162

Merged
terenceponce merged 3 commits into
mainfrom
docs/idle-compaction-design
Nov 1, 2026
Merged

terenceponce merged 3 commits into
mainfrom
docs/idle-compaction-design

Conversation

@terenceponce

@terenceponce terenceponce commented Nov 1, 2026 •

Copy link
Copy Markdown
Member

Closes nothing — #99 stays OPEN: this is the design-only lane (the plan gate). ADR 0033 lands in Proposed status and parks at Terence's morning read; the implementation lane opens only on his go.

The design (ADR 0033, Proposed)

A cache-TTL-derived idle timer in the agent, firing the same eviction_pass /compact fires — third caller of one pass, never a third implementation.

  • Idle = two clocks. Agent-idle (status: :idle, the same gate /compact uses — reached by exactly two code paths, reset_turn/1 and fill_cancelled/1) arms the timer; user-idle (@min_quiet 60 s without TUI-forwarded activity) gates the fire. The TTL clock starts at the last episode start (the site that mints request_len — not usage-frame arrival, which is one generation late) and is not reset by typing — the cache's clock is the provider's.
  • The formula: arm_delay = max(@min_quiet, (last_request_at + effective_ttl − margin) − now), margin = max(60 s, 10 % of ttl). Epoch-guarded {:idle_compact, epoch} fire (the suggester's pattern — a stale timer racing cancel_timer into the mailbox is dropped by construction). Monotonic time only; a suspend-paused clock fires late (post-expiry), the safe direction.
  • TTL chain (mirroring /compact answers 'no context window configured' - per-model window coverage is missing #111's window chain): configured settings.compaction.idleTtlSeconds → seeded per-provider (verified numbers only, table filled at implementation) → 300 s default, conservative because assuming-short never misses a harvest while assuming-long fires post-expiry — the unrecoverable mistake (with the honest cost recorded: on an hour-tier provider stage 2 pays a summarize per 300 s window; that trade is open question 4).
  • Honest observability: cached_tokens cannot be the primary TTL derivation (misses are retroactive, confounded by capacity eviction) — argued over the issue's initial lean, and that reversal is gated as open question 1, the owner's to confirm or overturn. Observation gets the two jobs it can do: the telemetry gate (no positive cached-count ever observed ⇒ the timer never arms) and calibration (deferred phase-2 ledger).
  • Same 80% trigger, same floors: arms only strictly past div(window*4,5); the estimate cannot change between arm and fire (the two idle mutators — {:adopt_session, _}, {:set_provider, _} — cancel and clear), so below-threshold sessions never compact by construction. Whole-turn/one-remaining-turn/pinned-system floors inherited unchanged; a no-progress latch bounds oversize sessions to one silent pass per turn.
  • UX: heard when it acts, silent when it doesn't — a dropping fire emits the automatic entry verbatim + persists + records exactly as /compact (additive "source" key); a no-drop fire is silent, latched, and the pass gains an announce policy (one parameter, two policies — no forked loop). The TUI hears a fire through the two messages it already renders for any mutation (entry + context push). No status-line changes, no new render events; the no-timers contract of ADR 0007/the agent moduledoc is the one deliberate bend, amendment note promised at acceptance. No /undo added.
  • Today vs stage 2, honestly: today the win is latency placement — the recorded m1 O(n²) eviction stall (10.1 s @ 20k) moves off the first send; request bytes identical. Stage 2 gets the full economics: the summarize rides the still-warm prefix. §8 pins the timer as stage-invariant and the stage-2 fire as a fail-closed, fail-bounded (twice, then disarm) async summarize episode; prompts queue behind it; give-up is logged, not rendered.
  • m1 answered with a measurement, not a guess: the idle path relocates the stall once per idle window (the latch closes the oversize loop); the implementation lane measures fire time on a 20k fixture and >1 s pulls the running-total refactor in.

5 open questions park at the gate (ADR §9): the derivation itself (chain vs observation-first — the issue's written lean, contravened with argument) · no-telemetry hard-off vs degraded variant · any-key vs submit-only activity · the 300 s default + silent timing · the m1 gate + stage-2 contract.

Also in this PR: the decisions README gains the Proposed status vocabulary (one word + its definition line) — the plan-gate workflow's status, riding here because 0033 is the first ADR to use it. Flagged for the owner's nod.

Captures

Non-visual: docs-only PR (ADR 0033 + decisions README index row); no UI surface to capture.

CI (raw)

$ mix ci; echo "MIX_CI_EXIT=$?"
1963 mods/funs, found no issues.          # credo --strict
Total errors: 0, Skipped: 0, Unnecessary Skips: 0   # dialyzer
Result: 1836 passed
[TOTAL]  99.2%
MIX_CI_EXIT=0

Review disclosure

Hostile DESIGN review: fresh-context agent on zai-coding-plan/glm-5.3, own tab, own read-only worktree, same host — disclosed (the capture-convention charter's arrangement). It attacked the trigger formula, the idle definition, and the failure modes, verifying every code claim in-tree. Arc: FIX-FIRST (4 BLOCKER + 6 FIX + 4 NIT — false choke-point claim, unmodeled {:adopt_session, _}/{:set_provider, _} paths, the {:context, _} render push, the agent's no-timers contract, a one-generation-late TTL anchor, an oversize re-arm loop, an unbounded stage-2 retry) → fixed in 54241c6 → CLEARED → two residual NITs in 7200f37 → CLEARED. Full arc in the review comment.

Lane staffing: architect on zai-coding-plan/glm-5.3; reviewer the same model, fresh context.

@codecov

codecov Bot commented Nov 1, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

…pt/provider resets, episode-start TTL anchor, no-progress latch, announce-policy seam, bounded stage-2 retry, honest context-push render claim, derivation question first
…section refs, log-not-render for the stage-2 give-up
@terenceponce

Copy link
Copy Markdown
Member Author

Hostile design review — the arc

Reviewer: fresh-context glm-5.3, own read-only worktree (~/Work/worktrees/df99-review-design), same host — disclosed. Mandate: attack the trigger formula, the idle definition, the failure modes; verify every code claim in-tree.

Round 1 — VERDICT: FIX-FIRST. 4 BLOCKER + 6 FIX + 4 NIT. The architecture held (timer → arming predicate → the shared eviction_pass; the gate-not-derivation stance; the stage-invariant contract); four "verified in-tree" claims were false, and the reviewer caught them all against the code:

  • B1 reset_turn/1 is not the single idle choke point — fill_cancelled/1 reaches status: :idle inline (agent.ex:1276): a timer armed only at reset_turn never arms after a cancelled tool run.
  • B2 {:adopt_session, _} (the in-session /resume picker) swaps the whole transcript while idle (agent.ex:617) — the estimate can jump, and the old session's TTL evidence would arm against the adopted one.
  • B3 the TUI hears a dropping compaction through the {:context, _} push too (persist/1 → push_context, agent.ex:1640/1749) — "only through the entry" was false, and probe 1 as written was self-contradictory.
  • B4 the agent's moduledoc + ADR 0007 say the agent holds no timers — a contract the design bent without acknowledging it.
  • F5 the TTL clock anchored at usage-frame arrival — one full generation late; a 60 s reply eats the whole 300 s-TTL margin and fires post-expiry.
  • F6 mid-session /model ({:set_provider, _}) reset nothing — provider-scoped facts survived a provider switch.
  • F7 the oversize case re-armed in a loop — every keystroke-then-quiet cycle re-ran the full O(n²) pass.
  • F8 "fully silent" oversize fire was unsatisfiable — the warning lives inside the shared pass.
  • F9 ADR 0022 §8 bent while the header claimed nothing changed.
  • F10 stage-2 fail-retry was an unbounded unattended spend loop (~hundreds of paid summarize attempts overnight).

Round 2 (fix commit 54241c6) — VERDICT: CLEARED. Every finding addressed with a mechanism, not a mention: both idle-arrival sites named (verified: exactly two status: :idle assignments beyond boot); adopt/provider-switch cancel-and-clear rules (§6) + probe; the render claim rescoped to the honest two-messages bound (§5); the no-timers contract explicitly amended with its purpose preserved (§1 + Alternatives + 0007 note at acceptance); the anchor moved to episode start (§1); the no-progress latch (§5/§6/§7); the announce-policy seam named (§5); the 0022 §8 amendment note promised at acceptance; the bounded retry — twice then disarm until the next user turn, give-up logged not rendered (§8). The reviewer also demanded the derivation reversal be gated first: the issue's written lean was observation-derived thresholds; §3 argues chain-over-derivation — that contravention now sits as open question 1, the owner's to confirm or overturn, not settled in prose.

Round 3 (residuals 7200f37) — VERDICT: CLEARED. The two one-clause residuals (disambiguate the ADR 0022 §4/§6 refs; log-not-render for the stage-2 give-up) applied verbatim; diff verified hunk-by-hunk, nothing else in it.

One governance rider, disclosed: the README diff introduces the Proposed status vocabulary (one word in the format list + its definition line) — the plan-gate workflow's new status, riding this PR because this is the first ADR to use it. Flagged for the owner's nod at the gate.

Lane staffing: architect zai-coding-plan/glm-5.3, same-model reviewer (fresh context, own tab, read-only worktree, same host). #99 stays OPEN — implementation gated on the owner's read of ADR 0033 §9.

@terenceponce
terenceponce merged commit 1b18701 into main Nov 1, 2026
5 checks passed
@terenceponce
terenceponce deleted the docs/idle-compaction-design branch November 1, 2026 17:27
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