cfdbender 0.4.2__py3-none-any.whl

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 (77) hide show
  1. cfdbender/__init__.py +7 -0
  2. cfdbender/_pyfs.py +92 -0
  3. cfdbender/core/__init__.py +13 -0
  4. cfdbender/core/adapter.py +148 -0
  5. cfdbender/core/executables.py +157 -0
  6. cfdbender/core/flight.py +346 -0
  7. cfdbender/core/matrix.py +354 -0
  8. cfdbender/core/naming.py +172 -0
  9. cfdbender/core/plan.py +463 -0
  10. cfdbender/core/registry.py +735 -0
  11. cfdbender/core/results.py +117 -0
  12. cfdbender/core/run.py +150 -0
  13. cfdbender/core/settings.py +92 -0
  14. cfdbender/core/workspace.py +93 -0
  15. cfdbender/geometry/__init__.py +1 -0
  16. cfdbender/geometry/blade_slicing.py +355 -0
  17. cfdbender/hpc/__init__.py +21 -0
  18. cfdbender/hpc/_plan.py +266 -0
  19. cfdbender/hpc/_profiles.py +305 -0
  20. cfdbender/hpc/_render.py +271 -0
  21. cfdbender/hpc/_submit.py +96 -0
  22. cfdbender/hpc/_walltime.py +301 -0
  23. cfdbender/matrix/__init__.py +1 -0
  24. cfdbender/matrix/cli.py +228 -0
  25. cfdbender/matrix/collection.py +251 -0
  26. cfdbender/matrix/exports.py +122 -0
  27. cfdbender/matrix/rerun.py +126 -0
  28. cfdbender/matrix/selection.py +62 -0
  29. cfdbender/matrix/submission.py +272 -0
  30. cfdbender/solvers/__init__.py +47 -0
  31. cfdbender/solvers/_host/__init__.py +1 -0
  32. cfdbender/solvers/_host/_config.py +10 -0
  33. cfdbender/solvers/_host/_execute.py +52 -0
  34. cfdbender/solvers/_host/_mesh.py +62 -0
  35. cfdbender/solvers/_host/_ram.py +69 -0
  36. cfdbender/solvers/_host/_single.py +63 -0
  37. cfdbender/solvers/flightstream/__init__.py +114 -0
  38. cfdbender/solvers/flightstream/reader.py +191 -0
  39. cfdbender/solvers/mock/__init__.py +273 -0
  40. cfdbender/solvers/openfoam/__init__.py +201 -0
  41. cfdbender/solvers/openfoam/_config.py +410 -0
  42. cfdbender/solvers/openfoam/_execute.py +162 -0
  43. cfdbender/solvers/openfoam/_history.py +158 -0
  44. cfdbender/solvers/pyfr/__init__.py +118 -0
  45. cfdbender/solvers/pyfr/_config.py +196 -0
  46. cfdbender/solvers/pyfr/_execute.py +127 -0
  47. cfdbender/solvers/pyfr/_history.py +88 -0
  48. cfdbender/solvers/qprop/__init__.py +303 -0
  49. cfdbender/solvers/qprop/_config.py +259 -0
  50. cfdbender/solvers/qprop/_execute.py +269 -0
  51. cfdbender/solvers/qprop/_output.py +64 -0
  52. cfdbender/solvers/qprop/_polar.py +98 -0
  53. cfdbender/solvers/qprop/_prop.py +81 -0
  54. cfdbender/solvers/qprop/_sections.py +193 -0
  55. cfdbender/solvers/su2/__init__.py +210 -0
  56. cfdbender/solvers/su2/_config.py +290 -0
  57. cfdbender/solvers/su2/_execute.py +196 -0
  58. cfdbender/solvers/su2/_history.py +117 -0
  59. cfdbender/solvers/su2/_pysu2_worker.py +25 -0
  60. cfdbender/solvers/su2/_ram.py +13 -0
  61. cfdbender/solvers/su2/_reference.py +79 -0
  62. cfdbender/solvers/su2/_single.py +3 -0
  63. cfdbender/solvers/su2/routes.py +61 -0
  64. cfdbender/solvers/xfoil/__init__.py +171 -0
  65. cfdbender/solvers/xfoil/_config.py +144 -0
  66. cfdbender/solvers/xfoil/_execute.py +227 -0
  67. cfdbender/solvers/xfoil/_polar.py +88 -0
  68. cfdbender/testing/__init__.py +301 -0
  69. cfdbender/workspace/__init__.py +1 -0
  70. cfdbender/workspace/cli.py +99 -0
  71. cfdbender/workspace/planning.py +38 -0
  72. cfdbender-0.4.2.dist-info/METADATA +57 -0
  73. cfdbender-0.4.2.dist-info/RECORD +77 -0
  74. cfdbender-0.4.2.dist-info/WHEEL +5 -0
  75. cfdbender-0.4.2.dist-info/entry_points.txt +3 -0
  76. cfdbender-0.4.2.dist-info/licenses/LICENSE +21 -0
  77. cfdbender-0.4.2.dist-info/top_level.txt +1 -0
@@ -0,0 +1,735 @@
1
+ """Store proposals and execution evidence per point in a workspace's runs.json.
2
+
3
+ Registration is explicit and separate from planning. Records describe proposed
4
+ work, with status PLANNED; RUNNING claims a point and COMPLETED seals evidence.
5
+ Numerical classification is separate from the execution lifecycle.
6
+ An exclusive writer lock and atomic replacement protect the record document.
7
+
8
+ A rerun archives: the document is copied to archive/<stamp>/runs.json, the
9
+ point folder moves to archive/<stamp>/<its directory>, and the record leaves
10
+ the records list for the document's history list, which keeps every archived
11
+ record with its time and archive folder. Nothing is deleted.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import hashlib
17
+ import json
18
+ import math
19
+ import os
20
+ import re
21
+ import tempfile
22
+ from collections.abc import Mapping
23
+ from dataclasses import dataclass, field, replace
24
+ from datetime import UTC, datetime
25
+ from pathlib import Path
26
+ from types import MappingProxyType
27
+ from typing import Any, cast
28
+
29
+ from cfdbender.core.plan import (
30
+ POINT_EXTRAS,
31
+ PlanError,
32
+ Point,
33
+ RunPlan,
34
+ check_claims,
35
+ workspace_path,
36
+ )
37
+ from cfdbender.core.results import Classification
38
+ from cfdbender.core.settings import WorkspaceError
39
+
40
+
41
+ class RegistryError(WorkspaceError):
42
+ """A registry read or write would lose or misidentify point evidence."""
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class RunRecord:
47
+ """One point's immutable proposal, status and timezone-qualified creation time."""
48
+
49
+ point: Point
50
+ matrix: str
51
+ solver: str
52
+ status: str
53
+ created_at: str
54
+ started_at: str | None = None
55
+ completed_at: str | None = None
56
+ classification: Classification | None = None
57
+ outputs_sha256: Mapping[str, str] = field(default_factory=lambda: MappingProxyType({}))
58
+ error: str | None = None
59
+ submission: Mapping[str, object] | None = None
60
+
61
+ @property
62
+ def point_id(self) -> str:
63
+ """Return the point's stable identifier."""
64
+ return self.point.point_id
65
+
66
+
67
+ def _timestamp(value: str) -> str:
68
+ try:
69
+ stamp = datetime.fromisoformat(value)
70
+ except ValueError as error:
71
+ raise RegistryError("created_at must be an ISO 8601 timestamp with a timezone") from error
72
+ if stamp.utcoffset() is None:
73
+ raise RegistryError("created_at must include a timezone")
74
+ return stamp.astimezone(UTC).isoformat()
75
+
76
+
77
+ def _object(value: object) -> dict[str, object]:
78
+ if not isinstance(value, dict) or any(not isinstance(k, str) for k in value):
79
+ raise RegistryError("expected a JSON object")
80
+ return dict(value)
81
+
82
+
83
+ def _text(values: dict[str, object], key: str) -> str:
84
+ value = values.get(key)
85
+ if not isinstance(value, str) or not value:
86
+ raise RegistryError(f"{key} must be a non-empty string")
87
+ return value
88
+
89
+
90
+ def _strings(values: dict[str, object], key: str) -> tuple[str, ...]:
91
+ value = values.get(key)
92
+ if not isinstance(value, list) or not value:
93
+ raise RegistryError(f"{key} must be a non-empty list")
94
+ result = tuple(value)
95
+ if any(not isinstance(v, str) or not v for v in result):
96
+ raise RegistryError(f"{key} must contain non-empty strings")
97
+ return result
98
+
99
+
100
+ def _submission(raw: object, root: Path, directory: str, started: str) -> Mapping[str, object]:
101
+ values = _object(raw)
102
+ job_outputs = values.pop("job_outputs", None)
103
+ if set(values) != {
104
+ "descriptor",
105
+ "descriptor_sha256",
106
+ "config_path",
107
+ "config_sha256",
108
+ "profile",
109
+ "command",
110
+ "stdout_path",
111
+ "stderr_path",
112
+ "stdout",
113
+ "stderr",
114
+ "started_at",
115
+ "finished_at",
116
+ "return_code",
117
+ "timeout_s",
118
+ "timed_out",
119
+ }:
120
+ raise RegistryError("submission has missing or unknown fields")
121
+ for key in ("descriptor", "config_path", "stdout_path", "stderr_path"):
122
+ name = _text(values, key)
123
+ path = workspace_path(root, name)
124
+ if path.relative_to(root).as_posix() != name or path.parent != root / directory:
125
+ raise RegistryError(f"submission {key} must be in the point directory")
126
+ for key in ("descriptor_sha256", "config_sha256"):
127
+ if re.fullmatch("[0-9a-f]{64}", _text(values, key)) is None:
128
+ raise RegistryError(f"submission {key} must be a SHA-256 hex digest")
129
+ profile = _text(values, "profile")
130
+ if (
131
+ workspace_path(root, profile).relative_to(root).as_posix() != profile
132
+ or not profile.startswith("inputs/hpc/")
133
+ or not profile.endswith(".toml")
134
+ ):
135
+ raise RegistryError("submission profile must name inputs/hpc/<NAME>.toml")
136
+ command = values["command"]
137
+ if (
138
+ not isinstance(command, (list, tuple))
139
+ or not command
140
+ or any(not isinstance(part, str) or not part for part in command)
141
+ ):
142
+ raise RegistryError("submission command must be a non-empty argv list")
143
+ if any(not isinstance(values[key], str) for key in ("stdout", "stderr")):
144
+ raise RegistryError("submission stdout and stderr must be text")
145
+ timeout = values["timeout_s"]
146
+ if (
147
+ isinstance(timeout, bool)
148
+ or not isinstance(timeout, (int, float))
149
+ or not math.isfinite(timeout)
150
+ or timeout <= 0
151
+ ):
152
+ raise RegistryError("submission timeout_s must be finite and positive")
153
+ if type(values["return_code"]) is not int or type(values["timed_out"]) is not bool:
154
+ raise RegistryError("submission requires an integer return_code and boolean timed_out")
155
+ if job_outputs is not None:
156
+ if (
157
+ not isinstance(job_outputs, (list, tuple))
158
+ or not job_outputs
159
+ or any(not isinstance(name, str) or not name for name in job_outputs)
160
+ ):
161
+ raise RegistryError("submission job_outputs must be a non-empty list of paths")
162
+ values["job_outputs"] = tuple(job_outputs)
163
+ begin = _timestamp(_text(values, "started_at"))
164
+ finish = _timestamp(_text(values, "finished_at"))
165
+ if (
166
+ not datetime.fromisoformat(started)
167
+ <= datetime.fromisoformat(begin)
168
+ <= datetime.fromisoformat(finish)
169
+ ):
170
+ raise RegistryError("submission timestamps precede the run or each other")
171
+ return MappingProxyType(
172
+ {**values, "command": tuple(command), "started_at": begin, "finished_at": finish}
173
+ )
174
+
175
+
176
+ def _extras(row: Mapping[str, object]) -> dict[str, Any]:
177
+ """Read the optional row columns a point carries, refusing a wrong type."""
178
+ found: dict[str, Any] = {}
179
+ for key in POINT_EXTRAS:
180
+ if key not in row:
181
+ continue
182
+ value = row[key]
183
+ if key == "variables":
184
+ found[key] = MappingProxyType(dict(_object(value)))
185
+ continue
186
+ if key in {"geometry", "solver_build"}:
187
+ valid = value is None or (isinstance(value, str) and bool(value))
188
+ elif key == "ncpus":
189
+ valid = value is None or (type(value) is int and value > 0)
190
+ elif key == "hidden":
191
+ valid = isinstance(value, bool)
192
+ else:
193
+ valid = isinstance(value, str)
194
+ if not valid:
195
+ raise RegistryError(f"{key} has an invalid value in a run record")
196
+ found[key] = value
197
+ return found
198
+
199
+
200
+ def _decode(raw: object, root: Path) -> RunRecord:
201
+ row = _object(raw)
202
+ expected = {
203
+ "point_id",
204
+ "pol",
205
+ "setup_id",
206
+ "reference_id",
207
+ "post_id",
208
+ "condition",
209
+ "walltime",
210
+ "directory",
211
+ "actions",
212
+ "outputs",
213
+ "inputs_sha256",
214
+ "matrix",
215
+ "solver",
216
+ "status",
217
+ "created_at",
218
+ }
219
+ execution = {"started_at", "completed_at", "classification", "outputs_sha256", "error"}
220
+ status = _text(row, "status")
221
+ optional = {"submission"} if "submission" in row and status != "PLANNED" else set()
222
+ optional |= set(row) & set(POINT_EXTRAS)
223
+ if set(row) != expected | (execution if status != "PLANNED" else set()) | optional:
224
+ raise RegistryError("run record has missing or unknown fields")
225
+ condition: dict[str, float] = {}
226
+ for key, value in _object(row["condition"]).items():
227
+ if (
228
+ isinstance(value, bool)
229
+ or not isinstance(value, (int, float))
230
+ or not math.isfinite(value)
231
+ ):
232
+ raise RegistryError(f"condition {key} must be finite")
233
+ condition[key] = float(value)
234
+ digests: dict[str, str] = {}
235
+ for key, value in _object(row["inputs_sha256"]).items():
236
+ workspace_path(root, key)
237
+ if not isinstance(value, str) or re.fullmatch("[0-9a-f]{64}", value) is None:
238
+ raise RegistryError(f"inputs_sha256 for {key} must be a SHA-256 hex digest")
239
+ digests[key] = value
240
+ pol = _text(row, "pol")
241
+ point_id = _text(row, "point_id")
242
+ if not point_id.startswith(pol + "/DP-") or re.fullmatch("[A-Za-z0-9_-]+", pol) is None:
243
+ raise RegistryError("point_id must identify POL and its DP name")
244
+ matrix = _text(row, "matrix")
245
+ required_inputs = {
246
+ "init.toml",
247
+ matrix,
248
+ f"inputs/setups/{_text(row, 'setup_id')}.toml",
249
+ f"inputs/references/{_text(row, 'reference_id')}.toml",
250
+ f"inputs/pproc/{_text(row, 'post_id')}.toml",
251
+ }
252
+ if not required_inputs <= set(digests):
253
+ raise RegistryError("inputs_sha256 is missing a matrix, init.toml or s/r/p input")
254
+ directory = _text(row, "directory")
255
+ outputs = _strings(row, "outputs")
256
+ for name in (directory, *outputs):
257
+ # The record names the path, not what it points at: a staged mesh is a link to
258
+ # inputs/geometry, so only the containing folder is resolved, never the file itself.
259
+ parent, _, leaf = name.rpartition("/")
260
+ folder = workspace_path(root, parent) if parent else root
261
+ if (
262
+ not parent
263
+ or not leaf
264
+ or folder.relative_to(root).as_posix() != parent
265
+ or not name.startswith(("sims/", "post/"))
266
+ ):
267
+ raise RegistryError(f"{name}: record path must be canonical under sims/ or post/")
268
+ walltime = row["walltime"]
269
+ if walltime is not None and not isinstance(walltime, str):
270
+ raise RegistryError("walltime must be a string or null")
271
+ if status not in ("PLANNED", "RUNNING", "SUBMITTED", "COMPLETED"):
272
+ raise RegistryError(f"unsupported run status {status!r}")
273
+ point = Point(
274
+ point_id=point_id,
275
+ pol=pol,
276
+ setup_id=_text(row, "setup_id"),
277
+ reference_id=_text(row, "reference_id"),
278
+ post_id=_text(row, "post_id"),
279
+ condition=MappingProxyType(condition),
280
+ walltime=walltime,
281
+ directory=directory,
282
+ actions=_strings(row, "actions"),
283
+ outputs=outputs,
284
+ inputs_sha256=MappingProxyType(digests),
285
+ **_extras(row),
286
+ )
287
+ record = RunRecord(
288
+ point, matrix, _text(row, "solver"), status, _timestamp(_text(row, "created_at"))
289
+ )
290
+ if status == "PLANNED":
291
+ return record
292
+ started = _timestamp(_text(row, "started_at"))
293
+ if datetime.fromisoformat(started) < datetime.fromisoformat(record.created_at):
294
+ raise RegistryError("started_at precedes created_at")
295
+ if "submission" in row:
296
+ record = replace(
297
+ record, submission=_submission(row["submission"], root, directory, started)
298
+ )
299
+ if status == "SUBMITTED" and record.submission is None:
300
+ raise RegistryError("SUBMITTED requires submission evidence")
301
+ classification = row["classification"]
302
+ error = row["error"]
303
+ if error is not None and (not isinstance(error, str) or not error.strip()):
304
+ raise RegistryError("error must be a non-empty string or null")
305
+ output_digests: dict[str, str] = {}
306
+ for name, digest in _object(row["outputs_sha256"]).items():
307
+ if (
308
+ name not in outputs
309
+ or not isinstance(digest, str)
310
+ or not re.fullmatch("[0-9a-f]{64}", digest)
311
+ ):
312
+ raise RegistryError("outputs_sha256 must name declared outputs with SHA-256 digests")
313
+ output_digests[name] = digest
314
+ if status in ("RUNNING", "SUBMITTED"):
315
+ if classification is not None or row["completed_at"] is not None or output_digests or error:
316
+ raise RegistryError(f"{status} must not carry terminal evidence")
317
+ return replace(record, started_at=started)
318
+ if classification not in ("converged", "iteration_limit", "failed"):
319
+ raise RegistryError("COMPLETED requires a numerical classification")
320
+ completed = _timestamp(_text(row, "completed_at"))
321
+ if datetime.fromisoformat(completed) < datetime.fromisoformat(started):
322
+ raise RegistryError("completed_at precedes started_at")
323
+ # A cluster job writes only its job outputs; files only a local run writes
324
+ # (execution.json) may then be absent.
325
+ required = set(outputs)
326
+ if record.submission is not None and "job_outputs" in record.submission:
327
+ required = set(cast(tuple[str, ...], record.submission["job_outputs"]))
328
+ if not required <= set(outputs):
329
+ raise RegistryError("submission job_outputs must name declared outputs")
330
+ if classification != "failed" and (not required <= set(output_digests) or error):
331
+ raise RegistryError("successful classification requires every output and no error")
332
+ return replace(
333
+ record,
334
+ started_at=started,
335
+ completed_at=completed,
336
+ classification=classification,
337
+ outputs_sha256=MappingProxyType(output_digests),
338
+ error=error,
339
+ )
340
+
341
+
342
+ def _relink(old: Path, new: Path) -> None:
343
+ """Point relative symbolic links of a moved folder at their original targets."""
344
+ for link in new.rglob("*"):
345
+ if not link.is_symlink():
346
+ continue
347
+ written = os.readlink(link)
348
+ if os.path.isabs(written):
349
+ continue
350
+ original = os.path.normpath(old / link.relative_to(new).parent / written)
351
+ link.unlink()
352
+ link.symlink_to(os.path.relpath(original, link.parent))
353
+
354
+
355
+ def _encode(record: RunRecord) -> dict[str, object]:
356
+ point = record.point
357
+ row: dict[str, object] = {
358
+ "point_id": point.point_id,
359
+ "pol": point.pol,
360
+ "setup_id": point.setup_id,
361
+ "reference_id": point.reference_id,
362
+ "post_id": point.post_id,
363
+ "condition": dict(point.condition),
364
+ "walltime": point.walltime,
365
+ "directory": point.directory,
366
+ "actions": list(point.actions),
367
+ "outputs": list(point.outputs),
368
+ "inputs_sha256": dict(point.inputs_sha256),
369
+ "matrix": record.matrix,
370
+ "solver": record.solver,
371
+ "status": record.status,
372
+ "created_at": record.created_at,
373
+ }
374
+ # Optional columns are written only when a row states them, so a record of
375
+ # a matrix without them keeps its earlier bytes.
376
+ for key, default in POINT_EXTRAS.items():
377
+ value = getattr(point, key)
378
+ if key == "variables":
379
+ value = dict(value)
380
+ if value != default:
381
+ row[key] = value
382
+ if record.status != "PLANNED":
383
+ row.update(
384
+ started_at=record.started_at,
385
+ completed_at=record.completed_at,
386
+ classification=record.classification,
387
+ outputs_sha256=dict(record.outputs_sha256),
388
+ error=record.error,
389
+ )
390
+ if record.submission is not None:
391
+ row["submission"] = dict(record.submission)
392
+ return row
393
+
394
+
395
+ def _unique_pairs(pairs: list[tuple[str, object]]) -> dict[str, object]:
396
+ result: dict[str, object] = {}
397
+ for key, value in pairs:
398
+ if key in result:
399
+ raise RegistryError(f"duplicate JSON field {key!r}")
400
+ result[key] = value
401
+ return result
402
+
403
+
404
+ class RunRegistry:
405
+ """Read proposals and seal executed points, refusing drift and overlapping claims.
406
+
407
+ No solver is loaded. Writers fail immediately if runs.json.lock exists;
408
+ they never steal or recover a lock. An interrupted writer's lock requires
409
+ the operator to establish that writer has stopped before removing it.
410
+ """
411
+
412
+ def __init__(self, root: str | Path) -> None:
413
+ self.root = Path(root).resolve()
414
+ self.path = self.root / "runs.json"
415
+
416
+ def _history(self) -> list[object]:
417
+ if not self.path.exists():
418
+ return []
419
+ document = _object(json.loads(self.path.read_bytes(), object_pairs_hook=_unique_pairs))
420
+ history = document.get("history", [])
421
+ if not isinstance(history, list):
422
+ raise RegistryError("history must be a list")
423
+ return history
424
+
425
+ def _replace(self, records: tuple[RunRecord, ...], history: list[object] | None = None) -> None:
426
+ temporary: Path | None = None
427
+ try:
428
+ kept = self._history() if history is None else history
429
+ document: dict[str, object] = {
430
+ "schema_version": 1,
431
+ "records": [_encode(r) for r in records],
432
+ }
433
+ if kept:
434
+ document["history"] = kept
435
+ data = (
436
+ json.dumps(document, indent=2, sort_keys=True, allow_nan=False) + chr(10)
437
+ ).encode()
438
+ with tempfile.NamedTemporaryFile(
439
+ dir=self.root, prefix=".runs-", suffix=".tmp", delete=False
440
+ ) as stream:
441
+ temporary = Path(stream.name)
442
+ stream.write(data)
443
+ stream.flush()
444
+ os.fsync(stream.fileno())
445
+ os.replace(temporary, self.path)
446
+ temporary = None
447
+ finally:
448
+ if temporary is not None:
449
+ temporary.unlink(missing_ok=True)
450
+
451
+ def transition(
452
+ self,
453
+ point_id: str,
454
+ status: str,
455
+ *,
456
+ timestamp: str | None = None,
457
+ classification: Classification | None = None,
458
+ error: str | None = None,
459
+ submission: Mapping[str, object] | None = None,
460
+ ) -> RunRecord:
461
+ """Claim, submit or seal a point; never rewrite a finished one.
462
+
463
+ Parameters
464
+ ----------
465
+ point_id : str
466
+ Exact registered point identity.
467
+ status : str
468
+ RUNNING, SUBMITTED or COMPLETED. Only lifecycle transitions succeed.
469
+ timestamp : str, optional
470
+ Timezone-qualified time, defaulting to UTC now.
471
+ classification : Classification, optional
472
+ Required for COMPLETED; never inferred from process exit.
473
+ error : str, optional
474
+ Failure diagnosis, retained with any partial output digests.
475
+ submission : mapping, optional
476
+ Descriptor/config digests, argv, captured output paths/text and submit
477
+ process timestamps, code, timeout and timed_out evidence, and optional
478
+ job_outputs: the declared outputs the cluster job itself writes. Required
479
+ when moving from RUNNING to SUBMITTED; retained on completion.
480
+
481
+ Returns
482
+ -------
483
+ RunRecord
484
+ Atomically persisted record, preserving the proposal and input digests.
485
+
486
+ Raises
487
+ ------
488
+ RegistryError
489
+ Held lock, illegal transition, changed inputs, existing output or bad evidence.
490
+ """
491
+ stamp = _timestamp(timestamp if timestamp is not None else datetime.now(UTC).isoformat())
492
+ lock = self.root / "runs.json.lock"
493
+ try:
494
+ lease = lock.open("x", encoding="utf-8")
495
+ except FileExistsError as exc:
496
+ raise RegistryError(f"{lock}: registry is locked by another writer") from exc
497
+ try:
498
+ with lease:
499
+ records = self.read()
500
+ for index in range(len(records)):
501
+ previous = records[index]
502
+ if previous.point_id == point_id:
503
+ break
504
+ else:
505
+ raise RegistryError(f"point {point_id!r} has no registered record")
506
+ if (previous.status, status) not in {
507
+ ("PLANNED", "RUNNING"),
508
+ ("RUNNING", "COMPLETED"),
509
+ ("RUNNING", "SUBMITTED"),
510
+ ("SUBMITTED", "COMPLETED"),
511
+ }:
512
+ raise RegistryError(
513
+ f"point {point_id!r} already recorded {previous.status}; "
514
+ f"refusing transition to {status}"
515
+ )
516
+ if previous.submission is not None and submission is not None:
517
+ raise RegistryError("submission evidence is immutable")
518
+ if status == "RUNNING":
519
+ for name, digest in previous.point.inputs_sha256.items():
520
+ if (
521
+ hashlib.sha256(workspace_path(self.root, name).read_bytes()).hexdigest()
522
+ != digest
523
+ ):
524
+ raise RegistryError(f"input changed after planning: {name}; plan again")
525
+ for name in (previous.point.directory, *previous.point.outputs):
526
+ if workspace_path(self.root, name).exists():
527
+ raise RegistryError(f"{name}: existing output; refusing overwrite")
528
+ updated = replace(
529
+ previous,
530
+ status=status,
531
+ started_at=stamp,
532
+ classification=classification,
533
+ error=error,
534
+ )
535
+ elif status == "SUBMITTED":
536
+ updated = replace(previous, status=status, submission=submission)
537
+ else:
538
+ digests = {}
539
+ for name in previous.point.outputs:
540
+ path = workspace_path(self.root, name)
541
+ if path.is_file():
542
+ digests[name] = hashlib.sha256(path.read_bytes()).hexdigest()
543
+ updated = replace(
544
+ previous,
545
+ status=status,
546
+ completed_at=stamp,
547
+ classification=classification,
548
+ error=error,
549
+ outputs_sha256=MappingProxyType(digests),
550
+ submission=previous.submission if submission is None else submission,
551
+ )
552
+ updated = _decode(_encode(updated), self.root)
553
+ if submission is not None:
554
+ for name, key in (
555
+ ("descriptor", "descriptor_sha256"),
556
+ ("config_path", "config_sha256"),
557
+ ):
558
+ path = workspace_path(self.root, str(submission[name]))
559
+ if hashlib.sha256(path.read_bytes()).hexdigest() != submission[key]:
560
+ raise RegistryError(f"submission {name} digest differs from file")
561
+ self._replace((*records[:index], updated, *records[index + 1 :]))
562
+ return updated
563
+ except (OSError, ValueError, TypeError) as exc:
564
+ raise RegistryError(f"{self.path}: cannot transition point: {exc}") from exc
565
+ finally:
566
+ lock.unlink(missing_ok=True)
567
+
568
+ def history(self) -> tuple[Mapping[str, object], ...]:
569
+ """Return archived records, oldest first, each with archived_at and archive.
570
+
571
+ Returns
572
+ -------
573
+ tuple of mapping
574
+ Entries ``{"archived_at", "archive", "record"}``; ``record`` is the
575
+ record as it was in runs.json when it was archived.
576
+ """
577
+ self.read()
578
+ return tuple(MappingProxyType(_object(entry)) for entry in self._history())
579
+
580
+ def archive(self, point_ids: tuple[str, ...], *, stamp: str | None = None) -> Path:
581
+ """Move recorded points and their folders to a new archive/<stamp>/ folder.
582
+
583
+ Parameters
584
+ ----------
585
+ point_ids : tuple of str
586
+ Recorded points to archive; each may then be registered again.
587
+ stamp : str, optional
588
+ Folder name; defaults to the UTC time as YYYYMMDDTHHMMSSZ, with a
589
+ numeric suffix when that folder exists.
590
+
591
+ Returns
592
+ -------
593
+ Path
594
+ The archive folder, holding runs.json as it was and each point folder
595
+ under its workspace-relative directory.
596
+
597
+ Raises
598
+ ------
599
+ RegistryError
600
+ A held lock, an unknown point or a move that cannot be made.
601
+ """
602
+ now = datetime.now(UTC)
603
+ name = stamp or now.strftime("%Y%m%dT%H%M%SZ")
604
+ target = self.root / "archive" / name
605
+ suffix = 1
606
+ while target.exists():
607
+ target = self.root / "archive" / f"{name}-{suffix}"
608
+ suffix += 1
609
+ lock = self.root / "runs.json.lock"
610
+ try:
611
+ lease = lock.open("x", encoding="utf-8")
612
+ except FileExistsError as error:
613
+ raise RegistryError(f"{lock}: registry is locked by another writer") from error
614
+ try:
615
+ with lease:
616
+ records = self.read()
617
+ chosen = {r.point_id: r for r in records if r.point_id in point_ids}
618
+ if missing := sorted(set(point_ids) - set(chosen)):
619
+ raise RegistryError(f"no recorded point {missing[0]!r} to archive")
620
+ target.mkdir(parents=True)
621
+ (target / "runs.json").write_bytes(self.path.read_bytes())
622
+ history = self._history()
623
+ relative = target.relative_to(self.root).as_posix()
624
+ for record in chosen.values():
625
+ folder = workspace_path(self.root, record.point.directory)
626
+ if folder.exists():
627
+ moved = target / record.point.directory
628
+ moved.parent.mkdir(parents=True, exist_ok=True)
629
+ os.replace(folder, moved)
630
+ _relink(folder, moved)
631
+ history.append(
632
+ {
633
+ "archived_at": now.isoformat(),
634
+ "archive": relative,
635
+ "record": _encode(record),
636
+ }
637
+ )
638
+ kept = tuple(r for r in records if r.point_id not in chosen)
639
+ self._replace(kept, history)
640
+ return target
641
+ except (OSError, ValueError, TypeError) as error:
642
+ raise RegistryError(f"{self.path}: cannot archive points: {error}") from error
643
+ finally:
644
+ lock.unlink(missing_ok=True)
645
+
646
+ def read(self) -> tuple[RunRecord, ...]:
647
+ """Read validated records, or return an empty tuple when runs.json is absent.
648
+
649
+ Returns
650
+ -------
651
+ tuple of RunRecord
652
+ Records in registration order; input bytes are not re-read here.
653
+
654
+ Raises
655
+ ------
656
+ RegistryError
657
+ An unreadable, corrupt or unsupported record document, named in the error.
658
+ """
659
+ try:
660
+ if self.path.is_symlink():
661
+ raise RegistryError("registry must not be a symlink")
662
+ if not self.path.exists():
663
+ return ()
664
+ document = _object(json.loads(self.path.read_bytes(), object_pairs_hook=_unique_pairs))
665
+ if (
666
+ set(document) - {"history"} != {"schema_version", "records"}
667
+ or not isinstance(document.get("history", []), list)
668
+ or type(document["schema_version"]) is not int
669
+ or document["schema_version"] != 1
670
+ or not isinstance(document["records"], list)
671
+ ):
672
+ raise RegistryError("expected schema_version = 1 and records list")
673
+ records = tuple(_decode(raw, self.root) for raw in document["records"])
674
+ check_claims(tuple(r.point for r in records))
675
+ return records
676
+ except (OSError, ValueError, TypeError, OverflowError) as error:
677
+ raise RegistryError(f"{self.path}: cannot read run registry: {error}") from error
678
+
679
+ def record(self, plan: RunPlan, *, created_at: str | None = None) -> tuple[RunRecord, ...]:
680
+ """Append a plan atomically after checking input bytes and all path claims.
681
+
682
+ Parameters
683
+ ----------
684
+ plan : RunPlan
685
+ Validated plan for this registry's workspace.
686
+ created_at : str, optional
687
+ ISO 8601 timestamp with timezone. Defaults to UTC now; pass an explicit
688
+ timestamp for deterministic output.
689
+
690
+ Returns
691
+ -------
692
+ tuple of RunRecord
693
+ Newly appended point records with status PLANNED.
694
+
695
+ Raises
696
+ ------
697
+ RegistryError
698
+ A held writer lock, changed input, duplicate point, collision or bad record.
699
+ """
700
+ if plan.root != self.root:
701
+ raise RegistryError("plan and registry must belong to the same workspace")
702
+ stamp = _timestamp(created_at if created_at is not None else datetime.now(UTC).isoformat())
703
+ lock = self.root / "runs.json.lock"
704
+ try:
705
+ lease = lock.open("x", encoding="utf-8")
706
+ except FileExistsError as error:
707
+ raise RegistryError(f"{lock}: registry is locked by another writer") from error
708
+ try:
709
+ with lease:
710
+ lease.write(str(os.getpid()))
711
+ lease.flush()
712
+ previous = self.read()
713
+ check_claims(tuple(r.point for r in previous) + plan.points)
714
+ records = tuple(
715
+ RunRecord(p, plan.matrix, plan.solver, "PLANNED", stamp) for p in plan.points
716
+ )
717
+ # Validate the same shape that a subsequent read accepts before writing.
718
+ records = tuple(_decode(_encode(r), self.root) for r in records)
719
+ for record in records:
720
+ for name, expected in record.point.inputs_sha256.items():
721
+ path = workspace_path(self.root, name)
722
+ try:
723
+ actual = hashlib.sha256(path.read_bytes()).hexdigest()
724
+ except OSError as error:
725
+ raise RegistryError(
726
+ f"input changed or missing: {name}: {error}"
727
+ ) from error
728
+ if actual != expected:
729
+ raise RegistryError(f"input changed after planning: {name}; plan again")
730
+ self._replace((*previous, *records))
731
+ return records
732
+ except (OSError, PlanError, ValueError, TypeError) as error:
733
+ raise RegistryError(f"{self.path}: cannot register plan: {error}") from error
734
+ finally:
735
+ lock.unlink(missing_ok=True)