Skip to content

Commit ee26c48

Browse files
vsits-proxy-builder[bot]vsits-team-lead-agent[bot]
authored andcommitted
directive: add Non-Functional Requirements section to session-health (NFR standard #161)
Brings the directive into compliance with the revised review standard (PR #161 / AGENTS.md): size budget, threat model (counts-only, read-only on bodies), maintainability, performance, and a Load-bearing? declaration (yes on the schema-contract dimension — extends the per-session JSON; NOT request-body-mutating like #162). Ref #158 #160
1 parent 8e3eaee commit ee26c48

1 file changed

Lines changed: 8 additions & 0 deletions

File tree

docs/directives/proxy-session-health-warning.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,14 @@ Once production `thinking_block_max` telemetry shows the in-context block count
6767
3. **Defaults → anchor tokens, hold blocks.** Token `high` ~340K / `warn` ~250K; no blind block defaults (telemetry-only until data sets them). Conservative early-warn bias retained.
6868
4. **`thinking_block_count` → track both.** Latest-request count (live driver) and `thinking_block_max` high-water (the missing calibration data).
6969

70+
## Non-Functional Requirements
71+
72+
- **Size/complexity budget:** small–moderate — telemetry fields on the existing per-session writer + a token-threshold risk computation + a one-time stderr warn. Reuses `cache-telemetry`'s `usage` read, the per-session quota-status writer, and `onRequest` body access. No new subsystem. ~100–200 LOC + tests; flag at review if it grows materially past that.
73+
- **Threat model:** counts/tokens only. MUST NOT log, persist, or emit thinking text, signatures, or any request/response content — telemetry is numeric (`context_tokens`, `thinking_block_count`, `thinking_block_max`, risk level) plus a content-free warn line. **Read-only on request/response bodies** — this extension observes and records; it never mutates the body. No new inbound surface.
74+
- **Maintainability constraints:** reuse the existing per-session quota-status writer and `cache-telemetry`'s usage extraction; do not introduce a new abstraction for the count/threshold logic. New JSON fields are additive. No dead code, no back-compat shims.
75+
- **Performance/reliability:** O(content-blocks) per request to count thinking blocks; cheap. Because the transform is read-only on the body, it does not churn the prompt-cache prefix.
76+
- **Load-bearing? yes — schema-contract dimension only.** It does **not** modify request/response bodies (unlike the sibling #162 sanitize), so it carries none of the request-path correctness/cache-mutation risk. BUT it extends the per-session quota-status JSON — a wire/schema contract that downstream consumers (statusline, dashboards) read — so it qualifies as load-bearing on the schema dimension. The additions are backward-compatible (new optional fields; existing consumers unaffected). Recommend the `schema-change` label and a brief human (Chris) confirmation that the schema additions don't break existing per-session consumers; it does not carry the request-mutation review burden #162 does.
77+
7078
## Out of scope
7179

7280
- **Fixing or working around the desync** — that's #63172, CC-side. cache-fix must not attempt to mutate/strip thinking blocks to "repair" a session (that path is exactly what #157 guards against). Warning only.

0 commit comments

Comments
 (0)