Skip to content

feat(review): clause-level 061 adapter with per-clause subject profile - #289

Closed
brianluby wants to merge 2 commits into
feat/f12-f13-m10-adaptersfrom
feat/f12-f13-deferred
Closed

brianluby wants to merge 2 commits into
feat/f12-f13-m10-adaptersfrom
feat/f12-f13-deferred

Conversation

@brianluby

Copy link
Copy Markdown
Collaborator

Summary

Implements the clause-level 061 adapter deferred item (F13 #59 / F12 #21). Each captured human clause becomes one reviewable subject bound to its exact original raw identity, borrowing from the genuine sealed CurrentAuthoringPlanClosure — reusing the existing mapping/applicability adapter pattern (no second convention).

Stacked on M-10 PR #288 (base feat/f12-f13-m10-adapters).

Changes

  • hash_v3 profile8 clause_subject: domain-separated per-clause fingerprint over the clause key, exact original digest and extent (independent byte-oracle test).
  • adapters::authoring_clause: prepare() re-verifies each selected clause's exact original against its sealed member (tampered original → Binding refusal); bind_queue() binds every clause subject to its own sealed ordinal source pin.
  • CurrentAuthoringPlanClosure::clause_members(): borrows each sealed clause's native key + complete original digest.
  • Consumed in authoring_binding::prepare (retained) and authoring_finalize (bind_queue), mirroring the /1 adapter consumption.

Contracts preserved

The /3 whole-plan queue shape and all existing zero-edit /1//2//3, quorum, dissent and M-10 /4 contracts are unchanged.

Verification

  • 4 new clause tests (per-clause binding, tampered-original refusal, selection order/membership, hash oracle).
  • 598 review tests green; cargo fmt --check, cargo clippy --all-targets -- -D warnings clean; pre-commit hook passed all gates.

Deferred (not in this PR)

S-4 supersession for Lifecycle /2 and Authoring /3 remains open — the supersession stack (wire/decode/binding/command/capture union) is V1-only and extending it to /2//3 is a separate large change. Reported honestly per assignment.

@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: e80e3edb-3271-4e57-a575-a7898c029e59

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

Share

Copy link
Copy Markdown
Collaborator Author

Code review: clause-level 061 adapter — Needs discussion

Reviewed adapters/authoring_clause.rs, the authoring_binding / authoring_finalize wiring, hash_v3::clause_subject and the tests. (Stacked on #288; retarget after it lands.)

Should fix

  1. Likely regression for plans with no human clauses. authoring_clause::prepare returns ContractError::Invalid for an empty selection, and authoring_binding::prepare now always calls it with every clause key. src/authoring/scaffold.rs emits "human_clauses": [], so a plan with no clauses would fail authoring review preparation. Please either allow an empty selection when the plan has zero clauses or add a test showing this case is unreachable.

  2. No-op "binding" check. At the end of bind_queue, crate::review::chain::compare(&pin.raw_sha256, fact.subject_sha256(), ledger)?; discards the returned ordering, so nothing is checked. It also compares a raw original digest to a domain-separated subject hash, which would never be equal by design. Remove it or replace it with a real check (e.g. the queue item's subject against fact.subject_sha256()).

Discussion

  1. The facts are verified but not consumed. The /3 queue shape is unchanged, so reviewers still review the whole plan; clauses() is retained and re-checked but no item is derived from it. The PR/ticket wording ("each captured human clause becomes one reviewable subject") overstates what ships. Consider saying it is preparatory.

  2. Uncharged quadratic scans. For up to 10,000 clauses, declared.iter().position(...) and pins.iter().find(...) (with a format! per clause) run per fact while the ledger only charges one visit. Use a map keyed by clause key and ordinal.

What looks good

Per-clause digest re-derivation, tamper refusal, strictly-ordered selection, and an independent byte-oracle test for the hash profile.


Generated by Claude Code

@brianluby
brianluby marked this pull request as ready for review November 14, 2026 22:15
Copilot AI balanced review requested due to automatic review settings November 14, 2026 22:15
@brianluby

Copy link
Copy Markdown
Collaborator Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟡 Changes recommended

The change still has unresolved findings—most notably a potentially O(n²) clause-binding loop up to 10k clauses plus confusing/misleading comparison and ordering semantics—so it needs fixes before approval.

3 open issues
What changed in this PR

Implements the clause-level Authoring /3 “061” adapter so each captured human clause becomes its own reviewable subject, bound to the sealed closure’s exact original identity and pinned during finalize.

Changes:

  • Add hash_v3::clause_subject (Profile8) to fingerprint clause key + original digest + byte length.
  • Introduce adapters::authoring_clause to prepare per-clause facts, re-verify originals, and bind each clause subject to its sealed queue pin.
  • Extend sealed authoring closure plumbing and wire clause binding into authoring finalize, with targeted adapter/hash tests.
File Description
src/​review/​hash_v3.rs Adds the Profile8 per-clause subject hashing routine (clause_subject) for clause-level review subjects.
src/​review/​hash_v3_tests.rs Adds oracle-style tests validating the new per-clause subject hash behavior.
src/​review/​authoring_finalize.rs Integrates clause-subject queue-pin binding into the Authoring /3 finalize flow before issuance.
src/​review/​authoring_capture.rs Exposes sealed clause member information (key and complete original digest) via clause_members() for adapter use.
src/​review/​authoring_capture_tests.rs Updates the authoring capture test suite to include the new clause adapter tests.
src/​review/​authoring_binding.rs Plumbs preparation of per-clause review subjects into authoring binding preparation and associated data flow.
src/​review/​adapters/​mod.rs Registers/exports the new authoring_clause adapter module within the adapters namespace.
src/​review/​adapters/​authoring_clause.rs Implements per-clause fact preparation, original-byte re-verification, and binding of each clause subject to its sealed ordinal source pin.
src/​review/​adapters/​authoring_clause_tests.rs Adds tests covering per-clause binding, tampered-original refusal, selection/membership rules, and hash expectations.

Review effort: Balanced

Comment thread src/review/adapters/authoring_clause.rs Outdated
Comment on lines +113 to +116
let ordinal = declared
.iter()
.position(|key| *key == fact.subject_id())
.ok_or(ContractError::Binding)?;

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 566c2bc: replaced the per-fact position() scan with a BTreeMap<&str, usize> built once before the loop (entry().or_insert(ordinal), first-wins matching the old scan; manifest enforces unique clause keys). Lookups are now O(log n); unknown key still ContractError::Binding. Derived storage charge updated to reflect the map entry type. All clause tests + full suite green.

Comment thread src/review/adapters/authoring_clause.rs Outdated
if pin.raw_sha256 != fact.raw_sha256() || pin.byte_length != fact.byte_length() {
return Err(ContractError::Binding);
}
crate::review::chain::compare(&pin.raw_sha256, fact.subject_sha256(), ledger)?;

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 566c2bc: replaced chain::compare with an explicit ledger.bytes(pin.raw_sha256.len() + fact.subject_sha256().len()) charge — identical byte accounting, no discarded Ordering. chain::compare itself stays (still used by chain.rs binary search).

Comment thread src/review/authoring_binding.rs Outdated
})
}

/// Borrow every captured human-clause key in exact native order for per-clause re-review.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 566c2bc: comment now reads "in lexicographic BTreeMap key order" — accurately describes the BTreeMap iteration, no longer implying native declaration order.

brianluby added a commit that referenced this pull request Nov 14, 2026
… charge

CodeRabbit findings on PR #289 (clause-061 adapter):
- bind_queue precomputes a BTreeMap of clause key -> declaration ordinal
  once, replacing the per-fact O(n) position() scan (O(n^2) at 10k
  clauses) with O(log n) lookups; first-wins ordinal, unknown-key refusal
  and derived storage charge preserved.
- Replace the misleading chain::compare() call with an explicit
  ledger.bytes() charge of both complete digest extents (same accounting,
  no discarded lexical comparison).
- Correct clause_subjects comment: keys iterate in lexicographic BTreeMap
  key order, not native declaration order.
@brianluby
brianluby force-pushed the feat/f12-f13-m10-adapters branch from 8d3692e to 33d4bfd Compare November 14, 2026 23:39
Each captured human clause becomes one reviewable subject bound to its exact
original raw identity, borrowing from the genuine sealed CurrentAuthoringPlanClosure.

- hash_v3 profile8 clause_subject: domain-separated per-clause fingerprint over
  the clause key, exact original digest and extent (independent byte oracle).
- adapters::authoring_clause: prepare() re-verifies each selected clause's exact
  original against its sealed member; a tampered clause original refuses.
  bind_queue() binds every clause subject to its own sealed ordinal source pin.
- CurrentAuthoringPlanClosure::clause_members() borrows each sealed clause's
  native key and complete original digest.
- Consumed in authoring_binding::prepare (retained) and authoring_finalize
  (bind_queue), mirroring the /1 mapping/applicability adapter pattern.

The /3 whole-plan queue shape and all existing zero-edit/quorum/dissent/M-10
contracts are unchanged. 4 new clause tests; 598 review tests green.
… charge

CodeRabbit findings on PR #289 (clause-061 adapter):
- bind_queue precomputes a BTreeMap of clause key -> declaration ordinal
  once, replacing the per-fact O(n) position() scan (O(n^2) at 10k
  clauses) with O(log n) lookups; first-wins ordinal, unknown-key refusal
  and derived storage charge preserved.
- Replace the misleading chain::compare() call with an explicit
  ledger.bytes() charge of both complete digest extents (same accounting,
  no discarded lexical comparison).
- Correct clause_subjects comment: keys iterate in lexicographic BTreeMap
  key order, not native declaration order.
@brianluby
brianluby force-pushed the feat/f12-f13-deferred branch from 566c2bc to 59234a3 Compare November 14, 2026 23:39
@brianluby
brianluby deleted the branch feat/f12-f13-m10-adapters November 14, 2026 23:41
@brianluby brianluby closed this Nov 14, 2026
brianluby added a commit that referenced this pull request Nov 14, 2026
… charge

CodeRabbit findings on PR #289 (clause-061 adapter):
- bind_queue precomputes a BTreeMap of clause key -> declaration ordinal
  once, replacing the per-fact O(n) position() scan (O(n^2) at 10k
  clauses) with O(log n) lookups; first-wins ordinal, unknown-key refusal
  and derived storage charge preserved.
- Replace the misleading chain::compare() call with an explicit
  ledger.bytes() charge of both complete digest extents (same accounting,
  no discarded lexical comparison).
- Correct clause_subjects comment: keys iterate in lexicographic BTreeMap
  key order, not native declaration order.
brianluby added a commit that referenced this pull request Nov 14, 2026
#292)

* feat(review): clause-level 061 adapter with per-clause subject profile

Each captured human clause becomes one reviewable subject bound to its exact
original raw identity, borrowing from the genuine sealed CurrentAuthoringPlanClosure.

- hash_v3 profile8 clause_subject: domain-separated per-clause fingerprint over
  the clause key, exact original digest and extent (independent byte oracle).
- adapters::authoring_clause: prepare() re-verifies each selected clause's exact
  original against its sealed member; a tampered clause original refuses.
  bind_queue() binds every clause subject to its own sealed ordinal source pin.
- CurrentAuthoringPlanClosure::clause_members() borrows each sealed clause's
  native key and complete original digest.
- Consumed in authoring_binding::prepare (retained) and authoring_finalize
  (bind_queue), mirroring the /1 mapping/applicability adapter pattern.

The /3 whole-plan queue shape and all existing zero-edit/quorum/dissent/M-10
contracts are unchanged. 4 new clause tests; 598 review tests green.

* fix(review): clause binding uses key->ordinal map and explicit digest charge

CodeRabbit findings on PR #289 (clause-061 adapter):
- bind_queue precomputes a BTreeMap of clause key -> declaration ordinal
  once, replacing the per-fact O(n) position() scan (O(n^2) at 10k
  clauses) with O(log n) lookups; first-wins ordinal, unknown-key refusal
  and derived storage charge preserved.
- Replace the misleading chain::compare() call with an explicit
  ledger.bytes() charge of both complete digest extents (same accounting,
  no discarded lexical comparison).
- Correct clause_subjects comment: keys iterate in lexicographic BTreeMap
  key order, not native declaration order.
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