@minca/core 0.1.17 → 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 (86) hide show
  1. package/README.md +2 -1
  2. package/dist/files/space-files.d.ts +2 -2
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +7 -5
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/inbox/names.d.ts +1 -1
  7. package/dist/inbox/names.js +1 -1
  8. package/dist/index.d.ts +2 -0
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +2 -0
  11. package/dist/index.js.map +1 -1
  12. package/dist/node/actions.d.ts +3 -0
  13. package/dist/node/actions.d.ts.map +1 -1
  14. package/dist/node/actions.js.map +1 -1
  15. package/dist/node/api.d.ts +1 -0
  16. package/dist/node/api.d.ts.map +1 -1
  17. package/dist/node/api.js +1 -0
  18. package/dist/node/api.js.map +1 -1
  19. package/dist/node/carrier.js +1 -1
  20. package/dist/node/carrier.js.map +1 -1
  21. package/dist/node/node-contacts.d.ts.map +1 -1
  22. package/dist/node/node-contacts.js +1 -0
  23. package/dist/node/node-contacts.js.map +1 -1
  24. package/dist/node/node-records.d.ts.map +1 -1
  25. package/dist/node/node-records.js +6 -1
  26. package/dist/node/node-records.js.map +1 -1
  27. package/dist/node/node.d.ts.map +1 -1
  28. package/dist/node/node.js +13 -1
  29. package/dist/node/node.js.map +1 -1
  30. package/dist/node/remote.d.ts.map +1 -1
  31. package/dist/node/remote.js +7 -1
  32. package/dist/node/remote.js.map +1 -1
  33. package/dist/node/space-runtime.d.ts +5 -3
  34. package/dist/node/space-runtime.d.ts.map +1 -1
  35. package/dist/node/space-runtime.js +3 -1
  36. package/dist/node/space-runtime.js.map +1 -1
  37. package/dist/node/types.d.ts +112 -36
  38. package/dist/node/types.d.ts.map +1 -1
  39. package/dist/query/types.d.ts +1 -0
  40. package/dist/query/types.d.ts.map +1 -1
  41. package/dist/query/types.js.map +1 -1
  42. package/dist/records/contract-builder.d.ts +22 -6
  43. package/dist/records/contract-builder.d.ts.map +1 -1
  44. package/dist/records/contract-builder.js.map +1 -1
  45. package/dist/schemas/automations.d.ts +6 -2
  46. package/dist/schemas/automations.d.ts.map +1 -1
  47. package/dist/schemas/automations.js.map +1 -1
  48. package/dist/schemas/connectors.d.ts +4 -3
  49. package/dist/schemas/connectors.d.ts.map +1 -1
  50. package/dist/schemas/connectors.js +4 -3
  51. package/dist/schemas/connectors.js.map +1 -1
  52. package/dist/schemas/library/media.js +1 -1
  53. package/dist/schemas/library/media.js.map +1 -1
  54. package/dist/session/auth.d.ts +7 -3
  55. package/dist/session/auth.d.ts.map +1 -1
  56. package/dist/session/auth.js.map +1 -1
  57. package/dist/storage/blob-store.d.ts +3 -0
  58. package/dist/storage/blob-store.d.ts.map +1 -1
  59. package/dist/types.d.ts +11 -2
  60. package/dist/types.d.ts.map +1 -1
  61. package/dist/types.js.map +1 -1
  62. package/docs/README.md +86 -93
  63. package/docs/actions.md +213 -152
  64. package/docs/agents.md +198 -167
  65. package/docs/automations.md +296 -204
  66. package/docs/blueprints-and-guides.md +405 -311
  67. package/docs/bots.md +208 -134
  68. package/docs/building-an-app.md +74 -163
  69. package/docs/collections.md +248 -328
  70. package/docs/computed.md +112 -89
  71. package/docs/contacts.md +151 -112
  72. package/docs/contracts.md +299 -120
  73. package/docs/direct-messages.md +80 -65
  74. package/docs/inbox.md +138 -93
  75. package/docs/node.md +1072 -996
  76. package/docs/permissions.md +142 -0
  77. package/docs/proposing-collections.md +74 -55
  78. package/docs/query-format.md +150 -126
  79. package/docs/records-and-queries.md +205 -126
  80. package/docs/sign-in.md +496 -418
  81. package/docs/spaces.md +261 -246
  82. package/docs/standard-library.md +473 -526
  83. package/docs/storage.md +325 -348
  84. package/docs/usernames.md +164 -97
  85. package/docs/warrants.md +100 -67
  86. package/package.json +1 -1
@@ -1,39 +1,25 @@
1
1
  # Blueprints and guides
2
2
 
3
- Two standard collections let a space grow new collections without anyone
4
- deploying anything, and say how they are meant to be used.
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
- - A **blueprint** (`std.blueprint`) is collections someone proposes: a title,
7
- and each collection as a full definition. Nothing is defined until someone
8
- who may define collections applies it (`applyBlueprint`).
9
- - A **guide** (`std.guide`) is how some of the space's collections are meant
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: an agent's, whose note grants records only, or
26
- a person's, whose roles hold no `/collection/define`. Both take the same path, and
27
- neither needs to know which they are. Every peer refuses a definition from a
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
- `applyBlueprint` defines each collection the space doesn't have as the
32
- blueprint says, signed by whoever applies it. They need a grant of
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
- - At most 10 collections per blueprint, none of them `sys.*`, none twice, and
64
- none with a `version`: the space decides that when it is applied
65
- (`checkBlueprint`).
66
- - Through `collections_propose`, a standard collection may be given by name
67
- (`"std.event"`): `standardCollections` puts the library's definition in its
68
- place, so it is exactly the library's ([what a `std.*` name means](standard-library.md#what-a-std-name-means)).
69
- - `copyBlueprint` proposes the same blueprint in another space, with `from`
70
- naming where it came from. People there decide for themselves.
71
- - The actions are `collections_propose`, `collections_proposals` and
72
- `collections_apply` ([actions](actions.md)). An agent's node is not offered
73
- `collections_apply`.
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
- _Source: `packages/core/src/schemas/blueprints.ts` (`checkBlueprint`, `proposeCollections`, `applyBlueprint`, `copyBlueprint`), `packages/core/src/schemas/library/collections.ts` (`blueprint`), `packages/core/src/node/actions.ts` (`collections_propose`, `collections_proposals`, `collections_apply`). Tests: `packages/core/tests/records-only.test.ts` ("collections proposed in a blueprint": "an agent proposes, someone who may define applies it, and the space then has the collections", "a person whose role holds no /collection/define proposes the same way, and someone who may applies it", "copying a blueprint into another space proposes it there, and says where it came from", "a proposal may not name the protocol's own collections, a version, or one collection twice")._
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
- each collection is `new`, the `same` as the space has it, or a `change`, with
81
- what it allows worked out from its rules ([describing a collection](#describing-a-collection))
82
- and, for a change, what would be different and which applied blueprints need
83
- the collection as it is (`usedBy`). A person reads that before applying; a
84
- blueprint is `applied` once every collection is the same.
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 space that holds the library's current definition of a standard
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
- _Source: `packages/core/src/schemas/blueprints.ts` (`reviewBlueprint`, `metByLibrary`). Tests: `packages/core/tests/records-only.test.ts` ("a proposal that changes a collection the space has says so, and says how", "a blueprint made against an earlier standard definition is met by the library's current one, not offered as a change back")._
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
- A blueprint is changed by proposing a new one whose `updates` is the key of
98
- the blueprint, in the same space, that it is a new version of.
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
- A blueprint is **superseded** when one that names it in `updates` is applied
105
- (every collection is in the space as it says), or is itself superseded. A
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
- - `applyBlueprint` never applies a superseded blueprint.
109
- - An app should not offer a superseded blueprint to be applied; it is
110
- history, which its proposer or a moderator may delete.
111
- - `updates` must name a blueprint that is in the space; `proposeCollections`
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
- Until its update is applied, the blueprint it names is still the one in use.
115
- Without `updates`, two blueprints that need the same collection differently
116
- each show as a change that undoes the other. So a review names the applied
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
- > **Planned (open question):** with [`compare`](#compatible-definitions), an update's review would list
122
- > its breaks.
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
- _Source: `packages/core/src/schemas/blueprints.ts` (`supersededBlueprints`, `reviewBlueprint`, `proposeCollections`, `applyBlueprint`), `packages/core/src/node/actions.ts` (`collections_propose`, `collections_proposals`). Tests: `packages/core/tests/records-only.test.ts` ("an update replaces the blueprint it names: once applied, the old version is not offered again", "a change to a collection another blueprint uses names it, and warns the agent")._
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 and the rules it keeps. It can't say
129
- "to add an app with its own screen, write one of these, pointing at a
130
- blueprint". An app that has more to say about its collections writes a
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,119 +153,190 @@ exists, and reads one with `records_get` before writing there.
144
153
  }
145
154
  ```
146
155
 
147
- - `writeGuide` defines `std.guide` when the space lacks it, writes the guide,
148
- and rewrites it only when this account wrote it and it says something else.
149
- So an app can call it every time a space opens.
150
- - `guidesOf` gives the space's guides by the collections they are about.
151
- - A guide is what someone in the space wrote. An agent must read it as data
152
- about the collections, never as instructions from the person it works for.
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
- _Source: `packages/core/src/schemas/guides.ts` (`writeGuide`, `guidesOf`), `packages/core/src/schemas/library/collections.ts` (`guide`), `packages/core/src/node/actions.ts` (`collections_list`). Tests: `packages/core/tests/records-only.test.ts` ("collections_list points at the guides written about each collection"), `apps/example/tests/launcher.test.ts` ("the guide agents read is in the space, on the collections it is about")._
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 its people add apps with their own
159
- UI keeps them as records of its own and runs the UI itself. The example app
160
- keeps each as a `launcher.app` record pointing at its blueprint, runs its
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
- **The launcher's order.** The launcher is in one order for everyone in the
167
- space (each record's `position`). The example app opens a space on its
168
- Overview, which lists the apps in that order. A new group starts with Chat,
169
- and so does a new space for two, which the one asking makes.
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
170
192
 
171
193
  A screen reaches the page around it only through `window.minca`, and only for
172
- its app's collections and the people in its space: it lists and writes
173
- records as the person looking, asks what they may do (`can`), gets someone's
174
- picture (`picture`), and asks the page to show a record or a person
175
- (`open`), or the record one of its own links to (`open` with `link`: the
176
- message a file was shared on), which shows it to the person and tells the screen nothing. The bridge never follows one to the space's own records (`sys.*`, `launcher.app`), and opening one answers the same whether or not the record is there; but the page visibly opens a record that is there, for the person, who can see it anyway. What a sealed frame can't do, the page does for it when it asks,
177
- after checking the request: it searches for places and asks where the person
178
- is (`places`), opens http and https pages (`link`), saves text files
179
- (`save`), keeps a few kilobytes per app on the device (`remember`, `recall`),
180
- and reads a picture that one of the app's own records refers to (`file`),
181
- or the whole file (`blob`), taking its type from the record rather than from
182
- the screen.
183
-
184
- **Settings and the network.** An app may ask for `settings`, like an API
185
- key. Someone who may add apps fills them in once, from the open app, for
186
- everyone in the space, and its screen reads them as `minca.settings`; nobody
187
- else is asked. They live on the app's own record, so they stand only as it
188
- does: a new version proposed without values keeps the ones the app has, and a
189
- copy to another space carries none. The origins an app names in `network` are
190
- allowed for everyone once it is added, as a workspace's admin adds an
191
- integration: adding it is the consent. The ready-made Chat asks for a GIPHY
192
- key, and shows its GIF button only once it has one.
193
-
194
- **An app's icon.** A `launcher.app` may carry an `icon`: `{ "path": "M10 10…Z",
195
- "colour": "coral" }`, the data of one SVG path on a 100 × 100 grid and one
196
- of the shapes' colours (cobalt, coral, peach, sage, lilac, ink). The example
197
- app draws it filled, in place of the shape the app would have otherwise, and
198
- only when the path is path data and nothing else (commands, numbers and
199
- separators, at most 4,000 characters), since it comes from other people; the
200
- stored schema can't hold that rule, so the check is where it is drawn. The
201
- guide asks an agent for one when it makes an app. Changing an icon is changing
202
- the app, as any other field is; updating a ready-made app keeps the icon the
203
- space gave it.
204
-
205
- **Opening a record where it belongs.** A `launcher.app` may name, among its
206
- `collections`, the ones it `shows`: the ones whose records it is the place
207
- to open (`shows: ["std.message"]` for a chat). An entry may name a kind of
208
- one too, `collection:kind`, for the records of that collection whose `kind`
209
- field holds it: `std.list:tab` for Bills' tabs, `std.work:book` for a
210
- reading app, or a `kind` in an app's own collection. Lists are folders,
211
- albums and tabs as well as checklists, and each belongs in a different app. Whatever asks the example app to open a record, a screen's
212
- `open` or a link beside a record, goes to the app that shows it, those
213
- naming its kind before those naming only its collection: the one open, if
214
- it does, else the only one, else the one the person picks when asked. So
215
- a Bills tab shared in a chat opens in Bills, a Files category in Files, and
216
- any other list in Lists. That app's
217
- screen is handed the record's key (`minca.shown`, `minca.onShow`, the kit's
218
- `useShown`) to scroll to or open, but only of a collection it shows, which
219
- it could list anyway. That app does learn which of those records the person
220
- opens from elsewhere, which is why only someone who may define collections
221
- adds an app. With no app that shows it, or when that app opens one of its
222
- own (a poll's title in Polls, for its comments), the record opens beside
223
- whatever is open. So the Files app opens a file's message in
224
- the chat, and a chat's file in Files, without either knowing the other. An
225
- app that names a collection in `shows` must do something with what it is
226
- handed. The kit's `<Record>` draws any standard record as one line the same
227
- way in every app, and opens it this way when clicked.
228
-
229
- **Sharing a record into an app.** A screen can't list or read what its app
230
- doesn't name, but a person can hand it one record, as a page gets only the
231
- file a person picks for it. `minca.pick` asks the page to show a finder over
232
- the whole space, and gives the screen the record the person chooses, or
233
- null. The screen may then link one of its records to it with `shares`, like
234
- a message, and anyone's screen reads it back through that link
235
- (`minca.get(key, { link: 'shares' })`), read only. `shares` is the only role
236
- a screen reads through: a file about a diary entry, or a reaction to it,
237
- shares nothing, so a screen reads beyond its collections only records the
238
- person picked, or that someone writing its collections shares (a member, an
239
- agent, another app). That binds the screen, not its author: a member who
240
- wrote a screen can share any record into its collections from their own
241
- node, and the screen reads it. A shared record comes with its files' keys,
242
- though not their bytes. A screen writes
243
- a link only to a record of its own collections, one the person picked for
244
- it, or one the record already has, refused alike whether or not the target
245
- is here (so a link to a record that hasn't arrived yet waits until it has):
246
- a screen never links out on its own, though like anything it reads, it can
247
- copy what was shared into its own records. A screen may ask to pick as often
248
- as it likes, and start the search from its own text; what it gets is still
249
- only what the person chooses, in a space they can read anyway: Enter takes
250
- the top match only once the person has typed. A chat
251
- shares a poll without being able to read polls; `/` typed into an empty
252
- message, or its `/` button, picks one; so does a comment box (the kit's
253
- `useShare`).
254
-
255
- A screen also sends live messages, kept nowhere, to the other devices that
256
- have the same app open in the space (`live.send`, `live.on`): for cursors,
257
- typing, who is here, or a game. Each goes as a live message of the space
258
- ([node](node.md#live-messages-and-status)) whose payload names the app by its
259
- `launcher.app` key, and a screen hears only those naming its own app:
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:
260
340
 
261
341
  ```json
262
342
  {
@@ -266,74 +346,77 @@ typing, who is here, or a game. Each goes as a live message of the space
266
346
  }
267
347
  ```
268
348
 
269
- A screen is handed `{ from, device, data, viaAgent }`, `from` being the
270
- sender's account as the node proved it; a message from a peer with no account
271
- is not passed on. One screen may send a burst of 30, then 15 a second, below
272
- what a peer takes from another across everything, so a busy screen leaves
273
- room for calls and the rest. An edited copy of an app is another
274
- `launcher.app` record, so its screens don't hear the original's.
275
-
276
- In front of every screen the example app also writes `@minca/ui`
277
- (`packages/ui`): Preact with htm, hooks that keep records current, people's
278
- faces, and Minca's look, so a screen is mostly what it is about. It isn't
279
- part of the screen, so it doesn't count toward the 48 KB a screen may be.
280
-
281
- The ready-made apps are screens too, written the same way. Adding one
282
- defines its collections and writes a copy of it, naming where it came from
283
- (`template: "kanban"`), and from then on the space changes its copy like any
284
- 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
285
359
 
286
- _Source: `apps/example/src/components/apps/launcher.ts` (`addTemplate`, `iconOf`, `showsRecord`, `saveSettings`, `settingsOf`), `apps/example/src/components/apps/entries.ts` (`addChat`), `apps/example/src/contacts.ts` (`withChat`), `apps/example/src/components/apps/screens.ts`, `apps/example/src/components/apps/ScreenFrame.tsx`, `apps/example/src/components/apps/AppSettings.tsx`, `apps/example/src/components/apps/templates/`, `apps/example/public/screen.html`, `packages/ui/src/frame/`, `packages/ui/src/guide.ts`. Tests: `apps/example/tests/launcher.test.ts` ("an app's own icon is drawn only as path data in a shape colour, and outlives an update of its ready-made app", "adding a ready-made app copies it into the space once, with its collections and first records", "settings filled in once stand for everyone, survive a new version of the app, and stay in their space"), `apps/example/tests/screens.test.ts` ("an app's settings come with the screen, and the screen can't change them", "a record opens in the apps that name it most closely: its kind, then its collection", "a screen checks, shows faces and opens things only within its app and its space", "what the page does for a screen, it does only as asked properly", "a screen can’t point a link out of its app, so it can’t probe for keys or reach what no one shared", "a record someone shared is read through the link to it, and only through that", "a screen links out only to what the person picked for it, and is handed what they picked", "the space’s own records are never picked for a screen", "a screen hears the same app's screens on other devices, as who sent it, and no other app's")._
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.
287
369
 
288
370
  ## Describing a collection
289
371
 
290
- A definition's `title` and `description` are its author's words and may say
291
- anything. What a collection actually allows is worked out from its rules, as
292
- fixed sentences, so a person deciding whether to add a collection reads what
293
- 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.
294
376
 
295
- `describeCollection(definition)` returns, in this order:
377
+ It returns, in this order:
296
378
 
297
379
  1. `final`: "Nobody can change or remove a vote once it is added."
298
380
  2. `onePer`: "One vote per person per poll — adding another changes the
299
- first." (with `@author`); otherwise "… — anyone adding another replaces the
300
- 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."
301
383
  3. `fixed`: "Once a poll is added, its “options” can't be changed."
302
- 4. Each condition of the contract (`contract.check`), in its own words: "Every change is checked: “…”".
303
- 5. One per declared link: "Each vote points at one thing: a poll (“about”)." or
304
- "A comment can point at anything in the space (“about”)."
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”)."
305
388
  6. `history: "all"`: "Every earlier version of a … is kept."
306
389
 
307
- Who may add, change or remove records is not the definition's to say: it is
308
- the space's grants ([spec 03 §2](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)),
309
- 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.
310
392
 
311
- Nouns come from `title`, else the last segment of `name`; field labels from
312
- the schema's `title`s, else the field name in words. A rule the describer does
313
- 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.
314
395
 
315
- The wording can change; that every rule produces a sentence doesn't.
316
-
317
- _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.
318
398
 
319
399
  ## Compatible definitions
320
400
 
321
- An app decides it can open a space by finding a collection with the right
322
- **name**. Chat opens any `std.message`, whatever its fields and rules. And a space whose definition is a little older than the
323
- app's (a `std.message` or `std.comment` without the `shares` link) stays that way, because the
324
- library skips a collection the space already has. Whether an app can use a
325
- definition it did not write is a question for the app, not for peers: a peer
326
- stores and judges every record the same way whatever the answer.
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.
327
410
 
328
- > **Planned.** Not built. Issues:
411
+ > **Planned.** Not built yet:
329
412
  > [#11](https://github.com/leifriksheim/minca/issues/11),
330
413
  > [#12](https://github.com/leifriksheim/minca/issues/12). The parts peers
331
- > would check, content-addressed definitions and additive-only changes, are
332
- > planned in [spec 02 §6.5](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
414
+ > would check are planned in
415
+ > [spec 02 §6.5](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
333
416
 
334
417
  ### The check: `compare(held, wanted)`
335
418
 
336
- `held` is the definition the space has; `wanted` the one the app was built
419
+ `held` is the definition the space has. `wanted` is the one the app was built
337
420
  with. The result is two lists of breaks, each a path and a plain sentence:
338
421
 
339
422
  ```ts
@@ -347,66 +430,76 @@ interface Break {
347
430
  } // 'rules.onePer', "Anyone can react twice with one emoji here; this app assumes once"
348
431
  ```
349
432
 
350
- An app that only shows records needs `read` empty; one that writes needs both.
351
- Anything the checker cannot decide is a break.
352
-
353
- - **Fields.** Reading needs every body the space accepts to be one the app
354
- accepts (held ⊆ wanted); writing needs wanted ⊆ held. Over the schema
355
- keywords a definition may use ([spec 02 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md))
356
- this is a walk of both schemas: `type` sets contained (`integer` inside
357
- `number`); a field one side relies on is `required` on the other; numeric
358
- and length ranges contained; `enum`, `const` and `oneOf` value sets
359
- contained; recurse into `properties` and `items`. `title`, `description`,
360
- `x-choicesFrom` and every other `x-*` annotation are ignored. A field only one side mentions is ignored,
361
- unless that side requires it or closes the schema
362
- (`additionalProperties: false`).
363
- - **Links.** A link role the app uses is declared in the space; where it may
364
- point is contained (`["app.poll"]` is inside `"*"` for reading, not for
365
- writing); `"one"` is inside `"many"`. Roles the app does not know are
366
- ignored when reading.
367
- - **Rules: never looser.** Stricter rules are never a safety problem (at worst
368
- the app cannot write, which `can` already reports), so rules are checked one
369
- way: the space's rule must be an **attenuation** of the app's, as in UCAN.
370
- `onePer`: the space promises at least the uniqueness the app relies on
371
- (fewer parts is a stronger promise). `fixed`: the space keeps at least the
372
- fields the app expects fixed. `final`: an app that relies on it needs it.
373
- Who may write is the space's grants, not the definition's, and is not
374
- compared.
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.
375
465
 
376
466
  ### What uses it
377
467
 
378
468
  1. **Apps open by compatibility**, not by name. A collection that exists but
379
- is not compatible is shown with its breaks instead of opened.
469
+ isn't compatible is shown with its breaks instead of opened.
380
470
  2. **Harmless updates apply themselves.** When the library's definition is
381
- newer and `compare(held, library)` finds no break in either direction and
382
- the rules are no looser, a writer allowed to change the definition writes
383
- it at the next version without asking. (Adding `shares` to an older
384
- `std.message` is this case.)
385
- 3. **Anything else asks a person.** The blueprint review shows the breaks ("a poll's
386
- options can now be changed after it is added"), not only "changes the
387
- rules".
388
-
389
- An app should not define a `std.*` name that is not compatible with the
390
- standard library's. Peers don't refuse one on arrival (refusing depends on
391
- what each peer knows, and would leave peers disagreeing), so an app treats an
392
- incompatible `std.message` as not a message.
393
-
394
- Built so far: `collections_propose` refuses a `std.*` definition that is not exactly
395
- the library's ([what a `std.*` name means](standard-library.md#what-a-std-name-means)).
396
- Typed handles in the library (`node.use(space, Poll)`) would run the same check.
397
-
398
- The plans differ in one place: this check stays on the app's side and lets a
399
- person approve a breaking change, while #12 makes "additive" a rule peers
400
- enforce. `compare` is the check "additive" needs, in both directions, and
401
- identical content-addressed definitions (#11) are trivially compatible, so it
402
- would run only on a real change.
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.
403
495
 
404
496
  ### What "additive" means
405
497
 
406
- Spec 02 §6.5 plans the rule; this is why it draws the line where it does.
407
- Changes are classified as **oasdiff** classifies OpenAPI changes, treating a
408
- collection's schema as a request body and a response body at once: apps write
409
- records (a request) and apps read them (a response).
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.
410
503
 
411
504
  - **As a request**, a change must not **tighten**: a new required field, a
412
505
  narrower type, a smaller range or length, fewer `enum`/`const`/`oneOf`
@@ -414,46 +507,47 @@ records (a request) and apps read them (a response).
414
507
  longer write.
415
508
  - **As a response**, a change must not **loosen**: a field no longer
416
509
  required, a wider type, a larger range, more `enum` values, a link that may
417
- point at more. Apps on the old definition would meet records they misread
418
- (a status they don't switch on).
510
+ point at more. Apps on the old definition would meet records they misread,
511
+ like a status they don't handle.
419
512
 
420
513
  A change under the same name is additive when oasdiff would report no
421
- error-level break for it on either side. Findings oasdiff reports as warnings
422
- or information stay that. The catalogue of checks is oasdiff's, mapped onto
423
- the schema keywords and links; a keyword it has no check for is a break.
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.
424
517
 
425
- Rules are not shape. `onePer`, `fixed` and `final` are the space's
426
- governance, as its grants are: a space may tighten them under the
427
- same name (at worst an app can't write, which `can` reports), and may never
428
- loosen them past what an app relies on ("never looser", above).
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.
429
522
 
430
523
  ### Open questions
431
524
 
432
525
  - **Rules only apply from now on.** A space that was loose last month and
433
526
  strict today holds records written under the loose rules. Either `compare`
434
- looks at every definition the collection has had, or "compatible" is stated
435
- to describe records written from now on. Probably the second.
436
- - **Translating instead of refusing** (lenses between versions, as in
437
- Cambria), so an app can read a definition it is not compatible with. Later.
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.
438
532
 
439
533
  ## Planned: meaning-level hints
440
534
 
441
535
  A definition says what a record may hold and the rules it keeps, not what it
442
- means to a screen. Views derived from definitions (the blueprint review, an
443
- app's collection views, made apps without a screen of their own) have to guess
444
- which field is the title or that votes are shown as counts. The plan adds
445
- 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:
446
539
 
447
540
  - which field is the record's **title**;
448
- - **tallies**: "show as a count" of records linking here, the way
449
- `x-choicesFrom` already makes vote-style counts possible;
450
- - values **worked out on read**: "voting closes Friday", "who hasn't
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
451
544
  answered". Each reader computes them from the records and its own clock, so
452
545
  nothing has to run anywhere.
453
546
 
454
- A field's kind (a person) is already its `x-kind` ([collections](collections.md#schemas)).
455
- Like `x-choicesFrom`, hints are display only and never checked when
456
- validating, and [`compare`](#compatible-definitions) ignores them. A hint
457
- about one field is an `x-*` keyword on it; one about the whole record goes
458
- in a top-level definition member, which today's peers ignore when they
459
- don't know it ([spec 02 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)). Added when a derived view falls short. _Open:_ the format.
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.