@estiva-app/interop 0.74.1 → 0.76.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/projection.ts CHANGED
@@ -14,7 +14,7 @@
14
14
  */
15
15
  import { decodeNevent, encodeNaddr, encodeNevent, pointerToAddress, referenceToPointer, type AddressPointer, type EventPointer } from '@estiva-app/protocol'
16
16
  import { parseProfile, type Profile, type SignedEvent } from '@estiva-app/protocol'
17
- import { MAX_FILTERS_PER_QUERY, RELAY_PAGE_CEILING } from '@estiva-app/protocol'
17
+ import { FILE_KINDS, MAX_FILTERS_PER_QUERY, RELAY_PAGE_CEILING } from '@estiva-app/protocol'
18
18
  import {
19
19
  attachmentsInDocument,
20
20
  BLOCK_DOCUMENT_FORMAT,
@@ -22,7 +22,7 @@ import {
22
22
  imetaTag,
23
23
  parseBlockDocument,
24
24
  } from '@estiva-app/protocol'
25
- import { identifierOf, planPlaceFile, planUnlistFile, type FolderRef } from './folders.js'
25
+ import { identifierOf, listedEntriesOf, listsFile, planPlaceFile, planUnlistFile, type FolderRef } from './folders.js'
26
26
  /*
27
27
  SPEC §6.4's comment strength and §6.3's ordering are the conversation
28
28
  package's (CON-5): one copy of each rule, read here for a file's `comments`,
@@ -386,7 +386,16 @@ export async function conversationsOf(
386
386
  query: QueryFn,
387
387
  /** Warm from the read that produced these files; see {@link ProjectionCache}. */
388
388
  cache?: ProjectionCache,
389
- options: { replies?: boolean } = {},
389
+ options: {
390
+ replies?: boolean
391
+ /**
392
+ * With `replies`, the second each file's replies are read from, or `null`
393
+ * to read none for it: a list that judges a dot on only some files, and
394
+ * knows no reply before a second can be unread, sends a smaller `#A`
395
+ * filter (SHIPS-2). Undefined reads every file's, unbounded.
396
+ */
397
+ repliesSince?: (address: string) => number | null
398
+ } = {},
390
399
  ): Promise<Record<string, ConversationMessage[]>> {
391
400
  const addressed = files.flatMap((file) => {
392
401
  if (!file.address) return []
@@ -434,11 +443,12 @@ export async function conversationsOf(
434
443
  const conversations: Record<string, ConversationMessage[]> = {}
435
444
  for (const a of asked) conversations[a.ref] = []
436
445
 
437
- const filters: Record<string, unknown>[] = asked.flatMap((a) =>
438
- options.replies
439
- ? [a.filter, { kinds: [KIND_COMMENT], '#A': [a.address], limit: CONVERSATION_LIMIT }]
440
- : [a.filter],
441
- )
446
+ const filters: Record<string, unknown>[] = asked.flatMap((a) => {
447
+ if (!options.replies) return [a.filter]
448
+ const since = options.repliesSince?.(a.address)
449
+ if (since === null) return [a.filter]
450
+ return [a.filter, { kinds: [KIND_COMMENT], '#A': [a.address], limit: CONVERSATION_LIMIT, ...(since === undefined ? {} : { since }) }]
451
+ })
442
452
  /** The file in this list an event is a comment on (§6.4), by every `a` it carries. */
443
453
  const commentedFile = (event: SignedEvent): string | undefined =>
444
454
  event.tags
@@ -2382,27 +2392,43 @@ function inTargetFolder(change: SignedEvent, folders: ReadonlySet<string> | unde
2382
2392
  function foldChanges(changes: SignedEvent[], rule: RecordsRule, root: SignedEvent | undefined) {
2383
2393
  const fields: Record<string, { value: string; by: string; at: number; format: ContentFormat }> = {}
2384
2394
  const folders = targetFolders(root)
2395
+ const id = root && tagValue(root, 'd')
2385
2396
  for (const change of [...changes].filter((c) => inTargetFolder(c, folders)).sort(byOrder)) {
2386
- const field = tagValue(change, rule.fieldTag)
2387
- const value = tagValue(change, rule.valueTag)
2388
- if (!field || value === undefined) continue // a partial change sets nothing
2389
- // A summary is new, so it takes neither of §6.2's exceptions: a change the
2390
- // reader cannot check against the root's Folder is not read (SPEC §6.12).
2391
- if (field === SUMMARY_FIELD && !folders) continue
2392
- // The format travels with the *winning* change, not with the object. SPEC
2393
- // §13.4: "an app MUST read the tag from the event it took the value from,
2394
- // never from the object's root" — a description created as marker text and
2395
- // later edited into blocks is a root with no tag and a change with one.
2396
- fields[field] = {
2397
- value,
2398
- by: change.pubkey,
2399
- at: change.created_at,
2400
- format: contentFormatOf(change),
2397
+ // A change whose `O` is not its `a`'s file is about neither (SPEC §6.2).
2398
+ const O = tagValue(change, 'O')
2399
+ if (O !== undefined && id !== undefined && O !== id) continue
2400
+ for (const { field, value } of settingsOf(change, rule)) {
2401
+ // A summary is new, so it takes neither of §6.2's exceptions: a change the
2402
+ // reader cannot check against the root's Folder is not read (SPEC §6.12).
2403
+ if (field === SUMMARY_FIELD && !folders) continue
2404
+ // The format travels with the *winning* change, not with the object. SPEC
2405
+ // §13.4: "an app MUST read the tag from the event it took the value from,
2406
+ // never from the object's root" — a description created as marker text and
2407
+ // later edited into blocks is a root with no tag and a change with one.
2408
+ fields[field] = {
2409
+ value,
2410
+ by: change.pubkey,
2411
+ at: change.created_at,
2412
+ format: contentFormatOf(change),
2413
+ }
2401
2414
  }
2402
2415
  }
2403
2416
  return fields
2404
2417
  }
2405
2418
 
2419
+ /**
2420
+ * The fields one change sets under `rule`: one per `set` when it carries any
2421
+ * (SPEC §6.2, applied at the change's time as that many one-field changes),
2422
+ * else its field and value tags. A partial change sets nothing.
2423
+ */
2424
+ function settingsOf(change: SignedEvent, rule: RecordsRule): { field: string; value: string }[] {
2425
+ const sets = change.tags.filter((t) => t[0] === 'set' && t[1] && typeof t[2] === 'string')
2426
+ if (sets.length) return sets.map((t) => ({ field: t[1], value: t[2] }))
2427
+ const field = tagValue(change, rule.fieldTag)
2428
+ const value = tagValue(change, rule.valueTag)
2429
+ return field && value !== undefined ? [{ field, value }] : []
2430
+ }
2431
+
2406
2432
  /**
2407
2433
  * One object's fold out of a pooled answer: its app's change kind, naming it as
2408
2434
  * the **first** target tag, as `archiveOf` reads it. Empty when the app declares
@@ -2512,15 +2538,19 @@ function archiveOf(
2512
2538
  }
2513
2539
  const folders = targetFolders(root)
2514
2540
  let last: SignedEvent | undefined
2541
+ let archived: string | undefined
2515
2542
  for (const change of changes) {
2516
2543
  // The target is the first target tag, as every other fold reads it: a
2517
2544
  // change archiving one file must not archive another it also mentions.
2518
2545
  if (change.kind !== rule.changeKind || tagValue(change, rule.targetTag) !== address) continue
2519
2546
  if (!inTargetFolder(change, folders)) continue
2520
- if (tagValue(change, rule.fieldTag) !== ARCHIVED_FIELD || tagValue(change, rule.valueTag) === undefined) continue
2521
- if (!last || byOrder(last, change) < 0) last = change
2547
+ const O = tagValue(change, 'O')
2548
+ if (O !== undefined && O !== identifier) continue
2549
+ const set = settingsOf(change, rule).find((s) => s.field === ARCHIVED_FIELD)
2550
+ if (!set) continue
2551
+ if (!last || byOrder(last, change) < 0) [last, archived] = [change, set.value]
2522
2552
  }
2523
- if (!last || tagValue(last, rule.valueTag) !== 'true') return undefined
2553
+ if (!last || archived !== 'true') return undefined
2524
2554
  const note = last.content.trim()
2525
2555
  return {
2526
2556
  by: last.pubkey,
@@ -3823,6 +3853,8 @@ export async function resolveForeignRoots(
3823
3853
  references: readonly string[],
3824
3854
  query: QueryFn,
3825
3855
  cache?: ProjectionCache,
3856
+ /** `archivedWith` marks a file archived with an archived parent, as {@link resolveForeignObject}'s does (SHIPS-2). */
3857
+ options: Pick<ArchiveReadOptions, 'archivedWith'> = {},
3826
3858
  ): Promise<ForeignObject[]> {
3827
3859
  const pointers = new Map<string, AddressPointer>()
3828
3860
  for (const reference of references) {
@@ -3856,7 +3888,15 @@ export async function resolveForeignRoots(
3856
3888
  }
3857
3889
  if (filters.length === 0) return []
3858
3890
  const events = await queryChunked(filters, query)
3859
- return projectEvents(events, (pointer) => manifests.get(manifestKeyOf(pointer)))
3891
+ const objects = projectEvents(events, (pointer) => manifests.get(manifestKeyOf(pointer)))
3892
+ if (options.archivedWith) {
3893
+ const manifestOf = (object: ForeignObject) => {
3894
+ const pointer = object.address ? addressPointerOf(object.address) : undefined
3895
+ return pointer ? manifests.get(manifestKeyOf(pointer))?.manifest : undefined
3896
+ }
3897
+ await markArchivedParents(objects.map((object) => ({ object, manifest: manifestOf(object) })), query, cache)
3898
+ }
3899
+ return objects
3860
3900
  }
3861
3901
 
3862
3902
  /**
@@ -6338,6 +6378,12 @@ export interface FolderSummary {
6338
6378
  * another app's files resolves them with {@link resolveFolderContents}.
6339
6379
  */
6340
6380
  addresses?: string[]
6381
+ /**
6382
+ * The files this folder's state lists by their id (an `o` entry, SPEC §3.3),
6383
+ * other than one it already lists by address — present only when there are
6384
+ * any. Ask whether a folder lists a file with `listsFile`, which reads both.
6385
+ */
6386
+ ids?: string[]
6341
6387
  /**
6342
6388
  * The Folder's own address as a file — its `kind:39000`, `39000:<relay>:<id>`.
6343
6389
  * What a state lists when it holds this Folder, and what an `archived`
@@ -6525,11 +6571,14 @@ async function readFolderRecords(query: QueryFn): Promise<{ events: SignedEvent[
6525
6571
  if (event.kind !== KIND_FOLDER_STATE && event.kind !== KIND_CHANNEL) continue
6526
6572
  const state = event.kind === KIND_FOLDER_STATE
6527
6573
  const existing = byId.get(id)
6528
- const addresses = state ? event.tags.filter((tag) => tag[0] === 'a' && tag[1]).map((tag) => tag[1]) : (existing?.addresses ?? [])
6574
+ const { addresses, ids } = state
6575
+ ? listedEntriesOf(event, new Map())
6576
+ : { addresses: existing?.addresses ?? [], ids: existing?.ids ?? [] }
6529
6577
  byId.set(id, {
6530
6578
  id,
6531
6579
  hasState: state || (existing?.hasState ?? false),
6532
6580
  ...(addresses.length ? { addresses } : {}),
6581
+ ...(ids.length ? { ids } : {}),
6533
6582
  })
6534
6583
  }
6535
6584
  // The title, privacy and admins are the channel's (§3.2), whichever order the events arrived.
@@ -6648,7 +6697,7 @@ export async function archiveImpact(
6648
6697
  for (const file of contents.files) {
6649
6698
  if (!file.address) continue
6650
6699
  const others = folders.filter(
6651
- (other) => !inTree.has(other.id) && !other.archived && other.addresses?.includes(file.address!),
6700
+ (other) => !inTree.has(other.id) && !other.archived && listsFile(other, file.address!),
6652
6701
  )
6653
6702
  if (others.length) {
6654
6703
  staysVisible.push({ address: file.address, kind: file.kind, in: others.map(({ id, name }) => ({ id, name })) })
@@ -6789,15 +6838,18 @@ async function placeRecordChannels(
6789
6838
  query: QueryFn,
6790
6839
  ): Promise<{ recordsOf: Map<string, string[]>; archives: SignedEvent[]; rootOf: Map<string, SignedEvent> }> {
6791
6840
  const containersOf = new Map<string, { pointer: AddressPointer; containers: string[] }>()
6792
- for (const event of events) {
6793
- if (event.kind !== KIND_FOLDER_STATE) continue
6841
+ const states = events.filter((event) => event.kind === KIND_FOLDER_STATE)
6842
+ // A file listed by its id alone (§3.3) costs one read for every such entry, before the roots.
6843
+ const ids = [...new Set(states.flatMap((state) => listedEntriesOf(state, new Map()).ids))]
6844
+ const addressOfId = ids.length ? await addressesOfIds(ids, query) : new Map<string, string>()
6845
+ for (const event of states) {
6794
6846
  const container = tagValue(event, 'd')
6795
6847
  if (!container) continue
6796
- for (const tag of event.tags) {
6797
- if (tag[0] !== 'a' || !tag[1]) continue
6848
+ const listed = listedEntriesOf(event, addressOfId)
6849
+ for (const address of [...listed.addresses, ...listed.ids.flatMap((id) => addressOfId.get(id) ?? [])]) {
6798
6850
  let pointer: AddressPointer
6799
6851
  try {
6800
- pointer = referenceToPointer(tag[1])
6852
+ pointer = referenceToPointer(address)
6801
6853
  } catch {
6802
6854
  continue
6803
6855
  }
@@ -6981,7 +7033,7 @@ export async function resolveFolderContents(
6981
7033
  ? // §5.2: one tag type lists every file, topics included, with no special
6982
7034
  // case. The order is the folder's, so it is preserved rather than sorted.
6983
7035
  {
6984
- addresses: [...new Set(state.tags.filter((t) => t[0] === 'a' && t[1]).map((t) => t[1]))],
7036
+ addresses: await listedAddressesOf(state, query),
6985
7037
  placed: new Map<string, SignedEvent[]>(),
6986
7038
  }
6987
7039
  : options.listedOnly
@@ -7231,6 +7283,56 @@ export async function resolveFolderContents(
7231
7283
  }
7232
7284
  }
7233
7285
 
7286
+ /**
7287
+ * A Folder state's files as addresses, in its order, each once (SPEC §3.3).
7288
+ *
7289
+ * An `o` entry names a file by its id alone, so it costs a read: one request
7290
+ * for every such entry, asking each id's addressable roots, and an id is
7291
+ * the file whose one kind and author answer it, as a link by id is resolved
7292
+ * (§7.7). An id answered by none, or by two files, is dropped like an `a`
7293
+ * nothing parses. A state with no `o` entry reads nothing.
7294
+ */
7295
+ async function listedAddressesOf(state: SignedEvent, query: QueryFn): Promise<string[]> {
7296
+ const all = listedEntriesOf(state, new Map())
7297
+ if (all.ids.length === 0) return all.order
7298
+ const addressOf = await addressesOfIds(all.ids, query)
7299
+ // Folded against the addresses found: an `a` with an `o`'s id and another kind or author is drawn beside it.
7300
+ const { order, ids } = listedEntriesOf(state, addressOf)
7301
+ const byId = new Set(ids)
7302
+ const listed = order.flatMap((entry) => (byId.has(entry) ? (addressOf.get(entry) ?? []) : [entry]))
7303
+ return [...new Set(listed)]
7304
+ }
7305
+
7306
+ /**
7307
+ * The address of each file named by its id alone: the one file kind and
7308
+ * author whose root holds that `d`, as a link by id is resolved (§7.7). Only
7309
+ * the file kinds are asked: the relay keeps a `d` unique across those alone,
7310
+ * so under any other kind anyone could claim a listed file's id. One request
7311
+ * for all of them; an id answered by none, or by two files, is absent.
7312
+ */
7313
+ async function addressesOfIds(ids: readonly string[], query: QueryFn): Promise<Map<string, string>> {
7314
+ const found = await queryChunked(
7315
+ Array.from({ length: Math.ceil(ids.length / ID_GROUP) }, (_, i) => {
7316
+ const group = ids.slice(i * ID_GROUP, (i + 1) * ID_GROUP)
7317
+ return { kinds: [...FILE_KINDS], '#d': group, limit: group.length * 2 }
7318
+ }),
7319
+ query,
7320
+ )
7321
+ const asked = new Set(ids)
7322
+ const owners = new Map<string, Set<string>>()
7323
+ for (const event of found) {
7324
+ const id = tagValue(event, 'd')
7325
+ if (id === undefined || !asked.has(id) || !FILE_KINDS.includes(event.kind)) continue
7326
+ owners.set(id, (owners.get(id) ?? new Set()).add(`${event.kind}:${event.pubkey.toLowerCase()}`))
7327
+ }
7328
+ const out = new Map<string, string>()
7329
+ for (const [id, one] of owners) if (one.size === 1) out.set(id, `${[...one][0]}:${id}`)
7330
+ return out
7331
+ }
7332
+
7333
+ /** Ids per filter when a Folder state's `o` entries are resolved. */
7334
+ const ID_GROUP = 50
7335
+
7234
7336
  /**
7235
7337
  * The contents of a folder that has no state event — containment by `h`.
7236
7338
  *
package/src/topics.ts CHANGED
@@ -25,13 +25,36 @@
25
25
  * nobody to the file (§11.8).
26
26
  */
27
27
  import { type SignedEvent, type UnsignedEvent } from '@estiva-app/protocol'
28
- import { byOrder } from '@estiva-app/conversation'
29
- import { folderOf, type QueryFn } from './projection.js'
28
+ import { RELAY_PAGE_CEILING } from '@estiva-app/protocol'
29
+ import {
30
+ byOrder,
31
+ candidateFilesOf,
32
+ fileContext,
33
+ foldMemberships,
34
+ HORIZON_SECONDS,
35
+ membersOf,
36
+ membershipJudges,
37
+ REPLY_FLOOR_CONTEXT,
38
+ streamHasUnread,
39
+ streamTermsOf,
40
+ THREAD_RULE_FROM,
41
+ type MembershipRead,
42
+ } from '@estiva-app/conversation'
43
+ import {
44
+ conversationsOf,
45
+ folderOf,
46
+ isArchived,
47
+ resolveForeignRoots,
48
+ type ForeignObject,
49
+ type ProjectionCache,
50
+ type QueryFn,
51
+ } from './projection.js'
30
52
 
31
53
  const KIND_CHANGE = 1851
32
54
  /** The topic (bare file) kind: the only lists this stage reads (Miky, 2026-10-30). */
33
55
  const KIND_TOPIC = 30840
34
56
  const KIND_FOLDER = 39000
57
+ const KIND_COMMENT = 1111
35
58
  /** Listed ids resolved per request: 2 × this stays under a relay's usual `limit` cap. */
36
59
  const RESOLVE_BATCH = 100
37
60
  /**
@@ -282,10 +305,20 @@ export async function topicLists(
282
305
  options: { fileKinds?: readonly number[] } = {},
283
306
  ): Promise<Map<string, ListedFile[]>> {
284
307
  const asked = [...new Set(topics)]
308
+ if (asked.length === 0) return new Map()
309
+ return listsOf(query, asked, rootsOf(query, asked), options)
310
+ }
311
+
312
+ /** {@link topicLists} with the roots already asked for: {@link readTopics} reads them once for everything. */
313
+ async function listsOf(
314
+ query: QueryFn,
315
+ asked: readonly string[],
316
+ rootsRead: Promise<ReadonlyMap<string, SignedEvent>>,
317
+ options: { fileKinds?: readonly number[] },
318
+ ): Promise<Map<string, ListedFile[]>> {
285
319
  const out = new Map<string, ListedFile[]>(asked.map((topic) => [topic, []]))
286
- if (asked.length === 0) return out
287
320
  // One filter per topic in one request, so a relay's cap on an answer cuts no more than it would for that topic alone.
288
- const [roots, events] = await Promise.all([rootsOf(query, asked), query(asked.map(topicListFilter))])
321
+ const [roots, events] = await Promise.all([rootsRead, query(asked.map(topicListFilter))])
289
322
  const folderOfList = (list: string) => {
290
323
  const root = out.has(list) ? roots.get(list) : undefined
291
324
  return root ? folderOf(root) : null
@@ -299,6 +332,221 @@ export async function topicLists(
299
332
  return out
300
333
  }
301
334
 
335
+ /** A topic as {@link readTopics} reads it. */
336
+ export interface ReadTopic {
337
+ address: string
338
+ /** As its roots and changes draw it: its title and summary slots, and `archived`, its own or its parent's (§6.5). */
339
+ object: ForeignObject
340
+ /** Its Folder, from its root (§6.2): where an entry on its list is filed. */
341
+ folder: string
342
+ /** Its list, as {@link topicLists} reads it. */
343
+ listed: ListedFile[]
344
+ /**
345
+ * The viewer is a member (§11.8): by the horizon's membership read, or,
346
+ * where that read has no word on them, over all history — a topic joined
347
+ * before the horizon with nothing since is still theirs, as Peek's Topics
348
+ * says.
349
+ */
350
+ yours: boolean
351
+ }
352
+
353
+ /** Every topic the viewer can read, and the membership read that judges their dots. */
354
+ export interface TopicsRead {
355
+ me: string
356
+ topics: ReadTopic[]
357
+ membership: MembershipRead
358
+ }
359
+
360
+ /** The filters for a person's part in some files over all history: the changes naming them, what they wrote, what names them. */
361
+ function personInFilesFilters(person: string, files: readonly string[]): Record<string, unknown>[] {
362
+ return [
363
+ { kinds: [KIND_CHANGE], '#a': files, '#p': [person] },
364
+ { kinds: [KIND_COMMENT], '#A': files, authors: [person] },
365
+ { kinds: [KIND_COMMENT], '#a': files, authors: [person] },
366
+ { kinds: [KIND_COMMENT], '#A': files, '#p': [person] },
367
+ { kinds: [KIND_COMMENT], '#a': files, '#p': [person] },
368
+ ]
369
+ }
370
+
371
+ /** Whether an event answers a filter, as NIP-01 reads it: kinds, authors, `#x` tags, `since` and `until`. */
372
+ function answers(event: SignedEvent, filter: Record<string, unknown>): boolean {
373
+ const { kinds, authors, since, until } = filter as { kinds?: number[]; authors?: string[]; since?: number; until?: number }
374
+ if (kinds && !kinds.includes(event.kind)) return false
375
+ if (authors && !authors.includes(event.pubkey)) return false
376
+ if (since !== undefined && event.created_at < since) return false
377
+ if (until !== undefined && event.created_at > until) return false
378
+ return Object.entries(filter).every(
379
+ ([key, values]) => !key.startsWith('#') || event.tags.some((t) => t[0] === key.slice(1) && (values as string[]).includes(t[1])),
380
+ )
381
+ }
382
+
383
+ /**
384
+ * Everything the filters match, however many: each asked with a page's
385
+ * `limit`, and a filter whose answer filled it asked again from its oldest
386
+ * second down (`until`), until a page comes back short. One request when
387
+ * nothing fills a page, as at Miky's scale; never a silent cut at the relay's
388
+ * cap. A second holding a page's worth on its own ends the walk there.
389
+ */
390
+ async function readAll(query: QueryFn, filters: readonly Record<string, unknown>[]): Promise<SignedEvent[]> {
391
+ const out = new Map<string, SignedEvent>()
392
+ let open = filters.map((filter) => ({ ...filter, limit: RELAY_PAGE_CEILING }))
393
+ while (open.length) {
394
+ const events = await query(open)
395
+ for (const event of events) out.set(event.id, event)
396
+ open = open.flatMap((filter) => {
397
+ const page = events.filter((event) => answers(event, filter))
398
+ if (page.length < filter.limit) return []
399
+ const until = Math.min(...page.map((event) => event.created_at))
400
+ return until === (filter as { until?: number }).until ? [] : [{ ...filter, until }]
401
+ })
402
+ }
403
+ return [...out.values()]
404
+ }
405
+
406
+ /** Whether the person is a member of the file over all history, folded as its own page folds it. */
407
+ function memberOverAllHistory(person: string, file: string, events: readonly SignedEvent[]): boolean {
408
+ const [kind, pubkey, ...d] = file.split(':')
409
+ // The root, dated before everything: its author is a member unless a leave of theirs says otherwise.
410
+ const root = { id: '0'.repeat(64), pubkey: pubkey ?? '', kind: Number(kind), created_at: 0, tags: [['d', d.join(':')]], content: '', sig: '' }
411
+ return membersOf(file, [root, ...events]).has(person)
412
+ }
413
+
414
+ /**
415
+ * Every topic the viewer can read, once (SHIPS-2): each with its list, its
416
+ * archive (its own, or with its project), its Folder and whether it is the
417
+ * viewer's — the one read Ship's Topics, a topic's page and Add to topic draw
418
+ * from, and Leaf's Add to topic too.
419
+ *
420
+ * Three rounds whatever the number of topics: every `kind:30840` root; then
421
+ * the topics as drawn, their lists and the viewer's part in them; then the
422
+ * listed ids and archived parents. No conversation is read here:
423
+ * {@link topicConversations} is for a page that draws them.
424
+ *
425
+ * The viewer's part is one read over all history, narrowed to the topics —
426
+ * the changes naming them, what they wrote, what names them — and the
427
+ * horizon's membership is folded from the part of it inside the horizon, as
428
+ * {@link membershipQueries} would have read it for these files. On
429
+ * production, QA-2's horizon read over every file was 500 KB; over the topics
430
+ * it is a few.
431
+ *
432
+ * "Yours" is today's membership fold (§11.8); following replaces it in this
433
+ * same function (Teams and following, milestone 5).
434
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
435
+ */
436
+ export async function readTopics(
437
+ query: QueryFn,
438
+ me: string,
439
+ options: { cache?: ProjectionCache; fileKinds?: readonly number[]; nowSeconds?: number } = {},
440
+ ): Promise<TopicsRead> {
441
+ const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000)
442
+ const rootEvents = await readAll(query, [{ kinds: [KIND_TOPIC] }])
443
+ const roots = new Map<string, SignedEvent>()
444
+ for (const root of rootEvents) {
445
+ if (root.kind !== KIND_TOPIC) continue
446
+ const address = `${root.kind}:${root.pubkey}:${tagOf(root, 'd') ?? ''}`
447
+ const held = roots.get(address)
448
+ // Two versions of one record: NIP-01's later created_at, then the lower id (§6.3).
449
+ if (!held || root.created_at > held.created_at || (root.created_at === held.created_at && root.id < held.id)) roots.set(address, root)
450
+ }
451
+ const addresses = [...roots.keys()]
452
+ if (addresses.length === 0) return { me, topics: [], membership: foldMemberships(me, [], nowSeconds) }
453
+ const [objects, lists, part] = await Promise.all([
454
+ resolveForeignRoots(addresses, query, options.cache, { archivedWith: true }),
455
+ listsOf(query, addresses, Promise.resolve(roots), options),
456
+ // Held once each, though one comment can answer two of the filters: the folds count events.
457
+ readAll(query, personInFilesFilters(me, addresses)),
458
+ ])
459
+ const membership = foldMemberships(me, part.filter((e) => e.created_at >= nowSeconds - HORIZON_SECONDS), nowSeconds)
460
+ // Each topic's own events, so each is folded over its own and not over all of them.
461
+ const byTopic = new Map<string, SignedEvent[]>()
462
+ for (const event of part) for (const file of candidateFilesOf(event)) byTopic.set(file, [...(byTopic.get(file) ?? []), event])
463
+ const none = new Set<string>()
464
+ const topics = objects.flatMap((object): ReadTopic[] => {
465
+ const root = object.address ? roots.get(object.address) : undefined
466
+ const folder = root ? folderOf(root) : null
467
+ if (!root || !folder || object.unreachable) return []
468
+ const address = object.address!
469
+ const yours =
470
+ streamTermsOf(address, membership, me, none).member || (!membershipJudges(address, membership, me) && memberOverAllHistory(me, address, byTopic.get(address) ?? []))
471
+ return [{ address, object, folder, listed: lists.get(address) ?? [], yours }]
472
+ })
473
+ return { me, topics, membership }
474
+ }
475
+
476
+ // An untitled topic sorts where the apps' "Untitled topic" would.
477
+ const titleOf = (topic: ReadTopic) => topic.object.slots.title?.value || 'Untitled topic'
478
+
479
+ /**
480
+ * What Add to topic offers: the open topics in a Folder the viewer is in —
481
+ * `folders`, the Folders the relay lists for them, where it accepts their
482
+ * entry — theirs first, then the rest, each A–Z. An archived topic, its own
483
+ * or with its project, is read-only and is not offered.
484
+ */
485
+ export function addableTopics(read: TopicsRead, folders: ReadonlySet<string>): { yours: ReadTopic[]; others: ReadTopic[] } {
486
+ const open = read.topics
487
+ .filter((topic) => !isArchived(topic.object) && folders.has(topic.folder))
488
+ .sort((a, b) => titleOf(a).localeCompare(titleOf(b)))
489
+ return { yours: open.filter((topic) => topic.yours), others: open.filter((topic) => !topic.yours) }
490
+ }
491
+
492
+ /** A topic's conversations in Peek: how many, and whether one has something new for the viewer. */
493
+ export interface TopicConversation {
494
+ /** Thread roots addressed to the topic, as Peek's Topics badge counts them. */
495
+ conversations: number
496
+ /** Peek's dot: only on an open topic of the viewer's. */
497
+ unread: boolean
498
+ }
499
+
500
+ /**
501
+ * Each topic's conversations and dot, as Peek's Topics shows them (SHIPS-2):
502
+ * the count is the thread roots addressed to the topic (`conversationsOf`),
503
+ * the dot is {@link streamHasUnread} on the topic's own marker, gated by
504
+ * membership (§11.8), on the viewer's open topics only.
505
+ *
506
+ * The read state and the muted list are encrypted, so the app hands in what
507
+ * it holds: `merged` (the merged markers, once the first merge has landed)
508
+ * and `muted`. Replies are read only for the topics a dot is judged on, and
509
+ * only from the latest second before which none can be unread: the thread
510
+ * rule's cut-over, the reply floor, and when the viewer joined (§11.3: a
511
+ * reply is read by its thread's marker or the floor, never the topic's).
512
+ */
513
+ export async function topicConversations(
514
+ read: TopicsRead,
515
+ query: QueryFn,
516
+ state: { merged: Readonly<Record<string, number>>; muted: ReadonlySet<string>; nowSeconds?: number },
517
+ options: { cache?: ProjectionCache } = {},
518
+ ): Promise<Map<string, TopicConversation>> {
519
+ const nowSeconds = state.nowSeconds ?? Math.floor(Date.now() / 1000)
520
+ const terms = (address: string) => streamTermsOf(address, read.membership, read.me, state.muted)
521
+ const judged = new Set(read.topics.filter((topic) => topic.yours && !isArchived(topic.object)).map((topic) => topic.address))
522
+ const repliesSince = (address: string) => {
523
+ if (!judged.has(address)) return null
524
+ const floor = state.merged[REPLY_FLOOR_CONTEXT]
525
+ return Math.max(THREAD_RULE_FROM, floor ?? 0, terms(address).since ?? 0)
526
+ }
527
+ const files = read.topics.map((topic) => ({ ...topic.object, ref: topic.address }))
528
+ const held = await conversationsOf(files, query, options.cache, { replies: true, repliesSince })
529
+ const out = new Map<string, TopicConversation>()
530
+ for (const topic of read.topics) {
531
+ const messages = held[topic.address]
532
+ if (!messages) continue
533
+ const context = fileContext(topic.address)
534
+ const unread =
535
+ !!context &&
536
+ judged.has(topic.address) &&
537
+ streamHasUnread(
538
+ // A reply from before the thread rule's cut-over never lit a row (CON-34).
539
+ messages.filter((m) => m.root === m.id || m.at >= THREAD_RULE_FROM),
540
+ context,
541
+ terms(topic.address),
542
+ { merged: state.merged, me: read.me, nowSeconds, horizonSeconds: HORIZON_SECONDS },
543
+ (id) => read.membership.mentioned.has(id),
544
+ )
545
+ out.set(topic.address, { conversations: messages.filter((m) => m.root === m.id).length, unread })
546
+ }
547
+ return out
548
+ }
549
+
302
550
  /** Each id's address when exactly one file of `fileKinds` the reader can read holds it; an id held by none or by two is left out. */
303
551
  async function resolveIds(query: QueryFn, ids: readonly string[], fileKinds?: readonly number[]): Promise<Map<string, string>> {
304
552
  // Never a Folder's `39000`, which shares its uuid (§11.1): an id only a Folder holds resolves to nothing.