Merge origin/main into codex/merge-candidate-visibility

No conflict; the branch was only behind. loopx-project#4628 memoized python_facts in the
same module this branch extends, and the two changes compose.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: song <22676124+songoow@users.noreply.github.com>

Author: songoow

docs/architecture/rfcs/semantic-vocabulary-convergence-v0.md

@@ -869,18 +869,30 @@ state at which this RFC is complete; each row is a registry budget or a
 vocabulary property the smoke can check. Rows marked *open* wait on a Section
 12 decision and are the reason the plan is a skeleton until those are recorded.
 
-| Surface | Baseline (`1dc6ad8d8`) | Target when this RFC closes | Reached by |
-| --- | --- | --- | --- |
-| `effective_action` values | 33 literals, no owner symbol | one enum owner; `skip`, `observe_replay`, `block_replay`, and the two `quota_action_selection_*` codes gone from the decision slot; 32 decision values after accounting for the five previously missed producers and retiring the synthetic operator_gate value | M1 |
-| `effective_action` slots in one envelope | 3 vocabularies under one field name | 1, or a registered union if Q6 keeps the field | M1 (Q6) |
-| Turn vocabularies | 3 sets, 28 values, 21 distinct, 7 redundant spellings | 3 sets kept; projection and decision table generated and checked; spellings unchanged unless Q10 sets a merge | M2 (Q2, Q10 *open*) |
-| Same-runtime forks, semantic | 18 names | 0 | baseline PRs |
-| Conflicting values, semantic | 2 names | 0 | baseline PRs |
-| Multi-value forks | 4 (1 misclassified) | 0 after `scope` declares bounded-context names | M0.5 + baseline PRs |
-| Multi-value twins | 19 | 0 | baseline PRs |
-| Legacy should-run fields | 6 fields, 124 py / 10 ts module mentions | 0 fields | M3, identifier-counted |
-| Merge-candidate groups | 32 unreviewed | every group classified; only `same_semantics` groups merged | classification PR, then per-group PRs |
-| Control-plane py/ts twins | 43 | follows the TypeScript migration RFC; no target here | M4 |
+| Surface | Baseline (`1dc6ad8d8`) | Measured by | Target when this RFC closes | Reached by |
+| --- | --- | --- | --- | --- |
+| `effective_action` values | 33 literals, no owner symbol | registry `vocabularies.effective_action.values`; `semantic-vocabulary-drift-smoke.py` fails on an unregistered literal | one enum owner; `skip`, `observe_replay`, `block_replay`, and the two `quota_action_selection_*` codes gone from the decision slot; 32 decision values after accounting for the five previously missed producers and retiring the synthetic operator_gate value | M1 |
+| `effective_action` slots in one envelope | 3 vocabularies under one field name | no counter: the slot split is a Q6 decision, not a number. Read `relations.shared_field_names` | 1, or a registered union if Q6 keeps the field | M1 (Q6) |
+| Turn vocabularies | 3 sets, 28 values, 21 distinct, 7 redundant spellings | registry `vocabularies`; spelling overlap is `relations.same_concept` | 3 sets kept; projection and decision table generated and checked; spellings unchanged unless Q10 sets a merge | M2 (Q2, Q10 *open*) |
+| Same-runtime forks, semantic | 18 names | `semantic-vocabulary-drift-smoke.py`: `same_runtime_forks_semantic` | 0 | baseline PRs |
+| Conflicting values, semantic | 2 names | `semantic-vocabulary-drift-smoke.py`: `conflicting_values_semantic` | 0 | baseline PRs |
+| Multi-value forks | 4 (1 misclassified) | `semantic-vocabulary-drift-smoke.py`: `multi_value_forks` and `multi_value_forks_semantic`. Only the count is printed today; #4614 adds `divergent_value_sets` to name the surviving forks | 0 after `scope` declares bounded-context names | M0.5 + baseline PRs |
+| Multi-value twins | 19 | `semantic-vocabulary-drift-smoke.py`: `multi_value_twins` | 0 | baseline PRs |
+| Legacy should-run fields | 6 fields, 124 py / 10 ts module mentions | `semantic-vocabulary-drift-smoke.py`: one `<field>.py` / `<field>.ts` pair per field | 0 fields | M3, identifier-counted |
+| Merge-candidate groups | 32 unreviewed | `merge_candidate_groups()` in `loopx/semantics/inventory.py`; no command prints it today, and #4630 adds the CLI line. Read the reviewable count, not the raw one -- a registered cross-runtime vocabulary owns both its Python and TypeScript symbols, so those pairs are required by I3 rather than debt | every group classified; only `same_semantics` groups merged | classification PR, then per-group PRs |
+| Control-plane py/ts twins | 43 | `semantic-vocabulary-drift-smoke.py`: `independently_maintained` | follows the TypeScript migration RFC; no target here | M4 |
+
+*Measured by* names the command and field that print each surface today, the
+way Section 9 names a test for each claim. It deliberately does not carry the
+values: a transcribed number is stale on the next merge, and a reader who wants
+the current state runs the command rather than trusting a date. Dated values
+belong to the delivery tracker, issue #4447, which owns delivery status; this
+table stays a contract about where the truth is measured.
+
+Read the reviewable merge-candidate count rather than the raw one. The raw
+grouping pairs any two names carrying identical values, which includes the
+Python and TypeScript symbols a registered cross-runtime vocabulary is required
+by I3 to have. Treating those as debt is a measurement artifact, not drift.
 
 ### Two-track execution and enforcement lanes
 

docs/architecture/rfcs/semantic-vocabulary-convergence-v0.zh-CN.md

@@ -710,18 +710,27 @@ TypeScript effective-action 绑定与[术语表](../../reference/glossary.md)通
 注册表预算或 smoke 可检查的词表属性。标为*未决*的行等待第 12 节的决策，这也
 是计划在那些决策记录之前只是骨架的原因。
 
-| 表面 | 基线（`1dc6ad8d8`） | 本 RFC 关闭时的目标 | 由谁达成 |
-| --- | --- | --- | --- |
-| `effective_action` 取值 | 33 个字面量，无 owner 符号 | 一个枚举 owner；`skip`、`observe_replay`、`block_replay` 与两个 `quota_action_selection_*` 码从判定槽位移出；计入五个此前漏记的生产值并移除合成 operator_gate 后，共 32 个决策值 | M1 |
-| 同一 envelope 里的 `effective_action` 槽位 | 一个字段名下 3 套词表 | 1，或在 Q6 保留字段时为一个已注册并集 | M1（Q6） |
-| Turn 词表 | 3 套、28 值、21 个不同值、7 个冗余拼法 | 保留 3 套；投影与决策表生成并校验；拼法不变，除非 Q10 决定合并 | M2（Q2、Q10 *未决*） |
-| 同运行时分叉（语义） | 18 个名字 | 0 | 基线窄 PR |
-| 冲突值（语义） | 2 个名字 | 0 | 基线窄 PR |
-| 多值分叉 | 4（1 个误分类） | `scope` 声明有界上下文名字后为 0 | M0.5 + 基线窄 PR |
-| 多值孪生 | 19 | 0 | 基线窄 PR |
-| 旧 should-run 字段 | 6 个字段，124 py / 10 ts 模块提及 | 0 个字段 | M3，按标识符计数 |
-| 合并候选组 | 32 组未评审 | 每组已分类；只合并 `same_semantics` 的组 | 分类表 PR，随后逐组 PR |
-| 控制面 py/ts 孪生 | 43 | 跟随 TypeScript 迁移 RFC；本 RFC 不设目标 | M4 |
+| 表面 | 基线（`1dc6ad8d8`） | 由什么度量 | 本 RFC 关闭时的目标 | 由谁达成 |
+| --- | --- | --- | --- | --- |
+| `effective_action` 取值 | 33 个字面量，无 owner 符号 | 注册表 `vocabularies.effective_action.values`；`semantic-vocabulary-drift-smoke.py` 在出现未注册字面量时失败 | 一个枚举 owner；`skip`、`observe_replay`、`block_replay` 与两个 `quota_action_selection_*` 码从判定槽位移出；计入五个此前漏记的生产值并移除合成 operator_gate 后，共 32 个决策值 | M1 |
+| 同一 envelope 里的 `effective_action` 槽位 | 一个字段名下 3 套词表 | 无计数器：拆槽是 Q6 的决策而非一个数字。读 `relations.shared_field_names` | 1，或在 Q6 保留字段时为一个已注册并集 | M1（Q6） |
+| Turn 词表 | 3 套、28 值、21 个不同值、7 个冗余拼法 | 注册表 `vocabularies`；拼法重叠见 `relations.same_concept` | 保留 3 套；投影与决策表生成并校验；拼法不变，除非 Q10 决定合并 | M2（Q2、Q10 *未决*） |
+| 同运行时分叉（语义） | 18 个名字 | `semantic-vocabulary-drift-smoke.py`：`same_runtime_forks_semantic` | 0 | 基线窄 PR |
+| 冲突值（语义） | 2 个名字 | `semantic-vocabulary-drift-smoke.py`：`conflicting_values_semantic` | 0 | 基线窄 PR |
+| 多值分叉 | 4（1 个误分类） | `semantic-vocabulary-drift-smoke.py`：`multi_value_forks` 与 `multi_value_forks_semantic`。今天只打印计数；#4614 增加 `divergent_value_sets` 以按名字列出存活的分叉 | `scope` 声明有界上下文名字后为 0 | M0.5 + 基线窄 PR |
+| 多值孪生 | 19 | `semantic-vocabulary-drift-smoke.py`：`multi_value_twins` | 0 | 基线窄 PR |
+| 旧 should-run 字段 | 6 个字段，124 py / 10 ts 模块提及 | `semantic-vocabulary-drift-smoke.py`：每个字段一对 `<字段>.py` / `<字段>.ts` | 0 个字段 | M3，按标识符计数 |
+| 合并候选组 | 32 组未评审 | `loopx/semantics/inventory.py` 的 `merge_candidate_groups()`；今天没有任何命令打印它，#4630 增加该 CLI 行。读可评审数而非原始数——注册的跨运行时词表本就同时拥有 Python 与 TypeScript 两个符号，这类配对是 I3 的要求而不是债务 | 每组已分类；只合并 `same_semantics` 的组 | 分类表 PR，随后逐组 PR |
+| 控制面 py/ts 孪生 | 43 | `semantic-vocabulary-drift-smoke.py`：`independently_maintained` | 跟随 TypeScript 迁移 RFC；本 RFC 不设目标 | M4 |
+
+*由什么度量* 列点明今天打印每个表面的命令与字段，与第 9 节为每条断言点明一个
+测试的写法一致。它**刻意不携带数值**：誊抄来的数字在下一次合并时就过期，而想
+知道当前状态的读者应当去跑那条命令，而不是相信一个日期。带日期的数值归交付
+追踪（issue #4447，它拥有交付状态）；本表保持为「真值在哪里被度量」的契约。
+
+合并候选要读**可评审数**而非原始数。原始分组会把任意两个携带相同值集的名字配
+成一组，其中包含注册的跨运行时词表按 I3 **必须**同时拥有的 Python 与 TypeScript
+两个符号。把它们当作债务是度量伪影，不是漂移。
 
 ### 两条执行轨道与强制层级
 

examples/control_plane/status-collection-readmodel-smoke.py

@@ -7,6 +7,7 @@
 from pathlib import Path
 import sys
 import tempfile
+from types import SimpleNamespace
 from typing import Any
 
 
@@ -117,6 +118,7 @@ def assert_wrapper_parity(registry_path: Path, runtime_root: Path, scan_root: Pa
 def assert_context_orchestration() -> None:
     calls: list[tuple[str, dict[str, Any]]] = []
     runtime_root = Path("/tmp/status-collection-runtime")
+    history_audit = object()
 
     def record(name: str, value: Any) -> Any:
         calls.append((name, value if isinstance(value, dict) else {"value": value}))
@@ -136,23 +138,28 @@ def resolve_runtime_root(
         assert registry_path == Path("registry.json"), registry_path
         return runtime_root
 
-    def collect_history(**kwargs: Any) -> dict[str, Any]:
+    def collect_status_history(**kwargs: Any) -> SimpleNamespace:
         assert kwargs["limit"] == 20, kwargs
         assert kwargs["goal_id"] == GOAL_ID, kwargs
-        assert kwargs["include_runtime_goals"] is True, kwargs
-        return record(
-            "collect_history",
+        assert kwargs["status_include_runtime_goals"] is True, kwargs
+        history = record(
+            "collect_status_history",
             {
                 "goal_count": 1,
                 "run_count": 0,
                 "goals": [],
                 "activation_state_filter": kwargs.get("activation_state_filter"),
             },
         )
+        return SimpleNamespace(
+            status_history=history,
+            contract_audit=history_audit,
+        )
 
     def check_contract(**kwargs: Any) -> dict[str, Any]:
         assert kwargs["limit"] == 2, kwargs
         assert kwargs["goal_id_filter"] == GOAL_ID, kwargs
+        assert kwargs["history_audit"] is history_audit, kwargs
         return record(
             "check_contract",
             {
@@ -186,7 +193,7 @@ def build_attention_queue(**kwargs: Any) -> dict[str, Any]:
             "collect_global_registry_health",
             {"ok": True, "current_registry_is_global": True},
         ),
-        collect_history=collect_history,
+        collect_status_history=collect_status_history,
         check_contract=check_contract,
         build_attention_queue=build_attention_queue,
         build_runtime_summaries=lambda **kwargs: record(
@@ -229,7 +236,9 @@ def build_attention_queue(**kwargs: Any) -> dict[str, Any]:
         context=context,
     )
 
-    history_call = next(call for call in calls if call[0] == "collect_history")
+    history_call = next(
+        call for call in calls if call[0] == "collect_status_history"
+    )
     assert history_call[1]["activation_state_filter"] == "active", history_call
     contract_call = next(call for call in calls if call[0] == "check_contract")
     assert contract_call[1]["activation_state_filter"] == "active", contract_call
@@ -257,7 +266,7 @@ def build_attention_queue(**kwargs: Any) -> dict[str, Any]:
     assert [name for name, _ in calls][:4] == [
         "load_registry",
         "collect_global_registry_health",
-        "collect_history",
+        "collect_status_history",
         "check_contract",
     ], calls
 

loopx/canary/maintainability_ratchet.py

@@ -612,6 +612,83 @@ def collect_module_metric_findings(
     return sorted(findings, key=lambda item: str(item["id"]))
 
 
+def _git_show_text(repository_root: Path, rev: str, path: str) -> str | None:
+    result = subprocess.run(
+        ["git", "show", f"{rev}:{path}"],
+        cwd=repository_root, capture_output=True,
+        text=True, encoding="utf-8", errors="replace", check=False,
+    )
+    return result.stdout if result.returncode == 0 else None
+
+
+def _rev_baseline_ceilings(repository_root: Path, rev: str) -> dict[str, dict[str, int]]:
+    """Mirror ``module_metric_baseline`` for a committed revision."""
+    text = _git_show_text(repository_root, rev, "loopx/canary/module_metric_baseline.json")
+    if text is None:
+        return {}
+    payload = json.loads(text)
+    ceilings = payload.get("module_metric_ceilings")
+    if not isinstance(ceilings, dict):
+        return {}
+    return {
+        str(path): {key: int(metrics[key]) for key in ("lines", "any_count", "dict_any_count") if key in metrics}
+        for path, metrics in ceilings.items()
+        if isinstance(metrics, dict)
+    }
+
+
+def diff_scoped_module_ceiling_violations(
+    repository_root: Path,
+    changed_files: Sequence[str],
+    *,
+    base_ref: str,
+) -> list[dict[str, Any]]:
+    """Module growth that crossed a reviewed ceiling must settle in the same diff.
+
+    A module may exceed its pre-diff ceiling without this check firing, as long
+    as this diff did not cause the crossing; and a module whose ceiling this diff
+    raises can stay silent. The single case this flags is the one that previously
+    merged and turned ``main`` red until a separate reconciliation PR refreshed
+    the ledger: this diff grew a module past the ceiling it inherited, without
+    settling that ceiling here.
+    """
+    head_ceilings = module_metric_baseline(
+        repository_root / "loopx" / "canary" / "module_metric_baseline.json"
+    )
+    base_ceilings = _rev_baseline_ceilings(repository_root, (base_ref or "origin/main").strip() or "origin/main")
+    violations: list[dict[str, Any]] = []
+    for changed in changed_files:
+        relative = str(changed)
+        if not relative.startswith("loopx/") or not relative.endswith(".py"):
+            continue
+        checkout_path = repository_root / relative
+        if not checkout_path.is_file():
+            continue
+        head_lines = module_metrics(checkout_path)["lines"]
+        base_lines = _git_show_text(repository_root, (base_ref or "origin/main").strip() or "origin/main", relative)
+        if base_lines is None:
+            base_ceiling = MODULE_LINE_LIMIT
+            was_within_budget = True
+        else:
+            base_ceiling = base_ceilings.get(relative, {}).get("lines", MODULE_LINE_LIMIT)
+            was_within_budget = len(base_lines.splitlines()) <= base_ceiling
+        head_ceiling = head_ceilings.get(relative, {}).get("lines", MODULE_LINE_LIMIT)
+        crossed_inherited_ceiling = was_within_budget and head_lines > base_ceiling
+        if crossed_inherited_ceiling and head_ceiling < head_lines:
+            violations.append(
+                {
+                    "id": _finding_id("module_metric_budget", relative),
+                    "category": "module_metric_budget",
+                    "path": relative,
+                    "base_lines": 0 if base_lines is None else len(base_lines.splitlines()),
+                    "base_ceiling": base_ceiling,
+                    "head_lines": head_lines,
+                    "head_ceiling": head_ceiling,
+                }
+            )
+    return sorted(violations, key=lambda item: str(item["id"]))
+
+
 def evaluate_maintainability_findings(
     findings: Sequence[Mapping[str, Any]],
     *,

loopx/canary/premerge.py

@@ -502,6 +502,55 @@ def _diff_hygiene_checks(
     return checks
 
 
+def _module_ceiling_colocation_check(
+    *,
+    changed_files: list[str],
+    base_ref: str,
+    execute: bool,
+    repo_root: Path = REPO_ROOT,
+) -> dict[str, Any] | None:
+    python_files = [
+        str(path) for path in changed_files
+        if str(path).startswith("loopx/")
+        and str(path).endswith(".py")
+        and (repo_root / str(path)).is_file()
+    ]
+    if not python_files:
+        return None
+    base = (base_ref or "origin/main").strip() or "origin/main"
+    if not execute:
+        return {
+            "id": "module_ceiling_colocation",
+            "kind": "direct_import",
+            "command": "python3 examples/control_plane/control-plane-maintainability-ratchet-smoke.py",
+            "reason": "module growth that crossed its reviewed ceiling must settle in the same diff",
+            "status": "ready",
+            "ok": True,
+        }
+    from loopx.canary.maintainability_ratchet import diff_scoped_module_ceiling_violations
+
+    violations = diff_scoped_module_ceiling_violations(
+        repo_root, python_files, base_ref=base
+    )
+    ok = not violations
+    check: dict[str, Any] = {
+        "id": "module_ceiling_colocation",
+        "kind": "direct_import",
+        "command": "python3 examples/control_plane/control-plane-maintainability-ratchet-smoke.py",
+        "reason": "module growth that crossed its reviewed ceiling must settle in the same diff",
+        "status": "passed" if ok else "failed",
+        "ok": ok,
+    }
+    if violations:
+        check["detail"] = [
+            f"{item['path']}: grew {item['base_lines']} -> {item['head_lines']} lines "
+            f"past its inherited ceiling {item['base_ceiling']}; settle the ceiling in "
+            f"this diff (loopx/canary/module_metric_baseline.json)"
+            for item in violations
+        ]
+    return check
+
+
 def _py_compile_check(
     *,
     python_files: list[str],
@@ -805,6 +854,15 @@ def build_premerge_validation_gate(
     if py_compile is not None:
         direct_checks.append(py_compile)
 
+    module_colocation = _module_ceiling_colocation_check(
+        changed_files=files,
+        base_ref=base_ref,
+        execute=execute,
+        repo_root=target_repo_root,
+    )
+    if module_colocation is not None:
+        direct_checks.append(module_colocation)
+
     if files:
         catalog_progress = _section_progress_callback(
             progress_callback,