Classify checked ref conflicts from observed posture

[flyingrobots]

Normalizes failed checked ref updates, atomic anchors, and checked deletes from structured post-failure ref posture instead of human-readable Git diagnostics. Operational failures remain unchanged when the attempted precondition still holds.

Validation:

• pnpm run lint
• pnpm test — 2,103 passed, 2 skipped
• GIT_STUNTS_DOCKER=1 pnpm vitest run test/integration/cache-set.test.js --no-file-parallelism — 15 passed
• Docker Node repeat — 15 passed

Refs #111

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8c4b9758-27b0-4aef-963c-d3832ec9d4b7

📥 Commits

Reviewing files that changed from the base of the PR and between e802269 and 44c279b.

📒 Files selected for processing (7)

• CHANGELOG.md
• docs/design/0057-deterministic-ref-conflict-posture/deterministic-ref-conflict-posture.md
• docs/design/README.md
• src/infrastructure/adapters/GitRefAdapter.js
• src/ports/GitRefPort.js
• test/integration/cache-set.test.js
• test/unit/infrastructure/adapters/GitRefAdapter.test.js

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (2)

docs/design/**

📄 CodeRabbit inference engine (AGENTS.md)

Use docs/design/ directory for durable design contracts and proof plans

Files:

• docs/design/README.md
• docs/design/0057-deterministic-ref-conflict-posture/deterministic-ref-conflict-posture.md

CHANGELOG.md

📄 CodeRabbit inference engine (AGENTS.md)

Use CHANGELOG.md to record the historical truth of merged behavior

Files:

• CHANGELOG.md

🧠 Learnings (3)

📚 Learning: 2026-03-30T19:53:48.000Z

Learnt from: flyingrobots
Repo: git-stunts/git-cas PR: 29
File: docs/design/TR-010-planning-index-consistency-review.md:121-131
Timestamp: 2026-03-30T19:53:48.000Z
Learning: In this repo, CHANGELOG.md entries should be user-facing and descriptive (bullet points) rather than cycle-ID headings (e.g., use a phrase like “Planning-index consistency review” instead of a “TR-010 — …” heading). When searching the changelog, don’t rely on grepping for cycle IDs (e.g., “TR-010”) because it may cause false negatives; search for the descriptive keywords/phrases from the bullet entries instead.

Applied to files:

• CHANGELOG.md

📚 Learning: 2026-07-13T17:00:46.222Z

Learnt from: flyingrobots
Repo: git-stunts/git-cas PR: 65
File: src/domain/helpers/isCanonicalCollectionKey.js:21-35
Timestamp: 2026-07-13T17:00:46.222Z
Learning: In git-stunts/git-cas, the codebase is intended to run on multiple JavaScript runtimes (Node, Bun, and Deno), not just Node. During code review, don’t suggest replacing existing portable helper logic with newer Node-only built-ins (e.g., Node 20+ APIs like `String.prototype.isWellFormed()`) unless the change preserves Bun/Deno compatibility (via portable/polyfill implementations or safe runtime gating). If a file includes manual implementations (such as `src/domain/helpers/isCanonicalCollectionKey.js`), treat them as intentional to avoid requiring a higher host built-in baseline.

Applied to files:

• src/ports/GitRefPort.js
• src/infrastructure/adapters/GitRefAdapter.js

📚 Learning: 2026-02-28T19:21:13.982Z

Learnt from: flyingrobots
Repo: git-stunts/git-cas PR: 15
File: test/unit/domain/services/CasService.envelope.test.js:326-330
Timestamp: 2026-02-28T19:21:13.982Z
Learning: In fuzz tests for cryptographic operations, use a seeded PRNG (e.g., xorshift32) for control-flow variables such as plaintext size selection and recipient index selection to ensure reproducibility. Continue to use randomBytes() for cryptographic keys and nonces to preserve realistic randomness and avoid security anti-patterns. This guideline applies to test files that perform fuzz testing of crypto logic; implement a consistent seed setup (e.g., fixed seed in test initialization) and document the rationale to enable deterministic replays across runs.

Applied to files:

• test/integration/cache-set.test.js
• test/unit/infrastructure/adapters/GitRefAdapter.test.js

🪛 LanguageTool

docs/design/0057-deterministic-ref-conflict-posture/deterministic-ref-conflict-posture.md

[style] ~271-~271: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ection and remove diagnostic parsing. - Add or revise the real-Git race witness. - ...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🔇 Additional comments (7)

docs/design/0057-deterministic-ref-conflict-posture/deterministic-ref-conflict-posture.md (1)

1-340: LGTM!

docs/design/README.md (1)

14-14: LGTM!

CHANGELOG.md (1)

19-23: LGTM!

src/infrastructure/adapters/GitRefAdapter.js (1)

4-4: LGTM!

Also applies to: 139-154, 184-192, 218-227, 280-290, 465-476, 503-511

src/ports/GitRefPort.js (1)

57-58: LGTM!

Also applies to: 71-72, 84-85

test/unit/infrastructure/adapters/GitRefAdapter.test.js (1)

18-43: LGTM!

Also applies to: 194-258, 340-398, 401-455

test/integration/cache-set.test.js (1)

97-126: LGTM!

Also applies to: 497-516

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • Improved checked ref updates, anchors, and deletes to reliably detect concurrent changes using the ref’s observed state.
  • Preserved original operational errors when the expected ref state remains valid.
  • Ensured conflicts are reported consistently, even when Git provides no diagnostic details.
  • Improved handling of symbolic, missing, and replaced refs during failed operations.

• Documentation

  • Documented ref conflict behavior and updated the unreleased changelog.

Walkthrough

Checked Git ref updates, anchors, and deletes now classify concurrency conflicts from structured post-failure ref posture rather than diagnostic text. The adapter, port documentation, design records, changelog, and diagnostic-free unit/integration tests were updated.

Changes

Deterministic ref conflict posture

Layer / File(s)	Summary
Posture contract and release definition docs/design/..., docs/design/README.md, CHANGELOG.md	Defines structured posture semantics for checked mutations, preserved operational errors, validation criteria, and release documentation.
Adapter posture inspection and classification src/infrastructure/adapters/GitRefAdapter.js, src/ports/GitRefPort.js	Inspects symbolic and direct ref state after failed mutations, normalizes contradicted preconditions, and rethrows failures when expectations remain satisfied.
Diagnostic-free mutation validation test/unit/infrastructure/adapters/GitRefAdapter.test.js, test/integration/cache-set.test.js	Covers update, anchor, and delete posture conflicts, preserved errors, structured metadata, and a dangling symbolic-ref race.
Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related issues

• git-stunts/git-cas#111 — Directly covers posture-based conflict normalization for checked update, anchor, and delete races.

Suggested reviewers: git-stunts

Sequence Diagram(s)

sequenceDiagram
  participant GitRefAdapter
  participant GitPlumbing
  participant RefPostureInspection
  GitRefAdapter->>GitPlumbing: execute checked mutation
  GitPlumbing-->>GitRefAdapter: failure
  GitRefAdapter->>RefPostureInspection: inspect ref posture
  RefPostureInspection-->>GitRefAdapter: oid and symref state
  GitRefAdapter-->>GitRefAdapter: return conflict or rethrow original error

Loading

Poem

A bunny checks the refs at night,
Reads every symbol, OID, and byte.
No stderr clues to lead astray,
Conflicts bloom from state today.
Hop, hop—clean errors stay!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	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 summarizes the main change: classifying checked ref conflicts from observed posture.
Description check	✅ Passed	It covers the issue and validation, but the template's Design/Proof and Release Impact sections are missing.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

---

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

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