Skip to content

Official Codebase of 3DCodeVerse

Python

config: one switch grammar — every C3D_* switch is a Settings field; env_flag, skills/config.py and the hand parsers are gone

gaoypenga415484cd02c
diff --git a/eval/bench/ab_plan.py b/eval/bench/ab_plan.py
index 8b6f2212..9f4f327f 100644
--- a/eval/bench/ab_plan.py
+++ b/eval/bench/ab_plan.py
@@ -19,9 +19,8 @@ shell never reaches the control either. With these mechanics the OFF arm is the
means turning skills OFF helped).
Why each arm is a child PROCESS rather than a thread: the switches under test are read
-from the environment (``codeverse3d.tracks.planner.brief_enabled`` reads ``os.environ`` at
-call time; anything under ``Settings`` is read once through an ``lru_cache``), so two
-threads in one interpreter cannot hold different values of them. A child gets exactly
+from the environment (each is a ``Settings`` field, read once per process through an
+``lru_cache``), so two threads in one interpreter cannot hold different values of them. A child gets exactly
the env its arm needs and nothing leaks across. The driver pins both children at
``C3D_MAX_IN_FLIGHT`` (default 16); the in-flight slots are machine-wide lock files, so
the two arms share those 16 with each other and with every other harness process
@@ -130,7 +129,7 @@ log = logging.getLogger(__name__)
DEFAULT_GENERATOR = Backends().generator
DEFAULT_JUDGE = "gemini:gemini-3.1-pro-preview"
#: the per-child cap. The flat name is a first-class alias of ``C3D_RATE__MAX_IN_FLIGHT``
-#: since 2026-08-24 (``Settings._FLAT_ALIASES``; before that it was read by nothing) and
+#: since 2026-08-24 (``Settings.FLAT``; before that it was read by nothing) and
#: wins over the nested spelling when both are set.
MAX_IN_FLIGHT_ENV = "C3D_MAX_IN_FLIGHT"
#: the nested spelling: popped from every child's env so it cannot fight the flat one
@@ -707,13 +706,13 @@ def main(argv: Sequence[str] | None = None) -> int:
# A KEY no code path reads makes the variant arm byte-identical to the control, so
# the battery costs a full run and yields a verdict about nothing. One such A/B is
# on record printing "keep, mean delta +0.344" (CQ-5).
- from codeverse3d.tracks.plan_features import DEAD_SWITCHES, dead_env_keys
+ from codeverse3d.tracks.plan_features import dead_env_keys
dead = dead_env_keys(opts.variant_env)
if dead and len(dead) == len(opts.variant_env):
_parser().error(
"--variant-env only sets switches nothing reads, so both arms would be identical: "
- + "; ".join(f"{k} ({DEAD_SWITCHES[k]})" for k in dead)
+ + ", ".join(dead) + " (no Settings field reads them)"
+ " (pass --aa if an identical-arms calibration run is the point)"
)
if opts.pin_plan and (blockers := pin_plan_blockers(opts.variant_env)):
diff --git a/eval/docs/PAPER_WRITING.md b/eval/docs/PAPER_WRITING.md
index 5578fa62..5da7ef06 100644
--- a/eval/docs/PAPER_WRITING.md
+++ b/eval/docs/PAPER_WRITING.md
@@ -562,9 +562,10 @@ data the repo does not carry; they are marked in the caveat column.
## 9.3 The switches this work added, and their state
-Every one is read at call time and registered in `tracks/plan_features.LIVE_SWITCHES`, which
-a test enforces by grepping the tree; a switch nothing reads once produced "keep, mean delta
-+0.344" on two byte-identical arms, which is why the registry exists.
+Every one is a `Settings` field, and `tracks/plan_features` derives from those fields which
+names are live (since 2026-09-22; before, a hand-kept registry and a test grepping the tree); a
+switch nothing reads once produced "keep, mean delta +0.344" on two byte-identical arms, which
+is why ab_plan refuses one.
| switch | what it does | default | why |
|---|---|---|---|
diff --git a/eval/tests/test_ab_plan_switches.py b/eval/tests/test_ab_plan_switches.py
index 1f0b5925..da859b46 100644
--- a/eval/tests/test_ab_plan_switches.py
+++ b/eval/tests/test_ab_plan_switches.py
@@ -62,17 +62,19 @@ def test_a_skills_ab_spells_its_off_arm_explicitly(monkeypatch):
identical arms, the byte-identical-arms trap tracks/plan_features.py exists for."""
from bench._ab_report import CONTROL, VARIANT
from bench.ab_plan import AbOptions, child_env
- from codeverse3d.skills.config import SKILLS_ENV, skills_enabled
+ from codeverse3d.config import Settings
+
+ skills = "C3D_SKILLS"
def enabled(env: dict[str, str]) -> bool:
- monkeypatch.delenv(SKILLS_ENV, raising=False)
- if SKILLS_ENV in env:
- monkeypatch.setenv(SKILLS_ENV, env[SKILLS_ENV])
- return skills_enabled()
+ monkeypatch.delenv(skills, raising=False)
+ if skills in env:
+ monkeypatch.setenv(skills, env[skills])
+ return Settings().skills
- shell = {"PATH": "/usr/bin", SKILLS_ENV: "0"} # exported in the launching shell: never reaches the control
- off = AbOptions(variant_env={SKILLS_ENV: "0"})
+ shell = {"PATH": "/usr/bin", skills: "0"} # exported in the launching shell: never reaches the control
+ off = AbOptions(variant_env={skills: "0"})
assert enabled(child_env(CONTROL, off, shell)) is True
assert enabled(child_env(VARIANT, off, shell)) is False
- on = AbOptions(variant_env={SKILLS_ENV: "1"})
+ on = AbOptions(variant_env={skills: "1"})
assert enabled(child_env(CONTROL, on, shell)) is enabled(child_env(VARIANT, on, shell)) is True
diff --git a/harness/codeverse3d/config.py b/harness/codeverse3d/config.py
index 502e46db..0e8c6c58 100644
--- a/harness/codeverse3d/config.py
+++ b/harness/codeverse3d/config.py
@@ -7,6 +7,11 @@ written to run records. The names before D78 (``~/.config/codeverse/config.yaml
Gemini keys: ``GEMINI_API_KEYS`` (csv) or ``GEMINI_API_KEY`` or the owner's
``~/.config/astra3d/gemini_keys.env`` file (read-only compatibility).
+
+One switch grammar: every ``C3D_*`` knob the harness reads is a field here, read through
+``get_settings()`` at the call that uses it — no module reads the environment by hand. A
+field ``x`` is ``C3D_X`` (a nested ``section.x`` is ``C3D_SECTION__X``, plus the flat
+spellings in :data:`Settings.FLAT`); an on/off switch is a :data:`Flag`.
"""
from __future__ import annotations
@@ -17,10 +22,20 @@ import re
import shutil
from functools import lru_cache
from pathlib import Path
-from typing import Any, ClassVar, Literal
+from typing import Annotated, Any, ClassVar, Literal
import yaml
-from pydantic import BaseModel, Field, model_validator
+from pydantic import (
+ BaseModel,
+ BeforeValidator,
+ Field,
+ ValidationError,
+ ValidationInfo,
+ ValidatorFunctionWrapHandler,
+ WrapValidator,
+ model_validator,
+)
+from pydantic_core import PydanticUseDefault
from pydantic_settings import BaseSettings, SettingsConfigDict
from codeverse3d.contracts.common import Backends
@@ -31,14 +46,24 @@ _USER_CONFIG = Path.home() / ".config" / "3dcodeverse" / "config.yaml"
_LEGACY_USER_CONFIG = Path.home() / ".config" / "codeverse" / "config.yaml"
-def _lower_bound(model: type[BaseModel], field: str) -> int | None:
- """The ``ge=`` declared on ``model.field`` (None when unbounded). Lets a flat env
- alias enforce exactly the bound its target field declares, in one place."""
- for meta in model.model_fields[field].metadata:
- lo = getattr(meta, "ge", None)
- if lo is not None:
- return int(lo)
- return None
+log = logging.getLogger(__name__)
+
+
+def _or_default(value: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any:
+ """A switch that does not parse warns and keeps its DEFAULT (D44 c): a typo in a bench
+ command runs the arm that never set it — not a crash mid-battery, and not the variant."""
+ try:
+ return handler(value.strip() if isinstance(value, str) else value)
+ except ValidationError:
+ log.warning("C3D_%s=%r does not parse; using the default", (info.field_name or "?").upper(), value)
+ raise PydanticUseDefault() from None
+
+
+#: an on/off switch: on/off, 1/0, true/false, yes/no (any case, t/f and y/n too); anything
+#: else warns and keeps the field's default
+Flag = Annotated[bool, WrapValidator(_or_default)]
+#: a switch that is a count (>= 0); anything else warns and keeps the field's default
+Count = Annotated[int, Field(ge=0), WrapValidator(_or_default)]
class Binaries(BaseModel):
@@ -65,7 +90,9 @@ class Render(BaseModel):
height: int = 768
scene_width: int = 1024
scene_height: int = 576
- gpu: str = Field(default="auto", description="auto | on | off (headless Chrome WebGL backend)")
+ gpu: Annotated[Literal["auto", "on", "off"], BeforeValidator(lambda v: str(v).strip().lower())] = Field(
+ default="auto", description="headless Chrome WebGL backend (C3D_RENDER__GPU, or the flat C3D_RENDER_GPU "
+ "the node side reads too)")
sheet_cols: int = 4
sheet_tile: int = 384
@@ -84,14 +111,14 @@ class Limits(BaseModel):
# render pass, whose tail is minutes long.
max_parallel_agents: int = Field(default=12, ge=1, description="thread fan-out for agent tasks (>= 1)")
max_parallel_builds: int = Field(default=8, ge=1, description="concurrent build subprocesses (>= 1)")
- agent_max_turns: int = Field(
+ agent_max_turns: Count = Field(
default=0,
- ge=0,
description="hard cap on model turns per agent session (0 = the backend's own default, "
"which is what ships: a 28-turn cap cost $0.02 more and 0.205 of a score point in its "
- "own A/B — docs/COST.md §17 — so no profile sets one; name it here if you want one).",
+ "own A/B — docs/COST.md §17 — so no profile sets one; name it here or as "
+ "C3D_AGENT_MAX_TURNS if you want one).",
)
- seed_recipes: bool = Field(
+ seed_recipes: Flag = Field(
default=True,
description="graphics / glsl_shader: paste the cookbook recipes the brief calls for "
"(curtain / aurora / stars / bokehSoft / dropsLayer + the hash / noise / fbm helpers "
@@ -101,7 +128,7 @@ class Limits(BaseModel):
"the prompt carried the verified curtain() recipe five times and the agent used it zero "
"times — round 0 was again a comb of bars (comb_artefact, 0.33); and (eval/bench/out/seed_v1) "
"recipes seeded into the agent's own common.glsl were overwritten before the end of the run. "
- "`C3D_SEED_RECIPES=0` (read at call time by `seed_recipes_enabled`) is the control arm.",
+ "`C3D_SEED_RECIPES=0` is the control arm.",
)
@@ -153,108 +180,39 @@ class Judge(BaseModel):
"Slice render is local CPU; no profile touches this dial (the channel measured ≤ $0).")
-#: The recipe-seeding switch (Limits.seed_recipes). Read at CALL time by
-#: :func:`seed_recipes_enabled`, never only through the cached Settings: ``eval/bench/ab_plan.py``
-#: differs its arms by environment alone, and a value frozen at first ``get_settings()``
-#: would hand the variant the control's behaviour (the CQ-5 lesson, tracks/plan_features.py).
-SEED_RECIPES_ENV = "C3D_SEED_RECIPES"
-#: wire the scene texture pack into the scene loop (a stage before env/zones, and the
-#: pack description in both prompts). OFF by default: it adds an image-model call per
-#: run, and whether it earns that is a measurement nobody has made yet.
-SCENE_TEXTURES_ENV = "C3D_SCENE_TEXTURES"
-_TRUE_WORDS = frozenset({"1", "on", "true", "yes", "y"})
-_FALSE_WORDS = frozenset({"0", "off", "false", "no", "n"})
-
-
-def _env_flag(raw: str, env: str) -> bool:
- word = raw.strip().lower()
- if word in _TRUE_WORDS:
- return True
- if word in _FALSE_WORDS:
- return False
- raise ValueError(f"{env}={raw!r}: expected on/off (1/0, true/false, yes/no)")
-
-
-def env_flag(env: str, fallback: bool) -> bool:
- """``$env`` read NOW (never through the cached Settings — an A/B arm sets it after
- first touch): unset or empty → ``fallback``; garbage → OFF with a warning, because a
- typo in a bench command must produce a control run, not a crash mid-battery (and
- not the variant: ``fallback`` may be on). ``skills/config.py`` reads its switches
- through this too."""
- raw = os.environ.get(env)
- if raw is not None and raw.strip():
- try:
- return _env_flag(raw, env)
- except ValueError as e:
- logging.getLogger(__name__).warning("%s; treating it as off", e)
- return False
- return fallback
-
-
-def scene_textures_enabled() -> bool:
- """Is the scene texture stage on for THIS call? ``$C3D_SCENE_TEXTURES``, else off.
-
- The pack generator (``texturing.plan.scene_texture_pack``) and the prompt snippet that
- describes it (``texture_pack_prompt`` — whose docstring already says "for zone/env
- generation") have existed since the texturing work, but nothing in ``tracks/scene.py``
- called either: the switch `Spec.options.texture` does nothing on this track and the
- generator was never told a pack could exist. Measured on eval/bench/out/scene_baseline
- (2026-09-05): four of the five scored cells' judge complaints are the GROUND being a
- flat untextured colour, in near-identical words, and that is the most consistent
- defect in the battery.
- """
- return env_flag(SCENE_TEXTURES_ENV, False)
-
-
-def seed_recipes_enabled() -> bool:
- """Is recipe seeding (``tracks/graphics.py:seed_recipes``) on for THIS call? ``$C3D_SEED_RECIPES``
- when it is set, else ``Settings.limits.seed_recipes`` (default ON)."""
- return env_flag(SEED_RECIPES_ENV, get_settings().limits.seed_recipes)
-
-
class Settings(BaseSettings):
- model_config = SettingsConfigDict(env_prefix="C3D_", env_nested_delimiter="__", extra="ignore")
-
- #: Flat aliases for nested knobs people actually type. ``C3D_MAX_IN_FLIGHT=16`` was
- #: written into three launch commands and two workflow briefs on 2026-08-24 before anyone
- #: noticed pydantic-settings only reads ``C3D_RATE__MAX_IN_FLIGHT`` — every one of them
- #: silently ran at the default 64. An env knob that is read by nothing is worse than no
- #: knob; both spellings now work and the doctor prints the short one.
- _FLAT_ALIASES: ClassVar[dict[str, tuple[str, str]]] = {
+ # env_ignore_empty: ``C3D_X=`` is unset, never "" (an empty C3D_CACHE_DIR was the cwd)
+ model_config = SettingsConfigDict(env_prefix="C3D_", env_nested_delimiter="__", extra="ignore",
+ env_ignore_empty=True)
+
+ #: Nested knobs that also have a flat spelling — the name the docs, the node side and the
+ #: A/B commands type. ``C3D_MAX_IN_FLIGHT=16`` went into three launch commands on
+ #: 2026-08-24 before anyone noticed only ``C3D_RATE__MAX_IN_FLIGHT`` was read. The flat
+ #: one wins when both are set; the nested field validates it.
+ FLAT: ClassVar[dict[str, tuple[str, str]]] = {
"C3D_MAX_IN_FLIGHT": ("rate", "max_in_flight"),
- # the spelling every doc and gpu_launch.cjs use; only C3D_RENDER__GPU was read
"C3D_RENDER_GPU": ("render", "gpu"),
- SEED_RECIPES_ENV: ("limits", "seed_recipes"),
+ "C3D_SEED_RECIPES": ("limits", "seed_recipes"),
+ "C3D_AGENT_MAX_TURNS": ("limits", "agent_max_turns"),
}
- @model_validator(mode="after")
- def _apply_flat_aliases(self) -> Settings:
- for env, (section, field) in self._FLAT_ALIASES.items():
- raw = os.environ.get(env)
- if raw is None or raw.strip() == "":
- continue
- sub = getattr(self, section)
- value: int | bool | str
- ann = type(sub).model_fields[field].annotation
- if ann is bool:
- value = _env_flag(raw, env)
- elif ann is str: # render.gpu is the only str alias: validate its enum here
- value = raw.strip().lower()
- if value not in ("auto", "on", "off"):
- raise ValueError(f"{env}={raw!r}: expected auto|on|off")
- else:
- try:
- value = int(raw)
- except ValueError as e:
- raise ValueError(f"{env}={raw!r}: expected an integer") from e
- # plain assignment does NOT re-validate (no validate_assignment), so the target
- # field's own bound is enforced here — and the message names the variable the
- # operator actually typed, not the nested field they never heard of.
- lo = _lower_bound(type(sub), field)
- if lo is not None and value < lo:
- raise ValueError(f"{env}={raw!r}: must be >= {lo}")
- setattr(sub, field, value)
- return self
+ @classmethod
+ def settings_customise_sources(cls, settings_cls: Any, init_settings: Any, env_settings: Any,
+ dotenv_settings: Any, file_secret_settings: Any) -> tuple[Any, ...]:
+ """``C3D_*`` beats the yaml files (``get_settings`` passes those as init kwargs, which
+ pydantic-settings ranks FIRST): a switch in a config file must never override the
+ environment an A/B arm runs under."""
+ return env_settings, init_settings, dotenv_settings, file_secret_settings
+
+ @model_validator(mode="before")
+ @classmethod
+ def _flat_spellings(cls, data: Any) -> Any:
+ for env, (section, name) in cls.FLAT.items():
+ raw = os.environ.get(env, "").strip()
+ if raw and isinstance(data, dict):
+ sub = data.get(section) or {}
+ data[section] = {**(sub.model_dump() if isinstance(sub, BaseModel) else sub), name: raw}
+ return data
runs_dir: Path = Field(default=Path("runs"))
cache_dir: Path = Field(default=Path.home() / ".cache" / "codeverse3d")
@@ -292,6 +250,48 @@ class Settings(BaseSettings):
cost_ledger: bool = Field(default=True, description="append one priced row per model call "
"to the run's telemetry/cost.jsonl (or a per-process log)")
+ # ------------------------------------------------------------------ switches
+ # The A/B switches and runtime overrides, each read as C3D_<NAME> at the call that uses
+ # it. An A/B arm is a child process with its own environment (eval/bench/ab_plan.py), and
+ # tracks/plan_features.py derives which C3D_* names are live from these fields.
+ skills: Flag = Field(default=True, description="route, materialise and measure skill bundles "
+ "(D81, on since 2026-09-22); C3D_SKILLS=0 is an A/B's no-skills arm")
+ skills_max: Count = Field(
+ default=5, description="bundles attached to one session (skills design §5.2 law 1)")
+ skills_unverified: Flag = Field(default=True, description="also route the bundles labelled "
+ "inherited-unverified (with it all 17 route; the cap still holds)")
+ skills_only: str = Field(default="", description="comma list: the router considers ONLY these "
+ "bundles, so an effect A/B can attribute its delta to one; an unknown name "
+ "routes nothing, which shows up at once as a variant equal to its control")
+ skills_dir: Path | None = Field(default=None, description="another skill library (tests, the live "
+ "CLI smoke, a private overlay)")
+ plan_brief: Flag = Field(default=True, description="expand the engineering brief before planning "
+ "(object tracks)")
+ plan_restart: Flag = Field(default=True, description="re-sample a degenerate plan from the original "
+ "prompt instead of editing it in context (docs/COST.md §30)")
+ scoped_parts: Flag = Field(default=True, description="per-part scoped baseline sessions for an object "
+ "of 8+ parts")
+ reference_diff: Flag = Field(default=True, description="the judge's reference-image mismatch pass")
+ zone_layouts: Flag = Field(default=True, description="scene track: the L2 zone-layout planner calls")
+ scene_textures: Flag = Field(default=False, description="scene track: generate a texture pack before "
+ "env/zones and describe it in both prompts. OFF: an image-model call per "
+ "run, unmeasured — though 4 of 5 scored cells of scene_baseline "
+ "(2026-09-05) complained about a flat, untextured ground")
+ axis_repair: Flag = Field(default=True, description="articulated track: rewrite a joint axis the "
+ "measured motion proves wrong, before the sweep renders")
+ settle: Flag = Field(default=True, description="scene driver: the boot-time auto-seat")
+ camera_repair: Flag = Field(default=True, description="scene driver: move a camera out of geometry "
+ "(zero triggers on a healthy battery; the case it exists for is fatal)")
+ auto_exposure: Flag = Field(default=False, description="scene driver: bounded scene-wide exposure "
+ "into the healthy band")
+ post: Flag = Field(default=True, description="scene pictures: the GTAO + bloom + grade post chain")
+ stream: Flag = Field(default=True, description="Gemini: stream replies with inter-chunk stall "
+ "detection (a hung buffered read held the socket for the whole attempt)")
+ ipv4: Flag = Field(default=True, description="Gemini: bind the transport to IPv4 (the WSL2 IPv6 "
+ "path dropped responses silently)")
+ runtime_js: Path | None = Field(default=None, description="the node runtime directory; a "
+ "non-editable install must point this at a checkout")
+
# ------------------------------------------------------------------ helpers
def backends(self, **overrides: str | None) -> Backends:
"""The ``Backends`` for a new Spec from the settings defaults. Keyword
@@ -373,8 +373,7 @@ class Settings(BaseSettings):
``C3D_RUNTIME_JS`` overrides the location (the wheel does not package
runtime_js, so a non-editable install MUST point this at a checkout).
Missing dir → a loud error at first use instead of a cryptic node crash."""
- override = os.environ.get("C3D_RUNTIME_JS", "").strip()
- d = Path(override).expanduser() if override else Path(__file__).resolve().parent.parent / "runtime_js"
+ d = self.runtime_js.expanduser() if self.runtime_js else Path(__file__).resolve().parent.parent / "runtime_js"
if not d.is_dir():
raise RuntimeError(
f"runtime_js not found at {d} — install the harness editable (pip install -e harness) "
diff --git a/harness/codeverse3d/doctor.py b/harness/codeverse3d/doctor.py
index 5b7ca6d8..1b418b5c 100644
--- a/harness/codeverse3d/doctor.py
+++ b/harness/codeverse3d/doctor.py
@@ -231,12 +231,12 @@ def check_skills() -> list[Row]:
the wiring gets a check you can run before spending money."""
from codeverse3d.agents.backends import ALLOWED_TOOLS, SYSTEM_SETTINGS
from codeverse3d.skills import bundle_dirs, skills_dir, validate_bundle
- from codeverse3d.skills.config import skills_enabled
from codeverse3d.skills.materialize import SKILL_ROOTS
from codeverse3d.skills.registry import ROUTED_SKILLS
- rows: list[Row] = [("skills switch", "OK" if skills_enabled() else "WARN",
- "C3D_SKILLS on (the default since 2026-09-22)" if skills_enabled()
+ on = get_settings().skills
+ rows: list[Row] = [("skills switch", "OK" if on else "WARN",
+ "C3D_SKILLS on (the default since 2026-09-22)" if on
else "C3D_SKILLS=0: no skill is attached to any session")]
dirs = bundle_dirs()
if not dirs:
diff --git a/harness/codeverse3d/judges/vlm_judge.py b/harness/codeverse3d/judges/vlm_judge.py
index 7e687f0c..3f672a9b 100644
--- a/harness/codeverse3d/judges/vlm_judge.py
+++ b/harness/codeverse3d/judges/vlm_judge.py
@@ -27,7 +27,7 @@ from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Literal
-from codeverse3d.config import env_flag, get_settings
+from codeverse3d.config import get_settings
from codeverse3d.contracts.artifacts import Judgment, RenderView
from codeverse3d.contracts.chat import ChatRequest, ChatResponse
from codeverse3d.contracts.common import Usage
@@ -347,7 +347,6 @@ NEUTRAL_SCORE = 0.5
#: ``*_34`` names are the pre-D47 rig, kept for re-judging stored runs.
DIFF_VIEW_NAMES: tuple[str, ...] = ("front", "front_right_high", "front_left_high", "right", "left",
"front_right_34", "front_left_34")
-_ENV_DIFF = "C3D_REFERENCE_DIFF"
def iou_to_score(iou: float) -> float:
@@ -355,8 +354,8 @@ def iou_to_score(iou: float) -> float:
def _diff_enabled(flag: bool) -> bool:
- """``$C3D_REFERENCE_DIFF`` at call time; a typo reads as OFF (``config.env_flag``)."""
- return flag and env_flag(_ENV_DIFF, True)
+ """``flag`` unless ``C3D_REFERENCE_DIFF`` switched the pass off (``Settings.reference_diff``)."""
+ return flag and get_settings().reference_diff
def _is_synth(note: str) -> bool:
diff --git a/harness/codeverse3d/models/gemini.py b/harness/codeverse3d/models/gemini.py
index b6226d58..d37dd2ea 100644
--- a/harness/codeverse3d/models/gemini.py
+++ b/harness/codeverse3d/models/gemini.py
@@ -14,7 +14,6 @@ from __future__ import annotations
import io
import logging
-import os
import re
import threading
import time
@@ -195,7 +194,7 @@ _RETRY_DELAY_RE = re.compile(r"retryDelay['\"]?\s*:\s*['\"]?(\d+(?:\.\d+)?)s")
#: rest of the retry budget intact, while a legitimate 930 s plan streams tokens
#: continuously (145 tok/s p50, audit 2026-08-27) and is bounded only by its
#: attempt budget. Generous vs the longest silent prefix we allow for thinking
-#: before the first chunk. ``C3D_STREAM=0`` restores the buffered call.
+#: before the first chunk. ``C3D_STREAM=off`` restores the buffered call.
STREAM_STALL_S = 300.0
_pools: dict[tuple[str, ...], KeyPool] = {}
@@ -294,15 +293,11 @@ def _ipv4_client_args() -> dict[str, Any]:
"""Bind the sync transport to IPv4. Every one of tonight's five hung reads sat
on an IPv6 destination (2001:4860::/32) with the response headers never arriving
— the WSL2 IPv6 path drops these silently and a buffered read then holds the
- socket for the whole attempt budget. ``C3D_IPV4=0`` restores the default
+ socket for the whole attempt budget. ``C3D_IPV4=off`` restores the default
(dual-stack) resolution."""
- if os.environ.get("C3D_IPV4", "1") == "0":
- return {}
- return {"transport": httpx.HTTPTransport(local_address="0.0.0.0")}
-
+ from codeverse3d.config import get_settings
-def _streaming_enabled() -> bool:
- return os.environ.get("C3D_STREAM", "1") != "0"
+ return {"transport": httpx.HTTPTransport(local_address="0.0.0.0")} if get_settings().ipv4 else {}
def _drain_stream(
@@ -506,7 +501,9 @@ class GeminiModel:
warnings: list[str],
) -> ChatResponse:
client = _client_for(key, self.timeout_s, self._client_factory)
- if not _streaming_enabled():
+ from codeverse3d.config import get_settings
+
+ if not get_settings().stream: # C3D_STREAM=off: the buffered call
with Stopwatch() as sw:
resp = client.models.generate_content(
model=self.model, contents=contents, config=config
diff --git a/harness/codeverse3d/skills/__init__.py b/harness/codeverse3d/skills/__init__.py
index fbe933c1..862e75e2 100644
--- a/harness/codeverse3d/skills/__init__.py
+++ b/harness/codeverse3d/skills/__init__.py
@@ -28,7 +28,6 @@ is behind ``C3D_SKILLS``: ON by default since 2026-09-22, ``C3D_SKILLS=0`` turns
from __future__ import annotations
import logging
-import os
from collections.abc import Iterator
from pathlib import Path
@@ -43,15 +42,14 @@ from codeverse3d.skills.model import (
log = logging.getLogger(__name__)
-#: point the library somewhere else (tests, the live CLI smoke, a private overlay)
-SKILLS_DIR_ENV = "C3D_SKILLS_DIR"
-
-
def skills_dir() -> Path:
- """The bundle root, resolved at call time so an installed wheel works too."""
- override = os.environ.get(SKILLS_DIR_ENV, "").strip()
+ """The bundle root (``C3D_SKILLS_DIR`` points it elsewhere), resolved at call time so an
+ installed wheel works too."""
+ from codeverse3d.config import get_settings
+
+ override = get_settings().skills_dir
if override:
- return Path(override).expanduser()
+ return override.expanduser()
try:
from importlib.resources import files
@@ -105,12 +103,10 @@ def load_skill(name: str, root: Path | None = None) -> Skill:
return parse_skill(d)
-from codeverse3d.skills.config import skills_enabled, skills_max, skills_unverified # noqa: E402
from codeverse3d.skills.materialize import attach_skills, materialize_skills # noqa: E402
from codeverse3d.skills.registry import plan_signals, select, skills_for # noqa: E402
from codeverse3d.skills.telemetry import probe_reads # noqa: E402
-__all__ = ["SKILLS_DIR_ENV", "Skill", "SkillError", "SkillRef", "all_skills", "attach_skills", "bundle_dirs",
+__all__ = ["Skill", "SkillError", "SkillRef", "all_skills", "attach_skills", "bundle_dirs",
"iter_skills", "load_skill", "materialize_skills", "plan_signals", "probe_reads", "select",
- "skills_dir", "skills_enabled", "skills_for", "skills_max", "skills_unverified",
- "validate_bundle"]
+ "skills_dir", "skills_for", "validate_bundle"]
diff --git a/harness/codeverse3d/skills/config.py b/harness/codeverse3d/skills/config.py
deleted file mode 100644
index 22ad2b44..00000000
--- a/harness/codeverse3d/skills/config.py
+++ /dev/null
@@ -1,94 +0,0 @@
-"""The three switches that gate the whole skill system — read from the environment NOW.
-
-WHY not ``Settings``: ``codeverse3d.config.get_settings`` is ``lru_cache``d, so a value
-read through it is frozen at first touch and an A/B arm that sets the variable after
-import gets the control's behaviour. ``eval/bench/ab_plan.py`` differs its arms only by
-environment, and a wave once printed "keep, mean delta +0.344" for two byte-identical
-arms because the switch it flipped was read by nothing at all
-(``codeverse3d/tracks/plan_features.py``). So: one module, read at call time, registered
-in ``plan_features.LIVE_SWITCHES``, and a test that greps the tree to prove it is read.
-
-* ``C3D_SKILLS`` — ON by default (2026-09-22). On = route, materialise, measure;
- ``C3D_SKILLS=0`` turns the whole system off (an A/B's no-skills arm must say so explicitly:
- ``ab_plan.py --variant-env C3D_SKILLS=0``).
-* ``C3D_SKILLS_MAX`` — attached bundles per session (default 5, design §5.2 law 1).
-* ``C3D_SKILLS_UNVERIFIED`` — also route bundles labelled ``inherited-unverified`` (the
- cadquery / threejs forms and the four scene-graphics ports). ON by default with the
- switch above, so all 17 bundles route; ``C3D_SKILLS_UNVERIFIED=0`` drops those six.
-* ``C3D_SKILLS_ONLY`` — comma list; the router may consider ONLY these bundles.
-
-WHY both defaults flipped ON (owner, 2026-09-22). They shipped OFF on 2026-08-25/26
-because the in-process ``api-agent`` read 0 of 5 routed bundles and the A/B could not
-resolve an effect (docs/SKILLS.md §6). That backend was deleted 2026-08-28; every
-backend left is a vendor CLI with its own native skill loader, and the 2026-09-22 live
-probes (docs/SKILLS_LEDGER.md §0b) watched gemini-cli, claude-code, codex and agy each
-activate all four routed bundles of a chair baseline unprompted and leave the control
-alone — read from the CLI's own tool calls, not from atime. Skills are part of the
-product now; measuring an effect is the A/B's job.
-
-WHY ``C3D_SKILLS_ONLY`` exists. An effect A/B has to attribute its delta to ONE bundle,
-and ``C3D_SKILLS=1`` routes up to five. Restricting the LIBRARY (rather than filtering
-the selection afterwards) is the semantics that keeps the arms honest: the named bundle
-is routed exactly where its own table rows fire, and the cap never silently drops it in
-favour of a higher-priority sheet that is not under test. An unknown name yields an
-empty library — every session then attaches nothing, which shows up immediately as a
-variant arm identical to its control, rather than quietly measuring the full set.
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-
-from codeverse3d.config import env_flag
-
-log = logging.getLogger(__name__)
-
-SKILLS_ENV = "C3D_SKILLS"
-SKILLS_MAX_ENV = "C3D_SKILLS_MAX"
-SKILLS_UNVERIFIED_ENV = "C3D_SKILLS_UNVERIFIED"
-SKILLS_ONLY_ENV = "C3D_SKILLS_ONLY"
-
-DEFAULT_SKILLS_MAX = 5
-def skills_enabled() -> bool:
- """Is the skill system on for this process? Default ON since 2026-09-22; ``C3D_SKILLS=0``
- (or ``off``) is the one way to turn it off — and a garbage value reads as off, never as
- the variant (``config.env_flag``)."""
- return env_flag(SKILLS_ENV, True)
-
-
-def skills_unverified() -> bool:
- """Route bundles whose evidence label is ``inherited-unverified``? Default yes since
- 2026-09-22, so the whole library routes; the per-session cap (5) still holds."""
- return env_flag(SKILLS_UNVERIFIED_ENV, True)
-
-
-def skills_only() -> frozenset[str]:
- """The bundles the router may consider, or empty for "all of them".
-
- Read at call time like the other three, for the same reason: an A/B arm sets it in
- the child's environment and a value frozen at import would hand the variant the
- control's library.
- """
- raw = os.environ.get(SKILLS_ONLY_ENV, "")
- return frozenset(n.strip() for n in raw.split(",") if n.strip())
-
-
-def skills_max(default: int = DEFAULT_SKILLS_MAX) -> int:
- """Cap on bundles attached to one session. A bad value falls back, never crashes a run."""
- raw = os.environ.get(SKILLS_MAX_ENV, "").strip()
- if not raw:
- return default
- try:
- n = int(raw)
- except ValueError:
- log.warning("%s=%r is not an integer; using %d", SKILLS_MAX_ENV, raw, default)
- return default
- if n < 0:
- log.warning("%s=%d is negative; using 0", SKILLS_MAX_ENV, n)
- return 0
- return n
-
-
-__all__ = ["DEFAULT_SKILLS_MAX", "SKILLS_ENV", "SKILLS_MAX_ENV", "SKILLS_ONLY_ENV",
- "SKILLS_UNVERIFIED_ENV", "skills_enabled", "skills_max", "skills_only", "skills_unverified"]
diff --git a/harness/codeverse3d/skills/materialize.py b/harness/codeverse3d/skills/materialize.py
index 6bfd8d73..c5066c71 100644
--- a/harness/codeverse3d/skills/materialize.py
+++ b/harness/codeverse3d/skills/materialize.py
@@ -40,7 +40,7 @@ from contextlib import suppress
from pathlib import Path
from typing import Any
-from codeverse3d.skills.config import SKILLS_ONLY_ENV, skills_max, skills_only, skills_unverified
+from codeverse3d.config import get_settings
from codeverse3d.skills.model import Selection, Skill, SkillsMaterialized
from codeverse3d.skills.prompting import (
AGENTS_SKILL_ROOT,
@@ -182,8 +182,8 @@ def attach_skills(
) -> SkillsMaterialized:
"""Route → write → return what a session will see. The one entry point tracks call.
- The caller decides whether the feature is on (``config.skills_enabled``); this
- function assumes it is, so a test can attach without setting the environment.
+ The caller decides whether the feature is on (``Settings.skills``); this function
+ assumes it is, so a test can attach without setting the environment.
``only`` (env ``C3D_SKILLS_ONLY``) restricts the LIBRARY before routing, which is
what an effect A/B needs: the delta then belongs to one bundle instead of to whatever
@@ -191,20 +191,21 @@ def attach_skills(
filtering ``sel`` afterwards — also stops the cap from spending a slot on a bundle
that is not under test and then dropping the one that is.
"""
- picked = skills_only() if only is None else only
+ cfg = get_settings()
+ picked = frozenset(n.strip() for n in cfg.skills_only.split(",") if n.strip()) if only is None else only
if picked:
from codeverse3d.skills import all_skills
lib = dict(all_skills() if library is None else library)
library = {n: s for n, s in lib.items() if n in picked}
if not library:
- log.warning("%s=%s matches no bundle in the library; this session attaches nothing",
- SKILLS_ONLY_ENV, ",".join(sorted(picked)))
+ log.warning("C3D_SKILLS_ONLY=%s matches no bundle in the library; this session attaches nothing",
+ ",".join(sorted(picked)))
sel: list[Selection] = select(
track, language, kind,
signals=plan_signals(plan), findings=findings, library=library,
- max_skills=skills_max() if max_skills is None else max_skills,
- allow_unverified=skills_unverified() if allow_unverified is None else allow_unverified,
+ max_skills=cfg.skills_max if max_skills is None else max_skills,
+ allow_unverified=cfg.skills_unverified if allow_unverified is None else allow_unverified,
)
out = SkillsMaterialized(listed=[s.name for s in sel], selections=list(sel),
reasons={s.name: s.reason for s in sel}, attached_at=time.time())
diff --git a/harness/codeverse3d/spatial/render_scene.py b/harness/codeverse3d/spatial/render_scene.py
index f20ff174..e7f71ab6 100644
--- a/harness/codeverse3d/spatial/render_scene.py
+++ b/harness/codeverse3d/spatial/render_scene.py
@@ -21,7 +21,7 @@ from collections.abc import Sequence
from pathlib import Path
from typing import Any
-from codeverse3d.config import env_flag, get_settings
+from codeverse3d.config import get_settings
from codeverse3d.contracts.artifacts import RenderSet, RenderView
from codeverse3d.contracts.plan import BBox, CameraPlan
from codeverse3d.conventions import SCENE_VIEWS, ViewPreset
@@ -120,21 +120,21 @@ def run_scene_script(script: str, args: Sequence[str], *, timeout_s: float, cwd:
def probe_env_args() -> list[str]:
- """Scene-driver flags from the ``C3D_*`` switches — the ONE parser (review-3 S4),
- on the canonical ``env_flag`` words, so ``C3D_CAMERA_REPAIR=false`` really
- disables and ``C3D_AUTO_EXPOSURE=true`` really enables. Every driver
- invocation — standalone probe, render, and the combined single-boot build —
- appends these, so a census is always measured under the same settle /
- camera-repair / auto-exposure policy the renders use."""
+ """Scene-driver flags from the ``C3D_SETTLE`` / ``C3D_CAMERA_REPAIR`` /
+ ``C3D_AUTO_EXPOSURE`` switches (``Settings``). Every driver invocation — standalone
+ probe, render, and the combined single-boot build — appends these, so a census is
+ always measured under the same settle / camera-repair / auto-exposure policy the
+ renders use."""
+ s = get_settings()
args: list[str] = []
- if not env_flag("C3D_SETTLE", True): # A/B switch for the boot-time auto-seat
+ if not s.settle: # A/B switch for the boot-time auto-seat
args.append("--no-settle")
- if env_flag("C3D_CAMERA_REPAIR", True): # default ON since 2026-08-30: pure insurance —
+ if s.camera_repair: # default ON since 2026-08-30: pure insurance —
# zero triggers across a whole healthy battery (scene_px_v1: layout camera-clearance
# already keeps lenses out of furniture), and the one class it exists for
# (fv_izakaya: three rounds of camera_in_geometry nobody could fix) is fatal.
args.append("--camera-repair")
- if env_flag("C3D_AUTO_EXPOSURE", False): # opt-in: bounded scene-wide exposure into the healthy band
+ if s.auto_exposure: # opt-in: bounded scene-wide exposure into the healthy band
args.append("--auto-exposure")
return args
@@ -145,7 +145,7 @@ def post_chain_args() -> list[str]:
PICTURES only: object renders never touch this driver, and the scene probe runs
raw because it is a 320x180 geometry instrument, not a judged frame. Kept out
of :func:`probe_env_args` for exactly that reason."""
- return [] if env_flag("C3D_POST", True) else ["--no-post"]
+ return [] if get_settings().post else ["--no-post"]
def _camera_json(cams: Sequence[CameraPlan]) -> str:
diff --git a/harness/codeverse3d/tracks/articulated_object.py b/harness/codeverse3d/tracks/articulated_object.py
index 279af1b0..ca38fb95 100644
--- a/harness/codeverse3d/tracks/articulated_object.py
+++ b/harness/codeverse3d/tracks/articulated_object.py
@@ -9,12 +9,12 @@ renders a pose sheet which is appended to the judge's views.
from __future__ import annotations
import logging
-import os
import time
import xml.etree.ElementTree as ET
from collections.abc import Sequence
from pathlib import Path
+from codeverse3d.config import get_settings
from codeverse3d.contracts.artifacts import (
BuildResult,
GateFinding,
@@ -59,7 +59,7 @@ class ArticulatedPipeline(ObjectPipeline):
def _axis_repair(ctx: RunContext) -> list[str]:
"""Measure → deterministically fix wrong joint axes BEFORE the sweep renders,
so this round's poses, renders and judge all see the corrected motion."""
- if os.environ.get(AXIS_REPAIR_ENV) == "0":
+ if not get_settings().axis_repair:
return []
try:
pre = ctx.services.motion_checks(ctx.ws, ctx.plan)
@@ -226,10 +226,6 @@ def axis_fix_hint(joint_name: str, axis: Sequence[float] | None, expected: str)
return f"negate the <axis> of joint '{joint_name}' in src/robot.urdf (or swap lower/upper) so motion goes {expected}"
-#: kill-switch for the deterministic axis repair (default ON, mirrors C3D_CAMERA_REPAIR)
-AXIS_REPAIR_ENV = "C3D_AXIS_REPAIR"
-
-
def _set_axis_in_urdf_text(text: str, urdf_joint: str, axis: tuple[float, float, float]) -> str | None:
"""``text`` with joint ``urdf_joint``'s ``<axis xyz>`` replaced (inserted when
missing). String surgery instead of an XML round-trip so authored comments and
@@ -285,7 +281,7 @@ def repair_motion_axes(ws: Workspace, report: GateReport | None) -> list[str]:
authored file and the built ``artifacts/robot.urdf`` copy are updated so the
re-run gate and the pose sweep see the repair. Returns repaired plan-joint
names; a finding without measured data (``cos``) is never touched."""
- if report is None or os.environ.get(AXIS_REPAIR_ENV) == "0":
+ if report is None or not get_settings().axis_repair:
return []
src = ws.src / "robot.urdf"
if not src.is_file():
diff --git a/harness/codeverse3d/tracks/depth.py b/harness/codeverse3d/tracks/depth.py
index 5908f338..bb0c4b87 100644
--- a/harness/codeverse3d/tracks/depth.py
+++ b/harness/codeverse3d/tracks/depth.py
@@ -115,11 +115,11 @@ MIN_PARTS_FOR_SCOPED = 8
DEFAULT_PARTS_PER_SCOPE = 3
-def scoped_generation_enabled(default: bool = True) -> bool:
- """``C3D_SCOPED_PARTS=off|0|false`` turns per-part scoped baselines off (A/B, debugging)."""
- from codeverse3d.config import env_flag
+def scoped_generation_enabled() -> bool:
+ """``C3D_SCOPED_PARTS=off`` turns per-part scoped baselines off (A/B, debugging)."""
+ from codeverse3d.config import get_settings
- return env_flag("C3D_SCOPED_PARTS", default)
+ return get_settings().scoped_parts
@dataclass(frozen=True)
diff --git a/harness/codeverse3d/tracks/generation.py b/harness/codeverse3d/tracks/generation.py
index 074f4615..04a210c7 100644
--- a/harness/codeverse3d/tracks/generation.py
+++ b/harness/codeverse3d/tracks/generation.py
@@ -34,7 +34,6 @@ attempt then raises. The label, round and outcome of each call are on the ledge
from __future__ import annotations
import logging
-import os
import re
import shutil
from collections.abc import Callable, Collection
@@ -249,22 +248,14 @@ WRAPUP_PROMPT = (
def agent_max_turns(default: int = DEFAULT_AGENT_MAX_TURNS) -> int:
- """The turn cap a machine asks for: ``C3D_AGENT_MAX_TURNS`` >
- ``Settings.limits.agent_max_turns`` > ``default``.
+ """The turn cap a machine asks for: ``Settings.limits.agent_max_turns`` (also spelled
+ ``C3D_AGENT_MAX_TURNS``) > ``default``.
``0`` means *no cap*: the caller leaves ``AgentJob.max_turns`` at the backend's
own default. That is the measured default (docs/COST.md §17)."""
- raw = os.environ.get("C3D_AGENT_MAX_TURNS", "").strip()
- if raw.isdigit() and int(raw) > 0:
- return int(raw)
- try:
- from codeverse3d.config import get_settings
+ from codeverse3d.config import get_settings
- configured = int(getattr(get_settings().limits, "agent_max_turns", 0) or 0)
- except Exception as e: # noqa: BLE001 — settings must never break a generation
- log.debug("agent turn cap fell back to the default: %s", e)
- configured = 0
- return max(0, configured or int(default))
+ return get_settings().limits.agent_max_turns or max(0, int(default))
def turn_capped(res: Any) -> bool:
diff --git a/harness/codeverse3d/tracks/graphics.py b/harness/codeverse3d/tracks/graphics.py
index 77ae64ea..56d11e43 100644
--- a/harness/codeverse3d/tracks/graphics.py
+++ b/harness/codeverse3d/tracks/graphics.py
@@ -19,7 +19,7 @@ from dataclasses import dataclass
from pathlib import Path
from typing import Any
-from codeverse3d.config import seed_recipes_enabled
+from codeverse3d.config import get_settings
from codeverse3d.contracts.artifacts import (
BuildResult,
GateReport,
@@ -250,7 +250,7 @@ def seed_recipes(ctx: RunContext) -> list[str]:
(a resume appends only names the file does not define yet); return the names written THIS call.
``ctx.extra["seeded_recipes"]`` lists every seeded recipe on disk (for the prompt block);
``recipes.seeded`` is emitted with both. No-op unless glsl_shader and enabled."""
- if ctx.language is not Language.GLSL_SHADER or not seed_recipes_enabled():
+ if ctx.language is not Language.GLSL_SHADER or not get_settings().limits.seed_recipes:
return []
known = cookbook_functions(ctx.cookbook_text or "")
chapters = recipe_chapters(ctx)
diff --git a/harness/codeverse3d/tracks/plan_features.py b/harness/codeverse3d/tracks/plan_features.py
index 536d8cc7..acdaa23b 100644
--- a/harness/codeverse3d/tracks/plan_features.py
+++ b/harness/codeverse3d/tracks/plan_features.py
@@ -1,26 +1,42 @@
-"""The A/B switch registry: which env switches any code path ACTUALLY reads.
-
-Born as the switchboard for the plan-loop-engineering wave (CQ-5): six features were
-declared under ``C3D_PLAN_FEATURES``, none was ever implemented, and one A/B run is on
-record printing "keep, mean delta +0.344" for two byte-identical arms. The feature
-runtime (``parse_features`` / ``plan_feature_on``) was deleted 2026-08-28 per its own
-instruction, and the six names with it (2026-09-22); what remains is the guard rail —
-:data:`LIVE_SWITCHES` / :data:`DEAD_SWITCHES` (kept honest by
-``tests/orchestrator_tracks/test_plan_features.py``, which greps the tree) and the
-``--pin-plan`` blocker rule ``eval/bench/ab_plan.py`` consults so a paired A/B cannot
-silently pin away the very thing it is testing.
+"""What an A/B rig may assume about a ``C3D_*`` switch — ``eval/bench/ab_plan.py`` asks.
+
+Eval-only: no runtime module imports this. Every switch the harness reads is a ``Settings``
+field (``config.py``), so which names are live is derived from ``Settings.model_fields``
+instead of a hand-kept list: an arm that differs only by a name no field reads is
+byte-identical to its control (one A/B printed "keep, mean delta +0.344" for two such arms,
+CQ-5), and ``ab_plan`` refuses it. ``pin_plan_blockers`` keeps ``--pin-plan`` from sharing
+one plan across arms whose switch acts at or before planning.
"""
from __future__ import annotations
-PLAN_FEATURES_ENV = "C3D_PLAN_FEATURES"
+from codeverse3d.config import Settings
-#: env switches that act AFTER planning — ``--pin-plan`` may share one plan across arms
-#: that differ only by these. Anything not listed is treated as plan-side: refusing to
-#: pin costs one noisy A/B, pinning wrongly costs a confident wrong answer
-#: (eval/docs/EVAL.md §8.1 measured it — the A/A's worst pair differed 1 part vs 10).
+#: switches that act AFTER planning — ``--pin-plan`` may share one plan across arms that
+#: differ only by these. Anything else is treated as plan-side: refusing to pin costs one
+#: noisy A/B, pinning wrongly costs a confident wrong answer (eval/docs/EVAL.md §8.1
+#: measured it — the A/A's worst pair differed 1 part vs 10).
GENERATION_SIDE_ENV: frozenset[str] = frozenset({"C3D_SKILLS", "C3D_SKILLS_MAX", "C3D_SKILLS_UNVERIFIED",
"C3D_SKILLS_ONLY", "C3D_REFERENCE_DIFF", "C3D_SEED_RECIPES"})
+#: the two the node side reads itself (runtime_js: gpu_launch.cjs, browser_daemon.cjs)
+NODE_SIDE_ENV: frozenset[str] = frozenset({"C3D_BROWSER_REUSE", "C3D_PAGE_TTL_MS"})
+
+
+def _read(key: str) -> bool:
+ """Does any ``Settings`` field — or the node side — read the environment variable ``key``?"""
+ if key in Settings.FLAT or key in NODE_SIDE_ENV:
+ return True
+ section, _, name = key.removeprefix("C3D_").lower().partition("__")
+ field = Settings.model_fields.get(section)
+ if not name:
+ return field is not None
+ return field is not None and name in getattr(field.annotation, "model_fields", {})
+
+
+def dead_env_keys(env: dict[str, str]) -> list[str]:
+ """The ``C3D_*`` keys of ``env`` that no Settings field reads — empty when the arm really
+ differs. A key outside the ``C3D_`` family is not judged (it may matter to a CLI)."""
+ return sorted(k for k in env if k.startswith("C3D_") and not _read(k))
def pin_plan_blockers(variant_env: dict[str, str]) -> list[str]:
@@ -28,53 +44,12 @@ def pin_plan_blockers(variant_env: dict[str, str]) -> list[str]:
Empty list = every switch this A/B changes acts after planning, so both arms can be
seeded with the same ``plan.json`` and the paired difference stops carrying the
- planner's spread (the dominant variance term, eval/docs/EVAL.md §8.1). A
- :data:`DEAD_SWITCHES` key blocks nothing: no code reads it, so it cannot change a plan.
+ planner's spread (the dominant variance term, eval/docs/EVAL.md §8.1). A dead key
+ blocks nothing: no code reads it, so it cannot change a plan.
"""
+ dead = set(dead_env_keys(variant_env))
return [f"{key} is not known to act after planning" for key in sorted(variant_env)
- if key not in GENERATION_SIDE_ENV and key not in DEAD_SWITCHES]
-
-#: Plan-loop switches the tree ACTUALLY reads, name → the module that reads it. Kept
-#: honest by tests/orchestrator_tracks/test_plan_features.py, which greps the tree.
-LIVE_SWITCHES: dict[str, str] = {
- "C3D_PLAN_BRIEF": "codeverse3d/tracks/planner.py", # brief.py merged in, 2026-08-28
- # re-sample a degenerate plan from the original prompt instead of editing it in context
- "C3D_PLAN_RESTART": "codeverse3d/tracks/planner.py",
- "C3D_SCOPED_PARTS": "codeverse3d/tracks/depth.py",
- "C3D_REFERENCE_DIFF": "codeverse3d/judges/vlm_judge.py", # reference.py merged in, 2026-08-28
- # the skill system (design: scratchpad/skills/design/DESIGN.md §6.5). All three are
- # read at call time by one module, so an A/B arm that sets them really differs.
- "C3D_SKILLS": "codeverse3d/skills/config.py",
- "C3D_SKILLS_MAX": "codeverse3d/skills/config.py",
- "C3D_SKILLS_UNVERIFIED": "codeverse3d/skills/config.py",
- "C3D_SKILLS_ONLY": "codeverse3d/skills/config.py",
- "C3D_SEED_RECIPES": "codeverse3d/config.py",
- # wire the scene texture pack into the scene loop: a stage before env/zones, and the
- # pack description (texturing.plan.texture_pack_prompt) in both prompts. OFF by
- # default — it costs an image-model call per run and nobody has measured what it buys.
- "C3D_SCENE_TEXTURES": "codeverse3d/config.py",
- # model-transport switches (2026-08-28, the hung-read waves): streaming with
- # inter-chunk stall detection, and the IPv4-only transport. Read at call time
- # by every gemini request, so a control arm can set either to 0.
- "C3D_STREAM": "codeverse3d/models/gemini.py",
- "C3D_IPV4": "codeverse3d/models/gemini.py",
-}
-
-#: Switches that are DECLARED but read by no code path, with the reason. An A/B arm that
-#: differs only by one of these is byte-identical to its control, so ``ab_plan`` refuses
-#: it: a rig that cannot tell a live switch from a dead one produces confident verdicts
-#: about nothing. A name leaves this dict in the same commit as the code that reads it.
-DEAD_SWITCHES: dict[str, str] = {
- PLAN_FEATURES_ENV: "none of its six features was ever implemented; nothing reads this variable",
- "C3D_DETAIL_ROUNDS": "the surface-detail round went with the judgement stops that offered it (2026-09-22)",
- "C3D_FEWER_TURNS": "the fewer-turns bundle was deleted after its A/B read out flat (2026-09-22, COST §29)",
-}
-
-
-def dead_env_keys(env: dict[str, str]) -> list[str]:
- """The keys of ``env`` that no code path reads — empty when the arm really differs."""
- return sorted(k for k in env if k in DEAD_SWITCHES)
+ if key not in GENERATION_SIDE_ENV and key not in dead]
-__all__ = ["DEAD_SWITCHES", "GENERATION_SIDE_ENV", "LIVE_SWITCHES", "PLAN_FEATURES_ENV", "dead_env_keys",
- "pin_plan_blockers"]
+__all__ = ["GENERATION_SIDE_ENV", "NODE_SIDE_ENV", "dead_env_keys", "pin_plan_blockers"]
diff --git a/harness/codeverse3d/tracks/planner.py b/harness/codeverse3d/tracks/planner.py
index 999245d1..538cf4dc 100644
--- a/harness/codeverse3d/tracks/planner.py
+++ b/harness/codeverse3d/tracks/planner.py
@@ -48,8 +48,6 @@ log = logging.getLogger(__name__)
# ===================================================================== the brief
-#: env switch: ``off``/``0``/``false`` disables brief expansion for the run
-BRIEF_ENV = "C3D_PLAN_BRIEF"
#: tracks the object-shaped brief applies to (graphics/scene get budgets only)
BRIEF_TRACKS = (Track.STATIC_OBJECT, Track.ARTICULATED_OBJECT)
BRIEF_TEMPLATE = "tracks/brief_object.j2"
@@ -57,11 +55,11 @@ BRIEF_MAX_TOKENS = 65_536
# ----------------------------------------------------------------------------- brief
-def brief_enabled(spec: Spec, *, default: bool = True) -> bool:
- """Whether to expand the brief for this spec (env switch wins; object tracks only)."""
- from codeverse3d.config import env_flag # ONE flag vocabulary (review-3 S4)
+def brief_enabled(spec: Spec) -> bool:
+ """Whether to expand the brief for this spec (``C3D_PLAN_BRIEF``; object tracks only)."""
+ from codeverse3d.config import get_settings
- return env_flag(BRIEF_ENV, default) and spec.track in BRIEF_TRACKS
+ return get_settings().plan_brief and spec.track in BRIEF_TRACKS
def brief_cache_dir() -> Path:
@@ -594,8 +592,6 @@ MAX_QUALITY_REASKS = 1
#: in context; at most this many times per plan. Measured 2026-09-02: 3-4 % of plan calls
#: end this way, and both in-context re-asks reproduce the same broken plan verbatim.
MAX_PLAN_RESTARTS = 1
-#: kill-switch for that restart (default ON, mirrors C3D_AXIS_REPAIR)
-PLAN_RESTART_ENV = "C3D_PLAN_RESTART"
#: Output room for the plan call, sized from the plan budget. A deep plan is much longer
#: JSON than a flat one AND Gemini 3.x bills its thinking against the same ceiling, so the
#: flat 24 000 that served 8 box-parts truncates a 12-part plan with sub-parts —
@@ -714,10 +710,10 @@ def restart_note(raw: Any, missing: list[str], budget: PlanBudget) -> str:
def restart_enabled() -> bool:
- """Kill switch for the degenerate-plan restart, ON by default (docs/COST.md §30)."""
- from codeverse3d.config import env_flag # ONE flag vocabulary (review-3 S4)
+ """Kill switch for the degenerate-plan restart (``C3D_PLAN_RESTART``, ON; docs/COST.md §30)."""
+ from codeverse3d.config import get_settings
- return env_flag(PLAN_RESTART_ENV, True)
+ return get_settings().plan_restart
#: an invalid plan attempt is written here, so a run that DIES at the plan stage still says
@@ -1096,7 +1092,7 @@ def normalise_names[P: BaseModel](plan_obj: P) -> P:
__all__ = ["MAX_PLAN_RESTARTS", "MAX_QUALITY_REASKS", "MAX_VALIDATION_REASKS",
- "PLAN_RESTART_ENV", "PLAN_TOKENS_MAX", "PlanningError", "add_acceptance_item",
+ "PLAN_TOKENS_MAX", "PlanningError", "add_acceptance_item",
"articulation_acceptance", "build_system_prompt", "build_user_prompt", "plan_event_stats",
"ensure_acceptance", "missing_link_names", "normalise_names", "plan",
"degenerate_plan", "plan_example", "plan_temperature", "plan_tokens", "restart_enabled",
diff --git a/harness/codeverse3d/tracks/scene.py b/harness/codeverse3d/tracks/scene.py
index c004b7cd..edbb5169 100644
--- a/harness/codeverse3d/tracks/scene.py
+++ b/harness/codeverse3d/tracks/scene.py
@@ -26,7 +26,7 @@ import time
from collections.abc import Callable, Sequence
from typing import Any
-from codeverse3d.config import scene_textures_enabled
+from codeverse3d.config import get_settings
from codeverse3d.contracts.artifacts import (
BuildResult,
GateFinding,
@@ -186,9 +186,7 @@ class SceneTrack(BaseTrack):
# so the two stages' commits cannot race.
def _layouts() -> dict[str, Any]:
"""L2 zone layouts (optional accelerator): planner-model calls, never fatal."""
- from codeverse3d.config import env_flag
-
- if not env_flag("C3D_ZONE_LAYOUTS", True): # A/B switch, default on; canonical words
+ if not get_settings().zone_layouts: # C3D_ZONE_LAYOUTS: an A/B switch, default on
return {}
try:
model = self._planner_model
@@ -209,9 +207,9 @@ class SceneTrack(BaseTrack):
# hit a stale cached stage. Old "assets+env" composite entries are ignored.
key = {"plan": plan, "agent": ctx.agent_id}
# textures first and alone: env and zones can only name the files if they exist by
- # the time those prompts are built (config.scene_textures_enabled explains why this
+ # the time those prompts are built (Settings.scene_textures says why this
# is off by default and what it costs)
- if scene_textures_enabled():
+ if get_settings().scene_textures:
ctx.extra["textures"] = runner.stage("textures", lambda: self._textures_stage(ctx), inputs={"plan": plan}) or {}
stage_fns: dict[str, Any] = {"assets": lambda: run_asset_stage(ctx),
"env": lambda: self._env_stage(ctx), "layouts": _layouts}
diff --git a/harness/codeverse3d/tracks/skills_hook.py b/harness/codeverse3d/tracks/skills_hook.py
index 86648231..514c299e 100644
--- a/harness/codeverse3d/tracks/skills_hook.py
+++ b/harness/codeverse3d/tracks/skills_hook.py
@@ -6,8 +6,8 @@ workspace conventions, no environment) and testable without a run. Kept out of
Everything here is a no-op when ``C3D_SKILLS=0`` (the system is ON by default since
2026-09-22), and every function swallows its own failures: a skill that cannot be routed,
-written or probed must cost that skill, not the round. The switch is read at CALL time
-(see ``skills/config.py`` for why). ``record_usage`` reads what the round's sessions did
+written or probed must cost that skill, not the round. The switch is ``Settings.skills``,
+read at the call. ``record_usage`` reads what the round's sessions did
from their CLIs' own tool calls (``skills/telemetry.probe_reads``), atime only as fallback.
"""
@@ -57,12 +57,13 @@ def _previous_findings(ctx: RunContext, index: int) -> list[GateReport]:
def attach_for_round(ctx: RunContext, *, index: int, kind: str) -> Any | None:
"""Route + materialise this round's skills. Returns the ``SkillsMaterialized``."""
- from codeverse3d.skills import attach_skills, skills_enabled
+ from codeverse3d.config import get_settings
+ from codeverse3d.skills import attach_skills
# drop the previous round's set first: a failure below must not leave this round
# probing — and crediting — bundles it never attached
ctx.extra.pop(CTX_KEY, None)
- if not skills_enabled():
+ if not get_settings().skills:
return None
try:
got = attach_skills(
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index cb11b6d0..385a4a51 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -75,7 +75,11 @@ codeverse3d/
to_snake/to_pascal/slugify, MAX_TRIS_*, BBOX_TOLERANCE_M, CONTACT_GAP_M (THE source)
config.py Settings (C3D_* env, ~/.config/3dcodeverse/config.yaml; role defaults come from
contracts Backends; Settings.backends(**overrides) builds a Spec's Backends;
- default_candidates=1)
+ default_candidates=1). ONE switch grammar: every C3D_* knob is a field, read
+ through get_settings() where it is used — no module reads the environment by
+ hand; an on/off switch is a Flag (on/off/1/0/true/false/yes/no; a typo warns
+ and keeps the default), Settings.FLAT holds the four flat spellings of nested
+ knobs (C3D_MAX_IN_FLIGHT, C3D_RENDER_GPU, C3D_SEED_RECIPES, C3D_AGENT_MAX_TURNS)
contracts/ pydantic: common (Track, Language, Usage, Budget, Backends, TRACK_INFO registry,
ENTRY_FILE/code_file/LANGUAGE_LABEL tables), spec (+ RunOptions), plan, artifacts
(GateFinding.as_line, GateReport.of, BuildResult.gates, RenderView.judge,
@@ -148,7 +152,8 @@ codeverse3d/
(per-backend delivery policy + the index/mandate text),
materialize.py,
telemetry.py (the read probe: the CLIs' own tool calls first, atime as
- fallback), config.py (call-time switches; skills ON by default since 2026-09-22)
+ fallback); its switches are Settings fields (C3D_SKILLS*, ON by default since
+ 2026-09-22)
cost/ types.py (CallCost/Stage/Role) ledger.py (append-only telemetry/cost.jsonl + price provenance)
context.py (per-call > ambient attribution) instrument.py (MeteredChatModel /
MeteredAgent — one row per ChatModel.generate; one session row only for a backend
@@ -197,9 +202,9 @@ codeverse3d/
(C3D_PLAN_BRIEF), plan budgets and the worked examples — and the ONE owner of
what differs per track when planning: template, example, temperature, output
floor, acceptance, all dispatched on spec.track),
- plan_features.py (the A/B switch registry: LIVE_SWITCHES / DEAD_SWITCHES,
- + pin_plan_blockers() deciding when two arms may share one plan —
- eval/docs/EVAL.md §8.1),
+ plan_features.py (eval-only: which C3D_* names are live, derived from
+ Settings, and pin_plan_blockers() deciding when two arms may share one
+ plan — eval/docs/EVAL.md §8.1),
depth.py,
skills_hook.py (the round's view of codeverse3d/skills: attach before generating,
probe reads after — a no-op under C3D_SKILLS=0; on by default since 2026-09-22)
diff --git a/harness/docs/INSTALL.md b/harness/docs/INSTALL.md
index cd2c8eae..31ff191a 100644
--- a/harness/docs/INSTALL.md
+++ b/harness/docs/INSTALL.md
@@ -428,10 +428,14 @@ export C3D_LIMITS__AGENT_TIMEOUT_S=900
export C3D_DEFAULT_CANDIDATES=2
```
-Three more are read directly by the runtime (not via `Settings`):
-`C3D_RENDER_GPU` (`auto|on|off`, seen by the node/moderngl renderers),
-`C3D_CACHE_DIR` (where `gpu_launch.cjs` puts the shared-browser endpoint file)
-and `C3D_BROWSER_REUSE=off` (disable the shared headless-Chrome daemon).
+Every knob the harness reads is a `Settings` field (`codeverse3d/config.py`, one
+description each): `C3D_<FIELD>` at the top level, `C3D_<SECTION>__<FIELD>` nested, plus
+four flat spellings of nested knobs — `C3D_MAX_IN_FLIGHT`, `C3D_RENDER_GPU`,
+`C3D_SEED_RECIPES`, `C3D_AGENT_MAX_TURNS`. An on/off switch (`C3D_SKILLS`, `C3D_STREAM`,
+`C3D_PLAN_BRIEF`, … — every `Flag` field) takes on/off, 1/0, true/false or yes/no in any
+case; a typo warns and keeps the default, and an empty value is unset. The node side also
+reads `C3D_RENDER_GPU` and `C3D_CACHE_DIR` itself, and one variable only it reads:
+`C3D_BROWSER_REUSE=off` disables the shared headless-Chrome daemon.
---
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index f0acb1b6..96fd0e1b 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -36,8 +36,9 @@ BuildResult.gates: list[GateReport] # the build's own reports (scene_probe + s
# tracks/steps appends them to the round's gates, after the track's, built or not
RenderView.judge: bool | None # stamped True/False at render time; None = legacy round (every stored view is judged)
RenderSet.out_dir: str # directory the views (+ views.json/metrics.json) were written to ("" on old rounds)
-from codeverse3d.config import get_settings, env_flag # env_flag(env, fallback) -> bool: on/off/1/0/true/false/yes/no;
- # unset/empty -> fallback; garbage -> warning + False (off, NOT the fallback), never a crash
+from codeverse3d.config import get_settings, Flag # every C3D_* switch is a Settings field (C3D_X -> .x,
+ # C3D_S__X -> .s.x, Settings.FLAT for four flat spellings); Flag: on/off/1/0/true/false/yes/no, any case;
+ # unset/empty -> the default; garbage -> warning + the DEFAULT, never a crash
get_settings().backends(planner=..., generator=..., judge=..., captioner=...) -> Backends
# settings defaults (default_planner/... mirror contracts Backends literals; + default_captioner);
# truthy keyword overrides win, None/"" falls through, unknown role -> TypeError
@@ -476,7 +477,7 @@ from codeverse3d.tracks.prompting import select_cookbook_chapters, is_always_cha
# select_cookbook_chapters(ctx, brief, *, budget=9000, always=COOKBOOK_ALWAYS) -> list[Section]: the header +
# always-on chapters + the brief's chapters (whole, cookbook order, inside budget)
from codeverse3d.tracks.graphics import seed_recipes, graphics_brief, cookbook_functions, EXTRA_KEY, RECIPES_REL
- # seed_recipes(ctx) -> list[str]: glsl_shader + seed_recipes_enabled() only. Writes the selected chapters'
+ # seed_recipes(ctx) -> list[str]: glsl_shader + Settings.limits.seed_recipes only. Writes the selected chapters'
# function definitions (minus always-on chapters and the raymarching template) + the helpers they call to
# the HARNESS-OWNED src/recipes.glsl (RECIPES_REL; header "// harness-owned: … READ-ONLY …"; a resume appends
# only names the file lacks); returns the names written THIS call; ctx.extra["seeded_recipes"] =
diff --git a/harness/tests/conftest.py b/harness/tests/conftest.py
index de6e54dd..ff4bdf4e 100644
--- a/harness/tests/conftest.py
+++ b/harness/tests/conftest.py
@@ -23,6 +23,22 @@ def _fresh_settings():
get_settings.cache_clear()
+def switch(monkeypatch):
+ """``switch("C3D_X", "off")`` sets (``None``: unsets) one variable and drops the cached
+ Settings, so the next ``get_settings()`` reads it the way a fresh A/B child would."""
+ from codeverse3d.config import get_settings
+
+ def set_(name: str, raw: str | None) -> None:
+ if raw is None:
+ monkeypatch.delenv(name, raising=False)
+ else:
+ monkeypatch.setenv(name, raw)
+ get_settings.cache_clear()
+
+ return set_
+
+
@pytest.fixture
def tmp_ws(tmp_path: Path) -> Workspace:
"""A fresh, git-initialised workspace under a temp dir."""
diff --git a/harness/tests/core/test_config_env_aliases.py b/harness/tests/core/test_config_env_aliases.py
index 3e4ca5c5..556c8e9d 100644
--- a/harness/tests/core/test_config_env_aliases.py
+++ b/harness/tests/core/test_config_env_aliases.py
@@ -1,11 +1,52 @@
-"""Flat environment aliases and layered configuration."""
+"""One switch grammar, the flat spellings, and layered configuration."""
from __future__ import annotations
+import logging
+
import pytest
+from pydantic import WrapValidator
from codeverse3d.config import Settings
+#: every on/off switch, by the name an operator types (nested ones by their flat spelling)
+_FLAGS = sorted([(f"C3D_{name.upper()}", field.default) for name, field in Settings.model_fields.items()
+ if field.annotation is bool and any(isinstance(m, WrapValidator) for m in field.metadata)]
+ + [("C3D_SEED_RECIPES", True)])
+
+
+def test_the_switches_are_the_ones_the_harness_reads():
+ """A guard on the list the next test walks: every switch with its shipped default."""
+ assert dict(_FLAGS) == {
+ "C3D_AUTO_EXPOSURE": False, "C3D_AXIS_REPAIR": True, "C3D_CAMERA_REPAIR": True, "C3D_IPV4": True,
+ "C3D_PLAN_BRIEF": True, "C3D_PLAN_RESTART": True, "C3D_POST": True, "C3D_REFERENCE_DIFF": True,
+ "C3D_SCENE_TEXTURES": False, "C3D_SCOPED_PARTS": True, "C3D_SEED_RECIPES": True, "C3D_SETTLE": True,
+ "C3D_SKILLS": True, "C3D_SKILLS_UNVERIFIED": True, "C3D_STREAM": True, "C3D_ZONE_LAYOUTS": True}
+
+
[email protected](("env", "default"), _FLAGS)
+def test_every_switch_speaks_one_grammar(monkeypatch, caplog, env, default):
+ """``C3D_STREAM=off``, ``C3D_IPV4=off`` and ``C3D_AXIS_REPAIR=off`` were silently ignored
+ until 2026-09-22 (only "0" was read), fourteen switches were parsed by hand, and a typo
+ in ``C3D_FEWER_TURNS`` crashed. Now: on/off, 1/0, true/false, yes/no in any case and
+ padding; empty is unset; anything else warns and keeps the default (D44 c)."""
+ def read(raw: str | None) -> bool:
+ if raw is None:
+ monkeypatch.delenv(env, raising=False)
+ else:
+ monkeypatch.setenv(env, raw)
+ s = Settings()
+ return s.limits.seed_recipes if env == "C3D_SEED_RECIPES" else getattr(s, env[4:].lower())
+
+ assert read(None) is default and read("") is default
+ for word in ("off", "0", "false", "no", "OFF", " Off "):
+ assert read(word) is False, word
+ for word in ("on", "1", "true", "yes", "ON"):
+ assert read(word) is True, word
+ with caplog.at_level(logging.WARNING, logger="codeverse3d.config"):
+ assert read("maybe") is default
+ assert env in caplog.text
+
def test_flat_and_nested_max_in_flight_aliases(monkeypatch):
monkeypatch.delenv("C3D_RATE__MAX_IN_FLIGHT", raising=False)
@@ -18,12 +59,13 @@ def test_flat_and_nested_max_in_flight_aliases(monkeypatch):
assert Settings().rate.max_in_flight == 8
-def test_empty_alias_is_ignored_and_garbage_is_loud(monkeypatch):
+def test_empty_is_unset_and_garbage_in_a_sizing_knob_is_loud(monkeypatch):
+ """A cap is not a switch: an unparsable one stops the run before it starts."""
monkeypatch.delenv("C3D_RATE__MAX_IN_FLIGHT", raising=False)
monkeypatch.setenv("C3D_MAX_IN_FLIGHT", "")
assert Settings().rate.max_in_flight == 64
monkeypatch.setenv("C3D_MAX_IN_FLIGHT", "sixteen")
- with pytest.raises(ValueError, match="C3D_MAX_IN_FLIGHT"):
+ with pytest.raises(ValueError, match="max_in_flight"):
Settings()
@@ -40,7 +82,7 @@ def test_render_gpu_is_read_by_both_spellings_and_garbage_is_loud(monkeypatch):
monkeypatch.setenv("C3D_RENDER__GPU", "off")
assert Settings().render.gpu == "off"
monkeypatch.setenv("C3D_RENDER_GPU", "maybe")
- with pytest.raises(ValueError, match="C3D_RENDER_GPU"):
+ with pytest.raises(ValueError, match="gpu"):
Settings()
@@ -48,7 +90,7 @@ def test_a_negative_cap_is_rejected_by_both_spellings(monkeypatch):
"""Both spellings reject negative caps; zero remains the unlimited sentinel."""
monkeypatch.delenv("C3D_RATE__MAX_IN_FLIGHT", raising=False)
monkeypatch.setenv("C3D_MAX_IN_FLIGHT", "-5")
- with pytest.raises(ValueError, match="C3D_MAX_IN_FLIGHT"): # names the variable they typed
+ with pytest.raises(ValueError, match="max_in_flight"):
Settings()
monkeypatch.delenv("C3D_MAX_IN_FLIGHT")
monkeypatch.setenv("C3D_RATE__MAX_IN_FLIGHT", "-5")
@@ -63,10 +105,11 @@ def test_the_rate_and_limits_dials_carry_their_bounds(monkeypatch):
for kwargs in ({"max_in_flight": -1}, {"hedge": 0}):
with pytest.raises(ValueError):
Rate(**kwargs)
- for kwargs in ({"max_parallel_agents": 0}, {"max_parallel_builds": -2}, {"agent_max_turns": -1}):
+ for kwargs in ({"max_parallel_agents": 0}, {"max_parallel_builds": -2}):
with pytest.raises(ValueError):
Limits(**kwargs)
assert Rate(max_in_flight=0).max_in_flight == 0, "0 stays legal: it means unlimited"
+ assert Limits(agent_max_turns=-1).agent_max_turns == 0, "a switch: a bad cap warns and asks for none"
# --------------------------------------------------------------------------- yaml layering
@@ -104,6 +147,18 @@ def test_a_project_file_overrides_only_the_keys_it_names(tmp_path, monkeypatch):
os.environ.pop("C3D_PROFILE", None)
+def test_the_environment_beats_the_config_files_per_setting(monkeypatch):
+ """docs/INSTALL.md §8.3 promises "... < project config < C3D_* env", but get_settings hands
+ the yaml to Settings as init kwargs, which pydantic-settings ranked ABOVE the environment:
+ a `skills: true` in a config file silently overrode an A/B arm's C3D_SKILLS=0 (the
+ switches became Settings fields 2026-09-22, so this now decides A/B arms)."""
+ for name, raw in (("C3D_SKILLS", "0"), ("C3D_RUNS_DIR", "/from_env"), ("C3D_JUDGE__SAMPLES", "3")):
+ monkeypatch.setenv(name, raw)
+ s = Settings(skills=True, runs_dir="/from_yaml", judge={"samples": 2, "max_px": 512})
+ assert (s.skills, str(s.runs_dir), s.judge.samples) == (False, "/from_env", 3)
+ assert s.judge.max_px == 512, "a yaml sibling the environment does not name survives"
+
+
def test_deep_merge_overlays_per_key_at_every_depth():
from codeverse3d.config import _deep_merge
diff --git a/harness/tests/install/test_docs.py b/harness/tests/install/test_docs.py
index ba9fbf0b..894e6116 100644
--- a/harness/tests/install/test_docs.py
+++ b/harness/tests/install/test_docs.py
@@ -232,7 +232,7 @@ def test_doctor_rows_have_troubleshooting_entries(monkeypatch) -> None:
from codeverse3d.proc import ProcResult
settings = SimpleNamespace(
- gemini_api_keys=("fake",), anthropic_api_key="", openai_api_key="",
+ gemini_api_keys=("fake",), anthropic_api_key="", openai_api_key="", skills=False,
rate=SimpleNamespace(max_in_flight=1),
binaries=SimpleNamespace(node="node", gemini_cli="gemini", claude_cli="claude",
codex_cli="codex", agy_cli="agy"),
diff --git a/harness/tests/models/test_gemini.py b/harness/tests/models/test_gemini.py
index 950493a7..93470154 100644
--- a/harness/tests/models/test_gemini.py
+++ b/harness/tests/models/test_gemini.py
@@ -389,25 +389,28 @@ def test_drain_stream_cuts_a_stream_past_its_attempt_budget():
assert e.value.retryable and "attempt budget" in str(e.value)
-def test_streaming_toggle(monkeypatch):
- from codeverse3d.models.gemini import _streaming_enabled
-
- monkeypatch.delenv("C3D_STREAM", raising=False)
- assert _streaming_enabled()
- monkeypatch.setenv("C3D_STREAM", "0")
- assert not _streaming_enabled()
-
-
-def test_ipv4_transport_toggle(monkeypatch):
[email protected](("raw", "streamed"), [(None, True), ("0", False), ("off", False), ("OFF", False),
+ ("on", True), ("garbage", True)])
+def test_streaming_toggle(monkeypatch, switch, raw, streamed):
+ """``C3D_STREAM=off`` was silently ignored until 2026-09-22: only "0" was read."""
+ switch("C3D_STREAM", raw)
+ calls: list[int] = []
+ real = FakeModels.generate_content_stream
+ monkeypatch.setattr(FakeModels, "generate_content_stream", lambda self, **kw: (calls.append(1), real(self, **kw))[1])
+ m, _log, _ = make_model([text_response("hi")])
+ assert m.generate(ChatRequest(messages=[ChatMessage.user("x")])).text == "hi"
+ assert bool(calls) is streamed
+
+
[email protected](("raw", "bound"), [(None, True), ("0", False), ("off", False), ("no", False), ("1", True)])
+def test_ipv4_transport_toggle(switch, raw, bound):
+ """``C3D_IPV4=off`` was silently ignored until 2026-09-22: only "0" restored dual-stack."""
import httpx
from codeverse3d.models.gemini import _ipv4_client_args
- monkeypatch.delenv("C3D_IPV4", raising=False)
- args = _ipv4_client_args()
- assert isinstance(args["transport"], httpx.HTTPTransport)
- monkeypatch.setenv("C3D_IPV4", "0")
- assert _ipv4_client_args() == {}
+ switch("C3D_IPV4", raw)
+ assert isinstance(_ipv4_client_args().get("transport"), httpx.HTTPTransport) is bound
def test_merge_stream_chunks_concatenates_text_and_keeps_final_usage():
diff --git a/harness/tests/orchestrator_tracks/test_generation_depth.py b/harness/tests/orchestrator_tracks/test_generation_depth.py
index a523226f..a467b22a 100644
--- a/harness/tests/orchestrator_tracks/test_generation_depth.py
+++ b/harness/tests/orchestrator_tracks/test_generation_depth.py
@@ -72,12 +72,12 @@ def test_interfaces_text_names_only_the_neighbours_outside_the_scope(chair_plan)
assert "no parts outside this scope" in empty
-def test_scoped_generation_can_be_switched_off(monkeypatch):
- monkeypatch.setenv("C3D_SCOPED_PARTS", "off")
+def test_scoped_generation_can_be_switched_off(switch):
+ switch("C3D_SCOPED_PARTS", "off")
assert scoped_generation_enabled() is False
- monkeypatch.setenv("C3D_SCOPED_PARTS", "on")
+ switch("C3D_SCOPED_PARTS", "on")
assert scoped_generation_enabled() is True
- monkeypatch.delenv("C3D_SCOPED_PARTS")
+ switch("C3D_SCOPED_PARTS", None)
assert scoped_generation_enabled() is True
diff --git a/harness/tests/orchestrator_tracks/test_graphics_recipes.py b/harness/tests/orchestrator_tracks/test_graphics_recipes.py
index e11ef80a..77f154a8 100644
--- a/harness/tests/orchestrator_tracks/test_graphics_recipes.py
+++ b/harness/tests/orchestrator_tracks/test_graphics_recipes.py
@@ -8,7 +8,7 @@ from types import SimpleNamespace
import pytest
-from codeverse3d.config import Settings, seed_recipes_enabled
+from codeverse3d.config import Settings, get_settings
from codeverse3d.contracts.common import HARNESS_OWNED_SRC, Language, Track
from codeverse3d.contracts.plan import GraphicsPlan
from codeverse3d.languages import get_runtime
@@ -25,7 +25,6 @@ from codeverse3d.languages.glsl_shader import (
from codeverse3d.languages.glsl_shader import HEADER as WRAP_HEADER
from codeverse3d.proc import EventLog
from codeverse3d.prompts import load_text, render
-from codeverse3d.tracks import graphics as gr
from codeverse3d.tracks.graphics import (
HEADER,
NOT_SEEDED,
@@ -267,23 +266,27 @@ def test_resume_appends_only_new_names(tmp_path) -> None:
def test_gate_and_language(tmp_path, monkeypatch) -> None:
+ def seeding(raw: str | None) -> bool:
+ if raw is None:
+ monkeypatch.delenv("C3D_SEED_RECIPES", raising=False)
+ else:
+ monkeypatch.setenv("C3D_SEED_RECIPES", raw)
+ get_settings.cache_clear()
+ return get_settings().limits.seed_recipes
+
ws = _ws(tmp_path)
- assert Settings().limits.seed_recipes is True and seed_recipes_enabled() is True
- monkeypatch.setenv("C3D_SEED_RECIPES", "0")
- assert seed_recipes_enabled() is False
+ assert seeding(None) is True
+ assert seeding("0") is False
ctx = _ctx(ws)
assert seed_recipes(ctx) == [] and not _recipes(ws).exists() and "seeded_recipes" not in ctx.extra
assert (ws.src / "common.glsl").read_text() == COMMON_GLSL and not _seeded_events(ws)
- monkeypatch.setenv("C3D_SEED_RECIPES", "garbage")
- assert seed_recipes_enabled() is False # a typo is a control run, not a crash
- monkeypatch.setenv("C3D_SEED_RECIPES", "on")
- assert seed_recipes_enabled() is True
- monkeypatch.delenv("C3D_SEED_RECIPES")
- monkeypatch.setattr(gr, "seed_recipes_enabled", lambda: True)
+ assert seeding("garbage") is True # a typo keeps the default: never a crash, never the arm
+ assert seeding("on") is True and seeding("off") is False
+ assert seeding(None) is True
assert seed_recipes(_ctx(ws, language=Language.OPENGL_PYTHON)) == [] # opengl_python: nothing seeded
assert not _recipes(ws).exists() and (ws.src / "common.glsl").read_text() == COMMON_GLSL
- monkeypatch.setenv("C3D_SEED_RECIPES", "off")
- assert Settings().limits.seed_recipes is False # the flat alias reaches Settings too
+ monkeypatch.setenv("C3D_LIMITS__SEED_RECIPES", "off")
+ assert Settings().limits.seed_recipes is False # the nested spelling reads the same field
# ----------------------------------------------------------------------------- compose / lint / prompt
diff --git a/harness/tests/orchestrator_tracks/test_plan_features.py b/harness/tests/orchestrator_tracks/test_plan_features.py
index 82341572..341ac7f9 100644
--- a/harness/tests/orchestrator_tracks/test_plan_features.py
+++ b/harness/tests/orchestrator_tracks/test_plan_features.py
@@ -1,59 +1,34 @@
-"""``tracks/plan_features.py``: the switch registry that keeps A/B rigs honest about
-which env switches any code actually reads (CQ-5)."""
+"""``tracks/plan_features.py``: what an A/B rig may assume about a ``C3D_*`` switch (CQ-5).
-from __future__ import annotations
-
-from functools import cache
-from pathlib import Path
-
-import pytest
-
-from codeverse3d.tracks import plan_features as F
-
-# --------------------------------------------------------------------------- CQ-5
-HARNESS = Path(__file__).resolve().parents[2]
-
-
-@cache
-def _sources() -> tuple[tuple[str, str], ...]:
- """(relpath, text) for every harness source, read ONCE per session.
-
- Only ``codeverse3d`` counts: a switch is live when the HARNESS reads it. The evaluation
- scripts (``eval/bench``) set switches for an A/B; they are not what makes one live.
- """
- out = []
- for p in (HARNESS / "codeverse3d").rglob("*.py"):
- if p.name != "plan_features.py":
- out.append((str(p.relative_to(HARNESS)), p.read_text(errors="replace")))
- return tuple(out)
-
-
-def _readers(name: str) -> list[str]:
- return [rel for rel, text in _sources() if name in text]
-
-
[email protected]("name", sorted(F.LIVE_SWITCHES))
-def test_every_live_switch_is_really_read(name: str):
- """A name in LIVE_SWITCHES that nothing reads is the CQ-5 bug all over again."""
- readers = _readers(name)
- assert readers, f"{name} is listed as live but no module reads it"
- assert F.LIVE_SWITCHES[name] in readers, f"{name} is read by {readers}, not {F.LIVE_SWITCHES[name]}"
-
-
[email protected]("name", sorted(F.DEAD_SWITCHES))
-def test_every_dead_switch_is_really_dead(name: str):
- """The mirror guard: once something reads the variable, it must leave DEAD_SWITCHES —
- otherwise ab_plan would refuse a legitimate A/B."""
- assert not _readers(name), f"{name} is now read by {_readers(name)}; move it to LIVE_SWITCHES"
+Which names are live is derived from ``Settings`` — every switch the harness reads is a
+field there — so no list can drift from the code and no test has to grep the tree.
+"""
+from __future__ import annotations
-def test_the_plan_features_switch_is_declared_dead():
- """It is: none of its six features was ever implemented, so an arm that differs
- only by C3D_PLAN_FEATURES is byte-identical to its control."""
- assert F.PLAN_FEATURES_ENV in F.DEAD_SWITCHES
- assert F.dead_env_keys({F.PLAN_FEATURES_ENV: "all"}) == [F.PLAN_FEATURES_ENV]
- assert F.dead_env_keys({"C3D_PLAN_BRIEF": "off"}) == []
- assert F.dead_env_keys({F.PLAN_FEATURES_ENV: "all", "C3D_PLAN_BRIEF": "off"}) == [F.PLAN_FEATURES_ENV]
+from codeverse3d.config import Settings
+from codeverse3d.tracks.plan_features import (
+ GENERATION_SIDE_ENV,
+ NODE_SIDE_ENV,
+ dead_env_keys,
+ pin_plan_blockers,
+)
+
+
+def test_every_settings_field_is_a_live_switch_and_anything_else_is_dead():
+ """An arm that differs only by a name nothing reads is byte-identical to its control
+ (one A/B printed "keep, mean delta +0.344" for two such arms), so ab_plan refuses it.
+ Every field, nested field, flat spelling and node-side name is live; the retired ones
+ are dead the moment their field goes."""
+ live = [f"C3D_{name.upper()}" for name in Settings.model_fields]
+ live += [f"C3D_{section.upper()}__{name.upper()}" for section in ("rate", "render", "limits", "judge")
+ for name in Settings.model_fields[section].annotation.model_fields]
+ live += [*Settings.FLAT, *NODE_SIDE_ENV, *GENERATION_SIDE_ENV]
+ assert dead_env_keys(dict.fromkeys(live, "1")) == []
+ retired = ["C3D_PLAN_FEATURES", "C3D_FEWER_TURNS", "C3D_DETAIL_ROUNDS", "C3D_RATE__STORM_GATE",
+ "C3D_RATE__TPM_PER_KEY", "C3D_MYSTERY_KNOB"]
+ assert dead_env_keys({**dict.fromkeys(retired, "1"), "C3D_PLAN_BRIEF": "off"}) == sorted(retired)
+ assert dead_env_keys({"GEMINI_CLI_HOME": "/x"}) == [], "outside the C3D_ family nothing is judged dead"
# --------------------------------------------------------------------- pin-plan safety
@@ -61,9 +36,7 @@ def test_a_generation_side_switch_may_share_one_plan():
"""A switch that acts after planning cannot change the plan, so both arms can be
seeded with the same plan.json and the paired delta stops carrying the planner's
spread — the dominant variance term (eval/docs/EVAL.md §8.1)."""
- from codeverse3d.tracks.plan_features import pin_plan_blockers
-
- for name in sorted(F.GENERATION_SIDE_ENV):
+ for name in sorted(GENERATION_SIDE_ENV):
assert pin_plan_blockers({name: "1"}) == [], name
assert pin_plan_blockers({}) == []
@@ -71,8 +44,6 @@ def test_a_generation_side_switch_may_share_one_plan():
def test_a_dead_switch_blocks_nothing_but_a_live_neighbour_still_does():
"""No code reads C3D_PLAN_FEATURES, so it cannot change a plan: it never blocks
--pin-plan (until 2026-09-22 its six never-implemented feature names did)."""
- from codeverse3d.tracks.plan_features import pin_plan_blockers
-
assert pin_plan_blockers({"C3D_PLAN_FEATURES": "fit"}) == []
assert pin_plan_blockers({"C3D_PLAN_FEATURES": "all", "C3D_PLAN_BRIEF": "off"}) == [
"C3D_PLAN_BRIEF is not known to act after planning"]
@@ -80,11 +51,9 @@ def test_a_dead_switch_blocks_nothing_but_a_live_neighbour_still_does():
def test_an_unclassified_switch_defaults_to_refusing():
"""Refusing to pin costs one noisy A/B; pinning wrongly costs a confident wrong
- answer. So the default for anything unknown is: do not pin."""
- from codeverse3d.tracks.plan_features import pin_plan_blockers
-
- assert pin_plan_blockers({"C3D_MYSTERY_KNOB": "1"}) == [
- "C3D_MYSTERY_KNOB is not known to act after planning"]
+ answer. So anything live that is not known to act after planning refuses — a
+ plan-side field, or a variable some CLI may read."""
assert pin_plan_blockers({"C3D_PLAN_BRIEF": "off"}) == [
"C3D_PLAN_BRIEF is not known to act after planning"]
-
+ assert pin_plan_blockers({"GEMINI_CLI_HOME": "/x"}) == [
+ "GEMINI_CLI_HOME is not known to act after planning"]
diff --git a/harness/tests/orchestrator_tracks/test_planner_depth.py b/harness/tests/orchestrator_tracks/test_planner_depth.py
index 4ffefd1d..8928fa67 100644
--- a/harness/tests/orchestrator_tracks/test_planner_depth.py
+++ b/harness/tests/orchestrator_tracks/test_planner_depth.py
@@ -274,13 +274,13 @@ def test_brief_failure_is_never_fatal(tmp_path):
assert brief is None and usage.cost_usd == 0.0
-def test_brief_switch_and_track_scope(monkeypatch):
- monkeypatch.delenv(BR.BRIEF_ENV, raising=False)
+def test_brief_switch_and_track_scope(monkeypatch, switch):
+ switch("C3D_PLAN_BRIEF", None)
assert BR.brief_enabled(_spec())
assert not BR.brief_enabled(_spec(track=Track.GRAPHICS, language=Language.GLSL_SHADER))
- monkeypatch.setenv(BR.BRIEF_ENV, "off")
+ switch("C3D_PLAN_BRIEF", "off")
assert not BR.brief_enabled(_spec())
- monkeypatch.setenv(BR.BRIEF_ENV, "on")
+ switch("C3D_PLAN_BRIEF", "on")
assert BR.brief_enabled(_spec())
@@ -340,8 +340,8 @@ def test_plan_output_room_grows_with_the_plan_and_is_capped():
assert plan_tokens(small, 24000) >= 24000 # never below the caller's floor
-def test_truncated_plans_keep_growing_output_room(tmp_path, monkeypatch):
- monkeypatch.setenv(BR.BRIEF_ENV, "off")
+def test_truncated_plans_keep_growing_output_room(tmp_path, switch):
+ switch("C3D_PLAN_BRIEF", "off")
from codeverse3d.models.base import ModelError
good = json.loads(_plan([_part(f"P{i}", desc=_detailed(i), material=f"m{i}") for i in range(9)]).model_dump_json())
@@ -364,8 +364,8 @@ def test_truncated_plans_keep_growing_output_room(tmp_path, monkeypatch):
assert len(got.parts) == 9
-def test_a_model_error_that_is_not_truncation_still_propagates(tmp_path, monkeypatch):
- monkeypatch.setenv(BR.BRIEF_ENV, "off")
+def test_a_model_error_that_is_not_truncation_still_propagates(tmp_path, switch):
+ switch("C3D_PLAN_BRIEF", "off")
from codeverse3d.models.base import ModelError
ws = Workspace(tmp_path / "run")
@@ -379,9 +379,9 @@ def test_a_model_error_that_is_not_truncation_still_propagates(tmp_path, monkeyp
# ----------------------------------------------------------------------------- the loop
-def test_planner_spends_one_quality_reask_then_ships_the_plan(tmp_path, monkeypatch):
+def test_planner_spends_one_quality_reask_then_ships_the_plan(tmp_path, switch):
"""A plan that never satisfies the gate is still USED — a mediocre plan beats no plan."""
- monkeypatch.setenv(BR.BRIEF_ENV, "off")
+ switch("C3D_PLAN_BRIEF", "off")
ws = Workspace(tmp_path / "run")
ws.create()
thin = json.loads(_plan([_part(f"P{i}") for i in range(3)]).model_dump_json())
@@ -400,8 +400,8 @@ def test_planner_spends_one_quality_reask_then_ships_the_plan(tmp_path, monkeypa
assert len(got.parts) == 3 and ws.plan_path.is_file()
-def test_a_good_plan_costs_exactly_one_call(tmp_path, monkeypatch):
- monkeypatch.setenv(BR.BRIEF_ENV, "off")
+def test_a_good_plan_costs_exactly_one_call(tmp_path, switch):
+ switch("C3D_PLAN_BRIEF", "off")
ws = Workspace(tmp_path / "run")
ws.create()
good = json.loads(_plan([_part(f"P{i}", desc=_detailed(i), material=f"m{i}") for i in range(9)]).model_dump_json())
@@ -415,9 +415,9 @@ def test_a_good_plan_costs_exactly_one_call(tmp_path, monkeypatch):
assert calls["n"] == 1 and len(got.parts) == 9
-def test_brief_and_plan_are_one_model_and_the_events_say_so(tmp_path, monkeypatch):
- monkeypatch.setenv(BR.BRIEF_ENV, "on")
- monkeypatch.setenv("C3D_CACHE_DIR", str(tmp_path / "cache"))
+def test_brief_and_plan_are_one_model_and_the_events_say_so(tmp_path, switch):
+ switch("C3D_PLAN_BRIEF", "on")
+ switch("C3D_CACHE_DIR", str(tmp_path / "cache"))
ws = Workspace(tmp_path / "run")
ws.create()
good = json.loads(_plan([_part(f"P{i}", desc=_detailed(i), material=f"m{i}") for i in range(10)]).model_dump_json())
diff --git a/harness/tests/orchestrator_tracks/test_planner_restart.py b/harness/tests/orchestrator_tracks/test_planner_restart.py
index 3ae51780..f0c0ed6a 100644
--- a/harness/tests/orchestrator_tracks/test_planner_restart.py
+++ b/harness/tests/orchestrator_tracks/test_planner_restart.py
@@ -11,12 +11,12 @@ import json
import pytest
+from codeverse3d.config import get_settings
from codeverse3d.contracts.common import Language, Track
from codeverse3d.contracts.plan import ArticulatedPlan
from codeverse3d.proc import EventLog
from codeverse3d.tracks.planner import (
MAX_PLAN_RESTARTS,
- PLAN_RESTART_ENV,
PlanningError,
missing_link_names,
plan,
@@ -84,7 +84,7 @@ def test_an_ordinary_validation_error_still_edits_in_context(tmp_ws):
def test_the_kill_switch_restores_the_in_context_reask(tmp_ws, monkeypatch):
- monkeypatch.setenv(PLAN_RESTART_ENV, "0")
+ monkeypatch.setattr(get_settings(), "plan_restart", False) # C3D_PLAN_RESTART=off
p, model = _run(tmp_ws, [_degenerate(), _good()])
assert isinstance(p, ArticulatedPlan) and len(model.requests[1].messages) == 3
diff --git a/harness/tests/orchestrator_tracks/test_round_economics.py b/harness/tests/orchestrator_tracks/test_round_economics.py
index 71fa0b43..3935d86d 100644
--- a/harness/tests/orchestrator_tracks/test_round_economics.py
+++ b/harness/tests/orchestrator_tracks/test_round_economics.py
@@ -58,8 +58,8 @@ class _TurnAgent:
usage=Usage(backend="api-agent", cost_usd=self.cost, input_tokens=1000))
-def test_agent_sessions_are_uncapped_by_default(tmp_ws, monkeypatch):
- monkeypatch.delenv("C3D_AGENT_MAX_TURNS", raising=False)
+def test_agent_sessions_are_uncapped_by_default(tmp_ws, switch):
+ switch("C3D_AGENT_MAX_TURNS", None)
assert DEFAULT_AGENT_MAX_TURNS == 0
agent = _TurnAgent(writes_on=1)
task = GenerationTask(label="baseline", prompt="p", round=0, kind="baseline")
@@ -67,11 +67,11 @@ def test_agent_sessions_are_uncapped_by_default(tmp_ws, monkeypatch):
assert agent.jobs[0].max_turns == AgentJob(workspace="w", prompt="p").max_turns # the backend's own default
assert agent_max_turns() == 0 # "no cap asked for"
# ... and the machine's way of asking for one still works
- monkeypatch.setenv("C3D_AGENT_MAX_TURNS", "9")
+ switch("C3D_AGENT_MAX_TURNS", "9")
assert agent_max_turns() == 9
run_agent_task(tmp_ws, agent=agent, task=task)
assert agent.jobs[-1].max_turns == 9
- monkeypatch.setenv("C3D_AGENT_MAX_TURNS", "nonsense")
+ switch("C3D_AGENT_MAX_TURNS", "nonsense") # warns, keeps the default: never a crash
assert agent_max_turns() == DEFAULT_AGENT_MAX_TURNS == 0
diff --git a/harness/tests/reference/test_judge_diff.py b/harness/tests/reference/test_judge_diff.py
index 0c18cb9c..9a5ab3f5 100644
--- a/harness/tests/reference/test_judge_diff.py
+++ b/harness/tests/reference/test_judge_diff.py
@@ -76,13 +76,14 @@ def test_diff_can_be_switched_off(ref_input, cache_dir):
assert all(not r.label.startswith("reference_diff") for r in model.requests)
[email protected]("value", ["off", "of"])
-def test_diff_off_via_env(ref_input, cache_dir, monkeypatch, value):
- """A typo is a control run, not the variant (config.env_flag): "of" used to read as ON."""
- monkeypatch.setenv("C3D_REFERENCE_DIFF", value)
- model = FakeChatModel(by_label={"judge": [good_reply(REF, ["A1", "A2"], 0.8)]})
[email protected](("value", "diffed"), [("off", False), ("OFF", False), ("of", True)])
+def test_diff_off_via_env(ref_input, cache_dir, switch, value, diffed):
+ """``C3D_REFERENCE_DIFF=off`` switches the pass off; a typo warns and keeps the default
+ (ON) — the arm that never set the switch, which is what D44 (c) asks of a typo."""
+ switch("C3D_REFERENCE_DIFF", value)
+ model = FakeChatModel(by_label={"reference_diff": [DIFF], "judge": [good_reply(REF, ["A1", "A2"], 0.8)]})
_judge(model, cache_dir=cache_dir).judge(ref_input)
- assert all(not r.label.startswith("reference_diff") for r in model.requests)
+ assert any(r.label.startswith("reference_diff") for r in model.requests) is diffed
def test_best_view_iou_beats_a_fixed_front_view(ref_input, cache_dir, tmp_path):
diff --git a/harness/tests/scene_gates/test_scene_textures_stage.py b/harness/tests/scene_gates/test_scene_textures_stage.py
index 3318f48a..6e71fc80 100644
--- a/harness/tests/scene_gates/test_scene_textures_stage.py
+++ b/harness/tests/scene_gates/test_scene_textures_stage.py
@@ -19,30 +19,19 @@ from __future__ import annotations
import pytest
-from codeverse3d.config import SCENE_TEXTURES_ENV, get_settings, scene_textures_enabled
-from codeverse3d.tracks.plan_features import LIVE_SWITCHES
+from codeverse3d.config import get_settings
@pytest.fixture(autouse=True)
def _clean_settings(monkeypatch):
- monkeypatch.delenv(SCENE_TEXTURES_ENV, raising=False)
+ monkeypatch.delenv("C3D_SCENE_TEXTURES", raising=False)
get_settings.cache_clear()
yield
get_settings.cache_clear()
-def test_the_switch_is_off_by_default_and_readable_at_call_time(monkeypatch):
- assert scene_textures_enabled() is False
- monkeypatch.setenv(SCENE_TEXTURES_ENV, "1")
- assert scene_textures_enabled() is True
- monkeypatch.setenv(SCENE_TEXTURES_ENV, "false")
- assert scene_textures_enabled() is False
-
-
-def test_the_switch_is_registered_as_live():
- """An A/B arm that differs only by a switch no code reads is byte-identical to its
- control; `plan_features` refuses such an arm, and only if the name is declared."""
- assert LIVE_SWITCHES[SCENE_TEXTURES_ENV] == "codeverse3d/config.py"
+def test_the_switch_is_off_by_default():
+ assert get_settings().scene_textures is False
def _render(name: str, **extra):
diff --git a/harness/tests/scene_runtime/test_post.py b/harness/tests/scene_runtime/test_post.py
index 071440c6..ef212e5b 100644
--- a/harness/tests/scene_runtime/test_post.py
+++ b/harness/tests/scene_runtime/test_post.py
@@ -77,12 +77,12 @@ def render(ws: Workspace, out: Path, *extra_args: str) -> Path:
return out / "cam_t0.png"
-def test_post_chain_args_follow_the_env_switch(monkeypatch):
- monkeypatch.delenv("C3D_POST", raising=False)
+def test_post_chain_args_follow_the_env_switch(switch):
+ switch("C3D_POST", None)
assert post_chain_args() == [] # ON by default for scene pictures
- monkeypatch.setenv("C3D_POST", "0")
+ switch("C3D_POST", "0")
assert post_chain_args() == ["--no-post"]
- monkeypatch.setenv("C3D_POST", "on")
+ switch("C3D_POST", "on")
assert post_chain_args() == []
diff --git a/harness/tests/scene_runtime/test_render_scene.py b/harness/tests/scene_runtime/test_render_scene.py
index 8a37bdd4..2c30da14 100644
--- a/harness/tests/scene_runtime/test_render_scene.py
+++ b/harness/tests/scene_runtime/test_render_scene.py
@@ -282,7 +282,7 @@ def _flags(args):
def test_probe_env_args_speaks_the_canonical_flag_words(monkeypatch, env, expect):
"""C3D_CAMERA_REPAIR=false must DISABLE, C3D_SETTLE=false must disable,
C3D_AUTO_EXPOSURE=true must enable — the raw '0'/'1' compares silently
- ignored every other word the doc'd env_flag vocabulary accepts."""
+ ignored every other word of the documented on/off vocabulary (config.Flag)."""
for k in ("C3D_SETTLE", "C3D_CAMERA_REPAIR", "C3D_AUTO_EXPOSURE"):
monkeypatch.delenv(k, raising=False)
for k, v in env.items():
@@ -290,7 +290,7 @@ def test_probe_env_args_speaks_the_canonical_flag_words(monkeypatch, env, expect
assert _flags(probe_env_args()) == expect
-def test_every_driver_invocation_carries_the_env_flags(monkeypatch, ws, tmp_path):
+def test_every_driver_invocation_carries_the_env_flags(monkeypatch, switch, ws, tmp_path):
"""Review-3 S4 (V7c): the combined single-boot build probes under the SAME
settle / camera-repair / auto-exposure flags as the standalone probe and
render paths — it used to pass none of them."""
@@ -319,8 +319,8 @@ def test_every_driver_invocation_carries_the_env_flags(monkeypatch, ws, tmp_path
assert _flags(captured["render_scene.mjs"]) == ["--camera-repair"]
# the A/B words reach every path, including the combined build
- monkeypatch.setenv("C3D_SETTLE", "0")
- monkeypatch.setenv("C3D_CAMERA_REPAIR", "false")
+ switch("C3D_SETTLE", "0")
+ switch("C3D_CAMERA_REPAIR", "false")
st.probe_and_preflight(ws, timeout_s=5.0)
assert _flags(captured["probe_scene.mjs"]) == ["--no-settle"]
probes_mod.probe_scene(ws)
diff --git a/harness/tests/skills/test_config.py b/harness/tests/skills/test_config.py
index 015132f5..1ae8c29e 100644
--- a/harness/tests/skills/test_config.py
+++ b/harness/tests/skills/test_config.py
@@ -1,4 +1,4 @@
-"""The switches: read at call time, tolerant of garbage, and registered as LIVE.
+"""The skill switches are ``Settings`` fields: ON by default, tolerant of garbage, live.
``tracks/plan_features.py`` exists because a wave A/B'd a switch nothing read and printed
"keep, mean delta +0.344" for two byte-identical arms. These tests are what keep
@@ -9,61 +9,46 @@ from __future__ import annotations
import pytest
-from codeverse3d.skills import config as C
-from codeverse3d.tracks import plan_features as F
+from codeverse3d.config import Settings, get_settings
+from codeverse3d.tracks.plan_features import dead_env_keys
+
+
+def _settings(monkeypatch, **env: str) -> Settings:
+ for name in ("C3D_SKILLS", "C3D_SKILLS_MAX", "C3D_SKILLS_UNVERIFIED"):
+ monkeypatch.delenv(name, raising=False)
+ for name, raw in env.items():
+ monkeypatch.setenv(name, raw)
+ return Settings()
def test_on_by_default(monkeypatch):
"""Flipped 2026-09-22 (owner): every backend is a vendor CLI with a native skill loader,
and the whole library routes — the cap of 5 per session is the cost knob, not the switch."""
- for env in (C.SKILLS_ENV, C.SKILLS_MAX_ENV, C.SKILLS_UNVERIFIED_ENV):
- monkeypatch.delenv(env, raising=False)
- assert C.skills_enabled() is True
- assert C.skills_unverified() is True
- assert C.skills_max() == C.DEFAULT_SKILLS_MAX == 5
+ s = _settings(monkeypatch)
+ assert (s.skills, s.skills_unverified, s.skills_max) == (True, True, 5)
@pytest.mark.parametrize("raw, want", [("on", True), ("1", True), ("true", True), ("YES", True),
- ("off", False), ("0", False), ("", True), ("maybe", False)])
+ ("off", False), ("0", False), ("no", False), ("", True),
+ ("maybe", True)])
def test_flag_spellings(monkeypatch, raw, want):
- """Unset or empty is the default (ON); garbage is OFF, never the variant — a typo in a
- bench command must produce a control run (``config.env_flag``)."""
- monkeypatch.setenv(C.SKILLS_ENV, raw)
- assert C.skills_enabled() is want
-
-
[email protected]("raw", ["0", "off", "false", "no"])
-def test_c3d_skills_0_turns_both_off(monkeypatch, raw):
- """The ONE off switch an A/B control arm sets: nothing is enabled, whatever UNVERIFIED says."""
- monkeypatch.setenv(C.SKILLS_ENV, raw)
- monkeypatch.delenv(C.SKILLS_UNVERIFIED_ENV, raising=False)
- assert C.skills_enabled() is False
+ """Unset or empty is the default (ON); garbage warns and keeps the default — a typo in
+ a bench command runs the arm that never set it, never a crash (D44 c)."""
+ assert _settings(monkeypatch, C3D_SKILLS=raw).skills is want
def test_unverified_can_still_be_turned_off(monkeypatch):
- monkeypatch.setenv(C.SKILLS_UNVERIFIED_ENV, "0")
- assert C.skills_unverified() is False
-
-
-def test_read_at_call_time_not_cached(monkeypatch):
- monkeypatch.setenv(C.SKILLS_ENV, "on")
- assert C.skills_enabled()
- monkeypatch.setenv(C.SKILLS_ENV, "off")
- assert not C.skills_enabled()
+ assert _settings(monkeypatch, C3D_SKILLS_UNVERIFIED="0").skills_unverified is False
[email protected]("raw, want", [("3", 3), ("0", 0), ("-1", 0), ("nope", 5), ("", 5)])
[email protected]("raw, want", [("3", 3), ("0", 0), ("-1", 5), ("nope", 5), ("", 5)])
def test_max_is_never_a_crash(monkeypatch, raw, want):
- monkeypatch.setenv(C.SKILLS_MAX_ENV, raw)
- assert C.skills_max() == want
+ assert _settings(monkeypatch, C3D_SKILLS_MAX=raw).skills_max == want
-def test_the_switches_are_registered_as_live_not_dead():
- for env in (C.SKILLS_ENV, C.SKILLS_MAX_ENV, C.SKILLS_UNVERIFIED_ENV):
- assert env in F.LIVE_SWITCHES, f"{env} must be declared so ab_plan accepts an arm using it"
- assert env not in F.DEAD_SWITCHES
- assert F.LIVE_SWITCHES[env] == "codeverse3d/skills/config.py"
- assert F.dead_env_keys({C.SKILLS_ENV: "on"}) == []
+def test_the_switches_are_live():
+ assert dead_env_keys(dict.fromkeys(("C3D_SKILLS", "C3D_SKILLS_MAX", "C3D_SKILLS_UNVERIFIED",
+ "C3D_SKILLS_ONLY", "C3D_SKILLS_DIR"), "1")) == []
def test_doctor_reports_the_default_and_the_gemini_pin(monkeypatch):
@@ -71,9 +56,10 @@ def test_doctor_reports_the_default_and_the_gemini_pin(monkeypatch):
must be pinned in the per-session system settings (a user file could turn it off)."""
from codeverse3d.doctor import check_skills
- monkeypatch.delenv(C.SKILLS_ENV, raising=False)
+ monkeypatch.delenv("C3D_SKILLS", raising=False)
rows = {name: status for name, status, _ in check_skills()}
assert rows["skills switch"] == "OK" and rows["gemini-cli skills setting"] == "OK"
assert rows["claude-code Skill tool"] == "OK"
- monkeypatch.setenv(C.SKILLS_ENV, "0")
+ monkeypatch.setenv("C3D_SKILLS", "0")
+ get_settings.cache_clear()
assert {name: status for name, status, _ in check_skills()}["skills switch"] == "WARN"
diff --git a/harness/tests/skills/test_hook.py b/harness/tests/skills/test_hook.py
index 338b82b5..a5dc233a 100644
--- a/harness/tests/skills/test_hook.py
+++ b/harness/tests/skills/test_hook.py
@@ -13,7 +13,6 @@ from types import SimpleNamespace as NS
import pytest
from codeverse3d.contracts.artifacts import GateFinding, GateReport, Severity
-from codeverse3d.skills import config as C
from codeverse3d.tracks import skills_hook as H
@@ -38,7 +37,7 @@ def ctx(tmp_path: Path, library_dir: Path, monkeypatch):
def test_the_switch_off_means_no_files_no_events_no_record(ctx, monkeypatch):
- monkeypatch.setenv(C.SKILLS_ENV, "0") # ON is the default since 2026-09-22; off must be said
+ monkeypatch.setenv("C3D_SKILLS", "0") # ON is the default since 2026-09-22; off must be said
assert H.attach_for_round(ctx, index=0, kind="baseline") is None
assert not (ctx.ws.root / ".agents").exists()
assert ctx.events == [] and ctx.extra == {}
@@ -47,7 +46,7 @@ def test_the_switch_off_means_no_files_no_events_no_record(ctx, monkeypatch):
def test_the_switch_on_attaches_records_and_measures(ctx, monkeypatch):
- monkeypatch.setenv(C.SKILLS_ENV, "on")
+ monkeypatch.setenv("C3D_SKILLS", "on")
got = H.attach_for_round(ctx, index=0, kind="baseline")
assert got and got.listed
assert (ctx.ws.root / ".agents" / "skills" / got.listed[0] / "SKILL.md").is_file()
@@ -60,7 +59,7 @@ def test_the_switch_on_attaches_records_and_measures(ctx, monkeypatch):
def test_the_previous_rounds_findings_route_the_repair_sheet(ctx, monkeypatch):
- monkeypatch.setenv(C.SKILLS_ENV, "on")
+ monkeypatch.setenv("C3D_SKILLS", "on")
rounds = ctx.ws.root / "rounds"
rounds.mkdir()
rec = {"index": 0, "kind": "baseline", "gates": [GateReport(
@@ -78,13 +77,13 @@ def test_the_previous_rounds_findings_route_the_repair_sheet(ctx, monkeypatch):
def test_round_zero_never_looks_for_a_previous_round(ctx, monkeypatch):
- monkeypatch.setenv(C.SKILLS_ENV, "on")
+ monkeypatch.setenv("C3D_SKILLS", "on")
got = H.attach_for_round(ctx, index=0, kind="baseline")
assert all(not s.gate_fired for s in got.selections)
def test_repair_pointers_name_the_skill_that_answers_the_current_lint(ctx, monkeypatch):
- monkeypatch.setenv(C.SKILLS_ENV, "on")
+ monkeypatch.setenv("C3D_SKILLS", "on")
H.attach_for_round(ctx, index=0, kind="repair")
lint = GateReport(gate="lint:blender", passed=False, findings=[GateFinding(
gate="lint:blender", severity=Severity.WARN,
@@ -94,7 +93,7 @@ def test_repair_pointers_name_the_skill_that_answers_the_current_lint(ctx, monke
def test_single_shot_inlines_one_body_into_every_task(ctx, monkeypatch):
- monkeypatch.setenv(C.SKILLS_ENV, "on")
+ monkeypatch.setenv("C3D_SKILLS", "on")
ctx.single_shot = True
got = H.attach_for_round(ctx, index=0, kind="baseline")
assert got.inlined and got.paths == []
@@ -111,14 +110,14 @@ def test_single_shot_inlines_one_body_into_every_task(ctx, monkeypatch):
def test_an_agent_session_never_gets_an_inlined_body(ctx, monkeypatch):
- monkeypatch.setenv(C.SKILLS_ENV, "on")
+ monkeypatch.setenv("C3D_SKILLS", "on")
H.attach_for_round(ctx, index=0, kind="baseline")
tasks = [NS(prompt="p")]
assert H.with_inlined_skill(ctx, tasks) == tasks
def test_a_broken_library_costs_the_skills_not_the_round(ctx, monkeypatch, caplog):
- monkeypatch.setenv(C.SKILLS_ENV, "on")
+ monkeypatch.setenv("C3D_SKILLS", "on")
monkeypatch.setenv("C3D_SKILLS_DIR", "/definitely/not/a/directory")
with caplog.at_level("WARNING"):
got = H.attach_for_round(ctx, index=0, kind="baseline")
@@ -127,7 +126,7 @@ def test_a_broken_library_costs_the_skills_not_the_round(ctx, monkeypatch, caplo
def test_a_failed_attach_clears_the_previous_rounds_set(ctx, monkeypatch):
"""Otherwise round N+1 probes round N's bundles and reports reads it never earned."""
- monkeypatch.setenv(C.SKILLS_ENV, "on")
+ monkeypatch.setenv("C3D_SKILLS", "on")
assert H.attach_for_round(ctx, index=0, kind="baseline")
monkeypatch.setattr("codeverse3d.skills.attach_skills",
lambda *a, **k: (_ for _ in ()).throw(RuntimeError("boom")))
@@ -136,7 +135,7 @@ def test_a_failed_attach_clears_the_previous_rounds_set(ctx, monkeypatch):
def test_a_probe_failure_is_logged_not_raised(ctx, monkeypatch):
- monkeypatch.setenv(C.SKILLS_ENV, "on")
+ monkeypatch.setenv("C3D_SKILLS", "on")
H.attach_for_round(ctx, index=0, kind="baseline")
monkeypatch.setattr("codeverse3d.skills.telemetry.probe_reads", lambda *a, **k: (_ for _ in ()).throw(OSError("boom")))
assert H.record_usage(ctx, index=0, kind="baseline") is None
diff --git a/harness/tests/skills/test_loader.py b/harness/tests/skills/test_loader.py
index 93a84e31..a41c0930 100644
--- a/harness/tests/skills/test_loader.py
+++ b/harness/tests/skills/test_loader.py
@@ -132,8 +132,10 @@ def test_load_skill_by_name(tmp_path: Path):
def test_the_library_dir_is_overridable_for_tests_and_the_live_smoke(tmp_path: Path, monkeypatch):
- from codeverse3d.skills import SKILLS_DIR_ENV, skills_dir
+ from codeverse3d.config import get_settings
+ from codeverse3d.skills import skills_dir
write_bundle(tmp_path, "c3d-demo")
- monkeypatch.setenv(SKILLS_DIR_ENV, str(tmp_path))
+ monkeypatch.setenv("C3D_SKILLS_DIR", str(tmp_path))
+ get_settings.cache_clear()
assert skills_dir() == tmp_path
diff --git a/harness/tests/skills/test_only_switch.py b/harness/tests/skills/test_only_switch.py
index 9cbe21f7..fb820f46 100644
--- a/harness/tests/skills/test_only_switch.py
+++ b/harness/tests/skills/test_only_switch.py
@@ -10,7 +10,7 @@ from __future__ import annotations
import pytest
-from codeverse3d.skills.config import SKILLS_ONLY_ENV, skills_only
+from codeverse3d.config import get_settings
from codeverse3d.skills.materialize import attach_skills
@@ -66,20 +66,12 @@ def test_an_unknown_name_attaches_nothing_rather_than_everything(ws, caplog):
"""A typo must make the variant visibly identical to its control, not silently
measure the full five-bundle set."""
assert _listed(ws, only=frozenset({"c3d-typo"})) == []
- assert SKILLS_ONLY_ENV in caplog.text
+ assert "C3D_SKILLS_ONLY" in caplog.text
-def test_the_switch_is_read_at_call_time(ws, monkeypatch):
- """Frozen at import (the get_settings/lru_cache trap) the variant child would run the
- control's library — the failure mode that printed 'keep, +0.344' for identical arms."""
- monkeypatch.delenv(SKILLS_ONLY_ENV, raising=False)
- assert skills_only() == frozenset()
- monkeypatch.setenv(SKILLS_ONLY_ENV, " c3d-bbox-contract , ")
- assert skills_only() == frozenset({"c3d-bbox-contract"})
- assert _listed(ws) == ["c3d-bbox-contract"], "attach_skills must consult the env when only= is omitted"
-
-
-def test_the_switch_is_registered_live():
- from codeverse3d.tracks.plan_features import LIVE_SWITCHES
-
- assert SKILLS_ONLY_ENV in LIVE_SWITCHES, "an unregistered switch is one ab_plan calls dead"
+def test_the_switch_reaches_the_router(ws, monkeypatch):
+ """``only=`` omitted, attach_skills reads ``C3D_SKILLS_ONLY`` (a comma list, blanks
+ ignored) — the variant child of an effect A/B sets nothing else."""
+ monkeypatch.setenv("C3D_SKILLS_ONLY", " c3d-bbox-contract , ")
+ get_settings.cache_clear()
+ assert _listed(ws) == ["c3d-bbox-contract"], "attach_skills must consult the switch when only= is omitted"
diff --git a/harness/tests/urdf_joints/test_axis_repair.py b/harness/tests/urdf_joints/test_axis_repair.py
index f3c59704..6afcb16a 100644
--- a/harness/tests/urdf_joints/test_axis_repair.py
+++ b/harness/tests/urdf_joints/test_axis_repair.py
@@ -3,6 +3,8 @@ from __future__ import annotations
import xml.etree.ElementTree as ET
+import pytest
+
from codeverse3d.contracts.artifacts import GateFinding, GateReport, Severity
from codeverse3d.tracks.articulated_object import MOTION_GATE, repair_motion_axes
from codeverse3d.workspace import Workspace
@@ -81,8 +83,10 @@ def test_warn_and_unknown_joints_are_skipped(tmp_path):
assert _axis_of(ws, "Hinge") == (0.0, 0.0, -1.0)
-def test_kill_switch_disables(tmp_path, monkeypatch):
- monkeypatch.setenv("C3D_AXIS_REPAIR", "0")
[email protected]("raw", ["0", "off", "false"])
+def test_kill_switch_disables(tmp_path, switch, raw):
+ """``C3D_AXIS_REPAIR=off`` was silently ignored until 2026-09-22: only "0" was read."""
+ switch("C3D_AXIS_REPAIR", raw)
ws = _ws(tmp_path)
assert repair_motion_axes(ws, _report(_finding("Hinge", cos=-1.0))) == []
assert _axis_of(ws, "Hinge") == (0.0, 0.0, -1.0)