From 1aadb7fea689905e169a027f6a13101f6a4ef958 Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Tue, 6 Oct 2026 01:16:25 -0500 Subject: [PATCH 1/6] Close the slot-audit coverage gaps the review found Widening the file audit to *_SLOT/*_INDEX left three gaps behind: - the in-registry distinctness check still filtered on _POSITION, so a hand-numbered PEER_SLOT inside the registry would have skipped the collision check the audit exists to feed; - the AST walker missed an object-literal spelling ({ PEER_POSITION: 30 }); - DESIGN.md still described the audit as _POSITION-only. Also drops two comments that explained why a test exists rather than stating an invariant. Co-Authored-By: Claude Opus 5 --- replication/DESIGN.md | 2 +- .../replication/sharedStatusSlots.test.mjs | 18 +++++++++++------- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/replication/DESIGN.md b/replication/DESIGN.md index 0b383b3c9..be3e3a4bc 100644 --- a/replication/DESIGN.md +++ b/replication/DESIGN.md @@ -153,7 +153,7 @@ Per (database, remote_node) pair: a `Float64Array` over the audit store's `getUs | 31 | `RECORD_LOCK_LEVEL_POSITION` | | 32–63 | unused headroom | -The buffer is 64 `Float64` slots (512 bytes, `REPLICATION_SHARED_STATUS_SLOTS` in `sharedStatusSlots.ts`, re-exported from `knownNodes.ts`) — 0–31 are used as above (30 is the record-lock home-map digest agreement tri-state; 31 is the peer's exact advertised `recordLocks` level); 32–63 are headroom for the peer-scoped transport (harper-pro#884) and the ownership domain (harper-pro#886). **A new slot is added in `sharedStatusSlots.ts`, never hand-numbered in an owning module**: `unitTests/replication/sharedStatusSlots.test.mjs` walks the TypeScript AST of every file under `replication/` (recursively) for a `*_POSITION` variable declaration outside the registry, asserts every allocated position is distinct and in range, that the fire-counter block doesn't reach its neighbors, and that the allocator throws rather than silently exceeding capacity. Slots 0–12 are written concurrently by `replicationConnection.ts` without explicit synchronization (single-writer-per-field in practice) — **don't introduce read-modify-write patterns on those.** Slots 13–28 are the one deliberate exception; see the counter invariant below. +The buffer is 64 `Float64` slots (512 bytes, `REPLICATION_SHARED_STATUS_SLOTS` in `sharedStatusSlots.ts`, re-exported from `knownNodes.ts`) — 0–31 are used as above (30 is the record-lock home-map digest agreement tri-state; 31 is the peer's exact advertised `recordLocks` level); 32–63 are headroom for the peer-scoped transport (harper-pro#884) and the ownership domain (harper-pro#886). **A new slot is added in `sharedStatusSlots.ts`, never hand-numbered in an owning module**: `unitTests/replication/sharedStatusSlots.test.mjs` walks the TypeScript AST of every file under `replication/` (recursively) for a `*_POSITION`, `*_SLOT` or `*_INDEX` declaration outside the registry, asserts every allocated position is distinct and in range, that the fire-counter block doesn't reach its neighbors, and that the allocator throws rather than silently exceeding capacity. Slots 0–12 are written concurrently by `replicationConnection.ts` without explicit synchronization (single-writer-per-field in practice) — **don't introduce read-modify-write patterns on those.** Slots 13–28 are the one deliberate exception; see the counter invariant below. The buffer size is fixed once, at this process's build, for the process's whole lifetime — nothing in this codebase resizes an existing (database, peer) buffer while a process runs, so growing the constant is safe across a restart. A **live** resize is not available: probed against both lmdb-js and `@harperfast/rocksdb-js`, a second `getUserSharedBuffer` for an already-registered key returns the **first** buffer at its original size and ignores the larger default — no throw, no resize — so writes past that length land outside the typed array and are silently dropped. The first registration of a key within a process therefore fixes its size for that process, and growing `REPLICATION_SHARED_STATUS_SLOTS` takes effect only on restart. Every caller must pass one size per key, which is why the capacity is read from the registry inside `getReplicationSharedStatus` rather than supplied by callers (`unitTests/replication/sharedStatusSlots.test.mjs` pins that). diff --git a/unitTests/replication/sharedStatusSlots.test.mjs b/unitTests/replication/sharedStatusSlots.test.mjs index 6eec10cf8..800d4abc1 100644 --- a/unitTests/replication/sharedStatusSlots.test.mjs +++ b/unitTests/replication/sharedStatusSlots.test.mjs @@ -8,14 +8,17 @@ import { getReplicationSharedStatus } from '#src/replication/knownNodes'; const REPLICATION_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'replication'); const REGISTRY_RELATIVE_PATH = 'sharedStatusSlots.ts'; -// A slot named _SLOT or _INDEX would otherwise walk straight past an audit keyed on _POSITION alone. const SLOT_NAME_SUFFIXES = ['_POSITION', '_SLOT', '_INDEX']; function declaredPositionNames(source, fileName) { const names = []; const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS); const visit = (node) => { - const binds = ts.isVariableDeclaration(node) || ts.isBindingElement(node) || ts.isPropertyDeclaration(node); + const binds = + ts.isVariableDeclaration(node) || + ts.isBindingElement(node) || + ts.isPropertyDeclaration(node) || + ts.isPropertyAssignment(node); if (binds && ts.isIdentifier(node.name) && SLOT_NAME_SUFFIXES.some((s) => node.name.text.endsWith(s))) { names.push(node.name.text); } @@ -38,9 +41,9 @@ function fakeAuditStore() { } describe('replication shared-status slot registry', () => { - const positionEntries = Object.entries(slots).filter(([name]) => name.endsWith('_POSITION')); + const positionEntries = Object.entries(slots).filter(([name]) => SLOT_NAME_SUFFIXES.some((x) => name.endsWith(x))); - it('assigns every *_POSITION export a distinct, in-range slot, reserving the fire-counter block whole', () => { + it('assigns every slot export a distinct, in-range slot, reserving the fire-counter block whole', () => { expect(positionEntries.length).to.be.greaterThan(0); const occupied = new Map(); const blockStart = slots.FIRE_COUNTER_BASE_POSITION; @@ -88,6 +91,10 @@ describe('replication shared-status slot registry', () => { expect(declaredPositionNames('const UNRELATED_OFFSET = 40;', 'a.ts')).to.deep.equal([]); }); + it('declaredPositionNames catches an object-literal slot too', () => { + expect(declaredPositionNames('const o = { PEER_POSITION: 30 };', 'a.ts')).to.deep.equal(['PEER_POSITION']); + }); + it('never hand-numbers a slot constant outside the registry, under any of its spellings', () => { const offenders = []; for (const file of readdirSync(REPLICATION_DIR, { withFileTypes: true, recursive: true })) { @@ -108,9 +115,6 @@ describe('replication shared-status slot registry', () => { expect(getReplicationSharedStatus(auditStore, 'data', 'peer')[topSlot]).to.equal(42); }); - // Probed against lmdb-js and @harperfast/rocksdb-js: a second request for a key already - // registered returns the FIRST buffer at its original size, with no throw, so writes past that - // length are silently dropped. Every caller must therefore pass one size per key. it('getReplicationSharedStatus() always requests the registry capacity, never a caller-chosen size', () => { const sizes = []; const auditStore = { From 7ddef5bac5cb1de9e48a7905f926ae6428592c89 Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Tue, 6 Oct 2026 11:53:55 -0500 Subject: [PATCH 2/6] Catch a quoted object-literal slot key too The walker required ts.isIdentifier, so { 'PEER_POSITION': 30 } slipped past the very check the unquoted case had just closed. Accepts a string-literal property name as well. Co-Authored-By: Claude Opus 5 --- unitTests/replication/sharedStatusSlots.test.mjs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/unitTests/replication/sharedStatusSlots.test.mjs b/unitTests/replication/sharedStatusSlots.test.mjs index 800d4abc1..fbe8c0c85 100644 --- a/unitTests/replication/sharedStatusSlots.test.mjs +++ b/unitTests/replication/sharedStatusSlots.test.mjs @@ -19,7 +19,8 @@ function declaredPositionNames(source, fileName) { ts.isBindingElement(node) || ts.isPropertyDeclaration(node) || ts.isPropertyAssignment(node); - if (binds && ts.isIdentifier(node.name) && SLOT_NAME_SUFFIXES.some((s) => node.name.text.endsWith(s))) { + const named = binds && (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)); + if (named && SLOT_NAME_SUFFIXES.some((s) => node.name.text.endsWith(s))) { names.push(node.name.text); } ts.forEachChild(node, visit); @@ -91,8 +92,10 @@ describe('replication shared-status slot registry', () => { expect(declaredPositionNames('const UNRELATED_OFFSET = 40;', 'a.ts')).to.deep.equal([]); }); - it('declaredPositionNames catches an object-literal slot too', () => { + it('declaredPositionNames catches an object-literal slot, quoted or not', () => { expect(declaredPositionNames('const o = { PEER_POSITION: 30 };', 'a.ts')).to.deep.equal(['PEER_POSITION']); + expect(declaredPositionNames("const o = { 'PEER_POSITION': 30 };", 'a.ts')).to.deep.equal(['PEER_POSITION']); + expect(declaredPositionNames("const o = { 'PEER_SLOT': 30 };", 'a.ts')).to.deep.equal(['PEER_SLOT']); }); it('never hand-numbers a slot constant outside the registry, under any of its spellings', () => { From afd2a547b90d7284c0925c3d9c1ecea8d8b10440 Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Tue, 6 Oct 2026 12:40:29 -0500 Subject: [PATCH 3/6] Resolve a slot key's static name once, instead of per spelling Three rounds each found another spelling that slipped past the walker: _SLOT and _INDEX, then a quoted object key, then a computed one. The predicate was enumerating spellings rather than asking the question the audit actually has -- what name does this declaration bind? staticName() answers that for bare, quoted, template and computed-literal keys alike, and returns undefined for a genuinely dynamic key, which has no static name to audit. Co-Authored-By: Claude Opus 5 --- .../replication/sharedStatusSlots.test.mjs | 21 ++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/unitTests/replication/sharedStatusSlots.test.mjs b/unitTests/replication/sharedStatusSlots.test.mjs index fbe8c0c85..7ffe87227 100644 --- a/unitTests/replication/sharedStatusSlots.test.mjs +++ b/unitTests/replication/sharedStatusSlots.test.mjs @@ -10,6 +10,15 @@ const REPLICATION_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..' const REGISTRY_RELATIVE_PATH = 'sharedStatusSlots.ts'; const SLOT_NAME_SUFFIXES = ['_POSITION', '_SLOT', '_INDEX']; +/** The name a declaration binds, however it is spelled: bare, quoted, or a computed key whose + * expression is a literal. Anything genuinely dynamic has no static name and returns undefined. */ +function staticName(node) { + if (!node) return undefined; + if (ts.isIdentifier(node) || ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text; + if (ts.isComputedPropertyName(node)) return staticName(node.expression); + return undefined; +} + function declaredPositionNames(source, fileName) { const names = []; const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS); @@ -19,9 +28,9 @@ function declaredPositionNames(source, fileName) { ts.isBindingElement(node) || ts.isPropertyDeclaration(node) || ts.isPropertyAssignment(node); - const named = binds && (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)); - if (named && SLOT_NAME_SUFFIXES.some((s) => node.name.text.endsWith(s))) { - names.push(node.name.text); + const name = binds ? staticName(node.name) : undefined; + if (name && SLOT_NAME_SUFFIXES.some((s) => name.endsWith(s))) { + names.push(name); } ts.forEachChild(node, visit); }; @@ -92,10 +101,12 @@ describe('replication shared-status slot registry', () => { expect(declaredPositionNames('const UNRELATED_OFFSET = 40;', 'a.ts')).to.deep.equal([]); }); - it('declaredPositionNames catches an object-literal slot, quoted or not', () => { + it('declaredPositionNames catches an object-literal slot however the key is spelled', () => { expect(declaredPositionNames('const o = { PEER_POSITION: 30 };', 'a.ts')).to.deep.equal(['PEER_POSITION']); expect(declaredPositionNames("const o = { 'PEER_POSITION': 30 };", 'a.ts')).to.deep.equal(['PEER_POSITION']); - expect(declaredPositionNames("const o = { 'PEER_SLOT': 30 };", 'a.ts')).to.deep.equal(['PEER_SLOT']); + expect(declaredPositionNames("const o = { ['PEER_SLOT']: 30 };", 'a.ts')).to.deep.equal(['PEER_SLOT']); + expect(declaredPositionNames('const o = { [`PEER_INDEX`]: 30 };', 'a.ts')).to.deep.equal(['PEER_INDEX']); + expect(declaredPositionNames('const o = { [dynamic]: 30 };', 'a.ts')).to.deep.equal([]); }); it('never hand-numbers a slot constant outside the registry, under any of its spellings', () => { From b9e213ede8a0fc97782a72b72e70cd50d90192e7 Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Tue, 6 Oct 2026 12:58:28 -0500 Subject: [PATCH 4/6] Don't mistake a reference to a slot constant for a declaration of one Generalizing to staticName() went one step too far: it unwrapped a computed key and accepted an identifier, so a label map keyed by the registry's own constants -- { [RECEIVED_VERSION_POSITION]: 'received' }, exactly what the registry exists to enable -- would fail the audit and be told to move itself into the registry. Inside a computed key an identifier references a value; it binds no name. Only a string or template literal there binds one. Adds the regression test, which fails if the computed branch accepts identifiers again. Co-Authored-By: Claude Opus 5 --- .../replication/sharedStatusSlots.test.mjs | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/unitTests/replication/sharedStatusSlots.test.mjs b/unitTests/replication/sharedStatusSlots.test.mjs index 7ffe87227..0b867b65d 100644 --- a/unitTests/replication/sharedStatusSlots.test.mjs +++ b/unitTests/replication/sharedStatusSlots.test.mjs @@ -10,12 +10,16 @@ const REPLICATION_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..' const REGISTRY_RELATIVE_PATH = 'sharedStatusSlots.ts'; const SLOT_NAME_SUFFIXES = ['_POSITION', '_SLOT', '_INDEX']; -/** The name a declaration binds, however it is spelled: bare, quoted, or a computed key whose - * expression is a literal. Anything genuinely dynamic has no static name and returns undefined. */ +function isLiteralName(node) { + return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node); +} + function staticName(node) { if (!node) return undefined; - if (ts.isIdentifier(node) || ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text; - if (ts.isComputedPropertyName(node)) return staticName(node.expression); + if (ts.isIdentifier(node) || isLiteralName(node)) return node.text; + // Inside a computed key an identifier REFERENCES a constant rather than binding a name, so + // `{ [RECEIVED_VERSION_POSITION]: 'received' }` is a legitimate use of the registry, not a slot. + if (ts.isComputedPropertyName(node) && isLiteralName(node.expression)) return node.expression.text; return undefined; } @@ -109,6 +113,11 @@ describe('replication shared-status slot registry', () => { expect(declaredPositionNames('const o = { [dynamic]: 30 };', 'a.ts')).to.deep.equal([]); }); + it("declaredPositionNames leaves a map keyed by the registry's own constants alone", () => { + expect(declaredPositionNames("const labels = { [PEER_SLOT]: 'peer' };", 'a.ts')).to.deep.equal([]); + expect(declaredPositionNames("const labels = { [RECEIVED_VERSION_POSITION]: 'v' };", 'a.ts')).to.deep.equal([]); + }); + it('never hand-numbers a slot constant outside the registry, under any of its spellings', () => { const offenders = []; for (const file of readdirSync(REPLICATION_DIR, { withFileTypes: true, recursive: true })) { From 7baf9dbf1efb795512cf21dae46331131ee7aaa4 Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Tue, 6 Oct 2026 13:30:04 -0500 Subject: [PATCH 5/6] Audit enum members too Raised independently by two review rounds and the CI reviewer. I had skipped it on the grounds that widening the predicate is what produced the earlier false positive -- but that conflated two different things. That bug came from treating a reference as a binding; an enum member's name is unambiguously a binding, so there is no such risk here. Enums stay banned by the guidelines and replication/ has none. The audit is defense in depth, and should catch one rather than wave it through. Co-Authored-By: Claude Opus 5 --- unitTests/replication/sharedStatusSlots.test.mjs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/unitTests/replication/sharedStatusSlots.test.mjs b/unitTests/replication/sharedStatusSlots.test.mjs index 0b867b65d..62ae22308 100644 --- a/unitTests/replication/sharedStatusSlots.test.mjs +++ b/unitTests/replication/sharedStatusSlots.test.mjs @@ -31,7 +31,8 @@ function declaredPositionNames(source, fileName) { ts.isVariableDeclaration(node) || ts.isBindingElement(node) || ts.isPropertyDeclaration(node) || - ts.isPropertyAssignment(node); + ts.isPropertyAssignment(node) || + ts.isEnumMember(node); const name = binds ? staticName(node.name) : undefined; if (name && SLOT_NAME_SUFFIXES.some((s) => name.endsWith(s))) { names.push(name); @@ -113,6 +114,11 @@ describe('replication shared-status slot registry', () => { expect(declaredPositionNames('const o = { [dynamic]: 30 };', 'a.ts')).to.deep.equal([]); }); + it('declaredPositionNames catches an enum member slot too', () => { + expect(declaredPositionNames('enum E { PEER_POSITION = 30 }', 'a.ts')).to.deep.equal(['PEER_POSITION']); + expect(declaredPositionNames("enum E { 'PEER_SLOT' = 30 }", 'a.ts')).to.deep.equal(['PEER_SLOT']); + }); + it("declaredPositionNames leaves a map keyed by the registry's own constants alone", () => { expect(declaredPositionNames("const labels = { [PEER_SLOT]: 'peer' };", 'a.ts')).to.deep.equal([]); expect(declaredPositionNames("const labels = { [RECEIVED_VERSION_POSITION]: 'v' };", 'a.ts')).to.deep.equal([]); From d705d452422e8208f83ef6fc3ba61b471bde5a55 Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Tue, 6 Oct 2026 13:45:58 -0500 Subject: [PATCH 6/6] Unwrap a parenthesized computed key Same reasoning as the enum case: [('PEER_SLOT')] still binds a literal name, so unwrapping it carries none of the reference-vs-binding risk that made the identifier case wrong. Prettier strips redundant parentheses, so this is belt-and-braces rather than a live hole. Co-Authored-By: Claude Opus 5 --- unitTests/replication/sharedStatusSlots.test.mjs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/unitTests/replication/sharedStatusSlots.test.mjs b/unitTests/replication/sharedStatusSlots.test.mjs index 62ae22308..0555c3e2a 100644 --- a/unitTests/replication/sharedStatusSlots.test.mjs +++ b/unitTests/replication/sharedStatusSlots.test.mjs @@ -11,7 +11,12 @@ const REGISTRY_RELATIVE_PATH = 'sharedStatusSlots.ts'; const SLOT_NAME_SUFFIXES = ['_POSITION', '_SLOT', '_INDEX']; function isLiteralName(node) { - return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node); + if (node && ts.isParenthesizedExpression(node)) return isLiteralName(node.expression); + return node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)); +} + +function literalNameText(node) { + return ts.isParenthesizedExpression(node) ? literalNameText(node.expression) : node.text; } function staticName(node) { @@ -19,7 +24,7 @@ function staticName(node) { if (ts.isIdentifier(node) || isLiteralName(node)) return node.text; // Inside a computed key an identifier REFERENCES a constant rather than binding a name, so // `{ [RECEIVED_VERSION_POSITION]: 'received' }` is a legitimate use of the registry, not a slot. - if (ts.isComputedPropertyName(node) && isLiteralName(node.expression)) return node.expression.text; + if (ts.isComputedPropertyName(node) && isLiteralName(node.expression)) return literalNameText(node.expression); return undefined; } @@ -111,6 +116,7 @@ describe('replication shared-status slot registry', () => { expect(declaredPositionNames("const o = { 'PEER_POSITION': 30 };", 'a.ts')).to.deep.equal(['PEER_POSITION']); expect(declaredPositionNames("const o = { ['PEER_SLOT']: 30 };", 'a.ts')).to.deep.equal(['PEER_SLOT']); expect(declaredPositionNames('const o = { [`PEER_INDEX`]: 30 };', 'a.ts')).to.deep.equal(['PEER_INDEX']); + expect(declaredPositionNames("const o = { [('PEER_SLOT')]: 30 };", 'a.ts')).to.deep.equal(['PEER_SLOT']); expect(declaredPositionNames('const o = { [dynamic]: 30 };', 'a.ts')).to.deep.equal([]); });