feat(sources): close OriginSpec conformance-law gaps#3246
Merged
Conversation
…erved) Problem: polylogue-2qx.1.1 asked for the OriginSpec admission kernel plus a conformance law where missing parser, stream/parser conflict, ambiguous detector order, absent fixture, undeclared coverage, leaked Provider token, and non-injective collision each yield a source-locatable diagnostic. The kernel (polylogue/sources/origin_specs.py, built on polylogue/declarations) already existed on master -- it landed incrementally via unrelated feature PRs (#3051, #3087, #3088, #3092, #3201, #3228) without ever citing this bead, so bd's tracking never reflected it (2026-07-18 warroom sweep found no bead-tagged commits and reset it to open). Auditing it against every AC clause found three real gaps: (1) no diagnostic caught a public origin name colliding with a raw Provider-wire token; (2) no check parity-verified declared `stream_parser_path` presence against dispatch's `STREAM_RECORD_PROVIDERS` set, so a stream/parser binding conflict could silently drift from dispatch's actual streaming behavior; (3) the module docstring still claimed a live "reserved origin" pilot, but Grok shipped a real parser (#3201) after this bead was written, so no OriginSpec is currently `lifecycle="reserved"` and that admission path had no live proof. Solution: added a `_PROVIDER_TOKEN_VALUES` guard in `OriginSpecRegistry.register()` that rejects a declaration whose `public_name` collides with any `Provider` enum value, before the existing public-name/origin equality check (so it's independently testable). Added `validate_stream_parser_parity()`, parity-checked in tests against `sources/dispatch.py:STREAM_RECORD_PROVIDERS` the same way `validate_dispatch_precedence()` already parity-checks tightness order -- zero edits to dispatch.py itself, respecting the ownership boundary with the concurrent ingest_worker.py/decoders.py lane. Updated the module docstring to state Grok's promotion honestly and point at the synthetic reserved-lifecycle proof. Added five tests to tests/unit/sources/test_origin_specs.py: undeclared coverage rejection, provider-token-leak rejection, a synthetic `lifecycle="reserved"` registration proving the reserved admission contract (built from a `replace()` of the real Grok spec, since every current public `Origin` token is already executable or compatibility-only), and positive plus negative stream/parser parity checks. Verification: - devtools test tests/unit/sources/test_origin_specs.py -> 8 passed - devtools test tests/unit/sources/test_dispatch_ordering.py tests/unit/sources/test_dispatch_payloads.py -> 21 passed - devtools test -k "provider_completeness or origin_specs or dispatch_ordering" -> 26 passed - mypy --strict polylogue/sources/origin_specs.py tests/unit/sources/test_origin_specs.py -> Success, no issues - devtools verify --quick -> exit 0 (all 16 steps ok, including render all and layering; no topology regen needed, no new module/file added) Ref polylogue-2qx.1.1 Co-Authored-By: Claude <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughOrigin admission documentation and registration validation are updated. A stream-parser parity validator is added and exported, with tests covering coverage evidence, provider-token collisions, reserved lifecycle declarations, and provider/parser parity. ChangesOrigin validation
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant STREAM_RECORD_PROVIDERS
participant validate_stream_parser_parity
participant ORIGIN_SPECS
STREAM_RECORD_PROVIDERS->>validate_stream_parser_parity: provide stream-capable providers
validate_stream_parser_parity->>ORIGIN_SPECS: inspect executable origin parser paths
validate_stream_parser_parity-->>STREAM_RECORD_PROVIDERS: return parity diagnostics
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Owner
Author
|
Coordinator review (classifier was down during the lane's run — diff re-verified line-by-line by the coordinator; CodeRabbit rate-limited): 215-line additive audit-closure over the pre-existing kernel (which landed untagged via #3051/#3087/#3088/#3092/#3201/#3228 — the bead-tracking gap is exactly what the receipts in the close reason now record). Provider-token leak guard, stream-parser parity validator (read-only against dispatch's STREAM_RECORD_PROVIDERS — no dispatch.py edits, concurrent-lane ownership respected), and the synthetic reserved-lifecycle proof with a real anti-vacuity story. 26 tests green, mypy strict clean. Merging. |
Sinity
added a commit
that referenced
this pull request
Jul 21, 2026
…gaps closed) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QUsH3Rhq6oAZpYPWcsZqnZ
Sinity
added a commit
that referenced
this pull request
Jul 21, 2026
…gue-2qx.1.2) (#3250) ## Summary Audits and closes the remaining gap in polylogue-2qx.1.2 ("migrate every current origin onto OriginSpec"). Most of this bead's scope was already shipped to `master` untagged across #3051/#3087/#3088/#3092/#3201/#3228/#3246 (closing `polylogue-2qx.1.1`'s notes confirm this). This PR verifies that prior work end-to-end, proves the parity checks actually catch regressions (not just pass today), and closes one concrete residual gap: a second, un-declared provider-to-assembly-hook dispatch that Claude Code, Codex, and AI Studio/Drive depend on. ## Problem `polylogue/sources/origin_specs.py` already declares all eleven `Origin` tokens with lifecycle/detector-tightness/parser/fixture/coverage bindings, and `polylogue/sources/provider_completeness.py` already derives its rows from `ORIGIN_SPECS` (`PACKAGE_MODE_SPECS` is a tuple comprehension over it, parity-proven by `test_provider_completeness_is_a_projection_of_every_origin_spec`). Dispatch-order and stream-parser-binding parity are also already mechanically checked (`validate_dispatch_precedence`, `validate_stream_parser_parity`) against the real production values in `sources/dispatch.py` (`RECORD_DETECTOR_PROVIDER_ORDER`, `STREAM_RECORD_PROVIDERS`). What was genuinely missing: the bead's design explicitly calls for "Claude Code and Codex specs [to] expose typed assembly/orchestration/title/action extension hooks (consumed later by 2qx.2, j2zz, ih67) — a typed field on the spec, not another registry." `polylogue.sources.assembly.get_assembly_spec()` is exactly that second, un-declared provider dispatch (`ProviderAssemblySpec` factory for `Provider.CLAUDE_CODE`/`Provider.CODEX`/ `Provider.GEMINI`) — it existed in production but had no OriginSpec declaration or parity check, so a caller had no way to discover the hook from `origin_specs.py` and no test would catch it drifting from the real registry. Also: `docs/provider-origin-identity.md` documented Provider/Origin/Source doctrine but never pointed at `origin_specs.py` as the per-origin admission authority a reader should trust over any hand-maintained list. ## Solution - `polylogue/sources/origin_specs.py`: added `OriginSpec.assembly_spec_path` (`"module/path.py:ClassName"` or `None`) declaring which `ProviderAssemblySpec` a given origin's provider wire binds. Populated for the three origins with a real live hook: `claude-code-session` → `assembly_claude_code.py:ClaudeCodeAssemblySpec`, `codex-session` → `assembly_codex.py:CodexAssemblySpec`, `aistudio-drive` → `assembly_gemini.py:GeminiAssemblySpec` (its `Provider.GEMINI` wire is the one `get_assembly_spec` keys on). Added `validate_assembly_spec_parity()`, following the exact idiom of `validate_dispatch_precedence`/ `validate_stream_parser_parity`: it checks the declared field against the live `get_assembly_spec(provider)` return value rather than replacing that registry with a second one in `origin_specs.py`. - `tests/unit/sources/test_origin_specs.py`: two new tests — one asserting the three declared hook paths (and `None` for two origins without a live hook), one asserting `validate_assembly_spec_parity(get_assembly_spec) == ()` plus the mutation shape (a resolver that always returns `None` makes every origin that declares a hook path report `assembly_spec_parity_mismatch`). - `docs/provider-origin-identity.md`: added an "Origin admission" section naming `origin_specs.py` as the per-origin declaration authority and pointing at both live-production parity checks. - No parallel hand-maintained inventory was deleted, because the audit found none left inside my ownership (`polylogue/sources/**`) — see the residual below for the one still outstanding elsewhere. ### Residual found outside owned scope `polylogue/cli/shell_completion_values.py:_ORIGIN_DESCRIPTIONS` is a hand-maintained `dict[str, str]` of 8 of the 11 origin tokens (missing `beads-issue`, `grok-export`, `unknown-export`) used for shell-completion help text, and it is **not** parity-checked against `Origin`/`ORIGIN_SPECS` the way `polylogue/agent_integration/spec.py:ORIGIN_MEANINGS` already is (that one has a `RuntimeError` guard requiring exact `Origin`-enum order match — already satisfies AC4, no action needed there). `cli/**` is out of this lane's ownership (per dispatch instructions, another lane owns it concurrently); flagging as a follow-up rather than touching it here. ## Verification - `devtools test tests/unit/sources/test_origin_specs.py tests/unit/sources/test_provider_completeness.py` → **15 passed** - `devtools test tests/unit/sources/ -k "origin_specs or provider_completeness or dispatch or assembly"` → **144 passed** - `devtools test tests/unit/sources/test_parsers_props.py` (protected file) → **43 passed** - `devtools verify --quick` → all 16 steps `ok`, `"exit_code": 0` (ruff format/check, mypy --strict, render all, topology/layering/closure-matrix, manifests, ci-workflows, doc-commands, docs-coverage, test-infra-currency, test-clock-hygiene, pytest-timeout-overrides, degrade-loudly) - Anti-vacuity mutations, run manually then reverted (`git checkout --`), each confirmed the *existing* production dependency actually fails on the mutation before I added anything: - Removing `_grok_spec()` from the registration loop → `ORIGIN_SPEC_REGISTRY.diagnostics()` reports `missing_origin_spec` for `grok-export`. - Dropping Claude Code's `detector_tightness` below `gemini_cli_session`'s (contradicting its real last-in-branch-order position) → `validate_dispatch_precedence(RECORD_DETECTOR_PROVIDER_ORDER)` reports `dispatch_tightness_mismatch`. - Deleting Codex's new `assembly_spec_path` declaration → `validate_assembly_spec_parity(get_assembly_spec)` reports `assembly_spec_parity_mismatch` for `codex-session` (this is the mutation the new code in this PR is proven against). ## AC matrix (polylogue-2qx.1.2) 1. **Satisfied (pre-existing).** All eleven `Origin` tokens are declared exactly once in `ORIGIN_SPECS`; `set(by_origin) == set(Origin)` is asserted in `test_origin_specs_cover_the_public_enum_and_admission_lifecycles`, and `OriginSpecRegistry.diagnostics()` emits `missing_origin_spec` for any omission (proven above). 2. **Satisfied (pre-existing + this PR).** Every executable origin declares acquisition modes, detector/parser/stream-parser/fixture/coverage/fidelity/reparse fields; `claude-code-session` additionally declares 6 typed `OriginArtifactRule`s for its workflow/journal/transcript/sidecar/adopt-manifest/coordinator-stream family. `grok-export` is `lifecycle="executable"` today (it shipped a real parser via #3201/polylogue-611 after 2qx.1.1's pilot design assumed it would stay reserved — documented at the top of `origin_specs.py`); the `reserved` lifecycle contract itself is proven against a synthetic variant since no current `Origin` is genuinely reserved. `unknown-export` is `lifecycle="compatibility-only"` with explicit fallback semantics; `beads-issue` is executable with `issue-jsonl` acquisition and its own non-`accepted` completeness maturity caveat (no harvested schema sample yet). This PR adds the Claude/Codex/AI-Studio assembly hook declaration. 3. **Satisfied (pre-existing).** `validate_dispatch_precedence`/`validate_stream_parser_parity` parity-check tightness and stream-binding against `sources/dispatch.py`'s real `RECORD_DETECTOR_PROVIDER_ORDER`/`STREAM_RECORD_PROVIDERS`; mutation-proven above (deleting/reordering a declaration fails). 4. **Satisfied (pre-existing) for `provider_completeness.py`; this PR extends it to the assembly-hook axis.** `PACKAGE_MODE_SPECS` is a direct tuple comprehension over `ORIGIN_SPECS`, parity-proven by `test_provider_completeness_is_a_projection_of_every_origin_spec`. `agent_integration/spec.py:ORIGIN_MEANINGS` is separately parity-guarded against `Origin` at import time. **Deferred**: `cli/shell_completion_values.py:_ORIGIN_DESCRIPTIONS` remains a stale, un-parity-checked hand-maintained inventory — out of this lane's ownership (`cli/**`), flagged as a residual above rather than a named follow-up bead (small, mechanical, single-file fix for whichever lane next touches CLI completions). 5. **Satisfied (pre-existing).** `aistudio-drive`'s `provider_wires=(Provider.GEMINI, Provider.DRIVE)` with `collision_policy` is registration-enforced (`OriginSpecRegistry.register` raises `ValueError` if `len(provider_wires) > 1` without a `collision_policy`, tested in `test_origin_spec_rejects_missing_fixture_and_noninjective_collision_without_policy`); `docs/provider-origin-identity.md` already documented the non-reversal doctrine, and this PR adds the pointer from that doc to the enforcing code. 6. **Misframed — recorded honestly rather than claimed satisfied.** `polylogue-2qx.2` (Claude Code orchestration artifact admission) already closed via PR #3088, and its own close reason states it shipped as a `claude_workflow_materializer` convergence stage *without* the OriginSpec migration this bead was meant to gate — the blocking edge was explicitly force-closed as "over-blocking" because the merged implementation disproves that ordering. So AC6 as written ("Claude/Codex extension hooks are the only admission path used by 2qx.2...") cannot be retroactively true for `2qx.2`. `j2zz` (Codex child-action lowering) and `ih67` (Codex title enrichment) are still open; this PR's new `assembly_spec_path`/`validate_assembly_spec_parity` gives them a real typed admission point to consume going forward, but I did not modify `assembly_codex.py`/`ih67`/`j2zz` scope — those remain their own beads' work, not migrated by me here. ## Files touched - `polylogue/sources/origin_specs.py` - `tests/unit/sources/test_origin_specs.py` - `docs/provider-origin-identity.md` Ref polylogue-2qx.1.2 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added guidance on how origin metadata is declared, validated, and kept aligned with runtime behavior. - Documented checks for provider completeness and assembly-related configuration. - **Improvements** - Added validation to detect mismatches between declared origin capabilities and available assembly behavior. - Added assembly configuration metadata for Claude Code, Codex, and AI Studio origins. - **Tests** - Added coverage confirming assembly declarations and runtime parity checks behave as expected. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes the remaining conformance-law gaps in the OriginSpec admission kernel
(
polylogue/sources/origin_specs.py) against every clause ofpolylogue-2qx.1.1's acceptance criteria: a public-origin/Provider-token leakguard, a stream/parser binding parity check against dispatch, and a live
proof of the
lifecycle="reserved"admission path.Problem
polylogue-2qx.1.1asked for the OriginSpec admission kernel (built on thepolylogue/declarationsDeclarationSpec kernel frompolylogue-o21.1) plus aconformance law where missing parser, stream/parser conflict, ambiguous
detector order, absent fixture, undeclared coverage, leaked Provider token,
and non-injective Provider-to-Origin collision each yield a source-locatable
diagnostic.
Auditing the live repo found the kernel already exists on master —
polylogue/sources/origin_specs.pylanded incrementally via unrelatedfeature PRs (#3051, #3087, #3088, #3092, #3201, #3228: Claude Workflow
admission, Hermes ATOF/ATIF, the Grok parser, provider_completeness
migration) without ever citing this bead, so
bd's tracking never reflectedit — the 2026-07-18 warroom sweep found no bead-tagged commits and reset the
bead to open even though the code was there. It already covers all 11
Origintokens, consumes the declarations kernel correctly, and is wiredinto
provider_completeness.py, the artifact taxonomy, the live watcher, andClaude Code orchestration.
Auditing it clause-by-clause against the AC found three real gaps:
public_namecolliding with a rawProvider-wire token — the doctrine indocs/provider-origin-identity.md("no provider wording on public originsurfaces") was enforced only indirectly (public_name must equal
origin.value, and no currentOrigin/Providerpair happens tocollide), with no explicit guard or diagnostic for a future collision.
stream_parser_pathpresence againstsources/dispatch.py:STREAM_RECORD_PROVIDERS— a stream/parser bindingcould silently drift from dispatch's actual streaming behavior with no
diagnostic.
Grok shipped a real parser (
polylogue-611, feat(sources): wire Grok account-data export parser #3201) after this bead waswritten, so no
OriginSpecis currentlylifecycle="reserved"and thatadmission path had no live proof.
Solution
_PROVIDER_TOKEN_VALUESand a guard inOriginSpecRegistry.register()that rejects a declaration whose
public_namecollides with anyProviderenum value, ordered before the existing public-name/origin equality check
so it is independently testable (a synthetic declaration can trip it
without also tripping the equality check).
validate_stream_parser_parity(), parity-checked againstsources/dispatch.py:STREAM_RECORD_PROVIDERSthe same wayvalidate_dispatch_precedence()already parity-checks detector tightnessorder. Zero edits to
dispatch.py— only a new read-only import of itsexisting
STREAM_RECORD_PROVIDERSconstant, respecting this slice'sownership boundary with the concurrent
ingest_worker.py/decoders.pylane.
reserved to executable, and point at the new synthetic reserved-lifecycle
test as the live proof of that admission path (since no real production
Originis currently reserved).tests/unit/sources/test_origin_specs.py: undeclared-coverage rejection, provider-token-leak rejection, a synthetic
lifecycle="reserved"registration (built viareplace()of the real Grokspec) proving the reserved admission contract requires no parser/detector
tightness while still requiring coverage/fixture evidence, and positive
plus negative stream/parser parity checks.
Verification
devtools test tests/unit/sources/test_origin_specs.py→ 8 passeddevtools test tests/unit/sources/test_dispatch_ordering.py tests/unit/sources/test_dispatch_payloads.py→ 21 passeddevtools test -k "provider_completeness or origin_specs or dispatch_ordering"→ 26 passedmypy --strict polylogue/sources/origin_specs.py tests/unit/sources/test_origin_specs.py→ Success, no issues founddevtools verify --quick→ exit 0 (all 16 steps ok: format, lint, mypy, render all, topology, layering, closure-matrix, schema roundtrip, manifests, ci-workflows, doc-commands, docs-coverage, test-infra-currency, test-clock-hygiene, pytest-timeout-overrides, degrade-loudly)AC matrix
origin_specs.pydefines complete typed fields/lifecycle states, consumespolylogue/declarationswithout adding source semantics to that kernelpolylogue/declarations/*and confirmingorigin_specs.pyonly wrapsDeclarationSpec/DeclarationRegistry, adding no kernel-layer semantics)Origintoken is admitted as executable or compatibility-onlydispatch.pyuses derived registration/order or is parity-checked by it; adding a synthetic executable origin requires one OriginSpec + adapter + fixturesvalidate_dispatch_precedence()(pre-existing) plus this PR's newvalidate_stream_parser_parity()parity-checkdispatch.py'sRECORD_DETECTOR_PROVIDER_ORDER/STREAM_RECORD_PROVIDERSwithout restructuring dispatch.pyValueErrorraises (now also covered by a dedicated undeclared-coverage test in this PR); ambiguous detector order was pre-existing (ambiguous_detector_tightness); this PR adds the previously-missing stream/parser-conflict diagnostic (stream_parser_parity_mismatch) and leaked-Provider-token guard. "Cyclic" detector order has no distinct failure mode beyond ambiguous tightness, since tightness is a total order, not a graphcollision_policyfield + registration guard, exercised byaistudio-drive'sProvider.GEMINI/Provider.DRIVEfiber)polylogue-2qx.1.2(migrate every current origin onto OriginSpec, deleteparallel inventories) is explicitly out of this slice's scope per the bead's
own design text — it is largely already superseded in practice too (all 11
origins are already declared here and
provider_completeness.pyalreadyprojects from
ORIGIN_SPECS), but a formal audit of that bead's own AC(exact-eleven-token enumeration, parallel-inventory deletion, dispatch
golden fixture) is left to whoever picks it up.
Ref polylogue-2qx.1.1
Summary by CodeRabbit