W3 reasoning-quota wall — public port (ADR-245 Decision 8)

[quantamixsol]

W3 reasoning-quota wall — public port (ADR-245 Decision 8)

Ports the W3 reasoning-quota monetisation wall to the public SDK. This is a
cherry-pick of already-merged private work, not new design:

Private PR	Commit	Public commit here
#316 — reasoning-quota wall	39d4bf48	271d6ae5
#321 — move the wall to the SDK primitive (Decision 8)	88567ae3	bb75efe3

⚠️ Two commits, not one. The public tree had neither, so reasoning_quota.py
arrived as a modify/delete conflict when #321 was picked alone. Both are required in order.

What it does

A free monthly reasoning allowance. Over the cap, a FREE-tier user gets
ReasoningQuotaExceeded and an upgrade CTA; reads and the graph keep working.

Where the wall sits — the whole point of Decision 8

graqle/core/graph.py, three sites:

Site	Why it needs its own gate
areason()	the SDK primitive — CLI, MCP, chat, server/app.py all funnel through it
areason_stream()	builds its own StreamingOrchestrator and never reaches areason()
reason() (sync)	delegates to areason(); deliberately NOT internal=True

Plus cli/commands/debate.py — DebateOrchestrator also reasons outside areason(),
so it carries an explicit check_reasoning_quota().

Rule 1: a wall at one surface is not a wall. The original spec named one bypass;
the audit found three. areason_stream and graq debate are those bypasses.

Rule 2: internal=True means NEVER METERED, not ALREADY METERED. Marking the sync
reason() wrapper internal would have made the entire synchronous API free — the
PR #316 bypass in mirror image. A delegating wrapper must not be internal; only its
delegate charges.

Rule 3: no self-attested env exemptions. internal=True appears only at
benchmark/graq bench callsites in code. There is deliberately no CI=true
exemption — that would be a one-line unlimited-reasoning bypass.

Verification

• Byte-identical to private/master for all 5 implementation files
  (reasoning_gate.py, reasoning_quota.py, debate.py, and both test files).
• 269 licensing tests pass, 1 skipped.
• areason_batch → self.areason(...) with no internal arg ⇒ N-query batch = N units.
• Gate imports are stdlib only + lazy graqle.licensing.*; zero references to
  graqle/cloud/* or graqle/server/*, so there is no ImportError→fail-open path.
• import graqle.cli.main succeeds — no circular import.
• Complete Orchestrator enumeration: no ungated reasoning path exists.

Pre-existing red — not from this diff

tests/test_cli/test_gate_install.py fails 9 of 44 identically on the untouched base
c51d1f26 and on this branch. Verified by checking out the base and re-running.
Unrelated to W3.

Governance — ADR-209

Phase	Status
1 BOOT	✅ 75,871 nodes on bolt, graph_health.degraded: false
2 INVESTIGATE	✅ wheel built + inspected; merge state verified via gh and base advanced
3 BLAST RADIUS	✅ MEDIUM — no escalation
4 PLAN	✅ plan_3859cba5
5–6 GENERATE/APPLY	✅ cherry-pick; graq_edit(strategy="literal") for docs
7 SENTINEL	✅ graq_reason ×2 on the full diff (graq_review is DOWN). Pass 1: 5 BLOCKERs, all self-labelled unverified. Each reproduced against code and refuted with evidence. Pass 2: APPROVE, 0 blockers, 87%
8 PR	✅ this PR
9 LEARN	⏳ after merge

Rule #0 — git remote -v run before push. Public cherry-pick authorised only
because private #321 is merged (mergedAt 2026-07-29T10:53:02Z, base advanced to
65be4f75). Sequential gate satisfied. No version files in this diff; 0.83.0 release
is a separate PR. Stray (inferred from graph) file excluded.

🤖 Generated with Claude Code

---

Update — rebased onto 21c91915 + a real regression fixed

Master gained CR-010.R6 (#244, scheduler contract), which also edits
graqle/core/graph.py. Rebased. GitHub reported MERGEABLE, zero conflicts — R6's
hunks are lines 33–1185, W3's are 1774–2020, no textual overlap.

But MERGEABLE is not correct. Running the suites together after the rebase
surfaced 11–12 real failures that git could not have detected:

Command	Plain master 21c91915	With W3
pytest tests/test_licensing/ tests/test_cli/test_headless_contract.py	249 passed	11 failed

Each file passed alone on both. Ordering-dependent pollution, introduced by W3's tests.

Root cause (traced to a real traceback, not inferred)

test_reasoning_gate.py imported graqle.server.app in-process, leaving
graqle.server in sys.modules. graqle/governance/tamper_evidence/verifier.py::_assert_isolated
(moat-M2 / WS-A3) raises ImportError when any server/studio module is already
loaded. R6's suite is the first to load the verifier after the licensing suite — so the
collision only appears once both features coexist.

Second, worse defect — found while fixing the first

That test imported ReasonRequest from graqle.server.app, which does not define
it (the models live in graqle.server.models), under a bare
except Exception: pytest.skip(...). The ImportError was swallowed, so this security
assertion — no HTTP request field may inject internal=True and buy unmetered
reasoning — never executed on any machine, on private or public.

A skip-on-bare-exception around an import is indistinguishable from a pass.

The fix (one file)

• Probe moved to a subprocess — the server import cannot touch the parent's sys.modules.
• Import corrected to graqle.server.models; widened to cover BatchReasonRequest too.
• Skip narrowed to except ImportError only; anything else now fails.
• Interpreter guard: CI runs the bare pytest shim (ci.yml:42), not
  python -m pytest, so sys.executable may not be the venv holding graqle. Without a
  guard the probe would exit 3 and skip — silently recreating the very defect this
  rewrite fixes. It now asserts import graqle succeeds first and fails loudly.

Evidence

• Security test now runs (was skipping): licensing 270 passed, up 1.
• Mutation-tested twice: probing a field that does exist → rc=1 (the assertion can
  fail); an interpreter that cannot import graqle → rc=1 (guard fails loud, never skips).
• Previously-failing combo: 346 passed, 0 failed.
• graqle.server in sys.modules after the licensing suite → False.
• W3 gates intact at graph.py:1899/1901 (areason) and :2117/2119 (areason_stream);
  sync reason() still ungated by design. R6 intact.
• test_gate_install.py fails 10/608 identically on base and branch — pre-existing,
  proven by checking out the base and re-running.

Sentinel (graq_review DOWN → graq_reason ×2, full graph, non-degraded)

Pass 1 BLOCKED with 2 blockers — both correct this time, and blocker 2's premise
was verified against the real CI config before fixing. Both fixed. Pass 2:
APPROVE, 0 blockers, 92%, unanimous.

Known red — infra, not this diff

Release Gate (PyPI): release_gate prediction provider failed: FileNotFoundError → exit 2.
Documented repo-wide flake (empty GRAQLE_LICENSE, no graqle.json/Neo4j in CI); fails on
8/8 branches including ones that merged fine. Needs an owner-approved infra fix.

---

Update 2 — independent pre-merge review found a paywall bypass

The earlier sentinel passes were process gates on a diff-in-progress. This is a fresh
line-by-line read of the whole change. It found 3 defects, each proven by execution.

🔴 F1 (BLOCKER) — GRAQLE_QUOTA_DIR was a one-line unlimited-reasoning bypass

resolve_quota_dir() honoured the env var unconditionally, so the meter could be
pointed anywhere. Proven: a FREE user at 30/30 gets ReasoningQuotaExceeded; set
GRAQLE_QUOTA_DIR to a fresh temp dir and the same call is allowed.

export GRAQLE_QUOTA_DIR=$(mktemp -d)   # in ~/.bashrc → unlimited free reasoning

Worse than the local-bypass class ADR-245 already accepts (deleting the quota file)
on three counts: it persists via a shell profile (set once, never repeated), it is
non-destructive (nothing looks tampered with), and it needs no repeat action.

It also contradicted this module's own rule — quota_exempt() refuses to honour
CI=true precisely because self-attested env exemptions are banned by Decision 8
rule 3. An env var that relocates the counter is that same bypass wearing a different hat.

Fix: the override is honoured only when "pytest" in sys.modules.

⚠️ My first attempt used PYTEST_CURRENT_TEST — the sentinel correctly called that
theatre: it is itself a self-attested env var, and I reproduced the forgery
(PYTEST_CURRENT_TEST=forged::call → override applied). It was also wrong on
timing — that var is unset during import/collection/session fixtures (measured:
False at import while "pytest" in sys.modules is already True), so a test
resolving the dir there would have silently written to the developer's real
./.graqle. sys.modules cannot be forged from the environment and is true from
process start. Both blockers fixed.

F2 (follow-up) — unbounded file growth

data[month] = used + 1 never pruned. Seeded 36 months → all 36 retained. Now trimmed to
13 months on write; schema_version preserved; unparseable keys left alone.

F3 (follow-up) — peek() disagreed with check_and_record()

peek() checked only the tier. With GRAQLE_ENFORCE_CAPS=0 at the cap it reported
allowed=False while calls actually succeeded. Not user-visible today — its sole
caller is check_and_record's own exempt-path return (grep: 1 hit) — but the two must
not drift.

Evidence

• Mutation-tested ×4 — reverting each fix individually makes its test fail;
  restoring it passes. Verified by editing the source back and re-running.
• Attack now closed end-to-end: forging PYTEST_CURRENT_TEST resolves to .graqle.
• Suite 350 passed / 0 failed (was 346 + 4 new regression tests).
• Sentinel ×2 on these fixes: pass 1 BLOCKED (both blockers correct, both fixed),
  pass 2 APPROVE, 0 blockers, 93%.

[github-actions]

🛡️ GraQle PR Guardian

💥 Blast Radius: 10 modules affected

Module	Files Changed	Risk Level	Impact Radius
graqle	8	🟡 T2	8
tests	2	🟢 T1	2

Total blast radius: 10

---

🏛️ Governance Verdict

⚠️ WARN

• T2: Advisory warnings detected. Review recommended.

---

🔍 SHACL Violations

No SHACL violations detected. ✅

---

🔐 Approval Requirements

This PR requires approval from: T2

• A Senior Engineer or above must approve.

❌ Approval requirement NOT yet satisfied.

---

Metric	Value
Blast Radius	10
Files Analyzed	10
Blocked	0
SHACL Violations	0
Verdict	WARN

---

_{🔬 Powered by GraQle PR Guardian v0.1.0 · Scan completed 2026-07-30T15:42:02.225456+00:00}