resolve-head.ts (13531B)
1 import { PUBLIC_QUERY_BUDGETS } from '../config/budgets.ts'; 2 import type { PublicFilter } from '../nostr/exports.ts'; 3 import { headResolutionQueries } from '../nostr/product-queries.ts'; 4 import { 5 verifiedEnvelopeSnapshot, 6 type VerifiedEnvelope 7 } from '../nostr/verified-envelope.ts'; 8 import { 9 admitDeletionRequest, 10 deletionRequestEnvelope, 11 deletionRequestSnapshot, 12 type DeletionRequest 13 } from '../nostr/deletion-adapter.ts'; 14 import { 15 closePublicRequest, 16 publicRequestScopeSnapshot, 17 publicRunObservations, 18 publicRunSnapshot, 19 type PublicRun, 20 type PublicRequest 21 } from '../nostr/request-scope.ts'; 22 import { 23 subscribePublicView, 24 publicViewRunCurrent, 25 publicViewProjectionAvailable, 26 publicViewKnownEvidence, 27 retainPublicViewHeads, 28 settlePublicViewProjection, 29 type PublicView 30 } from '../runtime/public-runtime.ts'; 31 import { 32 createPublicHeadCandidate, 33 publicHeadKey, 34 publicHeadSnapshot, 35 publicHeadEnvelope, 36 type PublicHead 37 } from './heads.ts'; 38 import { 39 createFoodHeadState, 40 advanceFoodHeadState, 41 refreshFoodHeadState, 42 foodHeadStateHead, 43 foodHeadStateSnapshot, 44 type FoodHeadState 45 } from './head-state.ts'; 46 import { evaluatePublicHeadDeletion } from './deletions.ts'; 47 import type { KnownPublicEvidence } from './retention.ts'; 48 import type { WallClock } from './clock-policy.ts'; 49 50 declare const resolverBrand: unique symbol; 51 export type HeadResolver = Readonly<{ readonly [resolverBrand]: true }>; 52 // Trusted logical request factory, like openPublicRequest's transport factory. 53 // Production binds this to the view's genuine shared run and anonymous pool. 54 export type HeadSubscriber = ( 55 kind: 'head' | 'deletion', 56 filters: readonly PublicFilter[], 57 onVerified: (proof: VerifiedEnvelope) => void 58 ) => PublicRequest; 59 type ScopeSnapshot = ReturnType<typeof publicRequestScopeSnapshot>; 60 interface Group { 61 readonly head: () => ScopeSnapshot | undefined; 62 readonly deletion: () => ScopeSnapshot | undefined; 63 readonly complete: () => boolean; 64 readonly open: () => void; 65 readonly close: () => void; 66 } 67 interface Entry { 68 readonly state: FoodHeadState; 69 readonly group: Group; 70 } 71 export interface KnownHeadSource { 72 readonly retain: (heads: readonly PublicHead[]) => boolean; 73 readonly read: (head: PublicHead) => KnownPublicEvidence; 74 readonly available: () => boolean; 75 } 76 interface Owner { 77 readonly available: () => boolean; 78 readonly resolve: (heads: readonly PublicHead[], lookup: boolean) => void; 79 readonly snapshot: () => readonly HeadResolution[]; 80 readonly close: () => void; 81 } 82 export type HeadResolution = Readonly<{ 83 key: string; 84 state: ReturnType<typeof foodHeadStateSnapshot>; 85 deletion: ReturnType<typeof evaluatePublicHeadDeletion>; 86 deletionProofs: readonly VerifiedEnvelope[]; 87 headSources: ScopeSnapshot | undefined; 88 deletionSources: ScopeSnapshot | undefined; 89 coverage: 'bounded-eose' | 'partial'; 90 lastKnown: boolean; 91 definitiveAbsence: false; 92 }>; 93 const owners = new WeakMap<HeadResolver, Owner>(); 94 function ownerOf(resolver: HeadResolver): Owner { 95 const owner = owners.get(resolver); 96 if (!owner) throw new Error('head_resolver_invalid'); 97 return owner; 98 } 99 function emptyRows<T>(): readonly T[] { 100 return []; 101 } 102 export function createHeadResolver( 103 run: PublicRun, 104 subscribe: HeadSubscriber, 105 clock: WallClock, 106 known?: KnownHeadSource 107 ): HeadResolver { 108 publicRunSnapshot(run); 109 const readClock = clock.nowSeconds; 110 if (typeof readClock !== 'function') 111 throw new Error('head_resolver_clock_invalid'); 112 const token = Object.freeze({}) as HeadResolver; 113 const entries = new Map<string, Entry>(), 114 evidence = new Map<string, DeletionRequest>(); 115 let groups = emptyRows<Group>(); 116 let closed = false; 117 const active = () => !closed && publicRunSnapshot(run).active; 118 function mergeKnown(head: PublicHead): PublicHead { 119 const row = known?.read(head); 120 if (!row) return head; 121 for (const request of row.requests) { 122 const snapshot = deletionRequestSnapshot(request); 123 if (snapshot) evidence.set(snapshot.id, request); 124 } 125 return row.head; 126 } 127 function clearProjection() { 128 entries.clear(); 129 evidence.clear(); 130 const pending = groups; 131 groups = emptyRows<Group>(); 132 for (const group of pending) { 133 try { 134 group.close(); 135 } catch { 136 groups = groups.concat(group); 137 } 138 } 139 if (groups.length) throw new Error('head_resolver_close_failed'); 140 } 141 const retained = () => known?.available() ?? true; 142 function groupFor(heads: readonly PublicHead[]): Group { 143 const queries = headResolutionQueries(heads), 144 keys = new Map(heads.map((h) => [publicHeadKey(h), true])); 145 const authors = new Map( 146 heads.map((h) => [publicHeadSnapshot(h).pubkey, true]) 147 ); 148 let headRequest: PublicRequest | undefined, 149 deletionRequest: PublicRequest | undefined; 150 let incomplete = false; 151 const snapshot = (request: PublicRequest | undefined) => 152 request === undefined ? undefined : publicRequestScopeSnapshot(request); 153 const stop = () => { 154 // Independent cleanup: failure of one control cannot strand the other. 155 let failed = false; 156 for (const request of [headRequest, deletionRequest]) { 157 if (request === undefined) continue; 158 try { 159 closePublicRequest(request); 160 } catch { 161 failed = true; 162 } 163 } 164 if (failed) throw new Error('head_resolver_close_failed'); 165 }; 166 const checked = ( 167 kind: 'head' | 'deletion', 168 filters: readonly PublicFilter[], 169 next: (proof: VerifiedEnvelope) => void 170 ) => { 171 const request = subscribe(kind, filters, (proof) => { 172 // The request owner has already admitted this callback, including the 173 // final valid delivery that exhausts ingress before request teardown. 174 if (!closed) next(proof); 175 }); 176 try { 177 publicRunObservations(run, request); 178 if (publicRequestScopeSnapshot(request).kind !== kind) 179 throw new Error('head_resolver_request_kind'); 180 } catch { 181 closePublicRequest(request); 182 throw new Error('head_resolver_request_owner'); 183 } 184 return request; 185 }; 186 return { 187 head: () => snapshot(headRequest), 188 deletion: () => snapshot(deletionRequest), 189 complete: () => 190 !incomplete && 191 snapshot(headRequest)?.state === 'eose' && 192 snapshot(deletionRequest)?.state === 'eose', 193 close: () => { 194 incomplete = true; 195 stop(); 196 }, 197 open() { 198 try { 199 headRequest = checked('head', queries.head, (proof) => { 200 const candidate = createPublicHeadCandidate(proof); 201 const key = 202 candidate === undefined ? undefined : publicHeadKey(candidate); 203 if (key === undefined || !keys.has(key)) { 204 incomplete = true; 205 return; 206 } 207 const entry = entries.get(key); 208 if (entry && candidate) 209 advanceFoodHeadState( 210 entry.state, 211 publicHeadEnvelope(mergeKnown(candidate)) 212 ); 213 }); 214 if (!active()) { 215 incomplete = true; 216 stop(); 217 return; 218 } 219 deletionRequest = checked('deletion', queries.deletion, (proof) => { 220 const event = verifiedEnvelopeSnapshot(proof); 221 if (!event || !authors.has(event.pubkey)) { 222 incomplete = true; 223 return; 224 } 225 const request = admitDeletionRequest(proof); 226 if (!request.ok) { 227 incomplete = true; 228 return; 229 } 230 const row = deletionRequestSnapshot(request.value); 231 if (row) evidence.set(row.id, request.value); 232 }); 233 if (!active()) { 234 incomplete = true; 235 stop(); 236 } 237 } catch { 238 incomplete = true; 239 stop(); 240 } 241 } 242 }; 243 } 244 owners.set(token, { 245 available: retained, 246 resolve(heads, lookup) { 247 if (closed || (lookup && !active())) 248 throw new Error('head_resolver_inactive'); 249 if (!lookup && active()) throw new Error('head_resolver_still_active'); 250 if (!lookup && !known) throw new Error('head_resolver_known_required'); 251 // Validate the complete batch and total coordinate admission before any 252 // external clock/request callback. Repeated coordinates never reset work. 253 headResolutionQueries(heads); 254 const unique = new Map<string, PublicHead>(); 255 for (const head of heads) unique.set(publicHeadKey(head), head); 256 const fresh = Array.from(unique.values()).filter( 257 (h) => !entries.has(publicHeadKey(h)) 258 ); 259 if (entries.size + fresh.length > PUBLIC_QUERY_BUDGETS.coordinatesPerRun) 260 throw new Error('head_resolver_coordinate_limit'); 261 if (!retained() || (known && !known.retain(heads))) { 262 clearProjection(); 263 return; 264 } 265 const group = fresh.length === 0 ? undefined : groupFor(fresh); 266 if (group) groups = groups.concat(group); 267 // Reserve every coordinate before caller-controlled clocks or openers. 268 let prepared = false; 269 let created = emptyRows<FoodHeadState>(); 270 for (const head of fresh) { 271 const state = createFoodHeadState(mergeKnown(head), { 272 nowSeconds: () => (prepared ? readClock() : NaN) 273 }); 274 entries.set(publicHeadKey(head), { state, group: group! }); 275 created = created.concat(state); 276 } 277 prepared = true; 278 for (const state of created) refreshFoodHeadState(state); 279 for (const head of heads) { 280 const entry = entries.get(publicHeadKey(head)); 281 if (entry) 282 advanceFoodHeadState( 283 entry.state, 284 publicHeadEnvelope(mergeKnown(head)) 285 ); 286 } 287 if (lookup && group && active()) group.open(); 288 }, 289 snapshot() { 290 if (!retained()) { 291 clearProjection(); 292 return []; 293 } 294 const available = active(); 295 const rows: readonly HeadResolution[] = Array.from( 296 entries, 297 ([key, entry]) => { 298 advanceFoodHeadState( 299 entry.state, 300 publicHeadEnvelope(mergeKnown(foodHeadStateHead(entry.state))) 301 ); 302 const deletion = evaluatePublicHeadDeletion( 303 foodHeadStateHead(entry.state), 304 Array.from(evidence.values()) 305 ); 306 const state = foodHeadStateSnapshot(entry.state); 307 const complete = available && entry.group.complete(); 308 return { 309 key, 310 state: { 311 ...state, 312 food: deletion.outcome === 'suppressed' ? undefined : state.food 313 }, 314 deletion, 315 deletionProofs: Array.from(evidence.values()).flatMap((r) => { 316 const proof = deletionRequestEnvelope(r); 317 return proof === undefined ? [] : [proof]; 318 }), 319 headSources: entry.group.head(), 320 deletionSources: entry.group.deletion(), 321 coverage: complete ? 'bounded-eose' : 'partial', 322 lastKnown: !complete, 323 definitiveAbsence: false 324 }; 325 } 326 ); 327 if (!retained()) { 328 clearProjection(); 329 return []; 330 } 331 return rows; 332 }, 333 close() { 334 closed = true; 335 let failed = false; 336 for (const group of groups) { 337 try { 338 group.close(); 339 } catch { 340 failed = true; 341 } 342 } 343 if (failed) throw new Error('head_resolver_close_failed'); 344 } 345 }); 346 return token; 347 } 348 const viewResolvers = new WeakMap< 349 PublicRun, 350 Readonly<{ view: PublicView; resolver: HeadResolver }> 351 >(); 352 export function createPublicViewHeadResolver( 353 view: PublicView, 354 run: PublicRun, 355 clock: WallClock 356 ): HeadResolver { 357 if (!publicViewRunCurrent(view, run)) 358 throw new Error('head_resolver_view_inactive'); 359 const current = viewResolvers.get(run); 360 if (current) { 361 if (current.view !== view) throw new Error('head_resolver_view_mismatch'); 362 return current.resolver; 363 } 364 const resolver = createHeadResolver( 365 run, 366 (kind, filters, next) => 367 subscribePublicView(view, run, kind, filters, next), 368 clock, 369 { 370 retain: (heads) => retainPublicViewHeads(view, run, heads), 371 read: (head) => publicViewKnownEvidence(view, head), 372 available: () => publicViewProjectionAvailable(view) 373 } 374 ); 375 viewResolvers.set(run, { view, resolver }); 376 settlePublicViewProjection(view, () => { 377 headResolutionSnapshot(resolver); 378 }); 379 return resolver; 380 } 381 export function resolveHeads( 382 resolver: HeadResolver, 383 heads: readonly PublicHead[] 384 ): void { 385 ownerOf(resolver).resolve(heads, true); 386 } 387 // Only previously retained proof may seed an ended run's partial projection. 388 // The known-source admission owner validates the complete batch before changes. 389 export function resolveKnownHeads( 390 resolver: HeadResolver, 391 heads: readonly PublicHead[] 392 ): void { 393 ownerOf(resolver).resolve(heads, false); 394 } 395 export function headResolutionSnapshot( 396 resolver: HeadResolver 397 ): readonly HeadResolution[] { 398 return ownerOf(resolver).snapshot(); 399 } 400 export function closeHeadResolver(resolver: HeadResolver): void { 401 ownerOf(resolver).close(); 402 } 403 404 export function headResolverRetentionState( 405 resolver: HeadResolver 406 ): Readonly<{ available: boolean; definitiveAbsence: false }> { 407 return { available: ownerOf(resolver).available(), definitiveAbsence: false }; 408 }