@minca/core 0.1.17 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) 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 +3 -1
  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/index.d.ts +1 -1
  22. package/dist/node/index.d.ts.map +1 -1
  23. package/dist/node/node-contacts.d.ts.map +1 -1
  24. package/dist/node/node-contacts.js +1 -0
  25. package/dist/node/node-contacts.js.map +1 -1
  26. package/dist/node/node-records.d.ts.map +1 -1
  27. package/dist/node/node-records.js +6 -1
  28. package/dist/node/node-records.js.map +1 -1
  29. package/dist/node/node.d.ts.map +1 -1
  30. package/dist/node/node.js +13 -1
  31. package/dist/node/node.js.map +1 -1
  32. package/dist/node/remote.d.ts.map +1 -1
  33. package/dist/node/remote.js +7 -1
  34. package/dist/node/remote.js.map +1 -1
  35. package/dist/node/space-runtime.d.ts +5 -3
  36. package/dist/node/space-runtime.d.ts.map +1 -1
  37. package/dist/node/space-runtime.js +3 -1
  38. package/dist/node/space-runtime.js.map +1 -1
  39. package/dist/node/types.d.ts +112 -36
  40. package/dist/node/types.d.ts.map +1 -1
  41. package/dist/node/watch-notifications.d.ts +6 -0
  42. package/dist/node/watch-notifications.d.ts.map +1 -1
  43. package/dist/node/watch-notifications.js +47 -9
  44. package/dist/node/watch-notifications.js.map +1 -1
  45. package/dist/query/types.d.ts +1 -0
  46. package/dist/query/types.d.ts.map +1 -1
  47. package/dist/query/types.js.map +1 -1
  48. package/dist/records/contract-builder.d.ts +22 -6
  49. package/dist/records/contract-builder.d.ts.map +1 -1
  50. package/dist/records/contract-builder.js.map +1 -1
  51. package/dist/schemas/automations.d.ts +6 -2
  52. package/dist/schemas/automations.d.ts.map +1 -1
  53. package/dist/schemas/automations.js.map +1 -1
  54. package/dist/schemas/connectors.d.ts +4 -3
  55. package/dist/schemas/connectors.d.ts.map +1 -1
  56. package/dist/schemas/connectors.js +4 -3
  57. package/dist/schemas/connectors.js.map +1 -1
  58. package/dist/schemas/library/media.js +1 -1
  59. package/dist/schemas/library/media.js.map +1 -1
  60. package/dist/session/account-hint.d.ts +2 -2
  61. package/dist/session/account-hint.d.ts.map +1 -1
  62. package/dist/session/account-hint.js +3 -3
  63. package/dist/session/account-hint.js.map +1 -1
  64. package/dist/session/auth.d.ts +7 -3
  65. package/dist/session/auth.d.ts.map +1 -1
  66. package/dist/session/auth.js.map +1 -1
  67. package/dist/session/connection.d.ts +18 -0
  68. package/dist/session/connection.d.ts.map +1 -1
  69. package/dist/session/connection.js +11 -0
  70. package/dist/session/connection.js.map +1 -1
  71. package/dist/session/index.d.ts +2 -2
  72. package/dist/session/index.d.ts.map +1 -1
  73. package/dist/session/index.js +2 -2
  74. package/dist/session/index.js.map +1 -1
  75. package/dist/storage/blob-store.d.ts +3 -0
  76. package/dist/storage/blob-store.d.ts.map +1 -1
  77. package/dist/types.d.ts +11 -2
  78. package/dist/types.d.ts.map +1 -1
  79. package/dist/types.js.map +1 -1
  80. package/docs/README.md +86 -93
  81. package/docs/actions.md +213 -152
  82. package/docs/agents.md +198 -167
  83. package/docs/automations.md +296 -204
  84. package/docs/blueprints-and-guides.md +405 -311
  85. package/docs/bots.md +208 -134
  86. package/docs/building-an-app.md +86 -159
  87. package/docs/collections.md +248 -328
  88. package/docs/computed.md +112 -89
  89. package/docs/contacts.md +151 -112
  90. package/docs/contracts.md +299 -120
  91. package/docs/direct-messages.md +80 -65
  92. package/docs/inbox.md +138 -93
  93. package/docs/node.md +1081 -996
  94. package/docs/permissions.md +142 -0
  95. package/docs/proposing-collections.md +74 -55
  96. package/docs/query-format.md +150 -126
  97. package/docs/records-and-queries.md +205 -126
  98. package/docs/sign-in.md +487 -416
  99. package/docs/spaces.md +261 -246
  100. package/docs/standard-library.md +487 -526
  101. package/docs/storage.md +325 -348
  102. package/docs/usernames.md +164 -97
  103. package/docs/warrants.md +100 -67
  104. package/package.json +1 -6
  105. package/dist/elements/auth-styles.d.ts +0 -18
  106. package/dist/elements/auth-styles.d.ts.map +0 -1
  107. package/dist/elements/auth-styles.js +0 -206
  108. package/dist/elements/auth-styles.js.map +0 -1
  109. package/dist/elements/dom.d.ts +0 -29
  110. package/dist/elements/dom.d.ts.map +0 -1
  111. package/dist/elements/dom.js +0 -91
  112. package/dist/elements/dom.js.map +0 -1
  113. package/dist/elements/index.d.ts +0 -13
  114. package/dist/elements/index.d.ts.map +0 -1
  115. package/dist/elements/index.js +0 -11
  116. package/dist/elements/index.js.map +0 -1
  117. package/dist/elements/minca-auth.d.ts +0 -55
  118. package/dist/elements/minca-auth.d.ts.map +0 -1
  119. package/dist/elements/minca-auth.js +0 -768
  120. package/dist/elements/minca-auth.js.map +0 -1
@@ -1,572 +1,533 @@
1
1
  # The standard library
2
2
 
3
- > Not protocol. This page describes the reference library, and another
4
- > implementation may do it differently and still interoperate. What peers must
5
- > agree on is in the [spec](https://github.com/leifriksheim/minca/blob/main/spec/README.md).
6
-
7
- An optional library of ordinary definitions (`@minca/core/schemas`),
8
- broad enough that most apps need no definitions of their own. The protocol
9
- knows none of them; a space learns one when someone defines it there. All are
10
- `version` 1 when first defined. They are drawn from atproto lexicons, Nostr
11
- NIPs, JSContact (RFC 9553), JSCalendar (RFC 8984) and schema.org; issue
3
+ The standard library is a set of ready-made collections for the things most
4
+ apps keep: messages, events, tasks, files, reactions. When your app keeps one
5
+ of those, use the standard one. Every other app that uses it reads your
6
+ records, and you read theirs.
7
+
8
+ ```ts
9
+ import type { NodeRecord } from '@minca/core';
10
+ declare const post: NodeRecord;
11
+ // ---cut---
12
+ import { reaction, comment, useSchemas } from '@minca/core/schemas';
13
+
14
+ await useSchemas(node, space.id, [reaction, comment]);
15
+ await node.records.put(
16
+ space.id,
17
+ reaction,
18
+ { emoji: '👍' },
19
+ {
20
+ links: [{ rel: 'about', to: post.key }],
21
+ },
22
+ );
23
+ ```
24
+
25
+ `useSchemas` defines the ones the space doesn't know yet and leaves the rest
26
+ alone, so you can call it every time a space opens.
27
+
28
+ The definitions are ordinary collections. The protocol knows none of them.
29
+ They are drawn from atproto lexicons, Nostr NIPs, JSContact (RFC 9553),
30
+ JSCalendar (RFC 8984) and schema.org; issue
12
31
  [#36](https://github.com/leifriksheim/minca/issues/36) has the sources.
13
32
 
14
33
  ## What a `std.*` name means
15
34
 
16
- A collection name belongs to the space that defines it. There is no registry,
17
- and two spaces may give one name different shapes. What lets two apps read
18
- each other's records is the definition, not the name, and the library exists
19
- so that apps reach for the same definitions.
35
+ A collection name belongs to the space that defines it. There is no
36
+ registry, so two spaces could give one name different shapes. What lets two
37
+ apps read each other's records is a shared definition, and the library is
38
+ where apps find one.
20
39
 
21
- `std.*` names are the library's by convention ([spec 02 §6.4](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)); peers do not refuse a
22
- `std.*` definition of another shape. The reference node's agent actions keep
23
- to the convention:
40
+ `std.*` names belong to the library by convention. Peers don't refuse a
41
+ `std.*` definition of another shape, but the node's agent actions keep to it:
24
42
 
25
- - `collections_standard` lists the library, and gives any of its definitions
26
- in full ([actions](actions.md)).
27
- - `collections_propose` takes a standard collection by name (`"std.event"`
28
- in `collections`) and stores the library's definition for it.
29
- - `collections_propose` refuses a `std.*` name the library does not have, and
43
+ - `collections_standard` lists the library, and gives any definition in
44
+ full.
45
+ - `collections_propose` takes a standard collection by name (`"std.event"`)
46
+ and stores the library's definition for it.
47
+ - `collections_propose` refuses a `std.*` name the library doesn't have, and
30
48
  a `std.*` definition whose `schema`, `links`, `rules`, `topics` or
31
- `history` differ from the library's. Its `title` and
32
- `description` may be its own.
49
+ `history` differ from the library's. The `title` and `description` may be
50
+ your own.
33
51
 
34
- Names of an app's own collections should say what they are for
35
- (`carpool.ride`) rather than share a generic prefix (`app.ride`) that another
36
- app may want for something else. Making apps open collections by what they
37
- hold rather than by name is [compatible definitions](blueprints-and-guides.md#compatible-definitions).
38
-
39
- _Source: `packages/core/src/schemas/blueprints.ts` (`standardCollections`), `packages/core/src/schemas/standard.ts` (`standardDefinition`, `standardGroups`), `packages/core/src/node/actions.ts` (`collections_standard`, `collections_propose`). Tests: `packages/core/tests/records-only.test.ts` ("a standard collection by name is exactly the library’s; a look-alike std.\* is refused", "collections_standard lists the library by area, and gives definitions in full")._
52
+ Name your app's own collections for what they hold (`carpool.ride`), not
53
+ with a generic prefix (`app.ride`) another app may want too. To open
54
+ collections by what they hold rather than by name, see
55
+ [compatible definitions](blueprints-and-guides.md#compatible-definitions).
56
+ See also [actions](actions.md) and
57
+ [spec 02 §6.4](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
40
58
 
41
59
  ## How the library is shaped
42
60
 
43
- People start with a few apps, then change them, add views, and build new
44
- apps over the same records, often by asking an agent. That only works if
45
- every app reaches for the same collection for the same thing. These rules
46
- keep the library small enough to choose from, and each choice obvious:
47
-
48
- 1. **One collection per kind of thing.** Variants are optional fields, not
49
- collections of their own: a photo, a video and a PDF are each a
50
- `std.file`, with `width`, `duration` or none. Two collections an agent
51
- could reasonably pick for the same thing is a bug in the library.
52
- 2. **A group is a relation, never a field on what is in it.** There are two
53
- ways to group, and only two: `std.tag` for loose labels, any number on a
54
- record, and `std.list` with a `std.list-item` per member for a named,
55
- ordered group that exists while empty: a folder, an album, a playlist, a
56
- category, an itinerary (`kind`). Because the group is a record of its
57
- own, one file can be in a chat, a category and an album, and each app
58
- arranges it without touching the file. A single facet that nearly every
59
- app filters by, like an event's or a transaction's `category`, may stay a
60
- field.
61
- 3. **What an app adds to a standard record is a record of its own about
62
- it.** A definition here is exact (`collections_propose` refuses a
63
- look-alike), so an app that needs more on a `std.file`, say, defines
64
- `recipes.photo-note` with an `about` link to the file and
65
- `onePer: [link:about]`. Every other app still reads the file; only the
66
- recipes app reads the note. Never a parallel `recipes.photo` collection.
67
- 4. **Links use one vocabulary**, below. A link that says where a record
68
- sits is `in`, whether that is a channel, a board column or a list.
61
+ People build several apps over the same records, often by asking an agent.
62
+ That only works if every app picks the same collection for the same thing.
63
+ Five rules keep the choice obvious.
64
+
65
+ 1. **One collection per kind of thing.** Variants are optional fields. A
66
+ photo, a video and a PDF are each a `std.file`, with `width`, `duration`
67
+ or neither. Two collections an agent could pick for the same thing is a
68
+ bug in the library.
69
+ 2. **A group is a relation, not a field.** `std.tag` is a loose label, any
70
+ number per record. `std.list` with a `std.list-item` per member is a
71
+ named, ordered group that exists while empty: a folder, an album, a
72
+ playlist, an itinerary (`kind`). So one file can be in a chat, a category
73
+ and an album at once. A facet nearly every app filters by, like an
74
+ event's `category`, may stay a field.
75
+ 3. **What your app adds to a standard record is a record of its own.** Say
76
+ your recipes app needs more on a `std.file`. Define `recipes.photo-note`
77
+ with an `about` link to the file and `onePer: [link:about]`. Every app
78
+ still reads the file. Never a parallel `recipes.photo`.
79
+ 4. **Links share one vocabulary** (below). Where a record sits is always
80
+ `in`: a channel, a board column or a list.
69
81
  5. **A description says when not to use it.** Agents choose by reading
70
- descriptions, so where a neighbour could be mistaken for it, the
71
- description names the neighbour: "To vote on a std.proposal, use
72
- std.ballot."
82
+ descriptions, so a definition names the neighbour it could be mistaken
83
+ for: "To vote on a std.proposal, use std.ballot."
73
84
 
74
85
  ## Conventions
75
86
 
76
- - What several people edit is several records, not an array in one body,
77
- because a record resolves as a whole ([spec 02 §4.3](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)): a list and its items, a
78
- document and its blocks, an order and the seller's updates to it.
79
- - "One per person" or "one per slot" is `onePer` ([spec 02 §7.3](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)), over links and
80
- scalar fields only (see the known defect there).
81
- - Bodies carry no `createdAt`; the record has one. They carry only the times
82
- of the thing itself (`start`, `due`, `takenAt`).
83
- - Link roles share one vocabulary: `about` (what an annotation is on),
84
- `replyTo` and `root` (threads), `parent` (trees), `in` (member of a list,
85
- album, calendar, document, account), `shares` (quotes).
86
- - What only one person should see — blocks, mutes, reminders, settings — goes
87
- in that person's own space, not in one others read.
88
-
89
- **Fragments.** The dialect has no `$ref` ([spec 02 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)), so shared shapes are spelled
90
- out in each definition, built by the library's `fragments` so they are
91
- identical everywhere:
92
-
93
- | Fragment | Shape |
94
- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
95
- | `when` | string 10–64, `x-kind: "when"`: RFC 3339 date-time (`2026-03-01T18:30:00+01:00`), or `YYYY-MM-DD` for a whole day |
96
- | `day` | string of 10, `x-kind: "day"`: `YYYY-MM-DD` |
97
- | `url` | string 1–2048, `x-kind: "url"`: a web address |
98
- | `timeZone` | string 1–64: an IANA zone, `Europe/Oslo` |
99
- | DID | string 1–256, `x-kind: "did"`: an account DID (built by `person`) |
100
- | `money` | `{ amount, currency }`, `x-kind: "money"`, both required: `amount` a decimal string 1–32 (`"12.50"`), never a number; `currency` ISO 4217, 3 characters |
101
- | `address` | `{ street, locality, region, postcode, country }`, each optional; `country` ISO 3166-1 alpha-2 |
102
- | `place` | `{ name, address, lat, lon, cells }` (built by `placeRef`), each optional; `lat` −90–90, `lon` −180–180, WGS 84; `cells` string 1–12[] (≤ 8), the geohash cells of `lat` and `lon` (see Places and areas) |
103
- | `blob` | `{ hash, size, mime, name?, key?, salt? }`, `x-kind: "file"`: what `records.addFile` gives: `hash` the file's id (64 hex characters), `size` bytes as stored, `mime` required; `key` and `salt` open it (22 base64url characters each) |
104
- | `image` | `{ blob, alt? }`, `x-kind: "image"`: `alt` ≤ 2000, what it shows |
105
- | `position` | string 1–200, `x-kind: "position"`, that sorts where a record goes (Positions, below) |
106
-
107
- Until the dialect has `format` ([spec 02 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)), `when` and `day` are checked only for
108
- length. A `blob` is what `records.addFile` gives
109
- ([storage](storage.md#files)): its `hash` is the file's id, and it carries
110
- the `key` and `salt` that open it
111
- ([spec 05 §16.6](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md)).
87
+ - What several people edit is several records, not an array in one body. A
88
+ list and its items, a document and its blocks, an order and its updates.
89
+ - "One per person" or "one per slot" is the `onePer` rule.
90
+ - A picture or a video in a `std.file` may carry a `thumbnail`: a small
91
+ still, about 480 px on its longer side, that apps show in its place until
92
+ someone opens it. It is small enough for every device to fetch ahead, so a
93
+ long chat shows its pictures without fetching each file whole. A picture
94
+ that is already small has none, and an app shows the picture itself. An
95
+ app shows a thumbnail only for a `mime` of `image/` or `video/`, and only
96
+ one of at most 256 KiB: it is the writer's word, like the rest of the body.
97
+ - Bodies have no `createdAt`, since the record has one. They carry only the
98
+ times of the thing itself: `start`, `due`, `takenAt`.
99
+ - Link roles: `about` (what an annotation is on), `replyTo` and `root`
100
+ (threads), `parent` (trees), `in` (member of a list, album, calendar,
101
+ document or account), `shares` (quotes).
102
+ - What only one person should see is kept where only they read it: a block
103
+ on the contact ([contacts](contacts.md)), and their own settings and
104
+ reminders in the account registry, `node.account.space()`
105
+ ([the node](node.md#records-and-the-account)).
106
+
107
+ See [spec 02 §4.3 and §7.3](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
108
+
109
+ ## Fragments
110
+
111
+ Shared shapes like a time or an amount of money are built by the library's
112
+ `fragments`, so they are identical in every definition. You can use them in
113
+ your own definitions too.
114
+
115
+ | Fragment | Shape |
116
+ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
117
+ | `when` | string 10–64, `x-kind: "when"`: RFC 3339 (`2026-03-01T18:30:00+01:00`), or `YYYY-MM-DD` for a whole day |
118
+ | `day` | string of 10, `x-kind: "day"`: `YYYY-MM-DD` |
119
+ | `url` | string 1–2048, `x-kind: "url"` |
120
+ | `timeZone` | string 1–64: an IANA zone, `Europe/Oslo` |
121
+ | DID | string 1–256, `x-kind: "did"`: an account (built by `person`) |
122
+ | `money` | `{ amount, currency }`, `x-kind: "money"`, both required. `amount` is a decimal string 1–32 (`"12.50"`), never a number. `currency` is ISO 4217 |
123
+ | `address` | `{ street, locality, region, postcode, country }`, each optional. `country` is ISO 3166-1 alpha-2 |
124
+ | `place` | `{ name, address, lat, lon, cells }` (built by `placeRef`), each optional. WGS 84. `cells` is up to 8 geohash cells ([Places and areas](#places-and-areas)) |
125
+ | `blob` | `{ hash, size, mime, name?, key?, salt? }`, `x-kind: "file"`: what `records.addFile` gives |
126
+ | `image` | `{ blob, alt? }`, `x-kind: "image"`, `alt` ≤ 2000 |
127
+ | `position` | string 1–200, `x-kind: "position"` ([Positions](#positions)) |
128
+
129
+ A `blob`'s `hash` is the file's id (64 hex characters), and its `key` and
130
+ `salt` open it (22 base64url characters each). See [storage](storage.md#files).
131
+
132
+ `when` and `day` are checked only for length until the schema dialect has
133
+ `format` (Planned, below).
112
134
 
113
135
  ## The definitions
114
136
 
115
- In the tables, a **bold** field is required; `string 1–200` gives its
116
- `minLength`–`maxLength`, `[]` a list with its `maxItems`, and `a`/`b` an
117
- `enum`. Links read `role` → where it may point, cardinality. Rules are what
118
- a definition asks of its records ([spec 02 §7](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)):
119
- `onePer`, `fixed`, `final`; a contract (`check`) is the definition's
120
- `contract`, beside them. Who may add, change and remove records
121
- is not the definition's to say but the space's grants
122
- ([spec 03 §2](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)):
123
- in the `community` template, members change only what they made, moderators
124
- anything, and only moderators and admins write in the collections in
125
- `STAFF_COLLECTIONS` ([spaces](spaces.md#presets)).
126
-
127
- **Annotations**
128
-
129
- | Name | Body | Links | Rules |
130
- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------- |
131
- | `std.reaction` | **`emoji`** string 1–16; `respondingTo` DID; topic `respondingTo` | `about` → `*`, one | `onePer: [@author, link:about, emoji]` |
132
- | `std.comment` | **`text`** string 1–10000; `mentions` DID[] (≤ 64); `replyingTo` DID; `respondingTo` DID; topics `mentions`, `replyingTo`, `respondingTo` | `about` → `*`, one; `replyTo` → `std.comment`, one; `shares` → `*`, one | — |
133
- | `std.tag` | **`label`** string 1–100 | `about` → `*`, one | `onePer: [@author, link:about, label]` |
134
- | `std.rating` | **`score`** integer 1–5; `review` string ≤ 10000 | `about` → `*`, one | `onePer: [@author, link:about]` |
135
- | `std.highlight` | **`quote`** string 1–10000; `prefix` string ≤ 500; `suffix` string ≤ 500; `note` string ≤ 10000 | `about` → `*`, one | — |
136
- | `std.pin` | `note` string ≤ 500 | `about` → `*`, one | `onePer: [link:about]` |
137
- | `std.report` | **`reason`** `spam`/`abuse`/`sexual`/`misleading`/`illegal`/`other`; `note` string ≤ 2000 | `about` → `*`, one | `onePer: [@author, link:about]` |
138
- | `std.label` | **`value`** string 1–64 | `about` → `*`, one | `onePer: [link:about, value]` |
139
- | `std.claim` | `note` string ≤ 500; `respondingTo` DID; topic `respondingTo` | `about` → `*`, one | `onePer: [link:about]` |
140
-
141
- **People**
142
-
143
- | Name | Body | Links | Rules |
144
- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------ |
145
- | `std.profile` | `name` string ≤ 100; `bio` string ≤ 2000; `avatar` blob; `banner` blob; `pronouns` string ≤ 50; `links` { `title` string ≤ 100, **`url`** string 1–2048 }[] (≤ 16); `bot` boolean | — | `onePer: [@author]` |
146
- | `std.space-profile` | **`space`** string 1–256; `name` string ≤ 100; `bio` string ≤ 2000; `avatar` blob; `banner` blob | — | `onePer: [space]` |
147
- | `std.card` | `name` { `full` string ≤ 200, `given` string ≤ 100, `family` string ≤ 100 }; `emails` { **`address`** string 1–320, `label` string ≤ 50 }[] (≤ 16); `phones` { **`number`** string 1–64, `label` string ≤ 50 }[] (≤ 16); `addresses` { **`address`** address, `label` string ≤ 50 }[] (≤ 16); `organization` string ≤ 200; `jobTitle` string ≤ 200; `birthday` day; `photo` blob; `urls` string 1–2048[] (≤ 16); `note` string ≤ 10000 | — | — |
148
- | `std.follow` | **`did`** DID; `space` string ≤ 256; topic `did` | — | `onePer: [@author, did]` |
149
- | `std.block` | **`did`** DID; `until` when | — | `onePer: [@author, did]` |
150
- | `std.mute` | **`did`** DID; `until` when | — | `onePer: [@author, did]` |
151
- | `std.status` | `text` string ≤ 280; `emoji` string ≤ 16; `until` when | — | `onePer: [@author]` |
152
-
153
- **Messaging and publishing**
154
-
155
- | Name | Body | Links | Rules |
156
- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------- |
157
- | `std.message` | **`text`** string 1–10000; `mentions` DID[] (≤ 64); `replyingTo` DID; topics `link:in`, `mentions`, `replyingTo` | `in` → `std.channel`, one; `replyTo` → `std.message`, one; `shares` → `*`, one | — |
158
- | `std.channel` | **`name`** string 1–100; `topic` string ≤ 500; `position` string 1–200 | — | — |
159
- | `std.direct` | **`to`** DID[] (1–16); **`data`** string ≤ 60000; **`boxes`** `{to, sealed}`[] (≤ 17); topic `to` | — | — |
160
- | `std.post` | `text` string ≤ 10000; `images` image[] (≤ 8); `langs` string 2–35[] (≤ 3); `mentions` DID[] (≤ 64); `replyingTo` DID; topics `mentions`, `replyingTo` | `replyTo` → `std.post`, one; `root` → `std.post`, one; `shares` → `*`, one | — |
161
- | `std.repost` | `respondingTo` DID; topic `respondingTo` | `about` → `*`, one | `onePer: [@author, link:about]` |
162
- | `std.article` | **`title`** string 1–300; `summary` string ≤ 1000; `content` string ≤ 200000; `cover` blob; `slug` string 1–200; `publishedAt` when; `draft` boolean; `mentions` DID[] (≤ 64); topic `mentions` | `in` → `std.publication`, one | — |
163
- | `std.publication` | **`title`** string 1–200; `description` string ≤ 2000; `icon` blob | — | — |
164
- | `std.doc` | **`title`** string 1–500 | — | — |
165
- | `std.doc-block` | **`type`** `paragraph`/`heading1`/`heading2`/`heading3`/`bullet`/`numbered`/`todo`/`quote`/`code`/`image`/`divider`; `text` string ≤ 20000; `checked` boolean; `language` string ≤ 32; `image` image; `position` string 1–200; `mentions` DID[] (≤ 64); topic `mentions` | `in` → `std.doc`, one; `parent` → `std.doc-block`, one | — |
166
- | `std.wiki-page` | **`slug`** string 1–200; **`title`** string 1–300; `content` string ≤ 200000 | — | `onePer: [slug]`; history `all` |
167
- | `std.note` | `title` string ≤ 500; `content` string ≤ 200000; `pinned` boolean; `color` string ≤ 32; `mentions` DID[] (≤ 64); topic `mentions` | — | — |
168
- | `std.call` | **`status`** `missed`/`ended`; `to` string ≤ 256; **`startedAt`** string ≤ 64; `endedAt` string ≤ 64; `people` string ≤ 256[] (≤ 64); topics `to`, `people` | — | — |
169
-
170
- **Lists**
171
-
172
- | Name | Body | Links | Rules |
173
- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | ----- |
174
- | `std.list` | **`title`** string 1–200; `description` string ≤ 2000; `icon` string ≤ 16; `kind` string ≤ 32 | — | — |
175
- | `std.list-item` | `text` string ≤ 1000; `url` string 1–2048; `did` DID; `checked` boolean; `quantity` number ≥ 0; `position` string 1–200; topic `did` | `in` → `std.list`, one; `about` → `*`, one | — |
176
-
177
- **Files and media**
178
-
179
- | Name | Body | Links | Rules |
180
- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----- |
181
- | `std.file` | **`name`** string 1–255; **`mime`** string 1–255; `size` integer ≥ 0; `blob` blob; `url` string 1–2048; `alt` string ≤ 2000; `width` integer ≥ 1; `height` integer ≥ 1; `duration` number ≥ 0; `takenAt` when; `place` place; `thumbnail` blob; `captions` blob | `about` → `*`, one | — |
182
- | `std.track` | **`title`** string 1–300; `artists` string 1–200[] (≤ 20); `album` string ≤ 300; `duration` number ≥ 0; `isrc` string ≤ 12; `mbid` string ≤ 36 | `file` → `std.file`, one | — |
183
- | `std.play` | **`title`** string 1–300; `artists` string 1–200[] (≤ 20); `album` string ≤ 300; `duration` number ≥ 0; `isrc` string ≤ 12; `mbid` string ≤ 36; **`playedAt`** when | `about` → `std.track`, one | — |
184
-
185
- **Time and planning**
186
-
187
- | Name | Body | Links | Rules |
188
- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------- |
189
- | `std.calendar` | **`name`** string 1–200; `color` string ≤ 32 | — | — |
190
- | `std.event` | **`title`** string 1–500; `description` string ≤ 10000; `category` string ≤ 100; **`start`** when; `end` when; `tz` string 1–64; `allDay` boolean; `place` place; `url` string 1–2048; `rrule` string 1–1000; `status` `confirmed`/`tentative`/`cancelled`; topic `place.cells` | `in` → `std.calendar`, one | — |
191
- | `std.rsvp` | **`status`** `going`/`maybe`/`no`; `guests` integer 0–100; `note` string ≤ 500; `respondingTo` DID; topic `respondingTo` | `about` → `std.event`, one | `onePer: [@author, link:about]` |
192
- | `std.slot` | **`start`** when; **`end`** when; `tz` string 1–64; `note` string ≤ 1000 | `in` → `std.calendar`, one | — |
193
- | `std.column` | **`name`** string 1–200; `position` string 1–200 | `in` → `std.project`, one | — |
194
- | `std.task` | **`title`** string 1–500; `notes` string ≤ 10000; `position` string 1–200; `due` when; `status` `todo`/`doing`/`done`/`cancelled`; `assignees` DID[] (≤ 20); `priority` integer 0–4; topic `assignees` | `in` → `std.column`, `std.project`, one; `parent` → `std.task`, one | — |
195
- | `std.project` | **`name`** string 1–200; `description` string ≤ 10000; `status` `planned`/`active`/`paused`/`done`/`cancelled`; `due` when | — | — |
196
- | `std.time-entry` | **`start`** when; `end` when; `note` string ≤ 1000 | `about` → `*`, one | — |
197
- | `std.reminder` | **`at`** when; `note` string ≤ 1000; `done` boolean | `about` → `*`, one | — |
198
- | `std.habit` | **`name`** string 1–200; `schedule` string ≤ 1000; `target` number ≥ 0; `unit` string ≤ 32; `position` string 1–200 | — | — |
199
- | `std.checkin` | **`date`** day; `value` number; `note` string ≤ 1000 | `about` → `std.habit`, one | `onePer: [@author, link:about, date]` |
200
-
201
- **Places and travel**
202
-
203
- | Name | Body | Links | Rules |
204
- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------- |
205
- | `std.place` | **`name`** string 1–200; `address` address; `lat` number -90–90; `lon` number -180–180; `cells` string 1–12[] (≤ 8); `category` string ≤ 100; `url` string 1–2048; topic `cells` | — | — |
206
- | `std.visit` | **`at`** when; `note` string ≤ 2000 | `about` → `std.place`, one | — |
207
- | `std.trip` | **`title`** string 1–200; `start` day; `end` day; `note` string ≤ 10000 | — | — |
208
- | `std.location` | **`lat`** number -90–90; **`lon`** number -180–180; `accuracy` number ≥ 0; **`at`** when | — | `onePer: [@author]` |
209
-
210
- **Home and life**
211
-
212
- | Name | Body | Links | Rules |
213
- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------- |
214
- | `std.recipe` | **`title`** string 1–300; `description` string ≤ 2000; `ingredients` { **`text`** string 1–500, `quantity` number ≥ 0, `unit` string ≤ 32 }[] (≤ 200); `steps` string 1–5000[] (≤ 200); `servings` integer ≥ 1; `prepMinutes` integer ≥ 0; `cookMinutes` integer ≥ 0; `image` image; `source` string 1–2048 | — | — |
215
- | `std.meal` | **`date`** day; **`meal`** `breakfast`/`lunch`/`dinner`/`snack`; `note` string ≤ 1000 | `about` → `std.recipe`, one | `onePer: [date, meal]` |
216
- | `std.journal-entry` | **`date`** day; `content` string ≤ 200000; `mood` string ≤ 32 | — | `onePer: [@author, date]` |
217
- | `std.measurement` | **`kind`** string 1–64; **`value`** number; **`unit`** string 1–32; **`at`** when; `note` string ≤ 1000 | — | — |
218
- | `std.workout` | **`type`** string 1–64; **`start`** when; `duration` number ≥ 0; `distance` number ≥ 0; `route` blob; `note` string ≤ 2000 | — | — |
219
- | `std.work` | **`kind`** `book`/`film`/`show`/`album`/`game`/`podcast`/`other`; **`title`** string 1–500; `creators` string 1–200[] (≤ 20); `year` integer 0–9999; `ids` { `isbn` string ≤ 17, `imdb` string ≤ 16, `mbid` string ≤ 36, `wikidata` string ≤ 16 }; `cover` blob | — | — |
220
- | `std.progress` | **`status`** `want`/`doing`/`done`/`dropped`; `percent` number 0–100; `finishedAt` when; `note` string ≤ 2000 | `about` → `std.work`, one | `onePer: [@author, link:about]` |
221
-
222
- **Money and trade**
223
-
224
- | Name | Body | Links | Rules |
225
- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------- |
226
- | `std.expense` | **`title`** string 1–200; **`amount`** money; **`paidBy`** DID; `split` { **`did`** DID, `share` string 1–32 }[] (≤ 100); `date` day; `note` string ≤ 2000; `owedBy` DID[] (≤ 63), the people in `split`; topics `paidBy`, `owedBy` | — | history `all` |
227
- | `std.settlement` | **`from`** DID; **`to`** DID; **`amount`** money; `date` day; `note` string ≤ 1000; topics `from`, `to` | — | `fixed: [from, to, amount]` |
228
- | `std.money-account` | **`name`** string 1–200; **`currency`** string 3–3; `kind` string ≤ 32 | — | — |
229
- | `std.transaction` | **`amount`** money; **`date`** day; `payee` string ≤ 200; `category` string ≤ 100; `note` string ≤ 1000; `cleared` boolean | `in` → `std.money-account`, one | — |
230
- | `std.listing` | **`title`** string 1–300; `description` string ≤ 10000; `price` money; `category` string ≤ 100; `condition` `new`/`like-new`/`good`/`fair`/`for-parts`; `images` image[] (≤ 12); `status` `available`/`reserved`/`sold`; `place` place; topic `place.cells` | — | — |
231
- | `std.order` | **`items`** { **`title`** string 1–300, **`quantity`** integer ≥ 1, `price` money }[] (1–100); `total` money; `note` string ≤ 2000; `respondingTo` DID; topic `respondingTo` | `about` → `std.listing`, many | — |
232
- | `std.order-update` | **`status`** `accepted`/`paid`/`shipped`/`delivered`/`cancelled`/`refunded`; `note` string ≤ 2000; `respondingTo` DID; topic `respondingTo` | `about` → `std.order`, one | — |
233
-
234
- **Community and governance**
235
-
236
- | Name | Body | Links | Rules |
237
- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------- |
238
- | `std.poll` | **`question`** string 1–500; **`options`** string 1–200[]; `closed` boolean | — | `fixed: [options]` |
239
- | `std.vote` | **`choice`** integer ≥ 0; `choices` integer ≥ 0[] (≤ 100); `respondingTo` DID; topic `respondingTo` | `about` → `std.poll`, one | `onePer: [@author, link:about]` |
240
- | `std.proposal` | **`title`** string 1–300; `body` string ≤ 20000; **`options`** string 1–200[] (1–20); `closesAt` when; `status` `open`/`passed`/`rejected`/`withdrawn`; `quorum` integer 1–10000 | — | `fixed: [options]` |
241
- | `std.ballot` | **`choice`** integer ≥ 0; `respondingTo` DID; topic `respondingTo` | `about` → `std.proposal`, one | `onePer: [@author, link:about]`; `fixed: [choice]` |
242
- | `std.decision` | **`outcome`** integer ≥ 0; **`proposal`** string 1–128 (a version id); **`ballots`** string 1–128[] (≤ 256) | `about` → `std.proposal`, one | `onePer: [link:about]`; `check` (below) |
243
- | `std.goal` | **`title`** string 1–300; `body` string ≤ 20000; **`target`** integer 1–10⁹; **`unit`** string 1–50; `closesAt` when | — | `fixed: [target, unit]` |
244
- | `std.pledge` | **`amount`** integer 1–10⁹; `note` string ≤ 1000; `respondingTo` DID; topic `respondingTo` | `about` → `std.goal`, one | `onePer: [@author, link:about]`; `fixed: [amount]` |
245
- | `std.goal-reached` | **`goal`** string 1–128 (a version id); **`pledges`** string 1–128[] (≤ 256) | `about` → `std.goal`, one | `onePer: [link:about]`; `check` (below) |
246
- | `std.announcement` | **`title`** string 1–300; `text` string ≤ 20000 | — | — |
247
- | `std.badge` | **`name`** string 1–100; `description` string ≤ 1000; `image` blob | — | — |
248
- | `std.award` | **`did`** DID; `note` string ≤ 1000; topic `did` | `about` → `std.badge`, one | `onePer: [link:about, did]` |
249
-
250
- **Proven outcomes.** A `std.decision` and a `std.goal-reached` are not
251
- declared by anyone: each cites the records that prove it, by version id, and
252
- every device checks the proof before it counts one ([contracts.md](contracts.md)). Anyone in the space may write one, once, when the
253
- proof is there:
254
-
255
- - `std.decision` cites the proposal's first version (`proposal`) and ballots
256
- (`ballots`). Its contract: the proposal is the one it is `about`, as first
257
- put; `outcome` is one of its options; and the ballots cited that are about
258
- that proposal and chose `outcome` come from at least `quorum` different
259
- people. A proposal without a `quorum` can't be decided this way.
260
- - `std.goal-reached` cites the goal's first version (`goal`) and pledges
261
- (`pledges`). Its contract: the goal is the one it is `about`, as first set;
262
- each person's pledge counts once; and the pledges add up to `target`.
263
-
264
- A cited version proves what was signed, so what they count is final: a
265
- ballot's `choice` and a pledge's `amount` are `fixed`, and their first
266
- versions are kept whole (`onePer`), so they can be cited. That is why
267
- `std.ballot` exists beside `std.vote`: a vote can be changed, a ballot can't.
137
+ How to read the tables:
138
+
139
+ - A **bold** field is required.
140
+ - `string 1–200` gives its shortest and longest length.
141
+ - `[]` is a list, with its most items in brackets.
142
+ - `a`/`b` is a choice of values.
143
+ - Links read `role` → what it may point at, and how many.
144
+ - Rules are `onePer`, `fixed` and `final`, and whether it has a contract.
145
+
146
+ Who may add, change and remove records isn't up to the definition, but to
147
+ the space's grants. In the `community` template, members change only what
148
+ they made, moderators change anything, and only moderators and admins write
149
+ in the collections in `STAFF_COLLECTIONS` ([spaces](permissions.md#presets)).
150
+
151
+ The tables are made from the definitions in `@minca/core/schemas` each time
152
+ [minca.dev](https://minca.dev/collections/standard-library/#the-definitions)
153
+ is built, so they always match the code.
154
+
155
+ <!-- catalogue: standard -->
156
+
157
+ ## About some of them
158
+
159
+ ### `std.call`
160
+
161
+ Calls themselves are kept nowhere ([calls](../../calls/README.md)). If the
162
+ space defines `std.call`, a call leaves a record of its history there.
163
+
164
+ | Field | Type | Meaning |
165
+ | ----------- | ----------------------- | -------------------------------------------- |
166
+ | `status` | `"missed"` \| `"ended"` | Required. |
167
+ | `to` | string ≤ 256 | For a missed call: who was rung. |
168
+ | `startedAt` | ISO date, ≤ 64 | Required. |
169
+ | `endedAt` | ISO date, ≤ 64 | For an ended call. |
170
+ | `people` | string ≤ 256[] (≤ 64) | For an ended call: every account seen in it. |
171
+
172
+ ```json
173
+ {
174
+ "status": "ended",
175
+ "startedAt": "2026-09-26T10:00:00.000Z",
176
+ "endedAt": "2026-09-26T10:14:02.311Z",
177
+ "people": ["did:key:zDnaeSm3…", "did:key:zDnaeXL64…"]
178
+ }
179
+ ```
180
+
181
+ The call a device is in is kept in `sessionStorage` under `minca-call` as
182
+ `{ space, call }`, so after a reload the page can offer to rejoin.
183
+
184
+ ### Tasks
185
+
186
+ A task is `in` its column, or `in` its project when it has no column. A
187
+ column is `in` its project.
188
+
189
+ ### Proven outcomes
190
+
191
+ Nobody declares a `std.decision` or a `std.goal-reached`. Each one cites the
192
+ records that prove it, by version id, and every device checks the proof
193
+ before it counts. Anyone in the space may write one, once, when the proof is
194
+ there.
195
+
196
+ - A `std.decision` cites the proposal's first version (`proposal`) and the
197
+ ballots (`ballots`). It holds when the ballots about that proposal that
198
+ chose `outcome` come from at least `quorum` different people. A proposal
199
+ without a `quorum` can't be decided this way.
200
+ - A `std.goal-reached` cites the goal's first version (`goal`) and the
201
+ pledges (`pledges`). It holds when the pledges add up to `target`,
202
+ counting each person once.
268
203
 
269
204
  ```json
270
205
  { "outcome": 0, "proposal": "bay24o4l…", "ballots": ["bq7x…", "b3kd…", "bm2a…"] }
271
206
  ```
272
207
 
273
- _Source: `packages/core/src/schemas/library/community.ts` (`ballot`, `decision`, `goal`, `pledge`, `goalReached`), `apps/example/src/components/apps/Decisions.tsx`. Tests: `packages/core/tests/contracts.test.ts` ("std.decision and std.goal-reached")._
274
-
275
- **Settings**
276
-
277
- | Name | Body | Links | Rules |
278
- | ------------- | ---------------------------------------------------------------- | ----- | ----------------------------- |
279
- | `std.setting` | **`app`** string 1–200; **`key`** string 1–200; `value` any | — | `onePer: [@author, app, key]` |
280
- | `std.host` | **`url`** string 1–2048; `did` string 1–256; `name` string ≤ 100 | — | `onePer: [url]` |
281
-
282
- `std.host` names a host the space pays to keep it online, which anyone in it
283
- may chip in for; members' devices hand it the space's pass
284
- ([node](node.md#a-space-paying-for-itself), [spec 08 §2](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md)).
285
- Naming a host sends it every member's pass, so only those granted it should:
286
- the `community` template leaves `std.host` to admins and moderators.
287
-
288
- _Source: `packages/core/src/schemas/library/community.ts` (`host`)._
289
-
290
- **Automations**
291
-
292
- `std.automation` and `std.automation-run`: what a space does by itself when records come
293
- to be a certain way, or at set times, and what each automation did. An
294
- account keeps automations of its own in its registry too, which notify it. Described in
295
- [automations.md](automations.md).
296
-
297
- **Bots**
298
-
299
- `std.bot`, `std.connect` and `std.connector`: how a community wants its bot
300
- to be, someone asking a bot's host to connect the bot to a service such as
301
- GitHub, and the bot saying what it is connected to. Described in
302
- [bots.md](bots.md).
303
-
304
- **Activity.** `std.activity` is someone at work on a record, for apps to show
305
- while it lasts: "My bot is working on it…" under a message, a spinner on a
306
- task. Anyone may write one, only about their own work, and apps show it as
307
- that account's word.
308
-
309
- | Collection | Body | Links | Rules |
310
- | -------------- | ----------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------- |
311
- | `std.activity` | **`state`** `working` \| `waiting` \| `done` \| `failed`; `label` string ≤ 120; **`at`** when it came to it | `about` → any, one | `onePer: [@author, link:about]` |
312
-
313
- One per account per record: writing another about the same record is its
314
- next version, so the work moves from `waiting` to `working` to `done` or
315
- `failed` in one record. A `working` or `waiting` activity whose `at` is more
316
- than five minutes old (`ACTIVITY_STALE_SECONDS`) must be shown as over: its
317
- writer may have gone away mid-way. `setActivity(node, space, key, state,
318
- label?)` writes one, and `activeNow(body)` says whether one is going on now.
319
- A setting without a label keeps the label it had. The action
320
- `activity_set` ([actions](actions.md)) lets an agent or bot say what it is
321
- doing in its own words ("Reading the thread", "Making an app"). A bot's
322
- automation runner marks what set each automation off: `waiting` when queued,
323
- `working` with the automation's name when it starts, then `done` or `failed`, keeping whatever the
324
- model last said it was doing; it tells the model which record to say it on
325
- ([automations.md](automations.md#running)).
326
-
327
- _Source: `packages/core/src/schemas/automations.ts` (`activity`, `setActivity`, `activeNow`), `packages/cli/src/bot-runner.ts` (`runAutomations`), `apps/example/src/activity.ts`, `apps/example/src/components/apps/Chat.tsx` (`Working`). Tests: `packages/core/tests/automation-runners.test.ts` ("std.activity"), `packages/cli/tests/agent-automations.test.ts` ("while an automation runs")._
328
-
329
- **Collections**
330
-
331
- `std.blueprint` and `std.guide`: collections someone proposes for the space,
332
- not yet added, and how some of its collections are meant to be used. Neither
333
- is about any one app. Described in [blueprints and guides](blueprints-and-guides.md).
334
-
335
- | Collection | Body | Rules |
336
- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
337
- | `std.blueprint` | **`title`** 1–100; **`collections`** 1–10 objects, each a definition without `version`; `description` ≤ 1000; `from` ≤ 300; `updates` 1–100 | — |
338
- | `std.guide` | **`name`** 1–100; **`title`** 1–200; **`text`** 1–20000; `collections` ≤ 16 names | `onePer: [name]` |
339
-
340
- _Source: `packages/core/src/schemas/library/collections.ts` (`blueprint`, `guide`), `packages/core/src/schemas/blueprints.ts`, `packages/core/src/schemas/guides.ts`. Tests: `packages/core/tests/records-only.test.ts` ("collections proposed in a blueprint")._
341
-
342
- **Bots.** A bot is an account of its own that people invite to their spaces
343
- as a member. The protocol does not tell bots and people apart, and has no way
344
- to: an account is an account. Disclosing is a convention. A bot says so with
345
- `bot: true` on its own `std.profile` in a space, which only it can write, and
346
- apps may show it; it is the account's word, like its name, so it proves
347
- nothing about an account that leaves it out. A bot whose role may add
348
- collections adds `std.profile` where a space keeps none, as an app does when
349
- it starts a hosted bot.
350
- Besides its own automations, it runs the automations in a space that name it in `by`,
351
- made by members granted `/std.automation/instruct` there
352
- ([automations.md](automations.md#who-runs-an-automation)). In the `community` template, admins
353
- and moderators hold it. Nothing the bot writes sets an automation off.
354
- What it writes shows as the bot, and every member's device checks it against
355
- the bot's role, so a role that may post messages but not delete keeps a
208
+ A ballot's `choice` and a pledge's `amount` are `fixed`, so what was counted
209
+ can't change. That's why `std.ballot` exists beside `std.vote`: a vote can be
210
+ changed, a ballot can't. See [contracts](contracts.md).
211
+
212
+ ### `std.host`
213
+
214
+ A `std.host` names a host the space pays to keep it online. Anyone in the
215
+ space may chip in, and members' devices hand the host the space's pass. That
216
+ means naming a host sends it every member's pass, so the `community`
217
+ template leaves `std.host` to admins and moderators. See
218
+ [node](node.md#a-space-paying-for-itself) and
219
+ [spec 08 §2](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md).
220
+
221
+ ### Automations, bots, blueprints and guides
222
+
223
+ - `std.automation` and `std.automation-run`: what a space does by itself
224
+ when records change or at set times, and what each run did. See
225
+ [automations](automations.md).
226
+ - `std.bot`, `std.connect` and `std.connector`: how a community wants its
227
+ bot to be, asking a bot's host to connect it to a service like GitHub, and
228
+ what the bot is connected to. See [bots](bots.md).
229
+
230
+ `std.blueprint` holds collections someone proposes for the space, not yet
231
+ added. `std.guide` says how some of the space's collections are meant to be
232
+ used. See [blueprints and guides](blueprints-and-guides.md).
233
+
234
+ ## Activity
235
+
236
+ `std.activity` shows that someone is at work on a record, for as long as it
237
+ lasts: "My bot is working on it…" under a message, or a spinner on a task.
238
+ Anyone may write one, but only about their own work.
239
+
240
+ | Name | Body | Links | Rules |
241
+ | -------------- | ------------------------------------------------------------------------------------------------------ | ------------------ | ------------------------------- |
242
+ | `std.activity` | **`state`** `working`/`waiting`/`done`/`failed`; `label` string ≤ 120; **`at`** when, since this state | `about` → any, one | `onePer: [@author, link:about]` |
243
+
244
+ There's one per account per record, so writing again moves the same record
245
+ from `waiting` to `working` to `done` or `failed`. A label left out keeps
246
+ the one it had.
247
+
248
+ ```ts
249
+ import type { NodeRecord } from '@minca/core';
250
+ declare const message: NodeRecord;
251
+ // ---cut---
252
+ import { setActivity, activeNow } from '@minca/core/schemas';
253
+
254
+ await setActivity(node, space.id, message.key, 'working', 'Reading the thread');
255
+ ```
256
+
257
+ A `working` or `waiting` activity whose `at` is more than five minutes old
258
+ (`ACTIVITY_STALE_SECONDS`) must be shown as over, since its writer may have
259
+ gone away. `activeNow(body)` tells you whether one is still going.
260
+
261
+ An agent or bot says what it's doing with the `activity_set` action
262
+ ([actions](actions.md)). A bot's automation runner marks what set each
263
+ automation off: `waiting` when queued, `working` with the automation's name
264
+ when it starts, then `done` or `failed`
265
+ ([automations](automations.md#running)).
266
+
267
+ ## Bots
268
+
269
+ A bot is an account of its own that people invite to their spaces as a
270
+ member. The protocol can't tell bots and people apart. A bot says it is one
271
+ with `bot: true` on its own `std.profile`, which only it can write, and apps
272
+ may show that. It's the account's own word, like its name, so leaving it out
273
+ proves nothing.
274
+
275
+ A bot that may add collections adds `std.profile` where a space has none.
276
+ Besides its own automations, it runs the space's automations that name it in
277
+ `by`, made by members granted `/std.automation/instruct`. In the `community`
278
+ template, admins and moderators hold that grant. Nothing the bot writes sets
279
+ an automation off. See [automations](automations.md#who-runs-an-automation).
280
+
281
+ What a bot writes shows as the bot, and every member's device checks it
282
+ against the bot's role. So a role that may post but not delete keeps a
356
283
  misled bot from deleting.
357
284
 
358
- _Source: `packages/core/src/schemas/library/social.ts` (`profile`), `packages/core/src/schemas/automations.ts` (`automationsFor`), `packages/cli/src/agent.ts` (`discloseBot`). Tests: `packages/cli/tests/agent-automations.test.ts` ("says it is a bot…", "adds std.profile itself…", "a bot’s name"), `packages/core/tests/automation-runners.test.ts` ("a bot")._
359
-
360
- `std.space-profile` is how a space presents itself, as `std.profile` is how
361
- someone does, with the same fields. Apps show its `name` in place of the name
362
- the space was founded with, and its `avatar` as the space's picture. The
363
- founding name stays in the constitution, where nobody can change it, so an
364
- invite shows it to someone who can't read the space yet, and the name shown
365
- after joining may differ from it. There is one key per space: `space` names
366
- the space by its id, and `onePer: [space]` gives everyone the same shared key,
367
- so changing it is editing it, and which edit stands is the versions' order,
368
- never a writer's clock. Whoever may write there can also start a rival chain
369
- at that key (02 §7.1), so who may write it matters. A reader takes only the record at the key its own
370
- space's id gives, so one naming another space is never read. Who may write
371
- it is the space's grants: it is in `STAFF_COLLECTIONS`, so in a `community`
372
- admins and moderators can, and members can't; in a `coop`, stewards. A space
373
- made before it was added keeps the grants it was made with: there, any
374
- member decides the space's name and picture, outranking staff and taking it
375
- back after each staff edit, until an admin redefines the member role. The example app reads
376
- no `std.space-profile` in a space for two, which it names for whom it is
377
- with.
378
-
379
- _Source: `packages/core/src/schemas/library/social.ts` (`spaceProfile`), `packages/core/src/space/presets.ts` (`STAFF_COLLECTIONS`), `apps/example/src/pictures.ts` (`useSpaceFaces`). Tests: `packages/core/tests/space-profile.test.ts` ("in a community, a member may not change how the space presents itself, and an admin may", "a peer refuses a member's profile forged past their own node's check", "a writer's clock decides nothing: a later edit stands over a profile dated far ahead")._
380
-
381
- **Mentions and replies.** A `std.message`, `std.comment` or `std.post` names
382
- the accounts it calls on in `mentions` (as do `std.note`, `std.doc-block` and
383
- `std.article`) and, when it replies to someone's
384
- message, comment or post, their account in `replyingTo`. An app should fill
385
- them from what the person picked (an `@name` they chose, the one they replied
386
- to), never from matching text. They are topics (with the `channel` link on a message),
387
- so an automation of the account's own can ask for only those that mention the
388
- account, or reply to it, or are in one channel
389
- ([automations](automations.md#the-accounts-own), `where: { "mentions": { "$contains": "$me" } }`),
390
- and a carrier's wake can match it unread ([spec 02 §8](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)).
391
- A `std.task`'s `assignees` is a topic in the same way: "assigned to me" is
392
- `where: { "assignees": { "$contains": "$me" } }`, with a tag for each assignee.
285
+ ## The space's profile
286
+
287
+ `std.space-profile` is how a space presents itself, the way `std.profile` is
288
+ how a person does. Apps show its `name` and `avatar` in place of the name
289
+ the space was founded with.
290
+
291
+ The founding name stays in the constitution, where nobody can change it. An
292
+ invite shows that name to someone who can't read the space yet, so the name
293
+ they see after joining may differ.
294
+
295
+ There's one per space. `space` holds the space's id, and `onePer: [space]`
296
+ gives everyone the same key, so changing it is editing one shared record.
297
+ Which edit stands follows the order of versions, never a writer's clock. A
298
+ reader takes only the record whose `space` is its own space's id.
299
+
300
+ Anyone who may write there could also start a rival record at that key, so
301
+ who may write it matters. It's in `STAFF_COLLECTIONS`: in a `community`,
302
+ admins and moderators can and members can't. In a `coop`, stewards can.
303
+
304
+ A space made before `std.space-profile` existed keeps the grants it was made
305
+ with. There, any member decides the name and picture, and outranks staff,
306
+ until an admin redefines the member role.
307
+
308
+ The example app reads no `std.space-profile` in a space for two. It names
309
+ the space for the other person.
310
+
311
+ ## Text is Markdown
312
+
313
+ The `text` of a `std.message`, `std.comment` or `std.post` is Markdown:
314
+ CommonMark, with GitHub's tables and `~~strikethrough~~`. A plain sentence is
315
+ Markdown too, so an app that shows text as it is still shows it right.
316
+
317
+ ````json
318
+ { "text": "Shipped **today**:\n\n- the chat\n- `code` blocks\n\n```\nnpm run dev\n```" }
319
+ ````
320
+
321
+ Draw it as elements, never as HTML, so a message can't put markup on the
322
+ screen. A screen gets this from the kit: `MentionText` draws it and
323
+ `MentionInput` writes it.
324
+
325
+ ## Mentions and replies
326
+
327
+ A `std.message`, `std.comment` or `std.post` names the accounts it calls on
328
+ in `mentions`. When it replies to someone, it names their account in
329
+ `replyingTo`. `std.note`, `std.doc-block` and `std.article` have `mentions`
330
+ too.
393
331
 
394
332
  ```json
395
333
  { "text": "@Sam are you coming?", "mentions": ["did:key:zDnae…Sam"], "replyingTo": "did:key:zDnae…Sam" }
396
334
  ```
397
335
 
398
- A comment can be `about` a record of any kind, so commenting is how to
399
- mention someone on a record whose own definition has no `mentions`, without
400
- changing that definition. An app's own collection can name a `mentions` field
401
- as a topic the same way.
402
-
403
- _Source: `packages/core/src/schemas/library/publishing.ts` (`message`, `post`), `packages/core/src/schemas/library/annotations.ts` (`comment`), `packages/core/src/schemas/library/planning.ts` (`task`), `apps/example/src/components/std/Mentions.tsx`, `apps/example/src/components/apps/Chat.tsx`, `apps/example/src/components/std/Comments.tsx`. Tests: `packages/core/tests/topics.test.ts` ("mentions and replies are tagged, so “mentions me” and “replies to me” match only those", "a std.comment is tagged like a message…", "a std.post is tagged like a message…", "a task carries a tag for each assignee…", "an app that needs std.message gets its topics…")._
404
-
405
- **Responses.** A record written in answer to someone's record names them in
406
- `respondingTo`: a `std.reaction`, `std.comment` or `std.repost` the author of
407
- what it is about, a `std.rsvp` the event's, a
408
- `std.vote` the poll's, a `std.ballot` the proposal's, a `std.pledge` the
409
- goal's, a `std.claim` the claimed record's, a `std.order` the listing's, and a
410
- `std.order-update` the order's. It is their topic, so "someone reacted to,
411
- commented on, or answered what I wrote" is `where: { "respondingTo":
412
- { "$contains": "$me" } }`, matched unread by a carrier's wake. The link says the same for a node
413
- that can read, but a carrier can't read a private space's links, so the
414
- account is written out. An app fills it from the author of the record it
415
- links to, and leaves it out when that is the writer themselves.
416
-
417
- A comment can carry all three: `respondingTo` the author of what it is
418
- about, `replyingTo` the author of the comment it answers, and `mentions`.
419
-
420
- Not every annotation has one. A `std.report` names nobody, so whoever is
421
- reported is not told, and a keeper can't tell whom it is about. Bookmarks,
422
- highlights, pins and tags are the writer's own, and what tracks the writer's
423
- own life (`std.progress`, `std.checkin`, `std.visit`, `std.meal`,
424
- `std.time-entry`, `std.reminder`) answers nobody.
425
-
426
- **People as topics.** Where a record names people it is about, they are its
427
- topics: `did` on `std.award` (given a badge), `std.follow` (followed) and
428
- `std.list-item` (put on a list); `from` and `to` on `std.settlement`; `to`
429
- and `people` on `std.call`. A `std.expense` names who owes a share inside
430
- `split`, a list of objects, which a topic can't reach (spec 02 §8.1: a path
431
- goes through objects only), so `owedBy` repeats those accounts as a list, at
432
- most 63 so that with `paidBy` every one is tagged: a record carries at most
433
- 64 tags.
434
-
435
- _Source: `packages/core/src/schemas/library/annotations.ts`, `packages/core/src/schemas/library/publishing.ts`, `packages/core/src/schemas/library/planning.ts`, `packages/core/src/schemas/library/community.ts`, `packages/core/src/schemas/library/money.ts`, `packages/core/src/schemas/library/social.ts`, `packages/core/src/schemas/library/media.ts`; `apps/example/src/derive/people.ts` (`respondingTo`), `apps/example/src/components/std/Reactions.tsx`, `apps/example/src/components/std/Comments.tsx`, `apps/example/src/components/apps/Polls.tsx`, `apps/example/src/components/apps/Decisions.tsx`, `apps/example/src/components/apps/Events.tsx`, `apps/example/src/components/apps/Marketplace.tsx`. Tests: `packages/core/tests/topics.test.ts` ("every standard collection that names people has them as topics…", "a report names nobody…", "a std.reaction is tagged for the person in its respondingTo…" and the rest of that list)._
436
-
437
- **Channels.** A space with more than one conversation lists `std.channel`
438
- records, by `position` then name, and a message is `in` its channel:
439
- `where: { 'link:in': key }` finds a channel's messages, and
440
- `include: { messages: { rel: 'in', from: 'std.message', count: true } }`
441
- counts them. A message in no channel is in the space's own room,
442
- which a chat shows first, as "general". In the `community` template only
443
- moderators and admins make or rename a channel. A channel is a label, not a boundary: every member reads
444
- every channel. Something only some members may read is a space of its own, or
445
- a direct message.
446
-
447
- **Direct messages.** A `std.direct` is sealed (`node.direct`, [direct-messages.md](direct-messages.md)):
448
- only the people in `to` and whoever wrote it can read `data`. A chat groups
449
- them into conversations by everyone in them, `to` plus the writer, and must
450
- show one it can't open as unreadable, not drop it. `to` is a topic, so
451
- "direct messages to me" is an automation of the account's own whose wake a
452
- keeper can match unread.
453
-
454
- _Source: `packages/core/src/schemas/library/publishing.ts` (`channel`, `direct`), `packages/core/src/privacy/direct.ts`, `apps/example/src/components/apps/Chat.tsx`. Tests: `packages/core/tests/direct.test.ts`._
455
-
456
- **Changes to earlier definitions.** Before v1 the library is reshaped
457
- without migrations, to keep to the rules above. The last such change merged
458
- `std.attachment`, `std.photo`, `std.video`, `std.folder` and `std.album` into
459
- one `std.file` (groups of files are `std.list`s); removed `std.booking` (a
460
- booking is a `std.claim` about a `std.slot`), `std.reference` (any link
461
- refers) and `std.bookmark` (a saved thing is a `std.list-item`); renamed
462
- `std.message`'s `channel` link and `std.task`'s `column` link to `in`, and
463
- dropped the task's `project` link (a task is `in` a project when it has no
464
- column, and a column is `in` its project); made `std.tag` one record per
465
- person, record and label; gave `std.track` a `file` link and `std.play` an
466
- `about` link to its track; and narrowed `std.vote` to polls, since a proposal
467
- is decided by `std.ballot`s. A space that holds an earlier definition keeps
468
- it until someone applies a blueprint that carries the new one.
469
-
470
- Since then ([#105](https://github.com/leifriksheim/minca/issues/105)), `std.comment` and `std.post` gained the same optional
471
- `mentions` and `replyingTo` as a message, and `std.note`, `std.doc-block` and
472
- `std.article` a `mentions`, all as topics; eleven annotations and answers
473
- gained `respondingTo` (Responses, above); `std.expense` gained `owedBy`; and
474
- the people fields of `std.task`, `std.award`, `std.follow`,
475
- `std.list-item`, `std.settlement`, `std.call` and `std.expense` became
476
- topics. A new topic tags only what is
477
- written under the new definition: records written before it carry no tags,
478
- so "mentions me" and "assigned to me" match from then on.
479
-
480
- **Also exported** from the same module (specified with their features):
481
-
482
- | Name | Body | Rules | Where |
483
- | --------------------- | --------------------------------------------------------------------------------------------------------- | ----------------- | ----------------------- |
484
- | `std.contact` | `did` ≤ 256 and `name` ≤ 200, required; `space` ≤ 256; `note` ≤ 2000; `blocked` boolean; `username` ≤ 320 | `onePer: [did]` | [contacts](contacts.md) |
485
- | `std.contact-request` | `to` ≤ 64 and `sealed` ≤ 16000, required | — | [contacts](contacts.md) |
486
- | `std.inbox` | `gen` ≥ 0 and `places` (1–3, each ≤ 200), required; `name` ≤ 64; `username` ≤ 320; `usernameUntil` | — | [inbox.md](inbox.md) |
487
- | `std.knock` | `space` ≤ 256, `name` ≤ 64 and `invite` ≤ 12000, all required; `username` ≤ 320 | `onePer: [space]` | [inbox.md](inbox.md) |
488
- | `std.space-invite` | `space` ≤ 256 and `invite` ≤ 12000, required | `onePer: [space]` | [contacts](contacts.md) |
489
-
490
- **Positions.** `position` is a string that sorts (by plain string comparison)
491
- where a record goes in a hand-made order. Digits are `0–9a–z`; a position
492
- never ends in `0`, so there is always room between two. Equal positions sort by
493
- key. A record without one goes at the end. `positionBetween(before, after)` in
494
- the library makes one; any string that sorts correctly is valid.
495
-
496
- _Source: `packages/core/src/schemas/fragments.ts`, `packages/core/src/schemas/library/` (one file per area), `packages/core/src/schemas/standard.ts` (`standardGroups`), `packages/core/src/schemas/index.ts` (`positionBetween`, `useSchemas`), `packages/core/src/schemas/contacts.ts`. Tests: `packages/core/tests/schemas.test.ts` ("the standard library", "standard nouns"), `packages/core/tests/contacts.test.ts`, `packages/core/tests/records-only.test.ts`._
497
-
498
- **Places and areas.** A place with a point also carries its `cells`: the
499
- geohash of `lat` and `lon` at precisions 3, 4, 5 and 6, coarsest first, about
500
- 156 km, 39 km, 4.9 km and 1.2 km across (`cellsOf(lat, lon)`). Geohash is
501
- Niemeyer's: longitude and latitude bits interleaved, longitude first, five to
502
- a character of `0123456789bcdefghjkmnpqrstuvwxyz`. For Grünerløkka in Oslo,
503
- `lat` 59.9226 and `lon` 10.7522 give `["u4x", "u4xs", "u4xsu", "u4xsus"]`.
336
+ Fill them from what the person picked, like an `@name` they chose or the
337
+ message they replied to. Never fill them by matching text.
504
338
 
505
- `std.event` and `std.listing` name `place.cells` as a topic, and `std.place`
506
- names `cells`, so each cell is a blind tag ([spec 02 §8](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)): a keeper that
507
- cannot read a private space can still hand over "listings in these cells".
508
- Tags match by equality only, which is why the cells are written out at each
509
- size instead of one long geohash and a prefix.
510
-
511
- To find what is within a radius, `cellsAround(lat, lon, km)` picks the finest
512
- precision whose cells are at least `km` wide and tall at that latitude, and
513
- returns the point's own cell and the eight around it. Everything inside the
514
- circle is in one of them, so a query or a keeper matches those (in a query,
515
- `{ "$or": [{ "place.cells": { "$contains": cell } }, …] }`), and the exact
516
- distance (`distanceKm`, haversine on a sphere of 6371.0088 km) decides the
517
- rest. It returns null for a radius over about 150 km, or a circle around a
518
- pole; then every place is a candidate. A record written by something that
519
- knows nothing of cells has none, and is found only by its point.
520
-
521
- `cells` say what `lat` and `lon` already say, and nothing checks that they
522
- agree: a peer only checks that the tags match the cells. An app that reads
523
- the body uses the point; a wrong cell only hides a record from area matches.
524
- A listing usually means someone's home, so the example's marketplace keeps
525
- only the part of town, moving the point to the middle of its precision 6 cell
526
- and leaving out the street.
339
+ They are topics, as is a message's `in` link. So an automation of the
340
+ account's own can ask for only what mentions it, replies to it, or is in one
341
+ channel, and a carrier's wake can match these unread:
342
+
343
+ ```json
344
+ { "where": { "mentions": { "$contains": "$me" } } }
345
+ ```
346
+
347
+ A `std.task`'s `assignees` is a topic the same way, so "assigned to me" is
348
+ `where: { "assignees": { "$contains": "$me" } }`.
349
+
350
+ A comment can be `about` any record. So commenting is how to mention someone
351
+ on a record whose definition has no `mentions`. Your own collections can
352
+ name a `mentions` field as a topic too. See
353
+ [automations](automations.md#the-accounts-own) and
354
+ [spec 02 §8](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
355
+
356
+ ## Responses
357
+
358
+ A record written in answer to someone's record names them in
359
+ `respondingTo`. It's the author of what it answers:
360
+
361
+ | Record | `respondingTo` |
362
+ | ------------------------------------------- | ----------------------------------- |
363
+ | `std.reaction`, `std.comment`, `std.repost` | the author of what it is about |
364
+ | `std.rsvp` | the event's author |
365
+ | `std.vote`, `std.ballot` | the poll's or the proposal's author |
366
+ | `std.pledge` | the goal's author |
367
+ | `std.claim` | the claimed record's author |
368
+ | `std.order`, `std.order-update` | the listing's or the order's author |
369
+
370
+ It's a topic, so "someone answered what I wrote" is
371
+ `where: { "respondingTo": { "$contains": "$me" } }`, and a carrier's wake can
372
+ match it unread. The link says the same to a node that can read, but a
373
+ carrier can't read a private space's links, so the account is written out.
374
+ Fill it from the author of the linked record, and leave it out when that's
375
+ the writer.
376
+
377
+ A comment can carry all three: `respondingTo`, `replyingTo` and `mentions`.
378
+
379
+ Some annotations name nobody. A `std.report` doesn't, so whoever is
380
+ reported isn't told, and a keeper can't tell whom it's about. Highlights,
381
+ pins and tags are the writer's own. What tracks the writer's own life
382
+ (`std.progress`, `std.checkin`, `std.visit`, `std.meal`, `std.time-entry`,
383
+ `std.reminder`) answers nobody.
384
+
385
+ ## People as topics
386
+
387
+ Where a record names the people it is about, they are its topics:
388
+
389
+ - `did` on `std.award`, `std.follow` and `std.list-item`
390
+ - `from` and `to` on `std.settlement`
391
+ - `to` and `people` on `std.call`
392
+ - `paidBy` and `owedBy` on `std.expense`
393
+
394
+ A topic can't reach into a list of objects, so `std.expense` repeats the
395
+ people in `split` as `owedBy`. It holds at most 63, so that with `paidBy`
396
+ each one is tagged: a record carries at most 64 tags. See
397
+ [spec 02 §8.1](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
398
+
399
+ ## Channels
400
+
401
+ A space with more than one conversation keeps `std.channel` records, sorted
402
+ by `position` then name. A message is `in` its channel.
403
+
404
+ ```ts
405
+ import type { NodeRecord } from '@minca/core';
406
+ declare const channel: NodeRecord;
407
+ // ---cut---
408
+ import type { Query } from '@minca/core';
409
+
410
+ // A channel's messages
411
+ const messages: Query = { collection: 'std.message', where: { 'link:in': channel.key } };
412
+
413
+ // Each channel, with how many messages it holds
414
+ const channels: Query = {
415
+ collection: 'std.channel',
416
+ include: { messages: { rel: 'in', from: 'std.message', count: true } },
417
+ };
418
+ ```
527
419
 
528
- Finding places by name is not part of the library. The example asks Photon
529
- (OpenStreetMap's data, `apps/shared/src/places.ts`), set by `VITE_MINCA_PLACES`,
530
- and shows OpenStreetMap's credit beside what it finds.
420
+ A message in no channel is in the space's own room, which a chat shows
421
+ first as "general". In the `community` template only moderators and admins
422
+ make or rename channels.
531
423
 
532
- _Source: `packages/core/src/schemas/geo.ts` (`geohash`, `cellsOf`, `cellsAround`, `aroundCell`, `distanceKm`), `apps/example/src/components/apps/Where.tsx`, `apps/shared/src/places.ts`. Tests: `packages/core/tests/geo.test.ts` (all)._
424
+ A channel is a label, not a boundary: every member reads every channel. For
425
+ something only some members may read, use a space of its own or a direct
426
+ message.
533
427
 
534
- ## Planned: what the library still waits on
428
+ ## Direct messages
535
429
 
536
- > **Planned.** Not normative. Each item names its own issue.
537
- >
538
- > - **References to other spaces** ([spec 02 §5.3](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md),
539
- > [#38](https://github.com/leifriksheim/minca/issues/38)). `std.follow`'s
540
- > `space` is a plain space id, and a repost or a list item can point only
541
- > within its own space.
542
- > - **`format`** ([spec 02 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)), to check `when`, `day` and `url`.
430
+ A `std.direct` is sealed. Only the people in `to` and whoever wrote it can
431
+ read `data`. Write and read it through `node.direct`
432
+ ([direct messages](direct-messages.md)).
543
433
 
544
- ## `std.call`
434
+ A chat groups direct messages into conversations by everyone in them: `to`
435
+ plus the writer. One it can't open must show as unreadable, not disappear.
436
+ `to` is a topic, so "direct messages to me" can be an automation of the
437
+ account's own that a keeper matches unread.
438
+
439
+ ## Positions
440
+
441
+ A `position` is a string that sorts where a record goes in a hand-made
442
+ order, by plain string comparison. Make one with `positionBetween`:
443
+
444
+ ```ts
445
+ import type { NodeRecord } from '@minca/core';
446
+ declare const above: NodeRecord<{ position: string }> | undefined;
447
+ declare const below: NodeRecord<{ position: string }> | undefined;
448
+ // ---cut---
449
+ import { positionBetween } from '@minca/core/schemas';
450
+
451
+ positionBetween(above?.body?.position, below?.body?.position);
452
+ ```
545
453
 
546
- Calls themselves are kept nowhere ([calls](../../calls/README.md)). Their history is a
547
- `std.call` record in the space, written only if the space defines `std.call`:
454
+ Either side may be missing, for the ends. Digits are `0–9a–z`, and a
455
+ position never ends in `0`, so there's always room between two. Equal
456
+ positions sort by key. A record without one goes at the end. Any string that
457
+ sorts correctly is valid.
548
458
 
549
- | Field | Type | Meaning |
550
- | ----------- | ------------------------------- | -------------------------------------------- |
551
- | `status` | `"missed"` \| `"ended"` | required |
552
- | `to` | string ≤ 256 | For a missed call: who was rung. |
553
- | `startedAt` | string ≤ 64 (ISO date) | required |
554
- | `endedAt` | string ≤ 64 (ISO date) | For an ended call. |
555
- | `people` | string[] ≤ 64 items, each ≤ 256 | For an ended call: every account seen in it. |
459
+ ## Places and areas
556
460
 
557
- Rules: none ([02](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)); who may change it is the space's grants.
461
+ A place with a point also carries its `cells`: the geohash of `lat` and
462
+ `lon` at precisions 3, 4, 5 and 6, coarsest first. They're about 156 km,
463
+ 39 km, 4.9 km and 1.2 km across. `cellsOf(lat, lon)` makes them.
464
+
465
+ For Grünerløkka in Oslo, `lat` 59.9226 and `lon` 10.7522 give
466
+ `["u4x", "u4xs", "u4xsu", "u4xsus"]`. Geohash here is Niemeyer's: longitude
467
+ and latitude bits interleaved, longitude first, five to a character of
468
+ `0123456789bcdefghjkmnpqrstuvwxyz`.
469
+
470
+ `std.event` and `std.listing` name `place.cells` as a topic, and `std.place`
471
+ names `cells`. So a keeper that can't read a private space can still hand
472
+ over "listings in these cells". Tags match only when equal, which is why
473
+ each size is written out instead of one long geohash.
474
+
475
+ ### Finding what is nearby
476
+
477
+ `cellsAround(lat, lon, km)` gives the nine cells that cover a circle: the
478
+ point's own cell and the eight around it, at the finest precision whose
479
+ cells are at least `km` across. Match any of them, then let the exact
480
+ distance decide:
558
481
 
559
482
  ```json
560
- {
561
- "status": "ended",
562
- "startedAt": "2026-09-26T10:00:00.000Z",
563
- "endedAt": "2026-09-26T10:14:02.311Z",
564
- "people": ["did:key:zDnaeSm3…", "did:key:zDnaeXL64…"]
565
- }
483
+ { "$or": [{ "place.cells": { "$contains": "u4xs" } }, { "place.cells": { "$contains": "u4xk" } }] }
566
484
  ```
567
485
 
568
- _Implementation detail:_ the call a device is in is kept in `sessionStorage`
569
- under `minca-call` as `{ space, call }`, so after a reload the page can offer to
570
- rejoin while the call is still going on.
486
+ `distanceKm` is haversine on a sphere of 6371.0088 km. `cellsAround` returns
487
+ null for a radius over about 150 km, or a circle around a pole. Then every
488
+ place is a candidate. A record written without cells is found only by its
489
+ point.
490
+
491
+ Nothing checks that `cells` agree with `lat` and `lon`. A peer only checks
492
+ that the tags match the cells. Apps that read the body use the point, so a
493
+ wrong cell only hides a record from area matches.
494
+
495
+ A listing usually means someone's home, so the example's marketplace keeps
496
+ only the part of town. It moves the point to the middle of its precision 6
497
+ cell and leaves out the street.
498
+
499
+ Finding places by name isn't part of the library. The example asks Photon,
500
+ which uses OpenStreetMap's data (set by `VITE_MINCA_PLACES`), and shows OpenStreetMap's credit beside the results.
501
+ See [spec 02 §8](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
502
+
503
+ ## Changing a definition
504
+
505
+ Before v1 the library changes without migrations. A space that holds an
506
+ earlier definition keeps it until someone applies a blueprint that carries
507
+ the new one.
508
+
509
+ A field that becomes a topic tags only what is written after the change.
510
+ Older records carry no tags, so "mentions me" or "assigned to me" match only
511
+ from then on.
512
+
513
+ Recent changes:
514
+
515
+ - `std.attachment`, `std.photo`, `std.video`, `std.folder` and `std.album`
516
+ became one `std.file`. Groups of files are `std.list`s.
517
+ - `std.booking` is a `std.claim` about a `std.slot`. `std.bookmark` is a
518
+ `std.list-item`. `std.reference` is gone: any link refers.
519
+ - `std.message`'s `channel` link and `std.task`'s `column` link are now `in`.
520
+ - `std.vote` is for polls only. A proposal is decided by `std.ballot`s.
521
+ - `mentions`, `replyingTo`, `respondingTo` and `owedBy` were added, and the
522
+ people fields became topics
523
+ ([#105](https://github.com/leifriksheim/minca/issues/105)).
524
+
525
+ ## Planned
526
+
527
+ > **Planned:** references to other spaces. `std.follow`'s `space` is a plain
528
+ > space id, and a repost or list item can only point within its own space
529
+ > ([#38](https://github.com/leifriksheim/minca/issues/38),
530
+ > [spec 02 §5.3](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)).
571
531
 
572
- _Source: `packages/calls/src/calls.ts`, `packages/core/src/schemas/library/publishing.ts` (`call`). Tests: `packages/calls/tests/calls.test.ts`._
532
+ > **Planned:** `format` in the schema dialect, to check `when`, `day` and
533
+ > `url` ([spec 02 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)).