Skip to content

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/Drift-contracts-logging · L-261009-f3ef28 (#1399)

Louis Choquel4d0c69f9f3fe
diff --git a/.drift/acks/log-call-convention.toml b/.drift/acks/log-call-convention.toml
new file mode 100644
index 000000000..a881b04ab
--- /dev/null
+++ b/.drift/acks/log-call-convention.toml
@@ -0,0 +1,9 @@
+contract = "log-call-convention"
+digest = "sha256:e8879f0f0bde0d0af33ac33fb0a6f4101114bbb96e9ba748e87cdad596d289fe"
+reviewed_by = "Claude (Opus 5.5)"
+reviewed_at = "2026-10-10T09:16:37Z"
+rationale = "clean-pass: the contract now also triggers on check_log_calls_cmd.py, whose options and output the page's Running it section states, and that section was re-derived from the command module. --quiet trims only a pass, to one line giving the baselined calls left and, when a comparison ran, that none were added since the trusted revision, while a failure still prints every call and entry; --prune rewrites the baseline without its stale signatures and then checks, never adding one; --report prints the baseline by package area, largest first, and returns before any gating; --against needs a ref that resolves, load_trusted_baseline raising otherwise; --against-merge-base skips the comparison with a notice when resolve_merge_base finds no merge base, and giving both options is an error; a failure lists each unlisted call with its file, line, qualified name and breaches, then the remedies of the rules seen, then the stale signatures under their keys, then the growth with both counts. The make wiring (--quiet with --against-merge-base origin/dev, or --against LOG_CALL_BASELINE_REF), the agent-check and check aggregates, the Lint (log calls) job under Lint (all), and the pre-main fresh check's base fetch and manual-run message match the Makefile and the workflows. The flag spellings and the -q alias are declared in pipelex/cli/dev_cli/_dev_cli.py, which is not a trigger. log_call_guard.py is unchanged since the last ack. The page needed no change."
+
+[trigger_files]
+"pipelex/cli/dev_cli/commands/check_log_calls_cmd.py" = "blob:47b6d88ea61446d2788f7fc7ee826cb1ffc7f582"
+"pipelex/cli/dev_cli/commands/log_call_guard.py" = "blob:f763d3d4448541d65273a44eef4eaa90cb2d35c4"
diff --git a/.drift/acks/logging-docs.toml b/.drift/acks/logging-docs.toml
new file mode 100644
index 000000000..a22d37363
--- /dev/null
+++ b/.drift/acks/logging-docs.toml
@@ -0,0 +1,9 @@
+contract = "logging-docs"
+digest = "sha256:26e4b90b98c1001b981f1d060d55c18383d988ec2704b2efa1f98f4af51c811d"
+reviewed_by = "Claude (Opus 5.5)"
+reviewed_at = "2026-10-10T09:16:44Z"
+rationale = "clean-pass: the only change to the triggers is console_fields.py's module docstring, which still gave LEFT_CUT_FIELDS as file.name alone after storage_key joined the set and now names the constant instead of listing its members; no constant or code moved, and error_fields.py is the blob the last ack reviewed. Re-derived the page's left-cut sentence from the code: it gives every LEFT_CUT_FIELD_SUFFIXES ending and both LEFT_CUT_FIELDS names, file.name and storage_key, so the page was already right where the docstring was not. Rechecked against the code the FIELD_STYLES keys and colours with unmapped fields and keys dimmed, the hidden run identifiers and data, the 80 cut and the 2000 cut of both FIELD_MAX_LENGTHS entries, the layout cut, the quoting characters, and the pydantic and extra_forbidden rules against SCHEMA_CONTEXT_KEYS and _pydantic_own_reason; all still hold. The page needed no change."
+
+[trigger_files]
+"pipelex/tools/log/console_fields.py" = "blob:cb51c6004ad7704f80f1753043180fb8e34b517c"
+"pipelex/tools/log/error_fields.py" = "blob:515b7649ddd22dceb192faa21713732ec61cd6e0"
diff --git a/docs/contribute/log-calls.md b/docs/contribute/log-calls.md
index cc76252eb..6986337aa 100644
--- a/docs/contribute/log-calls.md
+++ b/docs/contribute/log-calls.md
@@ -9,7 +9,7 @@ Pipelex's log calls follow the [log-call conventions](../tools/logging.md#log-ca
## What it reads
-The guard parses every Python module in `pipelex/`, except the facade's own package `pipelex/tools/log/`, and in the API server's `api/pipelex_api/`, which logs through the same facade. It reads the calls of the `log` facade, however a module reaches it: the name it imports `log` under, from `pipelex` or from `pipelex.tools.log.log`, an alias, a relative import and a star import included, or an attribute path through a module it imports, `pipelex.log.warning(...)` after `import pipelex`, `m.log.info(...)` after `from pipelex.tools.log import log as m`, `x.log.info(...)` after `import pipelex.tools.log.log as x`. The receiver is read where the call is made, through the bindings of its name that can reach the call, as a message's names are below: it is the facade when one of them imports the facade, so a parameter or a local named `log`, a stdlib logger say, is not the facade, and neither is a `log` imported in another function. A call's message is its first positional argument, or its `content=` keyword, and its `title=` and `inline=` keywords count as part of it, since the dispatch renders both into the message. A title or an inline title that is statically `None`, `title=None` or a name bound only to `None` and literals, is no message text at all. A `**` expansion of a dict literal whose keys are all strings passes its `content`, `title` and `inline` entries like keywords, `log.warning(**{"content": f"Value {value}"})` being read as `log.warning(content=f"Value {value}")`; any other `**` expansion in a facade call, `log.warning(**params)`, could carry the message or a title, so the call is refused as `non-literal`, at every level, since neither rule can read through it.
+The guard parses every Python module in `pipelex/`, except the facade's own package `pipelex/tools/log/`, and in the API server's `api/pipelex_api/`, which logs through the same facade. It reads the calls of the `log` facade, however a module reaches it: the name it imports `log` under, from `pipelex` or from `pipelex.tools.log.log`, an alias, a relative import and a star import included, or an attribute path through a module it imports, `pipelex.log.warning(...)` after `import pipelex`, `m.log.info(...)` after `from pipelex.tools.log import log as m`, `x.log.info(...)` after `import pipelex.tools.log.log as x`. The receiver is read where the call is made, through the bindings of its name that can reach the call, as a message's names are below, save that a name captured from an enclosing function is followed, through every binding that function makes: it is the facade when one of them imports the facade, so a parameter or a local named `log`, a stdlib logger say, is not the facade, and neither is a `log` imported in another function, while one imported in an enclosing function is. A call's message is its first positional argument, or its `content=` keyword, and its `title=` and `inline=` keywords count as part of it, since the dispatch renders both into the message. A title or an inline title that is statically `None`, `title=None` or a name bound only to `None` and literals, is no message text at all. A `**` expansion of a dict literal whose keys are all strings passes its `content`, `title` and `inline` entries like keywords, `log.warning(**{"content": f"Value {value}"})` being read as `log.warning(content=f"Value {value}")`; any other `**` expansion in a facade call, `log.warning(**params)`, could carry the message or a title, so the call is refused as `non-literal`, at every level, since neither rule can read through it.
## The rules
@@ -44,7 +44,7 @@ The `non-literal` rule is the guard's choice rather than the conventions' letter
### No markup at any level
-On every method, `log.verbose` and `log.debug` included, no literal text of a message, its title or its inline title holds a Rich markup tag. The literal text is the string constants written at the call, the literal parts of an f-string, the format string of a `%` or a `.format()`, and the literals a name read as above is bound to. It is read the way it reaches the console: a `+` whose operands are known, named literals, `+=` extensions and a name rebuilt from itself included, is folded into one text before the scan, so `"[" + "red]Loaded"` holds `[red]`, while a value the guard cannot read keeps the texts around it apart.
+On every method, `log.verbose` and `log.debug` included, no literal text of a message, its title or its inline title holds a Rich markup tag. The literal text is the string constants written at the call, the literal parts of an f-string, the format string of a `%` or a `.format()`, and the literals a name read as above is bound to. It is read the way it reaches the console: a `+` whose operands are known, named literals, `+=` extensions and a name rebuilt from itself included, is folded into one text before the scan, so `"[" + "red]Loaded"` holds `[red]`, while a value the guard cannot read keeps the texts around it apart, and so does a `+` whose two sides could combine into more texts than a fixed bound, each side then scanned on its own.
A markup tag is what Rich reads as one, matched with Rich's own tag pattern:
diff --git a/docs/tools/logging.md b/docs/tools/logging.md
index 3fe2fb582..726f44362 100644
--- a/docs/tools/logging.md
+++ b/docs/tools/logging.md
@@ -523,7 +523,7 @@ An exception rides the record, never the message. Spliced into the text, `{exc}`
- **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.
+- **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 a field with no length of its own is cut at 80 ([Fields after the message](#fields-after-the-message) names the fields that have one), 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.
diff --git a/drift.toml b/drift.toml
index 89c439dba..d0962ee67 100644
--- a/drift.toml
+++ b/drift.toml
@@ -118,3 +118,46 @@ review = [
"docs/under-the-hood/pipelex-kernel.md",
]
verify_commands = []
+
+[contracts.log-call-convention]
+description = "The log-calls doc is the log-call guard's specification and its command's reference, and must track the guard's behavior and the command's options and output."
+# The page states what the guard reads (the scanned trees, every way a module reaches the facade, a
+# message and its titles), each rule it refuses a call under, how a name is resolved through the
+# bindings and control flow of its scope, what counts as a Rich tag, and the baseline's key,
+# signature and shrink-only comparison. Under "Running it" it also states what each of the
+# command's options does and what a pass and a failure print, which the command module decides. A
+# reading, a rule or a signature changed in the guard, or an option or an output changed in the
+# command, silently falsifies the page a contributor converts a call by, which is the staleness
+# this contract exists to catch. No verify command: `check-log-calls` already gates `make check`,
+# `make agent-check` and CI, so re-running it here would only add the unstaged-file hard error
+# without adding a guarantee.
+triggers = [
+ "pipelex/cli/dev_cli/commands/log_call_guard.py",
+ "pipelex/cli/dev_cli/commands/check_log_calls_cmd.py",
+]
+review = [
+ "docs/contribute/log-calls.md",
+]
+verify_commands = []
+
+[contracts.logging-docs]
+description = "The logging doc restates the console's field rules and the handled-exception fields and must track the two modules that decide them."
+# The page restates, rule by rule, what the two modules decide: the style map (`FIELD_STYLES`) and
+# the fields it colours, the cut lengths (`FIELD_VALUE_MAX_LENGTH` and the generous ones in
+# `FIELD_MAX_LENGTHS`), the field names whose value is cut at its start (`LEFT_CUT_FIELD_SUFFIXES`,
+# `LEFT_CUT_FIELDS`), when a pydantic message is kept rather than its error type
+# (`SCHEMA_CONTEXT_KEYS`), and where an `extra_forbidden` error is located. A name added to one of
+# those sets, or a length moved, silently falsifies a sentence quantifying over it, which is the
+# staleness this contract exists to catch. The field-vocabulary table on the same page stays
+# outside any contract on purpose: its entries come from call sites everywhere, which no trigger
+# list could name, and a field joins the table in the change that first logs it. No verify
+# command: no gate checks these rules apart from the modules' own tests, which `make agent-test`
+# and CI already run.
+triggers = [
+ "pipelex/tools/log/console_fields.py",
+ "pipelex/tools/log/error_fields.py",
+]
+review = [
+ "docs/tools/logging.md",
+]
+verify_commands = []
diff --git a/pipelex/tools/log/console_fields.py b/pipelex/tools/log/console_fields.py
index 60128f1d3..cb51c6004 100644
--- a/pipelex/tools/log/console_fields.py
+++ b/pipelex/tools/log/console_fields.py
@@ -16,7 +16,7 @@ is cut short past ``FIELD_VALUE_MAX_LENGTH``, or past the generous length ``FIEL
own, a handled exception's text and a template finding's. A value is cut at its end, except a path's, or a list of
paths', which is cut at its start so the last file's name stays: a field is taken for a path by its name, one ending
in ``LEFT_CUT_FIELD_SUFFIXES`` (``file.path``, ``root_path``, ``override_paths``, ``library_dirs``, ``template_file``)
-or one of ``LEFT_CUT_FIELDS`` (``file.name``). The text is cut before it is quoted and escaped, a string's own or a
+or one listed whole in ``LEFT_CUT_FIELDS``. The text is cut before it is quoted and escaped, a string's own or a
JSON rendering alike, 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 has already