commit 4422dac7bdd418342d73e9e2b65e4b57b6a45b7c
parent 48f2a830d11eff75680ccfb1b3da02d0b456a92f
Author: triesap <tyson@radroots.org>
Date: Tue, 6 Oct 2026 16:51:28 +0000
availability: Add bounded chronological search (HCP-041)
- Reserve two chronological windows under the existing shared budgets.
- Protect each saturated source boundary with inclusive verified evidence.
- Keep local twenty-row pages separate from explicit older search runs.
- Verify multi-source gaps, cursor isolation, lifecycle and SDK behavior.
Diffstat:
9 files changed, 986 insertions(+), 39 deletions(-)
diff --git a/web/src/lib/catalog/continuation.ts b/web/src/lib/catalog/continuation.ts
@@ -0,0 +1,209 @@
+import {
+ RELAY_BUDGETS,
+ PUBLIC_QUERY_BUDGETS,
+ PUBLIC_SEARCH_BUDGETS,
+ PUBLIC_SEARCH_RUN_BUDGETS
+} from '../config/budgets.ts';
+import { publicHeadSnapshot, type PublicHead } from './heads.ts';
+export type ChronologicalCoverage =
+ 'unchecked' | 'checking' | 'bounded-eose' | 'partial';
+export type ChronologicalProgress = Readonly<{
+ windows: number;
+ active: boolean;
+ until: number | undefined;
+ gap: boolean;
+ coverage: ChronologicalCoverage;
+ observed: number;
+ definitiveAbsence: false;
+}>;
+export type ChronologicalSource = Readonly<{
+ source: string;
+ saturated: boolean;
+ eventIds: readonly string[];
+}>;
+export interface ChronologicalWindow {
+ readonly until: number | undefined;
+ readonly observe: (head: PublicHead) => void;
+ readonly finish: (
+ saturated: boolean,
+ coverage: 'bounded-eose' | 'partial',
+ sources?: readonly ChronologicalSource[]
+ ) => void;
+}
+export interface ChronologicalContinuation {
+ readonly begin: () => ChronologicalWindow;
+ readonly snapshot: () => ChronologicalProgress;
+ readonly restart: () => ChronologicalContinuation;
+}
+// Pure bookkeeping, held only in the coordinator's private session. The
+// coordinator alone associates verified chronological callbacks and real scope
+// outcomes; sample/auxiliary deliveries never reach this owner.
+function continuation(
+ seedUntil?: number,
+ seedIds: readonly string[] = [],
+ seedPartial = false
+): ChronologicalContinuation {
+ let until = seedUntil,
+ windows = 0,
+ active = false,
+ gap = false,
+ partial = seedPartial,
+ observed = 0;
+ let boundary = new Map(seedIds.map((id) => [id, true] as const));
+ const owner: ChronologicalContinuation = {
+ begin() {
+ if (active) throw new Error('food_search_chronological_pending');
+ if (gap) throw new Error('food_search_chronological_gap');
+ if (windows >= PUBLIC_SEARCH_RUN_BUDGETS.chronologicalWindows)
+ throw new Error('food_search_chronological_window_limit');
+ windows++;
+ active = true;
+ const requestedUntil = until,
+ ids = new Map<string, number>();
+ let settled = false;
+ return {
+ until: requestedUntil,
+ observe(head) {
+ if (settled)
+ throw new Error('food_search_chronological_window_closed');
+ const value = publicHeadSnapshot(head);
+ if (
+ value.kind !== 30402 ||
+ (requestedUntil !== undefined && value.created_at > requestedUntil)
+ )
+ return;
+ if (
+ !ids.has(value.id) &&
+ ids.size >= PUBLIC_QUERY_BUDGETS.coordinatesPerRun
+ ) {
+ gap = true;
+ partial = true;
+ return;
+ }
+ ids.set(value.id, value.created_at);
+ },
+ finish(saturated, coverage, sources) {
+ if (settled) return;
+ const facts = sources ?? [
+ { source: '', saturated, eventIds: Array.from(ids.keys()) }
+ ];
+ if (
+ facts.length > RELAY_BUDGETS.public ||
+ facts.some(
+ (source) =>
+ source.eventIds.length > PUBLIC_QUERY_BUDGETS.coordinatesPerRun
+ )
+ )
+ throw new Error('food_search_chronological_source_limit');
+ settled = true;
+ active = false;
+ partial = partial || coverage === 'partial';
+ observed = ids.size;
+ const times = Array.from(ids.values());
+ let oldest = times.length
+ ? times.reduce((minimum, value) => Math.min(minimum, value))
+ : undefined;
+ let protectedUntil: number | undefined;
+ for (const source of facts) {
+ if (!source.saturated) continue;
+ const sourceTimes = source.eventIds
+ .filter((id) => ids.has(id))
+ .map((id) => ids.get(id)!);
+ const sourceOldest = sourceTimes.length
+ ? sourceTimes.reduce((minimum, value) => Math.min(minimum, value))
+ : undefined;
+ if (sourceOldest === undefined) {
+ gap = true;
+ partial = true;
+ continue;
+ }
+ protectedUntil =
+ protectedUntil === undefined
+ ? sourceOldest
+ : Math.max(protectedUntil, sourceOldest);
+ const progress =
+ requestedUntil === undefined ||
+ sourceOldest < requestedUntil ||
+ source.eventIds.some(
+ (id) =>
+ ids.get(id) === sourceOldest &&
+ !boundary.has(source.source + '\0' + id)
+ );
+ if (!progress) {
+ gap = true;
+ partial = true;
+ }
+ }
+ // Every saturated source's unresolved boundary is protected. Another
+ // source's older item must never move a shared cursor below it.
+ oldest =
+ gap && requestedUntil !== undefined
+ ? requestedUntil
+ : (protectedUntil ?? oldest);
+ if (oldest !== undefined) {
+ if (oldest !== requestedUntil) boundary = new Map();
+ for (const source of facts)
+ for (const id of source.eventIds) {
+ if (ids.get(id) !== oldest) continue;
+ const key = source.source + '\0' + id;
+ if (
+ !boundary.has(key) &&
+ boundary.size >= PUBLIC_QUERY_BUDGETS.coordinatesPerRun
+ ) {
+ gap = true;
+ partial = true;
+ break;
+ }
+ boundary.set(key, true);
+ }
+ until = oldest;
+ }
+ }
+ };
+ },
+ snapshot: () => ({
+ windows,
+ active,
+ until,
+ gap,
+ coverage: active
+ ? 'checking'
+ : partial || gap
+ ? 'partial'
+ : windows
+ ? 'bounded-eose'
+ : 'unchecked',
+ observed,
+ definitiveAbsence: false
+ }),
+ restart() {
+ if (active) throw new Error('food_search_chronological_pending');
+ if (gap) throw new Error('food_search_chronological_gap');
+ if (until === undefined)
+ throw new Error('food_search_chronological_boundary_missing');
+ return continuation(until, Array.from(boundary.keys()), partial);
+ }
+ };
+ return owner;
+}
+export function createChronologicalContinuation(): ChronologicalContinuation {
+ return continuation();
+}
+
+// Local pages preserve the caller's observed ordering. No clocks or transport.
+export function localSearchPage<T>(
+ rows: readonly T[],
+ pages: number
+): Readonly<{ rows: readonly T[]; hasMore: boolean }> {
+ if (
+ !Number.isSafeInteger(pages) ||
+ pages < 1 ||
+ pages >
+ Math.ceil(
+ PUBLIC_QUERY_BUDGETS.coordinatesPerRun / PUBLIC_SEARCH_BUDGETS.pageRows
+ )
+ )
+ throw new Error('food_search_local_page_invalid');
+ const count = pages * PUBLIC_SEARCH_BUDGETS.pageRows;
+ return { rows: rows.slice(0, count), hasMore: rows.length > count };
+}
diff --git a/web/src/lib/catalog/search-run.ts b/web/src/lib/catalog/search-run.ts
@@ -1,11 +1,13 @@
import {
PUBLIC_QUERY_BUDGETS,
+ PUBLIC_SEARCH_BUDGETS,
PUBLIC_SEARCH_RUN_BUDGETS
} from '../config/budgets.ts';
import type { PublicFilter } from '../nostr/exports.ts';
import { headResolutionQueries } from '../nostr/product-queries.ts';
import {
publicRunSnapshot,
+ publicRunObservations,
publicRequestScopeSnapshot,
closePublicRequest,
cancelPublicRun,
@@ -44,6 +46,16 @@ import {
} from './search-state.ts';
import type { WallClock } from './clock-policy.ts';
import { nip50SearchQuery } from '../nostr/search-query.ts';
+import {
+ chronologicalSearchQuery,
+ requireChronologicalSearchQuery
+} from '../nostr/chronological-query.ts';
+import {
+ createChronologicalContinuation,
+ localSearchPage,
+ type ChronologicalContinuation,
+ type ChronologicalWindow
+} from './continuation.ts';
declare const coordinatorBrand: unique symbol;
declare const generationBrand: unique symbol;
export type FoodSearchCoordinator = Readonly<{
@@ -70,6 +82,18 @@ interface Session {
readonly track: (request: PublicRequest) => void;
readonly reserveSource: () => void;
readonly reserveSample: () => void;
+ readonly continuation: () => ChronologicalContinuation;
+ readonly bindContinuation: (value: ChronologicalContinuation) => void;
+ readonly chronological: () => readonly (readonly [
+ PublicRequest,
+ ChronologicalWindow
+ ])[];
+ readonly trackChronological: (
+ request: PublicRequest,
+ window: ChronologicalWindow
+ ) => void;
+ readonly pages: () => number;
+ readonly showMore: () => void;
readonly run: () => PublicRun | undefined;
readonly bindRun: (run: PublicRun) => void;
readonly model: () => HeadResolver | undefined;
@@ -79,6 +103,7 @@ interface Session {
failed: boolean;
capped: boolean;
}>;
+ readonly cap: () => void;
readonly fail: () => void;
readonly cancel: () => void;
}
@@ -126,6 +151,9 @@ function createSession(
capped = false;
let attempts = 0;
let sampleRounds = 0;
+ let chronological = createChronologicalContinuation(),
+ pages = 1;
+ const windows = new Map<PublicRequest, ChronologicalWindow>();
return {
coordinator,
token,
@@ -166,6 +194,24 @@ function createSession(
throw new Error('food_search_sample_round_limit');
sampleRounds++;
},
+ continuation: () => chronological,
+ bindContinuation: (value) => {
+ chronological = value;
+ },
+ chronological: () => Array.from(windows.entries()),
+ trackChronological: (request, window) => {
+ windows.set(request, window);
+ },
+ pages: () => pages,
+ showMore: () => {
+ pages = Math.min(
+ Math.ceil(
+ PUBLIC_QUERY_BUDGETS.coordinatesPerRun /
+ PUBLIC_SEARCH_BUDGETS.pageRows
+ ),
+ pages + 1
+ );
+ },
run: () => run,
bindRun: (value) => {
run = value;
@@ -175,6 +221,9 @@ function createSession(
model = value;
},
flags: () => ({ cancelled, failed, capped }),
+ cap: () => {
+ capped = true;
+ },
fail: () => {
failed = true;
},
@@ -293,12 +342,39 @@ export function subscribeFoodSearch(
): PublicRequest {
if (filters.some((filter) => 'search' in filter))
throw new Error('food_search_sample_required');
- return subscribeSearchSource(token, filters);
+ const session = sessionOf(token);
+ requireCurrent(session);
+ refreshChronological(session);
+ requireCurrent(session);
+ const selected = requireChronologicalSearchQuery(
+ filters,
+ session.continuation().snapshot().until
+ );
+ let window: ChronologicalWindow;
+ try {
+ window = session.continuation().begin();
+ } catch (error) {
+ if (
+ error instanceof Error &&
+ error.message === 'food_search_chronological_window_limit'
+ )
+ session.cap();
+ throw error;
+ }
+ try {
+ const request = subscribeSearchSource(token, selected, undefined, window);
+ session.trackChronological(request, window);
+ return request;
+ } catch (error) {
+ window.finish(false, 'partial');
+ throw error;
+ }
}
function subscribeSearchSource(
token: FoodSearchRun,
filters: readonly PublicFilter[],
- sampleSource?: string
+ sampleSource?: string,
+ chronologicalWindow?: ChronologicalWindow
): PublicRequest {
const session = sessionOf(token),
run = foodSearchRequestOwner(token);
@@ -315,6 +391,7 @@ function subscribeSearchSource(
if (!current(session)) return;
const head = createPublicHeadCandidate(proof);
if (!head || publicHeadSnapshot(head).kind !== 30402) return;
+ chronologicalWindow?.observe(head);
if (!session.remember(head)) cancelPublicRun(run);
},
sampleSource
@@ -354,6 +431,60 @@ export function sampleFoodSearch(
}
return Array.from(samples.keys());
}
+function refreshChronological(session: Session): void {
+ for (const [request, window] of session.chronological()) {
+ const scope = publicRequestScopeSnapshot(request);
+ if (scope.state === 'active') continue;
+ window.finish(
+ scope.result.sources.some(
+ (source) => source.candidates >= PUBLIC_QUERY_BUDGETS.requestedPerRelay
+ ),
+ scope.state === 'eose' && scope.result.coverage === 'bounded-eose'
+ ? 'bounded-eose'
+ : 'partial',
+ scope.result.sources.map((source) => ({
+ source: source.source,
+ saturated: source.candidates >= PUBLIC_QUERY_BUDGETS.requestedPerRelay,
+ eventIds: publicRunObservations(session.run()!, request)
+ .filter((row) => row.source === source.source && row.kind === 30402)
+ .map((row) => row.eventId)
+ }))
+ );
+ }
+}
+export function chronologicalFoodSearch(token: FoodSearchRun): PublicRequest {
+ const session = sessionOf(token);
+ requireCurrent(session);
+ refreshChronological(session);
+ requireCurrent(session);
+ return subscribeFoodSearch(
+ token,
+ chronologicalSearchQuery(session.continuation().snapshot().until)
+ );
+}
+export function showMoreFoodSearch(token: FoodSearchRun): void {
+ const session = sessionOf(token);
+ requireCurrent(session);
+ session.showMore();
+}
+export function searchOlderFoodSearch(
+ coordinator: FoodSearchCoordinator
+): FoodSearchRun {
+ const owner = coordinatorOf(coordinator),
+ previous = owner.current();
+ if (!previous || owner.closed()) throw new Error('food_search_inactive');
+ const session = sessionOf(previous);
+ const snapshot = foodSearchSnapshot(coordinator);
+ requireCurrent(session);
+ if (!snapshot?.available) throw new Error('food_search_unavailable');
+ const next = session.continuation().restart();
+ const token = beginFoodSearch(coordinator, session.query);
+ const successor = sessionOf(token);
+ requireCurrent(successor);
+ successor.bindContinuation(next);
+ chronologicalFoodSearch(token);
+ return token;
+}
export function foodSearchSnapshot(
coordinator: FoodSearchCoordinator
): SearchSnapshot<FoodSearchRun> | undefined {
@@ -377,6 +508,7 @@ export function foodSearchSnapshot(
}
}
}
+ refreshChronological(session);
const raw = model ? headResolutionSnapshot(model) : [];
const matched = model ? searchResolvedFood(model, session.query) : undefined;
const scopes = new Map<object, SearchScope>();
@@ -395,19 +527,28 @@ export function foodSearchSnapshot(
if (!current(session)) return undefined;
const sources = Array.from(scopes.values()),
flags = session.flags();
+ const refresh = searchRefreshState(
+ available,
+ run,
+ sources,
+ flags.cancelled,
+ flags.failed,
+ flags.capped
+ );
+ const continuation = session.continuation().snapshot(),
+ page = localSearchPage(
+ available && matched?.ok ? matched.rows : [],
+ session.pages()
+ );
return {
generation: token,
query: session.query,
- refresh: searchRefreshState(
- available,
- run,
- sources,
- flags.cancelled,
- flags.failed,
- flags.capped
- ),
+ refresh:
+ continuation.gap && refresh === 'bounded-eose' ? 'partial' : refresh,
available,
- rows: available && matched?.ok ? matched.rows : [],
+ rows: page.rows,
+ hasMore: page.hasMore,
+ continuation,
scopes: sources,
run,
definitiveAbsence: false
diff --git a/web/src/lib/catalog/search-state.ts b/web/src/lib/catalog/search-state.ts
@@ -1,3 +1,4 @@
+import type { ChronologicalProgress } from './continuation.ts';
import type {
publicRunSnapshot,
publicRequestScopeSnapshot
@@ -20,6 +21,8 @@ export type SearchSnapshot<Generation> = Readonly<{
refresh: SearchRefresh;
available: boolean;
rows: readonly HeadResolution[];
+ hasMore: boolean;
+ continuation: ChronologicalProgress;
scopes: readonly SearchScope[];
run: ReturnType<typeof publicRunSnapshot> | undefined;
definitiveAbsence: false;
diff --git a/web/src/lib/config/budgets.ts b/web/src/lib/config/budgets.ts
@@ -38,7 +38,8 @@ export const PUBLIC_RETENTION_BUDGETS = Object.freeze({
// Query text is public input. Bound both original and normalized UTF-8 copies.
export const PUBLIC_SEARCH_BUDGETS = Object.freeze({
queryBytes: 512,
- terms: 12
+ terms: 12,
+ pageRows: 20
});
// One NIP-50 round may select each of the three qualified sources separately;
diff --git a/web/src/lib/nostr/chronological-query.ts b/web/src/lib/nostr/chronological-query.ts
@@ -0,0 +1,43 @@
+import { PUBLIC_QUERY_BUDGETS } from '../config/budgets.ts';
+import type { PublicFilter } from './exports.ts';
+
+// NIP-01 until is inclusive. Never invent a cursor by subtracting a second.
+export function chronologicalSearchQuery(
+ until?: number
+): readonly PublicFilter[] {
+ if (until !== undefined && (!Number.isSafeInteger(until) || until < 0))
+ throw new Error('chronological_boundary_invalid');
+ return [
+ {
+ kinds: [30402],
+ limit: PUBLIC_QUERY_BUDGETS.requestedPerRelay,
+ ...(until === undefined ? {} : { until })
+ }
+ ];
+}
+// The coordinator accepts only its own observed boundary, never caller offsets
+// or a keyword-constrained chronological request. Return an independent copy.
+export function requireChronologicalSearchQuery(
+ filters: readonly PublicFilter[],
+ until?: number
+): readonly PublicFilter[] {
+ const expected = chronologicalSearchQuery(until),
+ filter = filters[0];
+ if (
+ !Array.isArray(filters) ||
+ filters.length !== 1 ||
+ !filter ||
+ 'search' in filter ||
+ 'q' in filter ||
+ 'since' in filter ||
+ 'authors' in filter ||
+ 'ids' in filter ||
+ !Array.isArray(filter.kinds) ||
+ filter.kinds.length !== 1 ||
+ filter.kinds[0] !== 30402 ||
+ filter.limit !== PUBLIC_QUERY_BUDGETS.requestedPerRelay ||
+ filter.until !== until
+ )
+ throw new Error('food_search_chronological_filter');
+ return expected;
+}
diff --git a/web/tests/integration/search-chronological.test.ts b/web/tests/integration/search-chronological.test.ts
@@ -0,0 +1,214 @@
+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,
+ closePublicRuntime
+} from '../../src/lib/runtime/public-runtime.ts';
+import {
+ createFoodSearchCoordinator,
+ beginFoodSearch,
+ subscribeFoodSearch,
+ foodSearchSnapshot,
+ cancelFoodSearch,
+ chronologicalFoodSearch,
+ showMoreFoodSearch,
+ searchOlderFoodSearch
+} from '../../src/lib/catalog/search-run.ts';
+
+await test('actual SDK chronological windows repeat the inclusive bucket, share lifecycle work and stop an honest gap', 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
+ ? query.authors === undefined
+ ? Array.from({ length: 200 }, () => previous)
+ : [current]
+ : [deletion];
+ for (const value of values)
+ socket.send(JSON.stringify(['EVENT', id, value]));
+ socket.send(JSON.stringify(['EOSE', id]));
+ if (filters.length === 1) 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);
+ const coordinator = createFoodSearchCoordinator(view, {
+ nowSeconds: () => base.created_at + 10
+ });
+ const generation = beginFoodSearch(coordinator, 'carrots');
+ subscribeFoodSearch(generation, [{ kinds: [30402], limit: 200 }]);
+ await sentBoth;
+ for (
+ let n = 0;
+ n < 100 && foodSearchSnapshot(coordinator)?.refresh !== 'bounded-eose';
+ n++
+ )
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ assert.equal(filters.length, 3);
+ const head = filters.find(
+ (q) => (q.kinds as number[])[0] === 30402 && q.authors !== undefined
+ )!;
+ 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 first = foodSearchSnapshot(coordinator)!;
+ assert.equal(first.continuation.until, previous.created_at);
+ assert.equal(first.continuation.gap, false);
+ const count = filters.length;
+ showMoreFoodSearch(generation);
+ assert.equal(filters.length, count);
+ chronologicalFoodSearch(generation);
+ for (
+ let n = 0;
+ n < 100 && !foodSearchSnapshot(coordinator)?.continuation.gap;
+ n++
+ )
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ const second = filters.filter((q) => q.authors === undefined);
+ assert.equal(second.length, 2);
+ assert.equal(second[1].until, previous.created_at);
+ assert.equal(second[1].limit, 200);
+ assert.equal('search' in second[1], false);
+ const snapshot = foodSearchSnapshot(coordinator)!;
+ assert.equal(snapshot.continuation.gap, true);
+ assert.equal(snapshot.continuation.coverage, 'partial');
+ assert.throws(
+ () => searchOlderFoodSearch(coordinator),
+ /food_search_chronological_gap/
+ );
+ assert.equal(filters.length, 4);
+ assert.equal(snapshot.query, 'carrots');
+ assert.equal(snapshot.refresh, 'partial');
+ assert.equal(snapshot.rows.length, 0);
+ assert.equal(snapshot.definitiveAbsence, false);
+ assert.equal(snapshot.run?.ingress.deliveries, 402);
+ assert.equal(snapshot.run?.activeRequests, 0);
+ assert.equal(snapshot.scopes.length, 4);
+ cancelFoodSearch(generation);
+ } 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/chronological-query.test.ts b/web/tests/unit/chronological-query.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import {
+ chronologicalSearchQuery,
+ requireChronologicalSearchQuery
+} from '../../src/lib/nostr/chronological-query.ts';
+
+describe('bounded chronological queries', () => {
+ it('requests a detached kind30402 window of200 without keyword or tag constraints', () => {
+ expect(chronologicalSearchQuery()).toEqual([
+ { kinds: [30402], limit: 200 }
+ ]);
+ expect(chronologicalSearchQuery(123)).toEqual([
+ { kinds: [30402], limit: 200, until: 123 }
+ ]);
+ const one = chronologicalSearchQuery();
+ one[0].kinds![0] = 5;
+ expect(chronologicalSearchQuery()[0].kinds).toEqual([30402]);
+ });
+ it('preserves zero/inclusive safe integer boundaries and refuses unsupported time', () => {
+ expect(chronologicalSearchQuery(0)[0].until).toBe(0);
+ for (const value of [-1, 1.5, NaN, Infinity, Number.MAX_SAFE_INTEGER + 1])
+ expect(() => chronologicalSearchQuery(value)).toThrow(
+ 'chronological_boundary_invalid'
+ );
+ });
+ it('refuses externally supplied skip cursors and extra keyword constraints', () => {
+ expect(
+ requireChronologicalSearchQuery(
+ [{ limit: 200, kinds: [30402], until: 123 }],
+ 123
+ )
+ ).toEqual(chronologicalSearchQuery(123));
+ for (const value of [
+ [],
+ [{ kinds: [30402], limit: 201 }],
+ [{ kinds: [5], limit: 200 }],
+ [{ kinds: [30402], limit: 200, search: 'carrots' }],
+ [{ kinds: [30402], limit: 200, since: 1 }],
+ [{ kinds: [30402], limit: 200, until: 122 }]
+ ])
+ expect(() => requireChronologicalSearchQuery(value, 123)).toThrow(
+ 'food_search_chronological_filter'
+ );
+ });
+});
diff --git a/web/tests/unit/continuation.test.ts b/web/tests/unit/continuation.test.ts
@@ -0,0 +1,183 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { finalizeEvent } from 'applesauce-core/helpers';
+import { verifyEnvelope } from '../../src/lib/nostr/verified-envelope.ts';
+import {
+ createPublicHeadCandidate,
+ publicHeadSnapshot
+} from '../../src/lib/catalog/heads.ts';
+import {
+ createChronologicalContinuation,
+ localSearchPage
+} from '../../src/lib/catalog/continuation.ts';
+const keys: Uint8Array[] = [];
+afterEach(() => {
+ for (const key of keys.splice(0)) key.fill(0);
+});
+function head(time: number, name: string, kind = 30402) {
+ const key = crypto.getRandomValues(new Uint8Array(32));
+ keys.push(key);
+ const proof = verifyEnvelope(
+ JSON.stringify(
+ finalizeEvent(
+ { kind, created_at: time, tags: [['d', name]], content: '' },
+ key
+ )
+ )
+ );
+ if (!proof.ok) throw Error('fixture verification');
+ const candidate = createPublicHeadCandidate(proof.value);
+ if (!candidate) throw Error('fixture head');
+ return candidate;
+}
+describe('inclusive chronological continuation and local pages', () => {
+ it('does not cross a saturated source bucket because another source returned an older item', () => {
+ const owner = createChronologicalContinuation(),
+ a = head(100, 'a'),
+ b = head(99, 'b');
+ const first = owner.begin();
+ first.observe(a);
+ first.observe(b);
+ first.finish(true, 'bounded-eose', [
+ { source: 'one', saturated: true, eventIds: [publicHeadSnapshot(a).id] },
+ { source: 'two', saturated: false, eventIds: [publicHeadSnapshot(b).id] }
+ ]);
+ expect(owner.snapshot().until).toBe(100);
+ const next = owner.begin();
+ next.observe(a);
+ next.observe(b);
+ next.finish(true, 'bounded-eose', [
+ { source: 'one', saturated: true, eventIds: [publicHeadSnapshot(a).id] },
+ { source: 'two', saturated: false, eventIds: [publicHeadSnapshot(b).id] }
+ ]);
+ expect(owner.snapshot()).toMatchObject({
+ until: 100,
+ gap: true,
+ coverage: 'partial'
+ });
+ });
+
+ it('repeats the observed boundary and stops a repeated saturated equal-time bucket with an explicit gap', () => {
+ const owner = createChronologicalContinuation(),
+ item = head(100, 'a');
+ const first = owner.begin();
+ first.observe(item);
+ first.observe(item);
+ first.finish(true, 'bounded-eose');
+ expect(owner.snapshot()).toMatchObject({
+ until: 100,
+ windows: 1,
+ observed: 1,
+ gap: false,
+ definitiveAbsence: false
+ });
+ const next = owner.begin();
+ expect(next.until).toBe(100);
+ next.observe(item);
+ next.finish(true, 'bounded-eose');
+ expect(owner.snapshot()).toMatchObject({
+ until: 100,
+ gap: true,
+ coverage: 'partial'
+ });
+ expect(() => owner.restart()).toThrow('food_search_chronological_gap');
+ });
+ it('accepts new boundary IDs as progress and advances only to an actually observed older timestamp', () => {
+ const owner = createChronologicalContinuation(),
+ a = head(100, 'a'),
+ b = head(100, 'b'),
+ c = head(99, 'c');
+ const first = owner.begin();
+ first.observe(a);
+ first.finish(true, 'bounded-eose');
+ const next = owner.begin();
+ next.observe(a);
+ next.observe(b);
+ next.finish(true, 'bounded-eose');
+ expect(owner.snapshot()).toMatchObject({
+ until: 100,
+ gap: false,
+ windows: 2
+ });
+ expect(() => owner.begin()).toThrow(
+ 'food_search_chronological_window_limit'
+ );
+ const older = owner.restart(),
+ window = older.begin();
+ expect(window.until).toBe(100);
+ window.observe(c);
+ window.finish(false, 'bounded-eose');
+ expect(older.snapshot()).toMatchObject({
+ until: 99,
+ windows: 1,
+ gap: false
+ });
+ });
+ it('ignores wrong-kind/out-of-bound/forged candidates for cursor purposes and preserves partial coverage', () => {
+ const owner = createChronologicalContinuation(),
+ first = owner.begin();
+ first.observe(head(10, 'a'));
+ first.finish(false, 'partial');
+ const next = owner.begin();
+ next.observe(head(11, 'future'));
+ next.observe(head(0, 'profile', 0));
+ expect(() => next.observe({} as ReturnType<typeof head>)).toThrow(
+ 'public_head_invalid'
+ );
+ next.finish(true, 'bounded-eose');
+ expect(owner.snapshot()).toMatchObject({
+ until: 10,
+ gap: true,
+ coverage: 'partial'
+ });
+ });
+ it('does not invent an older boundary for an empty window, and refuses parallel windows', () => {
+ const owner = createChronologicalContinuation(),
+ first = owner.begin();
+ expect(() => owner.begin()).toThrow('food_search_chronological_pending');
+ first.finish(false, 'bounded-eose');
+ expect(owner.snapshot().until).toBeUndefined();
+ expect(() => owner.restart()).toThrow(
+ 'food_search_chronological_boundary_missing'
+ );
+ expect(() => first.observe(head(0, 'late'))).toThrow(
+ 'food_search_chronological_window_closed'
+ );
+ });
+ it('restarts with known boundary evidence without mutating the predecessor or erasing partial coverage', () => {
+ const owner = createChronologicalContinuation(),
+ item = head(0, 'zero'),
+ first = owner.begin();
+ first.observe(item);
+ first.finish(true, 'partial');
+ const next = owner.restart(),
+ window = next.begin();
+ window.observe(item);
+ window.finish(true, 'bounded-eose');
+ expect(next.snapshot()).toMatchObject({
+ until: 0,
+ gap: true,
+ coverage: 'partial'
+ });
+ expect(owner.snapshot()).toMatchObject({ windows: 1, gap: false });
+ const copy = owner.snapshot();
+ Object.assign(copy, { until: 100 });
+ expect(owner.snapshot().until).toBe(0);
+ });
+ it('shows20 more local rows per page without changing order or creating network work', () => {
+ const rows = Array.from({ length: 45 }, (_, n) => n);
+ expect(localSearchPage(rows, 1)).toEqual({
+ rows: rows.slice(0, 20),
+ hasMore: true
+ });
+ expect(localSearchPage(rows, 2)).toEqual({
+ rows: rows.slice(0, 40),
+ hasMore: true
+ });
+ expect(localSearchPage(rows, 3)).toEqual({ rows, hasMore: false });
+ for (const value of [0, -1, 1.5, NaN, 101])
+ expect(() => localSearchPage(rows, value)).toThrow(
+ 'food_search_local_page_invalid'
+ );
+ expect(rows).toHaveLength(45);
+ });
+});
diff --git a/web/tests/unit/search-run.test.ts b/web/tests/unit/search-run.test.ts
@@ -33,7 +33,7 @@ const corpus = JSON.parse(
const base = JSON.parse(
corpus.vectors.find((v) => v.id.endsWith('_032'))!.signed_wires.previous
) as { tags: string[][]; content: string; created_at: number };
-async function fixture(nip50 = false) {
+async function fixture(nip50 = false, sourceCount = 1) {
const { RelayPool } = await import('applesauce-relay/pool');
const { validateRelayPolicy } =
await import('../../src/lib/config/relays.ts');
@@ -71,7 +71,12 @@ async function fixture(nip50 = false) {
const policy = validateRelayPolicy(
JSON.stringify({
schemaVersion: 1,
- public: [{ origin, read: true, write: false, nip50 }],
+ public: Array.from({ length: sourceCount }, (_, n) => ({
+ origin: n === 0 ? origin : `wss://source${n}.example.org`,
+ read: true,
+ write: false,
+ nip50
+ })),
inbox: [],
postingEnabled: false,
messagingEnabled: false,
@@ -139,6 +144,12 @@ async function fixture(nip50 = false) {
const emit = (i: number, event: ReturnType<typeof wire>) =>
channels[i].emit({ type: 'EVENT', id: 'fixture', from: origin, event });
return {
+ eose: (i: number) => {
+ const selected = provider.mock.calls[i][0];
+ if (!Array.isArray(selected)) throw new Error('fixture source array');
+ for (const source of selected)
+ channels[i].emit({ type: 'EOSE', id: 'fixture', from: String(source) });
+ },
coordinator,
view,
wallClock,
@@ -163,6 +174,101 @@ async function fixture(nip50 = false) {
};
}
describe('finite food search coordination (isolated SDK provider, not qualification)', () => {
+ it('reserves at most two chronological windows even after clean EOSE', async () => {
+ const f = await fixture(),
+ token = f.begin('');
+ for (let n = 0; n < 2; n++) {
+ search.subscribeFoodSearch(token, [{ kinds: [30402], limit: 200 }]);
+ f.channels[n].emit({ type: 'EOSE', id: 'fixture', from: f.origin });
+ }
+ expect(() =>
+ search.subscribeFoodSearch(token, [{ kinds: [30402], limit: 200 }])
+ ).toThrow('food_search_chronological_window_limit');
+ expect(f.provider).toHaveBeenCalledTimes(2);
+ expect(f.snapshot().definitiveAbsence).toBe(false);
+ });
+
+ it('keeps a saturated source boundary even when another readable source returns an older head', async () => {
+ const f = await fixture(false, 2),
+ token = f.begin('carrots');
+ search.subscribeFoodSearch(token, [{ kinds: [30402], limit: 200 }]);
+ const item = f.wire('Carrots', 'saturated', base.created_at),
+ older = f.wire('Carrots', 'other', base.created_at - 1);
+ for (let n = 0; n < 200; n++) f.emit(0, item);
+ f.channels[0].emit({
+ type: 'EVENT',
+ id: 'fixture',
+ from: 'wss://source1.example.org',
+ event: older
+ });
+ f.eose(0);
+ expect(f.snapshot().continuation.until).toBe(base.created_at);
+ search.chronologicalFoodSearch(token);
+ expect(f.provider.mock.calls.at(-1)![1]).toEqual([
+ { kinds: [30402], limit: 200, until: base.created_at }
+ ]);
+ });
+ it('uses only chronological verified times for the inclusive cursor despite earlier relevance samples', async () => {
+ const f = await fixture(true),
+ token = f.begin('carrots');
+ search.sampleFoodSearch(token);
+ f.emit(0, f.wire('Carrots', 'sample', base.created_at - 100));
+ f.channels[0].emit({ type: 'EOSE', id: 'sample', from: f.origin });
+ const request = search.chronologicalFoodSearch(token);
+ f.emit(1, f.wire('Carrots', 'chronological', base.created_at));
+ f.channels[1].emit({ type: 'EOSE', id: 'chronological', from: f.origin });
+ expect(requests.publicRequestScopeSnapshot(request).state).toBe('eose');
+ expect(f.snapshot().continuation.until).toBe(base.created_at);
+ search.chronologicalFoodSearch(token);
+ expect(f.provider.mock.calls.at(-1)![1]).toEqual([
+ { kinds: [30402], limit: 200, until: base.created_at }
+ ]);
+ expect(() =>
+ search.subscribeFoodSearch(token, [
+ { kinds: [30402], limit: 200, until: base.created_at - 1 }
+ ])
+ ).toThrow('food_search_chronological_filter');
+ });
+ it('shows another local20row page without opening a source and keeps the current generation', async () => {
+ const f = await fixture(),
+ heads = Array.from({ length: 26 }, (_, n) =>
+ f.head(f.wire('Carrots', String(n)))
+ );
+ const token = f.begin('carrots', heads),
+ first = f.snapshot();
+ expect(first.rows).toHaveLength(20);
+ expect(first.hasMore).toBe(true);
+ const count = f.provider.mock.calls.length;
+ search.showMoreFoodSearch(token);
+ expect(f.provider).toHaveBeenCalledTimes(count);
+ const next = f.snapshot();
+ expect(next.generation).toBe(token);
+ expect(next.rows).toHaveLength(26);
+ expect(next.hasMore).toBe(false);
+ });
+ it('starts an explicit older successor run at the same inclusive boundary and preserves known results', async () => {
+ const f = await fixture(),
+ token = f.begin('carrots');
+ search.chronologicalFoodSearch(token);
+ f.emit(0, f.wire());
+ f.channels[0].emit({ type: 'EOSE', id: 'chronological', from: f.origin });
+ const first = f.snapshot();
+ expect(first.continuation.until).toBe(base.created_at);
+ const older = search.searchOlderFoodSearch(f.coordinator);
+ expect(older).not.toBe(token);
+ expect(() => search.showMoreFoodSearch(token)).toThrow(
+ 'food_search_superseded'
+ );
+ expect(f.provider.mock.calls.at(-1)![1]).toEqual([
+ { kinds: [30402], limit: 200, until: base.created_at }
+ ]);
+ expect(f.snapshot()).toMatchObject({
+ query: 'carrots',
+ generation: older,
+ definitiveAbsence: false
+ });
+ expect(f.snapshot().rows).toHaveLength(1);
+ });
it('requires the one-round sampler for relevance filters even after a completed sample', async () => {
const f = await fixture(true),
token = f.begin('carrots');
@@ -267,35 +373,37 @@ describe('finite food search coordination (isolated SDK provider, not qualificat
})
).toThrow('food_search_clock_changed');
});
- it('bounds primary scope history to the approved source-round and chronological-window maximum', async () => {
- const f = await fixture(),
- token = f.begin('');
- for (let i = 0; i < 5; i++) {
- search.subscribeFoodSearch(token, [{ kinds: [30402], limit: 200 }]);
- f.channels[i].emit({ type: 'EOSE', id: 'fixture', from: f.origin });
+ it('bounds primary scope history to one three-source sample round plus two chronological windows', async () => {
+ const f = await fixture(true, 3),
+ token = f.begin('carrots');
+ search.sampleFoodSearch(token);
+ for (let i = 0; i < 3; i++) f.eose(i);
+ for (let i = 0; i < 2; i++) {
+ search.chronologicalFoodSearch(token);
+ f.eose(i + 3);
}
- expect(() =>
- search.subscribeFoodSearch(token, [{ kinds: [30402], limit: 200 }])
- ).toThrow('food_search_primary_limit');
+ expect(() => search.chronologicalFoodSearch(token)).toThrow(
+ 'food_search_chronological_window_limit'
+ );
expect(f.channels).toHaveLength(5);
expect(f.snapshot().scopes).toHaveLength(5);
expect(f.snapshot().refresh).toBe('limit');
});
- it('charges failed primary attempts before provider effects without unlimited retries', async () => {
- const f = await fixture(),
- token = f.begin('');
+ it('charges failed sample and chronological attempts before provider effects without unlimited retries', async () => {
+ const f = await fixture(true, 3),
+ token = f.begin('carrots');
f.provider.mockImplementation(() => {
throw new Error('isolated provider failure');
});
- for (let i = 0; i < 5; i++) {
- expect(() =>
- search.subscribeFoodSearch(token, [{ kinds: [30402], limit: 200 }])
- ).toThrow('food_search_request_failed');
- }
+ expect(search.sampleFoodSearch(token)).toEqual([]);
+ for (let i = 0; i < 2; i++)
+ expect(() => search.chronologicalFoodSearch(token)).toThrow(
+ 'food_search_request_failed'
+ );
expect(f.provider).toHaveBeenCalledTimes(5);
- expect(() =>
- search.subscribeFoodSearch(token, [{ kinds: [30402], limit: 200 }])
- ).toThrow('food_search_primary_limit');
+ expect(() => search.chronologicalFoodSearch(token)).toThrow(
+ 'food_search_chronological_window_limit'
+ );
expect(f.provider).toHaveBeenCalledTimes(5);
expect(f.channels).toHaveLength(0);
expect(f.snapshot().scopes).toHaveLength(0);
@@ -365,14 +473,14 @@ describe('finite food search coordination (isolated SDK provider, not qualificat
expect(f.snapshot().query).toBe('celery');
});
it('shares all six scope slots with cached latest and deletion lookups', async () => {
- const f = await fixture(),
- token = f.begin('', [f.head()]);
- for (let i = 0; i < 4; i++)
- search.subscribeFoodSearch(token, [{ kinds: [30402], limit: 200 }]);
+ const f = await fixture(true, 3),
+ token = f.begin('carrots', [f.head()]);
+ search.sampleFoodSearch(token);
+ search.chronologicalFoodSearch(token);
expect(f.snapshot().run?.activeRequests).toBe(6);
expect(() =>
search.subscribeFoodSearch(token, [{ kinds: [30402], limit: 200 }])
- ).toThrow('food_search_request_failed');
+ ).toThrow('food_search_chronological_pending');
expect(f.snapshot().run?.activeRequests).toBe(6);
search.cancelFoodSearch(token);
expect(f.channels.every((c) => c.stopped())).toBe(true);