Filesystem provider: close the cross-process window of conditional writes with a per-user OS lock (deferred)
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
Research direction
This work is explicitly deferred until needed and depends on #139 and #140. Start by reading the filesystem provider’s conditional-write path in src/OKF4net and the concurrent test in #131; then design a multi-process test for concurrent read-modify-write operations. Done means both processes’ updates repeatedly land, the lock stays outside the bundle, and killing a process leaves no blocking lock.
Written by the indexing model from the issue text.
Description
Area
The filesystem bundle provider's conditional write (#139 / #140) — src/OKF4net (BundleConceptWriter write path once it sits on the provider contract).
Why it matters
The provider contract adopts optimistic per-object concurrency (decided 2026-10-07, recorded on #139): a read returns content plus a version token (on the filesystem: SHA-256 of the content), and a write supplies the expected version; the provider replaces the object atomically only if the current version still matches, else it throws a write-conflict exception.
On the filesystem this is implemented as write a temporary file → re-check the version → File.Replace. Between the re-check and the replace, another process can still write the same file; within one process the existing per-bundle lock serializes it. The residual window is short but real: e.g. okf verify in a terminal and okf-mcp writing the same concept can still lose an update.
Decision (2026-10-07): accept and document this window for now (option a). This issue keeps the agreed fix for when it becomes necessary.
Proposal (option b, deferred)
An OS-level lock held only around check-and-replace:
- a lock file opened with
FileShare.None, in a per-user local cache directory (not in the bundle), named after a hash of the bundle's canonical root; - released by the OS if the process dies — no stale-lock recovery, unlike "the file exists, so it is locked" schemes;
- nothing written into the bundle, so no interaction with git, read-only bundles, or the reparse-point guards.
Known limits (to document when implemented)
- Per-user directory: coordinates processes of the same user (CLI + MCP + agent host), not two OS accounts writing the same directory.
- On Unix,
FileShare.Noneis an advisory lock: it coordinates cooperating .NET processes, not arbitrary editors.
Rejected alternative: a lock file inside the bundle (.okf.lock) — coordinates every account, but pollutes the bundle and adds a file the link guards must themselves protect, i.e. new attack surface inside the space being protected.
Acceptance (when picked up)
- Two processes running concurrent read-modify-write operations on one concept (e.g.
RecordVerifications) both land, repeatedly — a multi-process variant of #131's concurrent test. - Lock file never created inside the bundle root; killing a process mid-operation leaves no lock that blocks the next writer.
Depends on
#139, #140
Effort
S/M
🤖 Generated with Claude Code
- Dominant language
- C#
- Stars
- 4
- Forks
- 1
- Avg merge
- 1d 4h
- Merged PRs (30d)
- 32
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from jchable/okf4net
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
.NET bug
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
test
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
documentation good first issue
Difficulty 1/5 1-3 hours Newbie friendliness 90/100
Maintainers usually reply within 1 day
-
documentation good first issue
Difficulty 1/5 Under an hour Newbie friendliness 82/100
Maintainers usually reply within 1 day
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
area/backend type/bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
umbraco/Umbraco-CMS#24668 · 1 comment ·
Maintainers usually reply within 1 day
-
Pri3
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
MicrosoftDocs/windows-dev-docs#6205 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
area-ai untriaged
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
dotnet/extensions#7956 ·
Maintainers usually reply within 1 day