@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.
- package/README.md +10 -9
- package/dist/elements/auth-styles.d.ts +1 -1
- package/dist/elements/auth-styles.d.ts.map +1 -1
- package/dist/elements/auth-styles.js +14 -5
- package/dist/elements/auth-styles.js.map +1 -1
- package/dist/elements/minca-auth.d.ts.map +1 -1
- package/dist/elements/minca-auth.js +18 -15
- package/dist/elements/minca-auth.js.map +1 -1
- package/dist/files/space-files.d.ts +2 -2
- package/dist/files/space-files.d.ts.map +1 -1
- package/dist/files/space-files.js +7 -5
- package/dist/files/space-files.js.map +1 -1
- package/dist/inbox/names.d.ts +1 -1
- package/dist/inbox/names.js +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/network/ws-transport.d.ts.map +1 -1
- package/dist/network/ws-transport.js +3 -0
- package/dist/network/ws-transport.js.map +1 -1
- package/dist/node/actions.d.ts +5 -0
- package/dist/node/actions.d.ts.map +1 -1
- package/dist/node/actions.js +39 -20
- package/dist/node/actions.js.map +1 -1
- package/dist/node/api.d.ts +2 -0
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +2 -0
- package/dist/node/api.js.map +1 -1
- package/dist/node/carrier.js +1 -1
- package/dist/node/carrier.js.map +1 -1
- package/dist/node/node-carriers.d.ts.map +1 -1
- package/dist/node/node-carriers.js +6 -1
- package/dist/node/node-carriers.js.map +1 -1
- package/dist/node/node-contacts.d.ts.map +1 -1
- package/dist/node/node-contacts.js +1 -0
- package/dist/node/node-contacts.js.map +1 -1
- package/dist/node/node-hosting.d.ts.map +1 -1
- package/dist/node/node-hosting.js +11 -4
- package/dist/node/node-hosting.js.map +1 -1
- package/dist/node/node-records.d.ts.map +1 -1
- package/dist/node/node-records.js +6 -1
- package/dist/node/node-records.js.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +14 -1
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +7 -1
- package/dist/node/remote.js.map +1 -1
- package/dist/node/space-holding.d.ts +7 -3
- package/dist/node/space-holding.d.ts.map +1 -1
- package/dist/node/space-holding.js +90 -18
- package/dist/node/space-holding.js.map +1 -1
- package/dist/node/space-peers.d.ts.map +1 -1
- package/dist/node/space-peers.js +58 -24
- package/dist/node/space-peers.js.map +1 -1
- package/dist/node/space-runtime.d.ts +11 -3
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +22 -1
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/space-writing.d.ts +2 -0
- package/dist/node/space-writing.d.ts.map +1 -1
- package/dist/node/space-writing.js +2 -0
- package/dist/node/space-writing.js.map +1 -1
- package/dist/node/types.d.ts +130 -36
- package/dist/node/types.d.ts.map +1 -1
- package/dist/query/types.d.ts +1 -0
- package/dist/query/types.d.ts.map +1 -1
- package/dist/query/types.js.map +1 -1
- package/dist/records/contract-builder.d.ts +22 -6
- package/dist/records/contract-builder.d.ts.map +1 -1
- package/dist/records/contract-builder.js.map +1 -1
- package/dist/schemas/automations.d.ts +6 -2
- package/dist/schemas/automations.d.ts.map +1 -1
- package/dist/schemas/automations.js.map +1 -1
- package/dist/schemas/connectors.d.ts +4 -3
- package/dist/schemas/connectors.d.ts.map +1 -1
- package/dist/schemas/connectors.js +4 -3
- package/dist/schemas/connectors.js.map +1 -1
- package/dist/schemas/library/media.js +1 -1
- package/dist/schemas/library/media.js.map +1 -1
- package/dist/schemas/library/social.d.ts +258 -0
- package/dist/schemas/library/social.d.ts.map +1 -1
- package/dist/schemas/library/social.js +28 -1
- package/dist/schemas/library/social.js.map +1 -1
- package/dist/session/auth.d.ts +7 -3
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js.map +1 -1
- package/dist/session/hosting.d.ts.map +1 -1
- package/dist/session/hosting.js +8 -2
- package/dist/session/hosting.js.map +1 -1
- package/dist/space/presets.d.ts +2 -2
- package/dist/space/presets.d.ts.map +1 -1
- package/dist/space/presets.js +3 -2
- package/dist/space/presets.js.map +1 -1
- package/dist/storage/blob-store.d.ts +3 -0
- package/dist/storage/blob-store.d.ts.map +1 -1
- package/dist/types.d.ts +11 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -93
- package/docs/actions.md +212 -144
- package/docs/agents.md +198 -155
- package/docs/automations.md +296 -204
- package/docs/blueprints-and-guides.md +405 -295
- package/docs/bots.md +208 -134
- package/docs/building-an-app.md +74 -163
- package/docs/collections.md +248 -328
- package/docs/computed.md +112 -89
- package/docs/contacts.md +151 -112
- package/docs/contracts.md +299 -120
- package/docs/direct-messages.md +80 -61
- package/docs/inbox.md +138 -93
- package/docs/node.md +1072 -972
- package/docs/permissions.md +142 -0
- package/docs/proposing-collections.md +74 -55
- package/docs/query-format.md +150 -126
- package/docs/records-and-queries.md +205 -126
- package/docs/sign-in.md +496 -418
- package/docs/spaces.md +261 -245
- package/docs/standard-library.md +473 -504
- package/docs/storage.md +325 -348
- package/docs/usernames.md +164 -97
- package/docs/warrants.md +100 -67
- package/package.json +1 -2
|
@@ -1,39 +1,25 @@
|
|
|
1
1
|
# Blueprints and guides
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
A **blueprint** (`std.blueprint`) proposes new collections for a space, and a
|
|
4
|
+
**guide** (`std.guide`) says in words how some collections are meant to be
|
|
5
|
+
used. Together they let a space grow without anyone deploying anything. This
|
|
6
|
+
page is the reference. For a walkthrough, start with
|
|
7
|
+
[Proposing collections](proposing-collections.md).
|
|
5
8
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
to be used, in words, for whoever writes to them next, often an agent.
|
|
11
|
-
|
|
12
|
-
Neither is about any one app. An app that keeps more about itself, such as a
|
|
13
|
-
screen or what to notify about, keeps it in records of its own that point at
|
|
14
|
-
its blueprint. The example app's launcher does
|
|
15
|
-
(`apps/example/src/components/apps/launcher.ts`). Both records' fields are in
|
|
16
|
-
the [standard library](standard-library.md).
|
|
17
|
-
|
|
18
|
-
> Not protocol. This page describes the reference library, and another
|
|
19
|
-
> implementation may do it differently and still interoperate. What peers must
|
|
20
|
-
> agree on is in the [spec](https://github.com/leifriksheim/minca/blob/main/spec/README.md).
|
|
9
|
+
Neither belongs to one app. An app that keeps more about itself, like a screen
|
|
10
|
+
or what to notify about, keeps it in records of its own that point at its
|
|
11
|
+
blueprint. Both records' fields are in the
|
|
12
|
+
[standard library](standard-library.md).
|
|
21
13
|
|
|
22
14
|
## Who proposes
|
|
23
15
|
|
|
24
16
|
Anyone in a space may write a blueprint. It is how a key that may only write
|
|
25
|
-
records asks for collections
|
|
26
|
-
a person
|
|
27
|
-
|
|
28
|
-
key whose note doesn't grant `/collection/define`, so a blueprint is the only
|
|
29
|
-
way such a key gets a collection.
|
|
17
|
+
records asks for collections. That might be an agent, whose note grants records
|
|
18
|
+
only, or a person whose role doesn't hold `/collection/define`. Both take the
|
|
19
|
+
same path.
|
|
30
20
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
`/collection/define` in the space, and a note that grants it. It defines
|
|
34
|
-
`std.blueprint` itself first when the space lacks it. Who may edit a
|
|
35
|
-
blueprint is the space's grants: under the `community` template, only its
|
|
36
|
-
proposer, moderators and admins.
|
|
21
|
+
A blueprint is the only way such a key gets a collection. Every peer refuses a
|
|
22
|
+
definition from a key whose note doesn't grant `/collection/define`.
|
|
37
23
|
|
|
38
24
|
```typescript
|
|
39
25
|
import { proposeCollections, reviewBlueprint, applyBlueprint } from '@minca/core/schemas';
|
|
@@ -60,80 +46,103 @@ const review = reviewBlueprint(proposal.body!, await node.collections.list(space
|
|
|
60
46
|
await applyBlueprint(node, space.id, proposal.key);
|
|
61
47
|
```
|
|
62
48
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
49
|
+
Who may edit a blueprint is up to the space's grants. Under the `community`
|
|
50
|
+
template, that is its proposer, moderators and admins.
|
|
51
|
+
|
|
52
|
+
## Applying
|
|
53
|
+
|
|
54
|
+
`applyBlueprint` defines each collection the space doesn't have yet, as the
|
|
55
|
+
blueprint says, signed by whoever applies it. They need a grant of
|
|
56
|
+
`/collection/define` in the space, and a note that grants it. If the space
|
|
57
|
+
doesn't have `std.blueprint` yet, it defines that first.
|
|
58
|
+
|
|
59
|
+
It returns the [review](#the-review) of the blueprint as the space now has it.
|
|
60
|
+
|
|
61
|
+
## What a blueprint may hold
|
|
62
|
+
|
|
63
|
+
`checkBlueprint` refuses a blueprint that breaks these:
|
|
74
64
|
|
|
75
|
-
|
|
65
|
+
- At most 10 collections.
|
|
66
|
+
- No `sys.*` collection, and none named twice.
|
|
67
|
+
- No `version`. The space decides that when the blueprint is applied.
|
|
68
|
+
|
|
69
|
+
Through the `collections_propose` action, you can give a standard collection
|
|
70
|
+
by name, like `"std.event"`. `standardCollections` puts the library's
|
|
71
|
+
definition in its place, so it is exactly the library's. See
|
|
72
|
+
[what a `std.*` name means](standard-library.md#what-a-std-name-means).
|
|
73
|
+
|
|
74
|
+
## Copying to another space
|
|
75
|
+
|
|
76
|
+
`copyBlueprint` proposes the same blueprint in another space, with `from`
|
|
77
|
+
naming where it came from. People there decide for themselves.
|
|
78
|
+
|
|
79
|
+
## Actions
|
|
80
|
+
|
|
81
|
+
The node's actions are `collections_propose`, `collections_proposals` and
|
|
82
|
+
`collections_apply` ([actions](actions.md)). An agent's node isn't offered
|
|
83
|
+
`collections_apply`.
|
|
76
84
|
|
|
77
85
|
## The review
|
|
78
86
|
|
|
79
|
-
`reviewBlueprint` works out what applying a blueprint would do in a space
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
87
|
+
`reviewBlueprint` works out what applying a blueprint would do in a space.
|
|
88
|
+
Show it to the person before they apply.
|
|
89
|
+
|
|
90
|
+
Each collection comes back as one of three:
|
|
91
|
+
|
|
92
|
+
| `status` | Means |
|
|
93
|
+
| -------- | ------------------------------------------ |
|
|
94
|
+
| `new` | The space doesn't have it yet |
|
|
95
|
+
| `same` | The space already has it, exactly so |
|
|
96
|
+
| `change` | The space has it, and this would change it |
|
|
97
|
+
|
|
98
|
+
Each also has a `summary`: what it allows, in sentences worked out from its
|
|
99
|
+
rules ([describing a collection](#describing-a-collection)). A change also
|
|
100
|
+
says what would be different, and which applied blueprints it could break.
|
|
101
|
+
The rest is on [`CollectionReview`](https://minca.dev/api/schemas/interfaces/CollectionReview/).
|
|
85
102
|
|
|
86
|
-
A
|
|
87
|
-
collection meets a blueprint made against an earlier one: a `std.*`
|
|
88
|
-
collection is **the same** as what the space holds when the space's schema,
|
|
89
|
-
history, links, rules and topics are the library's. The review
|
|
90
|
-
never offers an earlier standard definition as a change to a space that
|
|
91
|
-
holds the current one, since applying it would only take the additions away.
|
|
103
|
+
A blueprint is `applied` once every collection in it is `same`.
|
|
92
104
|
|
|
93
|
-
|
|
105
|
+
### Older standard definitions
|
|
106
|
+
|
|
107
|
+
A blueprint made against an earlier version of a `std.*` collection doesn't
|
|
108
|
+
undo the space's newer one. A `std.*` collection counts as `same` when the
|
|
109
|
+
space holds the library's current definition. The review never offers the
|
|
110
|
+
older one as a change, since applying it would only take the additions away.
|
|
94
111
|
|
|
95
112
|
## Updates
|
|
96
113
|
|
|
97
|
-
|
|
98
|
-
|
|
114
|
+
To change a blueprint, propose a new one whose `updates` is the key of the
|
|
115
|
+
one it replaces:
|
|
99
116
|
|
|
100
117
|
```json
|
|
101
118
|
{ "title": "Carpool", "collections": [ … ], "updates": "5vcfnlfrf7qnql2jhyl7erfqva" }
|
|
102
119
|
```
|
|
103
120
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
superseded blueprint would only undo its update:
|
|
121
|
+
`updates` must name a blueprint in the same space. `proposeCollections` and
|
|
122
|
+
`collections_propose` refuse one that doesn't.
|
|
107
123
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
and `collections_propose` refuse one that does not.
|
|
124
|
+
Until the update is applied, the old blueprint is still the one in use. Once
|
|
125
|
+
it is, the old one is **superseded**. So is any blueprint whose update is
|
|
126
|
+
itself superseded. Applying a superseded blueprint would only undo its update,
|
|
127
|
+
so:
|
|
113
128
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
blueprints that need a collection it would change (`usedBy`), and
|
|
118
|
-
`collections_propose` warns a proposer whose blueprint changes one without
|
|
119
|
-
`updates`.
|
|
129
|
+
- `applyBlueprint` refuses it.
|
|
130
|
+
- Your app shouldn't offer it. It is history, which its proposer or a
|
|
131
|
+
moderator may delete.
|
|
120
132
|
|
|
121
|
-
|
|
122
|
-
|
|
133
|
+
Without `updates`, two blueprints that need the same collection differently
|
|
134
|
+
each show as a change that undoes the other. That's why the review names the
|
|
135
|
+
applied blueprints a change would touch (`usedBy`), and `collections_propose`
|
|
136
|
+
warns a proposer who changes a collection without `updates`.
|
|
123
137
|
|
|
124
|
-
|
|
138
|
+
> **Planned (open question):** with [`compare`](#compatible-definitions), an
|
|
139
|
+
> update's review would list its breaks.
|
|
125
140
|
|
|
126
141
|
## Guides
|
|
127
142
|
|
|
128
|
-
A definition says what a record may hold
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
`std.guide`: a `name`, a `title`, the `text`, and the `collections` it is
|
|
132
|
-
about. There is one guide of each name: whoever writes it first holds it.
|
|
133
|
-
|
|
134
|
-
`collections_list`, without names, gives each collection the guides about it,
|
|
135
|
-
`guides: [{ key, title }]`, so an agent finds them without knowing the app
|
|
136
|
-
exists, and reads one with `records_get` before writing there.
|
|
143
|
+
A definition says what a record may hold. It can't say "to add an app, write
|
|
144
|
+
one of these, pointing at a blueprint". A guide can. It has a `name`, a
|
|
145
|
+
`title`, the `text`, and the `collections` it is about:
|
|
137
146
|
|
|
138
147
|
```json
|
|
139
148
|
{
|
|
@@ -144,103 +153,190 @@ exists, and reads one with `records_get` before writing there.
|
|
|
144
153
|
}
|
|
145
154
|
```
|
|
146
155
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
156
|
+
There is one guide of each name. Whoever writes it first holds it.
|
|
157
|
+
|
|
158
|
+
`writeGuide` defines `std.guide` if the space lacks it, then writes the guide.
|
|
159
|
+
It rewrites the guide only when this account wrote it and the text has
|
|
160
|
+
changed, so your app can call it every time a space opens. `guidesOf` gives
|
|
161
|
+
the space's guides by the collections they are about.
|
|
162
|
+
|
|
163
|
+
### How agents find them
|
|
164
|
+
|
|
165
|
+
`collections_list`, called without names, gives each collection its guides as
|
|
166
|
+
`guides: [{ key, title }]`. An agent finds them without knowing the app
|
|
167
|
+
exists, and reads one with `records_get` before writing there.
|
|
153
168
|
|
|
154
|
-
|
|
169
|
+
A guide is what someone in the space wrote. An agent must read it as data
|
|
170
|
+
about the collections, never as instructions from the person it works for.
|
|
155
171
|
|
|
156
172
|
## Apps with a screen of their own
|
|
157
173
|
|
|
158
|
-
Core runs no app's code. An app that lets
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
screen in a sealed frame, and trusts a record only when someone who may
|
|
162
|
-
define collections wrote it under a note that isn't records-only
|
|
163
|
-
(`NodeRecord.recordsOnly`). It writes a guide on `launcher.app` saying how to
|
|
164
|
-
propose one.
|
|
174
|
+
Core runs no app's code. An app that lets people add apps with their own UI
|
|
175
|
+
keeps them as its own records, and runs the UI itself. This section describes
|
|
176
|
+
how the example app does it, as a pattern you can follow.
|
|
165
177
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
178
|
+
The example app keeps each app as a `launcher.app` record pointing at its
|
|
179
|
+
blueprint, and runs its screen in a sealed frame. It trusts a record only
|
|
180
|
+
when someone who may define collections wrote it, under a note that isn't
|
|
181
|
+
records-only (`NodeRecord.recordsOnly`). It writes a guide on `launcher.app`
|
|
182
|
+
saying how to propose one.
|
|
183
|
+
|
|
184
|
+
### The launcher's order
|
|
185
|
+
|
|
186
|
+
The launcher is in one order for everyone in the space, set by each record's
|
|
187
|
+
`position`. The example app opens a space on its Overview, which lists the
|
|
188
|
+
apps in that order. A new group starts with Chat. So does a new space for
|
|
189
|
+
two, which the person asking makes.
|
|
190
|
+
|
|
191
|
+
### What a screen can reach
|
|
171
192
|
|
|
172
193
|
A screen reaches the page around it only through `window.minca`, and only for
|
|
173
|
-
its app's collections and the people in its space
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
the
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
`
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
194
|
+
its app's collections and the people in its space. It can:
|
|
195
|
+
|
|
196
|
+
- list and write records, as the person looking;
|
|
197
|
+
- ask what they may do (`can`);
|
|
198
|
+
- get someone's picture (`picture`);
|
|
199
|
+
- ask the page to show a record or a person (`open`);
|
|
200
|
+
- open the record one of its own records links to (`open` with `link`), like
|
|
201
|
+
the message a file was shared on. The page shows it to the person and tells
|
|
202
|
+
the screen nothing.
|
|
203
|
+
|
|
204
|
+
`open` never follows a link to the space's own records (`sys.*` and
|
|
205
|
+
`launcher.app`). It answers the same whether or not the record exists. The
|
|
206
|
+
page does visibly open a record that exists, but only for the person, who
|
|
207
|
+
can see it anyway.
|
|
208
|
+
|
|
209
|
+
What a sealed frame can't do, the page does for it when asked, after checking
|
|
210
|
+
the request:
|
|
211
|
+
|
|
212
|
+
| Ask | Does |
|
|
213
|
+
| -------------------- | ------------------------------------------------------ |
|
|
214
|
+
| `places` | Searches for places, and asks where the person is |
|
|
215
|
+
| `link` | Opens an http or https page |
|
|
216
|
+
| `save` | Saves a text file |
|
|
217
|
+
| `remember`, `recall` | Keeps a few kilobytes per app on the device |
|
|
218
|
+
| `file` | Reads a picture one of the app's own records refers to |
|
|
219
|
+
| `blob` | Reads that whole file |
|
|
220
|
+
|
|
221
|
+
For `file` and `blob`, the type comes from the record, not from the screen.
|
|
222
|
+
|
|
223
|
+
### Settings and the network
|
|
224
|
+
|
|
225
|
+
An app may ask for `settings`, like an API key. Someone who may add apps fills
|
|
226
|
+
them in once, from the open app, for everyone in the space. Nobody else is
|
|
227
|
+
asked. The screen reads them as `minca.settings`.
|
|
228
|
+
|
|
229
|
+
Settings live on the app's own record, so they stand only as it does. A new
|
|
230
|
+
version proposed without values keeps the ones the app has. A copy to another
|
|
231
|
+
space carries none.
|
|
232
|
+
|
|
233
|
+
The origins an app names in `network` are allowed for everyone once it is
|
|
234
|
+
added. Adding it is the consent, as when a workspace admin adds an
|
|
235
|
+
integration. The ready-made Chat asks for a GIPHY key, and shows its GIF
|
|
236
|
+
button only once it has one.
|
|
237
|
+
|
|
238
|
+
### An app's icon
|
|
239
|
+
|
|
240
|
+
A `launcher.app` may carry an `icon`:
|
|
241
|
+
|
|
242
|
+
```json
|
|
243
|
+
{ "path": "M10 10…Z", "colour": "coral" }
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
`path` is the data of one SVG path on a 100 × 100 grid. `colour` is one of
|
|
247
|
+
the shape colours: cobalt, coral, peach, sage, lilac or ink. The example app
|
|
248
|
+
draws it filled, in place of the app's usual shape.
|
|
249
|
+
|
|
250
|
+
Icons come from other people, so the app draws one only when the path is
|
|
251
|
+
path data and nothing else: commands, numbers and separators, at most 4,000
|
|
252
|
+
characters. The stored schema can't hold that rule, so the check happens
|
|
253
|
+
where it is drawn.
|
|
254
|
+
|
|
255
|
+
The guide asks an agent for an icon when it makes an app. Changing an icon is
|
|
256
|
+
changing the app, like any other field. Updating a ready-made app keeps the
|
|
257
|
+
icon the space gave it.
|
|
258
|
+
|
|
259
|
+
### Opening a record where it belongs
|
|
260
|
+
|
|
261
|
+
A `launcher.app` may name, among its `collections`, the ones it `shows`. Those
|
|
262
|
+
are the collections it is the place to open, like `shows: ["std.message"]`
|
|
263
|
+
for a chat.
|
|
264
|
+
|
|
265
|
+
An entry may also name a kind, as `collection:kind`. It then covers only
|
|
266
|
+
records whose `kind` field holds it: `std.list:tab` for Bills' tabs,
|
|
267
|
+
`std.work:book` for a reading app, or a `kind` in an app's own collection.
|
|
268
|
+
Lists are folders, albums and tabs as well as checklists, and each belongs in
|
|
269
|
+
a different app.
|
|
270
|
+
|
|
271
|
+
When something asks to open a record, whether a screen's `open` or a link
|
|
272
|
+
beside a record, it goes to the app that shows it. Apps naming its kind come
|
|
273
|
+
before apps naming only its collection. Among those, it picks the app that's
|
|
274
|
+
open, else the only one, else the one the person picks. So a Bills tab shared
|
|
275
|
+
in a chat opens in Bills, a Files category in Files, and any other list in
|
|
276
|
+
Lists.
|
|
277
|
+
|
|
278
|
+
That app's screen is handed the record's key to scroll to or open
|
|
279
|
+
(`minca.shown`, `minca.onShow`, or the kit's `useShown`). It only gets keys
|
|
280
|
+
of collections it shows, which it could list anyway. It does learn which of
|
|
281
|
+
those records the person opens from elsewhere. That's one reason only someone
|
|
282
|
+
who may define collections adds an app.
|
|
283
|
+
|
|
284
|
+
With no app that shows it, or when an app opens one of its own records (a
|
|
285
|
+
poll's title in Polls, for its comments), the record opens beside whatever is
|
|
286
|
+
open. So Files opens a file's message in the chat, and a chat's file in
|
|
287
|
+
Files, without either knowing the other.
|
|
288
|
+
|
|
289
|
+
An app that names a collection in `shows` must do something with what it is
|
|
290
|
+
handed. The kit's `<Record>` draws any standard record as one line, the same
|
|
291
|
+
in every app, and opens it this way when clicked.
|
|
292
|
+
|
|
293
|
+
### Sharing a record into an app
|
|
294
|
+
|
|
295
|
+
A screen can't list or read what its app doesn't name. But a person can hand
|
|
296
|
+
it one record, the way a web page gets only the file a person picks for it.
|
|
297
|
+
|
|
298
|
+
`minca.pick` asks the page to show a finder over the whole space. The screen
|
|
299
|
+
gets the record the person chooses, or null. It may then link one of its own
|
|
300
|
+
records to it with `shares`, like a message. Anyone's screen reads it back
|
|
301
|
+
through that link, read only:
|
|
302
|
+
|
|
303
|
+
```js
|
|
304
|
+
minca.get(key, { link: 'shares' });
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
`shares` is the only link a screen reads through. A file about a diary entry,
|
|
308
|
+
or a reaction to it, shares nothing. So beyond its own collections, a screen
|
|
309
|
+
reads only records the person picked, or that someone writing its collections
|
|
310
|
+
shared: a member, an agent or another app.
|
|
311
|
+
|
|
312
|
+
That binds the screen, not its author. A member who wrote a screen can share
|
|
313
|
+
any record into its collections from their own node, and the screen reads it.
|
|
314
|
+
A shared record comes with its files' keys, but not their bytes.
|
|
315
|
+
|
|
316
|
+
A screen writes a link only to a record of its own collections, one the
|
|
317
|
+
person picked for it, or one the record already links to. A link is refused
|
|
318
|
+
the same way whether or not the target is here, so a link to a record that
|
|
319
|
+
hasn't arrived yet only goes through once it has. A screen never links out on
|
|
320
|
+
its own. Like anything it reads, though, it can copy what was shared into its
|
|
321
|
+
own records.
|
|
322
|
+
|
|
323
|
+
A screen may ask to pick as often as it likes, and may start the search from
|
|
324
|
+
its own text. What it gets is still only what the person chooses, in a space
|
|
325
|
+
they can read anyway. Enter takes the top match only once the person has
|
|
326
|
+
typed.
|
|
327
|
+
|
|
328
|
+
A chat shares a poll this way without being able to read polls: `/` typed
|
|
329
|
+
into an empty message, or the `/` button, picks one. So does a comment box,
|
|
330
|
+
through the kit's `useShare`.
|
|
331
|
+
|
|
332
|
+
### Live messages
|
|
333
|
+
|
|
334
|
+
A screen can send live messages to the other devices that have the same app
|
|
335
|
+
open in the space, with `live.send` and `live.on`. They are kept nowhere. Use
|
|
336
|
+
them for cursors, typing, who's here, or a game.
|
|
337
|
+
|
|
338
|
+
Each goes as a [live message](node.md#live-messages-and-status) of the space,
|
|
339
|
+
whose payload names the app by its `launcher.app` key:
|
|
244
340
|
|
|
245
341
|
```json
|
|
246
342
|
{
|
|
@@ -250,74 +346,77 @@ typing, who is here, or a game. Each goes as a live message of the space
|
|
|
250
346
|
}
|
|
251
347
|
```
|
|
252
348
|
|
|
253
|
-
A screen
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
part of the screen, so it doesn't count toward the 48 KB a screen may be.
|
|
264
|
-
|
|
265
|
-
The ready-made apps are screens too, written the same way. Adding one
|
|
266
|
-
defines its collections and writes a copy of it, naming where it came from
|
|
267
|
-
(`template: "kanban"`), and from then on the space changes its copy like any
|
|
268
|
-
other app.
|
|
349
|
+
A screen hears only those naming its own app, as
|
|
350
|
+
`{ from, device, data, viaAgent }`. `from` is the sender's account, as the
|
|
351
|
+
node proved it. A message from a peer with no account isn't passed on.
|
|
352
|
+
|
|
353
|
+
One screen may send a burst of 30, then 15 a second. That's below what a peer
|
|
354
|
+
takes from another overall, so a busy screen leaves room for calls and the
|
|
355
|
+
rest. An edited copy of an app is another `launcher.app` record, so its
|
|
356
|
+
screens don't hear the original's.
|
|
357
|
+
|
|
358
|
+
### The kit and ready-made apps
|
|
269
359
|
|
|
270
|
-
|
|
360
|
+
In front of every screen, the example app writes `@minca/ui` (`packages/ui`):
|
|
361
|
+
Preact with htm, hooks that keep records current, people's faces, and Minca's
|
|
362
|
+
look. So a screen is mostly what it is about. The kit doesn't count toward
|
|
363
|
+
the 48 KB a screen may be.
|
|
364
|
+
|
|
365
|
+
The ready-made apps are screens too, written the same way. Adding one defines
|
|
366
|
+
its collections and writes a copy of it, naming where it came from
|
|
367
|
+
(`template: "kanban"`). From then on the space changes its copy like any
|
|
368
|
+
other app.
|
|
271
369
|
|
|
272
370
|
## Describing a collection
|
|
273
371
|
|
|
274
|
-
A definition's `title` and `description` are its author's words and may say
|
|
275
|
-
anything.
|
|
276
|
-
|
|
277
|
-
every peer will enforce.
|
|
372
|
+
A definition's `title` and `description` are its author's words, and may say
|
|
373
|
+
anything. `describeCollection(definition)` says what the collection actually
|
|
374
|
+
allows, as fixed sentences worked out from its rules. A person deciding
|
|
375
|
+
whether to add a collection reads what every peer will enforce.
|
|
278
376
|
|
|
279
|
-
|
|
377
|
+
It returns, in this order:
|
|
280
378
|
|
|
281
379
|
1. `final`: "Nobody can change or remove a vote once it is added."
|
|
282
380
|
2. `onePer`: "One vote per person per poll — adding another changes the
|
|
283
|
-
first." (with `@author`)
|
|
284
|
-
first.", or with `final`, "… — the first one added holds it."
|
|
381
|
+
first." (with `@author`). Otherwise "… — anyone adding another replaces
|
|
382
|
+
the first.", or with `final`, "… — the first one added holds it."
|
|
285
383
|
3. `fixed`: "Once a poll is added, its “options” can't be changed."
|
|
286
|
-
4. Each condition of the contract (`contract.check`), in its own words:
|
|
287
|
-
|
|
288
|
-
|
|
384
|
+
4. Each condition of the contract (`contract.check`), in its own words:
|
|
385
|
+
"Every change is checked: “…”".
|
|
386
|
+
5. One per declared link: "Each vote points at one thing: a poll (“about”)."
|
|
387
|
+
or "A comment can point at anything in the space (“about”)."
|
|
289
388
|
6. `history: "all"`: "Every earlier version of a … is kept."
|
|
290
389
|
|
|
291
|
-
|
|
292
|
-
the
|
|
293
|
-
so the description says nothing of it.
|
|
390
|
+
Nouns come from `title`, else the last part of `name`. Field labels come from
|
|
391
|
+
the schema's `title`s, else the field name in words.
|
|
294
392
|
|
|
295
|
-
|
|
296
|
-
the
|
|
297
|
-
not know must make it fail rather than stay silent.
|
|
393
|
+
It says nothing about who may add, change or remove records. That's up to
|
|
394
|
+
the space's grants, not the definition.
|
|
298
395
|
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
_Source: `packages/core/src/records/describe.ts`. Tests: `packages/core/tests/records-only.test.ts` ("what a collection allows, in words")._
|
|
396
|
+
A rule the describer doesn't know makes it throw rather than stay silent. The
|
|
397
|
+
wording may change, but every rule always produces a sentence.
|
|
302
398
|
|
|
303
399
|
## Compatible definitions
|
|
304
400
|
|
|
305
|
-
|
|
306
|
-
**name**. Chat opens any `std.message`, whatever its fields and rules.
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
401
|
+
Today an app decides it can open a space by finding a collection with the
|
|
402
|
+
right **name**. Chat opens any `std.message`, whatever its fields and rules.
|
|
403
|
+
A space whose definition is a little older than the app's, like a
|
|
404
|
+
`std.message` or `std.comment` without the `shares` link, stays that way,
|
|
405
|
+
because the library skips a collection the space already has.
|
|
406
|
+
|
|
407
|
+
Whether an app can use a definition it didn't write is the app's question,
|
|
408
|
+
not the peers'. Peers store and judge every record the same way whatever the
|
|
409
|
+
answer.
|
|
311
410
|
|
|
312
|
-
> **Planned.** Not built
|
|
411
|
+
> **Planned.** Not built yet:
|
|
313
412
|
> [#11](https://github.com/leifriksheim/minca/issues/11),
|
|
314
413
|
> [#12](https://github.com/leifriksheim/minca/issues/12). The parts peers
|
|
315
|
-
> would check
|
|
316
|
-
>
|
|
414
|
+
> would check are planned in
|
|
415
|
+
> [spec 02 §6.5](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
|
|
317
416
|
|
|
318
417
|
### The check: `compare(held, wanted)`
|
|
319
418
|
|
|
320
|
-
`held` is the definition the space has
|
|
419
|
+
`held` is the definition the space has. `wanted` is the one the app was built
|
|
321
420
|
with. The result is two lists of breaks, each a path and a plain sentence:
|
|
322
421
|
|
|
323
422
|
```ts
|
|
@@ -331,66 +430,76 @@ interface Break {
|
|
|
331
430
|
} // 'rules.onePer', "Anyone can react twice with one emoji here; this app assumes once"
|
|
332
431
|
```
|
|
333
432
|
|
|
334
|
-
An app that only shows records needs `read` empty
|
|
335
|
-
Anything the checker
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
433
|
+
An app that only shows records needs `read` empty. One that writes needs
|
|
434
|
+
both. Anything the checker can't decide is a break.
|
|
435
|
+
|
|
436
|
+
**Fields.** Reading needs every body the space accepts to be one the app
|
|
437
|
+
accepts (held ⊆ wanted). Writing needs the reverse (wanted ⊆ held). The check
|
|
438
|
+
walks both schemas:
|
|
439
|
+
|
|
440
|
+
- `type` sets are contained (`integer` is inside `number`);
|
|
441
|
+
- a field one side relies on is `required` on the other;
|
|
442
|
+
- numeric and length ranges are contained;
|
|
443
|
+
- `enum`, `const` and `oneOf` value sets are contained;
|
|
444
|
+
- it recurses into `properties` and `items`.
|
|
445
|
+
|
|
446
|
+
`title`, `description`, `x-choicesFrom` and every other `x-*` annotation are
|
|
447
|
+
ignored. So is a field only one side mentions, unless that side requires it
|
|
448
|
+
or closes the schema with `additionalProperties: false`.
|
|
449
|
+
|
|
450
|
+
**Links.** A link role the app uses must be declared in the space. Where it
|
|
451
|
+
may point must be contained: `["app.poll"]` is inside `"*"` for reading, not
|
|
452
|
+
for writing. `"one"` is inside `"many"`. Roles the app doesn't know are
|
|
453
|
+
ignored when reading.
|
|
454
|
+
|
|
455
|
+
**Rules: never looser.** Stricter rules are never a safety problem. At worst
|
|
456
|
+
the app can't write, which `can` already reports. So rules are checked one
|
|
457
|
+
way: the space's rule must be an **attenuation** of the app's, as in UCAN.
|
|
458
|
+
|
|
459
|
+
- `onePer`: the space promises at least the uniqueness the app relies on.
|
|
460
|
+
Fewer parts is a stronger promise.
|
|
461
|
+
- `fixed`: the space keeps at least the fields the app expects fixed.
|
|
462
|
+
- `final`: an app that relies on it needs it.
|
|
463
|
+
|
|
464
|
+
Who may write is the space's grants, so it isn't compared.
|
|
359
465
|
|
|
360
466
|
### What uses it
|
|
361
467
|
|
|
362
468
|
1. **Apps open by compatibility**, not by name. A collection that exists but
|
|
363
|
-
|
|
469
|
+
isn't compatible is shown with its breaks instead of opened.
|
|
364
470
|
2. **Harmless updates apply themselves.** When the library's definition is
|
|
365
|
-
newer
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
3. **Anything else asks a person.** The blueprint review shows the breaks
|
|
370
|
-
options can now be changed after it is added"
|
|
371
|
-
rules".
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
standard library's. Peers don't refuse one
|
|
375
|
-
what each peer knows
|
|
376
|
-
incompatible `std.message` as not a message.
|
|
377
|
-
|
|
378
|
-
Built so far: `collections_propose` refuses a `std.*` definition that
|
|
379
|
-
the library's
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
471
|
+
newer, `compare(held, library)` finds no break either way, and the rules
|
|
472
|
+
are no looser, a writer allowed to change the definition writes it at the
|
|
473
|
+
next version without asking. Adding `shares` to an older `std.message` is
|
|
474
|
+
this case.
|
|
475
|
+
3. **Anything else asks a person.** The blueprint review shows the breaks,
|
|
476
|
+
like "a poll's options can now be changed after it is added", not just
|
|
477
|
+
"changes the rules".
|
|
478
|
+
|
|
479
|
+
Your app shouldn't define a `std.*` name that isn't compatible with the
|
|
480
|
+
standard library's. Peers don't refuse one when it arrives, since that would
|
|
481
|
+
depend on what each peer knows and leave them disagreeing. So an app treats
|
|
482
|
+
an incompatible `std.message` as not a message.
|
|
483
|
+
|
|
484
|
+
Built so far: `collections_propose` refuses a `std.*` definition that isn't
|
|
485
|
+
exactly the library's
|
|
486
|
+
([what a `std.*` name means](standard-library.md#what-a-std-name-means)).
|
|
487
|
+
Typed handles in the library (`node.use(space, Poll)`) would run the same
|
|
488
|
+
check.
|
|
489
|
+
|
|
490
|
+
The plans differ in one place. This check stays on the app's side and lets a
|
|
491
|
+
person approve a breaking change. #12 makes "additive" a rule peers enforce.
|
|
492
|
+
`compare` is the check "additive" needs, in both directions. Identical
|
|
493
|
+
content-addressed definitions (#11) are trivially compatible, so it would run
|
|
494
|
+
only on a real change.
|
|
387
495
|
|
|
388
496
|
### What "additive" means
|
|
389
497
|
|
|
390
|
-
Spec 02 §6.5 plans the rule
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
498
|
+
Spec 02 §6.5 plans the rule. This is why it draws the line where it does.
|
|
499
|
+
|
|
500
|
+
Changes are classified the way **oasdiff** classifies OpenAPI changes. A
|
|
501
|
+
collection's schema is treated as a request body and a response body at
|
|
502
|
+
once, because apps both write records and read them.
|
|
394
503
|
|
|
395
504
|
- **As a request**, a change must not **tighten**: a new required field, a
|
|
396
505
|
narrower type, a smaller range or length, fewer `enum`/`const`/`oneOf`
|
|
@@ -398,46 +507,47 @@ records (a request) and apps read them (a response).
|
|
|
398
507
|
longer write.
|
|
399
508
|
- **As a response**, a change must not **loosen**: a field no longer
|
|
400
509
|
required, a wider type, a larger range, more `enum` values, a link that may
|
|
401
|
-
point at more. Apps on the old definition would meet records they misread
|
|
402
|
-
|
|
510
|
+
point at more. Apps on the old definition would meet records they misread,
|
|
511
|
+
like a status they don't handle.
|
|
403
512
|
|
|
404
513
|
A change under the same name is additive when oasdiff would report no
|
|
405
|
-
error-level break
|
|
406
|
-
|
|
407
|
-
|
|
514
|
+
error-level break on either side. Its warnings and information stay that. The
|
|
515
|
+
catalogue of checks is oasdiff's, mapped onto the schema keywords and links.
|
|
516
|
+
A keyword it has no check for is a break.
|
|
408
517
|
|
|
409
|
-
Rules
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
518
|
+
Rules aren't shape. `onePer`, `fixed` and `final` are the space's governance,
|
|
519
|
+
like its grants. A space may tighten them under the same name, since at worst
|
|
520
|
+
an app can't write, which `can` reports. It may never loosen them past what
|
|
521
|
+
an app relies on.
|
|
413
522
|
|
|
414
523
|
### Open questions
|
|
415
524
|
|
|
416
525
|
- **Rules only apply from now on.** A space that was loose last month and
|
|
417
526
|
strict today holds records written under the loose rules. Either `compare`
|
|
418
|
-
looks at every definition the collection has had, or "compatible"
|
|
419
|
-
|
|
420
|
-
- **Translating instead of refusing
|
|
421
|
-
Cambria
|
|
527
|
+
looks at every definition the collection has had, or "compatible" describes
|
|
528
|
+
only records written from now on. Probably the second.
|
|
529
|
+
- **Translating instead of refusing.** Lenses between versions, as in
|
|
530
|
+
Cambria, would let an app read a definition it isn't compatible with.
|
|
531
|
+
Later.
|
|
422
532
|
|
|
423
533
|
## Planned: meaning-level hints
|
|
424
534
|
|
|
425
535
|
A definition says what a record may hold and the rules it keeps, not what it
|
|
426
|
-
means to a screen. Views
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
optional hints to a definition:
|
|
536
|
+
means to a screen. Views built from definitions, like the blueprint review or
|
|
537
|
+
made apps without a screen of their own, have to guess which field is the
|
|
538
|
+
title, or that votes show as counts. The plan adds optional hints:
|
|
430
539
|
|
|
431
540
|
- which field is the record's **title**;
|
|
432
|
-
- **tallies**:
|
|
433
|
-
`x-choicesFrom` already
|
|
434
|
-
- values **worked out on read
|
|
541
|
+
- **tallies**: show the records linking here as a count, the way
|
|
542
|
+
`x-choicesFrom` already allows vote-style counts;
|
|
543
|
+
- values **worked out on read**, like "voting closes Friday" or "who hasn't
|
|
435
544
|
answered". Each reader computes them from the records and its own clock, so
|
|
436
545
|
nothing has to run anywhere.
|
|
437
546
|
|
|
438
|
-
A field's kind
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
547
|
+
A field's kind, like a person, is already its `x-kind`
|
|
548
|
+
([collections](collections.md#schemas)). Hints are display only, like
|
|
549
|
+
`x-choicesFrom`. They are never checked when validating, and
|
|
550
|
+
[`compare`](#compatible-definitions) ignores them. A hint about one field is
|
|
551
|
+
an `x-*` keyword on it. One about the whole record is a top-level member of
|
|
552
|
+
the definition, which today's peers ignore. They'll be added when a derived
|
|
553
|
+
view falls short. The format is still open.
|