@estiva-app/interop 0.84.0 → 0.86.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.
@@ -0,0 +1,425 @@
1
+ /**
2
+ * The conversations of every file a topic lists, read in one go and kept live
3
+ * — the read behind a topic's All (SPEC §11.8).
4
+ *
5
+ * All reads the files on the topic's list and nothing under them: a listed
6
+ * project's issues, a listed Folder's files and a listed page's sub-pages are
7
+ * not here (Miky, 2026-11-06). Each file's events are returned as the shared
8
+ * fold's input (`foldThreads`, `@estiva-app/conversation`), so the app folds
9
+ * each file as its own pane would and every app draws the same threads.
10
+ *
11
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
12
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/what-belongs-to-a-file-is-stored-with-it.md
13
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-conversation-is-one-shared-thing-and-only-its-colours-are-the-apps.md
14
+ *
15
+ * ## The cold read
16
+ *
17
+ * 1. Every listed file's comments and replies: `kind:1111` by `#A` (its
18
+ * address) and by `#O` (its id), always both (§6.4: a comment may carry
19
+ * either form). The A/O rules decide which file each one is about
20
+ * (`isAbout`), so a comment whose `A` and `O` name different files is about
21
+ * neither. An owning app's older comment kinds (`emits.alsoRead`, Ship's
22
+ * `kind:9`) are read by `#a` when its manifest resolves; a file whose
23
+ * manifest does not resolve still has its `1111`s read.
24
+ * 2. One `#e` read on what those name: edits (`40003`), resolve and reopen
25
+ * (`9101`), deletions (`5`), the older kinds' replies, and reactions (`7`)
26
+ * on each file's newest 100 messages (`REACTION_HORIZON`), as each file's
27
+ * own pane asks (§6.6) — the cut is reported per file.
28
+ *
29
+ * About three requests for a topic of eight files, whatever their number up to
30
+ * `MAX_FILTERS_PER_QUERY / 2`. A listed id the reader cannot resolve is left
31
+ * out, not returned as an unreachable entry: the count is the disclosure
32
+ * (§6.14, §3.2).
33
+ */
34
+ import { MAX_FILTERS_PER_QUERY, RELAY_PAGE_CEILING, referenceToPointer, type LiveRelay, type SignedEvent } from '@estiva-app/protocol'
35
+ import {
36
+ editTargetOf,
37
+ groupThreads,
38
+ isAbout,
39
+ isCommentOn,
40
+ isReply,
41
+ KIND_ASSERTION,
42
+ KIND_COMMENT,
43
+ KIND_DELETION,
44
+ KIND_EDIT,
45
+ KIND_REACTION,
46
+ parentOf,
47
+ reactionHorizon,
48
+ reactionTargetOf,
49
+ resolutionTargetOf,
50
+ } from '@estiva-app/conversation'
51
+ import { commentKindsOf, resolveManifest, type ProjectionCache, type QueryFn } from './projection.js'
52
+ import { topicList, type ListedFile } from './topics.js'
53
+
54
+ /** The bare file has no owner, so no older comment kinds: its comments are `kind:1111` (§6.4). */
55
+ const KIND_BARE_FILE = 30840
56
+ /** Ids per `#e` filter: a comfortable fraction of the relay's page, as `decorationsOf` asks. */
57
+ const IDS_PER_FILTER = 100
58
+
59
+ /** One listed file's conversation, as the shared fold takes it. */
60
+ export interface ListedConversation {
61
+ /** The listed file's id. */
62
+ file: string
63
+ address: string
64
+ /** Its Folder, from its root, or `null` when the root names none. */
65
+ folder: string | null
66
+ /**
67
+ * Every event its threads need, unordered: its comments and their replies,
68
+ * and what the `#e` read returned on them. Pass to `foldThreads`.
69
+ */
70
+ events: SignedEvent[]
71
+ /** A comment read for it came back at the relay's page ceiling: its oldest comments may be missing. */
72
+ commentsCut: boolean
73
+ /** Its messages past the reaction horizon, not asked about reactions (§6.6: a cap is reported). */
74
+ reactionTargetsOmitted: number
75
+ /** Its reaction read came back at the page ceiling, so some reactions may be missing. */
76
+ reactionEventsCut: boolean
77
+ /** Its edit, resolution and deletion read came back at the page ceiling. */
78
+ editEventsCut: boolean
79
+ /** @internal The comment kinds its owning app used to publish, read by `#a` (`emits.alsoRead`). */
80
+ olderKinds: readonly number[]
81
+ }
82
+
83
+ /** What {@link listedConversations} read. */
84
+ export interface ListedConversations {
85
+ /** The listed files the reader can resolve, in the list's order. */
86
+ files: ListedConversation[]
87
+ }
88
+
89
+ /** The conversations of every file the topic at `topic` lists: its list read, then {@link listedConversationsOf}. */
90
+ export async function listedConversations(
91
+ query: QueryFn,
92
+ topic: string,
93
+ options: { cache?: ProjectionCache; fileKinds?: readonly number[] } = {},
94
+ ): Promise<ListedConversations> {
95
+ return listedConversationsOf(query, await topicList(query, topic, options.fileKinds ? { fileKinds: options.fileKinds } : {}), options)
96
+ }
97
+
98
+ /**
99
+ * The conversations of `listed`, a topic's list already read (`topicList`,
100
+ * `readTopics`). Files left unresolved are left out. A refused read is
101
+ * whatever `query` does with one.
102
+ */
103
+ export async function listedConversationsOf(
104
+ query: QueryFn,
105
+ listed: readonly ListedFile[],
106
+ options: { cache?: ProjectionCache } = {},
107
+ ): Promise<ListedConversations> {
108
+ const unique = new Map<string, ListedFile & { address: string }>()
109
+ for (const entry of listed) if (entry.address && !unique.has(entry.address)) unique.set(entry.address, { ...entry, address: entry.address })
110
+ const files = [...unique.values()]
111
+ if (files.length === 0) return { files: [] }
112
+
113
+ const olderKinds = await olderKindsOf(files.map((f) => f.address), query, options.cache)
114
+
115
+ // 1. Comments and replies, two filters per file (three with older kinds), so one busy file cannot starve another.
116
+ const filters = files.flatMap((f) => {
117
+ const older = olderKinds.get(f.address) ?? []
118
+ return [
119
+ { kinds: [KIND_COMMENT], '#A': [f.address], limit: RELAY_PAGE_CEILING },
120
+ { kinds: [KIND_COMMENT], '#O': [f.file], limit: RELAY_PAGE_CEILING },
121
+ ...(older.length > 0 ? [{ kinds: older, '#a': [f.address], limit: RELAY_PAGE_CEILING }] : []),
122
+ ]
123
+ })
124
+ const comments = await readAll(query, filters)
125
+
126
+ const out: ListedConversation[] = files.map((f) => ({
127
+ file: f.file,
128
+ address: f.address,
129
+ folder: f.folder,
130
+ events: [],
131
+ commentsCut: false,
132
+ reactionTargetsOmitted: 0,
133
+ reactionEventsCut: false,
134
+ editEventsCut: false,
135
+ olderKinds: olderKinds.get(f.address) ?? [],
136
+ }))
137
+ for (const conversation of out) {
138
+ const byA = comments.filter((e) => e.kind === KIND_COMMENT && e.tags.some((t) => t[0] === 'A' && t[1] === conversation.address))
139
+ const byO = comments.filter((e) => e.kind === KIND_COMMENT && e.tags.some((t) => t[0] === 'O' && t[1] === conversation.file))
140
+ const byOlder = comments.filter((e) => conversation.olderKinds.includes(e.kind) && e.tags.some((t) => t[0] === 'a' && t[1] === conversation.address))
141
+ conversation.commentsCut = [byA, byO, byOlder].some((answer) => answer.length >= RELAY_PAGE_CEILING)
142
+ conversation.events = comments.filter((e) => belongsAsComment(e, conversation))
143
+ }
144
+
145
+ // 2. What names them by `#e`, one request for every file.
146
+ const targetsOf = out.map((conversation) => {
147
+ const { missingRoots, replies } = groupThreads(conversation.events)
148
+ return [
149
+ ...conversation.events.map((e) => ({ id: e.id, at: e.created_at })),
150
+ ...missingRoots.map((id) => ({ id, at: replies[id]?.[0]?.created_at ?? 0 })),
151
+ ]
152
+ })
153
+ const fileOf = new Map<string, number>()
154
+ targetsOf.forEach((targets, i) => targets.forEach((t) => fileOf.set(t.id, i)))
155
+ const inHorizon = new Set<string>()
156
+ targetsOf.forEach((targets, i) => {
157
+ const { asked, omitted } = reactionHorizon(targets)
158
+ out[i].reactionTargetsOmitted = omitted
159
+ for (const id of asked) inHorizon.add(id)
160
+ })
161
+ const allOlder = [...new Set(out.flatMap((c) => c.olderKinds))]
162
+ const editChunks = chunked([...fileOf.keys()])
163
+ const reactionChunks = chunked([...inHorizon])
164
+ const named = await readAll(query, [
165
+ ...editChunks.map((ids) => ({ kinds: [KIND_EDIT, KIND_ASSERTION, KIND_DELETION, ...allOlder], '#e': ids, limit: RELAY_PAGE_CEILING })),
166
+ ...reactionChunks.map((ids) => ({ kinds: [KIND_REACTION], '#e': ids, limit: RELAY_PAGE_CEILING })),
167
+ ])
168
+
169
+ const have = out.map((c) => new Set(c.events.map((e) => e.id)))
170
+ const answered = { edit: new Array<number>(editChunks.length).fill(0), reaction: new Array<number>(reactionChunks.length).fill(0) }
171
+ const chunkOf = (chunks: string[][]) => new Map(chunks.flatMap((ids, i) => ids.map((id) => [id, i] as const)))
172
+ const editChunkOf = chunkOf(editChunks)
173
+ const reactionChunkOf = chunkOf(reactionChunks)
174
+ for (const event of named) {
175
+ for (const i of filesNamedBy(event, (id) => fileOf.get(id), inHorizon, (i, kind) => out[i].olderKinds.includes(kind))) {
176
+ if (have[i].has(event.id)) continue
177
+ have[i].add(event.id)
178
+ out[i].events.push(event)
179
+ }
180
+ const target = event.kind === KIND_REACTION ? reactionTargetOf(event) : firstNamed(event, editChunkOf)
181
+ const chunk = target === undefined ? undefined : (event.kind === KIND_REACTION ? reactionChunkOf : editChunkOf).get(target)
182
+ if (chunk !== undefined) (event.kind === KIND_REACTION ? answered.reaction : answered.edit)[chunk] += 1
183
+ }
184
+ answered.edit.forEach((n, chunk) => {
185
+ if (n >= RELAY_PAGE_CEILING) for (const id of editChunks[chunk]) out[fileOf.get(id)!].editEventsCut = true
186
+ })
187
+ answered.reaction.forEach((n, chunk) => {
188
+ if (n >= RELAY_PAGE_CEILING) for (const id of reactionChunks[chunk]) out[fileOf.get(id)!].reactionEventsCut = true
189
+ })
190
+
191
+ return { files: out }
192
+ }
193
+
194
+ /** A comment or reply about the file (§6.4's A/O rules), or a root of an older kind the owner declared. */
195
+ function belongsAsComment(event: SignedEvent, conversation: Pick<ListedConversation, 'address' | 'olderKinds'>): boolean {
196
+ if (event.kind === KIND_COMMENT) return isAbout(event, conversation.address)
197
+ return conversation.olderKinds.includes(event.kind) && isCommentOn(event, conversation.address, conversation.olderKinds)
198
+ }
199
+
200
+ /**
201
+ * Which files an event read by `#e` belongs to, by the id it names: an edit's
202
+ * and a resolution's target, a reaction's (only inside its file's horizon), a
203
+ * deletion's every `e`, an older-kind reply's parent.
204
+ */
205
+ function filesNamedBy(
206
+ event: SignedEvent,
207
+ fileOf: (id: string) => number | undefined,
208
+ inHorizon: ReadonlySet<string>,
209
+ olderKindOf: (file: number, kind: number) => boolean,
210
+ ): number[] {
211
+ const one = (id: string | null | undefined) => {
212
+ const i = id ? fileOf(id.toLowerCase()) ?? fileOf(id) : undefined
213
+ return i === undefined ? [] : [i]
214
+ }
215
+ switch (event.kind) {
216
+ case KIND_REACTION: {
217
+ const target = reactionTargetOf(event)
218
+ return target && inHorizon.has(target) ? one(target) : []
219
+ }
220
+ case KIND_EDIT:
221
+ return one(editTargetOf(event))
222
+ case KIND_ASSERTION:
223
+ return one(resolutionTargetOf(event))
224
+ case KIND_DELETION:
225
+ return [...new Set(event.tags.filter((t) => t[0] === 'e' && t[1]).flatMap((t) => one(t[1])))]
226
+ default: {
227
+ if (!isReply(event)) return []
228
+ return one(parentOf(event)).filter((i) => olderKindOf(i, event.kind))
229
+ }
230
+ }
231
+ }
232
+
233
+ /** The first `e` an event names that a chunk holds — what counts it against that chunk's page. */
234
+ function firstNamed(event: SignedEvent, chunkOf: ReadonlyMap<string, number>): string | undefined {
235
+ return event.tags.find((t) => t[0] === 'e' && t[1] && chunkOf.has(t[1]))?.[1]
236
+ }
237
+
238
+ /** Each owned file's older comment kinds, one manifest per app; a manifest that cannot be read declares none. */
239
+ async function olderKindsOf(addresses: readonly string[], query: QueryFn, cache?: ProjectionCache): Promise<Map<string, number[]>> {
240
+ const byApp = new Map<string, string[]>()
241
+ for (const address of addresses) {
242
+ const [kind, pubkey] = address.split(':')
243
+ if (Number(kind) === KIND_BARE_FILE) continue
244
+ const key = `${kind}:${pubkey}`
245
+ byApp.set(key, [...(byApp.get(key) ?? []), address])
246
+ }
247
+ const out = new Map<string, number[]>()
248
+ await Promise.all(
249
+ [...byApp.values()].map(async (owned) => {
250
+ let kinds: number[] = []
251
+ try {
252
+ const resolved = await resolveManifest(referenceToPointer(owned[0]), query, cache)
253
+ kinds = resolved ? commentKindsOf(resolved.manifest).filter((kind) => kind !== KIND_COMMENT) : []
254
+ } catch {
255
+ kinds = []
256
+ }
257
+ for (const address of owned) out.set(address, kinds)
258
+ }),
259
+ )
260
+ return out
261
+ }
262
+
263
+ /** Every filter answered, `MAX_FILTERS_PER_QUERY` per request, each event once. */
264
+ async function readAll(query: QueryFn, filters: Record<string, unknown>[]): Promise<SignedEvent[]> {
265
+ const seen = new Map<string, SignedEvent>()
266
+ for (let start = 0; start < filters.length; start += MAX_FILTERS_PER_QUERY) {
267
+ for (const event of await query(filters.slice(start, start + MAX_FILTERS_PER_QUERY))) if (!seen.has(event.id)) seen.set(event.id, event)
268
+ }
269
+ return [...seen.values()]
270
+ }
271
+
272
+ function chunked<T>(list: readonly T[], size = IDS_PER_FILTER): T[][] {
273
+ const out: T[][] = []
274
+ for (let i = 0; i < list.length; i += size) out.push(list.slice(i, i + size))
275
+ return out
276
+ }
277
+
278
+ /** A live watch's handle. */
279
+ export interface ListedWatch {
280
+ /** Idempotent. Closes its subscriptions. */
281
+ stop(): void
282
+ }
283
+
284
+ /**
285
+ * The most filters one live `REQ` may carry on our relay. Over it, the relay
286
+ * answers only a `NOTICE` ("REQ contains 14 filters, maximum is 10", measured
287
+ * 6 Nov) — no `CLOSED`, no `EOSE` — so a watch past it hears nothing and says
288
+ * nothing. `POST /query` takes 128 (`MAX_FILTERS_PER_QUERY`); a socket does not.
289
+ */
290
+ export const MAX_FILTERS_PER_REQ = 10
291
+
292
+ /** Wait before a watch that has learnt a new id asks again, so a burst of messages costs one new REQ. */
293
+ export const LISTED_WATCH_REBUILD_MS = 250
294
+
295
+ /**
296
+ * Hear, live, every new event on the files `read` holds, each handed to its
297
+ * file: a new comment or reply about one (`#A`, `#O`, and `#a` for an owner's
298
+ * older kinds), and an edit, resolution, reaction or deletion naming any
299
+ * message the watch knows (`#e`). One REQ for all of them (another per
300
+ * {@link MAX_FILTERS_PER_REQ} filters, past about 700 messages), asked again — a
301
+ * moment later, from the newest second it has seen — whenever a new message
302
+ * or reaction gives it another id to listen for, so a reaction to a comment
303
+ * written a second ago is heard. Each event is handed over once; the cold
304
+ * read's are never handed over.
305
+ *
306
+ * ## Naming the files' teams (`namesTeams`, on by default)
307
+ *
308
+ * The decided shape asks by file alone (Miky, 2026-11-06). Our relay does not
309
+ * yet deliver a team's event live to a subscription that names no team
310
+ * (buzz `fan_out_scoped`; measured 6 Nov: by `#A` or `#e` alone, nothing), so
311
+ * until it does every filter also carries the `#h` of each listed file's team
312
+ * and of every team a comment on them was filed in. Turn it off once the
313
+ * relay delivers by file — the Ship issue on the relay in "Topics: Main and
314
+ * All" — and the filters are the decided ones unchanged.
315
+ */
316
+ export function watchListedConversations(
317
+ relay: Pick<LiveRelay, 'subscribe'>,
318
+ read: ListedConversations,
319
+ onEvent: (file: string, event: SignedEvent) => void,
320
+ options: {
321
+ /** Unix seconds to hear from. Defaults to the newest event the read holds, else now. */
322
+ since?: number
323
+ namesTeams?: boolean
324
+ onClosed?: (reason: string) => void
325
+ now?: () => number
326
+ setTimer?: (run: () => void, ms: number) => unknown
327
+ clearTimer?: (timer: unknown) => void
328
+ } = {},
329
+ ): ListedWatch {
330
+ const files = read.files.map((c) => ({ ...c, ids: new Set(c.events.map((e) => e.id)) }))
331
+ // This package assumes no environment's typings; every JS runtime has both.
332
+ const timers = globalThis as unknown as { setTimeout(run: () => void, ms: number): unknown; clearTimeout(timer: unknown): void }
333
+ const setTimer = options.setTimer ?? ((run: () => void, ms: number) => timers.setTimeout(run, ms))
334
+ const clearTimer = options.clearTimer ?? ((timer: unknown) => timers.clearTimeout(timer))
335
+ const seen = new Set(files.flatMap((f) => [...f.ids]))
336
+ const teams = new Set<string>()
337
+ for (const f of read.files) {
338
+ if (f.folder) teams.add(f.folder)
339
+ for (const e of f.events) if (e.kind !== KIND_REACTION && e.kind !== KIND_DELETION) addTeam(teams, e)
340
+ }
341
+ const nowSeconds = () => Math.floor((options.now ?? Date.now)() / 1000)
342
+ // `created_at` is the author's to write (the relay takes 15 min ahead): `since` never passes the reader's own clock.
343
+ const newest = Math.max(0, ...read.files.flatMap((f) => f.events.map((e) => e.created_at)))
344
+ let since = options.since ?? (newest > 0 ? Math.min(newest, nowSeconds()) : nowSeconds())
345
+ const namesTeams = options.namesTeams ?? true
346
+
347
+ let subs: { close(): void }[] = []
348
+ let timer: unknown = null
349
+ let stopped = false
350
+
351
+ const filtersNow = (): Record<string, unknown>[] => {
352
+ const older = [...new Set(files.flatMap((f) => f.olderKinds))]
353
+ const byFile: Record<string, unknown>[] = [
354
+ { kinds: [KIND_COMMENT], '#A': files.map((f) => f.address) },
355
+ { kinds: [KIND_COMMENT], '#O': files.map((f) => f.file) },
356
+ ...(older.length > 0 ? [{ kinds: older, '#a': files.filter((f) => f.olderKinds.length > 0).map((f) => f.address) }] : []),
357
+ ...chunked([...new Set(files.flatMap((f) => [...f.ids]))]).map((ids) => ({
358
+ kinds: [KIND_REACTION, KIND_DELETION, KIND_EDIT, KIND_ASSERTION, ...older],
359
+ '#e': ids,
360
+ })),
361
+ ]
362
+ const teamChunks = namesTeams && teams.size > 0 ? chunked([...teams], 128) : [undefined]
363
+ return teamChunks.flatMap((h) => byFile.map((f) => ({ ...f, ...(h ? { '#h': h } : {}), since })))
364
+ }
365
+
366
+ const open = () => {
367
+ for (const sub of subs) sub.close()
368
+ subs = chunked(filtersNow(), MAX_FILTERS_PER_REQ).map((filters) =>
369
+ relay.subscribe(filters, hear, options.onClosed ? { onClosed: options.onClosed } : undefined),
370
+ )
371
+ }
372
+ const reopenSoon = () => {
373
+ if (stopped || timer !== null) return
374
+ timer = setTimer(() => {
375
+ timer = null
376
+ if (!stopped) open()
377
+ }, LISTED_WATCH_REBUILD_MS)
378
+ }
379
+
380
+ function hear(event: SignedEvent) {
381
+ if (stopped || seen.has(event.id)) return
382
+ const fileOf = (id: string) => {
383
+ const i = files.findIndex((f) => f.ids.has(id) || f.ids.has(id.toLowerCase()))
384
+ return i === -1 ? undefined : i
385
+ }
386
+ const everyId = new Set(files.flatMap((f) => [...f.ids]))
387
+ const owners =
388
+ event.kind === KIND_COMMENT || files.some((f) => f.olderKinds.includes(event.kind) && !isReply(event))
389
+ ? files.flatMap((f, i) => (belongsAsComment(event, f) ? [i] : []))
390
+ : filesNamedBy(event, fileOf, everyId, (i, kind) => files[i].olderKinds.includes(kind))
391
+ if (owners.length === 0) return
392
+ seen.add(event.id)
393
+ since = Math.max(since, Math.min(event.created_at, nowSeconds()))
394
+ let learnt = false
395
+ for (const i of owners) {
396
+ if (event.kind !== KIND_DELETION && !files[i].ids.has(event.id)) {
397
+ files[i].ids.add(event.id)
398
+ learnt = true
399
+ }
400
+ onEvent(files[i].file, event)
401
+ }
402
+ if (event.kind !== KIND_REACTION && event.kind !== KIND_DELETION) {
403
+ const before = teams.size
404
+ addTeam(teams, event)
405
+ if (teams.size !== before) learnt = true
406
+ }
407
+ if (learnt) reopenSoon()
408
+ }
409
+
410
+ open()
411
+ return {
412
+ stop() {
413
+ if (stopped) return
414
+ stopped = true
415
+ if (timer !== null) clearTimer(timer)
416
+ for (const sub of subs) sub.close()
417
+ subs = []
418
+ },
419
+ }
420
+ }
421
+
422
+ function addTeam(teams: Set<string>, event: SignedEvent): void {
423
+ const h = event.tags.find((t) => t[0] === 'h' && t[1])?.[1]
424
+ if (h) teams.add(h)
425
+ }
package/src/projection.ts CHANGED
@@ -7501,6 +7501,59 @@ export async function resolveFolderContents(
7501
7501
  }
7502
7502
  }
7503
7503
 
7504
+ /**
7505
+ * The deleted files a Folder lists, each with its `deleted` (SPEC §6.5): what
7506
+ * an Archive's Deleted filter draws, with who deleted each and when. A deleted
7507
+ * file stays listed in its Folder and every list leaves it out
7508
+ * ({@link resolveFolderContents}), so this is a read of its own, made where it
7509
+ * is drawn and nowhere else.
7510
+ *
7511
+ * With `listRead`, the Folder's files of the relay's file kinds are listed by
7512
+ * their fields first, in one request, and only the ones that answer nothing —
7513
+ * deleted, or not this reader's — are read whole: a deleted file is in no read
7514
+ * by its fields (§6.13), but stays readable by its id. Without it, each is read
7515
+ * whole, as every read was before.
7516
+ */
7517
+ export async function resolveDeletedFiles(
7518
+ folder: string,
7519
+ query: QueryFn,
7520
+ lookupPeople?: PeopleFn,
7521
+ cache?: ProjectionCache,
7522
+ options: { listRead?: boolean } = {},
7523
+ ): Promise<ForeignObject[]> {
7524
+ const [state] = await query([{ kinds: [KIND_FOLDER_STATE], '#d': [folder], limit: 1 }])
7525
+ const everyAddress =
7526
+ state && tagValue(state, 'd') === folder
7527
+ ? await listedAddressesOf(state, query)
7528
+ : (await addressesByContainment(folder, query)).addresses
7529
+ const files = everyAddress.flatMap((address) => {
7530
+ const pointer = addressPointerOf(address)
7531
+ return pointer && FILE_KINDS.includes(pointer.kind) ? [{ address, pointer }] : []
7532
+ })
7533
+ let asked = files.map(({ address }) => address)
7534
+ if (options.listRead && files.length) {
7535
+ const groups = new Map<string, { pointer: AddressPointer; ds: string[] }>()
7536
+ for (const { pointer } of files) {
7537
+ const key = `${pointer.kind}:${pointer.pubkey}`
7538
+ const group = groups.get(key)
7539
+ if (group) group.ds.push(pointer.identifier)
7540
+ else groups.set(key, { pointer, ds: [pointer.identifier] })
7541
+ }
7542
+ const listed = await queryChunked(
7543
+ [...groups.values()].map(({ pointer, ds }) => ({ kinds: [pointer.kind], authors: [pointer.pubkey], '#d': ds, limit: ds.length, fields: 'newest' })),
7544
+ query,
7545
+ )
7546
+ const answered = new Set(listed.filter((e) => FILE_KINDS.includes(e.kind)).map((e) => `${e.kind}:${e.pubkey}:${tagValue(e, 'd') ?? ''}`))
7547
+ asked = asked.filter((address) => !answered.has(address))
7548
+ }
7549
+ if (!asked.length) return []
7550
+ const objects = await resolveForeignObjects(asked, query, lookupPeople, cache)
7551
+ return asked.flatMap((address) => {
7552
+ const object = objects[address]
7553
+ return object && !object.unreachable && object.deleted ? [object] : []
7554
+ })
7555
+ }
7556
+
7504
7557
  /**
7505
7558
  * A Folder state's files as addresses, in its order, each once (SPEC §3.3).
7506
7559
  *
package/src/references.ts CHANGED
@@ -59,11 +59,12 @@ const typeOf = (kind: number): ReferenceType | undefined => REFERENCE_FILE_TYPES
59
59
 
60
60
  type Addressed = ForeignObject & { address: string }
61
61
 
62
- /** An object `[` may offer: a file kind it knows, resolved, with a title. */
62
+ /** An object `[` may offer: a file kind it knows, resolved, not deleted (SPEC §6.5), with a title. */
63
63
  const offerable = (object: ForeignObject | null | undefined): object is Addressed =>
64
64
  !!object &&
65
65
  !!object.address &&
66
66
  !object.unreachable &&
67
+ !object.deleted &&
67
68
  typeOf(object.kind) !== undefined &&
68
69
  !!object.slots.title?.value.trim()
69
70
 
@@ -123,13 +124,14 @@ export async function fileCandidates(
123
124
  ): Promise<ReferenceCandidate[]> {
124
125
  const files = objects.filter(offerable)
125
126
  const parents = new Map<string, ForeignObject>()
126
- for (const o of objects) if (o?.address && !o.unreachable) parents.set(o.address, o)
127
+ // A deleted project names no issue's caption: it is found nowhere else either (SPEC §6.5).
128
+ for (const o of objects) if (o?.address && !o.unreachable && !o.deleted) parents.set(o.address, o)
127
129
  const missing = [
128
130
  ...new Set(files.flatMap((o) => (o.kind === KIND_ISSUE && o.parentRef && !parents.has(o.parentRef) ? [o.parentRef] : []))),
129
131
  ]
130
132
  if (missing.length) {
131
133
  const read = await resolveForeignRoots(missing, query, cache, { listRead }).catch(() => [])
132
- for (const parent of read) if (parent.address) parents.set(parent.address, parent)
134
+ for (const parent of read) if (parent.address && !parent.deleted) parents.set(parent.address, parent)
133
135
  }
134
136
  return files.map((o) => {
135
137
  const parent = o.kind === KIND_ISSUE && o.parentRef ? parents.get(o.parentRef) : undefined
package/src/topics.ts CHANGED
@@ -270,6 +270,8 @@ export interface ListedFile {
270
270
  file: string
271
271
  /** Its address when exactly one file the reader can read holds the id, else `null`: not drawn, not counted. */
272
272
  address: string | null
273
+ /** The resolved file's Folder, from its root (§6.2), when it names one; `null` when unresolved or it names none. */
274
+ folder: string | null
273
275
  entry: ListEntry
274
276
  }
275
277
 
@@ -329,7 +331,10 @@ async function listsOf(
329
331
  .sort((a, b) => byOrder(a.event, b.event))
330
332
  if (entries.length === 0) return out
331
333
  const resolved = await resolveIds(query, [...new Set(entries.map((entry) => entry.file))], options.fileKinds)
332
- for (const entry of entries) out.get(entry.list)!.push({ file: entry.file, address: resolved.get(entry.file) ?? null, entry })
334
+ for (const entry of entries) {
335
+ const held = resolved.get(entry.file)
336
+ out.get(entry.list)!.push({ file: entry.file, address: held?.address ?? null, folder: held?.folder ?? null, entry })
337
+ }
333
338
  return out
334
339
  }
335
340
 
@@ -605,7 +610,11 @@ export async function topicConversations(
605
610
  }
606
611
 
607
612
  /** 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. */
608
- async function resolveIds(query: QueryFn, ids: readonly string[], fileKinds?: readonly number[]): Promise<Map<string, string>> {
613
+ async function resolveIds(
614
+ query: QueryFn,
615
+ ids: readonly string[],
616
+ fileKinds?: readonly number[],
617
+ ): Promise<Map<string, { address: string; folder: string | null }>> {
609
618
  // Never a Folder's `39000`, which shares its uuid (§11.1): an id only a Folder holds resolves to nothing.
610
619
  const kinds = (fileKinds ?? LISTED_FILE_KINDS).filter((kind) => kind !== KIND_FOLDER)
611
620
  // Room for a second holder of every id, so two holders are seen as two; in
@@ -617,15 +626,22 @@ async function resolveIds(query: QueryFn, ids: readonly string[], fileKinds?: re
617
626
  // first), and one holder would then pass for the only one: every id of that
618
627
  // batch stays unresolved rather than drawn as somebody else's file.
619
628
  const unsure = new Set(batches.flatMap((batch, i) => (answers[i].length >= batch.length * 2 ? batch : [])))
620
- const holders = new Map<string, Set<string>>()
629
+ // Each holder's newest root: a replaceable file the relay still holds two versions of names its Folder by the newer.
630
+ const holders = new Map<string, Map<string, SignedEvent>>()
621
631
  for (const event of answers.flat()) {
622
632
  const d = tagOf(event, 'd')
623
633
  if (!d || !kinds.includes(event.kind)) continue
624
- const set = holders.get(d) ?? new Set<string>()
625
- set.add(`${event.kind}:${event.pubkey}`)
626
- holders.set(d, set)
634
+ const roots = holders.get(d) ?? new Map<string, SignedEvent>()
635
+ const holder = `${event.kind}:${event.pubkey}`
636
+ const kept = roots.get(holder)
637
+ if (!kept || event.created_at > kept.created_at) roots.set(holder, event)
638
+ holders.set(d, roots)
639
+ }
640
+ const out = new Map<string, { address: string; folder: string | null }>()
641
+ for (const [d, roots] of holders) {
642
+ if (roots.size !== 1 || unsure.has(d)) continue
643
+ const [[holder, root]] = roots
644
+ out.set(d, { address: `${holder}:${d}`, folder: folderOf(root) })
627
645
  }
628
- const out = new Map<string, string>()
629
- for (const [d, set] of holders) if (set.size === 1 && !unsure.has(d)) out.set(d, `${[...set][0]}:${d}`)
630
646
  return out
631
647
  }