Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
feature/Log-calls-converted · L-260927-84362f (#1395)
Louis Choquelae0d3bf8221b
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 1e4b2da1b..a4ce4acd4 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:33069c67291228668d0f75b69195fb898918372b58dd416dc57d5f75cc9be789"+digest = "sha256:27af491de53630e46b102be16d3f416bde2273196f41f6186aacc18e69065033"reviewed_by = "Claude (Opus 5.5)"-reviewed_at = "2026-10-09T20:06:34Z"-rationale = "clean-pass: doctor_cmd.py now escapes the credentials advice at its print, and backend_credentials.py writes the table as [openai] instead of the Rich escape, so the doctor's Backend Credentials row prints the same [openai] it did before; graph_cmd.py's refused-spec branch keeps its console print and only turns its log line into a fixed message with file.path, error.type and error.message fields. Re-read doctor.md (the Backend Credentials row's advice, still accurate), run.md (no graph render failure wording) and agent_cli/CLAUDE.md (the agent doctor's envelope, which does not carry the comprehensive advice text, verified by grepping agent_cli for its factory): nothing stale."+reviewed_at = "2026-10-10T01:15:46Z"+rationale = "clean-pass: the generic failure branches of pipelex run (execute_run in commands/run/_run_core.py) and pipelex graph render (graph_render_cmd) now print the exception's type and message through the new print_unexpected_failure in error_handlers.py, beside the unchanged ERROR log line with its traceback, header line and exit code 1. Read docs/tools/cli/index.md, run.md and the rest of docs/tools/cli/: none describes what an unexpected local failure prints (run.md's failure prose covers hosted runs and bundle refusals, index.md's --traceback covers the known-error branches through print_traceback_if_requested, which did not move), so nothing is stale. Grepped pipelex/cli/agent_cli for both modules and the new helper: the agent CLI runs its own run core and never reaches either branch, so pipelex/cli/agent_cli/CLAUDE.md is unaffected."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -36,7 +36,7 @@ rationale = "clean-pass: doctor_cmd.py now escapes the credentials advice at its"pipelex/cli/agent_cli/commands/plxt_passthrough.py" = "blob:a1c530d110482485ce462f199b9e79fac29f8896""pipelex/cli/agent_cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/run/_output_helpers.py" = "blob:40ed1700e0d5e86d7696eadd7f9887baeb8059f6"-"pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:32f973c5c754b23016f3e708ab3235856e8bc5f4"+"pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:64995a638dfd3a0d0da3325d89e0aec318cceb58""pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:cea011e61feb082a7b9d82d7693b4fd3246737e5""pipelex/cli/agent_cli/commands/run/app.py" = "blob:7546d9b31ea2dc22b1ddae538edfbc8e7f7d08df""pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:86988b3506ebc057df6a55d8862105ba6ceb693b"@@ -74,13 +74,13 @@ rationale = "clean-pass: doctor_cmd.py now escapes the credentials advice at its"pipelex/cli/commands/codegen/inputs_cmd.py" = "blob:28b22cfbca717d3f5ee75162b68e132439655deb""pipelex/cli/commands/codegen/types_cmd.py" = "blob:27d7a06d571ad832b449d21b6f9eb66c017fb197""pipelex/cli/commands/crate_loading.py" = "blob:3d7d651931ecf1a15a3e2d72411b3212b55d74ef"-"pipelex/cli/commands/doctor_cmd.py" = "blob:ba2b1f3985b09aea8430410dad6c6bdbf0a2c599"+"pipelex/cli/commands/doctor_cmd.py" = "blob:a991d210787c0df68d9cc6bac29361df89e8e9c7""pipelex/cli/commands/fix/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:d39c0df92b95567f74881deb01f8c1b3119fc8ef""pipelex/cli/commands/fix/_fix_core.py" = "blob:aa698305e6b60dfb7caf133698dc1d5c1f5f68f1""pipelex/cli/commands/fix/app.py" = "blob:6f019930e8e3e0043ee46d87493ba4602eb33a76""pipelex/cli/commands/fix/bundle_cmd.py" = "blob:427364cc453957dfe0cec879f019050329c13b3c"-"pipelex/cli/commands/graph_cmd.py" = "blob:69402efebdd624ccad432256718c468c868f93b0"+"pipelex/cli/commands/graph_cmd.py" = "blob:1ffd1aa7342631eed79f68fe6dacc0959d3014c3""pipelex/cli/commands/init/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/init/backends.py" = "blob:04a1a06f1003ed0c7157ec4ca6c8659e4e09fe6b""pipelex/cli/commands/init/command.py" = "blob:f5cbca22f8ea19957f271af2d9844d9191263520"@@ -108,7 +108,7 @@ rationale = "clean-pass: doctor_cmd.py now escapes the credentials advice at its"pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:957e6eb00531d168b3b1e179a517717d069cb7fc""pipelex/cli/commands/run/_inputs_path_resolver.py" = "blob:c8ec89d98718e18af7aaaded44c9f545be60adab""pipelex/cli/commands/run/_main_stuff_file.py" = "blob:ca806e55085aa2e5748492751521296ce1f42960"-"pipelex/cli/commands/run/_run_core.py" = "blob:7e5b2fd0a44ad04b254c77384f24a370bc4e80b1"+"pipelex/cli/commands/run/_run_core.py" = "blob:54d326f5bc5fa62dfef11d96b36b9f8d2b352c22""pipelex/cli/commands/run/_run_hosted.py" = "blob:dd5801877a636f71187e9b23c2fab18d4d25ba32""pipelex/cli/commands/run/app.py" = "blob:e312b159625e0a72bc9a18d3bfd2c73e7ac59f24""pipelex/cli/commands/run/bundle_cmd.py" = "blob:aba274dc8d6d0ac08baa3f21afbc06b2fdbec356"@@ -123,9 +123,9 @@ rationale = "clean-pass: doctor_cmd.py now escapes the credentials advice at its"pipelex/cli/commands/validate/bundle_cmd.py" = "blob:1fbf3e0cf695db39101c83160a724df6468988e9""pipelex/cli/commands/validate/method_cmd.py" = "blob:f12ee233fc985d04a4512f1fef6b9ea02a1b9644""pipelex/cli/commands/validate/pipe_cmd.py" = "blob:791b9a693f4ec52f727b42dab4b102af46a4ee22"-"pipelex/cli/commands/which_cmd.py" = "blob:530bcf9c593f5b6d09b84d929b932310fc891fde"+"pipelex/cli/commands/which_cmd.py" = "blob:5febd14510603f09ef0fb29d5ef97c35b7a6692f""pipelex/cli/deck_notice.py" = "blob:542877125e89e35b02bc969cfee952155b0d7c2c"-"pipelex/cli/error_handlers.py" = "blob:92d233152460052a423f021e8252fbce872a9de4"+"pipelex/cli/error_handlers.py" = "blob:b4ddd1a0a40d75f948779e86a52739d793e4cff6""pipelex/cli/exceptions.py" = "blob:1d51c3a53ddd3f6cf8de566fa2ade3fa75ab7a3a""pipelex/cli/installed_methods.py" = "blob:f7818b7857a8350389cf196e32630e7b3c51818c""pipelex/cli/method_resolver.py" = "blob:afaf77b2d8b6a3467d6ab1f355b1ee78a71eafa7"diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.tomlindex ddb183aa9..a4bdd14ca 100644--- a/.drift/acks/config-docs.toml+++ b/.drift/acks/config-docs.toml@@ -1,8 +1,8 @@contract = "config-docs"-digest = "sha256:06083f22760900182f7c24332130ecebcde8874745159b69e6acf39e737f38eb"+digest = "sha256:befa3b014fb06f0fd7cdc943212d7d5b86f7eca17b5e8c7b8bb9b001af97b375"reviewed_by = "Claude (Opus 5.5)"-reviewed_at = "2026-10-09T19:29:59Z"-rationale = "real-catch: RichLogConfig loses is_markup_enabled and pipelex.toml its default. Grepped docs/configuration for the key and for rich_log: logging-config.md listed it under Syntax Highlighting and in the full example, both removed, and the section now says the console reads no message as markup and that a file still setting the key boots, deleted in memory by pipelex-config@7 with a stale-configuration warning, which tests/unit/pipelex/migration/test_markup_setting_retirement.py pins through ConfigLoader.load_config_validated. The ledger gains pipelex-config@7 (delete_key, safe) with defaults@7 and fingerprint@7; configs.py and config_cogt.py name no rich_log setting and are unchanged."+reviewed_at = "2026-10-10T00:27:59Z"+rationale = "real-catch: StaleConfigurationWarning.emit in config_surface.py now words its messages 'and nothing was written' and has two more messages for a file with blocked steps, reached by pipelex migrate or not. Re-read docs/configuration: inference-backend-config.md quoted the old 'without being rewritten' line and now quotes the reached, unblocked message as the code emits it; telemetry-config.md and logging-config.md only say the boot warns and writes nothing, which still holds. No config model, default, validator or ledger entry moved: configs.py, config_cogt.py and pipelex/migration/ledgers/ are untouched."[trigger_files]"pipelex/cogt/config_cogt.py" = "blob:02f71cb4a6b01aebda59c2e31f262ef9c865e17b"@@ -13,10 +13,10 @@ rationale = "real-catch: RichLogConfig loses is_markup_enabled and pipelex.toml"pipelex/pipelex.toml" = "blob:af0f9f1f117c404333866b8c60ae61d95afab962""pipelex/system/configuration/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc""pipelex/system/configuration/config_check.py" = "blob:2d5de29aba3d2ce205d3d82b4623f37b53108332"-"pipelex/system/configuration/config_loader.py" = "blob:7563f68051a568ba90d3209c1966d678078c6de2"+"pipelex/system/configuration/config_loader.py" = "blob:2850f6b39df6ad2afafefc4d431672cb6ee91ced""pipelex/system/configuration/config_model.py" = "blob:83b29dc6e93393c9b98c4353636caf0135c80339""pipelex/system/configuration/config_root.py" = "blob:c7d43851270912d17413cfc6a511247d3c7cc160"-"pipelex/system/configuration/config_surface.py" = "blob:dc6c877564254aa97ce0b20fd29118def31c957c"+"pipelex/system/configuration/config_surface.py" = "blob:7d865822cb339818ac54bbd0d623ad0b39f690fd""pipelex/system/configuration/configs.py" = "blob:1754391061f3be47e28088a4f8ea85e60b1cdd2b""pipelex/system/configuration/pipe_func_config.py" = "blob:dc8890e914fbcdb611147e42eaa0cd87b32288a5""pipelex/system/telemetry/telemetry_config.py" = "blob:068a785d97a2d52ee43e82e723cd944b8b6601bc"diff --git a/.drift/acks/pipelex-kernel-docs.toml b/.drift/acks/pipelex-kernel-docs.tomlindex b10f9f4e0..92d5f2f8a 100644--- a/.drift/acks/pipelex-kernel-docs.toml+++ b/.drift/acks/pipelex-kernel-docs.toml@@ -1,8 +1,8 @@contract = "pipelex-kernel-docs"-digest = "sha256:f5bde33c053cdc8c339cad7478dace7beeb9f9a3323e22e1fb98992bdb05717a"-reviewed_by = "Claude (Opus 5.5)"-reviewed_at = "2026-10-09T20:31:54Z"-rationale = "clean-pass: llm_ops.py's VERBOSE line for a model whose backend SDK is not installed gains gen_ai.request.model (the deck handle) and gen_ai.response.model (the provider's model id), the keys and meanings of the LLM span; no kernel function, parameter or behaviour moved. Re-read pipelex-kernel.md's check_llm_setting_with_served_model paragraph: such a model is still left to the run, and the doc names no log field."+digest = "sha256:fb848d94ab17c80a70f8e6118a66de94ae5be10c3688e8c3e55f224d6106e3d9"+reviewed_by = "Louis Choquel"+reviewed_at = "2026-10-09T22:54:09Z"+rationale = "clean-pass: judgment_ops.py's no-probability warning keeps its level and becomes a fixed message with pipe_code, threshold and model_handle as fields, and llm_ops.py's two cycle and hop-limit lines in concrete_llm_model_handle move from WARNING to DEBUG with fixed messages; no kernel function, parameter or behaviour moved. Re-read pipelex-kernel.md: its run_judgment paragraph still holds (a live run with a declared threshold and no probability logs a warning), and it describes no log line of concrete_llm_model_handle."[trigger_files]"pipelex/kernel/__init__.py" = "blob:c4f1b0fe2ccc17db9110733f71b612f4ac1ba4ce"@@ -16,9 +16,9 @@ rationale = "clean-pass: llm_ops.py's VERBOSE line for a model whose backend SDK"pipelex/kernel/img_gen_ops.py" = "blob:b85360f6c118e93be53bf8d1a04504ccb7552469""pipelex/kernel/img_gen_prompt.py" = "blob:1f6347e10eaab2eb229fa1cee080c6bbc7878bd2""pipelex/kernel/img_gen_results.py" = "blob:46b4ca11c70d906ae6d58ce66461f9b3414f1bfa"-"pipelex/kernel/judgment_ops.py" = "blob:49ce7414eed9cfdf5595e877a64aacd29ada86ca"+"pipelex/kernel/judgment_ops.py" = "blob:97acd7bdff4279b3c0ed01cc48f31716f0347cb4""pipelex/kernel/judgment_results.py" = "blob:40ba1258cc81d34df3e427d5511ccd40c6edf789"-"pipelex/kernel/llm_ops.py" = "blob:4002e83ea886140a930d994a717d3ef329453d25"+"pipelex/kernel/llm_ops.py" = "blob:d37a9c3718a37f5e7d1550d1512dddbf79032cae""pipelex/kernel/llm_prompt_content.py" = "blob:eabf0ee760c3a26b8967973d511e712e9275e99b""pipelex/kernel/llm_results.py" = "blob:6e3b8a2878b5bb284ece5fac10262fb59ac2029d""pipelex/kernel/memory_ops.py" = "blob:7fbbfaaec99f9712d8e215520cb02e26aad3fb40"diff --git a/AGENTS.md b/AGENTS.mdindex b98e4cb68..b93a0daae 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -202,7 +202,7 @@pretty_print(output_object, title="Your first Pipelex output")```- Both handle formatting json using Rich, pretty_print makes it prettier.-- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.+- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text; an exception logged and then re-raised rides as `**error_fields(exc=exc)` at every level, its traceback being its catcher's to print, and so do a cleanup's failure while another exception propagates, whose traceback would chain the primary's text, and a swallowed pydantic `ValidationError`, whose traceback quotes the values it refused. The catcher of an unexpected failure, a CLI command's root or the API's error handler, logs it at ERROR with `include_exception=True` and prints no traceback of its own; a CLI command's root also prints the exception's type and message in its own output (`print_unexpected_failure` in `pipelex.cli.error_handlers`), so the terminal names the cause whatever the sink and the level. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.#### StrEnum and Self typediff --git a/CHANGELOG.md b/CHANGELOG.mdindex 755cc909f..480b1c48e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,14 +4,14 @@### Added-- **The console shows a log call's fields and renders named layouts**: the `console` sink prints a record's fields after its message as a `key=value` suffix, `Scanned the inputs files=7`, each value on one line and cut short past 80 characters, a handled exception's `error.message` only past 2000, leaving out the run identifiers, and colours a value by its field's name, a pipe code red and a concept bold green, with any other field dimmed. A call can name a console layout with `layout=`, a Rich template over its fields in which every value is escaped, starting with `LogLayout.PIPE_RUN` for the pipe-run tree; every other sink writes the plain message and the fields.-- **Log-call conventions and their guard**: the logging documentation states how Pipelex's own log calls are written, a fixed message with its values in `fields` named from a shared vocabulary, an exception carried by the record rather than spliced into the text, no run identifier, payload, markup or emoji, and what each level promises. `make check-log-calls` (`pipelex-dev check-log-calls`), part of `make agent-check` and CI, refuses an interpolated or non-literal message at `INFO` and above and a Rich markup tag in a message at any level, against a committed baseline of the existing calls that only shrinks: `--against <ref>` and `--against-merge-base <ref>` refuse an entry the baseline at the base revision does not list, which CI runs against a pull request's base and `make` against the merge base with `origin/dev`. `pipelex.tools.log.error_fields` gives a handled exception's class and text as the `error.type` and `error.message` fields of a warning, which carries no traceback.+- **The console shows a log call's fields and renders named layouts**: the `console` sink prints a record's fields after its message as a `key=value` suffix, `Scanned the inputs files=7`, each value on one line and cut short past 80 characters, a string or the JSON of a list or a mapping before it is quoted so a quoted value keeps both its quotes and a cut one leaves no unbalanced quote or bracket, a path at its start so the file's name stays, a handled exception's `error.message` and a PipeDocGen template finding's text only past 2000, leaving out the run identifiers, and colours a value by its field's name, a pipe code red and a concept bold green, with any other field dimmed. A call can name a console layout with `layout=`, a Rich template over its fields in which every value is escaped, starting with `LogLayout.PIPE_RUN` for the pipe-run tree; every other sink writes the plain message and the fields.+- **Log-call conventions and their guard**: the logging documentation states how Pipelex's own log calls are written, a fixed message with its values in `fields` named from a shared vocabulary, an exception carried by the record rather than spliced into the text, no run identifier, payload, markup or emoji, and what each level promises. `make check-log-calls` (`pipelex-dev check-log-calls`), part of `make agent-check` and CI, refuses an interpolated or non-literal message at `INFO` and above and a Rich markup tag in a message at any level, against a committed baseline of the existing calls that only shrinks: `--against <ref>` and `--against-merge-base <ref>` refuse an entry the baseline at the base revision does not list, which CI runs against a pull request's base and `make` against the merge base with `origin/dev`. `pipelex.tools.log.error_fields` gives a handled exception's class and text as the `error.type` and `error.message` fields of a line that carries no traceback, a pydantic `ValidationError`'s text as its locations and reasons without the values it refused or the name of a key the model forbids, and any message that may quote the input, a custom validator's or one of pydantic's own templates', such as an unknown discriminator tag, as its error type alone.- **Summary events for inference calls and pipe runs**: every inference call, an LLM call, an image generation, an extraction, a search, a judgment or a document print, a call its checks refuse included, ends with one `INFO` event, `Inference call ends`, carrying the operation under `gen_ai.operation.name`, the model under `model_handle`, `backend_name`, `sdk`, `gen_ai.request.model` and `gen_ai.response.model`, the tokens under `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` and the price under `cost_usd` where the call recorded them, `duration_ms`, and `outcome`, `success`, `error` with `error.type`, or `cancelled` for work stopped from outside, logged by the worker bases so every provider's and plugin's worker gets it. Every live pipe run ends with `Pipe run ends`, logged as the pipe's own span closes and carrying its ids, with the announcement's fields, `duration_ms`, `outcome` and `error.type`, so a run's `json` output alone gives latency and cost per operation and model; an event that cannot be built is replaced by the warning `A summary event could not be logged` and never changes the work's outcome. The console draws each on one line through `LogLayout.INFERENCE_CALL_END` and `LogLayout.PIPE_RUN_END`; a document engine overrides `render` alone, and the print stage that calls it logs the event.- **Request- and page-priced usage**: a usage says what its counts are in `pricing_unit` (`PricingUnit` in `pipelex.cogt.usage.pricing_unit`), `token`, `request` or `page`, and a worker billed by the request or by the page records it with `record_unit_priced_usage` (`pipelex.cogt.usage.usage_cost`), as the Linkup workers and the extraction page fallback now do, so the summary event carries the call's cost and no token counts.### Changed-- **Library-loading warnings carry their values as fields**: the warnings logged while a library loads, for an unparseable `METHODS.toml`, an unsatisfied or unparseable `mthds_version`, a dependency with no valid bundle or a pipe that would not load, an unresolvable method package and the teardown of a stale library, each have one fixed message and carry the package address, the dependency alias, the pipe code and the error as fields, where they used to splice those values into the text.+- **Log lines carry a fixed message and their values as fields (Breaking)**: every `INFO`, `WARNING`, `ERROR` and `CRITICAL` line of Pipelex and of its API server has one fixed sentence for its message and carries what varies, a pipe code, a model handle, a file path, a handled error's `error.type` and `error.message`, as fields named from the vocabulary in the logging documentation, so a log store groups a line by its message and filters it by its fields, and the baseline of `make check-log-calls` is empty, every call being held to the conventions. A line nobody can act on moved down to `DEBUG`, a lost inference usage record up to `ERROR`, an exception logged and then re-raised, a cleanup's failure while another error propagates and a swallowed `ValidationError` carry no traceback, whose text could quote a run's inputs, so a failed `pipelex run` prints one, and `pipelex run` and `pipelex graph render` log an unexpected failure at `ERROR` with its traceback, which the console renders under the line without its local variables and a structured sink writes to the log store, while the command's own output names the exception's type and message whatever the sink and the level. What breaks is a log query: the API server's error record drops its `event: api_error` field and renames `route`, `user_id`, `error_type`, `status`, `provider` and `model` to `url.path`, `user.id`, `error.type`, `http.response.status_code`, `backend_name` and `model_handle`, the API server no longer writes a refused `user_id` claim or `X-User-Id` header under `user.id`, the claim's type riding `claim_type` instead, and the warning that a configuration file is out of date is one line per stale file, the file in `file.path`, where it used to list them all in one.- **The pipe announcement is a plain message with fields**: every live pipe run logs `Pipe run starts` with `pipe_type`, `pipe_code`, `output_concept` and `pipe_depth` as fields, where the `json`, `otlp` and `gcp` sinks used to receive Rich markup inside the message, and the console draws the same coloured pipe tree from those fields through `LogLayout.PIPE_RUN`. The warning that a model's fixed temperature replaced the requested one carries its values as fields in the same way: `model_handle`, `backend_name`, `sdk`, the model's handle under `gen_ai.request.model` and the provider's model id under `gen_ai.response.model` as on the LLM call's span, the requested temperature under `gen_ai.request.temperature`, and `fixed_temperature`; the verbose line saying a model's settings were not checked, since its backend's SDK is not installed, carries the same model fields.- **The default output logs every inference call and every live pipe run**: at the default `INFO` level an application embedding pipelex now gets an `Inference call ends` line after each inference call and a `Pipe run ends` line after each live pipe run. To quiet either, raise its logger's level in `[runtime.log.package_log_levels]`: `pipelex-cogt-inference-inference_call_summary = "WARNING"` for the inference event, and `pipelex-pipe_machinery-pipe_abstract = "WARNING"` for the pipe-run end, which quiets the pipe announcement too, since the two share that logger.diff --git a/api/CLAUDE.md b/api/CLAUDE.mdindex 19684cde3..cb96e3606 100644--- a/api/CLAUDE.md+++ b/api/CLAUDE.md@@ -198,7 +198,7 @@ Every error is rendered as RFC 7807 `application/problem+json` by the global han- **Domain errors** (pipelex `PipelexError` subclasses) — raise from your code and let them propagate. The `PipelexError` global handler obtains an `ErrorReport` via `to_error_report()` and renders it into a problem document. Do not wrap, classify, or re-shape.- **API-authored 4xx/5xx** — use the helpers in `pipelex_api/errors.py`: `raise_validation_error`, `raise_bad_request`, `raise_forbidden`, `raise_unauthenticated`, `raise_payload_too_large`, `raise_internal_server_error`. Each raises an `ApiError` carrying a pre-built problem document; the global handler emits it. **Do not raise `HTTPException` directly** — FastAPI's default handler wraps the body as `{"detail": <whatever>}` and cannot emit a flat RFC 7807 document.- **Auth errors** — the helpers set `WWW-Authenticate: Bearer` automatically on 401.-- **Logging** — the global handlers emit one structured record per error, carrying `event: "api_error"`, `route`, `error_type`, `error_domain`, `retryable`, `status`, and `user_id` / `pipe_code` / `pipeline_run_id` when the request bound them. `detail` rides the API-authored path only: a Pipelex `ErrorReport`'s body text has been through disclosure redaction, so it is not the cause and is deliberately not logged. They travel as `fields=` on the runtime's log call, never interpolated into the message, and `request_id` is not among them: `RequestIdMiddleware` binds it on the runtime's log context, so every record emitted under the request already carries it. The server selects the `json` sink, so a record reaches stderr as one JSON object per line — see `docs/api-server/logging.md` at the repository root. Log disposition follows the final HTTP status: 4xx logs at `warning` (caller mistakes, the provider-429 passthrough, and API-level 4xx overrides like the 409 conflict); 5xx logs at `error` with traceback. Routes should not log error tracebacks themselves.+- **Logging** — the global handlers emit one structured record per error, with the fixed message `A request ended in an error response` (the key the error stream is selected by; there is no `event` field) and the fields `url.path`, `error.type`, `error_domain`, `retryable`, `http.response.status_code`, and `user.id` / `pipe_code` / `pipeline_run_id` when the request bound them. `detail` rides the API-authored path only: a Pipelex `ErrorReport`'s body text has been through disclosure redaction, so it is not the cause and is deliberately not logged. They travel as `fields=` on the runtime's log call, never interpolated into the message, and `request_id` is not among them: `RequestIdMiddleware` binds it on the runtime's log context, so every record emitted under the request already carries it. The server selects the `json` sink, so a record reaches stderr as one JSON object per line — see `docs/api-server/logging.md` at the repository root. Log disposition follows the final HTTP status: 4xx logs at `warning` (caller mistakes, the provider-429 passthrough, and API-level 4xx overrides like the 409 conflict); 5xx logs at `error` with traceback. Routes should not log error tracebacks themselves.- **Documenting a failure in OpenAPI** — the shared, typed `responses=` declarations live in `pipelex_api/openapi_responses.py` (`ProblemDocument` + one constant per status). Every auth-wrapped `/v1` route already documents `401`/`413`/`422`/`500` via the composite router's `responses=` (`pipelex_api/routes/__init__.py`); a route declares on its own decorator only the statuses **it alone** can produce. Never hand-write an error `content` block: `pipelex_api/openapi_schema.py` re-keys the generated schema onto `application/problem+json`, because FastAPI renders a response `model` under the route's response-class media type and offers no per-response override. Adding a new status means adding a constant there and referencing it — then `make openapi-export`.Typical route:diff --git a/api/pipelex_api/bundle.py b/api/pipelex_api/bundle.pyindex 402debfd5..4ca721045 100644--- a/api/pipelex_api/bundle.py+++ b/api/pipelex_api/bundle.py@@ -49,6 +49,7 @@ from mthds.package.discovery import MANIFEST_FILENAMEfrom mthds.package.exceptions import ManifestErrorfrom mthds.package.manifest.parser import parse_methods_tomlfrom pipelex import log+from pipelex.tools.log.error_fields import error_fieldsfrom pydantic import ConfigDictfrom pydantic.dataclasses import dataclass@@ -133,13 +134,15 @@ def _entries_from_zip(bundle_b64: str) -> list[tuple[PurePosixPath, bytes]]:try:raw = base64.b64decode(bundle_b64, validate=True)except (binascii.Error, ValueError) as decode_error:- log.warning(f"bundle: invalid base64 ({decode_error})")+ # DEBUG: the refusal below is a caller's mistake, which the error handler already logs; this keeps the cause.+ log.debug("A bundle's base64 could not be decoded", fields=error_fields(exc=decode_error))raise_bad_request(message="bundle_b64 is not valid base64", error_type=ErrorType.INVALID_BASE64)try:archive = zipfile.ZipFile(BytesIO(raw))except zipfile.BadZipFile as zip_error:- log.warning(f"bundle: corrupt zip ({zip_error})")+ # DEBUG: the refusal below is a caller's mistake, which the error handler already logs; this keeps the cause.+ log.debug("A bundle is not a valid zip archive", fields=error_fields(exc=zip_error))raise_validation_error(message="bundle_b64 is not a valid zip archive", error_type=ErrorType.INVALID_BUNDLE)entries: list[tuple[PurePosixPath, bytes]] = []diff --git a/api/pipelex_api/exception_handlers.py b/api/pipelex_api/exception_handlers.pyindex 3b0101290..4158f0481 100644--- a/api/pipelex_api/exception_handlers.py+++ b/api/pipelex_api/exception_handlers.py@@ -27,7 +27,7 @@ every module that imports a handler at once."""import math-from collections.abc import Awaitable, Callable, Mapping+from collections.abc import Awaitable, Callablefrom typing import TYPE_CHECKING, Any, castfrom fastapi import FastAPI, Request, Response@@ -36,6 +36,8 @@ from fastapi.responses import JSONResponsefrom pipelex import logfrom pipelex.base_exceptions import DisclosureMode, ErrorDomain, ErrorReport, PipelexErrorfrom pipelex.plugins.registrar import HttpErrorMapperFn+from pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.error_fields import ERROR_TYPE_FIELDfrom starlette.requests import ClientDisconnectfrom pipelex_api.error_types import ErrorType@@ -54,10 +56,6 @@ if TYPE_CHECKING:# A Starlette/FastAPI async exception handler: `(request, exc) -> response`._ExceptionHandler = Callable[[Request, Exception], Awaitable[Response]]-# The value of the `event` field every error record carries: the one key a log sink filters this-# server's error stream on, whichever of the handlers below produced the record.-API_ERROR_EVENT = "api_error"-def _user_id_of(request: Request) -> str | None:"""Return the authenticated caller's id, when one is on the request.@@ -71,7 +69,7 @@ def _user_id_of(request: Request) -> str | None:pre-auth, on the static-API-key surface (no per-caller identity), or for`AUTH_MODE=none` without the forwarded-identity opt-in: `_emit_api_error`drops `None`-valued fields, so the attribute is absent from the record- rather than carried as `user_id: null`.+ rather than carried as `user.id: null`."""user: RequestUser | None = getattr(request.state, "user", None)return user.user_id if user is not None else None@@ -110,16 +108,19 @@ def _pipeline_run_id_of(request: Request) -> str | None:def _request_fields(request: Request) -> dict[str, Any]:"""Return the request-scoped attributes every error record carries.- Single source of truth for the `route` / `user_id` / `pipe_code` /+ Single source of truth for the `url.path` / `user.id` / `pipe_code` /`pipeline_run_id` set, so the three log paths (`_log_error_report`,- `_log_api_authored_error`, `handle_unexpected_error`) cannot drift.+ `_log_api_authored_error`, `handle_unexpected_error`) cannot drift. The+ path and the caller take their OpenTelemetry keys, the pipe and the run+ the runtime's own field names, so a query written for the runtime's lines+ finds these too.`request_id` is deliberately NOT here. `RequestIdMiddleware` binds it on theruntime's log context for the whole request, so it is already an attribute ofevery record emitted underneath — including the ones pipelex emits from insidea run, which this module never sees. Repeating it would give one value two- sources. `route` is here rather than on that context because the runtime- reserves the context for its three run identifiers, and a route path is not+ sources. The path is here rather than on that context because the runtime+ reserves the context for its three run identifiers, and a URL path is notone of them; a field is the seam it offers for everything else.Each value is `None` when the corresponding state is not bound on this request;@@ -127,8 +128,8 @@ def _request_fields(request: Request) -> dict[str, Any]:record rather than carried as `pipe_code: null`."""return {- "route": request.url.path,- "user_id": _user_id_of(request),+ "url.path": request.url.path,+ OTelLogAttr.USER_ID: _user_id_of(request),"pipe_code": _pipe_code_of(request),"pipeline_run_id": _pipeline_run_id_of(request),}@@ -156,30 +157,20 @@ def _retry_after_header(report: ErrorReport) -> dict[str, str]:return {"Retry-After": str(max(0, math.ceil(seconds)))}-def _error_summary(attributes: Mapping[str, Any]) -> str:- """Return the human-readable message an `api_error` record carries.-- Built from server-authored values only — the HTTP status and the error type,- both of which the API or pipelex chose. Nothing a caller supplied ever reaches- the message: `detail` is caller-controlled on several routes, and the route- path is percent-decoded from the request line, so both ride fields instead,- where a structured sink serializes them as values and a crafted newline stays- inside one. The message says which failure it is; the fields say everything- about it.- """- status = attributes.get("status")- error_type = attributes.get("error_type")- return f"API error {status}: {error_type}" if error_type else f"API error {status}"--def _emit_api_error(*, fields: dict[str, Any], as_error: bool) -> None:- """Emit one `event=api_error` record: a summary message, everything else a record attribute.+ """Emit one error record: a fixed message, everything about the failure a record attribute.++ The message is the same on every error line, whichever handler produced it, so it is the key a+ query or an alert selects this server's error stream by; there is no separate `event` field+ beside it. Nothing about the failure reaches the message, the status and the error type+ included: a log store groups and counts lines by their message, and `detail` is+ caller-controlled on several routes while the URL path is percent-decoded from the request+ line, so both ride fields, where a structured sink serializes them as values and a crafted+ newline stays inside one.- The fields are handed to the runtime's log call as `fields=`, so each one- becomes an attribute of the record and the selected sink decides how it goes- on the wire — a key of its own on the JSON sink's line, an OTLP attribute on- the collector's. Nothing is flattened into the message here any more, which- is what retires the API's own `key=value` rendering and its escaping with it.+ The fields are handed to the runtime's log call as `fields=`, so each one becomes an attribute+ of the record and the selected sink decides how it goes on the wire — a key of its own on the+ JSON sink's line, an OTLP attribute on the collector's.`None`-valued fields are dropped, so an identifier this request never bound isabsent rather than carried as a null. `as_error` picks the level — `error`@@ -187,11 +178,10 @@ def _emit_api_error(*, fields: dict[str, Any], as_error: bool) -> None:`INPUT`-domain caller mistakes."""attributes = {key: value for key, value in fields.items() if value is not None}- summary = _error_summary(attributes)if as_error:- log.error(summary, fields=attributes, include_exception=True)+ log.error("A request ended in an error response", fields=attributes, include_exception=True)else:- log.warning(summary, fields=attributes)+ log.warning("A request ended in an error response", fields=attributes)def _emit_at_error_level(status: int) -> bool:@@ -216,9 +206,9 @@ def _log_error_report(report: ErrorReport, *, request: Request, status: int | Nomistakes, the provider-429 passthrough, and API-level 4xx overrides likethe 409 conflict), a 5xx logs at `error` with the traceback. The fieldsmirror the response so the two never drift.- `user_id` rides every record when auth bound a caller — without it, the+ `user.id` rides every record when auth bound a caller — without it, thestorage / pipeline-backend leg of a failure carries only `request_id` and- `route`, and tying the failure to the caller requires correlating the+ `url.path`, and tying the failure to the caller requires correlating therequest id across unrelated records (Phase 3 deleted the per-route`log.error(... user=...)` lines those failures used to emit).@@ -229,15 +219,18 @@ def _log_error_report(report: ErrorReport, *, request: Request, status: int | No"""effective_status = status if status is not None else report.http_statusfields: dict[str, Any] = {- "event": API_ERROR_EVENT,**_request_fields(request),- "error_type": report.error_type,+ ERROR_TYPE_FIELD: report.error_type,"error_category": report.error_category,"error_domain": report.error_domain,"retryable": report.retryable,- "status": effective_status,- "provider": report.provider,- "model": report.model,+ OTelLogAttr.HTTP_RESPONSE_STATUS_CODE: effective_status,+ # A report's `provider` is the backend the error names, which a worker attributes its failure to, and its `model`+ # the handle the pipe named. The provider the SDK's metadata names, `openai` or `gateway`, is no backend's name+ # and no SDK's as the backends configuration names them, so it is left off: an unattributed failure has no+ # `backend_name` rather than a second spelling of the same backend.+ "backend_name": report.provider,+ "model_handle": report.model,}metadata = report.provider_metadataif metadata is not None:@@ -252,9 +245,9 @@ def _log_api_authored_error(*, document: dict[str, Any], status: int, request: RShares the disposition rule and the common-key set of `_log_error_report`so every error response — a pipelex `ErrorReport` translated to RFC 7807*or* an API-authored 4xx/5xx raised by an `pipelex_api.errors` helper — produces- one `event=api_error` record a downstream sink can filter uniformly on- `event`, `request_id`, `route`, `error_type`, `error_domain`, `retryable`,- and `status`. Without this, an API-owned 500 (a `raise_internal_server_error`+ one error record a downstream sink can filter uniformly on its message and+ on `request_id`, `url.path`, `error.type`, `error_domain`, `retryable`+ and `http.response.status_code`. Without this, an API-owned 500 (a `raise_internal_server_error`site — `/version`'s missing-package case is the canonical example)would land with zero operator output, since `handle_api_error` onlyserializes the response.@@ -265,8 +258,8 @@ def _log_api_authored_error(*, document: dict[str, Any], status: int, request: R`build_problem_document_from_api_error` does not apply strict-disclosureredaction (only `build_problem_document` does for pipelex domain errors).Carrying the message preserves the operator-facing cause in the record.- - API-authored docs omit `error_category`, `provider`, `model`, and- `provider_metadata.*` — those are inference-domain classifiers pipelex+ - API-authored docs omit `error_category`, `backend_name`, `model_handle`,+ `provider_status_code` and `provider_request_id` — those are inference-domain classifiers pipelexsets only on classifiable failures and the API never authors itself.A 4xx logs at `warning` without a traceback; a 5xx logs at `error` with@@ -275,12 +268,11 @@ def _log_api_authored_error(*, document: dict[str, Any], status: int, request: Rshape."""fields: dict[str, Any] = {- "event": API_ERROR_EVENT,**_request_fields(request),- "error_type": document.get("error_type"),+ ERROR_TYPE_FIELD: document.get("error_type"),"error_domain": document.get("error_domain"),"retryable": document.get("retryable"),- "status": status,+ OTelLogAttr.HTTP_RESPONSE_STATUS_CODE: status,"detail": document.get("detail"),}_emit_api_error(fields=fields, as_error=_emit_at_error_level(status))@@ -485,12 +477,11 @@ async def handle_unexpected_error(request: Request, exc: Exception) -> Response:request_id = request_id_of(request)_emit_api_error(fields={- "event": API_ERROR_EVENT,**_request_fields(request),- "error_type": type(exc).__name__,+ ERROR_TYPE_FIELD: type(exc).__name__,"error_category": "unknown","error_domain": ErrorDomain.RUNTIME,- "status": 500,+ OTelLogAttr.HTTP_RESPONSE_STATUS_CODE: 500,},as_error=True,)@@ -526,7 +517,7 @@ async def handle_api_error(request: Request, exc: Exception) -> Response:and `request_id`) onto a copy of it — the same two values, read from the sameplace, as the pipelex-error and request-validation paths use. It thenserializes that document, re-attaches any `WWW-Authenticate` challenge header,- and emits the structured `event=api_error` record so an API-owned 500 from any+ and emits the structured error record so an API-owned 500 from anyroute is observable (a `raise_internal_server_error` site like `version.py`'smissing-package case is the canonical example — it has no preceding`log.error` at the call site). `exc` is typed `Exception` to match Starlette's@@ -614,7 +605,7 @@ async def handle_request_validation_error(request: Request, exc: Exception) -> Rrequest_id=request_id_of(request),error_domain=ErrorDomain.INPUT,)- # Same `event=api_error` record as an explicit `raise_validation_error`,+ # Same error record as an explicit `raise_validation_error`,# so FastAPI's automatic-validation 422s aren't silent in operator logs._log_api_authored_error(document=document, status=422, request=request)return JSONResponse(status_code=422, content=document, media_type=PROBLEM_JSON_MEDIA_TYPE)diff --git a/api/pipelex_api/limits.py b/api/pipelex_api/limits.pyindex a92c2a8b6..2884d681e 100644--- a/api/pipelex_api/limits.py+++ b/api/pipelex_api/limits.py@@ -5,8 +5,7 @@ imported from this module. Values are read once at import time — changerequires a process restart."""-from pipelex import log-from pipelex.system.environment import get_optional_env+from pipelex.system.environment import get_positive_int_envDEFAULT_MAX_REQUEST_BODY_MIB = 100DEFAULT_MAX_MTHDS_FILE_KIB = 1024 # 1 MiB per .mthds file@@ -31,34 +30,19 @@ DEFAULT_MAX_METHOD_CACHE_TOTAL_KIB = 512 * 1024 # 512 MiB across all cached cloDEFAULT_MAX_METHOD_CACHE_AGE_HOURS = 24 # a cached clone unused for this long is evicted-def _read_positive_int(env_var: str, default: int) -> int:- raw = get_optional_env(env_var)- if not raw:- return default- try:- parsed = int(raw)- except ValueError:- log.warning(f"Invalid {env_var}={raw!r}, falling back to {default}")- return default- if parsed <= 0:- log.warning(f"{env_var} must be positive (got {parsed}), falling back to {default}")- return default- return parsed---MAX_REQUEST_BODY_MIB = _read_positive_int("MAX_REQUEST_BODY_MIB", DEFAULT_MAX_REQUEST_BODY_MIB)+MAX_REQUEST_BODY_MIB = get_positive_int_env(env_var="MAX_REQUEST_BODY_MIB", default=DEFAULT_MAX_REQUEST_BODY_MIB)MAX_REQUEST_BODY_BYTES = MAX_REQUEST_BODY_MIB * 1024 * 1024-MAX_MTHDS_FILE_BYTES = _read_positive_int("MAX_MTHDS_FILE_KIB", DEFAULT_MAX_MTHDS_FILE_KIB) * 1024-MAX_MTHDS_FILES_PER_REQUEST = _read_positive_int("MAX_MTHDS_FILES_PER_REQUEST", DEFAULT_MAX_MTHDS_FILES_PER_REQUEST)-MAX_PIPE_CODE_LEN = _read_positive_int("MAX_PIPE_CODE_LEN", DEFAULT_MAX_PIPE_CODE_LEN)+MAX_MTHDS_FILE_BYTES = get_positive_int_env(env_var="MAX_MTHDS_FILE_KIB", default=DEFAULT_MAX_MTHDS_FILE_KIB) * 1024+MAX_MTHDS_FILES_PER_REQUEST = get_positive_int_env(env_var="MAX_MTHDS_FILES_PER_REQUEST", default=DEFAULT_MAX_MTHDS_FILES_PER_REQUEST)+MAX_PIPE_CODE_LEN = get_positive_int_env(env_var="MAX_PIPE_CODE_LEN", default=DEFAULT_MAX_PIPE_CODE_LEN)-MAX_CALLBACK_URLS = _read_positive_int("MAX_CALLBACK_URLS", DEFAULT_MAX_CALLBACK_URLS)-MAX_CALLBACK_URL_LEN = _read_positive_int("MAX_CALLBACK_URL_LEN", DEFAULT_MAX_CALLBACK_URL_LEN)+MAX_CALLBACK_URLS = get_positive_int_env(env_var="MAX_CALLBACK_URLS", default=DEFAULT_MAX_CALLBACK_URLS)+MAX_CALLBACK_URL_LEN = get_positive_int_env(env_var="MAX_CALLBACK_URL_LEN", default=DEFAULT_MAX_CALLBACK_URL_LEN)-MAX_BUNDLE_FILES = _read_positive_int("MAX_BUNDLE_FILES", DEFAULT_MAX_BUNDLE_FILES)-MAX_BUNDLE_TOTAL_BYTES = _read_positive_int("MAX_BUNDLE_TOTAL_KIB", DEFAULT_MAX_BUNDLE_TOTAL_KIB) * 1024+MAX_BUNDLE_FILES = get_positive_int_env(env_var="MAX_BUNDLE_FILES", default=DEFAULT_MAX_BUNDLE_FILES)+MAX_BUNDLE_TOTAL_BYTES = get_positive_int_env(env_var="MAX_BUNDLE_TOTAL_KIB", default=DEFAULT_MAX_BUNDLE_TOTAL_KIB) * 1024-MAX_METHOD_CACHE_CLONES = _read_positive_int("MAX_METHOD_CACHE_CLONES", DEFAULT_MAX_METHOD_CACHE_CLONES)-MAX_METHOD_CACHE_TOTAL_BYTES = _read_positive_int("MAX_METHOD_CACHE_TOTAL_KIB", DEFAULT_MAX_METHOD_CACHE_TOTAL_KIB) * 1024-MAX_METHOD_CACHE_AGE_SECONDS = _read_positive_int("MAX_METHOD_CACHE_AGE_HOURS", DEFAULT_MAX_METHOD_CACHE_AGE_HOURS) * 3600+MAX_METHOD_CACHE_CLONES = get_positive_int_env(env_var="MAX_METHOD_CACHE_CLONES", default=DEFAULT_MAX_METHOD_CACHE_CLONES)+MAX_METHOD_CACHE_TOTAL_BYTES = get_positive_int_env(env_var="MAX_METHOD_CACHE_TOTAL_KIB", default=DEFAULT_MAX_METHOD_CACHE_TOTAL_KIB) * 1024+MAX_METHOD_CACHE_AGE_SECONDS = get_positive_int_env(env_var="MAX_METHOD_CACHE_AGE_HOURS", default=DEFAULT_MAX_METHOD_CACHE_AGE_HOURS) * 3600diff --git a/api/pipelex_api/method_source.py b/api/pipelex_api/method_source.pyindex 7dd299574..a6ebb18cc 100644--- a/api/pipelex_api/method_source.py+++ b/api/pipelex_api/method_source.py@@ -94,9 +94,16 @@ def _fetch_package(method_ref: str) -> FetchedMethodPackage:"""ref = parse_method_ref(method_ref)package = get_method_clone_cache().get_or_fetch(ref=ref)+ # The tag and the commit say which version of the package a hosted run executed; the tag is `None` when the+ # reference named none and the default branch was fetched.log.info(- f"Resolved method_ref '{ref.ref_str}': address={package.provenance.address} "- f"tag={package.provenance.tag} commit_sha={package.provenance.commit_sha}"+ "A method_ref was resolved to a package",+ fields={+ "method_ref": ref.ref_str,+ "package_address": package.provenance.address,+ "fetched_tag": package.provenance.tag,+ "commit_sha": package.provenance.commit_sha,+ },)return packagediff --git a/api/pipelex_api/middleware.py b/api/pipelex_api/middleware.pyindex 42bf94026..47dc20cbe 100644--- a/api/pipelex_api/middleware.py+++ b/api/pipelex_api/middleware.py@@ -204,6 +204,6 @@ class RequestIdMiddleware:# The runtime's own context, not an API-owned one: `request_id` is one of the three run# identifiers it reserves, so every record emitted underneath carries it as an attribute.# The route path is deliberately not bound here — it is not a run identifier, and the API- # ships it as a `route` field on the lines that want it (see `pipelex_api.exception_handlers`).+ # ships it as a `url.path` field on the lines that want it (see `pipelex_api.exception_handlers`).with log.context(request_id=request_id):await self.app(scope, receive, send_with_request_id)diff --git a/api/pipelex_api/security.py b/api/pipelex_api/security.pyindex 2383b6934..fbe8a59b4 100644--- a/api/pipelex_api/security.py+++ b/api/pipelex_api/security.py@@ -14,6 +14,7 @@ from fastapi.security import HTTPAuthorizationCredentials, HTTPBearerfrom pipelex import logfrom pipelex.system.environment import get_optional_envfrom pipelex.system.storage_scope import SINGLE_TENANT_USER_ID+from pipelex.tools.log.error_fields import error_fieldsfrom pydantic import BaseModel, Fieldfrom pipelex_api.error_types import ErrorType@@ -124,7 +125,7 @@ def get_auth_mode() -> AuthMode:try:return AuthMode(raw)except ValueError:- log.warning(f"Unknown AUTH_MODE '{raw}', falling back to 'none'")+ log.warning("AUTH_MODE names no known mode, so the server falls back to no authentication", fields={"env_var": "AUTH_MODE", "auth_mode": raw})return AuthMode.NONE@@ -165,7 +166,9 @@ async def verify_jwt(log.warning("JWT missing user_id claim")raise_unauthenticated("Invalid token: missing user_id claim", error_type=ErrorType.INVALID_TOKEN)if not isinstance(user_id, str) or not is_safe_user_id(user_id):- log.warning(f"JWT user_id claim is not a path-safe segment: {user_id!r}")+ # The claim is refused, so it is not `user.id`, which names an authenticated caller and is always a string:+ # the line carries the type the claim was decoded as, and never its value.+ log.warning("A JWT's user_id claim is not a path-safe segment", fields={"claim_type": type(user_id).__name__})raise_unauthenticated("Invalid token: user_id claim must be a single path-safe segment", error_type=ErrorType.INVALID_TOKEN)if user_id == SINGLE_TENANT_USER_ID:# Path-safe, but reserved for the no-user-model deployment. An@@ -186,7 +189,7 @@ async def verify_jwt(log.warning("JWT token has expired")raise_unauthenticated("Token expired", error_type=ErrorType.TOKEN_EXPIRED)except jwt.InvalidTokenError as exc:- log.warning(f"JWT validation failed: {exc!s}")+ log.warning("A JWT failed validation", fields=error_fields(exc=exc))raise_unauthenticated("Invalid token", error_type=ErrorType.INVALID_TOKEN)@@ -247,7 +250,8 @@ async def no_auth(request: Request) -> None:if not is_safe_user_id(user_id):# A non-empty but path-unsafe id: the proxy intended to authenticate# someone and sent a malformed value. Fail closed.- log.warning(f"Forwarded X-User-Id is not a path-safe segment, rejecting: {user_id!r}")+ # No value: the header is refused, so it names no caller, and it is whatever text anyone reaching the server sent.+ log.warning("A forwarded X-User-Id is not a path-safe segment, and the request is refused")raise_bad_request("Forwarded X-User-Id must be a single path-safe segment", error_type=ErrorType.BAD_REQUEST)_set_request_user(request, user_id=user_id)@@ -262,7 +266,7 @@ async def get_request_user(request: Request) -> RequestUser | None:Usage in route handlers:async def my_endpoint(user: Annotated[RequestUser | None, Depends(get_request_user)]):if user:- log.info(f"Request from {user.user_id}")+ log.debug("Serving a request", fields={OTelLogAttr.USER_ID: user.user_id})"""return getattr(request.state, "user", None)diff --git a/api/tests/unit/test_error_log_records.py b/api/tests/unit/test_error_log_records.pyindex 633f64801..c7f9b50a1 100644--- a/api/tests/unit/test_error_log_records.py+++ b/api/tests/unit/test_error_log_records.py@@ -24,7 +24,7 @@ from pipelex.tools.misc.toml_utils import load_toml_from_pathfrom pipelex_api.error_types import ErrorTypefrom pipelex_api.errors import raise_validation_error-from pipelex_api.exception_handlers import API_ERROR_EVENT, register_exception_handlers+from pipelex_api.exception_handlers import register_exception_handlersfrom pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddleware_SHIPPED_PIPELEX_CONFIG = Path(__file__).parents[2] / ".pipelex" / "pipelex.toml"@@ -54,10 +54,14 @@ def _build_client() -> TestClient:return TestClient(RequestIdMiddleware(app))+# The message every error line carries, whichever handler produced it: the key the error stream is selected by.+_ERROR_MESSAGE = "A request ended in an error response"++def _api_error_record(caplog: pytest.LogCaptureFixture) -> logging.LogRecord:- """The one `api_error` record the request emitted."""- records = [record for record in caplog.records if getattr(record, "event", None) == API_ERROR_EVENT]- assert len(records) == 1, f"expected exactly one api_error record, got {len(records)}"+ """The one error record the request emitted."""+ records = [record for record in caplog.records if record.getMessage() == _ERROR_MESSAGE]+ assert len(records) == 1, f"expected exactly one error record, got {len(records)}"return records[0]@@ -88,9 +92,9 @@ class TestErrorLogRecords:assert log_section["console_log_target"] == ConsoleTarget.STDERRassert log_section["pretty_print_mode"] == PrettyPrintMode.SILENT- def test_request_id_and_route_ride_the_error_record(self, caplog: pytest.LogCaptureFixture):+ def test_request_id_and_url_path_ride_the_error_record(self, caplog: pytest.LogCaptureFixture):# The two identifiers an operator starts from. `request_id` arrives from the log context- # the middleware bound for the request; `route` from the field set the handler ships.+ # the middleware bound for the request; `url.path` from the field set the handler ships.# Neither is interpolated into the message, which is the whole point of the change.with caplog.at_level(logging.WARNING):response = _build_client().get("/pipelex-failure")@@ -98,21 +102,20 @@ class TestErrorLogRecords:record = _api_error_record(caplog)assert record.levelno == logging.ERRORassert getattr(record, "request_id", None) == response.headers[REQUEST_ID_HEADER]- assert getattr(record, "route", None) == "/pipelex-failure"- assert getattr(record, "error_type", None) == "PipelexConfigError"- assert record.getMessage() == "API error 500: PipelexConfigError"+ assert getattr(record, "url.path", None) == "/pipelex-failure"+ assert getattr(record, "error.type", None) == "PipelexConfigError"def test_a_caller_mistake_records_a_warning_carrying_the_same_identifiers(self, caplog: pytest.LogCaptureFixture):- # A 4xx is a caller mistake, so it lands at `warning` — but it carries the same two- # identifiers, so one query over `event` returns the whole error stream of a request.+ # A 4xx is a caller mistake, so it lands at `warning` — but it carries the same message and+ # the same two identifiers, so one query over the message returns the whole error stream of a request.with caplog.at_level(logging.WARNING):response = _build_client().get("/caller-mistake", params={"detail": "the input is malformed"})assert response.status_code == 422record = _api_error_record(caplog)assert record.levelno == logging.WARNINGassert getattr(record, "request_id", None) == response.headers[REQUEST_ID_HEADER]- assert getattr(record, "route", None) == "/caller-mistake"- assert getattr(record, "status", None) == 422+ assert getattr(record, "url.path", None) == "/caller-mistake"+ assert getattr(record, "http.response.status_code", None) == 422def test_the_json_sink_writes_one_object_per_line_with_the_fields_flat(self, caplog: pytest.LogCaptureFixture):# The shape the runner's configured sink puts on stderr: the sink's own keys, then every@@ -121,12 +124,12 @@ class TestErrorLogRecords:response = _build_client().get("/pipelex-failure")payload = _rendered_json(_api_error_record(caplog))assert payload["severity"] == "ERROR"- assert payload["message"] == "API error 500: PipelexConfigError"- assert payload["event"] == API_ERROR_EVENT+ assert payload["message"] == _ERROR_MESSAGE+ assert "event" not in payloadassert payload["request_id"] == response.headers[REQUEST_ID_HEADER]- assert payload["route"] == "/pipelex-failure"- assert payload["status"] == 500- assert payload["error_type"] == "PipelexConfigError"+ assert payload["url.path"] == "/pipelex-failure"+ assert payload["http.response.status_code"] == 500+ assert payload["error.type"] == "PipelexConfigError"assert payload["error_domain"] == "config"# `retryable` is absent rather than false: pipelex populates it only on a classifiable# failure, and a field with no value is dropped rather than written as a null a query@@ -163,9 +166,9 @@ class TestErrorLogRecords:assert response.status_code == 422payload = _rendered_json(_api_error_record(caplog))assert payload["detail"] == logged_detail- assert payload["event"] == API_ERROR_EVENT, "a crafted detail forged or overwrote a field"- assert payload["status"] == 422, "a crafted detail forged or overwrote a field"- assert crafted_detail not in payload["message"], "caller input reached the message"+ assert "event" not in payload, "a crafted detail forged a field"+ assert payload["http.response.status_code"] == 422, "a crafted detail forged or overwrote a field"+ assert payload["message"] == _ERROR_MESSAGE, "caller input reached the message"def test_a_credential_echoed_into_a_detail_is_redacted_on_the_line(self, caplog: pytest.LogCaptureFixture):# A validation message can echo what the caller sent, header text included. The runtime'sdiff --git a/api/tests/unit/test_exception_handlers.py b/api/tests/unit/test_exception_handlers.pyindex fe360da9e..acc21fb2b 100644--- a/api/tests/unit/test_exception_handlers.py+++ b/api/tests/unit/test_exception_handlers.py@@ -24,6 +24,7 @@ from pipelex.base_exceptions import (PipelexConfigError,PipelexError,)+from pipelex.cogt.exceptions import InferenceErrorCategory, LLMCompletionErrorfrom pipelex.cogt.inference.error_classification import ProviderErrorMetadata, UserAction, UserActionKindfrom pipelex.cogt.inference.provider_name import ProviderNamefrom pipelex.config import get_config@@ -40,7 +41,7 @@ from typing_extensions import overridefrom pipelex_api.error_types import ErrorTypefrom pipelex_api.errors import raise_internal_server_error, raise_validation_error-from pipelex_api.exception_handlers import API_ERROR_EVENT, register_exception_handlers+from pipelex_api.exception_handlers import register_exception_handlersfrom pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddlewarefrom pipelex_api.problem_document import PROBLEM_JSON_MEDIA_TYPEfrom pipelex_api.routes.pipelex.pipeline import router as pipeline_router@@ -417,6 +418,29 @@ async def run_state_unexpected_error_route(request: Request) -> None:raise RuntimeError(msg)+def _gateway_failure() -> LLMCompletionError:+ """An inference failure whose SDK metadata names the provider family, `gateway`, and no backend."""+ return LLMCompletionError(+ "the gateway is unavailable",+ error_category=InferenceErrorCategory.TRANSIENT,+ provider_metadata=ProviderErrorMetadata(provider=ProviderName.GATEWAY, sdk_exception_type="APIStatusError", status_code=503),+ )+++@_router.get("/inference-failure-attributed")+async def inference_failure_attributed_route() -> None:+ # A failure the worker's chokepoint attributed: the error names the backend that served the model.+ gateway_failure = _gateway_failure()+ gateway_failure.fill_model_and_provider("claude-5.5-sonnet", backend_name="pipelex_gateway")+ raise gateway_failure+++@_router.get("/inference-failure-unattributed")+async def inference_failure_unattributed_route() -> None:+ # A failure no worker attributed: only the SDK's metadata names who answered.+ raise _gateway_failure()++def _build_client(*,raise_server_exceptions: bool = True,@@ -641,12 +665,11 @@ class TestExceptionHandlers:assert response.status_code == 500log_spy.error.assert_called_once()fields = _emitted_fields(log_spy, as_error=True)- assert fields["event"] == API_ERROR_EVENT- assert fields["status"] == 500- assert fields["error_type"] == "ServerMisconfigured"+ assert fields["http.response.status_code"] == 500+ assert fields["error.type"] == "ServerMisconfigured"assert fields["error_domain"] == "config"assert fields["retryable"] is False- assert fields["route"] == "/api-config-error"+ assert fields["url.path"] == "/api-config-error"# The operator-facing cause rides a field of its own and never reaches the message, which# is what stops a crafted value from shaping the rendered line at all.assert fields["detail"] == "the configuration is broken"@@ -662,9 +685,8 @@ class TestExceptionHandlers:assert response.status_code == 422log_spy.warning.assert_called_once()fields = _emitted_fields(log_spy, as_error=False)- assert fields["event"] == API_ERROR_EVENT- assert fields["status"] == 422- assert fields["error_type"] == "ValidationError"+ assert fields["http.response.status_code"] == 422+ assert fields["error.type"] == "ValidationError"assert fields["error_domain"] == "input"assert fields["retryable"] is Falseassert fields["detail"] == "a caller-side mistake"@@ -717,16 +739,41 @@ class TestExceptionHandlers:assert body["error_domain"] == "input"log_spy.warning.assert_called_once()fields = _emitted_fields(log_spy, as_error=False)- assert fields["status"] == 400- assert fields["error_type"] == "BadRequest"+ assert fields["http.response.status_code"] == 400+ assert fields["error.type"] == "BadRequest"log_spy.error.assert_not_called()- def test_the_summary_message_names_the_status_and_the_error_type(self, mocker: MockerFixture):- # The message is built from server-authored values alone, so it stays a stable sentence- # whatever a caller sent; everything variable is a field beside it.+ def test_the_message_is_fixed_and_the_failure_rides_the_fields(self, mocker: MockerFixture):+ # The message is the same sentence on every error line, at either level, so it is the key a+ # query or an alert selects the error stream by; the status and the error type, which used+ # to be spliced into it, ride fields under their OpenTelemetry keys.log_spy = mocker.patch("pipelex_api.exception_handlers.log")assert _build_client().get("/api-config-error").status_code == 500- assert log_spy.error.call_args.args[0] == "API error 500: ServerMisconfigured"+ assert _build_client().get("/api-input-error").status_code == 422+ assert log_spy.error.call_args.args[0] == "A request ended in an error response"+ assert log_spy.warning.call_args.args[0] == "A request ended in an error response"+ fields = _emitted_fields(log_spy, as_error=True)+ assert fields["http.response.status_code"] == 500+ assert fields["error.type"] == "ServerMisconfigured"+ assert "event" not in fields++ @pytest.mark.parametrize(+ ("path", "expected_backend_name"),+ [+ ("/inference-failure-attributed", "pipelex_gateway"),+ ("/inference-failure-unattributed", None),+ ],+ )+ def test_backend_name_is_only_ever_the_backend_the_error_names(self, mocker: MockerFixture, path: str, expected_backend_name: str | None):+ """The provider the SDK's metadata names, `gateway`, is no backend's name: it is never written under `backend_name`, nor under `sdk`."""+ log_spy = mocker.patch("pipelex_api.exception_handlers.log")+ response = _build_client().get(path)+ assert response.status_code == 500+ fields = _emitted_fields(log_spy, as_error=True)+ assert fields.get("backend_name") == expected_backend_name+ assert "sdk" not in fields+ assert ProviderName.GATEWAY not in fields.values()+ assert fields["provider_status_code"] == 503def test_user_id_rides_authenticated_pipelex_error_record(self, mocker: MockerFixture):# Phase 3 deleted the per-route `log.error(... user=...)` lines on@@ -739,13 +786,13 @@ class TestExceptionHandlers:assert response.status_code == 500log_spy.error.assert_called_once()fields = _emitted_fields(log_spy, as_error=True)- assert fields["user_id"] == _TEST_USER_ID- assert fields["error_type"] == "PipelexConfigError"+ assert fields["user.id"] == _TEST_USER_ID+ assert fields["error.type"] == "PipelexConfigError"def test_user_id_rides_authenticated_api_authored_record(self, mocker: MockerFixture):# `handle_api_error` covers the API-authored 4xx surface (storage's# `raise_bad_request`, `raise_forbidden`, `raise_payload_too_large`;- # uploader's same set). It must ride the same `user_id` correlation+ # uploader's same set). It must ride the same `user.id` correlation# `_log_error_report` does so the contract is uniform — a caller# mistake and a backend failure both name the caller.log_spy = mocker.patch("pipelex_api.exception_handlers.log")@@ -753,31 +800,31 @@ class TestExceptionHandlers:assert response.status_code == 422log_spy.warning.assert_called_once()fields = _emitted_fields(log_spy, as_error=False)- assert fields["user_id"] == _TEST_USER_ID- assert fields["error_type"] == "ValidationError"+ assert fields["user.id"] == _TEST_USER_ID+ assert fields["error.type"] == "ValidationError"def test_user_id_rides_authenticated_unexpected_error_record(self, mocker: MockerFixture):# The catch-all 500 (`handle_unexpected_error`) is the one place a- # missing `user_id` is most expensive — by definition the failure+ # missing `user.id` is most expensive — by definition the failure# was not classifiable upstream — so the same enrichment fires here.log_spy = mocker.patch("pipelex_api.exception_handlers.log")response = _build_client(raise_server_exceptions=False).get("/authenticated-unexpected-error")assert response.status_code == 500log_spy.error.assert_called_once()fields = _emitted_fields(log_spy, as_error=True)- assert fields["user_id"] == _TEST_USER_ID- assert fields["error_type"] == "RuntimeError"+ assert fields["user.id"] == _TEST_USER_ID+ assert fields["error.type"] == "RuntimeError"def test_user_id_absent_from_unauthenticated_error_record(self, mocker: MockerFixture):# Pre-auth paths, and a deployment with no user model, have no `request.state.user`;# `_user_id_of` returns `None` and `_emit_api_error` drops `None`-valued fields, so the- # record carries no `user_id` attribute at all — never a null, which a query filtering on+ # record carries no `user.id` attribute at all — never a null, which a query filtering on# presence would read as an answer.log_spy = mocker.patch("pipelex_api.exception_handlers.log")response = _build_client().get("/config-error")assert response.status_code == 500log_spy.error.assert_called_once()- assert "user_id" not in _emitted_fields(log_spy, as_error=True)+ assert "user.id" not in _emitted_fields(log_spy, as_error=True)def test_run_state_rides_pipelex_error_record(self, mocker: MockerFixture):# `_parse_request` binds `pipe_code` / `pipeline_run_id` on@@ -793,7 +840,7 @@ class TestExceptionHandlers:fields = _emitted_fields(log_spy, as_error=True)assert fields["pipe_code"] == _TEST_PIPE_CODEassert fields["pipeline_run_id"] == _TEST_RUN_ID- assert fields["error_type"] == "PipelexConfigError"+ assert fields["error.type"] == "PipelexConfigError"def test_run_state_rides_api_authored_record(self, mocker: MockerFixture):# API-authored 4xx surface: `raise_validation_error` raised from a@@ -807,7 +854,7 @@ class TestExceptionHandlers:fields = _emitted_fields(log_spy, as_error=False)assert fields["pipe_code"] == _TEST_PIPE_CODEassert fields["pipeline_run_id"] == _TEST_RUN_ID- assert fields["error_type"] == "ValidationError"+ assert fields["error.type"] == "ValidationError"def test_run_state_rides_unexpected_error_record(self, mocker: MockerFixture):# The catch-all 500 is the most operationally expensive case for a@@ -822,7 +869,7 @@ class TestExceptionHandlers:fields = _emitted_fields(log_spy, as_error=True)assert fields["pipe_code"] == _TEST_PIPE_CODEassert fields["pipeline_run_id"] == _TEST_RUN_ID- assert fields["error_type"] == "RuntimeError"+ assert fields["error.type"] == "RuntimeError"def test_run_state_absent_when_parse_request_did_not_bind(self, mocker: MockerFixture):# A route that didn't go through `_parse_request` (here: `/config-error`,@@ -853,9 +900,8 @@ class TestExceptionHandlers:assert response.status_code == 422log_spy.warning.assert_called_once()fields = _emitted_fields(log_spy, as_error=False)- assert fields["event"] == API_ERROR_EVENT- assert fields["status"] == 422- assert fields["error_type"] == "ValidationError"+ assert fields["http.response.status_code"] == 422+ assert fields["error.type"] == "ValidationError"assert fields["error_domain"] == "input"# The summary covers both per-field failures the request triggered.assert "field" in fields["detail"]@@ -890,8 +936,7 @@ class TestExceptionHandlers:assert response.status_code == 422fields = _emitted_fields(log_spy, as_error=False)assert fields["detail"] == crafted_detail, f"the value was altered on the way to the record: {fields['detail']!r}"- assert fields["event"] == API_ERROR_EVENT, "a crafted detail overwrote a legitimate field"- assert fields["status"] == 422, "a crafted detail overwrote a legitimate field"+ assert fields["http.response.status_code"] == 422, "a crafted detail overwrote a legitimate field"message = log_spy.warning.call_args.args[0]assert crafted_detail not in message, f"caller input reached the message: {message!r}"@@ -928,9 +973,8 @@ class TestExceptionHandlers:assert response.status_code == 501log_spy.error.assert_called_once()fields = _emitted_fields(log_spy, as_error=True)- assert fields["event"] == API_ERROR_EVENT- assert fields["status"] == 501- assert fields["error_type"] == "AsyncExecutionNotEnabledError"+ assert fields["http.response.status_code"] == 501+ assert fields["error.type"] == "AsyncExecutionNotEnabledError"assert fields["error_domain"] == "config"def test_pipeline_run_id_conflict_maps_to_409(self):@@ -982,6 +1026,5 @@ class TestExceptionHandlers:log_spy.warning.assert_called_once()log_spy.error.assert_not_called()fields = _emitted_fields(log_spy, as_error=False)- assert fields["event"] == API_ERROR_EVENT- assert fields["status"] == 409- assert fields["error_type"] == "PipelineManagerAlreadyExistsError"+ assert fields["http.response.status_code"] == 409+ assert fields["error.type"] == "PipelineManagerAlreadyExistsError"diff --git a/api/tests/unit/test_method_ref_run.py b/api/tests/unit/test_method_ref_run.pyindex 6f9540764..3db0d4571 100644--- a/api/tests/unit/test_method_ref_run.py+++ b/api/tests/unit/test_method_ref_run.py@@ -9,10 +9,12 @@ execution-locus gate refuses Python where it must, and each resolution failure mdistinct `error_type` + status as RFC 7807 `problem+json`."""+import loggingfrom collections.abc import Callablefrom pathlib import Pathfrom typing import Any+import pytestfrom fastapi import FastAPIfrom fastapi.testclient import TestClientfrom pipelex.methods.exceptions import MethodFetchError@@ -107,6 +109,36 @@ class TestMethodRefRun:"commit_sha": STUB_METHOD_COMMIT_SHA,}+ @pytest.mark.parametrize(+ ("method_ref", "expected_tag"),+ [+ (_METHOD_REF, "v0.1.0"),+ (STUB_METHOD_ADDRESS, None),+ ],+ )+ def test_the_resolution_line_names_the_tag_and_the_commit_the_run_executes(+ self,+ mocker: MockerFixture,+ install_method_package: Callable[..., Path],+ caplog: pytest.LogCaptureFixture,+ method_ref: str,+ expected_tag: str | None,+ ):+ """An operator reads off this line which version of the package a hosted run executed."""+ install_method_package(files={"documents.mthds": VALID_MTHDS})+ client, _ = _build_client(mocker)++ with caplog.at_level(logging.INFO, logger="pipelex_api.method_source"):+ response = client.post("/v1/execute", json={"method_ref": method_ref, "inputs": {"text": "hi"}})++ assert response.status_code == 200, response.text+ (resolution_record,) = [record for record in caplog.records if record.getMessage() == "A method_ref was resolved to a package"]+ record_fields = vars(resolution_record)+ assert record_fields["method_ref"] == method_ref+ assert record_fields["package_address"] == STUB_METHOD_ADDRESS+ assert record_fields["fetched_tag"] == expected_tag+ assert record_fields["commit_sha"] == STUB_METHOD_COMMIT_SHA+def test_request_pipe_code_overrides_manifest_main_pipe(self, mocker: MockerFixture, install_method_package: Callable[..., Path]):install_method_package(files={"documents.mthds": VALID_MTHDS})client, snapshot = _build_client(mocker)diff --git a/api/tests/unit/test_security_no_auth.py b/api/tests/unit/test_security_no_auth.pyindex 0fb87704b..5112df316 100644--- a/api/tests/unit/test_security_no_auth.py+++ b/api/tests/unit/test_security_no_auth.py@@ -1,9 +1,12 @@+import loggingfrom typing import Annotatedimport pytestfrom fastapi import Depends, FastAPIfrom fastapi.testclient import TestClientfrom pipelex.system.storage_scope import SINGLE_TENANT_USER_ID+from pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.log_fields import carried_attributesfrom pytest_mock import MockerFixturefrom pipelex_api.exception_handlers import register_exception_handlers@@ -110,7 +113,7 @@ class TestNoAuthForwardedHeaders:"a:99999", # URI port delimiter],)- def test_path_unsafe_forwarded_user_id_rejected(self, mocker: MockerFixture, unsafe_user_id: str):+ def test_path_unsafe_forwarded_user_id_rejected(self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture, unsafe_user_id: str):r"""A forwarded `X-User-Id` that is not a single path-safe segment fails closed.`user_id` is the owner segment of every storage key, so a value@@ -123,10 +126,21 @@ class TestNoAuthForwardedHeaders:mocker.patch("pipelex_api.security.get_optional_env", return_value="true")client = _build_client()headers: dict[str, str] = {ForwardedIdentityHeader.USER_ID: unsafe_user_id}- response = client.get(RoutePath.WHOAMI, headers=headers)+ with caplog.at_level(logging.WARNING):+ response = client.get(RoutePath.WHOAMI, headers=headers)assert response.status_code == 400assert response.headers["content-type"] == "application/problem+json"assert response.json()["error_type"] == "BadRequest"+ # The refused header names no caller, so it is never logged as `user.id`, nor logged at all: anyone reaching+ # the server could otherwise have any text recorded as a user.+ (record,) = [+ record+ for record in caplog.records+ if record.getMessage() == "A forwarded X-User-Id is not a path-safe segment, and the request is refused"+ ]+ carried = carried_attributes(record=record)+ assert OTelLogAttr.USER_ID not in carried+ assert unsafe_user_id not in carried.values()@pytest.mark.parametrize("opaque_user_id",diff --git a/api/tests/unit/test_security_verifiers.py b/api/tests/unit/test_security_verifiers.pyindex dd9dc3976..787fcd6c7 100644--- a/api/tests/unit/test_security_verifiers.py+++ b/api/tests/unit/test_security_verifiers.py@@ -1,5 +1,6 @@"""Tests for verify_jwt and verify_api_key in api/security."""+import loggingfrom typing import Annotatedimport jwt@@ -7,6 +8,8 @@ import pytestfrom fastapi import Depends, FastAPI, Requestfrom fastapi.testclient import TestClientfrom pipelex.system.storage_scope import SINGLE_TENANT_USER_ID+from pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.log_fields import carried_attributesfrom pytest_mock import MockerFixturefrom pipelex_api.exception_handlers import register_exception_handlers@@ -116,6 +119,37 @@ class TestSecurityVerifiers:assert response.headers["WWW-Authenticate"] == "Bearer"assert response.json()["error_type"] == "InvalidToken"+ @pytest.mark.parametrize(+ ("refused_claim", "expected_claim_type"),+ [+ (42, "int"),+ ({"tenant": "acme"}, "dict"),+ (["acme"], "list"),+ ("../etc/passwd", "str"),+ ],+ )+ def test_a_refused_user_id_claim_is_logged_as_its_type_never_as_user_id(+ self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture, refused_claim: object, expected_claim_type: str+ ):+ """`user.id` names an authenticated caller and is a string on every line; a refused claim is neither.++ The line used to carry the claim as decoded under `user.id`, an integer or an object on some lines, which split+ the field's type, and a value a token issuer put there under a key meaning the caller.+ """+ mocker.patch("pipelex_api.security.get_optional_env", return_value=JWT_SECRET)+ client = _build_jwt_client()+ token = jwt.encode({"user_id": refused_claim}, JWT_SECRET, algorithm="HS256")++ with caplog.at_level(logging.WARNING):+ response = client.get(RoutePath.WHOAMI, headers={"Authorization": f"Bearer {token}"})++ assert response.status_code == 401+ (record,) = [record for record in caplog.records if record.getMessage() == "A JWT's user_id claim is not a path-safe segment"]+ carried = carried_attributes(record=record)+ assert carried.get("claim_type") == expected_claim_type+ assert OTelLogAttr.USER_ID not in carried+ assert refused_claim not in carried.values()+@pytest.mark.parametrize("opaque_user_id",[diff --git a/docs/api-server/logging.md b/docs/api-server/logging.mdindex 531c5ddc3..c9be1a010 100644--- a/docs/api-server/logging.md+++ b/docs/api-server/logging.md@@ -7,12 +7,12 @@ The server writes structured logs: one JSON object per line, on **stderr**, withAn error response produces exactly one line. A caller mistake:```json-{"time": "2026-09-18T13:53:17.919Z", "severity": "WARNING", "logger": "pipelex_api.exception_handlers", "message": "API error 422: InvalidModelCategory", "request_id": "01M2TCP02W04RZG6DTM8AR508C", "event": "api_error", "route": "/v1/models", "error_type": "InvalidModelCategory", "error_domain": "input", "retryable": false, "status": 422, "detail": "Invalid model category. Valid values: extract, img_gen, judgment, llm, search"}+{"time": "2026-09-18T13:53:17.919Z", "severity": "WARNING", "logger": "pipelex_api.exception_handlers", "message": "A request ended in an error response", "request_id": "01M2TCP02W04RZG6DTM8AR508C", "url.path": "/v1/models", "error.type": "InvalidModelCategory", "error_domain": "input", "retryable": false, "http.response.status_code": 422, "detail": "Invalid model category. Valid values: extract, img_gen, judgment, llm, search"}```A server fault looks the same at `ERROR`, and carries the traceback under an `exception` key.-The `message` is a short, stable sentence built from the HTTP status and the error type — both of them values the server chose. Nothing a caller supplied ever reaches it: the caller-facing explanation rides the `detail` field instead, so a body crafted with newlines or quotes cannot break the line or forge a key. Two layers keep the `detail` value safe to write. Before any sink sees a record, the Pipelex runtime's redaction processor replaces a control character in a field's value with its printable escape, so a newline a caller sent reads as `\n` in `detail`, and replaces a credential it recognises, an `Authorization` header's token or an API key, with `[REDACTED]`. The sink then escapes what it writes, so a quote or an `=` stays inside its value. The processor is configured under `[runtime.log.redaction]` and is on by default.+The `message` is the same sentence on every error line, `A request ended in an error response`, whichever failure it reports, so it is the key a query or an alert selects this server's error stream by, following the [log-call conventions](../tools/logging.md#log-call-conventions). Everything about the failure, the HTTP status and the error type included, rides a field of its own, and nothing a caller supplied ever reaches the message: the caller-facing explanation rides the `detail` field instead, so a body crafted with newlines or quotes cannot break the line or forge a key. Two layers keep the `detail` value safe to write. Before any sink sees a record, the Pipelex runtime's redaction processor replaces a control character in a field's value with its printable escape, so a newline a caller sent reads as `\n` in `detail`, and replaces a credential it recognises, an `Authorization` header's token or an API key, with `[REDACTED]`. The sink then escapes what it writes, so a quote or an `=` stays inside its value. The processor is configured under `[runtime.log.redaction]` and is on by default.## The fields a line carries@@ -28,32 +28,47 @@ These keys come from the sink itself and are on every line written by the proces| `trace_id`, `span_id`, `trace_flags` | The process's current OpenTelemetry span, in lowercase hex, when one names a trace. This server registers no tracer and instruments nothing, so as shipped no line carries them; they appear only when the deployment runs it under OpenTelemetry instrumentation of its own that makes a span current || `pipelex.trace_id`, `pipelex.span_id` | The Pipelex span a runtime line was logged in, the pipe's or the LLM call's, in lowercase hex. Present on the runtime's lines inside a live run the runtime traces, which it does when AI span tracing is enabled on your own PostHog; never on the server's own lines, an error line included |-The two pairs name different traces. Pipelex's spans belong to a trace of their own, which only Pipelex's exporters receive, so if you export them to a backend of your own, such as Langfuse, an OTLP collector or your PostHog, join a line to them on `pipelex.trace_id` and `pipelex.span_id`. To gather a run's lines whether or not anything traces, use `request_id` or `pipeline_run_id`. How each sink writes both pairs is in the Pipelex documentation's [trace context](https://docs.pipelex.com/0.69.0/tools/logging/#the-trace-context) section.+The two pairs name different traces. Pipelex's spans belong to a trace of their own, which only Pipelex's exporters receive, so if you export them to a backend of your own, such as Langfuse, an OTLP collector or your PostHog, join a line to them on `pipelex.trace_id` and `pipelex.span_id`. To gather a run's lines whether or not anything traces, use `request_id` or `pipeline_run_id`. How each sink writes both pairs is in the Pipelex documentation's [trace context](../tools/logging.md#the-trace-context) section.`request_id` reaches a line in one of two ways, depending on which process writes it. In this server's own process, the request-id middleware binds it on the runtime's log context for the whole request, so every record emitted there while the request is in flight carries it: the server's own lines, like the example above, and the lines the Pipelex runtime emits from inside a run executed in-process (`orchestration_mode = "direct"`), without any call site passing it along. A run dispatched to a worker, under a distributed `orchestration_mode` such as `temporal`, happens in another process, which that binding does not reach, so the id travels with the run instead: both run routes, `POST /v1/execute` and `POST /v1/start`, put it on the run's metadata, and the worker binds it from there while it runs the run's workflow and activities, so the lines written inside them carry the same id. A line the worker writes outside those bindings does not, such as the one the orchestration SDK logs after an activity has failed. One path does not carry it at all yet: when `POST /v1/validate` dispatches its dry run to a worker, the lines that worker writes for it have no `request_id`. The value is the one echoed in the response's `X-Request-ID` header and in the problem document's `request_id` member, so a caller reporting a failure hands you the key to its log lines.-The remaining keys are what the error handlers attach to an `event: "api_error"` record:+The remaining keys are what the error handlers attach to an error line. The ones OpenTelemetry's semantic conventions define keep their keys verbatim, and the rest are spelled as the runtime's own lines spell them, so a query written for the runtime's lines finds these too:| Key | What it is || --- | --- |-| `event` | Always `api_error` on an error line — the one key a query filters this server's error stream on |-| `route` | The request's URL path |-| `status` | The HTTP status actually sent, including any API-level override |-| `error_type` | The class or `ErrorType` name the response reports |+| `url.path` | The request's URL path |+| `http.response.status_code` | The HTTP status actually sent, including any API-level override |+| `error.type` | The class or `ErrorType` name the response reports, which the response body carries as `error_type` || `error_domain` | `input`, `config`, `runtime`, … — who fixes it || `error_category` | A Pipelex classification, on the failures it classifies; `unknown` on the catch-all 500 || `retryable` | Whether a blind retry can help, when the failure says || `detail` | The operator-facing explanation, the same text the response body carries — on an API-authored failure only, see below |-| `user_id` | The authenticated caller, when auth bound one |+| `user.id` | The authenticated caller, when auth bound one. An identity the server refused, a token's `user_id` claim or a forwarded `X-User-Id` that is not a path-safe segment, is never written under it: the warning about the refusal carries the claim's type as `claim_type`, and no value at all for the header || `pipe_code` | The pipe the request named, on a run route whose body parsed || `pipeline_run_id` | The run the request named, on a run route whose body parsed |-| `provider`, `model`, `provider_status_code`, `provider_request_id` | The inference provider's own identifiers, on a failure that reached one |+| `backend_name`, `model_handle` | The inference backend that served the model and the handle the pipe named it by, on a failure that reached one; the response body carries them as `provider` and `model`. `backend_name` is only ever the backend the error names, which a worker attributes its failure to: a failure no worker attributed carries none, even when the provider's own metadata names who answered, `openai` or `gateway`, since that is neither a backend's name nor an SDK's as the backends configuration spells them, and the record leaves it off rather than write it under `backend_name` or `sdk` |+| `provider_status_code`, `provider_request_id` | The inference provider's own status and request id, on a failure that reached one |A key whose value is not set for this request is **absent** from the line rather than written as `null`, so a query filtering on presence gets an honest answer.-`detail` is the one field whose absence follows the failure's origin rather than the request's shape, and it is worth knowing which way round. A failure this API authored itself — a validation error, an unknown model category — carries `detail` on the record. A failure that arrives as a Pipelex `ErrorReport`, which is most `5xx` and every domain error, does not: the response body still carries a `detail`, but the record does not, because the body's text has been through disclosure redaction and the cause has not. So a `4xx` from that path logs as `API error 422: SomeError` with no explanation and no traceback, and the response is where the explanation is. Build an operator query on `error_type` and `route`, which every line carries, rather than on `detail`.+The record took these keys when the server's lines were brought to the log-call conventions, and it dropped two things it carried before: the `event` key, whose one value, `api_error`, the fixed message now plays the part of, and the message built from the status and the error type, `API error 422: InvalidModelCategory`. A query, a dashboard or an alert written for the earlier record moves to the keys of this one:-Every field in that table is a **record attribute**, which is a different thing from the message. A structured sink — `json` here, and the OTLP sink — writes them beside the message as keys. The Rich console sink shows them after the message as a `key=value` suffix, each value on one line and cut short when long, a handled exception's `error.message` at a far more generous length, and leaves out the run identifiers (`request_id`, `pipeline_run_id`), which a person at a terminal does not need on every line, so `API error 500: PipelexConfigError` is followed by the route, the status and the rest of the fields above. That rendering is for a person reading a terminal; keep `sink = "json"` wherever the lines are read by anything else.+| Earlier record | This record |+| --- | --- |+| `event` = `api_error` | `message` = `A request ended in an error response` |+| `message` = `API error <status>: <error type>` | `message` = `A request ended in an error response`, with `http.response.status_code` and `error.type` |+| `route` | `url.path` |+| `user_id` | `user.id` |+| `error_type` | `error.type` |+| `status` | `http.response.status_code` |+| `provider` | `backend_name` |+| `model` | `model_handle` |++The other keys, `error_domain`, `error_category`, `retryable`, `detail`, `pipe_code`, `pipeline_run_id`, `provider_status_code` and `provider_request_id`, kept their names.++`detail` is the one field whose absence follows the failure's origin rather than the request's shape, and it is worth knowing which way round. A failure this API authored itself — a validation error, an unknown model category — carries `detail` on the record. A failure that arrives as a Pipelex `ErrorReport`, which is most `5xx` and every domain error, does not: the response body still carries a `detail`, but the record does not, because the body's text has been through disclosure redaction and the cause has not. So a `4xx` from that path logs its `error.type` with no explanation and no traceback, and the response is where the explanation is. Build an operator query on `error.type` and `url.path`, which every line carries, rather than on `detail`.++Every field in that table is a **record attribute**, which is a different thing from the message. A structured sink — `json` here, and the OTLP sink — writes them beside the message as keys. The Rich console sink shows them after the message as a `key=value` suffix, each value on one line and cut short when long, a handled exception's `error.message` at a far more generous length, and leaves out the run identifiers (`request_id`, `pipeline_run_id`), which a person at a terminal does not need on every line, so `A request ended in an error response` is followed by the path, the status, the error type and the rest of the fields above. That rendering is for a person reading a terminal; keep `sink = "json"` wherever the lines are read by anything else.Disposition follows the HTTP status, not the error domain: a `4xx` is a caller mistake and logs at `WARNING` without a traceback; a `5xx` is a server fault and logs at `ERROR` with one. See [Error Responses](error-responses.md) for the response side of the same failure.diff --git a/docs/configuration/config-technical/inference-backend-config.md b/docs/configuration/config-technical/inference-backend-config.mdindex 1d2d84660..6a1df848c 100644--- a/docs/configuration/config-technical/inference-backend-config.md+++ b/docs/configuration/config-technical/inference-backend-config.md@@ -691,13 +691,10 @@ Common error types:`pipelex init` writes the backend definitions once and never overwrites a file you already have — which is what keeps your edits, and which also means a file written by an older Pipelex stays on your machine after the model-spec format changes. When a release removes a key, your copy still carries it, and the strict model that reads it refuses.-You do not have to do anything about that at boot. Pipelex reads the migration history for the `inference/backends/` files, carries the out-of-date ones forward **in memory**, and starts with a warning naming each file:+You do not have to do anything about that at boot. Pipelex reads the migration history for the `inference/backends/` files, carries the out-of-date ones forward **in memory**, and starts with a warning line for each file, the file and what the migration history carried forward following the message as fields:```-Your configuration is out of date, and pipelex read it as if it had been migrated:-'~/.pipelex/inference/backends/openai.toml'. What the ledger carried forward: Drop-prompting_target from every backend definition. Nothing was written. Run-`pipelex migrate` to bring the files up to date.+WARNING 🧠: A configuration file is out of date and was read as if it had been migrated, and nothing was written; run `pipelex migrate` to update it file.path=/Users/me/.pipelex/inference/backends/openai.toml migration_steps=["Drop prompting_target from every backend definition"] has_blocked_steps=false```Nothing has been written at that point, so the warning comes back at the next boot until you run the command:diff --git a/docs/contribute/log-calls.md b/docs/contribute/log-calls.mdindex 157973dc0..cc76252eb 100644--- a/docs/contribute/log-calls.md+++ b/docs/contribute/log-calls.md@@ -5,7 +5,7 @@ description: "The guard that holds Pipelex's own log calls to the log-call conve# Log-call guard-Pipelex's log calls follow the [log-call conventions](../tools/logging.md#log-call-conventions): a fixed message, its values in `fields`, no markup. Most of them are for review; the ones that can be read off the source are held by `make check-log-calls` on every call: a message at INFO and above is a literal written at the call, and no message holds Rich markup at any level. This page is the guard's specification. The calls that broke the rules when the guard arrived are listed in a committed baseline that can only shrink, so that new code is held to the conventions from the start while the existing calls are converted.+Pipelex's log calls follow the [log-call conventions](../tools/logging.md#log-call-conventions): a fixed message, its values in `fields`, no markup. Most of them are for review; the ones that can be read off the source are held by `make check-log-calls` on every call: a message at INFO and above is a literal written at the call, and no message holds Rich markup at any level. This page is the guard's specification. The calls that broke the rules when the guard arrived were listed in a committed baseline that can only shrink, so that new code was held to the conventions from the start while the existing calls were converted. Every one of them has been converted since: the baseline lists no call, and since it can only shrink, it stays empty, so every log call is held to the rules.## What it reads@@ -56,19 +56,19 @@ A bracketed word that is no style, `list[int]`, `[Errno 2]` or `items[index]`, i## The baseline-`log_call_baseline.toml`, at the repo root, lists every call that broke a rule when the guard arrived. Its key is the call's file and enclosing qualified name, `<relative_path>::<qualified_name>`, the classes and functions joined by dots, or `<module>` for a call made at module level. Under the key, each call is listed by its **signature**, once per call that carries it. A signature is the call's method, its message's source text with any `**` expansion it cannot read, the rules it breaks between brackets, and, after `where`, every binding the guard read to judge it, sorted, which is every binding that can reach the names it read, a binding it does not read written as what binds it (`<parameter>`, `<for target>`, `<enclosing function>`, `<unbound>`):+`log_call_baseline.toml`, at the repo root, lists the calls exempted from the rules until they are converted. It started with every call that broke one when the guard arrived, and lists none now that they are all converted. Its key is the call's file and enclosing qualified name, `<relative_path>::<qualified_name>`, the classes and functions joined by dots, or `<module>` for a call made at module level. Under the key, each call is listed by its **signature**, once per call that carries it. A signature is the call's method, its message's source text with any `**` expansion it cannot read, the rules it breaks between brackets, and, after `where`, every binding the guard read to judge it, sorted, which is every binding that can reach the names it read, a binding it does not read written as what binds it (`<parameter>`, `<for target>`, `<enclosing function>`, `<unbound>`). In a baseline that still listed calls, two entries would read like these, made up for the example:```tomlversion = 1-["pipelex/methods/fetch_on_miss.py::resolve_address_based_method"]+["pipelex/example/bundle_loader.py::BundleLoader.load"]calls = [- "info: f\"Fetched method '{fetched.full_address}' at commit {fetched.commit_sha} and installed it into '{installed.path}'\" [f-string]",+ "info: f\"Loaded the bundle '{bundle_path}' with {pipe_count} pipes\" [f-string]",]-["pipelex/pipe_run/pipe_run.py::PipeRun._build_pipe_io_artifacts_on_output"]+["pipelex/example/bundle_loader.py::report_load_failure"]calls = [- "warning: message [f-string] where message = f\"Failed to build the I/O artifacts for pipeline_run_id={pipeline_run_id}: {build_error}\"",+ "warning: message [f-string] where message = f\"Could not load the bundle '{bundle_path}': {load_error}\"",]```@@ -101,7 +101,7 @@ A failure lists each call the baseline does not list, at its file and line, with## Converting a call-1. Rewrite the call by the [conventions](../tools/logging.md#log-call-conventions): a fixed message, its values in `fields` under the names of the vocabulary table, a handled exception through `error_fields` at WARNING and below or `include_exception=True` at ERROR and above.+1. Rewrite the call by the [conventions](../tools/logging.md#log-call-conventions): a fixed message, its values in `fields` under the names of the vocabulary table, a handled exception through `error_fields` at WARNING and below or `include_exception=True` at ERROR and above, except one that is re-raised, one that failed while another propagated and a swallowed `ValidationError`, which ride as `error_fields` at every level.2. Run `make check-log-calls`. It reports the call's signature as stale; editing what a listed call logs without converting it reports the old signature as stale and the new one as unlisted.3. Remove the signature, by hand or with `.venv/bin/pipelex-dev check-log-calls --prune`, and commit the file with the change.diff --git a/docs/migration-ledger.md b/docs/migration-ledger.mdindex 147c0a0d1..1882dbed5 100644--- a/docs/migration-ledger.md+++ b/docs/migration-ledger.md@@ -552,14 +552,15 @@ The rules this encodes:- **The retry honours the [schema-version floor](#schema-versions-and-why-every-run-replays-everything).** A file that declares a version below `min_supported_schema_version` is one `pipelex migrate` refuses; the retry declines it through the same predicate rather than carrying it forward under-migrated, and the user's own error — with the `migration` block naming the floor — is what they see.- **The retry never becomes the failure.** Anything that goes wrong inside it — a ledger that will not load, a file that will not parse — makes it decline, and the error the *configuration* produced is what the user sees. Their error names the key to fix; ours would name our packaging. A file that cannot be re-read abandons the whole retry rather than being skipped, because skipping it would drop a layer from the merge and a re-validation that then succeeded would boot on a configuration the user does not have.- **The main configuration's warning waits for the logger.** That configuration is what configures logging, so when its retry succeeds there is no logger yet — the loader parks the warning (`config_manager.take_stale_configuration_warning()`) and the boot emits it right after `log.configure`. The telemetry and service loaders run after that point and warn directly. The warning is the same either way; only *when* it is said moves.-- **The inference backend loader parks its warning too, and for a different reason: a caller, not boot order.** By the time backends load, logging has been configured for a while. What that loader has instead is `pipelex doctor`, which probes the backend files by loading the whole library **once per backend** — so a loader that logged for itself would repeat one stale directory's warning a dozen times in one report. It hands the warning over instead (`take_stale_configuration_warning()`), and the caller that owes the user a copy takes it: the models-manager setup emits exactly one per boot, the doctor's per-backend probe simply never asks, and no abstract interface widens to carry it. One warning per load covering every stale file, not one per file and not one per backend.-- **The warning names `pipelex migrate` only for a file the command would reach.** The retry replays whatever the loader merged, and a loader pointed at a directory of its own — an embedder's `config_dir=`, or this repository's `tests/pipelex_{run_mode}.toml` — merges files [outside the walk](#the-commands). For those the warning says the file is the caller's to update where it lives, and does not name a command that would then report nothing to do; a load that spans both gets both sentences, each naming its own files. Same rule as [the remedy on a validation error](#every-surface-reports-it-the-same-way-and-none-of-them-says-start-over): *a remedy is named only where it would write*. The walk is `config_manager.existing_config_dirs`, which is also where `config_directories_to_migrate` reads it — one derivation, read from both ends, so a boot cannot promise what the command declines. Reach is per *surface*, not per path: the file must sit in the directory **its own surface** owns under one of those roots, so a `telemetry.toml` dropped into `inference/backends/` is out of reach exactly as it was before any surface owned a subdirectory.+- **The inference backend loader parks its warning too, and for a different reason: a caller, not boot order.** By the time backends load, logging has been configured for a while. What that loader has instead is `pipelex doctor`, which probes the backend files by loading the whole library **once per backend** — so a loader that logged for itself would repeat one stale directory's warning a dozen times in one report. It hands the warning over instead (`take_stale_configuration_warning()`), and the caller that owes the user a copy takes it: the models-manager setup emits it exactly once per boot, the doctor's per-backend probe simply never asks, and no abstract interface widens to carry it. One warning per load, not one per backend probe.+- **The warning names `pipelex migrate` only for a file the command would reach.** The retry replays whatever the loader merged, and a loader pointed at a directory of its own — an embedder's `config_dir=`, or this repository's `tests/pipelex_{run_mode}.toml` — merges files [outside the walk](#the-commands). For those the warning says the file is the caller's to update where it lives, and does not name a command that would then report nothing to do; a load that spans both gets both remedies, each on the lines of its own files. Same rule as [the remedy on a validation error](#every-surface-reports-it-the-same-way-and-none-of-them-says-start-over): *a remedy is named only where it would write*. The walk is `config_manager.existing_config_dirs`, which is also where `config_directories_to_migrate` reads it — one derivation, read from both ends, so a boot cannot promise what the command declines. Reach is per *surface*, not per path: the file must sit in the directory **its own surface** owns under one of those roots, so a `telemetry.toml` dropped into `inference/backends/` is out of reach exactly as it was before any surface owned a subdirectory.+- **The warning is a line per stale file.** Each line is a fixed message naming the file's remedy, `pipelex migrate` or an edit where the file lives, with the file in `file.path`, the titles of the ledger steps the replay carried in `migration_steps` and whether one of them is blocked in `has_blocked_steps`. The message follows the [log-call conventions](tools/logging.md#log-call-conventions): the files are values, so they ride fields rather than the text, and a list of paths in one field would be cut short on the console, which writes each field on one line at a fixed width. Everything on the line but the path is ledger text; nothing read from the user's file reaches it.- **The healthy path is untouched.** The replay runs only on the failure path, so a current configuration never reads a ledger, never re-parses a document, and never even imports the migration engine. (Not "never loads tomlkit": the ordinary configuration read has always imported it. What a healthy boot avoids is the second, DOM-level read.) Replay neutrality is what makes the retry free when it does run.- **One shared helper**, called by each configuration-surface loader — and that helper is also where `[meta] schema_version` is stripped. The strip belongs there and **not** in the generic TOML reader, which also reads `.mthds` files, backend definitions and the kit index, none of which reserve that key.**The helper owns the failure path, not the load.** The loaders do different things between their merge and their validate — the main configuration deep-merges programmatic overrides, telemetry substitutes `${VAR}` placeholders, the service configuration does nothing, and the inference backend loader does the most of any of them: it pops `[defaults]` out of the document, splits the header-shaped keys off each remaining root table, and validates the *merge* of the two rather than the document. A helper that owned the whole load would have to be told about every one of them. It is given the surface id and the same ordered path list the loader merged, and it hands back the migrated merge plus a `MigrationPlan` per file; each loader re-runs its own step over that and re-validates. The overrides in particular have to be re-applied by the caller: they are a layer of the *load*, and the replay only ever sees the *files*.-> **A surface whose files are independent documents calls the helper once per file.** The helper deep-merges the paths it is given, which is exactly right for a tier stack: `pipelex.toml` beneath `pipelex_local.toml` beneath `pipelex_override.toml` are layers of one configuration, and the thing that has to validate is their merge. Backend definitions are not layers of anything — `openai.toml` and `portkey.toml` are separate documents that happen to share a directory, and merging them would produce a backend nobody has. So that loader passes one path per call and keeps the results apart, and composes one warning covering every file the round recovered.+> **A surface whose files are independent documents calls the helper once per file.** The helper deep-merges the paths it is given, which is exactly right for a tier stack: `pipelex.toml` beneath `pipelex_local.toml` beneath `pipelex_override.toml` are layers of one configuration, and the thing that has to validate is their merge. Backend definitions are not layers of anything — `openai.toml` and `portkey.toml` are separate documents that happen to share a directory, and merging them would produce a backend nobody has. So that loader passes one path per call and keeps the results apart, and parks one warning covering every file the round recovered.> **The migration engine is imported inside the retry, not at the top of the module, and that is what makes "the healthy path is untouched" literal rather than approximate.** It is not what keeps the boot inside the kernel layer: the engine and the applier it uses (`pipelex.fix_ops`) are both kernel-layer, because the retry runs inside every kernel-layer boot that meets a stale file, so the replay path must load zero interpreter modules just as the healthy one does (see [`hub-layering.md`](contribute/hub-layering.md)). `tests/unit/pipelex/test_runtime_boot_closure.py` boots over a stale file to hold it to that.diff --git a/docs/tools/cli/migrate.md b/docs/tools/cli/migrate.mdindex 32850c104..d8a0bc7ba 100644--- a/docs/tools/cli/migrate.md+++ b/docs/tools/cli/migrate.md@@ -71,7 +71,7 @@ The command exits non-zero when it leaves something for you to look at.## The warning that sends you here-You will usually meet this command through a warning rather than a crash. When a file is out of date in a way the migration history explains, Pipelex boots anyway: it carries the file forward **in memory**, tells you which files it did that for, and points at this command. That covers your inference backend definitions as well as the configuration files proper — a backend file left behind by a model-spec change boots on the models it would have loaded anyway, and the warning arrives with the rest of the model setup. Nothing is written, so the same warning appears at the next boot, and the one after — running `pipelex migrate` is what makes the change to the file and stops it.+You will usually meet this command through a warning rather than a crash. When a file is out of date in a way the migration history explains, Pipelex boots anyway: it carries the file forward **in memory**, tells you which files it did that for, and points at this command. That covers your inference backend definitions as well as the configuration files proper — a backend file left behind by a model-spec change boots on the models it would have loaded anyway, and the warning arrives with the rest of the model setup. Nothing is written, so the same warning appears at the next boot, and the one after — running `pipelex migrate` is what makes the change to the file and stops it. When some of what a file needs cannot be applied for you, the warning says so, and `pipelex migrate` reports those changes for you to make by hand; a file the command does not reach is yours to update where it lives, and its warning says that instead.A file the history cannot explain is a different case, and it still fails the boot with the configuration error itself: tolerance widens what starts, never what is accepted. That error names this command too, though — beside the key it could not accept, it tells you which of your files a migration would touch, what it would carry forward, and what only you can decide.diff --git a/docs/tools/logging.md b/docs/tools/logging.mdindex 70a96628c..04c9d8ae7 100644--- a/docs/tools/logging.md+++ b/docs/tools/logging.md@@ -115,6 +115,8 @@ The context is a `LogContext` with three optional identifiers, `request_id`, `piThe identifiers travel in the payload, and the contextvar is in-process plumbing bound after deserialization and nothing else; it never crosses a process boundary. Each process entry binds from the payload it received:- **A direct-mode run**: `PipeRun.run` binds `request_id` and `pipeline_run_id` from the job's `JobMetadata` for the whole run, delivery included, through `JobMetadata.log_context()`, and releases the binding when the run returns. The metadata a submission builds carries no `pipe_run_id` yet.+- **A delivery**: `DeliveryExecutor.execute` binds `request_id` and `pipeline_run_id` for the length of a delivery, so its storage and webhook lines name the run whether or not its caller bound them, a durable-execution activity delivering a run included; a `request_id` of `None` inherits the one the caller bound.+- **A tracing assembly**: `assemble_tracing` binds `pipeline_run_id`, and the `request_id` of the run metadata it is given, for the length of the assembly, so its lines name the run in the durable-execution activity that runs it, `act_assemble_tracing`, as they do under `PipeRun`.- **Every pipe run**: `live_run_pipe` mints the pipe run's id and binds `pipe_run_id` around the whole of the run, the line announcing it, its span lines and its failure included, so every record emitted during a pipe's run names the run it belongs to, a nested pipe rebinding its own and the outer id coming back when it returns, however it returns. A pipe lifted for absent optional inputs does not run and has no id: its skip line carries the enclosing binding, the parent pipe's or none. This is the binding every orchestration shares, direct or distributed.- **Every kernel step**: each kernel function that takes a `job_metadata` — `run_llm_text`, `run_llm_object`, `generate_object_content`, `run_extract`, `run_search` and `run_img_gen` — binds it for the length of its call, so a program driving the kernel directly gets lines naming the run and the step. Inside the interpreter the operator hands the kernel the `pipe_run_id` that `live_run_pipe` already bound, so this nested binding changes nothing there.- **A kernel-driven run**: the host wraps its run in `PipelexKernel.log_context()`, which binds `request_id` and `pipeline_run_id` and no step. The kernel has no run boundary of its own, so this binding is the host's, and each step's binding merges over it. See [The Pipelex Kernel](../under-the-hood/pipelex-kernel.md#the-log-context).@@ -241,7 +243,7 @@ INFO 🧠: Scanned the inputs file_count=7 source=inbox/march```- **What is shown.** The fields the call attached, in the order it gave them, under the name each landed on (`field_name` for a field called `name`). The run identifiers (`request_id`, `pipeline_run_id`, `pipe_run_id`) are left out, since they are the same on every line of a run and would drown the message, and so is `data`, the structured content the message already renders. Nothing else on the record is shown: neither the stdlib's own attributes, nor Pipelex's marks, nor what a record factory or a third-party library stamped on it.-- **How a value is written.** On one line: a string bare, or quoted when it is empty or holds a space, an `=`, a `"`, a `\` or a character a terminal would act on. Inside the quotes a backslash is written `\\`, a quote `\"` and any character a terminal would act on as its escape (`"line\nbreak"`), so `fields={"a": "b=c"}` prints `a="b=c"` rather than a second pair. A number, a boolean, `None`, a mapping, a list or a pydantic model is written as compact JSON (`true`, `null`, `{"key":"value"}`, `["a","b"]`), and anything else as its text. A value longer than 80 characters is cut short and ends with `…`, except `error.message`, a handled exception's text, which is cut only past 2000 characters, quoted and escaped the same way: its diagnosis, a cause chain or a parse error's location, is what a fragment would lose, while a dependency's raw output, a validation error's every line or git's stderr, would flood the terminal uncut. A key is written the same way, so a field whose name holds a line break, a space, an `=` or an escape sequence is quoted and escaped rather than forging a line or a second pair: `fields={"x=1": 2}` prints `"x=1"=2`. The [redaction](#redaction) has run before the console renders, so a secret is already `[REDACTED]`.+- **How a value is written.** On one line: a string as itself, a number, a boolean, `None`, a mapping, a list or a pydantic model as compact JSON, and anything else as its text. That text is written bare, or quoted when it is empty or holds a space, an `=`, a `"`, a `\` or a character a terminal would act on. Inside the quotes a backslash is written `\\`, a quote `\"` and any character a terminal would act on as its escape (`"line\nbreak"`), so `fields={"a": "b=c"}` prints `a="b=c"` rather than a second pair. A number, a boolean and `None` print bare (`7`, `true`, `null`), and so does a list of numbers (`[1,2]`), while a JSON rendering holding a string holds a quote and is quoted like a string: `["a","b"]` prints `"[\"a\",\"b\"]"`. A value longer than 80 characters is cut short and ends with `…`, its text, a string's or a JSON rendering's, being cut before it is quoted and escaped, so a quoted value keeps both its quotes, no escape is split, and no unbalanced quote or bracket is left whose tail could read as a pair of its own, except `error.message`, a handled exception's text, which is cut only past 2000 characters, quoted and escaped the same way: its diagnosis, a cause chain or a parse error's location, is what a fragment would lose, while a dependency's raw output, a validation error's every line or git's stderr, would flood the terminal uncut. `finding_message`, the text of a PipeDocGen template finding, gets the same generous cut, being the part of its warning a reader acts on. A path, in `file.path`, `file.name`, `backup_path` or `template_file`, is cut at its start instead and begins with `…`, so the file's name stays on the line while the directory every line of a run shares goes. These cuts are the console's alone: every other sink writes each value whole. A key is written the same way, so a field whose name holds a line break, a space, an `=` or an escape sequence is quoted and escaped rather than forging a line or a second pair: `fields={"x=1": 2}` prints `"x=1"=2`. The [redaction](#redaction) has run before the console renders, so a secret is already `[REDACTED]`.- **Never markup.** The suffix is built as styled Rich `Text`, not as a markup string, so a value carrying `[red]x[/red]` prints exactly that.There is no setting to hide the suffix: it carries the values a message used to interpolate, so hiding it would hide what the line is about.@@ -269,7 +271,7 @@ INFO 🧠: ↳ PipeCompose: compose_company → Company```- **The console renders the layout in place of the message**, after the logger's emoji, and every other sink ignores it: the `json`, `otlp` and `gcp` sinks write the plain message, `Pipe run starts`, and the fields, and never the layout's name, which rides the record under a reserved mark. The name is explicit at the call, so rewording the message cannot lose the layout, and it is a `LogLayout` member, so a misspelt one is a type error.-- **Every value is escaped** with Rich's own escape before it is substituted, the values the layout derives included, so a field carrying `[red]x[/red]` prints literally. A value is written on one line and cut short past 80 characters, as in the suffix, except that a string is never quoted.+- **Every value is escaped** with Rich's own escape before it is substituted, the values the layout derives included, so a field carrying `[red]x[/red]` prints literally. A value is written on one line and cut short past 80 characters, as in the suffix, except that it is never quoted, a string or a JSON rendering alike.- **The fields a layout presents are not repeated after it**; any other field the call gave still follows as the suffix, and the run identifiers stay hidden.- **A layout that cannot be filled costs nothing but itself.** A field it needs is missing, a value its derivation refuses, or anything else the layout raises: the console falls back to the message and shows every field after it.- **A layout is for a string message.** A call whose content is anything else, a mapping, a list or a model, keeps its layout off the record, and the console renders its message: the message is the only place that content renders, since the suffix never repeats `data`, and a content JSON refuses, a circular one for instance, lives only in the message's `repr`. A record whose [redaction](#redaction) failed loses its layout too, so the notice saying the scrub failed is what prints.@@ -335,13 +337,13 @@ Every inference call ends with `Inference call ends`, on the logger `pipelex.cog| `backend_name` | string | The backend serving the model || `sdk` | string | The SDK the backend reaches the model through || `gen_ai.request.model` | string | The model requested, its handle, as on the LLM span |-| `gen_ai.response.model` | string | The provider's id of the model serving the call, as on the LLM span |+| `gen_ai.response.model` | string | The provider's id the model deck pins for the handle, the one the call is made with, as on the LLM span || `gen_ai.usage.input_tokens` | integer | The tokens the call read, when it reported them || `gen_ai.usage.output_tokens` | integer | The tokens the call wrote, when it reported them || `cost_usd` | number, in US dollars | What the call cost, when it reported usage and the model has rates || `duration_ms`, `outcome`, `error.type` | | As above |-A handle names one model per model type, so a query groups by `gen_ai.operation.name` and `model_handle` together. The model keys are read when the call ends, so a worker that names its model in the checks before the call is named on the event as on the call's span, and one that learns from the provider which model served the call is named after that model. A print that ended before its handle was resolved, refused by the read scope, or whose handle resolves to no model served here, names the model by its handle alone, under `model_handle` and `gen_ai.request.model`, and leaves off `backend_name`, `sdk` and `gen_ai.response.model`, which only a served model has. The usage is the one the call recorded on its job's report, the object the base hands to `ReportingProtocol.report_inference_job` when it reports the job and the reporting manager turns into a usage event, and the event prices it with `compute_tokens_usage_cost`, the cost engine the usage records and the run's cost report read, so a usage the cost report counts has the same price there as on the event. The event carries what the job recorded, though, and the cost report only what was reported: the search and judgment bases report a job whichever way it ends, while the LLM, image-generation and extraction bases report it only when it succeeds, so a failure of theirs the provider billed carries a cost on the event that the run's cost report does not count. A token count or a cost the call did not record is left off, never written as zero: a call that failed before the provider answered, or that the checks before it refused, recorded no usage, a model with no rates has no price, and a document engine reports no usage at all, so a print carries neither. A failure the provider billed, a search or a judgment whose answer a guard refused, carries the usage it recorded.+A handle names one model per model type, so a query groups by `gen_ai.operation.name` and `model_handle` together. The model keys are read when the call ends, so a worker that names its model in the checks before the call is named on the event as on the call's span. Every worker writes under `gen_ai.response.model` the provider's id the deck pins for the handle, the one the call is made with, and none writes the id a provider answers with: a provider that says another model answered is named on a warning of its own, the TypeSafe judgment worker's, under `answered_model_id`. A print that ended before its handle was resolved, refused by the read scope, or whose handle resolves to no model served here, names the model by its handle alone, under `model_handle` and `gen_ai.request.model`, and leaves off `backend_name`, `sdk` and `gen_ai.response.model`, which only a served model has. The usage is the one the call recorded on its job's report, the object the base hands to `ReportingProtocol.report_inference_job` when it reports the job and the reporting manager turns into a usage event, and the event prices it with `compute_tokens_usage_cost`, the cost engine the usage records and the run's cost report read, so a usage the cost report counts has the same price there as on the event. The event carries what the job recorded, though, and the cost report only what was reported: the search and judgment bases report a job whichever way it ends, while the LLM, image-generation and extraction bases report it only when it succeeds, so a failure of theirs the provider billed carries a cost on the event that the run's cost report does not count. A token count or a cost the call did not record is left off, never written as zero: a call that failed before the provider answered, or that the checks before it refused, recorded no usage, a model with no rates has no price, and a document engine reports no usage at all, so a print carries neither. A failure the provider billed, a search or a judgment whose answer a guard refused, carries the usage it recorded.Rates are per million tokens, so a call billed by the request or by the page records each unit as a million tokens in and out, and the rate table prices one unit: a Linkup search or fetch is one request, and an extraction whose provider reports no usage is priced by its pages. Its usage says so in its `pricing_unit`, `request` or `page` rather than `token`, and the event carries the call's cost and no token counts, since a request or a page is not a token. A worker records such a usage with `record_unit_priced_usage` (`pipelex.cogt.usage.usage_cost`), a plugin's worker as much as a provider's, and never writes the counts itself.@@ -408,7 +410,7 @@ Pipelex's own log calls, in `pipelex/` and in the API server's `api/pipelex_api/A message is a sentence that reads the same on every emission. A log store groups and counts lines by their message, and an interpolated value makes a different string of every line, so a question as plain as "how many of these today" needs a regular expression. The message is the key a query, a dashboard or an alert selects a line by, and Pipelex carries no separate `event` field beside it, so rewording a message is a change made on purpose.-At INFO and above, the message is a literal written at the call: no f-string, no `%`, no `+` and no `.format()`, and no message built elsewhere and passed in, since nothing can tell that one is fixed. DEBUG and VERBOSE may keep an f-string, because a person at a terminal reads them; fields are welcome there too.+At INFO and above, the message is a literal: written at the call, or a module constant holding a literal, as the summary events and `PIPE_RUN_STARTS_MESSAGE` pass theirs, and no f-string, no `%`, no `+`, no `.format()` and no message built elsewhere and passed in, since nothing can tell that one is fixed. DEBUG and VERBOSE may keep an f-string, because a person at a terminal reads them; fields are welcome there too.```python# Not this: the alias makes every line a different message, and the exception is buried in the text@@ -423,40 +425,92 @@ log.warning(### Values in fields-What varies goes in `fields`, named by the [naming convention](#naming-convention), and one concept has one name across the codebase, so that a query written for one line finds every line about the same thing. Pipelex's own concepts take the names in the table below. A concept the OpenTelemetry semantic conventions define takes their key verbatim: `file.path` for a path on disk, `url.full` for a URL, `user.id` for a user, `error.type` for the class of an error, and the `gen_ai.*` keys for inference, such as `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.request.temperature`, `gen_ai.operation.name`, `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. A `gen_ai.*` key means on a log line what it means on Pipelex's LLM span: `gen_ai.request.model` is the model's handle and `gen_ai.response.model` the provider's id of the model serving it. `gen_ai.operation.name` is the one exception for now, as [the inference call end](#the-inference-call-end) explains. A line about an inference call carries them beside `model_handle`, `backend_name` and `sdk`, so it joins its span in a log store, while `model_handle` names the handle on every line about a model, inference or not. A count is named `<what>_count` (`concept_count`) and a duration `duration_ms`, in milliseconds.--| Field | What it names |-| --- | --- |-| `pipe_code` | The pipe a line is about, bare or qualified by its domain, as the call site holds it: `compose_company`, `company.compose_company` |-| `pipe_type` | The pipe's class: `PipeLLM`, `PipeCompose` |-| `pipe_depth` | How deep a pipe run is nested, `0` at the top level |-| `is_dry_run` | Whether the run is a dry run |-| `output_concept` | The concept a pipe produces |-| `concept_ref` | A concept's qualified reference, `<domain>.<Code>`: `company.Company` |-| `concept_code` | A concept's code alone, where the call site has no domain for it: `Company` |-| `domain_code` | A domain's code: `company` |-| `stuff_name` | The name a stuff has in working memory |-| `variable_path` | A dotted path into working memory, as a pipe's inputs name it: `invoice.total` |-| `library_id` | The library a load or a lookup runs in |-| `package_address` | A method package's address, as its manifest declares it or a bundle's reference names it: `github.com/acme/methods/invoices` |-| `dependency_alias` | The alias under which a package's manifest declares a dependency; a dependency a bundle names by address has its address as its alias |-| `method_ref` | The address a caller names a method by, selector and tag included, as the run routes and the CLI take it: `github.com/acme/methods/[email protected]` |-| `commit_sha` | The commit a fetched method package was cloned at |-| `mthds_version_constraint` | The MTHDS standard versions a package accepts, as the `mthds_version` of its `METHODS.toml` declares them: `^4.0.0` |-| `mthds_standard_version` | The MTHDS standard version this runtime implements |-| `mthds_paths` | The `.mthds` files a load reads, as a list of paths |-| `crate_fingerprint` | The fingerprint that identifies a normalized crate in the library it is loaded into |-| `model_handle` | The handle a pipe or the model deck names a model by, an alias included: `gpt-image-2`, `@default-premium` |-| `backend_name` | The inference backend serving a model, as the backends configuration names it: `anthropic`, `bedrock` |-| `sdk` | The SDK a backend reaches a model through, as the backends configuration names it: `openai`, `bedrock_anthropic` |-| `fixed_temperature` | The one temperature a model accepts, as its constraints declare it, used in place of the one requested |-| `cost_usd` | What an inference call cost, in US dollars, as a number, as the cost engine prices the usage it reported |-| `duration_ms` | How long a unit of work took, in milliseconds, as a number |-| `outcome` | How a unit of work ended, `success`, `error` or `cancelled`, on the [summary events](#summary-events) |-| `summary_event` | The [summary event](#summary-events) a line is about, by its message: `Inference call ends` |-| `node_id` | A node of a run's execution graph, as the graph tracer names it |-| `env_var` | The name of an environment variable, never its value |-| `error.type`, `error.message` | A handled exception's class name and its text, as [Exceptions](#exceptions) describes |+What varies goes in `fields`, named by the [naming convention](#naming-convention), and one concept has one name across the codebase, so that a query written for one line finds every line about the same thing. Pipelex's own concepts take the names in the table below. A concept the OpenTelemetry semantic conventions define takes their key verbatim: `file.path` for a path on disk and `file.name` for a file's name alone, `url.full` for a URL and `url.path` for the path of a request's URL, `server.address` for the host a request is sent to, `http.response.status_code` for the status of an HTTP response, `user.id` for the authenticated caller, never an identity the server refused, `error.type` for the class of an error, and the `gen_ai.*` keys for inference, such as `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.request.temperature`, `gen_ai.operation.name`, `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. A `gen_ai.*` key means on a log line what it means on Pipelex's LLM span: `gen_ai.request.model` is the model's handle and `gen_ai.response.model` the provider's id the model deck pins for that handle, the one the call is made with, whichever model the provider says answered. `gen_ai.operation.name` is the one exception for now, as [the inference call end](#the-inference-call-end) explains. A line about an inference call carries them beside `model_handle`, `backend_name` and `sdk`, so it joins its span in a log store, while `model_handle` names the handle on every line about a model, inference or not. An OpenTelemetry key that more than one call site uses is spelled through a constant, so a misspelt one is an error the type checker reports rather than a field no query finds: `OTelLogAttr` in `pipelex/system/telemetry/otel_constants.py` holds those keys, `GenAISpanAttr` beside it the `gen_ai.*` ones, and `pipelex.tools.log.error_fields` the two error keys. A count is named `<what>_count` (`concept_count`) and a duration `duration_ms`, in milliseconds. A field carries one JSON type on every line that has it, `null` aside, so a query compares it one way: where the value would be an integer on some lines and a word on others, `unbounded` for instance, the field is left out of the lines the word would name, and the table says so.++| Field | Type | What it names |+| --- | --- | --- |+| `pipe_code` | string | The pipe a line is about, by its bare code, the value `Pipe run starts` carries for it: `compose_company` |+| `pipe_ref` | string | The pipe a line is about, by its reference qualified by its domain, beside its `pipe_code` where the line keeps both: `company.compose_company`. A qualified reference that resolved to no pipe is carried here as it was named |+| `popped_pipe_code` | string | The pipe taken off a run's pipe stack where the line's `pipe_code` was expected |+| `pipe_type` | string | The pipe's class: `PipeLLM`, `PipeCompose` |+| `pipe_depth` | integer | How deep a pipe run is nested, `0` at the top level |+| `is_dry_run` | boolean | Whether the run is a dry run |+| `item_count` | integer | The number of items a `PipeBatch` fans out over |+| `max_concurrency` | integer | The bound on the branches a `PipeBatch` runs at once; absent when the configuration's `"unbounded"` sets none |+| `threshold` | number | The probability threshold a judgment declares, between `0` and `1` |+| `template_file` | string | A PipeDocGen's template file, as the pipe declares it |+| `finding_message`, `finding_location` | string | The text of a PipeDocGen template finding, and where in the template it was found |+| `function_name` | string | A function PipeFunc registers or calls, by its name |+| `module_name` | string | A Python module's dotted name, as the PipeFunc registry imports or walks it: `myapp.functions` |+| `eligibility_error` | string | Why a function cannot be registered for PipeFunc |+| `output_concept` | string | The concept a pipe produces |+| `concept_ref` | string | A concept's qualified reference, `<domain>.<Code>`: `company.Company` |+| `concept_code` | string | A concept's code alone, where the call site has no domain for it: `Company` |+| `structure_class_name` | string | The Python class a concept's content is structured by, by its name |+| `structure_classes` | string | The Python structure classes a fetched method package declares, as one text naming each file and the classes it defines |+| `domain_code` | string | A domain's code: `company` |+| `metadata_field` | string | A field of a domain's metadata that two declarations of the domain give different values: `description` |+| `established_value`, `incoming_value` | string | The value a domain's metadata field already holds, which is kept, and the different one a later declaration gives |+| `stuff_name` | string | The name a stuff has in working memory |+| `variable_path` | string | A dotted path into working memory, as a pipe's inputs name it: `invoice.total` |+| `variable_names` | list of strings | The names a pipe's inputs give their variables, as a list: the absent inputs a pipe run was skipped for |+| `library_id` | string | The library a load or a lookup runs in |+| `caller` | string | The entry point a shared helper logs on behalf of, as the label it passes: `API validate` |+| `package_address` | string | A method package's address, as its manifest declares it or a bundle's reference names it: `github.com/acme/methods/invoices` |+| `package_version` | string | A method package's version, as its manifest declares it |+| `installed_tag` | string or `null` | The tag an installed method package was fetched at, `null` when it was fetched with no tag |+| `dependency_alias` | string | The alias under which a package's manifest declares a dependency; a dependency a bundle names by address has its address as its alias |+| `method_ref` | string | The address a caller names a method by, selector and tag included, as the run routes and the CLI take it: `github.com/acme/methods/[email protected]` |+| `fetched_tag` | string or `null` | The tag a method package was fetched at for a run, as its `method_ref` named it, `null` when it named none and the default branch was fetched |+| `commit_sha` | string | The commit a fetched method package was cloned at |+| `mthds_version_constraint` | string | The MTHDS standard versions a package accepts, as the `mthds_version` of its `METHODS.toml` declares them: `^4.0.0` |+| `mthds_standard_version` | string | The MTHDS standard version this runtime implements |+| `mthds_paths` | list of strings | The `.mthds` files a load reads, as a list of paths |+| `crate_fingerprint` | string | The fingerprint that identifies a normalized crate in the library it is loaded into |+| `model_handle` | string | The handle a pipe or the model deck names a model by, an alias included: `gpt-image-2`, `@default-premium` |+| `ideal_model_handle`, `fallback_model_handle` | string | A waterfall's first model, which the model deck lacks, and the model that replaces it, by their handles |+| `preset_id` | string | A preset of the model deck, by its id |+| `model_type` | string | The kind of model a line is about, as the model deck names it: `llm`, `img_gen`, `text_extractor` |+| `served_model_types` | list of strings | The kinds of model a model serves, as a list of `model_type` values |+| `matching_reference_kinds` | list of strings | The kinds of model reference a bare model name also names, as a list: `preset`, `alias`, `waterfall` |+| `backend_name` | string | The inference backend serving a model, as the backends configuration names it: `anthropic`, `bedrock` |+| `sdk` | string | The SDK a backend reaches a model through, as the backends configuration names it: `openai`, `bedrock_anthropic` |+| `answered_model_id` | string | The provider's id of the model a provider says answered a call, where it is not the pinned id the call was made with, which `gen_ai.response.model` names |+| `fixed_temperature` | number | The one temperature a model accepts, as its constraints declare it, used in place of the one requested |+| `inference_job_type` | string | An inference job's class: `LLMJob`, `ImgGenJob` |+| `image_size` | string | An image size as a generation request spells it, width by height: `2560x1440` |+| `nb_steps` | integer | The number of inference steps an image generation job requests, spelled as its parameters spell it |+| `cost_usd` | number | What an inference call cost, in US dollars, as the cost engine prices the usage it reported |+| `duration_ms` | number | How long a unit of work took, in milliseconds |+| `outcome` | string | How a unit of work ended, `success`, `error` or `cancelled`, on the [summary events](#summary-events) |+| `summary_event` | string | The [summary event](#summary-events) a line is about, by its message: `Inference call ends`, `Pipe run ends` |+| `node_id` | string | A node of a run's execution graph, as the graph tracer names it |+| `trace_event_type` | string | A trace event's class: `PipeStartEvent` |+| `writer_id`, `workflow_id` | string | The writer and the workflow a trace event names, as the event log records them |+| `tracer_key` | string | The key a graph tracer is registered under |+| `sort_key` | string | The sort key of a trace event's item in DynamoDB |+| `event_count` | integer | The number of events a line is about, telemetry events or trace events |+| `event_name` | string | A telemetry event, by its name |+| `pipelex_version` | string | The version of the Pipelex runtime |+| `integration_mode` | string | How the runtime is run, as the caller declares it: `cli`, `python`, `fastapi` |+| `plugin_name` | string | A plugin, by the name it is registered under |+| `callback_name` | string | A callback a plugin registered, by its module and qualified name: `my_plugin.runtime.release_workers` |+| `override_paths` | list of strings | The override files merged over the base configuration file in `file.path`, as a list of paths |+| `backup_path` | string | The backup a migration writes before it rewrites the file in `file.path` |+| `migration_steps` | list of strings | The titles of the migration ledger's steps a stale configuration file was read through, as a list |+| `has_blocked_steps` | boolean | Whether a stale configuration file needs a migration step that cannot be applied for the user |+| `file_count` | integer | The number of result files a delivery stored |+| `env_var` | string | The name of an environment variable, never its value |+| `default_value` | integer | The value a setting falls back to when its environment variable holds none it can use |+| `auth_mode` | string | The authentication mode the API server's `AUTH_MODE` names |+| `claim_type` | string | The type a token's claim was decoded as, by its Python name, where the claim is refused and its value is not logged: `str`, `int`, `dict` |+| `error.type`, `error.message` | string | A handled exception's class name and its text, as [Exceptions](#exceptions) describes |+| `error_domain` | string | Who fixes a failure, as an error report classifies it: `input`, `config`, `runtime` |+| `error_category` | string | A failure's Pipelex classification, as an error report carries it |+| `retryable` | boolean | Whether retrying the failed call as it was can help, as an error report says |+| `detail` | string | The explanation an API error response gives its caller |+| `provider_status_code` | integer | The HTTP status an inference provider answered a failed call with |+| `provider_request_id` | string | The id an inference provider gave a failed call |`pipe_code`, `pipe_type`, `output_concept`, `concept_ref`, `concept_code`, `domain_code` and `stuff_name` are in the console's [style map](#the-style-map), which colours their values wherever they appear. A concept missing from the table is added to it in the change that first logs it.@@ -464,8 +518,12 @@ What varies goes in `fields`, named by the [naming convention](#naming-conventioAn exception rides the record, never the message. Spliced into the text, `{exc}` makes the message vary, loses the exception's type and traceback, and gets only the pattern half of the [redaction](#redaction), where a field also has its control characters escaped. So:-- **At ERROR and CRITICAL**, inside the `except` block, pass `include_exception=True`: the record carries the exception, and each sink writes its type and its traceback its own way.+- **At ERROR and CRITICAL**, inside the `except` block, pass `include_exception=True`: the record carries the exception, and each sink writes its type and its traceback its own way. That is for an exception the code handles where it logs it, whose traceback nobody else will see, and above all for the catcher of an unexpected failure, the root of a CLI command or the API server's error handler, which logs it there and prints no traceback of its own: the `console` sink renders it under the line, and the `json` and `otlp` sinks write it to the log store, which a traceback printed on the console alone never reaches. A CLI command's root also names the exception's type and message in its own output, which is not a log record, so the terminal says why the command failed whatever the sink and the level, under a `json` sink writing to a file as under a level above ERROR.+- **An exception logged and then re-raised carries no traceback, at ERROR too**: it rides as `error_fields`, since whoever catches it owns its traceback, and a line that carried it as well would print it a second time, ahead of the catcher's own report.+- **A secondary failure carries no traceback either**: a cleanup that fails while another exception propagates, a tracer that will not close, a library that will not tear down, a delivery that fails after the run did, rides as `error_fields`, at ERROR too. Python chains the propagating exception onto it as its context, so its traceback would print the primary's text, a `ValidationError`'s refused input included, under a line that is not about it, while the primary's own catcher reports it. A cleanup that runs either way, a plugin's teardown callback, follows the same rule.+- **A `ValidationError` the code swallows carries no traceback**, at any level: its traceback ends in its own text, which quotes every value it refused, so it rides as `error_fields`, which writes it as below.- **At WARNING and below**, an exception the code expected and handled rides as two fields, `error.type`, its class's name, and `error.message`, its text, with no traceback, through `error_fields` (`pipelex.tools.log.error_fields`): `fields={"package_address": address, **error_fields(exc=exc)}`. A warning promises a degradation that was handled, and a traceback of Pipelex's own frames repeated on every emission of an expected failure says nothing a reader can act on; the facade's `warning` takes no `include_exception` for that reason. Where the diagnosis is the cause chain rather than the exception's own text, as when a fetch fails in git underneath, `error_fields(exc=exc, text=...)` carries the chain instead. The console cuts `error.message` only past 2000 characters, where it cuts every other field's value at 80, so the chain reaches the terminal whole without a dependency's raw output flooding it.+- **A pydantic `ValidationError` never reaches a field as its own text**, which quotes every value it refused, a run's input or a model's response among them: `error_fields` writes it as its locations and reasons alone, `limits.burst: Input should be a valid integer`, whichever line logs it. A reason is pydantic's own message, kept only when nothing in it came from the input: the error is one of pydantic's built-in types, its message is the one pydantic renders, and its context is empty or holds only values the schema gives, a bound such as `max_length`, the values or tags it expects, a discriminator's name, a pattern, a class. Any other error is written as its location and its type alone, `date: value_error`: a custom validator's message, a `value_error`, an `assertion_error` or a `PydanticCustomError`'s, is the validator's text, which can quote the very value it rejected, and several of pydantic's own templates quote the input as well, the unknown tag of a discriminated union (`item: union_tag_invalid`), the character a UUID could not parse, a parser's own complaint. An `extra_forbidden` error is located at its parent, `limits: Extra inputs are not permitted`, or carries no location at the root, since the last part of its location is the key the caller sent. A `text=` given in its place is carried as given.`error.type` is the OpenTelemetry key for the class of error an operation ended with. `error.message` is the key OpenTelemetry gave an error's text before deprecating that general attribute in favour of domain-specific ones; Pipelex keeps it as `error.type`'s companion because the `exception.*` keys belong to the sinks, which write them for a record that carries the exception itself and prefix a field spelling one.@@ -479,7 +537,7 @@ An exception rides the record, never the message. Spliced into the text, `{exc}`The [level table](#log-levels) states what a line at each level means, and choosing the level of a call follows from it. There is no DEV level.-- **ERROR** says a run failed or data was lost, and that somebody should look; it carries the exception with `include_exception=True` when there is one.+- **ERROR** says a run failed or data was lost, and that somebody should look; it carries an exception it handles with `include_exception=True`, and one it re-raises, a secondary failure and a swallowed `ValidationError` as `error_fields`.- **WARNING** must be actionable: a degradation that was handled, or a misconfiguration the user can fix. A warning nobody can act on moves down to DEBUG, or up to ERROR when something was in fact lost.- **INFO** marks a lifecycle milestone, and there are few of them, because Pipelex is also a library and a library says little at INFO. The [summary events](#summary-events) are the one exception in number, an event for each inference call and each live pipe run: they are INFO because the dashboards built from them read the default production level, and a host that wants Pipelex quieter at INFO raises their loggers' level, as that section shows.- **DEBUG** answers a question you would ask on reading a log a user sent: which file was read, which fallback was taken, why a model was left out.diff --git a/log_call_baseline.toml b/log_call_baseline.tomlindex f7139fa78..3022fc9b9 100644--- a/log_call_baseline.toml+++ b/log_call_baseline.toml@@ -5,539 +5,3 @@# Never add an entry: the check refuses a baseline that lists more than its base. See docs/contribute/log-calls.md.version = 1--["api/pipelex_api/bundle.py::_entries_from_zip"]-calls = [- "warning: f\"bundle: corrupt zip ({zip_error})\" [f-string]",- "warning: f\"bundle: invalid base64 ({decode_error})\" [f-string]",-]--["api/pipelex_api/exception_handlers.py::_emit_api_error"]-calls = [- "error: summary [non-literal] where summary = _error_summary(attributes)",- "warning: summary [non-literal] where summary = _error_summary(attributes)",-]--["api/pipelex_api/limits.py::_read_positive_int"]-calls = [- "warning: f\"Invalid {env_var}={raw!r}, falling back to {default}\" [f-string]",- "warning: f\"{env_var} must be positive (got {parsed}), falling back to {default}\" [f-string]",-]--["api/pipelex_api/method_source.py::_fetch_package"]-calls = [- "info: f\"Resolved method_ref '{ref.ref_str}': address={package.provenance.address} tag={package.provenance.tag} commit_sha={package.provenance.commit_sha}\" [f-string]",-]--["api/pipelex_api/security.py::get_auth_mode"]-calls = [- "warning: f\"Unknown AUTH_MODE '{raw}', falling back to 'none'\" [f-string]",-]--["api/pipelex_api/security.py::no_auth"]-calls = [- "warning: f\"Forwarded X-User-Id is not a path-safe segment, rejecting: {user_id!r}\" [f-string]",-]--["api/pipelex_api/security.py::verify_jwt"]-calls = [- "warning: f\"JWT user_id claim is not a path-safe segment: {user_id!r}\" [f-string]",- "warning: f\"JWT validation failed: {exc!s}\" [f-string]",-]--["pipelex/cli/agent_cli/commands/run/_run_core.py::run_pipeline_core"]-calls = [- "warning: f\"Cost summary generation failed (run succeeded): {cost_summary_error}\" [f-string]",-]--["pipelex/cli/commands/doctor_cmd.py::setup_doctor_runtime"]-calls = [- "warning: stale_warning [non-literal] where stale_warning = config_manager.take_stale_configuration_warning()",-]--["pipelex/cli/commands/graph_cmd.py::graph_render_cmd"]-calls = [- "error: f\"Error rendering graph: {exc}\" [f-string]",-]--["pipelex/cli/commands/run/_run_core.py::execute_run"]-calls = [- "error: f\"Error executing pipeline: {exc}\" [f-string]",-]--["pipelex/cli/commands/which_cmd.py::which_cmd"]-calls = [- "info: f\"No library directories to load ({source_label})\" [f-string]",-]--["pipelex/cogt/content_generation/generated_content_factory.py::GeneratedContentFactory.make_image_content"]-calls = [- "warning: f\"Failed to fetch a remote image: {exc}\" [f-string]",-]--["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_inference"]-calls = [- "warning: f\"Number of inference steps {num_inference_steps} for SDXL Lightning must be one of {acceptable_steps}\" [f-string]",-]--["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_prompt"]-calls = [- "warning: f\"A negative prompt was provided but the model's prompt taxonomy is '{PromptTaxonomy.POSITIVE_ONLY}', which does not support negative prompts. The negative prompt will be silently ignored.\" [f-string]",-]--["pipelex/cogt/img_gen/img_gen_gpt_mapping.py::ImgGenGptMapping.validate_gpt_image_2_size"]-calls = [- "warning: msg [f-string] where msg = f\"Size '{size_string}' is valid for OpenAI image model '{model_name}', but it is above the 2560x1440 reliability boundary.\"",-]--["pipelex/cogt/llm/llm_prompt.py::LLMPrompt.validate_before_execution"]-calls = [- "error: f\"Prompt template system_text should be None or contain text. system_text = '{self.system_text}'\" [f-string]",- "warning: f\"system_text should be None or contain text. system_text = '{self.system_text}'\" [f-string]",- "warning: f\"system_text should be None or contain text. system_text = '{self.system_text}'\" [f-string]",-]--["pipelex/cogt/model_backends/backend_library.py::InferenceBackendLibrary.load"]-calls = [- "info: f\"Inference backends read from {library_paths_description}\" [f-string]",-]--["pipelex/cogt/model_routing/routing_profile_loader.py::load_active_routing_profile"]-calls = [- "info: f\"Routing profiles read from {library_description}\" [f-string]",-]--["pipelex/cogt/models/model_deck.py::ModelDeck._get_optional_inference_model"]-calls = [- "warning: f\"Model handle '{ref.name}' is served as {served_types_description} but was requested as '{model_type}'. Skipping.\" [f-string]",-]--["pipelex/cogt/models/model_deck.py::ModelDeck._resolve_alias"]-calls = [- "warning: f\"Circular model reference detected: alias '{alias_name}' leads back to itself\" [f-string]",-]--["pipelex/cogt/models/model_deck.py::ModelDeck._resolve_waterfall"]-calls = [- "info: msg [f-string] where msg += f\" Please see our docs for more details about setting up inference backends:\\n{URLs.backend_provider_docs}\"; msg = f\"Inference model fallback: '{ideal_model_handle}' was not found in the model deck, so it was replaced by '{fallback}'. As a consequence, the results of the method may not have the expected quality, and the method might fail due to feature limitations such as context window size, etc. Consider getting access to '{ideal_model_handle}'.\"",- "warning: f\"Circular model reference detected: waterfall '{waterfall_name}' leads back to itself\" [f-string]",-]--["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_doc_gen"]-calls = [- "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",-]--["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_extract"]-calls = [- "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",-]--["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_img_gen"]-calls = [- "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",-]--["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_judgment"]-calls = [- "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",-]--["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_llm"]-calls = [- "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",-]--["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_search"]-calls = [- "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",-]--["pipelex/cogt/models/model_deck.py::ModelDeck.validate_registered_models"]-calls = [- "warning: f\"DocGen handle not found: {exc}\" [f-string]",- "warning: f\"Extract handle not found: {exc}\" [f-string]",- "warning: f\"ImgGen handle not found: {exc}\" [f-string]",- "warning: f\"Judgment handle not found: {exc}\" [f-string]",- "warning: f\"LLM handle not found: {exc}\" [f-string]",- "warning: f\"Search handle not found: {exc}\" [f-string]",-]--["pipelex/cogt/models/model_manager.py::ModelManager.setup"]-calls = [- "warning: stale_warning [non-literal] where stale_warning = self.inference_backend_library.take_stale_configuration_warning()",-]--["pipelex/cogt/usage/cost_registry.py::CostRegistry.generate_report"]-calls = [- "warning: f\"No report to generate for pipeline '{pipeline_run_id}'\" [f-string]",-]--["pipelex/config.py::is_method_fetch_on_miss_enabled"]-calls = [- "warning: f\"Unrecognized {METHODS_FETCH_ON_MISS_ENV_VAR}={raw_env!r} (expected 1/0, true/false); falling back to the config\" [f-string]",-]--["pipelex/core/concepts/concept_factory.py::_is_valid_structure_class"]-calls = [- "warning: f\"Concept class '{structure_class_name}' is registered but it's not a subclass of StuffContent\" [f-string]",-]--["pipelex/core/memory/working_memory.py::WorkingMemory.add_new_stuff"]-calls = [- "warning: f\"Key '{name}' already exists in WorkingMemory and will be replaced by something different\" [f-string]",- "warning: f\"Key '{name}' already exists in WorkingMemory with the same stuff\" [f-string]",-]--["pipelex/core/memory/working_memory.py::WorkingMemory.validate_stuff_names"]-calls = [- "warning: f\"Stuff key '{key}' starts with '_', which is reserved for params\" [f-string]",- "warning: f\"Stuff name '{stuff.stuff_name}' does not match the key '{key}'\" [f-string]",- "warning: f\"Stuff name '{stuff.stuff_name}' starts with '_', which is reserved for params\" [f-string]",-]--["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.convert_to_working_memory_format"]-calls = [- "warning: f\"Error getting structure class for concept '{named_stuff_spec.concept.code}': {exc}, falling back to TextContent\" [f-string]",-]--["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.make_mock_inputs"]-calls = [- "warning: f\"Failed to create mock for '{typed_named_stuff_spec.variable_name}' ({typed_named_stuff_spec.concept.code}): {exc}. Using fallback text content.\" [f-string]",-]--["pipelex/graph/graph_factory.py::save_graph_outputs_to_dir"]-calls = [- "warning: f\"Removed {file_name} at {file_path}: the graphspec written beside it carries no I/O artifacts of its own\" [f-string]",-]--["pipelex/graph/graph_tracer_manager.py::GraphTracerManager.open_tracer"]-calls = [- "warning: f\"Stale tracer teardown for key '{key}' failed; replacing anyway: {stale_teardown_exc}\" [f-string]",- "warning: f\"Tracer for key '{key}' already exists; replacing stale tracer left by a prior interrupted execution\" [f-string]",-]--["pipelex/kernel/judgment_ops.py::run_judgment"]-calls = [- "warning: f\"Judgment '{job_metadata.pipe_code or 'unnamed step'}' declares a threshold of {threshold}, but model '{judgment_setting.model}' reported no probability, so its own verdict stands.\" [f-string]",-]--["pipelex/kernel/llm_ops.py::concrete_llm_model_handle"]-calls = [- "warning: f\"Cycle resolving model reference '{model}' at '{current}'; reporting it unresolved\" [f-string]",- "warning: f\"Model reference '{model}' did not resolve within {_MAX_MODEL_RESOLUTION_HOPS} hops\" [f-string]",-]--["pipelex/libraries/domain/domain_metadata_merge.py::merge_domain_metadata_field"]-calls = [- "warning: f\"Domain '{domain_code}' declared with different {field_label}s. Keeping the first.\" [f-string]",- "warning: f\"Domain '{domain_code}' declared with different {field_label}s: '{established}' vs '{incoming}'. Keeping the first.\" [f-string]",-]--["pipelex/libraries/library_utils.py::get_pipelex_mthds_files_from_package._find_mthds_in_traversable"]-calls = [- "warning: f\"Could not access {traversable}: {exc}\" [f-string]",-]--["pipelex/libraries/library_utils.py::get_pipelex_package_dir_for_imports"]-calls = [- "warning: f\"Could not convert importlib.resources Traversable to filesystem Path: {exc}\" [f-string]",-]--["pipelex/methods/fetch_limits.py::_read_positive_int"]-calls = [- "warning: f\"Invalid {env_var}={raw!r}, falling back to {default}\" [f-string]",- "warning: f\"{env_var} must be positive (got {parsed}), falling back to {default}\" [f-string]",-]--["pipelex/methods/fetch_on_miss.py::_warn_on_tag_mismatch"]-calls = [- "warning: f\"Method '{ref.address}' is already installed at '{installed.path}' ({installed_desc}) while the reference pins '@{ref.tag}'; using the installed copy. Remove '{installed.path}' to re-fetch at the pinned tag.\" [f-string]",-]--["pipelex/methods/fetch_on_miss.py::find_vendored_method"]-calls = [- "warning: f\"Method '{lookup.ref.address}' is shipped with the request at version {version} while the reference pins '@{lookup.ref.tag}'; using the shipped copy.\" [f-string]",-]--["pipelex/methods/fetch_on_miss.py::resolve_address_based_method"]-calls = [- "info: f\"Fetched method '{fetched.full_address}' at commit {fetched.commit_sha} and installed it into '{installed.path}'\" [f-string]",- "warning: f\"Method '{fetched.full_address}' declares Python structure classes ({details}). It runs locally, but {STRUCTURES_REFUSAL_RULE} — hosted execution would refuse it. {STRUCTURES_REFUSAL_REMEDY}\" [f-string]",-]--["pipelex/migration/runner.py::_discard_backup"]-calls = [- "warning: f\"the backup '{backup.path}' was made for a write that did not happen and could not be removed: {exc.strerror or exc}\" [f-string]",-]--["pipelex/migration/runner.py::_discard_created_backup"]-calls = [- "warning: f\"the backup '{backup.path}' was made for a removal that did not happen and could not be removed: {exc.strerror or exc}\" [f-string]",-]--["pipelex/migration/runner.py::_prune_older_backups"]-calls = [- "warning: f\"'{snapshot.path}' was migrated and backed up to '{backup.path}', but an older backup could not be pruned: {exc.strerror or exc}\" [f-string]",-]--["pipelex/migration/runner.py::write_file_with_backup"]-calls = [- "warning: f\"'{snapshot.path}' was migrated, but the write left something behind: {exc}\" [f-string]",-]--["pipelex/pipe_controllers/batch/pipe_batch.py::PipeBatch._live_run_controller_pipe"]-calls = [- "warning: f\"PipeBatch '{self.code}' is fanning out over {item_count} items. Bounded fan-out (max_concurrency={max_concurrency if max_concurrency is not None else 'unbounded'}) is a basic backpressure effort, not durable execution — for a workload this size, consider a durable execution backend for rate-limited, resumable runs: {URLs.durable_execution}\" [f-string]",-]--["pipelex/pipe_controllers/condition/pipe_condition.py::PipeCondition._dry_run_controller_pipe"]-calls = [- "error: f\"Dry run failed: could not detect required variables from expression template: {exc}\" [f-string]",-]--["pipelex/pipe_machinery/pipe_abstract.py::PipeAbstract._make_lifted_output"]-calls = [- "info: f\"Skipping {self.type} '{self.code}': absent input(s): {absent_names}\" [f-string]",-]--["pipelex/pipe_machinery/pipe_abstract.py::PipeAbstract.validate_pipe_code_syntax"]-calls = [- "warning: f\"Runtime pipe code '{code}' contains a namespace prefix, stripped to '{bare_code}'\" [f-string]",-]--["pipelex/pipe_operators/doc_gen/pipe_doc_gen.py::PipeDocGen.check_template_file"]-calls = [- "warning: f\"PipeDocGen '{self.code}', template file '{self.template_file}'{location}: {finding.message}\" [f-string]",-]--["pipelex/pipe_operators/func/pipe_func.py::PipeFunc._dry_run_operator_pipe"]-calls = [- "info: f\"🚨 For your information, the dry run of PipeFunc '{self.code}' is not actually running the python function but only validating the inputs and return type.\" [f-string]",-]--["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._get_raw_main_absence"]-calls = [- "warning: f\"Malformed main-output absence record in raw working memory, treating as missing: {exc}\" [f-string]",-]--["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._notify_webhook"]-calls = [- "info: f\"Webhook delivery completed: pipeline_run_id={pipeline_run_id}, url={webhook.url}{request_id_suffix}\" [f-string]",-]--["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._resolve_concept_locally"]-calls = [- "warning: f\"Concept ref '{concept_ref}' is ambiguous in the current library, rendering the delivery raw: {exc}\" [f-string]",- "warning: f\"Concept ref '{concept_ref}' is not a valid concept ref, rendering the delivery raw: {exc}\" [f-string]",- "warning: f\"The current library is no longer reachable, rendering the delivery raw: {exc}\" [f-string]",-]--["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._store_results"]-calls = [- "info: f\"Storage delivery completed: pipeline_run_id={pipeline_run_id}, files={len(result_files)}{request_id_suffix}\" [f-string]",-]--["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._try_add_rendered_file"]-calls = [- "warning: f\"Failed to render {filename}\" [f-string]",-]--["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor.try_local_hydrate_stuff"]-calls = [- "warning: f\"Local hydration failed for delivery main stuff, falling back to raw render: 'concept' must be the concept ref string, got {type(concept_ref).__name__}\" [f-string]",- "warning: f\"Local hydration failed for delivery main stuff, falling back to raw render: class '{concept.structure_class_name}' not registered locally\" [f-string]",- "warning: f\"Local hydration failed for delivery main stuff, falling back to raw render: concept '{concept_ref}' not known locally\" [f-string]",- "warning: f\"Local hydration failed for delivery main stuff, falling back to raw render: {exc}\" [f-string]",-]--["pipelex/pipe_run/dry_run_in_process.py::best_effort_graph_spec"]-calls = [- "warning: f\"{log_context}: graph dry-run of '{pipe_ref}' did not produce a graph ({type(graph_error).__name__}: {graph_error}); returning validation result without graph_spec\" [f-string]",-]--["pipelex/pipe_run/pipe_run.py::PipeRun._build_pipe_io_artifacts_on_output"]-calls = [- "warning: message [f-string] where message = f\"Failed to build the I/O artifacts for pipeline_run_id={pipeline_run_id}: {build_error}\"",-]--["pipelex/pipe_run/pipe_run.py::PipeRun._run_bound"]-calls = [- "error: f\"Delivery also failed for pipeline_run_id={pipeline_run_id} after pipe execution failure; raising original execution error. Suppressed delivery error: {delivery_error}\" [f-string]",- "error: f\"Pipe execution failed for pipeline_run_id={pipeline_run_id}: {exc}\" [f-string]",- "error: f\"close_tracer also failed for pipeline_run_id={pipeline_run_id} after pipe execution failure; raising original execution error. Suppressed tracer close error: {tracer_close_error}\" [f-string]",-]--["pipelex/pipe_run/pipe_run_params.py::PipeRunParams.pop_pipe_from_stack"]-calls = [- "error: f\"Pipe code '{pipe_code}' was not the last pipe in the stack, it was '{popped_pipe_code}'\" [f-string]",-]--["pipelex/pipe_run/tracing_assembly.py::assemble_tracing"]-calls = [- "warning: message [f-string] where message = f\"Graph assembly failed for pipeline_run_id={pipeline_run_id}: {validation_error}\"",- "warning: message [f-string] where message = f\"Tracing assembly failed to read events for pipeline_run_id={pipeline_run_id}: {read_error}\"",-]--["pipelex/pipeline/pipeline_run_setup.py::pipeline_run_setup"]-calls = [- "error: f\"close_tracer also failed for pipeline_run_id={pipeline_run_id} during setup-failure cleanup; raising original setup error. Suppressed tracer close error: {tracer_close_error}\" [f-string]",-]--["pipelex/pipeline/validate_in_process.py::_validate_bundles_in_scope"]-calls = [- "error: f\"{log_context}: library teardown also failed after a body error; raising the original error. Suppressed teardown error: {teardown_error}\" [f-string]",-]--["pipelex/plugins/discovery.py::_skip_if_disabled"]-calls = [- "info: f\"Plugin '{name}' is disabled via runtime.plugins.disabled; skipping.\" [f-string]",-]--["pipelex/providers/pypdfium2/pypdfium2_worker.py::Pypdfium2Worker._extract_pages"]-calls = [- "warning: f\"Pypdfium2 does not support native image limiting. Extracted all images then truncated to {max_nb_images}.\" [f-string]",- "warning: f\"Pypdfium2 extracted {original_count} images on page {page_number}, truncated to {len(page_images)} (max_nb_images={max_nb_images})\" [f-string]",-]--["pipelex/providers/typesafe/typesafe_judgment_worker.py::TypesafeJudgmentWorker._warn_if_another_model_answered"]-calls = [- "warning: f\"TypeSafe was asked for judgment model '{self.inference_model.model_id}' and answered as '{response.model}': verdicts and their thresholds may not mean what they meant under the pinned model\" [f-string]",-]--["pipelex/reporting/cost_report_renderer.py::render_run_cost_report"]-calls = [- "warning: f\"Cost report generation failed (run succeeded): {cost_report_error}\" [f-string]",-]--["pipelex/reporting/reporting_manager.py::ReportingManager._emit_best_effort"]-calls = [- "warning: f\"Usage event emit failed; dropping: {exc}\" [f-string]",-]--["pipelex/reporting/reporting_manager.py::ReportingManager._emit_usage_event_runner_fallback"]-calls = [- "warning: f\"Runner-side activity event log construction failed; dropping usage event: {exc}\" [f-string]",-]--["pipelex/reporting/reporting_manager.py::ReportingManager.report_inference_job"]-calls = [- "warning: f\"ReportingManager does not support reporting for inference job type: {type(inference_job).__name__}\" [f-string]",-]--["pipelex/runtime_boot.py::RuntimeBoot.__init__"]-calls = [- "warning: stale_warning [non-literal] where stale_warning = config_manager.take_stale_configuration_warning()",-]--["pipelex/runtime_boot.py::RuntimeBoot._release_after_failed_boot"]-calls = [- "error: f\"Telemetry teardown failed while releasing a failed boot: {telemetry_exc}\" [f-string]",-]--["pipelex/runtime_boot.py::RuntimeBoot._teardown_plugin_callbacks"]-calls = [- "error: f\"A plugin teardown callback failed and was skipped: {teardown_exc}\" [f-string]",-]--["pipelex/system/registries/class_registry_utils.py::ClassRegistryUtils.import_modules_in_folder"]-calls = [- "warning: f\"Syntax error in {python_file}: {exc}\" [f-string]",-]--["pipelex/system/registries/func_registry_utils.py::FuncRegistryUtils._register_funcs_in_file"]-calls = [- "warning: f\"Could not import '{file_path}' while registering PipeFuncs; its functions are unavailable: {exc}\" [f-string]",- "warning: f\"Function '{func_name}' in '{file_path}' has @pipe_func() decorator but is not eligible: {eligibility_error}\" [f-string]",- "warning: f\"Syntax error in {file_path}: {exc}\" [f-string]",-]--["pipelex/system/registries/func_registry_utils.py::FuncRegistryUtils.register_pipe_funcs_from_package"]-calls = [- "warning: f\"Function '{func_name}' in '{modname}' has @pipe_func() decorator but is not eligible: {eligibility_error}\" [f-string]",- "warning: f\"Package {package_name} has no __path__ attribute, cannot walk modules\" [f-string]",-]--["pipelex/system/telemetry/telemetry_loader.py::_telemetry_config_the_ledger_can_explain"]-calls = [- "warning: stale_configuration_warning(plans=replayed.plans, walked_dirs=config_manager.existing_config_dirs) [non-literal]",-]--["pipelex/system/telemetry/telemetry_manager.py::TelemetryManager._handle_transmission_error"]-calls = [- "error: f\"Telemetry transmission error: {error}\" [f-string]",-]--["pipelex/system/telemetry/telemetry_manager.py::TelemetryManager.is_custom_portkey_logging_enabled"]-calls = [- "warning: f\"Disabling Custom Portkey logging (debug mode) because '{OTelConstants.DO_NOT_TRACK_ENV_VAR_KEY}' is set and that setting takes precedence\" [f-string]",-]--["pipelex/system/telemetry/telemetry_manager.py::TelemetryManager.track_event"]-calls = [- "error: f\"Could not track event '{event_name}' as identified because user_id is not set, tracking as anonymous\" [f-string]",-]--["pipelex/tools/misc/dict_utils.py::substitute_nested_in_context"]-calls = [- "error: extra_params, title='extra_params' [non-literal] where extra_params = <parameter>",- "error: extra_params, title='extra_params' [non-literal] where extra_params = <parameter>",- "error: original_context, title='original_context' [non-literal] where original_context = context.copy()",- "error: original_context, title='original_context' [non-literal] where original_context = context.copy()",-]--["pipelex/tracing/activity_event_log.py::ActivityEventLogCache.log_once_runner_fallback_engaged"]-calls = [- "info: f\"Activity-side usage event emission engaged (workflow_id={workflow_id}, writer_id={writer_id}). Activities always emit through the per-process activity event log, by design: activity emissions must never land in the workflow's replay-rebuilt buffer (replay determinism), whether the activity runs co-located with the workflow router or on a separate worker pool.\" [f-string]",-]--["pipelex/tracing/dynamodb_event_log.py::DynamoDBEventLog.read_events"]-calls = [- "warning: f\"Skipping DynamoDB item with missing payload: PK={item.get('PK')}, SK={item.get('SK')}\" [f-string]",- "warning: f\"Skipping unparseable DynamoDB item PK={item.get('PK')} SK={item.get('SK')}: {format_pydantic_validation_error(exc)}\" [f-string]",-]--["pipelex/tracing/graphspec_assembler.py::_AssemblerState._attribute_usage"]-calls = [- "warning: f\"UsageReportEvent for unknown node: {reported_node_id}\" [f-string]",-]--["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_controller_output"]-calls = [- "warning: f\"ControllerOutputEvent for unknown node: {event.node_id}\" [f-string]",-]--["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_execution_data"]-calls = [- "warning: f\"ExecutionDataEvent for unknown node: {event.node_id}\" [f-string]",-]--["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_pipe_end_error"]-calls = [- "warning: f\"PipeEndErrorEvent for unknown node: {event.node_id}\" [f-string]",-]--["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_pipe_end_skipped"]-calls = [- "warning: f\"PipeEndSkippedEvent for unknown node: {event.node_id}\" [f-string]",-]--["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_pipe_end_success"]-calls = [- "warning: f\"PipeEndSuccessEvent for unknown node: {event.node_id}\" [f-string]",-]--["pipelex/tracing/graphspec_assembler.py::_AssemblerState.pass_one"]-calls = [- "warning: f\"Unknown event type: {type(event).__name__}\" [f-string]",-]--["pipelex/tracing/ndjson_event_log.py::NdjsonEventLog.read_events"]-calls = [- "warning: f\"Skipping corrupt line in {ndjson_path}:{line_number} — {validation_error}\" [f-string]",-]--["pipelex/tracing/usage_attribution.py::_walk_subtree"]-calls = [- "warning: f\"Cycle in graph node parentage at '{node_id}'; subtree usage rollup will be incomplete\" [f-string]",-]diff --git a/pipelex/cli/agent_cli/commands/run/_run_core.py b/pipelex/cli/agent_cli/commands/run/_run_core.pyindex 32f973c5c..64995a638 100644--- a/pipelex/cli/agent_cli/commands/run/_run_core.py+++ b/pipelex/cli/agent_cli/commands/run/_run_core.py@@ -17,6 +17,7 @@ from pipelex.core.memory.absence_render import build_absence_html, build_absencefrom pipelex.graph.graph_factory import generate_graph_outputs, save_graph_outputs_to_dirfrom pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.misc.json_utils import clean_json_dumpsif TYPE_CHECKING:@@ -167,7 +168,10 @@ async def run_pipeline_core(try:cost_summary = CostRegistry.build_cost_summary(tokens_usages=pipe_output.tokens_usages)except PipelexError as cost_summary_error:- log.warning(f"Cost summary generation failed (run succeeded): {cost_summary_error}")+ log.warning(+ "The run succeeded but its cost summary could not be built, so the output carries no cost report",+ fields=error_fields(exc=cost_summary_error),+ )else:if cost_summary is not None:side_effects["cost_report"] = cost_summarydiff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.pyindex ba2b1f398..a991d2107 100644--- a/pipelex/cli/commands/doctor_cmd.py+++ b/pipelex/cli/commands/doctor_cmd.py@@ -1601,7 +1601,7 @@ def setup_doctor_runtime(*, log_config_overrides: Mapping[str, Any] | None = Nonruntime_setup = discover_doctor_runtime(log_config=log_config, installs_log_sink=installs_log_sink)runtime_hub.set_pretty_print_mode(mode=log_config.pretty_print_mode)if (stale_warning := config_manager.take_stale_configuration_warning()) is not None:- log.warning(stale_warning)+ stale_warning.emit()return runtime_setupdiff --git a/pipelex/cli/commands/graph_cmd.py b/pipelex/cli/commands/graph_cmd.pyindex 69402efeb..1ffd1aa73 100644--- a/pipelex/cli/commands/graph_cmd.py+++ b/pipelex/cli/commands/graph_cmd.py@@ -19,7 +19,7 @@ from rich.markup import escapefrom pipelex import logfrom pipelex.cli.cli_factory import make_pipelex_for_cli-from pipelex.cli.error_handlers import ErrorContext+from pipelex.cli.error_handlers import ErrorContext, print_unexpected_failurefrom pipelex.config import get_configfrom pipelex.graph.exceptions import GraphSpecValidationErrorfrom pipelex.graph.graph_rendering import render_graph_from_spec@@ -28,6 +28,8 @@ from pipelex.pipelex import Pipelexfrom pipelex.runtime_hub import get_console, get_telemetry_managerfrom pipelex.system.runtime import IntegrationModefrom pipelex.system.telemetry.events import EventName, EventProperty+from pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.misc.chart_utils import FlowchartDirectionfrom pipelex.tools.misc.file_utils import load_text_from_pathfrom pipelex.tools.misc.package_utils import get_package_version@@ -198,8 +200,7 @@ def graph_render_cmd(# would write. No sink reads a log message as markup, so the fields hold the text as written; the# console print below does read markup, and a path may hold brackets, so it prints the text escaped.log.error(- "The graph spec was refused, so no graph was rendered",- fields={"file.path": str(input_file), "error.type": type(spec_error).__name__, "error.message": str(spec_error)},+ "The graph spec was refused, so no graph was rendered", fields={OTelLogAttr.FILE_PATH: str(input_file), **error_fields(exc=spec_error)})console = get_console()console.print(f"\n[bold red]Failed to render graph[/bold red]\n\n{escape(str(spec_error))}\n")@@ -207,10 +208,13 @@ def graph_render_cmd(except Exception as exc:# CLI command root: any unexpected failure is reported to the user and exits non-zero via typer.Exit.- log.error(f"Error rendering graph: {exc}")- console = get_console()- console.print("\n[bold red]Failed to render graph[/bold red]\n")- console.print_exception(show_locals=True)+ # An unexpected failure is a bug, and this is the catcher that owns its traceback, so the traceback rides the+ # log record: the `console` sink renders it under the line, and the `json` and `otlp` sinks write it to the+ # log store, which a traceback printed on the console alone never reached. The CLI's own output names the+ # exception's type and message, so the terminal says why the render failed whatever the sink and the level.+ # The console renders no locals unless the configuration asks it to, since they would print the loaded graph.+ print_unexpected_failure(console=get_console(), title="Failed to render graph", exc=exc)+ log.error("The graph could not be rendered", fields={OTelLogAttr.FILE_PATH: str(input_file)}, include_exception=True)raise typer.Exit(1) from excfinally:diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.pyindex 7e5b2fd0a..54d326f5b 100644--- a/pipelex/cli/commands/run/_run_core.py+++ b/pipelex/cli/commands/run/_run_core.py@@ -23,6 +23,7 @@ from pipelex.cli.error_handlers import (handle_model_choice_error,handle_validate_bundle_error,print_traceback_if_requested,+ print_unexpected_failure,)from pipelex.config import get_configfrom pipelex.core.concepts.exceptions import ConceptValueError@@ -566,10 +567,13 @@ def execute_run(except Exception as exc:# CLI command root: any unexpected failure is reported to the user and exits non-zero via typer.Exit.- log.error(f"Error executing pipeline: {exc}")- console = get_console()- console.print("\n[bold red]Failed to execute pipeline[/bold red]\n")- console.print_exception(show_locals=True)+ # This is the catcher every re-raised failure hands its traceback to, so the traceback rides the log record,+ # where the `console` sink renders it under the line and the `json` and `otlp` sinks write it to the log+ # store; printing it on the console as well would show it twice. The CLI's own output names the exception's+ # type and message, so the terminal says why the run failed whatever the sink and the level. The console+ # renders no locals unless the configuration asks it to, since they hold the run's working memory.+ print_unexpected_failure(console=get_console(), title="Failed to execute pipeline", exc=exc)+ log.error("The pipeline could not be executed", include_exception=True)raise typer.Exit(1) from excfinally:diff --git a/pipelex/cli/commands/which_cmd.py b/pipelex/cli/commands/which_cmd.pyindex 530bcf9c5..5febd1451 100644--- a/pipelex/cli/commands/which_cmd.py+++ b/pipelex/cli/commands/which_cmd.py@@ -100,7 +100,7 @@ def which_cmd(if effective_dirs:library_manager.load_libraries(library_id=library_id, library_dirs=effective_dirs)else:- log.info(f"No library directories to load ({source_label})")+ log.verbose(f"No library directories to load ({source_label})")with get_telemetry_manager().telemetry_context():tag(name=EventProperty.INTEGRATION, value=IntegrationMode.CLI)diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.pyindex 92d233152..b4ddd1a0a 100644--- a/pipelex/cli/error_handlers.py+++ b/pipelex/cli/error_handlers.py@@ -76,6 +76,22 @@ def print_traceback_if_requested(*, console: Console) -> None:console.print(Traceback())+def print_unexpected_failure(*, console: Console, title: str, exc: BaseException) -> None:+ """Print a command's own report of an unexpected failure: the title, then the exception's type and message.++ The catcher logs the failure at ERROR with its traceback, which the `console` sink renders under the line and a+ structured sink writes to its log store. This report is the CLI's output, not a log record, so the terminal names+ the cause whatever the sink and the level: under the `json` sink writing to a file, or a level above ERROR, it is+ the only place the person running the command reads it. It prints no traceback, which the `console` sink already+ shows under the log line.+ """+ exception_text = str(exc)+ cause = f"{type(exc).__name__}: {exception_text}" if exception_text else type(exc).__name__+ console.print(f"\n[bold red]{escape(title)}[/bold red]\n")+ # The cause is plain text, a type such as `list[int]` included, so it is escaped before Rich reads markup in it.+ console.print(f" {escape(cause)}\n")++def display_error_panel(*, console: Console, title: str, fields: list[tuple[str, str]], error_message: str | None, tip: str, links: list[tuple[str, str]]) -> None:diff --git a/pipelex/cogt/content_generation/generated_content_factory.py b/pipelex/cogt/content_generation/generated_content_factory.pyindex 7a0428ff5..68ab05e75 100644--- a/pipelex/cogt/content_generation/generated_content_factory.py+++ b/pipelex/cogt/content_generation/generated_content_factory.py@@ -12,6 +12,7 @@ from pipelex.core.stuffs.page_content import PageContentfrom pipelex.core.stuffs.text_and_images_content import TextAndImagesContentfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.system.storage_scope import GENERATED_CONTENT_LEAF+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.misc.base64_utils import extract_base64_str_from_base64_url_if_possiblefrom pipelex.tools.misc.exceptions import RemoteFileFetchErrorfrom pipelex.tools.misc.file_fetch_utils import fetch_file_and_content_type_from_url_httpx@@ -223,7 +224,7 @@ class GeneratedContentFactory:# so there is nothing to refuse and the URL is kept as it came.actual_bytes, fetched_mime_type = await self._fetch_remote_content(url=url)except RemoteFileFetchError as exc:- log.warning(f"Failed to fetch a remote image: {exc}")+ log.warning("A generated image could not be fetched from its remote URL, so the URL is kept as it came", fields=error_fields(exc=exc))public_url = urlelse:if not declared_mime_type and fetched_mime_type:diff --git a/pipelex/cogt/img_gen/img_gen_args_factory.py b/pipelex/cogt/img_gen/img_gen_args_factory.pyindex fcbd7bb40..033fefdd7 100644--- a/pipelex/cogt/img_gen/img_gen_args_factory.py+++ b/pipelex/cogt/img_gen/img_gen_args_factory.py@@ -269,10 +269,7 @@ class ImgGenArgsFactory:match prompt_taxonomy:case PromptTaxonomy.POSITIVE_ONLY:if negative_text:- log.warning(- f"A negative prompt was provided but the model's prompt taxonomy is '{PromptTaxonomy.POSITIVE_ONLY}', "- "which does not support negative prompts. The negative prompt will be silently ignored."- )+ log.warning("A negative prompt was given to an image model that takes none, so it is ignored")return {"prompt": positive_text}case PromptTaxonomy.WITH_NEGATIVE:args_dict: dict[str, Any] = {"prompt": positive_text}@@ -503,7 +500,10 @@ class ImgGenArgsFactory:acceptable_steps = [1, 2, 4, 8]if num_inference_steps not in acceptable_steps:# TODO: prevent this when building presets and params- log.warning(f"Number of inference steps {num_inference_steps} for SDXL Lightning must be one of {acceptable_steps}")+ log.warning(+ "SDXL Lightning takes 1, 2, 4 or 8 inference steps, so the requested number is replaced by 4",+ fields={"nb_steps": num_inference_steps},+ )num_inference_steps = 4else:num_inference_steps = get_config().inference.img_gen.get_num_inference_steps(diff --git a/pipelex/cogt/img_gen/img_gen_gpt_mapping.py b/pipelex/cogt/img_gen/img_gen_gpt_mapping.pyindex 62769575f..c2da2a8a7 100644--- a/pipelex/cogt/img_gen/img_gen_gpt_mapping.py+++ b/pipelex/cogt/img_gen/img_gen_gpt_mapping.py@@ -184,12 +184,12 @@ class ImgGenGptMapping:raise ImgGenParameterError(msg)if total_pixels > cls.GPT_IMAGE_2_RELIABILITY_PIXELS:- msg = f"Size '{size_string}' is valid for OpenAI image model '{model_name}', but it is above the 2560x1440 reliability boundary."+ size_fields = {"model_handle": model_name, "image_size": size_string}if is_tier_derived:# A tier is a portable request, not a hand-picked size: note it quietly.- log.verbose(msg)+ log.verbose("The image size a tier derives is above the model's 2560x1440 reliability boundary", fields=size_fields)else:- log.warning(msg)+ log.warning("The requested image size is valid but above the model's 2560x1440 reliability boundary", fields=size_fields)@classmethoddef moderation_literal(cls, *, is_moderated: bool | None) -> GptImageModerationType | None:diff --git a/pipelex/cogt/llm/llm_prompt.py b/pipelex/cogt/llm/llm_prompt.pyindex 87ea5b095..9d9bb7649 100644--- a/pipelex/cogt/llm/llm_prompt.py+++ b/pipelex/cogt/llm/llm_prompt.py@@ -38,7 +38,7 @@ class LLMPrompt(BaseModel):case ProblemReaction.RAISE:if not is_none_or_has_text(text=self.system_text):if self.system_text == "":- log.warning(f"system_text should be None or contain text. system_text = '{self.system_text}'")+ log.debug("The prompt's system text is empty, so it is treated as absent")else:msg = "system_text should be None or contain text"raise LLMPromptParameterError(msg)@@ -48,9 +48,9 @@ class LLMPrompt(BaseModel):case ProblemReaction.LOG:if not is_none_or_has_text(text=self.system_text):if self.system_text == "":- log.warning(f"system_text should be None or contain text. system_text = '{self.system_text}'")+ log.debug("The prompt's system text is empty, so it is treated as absent")else:- log.error(f"Prompt template system_text should be None or contain text. system_text = '{self.system_text}'")+ log.error("The prompt's system text has no letter or digit in it; it should be absent or contain text")if not is_not_none_and_has_text(text=self.user_text):log.error("user_text should contain text")diff --git a/pipelex/cogt/model_backends/backend_library.py b/pipelex/cogt/model_backends/backend_library.pyindex 64dcddc70..55fbeeaba 100644--- a/pipelex/cogt/model_backends/backend_library.py+++ b/pipelex/cogt/model_backends/backend_library.py@@ -45,10 +45,12 @@ from pipelex.plugins.plugin_model_declarations import PluginModelDeclarationsfrom pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.configuration.config_surface import (INFERENCE_BACKEND_CONFIG_SURFACE_ID,+ StaleConfigurationWarning,replay_surface_files_in_memory,stale_configuration_warning,)from pipelex.system.runtime import runtime_manager+from pipelex.system.telemetry.otel_constants import OTelLogAttrfrom pipelex.tools.misc.dict_utils import (apply_to_strings_recursive,)@@ -109,7 +111,7 @@ def backend_toml_path(*, backends_dir_path: str, backend_name: str) -> Path:class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):root: InferenceBackendLibraryRoot = Field(default_factory=dict)- _stale_warning: str | None = PrivateAttr(default=None)+ _stale_warning: StaleConfigurationWarning | None = PrivateAttr(default=None)def reset(self):self.root = {}@@ -119,14 +121,14 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):def make_empty(cls) -> Self:return cls(root={})- def take_stale_configuration_warning(self) -> str | None:+ def take_stale_configuration_warning(self) -> StaleConfigurationWarning | None:"""The warning a tolerated load owes the user, once — or `None` when every file was current.Parked rather than logged, and the reason is a caller rather than boot order: `pipelexdoctor` probes the backend files by loading the whole library once per backend, so a loaderthat logged for itself would repeat the same warning a dozen times over one stale directory.- Handing it over instead lets each caller decide — `ModelManager.setup` emits it (one boot,- one warning), and the doctor's per-backend probe simply never asks.+ Handing it over instead lets each caller decide — `ModelManager.setup` emits it once per+ boot, a line per stale file, and the doctor's per-backend probe simply never asks."""warning, self._stale_warning = self._stale_warning, Nonereturn warning@@ -145,10 +147,11 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):**A file left behind by a schema change is carried forward rather than fatal.** When a localper-backend TOML is refused, the `inference-backend` ledger is replayed over that one file**in memory** and the loader's own steps re-run over what comes back; a load that then- succeeds parks a warning (`take_stale_configuration_warning`) naming the files and the- `pipelex migrate` remedy. Nothing is written — only the explicit command writes, which is- why the warning keeps coming back until it is run. A file the ledger cannot explain raises- exactly what it raised before: the retry either recovers or gets out of the way.+ succeeds parks a warning (`take_stale_configuration_warning`) naming each file and its+ remedy, `pipelex migrate` where the command reaches the file. Nothing is written — only the+ explicit command writes, which is why the warning keeps coming back until it is run. A file+ the ledger cannot explain raises exactly what it raised before: the retry either recovers or+ gets out of the way.The warning names the files *this* load merged, which is not always every file the commandwould repair: `backends_dir_path` picks one directory (a project's `.pipelex/` wins the whole@@ -191,9 +194,15 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):# the boot's own clause for that names the file; a raw parse error would not reach it.msg = f"Invalid inference backend library {library_paths_description}: {toml_exc}"raise InferenceBackendLibraryValidationError(msg) from toml_exc- if present_toml_override_paths(paths=backends_library_paths):+ if override_paths := present_toml_override_paths(paths=backends_library_paths):# The one trace a machine-wide override leaves: which files this boot actually merged.- log.info(f"Inference backends read from {library_paths_description}")+ log.info(+ "The inference backends were read with override files merged over the base",+ fields={+ OTelLogAttr.FILE_PATH: str(backends_library_paths[0]),+ "override_paths": [str(override_path) for override_path in override_paths],+ },+ )# Create a partial function with the secrets provider boundsubstitute_vars_with_provider = partial(substitute_vars, secrets_provider=secrets_provider)@@ -330,9 +339,8 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):)self.root[backend_name] = backend- # One warning for the whole load rather than one per backend: a schema change lands on every- # file of the directory at once, and a user reading a dozen warnings would learn nothing the- # first did not already say.+ # One warning parked for the whole load, emitted once by the caller that owes it to the user:+ # the doctor's per-backend probe loads this directory once per backend and never asks for it.self._stale_warning = stale_configuration_warning(plans=stale_plans, walked_dirs=config_manager.existing_config_dirs) if stale_plans else None@classmethoddiff --git a/pipelex/cogt/model_routing/routing_profile_loader.py b/pipelex/cogt/model_routing/routing_profile_loader.pyindex 4909603aa..0f4968754 100644--- a/pipelex/cogt/model_routing/routing_profile_loader.py+++ b/pipelex/cogt/model_routing/routing_profile_loader.py@@ -7,6 +7,7 @@ from pipelex import logfrom pipelex.cogt.exceptions import RoutingProfileDisabledBackendError, RoutingProfileLibraryError, RoutingProfileLibraryNotFoundErrorfrom pipelex.cogt.model_routing.routing_profile import RoutingProfilefrom pipelex.cogt.model_routing.routing_profile_factory import RoutingProfileFactory, RoutingProfileLibraryBlueprint+from pipelex.system.telemetry.otel_constants import OTelLogAttrfrom pipelex.tools.misc.exceptions import TomlErrorfrom pipelex.tools.misc.toml_utils import describe_toml_base_and_overrides, load_toml_from_base_and_overrides, present_toml_override_pathsfrom pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error@@ -45,8 +46,14 @@ def load_active_routing_profile(except TomlError as toml_exc:msg = f"Invalid routing profile library {library_description}: {toml_exc}"raise RoutingProfileLibraryError(msg) from toml_exc- if present_toml_override_paths(paths=routing_profile_library_paths):- log.info(f"Routing profiles read from {library_description}")+ if override_paths := present_toml_override_paths(paths=routing_profile_library_paths):+ log.info(+ "The routing profiles were read with override files merged over the base",+ fields={+ OTelLogAttr.FILE_PATH: str(routing_profile_library_paths[0]),+ "override_paths": [str(override_path) for override_path in override_paths],+ },+ )# Validate the routing profile library configurationtry:diff --git a/pipelex/cogt/models/model_deck.py b/pipelex/cogt/models/model_deck.pyindex 4eb505023..9601dc8ce 100644--- a/pipelex/cogt/models/model_deck.py+++ b/pipelex/cogt/models/model_deck.py@@ -1,4 +1,4 @@-from collections.abc import Mapping+from collections.abc import Container, Mappingfrom typing import NoReturn, Selffrom pydantic import Field, PrivateAttr, field_validator, model_validator@@ -8,6 +8,7 @@ from pipelex.cogt.config_cogt import ModelDeckConfigfrom pipelex.cogt.doc_gen.doc_gen_format import DocGenFormat, DocGenSource, doc_gen_choice_key, parse_doc_gen_choice_keyfrom pipelex.cogt.doc_gen.doc_gen_setting import DocGenModelChoice, DocGenSettingfrom pipelex.cogt.exceptions import (+ CogtError,DocGenHandleNotFoundError,ExtractHandleNotFoundError,ImgGenHandleNotFoundError,@@ -47,11 +48,45 @@ from pipelex.cogt.search.search_setting import SearchModelChoice, SearchSettingfrom pipelex.system.configuration.config_model import ConfigModelfrom pipelex.system.exceptions import ConfigValidationErrorfrom pipelex.system.runtime import ProblemReaction+from pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.urls import URLsLLM_PRESET_DISABLED = "disabled"+def _warn_if_ambiguous_bare_handle(+ *,+ name: str,+ model_type: ModelType,+ presets: Container[str],+ aliases: Container[str],+ waterfalls: Container[str],+) -> None:+ """Warn when a bare name, read as a direct model handle, also names a preset, an alias or a waterfall of its model type."""+ matching_reference_kinds: list[ModelReferenceKind] = []+ if name in presets:+ matching_reference_kinds.append(ModelReferenceKind.PRESET)+ if name in aliases:+ matching_reference_kinds.append(ModelReferenceKind.ALIAS)+ if name in waterfalls:+ matching_reference_kinds.append(ModelReferenceKind.WATERFALL)+ if matching_reference_kinds:+ log.warning(+ "A bare model name also names a preset, an alias or a waterfall, and is read as a direct model handle; "+ "prefix it ($ or preset:, @ or alias:, ~ or waterfall:) to avoid the ambiguity",+ fields={"model_handle": name, "model_type": model_type, "matching_reference_kinds": matching_reference_kinds},+ )+++def _warn_of_unresolvable_preset(*, model_type: ModelType, preset_id: str, model_handle: str | None, exc: CogtError) -> None:+ """Warn that a preset names a model the deck cannot resolve, for a deck whose `missing_presets_reaction` is to log it."""+ log.warning(+ "A preset of the model deck names a model the deck cannot resolve",+ fields={"model_type": model_type, "preset_id": preset_id, "model_handle": model_handle, **error_fields(exc=exc)},+ )++class LLMDeckBlueprint(ConfigModel):aliases: dict[str, str] = Field(default_factory=dict)waterfalls: dict[str, list[str]] = Field(default_factory=dict)@@ -315,87 +350,47 @@ class ModelDeck(ConfigModel):def _warn_if_ambiguous_llm(self, name: str) -> None:"""Log a warning if a bare string handle matches presets/aliases/waterfalls."""- matches: list[str] = []- if name in self.llm_presets:- matches.append(f"LLM preset (use ${name} or preset:{name})")- if name in self.llm_aliases:- matches.append(f"alias (use @{name} or alias:{name})")- if name in self.llm_waterfalls:- matches.append(f"waterfall (use ~{name} or waterfall:{name})")- if matches:- log.warning(- f"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity."- )+ _warn_if_ambiguous_bare_handle(+ name=name, model_type=ModelType.LLM, presets=self.llm_presets, aliases=self.llm_aliases, waterfalls=self.llm_waterfalls+ )def _warn_if_ambiguous_extract(self, name: str) -> None:"""Log a warning if a bare string handle matches presets/aliases/waterfalls."""- matches: list[str] = []- if name in self.extract_presets:- matches.append(f"extract preset (use ${name} or preset:{name})")- if name in self.extract_aliases:- matches.append(f"alias (use @{name} or alias:{name})")- if name in self.extract_waterfalls:- matches.append(f"waterfall (use ~{name} or waterfall:{name})")- if matches:- log.warning(- f"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity."- )+ _warn_if_ambiguous_bare_handle(+ name=name,+ model_type=ModelType.TEXT_EXTRACTOR,+ presets=self.extract_presets,+ aliases=self.extract_aliases,+ waterfalls=self.extract_waterfalls,+ )def _warn_if_ambiguous_img_gen(self, name: str) -> None:"""Log a warning if a bare string handle matches presets/aliases/waterfalls."""- matches: list[str] = []- if name in self.img_gen_presets:- matches.append(f"image generation preset (use ${name} or preset:{name})")- if name in self.img_gen_aliases:- matches.append(f"alias (use @{name} or alias:{name})")- if name in self.img_gen_waterfalls:- matches.append(f"waterfall (use ~{name} or waterfall:{name})")- if matches:- log.warning(- f"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity."- )+ _warn_if_ambiguous_bare_handle(+ name=name, model_type=ModelType.IMG_GEN, presets=self.img_gen_presets, aliases=self.img_gen_aliases, waterfalls=self.img_gen_waterfalls+ )def _warn_if_ambiguous_search(self, name: str) -> None:"""Log a warning if a bare string handle matches presets/aliases/waterfalls."""- matches: list[str] = []- if name in self.search_presets:- matches.append(f"search preset (use ${name} or preset:{name})")- if name in self.search_aliases:- matches.append(f"alias (use @{name} or alias:{name})")- if name in self.search_waterfalls:- matches.append(f"waterfall (use ~{name} or waterfall:{name})")- if matches:- log.warning(- f"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity."- )+ _warn_if_ambiguous_bare_handle(+ name=name, model_type=ModelType.SEARCH, presets=self.search_presets, aliases=self.search_aliases, waterfalls=self.search_waterfalls+ )def _warn_if_ambiguous_doc_gen(self, name: str) -> None:"""Log a warning if a bare string handle matches presets/aliases/waterfalls."""- matches: list[str] = []- if name in self.doc_gen_presets:- matches.append(f"doc gen preset (use ${name} or preset:{name})")- if name in self.doc_gen_aliases:- matches.append(f"alias (use @{name} or alias:{name})")- if name in self.doc_gen_waterfalls:- matches.append(f"waterfall (use ~{name} or waterfall:{name})")- if matches:- log.warning(- f"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity."- )+ _warn_if_ambiguous_bare_handle(+ name=name, model_type=ModelType.DOC_GEN, presets=self.doc_gen_presets, aliases=self.doc_gen_aliases, waterfalls=self.doc_gen_waterfalls+ )def _warn_if_ambiguous_judgment(self, name: str) -> None:"""Log a warning if a bare string handle matches presets/aliases/waterfalls."""- matches: list[str] = []- if name in self.judgment_presets:- matches.append(f"judgment preset (use ${name} or preset:{name})")- if name in self.judgment_aliases:- matches.append(f"alias (use @{name} or alias:{name})")- if name in self.judgment_waterfalls:- matches.append(f"waterfall (use ~{name} or waterfall:{name})")- if matches:- log.warning(- f"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity."- )+ _warn_if_ambiguous_bare_handle(+ name=name,+ model_type=ModelType.JUDGMENT,+ presets=self.judgment_presets,+ aliases=self.judgment_aliases,+ waterfalls=self.judgment_waterfalls,+ )def _raise_handle_not_found_error(self,@@ -921,7 +916,7 @@ class ModelDeck(ConfigModel):enabled_backends=exc.enabled_backends,) from exccase ProblemReaction.LOG:- log.warning(f"LLM handle not found: {exc}")+ _warn_of_unresolvable_preset(model_type=ModelType.LLM, preset_id=exc.preset_id, model_handle=exc.model_handle, exc=exc)case ProblemReaction.NONE:passtry:@@ -937,7 +932,7 @@ class ModelDeck(ConfigModel):model_handle=exc.model_handle,) from exccase ProblemReaction.LOG:- log.warning(f"ImgGen handle not found: {exc}")+ _warn_of_unresolvable_preset(model_type=ModelType.IMG_GEN, preset_id=exc.preset_id, model_handle=exc.model_handle, exc=exc)case ProblemReaction.NONE:passtry:@@ -953,7 +948,7 @@ class ModelDeck(ConfigModel):model_handle=exc.model_handle,) from exccase ProblemReaction.LOG:- log.warning(f"Extract handle not found: {exc}")+ _warn_of_unresolvable_preset(model_type=ModelType.TEXT_EXTRACTOR, preset_id=exc.preset_id, model_handle=exc.model_handle, exc=exc)case ProblemReaction.NONE:passtry:@@ -969,7 +964,7 @@ class ModelDeck(ConfigModel):model_handle=exc.model_handle,) from exccase ProblemReaction.LOG:- log.warning(f"Search handle not found: {exc}")+ _warn_of_unresolvable_preset(model_type=ModelType.SEARCH, preset_id=exc.preset_id, model_handle=exc.model_handle, exc=exc)case ProblemReaction.NONE:passtry:@@ -985,7 +980,7 @@ class ModelDeck(ConfigModel):model_handle=exc.model_handle,) from exccase ProblemReaction.LOG:- log.warning(f"DocGen handle not found: {exc}")+ _warn_of_unresolvable_preset(model_type=ModelType.DOC_GEN, preset_id=exc.preset_id, model_handle=exc.model_handle, exc=exc)case ProblemReaction.NONE:passtry:@@ -1001,7 +996,7 @@ class ModelDeck(ConfigModel):model_handle=exc.model_handle,) from exccase ProblemReaction.LOG:- log.warning(f"Judgment handle not found: {exc}")+ _warn_of_unresolvable_preset(model_type=ModelType.JUDGMENT, preset_id=exc.preset_id, model_handle=exc.model_handle, exc=exc)case ProblemReaction.NONE:pass@@ -1032,7 +1027,7 @@ class ModelDeck(ConfigModel):waterfall_key = f"{NAMESPACE_WATERFALL}{waterfall_name}"if waterfall_key in visited:if not is_quiet:- log.warning(f"Circular model reference detected: waterfall '{waterfall_name}' leads back to itself")+ log.warning("A model waterfall leads back to itself, so it resolves to no model", fields={"model_handle": waterfall_key})return Nonestep_visited = visited | {waterfall_key}ideal_model_handle = fallback_list[0]@@ -1069,15 +1064,17 @@ class ModelDeck(ConfigModel):# which would otherwise use up the notice the next real fallback owes its run.if fallback_index > 0 and not is_quiet and waterfall_name not in self._logged_fallback_warnings:# Waterfall success: we explain what happened in the logs- msg = (- f"Inference model fallback: '{ideal_model_handle}' was not found in the model deck, "- f"so it was replaced by '{fallback}'. "- f"As a consequence, the results of the method may not have the expected quality, "- f"and the method might fail due to feature limitations such as context window size, etc. "- f"Consider getting access to '{ideal_model_handle}'."+ log.info(+ "A waterfall's first model is not in the model deck, so a fallback model replaces it; the results may not have "+ "the expected quality, and the method may hit feature limits such as the context window. Consider getting access "+ "to the first model",+ fields={+ "model_handle": waterfall_key,+ "ideal_model_handle": ideal_model_handle,+ "fallback_model_handle": fallback,+ OTelLogAttr.URL_FULL: URLs.backend_provider_docs,+ },)- msg += f" Please see our docs for more details about setting up inference backends:\n{URLs.backend_provider_docs}"- log.info(msg)# Mark this warning as logged for this waterfall_nameself._logged_fallback_warnings.add(waterfall_name)return inference_model@@ -1100,7 +1097,7 @@ class ModelDeck(ConfigModel):alias_key = f"{NAMESPACE_ALIAS}{alias_name}"if alias_key in visited:if not is_quiet:- log.warning(f"Circular model reference detected: alias '{alias_name}' leads back to itself")+ log.warning("A model alias leads back to itself, so it resolves to no model", fields={"model_handle": alias_key})return Noneif not is_quiet:log.verbose(f"Alias '{alias_name}' -> '{alias_target}'")@@ -1224,8 +1221,10 @@ class ModelDeck(ConfigModel):if is_quiet:return Noneif served_types := self.inference_models.types_serving(handle=ref.name):- served_types_description = ", ".join(f"'{served_type}'" for served_type in served_types)- log.warning(f"Model handle '{ref.name}' is served as {served_types_description} but was requested as '{model_type}'. Skipping.")+ log.warning(+ "A model handle is served as another model type than the one requested, so it is skipped",+ fields={"model_handle": ref.name, "model_type": model_type, "served_model_types": served_types},+ )return Nonelog.verbose(f"Skipping model handle '{model_handle}' because it was not found in the model deck, it could be an external plugin.")return Nonediff --git a/pipelex/cogt/models/model_manager.py b/pipelex/cogt/models/model_manager.pyindex 15664213d..eb6fcd231 100644--- a/pipelex/cogt/models/model_manager.py+++ b/pipelex/cogt/models/model_manager.py@@ -108,7 +108,7 @@ class ModelManager(ModelManagerAbstract):# repeat one directory's warning a dozen times. This is the boot that owes the user the# single copy, and by here logging is configured.if (stale_warning := self.inference_backend_library.take_stale_configuration_warning()) is not None:- log.warning(stale_warning)+ stale_warning.emit()# The plugins' internal models join the internal backend before anything reads the library, so routing# and the deck see them exactly as they see a model `internal.toml` declares.has_internal_backend = self.inference_backend_library.merge_plugin_internal_models(diff --git a/pipelex/cogt/usage/cost_registry.py b/pipelex/cogt/usage/cost_registry.pyindex b2423c175..7a52af905 100644--- a/pipelex/cogt/usage/cost_registry.py+++ b/pipelex/cogt/usage/cost_registry.py@@ -81,7 +81,7 @@ class CostRegistry(RootModel[CostRegistryRoot]):):if not tokens_usages:if pipeline_run_id != "untitled":- log.warning(f"No report to generate for pipeline '{pipeline_run_id}'")+ log.debug("No cost report to generate: the run recorded no token usage")returncls.render_report(cls.aggregate_costs(tokens_usages=tokens_usages),diff --git a/pipelex/config.py b/pipelex/config.pyindex 001904104..6f68de84f 100644--- a/pipelex/config.py+++ b/pipelex/config.py@@ -50,7 +50,10 @@ def is_method_fetch_on_miss_enabled() -> bool:return Trueif normalized in _ENV_FALSY:return False- log.warning(f"Unrecognized {METHODS_FETCH_ON_MISS_ENV_VAR}={raw_env!r} (expected 1/0, true/false); falling back to the config")+ log.warning(+ "An environment variable holds no recognized boolean (1/0, true/false, yes/no, on/off), so it is ignored and the config decides",+ fields={"env_var": METHODS_FETCH_ON_MISS_ENV_VAR},+ )optional_config = get_optional_config()if not isinstance(optional_config, PipelexConfig):return Truediff --git a/pipelex/core/concepts/concept_factory.py b/pipelex/core/concepts/concept_factory.pyindex 5afa89b83..af07fdbf3 100644--- a/pipelex/core/concepts/concept_factory.py+++ b/pipelex/core/concepts/concept_factory.py@@ -35,7 +35,10 @@ def _is_valid_structure_class(*, structure_class_name: str) -> bool:if get_class_registry().has_subclass(name=structure_class_name, base_class=StuffContent):return Trueif get_class_registry().has_class(name=structure_class_name):- log.warning(f"Concept class '{structure_class_name}' is registered but it's not a subclass of StuffContent")+ log.warning(+ "A class registered under a concept's structure class name is not a StuffContent subclass, so the concept does not use it",+ fields={"structure_class_name": structure_class_name},+ )return Falsediff --git a/pipelex/core/memory/working_memory.py b/pipelex/core/memory/working_memory.pyindex 06d54ff9f..5e31ddd8c 100644--- a/pipelex/core/memory/working_memory.py+++ b/pipelex/core/memory/working_memory.py@@ -44,6 +44,9 @@ BATCH_ITEM_STUFF_NAME = "BATCH_ITEM"PRIVATE_BINDING_NAME_PREFIX = "_bound_"PRETTY_PRINT_MAX_LENGTH = 1000TEST_DUMMY_NAME = "dummy_result"+# What working memory logs when a name is bound anew to a different stuff. A sequence may rebind a name on purpose, so the+# line is a DEBUG one; a test watching for an unexpected replacement reads it by this constant.+STUFF_REPLACED_MESSAGE = "A name already in working memory is bound to a different stuff, which replaces the one it held"StuffDict = dict[str, Stuff]StuffArtefactDict = dict[str, StuffArtefact]@@ -67,14 +70,16 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):def validate_stuff_names(self) -> Self:for key, stuff in self.root.items():if _is_reserved_for_params(name=key):- log.warning(f"Stuff key '{key}' starts with '_', which is reserved for params")+ log.warning("A stuff name starts with an underscore, which is reserved for params", fields={"stuff_name": key})if not stuff.stuff_name:self.root[key].stuff_name = keyelif key not in {MAIN_STUFF_NAME, stuff.stuff_name}:- log.warning(f"Stuff name '{stuff.stuff_name}' does not match the key '{key}'")- elif _is_reserved_for_params(name=stuff.stuff_name):- log.warning(f"Stuff name '{stuff.stuff_name}' starts with '_', which is reserved for params")+ # Nothing for a user to act on: the key is the name the stuff is read by.+ log.debug(f"Stuff name '{stuff.stuff_name}' does not match the key '{key}'")+ elif key == MAIN_STUFF_NAME and _is_reserved_for_params(name=stuff.stuff_name):+ # A stuff stored under its own name was warned about by its key, above; the main stuff's own name is the one left.+ log.warning("A stuff name starts with an underscore, which is reserved for params", fields={"stuff_name": stuff.stuff_name})return self@@ -224,10 +229,10 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):if name in self.root or name in self.aliases:existing_stuff = self.get_stuff(name=name)if existing_stuff == stuff and name != TEST_DUMMY_NAME:- log.warning(f"Key '{name}' already exists in WorkingMemory with the same stuff")+ log.debug("A stuff is added under a name it is already bound to, so working memory is unchanged", fields={"stuff_name": name})returnelif name != TEST_DUMMY_NAME:- log.warning(f"Key '{name}' already exists in WorkingMemory and will be replaced by something different")+ log.debug(STUFF_REPLACED_MESSAGE, fields={"stuff_name": name})# it's a new stuffself.set_stuff(name=name, stuff=stuff)diff --git a/pipelex/core/memory/working_memory_factory.py b/pipelex/core/memory/working_memory_factory.pyindex d0e8ba203..fee3b4581 100644--- a/pipelex/core/memory/working_memory_factory.py+++ b/pipelex/core/memory/working_memory_factory.py@@ -19,6 +19,7 @@ from pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.core.stuffs.stuff_factory import StuffFactoryfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.runtime_hub import get_class_registry+from pipelex.tools.log.error_fields import error_fields# Field names whose mocked values must be snake_case codes, as MTHDS domain and pipe codes areSNAKE_CASE_FIELD_NAMES = {"domain", "domain_code", "pipe_code"}@@ -172,7 +173,14 @@ class WorkingMemoryFactory(BaseModel):except ValidationError as exc:# Fallback to TextContent when the typed stuff spec fails pydantic validation- log.warning(f"Error getting structure class for concept '{named_stuff_spec.concept.code}': {exc}, falling back to TextContent")+ log.warning(+ "The structure class of an input's concept could not be used, so the input is mocked as text",+ fields={+ "stuff_name": named_stuff_spec.variable_name,+ "concept_ref": named_stuff_spec.concept.concept_ref,+ **error_fields(exc=exc),+ },+ )text_typed_named_stuff_spec = TypedNamedStuffSpec.make_from_named(named=named_stuff_spec,structure_class=TextContent,@@ -275,8 +283,12 @@ class WorkingMemoryFactory(BaseModel):# Mock build (polyfactory) or content validation (pydantic) failed for this dynamic# class — fall back to text content. Unexpected errors propagate.log.warning(- f"Failed to create mock for '{typed_named_stuff_spec.variable_name}' ({typed_named_stuff_spec.concept.code}): "- f"{exc}. Using fallback text content."+ "A mock input could not be built from its concept's structure, so a text stand-in is used",+ fields={+ "stuff_name": typed_named_stuff_spec.variable_name,+ "concept_ref": typed_named_stuff_spec.concept.concept_ref,+ **error_fields(exc=exc),+ },)# Create fallback text contentfallback_content = TextContent(diff --git a/pipelex/graph/graph_factory.py b/pipelex/graph/graph_factory.pyindex 98689018f..8cac0c727 100644--- a/pipelex/graph/graph_factory.py+++ b/pipelex/graph/graph_factory.py@@ -20,6 +20,7 @@ from pipelex.core.pipes.pipe_io_artifacts import (from pipelex.graph.mermaidflow.mermaid_html import render_mermaid_html_async, render_mermaid_html_with_data_asyncfrom pipelex.graph.mermaidflow.mermaidflow_factory import MermaidflowFactoryfrom pipelex.graph.reactflow.reactflow_html import generate_reactflow_html_async+from pipelex.system.telemetry.otel_constants import OTelLogAttrfrom pipelex.tools.misc.string_utils import snake_to_title_caseif TYPE_CHECKING:@@ -204,7 +205,10 @@ def save_graph_outputs_to_dir(# directory would describe this graph's data with another method's declarations. Said out# loud, because the agent CLI's directory is the user's own bundle directory.file_path.unlink()- log.warning(f"Removed {file_name} at {file_path}: the graphspec written beside it carries no I/O artifacts of its own")+ log.warning(+ "Removed an I/O artifact an earlier run left beside the graphspec, which carries none of its own",+ fields={OTelLogAttr.FILE_PATH: str(file_path)},+ )if graph_outputs.mermaidflow_mmd is not None:file_path = output_dir / "mermaidflow.mmd"diff --git a/pipelex/graph/graph_tracer_manager.py b/pipelex/graph/graph_tracer_manager.pyindex 9388f2340..7e0705db7 100644--- a/pipelex/graph/graph_tracer_manager.py+++ b/pipelex/graph/graph_tracer_manager.py@@ -11,6 +11,7 @@ from pipelex.graph.graphspec import GraphSpec, GraphSpecMode, IOSpec, NodeKindfrom pipelex.system.data_inclusion_config import DataInclusionConfigfrom pipelex.system.registries.singleton import ABCSingletonMeta, MetaSingletonfrom pipelex.system.trace_context import TraceContext+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tracing.event_log_protocol import EventLogProtocol # ruff: ignore[typing-only-first-party-import] - used in open_tracer signature@@ -145,7 +146,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):# value is ambiguous (None both when no tracer existed and when a costs-only tracer# legitimately tears down without a GraphSpec).if key in self._tracers:- log.warning(f"Tracer for key '{key}' already exists; replacing stale tracer left by a prior interrupted execution")+ log.warning("Replacing a graph tracer left over by an interrupted execution whose cleanup never ran", fields={"tracer_key": key})try:self.close_tracer(key)except Exception as stale_teardown_exc: # ruff: ignore[blind-except]@@ -154,7 +155,10 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):# fail the fresh run's setup (that would be the M1 class again: worker-local# leak state deciding setup success). close_tracer pops before tearing down,# so the key is free either way.- log.warning(f"Stale tracer teardown for key '{key}' failed; replacing anyway: {stale_teardown_exc}")+ log.warning(+ "The teardown of a stale graph tracer raised; replacing it anyway",+ fields={"tracer_key": key, **error_fields(exc=stale_teardown_exc)},+ )tracer = GraphTracer()diff --git a/pipelex/kernel/judgment_ops.py b/pipelex/kernel/judgment_ops.pyindex 49ce7414e..97acd7bdf 100644--- a/pipelex/kernel/judgment_ops.py+++ b/pipelex/kernel/judgment_ops.py@@ -160,8 +160,8 @@ async def run_judgment(content, threshold_applied = make_verdict_content(answer=answer, threshold=threshold, is_dry=cogt_run_params.run_mode.is_dry)if threshold_applied is False:log.warning(- f"Judgment '{job_metadata.pipe_code or 'unnamed step'}' declares a threshold of {threshold}, but model "- f"'{judgment_setting.model}' reported no probability, so its own verdict stands."+ "A judgment declares a threshold, but its model reported no probability, so the model's own verdict stands",+ fields={"pipe_code": job_metadata.pipe_code, "threshold": threshold, "model_handle": judgment_setting.model},)return JudgmentResult(memory=store_result(memory=memory, concept=concept, content=content, result_name=result_name, result_code=result_code),diff --git a/pipelex/kernel/llm_ops.py b/pipelex/kernel/llm_ops.pyindex 4002e83ea..d37a9c371 100644--- a/pipelex/kernel/llm_ops.py+++ b/pipelex/kernel/llm_ops.py@@ -161,7 +161,12 @@ def concrete_llm_model_handle(model: str) -> str:match reference.kind:case ModelReferenceKind.PRESET | ModelReferenceKind.ALIAS:if current in seen:- log.warning(f"Cycle resolving model reference '{model}' at '{current}'; reporting it unresolved")+ # DEBUG, not WARNING: this only feeds a display field, and a run that uses the reference meets+ # the same deck through the model deck's own resolution, which reports it there+ log.debug(+ "A model reference leads back to itself, so it is reported unresolved",+ fields={"model_handle": model, "revisited_model_handle": current},+ )return currentseen.add(current)try:@@ -173,7 +178,10 @@ def concrete_llm_model_handle(model: str) -> str:current = setting.modelcase ModelReferenceKind.WATERFALL | ModelReferenceKind.HANDLE:return current- log.warning(f"Model reference '{model}' did not resolve within {_MAX_MODEL_RESOLUTION_HOPS} hops")+ log.debug(+ "A model reference did not resolve within the hop limit, so it is reported unresolved",+ fields={"model_handle": model, "hop_count": _MAX_MODEL_RESOLUTION_HOPS},+ )return currentdiff --git a/pipelex/kit/agent_rules/python_standards.md b/pipelex/kit/agent_rules/python_standards.mdindex 8e7edf79f..79a68098d 100644--- a/pipelex/kit/agent_rules/python_standards.md+++ b/pipelex/kit/agent_rules/python_standards.md@@ -75,7 +75,7 @@pretty_print(output_object, title="Your first Pipelex output")```- Both handle formatting json using Rich, pretty_print makes it prettier.-- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.+- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text; an exception logged and then re-raised rides as `**error_fields(exc=exc)` at every level, its traceback being its catcher's to print, and so do a cleanup's failure while another exception propagates, whose traceback would chain the primary's text, and a swallowed pydantic `ValidationError`, whose traceback quotes the values it refused. The catcher of an unexpected failure, a CLI command's root or the API's error handler, logs it at ERROR with `include_exception=True` and prints no traceback of its own; a CLI command's root also prints the exception's type and message in its own output (`print_unexpected_failure` in `pipelex.cli.error_handlers`), so the terminal names the cause whatever the sink and the level. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.### StrEnum and Self typediff --git a/pipelex/libraries/domain/domain_library.py b/pipelex/libraries/domain/domain_library.pyindex fb9160a1a..f5b3987bc 100644--- a/pipelex/libraries/domain/domain_library.py+++ b/pipelex/libraries/domain/domain_library.py@@ -42,14 +42,14 @@ class DomainLibrary(RootModel[DomainLibraryRoot], DomainLibraryAbstract):existing = self.root[domain_code]existing.description = merge_domain_metadata_field(domain_code=domain_code,- field_label="description",+ metadata_field="description",established=existing.description,incoming=domain.description,show_values_on_conflict=True,)existing.system_prompt = merge_domain_metadata_field(domain_code=domain_code,- field_label="system_prompt",+ metadata_field="system_prompt",established=existing.system_prompt,incoming=domain.system_prompt,show_values_on_conflict=False,diff --git a/pipelex/libraries/domain/domain_metadata_merge.py b/pipelex/libraries/domain/domain_metadata_merge.pyindex 650569baf..43c247e8f 100644--- a/pipelex/libraries/domain/domain_metadata_merge.py+++ b/pipelex/libraries/domain/domain_metadata_merge.py@@ -4,7 +4,7 @@ from pipelex import logdef merge_domain_metadata_field(*,domain_code: str,- field_label: str,+ metadata_field: str,established: str | None,incoming: str | None,show_values_on_conflict: bool,@@ -26,13 +26,13 @@ def merge_domain_metadata_field(- both non-empty and different -> keep the first, **warn** (a genuine double-declaration the author should resolve).Args:- domain_code: The domain these values belong to (used in the warning message).- field_label: Singular human-readable field name used in the warning, pluralized with "s"- (e.g. "description" -> "descriptions", "system_prompt" -> "system_prompts").+ domain_code: The domain these values belong to, named in the warning.+ metadata_field: The name of the domain's field being merged ("description", "system_prompt", "main_pipe"),+ named in the warning.established: The value already merged for this domain (may be empty/None).incoming: The value from the file being merged now (may be empty/None).- show_values_on_conflict: Whether to include both values in the conflict warning. True for short- fields (description); False for long ones (system_prompt) whose contents would flood the log.+ show_values_on_conflict: Whether the conflict warning carries both values as fields. True for short+ fields (description); False for a prompt (system_prompt), whose contents a log line never carries.Returns:The merged value (the established value wins on a genuine conflict).@@ -42,12 +42,8 @@ def merge_domain_metadata_field(if not established:return incomingif established != incoming:+ conflict_fields: dict[str, str] = {"domain_code": domain_code, "metadata_field": metadata_field}if show_values_on_conflict:- log.warning(- f"Domain '{domain_code}' declared with different {field_label}s: '{established}' vs '{incoming}'. Keeping the first.",- )- else:- log.warning(- f"Domain '{domain_code}' declared with different {field_label}s. Keeping the first.",- )+ conflict_fields.update(established_value=established, incoming_value=incoming)+ log.warning("Two declarations of one domain give one of its fields different values, so the first is kept", fields=conflict_fields)return establisheddiff --git a/pipelex/libraries/library_crate_factory.py b/pipelex/libraries/library_crate_factory.pyindex f4bc74986..0e26f614b 100644--- a/pipelex/libraries/library_crate_factory.py+++ b/pipelex/libraries/library_crate_factory.py@@ -85,7 +85,7 @@ class LibraryCrateFactory:existing.description = (merge_domain_metadata_field(domain_code=domain_code,- field_label="description",+ metadata_field="description",established=existing.description,incoming=blueprint.description,show_values_on_conflict=True,@@ -94,14 +94,14 @@ class LibraryCrateFactory:)existing.system_prompt = merge_domain_metadata_field(domain_code=domain_code,- field_label="system_prompt",+ metadata_field="system_prompt",established=existing.system_prompt,incoming=blueprint.system_prompt,show_values_on_conflict=False,)existing.main_pipe = merge_domain_metadata_field(domain_code=domain_code,- field_label="main_pipe",+ metadata_field="main_pipe",established=existing.main_pipe,incoming=blueprint.main_pipe,show_values_on_conflict=True,diff --git a/pipelex/libraries/library_utils.py b/pipelex/libraries/library_utils.pyindex cf8e2ac26..d61898969 100644--- a/pipelex/libraries/library_utils.py+++ b/pipelex/libraries/library_utils.py@@ -5,6 +5,8 @@ from pathlib import Pathfrom pipelex import logfrom pipelex.config import get_configfrom pipelex.mthds_parsing.helpers import MTHDS_EXTENSION, is_pipelex_file+from pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.misc.file_utils import find_files_in_dir@@ -35,7 +37,10 @@ def get_pipelex_mthds_files_from_package() -> list[Path]:if child.name not in excluded_dirs:_find_mthds_in_traversable(child, collected=collected)except (PermissionError, OSError) as exc:- log.warning(f"Could not access {traversable}: {exc}")+ log.warning(+ "A directory of the pipelex package could not be read, so its MTHDS files are left out",+ fields={OTelLogAttr.FILE_PATH: str(traversable), **error_fields(exc=exc)},+ )_find_mthds_in_traversable(pipelex_package, collected=mthds_files)log.verbose(f"Found {len(mthds_files)} MTHDS files in pipelex package")@@ -55,7 +60,9 @@ def get_pipelex_package_dir_for_imports() -> Path | None:if pkg_path.exists() and pkg_path.is_dir():return pkg_pathexcept (TypeError, ValueError, OSError) as exc:- log.warning(f"Could not convert importlib.resources Traversable to filesystem Path: {exc}")+ log.warning(+ "The pipelex package is not a directory on the filesystem, so its modules cannot be imported from it", fields=error_fields(exc=exc)+ )return Nonediff --git a/pipelex/methods/fetch_limits.py b/pipelex/methods/fetch_limits.pyindex 8e30bb03d..12855cffc 100644--- a/pipelex/methods/fetch_limits.py+++ b/pipelex/methods/fetch_limits.py@@ -5,8 +5,7 @@ bounded here rather than trusted. Values are read once at import time — a chana process restart. The pattern mirrors the request-size ceilings of `pipelex-api`."""-from pipelex import log-from pipelex.system.environment import get_optional_env+from pipelex.system.environment import get_positive_int_envDEFAULT_MAX_FETCHED_PACKAGE_FILES = 256DEFAULT_MAX_FETCHED_PACKAGE_TOTAL_KIB = 8 * 1024 # 8 MiB across the selected package@@ -14,24 +13,9 @@ DEFAULT_MAX_MANIFEST_FILE_KIB = 256 # per METHODS.toml read during package locaDEFAULT_MAX_SCANNED_MANIFESTS = 100 # METHODS.toml files considered per fetched repository-def _read_positive_int(*, env_var: str, default: int) -> int:- raw = get_optional_env(env_var)- if not raw:- return default- try:- parsed = int(raw)- except ValueError:- log.warning(f"Invalid {env_var}={raw!r}, falling back to {default}")- return default- if parsed <= 0:- log.warning(f"{env_var} must be positive (got {parsed}), falling back to {default}")- return default- return parsed---MAX_FETCHED_PACKAGE_FILES = _read_positive_int(env_var="PIPELEX_MAX_FETCHED_PACKAGE_FILES", default=DEFAULT_MAX_FETCHED_PACKAGE_FILES)+MAX_FETCHED_PACKAGE_FILES = get_positive_int_env(env_var="PIPELEX_MAX_FETCHED_PACKAGE_FILES", default=DEFAULT_MAX_FETCHED_PACKAGE_FILES)MAX_FETCHED_PACKAGE_TOTAL_BYTES = (- _read_positive_int(env_var="PIPELEX_MAX_FETCHED_PACKAGE_TOTAL_KIB", default=DEFAULT_MAX_FETCHED_PACKAGE_TOTAL_KIB) * 1024+ get_positive_int_env(env_var="PIPELEX_MAX_FETCHED_PACKAGE_TOTAL_KIB", default=DEFAULT_MAX_FETCHED_PACKAGE_TOTAL_KIB) * 1024)-MAX_MANIFEST_FILE_BYTES = _read_positive_int(env_var="PIPELEX_MAX_MANIFEST_FILE_KIB", default=DEFAULT_MAX_MANIFEST_FILE_KIB) * 1024-MAX_SCANNED_MANIFESTS = _read_positive_int(env_var="PIPELEX_MAX_SCANNED_MANIFESTS", default=DEFAULT_MAX_SCANNED_MANIFESTS)+MAX_MANIFEST_FILE_BYTES = get_positive_int_env(env_var="PIPELEX_MAX_MANIFEST_FILE_KIB", default=DEFAULT_MAX_MANIFEST_FILE_KIB) * 1024+MAX_SCANNED_MANIFESTS = get_positive_int_env(env_var="PIPELEX_MAX_SCANNED_MANIFESTS", default=DEFAULT_MAX_SCANNED_MANIFESTS)diff --git a/pipelex/methods/fetch_on_miss.py b/pipelex/methods/fetch_on_miss.pyindex ac42fbcbd..bb16c1fad 100644--- a/pipelex/methods/fetch_on_miss.py+++ b/pipelex/methods/fetch_on_miss.py@@ -30,12 +30,8 @@ from pipelex.methods.exceptions import ()from pipelex.methods.fetching import fetch_method_packagefrom pipelex.methods.method_ref import MethodRef, looks_like_method_ref, parse_method_ref-from pipelex.methods.structures_check import (- STRUCTURES_REFUSAL_REMEDY,- STRUCTURES_REFUSAL_RULE,- describe_structured_content_violations,- scan_structured_content_classes,-)+from pipelex.methods.structures_check import describe_structured_content_violations, scan_structured_content_classes+from pipelex.system.telemetry.otel_constants import OTelLogAttr# The remedy every refusal ends with. It names no directory: on a host, the runtime's own store is not the caller's to write.MANUAL_INSTALL_HINT = "install the package where this runtime runs (for example with `mthds install <address>`)"@@ -87,8 +83,8 @@ def find_vendored_method(*, full_address: str, methods_dirs: list[Path]) -> Instversion = vendored.manifest.versionif lookup.ref.tag not in {version, f"v{version}"}:log.warning(- f"Method '{lookup.ref.address}' is shipped with the request at version {version} while the reference pins "- f"'@{lookup.ref.tag}'; using the shipped copy."+ "A method reference pins a tag, and the copy shipped with the request is another version, which is used",+ fields={"method_ref": lookup.ref.ref_str, "package_version": version},)return vendored@@ -99,13 +95,13 @@ def _warn_on_tag_mismatch(*, installed: InstalledMethod, ref: MethodRef | None)returnif installed.provenance is not None and installed.provenance.tag == ref.tag:return- if installed.provenance is None:- installed_desc = "of unrecorded provenance"- else:- installed_desc = f"fetched at tag '{installed.provenance.tag}'" if installed.provenance.tag else "fetched with no tag"+ mismatch_fields: dict[str, str | None] = {"method_ref": ref.ref_str, OTelLogAttr.FILE_PATH: str(installed.path)}+ if installed.provenance is not None:+ # Absent when the copy's provenance was never recorded, and None when the copy was fetched with no tag.+ mismatch_fields["installed_tag"] = installed.provenance.taglog.warning(- f"Method '{ref.address}' is already installed at '{installed.path}' ({installed_desc}) while the reference pins "- f"'@{ref.tag}'; using the installed copy. Remove '{installed.path}' to re-fetch at the pinned tag."+ "A method reference pins a tag the installed copy was not fetched at, so the installed copy is used; removing it re-fetches the pinned tag",+ fields=mismatch_fields,)@@ -190,10 +186,11 @@ def resolve_address_based_method(violations = scan_structured_content_classes(package_dir=fetched.package_dir)if violations:- details = describe_structured_content_violations(violations=violations)+ # The remedy is in the message, which the console never cuts; `STRUCTURES_REFUSAL_REMEDY` says it at length in the refusal.log.warning(- f"Method '{fetched.full_address}' declares Python structure classes ({details}). It runs locally, but "- f"{STRUCTURES_REFUSAL_RULE} — hosted execution would refuse it. {STRUCTURES_REFUSAL_REMEDY}"+ "A fetched method declares Python structure classes: it runs locally, but hosted execution refuses them, "+ "so declare these types as MTHDS concepts with inline structures",+ fields={"package_address": fetched.full_address, "structure_classes": describe_structured_content_violations(violations=violations)},)name = fetched.manifest.name or fetched.package_dir.name@@ -210,5 +207,8 @@ def resolve_address_based_method(finally:shutil.rmtree(clone_dir, ignore_errors=True)- log.info(f"Fetched method '{fetched.full_address}' at commit {fetched.commit_sha} and installed it into '{installed.path}'")+ log.info(+ "Fetched a method package and installed it",+ fields={"package_address": fetched.full_address, "commit_sha": fetched.commit_sha, OTelLogAttr.FILE_PATH: str(installed.path)},+ )return installeddiff --git a/pipelex/methods/structures_check.py b/pipelex/methods/structures_check.pyindex 585132be7..1488db8ee 100644--- a/pipelex/methods/structures_check.py+++ b/pipelex/methods/structures_check.py@@ -46,7 +46,8 @@ STRUCTURE_BASE_CLASS_NAME = "StructuredContent"STRUCTURES_REFUSAL_RULE = "hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python"-# What every message about the rule tells the author to do, whether it refuses or only predicts a refusal.+# What every message about the rule tells the author to do, whether it refuses or only predicts a refusal. The one exception+# is the warning fetch-on-miss logs: a log message is a literal written at the call, so that line gives the remedy's first step.STRUCTURES_REFUSAL_REMEDY = ("Declare these types as MTHDS concepts with inline structures; a PipeFunc can return them by importing the classes ""the sandbox generates from those concepts (`from structures import <domain>__<Concept>`). A structures module "diff --git a/pipelex/migration/runner.py b/pipelex/migration/runner.pyindex 06aae8e9c..fac92f5d4 100644--- a/pipelex/migration/runner.py+++ b/pipelex/migration/runner.py@@ -32,6 +32,8 @@ from pipelex.migration.ledger import MigrationLedger, load_ledger_cachedfrom pipelex.migration.plan import FileBlockedReason, MigrationPlan, MigrationReport, UnexplainedPathfrom pipelex.migration.surfaces import Surface, SurfaceRegistryfrom pipelex.system.configuration.config_surface import version_declared_below_the_floor+from pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.error_fields import error_fieldsdef migrate_file(*, surface: Surface, ledger: MigrationLedger, file_path: Path, dry_run: bool, moment: datetime) -> MigrationPlan:@@ -232,7 +234,10 @@ def write_file_with_backup(*, snapshot: FileSnapshot, new_content: str, moment:),backup_path=kept.path,)- log.warning(f"'{snapshot.path}' was migrated, but the write left something behind: {exc}")+ log.warning(+ "A configuration file was migrated, but the write left temporary files behind",+ fields={OTelLogAttr.FILE_PATH: str(snapshot.path), **error_fields(exc=exc)},+ )_prune_older_backups(snapshot=snapshot, backup=backup)return FileWriteOutcome(backup_path=backup.path, was_written=True)@@ -284,7 +289,8 @@ def _prune_older_backups(*, snapshot: FileSnapshot, backup: WrittenBackup) -> No# An older backup that would not go is a housekeeping failure on a file that is already# migrated and already backed up. Not the plan's to report as a failure of the file.log.warning(- f"'{snapshot.path}' was migrated and backed up to '{backup.path}', but an older backup could not be pruned: {exc.strerror or exc}"+ "A change to a configuration file was backed up, but an older backup of the file could not be pruned",+ fields={OTelLogAttr.FILE_PATH: str(snapshot.path), "backup_path": str(backup.path), **error_fields(exc=exc, text=exc.strerror)},)@@ -307,7 +313,10 @@ def _discard_created_backup(*, backup: WrittenBackup, snapshot: FileSnapshot) ->try:backup.path.unlink(missing_ok=True)except OSError as exc:- log.warning(f"the backup '{backup.path}' was made for a removal that did not happen and could not be removed: {exc.strerror or exc}")+ log.warning(+ "A backup made for a removal that did not happen could not be removed, so it stays beside the file",+ fields={OTelLogAttr.FILE_PATH: str(snapshot.path), "backup_path": str(backup.path), **error_fields(exc=exc, text=exc.strerror)},+ )return None@@ -366,7 +375,10 @@ def _discard_backup(*, backup: WrittenBackup, snapshot: FileSnapshot, new_contentry:backup.path.unlink(missing_ok=True)except OSError as exc:- log.warning(f"the backup '{backup.path}' was made for a write that did not happen and could not be removed: {exc.strerror or exc}")+ log.warning(+ "A backup made for a write that did not happen could not be removed, so it stays beside the file",+ fields={OTelLogAttr.FILE_PATH: str(snapshot.path), "backup_path": str(backup.path), **error_fields(exc=exc, text=exc.strerror)},+ )def _carries(*, path: Path, content: str) -> bool:diff --git a/pipelex/pipe_controllers/batch/pipe_batch.py b/pipelex/pipe_controllers/batch/pipe_batch.pyindex ffa2f2251..0ccd71a4d 100644--- a/pipelex/pipe_controllers/batch/pipe_batch.py+++ b/pipelex/pipe_controllers/batch/pipe_batch.py@@ -17,6 +17,7 @@ from pipelex.pipe_controllers.pipe_controller import PipeControllerfrom pipelex.pipe_run.pipe_job_factory import PipeJobFactoryfrom pipelex.pipe_run.pipe_run_params import BatchParams, PipeRunParamsfrom pipelex.system.job_metadata import JobMetadata+from pipelex.system.telemetry.otel_constants import OTelLogAttrfrom pipelex.tools.misc.async_utils import gather_boundedfrom pipelex.urls import URLs@@ -31,6 +32,27 @@ if TYPE_CHECKING:LARGE_BATCH_ADVISORY_THRESHOLD = 100+def warn_of_large_batch(*, pipe_code: str, item_count: int, max_concurrency: int | None) -> None:+ """Advise a durable execution backend for a batch past ``LARGE_BATCH_ADVISORY_THRESHOLD`` items.++ Each case has its own message, which says what the fan-out is: bounded, it is backpressure, and unbounded it is not+ even that. ``max_concurrency`` is always an integer, so a log query reads one type: it is absent from the line when+ the configuration's ``"unbounded"`` resolved to no bound at all.+ """+ if max_concurrency is None:+ log.warning(+ "A PipeBatch fans out over a large list with unbounded fan-out, which is neither backpressure nor durable execution; "+ "for a workload this size, consider a durable execution backend for rate-limited, resumable runs",+ fields={"pipe_code": pipe_code, "item_count": item_count, OTelLogAttr.URL_FULL: URLs.durable_execution},+ )+ return+ log.warning(+ "A PipeBatch fans out over a large list with bounded fan-out, which is backpressure and not durable execution; "+ "for a workload this size, consider a durable execution backend for rate-limited, resumable runs",+ fields={"pipe_code": pipe_code, "item_count": item_count, "max_concurrency": max_concurrency, OTelLogAttr.URL_FULL: URLs.durable_execution},+ )++class PipeBatch(PipeController):type: Literal["PipeBatch"] = "PipeBatch"@@ -133,12 +155,7 @@ class PipeBatch(PipeController):# `PipeRunParams.batch_max_concurrency`.max_concurrency = pipe_run_params.batch_max_concurrencyif item_count > LARGE_BATCH_ADVISORY_THRESHOLD:- log.warning(- f"PipeBatch '{self.code}' is fanning out over {item_count} items. Bounded fan-out "- f"(max_concurrency={max_concurrency if max_concurrency is not None else 'unbounded'}) is a basic backpressure "- f"effort, not durable execution — for a workload this size, consider a durable execution backend for "- f"rate-limited, resumable runs: {URLs.durable_execution}"- )+ warn_of_large_batch(pipe_code=self.code, item_count=item_count, max_concurrency=max_concurrency)item_concept = self.inputs.get_required_stuff_spec(input_list_stuff_name).conceptdiff --git a/pipelex/pipe_controllers/condition/pipe_condition.py b/pipelex/pipe_controllers/condition/pipe_condition.pyindex 9bffbf4b5..b5f4e1718 100644--- a/pipelex/pipe_controllers/condition/pipe_condition.py+++ b/pipelex/pipe_controllers/condition/pipe_condition.py@@ -3,7 +3,6 @@ from typing import TYPE_CHECKING, Any, Literalfrom pydantic import BaseModel, ConfigDictfrom typing_extensions import override-from pipelex import logfrom pipelex.cogt.inference.error_classification import UserAction, UserActionKindfrom pipelex.cogt.templating.template_rendering import render_templatefrom pipelex.core.concepts.native.concept_native import NativeConceptCode@@ -461,7 +460,7 @@ class PipeCondition(PipeController):template_source=self.expression,)except Jinja2DetectVariablesError as exc:- log.error(f"Dry run failed: could not detect required variables from expression template: {exc}")+ # Nothing is logged here: the refusal raised below is the failure, and whoever handles it reports it.# The expression is the caller's own method. The message quotes neither the expression nor the parser's# diagnosis, which names the token it stopped at: the condition may be a host library's, whose text# must not reach the caller. The line locates the fault. It is raised from the parser's own error,diff --git a/pipelex/pipe_machinery/pipe_abstract.py b/pipelex/pipe_machinery/pipe_abstract.pyindex 7dc94362d..d107496f8 100644--- a/pipelex/pipe_machinery/pipe_abstract.py+++ b/pipelex/pipe_machinery/pipe_abstract.py@@ -256,7 +256,10 @@ class PipeAbstract(ABC, BaseModel):# comes from the bundle's domain field, not from the pipe code itself.if "." in code:bare_code = code.rsplit(".", maxsplit=1)[1]- log.warning(f"Runtime pipe code '{code}' contains a namespace prefix, stripped to '{bare_code}'")+ log.warning(+ "A pipe code carries a namespace prefix, which was stripped: write the pipe code bare",+ fields={"pipe_code": bare_code, "pipe_ref": code},+ )code = bare_codeif not is_snake_case(code):msg = f"Invalid pipe code syntax '{code}'. Must be in snake_case."@@ -960,9 +963,9 @@ class PipeAbstract(ABC, BaseModel):the same way, so no downstream consumer meets a neither-value-nor-record hard miss."""lifted_input = liftable[0]- absent_names = ", ".join(absent.named_stuff_spec.variable_name for absent in liftable)+ absent_names = [absent.named_stuff_spec.variable_name for absent in liftable]output_slot_name = output_name or MAIN_STUFF_NAME- log.info(f"Skipping {self.type} '{self.code}': absent input(s): {absent_names}")+ log.info("Pipe run skipped for absent inputs", fields={"pipe_type": self.pipe_type, "pipe_code": self.code, "variable_names": absent_names})skip_reason = self._make_skip_reason(liftable=liftable)skip_record = AbsenceRecord(diff --git a/pipelex/pipe_operators/doc_gen/pipe_doc_gen.py b/pipelex/pipe_operators/doc_gen/pipe_doc_gen.pyindex 1cf2f2822..c2afe7717 100644--- a/pipelex/pipe_operators/doc_gen/pipe_doc_gen.py+++ b/pipelex/pipe_operators/doc_gen/pipe_doc_gen.py@@ -298,8 +298,10 @@ class PipeDocGen(PipeOperator[PipeDocGenOutput]):errors = [finding for finding in findings if finding.severity.is_error]for finding in findings:if not finding.severity.is_error:- location = f" ({finding.location})" if finding.location else ""- log.warning(f"PipeDocGen '{self.code}', template file '{self.template_file}'{location}: {finding.message}")+ finding_fields: dict[str, str] = {"pipe_code": self.code, "template_file": self.template_file, "finding_message": finding.message}+ if finding.location:+ finding_fields["finding_location"] = finding.location+ log.warning("The template check of a PipeDocGen found a warning in its template file", fields=finding_fields)if errors:listed = "\n".join(f"- {finding.message}" + (f" ({finding.location})" if finding.location else "") for finding in errors)msg = f"PipeDocGen '{self.code}': the template file '{self.template_file}' does not fit the step's inputs:\n{listed}"diff --git a/pipelex/pipe_operators/func/pipe_func.py b/pipelex/pipe_operators/func/pipe_func.pyindex 5b7b74300..d2eca4448 100644--- a/pipelex/pipe_operators/func/pipe_func.py+++ b/pipelex/pipe_operators/func/pipe_func.py@@ -257,10 +257,7 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):pipe_run_params: PipeRunParams,output_name: str | None = None,) -> PipeFuncOutput:- log.info(- f"🚨 For your information, the dry run of PipeFunc '{self.code}' is not actually running the python function \- but only validating the inputs and return type."- )+ log.debug("The dry run of a PipeFunc validates its inputs and return type without running the function", fields={"pipe_code": self.code})# Sandbox-hosted mode: the customer function is not registered in THIS process (its source only# travels on the crate to the sandbox), so its return type cannot be inspected here. Build the# mock output from the DECLARED output concept's structure class instead — mirroring PipeLLM'sdiff --git a/pipelex/pipe_run/delivery_executor.py b/pipelex/pipe_run/delivery_executor.pyindex 3eb571bcc..0c107b011 100644--- a/pipelex/pipe_run/delivery_executor.py+++ b/pipelex/pipe_run/delivery_executor.py@@ -2,6 +2,7 @@ from __future__ import annotationsimport htmlfrom typing import TYPE_CHECKING, Any, Awaitable, NamedTuple, cast+from urllib.parse import urlsplitimport httpxfrom kajson.exceptions import KajsonException@@ -28,6 +29,7 @@ from pipelex.pipe_run.exceptions import PipeJobError, StorageDeliveryError, Webhfrom pipelex.reporting.usage_records import dump_tokens_usage_recordsfrom pipelex.runtime_bridge.primitives.hydration import hydrate_contentfrom pipelex.runtime_hub import get_class_registry, get_storage_provider+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.misc.json_utils import clean_json_dumpsfrom pipelex.tools.network.ssrf_guard import SsrfGuardedTransport@@ -61,31 +63,32 @@ class DeliveryExecutor:) -> None:"""Execute a full delivery: generate result files, store them, then notify webhooks.- ``request_id`` is the originating API request id (when set). It is threaded- into the storage / webhook completion log lines so the delivery phase can be- correlated with the workflow logs and the inbound request.+ ``request_id`` is the originating API request id (when set). The delivery binds it+ with ``pipeline_run_id`` onto the log context, so every record the delivery emits,+ its storage and webhook completion lines included, carries both and correlates+ with the workflow logs and the inbound request, whether or not the caller bound+ them already. A ``None`` request id inherits whatever the caller bound."""- # Step 1: Persist the result files to storage (only on success with output)- result_url: str | None = None- if delivery_assignment.storage is not None and pipe_output is not None:- result_url = await self._store_results(- pipe_output,- storage_scope=storage_scope,- pipeline_run_id=pipeline_run_id,- storage=delivery_assignment.storage,- request_id=request_id,- )+ with log.context(request_id=request_id, pipeline_run_id=pipeline_run_id):+ # Step 1: Persist the result files to storage (only on success with output)+ result_url: str | None = None+ if delivery_assignment.storage is not None and pipe_output is not None:+ result_url = await self._store_results(+ pipe_output,+ storage_scope=storage_scope,+ pipeline_run_id=pipeline_run_id,+ storage=delivery_assignment.storage,+ )- # Step 2: Notify webhooks with status + result_url (always, even on failure)- for webhook in delivery_assignment.webhooks:- await self._notify_webhook(- pipeline_run_id=pipeline_run_id,- status=status,- result_url=result_url,- webhook=webhook,- error_report=error_report,- request_id=request_id,- )+ # Step 2: Notify webhooks with status + result_url (always, even on failure)+ for webhook in delivery_assignment.webhooks:+ await self._notify_webhook(+ pipeline_run_id=pipeline_run_id,+ status=status,+ result_url=result_url,+ webhook=webhook,+ error_report=error_report,+ )# ---- Result file generation ----@@ -208,8 +211,13 @@ class DeliveryExecutor:return Nonetry:return AbsenceRecord.model_validate(candidate)- except ValidationError as exc:- log.warning(f"Malformed main-output absence record in raw working memory, treating as missing: {exc}")+ except ValidationError as validation_error:+ # Treated as missing, the caller then fails the delivery: the record is lost, and this line says why. The+ # error rides as its fields, never its text or traceback, which quote the values the record held.+ log.error(+ "The absence record of the main output is malformed, so the delivery has no result to render",+ fields=error_fields(exc=validation_error),+ )return None@classmethod@@ -244,19 +252,25 @@ class DeliveryExecutor:try:return get_concept_library().resolve_wire_concept_ref(concept_ref=concept_ref)except ConceptRefAmbiguousError as exc:- log.warning(f"Concept ref '{concept_ref}' is ambiguous in the current library, rendering the delivery raw: {exc}")+ log.warning(+ "A concept ref is ambiguous in the current library; the delivery renders the result raw",+ fields={"concept_ref": concept_ref, **error_fields(exc=exc)},+ )return Noneexcept (LibraryError, ConceptLibraryConceptNotFoundError):return Noneexcept RuntimeError as exc:# The contextvar still names a library, but the hub that held it is gone. A delivery# outlives the run it renders, so this is a race to survive, not a state to assert.- log.warning(f"The current library is no longer reachable, rendering the delivery raw: {exc}")+ log.warning("The current library is no longer reachable; the delivery renders the result raw", fields=error_fields(exc=exc))return Nonetry:is_native_ref = NativeConceptCode.is_valid_native_concept_ref(concept_ref=concept_ref)except QualifiedRefError as exc:- log.warning(f"Concept ref '{concept_ref}' is not a valid concept ref, rendering the delivery raw: {exc}")+ log.warning(+ "A concept ref is malformed; the delivery renders the result raw",+ fields={"concept_ref": concept_ref, **error_fields(exc=exc)},+ )return Noneif not is_native_ref:return None@@ -278,22 +292,22 @@ class DeliveryExecutor:try:concept_ref = stuff_raw["concept"]if not isinstance(concept_ref, str):- log.warning(- f"Local hydration failed for delivery main stuff, falling back to raw render: "- f"'concept' must be the concept ref string, got {type(concept_ref).__name__}"- )+ # A stale runtime dumped the whole concept object here: worth a redeploy, so a warning.+ log.warning("The delivered result does not name its concept by a concept ref string; the delivery renders it raw")return Noneconcept = cls._resolve_concept_locally(concept_ref=concept_ref)if concept is None:- log.warning(f"Local hydration failed for delivery main stuff, falling back to raw render: concept '{concept_ref}' not known locally")+ # A crate-free delivery worker does not know a method's own concepts by design, so this is the+ # expected path for most hosted results: worth a debug line, not a warning nobody can act on.+ log.debug("The delivered result's concept is not known here; the delivery renders it raw", fields={"concept_ref": concept_ref})return None# A structureless concept (`native.Anything`) names no class to look up: its content carries its own.if concept.declares_a_structure_class:item_class = get_class_registry().get_class(name=concept.structure_class_name)if item_class is None or not issubclass(item_class, StuffContent):log.warning(- f"Local hydration failed for delivery main stuff, falling back to raw render: "- f"class '{concept.structure_class_name}' not registered locally"+ "The structure class of the delivered result's concept is not registered here; the delivery renders it raw",+ fields={"concept_ref": concept_ref, "structure_class_name": concept.structure_class_name},)return Nonecontent = hydrate_content(concept=concept, raw_content=stuff_raw["content"])@@ -304,7 +318,10 @@ class DeliveryExecutor:content=content,)except (PipeJobError, ValidationError, KajsonException, KeyError, TypeError) as exc:- log.warning(f"Local hydration failed for delivery main stuff, falling back to raw render: {exc}")+ log.warning(+ "The delivered result could not be hydrated; the delivery renders it raw",+ fields=error_fields(exc=exc),+ )return None@classmethod@@ -358,9 +375,9 @@ class DeliveryExecutor:self._add_optional_text_file(files=files, filename="mermaidflow.mmd", text=graph_outputs.mermaidflow_mmd, content_type="text/plain")self._add_optional_text_file(files=files, filename="mermaidflow.html", text=graph_outputs.mermaidflow_html, content_type="text/html")self._add_optional_text_file(files=files, filename="reactflow.html", text=graph_outputs.reactflow_html, content_type="text/html")- except Exception: # ruff: ignore[blind-except]+ except Exception as exc: # ruff: ignore[blind-except]# Best-effort: graph generation spans a deep mermaid/reactflow render tree; a graph failure must never fail result delivery.- log.warning("Failed to generate graph outputs")+ log.warning("Failed to generate graph outputs", fields=error_fields(exc=exc))@classmethodasync def _try_add_rendered_file(@@ -374,9 +391,12 @@ class DeliveryExecutor:"""Await a render coroutine and store the encoded result; log a warning on failure."""try:text = await render- except Exception: # ruff: ignore[blind-except]+ except Exception as exc: # ruff: ignore[blind-except]# Best-effort: per-format rendering (incl. jinja2 viewer); a single render failure must not drop the other result files.- log.warning(f"Failed to render {filename}")+ log.warning(+ "A result file could not be rendered; the delivery goes on without it",+ fields={"file.name": filename, **error_fields(exc=exc)},+ )returnfiles[filename] = ResultFile(data=text.encode("utf-8"), content_type=content_type)@@ -395,7 +415,6 @@ class DeliveryExecutor:storage_scope: str,pipeline_run_id: str,storage: StorageTarget,- request_id: str | None = None,) -> str:"""Generate all result files and store them. Returns the base result URL.@@ -404,8 +423,8 @@ class DeliveryExecutor:which is what made a run's outputs unreadable by anyone else on the sameteam. `storage_scope` already identifies the run (the host composes itfrom whatever its tenancy model is), so `pipeline_run_id` no longer- appears in the key; it stays a parameter because the log line below- correlates on it.+ appears in the key; it stays a parameter because the failure below+ names it."""try:storage_provider = get_storage_provider()@@ -422,8 +441,7 @@ class DeliveryExecutor:# TODO: include the full S3 URI (s3://bucket/key/) so result_url is# self-contained and doesn't depend on knowing the bucket externally.result_url: str = f"{base_key}/"- request_id_suffix = f", request_id={request_id}" if request_id else ""- log.info(f"Storage delivery completed: pipeline_run_id={pipeline_run_id}, files={len(result_files)}{request_id_suffix}")+ log.info("Storage delivery completed", fields={"file_count": len(result_files)})return result_urlexcept Exception as exc:# Delivery boundary: any failure across result-file generation or storage is converted to StorageDeliveryError. Re-raises, never swallows.@@ -440,7 +458,6 @@ class DeliveryExecutor:result_url: str | None,webhook: WebhookTarget,error_report: ErrorReport | None = None,- request_id: str | None = None,) -> None:"""POST status, optional result_url, and optional VERBOSE error report to a webhook URL.@@ -478,8 +495,8 @@ class DeliveryExecutor:timeout=30.0,)response.raise_for_status()- request_id_suffix = f", request_id={request_id}" if request_id else ""- log.info(f"Webhook delivery completed: pipeline_run_id={pipeline_run_id}, url={webhook.url}{request_id_suffix}")+ # The receiver's host and not its URL: a webhook URL is the caller's, and its path or query may carry a credential.+ log.info("Webhook delivery completed", fields={"server.address": urlsplit(webhook.url).hostname})except httpx.HTTPStatusError as exc:msg = f"Webhook delivery failed for pipeline_run_id={pipeline_run_id}: HTTP {exc.response.status_code}"raise WebhookDeliveryError(msg) from excdiff --git a/pipelex/pipe_run/dry_run_in_process.py b/pipelex/pipe_run/dry_run_in_process.pyindex 9feb6bf0a..b3315ce83 100644--- a/pipelex/pipe_run/dry_run_in_process.py+++ b/pipelex/pipe_run/dry_run_in_process.py@@ -30,6 +30,7 @@ from pipelex.runtime_hub import scoped_content_generator, scoped_event_logfrom pipelex.system.caller_identity import CallerIdentity, scoped_caller_identityfrom pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.storage_scope import DRY_RUN_STORAGE_SCOPE, DRY_RUN_USER_ID+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tracing.in_memory_event_log import InMemoryEventLog@@ -51,13 +52,14 @@ async def best_effort_graph_spec(*, pipe_ref: str | None, library_id: str | NoneArgs:pipe_ref: The namespaced ref of the pipe to dry-run, or ``None`` for no graph.library_id: The id of the already-open library to run against, or ``None`` for no graph.- log_context: Caller tag prefixed to the degrade warning (e.g. ``"act_dry_validate"``).+ log_context: Caller tag the degrade warning carries in its ``caller`` field (e.g. ``"act_dry_validate"``).Returns:The assembled GraphSpec, or ``None`` when skipped or degraded."""if not pipe_ref or not library_id:return None+ pipe: PipeAbstract | None = Nonetry:# Entry-shaped: `pipe_ref` is either a caller-supplied graph target (a protocol request# field) or a bundle's already-qualified main_pipe_ref. Both are pipes someone pointed at,@@ -71,12 +73,26 @@ async def best_effort_graph_spec(*, pipe_ref: str | None, library_id: str | Noneif foreign_fault is not None and not isinstance(foreign_fault, (FactoryException, ValueError)):raiselog.warning(- f"{log_context}: graph dry-run of '{pipe_ref}' did not produce a graph "- f"({type(graph_error).__name__}: {graph_error}); returning validation result without graph_spec"+ "The graph dry run produced no graph; the validation result carries none",+ fields={"caller": log_context, **_graph_target_fields(pipe=pipe, target=pipe_ref), **error_fields(exc=graph_error)},)return None+def _graph_target_fields(*, pipe: PipeAbstract | None, target: str) -> dict[str, str]:+ """The fields naming the pipe a graph dry run was for, as the pipe-run lines name it.++ A resolved pipe is named by its bare code under `pipe_code`, the value `Pipe run starts` carries, and by its qualified+ reference under `pipe_ref`. A target that resolved to no pipe is carried as it was named: under `pipe_ref` when a+ domain qualifies it, under `pipe_code` when it is a bare code.+ """+ if pipe is not None:+ return {"pipe_code": pipe.code, "pipe_ref": pipe.pipe_ref}+ if "." in target:+ return {"pipe_ref": target}+ return {"pipe_code": target}++async def dry_run_pipe_in_process(pipe: PipeAbstract, *, library_id: str, caller_identity: CallerIdentity | None = None) -> GraphSpec:"""Dry-run ``pipe`` against an already-open library fully in-process, tracing the graph in memory.diff --git a/pipelex/pipe_run/pipe_run.py b/pipelex/pipe_run/pipe_run.pyindex 371f6e643..c21e4584f 100644--- a/pipelex/pipe_run/pipe_run.py+++ b/pipelex/pipe_run/pipe_run.py@@ -14,6 +14,7 @@ from pipelex.pipe_run.exceptions import DeliveryErrorfrom pipelex.pipe_run.pipe_run_protocol import PipeRunProtocolfrom pipelex.pipe_run.tracing_assembly import assemble_tracing_on_outputfrom pipelex.pipeline.build_pipe_io_artifacts import build_pipe_io_artifacts+from pipelex.tools.log.error_fields import error_fieldsif TYPE_CHECKING:from pipelex.core.pipes.pipe_output import PipeOutput@@ -71,19 +72,26 @@ class PipeRun(PipeRunProtocol):error_report = exc.to_error_report()else:error_report = PipelexUnexpectedError(str(exc) or repr(exc)).to_error_report()- log.error(f"Pipe execution failed for pipeline_run_id={pipeline_run_id}: {exc}")+ # The error rides as fields and no traceback: the exception is re-raised below, and its traceback+ # belongs to whoever catches it, the CLI or the API's handler, which would otherwise print it twice.+ # `pipe_code` is the bare code `Pipe run starts` carries for the same pipe, so one query finds both lines.+ log.error(+ "Pipe execution failed",+ fields={"pipe_code": pipe_job.pipe.code, "pipe_ref": pipe_job.pipe.pipe_ref, **error_fields(exc=exc)},+ )finally:tracer_manager = GraphTracerManager.get_instance()if tracer_manager is not None:try:tracer_manager.close_tracer(pipeline_run_id)- except OSError as tracer_close_error:+ except OSError as close_error:if execution_error is None:raise+ # A secondary failure rides as fields with no traceback: the execution error is chained onto it, so+ # its traceback would print the execution error's text, which can quote the run's inputs.log.error(- f"close_tracer also failed for pipeline_run_id={pipeline_run_id} "- f"after pipe execution failure; raising original execution error. "- f"Suppressed tracer close error: {tracer_close_error}"+ "Closing the graph tracer also failed after the pipe execution failed; the execution error is raised",+ fields=error_fields(exc=close_error),)# Assemble graph and/or usage onto pipe_output from the single trace-event read. The two@@ -119,10 +127,10 @@ class PipeRun(PipeRunProtocol):except DeliveryError as delivery_error:if execution_error is None:raise+ # As fields with no traceback, for the same reason as the tracer's: the execution error is chained onto it.log.error(- f"Delivery also failed for pipeline_run_id={pipeline_run_id} "- f"after pipe execution failure; raising original execution error. "- f"Suppressed delivery error: {delivery_error}"+ "The delivery also failed after the pipe execution failed; the execution error is raised",+ fields=error_fields(exc=delivery_error),)if execution_error is not None:@@ -150,6 +158,5 @@ class PipeRun(PipeRunProtocol):try:pipe_output.pipe_io_artifacts = build_pipe_io_artifacts(get_own_pipes())except Exception as build_error: # ruff: ignore[blind-except]- message = f"Failed to build the I/O artifacts for pipeline_run_id={pipeline_run_id}: {build_error}"- log.warning(message)- pipe_output.pipe_io_artifacts_error = message+ log.warning("The I/O artifacts of the run could not be built; the run keeps its result", fields=error_fields(exc=build_error))+ pipe_output.pipe_io_artifacts_error = f"Failed to build the I/O artifacts for pipeline_run_id={pipeline_run_id}: {build_error}"diff --git a/pipelex/pipe_run/pipe_run_params.py b/pipelex/pipe_run/pipe_run_params.pyindex e5cd40111..620f3fb93 100644--- a/pipelex/pipe_run/pipe_run_params.py+++ b/pipelex/pipe_run/pipe_run_params.py@@ -263,7 +263,10 @@ class PipeRunParams(BaseModel):# pipe fails — a mismatch here should not happen in normal flow. We log rather than# raise: this runs inside run_pipe()'s `finally`, where raising would mask the# in-flight exception.- log.error(f"Pipe code '{pipe_code}' was not the last pipe in the stack, it was '{popped_pipe_code}'")+ log.error(+ "The pipe stack is unbalanced: the pipe popped is not the last one pushed",+ fields={"pipe_code": pipe_code, "popped_pipe_code": popped_pipe_code},+ )def push_pipe_layer(self, pipe_code: str) -> None:if self.pipe_layers and self.pipe_layers[-1] == pipe_code:diff --git a/pipelex/pipe_run/tracing_assembly.py b/pipelex/pipe_run/tracing_assembly.pyindex a88f11905..876d59d9d 100644--- a/pipelex/pipe_run/tracing_assembly.py+++ b/pipelex/pipe_run/tracing_assembly.py@@ -24,6 +24,7 @@ from pipelex.runtime_hub import get_event_log_overridefrom pipelex.system.exceptions import MissingDependencyErrorfrom pipelex.system.job_metadata import RunMetadatafrom pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tracing.event_log_factory import make_event_logfrom pipelex.tracing.exceptions import EventLogErrorfrom pipelex.tracing.graphspec_assembler import GraphSpecAssembler@@ -115,6 +116,32 @@ def assemble_tracing("""result = TracingAssembly()result.set_run_metadata(run_metadata=run_metadata)+ # Bound here rather than left to the caller: besides `PipeRun`'s run, whose context binds the run already, this is+ # the body of the durable-execution activity `act_assemble_tracing`, which runs under no binding of the run, so its+ # lines would name no run. A `request_id` of `None` inherits whatever the caller bound.+ with log.context(request_id=run_metadata.request_id if run_metadata else None, pipeline_run_id=pipeline_run_id):+ return _assemble_tracing_events(+ result=result,+ pipeline_run_id=pipeline_run_id,+ assemble_graph=assemble_graph,+ assemble_usage=assemble_usage,+ domain_code=domain_code,+ main_pipe_code=main_pipe_code,+ run_mode=run_mode,+ )+++def _assemble_tracing_events(+ *,+ result: TracingAssembly,+ pipeline_run_id: str,+ assemble_graph: bool,+ assemble_usage: bool,+ domain_code: str | None,+ main_pipe_code: str | None,+ run_mode: PipeRunMode,+) -> TracingAssembly:+ """The body of ``assemble_tracing``, run inside the log context it binds: read the events once, assemble onto ``result``."""tracing_config = get_config().runtime.tracing# A scoped override (see hub.scoped_event_log) is the run's transport and implies# tracing-enabled (D1) — it must not be skipped by the is_enabled early-return.@@ -142,7 +169,7 @@ def assemble_tracing(event_log.close()except (OSError, json.JSONDecodeError, ValidationError, PipelexConfigError, MissingDependencyError, EventLogError) as read_error:message = f"Tracing assembly failed to read events for pipeline_run_id={pipeline_run_id}: {read_error}"- log.warning(message)+ log.warning("Tracing assembly could not read the run's trace events", fields=error_fields(exc=read_error))if assemble_graph:result.graph_assembly_error = messageif assemble_usage:@@ -166,11 +193,10 @@ def assemble_tracing(),mode=run_mode.graphspec_mode,)- log.debug(f"Graph assembled from {len(events)} events for pipeline_run_id={pipeline_run_id}")+ log.debug("Assembled the graph from the trace events", fields={"event_count": len(events)})except ValidationError as validation_error:- message = f"Graph assembly failed for pipeline_run_id={pipeline_run_id}: {validation_error}"- log.warning(message)- result.graph_assembly_error = message+ log.warning("The graph could not be assembled from the trace events", fields=error_fields(exc=validation_error))+ result.graph_assembly_error = f"Graph assembly failed for pipeline_run_id={pipeline_run_id}: {validation_error}"return resultdiff --git a/pipelex/pipelex.py b/pipelex/pipelex.pyindex de267e204..25b3757ee 100644--- a/pipelex/pipelex.py+++ b/pipelex/pipelex.py@@ -43,7 +43,7 @@ from pipelex.pipeline.pipeline_manager_abstract import PipelineManagerAbstractfrom pipelex.plugins.pipe_func_executor_registry import PipeFuncExecutorRegistryfrom pipelex.plugins.registrar import HubSlotfrom pipelex.reporting.reporting_protocol import ReportingProtocol-from pipelex.runtime_boot import PACKAGE_NAME, PACKAGE_VERSION, RuntimeBoot+from pipelex.runtime_boot import PACKAGE_VERSION, RuntimeBootfrom pipelex.system.configuration.config_root import ConfigRootfrom pipelex.system.environment import get_pipelexpath_dirsfrom pipelex.system.runtime import IntegrationMode@@ -341,5 +341,5 @@ class Pipelex(RuntimeBoot):# and the delete-on-failure handler above is behind us, so a reader can never adopt an instance# that is about to be removed from the registry.pipelex_instance.is_ready = True- log.debug(f"{PACKAGE_NAME} version {PACKAGE_VERSION} ready")+ log.debug("Pipelex is ready", fields={"pipelex_version": PACKAGE_VERSION, "integration_mode": integration_mode})return pipelex_instancediff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.pyindex 5d6bfd52a..61567f529 100644--- a/pipelex/pipeline/pipeline_run_setup.py+++ b/pipelex/pipeline/pipeline_run_setup.py@@ -39,6 +39,7 @@ from pipelex.system.storage_scope import (from pipelex.system.telemetry.events import EventName, EventPropertyfrom pipelex.system.telemetry.otel_constants import OTelConstantsfrom pipelex.system.telemetry.otel_factory import OtelFactory+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tracing.event_log_factory import make_event_logif TYPE_CHECKING:@@ -482,11 +483,13 @@ async def pipeline_run_setup(if tracer_manager is not None:try:tracer_manager.close_tracer(pipeline_run_id)- except OSError as tracer_close_error:+ except OSError as close_error:+ # A secondary failure rides as fields with no traceback: Python chains the setup error onto+ # it, so its traceback would print the setup error's text, which the setup error's own+ # catcher reports, and which can quote a run's inputs.log.error(- f"close_tracer also failed for pipeline_run_id={pipeline_run_id} "- f"during setup-failure cleanup; raising original setup error. "- f"Suppressed tracer close error: {tracer_close_error}"+ "Closing the graph tracer also failed while cleaning up after the setup failed; the setup error is raised",+ fields=error_fields(exc=close_error),)finally:if event_log is not None:diff --git a/pipelex/pipeline/validate_in_process.py b/pipelex/pipeline/validate_in_process.pyindex c111312e8..dc2fc8e9c 100644--- a/pipelex/pipeline/validate_in_process.py+++ b/pipelex/pipeline/validate_in_process.py@@ -36,6 +36,7 @@ from pipelex.pipeline.liftable_pipes import LiftablePipeEntry, build_liftable_pifrom pipelex.pipeline.validate_bundle import validate_bundlefrom pipelex.pipeline.validation_report import PipelexValidationReport, build_validation_reportfrom pipelex.system.caller_identity import CallerIdentity, scoped_caller_identity+from pipelex.tools.log.error_fields import error_fieldsif TYPE_CHECKING:from pipelex.graph.graphspec import GraphSpec@@ -74,7 +75,7 @@ async def validate_bundles_in_process(When omitted, the graph arm keeps the existing default of targeting theselected bundle `main_pipe`. Bare and qualified refs are accepted accordingto the loaded pipe library's normal resolution rules.- log_context: Label used in graph-arm degradation and teardown-failure logs.+ log_context: Label the graph-arm degradation and teardown-failure lines carry in their ``caller`` field.caller_identity: Who asked for the validation, when the host knows it. It is theambient caller for the whole pass — the sweep's telemetry event and every dry run,the graph arm's included — so none of it falls back to the telemetry stream's@@ -178,9 +179,11 @@ async def _validate_bundles_in_scope(# succeeded. Mirrors act_dry_validate's finally.if body_succeeded:raise+ # As fields and no traceback: the validation error is chained onto this one, so its traceback would+ # print the validation error's text, which can quote the bundle, and which its own catcher reports.log.error(- f"{log_context}: library teardown also failed after a body error; "- f"raising the original error. Suppressed teardown error: {teardown_error}"+ "The teardown of the validation library also failed after the validation failed; the original error is raised",+ fields={"caller": log_context, "library_id": validation_library_id, **error_fields(exc=teardown_error)},)return build_validation_report(blueprints=result.blueprints,diff --git a/pipelex/plugins/discovery.py b/pipelex/plugins/discovery.pyindex c1321d74a..ba037f012 100644--- a/pipelex/plugins/discovery.py+++ b/pipelex/plugins/discovery.py@@ -149,7 +149,8 @@ def _skip_if_disabled(return Falseif name in core_unconditional_plugin_names:raise CoreUnconditionalPluginDisabledError(plugin_name=name)- log.info(f"Plugin '{name}' is disabled via runtime.plugins.disabled; skipping.")+ # The user asked for this, and the discovery below records it for `pipelex plugins list`, so it is no news at INFO.+ log.debug("A plugin disabled by runtime.plugins.disabled is skipped", fields={"plugin_name": name})registrar.discoveries.append(PluginDiscovery(name=name,diff --git a/pipelex/providers/pypdfium2/pypdfium2_worker.py b/pipelex/providers/pypdfium2/pypdfium2_worker.pyindex 1edb522fc..e7954f1e6 100644--- a/pipelex/providers/pypdfium2/pypdfium2_worker.py+++ b/pipelex/providers/pypdfium2/pypdfium2_worker.py@@ -115,9 +115,9 @@ class Pypdfium2Worker(ExtractWorkerAbstract):elif len(page_images) > remaining_slots:original_count = len(page_images)page_images = page_images[:remaining_slots]- log.warning(- f"Pypdfium2 extracted {original_count} images on page {page_number}, "- f"truncated to {len(page_images)} (max_nb_images={max_nb_images})"+ log.debug(+ "Truncated the images extracted from a page to the requested maximum",+ fields={"page_number": page_number, "image_count": original_count, "kept_image_count": len(page_images)},)total_images_count += len(page_images)pages[page_number] = Page(text=page_text, extracted_images=page_images)@@ -125,6 +125,7 @@ class Pypdfium2Worker(ExtractWorkerAbstract):pages[page_number] = Page(text=page_text)if max_nb_images is not None and total_images_count < sum(len(imgs) for imgs in all_page_images.values()):- log.warning(f"Pypdfium2 does not support native image limiting. Extracted all images then truncated to {max_nb_images}.")+ # The caller gets the number of images it asked for: Pypdfium2 cannot limit them natively, so they are all extracted then truncated+ log.debug("Extracted every image of the document, then truncated them to the requested maximum", fields={"max_nb_images": max_nb_images})return ExtractOutput(pages=pages)diff --git a/pipelex/providers/typesafe/typesafe_judgment_worker.py b/pipelex/providers/typesafe/typesafe_judgment_worker.pyindex 3ce0dc4a1..66c843416 100644--- a/pipelex/providers/typesafe/typesafe_judgment_worker.py+++ b/pipelex/providers/typesafe/typesafe_judgment_worker.py@@ -13,6 +13,7 @@ from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategfrom pipelex.providers.typesafe.typesafe_error_classification import classify_typesafe_errorfrom pipelex.providers.typesafe.typesafe_translation import from_typesafe_response, to_typesafe_questionsfrom pipelex.reporting.reporting_protocol import ReportingProtocol+from pipelex.system.telemetry.otel_constants import GenAISpanAttrclass TypesafeJudgmentWorker(JudgmentWorkerAbstract):@@ -101,8 +102,17 @@ class TypesafeJudgmentWorker(JudgmentWorkerAbstract):"""if response.model != self.inference_model.model_id:log.warning(- f"TypeSafe was asked for judgment model '{self.inference_model.model_id}' and answered as "- f"'{response.model}': verdicts and their thresholds may not mean what they meant under the pinned model"+ "The provider answered under another model than the pinned one, so verdicts and their thresholds may not mean what "+ "they meant under the pinned model",+ fields={+ "model_handle": self.inference_model.name,+ "backend_name": self.inference_model.backend_name,+ "sdk": self.inference_model.sdk,+ # The model keys mean what they mean on the LLM span: the handle, then the provider's id the deck pins+ GenAISpanAttr.REQUEST_MODEL: self.inference_model.name,+ GenAISpanAttr.RESPONSE_MODEL: self.inference_model.model_id,+ "answered_model_id": response.model,+ },)def _record_usage(self, *, judgment_job: JudgmentJob, response: SystemOneResponse) -> None:diff --git a/pipelex/reporting/cost_report_renderer.py b/pipelex/reporting/cost_report_renderer.pyindex b4f5355c1..11e72232a 100644--- a/pipelex/reporting/cost_report_renderer.py+++ b/pipelex/reporting/cost_report_renderer.py@@ -16,6 +16,7 @@ from pipelex.cogt.usage.cost_registry import CostRegistryfrom pipelex.config import get_configfrom pipelex.core.pipes.pipe_output import PipeOutputfrom pipelex.reporting.reporting_types import AnyTokensUsage+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.misc.file_utils import ensure_path, get_incremental_file_path@@ -80,7 +81,7 @@ def render_run_cost_report(print_to_console=print_to_console,)except (OSError, UnicodeEncodeError, PipelexError) as cost_report_error:- log.warning(f"Cost report generation failed (run succeeded): {cost_report_error}")+ log.warning("The cost report could not be generated; the run itself succeeded", fields=error_fields(exc=cost_report_error))def render_cost_report_for_output(pipe_output: PipeOutput) -> None:diff --git a/pipelex/reporting/reporting_manager.py b/pipelex/reporting/reporting_manager.pyindex d2018d4ae..a09b599cd 100644--- a/pipelex/reporting/reporting_manager.py+++ b/pipelex/reporting/reporting_manager.py@@ -17,6 +17,7 @@ from pipelex.reporting.reporting_types import AnyTokensUsagefrom pipelex.runtime_hub import is_in_isolated_executionfrom pipelex.system.exceptions import MissingDependencyErrorfrom pipelex.system.trace_context import TraceContext+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tracing.activity_event_log import ActivityEventLogCachefrom pipelex.tracing.event_log_protocol import EventLogProtocolfrom pipelex.tracing.trace_events import UNATTRIBUTED_NODE_ID, UsageReportEvent@@ -253,7 +254,7 @@ class ReportingManager(ReportingProtocol):try:event_log.emit(event)except _EMIT_BEST_EFFORT_EXCEPTIONS as exc:- log.warning(f"Usage event emit failed; dropping: {exc}")+ log.warning("A usage event could not be written to the event log and was dropped", fields=error_fields(exc=exc))def _emit_usage_event_runner_fallback(self,@@ -293,7 +294,7 @@ class ReportingManager(ReportingProtocol):try:process_event_log = ActivityEventLogCache.get_or_create(tracing_config)except (OSError, MissingDependencyError, PipelexConfigError) as exc:- log.warning(f"Runner-side activity event log construction failed; dropping usage event: {exc}")+ log.warning("The runner-side activity event log could not be built, so a usage event was dropped", fields=error_fields(exc=exc))returnif process_event_log is None:@@ -330,4 +331,7 @@ class ReportingManager(ReportingProtocol):elif isinstance(inference_job, JudgmentJob):self._report_judgment_job(judgment_job=inference_job)else:- log.warning(f"ReportingManager does not support reporting for inference job type: {type(inference_job).__name__}")+ log.error(+ "The reporting manager cannot report this type of inference job, so its usage is lost",+ fields={"inference_job_type": type(inference_job).__name__},+ )diff --git a/pipelex/runtime_boot.py b/pipelex/runtime_boot.pyindex c0bf2bcb3..98eef4283 100644--- a/pipelex/runtime_boot.py+++ b/pipelex/runtime_boot.py@@ -111,6 +111,7 @@ from pipelex.system.telemetry.telemetry_manager_abstract import (from pipelex.test_extras.registry_test_models import TestRegistryModelsfrom pipelex.tools.jinja2.jinja2_template_loader import TemplateLoaderfrom pipelex.tools.jinja2.jinja2_template_registry import TemplateRegistry+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.misc.package_utils import get_package_infofrom pipelex.tools.misc.pretty import PrettyPrintMode, require_rich_for_renderingfrom pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract@@ -128,6 +129,13 @@ PACKAGE_NAME, PACKAGE_VERSION = get_package_info()_HubSlotImplT = TypeVar("_HubSlotImplT")+def _callable_name(*, function: Callable[..., object]) -> str:+ """A callable as its module and qualified name, which is what names a plugin's callback on a line with no traceback."""+ qualified_name = getattr(function, "__qualname__", None) or type(function).__qualname__+ module_name = getattr(function, "__module__", None)+ return f"{module_name}.{qualified_name}" if module_name else qualified_name++BACKEND_LIBRARY_REFUSED: tuple[type[Exception], ...] = (InferenceBackendLibraryValidationError,InferenceBackendLibraryError,@@ -251,7 +259,7 @@ class RuntimeBoot(metaclass=MetaSingleton):log.configure(log_config=log_config)self.runtime_hub.set_pretty_print_mode(mode=log_config.pretty_print_mode)if (stale_warning := config_manager.take_stale_configuration_warning()) is not None:- log.warning(stale_warning)+ stale_warning.emit()# toolsself.class_registry: ClassRegistryAbstract | None = None@@ -685,10 +693,15 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.for teardown_callback in reversed(self._plugin_registrar.teardown_callbacks):try:teardown_callback()- except Exception as teardown_exc: # ruff: ignore[blind-except]+ except Exception as callback_error: # ruff: ignore[blind-except]# (2) a plugin-registered callback is unbounded third-party code; its exception surface# cannot be enumerated, and the remaining callbacks still have resources to release.- log.error(f"A plugin teardown callback failed and was skipped: {teardown_exc}")+ # As fields with no traceback: a failed boot runs these callbacks while its own error propagates,+ # and Python chains that error onto this one, so a traceback would print the boot error's text.+ log.error(+ "A plugin teardown callback failed, and the remaining callbacks still run",+ fields={"callback_name": _callable_name(function=teardown_callback), **error_fields(exc=callback_error)},+ )def _teardown_runtime(self) -> None:"""Release what the runtime boot acquired, and the process-global *state* with it.@@ -848,10 +861,12 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.if self.telemetry_manager is not None:try:self.telemetry_manager.teardown()- except Exception as telemetry_exc: # ruff: ignore[blind-except]+ except Exception as teardown_error: # ruff: ignore[blind-except]# (2) an injected telemetry manager is unbounded code; its exception surface cannot# be enumerated, and the releases below must happen regardless.- log.error(f"Telemetry teardown failed while releasing a failed boot: {telemetry_exc}")+ # As fields with no traceback: the boot error is chained onto this one, so a traceback would print+ # the boot error's text, which the boot's own caller reports.+ log.error("The telemetry teardown failed while a failed boot was being released", fields=error_fields(exc=teardown_error))self.runtime_hub.reset_boot_state()class_registry_scoping.reset()KajsonManager.teardown()@@ -929,7 +944,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.# and the delete-on-failure handler above is behind us, so a reader can never adopt an instance# that is about to be removed from the registry.runtime_boot.is_ready = True- log.debug(f"{PACKAGE_NAME} version {PACKAGE_VERSION} runtime ready")+ log.debug("The Pipelex runtime is ready", fields={"pipelex_version": PACKAGE_VERSION, "integration_mode": integration_mode})return runtime_boot@classmethoddiff --git a/pipelex/system/configuration/config_loader.py b/pipelex/system/configuration/config_loader.pyindex 7563f6805..2850f6b39 100644--- a/pipelex/system/configuration/config_loader.py+++ b/pipelex/system/configuration/config_loader.py@@ -8,6 +8,7 @@ from pydantic import BaseModel, ValidationErrorfrom pipelex.kit.template_copy import can_fill_directory, copy_file_atomically, copy_kit_templatesfrom pipelex.system.configuration.config_surface import (PIPELEX_CONFIG_SURFACE_ID,+ StaleConfigurationWarning,replay_surface_files_in_memory,stale_configuration_warning,strip_reserved_meta,@@ -61,16 +62,17 @@ MODEL_DECKS_DIR_NAME = "deck"class ConfigLoader:def __init__(self) -> None:- self._stale_warning: str | None = None+ self._stale_warning: StaleConfigurationWarning | None = None- def take_stale_configuration_warning(self) -> str | None:+ def take_stale_configuration_warning(self) -> StaleConfigurationWarning | None:"""The warning a tolerated boot owes the user, once — or ``None`` when the load was clean.The loader parks it rather than logging it because the main configuration is what*configures logging*: at the moment the retry succeeds no handler is installed yet, and aline emitted then goes to the stdlib's default handling, where an ``INFO`` is dropped and awarning lands on stderr unformatted, ahead of the console about to be configured. The boot- emits it right after ``log.configure``, where it reads like every other line.+ emits it (``StaleConfigurationWarning.emit``) right after ``log.configure``, where it reads+ like every other line."""warning, self._stale_warning = self._stale_warning, Nonereturn warning@@ -564,8 +566,8 @@ class ConfigLoader:This is the boot's entry point, and the tolerance is the whole reason it exists. A fileleft behind by a schema change should not stop the world: when validation fails, thesurface's ledger is replayed over the same files **in memory**, the result is validated- again, and a boot that succeeds says so in a warning naming the files and the- ``pipelex migrate`` remedy — parked on the loader (``take_stale_configuration_warning``)+ again, and a boot that succeeds says so in a warning naming each file and its remedy, the+ ``pipelex migrate`` command where its walk reaches the file — parked on the loader (``take_stale_configuration_warning``)for the boot to emit once logging exists. Nothing is written — only the explicit commandwrites.diff --git a/pipelex/system/configuration/config_surface.py b/pipelex/system/configuration/config_surface.pyindex dc6c87756..7d865822c 100644--- a/pipelex/system/configuration/config_surface.py+++ b/pipelex/system/configuration/config_surface.py@@ -34,9 +34,11 @@ from typing import Any, NamedTuple, castimport tomlkitfrom tomlkit.exceptions import TOMLKitError+from pipelex import logfrom pipelex.migration.exceptions import MigrationLedgerErrorfrom pipelex.migration.ledger import MigrationLedger, load_ledger_cached, packaged_migration_dirfrom pipelex.migration.plan import MigrationPlan+from pipelex.system.telemetry.otel_constants import OTelLogAttrfrom pipelex.tools.misc.json_utils import deep_update# The reserved in-file table and key. Every configuration-surface reader tolerates them and@@ -237,44 +239,103 @@ def _is_within(*, plan: MigrationPlan, directories: Sequence[Path]) -> bool:return any(parent == (directory / subdirectory).resolve() for directory in directories)-def _quoted_files(*, plans: Sequence[MigrationPlan]) -> str:- return ", ".join(f"'{plan.file_path}'" for plan in plans)+class StaleConfigurationFile(NamedTuple):+ """One configuration file a boot carried forward in memory, as its warning line names it.+ Everything here but the path is ledger knowledge: the titles of the steps the replay carried+ and whether one of them is blocked. A value read from the user's file has no business in a+ boot warning, by the same rule the migration report obeys.+ """++ file_path: Path+ is_reached_by_migrate: bool+ """Whether `pipelex migrate`'s walk reaches the file, which decides the remedy its line names."""+ migration_steps: list[str]+ """The titles of the ledger steps the replay carried forward, sorted."""+ has_blocked_steps: bool+ """Whether some of what the file needs cannot be applied for the user."""++ def log_fields(self) -> dict[str, Any]:+ return {+ OTelLogAttr.FILE_PATH: str(self.file_path),+ "migration_steps": self.migration_steps,+ "has_blocked_steps": self.has_blocked_steps,+ }+++class StaleConfigurationWarning(NamedTuple):+ """What a boot owes the user when it carried a stale configuration forward rather than dying.++ A loader builds it when its retry succeeds and either emits it there or parks it for the caller+ that owes the user the one copy of it (`take_stale_configuration_warning` on the main+ configuration's loader and on the inference backend library). **It is emitted as one line per+ stale file**, each a fixed message naming that file's remedy with the file in `file.path`: the+ file list is a value, a value rides a field, and a field the console cuts at its width cannot+ carry a list of paths a person has to read. A load that spans files in and out of the walk+ therefore gets both remedies, each on the lines of its own files.+ """-def stale_configuration_warning(*, plans: Sequence[MigrationPlan], walked_dirs: Sequence[Path]) -> str:+ files: list[StaleConfigurationFile]++ def emit(self) -> None:+ """One line per stale file, a fixed message naming that file's remedy.++ The remedy is the command where it reaches the file, with the changes it reports it cannot apply where some+ steps are blocked, and the file's own place where it does not. Every message says that nothing was written,+ which is why the same warning comes back at the next boot.+ """+ for stale_file in self.files:+ if stale_file.is_reached_by_migrate and stale_file.has_blocked_steps:+ log.warning(+ "A configuration file is out of date and was read as if it had been migrated, and nothing was written; "+ "run `pipelex migrate` to update it, and make by hand the changes it reports it cannot apply",+ fields=stale_file.log_fields(),+ )+ elif stale_file.is_reached_by_migrate:+ log.warning(+ "A configuration file is out of date and was read as if it had been migrated, and nothing was written; "+ "run `pipelex migrate` to update it",+ fields=stale_file.log_fields(),+ )+ elif stale_file.has_blocked_steps:+ log.warning(+ "A configuration file is out of date and was read as if it had been migrated, and nothing was written; "+ "`pipelex migrate` does not reach it, so update it where it lives, including changes no migration can apply for you",+ fields=stale_file.log_fields(),+ )+ else:+ log.warning(+ "A configuration file is out of date and was read as if it had been migrated, and nothing was written; "+ "`pipelex migrate` does not reach it, so update it where it lives",+ fields=stale_file.log_fields(),+ )+++def stale_configuration_warning(*, plans: Sequence[MigrationPlan], walked_dirs: Sequence[Path]) -> StaleConfigurationWarning:"""What a boot says when it carried a stale configuration forward in memory rather than dying.- Names the files and the remedy, and takes everything else it says from the ledger — the same- rule the migration report obeys, because a boot warning is read in the same places a report is- and a value read from a user's file has no business in either.+ Names each stale file and its remedy, and takes everything else it says from the ledger — the+ same rule the migration report obeys, because a boot warning is read in the same places a+ report is and a value read from a user's file has no business in either.**`pipelex migrate` is named only for a file it would reach**, which is what `walked_dirs` isfor. Boot tolerance replays exactly the files the loader merged, and a loader pointed at adirectory of its own — `Pipelex.make(config_dir=…)`, or this repository's own`tests/pipelex_{run_mode}.toml` — merges files the command's fixed walk will never touch. A- warning that closed on "run `pipelex migrate`" there would name, on every boot, a command that- then reports nothing to do. The same rule as the migration report's: a remedy is named only- where it would write. Pass the walk (`config_manager.existing_config_dirs`); an embedder's- directory is theirs to update, and `--config-dir` is deliberately not the answer.+ warning that said "run `pipelex migrate`" there would name, on every boot, a command that then+ reports nothing to do. The same rule as the migration report's: a remedy is named only where+ it would write. Pass the walk (`config_manager.existing_config_dirs`); an embedder's directory+ is theirs to update, and `--config-dir` is deliberately not the answer."""- stale = [plan for plan in plans if not plan.is_clean]- in_reach = [plan for plan in stale if _is_within(plan=plan, directories=walked_dirs)]- out_of_reach = [plan for plan in stale if not _is_within(plan=plan, directories=walked_dirs)]- carried = sorted({step.title for plan in stale for step in plan.steps})- sentences = [f"Your configuration is out of date, and pipelex read it as if it had been migrated: {_quoted_files(plans=stale)}."]- if carried:- sentences.append(f"What the ledger carried forward: {'; '.join(carried)}.")- if any(plan.blocked for plan in stale):- blocked_note = "Some of what these files need cannot be applied for you"- sentences.append(f"{blocked_note} — `pipelex migrate` reports it." if in_reach else f"{blocked_note}.")- sentences.append("Nothing was written.")- if in_reach:- subject = _quoted_files(plans=in_reach) if out_of_reach else "the files"- sentences.append(f"Run `pipelex migrate` to bring {subject} up to date.")- if out_of_reach:- sentences.append(- f"`pipelex migrate` does not reach {_quoted_files(plans=out_of_reach)} — "- f"{'that file is' if len(out_of_reach) == 1 else 'those files are'} yours to update where "- f"{'it lives' if len(out_of_reach) == 1 else 'they live'}."- )- return " ".join(sentences)+ return StaleConfigurationWarning(+ files=[+ StaleConfigurationFile(+ file_path=plan.file_path,+ is_reached_by_migrate=_is_within(plan=plan, directories=walked_dirs),+ migration_steps=sorted({step.title for step in plan.steps}),+ has_blocked_steps=bool(plan.blocked),+ )+ for plan in plans+ if not plan.is_clean+ ]+ )diff --git a/pipelex/system/environment.py b/pipelex/system/environment.pyindex 23a9543bf..b46b9946b 100644--- a/pipelex/system/environment.py+++ b/pipelex/system/environment.py@@ -3,6 +3,7 @@ from pathlib import Pathfrom dotenv import load_dotenv+from pipelex import logfrom pipelex.system.exceptions import EnvVarNotFoundErrorfrom pipelex.tools.misc.placeholder import value_is_placeholder@@ -93,6 +94,29 @@ def set_env(key: str, value: str) -> None:os.environ[key] = value+def get_positive_int_env(*, env_var: str, default: int) -> int:+ """The positive integer an environment variable holds, or ``default`` when it holds none.++ An unset or empty variable gives the default silently. A value that is not a positive integer gives it with a+ warning, which names the variable and the default and never the value, whatever the environment holds there.+ The one reader of an env-tunable size or count, for the library's ceilings and the API server's limits alike.+ """+ raw = get_optional_env(env_var)+ if not raw:+ return default+ try:+ parsed = int(raw)+ except ValueError:+ parsed = 0+ if parsed <= 0:+ log.warning(+ "An environment variable holds no positive integer, so its default applies",+ fields={"env_var": env_var, "default_value": default},+ )+ return default+ return parsed++def is_env_var_truthy(key: str) -> bool:"""Return True if the env var is set and not a falsy sentinel ("false" or "0")."""value = get_optional_env(key)diff --git a/pipelex/system/registries/class_registry_utils.py b/pipelex/system/registries/class_registry_utils.pyindex d92b6f3bb..cdb66376f 100644--- a/pipelex/system/registries/class_registry_utils.py+++ b/pipelex/system/registries/class_registry_utils.py@@ -7,6 +7,8 @@ from typing import Anyfrom pipelex import logfrom pipelex.config import get_configfrom pipelex.runtime_hub import get_class_registry+from pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.misc.file_utils import find_files_in_dirfrom pipelex.tools.typing.exceptions import ModuleFileErrorfrom pipelex.tools.typing.module_inspector import (@@ -124,7 +126,9 @@ class ClassRegistryUtils:passexcept SyntaxError as exc:# Potentially problematic: invalid Python syntax may indicate broken code- log.warning(f"Syntax error in {python_file}: {exc}")+ log.warning(+ "A Python file has a syntax error and was not imported", fields={OTelLogAttr.FILE_PATH: str(python_file), **error_fields(exc=exc)}+ )@classmethoddef auto_register_all_subclasses(diff --git a/pipelex/system/registries/func_registry_utils.py b/pipelex/system/registries/func_registry_utils.pyindex 4a5aa3608..a1dba3107 100644--- a/pipelex/system/registries/func_registry_utils.py+++ b/pipelex/system/registries/func_registry_utils.py@@ -8,6 +8,8 @@ from typing import Anyfrom pipelex import logfrom pipelex.config import get_configfrom pipelex.system.registries.func_registry import func_registry, pipe_func+from pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.misc.file_utils import find_files_in_dirfrom pipelex.tools.typing.exceptions import ModuleFileErrorfrom pipelex.tools.typing.module_inspector import import_module_from_file_if_has_decorated_functions@@ -29,7 +31,9 @@ class FuncRegistryUtils:functions_registered = 0if not hasattr(package, "__path__"):- log.warning(f"Package {package_name} has no __path__ attribute, cannot walk modules")+ log.warning(+ "A PipeFunc package is a plain module with no submodules to walk, so nothing was registered", fields={"module_name": package_name}+ )return 0log.verbose(f"Walking package {package_name} at {package.__path__}")@@ -65,7 +69,10 @@ class FuncRegistryUtils:reason=eligibility_error,source_file=modname,)- log.warning(f"Function '{func_name}' in '{modname}' has @pipe_func() decorator but is not eligible: {eligibility_error}")+ log.warning(+ "A function decorated with @pipe_func is not eligible, and was not registered",+ fields={"function_name": func_name, "module_name": modname, "eligibility_error": eligibility_error},+ )return functions_registered@@ -195,7 +202,10 @@ class FuncRegistryUtils:reason=eligibility_error,source_file=str(file_path),)- log.warning(f"Function '{func_name}' in '{file_path}' has @pipe_func() decorator but is not eligible: {eligibility_error}")+ log.warning(+ "A function decorated with @pipe_func is not eligible, and was not registered",+ fields={"function_name": func_name, OTelLogAttr.FILE_PATH: str(file_path), "eligibility_error": eligibility_error},+ )except ModuleFileError:# Expected: file validation issues (directories with .py extension, etc.)pass@@ -205,10 +215,16 @@ class FuncRegistryUtils:# is essential: the only downstream symptom is an opaque "Function '<name>' not found in# registry" raised much later by the PipeFunc validator, with the real ImportError (the# actual cause) otherwise swallowed here and invisible.- log.warning(f"Could not import '{file_path}' while registering PipeFuncs; its functions are unavailable: {exc}")+ log.warning(+ "A Python file could not be imported while registering PipeFuncs, so its functions are unavailable",+ fields={OTelLogAttr.FILE_PATH: str(file_path), **error_fields(exc=exc)},+ )except SyntaxError as exc:# Potentially problematic: invalid Python syntax may indicate broken code- log.warning(f"Syntax error in {file_path}: {exc}")+ log.warning(+ "A Python file has a syntax error, so its PipeFuncs are unavailable",+ fields={OTelLogAttr.FILE_PATH: str(file_path), **error_fields(exc=exc)},+ )@classmethoddef _find_functions_in_module(diff --git a/pipelex/system/telemetry/otel_constants.py b/pipelex/system/telemetry/otel_constants.pyindex 1402e3aa9..f727d3198 100644--- a/pipelex/system/telemetry/otel_constants.py+++ b/pipelex/system/telemetry/otel_constants.py@@ -62,6 +62,20 @@ class GenAISpanAttr(StrEnum):COMPLETION_CONTENT = "gen_ai.completion.0.content"+class OTelLogAttr(StrEnum):+ """OpenTelemetry semantic-convention attribute keys that name a log line's fields, written verbatim so an OTLP sink emits them untranslated.++ Only the keys more than one call site uses are here; a key used once is spelled at its call. The handled+ exception's `error.type` and `error.message` are `pipelex.tools.log.error_fields`'s, and the `gen_ai.*` keys+ are `GenAISpanAttr`'s.+ """++ FILE_PATH = "file.path"+ URL_FULL = "url.full"+ USER_ID = "user.id"+ HTTP_RESPONSE_STATUS_CODE = "http.response.status_code"++class PostHogAttr(StrEnum):"""PostHog AI analytics attribute keys."""diff --git a/pipelex/system/telemetry/telemetry_loader.py b/pipelex/system/telemetry/telemetry_loader.pyindex 9289a9510..f01861d65 100644--- a/pipelex/system/telemetry/telemetry_loader.py+++ b/pipelex/system/telemetry/telemetry_loader.py@@ -19,7 +19,6 @@ from pathlib import Pathfrom pydantic import ValidationError-from pipelex import logfrom pipelex.core.validation import report_validation_errorfrom pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.configuration.config_surface import (@@ -142,5 +141,5 @@ def _telemetry_config_the_ledger_can_explain(telemetry_config = TelemetryConfig.model_validate(substituted)except (UnknownVarPrefixError, ValidationError):return None- log.warning(stale_configuration_warning(plans=replayed.plans, walked_dirs=config_manager.existing_config_dirs))+ stale_configuration_warning(plans=replayed.plans, walked_dirs=config_manager.existing_config_dirs).emit()return telemetry_configdiff --git a/pipelex/system/telemetry/telemetry_manager.py b/pipelex/system/telemetry/telemetry_manager.pyindex ada357c3a..56e24808e 100644--- a/pipelex/system/telemetry/telemetry_manager.py+++ b/pipelex/system/telemetry/telemetry_manager.py@@ -21,6 +21,7 @@ from pipelex.system.telemetry.otel_factory import OtelFactoryfrom pipelex.system.telemetry.telemetry_config import PostHogMode, TelemetryConfig, TelemetryRedactionConfigfrom pipelex.system.telemetry.telemetry_identity import RunIdentityPolicy, StreamIdentityRule, TelemetryIdentityfrom pipelex.system.telemetry.telemetry_manager_abstract import TelemetryManagerAbstract+from pipelex.tools.log.error_fields import error_fieldsif TYPE_CHECKING:from opentelemetry.sdk.trace import TracerProvider as OTelTracerProvider@@ -109,16 +110,21 @@ class TelemetryManager(TelemetryManagerAbstract):)def _handle_transmission_error( # kw-only: ignore — PostHog on_error callback, invoked positionally as (error, items)- self, error: Exception | None, _items: list[dict[str, Any]]+ self, error: Exception | None, items: list[dict[str, Any]]) -> None:"""Handle errors that occur during custom telemetry transmission.+ A warning rather than an error: the run the events describe is unaffected, and what was+ lost is the operator's own telemetry, whose endpoint or key is what to check. The callback+ runs outside any `except` block, so the exception rides as fields; the items are counted,+ never logged, since they are the events' own properties.+Args:error: The transmission error that occurred- _items: List of telemetry items that failed to send+ items: List of telemetry items that failed to send"""if error:- log.error(f"Telemetry transmission error: {error}")+ log.warning("Telemetry events could not be sent to PostHog", fields={"event_count": len(items), **error_fields(exc=error)})def _wrap_capture_exception(self, client: Posthog) -> None:"""Wrap a PostHog client's capture_exception method to sanitize exception messages.@@ -375,7 +381,10 @@ class TelemetryManager(TelemetryManagerAbstract):self._capture_custom_event(event_name, properties=tracked_properties, identity=TelemetryIdentity.make_anonymous())case PostHogMode.IDENTIFIED:if not self.telemetry_config.custom_posthog.user_id:- log.error(f"Could not track event '{event_name}' as identified because user_id is not set, tracking as anonymous")+ log.warning(+ "An event could not be tracked as identified because no user_id is set, and was tracked as anonymous",+ fields={"event_name": event_name},+ )self._capture_custom_event(event_name, properties=tracked_properties, identity=TelemetryIdentity.make_anonymous())else:self._capture_custom_event(@@ -442,9 +451,11 @@ class TelemetryManager(TelemetryManagerAbstract):log.verbose("Force-enabling Portkey logging (debug mode) because custom_portkey.force_debug_enabled is set in telemetry configuration")is_debug = Trueif is_debug and is_env_var_truthy(OTelConstants.DO_NOT_TRACK_ENV_VAR_KEY):- log.warning(- f"Disabling Custom Portkey logging (debug mode) "- f"because '{OTelConstants.DO_NOT_TRACK_ENV_VAR_KEY}' is set and that setting takes precedence"+ # DEBUG rather than WARNING: honouring DO_NOT_TRACK over every other setting is the documented rule, not a+ # degradation, and this runs on every Portkey call.+ log.debug(+ "Portkey logging (debug mode) is off because DO_NOT_TRACK takes precedence",+ fields={"env_var": OTelConstants.DO_NOT_TRACK_ENV_VAR_KEY},)is_debug = Falsereturn is_debug@@ -452,7 +463,8 @@ class TelemetryManager(TelemetryManagerAbstract):@overridedef is_custom_portkey_tracing_enabled(self) -> bool:if self.telemetry_config.custom_portkey.force_tracing_enabled and not is_env_var_truthy(OTelConstants.DO_NOT_TRACK_ENV_VAR_KEY):- log.info("Force-enabling Portkey tracing because custom_portkey.force_tracing_enabled is set in telemetry configuration")+ # DEBUG, not INFO: this is asked on every Portkey inference call, and a setting the user chose is no milestone.+ log.debug("Force-enabling Portkey tracing because custom_portkey.force_tracing_enabled is set in telemetry configuration")return Trueelse:return Falsediff --git a/pipelex/tools/log/console_fields.py b/pipelex/tools/log/console_fields.pyindex 4cea282cb..903684bf1 100644--- a/pipelex/tools/log/console_fields.py+++ b/pipelex/tools/log/console_fields.py@@ -8,12 +8,16 @@ third-party library stamped ever shows. The run identifiers and ``data`` are lefidentifiers are the same on every line of a run and would drown the message, and ``data`` is the structuredcontent the message already renders, which is why the dispatch never stamps a layout on a call carrying it.-A value renders on one line: a string bare unless it is empty or holds a space, an equals sign, a quote, a-backslash or a character a terminal would act on, in which case it is quoted, with a backslash and a quote-escaped by a backslash and that character written as its escape; anything else as compact JSON; and the-whole cut short past ``FIELD_VALUE_MAX_LENGTH``, or past the generous length ``FIELD_MAX_LENGTHS`` gives a field of-its own, a handled exception's text. A key is written the same way, so a field name holding a line break, a space, an-equals sign or an escape sequence can forge neither a line nor a pair. Redaction has+A value renders on one line: a string as itself, anything else as compact JSON, and the text either gives bare unless+it is empty or holds a space, an equals sign, a quote, a backslash or a character a terminal would act on, in which+case it is quoted, with a backslash and a quote escaped by a backslash and that character written as its escape. So a+list of strings, whose JSON holds quotes, is always quoted, while a number or a list of numbers stays bare. The text+is cut short past ``FIELD_VALUE_MAX_LENGTH``, or past the generous length ``FIELD_MAX_LENGTHS`` gives a field of its+own, a handled exception's text and a template finding's. A value is cut at its end, except a path's, from+``LEFT_CUT_FIELDS``, which is cut at its start so the file's name stays. The text is cut before it is quoted and+escaped, so a quoted value keeps both its quotes and no escape is split, and the cut can never leave an unbalanced+quote or bracket whose tail reads as another pair. A key is written the same way, so a field name+holding a line break, a space, an equals sign or an escape sequence can forge neither a line nor a pair. Redaction hasalready run when the console renders a record, so what is rendered is what the scrub left.Colour follows the name the field was given, from ``FIELD_STYLES``, wherever the field appears, and whatever@@ -71,8 +75,17 @@ TRUNCATION_MARK = "…"# error's every line or git's stderr, would flood the console uncut.ERROR_MESSAGE_MAX_LENGTH = 2000+# The text of a PipeDocGen template finding, which is the actionable part of its warning, as a handled exception's+# text is the actionable part of its line.+FINDING_MESSAGE_FIELD = "finding_message"+# The fields the console cuts at a length of their own, by the name the caller gave them.-FIELD_MAX_LENGTHS: dict[str, int] = {ERROR_MESSAGE_FIELD: ERROR_MESSAGE_MAX_LENGTH}+FIELD_MAX_LENGTHS: dict[str, int] = {ERROR_MESSAGE_FIELD: ERROR_MESSAGE_MAX_LENGTH, FINDING_MESSAGE_FIELD: ERROR_MESSAGE_MAX_LENGTH}++# The fields carrying a path on disk, by the name the caller gave them, which the console cuts at their start rather+# than at their end: what tells one file from another is its name, at the end, while the start is the directory most+# lines of a run share.+LEFT_CUT_FIELDS = frozenset({"file.path", "file.name", "backup_path", "template_file"})FIELD_SEPARATOR = " "KEY_VALUE_SEPARATOR = "="@@ -122,7 +135,8 @@ def field_suffix_segments(*, fields: Mapping[str, Any], presented_fields: frozen# The key is written like a value: a name a caller chose can hold a line break that would forge a# line, a space that would read as two pairs or an escape sequence the terminal would act on.segments.append((f"{format_field_value(value=name)}{KEY_VALUE_SEPARATOR}", FIELD_KEY_STYLE))- segments.append((format_field_value(value=value, max_length=field_max_length(name=name)), field_style(name=name)))+ rendered_value = format_field_value(value=value, max_length=field_max_length(name=name), is_cut_at_start=field_is_cut_at_start(name=name))+ segments.append((rendered_value, field_style(name=name)))return segments@@ -134,9 +148,28 @@ def field_max_length(*, name: str) -> int:return FIELD_MAX_LENGTHS.get(given_field_name(name=name), FIELD_VALUE_MAX_LENGTH)-def format_field_value(*, value: Any, max_length: int = FIELD_VALUE_MAX_LENGTH) -> str:- """A field's value as the suffix prints it: one line, a string quoted when it could forge a pair, cut short past ``max_length``."""- return _truncated(text=_one_line(value=value, is_quoting_strings=True), max_length=max_length)+def field_is_cut_at_start(*, name: str) -> bool:+ """Whether the console cuts a field's value at its start, keeping its end: a path's, from ``LEFT_CUT_FIELDS``.++ Read off the name the caller gave rather than the one it landed on, as the style is.+ """+ return given_field_name(name=name) in LEFT_CUT_FIELDS+++def format_field_value(*, value: Any, max_length: int = FIELD_VALUE_MAX_LENGTH, is_cut_at_start: bool = False) -> str:+ """A field's value as the suffix prints it: one line, quoted when it could forge a pair, cut short past ``max_length``.++ The cut drops the end of the value and marks it with a trailing ``TRUNCATION_MARK``, or, with ``is_cut_at_start``,+ drops its start and marks it with a leading one. The value's text, a string's own or a JSON rendering, is cut before+ it is quoted and escaped: cutting the quoted rendering would drop a quote, or split an escape, and the value's tail+ would then read as pairs of its own, ``file.path=…/file fake=value.txt"``. A JSON rendering is quoted by the same+ rule as a string, since a cut one can leave a string unterminated, ``paths=["/x/My dir/a b=c/…``, whose tail reads+ as a pair of its own.+ """+ string_text = _string_value_text(value=value)+ text = string_text if string_text is not None else _non_string_text(value=value)+ cut_text = _truncated_at_start(text=text, max_length=max_length) if is_cut_at_start else _truncated(text=text, max_length=max_length)+ return _string_text(text=cut_text, is_quoting_strings=True)def format_layout_value(*, value: Any) -> str:@@ -150,14 +183,29 @@ def one_line_text(*, text: str) -> str:def _one_line(*, value: Any, is_quoting_strings: bool) -> str:- if isinstance(value, str):- return _string_text(text=value, is_quoting_strings=is_quoting_strings)+ string_text = _string_value_text(value=value)+ if string_text is not None:+ return _string_text(text=string_text, is_quoting_strings=is_quoting_strings)+ return one_line_text(text=_non_string_text(value=value))+++def _non_string_text(*, value: Any) -> str:+ """The text of a value not written as a string: a non-finite float's spelling, else compact JSON, neither escaped yet."""if isinstance(value, float) and not math.isfinite(value):# ``NaN``, ``Infinity`` or ``-Infinity``, bare, as the wire sinks spell it.return str(spell_non_finite(value=value))+ return _compact_json(value=value)+++def _string_value_text(*, value: Any) -> str | None:+ """The raw text of a value written as a string, a string itself or what is neither JSON nor a non-finite float; else ``None``."""+ if isinstance(value, str):+ return value+ if isinstance(value, float) and not math.isfinite(value):+ return Noneif _renders_as_json(value=value):- return one_line_text(text=_compact_json(value=value))- return _string_text(text=str(value), is_quoting_strings=is_quoting_strings)+ return None+ return str(value)def _renders_as_json(*, value: Any) -> bool:@@ -195,3 +243,9 @@ def _truncated(*, text: str, max_length: int) -> str:if len(text) <= max_length:return textreturn f"{text[: max_length - len(TRUNCATION_MARK)]}{TRUNCATION_MARK}"+++def _truncated_at_start(*, text: str, max_length: int) -> str:+ if len(text) <= max_length:+ return text+ return f"{TRUNCATION_MARK}{text[len(text) - max_length + len(TRUNCATION_MARK) :]}"diff --git a/pipelex/tools/log/error_fields.py b/pipelex/tools/log/error_fields.pyindex f486d2603..515b7649d 100644--- a/pipelex/tools/log/error_fields.py+++ b/pipelex/tools/log/error_fields.py@@ -1,10 +1,19 @@"""The fields a handled exception rides a log line as, when the line carries no traceback.-A line at WARNING or below about an exception the code expected and recovered from names the exception's class and-its text in two fields, and never splices the exception into its message: the message stays the same on every-emission, so a log store groups and counts it, while the fields say what went wrong this time and get the redaction's-field treatment, control characters escaped included. No traceback rides along: a handled, expected failure is not a-bug in Pipelex's frames, and only ``error`` and ``critical`` take ``include_exception``.+A line about an exception names the exception's class and its text in two fields, and never splices the exception+into its message: the message stays the same on every emission, so a log store groups and counts it, while the fields+say what went wrong this time and get the redaction's field treatment, control characters escaped included. No+traceback rides along: at WARNING and below a handled, expected failure is not a bug in Pipelex's frames, and at ERROR+an exception that is re-raised has its traceback written by whoever catches it.++A pydantic ``ValidationError`` is written as its locations and reasons only: its own text quotes every value it+refused, which is payload, a run's inputs or a model's response, and no log line carries payload. A reason is pydantic's+own message, kept only when nothing in it came from the input: pydantic wrote all of it, and every value its template+fills in comes from the schema, a bound, the expected values or a discriminator's name. Otherwise the error is written as+its location and its error type, ``date: value_error``: a custom validator's message is the validator's text, which can+quote the value it rejected, and several of pydantic's own templates quote the input too, an unknown tag of a+discriminated union, the character a UUID could not parse, a parser's own complaint. An ``extra_forbidden`` error's last+location component is the key the caller sent, which is input by definition, so its location stops at its parent.``error.type`` is the OpenTelemetry semantic-convention key for the class of error an operation ended with.``error.message`` is the key the conventions gave an error's text before deprecating the general attribute in favour@@ -12,6 +21,12 @@ of domain-specific ones; it is kept here as ``error.type``'s companion because tsinks, which write them for a record that carries the exception itself and prefix a field spelling one."""+from typing import cast, get_args++from pydantic import ValidationError+from pydantic_core import ErrorDetails, PydanticKnownError+from pydantic_core.core_schema import ErrorType+#: The class of the handled exception, by its name.ERROR_TYPE_FIELD = "error.type"@@ -19,15 +34,105 @@ ERROR_TYPE_FIELD = "error.type"ERROR_MESSAGE_FIELD = "error.message"+#: The keys of a pydantic error's context whose values come from the schema, never from the input: the bounds a field+#: declares, the values, tags, schemes or version it expects, a discriminator's name, a pattern, and the class or the kind+#: of collection it validates into. A context holding any other key, the input's own tag, its length, or a parser's or+#: a validator's ``error`` text, which can quote the input, keeps its message off the line.+SCHEMA_CONTEXT_KEYS = frozenset(+ {+ "gt",+ "ge",+ "lt",+ "le",+ "multiple_of",+ "min_length",+ "max_length",+ "max_digits",+ "decimal_places",+ "whole_digits",+ "expected",+ "expected_tags",+ "expected_schemes",+ "expected_version",+ "discriminator",+ "pattern",+ "class_name",+ "class",+ "field_type",+ "method_name",+ "tz_expected",+ "encoding",+ }+)++#: The error type of a key the model forbids, whose last location component is that key, as the caller sent it.+EXTRA_FORBIDDEN_ERROR_TYPE = "extra_forbidden"++#: Every error type pydantic itself knows how to word.+_PYDANTIC_ERROR_TYPES: frozenset[str] = frozenset(get_args(ErrorType))+++def _pydantic_own_reason(*, error: ErrorDetails) -> str | None:+ """The error's message when nothing in it came from the input, or ``None`` when any of it may have.++ A type pydantic does not know is a ``PydanticCustomError``'s, whose message the validator wrote. A known type is+ kept only when every key of its context is in ``SCHEMA_CONTEXT_KEYS``, so that its template is filled from the+ schema alone, and when its message is exactly the one pydantic renders for it, which a ``PydanticCustomError``+ reusing a built-in type's name with a message of its own is not.+ """+ error_type = error["type"]+ if error_type not in _PYDANTIC_ERROR_TYPES:+ # A type pydantic does not know, and so a `PydanticCustomError`'s, worded by the validator.+ return None+ context = error.get("ctx")+ if context is not None and not SCHEMA_CONTEXT_KEYS.issuperset(context):+ # A value of the context may come from the input, or be a validator's or a parser's own text.+ return None+ try:+ own_message = PydanticKnownError(cast("ErrorType", error_type), context).message()+ except (KeyError, TypeError, ValueError):+ # Not with the context its template needs: the message is not pydantic's.+ return None+ if own_message != error["msg"]:+ return None+ return own_message+++def _validation_error_text(*, validation_error: ValidationError) -> str:+ """Each error of a ``ValidationError`` as its location and its reason, never the input it refused.++ The reason is pydantic's own message, or the error's type where the message may hold something of the input, since+ a validator's text, or one of pydantic's templates, can quote the very value it rejected. A forbidden key's location+ stops at its parent, the key being the caller's own text.+ """+ located_reasons: list[str] = []+ for error in validation_error.errors(include_url=False, include_input=False):+ location_parts = error["loc"][:-1] if error["type"] == EXTRA_FORBIDDEN_ERROR_TYPE else error["loc"]+ location = ".".join(str(part) for part in location_parts)+ reason = _pydantic_own_reason(error=error) or error["type"]+ located_reasons.append(f"{location}: {reason}" if location else reason)+ return "; ".join(located_reasons) or validation_error.title+++def _exception_text(*, exc: BaseException) -> str:+ """The text a handled exception is logged with: its own, except a ``ValidationError``'s, which quotes payload."""+ if isinstance(exc, ValidationError):+ return _validation_error_text(validation_error=exc)+ return str(exc)++def error_fields(*, exc: BaseException, text: str | None = None) -> dict[str, str]:"""The ``error.type`` and ``error.message`` fields of a handled exception, to spread into a call's ``fields``.Args:exc: The exception the line is about.- text: The text to carry instead of ``str(exc)``, for a line whose diagnosis is the exception's cause chain- rather than its own text.+ text: The text to carry instead of the exception's own, for a line whose diagnosis is the exception's cause+ chain rather than its own text.Returns:- ``{"error.type": <the exception's class name>, "error.message": <its text>}``.+ ``{"error.type": <the exception's class name>, "error.message": <its text>}``, the text of a pydantic+ ``ValidationError`` being its locations and reasons, without the values it refused, without a forbidden key's+ name, and without any message that may quote the input, a custom validator's or one of pydantic's own, which+ is written as its error type."""- return {ERROR_TYPE_FIELD: type(exc).__name__, ERROR_MESSAGE_FIELD: str(exc) if text is None else text}+ return {ERROR_TYPE_FIELD: type(exc).__name__, ERROR_MESSAGE_FIELD: _exception_text(exc=exc) if text is None else text}diff --git a/pipelex/tools/misc/dict_utils.py b/pipelex/tools/misc/dict_utils.pyindex 26b1a6621..8b9eb27d1 100644--- a/pipelex/tools/misc/dict_utils.py+++ b/pipelex/tools/misc/dict_utils.py@@ -4,7 +4,6 @@ import refrom collections.abc import Callablefrom typing import Any, TypeVar, cast-from pipelex import logfrom pipelex.system.exceptions import NestedKeyConflictErrorK = TypeVar("K")@@ -128,8 +127,6 @@ def substitute_nested_in_context(context: dict[str, Any], *, extra_params: dict[if not extra_params:return context- original_context = context.copy()-for key, value in extra_params.items():if "." not in key:# Simple key without dots - add directly to context@@ -147,8 +144,6 @@ def substitute_nested_in_context(context: dict[str, Any], *, extra_params: dict[elif not hasattr(current[segment], "__getitem__"):# Conflict: trying to nest under a primitive value (string, int, etc.)error_message = f"Cannot set nested key '{key}': '{segment}' is not a dict-like object"- log.error(original_context, title="original_context")- log.error(extra_params, title="extra_params")raise NestedKeyConflictError(error_message)elif not hasattr(current[segment], "__setitem__"):# Conflict: trying to nest under an immutable object (e.g., StuffArtefact)@@ -157,8 +152,6 @@ def substitute_nested_in_context(context: dict[str, Any], *, extra_params: dict[f"which is immutable (supports reading but not writing). "f"Use the appropriate filter (e.g., | with_images) instead of nested key substitution.")- log.error(original_context, title="original_context")- log.error(extra_params, title="extra_params")raise NestedKeyConflictError(error_message)# Navigate into the nested dictcurrent = current[segment]diff --git a/pipelex/tracing/activity_event_log.py b/pipelex/tracing/activity_event_log.pyindex bfe55d758..71e83d457 100644--- a/pipelex/tracing/activity_event_log.py+++ b/pipelex/tracing/activity_event_log.py@@ -92,13 +92,12 @@ class ActivityEventLogCache:if cls._fallback_logged:returncls._fallback_logged = True+ # Activities always emit through the per-process activity event log, by design: activity emissions must never+ # land in the workflow's replay-rebuilt buffer (replay determinism), whether the activity runs co-located with+ # the workflow router or on a separate worker pool.log.info(- f"Activity-side usage event emission engaged "- f"(workflow_id={workflow_id}, writer_id={writer_id}). "- "Activities always emit through the per-process activity event log, by design: "- "activity emissions must never land in the workflow's replay-rebuilt buffer "- "(replay determinism), whether the activity runs co-located with the workflow "- "router or on a separate worker pool."+ "Activity-side usage event emission engaged, through this process's activity event log",+ fields={"writer_id": writer_id, "workflow_id": workflow_id},)@classmethoddiff --git a/pipelex/tracing/dynamodb_event_log.py b/pipelex/tracing/dynamodb_event_log.pyindex e3991e54d..5ee578217 100644--- a/pipelex/tracing/dynamodb_event_log.py+++ b/pipelex/tracing/dynamodb_event_log.py@@ -19,10 +19,11 @@ from typing_extensions import overridefrom pipelex import logfrom pipelex.system.exceptions import MissingDependencyError+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.typing.pydantic_utils import format_pydantic_validation_errorfrom pipelex.tracing.event_log_protocol import EventLogProtocolfrom pipelex.tracing.exceptions import EventLogReadError, EventLogSchemaMismatchError, EventLogSetupError-from pipelex.tracing.trace_events import AnyTraceEvent, TraceEvent+from pipelex.tracing.trace_events import AnyTraceEvent, TraceEvent, json_invalid_messagetry:import boto3@@ -156,7 +157,10 @@ class DynamoDBEventLog(EventLogProtocol):for item in items:payload = item.get("payload")if payload is None:- log.warning(f"Skipping DynamoDB item with missing payload: PK={item.get('PK')}, SK={item.get('SK')}")+ log.warning(+ "A trace event item in DynamoDB has no payload, and was skipped",+ fields={"pipeline_run_id": pipeline_run_id, "sort_key": item.get("SK")},+ )continuetry:event = _any_trace_event_adapter.validate_json(payload)@@ -167,9 +171,10 @@ class DynamoDBEventLog(EventLogProtocol):# — so it is counted and raised rather than skipped, which would have handed the caller a# silently truncated record of the run. This is the shape that persists across a rolling# deploy, where one image writes what another reads back.- if any(error["type"] == "json_invalid" for error in exc.errors()):+ if (json_error := json_invalid_message(validation_error=exc)) is not None:log.warning(- f"Skipping unparseable DynamoDB item PK={item.get('PK')} SK={item.get('SK')}: {format_pydantic_validation_error(exc)}"+ "A trace event item in DynamoDB is not valid JSON, and was skipped",+ fields={"pipeline_run_id": pipeline_run_id, "sort_key": item.get("SK"), **error_fields(exc=exc, text=json_error)},)continuerefused_count += 1diff --git a/pipelex/tracing/graphspec_assembler.py b/pipelex/tracing/graphspec_assembler.pyindex 5f823fe77..867d69775 100644--- a/pipelex/tracing/graphspec_assembler.py+++ b/pipelex/tracing/graphspec_assembler.py@@ -222,7 +222,7 @@ class _AssemblerState:elif isinstance(event, UsageReportEvent):self._handle_usage_report(event)else:- log.warning(f"Unknown event type: {type(event).__name__}")+ log.warning("A trace event of a type the assembler does not handle was dropped", fields={"trace_event_type": type(event).__name__})# Mark any still-running nodes as CANCELEDself._mark_canceled_nodes()@@ -289,7 +289,10 @@ class _AssemblerState:def _handle_pipe_end_success(self, event: PipeEndSuccessEvent) -> None:node_data = self._nodes.get(event.node_id)if node_data is None:- log.warning(f"PipeEndSuccessEvent for unknown node: {event.node_id}")+ log.warning(+ "A trace event names a node the trace never started, and was dropped",+ fields={"trace_event_type": type(event).__name__, "node_id": event.node_id},+ )returnnode_data.ended_at = event.ended_at@@ -317,7 +320,10 @@ class _AssemblerState:def _handle_pipe_end_error(self, event: PipeEndErrorEvent) -> None:node_data = self._nodes.get(event.node_id)if node_data is None:- log.warning(f"PipeEndErrorEvent for unknown node: {event.node_id}")+ log.warning(+ "A trace event names a node the trace never started, and was dropped",+ fields={"trace_event_type": type(event).__name__, "node_id": event.node_id},+ )returnnode_data.ended_at = event.ended_at@@ -327,7 +333,10 @@ class _AssemblerState:def _handle_pipe_end_skipped(self, event: PipeEndSkippedEvent) -> None:node_data = self._nodes.get(event.node_id)if node_data is None:- log.warning(f"PipeEndSkippedEvent for unknown node: {event.node_id}")+ log.warning(+ "A trace event names a node the trace never started, and was dropped",+ fields={"trace_event_type": type(event).__name__, "node_id": event.node_id},+ )returnnode_data.ended_at = event.ended_at@@ -369,7 +378,10 @@ class _AssemblerState:def _handle_controller_output(self, event: ControllerOutputEvent) -> None:node_data = self._nodes.get(event.node_id)if node_data is None:- log.warning(f"ControllerOutputEvent for unknown node: {event.node_id}")+ log.warning(+ "A trace event names a node the trace never started, and was dropped",+ fields={"trace_event_type": type(event).__name__, "node_id": event.node_id},+ )returnnode_data.output_specs.append(event.output_spec)@@ -388,7 +400,10 @@ class _AssemblerState:def _handle_execution_data(self, event: ExecutionDataEvent) -> None:node_data = self._nodes.get(event.node_id)if node_data is None:- log.warning(f"ExecutionDataEvent for unknown node: {event.node_id}")+ log.warning(+ "A trace event names a node the trace never started, and was dropped",+ fields={"trace_event_type": type(event).__name__, "node_id": event.node_id},+ )returnnode_data.execution_data.update(event.execution_data)@@ -588,7 +603,9 @@ class _AssemblerState:own_usages = own_usages_by_node.get(reported_node_id)if own_usages is None:if reported_node_id != UNATTRIBUTED_NODE_ID:- log.warning(f"UsageReportEvent for unknown node: {reported_node_id}")+ log.warning(+ "A usage report names a node the trace never started, so its usage is left unattributed", fields={"node_id": reported_node_id}+ )unattributed_usages.extend(usages)continueown_usages.extend(usages)diff --git a/pipelex/tracing/ndjson_event_log.py b/pipelex/tracing/ndjson_event_log.pyindex 87a848d45..77132792e 100644--- a/pipelex/tracing/ndjson_event_log.py+++ b/pipelex/tracing/ndjson_event_log.py@@ -13,10 +13,12 @@ from pydantic import TypeAdapter, ValidationErrorfrom typing_extensions import overridefrom pipelex import log+from pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.typing.pydantic_utils import format_pydantic_validation_errorfrom pipelex.tracing.event_log_protocol import EventLogProtocolfrom pipelex.tracing.exceptions import EventLogSchemaMismatchError-from pipelex.tracing.trace_events import AnyTraceEvent, TraceEvent+from pipelex.tracing.trace_events import AnyTraceEvent, TraceEvent, json_invalid_message_any_trace_event_adapter: TypeAdapter[TraceEvent] = TypeAdapter(AnyTraceEvent)@@ -160,8 +162,16 @@ class NdjsonEventLog(EventLogProtocol):# written whole by a version whose event shape this one no longer accepts. The refusal# names fields rather than quoting them: it travels into the run's assembly errors, and# the pydantic error's own text quotes the traced values it refused.- if any(error["type"] == "json_invalid" for error in validation_error.errors()):- log.warning(f"Skipping corrupt line in {ndjson_path}:{line_number} — {validation_error}")+ if (json_error := json_invalid_message(validation_error=validation_error)) is not None:+ # The parse error's own message, never the exception's text, which quotes the line.+ log.warning(+ "A corrupt line of a trace event log, not valid JSON, was skipped",+ fields={+ OTelLogAttr.FILE_PATH: str(ndjson_path),+ "line_number": line_number,+ **error_fields(exc=validation_error, text=json_error),+ },+ )continuerefused_count += 1if first_refusal is None:diff --git a/pipelex/tracing/trace_events.py b/pipelex/tracing/trace_events.pyindex b0592c632..997f666f5 100644--- a/pipelex/tracing/trace_events.py+++ b/pipelex/tracing/trace_events.py@@ -9,7 +9,7 @@ from datetime import datetimefrom enum import StrEnumfrom typing import Annotated, Any, Literal-from pydantic import BaseModel, Field+from pydantic import BaseModel, Field, ValidationErrorfrom pipelex.graph.condition_output_merge import ConditionOutputMergefrom pipelex.graph.graphspec import EdgeKind, ErrorSpec, IOSpec, NodeKind@@ -224,3 +224,17 @@ AnyTraceEvent = Annotated[| UsageReportEvent,Field(discriminator="event_kind"),]+++def json_invalid_message(*, validation_error: ValidationError) -> str | None:+ """The parse error of a stored trace event that is not JSON at all, or `None` when it parsed and was refused.++ `validate_json` reports unparseable input as a `json_invalid` entry rather than raising `JSONDecodeError`, so+ the two cases are told apart by the entry's type. The entry's message says where the parse stopped and quotes+ nothing, while the exception's own text quotes the stored record whole, traced values included: a reader that+ logs why it skipped a record logs this message, never the exception's text.+ """+ for error in validation_error.errors():+ if error["type"] == "json_invalid":+ return error["msg"]+ return Nonediff --git a/pipelex/tracing/usage_attribution.py b/pipelex/tracing/usage_attribution.pyindex ff085ede7..9c6c1d778 100644--- a/pipelex/tracing/usage_attribution.py+++ b/pipelex/tracing/usage_attribution.py@@ -227,7 +227,7 @@ def _walk_subtree(if node_id in subtree_by_node:continueif node_id in in_progress:- log.warning(f"Cycle in graph node parentage at '{node_id}'; subtree usage rollup will be incomplete")+ log.warning("The node parentage of a graph has a cycle, so a subtree's usage rollup is incomplete", fields={"node_id": node_id})continuein_progress.add(node_id)diff --git a/tests/e2e/pipelex/cli/test_migrate_commands.py b/tests/e2e/pipelex/cli/test_migrate_commands.pyindex b7fbc2202..da74b2e73 100644--- a/tests/e2e/pipelex/cli/test_migrate_commands.py+++ b/tests/e2e/pipelex/cli/test_migrate_commands.py@@ -127,9 +127,9 @@ gemini = { tag_style = "xml" }RETIRED_BACKEND_KEY = "prompting_target"PLANTED_BACKEND_VALUE = "a_prompting_target_no_report_may_ever_render"-# How `stale_configuration_warning` opens. Matched in full rather than on a fragment: the same boot-# also prints a deck-staleness notice, and "out of date" appears in both.-STALE_CONFIGURATION_OPENING = "Your configuration is out of date"+# How each line of `stale_configuration_warning` opens. Matched in full rather than on a fragment: the+# same boot also prints a deck-staleness notice, and "out of date" appears in both.+STALE_CONFIGURATION_OPENING = "A configuration file is out of date and was read as if it had been migrated"def _old_shape_telemetry_document() -> str:diff --git a/tests/integration/pipelex/libraries/test_vendored_methods_dirs.py b/tests/integration/pipelex/libraries/test_vendored_methods_dirs.pyindex 77655c53b..f67623e3b 100644--- a/tests/integration/pipelex/libraries/test_vendored_methods_dirs.py+++ b/tests/integration/pipelex/libraries/test_vendored_methods_dirs.py@@ -95,10 +95,12 @@ class TestVendoredMethodsDirs:assert _helper_description(library=library, alias=pinned_alias) == VENDORED_HELPERfinally:get_library_manager().teardown(library_id=library_id)- warnings = [record.message for record in caplog.records if record.levelno == logging.WARNING and "@v9.9.9" in record.message]- assert len(warnings) == 1, warnings- assert PROBE_ALIAS in warnings[0]- assert "1.0.0" in warnings[0]+ pin_warnings = [+ (record.__dict__["method_ref"], record.__dict__["package_version"])+ for record in caplog.records+ if record.getMessage() == "A method reference pins a tag, and the copy shipped with the request is another version, which is used"+ ]+ assert pin_warnings == [(pinned_alias, "1.0.0")]@pytest.mark.asyncio(loop_scope="class")async def test_the_runner_protocol_runs_the_shipped_dependency(self, tmp_path: Path, mocker: MockerFixture) -> None:diff --git a/tests/integration/pipelex/pipeline/dry_run_condition/test_outcome_isolation.py b/tests/integration/pipelex/pipeline/dry_run_condition/test_outcome_isolation.pyindex 1be5a04b5..b4fd8221d 100644--- a/tests/integration/pipelex/pipeline/dry_run_condition/test_outcome_isolation.py+++ b/tests/integration/pipelex/pipeline/dry_run_condition/test_outcome_isolation.py@@ -6,19 +6,22 @@ after the condition read the value a live run falls back to when nothing matches"""from collections.abc import Sequence+from typing import Anyimport pytestfrom pytest_mock import MockerFixturefrom pipelex.core.memory import working_memory as working_memory_module+from pipelex.core.memory.working_memory import STUFF_REPLACED_MESSAGEfrom pipelex.pipeline.dry_run_pipeline import dry_run_pipelinefrom tests.integration.pipelex.pipeline.dry_run_condition.graph_reading import input_named, node_by_code, only_outputfrom tests.integration.pipelex.pipeline.dry_run_condition.test_data import DryRunConditionTestData-def _replaced_key_warnings(warning_calls: Sequence[object], *, key: str) -> list[str]:- needle = f"Key '{key}' already exists in WorkingMemory and will be replaced"- return [str(call) for call in warning_calls if needle in str(call)]+def _replacements_of(debug_calls: Sequence[Any], *, stuff_name: str) -> list[str]:+ return [+ str(call) for call in debug_calls if call.args == (STUFF_REPLACED_MESSAGE,) and call.kwargs.get("fields", {}).get("stuff_name") == stuff_name+ ]@pytest.mark.asyncio(loop_scope="class")@@ -37,11 +40,11 @@ class TestDryRunConditionOutcomeIsolation:async def test_no_outcome_replaces_a_sibling_value_in_the_slot(self, mocker: MockerFixture) -> None:"""`follow_up` holds nothing before the condition, so no outcome may find it already written."""- warning_spy = mocker.spy(working_memory_module.log, "warning")+ debug_spy = mocker.spy(working_memory_module.log, "debug")await dry_run_pipeline(mthds_contents=[DryRunConditionTestData.REPORT_SHAPE_MTHDS])- assert _replaced_key_warnings(warning_spy.call_args_list, key="follow_up") == []+ assert _replacements_of(debug_spy.call_args_list, stuff_name="follow_up") == []async def test_the_default_outcome_names_the_shared_stuff(self) -> None:"""The default outcome runs last, so its value is the one the next step reads."""diff --git a/tests/integration/pipelex/pipes/operator/pipe_doc_gen/test_pipe_doc_gen_template_files.py b/tests/integration/pipelex/pipes/operator/pipe_doc_gen/test_pipe_doc_gen_template_files.pyindex c0ce082cf..3f893fe1a 100644--- a/tests/integration/pipelex/pipes/operator/pipe_doc_gen/test_pipe_doc_gen_template_files.py+++ b/tests/integration/pipelex/pipes/operator/pipe_doc_gen/test_pipe_doc_gen_template_files.py@@ -1,7 +1,9 @@from pathlib import Pathimport pytest+from pytest_mock import MockerFixture+from pipelex import logfrom pipelex.cogt.doc_gen.input_shape import InputShapeKindfrom pipelex.cogt.doc_gen.template_check import TemplateFinding, TemplateFindingSeverityfrom pipelex.pipeline.exceptions import ValidateBundleError@@ -80,13 +82,28 @@ class TestPipeDocGenTemplateFiles:assert request.inputs["thing"].kind == InputShapeKind.ANYassert request.inputs["invoice"].kind == InputShapeKind.STRUCTURE- async def test_warnings_alone_pass_and_print_nothing(self, tmp_path: Path, stub_engines: StubEngines) -> None:- """A warning is logged, not raised, and the dry run prints nothing."""+ async def test_warnings_alone_pass_and_print_nothing(self, tmp_path: Path, stub_engines: StubEngines, mocker: MockerFixture) -> None:+ """A warning is logged, not raised, and the dry run prints nothing.++ The line is the same for every finding, and the finding's own words and place ride as fields beside the step and its file.+ """+ warning_spy = mocker.spy(log, "warning")(tmp_path / "invoice.docx").write_bytes(b"docx bytes")bundle_path = write_bundle(directory=tmp_path, step_fields=_DOCX_TEMPLATE_STEP)- stub_engines.findings = [TemplateFinding(severity=TemplateFindingSeverity.WARNING, message="The notes are never printed")]+ stub_engines.findings = [+ TemplateFinding(severity=TemplateFindingSeverity.WARNING, message="The notes are never printed", location="the field notes on page 2")+ ]await validate_bundle(mthds_file_path=bundle_path)assert len(stub_engines.check_requests) == 1assert stub_engines.engine.jobs == []+ (finding_call,) = [+ call for call in warning_spy.call_args_list if call.args[0] == "The template check of a PipeDocGen found a warning in its template file"+ ]+ assert finding_call.kwargs["fields"] == {+ "pipe_code": "print_invoice",+ "template_file": "invoice.docx",+ "finding_message": "The notes are never printed",+ "finding_location": "the field notes on page 2",+ }diff --git a/tests/unit/pipelex/cli/test_graph_render_cmd.py b/tests/unit/pipelex/cli/test_graph_render_cmd.pyindex cba43047b..92923f15a 100644--- a/tests/unit/pipelex/cli/test_graph_render_cmd.py+++ b/tests/unit/pipelex/cli/test_graph_render_cmd.py@@ -1,4 +1,6 @@-"""`pipelex graph render` on a spec this version refuses: the diagnosis names the file exactly as the user wrote it.+"""`pipelex graph render` when rendering fails: on a spec this version refuses, the diagnosis names the file exactly as+the user wrote it, and on an unexpected error the log line carries the exception, whose traceback every sink writes its+own way, while the console names the exception's type and message and prints no traceback of its own.Boot, teardown and telemetry are mocked out so no real Pipelex is made; the console is swapped for onewriting to a buffer so the printed diagnosis can be read back.@@ -8,6 +10,8 @@ from __future__ import annotationsimport contextlibimport io+import json+import loggingfrom typing import TYPE_CHECKINGimport pytest@@ -15,16 +19,20 @@ import typerfrom rich.console import Consolefrom pipelex.cli.commands.graph_cmd import graph_render_cmd+from pipelex.tools.log.json_log_sink import EXCEPTION_KEY, LOGGER_KEY, MESSAGE_KEY, JsonLogSink+from tests.helpers.console_log_rendering import console_sink_on_buffer, installed_logif TYPE_CHECKING:from pathlib import Pathfrom pytest_mock import MockerFixture+ from pipelex.tools.log.log_sink import LogSink+GRAPH_CMD = "pipelex.cli.commands.graph_cmd"-class TestGraphRenderRefusedSpec:+class TestGraphRenderFailure:@pytest.mark.parametrize("bracketed_dir", ["[draft]", "[/old]"])def test_a_bracketed_path_prints_as_written(self, mocker: MockerFixture, tmp_path: Path, bracketed_dir: str) -> None:"""A path is the user's text, not Rich markup: `[draft]` used to be swallowed as a style tag, naming a@@ -59,3 +67,70 @@ class TestGraphRenderRefusedSpec:assert fields["error.type"] == "GraphSpecValidationError"assert str(spec_file) in fields["error.message"]assert "\\[" not in fields["error.message"]++ def test_an_unexpected_error_logs_its_traceback_once(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """The log line is a fixed message with the file, and carries the exception for every sink to write its traceback,+ the console under the line; the console prints no traceback of its own, which would show it twice.+ """+ mocker.patch(f"{GRAPH_CMD}.make_pipelex_for_cli")+ mocker.patch(f"{GRAPH_CMD}.Pipelex.teardown_if_needed")+ mocker.patch(f"{GRAPH_CMD}.tag")+ telemetry_manager = mocker.patch(f"{GRAPH_CMD}.get_telemetry_manager").return_value+ telemetry_manager.telemetry_context.return_value = contextlib.nullcontext()+ printed = io.StringIO()+ mocker.patch(f"{GRAPH_CMD}.get_console", return_value=Console(file=printed, width=1000))+ mocker.patch(f"{GRAPH_CMD}._do_graph_render", side_effect=RuntimeError("the renderer broke"))+ log_spy = mocker.patch(f"{GRAPH_CMD}.log")++ spec_file = tmp_path / "graph.json"+ spec_file.write_text("{}", encoding="utf-8")++ with pytest.raises(typer.Exit) as exit_info:+ graph_render_cmd(input_file=spec_file)++ assert exit_info.value.exit_code == 1+ assert "Failed to render graph" in printed.getvalue()+ assert "RuntimeError: the renderer broke" in printed.getvalue()+ assert "Traceback" not in printed.getvalue()+ log_spy.error.assert_called_once_with("The graph could not be rendered", fields={"file.path": str(spec_file)}, include_exception=True)++ @pytest.mark.parametrize("sink_kind", ["console", "json"])+ def test_an_unexpected_error_names_its_cause_on_the_terminal_whatever_the_sink(+ self, mocker: MockerFixture, tmp_path: Path, caplog: pytest.LogCaptureFixture, sink_kind: str+ ) -> None:+ """Under a sink that does not write to the terminal, the CLI's own output was "Failed to render graph" and nothing else.++ The CLI names the exception's type and message itself, and the traceback is printed once, by the log line.+ """+ caplog.set_level(logging.INFO, logger=GRAPH_CMD)+ mocker.patch(f"{GRAPH_CMD}.make_pipelex_for_cli")+ mocker.patch(f"{GRAPH_CMD}.Pipelex.teardown_if_needed")+ mocker.patch(f"{GRAPH_CMD}.tag")+ telemetry_manager = mocker.patch(f"{GRAPH_CMD}.get_telemetry_manager").return_value+ telemetry_manager.telemetry_context.return_value = contextlib.nullcontext()+ printed = io.StringIO()+ mocker.patch(f"{GRAPH_CMD}.get_console", return_value=Console(file=printed, width=1000))+ mocker.patch(f"{GRAPH_CMD}._do_graph_render", side_effect=RuntimeError("the renderer broke"))+ sink_buffer = io.StringIO()+ sink: LogSink = console_sink_on_buffer(buffer=sink_buffer) if sink_kind == "console" else JsonLogSink(stream=sink_buffer)+ spec_file = tmp_path / "graph.json"+ spec_file.write_text("{}", encoding="utf-8")++ with installed_log(sink=sink) as fresh:+ mocker.patch(f"{GRAPH_CMD}.log", new=fresh)+ with pytest.raises(typer.Exit):+ graph_render_cmd(input_file=spec_file)++ terminal = printed.getvalue()+ assert "Failed to render graph" in terminal+ assert "RuntimeError: the renderer broke" in terminal+ assert "Traceback" not in terminal+ logged = sink_buffer.getvalue()+ if sink_kind == "console":+ assert "The graph could not be rendered" in logged+ assert logged.count("Traceback") == 1+ else:+ (record,) = [json.loads(line) for line in logged.splitlines() if line and json.loads(line)[LOGGER_KEY] == GRAPH_CMD]+ assert record[MESSAGE_KEY] == "The graph could not be rendered"+ assert record[EXCEPTION_KEY].startswith("Traceback")+ assert record[EXCEPTION_KEY].rstrip().endswith("RuntimeError: the renderer broke")diff --git a/tests/unit/pipelex/cli/test_run_core_wrapper.py b/tests/unit/pipelex/cli/test_run_core_wrapper.pyindex 21c6aa744..c209ec4ac 100644--- a/tests/unit/pipelex/cli/test_run_core_wrapper.py+++ b/tests/unit/pipelex/cli/test_run_core_wrapper.py@@ -5,6 +5,9 @@ Covers setup/teardown wiring and the error-handler dispatch at the CLI boundary.from __future__ import annotations+import io+import json+import loggingfrom typing import TYPE_CHECKING, Anyimport pytest@@ -19,11 +22,17 @@ from pipelex.cogt.model_backends.model_type import ModelTypefrom pipelex.core.pipes.exceptions import PipeOperatorModelChoiceErrorfrom pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityErrorfrom pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.tools.log.json_log_sink import EXCEPTION_KEY, LOGGER_KEY, MESSAGE_KEY, JsonLogSinkfrom pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider+from tests.helpers.console_log_rendering import console_sink_on_buffer, installed_logif TYPE_CHECKING:from pytest_mock import MockerFixture+ from pipelex.tools.log.log_sink import LogSink++RUN_CORE_MODULE = "pipelex.cli.commands.run._run_core"+def _call_execute_run(**overrides: Any) -> None:kwargs: dict[str, Any] = {@@ -174,8 +183,13 @@ class TestExecuteRunWrapper:assert "Add 'enabled = false' under '[openai]' in '.pipelex/inference/backends.toml'" in outputassert "\\[" not in output- def test_unexpected_error_prints_exception_and_exits(self, wrapper_mocks: dict[str, Any]) -> None:- """An unexpected exception prints the rich traceback and exits 1."""+ def test_unexpected_error_logs_its_traceback_and_exits(self, wrapper_mocks: dict[str, Any], mocker: MockerFixture) -> None:+ """An unexpected exception is logged at ERROR with its traceback, which the console does not print a second time, and exits 1.++ The traceback used to be printed on the console alone, so under the `json` or `otlp` sink an unexpected+ failure's stack never reached the log store.+ """+ log_mock = mocker.patch("pipelex.cli.commands.run._run_core.log")wrapper_mocks["core"].side_effect = RuntimeError("totally unexpected")with pytest.raises(typer.Exit) as exc_info:@@ -184,4 +198,53 @@ class TestExecuteRunWrapper:assert exc_info.value.exit_code == 1output = wrapper_mocks["console"].export_text()assert "Failed to execute pipeline" in output- assert "totally unexpected" in output+ assert "RuntimeError: totally unexpected" in output+ assert "Traceback" not in output+ log_mock.error.assert_called_once_with("The pipeline could not be executed", include_exception=True)++ @pytest.mark.parametrize("sink_kind", ["console", "json"])+ def test_unexpected_error_names_its_cause_on_the_terminal_whatever_the_sink(+ self, wrapper_mocks: dict[str, Any], mocker: MockerFixture, caplog: pytest.LogCaptureFixture, sink_kind: str+ ) -> None:+ """Under a sink that does not write to the terminal, the CLI's own output was "Failed to execute pipeline" and nothing else.++ The CLI names the exception's type and message itself, and the traceback is printed once, by the log line.+ """+ caplog.set_level(logging.INFO, logger=RUN_CORE_MODULE)+ sink_buffer = io.StringIO()+ sink: LogSink = console_sink_on_buffer(buffer=sink_buffer) if sink_kind == "console" else JsonLogSink(stream=sink_buffer)+ wrapper_mocks["core"].side_effect = RuntimeError("totally unexpected")++ with installed_log(sink=sink) as fresh:+ mocker.patch(f"{RUN_CORE_MODULE}.log", new=fresh)+ with pytest.raises(typer.Exit):+ _call_execute_run()++ terminal = wrapper_mocks["console"].export_text()+ assert "Failed to execute pipeline" in terminal+ assert "RuntimeError: totally unexpected" in terminal+ assert "Traceback" not in terminal+ logged = sink_buffer.getvalue()+ if sink_kind == "console":+ assert "The pipeline could not be executed" in logged+ assert logged.count("Traceback") == 1+ else:+ (record,) = [json.loads(line) for line in logged.splitlines() if line and json.loads(line)[LOGGER_KEY] == RUN_CORE_MODULE]+ assert record[MESSAGE_KEY] == "The pipeline could not be executed"+ assert record[EXCEPTION_KEY].startswith("Traceback")+ assert record[EXCEPTION_KEY].rstrip().endswith("RuntimeError: totally unexpected")++ def test_unexpected_error_reaches_a_structured_sink_with_its_traceback(+ self, wrapper_mocks: dict[str, Any], caplog: pytest.LogCaptureFixture+ ) -> None:+ """The record carries the exception itself, so a structured sink writes the stack the console used to keep to itself."""+ wrapper_mocks["core"].side_effect = RuntimeError("totally unexpected")++ with caplog.at_level(logging.ERROR, logger="pipelex.cli.commands.run._run_core"), pytest.raises(typer.Exit):+ _call_execute_run()++ (record,) = [record for record in caplog.records if record.getMessage() == "The pipeline could not be executed"]+ assert record.levelno == logging.ERROR+ assert record.exc_info is not None+ assert isinstance(record.exc_info[1], RuntimeError)+ assert str(record.exc_info[1]) == "totally unexpected"diff --git a/tests/unit/pipelex/cogt/img_gen/test_img_gen_args_gpt_sizes.py b/tests/unit/pipelex/cogt/img_gen/test_img_gen_args_gpt_sizes.pyindex a59ed4cc9..aef080458 100644--- a/tests/unit/pipelex/cogt/img_gen/test_img_gen_args_gpt_sizes.py+++ b/tests/unit/pipelex/cogt/img_gen/test_img_gen_args_gpt_sizes.py@@ -107,6 +107,8 @@ class TestImgGenArgsGptSizes:)mock_log.warning.assert_called_once()+ # The model's name here is its deck handle, and the size rides as a field, never in the message+ assert mock_log.warning.call_args.kwargs["fields"] == {"model_handle": "gpt-image-2", "image_size": "2048x2048"}mock_log.verbose.assert_not_called()def test_exact_size_below_reliability_boundary_logs_nothing(self, mocker: MockerFixture) -> None:diff --git a/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.py b/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.pyindex 7df3447c5..56a2d1f89 100644--- a/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.py+++ b/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.py@@ -190,11 +190,10 @@ class TestAStaleBackendDirectory:warning = library.take_stale_configuration_warning()assert warning is not None- assert str(openai_file) in warning- assert str(portkey_file) in warning- assert "Drop prompting_target from every backend definition" in warning- assert "Run `pipelex migrate`" in warning- assert "Nothing was written" in warning+ assert sorted(stale_file.file_path for stale_file in warning.files) == sorted([openai_file, portkey_file])+ for stale_file in warning.files:+ assert stale_file.migration_steps == ["Drop prompting_target from every backend definition"]+ assert stale_file.is_reached_by_migrateassert library.take_stale_configuration_warning() is None, "a warning is handed over once"def test_the_warning_carries_no_value_read_from_the_users_file(self, machine: Path) -> None:@@ -205,8 +204,9 @@ class TestAStaleBackendDirectory:warning = library.take_stale_configuration_warning()assert warning is not None- assert "gemini" not in warning- assert "gpt-4o" not in warning+ logged = repr([stale_file.log_fields() for stale_file in warning.files])+ assert "gemini" not in logged+ assert "gpt-4o" not in loggeddef test_nothing_is_written_to_disk(self, machine: Path) -> None:"""Boot never writes — no rewrite, and no backup beside the file either."""diff --git a/tests/unit/pipelex/cogt/model_backends/test_backend_library_overrides.py b/tests/unit/pipelex/cogt/model_backends/test_backend_library_overrides.pyindex 06da87db5..9330a3314 100644--- a/tests/unit/pipelex/cogt/model_backends/test_backend_library_overrides.py+++ b/tests/unit/pipelex/cogt/model_backends/test_backend_library_overrides.py@@ -140,8 +140,9 @@ class TestBackendLibraryOverrides:override_path.write_text("[acme]\nenabled = true\n")self._load(paths=[base_path, override_path], backends_dir=backends_dir)- logged = " ".join(str(call.args[0]) for call in logger.info.call_args_list)- assert str(override_path) in logged+ # The merged files ride as fields, base then overrides, never spliced into the message+ logger.info.assert_called_once()+ assert logger.info.call_args.kwargs["fields"] == {"file.path": str(base_path), "override_paths": [str(override_path)]}@pytest.mark.parametrize("credentials", [CredentialResolution.REQUIRE, CredentialResolution.SKIP])def test_a_scalar_where_a_table_was_meant_is_refused_in_both_modes(self, tmp_path: Path, credentials: CredentialResolution) -> None:diff --git a/tests/unit/pipelex/cogt/model_routing/test_routing_profile_overrides.py b/tests/unit/pipelex/cogt/model_routing/test_routing_profile_overrides.pyindex f0d0570b3..143c90dcd 100644--- a/tests/unit/pipelex/cogt/model_routing/test_routing_profile_overrides.py+++ b/tests/unit/pipelex/cogt/model_routing/test_routing_profile_overrides.py@@ -165,5 +165,6 @@ class TestRoutingProfileOverrides:override_path.write_text('active = "on_other"\n')load_active_routing_profile(routing_profile_library_paths=[base_path, override_path], enabled_backends=["acme", "other"])- logged = " ".join(str(call.args[0]) for call in logger.info.call_args_list)- assert str(override_path) in logged+ # The merged files ride as fields, base then overrides, never spliced into the message+ logger.info.assert_called_once()+ assert logger.info.call_args.kwargs["fields"] == {"file.path": str(base_path), "override_paths": [str(override_path)]}diff --git a/tests/unit/pipelex/cogt/models/test_model_deck_ambiguous_bare_handle.py b/tests/unit/pipelex/cogt/models/test_model_deck_ambiguous_bare_handle.pynew file mode 100644index 000000000..e43dd4d6d--- /dev/null+++ b/tests/unit/pipelex/cogt/models/test_model_deck_ambiguous_bare_handle.py@@ -0,0 +1,82 @@+from pytest_mock import MockerFixture++from pipelex.cogt.config_cogt import ModelDeckConfig+from pipelex.cogt.extract.extract_setting import ExtractSetting+from pipelex.cogt.img_gen.img_gen_job_components import Quality+from pipelex.cogt.llm.llm_setting import LLMSetting, LLMSettingChoicesDefaults+from pipelex.cogt.llm.thinking_mode import ThinkingMode+from pipelex.cogt.model_backends.model_spec import InferenceModelSpec+from pipelex.cogt.model_backends.model_spec_index import ModelSpecIndex+from pipelex.cogt.model_backends.model_type import ModelType+from pipelex.cogt.models.model_deck import ModelDeck+from pipelex.cogt.models.model_reference import ModelReferenceKind+from pipelex.cogt.usage.cost_category import CostCategory+from pipelex.system.runtime import ProblemReaction+++def _make_deck() -> ModelDeck:+ """A deck serving one LLM, where `twin` is at once a model, an alias and a preset."""+ twin_model = InferenceModelSpec(+ backend_name="test_backend",+ name="twin",+ sdk="test_sdk",+ model_type=ModelType.LLM,+ model_id="test_model_twin",+ costs={CostCategory.INPUT: 0.001, CostCategory.OUTPUT: 0.002},+ thinking_mode=ThinkingMode.NONE,+ max_tokens=1000,+ max_prompt_images=None,+ )+ return ModelDeck(+ inference_models=ModelSpecIndex.make_from_specs(model_specs=[twin_model]),+ llm_default_temperature=0.7,+ llm_aliases={"twin": "twin"},+ llm_waterfalls={},+ llm_presets={"twin": LLMSetting(model="twin", temperature=0.3)},+ llm_choice_defaults=LLMSettingChoicesDefaults(+ default_temperature=0.7,+ for_text=LLMSetting(model="twin", temperature=0.7),+ for_object=LLMSetting(model="twin", temperature=0.7),+ ),+ extract_aliases={},+ extract_waterfalls={},+ extract_presets={"deck-extract-preset": ExtractSetting(model="deck-extract-preset-model")},+ extract_choice_default="$deck-extract-preset",+ img_gen_default_quality=Quality.MEDIUM,+ img_gen_aliases={},+ img_gen_waterfalls={},+ img_gen_presets={},+ img_gen_choice_default="deck-img-gen-default",+ search_aliases={},+ search_waterfalls={},+ search_presets={},+ search_choice_default="deck-search-default",+ model_deck_config=ModelDeckConfig(is_model_fallback_enabled=True, missing_presets_reaction=ProblemReaction.NONE),+ )+++class TestModelDeckAmbiguousBareHandle:+ def test_the_warning_names_the_handle_its_type_and_every_kind_it_also_names(self, mocker: MockerFixture) -> None:+ """The kinds ride as a field, so one fixed message groups every such warning whatever the name."""+ deck = _make_deck()+ warning = mocker.patch("pipelex.cogt.models.model_deck.log.warning")++ setting = deck.get_llm_setting(llm_choice="twin")++ assert setting.model == "twin"+ warning.assert_called_once()+ assert warning.call_args.kwargs["fields"] == {+ "model_handle": "twin",+ "model_type": ModelType.LLM,+ "matching_reference_kinds": [ModelReferenceKind.PRESET, ModelReferenceKind.ALIAS],+ }++ def test_a_bare_name_that_names_nothing_else_is_not_warned_about(self, mocker: MockerFixture) -> None:+ deck = _make_deck()+ deck.llm_aliases.clear()+ deck.llm_presets.clear()+ warning = mocker.patch("pipelex.cogt.models.model_deck.log.warning")++ deck.get_llm_setting(llm_choice="twin")++ warning.assert_not_called()diff --git a/tests/unit/pipelex/cogt/models/test_model_deck_type_strictness.py b/tests/unit/pipelex/cogt/models/test_model_deck_type_strictness.pyindex 1b58f2633..3f044b1d0 100644--- a/tests/unit/pipelex/cogt/models/test_model_deck_type_strictness.py+++ b/tests/unit/pipelex/cogt/models/test_model_deck_type_strictness.py@@ -1,7 +1,9 @@"""The deck's own bindings and refusals hold a bare handle to the model type it is named for."""import pytest+from pytest_mock import MockerFixture+from pipelex import logfrom pipelex.cogt.config_cogt import ModelDeckConfigfrom pipelex.cogt.exceptions import ImgGenHandleNotFoundError, LLMHandleNotFoundError, ModelChoiceNotFoundError, ModelDeckPresetValidatonErrorfrom pipelex.cogt.img_gen.img_gen_job_components import Quality@@ -124,6 +126,36 @@ class TestModelDeckTypeStrictness:with pytest.raises(ModelDeckPresetValidatonError, match=r"Failed to validate all LLM presets: LLM preset 'painter': .* but not as an LLM"):model_deck.validate_registered_models()+ def test_a_deck_that_logs_its_unresolvable_presets_warns_once_per_model_type_with_the_same_fields(self, mocker: MockerFixture) -> None:+ """Each model type's refusal is logged through one helper, so every one of them names its type, preset and model alike."""+ model_deck = _make_deck(+ llm_presets={"painter": LLMSetting(model="img-painter", temperature=0.5)},+ img_gen_presets={"writer": ImgGenSetting(model="claude-x")},+ missing_presets_reaction=ProblemReaction.LOG,+ )+ warning_spy = mocker.patch.object(log, "warning")++ model_deck.validate_registered_models()++ assert [call.args for call in warning_spy.call_args_list] == [("A preset of the model deck names a model the deck cannot resolve",)] * 2+ llm_fields, img_gen_fields = [call.kwargs["fields"] for call in warning_spy.call_args_list]+ assert llm_fields == {+ "model_type": ModelType.LLM,+ "preset_id": "painter",+ "model_handle": "img-painter",+ "error.type": "LLMHandleNotFoundError",+ "error.message": "LLM preset 'painter': Model handle 'img-painter' is served by the model deck, but not as an LLM",+ }+ assert img_gen_fields == {+ "model_type": ModelType.IMG_GEN,+ "preset_id": "writer",+ "model_handle": "claude-x",+ "error.type": "ImgGenHandleNotFoundError",+ "error.message": (+ "Image generation preset 'writer': Model handle 'claude-x' is served by the model deck, but not as an image-generation model"+ ),+ }+def test_an_llm_override_naming_an_image_generation_model_is_refused_with_the_llms_alone(self) -> None:model_deck = _make_deck()diff --git a/tests/unit/pipelex/cogt/usage/test_cost_registry.py b/tests/unit/pipelex/cogt/usage/test_cost_registry.pyindex cf3f71e20..c29253b5d 100644--- a/tests/unit/pipelex/cogt/usage/test_cost_registry.py+++ b/tests/unit/pipelex/cogt/usage/test_cost_registry.py@@ -285,8 +285,8 @@ class TestCostRegistry:def test_generate_report_with_empty_data(self, mocker: MockerFixture):"""Test proper handling when no usage data."""- # Mock logging- mock_log_warning = mocker.patch("pipelex.cogt.usage.cost_registry.log.warning")+ # Mock logging: a run with no usage is not something an operator acts on, so it is noted at DEBUG+ mock_log_debug = mocker.patch("pipelex.cogt.usage.cost_registry.log.debug")# Test with non-untitled pipelineCostRegistry.generate_report(@@ -295,16 +295,16 @@ class TestCostRegistry:unit_scale=1.0,cost_report_file_path=None,)- mock_log_warning.assert_called_once()+ mock_log_debug.assert_called_once()- # Test with untitled pipeline: nothing more is warned+ # Test with untitled pipeline: nothing more is notedCostRegistry.generate_report(pipeline_run_id="untitled",tokens_usages=[],unit_scale=1.0,cost_report_file_path=None,)- mock_log_warning.assert_called_once()+ mock_log_debug.assert_called_once()def test_generate_report_with_file_output(self, job_metadata: JobMetadata, tmp_path: Path, mocker: MockerFixture):"""Test that CSV file is created when file path is provided."""diff --git a/tests/unit/pipelex/core/memory/test_working_memory_basic.py b/tests/unit/pipelex/core/memory/test_working_memory_basic.pyindex b369ed661..0b631d95b 100644--- a/tests/unit/pipelex/core/memory/test_working_memory_basic.py+++ b/tests/unit/pipelex/core/memory/test_working_memory_basic.py@@ -1,6 +1,11 @@+import pytest+from pytest_mock import MockerFixture++from pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.memory.working_memory import MAIN_STUFF_NAME, WorkingMemoryfrom pipelex.core.memory.working_memory_factory import WorkingMemoryFactory+from pipelex.core.stuffs.stuff_factory import StuffFactoryfrom pipelex.core.stuffs.text_content import TextContentfrom tests.unit.pipelex.core.memory.conftest import TestWorkingMemoryData@@ -40,3 +45,17 @@ class TestWorkingMemoryBasic:empty_memory = WorkingMemoryFactory.make_empty()assert len(empty_memory.root) == 0assert len(empty_memory.aliases) == 0++ @pytest.mark.parametrize("key", ["_draft", MAIN_STUFF_NAME])+ def test_a_name_reserved_for_params_warns_once_naming_it(self, mocker: MockerFixture, key: str):+ """A stuff named with the params underscore warns once, the name as a field, stored under that name or as the main stuff."""+ warning_mock = mocker.patch("pipelex.core.memory.working_memory.log.warning")+ stuff = StuffFactory.make_stuff(+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT),+ name="_draft",+ content=TextContent(text="A draft"),+ )++ WorkingMemory(root={key: stuff})++ warning_mock.assert_called_once_with("A stuff name starts with an underscore, which is reserved for params", fields={"stuff_name": "_draft"})diff --git a/tests/unit/pipelex/graph/test_graph_output_generation.py b/tests/unit/pipelex/graph/test_graph_output_generation.pyindex 4503d2c9f..6e7644ce3 100644--- a/tests/unit/pipelex/graph/test_graph_output_generation.py+++ b/tests/unit/pipelex/graph/test_graph_output_generation.py@@ -287,14 +287,13 @@ class TestGraphspecCompanions:assert set(saved) == {"graphspec_json"}assert {path.name for path in tmp_path.iterdir()} == {"graphspec.json"}- removed = [str(call.args[0]) for call in warning_spy.call_args_list if "Removed" in str(call.args[0])]- assert {- name for name in (PIPE_IO_CONTRACTS_FILE_NAME, INPUT_FORM_FILE_NAME, OUTPUT_FORM_FILE_NAME) if any(name in msg for msg in removed)- } == {+ removed_paths = [Path(call.kwargs["fields"]["file.path"]) for call in warning_spy.call_args_list if "Removed" in str(call.args[0])]+ assert {path.name for path in removed_paths} == {PIPE_IO_CONTRACTS_FILE_NAME,INPUT_FORM_FILE_NAME,OUTPUT_FORM_FILE_NAME,}+ assert {path.parent for path in removed_paths} == {tmp_path}async def test_a_fresh_directory_removes_nothing_and_says_nothing(self, tmp_path: Path, mocker: MockerFixture) -> None:"""The removal warning names a file that was there: a directory with no companions gets no warning."""diff --git a/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.py b/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.pyindex 259b0d33f..ba5d428f3 100644--- a/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.py+++ b/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.py@@ -24,6 +24,13 @@ _DATA_INCLUSION_OFF = DataInclusionConfig(_TRACER_KEY = "run_under_test"+_STALE_TRACER_MESSAGE = "Replacing a graph tracer left over by an interrupted execution whose cleanup never ran"+_STALE_TEARDOWN_MESSAGE = "The teardown of a stale graph tracer raised; replacing it anyway"+++def _records_with_message(*, caplog: pytest.LogCaptureFixture, message: str) -> list[logging.LogRecord]:+ return [record for record in caplog.records if record.getMessage() == message]+class TestGraphTracerManagerStaleKeyHealing:@pytest.fixture(autouse=True)@@ -57,7 +64,8 @@ class TestGraphTracerManagerStaleKeyHealing:fresh_tracer = manager.get_tracer(_TRACER_KEY)assert fresh_tracer is not Noneassert fresh_tracer is not stale_tracer, "the stale tracer must be evicted, not reused"- assert "already exists" in caplog.text+ (stale_record,) = _records_with_message(caplog=caplog, message=_STALE_TRACER_MESSAGE)+ assert vars(stale_record).get("tracer_key") == _TRACER_KEYdef test_open_tracer_heals_even_when_stale_teardown_raises(self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture) -> None:"""A stale tracer's raising teardown must not fail the fresh run's setup.@@ -79,11 +87,15 @@ class TestGraphTracerManagerStaleKeyHealing:fresh_tracer = manager.get_tracer(_TRACER_KEY)assert fresh_tracer is not Noneassert fresh_tracer is not stale_tracer, "the stale tracer must be evicted even when its teardown raises"+ (teardown_record,) = _records_with_message(caplog=caplog, message=_STALE_TEARDOWN_MESSAGE)+ assert vars(teardown_record).get("tracer_key") == _TRACER_KEY+ assert vars(teardown_record).get("error.type") == "RuntimeError"+ assert vars(teardown_record).get("error.message") == "half-built state"def test_open_tracer_fresh_key_does_not_warn(self, caplog: pytest.LogCaptureFixture) -> None:"""The healing warning must be gated on key membership: a fresh key opens silently."""manager = GraphTracerManager.get_or_create_instance()with caplog.at_level(logging.WARNING):self._open_tracer(manager)- assert "already exists" not in caplog.text+ assert not _records_with_message(caplog=caplog, message=_STALE_TRACER_MESSAGE)assert manager.get_tracer(_TRACER_KEY) is not Nonediff --git a/tests/unit/pipelex/kernel/test_run_judgment.py b/tests/unit/pipelex/kernel/test_run_judgment.pyindex e52d6bdb0..7aa2648d0 100644--- a/tests/unit/pipelex/kernel/test_run_judgment.py+++ b/tests/unit/pipelex/kernel/test_run_judgment.py@@ -91,8 +91,7 @@ class TestRunJudgment:assert result.threshold_applied is Falsewarning.assert_called_once()- assert "is_urgent" in warning.call_args.args[0]- assert "judgment-ops-model" in warning.call_args.args[0]+ assert warning.call_args.kwargs["fields"] == {"pipe_code": "is_urgent", "threshold": 0.8, "model_handle": "judgment-ops-model"}async def test_a_dry_threshold_without_a_probability_neither_warns_nor_records(self, mocker: MockerFixture) -> None:warning = mocker.patch("pipelex.kernel.judgment_ops.log.warning")diff --git a/tests/unit/pipelex/libraries/test_domain_library.py b/tests/unit/pipelex/libraries/test_domain_library.pyindex 6b4f8f43b..4eada56d9 100644--- a/tests/unit/pipelex/libraries/test_domain_library.py+++ b/tests/unit/pipelex/libraries/test_domain_library.py@@ -5,6 +5,8 @@ import pytestfrom pipelex.core.domains.domain import Domainfrom pipelex.libraries.domain.domain_library import DomainLibrary+DOMAIN_FIELD_CONFLICT_MESSAGE = "Two declarations of one domain give one of its fields different values, so the first is kept"+class TestDomainLibrary:"""Tests for DomainLibrary domain management."""@@ -46,7 +48,7 @@ class TestDomainLibrary:merged = library.get_required_domain("meta")assert merged.description == "Meta domain"assert merged.system_prompt == "You are a meta assistant."- assert not [record for record in caplog.records if "declared with different" in record.message]+ assert not [record for record in caplog.records if record.getMessage() == DOMAIN_FIELD_CONFLICT_MESSAGE]def test_same_values_no_warning(self, caplog: pytest.LogCaptureFixture):"""Two Domains declaring the same non-empty description/system_prompt merge without warning."""@@ -61,7 +63,7 @@ class TestDomainLibrary:merged = library.get_required_domain("meta")assert merged.description == "Meta domain"assert merged.system_prompt == "You are a meta assistant."- assert not [record for record in caplog.records if "declared with different" in record.message]+ assert not [record for record in caplog.records if record.getMessage() == DOMAIN_FIELD_CONFLICT_MESSAGE]def test_conflict_keeps_first_and_warns(self, caplog: pytest.LogCaptureFixture):"""Two Domains declaring different non-empty values keep the first and warn for each field."""@@ -76,9 +78,14 @@ class TestDomainLibrary:merged = library.get_required_domain("meta")assert merged.description == "Meta domain"assert merged.system_prompt == "You are a meta assistant."- messages = [record.message for record in caplog.records]- assert any(- "Domain 'meta' declared with different descriptions: 'Meta domain' vs 'A different meta domain'. Keeping the first." in message- for message in messages- )- assert any("Domain 'meta' declared with different system_prompts. Keeping the first." in message for message in messages)+ # A short field carries both values, while a prompt never rides the line.+ conflicts = {+ record.__dict__["metadata_field"]: (+ record.__dict__["domain_code"],+ record.__dict__.get("established_value"),+ record.__dict__.get("incoming_value"),+ )+ for record in caplog.records+ if record.getMessage() == DOMAIN_FIELD_CONFLICT_MESSAGE+ }+ assert conflicts == {"description": ("meta", "Meta domain", "A different meta domain"), "system_prompt": ("meta", None, None)}diff --git a/tests/unit/pipelex/libraries/test_library_crate.py b/tests/unit/pipelex/libraries/test_library_crate.pyindex 5fd7a42d6..d26d5efbf 100644--- a/tests/unit/pipelex/libraries/test_library_crate.py+++ b/tests/unit/pipelex/libraries/test_library_crate.py@@ -9,6 +9,8 @@ from pipelex.libraries.pipe.exceptions import PipeLibraryErrorfrom pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprintfrom tests.unit.pipelex.libraries.test_library_crate_data import BlueprintSamples+DOMAIN_FIELD_CONFLICT_MESSAGE = "Two declarations of one domain give one of its fields different values, so the first is kept"+class TestLibraryCrate:"""Tests for LibraryCrate model and LibraryCrateFactory."""@@ -283,7 +285,7 @@ class TestLibraryCrate:crate = LibraryCrateFactory.make_from_blueprints(blueprints=blueprints)assert crate.domains["meta"].description == "Meta domain"assert crate.domains["meta"].system_prompt == "You are a meta assistant."- assert not [record for record in caplog.records if "declared with different" in record.message]+ assert not [record for record in caplog.records if record.getMessage() == DOMAIN_FIELD_CONFLICT_MESSAGE]def test_domain_metadata_same_values_no_warning(self, caplog: pytest.LogCaptureFixture):"""Two files declaring the same non-empty description/system_prompt merge without warning."""@@ -293,7 +295,7 @@ class TestLibraryCrate:)assert crate.domains["meta"].description == "Meta domain"assert crate.domains["meta"].system_prompt == "You are a meta assistant."- assert not [record for record in caplog.records if "declared with different" in record.message]+ assert not [record for record in caplog.records if record.getMessage() == DOMAIN_FIELD_CONFLICT_MESSAGE]def test_domain_metadata_conflict_keeps_first_and_warns(self, caplog: pytest.LogCaptureFixture):"""Two files declaring different non-empty values keep the first and warn for each field."""@@ -303,9 +305,14 @@ class TestLibraryCrate:)assert crate.domains["meta"].description == "Meta domain"assert crate.domains["meta"].system_prompt == "You are a meta assistant."- messages = [record.message for record in caplog.records]- assert any(- "Domain 'meta' declared with different descriptions: 'Meta domain' vs 'A different meta domain'. Keeping the first." in message- for message in messages- )- assert any("Domain 'meta' declared with different system_prompts. Keeping the first." in message for message in messages)+ # A short field carries both values, while a prompt never rides the line.+ conflicts = {+ record.__dict__["metadata_field"]: (+ record.__dict__["domain_code"],+ record.__dict__.get("established_value"),+ record.__dict__.get("incoming_value"),+ )+ for record in caplog.records+ if record.getMessage() == DOMAIN_FIELD_CONFLICT_MESSAGE+ }+ assert conflicts == {"description": ("meta", "Meta domain", "A different meta domain"), "system_prompt": ("meta", None, None)}diff --git a/tests/unit/pipelex/methods/test_fetch_on_miss.py b/tests/unit/pipelex/methods/test_fetch_on_miss.pyindex dafd44d29..bb4227e51 100644--- a/tests/unit/pipelex/methods/test_fetch_on_miss.py+++ b/tests/unit/pipelex/methods/test_fetch_on_miss.py@@ -19,7 +19,6 @@ from pipelex.methods.exceptions import (from pipelex.methods.fetch_on_miss import resolve_address_based_methodfrom pipelex.methods.fetching import FetchedMethodPackage, MethodProvenancefrom pipelex.methods.method_ref import parse_method_ref-from pipelex.methods.structures_check import STRUCTURES_REFUSAL_REMEDYif TYPE_CHECKING:from pathlib import Path@@ -225,10 +224,10 @@ class TestResolveAddressBasedMethod:resolved = resolve_address_based_method(full_address=FULL_ADDRESS)assert (resolved.path / "structures.py").is_file()- warning_messages = [call.args[0] for call in warning_spy.call_args_list if "hosted execution would refuse" in call.args[0]]- assert len(warning_messages) == 1- assert "Invoice" in warning_messages[0]- assert STRUCTURES_REFUSAL_REMEDY in warning_messages[0]+ structures_warnings = [call for call in warning_spy.call_args_list if "hosted execution refuses them" in call.args[0]]+ assert len(structures_warnings) == 1+ assert "declare these types as MTHDS concepts" in structures_warnings[0].args[0]+ assert structures_warnings[0].kwargs["fields"] == {"package_address": FULL_ADDRESS, "structure_classes": "structures.py defines Invoice"}@pytest.mark.usefixtures("isolated_methods_dirs")def test_fetched_provenance_records_the_bare_address_fetch(self, tmp_path: Path, mocker: MockerFixture) -> None:diff --git a/tests/unit/pipelex/migration/test_dev_log_level_retirement.py b/tests/unit/pipelex/migration/test_dev_log_level_retirement.pyindex 608da2032..63b332dca 100644--- a/tests/unit/pipelex/migration/test_dev_log_level_retirement.py+++ b/tests/unit/pipelex/migration/test_dev_log_level_retirement.py@@ -142,6 +142,7 @@ class TestTheDevLogLevelRetirement:assert project_file.read_text(encoding="utf-8") == FILE_NAMING_DEV, "a boot writes nothing"parked = loader.take_stale_configuration_warning()assert parked is not None- assert str(project_file) in parked- assert "Retire the DEV log level" in parked- assert "Run `pipelex migrate`" in parked+ (stale_file,) = parked.files+ assert stale_file.file_path == project_file+ assert any("Retire the DEV log level" in step for step in stale_file.migration_steps)+ assert stale_file.is_reached_by_migratediff --git a/tests/unit/pipelex/migration/test_markup_setting_retirement.py b/tests/unit/pipelex/migration/test_markup_setting_retirement.pyindex 7f707980d..35fb7e571 100644--- a/tests/unit/pipelex/migration/test_markup_setting_retirement.py+++ b/tests/unit/pipelex/migration/test_markup_setting_retirement.py@@ -60,6 +60,7 @@ class TestTheMarkupSettingRetirement:assert project_file.read_text(encoding="utf-8") == FILE_SETTING_MARKUP, "a boot writes nothing"parked = loader.take_stale_configuration_warning()assert parked is not None- assert str(project_file) in parked- assert "The console reads no log message as markup" in parked- assert "Run `pipelex migrate`" in parked+ (stale_file,) = parked.files+ assert stale_file.file_path == project_file+ assert any("The console reads no log message as markup" in step for step in stale_file.migration_steps)+ assert stale_file.is_reached_by_migratediff --git a/tests/unit/pipelex/migration/test_runner.py b/tests/unit/pipelex/migration/test_runner.pyindex 0484e5629..19db06f46 100644--- a/tests/unit/pipelex/migration/test_runner.py+++ b/tests/unit/pipelex/migration/test_runner.py@@ -547,6 +547,7 @@ class TestMigrationRunner:entries=[build_entry(to_schema_version=2, ops=[RenameTableKeyOp(table_path=["reporting"], key="output_config", new_key="output")])])mocker.patch("pipelex.migration.runner.prune_backups_except", side_effect=OSError(errno.EACCES, "Permission denied"))+ warning_mock = mocker.patch("pipelex.migration.runner.log.warning")plan = migrate_file(surface=build_surface(), ledger=ledger, file_path=target, dry_run=False, moment=MOMENT)@@ -554,6 +555,16 @@ class TestMigrationRunner:assert plan.blocked_reason is Noneassert "output = " in target.read_text(encoding="utf-8")assert stale_backup.exists()+ # The warning names the file and the backup just taken, and carries the system's reason alone, the paths being fields.+ warning_mock.assert_called_once_with(+ "A change to a configuration file was backed up, but an older backup of the file could not be pruned",+ fields={+ "file.path": str(target),+ "backup_path": str(plan.backup_path),+ "error.type": "PermissionError",+ "error.message": "Permission denied",+ },+ )def test_an_unparseable_file_is_blocked_and_its_siblings_are_still_migrated(self,diff --git a/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_large_batch_advisory.py b/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_large_batch_advisory.pynew file mode 100644index 000000000..74d137f88--- /dev/null+++ b/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_large_batch_advisory.py@@ -0,0 +1,40 @@+import pytest+from pytest_mock import MockerFixture++from pipelex import log+from pipelex.pipe_controllers.batch.pipe_batch import warn_of_large_batch+from pipelex.urls import URLs+++class TestPipeBatchLargeBatchAdvisory:+ @pytest.mark.parametrize(+ ("max_concurrency", "expected_message", "expected_fields"),+ [+ (+ 8,+ (+ "A PipeBatch fans out over a large list with bounded fan-out, which is backpressure and not durable execution; "+ "for a workload this size, consider a durable execution backend for rate-limited, resumable runs"+ ),+ {"pipe_code": "summarize_each", "item_count": 250, "max_concurrency": 8, "url.full": URLs.durable_execution},+ ),+ (+ None,+ (+ "A PipeBatch fans out over a large list with unbounded fan-out, which is neither backpressure nor durable execution; "+ "for a workload this size, consider a durable execution backend for rate-limited, resumable runs"+ ),+ {"pipe_code": "summarize_each", "item_count": 250, "url.full": URLs.durable_execution},+ ),+ ],+ ids=["bounded", "unbounded"],+ )+ def test_the_advisory_says_what_the_fan_out_is(+ self, mocker: MockerFixture, max_concurrency: int | None, expected_message: str, expected_fields: dict[str, object]+ ) -> None:+ """The advisory said "with bounded fan-out" even when the configuration's `"unbounded"` set no bound at all."""+ warning_spy = mocker.patch.object(log, "warning")++ warn_of_large_batch(pipe_code="summarize_each", item_count=250, max_concurrency=max_concurrency)++ warning_spy.assert_called_once_with(expected_message, fields=expected_fields)diff --git a/tests/unit/pipelex/pipe_machinery/test_pipe_abstract_namespace_strip.py b/tests/unit/pipelex/pipe_machinery/test_pipe_abstract_namespace_strip.pyindex 8e4540ca6..261306250 100644--- a/tests/unit/pipelex/pipe_machinery/test_pipe_abstract_namespace_strip.py+++ b/tests/unit/pipelex/pipe_machinery/test_pipe_abstract_namespace_strip.py@@ -1,5 +1,7 @@import pytest+from pytest_mock import MockerFixture+from pipelex import logfrom pipelex.pipe_machinery.pipe_abstract import PipeAbstract@@ -19,6 +21,17 @@ class TestPipeAbstractNamespaceStrip:result = PipeAbstract.validate_pipe_code_syntax(code)assert result == expected+ def test_the_strip_warning_names_the_code_as_it_was_written(self, mocker: MockerFixture) -> None:+ """The warning's message is the same for every code, and its field is the dotted code the author wrote, the one to fix."""+ warning_spy = mocker.spy(log, "warning")++ PipeAbstract.validate_pipe_code_syntax("domain.my_pipe")++ warning_spy.assert_called_once_with(+ "A pipe code carries a namespace prefix, which was stripped: write the pipe code bare",+ fields={"pipe_code": "my_pipe", "pipe_ref": "domain.my_pipe"},+ )+def test_validate_pipe_code_syntax_raises_for_invalid_after_strip(self) -> None:"""A dotted code whose bare part is not snake_case should raise ValueError."""with pytest.raises(ValueError, match="Invalid pipe code syntax"):diff --git a/tests/unit/pipelex/pipe_run/test_delivery_executor.py b/tests/unit/pipelex/pipe_run/test_delivery_executor.pyindex efcae7041..de36c9f1f 100644--- a/tests/unit/pipelex/pipe_run/test_delivery_executor.py+++ b/tests/unit/pipelex/pipe_run/test_delivery_executor.py@@ -1,10 +1,12 @@import json+import loggingimport socketfrom datetime import UTC, datetimeimport pytestfrom pytest_mock import MockerFixture, MockType+from pipelex import logfrom pipelex.base_exceptions import ErrorDomain, ErrorReportfrom pipelex.cogt.inference.error_classification import ProviderErrorMetadata, UserAction, UserActionKindfrom pipelex.cogt.inference.provider_name import ProviderName@@ -29,6 +31,7 @@ from pipelex.core.stuffs.stuff import Stufffrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.graph.graphspec import GraphSpec, PipelineReffrom pipelex.interpreter_hub import get_concept_library, get_current_library_id_or_none, get_library_manager, scoped_current_library+from pipelex.pipe_run import delivery_executor as delivery_executor_modulefrom pipelex.pipe_run.delivery_assignment import (DeliveryAssignment,DeliveryStatus,@@ -42,6 +45,22 @@ from pipelex.tools.network.exceptions import SsrfBlockedErrorfrom tests.helpers.pipe_io_artifacts import make_pipe_io_artifacts+def _records_with_message(*, caplog: pytest.LogCaptureFixture, message: str) -> list[logging.LogRecord]:+ """The delivery executor's records whose message is ``message``, in emission order."""+ return [record for record in caplog.records if record.name == delivery_executor_module.__name__ and record.getMessage() == message]+++def _mock_webhook_client(mocker: MockerFixture) -> None:+ """Patch the delivery's HTTP client with one whose POST succeeds."""+ mock_client = mocker.AsyncMock()+ mock_response = mocker.MagicMock()+ mock_response.raise_for_status = mocker.Mock()+ mock_client.__aenter__ = mocker.AsyncMock(return_value=mock_client)+ mock_client.__aexit__ = mocker.AsyncMock(return_value=False)+ mock_client.post = mocker.AsyncMock(return_value=mock_response)+ mocker.patch("pipelex.pipe_run.delivery_executor.httpx.AsyncClient", return_value=mock_client)++def _make_main_stuff() -> Stuff:return Stuff(stuff_code="main-code",@@ -543,10 +562,14 @@ class TestDeliveryExecutor:assert result.content == contentasync def test_try_local_hydrate_stuff_returns_none_for_unknown_concept(self, mocker: MockerFixture) -> None:- """A dynamic concept is unknown to a crate-free delivery worker: the ref resolves to nothing, the raw render takes over."""+ """A dynamic concept is unknown to a crate-free delivery worker: the ref resolves to nothing, the raw render takes over.++ That is the expected path for most hosted results, so it is a debug line naming the concept, never a warning.+ """from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]warn_spy = mocker.spy(pipelex_log, "warning")+ debug_spy = mocker.spy(pipelex_log, "debug")stuff_raw = {"stuff_code": "test",@@ -558,8 +581,32 @@ class TestDeliveryExecutor:result = DeliveryExecutor.try_local_hydrate_stuff(stuff_raw)assert result is None- assert warn_spy.call_count == 1- assert "Local hydration failed" in str(warn_spy.call_args)+ assert warn_spy.call_count == 0+ unknown_concept_calls = [+ call+ for call in debug_spy.call_args_list+ if call.args[0] == "The delivered result's concept is not known here; the delivery renders it raw"+ ]+ assert len(unknown_concept_calls) == 1+ assert unknown_concept_calls[0].kwargs["fields"] == {"concept_ref": "dynamic_test.Greeting"}++ async def test_a_hydration_failure_is_logged_without_the_values_it_refused(self, mocker: MockerFixture) -> None:+ """A content that does not validate falls back to the raw render, and the warning says where and why it failed+ without quoting the run's own result, which a pydantic error's text would.+ """+ from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]++ warn_spy = mocker.spy(pipelex_log, "warning")+ stuff_raw = {"stuff_code": "test", "stuff_name": "greeting", "concept": "native.Text", "content": {"text": ["secret-result-value"]}}++ result = DeliveryExecutor.try_local_hydrate_stuff(stuff_raw)++ assert result is None+ (warning_call,) = warn_spy.call_args_list+ assert warning_call.args[0] == "The delivered result could not be hydrated; the delivery renders it raw"+ assert warning_call.kwargs["fields"]["error.type"] == "ValidationError"+ assert warning_call.kwargs["fields"]["error.message"].startswith("text: ")+ assert "secret-result-value" not in str(warning_call)async def test_try_local_hydrate_stuff_returns_none_for_malformed_dict(self, mocker: MockerFixture) -> None:from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]@@ -656,7 +703,7 @@ class TestDeliveryExecutor:"""A ref the current library does not hold falls back to the raw render rather than raising."""from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]- warn_spy = mocker.spy(pipelex_log, "warning")+ debug_spy = mocker.spy(pipelex_log, "debug")library_manager = get_library_manager()library_id, _ = library_manager.open_library()try:@@ -666,8 +713,7 @@ class TestDeliveryExecutor:result = DeliveryExecutor.try_local_hydrate_stuff(stuff_raw)assert result is None- assert warn_spy.call_count == 1- assert "dynamic_test.Greeting" in str(warn_spy.call_args)+ assert any(call.kwargs.get("fields") == {"concept_ref": "dynamic_test.Greeting"} for call in debug_spy.call_args_list)finally:library_manager.teardown(library_id=library_id)@@ -932,12 +978,12 @@ class TestDeliveryExecutor:assert payload["status"] == DeliveryStatus.FAILEDassert "error" not in payload- async def test_storage_completion_log_includes_request_id_when_set(self, mocker: MockerFixture) -> None:- """The ``Storage delivery completed`` log line carries the originating ``request_id`` for cross-phase correlation."""- from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]-- info_spy = mocker.spy(pipelex_log, "info")-+ async def test_the_storage_completion_line_names_the_run_through_its_context(+ self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture+ ) -> None:+ """The delivery binds the run's identifiers onto the log context, so the completion line carries them as the record's+ own, and its message stays the same on every run.+ """mock_storage = mocker.AsyncMock()mock_storage.store = mocker.AsyncMock(return_value="pipelex-storage://test-key")mocker.patch("pipelex.pipe_run.delivery_executor.get_storage_provider", return_value=mock_storage)@@ -948,140 +994,94 @@ class TestDeliveryExecutor:mock_output.working_memory.resolve_main_stuff.return_value = _make_main_stuff()mock_output.graph_spec = None- executor = DeliveryExecutor()- assignment = DeliveryAssignment(storage=StorageTarget())-- await executor.execute(- pipe_output=mock_output,- storage_scope="test-user",- pipeline_run_id="plr-storage-req",- delivery_assignment=assignment,- status=DeliveryStatus.COMPLETED,- request_id="req-abc-123",- )-- storage_messages = [str(c.args[0]) for c in info_spy.call_args_list if "Storage delivery completed" in str(c.args[0])]- assert storage_messages, "Storage delivery completion must emit one info log"- assert "request_id=req-abc-123" in storage_messages[0]- assert "pipeline_run_id=plr-storage-req" in storage_messages[0]-- async def test_webhook_completion_log_includes_request_id_when_set(self, mocker: MockerFixture) -> None:- """The ``Webhook delivery completed`` log line carries the originating ``request_id`` for cross-phase correlation."""- from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]-- info_spy = mocker.spy(pipelex_log, "info")-- mock_client = mocker.AsyncMock()- mock_response = mocker.MagicMock()- mock_response.raise_for_status = mocker.Mock()- mock_client.__aenter__ = mocker.AsyncMock(return_value=mock_client)- mock_client.__aexit__ = mocker.AsyncMock(return_value=False)- mock_client.post = mocker.AsyncMock(return_value=mock_response)- mocker.patch("pipelex.pipe_run.delivery_executor.httpx.AsyncClient", return_value=mock_client)-- executor = DeliveryExecutor()- assignment = DeliveryAssignment(webhooks=[WebhookTarget(url="https://example.com/callback")])-- await executor.execute(- pipe_output=None,- storage_scope="test-user",- pipeline_run_id="plr-webhook-req",- delivery_assignment=assignment,- status=DeliveryStatus.COMPLETED,- request_id="req-xyz-789",- )-- webhook_messages = [str(c.args[0]) for c in info_spy.call_args_list if "Webhook delivery completed" in str(c.args[0])]- assert webhook_messages, "Webhook delivery completion must emit one info log"- assert "request_id=req-xyz-789" in webhook_messages[0]- assert "pipeline_run_id=plr-webhook-req" in webhook_messages[0]-- async def test_failed_webhook_log_includes_request_id_when_set(self, mocker: MockerFixture) -> None:- """``request_id`` and ``error_report`` are independent dimensions of ``DeliveryExecutor.execute``.-- The COMPLETED variant is pinned by ``test_webhook_completion_log_includes_request_id_when_set``;- this pins that the FAILED + populated-error_report path still surfaces ``request_id`` on the- delivery log line — so a future refactor that split the FAILED and COMPLETED webhook code- paths cannot drop the correlation id from the failure surface.- """- from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]-- info_spy = mocker.spy(pipelex_log, "info")-- mock_client = mocker.AsyncMock()- mock_response = mocker.MagicMock()- mock_response.raise_for_status = mocker.Mock()- mock_client.__aenter__ = mocker.AsyncMock(return_value=mock_client)- mock_client.__aexit__ = mocker.AsyncMock(return_value=False)- mock_client.post = mocker.AsyncMock(return_value=mock_response)- mocker.patch("pipelex.pipe_run.delivery_executor.httpx.AsyncClient", return_value=mock_client)+ with caplog.at_level(logging.INFO, logger=delivery_executor_module.__name__):+ await DeliveryExecutor().execute(+ pipe_output=mock_output,+ storage_scope="test-user",+ pipeline_run_id="plr-storage-req",+ delivery_assignment=DeliveryAssignment(storage=StorageTarget()),+ status=DeliveryStatus.COMPLETED,+ request_id="req-abc-123",+ )- error_report = ErrorReport(- error_type="LLMCompletionError",- message="provider returned 429",- title="AI inference failed",- type_uri="https://docs.pipelex.com/latest/errors/llm-completion-error/",- error_category="transient",- error_domain=ErrorDomain.RUNTIME,- retryable=True,- user_action=UserAction(kind=UserActionKind.WAIT_AND_RETRY, detail="Wait a moment and retry"),- model="gpt-4o-mini",- provider="openai",- provider_metadata=ProviderErrorMetadata(- provider=ProviderName.OPENAI,- sdk_exception_type="RateLimitError",- message="429 Too Many Requests",- status_code=429,- retry_after_seconds=2.5,+ (record,) = _records_with_message(caplog=caplog, message="Storage delivery completed")+ assert vars(record).get("request_id") == "req-abc-123"+ assert vars(record).get("pipeline_run_id") == "plr-storage-req"+ assert isinstance(vars(record).get("file_count"), int)+ assert vars(record)["file_count"] > 0++ @pytest.mark.parametrize(+ ("status", "error_report"),+ [+ (DeliveryStatus.COMPLETED, None),+ (+ DeliveryStatus.FAILED,+ ErrorReport(+ error_type="LLMCompletionError",+ message="provider returned 429",+ title="AI inference failed",+ type_uri="https://docs.pipelex.com/latest/errors/llm-completion-error/",+ error_category="transient",+ error_domain=ErrorDomain.RUNTIME,+ retryable=True,+ ),),- )-- executor = DeliveryExecutor()- assignment = DeliveryAssignment(webhooks=[WebhookTarget(url="https://example.com/callback")])-- await executor.execute(- pipe_output=None,- storage_scope="test-user",- pipeline_run_id="plr-webhook-failed-req",- delivery_assignment=assignment,- status=DeliveryStatus.FAILED,- error_report=error_report,- request_id="req-fail-1",- )-- webhook_messages = [str(c.args[0]) for c in info_spy.call_args_list if "Webhook delivery completed" in str(c.args[0])]- assert webhook_messages, "Webhook delivery completion must emit one info log even on FAILED status"- assert "request_id=req-fail-1" in webhook_messages[0]- assert "pipeline_run_id=plr-webhook-failed-req" in webhook_messages[0]-- async def test_completion_logs_omit_request_id_when_unset(self, mocker: MockerFixture) -> None:- """When ``request_id`` is None (run dispatched without an inbound id), the log lines do NOT print a stray ``request_id=None``."""- from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]+ ],+ )+ async def test_the_webhook_completion_line_names_the_run_and_the_receiver_host(+ self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture, status: DeliveryStatus, error_report: ErrorReport | None+ ) -> None:+ """The webhook line carries the run's identifiers from the context, on a failed run with its error report as on a+ completed one, and names the receiver by its host alone: the URL is the caller's, and its path or query may carry+ a credential.+ """+ _mock_webhook_client(mocker)+ webhook_url = "https://hooks.example.com/services/T0SECRET/B0SECRET?token=s3cr3t-callback-token"- info_spy = mocker.spy(pipelex_log, "info")+ with caplog.at_level(logging.INFO, logger=delivery_executor_module.__name__):+ await DeliveryExecutor().execute(+ pipe_output=None,+ storage_scope="test-user",+ pipeline_run_id="plr-webhook-req",+ delivery_assignment=DeliveryAssignment(webhooks=[WebhookTarget(url=webhook_url)]),+ status=status,+ error_report=error_report,+ request_id="req-xyz-789",+ )- mock_client = mocker.AsyncMock()- mock_response = mocker.MagicMock()- mock_response.raise_for_status = mocker.Mock()- mock_client.__aenter__ = mocker.AsyncMock(return_value=mock_client)- mock_client.__aexit__ = mocker.AsyncMock(return_value=False)- mock_client.post = mocker.AsyncMock(return_value=mock_response)- mocker.patch("pipelex.pipe_run.delivery_executor.httpx.AsyncClient", return_value=mock_client)+ (record,) = _records_with_message(caplog=caplog, message="Webhook delivery completed")+ assert vars(record).get("request_id") == "req-xyz-789"+ assert vars(record).get("pipeline_run_id") == "plr-webhook-req"+ assert vars(record).get("server.address") == "hooks.example.com"+ assert "SECRET" not in json.dumps(vars(record), default=str)+ assert "s3cr3t-callback-token" not in json.dumps(vars(record), default=str)- executor = DeliveryExecutor()+ async def test_an_unset_request_id_inherits_the_callers_binding(self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture) -> None:+ """A delivery dispatched without an inbound id carries none of its own, and keeps the one its caller bound, if any."""+ _mock_webhook_client(mocker)assignment = DeliveryAssignment(webhooks=[WebhookTarget(url="https://example.com/callback")])- await executor.execute(- pipe_output=None,- storage_scope="test-user",- pipeline_run_id="plr-no-req",- delivery_assignment=assignment,- status=DeliveryStatus.COMPLETED,- )+ with caplog.at_level(logging.INFO, logger=delivery_executor_module.__name__):+ await DeliveryExecutor().execute(+ pipe_output=None,+ storage_scope="test-user",+ pipeline_run_id="plr-no-req",+ delivery_assignment=assignment,+ status=DeliveryStatus.COMPLETED,+ )+ with log.context(request_id="req-outer"):+ await DeliveryExecutor().execute(+ pipe_output=None,+ storage_scope="test-user",+ pipeline_run_id="plr-no-req",+ delivery_assignment=assignment,+ status=DeliveryStatus.COMPLETED,+ )- webhook_messages = [str(c.args[0]) for c in info_spy.call_args_list if "Webhook delivery completed" in str(c.args[0])]- assert webhook_messages, "Webhook delivery completion must emit one info log"- assert "request_id" not in webhook_messages[0], "an unset request_id must not produce a stray field"+ unbound_record, inherited_record = _records_with_message(caplog=caplog, message="Webhook delivery completed")+ assert "request_id" not in vars(unbound_record), "an unset request_id must not be stamped at all"+ assert vars(unbound_record).get("pipeline_run_id") == "plr-no-req"+ assert vars(inherited_record).get("request_id") == "req-outer"async def test_webhook_aborts_on_dns_rebind_to_private_ip(self, mocker: MockerFixture) -> None:"""A callback host that passes literal-IP validation but resolves to a privatediff --git a/tests/unit/pipelex/pipe_run/test_dry_run_degrade_fields.py b/tests/unit/pipelex/pipe_run/test_dry_run_degrade_fields.pynew file mode 100644index 000000000..7009a712e--- /dev/null+++ b/tests/unit/pipelex/pipe_run/test_dry_run_degrade_fields.py@@ -0,0 +1,50 @@+from typing import Any++import pytest+from pytest_mock import MockerFixture++from pipelex.base_exceptions import PipelexError+from pipelex.pipe_run.dry_run_in_process import best_effort_graph_spec++DRY_RUN_MODULE = "pipelex.pipe_run.dry_run_in_process"++[email protected](loop_scope="class")+class TestDryRunDegradeFields:+ @pytest.mark.parametrize(+ ("topic", "is_resolved", "target", "expected_pipe_fields"),+ [+ (+ "a pipe named by its reference",+ True,+ "company.describe_company",+ {"pipe_code": "describe_company", "pipe_ref": "company.describe_company"},+ ),+ ("a pipe named by its bare code", True, "describe_company", {"pipe_code": "describe_company", "pipe_ref": "company.describe_company"}),+ ("a qualified target that resolves to no pipe", False, "company.missing_pipe", {"pipe_ref": "company.missing_pipe"}),+ ("a bare target that resolves to no pipe", False, "missing_pipe", {"pipe_code": "missing_pipe"}),+ ],+ )+ async def test_the_degrade_warning_names_the_pipe_as_the_pipe_run_lines_do(+ self, mocker: MockerFixture, topic: str, is_resolved: bool, target: str, expected_pipe_fields: dict[str, Any]+ ) -> None:+ """`pipe_code` carries the bare code `Pipe run starts` carries, and a qualified reference rides `pipe_ref`."""+ pipe = mocker.MagicMock()+ pipe.code = "describe_company"+ pipe.pipe_ref = "company.describe_company"+ pipe_library = mocker.patch(f"{DRY_RUN_MODULE}.get_library_manager").return_value.get_library.return_value.pipe_library+ if is_resolved:+ pipe_library.get_required_entry_pipe.return_value = pipe+ mocker.patch(f"{DRY_RUN_MODULE}.dry_run_pipe_in_process", new=mocker.AsyncMock(side_effect=PipelexError("the dry run failed")))+ else:+ pipe_library.get_required_entry_pipe.side_effect = PipelexError("no such pipe")+ log_spy = mocker.patch(f"{DRY_RUN_MODULE}.log")++ graph_spec = await best_effort_graph_spec(pipe_ref=target, library_id="library-1", log_context="test_caller")++ assert graph_spec is None, topic+ log_spy.warning.assert_called_once()+ fields = log_spy.warning.call_args.kwargs["fields"]+ assert {key: value for key, value in fields.items() if key in {"pipe_code", "pipe_ref"}} == expected_pipe_fields, topic+ assert fields["caller"] == "test_caller", topic+ assert fields["error.type"] == "PipelexError", topicdiff --git a/tests/unit/pipelex/pipe_run/test_pipe_run.py b/tests/unit/pipelex/pipe_run/test_pipe_run.pyindex 8a86e0647..044dc1e74 100644--- a/tests/unit/pipelex/pipe_run/test_pipe_run.py+++ b/tests/unit/pipelex/pipe_run/test_pipe_run.py@@ -121,6 +121,31 @@ class TestPipeRun:assert record_fields.get("delivery_status") == expected_statusassert record_fields.get("pipeline_run_id") == "plr-delivery-log"+ async def test_the_failure_line_names_the_pipe_as_the_pipe_run_lines_do(self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture) -> None:+ """`pipe_code` carried the qualified reference here and the bare code on `Pipe run starts`, so one query missed this line."""+ mock_router = mocker.AsyncMock()+ mock_router.run = mocker.AsyncMock(side_effect=RuntimeError("router blew up"))+ mocker.patch("pipelex.pipe_run.pipe_run.DeliveryExecutor")+ mock_job = mocker.MagicMock()+ mock_job.pipe.code = "describe_company"+ mock_job.pipe.pipe_ref = "company.describe_company"+ mock_job.job_metadata = JobMetadata(+ run_metadata=RunMetadata(user_id="pytest", pipeline_run_id="plr-failure-line", storage_scope="test/scope", read_scope=None)+ )++ with pytest.raises(RuntimeError, match="router blew up"), caplog.at_level(logging.ERROR, logger=pipe_run_module.__name__):+ await PipeRun(pipe_router=mock_router).run(pipe_job=mock_job)++ (failure_record,) = [+ record for record in caplog.records if record.name == pipe_run_module.__name__ and record.getMessage() == "Pipe execution failed"+ ]+ record_fields = vars(failure_record)+ assert record_fields["pipe_code"] == "describe_company"+ assert record_fields["pipe_ref"] == "company.describe_company"+ assert record_fields["error.type"] == "RuntimeError"+ assert record_fields["error.message"] == "router blew up"+ assert failure_record.exc_info is None+async def test_run_success_no_delivery_when_none(self, mocker: MockerFixture) -> None:"""When delivery_assignment is None, the delivery executor is not called."""mock_output = mocker.MagicMock()diff --git a/tests/unit/pipelex/pipe_run/test_tracing_assembly.py b/tests/unit/pipelex/pipe_run/test_tracing_assembly.pyindex 4c682e7e5..fd7e3207e 100644--- a/tests/unit/pipelex/pipe_run/test_tracing_assembly.py+++ b/tests/unit/pipelex/pipe_run/test_tracing_assembly.py@@ -1,4 +1,5 @@import json+import loggingfrom datetime import UTC, datetimeimport pytest@@ -15,6 +16,7 @@ from pipelex.pipe_run.tracing_assembly import TracingAssembly, assemble_tracing,from pipelex.system.exceptions import MissingDependencyErrorfrom pipelex.system.job_metadata import JobMetadata, RunMetadatafrom pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.tools.log.log_context import PIPELINE_RUN_ID_FIELD, REQUEST_ID_FIELD, get_log_contextfrom pipelex.tracing.exceptions import EventLogReadError, EventLogSetupErrorfrom pipelex.tracing.trace_events import UsageReportEvent@@ -169,6 +171,29 @@ class TestTracingAssembly:assert result.usage_assembly_error is not Noneevent_log.close.assert_called_once()+ def test_a_line_it_logs_names_the_run_when_nothing_bound_it(self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture) -> None:+ """The durable-execution activity `act_assemble_tracing` runs this under no binding of the run.++ The assembly's lines dropped `pipeline_run_id` from their fields on the assumption that the run's context binds+ it, which holds under `PipeRun` and not in the activity, so an activity's failed read named no run at all.+ """+ self._enable_tracing(mocker)+ event_log = mocker.MagicMock()+ event_log.read_events = mocker.MagicMock(side_effect=OSError("file vanished"))+ mocker.patch(f"{_MODULE}.make_event_log", return_value=event_log)+ run_metadata = RunMetadata(+ storage_scope="test/scope", read_scope=None, user_id="tracing-assembly-test", pipeline_run_id="plr-activity", request_id="req-activity"+ )+ assert get_log_context() is None++ with caplog.at_level(logging.WARNING, logger=_MODULE):+ assemble_tracing(pipeline_run_id="plr-activity", assemble_graph=True, assemble_usage=True, run_metadata=run_metadata)++ (record,) = [record for record in caplog.records if record.getMessage() == "Tracing assembly could not read the run's trace events"]+ assert getattr(record, PIPELINE_RUN_ID_FIELD) == "plr-activity"+ assert getattr(record, REQUEST_ID_FIELD) == "req-activity"+ assert get_log_context() is None, "the binding is released when the assembly returns"+def test_make_event_log_setup_error_is_caught(self, mocker: MockerFixture) -> None:"""A construction-time backend failure degrades instead of aborting the run.diff --git a/tests/unit/pipelex/providers/typesafe/test_typesafe_judgment_worker.py b/tests/unit/pipelex/providers/typesafe/test_typesafe_judgment_worker.pyindex 8556758fc..452d8b5a8 100644--- a/tests/unit/pipelex/providers/typesafe/test_typesafe_judgment_worker.py+++ b/tests/unit/pipelex/providers/typesafe/test_typesafe_judgment_worker.py@@ -192,7 +192,10 @@ class TestTypesafeJudgmentWorker:if expects_warning:warning.assert_called_once()- assert "'jev-latest'" in warning.call_args.args[0]- assert "'jev-1.13.0'" in warning.call_args.args[0]+ # The pinned id rides gen_ai.response.model, as on the LLM span, and the id that answered beside it+ fields = warning.call_args.kwargs["fields"]+ assert fields["gen_ai.request.model"] == "jev-1.13.0"+ assert fields["gen_ai.response.model"] == "jev-latest"+ assert fields["answered_model_id"] == "jev-1.13.0"else:warning.assert_not_called()diff --git a/tests/unit/pipelex/system/configuration/test_boot_tolerance.py b/tests/unit/pipelex/system/configuration/test_boot_tolerance.pyindex 82599a1a0..117a51c28 100644--- a/tests/unit/pipelex/system/configuration/test_boot_tolerance.py+++ b/tests/unit/pipelex/system/configuration/test_boot_tolerance.py@@ -36,6 +36,8 @@ from pipelex.system.configuration.config_loader import ConfigLoaderfrom pipelex.system.configuration.config_surface import (PIPELEX_CONFIG_SURFACE_ID,TELEMETRY_CONFIG_SURFACE_ID,+ StaleConfigurationFile,+ StaleConfigurationWarning,replay_surface_files_in_memory,stale_configuration_warning,)@@ -295,9 +297,76 @@ class TestWhatTheWarningSays:warning = stale_configuration_warning(plans=plans, walked_dirs=[tmp_path])- assert str(stale) in warning- assert "pipelex migrate" in warning- assert "Nothing was written" in warning+ assert [stale_file.file_path for stale_file in warning.files] == [stale]+ assert warning.files[0].is_reached_by_migrate++ def test_each_stale_file_is_a_line_of_its_own_with_a_fixed_message(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """The shape the log-call conventions give it: the message names the remedy, the file rides a field.++ One line per file rather than one listing them all, because a field the console cuts at+ its width cannot carry a list of paths a person has to read, and the message cannot carry+ them without becoming a different string on every boot. The two files sit on either side+ of the walk, so the two lines name the two remedies, and neither message mentions a path.+ """+ walked = tmp_path / "walked"+ walked.mkdir()+ outside = tmp_path / "outside"+ outside.mkdir()+ inside_file, inside_plans = self._stale_telemetry_plans(directory=walked)+ outside_file, outside_plans = self._stale_telemetry_plans(directory=outside)+ warning_spy = mocker.patch.object(log, "warning")++ stale_configuration_warning(plans=inside_plans + outside_plans, walked_dirs=[walked]).emit()++ assert warning_spy.call_count == 2+ inside_call, outside_call = warning_spy.call_args_list+ assert "run `pipelex migrate` to update it" in inside_call.args[0]+ assert "`pipelex migrate` does not reach it, so update it where it lives" in outside_call.args[0]+ assert inside_call.kwargs["fields"] == {+ "file.path": str(inside_file),+ "migration_steps": ["Nest the flat telemetry settings under [custom_posthog]"],+ "has_blocked_steps": False,+ }+ assert outside_call.kwargs["fields"]["file.path"] == str(outside_file)+ for call in (inside_call, outside_call):+ assert str(tmp_path) not in call.args[0]++ @pytest.mark.parametrize(+ ("topic", "is_reached_by_migrate", "has_blocked_steps", "expected_remedy"),+ [+ ("in reach", True, False, "run `pipelex migrate` to update it"),+ ("in reach, blocked", True, True, "run `pipelex migrate` to update it, and make by hand the changes it reports it cannot apply"),+ ("out of reach", False, False, "`pipelex migrate` does not reach it, so update it where it lives"),+ (+ "out of reach, blocked",+ False,+ True,+ "`pipelex migrate` does not reach it, so update it where it lives, including changes no migration can apply for you",+ ),+ ],+ )+ def test_each_message_says_nothing_was_written_and_a_blocked_file_says_so(+ self, tmp_path: Path, mocker: MockerFixture, topic: str, is_reached_by_migrate: bool, has_blocked_steps: bool, expected_remedy: str+ ) -> None:+ """The warning used to be one text that said nothing was written, and that some of what a file needs cannot be applied for+ the user, with `pipelex migrate` reporting it; a fixed message per file must keep saying both.+ """+ stale_file = StaleConfigurationFile(+ file_path=tmp_path / "pipelex.toml",+ is_reached_by_migrate=is_reached_by_migrate,+ migration_steps=["Rename the default log level"],+ has_blocked_steps=has_blocked_steps,+ )+ warning_spy = mocker.patch.object(log, "warning")++ StaleConfigurationWarning(files=[stale_file]).emit()++ warning_spy.assert_called_once()+ message = warning_spy.call_args.args[0]+ assert message == (+ f"A configuration file is out of date and was read as if it had been migrated, and nothing was written; {expected_remedy}"+ ), topic+ assert warning_spy.call_args.kwargs["fields"]["has_blocked_steps"] is has_blocked_stepsdef test_it_says_what_the_ledger_carried_and_nothing_read_from_the_file(self, tmp_path: Path) -> None:"""Ledger text only, the same rule the migration report obeys — a boot warning is read in@@ -307,8 +376,8 @@ class TestWhatTheWarningSays:warning = stale_configuration_warning(plans=plans, walked_dirs=[tmp_path])- assert "Nest the flat telemetry settings under [custom_posthog]" in warning- assert "phc_a_secret_the_user_owns" not in warning+ assert warning.files[0].migration_steps == ["Nest the flat telemetry settings under [custom_posthog]"]+ assert "phc_a_secret_the_user_owns" not in repr(warning.files[0].log_fields())def test_a_file_outside_the_walk_is_not_offered_the_command(self, tmp_path: Path) -> None:"""`Pipelex.make(config_dir=…)` outside the two walked directories is the live case.@@ -324,18 +393,15 @@ class TestWhatTheWarningSays:warning = stale_configuration_warning(plans=plans, walked_dirs=[tmp_path / "global", tmp_path / "project"])- assert str(stale) in warning- assert "Nothing was written" in warning- assert "does not reach" in warning- assert "yours to update where it lives" in warning- assert "Run `pipelex migrate`" not in warning+ assert [stale_file.file_path for stale_file in warning.files] == [stale]+ assert not warning.files[0].is_reached_by_migratedef test_a_walk_of_one_file_in_and_one_out_names_each_side(self, tmp_path: Path) -> None:- """The mixed case is reachable, and a single closing sentence would be wrong for one of them.+ """The mixed case is reachable, and a single remedy would be wrong for one of them.A load merges tiers from several directories at once — under unit testing it also mergesthis repository's own `tests/pipelex_{run_mode}.toml`, which is outside the walk by design.- So the warning splits the files rather than picking one verb for all of them.+ So each file carries its own reach rather than the load picking one remedy for all of them."""walked = tmp_path / "walked"walked.mkdir()@@ -346,8 +412,10 @@ class TestWhatTheWarningSays:warning = stale_configuration_warning(plans=inside_plans + outside_plans, walked_dirs=[walked])- assert f"Run `pipelex migrate` to bring '{inside_file}' up to date." in warning- assert f"`pipelex migrate` does not reach '{outside_file}' — that file is yours to update where it lives." in warning+ assert [(stale_file.file_path, stale_file.is_reached_by_migrate) for stale_file in warning.files] == [+ (inside_file, True),+ (outside_file, False),+ ]def test_a_file_in_a_directory_its_own_surface_does_not_own_is_out_of_reach(self, tmp_path: Path) -> None:"""The walk reaches `inference/backends/` now — but for the surface that owns it, not for any file in it.@@ -362,8 +430,7 @@ class TestWhatTheWarningSays:warning = stale_configuration_warning(plans=plans, walked_dirs=[tmp_path])- assert "does not reach" in warning- assert "Run `pipelex migrate`" not in warning+ assert not warning.files[0].is_reached_by_migratedef test_a_file_in_the_directory_its_surface_owns_is_in_reach(self, tmp_path: Path, synthetic_migration_dir: Path) -> None:"""The other half, and the one the fourth surface needs: reach follows the surface's own directory.@@ -389,8 +456,7 @@ class TestWhatTheWarningSays:warning = stale_configuration_warning(plans=replayed.plans, walked_dirs=[tmp_path])- assert "Run `pipelex migrate` to bring the files up to date." in warning- assert "does not reach" not in warning+ assert warning.files[0].is_reached_by_migratedef test_a_directory_no_surface_owns_stays_out_of_reach(self, tmp_path: Path, synthetic_migration_dir: Path) -> None:"""`inference/deck/` is beside a directory the walk now enters and is still never entered itself.@@ -415,8 +481,7 @@ class TestWhatTheWarningSays:warning = stale_configuration_warning(plans=replayed.plans, walked_dirs=[tmp_path])- assert "does not reach" in warning- assert "Run `pipelex migrate`" not in warning+ assert not warning.files[0].is_reached_by_migratedef test_a_file_symlinked_out_of_a_walked_directory_is_still_in_reach(self, tmp_path: Path) -> None:"""Where the file points is not where the command looks for it.@@ -439,8 +504,7 @@ class TestWhatTheWarningSays:assert replayed is not Nonewarning = stale_configuration_warning(plans=replayed.plans, walked_dirs=[walked])- assert "Run `pipelex migrate` to bring the files up to date." in warning- assert "does not reach" not in warning+ assert warning.files[0].is_reached_by_migrateclass TestTheTelemetryLoader:@@ -456,13 +520,14 @@ class TestTheTelemetryLoader:stale = global_dir / "telemetry.toml"stale.write_text(old_shape_telemetry_document(), encoding="utf-8")before = stale.read_bytes()- warning = mocker.patch.object(telemetry_loader_module.log, "warning")+ warning = mocker.patch.object(log, "warning")config = load_telemetry_config(secrets_provider=secrets_provider)assert config.custom_posthog is not Noneassert stale.read_bytes() == before, "a tolerated boot writes nothing"assert "pipelex migrate" in warning.call_args.args[0]+ assert warning.call_args.kwargs["fields"]["file.path"] == str(stale)def test_a_file_the_ledger_cannot_explain_still_raises(self,@@ -552,7 +617,7 @@ class TestTheMainConfigurationLoader:assert config.runtime.log.default_log_level is LogLevel.DEBUGparked = loader.take_stale_configuration_warning()assert parked is not None- assert "pipelex migrate" in parked+ assert [stale_file.is_reached_by_migrate for stale_file in parked.files] == [True]assert loader.take_stale_configuration_warning() is None, "a warning is emitted once"def test_the_warning_reads_the_walk_off_the_loader_rather_than_deriving_its_own(@@ -586,8 +651,7 @@ class TestTheMainConfigurationLoader:parked = loader.take_stale_configuration_warning()assert parked is not None- assert "does not reach" in parked- assert "Run `pipelex migrate`" not in parked+ assert [stale_file.is_reached_by_migrate for stale_file in parked.files] == [False]@pytest.mark.usefixtures("fake_dirs")def test_a_healthy_configuration_parks_no_warning(self) -> None:diff --git a/tests/unit/pipelex/system/test_positive_int_env.py b/tests/unit/pipelex/system/test_positive_int_env.pynew file mode 100644index 000000000..189c192b6--- /dev/null+++ b/tests/unit/pipelex/system/test_positive_int_env.py@@ -0,0 +1,36 @@+import os++import pytest+from pytest_mock import MockerFixture++from pipelex import log+from pipelex.system.environment import get_positive_int_env++ENV_VAR = "PIPELEX_MAX_FETCHED_PACKAGE_FILES"+++class TestPositiveIntEnv:+ @pytest.mark.parametrize("raw", ["many", "0", "-3", "2.5"])+ def test_a_value_that_is_no_positive_integer_falls_back_naming_the_variable(self, mocker: MockerFixture, raw: str) -> None:+ """An unparseable and a non-positive value fall back alike, and the line names the variable and the default, never the value."""+ mocker.patch.dict(os.environ, {ENV_VAR: raw})+ warning_spy = mocker.patch.object(log, "warning")++ assert get_positive_int_env(env_var=ENV_VAR, default=256) == 256++ warning_spy.assert_called_once_with(+ "An environment variable holds no positive integer, so its default applies",+ fields={"env_var": ENV_VAR, "default_value": 256},+ )++ @pytest.mark.parametrize(("raw", "expected"), [("12", 12), (None, 256), ("", 256)], ids=["positive", "unset", "empty"])+ def test_a_positive_integer_or_no_value_is_read_silently(self, mocker: MockerFixture, raw: str | None, expected: int) -> None:+ environment = {key: value for key, value in os.environ.items() if key != ENV_VAR}+ if raw is not None:+ environment[ENV_VAR] = raw+ mocker.patch.dict(os.environ, environment, clear=True)+ warning_spy = mocker.patch.object(log, "warning")++ assert get_positive_int_env(env_var=ENV_VAR, default=256) == expected++ warning_spy.assert_not_called()diff --git a/tests/unit/pipelex/tools/test_log_console_field_values.py b/tests/unit/pipelex/tools/test_log_console_field_values.pyindex 2329a10f3..05ff4916b 100644--- a/tests/unit/pipelex/tools/test_log_console_field_values.py+++ b/tests/unit/pipelex/tools/test_log_console_field_values.py@@ -1,5 +1,6 @@from __future__ import annotations+import jsonimport mathfrom pathlib import Pathfrom typing import Any@@ -34,12 +35,13 @@ class TestConsoleFieldValues:("tab\\tliteral\ttab", '"tab\\\\tliteral\\ttab"'),("line\nbreak", '"line\\nbreak"'),("\x1b[31mred", '"\\x1b[31mred"'),- ({"key": "value", "nested": [1, 2]}, '{"key":"value","nested":[1,2]}'),- (["a", "b"], '["a","b"]'),- (("a", 1), '["a",1]'),+ ({"key": "value", "nested": [1, 2]}, '"{\\"key\\":\\"value\\",\\"nested\\":[1,2]}"'),+ (["a", "b"], '"[\\"a\\",\\"b\\"]"'),+ (("a", 1), '"[\\"a\\",1]"'),+ ([1, 2], "[1,2]"),(math.nan, "NaN"),- ({"ratio": math.inf}, '{"ratio":"Infinity"}'),- (_Sample(code="x", count=2), '{"code":"x","count":2}'),+ ({"ratio": math.inf}, '"{\\"ratio\\":\\"Infinity\\"}"'),+ (_Sample(code="x", count=2), '"{\\"code\\":\\"x\\",\\"count\\":2}"'),(Path("reports/march.csv"), "reports/march.csv"),],ids=[@@ -61,6 +63,7 @@ class TestConsoleFieldValues:"mapping","list","tuple",+ "list of numbers","nan","nested infinity","model",@@ -79,7 +82,21 @@ class TestConsoleFieldValues:circular: dict[str, Any] = {}circular["self"] = circular- assert format_field_value(value=circular) == "{'self': {...}}"+ assert format_field_value(value=circular) == "\"{'self': {...}}\""++ def test_a_long_list_of_paths_is_cut_before_it_is_quoted_so_no_tail_reads_as_a_pair(self) -> None:+ """Cut as rendered and left bare, the list kept an unterminated string, and its tail ``b=c/…`` read as a pair of its own."""+ paths = [f"/x/My dir/a b=c/{index_path}/backends.toml" for index_path in range(6)]++ rendered = format_field_value(value=paths)++ rendering = json.dumps(paths, separators=(",", ":"))+ kept = rendering[: FIELD_VALUE_MAX_LENGTH - len(TRUNCATION_MARK)]+ assert rendered == '"' + kept.replace("\\", "\\\\").replace('"', '\\"') + TRUNCATION_MARK + '"'+ assert rendered.startswith('"[\\"/x/My dir/a b=c/0/backends.toml\\",')+ # The value is one quoted span: every quote inside it is escaped, so nothing after a space reads as a pair.+ inner = rendered[1:-1]+ assert '"' not in inner.replace('\\"', "")def test_a_long_value_is_cut_short_at_the_limit_with_a_mark(self) -> None:rendered = format_field_value(value=list(range(200)))diff --git a/tests/unit/pipelex/tools/test_log_console_fields.py b/tests/unit/pipelex/tools/test_log_console_fields.pyindex aba6d3ba6..eb13a3197 100644--- a/tests/unit/pipelex/tools/test_log_console_fields.py+++ b/tests/unit/pipelex/tools/test_log_console_fields.py@@ -11,6 +11,8 @@ from pipelex.tools.log.console_fields import (FIELD_KEY_STYLE,FIELD_STYLES,FIELD_VALUE_MAX_LENGTH,+ FINDING_MESSAGE_FIELD,+ LEFT_CUT_FIELDS,TRUNCATION_MARK,UNMAPPED_FIELD_STYLE,)@@ -166,6 +168,65 @@ class TestConsoleFields:assert text.plain.endswith(f"error.message={'y' * (ERROR_MESSAGE_MAX_LENGTH - len(TRUNCATION_MARK))}{TRUNCATION_MARK}")assert "y" * ERROR_MESSAGE_MAX_LENGTH not in text.plain+ @pytest.mark.parametrize("path_field", sorted(LEFT_CUT_FIELDS))+ def test_a_long_path_is_cut_at_its_start_so_the_file_name_stays(self, path_field: str) -> None:+ """Cut at its end, a long path kept the directory every line of a run shares and lost the file's name."""+ long_path = "/Users/someone/projects/acme/" + "nested-directory/" * 8 + "invoice_template_v2.docx"+ text = rendered_text(record=record_with_fields(message="Read", extra={path_field: long_path, "excerpt": "x" * 500}))++ kept_tail = long_path[len(long_path) - FIELD_VALUE_MAX_LENGTH + len(TRUNCATION_MARK) :]+ assert f"{path_field}={TRUNCATION_MARK}{kept_tail} " in text.plain+ assert kept_tail.endswith("/invoice_template_v2.docx")+ assert "/Users/someone" not in text.plain+ assert text.plain.endswith(f"excerpt={'x' * (FIELD_VALUE_MAX_LENGTH - len(TRUNCATION_MARK))}{TRUNCATION_MARK}")++ @pytest.mark.parametrize(+ ("topic", "file_name"),+ [+ ("a space", "file fake=value.txt"),+ ("an equals sign", "file=fake.txt"),+ ],+ )+ def test_a_long_quoted_path_is_cut_before_it_is_quoted_so_its_quotes_stay_balanced(self, topic: str, file_name: str) -> None:+ """Cut after quoting, the path lost its opening quote, and its tail read as a pair of its own: ``file.path=…/file fake=value.txt"``."""+ long_path = "/Users/someone/projects/acme/" + "nested-directory/" * 8 + file_name+ text = rendered_text(record=record_with_fields(message="Read", extra={"file.path": long_path, "attempt": 2}))++ kept_tail = long_path[len(long_path) - FIELD_VALUE_MAX_LENGTH + len(TRUNCATION_MARK) :]+ assert text.plain.endswith(f'file.path="{TRUNCATION_MARK}{kept_tail}" attempt=2'), topic+ assert kept_tail.endswith(f"/{file_name}"), topic++ def test_a_long_quoted_value_is_cut_before_it_is_quoted_so_its_closing_quote_stays(self) -> None:+ """Cut after quoting, a long spaced value lost its closing quote, and every pair after it read as part of it."""+ excerpt = "two words " * 20+ text = rendered_text(record=record_with_fields(message="Read", extra={"excerpt": excerpt, "attempt": 2}))++ kept_head = excerpt[: FIELD_VALUE_MAX_LENGTH - len(TRUNCATION_MARK)]+ assert text.plain.endswith(f'excerpt="{kept_head}{TRUNCATION_MARK}" attempt=2')++ def test_a_cut_never_splits_an_escape(self) -> None:+ """A quote escaped at the cut kept its backslash and lost the quote, and the backslash then escaped the closing one."""+ excerpt = "x" * (FIELD_VALUE_MAX_LENGTH - len(TRUNCATION_MARK) - 1) + '"' + "y" * 40+ text = rendered_text(record=record_with_fields(message="Read", extra={"excerpt": excerpt, "attempt": 2}))++ assert text.plain.endswith(f'excerpt="{"x" * (FIELD_VALUE_MAX_LENGTH - len(TRUNCATION_MARK) - 1)}\\"{TRUNCATION_MARK}" attempt=2')++ def test_a_short_path_is_written_whole(self) -> None:+ text = rendered_text(record=record_with_fields(message="Read", extra={"file.path": "/repo/.pipelex/pipelex.toml"}))++ assert text.plain.endswith("file.path=/repo/.pipelex/pipelex.toml")++ def test_a_template_finding_gets_the_error_message_cut(self) -> None:+ """The finding is the actionable part of a PipeDocGen template warning, and the common cut lost it to a fragment."""+ finding = "The placeholder 'invoice.lines' is read as a list but the step's input 'invoice' declares it a single " + "Line; " * 20+ flood = "z" * (2 * ERROR_MESSAGE_MAX_LENGTH)+ whole = rendered_text(record=record_with_fields(message="Checked", extra={FINDING_MESSAGE_FIELD: finding}))+ flooded = rendered_text(record=record_with_fields(message="Checked", extra={FINDING_MESSAGE_FIELD: flood}))++ assert len(finding) > FIELD_VALUE_MAX_LENGTH+ assert whole.plain.endswith(f'{FINDING_MESSAGE_FIELD}="' + finding.replace('"', '\\"') + '"')+ assert flooded.plain.endswith(f"{FINDING_MESSAGE_FIELD}={'z' * (ERROR_MESSAGE_MAX_LENGTH - len(TRUNCATION_MARK))}{TRUNCATION_MARK}")+def test_a_field_is_styled_by_its_name_and_a_field_outside_the_map_is_dimmed(self) -> None:text = rendered_text(record=record_with_fields(diff --git a/tests/unit/pipelex/tools/test_log_error_fields.py b/tests/unit/pipelex/tools/test_log_error_fields.pyindex 6def58a0e..f29d26b4c 100644--- a/tests/unit/pipelex/tools/test_log_error_fields.py+++ b/tests/unit/pipelex/tools/test_log_error_fields.py@@ -3,10 +3,14 @@ from __future__ import annotationsimport ioimport jsonimport logging-from typing import TYPE_CHECKING+import uuid+from typing import TYPE_CHECKING, Annotated, Literalimport pytest+from pydantic import BaseModel, ConfigDict, Field, RootModel, ValidationError, field_validator, model_validator+from pydantic_core import PydanticCustomError+from pipelex.core.stuffs.date_content import DateContentfrom pipelex.system.configuration.config_loader import ConfigLoaderfrom pipelex.tools.log.error_fields import ERROR_MESSAGE_FIELD, ERROR_TYPE_FIELD, error_fieldsfrom pipelex.tools.log.json_log_sink import EXCEPTION_KEY, LOGGER_KEY, MESSAGE_KEY, JsonLogSink@@ -22,6 +26,96 @@ class _ManifestParseError(ValueError):pass+class _Settings(BaseModel):+ retries: int+ limits: dict[str, int]+++class _Retries(RootModel[int]):+ pass+++# A value no secret pattern matches, so the redaction never hides it and only the field's own rule can keep it out.+_PAYLOAD = "confidential-patient-diagnosis"+++class _Diagnosis(BaseModel):+ """A model whose validators quote the value they reject, as a custom validator is free to."""++ diagnosis: str+ severity: int = 0+ code: str = "none"+ reviewed: bool = False++ @field_validator("diagnosis")+ @classmethod+ def _diagnosis_is_coded(cls, value: str) -> str:+ if not value.startswith("ICD-"):+ msg = f"{value!r} is not a coded diagnosis"+ raise ValueError(msg)+ return value++ @field_validator("code")+ @classmethod+ def _code_is_known(cls, value: str) -> str:+ if value != "none":+ error_type = "unknown_code"+ message_template = "The code {code} is not known"+ raise PydanticCustomError(error_type, message_template, {"code": value})+ return value++ @field_validator("severity", mode="before")+ @classmethod+ def _severity_is_spelt_out(cls, value: object) -> object:+ if isinstance(value, str) and not value.isdigit():+ # A custom error borrowing a built-in type's name, with a message of its own that quotes the input.+ error_type = "int_parsing"+ message_template = "Severity {severity} is not a number"+ raise PydanticCustomError(error_type, message_template, {"severity": value})+ return value+++class _Review(BaseModel):+ note: str++ @model_validator(mode="after")+ def _note_is_signed(self) -> _Review:+ assert self.note.endswith("-- signed"), f"unsigned note {self.note!r}"+ return self+++class _Letter(BaseModel):+ kind: Literal["letter"]+++class _Parcel(BaseModel):+ kind: Literal["parcel"]+++class _Shipment(BaseModel):+ item: Annotated[_Letter | _Parcel, Field(discriminator="kind")]+++class _Record(BaseModel):+ record_id: uuid.UUID+++class _Limits(BaseModel):+ model_config = ConfigDict(extra="forbid")++ burst: int = 1+++class _StrictSettings(BaseModel):+ model_config = ConfigDict(extra="forbid")++ limits: _Limits = Field(default_factory=_Limits)+++class _Bounded(BaseModel):+ code: Annotated[str, Field(max_length=8)]++class TestLogErrorFields:@pytest.mark.parametrize(("topic", "exc", "text", "expected"),@@ -39,6 +133,122 @@ class TestLogErrorFields:def test_the_fields_name_the_class_and_carry_the_text(self, topic: str, exc: BaseException, text: str | None, expected: tuple[str, str]) -> None:assert error_fields(exc=exc, text=text) == {ERROR_TYPE_FIELD: expected[0], ERROR_MESSAGE_FIELD: expected[1]}, topic+ def test_a_validation_error_is_written_as_its_locations_and_reasons_never_its_input(self) -> None:+ """A pydantic error's own text quotes every value it refused, which is payload: a run's input or a model's response."""+ secret_looking = "sk-live-4f9a8b7c6d5e4f3a2b1c"+ with pytest.raises(ValidationError) as caught:+ _Settings.model_validate({"retries": secret_looking, "limits": {"burst": secret_looking}})+ assert secret_looking in str(caught.value)++ fields = error_fields(exc=caught.value)++ assert fields == {+ ERROR_TYPE_FIELD: "ValidationError",+ ERROR_MESSAGE_FIELD: (+ "retries: Input should be a valid integer, unable to parse string as an integer; "+ "limits.burst: Input should be a valid integer, unable to parse string as an integer"+ ),+ }+ assert secret_looking not in fields[ERROR_MESSAGE_FIELD]++ def test_a_validation_error_at_the_root_names_its_reason_alone(self) -> None:+ with pytest.raises(ValidationError) as caught:+ _Retries.model_validate("sk-live-4f9a8b7c6d5e4f3a2b1c")++ assert error_fields(exc=caught.value)[ERROR_MESSAGE_FIELD] == "Input should be a valid integer, unable to parse string as an integer"++ @pytest.mark.parametrize(+ ("topic", "document", "expected"),+ [+ ("a field validator's ValueError", {"diagnosis": _PAYLOAD}, "diagnosis: value_error"),+ ("a PydanticCustomError of its own type", {"diagnosis": "ICD-10", "code": _PAYLOAD}, "code: unknown_code"),+ ("a PydanticCustomError borrowing a built-in type's name", {"diagnosis": "ICD-10", "severity": _PAYLOAD}, "severity: int_parsing"),+ ],+ )+ def test_a_custom_validator_message_is_written_as_its_type_never_its_text(self, topic: str, document: dict[str, object], expected: str) -> None:+ """A validator writes its own message, and a message can quote the very value the validator rejected."""+ with pytest.raises(ValidationError) as caught:+ _Diagnosis.model_validate(document)+ assert _PAYLOAD in str(caught.value), topic++ message = error_fields(exc=caught.value)[ERROR_MESSAGE_FIELD]++ assert message == expected, topic+ assert _PAYLOAD not in message, topic++ def test_a_model_validator_assertion_has_no_location_and_is_written_as_its_type(self) -> None:+ with pytest.raises(ValidationError) as caught:+ _Review.model_validate({"note": _PAYLOAD})+ assert _PAYLOAD in str(caught.value)++ assert error_fields(exc=caught.value)[ERROR_MESSAGE_FIELD] == "assertion_error"++ def test_a_date_content_rejection_is_written_without_the_value_it_quotes(self) -> None:+ """`DateContent`'s validator names the string it could not read as a date, which can be a run's input."""+ with pytest.raises(ValidationError) as caught:+ DateContent.model_validate({"date": _PAYLOAD})+ assert _PAYLOAD in caught.value.errors()[0]["msg"]++ assert error_fields(exc=caught.value) == {ERROR_TYPE_FIELD: "ValidationError", ERROR_MESSAGE_FIELD: "date: value_error"}++ def test_pydantic_own_reasons_are_kept_beside_a_custom_one(self) -> None:+ """Only the validator's message goes: the reasons pydantic wrote itself, which quote no input, stay readable."""+ with pytest.raises(ValidationError) as mixed:+ _Diagnosis.model_validate({"diagnosis": _PAYLOAD, "reviewed": "not a boolean"})++ assert error_fields(exc=mixed.value)[ERROR_MESSAGE_FIELD] == (+ "diagnosis: value_error; reviewed: Input should be a valid boolean, unable to interpret input"+ )++ @pytest.mark.parametrize(+ ("topic", "model", "document", "input_echo", "expected"),+ [+ ("an unknown tag of a discriminated union", _Shipment, {"item": {"kind": _PAYLOAD}}, _PAYLOAD, "item: union_tag_invalid"),+ ("a value that is no UUID", _Record, {"record_id": _PAYLOAD}, "found `o`", "record_id: uuid_parsing"),+ ("a key a nested model forbids", _StrictSettings, {"limits": {_PAYLOAD: 1}}, None, "limits: Extra inputs are not permitted"),+ ("a key the root model forbids", _StrictSettings, {_PAYLOAD: 1}, None, "Extra inputs are not permitted"),+ ],+ )+ def test_a_message_or_a_location_drawn_from_the_input_never_reaches_the_line(+ self,+ json_buffer: tuple[Log, io.StringIO],+ topic: str,+ model: type[BaseModel],+ document: dict[str, object],+ input_echo: str | None,+ expected: str,+ ) -> None:+ """Some of pydantic's own templates quote the input, and a forbidden key's location is the caller's key itself."""+ with pytest.raises(ValidationError) as caught:+ model.model_validate(document)+ (error,) = caught.value.errors(include_url=False, include_input=False)+ if input_echo is not None:+ assert input_echo in error["msg"], topic+ else:+ assert _PAYLOAD in [str(part) for part in error["loc"]], topic++ fields = error_fields(exc=caught.value)+ fresh, buffer = json_buffer+ fresh.warning("A document was refused", fields=fields)++ assert fields[ERROR_MESSAGE_FIELD] == expected, topic+ own_lines = [line for line in buffer.getvalue().splitlines() if line and json.loads(line)[LOGGER_KEY] == __name__]+ assert len(own_lines) == 1, topic+ assert json.loads(own_lines[0])[ERROR_MESSAGE_FIELD] == expected, topic+ assert _PAYLOAD not in own_lines[0], topic++ def test_a_bounded_value_keeps_pydantic_s_message_whose_bound_comes_from_the_schema(self) -> None:+ with pytest.raises(ValidationError) as caught:+ _Bounded.model_validate({"code": _PAYLOAD})++ assert error_fields(exc=caught.value)[ERROR_MESSAGE_FIELD] == "code: String should have at most 8 characters"++ def test_a_text_given_for_a_validation_error_is_carried_as_given(self) -> None:+ with pytest.raises(ValidationError) as caught:+ _Retries.model_validate("not a number")++ assert error_fields(exc=caught.value, text="line 3: invalid JSON")[ERROR_MESSAGE_FIELD] == "line 3: invalid JSON"+@pytest.fixturedef json_buffer(self, caplog: pytest.LogCaptureFixture) -> Iterator[tuple[Log, io.StringIO]]:"""A fresh ``Log`` with the json sink installed on a buffer, torn down so the root logger is left as found."""diff --git a/tests/unit/pipelex/tools/test_log_json_sink.py b/tests/unit/pipelex/tools/test_log_json_sink.pyindex 9fc9357dd..7c9b9d0f3 100644--- a/tests/unit/pipelex/tools/test_log_json_sink.py+++ b/tests/unit/pipelex/tools/test_log_json_sink.py@@ -18,6 +18,7 @@ import pytestfrom pydantic import BaseModelfrom pipelex.system.configuration.config_loader import ConfigLoader+from pipelex.tools.log.console_fields import ERROR_MESSAGE_MAX_LENGTH, FIELD_VALUE_MAX_LENGTH, FINDING_MESSAGE_FIELDfrom pipelex.tools.log.json_log_sink import EXCEPTION_KEY, LOGGER_KEY, MESSAGE_KEY, SEVERITY_KEY, TIME_KEY, JsonLogFormatter, JsonLogSinkfrom pipelex.tools.log.log import Logfrom pipelex.tools.log.log_config import LogConfig@@ -91,6 +92,23 @@ class TestJsonLogSink:assert structured[DATA_FIELD] == {"key": "value", "nested": {"flag": True}}assert structured[MESSAGE_KEY].startswith("Config:")+ def test_the_console_s_cuts_never_reach_a_structured_line(self, json_log: tuple[Log, io.StringIO]) -> None:+ """The console cuts a long value, a path at its start and a template finding past its own length; the json sink writes each whole."""+ fresh, buffer = json_log+ long_path = "/Users/someone/projects/acme/" + "nested-directory/" * 8 + "invoice_template_v2.docx"+ long_finding = "The placeholder 'invoice.lines' is read as a list " + "z" * (2 * ERROR_MESSAGE_MAX_LENGTH)+ long_excerpt = "x" * (2 * FIELD_VALUE_MAX_LENGTH)++ fresh.warning(+ "Checked", fields={"file.path": long_path, "template_file": long_path, FINDING_MESSAGE_FIELD: long_finding, "excerpt": long_excerpt}+ )++ (checked,) = _own_lines(buffer)+ assert checked["file.path"] == long_path+ assert checked["template_file"] == long_path+ assert checked[FINDING_MESSAGE_FIELD] == long_finding+ assert checked["excerpt"] == long_excerpt+def test_a_field_value_carrying_a_newline_is_still_one_line_and_forges_nothing(self, json_log: tuple[Log, io.StringIO]) -> None:"""Redaction neutralises the control characters in a field value before the sink writes it, so a caller cannot forge a line or a field."""fresh, buffer = json_logdiff --git a/tests/unit/pipelex/tools/test_log_secondary_exceptions.py b/tests/unit/pipelex/tools/test_log_secondary_exceptions.pynew file mode 100644index 000000000..206f1046b--- /dev/null+++ b/tests/unit/pipelex/tools/test_log_secondary_exceptions.py@@ -0,0 +1,109 @@+"""A handled exception that sits beside a payload-bearing one writes none of that payload to a structured sink.++Two shapes, each at a real call site, the records going the whole way to the ``json`` sink's line: a cleanup failing+while a primary ``ValidationError`` propagates, whose traceback would carry the primary's text through Python's+implicit chaining, and a ``ValidationError`` the code swallows, whose own text quotes the values it refused.+"""++from __future__ import annotations++import io+import json+import logging+from typing import TYPE_CHECKING, Any++import pytest+from pydantic import BaseModel, ValidationError++from pipelex.core.memory.working_memory import MAIN_STUFF_NAME+from pipelex.pipe_run.delivery_executor import DeliveryExecutor+from pipelex.runtime_boot import RuntimeBoot+from pipelex.system.configuration.config_loader import ConfigLoader+from pipelex.tools.log.error_fields import ERROR_MESSAGE_FIELD, ERROR_TYPE_FIELD+from pipelex.tools.log.json_log_sink import EXCEPTION_KEY, LOGGER_KEY, MESSAGE_KEY, JsonLogSink+from pipelex.tools.log.log import Log+from pipelex.tools.log.log_config import LogConfig+from pipelex.tools.misc.toml_utils import load_toml_from_path++if TYPE_CHECKING:+ from collections.abc import Iterator++ from pytest_mock import MockerFixture++# A value no secret pattern matches, so the redaction never hides it and only the call site's own rule can keep it out.+_PAYLOAD = "confidential-patient-diagnosis"+++class _RunInputs(BaseModel):+ patient_age: int+++def _lines_of(*, buffer: io.StringIO, logger_name: str) -> list[dict[str, Any]]:+ lines = [json.loads(line) for line in buffer.getvalue().splitlines() if line]+ return [line for line in lines if line[LOGGER_KEY] == logger_name]+++class TestSecondaryExceptionsCarryNoPayload:+ @pytest.fixture+ def json_buffer(self, caplog: pytest.LogCaptureFixture) -> Iterator[io.StringIO]:+ """The json sink installed on a buffer through a fresh ``Log``, torn down so the root logger is left as found."""+ caplog.set_level(logging.INFO, logger="pipelex")+ config_dict = load_toml_from_path(ConfigLoader().pipelex_root_dir / "pipelex.toml")+ buffer = io.StringIO()+ fresh = Log()+ fresh.configure(log_config=LogConfig.model_validate(config_dict["runtime"]["log"]))+ fresh.install_sink(JsonLogSink(stream=buffer))+ try:+ yield buffer+ finally:+ fresh.reset()++ def test_a_cleanup_failing_while_a_validation_error_propagates_writes_no_payload(self, json_buffer: io.StringIO, mocker: MockerFixture) -> None:+ """The plugin teardown callbacks of a failed boot run while the boot error propagates, and Python chains it onto theirs.++ Logged with its traceback, a failing callback's record carried the boot error's text in its ``exception`` key,+ and a ``ValidationError``'s text quotes the value it refused.+ """++ def failing_callback() -> None:+ msg = "the worker pool was already closed"+ raise RuntimeError(msg)++ boot = object.__new__(RuntimeBoot)+ boot._plugin_registrar = mocker.Mock(teardown_callbacks=[failing_callback]) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ primary_text = ""+ try:+ _RunInputs.model_validate({"patient_age": _PAYLOAD})+ except ValidationError as primary:+ primary_text = str(primary)+ # As `make()`'s handler does: the release runs inside the `except` that holds the boot error.+ boot._teardown_plugin_callbacks() # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+ assert _PAYLOAD in primary_text++ raw = json_buffer.getvalue()+ assert _PAYLOAD not in raw+ (line,) = _lines_of(buffer=json_buffer, logger_name="pipelex.runtime_boot")+ assert line[MESSAGE_KEY] == "A plugin teardown callback failed, and the remaining callbacks still run"+ assert line[ERROR_TYPE_FIELD] == "RuntimeError"+ assert line[ERROR_MESSAGE_FIELD] == "the worker pool was already closed"+ assert line["callback_name"].endswith("failing_callback")+ assert EXCEPTION_KEY not in line++ def test_a_swallowed_validation_error_writes_none_of_the_values_it_refused(self, json_buffer: io.StringIO) -> None:+ """A malformed absence record is treated as missing, and its error used to reach every sink as its full text."""+ malformed_record = {"variable_name": "diagnosis", "kind": _PAYLOAD, "reason": {"note": _PAYLOAD}}++ absence = DeliveryExecutor._get_raw_main_absence( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+ working_memory_raw={"absences": {MAIN_STUFF_NAME: malformed_record}}+ )++ assert absence is None+ raw = json_buffer.getvalue()+ assert _PAYLOAD not in raw+ (line,) = _lines_of(buffer=json_buffer, logger_name="pipelex.pipe_run.delivery_executor")+ assert line[MESSAGE_KEY] == "The absence record of the main output is malformed, so the delivery has no result to render"+ assert line[ERROR_TYPE_FIELD] == "ValidationError"+ assert line[ERROR_MESSAGE_FIELD].startswith("kind: Input should be ")+ assert "reason: Input should be a valid string" in line[ERROR_MESSAGE_FIELD]+ assert EXCEPTION_KEY not in linediff --git a/tests/unit/pipelex/tracing/test_ndjson_event_log.py b/tests/unit/pipelex/tracing/test_ndjson_event_log.pyindex 49f402a5f..a07dc0495 100644--- a/tests/unit/pipelex/tracing/test_ndjson_event_log.py+++ b/tests/unit/pipelex/tracing/test_ndjson_event_log.py@@ -136,6 +136,32 @@ class TestNdjsonEventLog:assert len(result) == 2assert any("corrupt" in record.message.lower() or "skipping" in record.message.lower() for record in caplog.records)+ def test_a_skipped_line_is_named_by_its_place_and_never_quoted(self, tmp_path: Path, caplog: pytest.LogCaptureFixture) -> None:+ """The warning says where the line is and where its parse stopped, and carries none of the line itself.++ A half-written line is a traced event cut short, so it holds the run's values; pydantic's own text+ for the failure quotes it whole. The warning takes the parse error's message instead, which only+ says where the parse stopped.+ """+ event_log = NdjsonEventLog(traces_dir=str(tmp_path))+ event_log.emit(make_trace_event(sequence=0))+ event_log.close()+ ndjson_file = tmp_path / "run_001" / "wf_wf_abc.ndjson"+ with open(ndjson_file, "a", encoding="utf-8") as fhandle:+ fhandle.write('{"event_kind": "pipe_start", "traced_value": "a_value_from_the_run\n')++ with caplog.at_level(logging.WARNING):+ event_log.read_events("run_001")++ (record,) = [record for record in caplog.records if record.levelno == logging.WARNING]+ assert record.getMessage() == "A corrupt line of a trace event log, not valid JSON, was skipped"+ attributes = vars(record)+ assert attributes["file.path"] == str(ndjson_file)+ assert attributes["line_number"] == 2+ assert attributes["error.type"] == "ValidationError"+ assert attributes["error.message"].startswith("Invalid JSON")+ assert "a_value_from_the_run" not in repr(attributes)+def test_a_line_the_event_models_refuse_raises_instead_of_vanishing(self, tmp_path: Path) -> None:"""A line that parses as JSON and is then refused was written whole, by a version whose event shapethis one no longer accepts. Skipping those returned an old run's log as an empty list, which every