app

Local-first trade for farms and co-ops
git clone https://radroots.dev/git/app.git
Log | Files | Refs | README | LICENSE

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 }