docs(design): document policy.py, the fail-closed resource limits - #13
Merged
Conversation
Surfaced by the new --audit pass: policy.py was named in no design doc despite being imported by ir.py, parser.py, runtime.py and server.py. The drift report could never have flagged it — the module predates the LLD's last change, which is exactly the class --audit exists to catch. Tabulates all 14 constants and records the scope statement from its docstring: these are conservative defaults for the SINGLE-NODE runtime, not distributed-runtime service-level guarantees. A workload that needs more should split programs or add an authenticated admission layer, not raise the numbers — that distinction is the difference between a limit and a suggestion. Also records that fail-closed means rejected, never truncated: a silently clipped program would execute something the author did not write. Section edited in place; the doc was NOT regenerated. X-Review-Waive: documentation only, no product code touched. Claims traced to policy.py:1-22 and its importers ir.py:34, parser.py:55, runtime.py:48, server.py:31. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
1 participant
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.
First finding from the new
--auditpass, and a clean demonstration of why it exists.policy.pywas named in no design doc, despite being imported byir.py,parser.py,runtime.pyandserver.py. The drift report could never have flagged it — the module predates the LLD's last change, so it sits outside every forward diff. That's precisely the class--auditwas added to catch.What's now documented
All 14 constants, tabulated, plus the scope statement from the module's own docstring:
A workload that needs more should split programs or put an authenticated admission layer in front of the server — not raise the numbers. That distinction is the difference between a limit and a suggestion, and it's the kind of intent a regenerated doc would reduce to "there are some constants."
Also recorded: fail-closed means rejected, never truncated. A silently clipped program would execute something the author didn't write.
Verification
--auditnow reports 0 unnamed for this repo (was 1). 5 pytests pass; drift clean. Section edited in place, not regenerated.🤖 Generated with Claude Code
https://claude.ai/code/session_01VE91emzDnxCY2MWDmuuip7