wexample-wex-addon-process 2.0.0__tar.gz → 3.0.0__tar.gz

{wexample_wex_addon_process-2.0.0 → wexample_wex_addon_process-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-wex-addon-process
-Version: 2.0.0
+Version: 3.0.0
 Summary: Executes process runs defined on disk—either directly or by consuming them from a queue as a worker—against filestate selections
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -9,8 +9,8 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Requires-Dist: wexample-file>=9.2.0
-Requires-Dist: wexample-queue>=1.1.0
-Requires-Dist: wexample-wex-addon-app>=31.0.0
+Requires-Dist: wexample-queue>=2.0.0
+Requires-Dist: wexample-wex-addon-app>=32.0.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -18,7 +18,7 @@ Description-Content-Type: text/markdown
 
 # wex-addon-process
 
-Version: 2.0.0
+Version: 3.0.0
 
 `wexample-wex-addon-process` runs the treatments a board declares. A *process* says what to run and on which selection of files; a *run* is one execution of it, asked for by writing a record and picked up by a worker.
 
@@ -41,7 +41,7 @@ wex process::worker/start
 ```
 
 Blocks, consuming the `process_run` queue, and rings back on `process_run_event`
-every time a run moves — on each state change, and at most once a second while
+every time a run moves — on each state change, and at most four times a second while
 it advances. This is the process a worker container runs, and there may be as
 many as the parallelism asked for.
 
@@ -65,17 +65,27 @@ filestate:managed_blocks            filestate:class      filestate:on_bad_format
 Nothing is written per treatment: an option added to filestate is a type
 available here the same day, under the very name filestate gives it.
 
-The process's `options` block is the configuration handed to each file, and has
+The process's `options` object is the configuration handed to each file, and has
 to carry the option the type is named after:
 
-```yaml
-# a process of type filestate:mode
-mode: '600'
-dry_run: true
+```json
+// the options of a process of type filestate:mode
+{"mode": "600", "action": "dry_run"}
 ```
 
-`dry_run` is read by the family and handed to nobody: it runs the pass without
-applying it, so what a treatment *would* do is readable before it does it.
+`action` is read by the family and handed to nobody. It picks which of
+filestate's three verbs is asked, the same three the command line offers on an
+app's declared state:
+
+- `check`, the default, says what is wrong with each selected file and changes
+  nothing. Its `data` counts the files `checked` and `failing`, and lists under
+  `files` only those at fault, each with its `code`, `message`, `parameters` and
+  `remedy`, the name of the operation that would fix it or null when nothing can.
+- `dry_run` lists the operations one pass would apply.
+- `fix` applies them, then lists what is still wrong, the way `check` does.
+
+A rule that only observes, such as `max_lines`, is a type like the others: it has
+no remedy, so a `fix` changes nothing and reports it again.
 
 ## Writing a type
 
@@ -87,12 +97,17 @@ class ReviewProcessType(AbstractProcessType):
     label = "Review"
 
     def run(self, context: ProcessContext) -> dict[str, Any]:
-        for path in context.files:
-            context.advance()
+        for path in context.each():
+            ...
 
         return {"files": len(context.files)}
 ```
 
+`context.each()` hands the files over one at a time and keeps the run up to
+date: the file being worked on is the run's `current`, and it is counted once
+the loop comes back for the next one. A file whose treatment raises is never
+counted and stays `current`, so a failed run says where it failed.
+
 What `run()` returns goes into the run's `data`. Raising is how a type says it
 could not go on — the failure is written down for it, so nothing in a type has
 to know what a failed run looks like.
@@ -108,6 +123,9 @@ exist.
 - [The types on offer](#the-types-on-offer)
 - [Writing a type](#writing-a-type)
 - [Installation](#installation)
+- [What a run may ask for itself](#what-a-run-may-ask-for-itself)
+- [Runs that last a night](#runs-that-last-a-night)
+- [An item that fails, a run that is cancelled](#an-item-that-fails-a-run-that-is-cancelled)
 - [Tests](#tests)
 - [Architecture](#architecture)
 - [Integration in the Suite](#integration-in-the-suite)
@@ -128,28 +146,35 @@ pip install wexample-wex-addon-process
 
 Requires Python >=3.10.
 
-A process and a selection are records, so a treatment can be declared without a board:
+A process and a selection are records, so a treatment can be declared without a board.
+Records are JSON, written and read by programs on both sides:
 
-```yaml
-# .wex/data/selection/<uuid>.yml
-title: Markdowns
-patterns: "*.md\n!.wex/**"
+```json
+// .wex/data/selection/<uuid>.json
+{
+  "title": "Markdowns",
+  "patterns": "*.md\n!.wex/**"
+}
 ```
 
-```yaml
-# .wex/data/process/<uuid>.yml
-title: What the Markdowns take
-type: 'filestate:report'
-selection_id: <the selection's uuid>
-options: ''
+```json
+// .wex/data/process/<uuid>.json
+{
+  "title": "What the Markdowns take",
+  "type": "filestate:report",
+  "selection_id": "<the selection's uuid>",
+  "options": {}
+}
 ```
 
 Asking for a run is writing a third record:
 
-```yaml
-# .wex/data/process_run/<uuid>.yml
-process_id: <the process's uuid>
-state: pending
+```json
+// .wex/data/process_run/<uuid>.json
+{
+  "process_id": "<the process's uuid>",
+  "state": "pending"
+}
 ```
 
 Then:
@@ -160,18 +185,76 @@ wex process::run/execute --run <the run's uuid>
 
 The same file is read back afterwards, holding what happened:
 
-```yaml
-process_id: ...
-state: complete
-items_total: 3
-items_done: 3
-data: |
-  files: 3
-  bytes: 16
-  by_extension:
-    .md: 3
+```json
+{
+  "process_id": "...",
+  "state": "complete",
+  "items_total": 3,
+  "items_done": 3,
+  "data": {
+    "files": 3,
+    "bytes": 16,
+    "by_extension": {".md": 3}
+  }
+}
+```
+
+## What a run may ask for itself
+
+A run record may carry three keys of its own, written when it is created:
+
+- `action` — `check`, `dry_run` or `fix`, in place of the process's own, for this run.
+- `items` — paths relative to the app, taken in place of the selection. A path that is
+  gone is listed under `items_missing` rather than failing the run; a path outside the
+  app fails it.
+- `commit: true` — once the run completes, commit what it wrote and nothing else. The
+  result replaces the key: `{"sha": ..., "files": [...]}`, `{"sha": null, "files": []}`
+  when nothing changed, or `{"error": ..., "files": [...]}` when git refused — the
+  changes stay either way.
+
+```json
+{"process_id": "...", "state": "pending", "action": "fix", "items": ["docs/a.md"], "commit": true}
 ```
 
+What a run wrote is what its type declared through `context.touch(path)`: the operations
+of a filestate fix, the items an agent changed and their engrams.
+
+## Runs that last a night
+
+A worker takes one message at a time from the queue and acknowledges it at once: the
+run's record, not the broker, says what became of it. The run is worked on in a thread
+of its own while the worker keeps the broker connection alive, so a run of several
+hours needs no RabbitMQ setting — neither `consumer_timeout` nor the heartbeat can cut
+it. A connection lost meanwhile is opened again once the run ends; the board is told of
+the run's moves on a best-effort basis and reads the record again anyway.
+
+A running run writes `date_alive` into its record every minute. One still `running`
+whose last sign of life is too old was interrupted — worker killed, machine stopped —
+and is said `failed`, never run again: by the next run of the same app, and by any
+worker that served that app, within a minute of finding its queue empty.
+
+| Variable | Default | What it sets |
+|---|---|---|
+| `PROCESS_RUN_STALE_AFTER` | `600` | Seconds without a sign of life after which a running run is taken for dead |
+| `RABBITMQ_HEARTBEAT` | the broker's | Seconds between two heartbeats on the worker's connection |
+
+There is no limit on how long a run may take.
+
+## An item that fails, a run that is cancelled
+
+A type that cannot deal with one item says so with `context.fail(path, reason)` and
+moves on: the run still completes, and lists what it could not do under its data.
+
+```json
+"data": {"errors": [{"path": "docs/a.pdf", "reason": "docling timed out"}]}
+```
+
+To stop a run, write `"cancel": true` into its record. The runner checks it before every
+item (`context.each()`, `context.advance()`, or `context.check_cancel()` in a type's own
+loop) and ends the run `cancelled`, with `items_done` where it got to and the errors and
+artifacts collected so far. A run cancelled before it was taken ends `cancelled` without
+starting.
+
 ## Tests
 
 This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
@@ -229,7 +312,7 @@ The addon is one runner, a few types, and two ways to reach it.
 
 src/wexample_wex_addon_process/runner/process_runner.py is where a run is taken from `pending` to `complete` or to `failed`. It reads the run, the process it names, the selection that process names, resolves the type, walks the files, and writes back at every state change.
 
-Three decisions are worth reading. A run in any state but `pending` is left where it is, because a queue redelivers and a run is done once. The record is written on every file dealt with, being local and being the truth, while the ring is throttled to once a second — ten thousand files must not be ten thousand messages saying the same thing. And the type never sees the run: it is handed a src/wexample_wex_addon_process/process_type/process_context.py holding the files, the options and a way to say how far it has got, so what a run is *in* is decided in one place.
+Three decisions are worth reading. A run in any state but `pending` is left where it is, because a queue redelivers and a run is done once. Progress — the files done and the file being worked on, `current` — is kept in memory and written down at most four times a second, each write followed by a ring: the other end reads the record when rung, and ten thousand files must not be ten thousand rewrites saying the same thing. A state change is never held back, and a failed run keeps `current` on the file it failed on. And the type never sees the run: it is handed a src/wexample_wex_addon_process/process_type/process_context.py holding the files, the options and a way to say how far it has got, so what a run is *in* is decided in one place.
 
 ### Reading a selection
 
@@ -247,7 +330,7 @@ A type's name carries its family: `filestate:mode`, `agent:review`. The prefix i
 
 src/wexample_wex_addon_process/process_type/family/file_state_process_type_family.py declares none of its types by hand. It walks filestate's `DefaultOptionsProvider` and keeps the options that override `create_required_operation` — the precise line between a treatment and a piece of structure, asked of the option itself rather than listed here. `mode` is a treatment, `children` is not. Thirteen types come out of it, and an option added to filestate is a fourteenth the same day.
 
-Each of those is a src/wexample_wex_addon_process/process_type/filestate/file_state_option_process_type.py, which holds no logic either: the process's `options` become the configuration asked of every selected file, and filestate turns the difference with the disk into operations that can be described, applied and undone. `dry_run` in the options runs the pass without applying it.
+Each of those is a src/wexample_wex_addon_process/process_type/filestate/file_state_option_process_type.py, which holds no logic either: the process's `options` become the configuration asked of every selected file, and filestate turns the difference with the disk into operations that can be described, applied and undone. `action` in the options picks the verb: `check` returns verdicts per file, `dry_run` the operations a pass would apply, `fix` applies them.
 
 src/wexample_wex_addon_process/process_type/filestate/file_state_report_process_type.py is in that family and yet emits no operation, on filestate's own rule: a scope names something observable on disk, and a report changes nothing observable. An operation with no scope would be an operation nothing could ever run.
 
@@ -274,8 +357,8 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 ## Dependencies
 
 - wexample-file: >=9.2.0
-- wexample-queue: >=1.1.0
-- wexample-wex-addon-app: >=31.0.0
+- wexample-queue: >=2.0.0
+- wexample-wex-addon-app: >=32.0.0
 
 ## Versioning & Compatibility Policy
 

{wexample_wex_addon_process-2.0.0 → wexample_wex_addon_process-3.0.0}/README.md

@@ -1,6 +1,6 @@
 # wex-addon-process
 
-Version: 2.0.0
+Version: 3.0.0
 
 `wexample-wex-addon-process` runs the treatments a board declares. A *process* says what to run and on which selection of files; a *run* is one execution of it, asked for by writing a record and picked up by a worker.
 
@@ -23,7 +23,7 @@ wex process::worker/start
 ```
 
 Blocks, consuming the `process_run` queue, and rings back on `process_run_event`
-every time a run moves — on each state change, and at most once a second while
+every time a run moves — on each state change, and at most four times a second while
 it advances. This is the process a worker container runs, and there may be as
 many as the parallelism asked for.
 
@@ -47,17 +47,27 @@ filestate:managed_blocks            filestate:class      filestate:on_bad_format
 Nothing is written per treatment: an option added to filestate is a type
 available here the same day, under the very name filestate gives it.
 
-The process's `options` block is the configuration handed to each file, and has
+The process's `options` object is the configuration handed to each file, and has
 to carry the option the type is named after:
 
-```yaml
-# a process of type filestate:mode
-mode: '600'
-dry_run: true
+```json
+// the options of a process of type filestate:mode
+{"mode": "600", "action": "dry_run"}
 ```
 
-`dry_run` is read by the family and handed to nobody: it runs the pass without
-applying it, so what a treatment *would* do is readable before it does it.
+`action` is read by the family and handed to nobody. It picks which of
+filestate's three verbs is asked, the same three the command line offers on an
+app's declared state:
+
+- `check`, the default, says what is wrong with each selected file and changes
+  nothing. Its `data` counts the files `checked` and `failing`, and lists under
+  `files` only those at fault, each with its `code`, `message`, `parameters` and
+  `remedy`, the name of the operation that would fix it or null when nothing can.
+- `dry_run` lists the operations one pass would apply.
+- `fix` applies them, then lists what is still wrong, the way `check` does.
+
+A rule that only observes, such as `max_lines`, is a type like the others: it has
+no remedy, so a `fix` changes nothing and reports it again.
 
 ## Writing a type
 
@@ -69,12 +79,17 @@ class ReviewProcessType(AbstractProcessType):
     label = "Review"
 
     def run(self, context: ProcessContext) -> dict[str, Any]:
-        for path in context.files:
-            context.advance()
+        for path in context.each():
+            ...
 
         return {"files": len(context.files)}
 ```
 
+`context.each()` hands the files over one at a time and keeps the run up to
+date: the file being worked on is the run's `current`, and it is counted once
+the loop comes back for the next one. A file whose treatment raises is never
+counted and stays `current`, so a failed run says where it failed.
+
 What `run()` returns goes into the run's `data`. Raising is how a type says it
 could not go on — the failure is written down for it, so nothing in a type has
 to know what a failed run looks like.
@@ -90,6 +105,9 @@ exist.
 - [The types on offer](#the-types-on-offer)
 - [Writing a type](#writing-a-type)
 - [Installation](#installation)
+- [What a run may ask for itself](#what-a-run-may-ask-for-itself)
+- [Runs that last a night](#runs-that-last-a-night)
+- [An item that fails, a run that is cancelled](#an-item-that-fails-a-run-that-is-cancelled)
 - [Tests](#tests)
 - [Architecture](#architecture)
 - [Integration in the Suite](#integration-in-the-suite)
@@ -110,28 +128,35 @@ pip install wexample-wex-addon-process
 
 Requires Python >=3.10.
 
-A process and a selection are records, so a treatment can be declared without a board:
+A process and a selection are records, so a treatment can be declared without a board.
+Records are JSON, written and read by programs on both sides:
 
-```yaml
-# .wex/data/selection/<uuid>.yml
-title: Markdowns
-patterns: "*.md\n!.wex/**"
+```json
+// .wex/data/selection/<uuid>.json
+{
+  "title": "Markdowns",
+  "patterns": "*.md\n!.wex/**"
+}
 ```
 
-```yaml
-# .wex/data/process/<uuid>.yml
-title: What the Markdowns take
-type: 'filestate:report'
-selection_id: <the selection's uuid>
-options: ''
+```json
+// .wex/data/process/<uuid>.json
+{
+  "title": "What the Markdowns take",
+  "type": "filestate:report",
+  "selection_id": "<the selection's uuid>",
+  "options": {}
+}
 ```
 
 Asking for a run is writing a third record:
 
-```yaml
-# .wex/data/process_run/<uuid>.yml
-process_id: <the process's uuid>
-state: pending
+```json
+// .wex/data/process_run/<uuid>.json
+{
+  "process_id": "<the process's uuid>",
+  "state": "pending"
+}
 ```
 
 Then:
@@ -142,18 +167,76 @@ wex process::run/execute --run <the run's uuid>
 
 The same file is read back afterwards, holding what happened:
 
-```yaml
-process_id: ...
-state: complete
-items_total: 3
-items_done: 3
-data: |
-  files: 3
-  bytes: 16
-  by_extension:
-    .md: 3
+```json
+{
+  "process_id": "...",
+  "state": "complete",
+  "items_total": 3,
+  "items_done": 3,
+  "data": {
+    "files": 3,
+    "bytes": 16,
+    "by_extension": {".md": 3}
+  }
+}
+```
+
+## What a run may ask for itself
+
+A run record may carry three keys of its own, written when it is created:
+
+- `action` — `check`, `dry_run` or `fix`, in place of the process's own, for this run.
+- `items` — paths relative to the app, taken in place of the selection. A path that is
+  gone is listed under `items_missing` rather than failing the run; a path outside the
+  app fails it.
+- `commit: true` — once the run completes, commit what it wrote and nothing else. The
+  result replaces the key: `{"sha": ..., "files": [...]}`, `{"sha": null, "files": []}`
+  when nothing changed, or `{"error": ..., "files": [...]}` when git refused — the
+  changes stay either way.
+
+```json
+{"process_id": "...", "state": "pending", "action": "fix", "items": ["docs/a.md"], "commit": true}
 ```
 
+What a run wrote is what its type declared through `context.touch(path)`: the operations
+of a filestate fix, the items an agent changed and their engrams.
+
+## Runs that last a night
+
+A worker takes one message at a time from the queue and acknowledges it at once: the
+run's record, not the broker, says what became of it. The run is worked on in a thread
+of its own while the worker keeps the broker connection alive, so a run of several
+hours needs no RabbitMQ setting — neither `consumer_timeout` nor the heartbeat can cut
+it. A connection lost meanwhile is opened again once the run ends; the board is told of
+the run's moves on a best-effort basis and reads the record again anyway.
+
+A running run writes `date_alive` into its record every minute. One still `running`
+whose last sign of life is too old was interrupted — worker killed, machine stopped —
+and is said `failed`, never run again: by the next run of the same app, and by any
+worker that served that app, within a minute of finding its queue empty.
+
+| Variable | Default | What it sets |
+|---|---|---|
+| `PROCESS_RUN_STALE_AFTER` | `600` | Seconds without a sign of life after which a running run is taken for dead |
+| `RABBITMQ_HEARTBEAT` | the broker's | Seconds between two heartbeats on the worker's connection |
+
+There is no limit on how long a run may take.
+
+## An item that fails, a run that is cancelled
+
+A type that cannot deal with one item says so with `context.fail(path, reason)` and
+moves on: the run still completes, and lists what it could not do under its data.
+
+```json
+"data": {"errors": [{"path": "docs/a.pdf", "reason": "docling timed out"}]}
+```
+
+To stop a run, write `"cancel": true` into its record. The runner checks it before every
+item (`context.each()`, `context.advance()`, or `context.check_cancel()` in a type's own
+loop) and ends the run `cancelled`, with `items_done` where it got to and the errors and
+artifacts collected so far. A run cancelled before it was taken ends `cancelled` without
+starting.
+
 ## Tests
 
 This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
@@ -211,7 +294,7 @@ The addon is one runner, a few types, and two ways to reach it.
 
 src/wexample_wex_addon_process/runner/process_runner.py is where a run is taken from `pending` to `complete` or to `failed`. It reads the run, the process it names, the selection that process names, resolves the type, walks the files, and writes back at every state change.
 
-Three decisions are worth reading. A run in any state but `pending` is left where it is, because a queue redelivers and a run is done once. The record is written on every file dealt with, being local and being the truth, while the ring is throttled to once a second — ten thousand files must not be ten thousand messages saying the same thing. And the type never sees the run: it is handed a src/wexample_wex_addon_process/process_type/process_context.py holding the files, the options and a way to say how far it has got, so what a run is *in* is decided in one place.
+Three decisions are worth reading. A run in any state but `pending` is left where it is, because a queue redelivers and a run is done once. Progress — the files done and the file being worked on, `current` — is kept in memory and written down at most four times a second, each write followed by a ring: the other end reads the record when rung, and ten thousand files must not be ten thousand rewrites saying the same thing. A state change is never held back, and a failed run keeps `current` on the file it failed on. And the type never sees the run: it is handed a src/wexample_wex_addon_process/process_type/process_context.py holding the files, the options and a way to say how far it has got, so what a run is *in* is decided in one place.
 
 ### Reading a selection
 
@@ -229,7 +312,7 @@ A type's name carries its family: `filestate:mode`, `agent:review`. The prefix i
 
 src/wexample_wex_addon_process/process_type/family/file_state_process_type_family.py declares none of its types by hand. It walks filestate's `DefaultOptionsProvider` and keeps the options that override `create_required_operation` — the precise line between a treatment and a piece of structure, asked of the option itself rather than listed here. `mode` is a treatment, `children` is not. Thirteen types come out of it, and an option added to filestate is a fourteenth the same day.
 
-Each of those is a src/wexample_wex_addon_process/process_type/filestate/file_state_option_process_type.py, which holds no logic either: the process's `options` become the configuration asked of every selected file, and filestate turns the difference with the disk into operations that can be described, applied and undone. `dry_run` in the options runs the pass without applying it.
+Each of those is a src/wexample_wex_addon_process/process_type/filestate/file_state_option_process_type.py, which holds no logic either: the process's `options` become the configuration asked of every selected file, and filestate turns the difference with the disk into operations that can be described, applied and undone. `action` in the options picks the verb: `check` returns verdicts per file, `dry_run` the operations a pass would apply, `fix` applies them.
 
 src/wexample_wex_addon_process/process_type/filestate/file_state_report_process_type.py is in that family and yet emits no operation, on filestate's own rule: a scope names something observable on disk, and a report changes nothing observable. An operation with no scope would be an operation nothing could ever run.
 
@@ -256,8 +339,8 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 ## Dependencies
 
 - wexample-file: >=9.2.0
-- wexample-queue: >=1.1.0
-- wexample-wex-addon-app: >=31.0.0
+- wexample-queue: >=2.0.0
+- wexample-wex-addon-app: >=32.0.0
 
 ## Versioning & Compatibility Policy
 

{wexample_wex_addon_process-2.0.0 → wexample_wex_addon_process-3.0.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-wex-addon-process"
-version = "2.0.0"
+version = "3.0.0"
 description = "Executes process runs defined on disk—either directly or by consuming them from a queue as a worker—against filestate selections"
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -19,8 +19,8 @@ classifiers = [
 ]
 dependencies = [
     "wexample-file>=9.2.0",
-    "wexample-queue>=1.1.0",
-    "wexample-wex-addon-app>=31.0.0",
+    "wexample-queue>=2.0.0",
+    "wexample-wex-addon-app>=32.0.0",
 ]
 
 [project.readme]

{wexample_wex_addon_process-2.0.0 → wexample_wex_addon_process-3.0.0}/src/wexample_wex_addon_process/commands/run/execute.py

@@ -42,10 +42,15 @@ def process__run__execute(
         ProcessTypeRegistry,
     )
     from wexample_wex_addon_process.runner.process_runner import ProcessRunner
+    from wexample_wex_addon_process.selection.selection_registry import (
+        SelectionRegistry,
+    )
 
     runner = ProcessRunner(
         io=context.io,
         registry=ProcessTypeRegistry.from_kernel(context.kernel),
+        selections=SelectionRegistry.from_kernel(context.kernel),
+        kernel=context.kernel,
     )
 
     record = runner.execute(

wexample_wex_addon_process-3.0.0/src/wexample_wex_addon_process/const/filestate.py

@@ -0,0 +1,21 @@
+"""The options a filestate process type reads for itself, before handing the rest
+to each selected file.
+
+The three actions are filestate's three verbs, and the same three the command
+line offers on an app's declared state: `app::state/check`, `app::state/rectify
+--dry-run`, `app::state/rectify`. A process is that, on a selection instead of a
+whole declared tree.
+
+The key must not be the name of a filestate option, since every other key of the
+block is handed to each file as its configuration: `mode` already means chmod.
+"""
+
+from __future__ import annotations
+
+# filestate: python-constant-sort
+ACTION_CHECK: str = "check"
+ACTION_DRY_RUN: str = "dry_run"
+ACTION_FIX: str = "fix"
+ACTIONS: tuple[str, ...] = (ACTION_CHECK, ACTION_DRY_RUN, ACTION_FIX)
+
+OPTION_KEY_ACTION: str = "action"

wexample_wex_addon_process-3.0.0/src/wexample_wex_addon_process/const/process.py

@@ -0,0 +1,69 @@
+"""What a process, a selection and a run are called on disk.
+
+Spelled once here because wex is not the only reader: the board writes these very
+keys into the same files, so a name changed on one side has to be changed on the
+other or the two stop understanding each other.
+"""
+
+from __future__ import annotations
+
+# filestate: python-constant-sort
+ARTIFACT_TYPE_FILE: str = "file"
+
+# Under a run's data: the files it produced to be handed back, each
+# {type, path, label}.
+DATA_KEY_ARTIFACTS: str = "artifacts"
+
+# Under a run's data: the items a type could not deal with, each {path, reason}.
+# The run still completes — one bad file does not sink the batch.
+DATA_KEY_ERRORS: str = "errors"
+
+DEFAULT_COMMIT_AUTHOR: str = "wex <wex@localhost>"
+"""Who commits a run's work when neither the run nor git names anyone."""
+
+ENV_PROCESS_RUN_STALE_AFTER: str = "PROCESS_RUN_STALE_AFTER"
+"""Seconds without a sign of life after which a running run is taken for dead."""
+
+KIND_PROCESS: str = "process"
+KIND_PROCESS_RUN: str = "process_run"
+KIND_SELECTION: str = "selection"
+
+PROCESS_KEY_OPTIONS: str = "options"
+PROCESS_KEY_SELECTION_ID: str = "selection_id"
+PROCESS_KEY_TITLE: str = "title"
+PROCESS_KEY_TYPE: str = "type"
+
+RUN_KEY_ACTION: str = "action"
+RUN_KEY_AUTHOR: str = "author"
+RUN_KEY_CANCEL: str = "cancel"
+"""Written `true` by whoever wants the run stopped; read between two items."""
+RUN_KEY_COMMIT: str = "commit"
+RUN_KEY_CURRENT: str = "current"
+RUN_KEY_DATA: str = "data"
+RUN_KEY_DATE_ALIVE: str = "date_alive"
+RUN_KEY_DATE_ENDED: str = "date_ended"
+RUN_KEY_DATE_STARTED: str = "date_started"
+RUN_KEY_ITEMS: str = "items"
+RUN_KEY_ITEMS_DONE: str = "items_done"
+RUN_KEY_ITEMS_MISSING: str = "items_missing"
+RUN_KEY_ITEMS_TOTAL: str = "items_total"
+RUN_KEY_PROCESS_ID: str = "process_id"
+RUN_KEY_STATE: str = "state"
+
+SELECTION_KEY_PATTERNS: str = "patterns"
+SELECTION_KEY_PROVIDER: str = "provider"
+SELECTION_KEY_TITLE: str = "title"
+
+RUN_ALIVE_INTERVAL: float = 60.0
+"""Seconds between two signs of life a running run writes into its record."""
+
+RUN_STALE_AFTER_DEFAULT: float = 600.0
+"""How long a running run may stay silent before it is taken for dead, unless
+`PROCESS_RUN_STALE_AFTER` says otherwise. Ten signs of life missed: a busy machine
+may skip one, never ten."""
+
+STATE_CANCELLED: str = "cancelled"
+STATE_COMPLETE: str = "complete"
+STATE_FAILED: str = "failed"
+STATE_PENDING: str = "pending"
+STATE_RUNNING: str = "running"

wexample_wex_addon_process-3.0.0/src/wexample_wex_addon_process/exception/run_cancelled_exception.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class RunCancelledException(Exception):
+    """Raised between two items of a run whose record asks for it to stop.
+
+    Not an error: the runner catches it and ends the run `cancelled`, with what it
+    had done so far.
+    """