lab-kit-cli 1.0.0__tar.gz → 1.0.2__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 (37) hide show
  1. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/CHANGELOG.md +65 -0
  2. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/PKG-INFO +1 -1
  3. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/docs/model.md +78 -9
  4. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/pyproject.toml +1 -1
  5. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/skills/lab-work/SKILL.md +3 -1
  6. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/src/lab_kit/__init__.py +1 -1
  7. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/src/lab_kit/checks.py +15 -4
  8. lab_kit_cli-1.0.2/src/lab_kit/history.py +242 -0
  9. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/src/lab_kit/record.py +82 -12
  10. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/src/lab_kit/runs.py +6 -1
  11. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/src/lab_kit/views.py +15 -1
  12. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/src/lab_kit/write.py +2 -0
  13. lab_kit_cli-1.0.2/tests/test_held.py +395 -0
  14. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/tests/test_integrity.py +25 -1
  15. lab_kit_cli-1.0.2/tests/test_needs.py +148 -0
  16. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/tests/test_refusals.py +1 -1
  17. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/tests/test_site.py +21 -0
  18. lab_kit_cli-1.0.0/src/lab_kit/history.py +0 -155
  19. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/.github/workflows/ci.yml +0 -0
  20. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/.github/workflows/policy.yml +0 -0
  21. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/.github/workflows/release.yml +0 -0
  22. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/.gitignore +0 -0
  23. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/AGENTS.md +0 -0
  24. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/CLAUDE.md +0 -0
  25. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/CONTRIBUTING.md +0 -0
  26. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/LICENSE +0 -0
  27. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/README.md +0 -0
  28. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/agents/reviewer.md +0 -0
  29. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/method/METHOD.md +0 -0
  30. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/skills/lab-review/SKILL.md +0 -0
  31. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/skills/lab-set-up/SKILL.md +0 -0
  32. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/skills/lab-talk/SKILL.md +0 -0
  33. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/src/lab_kit/cli.py +0 -0
  34. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/src/lab_kit/site.py +0 -0
  35. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/src/lab_kit/supervise.py +0 -0
  36. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/tests/test_flow.py +0 -0
  37. {lab_kit_cli-1.0.0 → lab_kit_cli-1.0.2}/tools/import_run.py +0 -0
@@ -1,5 +1,70 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.0.2
4
+
5
+ One defect found while rehearsing a real lab, four follow-ups from 1.0.1, and three larger word
6
+ budgets. The skill `lab-work` changed with the budgets: run `lab init` in a lab after upgrading, or
7
+ `lab check` reports that the skill differs from the installed kit.
8
+
9
+ - A step may need a step that sits later in the tree, such as a build under the second question
10
+ that needs a reading under the third. States used to be worked out in the order of the cards, so
11
+ the earlier step never saw that the later one was done: it stayed under "Not yours to move yet",
12
+ waiting on a step that was done, and `lab lock` and `lab run` refused it. Each step's state is now
13
+ worked out after everything it needs, wherever that sits. `lab now`, `lab show`, `lab brief` and
14
+ the site agree, since they read the same states.
15
+ - Steps that need each other in a circle were already a problem in `lab check`. Now none of them
16
+ moves until the circle is broken, even when one of them is done, and each says which need leads
17
+ back to it.
18
+ - Rows that a committed review passed stay. A reviewed `results.tsv` could be emptied together with
19
+ the card's Found and Means, committed, and later filled with other rows and reviewed again, with
20
+ `lab check` sound at every step. Once a results review that passed is committed with the rows it
21
+ read, those rows are held, whatever the card and the file say later. A draft row committed after
22
+ a review, which that review never read, may still be corrected.
23
+ - A step that needs one that is dropped or replaced says so in what it waits on, with what to do:
24
+ remove the need or replace it. A need that names nothing in the lab, or something that is not a
25
+ step, now holds the step in `lab lock` and `lab run`, as `lab check` already reported it.
26
+ - A `.pyc` file in `plan/` outside `__pycache__` is refused by `lab lock` and `lab run` and reported
27
+ by `lab check`, as a link is: Python would import it, and the plan's hash does not cover it.
28
+ - `lab check` says in a note when the repository is a shallow clone, and fails with `--strict`: the
29
+ history check needs every commit, and CI should fetch all of the history (`fetch-depth: 0`). The
30
+ model also says that the history read is that of the record under the lab's root as it is now,
31
+ so moving the root inside the repository starts again what is held.
32
+ - A plan that 1.0.0 locked or ran while a `__pycache__` sat in `plan/` verifies again. 1.0.0 counted
33
+ those files in the plan's hash and 1.0.1 does not, so such a record could never match. When a
34
+ hash of `plan/` does not match and the experiment's lock was made by 1.0.0, the folder is hashed
35
+ once more the way 1.0.0 did before a change is reported. It applies to no other lock, and only
36
+ while the cache files are still there as they were.
37
+ - `lab show <experiment>` says of each run how many files it holds, how many at the top of its
38
+ folder and how many under each folder there. It used to list ten files and leave out `work/`, so
39
+ a run whose output was all in `work/` looked nearly empty.
40
+ - Three word budgets are larger, because real cards were hitting them and ending in fragments: an
41
+ experiment's Found goes from 130 words to 180 and its Means from 90 to 150, and a question's So
42
+ far from 120 to 180. A budget is a ceiling against sprawl. If a card needs its last words cut
43
+ into fragments to fit, it is saying too much for one slot or the budget is wrong, and full
44
+ sentences win.
45
+
46
+ ## 1.0.1
47
+
48
+ Three defects found by moving a real repository to 1.0.0, and one message.
49
+
50
+ - `lab check` reads the history of the lab's own record only: `log.md`, `resources.toml`,
51
+ `decisions/`, and each experiment's lock, runs, results and reviews under `goals/`. It used to
52
+ read every file with one of those names anywhere in the repository, so a repository that once held
53
+ an older layout, since removed, failed for ever with "was committed and is gone".
54
+ - A file of the record is known by the numbers in its path. A folder or a decision renamed after a
55
+ reworded title is the same record: the rename is no longer reported as a removal, and what was
56
+ committed under the old name is still held under the new one. A file moved to another number, or
57
+ out of the record's places, is reported as gone.
58
+ - The hash of `plan/` leaves out `__pycache__` folders and `*.pyc` files, as it always meant to.
59
+ Importing a script from `plan/` no longer makes `lab check` say the plan changed after the run.
60
+ The hash of a folder that holds neither is what it was, in both formats, so every existing lock,
61
+ run and review still verifies.
62
+ - A card's `see:` that names a page of another library is a note, not a problem, when that
63
+ library's folder is not on the machine, as in CI. With `--strict` it is a failure. When the folder
64
+ is there and the page is not, it is still a problem.
65
+ - `lab run` says that the resources changed when `uses:` is not what was locked. It used to say the
66
+ demand had changed.
67
+
3
68
  ## 1.0.0
4
69
 
5
70
  A rewrite from first principles. Nothing of 0.6 carries over: a lab kept with 0.6 is not read by 1.0,
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.0.0
3
+ Version: 1.0.2
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
@@ -32,7 +32,9 @@ leads to is complete: it never points at something it does not explain ("the sev
32
32
  reproduction's setting", "our loop") without saying what that is in the same place. An experiment
33
33
  names each arm and says what it is. A term is explained in the sentence that first uses it; the
34
34
  glossary is a second chance, not the explanation. A slot may hold paragraphs and a list when that
35
- is clearer than one long sentence. The word budgets are ceilings against sprawl, not targets.
35
+ is clearer than one long sentence. The word budgets are ceilings against sprawl, not targets. If a
36
+ card needs its last words cut into fragments to fit, the card is saying too much for one slot or
37
+ the budget is wrong, and full sentences win.
36
38
 
37
39
  A run's id is `<date>-<time>_<experiment>_<four random characters>`, for example
38
40
  `20261110-1432_G1.Q2.3_k7f2`. It sorts by time, and two machines starting runs in the same minute cannot
@@ -117,7 +119,9 @@ Each arrow is a command that refuses when the step before it is missing. You see
117
119
  one stays in the tree with its results, folded under the new one with that sentence, and off the
118
120
  Now page. The lock also records the hash of `plan/` as it was locked, which is the plan the
119
121
  reviewer read: the first run is held against it as every later run is held against the run before.
120
- And it records the resources the experiment uses: `uses:` does not change after the lock.
122
+ And it records the resources the experiment uses: `uses:` does not change after the lock. `lab run`
123
+ refuses an experiment whose `uses:` is not what was locked, and says that it is the resources that
124
+ changed; `lab check` reports it.
121
125
  - **Run.** One try at producing what the experiment demands. An experiment is run until one run
122
126
  finishes. Each run pins the apparatus it ran, the configuration and the code in `plan/`, and is
123
127
  detached, so it outlives the session; its output is sealed and kept outside git. A run that fails
@@ -147,6 +151,34 @@ Each arrow is a command that refuses when the step before it is missing. You see
147
151
  `lab now` and `lab check` say which locks and lists of runs are not committed yet. With no commit
148
152
  at all nothing is held, and `lab check` says that too; `--strict` turns each of these into a
149
153
  failure.
154
+ **Reviewed rows stay.** The rows of `results.tsv` may change until a review passes them. Once a
155
+ results review that passed is committed together with the rows it read, those rows stay, each as
156
+ it was, whatever happens to the card and to the reviews after it. Emptying the file or removing it
157
+ together with Found and Means, and filling it later with other rows for a new review, is a
158
+ problem `lab check` reports at every step: a different result is a new experiment. A review is
159
+ bound to the rows it read by its `of`, so only those are held: a draft row committed after a
160
+ review, which that review never read, may still be corrected before the next review reads it.
161
+ **The history that is read.** The check reads the history of the record under the lab's root as
162
+ that root is now. Moving the lab's root inside its repository, or to another repository, starts
163
+ again what is held: what was committed under the old root is not compared. And it needs the
164
+ repository's full history. A shallow clone holds only its last commits, so against it almost
165
+ nothing is held: `lab check` says so in a note, and fails with `--strict`. CI fetches all of the
166
+ history before it checks (`fetch-depth: 0` in `actions/checkout`).
167
+ **Where the record is.** The check reads the history of the lab's own record and of nothing else:
168
+ `log.md` and `resources.toml` at the lab's root, `decisions/D<n>-<name>.md`, and each experiment's
169
+ `lock.json`, `runs.tsv`, `results.tsv` and `reviews.tsv` in its folder,
170
+ `goals/G<n>-<name>/Q<n>-<name>/<n>-<name>/`. The lab's root may be a folder inside a larger
171
+ repository. What that repository holds or once held anywhere else, such as the folders of a lab
172
+ kept with an earlier kit, or a file with one of these names inside `plan/`, is not the lab's
173
+ record: its history is not read, and removing it is not a problem.
174
+ **A rename.** A file of the record is known by the numbers in its path and not by the words:
175
+ `goals/G1-<any name>/Q2-<any name>/3-<any name>/lock.json` is the lock of `G1.Q2.3`, and
176
+ `decisions/D4-<any name>.md` is `D4`. When a title is reworded, the folder or the file named after
177
+ it may be renamed to match. That is a rename and nothing else: what was committed under the old
178
+ name is held under the new one, so the lock is still the lock first committed, every committed
179
+ row is still there, and a settled decision still says what it said. A number never changes. A file
180
+ that is under another number, or outside these places, is not that file: the one that was
181
+ committed is gone, and `lab check` says so, as it does for a file deleted outright.
150
182
  Two things keep this honest. The first run that finishes is the only source of results, and
151
183
  nothing more runs under that experiment, so nobody chooses which numbers count; a different try
152
184
  after that is a new experiment, because the numbers have been seen. And the apparatus of the run
@@ -248,7 +280,10 @@ that resource, under `about:`.
248
280
  ## 5. What the agent uses
249
281
 
250
282
  - **To look:** `lab now`, `lab show <id or path>`, `lab brief <question>`, `lab since`, `lab define <term>`. Each shows one level,
251
- so the agent reads a card before it opens a file.
283
+ so the agent reads a card before it opens a file. Of each run, `lab show <experiment>` says how
284
+ many files it holds and where: how many at the top of its folder, and how many under each folder
285
+ there, `work/` included. It lists none of them, so a run whose output is all in `work/` does not
286
+ look empty.
252
287
  - **To write:** `lab new` (a goal, a question, an experiment, a build, a reading, a decision),
253
288
  `lab log`, `lab decide`, `lab answer`.
254
289
  - **To be seen:** `lab log <id> doing "<what>" "<why now>"` whenever it starts on a card. It is the
@@ -300,9 +335,10 @@ file that is not text) is a problem it reports; no command stops on it.
300
335
 
301
336
  `lab check` runs the command of every row in every `results.tsv`, as a shell command, each for at
302
337
  most `rederive_timeout` seconds (`lab.toml`, 120 unless set). Run it only on a lab you trust, as
303
- you would its code; `--no-rederive` runs none of them. Where the lab has no commit, or the store
304
- is not mounted, the check says in a note what it could not check and still passes; with `--strict`
305
- that is a failure, which is what CI wants.
338
+ you would its code; `--no-rederive` runs none of them. Where the lab has no commit or its repository is a shallow clone, the store
339
+ is not mounted, or another library that a card's `see:` points into is not on the machine, the check
340
+ says in a note what it could not check and still passes; with `--strict` that is a failure, which is
341
+ what CI wants.
306
342
 
307
343
  Every command that writes validates everything first, so that a refusal leaves nothing half
308
344
  written, and only one of them writes at a time.
@@ -414,8 +450,8 @@ the first two lines that are exactly `---`. A key that holds a list (`needs`, `u
414
450
  | Card | Front matter | Slots (word budget) |
415
451
  | --- | --- | --- |
416
452
  | `goal.md` | `title:`, `from:` (its decision); `reached: true`; `dropped: <why>` | description (70), Claim (90), Example: the idea in one case, from the reader's own domain (260), Approach: the design, how this lab approximates it, and where it knowingly differs (340), Roles: a list, `- <role>: <who plays it and what it does>` (170), Vocabulary: a list, `- <word>: <what it means>`, the few words every card uses the same way (260) |
417
- | `question.md` | `title:` (a short name), `asks:` (the question in full), `from:`, `needs:`; `dropped: <why>`; `answer:` and `answered:` are written by `lab answer` | description: why we ask (130), How we would know (150), Example: one case step by step, a numbered list (380), We expect (70), Wrong if (70), So far (120) |
418
- | `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:`, `dropped: <why>` | description (70), Compares: the comparison in a sentence (80), Arms (260), Cases (100), Confirmed if (150), Refuted if (110), Outcomes (200), Limits (120), Found (130), Means (90) |
453
+ | `question.md` | `title:` (a short name), `asks:` (the question in full), `from:`, `needs:`; `dropped: <why>`; `answer:` and `answered:` are written by `lab answer` | description: why we ask (130), How we would know (150), Example: one case step by step, a numbered list (380), We expect (70), Wrong if (70), So far (180) |
454
+ | `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:`, `dropped: <why>` | description (70), Compares: the comparison in a sentence (80), Arms (260), Cases (100), Confirmed if (150), Refuted if (110), Outcomes (200), Limits (120), Found (180), Means (150) |
419
455
  | `reading.md` | `title:`, `needs:`, `dropped: <why>` | description (70), Looks at: what, and where it is (110), Seen (320), Suggests (150) |
420
456
  | `build.md` | `title:`, `needs:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
421
457
  | `D<n>-<slug>.md` | `title:`, `about:` (the goals, questions, experiments or resources it concerns), `date:`, `holds:`; `decided: {date, with}` is written by `lab decide` | Seen (120), Options: a list, one option an item (200), Recommendation (80), Decided (120) |
@@ -426,6 +462,12 @@ for background the lab rests on and did not write. A card's prose may link the s
426
462
  `[the words](target)`: a name the reader may not know, such as a paper or a method, is linked where
427
463
  it is first used.
428
464
 
465
+ `lab check` asks that every page under `see:` is there. A page of another library is looked for in
466
+ that library's folder, where the charter says it is. When the folder itself is not on the machine,
467
+ as in CI, which checks out the lab alone, the page cannot be looked for: that is a note, and a
468
+ failure only with `--strict`. When the folder is there and the page is not, or the charter names no
469
+ such library, it is a problem.
470
+
429
471
  **An arm** is a list item under Arms: its name, a colon, and what it is, so that a reader who has
430
472
  never seen it knows what was run.
431
473
 
@@ -489,7 +531,20 @@ existed. A lock that names its kit and lacks one of these is not a lock the kit
489
531
  **How a folder is hashed.** `plan/` is hashed file by file: the length of its path, the path, the
490
532
  length of its content, the content. A lock or a run made this way says `"hash": 2`. One with no such
491
533
  marker was made by an earlier kit, which wrote the path, a newline and the content; it is verified
492
- the way it was made, and never hashed again.
534
+ the way it was made, and never hashed again. Either way the hash leaves out what Python writes when
535
+ it imports a script, which is no part of the plan: a folder named `__pycache__` with everything in
536
+ it, and any file whose name ends in `.pyc`, wherever it sits. Nothing else is left out; a hidden
537
+ file is hashed like any other.
538
+
539
+ One exception, for what lab-kit 1.0.0 made. That version did hash those files, so a plan locked or
540
+ run while a `__pycache__` sat in `plan/` holds a hash that counts them. When a hash of `plan/` held
541
+ by a lock or a run does not match and the experiment's lock says `"kit": "1.0.0"`, the folder is
542
+ hashed once more the way 1.0.0 did, those files included, before a change is reported. It applies
543
+ to no other lock, and it verifies only while those files are still there as they were.
544
+
545
+ A `.pyc` file in `plan/` that is not inside a `__pycache__` is refused, as a link is: Python would
546
+ import it in place of a script, and no hash covers it. `lab lock` and `lab run` refuse the plan and
547
+ `lab check` reports it. Under a lock that 1.0.0 made, whose hash did count such a file, it stays.
493
548
 
494
549
  **`runs.tsv`**, beside the lock and in git, is written by `lab run` and by the run as it ends: `run`
495
550
  (its id), `kind` (run, trial), `what` (started, ended, lost), `at`, on the ended row `exit` and `seal`,
@@ -510,3 +565,17 @@ starting on and why now. A line written before the kit kept the time has none.
510
565
  open, then yes or no; a page calls an open question with nothing under it "not started". A build is in
511
566
  progress once the log has a line about it, and built once it names its commits. An experiment whose
512
567
  results review failed shows as review failed until it is replaced or dropped.
568
+
569
+ **What a step needs.** `needs:` on an experiment, a build or a reading names other steps, anywhere in
570
+ the tree: under its own question or another, before it or after it. A step is not the agent's to move
571
+ while one it needs is neither done nor built, and `lab lock` and `lab run` refuse it until then. Each
572
+ step's state is worked out after the state of everything it needs, wherever that sits, so the order
573
+ of the cards changes nothing: a build under the second question that needs a reading under the third
574
+ moves as soon as that reading is done. Every view says the same: `lab now`, `lab show`, `lab brief`,
575
+ and the site's pages and rail. Steps that need each other in a circle are a problem `lab check`
576
+ reports. Until the circle is broken none of them moves, whatever the others' states, and each says
577
+ which of its needs leads back to it. A step that needs one that is dropped or replaced would wait
578
+ for ever, so what it waits on says so, and says what to do: remove the need or replace it. A need
579
+ that names nothing in the lab, or something that is not a step, holds the step in `lab lock` and
580
+ `lab run` as `lab check` reports it. A question's `needs:` names the questions it builds on, for its
581
+ briefing; it changes no state.
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  dynamic = ["readme"]
7
7
  name = "lab-kit-cli"
8
- version = "1.0.0"
8
+ version = "1.0.2"
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" }]
@@ -43,7 +43,9 @@ The operator reads every card on the site, usually days later and without you. W
43
43
  - Say what is measured and what is your reading of it, in so many words.
44
44
  - Use a list when the content is a list (arms, options, steps), and a second paragraph when one
45
45
  sentence is carrying too much. The word budgets are ceilings, not targets: short is good only
46
- while nothing is missing.
46
+ while nothing is missing. A budget is there against sprawl. If a card needs its last words cut
47
+ into fragments to fit, the card is saying too much for one slot or the budget is wrong, and full
48
+ sentences win.
47
49
  - Read the card as someone who was not there. If a question comes to mind, the card answers it.
48
50
 
49
51
  ## When to open a decision
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.0.0"
2
+ __version__ = "1.0.2"
@@ -26,6 +26,7 @@ def run(lab, rederive=True):
26
26
  notes.append("the store is not here: runs and re-derivation were not checked")
27
27
  unchecked = True
28
28
 
29
+ absent = {} # the libraries the charter names whose folder is not on this machine
29
30
  # cards: each has its slots, stays short, and writes only what is its to write
30
31
  for n in lab.goals + lab.questions + lab.items + lab.decisions:
31
32
  try:
@@ -54,10 +55,17 @@ def run(lab, rederive=True):
54
55
  from . import site
55
56
  name, _, path = str(page).partition(":")
56
57
  lib = site.libraries(lab).get(name)
57
- if not lib or not os.path.exists(os.path.join(lib["path"], path.lstrip("/"))):
58
+ if not lib:
58
59
  bad("links", n["path"], f"see names {page}, which is not a page of a library the charter names")
60
+ elif not os.path.isdir(lib["path"]): # the other library is not on this machine, as in CI: nothing to look in
61
+ absent.setdefault(name, lib["path"])
62
+ elif not os.path.exists(os.path.join(lib["path"], path.lstrip("/"))):
63
+ bad("links", n["path"], f"see names {page}, and the library {name} holds no such page")
59
64
  elif not os.path.exists(os.path.join(library, str(page).split("#")[0], "index.html")):
60
65
  bad("links", n["path"], f"see names the page {page}, which is not in the library")
66
+ for name, path in sorted(absent.items()):
67
+ notes.append(f"the library {name} is not here ({path}): the pages cards name in it under `see:` could not be checked here")
68
+ unchecked = True
61
69
  for d in {os.path.dirname(x["path"]) for x in lab.items}:
62
70
  if sum(os.path.exists(os.path.join(root, d, f"{kind}.md")) for kind in R.STEPS) > 1:
63
71
  bad("tree", d, "holds more than one of an experiment, a build and a reading; a folder is one of them")
@@ -142,6 +150,9 @@ def run(lab, rederive=True):
142
150
  links = R.symlinks(os.path.join(d, "plan"))
143
151
  if links:
144
152
  bad("locks", p, f"plan/ holds a link, {links[0]}: what a link points at is not in plan/ and is not pinned")
153
+ stray = R.compiled(os.path.join(d, "plan")) if (x["lock"] or {}).get("kit") != "1.0.0" else [] # 1.0.0 hashed such a file with the plan
154
+ if stray:
155
+ bad("locks", p, f"plan/ holds a compiled file outside __pycache__, {stray[0]}: Python would import it, and a `.pyc` is not pinned")
145
156
  if x["lock"]:
146
157
  if lab.nodes[x["question"]]["state"] == "under discussion":
147
158
  bad("locks", p, f"is locked under {x['question']}, whose decision is not settled")
@@ -154,13 +165,13 @@ def run(lab, rederive=True):
154
165
  bad("locks", p, "is locked with no refuted-if line")
155
166
  if any(lab.metered(r) for r in x["uses"]) and not any(r.get("stage") == "plan" and r.get("verdict") == "pass" for r in x["reviews"]):
156
167
  bad("locks", p, "uses a metered resource and was locked with no passed review of its plan")
157
- if x["finished"] and x["finished"].get("plan") and x["finished"]["plan"] != lab.plan_hash(x, x["finished"]["how"]):
168
+ if x["finished"] and x["finished"].get("plan") and not lab.plan_is(x, x["finished"]["plan"], x["finished"]["how"]):
158
169
  bad("locks", p, f"plan/ changed after {x['finished']['id']}, the run its results come from; the apparatus of a finished run stays as it ran")
159
170
  ran = [r for r in x["runs"] if not r["missing"]]
160
- if ran and x["lock"].get("plan") and ran[0]["how"] == x["lock"]["hash"] and ran[0].get("plan") != x["lock"]["plan"] and not R.flat(ran[0].get("changed") or ""):
171
+ if ran and x["lock"].get("plan") and ran[0]["how"] == x["lock"]["hash"] and lab.plans_differ(x, ran[0].get("plan"), x["lock"]["plan"], ran[0]["how"]) and not R.flat(ran[0].get("changed") or ""):
161
172
  bad("runs", ran[0]["dir"], "ran a plan/ that differs from the one that was locked and does not say what changed and why")
162
173
  for before, after in zip(ran, ran[1:]):
163
- if before["how"] == after["how"] and before.get("plan") != after.get("plan") and not R.flat(after.get("changed") or ""):
174
+ if before["how"] == after["how"] and lab.plans_differ(x, before.get("plan"), after.get("plan"), after["how"]) and not R.flat(after.get("changed") or ""):
164
175
  bad("runs", after["dir"], f"ran a plan/ that differs from {before['id']}'s and does not say what changed and why")
165
176
  finished = [r for r in x["runs"] if r["state"] == "finished"]
166
177
  if len(finished) > 1:
@@ -0,0 +1,242 @@
1
+ """Permanence: what was committed is still there. Git is the only witness to an edit that leaves the files consistent.
2
+
3
+ What is held is held from the commit that first holds it: the record is tamper-evident through git, not tamper-proof.
4
+ Before that commit nothing is held, and `lab check` says so.
5
+
6
+ Only the lab's own record is read, at its places under the lab's root: `log.md`, `resources.toml`,
7
+ `decisions/D<n>-<name>.md`, and each experiment's `lock.json`, `runs.tsv`, `results.tsv` and `reviews.tsv` under
8
+ `goals/G<n>-<name>/Q<n>-<name>/<n>-<name>/`. What the repository holds or once held anywhere else is not the lab's.
9
+ A file is known by the numbers in its path and not by the words, so a folder renamed after a reworded title is the
10
+ same place: what was committed under the old name is held under the new one.
11
+
12
+ - A committed `lock.json` is byte for byte its first committed version.
13
+ - `log.md`, `reviews.tsv` and `runs.tsv` only grow: no committed line is removed or changed.
14
+ - A `results.tsv` that a review has passed keeps every committed row. Once a results review that passed is committed
15
+ together with the rows it read, those rows stay, whatever the card and the file say later. Rows committed while
16
+ the last passed review was of other rows, such as a draft row added after it, were never reviewed and are not held.
17
+ - A settled decision keeps its `decided:`, its `about:` and its Decided text as first committed.
18
+ - A resource, once committed, is never removed. A metered resource's `granted`, `per_run` and `unit` change only together
19
+ with `from`, which then names another settled decision that lists the resource. Its `other_use` rows only grow.
20
+ - None of these files is deleted, and none changes its number.
21
+ """
22
+ from __future__ import annotations
23
+
24
+ import glob, os, re, subprocess
25
+
26
+ from . import record as R
27
+
28
+ GROW = ("log.md", "reviews.tsv", "results.tsv", "runs.tsv")
29
+ STEP = re.compile(r"goals/G(\d+)-[^/]+/Q(\d+)-[^/]+/(\d+)-[^/]+/(lock\.json|reviews\.tsv|results\.tsv|runs\.tsv)")
30
+ DECISION = re.compile(r"decisions/D(\d+)-[^/]+\.md")
31
+
32
+
33
+ def git(root, *args):
34
+ p = subprocess.run(["git", "-C", root, *args], capture_output=True, text=True, errors="replace")
35
+ return p.stdout.lstrip("").replace("\r\n", "\n") if p.returncode == 0 else None
36
+
37
+
38
+ def committed(root):
39
+ """Whether the lab is in git with at least one commit: without one, nothing is held."""
40
+ return git(root, "rev-parse", "--is-inside-work-tree") is not None and git(root, "rev-parse", "HEAD") is not None
41
+
42
+
43
+ def subsequence(old, new):
44
+ """The first line of `old` that `new` no longer holds in order, or None."""
45
+ it = iter(new)
46
+ for line in old:
47
+ if not any(line == x for x in it):
48
+ return line
49
+ return None
50
+
51
+
52
+ def place(path):
53
+ """Where a path, from the lab's root, sits in the lab's record: `log.md`, `D4`, `G1.Q2.3/lock.json`. None when it is
54
+ not a file of the record. The numbers place a file and the words do not, so a renamed folder is the same place."""
55
+ if path == "log.md":
56
+ return path
57
+ m = STEP.fullmatch(path)
58
+ if m:
59
+ return f"G{int(m.group(1))}.Q{int(m.group(2))}.{int(m.group(3))}/{m.group(4)}"
60
+ m = DECISION.fullmatch(path)
61
+ return f"D{int(m.group(1))}" if m else None
62
+
63
+
64
+ def held(root, *where):
65
+ """Every committed version of the lab's record under these paths, by place: {place: [(commit, path)]}, oldest
66
+ first. A rename is read as what it is in git, the old path leaving and the new one arriving, so both names of
67
+ one place are in its list whether or not git would have paired them."""
68
+ out = git(root, "-c", "core.quotepath=off", "log", "--topo-order", "-m", "--no-renames", "--format=commit %H", "--name-status", "--relative", "--", *where) or ""
69
+ found, commit = {}, None
70
+ for line in out.split("\n"):
71
+ if line.startswith("commit "):
72
+ commit = line[7:].strip()
73
+ elif "\t" in line and not line.startswith("D"): # a path that left in this commit has no version in it
74
+ path = line.split("\t", 1)[1]
75
+ if place(path) and (commit, path) not in found.setdefault(place(path), []):
76
+ found[place(path)].append((commit, path))
77
+ return {k: v[::-1] for k, v in found.items()}
78
+
79
+
80
+ def present(root):
81
+ """The files of the record that are in the lab now, by place: {place: [path]}."""
82
+ found = {}
83
+ for pattern in ("log.md", "decisions/*", "goals/*/*/*/*"):
84
+ for full in sorted(glob.glob(os.path.join(glob.escape(root), pattern))):
85
+ path = os.path.relpath(full, root).replace(os.sep, "/")
86
+ if place(path) and os.path.isfile(full):
87
+ found.setdefault(place(path), []).append(path)
88
+ return found
89
+
90
+
91
+ def tables(text):
92
+ try:
93
+ return {k: v for k, v in R.tomllib.loads(text or "").items() if isinstance(v, dict)}
94
+ except R.tomllib.TOMLDecodeError:
95
+ return None
96
+
97
+
98
+ def resources(lab):
99
+ """What changed in resources.toml that no decision covers, commit by commit and since the last one."""
100
+ root, problems = lab.root, []
101
+ if not committed(root):
102
+ return problems
103
+ bad = lambda what: problems.append(f"history: resources.toml: {what}")
104
+ versions = [(f"in {c[:8]}", tables(git(root, "show", f"{c}:./resources.toml"))) for c in reversed((git(root, "log", "--format=%H", "--relative", "--", "resources.toml") or "").split())]
105
+ if not versions:
106
+ return problems
107
+ now = tables(R.read(os.path.join(root, "resources.toml"))) if os.path.isfile(os.path.join(root, "resources.toml")) else {}
108
+ versions = [v for v in versions + [("since the last commit", now)] if v[1] is not None]
109
+ rows = lambda r: [(str(o.get("date")), o.get("amount"), str(o.get("what"))) for o in (r.get("other_use") if isinstance(r.get("other_use"), list) else []) if isinstance(o, dict)]
110
+ for (_, old), (when, new) in zip(versions, versions[1:]):
111
+ for name, a in old.items():
112
+ b = new.get(name)
113
+ if b is None:
114
+ bad(f"{name} was removed {when}: a resource is never removed. One that is no longer used gets `retired = \"<why>\"`")
115
+ continue
116
+ if any(k in a for k in ("granted", "per_run")) and tuple(a.get(k) for k in ("granted", "per_run", "unit")) != tuple(b.get(k) for k in ("granted", "per_run", "unit")):
117
+ d = lab.nodes.get(str(b.get("from")))
118
+ if b.get("from") == a.get("from") or not d or d["type"] != "decision" or d["state"] != "decided" or name not in d["about"]:
119
+ bad(f"{name}: `granted`, `per_run` or `unit` changed {when}, and `from` does not name another settled decision: an amount changes out of a decision")
120
+ lost = subsequence(rows(a), rows(b))
121
+ if lost is not None:
122
+ bad(f"{name}: an `other_use` row was removed or changed {when}: {lost[0]}, {lost[1]}, {lost[2][:40]!r}. Rows are only added")
123
+ return sorted(set(problems))
124
+
125
+
126
+ def decisions(lab, versions=None, now=None):
127
+ """The settled decisions that are no longer as they were first committed settled."""
128
+ root, problems = lab.root, []
129
+ if not committed(root):
130
+ return problems
131
+ bad = lambda where, what: problems.append(f"history: {where}: {what}")
132
+ versions = held(root, "decisions") if versions is None else versions
133
+ now = present(root) if now is None else now
134
+
135
+ def settled(text):
136
+ """What a decision's card says was decided, and about what, or None while it says nothing."""
137
+ try:
138
+ fm, slots, _ = R.parse(text)
139
+ except Exception:
140
+ return None
141
+ if not isinstance(fm, dict) or fm.get("decided") is None:
142
+ return None
143
+ about = fm.get("about")
144
+ return str(fm.get("decided")), sorted(str(i) for i in (about if isinstance(about, list) else [about] if about is not None else [])), R.flat(slots.get("Decided", ""))
145
+
146
+ for where, commits in sorted(versions.items()):
147
+ if not DECISION.fullmatch(commits[-1][1]):
148
+ continue
149
+ if where not in now:
150
+ bad(commits[-1][1], "was committed and is gone; nothing recorded is removed")
151
+ continue
152
+ for c, path in commits: # oldest first, under whichever name it had then
153
+ was = settled(git(root, "show", f"{c}:./{path}") or "")
154
+ if was:
155
+ mine = path if path in now[where] else now[where][0]
156
+ if settled(R.read(os.path.join(root, mine))) != was:
157
+ bad(mine, f"was settled in {c[:8]}" + ("" if mine == path else f", as {path}") + ", and its `decided:`, its `about:` or its Decided text has changed since; a change of mind is a new decision")
158
+ break
159
+ return problems
160
+
161
+
162
+ def uncommitted(lab):
163
+ """The locks and the lists of runs that git does not hold yet as they are: until they are committed, nothing witnesses them."""
164
+ root = lab.root
165
+ if not committed(root):
166
+ return []
167
+ out = git(root, "status", "--porcelain", "--untracked-files=all", "--", ".") or ""
168
+ paths = {line[3:].split(" -> ")[-1].strip('"') for line in out.splitlines() if len(line) > 3}
169
+ top = (git(root, "rev-parse", "--show-prefix") or "").strip()
170
+ paths = {p[len(top):] if top and p.startswith(top) else p for p in paths}
171
+ found = []
172
+ for x in lab.experiments:
173
+ for name, what in (("lock.json", "its lock"), ("runs.tsv", "its list of runs")):
174
+ if os.path.join(x["dir"], name) in paths:
175
+ found.append(f"{x['id']}: {what} is not committed ({os.path.join(x['dir'], name)}): until it is, git does not hold it")
176
+ return found
177
+
178
+
179
+ def check(lab):
180
+ root, problems = lab.root, []
181
+ bad = lambda where, what: problems.append(f"history: {where}: {what}")
182
+ if not committed(root):
183
+ return [], ["this lab is not in git, or has no commit: permanence against history was not checked, and nothing recorded is held yet"]
184
+ notes = []
185
+ if (git(root, "rev-parse", "--is-shallow-repository") or "").strip() == "true":
186
+ notes.append("this repository is a shallow clone: the history check needs every commit, and compared the record with the few that are here. "
187
+ "Fetch the full history (`git fetch --unshallow`; in CI, `fetch-depth: 0`)")
188
+ versions, now = held(root, "log.md", "decisions", "goals"), present(root)
189
+ reviewed = {os.path.join(x["dir"], "results.tsv") for x in lab.experiments if x["reviewed"]}
190
+ for where, commits in sorted(versions.items()):
191
+ name = os.path.basename(commits[-1][1])
192
+ if name not in GROW + ("lock.json",):
193
+ continue # a decision, held below
194
+ if where not in now:
195
+ bad(commits[-1][1], "was committed and is gone; nothing recorded is removed")
196
+ continue
197
+ mine = lambda path: path if path in now[where] else now[where][0] # the same file, under the name it has now
198
+ named = lambda path: "" if mine(path) == path else f", as {path}"
199
+ if name == "lock.json":
200
+ c, path = commits[0]
201
+ if git(root, "show", f"{c}:./{path}") != R.read(os.path.join(root, mine(path))):
202
+ bad(mine(path), f"differs from the lock first committed in {c[:8]}{named(path)}; a changed plan is a new experiment")
203
+ continue
204
+ if name == "results.tsv": # rows may change until a review passes them
205
+ commits = commits[-1:] if mine(commits[-1][1]) in reviewed else []
206
+ for c, path in reversed(commits):
207
+ lost = subsequence((git(root, "show", f"{c}:./{path}") or "").splitlines(), R.read(os.path.join(root, mine(path))).splitlines())
208
+ if lost is not None:
209
+ bad(mine(path), f"a line committed in {c[:8]}{named(path)} is gone or changed: {lost[:70]!r}")
210
+ break
211
+
212
+ # A results review that passed, once committed with the rows it read, holds those rows: emptying the file with
213
+ # Found and Means leaves the experiment unreviewed now, and the rows are held all the same. The review is bound to
214
+ # what it read by its `of`, the hash `lab review` wrote: of results.tsv and of the seal of the finished run, both
215
+ # as that commit has them. Rows in a commit whose last passed review is of other rows were never reviewed.
216
+ for where, commits in sorted(versions.items()):
217
+ if os.path.basename(commits[-1][1]) != "reviews.tsv":
218
+ continue
219
+ rows, read = where.rsplit("/", 1)[0] + "/results.tsv", set()
220
+ if rows not in now:
221
+ continue # never committed, so nothing is held; or committed and gone, which is said above
222
+ for c, path in reversed(commits + versions.get(rows, [])): # every commit that touched the reviews or the rows
223
+ folder = os.path.dirname(path)
224
+ if c in read:
225
+ continue
226
+ read.add(c)
227
+ passed = [r for r in R.table(git(root, "show", f"{c}:./{folder}/reviews.tsv") or "", R.COLUMNS["reviews.tsv"]) if r.get("stage") == "results" and r.get("verdict") == "pass"]
228
+ was = git(root, "show", f"{c}:./{folder}/results.tsv") if passed else None
229
+ if was is None:
230
+ continue
231
+ listed = [l.split("\t") for l in (git(root, "show", f"{c}:./{folder}/runs.tsv") or "").split("\n")]
232
+ seals = [l[5] for l in listed if len(l) >= 6 and l[1] == "run" and l[2] == "ended" and l[4] == "0"] # the finished run, as that commit lists it
233
+ if passed[-1].get("of") not in {R.text_hash(R.text_hash(was) + str(seal))[:16] for seal in seals}:
234
+ continue # the last review that passed there read other rows than these
235
+ lost = subsequence(was.splitlines(), R.read(os.path.join(root, now[rows][0])).splitlines())
236
+ if lost is not None:
237
+ bad(now[rows][0], f"a row that a review had passed in {c[:8]} is gone or changed: {lost[:70]!r}. Reviewed rows stay; a different result is a new experiment")
238
+ break
239
+
240
+ problems += decisions(lab, versions, now)
241
+ problems += resources(lab)
242
+ return sorted(set(problems)), notes