Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 4 additions & 13 deletions loopx/capabilities/periodic_report/triggers.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@

from .core import (
TRIGGER_DECISION_SCHEMA,
_REPORTABLE_TRIGGER_KINDS,
_boolean,
_digest,
_integer,
Expand All @@ -21,16 +22,6 @@

TRIGGER_REQUEST_SCHEMA = "periodic_report_trigger_request_v0"

_REPORTABLE_KINDS = {
"bounded_segment_milestone",
"cadence_due",
"manual",
"material_blocker",
"material_decision",
"material_recovery",
"primary_goal_outcome",
"vision_closed",
}
_NON_REPORTABLE_KINDS = {
"monitor_unchanged",
"state_refreshed",
Expand Down Expand Up @@ -84,11 +75,11 @@ def _normalize_profile(raw: object) -> dict[str, str]:

def _normalize_policy(raw: object) -> dict[str, Any]:
policy = _object(raw, "trigger_policy")
enabled_raw = policy.get("enabled_kinds", sorted(_REPORTABLE_KINDS))
enabled_raw = policy.get("enabled_kinds", sorted(_REPORTABLE_TRIGGER_KINDS))
enabled: list[str] = []
for index, value in enumerate(_list(enabled_raw, "trigger_policy.enabled_kinds")):
kind = _token(value, f"trigger_policy.enabled_kinds[{index}]")
if kind not in _REPORTABLE_KINDS:
if kind not in _REPORTABLE_TRIGGER_KINDS:
raise ValueError(f"trigger_policy.enabled_kinds[{index}] is not reportable")
if kind not in enabled:
enabled.append(kind)
Expand Down Expand Up @@ -388,7 +379,7 @@ def _normalize_candidates(raw: object, evaluated_at: str) -> list[dict[str, Any]
label = f"candidates[{index}]"
item = _object(value, label)
kind = _token(item.get("trigger_kind"), f"{label}.trigger_kind")
if kind not in _REPORTABLE_KINDS | _NON_REPORTABLE_KINDS:
if kind not in _REPORTABLE_TRIGGER_KINDS | _NON_REPORTABLE_KINDS:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P3] 候选资格校验仍能绕过共享定义。 35 项架构用例保持绿。owner 移除 manual 后,候选继续受理该事件并错误标为 disabled_by_profile。 在真实判定入口覆盖候选资格对共享定义的使用。

raise ValueError(f"{label}.trigger_kind is invalid")
observed_at = _timestamp(item.get("observed_at"), f"{label}.observed_at")
observed_value = datetime.fromisoformat(observed_at.replace("Z", "+00:00"))
Expand Down
305 changes: 305 additions & 0 deletions tests/architecture/test_periodic_report_reportable_kind_owner.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,305 @@
"""Guard one owner for the periodic-report reportable trigger kinds (#4447).

``_REPORTABLE_TRIGGER_KINDS`` in ``periodic_report/core.py`` decides which
trigger kinds may produce a periodic report. ``triggers.py`` restated the same
eight kinds as ``_REPORTABLE_KINDS`` while *already importing* eleven names from
``core`` -- the strongest form of this repository's duplicate-knowledge case: a
module restating a constant whose owner it already imports from. It now borrows
the owner object and the restated name is retired.

The hard checks are limited to identifiable eligibility decisions: the owner
states the vocabulary once, the consumer borrows that exact object and retires
its restated name, and the report mapping's domain equals the vocabulary. The
report mapping (``_REPORT_KIND``) legitimately keys on the same eight kinds, so
its keys are pinned by runtime domain parity, never by banning same-valued
literals -- an equivalent rewrite of that mapping must stay green. Behavioural
parity runs through the consumer's own policy normalizer and the real decision
entry.

Equal values make a renamed copy indistinguishable by value, so the policy
entry is also exercised under a controlled change of the shared definition:
with ``manual`` removed from the imported object the entry rejects the explicit
list (and its default follows the reduced set), and with the definition
restored the same request passes. A same-valued copy in that path is inert
under the change and fails there, while the report mapping and per-profile
selections -- different slots -- are unaffected.

The neighbouring ``_NON_REPORTABLE_KINDS`` (five different kinds) is a separate
vocabulary and is deliberately left alone; it must not overlap the reportable
set. A profile's ``enabled_kinds`` is a different slot -- a per-profile choice
of which kinds *that profile* enables -- so two profiles may legitimately select
the same eight kinds with different intervals; those selections are verified
through the real decision entry, not by counting literals. Whole-package
same-value matching stays in the existing advisory lane (the semantic
inventory's merge candidates): the convergence RFC makes merge candidates
advisory because an equal value set is not proof of one concept, and
``reuse_existing`` requires the same slot, compatible scope and an equivalent
contract.
"""

from __future__ import annotations

import ast
import pathlib
from typing import Any

import pytest

from loopx.capabilities.periodic_report import core, triggers

REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
OWNER_PATH = "loopx/capabilities/periodic_report/core.py"
CONSUMER_PATH = "loopx/capabilities/periodic_report/triggers.py"

KINDS = frozenset(
{
"bounded_segment_milestone",
"cadence_due",
"manual",
"material_blocker",
"material_decision",
"material_recovery",
"primary_goal_outcome",
"vision_closed",
}
)
NON_REPORTABLE = frozenset(
{
"monitor_unchanged",
"state_refreshed",
"surface_only",
"todo_completed",
"vision_checkpoint",
}
)


def _members(node: ast.expr) -> frozenset[str] | None:
"""Fold a set / frozenset / list / tuple of plain string literals to members."""

if isinstance(node, ast.Call):
fname = getattr(node.func, "id", None) or getattr(node.func, "attr", None)
if fname in {"frozenset", "set"} and len(node.args) == 1:
return _members(node.args[0])
return None
if isinstance(node, (ast.Set, ast.List, ast.Tuple)):
values = [
element.value
for element in node.elts
if isinstance(element, ast.Constant) and isinstance(element.value, str)
]
if len(values) == len(node.elts) and values:
return frozenset(values)
return None


def _kind_literal_sites(source: str) -> list[int]:
"""Every collection literal folding to KINDS, counted once (call+set is one)."""

tree = ast.parse(source)
wrapped = {
id(node.args[0])
for node in ast.walk(tree)
if isinstance(node, ast.Call)
and (getattr(node.func, "id", None) or getattr(node.func, "attr", None))
in {"frozenset", "set"}
and len(node.args) == 1
}
return [
node.lineno
for node in ast.walk(tree)
if id(node) not in wrapped and _members(node) == KINDS
]


def test_the_owner_states_the_recorded_members_once() -> None:
assert frozenset(core._REPORTABLE_TRIGGER_KINDS) == KINDS
source = (REPO_ROOT / OWNER_PATH).read_text(encoding="utf-8")
assert len(_kind_literal_sites(source)) == 1

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 同文件硬检查会拒绝独立的报告类型映射。 29 组实际 CLI 输出和退出码相同,硬检查因第二份同值元组失败。 按词表实际定义和用法验证,保留其他职责的同值表示。



def test_the_consumer_borrows_the_owner_object() -> None:
assert triggers._REPORTABLE_TRIGGER_KINDS is core._REPORTABLE_TRIGGER_KINDS


def test_the_report_mapping_domain_is_the_owner_set() -> None:
# The report mapping keys on the same eight kinds -- a legitimate
# same-valued use, not a restatement of the vocabulary. Pin the domain at
# runtime so any equivalent source shape (dict literal, dict(zip(...)))
# stays green while a drifted domain still fails.
assert set(triggers._REPORT_KIND) == KINDS


def test_the_consumer_retired_its_restated_name() -> None:
assert not hasattr(triggers, "_REPORTABLE_KINDS")
source = (REPO_ROOT / CONSUMER_PATH).read_text(encoding="utf-8")
assert "_REPORTABLE_TRIGGER_KINDS" in source

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 验证名单校验跟随触发类型的共享定义。 同值副本通过全部 34 项架构测试。共享定义去掉 manual 后,原提交以 enabled_kinds[0] is not reportable 拒绝该请求,副本仍接受配置,并返回 no_material_trigger。 在真实策略入口验证显式名单随共享集合变化。用受控的共享定义变更验证拒绝和恢复,并让等价的报告映射与独立 profile 继续通过。



def test_the_non_reportable_neighbour_is_a_different_set() -> None:
# The five non-reportable kinds stay where they are; they are a separate
# vocabulary and must not overlap the reportable set.
assert frozenset(triggers._NON_REPORTABLE_KINDS) == NON_REPORTABLE
assert NON_REPORTABLE.isdisjoint(KINDS)


def test_the_preset_enabled_kinds_is_a_configuration_not_the_vocabulary() -> None:
from loopx.capabilities.periodic_report import presets

# A preset's ``enabled_kinds`` is a configuration choice -- which kinds
# *this preset* enables -- not the vocabulary of which kinds are
# reportable. Borrowing the owner here would auto-enable any future
# reportable kind in the weekly preset, a domain decision rather than a
# deduplication. Two presets, two different selections, so the list is a
# per-preset policy; it is verified behaviourally below, not pinned by a
# literal-site count that a second legitimate profile would break.
weekly = presets._WEEKLY_PROGRESS_PROFILE["trigger_policy"]["enabled_kinds"]
assert frozenset(weekly) == KINDS
portfolio = presets.resolve_periodic_report_profile_preset("portfolio-progress")
assert portfolio["trigger_policy"]["enabled_kinds"] == ["cadence_due"]


# --- profile selections are configuration, verified through the real decision entry ---


def _decide(
profile_id: str, policy: dict[str, Any], kind: str, facts: dict[str, Any]
) -> dict[str, Any]:
return triggers.build_periodic_report_trigger_decision(
{
"schema_version": triggers.TRIGGER_REQUEST_SCHEMA,
"evaluated_at": "2026-11-12T00:00:00Z",
"profile": {"profile_id": profile_id, "profile_version": "v1"},
"trigger_policy": policy,
"candidates": [
{
"trigger_kind": kind,
"observed_at": "2026-11-12T00:00:00Z",
"source_ref": f"{profile_id}-{kind}",
"evidence_digest": f"{profile_id}-{kind}-evidence",
"facts": facts,
}
],
}
)


def test_each_profile_selection_drives_the_real_decision() -> None:
from loopx.capabilities.periodic_report import presets

weekly = presets.resolve_periodic_report_profile_preset("weekly-progress")
portfolio = presets.resolve_periodic_report_profile_preset("portfolio-progress")
# The same authorized manual candidate: weekly enables it, portfolio does not.
selected = _decide(
"weekly_progress", weekly["trigger_policy"], "manual", {"authorized": True}
)
assert selected["selected_trigger_kind"] == "manual"
suppressed = _decide(
"portfolio_progress",
portfolio["trigger_policy"],
"manual",
{"authorized": True},
)
assert suppressed["selected_trigger_kind"] is None
assert suppressed["suppressed_triggers"][0]["reason"] == "disabled_by_profile"


def test_a_second_profile_may_select_the_same_kinds_with_its_own_interval() -> None:
# Two profiles may legitimately select the same eight kinds with different
# intervals: the selection belongs to each profile, so the real decision
# entry must accept this one rather than treat it as a duplicate vocabulary.
policy = {"enabled_kinds": sorted(KINDS), "minimum_interval_seconds": 21_600}
decision = _decide("six_hour_digest", policy, "cadence_due", {"due": True})
assert decision["ok"] is True
assert decision["selected_trigger_kind"] == "cadence_due"
assert decision["trigger_policy"]["enabled_kinds"] == sorted(KINDS)
assert decision["trigger_policy"]["minimum_interval_seconds"] == 21_600


# --- behavioural parity through the consumer's own policy normalizer ----------------------


@pytest.mark.parametrize("kind", sorted(KINDS))
def test_each_reportable_kind_is_accepted(kind: str) -> None:
normalized = triggers._normalize_policy({"enabled_kinds": [kind]})
assert normalized["enabled_kinds"] == [kind]


@pytest.mark.parametrize("kind", sorted(NON_REPORTABLE | {"not_a_kind"}))
def test_a_non_reportable_kind_is_rejected(kind: str) -> None:
with pytest.raises(ValueError, match="is not reportable"):
triggers._normalize_policy({"enabled_kinds": [kind]})


def test_the_default_enabled_kinds_is_the_owner_set() -> None:
# With no explicit enabled_kinds the policy defaults to the full owner set,
# so the consumer's default is pinned to the borrowed object, not a copy.
normalized = triggers._normalize_policy({})
assert normalized["enabled_kinds"] == sorted(KINDS)


def test_the_policy_entry_follows_the_shared_definition(
monkeypatch: pytest.MonkeyPatch,
) -> None:
# A renamed same-value copy feeding only the explicit-list check passes every
# value check above, because the values are equal today. Make the definition
# observably different instead -- drop ``manual`` -- and require the real
# entry to reject it, then accept it again once the definition is restored.
# A copy is inert under that change, so it fails here.
reduced = KINDS - {"manual"}
request = {
"schema_version": triggers.TRIGGER_REQUEST_SCHEMA,
"evaluated_at": "2026-11-12T00:00:00Z",
"profile": {"profile_id": "manual_probe", "profile_version": "v1"},
"trigger_policy": {"enabled_kinds": ["manual"]},
"candidates": [
{
"trigger_kind": "surface_only",
"observed_at": "2026-11-12T00:00:00Z",
"source_ref": "manual-probe",
"evidence_digest": "manual-probe-evidence",
"facts": {},
}
],
}
with monkeypatch.context() as patched:
# Patch both legitimate lookup forms of the shared object, so an
# attribute-style ``core._REPORTABLE_TRIGGER_KINDS`` read stays green too.
patched.setattr(core, "_REPORTABLE_TRIGGER_KINDS", reduced)
patched.setattr(triggers, "_REPORTABLE_TRIGGER_KINDS", reduced)
with pytest.raises(ValueError, match=r"enabled_kinds\[0\] is not reportable"):
triggers.build_periodic_report_trigger_decision(request)
assert triggers._normalize_policy({})["enabled_kinds"] == sorted(reduced)
decision = triggers.build_periodic_report_trigger_decision(request)
assert decision["ok"] is True
assert decision["selected_trigger_kind"] is None
assert decision["reason"] == "no_material_trigger"


# --- the folded-value scan bites every restatement form and leaves the others -----------

_MEMBER_TEXT = ", ".join(repr(kind) for kind in sorted(KINDS))
_NON_MEMBER_TEXT = ", ".join(repr(kind) for kind in sorted(NON_REPORTABLE))

POISON_CORPUS = (
("bare set restatement", f"X = {{{_MEMBER_TEXT}}}\n", 1),
("frozenset call", f"X = frozenset({{{_MEMBER_TEXT}}})\n", 1),
("set call over a list", f"X = set([{_MEMBER_TEXT}])\n", 1),
("list literal", f"X = [{_MEMBER_TEXT}]\n", 1),
("tuple literal", f"X = ({_MEMBER_TEXT})\n", 1),
("renamed binding is still caught", f"_ANY = {{{_MEMBER_TEXT}}}\n", 1),
("nested inside a function", f"def f():\n return {{{_MEMBER_TEXT}}}\n", 1),
("importing the owner is not a restatement", "from .core import _REPORTABLE_TRIGGER_KINDS\n", 0),
("alias rebind is not a restatement", "_REPORTABLE_KINDS = _REPORTABLE_TRIGGER_KINDS\n", 0),
("the non-reportable neighbour is a different set", f"_NON_REPORTABLE_KINDS = {{{_NON_MEMBER_TEXT}}}\n", 0),
("a single kind is not the whole set", 'X = {"manual"}\n', 0),
)


@pytest.mark.parametrize(
"label,source,expected", POISON_CORPUS, ids=[case[0] for case in POISON_CORPUS]
)
def test_the_census_names_every_form_and_leaves_the_others(
label: str, source: str, expected: int
) -> None:
assert len(_kind_literal_sites(source)) == expected, label
Loading