@minca/core 0.1.13 → 0.1.14

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.
@@ -44,6 +44,48 @@ Through `collections_propose`, a standard collection may be given by name
44
44
  (`"std.task"`): `standardCollections` puts the library's definition in its
45
45
  place.
46
46
 
47
+ ## Trying a contract before proposing it
48
+
49
+ Anyone in a space can write records directly, not only through the app that
50
+ proposed a collection, so an app's own checks stop nobody. What records must
51
+ keep to for the app to mean anything (whose turn it is, a legal move, a
52
+ balance) belongs in the collection's [contract](collections.md#contracts),
53
+ which every reader judges.
54
+
55
+ A contract written wrong refuses fair moves, or lets a cheat count, and
56
+ nothing shows it until someone plays. So `collections_propose` takes
57
+ `examples`: versions it runs through their collection's schema and contract
58
+ before writing anything, so the proposer sees a mistake first.
59
+
60
+ ```json
61
+ "examples": [
62
+ { "collection": "app.counter", "body": { "n": 0 }, "expect": "pass" },
63
+ { "collection": "app.counter", "prev": { "body": { "n": 4 } }, "body": { "n": 5 }, "expect": "pass" },
64
+ { "collection": "app.counter", "prev": { "body": { "n": 4 } }, "body": { "n": 9 }, "expect": "fail" },
65
+ { "collection": "app.counter", "prev": { "body": { "n": 4 }, "author": "did:key:z…" }, "body": { "n": 5 }, "author": "did:key:z…", "expect": "pass" }
66
+ ]
67
+ ```
68
+
69
+ - `author` is an account DID, the proposer's when left out. `prev` is the
70
+ version before, `{ body, author?, links? }`, for a contract that reads
71
+ `prev`; its author is this one's unless it names another, so turn-taking
72
+ is tried by naming both. `creator`, who wrote the first version, is the
73
+ version before's author, or this one's, unless given. Without `prev` the
74
+ example is a first version.
75
+ - An example that should count must fit its collection's schema too.
76
+ - If any example comes out other than expected, nothing is proposed, and the
77
+ error says which and why.
78
+ - A collection with a contract that no example names is still proposed, with
79
+ a warning saying so. The warning goes to the proposer only: the person
80
+ applying the blueprint sees the contract's conditions, not whether anyone
81
+ tried them.
82
+ - What examples don't try: rules (`onePer`, `fixed`, `final`), who may write,
83
+ and a contract's `line`. `member(did)` asks the space as it is now, not as
84
+ of what the version saw. A cited version can't be given, so an example
85
+ whose contract cites one never counts as `pass`.
86
+
87
+ _Source: `packages/core/src/schemas/blueprints.ts` (`tryContracts`), `packages/core/src/node/actions.ts` (`collections_propose`). Tests: `packages/core/tests/contracts.test.ts` ("checks: tried before they are proposed")._
88
+
47
89
  ## Saying how they are meant to be used
48
90
 
49
91
  A definition can't say "write one rota for each week, and say in it who does
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@minca/core",
3
- "version": "0.1.13",
3
+ "version": "0.1.14",
4
4
  "type": "module",
5
5
  "description": "Self-sovereign P2P protocol for the browser — identity, schemas, storage, networking, and gossip sync",
6
6
  "repository": {