@minca/core 0.1.16 → 0.1.18

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.
Files changed (125) hide show
  1. package/README.md +10 -9
  2. package/dist/elements/auth-styles.d.ts +1 -1
  3. package/dist/elements/auth-styles.d.ts.map +1 -1
  4. package/dist/elements/auth-styles.js +14 -5
  5. package/dist/elements/auth-styles.js.map +1 -1
  6. package/dist/elements/minca-auth.d.ts.map +1 -1
  7. package/dist/elements/minca-auth.js +18 -15
  8. package/dist/elements/minca-auth.js.map +1 -1
  9. package/dist/files/space-files.d.ts +2 -2
  10. package/dist/files/space-files.d.ts.map +1 -1
  11. package/dist/files/space-files.js +7 -5
  12. package/dist/files/space-files.js.map +1 -1
  13. package/dist/inbox/names.d.ts +1 -1
  14. package/dist/inbox/names.js +1 -1
  15. package/dist/index.d.ts +2 -0
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +2 -0
  18. package/dist/index.js.map +1 -1
  19. package/dist/network/ws-transport.d.ts.map +1 -1
  20. package/dist/network/ws-transport.js +3 -0
  21. package/dist/network/ws-transport.js.map +1 -1
  22. package/dist/node/actions.d.ts +5 -0
  23. package/dist/node/actions.d.ts.map +1 -1
  24. package/dist/node/actions.js +39 -20
  25. package/dist/node/actions.js.map +1 -1
  26. package/dist/node/api.d.ts +2 -0
  27. package/dist/node/api.d.ts.map +1 -1
  28. package/dist/node/api.js +2 -0
  29. package/dist/node/api.js.map +1 -1
  30. package/dist/node/carrier.js +1 -1
  31. package/dist/node/carrier.js.map +1 -1
  32. package/dist/node/node-carriers.d.ts.map +1 -1
  33. package/dist/node/node-carriers.js +6 -1
  34. package/dist/node/node-carriers.js.map +1 -1
  35. package/dist/node/node-contacts.d.ts.map +1 -1
  36. package/dist/node/node-contacts.js +1 -0
  37. package/dist/node/node-contacts.js.map +1 -1
  38. package/dist/node/node-hosting.d.ts.map +1 -1
  39. package/dist/node/node-hosting.js +11 -4
  40. package/dist/node/node-hosting.js.map +1 -1
  41. package/dist/node/node-records.d.ts.map +1 -1
  42. package/dist/node/node-records.js +6 -1
  43. package/dist/node/node-records.js.map +1 -1
  44. package/dist/node/node.d.ts.map +1 -1
  45. package/dist/node/node.js +14 -1
  46. package/dist/node/node.js.map +1 -1
  47. package/dist/node/remote.d.ts.map +1 -1
  48. package/dist/node/remote.js +7 -1
  49. package/dist/node/remote.js.map +1 -1
  50. package/dist/node/space-holding.d.ts +7 -3
  51. package/dist/node/space-holding.d.ts.map +1 -1
  52. package/dist/node/space-holding.js +90 -18
  53. package/dist/node/space-holding.js.map +1 -1
  54. package/dist/node/space-peers.d.ts.map +1 -1
  55. package/dist/node/space-peers.js +58 -24
  56. package/dist/node/space-peers.js.map +1 -1
  57. package/dist/node/space-runtime.d.ts +11 -3
  58. package/dist/node/space-runtime.d.ts.map +1 -1
  59. package/dist/node/space-runtime.js +22 -1
  60. package/dist/node/space-runtime.js.map +1 -1
  61. package/dist/node/space-writing.d.ts +2 -0
  62. package/dist/node/space-writing.d.ts.map +1 -1
  63. package/dist/node/space-writing.js +2 -0
  64. package/dist/node/space-writing.js.map +1 -1
  65. package/dist/node/types.d.ts +130 -36
  66. package/dist/node/types.d.ts.map +1 -1
  67. package/dist/query/types.d.ts +1 -0
  68. package/dist/query/types.d.ts.map +1 -1
  69. package/dist/query/types.js.map +1 -1
  70. package/dist/records/contract-builder.d.ts +22 -6
  71. package/dist/records/contract-builder.d.ts.map +1 -1
  72. package/dist/records/contract-builder.js.map +1 -1
  73. package/dist/schemas/automations.d.ts +6 -2
  74. package/dist/schemas/automations.d.ts.map +1 -1
  75. package/dist/schemas/automations.js.map +1 -1
  76. package/dist/schemas/connectors.d.ts +4 -3
  77. package/dist/schemas/connectors.d.ts.map +1 -1
  78. package/dist/schemas/connectors.js +4 -3
  79. package/dist/schemas/connectors.js.map +1 -1
  80. package/dist/schemas/library/media.js +1 -1
  81. package/dist/schemas/library/media.js.map +1 -1
  82. package/dist/schemas/library/social.d.ts +258 -0
  83. package/dist/schemas/library/social.d.ts.map +1 -1
  84. package/dist/schemas/library/social.js +28 -1
  85. package/dist/schemas/library/social.js.map +1 -1
  86. package/dist/session/auth.d.ts +7 -3
  87. package/dist/session/auth.d.ts.map +1 -1
  88. package/dist/session/auth.js.map +1 -1
  89. package/dist/session/hosting.d.ts.map +1 -1
  90. package/dist/session/hosting.js +8 -2
  91. package/dist/session/hosting.js.map +1 -1
  92. package/dist/space/presets.d.ts +2 -2
  93. package/dist/space/presets.d.ts.map +1 -1
  94. package/dist/space/presets.js +3 -2
  95. package/dist/space/presets.js.map +1 -1
  96. package/dist/storage/blob-store.d.ts +3 -0
  97. package/dist/storage/blob-store.d.ts.map +1 -1
  98. package/dist/types.d.ts +11 -2
  99. package/dist/types.d.ts.map +1 -1
  100. package/dist/types.js.map +1 -1
  101. package/docs/README.md +86 -93
  102. package/docs/actions.md +212 -144
  103. package/docs/agents.md +198 -155
  104. package/docs/automations.md +296 -204
  105. package/docs/blueprints-and-guides.md +405 -295
  106. package/docs/bots.md +208 -134
  107. package/docs/building-an-app.md +74 -163
  108. package/docs/collections.md +248 -328
  109. package/docs/computed.md +112 -89
  110. package/docs/contacts.md +151 -112
  111. package/docs/contracts.md +299 -120
  112. package/docs/direct-messages.md +80 -61
  113. package/docs/inbox.md +138 -93
  114. package/docs/node.md +1072 -972
  115. package/docs/permissions.md +142 -0
  116. package/docs/proposing-collections.md +74 -55
  117. package/docs/query-format.md +150 -126
  118. package/docs/records-and-queries.md +205 -126
  119. package/docs/sign-in.md +496 -418
  120. package/docs/spaces.md +261 -245
  121. package/docs/standard-library.md +473 -504
  122. package/docs/storage.md +325 -348
  123. package/docs/usernames.md +164 -97
  124. package/docs/warrants.md +100 -67
  125. package/package.json +1 -2
package/docs/spaces.md CHANGED
@@ -1,274 +1,290 @@
1
- # Spaces in the library
1
+ # Spaces
2
2
 
3
- What the library chooses when it creates, invites to, reads and keeps
4
- spaces: constitution templates, invite defaults, profiles, the space manager, and how
5
- an app shows the account's own automations.
3
+ A space is a shared place: the records in it, and the people who may read
4
+ and write them. On this page we'll make a space, invite someone to it, and
5
+ then look at how a space decides who may do what.
6
6
 
7
- > Not protocol. None of this is checked by a peer, and another implementation
8
- > may do it differently and still interoperate. What peers must agree on about
9
- > spaces is in [spec 03 — Spaces](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
7
+ ## Making a space
10
8
 
11
- ## Presets
9
+ Give it a name, say whether it is private, and pick a preset for its roles:
10
+
11
+ ```ts
12
+ import { rolePresets } from '@minca/core';
13
+
14
+ const space = await node.spaces.create({
15
+ name: 'Bike co-op',
16
+ visibility: 'private',
17
+ ...rolePresets.community,
18
+ });
19
+ ```
20
+
21
+ A `private` space encrypts every record with the space's key, so only its
22
+ members can read it. A `public` one can be read by anyone who has it.
23
+
24
+ You are the space's founder. With no preset, the space gets `solo`: just you.
25
+
26
+ ## Inviting someone
27
+
28
+ `invite` makes an invite, a string you send to someone:
12
29
 
13
- A preset is a constitution template: who sits at the top, the roles a space
14
- is founded with and the grants each holds, and the roles the creator starts
15
- with ([spec 03 §1–§2](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
16
- The protocol reads whatever a constitution names and never looks at a
17
- preset's name; these are a sensible start for an app. Spread one into
18
- `spaces.create`, change it, or write your own:
30
+ ```ts
31
+ const invite = await node.spaces.invite(space.id);
32
+ ```
33
+
34
+ On their side, `preview` shows what it is for, and `join` takes them in:
19
35
 
20
36
  ```ts
21
- await node.spaces.create({ name: 'Bike co-op', visibility: 'private', ...rolePresets.coop });
37
+ declare const invite: string;
38
+ // ---cut---
39
+ const preview = await node.spaces.preview(invite); // its name, who sent it, the role
40
+ const joined = await node.spaces.join(invite);
22
41
  ```
23
42
 
24
- | Preset | `top` | Roles and their grants |
25
- | ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
- | `solo` | `founders` | none: the founder alone |
27
- | `team` | `founders` | editor: `/record`; `/collection/define`; `/role/assign` with `.role == "editor"` |
28
- | `community` | `founders` | admin: `/record`, `/collection/define`, `/role/assign`, `/role/define` for every role but admin, `/role/unassign` and `/member/remove` of anyone not an admin, `/std.automation/instruct`, `/space/succeed`, `/key/change`, `/space/relays`, `/space/keepers`; moderator: `/record`, `/role/assign` with `.role == "member"`, `/std.automation/instruct`; member: `/record/write` and `/record/delete` where `.byCreator` is true, outside `STAFF_COLLECTIONS` |
29
- | `coop` | `none` | steward (the creator's): `/record`, `/collection/define`, `/role/define` for member, `/role/assign` and `/role/unassign` of member or steward, `/member/remove` of anyone, `/std.automation/instruct`, `/space/succeed`, `/key/change`, `/space/relays`, `/space/keepers`; member: as in `community`, and `/space/succeed` |
30
-
31
- Under `top: founders` the creator is the space's founder and holds every
32
- command whatever the roles say, so no `founders` preset needs a role for it.
33
- `cofounders` names others who found it too. Under `top: none` (`coop`) there
34
- is no founder: the creator holds only `creatorRoles`, here `steward`, and
35
- another steward can remove it.
36
-
37
- Each preset must say explicitly whether members may change each other's
38
- records: a grant of `/record/write` without a policy on `.byCreator` lets
39
- them. In `community` and `coop`, members change only what they made, and
40
- moderators or stewards anything.
41
-
42
- What `.roles` protects, and what it doesn't. "Of anyone not an admin" is a
43
- policy on the target's roles, read as of the remover's own view, which the
44
- remover chooses by what it names as seen (spec 03 §2.3, §3.2). It stops an
45
- admin who has seen another's promotion. It doesn't stop one who names a view
46
- from before it, or acts concurrently with it: `community` admins can still
47
- remove or demote each other that way. `.roles` protects only against a
48
- remover whose view includes the target's role. A space where that matters
49
- gives removal to fewer people, or to the founders alone.
50
-
51
- A role that may define itself can be locked by rival definitions (spec 03
52
- §2): two of its holders who rewrite it apart and disagree leave it holding
53
- only what they share, and if that drops `/role/define`, nobody in it can
54
- settle them. So a preset gives `/role/define` for a role to another role, or
55
- to the founders alone: in `community` the founders define admin, and admins
56
- define the rest. In `coop` stewards define member, and nobody defines
57
- steward: its grants are the constitution's, and changing them takes a
58
- successor.
59
-
60
- `STAFF_COLLECTIONS` are the standard collections only moderators start in a
61
- community: announcements, badges, awards, pins, labels, channels and hosts.
62
- Their definitions used to say so with `create` rules; now the template does.
63
-
64
- When a space is created with no roles, it gets `solo`. The account's derived
65
- spaces (the registry, the contacts space) use `solo`'s roles, none, byte for
66
- byte: their ids depend on it
67
- ([spec 03 §13.1](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
68
- Changing `solo` would change those ids, so it must not change.
69
-
70
- _Source: `packages/core/src/space/presets.ts` (`solo`, `team`, `community`, `coop`, `STAFF_COLLECTIONS`), `packages/core/src/space/grants.ts`, `packages/core/src/space/space-manager.ts` (`create`), `packages/core/src/node/node.ts` (`spaces.create`). Tests: `packages/core/tests/space.test.ts`, `packages/core/tests/roles.test.ts` ("definitions", "`community` admins can remove each other by naming a view before the promotion"), `packages/core/tests/constitution.test.ts` ("the templates are well formed", "a co-op: no founders…")._
71
-
72
- ## The top and founders
73
-
74
- `spaces.access(id)` says who is at the top: `top` (`founders` or `none`),
75
- each member's `founder`, and `founder` for this account. A founder may:
76
-
77
- - **step down** with `spaces.stepDown(id, { keep? })`: it stays, with the
78
- roles it holds, and is a founder no more. Given `keep`, it assigns itself
79
- that role first. With no role it would be no member, so the library
80
- refuses; to go altogether, `leave`. Stepping down strikes whatever this
81
- account did elsewhere that hadn't seen it, as leaving does, so do it from
82
- a device that has synced;
83
- - **leave**, with `spaces.leave(id)`, as anyone may.
84
-
85
- Nobody removes or demotes a founder but the founder itself, so an app shows
86
- no remove button on a founder, and a "Step down" button on your own row when
87
- you are one.
88
-
89
- **Headless.** `access.headless` is true when no founder is left and no
90
- member may define or assign any role. Members keep what their roles allow,
91
- but nobody can change roles, and nothing in the constitution can change. An
92
- app says so plainly ("No one can change roles here any more") and offers the
93
- way on: naming a successor (below), which any member may do once no member holds `/space/succeed`.
94
-
95
- _Source: `packages/core/src/node/space-membership.ts` (`stepDown`, `access`), `packages/core/src/space/roles.ts` (`headless`). Tests: `packages/core/tests/constitution.test.ts` ("stepping down", "a founder steps down, keeping a role…")._
43
+ By default the invite gives the `member` role. Pass `{ role: 'editor' }` for
44
+ another, or `{ write: false }` to let them read and not write.
45
+
46
+ An invite is long. For something to paste in a chat, ask for a short link,
47
+ about 85 characters:
48
+
49
+ ```ts
50
+ const link = await node.spaces.invite(space.id, { short: true });
51
+ ```
52
+
53
+ ## Invite links
54
+
55
+ A private invite carries the space's key, so put it after `#` in a link.
56
+ Browsers never send that part to a server. `@minca/react` has three helpers:
57
+
58
+ - `inviteLink(invite)` makes a link to the current page.
59
+ - `inviteFromLink(text)` takes the invite out of a pasted link.
60
+ - `useInviteLink()` reads the invite the page was opened with.
61
+
62
+ ## Leaving
63
+
64
+ ```ts
65
+ await node.spaces.leave(space.id);
66
+ ```
67
+
68
+ Anyone may leave, founders too.
69
+
70
+ ## Presets
71
+
72
+ A preset is a starting constitution: who sits at the top, and the roles the
73
+ space begins with. `solo`, `team`, `community` and `coop` are described in
74
+ [Permissions](permissions.md#presets).
96
75
 
97
76
  ## Successors
98
77
 
99
- A space whose constitution must change, or a headless one, moves on to a
100
- successor (spec 03 §2.7). With the library:
78
+ A space whose constitution must change, or a headless one, moves on to a new
79
+ space, its successor:
101
80
 
102
- 1. Create the new space naming the old: `spaces.create({ …, succeeds: oldId })`.
103
- 2. Name it in the old space: `spaces.succeed(oldId, newId)`. It needs
81
+ 1. Create the new space, naming the old:
82
+ `spaces.create({ …, succeeds: oldId })`.
83
+ 2. Name it in the old space: `spaces.succeed(oldId, newId)`. This needs
104
84
  `/space/succeed`, or a place in a space where no member holds it. Where
105
85
  this node holds the new space, it refuses one whose constitution doesn't
106
86
  say it succeeds the old.
107
- 3. Tell members how to join it: an invite to the new space, posted in the
108
- old one (an announcement, a message). The succeed record carries only the
109
- new space's id.
87
+ 3. Tell members how to join: post an invite to the new space in the old one.
88
+ The succeed record carries only the new space's id.
110
89
 
111
- `spaces.access(oldId).successors` lists every space named, each with the
112
- accounts that named it: `[{ space, by }]`. A successor changes nothing in
113
- the old space; whoever stays carries on there.
90
+ A successor changes nothing in the old space. Whoever stays carries on there.
114
91
 
115
- What an app shows:
92
+ ### Showing successors
116
93
 
117
- - every successor named, **in no order**: never one as first, and never one
118
- picked for the member, since which community a member joins is theirs to
119
- choose. The list's order means nothing;
120
- - who named each, and whether each namer is still a member: a succeed stays
121
- named after its namer is removed;
122
- - that a space is a successor only once both hold: the new space's
123
- `succeeds` (`SpaceSummary.succeeds`, `preview(invite).space.succeeds`)
124
- names the old one, and the old one's `successors` names the new. An
125
- invite to a space that claims to succeed another, with no succeed for it
126
- there, is a copy, and is shown as one.
94
+ `spaces.access(oldId).successors` lists every space named, with who named
95
+ it ([`SpaceAccess`](https://minca.dev/api/core/interfaces/SpaceAccess/)).
96
+ Show:
127
97
 
128
- _Source: `packages/core/src/node/node.ts` (`spaces.succeed`), `packages/core/src/node/space-membership.ts` (`succeed`, `access`), `packages/core/src/space/space-manager.ts` (`previewInvite`). Tests: `packages/core/tests/constitution.test.ts` ("/space/succeed", "a successor: made with succeeds…")._
98
+ - **Every successor, in no order.** Never pick one for the member, or show
99
+ one first. Which community to join is theirs to choose.
100
+ - **Who named each**, and whether they are still a member. A succeed stays
101
+ after its namer is removed.
102
+ - **A successor only when both sides agree.** The new space's `succeeds`
103
+ (`SpaceSummary.succeeds`, `preview(invite).space.succeeds`) names the old,
104
+ and the old one's `successors` names the new. An invite to a space that
105
+ claims to succeed another, with no succeed for it there, is a copy. Show it
106
+ as one.
107
+
108
+ See [spec 03 §2.7](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
129
109
 
130
110
  ## Invites
131
111
 
132
- `node.spaces.invite(id, options?)`:
133
-
134
- - With no role given, it opens an invite for `member` when the inviter may
135
- assign it (`/role/assign` with `{ role, self: false, roles: [] }`), else for
136
- the first role by name it may assign. With none (as in `solo`), it makes a
137
- view-only invite. Opening an invite for a role needs the same grant as
138
- assigning it to someone holding nothing. Peers judge each join as the
139
- assignment the invite's opener makes, to whoever joins (spec 03 §4.5): an
140
- opener whose grant says `.self == false` can't join its own invite. A
141
- joiner judged in a view from before the opener lost the grant still gets
142
- in: to stop an invite, close it.
143
- - `write: false` always makes a view-only invite.
144
- - Each role invite gets its own fresh secret and its own `sys.invite` record,
145
- so one can be closed without the others.
146
- - The invite names the space's relays, or the inviter's own when the space
147
- names none, and the always-on nodes that hold it: the account's hosts and
148
- the space's own, at most 8, each pinned by its DID. A host that can't be
149
- described within three seconds is left out rather than hold the invite up.
150
- - `short: true` makes a short link (spec 03 §7.7), about 85 characters: the
151
- invite is sealed and left in the mailbox of the account's first host and of
152
- the first relay that takes it, and the link names those two. Where no
153
- mailbox takes it, or the space's constitution is too large for one, the
154
- long invite is returned instead; it works the same. `until` (ms) says when
155
- to stop sharing it.
156
-
157
- **Short links the account keeps.** Each short link's sealed invite is kept in
158
- the account registry (`sys.link`), never its secret, and copied to every
159
- carrier's carry space, so the account's host serves it while every device is
160
- away. Every hour, and whenever the registry or a space's key changes, a
161
- device holding the account key drops each one again where the space's members
162
- meet. One past its `until`, or carrying a key the space has moved on from, is
163
- ended: its role invite is closed and the record deleted. `closeInvite` by a
164
- short link closes its invite and forgets the record. The device that made a
165
- link holds its secret nowhere: copy the link when it is made.
112
+ `node.spaces.invite(id, options?)` takes the options in
113
+ [`InviteOptions`](https://minca.dev/api/core/interfaces/InviteOptions/): the
114
+ role it gives, `write: false` for a view-only invite, and `short` for a short
115
+ link.
116
+
117
+ ### Which role
118
+
119
+ With no `role`, the invite is for `member` when you may assign it. Otherwise
120
+ it is for the first role, by name, that you may assign. With none, as in
121
+ `solo`, it is view-only.
122
+
123
+ Opening an invite for a role needs the same grant as assigning that role to
124
+ someone who holds nothing: `/role/assign` with
125
+ `{ role, self: false, roles: [] }`. Each join counts as you assigning the
126
+ role to whoever joins. So if your grant says `.self == false`, you can't join
127
+ your own invite.
128
+
129
+ Someone judged on a view from before you lost the grant still gets in. To
130
+ stop an invite, close it with `spaces.closeInvite`.
131
+
132
+ Each role invite has its own secret and its own `sys.invite` record, so you
133
+ can close one without the others.
134
+
135
+ See [spec 03 §4.5](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
136
+
137
+ ### What an invite carries
138
+
139
+ An invite names where to find the space:
140
+
141
+ - the space's relays, or yours when the space names none;
142
+ - the always-on nodes that hold it, your account's hosts and the space's own,
143
+ at most 8, each pinned by its DID. A host that doesn't answer within three
144
+ seconds is left out, so it never holds the invite up.
145
+
146
+ On `join`, the node uses the invite's relays only when they pass
147
+ `checkRelays` and it has no relay list for the space yet. The invite's nodes
148
+ are dialled for the space, and kept like its relays.
149
+
150
+ Until the invite's record reaches this device, the space is held with
151
+ `joining: true`, and the node tries again as records arrive. See
152
+ [spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
153
+
154
+ ### Previewing
166
155
 
167
156
  `node.spaces.preview(invite)` reads an invite without storing anything, and
168
- for a short link fetches it first, which is why it is async:
157
+ gives an [`InvitePreview`](https://minca.dev/api/core/interfaces/InvitePreview/).
158
+ `invitedBy` is the account that signed the invite. `preview` and `join` both
159
+ refuse an invite whose signature or note doesn't check out. See
160
+ [spec 03 §7.4](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
169
161
 
170
- ```
171
- { space: { id, name, visibility, founders, createdAt, succeeds? }, invitedBy,
172
- carriesKey, carriesWrite, role, // role is null for a view-only invite
173
- until? } // a short link's, when given
174
- ```
162
+ ### Short links
163
+
164
+ `short: true` seals the invite and leaves it in two mailboxes: your account's
165
+ first host's, and the first relay's that takes it. The link names those two.
166
+ When no mailbox takes it, or the space's constitution is too big for one, you
167
+ get the long invite back. It works the same.
168
+
169
+ `preview` fetches a short link first, which is why it is async. The node
170
+ remembers it, so a preview and the join after it ask the mailboxes once. A
171
+ link whose invite is nowhere fails with "That invite was not found": it may
172
+ have expired, or its mailboxes may be down.
175
173
 
176
- `invitedBy` is the account that signed the invitation: `preview` and `join`
177
- both refuse an invite whose signature or note doesn't check out ([spec 03 §7.4](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
178
- A short link is fetched once and remembered by the node, so a preview and the
179
- join after it ask the mailboxes once. A link whose invite is nowhere fails
180
- with "That invite was not found"; it may have expired or its places be down.
181
- Invite nodes are dialled for the space alongside the hosts the account uses,
182
- and kept like its invite relays.
174
+ The device that made a link keeps its secret nowhere, so copy the link when
175
+ you make it.
183
176
 
184
- On `join`, relays carried by the invite are a hint: the node uses them only
185
- when they pass `checkRelays` and it holds no relay list for the space yet.
186
- While the invite's record has not reached this device, the space is held with
187
- `joining: true` and the node tries again as records arrive
188
- ([spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
177
+ See [spec 03 §7.7](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
189
178
 
190
- _Source: `packages/core/src/node/node.ts` (`spaces.invite`, `preview`, `join`), `packages/core/src/node/node-hosting.ts` (`nodesOf`), `packages/core/src/node/node-carriers.ts` (`inviteTo`, `shortInvite`, `resolveInvite`, `keepLinks`), `packages/core/src/space/space-manager.ts` (`previewInvite`, `join`), `packages/core/src/space/invite-link.ts`. Tests: `packages/core/tests/space.test.ts` ("invites"), `packages/core/tests/roles.test.ts` ("invites"), `packages/core/tests/invite-link.test.ts`, `packages/cli/tests/host.test.ts` ("someone invited reaches the space through the inviter’s host…", "a short link: the host keeps it…")._
179
+ ### Short links the account keeps
180
+
181
+ Each short link's sealed invite, never its secret, is kept in the account
182
+ registry as `sys.link`. It is copied to every carrier, so your host serves it
183
+ while all your devices are away.
184
+
185
+ Every hour, and whenever the registry or a space's key changes, a device
186
+ holding the account key drops each link again where the space's members meet.
187
+ A link past its `until`, or carrying a key the space has moved on from, is
188
+ ended: its invite is closed and the record deleted.
189
+
190
+ `closeInvite` with a short link closes its invite and forgets the record.
191
191
 
192
192
  ## Keeping a space's keys and relays
193
193
 
194
- The node does the protocol's key upkeep by itself, in each space it opens:
194
+ The node looks after each space it opens by itself:
195
195
 
196
- - On every upkeep it publishes this account's member key when it differs from
197
- the one published.
198
- - When a key change is due and its account may invoke `/key/change` and it
196
+ - It publishes this account's member key when it differs from the one
197
+ published.
198
+ - When a key change is due, and the account may invoke `/key/change` and
199
199
  holds the current key, it changes the key. `node.spaces.changeKey` does the
200
200
  same by hand.
201
- - In a space with no relays named yet, a node whose account may invoke
202
- `/space/relays` names its own.
203
-
204
- _Source: `packages/core/src/node/space-keys.ts` (`upkeep`, `rotateKey`, `nameRelays`). Tests: `packages/core/tests/key-change.test.ts`, `packages/core/tests/space-relays.test.ts`._
201
+ - In a space with no relays named yet, if the account may invoke
202
+ `/space/relays`, it names its own.
205
203
 
206
204
  ## Flagged accounts
207
205
 
208
- `spaces.access(id).flagged` lists accounts proven to have broken the protocol's
209
- rules in the space, by warrants members wrote and this node checked
210
- ([warrants](warrants.md)).
206
+ `spaces.access(id).flagged` lists accounts proven to have broken the
207
+ protocol's rules in the space. The proof is a warrant a member wrote and this
208
+ node checked. See [warrants](warrants.md).
211
209
 
212
210
  ## Profiles
213
211
 
214
- The record format, and whose versions count, is protocol
215
- ([spec 03 §11](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
216
- The rest is the library's.
217
-
218
- **Reading.** For each `profile:` key, the node looks at versions newest first,
219
- skipping any that is not `sys.profile`, does not verify, does not stand, or
220
- whose root's `hex40` is not the record key:
221
-
222
- - a deleted version ends the search: no profile;
223
- - the first remaining version gives `name` (trimmed, cut to 64 characters;
224
- empty means no profile), `did` (its root) and `updatedAt` (its `createdAt`);
225
- - `contactKey` comes from the newest remaining version that carries a valid
226
- P-256 point, so a newer version written without one does not hide it.
227
- - `avatar` comes from the newest version only (one without it has taken it
228
- away): a file reference (`records.addFile`) whose `mime` is an image.
229
-
230
- **Writing.** Profiles are written with `retain`, so older versions stay. A
231
- writer that does not hold the contact key must carry forward the
232
- `contactKey` of its current profile.
233
-
234
- **The account's name and picture.** The account keeps its name in the
235
- account registry, as `sys.profile` at key `profile` with body
236
- `{ name, avatar? }`; the newest version wins. `node.account.setName` writes
237
- the name, `setAvatar({ bytes, mime })` the picture (a file in the registry;
238
- the app resizes it first), and `picture()` reads it back. The node publishes
239
- both into every space it opens, and again on a change. A space's members
240
- can't read the registry, so the picture is copied into each space once, as a
241
- file of that space, and its reference names the registry file it copies
242
- (`source`), so opening the space again makes no second copy. A picture that
243
- can't be copied now (its bytes on a device that is away) leaves the space's
244
- copy as it was, and never holds back the name. Profiles are retained, so a
245
- picture once shared stays with the members who hold it: taking it away
246
- shows none from then on, and withdraws nothing. It publishes
247
- in every space but the registry and the contacts space, and not at all from
248
- a node whose note lacks `/account/write` (an agent's); a non-member
249
- publishes nothing
250
- ([spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
251
-
252
- > **Planned:** profiles, round two.
253
- >
254
- > - **A name per space** ("in this space, call me…"). The record is already
255
- > per space; what is missing is a way to say the name was chosen for this
256
- > space, so publishing the account name on the next rename does not
257
- > overwrite it.
258
- > - **Private nicknames for others**: a name you give someone, seen only by
259
- > you. It belongs in the account's own spaces, not in the shared one;
260
- > `std.contact`'s `name` already does this for contacts.
261
- >
262
- > Open questions: the field names; the avatar's size limit and format; and
263
- > whether nicknames for people who are not contacts get a collection of their
264
- > own. `profile:` keys may also change (spec 03 §8.6).
265
-
266
- _Source: `packages/core/src/node/space-profiles.ts` (`loadProfiles`), `packages/core/src/node/space-runtime.ts` (`publishProfile`), `packages/core/src/node/node-contacts.ts` (`publishProfile`, `ownName`, `account.setName`), `packages/core/src/space/account-registry.ts` (`PROFILE_COLLECTION`, `PROFILE_KEY`). Tests: `packages/core/tests/profiles.test.ts`, `packages/core/tests/contacts.test.ts` ("the contact key"), `packages/core/tests/account.test.ts` ("the account name")._
212
+ A profile is the name and picture someone shows in a space.
213
+ `node.spaces.profiles(id)` lists them.
214
+
215
+ ### Your name and picture
216
+
217
+ ```ts
218
+ declare const bytes: Uint8Array;
219
+ // ---cut---
220
+ await node.account.setName('Leif');
221
+ await node.account.setAvatar({ bytes, mime: 'image/png' });
222
+ ```
223
+
224
+ Both need the account key. Resize the picture first, and pass `null` to
225
+ remove it. `node.account.picture()` reads it back.
226
+
227
+ The node publishes both into every space it opens, and again when they
228
+ change. It skips the registry and the contacts space. A node whose note
229
+ lacks `/account/write`, such as an agent's, publishes nothing, and neither
230
+ does a non-member.
231
+
232
+ A picture once shared stays with the members who have it. Taking it away
233
+ shows none from then on, but withdraws nothing.
234
+
235
+ ### Showing names
236
+
237
+ A name is whatever its owner typed, so two people can both be "Sam".
238
+ `displayName(did, profiles)`, or `useNames(space)` in React, adds the tail
239
+ of the identity when a name is shared. For someone with no profile it shows
240
+ the tail alone.
241
+
242
+ ### How a profile is read
243
+
244
+ For each `profile:` key, the node looks at versions newest first. It skips
245
+ any that is not `sys.profile`, does not verify, does not stand, or whose
246
+ root's `hex40` is not the record key. Then:
247
+
248
+ - A deleted version ends the search: no profile.
249
+ - The first remaining version gives `name` (trimmed, cut to 64 characters;
250
+ empty means no profile), `did` (its root) and `updatedAt` (its
251
+ `createdAt`).
252
+ - `contactKey` comes from the newest remaining version with a valid P-256
253
+ point, so a newer version without one does not hide it.
254
+ - `avatar` comes from the newest version only, so a version without it takes
255
+ it away. It is a file reference (`records.addFile`) whose `mime` is an
256
+ image.
257
+
258
+ ### How a profile is written
259
+
260
+ Profiles are written with `retain`, so older versions stay. A writer that
261
+ does not hold the contact key must carry forward the `contactKey` of its
262
+ current profile.
263
+
264
+ The account keeps its own name in the account registry, as `sys.profile` at
265
+ key `profile`, with body `{ name, avatar? }`. The newest version wins.
266
+
267
+ Members of a space can't read the registry, so the picture is copied into
268
+ each space once, as a file of that space. Its reference names the registry
269
+ file it copies (`source`), so opening the space again makes no second copy. A
270
+ picture that can't be copied now, because its bytes are on a device that is
271
+ away, leaves the space's copy as it was. It never holds back the name.
272
+
273
+ The record format, and whose versions count, are protocol. See
274
+ [spec 03 §11](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)
275
+ and [spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
276
+
277
+ > **Planned:** profiles, round two. A name per space ("in this space, call
278
+ > me…"), which the next rename of the account would not overwrite. And
279
+ > private nicknames for others, kept in the account's own spaces, as
280
+ > `std.contact`'s `name` already does for contacts. Open: the field names, the
281
+ > avatar's size limit and format, a collection for nicknames of non-contacts,
282
+ > and whether `profile:` keys change (spec 03 §8.6).
267
283
 
268
284
  ## The space manager
269
285
 
270
- The space manager keeps, per space, in a storage adapter (the node's
271
- `registry` store, sealed at rest; see [node](node.md#stores)):
286
+ The space manager keeps what the node knows about each space in its
287
+ `registry` store, sealed at rest (see [node](node.md#stores)):
272
288
 
273
289
  | Storage key | Value |
274
290
  | --------------------- | -------------------------------------------------------------------------------------------- |
@@ -282,26 +298,24 @@ The space manager keeps, per space, in a storage adapter (the node's
282
298
  `remove` deletes all six. Joining again with a secret while one is waiting
283
299
  keeps the newer one.
284
300
 
285
- _Source: `packages/core/src/space/space-manager.ts`. Tests: `packages/core/tests/space.test.ts` ("space manager")._
286
-
287
301
  ## The account's own automations
288
302
 
289
303
  What the account wants to hear about is an automation of its own, kept in
290
- its registry ([automations](automations.md#the-accounts-own)). Its `app`
304
+ its registry. See [automations](automations.md#the-accounts-own). Its `app`
291
305
  names the app that proposed it, and that app shows what it matches. A home
292
306
  adds none of its own.
293
307
 
294
- **Narrowing with `where`.** A proposal, and an app's `notify` entry, may
295
- carry a `where` in its query: a filter over the record, the same as a
296
- query's ([query-format.md](query-format.md)): body fields, `link:<rel>`, and
297
- of the record's own fields `@key`, `@collection`, `@createdBy` and
298
- `@createdAt`. An app can build one from what a person picks — "a task whose
299
- priority is at least 3", "a poll that isn't closed" — rather than offering a
300
- fixed list. `checkOwnAutomation` says whether one can be kept, and
301
- `matches(record, filter)` whether it holds, which an app can use to show
302
- what it would have matched before proposing it.
308
+ ### Narrowing with `where`
309
+
310
+ A proposal, or an app's `notify` entry, can carry a `where`: a filter over
311
+ the record, the same as a [query's](query-format.md). It can test body
312
+ fields, `link:<rel>`, `@key`, `@collection`, `@createdBy` and `@createdAt`.
313
+ Build one from what a person picks, "a task whose priority is at least 3",
314
+ rather than offering a fixed list:
303
315
 
304
316
  ```typescript
317
+ import { notifyOn } from '@minca/core/schemas';
318
+
305
319
  await connection.propose([
306
320
  notifyOn('Urgent task for me', 'std.task', {
307
321
  assignees: { $contains: '$me' },
@@ -310,9 +324,11 @@ await connection.propose([
310
324
  ]);
311
325
  ```
312
326
 
313
- A condition on a topic field, at the top of `where` or in an `$and` there,
314
- is what a carrier's wake matches; the rest is judged only by the app. Without
315
- one, a carrier wakes the app for every new record of the collection, and the
316
- app turns down the rest.
327
+ `checkOwnAutomation` says whether one can be kept. `matches(record, filter)`
328
+ says whether a filter holds, so you can show what it would have matched
329
+ before proposing it.
317
330
 
318
- _Source: `packages/core/src/space/own-automations.ts` (`checkOwnAutomation`, `notifyOn`, `matchesRecord`), `packages/core/src/query/filter.ts` (`checkFilter`, `matches`), `packages/core/src/node/node-carriers.ts` (`automations`), `apps/example/src/notifications.ts`. Tests: `packages/core/tests/carrier.test.ts` ("notifications through a carrier"), `packages/core/tests/topics.test.ts` ("an automation of the account’s own: its where")._
331
+ A carrier wakes the app only on a condition on a topic field, at the top of
332
+ `where` or in an `$and` there. The app judges the rest. With no such
333
+ condition, a carrier wakes the app for every new record of the collection,
334
+ and the app turns down the rest.