@minca/core 0.1.16 → 0.1.17

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 (65) hide show
  1. package/README.md +8 -8
  2. package/dist/elements/auth-styles.d.ts +1 -1
  3. package/dist/elements/auth-styles.d.ts.map +1 -1
  4. package/dist/elements/auth-styles.js +14 -5
  5. package/dist/elements/auth-styles.js.map +1 -1
  6. package/dist/elements/minca-auth.d.ts.map +1 -1
  7. package/dist/elements/minca-auth.js +18 -15
  8. package/dist/elements/minca-auth.js.map +1 -1
  9. package/dist/network/ws-transport.d.ts.map +1 -1
  10. package/dist/network/ws-transport.js +3 -0
  11. package/dist/network/ws-transport.js.map +1 -1
  12. package/dist/node/actions.d.ts +2 -0
  13. package/dist/node/actions.d.ts.map +1 -1
  14. package/dist/node/actions.js +39 -20
  15. package/dist/node/actions.js.map +1 -1
  16. package/dist/node/api.d.ts +1 -0
  17. package/dist/node/api.d.ts.map +1 -1
  18. package/dist/node/api.js +1 -0
  19. package/dist/node/api.js.map +1 -1
  20. package/dist/node/node-carriers.d.ts.map +1 -1
  21. package/dist/node/node-carriers.js +6 -1
  22. package/dist/node/node-carriers.js.map +1 -1
  23. package/dist/node/node-hosting.d.ts.map +1 -1
  24. package/dist/node/node-hosting.js +11 -4
  25. package/dist/node/node-hosting.js.map +1 -1
  26. package/dist/node/node.d.ts.map +1 -1
  27. package/dist/node/node.js +1 -0
  28. package/dist/node/node.js.map +1 -1
  29. package/dist/node/space-holding.d.ts +7 -3
  30. package/dist/node/space-holding.d.ts.map +1 -1
  31. package/dist/node/space-holding.js +90 -18
  32. package/dist/node/space-holding.js.map +1 -1
  33. package/dist/node/space-peers.d.ts.map +1 -1
  34. package/dist/node/space-peers.js +58 -24
  35. package/dist/node/space-peers.js.map +1 -1
  36. package/dist/node/space-runtime.d.ts +6 -0
  37. package/dist/node/space-runtime.d.ts.map +1 -1
  38. package/dist/node/space-runtime.js +19 -0
  39. package/dist/node/space-runtime.js.map +1 -1
  40. package/dist/node/space-writing.d.ts +2 -0
  41. package/dist/node/space-writing.d.ts.map +1 -1
  42. package/dist/node/space-writing.js +2 -0
  43. package/dist/node/space-writing.js.map +1 -1
  44. package/dist/node/types.d.ts +18 -0
  45. package/dist/node/types.d.ts.map +1 -1
  46. package/dist/schemas/library/social.d.ts +258 -0
  47. package/dist/schemas/library/social.d.ts.map +1 -1
  48. package/dist/schemas/library/social.js +28 -1
  49. package/dist/schemas/library/social.js.map +1 -1
  50. package/dist/session/hosting.d.ts.map +1 -1
  51. package/dist/session/hosting.js +8 -2
  52. package/dist/session/hosting.js.map +1 -1
  53. package/dist/space/presets.d.ts +2 -2
  54. package/dist/space/presets.d.ts.map +1 -1
  55. package/dist/space/presets.js +3 -2
  56. package/dist/space/presets.js.map +1 -1
  57. package/docs/actions.md +31 -24
  58. package/docs/agents.md +28 -16
  59. package/docs/blueprints-and-guides.md +26 -10
  60. package/docs/direct-messages.md +6 -2
  61. package/docs/node.md +34 -10
  62. package/docs/spaces.md +3 -2
  63. package/docs/standard-library.md +30 -8
  64. package/docs/storage.md +1 -1
  65. package/package.json +1 -2
package/docs/node.md CHANGED
@@ -341,7 +341,8 @@ node's own choice; how it tells peers what it holds is in
341
341
  - Collections listed in `cache.collections` are held from the start and never
342
342
  dropped.
343
343
  - A query marks the collections it reads (its own and every `include … from`)
344
- as used; sync then fetches them. A query's result has `complete: false`
344
+ as used, and a write the collection it writes in; sync then fetches them. A
345
+ writer holds its own earlier writes that way, and the rest beside them. A query's result has `complete: false`
345
346
  until, for every collection it reads, the node has once been level with a
346
347
  node holding the whole space, **and** it lacks nothing a writer's line in
347
348
  that collection names
@@ -351,9 +352,7 @@ node's own choice; how it tells peers what it holds is in
351
352
  collection is level with a peer.
352
353
  - Until the node has once caught up fully with a node holding the whole space,
353
354
  it cannot know whether the space names keepers, so it holds only what it uses.
354
- - The node's own writes are _pending_ until `min(keepers named, max(copies ?? 2,
355
- cache.copies ?? 0))` of the space's named keepers have them. A collection
356
- holding a pending write is never dropped.
355
+ - A collection holding a pending write (below) is never dropped.
357
356
  - A collection unused for `cache.unusedAfterDays` (default 30) days is dropped
358
357
  when the space opens and every 6 hours while it stays open. It stops being
359
358
  held _before_ its versions are removed, so nothing syncs it back meanwhile.
@@ -362,16 +361,31 @@ cache.copies ?? 0))` of the space's named keepers have them. A collection
362
361
  - When what it holds changes (whole or part, or a newly used collection), the
363
362
  node says hello to every peer.
364
363
 
365
- A keeper confirms a write the way the spec says: by `stored`, or by being
366
- level with the writer on its collection. Only a peer named in `sys.keepers`
367
- counts ([spec 05 §9](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md)).
364
+ On every node, holding part of a space or all of it, its own writes in a
365
+ space that names keepers are _pending_ until `min(keepers named, max(copies ??
366
+ 2, cache.copies ?? 0))` of them have them; a keeper's own node counts as one.
367
+ A node holding part of the space keeps them in its store, across runs; one
368
+ holding all of it in memory, the latest 4096. A keeper confirms a write the way
369
+ the spec says: by `stored`, or by being level with the writer on its
370
+ collection. Only a peer named in `sys.keepers` counts
371
+ ([spec 05 §9](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md)).
372
+
373
+ `node.spaces.kept(spaceId, waitMs, since?)` waits up to `waitMs` (at most a
374
+ minute) for this node's writes in a space to be kept elsewhere. In a space
375
+ that names keepers, it says `'keepers'` once none of its writes from `since`
376
+ (ms) on, or all of them, is pending. In one that names none, every member's
377
+ node is a copy, so it says `'peer'` once a peer connected now holds all this
378
+ node does: less sure, since that peer may be a device that goes away. Null
379
+ when nobody had, in time. A node that may stop before it syncs again waits on
380
+ it: a tab about to close, a command about to exit, a node a server runs for a
381
+ while (the MCP service's).
368
382
 
369
383
  This state is kept in the space's own store (`spaces/<spaceId>`):
370
384
 
371
385
  | Key | Value (UTF-8 JSON) |
372
386
  | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
373
387
  | `cache` | `{ "settled": boolean, "used": { [collection]: ms }, "level": { [collection]: ms }, "missing": { [collection]: [version id…] } }`. `settled`: has synced with a whole-space peer; `used`: when a query last used it; `level`: when it was first level with a whole-space peer; `missing`: what a writer's line there names that isn't here |
374
- | `pending/<version id>` | `{ "collection": string, "by": [keeper DID…] }`, deleted once `by` reaches the target |
388
+ | `pending/<version id>` | `{ "collection": string, "by": [keeper DID…], "at": ms }`, deleted once `by` reaches the target |
375
389
 
376
390
  What a keeper withholds from the middle of a writer's line shows up as
377
391
  missing, whichever peer the node was level with. A writer's newest versions
@@ -381,7 +395,7 @@ with to do it.
381
395
  The account registry, the contacts space and carry spaces are always held
382
396
  whole. Apps connected to an account home use `cache: {}` by default ([the app-side client](#the-app-side-client)).
383
397
 
384
- _Source: `packages/core/src/node/space-holding.ts` (`openSpaceHolding`), `packages/core/src/node/types.ts` (`CacheConfig`). Tests: `packages/core/tests/caches.test.ts`, `packages/core/tests/reconcile.test.ts` ("holding part of a space")._
398
+ _Source: `packages/core/src/node/space-holding.ts` (`openSpaceHolding`, `kept`), `packages/core/src/node/space-writing.ts` (`write`), `packages/core/src/node/types.ts` (`CacheConfig`). Tests: `packages/core/tests/caches.test.ts`, `packages/core/tests/reconcile.test.ts` ("holding part of a space")._
385
399
 
386
400
  ### Planned: caches that widen and trim
387
401
 
@@ -953,6 +967,16 @@ to look for the account registry at before the account says which it uses, so
953
967
  an app built with a default host restores an account from its recovery code
954
968
  alone. `network.nodes` still adds sockets of its own, to every space.
955
969
 
970
+ `network.reach` says where a node may connect, asked of every address it
971
+ found rather than was given: a host or node a record or an invite names, a
972
+ relay a space or an invite names, a place a short link names, a host it asks
973
+ to describe itself. Its own `relays`, `nodes` and `hosts` are taken as given;
974
+ without `reach`, anywhere. Refused, a host is not asked (`hosting` calls fail),
975
+ a node or relay not dialled, a short link's place not asked. It is for a node
976
+ a server runs for someone else, such as the MCP service's for chat apps: what
977
+ that node reads, and the invites it is handed, are the other's to write, and
978
+ must not make the server connect inside its own network.
979
+
956
980
  A device waits 15 seconds for a host to answer any call, and a minute for
957
981
  `startBot`. A host that gives no answer, or none in time, is a `HostError`
958
982
  with status 0 whose message names the address (`describeHost(url, timeoutMs?)`
@@ -981,7 +1005,7 @@ hour (`evaluate`) holds each to the free line. Past a space's `until`, every
981
1005
  account's carry space stops carrying it (`skip`, in `createCarryCore`), while
982
1006
  its own subscription still may. Each change is a line in the host's log.
983
1007
 
984
- _Source: `packages/core/src/node/node-carriers.ts` (`carriers`), `packages/core/src/node/node-hosting.ts` (`hosting`), `packages/core/src/node/carrier.ts` (`arrived`, `skip`, `onArrived`), `packages/core/src/node/host.ts` (`evaluate`), `packages/core/src/session/hosting.ts`, `packages/cli/src/host.ts`. Tests: `packages/core/tests/carrier.test.ts`, `packages/core/tests/host-limits.test.ts`, `packages/cli/tests/host.test.ts`._
1008
+ _Source: `packages/core/src/node/node-carriers.ts` (`carriers`, `fetchInvite`), `packages/core/src/node/node-hosting.ts` (`hosting`, `describeAt`), `packages/core/src/node/space-peers.ts` (`useNodes`, `meshFor`), `packages/core/src/node/carrier.ts` (`arrived`, `skip`, `onArrived`), `packages/core/src/node/host.ts` (`evaluate`), `packages/core/src/session/hosting.ts`, `packages/cli/src/host.ts`. Tests: `packages/core/tests/carrier.test.ts`, `packages/core/tests/host-limits.test.ts`, `packages/core/tests/reach.test.ts`, `packages/cli/tests/host.test.ts`, `packages/cli/tests/remote-mcp-server.test.ts`, `packages/cli/tests/remote-mcp-offline.test.ts`._
985
1009
 
986
1010
  ### A space paying for itself
987
1011
 
package/docs/spaces.md CHANGED
@@ -58,7 +58,8 @@ steward: its grants are the constitution's, and changing them takes a
58
58
  successor.
59
59
 
60
60
  `STAFF_COLLECTIONS` are the standard collections only moderators start in a
61
- community: announcements, badges, awards, pins, labels, channels and hosts.
61
+ community: announcements, badges, awards, pins, labels, channels, hosts and
62
+ the space's own profile (`std.space-profile`).
62
63
  Their definitions used to say so with `create` rules; now the template does.
63
64
 
64
65
  When a space is created with no roles, it gets `solo`. The account's derived
@@ -67,7 +68,7 @@ byte: their ids depend on it
67
68
  ([spec 03 §13.1](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
68
69
  Changing `solo` would change those ids, so it must not change.
69
70
 
70
- _Source: `packages/core/src/space/presets.ts` (`solo`, `team`, `community`, `coop`, `STAFF_COLLECTIONS`), `packages/core/src/space/grants.ts`, `packages/core/src/space/space-manager.ts` (`create`), `packages/core/src/node/node.ts` (`spaces.create`). Tests: `packages/core/tests/space.test.ts`, `packages/core/tests/roles.test.ts` ("definitions", "`community` admins can remove each other by naming a view before the promotion"), `packages/core/tests/constitution.test.ts` ("the templates are well formed", "a co-op: no founders…")._
71
+ _Source: `packages/core/src/space/presets.ts` (`solo`, `team`, `community`, `coop`, `STAFF_COLLECTIONS`), `packages/core/src/space/grants.ts`, `packages/core/src/space/space-manager.ts` (`create`), `packages/core/src/node/node.ts` (`spaces.create`). Tests: `packages/core/tests/space.test.ts`, `packages/core/tests/space-profile.test.ts`, `packages/core/tests/roles.test.ts` ("definitions", "`community` admins can remove each other by naming a view before the promotion"), `packages/core/tests/constitution.test.ts` ("the templates are well formed", "a co-op: no founders…")._
71
72
 
72
73
  ## The top and founders
73
74
 
@@ -140,14 +140,15 @@ anything, and only moderators and admins write in the collections in
140
140
 
141
141
  **People**
142
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.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 | — | — |
147
- | `std.follow` | **`did`** DID; `space` string ≤ 256; topic `did` | — | `onePer: [@author, did]` |
148
- | `std.block` | **`did`** DID; `until` when | — | `onePer: [@author, did]` |
149
- | `std.mute` | **`did`** DID; `until` when | — | `onePer: [@author, did]` |
150
- | `std.status` | `text` string ≤ 280; `emoji` string ≤ 16; `until` when | — | `onePer: [@author]` |
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]` |
151
152
 
152
153
  **Messaging and publishing**
153
154
 
@@ -356,6 +357,27 @@ misled bot from deleting.
356
357
 
357
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")._
358
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
+
359
381
  **Mentions and replies.** A `std.message`, `std.comment` or `std.post` names
360
382
  the accounts it calls on in `mentions` (as do `std.note`, `std.doc-block` and
361
383
  `std.article`) and, when it replies to someone's
package/docs/storage.md CHANGED
@@ -175,7 +175,7 @@ change and on close.
175
175
  `writer-keys/`; a slot left in the home from before is not read, nor
176
176
  `writers/`, where a minca from before the numbered lock keeps its keys, so
177
177
  the two never sign with one key. `minca agent`
178
- and `minca mcp` keep each session's key and stores together in a slot of
178
+ and the commands an agent runs keep each session's key and stores together in a slot of
179
179
  `<home>/agent`, beside the data folder the sessions share
180
180
  ([actions](actions.md#the-agent-on-a-computer)).
181
181
  - **Elsewhere** it must be given: `folderStores` refuses to start without
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@minca/core",
3
- "version": "0.1.16",
3
+ "version": "0.1.17",
4
4
  "type": "module",
5
5
  "description": "Self-sovereign P2P protocol for the browser — identity, schemas, storage, networking, and gossip sync",
6
6
  "repository": {
@@ -67,7 +67,6 @@
67
67
  },
68
68
  "devDependencies": {
69
69
  "@types/ws": "^8.18.2",
70
- "esbuild": "^0.28.2",
71
70
  "tsx": "^4.19.0",
72
71
  "typescript": "^7.0.2",
73
72
  "ws": "^8.22.0",