[HugoXK]

Fixes #2476

Owner: Dev-2
Reviewer: Birfy
Written-by: FlyBot Dev-2
Claim-Id: dc3ee32e1d794f47ab74e82545a6de86
Risk tier: T2 — core/src/host/store.js is a T2 path; the other files are a test, one docs sentence and the two generated carriers the store's change drags with it.

Follow-up to #2471: same class — the store replaced the link at state.json and said nothing — different shape, because lstat().isSymbolicLink() never covers a hard link.

What the base already did, and what this adds

#2471 shipped in the base (2eca1c32): a save never writes through a link at the team file's own name — it writes the temp name and renames it over state.json, so the file the link pointed at keeps every byte and its last write time — and the store counts that save, so a window says one sentence once. The count only moved when lstat(name).isSymbolicLink() was true.

A hard link takes exactly the same path and is replaced just as silently: the state name gets a new inode, the other name keeps every byte, its mode and its mtime, and nobody is told, because isSymbolicLink() is false for a hard link. That is the gap this PR closes. The sentence #2471 shipped ("the file the link pointed at was not changed") stays true for this shape, so the wording is not touched here: a more precise line ("the other name") would touch core/client/i18n.js and the client bundle, and the bundle is a single lane currently held by #2474 — deferred on purpose, recorded here so it is not lost.

The rule is not new, only the count disagreed with it: plainLeaf in real-dir.js:38 — the guard a save's temp name is checked against — is isFile() && !isSymbolicLink() && nlink === 1, journal.js refuses any leaf whose nlink !== 1, and diagnostics.js:266 already describes a nlink > 1 state.json as a link.

The change

file	lines	what
core/src/host/store.js	+6/−2	isLink() returns info.isSymbolicLink() || (info.isFile() && info.nlink > 1); the comment beside it names the rule. tempWritable, the temp name, the lstat that precedes the rename and the rename itself are unchanged
core/test/state-link-hardlink.test.js (new)	+134	the counted save with the other name's inode, link count, size, mode and mtime pinned; the second save that must not move the count; the announcement through the real announceStateLink (once, and not again for the same answer); two guards — a plain file saved twice stays at 0, the symbolic link still counts 1
docs/subsystems/core-host.md	+1/−1	the same paragraph now says a hard link counts by nlink > 1 (the plainLeaf rule) and that a file of this host's own (nlink === 1) never does
patches/ds-bot/0002-flybot-api-host.patch	+7/−3	generated: the carrier holds core/src/host/store.js, so the store's hunk segment is re-emitted whole
patches/ds-bot/files/test/state-link-hardlink.test.js (new)	+134	generated: files/ stores a new file whole, so this is a byte-for-byte mirror of the test

Red first

On a clean checkout of base 2eca1c3222ea3b58b5feaa617868af03d9e27ac4 with the new test file in place and store.js untouched (core/):

node --import ./test/harness-resolve.mjs --test test/state-link-hardlink.test.js
not ok 1 - a save over a hard-linked state.json is counted, and the window says it once
  ---
  duration_ms: 21.23222
  type: 'testCodeFailure'
  location: '…/core/test/state-link-hardlink.test.js:54:1'
  error: |-
    the save that replaced a hard link is counted

    0 !== 1

  code: 'ERR_ASSERTION'
# tests 3 / # pass 2 / # fail 1

The two guards beside it are green on the same base — a plain file saved twice stays at 0, and the symbolic-link case still counts 1 — so the red is exactly the hard link. With the fix in place all three are green, and the case also pins what the save must leave behind: the other name keeps the very inode it had, one link fewer, with its size, mode and mtime unchanged, while the state name points at a new inode; a second save over the regular file that followed does not move the count again.

Why this predicate, and what it cannot break

• isLink() is info.isSymbolicLink() || (info.isFile() && info.nlink > 1). Not fileKind(): that predicate folds a FIFO, a socket and a device node into "not a plain file", and none of them belongs in this count.
• A plain single-name file has nlink === 1 by construction, so it is never counted; isFile() keeps directories out, whose nlink is already ≥ 2 by their own . and .. entries.
• A FIFO at state.json carries nlink === 1, so it is not counted: a save renames a regular file over it, silently, with no error and no notice. No shared bytes are lost (nothing else names that inode), and it is out of scope here — a separate shape, not this gap.
• Nothing on the refuse side changed (Security's read of the tree): the byte entry points are the temp name (real-dir.js:65's plainLeaf, which demands isFile && !isSymbolicLink && nlink === 1) and the journal (journal.js:263, :351, :375, each refusing a leaf whose nlink !== 1); rename only swaps the name and never opens the file, and the lock file is created with flag: 'wx' (exclusive). grep -rn "isLink(" over the tree finds one call site — store.js:986 on this branch, store.js:982 on the base — and it feeds linkReplaced and nothing else, while writable() / tempWritable never call it, so no refusal anywhere changed shape.

Generated files

generate re-cut the carrier and wrote the mirror; the total diff carries 5 paths:

• patches/ds-bot/0002-flybot-api-host.patch +7/−3: one hunk inside the store.js section — the enclosing hunk is re-emitted as a whole segment, so its header counts and the comment lines churn while the patch still applies to ds-bot/ in order.
• patches/ds-bot/files/test/state-link-hardlink.test.js (new): the whole-file mirror.
• No other patch moves, and core/client.js does not move: nothing under core/src/client/ changed.

Both checks pass at the tip — 10 patches apply cleanly in order, core/ equals ds-bot/ + patches/ds-bot/ — and canonical says patches/ds-bot/ is what generate writes (generate is a no-op); a second generate after that leaves git status --porcelain empty.

Verification at the tip

Tip SHA 8ed595625e8c34cfa8e266654ff9d858dc6e3abd (tree d1e774e5ca02cdb001f003318ce8f357986d9bb5, base 2eca1c3222ea3b58b5feaa617868af03d9e27ac4, 5 files +282/−6).

Ran on a clean tree (git status --porcelain empty) at that tree:

node scripts/ds-bot-patches.mjs generate
node scripts/ds-bot-patches.mjs check
node scripts/ds-bot-patches.mjs canonical
TZ=UTC ARCH_DOCS_BASE=2eca1c3222ea3b58b5feaa617868af03d9e27ac4 npm run verify
node scripts/ds-bot-patches.mjs generate    # second run: `git status --porcelain` empty after it

verify exit 0, every suite 0 failures:

• core 2893 pass; plugins/social 577; plugins/tree 137; plugins/timeline 141; plugins/workflow 427; .github/scripts + policy 671; interop 37; live-e2e 26 — 4909 tests, 0 fail.
• arch-docs: OK (5 changed file(s)) — the one docs sentence keeps the rule where the reader of the store finds it.
• 10 patches apply cleanly in order; core/ equals ds-bot/ + patches/ds-bot/; patches/ds-bot/ is what generate writes (generate is a no-op).
• client.js is the build of src/client ok (nothing in src/client/ moved).
• lint 0 errors (core 78 warnings, plugins 36/9/2/16, interop 1 pre-existing at dev/interop/isolation/probe.mjs:130, live-e2e 0).

Not run: the smoke test (core/dev/bench.sh smoke …) — it needs a free bench port and a DSH checkout on this box, and this change only moves a counter inside save(); and risk-gate, which judges a PR number and re-runs at merge time.

Checkpoint

{
  "pr": 2478,
  "claim": "Dev-2",
  "issue": 2476,
  "summary": "A save writes the temp name and renames it over state.json, so a link at that name is replaced, never written through, and the other name keeps every byte, its mode and its mtime; #2471 counted that save so a window says one sentence. The count only fired for a symbolic link, so a hard link was replaced just as silently. isLink() now also answers true for a regular file whose nlink is above 1, the rule plainLeaf and the journal already hold, and a file of this host's own is never counted. A window hears about a hard link once, and a later save over the regular file that followed stays quiet.",
  "files": [
    "core/src/host/store.js",
    "core/test/state-link-hardlink.test.js",
    "docs/subsystems/core-host.md",
    "patches/ds-bot/0002-flybot-api-host.patch",
    "patches/ds-bot/files/test/state-link-hardlink.test.js"
  ],
  "checks": {
    "ran": "TZ=UTC ARCH_DOCS_BASE=2eca1c3222ea3b58b5feaa617868af03d9e27ac4 npm run verify; node scripts/ds-bot-patches.mjs generate/check/canonical",
    "result": "green",
    "at": "8ed595625e8c34cfa8e266654ff9d858dc6e3abd"
  },
  "next": "none — ready for review"
}

[Birfy]

Verdict: PASS at 8ed5956
Written-by: Reviewer
Attestation: 8ed5956 role=Reviewer

Ran at this tip:

$ node --import ./test/harness-resolve.mjs --test test/state-link-hardlink.test.js
# tests 3  # pass 3  # fail 0
$ cp /tmp/store.base.js src/host/store.js  (red-first: core/src/host/store.js swapped back to its 2eca1c32 blob, same command, then restored byte-identical)
# tests 3  # pass 2  # fail 1

Tarball of 8ed595625e8c34cfa8e266654ff9d858dc6e3abd (5 files, +282/−6), test run from core/ only, not the suite.

• The change. core/src/host/store.js +6/−2: isLink() is now info.isSymbolicLink() || (info.isFile() && info.nlink > 1), with the plainLeaf rule named in the comment beside it. The temp name, the lstat before the rename and the rename are untouched, so nothing on the refuse side moves: plainLeaf (real-dir.js) still demands isFile && !isSymbolicLink && nlink === 1, journal.js still refuses any leaf with nlink !== 1, and grep -rn "isLink(" finds one call site feeding only linkReplaced.
• Red first, once. With store.js put back to the base blob 2eca1c32 and the new test in place, case 1 fails exactly as the body claims (the save that replaced a hard link is counted 0 !== 1) while the two guards stay green — the two guards isolate the hard link itself. After the swap back the same command is 3/3 green.
• What the test pins (core/test/state-link-hardlink.test.js): the state name gets a new inode with nlink === 1, the other name keeps the inode it had with one link fewer and its bytes/size/mode/mtime unchanged, the count moves once and not again for the regular file that follows, the notice is announced once through the real announceStateLink, and a plain file saved twice stays at 0 while the symbolic link still counts 1.
• Generated carriers. patches/ds-bot/0002-flybot-api-host.patch (+7/−3) is a whole-hunk re-emit of the store.js section and patches/ds-bot/files/test/state-link-hardlink.test.js is the byte mirror of the new test; core/client.js does not move, which matches "nothing under core/src/client/ changed". tests-ok is green at the tip, so ds-bot-patches check and build-client.mjs --check passed on exactly these bytes.
• Docs. docs/subsystems/core-host.md +1/−1 updates the paragraph that already owned this sentence; the wording of the notice itself is deliberately unchanged (the bundle lane).
• CI at this tip. tests-ok, plugins (tree|social|timeline|workflow), package, merge-gate, reviewed tip, risk tier, judge, policy-sign, agent-audience all success at 8ed5956. The only red is enqueue-guard, and its own text says why: no Verifier report names the tip 8ed595625e8c — that is this comment's absence, not a defect; it re-runs on the comment event.
• Fork, so exempt from the Fixes #N / agent-pr / Owner: / Reviewer: / checkpoint body checks (head repo HugoXK/FlyBot); body still carries them, and Fixes #2476 is there.

Not run: the full npm run verify suite (only the one changed test file), the smoke test (store.js is host code, so tests-ok's own test job is the standing evidence), and no client bundle check beyond the green tests-ok.

[HugoXK]

Security Self-test: PASS at 8ed5956 (base 2eca1c32, 5 files, +282/−6)

Dual-path tip verification: ls-remote on dev/2-hardlink-save-notice = 8ed59562…, REST agrees (Date 00:59:40Z).

Scope check: the predicate core/src/host/store.js:941 info.isSymbolicLink() || (info.isFile() && info.nlink > 1) is a strict superset of base for regular files: it adds counting only for "a regular file carrying a second name" and introduces no new miss. isLink( still has exactly one call site in the tree, at store.js, feeding only the notice counter (writable()/tempWritable do not call it); tempWritable, the journal, the lock and the rename order are untouched. core/client.js and 0008 are not among the 5 changed files.

FIFO note: the predicate does not include FIFOs, so behaviour there equals base (silent rename, no shared bytes lost) — the PR body lists it as explicitly out of scope. That was my suggestion, never a must-fix; my conclusion is unchanged.

Assertions match what I asked for: another name's st_ino unchanged, nlink exactly −1 (2→1), state.json on a different inode, size|mtimeMs|mode unchanged, count exactly +1, a second save does not increment, save() resolves without throwing.

Ran:

• node --import ./test/harness-resolve.mjs --test test/state-link-hardlink.test.js test/state-link-notice.test.js test/state-link-answer.test.js test/state-journal.test.js test/legacy-state.test.js → 45/45 pass; plus store.test.js 32/32.
• Red-first on base ac020d1d: same case → 3 tests / 2 pass / 1 fail, 0 !== 1 (the counted line).
• Patch carrier: node scripts/ds-bot-patches.mjs check → 10 patches apply in order, core/ equals ds-bot/ + patches; canonical → generate is a no-op.

Advisory only — T2 merge gate is the repository reviewer's Verdict PASS naming this tip.

[HugoXK]

Test Self-test: PASS at 8ed5956 (tree d1e774e5ca02cdb001f003318ce8f357986d9bb5, base 2eca1c32)

Dual-path: git ls-remote → 8ed59562…; REST (Date 01:06:45Z) → same sha, 5 files +282/−6; pulls/2478/files (Date 01:02:54Z) → store.js +6/−2, test +134, docs, 0002 carrier, mirror — no client.js, no 0008, matching the body.

TZ=UTC ARCH_DOCS_BASE=2eca1c32… npm run verify → exit 0, 4909 tests / 0 fail (core 2893, workflow 427); arch-docs: OK (5); patches clean + equivalence + no-op; risk recomputed T2.

Red-first on 2eca1c32 (only the new test): 3 tests / 2 pass / 1 fail — the save that replaced a hard link is counted 0 !== 1.

Independent probe against the real store and a real filesystem: the predicate is exactly isSymbolicLink() || (isFile() && nlink > 1); isLink( has a single call site (store.js:986) and tempWritable / temp names / rename are untouched. Whole hard-link chain: state lands on a new inode with nlink 1, the old name keeps its inode, size, mtime, mode and bytes with nlink 2→1, no temp residue, {gen,count} +1; a second save stays at 1; a plain file counts 0; a symlink still counts 1 and its target is untouched; second name already gone (nlink 1) → 0; FIFO replaced but counted 0 (same shape as base); directory → EISDIR, write refused, directory still there; {gen,count} announced once, and once more when the gen changes with the same count. No must-fix.