Skip to content

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

Closed
psychologister wants to merge 1 commit into
loopx-project:mainfrom
psychologister:codex/periodic-report-schema-visibility-owner
Closed

psychologister wants to merge 1 commit into
loopx-project:mainfrom
psychologister:codex/periodic-report-schema-visibility-owner

Conversation

@psychologister

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: 5d13cf6
  • 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: psychologister <230141834+psychologister@users.noreply.github.com>
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