@estiva-app/interop 0.45.0 → 0.46.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,57 @@
1
+ /**
2
+ * The files `[` offers, as @estiva-app/conversation ranks them (PEE-21).
3
+ *
4
+ * conversation's `rankReferences` orders candidates and knows nothing of a
5
+ * relay; this is the half that turns what a relay holds into candidates — a
6
+ * resolved object into a row, and typed text into the search tier — so Peek
7
+ * and Ship draw the same rows from the same reads.
8
+ *
9
+ * A row is the type word and the current title; an issue is captioned with its
10
+ * project's title, and nothing names a Folder (Miky, 2026-10-03). Only what the
11
+ * reader resolved is offered: an object the relay did not hand back to them is
12
+ * never a row, so nothing unreadable is offered. An archived file is offered
13
+ * at the lowest priority, and so is an issue in an archived project.
14
+ */
15
+ import { type ReferenceCandidate, type ReferenceType } from '@estiva-app/conversation';
16
+ import { type ForeignObject, type ProjectionCache, type QueryFn } from './projection.js';
17
+ /** The kinds `[` offers as files, and the type word each draws as. */
18
+ export declare const REFERENCE_FILE_TYPES: Readonly<Record<number, ReferenceType>>;
19
+ export interface FileCandidatesOptions {
20
+ cache?: ProjectionCache;
21
+ /** When each address was last written or read, in seconds — newer first within a tier. */
22
+ at?: ReadonlyMap<string, number>;
23
+ }
24
+ /**
25
+ * Rows for resolved files, all in one tier.
26
+ *
27
+ * An issue's caption is its project's title, and an issue in an archived
28
+ * project is archived with it: the project is taken from `objects` when it is
29
+ * among them, and otherwise read in one more batch for every missing project
30
+ * at once (roots and changes only). A project that cannot be read leaves the
31
+ * caption empty rather than dropping the issue. Objects that are not
32
+ * offerable — unreachable, untitled, or of a kind `[` does not offer — are
33
+ * left out.
34
+ */
35
+ export declare function fileCandidates(objects: readonly (ForeignObject | null | undefined)[], tier: number, query: QueryFn, { cache, at }?: FileCandidatesOptions): Promise<ReferenceCandidate[]>;
36
+ export interface SearchFileReferencesOptions extends Omit<FileCandidatesOptions, 'at'> {
37
+ /** How many roots, and separately how many renames, the relay is asked for. Default 32. */
38
+ limit?: number;
39
+ }
40
+ /**
41
+ * The files whose **current** title holds `text`, as the search tier.
42
+ *
43
+ * The relay indexes a root's `title` and a rename's `value` (relay ticket
44
+ * 6fea004e); neither is the current title on its own — a root keeps the name
45
+ * it was created with, and a rename found by an old word may since have been
46
+ * renamed again. So a hit is only an address: each is read back as its root
47
+ * and changes, folded through its app's manifest, and kept only when what it
48
+ * is called now matches what was typed.
49
+ *
50
+ * Roots and renames are asked for separately, so a burst of renames cannot
51
+ * crowd every root out of the answer, and with buzz's prefix mode, so the word
52
+ * being typed matches before it is finished. A relay that indexes none of these
53
+ * kinds answers nothing, and so does this. A failed read rejects, for
54
+ * `referenceSearch` to answer no hits for a while.
55
+ */
56
+ export declare function searchFileReferences(text: string, query: QueryFn, { limit, ...options }?: SearchFileReferencesOptions): Promise<ReferenceCandidate[]>;
57
+ //# sourceMappingURL=references.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAKL,KAAK,kBAAkB,EACvB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAA;AAKxB,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAIxE,CAAA;AAcD,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,0FAA0F;IAC1F,EAAE,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACtD,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAK,EAAE,EAAE,EAAE,GAAE,qBAA0B,GACxC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA0B/B;AAED,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CAAC,qBAAqB,EAAE,IAAI,CAAC;IACpF,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAU,EAAE,GAAG,OAAO,EAAE,GAAE,2BAAgC,GAC3D,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAuB/B"}
@@ -0,0 +1,117 @@
1
+ /**
2
+ * The files `[` offers, as @estiva-app/conversation ranks them (PEE-21).
3
+ *
4
+ * conversation's `rankReferences` orders candidates and knows nothing of a
5
+ * relay; this is the half that turns what a relay holds into candidates — a
6
+ * resolved object into a row, and typed text into the search tier — so Peek
7
+ * and Ship draw the same rows from the same reads.
8
+ *
9
+ * A row is the type word and the current title; an issue is captioned with its
10
+ * project's title, and nothing names a Folder (Miky, 2026-10-03). Only what the
11
+ * reader resolved is offered: an object the relay did not hand back to them is
12
+ * never a row, so nothing unreadable is offered. An archived file is offered
13
+ * at the lowest priority, and so is an issue in an archived project.
14
+ */
15
+ import { FILE_TIER, fileReference, KIND_CHANGE, referenceMatch, } from '@estiva-app/conversation';
16
+ import { isClosedStatus, KIND_BARE_FILE, resolveForeignRoots, } from './projection.js';
17
+ const KIND_PROJECT = 30850;
18
+ const KIND_ISSUE = 30851;
19
+ /** The kinds `[` offers as files, and the type word each draws as. */
20
+ export const REFERENCE_FILE_TYPES = {
21
+ [KIND_PROJECT]: 'project',
22
+ [KIND_ISSUE]: 'issue',
23
+ [KIND_BARE_FILE]: 'topic',
24
+ };
25
+ const typeOf = (kind) => REFERENCE_FILE_TYPES[kind];
26
+ /** An object `[` may offer: a file kind it knows, resolved, with a title. */
27
+ const offerable = (object) => !!object &&
28
+ !!object.address &&
29
+ !object.unreachable &&
30
+ typeOf(object.kind) !== undefined &&
31
+ !!object.slots.title?.value.trim();
32
+ /**
33
+ * Rows for resolved files, all in one tier.
34
+ *
35
+ * An issue's caption is its project's title, and an issue in an archived
36
+ * project is archived with it: the project is taken from `objects` when it is
37
+ * among them, and otherwise read in one more batch for every missing project
38
+ * at once (roots and changes only). A project that cannot be read leaves the
39
+ * caption empty rather than dropping the issue. Objects that are not
40
+ * offerable — unreachable, untitled, or of a kind `[` does not offer — are
41
+ * left out.
42
+ */
43
+ export async function fileCandidates(objects, tier, query, { cache, at } = {}) {
44
+ const files = objects.filter(offerable);
45
+ const parents = new Map();
46
+ for (const o of objects)
47
+ if (o?.address && !o.unreachable)
48
+ parents.set(o.address, o);
49
+ const missing = [
50
+ ...new Set(files.flatMap((o) => (o.kind === KIND_ISSUE && o.parentRef && !parents.has(o.parentRef) ? [o.parentRef] : []))),
51
+ ];
52
+ if (missing.length) {
53
+ const read = await resolveForeignRoots(missing, query, cache).catch(() => []);
54
+ for (const parent of read)
55
+ if (parent.address)
56
+ parents.set(parent.address, parent);
57
+ }
58
+ return files.map((o) => {
59
+ const parent = o.kind === KIND_ISSUE && o.parentRef ? parents.get(o.parentRef) : undefined;
60
+ return {
61
+ id: o.address,
62
+ uri: fileReference(o.address),
63
+ type: typeOf(o.kind),
64
+ kind: o.kind,
65
+ title: o.slots.title.value,
66
+ caption: parent?.slots.title?.value ?? '',
67
+ tier,
68
+ ...(isClosedStatus(o.slots.status) ? { closed: true } : {}),
69
+ ...(o.archived || parent?.archived ? { archived: true } : {}),
70
+ ...(at?.has(o.address) ? { at: at.get(o.address) } : {}),
71
+ };
72
+ });
73
+ }
74
+ const tagOf = (event, name) => event.tags.find((t) => t[0] === name)?.[1];
75
+ /**
76
+ * The files whose **current** title holds `text`, as the search tier.
77
+ *
78
+ * The relay indexes a root's `title` and a rename's `value` (relay ticket
79
+ * 6fea004e); neither is the current title on its own — a root keeps the name
80
+ * it was created with, and a rename found by an old word may since have been
81
+ * renamed again. So a hit is only an address: each is read back as its root
82
+ * and changes, folded through its app's manifest, and kept only when what it
83
+ * is called now matches what was typed.
84
+ *
85
+ * Roots and renames are asked for separately, so a burst of renames cannot
86
+ * crowd every root out of the answer, and with buzz's prefix mode, so the word
87
+ * being typed matches before it is finished. A relay that indexes none of these
88
+ * kinds answers nothing, and so does this. A failed read rejects, for
89
+ * `referenceSearch` to answer no hits for a while.
90
+ */
91
+ export async function searchFileReferences(text, query, { limit = 32, ...options } = {}) {
92
+ const wanted = text.trim();
93
+ if (!wanted)
94
+ return [];
95
+ const asked = { search: wanted, search_mode: 'prefix', limit };
96
+ const hits = await query([
97
+ { kinds: Object.keys(REFERENCE_FILE_TYPES).map(Number), ...asked },
98
+ { kinds: [KIND_CHANGE], ...asked },
99
+ ]);
100
+ const at = new Map();
101
+ for (const hit of hits) {
102
+ const address = hit.kind === KIND_CHANGE
103
+ ? tagOf(hit, 'field') === 'title'
104
+ ? tagOf(hit, 'a')
105
+ : undefined
106
+ : typeOf(hit.kind) && `${hit.kind}:${hit.pubkey}:${tagOf(hit, 'd') ?? ''}`;
107
+ if (!address || !typeOf(Number(address.split(':')[0])))
108
+ continue;
109
+ at.set(address, Math.max(at.get(address) ?? 0, hit.created_at));
110
+ }
111
+ if (at.size === 0)
112
+ return [];
113
+ const objects = await resolveForeignRoots([...at.keys()], query, options.cache);
114
+ const matching = objects.filter((o) => o.slots.title && referenceMatch(o.slots.title.value, wanted) > 0);
115
+ return fileCandidates(matching, FILE_TIER.search, query, { ...options, at });
116
+ }
117
+ //# sourceMappingURL=references.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"references.js","sourceRoot":"","sources":["../src/references.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.45.0",
3
+ "version": "0.46.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",
@@ -47,11 +47,11 @@
47
47
  "prepublishOnly": "npm run build"
48
48
  },
49
49
  "peerDependencies": {
50
- "@estiva-app/conversation": ">=0.1.0",
50
+ "@estiva-app/conversation": ">=0.5.0",
51
51
  "@estiva-app/protocol": ">=0.24.0"
52
52
  },
53
53
  "devDependencies": {
54
- "@estiva-app/conversation": ">=0.1.0",
54
+ "@estiva-app/conversation": ">=0.5.0",
55
55
  "@estiva-app/protocol": ">=0.24.0",
56
56
  "typescript": "~5.9.3"
57
57
  }
package/src/index.ts CHANGED
@@ -29,6 +29,7 @@ export {
29
29
  resolveActingManifest,
30
30
  resolveForeignObject,
31
31
  resolveForeignObjects,
32
+ resolveForeignRoots,
32
33
  projectEvents,
33
34
  resolveParents,
34
35
  resolveForeignEvent,
@@ -38,6 +39,7 @@ export {
38
39
  topLevelFolders,
39
40
  ARCHIVED_FIELD,
40
41
  isArchived,
42
+ isClosedStatus,
41
43
  archiveImpact,
42
44
  type Archive,
43
45
  type ArchiveImpact,
@@ -103,6 +105,18 @@ export {
103
105
  */
104
106
  export { nestingOf, type Nestable, type Nesting } from './nesting.js'
105
107
 
108
+ /**
109
+ * The files `[` offers (PEE-21): resolved objects as rows, and typed text as
110
+ * the search tier, both folded to the current title. conversation ranks them.
111
+ */
112
+ export {
113
+ fileCandidates,
114
+ REFERENCE_FILE_TYPES,
115
+ searchFileReferences,
116
+ type FileCandidatesOptions,
117
+ type SearchFileReferencesOptions,
118
+ } from './references.js'
119
+
106
120
  /**
107
121
  * Folder writes as unsigned events in publish order — create, rename, place,
108
122
  * unlist, move. Each takes `hasState` from the caller, because a `kind:1852`
package/src/projection.ts CHANGED
@@ -3243,6 +3243,60 @@ export function projectEvents(
3243
3243
  })
3244
3244
  }
3245
3245
 
3246
+ /**
3247
+ * The objects at a set of addresses, as their roots and changes alone draw
3248
+ * them — PEE-21.
3249
+ *
3250
+ * For a reader that needs what a file *is* now (its folded title, status,
3251
+ * parent, own archive) and not what is said about it: {@link projectEvents}
3252
+ * over each address's root and change filters — the same two
3253
+ * {@link resolveForeignObjects} sends — without the comments, children and
3254
+ * people that make up most of that call's bytes. `[` reads a search answer's
3255
+ * hits through this on every pause in typing.
3256
+ *
3257
+ * An address whose root the reader is not handed is simply absent, so a file
3258
+ * in a Folder they cannot read never comes back. A failed read rejects.
3259
+ */
3260
+ export async function resolveForeignRoots(
3261
+ references: readonly string[],
3262
+ query: QueryFn,
3263
+ cache?: ProjectionCache,
3264
+ ): Promise<ForeignObject[]> {
3265
+ const pointers = new Map<string, AddressPointer>()
3266
+ for (const reference of references) {
3267
+ const pointer = addressPointerOf(reference)
3268
+ if (pointer) pointers.set(`${pointer.kind}:${pointer.pubkey}:${pointer.identifier}`, pointer)
3269
+ }
3270
+ if (pointers.size === 0) return []
3271
+
3272
+ const manifests = new Map<string, ResolvedManifest>()
3273
+ const byApp = new Map<string, AddressPointer>()
3274
+ for (const pointer of pointers.values()) byApp.set(manifestKeyOf(pointer), pointer)
3275
+ await Promise.all(
3276
+ [...byApp].map(async ([key, pointer]) => {
3277
+ const resolved = await resolveManifest(pointer, query, cache)
3278
+ if (resolved) manifests.set(key, resolved)
3279
+ }),
3280
+ )
3281
+
3282
+ const filters: Record<string, unknown>[] = []
3283
+ for (const [address, pointer] of pointers) {
3284
+ const resolved = manifests.get(manifestKeyOf(pointer))
3285
+ if (!resolved?.manifest.projections?.[String(pointer.kind)]) continue
3286
+ // A manifest without `records` folds by a placeholder kind 0, never sent.
3287
+ const changeKinds = new Set(
3288
+ [foldRuleOf(resolved.manifest).changeKind, archiveRuleOf(resolved.manifest).changeKind].filter((k) => k !== 0),
3289
+ )
3290
+ filters.push(
3291
+ { kinds: [pointer.kind], authors: [pointer.pubkey], '#d': [pointer.identifier], limit: 1 },
3292
+ { kinds: [...changeKinds], '#a': [address], limit: 500 },
3293
+ )
3294
+ }
3295
+ if (filters.length === 0) return []
3296
+ const events = await queryChunked(filters, query)
3297
+ return projectEvents(events, (pointer) => manifests.get(manifestKeyOf(pointer)))
3298
+ }
3299
+
3246
3300
  /**
3247
3301
  * The parent each file sits under, and nothing else — FOL-50.
3248
3302
  *
@@ -4236,6 +4290,17 @@ function isDone(stage: Stage | undefined, raw: string | undefined, label: string
4236
4290
  return isDoneStatusByLabel(raw, label)
4237
4291
  }
4238
4292
 
4293
+ /**
4294
+ * Is a resolved `status` slot finished work — done or dropped — by its words?
4295
+ *
4296
+ * For a consumer holding only the object, not its manifest: the declared stage
4297
+ * is not on a {@link ResolvedSlot}, so this is the word-list fallback alone.
4298
+ * `[` uses it to put a closed issue after an open one (PEE-21).
4299
+ */
4300
+ export function isClosedStatus(slot: ResolvedSlot | undefined): boolean {
4301
+ return slot !== undefined && isDoneStatusByLabel(slot.value, slot.label)
4302
+ }
4303
+
4239
4304
  function isOpen(stage: Stage | undefined, raw: string | undefined, label: string | undefined) {
4240
4305
  if (stage) return stage === 'open' || stage === 'started'
4241
4306
  return isOpenStatusByLabel(raw, label)
@@ -0,0 +1,154 @@
1
+ /**
2
+ * The files `[` offers, as @estiva-app/conversation ranks them (PEE-21).
3
+ *
4
+ * conversation's `rankReferences` orders candidates and knows nothing of a
5
+ * relay; this is the half that turns what a relay holds into candidates — a
6
+ * resolved object into a row, and typed text into the search tier — so Peek
7
+ * and Ship draw the same rows from the same reads.
8
+ *
9
+ * A row is the type word and the current title; an issue is captioned with its
10
+ * project's title, and nothing names a Folder (Miky, 2026-10-03). Only what the
11
+ * reader resolved is offered: an object the relay did not hand back to them is
12
+ * never a row, so nothing unreadable is offered. An archived file is offered
13
+ * at the lowest priority, and so is an issue in an archived project.
14
+ */
15
+ import {
16
+ FILE_TIER,
17
+ fileReference,
18
+ KIND_CHANGE,
19
+ referenceMatch,
20
+ type ReferenceCandidate,
21
+ type ReferenceType,
22
+ } from '@estiva-app/conversation'
23
+ import {
24
+ isClosedStatus,
25
+ KIND_BARE_FILE,
26
+ resolveForeignRoots,
27
+ type ForeignObject,
28
+ type ProjectionCache,
29
+ type QueryFn,
30
+ } from './projection.js'
31
+
32
+ const KIND_PROJECT = 30850
33
+ const KIND_ISSUE = 30851
34
+
35
+ /** The kinds `[` offers as files, and the type word each draws as. */
36
+ export const REFERENCE_FILE_TYPES: Readonly<Record<number, ReferenceType>> = {
37
+ [KIND_PROJECT]: 'project',
38
+ [KIND_ISSUE]: 'issue',
39
+ [KIND_BARE_FILE]: 'topic',
40
+ }
41
+
42
+ const typeOf = (kind: number): ReferenceType | undefined => REFERENCE_FILE_TYPES[kind]
43
+
44
+ type Addressed = ForeignObject & { address: string }
45
+
46
+ /** An object `[` may offer: a file kind it knows, resolved, with a title. */
47
+ const offerable = (object: ForeignObject | null | undefined): object is Addressed =>
48
+ !!object &&
49
+ !!object.address &&
50
+ !object.unreachable &&
51
+ typeOf(object.kind) !== undefined &&
52
+ !!object.slots.title?.value.trim()
53
+
54
+ export interface FileCandidatesOptions {
55
+ cache?: ProjectionCache
56
+ /** When each address was last written or read, in seconds — newer first within a tier. */
57
+ at?: ReadonlyMap<string, number>
58
+ }
59
+
60
+ /**
61
+ * Rows for resolved files, all in one tier.
62
+ *
63
+ * An issue's caption is its project's title, and an issue in an archived
64
+ * project is archived with it: the project is taken from `objects` when it is
65
+ * among them, and otherwise read in one more batch for every missing project
66
+ * at once (roots and changes only). A project that cannot be read leaves the
67
+ * caption empty rather than dropping the issue. Objects that are not
68
+ * offerable — unreachable, untitled, or of a kind `[` does not offer — are
69
+ * left out.
70
+ */
71
+ export async function fileCandidates(
72
+ objects: readonly (ForeignObject | null | undefined)[],
73
+ tier: number,
74
+ query: QueryFn,
75
+ { cache, at }: FileCandidatesOptions = {},
76
+ ): Promise<ReferenceCandidate[]> {
77
+ const files = objects.filter(offerable)
78
+ const parents = new Map<string, ForeignObject>()
79
+ for (const o of objects) if (o?.address && !o.unreachable) parents.set(o.address, o)
80
+ const missing = [
81
+ ...new Set(files.flatMap((o) => (o.kind === KIND_ISSUE && o.parentRef && !parents.has(o.parentRef) ? [o.parentRef] : []))),
82
+ ]
83
+ if (missing.length) {
84
+ const read = await resolveForeignRoots(missing, query, cache).catch(() => [])
85
+ for (const parent of read) if (parent.address) parents.set(parent.address, parent)
86
+ }
87
+ return files.map((o) => {
88
+ const parent = o.kind === KIND_ISSUE && o.parentRef ? parents.get(o.parentRef) : undefined
89
+ return {
90
+ id: o.address,
91
+ uri: fileReference(o.address),
92
+ type: typeOf(o.kind)!,
93
+ kind: o.kind,
94
+ title: o.slots.title!.value,
95
+ caption: parent?.slots.title?.value ?? '',
96
+ tier,
97
+ ...(isClosedStatus(o.slots.status) ? { closed: true } : {}),
98
+ ...(o.archived || parent?.archived ? { archived: true } : {}),
99
+ ...(at?.has(o.address) ? { at: at.get(o.address) } : {}),
100
+ }
101
+ })
102
+ }
103
+
104
+ export interface SearchFileReferencesOptions extends Omit<FileCandidatesOptions, 'at'> {
105
+ /** How many roots, and separately how many renames, the relay is asked for. Default 32. */
106
+ limit?: number
107
+ }
108
+
109
+ const tagOf = (event: { tags: string[][] }, name: string) => event.tags.find((t) => t[0] === name)?.[1]
110
+
111
+ /**
112
+ * The files whose **current** title holds `text`, as the search tier.
113
+ *
114
+ * The relay indexes a root's `title` and a rename's `value` (relay ticket
115
+ * 6fea004e); neither is the current title on its own — a root keeps the name
116
+ * it was created with, and a rename found by an old word may since have been
117
+ * renamed again. So a hit is only an address: each is read back as its root
118
+ * and changes, folded through its app's manifest, and kept only when what it
119
+ * is called now matches what was typed.
120
+ *
121
+ * Roots and renames are asked for separately, so a burst of renames cannot
122
+ * crowd every root out of the answer, and with buzz's prefix mode, so the word
123
+ * being typed matches before it is finished. A relay that indexes none of these
124
+ * kinds answers nothing, and so does this. A failed read rejects, for
125
+ * `referenceSearch` to answer no hits for a while.
126
+ */
127
+ export async function searchFileReferences(
128
+ text: string,
129
+ query: QueryFn,
130
+ { limit = 32, ...options }: SearchFileReferencesOptions = {},
131
+ ): Promise<ReferenceCandidate[]> {
132
+ const wanted = text.trim()
133
+ if (!wanted) return []
134
+ const asked = { search: wanted, search_mode: 'prefix', limit }
135
+ const hits = await query([
136
+ { kinds: Object.keys(REFERENCE_FILE_TYPES).map(Number), ...asked },
137
+ { kinds: [KIND_CHANGE], ...asked },
138
+ ])
139
+ const at = new Map<string, number>()
140
+ for (const hit of hits) {
141
+ const address =
142
+ hit.kind === KIND_CHANGE
143
+ ? tagOf(hit, 'field') === 'title'
144
+ ? tagOf(hit, 'a')
145
+ : undefined
146
+ : typeOf(hit.kind) && `${hit.kind}:${hit.pubkey}:${tagOf(hit, 'd') ?? ''}`
147
+ if (!address || !typeOf(Number(address.split(':')[0]))) continue
148
+ at.set(address, Math.max(at.get(address) ?? 0, hit.created_at))
149
+ }
150
+ if (at.size === 0) return []
151
+ const objects = await resolveForeignRoots([...at.keys()], query, options.cache)
152
+ const matching = objects.filter((o) => o.slots.title && referenceMatch(o.slots.title.value, wanted) > 0)
153
+ return fileCandidates(matching, FILE_TIER.search, query, { ...options, at })
154
+ }