@estiva-app/interop 0.89.0 → 0.91.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,527 @@
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, openWhenKnown } 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, it asks by file alone when given
383
+ * `namesTeams: relayNamesTeams(relay)` on a relay that lists
384
+ * `buzz-live-as-stored` (ours), opening once that answer is in. Otherwise
385
+ * (the default) every filter also names the teams of the topics and their
386
+ * files, and a file whose team is unknown is not heard from its team.
387
+ *
388
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-request-kept-open-hears-what-asking-again-would-return.md
389
+ */
390
+ export function watchTopicActivity(
391
+ relay: Pick<LiveRelay, 'subscribe'>,
392
+ activity: TopicActivity,
393
+ onActivity: (topic: string, at: number) => void,
394
+ options: {
395
+ /** Unix seconds to hear from. Defaults to now. */
396
+ since?: number
397
+ /** Whether to name teams; a promise ({@link relayNamesTeams}) holds the REQ until it settles. Defaults to true. */
398
+ namesTeams?: boolean | Promise<boolean>
399
+ onClosed?: (reason: string) => void
400
+ now?: () => number
401
+ setTimer?: (run: () => void, ms: number) => unknown
402
+ clearTimer?: (timer: unknown) => void
403
+ } = {},
404
+ ): ActivityWatch {
405
+ const timers = globalThis as unknown as { setTimeout(run: () => void, ms: number): unknown; clearTimeout(timer: unknown): void }
406
+ const setTimer = options.setTimer ?? ((run: () => void, ms: number) => timers.setTimeout(run, ms))
407
+ const clearTimer = options.clearTimer ?? ((timer: unknown) => timers.clearTimeout(timer))
408
+ const nowSeconds = () => Math.floor((options.now ?? Date.now)() / 1000)
409
+ let namesTeams = typeof options.namesTeams === 'boolean' ? options.namesTeams : true
410
+ let since = Math.min(options.since ?? nowSeconds(), nowSeconds())
411
+
412
+ // Which topics each file is news for; each file's team; the files by id, for a comment's `O`.
413
+ const byAddress = new Map<string, Set<string>>()
414
+ const folderOfFile = new Map<string, string | null>()
415
+ const byId = new Map<string, Set<string>>()
416
+ const teams = new Set<string>()
417
+ const add = (file: ActivityFile, topic: string) => {
418
+ const set = byAddress.get(file.address) ?? new Set<string>()
419
+ set.add(topic)
420
+ byAddress.set(file.address, set)
421
+ if (!folderOfFile.get(file.address)) folderOfFile.set(file.address, file.folder)
422
+ const id = fileIdOf(file.address)
423
+ if (id) byId.set(id, (byId.get(id) ?? new Set<string>()).add(file.address))
424
+ if (file.folder) teams.add(file.folder)
425
+ }
426
+ for (const [topic, list] of activity.files) for (const file of list) add(file, topic)
427
+ // Files heard under each parent since the watch began, beside those read: capped as the read is.
428
+ const children = new Map<string, number>()
429
+ for (const folder of activity.folders.values()) if (folder) teams.add(folder)
430
+ const topicSet = new Set(activity.at.keys())
431
+
432
+ let subs: { close(): void }[] = []
433
+ let timer: unknown = null
434
+ let stopped = false
435
+
436
+ const filtersNow = (): Record<string, unknown>[] => {
437
+ const topicAddresses = [...topicSet]
438
+ const fileAddresses = [...byAddress.keys()]
439
+ const parents = fileAddresses.filter((address) => CHILD_KINDS[kindOf(address) ?? -1])
440
+ const childKinds = [...new Set(parents.flatMap((address) => CHILD_KINDS[kindOf(address)!]!))]
441
+ const base: Record<string, unknown>[] = [
442
+ ...chunked(topicAddresses, VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_COMMENT, KIND_MESSAGE], '#A': values })),
443
+ ...chunked([...topicAddresses, ...fileAddresses], VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_CHANGE], '#a': values })),
444
+ ...chunked(fileAddresses, VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_COMMENT], '#A': values })),
445
+ ...chunked([...byId.keys()], VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_COMMENT], '#O': values })),
446
+ ...chunked(parents, VALUES_PER_FILTER).map((values) => ({ kinds: childKinds, '#a': values })),
447
+ ]
448
+ const teamChunks = namesTeams && teams.size > 0 ? chunked([...teams], 128) : [undefined]
449
+ return teamChunks.flatMap((h) => base.map((f) => ({ ...f, ...(h ? { '#h': h } : {}), since })))
450
+ }
451
+
452
+ const open = () => {
453
+ for (const sub of subs) sub.close()
454
+ subs = chunked(filtersNow(), MAX_FILTERS_PER_REQ).map((filters) =>
455
+ relay.subscribe(filters, hear, options.onClosed ? { onClosed: options.onClosed } : undefined),
456
+ )
457
+ }
458
+ const reopenSoon = () => {
459
+ if (stopped || timer !== null) return
460
+ timer = setTimer(() => {
461
+ timer = null
462
+ if (!stopped) open()
463
+ }, LISTED_WATCH_REBUILD_MS)
464
+ }
465
+
466
+ function raise(topic: string, created: number) {
467
+ const when = Math.min(created, nowSeconds())
468
+ if (when <= (activity.at.get(topic) ?? 0)) return
469
+ activity.at.set(topic, when)
470
+ onActivity(topic, when)
471
+ }
472
+
473
+ function hear(event: SignedEvent) {
474
+ if (stopped) return
475
+ since = Math.max(since, Math.min(event.created_at, nowSeconds()))
476
+ // A new file under a listed one: news, and listened to from now on.
477
+ const d = tagValues(event, 'd')[0]
478
+ // Its parent is its one `a` (§6.7), a held file whose kind holds this kind (a project its issue, a page its page).
479
+ const first = tagValues(event, 'a')[0]
480
+ const parent = d && first && byAddress.has(first) && CHILD_KINDS[kindOf(first) ?? -1]?.includes(event.kind) ? first : undefined
481
+ if (parent && d) {
482
+ const file = { address: `${event.kind}:${event.pubkey}:${d}`, folder: folderOf(event) }
483
+ const fresh = !byAddress.has(file.address)
484
+ const listen = fresh && (children.get(parent) ?? 0) < MAX_CHILDREN
485
+ if (listen) children.set(parent, (children.get(parent) ?? 0) + 1)
486
+ for (const topic of byAddress.get(parent)!) {
487
+ if (listen) {
488
+ activity.files.get(topic)?.push(file)
489
+ add(file, topic)
490
+ }
491
+ raise(topic, event.created_at)
492
+ }
493
+ if (listen) reopenSoon()
494
+ return
495
+ }
496
+ // The files and topics it may be on, then only those it is on as the read judges it.
497
+ const names = new Set<string>()
498
+ if (event.kind === KIND_CHANGE) {
499
+ if (first) names.add(first)
500
+ } else if (event.kind === KIND_COMMENT) {
501
+ const root = tagValues(event, 'A')[0] ?? first
502
+ if (root) names.add(root)
503
+ for (const id of tagValues(event, 'O')) for (const address of byId.get(id) ?? []) names.add(address)
504
+ } else {
505
+ // A chat message is a topic's only, as the read asks for it: none lists under a file.
506
+ const root = tagValues(event, 'A')[0]
507
+ if (root && topicSet.has(root)) names.add(root)
508
+ }
509
+ const topics = new Set<string>()
510
+ for (const name of names) {
511
+ if (topicSet.has(name) && isOn(event, name, activity.folders.get(name) ?? null)) topics.add(name)
512
+ if (byAddress.has(name) && isOn(event, name, folderOfFile.get(name) ?? null)) for (const topic of byAddress.get(name)!) topics.add(topic)
513
+ }
514
+ for (const topic of topics) if (countsAsActivity(event, topic)) raise(topic, event.created_at)
515
+ }
516
+
517
+ openWhenKnown(options.namesTeams, (names) => (namesTeams = names), () => !stopped && open())
518
+ return {
519
+ stop() {
520
+ if (stopped) return
521
+ stopped = true
522
+ if (timer !== null) clearTimer(timer)
523
+ for (const sub of subs) sub.close()
524
+ subs = []
525
+ },
526
+ }
527
+ }
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).
@@ -197,6 +213,9 @@ export {
197
213
  type ListedWatch,
198
214
  } from './listedConversations.js'
199
215
 
216
+ /** Whether a live watch must name teams on a relay: its NIP-11 `buzz-live-as-stored` (SPEC §5). */
217
+ export { namesTeamsOn, relayNamesTeams, LIVE_AS_STORED_EXTENSION } from './liveAsStored.js'
218
+
200
219
  /**
201
220
  * A file as its fields, each kept in order by the relay (SPEC §6.2, §6.13):
202
221
  * the list and open reads, and the change writer that answers `conflict:`.
@@ -303,15 +303,18 @@ export const LISTED_WATCH_REBUILD_MS = 250
303
303
  * written a second ago is heard. Each event is handed over once; the cold
304
304
  * read's are never handed over.
305
305
  *
306
- * ## Naming the files' teams (`namesTeams`, on by default)
306
+ * ## Asking by file alone (`namesTeams: relayNamesTeams(relay)`)
307
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.
308
+ * The decided shape asks by file alone (Miky, 2026-11-06), and a relay that
309
+ * lists `buzz-live-as-stored` (ours) delivers a team's event live to a
310
+ * request that names no team, as a stored read returns it. Pass
311
+ * `namesTeams: relayNamesTeams(relay)` and the watch asks by file alone on
312
+ * such a relay; it opens once that answer is in. Otherwise (`namesTeams`
313
+ * true, the default, or a relay that does not say so) every filter also
314
+ * carries the `#h` of each listed file's team and of every team a comment on
315
+ * them was filed in.
316
+ *
317
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-request-kept-open-hears-what-asking-again-would-return.md
315
318
  */
316
319
  export function watchListedConversations(
317
320
  relay: Pick<LiveRelay, 'subscribe'>,
@@ -320,7 +323,8 @@ export function watchListedConversations(
320
323
  options: {
321
324
  /** Unix seconds to hear from. Defaults to the newest event the read holds, else now. */
322
325
  since?: number
323
- namesTeams?: boolean
326
+ /** Whether to name teams; a promise ({@link relayNamesTeams}) holds the REQ until it settles. Defaults to true. */
327
+ namesTeams?: boolean | Promise<boolean>
324
328
  onClosed?: (reason: string) => void
325
329
  now?: () => number
326
330
  setTimer?: (run: () => void, ms: number) => unknown
@@ -342,7 +346,7 @@ export function watchListedConversations(
342
346
  // `created_at` is the author's to write (the relay takes 15 min ahead): `since` never passes the reader's own clock.
343
347
  const newest = Math.max(0, ...read.files.flatMap((f) => f.events.map((e) => e.created_at)))
344
348
  let since = options.since ?? (newest > 0 ? Math.min(newest, nowSeconds()) : nowSeconds())
345
- const namesTeams = options.namesTeams ?? true
349
+ let namesTeams = typeof options.namesTeams === 'boolean' ? options.namesTeams : true
346
350
 
347
351
  let subs: { close(): void }[] = []
348
352
  let timer: unknown = null
@@ -407,7 +411,7 @@ export function watchListedConversations(
407
411
  if (learnt) reopenSoon()
408
412
  }
409
413
 
410
- open()
414
+ openWhenKnown(options.namesTeams, (names) => (namesTeams = names), () => !stopped && open())
411
415
  return {
412
416
  stop() {
413
417
  if (stopped) return
@@ -419,6 +423,22 @@ export function watchListedConversations(
419
423
  }
420
424
  }
421
425
 
426
+ /**
427
+ * Open a watch now, or once `namesTeams` (a promise, `relayNamesTeams`)
428
+ * settles, naming teams if it rejects. `since` covers the wait.
429
+ */
430
+ export function openWhenKnown(
431
+ namesTeams: boolean | Promise<boolean> | undefined,
432
+ set: (names: boolean) => void,
433
+ open: () => void,
434
+ ): void {
435
+ if (namesTeams === undefined || typeof namesTeams === 'boolean') {
436
+ open()
437
+ return
438
+ }
439
+ namesTeams.then(set, () => set(true)).then(open)
440
+ }
441
+
422
442
  function addTeam(teams: Set<string>, event: SignedEvent): void {
423
443
  const h = event.tags.find((t) => t[0] === 'h' && t[1])?.[1]
424
444
  if (h) teams.add(h)