From 435cca90aa08939190e26be1334fe9ea013d843f Mon Sep 17 00:00:00 2001
From: Minglong Pan <56749246+minglong51@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:58:38 -0700
Subject: [PATCH] docs(design): document policy.py, the fail-closed resource
 limits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 docs/design/LLD.md | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/design/LLD.md b/docs/design/LLD.md
index f9d5bef..1f09444 100644
--- a/docs/design/LLD.md
+++ b/docs/design/LLD.md
@@ -475,7 +475,32 @@ output; on durable failure print `resume with: --store ... --resume <id>`
 
 ## Config / Env Surface
 
-Environment variables (all read in `llm.py`):
+### `policy.py` — fail-closed resource limits
+
+Module-level constants, no env override, imported by `ir.py`, `parser.py`,
+`runtime.py` and `server.py`. Its docstring is the scope statement worth keeping:
+these are **conservative defaults for the single-node runtime, not
+distributed-runtime service-level guarantees** — a workload that needs more should
+split programs or put an authenticated admission layer in front of the server,
+rather than raise the numbers.
+
+| Constant | Value | Bounds |
+|---|---|---|
+| `MAX_SOURCE_BYTES` | 256 KiB | `.thread` source accepted by the parser |
+| `MAX_IR_BYTES` | 1 MiB | serialized IR accepted by `load_ir_bytes` |
+| `MAX_STRING_CHARS` | 64 Ki | any single string value |
+| `MAX_AGENT_ITERS` | 32 | agent-step loop ceiling |
+| `MAX_REGEX_PATTERN_CHARS` / `MAX_REGEX_INPUT_CHARS` | 512 / 64 Ki | regex surface |
+| `REGEX_TIMEOUT_SECONDS` | 1.0 | per-match wall clock — the ReDoS floor |
+| `MAX_REQUEST_BYTES` | 1 MiB | HTTP body |
+| `MAX_INPUTS` / `MAX_INPUT_KEY_CHARS` / `MAX_INPUT_VALUE_CHARS` | 128 / 128 / 64 Ki | run inputs |
+| `DEFAULT_MAX_PENDING_RUNS` / `DEFAULT_MAX_RETAINED_RUNS` | 1 000 / 10 000 | queue + retention |
+| `DEFAULT_LIST_LIMIT` / `MAX_LIST_LIMIT` | 100 / 1 000 | list pagination |
+
+Fail-closed means a value over the limit is rejected, never truncated — a silently
+clipped program would execute something the author did not write.
+
+### Environment variables (all read in `llm.py`)
 
 - `ANTHROPIC_API_KEY` — `AnthropicClient` when no `api_key` passed
   (`llm.py:143`).