ForgeClaw: The Great Sharding
A historical account of project-based sharding, repeated-routing cache behavior, and why the old performance claim is no longer presented as a benchmark.
Correction — September 5, 2026: The earlier performance percentage remains withdrawn because a reproducible method was not retained publicly. Remaining implementation details are now attributed to the period account, and unsupported named commentary has been removed. The historical behavior has not been independently reproduced by this review. See the historical review note.
April 2026 Note
This article remains online as a historical engineering record. ForgeClaw has since been retired from the public WebForge catalog. The current public policy is documented in Retiring the Fork.
Historical Case Study
- Research question or engineering problem
- What problem was project-based sharding intended to solve in the retired ForgeClaw dispatcher?
- Principal finding
- The period account reports less repeated routing and coordination friction after separating project state; a reproducible latency benchmark is not retained publicly.
- Evidence type
- Historical engineering narrative with incomplete measurement evidence.
- Method summary
- Retain the architecture change and explicitly remove numeric and absolute performance claims that lack a public method packet.
- Scope
- Retired ForgeClaw routing and storage behavior in February 2026.
- Limitations
- Cold and cached timings, sample size, cache-hit rules, hardware, revision, and commands were not retained publicly.
- No current-system performance conclusion can be drawn.
- Public source or reproduction note
- No reproducible benchmark retained; read current fork doctrine
- Published
- 2026-02-10
- Last verified
- 2026-08-27
- Status
- Historical record
Optimizing the Historical ForgeClaw Dispatcher
The period account describes the ForgeClaw dispatcher moving away from one shared state path during the v3 rebuild. It reports that repeated project work spent less time in classification after caching. The public archive does not retain the timings, run count, cache-hit rules, hardware, revision or command needed to turn that report into a reproducible performance result.
>_1. Classification Caching
Earlier routing was described as performing classification before choosing a specialist. The historical narrative identifies that step as a source of delay during repeated work; this review did not reproduce its timing.
The account attributes less repeated-routing work to a project-level cache with query normalization. In that description, a matching cached result avoids another classification step. The report remains a historical observation, not a retained benchmark.
Reported behavior and evidence limits
- Cold path: the account identifies classification as the expensive stage in operator use; its timing was not retained.
- Cached path: according to the account, similar repeated work avoided that classification stage when the cache matched.
- Evidence limit: no public timing table or reproducible method survived, so the original percentage has been withdrawn.
>_2. Project-Based Sharding
The period account describes interaction records sharing one file and proposes project-based partitioning to make them easier to manage. It attributes coordination pressure to that shared path, but no retained trace in this review establishes a serial-I/O bottleneck or isolates its cause.
The Described Shard Topology
The described arrangement gives each project separate namespaces for memory, interaction logs and knowledge records. The original account reports less cross-project contention. That report does not establish complete isolation, linear scaling or the behavior of the current system.
>_3. Persistent I/O Optimization
The account also describes a heartbeat loop that frequently wrote transient status to disk. Its exact flush cadence and durability guarantees are not established by the reviewed sources.
The proposed distinction is between short-lived heartbeat state and routing changes intended to persist. The account attributes fewer unnecessary writes to that separation, but the archive does not retain device-level I/O or longevity measurements.
>_Future Roadmap: Unix Domain Sockets
The historical roadmap proposed replacing file-based status polling with Unix domain sockets. The intent was to remove the fixed polling interval from the update path, but this page does not claim that the design was completed or that jitter was measured away. The current system no longer uses this record as deployment doctrine.
Editorial takeaway: Separating project state and distinguishing transient status from durable records gives a reader concrete architectural choices to examine. The old performance effect remains unquantified.