Skip to content

Build a project's map in one process at a time - #11

Merged
coffeecoproject merged 1 commit into
mainfrom
fix/shared-map-build
Nov 10, 2026
Merged

coffeecoproject merged 1 commit into
mainfrom
fix/shared-map-build

Conversation

@coffeecoproject

Copy link
Copy Markdown
Owner

Summary

Each MCP server built a project's map on its own. Sessions that open the same repository at once, as #10 saw with two tsc processes on one repository, ran the same analysis side by side, each with its own memory.

A map build now takes an exclusive transaction on build.lock, beside the project's map in the cache. A process that finds the lock held waits. Once it has the lock, it checks again: if the other process built the same version, it uses that one. Otherwise it builds, replaying from what the other one built.

  • Only builds wait. A capture whose version already exists takes no lock, so queries of a map that is already built do not wait for another process's build.
  • The system releases the lock when its process stops, however it stops, so nothing goes stale and there is no heartbeat or expiry.
  • The map's schema is unchanged. Older versions of LayerMap that share the cache still open it. They do not take the lock and build as before.
  • Correctness does not depend on the lock. A version's id is a digest of its files, installed packages and analyzer, so a version found after waiting is the one this process would have built. Without the lock, the worst case is the duplicate build of before.

Refs #10. This does not close the issue: the build still starts when the client connects, and tsc's memory on that repository is not addressed.

Known cost

A build has no time limit. While a process holds the lock, for example one stopped with Ctrl-Z, other sessions of the same repository cannot build the map until it resumes or exits. Their tool calls still return "still building" after 40 seconds instead of hanging. If a build hangs because of the repository's contents, another session building on its own would most likely hang too.

Testing

  • test/store.test.ts, 2 new tests:
    • Two sessions refreshing at once start the TypeScript worker as many times as one session alone.
    • While another process holds the lock, an unchanged refresh returns. A refresh that needs a build starts no analysis, and one that is cancelled while waiting rejects. Once the holder is killed, the build completes.
  • tsc and biome pass. 7 related test files (36 tests) pass locally; the full suite was not run locally.
  • Mutation checks: without the lock, both new tests fail (6 worker starts instead of 2). Without the check after taking the lock, the first one fails. A wait that ignores cancellation hangs the test run instead of failing it, since closing a map waits for its build.
  • Real test with packed packages, two layermap mcp processes started on a 3,312-file TypeScript monorepo with 220 tsconfigs and its node_modules, from a fresh cache each time:
Scenario 0.1.36 This branch
Two servers at once both analyze, 2 tsc, 4.4 GB peak, both ready at 48 s one analyzes, 1 tsc, 1.9 GB peak, both ready at 40.6 s
Holder killed with SIGKILL mid-build – the other starts building 1 s later and is ready 37 s after that; all 12 of the killed server's processes gone within 10 s
Holder stopped with SIGSTOP for 100 s – the other waits without analyzing, and its calls return "still building"; both ready 12 s after SIGCONT
0.1.36 and this branch at once – both build, no errors
Query of a built map while another process holds the lock – answered in 4.5 s, no analysis

Not run on Windows, apart from CI, and not tried under the Codex desktop app.

🤖 Generated with Claude Code

Each MCP server analyzed a project on its own, so sessions that opened the
same repository at once ran the same analysis side by side. A map build now
takes an exclusive transaction on build.lock beside the map; a process that
finds it held waits, then finds the version built there, or builds from it.
The system releases the lock when its process stops, however it stops. A
capture whose version already exists takes no lock, so queries do not wait.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coffeecoproject
coffeecoproject merged commit 1f89dfd into main Nov 10, 2026
3 checks passed
@coffeecoproject
coffeecoproject deleted the fix/shared-map-build branch November 10, 2026 06:36
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