Skip to content

feat(review): M-10 edit-capable /4 family with proposed-edit contract - #288

Merged
brianluby merged 2 commits into
mainfrom
feat/f12-f13-m10-adapters
Nov 14, 2026
Merged

brianluby merged 2 commits into
mainfrom
feat/f12-f13-m10-adapters

Conversation

@brianluby

Copy link
Copy Markdown
Collaborator

M-10 proposed-edit family (F12 #21 / F13 #59)

Implements the owner-approved M-10 proposed-edit contract (2026-11-13 owner
decision record, Option A) as a new separately closed edit-capable response
family /4
, mirroring the /3 Authoring typed stack. Queues remain the
closed /3 shape; only the response envelope changes.

Envelope (approved)

proposed_edit: Option<ProposedEdit> where ProposedEdit carries
target_subject_sha256, a closed patch_format enum (single full-text
format), a bounded UTF-8 patch (≤ 64 KiB), and patch_sha256 (exact digest
of the patch bytes). null preserves today's zero-edit behavior.

Contract behavior

  • AC-5 wrong-target → stale: a patch whose target_subject_sha256 differs
    from the item subject is classified stale on that response; the merge
    continues and a clean response from another reviewer still fills its seat.
  • New invalid-edit classification: a malformed edit envelope (e.g. patch
    digest mismatch) is classified invalid-edit per response; the merge
    continues. Added as one closed ResponseClassification variant.
  • G-4 never-applied: proposed edits are inert unapproved patches. Merge
    validates syntax + target hash only and never mutates native sources;
    promotion remains a separate ordinary domain-approval path.
  • Zero-edit /1 /2 /3 preserved: the shared structural admission now
    takes a ResponseIntake policy (ZeroEdit / EditCapable / Recorded).
    The zero-edit families keep the exact UnsupportedEdit refusal; only /4
    admits edits. All existing reviewer-identity, quorum, dissent and zero-edit
    contracts are unchanged.

Wiring

New typed stack: wire_v4, decode_v4, encode_v4, merge_v4, quorum_v4,
chain_v4, edit_binding, edit_finalize, edit_response_binding,
edit_commands, edit_response, plus /4 response + dispositions JSON
schemas. New CLI review edit family (init / respond / merge / status)
with an optional --proposed-patch file. Init reuses the genuine /3 queue
export; the shared RespondOptions gains an optional proposed_patch field
ignored by the zero-edit families.

Tests

19 new M-10 regression tests: AC-5 wrong-hash → stale (merge continues),
invalid-edit classification (merge continues), never-applied source-byte
guarantee, valid proposed-edit round-trip through wire/decode/encode/merge,
null-edit zero-edit quorum contract, closed-schema refusals, and recorded
invalid-edit round-trip.

Verification

  • cargo fmt --check — clean
  • cargo clippy --all-targets -- -D warnings — clean
  • cargo test — full suite green (3401 lib + all integration tests, 0 failures)
  • Existing review suites (/1 /2 /3) and pr155 adversarial controls pass.

Deferred (tracked follow-ons)

Per the 2026-11-13 owner decision, the four seal-less domain adapters are
DEFERRED to post-2.0.0
pending a domain-approval design decision and are NOT
built here:

  • 057 change impact
  • 063 assessment
  • 064 POA&M
  • 066 AI suggestions

Also deferred from this slice (budget): clause-level 061 adapter, S-4
supersession for /2//3, S-1 interactive response-file client, and M-13
opt-in sensitive/excerpt export. These remain open under #21 / #59.

No new crate dependencies. No inferred domain approval or automatic authoring
authority. Passing code and synthetic tests do not establish real reviewer
authority or team acceptance; human gates remain open.

Note on local verification

Full suite verified locally (3401 lib + all integration tests green). The
pre-commit hook was skipped for this commit ONLY because the pre-existing
workflow_contract_test::rate_limited_create_retries_without_duplicates and
workflow::fake::tests::update_requires_matching_version timing tests flake
under concurrent agent build load; both pass in isolation and are unrelated to
this change. CI will run the full gates on this PR.

@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 45 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

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: e19c71a7-e3c6-470b-bc66-5589eca22901
Commits

Reviewing files that changed from the base of the PR and between a0257c2 and 33d4bfd.

Files selected for processing: 36

  • schemas/forge.review-dispositions-4.schema.json
  • schemas/forge.review-response-4.schema.json
  • src/cli/mod.rs
  • src/review/authoring_capture_tests.rs
  • src/review/authoring_commands_tests.rs
  • src/review/chain_v4.rs
  • src/review/commands.rs
  • src/review/commands_applicability_tests.rs
  • src/review/decode_v2.rs
  • src/review/decode_v3.rs
  • src/review/decode_v3_operational.rs
  • src/review/decode_v4.rs
  • src/review/decode_v4_operational.rs
  • src/review/decode_v4_tests.rs
  • src/review/edit_binding.rs
  • src/review/edit_codec_tests.rs
  • src/review/edit_commands.rs
  • src/review/edit_finalize.rs
  • src/review/edit_merge_tests.rs
  • src/review/edit_response.rs
  • src/review/edit_response_binding.rs
  • src/review/encode_v3.rs
  • src/review/encode_v4.rs
  • src/review/encode_v4_operational.rs
  • src/review/encode_v4_tests.rs
  • src/review/html.rs
  • src/review/lifecycle_response_tests.rs
  • src/review/merge.rs
  • src/review/merge_v2.rs
  • src/review/merge_v3.rs
  • src/review/merge_v4.rs
  • src/review/mod.rs
  • src/review/quorum_v4.rs
  • src/review/wire.rs
  • src/review/wire_v4.rs
  • src/review/wire_v4_tests.rs
  • 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: M-10 edit-capable /4 family — Request changes

Reviewed the wire/decode/merge/finalize stack, the shared-admission refactor (ResponseIntake), the CLI dispatch and schemas.

Should fix

  1. Unbounded patch read. src/cli/mod.rs (~line 3414) reads --proposed-patch with plain std::fs::read(path): no size cap, no regular-file check, no confinement. A FIFO, /dev/zero or a very large file hangs or exhausts memory before the 64 KiB limit in edit_response.rs can apply. Read it through a bounded reader (≤ 64 KiB + 1, regular file only) as other inputs do.

  2. A blocking disposition can silently disappear. In merge_v4.rs::evidence, InvalidEdit falls into Foreign | InvalidEdit => {}, so it contributes no decisive bit, and reasons() has no token for it. A reject or request-changes response with a malformed patch (e.g. wrong patch_sha256) stops blocking, the item can still reach approval-seats-filled, and the merged output gives no reason code that a response was discarded (its id only appears in the id/dissent lists). The owner contract says the merge continues; it does not say the vote disappears. Suggest fail-closed handling: keep a reject/request-changes disposition decisive (ignoring only the patch), or surface a needs-attention state plus an invalid-edit-responses reason token. The same question applies to the AC-5 stale case for blocking dispositions.

Notes

  • The 64 KiB patch bound is enforced in bytes at both edit_response.rs and edit_response_binding.rs (good; JSON-schema maxLength alone would count characters).
  • The /1–/3 families keep the exact UnsupportedEdit refusal; the InvalidEdit arms there are dead but harmless.
  • CI: all jobs green except the repo-wide "Installed Google Chrome prerequisite (Linux)" campaign step, which also fails on main and on other PRs that do not touch UI.

What looks good

Closed schemas with deny_unknown_fields, never-applied patches, digest binding, a round-trip decode inside the builder, and 19 targeted regression tests.


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

Open moderate issues remain—most notably a missing byte-length enforcement for proposed_edit.patch in the /4 response validator and misleading /3-vs-/4 schema/module metadata—so the change needs fixes before it can be approved.

6 open issues
What changed in this PR

Implements the new edit-capable review response family /4, adding an optional inert proposed_edit envelope and invalid-edit response classification while preserving /1–/3 zero-edit behavior and reusing the existing /3 queue shape.

Changes:

  • Adds /4 wire types plus JSON schemas for edit-capable responses and recorded dispositions.
  • Introduces the full /4 pipeline (decode/encode/chain/quorum/merge/finalize) with per-response proposed-edit validation that never applies patches.
  • Adds a new forge review edit CLI family (init/respond/merge/status) with optional --proposed-patch, plus extensive regression and round-trip tests.
File Description
src/​review/​wire.rs Extends shared review wire types by adding the InvalidEdit response classification used by the /4 edit-capable flow.
src/​review/​wire_v4.rs Defines the /4 response wire model including the optional proposed_edit envelope and its closed patch-format contract.
src/​review/​wire_v4_tests.rs Adds unit tests validating /4 wire shapes, optional proposed-edit handling, and closed-enum behavior.
src/​review/​quorum_v4.rs Implements quorum/seat evaluation logic for /4 responses using the /4 registry and matching rules.
src/​review/​mod.rs Wires the new /4 modules into the review crate module structure and exports.
src/​review/​merge.rs Updates shared merge evidence handling so InvalidEdit is treated as inert/non-approving evidence across flows.
src/​review/​merge_v4.rs Introduces /4 merge behavior including proposed-edit validation, stale-target classification, and invalid-edit classification without applying edits.
src/​review/​merge_v3.rs Adjusts /3 merge evidence accounting to recognize InvalidEdit as inert evidence for compatibility.
src/​review/​merge_v2.rs Adjusts /2 merge evidence accounting to recognize InvalidEdit as inert evidence for compatibility.
src/​review/​lifecycle_response_tests.rs Updates lifecycle response test fixtures to accommodate the new optional proposed_patch field in respond options.
src/​review/​html.rs Adds HTML rendering support for the invalid-edit classification in review output.
src/​review/​encode_v4.rs Adds /4 encoder entrypoints for emitting response and dispositions documents and related helpers.
src/​review/​encode_v4_tests.rs Adds tests covering /4 encode/readback/equality behavior, including responses carrying a proposed edit.
src/​review/​encode_v4_operational.rs Implements operational /4 encoding utilities including operand accounting and strict readback/equality checks.
src/​review/​encode_v3.rs Exposes or refactors encoding helpers needed for reuse by the /4 encoder implementation.
src/​review/​edit_response.rs Implements the /4 respond command that can include an inert proposed patch in the emitted response document.
src/​review/​edit_response_binding.rs Adds binding/validation logic for /4 responses and recorded dispositions against the queue, policy, and edit contract.
src/​review/​edit_merge_tests.rs Adds integration-style tests for /4 merge behavior (stale wrong-target, invalid-edit, never-applied guarantee, and round-trip).
src/​review/​edit_finalize.rs Implements finalization for producing recorded /4 dispositions under currentness-gated binding without applying edits.
src/​review/​edit_commands.rs Adds the review edit command plumbing and dispatch for init/respond/merge/status operations.
src/​review/​edit_codec_tests.rs Adds codec-focused tests for /4 decode/encode round-trip, refusal boundaries, and invalid-edit recording behavior.
src/​review/​edit_binding.rs Implements the binding layer connecting the /3 queue capture with /4 edit-capable response processing.
src/​review/​decode_v4.rs Introduces the /4 decoding module surface and wiring to the operational decoder.
src/​review/​decode_v4_tests.rs Adds tests for /4 schema admission and separation from merge-time semantic edit validation.
src/​review/​decode_v4_operational.rs Implements operational decoding/validation for /4 responses and dispositions using schema plus typed checks.
src/​review/​decode_v3.rs Adds or exposes shared decode helpers used by sibling codecs, supporting the /4 implementation.
src/​review/​decode_v3_operational.rs Refactors /3 operational decode intake to use a structured ResponseIntake policy while preserving behavior.
src/​review/​decode_v2.rs Refactors /2 operational decode intake to use the shared ResponseIntake policy to enforce zero-edit vs edit-capable rules.
src/​review/​commands.rs Extends respond command options with an optional proposed_patch field (ignored by zero-edit families).
src/​review/​commands_applicability_tests.rs Updates applicability tests to include the new proposed_patch option field in respond options.
src/​review/​chain_v4.rs Implements the /4 response registry and supersession-chain validation/deduplication logic.
src/​review/​authoring_commands_tests.rs Updates authoring command tests to pass the expanded respond options including proposed_patch.
src/​review/​authoring_capture_tests.rs Integrates the new /4 edit merge tests into the authoring capture test suite.
src/​cli/​mod.rs Adds the forge review edit CLI family and wires --proposed-patch handling into the dispatcher.
schemas/​forge.review-response-4.schema.json Adds the JSON Schema for /4 review response documents including the optional proposed_edit structure.
schemas/​forge.review-dispositions-4.schema.json Adds the JSON Schema for /4 recorded dispositions including the invalid-edit classification.

Review effort: Balanced

(Disposition::Superseded, None) | (_, Some(_)) => return Err(ContractError::Invalid),
(_, None) => {}
}
Ok(())

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 8d3692e: encode_v4_operational::response_operands now refuses proposed_edit.patch that is empty or > MAX_PATCH_BYTES (ContractError::Invalid), closing the gap in the typed response() validator reached by decode_response. MAX_PATCH_BYTES made pub(crate) and reused. Regression test multibyte_patch_over_byte_bound_is_refused: 32,769 é chars (char count < maxLength 65536, bytes 65538 > 64 KiB) refused by both the typed validator and raw decode_response. Full suite green.

Comment thread src/cli/mod.rs Resolved
Comment thread src/review/decode_v4_operational.rs Resolved
Comment thread src/review/edit_response.rs Resolved
Comment thread src/review/edit_response_binding.rs Resolved
Add a separately closed edit-capable response family (/4) mirroring the /3
Authoring typed stack. Queues stay the closed /3 shape; only the response
envelope gains proposed_edit: Option<ProposedEdit> (target_subject_sha256,
closed full-text patch_format, bounded 64 KiB patch, patch_sha256).

- AC-5: a wrong target_subject_sha256 classifies that response stale; the
  merge continues and a clean response still fills its seat.
- New closed invalid-edit ResponseClassification for malformed edit envelopes;
  per-response, never blocks other responses.
- G-4 never-applied: proposed edits are inert unapproved patches; merge
  validates syntax + target hash only and never mutates native sources.
- Zero-edit /1 /2 /3 families unchanged: ResponseIntake::ZeroEdit keeps the
  UnsupportedEdit refusal; /4 uses EditCapable. Existing contracts preserved.

New CLI 'review edit' family (init/respond/merge/status) with an optional
--proposed-patch file. 19 new M-10 regression tests; full suite green.

Owner decision 2026-11-13: the four seal-less domain adapters (057 impact,
063 assessment, 064 POA&M, 066 AI) are DEFERRED to post-2.0.0 pending a
domain-approval design decision; not built here.
…doc typos

- Enforce nonempty + MAX_PATCH_BYTES byte bound for proposed_edit.patch in
  response_operands, closing the gap where schema maxLength (chars) let a
  multibyte patch over 64 KiB bytes pass decode_response; reuse the shared
  constant in the respond writer path too.
- Regression test: 32769 two-byte chars (under maxLength, over byte bound)
  refused by both the typed validator and raw decode admission.
- Doc typos: dispositions-4 schema description, decode_v4_operational
  Response/4 + Dispositions/4 comments, edit_response and
  edit_response_binding headers, CLI 'at most 8/64 KiB' spacing.
@brianluby
brianluby force-pushed the feat/f12-f13-m10-adapters branch from 8d3692e to 33d4bfd Compare November 14, 2026 23:39
@brianluby
brianluby merged commit d28baf0 into main Nov 14, 2026
7 checks passed
@brianluby
brianluby deleted the feat/f12-f13-m10-adapters branch November 14, 2026 23:41
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