docs: correct fs/observed concurrency-safety wording

The read tool's isConcurrencySafe rationale called the fs/observed recorder
"commutative" and said concurrent reads "converge to one observed version",
overstating the guarantee: the WeakMap record is last-writer-wins. Safety comes
from write/edit re-checking the version in their in-lock CAS (a stale
observation only forces a later edit to fail closed with FS_STALE_VERSION), as
the RFC already states. Align the read comment, the ToolDefinition JSDoc, both
READMEs, and the regenerated catalogs.
This commit is contained in:
Dudu-0223
2026-07-14 11:56:27 +08:00
parent eae8b8ce2e
commit 5ab8f2e328
7 changed files with 18 additions and 12 deletions

View File

@@ -92,10 +92,12 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
offset: { type: 'number', description: '1-based first line to return. Defaults to 1.' },
limit: { type: 'number', description: `Maximum number of lines to return. Defaults to ${caps.limit}.` },
},
// Read-only. Its one side effect is the synchronous, commutative `fs/observed`
// version recorder (a WeakMap write; see below and the fs-policy plugin), so
// concurrent same-target reads converge to one observed version. write/edit
// stay exclusive barriers and re-check versions in-lock before mutating.
// Read-only. Its one side effect is the synchronous `fs/observed` version
// recorder (a WeakMap write; see below and the fs-policy plugin): concurrent
// same-target reads race last-writer-wins on that record, which is safe because
// it is NOT the safety boundary — write/edit stay exclusive barriers and
// re-check the version in-lock, so a stale observation only makes a later edit
// fail closed with FS_STALE_VERSION.
isConcurrencySafe: () => true,
async execute(args, exec): Promise<ContentBlock[]> {
const input = parseReadArgs(args, caps.limit)