Filesystem provider: close the cross-process window of conditional writes with a per-user OS lock (deferred)

Open
#178 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
csharp
Domain
backend, database

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

.NET enhancement

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.None is 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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from jchable/okf4net

All issues in jchable/okf4net

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.