napkinstack 0.29.1__tar.gz → 0.30.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. {napkinstack-0.29.1 → napkinstack-0.30.0}/PKG-INFO +5 -5
  2. {napkinstack-0.29.1 → napkinstack-0.30.0}/README.md +4 -4
  3. {napkinstack-0.29.1 → napkinstack-0.30.0}/pyproject.toml +1 -1
  4. {napkinstack-0.29.1 → napkinstack-0.30.0}/pyproject.toml.orig +1 -1
  5. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/attest.py +116 -6
  6. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/cli.py +4 -2
  7. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/evidence.py +33 -3
  8. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/fitness/manifests.py +6 -1
  9. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/modules.py +6 -2
  10. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/pull_request.py +104 -7
  11. {napkinstack-0.29.1 → napkinstack-0.30.0}/LICENSE +0 -0
  12. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/__init__.py +0 -0
  13. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/__main__.py +0 -0
  14. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/agent.py +0 -0
  15. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/assurance.py +0 -0
  16. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/board.py +0 -0
  17. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/compat.py +0 -0
  18. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/discovery.py +0 -0
  19. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/doctor.py +0 -0
  20. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/fitness/__init__.py +0 -0
  21. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/fitness/boundaries.py +0 -0
  22. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/fitness/hygiene.py +0 -0
  23. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/fitness/plan.py +0 -0
  24. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/fitness/pr_scope.py +0 -0
  25. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/hold.py +0 -0
  26. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/landed.py +0 -0
  27. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/owners.py +0 -0
  28. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/project.py +0 -0
  29. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/provenance.py +0 -0
  30. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/settings.py +0 -0
  31. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/skills.py +0 -0
  32. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
  33. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
  34. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/templates/contracts/README.md +0 -0
  35. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
  36. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
  37. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/templates/module/AGENTS.md +0 -0
  38. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
  39. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/templates/module/README.md +0 -0
  40. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/templates/module/src/.gitkeep +0 -0
  41. {napkinstack-0.29.1 → napkinstack-0.30.0}/src/napkinstack/templates/module/tests/.gitkeep +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: napkinstack
3
- Version: 0.29.1
3
+ Version: 0.30.0
4
4
  Summary: Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI.
5
5
  License-Expression: MIT
6
6
  License-File: LICENSE
@@ -22,7 +22,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
22
22
  the project, which then receives new versions on demand; no application stack is imposed.
23
23
  Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
24
24
 
25
- > **Status: v0.29.1, published** on [PyPI](https://pypi.org/project/napkinstack/).
25
+ > **Status: v0.30.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
26
26
  > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
27
27
  > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
28
28
 
@@ -86,8 +86,8 @@ To try it without installing anything, or to install it from this repository ins
86
86
  registry — always pinned to a release tag:
87
87
 
88
88
  ```bash
89
- uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.29.1" nstack init my-project
90
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.29.1"
89
+ uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.30.0" nstack init my-project
90
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.30.0"
91
91
  ```
92
92
 
93
93
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -122,7 +122,7 @@ Each project then pins its version and changes it through `nstack update`.
122
122
  | `nstack pr-scope` | One PR = one module, review budget |
123
123
  | `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
124
124
  | `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
125
- | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine |
125
+ | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine, unless the module declares it sealed |
126
126
  | `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
127
127
  | `nstack pr-check` | The test sheet, the cycle and the attested checks, read from the pull request description |
128
128
  | `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
@@ -5,7 +5,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
5
5
  the project, which then receives new versions on demand; no application stack is imposed.
6
6
  Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
7
7
 
8
- > **Status: v0.29.1, published** on [PyPI](https://pypi.org/project/napkinstack/).
8
+ > **Status: v0.30.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
9
9
  > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
10
10
  > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
11
11
 
@@ -69,8 +69,8 @@ To try it without installing anything, or to install it from this repository ins
69
69
  registry — always pinned to a release tag:
70
70
 
71
71
  ```bash
72
- uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.29.1" nstack init my-project
73
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.29.1"
72
+ uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.30.0" nstack init my-project
73
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.30.0"
74
74
  ```
75
75
 
76
76
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -105,7 +105,7 @@ Each project then pins its version and changes it through `nstack update`.
105
105
  | `nstack pr-scope` | One PR = one module, review budget |
106
106
  | `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
107
107
  | `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
108
- | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine |
108
+ | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine, unless the module declares it sealed |
109
109
  | `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
110
110
  | `nstack pr-check` | The test sheet, the cycle and the attested checks, read from the pull request description |
111
111
  | `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "napkinstack"
3
- version = "0.29.1"
3
+ version = "0.30.0"
4
4
  description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
5
5
  requires-python = ">=3.12"
6
6
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "napkinstack"
3
- version = "0.29.1"
3
+ version = "0.30.0"
4
4
  description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
5
5
  requires-python = ">=3.12"
6
6
  license = "MIT"
@@ -7,7 +7,10 @@ test — on a clean tree at a commit, and appends the run to that commit's note
7
7
  `refs/notes/nstack/checks`, one JSON line per run. The note travels with the branch's remote
8
8
  and is merged line by line; the latest line for a commit is its record. On GitHub, with a token
9
9
  that may write statuses, the run is also shown as `nstack / local checks` — a name no CI job
10
- has. A ruleset that requires that name gates the merge on the record, and the forge's pull
10
+ has. A passed `Module checks` is kept, not run again, while the digest of what it reads is
11
+ unchanged — the modules it runs and those they consume from or assemble, the files outside the
12
+ modules, `contracts/` and `platform/` included, the engine and the person — for 7 days and 20 commits of the default branch at most (ADR-0006,
13
+ D223). A ruleset that requires that name gates the merge on the record, and the forge's pull
11
14
  request run leaves the record to it (D221): notes start no run, a status is an event.
12
15
  A record is *attested*, never *checked*: it makes a claim traceable, not true.
13
16
 
@@ -293,6 +296,93 @@ def why(output: str) -> list[str]:
293
296
  NAMED = re.compile(r".* \(commit [0-9a-f]{7,}\)|.*@[0-9a-f]{7,}|a local checkout at (?!an unknown commit)\S+(?<!-dirty)")
294
297
 
295
298
 
299
+ FRESH_DAYS = 7 # a check kept by its inputs, at most this old (ADR-0006, D223)
300
+ FRESH_COMMITS = 20 # and the default branch moved by at most this many commits since its run
301
+
302
+
303
+ SHARED_MODULES = ("contracts", "platform") # read by every module: counted as shared files (D223)
304
+
305
+
306
+ def inputs(root: Path, base: str, identity: str = "") -> str | None:
307
+ """The digest of what `Module checks` reads at HEAD (ADR-0006 decision 2, D223): the folders of
308
+ the modules it runs, of those they consume from or assemble, every tracked path outside the
309
+ module folders — `contracts/` and `platform/` included, which every module reads — and who runs
310
+ it with which engine; git's ids, never hashed by hand. None when it cannot be told: no key."""
311
+ import yaml
312
+
313
+ from napkinstack import modules
314
+
315
+ ran = modules.listing(root, base, with_contract_sides=True)
316
+ every = {module["name"]: module["folder"] for module in modules.listing(root) or []}
317
+ if ran is None:
318
+ return None
319
+ folders = {module["folder"] for module in ran}
320
+ for module in ran:
321
+ try:
322
+ data = yaml.safe_load((root / module["folder"] / "MANIFEST.yaml").read_text(encoding="utf-8")) or {}
323
+ except (OSError, yaml.YAMLError):
324
+ return None
325
+ consumes = data.get("consumes") if isinstance(data, dict) else None
326
+ assembles = data.get("assembles") if isinstance(data, dict) else None
327
+ named = [entry.get("module") for entry in consumes if isinstance(entry, dict) and entry.get("module")] \
328
+ if isinstance(consumes, list) else []
329
+ named += [name for name in assembles if isinstance(name, str)] if isinstance(assembles, list) else []
330
+ for name in named:
331
+ if name not in every:
332
+ return None # a dependency the project does not hold: what it reads is unknown
333
+ folders.add(every[name])
334
+ lines = [f"ran {' '.join(sorted(module['name'] for module in ran))}", f"identity {identity}"]
335
+ for folder in sorted(folders):
336
+ tree = _git(root, "rev-parse", "--verify", "--quiet", f"HEAD:{folder}", check=False).stdout.strip()
337
+ if not tree:
338
+ return None
339
+ lines.append(f"{folder} {tree}")
340
+ inside = tuple(f"{folder}/" for folder in every.values() if folder.split("/", 1)[0] not in SHARED_MODULES)
341
+ listed = _git(root, "ls-tree", "-r", "--full-tree", "HEAD", check=False)
342
+ if listed.returncode:
343
+ return None
344
+ lines += [line for line in listed.stdout.splitlines() if not line.split("\t", 1)[-1].startswith(inside)]
345
+ return hashlib.sha256("\n".join(lines).encode("utf-8", "surrogateescape")).hexdigest()
346
+
347
+
348
+ def _fresh(root: Path, at: str, run_base: str | None, base_commit: str | None) -> bool:
349
+ """Whether a run kept by its inputs is recent enough (ADR-0006, D223)."""
350
+ try:
351
+ when = datetime.datetime.fromisoformat(at)
352
+ except (TypeError, ValueError):
353
+ return False
354
+ now = datetime.datetime.now(datetime.timezone.utc)
355
+ if when.tzinfo is None or now - when > datetime.timedelta(days=FRESH_DAYS) or when - now > datetime.timedelta(minutes=5):
356
+ return False # too old, or from a clock ahead: never fresh for longer than the bound
357
+ if not run_base or not base_commit:
358
+ return False
359
+ moved = _git(root, "rev-list", "--count", f"{run_base}..{base_commit}", check=False)
360
+ return moved.returncode == 0 and int(moved.stdout.strip() or 0) <= FRESH_COMMITS
361
+
362
+
363
+ def _by_inputs(root: Path, base: str, digest: str | None, check: Check, engine: str, origin: str | None,
364
+ base_commit: str | None, who: str, said: str | None) -> dict | None:
365
+ """The check as a passed run on this branch's history left it, when what it reads is the same
366
+ — the digest of its inputs, whatever the commit — and the run is fresh (ADR-0006, D223)."""
367
+ if digest is None or not check.kept or base_commit is None or not (origin is None or NAMED.fullmatch(origin)):
368
+ return None
369
+ for commit in _git(root, "rev-list", f"{base_commit}..HEAD", check=False).stdout.split():
370
+ record = latest(root, commit)
371
+ if record is None or (record.get("engine"), record.get("origin"), record.get("published"),
372
+ record.get("by")) != (engine, said, origin is None, who):
373
+ continue
374
+ checks = record.get("checks") if isinstance(record.get("checks"), list) else []
375
+ found = next((c for c in checks if isinstance(c, dict) and c.get("name") == check.name), None)
376
+ if not found or found.get("passed") is not True or found.get("inputs") != digest:
377
+ continue
378
+ first = str(found.get("kept_from") or record.get("at", ""))
379
+ run_base = found.get("kept_base") or record.get("base_commit")
380
+ if not _fresh(root, first, run_base, base_commit):
381
+ continue
382
+ return {**found, "kept_from": first, "kept_commit": found.get("kept_commit") or commit, "kept_base": run_base}
383
+ return None
384
+
385
+
296
386
  def _kept(previous: dict | None, check: Check, engine: str, origin: str | None, base_commit: str | None,
297
387
  who: str, said: str | None = None) -> dict | None:
298
388
  """The check as the commit's record last passed it, when what it reads is the same: the commit,
@@ -307,8 +397,8 @@ def _kept(previous: dict | None, check: Check, engine: str, origin: str | None,
307
397
  return None
308
398
  checks = previous.get("checks") if isinstance(previous.get("checks"), list) else []
309
399
  found = next((c for c in checks if isinstance(c, dict) and c.get("name") == check.name), None)
310
- if not found or found.get("passed") is not True:
311
- return None
400
+ if not found or found.get("passed") is not True or found.get("kept_commit"):
401
+ return None # kept by its inputs from another commit: its freshness is _by_inputs' to judge (D223)
312
402
  return {**found, "kept_from": found.get("kept_from") or previous.get("at")}
313
403
 
314
404
 
@@ -355,8 +445,16 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
355
445
  engine, origin = provenance.engine()
356
446
  base_commit = _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}", check=False).stdout.strip() or None
357
447
  previous = None if again else latest(root, commit)
358
- # The option, else PR_LABELS as the caller set it: one way for attest and pr-check (D147).
359
- env = dict(os.environ, PR_LABELS=os.environ.get("PR_LABELS", "") if labels is None else labels)
448
+ # The option, else PR_LABELS as the caller set it: one way for attest and pr-check (D147) — and the
449
+ # pull request's own when the forge answers, a label it does not carry refused (#368).
450
+ from napkinstack.pull_request import labels_for
451
+
452
+ judged, labels_from, refused = labels_for(root, commit, os.environ.get("PR_LABELS", "") if labels is None else labels)
453
+ if refused:
454
+ print(f"FAIL [attest] {refused}")
455
+ return 1
456
+ print(f"Labels: {', '.join(sorted(judged)) or 'none'} — {labels_from}", flush=True)
457
+ env = dict(os.environ, PR_LABELS=",".join(sorted(judged)))
360
458
  # The engine that runs this command runs the checks: its folder first on the path.
361
459
  env["PATH"] = os.pathsep.join([str(Path(sys.argv[0]).resolve().parent), env.get("PATH", "")])
362
460
  results = []
@@ -369,6 +467,8 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
369
467
  # without asking for the record this run is making (A1, A2) — found rehearsing v0.10.0.
370
468
  env.update(NSTACK_BASE=base, NSTACK_BODY=str(Path(body).resolve()), NSTACK_TMP=tmp,
371
469
  NSTACK_ATTESTING=commit)
470
+ digest = inputs(root, base, json.dumps([engine, unplaced(origin, root), origin is None, who]))
471
+ env["NSTACK_INPUTS"] = digest or "" # the head's, for pr-check's T4 while this record is made (D223)
372
472
  for check in CHECKS:
373
473
  kept = _kept(previous, check, engine, origin, base_commit, who, unplaced(origin, root))
374
474
  if kept is not None:
@@ -376,6 +476,14 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
376
476
  print(f"ok [attest] {check.name}: kept from the record of {kept['kept_from']} — same commit, base "
377
477
  "and engine (nstack attest --again runs it)", flush=True)
378
478
  continue
479
+ kept = None if again else _by_inputs(root, base, digest, check, engine, origin, base_commit, who,
480
+ unplaced(origin, root))
481
+ if kept is not None:
482
+ results.append(kept)
483
+ print(f"ok [attest] {check.name}: kept from the run on {kept['kept_commit'][:7]} at {kept['kept_from']} — "
484
+ f"same inputs ({digest[:12]}), within {FRESH_DAYS} days and {FRESH_COMMITS} commits of the "
485
+ "default branch (nstack attest --again runs it)", flush=True)
486
+ continue
379
487
  steps = []
380
488
  for step in check.steps:
381
489
  done = subprocess.run(["bash", "-c", step.command], cwd=root, env=env,
@@ -384,7 +492,8 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
384
492
  "output": capped(done.stdout),
385
493
  "sha256": hashlib.sha256(done.stdout.encode("utf-8", "replace")).hexdigest()})
386
494
  passed = all(step["exit"] == 0 for step in steps)
387
- results.append({"name": check.name, "passed": passed, "steps": steps})
495
+ results.append({"name": check.name, "passed": passed, "steps": steps,
496
+ **({"inputs": digest} if check.kept and digest else {})})
388
497
  failed = "; ".join(f"{s['label']} exited {s['exit']}" for s in steps if s["exit"])
389
498
  print(f"FAIL [attest] {check.name}: {failed}" if failed else f"ok [attest] {check.name}", flush=True)
390
499
  for step in steps:
@@ -395,6 +504,7 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
395
504
  "engine": engine, "origin": origin, "published": origin is None, "by": who, "session": _session(root, commit),
396
505
  "base": base, "base_commit": base_commit, "checks": results,
397
506
  "sheet": sheet_of(body_text),
507
+ "labels": {"names": sorted(judged), "from": labels_from},
398
508
  # The audits of the run the module checks come from: kept with them, never read again (#275).
399
509
  "evidence": (previous.get("evidence") if isinstance(previous.get("evidence"), list) else [])
400
510
  if previous and any(r.get("kept_from") for r in results) else evidence_of(root, commit)}
@@ -169,7 +169,8 @@ def build_parser() -> argparse.ArgumentParser:
169
169
  lambda a: pull_request.run(a.root, a.base, a.body_file, a.labels))
170
170
  pc.add_argument("--base", default="origin/main")
171
171
  pc.add_argument("--body-file", type=Path, help="the description, when PR_BODY is not set")
172
- pc.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS)")
172
+ pc.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS); with a "
173
+ "token and one open pull request at the head, its own are read")
173
174
  ld = _add(sub, "landed", "what reached this branch outside a pull request, recorded (W1)",
174
175
  lambda a: landed.run(a.root, a.span, landed.from_environment(a.root)))
175
176
  ld.add_argument("--span", default="HEAD~1..HEAD",
@@ -178,7 +179,8 @@ def build_parser() -> argparse.ArgumentParser:
178
179
  lambda a: attest.run(a.root, a.base, a.body_file, a.labels, a.accept_identity, a.again))
179
180
  at.add_argument("--base", default="origin/main")
180
181
  at.add_argument("--body-file", type=Path, help="the pull request's description, for its checks")
181
- at.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS)")
182
+ at.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS); with a "
183
+ "token and one open pull request at the head, its own are read")
182
184
  at.add_argument("--accept-identity", action="store_true",
183
185
  help="record under an identity the project's history does not show yet — a first record of yours")
184
186
  at.add_argument("--again", action="store_true",
@@ -266,15 +266,33 @@ def prepare(root: Path, module: Path) -> Path | str:
266
266
 
267
267
 
268
268
  HELD = "NSTACK_E2E_HELD" # set for what the run starts: an e2e inside an e2e waits for nothing
269
+ WAIT_SAID_EVERY = 60.0 # seconds between two lines of a run that waits: a long wait is never read as a hang (#402)
270
+
271
+
272
+ def sealed(manifest: Path) -> bool:
273
+ """Whether the module declares its end-to-end run sealed, `evidence.sealed: true` (#402): its own
274
+ session, sound server and ports — nothing of the machine's that another run reads."""
275
+ try:
276
+ data = yaml.safe_load(manifest.read_text(encoding="utf-8")) or {}
277
+ except (OSError, yaml.YAMLError):
278
+ return False
279
+ section = data.get("evidence") if isinstance(data, dict) else None
280
+ return isinstance(section, dict) and section.get("sealed") is True
269
281
 
270
282
 
271
283
  @contextlib.contextmanager
272
- def one_at_a_time(root: Path, target: str):
284
+ def one_at_a_time(root: Path, target: str, is_sealed: bool = False):
273
285
  """One e2e at a time on this machine, for this user, whichever project or command starts it —
274
286
  `nstack e2e`, or `nstack attest` through it: what an end-to-end run drives (a sound server, a
275
287
  display, a port) is the machine's, and two runs reading it see each other's (#287). An advisory
276
288
  lock, `flock(2)`, released by the system when the holder exits however it exits; the one that
277
- waits says for whom."""
289
+ waits says for whom, and again every WAIT_SAID_EVERY seconds. A sealed run shares nothing of the
290
+ machine's: it neither waits nor holds the lock (#402)."""
291
+ if is_sealed:
292
+ print(f"-> {target}: sealed (evidence.sealed): runs beside any other end-to-end run on this machine",
293
+ flush=True)
294
+ yield
295
+ return
278
296
  try:
279
297
  import fcntl
280
298
  except ImportError: # no flock on this system: the runs are not kept apart
@@ -299,7 +317,19 @@ def one_at_a_time(root: Path, target: str):
299
317
  handle.seek(0)
300
318
  holder = handle.read().strip() or "another run"
301
319
  print(f"-> {target}: waits for the end-to-end run already on this machine — {holder}", flush=True)
302
- fcntl.flock(handle, fcntl.LOCK_EX)
320
+ began = said = time.monotonic()
321
+ while True:
322
+ try:
323
+ fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
324
+ break
325
+ except BlockingIOError:
326
+ time.sleep(min(1.0, WAIT_SAID_EVERY / 3))
327
+ if time.monotonic() - said >= WAIT_SAID_EVERY:
328
+ said = time.monotonic()
329
+ handle.seek(0)
330
+ holder = handle.read().strip() or holder
331
+ print(f"-> {target}: still waits for the end-to-end run already on this machine, "
332
+ f"{int(said - began) // 60} min {int(said - began) % 60} s so far — {holder}", flush=True)
303
333
  handle.seek(0)
304
334
  handle.truncate()
305
335
  started = datetime.datetime.now().astimezone().isoformat(timespec="seconds")
@@ -385,7 +385,7 @@ def declared_evidence(manifests: list[Path], root: Path) -> None:
385
385
  continue # absent, or not a mapping: M2 says it
386
386
  name, at = manifest.parent.name, f"{manifest.relative_to(root).as_posix()}:{line_of(text, 'evidence')}"
387
387
  action = " Action: evidence.provoked — a list of {pattern, level: warning|error, scenario} (.nstack/playbooks/tests.md)."
388
- for key in sorted(set(section) - {"provoked", "levels"}):
388
+ for key in sorted(set(section) - {"provoked", "levels", "sealed"}):
389
389
  fail(name, "M12", f"evidence has an unknown key '{key}': it declares nothing.\n{action}", at)
390
390
  provoked = section.get("provoked", [])
391
391
  if not isinstance(provoked, list):
@@ -410,6 +410,11 @@ def declared_evidence(manifests: list[Path], root: Path) -> None:
410
410
  fail(name, "M12", f"level {item['level']!r}: warning or error.\n{action}", at)
411
411
  if not isinstance(item["scenario"], str) or not item["scenario"].strip():
412
412
  fail(name, "M12", f"the declaration of {item['pattern']!r} names no scenario: say which provokes it.\n{action}", at)
413
+ if "sealed" in section and not isinstance(section["sealed"], bool):
414
+ fail(name, "M12", "evidence.sealed must be true or false: true when the module's end-to-end run brings its "
415
+ "own session, sound server and ports, and reads nothing of the machine's another run "
416
+ "reads.\n Action: evidence.sealed: true or false, or no key: the run then waits "
417
+ "its turn (.nstack/playbooks/tests.md).", at)
413
418
  if "levels" in section and not isinstance(section["levels"], str):
414
419
  fail(name, "M12", "evidence.levels must be text, a regular expression.\n"
415
420
  " Action: an expression whose group named level captures the line's level word.", at)
@@ -392,13 +392,17 @@ def run_verb(root: Path, verb: str, name: str | None, arguments: list[str] | Non
392
392
  # Its evidence: a folder of its own, its output kept, its logs read after (ADR-0009).
393
393
  from napkinstack import evidence
394
394
 
395
- with evidence.one_at_a_time(root, target):
395
+ sealed = evidence.sealed(manifest)
396
+ # HELD says an ancestor holds the machine: a sealed run holds nothing, so what it starts
397
+ # does not inherit it — a run it nests waits as any other would (#402).
398
+ held_for_children = {} if sealed else {evidence.HELD: "1"}
399
+ with evidence.one_at_a_time(root, target, is_sealed=sealed):
396
400
  folder = evidence.prepare(root, known[target])
397
401
  if isinstance(folder, str):
398
402
  print(f"FAIL [e2e] module '{target}': {folder}")
399
403
  return 1
400
404
  print(f"-> {target}: {command}", flush=True)
401
- code, held = evidence.run(command, known[target], {**os.environ, evidence.HELD: "1",
405
+ code, held = evidence.run(command, known[target], {**os.environ, **held_for_children,
402
406
  "NSTACK_EVIDENCE": str(folder.resolve())}, folder)
403
407
  passed = evidence.finish(root, target, known[target], folder, code, held)
404
408
  if code == evidence.NOT_RUN and passed:
@@ -32,7 +32,9 @@ The out-of-cycle label lifts K1 to K3 and K5, visibly and countably (.nstack/han
32
32
 
33
33
  Usage : nstack pr-check [--root ROOT] [--base BASE] [--body-file FILE] [--labels a,b]
34
34
  In CI : PR_BODY, PR_LABELS, PR_HEAD_SHA and PR_AUTHOR come from the pull_request event;
35
- --labels, when given, takes the place of PR_LABELS, as for nstack attest.
35
+ --labels, when given, takes the place of PR_LABELS, as for nstack attest. Elsewhere, with
36
+ a token and one open pull request at the head, its own labels are read, and a label
37
+ given that it does not carry is refused (#368).
36
38
 
37
39
  The verifier (T2) is a person, `@handle`, or an agent session, `session <id>`. The change's
38
40
  authors are the pull request's author, the GitHub accounts behind its commits' authors,
@@ -360,7 +362,7 @@ def _split(row: dict, width: int) -> bool:
360
362
  def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
361
363
  authorship: tuple[set[str], set[str], list[str]] = (set(), set(), []),
362
364
  strict: bool = False, unchanged: Callable[[str], bool] = lambda commit: False,
363
- hands: set[str] | None = None) -> list[str]:
365
+ hands: set[str] | None = None, same_inputs: Callable[[str], bool] = lambda commit: False) -> list[str]:
364
366
  """T1 to T5; returns the human-only scenarios, listed apart for the approver."""
365
367
  verifier, header, rows = read_sheet(body)
366
368
  if reasons and not rows:
@@ -416,7 +418,9 @@ def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
416
418
  # joins an earlier one after a `;`, never replacing it (#288).
417
419
  confirmed = [clause.strip().split(" ", 1)[0].strip("`").lower()
418
420
  for clause in row.get(CONFIRMED, "").split(";")]
419
- if kind.lower() == "automated" or strict:
421
+ if kind.lower() == "automated" and not strict and same_inputs(commit):
422
+ pass # what its module reads is unchanged since that run, and the run is fresh (D223)
423
+ elif kind.lower() == "automated" or strict:
420
424
  rerun.append(ident)
421
425
  elif not any(SHA.fullmatch(commit) and head.startswith(commit) for commit in confirmed):
422
426
  unconfirmed.append(ident)
@@ -490,8 +494,8 @@ def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, f
490
494
  fail("K3", f"no deliverable named.\n Action: \"Deliverable: D<n>\" in the description, "
491
495
  f"a deliverable of {path.name}."
492
496
  + ("" if labels else f"\n This run read no label. If the pull request is out of cycle, it "
493
- f"carries the {LABEL} label; a run on a workstation is given it with --labels {LABEL} "
494
- "(or PR_LABELS), as the forge passes its labels."))
497
+ f"carries the {LABEL} label, put on the pull request: a run on a workstation reads it there "
498
+ f"with a token, or is given it with --labels {LABEL} (or PR_LABELS)."))
495
499
  elif match[1] not in states:
496
500
  fail("K3", f"deliverable {match[1]} is not in {path.name}.\n Action: name one of "
497
501
  f"{', '.join(states) or 'its deliverables'}, or re-frame the cycle with the decider.")
@@ -631,6 +635,51 @@ def check_moved(body: str, recorded: list[tuple[str, str, dict]], fail: Fail, wa
631
635
  "description; restore it from the description's history otherwise.")
632
636
 
633
637
 
638
+ def _pull_labels(root: Path, head: str) -> tuple[int, set[str]] | str | None:
639
+ """The open pull request whose head is `head`, and its labels, read on the forge (#368); why not,
640
+ when it was asked; None when nothing is asked: off GitHub or without a token, and where the
641
+ labels given are already the pull request's — the forge's own run, and the checks nstack attest
642
+ runs with the labels it read."""
643
+ if os.environ.get("GITHUB_ACTIONS") == "true" or os.environ.get("NSTACK_ATTESTING") == head:
644
+ return None
645
+ from napkinstack import attest, hold
646
+
647
+ forge = hold._forge(root, attest._remote(root) or "origin")
648
+ if forge is None:
649
+ return None
650
+ try:
651
+ answer = hold._call(forge, "GET", f"/commits/{head}/pulls")
652
+ except hold.Refused as error:
653
+ return str(error)
654
+ pulls = [pull for pull in answer if isinstance(pull, dict) and pull.get("state") == "open"
655
+ and isinstance(pull.get("head"), dict) and pull["head"].get("sha") == head] if isinstance(answer, list) else []
656
+ if len(pulls) != 1:
657
+ return "no open pull request has this head" if not pulls else f"{len(pulls)} open pull requests have this head"
658
+ names = {str(label["name"]) for label in pulls[0].get("labels") or [] if isinstance(label, dict) and label.get("name")}
659
+ return int(pulls[0].get("number") or 0), names
660
+
661
+
662
+ def labels_for(root: Path, head: str, given: str) -> tuple[set[str], str, str | None]:
663
+ """The labels judged, where they come from, and a refusal: the pull request's own when it is read
664
+ — a label given that it does not carry is refused, since a label is what the reviewer sees on the
665
+ forge (#368); else the ones given, said as the caller's."""
666
+ named = {label.strip() for label in given.split(",") if label.strip()}
667
+ found = _pull_labels(root, head)
668
+ if isinstance(found, tuple):
669
+ number, carried = found
670
+ if extra := sorted(name for name in named if name.lower() not in {label.lower() for label in carried}):
671
+ return named, "", (f"pull request #{number} carries no label {', '.join(extra)}: a label is judged as the "
672
+ f"reviewer sees it on the forge.\n Action: put it on pull request #{number}, or "
673
+ "run without --labels and with PR_LABELS unset: the pull request's own are read.")
674
+ return carried, f"read from pull request #{number}", None
675
+ if os.environ.get("GITHUB_ACTIONS") == "true":
676
+ return named, "the pull request event's", None
677
+ if os.environ.get("NSTACK_ATTESTING") == head:
678
+ return named, "as nstack attest read them", None
679
+ return named, ("given by the caller (--labels, PR_LABELS)" if named else "none given") + (
680
+ f" — the pull request's not read: {found}" if found else ""), None
681
+
682
+
634
683
  def status_required(root: Path) -> bool:
635
684
  """Whether the base branch's rules require the record's own status, `nstack / local checks`
636
685
  (D221, #399): read on the forge's run only, from the rules that apply to the branch — readable
@@ -660,6 +709,50 @@ def status_required(root: Path) -> bool:
660
709
  for rule in rules if isinstance(rules, list))
661
710
 
662
711
 
712
+ def _module_inputs(record: dict | None) -> tuple[str, str, str | None] | None:
713
+ """A record's `Module checks` digest, its first run's time and base (ADR-0006, D223)."""
714
+ checks = record.get("checks") if isinstance(record, dict) and isinstance(record.get("checks"), list) else []
715
+ found = next((c for c in checks if isinstance(c, dict) and c.get("name") == "Module checks"), None)
716
+ if not found or found.get("passed") is not True or not found.get("inputs"):
717
+ return None
718
+ return str(found["inputs"]), str(found.get("kept_from") or record.get("at", "")), \
719
+ found.get("kept_base") or record.get("base_commit")
720
+
721
+
722
+ def same_inputs(root: Path, head: str, base: str) -> Callable[[str], bool]:
723
+ """T4's relief for an automated row (D223): the record of the row's commit and the head's hold
724
+ the same inputs digest, and the row's run is fresh. While nstack attest makes the head's record,
725
+ the digest it computed stands in for it."""
726
+ from napkinstack import attest
727
+
728
+ try:
729
+ answers = yaml.safe_load((root / ANSWERS).read_text(encoding="utf-8")) or {}
730
+ except (OSError, yaml.YAMLError):
731
+ answers = {}
732
+ if not isinstance(answers, dict) or answers.get("checks") != "attested":
733
+ return lambda commit: False # the forge's CI replays it: the relief is for attested checks
734
+ cache: dict[str, str | None] = {}
735
+
736
+ def head_digest() -> str | None:
737
+ if "head" not in cache:
738
+ if os.environ.get("NSTACK_ATTESTING") == head:
739
+ cache["head"] = os.environ.get("NSTACK_INPUTS") or None
740
+ else:
741
+ attest.read_remote(root)
742
+ found = _module_inputs(attest.latest(root, head))
743
+ cache["head"] = found[0] if found else None
744
+ return cache["head"]
745
+
746
+ def same(commit: str) -> bool:
747
+ full = _git(root, "rev-parse", "--verify", "--quiet", f"{commit}^{{commit}}").stdout.strip()
748
+ digest = head_digest()
749
+ found = _module_inputs(attest.latest(root, full)) if full and digest else None
750
+ base_commit = _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}").stdout.strip() or None
751
+ return bool(found and found[0] == digest and attest._fresh(root, found[1], found[2], base_commit))
752
+
753
+ return same
754
+
755
+
663
756
  def check_attested(root: Path, head: str, fail, warn=lambda message: None) -> str:
664
757
  """Where the checks are judged, as the decider's answer `checks` says (A1, A2): on the forge's
665
758
  CI, or attested on a workstation by `nstack attest` — then a complete, passed record of the
@@ -738,7 +831,7 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
738
831
  modules = touched_modules(root, fork, files)
739
832
  # The option, else PR_LABELS: one way for pr-check and attest alike (D147).
740
833
  given = os.environ.get("PR_LABELS", "") if labels_given is None else labels_given
741
- labels = {label.strip() for label in given.split(",") if label.strip()}
834
+ labels, labels_from, refused = labels_for(root, head, given)
742
835
 
743
836
  failures: list[str] = []
744
837
  warnings = charter_without_pdr(root, base, files)
@@ -746,6 +839,9 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
746
839
  def fail(rule: str, message: str) -> None:
747
840
  failures.append(f"[{rule}] {message}")
748
841
 
842
+ if refused:
843
+ fail("labels", refused)
844
+
749
845
  reasons = [reason for folder, found in modules.items() if (reason := sheet_reason(folder, found))]
750
846
  authorship = authors(root, base, head, os.environ.get("PR_AUTHOR", ""))
751
847
  # A commit whose tree is the head's is the head, for a sheet (D93): merging the default
@@ -764,7 +860,7 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
764
860
  f"request is not read: {hands}.")
765
861
  human_only = check_sheet(body, head, reasons, fail, authorship, rerun_at_head(modules),
766
862
  lambda commit: bool(tree_of(commit)) and tree_of(commit) == tree_of(head),
767
- hands if isinstance(hands, set) else None) if carried else []
863
+ hands if isinstance(hands, set) else None, same_inputs(root, head, base)) if carried else []
768
864
  if modules:
769
865
  check_cycle(root, body, labels, datetime.date.today(), fail, warnings.append)
770
866
  check_hold(root, body, labels, authorship, fail, warnings.append, identities(root, base, head))
@@ -778,6 +874,7 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
778
874
  + ("" if carried or not reasons else " — no carrier: forge none has no pull request. T1 to T5 "
779
875
  "judge a sheet filled in docs/pull_request_template.md — with its Deliverable line — passed by "
780
876
  "nstack attest --body-file <file>"))
877
+ print(f"Labels : {', '.join(sorted(labels)) or 'none'} — {labels_from}")
781
878
  print(f"Checks : {checks}")
782
879
  for line in summary(body, authorship) if reasons and carried else []:
783
880
  print(line)
File without changes