@biolibs/bionet 1.1.0 → 1.2.1

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.
package/README.md CHANGED
@@ -33,8 +33,8 @@ of exactly the kind this is meant to avoid:
33
33
  | it came from its own address | The document names the origin it was served from, so those keys belong to **that address** |
34
34
 
35
35
  `settled()` is all three at once. What none of them is: *this lab is who it says it is.* The address
36
- does that work, and only as far as you already trusted the address. If you know `endylab.example` is
37
- the Endy lab — from a paper, a colleague, a sign on the door — then a signed inventory served from
36
+ does that work, and only as far as you already trusted the address. If you know `wrenlab.example` is
37
+ the Wren lab — from a paper, a colleague, a sign on the door — then a signed inventory served from
38
38
  there ties that key to that lab. If you do not know that, nothing here will tell you.
39
39
 
40
40
  Two edges worth stating plainly:
@@ -66,8 +66,8 @@ import { generateSigningKey } from "@biolibs/opencloning";
66
66
  const key = await generateSigningKey();
67
67
 
68
68
  const inventory = inventoryFrom([f1, f2, f3], {
69
- name: "Endy lab",
70
- origin: "https://endylab.example",
69
+ name: "Wren lab",
70
+ origin: "https://wrenlab.example",
71
71
  contact: null,
72
72
  note: null,
73
73
  });
@@ -75,7 +75,7 @@ const inventory = inventoryFrom([f1, f2, f3], {
75
75
  console.log(inventory.parts[0].name); // "f1" — what this lab calls it
76
76
  console.log(inventory.parts[0].checksum); // ldseguid=... — what everyone else matches on
77
77
 
78
- const published = await signInventory(inventory, key, { signer: "Endy lab" });
78
+ const published = await signInventory(inventory, key, { signer: "Wren lab" });
79
79
  // write JSON.stringify(published) to /.well-known/bionet.json
80
80
  ```
81
81
 
@@ -88,7 +88,7 @@ the same molecule. Their names for it agree with nothing.
88
88
  ```ts
89
89
  import { fetchInventory, settled, signingKeys } from "@biolibs/bionet";
90
90
 
91
- const found = await fetchInventory("endylab.example");
91
+ const found = await fetchInventory("wrenlab.example");
92
92
 
93
93
  console.log(found.checks[0].ok); // true — the signature holds
94
94
  console.log(found.fromItsOwnAddress); // true — and it was served from the address it names
@@ -133,11 +133,11 @@ const inventory = inventoryFrom(parts, lab, {
133
133
  });
134
134
 
135
135
  // walking from a lab you were told about
136
- const walk = await discover(["endylab.example"], { maxDepth: 2 });
136
+ const walk = await discover(["wrenlab.example"], { maxDepth: 2 });
137
137
 
138
138
  console.log(walk.reached.map((one) => one.path.join(" → ")));
139
- // [ "https://endylab.example",
140
- // "https://endylab.example → https://otherlab.example" ]
139
+ // [ "https://wrenlab.example",
140
+ // "https://wrenlab.example → https://otherlab.example" ]
141
141
  console.log(walk.unreachable[0]?.why); // why an address did not answer, and who pointed at it
142
142
  ```
143
143
 
@@ -186,18 +186,96 @@ const needed = partsNeeded(plan.document);
186
186
  console.log(needed.map((part) => part.name)); // [ "f1", "f2", "f3" ]
187
187
 
188
188
  const sourcing = whoHas(needed, [found]);
189
- console.log(sourcing[0].holders[0].lab); // "Endy lab"
189
+ console.log(sourcing[0].holders[0].lab); // "Wren lab"
190
190
  console.log(unsourced(sourcing).map((p) => p.name)); // [ "f3" ] — nobody asked has this one
191
191
  ```
192
192
 
193
193
  `partsNeeded` is the plan's leaves: the molecules no step in it makes, which is exactly what somebody
194
- has to already have. Matching is by checksum, so a lab that calls the same molecule `pEndy-402` is
194
+ has to already have. Matching is by checksum, so a lab that calls the same molecule `pWren-402` is
195
195
  found anyway. `heldButNotOffered` separates "nobody has it" from "somebody has it but is not sending
196
196
  it", which are different problems for the person reading the plan.
197
197
 
198
198
  Inventories whose signatures do not hold are yours to filter out before you call `whoHas` — it matches
199
199
  what it is given and claims nothing about whether the labs are to be believed.
200
200
 
201
+ ## Inside a lab
202
+
203
+ An inventory is what a lab shows the world. Inside it, a freezer changes every day and the people
204
+ changing it are not always online, so what a lab holds is not a file anybody edits. It is worked out
205
+ from **signed logs**: each device has a key, every change made on it is one signed entry in that
206
+ key's own log, and nobody writes to anybody else's.
207
+
208
+ ```ts
209
+ import { addItem, addPart, addToRoster, adjustItem, entryId, foundLab, mergeLog, newItemId,
210
+ nextEntry, publicInventory, recountItem, signInventory } from "@biolibs/bionet";
211
+
212
+ // Ada founds the lab. Its ID is the ID of that entry, not a name or an address.
213
+ const founding = await foundLab(adasKey, { name: "The Wren Lab", person: "Ada" });
214
+ const ada = [founding];
215
+ const write = async (held, key, op) => held.push(await nextEntry(await mergeLog(held), key, op));
216
+
217
+ await write(ada, adasKey, addToRoster(bobsKey.publicKey, "Bob"));
218
+ await write(ada, adasKey, addPart({ sequence: "GGATCACAGTCTACACTGCTCACTCCAACCCCGGCCCCTGAGTCCGAGGA", name: "f1" }));
219
+ const part = (await mergeLog(ada)).parts[0].checksum;
220
+ const tube = newItemId();
221
+ await write(ada, adasKey, addItem({ item: tube, part, amount: 10, unit: "µL" }));
222
+
223
+ // Bob takes a copy and both go offline. Each uses some of the tube.
224
+ const bob = [...ada];
225
+ await write(ada, adasKey, adjustItem(tube, -1));
226
+ await write(bob, bobsKey, adjustItem(tube, -2));
227
+
228
+ // They meet. Either order, either machine: the same lab, and both uses counted.
229
+ const everything = [...new Set([...ada, ...bob])];
230
+ (await mergeLog(everything)).items[0].amount; // 7
231
+ (await mergeLog(everything.reverse())).items[0].amount; // 7
232
+ ```
233
+
234
+ `mergeLog` takes every entry held, in any order, and returns the lab: its roster, its parts, its
235
+ items and how much of each, and for every entry whether it counted and why not if not.
236
+
237
+ | Rule | Why |
238
+ |---|---|
239
+ | Order comes from what an entry had seen, never from a clock | Offline laptops agree about nothing, least of all the time |
240
+ | Amounts are whole-number differences | Two people using a tube are two uses. Whole numbers have one spelling to sign and add up exactly |
241
+ | A recount replaces only the adjustments its author had seen | The count was true when it was made; what happened unseen still happened |
242
+ | An item below zero, or counted twice at once, is flagged `needsRecount` | The freezer is the truth, and the log should say when it has lost track |
243
+ | Overlapping edits: the lower entry ID stands, and `overlaps` reports the other | The same choice on every machine, and nobody can arrange it in advance |
244
+ | Only a keeper changes the roster; the longer-standing keeper is heard first | Two keepers removing each other must come out one way |
245
+ | A removal names a cutoff in the removed key's log | Somebody removed cannot add to the lab later by claiming not to have heard. What they wrote past it is kept and marked `set aside` |
246
+
247
+ An entry that is not allowed is still placed, with `status` and `reason`, because the people in the
248
+ lab need to see what was turned away. An entry whose kind this version does not know is kept in the
249
+ chain and not applied, so an older app survives a newer one.
250
+
251
+ What leaves the lab is a reduction of all that:
252
+
253
+ ```ts
254
+ const lab = await mergeLog(everything);
255
+ const inventory = publicInventory(lab, {
256
+ name: "The Wren Lab", origin: "https://lab-wren.onrender.com", contact: null, note: null,
257
+ });
258
+ inventory.parts.map((one) => [one.name, one.available]); // [ [ "f1", false ] ]
259
+
260
+ const published = await signInventory(inventory, adasKey, { signer: "Ada" });
261
+ ```
262
+
263
+ A part is listed if some item of it has anything left, and is on offer only once a member has said
264
+ so with `offerPart`. Amounts, items and who did what stay inside.
265
+
266
+ ### Moving entries between machines
267
+
268
+ `mergeLog` works on whatever it is given. `sync.ts` is how entries are given, without opening a
269
+ connection itself: each side says how far into every log it holds (`haveOf`), sends what the other
270
+ lacks (`entriesBeyond`), and keeps what belongs of what arrives (`takeEntries`, which drops anything
271
+ from a key the roster has never heard of).
272
+
273
+ A lab's web peer relays entries between members and must not hand them to anybody who asks. So it
274
+ sends a `challenge`, the other side answers with `signHello`, and the peer sends entries only if
275
+ `verifyHello` names a key that `isMember`. Writing needs no proof: entries are signed by their
276
+ authors. `inventoryProblem` is the peer's rule for publishing an inventory a member sends it, and
277
+ `readMessage` reads one message off the wire.
278
+
201
279
  ## Testing
202
280
 
203
281
  ```bash
@@ -209,6 +287,8 @@ npx vitest run packages/bionet/test
209
287
  |---|---|
210
288
  | `test/bionet.test.ts` | inventories, signing, addresses, fetching, remembering, matching |
211
289
  | `test/discover.test.ts` | walking the network, and everything a walk refuses to do |
290
+ | `test/log.test.ts` | signed logs: offline work, recounts, overlaps, forgery, removal |
291
+ | `test/sync.test.ts` | exchanging entries, who may read them, what a peer keeps and publishes |
212
292
  | `test/readme.test.ts` | every code block in this file |
213
293
 
214
294
  ## Things to know
@@ -223,6 +303,10 @@ npx vitest run packages/bionet/test
223
303
  - **An inventory written before there were peers is still valid.** A missing list of pointers reads
224
304
  as an empty one, and nothing adds the field to a document it did not write — the signature covers
225
305
  the document as the lab wrote it.
306
+ - **A log entry is signed under its own domain**, `biolibs/bionet log entry v1`, and must be signed by
307
+ the key whose log it is in. A good signature from the wrong key is refused.
308
+ - **Nothing here opens a connection.** `sync.ts` says what two machines send each other; carrying
309
+ the messages is for whatever uses this.
226
310
  - **Nothing here fetches a part.** Finding out who has a plasmid is as far as software goes; the rest
227
311
  is an email and a padded envelope.
228
312
 
@@ -91,7 +91,7 @@ export interface DiscoverOptions extends FetchOptions {
91
91
  * ```ts
92
92
  * import { discover, partsNeeded, settledLabs, whoHas } from "@biolibs/bionet";
93
93
  *
94
- * const walk = await discover(["endylab.example"], { maxDepth: 2 });
94
+ * const walk = await discover(["wrenlab.example"], { maxDepth: 2 });
95
95
  * walk.reached.map((one) => `${one.path.join(" → ")}`);
96
96
  *
97
97
  * whoHas(partsNeeded(plan.document), settledLabs(walk));
package/dist/discover.js CHANGED
@@ -37,7 +37,7 @@ export const BY_DEFAULT = { labs: 50, depth: 2 };
37
37
  * ```ts
38
38
  * import { discover, partsNeeded, settledLabs, whoHas } from "@biolibs/bionet";
39
39
  *
40
- * const walk = await discover(["endylab.example"], { maxDepth: 2 });
40
+ * const walk = await discover(["wrenlab.example"], { maxDepth: 2 });
41
41
  * walk.reached.map((one) => `${one.path.join(" → ")}`);
42
42
  *
43
43
  * whoHas(partsNeeded(plan.document), settledLabs(walk));
package/dist/fetch.d.ts CHANGED
@@ -21,7 +21,7 @@ export interface FetchOptions {
21
21
  /**
22
22
  * Fetch a lab's inventory and check it.
23
23
  *
24
- * @param address - The lab's address, like `endylab.example`.
24
+ * @param address - The lab's address, like `wrenlab.example`.
25
25
  * @param options - What to fetch with, and how long to wait.
26
26
  * @returns What came back, with the signatures checked and the address compared.
27
27
  * @throws If the address is not usable, nothing answered, or what answered is not an inventory.
@@ -30,7 +30,7 @@ export interface FetchOptions {
30
30
  * ```ts
31
31
  * import { fetchInventory, settled } from "@biolibs/bionet";
32
32
  *
33
- * const found = await fetchInventory("endylab.example");
33
+ * const found = await fetchInventory("wrenlab.example");
34
34
  * settled(found); // signed, and served from the address it claims
35
35
  * found.signed.inventory.parts.length;
36
36
  * ```
package/dist/fetch.js CHANGED
@@ -14,7 +14,7 @@ const PATIENCE = 10_000;
14
14
  /**
15
15
  * Fetch a lab's inventory and check it.
16
16
  *
17
- * @param address - The lab's address, like `endylab.example`.
17
+ * @param address - The lab's address, like `wrenlab.example`.
18
18
  * @param options - What to fetch with, and how long to wait.
19
19
  * @returns What came back, with the signatures checked and the address compared.
20
20
  * @throws If the address is not usable, nothing answered, or what answered is not an inventory.
@@ -23,7 +23,7 @@ const PATIENCE = 10_000;
23
23
  * ```ts
24
24
  * import { fetchInventory, settled } from "@biolibs/bionet";
25
25
  *
26
- * const found = await fetchInventory("endylab.example");
26
+ * const found = await fetchInventory("wrenlab.example");
27
27
  * settled(found); // signed, and served from the address it claims
28
28
  * found.signed.inventory.parts.length;
29
29
  * ```
package/dist/index.d.ts CHANGED
@@ -20,12 +20,15 @@
20
20
  * - `discover.ts` — finding labs you were never told about, by walking from ones you were
21
21
  * - `trust.ts` — remembering which key answered last time, so a change gets noticed
22
22
  * - `match.ts` — what a plan needs, and who has it
23
+ * - `log.ts` — one signed change inside a lab, and the log it belongs to
24
+ * - `merge.ts` — what a lab holds, worked out from every key's log together
25
+ * - `sync.ts` — getting entries from one machine to another, and deciding who may have them
23
26
  *
24
27
  * @example
25
28
  * ```ts
26
29
  * import { fetchInventory, partsNeeded, settled, whoHas } from "@biolibs/bionet";
27
30
  *
28
- * const found = await fetchInventory("endylab.example");
31
+ * const found = await fetchInventory("wrenlab.example");
29
32
  * const sourcing = whoHas(partsNeeded(plan.document), settled(found) ? [found] : []);
30
33
  *
31
34
  * for (const { needed, holders } of sourcing) {
@@ -40,4 +43,7 @@ export * from "./fetch.js";
40
43
  export * from "./discover.js";
41
44
  export * from "./trust.js";
42
45
  export * from "./match.js";
46
+ export * from "./log.js";
47
+ export * from "./merge.js";
48
+ export * from "./sync.js";
43
49
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}
package/dist/index.js CHANGED
@@ -20,12 +20,15 @@
20
20
  * - `discover.ts` — finding labs you were never told about, by walking from ones you were
21
21
  * - `trust.ts` — remembering which key answered last time, so a change gets noticed
22
22
  * - `match.ts` — what a plan needs, and who has it
23
+ * - `log.ts` — one signed change inside a lab, and the log it belongs to
24
+ * - `merge.ts` — what a lab holds, worked out from every key's log together
25
+ * - `sync.ts` — getting entries from one machine to another, and deciding who may have them
23
26
  *
24
27
  * @example
25
28
  * ```ts
26
29
  * import { fetchInventory, partsNeeded, settled, whoHas } from "@biolibs/bionet";
27
30
  *
28
- * const found = await fetchInventory("endylab.example");
31
+ * const found = await fetchInventory("wrenlab.example");
29
32
  * const sourcing = whoHas(partsNeeded(plan.document), settled(found) ? [found] : []);
30
33
  *
31
34
  * for (const { needed, holders } of sourcing) {
@@ -40,4 +43,7 @@ export * from "./fetch.js";
40
43
  export * from "./discover.js";
41
44
  export * from "./trust.js";
42
45
  export * from "./match.js";
46
+ export * from "./log.js";
47
+ export * from "./merge.js";
48
+ export * from "./sync.js";
43
49
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}
@@ -46,9 +46,9 @@ export interface InventoryOptions {
46
46
  * import { inventoryFrom, signInventory } from "@biolibs/bionet";
47
47
  *
48
48
  * const inventory = inventoryFrom([pUC19, insert], {
49
- * name: "Endy lab", origin: "https://endylab.example", contact: null, note: null,
49
+ * name: "Wren lab", origin: "https://wrenlab.example", contact: null, note: null,
50
50
  * });
51
- * const published = await signInventory(inventory, key, { signer: "Endy lab" });
51
+ * const published = await signInventory(inventory, key, { signer: "Wren lab" });
52
52
  * ```
53
53
  */
54
54
  export declare function inventoryFrom(records: readonly Dseqrecord[], lab: LabModel, options?: InventoryOptions): InventoryDocument;
package/dist/inventory.js CHANGED
@@ -22,9 +22,9 @@ export const MOST_PEERS = 200;
22
22
  * import { inventoryFrom, signInventory } from "@biolibs/bionet";
23
23
  *
24
24
  * const inventory = inventoryFrom([pUC19, insert], {
25
- * name: "Endy lab", origin: "https://endylab.example", contact: null, note: null,
25
+ * name: "Wren lab", origin: "https://wrenlab.example", contact: null, note: null,
26
26
  * });
27
- * const published = await signInventory(inventory, key, { signer: "Endy lab" });
27
+ * const published = await signInventory(inventory, key, { signer: "Wren lab" });
28
28
  * ```
29
29
  */
30
30
  export function inventoryFrom(records, lab, options = {}) {
package/dist/log.d.ts ADDED
@@ -0,0 +1,196 @@
1
+ /**
2
+ * One signed change to a lab, and the log it belongs to.
3
+ *
4
+ * A published inventory is what a lab shows the world. This is what happens inside it: every change
5
+ * anybody makes — somebody joined, a tube was added, some of it was used — is one entry, signed by
6
+ * the key of the device it was made on, and appended to that key's own log. Nobody writes to another
7
+ * key's log, so two people working offline cannot overwrite each other; what the lab holds is
8
+ * whatever `merge.ts` makes of all the logs together.
9
+ *
10
+ * An entry says three things beyond the change itself. Which lab it is for, so it cannot be replayed
11
+ * into another. Where it sits in its own key's log, so a missing or substituted entry shows. And what
12
+ * its author had seen of everybody else's logs when they wrote it, which is the only honest way to
13
+ * order changes made on laptops whose clocks agree about nothing.
14
+ *
15
+ * Reading is the careful half here too. An entry arrives from another machine, so `readEntry` checks
16
+ * its shape and its size before anything else looks at it.
17
+ */
18
+ import { type DocumentSignature, type SignatureCheck, type SignOptions, type SigningKey } from "@biolibs/opencloning";
19
+ /** The version of the entry format written here. */
20
+ export declare const LOG_VERSION = 1;
21
+ /** What the bytes of a signed entry are for. No other kind of document is signed under this. */
22
+ export declare const LOG_DOMAIN = "biolibs/bionet log entry v1";
23
+ /** The longest one entry may be, as canonical text. A plasmid's sequence has to fit. */
24
+ export declare const LONGEST_ENTRY = 600000;
25
+ /** How many other logs one entry may say it had seen. */
26
+ export declare const MOST_SEEN = 1000;
27
+ /** What a key on the roster may do: change the inventory, or change the roster as well. */
28
+ export type Role = "member" | "keeper";
29
+ /**
30
+ * One change. `type` says which; the rest is whatever that change carries.
31
+ *
32
+ * It is deliberately loose. An entry whose `type` this version does not know is kept and chained
33
+ * like any other and simply not applied, so that an older app survives a newer one writing to the
34
+ * same lab. The operations this version does know are built by the functions at the foot of this
35
+ * file and checked by `merge.ts` when they are applied.
36
+ */
37
+ export interface Operation {
38
+ /** Which change this is, like `item.adjust`. */
39
+ type: string;
40
+ [field: string]: unknown;
41
+ }
42
+ /** One entry in one key's log. This is what is signed. */
43
+ export interface LogEntry {
44
+ /** Always `1`. */
45
+ bionet_log_version: number;
46
+ /** The lab this is for: the ID of its founding entry. `null` only in that founding entry. */
47
+ lab: string | null;
48
+ /** The key whose log this is in, 32 bytes in base64url. It must be the key that signs. */
49
+ author: string;
50
+ /** Where this sits in that log, from 0. */
51
+ seq: number;
52
+ /** The ID of the entry before it in the same log, or `null` at 0. */
53
+ prev: string | null;
54
+ /**
55
+ * What the author had of other keys' logs: for each key, the ID of the latest entry they held.
56
+ * Only keys whose latest entry changed since this author's previous entry need be listed.
57
+ */
58
+ seen: Record<string, string>;
59
+ /** The change. */
60
+ op: Operation;
61
+ }
62
+ /** An entry with its signature beside it, which is how one travels. */
63
+ export interface SignedEntry {
64
+ /** The entry, exactly as it was signed. */
65
+ entry: LogEntry;
66
+ /** The author's signature over it. */
67
+ signature: DocumentSignature;
68
+ }
69
+ /**
70
+ * The ID of an entry: the SHA-256 of its canonical form, in hex.
71
+ *
72
+ * It covers the entry and not the signature, so it names the change itself. An entry's ID is how the
73
+ * next entry in the log points back at it and how another key says it has seen it.
74
+ *
75
+ * @param entry - The entry.
76
+ * @returns 64 hex characters.
77
+ */
78
+ export declare function entryId(entry: LogEntry): Promise<string>;
79
+ /** What `writeEntry` needs to know about where an entry goes. */
80
+ export interface EntryPlace {
81
+ /** The lab's ID. */
82
+ lab: string;
83
+ /** This key's previous entry, or `null` if this is its first. */
84
+ prev: SignedEntry | null;
85
+ /** The latest entry held from each other key, where that changed since `prev`. */
86
+ seen?: Record<string, string>;
87
+ }
88
+ /**
89
+ * Write and sign the next entry in a key's log.
90
+ *
91
+ * Most callers want `nextEntry` in `merge.ts`, which works the place out from the lab's merged state.
92
+ * This is the plain form underneath it.
93
+ *
94
+ * @param key - The device's key. Its log is the one written to.
95
+ * @param place - Which lab, what came before in this log, and what had been seen of the others.
96
+ * @param op - The change.
97
+ * @param options - A name to sign under, and when.
98
+ * @returns The signed entry.
99
+ * @throws If `prev` belongs to another key or another lab.
100
+ */
101
+ export declare function writeEntry(key: SigningKey, place: EntryPlace, op: Operation, options?: SignOptions): Promise<SignedEntry>;
102
+ /**
103
+ * Found a lab: write the entry every other entry in it will point back to.
104
+ *
105
+ * The lab's ID is this entry's ID, so a lab is named by an act — this key, founding this lab, at this
106
+ * claimed moment — and not by an address, which can change, or a name, which anybody can use.
107
+ *
108
+ * @param key - The founder's device key. It becomes the lab's first keeper.
109
+ * @param about - What the lab is called, and who is founding it.
110
+ * @param options - A name to sign under, and when.
111
+ * @returns The founding entry. `entryId` of its `entry` is the lab's ID.
112
+ *
113
+ * @example
114
+ * ```ts
115
+ * import { entryId, foundLab } from "@biolibs/bionet";
116
+ *
117
+ * const founding = await foundLab(key, { name: "The Wren Lab", person: "Ada" });
118
+ * const lab = await entryId(founding.entry);
119
+ * ```
120
+ */
121
+ export declare function foundLab(key: SigningKey, about: {
122
+ name: string;
123
+ person: string;
124
+ }, options?: SignOptions): Promise<SignedEntry>;
125
+ /**
126
+ * Whether a value is shaped like a signed entry. Says nothing about whether the signature holds.
127
+ *
128
+ * @param value - Anything.
129
+ * @returns Whether it has an entry and a signature.
130
+ */
131
+ export declare function isSignedEntry(value: unknown): value is SignedEntry;
132
+ /**
133
+ * Read an entry that came from somewhere else.
134
+ *
135
+ * This checks shape and size and nothing more: that it could be an entry. Whether its signature
136
+ * holds is `verifyEntry`'s question, and whether it belongs in the lab is `mergeLog`'s.
137
+ *
138
+ * @param value - What arrived.
139
+ * @returns The same value, known to be shaped like an entry.
140
+ * @throws If it is not one, saying what is wrong.
141
+ */
142
+ export declare function readEntry(value: unknown): SignedEntry;
143
+ /**
144
+ * Check an entry's signature.
145
+ *
146
+ * Two things have to be true: the signature holds over these bytes under the log's own domain, and
147
+ * the key that signed is the key whose log the entry claims to be in. The second matters as much as
148
+ * the first — without it anybody could sign an entry into somebody else's log with their own key.
149
+ *
150
+ * @param signed - The entry.
151
+ * @returns The check. `ok` only if both hold; `problem` says which did not.
152
+ */
153
+ export declare function verifyEntry(signed: SignedEntry): Promise<SignatureCheck>;
154
+ /** @returns The change that adds a key to the roster. */
155
+ export declare const addToRoster: (key: string, person: string, role?: Role) => Operation;
156
+ /**
157
+ * @param key - The key to remove.
158
+ * @param cutoff - The last `seq` of that key's log the lab accepts. -1 accepts none of it.
159
+ * @returns The change that removes a key, keeping its entries up to the cutoff.
160
+ */
161
+ export declare const removeFromRoster: (key: string, cutoff: number) => Operation;
162
+ /** @returns The change that makes a key a keeper, or an ordinary member again. */
163
+ export declare const setRole: (key: string, role: Role) => Operation;
164
+ /** @returns The change that adds a part, by its sequence. Its checksum is computed when applied. */
165
+ export declare const addPart: (part: {
166
+ sequence: string;
167
+ circular?: boolean;
168
+ name: string;
169
+ }) => Operation;
170
+ /** @returns The change that says whether a part is on offer to other labs. */
171
+ export declare const offerPart: (part: string, available: boolean) => Operation;
172
+ /** @returns The change that adds one physical item of a part. `amount` is a whole number of `unit`. */
173
+ export declare const addItem: (item: {
174
+ item: string;
175
+ part: string;
176
+ amount: number;
177
+ unit?: string | null;
178
+ }) => Operation;
179
+ /** @returns The change that adds to or takes from an item. `by` is a whole-number difference, never a total. */
180
+ export declare const adjustItem: (item: string, by: number) => Operation;
181
+ /** @returns The change that says how much of an item is physically there. */
182
+ export declare const recountItem: (item: string, amount: number) => Operation;
183
+ /** @returns The change that retires an item. It stays in the history. */
184
+ export declare const retireItem: (item: string) => Operation;
185
+ /** @returns The change that sets one field on a part (by checksum) or an item (by ID). */
186
+ export declare const setField: (on: "part" | "item", id: string, field: string, value: string | number | null) => Operation;
187
+ /**
188
+ * A new ID for an item: 16 random bytes in hex.
189
+ *
190
+ * Random, because items are created on laptops that are offline, and two of them counting up from
191
+ * the same number would collide the moment they met.
192
+ *
193
+ * @returns 32 hex characters.
194
+ */
195
+ export declare function newItemId(): string;
196
+ //# sourceMappingURL=log.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"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"}