release: prepare git-cas v6.4.0

[flyingrobots]

Linked Issue

• Refs Scoped staging workspaces for multi-object promotion #75
• Refs RootSet retry misses structured update-ref lock races #77
• Neither issue closes until the tag workflow and publication evidence are complete.

Summary

• prepare the reviewed scoped-staging-workspace implementation for v6.4.0;
• normalize structured Git lock races for this RootSet's exact update-ref --no-deref command so the existing bounded retry policy can run;
• publish v6.4.0 release notes, upgrade guidance, lifecycle assertions, roadmap truth, and an explicitly unpublished candidate witness.

Root Cause

The first release-candidate verifier exposed a nondeterministic ExpiringSet writer failure. Git can report a compare-and-swap lock race as structured GIT_REPOSITORY_LOCKED evidence whose text lacks the older "but expected" or "reference already exists" markers. RootSetPersistence therefore wrapped the race as ROOT_SET_REF_UPDATE_FAILED, bypassing RootSet's bounded conflict retry. The correction recognizes the structured error only when its argument vector proves an exact managed update-ref --no-deref operation; lock failures for other refs remain terminal.

Design / Proof

• Design doc: docs/design/0049-scoped-staging-workspaces/scoped-staging-workspaces.md
• Feature witness: docs/design/0049-scoped-staging-workspaces/witness/verification.md
• Release candidate witness: docs/design/0049-scoped-staging-workspaces/witness/release-candidate.md

Validation

pnpm run release:verify
  14/14 gates passed
  6,538 tests observed
  Node unit: 1,993
  Bun unit: 1,992
  Deno unit: 1,983
  Node/Bun/Deno integration: 190 each
  npm pack dry-run: PASS
  JSR publish dry-run: PASS

pnpm exec vitest run test/unit/domain/services/RootSetPersistence.test.js
  16/16 passed

20 repeated real-Git ExpiringSet concurrency runs
  20/20 passed

npm pack --dry-run --json
  247 files
  763,925 packed bytes
  2,129,717 unpacked bytes

Graft found no removed JavaScript exports. Its only semver warning is the additive package.json files array entry that packages docs/releases/v6.4.0.md; this does not change an executable API signature.

Release Impact

• Changelog updated, if release behavior changed.
• Public docs updated, if user-facing behavior changed.
• Issue labels/milestone reflect final disposition.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

v6.4.0 release and RootSet conflict handling

Layer / File(s)	Summary
Structured RootSet conflict classification src/domain/services/RootSetPersistence.js, test/unit/domain/services/RootSetPersistence.test.js, CHANGELOG.md	Structured locks for the managed RootSet ref normalize to ROOT_SET_CONFLICT, while locks for other refs remain terminal errors.
Version metadata and packaged release notes jsr.json, package.json, src/package-version.js, README.md, test/unit/docs/package-docs.test.js	Version metadata and release links move to v6.4.0, and the new release notes are included in packaged-document checks.
Scoped staging workspace documentation UPGRADING.md, docs/releases/v6.4.0.md, docs/design/0049-scoped-staging-workspaces/*, test/unit/docs/release-truth.test.js	Documentation describes workspace lifecycle and paginated cleanup, with release-candidate verification details and contract assertions.
Release train and lifecycle alignment ROADMAP.md, STATUS.md, test/unit/docs/release-state.test.js	Roadmap, status, witnesses, and tests reflect the v6.4.0 candidate-to-publication lifecycle.

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

Possibly related issues

• RootSet retry misses structured update-ref lock races #77 — Adds structured GIT_REPOSITORY_LOCKED classification for the managed RootSet ref and tests bounded retry behavior.

Possibly related PRs

• git-stunts/git-cas#68 — Both PRs update release-state tests for version-specific publication and witness evidence.

Suggested reviewers: git-stunts

Poem

A rabbit hops through version six-four,
Packing fresh notes by the door.
Root locks now know where conflicts belong,
Staging workspaces march along.
“Ship when the gates are green!” sings the hare.

🚥 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
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.
Title check	✅ Passed	The title is concise and accurately summarizes the v6.4.0 release preparation.
Description check	✅ Passed	The description includes all required sections and the key release, design, validation, and impact details.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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

[flyingrobots]

@codex self-review and Code Lawyer review completed.

Severity	Count
Critical	0
High / Major	1 found and resolved
Medium	1 found and resolved
Low	0

The independent review found that the design checklist's generic review wording could be read as claiming release-PR CI/review was already complete. Commit 7e64ea0f now identifies the checked criterion as the completed implementation-PR gate; the candidate witness continues to leave release-PR CI, review, tagging, and publication pending.

CodeRabbit then required exact validation of the complete structured update-ref argument vector. Commit d1e12695 now validates all five operands, including the expected old OID or zero creation sentinel, and keeps malformed vectors terminal even when their stderr carries legacy conflict markers. The review thread is resolved with direct source and test evidence.

Runtime review confirmed the structured lock classifier requires the exact error code, command, --no-deref option, and managed ref. The negative test proves another ref remains terminal. No public runtime export or declaration changes in this PR; Graft's package.json.files warning is an additive release-note packaging entry, not a breaking API change.

Final validation: lint passed; focused RootSet tests passed 16/16; planning/lifecycle tests passed 10/10; repeated real-Git ExpiringSet concurrency runs passed 20/20; and the complete release verifier passed 14/14 with 6,538 observed tests. The final pre-push Node unit gate passed 1,993 tests.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/domain/services/RootSetPersistence.js`:
- Around line 15-21: Update isStructuredUpdateRefConflict to require the exact
update-ref argument vector: validate the expected argument count and verify the
new and expected OID operands for this operation, rejecting missing, altered, or
trailing arguments. Preserve the existing GIT_REPOSITORY_LOCKED, command,
option, and rootSetRef checks, and add negative tests covering malformed and
extra arguments.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0f8d7bc8-3748-4c3c-8d2a-74cb46036ee6

📥 Commits

Reviewing files that changed from the base of the PR and between 1ac2fc8 and 7e64ea0.

📒 Files selected for processing (17)

• CHANGELOG.md
• README.md
• ROADMAP.md
• STATUS.md
• UPGRADING.md
• docs/design/0049-scoped-staging-workspaces/scoped-staging-workspaces.md
• docs/design/0049-scoped-staging-workspaces/witness/release-candidate.md
• docs/design/0049-scoped-staging-workspaces/witness/verification.md
• docs/releases/v6.4.0.md
• jsr.json
• package.json
• src/domain/services/RootSetPersistence.js
• src/package-version.js
• test/unit/docs/package-docs.test.js
• test/unit/docs/release-state.test.js
• test/unit/docs/release-truth.test.js
• test/unit/domain/services/RootSetPersistence.test.js

📜 Review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: test-unit

🧰 Additional context used

📓 Path-based instructions (5)

docs/design/**

📄 CodeRabbit inference engine (AGENTS.md)

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

Files:

• docs/design/0049-scoped-staging-workspaces/witness/release-candidate.md
• docs/design/0049-scoped-staging-workspaces/scoped-staging-workspaces.md
• docs/design/0049-scoped-staging-workspaces/witness/verification.md

STATUS.md

📄 CodeRabbit inference engine (AGENTS.md)

Use STATUS.md as a compact snapshot of release and runtime truth

Files:

• STATUS.md

README.md

📄 CodeRabbit inference engine (AGENTS.md)

Use README.md as the public front door, core value prop, and quick start documentation

Files:

• README.md

ROADMAP.md

📄 CodeRabbit inference engine (AGENTS.md)

Use ROADMAP.md as a signpost to the GitHub release tracker

Files:

• ROADMAP.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-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/package-version.js
• src/domain/services/RootSetPersistence.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/unit/docs/release-truth.test.js
• test/unit/docs/package-docs.test.js
• test/unit/domain/services/RootSetPersistence.test.js
• test/unit/docs/release-state.test.js

📚 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

🪛 LanguageTool

docs/design/0049-scoped-staging-workspaces/witness/release-candidate.md

[style] ~76-~76: Consider removing “of” to be more concise
Context: ...Gate Publication remains blocked until all of the following are true: 1. the release PR ...

(ALL_OF_THE)

🔇 Additional comments (17)

test/unit/domain/services/RootSetPersistence.test.js (1)

45-59: LGTM!

Also applies to: 125-155

CHANGELOG.md (1)

10-10: LGTM!

Also applies to: 29-35

docs/design/0049-scoped-staging-workspaces/scoped-staging-workspaces.md (1)

529-530: LGTM!

docs/design/0049-scoped-staging-workspaces/witness/release-candidate.md (1)

1-88: LGTM!

docs/design/0049-scoped-staging-workspaces/witness/verification.md (1)

141-143: LGTM!

ROADMAP.md (1)

35-52: LGTM!

STATUS.md (1)

4-5: LGTM!

Also applies to: 21-25, 107-111

test/unit/docs/release-state.test.js (1)

6-11: LGTM!

Also applies to: 27-100, 102-116

jsr.json (1)

3-3: LGTM!

package.json (1)

3-3: LGTM!

Also applies to: 38-38

src/package-version.js (1)

1-1: LGTM!

test/unit/docs/package-docs.test.js (1)

16-16: LGTM!

Also applies to: 93-93

README.md (1)

47-47: LGTM!

Also applies to: 203-204

UPGRADING.md (1)

5-46: LGTM!

docs/releases/v6.4.0.md (2)

60-68: 🩺 Stability & Availability

Confirm the terminal nextCursor contract.

This loop stops only when cleanup.nextCursor is exactly null on Line 68. Verify that cas.workspaces.sweep() guarantees that sentinel on the final page; if it returns undefined or omits the property, the example can continue paging indefinitely or restart from the first page. Add coverage for both single-page and multi-page cleanup behavior.

---

115-120: LGTM!

test/unit/docs/release-truth.test.js (1)

203-217: LGTM!