@biolibs/bionet 1.8.4 → 1.8.6

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/src/merge.ts CHANGED
@@ -198,6 +198,38 @@ export interface RunState {
198
198
  added: string;
199
199
  }
200
200
 
201
+ /**
202
+ * What a lab expects to see if a plan worked, and what was seen.
203
+ *
204
+ * A plan says what it would make; this says what somebody would observe. Keeping them apart is the
205
+ * point: a correct molecule can give a reading nobody expected, and a reading that looks right can
206
+ * come from the wrong molecule. One is a claim about a thing, the other about looking at it.
207
+ */
208
+ export interface ExpectationState {
209
+ /** Its ID. */
210
+ expect: string;
211
+ /** The plan it is about. */
212
+ plan: string;
213
+ /** How it would be observed: `digest`, `colony pcr`, `protein gel`. */
214
+ kind: string;
215
+ /** What to expect, for somebody at the bench to read. */
216
+ says: string;
217
+ /** The readings expected, as whole numbers. */
218
+ numbers: number[];
219
+ /** How to observe it: which enzymes, which gel. */
220
+ settings: Record<string, string | number>;
221
+ /** Anything else said about it. */
222
+ note: string | null;
223
+ /** The key that wrote it. */
224
+ by: string;
225
+ /** What was seen, or `null` while nobody has looked. */
226
+ met: { met: boolean; saw: number[]; run: string | null; note: string | null; by: string; entry: string } | null;
227
+ /** Anything else set on it. */
228
+ fields: Record<string, string | number | null>;
229
+ /** The entry that wrote it. */
230
+ added: string;
231
+ }
232
+
201
233
  /** A run somebody has proposed, as the lab holds it. */
202
234
  export interface PlanState {
203
235
  /** Its ID. */
@@ -223,6 +255,13 @@ export interface PlanState {
223
255
  * would use. The plan is kept and shown; somebody has to look before carrying it out.
224
256
  */
225
257
  wanting: string[];
258
+ /**
259
+ * For a plan still open: the molecules it would use that only a plan the lab has set aside would
260
+ * have made. Refiling a plan leaves the ones downstream of it naming what the old plan would have
261
+ * made, which no entry is wrong for saying and no reader of one entry can see. A molecule still to
262
+ * be ordered is not listed: nothing was ever going to make it here.
263
+ */
264
+ orphaned: string[];
226
265
  /** Anything else set on it, such as which project it is part of. */
227
266
  fields: Record<string, string | number | null>;
228
267
  /** The entry that proposed it. */
@@ -286,6 +325,8 @@ export interface LabState {
286
325
  strains: StrainState[];
287
326
  /** Everything the lab has and cannot yet name. */
288
327
  specimens: SpecimenState[];
328
+ /** What the lab expects to see of its plans, and what was seen. */
329
+ expectations: ExpectationState[];
289
330
  /** Every item. */
290
331
  items: ItemState[];
291
332
  /** Every place. */
@@ -336,6 +377,7 @@ const PLACE_RESERVED = new Set(["place", "kind", "parent", "grid", "standing", "
336
377
  /** The same, for a strain: what it is and came from is fixed when it is added. */
337
378
  const STRAIN_RESERVED = new Set(["strain", "host", "carries", "parent", "from"]);
338
379
  const SPECIMEN_RESERVED = new Set(["specimen", "note", "is", "added"]);
380
+ const EXPECT_RESERVED = new Set(["expect", "plan", "kind", "says", "numbers", "settings", "note", "by", "met", "added"]);
339
381
 
340
382
  /**
341
383
  * What a plan's fields may not be called.
@@ -345,7 +387,7 @@ const SPECIMEN_RESERVED = new Set(["specimen", "note", "is", "added"]);
345
387
  * something nobody proposed. A field says what a plan is *about* — which project it is part of,
346
388
  * say — and nothing about what carrying it out would do.
347
389
  */
348
- const PLAN_RESERVED = new Set(["plan", "kind", "instrument", "inputs", "expects", "settings", "note", "by", "settled", "wanting", "added"]);
390
+ const PLAN_RESERVED = new Set(["plan", "kind", "instrument", "inputs", "expects", "settings", "note", "by", "settled", "wanting", "orphaned", "added"]);
349
391
 
350
392
  /** The most positions a box may have along one side, and the farthest a place may stand or reach, in millimetres. */
351
393
  const MOST_SIDE = 100;
@@ -476,6 +518,8 @@ const KNOWN: Readonly<Record<string, Readonly<Record<string, Known>>>> = {
476
518
  "strain.add": { strain: true, name: true, host: true, carries: true, parent: true, from: true },
477
519
  "specimen.add": { specimen: true, name: true, note: true },
478
520
  "specimen.identify": { specimen: true, part: true },
521
+ "expect.add": { expect: true, plan: true, kind: true, says: true, numbers: true, settings: true, note: true },
522
+ "expect.meet": { expect: true, met: true, saw: true, run: true, note: true },
479
523
  "item.adjust": { item: true, by: true },
480
524
  "item.recount": { item: true, amount: true },
481
525
  "item.retire": { item: true },
@@ -505,7 +549,9 @@ const KNOWN: Readonly<Record<string, Readonly<Record<string, Known>>>> = {
505
549
  * the parts are known: an adviser may say what is on a part that nothing is marked on, and may not
506
550
  * change what somebody has already marked.
507
551
  */
508
- const ADVISER_MAY = new Set(["part.add", "part.annotate", "plan.add", "plan.settle", "field.set"]);
552
+ // An adviser may say what to look for, because that is reading and working out. It may not say what
553
+ // was seen: a reading is made by somebody standing at a bench, and nothing with no hands was there.
554
+ const ADVISER_MAY = new Set(["part.add", "part.annotate", "plan.add", "plan.settle", "field.set", "expect.add"]);
509
555
 
510
556
  /**
511
557
  * The first field in a change that this version does not know, if there is one.
@@ -657,7 +703,7 @@ const hadSeen = (later: Node, earlier: Node): boolean => (later.vc.get(earlier.a
657
703
  * ```
658
704
  */
659
705
  export async function mergeLog(entries: readonly unknown[], options: { lab?: string } = {}): Promise<LabState> {
660
- const state: LabState = { lab: options.lab ?? null, name: null, roster: [], parts: [], items: [], places: [], crowded: [], runs: [], plans: [], strains: [], specimens: [], entries: [],
706
+ const state: LabState = { lab: options.lab ?? null, name: null, roster: [], parts: [], items: [], places: [], crowded: [], runs: [], plans: [], strains: [], specimens: [], expectations: [], entries: [],
661
707
  waiting: [], discarded: [], overlaps: [], heads: {}, knows: {} };
662
708
 
663
709
  // Read and check every entry on its own, before any of them is believed about the others.
@@ -923,6 +969,7 @@ function fold(state: LabState, placed: Placed[], chained: Map<string, Node>): vo
923
969
  const places = new Map<string, { place: PlaceState; set: Map<string, Register> }>();
924
970
  const strains = new Map<string, { strain: StrainState; set: Map<string, Register> }>();
925
971
  const specimens = new Map<string, { specimen: SpecimenState; set: Map<string, Register> }>();
972
+ const expectations = new Map<string, { expectation: ExpectationState; seen: Node | null; set: Map<string, Register> }>();
926
973
  /** Each plan, with the entry that settled it, if one has, and anything set on it. */
927
974
  const plans = new Map<string, { plan: PlanState; settled: Node | null; set: Map<string, Register> }>();
928
975
  /** Where each item was last put. */
@@ -1148,6 +1195,60 @@ function fold(state: LabState, placed: Placed[], chained: Map<string, Node>): vo
1148
1195
  // like any other, so the same rule settles it and every lab reads the same answer.
1149
1196
  write(held.set, "is", node, op["part"], `what specimen ${op["specimen"]} is`);
1150
1197
  }
1198
+ } else if (op.type === "expect.add") {
1199
+ const numbers = op["numbers"], settings = op["settings"];
1200
+ if (!(typeof op["expect"] === "string" && ITEM_ID.test(op["expect"])) || !text(op["kind"], 40) || !text(op["says"], 2_000)
1201
+ || !(op["note"] === null || text(op["note"], 2_000))) {
1202
+ refuse("It does not carry an expectation ID, how it would be seen, what to expect, and a note or nothing.");
1203
+ } else if (!(typeof op["plan"] === "string" && plans.has(op["plan"]))) {
1204
+ refuse("The plan it is about is not one the lab has.");
1205
+ } else if (!Array.isArray(numbers) || numbers.length > MOST_IN_A_RUN || !numbers.every((one) => amountOf(one) && one >= 0)) {
1206
+ // A fraction never reaches here: the log will not sign one, because two devices that round
1207
+ // differently would put their names to different documents. So a band read at 4,757.5 bases
1208
+ // is written in the words. What this catches is a negative reading, which signs and means
1209
+ // nothing, and a list that is not a list.
1210
+ refuse("Its readings are not whole numbers that are not negative.");
1211
+ } else if (typeof settings !== "object" || settings === null || Array.isArray(settings) || Object.keys(settings).length > MOST_IN_A_RUN
1212
+ || !Object.entries(settings).every(([name, value]) => FIELD.test(name) && (amountOf(value) || (typeof value === "string" && value.length <= 200)))) {
1213
+ refuse("Its settings are not whole numbers and short text, by name.");
1214
+ } else if (expectations.has(op["expect"])) {
1215
+ refuse("An expectation with that ID already exists.");
1216
+ } else {
1217
+ expectations.set(op["expect"], {
1218
+ seen: null,
1219
+ expectation: { expect: op["expect"], plan: op["plan"], kind: op["kind"], says: op["says"],
1220
+ numbers: [...(numbers as number[])], settings: { ...(settings as Record<string, string | number>) },
1221
+ note: op["note"] as string | null, by: node.author, met: null, fields: {}, added: node.id },
1222
+ set: new Map(),
1223
+ });
1224
+ }
1225
+ } else if (op.type === "expect.meet") {
1226
+ const held = typeof op["expect"] === "string" ? expectations.get(op["expect"]) : undefined;
1227
+ const saw = op["saw"], run = op["run"];
1228
+ if (held === undefined) {
1229
+ refuse("The expectation it answers is not one the lab has.");
1230
+ } else if (typeof op["met"] !== "boolean" || !(op["note"] === null || text(op["note"], 2_000))) {
1231
+ refuse("It does not say whether what was seen is what was expected.");
1232
+ } else if (!Array.isArray(saw) || saw.length > MOST_IN_A_RUN || !saw.every((one) => amountOf(one) && one >= 0)) {
1233
+ refuse("What it says was seen is not whole numbers that are not negative.");
1234
+ } else if (!(run === null || (typeof run === "string" && state.runs.some((one) => one.run === run)))) {
1235
+ refuse("The run it says this was seen in is not one the lab has.");
1236
+ } else {
1237
+ const meet = (): void => {
1238
+ held.seen = node;
1239
+ held.expectation.met = { met: op["met"] as boolean, saw: [...(saw as number[])], run: run as string | null,
1240
+ note: op["note"] as string | null, by: node.author, entry: node.id };
1241
+ };
1242
+ if (held.seen === null) meet();
1243
+ else if (hadSeen(node, held.seen)) refuse("What was seen of that expectation is already recorded.");
1244
+ else {
1245
+ // Two people read the same gel without knowing of each other. One stands, and the overlap
1246
+ // is shown: a disagreement about what was seen is worth somebody looking at.
1247
+ const wins = node.id < held.seen.id;
1248
+ state.overlaps.push({ what: `what was seen of expectation ${held.expectation.expect.slice(0, 12)}`, kept: wins ? node.id : held.seen.id, dropped: wins ? held.seen.id : node.id });
1249
+ if (wins) meet();
1250
+ }
1251
+ }
1151
1252
  } else if (op.type === "plan.add") {
1152
1253
  const problem = planProblem(op, items, parts, places, plans);
1153
1254
  if (problem !== null) { refuse(problem); continue; }
@@ -1167,7 +1268,7 @@ function fold(state: LabState, placed: Placed[], chained: Map<string, Node>): vo
1167
1268
  plan: op["plan"] as string, kind: op["kind"] as string, instrument: op["instrument"] as string | null,
1168
1269
  inputs: (op["inputs"] as PlanInput[]).map((input) => ({ ...(input.item === undefined ? { part: input.part! } : { item: input.item }), amount: input.amount, role: input.role })),
1169
1270
  expects, settings: { ...(op["settings"] as Record<string, string | number>) }, note: op["note"] as string | null,
1170
- by: node.author, settled: null, wanting: [], fields: {}, added: node.id,
1271
+ by: node.author, settled: null, wanting: [], orphaned: [], fields: {}, added: node.id,
1171
1272
  },
1172
1273
  });
1173
1274
  } else if (op.type === "plan.settle") {
@@ -1194,12 +1295,14 @@ function fold(state: LabState, placed: Placed[], chained: Map<string, Node>): vo
1194
1295
  : op["on"] === "place" && typeof op["id"] === "string" ? places.get(op["id"])
1195
1296
  : op["on"] === "strain" && typeof op["id"] === "string" ? strains.get(op["id"])
1196
1297
  : op["on"] === "specimen" && typeof op["id"] === "string" ? specimens.get(op["id"])
1197
- : op["on"] === "plan" && typeof op["id"] === "string" ? plans.get(op["id"]) : undefined;
1198
- if (target === undefined) { refuse("It does not name a part, an item, a place, a strain, a specimen or a plan the lab has."); continue; }
1298
+ : op["on"] === "plan" && typeof op["id"] === "string" ? plans.get(op["id"])
1299
+ : op["on"] === "expectation" && typeof op["id"] === "string" ? expectations.get(op["id"]) : undefined;
1300
+ if (target === undefined) { refuse("It does not name a part, an item, a place, a strain, a specimen, a plan or an expectation the lab has."); continue; }
1199
1301
  if (op["on"] === "place" && typeof field === "string" && PLACE_RESERVED.has(field)) { refuse("It does not name a field that can be set."); continue; }
1200
1302
  if (op["on"] === "strain" && typeof field === "string" && STRAIN_RESERVED.has(field)) { refuse("It does not name a field that can be set."); continue; }
1201
1303
  if (op["on"] === "specimen" && typeof field === "string" && SPECIMEN_RESERVED.has(field)) { refuse("It does not name a field that can be set."); continue; }
1202
1304
  if (op["on"] === "plan" && typeof field === "string" && PLAN_RESERVED.has(field)) { refuse("It does not name a field that can be set."); continue; }
1305
+ if (op["on"] === "expectation" && typeof field === "string" && EXPECT_RESERVED.has(field)) { refuse("It does not name a field that can be set."); continue; }
1203
1306
  // An adviser may file its own proposals and nothing else. It proposes the work, so leaving it
1204
1307
  // unable to say which project the work is for would have a person filing every step by hand;
1205
1308
  // letting it set any field at all would let it rename the lab's parts. This is the same line
@@ -1243,6 +1346,10 @@ function fold(state: LabState, placed: Placed[], chained: Map<string, Node>): vo
1243
1346
  }
1244
1347
  state.specimens.push(specimen);
1245
1348
  }
1349
+ for (const { expectation, set } of expectations.values()) {
1350
+ for (const [field, held] of set) expectation.fields[field] = held.value as string | number | null;
1351
+ state.expectations.push(expectation);
1352
+ }
1246
1353
  for (const { item, set, base, adjusted, overlapped } of items.values()) {
1247
1354
  // A recount replaces the adjustments its author had seen. Everything else still counts.
1248
1355
  const since = adjusted.filter((one) => !hadSeen(base.node, one.node)).reduce((sum, one) => sum + one.by, 0);
@@ -1257,6 +1364,12 @@ function fold(state: LabState, placed: Placed[], chained: Map<string, Node>): vo
1257
1364
  item.where = (put.get(item.item)?.get("where")?.value ?? null) as ItemState["where"];
1258
1365
  state.items.push(item);
1259
1366
  }
1367
+ // Which molecules the lab could actually put into a plan: one a live tube holds, or one a plan
1368
+ // still open is expected to make. And, separately, the ones whose only maker has been set aside.
1369
+ const heldNow = new Set(state.items.filter((one) => !one.retired && one.amount > 0 && one.part !== null).map((one) => one.part!));
1370
+ const willBeMade = new Set<string>(), wasToBeMade = new Set<string>();
1371
+ for (const { plan } of plans.values())
1372
+ for (const expect of plan.expects) (plan.settled === null ? willBeMade : wasToBeMade).add(expect.checksum);
1260
1373
  // A plan counts on tubes that go on being used after it is written. It is not refused for that:
1261
1374
  // it is kept, and says which of them are no longer what it needs.
1262
1375
  for (const { plan, set } of plans.values()) {
@@ -1266,6 +1379,14 @@ function fold(state: LabState, placed: Placed[], chained: Map<string, Node>): vo
1266
1379
  const held = input.item === undefined ? undefined : items.get(input.item)?.item;
1267
1380
  return held !== undefined && (held.retired || held.amount < input.amount) ? [held.item] : [];
1268
1381
  });
1382
+ // Refiling a plan leaves the plans downstream of it pointing at what the old one would have
1383
+ // made. Nothing about either plan is wrong on its own, so neither is refused; what is wrong is
1384
+ // the pair, and only the lab as a whole can see it. A molecule still to be ordered is not this:
1385
+ // it was never any plan's output, so it is left alone. This is the molecule a plan the lab has
1386
+ // set aside would have made, and that nothing open makes now.
1387
+ plan.orphaned = plan.inputs.flatMap((input) =>
1388
+ input.part !== undefined && !heldNow.has(input.part) && !willBeMade.has(input.part) && wasToBeMade.has(input.part)
1389
+ ? [input.part] : []);
1269
1390
  }
1270
1391
  state.plans.push(plan);
1271
1392
  }