Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/adr/ADR-2002-corpus-is-the-ontology.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,20 @@ lineage: distils the ADR-NG-001 explorer-architecture reconstruction and the ADR

# ADR-2002 — Fuse corpus and ontology — a Logseq page IS an OWL class

## Retained explorer verification — 2026-11-14

Reviewed the pending buffer repair before publication. The worker admission path still checks the current generation before releasing a return. The regression now exercises twenty rounds with both slots occupied and two structured-clone transfers per buffer, detaching each outbound wrapper. All 26 worker tests pass, including 12 position-transport tests. Replacing only the implementation with remote main's original source makes both transfer regressions fail (10 other position-transport tests pass); the repaired source was restored before the passing run. This verifies the retained copy only: no renderer dependency upgrade, website build or live deployment is claimed.

## External findings repair — 2026-11-03

The retained explorer's DoubleBuffer now counts outstanding transfers, rather than requiring object identity to survive a worker transfer. Its caller remains responsible for generation admission. The regression uses structuredClone with transfer to detach the original and return a fresh object; all eleven position transport tests pass. This repairs the local legacy copy without claiming an upgrade of its v0.1.1 renderer dependency or remote publication.

## External review reconciliation — 2026-11-02

Source at `4ed9ac159da` retains the legacy explorer independently of the authored-vault publisher. `explorer/modern/package.json:20` pins the vowl-wasm v0.1.1 release tarball. Its `src/workers/positionTransport.ts:76-82` requires returned buffers to retain object identity in `owned`, which transferable round-trips do not preserve; the external DoubleBuffer finding remains relevant to this copy.

Choose retirement or a tested consumer upgrade explicitly; neither a newer renderer checkout nor visionGraph's own fix updates this retained explorer. The historical Logseq authoring description above is lineage, not the current visionGraph authoring interface. No website build or deployment was performed here.

## Context

The baseline records *that* every page in `ontology/pages/` carries a `Page`
Expand Down
31 changes: 29 additions & 2 deletions explorer/modern/src/workers/__tests__/positionTransport.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,33 @@ describe('copyPositions', () => {
});

describe('DoubleBuffer ping-pong swap', () => {
it('reclaims a transferred buffer whose object identity changed', () => {
const db = new DoubleBuffer(8);
const original = db.acquire()!;
const returned = structuredClone(original, { transfer: [original] });
expect(original.byteLength).toBe(0);
expect(db.release(returned)).toBe(true);
expect(db.freeCount).toBe(2);
expect(db.acquire()).toBe(returned);
});
it('keeps both slots reusable across repeated two-way transfers', () => {
const db = new DoubleBuffer(8);
for (let frame = 0; frame < 20; frame++) {
const first = db.acquire()!;
const second = db.acquire()!;
expect(db.acquire()).toBeUndefined();
for (const outbound of [first, second]) {
const onMain = structuredClone(outbound, { transfer: [outbound] });
expect(outbound.byteLength).toBe(0);
const onWorker = structuredClone(onMain, { transfer: [onMain] });
expect(onMain.byteLength).toBe(0);
expect(db.release(onWorker)).toBe(true);
}
expect(db.allFree).toBe(true);
expect(db.freeCount).toBe(2);
}
});

it('hands out exactly two distinct buffers of the right size', () => {
const db = new DoubleBuffer(24);
expect(db.freeCount).toBe(2);
Expand Down Expand Up @@ -62,12 +89,12 @@ describe('DoubleBuffer ping-pong swap', () => {
expect(db.acquire()).toBe(a); // the reclaimed one comes back
});

it('is idempotent on double-release and rejects foreign buffers', () => {
it('rejects duplicate, unsolicited and wrong-sized returns', () => {
const db = new DoubleBuffer(8);
const a = db.acquire()!;
expect(db.release(a)).toBe(true);
expect(db.release(a)).toBe(false); // already free
expect(db.release(new ArrayBuffer(8))).toBe(false); // not ours
expect(db.release(new ArrayBuffer(8))).toBe(false); // no outstanding transfer
expect(db.release(new ArrayBuffer(16))).toBe(false); // wrong size
expect(db.freeCount).toBe(2);
});
Expand Down
24 changes: 13 additions & 11 deletions explorer/modern/src/workers/positionTransport.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,20 +46,20 @@ export function copyPositions(src: Float32Array, dst: Float32Array): void {
* regardless.
*
* Invariant: a buffer is either free (in the pool) or in flight (acquired, not
* yet released) — never both, never lost. `release()` ignores foreign buffers
* (wrong size or not one of ours) so a stale ReturnBuffer from a superseded
* generation cannot corrupt the pool.
* yet released) — never both, never lost. Transfer changes object identity;
* the worker's generation guard rejects stale messages, while this pool
* bounds returned buffers by size and the outstanding transfer count.
*/
export class DoubleBuffer {
readonly byteLength: number;
private readonly owned: ArrayBuffer[];
private inFlight = 0;
private static readonly SIZE = 2;
private free: ArrayBuffer[];

constructor(byteLength: number) {
this.byteLength = byteLength;
const a = new ArrayBuffer(byteLength);
const b = new ArrayBuffer(byteLength);
this.owned = [a, b];
this.free = [a, b];
}

Expand All @@ -70,24 +70,26 @@ export class DoubleBuffer {

/** Pop a free buffer to compute into, or undefined when both are in flight. */
acquire(): ArrayBuffer | undefined {
return this.free.pop();
const buffer = this.free.pop();
if (buffer !== undefined) this.inFlight++;
return buffer;
}

/**
* Return a buffer to the pool. Accepts only a buffer this pool owns and of the
* right size that is not already free (idempotent, ignores foreign/stale
* buffers). Returns true if it was reclaimed.
* Return one in-flight buffer of the right size. Generation validation
* belongs to the caller because transferred objects have new identities.
*/
release(buf: ArrayBuffer): boolean {
if (buf.byteLength !== this.byteLength) return false;
if (!this.owned.includes(buf)) return false;
if (this.inFlight === 0) return false;
if (this.free.includes(buf)) return false;
this.inFlight--;
this.free.push(buf);
return true;
}

/** True when neither buffer is in flight. */
get allFree(): boolean {
return this.free.length === this.owned.length;
return this.free.length === DoubleBuffer.SIZE;
}
}
Loading