lab-kit-cli 1.10.0__tar.gz → 1.11.0__tar.gz

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 (44) hide show
  1. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/CHANGELOG.md +20 -0
  2. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/PKG-INFO +1 -1
  3. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/docs/model.md +20 -4
  4. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/pyproject.toml +1 -1
  5. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/skills/lab-work/SKILL.md +5 -0
  6. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/src/lab_kit/__init__.py +1 -1
  7. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/src/lab_kit/checks.py +6 -0
  8. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/src/lab_kit/cli.py +6 -1
  9. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/src/lab_kit/history.py +13 -4
  10. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/src/lab_kit/record.py +22 -4
  11. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/src/lab_kit/runs.py +94 -3
  12. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/src/lab_kit/views.py +1 -1
  13. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_drafts.py +36 -0
  14. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_integrity.py +46 -0
  15. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/.github/workflows/ci.yml +0 -0
  16. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/.github/workflows/policy.yml +0 -0
  17. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/.github/workflows/release.yml +0 -0
  18. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/.gitignore +0 -0
  19. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/AGENTS.md +0 -0
  20. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/CLAUDE.md +0 -0
  21. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/CONTRIBUTING.md +0 -0
  22. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/LICENSE +0 -0
  23. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/README.md +0 -0
  24. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/agents/reviewer.md +0 -0
  25. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/method/METHOD.md +0 -0
  26. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/skills/lab-mission/SKILL.md +0 -0
  27. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/skills/lab-review/SKILL.md +0 -0
  28. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/skills/lab-set-up/SKILL.md +0 -0
  29. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/skills/lab-talk/SKILL.md +0 -0
  30. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/src/lab_kit/site.py +0 -0
  31. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/src/lab_kit/supervise.py +0 -0
  32. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/src/lab_kit/write.py +0 -0
  33. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_flow.py +0 -0
  34. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_held.py +0 -0
  35. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_mission.py +0 -0
  36. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_needs.py +0 -0
  37. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_order.py +0 -0
  38. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_parked.py +0 -0
  39. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_refusals.py +0 -0
  40. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_site.py +0 -0
  41. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_states.py +0 -0
  42. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_vocabulary.py +0 -0
  43. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tests/test_wording.py +0 -0
  44. {lab_kit_cli-1.10.0 → lab_kit_cli-1.11.0}/tools/import_run.py +0 -0
@@ -1,5 +1,25 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.11.0
4
+
5
+ - **An ended run that did not record what it used can be amended.** A run stopped before its machines' files came
6
+ back seals with no amount for a resource it ran on, and `lab check` says it "did not record what it used"; `lab
7
+ runs close` refused it, since it had ended. `lab runs close <run> "<why>" --used <resource>=<amount>...
8
+ --evidence <folder>` now writes a sealed amendment, `<run>.amended.json`, beside the run's folder in the store,
9
+ never inside it: the run's seal, the amounts, why, and every file of the evidence with its hash. `runs.tsv`
10
+ lists it on an `amended` row with its seal. It covers only resources the run ran on and did not record, once.
11
+ `lab check` counts the amounts, and checks the amendment's seal, its row, the run's seal and the evidence's
12
+ hashes.
13
+ - The skill `lab-work` changed: run `lab init` in a lab after upgrading.
14
+
15
+ ## 1.10.1
16
+
17
+ - **A fold, once committed, ends what can lock the folded decision.** `lab check` refused a draft folded into another
18
+ as soon as a run started under an order the draft once held, even when the run started after the fold was
19
+ committed. Only what acted before the commit that removed the folded decision's file now locks it; what acts later
20
+ acts on the decision that took it in. A run that started before that commit still locks it, even when its line in
21
+ `runs.tsv` is committed with the fold.
22
+
3
23
  ## 1.10.0
4
24
 
5
25
  - **A settled decision is a draft until something acts on it.** A mission that carries it is launched, or a run or a
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.10.0
3
+ Version: 1.11.0
4
4
  Summary: A research lab's record, its method, and the command that keeps both.
5
5
  Project-URL: Homepage, https://github.com/pierg/lab-kit
6
6
  Project-URL: Issues, https://github.com/pierg/lab-kit/issues
@@ -337,7 +337,8 @@ Once something has acted on it, the decision is **locked**: its `decided:`, its
337
337
  first commit that records what acted on it (the mission's launch in the log, the run's line in `runs.tsv`), or, while
338
338
  none does, as in the last commit. An edit committed together with the act is already too late: commit the decision
339
339
  first. A change of mind is a new decision. `lab check` holds this against the lab's history, and refuses a
340
- locked decision folded into another. So a decision cannot be made, afterwards, to be about something it never
340
+ locked decision folded into another: one that something acted on before the commit that removed its file. What
341
+ acts after that commit acts on the decision that took it in. So a decision cannot be made, afterwards, to be about something it never
341
342
  discussed once anything was done on its word. `lab show` and the decision's page say whether it is a draft or locked,
342
343
  and since when.
343
344
 
@@ -388,7 +389,8 @@ that resource, under `about:`.
388
389
  the store (`lab runs publish`) and copies one from a store this machine does not mount
389
390
  (`lab runs fetch`). Closing a run stops whatever its command left running, reads what it said it
390
391
  used, and takes `--used <resource>=<amount>` for a run that said nothing; that amount is recorded
391
- as stated by hand. Where the system gives no way to tell that a process is the run's, nothing is
392
+ as stated by hand. On a run that has already ended, `lab runs close` with `--used` and
393
+ `--evidence <folder>` writes an amendment instead (below, under `runs.tsv`). Where the system gives no way to tell that a process is the run's, nothing is
392
394
  stopped and the command says so. `lab runs lost` records a run that started and whose folder is
393
395
  gone for good.
394
396
  - **Once:** `lab init`. Run again, it restores the method, the skills and the reviewer role.
@@ -834,11 +836,25 @@ import it in place of a script, and no hash covers it. `lab lock` and `lab run`
834
836
  `lab check` reports it. Under a lock that 1.0.0 made, whose hash did count such a file, it stays.
835
837
 
836
838
  **`runs.tsv`**, beside the lock and in git, is written by `lab run` and by the run as it ends: `run`
837
- (its id), `kind` (run, trial), `what` (started, ended, lost), `at`, on the ended row `exit` and `seal`,
838
- and on a lost row `used` (`{"<resource>": <amount>}`, or empty) and `note` (why it is lost). When a
839
+ (its id), `kind` (run, trial), `what` (started, ended, lost, amended), `at`, on the ended row `exit` and `seal`,
840
+ on a lost row `used` (`{"<resource>": <amount>}`, or empty) and `note` (why it is lost), and on an
841
+ amended row the amendment's `seal`, `used` and `note` (why). When a
839
842
  run ends on a machine that cannot write the lab, `lab runs publish`, `lab runs fetch` or
840
843
  `lab runs close` adds its ended row.
841
844
 
845
+ **An amendment** records what an ended run used of a resource it ran on (one in its `cap`) and did not
846
+ record itself, for example because it was stopped before its machines' files came back:
847
+ `lab runs close <run> "<why>" --used <resource>=<amount>... --evidence <folder>`. The run's folder is
848
+ sealed, every file in it hashed, so nothing is added to it: the amendment is `<run>.amended.json`
849
+ beside the folder in the store, read-only, holding the run's seal, the amounts, why, and the
850
+ evidence the amounts were read from, a folder outside the run's (its path, relative to the store
851
+ when it is in it, and every file in it with its hash), with one seal over it all. Its seal goes into
852
+ `runs.tsv` on an amended row. A run is amended at most once, and what it recorded itself stands.
853
+ `lab check` counts the amended amounts as what the run used, and asks that the amendment matches
854
+ its seal, names this run with its seal, is the one `runs.tsv` lists, and that every file of its
855
+ evidence is still there with its hash; and that a run `runs.tsv` lists as amended has its amendment
856
+ beside it.
857
+
842
858
  **A run** writes into the folder `LAB_RUN` names. If it uses a metered resource it writes
843
859
  `used.json` there: `{"<resource>": <amount>}`, each amount a number, finite and not negative;
844
860
  anything else is refused when the run is sealed and reported by `lab check`. Its record is `run.json`.
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  dynamic = ["readme"]
7
7
  name = "lab-kit-cli"
8
- version = "1.10.0"
8
+ version = "1.11.0"
9
9
  description = "A research lab's record, its method, and the command that keeps both."
10
10
  license = "MIT"
11
11
  authors = [{ name = "Piergiuseppe Mallozzi" }]
@@ -263,6 +263,11 @@ what should come next: open a decision.
263
263
  - **A run's process died.** `lab runs close <run> "<why>"`. It stops whatever the run left going and
264
264
  reads the run's `used.json`. If the run used a metered resource and wrote none, say what it used:
265
265
  `--used <resource>=<amount>`.
266
+ - **A run ended without recording what it used of a resource it ran on** (it was stopped before its
267
+ machines' files came back, and `lab check` says it "did not record what it used"). Copy the files
268
+ the amounts can be read from to a folder outside the run's, read the amounts there, then
269
+ `lab runs close <run> "<why>" --used <resource>=<amount>... --evidence <folder>`, and commit
270
+ `runs.tsv`. The amendment is sealed beside the run's folder; the folder is never touched.
266
271
  - **A run started and its folder is gone for good** (the machine was deleted with it). `lab runs lost
267
272
  <run> "<why>"`, with `--used <resource>=<amount>` for what it spent, then commit. It counts as a
268
273
  failed run, and another may follow.
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.10.0"
2
+ __version__ = "1.11.0"
@@ -271,6 +271,12 @@ def run(lab, rederive=True):
271
271
  why = runs_.verify(os.path.join(root, r["dir"]))
272
272
  if why:
273
273
  bad("runs", where, why)
274
+ if r.get("amendment") is not None:
275
+ why = runs_.check_amendment(lab, r, listed)
276
+ if why:
277
+ bad("runs", where, why)
278
+ elif listed and listed.get("amended") and not r["local"]:
279
+ bad("runs", where, f"runs.tsv lists an amendment of it, and {r['id']}.amended.json is not beside it in the store")
274
280
  for name, cap in (r.get("cap") or {}).items():
275
281
  used = (r.get("used") or {}).get(name)
276
282
  if used is None:
@@ -32,6 +32,7 @@ For evidence
32
32
  lab run <experiment> [--trial] [--wait] [--changed "<what changed since the last run, and why>"] -- <command>
33
33
  lab runs every run; also: lab runs publish [--keep] | fetch <run>
34
34
  lab runs close <run> "<why>" [--used <resource>=<amount>]... a run whose process died; --used for one that wrote no used.json
35
+ lab runs close <run> "<why>" --used <resource>=<amount>... --evidence <folder> an ended run that did not record what it used of a resource it ran on
35
36
  lab runs lost <run> "<why>" [--used <resource>=<amount>]... a run that started and whose folder is gone for good
36
37
  lab review <experiment> plan|results pass|fail "<note>" [--by <who>]
37
38
  lab check [--no-rederive] [--strict] runs every command in results.tsv: only on a lab you trust. --strict fails when
@@ -163,13 +164,17 @@ def main(argv=None):
163
164
  used[name] = float(text) if "." in text or "e" in text.lower() else int(text)
164
165
  except ValueError:
165
166
  raise SystemExit(f"--used {pair}: <resource>=<amount>")
167
+ evidence = flag("--evidence")
166
168
  if len(rest) != 3:
167
169
  raise SystemExit(USAGE)
170
+ if evidence and rest[0] == "lost":
171
+ raise SystemExit("--evidence is for `lab runs close` on a run that has ended")
168
172
  if rest[0] == "lost":
169
173
  with runs.exclusive(lab.root):
170
174
  print(f"recorded as lost in {runs.lost(Lab(lab.root), rest[1], rest[2], used)}; commit it")
171
175
  else:
172
- print(f"closed: {runs.close(lab, rest[1], rest[2], used)}")
176
+ done = runs.close(lab, rest[1], rest[2], used, evidence)
177
+ print(f"amended: {done[0]}, listed in {done[1]}; commit it" if isinstance(done, tuple) else f"closed: {done}")
173
178
  elif rest[0] == "publish":
174
179
  keep = flag("--keep", switch=True)
175
180
  for r in lab.runs: # a run that ended where the lab could not be written gets its seal listed here
@@ -207,11 +207,15 @@ def decisions(lab, versions=None, now=None):
207
207
  return (str(fm.get("decided")), s("about"), s("parks"), s("unparks"), s("drops"), ids(fm.get("order")), s("folds"), # its order is kept as written
208
208
  R.flat(slots.get("Decided", "")))
209
209
 
210
+ def removed(path):
211
+ """The commit that removed a file, or None while HEAD still has it and only the work tree lacks it."""
212
+ if git(root, "cat-file", "-e", f"HEAD:./{path}") is not None:
213
+ return None
214
+ return (git(root, "log", "-1", "--diff-filter=D", "--format=%H", "--", path) or "").strip() or None
215
+
210
216
  def last(path):
211
217
  """The last commit that still had a file: HEAD while only the work tree lacks it, else the one before its removal."""
212
- if git(root, "cat-file", "-e", f"HEAD:./{path}") is not None:
213
- return "HEAD"
214
- gone = (git(root, "log", "-1", "--diff-filter=D", "--format=%H", "--", path) or "").strip()
218
+ gone = removed(path)
215
219
  return f"{gone}^" if gone else "HEAD"
216
220
 
217
221
  def launched(c, ident):
@@ -252,7 +256,12 @@ def decisions(lab, versions=None, now=None):
252
256
  fm, _ = card(git(root, "show", f"{c}:./{commits[-1][1]}") or "")
253
257
  acted = None
254
258
  if fm and fm.get("decided") is not None:
255
- acts = lab.acts(ident, orders | set(ids(fm.get("order"))), lab.settled_at(ident, fm.get("decided")))
259
+ # Only what acted while it was still here locks it: an act after the commit that removed it acts on
260
+ # the decision that took it in. While the removal is not committed yet, everything so far counts.
261
+ gone = removed(commits[-1][1])
262
+ until = R.moment((git(root, "log", "-1", "--format=%cI", gone) or "").strip()) if gone else None
263
+ acts = [a for a in lab.acts(ident, orders | set(ids(fm.get("order"))), lab.settled_at(ident, fm.get("decided")))
264
+ if until is None or R.moment(a[0]) <= until]
256
265
  acted = acts[0][0] if acts else launched(c, ident)
257
266
  if not into:
258
267
  bad(commits[-1][1], "was committed and is gone; nothing recorded is removed. A draft decision is folded into another with `folds:`")
@@ -594,11 +594,22 @@ class Lab:
594
594
  for r in rows[1:]:
595
595
  row = dict(zip(LEDGER, r + [""] * (len(LEDGER) - len(r))))
596
596
  run, what = row["run"], row["what"]
597
- if len(r) < 6 or len(r) > len(LEDGER) or not RUN_ID.match(run) or row["kind"] not in ("run", "trial") or what not in ("started", "ended", "lost") or not moment(row["at"]):
598
- self.problems.append(f"runs: {where}: the row for {run[:40]!r} is not `run, kind, started|ended|lost, time, exit, seal, used, note`")
597
+ if len(r) < 6 or len(r) > len(LEDGER) or not RUN_ID.match(run) or row["kind"] not in ("run", "trial") or what not in ("started", "ended", "lost", "amended") or not moment(row["at"]):
598
+ self.problems.append(f"runs: {where}: the row for {run[:40]!r} is not `run, kind, started|ended|lost|amended, time, exit, seal, used, note`")
599
599
  continue
600
- e = out.setdefault(run, {"id": run, "kind": row["kind"], "started": None, "ended": None, "exit": None, "seal": None, "lost": "", "used": None})
601
- if (what == "started" and e["started"]) or (what != "started" and e["ended"]) or e["kind"] != row["kind"]:
600
+ e = out.setdefault(run, {"id": run, "kind": row["kind"], "started": None, "ended": None, "exit": None, "seal": None, "lost": "", "used": None, "amended": None})
601
+ if what == "amended":
602
+ try:
603
+ used = json.loads(row["used"]) if row["used"] else {}
604
+ except ValueError:
605
+ used = None
606
+ if e["amended"] or not e["ended"] or e["lost"] or e["kind"] != row["kind"]:
607
+ self.problems.append(f"runs: {where}: {run} is amended twice, or before it ended, or after it was declared lost")
608
+ elif not flat(row["note"]) or not re.fullmatch(r"[0-9a-f]{64}", row["seal"]) or not isinstance(used, dict) or not used or not all(amount(v) for v in used.values()):
609
+ self.problems.append(f"runs: {where}: {run} is amended with no reason, no seal, or a use that is not `{{\"<resource>\": <amount>}}`")
610
+ else:
611
+ e["amended"] = {"at": row["at"], "seal": row["seal"], "used": used, "why": flat(row["note"])}
612
+ elif (what == "started" and e["started"]) or (what != "started" and e["ended"]) or e["kind"] != row["kind"]:
602
613
  self.problems.append(f"runs: {where}: {run} is listed twice as {'started' if what == 'started' else 'ended'}")
603
614
  elif what == "started":
604
615
  e["started"] = row["at"]
@@ -795,6 +806,13 @@ class Lab:
795
806
  r["orphan"] = r["state"] == "running" and r.get("host") == os.uname().nodename and not alive(r.get("pid"))
796
807
  note = d + ".unpublished"
797
808
  r["unpublished"] = read(note).strip() if os.path.exists(note) else ""
809
+ r["own_used"] = dict(r.get("used") or {})
810
+ amended = d + ".amended.json" # what the run used and did not record, stated after it ended: beside its folder, not in it
811
+ r["amendment"] = None if r["local"] or not os.path.lexists(amended) else (self._json(amended) or {})
812
+ a = r["amendment"]
813
+ if isinstance(a, dict) and isinstance(a.get("used"), dict):
814
+ more = {k: v for k, v in a["used"].items() if k not in r["own_used"]}
815
+ r["used"], r["used_amended"] = {**r["own_used"], **more}, sorted(more)
798
816
  out.append(r)
799
817
  here = {r["id"] for r in out}
800
818
  for x in self.experiments: # a run the ledger lists and the store does not hold: known to have run, with nothing to read
@@ -374,16 +374,16 @@ def lost(lab, run_id, why, used=None):
374
374
  stop(f"no run {run_id} is listed as started")
375
375
 
376
376
 
377
- def close(lab, run_id, why, used=None):
377
+ def close(lab, run_id, why, used=None, evidence=""):
378
378
  """Close a run whose process died: stop what it left running, record that it stopped and what it used, seal what it
379
- left, move it into the store."""
379
+ left, move it into the store. On a run that has ended, record what it used and did not record (`amend`)."""
380
380
  run_id_or_stop(run_id)
381
381
  if not R.flat(why):
382
382
  stop("say why the run is closed")
383
383
  for r in lab.runs:
384
384
  if r["id"] == run_id:
385
385
  if r["state"] != "running":
386
- stop(f"{run_id} has already ended")
386
+ return amend(lab, run_id, why, used, evidence)
387
387
  if r["missing"]:
388
388
  stop(f"{run_id} is listed in runs.tsv and its folder is not on this machine: close it where it ran, or if it is gone for good, `lab runs lost {run_id} \"<why>\"`")
389
389
  if not r["orphan"]:
@@ -407,6 +407,97 @@ def close(lab, run_id, why, used=None):
407
407
  stop(f"no run {run_id}")
408
408
 
409
409
 
410
+ def amendment(lab, run_id):
411
+ """Where the amendment of an ended run is kept: beside its folder in the store, never inside it, since the seal
412
+ covers every file in the folder."""
413
+ return os.path.join(lab.store, run_id + ".amended.json")
414
+
415
+
416
+ def evidence_files(folder):
417
+ """Every file under the evidence, with its hash."""
418
+ if os.path.isfile(folder):
419
+ return {os.path.basename(folder): R.sha(folder)}
420
+ return {os.path.relpath(os.path.join(top, f), folder): R.sha(os.path.join(top, f)) for top, _, fs in os.walk(folder) for f in fs}
421
+
422
+
423
+ def evidence_at(lab, where):
424
+ return where if os.path.isabs(where) else os.path.join(lab.store_root, where)
425
+
426
+
427
+ def check_amendment(lab, r, listed):
428
+ """Why the amendment beside an ended run does not stand, or None."""
429
+ a = r.get("amendment")
430
+ if not isinstance(a, dict) or not isinstance(a.get("used"), dict) or not isinstance(a.get("evidence"), dict) or not isinstance(a["evidence"].get("files"), dict):
431
+ return "its amendment cannot be read as one `lab runs close` wrote"
432
+ if R.seal_of(a) != a.get("seal"):
433
+ return "its amendment does not match its seal"
434
+ if a.get("run") != r["id"] or a.get("run_seal") != r.get("seal"):
435
+ return "its amendment is of another run, or of this run with another seal"
436
+ if not listed or (listed.get("amended") or {}).get("seal") != a["seal"]:
437
+ return f"its amendment is not the one runs.tsv lists: `lab runs close {r['id']}` lists it when it writes it"
438
+ for k, v in a["used"].items():
439
+ if not R.amount(v):
440
+ return f"its amendment records {v!r} as what it used of {k}: an amount is a number, finite and not negative"
441
+ if k in (r.get("own_used") or {}):
442
+ return f"its amendment states what it used of {k}, which the run recorded itself"
443
+ where = evidence_at(lab, str(a["evidence"].get("path") or ""))
444
+ if not a["evidence"]["files"] or not os.path.exists(where):
445
+ return f"the evidence of its amendment, {a['evidence'].get('path')}, is not there"
446
+ for p, h in a["evidence"]["files"].items():
447
+ f = where if os.path.isfile(where) else os.path.join(where, p)
448
+ if not os.path.isfile(f) or R.sha(f) != h:
449
+ return f"the evidence of its amendment changed: {p} does not match its hash"
450
+ return None
451
+
452
+
453
+ def amend(lab, run_id, why, used, evidence):
454
+ """Record what an ended run used and did not record: a sealed amendment beside its folder in the store, naming
455
+ the files the amounts were read from with their hashes, and listed in runs.tsv. What the run recorded stands."""
456
+ r = next((x for x in lab.runs if x["id"] == run_id), None)
457
+ if r["missing"] or r["local"]:
458
+ stop(f"{run_id} is not in the store here: an amendment is written beside a run in the store" + (", so `lab runs publish` it first" if r["local"] else ""))
459
+ if not used:
460
+ stop("--used <resource>=<amount>: what the run used and did not record")
461
+ if not evidence:
462
+ stop("--evidence <folder>: the files the amounts were read from, kept outside the run's folder")
463
+ used = stated(lab, used)
464
+ own = r.get("own_used") or {}
465
+ for k in used:
466
+ if k in own:
467
+ stop(f"{run_id} recorded what it used of {k} itself, and that stands")
468
+ if k not in (r.get("cap") or {}):
469
+ stop(f"{run_id} did not run on {k}")
470
+ rdir = os.path.join(lab.root, r["dir"])
471
+ why_not = verify(rdir)
472
+ if why_not:
473
+ stop(f"{run_id} does not match its seal: {why_not}")
474
+ path = amendment(lab, run_id)
475
+ if os.path.lexists(path) or (lab.nodes[r["experiment"]]["listed"].get(run_id) or {}).get("amended"):
476
+ stop(f"{run_id} has already been amended: an amendment is never rewritten")
477
+ ev = os.path.abspath(evidence)
478
+ if not os.path.exists(ev):
479
+ stop(f"--evidence {evidence}: not there")
480
+ if ev == os.path.abspath(rdir) or ev.startswith(os.path.realpath(rdir) + os.sep) or ev.startswith(os.path.abspath(rdir) + os.sep):
481
+ stop("--evidence is outside the run's folder: the run's own files are sealed as they are")
482
+ files = evidence_files(ev)
483
+ if not files:
484
+ stop(f"--evidence {evidence}: holds no files")
485
+ store = os.path.realpath(lab.store_root)
486
+ real = os.path.realpath(ev)
487
+ where = os.path.relpath(real, store) if real.startswith(store + os.sep) else real
488
+ a = {"run": run_id, "run_seal": r["seal"], "at": now(), "why": " ".join(why.split()), "used": used,
489
+ "evidence": {"path": where, "files": dict(sorted(files.items()))}}
490
+ a["seal"] = R.seal_of(a)
491
+ tmp = path + ".tmp"
492
+ with open(tmp, "w") as f:
493
+ json.dump(a, f, indent=1, sort_keys=True)
494
+ f.write("\n")
495
+ os.chmod(tmp, 0o444)
496
+ os.rename(tmp, path)
497
+ ledger(lab, lab.nodes[r["experiment"]], run_id, r["kind"], "amended", a["at"], seal=a["seal"], used=json.dumps(used, sort_keys=True), note=why)
498
+ return lab.rel(path), os.path.join(lab.nodes[r["experiment"]]["dir"], "runs.tsv")
499
+
500
+
410
501
  def listing(lab):
411
502
  out = []
412
503
  for r in lab.runs:
@@ -264,7 +264,7 @@ def _show(lab, ident):
264
264
  if x["results"]:
265
265
  out += ["", "Results" + ("" if x["reviewed"] else " (not reviewed: not to be used on a card yet)")] + [f"- {r['name']} = {r['value']}" + (f", shown as {R.shown(r)}" if R.shown(r) != r["value"] else "") + f" ({r.get('label') or 'no label'}; against: {r.get('versus', '')})" for r in x["results"]]
266
266
  for r in x["trials"] + x["runs"]:
267
- used = "".join(f", used {num(v)} {lab.resources.get(k, {}).get('unit', k)}" + (" (stated by hand when it was closed)" if k in (r.get("used_by_hand") or []) else "") for k, v in (r.get("used") or {}).items() if R.amount(v))
267
+ used = "".join(f", used {num(v)} {lab.resources.get(k, {}).get('unit', k)}" + (" (stated by hand when it was closed)" if k in (r.get("used_by_hand") or []) else " (stated after it ended, from the evidence its amendment names)" if k in (r.get("used_amended") or []) else "") for k, v in (r.get("used") or {}).items() if R.amount(v))
268
268
  out += ["", f"{'Trial run' if r['kind'] == 'trial' else 'Run'} {r['id']}: {r['state']}" + (f" (exit {r['exit']})" if r["state"] == "failed" else "") + f"{used}, {r['dir']}"]
269
269
  out += [f" declared lost: {r['lost']}"] if r["lost"] else [" listed in runs.tsv; its folder is not in the store here"] if r["missing"] else []
270
270
  out += [f" closed by hand: {r['closed']}"] if r.get("closed") and not r["lost"] else []
@@ -223,3 +223,39 @@ def test_a_lock_is_read_from_history_by_lab_show_and_lab_check_alike(tmp_path):
223
223
  open(mission, "w").write(text.replace(f"carries: {d2}", f"carries: {d3}"))
224
224
  assert "A draft: nothing has acted on it yet" in lab(root, "show", d3)
225
225
  assert "Locked: acted on at" in lab(root, "show", d2)
226
+
227
+
228
+ def test_what_acts_after_a_fold_is_committed_acts_on_the_decision_that_took_it_in(tmp_path):
229
+ import time
230
+ root = str(tmp_path)
231
+ open_question(root)
232
+ ident, d, command = experiment(root)
233
+ card2, d2 = settled_order(root, [ident], "The first experiment first", "The error experiment first: it is the cheapest check of the law.")
234
+ card3, d3 = settled_order(root, [ident], "The first experiment, again", "The error experiment first, and nothing else before it.")
235
+ commit(root)
236
+ # D2 is folded into D3 while both are drafts, and the fold is committed
237
+ os.remove(card2)
238
+ front(card3, folds=f"[{d2}]")
239
+ commit(root, "D2 folded into D3")
240
+ time.sleep(1.1) # a run's start is kept to the second
241
+ # a run of the step D2 once ordered starts afterwards: it acts on D3, and D2 was folded while it was a draft
242
+ lab(root, "lock", ident)
243
+ lab(root, "run", ident, "--wait", "--", *command)
244
+ commit(root, "the run")
245
+ assert "the record is sound" in lab(root, "check", "--no-rederive")
246
+ assert "Locked: acted on at" in lab(root, "show", d3)
247
+
248
+ # a run that started before the fold was committed still locks the folded decision, though its line is committed with the fold
249
+ root = str(tmp_path / "before")
250
+ os.makedirs(root)
251
+ open_question(root)
252
+ ident, d, command = experiment(root)
253
+ card2, d2 = settled_order(root, [ident], "The first experiment first", "The error experiment first: it is the cheapest check of the law.")
254
+ card3, d3 = settled_order(root, [ident], "The first experiment, again", "The error experiment first, and nothing else before it.")
255
+ commit(root)
256
+ lab(root, "lock", ident)
257
+ lab(root, "run", ident, "--wait", "--", *command)
258
+ os.remove(card2)
259
+ front(card3, folds=f"[{d2}]")
260
+ commit(root, "the run, and D2 folded into D3")
261
+ assert f"is folded into {d3}, and something acted on it" in lab(root, "check", "--no-rederive", ok=False)
@@ -313,6 +313,52 @@ def test_what_a_run_says_it_used_is_an_amount(tmp_path):
313
313
  assert "gpu: 0 of 10 hours used" in lab(root, "now") and "nan" not in lab(root, "now").lower()
314
314
 
315
315
 
316
+ def test_an_ended_run_that_did_not_record_what_it_used_is_amended_beside_its_folder(tmp_path):
317
+ root = str(tmp_path)
318
+ open_question(root)
319
+ ident, d, command = experiment(root, uses="[gpu]", command=WRITES % "0.5") # it writes no used.json: stopped before it could
320
+ lab(root, "review", ident, "plan", "pass", "One thing varies; the refuting line can hold.")
321
+ lab(root, "lock", ident)
322
+ assert "finished" in lab(root, "run", ident, "--wait", "--", *command)
323
+ run_id = open(f"{d}/runs.tsv").read().splitlines()[1].split("\t")[0]
324
+ assert "did not record what it used" in lab(root, "check", "--no-rederive", ok=False)
325
+ os.makedirs(f"{root}/recovered/helper-1")
326
+ open(f"{root}/recovered/helper-1/used.json", "w").write('{"gpu": 0.75}\n')
327
+
328
+ # it names its evidence, outside the run's folder, and only what the run ran on and did not record
329
+ assert "--evidence <folder>" in lab(root, "runs", "close", run_id, "stopped", "--used", "gpu=0.75", ok=False)
330
+ assert "outside the run's folder" in lab(root, "runs", "close", run_id, "stopped", "--used", "gpu=0.75", "--evidence", f"runs/{run_id}", ok=False)
331
+ assert "a metered resource" in lab(root, "runs", "close", run_id, "stopped", "--used", "laptop=1", "--evidence", "recovered", ok=False)
332
+ assert "--evidence is for" in lab(root, "runs", "lost", run_id, "stopped", "--evidence", "recovered", ok=False)
333
+ out = lab(root, "runs", "close", run_id, "Stopped before its members' files came back; read from their used.json.", "--used", "gpu=0.75", "--evidence", "recovered")
334
+ assert f"amended: runs/{run_id}.amended.json" in out
335
+ seal = json.load(open(f"{root}/runs/{run_id}/run.json"))["seal"]
336
+ a = json.load(open(f"{root}/runs/{run_id}.amended.json"))
337
+ assert a["run_seal"] == seal and a["used"] == {"gpu": 0.75} and a["evidence"] == {"path": "recovered", "files": {"helper-1/used.json": a["evidence"]["files"]["helper-1/used.json"]}}
338
+ assert [r.split("\t")[2] for r in open(f"{d}/runs.tsv").read().splitlines()[1:]] == ["started", "ended", "amended"]
339
+ assert "the record is sound" in lab(root, "check", "--no-rederive")
340
+ assert "used 0.75 hours (stated after it ended" in lab(root, "show", ident) and "gpu: 0.75 of 10 hours used" in lab(root, "now")
341
+ assert "never rewritten" in lab(root, "runs", "close", run_id, "again", "--used", "gpu=1", "--evidence", "recovered", ok=False)
342
+
343
+ # the evidence, the amendment and its row in runs.tsv hold one another
344
+ open(f"{root}/recovered/helper-1/used.json", "w").write('{"gpu": 0.5}\n')
345
+ assert "the evidence of its amendment changed" in lab(root, "check", "--no-rederive", ok=False)
346
+ open(f"{root}/recovered/helper-1/used.json", "w").write('{"gpu": 0.75}\n')
347
+ ledger = open(f"{d}/runs.tsv").read()
348
+ open(f"{d}/runs.tsv", "w").write("\n".join(ledger.splitlines()[:-1]) + "\n")
349
+ assert "is not the one runs.tsv lists" in lab(root, "check", "--no-rederive", ok=False)
350
+ open(f"{d}/runs.tsv", "w").write(ledger)
351
+ path = f"{root}/runs/{run_id}.amended.json"
352
+ text = open(path).read()
353
+ os.chmod(path, 0o644)
354
+ open(path, "w").write(text.replace('"gpu": 0.75', '"gpu": 0.25'))
355
+ assert "does not match its seal" in lab(root, "check", "--no-rederive", ok=False)
356
+ os.remove(path)
357
+ assert "is not beside it in the store" in lab(root, "check", "--no-rederive", ok=False)
358
+ open(path, "w").write(text)
359
+ assert "the record is sound" in lab(root, "check", "--no-rederive")
360
+
361
+
316
362
  def test_a_run_may_write_any_file_and_a_run_is_named_by_its_id(tmp_path):
317
363
  root = str(tmp_path)
318
364
  open_question(root)
File without changes
File without changes
File without changes
File without changes
File without changes