@estiva-app/interop 0.66.0 → 0.68.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.66.0",
3
+ "version": "0.68.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
@@ -110,6 +110,7 @@ export {
110
110
  * breadcrumbs and move targets, with cycles cut. No requests.
111
111
  */
112
112
  export { nestingOf, type Nestable, type Nesting } from './nesting.js'
113
+ export { createLoadQuery } from './loadQuery.js'
113
114
 
114
115
  /**
115
116
  * The files `[` offers (PEE-21): resolved objects as rows, and typed text as
@@ -0,0 +1,157 @@
1
+ /**
2
+ * One load's reads, each asked of the relay once (APP-2).
3
+ *
4
+ * A screen that lists the workspace reads it in two steps: `listFolders`, which
5
+ * reads every change naming every listed file to learn what is archived, and
6
+ * then `resolveFolderContents` once per Folder, which reads the same changes
7
+ * again to build each file. Measured on production 26 Oct: Leaf's Weekly Plans
8
+ * load read 79 MB, 78 MB of it changes, while 36.9 MB of changes existed.
9
+ *
10
+ * {@link createLoadQuery} wraps the caller's query for the length of one load:
11
+ *
12
+ * - **A read that came back complete is not asked again.** A filter asking for
13
+ * every event of one kind naming any of a list of values in one tag — the
14
+ * shape every change read uses — is complete for each of those values when
15
+ * the relay's answer did not fill the page. A later filter in the same load
16
+ * naming such a value gets the events already read, and asks only for the
17
+ * rest.
18
+ * - **A read in flight is joined, not repeated.** A value still being read is
19
+ * waited for, and an identical request still in flight shares its answer.
20
+ *
21
+ * **One load, never longer.** What it holds is the relay's answer at the moment
22
+ * of the load: a refresh, a live update, or the next screen must read afresh,
23
+ * so the caller makes one per load and drops it after. Caching changes across
24
+ * loads is how a live list becomes a screenshot (`ProjectionCache` keeps only
25
+ * manifests for that reason).
26
+ *
27
+ * A refused read fails every call waiting on it, and is forgotten, so a retry
28
+ * asks again: a listing missing what it should have read must still fail
29
+ * loudly (`placeRecordChannels`, 2026-09-22).
30
+ */
31
+ import { RELAY_PAGE_CEILING, type SignedEvent } from '@estiva-app/protocol'
32
+ import type { QueryFn } from './projection.js'
33
+
34
+ type Filter = Record<string, unknown>
35
+
36
+ /** `{ kinds: [kind], '#<tag>': values, limit }` and nothing else. */
37
+ interface ByTag {
38
+ kind: number
39
+ tag: string
40
+ values: string[]
41
+ limit: number
42
+ }
43
+
44
+ function byTagOf(filter: Filter): ByTag | null {
45
+ const keys = Object.keys(filter)
46
+ const tagKeys = keys.filter((key) => key.startsWith('#'))
47
+ if (keys.length !== 3 || tagKeys.length !== 1 || tagKeys[0].length !== 2) return null
48
+ const { kinds, limit } = filter
49
+ const values = filter[tagKeys[0]]
50
+ if (!Array.isArray(kinds) || kinds.length !== 1 || typeof kinds[0] !== 'number') return null
51
+ if (typeof limit !== 'number' || !Array.isArray(values) || values.length === 0) return null
52
+ if (!values.every((value) => typeof value === 'string')) return null
53
+ return { kind: kinds[0], tag: tagKeys[0].slice(1), values, limit }
54
+ }
55
+
56
+ /**
57
+ * The events naming each of the filter's values, if this answer holds them
58
+ * all: fewer came back for the filter than its page. The count is of
59
+ * everything in the pooled answer the filter matches, which can only
60
+ * overcount — so a page is never taken as complete when it was full.
61
+ */
62
+ function completeByValue(shape: ByTag, answer: SignedEvent[]): Map<string, SignedEvent[]> | null {
63
+ const byValue = new Map<string, SignedEvent[]>(shape.values.map((value) => [value, []]))
64
+ let matched = 0
65
+ for (const event of answer) {
66
+ if (event.kind !== shape.kind) continue
67
+ let hit = false
68
+ for (const [name, value] of event.tags) {
69
+ const held = name === shape.tag ? byValue.get(value) : undefined
70
+ if (held && !held.includes(event)) {
71
+ held.push(event)
72
+ hit = true
73
+ }
74
+ }
75
+ if (hit) matched++
76
+ }
77
+ return matched >= Math.min(shape.limit, RELAY_PAGE_CEILING) ? null : byValue
78
+ }
79
+
80
+ /** A query for one load: see the module's note. Make one per load and drop it after. */
81
+ export function createLoadQuery(query: QueryFn): QueryFn {
82
+ // Per `<kind>:<tag>:<value>`: the events naming it, `null` while unknown
83
+ // (the page was full), or the read still in flight — and the limit it was
84
+ // read with, since only an ask with as large a limit would have got them all.
85
+ const known = new Map<string, { limit: number; events: Promise<SignedEvent[] | null> }>()
86
+ const flights = new Map<string, Promise<SignedEvent[]>>()
87
+
88
+ const ask = (filters: Filter[]): Promise<SignedEvent[]> => {
89
+ const key = JSON.stringify(filters)
90
+ const held = flights.get(key)
91
+ if (held) return held
92
+ const flight = query(filters).finally(() => flights.delete(key))
93
+ flights.set(key, flight)
94
+ return flight
95
+ }
96
+
97
+ return async (filters) => {
98
+ const send: Filter[] = []
99
+ const asked: ByTag[] = []
100
+ const joined: { shape: ByTag; value: string; entry: Promise<SignedEvent[] | null> }[] = []
101
+ for (const filter of filters) {
102
+ const shape = byTagOf(filter)
103
+ if (!shape) {
104
+ send.push(filter)
105
+ continue
106
+ }
107
+ const fresh: string[] = []
108
+ for (const value of new Set(shape.values)) {
109
+ const entry = known.get(`${shape.kind}:${shape.tag}:${value}`)
110
+ // A smaller page than the read had might not have held them all: the relay is asked, as it was.
111
+ if (entry && entry.limit <= shape.limit) joined.push({ shape, value, entry: entry.events })
112
+ else fresh.push(value)
113
+ }
114
+ if (fresh.length === 0) continue
115
+ send.push({ ...filter, [`#${shape.tag}`]: fresh })
116
+ asked.push({ ...shape, values: fresh })
117
+ }
118
+
119
+ const answer = send.length ? ask(send) : Promise.resolve([])
120
+ for (const shape of asked) {
121
+ const split = answer.then((events) => completeByValue(shape, events))
122
+ for (const value of shape.values) {
123
+ const key = `${shape.kind}:${shape.tag}:${value}`
124
+ // A larger read of the same value, in flight or done, is kept.
125
+ if ((known.get(key)?.limit ?? -1) > shape.limit) continue
126
+ const entry = { limit: shape.limit, events: split.then((byValue) => byValue?.get(value) ?? null) }
127
+ known.set(key, entry)
128
+ // Forget a refused read, and a page that came back full, so the next ask goes to the relay.
129
+ const forget = () => {
130
+ if (known.get(key) === entry) known.delete(key)
131
+ }
132
+ entry.events.then((events) => events ?? forget(), forget)
133
+ }
134
+ }
135
+
136
+ const out = [...(await answer)]
137
+ // Per filter of the caller's, so a re-ask keeps the grouping it chose.
138
+ const unknown = new Map<ByTag, string[]>()
139
+ for (const { shape, value, entry } of joined) {
140
+ const events = await entry
141
+ if (events) out.push(...events)
142
+ // That read's page was full: ask for this value here, as the caller would have.
143
+ else unknown.set(shape, [...(unknown.get(shape) ?? []), value])
144
+ }
145
+ if (unknown.size) {
146
+ out.push(
147
+ ...(await ask(
148
+ [...unknown].map(([shape, values]) => ({ kinds: [shape.kind], [`#${shape.tag}`]: values, limit: shape.limit })),
149
+ )),
150
+ )
151
+ }
152
+
153
+ // One copy of each event, as one request to the relay answers.
154
+ const seen = new Set<string>()
155
+ return out.filter((e) => !seen.has(e.id) && !!seen.add(e.id))
156
+ }
157
+ }
package/src/projection.ts CHANGED
@@ -4154,8 +4154,14 @@ async function walkArchivedAbove(
4154
4154
  * every change naming its addresses — titles, statuses, moves — not only the
4155
4155
  * archives, and a relay answers newest first, so a small group keeps the
4156
4156
  * archive change inside the page.
4157
+ *
4158
+ * Ten, because the relay slows sharply past about twelve values in one `#a`
4159
+ * on `kind:1851`, while many small filters in one request do not. Measured as
4160
+ * the agent on production 2026-10-26, 49 Folder channels with no change among
4161
+ * them: one filter of 49 took 15–20 s, of 25 3.5 s, of 12 0.3 s, and 49
4162
+ * filters of one 0.3–0.5 s (43e9a775). `kind:1111` stayed under a second at 49.
4157
4163
  */
4158
- const ARCHIVE_READ_GROUP = 25
4164
+ const ARCHIVE_READ_GROUP = 10
4159
4165
 
4160
4166
  /**
4161
4167
  * Identifiers per root filter in {@link resolveParents}. A root read answers
@@ -6320,7 +6326,24 @@ export interface FolderContents extends FolderSummary {
6320
6326
  * goes; a sidebar built by walking something else would inherit exactly that.
6321
6327
  * This asks for folders by kind.
6322
6328
  */
6323
- export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
6329
+ export async function listFolders(
6330
+ query: QueryFn,
6331
+ options: {
6332
+ /**
6333
+ * `false` leaves out what only a record's channel needs — a Ship project's
6334
+ * conversation placed under the Folder that lists the project, and archived
6335
+ * with it — and so reads only the Folders' own archives. Those channels have
6336
+ * no state, so {@link topLevelFolders} is the same either way.
6337
+ *
6338
+ * For a reader that walks Folders for their files and draws no dots (the
6339
+ * agent's Peek topics): placing them reads every change to every file a
6340
+ * Folder lists, and a text save is a whole document. Measured as the agent
6341
+ * on production 2026-10-26: 149 s and 22.8 MB with them, where the Folders'
6342
+ * records alone were 0.9 s.
6343
+ */
6344
+ recordChannels?: boolean
6345
+ } = {},
6346
+ ): Promise<FolderSummary[]> {
6324
6347
  const { events, byId } = await readFolderRecords(query)
6325
6348
  /*
6326
6349
  A folder listed in another folder's state is a file there. Read off the
@@ -6342,7 +6365,17 @@ export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
6342
6365
  listedIn.set(identifier, containers)
6343
6366
  }
6344
6367
  }
6345
- const { recordsOf, archives, rootOf } = await placeRecordChannels(events, byId, listedIn, query)
6368
+ const { recordsOf, archives, rootOf } =
6369
+ options.recordChannels === false
6370
+ ? {
6371
+ recordsOf: new Map<string, string[]>(),
6372
+ archives: await readArchiveChanges(
6373
+ [...byId.values()].flatMap((folder) => (folder.channel ? [folder.channel] : [])),
6374
+ query,
6375
+ ),
6376
+ rootOf: new Map<string, SignedEvent>(),
6377
+ }
6378
+ : await placeRecordChannels(events, byId, listedIn, query)
6346
6379
  for (const [id, containers] of listedIn) {
6347
6380
  const folder = byId.get(id)
6348
6381
  if (folder) folder.listedIn = containers
@@ -6802,6 +6835,17 @@ export async function resolveFolderContents(
6802
6835
  * card ({@link ArchiveReadOptions.folderFiles}).
6803
6836
  */
6804
6837
  listedOnly?: boolean
6838
+ /**
6839
+ * Only the listed files of these kinds: the rest are neither read nor
6840
+ * returned, as if no app drew them. Every rule above still holds for the
6841
+ * ones kept — a parent of another kind is read as a link reads it.
6842
+ *
6843
+ * For a reader that draws only some kinds (the agent's Peek topics: bare
6844
+ * files and nested Folders), since every listed file is read with its whole
6845
+ * change history: Estiva HQ cost 75 s and 11 MB on 2026-10-26, nearly all
6846
+ * of it project descriptions.
6847
+ */
6848
+ kinds?: readonly number[]
6805
6849
  } = {},
6806
6850
  ): Promise<FolderContents> {
6807
6851
  // 1. The folder itself. Both kinds in one trip: the state is the model and
@@ -6833,7 +6877,7 @@ export async function resolveFolderContents(
6833
6877
  : {}),
6834
6878
  }
6835
6879
 
6836
- const { addresses, placed } = state
6880
+ const { addresses: everyAddress, placed } = state
6837
6881
  ? // §5.2: one tag type lists every file, topics included, with no special
6838
6882
  // case. The order is the folder's, so it is preserved rather than sorted.
6839
6883
  {
@@ -6843,6 +6887,10 @@ export async function resolveFolderContents(
6843
6887
  : options.listedOnly
6844
6888
  ? { addresses: [], placed: new Map<string, SignedEvent[]>() }
6845
6889
  : await addressesByContainment(folder, query)
6890
+ const { kinds } = options
6891
+ const addresses = kinds
6892
+ ? everyAddress.filter((address) => kinds.includes(addressPointerOf(address)?.kind ?? NaN))
6893
+ : everyAddress
6846
6894
 
6847
6895
  if (addresses.length === 0) {
6848
6896
  // Nothing listed, so no change query to ride on: the Folder's own archive
@@ -6898,22 +6946,26 @@ export async function resolveFolderContents(
6898
6946
  ]),
6899
6947
  ]
6900
6948
  const nestedFolderIds = pointers.filter(({ pointer }) => pointer.kind === KIND_CHANNEL).map(({ pointer }) => pointer.identifier)
6901
- const events = await query([
6949
+ // SPEC's change kind is read whole by the archive filters below, so a filter
6950
+ // for it here only repeated them: its 500 newest are among each group's page
6951
+ // (APP-2, where it was most of a second copy of every change).
6952
+ const otherChangeKinds = changeKinds.filter((kind) => kind !== ARCHIVE_RULE.changeKind)
6953
+ // Chunked: at ten addresses per archive filter, a Folder of about 1,200 files
6954
+ // would pass the relay's filters-per-request ceiling in one request.
6955
+ const events = await queryChunked([
6902
6956
  ...[...groups.values()].map(({ pointer, addresses: group }) => ({
6903
6957
  kinds: [pointer.kind],
6904
6958
  authors: [pointer.pubkey],
6905
6959
  '#d': group.map((a) => referenceToPointer(a).identifier),
6906
6960
  limit: group.length,
6907
6961
  })),
6908
- { kinds: changeKinds, '#a': addresses, limit: 500 },
6909
- // The archives again, in groups small enough that a busy Folder's other
6910
- // changes cannot push them off the page — the filter above holds 500
6911
- // changes for every file together, and one Folder has already had 688.
6912
- // Same request.
6962
+ ...(otherChangeKinds.length ? [{ kinds: otherChangeKinds, '#a': addresses, limit: 500 }] : []),
6963
+ // Every change, in groups small enough that a busy Folder's changes cannot
6964
+ // push one file's off the page — one Folder has already had 688. Same request.
6913
6965
  ...archiveFilters(channelAddress ? [...addresses, channelAddress] : addresses),
6914
6966
  // A Folder listed here counts its archive only from its own admins (§3.2). Same request.
6915
6967
  ...(nestedFolderIds.length ? [{ kinds: [KIND_CHANNEL_ADMINS], '#d': nestedFolderIds, limit: nestedFolderIds.length }] : []),
6916
- ])
6968
+ ], query)
6917
6969
  const ownArchive = folderArchiveOf(events, summary)
6918
6970
  if (ownArchive) summary.archived = ownArchive
6919
6971