@estiva-app/interop 0.70.2 → 0.71.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,31 @@ how a declaration is read, is a MAJOR — in `0.x`, a MINOR — even when no
6
6
  TypeScript signature moved. A consumer upgrading must be able to tell whether
7
7
  manifests already published still mean what they meant.
8
8
 
9
+ ## 0.71.0 — 2026-10-30
10
+
11
+ **Manifest: nothing.** A topic keeps a list of files from any Folder, and any
12
+ app can ask which topics list a file (SPEC §6.14; record
13
+ a-topic-keeps-its-own-list-of-files). New API only; every read that existed is
14
+ unchanged.
15
+
16
+ - `planListInTopic` and `planRemoveFromTopic` write one `kind:1851` entry on
17
+ the topic: `a`, `O` (the topic's `d`), `field` `lists:<d>`, `value`
18
+ `true`/`false`, `h` (the topic's Folder), `ts`, `["o", <d>]`. No `p`: a
19
+ listing adds nobody to the file.
20
+ - `topicsOfFile(query, d)` asks `{kinds:[1851], "#o":[d]}` and returns the
21
+ topics whose newest entry lists the file, each with its root; an entry filed
22
+ outside its topic's Folder, on a topic the reader cannot read, or on any
23
+ other type is left out. `topicList(query, topicAddress)` reads the topic's
24
+ root for its Folder and returns its listed
25
+ files, in no promised order, each id resolved over `LISTED_FILE_KINDS` (or
26
+ `fileKinds`), never a Folder's `39000`; an id held by two files or by none
27
+ resolves to `null`, not drawn and not counted.
28
+ - `listEntries` is the fold both use: newest per topic and file, listed only
29
+ by exactly `true`; an entry is skipped when none of its `o` is the field's
30
+ `<d>`, its `O` is not its `a`'s `d`, it lists the topic itself, or it names
31
+ no Folder. `topicsOfFileFilter`, `topicListFilter` and `listsField` are the
32
+ filters and the field name.
33
+
9
34
  ## 0.70.2 — 2026-10-30
10
35
 
11
36
  **Manifest: nothing.** A reader may ask for a file's archived children too
package/README.md CHANGED
@@ -740,6 +740,31 @@ Its wording is the relay's. Take the count and say it in your app's words
740
740
  ("This Folder still has 2 files. Move or delete them first."), as you would
741
741
  for `target-is-private`.
742
742
 
743
+ ### A topic's list of files (0.71.0)
744
+
745
+ A topic lists files from any Folder, one `kind:1851` entry per file, by the
746
+ file's id (SPEC §6.14). The file stays where it is filed; a listing grants,
747
+ moves and archives nothing.
748
+
749
+ ```ts
750
+ import { planListInTopic, planRemoveFromTopic, topicList, topicsOfFile, folderOf } from '@estiva-app/interop'
751
+
752
+ const topic = { address: topicAddress, folder: folderOf(topicRoot)! } // the Folder its root names
753
+ const [entry] = planListInTopic(me, Date.now(), { topic, file: projectId }) // or planRemoveFromTopic
754
+ await publish(await sign(entry))
755
+
756
+ const files = await topicList(query, topicAddress) // [{ file, address, entry }], in no promised order: sort as your design says
757
+ const shown = files.filter((f) => f.address) // address null: unreadable, or two files hold the id
758
+ const topics = await topicsOfFile(query, projectId) // [{ address, root, entry }]: which topics list it
759
+ ```
760
+
761
+ `topicsOfFile` asks `{kinds:[1851], "#o":[id]}`; a file's own changes, by `#O`
762
+ or `#a`, never hold an entry that lists it. Only topics' lists are read, an
763
+ entry filed outside its topic's Folder is ignored, and an id held by two files
764
+ or only by a Folder resolves to nothing: draw and count only the resolved ones.
765
+ `topicList` resolves ids over `LISTED_FILE_KINDS`; pass `fileKinds` for kinds
766
+ you know from manifests.
767
+
743
768
  ### Archiving anything (0.37.0)
744
769
 
745
770
  ```ts
package/dist/index.d.ts CHANGED
@@ -43,6 +43,12 @@ export { fileCandidates, REFERENCE_FILE_TYPES, searchFileReferences, type FileCa
43
43
  * empties it. No signing, no requests.
44
44
  */
45
45
  export { planCreateFolder, planRenameFolder, planDeleteFolder, planPlaceFile, planUnlistFile, planMoveFile, planMoveFromFolders, planArchiveFolder, listedBeneath, type FolderRef, type MovableFile, type MovePlan, type MoveFromFoldersPlan, type MoveRefusal, } from './folders.js';
46
+ /**
47
+ * SPEC §6.14: a topic's list of files from any Folder, one `kind:1851` entry
48
+ * per file by its id. Plan an entry, read a topic's list, and ask which topics
49
+ * list a file (`#o`); a file's own changes (`#O`) never hold an entry.
50
+ */
51
+ export { planListInTopic, planRemoveFromTopic, topicsOfFile, topicList, topicsOfFileFilter, topicListFilter, listEntries, listsField, LISTED_FILE_KINDS, type ListHolder, type ListEntry, type FileTopic, type ListedFile, } from './topics.js';
46
52
  /**
47
53
  * What an app link names, and where a file is mentioned — once for every app
48
54
  * (SPEC §7.7, §13.1, §6.8; PEEKM-7). Each app passes its relay read; none
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/dist/index.js CHANGED
@@ -43,6 +43,12 @@ export { fileCandidates, REFERENCE_FILE_TYPES, searchFileReferences, } from './r
43
43
  * empties it. No signing, no requests.
44
44
  */
45
45
  export { planCreateFolder, planRenameFolder, planDeleteFolder, planPlaceFile, planUnlistFile, planMoveFile, planMoveFromFolders, planArchiveFolder, listedBeneath, } from './folders.js';
46
+ /**
47
+ * SPEC §6.14: a topic's list of files from any Folder, one `kind:1851` entry
48
+ * per file by its id. Plan an entry, read a topic's list, and ask which topics
49
+ * list a file (`#o`); a file's own changes (`#O`) never hold an entry.
50
+ */
51
+ export { planListInTopic, planRemoveFromTopic, topicsOfFile, topicList, topicsOfFileFilter, topicListFilter, listEntries, listsField, LISTED_FILE_KINDS, } from './topics.js';
46
52
  /**
47
53
  * What an app link names, and where a file is mentioned — once for every app
48
54
  * (SPEC §7.7, §13.1, §6.8; PEEKM-7). Each app passes its relay read; none
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,aAAa,EAIb,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,0BAA0B,EAC1B,sBAAsB,EACtB,OAAO,EAEP,cAAc,EACd,oBAAoB,EACpB,eAAe,EAEf,SAAS,EAET,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EAEjB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EAErB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EAmBnB,cAAc,GAEf,MAAM,iBAAiB,CAAA;AAExB;;;GAGG;AACH,OAAO,EAAE,SAAS,EAA+B,MAAM,cAAc,CAAA;AACrE,OAAO,EAAE,eAAe,EAAyB,MAAM,gBAAgB,CAAA;AAEvE;;;GAGG;AACH,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,oBAAoB,GAGrB,MAAM,iBAAiB,CAAA;AAExB;;;;;GAKG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,GAMd,MAAM,cAAc,CAAA;AAErB;;;;GAIG;AACH,OAAO,EACL,UAAU,EACV,UAAU,EACV,OAAO,EACP,eAAe,EACf,MAAM,EACN,eAAe,GAKhB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,4BAA4B,GAE7B,MAAM,eAAe,CAAA;AAEtB;;;;;;;GAOG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,UAAU,GAGX,MAAM,gBAAgB,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,aAAa,EAIb,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,0BAA0B,EAC1B,sBAAsB,EACtB,OAAO,EAEP,cAAc,EACd,oBAAoB,EACpB,eAAe,EAEf,SAAS,EAET,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EAEjB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EAErB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EAmBnB,cAAc,GAEf,MAAM,iBAAiB,CAAA;AAExB;;;GAGG;AACH,OAAO,EAAE,SAAS,EAA+B,MAAM,cAAc,CAAA;AACrE,OAAO,EAAE,eAAe,EAAyB,MAAM,gBAAgB,CAAA;AAEvE;;;GAGG;AACH,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,oBAAoB,GAGrB,MAAM,iBAAiB,CAAA;AAExB;;;;;GAKG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,GAMd,MAAM,cAAc,CAAA;AAErB;;;;GAIG;AACH,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,UAAU,EACV,iBAAiB,GAKlB,MAAM,aAAa,CAAA;AAEpB;;;;GAIG;AACH,OAAO,EACL,UAAU,EACV,UAAU,EACV,OAAO,EACP,eAAe,EACf,MAAM,EACN,eAAe,GAKhB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,4BAA4B,GAE7B,MAAM,eAAe,CAAA;AAEtB;;;;;;;GAOG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,UAAU,GAGX,MAAM,gBAAgB,CAAA"}
@@ -0,0 +1,131 @@
1
+ /**
2
+ * A topic's list of files — SPEC §6.14 "A file's list of other files"; record
3
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
4
+ *
5
+ * A topic lists files from any Folder, one entry per file, by the file's id.
6
+ * An entry is a `kind:1851` change on the topic: `a` and `O` name the topic,
7
+ * `field` is `lists:<d>`, `value` is `true` or `false`, `h` is the topic's
8
+ * Folder, then `ts`, then `["o", <d>]` naming the listed file. The newest
9
+ * entry per topic and file counts (§6.3).
10
+ *
11
+ * `O` is the file the change is about and `o` another file it points at
12
+ * (why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-change-is-about-its-file-as-a-comment-is.md),
13
+ * so `#o` asks which topics list a file and `#O` asks what changed on a topic,
14
+ * and a file's own changes never include a topic's entry about it.
15
+ *
16
+ * Here rather than in each app because Peek, Ship and Leaf all add, remove
17
+ * and read entries, and a reader rule kept in one of them only is a list that
18
+ * reads differently in the next.
19
+ *
20
+ * ## What a listing is not
21
+ *
22
+ * It grants nothing: who reads the listed file is its own Folder's rule. It is
23
+ * not a mention, not a parent and not a Folder's listing, so Mentioned in, the
24
+ * archive chain and a Folder move all ignore it. It carries no `p`, so it adds
25
+ * nobody to the file (§11.8).
26
+ */
27
+ import { type SignedEvent, type UnsignedEvent } from '@estiva-app/protocol';
28
+ import { type QueryFn } from './projection.js';
29
+ /**
30
+ * The file kinds a listed id is looked for under by default: topic, document,
31
+ * project, issue. Never a bare `#d`, since a Folder's `kind:39000` shares its
32
+ * uuid (§11.1). An app that knows more kinds from manifests passes them.
33
+ */
34
+ export declare const LISTED_FILE_KINDS: readonly number[];
35
+ /** The field an entry for `file` sets: `lists:<d>`. */
36
+ export declare function listsField(file: string): string;
37
+ /** The file a list carries entries on, as a write needs it. */
38
+ export interface ListHolder {
39
+ /** Its address, `<kind>:<pubkey>:<d>`. */
40
+ address: string;
41
+ /** Its Folder, read from its root (`folderOf`), never the Folder it was opened from (§6.2). */
42
+ folder: string;
43
+ }
44
+ /**
45
+ * Put a file on a topic's list: `[kind:1851 lists:<d> = true]`, signed by
46
+ * whoever adds it. `file` is the listed file's id (its `d`), from any Folder.
47
+ */
48
+ export declare function planListInTopic(pubkey: string, createdAtMs: number, args: {
49
+ topic: ListHolder;
50
+ file: string;
51
+ note?: string;
52
+ }): UnsignedEvent[];
53
+ /** Take a file off a topic's list: `[kind:1851 lists:<d> = false]`. {@link planListInTopic} in reverse. */
54
+ export declare function planRemoveFromTopic(pubkey: string, createdAtMs: number, args: {
55
+ topic: ListHolder;
56
+ file: string;
57
+ note?: string;
58
+ }): UnsignedEvent[];
59
+ /** Which topics list a file: every entry naming its id in `o`. Fold with {@link listEntries}. */
60
+ export declare function topicsOfFileFilter(file: string): Record<string, unknown>;
61
+ /** A topic's changes, its list entries among them: `#O` on its id. Fold with {@link listEntries}. */
62
+ export declare function topicListFilter(topic: string): Record<string, unknown>;
63
+ /** The newest entry for one list and one file. */
64
+ export interface ListEntry {
65
+ /** The address of the file keeping the list (a topic). */
66
+ list: string;
67
+ /** The listed file's id. */
68
+ file: string;
69
+ /** The entry's Folder: its first `h` with a value. */
70
+ folder: string;
71
+ /** `true` when the newest entry lists the file. */
72
+ listed: boolean;
73
+ event: SignedEvent;
74
+ }
75
+ /**
76
+ * The newest entry per list and file, from any mix of changes: the reader
77
+ * rules of §6.14. A change counts as an entry only when its field is
78
+ * `lists:<d>`, one of its `o` tags is that same `<d>` (an `o` the field does
79
+ * not name is some other relation, a move's new parent for one), its `a`
80
+ * names a file whose `d` is its `O`, `<d>` is not that file itself, and it
81
+ * names a Folder. Anything else is skipped, not folded, so a malformed entry
82
+ * never hides a good one. A `value` other than exactly `true` does not list
83
+ * the file.
84
+ *
85
+ * `folderOfList` is §6.2's Folder check against each list's root, applied
86
+ * before the fold: an entry filed in any other Folder must not become the
87
+ * newest and hide the good one before it. A list it answers no Folder for (an
88
+ * unread root, or one naming none) keeps no entry. Without it the check is the
89
+ * caller's; {@link topicsOfFile} and {@link topicList} pass it.
90
+ */
91
+ export declare function listEntries(events: readonly SignedEvent[], folderOfList?: (list: string) => string | null | undefined): ListEntry[];
92
+ /** A topic that lists a file. */
93
+ export interface FileTopic {
94
+ /** The topic's address. */
95
+ address: string;
96
+ /** The topic's root, as the reader read it. */
97
+ root: SignedEvent;
98
+ entry: ListEntry;
99
+ }
100
+ /**
101
+ * Which topics list a file — `{kinds:[1851], "#o":[<d>]}`, folded per topic.
102
+ *
103
+ * Keeps an entry only when its newest value lists the file, it is on a topic
104
+ * (only topics' lists are read, Miky 2026-10-30), the topic's root is one the
105
+ * reader can read (a deleted or unreadable topic drops out), and the entry is
106
+ * filed in the topic's own Folder (§6.2). Two reads: the entries, then the
107
+ * topics' roots.
108
+ */
109
+ export declare function topicsOfFile(query: QueryFn, file: string): Promise<FileTopic[]>;
110
+ /** A file on a topic's list. */
111
+ export interface ListedFile {
112
+ /** The listed file's id. */
113
+ file: string;
114
+ /** Its address when exactly one file the reader can read holds the id, else `null`: not drawn, not counted. */
115
+ address: string | null;
116
+ entry: ListEntry;
117
+ }
118
+ /**
119
+ * A topic's list, by the topic's address: its entries whose newest value
120
+ * lists the file, filed in the Folder the topic's root names (§6.2; read here,
121
+ * never taken from the caller), in no promised order (sort as the design
122
+ * says; `entry.event` carries the time), each id resolved over `fileKinds` by
123
+ * `#d`. A topic the reader cannot read, or whose root names no Folder, lists
124
+ * nothing. An id held by none the reader can read, or by two, resolves to
125
+ * `null`: a consumer draws and counts only the resolved ones (§3.2, the count
126
+ * is the disclosure).
127
+ */
128
+ export declare function topicList(query: QueryFn, topic: string, options?: {
129
+ fileKinds?: readonly number[];
130
+ }): Promise<ListedFile[]>;
131
+ //# sourceMappingURL=topics.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"topics.d.ts","sourceRoot":"","sources":["../src/topics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAE3E,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAQxD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAAiC,CAAA;AAKhF,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAA;CACf;AAgCD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD,aAAa,EAAE,CAEjB;AAED,2GAA2G;AAC3G,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD,aAAa,EAAE,CAEjB;AAED,iGAAiG;AACjG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAExE;AAED,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGtE;AAED,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAA;IACd,mDAAmD;IACnD,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,WAAW,CAAA;CACnB;AAWD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,GACzD,SAAS,EAAE,CAsBb;AAyBD,iCAAiC;AACjC,MAAM,WAAW,SAAS;IACxB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,+CAA+C;IAC/C,IAAI,EAAE,WAAW,CAAA;IACjB,KAAK,EAAE,SAAS,CAAA;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAarF;AAED,gCAAgC;AAChC,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,+GAA+G;IAC/G,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,KAAK,EAAE,SAAS,CAAA;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GAC9C,OAAO,CAAC,UAAU,EAAE,CAAC,CA6BvB"}
package/dist/topics.js ADDED
@@ -0,0 +1,241 @@
1
+ /**
2
+ * A topic's list of files — SPEC §6.14 "A file's list of other files"; record
3
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
4
+ *
5
+ * A topic lists files from any Folder, one entry per file, by the file's id.
6
+ * An entry is a `kind:1851` change on the topic: `a` and `O` name the topic,
7
+ * `field` is `lists:<d>`, `value` is `true` or `false`, `h` is the topic's
8
+ * Folder, then `ts`, then `["o", <d>]` naming the listed file. The newest
9
+ * entry per topic and file counts (§6.3).
10
+ *
11
+ * `O` is the file the change is about and `o` another file it points at
12
+ * (why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-change-is-about-its-file-as-a-comment-is.md),
13
+ * so `#o` asks which topics list a file and `#O` asks what changed on a topic,
14
+ * and a file's own changes never include a topic's entry about it.
15
+ *
16
+ * Here rather than in each app because Peek, Ship and Leaf all add, remove
17
+ * and read entries, and a reader rule kept in one of them only is a list that
18
+ * reads differently in the next.
19
+ *
20
+ * ## What a listing is not
21
+ *
22
+ * It grants nothing: who reads the listed file is its own Folder's rule. It is
23
+ * not a mention, not a parent and not a Folder's listing, so Mentioned in, the
24
+ * archive chain and a Folder move all ignore it. It carries no `p`, so it adds
25
+ * nobody to the file (§11.8).
26
+ */
27
+ import {} from '@estiva-app/protocol';
28
+ import { byOrder } from '@estiva-app/conversation';
29
+ import { folderOf } from './projection.js';
30
+ const KIND_CHANGE = 1851;
31
+ /** The topic (bare file) kind: the only lists this stage reads (Miky, 2026-10-30). */
32
+ const KIND_TOPIC = 30840;
33
+ const KIND_FOLDER = 39000;
34
+ /** Listed ids resolved per request: 2 × this stays under a relay's usual `limit` cap. */
35
+ const RESOLVE_BATCH = 100;
36
+ /**
37
+ * The file kinds a listed id is looked for under by default: topic, document,
38
+ * project, issue. Never a bare `#d`, since a Folder's `kind:39000` shares its
39
+ * uuid (§11.1). An app that knows more kinds from manifests passes them.
40
+ */
41
+ export const LISTED_FILE_KINDS = [30840, 30842, 30850, 30851];
42
+ const ADDRESS = /^(\d+):([0-9a-f]{64}):(.+)$/;
43
+ const FIELD_PREFIX = 'lists:';
44
+ /** The field an entry for `file` sets: `lists:<d>`. */
45
+ export function listsField(file) {
46
+ return `${FIELD_PREFIX}${file}`;
47
+ }
48
+ function entry(pubkey, createdAtMs, args) {
49
+ const holder = ADDRESS.exec(args.list.address);
50
+ if (!holder)
51
+ throw new Error(`not a file address: ${JSON.stringify(args.list.address)}`);
52
+ if (!args.list.folder)
53
+ throw new Error('a list entry names the Folder of the file that keeps the list');
54
+ if (!args.file || /\s/.test(args.file))
55
+ throw new Error(`not a file id: ${JSON.stringify(args.file)}`);
56
+ // A reader ignores a file on its own list (§6.14): refuse it here rather than publish an entry that shows nothing.
57
+ if (args.file === holder[3])
58
+ throw new Error('a file is not on its own list');
59
+ if (!Number.isSafeInteger(createdAtMs) || createdAtMs < 0)
60
+ throw new Error(`not epoch milliseconds: ${createdAtMs}`);
61
+ return {
62
+ pubkey,
63
+ created_at: Math.floor(createdAtMs / 1000),
64
+ kind: KIND_CHANGE,
65
+ tags: [
66
+ ['a', args.list.address],
67
+ ['O', holder[3]],
68
+ ['field', listsField(args.file)],
69
+ ['value', args.listed ? 'true' : 'false'],
70
+ ['h', args.list.folder],
71
+ ['ts', String(createdAtMs)],
72
+ ['o', args.file],
73
+ ],
74
+ // Empty unless the person wrote a note: each app says "added" and "removed" in its own words (§6.14).
75
+ content: args.note ?? '',
76
+ };
77
+ }
78
+ /**
79
+ * Put a file on a topic's list: `[kind:1851 lists:<d> = true]`, signed by
80
+ * whoever adds it. `file` is the listed file's id (its `d`), from any Folder.
81
+ */
82
+ export function planListInTopic(pubkey, createdAtMs, args) {
83
+ return [entry(pubkey, createdAtMs, { list: args.topic, file: args.file, listed: true, note: args.note })];
84
+ }
85
+ /** Take a file off a topic's list: `[kind:1851 lists:<d> = false]`. {@link planListInTopic} in reverse. */
86
+ export function planRemoveFromTopic(pubkey, createdAtMs, args) {
87
+ return [entry(pubkey, createdAtMs, { list: args.topic, file: args.file, listed: false, note: args.note })];
88
+ }
89
+ /** Which topics list a file: every entry naming its id in `o`. Fold with {@link listEntries}. */
90
+ export function topicsOfFileFilter(file) {
91
+ return { kinds: [KIND_CHANGE], '#o': [file] };
92
+ }
93
+ /** A topic's changes, its list entries among them: `#O` on its id. Fold with {@link listEntries}. */
94
+ export function topicListFilter(topic) {
95
+ const holder = ADDRESS.exec(topic);
96
+ return { kinds: [KIND_CHANGE], '#O': [holder ? holder[3] : topic] };
97
+ }
98
+ const tagOf = (event, name) => event.tags.find((t) => t[0] === name && t[1])?.[1];
99
+ /** The file an entry lists: the `<d>` of its `lists:<d>` field, or `null` for any other change. */
100
+ const listedIn = (event) => {
101
+ const field = tagOf(event, 'field');
102
+ return field?.startsWith(FIELD_PREFIX) ? field.slice(FIELD_PREFIX.length) || null : null;
103
+ };
104
+ /**
105
+ * The newest entry per list and file, from any mix of changes: the reader
106
+ * rules of §6.14. A change counts as an entry only when its field is
107
+ * `lists:<d>`, one of its `o` tags is that same `<d>` (an `o` the field does
108
+ * not name is some other relation, a move's new parent for one), its `a`
109
+ * names a file whose `d` is its `O`, `<d>` is not that file itself, and it
110
+ * names a Folder. Anything else is skipped, not folded, so a malformed entry
111
+ * never hides a good one. A `value` other than exactly `true` does not list
112
+ * the file.
113
+ *
114
+ * `folderOfList` is §6.2's Folder check against each list's root, applied
115
+ * before the fold: an entry filed in any other Folder must not become the
116
+ * newest and hide the good one before it. A list it answers no Folder for (an
117
+ * unread root, or one naming none) keeps no entry. Without it the check is the
118
+ * caller's; {@link topicsOfFile} and {@link topicList} pass it.
119
+ */
120
+ export function listEntries(events, folderOfList) {
121
+ const newest = new Map();
122
+ for (const event of events) {
123
+ if (event.kind !== KIND_CHANGE)
124
+ continue;
125
+ const file = listedIn(event);
126
+ if (!file || !event.tags.some((t) => t[0] === 'o' && t[1] === file))
127
+ continue;
128
+ const list = tagOf(event, 'a');
129
+ const holder = list ? ADDRESS.exec(list) : null;
130
+ const folder = tagOf(event, 'h');
131
+ if (!holder || tagOf(event, 'O') !== holder[3] || file === holder[3] || !folder)
132
+ continue;
133
+ if (folderOfList && folderOfList(list) !== folder)
134
+ continue;
135
+ const key = `${list}\n${file}`;
136
+ const seen = newest.get(key);
137
+ if (!seen || byOrder(seen.event, event) < 0)
138
+ newest.set(key, { event, file });
139
+ }
140
+ return [...newest.values()].map(({ event, file }) => ({
141
+ list: tagOf(event, 'a'),
142
+ file,
143
+ folder: tagOf(event, 'h'),
144
+ listed: event.tags.find((t) => t[0] === 'value')?.[1] === 'true',
145
+ event,
146
+ }));
147
+ }
148
+ /** The roots of the given list addresses that the reader can read, by address. */
149
+ async function rootsOf(query, addresses) {
150
+ const byKindAuthor = new Map();
151
+ for (const address of addresses) {
152
+ const [, kind, pubkey, d] = ADDRESS.exec(address) ?? [];
153
+ if (!d)
154
+ continue;
155
+ const key = `${kind}:${pubkey}`;
156
+ const group = byKindAuthor.get(key) ?? { kind: Number(kind), pubkey, ds: [] };
157
+ group.ds.push(d);
158
+ byKindAuthor.set(key, group);
159
+ }
160
+ if (byKindAuthor.size === 0)
161
+ return new Map();
162
+ const filters = [...byKindAuthor.values()].map(({ kind, pubkey, ds }) => ({ kinds: [kind], authors: [pubkey], '#d': ds, limit: ds.length }));
163
+ const roots = new Map();
164
+ for (const root of await query(filters)) {
165
+ const address = `${root.kind}:${root.pubkey}:${tagOf(root, 'd') ?? ''}`;
166
+ const held = roots.get(address);
167
+ // Two versions of one record: NIP-01's later created_at, then the lower id (§6.3).
168
+ if (!held || root.created_at > held.created_at || (root.created_at === held.created_at && root.id < held.id))
169
+ roots.set(address, root);
170
+ }
171
+ return roots;
172
+ }
173
+ /**
174
+ * Which topics list a file — `{kinds:[1851], "#o":[<d>]}`, folded per topic.
175
+ *
176
+ * Keeps an entry only when its newest value lists the file, it is on a topic
177
+ * (only topics' lists are read, Miky 2026-10-30), the topic's root is one the
178
+ * reader can read (a deleted or unreadable topic drops out), and the entry is
179
+ * filed in the topic's own Folder (§6.2). Two reads: the entries, then the
180
+ * topics' roots.
181
+ */
182
+ export async function topicsOfFile(query, file) {
183
+ const isTopic = (entry) => entry.file === file && entry.list.startsWith(`${KIND_TOPIC}:`);
184
+ const events = await query([topicsOfFileFilter(file)]);
185
+ const lists = [...new Set(listEntries(events).filter(isTopic).map((entry) => entry.list))];
186
+ if (lists.length === 0)
187
+ return [];
188
+ const roots = await rootsOf(query, lists);
189
+ const folderOfList = (list) => {
190
+ const root = roots.get(list);
191
+ return root ? folderOf(root) : null;
192
+ };
193
+ return listEntries(events, folderOfList)
194
+ .filter((entry) => entry.listed && isTopic(entry))
195
+ .map((entry) => ({ address: entry.list, root: roots.get(entry.list), entry }));
196
+ }
197
+ /**
198
+ * A topic's list, by the topic's address: its entries whose newest value
199
+ * lists the file, filed in the Folder the topic's root names (§6.2; read here,
200
+ * never taken from the caller), in no promised order (sort as the design
201
+ * says; `entry.event` carries the time), each id resolved over `fileKinds` by
202
+ * `#d`. A topic the reader cannot read, or whose root names no Folder, lists
203
+ * nothing. An id held by none the reader can read, or by two, resolves to
204
+ * `null`: a consumer draws and counts only the resolved ones (§3.2, the count
205
+ * is the disclosure).
206
+ */
207
+ export async function topicList(query, topic, options = {}) {
208
+ const [roots, events] = await Promise.all([rootsOf(query, [topic]), query([topicListFilter(topic)])]);
209
+ const root = roots.get(topic);
210
+ const folder = root ? folderOf(root) : null;
211
+ if (!folder)
212
+ return [];
213
+ const entries = listEntries(events, (list) => (list === topic ? folder : null))
214
+ .filter((entry) => entry.listed)
215
+ .sort((a, b) => byOrder(a.event, b.event));
216
+ if (entries.length === 0)
217
+ return [];
218
+ const ids = [...new Set(entries.map((entry) => entry.file))];
219
+ // Never a Folder's `39000`, which shares its uuid (§11.1): an id only a Folder holds resolves to nothing.
220
+ const kinds = (options.fileKinds ?? LISTED_FILE_KINDS).filter((kind) => kind !== KIND_FOLDER);
221
+ // Room for a second holder of every id, so two holders are seen as two; in
222
+ // batches, so a relay's cap on `limit` cannot cut a long list short.
223
+ const batches = [];
224
+ for (let i = 0; i < ids.length; i += RESOLVE_BATCH)
225
+ batches.push(ids.slice(i, i + RESOLVE_BATCH));
226
+ const found = (await Promise.all(batches.map((batch) => query([{ kinds, '#d': batch, limit: batch.length * 2 }])))).flat();
227
+ const holders = new Map();
228
+ for (const event of found) {
229
+ const d = tagOf(event, 'd');
230
+ if (!d || !kinds.includes(event.kind))
231
+ continue;
232
+ const set = holders.get(d) ?? new Set();
233
+ set.add(`${event.kind}:${event.pubkey}`);
234
+ holders.set(d, set);
235
+ }
236
+ return entries.map((entry) => {
237
+ const set = holders.get(entry.file);
238
+ return { file: entry.file, address: set?.size === 1 ? `${[...set][0]}:${entry.file}` : null, entry };
239
+ });
240
+ }
241
+ //# sourceMappingURL=topics.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"topics.js","sourceRoot":"","sources":["../src/topics.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.70.2",
3
+ "version": "0.71.0",
4
4
  "description": "Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/index.ts CHANGED
@@ -147,6 +147,27 @@ export {
147
147
  type MoveRefusal,
148
148
  } from './folders.js'
149
149
 
150
+ /**
151
+ * SPEC §6.14: a topic's list of files from any Folder, one `kind:1851` entry
152
+ * per file by its id. Plan an entry, read a topic's list, and ask which topics
153
+ * list a file (`#o`); a file's own changes (`#O`) never hold an entry.
154
+ */
155
+ export {
156
+ planListInTopic,
157
+ planRemoveFromTopic,
158
+ topicsOfFile,
159
+ topicList,
160
+ topicsOfFileFilter,
161
+ topicListFilter,
162
+ listEntries,
163
+ listsField,
164
+ LISTED_FILE_KINDS,
165
+ type ListHolder,
166
+ type ListEntry,
167
+ type FileTopic,
168
+ type ListedFile,
169
+ } from './topics.js'
170
+
150
171
  /**
151
172
  * What an app link names, and where a file is mentioned — once for every app
152
173
  * (SPEC §7.7, §13.1, §6.8; PEEKM-7). Each app passes its relay read; none
package/src/topics.ts ADDED
@@ -0,0 +1,295 @@
1
+ /**
2
+ * A topic's list of files — SPEC §6.14 "A file's list of other files"; record
3
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
4
+ *
5
+ * A topic lists files from any Folder, one entry per file, by the file's id.
6
+ * An entry is a `kind:1851` change on the topic: `a` and `O` name the topic,
7
+ * `field` is `lists:<d>`, `value` is `true` or `false`, `h` is the topic's
8
+ * Folder, then `ts`, then `["o", <d>]` naming the listed file. The newest
9
+ * entry per topic and file counts (§6.3).
10
+ *
11
+ * `O` is the file the change is about and `o` another file it points at
12
+ * (why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-change-is-about-its-file-as-a-comment-is.md),
13
+ * so `#o` asks which topics list a file and `#O` asks what changed on a topic,
14
+ * and a file's own changes never include a topic's entry about it.
15
+ *
16
+ * Here rather than in each app because Peek, Ship and Leaf all add, remove
17
+ * and read entries, and a reader rule kept in one of them only is a list that
18
+ * reads differently in the next.
19
+ *
20
+ * ## What a listing is not
21
+ *
22
+ * It grants nothing: who reads the listed file is its own Folder's rule. It is
23
+ * not a mention, not a parent and not a Folder's listing, so Mentioned in, the
24
+ * archive chain and a Folder move all ignore it. It carries no `p`, so it adds
25
+ * nobody to the file (§11.8).
26
+ */
27
+ import { type SignedEvent, type UnsignedEvent } from '@estiva-app/protocol'
28
+ import { byOrder } from '@estiva-app/conversation'
29
+ import { folderOf, type QueryFn } from './projection.js'
30
+
31
+ const KIND_CHANGE = 1851
32
+ /** The topic (bare file) kind: the only lists this stage reads (Miky, 2026-10-30). */
33
+ const KIND_TOPIC = 30840
34
+ const KIND_FOLDER = 39000
35
+ /** Listed ids resolved per request: 2 × this stays under a relay's usual `limit` cap. */
36
+ const RESOLVE_BATCH = 100
37
+ /**
38
+ * The file kinds a listed id is looked for under by default: topic, document,
39
+ * project, issue. Never a bare `#d`, since a Folder's `kind:39000` shares its
40
+ * uuid (§11.1). An app that knows more kinds from manifests passes them.
41
+ */
42
+ export const LISTED_FILE_KINDS: readonly number[] = [30840, 30842, 30850, 30851]
43
+
44
+ const ADDRESS = /^(\d+):([0-9a-f]{64}):(.+)$/
45
+ const FIELD_PREFIX = 'lists:'
46
+
47
+ /** The field an entry for `file` sets: `lists:<d>`. */
48
+ export function listsField(file: string): string {
49
+ return `${FIELD_PREFIX}${file}`
50
+ }
51
+
52
+ /** The file a list carries entries on, as a write needs it. */
53
+ export interface ListHolder {
54
+ /** Its address, `<kind>:<pubkey>:<d>`. */
55
+ address: string
56
+ /** Its Folder, read from its root (`folderOf`), never the Folder it was opened from (§6.2). */
57
+ folder: string
58
+ }
59
+
60
+ function entry(
61
+ pubkey: string,
62
+ createdAtMs: number,
63
+ args: { list: ListHolder; file: string; listed: boolean; note?: string },
64
+ ): UnsignedEvent {
65
+ const holder = ADDRESS.exec(args.list.address)
66
+ if (!holder) throw new Error(`not a file address: ${JSON.stringify(args.list.address)}`)
67
+ if (!args.list.folder) throw new Error('a list entry names the Folder of the file that keeps the list')
68
+ if (!args.file || /\s/.test(args.file)) throw new Error(`not a file id: ${JSON.stringify(args.file)}`)
69
+ // A reader ignores a file on its own list (§6.14): refuse it here rather than publish an entry that shows nothing.
70
+ if (args.file === holder[3]) throw new Error('a file is not on its own list')
71
+ if (!Number.isSafeInteger(createdAtMs) || createdAtMs < 0) throw new Error(`not epoch milliseconds: ${createdAtMs}`)
72
+ return {
73
+ pubkey,
74
+ created_at: Math.floor(createdAtMs / 1000),
75
+ kind: KIND_CHANGE,
76
+ tags: [
77
+ ['a', args.list.address],
78
+ ['O', holder[3]],
79
+ ['field', listsField(args.file)],
80
+ ['value', args.listed ? 'true' : 'false'],
81
+ ['h', args.list.folder],
82
+ ['ts', String(createdAtMs)],
83
+ ['o', args.file],
84
+ ],
85
+ // Empty unless the person wrote a note: each app says "added" and "removed" in its own words (§6.14).
86
+ content: args.note ?? '',
87
+ }
88
+ }
89
+
90
+ /**
91
+ * Put a file on a topic's list: `[kind:1851 lists:<d> = true]`, signed by
92
+ * whoever adds it. `file` is the listed file's id (its `d`), from any Folder.
93
+ */
94
+ export function planListInTopic(
95
+ pubkey: string,
96
+ createdAtMs: number,
97
+ args: { topic: ListHolder; file: string; note?: string },
98
+ ): UnsignedEvent[] {
99
+ return [entry(pubkey, createdAtMs, { list: args.topic, file: args.file, listed: true, note: args.note })]
100
+ }
101
+
102
+ /** Take a file off a topic's list: `[kind:1851 lists:<d> = false]`. {@link planListInTopic} in reverse. */
103
+ export function planRemoveFromTopic(
104
+ pubkey: string,
105
+ createdAtMs: number,
106
+ args: { topic: ListHolder; file: string; note?: string },
107
+ ): UnsignedEvent[] {
108
+ return [entry(pubkey, createdAtMs, { list: args.topic, file: args.file, listed: false, note: args.note })]
109
+ }
110
+
111
+ /** Which topics list a file: every entry naming its id in `o`. Fold with {@link listEntries}. */
112
+ export function topicsOfFileFilter(file: string): Record<string, unknown> {
113
+ return { kinds: [KIND_CHANGE], '#o': [file] }
114
+ }
115
+
116
+ /** A topic's changes, its list entries among them: `#O` on its id. Fold with {@link listEntries}. */
117
+ export function topicListFilter(topic: string): Record<string, unknown> {
118
+ const holder = ADDRESS.exec(topic)
119
+ return { kinds: [KIND_CHANGE], '#O': [holder ? holder[3] : topic] }
120
+ }
121
+
122
+ /** The newest entry for one list and one file. */
123
+ export interface ListEntry {
124
+ /** The address of the file keeping the list (a topic). */
125
+ list: string
126
+ /** The listed file's id. */
127
+ file: string
128
+ /** The entry's Folder: its first `h` with a value. */
129
+ folder: string
130
+ /** `true` when the newest entry lists the file. */
131
+ listed: boolean
132
+ event: SignedEvent
133
+ }
134
+
135
+ const tagOf = (event: Pick<SignedEvent, 'tags'>, name: string): string | undefined =>
136
+ event.tags.find((t) => t[0] === name && t[1])?.[1]
137
+
138
+ /** The file an entry lists: the `<d>` of its `lists:<d>` field, or `null` for any other change. */
139
+ const listedIn = (event: Pick<SignedEvent, 'tags'>): string | null => {
140
+ const field = tagOf(event, 'field')
141
+ return field?.startsWith(FIELD_PREFIX) ? field.slice(FIELD_PREFIX.length) || null : null
142
+ }
143
+
144
+ /**
145
+ * The newest entry per list and file, from any mix of changes: the reader
146
+ * rules of §6.14. A change counts as an entry only when its field is
147
+ * `lists:<d>`, one of its `o` tags is that same `<d>` (an `o` the field does
148
+ * not name is some other relation, a move's new parent for one), its `a`
149
+ * names a file whose `d` is its `O`, `<d>` is not that file itself, and it
150
+ * names a Folder. Anything else is skipped, not folded, so a malformed entry
151
+ * never hides a good one. A `value` other than exactly `true` does not list
152
+ * the file.
153
+ *
154
+ * `folderOfList` is §6.2's Folder check against each list's root, applied
155
+ * before the fold: an entry filed in any other Folder must not become the
156
+ * newest and hide the good one before it. A list it answers no Folder for (an
157
+ * unread root, or one naming none) keeps no entry. Without it the check is the
158
+ * caller's; {@link topicsOfFile} and {@link topicList} pass it.
159
+ */
160
+ export function listEntries(
161
+ events: readonly SignedEvent[],
162
+ folderOfList?: (list: string) => string | null | undefined,
163
+ ): ListEntry[] {
164
+ const newest = new Map<string, { event: SignedEvent; file: string }>()
165
+ for (const event of events) {
166
+ if (event.kind !== KIND_CHANGE) continue
167
+ const file = listedIn(event)
168
+ if (!file || !event.tags.some((t) => t[0] === 'o' && t[1] === file)) continue
169
+ const list = tagOf(event, 'a')
170
+ const holder = list ? ADDRESS.exec(list) : null
171
+ const folder = tagOf(event, 'h')
172
+ if (!holder || tagOf(event, 'O') !== holder[3] || file === holder[3] || !folder) continue
173
+ if (folderOfList && folderOfList(list!) !== folder) continue
174
+ const key = `${list}\n${file}`
175
+ const seen = newest.get(key)
176
+ if (!seen || byOrder(seen.event, event) < 0) newest.set(key, { event, file })
177
+ }
178
+ return [...newest.values()].map(({ event, file }) => ({
179
+ list: tagOf(event, 'a')!,
180
+ file,
181
+ folder: tagOf(event, 'h')!,
182
+ listed: event.tags.find((t) => t[0] === 'value')?.[1] === 'true',
183
+ event,
184
+ }))
185
+ }
186
+
187
+ /** The roots of the given list addresses that the reader can read, by address. */
188
+ async function rootsOf(query: QueryFn, addresses: readonly string[]): Promise<Map<string, SignedEvent>> {
189
+ const byKindAuthor = new Map<string, { kind: number; pubkey: string; ds: string[] }>()
190
+ for (const address of addresses) {
191
+ const [, kind, pubkey, d] = ADDRESS.exec(address) ?? []
192
+ if (!d) continue
193
+ const key = `${kind}:${pubkey}`
194
+ const group = byKindAuthor.get(key) ?? { kind: Number(kind), pubkey, ds: [] }
195
+ group.ds.push(d)
196
+ byKindAuthor.set(key, group)
197
+ }
198
+ if (byKindAuthor.size === 0) return new Map()
199
+ const filters = [...byKindAuthor.values()].map(({ kind, pubkey, ds }) => ({ kinds: [kind], authors: [pubkey], '#d': ds, limit: ds.length }))
200
+ const roots = new Map<string, SignedEvent>()
201
+ for (const root of await query(filters)) {
202
+ const address = `${root.kind}:${root.pubkey}:${tagOf(root, 'd') ?? ''}`
203
+ const held = roots.get(address)
204
+ // Two versions of one record: NIP-01's later created_at, then the lower id (§6.3).
205
+ if (!held || root.created_at > held.created_at || (root.created_at === held.created_at && root.id < held.id)) roots.set(address, root)
206
+ }
207
+ return roots
208
+ }
209
+
210
+ /** A topic that lists a file. */
211
+ export interface FileTopic {
212
+ /** The topic's address. */
213
+ address: string
214
+ /** The topic's root, as the reader read it. */
215
+ root: SignedEvent
216
+ entry: ListEntry
217
+ }
218
+
219
+ /**
220
+ * Which topics list a file — `{kinds:[1851], "#o":[<d>]}`, folded per topic.
221
+ *
222
+ * Keeps an entry only when its newest value lists the file, it is on a topic
223
+ * (only topics' lists are read, Miky 2026-10-30), the topic's root is one the
224
+ * reader can read (a deleted or unreadable topic drops out), and the entry is
225
+ * filed in the topic's own Folder (§6.2). Two reads: the entries, then the
226
+ * topics' roots.
227
+ */
228
+ export async function topicsOfFile(query: QueryFn, file: string): Promise<FileTopic[]> {
229
+ const isTopic = (entry: ListEntry) => entry.file === file && entry.list.startsWith(`${KIND_TOPIC}:`)
230
+ const events = await query([topicsOfFileFilter(file)])
231
+ const lists = [...new Set(listEntries(events).filter(isTopic).map((entry) => entry.list))]
232
+ if (lists.length === 0) return []
233
+ const roots = await rootsOf(query, lists)
234
+ const folderOfList = (list: string) => {
235
+ const root = roots.get(list)
236
+ return root ? folderOf(root) : null
237
+ }
238
+ return listEntries(events, folderOfList)
239
+ .filter((entry) => entry.listed && isTopic(entry))
240
+ .map((entry) => ({ address: entry.list, root: roots.get(entry.list)!, entry }))
241
+ }
242
+
243
+ /** A file on a topic's list. */
244
+ export interface ListedFile {
245
+ /** The listed file's id. */
246
+ file: string
247
+ /** Its address when exactly one file the reader can read holds the id, else `null`: not drawn, not counted. */
248
+ address: string | null
249
+ entry: ListEntry
250
+ }
251
+
252
+ /**
253
+ * A topic's list, by the topic's address: its entries whose newest value
254
+ * lists the file, filed in the Folder the topic's root names (§6.2; read here,
255
+ * never taken from the caller), in no promised order (sort as the design
256
+ * says; `entry.event` carries the time), each id resolved over `fileKinds` by
257
+ * `#d`. A topic the reader cannot read, or whose root names no Folder, lists
258
+ * nothing. An id held by none the reader can read, or by two, resolves to
259
+ * `null`: a consumer draws and counts only the resolved ones (§3.2, the count
260
+ * is the disclosure).
261
+ */
262
+ export async function topicList(
263
+ query: QueryFn,
264
+ topic: string,
265
+ options: { fileKinds?: readonly number[] } = {},
266
+ ): Promise<ListedFile[]> {
267
+ const [roots, events] = await Promise.all([rootsOf(query, [topic]), query([topicListFilter(topic)])])
268
+ const root = roots.get(topic)
269
+ const folder = root ? folderOf(root) : null
270
+ if (!folder) return []
271
+ const entries = listEntries(events, (list) => (list === topic ? folder : null))
272
+ .filter((entry) => entry.listed)
273
+ .sort((a, b) => byOrder(a.event, b.event))
274
+ if (entries.length === 0) return []
275
+ const ids = [...new Set(entries.map((entry) => entry.file))]
276
+ // Never a Folder's `39000`, which shares its uuid (§11.1): an id only a Folder holds resolves to nothing.
277
+ const kinds = (options.fileKinds ?? LISTED_FILE_KINDS).filter((kind) => kind !== KIND_FOLDER)
278
+ // Room for a second holder of every id, so two holders are seen as two; in
279
+ // batches, so a relay's cap on `limit` cannot cut a long list short.
280
+ const batches: string[][] = []
281
+ for (let i = 0; i < ids.length; i += RESOLVE_BATCH) batches.push(ids.slice(i, i + RESOLVE_BATCH))
282
+ const found = (await Promise.all(batches.map((batch) => query([{ kinds, '#d': batch, limit: batch.length * 2 }])))).flat()
283
+ const holders = new Map<string, Set<string>>()
284
+ for (const event of found) {
285
+ const d = tagOf(event, 'd')
286
+ if (!d || !kinds.includes(event.kind)) continue
287
+ const set = holders.get(d) ?? new Set<string>()
288
+ set.add(`${event.kind}:${event.pubkey}`)
289
+ holders.set(d, set)
290
+ }
291
+ return entries.map((entry) => {
292
+ const set = holders.get(entry.file)
293
+ return { file: entry.file, address: set?.size === 1 ? `${[...set][0]}:${entry.file}` : null, entry }
294
+ })
295
+ }