Repository navigation
refactor(config): give each config domain a named owner module - #14558
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Confirm the BASE-vs-HEAD equivalence snapshot was re-run on this exact revision — it lives in the description, not CI. [DESIGN-REVIEWED] 8e17f6c |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS The BASE-vs-HEAD equivalence snapshot the description leans on is not shipped in the diff — confirm it ran, since behaviour identity otherwise rests on the new contract test alone. What this change shipsInventory (10 items) — 10 justifiedIntent: make every
[FIRST-PRINCIPLES-REVIEWED] 8e17f6c |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
|
The route sweep's No repair here: fixing an expectation in |
|
Equivalence evidence for head It ran from the committed trees, extracted with The "rich" document exercises clamps, fail-closed coercions, retired STT providers, the monitoring ceiling fallback, The same guarantees that must hold after any later edit are pinned as tests in this diff, not left to the snapshot. They cover name sets and identity, logger names, the patch seams, migration ids, order and backup bytes, and Snapshot script (reproducible: run from a tree extracted with `git archive <sha> src scripts/generate_config_baseline.py config-baseline.json`)"""Behavior-equivalence snapshot of kiro_crew.config for BASE-vs-HEAD comparison.
Run from a worktree root: python equiv_snapshot.py <out.json>
Uses an isolated KIROCREW_HOME/HOME under a temp dir.
"""
import re, dataclasses, importlib, inspect, io, json, logging, os, subprocess, sys, tempfile, types
from pathlib import Path
out_path = sys.argv[1]
tmp = Path(tempfile.mkdtemp(prefix="b07eq-"))
os.environ["KIROCREW_HOME"] = str(tmp / "home")
os.environ["HOME"] = str(tmp / "userhome")
os.environ["KIRO_HOME"] = str(tmp / "kirohome")
(tmp / "userhome").mkdir()
sys.path.insert(0, str(Path.cwd() / "src"))
MODS = ["kiro_crew.config", "kiro_crew.config.sections", "kiro_crew.config.loader", "kiro_crew.config.live",
"kiro_crew.config.paths", "kiro_crew.config.resolution", "kiro_crew.config.schema",
"kiro_crew.config.validation", "kiro_crew.config.superseded_defaults"]
snap = {}
def describe(v):
if isinstance(v, types.ModuleType):
return ["module", v.__name__]
if isinstance(v, type):
return ["class", v.__qualname__]
if callable(v) and hasattr(v, "__qualname__"):
try:
sig = re.sub(r" at 0x[0-9a-f]+", "", str(inspect.signature(v)))
except (TypeError, ValueError):
sig = "?"
return ["callable", v.__qualname__, sig]
if isinstance(v, (set, frozenset)):
return ["value", type(v).__qualname__, repr(sorted(map(repr, v)))]
if isinstance(v, dict) and any(isinstance(x, (set, frozenset)) for x in v.values()):
return ["value", "dict", repr({k: sorted(map(repr, x)) if isinstance(x, (set, frozenset)) else repr(x) for k, x in v.items()})]
try:
r = repr(v)
except Exception:
r = "<unreprable>"
if " at 0x" in r:
r = type(v).__qualname__
return ["value", type(v).__qualname__, r[:2000]]
for m in MODS:
mod = importlib.import_module(m)
snap["surface:" + m] = {n: describe(getattr(mod, n)) for n in sorted(vars(mod)) if not (n.startswith("__") and n.endswith("__"))}
# also names reachable via package __getattr__
from kiro_crew.config import loader, sections, schema
def field_fp(cls):
rows = []
for f in dataclasses.fields(cls):
if f.default is not dataclasses.MISSING:
d = ["value", repr(f.default)]
elif f.default_factory is not dataclasses.MISSING:
d = ["factory", repr(f.default_factory())]
else:
d = ["required", ""]
rows.append([f.name, str(f.type), d, repr(sorted(f.metadata.items())), f.init, f.repr, f.compare, f.kw_only])
members = {}
for n, v in vars(cls).items():
if n.startswith("__") and n.endswith("__"):
continue
members[n] = describe(v)
return {"qualname": cls.__qualname__, "doc": cls.__doc__, "fields": rows, "members": members,
"params": repr(cls.__dataclass_params__), "mro": [c.__qualname__ for c in cls.__mro__]}
classes = {}
for m in (sections, loader):
for v in vars(m).values():
if isinstance(v, type) and dataclasses.is_dataclass(v):
classes[v.__qualname__] = v
snap["dataclasses"] = {k: field_fp(classes[k]) for k in sorted(classes)}
snap["default_repr"] = {k: repr(classes[k]()) for k in sorted(classes) if all(
f.default is not dataclasses.MISSING or f.default_factory is not dataclasses.MISSING or not f.init
for f in dataclasses.fields(classes[k]))}
snap["to_dict_default"] = json.dumps(loader.KiroCrewConfig().to_dict())
snap["json_schema"] = json.dumps(schema.build_json_schema(loader.KiroCrewConfig), default=repr)
snap["entries"] = [json.dumps(schema.config_entry_to_dict(e), default=str) for e in schema.SCHEMA_REGISTRY]; snap["restart_paths"] = sorted(schema._RESTART_PATHS)
# baseline generator bytes
bl = tmp / "baseline.json"
env = dict(os.environ, KIROCREW_BASELINE_OUTPUT=str(bl), PYTHONPATH=str(Path.cwd() / "src"))
r = subprocess.run([sys.executable, "scripts/generate_config_baseline.py"], capture_output=True, text=True, encoding="utf-8", env=env, cwd=str(Path.cwd()), timeout=120)
snap["baseline_rc"] = r.returncode
snap["baseline_bytes_sha"] = __import__("hashlib").sha256(bl.read_bytes()).hexdigest() if bl.exists() else None
snap["committed_baseline_sha"] = __import__("hashlib").sha256(Path("config-baseline.json").read_bytes()).hexdigest()
# load scenarios with captured logs
class Cap(logging.Handler):
def __init__(self):
super().__init__(logging.DEBUG); self.records = []
def emit(self, rec):
self.records.append([rec.name, rec.levelname, rec.getMessage()[:500]])
root = logging.getLogger()
root.setLevel(logging.DEBUG)
def scenario(name, doc, local=None):
home = Path(os.environ["KIROCREW_HOME"])
home.mkdir(parents=True, exist_ok=True)
for p in home.iterdir():
if p.is_file():
p.unlink()
if doc is not None:
(home / "config.json").write_text(doc if isinstance(doc, str) else json.dumps(doc), encoding="utf-8")
if local is not None:
(home / "config.local.json").write_text(json.dumps(local), encoding="utf-8")
loader._invalidate_config_cache()
h = Cap(); root.addHandler(h)
try:
cfg = loader.KiroCrewConfig.load()
res = {"to_dict": json.dumps(cfg.to_dict()), "degraded": sorted(cfg.degraded_sections)}
except Exception as e:
res = {"error": repr(e)}
finally:
root.removeHandler(h)
files = {}
for p in sorted(home.iterdir()):
try:
if p.is_file() and p.suffix in (".json", ".bak", ".local"):
files[p.name] = p.read_text(encoding="utf-8", errors="replace")
except OSError:
pass
# strip timestamps in meta stamps
res["files"] = sorted(files)
res["config_after"] = files.get("config.json")
res["logs"] = [r for r in h.records if r[0].startswith("kiro_crew")]
blob = json.dumps(res)
blob = blob.replace(str(tmp), "<TMP>")
blob = re.sub(r'lastTouchedAt\\": \\"[^"\\]+', 'lastTouchedAt\\": \\"<TS>', blob)
res = json.loads(blob)
snap["load:" + name] = res
scenario("absent", None)
scenario("empty", {})
scenario("garbage", "{not json")
scenario("list", "[1,2]")
scenario("rich", {
"agent": {"model": "auto", "sandbox": "strict", "max_subagents": 999, "subagent_max_turns": 0, "chat_turn_timeout_secs": 5,
"tool_approval_timeout_secs": 99999, "session_control": "false", "acp_backend": "nonexistent", "role_models": {"subagent": 7},
"yolo_duration": "bogus", "jail": "weird", "fallback_model": 12, "lane_weights": {"x": 999, "": 3}},
"session": {"timeout_secs": -5, "autocompact_pct": 200, "pool_size": 99},
"monitoring": {"max_runtime_secs": 0, "prefer_structured_arming": True},
"mcp": {"honour_auto_approve": "yes", "extra_path_dirs": ["/opt/x", 3]},
"stt": {"provider": "whisper", "model": "nope"},
"telegram": {"enabled": True, "allowed_user_ids": ["12", 3.0, "x"]},
"slack": {"allowed_users": ["U1"], "command": "/k"},
"resource_limits": {"memory_mb": 512.5},
"dashboard": {"folder_sort": "zzz", "verbosity": "concise"},
"memory": {"embedding_provider": "none"},
"knowledge": {"auto_ingest_doc_links": True},
"decisions": {"enabled": True},
"unknown_section": {"a": 1},
"agents": {"default": {"kiro_agent": "kirocrew", "workspace": "default", "session_color": "#zzz"}},
"workspaces": {"default": {"path": "~/w"}},
"timezone": "Europe/Paris",
})
scenario("overlay", {"agent": {"model": "auto"}, "session": {"timeout_secs": 100}}, local={"session": {"timeout_secs": 200}, "dashboard": {"url": "http://x"}})
snap["tmp"] = str(tmp)
json.dump(snap, open(out_path, "w"), indent=1, sort_keys=True, default=str)
print("wrote", out_path, len(snap), "keys; baseline rc", snap["baseline_rc"], "match", snap["baseline_bytes_sha"] == snap["committed_baseline_sha"]) |
|
|
8c54b8c to
26636fb
Compare
|
Infra reruns on head
Each of these runs was rerun once with |
|
|
26636fb to
9a76ebd
Compare
|
The same lane finished with "no blocking findings" on the two previous heads of this PR, |
|
The single rerun of
Nothing in the diff is being reviewed as wrong. The delta from |
Human judgment recorded@bolichen97 marked the fable AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
9a76ebd to
4ca18a5
Compare
|
Rebased onto The port. #13948 added three things. A
Proof that only upstream's change moved in. For every file this PR touches, the change from old head An AST check also found every one of the 78 relocated definitions byte-identical to its Re-gated at
The failure is |
|
Status of head
Holding with no rerun and no push. A rerun cannot pick up #14639, and the GPT and Opus lanes run again on the one fresh push after it merges. |
sections.py (8,199 lines) and loader.py (6,840) held every configuration rule, so no group of settings had an owner and a one-setting edit sat among forty unrelated sections. Both files are among the most-edited in the repository, so finding the rule for one setting cost the same scroll every time -- and these files carry the security clamps, the fail-closed defaults, the write-back migrations and the credential list, where a guess ships silently. Each config.json domain now has its own module, with the two old files kept as the facades every caller imports: config/fields.py owns the field metadata and the shared value coercers; memory_sections, integration_sections and service_sections own their sections' DTOs; section_builders owns the _build_* helper of 28 sections, grouped by the module that owns each section's DTO; migration owns the write-back migration ids, the document transform and superseded-default reporting. Imports run one way -- fields, the section owners, sections, then section_builders/migration, then loader -- and a test pins that graph. Every module split out keeps the kiro_crew.config.loader logger, so a relocated warning keeps the name operators filter on. Each file's residual core stays put because something outside the config package names that file, not because it was convenient: the writer scans exempt only loader.py, seven specs and the feature map cite it for the clamp, credentials, port, agent resolution and telemetry parse, the agent-spec read inventory and agent-SDK edge baseline key to it, the second-boot witness keys the published counters to it, and the blocking harness-parity and memory-store rules cover it; sections.py keeps the DTOs that messaging, slack-gateway, crew-mode, history, stt-streaming, metrics, decisions, security, model-selection, model-fallback, subagent, acp-client and crew-log-projection name, plus the four constructs whose source scans allow them only there. config.md carries that table. Behaviour is unchanged: both facades re-export every historical name as the same object, so every import still resolves, and the schema baseline config-baseline.json regenerates byte-identical. A patch reaches the code that looks the name up in the patched module: loader-resident seams (the path helpers, the config writers, the clamp event, DEFAULT_POOL_SIZE, record_adoptions, each _build_* name at its _load_resolved call site, the snapshot globals) stay call-time seams on the loader, while a helper read inside a relocated builder or migration rule is patched on section_builders or migration. No test or caller that predates this change patches one of the relocated names; config.md lists both sets, and a contract test pins representative seams of each kind. The one changed call shape is internal -- the migration transform takes the adoption-ledger writer as an argument and the loader passes its own record_adoptions at call time, preserving that patch seam.
4ca18a5 to
8e17f6c
Compare
|
|
|
Green age on head I checked it against this exact head without rebasing. I took an archive of This head's green is kept as-is rather than re-synced. A re-sync would restart every check and review lane and change nothing that #14651 tests. |
Problem / Motivation
Goal: Make each configuration rule easy to find and safe to change by giving every group of
config.jsonsettings a named owner module, without changing a single setting's behaviour.src/kiro_crew/config/sections.py(8,199 lines) andconfig/loader.py(6,840 lines)were the two places every config rule lived. Finding the owner of one setting meant
scrolling one of them, and a small edit sat next to forty unrelated sections. Both
files are among the most-edited in the repository, so that cost is paid constantly.
Why it matters
A setting whose rule is hard to find is a setting people change by guessing. The two
files carry security clamps, fail-closed defaults, the write-back migrations and the
credential list, so a guess there is expensive: a wrong default ships silently and is
only noticed when an operator's gateway behaves differently from their config file.
Named owners make the rule for one domain readable on its own, and the same split
lets a reviewer see that a change touches only the domain it claims to.
Not a goal
config-baseline.jsonis unchanged.config.sectionsandconfig.loaderstill expose every name they exposed, as the same objects.config/paths.py, orsession_work_dir.py.What changed (motivation → approach → change)
Two files held every config rule, so neither had an owner. Each
config.jsondomainnow has its own module, and the two old files stay as the facades callers import.
config/fields.py_metafield metadata and the_safe_*value coercers every section shares. Imports nothing fromkiro_crew.config/memory_sections.pymemory,knowledge,skills,session_summary, named memory storesconfig/integration_sections.pymcp,mcp_gateway,instances,tunnel,publish,computer_use, app registriesconfig/service_sections.pytaskrunner,orchestrator,messaging,cron_history,monitoring,heartbeat,watchdogconfig/section_builders.py_build_*helper of 28 sections, grouped by the module owning each section's DTO (sections with no helper stay built inline in_load_resolvedor by their DTO'sfrom_raw)config/migration.pyImports run one way —
fields, then the section owners, thensections, thensection_buildersandmigration, thenloader— and a new test pins that graph.Every module split out logs as
kiro_crew.config.loader, so a relocated warning keepsthe record name operators filter on and
caplogtests select.Each file's residual core stays where it is because something outside this package
names that file, not because it was convenient.
docs/system-specs/modules/config.mdcarries the same table; the short version:
sections.py: agent, crew record, session, workspace, dashboard (+tailnet), the 9 channel DTOs,wakatime, speech-to-text, telemetry, decisions, resource limitsmessaging.md(channel restart flags),slack-gateway.md,crew-mode.md,history.md,stt-streaming.md,metrics.md,decisions.md,security.md,model-selection.md,model-fallback.md,subagent.md,acp-client.md,crew-log-projection.md; plus source scans that allowResourceLimitsConfig.from_raw,_tailscale_config_from, the avatar-motion literal and theacp_backenddeclaration only in that fileloader.py: document I/O, write-back persistence, the unsandboxed-exec policy, the validated-document cache fingerprint,KiroCrewConfig.load/save, the security clamp, the loop-stall readers, published snapshots, agent resolution, the provider factory, the credential list and port, the agent/session/telemetry/dashboard buildersloader.py;code-style.md,security.md,sel.md,resource-protection.md,crew-mode.md,context-management.md,metrics.mdand the feature map name it; the agent-spec read inventory, the agent-SDK edge baseline, the second-boot witness and the blocking harness-parity and memory-store review rules key to itThe one changed call shape is internal: the migration transform now takes the
adoption-ledger writer as an argument, and
loader._apply_document_migrationspassesits own
record_adoptionsat call time, so the existing patch seam still reaches it.loader.pyalso groups its residual responsibilities into commented sections insteadof interleaving them.
Backwards compatibility
Compatible: both facades re-export every name they had, as the same object, so every
existing import resolves and nothing is rejected, renamed or removed. A patch reaches
the code that looks the name up in the patched module. Names read by code that stays in
loader.py(the path helpers, the config writers,_log_config_clamp_event,DEFAULT_POOL_SIZE,record_adoptions, each_build_*name at its call site, thesnapshot globals) stay call-time seams on the loader. A helper read inside a relocated
builder or migration rule is now patched on
config.section_buildersorconfig.migration. A scan of everysetattr/patch.object/string-path patch intest/andsrc/finds no patch on theloaderorsectionsfacade that targetsone of those relocated names, and
config.mdlists both sets.Tests
test/test_config_refactor_contract.py(new) pins:honour_auto_approvebuilder/dataclass lockstep;workspace_root(create=False)resolving without creating anything;config_path/config_dir/DEFAULT_POOL_SIZE/_log_config_clamp_event/record_adoptions/env_path/write_config_atomically) and ones that live on their owner (section_builders._resolve_stub_servers,coerce_runtime_ceiling,_validated_stt_provider;migration.superseded_default_drift);test/test_config_module_boundaries.py: extended with the owner import DAG and a leaf-purity check onconfig/fields.py. The scanner countsfrom kiro_crew.config import <submodule>as that submodule and walks module-levelif/tryblocks, and a self-test pins that. Its subprocess check also proves importingsection_builders/migrationpulls in no loader, schema or validation.to_dict(), and six load scenarios with their full log output and on-disk result) compares byte-identical apart from the one added module alias.Manual verification
N/A — unit coverage sufficient: the change moves code and the equivalence snapshot plus the owned suites cover every observable contract.
config-baseline.jsonregenerates byte-identical, which is the operator-visible schema surface.Related Issues
no linked issue: internal refactor with no user-visible change.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)