commit cfdddcfb578b2a71d928b3abeaf683fa0547464c
parent 554afb6602c34c4335f9209e89488f0d8f4f0b14
Author: triesap <tyson@radroots.org>
Date: Tue, 6 Oct 2026 09:46:25 +0000
availability: Record exact source observations separately (HCP-031)
- Record verified public event and source tuples before store deduplication
- Preserve bounded partial outcomes without relay prose or absence claims
- Bind independent acceptance to executed checks and preserved native inputs
- Retain qualification limits and continue the authorized RCL sequence
Diffstat:
6 files changed, 974 insertions(+), 4 deletions(-)
diff --git a/web/src/lib/catalog/observations.ts b/web/src/lib/catalog/observations.ts
@@ -0,0 +1,154 @@
+import { PUBLIC_INGRESS_BUDGETS } from '../config/budgets.ts';
+import { publicRelayTargets, type RelayPolicy } from '../config/relays.ts';
+import {
+ verifiedEnvelopeSnapshot,
+ type VerifiedEnvelope
+} from '../nostr/verified-envelope.ts';
+import { isPublicEnvelopeKind } from '../nostr/public-store.ts';
+declare const journalBrand: unique symbol;
+declare const contextBrand: unique symbol;
+export type ObservationJournal = Readonly<{ readonly [journalBrand]: true }>;
+export type ObservationContext = Readonly<{ readonly [contextBrand]: true }>;
+export type PublicObservation = Readonly<{
+ eventId: string;
+ source: string;
+ kind: number;
+}>;
+interface Owner {
+ readonly origins: () => readonly string[];
+ readonly context: () => ObservationContext;
+ readonly record: (
+ context: ObservationContext,
+ source: string,
+ event: VerifiedEnvelope
+ ) => boolean;
+ readonly exact: (
+ context: ObservationContext,
+ eventId: string,
+ source: string
+ ) => boolean;
+ readonly rows: (context: ObservationContext) => readonly PublicObservation[];
+ readonly stats: () => Readonly<{ rows: number; closed: boolean }>;
+ readonly close: () => void;
+}
+const owners = new WeakMap<ObservationJournal, Owner>();
+// One journal belongs to a public run; request tokens are local identities,
+// never relay-supplied IDs. No SDK seen-relay metadata or receipt inference.
+export function createObservationJournal(
+ policy: RelayPolicy
+): ObservationJournal {
+ const origins = publicRelayTargets(policy, 'read');
+ let contexts = new WeakMap<ObservationContext, Map<string, string>>();
+ let rows = 0;
+ let closed = false;
+ function contextRows(context: ObservationContext): Map<string, string> {
+ const result = contexts.get(context);
+ if (!result) throw new Error('observation_context_invalid');
+ return result;
+ }
+ const owner: Owner = {
+ origins: () => [...origins],
+ context() {
+ if (closed) throw new Error('observations_closed');
+ const token = Object.freeze({}) as ObservationContext;
+ contexts.set(token, new Map());
+ return token;
+ },
+ record(context, source, event) {
+ if (closed) return false;
+ const records = contextRows(context);
+ if (!origins.includes(source)) return false;
+ const snapshot = verifiedEnvelopeSnapshot(event);
+ if (!snapshot || !isPublicEnvelopeKind(snapshot.kind)) return false;
+ const key = source + '\0' + snapshot.id;
+ if (records.has(key)) return true;
+ if (rows >= PUBLIC_INGRESS_BUDGETS.deliveries) return false;
+ // Retain only exact public ID/kind/source. Private/decrypted metadata and
+ // full payloads never enter this bounded observation cache.
+ records.set(
+ key,
+ JSON.stringify({
+ eventId: snapshot.id,
+ source: source,
+ kind: snapshot.kind
+ })
+ );
+ rows++;
+ return true;
+ },
+ exact(context, eventId, source) {
+ if (closed) return false;
+ const records = contextRows(context);
+ return (
+ typeof eventId === 'string' &&
+ /^[0-9a-f]{64}$/u.test(eventId) &&
+ origins.includes(source) &&
+ records.has(source + '\0' + eventId)
+ );
+ },
+ rows(context) {
+ if (closed) return [];
+ return Array.from(
+ contextRows(context).values(),
+ (raw) => JSON.parse(raw) as PublicObservation
+ );
+ },
+ stats() {
+ return Object.freeze({ rows: rows, closed: closed });
+ },
+ close() {
+ closed = true;
+ contexts = new WeakMap();
+ rows = 0;
+ }
+ };
+ const token = Object.freeze({}) as ObservationJournal;
+ owners.set(token, owner);
+ return token;
+}
+function ownerOf(journal: ObservationJournal): Owner {
+ const owner = owners.get(journal);
+ if (!owner) throw new Error('observation_journal_invalid');
+ return owner;
+}
+export function createObservationContext(
+ journal: ObservationJournal
+): ObservationContext {
+ return ownerOf(journal).context();
+}
+export function recordPublicObservation(
+ journal: ObservationJournal,
+ context: ObservationContext,
+ source: string,
+ event: VerifiedEnvelope
+): boolean {
+ return ownerOf(journal).record(context, source, event);
+}
+export function exactPublicObservation(
+ journal: ObservationJournal,
+ context: ObservationContext,
+ eventId: string,
+ source: string
+): boolean {
+ return ownerOf(journal).exact(context, eventId, source);
+}
+export function publicObservations(
+ journal: ObservationJournal,
+ context: ObservationContext
+): readonly PublicObservation[] {
+ return ownerOf(journal).rows(context);
+}
+export function observationJournalStats(
+ journal: ObservationJournal
+): Readonly<{ rows: number; closed: boolean }> {
+ return ownerOf(journal).stats();
+}
+export function closeObservationJournal(journal: ObservationJournal): void {
+ ownerOf(journal).close();
+}
+
+export function observationSourceOrigins(
+ journal: ObservationJournal
+): readonly string[] {
+ return ownerOf(journal).origins();
+}
diff --git a/web/src/lib/nostr/ingress.ts b/web/src/lib/nostr/ingress.ts
@@ -10,8 +10,8 @@ import {
declare const ingressOwner: unique symbol;
export type PublicIngress = Readonly<{ readonly [ingressOwner]: true }>;
export type IngressResult =
- | Readonly<{ status: 'accepted'; value: VerifiedEnvelope }>
- | Readonly<{ status: 'duplicate' | 'rejected' | 'limit' }>;
+ | Readonly<{ status: 'accepted' | 'duplicate'; value: VerifiedEnvelope }>
+ | Readonly<{ status: 'rejected' | 'limit' }>;
export type IngressStats = Readonly<{
deliveries: number;
chargedBytes: number;
@@ -182,7 +182,9 @@ export function createPublicIngress(): PublicIngress {
if (!result.ok) return { status: 'rejected' };
const event = verifiedEnvelopeSnapshot(result.value);
if (!event) return { status: 'rejected' };
- if (seen.has(event.id)) return { status: 'duplicate' };
+ // Dedup does not erase freshly verified per-source observation proof.
+ if (seen.has(event.id))
+ return { status: 'duplicate', value: result.value };
seen.set(event.id, true);
return { status: 'accepted', value: result.value };
} finally {
diff --git a/web/src/lib/nostr/public-store.ts b/web/src/lib/nostr/public-store.ts
@@ -55,6 +55,10 @@ const options: Readonly<EventStoreOptions> & {
keepExpired: true,
verifyEvent: verifyStoredEvent
};
+// The same approved inventory gates public source observations and storage.
+export function isPublicEnvelopeKind(kind: unknown): kind is number {
+ return typeof kind === 'number' && [0, 5, 10050, 30402].includes(kind);
+}
// Import/SSR is inert. The private SDK instance and mutable verifier setter are
// never exposed; acquisition accepts no caller options or private session state.
@@ -75,7 +79,7 @@ export function getPublicStore(): PublicStore | undefined {
if (!snapshot) return 'rejected';
// This application's approved public inventory. Private wrappers, inner
// plaintext and connection AUTH belong to separate owners, never here.
- if (![0, 5, 10050, 30402].includes(snapshot.kind)) return 'not_public';
+ if (!isPublicEnvelopeKind(snapshot.kind)) return 'not_public';
const event = signedFields(snapshot);
const sanitized = verifyEnvelope(JSON.stringify(event));
if (!sanitized.ok) return 'rejected';
diff --git a/web/src/lib/nostr/request-result.ts b/web/src/lib/nostr/request-result.ts
@@ -0,0 +1,214 @@
+import { PUBLIC_INGRESS_BUDGETS } from '../config/budgets.ts';
+import { publicRelayTargets, type RelayPolicy } from '../config/relays.ts';
+import {
+ createObservationContext,
+ recordPublicObservation,
+ observationSourceOrigins,
+ type ObservationJournal,
+ type ObservationContext
+} from '../catalog/observations.ts';
+import {
+ admitPublicEvent,
+ publicIngressStats,
+ type PublicIngress
+} from './ingress.ts';
+import {
+ verifiedEnvelopeSnapshot,
+ type VerifiedEnvelope
+} from './verified-envelope.ts';
+import { isPublicEnvelopeKind } from './public-store.ts';
+import type { PublicPoolMessage } from './exports.ts';
+declare const requestBrand: unique symbol;
+export type PublicRequestResult = Readonly<{ readonly [requestBrand]: true }>;
+export type SourceState =
+ 'pending' | 'eose' | 'closed' | 'error' | 'limit' | 'cancelled';
+export type SourceOutcome = Readonly<{
+ source: string;
+ state: SourceState;
+ candidates: number;
+ accepted: number;
+ duplicates: number;
+ rejected: number;
+}>;
+export type RequestSnapshot = Readonly<{
+ context: ObservationContext;
+ sources: readonly SourceOutcome[];
+ coverage: 'bounded-eose' | 'partial';
+ definitiveAbsence: false;
+ inactive: boolean;
+}>;
+export type RequestMessageResult =
+ | Readonly<{ status: 'accepted' | 'duplicate'; value: VerifiedEnvelope }>
+ | Readonly<{
+ status:
+ | 'rejected'
+ | 'limit'
+ | 'not_public'
+ | 'source_unknown'
+ | 'inactive'
+ | 'control';
+ }>;
+interface Owner {
+ readonly handle: (message: PublicPoolMessage) => RequestMessageResult;
+ readonly snapshot: () => RequestSnapshot;
+ readonly dispose: () => void;
+}
+const owners = new WeakMap<PublicRequestResult, Owner>();
+const runIngress = new WeakMap<ObservationJournal, PublicIngress>();
+// Scalar state remains inside its own closure; unknown Map-returned records
+// are never treated as mutable DOM/model receivers by the source guard.
+function sourceOwner(source: string) {
+ let state: SourceState = 'pending';
+ let candidates = 0;
+ let accepted = 0;
+ let duplicates = 0;
+ let rejected = 0;
+ return {
+ state: () => state,
+ candidate() {
+ candidates = Math.min(PUBLIC_INGRESS_BUDGETS.deliveries, candidates + 1);
+ },
+ reject() {
+ rejected = Math.min(PUBLIC_INGRESS_BUDGETS.deliveries, rejected + 1);
+ },
+ admit(duplicate: boolean) {
+ if (duplicate) duplicates++;
+ else accepted++;
+ },
+ control(next: 'eose' | 'error' | 'closed' | 'limit') {
+ if (next === 'limit') state = 'limit';
+ else if (next === 'eose') {
+ if (state === 'pending') state = 'eose';
+ } else if (state !== 'limit' && state !== 'cancelled') state = next;
+ },
+ cancel() {
+ if (state === 'pending') state = 'cancelled';
+ },
+ snapshot(): SourceOutcome {
+ return {
+ source: source,
+ state: state,
+ candidates: candidates,
+ accepted: accepted,
+ duplicates: duplicates,
+ rejected: rejected
+ };
+ }
+ };
+}
+
+// Pure decoded-SDK adapter. Network callbacks bind this opaque logical request;
+// HCP032 owns actual deadline/concurrency/generation and browser composition.
+export function createPublicRequestResult(
+ policy: RelayPolicy,
+ ingress: PublicIngress,
+ journal: ObservationJournal
+): PublicRequestResult {
+ publicIngressStats(ingress);
+ const origins = publicRelayTargets(policy, 'read');
+ const expected = observationSourceOrigins(journal);
+ if (
+ origins.length !== expected.length ||
+ !origins.every((origin, index) => origin === expected[index])
+ )
+ throw new Error('request_observation_policy_changed');
+ const priorIngress = runIngress.get(journal);
+ if (priorIngress && priorIngress !== ingress)
+ throw new Error('public_request_ingress_changed');
+ const context = createObservationContext(journal);
+ runIngress.set(journal, ingress);
+ const sources = new Map<string, ReturnType<typeof sourceOwner>>();
+ for (const source of origins) sources.set(source, sourceOwner(source));
+ let inactive = false;
+ const owner: Owner = {
+ handle(message) {
+ if (inactive) return { status: 'inactive' };
+ // Pinned SDK normalized relay URLs may carry the origin's sole trailing
+ // slash. Match only the two exact spellings of an already approved origin.
+ const origin = origins.find(
+ (value) => message.from === value || message.from === value + '/'
+ );
+ const source = origin === undefined ? undefined : sources.get(origin);
+ if (message.type === 'EVENT') {
+ const admitted = admitPublicEvent(ingress, message.event);
+ if (!source || origin === undefined)
+ return { status: 'source_unknown' };
+ source.candidate();
+ if (admitted.status === 'limit') {
+ source.control('limit');
+ return { status: 'limit' };
+ }
+ if (admitted.status === 'rejected') {
+ source.reject();
+ return { status: 'rejected' };
+ }
+ if (source.state() !== 'pending') {
+ source.reject();
+ return { status: 'inactive' };
+ }
+ if (!('value' in admitted)) return { status: 'rejected' };
+ const event = verifiedEnvelopeSnapshot(admitted.value);
+ if (!event || !isPublicEnvelopeKind(event.kind)) {
+ source.reject();
+ return { status: 'not_public' };
+ }
+ if (
+ !recordPublicObservation(journal, context, origin, admitted.value)
+ ) {
+ source.control('limit');
+ return { status: 'limit' };
+ }
+ source.admit(admitted.status === 'duplicate');
+ // Record exact source evidence BEFORE any caller inserts/deduplicates into
+ // EventStore. Only verified proof leaves this boundary, never SDK metadata.
+ return admitted;
+ }
+ if (!source) return { status: 'source_unknown' };
+ if (message.type === 'EOSE') source.control('eose');
+ else if (message.type === 'ERROR') source.control('error');
+ else if (message.type === 'CLOSED') source.control('closed');
+ // Deliberately do not read message.reason, message.error, filters or IDs.
+ return { status: 'control' };
+ },
+ snapshot() {
+ const outcomes = Array.from(sources.values(), (row) => row.snapshot());
+ const complete =
+ outcomes.length > 0 &&
+ outcomes.every((row) => row.state === 'eose' && row.rejected === 0);
+ return {
+ context: context,
+ sources: outcomes,
+ coverage: complete ? 'bounded-eose' : 'partial',
+ definitiveAbsence: false,
+ inactive: inactive
+ };
+ },
+ dispose() {
+ if (inactive) return;
+ inactive = true;
+ for (const row of sources.values()) row.cancel();
+ }
+ };
+ const token = Object.freeze({}) as PublicRequestResult;
+ owners.set(token, owner);
+ return token;
+}
+function ownerOf(token: PublicRequestResult): Owner {
+ const owner = owners.get(token);
+ if (!owner) throw new Error('public_request_result_invalid');
+ return owner;
+}
+export function handlePublicRequestMessage(
+ owner: PublicRequestResult,
+ message: PublicPoolMessage
+): RequestMessageResult {
+ return ownerOf(owner).handle(message);
+}
+export function publicRequestSnapshot(
+ owner: PublicRequestResult
+): RequestSnapshot {
+ return ownerOf(owner).snapshot();
+}
+export function disposePublicRequestResult(owner: PublicRequestResult): void {
+ ownerOf(owner).dispose();
+}
diff --git a/web/tests/integration/source-observations.test.ts b/web/tests/integration/source-observations.test.ts
@@ -0,0 +1,194 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import { readFile } from 'node:fs/promises';
+import WebSocket, { WebSocketServer } from 'ws';
+import { validateRelayPolicy } from '../../src/lib/config/relays.ts';
+import {
+ getPublicPool,
+ subscribePublicPool,
+ closePublicPool
+} from '../../src/lib/nostr/public-pool.ts';
+import {
+ getPublicStore,
+ insertPublicEnvelope,
+ closePublicStore,
+ publicStoreEnvelope
+} from '../../src/lib/nostr/public-store.ts';
+import {
+ createPublicIngress,
+ publicIngressStats
+} from '../../src/lib/nostr/ingress.ts';
+import {
+ createObservationJournal,
+ publicObservations,
+ exactPublicObservation
+} from '../../src/lib/catalog/observations.ts';
+import {
+ createPublicRequestResult,
+ handlePublicRequestMessage,
+ publicRequestSnapshot,
+ disposePublicRequestResult
+} from '../../src/lib/nostr/request-result.ts';
+await test('actual SDK sources retain exact observations before store dedup and sanitize partial outcomes', 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 wires = corpus.vectors.find((v) => v.id.endsWith('_032'))!.signed_wires;
+ const current = JSON.parse(wires.current) as { id: string; sig: string };
+ const previous = JSON.parse(wires.previous) as { id: string };
+ const origins = ['wss://one.example.org', 'wss://two.example.org'];
+ const servers = origins.map(
+ () => new WebSocketServer({ host: '127.0.0.1', port: 0, maxPayload: 4096 })
+ );
+ const sockets: WebSocket[] = [];
+ for (const [index, server] of servers.entries()) {
+ 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 = frame[1];
+ if (index === 0) {
+ socket.send(JSON.stringify(['EVENT', id, current]));
+ socket.send(JSON.stringify(['EVENT', id, current]));
+ socket.send(
+ JSON.stringify(['EVENT', id, { ...current, sig: '0'.repeat(128) }])
+ );
+ socket.send(JSON.stringify(['EOSE', id]));
+ } else {
+ socket.send(JSON.stringify(['EVENT', id, previous]));
+ socket.send(
+ JSON.stringify([
+ 'CLOSED',
+ id,
+ 'HC_TEST_ONLY_PRIVATE_RAW_REASON <script>unsafe</script>'
+ ])
+ );
+ }
+ });
+ });
+ }
+ await Promise.all(servers.map((server) => once(server, 'listening')));
+ const ports = servers.map((server) => {
+ const address = server.address();
+ assert.ok(address && typeof address !== 'string');
+ return address.port;
+ });
+ const windowDescriptor = Object.getOwnPropertyDescriptor(
+ globalThis,
+ 'window'
+ );
+ const originalSocket = globalThis.WebSocket;
+ class FixtureSocket extends WebSocket {
+ constructor(url: string | URL) {
+ const origin = String(url).replace(/\/$/, '');
+ const index = origins.indexOf(origin);
+ assert.notEqual(index, -1);
+ super(`ws://127.0.0.1:${ports[index]}`);
+ }
+ }
+ Object.defineProperty(globalThis, 'window', {
+ configurable: true,
+ value: {}
+ });
+ globalThis.WebSocket =
+ FixtureSocket as unknown as typeof globalThis.WebSocket;
+ const policy = validateRelayPolicy(
+ JSON.stringify({
+ schemaVersion: 1,
+ public: origins.map((origin) => ({
+ origin,
+ read: true,
+ write: false,
+ nip50: false
+ })),
+ inbox: [],
+ postingEnabled: false,
+ messagingEnabled: false,
+ operatorDenylist: []
+ })
+ );
+ assert.ok(policy);
+ const pool = getPublicPool(policy)!;
+ const store = getPublicStore()!;
+ const ingress = createPublicIngress();
+ const journal = createObservationJournal(policy);
+ const result = createPublicRequestResult(policy, ingress, journal);
+ const statuses: string[] = [];
+ try {
+ await new Promise<void>((resolve) =>
+ subscribePublicPool(pool, [{ kinds: [30402], limit: 200 }], (message) => {
+ const outcome = handlePublicRequestMessage(result, message);
+ if (message.type === 'EVENT') statuses.push(outcome.status);
+ if (outcome.status === 'accepted' || outcome.status === 'duplicate')
+ insertPublicEnvelope(store, outcome.value);
+ if (
+ publicRequestSnapshot(result).sources.every(
+ (row) => row.state === 'eose' || row.state === 'closed'
+ )
+ )
+ resolve();
+ })
+ );
+ const snapshot = publicRequestSnapshot(result);
+ assert.equal(snapshot.coverage, 'partial');
+ assert.equal(snapshot.definitiveAbsence, false);
+ assert.equal(publicObservations(journal, snapshot.context).length, 2);
+ assert.equal(
+ exactPublicObservation(journal, snapshot.context, current.id, origins[0]),
+ true
+ );
+ assert.equal(
+ exactPublicObservation(journal, snapshot.context, current.id, origins[1]),
+ false
+ );
+ assert.equal(
+ exactPublicObservation(
+ journal,
+ snapshot.context,
+ previous.id,
+ origins[1]
+ ),
+ true
+ );
+ assert.ok(publicStoreEnvelope(store, current.id));
+ assert.ok(publicStoreEnvelope(store, previous.id));
+ assert.equal(publicIngressStats(ingress).deliveries, 4);
+ assert.equal(statuses.filter((x) => x === 'accepted').length, 2);
+ assert.equal(statuses.filter((x) => x === 'duplicate').length, 1);
+ assert.equal(statuses.filter((x) => x === 'rejected').length, 1);
+ assert.doesNotMatch(
+ JSON.stringify(snapshot),
+ /HC_TEST_ONLY_PRIVATE_RAW_REASON|script|unsafe/
+ );
+ } finally {
+ disposePublicRequestResult(result);
+ closePublicStore(store);
+ closePublicPool(pool);
+ for (const socket of sockets) socket.terminate();
+ await Promise.all(
+ servers.map(
+ (server) =>
+ new Promise<void>((resolve, reject) =>
+ server.close((error) => (error ? reject(error) : resolve()))
+ )
+ )
+ );
+ globalThis.WebSocket = originalSocket;
+ if (windowDescriptor)
+ Object.defineProperty(globalThis, 'window', windowDescriptor);
+ else Reflect.deleteProperty(globalThis, 'window');
+ }
+});
diff --git a/web/tests/unit/request-result.test.ts b/web/tests/unit/request-result.test.ts
@@ -0,0 +1,402 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { EventStore } from 'applesauce-core';
+import { getSeenRelays } from 'applesauce-core/helpers';
+import { validateRelayPolicy } from '../../src/lib/config/relays.ts';
+import {
+ createPublicIngress,
+ publicIngressStats
+} from '../../src/lib/nostr/ingress.ts';
+import {
+ verifyEnvelope,
+ verifiedEnvelopeSnapshot
+} from '../../src/lib/nostr/verified-envelope.ts';
+import {
+ createObservationJournal,
+ createObservationContext,
+ recordPublicObservation,
+ exactPublicObservation,
+ publicObservations,
+ observationJournalStats,
+ closeObservationJournal
+} from '../../src/lib/catalog/observations.ts';
+import {
+ createPublicRequestResult,
+ handlePublicRequestMessage,
+ publicRequestSnapshot,
+ disposePublicRequestResult
+} from '../../src/lib/nostr/request-result.ts';
+const origins = ['wss://one.example.org', 'wss://two.example.org'];
+const policy = validateRelayPolicy(
+ JSON.stringify({
+ schemaVersion: 1,
+ public: origins.map((origin) => ({
+ origin,
+ read: true,
+ write: false,
+ nip50: false
+ })),
+ inbox: [],
+ postingEnabled: false,
+ messagingEnabled: false,
+ operatorDenylist: []
+ })
+)!;
+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 wires = corpus.vectors.find((v) => v.id.endsWith('_032'))!.signed_wires;
+function proof(raw: string) {
+ const result = verifyEnvelope(raw);
+ if (!result.ok) throw new Error('Invalid signed test vector');
+ return result.value;
+}
+const current = proof(wires.current);
+const previous = proof(wires.previous);
+const currentEvent = () =>
+ JSON.parse(wires.current) as NonNullable<
+ ReturnType<typeof verifiedEnvelopeSnapshot>
+ >;
+function setup() {
+ const journal = createObservationJournal(policy);
+ const ingress = createPublicIngress();
+ const result = createPublicRequestResult(policy, ingress, journal);
+ return { journal, ingress, result };
+}
+describe('exact public source observations', () => {
+ it('binds every request in a journal to one shared admission owner', () => {
+ const { journal, ingress } = setup();
+ expect(() =>
+ createPublicRequestResult(policy, createPublicIngress(), journal)
+ ).toThrow('public_request_ingress_changed');
+ expect(publicIngressStats(ingress).deliveries).toBe(0);
+ expect(observationJournalStats(journal).rows).toBe(0);
+ });
+ it('rejects a different source manifest before request observation creation', () => {
+ const { journal, ingress } = setup();
+ const different = validateRelayPolicy(
+ JSON.stringify({
+ schemaVersion: 1,
+ public: [
+ { origin: origins[0], read: true, write: false, nip50: false }
+ ],
+ inbox: [],
+ postingEnabled: false,
+ messagingEnabled: false,
+ operatorDenylist: []
+ })
+ )!;
+ expect(() =>
+ createPublicRequestResult(different, ingress, journal)
+ ).toThrow('request_observation_policy_changed');
+ expect(publicIngressStats(ingress).deliveries).toBe(0);
+ expect(observationJournalStats(journal).rows).toBe(0);
+ });
+ it('does not cache authentic events outside the shared approved public inventory', () => {
+ const { journal, ingress, result } = setup();
+ const raw = corpus.vectors.find((row) => row.id.endsWith('_019'))!
+ .signed_wires.event;
+ expect(verifyEnvelope(raw).ok).toBe(true);
+ expect(
+ handlePublicRequestMessage(result, {
+ type: 'EVENT',
+ from: origins[0],
+ id: 'a',
+ event: JSON.parse(raw) as ReturnType<typeof currentEvent>
+ }).status
+ ).toBe('not_public');
+ expect(
+ handlePublicRequestMessage(result, {
+ type: 'EVENT',
+ from: origins[0],
+ id: 'a',
+ event: currentEvent()
+ }).status
+ ).toBe('accepted');
+ expect(
+ publicObservations(journal, publicRequestSnapshot(result).context)
+ ).toHaveLength(1);
+ expect(publicIngressStats(ingress).deliveries).toBe(2);
+ });
+ it('deduplicates only the exact event/source/request tuple', () => {
+ const journal = createObservationJournal(policy);
+ const first = createObservationContext(journal);
+ const second = createObservationContext(journal);
+ expect(recordPublicObservation(journal, first, origins[0], current)).toBe(
+ true
+ );
+ expect(recordPublicObservation(journal, first, origins[0], current)).toBe(
+ true
+ );
+ expect(recordPublicObservation(journal, first, origins[1], current)).toBe(
+ true
+ );
+ expect(recordPublicObservation(journal, second, origins[0], current)).toBe(
+ true
+ );
+ expect(publicObservations(journal, first)).toHaveLength(2);
+ expect(publicObservations(journal, second)).toHaveLength(1);
+ expect(observationJournalStats(journal).rows).toBe(3);
+ (publicObservations(journal, first) as unknown as unknown[]).pop();
+ expect(publicObservations(journal, first)).toHaveLength(2);
+ });
+ it('never derives exact receipt from actual SDK cross-version seen metadata', () => {
+ const journal = createObservationJournal(policy);
+ const context = createObservationContext(journal);
+ const sdk = new EventStore({ keepOldVersions: false });
+ const newer = currentEvent();
+ const older = JSON.parse(wires.previous) as typeof newer;
+ sdk.add(newer, origins[0]);
+ sdk.add(older, origins[1]);
+ expect(getSeenRelays(newer)?.has(origins[1])).toBe(true);
+ recordPublicObservation(journal, context, origins[0], current);
+ recordPublicObservation(journal, context, origins[1], previous);
+ expect(exactPublicObservation(journal, context, newer.id, origins[0])).toBe(
+ true
+ );
+ expect(exactPublicObservation(journal, context, newer.id, origins[1])).toBe(
+ false
+ );
+ expect(exactPublicObservation(journal, context, older.id, origins[1])).toBe(
+ true
+ );
+ sdk.dispose();
+ });
+ it('rejects forged proof, unapproved source and another journal context', () => {
+ const journal = createObservationJournal(policy);
+ const context = createObservationContext(journal);
+ expect(
+ recordPublicObservation(
+ journal,
+ context,
+ origins[0],
+ {} as typeof current
+ )
+ ).toBe(false);
+ expect(
+ recordPublicObservation(
+ journal,
+ context,
+ 'wss://hint.example.org',
+ current
+ )
+ ).toBe(false);
+ const other = createObservationJournal(policy);
+ const alien = createObservationContext(other);
+ expect(() =>
+ recordPublicObservation(journal, alien, origins[0], current)
+ ).toThrow('observation_context_invalid');
+ expect(() => publicObservations({} as typeof journal, context)).toThrow(
+ 'observation_journal_invalid'
+ );
+ expect(observationJournalStats(journal).rows).toBe(0);
+ });
+ it('charges duplicates while retaining their freshly verified exact source proof before store dedup', () => {
+ const { journal, ingress, result } = setup();
+ const first = handlePublicRequestMessage(result, {
+ type: 'EVENT',
+ from: origins[0],
+ id: 'a',
+ event: currentEvent()
+ });
+ const second = handlePublicRequestMessage(result, {
+ type: 'EVENT',
+ from: origins[1] + '/',
+ id: 'b',
+ event: currentEvent()
+ });
+ expect(first.status).toBe('accepted');
+ expect(second.status).toBe('duplicate');
+ if (second.status === 'duplicate')
+ expect(verifiedEnvelopeSnapshot(second.value)?.id).toBe(
+ currentEvent().id
+ );
+ const context = publicRequestSnapshot(result).context;
+ expect(
+ exactPublicObservation(journal, context, currentEvent().id, origins[0])
+ ).toBe(true);
+ expect(
+ exactPublicObservation(journal, context, currentEvent().id, origins[1])
+ ).toBe(true);
+ expect(publicIngressStats(ingress).deliveries).toBe(2);
+ expect(publicIngressStats(ingress).chargedBytes).toBeGreaterThan(0);
+ });
+ it('retains valid evidence across a malformed candidate and failing source', () => {
+ const { journal, ingress, result } = setup();
+ expect(
+ handlePublicRequestMessage(result, {
+ type: 'EVENT',
+ from: origins[0],
+ id: 'a',
+ event: { ...currentEvent(), sig: '0'.repeat(128) }
+ }).status
+ ).toBe('rejected');
+ expect(
+ handlePublicRequestMessage(result, {
+ type: 'EVENT',
+ from: origins[0],
+ id: 'a',
+ event: currentEvent()
+ }).status
+ ).toBe('accepted');
+ handlePublicRequestMessage(result, {
+ type: 'EOSE',
+ from: origins[0],
+ id: 'a'
+ });
+ handlePublicRequestMessage(result, {
+ type: 'ERROR',
+ from: origins[1],
+ error: new Error('HC_TEST_ONLY_RAW_PRIVATE_ERROR')
+ });
+ const snapshot = publicRequestSnapshot(result);
+ expect(snapshot.coverage).toBe('partial');
+ expect(snapshot.definitiveAbsence).toBe(false);
+ expect(publicObservations(journal, snapshot.context)).toHaveLength(1);
+ expect(publicIngressStats(ingress).deliveries).toBe(2);
+ expect(JSON.stringify(snapshot)).not.toContain(
+ 'HC_TEST_ONLY_RAW_PRIVATE_ERROR'
+ );
+ });
+ it('does not inspect or expose arbitrary relay reasons or error objects', () => {
+ const { result } = setup();
+ let reads = 0;
+ handlePublicRequestMessage(result, {
+ type: 'CLOSED',
+ from: origins[0],
+ id: 'a',
+ get reason(): string {
+ reads++;
+ throw new Error('Untrusted relay text');
+ }
+ });
+ handlePublicRequestMessage(result, {
+ type: 'ERROR',
+ from: origins[1],
+ get error() {
+ reads++;
+ throw new Error('Untrusted error object');
+ }
+ });
+ expect(reads).toBe(0);
+ const snapshot = publicRequestSnapshot(result);
+ expect(snapshot.sources.map((row) => row.state)).toEqual([
+ 'closed',
+ 'error'
+ ]);
+ expect(JSON.stringify(snapshot)).not.toContain('Untrusted');
+ });
+ it('ignores unknown source hints without letting them become observation authority', () => {
+ const { journal, ingress, result } = setup();
+ expect(
+ handlePublicRequestMessage(result, {
+ type: 'EVENT',
+ from: 'wss://hint.example.org',
+ id: 'a',
+ event: currentEvent()
+ }).status
+ ).toBe('source_unknown');
+ const snapshot = publicRequestSnapshot(result);
+ expect(publicObservations(journal, snapshot.context)).toEqual([]);
+ expect(publicIngressStats(ingress).deliveries).toBe(1);
+ expect(JSON.stringify(snapshot)).not.toContain('hint.example.org');
+ });
+ it('bounds journal rows across all request contexts at the approved delivery cap', () => {
+ const journal = createObservationJournal(policy);
+ for (let i = 0; i < 2000; i++)
+ expect(
+ recordPublicObservation(
+ journal,
+ createObservationContext(journal),
+ origins[0],
+ current
+ )
+ ).toBe(true);
+ expect(
+ recordPublicObservation(
+ journal,
+ createObservationContext(journal),
+ origins[0],
+ current
+ )
+ ).toBe(false);
+ expect(observationJournalStats(journal)).toEqual({
+ rows: 2000,
+ closed: false
+ });
+ });
+ it('cannot turn a degraded empty request or bounded EOSE into definitive absence', () => {
+ const { result } = setup();
+ handlePublicRequestMessage(result, {
+ type: 'EOSE',
+ from: origins[0],
+ id: 'a'
+ });
+ expect(publicRequestSnapshot(result).coverage).toBe('partial');
+ handlePublicRequestMessage(result, {
+ type: 'EOSE',
+ from: origins[1],
+ id: 'b'
+ });
+ expect(publicRequestSnapshot(result).coverage).toBe('bounded-eose');
+ expect(publicRequestSnapshot(result).definitiveAbsence).toBe(false);
+ });
+ it('disposes only its request and preserves another request and valid observations', () => {
+ const { journal, ingress, result } = setup();
+ const other = createPublicRequestResult(policy, ingress, journal);
+ handlePublicRequestMessage(result, {
+ type: 'EVENT',
+ from: origins[0],
+ id: 'a',
+ event: currentEvent()
+ });
+ const context = publicRequestSnapshot(result).context;
+ disposePublicRequestResult(result);
+ expect(
+ handlePublicRequestMessage(result, {
+ type: 'EVENT',
+ from: origins[1],
+ id: 'b',
+ event: currentEvent()
+ }).status
+ ).toBe('inactive');
+ expect(publicObservations(journal, context)).toHaveLength(1);
+ expect(
+ handlePublicRequestMessage(other, {
+ type: 'EVENT',
+ from: origins[1],
+ id: 'b',
+ event: currentEvent()
+ }).status
+ ).toBe('duplicate');
+ expect(
+ publicObservations(journal, publicRequestSnapshot(other).context)
+ ).toHaveLength(1);
+ });
+ it('keeps snapshots detached and explicit journal closure terminal', () => {
+ const { journal, result } = setup();
+ handlePublicRequestMessage(result, {
+ type: 'EVENT',
+ from: origins[0],
+ id: 'a',
+ event: currentEvent()
+ });
+ const snapshot = publicRequestSnapshot(result);
+ (snapshot.sources as unknown as unknown[]).pop();
+ expect(publicRequestSnapshot(result).sources).toHaveLength(2);
+ closeObservationJournal(journal);
+ expect(publicObservations(journal, snapshot.context)).toEqual([]);
+ expect(
+ recordPublicObservation(journal, snapshot.context, origins[0], current)
+ ).toBe(false);
+ expect(() => createObservationContext(journal)).toThrow(
+ 'observations_closed'
+ );
+ });
+});