fix: preserve family invariants during parent replacement

[flyingrobots]

Ordinary claims could create a parent cycle or replace Alice's parent acquisition with Bob's while leaving Alice's child attached. Admission now refuses parent replacement whenever stored descendants remain, including same-holder replacements and expired unswept descendants. extend renews the existing family; release or sweep ends the relevant descendants before replacement. Leaves can still be replaced or reparented.

The README makes the policy explicit: child records name a parent job, but belong to the acquisition that admitted them. A batch may replace a leaf and then admit new children; it cannot admit a child and then replace its parent, or replace a parent whose children are already stored. Cycle checks include earlier batch plans. Observed ancestor records participate in the transaction's expected values. The JSON schema adds parent refusal details cycle and descendants, and the generated executable is rebuilt.

Validation on 41e511e5936b57f72cfbb0822a598ddd4df55b1a:

• Observed RED against the original executable for both reported corruptions and the child-first forced race. The independent model also failed seed 1701, operation 39, where admission incorrectly returned 0.
• Normal pre-commit lint passed. Normal pre-push make test passed 503 assertions, including 51 focused family assertions.
• Golden paths and edges cover leaf replacement, parent renewal/acquisition identity, release/recreate, expired unswept descendants, self/indirect cycles, input validation, batch ordering and byte-for-byte ref preservation after refusal.
• Both forced child-admission/replacement race directions pass. A model independent of production parsing and doctor checks 192 command operations across seeds 34, 1701 and 20260922, including full public family state, acquisition identities and unchanged refs after refusals.

Tests ran with Bash 5.3.9 and Git 2.54.0. The suite changes HOME, so the existing jsonschema installation was made available through PYTHONPATH; no dependency was installed. An earlier test run hit host-disk exhaustion. The unchanged commit passed the full gate after space was recovered, using a dedicated temporary directory.

The forced schedules test changes between observation and commit. They do not prove coherent membership/generation observation during partial visibility of a multi-ref transaction; #38 remains a separate investigation.

Fixes #34.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 0e14f556-ae5b-4a6d-ad3e-278a8233463f

📥 Commits

Reviewing files that changed from the base of the PR and between 01e39c3 and 41e511e.

📒 Files selected for processing (9)

• CHANGELOG.md
• Makefile
• README.md
• bin/git-locks
• lib/090-claim-planning.sh
• schema/git-locks.schema.json
• test/family-model.py
• test/family-replacement.sh
• test/test.sh

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

📜 Recent review details

🧰 Additional context used

🪛 ast-grep (0.45.3)

test/family-model.py

[info] 18-18: use secrets package over random package
Context: random.Random(seed)
Note: [CWE-330] Use of Insufficiently Random Values.

(avoid-random-python)

---

[error] 25-25: Command coming from incoming request
Context: subprocess.run([binary, *args], cwd=tmp, env=env, text=True, capture_output=True, timeout=15)
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').

(subprocess-from-request)

---

[error] 31-33: Avoid command injection
Context: subprocess.check_output(
["git", f"--git-dir={store}", "for-each-ref", "--format=%(refname) %(objectname)"], text=True
)
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').

(command-injection-python)

---

[error] 31-33: Command coming from incoming request
Context: subprocess.check_output(
["git", f"--git-dir={store}", "for-each-ref", "--format=%(refname) %(objectname)"], text=True
)
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').

(subprocess-from-request)

🪛 Ruff (0.16.5)

test/family-model.py

[error] 19-19: Standard pseudo-random generators are not suitable for cryptographic purposes

(S311)

---

[warning] 25-25: Missing type annotation for *args

(ANN002)

---

[error] 26-26: subprocess call: check for execution of untrusted input

(S603)

---

[warning] 26-26: subprocess.run without explicit check argument

Add explicit check=False

(PLW1510)

---

[warning] 26-26: Function definition does not bind loop variable env

(B023)

---

[error] 32-32: subprocess call: check for execution of untrusted input

(S603)

---

[error] 33-33: Starting a process with a partial executable path

(S607)

🔇 Additional comments (9)

bin/git-locks (1)

809-809: LGTM!

Also applies to: 817-861, 895-901, 1089-1089, 1126-1126, 2444-2444

lib/090-claim-planning.sh (1)

5-5: LGTM!

Also applies to: 13-57, 91-97, 285-285, 322-322

schema/git-locks.schema.json (1)

368-372: LGTM!

README.md (1)

348-354: LGTM!

CHANGELOG.md (1)

7-10: LGTM!

test/family-replacement.sh (1)

1-136: LGTM!

test/family-model.py (1)

1-88: LGTM!

test/test.sh (1)

1574-1576: LGTM!

Makefile (1)

3-3: LGTM!

---

📝 Summary

Summary by CodeRabbit

• Bug Fixes

  • Parent replacement is now refused when stored descendants remain, including expired-but-unswept descendants.
  • Self-parenting and indirect parent cycles are rejected.
  • Batch operations now enforce descendant and cycle protections while preserving valid leaf replacement.
  • Refusal responses identify whether the cause is a cycle or existing descendants.
  • Parent renewal continues to preserve the family and acquisition identity.

• Documentation

  • Updated the parent and replacement behavior documentation, including batch rules and refusal details.

• Tests

  • Added coverage for replacement, cycle detection, race conditions, and randomized family operations.

Walkthrough

Changes

Family replacement admission

Layer / File(s)	Summary
Family validation planning bin/git-locks, lib/090-claim-planning.sh	Claim planning tracks batch parent relationships, verifies ancestor refs, rejects cycles, and refuses replacement when descendants remain stored or planned.
Refusal output and documented contract schema/git-locks.schema.json, README.md, CHANGELOG.md	The schema, contract, and changelog describe cycle and descendants parent refusals and acquisition-preserving renewal behavior.
Family replacement validation test/family-replacement.sh, test/family-model.py, test/test.sh, Makefile	Tests cover descendants, expiry, batches, races, release and recreation, and 192 model-based operations. The new suite runs through test and lint targets.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant FirstClaim
  participant SecondClaim
  participant plan_family
  participant GitRefs
  FirstClaim->>GitRefs: prepare parent or child admission
  SecondClaim->>GitRefs: commit competing admission
  FirstClaim->>plan_family: re-plan family observations
  plan_family->>GitRefs: verify ancestor and descendant refs
  GitRefs-->>plan_family: return current family state
  plan_family-->>FirstClaim: accept or refuse with cycle/descendants

Loading

Merge Risk: ⚪ Minimal · up to 41e51

Parent replacement now rejects cyclic or descendant-invalid transitions while preserving supported renewal and leaf replacement behavior; the supplied coverage indicates the change is ready to merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 4 files. (5 skipped: 5…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: preserving family invariants during parent replacement.
Description check	✅ Passed	The description directly explains the parent replacement policy, cycle prevention, transaction checks, schema updates, tests, and issue addressed.
Linked Issues check	✅ Passed	The PR addresses all coding requirements in #34. README.md documents child binding to a parent acquisition and the replacement policy. lib/090-claim-planning.sh and bin/git-locks reject direct and ind…
Out of Scope Changes check	✅ Passed	The changed files remain within #34. README.md and CHANGELOG.md document the implemented policy. Makefile and test/test.sh integrate the required tests. bin/git-locks, lib/090-claim-planning.sh, and s…

Full details: Docstring Coverage

Explanation

Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 4 files. (5 skipped: 5 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit checks each parent’s thread
No tangled family paths are spread
Descendants guard the older claim
Renewals keep the same old name
Clean refs rest when tests are done}

_{Comment @coderabbitai help to get the list of available commands.}