@estiva-app/interop 0.45.0 → 0.47.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.47.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/folders.ts CHANGED
@@ -1,13 +1,21 @@
1
1
  /**
2
- * Folder writes, planned — RFC 0.4 §4, FOL-4.
2
+ * Folder writes, planned — SPEC §3.3. Every app gets exactly these operations,
3
+ * and these planners are the reference implementation: an app that does not
4
+ * call them MUST produce the same events in the same order.
3
5
  *
4
- * Every change to a Folder is one or more events published in order, and which
5
- * events depends on one fact the relay will not check for you: **whether the
6
- * Folder has a `kind:30890` yet.** `handle_folder_command` computes the next
7
- * state from the existing one, and a Folder with no state has none — so any
8
- * `kind:1852` against it emits state listing only what that command named, and
9
- * everything filed in the Folder by `h` stops being listed on every surface
10
- * (peek#192). Nothing fails; the Folder just looks emptied.
6
+ * Every change to a Folder is one or more events published in order. Where a
7
+ * planner lists a file, it depends on one fact the relay will not check for
8
+ * you: **whether the Folder has a `kind:30890` yet.** `handle_folder_command`
9
+ * computes the next state from the existing one, and a group with no state has
10
+ * none — so any `kind:1852` against it emits state listing only what that
11
+ * command named, and everything filed there by `h` stops being listed on every
12
+ * surface (peek#192). Nothing fails; the group just looks emptied.
13
+ *
14
+ * A group with no state is not a Folder (SPEC §3), and §3.3's operations are
15
+ * not run on one. The `hasState: false` branches below are kept for §7.3's
16
+ * `listed` rule, which still applies to an object filed in such a group: a
17
+ * file placed or unlisted there is reached by containment and needs no
18
+ * command.
11
19
  *
12
20
  * That is why these are here rather than in each app. Peek learned it once per
13
21
  * writer — rename, start a topic, delete a file — and its move never learned it
@@ -27,31 +35,49 @@
27
35
  * assumes the earlier ones were accepted. What a refusal part-way through
28
36
  * *means* — "created but not listed", "added but still in the old one" — is
29
37
  * each app's to say, and the index of the refused event is enough to say it.
38
+ *
39
+ * ## A command never carries a name
40
+ *
41
+ * A Folder's title is the `name` of its `kind:39000` and only that (§3.2). The
42
+ * relay lets only the channel's owners and admins change that, while any
43
+ * member may send a `kind:1852` — so a name on a command would let anyone
44
+ * retitle the Folder for every reader that believed it.
30
45
  */
31
46
  import {
32
47
  buildCreateChannel,
48
+ buildDeleteChannel,
33
49
  buildEditChannelMetadata,
34
50
  buildFolderCommand,
35
51
  type ChannelVisibility,
36
52
  type UnsignedEvent,
37
53
  } from '@estiva-app/protocol'
38
54
 
39
- /** A Folder as a write needs it: which one, and whether the relay holds state for it. */
55
+ /** A Folder as a write needs it: which one, and what a read said about it. */
40
56
  export interface FolderRef {
41
57
  id: string
42
58
  /** `FolderSummary.hasState` / `FolderContents.hasState`, from a read — never a guess. */
43
59
  hasState: boolean
60
+ /**
61
+ * `FolderSummary.private`: the Folder's relay-signed `kind:39000` carries
62
+ * `["private"]`. Only a move *into* the Folder reads it.
63
+ */
64
+ private?: boolean
44
65
  }
45
66
 
46
67
  /**
47
- * Create a Folder: `[kind:9007, kind:1852 add + name]`.
68
+ * Create a Folder: `[kind:9007 + name, kind:1852 add]`.
48
69
  *
49
- * The channel first, because a Folder *is* one (RFC 0.4 §4.1). Then a command
50
- * naming it and listing nothing, so the Folder **has state from birth** — a
51
- * listing that shows only Folders with state would otherwise never show it,
52
- * and a stateless Folder is indistinguishable from a bare channel. Safe here
70
+ * The channel first, because a Folder *is* one (§3). Then a command listing
71
+ * nothing, so the Folder **has state from birth** — a group without a
72
+ * `kind:30890` is not a Folder, and a listing would never show it. Safe here
53
73
  * and nowhere else without `hasState`: the channel was created by the first
54
- * event, so nothing is filed in it to hide.
74
+ * event, so nothing is filed in it to hide. The relay emits state for an `add`
75
+ * with no addresses and no name.
76
+ *
77
+ * `folder` MUST be a uuid nobody has used. The relay answers a `kind:9007` for
78
+ * an existing channel with `duplicate:`, which the bridge reports as accepted,
79
+ * so a reused id would send the `add` to a group that may hold files and no
80
+ * state — and empty it on every surface.
55
81
  */
56
82
  export function planCreateFolder(
57
83
  pubkey: string,
@@ -64,37 +90,52 @@ export function planCreateFolder(
64
90
  name: args.name,
65
91
  ...(args.visibility ? { visibility: args.visibility } : {}),
66
92
  }),
67
- buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', name: args.name }),
93
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add' }),
68
94
  ]
69
95
  }
70
96
 
71
97
  /**
72
- * Rename a Folder: `[kind:9002, kind:1852 add + name if it has state]`.
98
+ * Rename a Folder: `[kind:9002]`, and nothing else.
73
99
  *
74
- * **A Folder's name has two homes** and the state's shadows the channel's, so
75
- * writing only the channel leaves the old name wherever the state is read. The
76
- * command is `add` with no addresses — the contents are kept and only the name
77
- * changes; `set` would empty it and there is no `rename` op. With no state
78
- * there is only the channel to rename, and a command would empty the Folder.
100
+ * The title is the channel's name (§3.2), so the channel is the only home to
101
+ * write. The relay refuses it to anybody but the channel's owners and admins.
102
+ * A name left on an older state by a command is never shown.
79
103
  */
80
104
  export function planRenameFolder(
81
105
  pubkey: string,
82
106
  createdAtMs: number,
83
- args: { folder: string; name: string; hasState: boolean },
107
+ args: { folder: string; name: string },
84
108
  ): UnsignedEvent[] {
85
- const rename = buildEditChannelMetadata(pubkey, createdAtMs, { channelUuid: args.folder, name: args.name })
86
- if (!args.hasState) return [rename]
87
- return [rename, buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', name: args.name })]
109
+ return [buildEditChannelMetadata(pubkey, createdAtMs, { channelUuid: args.folder, name: args.name })]
110
+ }
111
+
112
+ /**
113
+ * Delete a Folder: `[kind:9008]`.
114
+ *
115
+ * **For an empty Folder.** The relay refuses while the Folder holds a file —
116
+ * a `30840`, `30850` or `30851` under its `h`, or any address its listing
117
+ * names — with a reason naming the count ("folder holds N file(s) … remove
118
+ * them first"), and a consumer shows that reason. A file moved out keeps its
119
+ * `h`, so a Folder whose listing looks empty can still refuse.
120
+ *
121
+ * An accepted delete hides **every** event under the `h`, its conversation
122
+ * included, for good. Archive ({@link planArchiveFolder}) is the reversible way
123
+ * to put a Folder away. Folders never nest, so there is no container to unlist
124
+ * it from.
125
+ */
126
+ export function planDeleteFolder(pubkey: string, createdAtMs: number, args: { folder: string }): UnsignedEvent[] {
127
+ if (!args.folder) throw new Error('a Folder delete names the Folder')
128
+ return [buildDeleteChannel(pubkey, createdAtMs, { channelUuid: args.folder })]
88
129
  }
89
130
 
90
131
  /**
91
132
  * List a file that was just published into a Folder: `[kind:1852 add]` if the
92
133
  * Folder has state, otherwise nothing.
93
134
  *
94
- * A Folder read by containment lists the file the moment its `h` is stored. A
95
- * Folder with state lists only what its state names, so it needs the `add`.
96
- * Publish the file first: a refused `add` then leaves a file that exists and
97
- * is reachable, rather than a listing that points at nothing.
135
+ * A Folder with state lists only what its state names, so it needs the `add`.
136
+ * A group with no state lists the file by containment the moment its `h` is
137
+ * stored (§7.3). Publish the file first: a refused `add` then leaves a file
138
+ * that exists and is reachable, rather than a listing that points at nothing.
98
139
  */
99
140
  export function planPlaceFile(
100
141
  pubkey: string,
@@ -110,7 +151,7 @@ export function planPlaceFile(
110
151
  * the Folder has state, otherwise nothing.
111
152
  *
112
153
  * {@link planPlaceFile} in reverse. A Folder with state lists what it names,
113
- * deleted or not, so the row would stay pointing at nothing; a Folder read by
154
+ * deleted or not, so the row would stay pointing at nothing; a group read by
114
155
  * containment stops listing the file once the relay hides it. Delete first: a
115
156
  * refused `remove` then leaves a stale row, where the other order would unlist
116
157
  * a file the relay kept.
@@ -125,47 +166,19 @@ export function planUnlistFile(
125
166
  }
126
167
 
127
168
  /**
128
- * Why a move was refused. The source is checked first: no choice of target
129
- * fixes it, so a consumer can stop offering Move for that file at all.
130
- */
131
- export type MoveRefusal = 'source-has-no-state' | 'target-has-no-state'
132
-
133
- export type MovePlan = { ok: true; events: UnsignedEvent[] } | { ok: false; reason: MoveRefusal }
134
-
135
- /**
136
- * Move a file between Folders: `[kind:1852 add to target, kind:1852 remove from source]`.
137
- *
138
- * **Add first.** There is no atomic move — state is per Folder — so something
139
- * can fail between the two. After the add, a failure leaves the file in both
140
- * Folders: visible, obviously wrong, fixed by moving again. Removing first and
141
- * failing would leave it in neither, which looks like a file that never was.
142
- *
143
- * **Refused unless both Folders have state.** An `add` to a Folder with none
144
- * emits state listing only the moved file, and everything already filed in it
145
- * disappears; a `remove` from one emits state listing nothing, and the whole
146
- * source disappears. Writing a complete state first is not offered here: what
147
- * a stateless Folder holds is whatever its `h` implies to *this* reader, and a
148
- * planner that enumerated it would be deciding on everyone's behalf.
149
- *
150
- * A move to the same Folder plans nothing.
151
- */
152
- /**
153
- * Archive a Folder, or restore it: `[kind:1851 archived]` — FOL-46.
169
+ * Archive a Folder, or restore it: `[kind:1851 archived]` — FOL-46, SPEC §3.3.
154
170
  *
155
171
  * **Not a Folder command.** A Folder is archived the way any file is: a change
156
172
  * setting `archived` on its address — its channel's, `FolderSummary.channel` —
157
173
  * to `'true'`, or to an empty value to restore it. Its state, its contents and
158
174
  * its channel are untouched, which is what makes it reversible: a `kind:9008`
159
- * hides everything under the Folder's `h` for good (FOL-9), and a `kind:1852`
160
- * would unlist the Folder from somewhere a person would have to remember.
175
+ * hides everything under the Folder's `h` for good, and a `kind:1852` would
176
+ * unlist a file from somewhere a person would have to remember.
161
177
  *
162
- * **Where it is published decides who reads it**, because a change is read by
163
- * the members of the channel it is in. `into` is the Folder that lists this
164
- * one (`FolderSummary.listedIn`), when there is one: everyone reading that
165
- * Folder then reads the archive, and a private sub-Folder is hidden from its
166
- * team for the team's members too, not only for its own. A top-level Folder has
167
- * no container, so it defaults to the Folder itself — anyone who may write
168
- * there, a member and not only an admin, may archive it.
178
+ * **Always in the Folder's own `h`**, and readers count it only from an owner
179
+ * or admin on the Folder's `kind:39001` (§3.2) — the people who may rename it.
180
+ * So offer Archive only to them (`FolderSummary.admins`): from anybody else the
181
+ * relay accepts the event and every reader ignores it.
169
182
  *
170
183
  * `resolution` is what the person archiving said about it, carried as the
171
184
  * change's `content`; readers show it first when the archived Folder is
@@ -174,7 +187,7 @@ export type MovePlan = { ok: true; events: UnsignedEvent[] } | { ok: false; reas
174
187
  export function planArchiveFolder(
175
188
  pubkey: string,
176
189
  createdAtMs: number,
177
- args: { folder: string; channel: string; archived: boolean; resolution?: string; into?: string },
190
+ args: { folder: string; channel: string; archived: boolean; resolution?: string },
178
191
  ): UnsignedEvent[] {
179
192
  return [
180
193
  {
@@ -187,7 +200,7 @@ export function planArchiveFolder(
187
200
  ['a', args.channel],
188
201
  ['field', 'archived'],
189
202
  ['value', args.archived ? 'true' : ''],
190
- ['h', args.into ?? args.folder],
203
+ ['h', args.folder],
191
204
  ['ts', String(createdAtMs)],
192
205
  ],
193
206
  content: args.archived ? (args.resolution ?? '') : '',
@@ -195,19 +208,131 @@ export function planArchiveFolder(
195
208
  ]
196
209
  }
197
210
 
211
+ /**
212
+ * A file as a move needs it. A `ForeignObject` from `resolveFolderContents` is
213
+ * one: `ref` is its identity, `parentRef` the file it is drawn beneath, and
214
+ * `folder` the `h` of its root — absent for a root placed by `buzz-channel`.
215
+ */
216
+ export interface MovableFile {
217
+ ref: string
218
+ address?: string
219
+ parentRef?: string
220
+ folder?: string
221
+ }
222
+
223
+ /**
224
+ * Why a move was refused. The source is checked first: no choice of target
225
+ * fixes it, so a consumer can stop offering Move for that file at all.
226
+ *
227
+ * `target-is-private`: the target's `kind:39000` is private and a moved file's
228
+ * `h` names any other channel, or none. A listing never changes who can read a
229
+ * file (§3.1), so the file would look private in the target and not be.
230
+ */
231
+ export type MoveRefusal = 'source-has-no-state' | 'target-has-no-state' | 'target-is-private'
232
+
233
+ export type MovePlan =
234
+ | {
235
+ ok: true
236
+ events: UnsignedEvent[]
237
+ /** The addresses the plan moves — the file, when the source lists it, and every file listed beneath it. */
238
+ moved: string[]
239
+ }
240
+ | { ok: false; reason: MoveRefusal }
241
+
242
+ /**
243
+ * The files `listing` draws beneath `file`, at any depth, in listing order.
244
+ *
245
+ * Walked by `parentRef` — the bare file's folded `parent` (§6.7) and every
246
+ * other kind's declared children (§7.2) alike. A file on a cycle is drawn at
247
+ * the top (§6.7), so nothing is beneath it through the cycle: two files each
248
+ * moved under the other are neither's sub-file.
249
+ */
250
+ export function listedBeneath<T extends MovableFile>(listing: readonly T[], file: Pick<MovableFile, 'ref' | 'parentRef'>): T[] {
251
+ const byRef = new Map(listing.map((candidate) => [candidate.ref, candidate]))
252
+ const cycles = new Map<string, boolean>()
253
+ const onCycle = (ref: string) => {
254
+ let found = cycles.get(ref)
255
+ if (found !== undefined) return found
256
+ found = false
257
+ const seen = new Set<string>()
258
+ for (let at = byRef.get(ref)?.parentRef; at && !seen.has(at); at = byRef.get(at)?.parentRef) {
259
+ if (at === ref) {
260
+ found = true
261
+ break
262
+ }
263
+ seen.add(at)
264
+ }
265
+ cycles.set(ref, found)
266
+ return found
267
+ }
268
+ // Up from `candidate` until `file`; a file on a cycle is at the top, so the walk ends there.
269
+ const isBeneath = (candidate: MovableFile) => {
270
+ if (onCycle(candidate.ref)) return false
271
+ const seen = new Set<string>()
272
+ for (let at = candidate.parentRef; at && !seen.has(at); at = byRef.get(at)?.parentRef) {
273
+ if (at === file.ref) return true
274
+ if (onCycle(at)) return false
275
+ seen.add(at)
276
+ }
277
+ return false
278
+ }
279
+ return listing.filter((candidate) => candidate.ref !== file.ref && isBeneath(candidate))
280
+ }
281
+
282
+ /**
283
+ * Move a file to another Folder, with everything listed beneath it:
284
+ * `[kind:1852 add to target, kind:1852 remove from source]` — SPEC §3.3.
285
+ *
286
+ * **One command each way, naming the whole set.** `listing` is the source
287
+ * Folder's files (`FolderContents.files`); the file moves with every file
288
+ * listed beneath it ({@link listedBeneath}), so a subtree moves whole. The
289
+ * relay applies every address on a command in one state write, so a failure
290
+ * can never split the subtree between the two Folders. The file itself is
291
+ * moved only when the source lists it — a Ship issue is listed by no Folder,
292
+ * its project is. The file's `h` does not change.
293
+ *
294
+ * `listing` is required, and `null` says "nothing can be listed beneath this
295
+ * file", making the file the whole set. A move that silently left its
296
+ * sub-files behind is the bug this planner exists to end, so omitting the
297
+ * listing is a type error rather than a quiet single-file move.
298
+ *
299
+ * **Add first.** There is no atomic move — state is per Folder — so something
300
+ * can fail between the two. After the add, a failure leaves the set in both
301
+ * Folders: visible, obviously wrong, fixed by moving again. Removing first and
302
+ * failing would leave it in neither, which looks like files that never were.
303
+ *
304
+ * **Refused unless both Folders have state.** An `add` to a Folder with none
305
+ * emits state listing only the moved files, and everything already filed in
306
+ * it disappears; a `remove` from one emits state listing nothing, and the
307
+ * whole source disappears.
308
+ *
309
+ * **Refused into a private Folder** when any moved file's `h` is another
310
+ * channel or absent (`target-is-private`, §3.1).
311
+ *
312
+ * A move to the same Folder, or of a set the source does not list, plans nothing.
313
+ */
198
314
  export function planMoveFile(
199
315
  pubkey: string,
200
316
  createdAtMs: number,
201
- args: { address: string; from: FolderRef; to: FolderRef },
317
+ args: { file: MovableFile; from: FolderRef; to: FolderRef; listing: readonly MovableFile[] | null },
202
318
  ): MovePlan {
203
- if (args.from.id === args.to.id) return { ok: true, events: [] }
319
+ if (args.from.id === args.to.id) return { ok: true, events: [], moved: [] }
204
320
  if (!args.from.hasState) return { ok: false, reason: 'source-has-no-state' }
205
321
  if (!args.to.hasState) return { ok: false, reason: 'target-has-no-state' }
322
+ const { file, listing } = args
323
+ // The listing's own entry when it has one, so the walk goes by the refs the listing's children name.
324
+ const listed = listing?.find((candidate) => candidate.ref === file.ref || (!!file.address && candidate.address === file.address))
325
+ const set = listing ? [...(listed ? [listed] : []), ...listedBeneath(listing, listed ?? file)] : [file]
326
+ const moving = set.filter((candidate) => candidate.address)
327
+ if (args.to.private && moving.some((candidate) => candidate.folder !== args.to.id)) return { ok: false, reason: 'target-is-private' }
328
+ const moved = [...new Set(moving.map((candidate) => candidate.address!))]
329
+ if (!moved.length) return { ok: true, events: [], moved }
206
330
  return {
207
331
  ok: true,
208
332
  events: [
209
- buildFolderCommand(pubkey, createdAtMs, { folder: args.to.id, op: 'add', addresses: [args.address] }),
210
- buildFolderCommand(pubkey, createdAtMs, { folder: args.from.id, op: 'remove', addresses: [args.address] }),
333
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.to.id, op: 'add', addresses: moved }),
334
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.from.id, op: 'remove', addresses: moved }),
211
335
  ],
336
+ moved,
212
337
  }
213
338
  }
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,
@@ -98,24 +100,40 @@ export {
98
100
  } from './projection.js'
99
101
 
100
102
  /**
101
- * SPEC §6.7's nesting, drawn from one team listing: roots, children,
103
+ * SPEC §6.7's nesting, drawn from one Folder listing: roots, children,
102
104
  * breadcrumbs and move targets, with cycles cut. No requests.
103
105
  */
104
106
  export { nestingOf, type Nestable, type Nesting } from './nesting.js'
105
107
 
106
108
  /**
107
- * Folder writes as unsigned events in publish order — create, rename, place,
108
- * unlist, move. Each takes `hasState` from the caller, because a `kind:1852`
109
- * against a Folder with no state empties it. No signing, no requests.
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
+
120
+ /**
121
+ * SPEC §3.3's Folder operations as unsigned events in publish order — create,
122
+ * rename, archive, delete, place, unlist, move. Where a `kind:1852` is sent,
123
+ * `hasState` comes from the caller, because one against a group with no state
124
+ * empties it. No signing, no requests.
110
125
  */
111
126
  export {
112
127
  planCreateFolder,
113
128
  planRenameFolder,
129
+ planDeleteFolder,
114
130
  planPlaceFile,
115
131
  planUnlistFile,
116
132
  planMoveFile,
117
133
  planArchiveFolder,
134
+ listedBeneath,
118
135
  type FolderRef,
136
+ type MovableFile,
119
137
  type MovePlan,
120
138
  type MoveRefusal,
121
139
  } from './folders.js'