commit cbb222637127034174b0216a59d983878b342132
parent d525b5530b4045eb5a8825a2156f8ab23f95a3b6
Author: triesap <tyson@radroots.org>
Date: Tue, 6 Oct 2026 13:12:22 +0000
availability: Resolve latest heads independently of search constraints (HCP-036)
- Batch exact coordinates and bounded same-author deletion lookups without search terms
- Coalesce reads through shared run budgets and retain final admitted evidence
- Share known tombstones across batches and expose honest partial source outcomes
- Verify signed head supersession, lifecycle preservation and actual SDK loopback behavior
Diffstat:
5 files changed, 1000 insertions(+), 1 deletion(-)
diff --git a/web/src/lib/catalog/resolve-head.ts b/web/src/lib/catalog/resolve-head.ts
@@ -0,0 +1,318 @@
+import { PUBLIC_QUERY_BUDGETS } from '../config/budgets.ts';
+import type { PublicFilter } from '../nostr/exports.ts';
+import { headResolutionQueries } from '../nostr/product-queries.ts';
+import {
+ verifiedEnvelopeSnapshot,
+ type VerifiedEnvelope
+} from '../nostr/verified-envelope.ts';
+import {
+ admitDeletionRequest,
+ deletionRequestEnvelope,
+ deletionRequestSnapshot,
+ type DeletionRequest
+} from '../nostr/deletion-adapter.ts';
+import {
+ closePublicRequest,
+ publicRequestScopeSnapshot,
+ publicRunObservations,
+ publicRunSnapshot,
+ type PublicRun,
+ type PublicRequest
+} from '../nostr/request-scope.ts';
+import {
+ subscribePublicView,
+ publicViewRunCurrent,
+ type PublicView
+} from '../runtime/public-runtime.ts';
+import {
+ createPublicHeadCandidate,
+ publicHeadKey,
+ publicHeadSnapshot,
+ publicHeadEnvelope,
+ type PublicHead
+} from './heads.ts';
+import {
+ createFoodHeadState,
+ advanceFoodHeadState,
+ refreshFoodHeadState,
+ foodHeadStateHead,
+ foodHeadStateSnapshot,
+ type FoodHeadState
+} from './head-state.ts';
+import { evaluatePublicHeadDeletion } from './deletions.ts';
+import type { WallClock } from './clock-policy.ts';
+
+declare const resolverBrand: unique symbol;
+export type HeadResolver = Readonly<{ readonly [resolverBrand]: true }>;
+// Trusted logical request factory, like openPublicRequest's transport factory.
+// Production binds this to the view's genuine shared run and anonymous pool.
+export type HeadSubscriber = (
+ kind: 'head' | 'deletion',
+ filters: readonly PublicFilter[],
+ onVerified: (proof: VerifiedEnvelope) => void
+) => PublicRequest;
+type ScopeSnapshot = ReturnType<typeof publicRequestScopeSnapshot>;
+interface Group {
+ readonly head: () => ScopeSnapshot | undefined;
+ readonly deletion: () => ScopeSnapshot | undefined;
+ readonly complete: () => boolean;
+ readonly open: () => void;
+ readonly close: () => void;
+}
+interface Entry {
+ readonly state: FoodHeadState;
+ readonly group: Group;
+}
+interface Owner {
+ readonly resolve: (heads: readonly PublicHead[]) => void;
+ readonly snapshot: () => readonly HeadResolution[];
+ readonly close: () => void;
+}
+export type HeadResolution = Readonly<{
+ key: string;
+ state: ReturnType<typeof foodHeadStateSnapshot>;
+ deletion: ReturnType<typeof evaluatePublicHeadDeletion>;
+ deletionProofs: readonly VerifiedEnvelope[];
+ headSources: ScopeSnapshot | undefined;
+ deletionSources: ScopeSnapshot | undefined;
+ coverage: 'bounded-eose' | 'partial';
+ lastKnown: boolean;
+ definitiveAbsence: false;
+}>;
+const owners = new WeakMap<HeadResolver, Owner>();
+function ownerOf(resolver: HeadResolver): Owner {
+ const owner = owners.get(resolver);
+ if (!owner) throw new Error('head_resolver_invalid');
+ return owner;
+}
+function emptyRows<T>(): readonly T[] {
+ return [];
+}
+export function createHeadResolver(
+ run: PublicRun,
+ subscribe: HeadSubscriber,
+ clock: WallClock
+): HeadResolver {
+ publicRunSnapshot(run);
+ const readClock = clock.nowSeconds;
+ if (typeof readClock !== 'function')
+ throw new Error('head_resolver_clock_invalid');
+ const token = Object.freeze({}) as HeadResolver;
+ const entries = new Map<string, Entry>(),
+ evidence = new Map<string, DeletionRequest>();
+ let groups = emptyRows<Group>();
+ let closed = false;
+ const active = () => !closed && publicRunSnapshot(run).active;
+ function groupFor(heads: readonly PublicHead[]): Group {
+ const queries = headResolutionQueries(heads),
+ keys = new Map(heads.map((h) => [publicHeadKey(h), true]));
+ const authors = new Map(
+ heads.map((h) => [publicHeadSnapshot(h).pubkey, true])
+ );
+ let headRequest: PublicRequest | undefined,
+ deletionRequest: PublicRequest | undefined;
+ let incomplete = false;
+ const snapshot = (request: PublicRequest | undefined) =>
+ request === undefined ? undefined : publicRequestScopeSnapshot(request);
+ const stop = () => {
+ // Independent cleanup: failure of one control cannot strand the other.
+ let failed = false;
+ for (const request of [headRequest, deletionRequest]) {
+ if (request === undefined) continue;
+ try {
+ closePublicRequest(request);
+ } catch {
+ failed = true;
+ }
+ }
+ if (failed) throw new Error('head_resolver_close_failed');
+ };
+ const checked = (
+ kind: 'head' | 'deletion',
+ filters: readonly PublicFilter[],
+ next: (proof: VerifiedEnvelope) => void
+ ) => {
+ const request = subscribe(kind, filters, (proof) => {
+ // The request owner has already admitted this callback, including the
+ // final valid delivery that exhausts ingress before request teardown.
+ if (!closed) next(proof);
+ });
+ try {
+ publicRunObservations(run, request);
+ if (publicRequestScopeSnapshot(request).kind !== kind)
+ throw new Error('head_resolver_request_kind');
+ } catch {
+ closePublicRequest(request);
+ throw new Error('head_resolver_request_owner');
+ }
+ return request;
+ };
+ return {
+ head: () => snapshot(headRequest),
+ deletion: () => snapshot(deletionRequest),
+ complete: () =>
+ !incomplete &&
+ snapshot(headRequest)?.state === 'eose' &&
+ snapshot(deletionRequest)?.state === 'eose',
+ close: () => {
+ incomplete = true;
+ stop();
+ },
+ open() {
+ try {
+ headRequest = checked('head', queries.head, (proof) => {
+ const candidate = createPublicHeadCandidate(proof);
+ const key =
+ candidate === undefined ? undefined : publicHeadKey(candidate);
+ if (key === undefined || !keys.has(key)) {
+ incomplete = true;
+ return;
+ }
+ const entry = entries.get(key);
+ if (entry) advanceFoodHeadState(entry.state, proof);
+ });
+ if (!active()) {
+ incomplete = true;
+ stop();
+ return;
+ }
+ deletionRequest = checked('deletion', queries.deletion, (proof) => {
+ const event = verifiedEnvelopeSnapshot(proof);
+ if (!event || !authors.has(event.pubkey)) {
+ incomplete = true;
+ return;
+ }
+ const request = admitDeletionRequest(proof);
+ if (!request.ok) {
+ incomplete = true;
+ return;
+ }
+ const row = deletionRequestSnapshot(request.value);
+ if (row) evidence.set(row.id, request.value);
+ });
+ if (!active()) {
+ incomplete = true;
+ stop();
+ }
+ } catch {
+ incomplete = true;
+ stop();
+ }
+ }
+ };
+ }
+ owners.set(token, {
+ resolve(heads) {
+ if (!active()) throw new Error('head_resolver_inactive');
+ // Validate the complete batch and total coordinate admission before any
+ // external clock/request callback. Repeated coordinates never reset work.
+ headResolutionQueries(heads);
+ const unique = new Map<string, PublicHead>();
+ for (const head of heads) unique.set(publicHeadKey(head), head);
+ const fresh = Array.from(unique.values()).filter(
+ (h) => !entries.has(publicHeadKey(h))
+ );
+ if (entries.size + fresh.length > PUBLIC_QUERY_BUDGETS.coordinatesPerRun)
+ throw new Error('head_resolver_coordinate_limit');
+ const group = fresh.length === 0 ? undefined : groupFor(fresh);
+ if (group) groups = groups.concat(group);
+ // Reserve every coordinate before caller-controlled clocks or openers.
+ let prepared = false;
+ let created = emptyRows<FoodHeadState>();
+ for (const head of fresh) {
+ const state = createFoodHeadState(head, {
+ nowSeconds: () => (prepared ? readClock() : NaN)
+ });
+ entries.set(publicHeadKey(head), { state, group: group! });
+ created = created.concat(state);
+ }
+ prepared = true;
+ for (const state of created) refreshFoodHeadState(state);
+ for (const head of heads) {
+ const entry = entries.get(publicHeadKey(head));
+ if (entry) advanceFoodHeadState(entry.state, publicHeadEnvelope(head));
+ }
+ if (group && active()) group.open();
+ },
+ snapshot() {
+ const available = active();
+ return Array.from(entries, ([key, entry]) => {
+ const deletion = evaluatePublicHeadDeletion(
+ foodHeadStateHead(entry.state),
+ Array.from(evidence.values())
+ );
+ const state = foodHeadStateSnapshot(entry.state);
+ const complete = available && entry.group.complete();
+ return {
+ key,
+ state: {
+ ...state,
+ food: deletion.outcome === 'suppressed' ? undefined : state.food
+ },
+ deletion,
+ deletionProofs: Array.from(evidence.values()).flatMap((r) => {
+ const proof = deletionRequestEnvelope(r);
+ return proof === undefined ? [] : [proof];
+ }),
+ headSources: entry.group.head(),
+ deletionSources: entry.group.deletion(),
+ coverage: complete ? 'bounded-eose' : 'partial',
+ lastKnown: !complete,
+ definitiveAbsence: false
+ };
+ });
+ },
+ close() {
+ closed = true;
+ let failed = false;
+ for (const group of groups) {
+ try {
+ group.close();
+ } catch {
+ failed = true;
+ }
+ }
+ if (failed) throw new Error('head_resolver_close_failed');
+ }
+ });
+ return token;
+}
+const viewResolvers = new WeakMap<
+ PublicRun,
+ Readonly<{ view: PublicView; resolver: HeadResolver }>
+>();
+export function createPublicViewHeadResolver(
+ view: PublicView,
+ run: PublicRun,
+ clock: WallClock
+): HeadResolver {
+ if (!publicViewRunCurrent(view, run))
+ throw new Error('head_resolver_view_inactive');
+ const current = viewResolvers.get(run);
+ if (current) {
+ if (current.view !== view) throw new Error('head_resolver_view_mismatch');
+ return current.resolver;
+ }
+ const resolver = createHeadResolver(
+ run,
+ (kind, filters, next) =>
+ subscribePublicView(view, run, kind, filters, next),
+ clock
+ );
+ viewResolvers.set(run, { view, resolver });
+ return resolver;
+}
+export function resolveHeads(
+ resolver: HeadResolver,
+ heads: readonly PublicHead[]
+): void {
+ ownerOf(resolver).resolve(heads);
+}
+export function headResolutionSnapshot(
+ resolver: HeadResolver
+): readonly HeadResolution[] {
+ return ownerOf(resolver).snapshot();
+}
+export function closeHeadResolver(resolver: HeadResolver): void {
+ ownerOf(resolver).close();
+}
diff --git a/web/src/lib/config/budgets.ts b/web/src/lib/config/budgets.ts
@@ -4,8 +4,9 @@ export const RELAY_BUDGETS = Object.freeze({ public: 3, inbox: 3 });
// Approved public-run admission limits shared by all primary/auxiliary sources.
// Logical post-parse work accounting; no WebSocket preallocation guarantee.
+const publicDeliveryLimit = 2000;
export const PUBLIC_INGRESS_BUDGETS = Object.freeze({
- deliveries: 2000,
+ deliveries: publicDeliveryLimit,
processedBytes: 8388608,
eventBytes: 262144
});
@@ -16,3 +17,11 @@ export const PUBLIC_REQUEST_BUDGETS = Object.freeze({
runMilliseconds: 15000,
requestMilliseconds: 10000
});
+
+// Exact-coordinate auxiliary reads use the approved chronological page size.
+// Query input admission is bounded by the existing run delivery ceiling;
+// coherent logical working-set retention is a separate policy.
+export const PUBLIC_QUERY_BUDGETS = Object.freeze({
+ requestedPerRelay: 200,
+ coordinatesPerRun: publicDeliveryLimit
+});
diff --git a/web/src/lib/nostr/product-queries.ts b/web/src/lib/nostr/product-queries.ts
@@ -0,0 +1,46 @@
+import { PUBLIC_QUERY_BUDGETS } from '../config/budgets.ts';
+import {
+ publicHeadKey,
+ publicHeadSnapshot,
+ type PublicHead
+} from '../catalog/heads.ts';
+import type { PublicFilter } from './exports.ts';
+
+export function headResolutionQueries(heads: readonly PublicHead[]): Readonly<{
+ head: readonly PublicFilter[];
+ deletion: readonly PublicFilter[];
+}> {
+ if (heads.length > PUBLIC_QUERY_BUDGETS.coordinatesPerRun)
+ throw new Error('head_query_input_limit');
+ const coordinates = new Map<string, PublicHead>(),
+ authors = new Map<string, true>();
+ for (const head of heads) {
+ const row = publicHeadSnapshot(head);
+ if (row.kind !== 30402) throw new Error('head_query_kind_invalid');
+ coordinates.set(publicHeadKey(head), head);
+ authors.set(row.pubkey, true);
+ }
+ const limit = PUBLIC_QUERY_BUDGETS.requestedPerRelay;
+ return {
+ head: Array.from(coordinates.values(), (head) => {
+ const row = publicHeadSnapshot(head);
+ // A missing/malformed first d has the generic empty coordinate. An
+ // author-only bounded query discovers these, with exact reduction local.
+ return row.identifier === ''
+ ? { kinds: [30402], authors: [row.pubkey], limit }
+ : {
+ kinds: [30402],
+ authors: [row.pubkey],
+ '#d': [row.identifier!],
+ limit
+ };
+ }),
+ // Author lookups also cover e-only requests for a newer, initially unknown
+ // head ID. Advisory k and request time cannot restrict deletion authority.
+ deletion: Array.from(authors, ([author]) => ({
+ kinds: [5],
+ authors: [author],
+ limit
+ }))
+ };
+}
diff --git a/web/tests/integration/head-resolution.test.ts b/web/tests/integration/head-resolution.test.ts
@@ -0,0 +1,193 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import { readFile } from 'node:fs/promises';
+import { finalizeEvent } from 'applesauce-core/helpers';
+import WebSocket, { WebSocketServer } from 'ws';
+import { validateRelayPolicy } from '../../src/lib/config/relays.ts';
+import {
+ createPublicRuntimeContext,
+ mountPublicRuntime,
+ createPublicView,
+ beginPublicViewRun,
+ closePublicRuntime
+} from '../../src/lib/runtime/public-runtime.ts';
+import { publicRunSnapshot } from '../../src/lib/nostr/request-scope.ts';
+import { verifyEnvelope } from '../../src/lib/nostr/verified-envelope.ts';
+import { createPublicHeadCandidate } from '../../src/lib/catalog/heads.ts';
+import {
+ createPublicViewHeadResolver,
+ resolveHeads,
+ headResolutionSnapshot
+} from '../../src/lib/catalog/resolve-head.ts';
+
+await test('actual SDK exact-coordinate and author deletion queries share one bounded run and retain suppressed newest evidence', async () => {
+ const corpus = JSON.parse(
+ await readFile(
+ new URL(
+ '../../../contracts/interop/food_availability/corpus.v1.json',
+ import.meta.url
+ ),
+ 'utf8'
+ )
+ ) as { vectors: { id: string; signed_wires: Record<string, string> }[] };
+ const base = JSON.parse(
+ corpus.vectors.find((v) => v.id.endsWith('_032'))!.signed_wires.previous
+ ) as { tags: string[][]; content: string; created_at: number };
+ const key = crypto.getRandomValues(new Uint8Array(32));
+ const previous = finalizeEvent(
+ {
+ kind: 30402,
+ created_at: base.created_at,
+ tags: base.tags,
+ content: base.content
+ },
+ key
+ );
+ const current = finalizeEvent(
+ {
+ kind: 30402,
+ created_at: base.created_at + 1,
+ tags: base.tags.map((t) =>
+ t[0] === 'status'
+ ? ['status', 'sold']
+ : t[0] === 'title'
+ ? ['title', 'Renamed celery']
+ : [...t]
+ ),
+ content: base.content
+ },
+ key
+ );
+ const deletion = finalizeEvent(
+ {
+ kind: 5,
+ created_at: base.created_at - 1,
+ tags: [['e', current.id]],
+ content: ''
+ },
+ key
+ );
+ key.fill(0);
+ const origin = 'wss://one.example.org',
+ server = new WebSocketServer({
+ host: '127.0.0.1',
+ port: 0,
+ maxPayload: 4096
+ });
+ const sockets: WebSocket[] = [];
+ const filters: Record<string, unknown>[] = [];
+ let sent = () => {};
+ const sentBoth = new Promise<void>((resolve) => {
+ sent = resolve;
+ });
+ server.on('connection', (socket) => {
+ sockets.push(socket);
+ socket.on('message', (bytes) => {
+ const buffer = Array.isArray(bytes)
+ ? Buffer.concat(bytes)
+ : Buffer.isBuffer(bytes)
+ ? bytes
+ : Buffer.from(bytes);
+ const frame = JSON.parse(buffer.toString('utf8')) as unknown[];
+ if (frame[0] !== 'REQ') return;
+ const id = String(frame[1]),
+ query = frame[2] as Record<string, unknown>;
+ filters.push(query);
+ const values =
+ (query.kinds as number[])[0] === 30402
+ ? [previous, current]
+ : [deletion];
+ for (const value of values)
+ socket.send(JSON.stringify(['EVENT', id, value]));
+ socket.send(JSON.stringify(['EOSE', id]));
+ if (filters.length === 2) sent();
+ });
+ });
+ await once(server, 'listening');
+ const address = server.address();
+ assert.ok(address && typeof address !== 'string');
+ const port = address.port;
+ const oldWindow = Object.getOwnPropertyDescriptor(globalThis, 'window'),
+ oldSocket = globalThis.WebSocket;
+ class FixtureSocket extends WebSocket {
+ constructor(url: string | URL) {
+ assert.equal(String(url).replace(/\/$/, ''), origin);
+ super(`ws://127.0.0.1:${port}`);
+ }
+ }
+ Object.defineProperty(globalThis, 'window', {
+ configurable: true,
+ value: {}
+ });
+ globalThis.WebSocket =
+ FixtureSocket as unknown as typeof globalThis.WebSocket;
+ const context = createPublicRuntimeContext();
+ try {
+ const policy = validateRelayPolicy(
+ JSON.stringify({
+ schemaVersion: 1,
+ public: [{ origin, read: true, write: false, nip50: false }],
+ inbox: [],
+ postingEnabled: false,
+ messagingEnabled: false,
+ operatorDenylist: []
+ })
+ )!;
+ const runtime = mountPublicRuntime(context, policy)!;
+ const view = createPublicView(runtime),
+ run = beginPublicViewRun(view);
+ const proof = verifyEnvelope(JSON.stringify(previous));
+ assert.ok(proof.ok);
+ const initial = createPublicHeadCandidate(proof.value);
+ assert.ok(initial);
+ const resolver = createPublicViewHeadResolver(view, run, {
+ nowSeconds: () => base.created_at + 10
+ });
+ resolveHeads(resolver, [initial, initial]);
+ resolveHeads(resolver, [initial]);
+ await sentBoth;
+ for (
+ let n = 0;
+ n < 100 &&
+ headResolutionSnapshot(resolver)[0].coverage !== 'bounded-eose';
+ n++
+ )
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ assert.equal(filters.length, 2);
+ const head = filters.find((q) => (q.kinds as number[])[0] === 30402)!;
+ const requests = filters.find((q) => (q.kinds as number[])[0] === 5)!;
+ assert.deepEqual(head.authors, [previous.pubkey]);
+ assert.deepEqual(head['#d'], [base.tags.find((t) => t[0] === 'd')![1]]);
+ assert.deepEqual(requests.authors, [previous.pubkey]);
+ for (const q of filters) {
+ assert.equal(q.limit, 200);
+ assert.equal('q' in q, false);
+ assert.equal('search' in q, false);
+ assert.equal('since' in q, false);
+ assert.equal('#k' in q, false);
+ }
+ const row = headResolutionSnapshot(resolver)[0];
+ assert.equal(row.coverage, 'bounded-eose');
+ assert.equal(row.lastKnown, false);
+ assert.equal(row.state.head.id, current.id);
+ assert.equal(row.state.food, undefined);
+ assert.equal(row.deletion.outcome, 'suppressed');
+ assert.equal(row.deletionProofs.length, 1);
+ assert.equal(row.definitiveAbsence, false);
+ assert.equal(publicRunSnapshot(run).ingress.deliveries, 3);
+ assert.equal(publicRunSnapshot(run).activeRequests, 0);
+ closePublicRuntime(context);
+ assert.equal(headResolutionSnapshot(resolver)[0].lastKnown, true);
+ } finally {
+ closePublicRuntime(context);
+ key.fill(0);
+ globalThis.WebSocket = oldSocket;
+ if (oldWindow) Object.defineProperty(globalThis, 'window', oldWindow);
+ else delete (globalThis as { window?: unknown }).window;
+ for (const socket of sockets) socket.terminate();
+ await new Promise<void>((resolve, reject) =>
+ server.close((error) => (error ? reject(error) : resolve()))
+ );
+ }
+});
diff --git a/web/tests/unit/resolve-head.test.ts b/web/tests/unit/resolve-head.test.ts
@@ -0,0 +1,433 @@
+import { afterAll, describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { finalizeEvent } from 'applesauce-core/helpers';
+import { validateRelayPolicy } from '../../src/lib/config/relays.ts';
+import { PUBLIC_INGRESS_BUDGETS } from '../../src/lib/config/budgets.ts';
+import { verifyEnvelope } from '../../src/lib/nostr/verified-envelope.ts';
+import type { PublicPoolMessage } from '../../src/lib/nostr/exports.ts';
+import {
+ createPublicScheduler,
+ createPublicRun,
+ openPublicRequest,
+ publicRunSnapshot,
+ closePublicScheduler,
+ type RequestClock
+} from '../../src/lib/nostr/request-scope.ts';
+import {
+ createPublicHeadCandidate,
+ publicHeadKey
+} from '../../src/lib/catalog/heads.ts';
+import { headResolutionQueries } from '../../src/lib/nostr/product-queries.ts';
+import {
+ createHeadResolver,
+ resolveHeads,
+ headResolutionSnapshot,
+ closeHeadResolver,
+ type HeadSubscriber
+} from '../../src/lib/catalog/resolve-head.ts';
+
+const corpus = JSON.parse(
+ readFileSync(
+ new URL(
+ '../../../contracts/interop/food_availability/corpus.v1.json',
+ import.meta.url
+ ),
+ 'utf8'
+ )
+) as { vectors: { id: string; signed_wires: Record<string, string> }[] };
+const base = JSON.parse(
+ corpus.vectors.find((v) => v.id.endsWith('_032'))!.signed_wires.previous
+) as { tags: string[][]; content: string; created_at: number };
+const keys: Uint8Array[] = [];
+const cleanup: (() => void)[] = [];
+afterAll(() => {
+ for (const stop of cleanup) stop();
+ for (const key of keys) key.fill(0);
+});
+function fixture() {
+ const key = crypto.getRandomValues(new Uint8Array(32));
+ keys.push(key);
+ const event = (
+ time = base.created_at,
+ tags = base.tags,
+ content = base.content,
+ kind = 30402
+ ) => finalizeEvent({ kind, created_at: time, tags, content }, key);
+ const proof = (value: ReturnType<typeof event>) => {
+ const p = verifyEnvelope(JSON.stringify(value));
+ if (!p.ok) throw Error('fixture proof');
+ return p.value;
+ };
+ const head = (value = event()) => {
+ const h = createPublicHeadCandidate(proof(value));
+ if (!h) throw Error('fixture head');
+ return h;
+ };
+ const origin = 'wss://one.example.org';
+ const policy = validateRelayPolicy(
+ JSON.stringify({
+ schemaVersion: 1,
+ public: [{ origin, read: true, write: false, nip50: false }],
+ inbox: [],
+ postingEnabled: false,
+ messagingEnabled: false,
+ operatorDenylist: []
+ })
+ )!;
+ let now = 0;
+ const timers = new Map<() => void, { at: number; callback: () => void }>();
+ const clock: RequestClock = {
+ now: () => now,
+ schedule(callback, delay) {
+ const cancel = () => {
+ timers.delete(cancel);
+ };
+ timers.set(cancel, { at: now + delay, callback });
+ return cancel;
+ }
+ };
+ const scheduler = createPublicScheduler(clock),
+ run = createPublicRun(scheduler, policy);
+ cleanup.push(() => closePublicScheduler(scheduler));
+ const channels: {
+ kind: string;
+ filters: unknown;
+ emit: (message: PublicPoolMessage) => void;
+ stopped: () => boolean;
+ }[] = [];
+ const subscribe: HeadSubscriber = (kind, filters, onVerified) =>
+ openPublicRequest(
+ run,
+ kind,
+ (next) => {
+ let stopped = false;
+ channels.push({ kind, filters, emit: next, stopped: () => stopped });
+ return () => {
+ stopped = true;
+ };
+ },
+ onVerified
+ );
+ const resolver = createHeadResolver(run, subscribe, {
+ nowSeconds: () => base.created_at + 10
+ });
+ const emit = (i: number, value: ReturnType<typeof event>) =>
+ channels[i].emit({
+ type: 'EVENT',
+ id: 'fixture',
+ from: origin,
+ event: value
+ });
+ const eose = (i: number) =>
+ channels[i].emit({ type: 'EOSE', id: 'fixture', from: origin });
+ const initial = head();
+ return {
+ event,
+ head,
+ initial,
+ run,
+ resolver,
+ channels,
+ emit,
+ eose,
+ proof,
+ origin,
+ timers,
+ advance: (value: number) => {
+ now = value;
+ for (const t of [...timers.values()]) if (t.at <= now) t.callback();
+ }
+ };
+}
+describe('bounded exact-coordinate head resolution', () => {
+ it('batches unique exact coordinates and author deletion lookups without keyword constraints', () => {
+ const f = fixture(),
+ other = f.head(
+ f.event(
+ base.created_at,
+ base.tags.map((t) => (t[0] === 'd' ? ['d', 'other'] : [...t]))
+ )
+ );
+ const queries = headResolutionQueries([f.initial, other, f.initial]);
+ expect(queries.head).toHaveLength(2);
+ expect(queries.deletion).toHaveLength(1);
+ expect(queries.head[0]).toEqual({
+ kinds: [30402],
+ authors: [f.event().pubkey],
+ '#d': [base.tags.find((t) => t[0] === 'd')![1]],
+ limit: 200
+ });
+ for (const filter of [...queries.head, ...queries.deletion]) {
+ expect(filter).not.toHaveProperty('search');
+ expect(filter).not.toHaveProperty('q');
+ expect(filter).not.toHaveProperty('since');
+ }
+ expect(queries.deletion[0]).toMatchObject({ kinds: [5], limit: 200 });
+ });
+ it('empty generic coordinates omit d filters so missing first d is discoverable', () => {
+ const f = fixture();
+ const h = f.head(
+ f.event(
+ base.created_at,
+ base.tags.filter((t) => t[0] !== 'd')
+ )
+ );
+ expect(headResolutionQueries([h]).head[0]).not.toHaveProperty('#d');
+ });
+ it('renamed and sold revisions supersede the original keyword match before projection', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ const tags = base.tags.map((t) =>
+ t[0] === 'title'
+ ? ['title', 'Renamed celery']
+ : t[0] === 'status'
+ ? ['status', 'sold']
+ : [...t]
+ );
+ const newer = f.event(base.created_at + 1, tags);
+ f.emit(0, newer);
+ f.eose(0);
+ f.eose(1);
+ const row = headResolutionSnapshot(f.resolver)[0];
+ expect(row.state.head.id).toBe(newer.id);
+ expect(row.state.food?.title).toBe('Renamed celery');
+ expect(row.state.food?.status).toBe('sold');
+ expect(row.coverage).toBe('bounded-eose');
+ expect(row.lastKnown).toBe(false);
+ expect(row.definitiveAbsence).toBe(false);
+ });
+ it('newer incompatible heads prevent an older focused fallback', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ const newer = f.event(
+ base.created_at + 1,
+ base.tags.map((t) => (t[0] === 'status' ? ['status', 'unknown'] : [...t]))
+ );
+ f.emit(0, newer);
+ f.emit(0, f.event());
+ const row = headResolutionSnapshot(f.resolver)[0];
+ expect(row.state.head.id).toBe(newer.id);
+ expect(row.state.display).toBe('unsupported');
+ expect(row.state.food).toBeUndefined();
+ });
+ it('incomplete or unavailable lookup retains honest last-known source outcomes', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ f.eose(0);
+ let row = headResolutionSnapshot(f.resolver)[0];
+ expect(row.lastKnown).toBe(true);
+ expect(row.deletionSources?.result.sources[0].state).toBe('pending');
+ f.channels[1].emit({
+ type: 'CLOSED',
+ id: 'fixture',
+ from: f.origin,
+ reason: 'untrusted relay text'
+ });
+ row = headResolutionSnapshot(f.resolver)[0];
+ expect(row.coverage).toBe('partial');
+ expect(row.lastKnown).toBe(true);
+ expect(row.state.head.id).toBe(
+ headResolutionSnapshot(f.resolver)[0].state.head.id
+ );
+ expect(JSON.stringify(row)).not.toContain('untrusted relay text');
+ });
+ it('coalesces repeated coordinates and updates retained winners without extra requests', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial, f.initial]);
+ resolveHeads(f.resolver, [f.initial]);
+ expect(f.channels).toHaveLength(2);
+ expect(publicRunSnapshot(f.run).activeRequests).toBe(2);
+ const newer = f.head(f.event(base.created_at + 1));
+ resolveHeads(f.resolver, [newer]);
+ expect(f.channels).toHaveLength(2);
+ expect(headResolutionSnapshot(f.resolver)[0].key).toBe(
+ publicHeadKey(newer)
+ );
+ });
+ it('same-author deletion of a newly discovered ID suppresses that winner and retains its evidence', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ const newer = f.event(base.created_at + 1);
+ f.emit(0, newer);
+ f.emit(1, f.event(base.created_at - 1, [['e', newer.id]], '', 5));
+ f.eose(0);
+ f.eose(1);
+ const row = headResolutionSnapshot(f.resolver)[0];
+ expect(row.state.head.id).toBe(newer.id);
+ expect(row.deletion.outcome).toBe('suppressed');
+ expect(row.state.food).toBeUndefined();
+ expect(row.deletionProofs).toHaveLength(1);
+ expect(verifyEnvelope(JSON.stringify(newer)).ok).toBe(true);
+ expect(publicRunSnapshot(f.run).ingress.deliveries).toBe(2);
+ });
+ it('rejects out-of-coordinate responses locally and marks malformed deletion coverage partial', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ f.emit(
+ 0,
+ f.event(
+ base.created_at + 1,
+ base.tags.map((t) => (t[0] === 'd' ? ['d', 'wrong'] : [...t]))
+ )
+ );
+ f.emit(1, f.event(base.created_at, [['e', 'bad']], '', 5));
+ f.eose(0);
+ f.eose(1);
+ const row = headResolutionSnapshot(f.resolver)[0];
+ expect(row.coverage).toBe('partial');
+ expect(row.state.head.id).toBe(f.event().id);
+ expect(publicRunSnapshot(f.run).ingress.deliveries).toBe(2);
+ });
+ it('auxiliary deliveries exhaust the same run budget and stop both queries', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ const value = f.event();
+ for (let n = 0; n < PUBLIC_INGRESS_BUDGETS.deliveries; n++)
+ f.emit(n % 2, value);
+ expect(publicRunSnapshot(f.run).ingress.deliveries).toBe(2000);
+ expect(f.channels.every((c) => c.stopped())).toBe(true);
+ expect(headResolutionSnapshot(f.resolver)[0].lastKnown).toBe(true);
+ });
+ it('deadline and explicit teardown stop effects while retaining last-known evidence', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ f.advance(10000);
+ expect(f.channels.every((c) => c.stopped())).toBe(true);
+ expect(f.timers.size).toBe(0);
+ expect(headResolutionSnapshot(f.resolver)[0].headSources?.state).toBe(
+ 'deadline'
+ );
+ closeHeadResolver(f.resolver);
+ expect(headResolutionSnapshot(f.resolver)[0].lastKnown).toBe(true);
+ expect(() => resolveHeads(f.resolver, [f.initial])).toThrow();
+ });
+ it('a second scope admission failure closes the first without cancelling unrelated work', () => {
+ const f = fixture();
+ for (let n = 0; n < 5; n++)
+ openPublicRequest(
+ f.run,
+ 'profile',
+ () => () => {},
+ () => {}
+ );
+ resolveHeads(f.resolver, [f.initial]);
+ expect(f.channels).toHaveLength(1);
+ expect(f.channels[0].stopped()).toBe(true);
+ expect(publicRunSnapshot(f.run).activeRequests).toBe(5);
+ expect(headResolutionSnapshot(f.resolver)[0].coverage).toBe('partial');
+ });
+ it('detached result metadata cannot alter winner, deletion evidence or later coverage', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ const row = headResolutionSnapshot(f.resolver)[0];
+ (row.state.head as unknown as { id: string }).id = 'forged';
+ const source = row.headSources!.result.sources[0];
+ (source as unknown as { state: string }).state = 'eose';
+ expect(headResolutionSnapshot(f.resolver)[0].state.head.id).toBe(
+ f.event().id
+ );
+ expect(
+ headResolutionSnapshot(f.resolver)[0].headSources?.result.sources[0].state
+ ).toBe('pending');
+ });
+ it('late callbacks after resolver teardown cannot replace retained evidence', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ closeHeadResolver(f.resolver);
+ f.emit(0, f.event(base.created_at + 1));
+ expect(headResolutionSnapshot(f.resolver)[0].state.head.id).toBe(
+ f.event().id
+ );
+ expect(publicRunSnapshot(f.run).ingress.deliveries).toBe(0);
+ });
+ it('first d identity prevents a matching secondary d from advancing another coordinate', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ f.emit(0, f.event(base.created_at + 1, [['d', 'other'], ...base.tags]));
+ expect(headResolutionSnapshot(f.resolver)[0].state.head.id).toBe(
+ f.event().id
+ );
+ expect(headResolutionSnapshot(f.resolver)[0].coverage).toBe('partial');
+ });
+ it('publishes the accepted final head delivery before the shared budget stops the run', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ const value = f.event();
+ for (let n = 0; n < 1999; n++) f.emit(0, value);
+ const newer = f.event(base.created_at + 1);
+ f.emit(0, newer);
+ expect(publicRunSnapshot(f.run).ingress.deliveries).toBe(2000);
+ expect(headResolutionSnapshot(f.resolver)[0].state.head.id).toBe(newer.id);
+ expect(headResolutionSnapshot(f.resolver)[0].lastKnown).toBe(true);
+ });
+ it('retains the accepted final tombstone delivery before the shared budget stops the run', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ const value = f.event();
+ for (let n = 0; n < 1999; n++) f.emit(0, value);
+ f.emit(1, f.event(base.created_at - 1, [['e', value.id]], '', 5));
+ expect(publicRunSnapshot(f.run).ingress.deliveries).toBe(2000);
+ const row = headResolutionSnapshot(f.resolver)[0];
+ expect(row.deletion.outcome).toBe('suppressed');
+ expect(row.state.food).toBeUndefined();
+ expect(row.lastKnown).toBe(true);
+ });
+ it('a tombstone already retained by an earlier batch suppresses a subsequently resolved coordinate without relay redelivery', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ const next = f.head(
+ f.event(
+ base.created_at + 1,
+ base.tags.map((t) => (t[0] === 'd' ? ['d', 'next'] : [...t]))
+ )
+ );
+ const author = f.event().pubkey;
+ f.emit(
+ 1,
+ f.event(base.created_at + 2, [['a', `30402:${author}:next`]], '', 5)
+ );
+ f.eose(0);
+ f.eose(1);
+ resolveHeads(f.resolver, [next]);
+ f.eose(2);
+ f.eose(3);
+ const row = headResolutionSnapshot(f.resolver).find(
+ (r) => r.key === publicHeadKey(next)
+ )!;
+ expect(row.deletion.outcome).toBe('suppressed');
+ expect(row.state.food).toBeUndefined();
+ expect(row.coverage).toBe('bounded-eose');
+ });
+ it('deletion learned in a later batch also suppresses an earlier retained coordinate', () => {
+ const f = fixture();
+ resolveHeads(f.resolver, [f.initial]);
+ f.eose(0);
+ f.eose(1);
+ const next = f.head(
+ f.event(
+ base.created_at + 1,
+ base.tags.map((t) => (t[0] === 'd' ? ['d', 'next'] : [...t]))
+ )
+ );
+ resolveHeads(f.resolver, [next]);
+ f.emit(3, f.event(base.created_at - 1, [['e', f.event().id]], '', 5));
+ f.eose(2);
+ f.eose(3);
+ const row = headResolutionSnapshot(f.resolver).find(
+ (r) => r.key === publicHeadKey(f.initial)
+ )!;
+ expect(row.deletion.outcome).toBe('suppressed');
+ expect(row.state.food).toBeUndefined();
+ expect(row.deletionProofs).toHaveLength(1);
+ });
+ it('refuses oversized batches before effects', () => {
+ const f = fixture();
+ expect(() =>
+ resolveHeads(
+ f.resolver,
+ Array.from({ length: 2001 }, () => f.initial)
+ )
+ ).toThrow();
+ expect(f.channels).toHaveLength(0);
+ });
+});