@estiva-app/interop 0.88.0 → 0.90.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,524 @@
1
+ /**
2
+ * Your topics, newest activity first: the one shared rule Peek, Ship and Leaf
3
+ * order topics by (TOPI-10; Miky, 2026-11-06, "Where anything moved").
4
+ *
5
+ * A topic's time is when anything last happened in it, deep:
6
+ *
7
+ * - a message or reply in its own conversation (`kind:1111`/`9` with its `A`);
8
+ * - a change to the topic itself, except tidying it: its `order:<d>` and
9
+ * `look:<d>` (arranging, a row/card switch), a file taken off its list
10
+ * (`lists:<d>` = `false`) — a file put on it counts;
11
+ * - a change to, or a comment on, any file its list holds, and on every file
12
+ * under one: a listed project's issues, a listed document's pages, any depth
13
+ * (the newest {@link MAX_CHILDREN} under each);
14
+ * - a new file under one (an issue filed in a listed project).
15
+ *
16
+ * Never, anywhere: a rename (`title`, on the topic or any file; Miky,
17
+ * 2026-11-09), who is on a file or at what level (`member:<P>`, `follow:<P>`,
18
+ * §11.8) — joining would move a topic up for everyone — and read state
19
+ * (`kind:30078`). The agent's own writes count like anyone's.
20
+ *
21
+ * An event counts only on the file it is on as the fold reads it, never by a
22
+ * tag alone: a change by its first `a`, in its file's own team (`h`); a
23
+ * comment by its root, never a crossed one; a new file by its one `a`.
24
+ * With nothing else, a topic's time is its first record's.
25
+ *
26
+ * Every `created_at` is the author's to write, and the relay takes one up to
27
+ * 15 minutes ahead: each time is capped at the reader's clock, so a
28
+ * future-dated event cannot pin a topic to the top.
29
+ *
30
+ * Two people's orders may differ where a listed file sits in a team only one
31
+ * of them reads; nothing unreadable is revealed, since each reads as itself.
32
+ *
33
+ * The rule takes any set of topics, so an Explore page orders every topic the
34
+ * reader can open with the same read ({@link readTopicActivity}), and a live
35
+ * app keeps it current with {@link watchTopicActivity}.
36
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/each-file-on-a-topic-keeps-its-own-place-and-look.md
37
+ */
38
+ import { fileIdOf, MAX_FILTERS_PER_QUERY, type LiveRelay, type SignedEvent } from '@estiva-app/protocol'
39
+ import { isAbout, KIND_COMMENT } from '@estiva-app/conversation'
40
+ import { folderOf, KIND_MESSAGE, type QueryFn } from './projection.js'
41
+ import { answers, readAll, type ReadTopic } from './topics.js'
42
+ import { LISTED_WATCH_REBUILD_MS, MAX_FILTERS_PER_REQ } from './listedConversations.js'
43
+
44
+ const KIND_CHANGE = 1851
45
+ const KIND_READ_STATE = 30078
46
+ const KIND_PROJECT = 30850
47
+ const KIND_ISSUE = 30851
48
+ const KIND_DOCUMENT = 30842
49
+ /** What may sit under a file, by the file's kind: a project's issues, a document's pages (§6.7). */
50
+ const CHILD_KINDS: Readonly<Record<number, readonly number[]>> = {
51
+ [KIND_PROJECT]: [KIND_ISSUE],
52
+ [KIND_DOCUMENT]: [KIND_DOCUMENT],
53
+ }
54
+ /** How deep the pages under a listed document are walked. */
55
+ const MAX_DEPTH = 8
56
+ /** The newest files under one parent that are read and listened to: a team member filing thousands cannot multiply the reads. */
57
+ const MAX_CHILDREN = 500
58
+ /** Newest events asked per target in the first round; a target whose page holds only what does not count is asked again, older. */
59
+ const FIRST_PAGE = 1
60
+ const MAX_ROUNDS = 6
61
+ const ADDRESS = /^(\d+):([0-9a-f]{64}):(.+)$/
62
+ /** Values per tag in one live filter: the watch's filters stay small whatever the number of files. */
63
+ const VALUES_PER_FILTER = 100
64
+
65
+ /** A file whose activity is a topic's: on its list, or under a file on it. */
66
+ export interface ActivityFile {
67
+ /** Its address, `<kind>:<pubkey>:<d>`. */
68
+ address: string
69
+ /** Its team, from its root (§6.2), when the reader holds it: a live watch names it. */
70
+ folder: string | null
71
+ }
72
+
73
+ /** A topic to order, as the reader holds it. */
74
+ export interface ActivityTopic {
75
+ /** Its address. */
76
+ address: string
77
+ /** Its first record's time (Unix seconds): its time, when nothing has happened in it since. */
78
+ createdAt?: number
79
+ /** Its team, from its root: a change to it counts only in it, and a live watch names it. */
80
+ folder?: string | null
81
+ /** The files its list holds. A file under one of them is found by the read. */
82
+ files: readonly ActivityFile[]
83
+ }
84
+
85
+ /** {@link readTopicActivity}'s answer, and what {@link watchTopicActivity} keeps current. */
86
+ export interface TopicActivity {
87
+ /** Each topic asked for, by address: Unix seconds of the newest thing that happened in it, capped at the reader's clock; 0 when nothing is known. */
88
+ at: Map<string, number>
89
+ /** Each topic's files, by address: the listed ones and every file under them. */
90
+ files: Map<string, ActivityFile[]>
91
+ /** Each topic's team, as asked. */
92
+ folders: Map<string, string | null>
93
+ }
94
+
95
+ /** {@link ActivityTopic}s from {@link readTopics}' answer: each topic with its resolved list. */
96
+ export function activityTopics(topics: readonly ReadTopic[]): ActivityTopic[] {
97
+ return topics.map((topic) => ({
98
+ address: topic.address,
99
+ createdAt: topic.createdAt,
100
+ folder: topic.folder,
101
+ files: topic.listed.flatMap((listed) => (listed.address ? [{ address: listed.address, folder: listed.folder }] : [])),
102
+ }))
103
+ }
104
+
105
+ /** The fields a change sets: `field`, or one `set` per field. */
106
+ function fieldsOf(event: SignedEvent): { field: string; value: string | undefined }[] {
107
+ const out: { field: string; value: string | undefined }[] = []
108
+ for (const tag of event.tags) {
109
+ if (tag[0] === 'set' && tag[1]) out.push({ field: tag[1], value: tag[2] })
110
+ }
111
+ const field = event.tags.find((tag) => tag[0] === 'field')?.[1]
112
+ if (field) out.push({ field, value: event.tags.find((tag) => tag[0] === 'value')?.[1] })
113
+ return out
114
+ }
115
+
116
+ /**
117
+ * Whether an event is news for the topic it is read for: the rule above,
118
+ * event by event. `topic` is the address of the topic being ordered, so a
119
+ * change to the topic itself is judged as tidying or not.
120
+ */
121
+ export function countsAsActivity(event: SignedEvent, topic: string): boolean {
122
+ if (event.kind === KIND_READ_STATE) return false
123
+ if (event.kind !== KIND_CHANGE) return true
124
+ // A change's file is its first `a` (§6.10); any later one is no target.
125
+ const own = tagValues(event, 'a')[0] === topic
126
+ return fieldsOf(event).some(({ field, value }) => {
127
+ // A rename moves nothing, on the topic or on any file (Miky, 2026-11-09).
128
+ if (field.startsWith('member:') || field.startsWith('follow:') || field === 'title') return false
129
+ if (!own) return true
130
+ if (field.startsWith('order:') || field.startsWith('look:')) return false
131
+ if (field.startsWith('lists:')) return value === 'true'
132
+ return true
133
+ })
134
+ }
135
+
136
+ /** Newest first, then by address: the order of a set of topics, from {@link TopicActivity.at}. */
137
+ export function byActivity(at: ReadonlyMap<string, number>): (a: string, b: string) => number {
138
+ return (a, b) => (at.get(b) ?? 0) - (at.get(a) ?? 0) || (a < b ? -1 : a > b ? 1 : 0)
139
+ }
140
+
141
+ function idOf(address: string): string | undefined {
142
+ return ADDRESS.exec(address)?.[3]
143
+ }
144
+ function kindOf(address: string): number | undefined {
145
+ const m = ADDRESS.exec(address)
146
+ return m ? Number(m[1]) : undefined
147
+ }
148
+ function tagValues(event: SignedEvent, name: string): string[] {
149
+ return event.tags.filter((tag) => tag[0] === name && tag[1]).map((tag) => tag[1]!)
150
+ }
151
+
152
+ /**
153
+ * Whether an event is on the file at `address` (whose root names `folder`),
154
+ * as the fold reads it, rather than merely tagging it: a change by its first
155
+ * `a`, its `O` when it carries one, and its file's own team in `h` (§6.10); a
156
+ * comment by its root (`isAbout`: its one `A`, or its `O` when it has no root,
157
+ * never a crossed one, §6.4); a message by its first `A`. Anybody may tag any
158
+ * file, so a tag alone would let a write in one team move a topic in another.
159
+ */
160
+ function isOn(event: SignedEvent, address: string, folder: string | null): boolean {
161
+ if (event.kind === KIND_CHANGE) {
162
+ const id = tagValues(event, 'O')[0]
163
+ return tagValues(event, 'a')[0] === address && (id === undefined || id === idOf(address)) && tagValues(event, 'h')[0] === (folder ?? undefined)
164
+ }
165
+ if (event.kind === KIND_COMMENT) return isAbout(event, address)
166
+ return tagValues(event, 'A')[0] === address
167
+ }
168
+
169
+ async function queryChunked(query: QueryFn, filters: readonly Record<string, unknown>[]): Promise<SignedEvent[]> {
170
+ const runs: Promise<SignedEvent[]>[] = []
171
+ for (let i = 0; i < filters.length; i += MAX_FILTERS_PER_QUERY) runs.push(query(filters.slice(i, i + MAX_FILTERS_PER_QUERY)))
172
+ return (await Promise.all(runs)).flat()
173
+ }
174
+
175
+ /**
176
+ * Every file under the given ones, any depth: a project's issues, a
177
+ * document's pages, each by its root's `a` (§6.7). One request per level.
178
+ * Each found file with its root's team and its root's time.
179
+ */
180
+ async function filesUnder(
181
+ query: QueryFn,
182
+ parents: readonly string[],
183
+ ): Promise<{ parent: string; file: ActivityFile; at: number }[]> {
184
+ const out: { parent: string; file: ActivityFile; at: number }[] = []
185
+ // Each file under one is answered once per parent, even when it is listed itself (on another topic, say);
186
+ // each parent is walked once.
187
+ const found = new Set<string>()
188
+ let level = parents.filter((address) => CHILD_KINDS[kindOf(address) ?? -1])
189
+ const walked = new Set(level)
190
+ for (let depth = 0; depth < MAX_DEPTH && level.length > 0; depth++) {
191
+ const kinds = [...new Set(level.flatMap((address) => CHILD_KINDS[kindOf(address)!]!))]
192
+ const filters: Record<string, unknown>[] = []
193
+ for (let i = 0; i < level.length; i += VALUES_PER_FILTER) filters.push({ kinds, '#a': level.slice(i, i + VALUES_PER_FILTER) })
194
+ // Every one, however many: paged past the relay's cap rather than cut at it.
195
+ const roots = await readAll(query, filters)
196
+ const asked = new Set(level)
197
+ const next: string[] = []
198
+ // A replaceable root the relay still holds twice is one file: its newest names its team.
199
+ const newest = new Map<string, { root: SignedEvent; parent: string }>()
200
+ for (const root of roots) {
201
+ const d = tagValues(root, 'd')[0]
202
+ // A root's parent is its one `a` (§6.7): a later one is no parent.
203
+ const parent = tagValues(root, 'a')[0]
204
+ if (!d || !parent || !asked.has(parent) || !(CHILD_KINDS[kindOf(parent)!] ?? []).includes(root.kind)) continue
205
+ const address = `${root.kind}:${root.pubkey}:${d}`
206
+ const held = newest.get(address)
207
+ if (!held || root.created_at > held.root.created_at) newest.set(address, { root, parent })
208
+ }
209
+ const perParent = new Map<string, number>()
210
+ for (const [address, { root, parent }] of [...newest].sort((a, b) => b[1].root.created_at - a[1].root.created_at)) {
211
+ const count = perParent.get(parent) ?? 0
212
+ if (count >= MAX_CHILDREN) continue
213
+ perParent.set(parent, count + 1)
214
+ if (found.has(`${parent} ${address}`)) continue
215
+ found.add(`${parent} ${address}`)
216
+ out.push({ parent, file: { address, folder: folderOf(root) }, at: root.created_at })
217
+ if (CHILD_KINDS[root.kind] && !walked.has(address)) {
218
+ walked.add(address)
219
+ next.push(address)
220
+ }
221
+ }
222
+ level = next
223
+ }
224
+ return out
225
+ }
226
+
227
+ /** One thing to find the newest counting event of: a filter, the file it is on, and the topics its answer is news for. */
228
+ interface Probe {
229
+ filter: Record<string, unknown>
230
+ target: ActivityFile
231
+ topics: string[]
232
+ }
233
+
234
+ /**
235
+ * Each topic's newest activity (the rule above), for any set of topics the
236
+ * reader holds — theirs, or every one they can open.
237
+ *
238
+ * Reads, whatever the number of topics: one request per level of files under
239
+ * the listed ones (a project's issues, then each further level of pages),
240
+ * then the newest few events of each topic's conversation and own changes and
241
+ * of each file's changes and comments, every target one filter in the same
242
+ * request (another per {@link MAX_FILTERS_PER_QUERY}). A target whose newest
243
+ * events are all tidying is asked again from older ones, up to a few rounds.
244
+ *
245
+ * Measured 9 Nov 2026 on production over the 47 topics the agent can read
246
+ * (Miky is in 24 of them): about 1.9 MB in 7 requests, 1 s. Most of it is the
247
+ * newest text save of a file, which carries the whole text, and the roots of
248
+ * the issues under listed projects.
249
+ *
250
+ * `query` answers each filter as one request would, honouring `limit` and
251
+ * `until` (the apps' viewer query does). A failed read rejects.
252
+ */
253
+ export async function readTopicActivity(
254
+ query: QueryFn,
255
+ topics: readonly ActivityTopic[],
256
+ options: { nowSeconds?: number } = {},
257
+ ): Promise<TopicActivity> {
258
+ const now = options.nowSeconds ?? Math.floor(Date.now() / 1000)
259
+ const capped = (at: number) => Math.min(at, now)
260
+ const at = new Map<string, number>()
261
+ const files = new Map<string, ActivityFile[]>()
262
+ const folders = new Map<string, string | null>()
263
+ for (const topic of topics) {
264
+ at.set(topic.address, topic.createdAt ? capped(topic.createdAt) : 0)
265
+ files.set(topic.address, [...topic.files])
266
+ folders.set(topic.address, topic.folder ?? null)
267
+ }
268
+ if (topics.length === 0) return { at, files, folders }
269
+ const bump = (topic: string, when: number) => {
270
+ if (capped(when) > (at.get(topic) ?? 0)) at.set(topic, capped(when))
271
+ }
272
+
273
+ // Which topics each file is on (a file can be on several), then the files under them.
274
+ const topicsOf = new Map<string, Set<string>>()
275
+ const onTopic = (file: string, topic: string) => {
276
+ const set = topicsOf.get(file) ?? new Set<string>()
277
+ set.add(topic)
278
+ topicsOf.set(file, set)
279
+ }
280
+ for (const topic of topics) for (const file of topic.files) onTopic(file.address, topic.address)
281
+ const listed = new Map([...topicsOf].map(([file, on]) => [file, new Set(on)]))
282
+
283
+ // Each listed file's team, from its root, for the changes' `h`.
284
+ const folderOfFile = new Map<string, string | null>()
285
+ for (const topic of topics) for (const file of topic.files) if (!folderOfFile.get(file.address)) folderOfFile.set(file.address, file.folder)
286
+
287
+ const fileProbes = (target: ActivityFile, list: string[]): Probe[] => {
288
+ const file = target.address
289
+ const id = fileIdOf(file)
290
+ // Every change carries the file's `a`; its `O` only since 30 Oct 2026. A comment carries `A`, or `O` in its newer form (§6.4).
291
+ return [
292
+ { filter: { kinds: [KIND_CHANGE], '#a': [file] }, target, topics: list },
293
+ { filter: { kinds: [KIND_COMMENT], '#A': [file] }, target, topics: list },
294
+ ...(id ? [{ filter: { kinds: [KIND_COMMENT], '#O': [id] }, target, topics: list }] : []),
295
+ ]
296
+ }
297
+ const first: Probe[] = []
298
+ for (const topic of topics) {
299
+ const target = { address: topic.address, folder: topic.folder ?? null }
300
+ first.push({ filter: { kinds: [KIND_COMMENT, KIND_MESSAGE], '#A': [topic.address] }, target, topics: [topic.address] })
301
+ first.push({ filter: { kinds: [KIND_CHANGE], '#a': [topic.address] }, target, topics: [topic.address] })
302
+ }
303
+ for (const [file, on] of listed) first.push(...fileProbes({ address: file, folder: folderOfFile.get(file) ?? null }, [...on]))
304
+
305
+ // The topics and their listed files are read while the files under them are found, and those as soon as they are.
306
+ const deep = async () => {
307
+ const under = await filesUnder(query, [...listed.keys()])
308
+ // Parents come before their children in `under`, so a page two levels down inherits its topics.
309
+ for (const { parent, file, at: created } of under) {
310
+ for (const topic of topicsOf.get(parent) ?? []) {
311
+ if (!topicsOf.get(file.address)?.has(topic)) files.get(topic)!.push(file)
312
+ onTopic(file.address, topic)
313
+ // A new issue filed in a listed project is news.
314
+ bump(topic, created)
315
+ }
316
+ }
317
+ const then: Probe[] = []
318
+ const asFound = new Map(under.map((found) => [found.file.address, found.file]))
319
+ for (const [file, target] of asFound) {
320
+ // Only for the topics it was not already read for as a listed file.
321
+ const fresh = [...(topicsOf.get(file) ?? [])].filter((topic) => !listed.get(file)?.has(topic))
322
+ if (fresh.length > 0) then.push(...fileProbes(target, fresh))
323
+ }
324
+ await newestOf(then)
325
+ }
326
+ await Promise.all([deep(), newestOf(first)])
327
+ return { at, files, folders }
328
+
329
+ /** Per probe, the newest event that counts for one of its topics. Read in rounds; each round asks only what is still open. */
330
+ async function newestOf(probes: readonly Probe[]): Promise<void> {
331
+ let open = probes.map((probe) => ({ probe, filter: { ...probe.filter, limit: FIRST_PAGE } as Record<string, unknown> }))
332
+ for (let round = 0; round < MAX_ROUNDS && open.length > 0; round++) {
333
+ const events = await queryChunked(query, open.map((o) => o.filter))
334
+ const still: typeof open = []
335
+ for (const o of open) {
336
+ const page = events.filter((event) => answers(event, o.filter)).sort((a, b) => b.created_at - a.created_at)
337
+ const left = new Set(o.probe.topics)
338
+ for (const event of page) {
339
+ if (!isOn(event, o.probe.target.address, o.probe.target.folder)) continue
340
+ for (const topic of [...left]) {
341
+ if (!countsAsActivity(event, topic)) continue
342
+ bump(topic, event.created_at)
343
+ left.delete(topic)
344
+ }
345
+ if (left.size === 0) break
346
+ }
347
+ const limit = o.filter.limit as number
348
+ if (left.size === 0 || page.length < limit) continue
349
+ const until = page[page.length - 1]!.created_at
350
+ // A second holding a whole page on its own: ask a bigger page of it rather than step past it.
351
+ const same = until === (o.filter.until as number | undefined)
352
+ still.push({ probe: { ...o.probe, topics: [...left] }, filter: { ...o.probe.filter, until, limit: same ? limit * 4 : limit * 2 } })
353
+ }
354
+ open = still
355
+ }
356
+ }
357
+ }
358
+
359
+ /** A live watch's handle. */
360
+ export interface ActivityWatch {
361
+ /** Idempotent. Closes its subscriptions. */
362
+ stop(): void
363
+ }
364
+
365
+ function chunked<T>(list: readonly T[], size: number): T[][] {
366
+ const out: T[][] = []
367
+ for (let i = 0; i < list.length; i += size) out.push(list.slice(i, i + size))
368
+ return out
369
+ }
370
+
371
+ /**
372
+ * Keep {@link TopicActivity} current, live: hear every new event that is news
373
+ * for a topic it holds (the rule above), raise that topic's time, and say so.
374
+ * A new file under a listed one (an issue filed in a listed project) is news,
375
+ * and its own activity is heard from then on.
376
+ *
377
+ * One REQ for every topic (another per {@link MAX_FILTERS_PER_REQ} filters).
378
+ * `onActivity` is called with the topic and its new time, after `activity.at`
379
+ * is raised in place; an event that is not news, or older than what is held,
380
+ * says nothing.
381
+ *
382
+ * As {@link watchListedConversations} does, every filter also names the teams
383
+ * of the topics and their files (`namesTeams`, on by default), since our
384
+ * relay does not yet deliver a team's event live to a subscription that names
385
+ * no team. A file whose team is unknown is still asked for; it is heard once
386
+ * the relay delivers by file.
387
+ */
388
+ export function watchTopicActivity(
389
+ relay: Pick<LiveRelay, 'subscribe'>,
390
+ activity: TopicActivity,
391
+ onActivity: (topic: string, at: number) => void,
392
+ options: {
393
+ /** Unix seconds to hear from. Defaults to now. */
394
+ since?: number
395
+ namesTeams?: boolean
396
+ onClosed?: (reason: string) => void
397
+ now?: () => number
398
+ setTimer?: (run: () => void, ms: number) => unknown
399
+ clearTimer?: (timer: unknown) => void
400
+ } = {},
401
+ ): ActivityWatch {
402
+ const timers = globalThis as unknown as { setTimeout(run: () => void, ms: number): unknown; clearTimeout(timer: unknown): void }
403
+ const setTimer = options.setTimer ?? ((run: () => void, ms: number) => timers.setTimeout(run, ms))
404
+ const clearTimer = options.clearTimer ?? ((timer: unknown) => timers.clearTimeout(timer))
405
+ const nowSeconds = () => Math.floor((options.now ?? Date.now)() / 1000)
406
+ const namesTeams = options.namesTeams ?? true
407
+ let since = Math.min(options.since ?? nowSeconds(), nowSeconds())
408
+
409
+ // Which topics each file is news for; each file's team; the files by id, for a comment's `O`.
410
+ const byAddress = new Map<string, Set<string>>()
411
+ const folderOfFile = new Map<string, string | null>()
412
+ const byId = new Map<string, Set<string>>()
413
+ const teams = new Set<string>()
414
+ const add = (file: ActivityFile, topic: string) => {
415
+ const set = byAddress.get(file.address) ?? new Set<string>()
416
+ set.add(topic)
417
+ byAddress.set(file.address, set)
418
+ if (!folderOfFile.get(file.address)) folderOfFile.set(file.address, file.folder)
419
+ const id = fileIdOf(file.address)
420
+ if (id) byId.set(id, (byId.get(id) ?? new Set<string>()).add(file.address))
421
+ if (file.folder) teams.add(file.folder)
422
+ }
423
+ for (const [topic, list] of activity.files) for (const file of list) add(file, topic)
424
+ // Files heard under each parent since the watch began, beside those read: capped as the read is.
425
+ const children = new Map<string, number>()
426
+ for (const folder of activity.folders.values()) if (folder) teams.add(folder)
427
+ const topicSet = new Set(activity.at.keys())
428
+
429
+ let subs: { close(): void }[] = []
430
+ let timer: unknown = null
431
+ let stopped = false
432
+
433
+ const filtersNow = (): Record<string, unknown>[] => {
434
+ const topicAddresses = [...topicSet]
435
+ const fileAddresses = [...byAddress.keys()]
436
+ const parents = fileAddresses.filter((address) => CHILD_KINDS[kindOf(address) ?? -1])
437
+ const childKinds = [...new Set(parents.flatMap((address) => CHILD_KINDS[kindOf(address)!]!))]
438
+ const base: Record<string, unknown>[] = [
439
+ ...chunked(topicAddresses, VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_COMMENT, KIND_MESSAGE], '#A': values })),
440
+ ...chunked([...topicAddresses, ...fileAddresses], VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_CHANGE], '#a': values })),
441
+ ...chunked(fileAddresses, VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_COMMENT], '#A': values })),
442
+ ...chunked([...byId.keys()], VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_COMMENT], '#O': values })),
443
+ ...chunked(parents, VALUES_PER_FILTER).map((values) => ({ kinds: childKinds, '#a': values })),
444
+ ]
445
+ const teamChunks = namesTeams && teams.size > 0 ? chunked([...teams], 128) : [undefined]
446
+ return teamChunks.flatMap((h) => base.map((f) => ({ ...f, ...(h ? { '#h': h } : {}), since })))
447
+ }
448
+
449
+ const open = () => {
450
+ for (const sub of subs) sub.close()
451
+ subs = chunked(filtersNow(), MAX_FILTERS_PER_REQ).map((filters) =>
452
+ relay.subscribe(filters, hear, options.onClosed ? { onClosed: options.onClosed } : undefined),
453
+ )
454
+ }
455
+ const reopenSoon = () => {
456
+ if (stopped || timer !== null) return
457
+ timer = setTimer(() => {
458
+ timer = null
459
+ if (!stopped) open()
460
+ }, LISTED_WATCH_REBUILD_MS)
461
+ }
462
+
463
+ function raise(topic: string, created: number) {
464
+ const when = Math.min(created, nowSeconds())
465
+ if (when <= (activity.at.get(topic) ?? 0)) return
466
+ activity.at.set(topic, when)
467
+ onActivity(topic, when)
468
+ }
469
+
470
+ function hear(event: SignedEvent) {
471
+ if (stopped) return
472
+ since = Math.max(since, Math.min(event.created_at, nowSeconds()))
473
+ // A new file under a listed one: news, and listened to from now on.
474
+ const d = tagValues(event, 'd')[0]
475
+ // Its parent is its one `a` (§6.7), a held file whose kind holds this kind (a project its issue, a page its page).
476
+ const first = tagValues(event, 'a')[0]
477
+ const parent = d && first && byAddress.has(first) && CHILD_KINDS[kindOf(first) ?? -1]?.includes(event.kind) ? first : undefined
478
+ if (parent && d) {
479
+ const file = { address: `${event.kind}:${event.pubkey}:${d}`, folder: folderOf(event) }
480
+ const fresh = !byAddress.has(file.address)
481
+ const listen = fresh && (children.get(parent) ?? 0) < MAX_CHILDREN
482
+ if (listen) children.set(parent, (children.get(parent) ?? 0) + 1)
483
+ for (const topic of byAddress.get(parent)!) {
484
+ if (listen) {
485
+ activity.files.get(topic)?.push(file)
486
+ add(file, topic)
487
+ }
488
+ raise(topic, event.created_at)
489
+ }
490
+ if (listen) reopenSoon()
491
+ return
492
+ }
493
+ // The files and topics it may be on, then only those it is on as the read judges it.
494
+ const names = new Set<string>()
495
+ if (event.kind === KIND_CHANGE) {
496
+ if (first) names.add(first)
497
+ } else if (event.kind === KIND_COMMENT) {
498
+ const root = tagValues(event, 'A')[0] ?? first
499
+ if (root) names.add(root)
500
+ for (const id of tagValues(event, 'O')) for (const address of byId.get(id) ?? []) names.add(address)
501
+ } else {
502
+ // A chat message is a topic's only, as the read asks for it: none lists under a file.
503
+ const root = tagValues(event, 'A')[0]
504
+ if (root && topicSet.has(root)) names.add(root)
505
+ }
506
+ const topics = new Set<string>()
507
+ for (const name of names) {
508
+ if (topicSet.has(name) && isOn(event, name, activity.folders.get(name) ?? null)) topics.add(name)
509
+ if (byAddress.has(name) && isOn(event, name, folderOfFile.get(name) ?? null)) for (const topic of byAddress.get(name)!) topics.add(topic)
510
+ }
511
+ for (const topic of topics) if (countsAsActivity(event, topic)) raise(topic, event.created_at)
512
+ }
513
+
514
+ open()
515
+ return {
516
+ stop() {
517
+ if (stopped) return
518
+ stopped = true
519
+ if (timer !== null) clearTimer(timer)
520
+ for (const sub of subs) sub.close()
521
+ subs = []
522
+ },
523
+ }
524
+ }
package/src/index.ts CHANGED
@@ -182,6 +182,22 @@ export {
182
182
  type ListedFile,
183
183
  } from './topics.js'
184
184
 
185
+ /**
186
+ * Your topics, newest activity first: the one rule every app orders topics by
187
+ * (TOPI-10), read once for any set of topics and kept current live.
188
+ */
189
+ export {
190
+ readTopicActivity,
191
+ watchTopicActivity,
192
+ countsAsActivity,
193
+ byActivity,
194
+ activityTopics,
195
+ type ActivityFile,
196
+ type ActivityTopic,
197
+ type TopicActivity,
198
+ type ActivityWatch,
199
+ } from './activity.js'
200
+
185
201
  /**
186
202
  * A topic's All: the conversations of every file on its list, read in one go
187
203
  * and kept live, each file's events ready for the shared fold (SPEC §11.8).
package/src/projection.ts CHANGED
@@ -3910,8 +3910,10 @@ export async function resolveForeignRoots(
3910
3910
  * `listRead`, where the relay offers the list read (NIP-11 `file_list`), reads each file of the relay's file kinds
3911
3911
  * as its first record and its fields' current changes (§6.13), not every change ever made to it: no text, and a
3912
3912
  * deleted file is absent. Other kinds are read as before.
3913
+ * `parentsListRead`, with `archivedWith`, reads only the parents walked for an archive by the list read (with
3914
+ * `listRead`'s fallback for one it leaves out); the files asked for are still read in full, their text included.
3913
3915
  */
3914
- options: Pick<ArchiveReadOptions, 'archivedWith'> & { listRead?: boolean } = {},
3916
+ options: Pick<ArchiveReadOptions, 'archivedWith'> & { listRead?: boolean; parentsListRead?: boolean } = {},
3915
3917
  ): Promise<ForeignObject[]> {
3916
3918
  const pointers = new Map<string, AddressPointer>()
3917
3919
  for (const reference of references) {
@@ -3952,7 +3954,7 @@ export async function resolveForeignRoots(
3952
3954
  objects.map((object) => ({ object, manifest: manifestOf(object) })),
3953
3955
  query,
3954
3956
  cache,
3955
- options.listRead ? FILE_KINDS : [],
3957
+ options.listRead || options.parentsListRead ? FILE_KINDS : [],
3956
3958
  )
3957
3959
  }
3958
3960
  return objects
package/src/topics.ts CHANGED
@@ -346,6 +346,8 @@ export interface ReadTopic {
346
346
  object: ForeignObject
347
347
  /** Its Folder, from its root (§6.2): where an entry on its list is filed. */
348
348
  folder: string
349
+ /** Its first record's time, Unix seconds: its time in the order of topics when nothing has happened in it since. */
350
+ createdAt: number
349
351
  /** Its list, as {@link topicLists} reads it. */
350
352
  listed: ListedFile[]
351
353
  /**
@@ -434,7 +436,7 @@ function personInFilesFilters(person: string, files: readonly string[]): Record<
434
436
  }
435
437
 
436
438
  /** Whether an event answers a filter, as NIP-01 reads it: kinds, authors, `#x` tags, `since` and `until`. */
437
- function answers(event: SignedEvent, filter: Record<string, unknown>): boolean {
439
+ export function answers(event: SignedEvent, filter: Record<string, unknown>): boolean {
438
440
  const { kinds, authors, since, until } = filter as { kinds?: number[]; authors?: string[]; since?: number; until?: number }
439
441
  if (kinds && !kinds.includes(event.kind)) return false
440
442
  if (authors && !authors.includes(event.pubkey)) return false
@@ -452,7 +454,7 @@ function answers(event: SignedEvent, filter: Record<string, unknown>): boolean {
452
454
  * nothing fills a page, as at Miky's scale; never a silent cut at the relay's
453
455
  * cap. A second holding a page's worth on its own ends the walk there.
454
456
  */
455
- async function readAll(query: QueryFn, filters: readonly Record<string, unknown>[]): Promise<SignedEvent[]> {
457
+ export async function readAll(query: QueryFn, filters: readonly Record<string, unknown>[]): Promise<SignedEvent[]> {
456
458
  const out = new Map<string, SignedEvent>()
457
459
  let open = filters.map((filter) => ({ ...filter, limit: RELAY_PAGE_CEILING }))
458
460
  while (open.length) {
@@ -489,12 +491,17 @@ async function readAll(query: QueryFn, filters: readonly Record<string, unknown>
489
491
  *
490
492
  * How the viewer is in each topic is {@link followingOf} over its root and
491
493
  * the changes naming them (TEA-6), the fold Peek's switch reads too.
494
+ * `parentsListRead`, where the relay offers the list read (NIP-11
495
+ * `file_list`): the parents walked to see whether a topic is archived with one
496
+ * are read as their current values (§6.13), not every change ever made to them
497
+ * (ALO-15). The topics themselves are read as before, their text included.
498
+ *
492
499
  * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
493
500
  */
494
501
  export async function readTopics(
495
502
  query: QueryFn,
496
503
  me: string,
497
- options: { cache?: ProjectionCache; fileKinds?: readonly number[]; nowSeconds?: number } = {},
504
+ options: { cache?: ProjectionCache; fileKinds?: readonly number[]; nowSeconds?: number; parentsListRead?: boolean } = {},
498
505
  ): Promise<TopicsRead> {
499
506
  const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000)
500
507
  const rootEvents = await readAll(query, [{ kinds: [KIND_TOPIC] }])
@@ -509,7 +516,7 @@ export async function readTopics(
509
516
  const addresses = [...roots.keys()]
510
517
  if (addresses.length === 0) return { me, topics: [], membership: foldMemberships(me, [], nowSeconds), mentionedIn: new Set(), inConversations: new Map() }
511
518
  const [objects, lists, part, states] = await Promise.all([
512
- resolveForeignRoots(addresses, query, options.cache, { archivedWith: true }),
519
+ resolveForeignRoots(addresses, query, options.cache, { archivedWith: true, parentsListRead: options.parentsListRead }),
513
520
  listsOf(query, addresses, Promise.resolve(roots), options),
514
521
  // Held once each, though one comment can answer two of the filters: the folds count events.
515
522
  readAll(query, personInFilesFilters(me, addresses)),
@@ -550,7 +557,7 @@ export async function readTopics(
550
557
  const address = object.address!
551
558
  // The team is the topic's own Folder; a team's default reaches no topic, so its roster is not needed (§11.8).
552
559
  const following = followingOf({ address, team: folder }, me, { events: [root, ...(byTopic.get(address) ?? [])], listing: states })
553
- return [{ address, object, folder, listed: lists.get(address) ?? [], following, yours: following.in, space: spaces.has(address) }]
560
+ return [{ address, object, folder, createdAt: root.created_at, listed: lists.get(address) ?? [], following, yours: following.in, space: spaces.has(address) }]
554
561
  })
555
562
  return { me, topics, membership, mentionedIn, inConversations }
556
563
  }