Skip to content

refactor(periodic_report): fold document schema and visibility vocabularies into one owner - #8832

Merged
loopx-agent merged 1 commit into
loopx-project:mainfrom
2430468136:codex/periodic-report-schema-visibility-owner
Nov 15, 2026
Merged

loopx-agent merged 1 commit into
loopx-project:mainfrom
2430468136:codex/periodic-report-schema-visibility-owner

Conversation

@2430468136

Copy link
Copy Markdown
Contributor

Goal And Delivered Outcome

  • Outcome basis / optional anchor: Self-contained ordinary maintenance contribution (single-owner convergence); no issue or roadmap id invented.
  • Goal/source and gap: loopx/capabilities/periodic_report/field_shapes.py is the declared owner of the capability's closed field vocabularies. Two decisions were still restated by consumers: adapters.py defined DOCUMENT_SCHEMA and _ITEM_VISIBILITIES, and audience.py defined _DOCUMENT_SCHEMA and _VISIBILITIES. One decision had three owners, so a renamed or value-drifted copy would let the validators disagree about the same payload fields undetected.
  • Observable before → after, with the validation row that proves it: Before — the schema tag literal was defined in two modules and the primary/supporting visibility pair existed as two separate set literals, with no guard against a third copy. After — both decisions are stated only in field_shapes.py (DOCUMENT_SCHEMA, ITEM_VISIBILITIES), the consumers import the owner objects, and the extended owner guard fails if any second definition reappears anywhere in the package (see the unit and regression_parity rows).
  • Issue/task and intended base: Related to the single-owner convergence direction; base main.

Author Declaration

  • Written by: model_agent

Implemented against

  • Specification and revision: no written specification; the request in this PR is the basis.
  • Criteria:
Criterion (spec clause) Disposition Symbol / path Test or command
The document schema tag is stated only by the owner and read by identity elsewhere implemented field_shapes.DOCUMENT_SCHEMA; adapters/audience imports; adapters re-export tests/architecture/test_periodic_report_field_shapes_owner.py
The item-visibility pair is stated only by the owner and read by identity elsewhere implemented field_shapes.ITEM_VISIBILITIES; adapters/audience imports tests/architecture/test_periodic_report_field_shapes_owner.py
  • Self-check before submission: ran the extended owner guard, the periodic_report capability/presentation/extensions subset, and the full tests/architecture suite on both a pristine base worktree and the head worktree and compared failure sets; ran three mutations against the guard; ran ruff, the public-boundary scan, and the semantic-vocabulary drift smoke. Deliberately kept adapters.DOCUMENT_SCHEMA importable as a plain re-export (four external readers: bindings, archive, and the HTML/Markdown renderers) and did not touch schema tags owned by other capabilities.

Scope And Continuation

  • Completed scope and remaining work: complete within this scope. The fold removes the duplicate definitions and extends the existing owner guard so the two new decisions are pinned by value, by identity, by wiring through both consumer faces, and by retired-local-name checks.
  • Slice boundary / successor: N/A — the maintenance outcome is complete. The vocabularies field_shapes.py already owned are unchanged.

Validation

  • Tested revision: 762b50f
  • Run state: finished
  • Input classes: synthetic, public_fixture
Check kind Result Public-safe evidence / limitation
unit passed python -m pytest tests/architecture/test_periodic_report_field_shapes_owner.py — 34/34 passed; census-by-value for the schema string and the visibility set (including reordered copies), identity, wiring through the adapters and audience faces, re-export identity for the four external readers, retired local names, with positive and negative controls.
regression_parity passed Pristine base vs head on identical selections: tests/architecture base 2 failed / 1842 passed, head 2 failed / 1851 passed; the 25-file periodic_report capability/presentation/extensions subset base 9 failed / 491 passed, head 9 failed / 491 passed. Failure sets byte-identical (pre-existing test_content_digest_single_owner and test_posix_flag_portability, plus 9 pre-existing pending-intent / turn-replan / goal-channel-delivery cases); the +9 are exactly the new guard tests. Three mutations each caught: restored schema literal copy in audience → census + retired-names; reordered visibility copy in adapters → set census + retired-names; divergent visibility copy in audience (drops supporting) → policy and document wiring + use-beyond-import + retired-names. Dependency-lock and top-level-module-budget invariants pass on head (7/7).
static passed python -m ruff check clean on all four changed files.
real_entrypoint passed loopx check --scan-path <changed files> reports public boundary scan clean: 4 files; the unrelated registry-goal error reproduces identically on the pristine base.
integration passed python examples/semantic-vocabulary-drift-smoke.py reports ok with byte-identical budget lines between base and head; the schema tag stays a single definition (moved) and the visibility pair is a new single-definition name, so no ratcheted collision budget moves.
static not_run mypy is not installed in the local environment; no changed file is in the pinned mypy scope (pyproject.toml [tool.mypy] files) or the Todo CLI adapter gate, so the CI type gates are unaffected.
  • Coverage and gaps: the changed paths are the two vocabulary definitions and their consumers (adapters item normalization, audience document and policy faces); the guard exercises both faces with in-set and out-of-set values and pins the four external re-export readers by identity. The full tests/ tree was not run locally — scope was tests/architecture (complete) plus the 25-file periodic_report capability/presentation/extensions subset; the pre-existing failures reproduce on the pristine base. No UI impact.

Frontend / Visual Evidence

  • UI impact: none
  • Before: N/A
  • After: N/A
  • First viewport and preview: N/A
  • States and viewports shown: N/A
  • Source data: none
  • Attention review: N/A
  • Craft review: N/A

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Refactoring (no functional changes)
  • Documentation update
  • Test update

LoopX Area

  • Control plane (goals, todos, quota, scheduler, registry, runtime)
  • Benchmark boundary (adapters, runners, verifiers, scoring, evidence)
  • Capability or extension (providers, adapters, skills)
  • Public docs or presentation surface (README, protocols, dashboard)
  • Build, packaging, installer, or CI
  • Host or runtime integration

Technical Direction

  • Direction / acceptance reference, when applicable: N/A (single-owner maintainability convergence).

Shared-authority RFC fixture impact

  • Production-scale fixture schema: N/A
  • Semantic dimensions changed, or reviewed no-impact rationale: N/A — no TypeScript control-plane or shared Goal Authority claim.
  • Provider conformance arms run: N/A
  • Read-only legacy/file/PostgreSQL three-arm rehearsal: N/A

Boundary Checklist

  • Neither the diff nor this PR body/comments/attachments disclose private state, credentials, raw traces or verifier output, internal links, or local machine paths.
  • I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
  • I kept the change scoped to the linked issue/task.
  • Existing English/Chinese RFC pairs both have a diff and the local premerge check passes, or no paired RFC changed. (no paired RFC changed)
  • I completed the visual evidence section for UI changes, or marked UI impact none.
  • Every commit includes a DCO Signed-off-by trailer (git commit -s).

…laries into one owner

adapters.py and audience.py each restated the document schema tag and the
primary/supporting visibility pair that field_shapes.py owns. Import both
decisions from the owner (adapters keeps DOCUMENT_SCHEMA importable for its
four external readers), and extend the existing owner guard with
census-by-value, identity, wiring and retired-local-name checks for the two
new decisions.

Signed-off-by: 2430468136 <130272264+2430468136@users.noreply.github.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-15T14:59:57.109393Z 762b50f PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@loopx-agent loopx-agent left a comment

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.

Reviewer: model_agent / gpt-6.1-sol / OpenAI / runtime_reported / reasoning effort max

动机

影响周期报告生成、受众匹配、归档和 HTML/Markdown 渲染的使用者。同一份 v0 文档通过来源规范化、受众选择、旧导入与两个渲染器。三组有效策略、七个非法输入及两个渲染结果在基线和候选一致。本次验收覆盖本地合成与报告规划。外部发送和部署继续由既有授权流程管理。报告 adapter 与 audience 分别定义 document schema 和 item visibility,未来增删一个值需要两次同步。

改动思路

把文档 label 和 visibility 收到现有 field_shapes。用 adapters 的 schema re-export 支持已有四个调用方。本次验收覆盖本地合成与报告规划。外部发送和部署继续由既有授权流程管理。沿用既有 schema、成员资格与消费顺序。对照真实入口和已经发布的格式,并用隔离安装核对导入依赖。现有值域的 owner

具体改动

  • one-report-vocabulary 已实现。field_shapes 持有文档标签与 visibility。两个真实规范化路径保持原输入、默认和拒绝。对应代码
  • preserve-existing-readers 已实现。bindings、archive、HTML 与 Markdown 继续通过 adapters 读取标签;隔离 wheel 的产物与基线逐字一致。对应代码
  • same-audience-scope 已实现。缺省、仅 supporting 及双 visibility 分别匹配 2、1、3 项,七个非法输入沿既有校验拒绝。对应代码

关键代码讲解

DOCUMENT_SCHEMA、ITEM_VISIBILITIES 持有已有 v0 标签和两种可见性。_normalize_item 规范化来源条目并验证其 visibility。normalize_periodic_report_audience_policy 按同一个已声明值域验证受众策略。实际消费路径

语义与 CI 对齐

架构基线 1842 通过、候选 1851 通过。两项同条件失败。报告链路两边均为 647 通过、9 项同标识及诊断失败,涉及旧 Goal activation、DSH 重放和 Goal Channel stop。词汇 drift 输出逐字一致。Ruff 与完整差异检查通过。实际比较基线 8ade78cddeb6bdcd947c0a81507393c4599c7652,对应 loopx/capabilities/periodic_report/README.md。基线规范

对主干的风险

受众计划依 typed owned_domains、item 规则与 visibility 选择符号身份,结果不扩大外部交付范围。来源和受众拒绝未知 visibility,受众与渲染器拒绝伪造的 v1。缺标记的 supporting 内容仍触发原错误。对照使用本地合成输入和隔离 wheel。实发 Lark 或部署不在这一轮的验收范围。基线与当前主干的合并树均已核对。现有输出、历史入口与失败情况在源码和独立安装路径分别读回。

我的整体评价

当前提交 762b50f8b2788afa7a1cb3bbc8eb27984ffd7283 通过独立代码评审。复用 field_shapes,保住 adapters 的兼容导入,按原产品入口核对两个消费者。三组有效策略、七个非法输入及两个渲染结果在基线和候选一致。局部闭集由一处维护,实际消费者的兼容与边界经过同条件对照。

English verdict: APPROVE | Exact head 762b50f8b2788afa7a1cb3bbc8eb27984ffd7283. Document, visibility, audience planning, and installed renderers match the baseline. The nine known report failures reproduce on both revisions.

@loopx-agent
loopx-agent merged commit ab0eecb into loopx-project:main Nov 15, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants