@minca/core 0.1.16 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/README.md +10 -9
  2. package/dist/elements/auth-styles.d.ts +1 -1
  3. package/dist/elements/auth-styles.d.ts.map +1 -1
  4. package/dist/elements/auth-styles.js +14 -5
  5. package/dist/elements/auth-styles.js.map +1 -1
  6. package/dist/elements/minca-auth.d.ts.map +1 -1
  7. package/dist/elements/minca-auth.js +18 -15
  8. package/dist/elements/minca-auth.js.map +1 -1
  9. package/dist/files/space-files.d.ts +2 -2
  10. package/dist/files/space-files.d.ts.map +1 -1
  11. package/dist/files/space-files.js +7 -5
  12. package/dist/files/space-files.js.map +1 -1
  13. package/dist/inbox/names.d.ts +1 -1
  14. package/dist/inbox/names.js +1 -1
  15. package/dist/index.d.ts +2 -0
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +2 -0
  18. package/dist/index.js.map +1 -1
  19. package/dist/network/ws-transport.d.ts.map +1 -1
  20. package/dist/network/ws-transport.js +3 -0
  21. package/dist/network/ws-transport.js.map +1 -1
  22. package/dist/node/actions.d.ts +5 -0
  23. package/dist/node/actions.d.ts.map +1 -1
  24. package/dist/node/actions.js +39 -20
  25. package/dist/node/actions.js.map +1 -1
  26. package/dist/node/api.d.ts +2 -0
  27. package/dist/node/api.d.ts.map +1 -1
  28. package/dist/node/api.js +2 -0
  29. package/dist/node/api.js.map +1 -1
  30. package/dist/node/carrier.js +1 -1
  31. package/dist/node/carrier.js.map +1 -1
  32. package/dist/node/node-carriers.d.ts.map +1 -1
  33. package/dist/node/node-carriers.js +6 -1
  34. package/dist/node/node-carriers.js.map +1 -1
  35. package/dist/node/node-contacts.d.ts.map +1 -1
  36. package/dist/node/node-contacts.js +1 -0
  37. package/dist/node/node-contacts.js.map +1 -1
  38. package/dist/node/node-hosting.d.ts.map +1 -1
  39. package/dist/node/node-hosting.js +11 -4
  40. package/dist/node/node-hosting.js.map +1 -1
  41. package/dist/node/node-records.d.ts.map +1 -1
  42. package/dist/node/node-records.js +6 -1
  43. package/dist/node/node-records.js.map +1 -1
  44. package/dist/node/node.d.ts.map +1 -1
  45. package/dist/node/node.js +14 -1
  46. package/dist/node/node.js.map +1 -1
  47. package/dist/node/remote.d.ts.map +1 -1
  48. package/dist/node/remote.js +7 -1
  49. package/dist/node/remote.js.map +1 -1
  50. package/dist/node/space-holding.d.ts +7 -3
  51. package/dist/node/space-holding.d.ts.map +1 -1
  52. package/dist/node/space-holding.js +90 -18
  53. package/dist/node/space-holding.js.map +1 -1
  54. package/dist/node/space-peers.d.ts.map +1 -1
  55. package/dist/node/space-peers.js +58 -24
  56. package/dist/node/space-peers.js.map +1 -1
  57. package/dist/node/space-runtime.d.ts +11 -3
  58. package/dist/node/space-runtime.d.ts.map +1 -1
  59. package/dist/node/space-runtime.js +22 -1
  60. package/dist/node/space-runtime.js.map +1 -1
  61. package/dist/node/space-writing.d.ts +2 -0
  62. package/dist/node/space-writing.d.ts.map +1 -1
  63. package/dist/node/space-writing.js +2 -0
  64. package/dist/node/space-writing.js.map +1 -1
  65. package/dist/node/types.d.ts +130 -36
  66. package/dist/node/types.d.ts.map +1 -1
  67. package/dist/query/types.d.ts +1 -0
  68. package/dist/query/types.d.ts.map +1 -1
  69. package/dist/query/types.js.map +1 -1
  70. package/dist/records/contract-builder.d.ts +22 -6
  71. package/dist/records/contract-builder.d.ts.map +1 -1
  72. package/dist/records/contract-builder.js.map +1 -1
  73. package/dist/schemas/automations.d.ts +6 -2
  74. package/dist/schemas/automations.d.ts.map +1 -1
  75. package/dist/schemas/automations.js.map +1 -1
  76. package/dist/schemas/connectors.d.ts +4 -3
  77. package/dist/schemas/connectors.d.ts.map +1 -1
  78. package/dist/schemas/connectors.js +4 -3
  79. package/dist/schemas/connectors.js.map +1 -1
  80. package/dist/schemas/library/media.js +1 -1
  81. package/dist/schemas/library/media.js.map +1 -1
  82. package/dist/schemas/library/social.d.ts +258 -0
  83. package/dist/schemas/library/social.d.ts.map +1 -1
  84. package/dist/schemas/library/social.js +28 -1
  85. package/dist/schemas/library/social.js.map +1 -1
  86. package/dist/session/auth.d.ts +7 -3
  87. package/dist/session/auth.d.ts.map +1 -1
  88. package/dist/session/auth.js.map +1 -1
  89. package/dist/session/hosting.d.ts.map +1 -1
  90. package/dist/session/hosting.js +8 -2
  91. package/dist/session/hosting.js.map +1 -1
  92. package/dist/space/presets.d.ts +2 -2
  93. package/dist/space/presets.d.ts.map +1 -1
  94. package/dist/space/presets.js +3 -2
  95. package/dist/space/presets.js.map +1 -1
  96. package/dist/storage/blob-store.d.ts +3 -0
  97. package/dist/storage/blob-store.d.ts.map +1 -1
  98. package/dist/types.d.ts +11 -2
  99. package/dist/types.d.ts.map +1 -1
  100. package/dist/types.js.map +1 -1
  101. package/docs/README.md +86 -93
  102. package/docs/actions.md +212 -144
  103. package/docs/agents.md +198 -155
  104. package/docs/automations.md +296 -204
  105. package/docs/blueprints-and-guides.md +405 -295
  106. package/docs/bots.md +208 -134
  107. package/docs/building-an-app.md +74 -163
  108. package/docs/collections.md +248 -328
  109. package/docs/computed.md +112 -89
  110. package/docs/contacts.md +151 -112
  111. package/docs/contracts.md +299 -120
  112. package/docs/direct-messages.md +80 -61
  113. package/docs/inbox.md +138 -93
  114. package/docs/node.md +1072 -972
  115. package/docs/permissions.md +142 -0
  116. package/docs/proposing-collections.md +74 -55
  117. package/docs/query-format.md +150 -126
  118. package/docs/records-and-queries.md +205 -126
  119. package/docs/sign-in.md +496 -418
  120. package/docs/spaces.md +261 -245
  121. package/docs/standard-library.md +473 -504
  122. package/docs/storage.md +325 -348
  123. package/docs/usernames.md +164 -97
  124. package/docs/warrants.md +100 -67
  125. package/package.json +1 -2
@@ -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,103 +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
- **Where a space opens.** The launcher is in one order for everyone in the
167
- space (each record's `position`). The example app opens a space into the
168
- first app on it, so a group chooses where it opens by moving an app to the
169
- top. A new group starts with Chat, and so does a new space for two, which
170
- the one asking makes, so both people open it into a conversation.
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: it lists and writes
174
- records as the person looking, asks what they may do (`can`), gets someone's
175
- picture (`picture`), and asks the page to show a record or a person
176
- (`open`), or the record one of its own links to (`open` with `link`: the
177
- 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,
178
- after checking the request: it searches for places and asks where the person
179
- is (`places`), opens http and https pages (`link`), saves text files
180
- (`save`), keeps a few kilobytes per app on the device (`remember`, `recall`),
181
- and reads a picture that one of the app's own records refers to (`file`),
182
- or the whole file (`blob`), taking its type from the record rather than from
183
- the screen.
184
-
185
- **Settings and the network.** An app may ask for `settings`, like an API
186
- key. Someone who may add apps fills them in once, from the open app, for
187
- everyone in the space, and its screen reads them as `minca.settings`; nobody
188
- else is asked. They live on the app's own record, so they stand only as it
189
- does: a new version proposed without values keeps the ones the app has, and a
190
- copy to another space carries none. The origins an app names in `network` are
191
- allowed for everyone once it is added, as a workspace's admin adds an
192
- integration: adding it is the consent. The ready-made Chat asks for a GIPHY
193
- key, and shows its GIF button only once it has one.
194
-
195
- **Opening a record where it belongs.** A `launcher.app` may name, among its
196
- `collections`, the ones it `shows`: the ones whose records it is the place
197
- to open (`shows: ["std.message"]` for a chat). Whatever asks the example app
198
- to open a record, a screen's `open` or a link beside a record, goes to the
199
- app that shows that record's collection: the one open, if it does, else the
200
- only one, else the one the person picks when asked, and that app's
201
- screen is handed the record's key (`minca.shown`, `minca.onShow`, the kit's
202
- `useShown`) to scroll to or open, but only of a collection it shows, which
203
- it could list anyway. That app does learn which of those records the person
204
- opens from elsewhere, which is why only someone who may define collections
205
- adds an app. With no app that shows it, or when that app opens one of its
206
- own (a poll's title in Polls, for its comments), the record opens beside
207
- whatever is open. So the Files app opens a file's message in
208
- the chat, and a chat's file in Files, without either knowing the other. An
209
- app that names a collection in `shows` must do something with what it is
210
- handed. The kit's `<Record>` draws any standard record as one line the same
211
- way in every app, and opens it this way when clicked.
212
-
213
- **Sharing a record into an app.** A screen can't list or read what its app
214
- doesn't name, but a person can hand it one record, as a page gets only the
215
- file a person picks for it. `minca.pick` asks the page to show a finder over
216
- the whole space, and gives the screen the record the person chooses, or
217
- null. The screen may then link one of its records to it with `shares`, like
218
- a message, and anyone's screen reads it back through that link
219
- (`minca.get(key, { link: 'shares' })`), read only. `shares` is the only role
220
- a screen reads through: a file about a diary entry, or a reaction to it,
221
- shares nothing, so a screen reads beyond its collections only records the
222
- person picked, or that someone writing its collections shares (a member, an
223
- agent, another app). That binds the screen, not its author: a member who
224
- wrote a screen can share any record into its collections from their own
225
- node, and the screen reads it. A shared record comes with its files' keys,
226
- though not their bytes. A screen writes
227
- a link only to a record of its own collections, one the person picked for
228
- it, or one the record already has, refused alike whether or not the target
229
- is here (so a link to a record that hasn't arrived yet waits until it has):
230
- a screen never links out on its own, though like anything it reads, it can
231
- copy what was shared into its own records. A screen may ask to pick as often
232
- as it likes, and start the search from its own text; what it gets is still
233
- only what the person chooses, in a space they can read anyway: Enter takes
234
- the top match only once the person has typed. A chat
235
- shares a poll without being able to read polls; `/` typed into an empty
236
- message, or its `/` button, picks one; so does a comment box (the kit's
237
- `useShare`).
238
-
239
- A screen also sends live messages, kept nowhere, to the other devices that
240
- have the same app open in the space (`live.send`, `live.on`): for cursors,
241
- typing, who is here, or a game. Each goes as a live message of the space
242
- ([node](node.md#live-messages-and-status)) whose payload names the app by its
243
- `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:
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 is handed `{ from, device, data, viaAgent }`, `from` being the
254
- sender's account as the node proved it; a message from a peer with no account
255
- is not passed on. One screen may send a burst of 30, then 15 a second, below
256
- what a peer takes from another across everything, so a busy screen leaves
257
- room for calls and the rest. An edited copy of an app is another
258
- `launcher.app` record, so its screens don't hear the original's.
259
-
260
- In front of every screen the example app also writes `@minca/ui`
261
- (`packages/ui`): Preact with htm, hooks that keep records current, people's
262
- faces, and Minca's look, so a screen is mostly what it is about. It isn't
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
- _Source: `apps/example/src/components/apps/launcher.ts` (`addTemplate`, `firstApp`, `saveSettings`, `settingsOf`), `apps/example/src/components/apps/entries.ts` (`landingApp`, `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` ("a space opens with the first app on its launcher, the same for everyone in it, and moving one changes it", "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 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.
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. What a collection actually allows is worked out from its rules, as
276
- fixed sentences, so a person deciding whether to add a collection reads what
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
- `describeCollection(definition)` returns, in this order:
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`); otherwise "… — anyone adding another replaces the
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: "Every change is checked: “…”".
287
- 5. One per declared link: "Each vote points at one thing: a poll (“about”)." or
288
- "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”)."
289
388
  6. `history: "all"`: "Every earlier version of a … is kept."
290
389
 
291
- Who may add, change or remove records is not the definition's to say: it is
292
- the space's grants ([spec 03 §2](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)),
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
- Nouns come from `title`, else the last segment of `name`; field labels from
296
- the schema's `title`s, else the field name in words. A rule the describer does
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
- The wording can change; that every rule produces a sentence doesn't.
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
- An app decides it can open a space by finding a collection with the right
306
- **name**. Chat opens any `std.message`, whatever its fields and rules. And a space whose definition is a little older than the
307
- app's (a `std.message` or `std.comment` without the `shares` link) stays that way, because the
308
- library skips a collection the space already has. Whether an app can use a
309
- definition it did not write is a question for the app, not for peers: a peer
310
- 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.
311
410
 
312
- > **Planned.** Not built. Issues:
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, content-addressed definitions and additive-only changes, are
316
- > 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).
317
416
 
318
417
  ### The check: `compare(held, wanted)`
319
418
 
320
- `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
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; one that writes needs both.
335
- Anything the checker cannot decide is a break.
336
-
337
- - **Fields.** Reading needs every body the space accepts to be one the app
338
- accepts (held ⊆ wanted); writing needs wanted ⊆ held. Over the schema
339
- keywords a definition may use ([spec 02 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md))
340
- this is a walk of both schemas: `type` sets contained (`integer` inside
341
- `number`); a field one side relies on is `required` on the other; numeric
342
- and length ranges contained; `enum`, `const` and `oneOf` value sets
343
- contained; recurse into `properties` and `items`. `title`, `description`,
344
- `x-choicesFrom` and every other `x-*` annotation are ignored. A field only one side mentions is ignored,
345
- unless that side requires it or closes the schema
346
- (`additionalProperties: false`).
347
- - **Links.** A link role the app uses is declared in the space; where it may
348
- point is contained (`["app.poll"]` is inside `"*"` for reading, not for
349
- writing); `"one"` is inside `"many"`. Roles the app does not know are
350
- ignored when reading.
351
- - **Rules: never looser.** Stricter rules are never a safety problem (at worst
352
- the app cannot write, which `can` already reports), so rules are checked one
353
- way: the space's rule must be an **attenuation** of the app's, as in UCAN.
354
- `onePer`: the space promises at least the uniqueness the app relies on
355
- (fewer parts is a stronger promise). `fixed`: the space keeps at least the
356
- fields the app expects fixed. `final`: an app that relies on it needs it.
357
- Who may write is the space's grants, not the definition's, and is not
358
- 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.
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
- is not compatible is shown with its breaks instead of opened.
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 and `compare(held, library)` finds no break in either direction and
366
- the rules are no looser, a writer allowed to change the definition writes
367
- it at the next version without asking. (Adding `shares` to an older
368
- `std.message` is this case.)
369
- 3. **Anything else asks a person.** The blueprint review shows the breaks ("a poll's
370
- options can now be changed after it is added"), not only "changes the
371
- rules".
372
-
373
- An app should not define a `std.*` name that is not compatible with the
374
- standard library's. Peers don't refuse one on arrival (refusing depends on
375
- what each peer knows, and would leave peers disagreeing), so an app treats an
376
- incompatible `std.message` as not a message.
377
-
378
- Built so far: `collections_propose` refuses a `std.*` definition that is not exactly
379
- the library's ([what a `std.*` name means](standard-library.md#what-a-std-name-means)).
380
- Typed handles in the library (`node.use(space, Poll)`) would run the same check.
381
-
382
- The plans differ in one place: this check stays on the app's side and lets a
383
- person approve a breaking change, while #12 makes "additive" a rule peers
384
- enforce. `compare` is the check "additive" needs, in both directions, and
385
- identical content-addressed definitions (#11) are trivially compatible, so it
386
- 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.
387
495
 
388
496
  ### What "additive" means
389
497
 
390
- Spec 02 §6.5 plans the rule; this is why it draws the line where it does.
391
- Changes are classified as **oasdiff** classifies OpenAPI changes, treating a
392
- collection's schema as a request body and a response body at once: apps write
393
- 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.
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
- (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.
403
512
 
404
513
  A change under the same name is additive when oasdiff would report no
405
- error-level break for it on either side. Findings oasdiff reports as warnings
406
- or information stay that. The catalogue of checks is oasdiff's, mapped onto
407
- 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.
408
517
 
409
- Rules are not shape. `onePer`, `fixed` and `final` are the space's
410
- governance, as its grants are: a space may tighten them under the
411
- same name (at worst an app can't write, which `can` reports), and may never
412
- 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.
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" is stated
419
- to describe records written from now on. Probably the second.
420
- - **Translating instead of refusing** (lenses between versions, as in
421
- 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.
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 derived from definitions (the blueprint review, an
427
- app's collection views, made apps without a screen of their own) have to guess
428
- which field is the title or that votes are shown as counts. The plan adds
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**: "show as a count" of records linking here, the way
433
- `x-choicesFrom` already makes vote-style counts possible;
434
- - 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
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 (a person) is already its `x-kind` ([collections](collections.md#schemas)).
439
- Like `x-choicesFrom`, hints are display only and never checked when
440
- validating, and [`compare`](#compatible-definitions) ignores them. A hint
441
- about one field is an `x-*` keyword on it; one about the whole record goes
442
- in a top-level definition member, which today's peers ignore when they
443
- 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.