@minca/core 0.1.17 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) 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 +2 -0
  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/node-contacts.d.ts.map +1 -1
  22. package/dist/node/node-contacts.js +1 -0
  23. package/dist/node/node-contacts.js.map +1 -1
  24. package/dist/node/node-records.d.ts.map +1 -1
  25. package/dist/node/node-records.js +6 -1
  26. package/dist/node/node-records.js.map +1 -1
  27. package/dist/node/node.d.ts.map +1 -1
  28. package/dist/node/node.js +13 -1
  29. package/dist/node/node.js.map +1 -1
  30. package/dist/node/remote.d.ts.map +1 -1
  31. package/dist/node/remote.js +7 -1
  32. package/dist/node/remote.js.map +1 -1
  33. package/dist/node/space-runtime.d.ts +5 -3
  34. package/dist/node/space-runtime.d.ts.map +1 -1
  35. package/dist/node/space-runtime.js +3 -1
  36. package/dist/node/space-runtime.js.map +1 -1
  37. package/dist/node/types.d.ts +112 -36
  38. package/dist/node/types.d.ts.map +1 -1
  39. package/dist/query/types.d.ts +1 -0
  40. package/dist/query/types.d.ts.map +1 -1
  41. package/dist/query/types.js.map +1 -1
  42. package/dist/records/contract-builder.d.ts +22 -6
  43. package/dist/records/contract-builder.d.ts.map +1 -1
  44. package/dist/records/contract-builder.js.map +1 -1
  45. package/dist/schemas/automations.d.ts +6 -2
  46. package/dist/schemas/automations.d.ts.map +1 -1
  47. package/dist/schemas/automations.js.map +1 -1
  48. package/dist/schemas/connectors.d.ts +4 -3
  49. package/dist/schemas/connectors.d.ts.map +1 -1
  50. package/dist/schemas/connectors.js +4 -3
  51. package/dist/schemas/connectors.js.map +1 -1
  52. package/dist/schemas/library/media.js +1 -1
  53. package/dist/schemas/library/media.js.map +1 -1
  54. package/dist/session/auth.d.ts +7 -3
  55. package/dist/session/auth.d.ts.map +1 -1
  56. package/dist/session/auth.js.map +1 -1
  57. package/dist/storage/blob-store.d.ts +3 -0
  58. package/dist/storage/blob-store.d.ts.map +1 -1
  59. package/dist/types.d.ts +11 -2
  60. package/dist/types.d.ts.map +1 -1
  61. package/dist/types.js.map +1 -1
  62. package/docs/README.md +86 -93
  63. package/docs/actions.md +213 -152
  64. package/docs/agents.md +198 -167
  65. package/docs/automations.md +296 -204
  66. package/docs/blueprints-and-guides.md +405 -311
  67. package/docs/bots.md +208 -134
  68. package/docs/building-an-app.md +74 -163
  69. package/docs/collections.md +248 -328
  70. package/docs/computed.md +112 -89
  71. package/docs/contacts.md +151 -112
  72. package/docs/contracts.md +299 -120
  73. package/docs/direct-messages.md +80 -65
  74. package/docs/inbox.md +138 -93
  75. package/docs/node.md +1072 -996
  76. package/docs/permissions.md +142 -0
  77. package/docs/proposing-collections.md +74 -55
  78. package/docs/query-format.md +150 -126
  79. package/docs/records-and-queries.md +205 -126
  80. package/docs/sign-in.md +496 -418
  81. package/docs/spaces.md +261 -246
  82. package/docs/standard-library.md +473 -526
  83. package/docs/storage.md +325 -348
  84. package/docs/usernames.md +164 -97
  85. package/docs/warrants.md +100 -67
  86. package/package.json +1 -1
package/docs/contracts.md CHANGED
@@ -1,22 +1,92 @@
1
1
  # Contracts
2
2
 
3
- A collection's contract says what a version must _be_ to count: conditions
4
- over its body, the version before it, and other versions it cites as
5
- evidence, in a subset of CEL. A line is one account's sequence of versions
6
- in a collection, where two versions after the same one cancel each other.
7
- What they mean exactly (the language, citations, limits, verdicts and the
8
- line rule) is protocol, in [spec 09](../../../spec/09-contracts.md), so that
9
- two implementations count the same records. How to write contracts, with
10
- patterns, is in [collections.md](collections.md#contracts). This page is how the
11
- library builds, checks and runs them.
3
+ A contract says when a version of a record counts. Use one when every app
4
+ must agree on something no single writer can be trusted with: a proposal
5
+ that passes only with enough votes, a move that must be legal, points that
6
+ can't be spent twice.
7
+
8
+ Here is a counter anyone may add to, but nobody can skip ahead:
9
+
10
+ ```ts
11
+ import * as z from 'zod';
12
+ import { collection } from '@minca/core';
13
+
14
+ export const counter = collection({
15
+ name: 'app.counter',
16
+ schema: z.object({ count: z.number() }),
17
+ contract: {
18
+ check: ({ body, prev, when }) => ({
19
+ 'The count goes up by one at a time': body.count.eq(when(prev.eq(null), 0, prev.body.count).add(1)),
20
+ }),
21
+ },
22
+ });
23
+ ```
24
+
25
+ Anyone can still write a version with `count: 100`. It just doesn't count:
26
+ every app reading the space skips it and shows the version before.
27
+
28
+ When a value only needs to look the same in every app, like a to-do that is
29
+ done once two people react, a [computed field](computed.md) is simpler.
30
+
31
+ ## How a contract is judged
32
+
33
+ Grants say who may write, and [rules](collections.md#rules) say what a record
34
+ must keep to. Every peer enforces both, and refuses what breaks them. A
35
+ contract is different: readers judge it, and peers don't enforce it.
36
+
37
+ A version that fails its contract is kept and synced like any other. But
38
+ `get`, `list` and queries count only a record's newest version that passes.
39
+ One that fails is skipped, and the version before shows instead.
40
+
41
+ Your own node refuses to sign a version that fails, with the condition's
42
+ reason as the error. Another implementation could still send one, and no
43
+ reader would count it.
44
+
45
+ ## Citing evidence
46
+
47
+ A contract never searches, because no device holds everything. The writer
48
+ does the work instead: it finds the votes, adds up the balances or picks the
49
+ move, and cites the versions that prove it. Every reader then checks that
50
+ exactly what was cited proves it. The example in
51
+ [Contracts](collections.md#contracts) on the collections page finds a
52
+ proposal's votes and cites them by version id.
53
+
54
+ A version citing one that hasn't arrived yet is pending, and doesn't count
55
+ until it does.
56
+
57
+ ### What can be cited
58
+
59
+ Only versions kept whole can be cited, so every device reads the same thing
60
+ however late it joins:
61
+
62
+ - any version in a collection with `history: 'all'`,
63
+ - any version in a collection with a contract of its own, since the node
64
+ keeps those whole,
65
+ - the first version of a record under `onePer` or `fixed`.
66
+
67
+ A cited version must also pass its own contract. Give a collection you mean
68
+ to cite `history: 'all'`, or the latest version of an edited vote can't be
69
+ cited.
70
+
71
+ A citation proves what was signed, not that it is still current. Make
72
+ evidence final where it matters: `final: true` on a vote, so nobody can
73
+ change or delete it once it is counted, or `fixed: ['choice']` to allow
74
+ other edits.
75
+
76
+ ### A proof stays a proof
77
+
78
+ A cited version is judged as of what the citing version saw. Removing a
79
+ voter later, or revoking the device that voted, doesn't undo a decision that
80
+ already counted the vote. A decision written after seeing the removal can't
81
+ count it. Peers keep such withdrawn versions, and the library reads them for
82
+ this without showing them.
12
83
 
13
84
  ## Writing one in TypeScript
14
85
 
15
86
  Write `check` as a function in the collection. It gets the version's names,
16
- typed from the collection's own schema, and gives an object: each key says
17
- why a version failing its condition doesn't count, and each value is the
18
- condition. Peers still see CEL: `define` builds it, as a query builder writes
19
- SQL.
87
+ typed from the collection's schema, and returns an object. Each key is the
88
+ reason a version failing that condition doesn't count, and each value is the
89
+ condition. `define` turns it into CEL, the way a query builder writes SQL.
20
90
 
21
91
  ```ts
22
92
  import * as z from 'zod';
@@ -56,55 +126,74 @@ That stores:
56
126
  ]
57
127
  ```
58
128
 
59
- - **Typed from the schemas.** `body.` completes the collection's fields, and
60
- `body.amont`, `body.to.eq(1)` or a condition that gives a number are type
61
- errors.
62
- - **`cited(ids, collection)`** reads the versions cited by `ids` that are in
63
- `collection`, typed from its schema, so `r.body.emojii` is a type error
64
- too. Versions of any other collection are left out, so nothing can be cited
65
- in their place. Where a citation of anything else must refuse the version
66
- instead, use `versions(ids)`, untyped until `.of(collection)`, and test
67
- `collection` yourself.
68
- - **What it reads:** `body`, `prev` (`prev.eq(null)` on a first version),
69
- `links`, `key`, `seq`, `collection`, `author`, `creator`, `createdAt`, and
70
- the functions `cited(ids, collection)`, `versions(ids)`, `link(rel)`,
71
- `member(did)`, `hash(x)`, `has(field)`, `when(test, then, otherwise)` and
72
- `raw(cel)`.
73
- - **Methods by type.** Comparison: `eq` `ne` `lt` `lte` `gt` `gte` `in`.
74
- Numbers: `add` `sub` `mul` `div` `neg`, ints also `mod`, and `toInt`,
75
- `toDouble`. Bools: `and` `or` `not`. Strings: `size` `contains`
76
- `startsWith` `endsWith` `add`. Lists: `size` (or `count`), `where` (or
77
- `filter`), `map`, `all`, `exists`, `existsOne`, `distinct`, `sum`,
78
- `includes`, `at`.
79
- - **Literals take the kind CEL needs.** A body's numbers are doubles and a
80
- size is an int, so `body.amount.gte(0)` writes `0.0` and
81
- `list.count().gte(5)` writes `5`. A fraction where an int is needed throws.
82
- - **`raw(cel)`** writes CEL by hand for what the builder doesn't cover:
83
- `math.greatest`, map literals, `string()`, indexing a map. Its result is
84
- untyped unless you say: `raw<boolean>('…')`.
85
- - **Each reason once.** Two conditions under the same reason are one key,
86
- and the later replaces the earlier, so a contract loses a condition
87
- without a word. Give each its own reason, or join them with `and`.
88
- - `define` throws when what it builds isn't a condition it would take,
89
- saying why.
90
-
91
- What it can't express, and `raw` covers: map literals, `math.greatest` and
92
- `math.least`, `string()`, `bool()`, `uint` values, `.map` with a filter
93
- (`map(x, p, t)`), and a field of an untyped value whose name is one of the
94
- methods above (use `.get('size')`).
95
-
96
- `contract(schema, that, else)` builds one condition outside a collection,
97
- for one shared by several, and gives the `{ that, else }` that a `check`
98
- list holds.
129
+ `body.` completes the collection's fields. `body.amont`, `body.to.eq(1)` and
130
+ a condition that gives a number are all type errors.
131
+
132
+ ### Cited versions
133
+
134
+ `cited(ids, collection)` reads the versions cited by `ids` that are in
135
+ `collection`, typed from its schema, so `r.body.emojii` is a type error too.
136
+ Versions of any other collection are left out, so nothing can be cited in
137
+ their place.
138
+
139
+ When citing anything else should fail the version instead, use
140
+ `versions(ids)`. It is untyped until `.of(collection)`, and you test
141
+ `collection` yourself.
142
+
143
+ ### What it reads
144
+
145
+ `check` gets a [`ContractContext`](https://minca.dev/api/core/interfaces/ContractContext/):
146
+ the version's fields, like `body` and `prev`, and the functions it may call,
147
+ like `cited` and `member`.
148
+
149
+ Each value has the methods of its type:
150
+ [numbers](https://minca.dev/api/core/interfaces/NumExpr/),
151
+ [ints](https://minca.dev/api/core/interfaces/IntExpr/),
152
+ [bools](https://minca.dev/api/core/interfaces/BoolExpr/),
153
+ [strings](https://minca.dev/api/core/interfaces/StrExpr/),
154
+ [lists](https://minca.dev/api/core/interfaces/ListExpr/) and
155
+ [versions](https://minca.dev/api/core/interfaces/VersionExpr/).
156
+
157
+ Literals take the kind CEL needs. A body's numbers are doubles and a size is
158
+ an int, so `body.amount.gte(0)` writes `0.0` and `list.count().gte(5)` writes
159
+ `5`. A fraction where an int is needed throws.
160
+
161
+ ### Writing CEL by hand inside the builder
162
+
163
+ `raw(cel)` covers what the builder can't express, like map literals,
164
+ indexing a map, and `.map` with a filter (`map(x, p, t)`). For a field of an
165
+ untyped value named like a method, use `.get('size')`.
166
+
167
+ ### Each reason once
168
+
169
+ Two conditions under the same reason are one key, and the later replaces the
170
+ earlier. The contract silently loses a condition. Give each its own reason,
171
+ or join them with `and`.
172
+
173
+ `define` throws when what it builds isn't a condition it would accept, and
174
+ says why.
175
+
176
+ ### One condition on its own
177
+
178
+ [`contract(schema, that, else)`](https://minca.dev/api/core/functions/contract/)
179
+ builds a single condition outside a collection, to share between several. It
180
+ gives the `{ that, else }` that a `check` list holds.
99
181
 
100
182
  ## Writing it by hand
101
183
 
102
- A condition is a CEL string, and a hand-written one is stored the same way:
184
+ A condition is a CEL string, and a hand-written list is stored the same way:
103
185
 
104
186
  ```ts
105
- await node.collections.define(space, {
187
+ import * as z from 'zod';
188
+
189
+ await node.collections.define(space.id, {
106
190
  name: 'app.pay',
107
- schema: Payment,
191
+ schema: z.object({
192
+ to: z.string(),
193
+ amount: z.number(),
194
+ balance: z.number(),
195
+ received: z.array(z.string()),
196
+ }),
108
197
  contract: {
109
198
  check: [
110
199
  {
@@ -116,84 +205,174 @@ await node.collections.define(space, {
116
205
  line: { once: ['received'] },
117
206
  },
118
207
  });
208
+ ```
209
+
210
+ A contract sits in the definition's `contract`, apart from its `rules`. Peers
211
+ check `rules` and refuse `check` there. They never read `contract`. Its type
212
+ is [`CollectionContract`](https://minca.dev/api/core/interfaces/CollectionContract/).
213
+
214
+ ## The language
215
+
216
+ A condition is a [CEL](https://cel.dev) expression. CEL is the Common
217
+ Expression Language that Kubernetes, Firebase and Envoy use for policies.
218
+
219
+ A condition reads `body`, `links`, `key`, `seq`, `collection`, `author` (the
220
+ account), `creator`, `createdAt` and `prev` (the version before, or `null`).
221
+ It has:
222
+
223
+ - CEL's operators, `has()`, and the macros `all`, `exists`, `exists_one`,
224
+ `filter` and `map`
225
+ - `size`, `contains`, `startsWith` and `endsWith`
226
+ - the conversions `int`, `uint`, `double`, `string` and `bool`
227
+ - from CEL's extensions, `distinct()`, `math.greatest` and `math.least`
228
+ - from Minca, `sum(list)`, `hash(x)`, `link("rel")` and `v.link("rel")`
229
+ - two that ask the space: `versions(ids)` reads cited versions by id, and
230
+ `member(did)`
231
+
232
+ Bytes, timestamps, durations, regular expressions and types as values are
233
+ left out.
234
+
235
+ ### Things to know
236
+
237
+ - A body's numbers are doubles, as JSON's are, and a literal like `1` is an
238
+ int. They compare freely, but don't mix in arithmetic. Write
239
+ `body.n + 1.0`, or `int(body.n) + 1`.
240
+ - Reading a field that isn't there is an error, not `null`. Ask
241
+ `has(body.note)` first. `&&` and `||` let an error pass when the other side
242
+ decides.
243
+ - A condition holds only when it gives `true`.
244
+ - A condition always ends. Its only loops are over lists in hand, and there
245
+ is a step limit.
246
+
247
+ ### Cost
248
+
249
+ A condition that goes over its limits is refused, so one that passes on
250
+ small records can fail on large ones.
251
+ [`contractCostHints(check)`](https://minca.dev/api/core/functions/contractCostHints/) flags what
252
+ makes a condition grow costly: macros nested three deep, or `versions()`
253
+ called inside a macro. It is advice only, and no verdict depends on it.
119
254
 
120
- // The first payment starts this account's line, at its line key;
121
- // each one after is the line's next version.
255
+ The exact subset and its limits are in [spec 09](../../../spec/09-contracts.md).
256
+
257
+ ## Lines
258
+
259
+ A line is one account's sequence of versions in a collection. A collection
260
+ whose contract has `line: { once: [...] }` gives each account one line, at
261
+ `lineKey(account, collection)`. Each version names the account's previous
262
+ one, so a payment can carry a running balance its contract checks.
263
+
264
+ ```ts
265
+ import { lineKey } from '@minca/core';
266
+
267
+ // The first payment starts this account's line, at its line key.
268
+ // Each one after is the line's next version.
122
269
  const line = await lineKey(node.did, 'app.pay');
123
- await node.records.put(space, 'app.pay', { to, amount: 30, balance: -30, received: [] }, { key: line });
124
- await node.records.update(space, line, { to: other, amount: 20, balance: -50, received: [] });
270
+ await node.records.put(
271
+ space.id,
272
+ 'app.pay',
273
+ { to: did, amount: 30, balance: -30, received: [] },
274
+ { key: line },
275
+ );
276
+ await node.records.update(space.id, line, { to: did, amount: 20, balance: -50, received: [] });
125
277
  ```
126
278
 
127
- A contract is the definition's `contract`, apart from its `rules`: peers
128
- check `rules` and refuse `check` there, and never read `contract`
129
- (spec 09 §1). The functions and types are `Contract`, `CollectionContract`, `ContractContext`,
130
- `contract`, `contractCostHints` and `node.records.contracts`.
279
+ Two versions after the same one are a double spend. Neither counts, and
280
+ nothing after either does. There is no way back, so keep a line on one
281
+ device at a time.
282
+
283
+ Each citation in a `once` field may appear only once along the line. That is
284
+ what stops one payment received from being counted twice.
285
+
286
+ The exact rule is in [spec 09 §7](../../../spec/09-contracts.md#7-lines).
131
287
 
132
288
  ## Checked against the schema when defined
133
289
 
134
290
  `collections.define` reads every condition, built or hand-written, against
135
- the collection's JSON Schema, and refuses one it can show is a mistake,
136
- saying where:
137
-
138
- - a field an object doesn't declare (`body.amont`, `prev.body.balanse`).
139
- This is stricter than JSON Schema: an object without
140
- `additionalProperties` counts as closed, as a Zod object writes it. Say
141
- other fields may be there (`additionalProperties: {}` or a schema, as
142
- `z.looseObject` and `.catchall()` write it) to read one;
143
- - a comparison that is never equal or always an error: a string with a
144
- number, `body.n > "1"`;
145
- - arithmetic that is always an error: `body.n + 1` (a body's numbers are
146
- doubles: write `1.0`);
147
- - a value used where it can't be: `versions(body.game)` on a string,
148
- `sum()` of strings, `size()` of a number, `&&` or `||` where no side is a
149
- bool, a field of a string, a condition that gives anything but a bool.
150
-
151
- This is the library's care, not protocol: another writer's definition that
152
- it would refuse still stands, and peers judge it by spec 09. It can't catch:
153
- a missing optional field (ask `has()`); anything read from a cited version
154
- not narrowed by the schema (a cited body is untyped to it); a cited version
155
- of the wrong collection; values out of range; and whatever `dyn()` or a
156
- schema it can't follow (no `type`, a mix of types) hides. A number's
157
- `integer` type reads as a double, as CEL reads JSON, and a sum of ints is
158
- untyped, since `sum([])` is `0.0`.
291
+ the collection's JSON Schema. It refuses one it can show is a mistake, and
292
+ says where:
293
+
294
+ - a field an object doesn't declare, like `body.amont` or
295
+ `prev.body.balanse`
296
+ - a comparison that is never equal or always an error, like a string with a
297
+ number: `body.n > "1"`
298
+ - arithmetic that is always an error, like `body.n + 1`, since a body's
299
+ numbers are doubles (write `1.0`)
300
+ - a value used where it can't be: `versions(body.game)` on a string, `sum()`
301
+ of strings, `size()` of a number, `&&` or `||` with no bool side, a field
302
+ of a string, or a condition that gives anything but a bool
303
+
304
+ This is stricter than JSON Schema in one way. An object without
305
+ `additionalProperties` counts as closed, as a Zod object writes it. To read a
306
+ field the schema doesn't declare, say other fields may be there:
307
+ `additionalProperties: {}` or a schema, as `z.looseObject` and `.catchall()`
308
+ write it.
309
+
310
+ It can't catch:
311
+
312
+ - a missing optional field (ask `has()`)
313
+ - anything read from a cited version, since a cited body is untyped to it
314
+ - a cited version of the wrong collection
315
+ - values out of range
316
+ - whatever `dyn()`, or a schema it can't follow (no `type`, a mix of types),
317
+ hides
318
+
319
+ A number's `integer` type reads as a double, as CEL reads JSON. A sum of
320
+ ints is untyped, since `sum([])` is `0.0`.
321
+
322
+ This check is the library's care, not protocol. A definition from another
323
+ writer that it would refuse still stands, and readers judge it by spec 09.
324
+
325
+ ## Patterns
326
+
327
+ - **Quorums and multisig.** "Three members approved": cite the approvals, and
328
+ check `distinct()` authors with `member(v.author)`. Who may approve at all
329
+ is the grant on the approvals' collection.
330
+ - **State machines.** Check each version against `prev`. A task moves from
331
+ `open` to `done` only, a counter goes up by one, a chess move is legal from
332
+ the board before. Each step is small, and there is no limit on steps.
333
+ - **Ledgers.** A transfer cites the balance records it spends, and checks
334
+ that they are the sender's and add up. Two spends of one balance are two
335
+ versions of it, which everyone sees.
336
+ - **Commit, then reveal.** A player first writes `hash` of a secret, then
337
+ reveals it: `hash(body.secret) == "<the commitment>"`. Shared dice,
338
+ lotteries and sealed bids need nothing else.
339
+ - **Closing a set.** A contract can prove that something exists, not that
340
+ nothing else does. For "a majority" or "nobody objected", someone granted
341
+ it signs a record that closes the vote and lists what counts, and the
342
+ result cites that.
343
+ - **Time.** There is no clock. "Before Friday" is a record from someone
344
+ trusted to say it, like a host or a witness, that the result cites.
345
+
346
+ The standard library has two ready-made: `std.decision`, a proposal decided
347
+ by a quorum of ballots, and `std.goal-reached`, a goal reached by pledges
348
+ ([standard library](standard-library.md)).
159
349
 
160
350
  ## How the library reads them
161
351
 
162
- - **Counted only when it passes.** `get`, `list`, `linked`, queries and their
163
- counts, automations and notifications count only versions that pass; `history`
164
- lists every version and gives a failing one its reason.
165
- - **`node.records.contracts(space, key, version?)`** says how the record's
166
- newest version that stands fares, or the version named:
167
- `{ version, passes, reason?, pending?, unjudged? }`. `passes` is `true`,
168
- `false` with the failing condition's `else` as `reason`, or `null` when the
169
- collection has no contract, the version waits (`pending: true`), or this
170
- library can't judge it (`unjudged: true`, with why).
171
- - **The writer refuses its own failing version.** The node judges a version's
172
- contract before signing it, and throws with the condition's `else` when it
173
- fails, when a version it cites hasn't arrived, or when it would be a double
174
- spend. Another implementation, or a writer that signs anyway, can still
175
- send one: every peer keeps it, and no reader counts it.
352
+ - **Counted only when it passes.** `get`, `list`, `linked`, queries and
353
+ their counts, automations and notifications count only versions that pass.
354
+ `history` lists every version, and gives a failing one its reason.
355
+ - **Asking how a version fares.**
356
+ [`node.records.contracts`](https://minca.dev/api/core/interfaces/NodeRecords/)
357
+ says how the record's newest standing version fares, or the version named.
358
+ - **The writer refuses its own failing version.** The node judges a
359
+ version's contract before signing it. It throws with the condition's `else`
360
+ when the version fails, when a version it cites hasn't arrived, or when it
361
+ would be a double spend.
176
362
  - **Kept whole.** The node sets `retain` on every version of a collection
177
- under a contract or a line that is not a delete, as spec 09 §4.2 asks of
178
- writers.
363
+ under a contract or a line, apart from deletes.
179
364
  - **Pending, read again.** A version waiting on one it cites is judged again
180
- whenever anything arrives, for up to **256** records at a time; beyond
181
- that, when the space's index is next rebuilt. Only a pass or a fail is
182
- cached.
365
+ whenever anything arrives, for up to **256** records at a time. Beyond
366
+ that, it waits until the space's index is next rebuilt. Only a pass or a
367
+ fail is cached.
183
368
  - **Double spends undo verdicts.** A version arriving in a line collection
184
- throws away every cached verdict in the space, since it can make a counted
185
- payment a double spend, and every version citing it fail with it.
369
+ throws away every cached verdict in the space. It can make a counted
370
+ payment a double spend, and every version citing that payment fails with
371
+ it.
186
372
  - **Defining.** `collections.define` refuses a contract outside the subset,
187
373
  one that misreads its schema ([above](#checked-against-the-schema-when-defined)),
188
374
  a `contract` with any key but `check` and `line`, and a `line` with any key
189
- but `once` (spec 09 §8).
190
- - **Cost hints.** `contractCostHints(check)` flags conditions whose cost grows
191
- fast with the records they read (macros three deep, `versions()` inside a
192
- macro), so one that passes on small records doesn't run out of steps on
193
- large ones. Advice only: no verdict depends on it.
194
-
195
- A line is checked by walking its counted chain for each version judged, so a
196
- very long line costs time in proportion to its length squared, once; the
197
- verdicts are cached.
198
-
199
- _Source: `packages/core/src/records/contract-builder.ts` (`contract`, `buildChecks`, `storedContract`), `packages/core/src/records/cel-types.ts` (`typeCheckCel`, `typeOfSchema`), `packages/core/src/records/contracts.ts` (`checkContracts`, `checkContractShape`, `checkContractTypes`, `runContracts`, `contractCostHints`, `checkLine`), `packages/core/src/node/space-checks.ts` (`checksOf`, `lineBreak`, `counts`), `packages/core/src/node/space-writing.ts` (`contractsFor`, `after`, `write`), `packages/core/src/node/space-runtime.ts` (`recordsChanged`, `define`), `packages/core/src/node/node-records.ts` (`contracts`). Tests: `packages/core/tests/contract-builder.test.ts`, `packages/core/tests/contracts.test.ts`, `packages/core/tests/contracts-shape.test.ts`, `packages/core/tests/contracts-line.test.ts`, `packages/core/tests/contracts-pending.test.ts`, `packages/core/tests/contracts-reads.test.ts`, `scenarios/tests/fame.test.ts` and `scenarios/tests/credit.test.ts` (each case with the built contract and the hand-written one)._
375
+ but `once`.
376
+ - **Long lines.** A line is checked by walking its counted chain for each
377
+ version judged. A very long line costs time in proportion to its length
378
+ squared, once, and then the verdicts are cached.