@minca/core 0.1.13 → 0.1.15

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 (148) hide show
  1. package/README.md +2 -2
  2. package/dist/files/space-files.d.ts +15 -3
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +225 -37
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/index.d.ts +1 -1
  7. package/dist/index.d.ts.map +1 -1
  8. package/dist/index.js +1 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/network/introductions.d.ts +20 -7
  11. package/dist/network/introductions.d.ts.map +1 -1
  12. package/dist/network/introductions.js +9 -6
  13. package/dist/network/introductions.js.map +1 -1
  14. package/dist/network/mesh.d.ts.map +1 -1
  15. package/dist/network/mesh.js +88 -20
  16. package/dist/network/mesh.js.map +1 -1
  17. package/dist/network/relay-minca.d.ts +12 -1
  18. package/dist/network/relay-minca.d.ts.map +1 -1
  19. package/dist/network/relay-minca.js +14 -6
  20. package/dist/network/relay-minca.js.map +1 -1
  21. package/dist/network/relay-nostr.d.ts +14 -3
  22. package/dist/network/relay-nostr.d.ts.map +1 -1
  23. package/dist/network/relay-nostr.js +11 -9
  24. package/dist/network/relay-nostr.js.map +1 -1
  25. package/dist/network/relays.d.ts +26 -17
  26. package/dist/network/relays.d.ts.map +1 -1
  27. package/dist/network/relays.js +21 -28
  28. package/dist/network/relays.js.map +1 -1
  29. package/dist/network/rendezvous.d.ts +1 -1
  30. package/dist/network/rendezvous.d.ts.map +1 -1
  31. package/dist/network/rendezvous.js +2 -2
  32. package/dist/network/rendezvous.js.map +1 -1
  33. package/dist/node/actions.d.ts.map +1 -1
  34. package/dist/node/actions.js +54 -2
  35. package/dist/node/actions.js.map +1 -1
  36. package/dist/node/node.d.ts.map +1 -1
  37. package/dist/node/node.js +7 -7
  38. package/dist/node/node.js.map +1 -1
  39. package/dist/node/space-runtime.d.ts +1 -1
  40. package/dist/node/space-runtime.d.ts.map +1 -1
  41. package/dist/node/space-runtime.js +17 -5
  42. package/dist/node/space-runtime.js.map +1 -1
  43. package/dist/node/types.d.ts +4 -3
  44. package/dist/node/types.d.ts.map +1 -1
  45. package/dist/schema/collection-def.d.ts.map +1 -1
  46. package/dist/schema/collection-def.js +16 -5
  47. package/dist/schema/collection-def.js.map +1 -1
  48. package/dist/schemas/automations.d.ts +8 -0
  49. package/dist/schemas/automations.d.ts.map +1 -1
  50. package/dist/schemas/blueprints.d.ts +33 -0
  51. package/dist/schemas/blueprints.d.ts.map +1 -1
  52. package/dist/schemas/blueprints.js +63 -0
  53. package/dist/schemas/blueprints.js.map +1 -1
  54. package/dist/schemas/connectors.d.ts +12 -0
  55. package/dist/schemas/connectors.d.ts.map +1 -1
  56. package/dist/schemas/fragments.d.ts +22 -2
  57. package/dist/schemas/fragments.d.ts.map +1 -1
  58. package/dist/schemas/fragments.js +20 -12
  59. package/dist/schemas/fragments.js.map +1 -1
  60. package/dist/schemas/library/annotations.d.ts +30 -0
  61. package/dist/schemas/library/annotations.d.ts.map +1 -1
  62. package/dist/schemas/library/annotations.js +1 -0
  63. package/dist/schemas/library/annotations.js.map +1 -1
  64. package/dist/schemas/library/community.d.ts +28 -0
  65. package/dist/schemas/library/community.d.ts.map +1 -1
  66. package/dist/schemas/library/life.d.ts +62 -2
  67. package/dist/schemas/library/life.d.ts.map +1 -1
  68. package/dist/schemas/library/media.d.ts +36 -0
  69. package/dist/schemas/library/media.d.ts.map +1 -1
  70. package/dist/schemas/library/money.d.ts +74 -2
  71. package/dist/schemas/library/money.d.ts.map +1 -1
  72. package/dist/schemas/library/planning.d.ts +56 -0
  73. package/dist/schemas/library/planning.d.ts.map +1 -1
  74. package/dist/schemas/library/publishing.d.ts +80 -4
  75. package/dist/schemas/library/publishing.d.ts.map +1 -1
  76. package/dist/schemas/library/social.d.ts +44 -0
  77. package/dist/schemas/library/social.d.ts.map +1 -1
  78. package/docs/README.md +2 -2
  79. package/docs/actions.md +83 -56
  80. package/docs/blueprints-and-guides.md +41 -13
  81. package/docs/building-an-app.md +4 -4
  82. package/docs/collections.md +31 -3
  83. package/docs/node.md +15 -13
  84. package/docs/proposing-collections.md +42 -0
  85. package/docs/standard-library.md +26 -25
  86. package/docs/storage.md +33 -10
  87. package/package.json +2 -21
  88. package/dist/calls/calls.d.ts +0 -140
  89. package/dist/calls/calls.d.ts.map +0 -1
  90. package/dist/calls/calls.js +0 -861
  91. package/dist/calls/calls.js.map +0 -1
  92. package/dist/calls/index.d.ts +0 -4
  93. package/dist/calls/index.d.ts.map +0 -1
  94. package/dist/calls/index.js +0 -3
  95. package/dist/calls/index.js.map +0 -1
  96. package/dist/react/context.d.ts +0 -81
  97. package/dist/react/context.d.ts.map +0 -1
  98. package/dist/react/context.js +0 -97
  99. package/dist/react/context.js.map +0 -1
  100. package/dist/react/follow.d.ts +0 -11
  101. package/dist/react/follow.d.ts.map +0 -1
  102. package/dist/react/follow.js +0 -7
  103. package/dist/react/follow.js.map +0 -1
  104. package/dist/react/index.d.ts +0 -44
  105. package/dist/react/index.d.ts.map +0 -1
  106. package/dist/react/index.js +0 -40
  107. package/dist/react/index.js.map +0 -1
  108. package/dist/react/minca-auth.d.ts +0 -19
  109. package/dist/react/minca-auth.d.ts.map +0 -1
  110. package/dist/react/minca-auth.js +0 -36
  111. package/dist/react/minca-auth.js.map +0 -1
  112. package/dist/react/use-calls.d.ts +0 -21
  113. package/dist/react/use-calls.d.ts.map +0 -1
  114. package/dist/react/use-calls.js +0 -39
  115. package/dist/react/use-calls.js.map +0 -1
  116. package/dist/react/use-invite-link.d.ts +0 -24
  117. package/dist/react/use-invite-link.d.ts.map +0 -1
  118. package/dist/react/use-invite-link.js +0 -62
  119. package/dist/react/use-invite-link.js.map +0 -1
  120. package/dist/react/use-live.d.ts +0 -16
  121. package/dist/react/use-live.d.ts.map +0 -1
  122. package/dist/react/use-live.js +0 -56
  123. package/dist/react/use-live.js.map +0 -1
  124. package/dist/react/use-my-name.d.ts +0 -12
  125. package/dist/react/use-my-name.d.ts.map +0 -1
  126. package/dist/react/use-my-name.js +0 -38
  127. package/dist/react/use-my-name.js.map +0 -1
  128. package/dist/react/use-names.d.ts +0 -7
  129. package/dist/react/use-names.d.ts.map +0 -1
  130. package/dist/react/use-names.js +0 -13
  131. package/dist/react/use-names.js.map +0 -1
  132. package/dist/react/use-network.d.ts +0 -9
  133. package/dist/react/use-network.d.ts.map +0 -1
  134. package/dist/react/use-network.js +0 -33
  135. package/dist/react/use-network.js.map +0 -1
  136. package/dist/react/use-query.d.ts +0 -14
  137. package/dist/react/use-query.d.ts.map +0 -1
  138. package/dist/react/use-query.js +0 -26
  139. package/dist/react/use-query.js.map +0 -1
  140. package/dist/react/use-space.d.ts +0 -29
  141. package/dist/react/use-space.d.ts.map +0 -1
  142. package/dist/react/use-space.js +0 -57
  143. package/dist/react/use-space.js.map +0 -1
  144. package/dist/react/use-spaces.d.ts +0 -29
  145. package/dist/react/use-spaces.d.ts.map +0 -1
  146. package/dist/react/use-spaces.js +0 -78
  147. package/dist/react/use-spaces.js.map +0 -1
  148. package/docs/calls.md +0 -189
package/docs/actions.md CHANGED
@@ -29,42 +29,42 @@ It refuses: a non-object input; a missing required field; **any field not in
29
29
 
30
30
  The actions (R = readOnly, S = sensitive, D = destructive, P = peerContent):
31
31
 
32
- | Name | Flags | Input (required in **bold**) | Does |
33
- | ----------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
34
- | `node_info` | R | — | `{ did, sessionDid }` |
35
- | `spaces_list` | R | — | `spaces.list()` |
36
- | `spaces_create` | | **`name`**, **`visibility`** (`private`\|`public`), `roles` (`solo`\|`team`\|`community`\|`coop`; default `solo`) | Creates a space with that template. |
37
- | `spaces_invite` | S | **`space`**, `role`, `viewOnly` (bool) | `{ invite }`. `viewOnly: true` wins over `role`. |
38
- | `spaces_preview_invite` | R | **`invite`** | `spaces.preview()` |
39
- | `spaces_join` | D | **`invite`** | `spaces.join()` |
40
- | `spaces_leave` | D | **`space`** | `{ left: <id> }` |
41
- | `spaces_access` | R | **`space`** | `spaces.access()` |
42
- | `spaces_assign` | D | **`space`**, **`did`**, **`role`**, `remove` (bool) | `spaces.assign()`, or with `remove: true` `unassign()`. Then returns `spaces.access()`. |
43
- | `spaces_remove_member` | D | **`space`**, **`did`** | `spaces.removeMember()`. Then returns `spaces.access()`. |
44
- | `spaces_step_down` | D | **`space`**, `keep` | `spaces.stepDown()`. Then returns `spaces.access()`. |
45
- | `spaces_succeed` | D | **`space`**, **`successor`** | `spaces.succeed()`. Then returns `spaces.access()`. |
46
- | `spaces_close_invite` | D | **`space`**, **`key`** | Then returns `spaces.access()`. |
47
- | `spaces_status` | R | **`space`** | `spaces.status()` |
48
- | `spaces_profiles` | R P | **`space`** | `spaces.profiles()` |
49
- | `collections_list` | R P | **`space`**, `names` | Without `names`: each collection in a line, `{ name, title?, description?, records, links, guides? }` with `links` its link roles' names and `guides` the `std.guide` records about it, `{ key, title }`. With them: those collections in full, as `collections.list()` gives them; refuses a name the space doesn't have. |
50
- | `collections_standard` | R | `names` | Without `names`: `{ choose, areas }`, `choose` a line per kind of thing saying which collection holds it, and `areas` the library by area, each `{ name, title, description }`. With them: each definition in full, plus `summary`. Refuses a name not in the library ([what a `std.*` name means](standard-library.md#what-a-std-name-means); [spec 02 §6.4](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)). |
51
- | `collections_define` | D | **`space`**, **`name`**, **`schema`**, `title`, `description`, `version`, `history` (`latest`\|`all`), `links`, `rules`, `topics` | The definition, plus `summary`: what its rules say, in words. |
52
- | `collections_propose` | | **`space`**, **`title`**, **`collections`** (definitions, or standard names like `"std.event"`), `description`, `updates` (key of the blueprint it replaces) | Writes a `std.blueprint`, a standard name stored as the library's definition; returns `{ key, proposed, applied: false, next, collections, warnings? }`, warning when it would change a collection another applied blueprint uses, when a collection of its own looks like a standard one (it keeps a file, like `std.file`; it is something at a time, like `std.event`), and when a link of its own says where a record sits, which the library calls `in` (`lookalikes`). Warnings don't refuse: the person applying it decides. Refuses an `updates` that names no blueprint in the space, and a `std.*` collection that is not the library's ([standard library](standard-library.md)). |
53
- | `collections_proposals` | R P | **`space`** | Blueprints: `key`, `title`, `description`, `proposedBy`, `recordsOnly?`, `updates?`, `applied`, `superseded`, `problem`, `collections[]` (each `name`, `status`, `summary`, `changes`, and `usedBy`: the applied blueprints a change would touch). |
54
- | `collections_apply` | D | **`space`**, **`key`** | `applyBlueprint()`: `{ applied, collections }`. Needs a grant of `/collection/define` in the space, and a note that grants it. |
55
- | `collections_delete` | D | **`space`**, **`name`** | `collections.delete()` |
56
- | `records_list` | R P | **`space`**, `collection`, `limit`, `newestFirst` | `records.list()` |
57
- | `records_query` | R P | **`space`**, **`collection`**, `where`, `include`, `sort`, `limit`, `cursor` | `records.query()` ([02](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)) |
58
- | `records_get` | R P | **`space`**, **`key`** | `records.get()` |
59
- | `records_history` | R P | **`space`**, **`key`** | `records.history()` |
60
- | `records_put` | | **`space`**, **`collection`**, **`body`**, `key`, `links` | `records.put()` |
61
- | `records_linked` | R P | **`space`**, **`key`**, `rel`, `collection` | `records.linked()` |
62
- | `records_can` | R | **`space`**, **`action`** (`create`\|`edit`\|`delete`), **`target`** | `records.can()` → boolean |
63
- | `records_update` | D | **`space`**, **`key`**, **`body`**, `links` | `records.update()` |
64
- | `records_delete` | D | **`space`**, **`key`** | `{ deleted: <key> }` |
65
- | `activity_set` | | **`space`**, **`about`** (a record's key), **`label`** (≤ 120), `state` (`working`\|`waiting`\|`done`\|`failed`; default `working`) | Your `std.activity` about that record, made or changed ([standard library](standard-library.md)); refuses in a space that keeps no `std.activity`. |
66
- | `direct_list` | R P | **`space`**, `with` (a member's DID), `limit` (default 30) | The direct messages by or to you, opened, oldest first, the newest `limit`; with `with`, only those between you and them ([direct messages](direct-messages.md)). |
67
- | `direct_send` | | **`space`**, **`to`** (DIDs), **`text`** | `direct.send()`: seals it for them and you. |
32
+ | Name | Flags | Input (required in **bold**) | Does |
33
+ | ----------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
34
+ | `node_info` | R | — | `{ did, sessionDid }` |
35
+ | `spaces_list` | R | — | `spaces.list()` |
36
+ | `spaces_create` | | **`name`**, **`visibility`** (`private`\|`public`), `roles` (`solo`\|`team`\|`community`\|`coop`; default `solo`) | Creates a space with that template. |
37
+ | `spaces_invite` | S | **`space`**, `role`, `viewOnly` (bool) | `{ invite }`. `viewOnly: true` wins over `role`. |
38
+ | `spaces_preview_invite` | R | **`invite`** | `spaces.preview()` |
39
+ | `spaces_join` | D | **`invite`** | `spaces.join()` |
40
+ | `spaces_leave` | D | **`space`** | `{ left: <id> }` |
41
+ | `spaces_access` | R | **`space`** | `spaces.access()` |
42
+ | `spaces_assign` | D | **`space`**, **`did`**, **`role`**, `remove` (bool) | `spaces.assign()`, or with `remove: true` `unassign()`. Then returns `spaces.access()`. |
43
+ | `spaces_remove_member` | D | **`space`**, **`did`** | `spaces.removeMember()`. Then returns `spaces.access()`. |
44
+ | `spaces_step_down` | D | **`space`**, `keep` | `spaces.stepDown()`. Then returns `spaces.access()`. |
45
+ | `spaces_succeed` | D | **`space`**, **`successor`** | `spaces.succeed()`. Then returns `spaces.access()`. |
46
+ | `spaces_close_invite` | D | **`space`**, **`key`** | Then returns `spaces.access()`. |
47
+ | `spaces_status` | R | **`space`** | `spaces.status()` |
48
+ | `spaces_profiles` | R P | **`space`** | `spaces.profiles()` |
49
+ | `collections_list` | R P | **`space`**, `names` | Without `names`: each collection in a line, `{ name, title?, description?, records, links, guides? }` with `links` its link roles' names and `guides` the `std.guide` records about it, `{ key, title }`. With them: those collections in full, as `collections.list()` gives them; refuses a name the space doesn't have. |
50
+ | `collections_standard` | R | `names` | Without `names`: `{ choose, areas }`, `choose` a line per kind of thing saying which collection holds it, and `areas` the library by area, each `{ name, title, description }`. With them: each definition in full, plus `summary`. Refuses a name not in the library ([what a `std.*` name means](standard-library.md#what-a-std-name-means); [spec 02 §6.4](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)). |
51
+ | `collections_define` | D | **`space`**, **`name`**, **`schema`**, `title`, `description`, `version`, `history` (`latest`\|`all`), `links`, `rules`, `topics` | The definition, plus `summary`: what its rules say, in words. |
52
+ | `collections_propose` | | **`space`**, **`title`**, **`collections`** (definitions, or standard names like `"std.event"`), `description`, `updates` (key of the blueprint it replaces), `examples` (versions to try its contracts on) | Writes a `std.blueprint`, a standard name stored as the library's definition; returns `{ key, proposed, applied: false, next, collections, warnings? }`, warning when it would change a collection another applied blueprint uses, when a collection of its own looks like a standard one (it keeps a file, like `std.file`; it is something at a time, like `std.event`), and when a link of its own says where a record sits, which the library calls `in` (`lookalikes`), and when a collection has a contract no example tried. Warnings don't refuse: the person applying it decides. Examples that come out other than expected do: nothing is proposed ([proposing collections](proposing-collections.md#trying-a-contract-before-proposing-it)). Refuses an `updates` that names no blueprint in the space, and a `std.*` collection that is not the library's ([standard library](standard-library.md)). |
53
+ | `collections_proposals` | R P | **`space`** | Blueprints: `key`, `title`, `description`, `proposedBy`, `recordsOnly?`, `updates?`, `applied`, `superseded`, `problem`, `collections[]` (each `name`, `status`, `summary`, `changes`, and `usedBy`: the applied blueprints a change would touch). |
54
+ | `collections_apply` | D | **`space`**, **`key`** | `applyBlueprint()`: `{ applied, collections }`. Needs a grant of `/collection/define` in the space, and a note that grants it. |
55
+ | `collections_delete` | D | **`space`**, **`name`** | `collections.delete()` |
56
+ | `records_list` | R P | **`space`**, `collection`, `limit`, `newestFirst` | `records.list()` |
57
+ | `records_query` | R P | **`space`**, **`collection`**, `where`, `include`, `sort`, `limit`, `cursor` | `records.query()` ([02](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)) |
58
+ | `records_get` | R P | **`space`**, **`key`** | `records.get()` |
59
+ | `records_history` | R P | **`space`**, **`key`** | `records.history()` |
60
+ | `records_put` | | **`space`**, **`collection`**, **`body`**, `key`, `links` | `records.put()` |
61
+ | `records_linked` | R P | **`space`**, **`key`**, `rel`, `collection` | `records.linked()` |
62
+ | `records_can` | R | **`space`**, **`action`** (`create`\|`edit`\|`delete`), **`target`** | `records.can()` → boolean |
63
+ | `records_update` | D | **`space`**, **`key`**, **`body`**, `links` | `records.update()` |
64
+ | `records_delete` | D | **`space`**, **`key`** | `{ deleted: <key> }` |
65
+ | `activity_set` | | **`space`**, **`about`** (a record's key), **`label`** (≤ 120), `state` (`working`\|`waiting`\|`done`\|`failed`; default `working`) | Your `std.activity` about that record, made or changed ([standard library](standard-library.md)); refuses in a space that keeps no `std.activity`. |
66
+ | `direct_list` | R P | **`space`**, `with` (a member's DID), `limit` (default 30) | The direct messages by or to you, opened, oldest first, the newest `limit`; with `with`, only those between you and them ([direct messages](direct-messages.md)). |
67
+ | `direct_send` | | **`space`**, **`to`** (DIDs), **`text`** | `direct.send()`: seals it for them and you. |
68
68
 
69
69
  The blueprint the three proposal actions read and write (`collections_propose`,
70
70
  `collections_proposals`, `collections_apply`), and the guides `collections_list`
@@ -103,26 +103,53 @@ _Source: `packages/core/src/node/actions.ts` (`callAction`, `offeredActions`), `
103
103
 
104
104
  ## The agent on a computer
105
105
 
106
- _Implementation detail of the CLI._ Each `minca connect` makes a new P-256
107
- key and keeps it as JWK in `<home>/agent/key.json` (mode 0600), then the grant
108
- made out to it in `grant.json`, each written whole, and the spaces in `data/`.
109
- A new key each time, since a key the account home revoked stays revoked in
110
- every space, so a new note made out to it would write nothing. `minca mcp`
111
- then starts a node of its own: signer `grantSigner(grant)`, session key = the
112
- agent key, the grant's keys when present and relays = the grant's ∪
113
- `$MINCA_RELAYS` (default `wss://minca.fly.dev`) (`nodeOptionsFromGrant`),
114
- WebRTC via `node-datachannel`; joins any granted spaces it lacks (`joinGranted`); wraps the node with `asAgent`; holds every
115
- space; and serves MCP over stdio: `offeredActions({ agent: true })`, without
116
- the `PERSON_ONLY` actions or direct messages ([actions](#actions)).
117
-
118
- Only one `minca mcp` or `minca agent` with the same `--home` runs at a time:
119
- both sign with the one agent key, which is held under a lock in the agent's
120
- folder, so a second says the agent is already running and stops.
121
-
122
- A running `minca mcp` watches `grant.json`, and looks every 30 s as well.
123
- When `minca connect` writes a new key and grant that check out, it closes its
124
- node and starts one under them, keeping the lock, so the session using it
106
+ _Implementation detail of the CLI._ A key signs in one process at a time,
107
+ or its log forks (spec 02 §4.10). So each session running the agent at once,
108
+ a `minca mcp` per Claude window or a `minca agent`, has a key of its own, in a
109
+ numbered slot: `<home>/agent/<n>/` (1 to 16) holds `key.json`, the P-256 key
110
+ as JWK (mode 0600), the grant made out to it in `grant.json`, each written
111
+ whole, its lock, and `stores/`, what only that session keeps (its key's
112
+ places in its logs among them). The spaces are in one folder,
113
+ `<home>/agent/spaces/`, under a path per account, that every session reads
114
+ and writes at once the way clients share a data folder (spec 05 §14.5,
115
+ `folderStores`): what one session synced, the next starts from. It is a cache
116
+ of this CLI's, not a data folder another program opens.
117
+
118
+ Each session is a connection of its own at the account home, named "Agent on
119
+ <host>, session <n>", and is disconnected there on its own. A session whose
120
+ key is revoked forgets its slot's grant, so the next session there asks to be
121
+ allowed again, with a new key.
122
+
123
+ A session claims the first connected slot no other process holds, else the
124
+ first not connected yet. In that one, `minca mcp` offers only `agent_connect`:
125
+ the person allows this session at their account home and gives the model the
126
+ code it shows, once; the slot keeps its key and grant for later sessions.
127
+ `minca connect` at a terminal connects slot 1 and forgets the other slots'
128
+ grants, so each session after asks for its own again rather than run on a
129
+ note the person may have revoked; a session connected to another account
130
+ has every slot connected to the first forget its grant, so no later session
131
+ is handed one and writes as that account. Each connection is named for its
132
+ slot: "Agent on <host>", then ", session <n>" from slot 2. A slot's lock is
133
+ numbered files, `lock.<n>`, each linked into place whole: the highest is the
134
+ lock, taken over once its process is gone by linking the next number, and
135
+ let go of by writing `released` into it, so no number is used twice. Only one
136
+ session of an account runs its automations, under
137
+ `<home>/agent/automations-<account key>.lock`. A new key each time, since a key the
138
+ account home revoked stays revoked in every space, so a new note made out to
139
+ it would write nothing.
140
+
141
+ A session's node: signer `grantSigner(grant)`, session key = the slot's key,
142
+ the grant's keys when present and relays = the grant's ∪ `$MINCA_RELAYS`
143
+ (default `wss://minca.fly.dev`) (`nodeOptionsFromGrant`), WebRTC via
144
+ `node-datachannel`; it joins any granted spaces it lacks (`joinGranted`);
145
+ wraps the node with `asAgent`; holds every space; and serves MCP over stdio:
146
+ `offeredActions({ agent: true })`, without the `PERSON_ONLY` actions or
147
+ direct messages ([actions](#actions)).
148
+
149
+ A running session watches its slot's `grant.json`, and looks every 30 s as
150
+ well. When `minca connect` writes a new key and grant there that check out, it
151
+ closes its node and starts one under them, keeping the slot, so the session
125
152
  needs no restart. When the node hears that its key was revoked in a space, a
126
153
  tool that fails says so, and that connecting again fixes it.
127
154
 
128
- _Source: `packages/cli/src/agent.ts` (`connectAgent`, `startAgentNode`, `reloadOnConnect`), `packages/cli/src/writer-keys.ts` (`holdLock`), `packages/cli/src/mcp.ts`, `packages/cli/src/main.ts` (`minca mcp`). Tests: `packages/core/tests/records-only.test.ts` ("an agent running a node of its own"), `packages/cli/tests/cli.test.ts` ("MCP"), `packages/cli/tests/agent-reconnect.test.ts` (all)._
155
+ _Source: `packages/cli/src/agent.ts` (`claimSlot`, `connectAgent`, `reconnectAgent`, `startAgentNode`, `reloadOnConnect`), `packages/cli/src/writer-keys.ts` (`holdLock`), `packages/cli/src/mcp.ts`, `packages/cli/src/main.ts` (`minca mcp`). Tests: `packages/core/tests/records-only.test.ts` ("an agent running a node of its own"), `packages/cli/tests/cli.test.ts` ("MCP"), `packages/cli/tests/agent-reconnect.test.ts` (all), `packages/cli/tests/agent-slot-lock.test.ts` (all), `packages/cli/tests/writer-keys.test.ts` ("a lock number is never used twice, so one taker that stalled can’t hold it beside another")._
@@ -168,7 +168,7 @@ its app's collections and the people in its space: it lists and writes
168
168
  records as the person looking, asks what they may do (`can`), gets someone's
169
169
  picture (`picture`), and asks the page to show a record or a person
170
170
  (`open`), or the record one of its own links to (`open` with `link`: the
171
- message a file was shared on). Following a link is the one way past its collections. The bridge answers the same whether or not the record is there, and never opens the space's own records (`sys.*`, `launcher.app`); but the page visibly opens a record that is there, for the person, who can see it anyway, so a screen that already knows a key could notice, from outside, that it exists. What a sealed frame can't do, the page does for it when it asks,
171
+ 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,
172
172
  after checking the request: it searches for places and asks where the person
173
173
  is (`places`), opens http and https pages (`link`), saves text files
174
174
  (`save`), keeps a few kilobytes per app on the device (`remember`, `recall`),
@@ -180,18 +180,46 @@ the screen.
180
180
  `collections`, the ones it `shows`: the ones whose records it is the place
181
181
  to open (`shows: ["std.message"]` for a chat). Whatever asks the example app
182
182
  to open a record, a screen's `open` or a link beside a record, goes to the
183
- app that shows that record's collection, the one open first, and that app's
183
+ app that shows that record's collection: the one open, if it does, else the
184
+ only one, else the one the person picks when asked, and that app's
184
185
  screen is handed the record's key (`minca.shown`, `minca.onShow`, the kit's
185
186
  `useShown`) to scroll to or open, but only of a collection it shows, which
186
187
  it could list anyway. That app does learn which of those records the person
187
188
  opens from elsewhere, which is why only someone who may define collections
188
- adds an app. With no app that shows it, the record
189
- opens beside whatever is open. So the Files app opens a file's message in
189
+ adds an app. With no app that shows it, or when that app opens one of its
190
+ own (a poll's title in Polls, for its comments), the record opens beside
191
+ whatever is open. So the Files app opens a file's message in
190
192
  the chat, and a chat's file in Files, without either knowing the other. An
191
193
  app that names a collection in `shows` must do something with what it is
192
194
  handed. The kit's `<Record>` draws any standard record as one line the same
193
195
  way in every app, and opens it this way when clicked.
194
196
 
197
+ **Sharing a record into an app.** A screen can't list or read what its app
198
+ doesn't name, but a person can hand it one record, as a page gets only the
199
+ file a person picks for it. `minca.pick` asks the page to show a finder over
200
+ the whole space, and gives the screen the record the person chooses, or
201
+ null. The screen may then link one of its records to it with `shares`, like
202
+ a message, and anyone's screen reads it back through that link
203
+ (`minca.get(key, { link: 'shares' })`), read only. `shares` is the only role
204
+ a screen reads through: a file about a diary entry, or a reaction to it,
205
+ shares nothing, so a screen reads beyond its collections only records the
206
+ person picked, or that someone writing its collections shares (a member, an
207
+ agent, another app). That binds the screen, not its author: a member who
208
+ wrote a screen can share any record into its collections from their own
209
+ node, and the screen reads it. A shared record comes with its files' keys,
210
+ though not their bytes. A screen writes
211
+ a link only to a record of its own collections, one the person picked for
212
+ it, or one the record already has, refused alike whether or not the target
213
+ is here (so a link to a record that hasn't arrived yet waits until it has):
214
+ a screen never links out on its own, though like anything it reads, it can
215
+ copy what was shared into its own records. A screen may ask to pick as often
216
+ as it likes, and start the search from its own text; what it gets is still
217
+ only what the person chooses, in a space they can read anyway: Enter takes
218
+ the top match only once the person has typed. A chat
219
+ shares a poll without being able to read polls; `/` typed into an empty
220
+ message, or its `/` button, picks one; so does a comment box (the kit's
221
+ `useShare`).
222
+
195
223
  A screen also sends live messages, kept nowhere, to the other devices that
196
224
  have the same app open in the space (`live.send`, `live.on`): for cursors,
197
225
  typing, who is here, or a game. Each goes as a live message of the space
@@ -223,7 +251,7 @@ defines its collections and writes a copy of it, naming where it came from
223
251
  (`template: "kanban"`), and from then on the space changes its copy like any
224
252
  other app.
225
253
 
226
- _Source: `apps/example/src/components/apps/launcher.ts` (`addTemplate`), `apps/example/src/components/apps/screens.ts`, `apps/example/src/components/apps/ScreenFrame.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` ("adding a ready-made app copies it into the space once, with its collections and first records"), `apps/example/tests/screens.test.ts` ("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 hears the same app's screens on other devices, as who sent it, and no other app's")._
254
+ _Source: `apps/example/src/components/apps/launcher.ts` (`addTemplate`), `apps/example/src/components/apps/screens.ts`, `apps/example/src/components/apps/ScreenFrame.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` ("adding a ready-made app copies it into the space once, with its collections and first records"), `apps/example/tests/screens.test.ts` ("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")._
227
255
 
228
256
  ## Describing a collection
229
257
 
@@ -260,7 +288,7 @@ _Source: `packages/core/src/records/describe.ts`. Tests: `packages/core/tests/re
260
288
 
261
289
  An app decides it can open a space by finding a collection with the right
262
290
  **name**. Chat opens any `std.message`, whatever its fields and rules. And a space whose definition is a little older than the
263
- app's (a `std.message` without the `shares` link) stays that way, because the
291
+ app's (a `std.message` or `std.comment` without the `shares` link) stays that way, because the
264
292
  library skips a collection the space already has. Whether an app can use a
265
293
  definition it did not write is a question for the app, not for peers: a peer
266
294
  stores and judges every record the same way whatever the answer.
@@ -296,8 +324,8 @@ Anything the checker cannot decide is a break.
296
324
  this is a walk of both schemas: `type` sets contained (`integer` inside
297
325
  `number`); a field one side relies on is `required` on the other; numeric
298
326
  and length ranges contained; `enum`, `const` and `oneOf` value sets
299
- contained; recurse into `properties` and `items`. `title`, `description`
300
- and `x-choicesFrom` are ignored. A field only one side mentions is ignored,
327
+ contained; recurse into `properties` and `items`. `title`, `description`,
328
+ `x-choicesFrom` and every other `x-*` annotation are ignored. A field only one side mentions is ignored,
301
329
  unless that side requires it or closes the schema
302
330
  (`additionalProperties: false`).
303
331
  - **Links.** A link role the app uses is declared in the space; where it may
@@ -385,15 +413,15 @@ which field is the title or that votes are shown as counts. The plan adds
385
413
  optional hints to a definition:
386
414
 
387
415
  - which field is the record's **title**;
388
- - a field's **role** (a date, a person, an amount);
389
416
  - **tallies**: "show as a count" of records linking here, the way
390
417
  `x-choicesFrom` already makes vote-style counts possible;
391
418
  - values **worked out on read**: "voting closes Friday", "who hasn't
392
419
  answered". Each reader computes them from the records and its own clock, so
393
420
  nothing has to run anywhere.
394
421
 
422
+ A field's kind (a person) is already its `x-kind` ([collections](collections.md#schemas)).
395
423
  Like `x-choicesFrom`, hints are display only and never checked when
396
- validating, and [`compare`](#compatible-definitions) ignores them. They would go in a new
397
- top-level definition member rather than as schema keywords: unknown
398
- top-level members are ignored by today's peers, while an unknown schema
399
- keyword makes the definition invalid ([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.
424
+ validating, and [`compare`](#compatible-definitions) ignores them. A hint
425
+ about one field is an `x-*` keyword on it; one about the whole record goes
426
+ in a top-level definition member, which today's peers ignore when they
427
+ 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.
@@ -12,7 +12,7 @@ the app cannot write anywhere it was not given.
12
12
 
13
13
  ```tsx
14
14
  import { createMincaConnection } from '@minca/core/session';
15
- import { MincaProvider, useConnection } from '@minca/core/react';
15
+ import { MincaProvider, useConnection } from '@minca/react';
16
16
 
17
17
  const connection = createMincaConnection({
18
18
  home: 'https://home.minca.social/connect', // a suggestion: the person may use their own
@@ -67,7 +67,7 @@ element and as a React component.
67
67
 
68
68
  ```tsx
69
69
  import { createMincaAuth } from '@minca/core/session';
70
- import { MincaProvider, MincaAuth, useMinca } from '@minca/core/react';
70
+ import { MincaProvider, MincaAuth, useMinca } from '@minca/react';
71
71
 
72
72
  const auth = createMincaAuth({ appName: 'Todo', network: { relays: ['wss://minca.fly.dev'] } });
73
73
 
@@ -135,7 +135,7 @@ await node.spaces.closeInvite(space.id, invite); // nobody else joins with it
135
135
 
136
136
  ## React hooks
137
137
 
138
- All from `@minca/core/react`, below a `MincaProvider`:
138
+ All from `@minca/react`, below a `MincaProvider`:
139
139
 
140
140
  | Hook | Gives |
141
141
  | ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
@@ -177,7 +177,7 @@ takes the invite out of a pasted link, and `useInviteLink()` reads the one the
177
177
  page was opened with:
178
178
 
179
179
  ```tsx
180
- import { inviteLink, useInviteLink, useMyName, useNode } from '@minca/core/react';
180
+ import { inviteLink, useInviteLink, useMyName, useNode } from '@minca/react';
181
181
 
182
182
  const link = inviteLink(await node.spaces.invite(space.id, { short: true })); // https://app.example/#invite=…
183
183
 
@@ -45,13 +45,39 @@ What gets stored is JSON Schema, in a small subset every app agrees on:
45
45
  `maximum`, `minLength`, `maxLength`, `minItems`, `maxItems`,
46
46
  `additionalProperties` (true or false), `title`, `description`
47
47
 
48
- and two that say what a value means, so any app can show it well:
48
+ and three that say what a value means, so any app can show it well:
49
49
 
50
50
  - `oneOf: [{ const, title }]`: fixed choices with labels.
51
51
  - `x-choicesFrom: { rel, field }`: the value picks from a list in the record
52
52
  this one links to as `rel`, in its field `field`. A number is a position in
53
53
  that list; anything else is the option itself. A vote's `choice` picks from
54
54
  its poll's `options`. It is a display hint, never checked when validating.
55
+ - `x-kind: "<name>"`: what kind of value a field holds. The names apps read:
56
+
57
+ | `x-kind` | The value | An app shows |
58
+ | ---------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
59
+ | `did` | an account's DID, `did:key:z…` ([spec 01 §4](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md)) | who it is, and a list of people to pick from |
60
+ | `when` | a moment, RFC 3339, or a whole day, `YYYY-MM-DD` | the time in the reader's words, a date and time picker with "all day" |
61
+ | `day` | a day, `YYYY-MM-DD` | the day in the reader's words, a date picker |
62
+ | `url` | a web address | a link, opened only when it is `http` or `https` |
63
+ | `money` | `{ amount, currency }`, `amount` a decimal string | `€12.50` in the reader's format; an amount and a currency |
64
+ | `file` | a file, as `records.addFile` gives it | its name and size, a picture when it is one; a file picker |
65
+ | `image` | `{ blob, alt }`: a picture and what it shows | the picture; a picker and its description |
66
+ | `position` | a sort key (`positionBetween`) | nothing: it orders records, nobody reads it |
67
+
68
+ Each is what the fragment of the same name writes (`person` writes `did`,
69
+ `blob` writes `file`). An app shows a kind it doesn't know as the plain
70
+ value. A definition
71
+ already in a space keeps the labels it was written with: a space defined
72
+ before these labels shows those fields plainly until the collection is
73
+ redefined.
74
+
75
+ Any keyword starting `x-` is an annotation like these: any JSON, and it says
76
+ nothing about whether a body fits. A new one, or a new `x-kind`, is a row
77
+ here, never a change to the protocol. With Zod, add one with
78
+ `.meta({ 'x-kind': 'did' })`. Keep annotations to plain values: a validator
79
+ that can't build from a schema (an `$id` inside one is enough) checks
80
+ nothing against it, so the collection's shape goes unchecked.
55
81
 
56
82
  Anything else, like `pattern` or `format`, is refused when you define the
57
83
  collection, with the reason. A Zod `.regex()` or `.email()` fails for that
@@ -69,7 +95,9 @@ unknown keywords ignored, so a space written by a newer app that allows more
69
95
  stays readable by an older one. Every failing leaf is reported, not only the
70
96
  first, with a JSON Pointer to the value. The validator is
71
97
  `@cfworker/json-schema`, which interprets rather than compiles, so it runs
72
- under a strict CSP.
98
+ under a strict CSP. A schema it can't build a validator from (it follows
99
+ `$id`s into any key it doesn't know, so a bad one in an annotation is enough)
100
+ checks nothing, like an invalid definition; reading never fails on it.
73
101
 
74
102
  A record that doesn't fit the schema is still kept and synced, and comes back
75
103
  with `conforms: false` and the issues. Shape is checked when you write, not
@@ -77,7 +105,7 @@ enforced on arrival, because two peers may have seen different versions of a
77
105
  definition ([spec 02 §9.6](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)).
78
106
  Rules, below, are enforced everywhere.
79
107
 
80
- _Source: `packages/core/src/schema/collection-def.ts` (`validateJsonSchema`, `toJsonSchema`, `asStandardSchema`), `packages/core/src/node/space-runtime.ts` (`contentIssues`). Tests: `packages/core/tests/space-catalog.test.ts` ("validate and reject within the supported subset", "an unknown keyword is ignored when validating, so newer spaces stay readable", "choices can carry labels, or come from a linked record", "a record that does not fit is kept and flagged when it arrives, never rejected"), `packages/core/tests/schemas.test.ts` ("schemas from a validator you already use")._
108
+ _Source: `packages/core/src/schema/collection-def.ts` (`validateJsonSchema`, `toJsonSchema`, `asStandardSchema`), `packages/core/src/node/space-runtime.ts` (`contentIssues`). Tests: `packages/core/tests/space-catalog.test.ts` ("validate and reject within the supported subset", "an unknown keyword is ignored when validating, so newer spaces stay readable", "choices can carry labels, or come from a linked record", "an x-\* keyword is an annotation: any one publishes, and no value is checked against it", "a record that does not fit is kept and flagged when it arrives, never rejected"), `packages/core/tests/attacks.test.ts` ("a definition the validator can't use can't break reading the collection, or the space"), `packages/core/tests/schemas.test.ts` ("schemas from a validator you already use")._
81
109
 
82
110
  ## Links
83
111