lab-kit-cli 1.0.1__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 (36) hide show
  1. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/CHANGELOG.md +43 -0
  2. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/PKG-INFO +1 -1
  3. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/docs/model.md +47 -5
  4. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/pyproject.toml +1 -1
  5. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/skills/lab-work/SKILL.md +3 -1
  6. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/src/lab_kit/__init__.py +1 -1
  7. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/src/lab_kit/checks.py +6 -3
  8. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/src/lab_kit/history.py +36 -2
  9. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/src/lab_kit/record.py +76 -10
  10. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/src/lab_kit/runs.py +3 -1
  11. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/src/lab_kit/views.py +15 -1
  12. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/src/lab_kit/write.py +2 -0
  13. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/tests/test_held.py +174 -1
  14. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/tests/test_integrity.py +23 -0
  15. lab_kit_cli-1.0.2/tests/test_needs.py +148 -0
  16. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/tests/test_refusals.py +1 -1
  17. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/tests/test_site.py +21 -0
  18. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/.github/workflows/ci.yml +0 -0
  19. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/.github/workflows/policy.yml +0 -0
  20. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/.github/workflows/release.yml +0 -0
  21. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/.gitignore +0 -0
  22. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/AGENTS.md +0 -0
  23. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/CLAUDE.md +0 -0
  24. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/CONTRIBUTING.md +0 -0
  25. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/LICENSE +0 -0
  26. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/README.md +0 -0
  27. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/agents/reviewer.md +0 -0
  28. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/method/METHOD.md +0 -0
  29. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/skills/lab-review/SKILL.md +0 -0
  30. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/skills/lab-set-up/SKILL.md +0 -0
  31. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/skills/lab-talk/SKILL.md +0 -0
  32. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/src/lab_kit/cli.py +0 -0
  33. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/src/lab_kit/site.py +0 -0
  34. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/src/lab_kit/supervise.py +0 -0
  35. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/tests/test_flow.py +0 -0
  36. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.2}/tools/import_run.py +0 -0
@@ -1,5 +1,48 @@
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
+
3
46
  ## 1.0.1
4
47
 
5
48
  Three defects found by moving a real repository to 1.0.0, and one message.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.0.1
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
@@ -149,6 +151,19 @@ Each arrow is a command that refuses when the step before it is missing. You see
149
151
  `lab now` and `lab check` say which locks and lists of runs are not committed yet. With no commit
150
152
  at all nothing is held, and `lab check` says that too; `--strict` turns each of these into a
151
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`).
152
167
  **Where the record is.** The check reads the history of the lab's own record and of nothing else:
153
168
  `log.md` and `resources.toml` at the lab's root, `decisions/D<n>-<name>.md`, and each experiment's
154
169
  `lock.json`, `runs.tsv`, `results.tsv` and `reviews.tsv` in its folder,
@@ -265,7 +280,10 @@ that resource, under `about:`.
265
280
  ## 5. What the agent uses
266
281
 
267
282
  - **To look:** `lab now`, `lab show <id or path>`, `lab brief <question>`, `lab since`, `lab define <term>`. Each shows one level,
268
- 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.
269
287
  - **To write:** `lab new` (a goal, a question, an experiment, a build, a reading, a decision),
270
288
  `lab log`, `lab decide`, `lab answer`.
271
289
  - **To be seen:** `lab log <id> doing "<what>" "<why now>"` whenever it starts on a card. It is the
@@ -317,7 +335,7 @@ file that is not text) is a problem it reports; no command stops on it.
317
335
 
318
336
  `lab check` runs the command of every row in every `results.tsv`, as a shell command, each for at
319
337
  most `rederive_timeout` seconds (`lab.toml`, 120 unless set). Run it only on a lab you trust, as
320
- you would its code; `--no-rederive` runs none of them. Where the lab has no commit, the store
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
321
339
  is not mounted, or another library that a card's `see:` points into is not on the machine, the check
322
340
  says in a note what it could not check and still passes; with `--strict` that is a failure, which is
323
341
  what CI wants.
@@ -432,8 +450,8 @@ the first two lines that are exactly `---`. A key that holds a list (`needs`, `u
432
450
  | Card | Front matter | Slots (word budget) |
433
451
  | --- | --- | --- |
434
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) |
435
- | `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) |
436
- | `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) |
437
455
  | `reading.md` | `title:`, `needs:`, `dropped: <why>` | description (70), Looks at: what, and where it is (110), Seen (320), Suggests (150) |
438
456
  | `build.md` | `title:`, `needs:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
439
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) |
@@ -518,6 +536,16 @@ it imports a script, which is no part of the plan: a folder named `__pycache__`
518
536
  it, and any file whose name ends in `.pyc`, wherever it sits. Nothing else is left out; a hidden
519
537
  file is hashed like any other.
520
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.
548
+
521
549
  **`runs.tsv`**, beside the lock and in git, is written by `lab run` and by the run as it ends: `run`
522
550
  (its id), `kind` (run, trial), `what` (started, ended, lost), `at`, on the ended row `exit` and `seal`,
523
551
  and on a lost row `used` (`{"<resource>": <amount>}`, or empty) and `note` (why it is lost). When a
@@ -537,3 +565,17 @@ starting on and why now. A line written before the kit kept the time has none.
537
565
  open, then yes or no; a page calls an open question with nothing under it "not started". A build is in
538
566
  progress once the log has a line about it, and built once it names its commits. An experiment whose
539
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.1"
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.1"
2
+ __version__ = "1.0.2"
@@ -150,6 +150,9 @@ def run(lab, rederive=True):
150
150
  links = R.symlinks(os.path.join(d, "plan"))
151
151
  if links:
152
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")
153
156
  if x["lock"]:
154
157
  if lab.nodes[x["question"]]["state"] == "under discussion":
155
158
  bad("locks", p, f"is locked under {x['question']}, whose decision is not settled")
@@ -162,13 +165,13 @@ def run(lab, rederive=True):
162
165
  bad("locks", p, "is locked with no refuted-if line")
163
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"]):
164
167
  bad("locks", p, "uses a metered resource and was locked with no passed review of its plan")
165
- 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"]):
166
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")
167
170
  ran = [r for r in x["runs"] if not r["missing"]]
168
- 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 ""):
169
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")
170
173
  for before, after in zip(ran, ran[1:]):
171
- 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 ""):
172
175
  bad("runs", after["dir"], f"ran a plan/ that differs from {before['id']}'s and does not say what changed and why")
173
176
  finished = [r for r in x["runs"] if r["state"] == "finished"]
174
177
  if len(finished) > 1:
@@ -11,7 +11,9 @@ same place: what was committed under the old name is held under the new one.
11
11
 
12
12
  - A committed `lock.json` is byte for byte its first committed version.
13
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.
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.
15
17
  - A settled decision keeps its `decided:`, its `about:` and its Decided text as first committed.
16
18
  - A resource, once committed, is never removed. A metered resource's `granted`, `per_run` and `unit` change only together
17
19
  with `from`, which then names another settled decision that lists the resource. Its `other_use` rows only grow.
@@ -179,6 +181,10 @@ def check(lab):
179
181
  bad = lambda where, what: problems.append(f"history: {where}: {what}")
180
182
  if not committed(root):
181
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`)")
182
188
  versions, now = held(root, "log.md", "decisions", "goals"), present(root)
183
189
  reviewed = {os.path.join(x["dir"], "results.tsv") for x in lab.experiments if x["reviewed"]}
184
190
  for where, commits in sorted(versions.items()):
@@ -203,6 +209,34 @@ def check(lab):
203
209
  bad(mine(path), f"a line committed in {c[:8]}{named(path)} is gone or changed: {lost[:70]!r}")
204
210
  break
205
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
+
206
240
  problems += decisions(lab, versions, now)
207
241
  problems += resources(lab)
208
- return sorted(set(problems)), []
242
+ return sorted(set(problems)), notes
@@ -17,8 +17,8 @@ KINDS = ["decision", "agent", "result", "stuck", "doing"] # a decision recorded
17
17
  CLOSES = ("agent", "result", "stuck") # a later line of these kinds about the same card ends a `doing` line
18
18
  SLOTS = { # every slot a card has, with its word budget
19
19
  "goal": (("Claim", 90), ("Example", 260), ("Approach", 340), ("Roles", 170), ("Vocabulary", 260)),
20
- "question": (("How we would know", 150), ("Example", 380), ("We expect", 70), ("Wrong if", 70), ("So far", 120)),
21
- "experiment": (("Compares", 80), ("Arms", 260), ("Cases", 100), ("Confirmed if", 150), ("Refuted if", 110), ("Outcomes", 200), ("Limits", 120), ("Found", 130), ("Means", 90)),
20
+ "question": (("How we would know", 150), ("Example", 380), ("We expect", 70), ("Wrong if", 70), ("So far", 180)),
21
+ "experiment": (("Compares", 80), ("Arms", 260), ("Cases", 100), ("Confirmed if", 150), ("Refuted if", 110), ("Outcomes", 200), ("Limits", 120), ("Found", 180), ("Means", 150)),
22
22
  "build": (("How it works", 200), ("Works when", 80)),
23
23
  "reading": (("Looks at", 110), ("Seen", 320), ("Suggests", 150)),
24
24
  "decision": (("Seen", 120), ("Options", 200), ("Recommendation", 80)),
@@ -143,6 +143,16 @@ def symlinks(folder):
143
143
  return sorted(out)
144
144
 
145
145
 
146
+ def compiled(folder):
147
+ """Every `.pyc` file under a folder that is not inside a `__pycache__`. Python imports such a file as it would the
148
+ script of the same name, and no hash of the folder covers it."""
149
+ out = []
150
+ for top, dirs, files in os.walk(folder):
151
+ dirs[:] = [d for d in dirs if d != "__pycache__"]
152
+ out += [os.path.relpath(os.path.join(top, n), folder) for n in files if n.endswith(".pyc")]
153
+ return sorted(out)
154
+
155
+
146
156
  def sha(path):
147
157
  return hashlib.sha256(open(path, "rb").read()).hexdigest()
148
158
 
@@ -151,17 +161,18 @@ def text_hash(text):
151
161
  return hashlib.sha256(text.encode()).hexdigest()
152
162
 
153
163
 
154
- def tree_hash(folder, how=HASH):
164
+ def tree_hash(folder, how=HASH, cache=False):
155
165
  """One hash over a folder: every file's path and bytes, each preceded by its length, so that no two folders give
156
166
  the same hash. The first way (`how` 1: the path, a newline, the bytes) is kept to verify what was made with it.
157
167
  What Python leaves when it imports a script is not part of the folder, in either way: a `__pycache__` folder with
158
- everything under it, and a `*.pyc` file wherever it sits."""
168
+ everything under it, and a `*.pyc` file wherever it sits. With `cache` those are hashed too, which is what
169
+ lab-kit 1.0.0 did: kept only to verify a plan that 1.0.0 locked or ran while such files sat in it."""
159
170
  h, walked = hashlib.sha256(), []
160
171
  for root, dirs, files in os.walk(folder):
161
- dirs[:] = [d for d in dirs if d != "__pycache__"] # as the walk goes: sorting the walk first would read them all
172
+ dirs[:] = [d for d in dirs if cache or d != "__pycache__"] # as the walk goes: sorting the walk first would read them all
162
173
  walked.append((root, files))
163
174
  for root, files in sorted(walked):
164
- for name in sorted(f for f in files if not f.endswith(".pyc")):
175
+ for name in sorted(f for f in files if cache or not f.endswith(".pyc")):
165
176
  p = os.path.join(root, name)
166
177
  path, data = os.path.relpath(p, folder).encode(), open(p, "rb").read()
167
178
  h.update(path + b"\n" + data if how == 1 else len(path).to_bytes(8, "big") + path + len(data).to_bytes(8, "big") + data)
@@ -324,7 +335,8 @@ class Lab:
324
335
  self.results[row["ref"]] = row
325
336
  for q in self.questions:
326
337
  q["state"] = self._question_state(q)
327
- for x in self.items: # needs look at earlier items, so builds and experiments are settled in tree order
338
+ self.reach = self._reach()
339
+ for x in self._in_order(): # a step after everything it needs, wherever that sits in the tree
328
340
  x["state"], x["next"], x["mine"] = {"build": self._build_state, "reading": self._reading_state, "experiment": self._experiment_state}[x["type"]](x)
329
341
  for row in self.results.values(): # a number may be used on a card once its experiment is reviewed, and until it is replaced
330
342
  x = self.nodes[row["experiment"]]
@@ -715,9 +727,22 @@ class Lab:
715
727
  def before_hash(self, x):
716
728
  return text_hash("\n".join(f"{k}\n{flat(x['slots'].get(k, ''))}" for k in BEFORE))
717
729
 
718
- def plan_hash(self, x, how=HASH):
730
+ def plan_hash(self, x, how=HASH, cache=False):
719
731
  d = os.path.join(self.root, x["dir"], "plan")
720
- return tree_hash(d, how) if os.path.isdir(d) else "-"
732
+ return tree_hash(d, how, cache) if os.path.isdir(d) else "-"
733
+
734
+ def plan_is(self, x, pinned, how=HASH):
735
+ """Whether a hash of plan/ that a lock or a run holds is plan/ as it is now. lab-kit 1.0.0 hashed what Python
736
+ leaves in a folder, and no later kit does: under a lock that 1.0.0 made, a hash that does not match is tried
737
+ once more the way 1.0.0 hashed, before a change is reported."""
738
+ if pinned == self.plan_hash(x, how):
739
+ return True
740
+ return (x.get("lock") or {}).get("kit") == "1.0.0" and pinned == self.plan_hash(x, how, cache=True)
741
+
742
+ def plans_differ(self, x, a, b, how=HASH):
743
+ """Whether two hashes of plan/, held by a lock and a run or by two runs, are of two different plans. Under a
744
+ lock that 1.0.0 made, one may count what Python left and the other not: both are then plan/ as it is now."""
745
+ return a != b and not (self.plan_is(x, a, how) and self.plan_is(x, b, how))
721
746
 
722
747
  def content(self, x, stage, how=HASH):
723
748
  """One hash of what a review of this stage reads: the lines and the plan, or the results and the run they come
@@ -776,6 +801,41 @@ class Lab:
776
801
  return q["answer"]
777
802
  return "open" if self.settled(q) else "under discussion"
778
803
 
804
+ def _reach(self):
805
+ """For each step, every step it needs, directly or through what it needs: {id: {ids}}. A step that is in its
806
+ own set needs itself, which `lab check` reports."""
807
+ needs = {x["id"]: [i for i in x["needs"] if self.nodes.get(i, {}).get("type") in STEPS] for x in self.items}
808
+ out = {}
809
+ for ident in needs:
810
+ seen, todo = set(), list(needs[ident])
811
+ while todo:
812
+ i = todo.pop()
813
+ if i not in seen:
814
+ seen.add(i)
815
+ todo += needs[i]
816
+ out[ident] = seen
817
+ return out
818
+
819
+ def _in_order(self):
820
+ """The steps in the order their states are worked out: each after every step it needs, earlier or later in the
821
+ tree, and otherwise in tree order. Steps that need each other in a circle have no such order: the walk does not
822
+ go round, and `_blocked` holds each of them whatever the others' states."""
823
+ by, out, met = {x["id"]: x for x in self.items}, [], set()
824
+ for first in self.items:
825
+ if first["id"] in met:
826
+ continue
827
+ met.add(first["id"])
828
+ path = [(first, iter(first["needs"]))]
829
+ while path:
830
+ x, needs = path[-1]
831
+ need = next((by[i] for i in needs if i in by and i not in met), None)
832
+ if need is None:
833
+ out.append(path.pop()[0])
834
+ else:
835
+ met.add(need["id"])
836
+ path.append((need, iter(need["needs"])))
837
+ return out
838
+
779
839
  def _blocked(self, x):
780
840
  """Why nothing under this item may move yet, or None."""
781
841
  q, g = self.nodes[x["question"]], self.nodes[x["goal"]]
@@ -787,7 +847,13 @@ class Lab:
787
847
  return f"{q['id']} is {'answered ' + q['state'] if q['state'] in ('yes', 'no') else q['state']}"
788
848
  for need in x.get("needs") or []:
789
849
  n = self.nodes.get(need)
790
- if n and n.get("state") not in ("done", "built", "yes", "no"):
850
+ if n and x["id"] in self.reach.get(need, {need} if need == x["id"] else ()): # a circle of needs: nothing in it moves
851
+ return f"{need} {n['title']}, which needs {x['id']} in turn: no step in a circle of needs can move" if need != x["id"] else f"{need}, which is itself: a step cannot need itself"
852
+ if not n or n["type"] not in STEPS: # held here as `lab check` reports it: a need names a step
853
+ return f"{need}, which {'is not an experiment, a build or a reading' if n else 'does not exist'}: correct the need or remove it"
854
+ if n.get("state") in ("dropped", "replaced"): # it will never be done: waiting on it is waiting for ever
855
+ return f"{need} {n['title']}, which is {n['state']}: remove the need or replace it"
856
+ if n.get("state") not in ("done", "built"):
791
857
  return f"{need} {n['title']}"
792
858
  return None
793
859
 
@@ -111,6 +111,8 @@ def _start(lab, ident, command, trial, changed):
111
111
  plan = os.path.join(lab.root, x["dir"], "plan")
112
112
  if R.symlinks(plan):
113
113
  stop(f"{ident}: plan/ holds a link, {R.symlinks(plan)[0]}. A run pins what it executes, and what a link points at is not in plan/: copy it in")
114
+ if R.compiled(plan) and (x["lock"] or {}).get("kit") != "1.0.0": # 1.0.0 hashed such a file with the plan; no later kit does
115
+ stop(f"{ident}: plan/ holds a compiled file outside __pycache__, {R.compiled(plan)[0]}. Python would import it, and a `.pyc` is not pinned: remove it, and keep the script")
114
116
  from . import history
115
117
  if any(lab.metered(r) for r in x["uses"]): # before the hours are spent, not after
116
118
  against = history.resources(lab) + history.decisions(lab)
@@ -136,7 +138,7 @@ def _start(lab, ident, command, trial, changed):
136
138
  ran = [r for r in x["runs"] if not r["missing"]] # a lost run pinned nothing that can be read
137
139
  before = ran[-1] if ran else None # the first run is held against the plan/ that was locked
138
140
  was, how, since = (before.get("plan"), before["how"], f"what {before['id']} ran") if before else (x["lock"].get("plan"), x["lock"]["hash"], "what was locked")
139
- if was and was != lab.plan_hash(x, how) and not R.flat(changed):
141
+ if was and not lab.plan_is(x, was, how) and not R.flat(changed):
140
142
  stop(f"{ident}: plan/ is not {since}. Say what changed and why, in a sentence the operator can read: "
141
143
  f"lab run {ident} --changed \"<what changed since {'the last run' if before else 'the lock'}, and why>\" -- <command>")
142
144
  caps = {}
@@ -97,6 +97,20 @@ def tick(l):
97
97
  return f"- {l['say']} [{l['test'] or 'NO TEST'}]: {mark}{value}"
98
98
 
99
99
 
100
+ def held(r):
101
+ """What a run's folder holds, in one line: how many files, how many of them at the top, and how many under each
102
+ folder there. Nothing is listed, so no folder is hidden and no list is cut short."""
103
+ here, under = r["present"], {}
104
+ for p in here:
105
+ top = p.split("/", 1)[0] + "/" if "/" in p else ""
106
+ under[top] = under.get(top, 0) + 1
107
+ count = lambda n: f"{n:,} file{'' if n == 1 else 's'}"
108
+ parts = ([f"{under['']:,} at the top"] if under.get("") else []) + [f"{under[d]:,} under {d}" for d in sorted(under) if d]
109
+ gone = len(r["files"]) - len(here)
110
+ return (f"{count(len(here))}" + (": " + ", ".join(parts) if parts else "")
111
+ + (f". {count(gone)} it sealed {'is' if gone == 1 else 'are'} not here" if gone else ""))
112
+
113
+
100
114
  def _show(lab, ident):
101
115
  if ident not in lab.nodes: # a path, as the site's pages give it, names the node it belongs to
102
116
  found = lab.at(ident) if ("/" in ident or "." in os.path.basename(ident)) else None
@@ -171,7 +185,7 @@ def _show(lab, ident):
171
185
  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 []
172
186
  out += [f" closed by hand: {r['closed']}"] if r.get("closed") and not r["lost"] else []
173
187
  out += [f" changed since {'the run before' if x['runs'] and r is not x['runs'][0] else 'the lock'}: {r['changed']}"] if r.get("changed") else []
174
- out += [f" {p}" for p in sorted(r["present"]) if not p.startswith("work/")][:10]
188
+ out += [f" {held(r)}"] if r["files"] else []
175
189
  return "\n".join(out + decisions)
176
190
 
177
191
 
@@ -283,6 +283,8 @@ def lock(lab, ident):
283
283
  problems.append("plan/ is empty: it holds the configuration and the code the run executes")
284
284
  elif R.symlinks(plan):
285
285
  problems.append(f"plan/ holds a link, {R.symlinks(plan)[0]}: what a link points at is not in plan/ and is not pinned. Copy it in")
286
+ elif R.compiled(plan):
287
+ problems.append(f"plan/ holds a compiled file outside __pycache__, {R.compiled(plan)[0]}: Python would import it, and a `.pyc` is not pinned. Remove it, and keep the script")
286
288
  for r in x["uses"]:
287
289
  if r not in lab.resources:
288
290
  problems.append(f"uses {r}, which resources.toml does not list")
@@ -9,6 +9,10 @@ from test_integrity import WRITES, commit, done, under
9
9
  FIXED = {"a.py": b"print(1)\n", "b/c.txt": b"x\n", "a-b/d.cfg": b"k = 1\n", "b/e/f.json": b"{}\n", "Z.md": b"\xef\xbb\xbfcr\r\n", "b.py": b""}
10
10
  FIRST_WAY = "11376786fde57ae78bf9a099b1a8f1e4085e40640489f90acafac5f48654119f"
11
11
  AS_NOW = "9b4bebefd67a0699c57b4b5c2a431326b634f4d9a7a4d6f11a8087b34ee1d2fb"
12
+ # The same folder with what Python left in it, as the released 1.0.0 hashed it: 1.0.0 counted those files.
13
+ CACHE = {"__pycache__/a.cpython-312.pyc": b"\x00a", "b/__pycache__/c.cpython-310.pyc": b"\x00b", "b/stray.pyc": b"\x00c"}
14
+ FIRST_WAY_WITH_CACHE = "1aa294c663120a3b5b5e4448f1bb0d1e5bce9790403fe434002aa8e02e13c3c1"
15
+ AS_1_0_0_WITH_CACHE = "185df619bb23776ab90f0a0fb9a2be66882b7a7a73ee2a8d16c3c1f7009e381a"
12
16
 
13
17
 
14
18
  def put(folder, files):
@@ -183,14 +187,183 @@ def test_what_python_leaves_in_a_plan_is_not_the_plan(tmp_path):
183
187
  assert glob.glob(f"{d}/plan/__pycache__/sample.*.pyc")
184
188
  assert "finished" in lab(root, "run", ident, "--wait", "--", *command) # no `--changed` is asked for: nothing changed
185
189
  done(root, ident, d)
186
- shutil.copy(glob.glob(f"{d}/plan/__pycache__/sample.*.pyc")[0], f"{d}/plan/sample.pyc")
187
190
  put(d, {"plan/__pycache__/more.cpython-312.pyc": b"\x00"})
188
191
  out = lab(root, "check")
189
192
  assert "the record is sound" in out and "plan/ changed" not in out
193
+
194
+ # a compiled file outside __pycache__ is another matter: Python would import it, and no hash covers it
195
+ shutil.copy(glob.glob(f"{d}/plan/__pycache__/sample.*.pyc")[0], f"{d}/plan/sample.pyc")
196
+ out = lab(root, "check", "--no-rederive", ok=False)
197
+ assert "plan/ holds a compiled file outside __pycache__, sample.pyc" in out and "plan/ changed" not in out
198
+ os.remove(f"{d}/plan/sample.pyc")
199
+ assert "the record is sound" in lab(root, "check")
200
+ second, d2, command2 = experiment(root, title="Error at 1600 flips", command=WRITES % "0.5")
201
+ put(d2, {"plan/lib/helper.pyc": b"\x00compiled, with no script beside it"})
202
+ assert "plan/ holds a compiled file outside __pycache__, lib/helper.pyc" in lab(root, "lock", second, ok=False) and not os.path.exists(f"{d2}/lock.json")
203
+ assert "plan/ holds a compiled file outside __pycache__, lib/helper.pyc" in lab(root, "run", second, "--trial", "--wait", "--", *command2, ok=False)
204
+ os.remove(f"{d2}/plan/lib/helper.pyc")
205
+ lab(root, "lock", second)
206
+ put(d2, {"plan/lib/helper.pyc": b"\x00put there after the lock"})
207
+ assert "plan/ holds a compiled file outside __pycache__" in lab(root, "run", second, "--wait", "--", *command2, ok=False)
208
+ assert not glob.glob(f"{root}/runs/*{second}*") and not glob.glob(f"{root}/.lab/running/*{second}*")
209
+ os.remove(f"{d2}/plan/lib/helper.pyc")
210
+ assert "finished" in lab(root, "run", second, "--wait", "--", *command2)
211
+ open(f"{d}/plan/sample.py", "a").write("# after the fact\n")
212
+ assert "plan/ changed after" in lab(root, "check", "--no-rederive", ok=False)
213
+
214
+
215
+ def test_a_plan_that_1_0_0_hashed_with_its_cache_files_still_verifies(tmp_path):
216
+ sys.path.insert(0, SRC)
217
+ from lab_kit import record as R
218
+
219
+ # the 1.0.0 way of hashing, kept: a fixed folder with cache files gives what the released 1.0.0 gave
220
+ plan = under(tmp_path, "fixed")
221
+ put(plan, {**FIXED, **CACHE})
222
+ assert (R.tree_hash(plan, 1, cache=True), R.tree_hash(plan, 2, cache=True)) == (FIRST_WAY_WITH_CACHE, AS_1_0_0_WITH_CACHE)
223
+ assert (R.tree_hash(plan, 1), R.tree_hash(plan, 2)) == (FIRST_WAY, AS_NOW)
224
+
225
+ # a lock as 1.0.0 wrote it while a __pycache__ sat in plan/: its hash of plan/ counts the cache file
226
+ root = under(tmp_path, "lab")
227
+ open_question(root)
228
+ ident, d, command = experiment(root, command=WRITES % "0.5")
229
+ put(d, {"plan/__pycache__/sample.cpython-312.pyc": b"\x00left by an import"})
230
+ lab(root, "lock", ident)
231
+ with_cache = R.tree_hash(f"{d}/plan", 2, cache=True)
232
+ lock = json.load(open(f"{d}/lock.json"))
233
+ assert lock["plan"] == R.tree_hash(f"{d}/plan") != with_cache
234
+
235
+ def relock(kit):
236
+ open(f"{d}/lock.json", "w").write(json.dumps({**lock, "kit": kit, "plan": with_cache}, indent=1) + "\n")
237
+
238
+ # only a lock that 1.0.0 made is read that way: the same hash under any other kit is a changed plan
239
+ relock("1.0.1")
240
+ assert "plan/ is not what was locked" in lab(root, "run", ident, "--wait", "--", *command, ok=False)
241
+ relock("1.0.0")
242
+ assert "finished" in lab(root, "run", ident, "--wait", "--", *command) # no `--changed` is asked for: nothing changed
243
+ assert "the record is sound" in lab(root, "check", "--no-rederive") # the run pins the plan as hashed now, the lock as 1.0.0 hashed it: one plan
244
+
245
+ # the run as 1.0.0 would have recorded it: its hash of plan/ counts the cache file too
246
+ rj = glob.glob(f"{root}/runs/*/run.json")[0]
247
+ record = json.load(open(rj))
248
+ old_seal = record["seal"]
249
+ record["plan"] = with_cache
250
+ record["seal"] = R.seal_of(record)
251
+ os.chmod(rj, 0o644)
252
+ open(rj, "w").write(json.dumps(record, indent=1) + "\n")
253
+ listed = open(f"{d}/runs.tsv").read()
254
+ open(f"{d}/runs.tsv", "w").write(listed.replace(old_seal, record["seal"]))
255
+ done(root, ident, d)
256
+ assert "the record is sound" in lab(root, "check")
257
+ relock("1.0.1")
258
+ assert "plan/ changed after" in lab(root, "check", "--no-rederive", ok=False)
259
+ relock("1.0.0")
260
+
261
+ # it verifies only what was hashed: a cache file that changed, or went, is a plan that cannot be verified, and a changed script still shows
262
+ cache = f"{d}/plan/__pycache__/sample.cpython-312.pyc"
263
+ open(cache, "wb").write(b"\x00written again by a later import")
264
+ assert "plan/ changed after" in lab(root, "check", "--no-rederive", ok=False)
265
+ os.remove(cache)
266
+ assert "plan/ changed after" in lab(root, "check", "--no-rederive", ok=False)
267
+ open(cache, "wb").write(b"\x00left by an import")
268
+ assert "the record is sound" in lab(root, "check")
190
269
  open(f"{d}/plan/sample.py", "a").write("# after the fact\n")
191
270
  assert "plan/ changed after" in lab(root, "check", "--no-rederive", ok=False)
192
271
 
193
272
 
273
+ ROWS = "name\tlabel\tvalue\treads\tversus\tcommand\n"
274
+ CLEARED = dict(Found="", Means="")
275
+
276
+
277
+ def test_rows_that_a_committed_review_passed_stay_whatever_the_card_says_later(tmp_path):
278
+ kept = under(tmp_path, "kept")
279
+ ident, d = finished(kept) # locked, run, its results reviewed and passed, and all of it committed
280
+ root = str(tmp_path / "lab")
281
+ shutil.copytree(kept, root, symlinks=True)
282
+ d = root + d[len(kept):]
283
+ card, rows, was = f"{d}/experiment.md", f"{d}/results.tsv", open(f"{d}/results.tsv").read()
284
+ written = open(card).read()
285
+ held = "a row that a review had passed in"
286
+
287
+ # the file emptied together with Found and Means: nothing on the card contradicts it, and git still holds the rows
288
+ fill(card, **CLEARED)
289
+ open(rows, "w").write(ROWS)
290
+ out = lab(root, "check", ok=False)
291
+ assert held in out and "Reviewed rows stay" in out and "ratio" in out
292
+ open(rows, "w").write("")
293
+ assert held in lab(root, "check", ok=False)
294
+ os.remove(rows)
295
+ assert "results.tsv: was committed and is gone" in lab(root, "check", ok=False)
296
+
297
+ # the emptied file committed, then filled with other rows, reviewed again and committed: still held, at every step
298
+ open(rows, "w").write(ROWS)
299
+ commit(root, "emptied")
300
+ assert held in lab(root, "check", ok=False)
301
+ open(rows, "w").write(was.replace("the error at 400 flips as a share", "the error at 400 flips, read again, as a share"))
302
+ assert held in lab(root, "check", ok=False)
303
+ lab(root, "review", ident, "results", "pass", "Read the new rows; the command prints the value.")
304
+ open(card, "w").write(written)
305
+ assert "(done, confirmed)" in lab(root, "show", ident) # everything in the files agrees
306
+ assert held in lab(root, "check", ok=False)
307
+ commit(root, "filled with other rows")
308
+ out = lab(root, "check", ok=False)
309
+ assert held in out and "ratio\\tthe error at 400 flips as a share" in out
310
+
311
+ # in the lab as it was: a row added after the reviewed ones and read by a new review. Rows are only added
312
+ root, d = kept, kept + d[len(root):]
313
+ rows = f"{d}/results.tsv"
314
+ open(rows, "w").write(was + "ratio.high\tthe upper end of that share\t0.5\tpercent\tone half\tcat $RUN/ratio.txt\n")
315
+ lab(root, "review", ident, "results", "pass", "Read the added row.")
316
+ assert "the record is sound" in lab(root, "check")
317
+ commit(root, "a row added")
318
+ assert "the record is sound" in lab(root, "check", "--strict")
319
+
320
+ # a draft row committed after the review, which that review never read: it may be corrected, and then reviewed
321
+ root = under(tmp_path, "draft")
322
+ ident, d = finished(root)
323
+ rows, was = f"{d}/results.tsv", open(f"{d}/results.tsv").read()
324
+ open(rows, "w").write(was + "ratio.high\tthe uper end of taht share\t0.5\tpercent\tone half\tcat $RUN/ratio.txt\n")
325
+ assert "its results or its run changed after the review that passed them" in lab(root, "check", ok=False)
326
+ commit(root, "a draft row")
327
+ open(rows, "w").write(was + "ratio.high\tthe upper end of that share\t0.5\tpercent\tone half\tcat $RUN/ratio.txt\n")
328
+ lab(root, "review", ident, "results", "pass", "Read both rows; the label is corrected.")
329
+ commit(root, "the row corrected, and reviewed")
330
+ out = lab(root, "check", "--strict")
331
+ assert "the record is sound" in out and held not in out
332
+ open(rows, "w").write(was) # the corrected row was read by a committed review: now it stays
333
+ assert held in lab(root, "check", ok=False)
334
+
335
+ # rows no review has passed yet may still change, committed or not
336
+ root = under(tmp_path, "unreviewed")
337
+ open_question(root)
338
+ ident, d, command = experiment(root, command=WRITES % "0.5")
339
+ lab(root, "lock", ident)
340
+ lab(root, "run", ident, "--wait", "--", *command)
341
+ open(f"{d}/results.tsv", "w").write(ROWS + "ratio\ta first wording\t0.5\tpercent\tone half\tcat $RUN/ratio.txt\n")
342
+ commit(root)
343
+ open(f"{d}/results.tsv", "w").write(ROWS + "ratio\ta second wording\t0.5\tpercent\tone half\tcat $RUN/ratio.txt\n")
344
+ assert "the record is sound" in lab(root, "check")
345
+ open(f"{d}/results.tsv", "w").write(ROWS)
346
+ assert "the record is sound" in lab(root, "check")
347
+
348
+
349
+ def test_a_shallow_clone_holds_almost_nothing_and_the_check_says_so(tmp_path):
350
+ root = under(tmp_path, "lab")
351
+ ident, d = finished(root)
352
+ lab(root, "log", ident, "agent", "Read the result again.", "Nothing to add.")
353
+ commit(root, "a second commit")
354
+ shallow, full = str(tmp_path / "shallow"), str(tmp_path / "full")
355
+ subprocess.run(["git", "clone", "-q", "--depth", "1", f"file://{root}", shallow], check=True)
356
+ subprocess.run(["git", "clone", "-q", f"file://{root}", full], check=True)
357
+ for clone in (shallow, full):
358
+ shutil.copytree(f"{root}/runs", f"{clone}/runs") # the store is there in both: only the history differs
359
+ out = lab(shallow, "check")
360
+ assert "this repository is a shallow clone" in out and "fetch-depth: 0" in out and "the record is sound" in out
361
+ assert "not everything could be checked" in lab(shallow, "check", "--strict", ok=False)
362
+ assert "shallow" not in lab(full, "check", "--strict")
363
+ subprocess.run(["git", "fetch", "-q", "--unshallow"], cwd=shallow, check=True)
364
+ assert "shallow" not in lab(shallow, "check", "--strict")
365
+
366
+
194
367
  def test_a_page_of_another_library_is_looked_for_where_that_library_is(tmp_path):
195
368
  root = under(tmp_path, "lab")
196
369
  qdir = open_question(root)
@@ -360,6 +360,29 @@ def test_a_command_validates_everything_before_it_writes_and_quotes_what_it_writ
360
360
  assert "holds no other |" in lab(root, "check", "--no-rederive", ok=False)
361
361
 
362
362
 
363
+ def test_a_run_is_shown_by_how_many_files_it_holds_and_where(tmp_path):
364
+ # a run whose output is nearly all under work/, more than any list would show
365
+ root = str(tmp_path)
366
+ open_question(root)
367
+ paths = [f"work/traces/{n}.json" for n in range(14)] + ["work/scores.csv", "logs/a.log"]
368
+ deep = (WRITES % "0.5" + "".join(f"os.makedirs(os.environ['LAB_RUN'] + '/{p}', exist_ok=True)\n" for p in ("work/traces", "logs"))
369
+ + "".join(f"open(os.environ['LAB_RUN'] + '/{p}', 'w').write('x')\n" for p in paths))
370
+ ident, d, command = experiment(root, command=deep)
371
+ lab(root, "lock", ident)
372
+ lab(root, "run", ident, "--wait", "--", *command)
373
+ run = glob.glob(f"{root}/runs/*")[0]
374
+ held = len(json.load(open(f"{run}/run.json"))["files"])
375
+ top = held - len(paths)
376
+ out = lab(root, "show", ident)
377
+ assert f" {held} files: {top} at the top, 1 under logs/, 15 under work/" in out
378
+ assert "work/scores.csv" not in out and "ratio.txt" not in out # a count and the folders, and no list that could be cut short
379
+
380
+ # a file the run sealed that is no longer there is said, not left out of the count in silence
381
+ os.chmod(f"{run}/work", 0o755)
382
+ os.remove(f"{run}/work/scores.csv")
383
+ assert f" {held - 1} files: {top} at the top, 1 under logs/, 14 under work/. 1 file it sealed is not here" in lab(root, "show", ident)
384
+
385
+
363
386
  def test_commands_given_at_once_do_not_take_the_same_number_or_start_two_runs(tmp_path):
364
387
  root = str(tmp_path)
365
388
  open_question(root)
@@ -0,0 +1,148 @@
1
+ """A step may need a step anywhere in the tree, before it or after it, and every view says the same of it."""
2
+ import glob, re
3
+
4
+ from test_flow import describe, experiment, fill, folder, front, lab, open_question
5
+
6
+
7
+ def reading(root, question, title, done=True):
8
+ ident = re.search(r"made (\S+):", lab(root, "new", "reading", question, title)).group(1)
9
+ card = f"{folder(root, ident)}/reading.md"
10
+ describe(card, "Reads what the sampler already wrote, to say what the next step should be.")
11
+ fill(card, Looks_at="The sampler's own log.")
12
+ if done:
13
+ fill(card, Seen="- Nine estimates used the short sample.", Suggests="Fix the seed, then measure again.")
14
+ return ident, card
15
+
16
+
17
+ def across(root):
18
+ """Two questions. Under the first: a reading, a build and an experiment, each needing a reading under the second."""
19
+ open_question(root)
20
+ lab(root, "new", "question", "G1", "Does it hold further out?", "--from", "D1")
21
+ describe(glob.glob(f"{root}/goals/G1-*/Q2-*/question.md")[0], "What follows once the first sizes are measured.")
22
+ first, card = reading(root, "G1.Q1", "Which sizes to compare", done=False)
23
+ lab(root, "new", "build", "G1.Q1", "A sampler with a fixed seed")
24
+ describe(f"{folder(root, 'G1.Q1.2')}/build.md", "The sampler, with its seed set once.")
25
+ ident, d, command = experiment(root)
26
+ later, later_card = reading(root, "G1.Q2", "Every estimate that missed, by cause")
27
+ assert (first, ident, later) == ("G1.Q1.1", "G1.Q1.3", "G1.Q2.1")
28
+ for path in (card, f"{folder(root, 'G1.Q1.2')}/build.md", f"{d}/experiment.md"):
29
+ front(path, needs=f"[{later}]")
30
+ return ident, d, later_card
31
+
32
+
33
+ def mine(root):
34
+ """The ids `lab now` lists as the agent's to move, and those it lists as waiting."""
35
+ out = lab(root, "now")
36
+ ids = lambda text: re.findall(r"^- (G\d+\.Q\d+\.\d+) ", text, flags=re.M)
37
+ return ids(out.split("Yours next")[1].split("Not yours to move yet")[0]), ids(out.split("Not yours to move yet")[1].split("Questions")[0])
38
+
39
+
40
+ def test_a_step_may_need_one_that_sits_later_in_the_tree(tmp_path):
41
+ root = str(tmp_path)
42
+ ident, d, later_card = across(root)
43
+
44
+ # what is needed is done, under a later question: all three are the agent's to move, and every view says so
45
+ assert mine(root) == (["G1.Q1.1", "G1.Q1.2", "G1.Q1.3"], [])
46
+ assert "Next: read it" in lab(root, "show", "G1.Q1.1") and "Needs: G1.Q2.1 (done)" in lab(root, "show", "G1.Q1.1")
47
+ assert "Next: build it" in lab(root, "show", "G1.Q1.2") and "Next: lock it" in lab(root, "show", ident)
48
+ under = lab(root, "show", "G1.Q1").split("Under it")[1]
49
+ assert under.count(". Next: ") == 3 and "waiting on" not in lab(root, "brief", "G1.Q1") and lab(root, "brief", "G1.Q1").count("Next, for the agent: ") == 3
50
+ assert "the record is sound" in lab(root, "check")
51
+ assert "locked" in lab(root, "lock", ident)
52
+
53
+ # a chain that goes forward and back again: Q1.1 needs Q2.1, which needs Q2.2, which needs Q1.2
54
+ _, last = reading(root, "G1.Q2", "What the fixed seed changes", done=False)
55
+ front(later_card, needs="[G1.Q2.2]")
56
+ front(last, needs="[G1.Q1.2]")
57
+ front(f"{folder(root, 'G1.Q1.2')}/build.md", needs="[]")
58
+ fill(later_card, Suggests="")
59
+ assert mine(root) == (["G1.Q1.2"], ["G1.Q1.1", ident, "G1.Q2.1", "G1.Q2.2"]) # only the build at the end of the chain moves
60
+ front(f"{folder(root, 'G1.Q1.2')}/build.md", commits="[abc1234]", tests="[tests/test_seed.py]")
61
+ assert mine(root) == (["G1.Q2.2"], ["G1.Q1.1", ident, "G1.Q2.1"])
62
+ fill(last, Seen="- The spread halves.", Suggests="Measure at two sizes.")
63
+ assert mine(root) == (["G1.Q2.1"], ["G1.Q1.1", ident])
64
+ fill(later_card, Suggests="Fix the seed, then measure again.")
65
+ assert mine(root) == (["G1.Q1.1", ident], []) and "the record is sound" in lab(root, "check")
66
+
67
+
68
+ def test_a_step_waits_while_what_it_needs_is_not_done_wherever_that_sits(tmp_path):
69
+ root = str(tmp_path)
70
+ ident, d, later_card = across(root)
71
+ fill(later_card, Suggests="") # the reading under the second question is not done yet
72
+ assert mine(root) == (["G1.Q2.1"], ["G1.Q1.1", "G1.Q1.2", "G1.Q1.3"])
73
+ assert "G1.Q1.1 Which sizes to compare: on G1.Q2.1 Every estimate that missed, by cause" in lab(root, "now")
74
+ assert "Waiting on: G1.Q2.1 Every estimate that missed, by cause" in lab(root, "show", "G1.Q1.1") and "Needs: G1.Q2.1 (planned)" in lab(root, "show", ident)
75
+ assert lab(root, "brief", "G1.Q1").count("Waiting on G1.Q2.1") == 3
76
+ assert f"{ident} waits on G1.Q2.1" in lab(root, "lock", ident, ok=False)
77
+ assert f"{ident} waits on G1.Q2.1" in lab(root, "run", ident, "--trial", "--wait", "--", "true", ok=False)
78
+ assert not glob.glob(f"{d}/lock.json") and not glob.glob(f"{root}/runs/*") and not glob.glob(f"{root}/.lab/running/2*")
79
+
80
+
81
+ def test_steps_that_need_each_other_stay_where_they_are_and_say_why(tmp_path):
82
+ root = str(tmp_path)
83
+ ident, d, later_card = across(root)
84
+
85
+ # the reading that is done needs, in turn, the experiment that needs it: a circle, with one of its steps done
86
+ front(later_card, needs=f"[{ident}]")
87
+ out = lab(root, "check", ok=False)
88
+ assert f"{d[len(root) + 1:]}/experiment.md: needs itself, directly or through what it needs" in out
89
+ assert mine(root) == (["G1.Q1.1", "G1.Q1.2"], [ident]) # what only needs the done reading still moves; what is in the circle does not
90
+ why = "G1.Q2.1 Every estimate that missed, by cause, which needs G1.Q1.3 in turn: no step in a circle of needs can move"
91
+ assert f"{ident} Error at 100 and at 400 flips: on {why}" in lab(root, "now") and f"Waiting on: {why}" in lab(root, "show", ident)
92
+ assert f"{ident} waits on {why}" in lab(root, "lock", ident, ok=False) and not glob.glob(f"{d}/lock.json")
93
+ assert "Waiting on G1.Q2.1" in lab(root, "brief", "G1.Q1") and "reading (done)" in lab(root, "show", "G1.Q2.1")
94
+
95
+ # a longer circle with nothing done, and a step that needs itself: nothing loops, and each says which need leads back
96
+ fill(later_card, Suggests="")
97
+ front(later_card, needs="[G1.Q1.1]")
98
+ front(f"{folder(root, 'G1.Q1.1')}/reading.md", needs="[G1.Q1.2]")
99
+ front(f"{folder(root, 'G1.Q1.2')}/build.md", needs="[G1.Q2.1]")
100
+ front(f"{d}/experiment.md", needs=f"[{ident}]")
101
+ assert mine(root) == ([], ["G1.Q1.1", "G1.Q1.2", ident, "G1.Q2.1"])
102
+ out = lab(root, "now")
103
+ assert "G1.Q1.2 A sampler with a fixed seed, which needs G1.Q1.1 in turn" in out and "G1.Q2.1 Every estimate that missed, by cause, which needs G1.Q1.2 in turn" in out
104
+ assert f"on {ident}, which is itself: a step cannot need itself" in out and "G1.Q1.1 Which sizes to compare, which needs G1.Q2.1 in turn" in out
105
+ assert lab(root, "check", ok=False).count("needs itself, directly or through what it needs") == 4
106
+ assert "which is itself" in lab(root, "lock", ident, ok=False)
107
+
108
+ # the circle broken, everything moves again in the order of what needs what
109
+ front(later_card, needs="[]")
110
+ front(f"{d}/experiment.md", needs="[G1.Q1.2]")
111
+ assert mine(root) == (["G1.Q2.1"], ["G1.Q1.1", "G1.Q1.2", ident]) and "needs itself" not in lab(root, "check")
112
+
113
+
114
+ def test_a_need_that_can_never_be_met_says_so_and_holds_the_step(tmp_path):
115
+ root = str(tmp_path)
116
+ ident, d, later_card = across(root)
117
+
118
+ # the reading they need is dropped: nothing would ever end the wait, so what they wait on says what to do
119
+ front(later_card, dropped='"The log was not kept."')
120
+ why = "G1.Q2.1 Every estimate that missed, by cause, which is dropped: remove the need or replace it"
121
+ assert mine(root) == ([], ["G1.Q1.1", "G1.Q1.2", ident])
122
+ assert f"{ident} Error at 100 and at 400 flips: on {why}" in lab(root, "now") and f"Waiting on: {why}" in lab(root, "show", "G1.Q1.2")
123
+ assert f"{ident} waits on {why}" in lab(root, "lock", ident, ok=False) and not glob.glob(f"{d}/lock.json")
124
+
125
+ # an experiment that was replaced is the same: the need names the one that replaced it, or goes
126
+ old, d_old, _ = experiment(root, title="A first pair of sizes")
127
+ new, d_new, _ = experiment(root, title="A second pair of sizes")
128
+ front(f"{d_new}/experiment.md", replaces=old, because='"The first pair was too close."')
129
+ front(f"{d}/experiment.md", needs=f"[{old}]")
130
+ assert f"{ident} waits on {old} A first pair of sizes, which is replaced: remove the need or replace it" in lab(root, "lock", ident, ok=False)
131
+
132
+ # a need that names nothing in the lab, or a question, holds the step in the commands as the check reports it
133
+ front(f"{d}/experiment.md", needs="[G1.Q9.9]")
134
+ assert "needs G1.Q9.9, which is not an experiment, a build or a reading" in lab(root, "check", "--no-rederive", ok=False)
135
+ assert f"{ident} waits on G1.Q9.9, which does not exist: correct the need or remove it" in lab(root, "lock", ident, ok=False)
136
+ assert f"{ident} waits on G1.Q9.9, which does not exist" in lab(root, "run", ident, "--trial", "--wait", "--", "true", ok=False)
137
+ assert f"{ident} Error at 100 and at 400 flips: on G1.Q9.9, which does not exist" in lab(root, "now")
138
+ front(f"{d}/experiment.md", needs="[G1.Q2]")
139
+ assert f"{ident} waits on G1.Q2, which is not an experiment, a build or a reading" in lab(root, "lock", ident, ok=False)
140
+ assert not glob.glob(f"{d}/lock.json") and not glob.glob(f"{root}/runs/*") and not glob.glob(f"{root}/.lab/running/2*")
141
+
142
+ # locked while its needs were met, and a need that does not exist written after: `lab run` holds it too
143
+ front(f"{d}/experiment.md", needs="[]")
144
+ lab(root, "lock", ident)
145
+ front(f"{d}/experiment.md", needs="[G1.Q9.9]")
146
+ assert f"{ident} waits on G1.Q9.9, which does not exist" in lab(root, "run", ident, "--wait", "--", "true", ok=False)
147
+ front(f"{d}/experiment.md", needs="[]")
148
+ assert ident in mine(root)[0]
@@ -90,7 +90,7 @@ def test_what_the_check_refuses(tmp_path):
90
90
  assert "the record is sound" in lab(root, "check")
91
91
 
92
92
  # a card stays short, and writes only what is its to write: never a state, never a key the model does not give it
93
- broken(root, card, lambda t: t.replace("It converges as the theory says.", "word " * 91), "Means is 91 words, budget 90")
93
+ broken(root, card, lambda t: t.replace("It converges as the theory says.", "word " * 151), "Means is 151 words, budget 150")
94
94
  broken(root, card, lambda t: t.replace("Measures the error", "word " * 71 + "Measures the error"), "its description is ", "budget 70")
95
95
  broken(root, card, lambda t: t.replace("\n---\n", "\nstatus: done\n---\n", 1), "writes `status:`, which is worked out from the record")
96
96
  broken(root, card, lambda t: t.replace("\n---\n", "\nowner: someone\n---\n", 1), "`owner:` is not something a experiment card holds")
@@ -17,6 +17,7 @@ from html.parser import HTMLParser # noqa: E402
17
17
 
18
18
  from test_flow import describe, experiment, fill, front, lab, locked, results # noqa: E402
19
19
  from test_integrity import mutated # noqa: E402
20
+ from test_needs import across # noqa: E402
20
21
 
21
22
 
22
23
  def a_lab(tmp_path):
@@ -306,3 +307,23 @@ def test_a_lost_run_stays_on_its_experiments_page_with_the_reason(tmp_path):
306
307
  assert f"<code>{gone}</code>" in page and "Stopped with an error: declared lost: The machine was deleted with the run on it." in page
307
308
  lab(root, "run", ident, "--wait", "--", *command)
308
309
  assert "Finished on its second run" in Provider(root).get(ident).main
310
+
311
+
312
+ def test_a_step_that_needs_a_later_one_reads_on_every_page_as_it_does_in_the_command(tmp_path):
313
+ root = str(tmp_path)
314
+ ident, d, later_card = across(root) # a reading, a build and an experiment under Q1, each needing a done reading under Q2
315
+ site = Provider(root)
316
+ front_page = site.get("").main
317
+ assert front_page.count("<td>the agent</td>") == 3 and "<td>waits</td>" not in front_page
318
+ for step in ("G1.Q1.1", "G1.Q1.2", ident):
319
+ assert "Next, for the agent:" in site.get(step).main and "Waiting on" not in site.get(step).main, step
320
+ assert "Waiting on" not in site.get("G1.Q1").main and site.get("G1.Q1").main.count("Next: ") == 3
321
+ assert [i["status"] for r in site.rail() if "items" in r for i in r["items"]] == ["planned", "planned", "planned", "done"]
322
+
323
+ fill(later_card, Suggests="") # the reading they need is not done: all three wait on it, on every page
324
+ site = Provider(root)
325
+ front_page = site.get("").main
326
+ assert front_page.count("<td>waits</td>") == 3 and front_page.count("<td>the agent</td>") == 1
327
+ for step in ("G1.Q1.1", "G1.Q1.2", ident):
328
+ assert "Waiting on" in site.get(step).main and "Every estimate that missed, by cause" in site.get(step).main, step
329
+ assert site.get("G1.Q1").main.count("Waiting on ") == 3
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes