Skip to content

feat: concurrency-safe append claim and run commands - #45

Merged
anusbutt merged 2 commits into
mainfrom
008-concurrent-appends
Aug 23, 2026
Merged

anusbutt merged 2 commits into
mainfrom
008-concurrent-appends

Conversation

@anusbutt

Copy link
Copy Markdown
Owner

Fixes a read-modify-write race on graph/claims.json and graph/runs.json where two concurrent agents silently dropped one writer's record.

What changed

  • Shared helper (src/lib/optimistic-write.ts): mutateJsonArrayFile / acquireLock / writeJsonArrayUnderLock — exclusive graph-file lock (atomic hard-link) + compare-before-rename + bounded retry (default 5).
  • CLI commands (src/commands/append.ts, wired in src/cli.ts): graphkeeper append claim and graphkeeper append run. append claim acquires claims.json then runs.json locks up front and writes both in one critical section, so a run closed mid-flight cannot orphan a claim.
  • Diagnostics: GK400 (write did not stabilize / lock timeout), GK401 (invalid input).
  • SKILL.md now prescribes the append commands in place of direct JSON editing.

Verification

  • 50-trial staggered stress (400 concurrent appends): 0 lost records, 0 failures.
  • Full functional suite: 357 pass, 0 fail. typecheck, validator:check, package smoke clean.
  • Targeted mid-flight-close test confirms no orphaned claim (both files asserted).

Notes

  • specs/, .specify/, PROGRESS.md are git-ignored local SDD artifacts (not in the PR).
  • Does not touch entities.json write path or per-record storage (out of scope).

Adds graphkeeper append claim/run that write through a shared optimistic-write
helper (exclusive graph-file lock + compare-before-rename with bounded retry),
closing a read-modify-write race that silently dropped concurrent writers' records.

- add src/lib/optimistic-write.ts (mutateJsonArrayFile, acquireLock,
  writeJsonArrayUnderLock)
- add src/commands/append.ts and wire append claim/run into the CLI
- append claim acquires claims.json then runs.json locks up front and writes both
  in one critical section, so a run closed mid-flight cannot orphan a claim
- add GK400 (write did not stabilize/lock timeout) and GK401 (invalid input)
- SKILL.md prescribes the append commands instead of direct JSON editing
- tests: helper race, command race, mid-flight close, and pre-staged closed-run
@anusbutt
anusbutt merged commit 632a563 into main Aug 23, 2026
6 checks passed
@anusbutt
anusbutt deleted the 008-concurrent-appends branch August 23, 2026 18:38
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.

1 participant