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.

Subject grants: every positional subject is an explicit, recorded, reviewed exception (#1040)

Louis Choqueld3550330a426
diff --git a/.claude/skills/drift-review/SKILL.md b/.claude/skills/drift-review/SKILL.md
new file mode 100644
index 000000000..0e5e038d7
--- /dev/null
+++ b/.claude/skills/drift-review/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: drift-review
+description: >
+ Resolve open drift contracts — the review obligations between code and docs
+ declared in drift.toml. Use whenever `make drift-check` (or the `make check`
+ aggregate, or the CI lint-drift job) fails with open contracts, when the user
+ says "drift check failed", "resolve the drift contract", "ack the drift",
+ "run drift plan", or after any change that touches drift trigger files (the
+ config model / pipelex.toml, CLI code, the keyword-only guard). Also use when
+ recording a drift dogfood observation. Performs the review for real, records
+ an honest ack, and logs the dogfood observation the pilot phase depends on.
+---
+
+# Drift Review
+
+Resolve open drift contracts: review the declared targets against what actually changed, fix staleness, record the ack, log a dogfood observation. Full system reference: `docs/contribute/drift-contracts.md`. The manifest is `drift.toml` at the repo root.
+
+A contract is "open" when tracked files matching its triggers changed (in the git index) since the last recorded review — or the contract definition itself changed, or it never had an ack. The tool proves *that* a review happened; this skill's job is to make the review *genuine*. There is deliberately no bypass anywhere in the system — the legitimate escape is an honest "nothing to update" rationale, which is cheap and auditable.
+
+## Workflow
+
+### 1. See what's open
+
+```bash
+make drift-plan # all open contracts
+make drift-plan CONTRACT=<id> # one contract's full packet
+```
+
+Each packet gives you: the description, exactly which trigger files were added/removed/modified since the last ack, the review targets, the verify commands, the previous ack's rationale, and the exact ack command to run.
+
+### 2. Review — this is the point, not a formality
+
+Work from the trigger diff to the review targets:
+
+- For each added/modified/removed trigger file, identify what a reader of the review targets could observe changing: new, renamed, or removed options, settings, defaults, commands, behaviors. Use `git diff` on the trigger files; the previous ack's rationale tells you what the last review already covered, so focus on what changed since.
+- Grep the review targets for the changed names, settings, and symbols — then read the surrounding prose. A mention can be present but stale (wrong default, wrong behavior, incomplete), not just missing.
+- Fix what's stale, following the repo's doc rules: docs describe current reality, no hardcoded counts, MkDocs conventions (blank line before lists).
+- "Nothing to update" is a legitimate verdict — but only after you actually opened and read the review targets. If you didn't open them, you haven't reviewed.
+
+### 3. Stage, then ack
+
+The digest is computed from the **git index**, not the working tree: `git add` the trigger files (and any doc fixes you made). Staging is enough — no commit needed first, and unrelated unstaged changes elsewhere are fine. Take `drift ack`'s warnings about untracked or unstaged-modified matched files seriously: an unstaged edit is invisible to the ack.
+
+```bash
+make drift-ack CONTRACT=<id> RATIONALE="<honest sentence>" BY="<your identity>"
+```
+
+As an agent, always pass `BY` with your **own actual identity** — the model you are actually running as, in the form `BY="Claude (<your model name>)"`. Do not copy a model name from an example or from a previous ack; the reviewer field is audit data and must name who really did the review. Never ack under the human's `git config user.name`. The contract's verify commands run first (no shell, fail-fast); a failure aborts the ack. Fix what the verifier caught — do not look for a bypass; none exists, by design.
+
+**The rationale is the on-the-record review decision.** It must say what was reviewed and what the verdict was:
+
+- Bad: `"docs fine"`, `"reviewed"`, `"re-ack after refactor"`
+- Good: `"Documented the new activity_queues setting in general-config.md; other config pages unaffected."`
+- Good: `"CLI change is internal plumbing (renamed a private helper); no user-visible surface moved; cli docs and agent-CLI contract doc verified unchanged."`
+
+### 4. Verify and commit
+
+`make drift-check` must pass. Commit the ack file(s) under `.drift/acks/` **together with the change they cover** — the rationale lands in the PR diff next to the change, which is the audit trail. Never hand-edit files under `.drift/acks/`.
+
+## Mandatory: log the dogfood observation
+
+The drift system is in its pilot phase, and the one question only usage can answer is: **is the ack friction proportionate to the staleness caught?** Every ack must therefore produce one evidence entry — the per-contract keep/narrow/mechanize/drop verdict will be decided from this log.
+
+Append to `wip/drift-contracts/dogfood-log.md` (create it with this header if missing):
+
+```markdown
+# Drift-contracts dogfood log
+
+One entry per ack. Verdicts: **real-catch** (the review found actual staleness), **clean-pass** (genuinely reviewed, nothing was stale), **friction** (the contract opened on changes that could not have affected the targets — candidate for narrowing or mechanizing).
+
+- **YYYY-MM-DD · <contract-id> · <verdict>** — one sentence: what triggered the contract, what the review found.
+```
+
+A `clean-pass` is a fine outcome; a *pattern* of clean-passes on the same contract is signal. When you record `friction`, also say which trigger narrowing would have prevented the false opening.
+
+## Failure modes
+
+- **`drift check` fails on manifest rot** (dead trigger glob, zero-match review target, orphan ack, id/filename mismatch): the manifest itself needs fixing — edit `drift.toml` first (typically a rename left a glob dead), then re-review and re-ack. Editing a contract reopens it; that is expected.
+- **A verify command fails:** it caught something real — fix it; the ack stays blocked until the verifier passes.
+- **A contract keeps reopening on edits that cannot affect its targets:** keep recording `friction` entries and propose a trigger narrowing to the user. During the pilot, do not grow the manifest (no new contracts) without the user's explicit say-so — growth follows pain, not tooling enthusiasm.
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
new file mode 100644
index 000000000..1a1609022
--- /dev/null
+++ b/.drift/acks/cli-docs.toml
@@ -0,0 +1,132 @@
+contract = "cli-docs"
+digest = "sha256:e7bb78cd62dab12872fe04e1a52cc790f03cd5f34ed277c377ceb2837938640b"
+reviewed_by = "Louis Choquel"
+reviewed_at = "2026-07-11T15:45:13Z"
+rationale = "Trigger changes are the subject-grant regrind's internal signature demotes plus the pipelex-dev --seed removal; docs/tools/cli/ and agent_cli/CLAUDE.md document neither pipelex-dev nor any changed command flag or output contract — reviewed, no doc change needed."
+
+[trigger_files]
+"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
+"pipelex/cli/_cli.py" = "blob:dec199a605168d168b512805f03a81cbe75d8bc9"
+"pipelex/cli/agent_cli/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/agent_cli/_agent_cli.py" = "blob:bbbb33d750a93df1a5afd72b43e0a381d5081279"
+"pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py" = "blob:a1fc438119dd10607252c08390ebd6384d999678"
+"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:8ea8729c402874fa760c46670da5ebd6967648b5"
+"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:8868104d882e160a5b5a95d3f6c7642499488786"
+"pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:30339c5d91048f4e67312d5691ed9a65d57472e0"
+"pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:2e3bb5be7e0fd72c43bf43e1faa3eb9d5c8353b2"
+"pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/agent_cli/commands/codegen/app.py" = "blob:0f3daa4a3962273c4b347a619dd99bef72f735be"
+"pipelex/cli/agent_cli/commands/codegen/check_cmd.py" = "blob:bacfda014d158c9a4e9de5f8ca03ba9628b6b102"
+"pipelex/cli/agent_cli/commands/codegen/types_cmd.py" = "blob:256d428cff7738af33ce69281f8e81b538ba7996"
+"pipelex/cli/agent_cli/commands/concept_cmd.py" = "blob:518d291b5e74a7f5ffb2da1606aae42ca2c57835"
+"pipelex/cli/agent_cli/commands/doctor_cmd.py" = "blob:d1ee397d4c62e8768a0ab8a7011468d60581fc12"
+"pipelex/cli/agent_cli/commands/fix/__init__.py" = "blob:65662c86f17f610ad55ecfc3e27a022b9aa26e8b"
+"pipelex/cli/agent_cli/commands/fix/app.py" = "blob:e6190d9bde6a05755c04bd21806f699461038ac0"
+"pipelex/cli/agent_cli/commands/fix/bundle_cmd.py" = "blob:aa2328eb97365a37ce3c2fd885847402508c7476"
+"pipelex/cli/agent_cli/commands/fmt_cmd.py" = "blob:97d6fb6c328e0b718b1293bd6b73cba03edcb7dc"
+"pipelex/cli/agent_cli/commands/init_cmd.py" = "blob:3ed36d13bddebbadb90272b689a15e9ebdbcabf7"
+"pipelex/cli/agent_cli/commands/inputs/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/agent_cli/commands/inputs/_inputs_core.py" = "blob:459e29b581f873a92195723d7f4e9293497b398c"
+"pipelex/cli/agent_cli/commands/inputs/app.py" = "blob:7e19284687b334c684fb03381a8d9d20af1aa152"
+"pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py" = "blob:c6ad6a69bf161573617fb1c2eaa1367d6d63239d"
+"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:516cf6fc7030d59792cef4b6e3a30448e21f6cff"
+"pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:08cf0c6d2a0c2aa41a3c61b0b97b02989c79395f"
+"pipelex/cli/agent_cli/commands/lint_cmd.py" = "blob:91ad9cb4d618ba4c0b7da366cde2f74f38d350df"
+"pipelex/cli/agent_cli/commands/models_cmd.py" = "blob:90d30128fe924677ee84f926fc733b2016333297"
+"pipelex/cli/agent_cli/commands/pipe_cmd.py" = "blob:0be9fb13dbec21da0958ed66b45748291b4e5e2d"
+"pipelex/cli/agent_cli/commands/plxt_passthrough.py" = "blob:22a4666dbd179a68b86cb340cdb9dbe207c8c1e1"
+"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:0e211c802005719777dd08a439e83521dead57c4"
+"pipelex/cli/agent_cli/commands/run/_run_core_api.py" = "blob:78a27e0ba91e6bbf99c11caedb29ad4cf20ac78b"
+"pipelex/cli/agent_cli/commands/run/app.py" = "blob:64b2ecc02007cda11b526d8d3fc139593875dd9d"
+"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:a8c2685cc21f195d51a768e44430f358ecc67b99"
+"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:0cdc4b29197d84ff8a006bede7515cb1b1723a03"
+"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:31ce470e603a5b28207d176a5ae2820216b199e0"
+"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:4bc7f4e91ddb3900a75356f8f8e6ba5a586a3690"
+"pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:94c86636f1b8494263e1dd49dc6168834996e39e"
+"pipelex/cli/agent_cli/commands/validate/app.py" = "blob:d2d0ed19288c2d1c25be1650dd962189fcdb3b86"
+"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:31b5210e5495b8687ea7029c2d3660d25167eea7"
+"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:24ddeef224fa2d88781141467ef80c414d34f77a"
+"pipelex/cli/agent_cli/commands/validate/pipe_cmd.py" = "blob:ab9f230a54c865edf5b38ac1d572eee0f8aac0d3"
+"pipelex/cli/bundle_target_resolution.py" = "blob:32ee80e4bf0ebaf1a81dc9ad4a08e4efe1baf9ff"
+"pipelex/cli/cli_factory.py" = "blob:1f859ab3b995e1a67e5fdc812a168d56c338e970"
+"pipelex/cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/build/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/build/app.py" = "blob:fabe555870e61d147d0bf01e49de6e5cc9719d34"
+"pipelex/cli/commands/build/inputs/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/build/inputs/_inputs_core.py" = "blob:60aa8704f384feb4314a32ff390027479a7f03d8"
+"pipelex/cli/commands/build/inputs/app.py" = "blob:2a7770c8294b8c2c1b4420ac00d6ffdfa50609bf"
+"pipelex/cli/commands/build/inputs/bundle_cmd.py" = "blob:9ab5ff3eaaefb8cc0102ee4dfd6001f67fbd4863"
+"pipelex/cli/commands/build/inputs/method_cmd.py" = "blob:5a7d0a53f926cb5648fbbc1beb8bce20b86bc200"
+"pipelex/cli/commands/build/inputs/pipe_cmd.py" = "blob:4ac82731c730940b7fe4f80002610beb16488d65"
+"pipelex/cli/commands/build/output/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/build/output/_output_core.py" = "blob:12e0966394f28a70645d63e024dd76678f220bc2"
+"pipelex/cli/commands/build/output/app.py" = "blob:67996650b99551fbd58be30e692688204d16935a"
+"pipelex/cli/commands/build/output/bundle_cmd.py" = "blob:a4a04ce555e0bbf2178206269fe769c13a0bd0f7"
+"pipelex/cli/commands/build/output/method_cmd.py" = "blob:f43bd91fd9007358f725dc489212bec35a1e223d"
+"pipelex/cli/commands/build/output/pipe_cmd.py" = "blob:eb0db8279c93fcff9d5fe4546f593d753282acb5"
+"pipelex/cli/commands/build/runner/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/build/runner/_runner_core.py" = "blob:dd0ce14f5286bacfb6468875186449a01c93f2d7"
+"pipelex/cli/commands/build/runner/app.py" = "blob:b5aa321ed93dc2cb9b138e4a26bae9eb75c732b7"
+"pipelex/cli/commands/build/runner/bundle_cmd.py" = "blob:d18b32232d45010150cce2779242057adb8dc51a"
+"pipelex/cli/commands/build/runner/method_cmd.py" = "blob:0f497ffcae50d89483d8cf953c6dc03599bc2a5f"
+"pipelex/cli/commands/build/structures_cmd.py" = "blob:3c0cf372e381e8141fa49f18e261c5047df13e7c"
+"pipelex/cli/commands/bundle_path_resolver.py" = "blob:60c6a2994c9b7c6e0ec212702467d668eecb6d50"
+"pipelex/cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/codegen/app.py" = "blob:9158084a89da23654e122e9df3a0a9c726401642"
+"pipelex/cli/commands/codegen/check_cmd.py" = "blob:d73d0c73e82fa50e072058caf0ca92e52fe17b0f"
+"pipelex/cli/commands/codegen/inputs_cmd.py" = "blob:02049944149cac3d2b2f59b14be0d74271a20010"
+"pipelex/cli/commands/codegen/types_cmd.py" = "blob:944541cdf040bf63ee3ebbd6c74d15dc523dbee2"
+"pipelex/cli/commands/crate_loading.py" = "blob:1b62ace3a8c439ae6a84612b503dced2e89c01b6"
+"pipelex/cli/commands/doctor_cmd.py" = "blob:0823f00388f32e9f32ae0e709a4412784cd14dd4"
+"pipelex/cli/commands/fix/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:c9a899c68653bab4082fbe81a5f8af571919d87a"
+"pipelex/cli/commands/fix/_fix_core.py" = "blob:5bd7ba061fe2c00932279db7af2b419c6f5e06f2"
+"pipelex/cli/commands/fix/app.py" = "blob:6f019930e8e3e0043ee46d87493ba4602eb33a76"
+"pipelex/cli/commands/fix/bundle_cmd.py" = "blob:427364cc453957dfe0cec879f019050329c13b3c"
+"pipelex/cli/commands/graph_cmd.py" = "blob:4363d3b9320e352244883f5fa1fe94dffc6faee8"
+"pipelex/cli/commands/init/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/init/backends.py" = "blob:69ceaa1edef130a38214423956b839741e243614"
+"pipelex/cli/commands/init/command.py" = "blob:80ad0831db0688a02aeac916ea6b87ccae4a093b"
+"pipelex/cli/commands/init/config_files.py" = "blob:6e926eb3beb3c12a38d25f34c10e7b5ab6a7a99a"
+"pipelex/cli/commands/init/credentials.py" = "blob:7475c3082b8ee7530a76a52a8ab8bf18a7e21209"
+"pipelex/cli/commands/init/ide_extension.py" = "blob:b1ff7341253a56a8cbccfccce7b14d9053cd5b16"
+"pipelex/cli/commands/init/routing.py" = "blob:224e4e46c519edb7d64060d32395c4332099560f"
+"pipelex/cli/commands/init/telemetry.py" = "blob:da0c79bdf04b97f0655c42bc9cea98e9e40ea256"
+"pipelex/cli/commands/init/ui/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/init/ui/backends_ui.py" = "blob:16006c2efa81640ef196986a527b629b4d91fbda"
+"pipelex/cli/commands/init/ui/gateway_ui.py" = "blob:d4752deb5679d53cc21a9a4a307f2d9305e20291"
+"pipelex/cli/commands/init/ui/general_ui.py" = "blob:6fdc9cb429a5da261013679aae19afa10344770e"
+"pipelex/cli/commands/init/ui/routing_ui.py" = "blob:640bd0d11d1879ead83fd9f3d1736d2735c1abfa"
+"pipelex/cli/commands/init/ui/types.py" = "blob:1361f29ca95bacc90bca90ea6c0e39f44b6734ab"
+"pipelex/cli/commands/login/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/login/command.py" = "blob:6ae5c3db3d6da208be955ff9ab66022ee162a2b8"
+"pipelex/cli/commands/plugins_cmd.py" = "blob:2987904797831cdff476d1034d513320051cbb5a"
+"pipelex/cli/commands/resolve_cmd.py" = "blob:7b3f61ee79619a90e8428d9bc376d3b43c2816dc"
+"pipelex/cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:dde781f846968b667a0acfb4b3e3cea01cef7049"
+"pipelex/cli/commands/run/_inputs_path_resolver.py" = "blob:c8ec89d98718e18af7aaaded44c9f545be60adab"
+"pipelex/cli/commands/run/_run_core.py" = "blob:2862ba63bc6571b60cf9b37a0d1132c95400d344"
+"pipelex/cli/commands/run/app.py" = "blob:a7090b0ff6bf2f1d47827fa27d2a138096a2e148"
+"pipelex/cli/commands/run/bundle_cmd.py" = "blob:2c0233ff88988038cc6f4189499ef1744a9579c3"
+"pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472"
+"pipelex/cli/commands/run/method_cmd.py" = "blob:828bd9b9c72a0e1132e54241817e388c97d9adad"
+"pipelex/cli/commands/run/pipe_cmd.py" = "blob:88878cb413b406612d16140ec1b1b9bed8c90d94"
+"pipelex/cli/commands/show_cmd.py" = "blob:5687ac523a7e22168b5db5bc622f70cf284fb031"
+"pipelex/cli/commands/update_cmd.py" = "blob:ca40a94d5756ee9bfb89251b931026bb39b9901e"
+"pipelex/cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+"pipelex/cli/commands/validate/_validate_core.py" = "blob:4613d20bc67d8b1b917cc70b50834b8f912338d9"
+"pipelex/cli/commands/validate/app.py" = "blob:309061423af13f2f6c496a024306ad696af567ab"
+"pipelex/cli/commands/validate/bundle_cmd.py" = "blob:1fbf3e0cf695db39101c83160a724df6468988e9"
+"pipelex/cli/commands/validate/method_cmd.py" = "blob:2cb68d5c371a5b45841fce9c26da5e4622e6b042"
+"pipelex/cli/commands/validate/pipe_cmd.py" = "blob:5720f3a3f4f3c555e772a2dbb335c3139ae4457e"
+"pipelex/cli/commands/which_cmd.py" = "blob:539c708523b4adf723ef58c79d9de66c365231d4"
+"pipelex/cli/deck_notice.py" = "blob:ff0caeb50971f1b9828b2b4336ebc40312fe1b5f"
+"pipelex/cli/error_handlers.py" = "blob:9b69c4de9d95999b666ce47e52eaa95c3efb481f"
+"pipelex/cli/exceptions.py" = "blob:1d51c3a53ddd3f6cf8de566fa2ade3fa75ab7a3a"
+"pipelex/cli/installed_methods.py" = "blob:2a1adeda25082bd2bef44887b9af60c29dab8d7b"
+"pipelex/cli/method_resolver.py" = "blob:850ad43ee2c6fb0ffc3f449f62ceea1ab6f17297"
+"pipelex/cli/readiness.py" = "blob:16393528f294750878d2381d151ddc3da36e6bb2"
diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.toml
new file mode 100644
index 000000000..0181d769a
--- /dev/null
+++ b/.drift/acks/config-docs.toml
@@ -0,0 +1,19 @@
+contract = "config-docs"
+digest = "sha256:452d8805882407ae15c3f0f977b6a1ef4dd61b1282d354a8c14bb2fa9387e7f0"
+reviewed_by = "Louis Choquel"
+reviewed_at = "2026-07-11T15:46:20Z"
+rationale = "The trigger change is dev's Python-3.10 drop (StrEnum import swap in img_gen_job_components.py), merged in via the Phase-M dev merge — no config field, default, or documented behavior changed; reviewed, no doc change needed."
+
+[trigger_files]
+"pipelex/cogt/config_cogt.py" = "blob:fca7b96f9147122b6b8300471cac637b05fed1ee"
+"pipelex/cogt/img_gen/img_gen_job_components.py" = "blob:084985080413fd8d6c3b1b9b0747020cb0161858"
+"pipelex/pipelex.toml" = "blob:8952bf3f4367ce4c761fa24aeda35e5aba0ea24a"
+"pipelex/system/configuration/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
+"pipelex/system/configuration/config_check.py" = "blob:12cf96754989b59ffced39521e3fe11606058d8f"
+"pipelex/system/configuration/config_loader.py" = "blob:af3ba71ed4e589cec42cb197d7d11539cea50ecd"
+"pipelex/system/configuration/config_model.py" = "blob:83b29dc6e93393c9b98c4353636caf0135c80339"
+"pipelex/system/configuration/config_root.py" = "blob:c7d43851270912d17413cfc6a511247d3c7cc160"
+"pipelex/system/configuration/configs.py" = "blob:8f0fc7f74b3762f2d517da49bf8f0ee8ad0b941d"
+"pipelex/system/telemetry/telemetry_config.py" = "blob:b6912e8be8932b65213dab23ac66372b8b45ca58"
+"pipelex/tools/aws/aws_config.py" = "blob:4c0b30c6f500aaf0f4c25395fc361a20d2e7f828"
+"pipelex/tools/log/log_config.py" = "blob:7b6d032ffea29d6ce60e8af7106f2d935bc18348"
diff --git a/.drift/acks/keyword-only-convention.toml b/.drift/acks/keyword-only-convention.toml
new file mode 100644
index 000000000..caa281a5c
--- /dev/null
+++ b/.drift/acks/keyword-only-convention.toml
@@ -0,0 +1,8 @@
+contract = "keyword-only-convention"
+digest = "sha256:2d2a8228601e1fa98d483b5c1d162ddcb8037ac02391d1c0409f8bd48d203571"
+reviewed_by = "Louis Choquel"
+reviewed_at = "2026-07-11T15:45:25Z"
+rationale = "Phase 5 closed the transitional door: --seed and the seeded field are deleted, the registry schema is strict (param + rationale only). Rewrote the doc's transitional-state section as the post-transitional Registry schema section and fixed the --report description."
+
+[trigger_files]
+"pipelex/cli/dev_cli/commands/keyword_only_guard.py" = "blob:c998cfc324c7f1096e974133b75db59c6190c117"
diff --git a/.github/workflows/lint-check.yml b/.github/workflows/lint-check.yml
index fd592d4ef..88ac417c8 100644
--- a/.github/workflows/lint-check.yml
+++ b/.github/workflows/lint-check.yml
@@ -97,7 +97,28 @@ jobs:
run: make check-keyword-only
# --------------------------------------------------------------------------
-# 5. Aggregator job — the *single* required status check
+# 5. Drift contracts — single job, version-independent
+# ADVISORY: deliberately NOT in lint-all's `needs`, so an open contract is
+# visible on the PR but does not block merges. Promote it into lint-all's
+# `needs` once the current open-PR backlog has landed.
+# --------------------------------------------------------------------------
+ lint-drift:
+ name: Lint (drift-contracts)
+ runs-on: [aca-runner-lint]
+ env:
+ VIRTUAL_ENV: ${{ github.workspace }}/.venv
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install dependencies
+ run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+
+ - name: Run drift contracts check
+ run: make drift-check
+
+# --------------------------------------------------------------------------
+# 6. Aggregator job — the *single* required status check
# --------------------------------------------------------------------------
lint-all:
name: Lint (all)
diff --git a/AGENTS.md b/AGENTS.md
index d26d32a76..2e857a7a7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -224,14 +224,18 @@ Once you've landed on a `BaseModel` (the default for anything that serializes),
### Keyword-only arguments
-Across `pipelex/` source, non-subject function parameters must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shape places a bare `*` after the subject:
+Across `pipelex/` source, non-subject function parameters must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shapes:
-- `def f(subject, *, opt1, opt2): ...` — the first non-`self`/`cls` parameter (the subject) may stay positional; everything after it must be keyword-only. Making the subject keyword-only too (`def f(*, a, b)`, `def m(self, *, a, b)`) is always allowed and is the form the auto-fixer produces.
-- A lone subject (`def render(node)`) is compliant; a second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is a violation.
+- `def f(*, opt1, opt2): ...` — fully keyword-only. Always compliant, needs nothing.
+- `def f(subject, *, opt1, opt2): ...` — a positional subject is legal ONLY under a **subject grant** recorded in `subject_grants.toml` at the repo root. A lone subject (`def render(node)`) needs a grant too. No grant → violation.
+- A second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is always a violation, grant or not.
+- A subject annotated `bool`/`int`/`float` (including `Optional[X]` / `X | None` forms) is **banned outright** — grants are impossible; call sites like `f(True)` are never acceptable. `str` subjects stay grantable.
-The rule is mechanically enforced by the `check-keyword-only` AST guard (`make cko`), which runs in `make agent-check`, in the `make check` aggregate, in CI, and via a Claude Code `PostToolUse` hook that checks each edited file at edit time. The tree is fully compliant, so it hard-blocks on **any** violation. Carve-outs — dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, `@override` impls, and a small curated symmetric-tuple allowlist — are skipped automatically. A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line).
+To keep a subject positional, record a grant with an honest, def-specific rationale: `make subject-grant FUNC="<relative_path>::<qualified_name>" RATIONALE="…"` (alias `make sgr`). The command validates the def, records the param automatically, and rewrites the registry sorted. A grant is warranted when the call reads as a verb–object sentence with a single obvious operand (`render(node)`, `validate_bundle(bundle)`) and call sites pass self-labelling expressions — when in doubt, go keyword-only instead. Grants are checked symmetrically: a grant whose def was renamed, moved, demoted, or deleted hard-fails the check until the registry is cleaned up (delete the entry or re-grant).
-**Auto-fix.** `make fix-keyword-only` (alias `fko`, or `pipelex-dev check-keyword-only --fix`) rewrites every mechanically-fixable violation by inserting a bare `*` as far left as possible — right after `self`/`cls` — so every non-`self`/`cls` parameter becomes keyword-only, and re-parses each rewrite before writing (a rewrite that would not parse is discarded and reported instead). It runs automatically early in `make agent-check`, before `ruff format`. It is **non-gating**: it mutates and reports but never exits non-zero — the read-only `check-keyword-only` (run last in `agent-check`, and the variant `make check` / CI use) owns the pass/fail gate. A few shapes a single `*` insert cannot fix are reported for a manual fix instead of rewritten: a `*args` is present, a keyword-only section already exists, or two-or-more positional-only params remain.
+The rule is mechanically enforced by the `check-keyword-only` AST guard (`make cko`), which runs in `make agent-check`, in the `make check` aggregate, in CI, and via a Claude Code `PostToolUse` hook that checks each edited file at edit time. The tree is fully compliant, so it hard-blocks on **any** violation, and each violation kind names its remedy in the output. Carve-outs — dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, `@override` impls, and a small curated symmetric-tuple allowlist — are skipped automatically (they neither need nor hold grants). A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line).
+
+**Auto-fix.** `make fix-keyword-only` (alias `fko`, or `pipelex-dev check-keyword-only --fix`) rewrites every mechanically-fixable violation by inserting a bare `*` as far left as possible — right after `self`/`cls` — so every non-`self`/`cls` parameter becomes keyword-only, and re-parses each rewrite before writing (a rewrite that would not parse is discarded and reported instead). Ungranted-subject and literal-subject defs are fixable this way too; a grant-param mismatch is never rewritten (that is a registry decision). It runs automatically early in `make agent-check`, before `ruff format`. It is **non-gating**: it mutates and reports but never exits non-zero — the read-only `check-keyword-only` (run last in `agent-check`, and the variant `make check` / CI use) owns the pass/fail gate. ⚠ Because an ungranted subject is a violation, `make agent-check` will silently keyword-only it — record the grant BEFORE running checks if the subject should stay positional. Shapes a single `*` insert cannot fix are reported for a manual fix: a `*args` is present, a keyword-only section already exists (move the `*` by hand — the common `def f(subject, *, opt)` case when the subject is ungranted or literal-typed), or two-or-more positional-only params remain.
Auto-fix is not a substitute for review: the guard is blind to functions a framework or the interpreter invokes positionally (callbacks, `__import__` hooks, route handlers, Jinja2 filters) — pyright/mypy will pass a wrongly-keywordized callback, so `make agent-test` is the safety net after a bulk fix.
@@ -333,14 +337,16 @@ When adding validation or fields, decide which layer they belong to. Language ru
### Keyword-only arguments
-Non-subject function parameters across `pipelex/` source must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shape places a bare `*` after the subject:
+Non-subject function parameters across `pipelex/` source must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shapes:
-- `def f(subject, *, opt1, opt2): ...` — the first non-`self`/`cls` parameter (the subject) may stay positional; everything after it must be keyword-only. Making the subject keyword-only too (`def f(*, a, b)`) is always allowed and often preferable.
-- A lone subject (`def render(node)`) is compliant; a second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is a violation.
+- `def f(*, opt1, opt2): ...` — fully keyword-only. Always compliant, needs nothing.
+- `def f(subject, *, opt1, opt2): ...` — a positional subject (including a lone one, `def render(node)`) is legal ONLY under a **subject grant** recorded in `subject_grants.toml` at the repo root: `make subject-grant FUNC="<path>::<qualname>" RATIONALE="…"` (alias `sgr`). Grant when the call reads as a verb–object sentence with a single obvious operand; when in doubt, go keyword-only.
+- A second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is always a violation, grant or not.
+- A `bool`/`int`/`float` subject (incl. `Optional`/union-with-`None` forms) is banned outright — grants are impossible; `f(True)` call sites are never acceptable.
-The rule is mechanically enforced by the `check-keyword-only` AST guard, which runs in `make agent-check`, in the `make check` aggregate, and in CI; the tree is fully compliant, so it hard-blocks on **any** violation. Carve-outs (dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, `@override` impls) are skipped automatically. A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line). Watch for functions a framework or the interpreter invokes positionally (callbacks, `__import__` hooks, route handlers): the type checker is blind to those, so `make agent-test` is the safety net.
+The rule is mechanically enforced by the `check-keyword-only` AST guard, which runs in `make agent-check`, in the `make check` aggregate, and in CI; the tree is fully compliant, so it hard-blocks on **any** violation, and staleness is symmetric (a grant whose def was renamed, moved, demoted, or deleted fails the check until the registry is cleaned up). Carve-outs (dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, `@override` impls) are skipped automatically. A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line). Watch for functions a framework or the interpreter invokes positionally (callbacks, `__import__` hooks, route handlers): the type checker is blind to those, so `make agent-test` is the safety net. ⚠ `make agent-check` runs the auto-fixer, which will silently keyword-only an ungranted subject — record the grant BEFORE running checks if the subject should stay positional.
-The full specification — the two exceptions, the carve-out list, the symmetric-tuple allowlist, the escape hatch, and worked examples — is in [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md).
+The full specification — the grant registry and rubric, the symmetric-tuple allowlist, the carve-out list, the escape hatch, and worked examples — is in [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md).
## Writing Tests
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 178e1c006..b35eafb07 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,8 +23,11 @@
- **Host-facing resolve/codegen engine cores (what the HTTP routes ride):** `pipelex.pipeline.resolve_bundle.resolve_crate_from_contents` resolves **in-memory** MTHDS contents into the normalized crate — same engine, same `ValidateBundleError` verdict vocabulary, and the same loaded-on-success library contract as `validate_bundle` — so a host (the `pipelex-api` `/v1/resolve` + `/v1/codegen` routes) serves resolution without touching the filesystem. `pipelex.codegen.emission.build_stamped_projection` is the new **pure** stamping core (stamped files + `codegen.lock` content, no disk writes) that `write_stamped_projection` now rides, so artifacts served over HTTP are byte-identical to locally written ones and pass the offline `codegen check` verbatim. The shared bundle-loading error cascade `translate_to_validate_bundle_error` is now public (renamed from its underscore-private form) since it gained a third entry point.
- **Comprehensive input error handling:** A suite of typed errors for input shaping failures (`WrongScalarKindError`, `ListWhereSingularError`, `MultiplicityCountMismatchError`, `StructureValidationError`, `UnknownInputNameError`) that provide clear hints and render the expected JSON shape.
- **CLI `--explicit` flag:** Added `--explicit` to `pipelex build inputs` and `pipelex-agent inputs` to generate the legacy `{"concept", "content"}` envelope templates.
+- **Subject-grants registry — the keyword-only convention hardened:** a positional first parameter ("subject") in `pipelex/` source is now legal only under an explicit grant recorded in `subject_grants.toml` at the repo root, carrying the subject's param name and an honest, def-specific review rationale — every grant in the registry has been individually reviewed against the grant rubric. `pipelex-dev subject-grant` is the sole registry writer; the `check-keyword-only` AST guard enforces the registry symmetrically (an ungranted subject fails, and so does a stale grant whose def was renamed, moved, demoted, or newly carved out) in `make check`, CI, and the edit-time hook. Subjects typed `bool`/`int`/`float` are banned outright — no grant can cover them. The registry schema is strict: exactly `param` + `rationale`, unknown keys fail the check. See `docs/contribute/keyword-only-arguments.md`.
+- **Drift contracts (`pipelex-dev drift plan|check|ack`):** Deterministic review obligations between code and docs. A root `drift.toml` declares contracts ("when these trigger files change, these review targets must be re-examined and the examination recorded"); committed ack files under `.drift/acks/` record each fulfilled review with a digest, reviewer, and rationale. A contract is fulfilled iff its stored ack digest equals the digest recomputed from the current tree (staged blob OIDs from the git index — no base ref, no timestamps), so trigger edits, matched-file adds/deletes, and contract-definition edits all reopen it. `make drift-check` gates the `make check` aggregate and runs as an advisory CI job; `make drift-plan` prints per-contract Markdown packets with exact per-file changes since the last ack; `make drift-ack CONTRACT=… RATIONALE="…"` runs the contract's verify commands then records the review. Seeded with contracts for the config docs, the CLI docs, and the keyword-only convention spec; workflow documented in `docs/contribute/drift-contracts.md`.
### Changed
+- (Breaking) **Keyword-only demotions across the public API:** the subject-grant review demoted every positional first parameter that failed the grant rubric to keyword-only, and external code calling these surfaces positionally (or subclassing them with positional signatures) breaks. Notable demoted families: the `PipeAbstract` run family (`run_pipe`, `dry_run_pipe`, `validate_before_run`, … — `job_metadata`/`visited_pipes` now keyword-only), `StuffContent.rendered_for_prompt`/`rendered_for_template_async` (`text_format`) and the `TextFormatRenderable`/`ImageRenderable` protocols with all their implementations, the `LibraryManagerAbstract` load family (`library_id`), `ensure_pipelex_booted` (`config_overrides`), `pipeline_run_setup` (`execution_config`), `ConceptLibrary.is_compatible` (`tested_concept`), `GraphTracerProtocol.setup` (`graph_id`), the `PromptImageFactory`/`PromptDocumentFactory` content factories (`uri`), the model-manager/backend-library setup+load (`secrets_provider`), the reporting protocol's `set_event_log`/`clear_event_log` (`context_key`), and assorted tools helpers (`pluralize`/`count_with_noun`, `LogLevel.from_int`, `set_dry_run_forced`, …).
- (Breaking) **`pipelex build structures` is now an alias of `codegen types --target python-structures`:** the legacy always-qualified per-file generator is deleted. The alias resolves the target's whole directory closure and emits one stamped `structures.py` module plus a `codegen.lock` (bare-when-unique class names, declared imprecision instead of the old silent `TextContent` guess for structureless concepts). The `--force` flag is gone (emission is write-if-changed), a `.mthds` file target now resolves its parent directory's closure, and concepts-only loading of invalid-pipe bundles is no longer supported (the crate requires a valid library). The concepts-only loading API (`load_concepts_only`, `load_concepts_only_from_directory`, and the library-manager methods behind them) is removed with it.
- (Breaking) **`pipelex build runner` emits its structures through the codegen engine:** the scaffolded `structures/` directory now contains the stamped single-module projection (`structures.py` + `codegen.lock`) instead of per-concept files, and the generated runner script imports and instantiates the emitted class spellings (`from structures.structures import Invoice`) — fixing dropped imports for nested custom concepts along the way. A user class backing a `structure = "<ClassName>"` concept is imported from its real module.
- **Human validation error rendering routed through the shared structured items:** `pipelex validate`'s error details now render from the same `ValidationErrorItem`s the agent CLI and API emit, which surfaces information the old renderer silently dropped: pipe-factory errors (e.g. an unknown concept) get their own section, a parse-level failure (e.g. a TOML syntax error) now shows its message instead of no detail at all, and pipe validation errors name their source file. The dry-run message remains visible alongside categorized errors.
diff --git a/CLAUDE.md b/CLAUDE.md
index 16d481bfd..1fe1572f6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,14 +22,15 @@
### Keyword-only arguments check
- Non-subject function parameters across `pipelex/` source must be keyword-only (a bare `*` after the subject). The convention is mechanically enforced and already runs as part of `make agent-check`, but you can invoke it on its own:
+ Non-subject function parameters across `pipelex/` source must be keyword-only, and a positional subject is legal only under a grant recorded in `subject_grants.toml`. The convention is mechanically enforced and already runs as part of `make agent-check`, but you can invoke it on its own:
```bash
make check-keyword-only # alias: make cko — read-only gate; hard-blocks on any violation
make fix-keyword-only # alias: make fko — auto-insert a bare * for mechanically-fixable violations
+ make subject-grant FUNC="<path>::<qualname>" RATIONALE="…" # alias: make sgr — grant a positional subject
```
- `check-keyword-only` owns the pass/fail gate; `fix-keyword-only` rewrites what it can and reports the shapes it can't fix mechanically (resolve those by hand). See [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md) for the full convention.
+ `check-keyword-only` owns the pass/fail gate; `fix-keyword-only` rewrites what it can (including ungranted subjects — grant BEFORE running checks if the subject should stay positional) and reports the shapes it can't fix mechanically (resolve those by hand). See [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md) for the full convention.
### Cleaning Derived Files
@@ -136,6 +137,13 @@
.venv/bin/pipelex-dev refresh-graph-ui-sri --mthds-ui-version 0.6.3 --elkjs-version 0.11.1
```
+ - **`drift`**: Drift contracts — deterministic review obligations between code and docs, declared in the root `drift.toml` (see `docs/contribute/drift-contracts.md`). When `make drift-check` (part of `make check` and CI) reports an open contract: run `make drift-plan` to see what changed and what to review, actually review the targets and fix what is stale, `git add` the trigger files (the digest reads the git index, not the working tree), then record the review with `make drift-ack CONTRACT=<id> RATIONALE="…"`. The rationale is the on-the-record review decision — write an honest sentence. There is no bypass flag; "reviewed, no doc change needed" is a legitimate rationale.
+
+ ```bash
+ make drift-plan
+ make drift-ack CONTRACT=config-docs RATIONALE="Documented the new setting; other config pages unaffected."
+ ```
+
## Standards related to developing the Pipelex codebase
### Spec vs Blueprint Architecture
@@ -157,14 +165,16 @@ When adding validation or fields, decide which layer they belong to. Language ru
### Keyword-only arguments
-Non-subject function parameters across `pipelex/` source must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shape places a bare `*` after the subject:
+Non-subject function parameters across `pipelex/` source must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shapes:
-- `def f(subject, *, opt1, opt2): ...` — the first non-`self`/`cls` parameter (the subject) may stay positional; everything after it must be keyword-only. Making the subject keyword-only too (`def f(*, a, b)`) is always allowed and often preferable.
-- A lone subject (`def render(node)`) is compliant; a second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is a violation.
+- `def f(*, opt1, opt2): ...` — fully keyword-only. Always compliant, needs nothing.
+- `def f(subject, *, opt1, opt2): ...` — a positional subject (including a lone one, `def render(node)`) is legal ONLY under a **subject grant** recorded in `subject_grants.toml` at the repo root: `make subject-grant FUNC="<path>::<qualname>" RATIONALE="…"` (alias `sgr`). Grant when the call reads as a verb–object sentence with a single obvious operand; when in doubt, go keyword-only.
+- A second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is always a violation, grant or not.
+- A `bool`/`int`/`float` subject (incl. `Optional`/union-with-`None` forms) is banned outright — grants are impossible; `f(True)` call sites are never acceptable.
-The rule is mechanically enforced by the `check-keyword-only` AST guard, which runs in `make agent-check`, in the `make check` aggregate, and in CI; the tree is fully compliant, so it hard-blocks on **any** violation. Carve-outs (dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, `@override` impls) are skipped automatically. A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line). Watch for functions a framework or the interpreter invokes positionally (callbacks, `__import__` hooks, route handlers): the type checker is blind to those, so `make agent-test` is the safety net.
+The rule is mechanically enforced by the `check-keyword-only` AST guard, which runs in `make agent-check`, in the `make check` aggregate, and in CI; the tree is fully compliant, so it hard-blocks on **any** violation, and staleness is symmetric (a grant whose def was renamed, moved, demoted, or deleted fails the check until the registry is cleaned up). Carve-outs (dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, `@override` impls) are skipped automatically. A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line). Watch for functions a framework or the interpreter invokes positionally (callbacks, `__import__` hooks, route handlers): the type checker is blind to those, so `make agent-test` is the safety net. ⚠ `make agent-check` runs the auto-fixer, which will silently keyword-only an ungranted subject — record the grant BEFORE running checks if the subject should stay positional.
-The full specification — the two exceptions, the carve-out list, the symmetric-tuple allowlist, the escape hatch, and worked examples — is in [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md).
+The full specification — the grant registry and rubric, the symmetric-tuple allowlist, the carve-out list, the escape hatch, and worked examples — is in [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md).
## Writing Docs
diff --git a/Makefile b/Makefile
index 25f4afe1f..c7a1667a0 100644
--- a/Makefile
+++ b/Makefile
@@ -154,6 +154,8 @@ make fix-unused-imports - Fix unused imports with ruff
make fui - Shorthand -> fix-unused-imports
make fix-keyword-only - Auto-fix keyword-only-args violations (insert a bare *)
make fko - Shorthand -> fix-keyword-only
+make subject-grant - Record a subject grant (FUNC="<path>::<qualname>" RATIONALE="…")
+make sgr - Shorthand -> subject-grant
make check-TODOs - Check for TODOs
make docs - Serve documentation locally with mkdocs
@@ -193,7 +195,8 @@ export HELP
.PHONY: \
all help env env-verbose check-uv check-uv-verbose lock install update build \
format lint ruff-format ruff-lint pyright mypy pylint plxt plxt-format plxt-lint \
- rules rules-claude-standalone up-kit-configs ukc check-config-sync ccs check-keyword-only cko fix-keyword-only fko check-rules check-urls cu insert-skeleton \
+ rules rules-claude-standalone up-kit-configs ukc check-config-sync ccs check-keyword-only cko fix-keyword-only fko subject-grant sgr check-rules check-urls cu insert-skeleton \
+ drift-plan dp drift-check dc drift-ack da \
cleanderived cleanenv cleanall \
test test-xdist t test-quiet tq test-with-prints tp test-inference ti \
test-llm tl test-img-gen tg test-extract te codex-tests gha-tests \
@@ -342,6 +345,41 @@ fix-keyword-only: env
fko: fix-keyword-only
@echo "> done: fko = fix-keyword-only"
+subject-grant: env
+ $(call PRINT_TITLE,"Recording a subject grant")
+ @if [ -z "$(FUNC)" ] || [ -z "$(RATIONALE)" ]; then \
+ echo 'Usage: make subject-grant FUNC="<relative_path>::<qualified_name>" RATIONALE="…"'; \
+ exit 1; \
+ fi
+ $(VENV_PIPELEX_DEV) subject-grant "$(FUNC)" --rationale "$(RATIONALE)"
+
+sgr: subject-grant
+ @echo "> done: sgr = subject-grant"
+
+drift-plan: env
+ $(VENV_PIPELEX_DEV) drift plan $(CONTRACT)
+
+dp: drift-plan
+ @echo "> done: dp = drift-plan"
+
+drift-check: env
+ $(call PRINT_TITLE,"Checking drift contracts — review obligations between code and docs")
+ $(VENV_PIPELEX_DEV) drift check --quiet
+
+dc: drift-check
+ @echo "> done: dc = drift-check"
+
+drift-ack: env
+ $(call PRINT_TITLE,"Recording drift ack")
+ @if [ -z "$(CONTRACT)" ] || [ -z "$(RATIONALE)" ]; then \
+ echo 'Usage: make drift-ack CONTRACT=<contract-id> RATIONALE="…" [BY=<reviewer>]'; \
+ exit 1; \
+ fi
+ $(VENV_PIPELEX_DEV) drift ack "$(CONTRACT)" --rationale "$(RATIONALE)" $(if $(BY),--by "$(BY)")
+
+da: drift-ack
+ @echo "> done: da = drift-ack"
+
generate-mthds-schema: env
$(call PRINT_TITLE,"Generating MTHDS JSON Schema")
$(VENV_PIPELEX_DEV) generate-mthds-schema
@@ -1078,7 +1116,7 @@ cc: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet update
up: generate-mthds-schema-quiet update-gateway-models-quiet up-kit-configs rules
@echo "> done: up = generate-mthds-schema update-gateway-models up-kit-configs rules"
-check: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet update-gateway-models-quiet check-unused-imports check-config-sync check-rules check-urls check-gateway-models check-mthds-schema check-keyword-only format lint pyright mypy pylint
+check: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet update-gateway-models-quiet check-unused-imports check-config-sync check-rules check-urls check-gateway-models check-mthds-schema check-keyword-only drift-check format lint pyright mypy pylint
@echo "> done: check"
agent-check: fix-unused-imports fix-keyword-only format lint pyright mypy check-keyword-only
diff --git a/TODOS.md b/TODOS.md
index fa9cd195a..46d252a54 100644
--- a/TODOS.md
+++ b/TODOS.md
@@ -1,54 +1,241 @@
-# PR recap — DevEx codegen: the normalized library crate and its projections
+# Subject Grants — dropping the generic positional-subject exception
+
+Hardens the keyword-only-arguments convention: Exception 1 (the positional subject) stops being a generic permission and becomes an **explicitly granted, recorded exception**. There is no separate design doc — this file is the authority on the design (decisions, rubric, registry format) and tracks execution state.
+
+## Cold-start context (update at every checkpoint)
+
+- **Status:** **TRACK COMPLETE (2026-07-11). Phase 5 finalization DONE with Louis' greenlight:** `--seed` + `seeded` schema support deleted (registry schema strict: exactly `param` + `rationale`), CHANGELOG `[Unreleased]` carries the convention entry + the breaking demoted-signatures note, convention doc post-transitional, all three open drift contracts reviewed + acked (cli-docs, keyword-only-convention, config-docs), demoted-public-surfaces inventory handed off to `wip/subject-grants/demoted-public-surfaces.md` for the release-wave cross-repo sweep. Registry: 1,742 grants, no seeded field. Phase M history: regrind waves A/B/C + checkpoint review triaged (see the wip record). **PR #1040 → dev OPEN.** The regrind ran as three waves on top of the reseed commit `d58cd847b`: **Wave A `fb1a91197`** — AST classifier compared each seeded def's signature across pre-grind base / archive tip / merged tree; 1,470 archive-KEPT rationales ported verbatim. **Wave B `65a4153ae`** — 148 archive demotes re-applied by splicing the archive's demoted headers byte-for-byte, PLUS the @override/protocol implementers the archive demoted alongside (registry-invisible carve-outs), recovered pyright-guided; call sites re-labelled mechanically; full agent-test green. **Wave C `f83308367`** — genuine review of the dev-delta (285 new + 24 dev-changed): 268 kept, 41 demoted per settled case-law families; GraphTracerProtocol.setup demoted with parity (GraphTracer + GraphTracerNoOp); full agent-test green. Method + judgment calls recorded in `wip/subject-grants/regrind-after-dev-merge.md`. Prior merge context: rewind to pre-grind `9f5bd54a3` + merge `5bb8c2756` (dev tip `048c87971`) + reseed `d58cd847b`; full first grind archived at tag **`subject-grants-grind-archive`** (`2ebf3f293` — checkpoint-2/3 records live in that branch's wip/). **PUSH STATE: NOT pushed; rewind ⇒ force-push (Louis-approved), push the archive tag too.**
+- **Resume point:** nothing left on this branch — the track is complete and pushed to PR #1040. Remaining work is release-gated and lives outside this branch: the cross-repo sweep over `wip/subject-grants/demoted-public-surfaces.md` once the release ships.
+- **Registry state (post-regrind + checkpoint triage):** **1,743 grants total, 0 seeded.** Wave B deleted 148 entries, wave C deleted 41, checkpoint triage deleted 3 more; all remaining rationales are real (ported or newly written). The classifier + rewriter scripts live in the session scratchpad (throwaway; method documented in the wip record).
+- **Rubric case-law built up over batches 1–7 (apply consistently to cli/cogt/plugins/tools):**
+ - DEMOTE patterns: key+payload attachment (`set_event_log(context_key, *, event_log)` — the payload is the verb's object, the positional is a registry/target key); field-bag factories (`ConceptFactory.make(concept_code, *, domain_code, description, …)` — first field arbitrarily positional); mode/option params (`to_dict(disclosure_mode)`, `render_stuff_spec(output_format)`, `rendered_for_prompt(text_format)`, `pretty_print_*(title)`); instrumental/context params (`_evaluate_expression(working_memory)`, `_start_pipe_span(parent_otel_context)`, `render_with_images(registry)`, `_emit_via_registered_context(context)`); optional-selector-among-alternatives (`build_inputs_for_pipe(pipe_code=None, *, mthds_contents, bundle_path)`); symmetric/near-symmetric pairs (`expected`/`actual`, `domain_path`+`local_code`, `trace_name`+`trace_name_redacted`, and **same-type operand pairs** like `is_compatible(tested_concept: Concept, *, wanted_concept: Concept)` — two `Concept`s, no single candidate, demote like `copy_file(source, target)`); lone recursion accumulators (`needed_inputs(visited_pipes)`); config-first (`pipeline_run_setup(execution_config)`) and dependency-first (`load_telemetry_config(secrets_provider)`); filter/scope params (`list_models(categories)`, `validate_all(library_dirs)`); bare-literal call sites (`_get_config_file_not_found_error_msg("routing profile library")`); derived-value lookups (`_get_structure_class_import(class_name)`).
+ - KEEP families: entity-keyed getters/setters/managers (hub, libraries, registries, working memory, env — `get_stuff(name)`, `set_config(config)`, `open_tracer(graph_id)`); predicates (`is_x(value)`); single-operand transformations/conversions/parsers/validators/normalizers; factories-from-source (`make_from_blueprint(blueprint)`); protocol event/payload handlers (`observe_before_run(payload)`, `run(pipe_job)`, `emit(event)`, `on_pipe_end_success(node_id, *, …)`); positional-Callable protocols (visitors, re.sub repl, tenacity before_sleep, threading.excepthook, decorators, sort keys); pytest hooks (pluggy binds by name); noun-named single-operand derivations (`page_slug(cls)`, `_make_pk(pipeline_run_id)` — id encoded, not looked up); type-directed accessors (`main_stuff_as(content_type)`, `get_items(item_type)`).
+ - **job_metadata run-family demoted hierarchy-wide** (JobMetadata = information, not operand): PipeAbstract run/validate/span family + all operator/controller/signature overrides + PipeFactoryProtocol.make + factory impls. ⚠ cogt batch: `dry_mock.py`'s `__call__(self, job_metadata, *, …)` reporter protocol was deliberately LEFT positional — decide that family (report_dry_llm_job / report_mock_usage_llm_job must match the protocol) in the cogt batch; `update_job_metadata(job_metadata)` is a genuine keep (metadata IS the operand there).
+ - Registry edits are done with a tomlkit script per batch (`load_toml_with_tomlkit(path)` / `save_toml_to_path(data, path=…)`); keeps = replace rationale + drop `seeded`, demotes = delete entry, guard's `dead-grant` full-scan confirms nothing dangles. Rationale style: terse but def-specific family formulas (explicitly allowed by the rubric). (Single-entry deletions can be a plain line-block delete — deletion preserves sort order; agent-check's plxt-format + cko validate the result.)
+ - **Batches 8–11 learnings (plugins/cli/cogt/tools — now settled case-law):** (a) **console/logger/registry/client/secrets_provider as first param = instrumental sink/dependency → DEMOTE** even when it's the sole param — the object is in the verb name (`display_gateway_accepted_message(console)`, `InferenceBackendLibrary.load(secrets_provider)` matches the demoted `load_telemetry_config(secrets_provider)`). Consistency check: no reviewed package kept a console-as-sink grant (`PipelexHub.set_console(console)` is the lone exception — there console IS the operand being installed). (b) **`X | None = None` first positional that is a scope/location/destination/override and is often omitted or keyword at call sites → DEMOTE** (`check_config_files(config_dir=None)`, `make_pipelex_for_agent_cli(library_dirs=None)`, `generate_error_pages_cmd(output=None)`). But an **optional param that is genuinely the operand being resolved/parsed/acted-upon stays KEEP** (`_resolve_repo_root(repo_root)`, `_parse_config_arg(config_arg)`, `_end_otel_span_with_error(span)` — span is the object ended; `drift_plan_cmd(contract_id)` — contract_id is the direct object). Optionality is a *signal*, not a verdict — the discriminator is the verb-object/single-candidate test. (c) **optional-selector-among-alternatives → DEMOTE** (`make_prompt_document(uri=None, *, base64_data, raw_bytes)` — three co-equal sources; matches demoted `build_inputs_for_pipe`). (d) **positional-Callable protocols → KEEP** and this bit hard in cogt: `report_dry_llm_job`/`report_mock_usage_llm_job` are assigned as a `report_func` and called `report_func(job_metadata, ...)` positionally to satisfy `_ReportLLMJobFunc.__call__(job_metadata, *, ...)` — so job_metadata STAYS positional there (the hierarchy-wide job_metadata demote does NOT apply to protocol-satisfying reporters). Same KEEP for jinja `finalize`, `re.sub` repl, tenacity `should_retry`/`_transport_retry_wait`, Rich `__rich_repr__`, decorators (`update_job_metadata(func)`). (e) **mode/strategy selector as sole param → DEMOTE** (`get_aws_access_keys_with_method(api_key_method)` — enum match/case). (f) **bare-literal label param → DEMOTE** (`_validate_version("mthds-ui", value=...)` — name is only for the error msg, value is the real subject). (g) **Mechanical tooling that worked well (reuse for Phase-5-style sweeps):** a signature rewriter that moves the first non-self/cls positional after `*` (AST-reconstructs the param list preserving defaults/annotations; handles multiline) + a call-site fixer that inserts `<param>=` before the first positional arg at every call keyed by simple function name, run over `pipelex/` AND `tests/`, then pyright drives the checklist of remaining positional call sites. Scripts in the session scratchpad; `fko` handles single-param no-`*` defs, the rewriter handles `subject, *, opt` shapes fko can't.
+ - **Checkpoint-2 review learnings (apply to cli/cogt/plugins/tools):** (a) **Protocol/ABC parity is mandatory when demoting** — if a def implements a `@runtime_checkable` Protocol or overrides an ABC, demote the interface AND every implementer together (mode-param demotes on `StuffContent`/`StuffArtefact.rendered_for_template_async` left the `TextFormatRenderable` protocol positional → type-checker-blind landmine; caught at checkpoint 2). When a demote touches a class in a not-yet-reviewed batch's file (its protocol/base), reach in and demote it too (the ImageRenderable spillover precedent). (b) `rendered_for_template_async(text_format)` joins the mode/option DEMOTE family alongside `rendered_for_prompt(text_format)`. (c) **cli batch action item:** `cli/agent_cli/commands/pipe_cmd.py::_add_type_specific_fields` (seeded) is a near-duplicate of the already-demoted `builder/operations/pipe_ops.py::add_type_specific_fields` — demote the cli twin to match. (d) A grant whose call sites ALL pass by keyword isn't automatically a demote (grants permit but don't require positional) — the disqualifier is the *single-candidate* test, not call-site style.
+- **Batch execution recipe (how to grind one package — cli/cogt/plugins/tools):**
+ 1. `.venv/bin/pipelex-dev check-keyword-only --report` — confirm the package's seeded count (and that violations = 0 before you start).
+ 2. **Enumerate the batch's seeded entries.** Each `["pipelex/<pkg>/….py::<qualname>"]` with `seeded = true` in `subject_grants.toml` is one def to review. A python read is cleanest: `tomllib.load` the registry, filter keys `startswith("pipelex/<pkg>/")` where the entry still has `seeded`. (grep works too: entries are 3–4 lines, key → `param` → `rationale` → `seeded = true`.)
+ 3. **Review each entry** against the Rubric + the case-law above. Open the def (`path::qualname` → file+symbol), read its signature, `git grep` its call sites, then pick exactly one: **KEEP** (replace the SEEDED placeholder with a real def-specific rationale, drop the `seeded` line) · **DEMOTE** (move the subject param after the `*` — insert one if absent — on the def AND every Protocol/ABC/override sibling together, fix call sites pyright-guided, delete the entry) · **HATCH** (rare: `# kw-only: ignore` on the def line for framework-positional shapes, delete the entry).
+ 4. **Apply registry edits** with a tomlkit script (`from pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path`) — batch all keeps/demotes for the package in one pass; keeps mutate `rationale` + delete the `seeded` key, demotes `del data[key]`. Single-entry deletions may instead be a plain line-block Edit (deletion preserves sort order). Never hand-roll tomlkit (D10).
+ 5. **Gate:** `make agent-check` (runs fko → format → lint → pyright → mypy → cko; cko's dead-grant full-scan confirms nothing dangles). Run targeted tests for touched areas; run **full `make agent-test` if the batch demoted ANY framework-adjacent def** (Protocol/callback/Jinja/Typer/pytest-hook — pyright is blind to those, per the Risks section).
+ 6. **Commit** one per batch: `Subject grants batch N: review <pkg> (X kept, Y demoted)`. Do NOT push. Update this file's Status line (seeded-remaining + commit SHA) as you go, or at the next checkpoint.
+ ⚠ **Protocol/ABC parity (checkpoint-2 learning, bites silently):** demoting a def that implements a `@runtime_checkable` Protocol or overrides an ABC MUST demote the interface + every implementer in the same commit — even when the interface lives in a not-yet-reviewed file (reach in, `*`-it, delete its seeded grant). Leaving the interface positional while impls are keyword-only is a type-checker-blind landmine (exactly the two defects checkpoint 2 caught).
+- **Deviations from the plan (all deliberate):**
+ - The seed NEVER enters literal-typed subjects (rather than seeding then removing them) — they can never be granted (D4), so seeding them would only create entries destined for deletion. Same end state, no dead entries.
+ - `--report` grant/seeded progress meter lives in `check-keyword-only --report`; violation kinds are `missing-star` / `ungranted-subject` / `literal-subject` / `grant-param-mismatch` (def-level, lean path sees it) / `dead-grant` (full-scan only — covers deleted, renamed, demoted-to-all-keyword, and newly-carved-out defs).
+ - `SubjectGrantRegistryError` is defined IN `keyword_only_guard.py` (not an `exceptions.py`): the lean hook path cannot import a sibling module without dragging the `pipelex` package chain. It is a plain `Exception` subclass, not a `PipelexError` (no error page needed; `make gep` not required).
+ - TWO drift contracts opened (not one): `cli-docs` also triggered because the literal sweep touched `pipelex/cli/**`. Both acked genuinely; dogfood log has a real-catch (keyword-only-convention) + a clean-pass (cli-docs) entry.
+ - The workspace-root `.claude/rules/python-standards.md` keyword-only section was spliced from the kit source by hand (section-only replacement — the rest of that file tracks dev, which is ahead of this branch on Python-3.10-drop wording; do NOT copy the whole kit file over it).
+- **Branch / worktree:** `feature/Signatures` in the `_sig` worktree (branched off `docs/Update`). Treat `_sig` as the repo root. This file replaced the drift-contracts tracker inherited from `docs/Update` — that plan lives on in the `docs/Update` branch history and is in its dogfood phase; not this project's concern.
+- **Problem being solved:** the guard mechanically allows ANY first non-`self`/`cls` parameter to stay positional-or-keyword. Coding agents abuse that judgment-shaped permission, leaving first arguments positional when they are not the subject or not obviously so. The check must stay deterministic, but the exception must become deliberate, recorded, and reviewable — and **every existing positional subject is considered new: seeded into the registry unreviewed, then actually checked** (Phase 4).
+- **The shape in one paragraph:** a committed registry (`subject_grants.toml` at repo root) lists every def allowed a positional subject, with the subject param name and a one-sentence rationale. `check-keyword-only` fails on any positional subject without a matching grant, on any grant without a matching def (staleness is symmetric), and on any literal-typed positional subject regardless of grant. `make fko` already rewrites to the all-keyword form, so the lazy path is the strict path; keeping a positional subject costs a deliberate `subject-grant` command with an honest rationale, visible as a registry diff in every PR. Judgment happens at grant time and in review of the registry diff — CI stays 100% deterministic (no LLM in any gate, ever).
+
+### Decisions (settled — do not relitigate without Louis)
+
+- **D1 — Generic exception dropped.** A positional-or-keyword subject is legal only when a subject grant exists for that def. No grant → violation; `fko` auto-fixes it to all-keyword.
+- **D2 — Registry** = `subject_grants.toml` at repo root. One entry per def, keyed `<relative_path>::<qualified_name>` (exactly the guard's `Violation.key` format), recording `param` (the subject's name) and `rationale`. The file is rewritten sorted by key on every change so diffs are stable and merge conflicts stay trivial.
+- **D3 — CI stays deterministic.** No model verdict in any gate. The guard only verifies grant existence, param match, and freshness. The judgment lives in the grant rationale and in PR review of the registry diff (drift-ack spirit: an honest sentence, on the record).
+- **D4 — Literal-typed subjects banned outright**, grant impossible: a subject annotated `bool`, `int`, or `float` (including `X | None` / `Optional[X]` forms of those) is a violation no matter what. `f(True)` call sites are never acceptable. `str` subjects stay grantable — they are the house style (`pipe_code`, `name`, `uri`, …).
+- **D5 — Strict-all scope.** Grants are required for every positional subject: lone-subject defs (`def render(node)`) and subject-plus-kwonly defs (`def f(spec, *, ...)`) alike. Relaxing later (e.g. exempting lone-subject defs) is trivial; re-tightening later reopens ~1,000 defs — so start strict.
+- **D6 — All existing positional subjects are treated as NEW.** Seeded into the registry with `seeded = true` and a placeholder rationale, then every one is genuinely reviewed in Phase 4: real rationale (keep), or converted to keyword-only (demote), or `# kw-only: ignore` (rare, framework-positional). Zero `seeded` entries may remain at finalization.
+- **D7 — Staleness is symmetric and hard-fails.** Positional subject without grant = violation. Grant whose def no longer exists, or whose recorded `param` no longer matches the def's first param = violation. Renames and file moves therefore force a re-grant — that is a deliberate re-decision, not friction to engineer away.
+- **D8 — Existing mechanisms unchanged.** `# kw-only: ignore` (stronger hatch, short-circuits before the rule — required for framework-positional callables), the symmetric-tuple allowlist (whole-function, stays curated in code, NOT merged into the registry — different semantics), all carve-outs, and `fko`'s insert-leftmost behavior. Note `fko`'s reach grows: an ungranted subject def is now a violation, so `fko` (which runs inside `make agent-check`) will silently kwonly it — grant BEFORE running checks if you want the subject positional.
+- **D9 — `/` (positional-only) stays banned.** The convention doc's deliberate no-`/` decision stands; callers keep keyword discretion on granted subjects.
+- **D10 — Hook budget preserved.** The lean single-file path (`keyword_only_guard.py` run by file path from the PostToolUse hook) stays stdlib-only: it reads the registry with `tomllib` (read-only, machine-written file — the tomli-error-attrs concern applies to user-config parsing, not here). Registry writes happen only in the full CLI via `pipelex/tools/misc/toml_utils.py` (`load_toml_with_tomlkit` / `save_toml_to_path` — do not hand-roll tomlkit).
+- **D11 — Same-qualname defs share one entry.** `@overload` stubs and conditional redefinitions collapse onto one key; the recorded `param` must match each of them (forces overload stubs to align their subject name — acceptable).
-This file is a reviewer's guide to this PR (`feature/Devex-codegen` → `dev`). It summarizes what the branch delivers, the design decisions behind shapes a reviewer might otherwise flag, and the verification already performed. The full execution history (checkpoints, review fan-outs, triage records) lives in this file's git history on the branch; the deferred continuation of the track is documented at the workspace root under `wip/codegen/`.
+### Scan snapshot (2026-07-10 — point-in-time measurements, they WILL drift; regenerate via the Phase 1 `--report` extension)
-## What this PR delivers
+- ~2,600 defs inspected by the guard (after carve-outs); ~650 of them take no params.
+- **~1,700 use Exception 1 today** (~1,000 lone-subject, ~700 subject-plus-kwonly) — roughly 9 in 10 param-bearing inspected defs. The stock is the house style and looks overwhelmingly legitimate (top subject names: `name`, `pipe_code`, `exc`, `value`, `path`, `content`, `data`, `node`, …) — which is why the stock is seeded-then-reviewed rather than mass-demoted.
+- ~220 defs are already fully keyword-only; zero use `/`; a handful of `# kw-only: ignore` hatches.
+- **~30 literal-typed subjects** (`bool`/`int`/`float`, e.g. `do_doctor_cmd(fix: bool)`) — the mechanically-catchable slice of exactly the abuse this project kills. Beware: some are framework-positional (`version_callback(value: bool)` is invoked positionally by Typer via `callback=` — pyright is blind to that; `make agent-test` is the safety net).
-**One authority, many projections.** A resolved, validated MTHDS library is snapshotted into a **normalized library crate** — flat, fully qualified, natives materialized, refinement flattened, fingerprinted — and every developer-facing artifact is a deterministic projection off that crate: typed models (Python/TS), runnable input templates, runner scaffolds, and (served from `pipelex-api`, in a companion branch) HTTP responses. Generated files carry a self-describing stamp, are tracked in a sibling `codegen.lock`, and are verifiable **offline** by pure hashing.
+### Key repo facts (verified 2026-07-10)
+
+- Guard core: `pipelex/cli/dev_cli/commands/keyword_only_guard.py` (pure stdlib; `_evaluate_def` order = dunder → escape hatch → decorator carve-outs → typer-annotation → symmetric allowlist → rule). Presentation layer: `check_keyword_only_cmd.py`. Hook: `.claude/hooks/check-keyword-only.sh` invokes the guard **by file path** (never `-m` — that would import the `pipelex` package chain and blow the cold-start budget).
+- `make fko` inserts the bare `*` leftmost (all-keyword form) and is non-gating; read-only `make cko` owns the gate and runs last in `agent-check`, in `make check`, and as the `lint-keyword-only` CI job (aggregated by `lint-all`).
+- Convention doc: `docs/contribute/keyword-only-arguments.md`. **Drift contract `keyword-only-convention`** (in root `drift.toml`) triggers on the guard file with that doc as review target → Phase 3 must stage the trigger and `make drift-ack CONTRACT=keyword-only-convention RATIONALE="…"` after genuinely updating the doc. The new dev-CLI command sits under `pipelex/cli/dev_cli/**`, which the `cli-docs` contract excludes — only the one contract opens.
+- Dev CLI house style: Typer wrapper in `_dev_cli.py` delegating to a keyword-only `*_cmd()` in the module; CI-gate idiom prints a rich panel then `sys.exit(1)` (see `check_config_sync_cmd.py`). Unit tests: `tests/unit/pipelex/cli/dev/`, inline-source style (`find_violations_in_source` on snippets); a reusable `git_repo` fixture already exists in that conftest (built by the drift project) if needed.
+- If new CLI error classes are added (grant-command failures), they go in an `exceptions.py` per house rules and require `make gep` (error-pages regeneration) in the same commit.
+- Agent-rules source: the keyword-only section of `.claude/rules/python-standards.md` (workspace root) is generated from the kit rules source in this repo — edit the kit source, then regenerate (`make rules` family), never the generated file.
+- Makefile: per-target + shorthand-alias pattern (`check-keyword-only`/`cko`); `.PHONY` is one block. mkdocs nav lists contribute docs in TWO places in `mkdocs.yml` — update both if a doc is added (none planned; the convention doc already exists).
+
+## Checkpoint protocol (mandatory at every CHECKPOINT below)
+
+1. **Verify:** the phase's gates green — `make agent-check`, full `make agent-test` (targeted tests are fine between checkpoints), plus the checkpoint's specific gates. Do not proceed with failures.
+2. **Commit** the phase's work as one coherent commit (do not push unless asked).
+3. **Update this file** — tick boxes, refresh Cold-start context (status, decisions, deviations, commit SHAs) so a brand-new session resumes with zero conversation context.
+4. **Fan out `/code-review`** — a fresh no-context Sonnet sub-agent (Agent tool, `general-purpose`, `model: sonnet`, never a fork) pointed only at the commit range; never hand it this plan or your own conclusions.
+5. **Triage findings:** fix real defects; findings that are design tradeoffs get captured in a deferred-items doc under `wip/subject-grants/`, not reflexively applied.
+6. **STOP** — natural handoff point.
+
+## Rubric — what earns a grant
+
+Applies to every Phase 4 review and every future grant. Formalized into the convention doc in Phase 3; until then this section is the reference.
+
+A subject grant is warranted when EITHER:
+
+- **Verb–object test:** the function name is a verb (phrase) and the param is its direct object — the call reads as a sentence (`render(node)`, `validate_bundle(bundle)`, `parse_concept_spec(spec_data)`) — AND it is the **single candidate** (if you hesitate between two params, neither is the subject) — AND typical call sites pass a **self-labelling expression**, never a bare literal (literal-typed subjects are banned by D4 anyway);
+- OR the def must satisfy a **positional `Callable` protocol** (it is passed as a value to something that calls it positionally) and a grant keeps it compliant without reaching for the heavier `# kw-only: ignore`.
+
+When in doubt → keyword-only. The grant is the exception tier; all-keyword is always compliant and often more readable. Rationales must be def-specific but may be terse for obvious keeps ("verb–object; single operand") — the value is that someone actually looked; copy-paste boilerplate across dozens of entries defeats the point and is what Louis will spot-check for.
+
+## Registry format
+
+```toml
+version = 1
+
+["pipelex/graph/render.py::render_node"]
+param = "node"
+rationale = "Verb–object: renders the node; single obvious operand."
+
+# Transitional shape during Phases 2-4 only (rejected entirely by the guard after Phase 5):
+["pipelex/foo/bar.py::SomeClass.some_method"]
+param = "spec"
+rationale = "SEEDED 2026-07 — pre-registry tree, treated as new, review pending"
+seeded = true
+```
-The crate format is spec'd in the MTHDS standard (`mthds` repo: `docs/spec/library-crate.md`); the pipelex surfaces are spec'd at the workspace root (`docs/specs/pipelex-codegen.md`) with conformance skeletons/tests in the `conformance` repo. Contract-first: the specs and skeletons were written and reviewed before the engine code.
+Schema after finalization: exactly `param` + `rationale` per entry, `version` at top; unknown keys are a check failure.
+
+## Phase 1 — Mechanism: guard + registry + commands
+
+- [x] Guard core (`keyword_only_guard.py`, stays stdlib-only): load `subject_grants.toml` from repo root (`tomllib`); missing registry file = explicit check error (not mass-violation). New rule: a positional-or-keyword subject requires a matching grant (key + `param`); a literal-typed subject (D4) is a violation even with a grant; grants with no matching def or mismatched `param` are check failures. `# kw-only: ignore` keeps short-circuiting everything (existing evaluation order).
+- [x] Distinct violation messages per kind — "ungranted positional subject" / "banned literal-typed subject" / "stale grant" — each naming its fix (`make fko`, `make subject-grant FUNC=… RATIONALE=…`, or registry cleanup). Update the lean `main()` hook message text too.
+- [x] `pipelex-dev subject-grant "<path>::<qualname>" --rationale "…"`: validates the def exists, its first non-`self`/`cls` param is positional-or-keyword and not literal-typed, rationale non-empty; records `param` automatically; rewrites the registry sorted. Make target `subject-grant` (+ short alias, e.g. `sgr`), following the existing per-target pattern.
+- [x] Temporary `--seed` mode on `subject-grant` (deleted in Phase 5): scan the tree, emit an entry for every existing positional subject with `seeded = true` + the placeholder rationale.
+- [x] Extend `check-keyword-only --report`: per-package grant totals and seeded-remaining counts — this is the Phase 4 progress meter.
+- [x] Verify `fko` handles the new violation kind (it already inserts `*` leftmost; ungranted subject defs must be mechanically fixable; the re-parse-before-write guarantee is unchanged).
+- [x] Unit tests (inline-source style + injected registry content): grant match / missing grant / param mismatch / dead entry / seeded accepted (transitional) / literal ban incl. union and Optional forms / ignore-hatch precedence / same-qualname sharing (D11) / lean single-file path reads the registry / sorted-write round-trip / grant-command refusals (literal subject, non-positional subject, empty rationale, missing def).
+- [x] New code itself passes the convention; new error classes (if any) in `exceptions.py` + `make gep`.
+
+## Phase 2 — Seed + literal-subject sweep (lands atomically with Phase 1 — the tree must never gate red)
+
+⚠ **Ordering hazard:** between flipping the guard and committing the seed, NEVER run `make fko` / `make agent-check` on the tree — the fixer would kwonly ~1,700 defs. Generate the seed first (standalone scan), commit guard + registry together.
-## Component map (where to look in the diff)
+- [x] Run `--seed`, commit the registry: every existing positional subject enters as `seeded = true`.
+- [x] Sweep the literal-typed subjects (~30 per snapshot): kwonly each (fix call sites, pyright-guided), EXCEPT framework-positional ones (Typer `callback=`, etc.) which get `# kw-only: ignore` with a nearby justification. Remove their seed entries. `make agent-test` is the safety net for the pyright-blind cases.
+- [x] Gates green: `make agent-check`, `make agent-test`, `make cko`.
-- **`pipelex/codegen/`** — the engine. `resolved_fields.py` / `resolved_concepts.py` (neutral resolved layers every emitter consumes; imprecision is explicit, never guessed), `emitters/` (`python_structures`, `python_pydantic`, `ts_zod` + `naming`, `target`, `types_emitter` dispatch), `crate_encoding.py` (canonical JSON/TOML), `stamp.py` / `lock.py` / `check.py` / `emission.py` (the trust chain: stamped headers, `codegen.lock`, offline drift check, idempotent write-if-changed emission with stale-file pruning), `native_expansion.py` (retained as a consistency probe only — see pinned natives below).
-- **`pipelex/libraries/crate_normalization.py`** + `LibraryCrate.compute_normalized_fingerprint` — the normalization pass (post-validation, D6) and the widened fingerprint (concepts + pipes + domain metadata, provenance excluded; canonical JSON ≈ RFC 8785). The loader skips `native.*` crate entries so a normalized crate round-trips through `load_from_crate`.
-- **`pipelex/core/concepts/native/pinned_blueprints.py`** — natives materialize by lookup into the standard's pinned per-version definitions, never by runtime reflection (cross-implementation fingerprint byte-agreement). A parametrized test proves each pinned blueprint still matches its runtime content class.
-- **New native surface** — `native.Time` (`TimeContent`), the `time` structure-field type through the whole chain (blueprint enum → resolved fields → all three emitters → `StructureGenerator`), `ImageContent` flattened to paired `width`/`height` (breaking wire), `native.Date` pinned with real structure (wire unchanged).
-- **CLI** — `pipelex resolve` (crate to stdout, JSON/TOML), the `pipelex codegen types|inputs|check` family, shared `crate_loading.py` (one resolve/validate exit-code contract: 0 resolved · 1 invalid library · 2 no-verdict), and the D9 re-point: `build structures` is a thin alias of `codegen types --target python-structures`, `build runner` scaffolds through the same projection with the emitted class spellings. The legacy per-file structures generator and the concepts-only loading family are deleted.
-- **Agent CLI** — `pipelex-agent codegen types|check` mirrors the family through the two-stream envelopes (markdown/JSON); drift is a structured `CodegenDriftError` with `drifts[]` (exit 1), a missing/unreadable lock is no-verdict (exit 2). Deliberately no `codegen inputs` mirror (`pipelex-agent inputs` already surfaces that projection).
-- **`pipelex/pipeline/resolve_bundle.py`** + `emission.build_stamped_projection` — host-facing engine cores for the HTTP routes (`pipelex-api` companion branch): in-memory resolve with `validate_bundle`'s verdict vocabulary and loaded-on-success lifecycle; a pure stamping core so HTTP-served artifacts are byte-identical to locally written ones (pinned by a direct parity test).
-- **`StructureGenerator`** — refactored to consume the resolved-field layer; runtime materialization via `concept_factory` is byte-for-byte unchanged (the existing suite was the harness). Dead legacy dict-based paths deleted.
-- **Docs** — `docs/under-the-hood/codegen-projections.md` (engine, trust chain, extension-file story, HTTP serving), plus native/inputs doc updates. `CHANGELOG.md` `[Unreleased]` covers everything user-visible.
+## Phase 3 — Docs, rules, drift-ack (before the grind — mid-grind sessions must read the NEW convention, not the stale one)
-## Breaking changes (intentional, changelogged — no-backward-compat policy)
+- [x] Rewrite `docs/contribute/keyword-only-arguments.md`: Exception 1 becomes "granted subjects" (registry, commands, staleness semantics, D4 literal ban), add the rubric verbatim, record the reversal honestly (generic permission → explicit grant, and why: agents follow checks, not prose). Keep the no-`/` decision section (D9).
+- [x] Update the kit rules source for the keyword-only section (the generated `.claude/rules/python-standards.md` block) + regenerate; update the summary block in this repo's `CLAUDE.md`.
+- [x] Drift: stage the trigger files, then `make drift-ack CONTRACT=keyword-only-convention RATIONALE="…"` — a genuine review, and a real dogfood data point for the drift system (log it via the drift-review skill's dogfood log).
-- `pipelex build structures` output shape: one stamped `structures.py` + `codegen.lock`, bare-when-unique class names, declared imprecision instead of the old silent `TextContent` guess; `--force` gone; concepts-only loading API removed.
-- `pipelex build runner` structures directory rides the same projection; the script imports emitted class spellings.
-- `ImageContent` wire shape: `size` → paired `width`/`height` (both-or-neither validator).
-- `Time` joins the reserved native codes; the former blanket bare-time input rejection (`InputsTimeOnlyNotSupportedError`) is removed — a top-level TOML time maps to `TimeContent`.
+### CHECKPOINT 1 — mechanism live, seeded, documented
-## Design decisions a reviewer might otherwise flag
+Everything except the grind is done and reviewed as one unit. Gates: full checkpoint protocol + `make check` end-to-end (includes `drift-check`) + mkdocs strict build if docs changed.
-- **Imprecision over guessing (D5/B1-3):** a structureless or Python-class-backed concept emits an explicit opaque/imprecise marker (`# imprecise:` / `@imprecise`, `extra="allow"` pass-through classes), never a fabricated shape. This is the spec'd behavior, not missing handling.
-- **ts-zod keys are wire-native snake_case (D10):** a cold review empirically confirmed that a generic deep snake↔camel remap silently corrupts caller data keys inside `z.record()`/`z.unknown()` values, so the schema validates the wire directly and the remap layer does not exist. camelCase ergonomics, if ever wanted, must be a schema-aware transform.
-- **Sibling `codegen.lock`, not an extension of `methods.lock` (D4):** different owner (Pipelex vs standard), location, content, and lifecycle — consumer projects often aren't MTHDS packages at all.
-- **Verdicts are structural, exit codes/HTTP statuses are presentation** (workspace meta-rule): machine consumers branch on `is_valid`/error envelopes, never on exit codes.
-- **`pipe_ref` is plumbed through the stamp but unused today:** the stamp format is spec'd to carry it for the per-pipe projection kinds that arrive in later phases; it is cheap and round-trip tested — not speculative dead code.
-- **Loaded-on-success contract:** `resolve_crate_from_contents` (like `validate_bundle`) leaves the library loaded + current on success and the host owns teardown — the HTTP routes read live pipes from it before their `finally`. Teardown conservation is pinned by tests on both repos.
-- **`native_expansion.py` reflection retained:** consistency probe only (pinned blueprint ↔ runtime class); materialization is the pinned lookup.
+## Phase 4 — The review grind (every seeded grant treated as new)
-## Verification record
+Batch by top-level package (`pipelex/core`, `pipelex/builder`, `pipelex/cli`, `pipelex/cogt`, …), sized via `--report` — expect on the order of 10–15 batches for ~1,700 entries. This phase is the dominant cost of the project.
-- Gates at every checkpoint and after the final dev merge: `make agent-check` (ruff, pyright 0, mypy 0, kw-only, plxt) + **full** `make agent-test`.
-- Emitted-code quality gates in-tree: `pyright --strict` over generated Python (D7), serialize→parse round-trips, resolve→emit e2e over a multi-bundle closure fixture feeding every emitter; golden tests assert compile-and-parse behavior, not byte equality.
-- Live binary proofs at each stage: stamp/lock/check drift loop (hand-edit → exit 1 → regen heals → byte-identical), alias re-point, agent-CLI envelopes and exit codes.
-- **Proof by starter** (`pipelex-starter-python`, companion branch): hand-written models deleted, committed generated clients, offline smoke tests — the conversion caught and fixed real engine bugs (model-spec-less boot, structureless `Image`, non-deterministic template placeholders).
-- Independent cold `/code-review` fan-outs (one reviewer per touched repo, diff-pointer only, no plan context) ran at every checkpoint; all confirmed findings were fixed in-branch (e.g. the ts-binder key-corruption Critical, the non-UTF-8 `codegen check` crash, the `time` exec-globals `NameError`) and design tradeoffs were recorded as deferred docs rather than reflexively applied.
+Per seeded entry, apply the rubric and pick exactly one:
-## Cross-repo companions (separate branches, not in this PR)
+- **Keep:** replace the placeholder with a real, def-specific rationale; drop `seeded`.
+- **Demote:** convert the def to all-keyword (`*` leftmost), fix call sites (pyright-guided), delete the entry.
+- **Hatch (rare):** `# kw-only: ignore` when the positional shape is framework-owned; delete the entry.
-`pipelex-api` `feature/Codegen` (routes `POST /v1/resolve` + `POST /v1/codegen`, breaking `/v1/build/*` migration — deploy gated on this release), `mthds` `feature/Codegen` (library-crate + native-concepts specs), `conformance` `feature/Codegen` (route conformance live; CLI skeletons release-gated), workspace-root `feature/Follow-ups` (`docs/specs/pipelex-codegen.md`), `mthds-js` `feature/Codegen` (agent passthrough stubs), `pipelex-starter-python` `feature/Codegen` (the converted starter). Post-release coordination lives in `wip/codegen/release-wave.md` at the workspace root.
+Rules of engagement:
-## Deferred (documented, not in this PR)
+- [x] Each batch is one commit, gates green (`make agent-check` + targeted tests; full `make agent-test` at checkpoints and after any batch that demoted framework-adjacent defs). — done for all 11 batches; full agent-test run after each of batches 8–11.
+- [x] Expect drift toward all-keyword — that is desired; grants are the luxury tier. — confirmed: ~150 demoted, ~1,453 kept overall.
+- [x] **Demoted public surfaces:** appended below (see the new batch-8–11 entries). No backward compat, but the breakage is inventoried for the release-wave cross-repo sweep.
-The remaining Phase 3 stretches (MCP projection; webapp form + n8n), Phase 4 (methods as products), and Phase 5 (frontier) are deferred by decision (2026-07-11) and documented one-file-per-concern under the workspace root's `wip/codegen/`.
+Demoted public surfaces (append as you grind — the Phase 2 literal sweep already demoted these; external consumers calling them positionally break):
+
+- `pipelex.tools.misc.string_utils.pluralize` / `count_with_noun` — `count` now keyword-only
+- `pipelex.tools.log.log.Log.set_level_by_int` (`level_int`) and `pipelex.tools.log.log_levels.LogLevel.from_int` (`logging_level`)
+- `pipelex.tools.misc.pretty.PrettyPrinter.pretty_width` (`width`)
+- `pipelex.hub.PipelexHub.set_dry_run_forced` (`is_forced`)
+- `pipelex.cli.installed_methods.discover_installed_methods` (`include_global`)
+- `pipelex.cli.commands.init.config_files.init_config` (`reset`)
+- `pipelex.system.telemetry.*.is_custom_portkey_logging_enabled` / `is_pipelex_gateway_portkey_logging_enabled` (`is_debug_configured`; internal callers already keyword)
+- `pipelex.plugins.anthropic.anthropic_factory.AnthropicFactory.calculate_safe_max_tokens_for_timeout` (`timeout_seconds`)
+- `pipelex.runtime_bridge.bootstrap.ensure_pipelex_booted` (`config_overrides`) — runtime_bridge is consumed by pipelex-api / pipelex-worker; positional callers break
+- `pipelex.builder.operations` entry points `build_inputs_for_pipe` (`pipe_code`), `list_models` (`categories`), `validate_all` (`library_dirs`) — agent-CLI/MCP plumbing, but importable
+- `pipelex.errors.error_pages_generator.generate_error_pages` (`output_dir`) — dev tooling, listed for completeness
+- `pipelex.reporting` protocol methods `set_event_log` / `clear_event_log` (`context_key`) — external ReportingProtocol implementations must match
+- `pipelex.core.pipes.pipe_abstract.PipeAbstract` run-family (`run_pipe`, `live_run_pipe`, `dry_run_pipe`, `validate_before_run`, `validate_after_run`, `needed_inputs`) — `job_metadata` / `visited_pipes` now keyword-only; any external code subclassing or invoking pipes positionally breaks
+- `pipelex.core.stuffs.stuff_content.StuffContent.rendered_for_prompt` / `rendered_for_template_async` (`text_format`) and `pretty_print_content` (`title`) — public content API; positional TextFormat callers break
+- `pipelex.libraries.library_manager_abstract.LibraryManagerAbstract` load family (`load_libraries`, `load_from_blueprints`, `load_from_crate`, …) — `library_id` now keyword-only
+- `pipelex.pipeline.pipeline_run_setup.pipeline_run_setup` (`execution_config`) and `pipelex.pipeline.pipeline_manager_abstract.add_new_pipeline` (`pipe_code`)
+- `pipelex.tools.jinja2.image_renderable.ImageRenderable.render_with_images` (`registry`) — protocol + all content-class implementations
+- CLI-internal helpers (doctor/show/update/validate `*_cmd` delegates and UI builders) — almost certainly not called externally, listed for completeness in the diff, not here
+- `pipelex.tools.jinja2.text_format_renderable.TextFormatRenderable.rendered_for_template_async` (`text_format`) — `@runtime_checkable` protocol; external implementers/positional callers break (checkpoint-2 spillover completion)
+- `pipelex.libraries.concept.concept_library_abstract.ConceptLibraryAbstract.is_compatible` / `concept_library.ConceptLibrary.is_compatible` (`tested_concept`) — external code subclassing or calling `is_compatible` positionally breaks (checkpoint-2 demote)
+- **Batch 8–11 demoted public surfaces (external consumers calling positionally break):**
+ - `pipelex.cogt.image.prompt_image_factory.PromptImageFactory.make_prompt_image` (`uri`) and `pipelex.cogt.document.prompt_document_factory.PromptDocumentFactory.make_prompt_document` (`uri`) — public content factories; positional-`uri` callers (cookbook, cocode, app) break
+ - `pipelex.cogt.models.model_manager_abstract.ModelManagerAbstract.setup` + its `ModelManager.setup` override (`secrets_provider`) and `pipelex.cogt.model_backends.backend_library.InferenceBackendLibrary.load` (`secrets_provider`) — external code subclassing/invoking the model-manager setup/backend-load positionally breaks (dependency-first demote, matches `load_telemetry_config`)
+ - `pipelex.cogt.llm.llm_setting.LLMSettingChoices.make_completed_with_defaults` (`for_text`) and `pipelex.cogt.model_routing.routing_profile.RoutingProfile.get_backend_match_for_model` (`enabled_backends`)
+ - `pipelex.tools.aws.aws_config.AwsConfig.get_aws_access_keys_with_method` (`api_key_method`) — mode selector
+ - The remaining batch-8–11 demotes are CLI-internal / plugin-internal helpers (list_*_models, discovery register helpers, console UI, doctor check_*, run/validate/build cores, gateway `_call_relay`) — not part of the importable `pipelex` public API; listed in the commit diffs, not here.
+
+### CHECKPOINT 2 — mid-grind (after roughly half the batches) ✅ DONE 2026-07-10
+
+Full checkpoint protocol completed. Gates green (`make agent-check` + full `make agent-test`, run twice — before and after the review fixes). Cold no-context Sonnet `/code-review` fan-out over `9f5bd54a3..227b98822` (4 agents) ran and was triaged: two real interface/impl-parity defects fixed in `f10b9ad37` (TextFormatRenderable protocol spillover, is_compatible near-symmetric demote), one low-confidence rationale deferred, test changes clean. Record: `wip/subject-grants/checkpoint-2-review.md`. Seeded-remaining count and rubric learnings updated in the Cold-start context above. NEXT: grind cli / cogt / plugins / tools.
+
+### CHECKPOINT 3 — grind complete ✅ REACHED 2026-07-11
+
+Zero `seeded = true` entries remain (`--report` confirms `seeded remaining: 0`). Gates green: `make agent-check` + full `make agent-test` green at the checkpoint (and after each of batches 8–11). Batches 8–11 committed (`ea0e642e6` plugins, `c3aa0ee3c` cli, `f542ba941` cogt, `ff8bfbdc6` tools). **CHECKPOINT 3 review DONE + triaged:** cold no-context Sonnet `/code-review` fan-out over `a1649f269..ff8bfbdc6` (3 agents: code-correctness, grant-judgment, mechanical-rewrite-safety). Correctness + mechanical-safety came back clean (independent AST scan = 0 positional-call breakage, all signature rewrites preserved defaults/order/types, no name-collision mis-edits). Grant-judgment found **3 real misses — all fixed**: kept-as-subject lookup-container/scope params where a same-batch sibling demoted the identical shape (`sync_main_config_cmd(target)`, `_resolve_terminal_candidates(deck)`, `suggest_model_alternatives(model_deck)` — the last needed 2 call-site fixes). One low-confidence flag (`get_api_key(backend)` family) considered and deliberately kept (registry-wide "derive value from config" convention). Full record: `wip/subject-grants/checkpoint-3-review.md`. NEXT: Phase 5 finalization.
+
+## Phase M — Absorb the upstream `dev` merge (⚠ DO THIS BEFORE PHASE 5; then STOP for Louis)
+
+Louis pushed `feature/Signatures` (tip `c60a448b8`) and is bringing a big update in from `dev`. **Sequencing decision, settled with Louis: merge FIRST, Phase 5 LAST, and check with Louis before starting Phase 5.** Why merge-first: Phase 5 *deletes* the `--seed`/`seeded` machinery, and that machinery is exactly what absorbs the merge's wave of new positional subjects. Close that door only after everyone is through it. Doing Phase 5 first would throw away the onboarding tool at the moment it's most needed AND force redoing the Phase-5 deliverables (CHANGELOG, docs, demoted-surfaces list, drift-ack) that the merge perturbs anyway.
+
+### ⚠ The one destructive misstep — fko-clobber, merge edition
+
+After you resolve the merge, the tree is full of **dev's ungranted positional subjects** — `dev` still runs the OLD generic-exception guard, so every new positional first-arg it added is a violation under our guard. The instant you run **`make fko` or `make agent-check`** (agent-check runs `fko` first), the fixer **silently keyword-only's all of them**, rewriting freshly-merged upstream signatures out from under you. This is the Phase-2 fko-before-seed hazard, now against dev's code.
+
+- **SAFE to run freely:** the read-only gate `make cko` and the PostToolUse edit hook (`.claude/hooks/check-keyword-only.sh`) — both only *report* violations, never fix. Survey with `cko` as much as you like.
+- **SAFE:** `subject-grant --seed` — verified idempotent + additive (`subject_grant_cmd.py::_run_seed`): it seeds only *ungranted* positional subjects and leaves the 1,513 reviewed grants (and any existing seeded entries) untouched; literal-typed subjects are never seeded.
+- **HARD RULE:** run `--seed` **before** the first `fko` / `agent-check` on the merged tree.
+
+### Merge workflow (cold-start-safe)
+
+> **PROGRESS (2026-07-11, second session): steps 0–6 DONE — step 7 REMAINS.** Steps 0–4 ran via the REWIND variant (rewind to pre-grind `9f5bd54a3`, merge dev there — 9 trivial conflicts instead of 23 — then survey/`--seed`/dead-grant cleanup). Step 5 (the regrind) is COMPLETE as waves A/B/C (`fb1a91197` / `65a4153ae` / `f83308367` — see Status line; method in `wip/subject-grants/regrind-after-dev-merge.md`). Step 6 (checkpoint review fan-out + triage) is COMPLETE — findings and triage in the wip record's §Checkpoint review. **NEXT = step 7 (STOP for Louis before Phase 5).**
+
+0. **Decide with Louis:** merge onto `feature/Signatures` directly, or onto a throwaway integration branch off it (keeps the ~1,513-grant baseline trivially recoverable if the merge gets messy). Confirm the exact source ref — Louis said "dev", most likely `origin/dev`; `git fetch` then `git log --oneline origin/dev -5` to eyeball what's coming.
+1. **Merge** (`git merge origin/dev`). Resolve the **mechanism conflicts by keeping OUR side** — this branch *is* the new guard, `dev` has the old one:
+
+ - `pipelex/cli/dev_cli/commands/keyword_only_guard.py`, `check_keyword_only_cmd.py`, `subject_grant_cmd.py`
+ - `pipelex/cli/dev_cli/_dev_cli.py` (the `subject-grant` / `check-keyword-only` wiring)
+ - `Makefile` (the `cko` / `fko` / `sgr` / `subject-grant` targets)
+ - `docs/contribute/keyword-only-arguments.md` (we rewrote it)
+ - `subject_grants.toml` is OURS ALONE (`dev` has no such file) → no textual conflict, but it is now semantically stale wherever `dev` changed code — the guard's symmetric staleness surfaces that in step 2.
+ - **Re-splice, do NOT take-ours wholesale:** `.claude/rules/python-standards.md`, this repo's `CLAUDE.md`, and `drift.toml` — take **dev's** version of each file (it carries dev's other evolution, e.g. Python-3.10-drop wording and any new drift contracts), then re-splice ONLY our keyword-only section / `keyword-only-convention` contract back in. Do not clobber dev's non-keyword content.
+
+2. **Survey (read-only, no clobber):** `make cko`. Expect four violation kinds — `ungranted-subject` (dev's NEW positional subjects — the big wave), `dead-grant` (a grant whose def dev renamed/moved/deleted), `grant-param-mismatch` (dev changed a granted def's first param name), `literal-subject` (dev added a `bool`/`int`/`float` subject).
+3. **Onboard the new wave:** `.venv/bin/pipelex-dev subject-grant --seed` (additive — safe). Stamps every new ungranted positional subject as `seeded = true`. `--report` then shows per-package seeded counts — the Phase-4 progress meter, now for the merge delta.
+4. **Fix the staleness `--seed` does NOT handle:** `dead-grant` → delete the entry (def gone) or re-grant at the new path (def moved but still a legit subject); `grant-param-mismatch` → update the entry's `param` if the subject was just renamed, else demote; `literal-subject` → demote the def (or `# kw-only: ignore` if framework-positional) — never seed it (D4).
+5. **Now** `make agent-check` is safe (seeded entries are valid grants; `fko` leaves them alone). **Grind the new seeded wave batch-by-batch** with the exact Phase-4 **Batch execution recipe** + this session's mechanical tooling (signature-rewriter + call-site fixer — see batch-8–11 learnings item (g)), applying the same rubric + all accumulated case-law.
+6. **Gates + checkpoint review:** `make agent-check` + full `make agent-test` green; fan out a fresh no-context `/code-review` over the merge+grind commit range (same 3-agent shape as CHECKPOINT 3: code-correctness, grant-judgment, mechanical-rewrite-safety); triage real defects, record under `wip/subject-grants/`.
+7. **⚠ STOP — confirm with Louis before starting Phase 5.** Do NOT auto-proceed. Phase 5 closes the transitional door (deletes `--seed`); only do it once Louis agrees the merge is fully absorbed and the tree is clean (`--report`: `seeded remaining: 0` again, all gates green).
+
+## Phase 5 — Finalization
+
+**⚠ GATED: do NOT start until Phase M (the `dev` merge) is fully absorbed AND Louis has signed off.** Phase 5 deletes `--seed`, which the merge depends on — see Phase M.
+
+- [x] Delete `--seed` and all `seeded`-field support; tighten the registry schema (exactly `param` + `rationale`; unknown keys fail the check). The now-dead `collect_all_def_infos` helper deleted too (the dead-grant scan caught its stale entry — the symmetry working as designed).
+- [x] CHANGELOG `[Unreleased]`: convention hardened (grants registry, literal-subject ban) + breaking note covering the demoted signatures.
+- [x] Final docs pass (convention doc reflects the post-transitional state; no `seeded` mentions survive); drift re-acked (keyword-only-convention + cli-docs + config-docs, the last two opened by the regrind / dev merge).
+- [x] Hand off the demoted-public-surfaces list to the release-gated cross-repo sweep: `wip/subject-grants/demoted-public-surfaces.md`.
+- [x] Full gates: `make check` end-to-end + `make agent-test`. Cold-start context updated to COMPLETE.
+
+## Risks & safety nets
+
+- **Framework-positional callers** (Typer `callback=`, Jinja filters, SDK hooks): pyright passes a wrongly-kwonly'd callback; `make agent-test` is the net — mandatory after the Phase 2 sweep and any suspicious Phase 4 demotion.
+- **fko-before-seed hazard** (Phase 2 warning above) — the one truly destructive misstep; land guard + seed atomically. **Recurs at the `dev` merge (Phase M):** after resolving the merge, `--seed` the new ungranted subjects BEFORE the first `fko`/`agent-check`, or the fixer silently keyword-only's all of dev's freshly-merged positional signatures. `make cko` (read-only) and the edit hook are safe; `--seed` is additive/idempotent.
+- **Rubber-stamp risk in the grind:** rationale honesty can't be mechanized. Mitigations: def-specific rationale rule, Louis spot-checks registry diffs, batches small enough to review for real.
+- **Registry merge conflicts** across parallel branches: sorted, append-mostly file; conflicts resolve trivially, same as the drift manifest.
+- **Hook cold-start budget:** one `tomllib` read of a machine-written file — negligible; keep the lean path import-clean (no tomlkit there).
+
+## Out of scope
+
+- Any LLM verdict inside CI (D3 — permanent).
+- Other repos' conventions; the conformance suite (this is repo-internal dev tooling, no cross-repo spec surface).
+- Retro-fitting the symmetric-tuple allowlist into the registry (D8 — different semantics, stays in code).
diff --git a/docs/configuration/config-practical/logging-config.md b/docs/configuration/config-practical/logging-config.md
index 4fbce4db9..339b0d8e0 100644
--- a/docs/configuration/config-practical/logging-config.md
+++ b/docs/configuration/config-practical/logging-config.md
@@ -114,7 +114,7 @@ is_link_path_enabled = true
```toml
highlighter_name = "json" # or "repr"
-is_markup_enabled = false
+is_markup_enabled = true
```
- `highlighter_name`: Choose between JSON or repr highlighting
@@ -168,7 +168,7 @@ is_show_time = false
is_show_level = true
is_link_path_enabled = true
highlighter_name = "json"
-is_markup_enabled = false
+is_markup_enabled = true
is_rich_tracebacks = true
is_tracebacks_word_wrap = true
is_tracebacks_show_locals = false
diff --git a/docs/configuration/config-technical/cogt-config.md b/docs/configuration/config-technical/cogt-config.md
index 52bf0706d..1212c3cec 100644
--- a/docs/configuration/config-technical/cogt-config.md
+++ b/docs/configuration/config-technical/cogt-config.md
@@ -14,7 +14,6 @@ The Cogt configuration manages all cognitive tools in Pipelex, including LLM (La
transport_max_retries = 2
# Main Cogt configuration sections
-[cogt.inference_manager_config]
[cogt.llm_config]
[cogt.img_gen_config]
[cogt.extract_config]
@@ -35,17 +34,6 @@ This is "Tier 1" of the retry model. It is wired uniformly into every inference
It is distinct from `llm_config.schema_reask_max_attempts`, which is `instructor`'s schema re-ask count for structured-output validation failures — a different concern.
-## Inference Manager Configuration
-
-Controls automatic setup of various cognitive tools:
-
-```toml
-[cogt.inference_manager_config]
-is_auto_setup_preset_llm = true
-is_auto_setup_preset_img_gen = true
-is_auto_setup_preset_extract = true
-```
-
## LLM Configuration
Configuration for all Language Model interactions:
@@ -53,7 +41,7 @@ Configuration for all Language Model interactions:
```toml
[cogt.llm_config]
default_max_images = 100 # Maximum number of images in prompts
-is_structure_prompt_enabled = false
+is_structure_prompt_enabled = true
schema_reask_max_attempts = 3 # instructor schema re-ask attempts, between 1 and 10
```
@@ -80,20 +68,21 @@ aspect_ratio = "square" # Options: square, landscape_4_3, landscape_3_2, landsc
background = "auto" # Options: transparent, opaque, auto
# size is optional and has no default key: when unset, no size intent is sent and the provider's
# default size applies (Gemini jobs omit image_size; OpenAI models use their fixed 1K-class preset
-# for the aspect ratio). Set it to a size tier ("1k", "2k", "4k") or an exact size like "2048x1152"
+# for the aspect ratio). Set it to a size tier ("0.5k", "1k", "2k", "4k") or an exact size like "2048x1152"
# to apply a default size to every PipeImgGen that doesn't set its own. A tier default composes
# with any aspect_ratio; an exact-size default implies its own ratio, so it is not applied to
# pipes that explicitly set aspect_ratio (the pipe's ratio wins).
quality = "low" # Options: low, medium, high
-# nb_steps = 1 # Number of diffusion steps (28 is good for Flux, [1,2,4,8] for SDXL Lightning)
-guidance_scale = 3.5 # Controls adherence to prompt
+nb_steps = 28 # Number of diffusion steps (28 is good for Flux, [1,2,4,8] for SDXL Lightning)
+guidance_scale = 2.5 # Controls adherence to prompt
is_moderated = true # Enable content moderation
safety_tolerance = 5 # Safety level (1-6)
is_raw = false # Raw output mode
-output_format = "jpeg" # Options: png, jpeg, webp
seed = "auto" # "auto" or specific integer
```
+Note: `output_format` is a per-job parameter (set on the pipe), not a valid key under `img_gen_param_defaults`.
+
### ImageGen Job Parameters
Image generation jobs support these parameters:
@@ -101,7 +90,7 @@ Image generation jobs support these parameters:
- **Dimensions**:
- `aspect_ratio`: Predefined ratios for image dimensions
- - `size` (optional): Portable size intent — a size tier (`"1k"`, `"2k"`, `"4k"`) or an exact pixel size like `"2048x1152"`. Unset means the provider's default size. See [PipeImgGen — Image size and portability](../../building-methods/pipes/pipe-operators/PipeImgGen.md#image-size-and-portability)
+ - `size` (optional): Portable size intent — a size tier (`"0.5k"`, `"1k"`, `"2k"`, `"4k"`) or an exact pixel size like `"2048x1152"`. Unset means the provider's default size. See [PipeImgGen — Image size and portability](../../building-methods/pipes/pipe-operators/PipeImgGen.md#image-size-and-portability)
- `background`: Background handling mode
- **Quality Control**:
@@ -128,6 +117,7 @@ Configuration for Optical Character Recognition:
```toml
[cogt.extract_config]
default_page_views_dpi = 72
+```
## Unified Backend Integration
@@ -178,7 +168,6 @@ All model types support the same routing, aliasing, and preset systems.
3. **General**:
- - Enable auto-setup for easier initialization
- Use platform preferences to ensure consistent model selection
- Configure OCR handles based on your accuracy needs
@@ -188,14 +177,9 @@ All model types support the same routing, aliasing, and preset systems.
[cogt]
transport_max_retries = 2
-[cogt.inference_manager_config]
-is_auto_setup_preset_llm = true
-is_auto_setup_preset_img_gen = true
-is_auto_setup_preset_extract = true
-
[cogt.llm_config]
default_max_images = 100
-is_structure_prompt_enabled = false
+is_structure_prompt_enabled = true
schema_reask_max_attempts = 3
[cogt.img_gen_config.img_gen_job_config]
@@ -205,12 +189,11 @@ is_sync_mode = false
aspect_ratio = "square"
background = "auto"
quality = "low"
-# nb_steps = 1
-guidance_scale = 3.5
+nb_steps = 28
+guidance_scale = 2.5
is_moderated = true
safety_tolerance = 5
is_raw = false
-output_format = "jpeg"
seed = "auto"
[cogt.extract_config]
diff --git a/docs/configuration/config-technical/inference-backend-config.md b/docs/configuration/config-technical/inference-backend-config.md
index 03aa1732d..8f7f6e358 100644
--- a/docs/configuration/config-technical/inference-backend-config.md
+++ b/docs/configuration/config-technical/inference-backend-config.md
@@ -434,15 +434,15 @@ Define user-friendly names that map to model names. Aliases are defined in the d
```toml
[llm.aliases]
# Simple aliases map to a single model
-best-claude = "claude-4.5-opus"
-best-gpt = "gpt-5.2"
-best-gemini = "gemini-3.1-pro"
+best-claude = "claude-4.8-opus"
+best-gpt = "gpt-5.5"
+best-gemini = "gemini-pro-latest"
# Default aliases (used in presets)
-default-general = "claude-4.5-sonnet"
-default-premium = "claude-4.5-opus"
-default-large-context-text = "gemini-2.5-flash"
-default-small = "gemini-2.5-flash-lite"
+default-general = "claude-4.6-sonnet"
+default-premium = "claude-4.8-opus"
+default-large-context-text = "gemini-flash-latest"
+default-small = "gpt-4o-mini"
```
When using aliases in `.mthds` files or other configurations, prefix them with `@`:
@@ -624,9 +624,9 @@ The system loads configurations in this order:
Common error types:
- `ModelDeckNotFoundError`: Missing LLM deck configuration files
-- `ModelsManagerError`: Issues with model management
+- `ModelNotFoundError`: Referenced model not found in the deck
- `LLMHandleNotFoundError`: Referenced model or alias not found
-- `LLMPresetNotFoundError`: Referenced preset not found
+- `ModelChoiceNotFoundError`: Referenced preset/choice not found
## Best Practices
@@ -654,7 +654,7 @@ Common error types:
- Document custom presets and their use cases in your team documentation
5. **Customization**:
- - Use `overrides.toml` for project-specific settings
+ - Use `x_custom_*.toml` deck files for project-specific settings
- Keep base configurations unchanged to make upgrades easier
- Version control your custom configurations
- Share routing profiles and presets across your team
diff --git a/docs/configuration/config-technical/library-config.md b/docs/configuration/config-technical/library-config.md
index 75e455c2a..8dd6d4f0a 100644
--- a/docs/configuration/config-technical/library-config.md
+++ b/docs/configuration/config-technical/library-config.md
@@ -30,7 +30,7 @@ from pipelex.pipeline.runner import PipelexMTHDSProtocol
# Python: run the bundle's main_pipe
runner = PipelexMTHDSProtocol(
- bundle_uri="path/to/my_bundle.mthds",
+ bundle_uris=["path/to/my_bundle.mthds"],
)
response = await runner.execute(
inputs={...},
@@ -39,7 +39,7 @@ pipe_output = response.pipe_output
# Python: run a specific pipe from the bundle
runner = PipelexMTHDSProtocol(
- bundle_uri="path/to/my_bundle.mthds",
+ bundle_uris=["path/to/my_bundle.mthds"],
)
response = await runner.execute(
pipe_code="my_pipe",
@@ -81,7 +81,7 @@ Pipelex resolves library directories using this priority order (highest to lowes
| **3 (Fallback)** | `PIPELEXPATH` environment variable | System-wide or shell session default |
!!! info "Empty List is Valid"
- Passing an empty list `[]` to `library_dirs` is a valid explicit value that **disables** directory-based library loading. This is useful when using `mthds_content` directly without needing files from the filesystem.
+ Passing an empty list `[]` to `library_dirs` is a valid explicit value that **disables** directory-based library loading. This is useful when using `mthds_contents` directly without needing files from the filesystem.
### Using the PIPELEXPATH Environment Variable
@@ -196,12 +196,12 @@ response2 = await runner2.execute(
)
pipe_output2 = response2.pipe_output
-# Disable directory loading (use only mthds_content)
+# Disable directory loading (use only mthds_contents)
runner3 = PipelexMTHDSProtocol(
library_dirs=[], # Empty list disables directory-based loading
)
response3 = await runner3.execute(
- mthds_content=my_mthds_string,
+ mthds_contents=[my_mthds_string],
inputs={"input": "value"},
)
pipe_output3 = response3.pipe_output
@@ -273,7 +273,7 @@ pipe_output = response.pipe_output
3. **Use per-call `library_dirs` for exceptions**: Override only when a specific execution needs different directories.
-4. **Use empty list `[]` for isolated execution**: When you want to execute only from `mthds_content` without loading any file-based definitions.
+4. **Use empty list `[]` for isolated execution**: When you want to execute only from `mthds_contents` without loading any file-based definitions.
5. **Include structure class directories**: Remember that `library_dirs` must contain both `.mthds` files AND Python files defining `StructuredContent` classes.
@@ -281,7 +281,7 @@ pipe_output = response.pipe_output
To improve performance and avoid loading unnecessary files, Pipelex automatically excludes common directories from discovery:
-- `.venv` - Virtual environments
+- `.venv`, `venv`, `env`, `virtualenv`, `.virtualenv` - Virtual environments
- `.git` - Git repository data
- `__pycache__` - Python bytecode cache
- `.pytest_cache` - Pytest cache
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index 8273d9bb5..6b66126fe 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -11,15 +11,18 @@ Pipelex uses a TOML-based configuration system with **shipped defaults** plus **
- **Shipped defaults**: Pipelex ships default values that are maintained in the Pipelex repository (contributors will see them in the repo root `pipelex.toml`). This is the baseline used by the installed package.
- **Project overrides**: a project that *uses* Pipelex typically customizes behavior via files created in `.pipelex/`.
-You can create the project configuration files by running:
+You can create the configuration files by running:
```bash
-pipelex init config
+pipelex init config # creates the global config at ~/.pipelex/
+pipelex init config --local # creates the project config at {project_root}/.pipelex/
```
!!! important "Configuration Setup Notes"
- 1. `pipelex init config` creates a **template** configuration file with sample settings. It does not include all possible configuration options - it's meant as a starting point.
- 2. Running `pipelex init config` will **overwrite** your existing `pipelex.toml` file without warning. Make sure to backup your configuration before running this command.
+ 1. By default `pipelex init config` targets the **global** `~/.pipelex/` directory; pass `--local` to create the project-level `.pipelex/` instead.
+ 2. `pipelex init config` creates a **template** configuration file with sample settings. It does not include all possible configuration options - it's meant as a starting point.
+ 3. Running `pipelex init config` will **overwrite** your existing `pipelex.toml` file without warning. Make sure to backup your configuration before running this command.
+ 4. Credentials (`~/.pipelex/.env`) and the Gateway service-agreement file always remain in the global `~/.pipelex/` directory regardless of `--local` — only config, inference, and telemetry files are written to the project `.pipelex/`.
For a complete list of all possible configuration options, refer to the configuration group documentation below.
@@ -33,23 +36,25 @@ The main project configuration files are:
## Overrides (advanced)
-In addition to `.pipelex/pipelex.toml`, Pipelex can apply override files at the **project root** (not in `.pipelex/`) for machine- and environment-specific settings:
+In addition to the base `pipelex.toml`, Pipelex applies override files from **inside** each `.pipelex/` directory (both the global `~/.pipelex/` and the project's `.pipelex/`) for machine- and environment-specific settings:
1. `pipelex_local.toml`
2. `pipelex_{environment}.toml` (example: `pipelex_dev.toml`) — selected by the `PIPELEX_ENV` environment variable (see [Selecting the environment](#selecting-the-environment))
-3. `pipelex_{run_mode}.toml` (example: `pipelex_normal.toml`; unit tests may use `tests/pipelex_unit_test.toml`)
+3. `pipelex_{run_mode}.toml` (example: `pipelex_normal.toml`; unit tests use `tests/pipelex_unit_test.toml`, the one override file read outside a `.pipelex/` directory)
4. `pipelex_override.toml` (recommended to gitignore)
+5. `pipelex_temporary_override.toml` (recommended to gitignore)
!!! info "Contributor details"
For the full “where defaults live” and “how config is merged” explanation, see [Configuration Internals](../contribute/configuration-defaults-and-overrides.md).
## Configuration Structure
-The configuration is organized into three main sections:
+The configuration is organized into four main sections:
1. `[pipelex]` - Core Pipelex settings
2. `[cogt]` - Cognitive tools and LLM settings
3. `[plugins]` - Plugin-specific configurations
+4. `[migration]` - Migration helpers for renamed settings
Each section contains multiple subsections for specific features and functionalities.
@@ -57,23 +62,20 @@ Each section contains multiple subsections for specific features and functionali
Pipelex uses a sophisticated configuration override system that loads and merges configurations in a specific order. This allows for fine-grained control over settings in different environments and scenarios.
-The exact loading sequence is:
+The exact loading sequence is (later wins, per leaf key):
1. Base configuration from the installed Pipelex package (`pipelex.toml`)
-2. Your project's base configuration (`pipelex.toml` in your project root)
-3. Local overrides (`pipelex_local.toml`)
-4. Environment-specific overrides (`pipelex_{environment}.toml`)
- - Example environments: `local`, `dev`, `staging`, `prod` — selected by the `PIPELEX_ENV` environment variable (see [Selecting the environment](#selecting-the-environment))
-5. Run mode overrides (`pipelex_{run_mode}.toml`)
- - Example run modes: normal, unit_test
-6. Final overrides (`pipelex_override.toml`) (recommended to put in .gitignore)
-
-Each subsequent configuration file in this sequence can override settings from the previous ones. This means:
-
-- Settings in `pipelex_local.toml` override the base configuration
-- Environment-specific settings override local settings
-- Run mode settings override environment settings
-- Super user settings override all previous settings
+2. Global base configuration (`~/.pipelex/pipelex.toml`)
+3. Global override sequence, from `~/.pipelex/`: `pipelex_local.toml`, `pipelex_{environment}.toml`, `pipelex_{run_mode}.toml`, `pipelex_override.toml`, `pipelex_temporary_override.toml`
+4. Your project's base configuration (`{project_root}/.pipelex/pipelex.toml`)
+5. Project override sequence, from the project's `.pipelex/`: the same five files as step 3
+6. Programmatic overrides passed in code, if any
+
+Notes on the override sequence:
+
+- `pipelex_{environment}.toml` (example: `pipelex_dev.toml`) is selected by the `PIPELEX_ENV` environment variable (see [Selecting the environment](#selecting-the-environment))
+- `pipelex_{run_mode}.toml` — example run modes: normal, unit_test; under unit testing the run-mode overlay is sourced exclusively from `./tests/pipelex_{run_mode}.toml`
+- Each subsequent configuration file in this sequence can override settings from the previous ones, and project-level files override the global `~/.pipelex/` layer
### Override File Naming
diff --git a/docs/contribute/drift-contracts.md b/docs/contribute/drift-contracts.md
new file mode 100644
index 000000000..aec232d01
--- /dev/null
+++ b/docs/contribute/drift-contracts.md
@@ -0,0 +1,67 @@
+# Drift Contracts
+
+Drift contracts turn the "keep docs in sync with code" policy from advisory prose into a deterministic, mechanically-checked obligation. A **drift contract** declares: *when these trigger files change, these review targets must be re-examined against the change, and the examination must be recorded.* The tool cannot judge whether a doc is still correct — that takes a human or an agent — but it can prove, deterministically, that someone looked at this exact content and said so on the record.
+
+## The three synchronization tiers
+
+Not every code↔doc relationship deserves a review contract. This repo distinguishes three tiers, and a drift contract is the right tool only for the last one:
+
+| Tier | Mechanism | Judgment needed |
+|---|---|---|
+| **Derived** | Regenerate and diff: `check-config-sync`, `check-mthds-schema`, `check-gateway-models`, `generate-error-pages` | None — the output is a pure function of its sources |
+| **Linkage** | Referential integrity of declared cross-references (the spec/conformance `check-spec-links` pair) | None — links either resolve or they don't |
+| **Review** | Drift contracts: "this changed → that must be looked at, and the look recorded" | Yes — someone must judge whether the prose still holds |
+
+The standing rule: **anything mechanizable becomes a derived check.** If a review contract keeps opening and the review is always the same mechanical comparison, delete the contract and write a derived check instead — it needs no judgment and can't be rubber-stamped. The best review contract is one you eventually mechanize out of existence. Corollary: generated artifacts (`docs/errors/`, `derived/`, gateway model docs) must never appear in a contract's `review` list — reviewing generator *output* is how you end up editing generated files.
+
+## How it works
+
+Three pieces:
+
+- **`drift.toml`** (repo root, human-authored) declares the contracts: `triggers` (globs over tracked files), optional `exclude`, `review` targets, and optional `verify_commands`.
+- **`.drift/acks/<contract-id>.toml`** (tool-written, committed) records the last fulfilled review: a content digest, the reviewer, a timestamp, a rationale, and the per-file trigger snapshot.
+- **`pipelex-dev drift plan|check|ack`** computes obligations, checks them, and records acks. Make wrappers: `make drift-plan`, `make drift-check` (in the `make check` aggregate; in CI it currently runs as an **advisory** job that is visible on the PR but does not block merges — it will be promoted to a required check), `make drift-ack CONTRACT=… RATIONALE="…"`.
+
+The validity rule is a single equality, with no base ref, no git diff, and no timestamps:
+
+> A contract is **fulfilled** iff the stored ack digest equals the digest recomputed from the current tree. Otherwise it is **open**.
+
+The digest covers both the contract's own definition and the `(path, blob OID)` pairs of every tracked file matching its triggers — so editing a trigger file, adding or deleting a matched file, *or editing the contract itself* all open the contract. A brand-new contract has no ack, so it is open until its targets are reviewed once and acked: adoption is explicit, contract by contract.
+
+## The ack workflow
+
+When `make drift-check` fails (locally or in CI), run:
+
+```bash
+make drift-plan
+```
+
+It prints one Markdown packet per open contract: the description, exactly which trigger files were added/removed/modified since the last ack, the review targets, the verify commands, and the previous reviewer's rationale. To fulfill a contract:
+
+1. **Review the targets against the trigger changes.** Actually read them. Update whatever is stale. "Nothing to update" is a legitimate outcome — say so in the rationale.
+2. **Stage the trigger files:** `git add` them (staging is enough; you don't need to commit first, and other unstaged changes elsewhere are fine). **The digest is computed from the git index, not the working tree** — an unstaged edit or an untracked file is invisible to the ack, and `drift ack` warns when it sees one that matches the triggers.
+3. **Record the ack:**
+
+ ```bash
+ make drift-ack CONTRACT=config-docs RATIONALE="Documented the new activity_queues setting; other config pages unaffected."
+ ```
+
+ This first runs the contract's `verify_commands` (each one `shlex`-split and run without a shell, from the repo root; the first failure aborts the ack), then recomputes the digest from the index and writes the ack file.
+
+4. **Commit the ack file together with the change it covers.** The ack surfaces in the PR diff, so the reviewer sees the rationale next to the change — that is the audit trail.
+
+`reviewed_by` defaults from `git config user.name`; agents pass `BY=<identity>` (e.g. a model name or session URL). The rationale is required and is the on-the-record review decision — write an honest sentence, not "docs fine".
+
+## Why there is no bypass
+
+`drift ack` has no `--skip-verify`, and `drift check` has no override label. Every escape hatch here is a rubber-stamp invitation, and the legitimate escape already exists: acking with a rationale that says "no doc change needed" is cheap, honest, and auditable. If a contract opens so often that acking feels like ceremony, the contract is mis-scoped — narrow its triggers or mechanize it into a derived check; don't add a bypass.
+
+## Merges
+
+Two branches that each re-acked the same contract can produce a literal merge conflict in its ack file — but don't rely on that: a line-wise auto-merge can just as well splice the two acks into one that neither branch reviewed. The guarantee to rely on is different: **after the merge, `drift check` recomputes the digest over the merged tree**, and a spliced or stale ack simply fails the check, because the merged trigger content was never reviewed as a whole. Resolution is the same either way: finish the merge, review, then re-ack on the merged tree.
+
+## Manifest hygiene
+
+`drift check` hard-fails on manifest rot, not just open contracts: a trigger glob or review target matching zero tracked files, triggers fully shadowed by excludes, duplicate or malformed contract ids, an ack file with no matching contract, or an ack whose `contract` field disagrees with its filename. A rename that leaves a glob dead is caught on the same PR that should fix it — edit `drift.toml` first, then re-ack.
+
+Keep the manifest small. Contracts are added one at a time, where staleness has actually hurt; growth should follow pain, not tooling enthusiasm.
diff --git a/docs/contribute/keyword-only-arguments.md b/docs/contribute/keyword-only-arguments.md
index 9cfa49e78..ebf50af50 100644
--- a/docs/contribute/keyword-only-arguments.md
+++ b/docs/contribute/keyword-only-arguments.md
@@ -4,29 +4,67 @@ This is the canonical convention for keyword-only function parameters across the
## The rule
-A function or method must place a bare `*` separator in its signature so that every parameter after the subject is keyword-only. The compliant shape is:
+A function or method must place a bare `*` separator in its signature so that every parameter after the subject is keyword-only. The compliant shapes are:
```python
-def f(subject, *, opt1, opt2): ...
+def f(*, opt1, opt2): ... # fully keyword-only — always compliant, no registry entry needed
+def f(subject, *, opt1, opt2): ... # positional subject — compliant ONLY under a recorded subject grant
```
-The first non-`self`/`cls` parameter — the subject — stays positional-or-keyword. We deliberately do NOT use the positional-only `/` separator anywhere; the subject is allowed to be passed positionally or by keyword, at the caller's discretion.
+The first non-`self`/`cls` parameter — the subject — may stay positional-or-keyword **only when a subject grant for that def is recorded in `subject_grants.toml`** (see the next section). We deliberately do NOT use the positional-only `/` separator anywhere; a granted subject may be passed positionally or by keyword, at the caller's discretion.
-A signature is a violation when, after dropping a leading `self`/`cls` and the single allowed subject parameter, any positional-or-keyword parameter that is not already keyword-only remains. In other words, a function needs the bare `*` as soon as it would otherwise expose a *second* bare positional argument to callers: only the subject may be passed positionally, and everything after it must be named. Making the subject keyword-only too is always allowed — see Exception 1.
+A signature is a violation when any of these holds:
-## The two exceptions
+- **Missing bare `*`** — after dropping a leading `self`/`cls` and the subject, a positional-or-keyword parameter remains. Only the subject may ever be positional; everything after it must be named. So `def f(a, b)` and `def truncate(text, max_length=80)` are violations regardless of any grant.
+- **Ungranted subject** — the def keeps a positional subject (`def render(node)`, `def f(spec, *, opt)`) but no grant for it exists in the registry.
+- **Banned literal-typed subject** — the subject is annotated `bool`, `int`, or `float`, including their `Optional[X]` / `X | None` / `Union[X, None]` forms. This is a violation no matter what: a grant can never cover it, because call sites read as bare literals (`f(True)`, `retry(3)`) — exactly the opacity this convention exists to kill. `str` subjects remain grantable; they are the house style (`pipe_code`, `name`, `uri`, …). An unannotated subject is not provably literal and remains grantable.
+- **Stale grant** — a registry entry whose def no longer exists, whose recorded `param` no longer matches the def's subject, or whose def no longer has a positional subject at all (demoted, renamed, moved, or newly carved out). Staleness is symmetric and hard-fails: a rename or file move forces a deliberate re-grant, not silent rot.
-These two exceptions are part of the rule itself — they describe signatures that are compliant without a bare `*`.
+## Exception 1 — granted subject parameters
-### Exception 1 — the subject parameter
+> **History note — this exception was narrowed, deliberately.** Exception 1 used to be a *generic* permission: any first non-`self`/`cls` parameter could stay positional, guard-approved, no questions asked. That judgment-shaped permission was systematically abused by coding agents, which left first arguments positional when they were not the subject or not obviously so — the check passed, so the prose was ignored. The permission is now an **explicitly granted, recorded exception**: judgment still exists, but it happens at grant time and in review of the registry diff, while CI stays 100% deterministic. Agents follow checks, not prose — so the check now carries the whole rule.
-The first parameter after `self`/`cls` — the subject — *may* stay positional-or-keyword. This is a permission, not a requirement, and it exists for the same reason Swift lets you drop the first argument label with `_`: when the function name already designates what it acts on, naming the subject at the call site adds nothing (`render(node)`, `parse_blueprint(bp)`). A function with only a subject is compliant, and so is `def f(subject, *, opt1, opt2)` where every parameter after the subject is keyword-only.
+A def may keep its subject positional only under a **subject grant**: an entry in `subject_grants.toml` at the repo root, keyed by the def's stable identity (`<relative_path>::<qualified_name>`), recording the subject's parameter name and a one-sentence rationale:
-Making the subject keyword-only too is always allowed and is frequently the better choice — `def f(*, source, target)` is fully compliant and often more readable than leaning on a positional subject. The exception only *permits* a positional subject; it never forces one. What the rule forbids is a *second* positional parameter: as soon as a non-subject parameter would be passed positionally, the bare `*` is required. So `def f(a, b)` and `def truncate(text, max_length=80)` are violations (`def f(a, *, b)`, `def truncate(text, *, max_length=80)`), while `def render(node)` and `def f(*, a, b)` are both fine.
+```toml
+version = 1
-### Exception 2 — symmetric tuples (explicit allowlist only)
+["pipelex/graph/render.py::render_node"]
+param = "node"
+rationale = "Verb–object: renders the node; single obvious operand."
+```
+
+The registry is machine-written and sorted by key, so diffs stay stable and merge conflicts resolve trivially. It is written **only** by the grant command; never edit it by hand except to delete a stale entry:
+
+```bash
+make subject-grant FUNC="pipelex/graph/render.py::render_node" RATIONALE="Verb–object: renders the node; single obvious operand."
+# alias: make sgr — wraps: pipelex-dev subject-grant "<path>::<qualname>" --rationale "…"
+```
+
+The command validates the def (it must exist, be inspected by the guard, and have a positional non-literal-typed subject), records the `param` automatically, and rewrites the file sorted. It refuses literal-typed subjects, fully-keyword-only defs, carved-out defs, and empty rationales. Same-qualname defs (`@overload` stubs, conditional redefinitions) share one entry — the recorded `param` must match each of them, which forces overload stubs to align their subject name.
+
+### What earns a grant — the rubric
+
+A subject grant is warranted when EITHER:
+
+- **Verb–object test:** the function name is a verb (phrase) and the param is its direct object — the call reads as a sentence (`render(node)`, `validate_bundle(bundle)`, `parse_concept_spec(spec_data)`) — AND it is the **single candidate** (if you hesitate between two params, neither is the subject) — AND typical call sites pass a **self-labelling expression**, never a bare literal (literal-typed subjects are banned outright anyway);
+- OR the def must satisfy a **positional `Callable` protocol** (it is passed as a value to something that calls it positionally) and a grant keeps it compliant without reaching for the heavier `# kw-only: ignore`.
+
+When in doubt → keyword-only. The grant is the exception tier; all-keyword is always compliant and often more readable. Rationales must be def-specific but may be terse for obvious keeps ("verb–object; single operand") — the value is that someone actually looked; copy-paste boilerplate across dozens of entries defeats the point.
+
+The grant is a permission, not a requirement — making the subject keyword-only too is always allowed, needs no registry entry, and is frequently the better choice. The economics are intentional: `make fko` mechanically produces the all-keyword form, so the lazy path is the strict path; keeping a positional subject costs a deliberate command with an honest rationale, visible as a registry diff in every PR.
+
+### Staleness is symmetric
-A small set of functions take a short, conventionally-ordered tuple of arguments where positional calling is the universally-understood form and naming would be pure noise: `clamp(value, low, high)`, `Point(x, y)`, `replace(text, old, new)`, `lerp(a, b, t)`, `set_env(key, value)`. These are exempt ENTIRELY — the whole function, including any trailing options — but ONLY via an explicit allowlist keyed by qualified name and file. There is no pattern-based guessing: a function is symmetric-tuple-exempt if and only if it is listed in the allowlist. This keeps the carve-out auditable and prevents the exemption from quietly swallowing genuine subject-plus-options signatures, which are the main thing this refactor wants to fix.
+The guard verifies the registry in both directions on every run: a positional subject without a grant fails, and a grant without a matching def fails (`dead-grant`), as does a grant whose recorded `param` no longer matches the def's subject (`grant-param-mismatch`). Renames, file moves, demotions to all-keyword, and newly added carve-outs (`@override`, framework decorators) all kill the grant — delete the entry or re-grant deliberately. A missing or malformed `subject_grants.toml` is an explicit check error, never treated as an empty registry (that would mass-flag every granted subject in the tree).
+
+### Registry schema
+
+A registry entry carries exactly two keys — `param` and `rationale`; anything else fails the check. When the registry was introduced, every pre-existing positional subject entered a transitional review grind (treated as new, not grandfathered); that transition is over — every grant now carries a genuine, def-specific review rationale. `pipelex-dev check-keyword-only --report` shows the full inventory and the per-package grant counts.
+
+## Exception 2 — symmetric tuples (explicit allowlist only)
+
+A small set of functions take a short, conventionally-ordered tuple of arguments where positional calling is the universally-understood form and naming would be pure noise: `clamp(value, low, high)`, `Point(x, y)`, `replace(text, old, new)`, `lerp(a, b, t)`, `set_env(key, value)`. These are exempt ENTIRELY — the whole function, including any trailing options — but ONLY via an explicit allowlist keyed by qualified name and file, curated in the guard's source (NOT in `subject_grants.toml` — the registry covers single subjects; the allowlist exempts whole functions, a different semantic). There is no pattern-based guessing: a function is symmetric-tuple-exempt if and only if it is listed in the allowlist. This keeps the carve-out auditable and prevents the exemption from quietly swallowing genuine subject-plus-options signatures, which are the main thing this convention wants to fix.
The curated allowlist is intentionally short. Each entry is a genuine ordered tuple under a well-known convention, not a subject followed by descriptive options.
@@ -39,7 +77,7 @@ The curated allowlist is intentionally short. Each entry is a genuine ordered tu
The operating rule for two-operand functions — when only one of the operand-positional and the all-keyword form should win:
- **A clean symmetric/ordered pair with NO trailing options** may go on the allowlist and stay fully positional (the entries above). Order is either irrelevant (`are_classes_equivalent`) or universally understood (`diff_files`'s `1`/`2`).
-- **A pair that also carries trailing options** is reshaped to fully keyword-only instead — the whole-function allowlist is all-or-nothing, so it cannot keep the pair positional while forcing the options keyword, and letting the options go positional is exactly the unreadable case this refactor targets. Examples now keyword-only: `copy_file(*, source_path, target_path, overwrite=True)`, `mirror_dir(*, source_dir, target_dir, …)`, `sync_toml_values(*, source_path, target_path, dry_run=False)`, `has_diff_dirs(*, dir1, dir2, exclude_files=None, exclude_dirs=None)`, `is_multiplicity_compatible(*, source_multiplicity, target_multiplicity)`, the graph tracer's `add_edge(*, source_node_id, target_node_id, edge_kind, …)`.
+- **A pair that also carries trailing options** is reshaped to fully keyword-only instead — the whole-function allowlist is all-or-nothing, so it cannot keep the pair positional while forcing the options keyword, and letting the options go positional is exactly the unreadable case this convention targets. Examples now keyword-only: `copy_file(*, source_path, target_path, overwrite=True)`, `mirror_dir(*, source_dir, target_dir, …)`, `sync_toml_values(*, source_path, target_path, dry_run=False)`, `has_diff_dirs(*, dir1, dir2, exclude_files=None, exclude_dirs=None)`, `is_multiplicity_compatible(*, source_multiplicity, target_multiplicity)`, the graph tracer's `add_edge(*, source_node_id, target_node_id, edge_kind, …)`.
This deliberately keeps the allowlist whole-function (no per-entry "leading positional count" machinery): the handful of pairs that would benefit from staying positional-with-keyword-options are rare enough that reshaping to all-keyword is the simpler, uniform answer.
@@ -47,7 +85,7 @@ Adding to the allowlist is a deliberate act: the entry must name a genuine order
## Carve-outs (skipped entirely)
-Carve-outs are different from exceptions: a carved-out def is never inspected at all, regardless of its parameter shape. These are signatures the guard cannot or must not touch because some framework or the interpreter itself owns the calling convention.
+Carve-outs are different from exceptions: a carved-out def is never inspected at all, regardless of its parameter shape — it neither needs a subject grant nor can hold one alive. These are signatures the guard cannot or must not touch because some framework or the interpreter itself owns the calling convention.
### Dunder and operator methods
@@ -64,7 +102,7 @@ A def decorated with any of these pydantic decorator names is skipped, because p
- `validator` (pydantic v1 legacy)
- `root_validator` (pydantic v1 legacy)
-Only `field_validator`, `model_validator`, and `model_serializer` are actually used in the source today; the v1 legacy names and `field_serializer` are included defensively so the guard stays correct if they are introduced later. Decorators may be call-form (`@field_validator("name", mode="before")`) or bare (`@model_serializer`); the guard handles both by unwrapping `ast.Call.func` when present and matching on the unqualified decorator name. The `parse_model_reference` helper referenced via `Annotated[..., BeforeValidator(parse_model_reference)]` is NOT a decorated def — it is a plain single-parameter module function, already compliant under the single-parameter rule, and needs no carve-out.
+Only `field_validator`, `model_validator`, and `model_serializer` are actually used in the source today; the v1 legacy names and `field_serializer` are included defensively so the guard stays correct if they are introduced later. Decorators may be call-form (`@field_validator("name", mode="before")`) or bare (`@model_serializer`); the guard handles both by unwrapping `ast.Call.func` when present and matching on the unqualified decorator name. The `parse_model_reference` helper referenced via `Annotated[..., BeforeValidator(parse_model_reference)]` is NOT a decorated def — it is a plain single-parameter module function (whose lone subject needs a grant like any other), and needs no carve-out.
### Framework entrypoints
@@ -72,7 +110,7 @@ A def is skipped when it is registered with a framework whose calling convention
- Typer/click commands and callbacks — any decorator that is an attribute access ending in `.command` or `.callback`. The guard scans the WHOLE decorator stack for a framework match (a framework decorator may sit above a custom one such as `@convert_pipelex_errors`), not just the innermost or outermost decorator.
- pytest fixtures — `fixture`, matched on the bare decorator name so both `@pytest.fixture` and bare `@fixture` (`from pytest import fixture`) are covered (the only src-side fixtures live in the shipped `pipelex/test_extras/shared_pytest_plugins.py` plugin module).
-- Jinja2 filters/tests/globals — `pass_context`, `pass_environment`, `pass_eval_context`, matched on the bare decorator name (covers both `@pass_context` from `from jinja2 import pass_context` and the attributed `@jinja2.pass_context`). The Jinja2 engine invokes a filter POSITIONALLY from template syntax — `{{ value | tag("name") }}` calls `tag(context, value, "name")` — so the wrapped callable's arguments cannot be made keyword-only. This is the same framework-entrypoint category as Typer/pytest. A multi-argument filter without one of these decorators (rare) is covered by the `# kw-only: ignore` escape hatch; single-argument filters (`escape_script_tag(value)`) are compliant under the single-parameter rule and need nothing.
+- Jinja2 filters/tests/globals — `pass_context`, `pass_environment`, `pass_eval_context`, matched on the bare decorator name (covers both `@pass_context` from `from jinja2 import pass_context` and the attributed `@jinja2.pass_context`). The Jinja2 engine invokes a filter POSITIONALLY from template syntax — `{{ value | tag("name") }}` calls `tag(context, value, "name")` — so the wrapped callable's arguments cannot be made keyword-only. This is the same framework-entrypoint category as Typer/pytest. A multi-argument filter without one of these decorators (rare) is covered by the `# kw-only: ignore` escape hatch; single-argument filters (`escape_script_tag(value)`) have an ordinary lone subject and take a grant like any other def.
FastAPI is intentionally absent: there are no route handlers in `pipelex/` source — the FastAPI server lives in the separate `pipelex-api/` repo.
@@ -86,45 +124,51 @@ A def decorated with `@override` (from `typing_extensions` / `typing`) is skippe
DECISION: skip any def carrying an `@override` decorator. We do NOT introduce a dedicated `@kw_exempt` decorator for overrides, and we do NOT attempt base-aware (import-resolving / type-inferring) detection.
-Rationale. An overriding method cannot freely re-shape its signature — it must stay compatible with the base/Protocol it implements — so the correct place to apply the keyword-only convention is the base definition, after which implementations inherit the contract and pyright's `reportIncompatibleMethodOverride` keeps them in line. Skipping `@override` defs is consistent with fixing the base. Crucially, `@override` is a reliable AND complete signal here: `pyproject.toml` sets `reportImplicitOverride = true`, so any method overriding a nominal base MUST carry `@override` or `make agent-check` already fails before the keyword-only guard runs — the marker cannot silently rot. Protocol implementations are structural and not forced by that setting, but house style applies `@override` to them consistently too; the residual risk is a hypothetical future Protocol implementor that forgets `@override`, which is already a style deviation the team avoids and is covered by the inline escape hatch below. A `@kw_exempt` decorator would duplicate semantics `@override` already carries and add a second redundant annotation to dozens of override sites for no gain. Base-aware detection would require import resolution a pure-AST guard cannot do reliably, and the codebase has already solved the problem for us via `reportImplicitOverride`. The guard matches `@override` structurally: a decorator that is an `ast.Name` with `id == "override"` or an `ast.Attribute` with `attr == "override"`, covering both `override` and `typing_extensions.override` without resolving imports.
+Rationale. An overriding method cannot freely re-shape its signature — it must stay compatible with the base/Protocol it implements — so the correct place to apply the keyword-only convention (and to record the subject grant, when the base keeps a positional subject) is the base definition, after which implementations inherit the contract and pyright's `reportIncompatibleMethodOverride` keeps them in line. Skipping `@override` defs is consistent with fixing the base. Crucially, `@override` is a reliable AND complete signal here: `pyproject.toml` sets `reportImplicitOverride = true`, so any method overriding a nominal base MUST carry `@override` or `make agent-check` already fails before the keyword-only guard runs — the marker cannot silently rot. Protocol implementations are structural and not forced by that setting, but house style applies `@override` to them consistently too; the residual risk is a hypothetical future Protocol implementor that forgets `@override`, which is already a style deviation the team avoids and is covered by the inline escape hatch below. A `@kw_exempt` decorator would duplicate semantics `@override` already carries and add a second redundant annotation to dozens of override sites for no gain. Base-aware detection would require import resolution a pure-AST guard cannot do reliably, and the codebase has already solved the problem for us via `reportImplicitOverride`. The guard matches `@override` structurally: a decorator that is an `ast.Name` with `id == "override"` or an `ast.Attribute` with `attr == "override"`, covering both `override` and `typing_extensions.override` without resolving imports.
## Inline escape hatch
-A `# kw-only: ignore` comment on the `def` line (or the `async def` line) suppresses exactly one violation for that function. This is the documented fallback for the rare legitimate case the carve-outs and allowlist do not cover — for example a Protocol implementor that genuinely lacks `@override`, or a one-off signature whose positional shape is justified and does not merit a permanent allowlist entry. The escape hatch is the exception, not the mechanism: the carve-outs and the `@override` skip are expected to handle the vast majority of legitimate non-compliant signatures, and a reviewer seeing `# kw-only: ignore` should expect a short justification nearby. The marker is matched against the comment text on the def line; it suppresses the single def it sits on, not a whole class or module.
+A `# kw-only: ignore` comment on the `def` line (or the `async def` line) suppresses exactly one violation for that function — it short-circuits everything, including the subject-grant rules and the literal-subject ban. This is the documented fallback for the rare legitimate case the carve-outs and allowlist do not cover: chiefly a def some framework invokes positionally without a recognizable decorator (a `typer.Option(callback=...)` target like `version_callback(value: bool)`, an `__import__` hook, an SDK error callback), or a Protocol implementor that genuinely lacks `@override`. The escape hatch is the exception, not the mechanism: a reviewer seeing `# kw-only: ignore` should expect a short justification nearby. The marker is matched against the comment text on the def line; it suppresses the single def it sits on, not a whole class or module.
## Worked examples
-A subject plus options — the canonical thing this refactor fixes:
+A subject plus options — the canonical shape, legal only with a grant:
```python
-# before — opaque at the call site: build_pipe(my_spec, True, 3, False)
-def build_pipe(spec, dry_run, retries, validate): ...
-
-# after — self-documenting: build_pipe(my_spec, dry_run=True, retries=3, validate=False)
-def build_pipe(spec, *, dry_run, retries, validate): ...
+# subject_grants.toml carries: ["pipelex/builder/build.py::build_pipe"] param = "spec" rationale = "…"
+def build_pipe(spec, *, dry_run, retries, validate): ... # build_pipe(my_spec, dry_run=True, retries=3, validate=False)
```
-A single subject and nothing else — compliant; the subject may be passed positionally:
+A single subject and nothing else — needs a grant too (strict-all scope; lone-subject defs are not implicitly exempt):
```python
-def render(node): ... # render(my_node)
+def render(node): ... # render(my_node) — granted: verb–object, single operand
```
-All parameters named, including the first — always compliant, and often the most readable choice:
+All parameters named, including the first — always compliant, no registry entry, and often the most readable choice:
```python
def copy_payload(*, source, target): ... # copy_payload(source=a, target=b)
```
-Even a single defaulted option must be named — this is the common case the refactor fixes, not an exception to it:
+Even a single defaulted option must be named — this is the common case the convention fixes, not an exception to it:
```python
# before: truncate(text, 120) — what does 120 mean?
def truncate(text, max_length=80): ...
-# after: truncate(text, max_length=120)
+# after: truncate(text, max_length=120) — with a grant for `text`, or fully keyword-only with none
def truncate(text, *, max_length=80): ...
```
+A literal-typed subject — banned outright, no grant possible; make it keyword-only:
+
+```python
+# before: doctor_cmd(True) — reads as a bare literal
+def doctor_cmd(fix: bool): ...
+# after: doctor_cmd(fix=True)
+def doctor_cmd(*, fix: bool): ...
+```
+
A symmetric tuple on the allowlist — exempt entirely, stays positional:
```python
@@ -142,11 +186,11 @@ def copy_file(*, source_path, target_path, overwrite=True): ...
A clean symmetric pair with no trailing options is the opposite case — it goes on the Exception 2 allowlist and stays fully positional (`are_classes_equivalent(class_1, class_2)`).
-An override — skipped because of `@override`; fix the base signature instead:
+An override — skipped because of `@override`; fix (and grant) the base signature instead:
```python
@override
-def _store(self, data, *, key, content_type): ... # base StorageProviderAbstract._store defines the kw-only contract
+def _store(self, data, *, key, content_type): ... # base StorageProviderAbstract._store defines the contract and holds any grant
```
A dunder — skipped by name; the interpreter owns the calling convention:
@@ -164,35 +208,46 @@ def normalize(cls, value, info): ...
## Enforcement
-The entire `pipelex/` source tree is compliant, so the guard hard-blocks on **any** violation — there is no baseline and no tolerated debt. The guard runs at several gates:
+The entire `pipelex/` source tree is compliant, so the guard hard-blocks on **any** violation — there is no baseline and no tolerated debt. Each violation kind names its own remedy in the check output:
+
+| Kind | Meaning | Remedy |
+|---|---|---|
+| `missing-star` | a non-subject positional-or-keyword param remains | place the bare `*` (or `make fko`) |
+| `ungranted-subject` | positional subject with no registry entry | `make fko` to go all-keyword, or `make subject-grant` |
+| `literal-subject` | `bool`/`int`/`float` subject (incl. Optional/union-with-None) | make it keyword-only — grants are impossible |
+| `grant-param-mismatch` | the grant's recorded `param` no longer matches the def | re-grant, or fix the registry |
+| `dead-grant` | the grant matches no def with a positional subject | delete the entry (or re-grant after a rename/move) |
+
+The guard runs at several gates:
-- A Claude Code `PostToolUse` hook (`.claude/hooks/check-keyword-only.sh`, wired in `.claude/settings.json`) — the tightest loop. After every `Edit`/`Write`/`MultiEdit` of a `pipelex/**/*.py` file it checks just that file and blocks with the offending signatures if it regressed, so an agent learns at edit time rather than at the end of the session. It runs the stdlib-only core by file path (no Typer/hub import), so it costs a few tens of milliseconds. The hook is check-only — it never rewrites a file mid-edit.
-- `make agent-check` — the fast everyday gate. It runs the **auto-fixing** variant (`fix-keyword-only`) early, right after `fix-unused-imports` and before `ruff format`, so a mechanically-fixable violation is corrected in place instead of failing the build. The fixer is **non-gating** — it reports the violations it can't mechanically fix but does not abort — so `format`, `lint`, `pyright`, and `mypy` all still run (you get keyword-only *and* type feedback in a single pass, and the tree is never left half-mutated and unformatted). The **read-only** `check-keyword-only` then runs **last** and is what actually blocks on any remaining violation.
+- A Claude Code `PostToolUse` hook (`.claude/hooks/check-keyword-only.sh`, wired in `.claude/settings.json`) — the tightest loop. After every `Edit`/`Write`/`MultiEdit` of a `pipelex/**/*.py` file it checks just that file and blocks with the offending signatures if it regressed, so an agent learns at edit time rather than at the end of the session. It runs the stdlib-only core by file path (no Typer/hub import), so it costs a few tens of milliseconds — including one `tomllib` read of the registry. The hook is check-only — it never rewrites a file mid-edit. It cannot see registry-level staleness (dead grants are a full-scan concern); the full check owns those.
+- `make agent-check` — the fast everyday gate. It runs the **auto-fixing** variant (`fix-keyword-only`) early, right after `fix-unused-imports` and before `ruff format`, so a mechanically-fixable violation is corrected in place instead of failing the build. The fixer is **non-gating** — it reports the violations it can't mechanically fix but does not abort — so `format`, `lint`, `pyright`, and `mypy` all still run (you get keyword-only *and* type feedback in a single pass, and the tree is never left half-mutated and unformatted). The **read-only** `check-keyword-only` then runs **last** and is what actually blocks on any remaining violation. ⚠ Note the fixer's reach: an **ungranted subject def is a violation**, so `make agent-check` will silently keyword-only it — record the grant BEFORE running checks if you want the subject to stay positional.
- `make check` — the heavy aggregate gate. It runs the **check-only** `check-keyword-only` (no rewriting), so CI-equivalent runs stay read-only.
-- CI — a dedicated lint job (`lint-keyword-only` in `.github/workflows/lint-check.yml`) gated by the required `Lint (all)` status check, so no non-compliant signature can merge. This is the hard guarantee; the hook and `make` gates are local conveniences layered on top.
+- CI — a dedicated lint job (`lint-keyword-only` in `.github/workflows/lint-check.yml`) gated by the required `Lint (all)` status check, so no non-compliant signature can merge. This is the hard guarantee; the hook and `make` gates are local conveniences layered on top. The registry diff in the PR is where grant judgment gets reviewed.
-When you add or change a signature, place the bare `*` after the subject — or run `make fix-keyword-only` (alias `fko`) to insert it automatically. If the type checker is blind to how a function is called (a framework or the interpreter invokes it positionally — a Jinja2 filter, an `__import__` hook, an aiohttp route handler, a PostHog `on_error` callback), the guard cannot detect that statically; the carve-outs above cover the known cases, and a genuinely justified one-off uses the `# kw-only: ignore` escape hatch. `make agent-test` is the safety net for these dynamic call surfaces — pyright/mypy will pass a wrongly-keywordized callback that the suite then catches at runtime.
+When you add or change a signature, place the bare `*` after the subject and grant the subject (or make everything keyword-only — no grant needed). If the type checker is blind to how a function is called (a framework or the interpreter invokes it positionally — a Jinja2 filter, an `__import__` hook, an aiohttp route handler, a PostHog `on_error` callback), the guard cannot detect that statically; the carve-outs above cover the known cases, and a genuinely justified one-off uses the `# kw-only: ignore` escape hatch. `make agent-test` is the safety net for these dynamic call surfaces — pyright/mypy will pass a wrongly-keywordized callback that the suite then catches at runtime.
## Auto-fix
-`pipelex-dev check-keyword-only --fix` (exposed as `make fix-keyword-only` / `fko`, and run automatically inside `make agent-check`) rewrites every *mechanically-fixable* violation by inserting a bare `*` as far left as possible — immediately after `self`/`cls` (and after any `/`) — so **every** non-`self`/`cls` parameter becomes keyword-only, not just the ones after the subject: `def f(a, b)` becomes `def f(*, a, b)`, `def m(self, a, b)` becomes `def m(self, *, a, b)`. (The exception that lets the subject stay positional is a permission, not a requirement — the fixer takes the always-allowed, more explicit form.) The raw insert lands on the def's original line(s); the `make fix-keyword-only` / `fko` target runs `ruff format` right after the rewrite, so the standalone path leaves a `ruff format`-clean tree (inside `agent-check` the later `format` step would normalize it anyway). The rewrite is idempotent and is re-parsed before being written — a rewrite that would not parse is discarded and the violation reported instead.
+`pipelex-dev check-keyword-only --fix` (exposed as `make fix-keyword-only` / `fko`, and run automatically inside `make agent-check`) rewrites every *mechanically-fixable* violation by inserting a bare `*` as far left as possible — immediately after `self`/`cls` (and after any `/`) — so **every** non-`self`/`cls` parameter becomes keyword-only, not just the ones after the subject: `def f(a, b)` becomes `def f(*, a, b)`, `def m(self, a, b)` becomes `def m(self, *, a, b)`, and an ungranted `def render(node)` becomes `def render(*, node)`. (The all-keyword form is always compliant and needs no grant — the fixer takes it.) `missing-star`, `ungranted-subject`, and `literal-subject` violations are all fixable this way; a `grant-param-mismatch` is never rewritten — a stale grant is a registry decision, not a signature to silently change. The raw insert lands on the def's original line(s); the `make fix-keyword-only` / `fko` target runs `ruff format` right after the rewrite, so the standalone path leaves a `ruff format`-clean tree (inside `agent-check` the later `format` step would normalize it anyway). The rewrite is idempotent and is re-parsed before being written — a rewrite that would not parse is discarded and the violation reported instead.
A few shapes the guard flags cannot be fixed by a single bare-`*` insert, and are reported for a manual fix rather than rewritten:
- a `*args` is present — the parameters before it cannot be made keyword-only by a bare `*`, and a bare `*` cannot coexist with `*args`;
-- a keyword-only section already exists (a bare `*` is already in the signature, with a positional parameter still ahead of it) — the existing `*` must be moved by hand, since a second one is a syntax error;
-- two or more positional-only parameters (before a `/`, excluding a leading `self`/`cls`) remain — a bare `*` cannot precede the `/`, so they stay positional and the single permitted positional subject is not enough to reach compliance. (A *single* positional-only subject is still auto-fixable: the `*` goes right after the `/`, e.g. `def f(a, /, b, c)` → `def f(a, /, *, b, c)`.)
+- a keyword-only section already exists (a bare `*` is already in the signature, with a positional parameter still ahead of it) — the existing `*` must be moved by hand, since a second one is a syntax error. This includes the common `def f(subject, *, opt)` shape when the subject is ungranted or literal-typed;
+- two or more positional-only parameters (before a `/`, excluding a leading `self`/`cls`) remain — a bare `*` cannot precede the `/`, so they stay positional and cannot reach compliance mechanically. (A *single* positional-only subject still gets the `*` after the `/`, e.g. `def f(a, /, b, c)` → `def f(a, /, *, b, c)` — but the positional-only subject itself then still needs a grant or the `/` removed by hand.)
The `--fix` path is **non-gating**: it mutates and reports, but never exits non-zero on the violations it couldn't fix. The read-only `check-keyword-only` (no flag) owns the gating — it runs last in `agent-check` and is the variant `make check` / CI use. So `make fko` fixes what it can and prints the rest without failing your shell; run `make check-keyword-only` (alias `cko`) when you want the pass/fail gate. This split is deliberate: a tree-mutating step shouldn't also be the hard gate, or an abort could leave files rewritten-but-unformatted and mask the type-check phase.
-Auto-fix is not a substitute for review: the guard is blind to framework-positional callers (see the safety-net note above), so a signature it "fixes" might be one some framework invokes positionally. `make agent-test` remains the safety net — verify after a bulk auto-fix.
+Auto-fix is not a substitute for review: the guard is blind to framework-positional callers (see the safety-net note above), so a signature it "fixes" might be one some framework invokes positionally. And a fixed `ungranted-subject` def might have *deserved* its positional subject — if so, revert the def and record the grant instead. `make agent-test` remains the safety net — verify after a bulk auto-fix.
Run the guard directly to see the full picture:
```bash
-make check-keyword-only # alias: make cko — one line on pass, the full violation list on fail
+make check-keyword-only # alias: make cko — one line on pass, the per-kind violation list on fail
make fix-keyword-only # alias: make fko — auto-insert the bare `*`; reports any manual-fix cases
-.venv/bin/pipelex-dev check-keyword-only --report # full inventory grouped by package
+make subject-grant FUNC="pipelex/….py::qualname" RATIONALE="…" # alias: make sgr — record a subject grant
+.venv/bin/pipelex-dev check-keyword-only --report # full inventory by package + per-package grant counts
.venv/bin/pipelex-dev check-keyword-only --fix # auto-fix (what `make fko` runs)
# Lean single-file check (what the PostToolUse hook runs): stdlib only, invoked by file path so it
diff --git a/docs/errors/drift-ack-error.md b/docs/errors/drift-ack-error.md
new file mode 100644
index 000000000..b46806857
--- /dev/null
+++ b/docs/errors/drift-ack-error.md
@@ -0,0 +1,21 @@
+---
+title: "Drift ack"
+description: "Reference for the `DriftAckError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Drift ack
+
+Raised when an ack file is invalid or an ack operation cannot proceed.
+
+| Field | Value |
+|---|---|
+| `error_type` | `DriftAckError` |
+| `title` | Drift ack |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/drift-ack-error/` |
+| `error_domain` | _(inherited from parent)_ |
+| Defined in | `pipelex.cli.dev_cli.commands.drift.exceptions` |
+| Parent class | [`DriftError`](drift-error.md) |
+
+[Back to Error Reference](index.md)
diff --git a/docs/errors/drift-error.md b/docs/errors/drift-error.md
new file mode 100644
index 000000000..c9556820a
--- /dev/null
+++ b/docs/errors/drift-error.md
@@ -0,0 +1,21 @@
+---
+title: "Drift"
+description: "Reference for the `DriftError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Drift
+
+Base error for the drift-contracts tooling.
+
+| Field | Value |
+|---|---|
+| `error_type` | `DriftError` |
+| `title` | Drift |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/drift-error/` |
+| `error_domain` | _(inherited from parent)_ |
+| Defined in | `pipelex.cli.dev_cli.commands.drift.exceptions` |
+| Parent class | [`PipelexCLIError`](pipelex-cli-error.md) |
+
+[Back to Error Reference](index.md)
diff --git a/docs/errors/drift-git-error.md b/docs/errors/drift-git-error.md
new file mode 100644
index 000000000..8fe442498
--- /dev/null
+++ b/docs/errors/drift-git-error.md
@@ -0,0 +1,21 @@
+---
+title: "Drift git"
+description: "Reference for the `DriftGitError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Drift git
+
+Raised when a git plumbing call needed by drift fails.
+
+| Field | Value |
+|---|---|
+| `error_type` | `DriftGitError` |
+| `title` | Drift git |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/drift-git-error/` |
+| `error_domain` | _(inherited from parent)_ |
+| Defined in | `pipelex.cli.dev_cli.commands.drift.exceptions` |
+| Parent class | [`DriftError`](drift-error.md) |
+
+[Back to Error Reference](index.md)
diff --git a/docs/errors/drift-manifest-error.md b/docs/errors/drift-manifest-error.md
new file mode 100644
index 000000000..2f763409e
--- /dev/null
+++ b/docs/errors/drift-manifest-error.md
@@ -0,0 +1,21 @@
+---
+title: "Drift manifest"
+description: "Reference for the `DriftManifestError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Drift manifest
+
+Raised when drift.toml is missing, unparseable, or schema-invalid.
+
+| Field | Value |
+|---|---|
+| `error_type` | `DriftManifestError` |
+| `title` | Drift manifest |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/drift-manifest-error/` |
+| `error_domain` | _(inherited from parent)_ |
+| Defined in | `pipelex.cli.dev_cli.commands.drift.exceptions` |
+| Parent class | [`DriftError`](drift-error.md) |
+
+[Back to Error Reference](index.md)
diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.md
index 764a19bbb..6c07d427b 100644
--- a/docs/tools/cli/agent-cli.md
+++ b/docs/tools/cli/agent-cli.md
@@ -12,10 +12,11 @@ It is consumed by the `mthds-agent` CLI (from the `mthds` npm package) which its
| Option | Description |
|--------|-------------|
-| `--log-level` | Set the logging level (e.g., `debug`, `info`, `warning`, `error`) |
-| `--runner` | Select the runner backend to use |
+| `--runner` | Select the runner backend to use (`pipelex` or `api`) |
| `--version` | Print the version and exit |
+There is no `--log-level` flag: `pipelex-agent` is machine-consumed, so logging is cut off process-wide by design.
+
## Commands Overview
The agent CLI mirrors the main CLI's subcommand structure for `run`, `validate`, and `inputs`, each with `pipe`, `bundle`, and `method` subcommands. It also provides `fix bundle` for deterministic in-place repairs.
@@ -74,10 +75,10 @@ For `bundle`, additional options are available:
!!! note "Signature pipes"
`pipelex-agent validate` is strict by default — same as `pipelex validate`. A bundle whose dependency graph reaches a `PipeSignature` is rejected unless you pass `--allow-signatures`, which dry-runs signatures as mocks.
- On a successful `validate bundle` run, the envelope also carries `pending_signatures` — the library-wide list of pipes still declared as `PipeSignature` (unimplemented forward declarations), each namespaced by `pipe_ref` (`domain.code`). It is a non-blocking nudge: in JSON it is a `pending_signatures` array, in markdown a "Pending signatures" section. A top-down build reads it to see exactly which headers remain to implement. The envelope also carries a derived `is_runnable` boolean (`true` ⇔ `pending_signatures` is empty), and the markdown states the runnability verdict in plain English — runnable when complete, NOT yet runnable above the "Pending signatures" section otherwise. Both are scoped to `validate bundle`; `validate all` / `validate pipe` omit them.
+ On a successful run, the envelope also carries `pending_signatures` — the library-wide list of pipes still declared as `PipeSignature` (unimplemented forward declarations), each namespaced by `pipe_ref` (`domain.code`). In JSON it is a `pending_signatures` array, in markdown a "Pending signatures" section. A top-down build reads it to see exactly which headers remain to implement. The envelope also carries a derived `is_runnable` boolean (`true` ⇔ `pending_signatures` is empty), and the markdown states the runnability verdict in plain English — runnable when complete, NOT yet runnable above the "Pending signatures" section otherwise. `validate bundle`, `validate method`, and `validate pipe --all` carry them and gate on them: without `--allow-signatures`, the command exits non-zero when `is_runnable` is false. Bare `validate pipe <code>` omits them, and a `--pipe` slice surfaces them for information without gating.
!!! note "Advisory warnings on validate"
- Whole-bundle validate surfaces (`validate bundle`, `validate method`) also carry a `warnings` array — advisory optionality lints on a VALID bundle that never flip the verdict or the exit code. Each entry has the **same shape as a validation error item** (`category`, `error_type`, `pipe_code`, `domain_code`, `variable_names`, `message`) — this is a different shape from the `init`/`doctor` setup `warnings` (`{type, message}`) documented under Output Contract below. The first occupant is the useless-`!` lint (`optional_force_redundant`): a `!` (force) input whose slot is guaranteed present in every analyzed flow, so the assertion can never fire. In markdown, warnings render as a "Warnings" section. The array is empty when there is nothing to report; single-pipe `validate pipe` omits it (no flow context to lint in).
+ Whole-bundle and whole-library validate surfaces (`validate bundle`, `validate method`, `validate pipe --all`) also carry a `warnings` array — advisory optionality lints on a VALID bundle that never flip the verdict or the exit code. Each entry has the **same shape as a validation error item** (`category`, `error_type`, `pipe_code`, `domain_code`, `variable_names`, `message`) — this is a different shape from the `init`/`doctor` setup `warnings` (`{type, message}`) documented under Output Contract below. The first occupant is the useless-`!` lint (`optional_force_redundant`): a `!` (force) input whose slot is guaranteed present in every analyzed flow, so the assertion can never fire. In markdown, warnings render as a "Warnings" section. The array is empty when there is nothing to report; single-pipe `validate pipe` omits it (no flow context to lint in).
### Fix
diff --git a/docs/tools/cli/init.md b/docs/tools/cli/init.md
index b49add305..1429f233d 100644
--- a/docs/tools/cli/init.md
+++ b/docs/tools/cli/init.md
@@ -98,8 +98,7 @@ pipelex-agent init [--config/-c JSON] [--global/-g]
{
"backends": ["openai", "anthropic"],
"primary_backend": "openai",
- "accept_gateway_terms": true,
- "telemetry_mode": "off"
+ "accept_gateway_terms": true
}
```
@@ -110,13 +109,14 @@ All fields are optional:
| `backends` | `list[str]` | Backend keys to enable (e.g. `openai`, `anthropic`, `pipelex_gateway`). Omit to keep template defaults. |
| `primary_backend` | `str` | Required only when 2+ backends are selected and `pipelex_gateway` is not among them. |
| `accept_gateway_terms` | `bool` | Required when `pipelex_gateway` is in backends. |
-| `telemetry_mode` | `str` | `off` (default), `anonymous`, or `identified`. |
+
+Telemetry is not configured via `--config`: init seeds a `telemetry.toml` from a template (a global init writes an active one; a project init drops a commented-out one).
**Examples:**
```bash
# Initialize with OpenAI backend (project-level)
-pipelex-agent init --config '{"backends": ["openai"], "telemetry_mode": "off"}'
+pipelex-agent init --config '{"backends": ["openai"]}'
# Initialize globally with gateway
pipelex-agent init -g --config '{"backends": ["pipelex_gateway"], "accept_gateway_terms": true}'
diff --git a/drift.toml b/drift.toml
new file mode 100644
index 000000000..c26deba6a
--- /dev/null
+++ b/drift.toml
@@ -0,0 +1,56 @@
+# Drift contracts — declared review obligations between code, docs, and tests.
+#
+# A contract says: when these trigger files change, these review targets must be
+# re-examined against the change, and the examination must be recorded with
+# `make drift-ack CONTRACT=<id> RATIONALE="…"`. `make drift-check` gates the local
+# `make check` aggregate and runs as an advisory CI job (to be promoted to a
+# required check — see TODOS.md). See docs/contribute/drift-contracts.md for the
+# full workflow.
+#
+# Keep this manifest small: every contract here must earn its friction. Anything
+# mechanizable (regenerate-and-diff, referential integrity) belongs in a derived
+# check (check-config-sync, check-mthds-schema, …), never in a review contract.
+
+version = 1
+
+[contracts.config-docs]
+description = "User-facing configuration docs must track the config model and the shipped defaults."
+# The config model tree is rooted in system/configuration/ but several documented
+# submodels are defined in their own packages — they trigger too.
+triggers = [
+ "pipelex/system/configuration/**/*.py",
+ "pipelex/system/telemetry/telemetry_config.py",
+ "pipelex/cogt/config_cogt.py",
+ "pipelex/cogt/img_gen/img_gen_job_components.py",
+ "pipelex/tools/aws/aws_config.py",
+ "pipelex/tools/log/log_config.py",
+ "pipelex/pipelex.toml",
+]
+review = [
+ "docs/configuration/**/*.md",
+]
+verify_commands = ["make tb"]
+
+[contracts.cli-docs]
+description = "CLI docs and the agent-CLI contract doc must track the CLI surface."
+triggers = [
+ "pipelex/cli/**/*.py",
+]
+exclude = [
+ "pipelex/cli/dev_cli/**",
+]
+review = [
+ "docs/tools/cli/",
+ "pipelex/cli/agent_cli/CLAUDE.md",
+]
+verify_commands = []
+
+[contracts.keyword-only-convention]
+description = "The keyword-only-arguments doc is the convention's specification and must track the guard's behavior."
+triggers = [
+ "pipelex/cli/dev_cli/commands/keyword_only_guard.py",
+]
+review = [
+ "docs/contribute/keyword-only-arguments.md",
+]
+verify_commands = []
diff --git a/mkdocs.yml b/mkdocs.yml
index 7ce5022db..1ffcbe783 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -328,6 +328,7 @@ plugins:
- contributing.md: "Contributing"
- contribute/configuration-defaults-and-overrides.md: "Configuration Internals"
- contribute/keyword-only-arguments.md: "Keyword-Only Arguments"
+ - contribute/drift-contracts.md: "Drift Contracts"
- changelog.md: "Changelog"
markdown_extensions:
@@ -563,6 +564,7 @@ nav:
- Contributing: contributing.md
- Configuration Internals: contribute/configuration-defaults-and-overrides.md
- Keyword-Only Arguments: contribute/keyword-only-arguments.md
+ - Drift Contracts: contribute/drift-contracts.md
- Code of Conduct: CODE_OF_CONDUCT.md
- License: license.md
- Changelog: changelog.md
diff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.py
index 016ec53de..fdffa7d7f 100644
--- a/pipelex/base_exceptions.py
+++ b/pipelex/base_exceptions.py
@@ -360,7 +360,7 @@ class ErrorReport(BaseModel):
# not server internals.
validation_errors: list[ValidationErrorItem] | None = None
- def to_dict(self, disclosure_mode: DisclosureMode = DisclosureMode.VERBOSE) -> dict[str, Any]:
+ def to_dict(self, *, disclosure_mode: DisclosureMode = DisclosureMode.VERBOSE) -> dict[str, Any]:
"""Return a dict with only non-None fields, projected through ``disclosure_mode``.
``VERBOSE`` is the strict inverse of :meth:`from_dict` — every populated
diff --git a/pipelex/builder/bundle_spec.py b/pipelex/builder/bundle_spec.py
index 6e371d9c8..ad601ee6e 100644
--- a/pipelex/builder/bundle_spec.py
+++ b/pipelex/builder/bundle_spec.py
@@ -107,7 +107,9 @@ class PipelexBundleSpec(StructuredContent):
if isinstance(pipe_code, str) and not is_pipe_code_valid(pipe_code=pipe_code):
msg = f"Pipe code '{pipe_code}' is not a valid pipe code. Must be in snake_case."
raise ValueError(msg)
- normalized[pipe_code] = normalize_typeless_signature_section(pipe_code, pipe_section=pipe_section, allowed_keys=SIGNATURE_ONLY_SPEC_KEYS)
+ normalized[pipe_code] = normalize_typeless_signature_section(
+ pipe_code=pipe_code, pipe_section=pipe_section, allowed_keys=SIGNATURE_ONLY_SPEC_KEYS
+ )
return normalized
@model_validator(mode="after")
diff --git a/pipelex/builder/concept/concept_spec.py b/pipelex/builder/concept/concept_spec.py
index 8fa0fb1bd..950e0b45e 100644
--- a/pipelex/builder/concept/concept_spec.py
+++ b/pipelex/builder/concept/concept_spec.py
@@ -179,24 +179,24 @@ class ConceptStructureSpec(StructuredContent):
match self.type:
case ConceptStructureSpecFieldType.TEXT:
if not isinstance(self.default_value, str):
- self._raise_type_mismatch_error("str", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="str", actual_type_name=type(self.default_value).__name__)
case ConceptStructureSpecFieldType.INTEGER:
if not isinstance(self.default_value, int):
- self._raise_type_mismatch_error("int", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="int", actual_type_name=type(self.default_value).__name__)
case ConceptStructureSpecFieldType.BOOLEAN:
if not isinstance(self.default_value, bool):
- self._raise_type_mismatch_error("bool", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="bool", actual_type_name=type(self.default_value).__name__)
case ConceptStructureSpecFieldType.NUMBER:
if not isinstance(self.default_value, (int, float)):
- self._raise_type_mismatch_error("number (int or float)", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="number (int or float)", actual_type_name=type(self.default_value).__name__)
case ConceptStructureSpecFieldType.DATE:
# A calendar date, not a datetime: datetime is a subclass of date, so reject it explicitly
# (a datetime default would carry a time the `date` field silently drops).
if not isinstance(self.default_value, date) or isinstance(self.default_value, datetime):
- self._raise_type_mismatch_error("date", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="date", actual_type_name=type(self.default_value).__name__)
case ConceptStructureSpecFieldType.DATETIME:
if not isinstance(self.default_value, datetime):
- self._raise_type_mismatch_error("datetime", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="datetime", actual_type_name=type(self.default_value).__name__)
case ConceptStructureSpecFieldType.CONCEPT:
# CONCEPT type cannot have default values, this is already validated in validate_structure_blueprint
pass
@@ -204,7 +204,7 @@ class ConceptStructureSpec(StructuredContent):
# LIST type cannot have default values, this is already validated in validate_structure_blueprint
pass
- def _raise_type_mismatch_error(self, expected_type_name: str, *, actual_type_name: str) -> None:
+ def _raise_type_mismatch_error(self, *, expected_type_name: str, actual_type_name: str) -> None:
msg = f"default_value type mismatch: expected {expected_type_name} for type '{self.type}', but got {actual_type_name}"
raise ValueError(msg)
diff --git a/pipelex/builder/operations/inputs_ops.py b/pipelex/builder/operations/inputs_ops.py
index ac009ecc3..ec63528c3 100644
--- a/pipelex/builder/operations/inputs_ops.py
+++ b/pipelex/builder/operations/inputs_ops.py
@@ -21,8 +21,8 @@ if TYPE_CHECKING:
async def build_inputs_for_pipe(
- pipe_code: str | None = None,
*,
+ pipe_code: str | None = None,
mthds_contents: list[str] | None = None,
bundle_path: Path | None = None,
library_dirs: list[Path] | None = None,
diff --git a/pipelex/builder/operations/models_ops.py b/pipelex/builder/operations/models_ops.py
index 5bf631eeb..dfeb12fce 100644
--- a/pipelex/builder/operations/models_ops.py
+++ b/pipelex/builder/operations/models_ops.py
@@ -183,8 +183,8 @@ def _build_waterfalls_for_category(
def list_models(
- categories: list[ModelCategory] | None = None,
*,
+ categories: list[ModelCategory] | None = None,
backend: str | None = None,
) -> dict[str, Any]:
"""List available model presets, aliases, and waterfalls.
diff --git a/pipelex/builder/operations/pipe_ops.py b/pipelex/builder/operations/pipe_ops.py
index e892f989d..003e67595 100644
--- a/pipelex/builder/operations/pipe_ops.py
+++ b/pipelex/builder/operations/pipe_ops.py
@@ -180,7 +180,9 @@ def parse_pipe_spec(spec_data: Any, *, pipe_type: str | None) -> PipeSpec:
if pipe_type == PIPE_SIGNATURE_TYPE_TAG:
raise ValueError(explicit_signature_tag_migration_message(spec_data.get("pipe_code")))
if pipe_type is None:
- normalized = normalize_typeless_signature_section(spec_data.get("pipe_code"), pipe_section=spec_data, allowed_keys=SIGNATURE_ONLY_SPEC_KEYS)
+ normalized = normalize_typeless_signature_section(
+ pipe_code=spec_data.get("pipe_code"), pipe_section=spec_data, allowed_keys=SIGNATURE_ONLY_SPEC_KEYS
+ )
return PipeSignatureSpec.model_validate(normalized)
if pipe_type not in pipe_type_to_spec_class:
@@ -224,7 +226,7 @@ def parse_pipe_spec(spec_data: Any, *, pipe_type: str | None) -> PipeSpec:
return spec_class.model_validate(spec_data)
-def add_type_specific_fields(pipe_spec: PipeSpec, *, pipe_table: Table) -> None:
+def add_type_specific_fields(*, pipe_spec: PipeSpec, pipe_table: Table) -> None:
"""Add type-specific fields to the pipe TOML table.
Args:
@@ -371,7 +373,7 @@ def pipe_spec_to_toml(pipe_spec: PipeSpec) -> str:
pipe_item_table.add("output", pipe_spec.output)
# Add type-specific fields
- add_type_specific_fields(pipe_spec, pipe_table=pipe_item_table)
+ add_type_specific_fields(pipe_spec=pipe_spec, pipe_table=pipe_item_table)
# Build the nested structure: [pipe.pipe_code]
pipe_section = tomlkit.table()
diff --git a/pipelex/builder/operations/validate_ops.py b/pipelex/builder/operations/validate_ops.py
index 9a81f18ac..89bae1e1a 100644
--- a/pipelex/builder/operations/validate_ops.py
+++ b/pipelex/builder/operations/validate_ops.py
@@ -22,6 +22,7 @@ if TYPE_CHECKING:
async def validate_all(
+ *,
library_dirs: list[Path] | None = None,
) -> dict[str, Any]:
"""Validate all pipes in all libraries.
diff --git a/pipelex/builder/runner_code.py b/pipelex/builder/runner_code.py
index c77765720..b2d5e6d4e 100644
--- a/pipelex/builder/runner_code.py
+++ b/pipelex/builder/runner_code.py
@@ -66,7 +66,7 @@ def _format_representation_as_python(representation: dict[str, Any], *, is_multi
return f'{{\n "concept": "{concept}",\n "content": {content},\n }}'
-def _get_structure_class_import(class_name: str) -> str | None:
+def _get_structure_class_import(*, class_name: str) -> str | None:
"""Get the import statement for a native structure class.
The import statement is generated dynamically from the class's actual module location,
@@ -84,7 +84,7 @@ def _get_structure_class_import(class_name: str) -> str | None:
return f"from {cls.__module__} import {cls.__name__}"
-def _custom_import_statement(class_name: str, *, emitted_names: set[str]) -> str:
+def _custom_import_statement(*, class_name: str, emitted_names: set[str]) -> str:
"""Build the import statement for a custom (non-native) structure class.
A name the codegen engine emitted comes from the single-module projection. Otherwise, a class
@@ -202,7 +202,7 @@ def generate_runner_code(
# Add native content class imports
native_imports: list[str] = []
for class_name in sorted(native_classes):
- import_stmt = _get_structure_class_import(class_name)
+ import_stmt = _get_structure_class_import(class_name=class_name)
if import_stmt:
native_imports.append(import_stmt)
import_lines.extend(native_imports)
@@ -211,7 +211,7 @@ def generate_runner_code(
if custom_classes:
import_lines.append("")
for class_name in sorted(custom_classes):
- import_lines.append(_custom_import_statement(class_name, emitted_names=emitted_names))
+ import_lines.append(_custom_import_statement(class_name=class_name, emitted_names=emitted_names))
import_lines.extend(
[
diff --git a/pipelex/cli/_cli.py b/pipelex/cli/_cli.py
index cc50dcae9..dec199a60 100644
--- a/pipelex/cli/_cli.py
+++ b/pipelex/cli/_cli.py
@@ -89,7 +89,7 @@ class PipelexCLI(TyperGroup):
ctx.obj["traceback"] = traceback
# Record at parse time so error handlers honor --traceback without relying on
# an active global Click context (absent under typer >= 0.26 / click >= 8.4).
- set_traceback_requested(traceback)
+ set_traceback_requested(value=traceback)
return ctx
@@ -101,7 +101,7 @@ app = typer.Typer(
)
-def version_callback(value: bool) -> None:
+def version_callback(value: bool) -> None: # kw-only: ignore — click invokes Option callbacks positionally
"""Print version and exit when --version is passed."""
if value:
package_version = get_package_version()
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index c6e17d167..8b5eaee35 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -9,7 +9,7 @@ Two independent options control the two output streams:
- `--format markdown|json` — **success/useful output**. Defaults to markdown. Accepted by `run`, `validate`, `fix`, `init`, `models`, `check-model`, `doctor`, `codegen types`, `codegen check`. Goes to stdout. Threaded explicitly to `agent_success_formatted()` from each command function — no hidden state.
- `--error-format markdown|json` — **error reporting** (stderr). Optional. When omitted, **inherits the value of `--format`**, so `--format json` still flips both as it did historically. Accepted by the same commands as `--format`.
-Only the error format is backed by a module-level `ContextVar` in `agent_output.py` (`_agent_cli_error_format`). The reason: `agent_error()` is called from sites that don't see the Typer option — factory init failures (`agent_cli_factory.py`), the unknown-command handler in `PipelexAgentCLI.get_command`, log-level/runner validation in the app callback, and any future site in shared library/runtime code. The ContextVar lets all of them honor `--error-format` (or `--format`'s inherited value) for free. JSON is the default so errors raised before any command opts in stay machine-parseable.
+Only the error format is backed by a module-level `ContextVar` in `agent_output.py` (`_agent_cli_error_format`). The reason: `agent_error()` is called from sites that don't see the Typer option — factory init failures (`agent_cli_factory.py`), the unknown-command handler in `PipelexAgentCLI.get_command`, runner validation in the app callback, and any future site in shared library/runtime code. The ContextVar lets all of them honor `--error-format` (or `--format`'s inherited value) for free. JSON is the default so errors raised before any command opts in stay machine-parseable.
`concept`, `pipe`, `fmt`, `lint`, `accept-gateway-terms` are **always JSON / raw passthrough** — they have neither `--format` nor `--error-format`. Their errors keep flowing through the ContextVar's JSON default.
@@ -27,19 +27,17 @@ Markdown structure per command:
The CLI is consumed by a set of Claude skills defined in a separate repo. Changes to the CLI often require corresponding skill updates, and vice versa.
-- Skills repo: `../skills/skills/` (relative to project root)
-- Skills: `mthds-build`, `mthds-check`, `mthds-edit`, `mthds-explain`, `mthds-fix`, `mthds-inputs`, `mthds-install`, `mthds-pkg`, `mthds-run`
+- Skills location: `../mthds-plugins/mthds/skills/` (relative to project root) — one `mthds-*` directory per skill
- Each skill is a `SKILL.md` with optional `references/` dir
-- Shared reference docs: `../skills/skills/shared/` (`error-handling.md`, `mthds-agent-guide.md`, `mthds-reference.md`, `native-content-types.md`)
+- Shared reference docs: `../mthds-plugins/mthds/skills/shared/` (`error-handling.md`, `mthds-agent-guide.md`, `mthds-reference.md`, `native-content-types.md`, …)
When changing CLI command signatures, output schemas, or error types, check whether the affected skills need updating.
## Code Layout
```
-_agent_cli.py # Typer app setup, version callback
+_agent_cli.py # Typer app setup, version callback, PipelexAgentCLI(TyperGroup) — command registration, ordering
commands/
- _agent_cli.py # PipelexAgentCLI(TyperGroup) — command registration, ordering
agent_output.py # agent_success(), agent_error(), error hints/domains
agent_cli_factory.py # make_pipelex_for_agent_cli() — init with JSON errors
run/ # run — execute pipeline (pipe|bundle|method subcommands)
@@ -85,7 +83,7 @@ commands/
| Command | Does |
|---------|------|
-| `init` | Initializes Pipelex configuration (non-interactive). Defaults to project `.pipelex/` at detected project root. Use `--global`/`-g` to target `~/.pipelex/`. Accepts `--config`/`-c` with inline JSON or file path for backends, routing, telemetry, and gateway terms. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |
+| `init` | Initializes Pipelex configuration (non-interactive). Defaults to project `.pipelex/` at detected project root. Use `--global`/`-g` to target `~/.pipelex/`. Accepts `--config`/`-c` with inline JSON or file path for backends, routing (via `primary_backend`), and gateway terms; telemetry is seeded from a template, not `--config`. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |
| `run` | Executes a pipeline (pipe\|bundle\|method subcommands), returns main_stuff + working_memory. Graph visualizations on by default (`--no-graph` to disable). `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |
| `validate` | Dry-runs pipes/bundles/methods (pipe\|bundle\|method subcommands), returns validation status per pipe. Bundle subcommand supports `--graph` for graph visualization (with `--graph-format` for the graph renderer). `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |
| `fix` | Applies deterministic safe fixes to a bundle file or directory (`fix bundle`) and re-validates until valid, out of fixes, or max iterations. Supports `--allow-signatures`, `--select`, `--ignore`, `--max-iterations`, and `-L/--library-dir`. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |
diff --git a/pipelex/cli/agent_cli/_agent_cli.py b/pipelex/cli/agent_cli/_agent_cli.py
index 209f2c577..bbbb33d75 100644
--- a/pipelex/cli/agent_cli/_agent_cli.py
+++ b/pipelex/cli/agent_cli/_agent_cli.py
@@ -74,7 +74,7 @@ app = typer.Typer(
)
-def version_callback(value: bool) -> None:
+def version_callback(value: bool) -> None: # kw-only: ignore — click invokes Option callbacks positionally
"""Print version and exit when --version is passed."""
if value:
package_version = get_package_version()
diff --git a/pipelex/cli/agent_cli/commands/agent_cli_factory.py b/pipelex/cli/agent_cli/commands/agent_cli_factory.py
index 1aadf7efb..8ea8729c4 100644
--- a/pipelex/cli/agent_cli/commands/agent_cli_factory.py
+++ b/pipelex/cli/agent_cli/commands/agent_cli_factory.py
@@ -161,10 +161,7 @@ def apply_agent_cli_output_discipline() -> None:
def make_pipelex_for_agent_cli(
- library_dirs: list[str] | list[Path] | None = None,
- *,
- needs_inference: bool = True,
- needs_model_specs: bool | None = None,
+ *, library_dirs: list[str] | list[Path] | None = None, needs_inference: bool = True, needs_model_specs: bool | None = None
) -> Pipelex:
"""Initialize Pipelex for agent CLI commands with JSON error output.
diff --git a/pipelex/cli/agent_cli/commands/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.py
index 3c9fd5d78..8868104d8 100644
--- a/pipelex/cli/agent_cli/commands/agent_output.py
+++ b/pipelex/cli/agent_cli/commands/agent_output.py
@@ -479,7 +479,9 @@ def _render_validate_bundle_markdown(
# "check the validation_errors array" hint that the JSON envelope keeps.
fixable_count = count_applicable_fixes(items, bundle_path=bundle_path, library_dirs=library_dirs)
if fixable_count:
- fix_command = build_fix_command("pipelex-agent", bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures)
+ fix_command = build_fix_command(
+ executable="pipelex-agent", bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures
+ )
lines += ["", f"💡 {fixable_count} of these errors can be fixed automatically — run: `{fix_command}`"]
else:
lines += ["", "💡 These errors have no automatic fix — review the messages above and edit the bundle."]
diff --git a/pipelex/cli/agent_cli/commands/check_model_cmd.py b/pipelex/cli/agent_cli/commands/check_model_cmd.py
index 33ae58d4a..2e3bb5be7 100644
--- a/pipelex/cli/agent_cli/commands/check_model_cmd.py
+++ b/pipelex/cli/agent_cli/commands/check_model_cmd.py
@@ -95,7 +95,7 @@ def agent_check_model_cmd(
if not is_valid:
suggestions, wrong_sigil_hints, cross_suggestions = suggest_model_alternatives(
- model_deck, model_type=resolved_model_type, name=ref.name, kind=ref.kind
+ model_deck=model_deck, model_type=resolved_model_type, name=ref.name, kind=ref.kind
)
result["suggestions"] = suggestions
result["wrong_sigil_hints"] = wrong_sigil_hints
diff --git a/pipelex/cli/agent_cli/commands/doctor_cmd.py b/pipelex/cli/agent_cli/commands/doctor_cmd.py
index 216372c41..d1ee397d4 100644
--- a/pipelex/cli/agent_cli/commands/doctor_cmd.py
+++ b/pipelex/cli/agent_cli/commands/doctor_cmd.py
@@ -24,7 +24,7 @@ from pipelex.cli.commands.doctor_cmd import (
from pipelex.system.configuration.config_loader import config_manager
-def _status_icon(healthy: bool) -> str:
+def _status_icon(*, healthy: bool) -> str:
"""Return a status emoji: checkmark for healthy, warning for unhealthy."""
return "\u2705" if healthy else "\u26a0\ufe0f"
@@ -35,7 +35,7 @@ def _format_doctor_markdown(result: dict[str, Any]) -> str:
config_location: dict[str, Any] = result["config_location"]
checks: dict[str, Any] = result["checks"]
- status_text = f"All healthy {_status_icon(True)}" if all_healthy else f"Issues found {_status_icon(False)}"
+ status_text = f"All healthy {_status_icon(healthy=True)}" if all_healthy else f"Issues found {_status_icon(healthy=False)}"
location_type = "project-local" if config_location.get("is_project_local") else "global"
lines: list[str] = [
@@ -47,17 +47,17 @@ def _format_doctor_markdown(result: dict[str, Any]) -> str:
# Config Files
config_check = checks["config_files"]
- lines.append(f"\n## Config Files \u2014 {_status_icon(config_check['healthy'])}\n")
+ lines.append(f"\n## Config Files \u2014 {_status_icon(healthy=config_check['healthy'])}\n")
lines.append(config_check["message"])
# Telemetry
telemetry_check = checks["telemetry"]
- lines.append(f"\n## Telemetry \u2014 {_status_icon(telemetry_check['healthy'])}\n")
+ lines.append(f"\n## Telemetry \u2014 {_status_icon(healthy=telemetry_check['healthy'])}\n")
lines.append(telemetry_check["message"])
# Backend Credentials
creds_check = checks["backend_credentials"]
- lines.append(f"\n## Backend Credentials \u2014 {_status_icon(creds_check['healthy'])}\n")
+ lines.append(f"\n## Backend Credentials \u2014 {_status_icon(healthy=creds_check['healthy'])}\n")
lines.append(creds_check["message"])
for backend_entry in creds_check.get("backends", []):
name = backend_entry["backend_name"]
@@ -78,7 +78,7 @@ def _format_doctor_markdown(result: dict[str, Any]) -> str:
models_skipped_flag = models_check.get("skipped", False)
# Skipped state renders with the warn icon so consumers don't confuse "deferred until
# config is fixed" with a genuine models failure.
- models_icon = "\u26a0\ufe0f" if models_skipped_flag else _status_icon(models_check["healthy"])
+ models_icon = "\u26a0\ufe0f" if models_skipped_flag else _status_icon(healthy=models_check["healthy"])
lines.append(f"\n## Models \u2014 {models_icon}\n")
lines.append(models_check["message"])
for file_entry in models_check.get("backend_files", []):
diff --git a/pipelex/cli/agent_cli/commands/init_cmd.py b/pipelex/cli/agent_cli/commands/init_cmd.py
index c1e186758..3ed36d13b 100644
--- a/pipelex/cli/agent_cli/commands/init_cmd.py
+++ b/pipelex/cli/agent_cli/commands/init_cmd.py
@@ -85,7 +85,7 @@ def _format_init_markdown(result: dict[str, Any]) -> str:
return "\n".join(lines)
-def _resolve_target_dir(global_: bool) -> Path:
+def _resolve_target_dir(*, global_: bool) -> Path:
"""Resolve the target directory for initialization.
Args:
@@ -380,7 +380,7 @@ def agent_init_cmd(
parsed_config = _parse_config_arg(config)
# Resolve target directory
- target_dir = _resolve_target_dir(global_)
+ target_dir = _resolve_target_dir(global_=global_)
# Step 1: Copy config files (skips inference/ directory)
config_files_copied = init_config(reset=True, target_dir=target_dir)
diff --git a/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py b/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py
index c81f4ebe7..459e29b58 100644
--- a/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py
+++ b/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py
@@ -13,11 +13,7 @@ if TYPE_CHECKING:
async def inputs_core(
- pipe_code: str | None = None,
- *,
- bundle_path: Path | None = None,
- library_dirs: list[Path] | None = None,
- explicit: bool = False,
+ *, pipe_code: str | None = None, bundle_path: Path | None = None, library_dirs: list[Path] | None = None, explicit: bool = False
) -> dict[str, Any]:
"""Core logic for generating input JSON for a pipe.
@@ -70,7 +66,7 @@ def emit_inputs_result(result: dict[str, Any], *, template_format: InputsTemplat
print(toml_content, end="" if toml_content.endswith("\n") else "\n")
-def emit_no_inputs_result(pipe_code: str | None, *, message: str, template_format: InputsTemplateFormat) -> None:
+def emit_no_inputs_result(*, pipe_code: str | None, message: str, template_format: InputsTemplateFormat) -> None:
"""Emit the not-an-error result for a pipe that requires no inputs.
JSON keeps the structured envelope with an empty ``inputs`` dict; TOML
diff --git a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
index 1229b0c95..c6ad6a69b 100644
--- a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
@@ -112,7 +112,7 @@ def inputs_bundle_cmd(
agent_error(exc.message, error_type="ValidateBundleError", cause=exc, **extra)
except NoInputsRequiredError as exc:
- emit_no_inputs_result(pipe_code, message=str(exc), template_format=template_format)
+ emit_no_inputs_result(pipe_code=pipe_code, message=str(exc), template_format=template_format)
except PipeOperatorModelChoiceError as exc:
agent_error(
diff --git a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
index 8c5f1061f..516cf6fc7 100644
--- a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
@@ -85,7 +85,7 @@ def inputs_method_cmd(
agent_error(exc.message, error_type="ValidateBundleError", cause=exc, **extra)
except NoInputsRequiredError as exc:
- emit_no_inputs_result(pipe_code, message=str(exc), template_format=template_format)
+ emit_no_inputs_result(pipe_code=pipe_code, message=str(exc), template_format=template_format)
except PipeOperatorModelChoiceError as exc:
agent_error(
diff --git a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
index f222e810a..08cf0c6d2 100644
--- a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
@@ -93,7 +93,7 @@ def inputs_pipe_cmd(
except NoInputsRequiredError as exc:
# Not really an error - just a pipe with no inputs
- emit_no_inputs_result(pipe_code, message=str(exc), template_format=template_format)
+ emit_no_inputs_result(pipe_code=pipe_code, message=str(exc), template_format=template_format)
except PipeOperatorModelChoiceError as exc:
agent_error(
diff --git a/pipelex/cli/agent_cli/commands/pipe_cmd.py b/pipelex/cli/agent_cli/commands/pipe_cmd.py
index 2b309a6f7..0be9fb13d 100644
--- a/pipelex/cli/agent_cli/commands/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/pipe_cmd.py
@@ -64,7 +64,7 @@ def _pipe_spec_to_toml(pipe_spec: PipeSpec) -> str:
pipe_item_table.add("output", pipe_spec.output)
# Add type-specific fields
- _add_type_specific_fields(pipe_spec, pipe_table=pipe_item_table)
+ _add_type_specific_fields(pipe_spec=pipe_spec, pipe_table=pipe_item_table)
# Build the nested structure: [pipe.pipe_code]
pipe_section = tomlkit.table()
@@ -73,7 +73,7 @@ def _pipe_spec_to_toml(pipe_spec: PipeSpec) -> str:
return tomlkit.dumps(doc)
-def _add_type_specific_fields(pipe_spec: PipeSpec, *, pipe_table: tomlkit.TOMLDocument | tomlkit.items.Table) -> None: # type: ignore[name-defined]
+def _add_type_specific_fields(*, pipe_spec: PipeSpec, pipe_table: tomlkit.TOMLDocument | tomlkit.items.Table) -> None: # type: ignore[name-defined]
"""Add type-specific fields to the pipe TOML table.
Args:
diff --git a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py b/pipelex/cli/agent_cli/commands/run/stdin_resolver.py
index 698b331ea..4bc7f4e91 100644
--- a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py
+++ b/pipelex/cli/agent_cli/commands/run/stdin_resolver.py
@@ -173,7 +173,7 @@ def parse_cli_inputs(
if auto_inputs_dir is not None:
try:
- auto_inputs_file = find_default_inputs_file(auto_inputs_dir)
+ auto_inputs_file = find_default_inputs_file(directory=auto_inputs_dir)
except AmbiguousInputsFilesError as ambiguity_exc:
agent_error(ambiguity_exc.message, error_type="AmbiguousInputsFilesError", cause=ambiguity_exc)
if auto_inputs_file is not None:
diff --git a/pipelex/cli/agent_cli/commands/validate/_validate_core.py b/pipelex/cli/agent_cli/commands/validate/_validate_core.py
index b03696b03..94c86636f 100644
--- a/pipelex/cli/agent_cli/commands/validate/_validate_core.py
+++ b/pipelex/cli/agent_cli/commands/validate/_validate_core.py
@@ -23,11 +23,7 @@ if TYPE_CHECKING:
from pathlib import Path
-async def validate_all_core(
- library_dirs: list[Path] | None = None,
- *,
- allow_signatures: bool = False,
-) -> dict[str, Any]:
+async def validate_all_core(*, library_dirs: list[Path] | None = None, allow_signatures: bool = False) -> dict[str, Any]:
"""Validate all pipes in all libraries.
Args:
diff --git a/pipelex/cli/commands/build/inputs/_inputs_core.py b/pipelex/cli/commands/build/inputs/_inputs_core.py
index c92dc7ebc..60aa8704f 100644
--- a/pipelex/cli/commands/build/inputs/_inputs_core.py
+++ b/pipelex/cli/commands/build/inputs/_inputs_core.py
@@ -33,8 +33,8 @@ SUB_COMMAND_INPUTS = "inputs"
async def _generate_inputs_core(
- pipe_code: str | None = None,
*,
+ pipe_code: str | None = None,
bundle_path: Path | None = None,
output_path: Path | None = None,
library_dir: list[str] | None = None,
@@ -124,8 +124,8 @@ async def _generate_inputs_core(
def execute_generate_inputs(
- pipe_code: str | None,
*,
+ pipe_code: str | None,
bundle_path: Path | None,
output_path: Path | None,
library_dir: list[str] | None = None,
diff --git a/pipelex/cli/commands/build/output/_output_core.py b/pipelex/cli/commands/build/output/_output_core.py
index 2984fb243..12e096639 100644
--- a/pipelex/cli/commands/build/output/_output_core.py
+++ b/pipelex/cli/commands/build/output/_output_core.py
@@ -33,8 +33,8 @@ SUB_COMMAND_OUTPUT = "output"
async def _generate_output_core(
- pipe_code: str | None = None,
*,
+ pipe_code: str | None = None,
bundle_path: Path | None = None,
output_path: Path | None = None,
output_format: ConceptRepresentationFormat = ConceptRepresentationFormat.JSON,
@@ -128,8 +128,8 @@ async def _generate_output_core(
def execute_generate_output(
- pipe_code: str | None,
*,
+ pipe_code: str | None,
bundle_path: Path | None,
output_path: Path | None,
output_format: ConceptRepresentationFormat,
diff --git a/pipelex/cli/commands/build/runner/_runner_core.py b/pipelex/cli/commands/build/runner/_runner_core.py
index d71301b30..dd0ce14f5 100644
--- a/pipelex/cli/commands/build/runner/_runner_core.py
+++ b/pipelex/cli/commands/build/runner/_runner_core.py
@@ -50,11 +50,7 @@ SUB_COMMAND_RUNNER = "runner"
async def _prepare_runner_core(
- pipe_code: str | None = None,
- *,
- bundle_path: Path | None = None,
- output_path: Path | None = None,
- library_dirs: list[Path] | None = None,
+ *, pipe_code: str | None = None, bundle_path: Path | None = None, output_path: Path | None = None, library_dirs: list[Path] | None = None
) -> None:
"""Core logic for generating a Python runner file."""
all_blueprints: list[PipelexBundleBlueprint] = []
@@ -166,8 +162,8 @@ async def _prepare_runner_core(
def execute_prepare_runner(
- pipe_code: str | None,
*,
+ pipe_code: str | None,
bundle_path: Path | None,
output_path: Path | None,
library_dirs: list[Path] | None = None,
diff --git a/pipelex/cli/commands/codegen/inputs_cmd.py b/pipelex/cli/commands/codegen/inputs_cmd.py
index 5beb3cd66..020499441 100644
--- a/pipelex/cli/commands/codegen/inputs_cmd.py
+++ b/pipelex/cli/commands/codegen/inputs_cmd.py
@@ -73,7 +73,7 @@ def codegen_inputs_cmd(
combined_dirs: list[Path] = [*(paths or []), *(library_dir or [])]
crate = load_normalized_crate_or_exit(library_dirs=combined_dirs or None)
- pipe_ref = pipe or _default_main_pipe_ref(crate)
+ pipe_ref = pipe or _default_main_pipe_ref(crate=crate)
try:
the_pipe = get_required_pipe(pipe_code=pipe_ref)
except PipeLibraryError as exc:
@@ -108,7 +108,7 @@ def _render(*, the_pipe: PipeAbstract, template_format: InputsTemplateFormat, ex
return render_inputs_toml(the_pipe, explicit=explicit), DEFAULT_INPUTS_TOML_FILE_NAME
-def _default_main_pipe_ref(crate: LibraryCrate) -> str:
+def _default_main_pipe_ref(*, crate: LibraryCrate) -> str:
"""The closure's single declared `main_pipe` (qualified), or exit 1 if none / ambiguous."""
candidates = [f"{domain_code}.{domain.main_pipe}" for domain_code, domain in crate.domains.items() if domain.main_pipe]
if not candidates:
diff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.py
index bcc4dcef7..0823f0038 100644
--- a/pipelex/cli/commands/doctor_cmd.py
+++ b/pipelex/cli/commands/doctor_cmd.py
@@ -106,7 +106,7 @@ class BackendFileReport(BaseModel):
has_kit_template: bool = False
-def check_config_files(config_dir: Path | None = None) -> tuple[bool, int, str]:
+def check_config_files(*, config_dir: Path | None = None) -> tuple[bool, int, str]:
"""Check if configuration files are present and main config is valid.
Args:
@@ -159,7 +159,7 @@ def check_config_files(config_dir: Path | None = None) -> tuple[bool, int, str]:
return False, missing_count, f"{missing_count} configuration file(s) missing"
-def check_telemetry_config(config_dir: Path | None = None) -> tuple[bool, str]:
+def check_telemetry_config(*, config_dir: Path | None = None) -> tuple[bool, str]:
"""Check if telemetry configuration is valid.
Args:
@@ -188,7 +188,7 @@ def check_telemetry_config(config_dir: Path | None = None) -> tuple[bool, str]:
return False, "Invalid configuration - run 'pipelex init telemetry' to fix"
-def check_backend_credentials(config_dir: Path | None = None) -> tuple[bool, dict[str, BackendCredentialsReport], str]:
+def check_backend_credentials(*, config_dir: Path | None = None) -> tuple[bool, dict[str, BackendCredentialsReport], str]:
"""Check if backend credentials are properly configured.
Args:
@@ -330,7 +330,7 @@ def replace_backend_file(backend_name: str, *, dry_run: bool = False, config_dir
return False
-def check_backend_files(config_dir: Path | None = None) -> tuple[bool, dict[str, BackendFileReport], str]:
+def check_backend_files(*, config_dir: Path | None = None) -> tuple[bool, dict[str, BackendFileReport], str]:
"""Check individual backend configuration files for validity.
Args:
@@ -703,7 +703,7 @@ def display_health_report(
console.print()
-def check_deck_sync(config_dir: Path | None = None) -> tuple[bool, DeckSyncReport, str]:
+def check_deck_sync(*, config_dir: Path | None = None) -> tuple[bool, DeckSyncReport, str]:
"""Check whether the installed model deck is in sync with the kit shipped by this pipelex version.
Args:
@@ -738,11 +738,7 @@ def check_deck_sync(config_dir: Path | None = None) -> tuple[bool, DeckSyncRepor
return False, report, f"{len(actionable)} deck file(s) need action"
-def setup_doctor_runtime(
- log_config_overrides: Mapping[str, Any] | None = None,
- *,
- config_dir: Path | None = None,
-) -> None:
+def setup_doctor_runtime(*, log_config_overrides: Mapping[str, Any] | None = None, config_dir: Path | None = None) -> None:
"""Spin up a fresh PipelexHub and configure logging for doctor checks.
Doctor intentionally bypasses ``Pipelex.make`` so it can diagnose a broken config
@@ -793,7 +789,7 @@ def setup_doctor_runtime(
log.configure_if_unset(log_config=log_config)
-def check_models(config_dir: Path | None = None) -> tuple[bool, str, dict[str, BackendFileReport]]:
+def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[str, BackendFileReport]]:
"""Check if models are valid, including backend file validation.
Assumes ``setup_doctor_runtime`` has already run — the function reads from the
@@ -892,6 +888,7 @@ def check_models(config_dir: Path | None = None) -> tuple[bool, str, dict[str, B
def doctor_cmd(
+ *,
fix: bool = False,
) -> None:
"""Check Pipelex configuration health and suggest fixes.
@@ -916,6 +913,7 @@ def doctor_cmd(
def do_doctor_cmd(
+ *,
fix: bool = False,
) -> None:
"""Check Pipelex configuration health and suggest fixes.
diff --git a/pipelex/cli/commands/fix/_fix_core.py b/pipelex/cli/commands/fix/_fix_core.py
index aa55d404f..5bd7ba061 100644
--- a/pipelex/cli/commands/fix/_fix_core.py
+++ b/pipelex/cli/commands/fix/_fix_core.py
@@ -40,7 +40,7 @@ if TYPE_CHECKING:
COMMAND = "fix"
-def _print_applied_fixes(console: Console, *, fixes: list[SuggestedFix], bundle_path: Path) -> None:
+def _print_applied_fixes(*, console: Console, fixes: list[SuggestedFix], bundle_path: Path) -> None:
"""Numbered list naming every change made — descriptions only, ops stay machine-facing."""
entry_resolved = bundle_path.resolve()
for fix_index, fix in enumerate(fixes, 1):
@@ -50,10 +50,10 @@ def _print_applied_fixes(console: Console, *, fixes: list[SuggestedFix], bundle_
console.print(line)
-def _print_work_done(console: Console, *, result: FixBundleResult, bundle_path: Path, preview: bool = False) -> None:
+def _print_work_done(*, console: Console, result: FixBundleResult, bundle_path: Path, preview: bool = False) -> None:
"""The applied fixes, files written, and iteration count of one fix run."""
console.print(f"[bold cyan]{'Fixes that would be applied:' if preview else 'Applied fixes:'}[/bold cyan]")
- _print_applied_fixes(console, fixes=result.fixes_applied, bundle_path=bundle_path)
+ _print_applied_fixes(console=console, fixes=result.fixes_applied, bundle_path=bundle_path)
if result.files_written:
console.print(f"\n[bold cyan]{'Files that would be written:' if preview else 'Files written:'}[/bold cyan]")
for file_path in result.files_written:
@@ -61,7 +61,7 @@ def _print_work_done(console: Console, *, result: FixBundleResult, bundle_path:
console.print(f"\n[bold cyan]Iterations:[/bold cyan] {result.iterations}")
-def _render_fix_result(console: Console, *, result: FixBundleResult, bundle_path: Path, allow_signatures: bool, preview: bool = False) -> None:
+def _render_fix_result(*, console: Console, result: FixBundleResult, bundle_path: Path, allow_signatures: bool, preview: bool = False) -> None:
"""Render a ``FixBundleResult`` for humans and exit per the 0/1 verdict policy.
Valid (fixed or already valid) exits 0; valid-but-not-runnable without
@@ -82,7 +82,7 @@ def _render_fix_result(console: Console, *, result: FixBundleResult, bundle_path
console.print(f"[bold cyan]Bundle:[/bold cyan] [yellow]{escape(str(bundle_path))}[/yellow]")
if result.fixes_applied:
console.print()
- _print_work_done(console, result=result, bundle_path=bundle_path, preview=preview)
+ _print_work_done(console=console, result=result, bundle_path=bundle_path, preview=preview)
console.print()
if result.pending_signatures:
@@ -114,7 +114,7 @@ def _render_fix_result(console: Console, *, result: FixBundleResult, bundle_path
# Partial progress is normal: name what WAS applied before the remaining errors.
if result.fixes_applied:
- _print_work_done(console, result=result, bundle_path=bundle_path, preview=preview)
+ _print_work_done(console=console, result=result, bundle_path=bundle_path, preview=preview)
console.print()
if result.bail_reason:
@@ -122,7 +122,7 @@ def _render_fix_result(console: Console, *, result: FixBundleResult, bundle_path
if result.remaining_errors:
console.print("[bold cyan]Remaining errors:[/bold cyan]\n")
- display_validation_error_items(console, items=result.remaining_errors)
+ display_validation_error_items(console=console, items=result.remaining_errors)
# A remaining error can still carry a 💡 suggested-fix line — dropped by --select/--ignore,
# left outside the write scope, or unconverged when the loop bailed. Claiming "no safe fix"
@@ -179,7 +179,7 @@ def _remap_result_to_originals(result: FixBundleResult, *, sandbox: PreviewSandb
)
-def _print_preview_diffs(console: Console, *, result: FixBundleResult, sandbox: PreviewSandbox) -> None:
+def _print_preview_diffs(*, console: Console, result: FixBundleResult, sandbox: PreviewSandbox) -> None:
"""Unified diff (original vs sandbox copy) per file the preview run wrote.
Must run while the sandbox still exists — it reads the mutated copies off disk.
@@ -211,8 +211,8 @@ def _print_preview_diffs(console: Console, *, result: FixBundleResult, sandbox:
def _run_fix_preview(
- console: Console,
*,
+ console: Console,
bundle_path: Path,
library_dirs: list[Path] | None,
allow_signatures: bool,
@@ -235,9 +235,9 @@ def _run_fix_preview(
)
)
if result.files_written:
- _print_preview_diffs(console, result=result, sandbox=sandbox)
+ _print_preview_diffs(console=console, result=result, sandbox=sandbox)
display_result = _remap_result_to_originals(result, sandbox=sandbox)
- _render_fix_result(console, result=display_result, bundle_path=bundle_path, allow_signatures=allow_signatures, preview=True)
+ _render_fix_result(console=console, result=display_result, bundle_path=bundle_path, allow_signatures=allow_signatures, preview=True)
def execute_fix(
@@ -269,7 +269,7 @@ def execute_fix(
if diff:
_run_fix_preview(
- get_console(),
+ console=get_console(),
bundle_path=bundle_path,
library_dirs=library_dirs,
allow_signatures=allow_signatures,
@@ -289,9 +289,9 @@ def execute_fix(
ignore_codes=ignore_codes,
)
)
- _render_fix_result(get_console(), result=result, bundle_path=bundle_path, allow_signatures=allow_signatures)
+ _render_fix_result(console=get_console(), result=result, bundle_path=bundle_path, allow_signatures=allow_signatures)
except FileNotFoundError as exc:
- print_traceback_if_requested(get_console())
+ print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to fix: bundle file not found: '{bundle_path}'", fg=typer.colors.RED, err=True)
raise typer.Exit(2) from exc
except PipeOperatorModelChoiceError as exc:
@@ -302,7 +302,7 @@ def execute_fix(
raise
except Exception as exc:
# Human CLI command boundary: an unexpected failure produced no verdict — exit 2.
- print_traceback_if_requested(get_console())
+ print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to fix: {exc}", fg=typer.colors.RED, err=True)
raise typer.Exit(2) from exc
finally:
diff --git a/pipelex/cli/commands/init/backends.py b/pipelex/cli/commands/init/backends.py
index 2bf4234bb..69ceaa1ed 100644
--- a/pipelex/cli/commands/init/backends.py
+++ b/pipelex/cli/commands/init/backends.py
@@ -133,7 +133,7 @@ def customize_backends_config(*, is_first_time_setup: bool = False, target_confi
# Suggest IDE extension install after backend selection, before gateway terms
try:
- suggest_extension_install_if_needed(console)
+ suggest_extension_install_if_needed(console=console)
except EOFError as exc:
# No stdin available for the install prompt — skip the optional IDE extension suggestion.
log.debug(f"IDE extension suggestion skipped: {exc}")
@@ -141,13 +141,13 @@ def customize_backends_config(*, is_first_time_setup: bool = False, target_confi
# Check if pipelex_gateway is selected and handle terms acceptance prompt
gateway_terms_accepted: bool | None = None
if PipelexBackend.GATEWAY in selected_backends:
- gateway_accepted = prompt_gateway_acceptance(console)
+ gateway_accepted = prompt_gateway_acceptance(console=console)
if gateway_accepted:
- display_gateway_accepted_message(console)
+ display_gateway_accepted_message(console=console)
gateway_terms_accepted = True
else:
- display_gateway_declined_message(console)
+ display_gateway_declined_message(console=console)
gateway_terms_accepted = False
# Remove pipelex_gateway from selected indices
diff --git a/pipelex/cli/commands/init/command.py b/pipelex/cli/commands/init/command.py
index 488d5b447..80ad0831d 100644
--- a/pipelex/cli/commands/init/command.py
+++ b/pipelex/cli/commands/init/command.py
@@ -58,7 +58,7 @@ class CachePrimingResult(BaseModel):
error_message: str | None = None
-def attempt_prime_remote_config_cache(target_config_dir: Path | None = None) -> CachePrimingResult:
+def attempt_prime_remote_config_cache(*, target_config_dir: Path | None = None) -> CachePrimingResult:
"""Prime the on-disk remote-config cache so later offline runs can fall back to it.
Pure-logic variant: no I/O on the way out, so both the interactive (`pipelex init`) and
@@ -126,7 +126,7 @@ def attempt_prime_remote_config_cache(target_config_dir: Path | None = None) ->
return CachePrimingResult(primed=True)
-def prime_remote_config_cache(console: Console, *, target_config_dir: Path | None = None) -> None:
+def prime_remote_config_cache(*, console: Console, target_config_dir: Path | None = None) -> None:
"""Interactive-surface wrapper around :func:`attempt_prime_remote_config_cache`.
Prints a yellow warning to the console when a fetch was attempted and failed; otherwise
@@ -141,7 +141,7 @@ def prime_remote_config_cache(console: Console, *, target_config_dir: Path | Non
console.print("[dim]Re-run 'pipelex init' while online to prime the cache for offline dry-runs.[/dim]")
-def _check_gateway_terms_if_needed(console: Console, *, backends_toml_path: Path) -> None:
+def _check_gateway_terms_if_needed(*, console: Console, backends_toml_path: Path) -> None:
"""Check if gateway is enabled and terms not yet accepted, then prompt for acceptance.
This is called after init_config() to ensure users who have gateway enabled
@@ -166,14 +166,14 @@ def _check_gateway_terms_if_needed(console: Console, *, backends_toml_path: Path
return
# Gateway is enabled but terms not accepted - prompt user
- gateway_accepted = prompt_gateway_acceptance(console)
+ gateway_accepted = prompt_gateway_acceptance(console=console)
config_manager.global_config_dir.mkdir(parents=True, exist_ok=True)
if gateway_accepted:
- display_gateway_accepted_message(console)
+ display_gateway_accepted_message(console=console)
update_service_terms_acceptance(accepted=True, config_dir=config_manager.global_config_dir)
else:
- display_gateway_declined_message(console)
+ display_gateway_declined_message(console=console)
update_service_terms_acceptance(accepted=False, config_dir=config_manager.global_config_dir)
# Actually disable the gateway in backends.toml
disable_gateway_backend(backends_toml_path)
@@ -217,8 +217,8 @@ def determine_needs(
def confirm_initialization(
- console: Console,
*,
+ console: Console,
needs_config: bool,
needs_inference: bool,
needs_routing: bool,
@@ -248,7 +248,7 @@ def confirm_initialization(
console.print()
console.print(
build_initialization_panel(
- needs_config,
+ needs_config=needs_config,
needs_inference=needs_inference,
needs_routing=needs_routing,
needs_telemetry=needs_telemetry,
@@ -275,8 +275,8 @@ def confirm_initialization(
def execute_initialization(
- console: Console,
*,
+ console: Console,
needs_config: bool,
needs_inference: bool,
needs_routing: bool,
@@ -329,7 +329,7 @@ def execute_initialization(
# If we're NOT going to run customize_backends_config (which handles gateway terms),
# we need to check if gateway is enabled and terms not accepted
if not needs_inference and backends_existed_before:
- _check_gateway_terms_if_needed(console, backends_toml_path=backends_toml_path)
+ _check_gateway_terms_if_needed(console=console, backends_toml_path=backends_toml_path)
# Determine if this is truly a first-time setup
first_time_setup = is_first_time_backends_setup
@@ -390,7 +390,7 @@ def execute_initialization(
# Step 2.5: Prompt for missing credentials
if check_credentials:
- prompt_credentials(console, backends_toml_path=backends_toml_path)
+ prompt_credentials(console=console, backends_toml_path=backends_toml_path)
# Step 3: Set up routing profile if specifically requested
if needs_routing:
@@ -419,12 +419,12 @@ def execute_initialization(
# No-op when gateway is disabled or terms have not been accepted. We forward
# ``target_config_dir`` so the gateway-enabled check inspects the directory we just
# initialized (matters for ``--local`` vs default init).
- prime_remote_config_cache(console, target_config_dir=target_config_dir)
+ prime_remote_config_cache(console=console, target_config_dir=target_config_dir)
console.print()
-def _init_agreement(console: Console) -> None:
+def _init_agreement(*, console: Console) -> None:
"""Handle the agreement-only initialization flow.
This prompts the user to accept Pipelex Gateway terms without resetting any configuration.
@@ -462,10 +462,10 @@ def _init_agreement(console: Console) -> None:
)
if accepted:
- display_gateway_accepted_message(console)
+ display_gateway_accepted_message(console=console)
update_service_terms_acceptance(accepted=True, config_dir=config_manager.global_config_dir)
else:
- display_gateway_declined_message(console)
+ display_gateway_declined_message(console=console)
update_service_terms_acceptance(accepted=False, config_dir=config_manager.global_config_dir)
# Disable the gateway since terms were declined
backends_toml_path = config_manager.pipelex_config_dir / "inference" / "backends.toml"
@@ -495,7 +495,7 @@ def init_cmd(
# Handle agreement-only flow separately (no reset needed)
if focus == InitFocus.AGREEMENT:
- _init_agreement(console)
+ _init_agreement(console=console)
return
# Handle credentials-only flow separately (no reset needed)
@@ -506,7 +506,7 @@ def init_cmd(
console.print("[yellow]No backends.toml found. Please run 'pipelex init' first.[/yellow]")
console.print()
return
- prompt_credentials(console, backends_toml_path=backends_toml_path)
+ prompt_credentials(console=console, backends_toml_path=backends_toml_path)
console.print()
return
diff --git a/pipelex/cli/commands/init/config_files.py b/pipelex/cli/commands/init/config_files.py
index 32ce95971..6e926eb3b 100644
--- a/pipelex/cli/commands/init/config_files.py
+++ b/pipelex/cli/commands/init/config_files.py
@@ -17,7 +17,7 @@ INIT_SKIP_FILES: frozenset[str] = GIT_IGNORED_CONFIG_FILES | {TELEMETRY_CONFIG_F
INIT_SKIP_DIRS: frozenset[str] = frozenset({"inference"})
-def init_config(reset: bool = False, *, dry_run: bool = False, target_dir: Path | None = None) -> int:
+def init_config(*, reset: bool = False, dry_run: bool = False, target_dir: Path | None = None) -> int:
"""Initialize pipelex configuration in the .pipelex directory. Does not install telemetry, just the main config and inference backends.
Args:
diff --git a/pipelex/cli/commands/init/credentials.py b/pipelex/cli/commands/init/credentials.py
index c7ab5b57a..7475c3082 100644
--- a/pipelex/cli/commands/init/credentials.py
+++ b/pipelex/cli/commands/init/credentials.py
@@ -101,7 +101,7 @@ def get_required_vars_for_enabled_backends(backends_toml_path: Path) -> dict[str
return var_to_backends
-def prompt_credentials(console: Console, *, backends_toml_path: Path) -> None:
+def prompt_credentials(*, console: Console, backends_toml_path: Path) -> None:
"""Prompt the user for missing credentials and persist them to ~/.pipelex/.env.
Reads the backends.toml to find which env vars are needed by enabled backends,
diff --git a/pipelex/cli/commands/init/ide_extension.py b/pipelex/cli/commands/init/ide_extension.py
index 91a0a9424..b1ff73412 100644
--- a/pipelex/cli/commands/init/ide_extension.py
+++ b/pipelex/cli/commands/init/ide_extension.py
@@ -86,7 +86,7 @@ def _install_extension(ide_name: str, *, cmd: str, console: Console) -> bool:
return False
-def suggest_extension_install_if_needed(console: Console) -> None:
+def suggest_extension_install_if_needed(*, console: Console) -> None:
"""Check whether the Pipelex IDE extension is installed and offer to install it.
Uses ``<cmd> --list-extensions`` to reliably detect whether the extension
diff --git a/pipelex/cli/commands/init/routing.py b/pipelex/cli/commands/init/routing.py
index 3962b2f06..224e4e46c 100644
--- a/pipelex/cli/commands/init/routing.py
+++ b/pipelex/cli/commands/init/routing.py
@@ -55,7 +55,7 @@ def customize_routing_profile(selected_backend_keys: list[str], *, target_config
if PipelexBackend.GATEWAY in selected_backend_keys:
toml_doc["active"] = PipelexRoutingProfile.ALL_PIPELEX_GATEWAY
save_toml_to_path(toml_doc, path=routing_profiles_toml_path)
- display_routing_profile_result(console, profile_name=PipelexRoutingProfile.ALL_PIPELEX_GATEWAY, created=False)
+ display_routing_profile_result(console=console, profile_name=PipelexRoutingProfile.ALL_PIPELEX_GATEWAY, created=False)
return
# Case 2: Only one backend selected - use all_{backend_key} profile
@@ -89,7 +89,7 @@ def customize_routing_profile(selected_backend_keys: list[str], *, target_config
# Set as active profile
toml_doc["active"] = profile_name
save_toml_to_path(toml_doc, path=routing_profiles_toml_path)
- display_routing_profile_result(console, profile_name=profile_name, created=not profile_exists)
+ display_routing_profile_result(console=console, profile_name=profile_name, created=not profile_exists)
return
# Case 3: Multiple backends (no pipelex_gateway) - create/update custom_routing profile
@@ -109,7 +109,7 @@ def customize_routing_profile(selected_backend_keys: list[str], *, target_config
console.print()
console.print(build_fallback_order_panel(remaining_backends, backend_options=backend_options))
# Get the ordered remaining backends from user (default keeps current order)
- ordered_remaining = prompt_fallback_order(console, remaining_backends=remaining_backends, backend_options=backend_options)
+ ordered_remaining = prompt_fallback_order(console=console, remaining_backends=remaining_backends, backend_options=backend_options)
fallback_order = [primary_backend, *ordered_remaining]
elif len(remaining_backends) == 1:
# Only one remaining backend - set fallback_order with primary first
@@ -145,7 +145,7 @@ def customize_routing_profile(selected_backend_keys: list[str], *, target_config
toml_doc["active"] = "custom_routing"
save_toml_to_path(toml_doc, path=routing_profiles_toml_path)
- display_routing_profile_result(console, profile_name="custom_routing", created=True)
+ display_routing_profile_result(console=console, profile_name="custom_routing", created=True)
# Inform user about customization options
console.print("[dim]You can find your custom routing profile in:[/dim]")
diff --git a/pipelex/cli/commands/init/ui/backends_ui.py b/pipelex/cli/commands/init/ui/backends_ui.py
index 81ea68fe4..16006c2ef 100644
--- a/pipelex/cli/commands/init/ui/backends_ui.py
+++ b/pipelex/cli/commands/init/ui/backends_ui.py
@@ -153,11 +153,7 @@ def build_backend_selection_panel(
def prompt_backend_select(
- console: Console,
- *,
- backend_options: list[tuple[str, str]],
- currently_enabled: list[int] | None = None,
- is_first_time_setup: bool = False,
+ *, console: Console, backend_options: list[tuple[str, str]], currently_enabled: list[int] | None = None, is_first_time_setup: bool = False
) -> tuple[list[int], set[str]]:
"""Prompt user to select backend indices with validation.
diff --git a/pipelex/cli/commands/init/ui/gateway_ui.py b/pipelex/cli/commands/init/ui/gateway_ui.py
index 7d66086ce..d4752deb5 100644
--- a/pipelex/cli/commands/init/ui/gateway_ui.py
+++ b/pipelex/cli/commands/init/ui/gateway_ui.py
@@ -91,7 +91,7 @@ def build_gateway_terms_panel() -> Panel:
)
-def prompt_gateway_acceptance(console: Console) -> bool:
+def prompt_gateway_acceptance(*, console: Console) -> bool:
"""Prompt the user to accept Pipelex Gateway terms.
Args:
@@ -111,7 +111,7 @@ def prompt_gateway_acceptance(console: Console) -> bool:
)
-def display_gateway_declined_message(console: Console) -> None:
+def display_gateway_declined_message(*, console: Console) -> None:
"""Display message when user declines gateway terms.
Args:
@@ -133,7 +133,7 @@ def display_gateway_declined_message(console: Console) -> None:
console.print(f"[dim]Need help? Visit {URLs.documentation} or join {URLs.discord}[/dim]")
-def display_gateway_accepted_message(console: Console) -> None:
+def display_gateway_accepted_message(*, console: Console) -> None:
"""Display confirmation message when user accepts gateway terms.
Args:
diff --git a/pipelex/cli/commands/init/ui/general_ui.py b/pipelex/cli/commands/init/ui/general_ui.py
index 80a86feb9..6fdc9cb42 100644
--- a/pipelex/cli/commands/init/ui/general_ui.py
+++ b/pipelex/cli/commands/init/ui/general_ui.py
@@ -4,8 +4,8 @@ from rich.panel import Panel
def build_initialization_panel(
- needs_config: bool,
*,
+ needs_config: bool,
needs_inference: bool,
needs_routing: bool,
needs_telemetry: bool,
diff --git a/pipelex/cli/commands/init/ui/routing_ui.py b/pipelex/cli/commands/init/ui/routing_ui.py
index 9efa7dbeb..640bd0d11 100644
--- a/pipelex/cli/commands/init/ui/routing_ui.py
+++ b/pipelex/cli/commands/init/ui/routing_ui.py
@@ -124,7 +124,7 @@ def build_fallback_order_panel(remaining_backends: list[str], *, backend_options
)
-def prompt_fallback_order(console: Console, *, remaining_backends: list[str], backend_options: list[tuple[str, str]]) -> list[str]:
+def prompt_fallback_order(*, console: Console, remaining_backends: list[str], backend_options: list[tuple[str, str]]) -> list[str]:
"""Prompt user to order the remaining backends for fallback.
Args:
@@ -195,7 +195,7 @@ def prompt_fallback_order(console: Console, *, remaining_backends: list[str], ba
return fallback_order
-def display_routing_profile_result(console: Console, *, profile_name: str, created: bool = False) -> None:
+def display_routing_profile_result(*, console: Console, profile_name: str, created: bool = False) -> None:
"""Display confirmation of routing profile configuration.
Args:
diff --git a/pipelex/cli/commands/run/_inputs_file_loader.py b/pipelex/cli/commands/run/_inputs_file_loader.py
index eb39cf900..dde781f84 100644
--- a/pipelex/cli/commands/run/_inputs_file_loader.py
+++ b/pipelex/cli/commands/run/_inputs_file_loader.py
@@ -80,7 +80,7 @@ def resolve_inputs_arg_against_dir(inputs_arg: str | None, *, base_dir: Path) ->
return str(base_dir / inputs_path)
-def find_default_inputs_file(directory: Path) -> Path | None:
+def find_default_inputs_file(*, directory: Path) -> Path | None:
"""Probe a bundle directory for the default inputs file (JSON or TOML).
Args:
diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.py
index d19fcd70c..2862ba63b 100644
--- a/pipelex/cli/commands/run/_run_core.py
+++ b/pipelex/cli/commands/run/_run_core.py
@@ -75,8 +75,8 @@ def validate_run_flag_combination(*, dry_run: bool, mock_usage: bool, mock_input
async def _execute_run(
- pipe_code: str | None,
*,
+ pipe_code: str | None,
bundle_path: str | None,
inputs: str | None,
save_working_memory: bool,
@@ -129,11 +129,11 @@ async def _execute_run(
raise typer.Exit(1)
pipe_code = main_pipe_code
except FileNotFoundError as exc:
- print_traceback_if_requested(get_console())
+ print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to load bundle '{bundle_path}': {exc}", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from exc
except PipelexInterpreterError as exc:
- print_traceback_if_requested(get_console())
+ print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to parse bundle '{bundle_path}': {exc}", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from exc
elif not pipe_code:
@@ -150,7 +150,7 @@ async def _execute_run(
try:
pipeline_inputs = json.loads(inputs)
except json.JSONDecodeError as json_decode_exc:
- print_traceback_if_requested(get_console())
+ print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to parse inline JSON inputs: {json_decode_exc}", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from json_decode_exc
else:
@@ -166,19 +166,19 @@ async def _execute_run(
pipeline_inputs = resolve_inputs_paths(pipeline_inputs, base_dir=inputs_base_dir)
typer.echo(f"Loaded inputs from: {inputs}")
except FileNotFoundError as file_not_found_exc:
- print_traceback_if_requested(get_console())
+ print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to load input file '{inputs}': file not found", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from file_not_found_exc
except json.JSONDecodeError as json_decode_exc:
- print_traceback_if_requested(get_console())
+ print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to parse input file '{inputs}': invalid JSON: {json_decode_exc}", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from json_decode_exc
except JsonTypeError as json_type_error_exc:
- print_traceback_if_requested(get_console())
+ print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to parse input file '{inputs}': must be a valid JSON dictionary", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from json_type_error_exc
except TomlError as toml_error_exc:
- print_traceback_if_requested(get_console())
+ print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to parse input file: {toml_error_exc.message}", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from toml_error_exc
@@ -210,11 +210,11 @@ async def _execute_run(
)
pipe_output = response.pipe_output
except PipelineExecutionError as exc:
- print_traceback_if_requested(get_console())
+ print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to execute pipeline '{exc.pipe_code}': {exc}", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from exc
except PipelexError as exc:
- print_traceback_if_requested(get_console())
+ print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to execute pipeline '{pipe_code or bundle_path}': {exc}", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from exc
@@ -385,8 +385,8 @@ async def _execute_run(
def execute_run(
- pipe_code: str | None,
*,
+ pipe_code: str | None,
bundle_path: str | None,
inputs: str | None,
save_working_memory: bool,
@@ -450,7 +450,7 @@ def execute_run(
except PipelexError as exc:
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print("\n[bold red]Failed to execute pipeline[/bold red]\n")
console.print(f" {exc.message}\n")
raise typer.Exit(1) from exc
diff --git a/pipelex/cli/commands/run/bundle_cmd.py b/pipelex/cli/commands/run/bundle_cmd.py
index c72346487..2c0233ff8 100644
--- a/pipelex/cli/commands/run/bundle_cmd.py
+++ b/pipelex/cli/commands/run/bundle_cmd.py
@@ -150,7 +150,7 @@ def run_bundle_cmd(
# Auto-detect inputs (inputs.json or inputs.toml) if --inputs not explicitly provided
if not inputs:
try:
- inputs_file = find_default_inputs_file(target_path)
+ inputs_file = find_default_inputs_file(directory=target_path)
except AmbiguousInputsFilesError as ambiguity_exc:
typer.secho(f"Failed to run: {ambiguity_exc.message}", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from ambiguity_exc
diff --git a/pipelex/cli/commands/show_cmd.py b/pipelex/cli/commands/show_cmd.py
index d214a855a..5687ac523 100644
--- a/pipelex/cli/commands/show_cmd.py
+++ b/pipelex/cli/commands/show_cmd.py
@@ -69,7 +69,7 @@ def do_show_pipe(pipe_code: str) -> None:
pretty_print(pipe, title=f"Pipe '{pipe_code}'")
-def do_show_backends(show_all: bool = False) -> None:
+def do_show_backends(*, show_all: bool = False) -> None:
"""Display all backends and the active routing profile."""
try:
secrets_provider = get_secrets_provider()
diff --git a/pipelex/cli/commands/update_cmd.py b/pipelex/cli/commands/update_cmd.py
index a54fd5bd8..ca40a94d5 100644
--- a/pipelex/cli/commands/update_cmd.py
+++ b/pipelex/cli/commands/update_cmd.py
@@ -32,8 +32,8 @@ from pipelex.system.configuration.config_loader import config_manager
def update_cmd(
- local: bool = False,
*,
+ local: bool = False,
yes: bool = False,
dry_run: bool = False,
no_backup: bool = False,
@@ -88,7 +88,7 @@ def update_cmd(
console.print()
-def _resolve_deck_dir(local: bool) -> Path:
+def _resolve_deck_dir(*, local: bool) -> Path:
"""Pick the deck directory to operate on, mirroring the ``--local`` semantics of ``pipelex init``."""
if local:
project_root = config_manager.project_root
diff --git a/pipelex/cli/commands/validate/_validate_core.py b/pipelex/cli/commands/validate/_validate_core.py
index 29531a805..4613d20bc 100644
--- a/pipelex/cli/commands/validate/_validate_core.py
+++ b/pipelex/cli/commands/validate/_validate_core.py
@@ -48,7 +48,7 @@ if TYPE_CHECKING:
COMMAND = "validate"
-def _echo_optionality_warnings(pipes: list[PipeAbstract]) -> None:
+def _echo_optionality_warnings(*, pipes: list[PipeAbstract]) -> None:
"""Render the advisory optionality lints (e.g. the useless-`!` lint) in yellow.
Advisory only — a warning never changes the validation verdict or the exit code. Requires
@@ -58,7 +58,7 @@ def _echo_optionality_warnings(pipes: list[PipeAbstract]) -> None:
typer.secho(f"Warning: {warning.message}", fg=typer.colors.YELLOW)
-def _format_signatures_summary_suffix(signature_count: int) -> str:
+def _format_signatures_summary_suffix(*, signature_count: int) -> str:
"""Return the suffix appended to lenient-mode validation summaries.
Empty when no signatures were involved so fully-implemented bundles read naturally.
@@ -70,11 +70,7 @@ def _format_signatures_summary_suffix(signature_count: int) -> str:
return f" ({signature_count} signatures)"
-def do_validate_all_libraries_and_dry_run(
- library_dirs: list[Path] | None = None,
- *,
- allow_signatures: bool = False,
-) -> None:
+def do_validate_all_libraries_and_dry_run(*, library_dirs: list[Path] | None = None, allow_signatures: bool = False) -> None:
try:
with get_telemetry_manager().telemetry_context():
tag(name=EventProperty.INTEGRATION, value=IntegrationMode.CLI)
@@ -93,7 +89,7 @@ def do_validate_all_libraries_and_dry_run(
pipes = all_pipes if allow_signatures else [pipe for pipe in all_pipes if not pipe.is_signature]
if library_dirs:
dirs_str = ", ".join(f'"{lib_dir}"' for lib_dir in library_dirs)
- typer.echo(f"Validating {count_with_noun(len(pipes), singular='pipe')} from: {dirs_str}")
+ typer.echo(f"Validating {count_with_noun(count=len(pipes), singular='pipe')} from: {dirs_str}")
# validate_current_library owns the static wiring pass and the single PIPE_DRY_RUN telemetry
# event — sweeping the library we just loaded, without teardown.
@@ -101,7 +97,7 @@ def do_validate_all_libraries_and_dry_run(
# Advisory optionality lints over the whole loaded library (the lint's cross-flow
# aggregation needs every flow) — printed even when the signature gate below exits non-zero.
- _echo_optionality_warnings(all_pipes)
+ _echo_optionality_warnings(pipes=all_pipes)
# Gate-from-report (D-B consumer-decides): signatures are never a validation error, but a
# library with unsatisfied PipeSignature placeholders is valid yet NOT runnable. `validate
@@ -120,7 +116,9 @@ def do_validate_all_libraries_and_dry_run(
raise typer.Exit(1)
signature_count = sum(1 for pipe in all_pipes if pipe.is_signature)
- typer.echo(f"Setup sequence passed OK, config and pipelines are validated.{_format_signatures_summary_suffix(signature_count)}")
+ typer.echo(
+ f"Setup sequence passed OK, config and pipelines are validated.{_format_signatures_summary_suffix(signature_count=signature_count)}"
+ )
except PipeOperatorModelAvailabilityError as exc:
handle_model_availability_error(exc, context=ErrorContext.VALIDATION, exit_code=2)
except PipeOperatorModelChoiceError as exc:
@@ -128,11 +126,7 @@ def do_validate_all_libraries_and_dry_run(
async def _validate_pipe_or_bundle(
- pipe_code: str | None = None,
- *,
- bundle_path: Path | None = None,
- library_dirs: list[Path] | None = None,
- allow_signatures: bool = False,
+ *, pipe_code: str | None = None, bundle_path: Path | None = None, library_dirs: list[Path] | None = None, allow_signatures: bool = False
) -> None:
"""Core async validation logic shared between method and pipe subcommands."""
if bundle_path:
@@ -156,12 +150,12 @@ async def _validate_pipe_or_bundle(
raise typer.Exit(1)
signature_count = sum(1 for pipe in bundle_result.pipes if pipe.is_signature)
typer.secho(
- f"Successfully validated bundle '{bundle_path}'{_format_signatures_summary_suffix(signature_count)}",
+ f"Successfully validated bundle '{bundle_path}'{_format_signatures_summary_suffix(signature_count=signature_count)}",
fg=typer.colors.GREEN,
)
# validate_bundle leaves its validation library open on success, so the taint walk
# behind the advisory lints can still resolve the bundle's pipes.
- _echo_optionality_warnings(bundle_result.pipes)
+ _echo_optionality_warnings(pipes=bundle_result.pipes)
except FileNotFoundError as exc:
get_console().print(Traceback())
typer.secho(
@@ -193,7 +187,7 @@ async def _validate_pipe_or_bundle(
)
signature_count = len(collect_signature_refs(pipe=pipe))
typer.secho(
- f"Successfully validated pipe '{pipe_code}'{_format_signatures_summary_suffix(signature_count)}",
+ f"Successfully validated pipe '{pipe_code}'{_format_signatures_summary_suffix(signature_count=signature_count)}",
fg=typer.colors.GREEN,
)
else:
@@ -206,8 +200,8 @@ async def _validate_pipe_or_bundle(
def execute_validate(
- pipe_code: str | None,
*,
+ pipe_code: str | None,
bundle_path: Path | None,
library_dirs: list[Path] | None,
telemetry_command_label: str = COMMAND,
diff --git a/pipelex/cli/dev_cli/_dev_cli.py b/pipelex/cli/dev_cli/_dev_cli.py
index 7d5fe151e..20d207017 100644
--- a/pipelex/cli/dev_cli/_dev_cli.py
+++ b/pipelex/cli/dev_cli/_dev_cli.py
@@ -16,11 +16,13 @@ from pipelex.cli.dev_cli.commands.check_keyword_only_cmd import check_keyword_on
from pipelex.cli.dev_cli.commands.check_mthds_schema_cmd import check_mthds_schema_cmd
from pipelex.cli.dev_cli.commands.check_rules_sync_cmd import check_rules_sync_cmd
from pipelex.cli.dev_cli.commands.check_urls_cmd import DEFAULT_TIMEOUT, check_urls_cmd
+from pipelex.cli.dev_cli.commands.drift.drift_cmd import drift_app
from pipelex.cli.dev_cli.commands.generate_error_pages_cmd import generate_error_pages_cmd
from pipelex.cli.dev_cli.commands.generate_mthds_schema_cmd import generate_mthds_schema_cmd
from pipelex.cli.dev_cli.commands.kit_cmd import kit_app
from pipelex.cli.dev_cli.commands.preprocess_test_models_cmd import preprocess_test_models_cmd
from pipelex.cli.dev_cli.commands.refresh_graph_ui_sri_cmd import refresh_graph_ui_sri_cmd
+from pipelex.cli.dev_cli.commands.subject_grant_cmd import subject_grant_cmd
from pipelex.cli.dev_cli.commands.sync_kit_configs_cmd import sync_kit_configs_cmd
from pipelex.cli.dev_cli.commands.sync_main_config_cmd import SyncTarget, sync_main_config_cmd
from pipelex.cli.dev_cli.commands.update_gateway_models_cmd import update_gateway_models_cmd
@@ -41,11 +43,13 @@ class PipelexDevCLI(TyperGroup):
"check-mthds-schema",
"check-rules",
"check-urls",
+ "drift",
"generate-error-pages",
"generate-mthds-schema",
"kit",
"preprocess-test-models",
"refresh-graph-ui-sri",
+ "subject-grant",
"sync-kit-configs",
"sync-main-config",
"update-gateway-models",
@@ -74,6 +78,7 @@ app = typer.Typer(
cls=PipelexDevCLI,
)
+app.add_typer(drift_app, name="drift", help="Drift contracts: deterministic review obligations between code, docs, and tests")
app.add_typer(kit_app, name="kit", help="Manage agent rules for the Pipelex repository")
@@ -281,6 +286,34 @@ def check_keyword_only_command(
sys.exit(1)
[email protected](name="subject-grant", help="Record a subject grant in subject_grants.toml (keyword-only convention)")
+def subject_grant_command(
+ func_key: Annotated[
+ str | None,
+ typer.Argument(help='The def to grant, keyed "<relative_path>::<qualified_name>" (e.g. "pipelex/graph/render.py::render_node")'),
+ ] = None,
+ rationale: Annotated[
+ str | None,
+ typer.Option("--rationale", help="The on-the-record review decision — an honest, def-specific sentence"),
+ ] = None,
+ quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Output only a single status line")] = False,
+) -> None:
+ """Record a subject grant — the explicit permission for a def's positional subject parameter."""
+ try:
+ subject_grant_cmd(func_key=func_key, rationale=rationale, quiet=quiet)
+ except (typer.Exit, typer.Abort):
+ # Typer control-flow exits carry an intended exit code — not a failure. Let them through.
+ raise
+ except Exception: # noqa: BLE001
+ # Dev CLI command root: print a traceback for any unexpected failure and exit non-zero.
+ console = get_console()
+ console.print()
+ console.print("[bold red]Unexpected error occurred[/bold red]")
+ console.print()
+ console.print(Traceback())
+ sys.exit(1)
+
+
@app.command(name="sync-main-config", help="Sync main config values to kit and project configs")
def sync_main_config_command(
target: Annotated[
diff --git a/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py b/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py
index 5bcf48841..996bd51ae 100644
--- a/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py
@@ -22,8 +22,8 @@ class LeadingConfig(StrEnum):
def check_config_sync_cmd(
- show_diff: bool = True,
*,
+ show_diff: bool = True,
leading: LeadingConfig = LeadingConfig.INSTALLED,
quiet: bool = False,
) -> None:
diff --git a/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py b/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py
index 2cfa7d698..3786864bf 100644
--- a/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py
@@ -25,7 +25,7 @@ if TYPE_CHECKING:
from rich.console import Console
-def check_gateway_models_cmd(show_diff: bool = True, *, quiet: bool = False) -> None:
+def check_gateway_models_cmd(*, show_diff: bool = True, quiet: bool = False) -> None:
"""Verify that the Pipelex Gateway models reference files are up-to-date.
Compares the existing reference files — both the .pipelex/ copies and the
diff --git a/pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py b/pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py
index ddeaa9239..0975bc688 100644
--- a/pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py
@@ -1,14 +1,16 @@
"""Command enforcing the keyword-only-arguments convention across ``pipelex/`` source.
Non-subject function parameters must be keyword-only so call sites are self-documenting:
-``do_thing(retries=3, timeout=30)`` is forced over the opaque ``do_thing(3, 30)``.
+``do_thing(retries=3, timeout=30)`` is forced over the opaque ``do_thing(3, 30)``. A positional
+subject is legal only under an explicit grant recorded in ``subject_grants.toml`` (see the
+``subject-grant`` command), and a ``bool``/``int``/``float`` subject is banned outright.
The canonical human-readable specification lives in ``docs/contribute/keyword-only-arguments.md``.
The pure-AST collection logic lives in the stdlib-only ``keyword_only_guard`` module; this module
is the ``rich``/``pipelex.hub`` presentation layer wired into the ``pipelex-dev`` Typer app
(``make check-keyword-only`` / ``make agent-check`` / CI). The ``pipelex/`` source tree is fully
-compliant, so the guard hard-blocks on ANY violation (a bare ``*`` after the subject, or a
-``# kw-only: ignore`` escape hatch with a justification, is required).
+compliant, so the guard hard-blocks on ANY violation (a bare ``*`` after the subject, a recorded
+subject grant, or a ``# kw-only: ignore`` escape hatch with a justification, is required).
The read-only check (``check-keyword-only``, no flag) is the gate; ``--fix`` only mutates and reports.
``--fix`` never exits non-zero on remaining violations, so ``agent-check`` runs it early (fixing before
@@ -19,25 +21,48 @@ enforce. ``make check`` / CI gate with the read-only check and never mutate.
from __future__ import annotations
import sys
+from typing import TYPE_CHECKING
from rich.markup import escape
from rich.panel import Panel
-from pipelex.cli.dev_cli.commands.keyword_only_guard import SOURCE_ROOT, Violation, collect_all_violations, fix_all_violations
+from pipelex.cli.dev_cli.commands.keyword_only_guard import (
+ SOURCE_ROOT,
+ SubjectGrantRegistryError,
+ Violation,
+ collect_all_violations,
+ fix_all_violations,
+ load_subject_grants,
+)
from pipelex.hub import get_console
+if TYPE_CHECKING:
+ from pipelex.cli.dev_cli.commands.keyword_only_guard import SubjectGrant
+
# --------------------------------------------------------------------------------------
# Command entrypoint
# --------------------------------------------------------------------------------------
-def _print_report(violations: list[Violation]) -> None:
- """Print the full inventory grouped by top-level package."""
+def _package_of(key_or_path: str) -> str:
+ """The top-level package of a ``pipelex/...`` path or ``<path>::<qualname>`` key, for report grouping.
+
+ Files sitting directly under the source root (``pipelex/hub.py``) group under ``(root)`` rather than
+ each filename becoming its own one-off "package" line in the report.
+ """
+ path = key_or_path.partition("::")[0]
+ parts = path.split("/")
+ if len(parts) > 2:
+ return parts[1]
+ return "(root)" if len(parts) == 2 else path
+
+
+def _print_report(violations: list[Violation], *, grants: dict[str, SubjectGrant]) -> None:
+ """Print the full inventory grouped by top-level package, plus the per-package grant counts."""
console = get_console()
grouped: dict[str, list[Violation]] = {}
for violation in violations:
- package = violation.relative_path.split("/")[1] if "/" in violation.relative_path else violation.relative_path
- grouped.setdefault(package, []).append(violation)
+ grouped.setdefault(_package_of(violation.relative_path), []).append(violation)
console.print()
console.print("[bold]Keyword-only convention — full inventory[/bold]")
console.print()
@@ -45,26 +70,53 @@ def _print_report(violations: list[Violation]) -> None:
package_violations = grouped[package]
console.print(f"[bold cyan]{escape(package)}[/bold cyan] ([dim]{len(package_violations)}[/dim])")
for violation in package_violations:
- console.print(f" {escape(violation.relative_path)}:{violation.lineno} [dim]{escape(violation.qualified_name)}[/dim]")
+ console.print(
+ f" {escape(violation.relative_path)}:{violation.lineno} [dim]{escape(violation.qualified_name)}[/dim]"
+ f" [yellow]{escape(violation.kind)}[/yellow]"
+ )
console.print()
- console.print(f"[bold]Total:[/bold] {len(violations)}")
+ console.print(f"[bold]Total violations:[/bold] {len(violations)}")
console.print()
+ grant_totals: dict[str, int] = {}
+ for key in grants:
+ package = _package_of(key)
+ grant_totals[package] = grant_totals.get(package, 0) + 1
+ console.print("[bold]Subject grants by package[/bold]")
+ console.print()
+ for package in sorted(grant_totals):
+ console.print(f" [bold cyan]{escape(package)}[/bold cyan] {grant_totals[package]} grant(s)")
+ console.print()
+ console.print(f"[bold]Grants total:[/bold] {len(grants)}")
+ console.print()
+
+
+def _load_grants_or_exit() -> dict[str, SubjectGrant]:
+ """Load the subject-grants registry, or exit 1 with the explicit error (never a silent empty registry)."""
+ try:
+ return load_subject_grants()
+ except SubjectGrantRegistryError as exc:
+ console = get_console()
+ console.print(f"[red]✗ Keyword-only check: FAILED[/red] - {escape(str(exc))}")
+ sys.exit(1)
+
def check_keyword_only_cmd(*, report: bool = False, fix: bool = False, quiet: bool = False) -> None:
"""Enforce the keyword-only-arguments convention across ``pipelex/`` source.
The source tree is fully compliant, so the guard hard-blocks on ANY violation. The only
- sanctioned non-compliant signatures are the explicit carve-outs and the ``# kw-only: ignore``
- escape hatch (see ``docs/contribute/keyword-only-arguments.md``).
+ sanctioned non-compliant signatures are the explicit carve-outs, the granted positional
+ subjects recorded in ``subject_grants.toml``, and the ``# kw-only: ignore`` escape hatch
+ (see ``docs/contribute/keyword-only-arguments.md``).
Args:
- report: If True, print the full inventory grouped by package (no pass/fail gating).
+ report: If True, print the full inventory grouped by package plus the per-package
+ grant counts (no pass/fail gating).
fix: If True, auto-fix every mechanically-fixable violation by inserting a bare ``*`` as far
- left as possible (right after ``self``/``cls``) so every other parameter becomes keyword-only,
- then report what was fixed and what still needs a manual fix. Non-gating — it reports the
- unfixable ones but exits 0; the read-only check (run last in ``agent-check`` and in
- ``make check`` / CI) enforces compliance. Takes precedence over ``report``.
+ left as possible (right after ``self``/``cls``) so every non-``self``/``cls`` parameter becomes
+ keyword-only, then report what was fixed and what still needs a manual fix. Non-gating — it
+ reports the unfixable ones but exits 0; the read-only check (run last in ``agent-check`` and
+ in ``make check`` / CI) enforces compliance. Takes precedence over ``report``.
quiet: If True, keep the success output to a single line (for Make targets / CI). Quiet
only trims the happy path — a failure still prints the full actionable violation list.
"""
@@ -75,14 +127,16 @@ def check_keyword_only_cmd(*, report: bool = False, fix: bool = False, quiet: bo
console.print("[red]✗ Keyword-only check: FAILED[/red] - source root [cyan]pipelex/[/cyan] does not exist")
sys.exit(1)
+ grants = _load_grants_or_exit()
+
if fix:
- _run_fix(quiet=quiet)
+ _run_fix(quiet=quiet, grants=grants)
return
- violations = collect_all_violations(SOURCE_ROOT)
+ violations = collect_all_violations(SOURCE_ROOT, grants=grants)
if report:
- _print_report(violations)
+ _print_report(violations, grants=grants)
return
if not violations:
@@ -102,7 +156,7 @@ def check_keyword_only_cmd(*, report: bool = False, fix: bool = False, quiet: bo
sys.exit(1)
-def _run_fix(*, quiet: bool) -> None:
+def _run_fix(*, quiet: bool, grants: dict[str, SubjectGrant]) -> None:
"""Auto-fix path: insert a bare ``*`` for every fixable violation, then report the outcome.
Non-gating by design: it mutates and reports but never exits non-zero on remaining (unfixable)
@@ -113,7 +167,7 @@ def _run_fix(*, quiet: bool) -> None:
still exits non-zero — that is handled by the caller, not here.
"""
console = get_console()
- fixed, unfixable = fix_all_violations(SOURCE_ROOT)
+ fixed, unfixable = fix_all_violations(SOURCE_ROOT, grants=grants)
if fixed:
# Files changed — always surface this, even in quiet mode.
@@ -121,22 +175,24 @@ def _run_fix(*, quiet: bool) -> None:
f"[green]✓ Auto-fixed {len(fixed)} keyword-only violation(s)[/green] "
"(inserted a bare `*` after self/cls so every other parameter is keyword-only):"
)
- _print_violation_lines(fixed)
+ _print_violation_lines(violations=fixed)
console.print(
"[dim]Verify with `make agent-test` — the guard can't see framework-positional callers, "
- "so a wrongly keyword-only'd call site only fails at runtime.[/dim]"
+ "so a wrongly keyword-only'd call site only fails at runtime. If a fixed def deserved its "
+ "positional subject, revert it and record a grant (`make subject-grant`) instead.[/dim]"
)
if unfixable:
# Reported, not gated here — the read-only `check-keyword-only` (last in agent-check / CI) fails on these.
console.print(
f"[red]✗ {len(unfixable)} violation(s) need a manual fix[/red] "
- "(e.g. `*args` present, an existing keyword-only section, or two+ positional-only params):"
+ "(e.g. `*args` present, an existing keyword-only section, two+ positional-only params, or a stale grant):"
)
- _print_violation_lines(unfixable)
+ _print_violation_lines(violations=unfixable)
console.print(
- "[dim]Place the bare `*` by hand, or add `# kw-only: ignore` on the def line if justified — "
- "`make check-keyword-only` (and CI) will fail until then. See docs/contribute/keyword-only-arguments.md[/dim]"
+ "[dim]Fix each by hand (its remedy is shown by `make check-keyword-only`), or add `# kw-only: ignore` "
+ "on the def line if justified — `make check-keyword-only` (and CI) will fail until then. "
+ "See docs/contribute/keyword-only-arguments.md[/dim]"
)
if not fixed and not unfixable:
@@ -163,38 +219,47 @@ def _print_success_panel() -> None:
def _print_failure_panel(*, violations: list[Violation]) -> None:
- """Verbose failure output with a per-violation file:line list."""
+ """Verbose failure output with a per-violation file:line list grouped by kind."""
console = get_console()
console.print()
console.print(
Panel(
f"[red]✗[/red] {len(violations)} keyword-only violation(s) found.\n\n"
- "[dim]Non-subject parameters must be keyword-only — place a bare `*` before them, "
- "or add `# kw-only: ignore` on the def line if genuinely justified.[/dim]",
+ "[dim]Non-subject parameters must be keyword-only, and a positional subject needs a recorded "
+ "grant — each violation kind below names its remedy.[/dim]",
title="[bold red]Keyword-only Check: FAILED[/bold red]",
border_style="red",
padding=(1, 2),
)
)
console.print()
- console.print("[bold]Violations:[/bold]")
- _print_violation_lines(violations)
- console.print()
+ _print_violations_by_kind(violations=violations)
def _print_failure_quiet(*, violations: list[Violation]) -> None:
- """Compact failure output for quiet mode: a status line, the actionable file:line list, one remedy hint."""
+ """Compact failure output for quiet mode: a status line, then the actionable per-kind violation list."""
console = get_console()
console.print(f"[red]✗ Keyword-only check: FAILED[/red] - {len(violations)} violation(s):")
- _print_violation_lines(violations)
- console.print(
- "[dim]Place a bare `*` so non-subject parameters are keyword-only (or run `make fix-keyword-only`), "
- "or add `# kw-only: ignore` if justified — see docs/contribute/keyword-only-arguments.md[/dim]"
- )
+ _print_violations_by_kind(violations=violations)
+
+
+def _print_violations_by_kind(*, violations: list[Violation]) -> None:
+ """Print the violations grouped by kind, each group headed by its remedy."""
+ console = get_console()
+ grouped: dict[str, list[Violation]] = {}
+ for violation in violations:
+ grouped.setdefault(violation.kind, []).append(violation)
+ for kind_value in sorted(grouped):
+ kind_violations = grouped[kind_value]
+ kind = kind_violations[0].kind
+ console.print(f"[bold]{escape(kind_value)}[/bold] ({len(kind_violations)}) — [dim]{escape(kind.remedy)}[/dim]")
+ _print_violation_lines(violations=kind_violations)
+ console.print("[dim]See docs/contribute/keyword-only-arguments.md[/dim]")
-def _print_violation_lines(violations: list[Violation]) -> None:
+def _print_violation_lines(*, violations: list[Violation]) -> None:
"""Print one ``file:line qualified_name`` row per violation."""
console = get_console()
for violation in violations:
- console.print(f" [red]{escape(violation.relative_path)}:{violation.lineno}[/red] [dim]{escape(violation.qualified_name)}[/dim]")
+ detail = f" [yellow]{escape(violation.detail)}[/yellow]" if violation.detail else ""
+ console.print(f" [red]{escape(violation.relative_path)}:{violation.lineno}[/red] [dim]{escape(violation.qualified_name)}[/dim]{detail}")
diff --git a/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py b/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py
index 37a9cd261..a59d8f36b 100644
--- a/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py
@@ -18,7 +18,7 @@ if TYPE_CHECKING:
from rich.console import Console
-def check_mthds_schema_cmd(show_diff: bool = True, *, quiet: bool = False) -> None:
+def check_mthds_schema_cmd(*, show_diff: bool = True, quiet: bool = False) -> None:
"""Verify that the MTHDS JSON Schema file is up-to-date.
Regenerates the schema in memory and compares it against the on-disk file.
diff --git a/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py b/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py
index c430903e4..df34804b4 100644
--- a/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py
@@ -37,7 +37,7 @@ def _get_preferred_targets_from_toml() -> list[AgentTarget]:
return parsed_targets or _DEFAULT_TARGETS
-def check_rules_sync_cmd(show_diff: bool = True, *, quiet: bool = False) -> None:
+def check_rules_sync_cmd(*, show_diff: bool = True, quiet: bool = False) -> None:
"""Verify that installed agent rules match kit templates.
Args:
diff --git a/pipelex/cli/dev_cli/commands/check_urls_cmd.py b/pipelex/cli/dev_cli/commands/check_urls_cmd.py
index c46c184f9..ae64d85e1 100644
--- a/pipelex/cli/dev_cli/commands/check_urls_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_urls_cmd.py
@@ -60,12 +60,7 @@ def get_all_urls_from_class() -> list[tuple[str, str]]:
return url_pairs
-async def check_single_url_async(
- client: httpx.AsyncClient,
- *,
- name: str,
- url: str,
-) -> URLCheckResult:
+async def check_single_url_async(*, client: httpx.AsyncClient, name: str, url: str) -> URLCheckResult:
"""Check if a single URL is accessible asynchronously.
Args:
@@ -137,12 +132,12 @@ async def check_all_urls_async(
timeout=request_timeout,
limits=HTTP_LIMITS,
) as client:
- tasks = [check_single_url_async(client, name=name, url=url) for name, url in url_pairs]
+ tasks = [check_single_url_async(client=client, name=name, url=url) for name, url in url_pairs]
results = await asyncio.gather(*tasks)
return list(results)
-def check_urls_cmd(quiet: bool = False, *, timeout: int = DEFAULT_TIMEOUT) -> None:
+def check_urls_cmd(*, quiet: bool = False, timeout: int = DEFAULT_TIMEOUT) -> None:
"""Check all URLs defined in pipelex/urls.py for broken links.
Args:
diff --git a/pipelex/cli/dev_cli/commands/drift/__init__.py b/pipelex/cli/dev_cli/commands/drift/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/pipelex/cli/dev_cli/commands/drift/core.py b/pipelex/cli/dev_cli/commands/drift/core.py
new file mode 100644
index 000000000..5e5897221
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/drift/core.py
@@ -0,0 +1,242 @@
+"""Pure drift engine: glob matching, digest computation, plan-diff, and check evaluation.
+
+Everything here operates on injected data (file lists, path→OID maps, parsed models)
+— no git, no filesystem, no subprocesses. The git adapter feeds it the index state.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from enum import StrEnum
+from functools import cache
+from typing import TYPE_CHECKING
+
+from pydantic.dataclasses import dataclass
+
+# Runtime import (not TYPE_CHECKING): pydantic dataclasses resolve their field annotations
+# (DriftAck, DriftContract) against module globals when the class is built.
+from pipelex.cli.dev_cli.commands.drift.models import DriftAck, DriftContract, DriftManifest # noqa: TC001
+
+if TYPE_CHECKING:
+ from collections.abc import Iterable, Mapping, Sequence
+
+DIGEST_PREFIX = "sha256:"
+GLOB_CHARS = ("*", "?")
+
+# Ack files are rewritten by `drift ack` itself; if a trigger glob could match them, every
+# ack would invalidate its own (or a sibling's) digest as soon as the ack file is staged —
+# an unfixable open-contract loop. So the internal state directory is never trigger-matchable.
+DRIFT_STATE_PREFIX = ".drift/"
+
+
+def _normalize_pattern(pattern: str) -> str:
+ """Strip trailing slashes: a directory pattern and its slashless form match the same files."""
+ return pattern.rstrip("/")
+
+
+@cache
+def _pattern_to_regex(pattern: str) -> re.Pattern[str]:
+ """Translate a glob pattern into a full-match regex.
+
+ Semantics: `**/` spans any number of directories (including zero), a trailing `**`
+ matches everything under the prefix, `*` and `?` never cross `/`. Character classes
+ are not supported (`[` is literal). Matching is case-sensitive per POSIX.
+ """
+ regex_parts: list[str] = []
+ index = 0
+ while index < len(pattern):
+ char = pattern[index]
+ if char == "*":
+ if pattern.startswith("**/", index):
+ regex_parts.append("(?:[^/]+/)*")
+ index += 3
+ elif pattern.startswith("**", index):
+ regex_parts.append(".*")
+ index += 2
+ else:
+ regex_parts.append("[^/]*")
+ index += 1
+ elif char == "?":
+ regex_parts.append("[^/]")
+ index += 1
+ else:
+ regex_parts.append(re.escape(char))
+ index += 1
+ return re.compile("".join(regex_parts) + r"\Z")
+
+
+def match_pattern(path: str, *, pattern: str) -> bool:
+ """Check whether a tracked-file path matches one trigger/review pattern.
+
+ A pattern without glob characters matches the exact path or, as a directory
+ prefix, every tracked file under it (`docs/tools/cli/` and `docs/tools/cli`
+ are equivalent).
+ """
+ normalized = _normalize_pattern(pattern)
+ if not any(glob_char in normalized for glob_char in GLOB_CHARS):
+ return path == normalized or path.startswith(normalized + "/")
+ return _pattern_to_regex(normalized).match(path) is not None
+
+
+def match_files(files: Iterable[str], *, patterns: Sequence[str], exclude: Sequence[str] = ()) -> list[str]:
+ """Return the sorted subset of files matching any pattern and no exclude."""
+ matched: list[str] = []
+ for path in files:
+ if not any(match_pattern(path, pattern=pattern) for pattern in patterns):
+ continue
+ if any(match_pattern(path, pattern=exclude_pattern) for exclude_pattern in exclude):
+ continue
+ matched.append(path)
+ return sorted(matched)
+
+
+def find_dead_patterns(files: Iterable[str], *, patterns: Sequence[str]) -> list[str]:
+ """Return the patterns matching zero files, in their declared order (manifest rot detector)."""
+ file_list = list(files)
+ return [pattern for pattern in patterns if not any(match_pattern(path, pattern=pattern) for path in file_list)]
+
+
+def compute_contract_digest(contract: DriftContract, *, contract_id: str, trigger_files: Mapping[str, str]) -> str:
+ """Digest a contract: sha256 over a canonical JSON of its definition plus its trigger content.
+
+ Canonicalization (what must NOT change the digest): object keys are sorted by json.dumps,
+ glob lists are sorted (matching is order-independent), and defaulted fields serialize like
+ their explicit-empty forms. verify_commands keep their order — it is execution order, hence
+ part of the definition.
+ """
+ canonical = {
+ "contract": {
+ "id": contract_id,
+ "description": contract.description,
+ "triggers": sorted(contract.triggers),
+ "exclude": sorted(contract.exclude),
+ "review": sorted(contract.review),
+ "verify_commands": list(contract.verify_commands),
+ },
+ "trigger_files": sorted(trigger_files.items()),
+ }
+ payload = json.dumps(canonical, sort_keys=True, separators=(",", ":"))
+ return DIGEST_PREFIX + hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class TriggerFilesDiff:
+ """Per-file changes between a stored ack map and the current index map."""
+
+ added: list[str]
+ removed: list[str]
+ modified: list[str]
+
+ @property
+ def is_empty(self) -> bool:
+ return not (self.added or self.removed or self.modified)
+
+
+def diff_trigger_files(*, stored: Mapping[str, str], current: Mapping[str, str]) -> TriggerFilesDiff:
+ """Diff the ack's stored trigger-file map against the current one (messaging only, no validity)."""
+ added = sorted(path for path in current if path not in stored)
+ removed = sorted(path for path in stored if path not in current)
+ modified = sorted(path for path in current if path in stored and current[path] != stored[path])
+ return TriggerFilesDiff(added=added, removed=removed, modified=modified)
+
+
+@dataclass(frozen=True)
+class ContractDigestResult:
+ """The current digest of a contract plus the trigger-file map it was computed from."""
+
+ digest: str
+ trigger_files: dict[str, str]
+
+
+def compute_current_digest(contract: DriftContract, *, contract_id: str, staged_oids: Mapping[str, str]) -> ContractDigestResult:
+ """Match the contract's triggers against the index map and digest the result."""
+ matchable = (path for path in staged_oids if not path.startswith(DRIFT_STATE_PREFIX))
+ matched = match_files(matchable, patterns=contract.triggers, exclude=contract.exclude)
+ trigger_files = {path: staged_oids[path] for path in matched}
+ digest = compute_contract_digest(contract, contract_id=contract_id, trigger_files=trigger_files)
+ return ContractDigestResult(digest=digest, trigger_files=trigger_files)
+
+
+class DriftIssueKind(StrEnum):
+ """Everything `drift check` can flag."""
+
+ DEAD_TRIGGER_PATTERN = "dead_trigger_pattern"
+ DEAD_REVIEW_TARGET = "dead_review_target"
+ EMPTY_EFFECTIVE_TRIGGERS = "empty_effective_triggers"
+ MISSING_ACK = "missing_ack"
+ ORPHAN_ACK = "orphan_ack"
+ ACK_CONTRACT_MISMATCH = "ack_contract_mismatch"
+ DIGEST_MISMATCH = "digest_mismatch"
+
+ @property
+ def is_manifest_rot(self) -> bool:
+ """Rot issues are fixed by editing drift.toml, not by re-acking."""
+ match self:
+ case DriftIssueKind.DEAD_TRIGGER_PATTERN | DriftIssueKind.DEAD_REVIEW_TARGET | DriftIssueKind.EMPTY_EFFECTIVE_TRIGGERS:
+ return True
+ case DriftIssueKind.MISSING_ACK | DriftIssueKind.ORPHAN_ACK | DriftIssueKind.ACK_CONTRACT_MISMATCH | DriftIssueKind.DIGEST_MISMATCH:
+ return False
+
+
+@dataclass(frozen=True)
+class DriftIssue:
+ """One check finding: what kind, on which contract, with an optional detail (pattern, field value)."""
+
+ kind: DriftIssueKind
+ contract_id: str
+ detail: str = ""
+
+
+def find_issues(manifest: DriftManifest, *, staged_oids: Mapping[str, str], acks: Mapping[str, DriftAck]) -> list[DriftIssue]:
+ """Evaluate every check validation over injected index state; empty result means all green."""
+ issues: list[DriftIssue] = []
+ tracked_files = [path for path in staged_oids if not path.startswith(DRIFT_STATE_PREFIX)]
+ for contract_id, contract in manifest.contracts.items():
+ dead_triggers = find_dead_patterns(tracked_files, patterns=contract.triggers)
+ for pattern in dead_triggers:
+ issues.append(DriftIssue(kind=DriftIssueKind.DEAD_TRIGGER_PATTERN, contract_id=contract_id, detail=pattern))
+ for pattern in find_dead_patterns(tracked_files, patterns=contract.review):
+ issues.append(DriftIssue(kind=DriftIssueKind.DEAD_REVIEW_TARGET, contract_id=contract_id, detail=pattern))
+ # A contract whose excludes swallow every trigger match has an empty effective set: it can
+ # never go stale, so it is manifest rot. Skip when dead trigger globs already explain it.
+ if not dead_triggers and not match_files(tracked_files, patterns=contract.triggers, exclude=contract.exclude):
+ issues.append(DriftIssue(kind=DriftIssueKind.EMPTY_EFFECTIVE_TRIGGERS, contract_id=contract_id))
+ ack = acks.get(contract_id)
+ if ack is None:
+ issues.append(DriftIssue(kind=DriftIssueKind.MISSING_ACK, contract_id=contract_id))
+ continue
+ if ack.contract != contract_id:
+ issues.append(DriftIssue(kind=DriftIssueKind.ACK_CONTRACT_MISMATCH, contract_id=contract_id, detail=ack.contract))
+ digest_result = compute_current_digest(contract, contract_id=contract_id, staged_oids=staged_oids)
+ if ack.digest != digest_result.digest:
+ issues.append(DriftIssue(kind=DriftIssueKind.DIGEST_MISMATCH, contract_id=contract_id))
+ for ack_stem in sorted(acks):
+ if ack_stem not in manifest.contracts:
+ issues.append(DriftIssue(kind=DriftIssueKind.ORPHAN_ACK, contract_id=ack_stem))
+ return issues
+
+
+@dataclass(frozen=True)
+class ContractPlanPacket:
+ """Everything `drift plan` renders for one open contract."""
+
+ contract_id: str
+ contract: DriftContract
+ previous_ack: DriftAck | None
+ diff: TriggerFilesDiff
+
+
+def build_plan_packets(manifest: DriftManifest, *, staged_oids: Mapping[str, str], acks: Mapping[str, DriftAck]) -> list[ContractPlanPacket]:
+ """Return a packet per open contract (no ack, or digest mismatch), in manifest order."""
+ packets: list[ContractPlanPacket] = []
+ for contract_id, contract in manifest.contracts.items():
+ ack = acks.get(contract_id)
+ digest_result = compute_current_digest(contract, contract_id=contract_id, staged_oids=staged_oids)
+ if ack is not None and ack.digest == digest_result.digest:
+ continue
+ stored = ack.trigger_files if ack is not None else {}
+ diff = diff_trigger_files(stored=stored, current=digest_result.trigger_files)
+ packets.append(ContractPlanPacket(contract_id=contract_id, contract=contract, previous_ack=ack, diff=diff))
+ return packets
diff --git a/pipelex/cli/dev_cli/commands/drift/drift_cmd.py b/pipelex/cli/dev_cli/commands/drift/drift_cmd.py
new file mode 100644
index 000000000..598a2008b
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/drift/drift_cmd.py
@@ -0,0 +1,273 @@
+"""Typer sub-app for drift contracts: `pipelex-dev drift plan|check|ack`.
+
+Wires the pure core to the git adapter; this module owns presentation only.
+`plan` prints Markdown (its consumer is an agent), `check` prints the CI-gate
+report, `ack` runs verify commands then records the review.
+"""
+
+from __future__ import annotations
+
+import shlex
+import subprocess # noqa: S404
+import sys
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from rich.markup import escape
+
+from pipelex.cli.dev_cli.commands.drift.core import (
+ ContractPlanPacket,
+ DriftIssue,
+ DriftIssueKind,
+ build_plan_packets,
+ compute_current_digest,
+ find_issues,
+ match_files,
+)
+from pipelex.cli.dev_cli.commands.drift.exceptions import DriftAckError, DriftError
+from pipelex.cli.dev_cli.commands.drift.git_adapter import (
+ get_git_user_name,
+ get_repo_toplevel,
+ read_staged_files,
+ read_unstaged_modified,
+ read_untracked,
+)
+from pipelex.cli.dev_cli.commands.drift.models import (
+ ACKS_DIR_RELATIVE,
+ DriftAck,
+ DriftContract,
+ ack_file_path,
+ load_all_acks,
+ load_manifest,
+ save_ack,
+)
+from pipelex.hub import get_console
+
+if TYPE_CHECKING:
+ from collections.abc import Sequence
+ from pathlib import Path
+
+ from rich.console import Console
+
+VERIFY_COMMAND_TIMEOUT_SECONDS = 900
+
+drift_app = typer.Typer(no_args_is_help=True)
+
+
+def _resolve_repo_root(repo_root: Path | None) -> Path:
+ return repo_root if repo_root is not None else get_repo_toplevel()
+
+
+def _issue_message(issue: DriftIssue) -> str:
+ match issue.kind:
+ case DriftIssueKind.DEAD_TRIGGER_PATTERN:
+ return f"trigger pattern '{issue.detail}' matches no tracked file"
+ case DriftIssueKind.DEAD_REVIEW_TARGET:
+ return f"review target '{issue.detail}' matches no tracked file"
+ case DriftIssueKind.EMPTY_EFFECTIVE_TRIGGERS:
+ return "triggers are fully excluded — no tracked file is effectively covered"
+ case DriftIssueKind.MISSING_ACK:
+ return "no ack recorded — initial review required"
+ case DriftIssueKind.ORPHAN_ACK:
+ return f"ack file '{ACKS_DIR_RELATIVE / (issue.contract_id + '.toml')}' has no matching contract in drift.toml"
+ case DriftIssueKind.ACK_CONTRACT_MISMATCH:
+ return f"ack contract field '{issue.detail}' does not match its filename stem"
+ case DriftIssueKind.DIGEST_MISMATCH:
+ return "trigger content or contract definition changed since last ack"
+
+
+def drift_check_cmd(*, quiet: bool = False, repo_root: Path | None = None) -> None:
+ """The CI gate: validate the manifest and every ack against the current index. Exits 1 on any issue."""
+ console = get_console()
+ resolved_root = _resolve_repo_root(repo_root)
+ manifest = load_manifest(resolved_root)
+ staged_oids = read_staged_files(resolved_root)
+ acks = load_all_acks(resolved_root)
+ issues = find_issues(manifest, staged_oids=staged_oids, acks=acks)
+
+ if not issues:
+ if quiet:
+ console.print("[green]✓ Drift check: PASSED[/green]")
+ else:
+ console.print()
+ console.print("[green]✓ Drift check: PASSED[/green] — every contract is fulfilled")
+ console.print()
+ return
+
+ console.print()
+ console.print("[bold red]✗ Drift check: FAILED[/bold red]")
+ console.print()
+ for issue in issues:
+ console.print(f" [red]✗[/red] [cyan]{escape(issue.contract_id)}[/cyan]: {escape(_issue_message(issue))}")
+ console.print()
+ if any(issue.kind.is_manifest_rot for issue in issues):
+ console.print(" Dead patterns are manifest rot: edit drift.toml first.")
+ console.print(" To see open contracts and how to fulfill them,")
+ console.print(" run `make drift-plan`")
+ console.print()
+ sys.exit(1)
+
+
+def _render_packet_markdown(packet: ContractPlanPacket) -> str:
+ lines: list[str] = [f"## Open contract: {packet.contract_id}", "", packet.contract.description, ""]
+ previous_ack = packet.previous_ack
+ if previous_ack is None:
+ lines.append("**Trigger files** (no previous ack — initial review required):")
+ else:
+ ack_date = previous_ack.reviewed_at.split("T")[0]
+ lines.append(f'**Trigger changes since last ack** (by {previous_ack.reviewed_by}, {ack_date}, "{previous_ack.rationale}"):')
+ lines.append("")
+ for path in packet.diff.added:
+ lines.append(f"- added: {path}")
+ for path in packet.diff.removed:
+ lines.append(f"- removed: {path}")
+ for path in packet.diff.modified:
+ lines.append(f"- modified: {path}")
+ if packet.diff.is_empty:
+ lines.append("- (no trigger-file changes — the contract definition itself changed)")
+ lines.extend(["", "**Review targets:**", ""])
+ lines.extend(f"- {target}" for target in packet.contract.review)
+ if packet.contract.verify_commands:
+ lines.extend(["", "**Verify commands (run by ack):**", ""])
+ lines.extend(f"- {command}" for command in packet.contract.verify_commands)
+ ack_invocation = f'make drift-ack CONTRACT={packet.contract_id} RATIONALE="…"'
+ lines.extend(
+ [
+ "",
+ "**To fulfill:** review the targets against the trigger changes, update what is stale,",
+ f"stage the trigger files (`git add`), then run `{ack_invocation}`",
+ ]
+ )
+ return "\n".join(lines)
+
+
+def drift_plan_cmd(contract_id: str | None = None, *, repo_root: Path | None = None) -> None:
+ """List open contracts as Markdown packets (the consumer is an agent fulfilling them)."""
+ resolved_root = _resolve_repo_root(repo_root)
+ manifest = load_manifest(resolved_root)
+ if contract_id is not None and contract_id not in manifest.contracts:
+ known_ids = ", ".join(manifest.contracts)
+ msg = f"Unknown contract '{contract_id}' — known contracts: {known_ids}"
+ raise DriftError(msg)
+ staged_oids = read_staged_files(resolved_root)
+ acks = load_all_acks(resolved_root)
+ packets = build_plan_packets(manifest, staged_oids=staged_oids, acks=acks)
+ if contract_id is not None:
+ packets = [packet for packet in packets if packet.contract_id == contract_id]
+ if not packets:
+ typer.echo(f"Contract '{contract_id}' is fulfilled — nothing to review.")
+ return
+ if not packets:
+ typer.echo("All drift contracts are fulfilled — nothing to review.")
+ return
+ rendered = "\n\n".join(_render_packet_markdown(packet) for packet in packets)
+ typer.echo(rendered)
+
+
+def _run_verify_commands(commands: Sequence[str], *, repo_root: Path, console: Console) -> None:
+ """Run each verify command (shlex argv, no shell, cwd=repo root, env inherited); first failure aborts."""
+ for command in commands:
+ argv = shlex.split(command)
+ if not argv:
+ msg = f"Empty verify command in contract definition: {command!r}"
+ raise DriftAckError(msg)
+ console.print(f" Running verify command: [cyan]{escape(command)}[/cyan]")
+ try:
+ result = subprocess.run( # noqa: S603
+ argv,
+ cwd=repo_root,
+ capture_output=True,
+ text=True,
+ timeout=VERIFY_COMMAND_TIMEOUT_SECONDS,
+ check=False,
+ )
+ except FileNotFoundError as exc:
+ msg = f"Verify command not found: '{argv[0]}' — ack aborted, nothing written"
+ raise DriftAckError(msg) from exc
+ except subprocess.TimeoutExpired as exc:
+ msg = f"Verify command timed out after {VERIFY_COMMAND_TIMEOUT_SECONDS}s: '{command}' — ack aborted, nothing written"
+ raise DriftAckError(msg) from exc
+ if result.returncode != 0:
+ if result.stdout.strip():
+ console.print(escape(result.stdout))
+ if result.stderr.strip():
+ console.print(escape(result.stderr))
+ msg = f"Verify command failed (exit {result.returncode}): '{command}' — ack aborted, nothing written"
+ raise DriftAckError(msg)
+
+
+def _warn_uncovered_working_tree(contract: DriftContract, *, repo_root: Path, console: Console) -> None:
+ """Warn when working-tree state lags the index: the ack covers staged content only."""
+ unstaged_matched = match_files(read_unstaged_modified(repo_root), patterns=contract.triggers, exclude=contract.exclude)
+ for path in unstaged_matched:
+ console.print(f"[yellow]⚠[/yellow] trigger file has unstaged modifications: {escape(path)}")
+ console.print(" The ack covers its staged content — `git add` it first if the edit should be covered.")
+ untracked_matched = match_files(read_untracked(repo_root), patterns=contract.triggers, exclude=contract.exclude)
+ for path in untracked_matched:
+ console.print(f"[yellow]⚠[/yellow] untracked file matches triggers: {escape(path)}")
+ console.print(" Untracked files are not covered until staged (`git add`).")
+
+
+def drift_ack_cmd(contract_id: str, *, rationale: str, reviewed_by_override: str | None = None, repo_root: Path | None = None) -> None:
+ """Run the contract's verify commands, then record the ack from the current index state."""
+ console = get_console()
+ resolved_root = _resolve_repo_root(repo_root)
+ manifest = load_manifest(resolved_root)
+ contract = manifest.contracts.get(contract_id)
+ if contract is None:
+ known_ids = ", ".join(manifest.contracts)
+ msg = f"Unknown contract '{contract_id}' — known contracts: {known_ids}"
+ raise DriftAckError(msg)
+ if not rationale.strip():
+ msg = "An ack requires a non-empty --rationale: it is the on-the-record review decision"
+ raise DriftAckError(msg)
+ reviewed_by = reviewed_by_override or get_git_user_name(resolved_root)
+ if reviewed_by is None:
+ msg = "Cannot resolve the reviewer identity: set `git config user.name` or pass --by"
+ raise DriftAckError(msg)
+
+ _run_verify_commands(contract.verify_commands, repo_root=resolved_root, console=console)
+
+ staged_oids = read_staged_files(resolved_root)
+ digest_result = compute_current_digest(contract, contract_id=contract_id, staged_oids=staged_oids)
+ _warn_uncovered_working_tree(contract, repo_root=resolved_root, console=console)
+
+ ack = DriftAck(
+ contract=contract_id,
+ digest=digest_result.digest,
+ reviewed_by=reviewed_by,
+ reviewed_at=datetime.now(tz=UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+ rationale=rationale,
+ trigger_files=digest_result.trigger_files,
+ )
+ save_ack(ack, repo_root=resolved_root)
+ ack_path = ack_file_path(resolved_root, contract_id=contract_id)
+ console.print(f"[green]✓[/green] Ack recorded for [cyan]{contract_id}[/cyan] at {ack_path.relative_to(resolved_root)}")
+ console.print(" Commit the ack file together with the change it covers.")
+
+
+@drift_app.command("plan", help="Show open drift contracts and how to fulfill them (Markdown output)")
+def plan_command(
+ contract: Annotated[str | None, typer.Argument(help="Contract id — show the full packet for this contract only")] = None,
+) -> None:
+ """Show open drift contracts and how to fulfill them."""
+ drift_plan_cmd(contract)
+
+
+@drift_app.command("check", help="CI gate: validate the manifest and every ack against the current index")
+def check_command(
+ quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Single line on success; failures always print in full")] = False,
+) -> None:
+ """Validate drift contracts; exit non-zero when any contract is open or the manifest rotted."""
+ drift_check_cmd(quiet=quiet)
+
+
+@drift_app.command("ack", help="Run the contract's verify commands, then record the review ack")
+def ack_command(
+ contract: Annotated[str, typer.Argument(help="Contract id to acknowledge")],
+ rationale: Annotated[str, typer.Option("--rationale", "-r", help="The on-the-record review decision (required)")],
+ by: Annotated[str | None, typer.Option("--by", help="Reviewer identity (default: git config user.name)")] = None,
+) -> None:
+ """Record a fulfilled review for one contract."""
+ drift_ack_cmd(contract, rationale=rationale, reviewed_by_override=by)
diff --git a/pipelex/cli/dev_cli/commands/drift/exceptions.py b/pipelex/cli/dev_cli/commands/drift/exceptions.py
new file mode 100644
index 000000000..d535f332f
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/drift/exceptions.py
@@ -0,0 +1,19 @@
+"""Exceptions for the drift-contracts dev CLI (`pipelex-dev drift`)."""
+
+from pipelex.cli.exceptions import PipelexCLIError
+
+
+class DriftError(PipelexCLIError):
+ """Base error for the drift-contracts tooling."""
+
+
+class DriftManifestError(DriftError):
+ """Raised when drift.toml is missing, unparseable, or schema-invalid."""
+
+
+class DriftAckError(DriftError):
+ """Raised when an ack file is invalid or an ack operation cannot proceed."""
+
+
+class DriftGitError(DriftError):
+ """Raised when a git plumbing call needed by drift fails."""
diff --git a/pipelex/cli/dev_cli/commands/drift/git_adapter.py b/pipelex/cli/dev_cli/commands/drift/git_adapter.py
new file mode 100644
index 000000000..cc7ce3ae7
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/drift/git_adapter.py
@@ -0,0 +1,102 @@
+"""The only git-touching module of the drift engine: index reads via git plumbing.
+
+Digest sourcing is index-based (staged blob OIDs from `git ls-files -s`), so matching
+and hashing share one source, content is filter-normalized (CRLF/smudge safe), and the
+digest covers exactly what would land in the commit. Working-tree bytes are never hashed.
+"""
+
+from __future__ import annotations
+
+import subprocess # noqa: S404
+from pathlib import Path
+
+from pipelex.cli.dev_cli.commands.drift.exceptions import DriftGitError
+
+GIT_TIMEOUT_SECONDS = 30
+OID_PREFIX = "blob:"
+
+
+def _run_git(args: list[str], *, cwd: Path) -> str:
+ """Run one git plumbing command and return stdout; every failure is a DriftGitError."""
+ try:
+ result = subprocess.run( # noqa: S603
+ ["git", *args], # noqa: S607
+ cwd=cwd,
+ capture_output=True,
+ text=True,
+ timeout=GIT_TIMEOUT_SECONDS,
+ check=False,
+ )
+ except FileNotFoundError as exc:
+ msg = "git binary not found on PATH — the drift commands need git"
+ raise DriftGitError(msg) from exc
+ except subprocess.TimeoutExpired as exc:
+ msg = f"git {' '.join(args)} timed out after {GIT_TIMEOUT_SECONDS}s"
+ raise DriftGitError(msg) from exc
+ if result.returncode != 0:
+ msg = f"git {' '.join(args)} failed (exit {result.returncode}): {result.stderr.strip()}"
+ raise DriftGitError(msg)
+ return result.stdout
+
+
+def get_repo_toplevel(*, cwd: Path | None = None) -> Path:
+ """Resolve the git toplevel directory from cwd (where drift.toml and .drift/ live)."""
+ output = _run_git(["rev-parse", "--show-toplevel"], cwd=cwd or Path.cwd())
+ return Path(output.strip())
+
+
+def read_staged_files(repo_root: Path) -> dict[str, str]:
+ """Read the whole index in one `git ls-files -s -z` call: path → "blob:<oid>".
+
+ The keys are the tracked-file set the matcher runs over and the values are the
+ staged blob OIDs the digest hashes — one call, one source.
+
+ Raises:
+ DriftGitError: On any git failure, malformed output, or unmerged index entries.
+ """
+ output = _run_git(["ls-files", "-s", "-z"], cwd=repo_root)
+ staged: dict[str, str] = {}
+ for entry in output.split("\0"):
+ if not entry:
+ continue
+ header, separator, path = entry.partition("\t")
+ header_parts = header.split()
+ if not separator or len(header_parts) != 3:
+ msg = f"Malformed `git ls-files -s` entry: {entry!r}"
+ raise DriftGitError(msg)
+ _mode, oid, stage = header_parts
+ if stage != "0":
+ msg = f"Unmerged index entry for '{path}' — resolve the merge, then re-run"
+ raise DriftGitError(msg)
+ staged[path] = OID_PREFIX + oid
+ return staged
+
+
+def read_unstaged_modified(repo_root: Path) -> list[str]:
+ """Tracked files whose working-tree content differs from the index (for ack-time warnings)."""
+ output = _run_git(["diff", "--name-only", "-z"], cwd=repo_root)
+ return sorted(path for path in output.split("\0") if path)
+
+
+def read_untracked(repo_root: Path) -> list[str]:
+ """Untracked, non-ignored files (for ack-time warnings — they are invisible to the index)."""
+ output = _run_git(["ls-files", "--others", "--exclude-standard", "-z"], cwd=repo_root)
+ return sorted(path for path in output.split("\0") if path)
+
+
+def get_git_user_name(repo_root: Path) -> str | None:
+ """The configured git user.name, or None when unset (callers must then require --by)."""
+ try:
+ result = subprocess.run(
+ ["git", "config", "user.name"], # noqa: S607
+ cwd=repo_root,
+ capture_output=True,
+ text=True,
+ timeout=GIT_TIMEOUT_SECONDS,
+ check=False,
+ )
+ except (subprocess.TimeoutExpired, OSError):
+ return None
+ if result.returncode != 0:
+ return None
+ return result.stdout.strip() or None
diff --git a/pipelex/cli/dev_cli/commands/drift/models.py b/pipelex/cli/dev_cli/commands/drift/models.py
new file mode 100644
index 000000000..8ead2c3da
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/drift/models.py
@@ -0,0 +1,137 @@
+"""Manifest (drift.toml) and ack (.drift/acks/) models and their TOML I/O.
+
+The manifest is human-authored and validated strictly (unknown fields are errors).
+Ack files are tool-written by `drift ack` and committed; one file per contract so
+merge conflicts stay scoped to the contract they concern.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+from tomlkit.exceptions import TOMLKitError
+
+from pipelex.cli.dev_cli.commands.drift.exceptions import DriftAckError, DriftManifestError
+from pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path
+
+MANIFEST_FILENAME = "drift.toml"
+ACKS_DIR_RELATIVE = Path(".drift") / "acks"
+CONTRACT_ID_PATTERN = re.compile(r"^[a-z0-9-]+$")
+
+
+class DriftContract(BaseModel):
+ """One declared review obligation: when triggers change, review targets must be re-examined."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ description: str
+ triggers: list[str] = Field(min_length=1)
+ exclude: list[str] = Field(default_factory=list)
+ review: list[str] = Field(min_length=1)
+ verify_commands: list[str] = Field(default_factory=list)
+
+
+class DriftManifest(BaseModel):
+ """The parsed drift.toml: contract declarations keyed by contract id."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ version: int
+ contracts: dict[str, DriftContract]
+
+ @field_validator("contracts")
+ @classmethod
+ def validate_contract_ids(cls, value: dict[str, DriftContract]) -> dict[str, DriftContract]:
+ for contract_id in value:
+ if not CONTRACT_ID_PATTERN.match(contract_id):
+ msg = f"Invalid contract id '{contract_id}': ids must match [a-z0-9-]+ (they become ack filenames and TOML keys)"
+ raise ValueError(msg)
+ return value
+
+
+class DriftAck(BaseModel):
+ """The recorded fulfillment of one contract's review, committed under .drift/acks/.
+
+ `digest` alone carries validity; `reviewed_by`/`reviewed_at`/`rationale` are audit
+ context, and `trigger_files` exists so `drift plan` can report per-file changes.
+ """
+
+ model_config = ConfigDict(extra="forbid")
+
+ contract: str
+ digest: str
+ reviewed_by: str
+ reviewed_at: str
+ rationale: str
+ trigger_files: dict[str, str] = Field(default_factory=dict)
+
+
+def load_manifest(repo_root: Path) -> DriftManifest:
+ """Load and validate drift.toml from the repo root.
+
+ Raises:
+ DriftManifestError: If the manifest is missing, unparseable, or schema-invalid.
+ """
+ manifest_path = repo_root / MANIFEST_FILENAME
+ if not manifest_path.is_file():
+ msg = f"No {MANIFEST_FILENAME} found at repo root '{repo_root}' — create one to declare drift contracts"
+ raise DriftManifestError(msg)
+ try:
+ document = load_toml_with_tomlkit(manifest_path)
+ except TOMLKitError as exc:
+ msg = f"Failed to parse {MANIFEST_FILENAME}: {exc}"
+ raise DriftManifestError(msg) from exc
+ try:
+ return DriftManifest.model_validate(document.unwrap())
+ except ValidationError as exc:
+ msg = f"{MANIFEST_FILENAME} is schema-invalid: {exc}"
+ raise DriftManifestError(msg) from exc
+
+
+def ack_file_path(repo_root: Path, *, contract_id: str) -> Path:
+ """Path of the ack file for a contract id."""
+ return repo_root / ACKS_DIR_RELATIVE / f"{contract_id}.toml"
+
+
+def load_ack(ack_path: Path) -> DriftAck:
+ """Load and validate one ack file.
+
+ Raises:
+ DriftAckError: If the ack file is unparseable or schema-invalid.
+ """
+ try:
+ document = load_toml_with_tomlkit(ack_path)
+ except TOMLKitError as exc:
+ msg = f"Failed to parse ack file '{ack_path}': {exc}"
+ raise DriftAckError(msg) from exc
+ try:
+ return DriftAck.model_validate(document.unwrap())
+ except ValidationError as exc:
+ msg = f"Ack file '{ack_path}' is schema-invalid: {exc}"
+ raise DriftAckError(msg) from exc
+
+
+def load_all_acks(repo_root: Path) -> dict[str, DriftAck]:
+ """Load every ack under .drift/acks/, keyed by filename stem.
+
+ The stem is the key (not the ack's `contract` field) so that a mismatch between
+ the two can be detected by `drift check`.
+ """
+ acks_dir = repo_root / ACKS_DIR_RELATIVE
+ if not acks_dir.is_dir():
+ return {}
+ acks: dict[str, DriftAck] = {}
+ for ack_path in sorted(acks_dir.glob("*.toml")):
+ acks[ack_path.stem] = load_ack(ack_path)
+ return acks
+
+
+def save_ack(ack: DriftAck, *, repo_root: Path) -> None:
+ """Write an ack file atomically (temp file + os.replace)."""
+ target_path = ack_file_path(repo_root, contract_id=ack.contract)
+ target_path.parent.mkdir(parents=True, exist_ok=True)
+ temp_path = target_path.with_name(f".{target_path.name}.tmp")
+ save_toml_to_path(ack.model_dump(), path=temp_path)
+ Path(temp_path).replace(target_path)
diff --git a/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py b/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py
index 90a4a46e0..c3a04605a 100644
--- a/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py
+++ b/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py
@@ -13,7 +13,7 @@ from pipelex.pipelex import Pipelex
ERROR_PAGES_DIR = Path("docs/errors")
-def generate_error_pages_cmd(output: Path | None = None, *, quiet: bool = False) -> None:
+def generate_error_pages_cmd(*, output: Path | None = None, quiet: bool = False) -> None:
"""Generate per-class error documentation pages.
Bootstraps Pipelex with ``needs_inference=False`` (kept for parity with other
diff --git a/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py b/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py
index b9a1af012..a6b6ae785 100644
--- a/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py
+++ b/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py
@@ -15,7 +15,7 @@ from pipelex.language.mthds_schema_generator import generate_mthds_schema
MTHDS_SCHEMA_PATH = Path("derived/mthds_schema.json")
-def generate_mthds_schema_cmd(output: Path | None = None, *, quiet: bool = False) -> None:
+def generate_mthds_schema_cmd(*, output: Path | None = None, quiet: bool = False) -> None:
"""Generate a Taplo-compatible JSON Schema for .mthds files.
Generates the schema from PipelexBundleBlueprint and writes it as JSON.
diff --git a/pipelex/cli/dev_cli/commands/keyword_only_guard.py b/pipelex/cli/dev_cli/commands/keyword_only_guard.py
index 7030c7d66..c998cfc32 100644
--- a/pipelex/cli/dev_cli/commands/keyword_only_guard.py
+++ b/pipelex/cli/dev_cli/commands/keyword_only_guard.py
@@ -24,6 +24,16 @@ The module also exposes an auto-fix surface (``fix_source`` / ``fix_all_violatio
non-``self``/``cls`` parameter becomes keyword-only, for the mechanically fixable violations, and reports
the rest for a manual fix. See ``docs/contribute/keyword-only-arguments.md`` (the Auto-fix section) for the
fixable/unfixable shapes.
+
+Beyond the bare-``*`` rule, the guard enforces the **subject-grant registry**: a def may keep its
+subject positional only under an explicitly recorded grant in ``subject_grants.toml`` at the repo
+root (one entry per def, keyed ``<relative_path>::<qualified_name>``, recording the subject's
+``param`` name and a one-sentence ``rationale``). A positional subject without a grant is a
+violation; a grant whose def no longer exists (or whose recorded ``param`` no longer matches) is a
+violation too — staleness is symmetric. A subject annotated ``bool``/``int``/``float`` (including
+their ``Optional``/union-with-``None`` forms) is banned outright, grant or not: ``f(True)`` call
+sites are never acceptable. The registry is READ here (``tomllib``, stdlib); it is only ever
+WRITTEN by the full ``pipelex-dev subject-grant`` command (tomlkit, via ``toml_utils``).
"""
from __future__ import annotations
@@ -31,13 +41,15 @@ from __future__ import annotations
import ast
import re
import sys
+import tomllib
+from enum import StrEnum
from pathlib import Path
-from typing import TYPE_CHECKING, NamedTuple
+from typing import TYPE_CHECKING, Any, NamedTuple, cast
from typing_extensions import override
if TYPE_CHECKING:
- from collections.abc import Iterable, Iterator
+ from collections.abc import Iterable, Iterator, Mapping
# --------------------------------------------------------------------------------------
# Configuration / carve-out data
@@ -46,6 +58,13 @@ if TYPE_CHECKING:
#: Source root scanned by the guard (relative to the repo root / cwd).
SOURCE_ROOT = Path("pipelex")
+#: Committed registry of granted positional subjects (relative to the repo root / cwd).
+SUBJECT_GRANTS_FILE = Path("subject_grants.toml")
+
+#: Subject annotations whose values read as bare literals at call sites (`f(True)`, `f(3)`).
+#: A positional subject of these types is a violation no matter what — grants are impossible.
+LITERAL_SUBJECT_TYPE_NAMES = frozenset({"bool", "int", "float"})
+
#: The line breaks ``ast``/CPython counts toward ``node.lineno`` — and ONLY these.
#: ``str.splitlines()`` additionally splits on form-feed, vertical tab, NEL, file/group/record/unit
#: separators and the Unicode line/paragraph separators, so a single such character before a violation
@@ -99,6 +118,48 @@ SYMMETRIC_ALLOWLIST: frozenset[tuple[str, str]] = frozenset(
)
+class ViolationKind(StrEnum):
+ """The distinct keyword-only violation kinds — each names its own remedy."""
+
+ MISSING_STAR = "missing-star"
+ UNGRANTED_SUBJECT = "ungranted-subject"
+ LITERAL_SUBJECT = "literal-subject"
+ GRANT_PARAM_MISMATCH = "grant-param-mismatch"
+ DEAD_GRANT = "dead-grant"
+
+ @property
+ def remedy(self) -> str:
+ """One actionable sentence naming how to fix this violation kind."""
+ match self:
+ case ViolationKind.MISSING_STAR:
+ return "place a bare `*` so non-subject parameters are keyword-only, or run `make fko`"
+ case ViolationKind.UNGRANTED_SUBJECT:
+ return (
+ "run `make fko` to make the subject keyword-only, or keep it positional with "
+ '`make subject-grant FUNC="<path>::<qualname>" RATIONALE="…"`'
+ )
+ case ViolationKind.LITERAL_SUBJECT:
+ return (
+ "a bool/int/float subject reads as a bare literal at call sites — make it keyword-only "
+ "(`make fko`); literal-typed subjects can never be granted"
+ )
+ case ViolationKind.GRANT_PARAM_MISMATCH:
+ return "the recorded grant no longer matches the def's subject — re-run `make subject-grant`, or clean up subject_grants.toml"
+ case ViolationKind.DEAD_GRANT:
+ return (
+ "no def with a positional subject matches this grant — remove the entry from subject_grants.toml (re-grant after a rename/move)"
+ )
+
+ @property
+ def is_fixable_by_star_insert(self) -> bool:
+ """Whether ``--fix`` may resolve this kind by inserting a bare ``*`` (making every param keyword-only)."""
+ match self:
+ case ViolationKind.MISSING_STAR | ViolationKind.UNGRANTED_SUBJECT | ViolationKind.LITERAL_SUBJECT:
+ return True
+ case ViolationKind.GRANT_PARAM_MISMATCH | ViolationKind.DEAD_GRANT:
+ return False
+
+
class Violation(NamedTuple):
"""A single keyword-only convention violation.
@@ -106,11 +167,16 @@ class Violation(NamedTuple):
relative_path: The source file path relative to the repo root.
qualified_name: Module-relative dotted path (package.module + class chain + function name).
lineno: 1-based line of the ``def`` for human display only — never part of the stable key.
+ Registry-level violations (``dead-grant``) carry ``0``: there is no def line to point at.
+ kind: Which rule was broken — determines the remedy shown.
+ detail: Optional human-facing specifics (e.g. the subject param name, or the mismatch description).
"""
relative_path: str
qualified_name: str
lineno: int
+ kind: ViolationKind
+ detail: str = ""
@property
def key(self) -> str:
@@ -118,6 +184,132 @@ class Violation(NamedTuple):
return f"{self.relative_path}::{self.qualified_name}"
+class SubjectGrant(NamedTuple):
+ """A recorded permission for one def to keep its subject parameter positional.
+
+ Attributes:
+ param: The subject parameter's name — must keep matching the def's first non-``self``/``cls`` param.
+ rationale: The on-the-record review decision (an honest, def-specific sentence).
+ """
+
+ param: str
+ rationale: str
+
+
+class SubjectGrantRegistryError(Exception):
+ """The subject-grants registry is missing or malformed — no keyword-only verdict can be produced.
+
+ Defined here rather than in an ``exceptions.py`` module (the house convention) because this module
+ must stay importable as a standalone single file for the PostToolUse hook's cold-start budget —
+ importing a sibling module would drag in the whole ``pipelex`` package import chain.
+ """
+
+
+class SubjectStatus(StrEnum):
+ """How a def stands with respect to the positional-subject rule."""
+
+ EXEMPT = "exempt" # carve-out / escape hatch / symmetric allowlist — never inspected
+ NO_POSITIONAL_SUBJECT = "no-positional-subject" # fully keyword-only, or no params at all
+ LITERAL_SUBJECT = "literal-subject" # positional subject typed bool/int/float — never grantable
+ GRANTABLE_SUBJECT = "grantable-subject" # positional subject that a grant may cover
+
+ @property
+ def is_grantable(self) -> bool:
+ match self:
+ case SubjectStatus.GRANTABLE_SUBJECT:
+ return True
+ case SubjectStatus.EXEMPT | SubjectStatus.NO_POSITIONAL_SUBJECT | SubjectStatus.LITERAL_SUBJECT:
+ return False
+
+ @property
+ def is_literal(self) -> bool:
+ match self:
+ case SubjectStatus.LITERAL_SUBJECT:
+ return True
+ case SubjectStatus.EXEMPT | SubjectStatus.NO_POSITIONAL_SUBJECT | SubjectStatus.GRANTABLE_SUBJECT:
+ return False
+
+ @property
+ def is_exempt(self) -> bool:
+ match self:
+ case SubjectStatus.EXEMPT:
+ return True
+ case SubjectStatus.NO_POSITIONAL_SUBJECT | SubjectStatus.LITERAL_SUBJECT | SubjectStatus.GRANTABLE_SUBJECT:
+ return False
+
+
+class DefInfo(NamedTuple):
+ """Subject-rule facts about one inspected def — feeds grant freshness and the grant command.
+
+ Attributes:
+ key: Stable identity key, ``<relative_path>::<qualified_name>`` (same format as ``Violation.key``).
+ lineno: 1-based line of the ``def``, for human display.
+ status: Where the def stands with respect to the positional-subject rule.
+ subject_param: The positional subject's name, or ``None`` when the def has none (or is exempt).
+ """
+
+ key: str
+ lineno: int
+ status: SubjectStatus
+ subject_param: str | None
+
+
+#: The complete set of keys a registry entry may carry — anything else fails the check.
+_GRANT_ALLOWED_KEYS = frozenset({"param", "rationale"})
+
+
+def load_subject_grants(*, root: Path | None = None) -> dict[str, SubjectGrant]:
+ """Load and validate the subject-grants registry (``subject_grants.toml`` at the repo root).
+
+ Args:
+ root: The repo root; defaults to the current working directory (checks and the hook run from there).
+
+ Returns:
+ The grants keyed by ``<relative_path>::<qualified_name>``.
+
+ Raises:
+ SubjectGrantRegistryError: When the file is missing or malformed. A missing registry is an explicit
+ check error, never a silent empty registry — otherwise every granted subject in the tree would
+ suddenly report as ungranted (a mass false-violation).
+ """
+ path = (root or Path.cwd()) / SUBJECT_GRANTS_FILE
+ if not path.is_file():
+ msg = f"Subject-grants registry not found at '{path}'. It is committed at the repo root; run the check from there."
+ raise SubjectGrantRegistryError(msg)
+ try:
+ raw = tomllib.loads(path.read_text(encoding="utf-8"))
+ except tomllib.TOMLDecodeError as exc:
+ msg = f"Subject-grants registry '{path}' is not valid TOML: {exc}"
+ raise SubjectGrantRegistryError(msg) from exc
+ version = raw.pop("version", None)
+ if version != 1:
+ msg = f"Subject-grants registry '{path}' must declare `version = 1` (found: {version!r})"
+ raise SubjectGrantRegistryError(msg)
+ grants: dict[str, SubjectGrant] = {}
+ for key, raw_entry in raw.items():
+ if not isinstance(raw_entry, dict):
+ msg = f"Subject-grants registry entry '{key}' must be a table"
+ raise SubjectGrantRegistryError(msg)
+ if "::" not in key or not key.partition("::")[0].endswith(".py"):
+ msg = f"Subject-grants registry key '{key}' is not of the form '<relative_path>::<qualified_name>'"
+ raise SubjectGrantRegistryError(msg)
+ entry = cast("dict[str, Any]", raw_entry)
+ unknown_keys = set(entry) - _GRANT_ALLOWED_KEYS
+ if unknown_keys:
+ msg = f"Subject-grants registry entry '{key}' has unknown key(s): {sorted(unknown_keys)}"
+ raise SubjectGrantRegistryError(msg)
+ param = entry.get("param")
+ rationale = entry.get("rationale")
+ if not isinstance(param, str) or not param:
+ msg = f"Subject-grants registry entry '{key}' must record a non-empty string `param`"
+ raise SubjectGrantRegistryError(msg)
+ if not isinstance(rationale, str) or not rationale.strip():
+ msg = f"Subject-grants registry entry '{key}' must record a non-empty `rationale`"
+ raise SubjectGrantRegistryError(msg)
+ grants[key] = SubjectGrant(param=param, rationale=rationale)
+ return grants
+
+
# --------------------------------------------------------------------------------------
# Carve-out detection (pure AST, no import resolution)
# --------------------------------------------------------------------------------------
@@ -197,6 +389,59 @@ def _has_typer_param_annotation(node: ast.FunctionDef | ast.AsyncFunctionDef) ->
# --------------------------------------------------------------------------------------
+def _is_literal_type_name(annotation: ast.expr) -> bool:
+ """Whether an annotation node is a bare ``bool``/``int``/``float`` name."""
+ return isinstance(annotation, ast.Name) and annotation.id in LITERAL_SUBJECT_TYPE_NAMES
+
+
+def _union_members(annotation: ast.expr) -> list[ast.expr] | None:
+ """Flatten a ``X | Y`` / ``Optional[X]`` / ``Union[X, Y]`` annotation into its members, or None when not a union form."""
+ if isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
+ left = _union_members(annotation.left) or [annotation.left]
+ right = _union_members(annotation.right) or [annotation.right]
+ return [*left, *right]
+ if isinstance(annotation, ast.Subscript):
+ callee = _callee_name(annotation.value)
+ if callee == "Optional":
+ return [annotation.slice]
+ if callee == "Union":
+ if isinstance(annotation.slice, ast.Tuple):
+ return list(annotation.slice.elts)
+ return [annotation.slice]
+ return None
+
+
+def _is_literal_typed_annotation(annotation: ast.expr | None) -> bool:
+ """Whether an annotation denotes ``bool``/``int``/``float`` — including Optional/union-with-None forms.
+
+ ``bool | None``, ``Optional[int]``, and ``Union[float, None]`` are all literal-typed: their call-site
+ values are still bare literals. A union carrying any non-literal member (``int | str``) is not.
+ An absent annotation is not literal-typed — the ban is on provably-literal subjects only.
+ """
+ if annotation is None:
+ return False
+ members = _union_members(annotation)
+ if members is None:
+ return _is_literal_type_name(annotation)
+ has_literal = False
+ for member in members:
+ if isinstance(member, ast.Constant) and member.value is None:
+ continue
+ if _is_literal_type_name(member) or _is_literal_typed_annotation(member):
+ has_literal = True
+ continue
+ return False
+ return has_literal
+
+
+def _subject_param(node: ast.FunctionDef | ast.AsyncFunctionDef, *, is_method: bool) -> ast.arg | None:
+ """The def's subject: its first positional (positional-only or positional-or-keyword) param after ``self``/``cls``."""
+ params = [*node.args.posonlyargs, *node.args.args]
+ if is_method and params and params[0].arg in {"self", "cls"}:
+ params = params[1:]
+ return params[0] if params else None
+
+
def _positional_or_keyword_count(node: ast.FunctionDef | ast.AsyncFunctionDef, *, is_method: bool) -> int:
"""Count positional-or-keyword params after dropping self/cls and the allowed subject.
@@ -237,28 +482,68 @@ def _evaluate_def(
func_stack: tuple[str, ...],
is_method: bool,
source_lines: list[str],
-) -> Violation | None:
- """Apply the carve-outs then the rule to a single def; return a Violation or None."""
- # Carve-outs first — any match => skip entirely.
- if _is_dunder(node.name):
- return None
- if _def_line_has_escape_hatch(node, source_lines=source_lines):
- return None
- if _has_carveout_decorator(node):
- return None
- if _has_typer_param_annotation(node):
- return None
-
+ grants: Mapping[str, SubjectGrant],
+) -> tuple[Violation | None, DefInfo]:
+ """Apply the carve-outs then the rules to a single def; return its (violation-or-None, DefInfo) pair."""
local_qname = _qualify(node.name, class_stack=class_stack, func_stack=func_stack)
- dotted_qname = f"{module_qname}.{local_qname}"
- if (dotted_qname, relative_path) in SYMMETRIC_ALLOWLIST:
- return None
+ key = f"{relative_path}::{local_qname}"
+
+ # Carve-outs first — any match => skip entirely (an exempt def neither needs nor keeps a grant alive).
+ is_exempt = (
+ _is_dunder(node.name)
+ or _def_line_has_escape_hatch(node, source_lines=source_lines)
+ or _has_carveout_decorator(node)
+ or _has_typer_param_annotation(node)
+ or (f"{module_qname}.{local_qname}", relative_path) in SYMMETRIC_ALLOWLIST
+ )
+ if is_exempt:
+ return None, DefInfo(key=key, lineno=node.lineno, status=SubjectStatus.EXEMPT, subject_param=None)
- # Rule: a bare `*` is required once two or more positional-or-keyword params remain
- # after dropping self/cls — i.e. at least one non-subject positional-or-keyword param.
+ subject = _subject_param(node, is_method=is_method)
+ if subject is None:
+ return None, DefInfo(key=key, lineno=node.lineno, status=SubjectStatus.NO_POSITIONAL_SUBJECT, subject_param=None)
+
+ is_literal = _is_literal_typed_annotation(subject.annotation)
+ status = SubjectStatus.LITERAL_SUBJECT if is_literal else SubjectStatus.GRANTABLE_SUBJECT
+ def_info = DefInfo(key=key, lineno=node.lineno, status=status, subject_param=subject.arg)
+
+ # Rule 1 (the bare-`*` rule): a violation once any non-subject positional-or-keyword param remains
+ # after dropping self/cls. This dominates the subject rules — the auto-fix makes the def all-keyword.
if _positional_or_keyword_count(node, is_method=is_method) >= 1:
- return Violation(relative_path=relative_path, qualified_name=local_qname, lineno=node.lineno)
- return None
+ violation = Violation(relative_path=relative_path, qualified_name=local_qname, lineno=node.lineno, kind=ViolationKind.MISSING_STAR)
+ return violation, def_info
+
+ # Rule 2 (the subject rules): a positional subject is legal only under an explicit grant,
+ # and never when literal-typed — `f(True)` call sites are unacceptable no matter what.
+ if is_literal:
+ violation = Violation(
+ relative_path=relative_path,
+ qualified_name=local_qname,
+ lineno=node.lineno,
+ kind=ViolationKind.LITERAL_SUBJECT,
+ detail=f"subject '{subject.arg}'",
+ )
+ return violation, def_info
+ grant = grants.get(key)
+ if grant is None:
+ violation = Violation(
+ relative_path=relative_path,
+ qualified_name=local_qname,
+ lineno=node.lineno,
+ kind=ViolationKind.UNGRANTED_SUBJECT,
+ detail=f"subject '{subject.arg}'",
+ )
+ return violation, def_info
+ if grant.param != subject.arg:
+ violation = Violation(
+ relative_path=relative_path,
+ qualified_name=local_qname,
+ lineno=node.lineno,
+ kind=ViolationKind.GRANT_PARAM_MISMATCH,
+ detail=f"grant records param '{grant.param}' but the subject is '{subject.arg}'",
+ )
+ return violation, def_info
+ return None, def_info
def _fix_insertion_point(node: ast.FunctionDef | ast.AsyncFunctionDef, *, is_method: bool) -> tuple[int, int] | None:
@@ -314,13 +599,23 @@ class _FixRecord(NamedTuple):
class _Collector(ast.NodeVisitor):
"""Walks the module, tracking the enclosing class/function scope to qualify defs."""
- def __init__(self, *, module_qname: str, relative_path: str, source_lines: list[str], collect_fixes: bool = False) -> None:
+ def __init__(
+ self,
+ *,
+ module_qname: str,
+ relative_path: str,
+ source_lines: list[str],
+ grants: Mapping[str, SubjectGrant],
+ collect_fixes: bool = False,
+ ) -> None:
self.module_qname = module_qname
self.relative_path = relative_path
self.source_lines = source_lines
+ self.grants = grants
self.collect_fixes = collect_fixes
self.violations: list[Violation] = []
self.fix_records: list[_FixRecord] = []
+ self.def_infos: list[DefInfo] = []
self._class_stack: tuple[str, ...] = ()
self._func_stack: tuple[str, ...] = ()
self._in_class_body: tuple[bool, ...] = ()
@@ -335,7 +630,7 @@ class _Collector(ast.NodeVisitor):
def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
is_method = bool(self._in_class_body) and self._in_class_body[-1]
- violation = _evaluate_def(
+ violation, def_info = _evaluate_def(
node,
module_qname=self.module_qname,
relative_path=self.relative_path,
@@ -343,11 +638,15 @@ class _Collector(ast.NodeVisitor):
func_stack=self._func_stack,
is_method=is_method,
source_lines=self.source_lines,
+ grants=self.grants,
)
+ self.def_infos.append(def_info)
if violation is not None:
self.violations.append(violation)
if self.collect_fixes:
- insertion = _fix_insertion_point(node, is_method=is_method)
+ # A bare-`*` insert can only resolve the star-insert-fixable kinds; a grant mismatch
+ # needs a registry decision, never a silent signature rewrite.
+ insertion = _fix_insertion_point(node, is_method=is_method) if violation.kind.is_fixable_by_star_insert else None
self.fix_records.append(_FixRecord(violation=violation, insertion=insertion))
# Descend into the function body; nested defs are NOT methods of the enclosing class.
self._func_stack = (*self._func_stack, node.name)
@@ -375,37 +674,66 @@ def _split_source_lines(source: str) -> list[str]:
return _LINE_BREAK_RE.split(source)[::2]
-def find_violations_in_source(source: str, *, module_qname: str, relative_path: str) -> list[Violation]:
+def find_violations_in_source(source: str, *, module_qname: str, relative_path: str, grants: Mapping[str, SubjectGrant]) -> list[Violation]:
"""Find all keyword-only convention violations in a single Python source string.
+ Registry-level freshness (dead grants) is NOT checked here — a single source string cannot know
+ whether a grant's def exists elsewhere; that is :func:`collect_all_violations`'s job.
+
Args:
source: The Python source text to scan.
module_qname: The dotted module path used to qualify each def (e.g. ``pipelex.builder.foo``).
relative_path: The source file path relative to the repo root (used in the violation's sort/identity key).
+ grants: The subject-grants registry content (see :func:`load_subject_grants`).
Returns:
The violations found, in source order.
"""
tree = ast.parse(source)
- collector = _Collector(module_qname=module_qname, relative_path=relative_path, source_lines=_split_source_lines(source))
+ collector = _Collector(module_qname=module_qname, relative_path=relative_path, source_lines=_split_source_lines(source), grants=grants)
collector.visit(tree)
return collector.violations
+def collect_def_infos_in_source(source: str, *, module_qname: str, relative_path: str) -> list[DefInfo]:
+ """Collect the per-def subject facts for a single source string (feeds the grant command).
+
+ Args:
+ source: The Python source text to scan.
+ module_qname: The dotted module path used to qualify each def.
+ relative_path: The source file path relative to the repo root (used in each info's key).
+
+ Returns:
+ One :class:`DefInfo` per def the walker encounters, in source order.
+ """
+ tree = ast.parse(source)
+ collector = _Collector(module_qname=module_qname, relative_path=relative_path, source_lines=_split_source_lines(source), grants={})
+ collector.visit(tree)
+ return collector.def_infos
+
+
# --------------------------------------------------------------------------------------
# Auto-fix (insert a bare `*` before the first non-self/cls positional-or-keyword param)
# --------------------------------------------------------------------------------------
-def _find_fix_records_in_source(source: str, *, module_qname: str, relative_path: str) -> list[_FixRecord]:
+def _find_fix_records_in_source(source: str, *, module_qname: str, relative_path: str, grants: Mapping[str, SubjectGrant]) -> list[_FixRecord]:
"""Collect a fix record (violation + insertion point) for every violation in a single source string."""
tree = ast.parse(source)
- collector = _Collector(module_qname=module_qname, relative_path=relative_path, source_lines=_split_source_lines(source), collect_fixes=True)
+ collector = _Collector(
+ module_qname=module_qname,
+ relative_path=relative_path,
+ source_lines=_split_source_lines(source),
+ grants=grants,
+ collect_fixes=True,
+ )
collector.visit(tree)
return collector.fix_records
-def fix_source(source: str, *, module_qname: str, relative_path: str) -> tuple[str, list[Violation], list[Violation]]:
+def fix_source(
+ source: str, *, module_qname: str, relative_path: str, grants: Mapping[str, SubjectGrant]
+) -> tuple[str, list[Violation], list[Violation]]:
"""Insert a bare ``*`` for every mechanically-fixable violation in a single source string.
Returns ``(new_source, fixed, unfixable)``: the rewritten text, the violations that were auto-fixed,
@@ -417,8 +745,9 @@ def fix_source(source: str, *, module_qname: str, relative_path: str) -> tuple[s
source: The Python source text to fix.
module_qname: The dotted module path used to qualify each def (e.g. ``pipelex.builder.foo``).
relative_path: The source file path relative to the repo root (used in each violation's key).
+ grants: The subject-grants registry content (an ungranted subject is a fixable violation).
"""
- records = _find_fix_records_in_source(source, module_qname=module_qname, relative_path=relative_path)
+ records = _find_fix_records_in_source(source, module_qname=module_qname, relative_path=relative_path, grants=grants)
fixable = [(record.violation, record.insertion) for record in records if record.insertion is not None]
unfixable = [record.violation for record in records if record.insertion is None]
if not fixable:
@@ -446,7 +775,7 @@ def fix_source(source: str, *, module_qname: str, relative_path: str) -> tuple[s
# --------------------------------------------------------------------------------------
-def _module_qname_for(path: Path) -> str:
+def module_qname_for(path: Path) -> str:
"""Compute the dotted module name for a ``.py`` file under the source root."""
parts = list(path.with_suffix("").parts)
if parts and parts[-1] == "__init__":
@@ -462,18 +791,53 @@ def iter_source_files(root: Path) -> Iterator[Path]:
yield path
-def collect_all_violations(root: Path) -> list[Violation]:
- """Scan every source file under ``root`` and return all violations, sorted by key."""
+def find_dead_grants(*, grants: Mapping[str, SubjectGrant], live_subject_keys: set[str]) -> list[Violation]:
+ """Report every grant whose key matches no inspected def with a positional subject (staleness is symmetric).
+
+ A grant dies when its def is deleted, renamed, moved, demoted to all-keyword, or newly carved out —
+ every one of those must force a deliberate registry decision rather than rot silently.
+
+ Args:
+ grants: The subject-grants registry content.
+ live_subject_keys: The keys of every inspected def that has a positional subject.
+ """
+ dead: list[Violation] = []
+ for key, grant in grants.items():
+ if key in live_subject_keys:
+ continue
+ relative_path, _, qualified_name = key.partition("::")
+ dead.append(
+ Violation(
+ relative_path=relative_path,
+ qualified_name=qualified_name,
+ lineno=0,
+ kind=ViolationKind.DEAD_GRANT,
+ detail=f"granted param '{grant.param}'",
+ )
+ )
+ return dead
+
+
+def collect_all_violations(root: Path, *, grants: Mapping[str, SubjectGrant]) -> list[Violation]:
+ """Scan every source file under ``root`` and return all violations (including dead grants), sorted by key."""
violations: list[Violation] = []
+ live_subject_keys: set[str] = set()
for path in iter_source_files(root):
relative_path = path.as_posix()
- module_qname = _module_qname_for(path)
+ module_qname = module_qname_for(path)
source = path.read_text(encoding="utf-8")
- violations.extend(find_violations_in_source(source, module_qname=module_qname, relative_path=relative_path))
+ tree = ast.parse(source)
+ collector = _Collector(module_qname=module_qname, relative_path=relative_path, source_lines=_split_source_lines(source), grants=grants)
+ collector.visit(tree)
+ violations.extend(collector.violations)
+ for def_info in collector.def_infos:
+ if def_info.subject_param is not None:
+ live_subject_keys.add(def_info.key)
+ violations.extend(find_dead_grants(grants=grants, live_subject_keys=live_subject_keys))
return sorted(violations, key=lambda violation: violation.key)
-def fix_all_violations(root: Path) -> tuple[list[Violation], list[Violation]]:
+def fix_all_violations(root: Path, *, grants: Mapping[str, SubjectGrant]) -> tuple[list[Violation], list[Violation]]:
"""Rewrite every mechanically-fixable violation under ``root`` in place.
Returns ``(fixed, unfixable)``, each sorted by key: the violations auto-fixed by inserting a bare
@@ -485,7 +849,7 @@ def fix_all_violations(root: Path) -> tuple[list[Violation], list[Violation]]:
unfixable_all: list[Violation] = []
for path in iter_source_files(root):
source = path.read_text(encoding="utf-8")
- new_source, fixed, unfixable = fix_source(source, module_qname=_module_qname_for(path), relative_path=path.as_posix())
+ new_source, fixed, unfixable = fix_source(source, module_qname=module_qname_for(path), relative_path=path.as_posix(), grants=grants)
if new_source != source:
path.write_text(new_source, encoding="utf-8")
fixed_all.extend(fixed)
@@ -524,12 +888,13 @@ def relative_source_path(path: Path, *, root: Path | None = None) -> Path | None
return relative
-def collect_violations_for_files(paths: Iterable[Path], *, root: Path | None = None) -> list[Violation]:
+def collect_violations_for_files(paths: Iterable[Path], *, root: Path | None = None, grants: Mapping[str, SubjectGrant]) -> list[Violation]:
"""Find violations across the given files; out-of-scope, missing, or unparseable files are skipped.
- Results are an exact subset of :func:`collect_all_violations`: ``relative_path`` and ``module_qname``
- are computed identically (the carve-out allowlist keys on both), so a single-file scan agrees with
- the full-tree scan for that file.
+ Results are an exact subset of :func:`collect_all_violations` for the def-level rules:
+ ``relative_path`` and ``module_qname`` are computed identically (the carve-out allowlist keys on
+ both), so a single-file scan agrees with the full-tree scan for that file. Registry-level freshness
+ (dead grants) is full-scan-only — a single file cannot know whether a grant's def exists elsewhere.
A file that does not parse yet (``SyntaxError``) is skipped rather than reported — a mid-edit file
is not a keyword-only violation, and the hook must never block on a transient syntax error.
@@ -537,6 +902,7 @@ def collect_violations_for_files(paths: Iterable[Path], *, root: Path | None = N
Args:
paths: Edited paths, absolute or relative to ``root``.
root: The repo root; defaults to the current working directory.
+ grants: The subject-grants registry content (see :func:`load_subject_grants`).
"""
base = root or Path.cwd()
violations: list[Violation] = []
@@ -551,8 +917,9 @@ def collect_violations_for_files(paths: Iterable[Path], *, root: Path | None = N
try:
file_violations = find_violations_in_source(
source,
- module_qname=_module_qname_for(relative),
+ module_qname=module_qname_for(relative),
relative_path=relative.as_posix(),
+ grants=grants,
)
except SyntaxError:
continue # not-yet-parseable mid-edit file is not a violation
@@ -570,15 +937,22 @@ def main(argv: list[str]) -> int:
the agent); returns ``0`` when the in-scope files are clean or none are in scope. Plain ``print`` to
stderr is intentional here — pulling in ``pipelex.log``/``rich`` would defeat the cold-start budget.
"""
- violations = collect_violations_for_files([Path(arg) for arg in argv])
+ try:
+ grants = load_subject_grants()
+ except SubjectGrantRegistryError as exc:
+ print(f"✗ Keyword-only check could not run: {exc}", file=sys.stderr)
+ return 2
+ violations = collect_violations_for_files([Path(arg) for arg in argv], grants=grants)
if not violations:
return 0
print("✗ Keyword-only violation(s) in edited pipelex source:", file=sys.stderr)
for violation in violations:
- print(f" {violation.relative_path}:{violation.lineno} {violation.qualified_name}", file=sys.stderr)
+ detail = f" ({violation.detail})" if violation.detail else ""
+ print(f" {violation.relative_path}:{violation.lineno} {violation.qualified_name} [{violation.kind}]{detail}", file=sys.stderr)
+ for kind in sorted({violation.kind for violation in violations}):
+ print(f" fix [{kind}]: {kind.remedy}", file=sys.stderr)
print(
- "Place a bare `*` so the non-subject parameters are keyword-only (or run `make fix-keyword-only`), "
- "or add `# kw-only: ignore` on the def line if justified — see docs/contribute/keyword-only-arguments.md",
+ "A justified one-off may use `# kw-only: ignore` on the def line — see docs/contribute/keyword-only-arguments.md",
file=sys.stderr,
)
return 2
diff --git a/pipelex/cli/dev_cli/commands/kit_cmd.py b/pipelex/cli/dev_cli/commands/kit_cmd.py
index 2a0c20d37..1ae5f9b5d 100644
--- a/pipelex/cli/dev_cli/commands/kit_cmd.py
+++ b/pipelex/cli/dev_cli/commands/kit_cmd.py
@@ -29,8 +29,8 @@ kit_app = typer.Typer(no_args_is_help=True)
def _sync_agent_rules(
- repo_root: Path | None,
*,
+ repo_root: Path | None,
agent_set: str | None,
cleanup: bool,
kit_index: KitIndex | None = None,
@@ -89,8 +89,8 @@ def _sync_agent_rules(
def _cleanup_other_targets(
- repo_root: Path,
*,
+ repo_root: Path,
kit_index: KitIndex,
preferred_targets: list[AgentTarget],
) -> None:
diff --git a/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py b/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py
index 718ac3f4a..de2c70cec 100644
--- a/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py
+++ b/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py
@@ -83,7 +83,7 @@ ELKJS = CDNAsset(
'''
-def _validate_version(name: str, *, value: str) -> str:
+def _validate_version(*, name: str, value: str) -> str:
if not _VERSION_PATTERN.fullmatch(value):
msg = f"Invalid {name} version {value!r}: expected a SemVer string like 1.2.3 or 1.2.3-rc.1"
raise PipelexCLIError(msg)
@@ -146,11 +146,7 @@ def _render_module_source(
def refresh_graph_ui_sri_cmd(
- mthds_ui_version: str | None = None,
- *,
- elkjs_version: str | None = None,
- output_path: Path | None = None,
- quiet: bool = False,
+ *, mthds_ui_version: str | None = None, elkjs_version: str | None = None, output_path: Path | None = None, quiet: bool = False
) -> None:
"""Refetch the pinned graph viewer assets and rewrite `standalone_assets.py`.
@@ -162,11 +158,11 @@ def refresh_graph_ui_sri_cmd(
"""
# `is None` (not falsy) so an explicit empty-string argument fails validation rather than silently falling back to the default.
target_mthds_ui_version = _validate_version(
- "mthds-ui",
+ name="mthds-ui",
value=current_pins.MTHDS_UI_VERSION if mthds_ui_version is None else mthds_ui_version,
)
target_elkjs_version = _validate_version(
- "elkjs",
+ name="elkjs",
value=current_pins.ELKJS_VERSION if elkjs_version is None else elkjs_version,
)
target_path = output_path or _DEFAULT_OUTPUT_PATH
diff --git a/pipelex/cli/dev_cli/commands/subject_grant_cmd.py b/pipelex/cli/dev_cli/commands/subject_grant_cmd.py
new file mode 100644
index 000000000..f267db7fe
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/subject_grant_cmd.py
@@ -0,0 +1,120 @@
+"""Command recording subject grants — the explicit permissions for positional subject parameters.
+
+The keyword-only convention allows a def's subject to stay positional ONLY under a grant recorded in
+``subject_grants.toml`` at the repo root (see ``docs/contribute/keyword-only-arguments.md``). This
+command is the sole WRITER of that registry: it validates the target def (it must exist, have a
+positional non-literal-typed subject, and same-qualname defs must agree on the subject name), records
+the subject's param name automatically, and rewrites the file sorted by key so diffs stay stable.
+
+The registry is READ by the stdlib-only ``keyword_only_guard`` (``tomllib``); writes happen only here,
+through ``pipelex.tools.misc.toml_utils`` (tomlkit) — never hand-rolled.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from rich.markup import escape
+
+from pipelex.cli.dev_cli.commands.keyword_only_guard import (
+ SOURCE_ROOT,
+ SUBJECT_GRANTS_FILE,
+ DefInfo,
+ SubjectGrant,
+ SubjectGrantRegistryError,
+ collect_def_infos_in_source,
+ load_subject_grants,
+ module_qname_for,
+)
+from pipelex.hub import get_console
+from pipelex.tools.misc.toml_utils import save_toml_to_path
+
+
+def _fail(message: str) -> None:
+ """Print an actionable refusal and exit 1 (the CI-gate idiom: loud, non-zero, no traceback)."""
+ console = get_console()
+ console.print(f"[red]✗ subject-grant: FAILED[/red] - {escape(message)}")
+ sys.exit(1)
+
+
+def _write_registry(*, grants: dict[str, SubjectGrant], root: Path) -> None:
+ """Rewrite the registry sorted by key — stable diffs, trivial merges (the file is machine-written)."""
+ data: dict[str, Any] = {"version": 1}
+ for key in sorted(grants):
+ grant = grants[key]
+ data[key] = {"param": grant.param, "rationale": grant.rationale}
+ save_toml_to_path(data, path=root / SUBJECT_GRANTS_FILE)
+
+
+def _validated_subject_param(*, func_key: str) -> str:
+ """Validate that ``func_key`` names a grantable def and return its subject param name, or exit 1.
+
+ Refusals: malformed key, out-of-scope or missing file, no def with that qualified name, def exempt
+ (carve-out — no grant needed), literal-typed subject (banned outright), no positional subject
+ (nothing to grant), or same-qualname defs disagreeing on the subject name (align them first).
+ """
+ relative_path_str, separator, qualified_name = func_key.partition("::")
+ if not separator or not qualified_name or not relative_path_str.endswith(".py"):
+ _fail(f'the FUNC key must be "<relative_path>::<qualified_name>" (got: {func_key!r})')
+ relative_path = Path(relative_path_str)
+ if not relative_path.parts or relative_path.parts[0] != SOURCE_ROOT.name:
+ _fail(f"'{relative_path_str}' is not under {SOURCE_ROOT.name}/ — only pipelex/ source is in the guard's scope")
+ if not relative_path.is_file():
+ _fail(f"source file '{relative_path_str}' does not exist (run from the repo root)")
+
+ def_infos = collect_def_infos_in_source(
+ relative_path.read_text(encoding="utf-8"),
+ module_qname=module_qname_for(relative_path),
+ relative_path=relative_path.as_posix(),
+ )
+ matching: list[DefInfo] = [def_info for def_info in def_infos if def_info.key == func_key]
+ if not matching:
+ _fail(f"no def '{qualified_name}' found in {relative_path_str} — check the qualified name (Class.method for methods)")
+ if all(def_info.status.is_exempt for def_info in matching):
+ _fail(f"def '{qualified_name}' is exempt (dunder / framework carve-out / allowlist / escape hatch) — no grant needed")
+ if any(def_info.status.is_literal for def_info in matching):
+ _fail(f"def '{qualified_name}' has a bool/int/float subject — literal-typed subjects can never be granted; make it keyword-only instead")
+ grantable = [def_info for def_info in matching if def_info.status.is_grantable]
+ if not grantable:
+ _fail(f"def '{qualified_name}' has no positional subject (already fully keyword-only) — nothing to grant")
+ subject_names = {def_info.subject_param for def_info in grantable if def_info.subject_param is not None}
+ if len(subject_names) > 1:
+ _fail(
+ f"defs sharing the qualified name '{qualified_name}' disagree on the subject name "
+ f"({', '.join(sorted(subject_names))}) — align them first (one grant covers them all)"
+ )
+ return subject_names.pop()
+
+
+def subject_grant_cmd(*, func_key: str | None, rationale: str | None, quiet: bool = False) -> None:
+ """Record a subject grant in ``subject_grants.toml``.
+
+ Args:
+ func_key: The def to grant, keyed ``<relative_path>::<qualified_name>`` (the guard's key format).
+ rationale: The on-the-record review decision — an honest, def-specific sentence.
+ quiet: If True, keep the success output to a single line.
+ """
+ console = get_console()
+ if not func_key:
+ _fail('a FUNC key is required: subject-grant "<relative_path>::<qualified_name>" --rationale "…"')
+ return # unreachable — _fail exits; keeps the type-checker aware func_key is str below
+ if rationale is None or not rationale.strip():
+ _fail("a non-empty --rationale is required — it is the on-the-record review decision for this grant")
+ return # unreachable
+ subject_param = _validated_subject_param(func_key=func_key)
+
+ try:
+ grants = load_subject_grants()
+ except SubjectGrantRegistryError as exc:
+ _fail(str(exc))
+ return # unreachable
+ previous = grants.get(func_key)
+ grants[func_key] = SubjectGrant(param=subject_param, rationale=rationale.strip())
+ _write_registry(grants=grants, root=Path.cwd())
+
+ action = "updated" if previous is not None else "recorded"
+ console.print(f"[green]✓ subject-grant {action}[/green]: [cyan]{escape(func_key)}[/cyan] (param [bold]{escape(subject_param)}[/bold])")
+ if not quiet:
+ console.print(f" [dim]rationale:[/dim] {escape(rationale.strip())}")
diff --git a/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py b/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py
index 711b877c0..9f7fee80f 100644
--- a/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py
+++ b/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py
@@ -83,7 +83,7 @@ def _display_result(result: MirrorDirResult, *, quiet: bool) -> None:
console.print()
-def sync_kit_configs_cmd(quiet: bool = False, *, dry_run: bool = False) -> None:
+def sync_kit_configs_cmd(*, quiet: bool = False, dry_run: bool = False) -> None:
"""Mirror the .pipelex/ directory into pipelex/kit/configs/.
Copies new and changed files and deletes files absent from .pipelex/, using
diff --git a/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py b/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py
index 1c11e879c..75ab95c46 100644
--- a/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py
+++ b/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py
@@ -74,13 +74,7 @@ def _display_sync_result(
console.print(table)
-def sync_main_config_cmd(
- target: SyncTarget = SyncTarget.ALL,
- *,
- dry_run: bool = False,
- quiet: bool = False,
- show_diff: bool = True,
-) -> None:
+def sync_main_config_cmd(*, target: SyncTarget = SyncTarget.ALL, dry_run: bool = False, quiet: bool = False, show_diff: bool = True) -> None:
"""Sync values from main config to kit and/or project configs.
Args:
diff --git a/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py b/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py
index ea38c2a3d..2ae835803 100644
--- a/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py
+++ b/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py
@@ -62,7 +62,7 @@ def _all_references_up_to_date(
return True
-def update_gateway_models_cmd(quiet: bool = False) -> None:
+def update_gateway_models_cmd(*, quiet: bool = False) -> None:
"""Update the Pipelex Gateway models reference files.
Fetches the current model specifications from the remote config and
diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.py
index 2d454a392..9b69c4de9 100644
--- a/pipelex/cli/error_handlers.py
+++ b/pipelex/cli/error_handlers.py
@@ -56,7 +56,7 @@ class ErrorContext(StrEnum):
_traceback_requested: ContextVar[bool] = ContextVar("pipelex_cli_traceback_requested", default=False)
-def set_traceback_requested(value: bool) -> None:
+def set_traceback_requested(*, value: bool) -> None:
"""Record whether --traceback was passed, independent of the Click context."""
_traceback_requested.set(value)
@@ -79,20 +79,14 @@ def is_traceback_requested() -> bool:
return bool(obj.get("traceback", False))
-def print_traceback_if_requested(console: Console) -> None:
+def print_traceback_if_requested(*, console: Console) -> None:
"""Print a Rich traceback of the current exception when --traceback is active."""
if is_traceback_requested():
console.print(Traceback())
def display_error_panel(
- console: Console,
- *,
- title: str,
- fields: list[tuple[str, str]],
- error_message: str | None,
- tip: str,
- links: list[tuple[str, str]],
+ *, console: Console, title: str, fields: list[tuple[str, str]], error_message: str | None, tip: str, links: list[tuple[str, str]]
) -> None:
"""Print the canonical CLI error panel.
@@ -134,13 +128,13 @@ def handle_model_choice_error(exc: PipeOperatorModelChoiceError, *, context: Err
setup/config error per its 0/1/2 policy); other contexts keep the default 1.
"""
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
report = exc.to_error_report()
tip = report.user_action_detail() or (
f"Check your model configuration in .pipelex/inference/ or specify a different model in the '{exc.pipe_code}' pipe."
)
display_error_panel(
- console,
+ console=console,
title=f"{context} failed because of a model choice could not be interpreted correctly",
fields=[
("Pipe", f"[yellow]'{escape(exc.pipe_code)}'[/yellow] [dim]({escape(exc.pipe_type)})[/dim]"),
@@ -167,7 +161,7 @@ def handle_model_availability_error(exc: PipeOperatorModelAvailabilityError, *,
setup/config error per its 0/1/2 policy); other contexts keep the default 1.
"""
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
report = exc.to_error_report()
fields: list[tuple[str, str]] = [
("Pipe", f"[yellow]'{escape(exc.pipe_code)}'[/yellow] [dim]({escape(exc.pipe_type)})[/dim]"),
@@ -183,7 +177,7 @@ def handle_model_availability_error(exc: PipeOperatorModelAvailabilityError, *,
f"Check your model configuration in .pipelex/inference/ or specify a different model in the '{exc.pipe_code}' pipe."
)
display_error_panel(
- console,
+ console=console,
title=f"{context} failed because a model wasn't available",
fields=fields,
error_message=escape(str(exc)),
@@ -204,7 +198,7 @@ def handle_model_deck_preset_error(exc: ModelDeckPresetValidatonError, *, contex
context: Context for the error message
"""
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
report = exc.to_error_report()
model_handle = exc.model_handle or ""
fields: list[tuple[str, str]] = [
@@ -238,7 +232,7 @@ def handle_model_deck_preset_error(exc: ModelDeckPresetValidatonError, *, contex
tip = "\n".join(tip_lines)
display_error_panel(
- console,
+ console=console,
title=f"{context} failed due to model deck preset validation error",
fields=fields,
error_message=escape(exc.message),
@@ -263,7 +257,7 @@ def _validation_category_header(category: ValidationErrorCategory) -> str:
return "Dry Run Error:"
-def _display_validation_error_item(console: Console, *, item: ValidationErrorItem, error_index: int) -> None:
+def _display_validation_error_item(*, console: Console, item: ValidationErrorItem, error_index: int) -> None:
"""Render one structured validation-error item: title, identity fields, message, fix, locators."""
error_type_display = item.error_type.replace("_", " ").title() if item.error_type else "Validation Error"
console.print(f"[bold yellow]{error_index}. {error_type_display}[/bold yellow]")
@@ -300,7 +294,7 @@ def _display_validation_error_item(console: Console, *, item: ValidationErrorIte
console.print()
-def display_validation_error_items(console: Console, *, items: list[ValidationErrorItem]) -> None:
+def display_validation_error_items(*, console: Console, items: list[ValidationErrorItem]) -> None:
"""Render structured validation-error items grouped by category, with per-item suggested fixes.
The single human renderer for bundle-validation diagnostics — used by ``pipelex validate``
@@ -325,7 +319,7 @@ def display_validation_error_items(console: Console, *, items: list[ValidationEr
console.print(f"[yellow]{escape(item.message)}[/yellow]\n")
case ValidationErrorCategory.BLUEPRINT_VALIDATION | ValidationErrorCategory.PIPE_FACTORY | ValidationErrorCategory.PIPE_VALIDATION:
for error_index, item in enumerate(category_items, 1):
- _display_validation_error_item(console, item=item, error_index=error_index)
+ _display_validation_error_item(console=console, item=item, error_index=error_index)
def handle_validate_bundle_error(
@@ -349,13 +343,13 @@ def handle_validate_bundle_error(
report = exc.to_error_report()
items = list(report.validation_errors or [])
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print("\n[bold red]❌ Bundle validation failed[/bold red]\n")
if bundle_path:
console.print(f"[bold cyan]Bundle:[/bold cyan] [yellow]{escape(str(bundle_path))}[/yellow]\n")
- display_validation_error_items(console, items=items)
+ display_validation_error_items(console=console, items=items)
# The shared items builder projects the dry-run channel only when it is the sole failure
# channel (the wire's structured-info invariant); the human surface keeps printing it
@@ -369,7 +363,7 @@ def handle_validate_bundle_error(
fixable_count = count_applicable_fixes(items, bundle_path=bundle_path, library_dirs=library_dirs) if bundle_path is not None else 0
if fixable_count and bundle_path is not None:
# Shared builder so the human and agent fix-command footers echo -L / --allow-signatures identically.
- fix_command = build_fix_command("pipelex", bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures)
+ fix_command = build_fix_command(executable="pipelex", bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures)
console.print(
f"[bold green]💡 {fixable_count} of these errors can be fixed automatically[/bold green] — run: [cyan]{escape(fix_command)}[/cyan]"
)
@@ -393,7 +387,7 @@ def handle_inference_setup_required_error(exc: InferenceSetupRequiredError) -> N
exc: The inference setup required error exception
"""
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print("\n[bold yellow]⚠ First-time inference setup required[/bold yellow]\n")
console.print(
@@ -420,7 +414,7 @@ def handle_telemetry_config_validation_error(exc: TelemetryConfigValidationError
exc: The telemetry config validation error exception
"""
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print("\n[bold red]❌ Telemetry configuration format has changed[/bold red]\n")
console.print(
@@ -450,7 +444,7 @@ def handle_gateway_terms_not_accepted_error(exc: GatewayTermsNotAcceptedError) -
exc: The gateway terms not accepted error exception
"""
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print("\n[bold red]❌ Pipelex Gateway terms not accepted[/bold red]\n")
console.print("[bold yellow]⚠ Action Required:[/bold yellow] Pipelex Gateway is enabled but you haven't accepted\nthe terms of service yet.\n")
@@ -477,7 +471,7 @@ def handle_gateway_api_key_missing_error(exc: GatewayApiKeyMissingError) -> NoRe
exc: The gateway API key missing error exception
"""
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print("\n[bold red]❌ Pipelex Gateway API key not set[/bold red]\n")
console.print("[bold yellow]⚠ Action Required:[/bold yellow] Pipelex Gateway is enabled but the API key\nenvironment variable is not set.\n")
@@ -507,7 +501,7 @@ def handle_gateway_do_not_track_conflict_error(exc: GatewayDoNotTrackConflictErr
exc: The gateway do not track conflict error exception
"""
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print("\n[bold red]❌ Pipelex Gateway requires telemetry[/bold red]\n")
console.print(
@@ -536,7 +530,7 @@ def handle_remote_config_validation_error(exc: RemoteConfigValidationError) -> N
exc: The remote config validation error exception
"""
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print("\n[bold red]❌ Pipelex Gateway configuration is invalid[/bold red]\n")
console.print(
@@ -573,7 +567,7 @@ def handle_remote_config_unavailable_error(exc: RemoteConfigUnavailableError) ->
exc: The remote config unavailable error exception
"""
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print("\n[bold red]❌ Pipelex Gateway is unreachable and no cached config is available[/bold red]\n")
console.print(
@@ -607,7 +601,7 @@ def handle_gateway_unknown_model_error(exc: GatewayUnknownModelError) -> NoRetur
exc: The gateway unknown model error exception
"""
console = get_console()
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print("\n[bold red]❌ Unknown gateway model handle[/bold red]\n")
console.print(f"[bold cyan]Model handle:[/bold cyan] [yellow]'{escape(exc.model_name)}'[/yellow]")
diff --git a/pipelex/cli/installed_methods.py b/pipelex/cli/installed_methods.py
index 8284ebf7b..2a1adeda2 100644
--- a/pipelex/cli/installed_methods.py
+++ b/pipelex/cli/installed_methods.py
@@ -41,8 +41,8 @@ class InstalledMethod(BaseModel):
def discover_installed_methods(
- include_global: bool = True,
*,
+ include_global: bool = True,
include_project: bool = True,
extra_search_dirs: list[Path] | None = None,
) -> list[InstalledMethod]:
diff --git a/pipelex/codegen/check.py b/pipelex/codegen/check.py
index 7c4107f6f..8cf67d6a5 100644
--- a/pipelex/codegen/check.py
+++ b/pipelex/codegen/check.py
@@ -79,7 +79,7 @@ class CodegenCheckReport(BaseModel):
def run_codegen_check(*, root: Path) -> CodegenCheckReport:
"""Run the offline drift check over `root` (the directory holding `codegen.lock`)."""
try:
- lock_path = resolve_output_path(root, relative_path=Path(CODEGEN_LOCK_FILENAME))
+ lock_path = resolve_output_path(root=root, relative_path=Path(CODEGEN_LOCK_FILENAME))
safe_root = lock_path.parent
lock = load_lock(lock_path)
if lock is None:
@@ -99,7 +99,7 @@ def run_codegen_check(*, root: Path) -> CodegenCheckReport:
def _check_locked_artifacts(*, root: Path, lock: CodegenLock) -> list[CodegenDrift]:
drifts: list[CodegenDrift] = []
for path, locked_hash in sorted(lock.hash_by_path().items()):
- file_path = resolve_artifact_path(root, artifact_path=path)
+ file_path = resolve_artifact_path(root=root, artifact_path=path)
if not file_path.is_file():
drifts.append(CodegenDrift(path=path, category=DriftCategory.MISSING, detail="Locked artifact is absent on disk."))
continue
@@ -127,7 +127,7 @@ def _check_present_artifact(*, path: str, file_path: Path, locked_hash: str) ->
def _find_orphans(*, root: Path, lock: CodegenLock) -> list[CodegenDrift]:
tracked = lock.paths()
orphans: list[CodegenDrift] = []
- for file_path in _iter_stampable_files(root):
+ for file_path in _iter_stampable_files(directory=root):
relative = file_path.relative_to(root).as_posix()
if relative in tracked:
continue
@@ -143,14 +143,14 @@ def _find_orphans(*, root: Path, lock: CodegenLock) -> list[CodegenDrift]:
return orphans
-def _iter_stampable_files(directory: Path) -> Iterator[Path]:
+def _iter_stampable_files(*, directory: Path) -> Iterator[Path]:
"""Yield stampable files under `directory`, pre-order and deterministic, pruning vendor/VCS dirs."""
for entry in sorted(directory.iterdir()):
if entry.is_symlink():
continue
if entry.is_dir():
if entry.name not in _SKIP_DIRS:
- yield from _iter_stampable_files(entry)
+ yield from _iter_stampable_files(directory=entry)
elif entry.suffix in STAMPABLE_SUFFIXES:
yield entry
diff --git a/pipelex/codegen/emission.py b/pipelex/codegen/emission.py
index 4c81c5a98..7ecb65605 100644
--- a/pipelex/codegen/emission.py
+++ b/pipelex/codegen/emission.py
@@ -115,7 +115,7 @@ def write_stamped_projection(
options: dict[str, str] | None = None,
) -> WriteReport:
"""Stamp, write-if-changed, prune de-listed files, and rewrite the lock for one projection run."""
- lock_path = resolve_output_path(output_dir, relative_path=Path(CODEGEN_LOCK_FILENAME))
+ lock_path = resolve_output_path(root=output_dir, relative_path=Path(CODEGEN_LOCK_FILENAME))
output_root = lock_path.parent
previous_paths = _previous_tracked_paths(lock_path)
@@ -133,15 +133,15 @@ def write_stamped_projection(
written: list[str] = []
unchanged: list[str] = []
for stamped_file in projection.files:
- destination = resolve_artifact_path(output_root, artifact_path=stamped_file.filename)
- if _write_if_changed(destination, content=stamped_file.content):
+ destination = resolve_artifact_path(root=output_root, artifact_path=stamped_file.filename)
+ if _write_if_changed(path=destination, content=stamped_file.content):
written.append(stamped_file.filename)
else:
unchanged.append(stamped_file.filename)
removed = _prune_delisted(output_dir=output_root, previous_paths=previous_paths, current_paths=projection.lock.paths())
- _write_if_changed(lock_path, content=projection.lock_content)
+ _write_if_changed(path=lock_path, content=projection.lock_content)
return WriteReport(written=written, unchanged=unchanged, removed=removed, lock_path=CODEGEN_LOCK_FILENAME)
@@ -149,7 +149,7 @@ def write_stamped_projection(
def _preflight_destinations(*, output_root: Path, projection: StampedProjection, previous_paths: set[str]) -> None:
"""Reject unowned destination collisions before any projection file is written."""
for stamped_file in projection.files:
- destination = resolve_artifact_path(output_root, artifact_path=stamped_file.filename)
+ destination = resolve_artifact_path(root=output_root, artifact_path=stamped_file.filename)
existing_content = failable_load_text_from_path(destination)
if existing_content is None or existing_content == stamped_file.content:
continue
@@ -176,7 +176,7 @@ def _previous_tracked_paths(lock_path: Path) -> set[str]:
return lock.paths() if lock is not None else set()
-def _write_if_changed(path: Path, *, content: str) -> bool:
+def _write_if_changed(*, path: Path, content: str) -> bool:
"""Write `content` to `path` only if it differs from what is already there. Returns whether it wrote."""
if failable_load_text_from_path(path) == content:
return False
@@ -189,7 +189,7 @@ def _prune_delisted(*, output_dir: Path, previous_paths: set[str], current_paths
"""Delete files that were tracked before but are no longer produced — only if they still carry our stamp."""
removed: list[str] = []
for relative in sorted(previous_paths - current_paths):
- stale_path = resolve_artifact_path(output_dir, artifact_path=relative)
+ stale_path = resolve_artifact_path(root=output_dir, artifact_path=relative)
content = failable_load_text_from_path(stale_path)
if content is None:
continue
diff --git a/pipelex/codegen/lock.py b/pipelex/codegen/lock.py
index 1299da8b2..6a1c64933 100644
--- a/pipelex/codegen/lock.py
+++ b/pipelex/codegen/lock.py
@@ -99,13 +99,13 @@ def validate_artifact_paths(paths: Iterable[str]) -> dict[str, Path]:
return validated
-def resolve_artifact_path(root: Path, *, artifact_path: str) -> Path:
+def resolve_artifact_path(*, root: Path, artifact_path: str) -> Path:
"""Resolve a validated artifact beneath `root` without following symbolic links."""
relative_path = validate_artifact_path(artifact_path)
- return resolve_output_path(root, relative_path=relative_path)
+ return resolve_output_path(root=root, relative_path=relative_path)
-def resolve_output_path(root: Path, *, relative_path: Path) -> Path:
+def resolve_output_path(*, root: Path, relative_path: Path) -> Path:
"""Resolve one internal output file beneath `root`, rejecting all symlink components."""
if relative_path.is_absolute() or not relative_path.parts or any(part in {"", ".", ".."} for part in relative_path.parts):
_raise_path_error(str(relative_path), reason="internal output path must be a canonical relative path")
@@ -118,7 +118,7 @@ def resolve_output_path(root: Path, *, relative_path: Path) -> Path:
_raise_path_error(str(normalized_root), reason="output root exists but is not a directory")
destination = normalized_root / relative_path
- _reject_symlink_components(normalized_root, relative_path=relative_path)
+ _reject_symlink_components(root=normalized_root, relative_path=relative_path)
resolved_root = normalized_root.resolve(strict=False)
resolved_destination = destination.resolve(strict=False)
if not resolved_destination.is_relative_to(resolved_root):
@@ -128,7 +128,7 @@ def resolve_output_path(root: Path, *, relative_path: Path) -> Path:
return destination
-def _reject_symlink_components(root: Path, *, relative_path: Path) -> None:
+def _reject_symlink_components(*, root: Path, relative_path: Path) -> None:
current = root
for part in relative_path.parts:
current /= part
diff --git a/pipelex/codegen/resolved_fields.py b/pipelex/codegen/resolved_fields.py
index f576dfe21..b9600cf37 100644
--- a/pipelex/codegen/resolved_fields.py
+++ b/pipelex/codegen/resolved_fields.py
@@ -84,7 +84,8 @@ def resolve_structure_fields(
) -> list[ResolvedField]:
"""Resolve every field of a structure blueprint into the neutral form, preserving field order."""
return [
- resolve_field(field_name, blueprint=field_blueprint, local_domain=local_domain) for field_name, field_blueprint in structure_blueprint.items()
+ resolve_field(field_name=field_name, blueprint=field_blueprint, local_domain=local_domain)
+ for field_name, field_blueprint in structure_blueprint.items()
]
@@ -106,12 +107,7 @@ def iter_imprecision_reasons(resolved_type: ResolvedType) -> list[str]:
return reasons
-def resolve_field(
- field_name: str,
- *,
- blueprint: ConceptStructureBlueprint,
- local_domain: str | None = None,
-) -> ResolvedField:
+def resolve_field(*, field_name: str, blueprint: ConceptStructureBlueprint, local_domain: str | None = None) -> ResolvedField:
"""Resolve a single structure-blueprint field into a neutral `ResolvedField`."""
return ResolvedField(
name=field_name,
diff --git a/pipelex/cogt/content_generation/dry_run_factory.py b/pipelex/cogt/content_generation/dry_run_factory.py
index cf2ce38ef..af42096aa 100644
--- a/pipelex/cogt/content_generation/dry_run_factory.py
+++ b/pipelex/cogt/content_generation/dry_run_factory.py
@@ -61,7 +61,7 @@ class DryRunFactory:
return f"{cls.generate_snake_case_code()}.{cls.generate_pascal_case_code()}"
@classmethod
- def generate_dict_snake_key_pascal_value(cls, num_items: int = 2) -> dict[str, str]:
+ def generate_dict_snake_key_pascal_value(cls, *, num_items: int = 2) -> dict[str, str]:
"""Generate a dict with snake_case keys and PascalCase values."""
result: dict[str, str] = {}
for _ in range(num_items):
diff --git a/pipelex/cogt/document/prompt_document.py b/pipelex/cogt/document/prompt_document.py
index 835f3a2bc..27bd22540 100644
--- a/pipelex/cogt/document/prompt_document.py
+++ b/pipelex/cogt/document/prompt_document.py
@@ -68,7 +68,7 @@ class PromptDocumentUri(BaseModel):
return mime_type_to_extension(self.mime_type)
return UNKNOWN_FILE_TYPE
- def get_content_hash(self, length: int | None = None) -> str:
+ def get_content_hash(self, *, length: int | None = None) -> str:
"""Return a hash of the document content."""
return hash_sha256(self.uri, length=length)
@@ -109,7 +109,7 @@ class PromptDocumentBase64(BaseModel):
"""Get the document type (extension) from the file contents."""
return self.get_file_type().extension
- def get_content_hash(self, length: int | None = None) -> str:
+ def get_content_hash(self, *, length: int | None = None) -> str:
"""Return a hash of the document content."""
return hash_sha256(self.base64_data, length=length)
@@ -142,7 +142,7 @@ class PromptDocumentBinary(BaseModel):
"""Get the document type (extension) from the file contents."""
return self.get_file_type().extension
- def get_content_hash(self, length: int | None = None) -> str:
+ def get_content_hash(self, *, length: int | None = None) -> str:
"""Return a hash of the document content."""
return hash_sha256(self.raw_bytes, length=length)
diff --git a/pipelex/cogt/document/prompt_document_factory.py b/pipelex/cogt/document/prompt_document_factory.py
index eda37ad88..0afe8cb83 100644
--- a/pipelex/cogt/document/prompt_document_factory.py
+++ b/pipelex/cogt/document/prompt_document_factory.py
@@ -16,12 +16,7 @@ from pipelex.tools.misc.base64_utils import (
class PromptDocumentFactory:
@classmethod
def make_prompt_document(
- cls,
- uri: str | None = None,
- *,
- base64_data: str | None = None,
- raw_bytes: bytes | None = None,
- mime_type: str | None = None,
+ cls, *, uri: str | None = None, base64_data: str | None = None, raw_bytes: bytes | None = None, mime_type: str | None = None
) -> PromptDocument:
"""Create a PromptDocument from the provided input.
diff --git a/pipelex/cogt/image/prompt_image_factory.py b/pipelex/cogt/image/prompt_image_factory.py
index 41a38f8a0..d8dc85bdc 100644
--- a/pipelex/cogt/image/prompt_image_factory.py
+++ b/pipelex/cogt/image/prompt_image_factory.py
@@ -15,13 +15,7 @@ from pipelex.tools.misc.base64_utils import (
class PromptImageFactory:
@classmethod
- def make_prompt_image(
- cls,
- uri: str | None = None,
- *,
- base64_data: str | None = None,
- raw_bytes: bytes | None = None,
- ) -> PromptImage:
+ def make_prompt_image(cls, *, uri: str | None = None, base64_data: str | None = None, raw_bytes: bytes | None = None) -> PromptImage:
"""Create a PromptImage from the provided input.
Args:
diff --git a/pipelex/cogt/inference/transport_retry.py b/pipelex/cogt/inference/transport_retry.py
index 6bb0baa36..9774b2c01 100644
--- a/pipelex/cogt/inference/transport_retry.py
+++ b/pipelex/cogt/inference/transport_retry.py
@@ -78,7 +78,7 @@ def _transport_retry_wait(retry_state: RetryCallState) -> float:
return _exponential_wait(retry_state)
-def _make_retry_predicate(retry_on_ambiguous_failure: bool) -> Callable[[BaseException], bool]:
+def _make_retry_predicate(*, retry_on_ambiguous_failure: bool) -> Callable[[BaseException], bool]:
"""Build the retry predicate for the configured idempotency posture.
With ``retry_on_ambiguous_failure`` True the predicate retries the full transient set — every
@@ -134,7 +134,7 @@ async def request_with_transport_retry(
httpx.HTTPError: The last attempt's error, re-raised once the retry budget is exhausted.
"""
retrying = AsyncRetrying(
- retry=retry_if_exception(_make_retry_predicate(retry_on_ambiguous_failure)),
+ retry=retry_if_exception(_make_retry_predicate(retry_on_ambiguous_failure=retry_on_ambiguous_failure)),
wait=_transport_retry_wait,
stop=stop_after_attempt(max_retries + 1),
reraise=True,
diff --git a/pipelex/cogt/llm/instructor_retry.py b/pipelex/cogt/llm/instructor_retry.py
index 9ad6a8d50..f81ba2f67 100644
--- a/pipelex/cogt/llm/instructor_retry.py
+++ b/pipelex/cogt/llm/instructor_retry.py
@@ -4,7 +4,7 @@ from pydantic import ValidationError
from tenacity import AsyncRetrying, retry_if_exception_type, stop_after_attempt
-def make_instructor_schema_retrying(max_attempts: int) -> AsyncRetrying:
+def make_instructor_schema_retrying(*, max_attempts: int) -> AsyncRetrying:
"""Build a ``tenacity.AsyncRetrying`` that confines ``instructor``'s retry to schema re-ask.
Passed a bare ``int``, ``instructor``'s ``max_retries`` builds a retry loop whose default
diff --git a/pipelex/cogt/llm/llm_prompt.py b/pipelex/cogt/llm/llm_prompt.py
index 96c792ced..9a4311275 100644
--- a/pipelex/cogt/llm/llm_prompt.py
+++ b/pipelex/cogt/llm/llm_prompt.py
@@ -51,7 +51,7 @@ class LLMPrompt(BaseModel):
def __format__(self, format_spec: str) -> str:
return self.desc()
- def desc(self, truncate_text_length: int | None = None) -> str:
+ def desc(self, *, truncate_text_length: int | None = None) -> str:
description = "LLM Prompt:"
if truncate_text_length:
if self.system_text:
diff --git a/pipelex/cogt/llm/llm_prompt_template.py b/pipelex/cogt/llm/llm_prompt_template.py
index 74e41ab75..a441a9b28 100644
--- a/pipelex/cogt/llm/llm_prompt_template.py
+++ b/pipelex/cogt/llm/llm_prompt_template.py
@@ -57,8 +57,8 @@ class LLMPromptTemplate(LLMPromptFactoryAbstract):
async def _make_llm_prompt(
self,
- system_text: str | None = None,
*,
+ system_text: str | None = None,
user_text: str | None = None,
user_images: list[PromptImage] | None = None,
is_user_images_append: bool | None = None,
diff --git a/pipelex/cogt/llm/llm_setting.py b/pipelex/cogt/llm/llm_setting.py
index df8556087..c46fbcf6b 100644
--- a/pipelex/cogt/llm/llm_setting.py
+++ b/pipelex/cogt/llm/llm_setting.py
@@ -91,12 +91,7 @@ class LLMSettingChoices(ConfigModel):
return {item for item in (self.for_text, self.for_object) if isinstance(item, ModelReference)}
@classmethod
- def make_completed_with_defaults(
- cls,
- for_text: LLMModelChoice | None = None,
- *,
- for_object: LLMModelChoice | None = None,
- ) -> Self:
+ def make_completed_with_defaults(cls, *, for_text: LLMModelChoice | None = None, for_object: LLMModelChoice | None = None) -> Self:
return cls(
for_text=for_text,
for_object=for_object,
diff --git a/pipelex/cogt/model_backends/backend_library.py b/pipelex/cogt/model_backends/backend_library.py
index 3a9c32504..9154f7358 100644
--- a/pipelex/cogt/model_backends/backend_library.py
+++ b/pipelex/cogt/model_backends/backend_library.py
@@ -56,8 +56,8 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):
def load(
self,
- secrets_provider: SecretsProviderAbstract,
*,
+ secrets_provider: SecretsProviderAbstract,
backends_library_path: str,
backends_dir_path: str,
include_disabled: bool = False,
diff --git a/pipelex/cogt/model_backends/model_lists.py b/pipelex/cogt/model_backends/model_lists.py
index 818941032..f1c759561 100644
--- a/pipelex/cogt/model_backends/model_lists.py
+++ b/pipelex/cogt/model_backends/model_lists.py
@@ -86,8 +86,8 @@ class ModelLister:
@staticmethod
def _display_unsupported_sdks_message(
- any_listed: bool,
*,
+ any_listed: bool,
unsupported_sdks: list[str],
backend_name: str,
models_by_sdk: dict[str, list[str]],
diff --git a/pipelex/cogt/model_routing/routing_profile.py b/pipelex/cogt/model_routing/routing_profile.py
index 7a6dd0ef5..822aef0e6 100644
--- a/pipelex/cogt/model_routing/routing_profile.py
+++ b/pipelex/cogt/model_routing/routing_profile.py
@@ -23,7 +23,7 @@ class RoutingProfile(ConfigModel):
optional_routes: dict[str, str] = Field(default_factory=dict)
fallback_order: list[str] | None = None # Ordered list of backends for fallback
- def get_backend_match_for_model(self, enabled_backends: list[str], *, model_name: str) -> BackendMatchForModel | None:
+ def get_backend_match_for_model(self, *, enabled_backends: list[str], model_name: str) -> BackendMatchForModel | None:
"""Get the backend name for a given model name.
Args:
diff --git a/pipelex/cogt/models/model_deck_check.py b/pipelex/cogt/models/model_deck_check.py
index 6bde84c77..8ff023488 100644
--- a/pipelex/cogt/models/model_deck_check.py
+++ b/pipelex/cogt/models/model_deck_check.py
@@ -25,7 +25,9 @@ def _raise_model_choice_not_found(
available_options: list[str],
) -> NoReturn:
"""Compute fuzzy suggestions and raise ModelChoiceNotFoundError."""
- suggestions, wrong_sigil_hints, cross_suggestions = suggest_model_alternatives(model_deck, model_type=model_type, name=name, kind=reference_kind)
+ suggestions, wrong_sigil_hints, cross_suggestions = suggest_model_alternatives(
+ model_deck=model_deck, model_type=model_type, name=name, kind=reference_kind
+ )
raise ModelChoiceNotFoundError(
message=msg,
model_type=model_type,
diff --git a/pipelex/cogt/models/model_manager.py b/pipelex/cogt/models/model_manager.py
index f76b780e5..55fd76053 100644
--- a/pipelex/cogt/models/model_manager.py
+++ b/pipelex/cogt/models/model_manager.py
@@ -63,8 +63,8 @@ class ModelManager(ModelManagerAbstract):
@override
def setup(
self,
- secrets_provider: SecretsProviderAbstract,
*,
+ secrets_provider: SecretsProviderAbstract,
gateway_config: GatewayConfig | None,
gateway_config_source: RemoteConfigSource | None,
needs_inference: bool = True,
@@ -190,13 +190,7 @@ class ModelManager(ModelManagerAbstract):
return choice.model
@classmethod
- def _resolve_terminal_candidates(
- cls,
- deck: ModelDeck,
- *,
- ref: ModelReference,
- model_type: ModelType,
- ) -> list[str]:
+ def _resolve_terminal_candidates(cls, *, deck: ModelDeck, ref: ModelReference, model_type: ModelType) -> list[str]:
"""Return every terminal handle reachable from ``ref`` via aliases/waterfalls.
For ``HANDLE`` references: returns ``[name]`` (bare strings are HANDLEs by design —
diff --git a/pipelex/cogt/models/model_manager_abstract.py b/pipelex/cogt/models/model_manager_abstract.py
index 4c97ff188..cc0252d6c 100644
--- a/pipelex/cogt/models/model_manager_abstract.py
+++ b/pipelex/cogt/models/model_manager_abstract.py
@@ -21,8 +21,8 @@ class ModelManagerAbstract(ABC):
@abstractmethod
def setup(
self,
- secrets_provider: SecretsProviderAbstract,
*,
+ secrets_provider: SecretsProviderAbstract,
gateway_config: GatewayConfig | None,
gateway_config_source: RemoteConfigSource | None,
needs_inference: bool = True,
diff --git a/pipelex/cogt/models/model_suggestion.py b/pipelex/cogt/models/model_suggestion.py
index 8aad00dab..942ad58dc 100644
--- a/pipelex/cogt/models/model_suggestion.py
+++ b/pipelex/cogt/models/model_suggestion.py
@@ -73,11 +73,7 @@ def get_collection_keys(
def suggest_model_alternatives(
- model_deck: ModelDeck,
- *,
- model_type: ModelType,
- name: str,
- kind: ModelReferenceKind,
+ *, model_deck: ModelDeck, model_type: ModelType, name: str, kind: ModelReferenceKind
) -> tuple[list[str], list[str], list[str]]:
"""Find fuzzy matches and detect wrong-sigil usage for a model name.
diff --git a/pipelex/core/bundles/pipelex_bundle_blueprint.py b/pipelex/core/bundles/pipelex_bundle_blueprint.py
index 91526f16b..cba6a2a7c 100644
--- a/pipelex/core/bundles/pipelex_bundle_blueprint.py
+++ b/pipelex/core/bundles/pipelex_bundle_blueprint.py
@@ -186,7 +186,7 @@ class PipelexBundleBlueprint(BaseModel):
# (offending dotted key + stripped bare key) structurally for the fix planner.
raise InvalidPipeCodeSyntaxError(msg, offending_code=pipe_code, stripped_code=stripped)
raise ValueError(msg)
- normalized[pipe_code] = normalize_typeless_signature_section(pipe_code, pipe_section=pipe_section)
+ normalized[pipe_code] = normalize_typeless_signature_section(pipe_code=pipe_code, pipe_section=pipe_section)
return normalized
@model_validator(mode="after")
diff --git a/pipelex/core/concepts/concept.py b/pipelex/core/concepts/concept.py
index 31f5f448c..ad94627b3 100644
--- a/pipelex/core/concepts/concept.py
+++ b/pipelex/core/concepts/concept.py
@@ -227,7 +227,7 @@ class Concept(ConceptAbstract):
return result, generator.imports_needed
- def _render_schema_representation(self, is_multiple: bool = False) -> tuple[dict[str, Any], set[str]]:
+ def _render_schema_representation(self, *, is_multiple: bool = False) -> tuple[dict[str, Any], set[str]]:
"""Render JSON Schema for this concept.
Args:
diff --git a/pipelex/core/concepts/concept_factory.py b/pipelex/core/concepts/concept_factory.py
index 63b8bf3f1..d6d0e4d88 100644
--- a/pipelex/core/concepts/concept_factory.py
+++ b/pipelex/core/concepts/concept_factory.py
@@ -85,7 +85,7 @@ class DomainAndConceptCode(BaseModel):
class ConceptFactory:
@classmethod
- def make(cls, concept_code: str, *, domain_code: str, description: str, structure_class_name: str, refines: str | None = None) -> Concept:
+ def make(cls, *, concept_code: str, domain_code: str, description: str, structure_class_name: str, refines: str | None = None) -> Concept:
return Concept(
code=concept_code,
domain_code=domain_code,
@@ -365,8 +365,8 @@ class ConceptFactory:
@classmethod
def _handle_basic_blueprint(
cls,
- concept_code: str,
*,
+ concept_code: str,
domain_code: str,
description: str,
) -> StructureNameAndRefine:
diff --git a/pipelex/core/concepts/concept_representation_generator.py b/pipelex/core/concepts/concept_representation_generator.py
index 86e983d3d..682169e10 100644
--- a/pipelex/core/concepts/concept_representation_generator.py
+++ b/pipelex/core/concepts/concept_representation_generator.py
@@ -110,7 +110,7 @@ class ConceptRepresentationGenerator:
case ConceptRepresentationFormat.JSON:
return fields_dict
case ConceptRepresentationFormat.PYTHON:
- return self._format_as_python(class_name, fields=fields_dict)
+ return self._format_as_python(class_name=class_name, fields=fields_dict)
case ConceptRepresentationFormat.SCHEMA:
msg = "Schema format is not supported by ConceptRepresentationGenerator. Use render_concept_representation on Concept instead."
raise ValueError(msg)
@@ -296,7 +296,7 @@ class ConceptRepresentationGenerator:
case ConceptRepresentationFormat.JSON:
return fields_dict
case ConceptRepresentationFormat.PYTHON:
- return self._format_as_python(class_name, fields=fields_dict)
+ return self._format_as_python(class_name=class_name, fields=fields_dict)
case ConceptRepresentationFormat.SCHEMA:
msg = "Schema format is not supported by ConceptRepresentationGenerator. Use render_concept_representation on Concept instead."
raise ValueError(msg)
@@ -348,7 +348,7 @@ class ConceptRepresentationGenerator:
type_name = getattr(actual_type, "__name__", str(actual_type))
return f"{field_name}_{type_name}"
- def _format_as_python(self, class_name: str, *, fields: dict[str, Any]) -> str:
+ def _format_as_python(self, *, class_name: str, fields: dict[str, Any]) -> str:
"""Format a class instantiation as Python code string.
Args:
diff --git a/pipelex/core/concepts/concept_structure_blueprint.py b/pipelex/core/concepts/concept_structure_blueprint.py
index 54130b1b8..bfa9aebd7 100644
--- a/pipelex/core/concepts/concept_structure_blueprint.py
+++ b/pipelex/core/concepts/concept_structure_blueprint.py
@@ -166,38 +166,38 @@ class ConceptStructureBlueprint(BaseModel):
match self.type:
case ConceptStructureBlueprintFieldType.TEXT:
if not isinstance(self.default_value, str):
- self._raise_type_mismatch_error("str", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="str", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.INTEGER:
if not isinstance(self.default_value, int):
- self._raise_type_mismatch_error("int", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="int", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.BOOLEAN:
if not isinstance(self.default_value, bool):
- self._raise_type_mismatch_error("bool", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="bool", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.NUMBER:
if not isinstance(self.default_value, (int, float)):
- self._raise_type_mismatch_error("number (int or float)", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="number (int or float)", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.LIST:
if not isinstance(self.default_value, list):
- self._raise_type_mismatch_error("list", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="list", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.DICT:
if not isinstance(self.default_value, dict):
- self._raise_type_mismatch_error("dict", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="dict", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.DATE:
# A calendar date, not a datetime: datetime is a subclass of date, so reject it explicitly
# (a datetime default would carry a time the `date` field silently drops).
if not isinstance(self.default_value, date) or isinstance(self.default_value, datetime):
- self._raise_type_mismatch_error("date", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="date", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.DATETIME:
if not isinstance(self.default_value, datetime):
- self._raise_type_mismatch_error("datetime", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="datetime", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.TIME:
if not isinstance(self.default_value, time):
- self._raise_type_mismatch_error("time", actual_type_name=type(self.default_value).__name__)
+ self._raise_type_mismatch_error(expected_type_name="time", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.CONCEPT:
# CONCEPT type cannot have default values, this is already validated in validate_structure_blueprint
# This case is here for exhaustiveness
pass
- def _raise_type_mismatch_error(self, expected_type_name: str, *, actual_type_name: str) -> None:
+ def _raise_type_mismatch_error(self, *, expected_type_name: str, actual_type_name: str) -> None:
msg = f"default_value type mismatch: expected {expected_type_name} for type '{self.type}', but got {actual_type_name}"
raise ValueError(msg)
diff --git a/pipelex/core/concepts/native/pinned_blueprints.py b/pipelex/core/concepts/native/pinned_blueprints.py
index f9f1c0f3e..e357505c3 100644
--- a/pipelex/core/concepts/native/pinned_blueprints.py
+++ b/pipelex/core/concepts/native/pinned_blueprints.py
@@ -70,35 +70,35 @@ def _pinned_structure(native_code: NativeConceptCode) -> dict[str, ConceptStruct
return None
case NativeConceptCode.TEXT:
return {
- "text": _text_field("The text", required=True),
+ "text": _text_field(description="The text", required=True),
}
case NativeConceptCode.IMAGE:
return {
- "url": _text_field("The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL", required=True),
- "public_url": _text_field("The public URL of the image"),
- "source_prompt": _text_field("The source prompt of the image"),
- "source_negative_prompt": _text_field("The source negative prompt of the image"),
- "caption": _text_field("The caption of the image"),
- "mime_type": _text_field("The MIME type of the image"),
+ "url": _text_field(description="The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL", required=True),
+ "public_url": _text_field(description="The public URL of the image"),
+ "source_prompt": _text_field(description="The source prompt of the image"),
+ "source_negative_prompt": _text_field(description="The source negative prompt of the image"),
+ "caption": _text_field(description="The caption of the image"),
+ "mime_type": _text_field(description="The MIME type of the image"),
"width": ConceptStructureBlueprint(description="The width of the image, in pixels", type=ConceptStructureBlueprintFieldType.INTEGER),
"height": ConceptStructureBlueprint(
description="The height of the image, in pixels", type=ConceptStructureBlueprintFieldType.INTEGER
),
- "filename": _text_field("The original filename of the image"),
+ "filename": _text_field(description="The original filename of the image"),
}
case NativeConceptCode.DOCUMENT:
return {
- "url": _text_field("The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL", required=True),
- "public_url": _text_field("The public HTTPS URL of the document"),
- "mime_type": _text_field("The MIME type of the document"),
- "filename": _text_field("The original filename of the document"),
- "title": _text_field("The title of the document or source"),
- "snippet": _text_field("A text snippet or excerpt from the document"),
+ "url": _text_field(description="The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL", required=True),
+ "public_url": _text_field(description="The public HTTPS URL of the document"),
+ "mime_type": _text_field(description="The MIME type of the document"),
+ "filename": _text_field(description="The original filename of the document"),
+ "title": _text_field(description="The title of the document or source"),
+ "snippet": _text_field(description="A text snippet or excerpt from the document"),
}
case NativeConceptCode.HTML:
return {
- "inner_html": _text_field("The inner HTML of the content", required=True),
- "css_class": _text_field("The CSS class of the content", required=True),
+ "inner_html": _text_field(description="The inner HTML of the content", required=True),
+ "css_class": _text_field(description="The CSS class of the content", required=True),
}
case NativeConceptCode.TEXT_AND_IMAGES:
return {
@@ -113,7 +113,7 @@ def _pinned_structure(native_code: NativeConceptCode) -> dict[str, ConceptStruct
item_type="concept",
item_concept_ref=NativeConceptCode.IMAGE.concept_ref,
),
- "raw_html": _text_field("The raw HTML of the fetched page, if requested"),
+ "raw_html": _text_field(description="The raw HTML of the fetched page, if requested"),
}
case NativeConceptCode.NUMBER:
return {
@@ -175,7 +175,7 @@ def _pinned_structure(native_code: NativeConceptCode) -> dict[str, ConceptStruct
}
case NativeConceptCode.SEARCH_RESULT:
return {
- "answer": _text_field("The answer to the search query", required=True),
+ "answer": _text_field(description="The answer to the search query", required=True),
"sources": ConceptStructureBlueprint(
description="The source documents supporting the answer",
type=ConceptStructureBlueprintFieldType.LIST,
@@ -186,5 +186,5 @@ def _pinned_structure(native_code: NativeConceptCode) -> dict[str, ConceptStruct
}
-def _text_field(description: str, *, required: bool = False) -> ConceptStructureBlueprint:
+def _text_field(*, description: str, required: bool = False) -> ConceptStructureBlueprint:
return ConceptStructureBlueprint(description=description, type=ConceptStructureBlueprintFieldType.TEXT, required=required)
diff --git a/pipelex/core/concepts/structure_generation/generator.py b/pipelex/core/concepts/structure_generation/generator.py
index 76061e9e4..1c96dfa6f 100644
--- a/pipelex/core/concepts/structure_generation/generator.py
+++ b/pipelex/core/concepts/structure_generation/generator.py
@@ -73,7 +73,7 @@ class StructureGenerator:
"""
# Generate the class
class_code = self._generate_class_source_code_from_blueprint(
- class_name, structure_blueprint=structure_blueprint, base_class_name=base_class_name, description=description
+ class_name=class_name, structure_blueprint=structure_blueprint, base_class_name=base_class_name, description=description
)
# Generate the complete module with a header comment
@@ -246,8 +246,8 @@ class StructureGenerator:
def _generate_class_source_code_from_blueprint(
self,
- class_name: str,
*,
+ class_name: str,
structure_blueprint: dict[str, ConceptStructureBlueprint],
base_class_name: str | None = None,
description: str = "",
diff --git a/pipelex/core/interpreter/bundle_elaborator.py b/pipelex/core/interpreter/bundle_elaborator.py
index fcb5321c4..7ace6555d 100644
--- a/pipelex/core/interpreter/bundle_elaborator.py
+++ b/pipelex/core/interpreter/bundle_elaborator.py
@@ -104,8 +104,8 @@ class BundleElaborator:
@classmethod
def _elaborate_preliminary_text(
cls,
- pipe_code: str,
*,
+ pipe_code: str,
pipe_blueprint: PipeLLMBlueprint,
new_pipe_dict: dict[str, PipeBlueprintUnion],
elaboration_metadata: dict[str, ElaborationMetadata],
diff --git a/pipelex/core/memory/input_shaper.py b/pipelex/core/memory/input_shaper.py
index 9bb3c3a72..59268d928 100644
--- a/pipelex/core/memory/input_shaper.py
+++ b/pipelex/core/memory/input_shaper.py
@@ -596,7 +596,7 @@ class InputShaper:
@classmethod
def _render_expected_shape(cls, *, stuff_spec: StuffSpec) -> str:
"""Render the expected input shape from the signature, reused verbatim in D4 error hints."""
- return json.dumps(stuff_spec.render_stuff_spec(ConceptRepresentationFormat.JSON), ensure_ascii=False)
+ return json.dumps(stuff_spec.render_stuff_spec(output_format=ConceptRepresentationFormat.JSON), ensure_ascii=False)
@classmethod
def _describe_value(cls, value: Any) -> str:
diff --git a/pipelex/core/pipes/inputs/input_stuff_specs.py b/pipelex/core/pipes/inputs/input_stuff_specs.py
index 7fec305f4..a155c85b7 100644
--- a/pipelex/core/pipes/inputs/input_stuff_specs.py
+++ b/pipelex/core/pipes/inputs/input_stuff_specs.py
@@ -87,8 +87,8 @@ class InputStuffSpecs(RootModel[PipeInputsRoot]):
def add_stuff_spec(
self,
- variable_name: str,
*,
+ variable_name: str,
concept: Concept,
multiplicity: VariableMultiplicity | None = None,
presence: PresenceMarker = PresenceMarker.PLAIN,
@@ -159,7 +159,7 @@ class InputStuffSpecs(RootModel[PipeInputsRoot]):
def is_empty(self) -> bool:
return not bool(self.root)
- def format_for_display(self, indent: int = 6) -> str:
+ def format_for_display(self, *, indent: int = 6) -> str:
"""Format input stuff specs as a human-readable multi-line string.
Args:
@@ -184,10 +184,10 @@ class InputStuffSpecs(RootModel[PipeInputsRoot]):
"""
template: dict[str, Any] = {}
for var_name, stuff_spec in self.root.items():
- template[var_name] = stuff_spec.render_stuff_spec(ConceptRepresentationFormat.JSON)
+ template[var_name] = stuff_spec.render_stuff_spec(output_format=ConceptRepresentationFormat.JSON)
return template
- def render_inputs(self, indent: int = 2) -> str:
+ def render_inputs(self, *, indent: int = 2) -> str:
"""Render a JSON representation for all stuff specs as a formatted string.
Args:
diff --git a/pipelex/core/pipes/output/output_renderer.py b/pipelex/core/pipes/output/output_renderer.py
index c02e20ca0..4866f694c 100644
--- a/pipelex/core/pipes/output/output_renderer.py
+++ b/pipelex/core/pipes/output/output_renderer.py
@@ -50,7 +50,7 @@ def _collect_possible_outputs(
for mapped_pipe_code in sorted(mapped_pipe_codes):
mapped_pipe = get_required_pipe(pipe_code=mapped_pipe_code)
try:
- output_dict = mapped_pipe.output.render_stuff_spec(output_format)
+ output_dict = mapped_pipe.output.render_stuff_spec(output_format=output_format)
content = output_dict.get("content", output_dict)
possible_outputs.append(
{
@@ -89,7 +89,7 @@ def _collect_possible_outputs(
# Otherwise render the last pipe's output
try:
- output_dict = last_pipe.output.render_stuff_spec(output_format)
+ output_dict = last_pipe.output.render_stuff_spec(output_format=output_format)
content = output_dict.get("content", output_dict)
return [
{
@@ -184,7 +184,7 @@ def _render_json_output(the_pipe: PipeAbstract, *, indent: int = 2) -> str:
return json.dumps(result, indent=indent, ensure_ascii=False)
# Normal output rendering - returns dict with "concept" and "content"
- output_dict = the_pipe.output.render_stuff_spec(ConceptRepresentationFormat.JSON)
+ output_dict = the_pipe.output.render_stuff_spec(output_format=ConceptRepresentationFormat.JSON)
return json.dumps(output_dict, indent=indent, ensure_ascii=False)
@@ -225,7 +225,7 @@ def _render_python_output(the_pipe: PipeAbstract) -> str:
return "\n".join(lines)
# Normal output rendering
- output_dict = the_pipe.output.render_stuff_spec(ConceptRepresentationFormat.PYTHON)
+ output_dict = the_pipe.output.render_stuff_spec(output_format=ConceptRepresentationFormat.PYTHON)
concept_ref = output_dict.get("concept", "")
content = output_dict.get("content", "")
@@ -269,5 +269,5 @@ def _render_schema_output(the_pipe: PipeAbstract, *, indent: int = 2) -> str:
return json.dumps(result, indent=indent, ensure_ascii=False)
# Normal output rendering - get JSON Schema directly
- output_dict = the_pipe.output.render_stuff_spec(ConceptRepresentationFormat.SCHEMA)
+ output_dict = the_pipe.output.render_stuff_spec(output_format=ConceptRepresentationFormat.SCHEMA)
return json.dumps(output_dict, indent=indent, ensure_ascii=False)
diff --git a/pipelex/core/pipes/pipe_abstract.py b/pipelex/core/pipes/pipe_abstract.py
index 7f422c11f..358489558 100644
--- a/pipelex/core/pipes/pipe_abstract.py
+++ b/pipelex/core/pipes/pipe_abstract.py
@@ -140,7 +140,7 @@ class PipeAbstract(ABC, BaseModel):
return unique_concepts
- def _register_execution_data(self, job_metadata: JobMetadata, *, execution_data: dict[str, Any]) -> None:
+ def _register_execution_data(self, *, job_metadata: JobMetadata, execution_data: dict[str, Any]) -> None:
"""Register execution metadata with the graph tracer.
Called by pipe subclasses during execution to capture runtime-resolved data
@@ -445,8 +445,8 @@ class PipeAbstract(ABC, BaseModel):
@final
async def validate_before_run(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -517,8 +517,8 @@ class PipeAbstract(ABC, BaseModel):
@abstractmethod
async def _validate_before_run(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -528,8 +528,8 @@ class PipeAbstract(ABC, BaseModel):
@final
async def validate_after_run(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -541,8 +541,8 @@ class PipeAbstract(ABC, BaseModel):
@abstractmethod
async def _validate_after_run(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -561,7 +561,7 @@ class PipeAbstract(ABC, BaseModel):
"""
@abstractmethod
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
"""Return the stuff specs that are needed for the pipe to run.
Args:
@@ -589,8 +589,8 @@ class PipeAbstract(ABC, BaseModel):
@final
async def run_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -615,8 +615,8 @@ class PipeAbstract(ABC, BaseModel):
@final
async def _run_pipe_traced(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -837,8 +837,8 @@ class PipeAbstract(ABC, BaseModel):
def _make_lifted_output(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
liftable: list[AbsentInput],
pipe_run_params: PipeRunParams,
@@ -908,8 +908,8 @@ class PipeAbstract(ABC, BaseModel):
@final
async def live_run_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -981,8 +981,8 @@ class PipeAbstract(ABC, BaseModel):
@final
async def dry_run_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -1001,8 +1001,8 @@ class PipeAbstract(ABC, BaseModel):
@abstractmethod
async def _live_run_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -1013,8 +1013,8 @@ class PipeAbstract(ABC, BaseModel):
@abstractmethod
async def _dry_run_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -1024,8 +1024,8 @@ class PipeAbstract(ABC, BaseModel):
def _start_pipe_span(
self,
- parent_otel_context: OtelContext,
*,
+ parent_otel_context: OtelContext,
pipeline_run_id: str,
working_memory: WorkingMemory,
) -> tuple[Span | None, bool]:
diff --git a/pipelex/core/pipes/pipe_blueprint.py b/pipelex/core/pipes/pipe_blueprint.py
index 705661c14..b71c9a670 100644
--- a/pipelex/core/pipes/pipe_blueprint.py
+++ b/pipelex/core/pipes/pipe_blueprint.py
@@ -53,7 +53,7 @@ def explicit_signature_tag_migration_message(pipe_code: Any) -> str:
)
-def normalize_typeless_signature_section(pipe_code: Any, *, pipe_section: Any, allowed_keys: frozenset[str] = SIGNATURE_ONLY_KEYS) -> Any:
+def normalize_typeless_signature_section(*, pipe_code: Any, pipe_section: Any, allowed_keys: frozenset[str] = SIGNATURE_ONLY_KEYS) -> Any:
"""Inject the internal `PipeSignature` tag on a typeless contract-only section, reject a typeless
section that declares more than the contract, and reject a section that still writes the retired
explicit `type = "PipeSignature"` tag. Non-dict values (already-built pipe instances) and sections
diff --git a/pipelex/core/pipes/pipe_factory.py b/pipelex/core/pipes/pipe_factory.py
index 91236061c..e5b5772c5 100644
--- a/pipelex/core/pipes/pipe_factory.py
+++ b/pipelex/core/pipes/pipe_factory.py
@@ -26,8 +26,8 @@ class PipeFactoryProtocol(Protocol[PipeBlueprintType, PipeAbstractType]):
@classmethod
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/core/pipes/stuff_spec/stuff_spec.py b/pipelex/core/pipes/stuff_spec/stuff_spec.py
index 989feea34..5de710254 100644
--- a/pipelex/core/pipes/stuff_spec/stuff_spec.py
+++ b/pipelex/core/pipes/stuff_spec/stuff_spec.py
@@ -38,7 +38,7 @@ class StuffSpec(BaseModel):
presence=self.presence,
)
- def render_stuff_spec(self, output_format: ConceptRepresentationFormat) -> dict[str, Any]:
+ def render_stuff_spec(self, *, output_format: ConceptRepresentationFormat) -> dict[str, Any]:
"""Render a representation of this stuff spec.
Args:
diff --git a/pipelex/core/qualified_ref.py b/pipelex/core/qualified_ref.py
index bc0aaa469..729f7a08c 100644
--- a/pipelex/core/qualified_ref.py
+++ b/pipelex/core/qualified_ref.py
@@ -133,7 +133,7 @@ class QualifiedRef(BaseModel):
return ref
@classmethod
- def from_domain_and_code(cls, domain_path: str, *, local_code: str) -> "QualifiedRef":
+ def from_domain_and_code(cls, *, domain_path: str, local_code: str) -> "QualifiedRef":
"""Build from already-known parts.
Args:
diff --git a/pipelex/core/stuffs/image_content.py b/pipelex/core/stuffs/image_content.py
index 57f9b070e..0e59796d6 100644
--- a/pipelex/core/stuffs/image_content.py
+++ b/pipelex/core/stuffs/image_content.py
@@ -79,8 +79,8 @@ class ImageContent(StuffContent):
def render_with_images(
self,
- registry: ImageRegistry,
*,
+ registry: ImageRegistry,
text_format: TextFormat, # noqa: ARG002
) -> str:
"""Register this image and return a token."""
diff --git a/pipelex/core/stuffs/list_content.py b/pipelex/core/stuffs/list_content.py
index 159a1f1ff..d259091c0 100644
--- a/pipelex/core/stuffs/list_content.py
+++ b/pipelex/core/stuffs/list_content.py
@@ -140,15 +140,15 @@ class ListContent(StuffContent, Generic[StuffContentType]):
def render_with_images(
self,
- registry: ImageRegistry,
*,
+ registry: ImageRegistry,
text_format: TextFormat,
) -> str:
"""Render each item with images."""
parts: list[str] = []
for item in self.items:
if isinstance(item, ImageRenderable): # pyright: ignore[reportUnnecessaryIsInstance]
- rendered = item.render_with_images(registry, text_format=text_format)
+ rendered = item.render_with_images(registry=registry, text_format=text_format)
else:
rendered = item.rendered_markdown()
if rendered:
diff --git a/pipelex/core/stuffs/structured_content.py b/pipelex/core/stuffs/structured_content.py
index 963f4ffe0..74ae724ee 100644
--- a/pipelex/core/stuffs/structured_content.py
+++ b/pipelex/core/stuffs/structured_content.py
@@ -51,8 +51,8 @@ class StructuredContent(StuffContent):
def render_with_images(
self,
- registry: ImageRegistry,
*,
+ registry: ImageRegistry,
text_format: TextFormat,
) -> str:
"""Render with image extraction - recursively handles nested structures.
@@ -98,7 +98,7 @@ class StructuredContent(StuffContent):
if value is None:
return ""
if isinstance(value, ImageRenderable):
- return value.render_with_images(registry, text_format=text_format)
+ return value.render_with_images(registry=registry, text_format=text_format)
if isinstance(value, (list, tuple)):
parts: list[str] = []
list_value = cast("list[Any]", value)
@@ -116,7 +116,7 @@ class StructuredContent(StuffContent):
dict_parts.append(f"{key}: {rendered}")
return "\n".join(dict_parts)
if isinstance(value, StuffContent):
- return value.rendered_for_prompt(text_format)
+ return value.rendered_for_prompt(text_format=text_format)
return str(value)
# -------------------------------------------------------------------------
diff --git a/pipelex/core/stuffs/stuff.py b/pipelex/core/stuffs/stuff.py
index f11a4b35c..8445d85de 100644
--- a/pipelex/core/stuffs/stuff.py
+++ b/pipelex/core/stuffs/stuff.py
@@ -267,7 +267,7 @@ class Stuff(PrettyRenderable, CustomBaseModel, StuffAbstract[Concept, StuffConte
title = f"Some stuff ([bold green]{self.concept.code}[/bold green])"
return self.content.rendered_pretty(title=title, depth=depth)
- def pretty_print_stuff(self, title: str | None = None) -> None:
+ def pretty_print_stuff(self, *, title: str | None = None) -> None:
title = title or f"[cyan]{self.stuff_name}[/cyan] ([bold green]{self.concept.code}[/bold green])"
self.content.pretty_print_content(title=title)
diff --git a/pipelex/core/stuffs/stuff_artefact.py b/pipelex/core/stuffs/stuff_artefact.py
index 5dd787762..cae8995dc 100644
--- a/pipelex/core/stuffs/stuff_artefact.py
+++ b/pipelex/core/stuffs/stuff_artefact.py
@@ -344,7 +344,7 @@ class StuffArtefact:
# TextFormatRenderable protocol implementation
# -------------------------------------------------------------------------
- async def rendered_for_template_async(self, text_format: TextFormat) -> str:
+ async def rendered_for_template_async(self, *, text_format: TextFormat) -> str:
"""Render content for templates in the specified text format.
Args:
@@ -362,8 +362,8 @@ class StuffArtefact:
def render_with_images(
self,
- registry: ImageRegistry,
*,
+ registry: ImageRegistry,
text_format: TextFormat,
) -> str:
"""Delegate to content's render_with_images.
@@ -386,7 +386,7 @@ class StuffArtefact:
f"ImageContent, TextAndImagesContent, ListContent, StructuredContent (and subclasses like PageContent)."
)
raise TypeError(msg)
- return content.render_with_images(registry, text_format=text_format)
+ return content.render_with_images(registry=registry, text_format=text_format)
# -------------------------------------------------------------------------
# Access to underlying Stuff
diff --git a/pipelex/core/stuffs/stuff_content.py b/pipelex/core/stuffs/stuff_content.py
index 228a799a6..4059c19e8 100644
--- a/pipelex/core/stuffs/stuff_content.py
+++ b/pipelex/core/stuffs/stuff_content.py
@@ -76,7 +76,7 @@ class StuffContent(PrettyRenderable, CustomBaseModel, StuffContentAbstract):
return kajson.dumps(self.smart_dump(), indent=4)
@final
- def rendered_for_prompt(self, text_format: TextFormat = TextFormat.PLAIN) -> str:
+ def rendered_for_prompt(self, *, text_format: TextFormat = TextFormat.PLAIN) -> str:
match text_format:
case TextFormat.PLAIN:
return self.rendered_plain()
@@ -92,7 +92,7 @@ class StuffContent(PrettyRenderable, CustomBaseModel, StuffContentAbstract):
# -------------------------------------------------------------------------------------
@final
- async def rendered_for_template_async(self, text_format: TextFormat = TextFormat.PLAIN) -> str:
+ async def rendered_for_template_async(self, *, text_format: TextFormat = TextFormat.PLAIN) -> str:
match text_format:
case TextFormat.PLAIN:
return await self.rendered_plain_async()
@@ -132,7 +132,7 @@ class StuffContent(PrettyRenderable, CustomBaseModel, StuffContentAbstract):
json_data = self.smart_dump()
return JSON.from_data(json_data, indent=4)
- def pretty_print_content(self, title: str | None = None) -> None:
+ def pretty_print_content(self, *, title: str | None = None) -> None:
pretty = self.rendered_pretty()
width = PrettyPrinter.pretty_width()
pretty_print(pretty, title=title, width=width)
diff --git a/pipelex/core/stuffs/stuff_content_factory.py b/pipelex/core/stuffs/stuff_content_factory.py
index 313d8a7da..1d72237d5 100644
--- a/pipelex/core/stuffs/stuff_content_factory.py
+++ b/pipelex/core/stuffs/stuff_content_factory.py
@@ -15,7 +15,7 @@ from pipelex.hub import get_class_registry
class StuffContentFactory:
@classmethod
def make_content_from_value(
- cls, stuff_content_subclass: type[StuffContent], *, value: dict[str, Any] | str | bool | datetime.date | datetime.time
+ cls, *, stuff_content_subclass: type[StuffContent], value: dict[str, Any] | str | bool | datetime.date | datetime.time
) -> StuffContent:
# bool must be handled ahead of any future int handling (bool is a subclass of int) and before model_validate,
# which rejects a bare bool. Covers native YesNoContent and the subclasses generated for concepts refining YesNo.
diff --git a/pipelex/core/stuffs/text_and_images_content.py b/pipelex/core/stuffs/text_and_images_content.py
index 959e57e57..b31b6eb02 100644
--- a/pipelex/core/stuffs/text_and_images_content.py
+++ b/pipelex/core/stuffs/text_and_images_content.py
@@ -75,14 +75,14 @@ class TextAndImagesContent(StuffContent):
def render_with_images(
self,
- registry: ImageRegistry,
*,
+ registry: ImageRegistry,
text_format: TextFormat,
) -> str:
"""Render text, then register images."""
parts: list[str] = []
if self.text:
- parts.append(self.text.rendered_for_prompt(text_format))
+ parts.append(self.text.rendered_for_prompt(text_format=text_format))
if self.images:
for image in self.images:
image_index = registry.register_image(image)
diff --git a/pipelex/errors/error_pages_generator.py b/pipelex/errors/error_pages_generator.py
index 94ec0a47b..ead89333f 100644
--- a/pipelex/errors/error_pages_generator.py
+++ b/pipelex/errors/error_pages_generator.py
@@ -251,8 +251,8 @@ def render_error_page(cls: type[PipelexError]) -> str:
def generate_error_pages(
- output_dir: Path,
*,
+ output_dir: Path,
classes: Iterable[type[PipelexError]] | None = None,
) -> ErrorPagesReport:
"""Write one markdown page per :class:`PipelexError` subclass into ``output_dir``.
@@ -308,7 +308,7 @@ def generate_error_pages(
expected_stems: set[str] = {page_slug(cls) for cls in target_classes} | {INDEX_STEM}
for cls in target_classes:
target = output_dir / f"{page_slug(cls)}.md"
- _commit_page(target, new_content=render_error_page(cls), report=report)
+ _commit_page(target=target, new_content=render_error_page(cls), report=report)
# Macro listing pages — one per non-empty macro area. Their stems join
# ``expected_stems`` so a macro that still has classes is never treated as an
@@ -316,14 +316,16 @@ def generate_error_pages(
# falls through to ``_remove_orphans`` and is deleted like any stale page.
by_subsystem = _group_by_subsystem(target_classes)
for macro_slug, macro_heading in _MACRO_SECTIONS:
- sections = _subsystems_for_macro(macro_slug, by_subsystem=by_subsystem)
+ sections = _subsystems_for_macro(macro_slug=macro_slug, by_subsystem=by_subsystem)
if not sections:
continue
- _commit_page(output_dir / f"{macro_slug}.md", new_content=render_macro_page(macro_heading, sections=sections), report=report)
+ _commit_page(
+ target=output_dir / f"{macro_slug}.md", new_content=render_macro_page(macro_heading=macro_heading, sections=sections), report=report
+ )
expected_stems.add(macro_slug)
index_target = output_dir / f"{INDEX_STEM}.md"
- _commit_page(index_target, new_content=render_index_page(by_subsystem), report=report)
+ _commit_page(target=index_target, new_content=render_index_page(by_subsystem), report=report)
_remove_orphans(output_dir=output_dir, expected_stems=expected_stems, report=report)
@@ -352,7 +354,7 @@ def _remove_orphans(output_dir: Path, *, expected_stems: set[str], report: Error
report.removed.append(path)
-def _commit_page(target: Path, *, new_content: str, report: ErrorPagesReport) -> None:
+def _commit_page(*, target: Path, new_content: str, report: ErrorPagesReport) -> None:
"""Apply the write / unchanged / preserved classification to one target path."""
if target.exists():
existing = target.read_text(encoding="utf-8")
@@ -445,8 +447,8 @@ def _group_by_subsystem(classes: Iterable[type[PipelexError]]) -> dict[str, list
def _subsystems_for_macro(
- macro_slug: str,
*,
+ macro_slug: str,
by_subsystem: dict[str, list[type[PipelexError]]],
) -> list[tuple[str, list[type[PipelexError]]]]:
"""Return the ``(heading, classes)`` subsystem sections that belong on a macro page.
@@ -469,7 +471,7 @@ def _subsystems_for_macro(
return sections
-def render_macro_page(macro_heading: str, *, sections: list[tuple[str, list[type[PipelexError]]]]) -> str:
+def render_macro_page(*, macro_heading: str, sections: list[tuple[str, list[type[PipelexError]]]]) -> str:
"""Render one macro listing page: a ``## subsystem`` block per section, class links beneath.
``sections`` is the output of :func:`_subsystems_for_macro` — already ordered
@@ -530,7 +532,7 @@ def render_index_page(by_subsystem: dict[str, list[type[PipelexError]]]) -> str:
"",
]
for macro_slug, macro_heading in _MACRO_SECTIONS:
- sections = _subsystems_for_macro(macro_slug, by_subsystem=by_subsystem)
+ sections = _subsystems_for_macro(macro_slug=macro_slug, by_subsystem=by_subsystem)
if not sections:
continue
covered = ", ".join(heading for heading, _ in sections)
diff --git a/pipelex/graph/graph_tracer.py b/pipelex/graph/graph_tracer.py
index 64d61b1ca..62685cec3 100644
--- a/pipelex/graph/graph_tracer.py
+++ b/pipelex/graph/graph_tracer.py
@@ -220,8 +220,8 @@ class GraphTracer(GraphTracerProtocol):
@override
def setup(
self,
- graph_id: str,
*,
+ graph_id: str,
data_inclusion: DataInclusionConfig,
pipeline_ref_domain: str | None = None,
pipeline_ref_main_pipe: str | None = None,
@@ -385,7 +385,7 @@ class GraphTracer(GraphTracerProtocol):
producer_data = self._nodes.get(producer_node_id)
if producer_data is None:
return False
- return output_digest_is_optional(producer_data.output_specs, digest=digest)
+ return output_digest_is_optional(output_specs=producer_data.output_specs, digest=digest)
def _generate_batch_item_edges(self) -> None:
"""Generate BATCH_ITEM edges for batch fan-out.
@@ -489,8 +489,8 @@ class GraphTracer(GraphTracerProtocol):
@override
def register_batch_item_extraction(
self,
- list_stuff_code: str,
*,
+ list_stuff_code: str,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -533,8 +533,8 @@ class GraphTracer(GraphTracerProtocol):
@override
def register_batch_aggregation(
self,
- output_list_stuff_code: str,
*,
+ output_list_stuff_code: str,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -577,8 +577,8 @@ class GraphTracer(GraphTracerProtocol):
@override
def register_parallel_combine(
self,
- combined_stuff_code: str,
*,
+ combined_stuff_code: str,
branch_stuff_codes: list[str],
parallel_controller_node_id: str,
) -> None:
@@ -709,8 +709,8 @@ class GraphTracer(GraphTracerProtocol):
@override
def register_execution_data(
self,
- node_id: str,
*,
+ node_id: str,
execution_data: dict[str, Any],
) -> None:
"""Register execution metadata for a node."""
@@ -801,8 +801,8 @@ class GraphTracer(GraphTracerProtocol):
@override
def register_controller_output(
self,
- node_id: str,
*,
+ node_id: str,
output_spec: IOSpec,
) -> None:
"""Register an additional output for a controller node.
@@ -993,8 +993,8 @@ class GraphTracer(GraphTracerProtocol):
def add_selected_outcome_edge(
self,
- condition_node_id: str,
*,
+ condition_node_id: str,
outcome_node_id: str,
outcome_value: str,
) -> None:
diff --git a/pipelex/graph/graph_tracer_protocol.py b/pipelex/graph/graph_tracer_protocol.py
index 186b8bc98..daaf94e1f 100644
--- a/pipelex/graph/graph_tracer_protocol.py
+++ b/pipelex/graph/graph_tracer_protocol.py
@@ -18,8 +18,8 @@ class GraphTracerProtocol(Protocol):
def setup(
self,
- graph_id: str,
*,
+ graph_id: str,
data_inclusion: DataInclusionConfig,
pipeline_ref_domain: str | None = None,
pipeline_ref_main_pipe: str | None = None,
@@ -187,8 +187,8 @@ class GraphTracerProtocol(Protocol):
def register_controller_output(
self,
- node_id: str,
*,
+ node_id: str,
output_spec: IOSpec,
) -> None:
"""Register an additional output for a controller node.
@@ -204,8 +204,8 @@ class GraphTracerProtocol(Protocol):
def register_batch_item_extraction(
self,
- list_stuff_code: str,
*,
+ list_stuff_code: str,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -223,8 +223,8 @@ class GraphTracerProtocol(Protocol):
def register_batch_aggregation(
self,
- output_list_stuff_code: str,
*,
+ output_list_stuff_code: str,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -243,8 +243,8 @@ class GraphTracerProtocol(Protocol):
def register_parallel_combine(
self,
- combined_stuff_code: str,
*,
+ combined_stuff_code: str,
branch_stuff_codes: list[str],
parallel_controller_node_id: str,
) -> None:
@@ -262,8 +262,8 @@ class GraphTracerProtocol(Protocol):
def register_execution_data(
self,
- node_id: str,
*,
+ node_id: str,
execution_data: dict[str, Any],
) -> None:
"""Register execution metadata for a node.
@@ -284,8 +284,8 @@ class GraphTracerNoOp(GraphTracerProtocol):
@override
def setup(
self,
- graph_id: str,
*,
+ graph_id: str,
data_inclusion: DataInclusionConfig,
pipeline_ref_domain: str | None = None,
pipeline_ref_main_pipe: str | None = None,
@@ -342,8 +342,8 @@ class GraphTracerNoOp(GraphTracerProtocol):
@override
def register_execution_data(
self,
- node_id: str,
*,
+ node_id: str,
execution_data: dict[str, Any],
) -> None:
pass
@@ -389,8 +389,8 @@ class GraphTracerNoOp(GraphTracerProtocol):
@override
def register_controller_output(
self,
- node_id: str,
*,
+ node_id: str,
output_spec: IOSpec,
) -> None:
pass
@@ -398,8 +398,8 @@ class GraphTracerNoOp(GraphTracerProtocol):
@override
def register_batch_item_extraction(
self,
- list_stuff_code: str,
*,
+ list_stuff_code: str,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -409,8 +409,8 @@ class GraphTracerNoOp(GraphTracerProtocol):
@override
def register_batch_aggregation(
self,
- output_list_stuff_code: str,
*,
+ output_list_stuff_code: str,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -420,8 +420,8 @@ class GraphTracerNoOp(GraphTracerProtocol):
@override
def register_parallel_combine(
self,
- combined_stuff_code: str,
*,
+ combined_stuff_code: str,
branch_stuff_codes: list[str],
parallel_controller_node_id: str,
) -> None:
diff --git a/pipelex/graph/graphspec.py b/pipelex/graph/graphspec.py
index 59303b572..159bfa6df 100644
--- a/pipelex/graph/graphspec.py
+++ b/pipelex/graph/graphspec.py
@@ -215,7 +215,7 @@ class IOSpec(BaseModel):
return _truncate_string(value, max_length=MAX_PREVIEW_LENGTH)
-def output_digest_is_optional(output_specs: Sequence[IOSpec], *, digest: str) -> bool:
+def output_digest_is_optional(*, output_specs: Sequence[IOSpec], digest: str) -> bool:
"""Whether a producer registered ``digest`` as a declared-optional (`?`) output.
The optional marker rides the output IOSpec's ``extra`` dict (set at the pipe-run
diff --git a/pipelex/hub.py b/pipelex/hub.py
index 9ac1ed2b7..e32f9b331 100644
--- a/pipelex/hub.py
+++ b/pipelex/hub.py
@@ -231,7 +231,7 @@ class PipelexHub:
def set_content_generator(self, content_generator: ContentGeneratorProtocol):
self._content_generator = content_generator
- def set_dry_run_forced(self, is_forced: bool) -> None:
+ def set_dry_run_forced(self, *, is_forced: bool) -> None:
self._is_dry_run_forced = is_forced
def is_dry_run_forced(self) -> bool:
diff --git a/pipelex/kit/agent_rules/commands.md b/pipelex/kit/agent_rules/commands.md
index a4ec2714d..09b899027 100644
--- a/pipelex/kit/agent_rules/commands.md
+++ b/pipelex/kit/agent_rules/commands.md
@@ -20,14 +20,15 @@
## Keyword-only arguments check
- Non-subject function parameters across `pipelex/` source must be keyword-only (a bare `*` after the subject). The convention is mechanically enforced and already runs as part of `make agent-check`, but you can invoke it on its own:
+ Non-subject function parameters across `pipelex/` source must be keyword-only, and a positional subject is legal only under a grant recorded in `subject_grants.toml`. The convention is mechanically enforced and already runs as part of `make agent-check`, but you can invoke it on its own:
```bash
make check-keyword-only # alias: make cko — read-only gate; hard-blocks on any violation
make fix-keyword-only # alias: make fko — auto-insert a bare * for mechanically-fixable violations
+ make subject-grant FUNC="<path>::<qualname>" RATIONALE="…" # alias: make sgr — grant a positional subject
```
- `check-keyword-only` owns the pass/fail gate; `fix-keyword-only` rewrites what it can and reports the shapes it can't fix mechanically (resolve those by hand). See [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md) for the full convention.
+ `check-keyword-only` owns the pass/fail gate; `fix-keyword-only` rewrites what it can (including ungranted subjects — grant BEFORE running checks if the subject should stay positional) and reports the shapes it can't fix mechanically (resolve those by hand). See [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md) for the full convention.
## Cleaning Derived Files
@@ -133,3 +134,10 @@
# or rotate elkjs alongside:
.venv/bin/pipelex-dev refresh-graph-ui-sri --mthds-ui-version 0.6.3 --elkjs-version 0.11.1
```
+
+ - **`drift`**: Drift contracts — deterministic review obligations between code and docs, declared in the root `drift.toml` (see `docs/contribute/drift-contracts.md`). When `make drift-check` (part of `make check` and CI) reports an open contract: run `make drift-plan` to see what changed and what to review, actually review the targets and fix what is stale, `git add` the trigger files (the digest reads the git index, not the working tree), then record the review with `make drift-ack CONTRACT=<id> RATIONALE="…"`. The rationale is the on-the-record review decision — write an honest sentence. There is no bypass flag; "reviewed, no doc change needed" is a legitimate rationale.
+
+ ```bash
+ make drift-plan
+ make drift-ack CONTRACT=config-docs RATIONALE="Documented the new setting; other config pages unaffected."
+ ```
diff --git a/pipelex/kit/agent_rules/pipelex_standards.md b/pipelex/kit/agent_rules/pipelex_standards.md
index cecabef06..30e779a0c 100644
--- a/pipelex/kit/agent_rules/pipelex_standards.md
+++ b/pipelex/kit/agent_rules/pipelex_standards.md
@@ -19,11 +19,13 @@ When adding validation or fields, decide which layer they belong to. Language ru
## Keyword-only arguments
-Non-subject function parameters across `pipelex/` source must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shape places a bare `*` after the subject:
+Non-subject function parameters across `pipelex/` source must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shapes:
-- `def f(subject, *, opt1, opt2): ...` — the first non-`self`/`cls` parameter (the subject) may stay positional; everything after it must be keyword-only. Making the subject keyword-only too (`def f(*, a, b)`) is always allowed and often preferable.
-- A lone subject (`def render(node)`) is compliant; a second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is a violation.
+- `def f(*, opt1, opt2): ...` — fully keyword-only. Always compliant, needs nothing.
+- `def f(subject, *, opt1, opt2): ...` — a positional subject (including a lone one, `def render(node)`) is legal ONLY under a **subject grant** recorded in `subject_grants.toml` at the repo root: `make subject-grant FUNC="<path>::<qualname>" RATIONALE="…"` (alias `sgr`). Grant when the call reads as a verb–object sentence with a single obvious operand; when in doubt, go keyword-only.
+- A second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is always a violation, grant or not.
+- A `bool`/`int`/`float` subject (incl. `Optional`/union-with-`None` forms) is banned outright — grants are impossible; `f(True)` call sites are never acceptable.
-The rule is mechanically enforced by the `check-keyword-only` AST guard, which runs in `make agent-check`, in the `make check` aggregate, and in CI; the tree is fully compliant, so it hard-blocks on **any** violation. Carve-outs (dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, `@override` impls) are skipped automatically. A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line). Watch for functions a framework or the interpreter invokes positionally (callbacks, `__import__` hooks, route handlers): the type checker is blind to those, so `make agent-test` is the safety net.
+The rule is mechanically enforced by the `check-keyword-only` AST guard, which runs in `make agent-check`, in the `make check` aggregate, and in CI; the tree is fully compliant, so it hard-blocks on **any** violation, and staleness is symmetric (a grant whose def was renamed, moved, demoted, or deleted fails the check until the registry is cleaned up). Carve-outs (dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, `@override` impls) are skipped automatically. A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line). Watch for functions a framework or the interpreter invokes positionally (callbacks, `__import__` hooks, route handlers): the type checker is blind to those, so `make agent-test` is the safety net. ⚠ `make agent-check` runs the auto-fixer, which will silently keyword-only an ungranted subject — record the grant BEFORE running checks if the subject should stay positional.
-The full specification — the two exceptions, the carve-out list, the symmetric-tuple allowlist, the escape hatch, and worked examples — is in [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md).
+The full specification — the grant registry and rubric, the symmetric-tuple allowlist, the carve-out list, the escape hatch, and worked examples — is in [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md).
diff --git a/pipelex/kit/agent_rules/python_standards.md b/pipelex/kit/agent_rules/python_standards.md
index f506b811a..865349bb3 100644
--- a/pipelex/kit/agent_rules/python_standards.md
+++ b/pipelex/kit/agent_rules/python_standards.md
@@ -123,14 +123,18 @@ Once you've landed on a `BaseModel` (the default for anything that serializes),
## Keyword-only arguments
-Across `pipelex/` source, non-subject function parameters must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shape places a bare `*` after the subject:
+Across `pipelex/` source, non-subject function parameters must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shapes:
-- `def f(subject, *, opt1, opt2): ...` — the first non-`self`/`cls` parameter (the subject) may stay positional; everything after it must be keyword-only. Making the subject keyword-only too (`def f(*, a, b)`, `def m(self, *, a, b)`) is always allowed and is the form the auto-fixer produces.
-- A lone subject (`def render(node)`) is compliant; a second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is a violation.
+- `def f(*, opt1, opt2): ...` — fully keyword-only. Always compliant, needs nothing.
+- `def f(subject, *, opt1, opt2): ...` — a positional subject is legal ONLY under a **subject grant** recorded in `subject_grants.toml` at the repo root. A lone subject (`def render(node)`) needs a grant too. No grant → violation.
+- A second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is always a violation, grant or not.
+- A subject annotated `bool`/`int`/`float` (including `Optional[X]` / `X | None` forms) is **banned outright** — grants are impossible; call sites like `f(True)` are never acceptable. `str` subjects stay grantable.
-The rule is mechanically enforced by the `check-keyword-only` AST guard (`make cko`), which runs in `make agent-check`, in the `make check` aggregate, in CI, and via a Claude Code `PostToolUse` hook that checks each edited file at edit time. The tree is fully compliant, so it hard-blocks on **any** violation. Carve-outs — dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, `@override` impls, and a small curated symmetric-tuple allowlist — are skipped automatically. A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line).
+To keep a subject positional, record a grant with an honest, def-specific rationale: `make subject-grant FUNC="<relative_path>::<qualified_name>" RATIONALE="…"` (alias `make sgr`). The command validates the def, records the param automatically, and rewrites the registry sorted. A grant is warranted when the call reads as a verb–object sentence with a single obvious operand (`render(node)`, `validate_bundle(bundle)`) and call sites pass self-labelling expressions — when in doubt, go keyword-only instead. Grants are checked symmetrically: a grant whose def was renamed, moved, demoted, or deleted hard-fails the check until the registry is cleaned up (delete the entry or re-grant).
-**Auto-fix.** `make fix-keyword-only` (alias `fko`, or `pipelex-dev check-keyword-only --fix`) rewrites every mechanically-fixable violation by inserting a bare `*` as far left as possible — right after `self`/`cls` — so every non-`self`/`cls` parameter becomes keyword-only, and re-parses each rewrite before writing (a rewrite that would not parse is discarded and reported instead). It runs automatically early in `make agent-check`, before `ruff format`. It is **non-gating**: it mutates and reports but never exits non-zero — the read-only `check-keyword-only` (run last in `agent-check`, and the variant `make check` / CI use) owns the pass/fail gate. A few shapes a single `*` insert cannot fix are reported for a manual fix instead of rewritten: a `*args` is present, a keyword-only section already exists, or two-or-more positional-only params remain.
+The rule is mechanically enforced by the `check-keyword-only` AST guard (`make cko`), which runs in `make agent-check`, in the `make check` aggregate, in CI, and via a Claude Code `PostToolUse` hook that checks each edited file at edit time. The tree is fully compliant, so it hard-blocks on **any** violation, and each violation kind names its remedy in the output. Carve-outs — dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, `@override` impls, and a small curated symmetric-tuple allowlist — are skipped automatically (they neither need nor hold grants). A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line).
+
+**Auto-fix.** `make fix-keyword-only` (alias `fko`, or `pipelex-dev check-keyword-only --fix`) rewrites every mechanically-fixable violation by inserting a bare `*` as far left as possible — right after `self`/`cls` — so every non-`self`/`cls` parameter becomes keyword-only, and re-parses each rewrite before writing (a rewrite that would not parse is discarded and reported instead). Ungranted-subject and literal-subject defs are fixable this way too; a grant-param mismatch is never rewritten (that is a registry decision). It runs automatically early in `make agent-check`, before `ruff format`. It is **non-gating**: it mutates and reports but never exits non-zero — the read-only `check-keyword-only` (run last in `agent-check`, and the variant `make check` / CI use) owns the pass/fail gate. ⚠ Because an ungranted subject is a violation, `make agent-check` will silently keyword-only it — record the grant BEFORE running checks if the subject should stay positional. Shapes a single `*` insert cannot fix are reported for a manual fix: a `*args` is present, a keyword-only section already exists (move the `*` by hand — the common `def f(subject, *, opt)` case when the subject is ungranted or literal-typed), or two-or-more positional-only params remain.
Auto-fix is not a substitute for review: the guard is blind to functions a framework or the interpreter invokes positionally (callbacks, `__import__` hooks, route handlers, Jinja2 filters) — pyright/mypy will pass a wrongly-keywordized callback, so `make agent-test` is the safety net after a bulk fix.
diff --git a/pipelex/kit/cursor_rules.py b/pipelex/kit/cursor_rules.py
index 64682d063..72cf5d270 100644
--- a/pipelex/kit/cursor_rules.py
+++ b/pipelex/kit/cursor_rules.py
@@ -31,7 +31,7 @@ def _iter_agent_files(agents_dir: Traversable) -> Iterable[tuple[str, str]]:
yield child.name, child.read_text(encoding="utf-8")
-def _front_matter_for(name: str, *, kit_index: KitIndex) -> dict[str, Any]:
+def _front_matter_for(*, name: str, kit_index: KitIndex) -> dict[str, Any]:
"""Build front-matter for a specific file.
Args:
@@ -96,7 +96,7 @@ def update_cursor_rules(repo_root: Path, *, kit_index: KitIndex, agent_set: str)
for fname, body in _iter_agent_files(agents_dir):
if fname not in allowed_files:
continue
- fm = _front_matter_for(fname, kit_index=kit_index)
+ fm = _front_matter_for(name=fname, kit_index=kit_index)
yaml_block = "---\n" + yaml.safe_dump(fm, sort_keys=False).rstrip() + "\n---\n"
mdc = yaml_block + body
out_path = out_dir / (fname.removesuffix(".md") + ".mdc")
diff --git a/pipelex/libraries/concept/concept_library.py b/pipelex/libraries/concept/concept_library.py
index 3cfcc021f..fad45a0d4 100644
--- a/pipelex/libraries/concept/concept_library.py
+++ b/pipelex/libraries/concept/concept_library.py
@@ -95,7 +95,7 @@ class ConceptLibrary(RootModel[ConceptLibraryRoot], ConceptLibraryAbstract):
del self.root[concept_ref]
@override
- def is_compatible(self, tested_concept: Concept, *, wanted_concept: Concept, strict: bool = False) -> bool:
+ def is_compatible(self, *, tested_concept: Concept, wanted_concept: Concept, strict: bool = False) -> bool:
return Concept.are_concept_compatible(
concept_1=tested_concept,
concept_2=wanted_concept,
diff --git a/pipelex/libraries/concept/concept_library_abstract.py b/pipelex/libraries/concept/concept_library_abstract.py
index afb192f40..51d6a5f57 100644
--- a/pipelex/libraries/concept/concept_library_abstract.py
+++ b/pipelex/libraries/concept/concept_library_abstract.py
@@ -30,7 +30,7 @@ class ConceptLibraryAbstract(ABC):
pass
@abstractmethod
- def is_compatible(self, tested_concept: Concept, *, wanted_concept: Concept, strict: bool = False) -> bool:
+ def is_compatible(self, *, tested_concept: Concept, wanted_concept: Concept, strict: bool = False) -> bool:
pass
@abstractmethod
diff --git a/pipelex/libraries/crate_normalization.py b/pipelex/libraries/crate_normalization.py
index 0ee2e9e94..f00207434 100644
--- a/pipelex/libraries/crate_normalization.py
+++ b/pipelex/libraries/crate_normalization.py
@@ -304,15 +304,15 @@ def _collect_referenced_natives(*, concepts: dict[str, _ConceptEntry], pipes: di
if not isinstance(value, ConceptBlueprint):
continue
if value.refines:
- _add_native_ref(referenced, concept_ref_or_code=value.refines)
+ _add_native_ref(referenced=referenced, concept_ref_or_code=value.refines)
if isinstance(value.structure, dict):
for field in value.structure.values():
if isinstance(field, ConceptStructureBlueprint):
- _add_native_ref(referenced, concept_ref_or_code=field.concept_ref)
- _add_native_ref(referenced, concept_ref_or_code=field.item_concept_ref)
+ _add_native_ref(referenced=referenced, concept_ref_or_code=field.concept_ref)
+ _add_native_ref(referenced=referenced, concept_ref_or_code=field.item_concept_ref)
for blueprint in pipes.values():
for io_ref in [*(blueprint.inputs or {}).values(), blueprint.output]:
- _add_native_ref(referenced, concept_ref_or_code=_io_ref_concept(io_ref))
+ _add_native_ref(referenced=referenced, concept_ref_or_code=_io_ref_concept(io_ref))
return referenced
@@ -322,6 +322,6 @@ def _io_ref_concept(io_ref: str) -> str | None:
return parse_concept_with_multiplicity(io_ref).concept_ref_or_code
-def _add_native_ref(referenced: set[str], *, concept_ref_or_code: str | None) -> None:
+def _add_native_ref(*, referenced: set[str], concept_ref_or_code: str | None) -> None:
if concept_ref_or_code and NativeConceptCode.is_native_concept_ref_or_code(concept_ref_or_code=concept_ref_or_code):
referenced.add(NativeConceptCode.get_validated_native_concept_ref(concept_ref_or_code=concept_ref_or_code))
diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.py
index 7bf17e78c..8500327c0 100644
--- a/pipelex/libraries/library_manager.py
+++ b/pipelex/libraries/library_manager.py
@@ -276,8 +276,8 @@ class LibraryManager(LibraryManagerAbstract):
@override
def load_libraries(
self,
- library_id: str,
*,
+ library_id: str,
library_dirs: list[Path] | None = None,
library_file_paths: list[Path] | None = None,
) -> list[PipeAbstract]:
@@ -337,7 +337,7 @@ class LibraryManager(LibraryManagerAbstract):
return self._load_mthds_files_into_library(library_id=library_id, valid_mthds_paths=valid_mthds_paths)
@override
- def load_from_crate(self, library_id: str, *, crate: LibraryCrate) -> list[PipeAbstract]:
+ def load_from_crate(self, *, library_id: str, crate: LibraryCrate) -> list[PipeAbstract]:
"""Load a LibraryCrate into a live Library.
Fingerprint idempotency: if a crate with the same fingerprint was already loaded
@@ -431,7 +431,7 @@ class LibraryManager(LibraryManagerAbstract):
return all_pipes
@override
- def load_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> list[PipeAbstract]:
+ def load_from_blueprints(self, *, library_id: str, blueprints: list[PipelexBundleBlueprint]) -> list[PipeAbstract]:
"""Load domains, concepts, and pipes from a list of blueprints.
Delegates through LibraryCrate: builds a crate from blueprints, then loads from the crate.
@@ -621,7 +621,7 @@ class LibraryManager(LibraryManagerAbstract):
# Private helper methods
############################################################
- def _load_mthds_files_into_library(self, library_id: str, *, valid_mthds_paths: list[Path]) -> list[PipeAbstract]:
+ def _load_mthds_files_into_library(self, *, library_id: str, valid_mthds_paths: list[Path]) -> list[PipeAbstract]:
"""Load MTHDS files into a specific library.
This method:
@@ -804,8 +804,8 @@ class LibraryManager(LibraryManagerAbstract):
def _load_dependency_packages(
self,
- library_id: str,
*,
+ library_id: str,
manifest: MethodsManifest,
package_root: Path,
) -> None:
@@ -1001,8 +1001,8 @@ class LibraryManager(LibraryManagerAbstract):
def _load_address_based_dependencies(
self,
- library_id: str,
*,
+ library_id: str,
blueprints: list[PipelexBundleBlueprint],
) -> None:
"""Scan blueprints for cross-package pipe refs with address-based aliases and load them.
@@ -1112,12 +1112,12 @@ class LibraryManager(LibraryManagerAbstract):
library.concept_library.remove_concepts_by_concept_refs(concept_refs=concept_codes_to_remove)
@override
- def _remove_from_blueprint(self, library_id: str, *, blueprint: PipelexBundleBlueprint) -> None:
+ def _remove_from_blueprint(self, *, library_id: str, blueprint: PipelexBundleBlueprint) -> None:
self._remove_pipes_from_blueprint(blueprint=blueprint)
self._remove_concepts_from_blueprint(blueprint=blueprint)
@override
- def _remove_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> None:
+ def _remove_from_blueprints(self, *, library_id: str, blueprints: list[PipelexBundleBlueprint]) -> None:
for blueprint in blueprints:
self._remove_from_blueprint(library_id=library_id, blueprint=blueprint)
diff --git a/pipelex/libraries/library_manager_abstract.py b/pipelex/libraries/library_manager_abstract.py
index 866477907..bf9b8171f 100644
--- a/pipelex/libraries/library_manager_abstract.py
+++ b/pipelex/libraries/library_manager_abstract.py
@@ -81,7 +81,7 @@ class LibraryManagerAbstract(ABC):
"""
@abstractmethod
- def load_from_crate(self, library_id: str, *, crate: LibraryCrate) -> list[PipeAbstract]:
+ def load_from_crate(self, *, library_id: str, crate: LibraryCrate) -> list[PipeAbstract]:
"""Load a LibraryCrate into a live Library.
Note: This method does NOT resolve cross-package address-based dependencies.
@@ -93,22 +93,22 @@ class LibraryManagerAbstract(ABC):
"""
@abstractmethod
- def load_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> list[PipeAbstract]:
+ def load_from_blueprints(self, *, library_id: str, blueprints: list[PipelexBundleBlueprint]) -> list[PipeAbstract]:
pass
@abstractmethod
- def _remove_from_blueprint(self, library_id: str, *, blueprint: PipelexBundleBlueprint) -> None:
+ def _remove_from_blueprint(self, *, library_id: str, blueprint: PipelexBundleBlueprint) -> None:
pass
@abstractmethod
- def _remove_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> None:
+ def _remove_from_blueprints(self, *, library_id: str, blueprints: list[PipelexBundleBlueprint]) -> None:
pass
@abstractmethod
def load_libraries(
self,
- library_id: str,
*,
+ library_id: str,
library_dirs: list[Path] | None = None,
library_file_paths: list[Path] | None = None,
) -> list[PipeAbstract]:
diff --git a/pipelex/pipe_controllers/absence_taint.py b/pipelex/pipe_controllers/absence_taint.py
index c658276a5..1ee8552cd 100644
--- a/pipelex/pipe_controllers/absence_taint.py
+++ b/pipelex/pipe_controllers/absence_taint.py
@@ -111,7 +111,7 @@ def scan_taint_triggers(pipe: PipeAbstract, *, slot_taints: dict[str, SlotTaint]
redundant_force_names: list[str] = []
for named_stuff_spec in pipe.needed_inputs().named_stuff_specs:
incoming_taint = slot_taints.get(named_stuff_spec.variable_name)
- match effective_consumption_presence(pipe, named_stuff_spec=named_stuff_spec):
+ match effective_consumption_presence(pipe=pipe, named_stuff_spec=named_stuff_spec):
case PresenceMarker.PLAIN:
if incoming_taint is not None:
trigger_names.append(named_stuff_spec.variable_name)
@@ -144,7 +144,7 @@ def is_plural_step_result(
return has_batch_params or step_output_multiplicity is not None or pipe.output.multiplicity is not None
-def effective_consumption_presence(pipe: PipeAbstract, *, named_stuff_spec: NamedStuffSpec) -> PresenceMarker:
+def effective_consumption_presence(*, pipe: PipeAbstract, named_stuff_spec: NamedStuffSpec) -> PresenceMarker:
"""The presence marker governing how `pipe` consumes the given needed input.
The pipe's OWN input declaration wins when it exists — that is the boundary contract
diff --git a/pipelex/pipe_controllers/batch/pipe_batch.py b/pipelex/pipe_controllers/batch/pipe_batch.py
index 029df2bf5..42f3b224c 100644
--- a/pipelex/pipe_controllers/batch/pipe_batch.py
+++ b/pipelex/pipe_controllers/batch/pipe_batch.py
@@ -66,7 +66,7 @@ class PipeBatch(PipeController):
return required_variables
@override
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
return self.inputs
@override
@@ -95,7 +95,7 @@ class PipeBatch(PipeController):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
) -> None:
batch_params = pipe_run_params.batch_params or self.batch_params or BatchParams.make_default()
input_list_stuff_name = batch_params.input_list_stuff_name
@@ -256,7 +256,7 @@ class PipeBatch(PipeController):
"item_count": len(input_content.items),
"branch_pipe_code": self.branch_pipe_code,
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeOutput(
working_memory=working_memory,
@@ -293,6 +293,6 @@ class PipeBatch(PipeController):
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_controllers/batch/pipe_batch_factory.py b/pipelex/pipe_controllers/batch/pipe_batch_factory.py
index 5c3ae1ed6..ef987b5c6 100644
--- a/pipelex/pipe_controllers/batch/pipe_batch_factory.py
+++ b/pipelex/pipe_controllers/batch/pipe_batch_factory.py
@@ -15,8 +15,8 @@ class PipeBatchFactory(PipeFactoryProtocol[PipeBatchBlueprint, PipeBatch]):
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_controllers/condition/pipe_condition.py b/pipelex/pipe_controllers/condition/pipe_condition.py
index f6cee19c4..c79f30f39 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition.py
@@ -63,7 +63,7 @@ class PipeCondition(PipeController):
return {var for var in required_variables if not var.startswith("_")}
@override
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
if visited_pipes is None:
visited_pipes = set()
@@ -97,7 +97,7 @@ class PipeCondition(PipeController):
for pipe_code in self.pipe_dependencies():
pipe = get_required_pipe(pipe_code=pipe_code)
# Use the centralized recursion detection
- pipe_needed_inputs = pipe.needed_inputs(visited_pipes_with_current)
+ pipe_needed_inputs = pipe.needed_inputs(visited_pipes=visited_pipes_with_current)
for input_name, stuff_spec in pipe_needed_inputs.items:
needed_inputs.add_stuff_spec(
@@ -228,7 +228,7 @@ class PipeCondition(PipeController):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
evaluated_expression = await render_template(
template=self.expression,
@@ -245,12 +245,13 @@ class PipeCondition(PipeController):
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
async def _evaluate_expression(
self,
+ *,
working_memory: WorkingMemory,
) -> str:
"""Evaluate the conditional expression and select the appropriate pipe.
@@ -302,7 +303,7 @@ class PipeCondition(PipeController):
# downstream); it no longer passes through as this pipe's output.
if SpecialOutcome.is_continue(outcome):
log.dev(f"PipeCondition '{self.code}' continued with outcome: {outcome}. Evaluated expression: {evaluated_expression}")
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
self._record_declared_absent_output(
working_memory=working_memory,
output_name=output_name,
@@ -311,7 +312,7 @@ class PipeCondition(PipeController):
return PipeOutput(working_memory=working_memory, pipeline_run_id=job_metadata.pipeline_run_id)
if SpecialOutcome.is_fail(outcome):
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
msg = f"PipeCondition '{self.code}' failed with outcome: {outcome}. Evaluated expression: {evaluated_expression}"
raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)
@@ -349,7 +350,7 @@ class PipeCondition(PipeController):
library_crate=library_crate,
),
)
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return pipe_output
@override
@@ -407,7 +408,7 @@ class PipeCondition(PipeController):
"evaluated_expression": "dry_run",
"selected_outcome": "all_outcomes",
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
# Dry-run parity with the live `continue` arm: with only special outcomes mapped, no pipe
# dry-ran into this memory. When `continue` is reachable the declared output resolves
# absent, memory otherwise unchanged (the static rule "continue-reachable ⇒ `?` output" is
diff --git a/pipelex/pipe_controllers/condition/pipe_condition_factory.py b/pipelex/pipe_controllers/condition/pipe_condition_factory.py
index 5f20693e6..13ca7420a 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition_factory.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition_factory.py
@@ -15,8 +15,8 @@ class PipeConditionFactory(PipeFactoryProtocol[PipeConditionBlueprint, PipeCondi
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_controllers/parallel/pipe_parallel.py b/pipelex/pipe_controllers/parallel/pipe_parallel.py
index cd18522c7..319ae18c5 100644
--- a/pipelex/pipe_controllers/parallel/pipe_parallel.py
+++ b/pipelex/pipe_controllers/parallel/pipe_parallel.py
@@ -74,7 +74,7 @@ class PipeParallel(PipeController):
return set()
@override
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
if visited_pipes is None:
visited_pipes = set()
@@ -90,7 +90,7 @@ class PipeParallel(PipeController):
for sub_pipe in self.parallel_sub_pipes:
pipe = get_required_pipe(pipe_code=sub_pipe.pipe_code)
# Use the centralized recursion detection
- pipe_needed_inputs = pipe.needed_inputs(visited_pipes_with_current)
+ pipe_needed_inputs = pipe.needed_inputs(visited_pipes=visited_pipes_with_current)
if sub_pipe.batch_params:
try:
stuff_spec = pipe_needed_inputs.get_required_stuff_spec(variable_name=sub_pipe.batch_params.input_item_stuff_name)
@@ -109,12 +109,12 @@ class PipeParallel(PipeController):
for input_name, stuff_spec in pipe_needed_inputs.items:
if input_name != sub_pipe.batch_params.input_item_stuff_name:
needed_inputs.add_stuff_spec(
- input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity, presence=stuff_spec.presence
+ variable_name=input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity, presence=stuff_spec.presence
)
else:
for input_name, stuff_spec in pipe_needed_inputs.items:
needed_inputs.add_stuff_spec(
- input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity, presence=stuff_spec.presence
+ variable_name=input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity, presence=stuff_spec.presence
)
return needed_inputs
@@ -545,7 +545,7 @@ class PipeParallel(PipeController):
"add_each_output": self.add_each_output,
"combined_output_concept": self.output.concept.concept_ref,
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeOutput(
working_memory=working_memory,
@@ -672,12 +672,12 @@ class PipeParallel(PipeController):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py b/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py
index afe5b2290..84def2e47 100644
--- a/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py
+++ b/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py
@@ -19,8 +19,8 @@ class PipeParallelFactory(PipeFactoryProtocol[PipeParallelBlueprint, PipeParalle
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_controllers/pipe_controller.py b/pipelex/pipe_controllers/pipe_controller.py
index 04f4a6606..40dcc20b3 100644
--- a/pipelex/pipe_controllers/pipe_controller.py
+++ b/pipelex/pipe_controllers/pipe_controller.py
@@ -33,8 +33,8 @@ class PipeController(PipeAbstract):
@override
async def _live_run_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -52,8 +52,8 @@ class PipeController(PipeAbstract):
@override
async def _dry_run_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence.py b/pipelex/pipe_controllers/sequence/pipe_sequence.py
index 5ad92a6e0..056772726 100644
--- a/pipelex/pipe_controllers/sequence/pipe_sequence.py
+++ b/pipelex/pipe_controllers/sequence/pipe_sequence.py
@@ -281,7 +281,7 @@ class PipeSequence(PipeController):
)
@override
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
if visited_pipes is None:
visited_pipes = set()
@@ -304,7 +304,7 @@ class PipeSequence(PipeController):
else:
sub_pipe = get_required_pipe(pipe_code=sequential_sub_pipe.pipe_code)
# Use the centralized recursion detection
- sub_pipe_needed_inputs = sub_pipe.needed_inputs(visited_pipes_with_current)
+ sub_pipe_needed_inputs = sub_pipe.needed_inputs(visited_pipes=visited_pipes_with_current)
if isinstance(sub_pipe, PipeParallel) and sub_pipe.add_each_output:
for sub_parallel_pipe in sub_pipe.parallel_sub_pipes:
@@ -333,13 +333,16 @@ class PipeSequence(PipeController):
for input_name, stuff_spec in sub_pipe_needed_inputs.items:
if input_name != sequential_sub_pipe.batch_params.input_item_stuff_name and input_name not in generated_outputs:
needed_inputs.add_stuff_spec(
- input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity, presence=stuff_spec.presence
+ variable_name=input_name,
+ concept=stuff_spec.concept,
+ multiplicity=stuff_spec.multiplicity,
+ presence=stuff_spec.presence,
)
else:
for input_name, stuff_spec in sub_pipe_needed_inputs.items:
if input_name not in generated_outputs:
needed_inputs.add_stuff_spec(
- input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity, presence=stuff_spec.presence
+ variable_name=input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity, presence=stuff_spec.presence
)
# Add this step's output to generated outputs
@@ -382,7 +385,7 @@ class PipeSequence(PipeController):
execution_data_dict: dict[str, Any] = {
"step_count": len(self.sequential_sub_pipes),
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeOutput(
working_memory=evolving_memory,
@@ -409,12 +412,12 @@ class PipeSequence(PipeController):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py b/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py
index d9f8601f5..3f452770d 100644
--- a/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py
+++ b/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py
@@ -18,8 +18,8 @@ class PipeSequenceFactory(PipeFactoryProtocol[PipeSequenceBlueprint, PipeSequenc
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_operators/compose/pipe_compose.py b/pipelex/pipe_operators/compose/pipe_compose.py
index ec2d5f565..654a21c08 100644
--- a/pipelex/pipe_operators/compose/pipe_compose.py
+++ b/pipelex/pipe_operators/compose/pipe_compose.py
@@ -91,7 +91,7 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
@override
# TODO: this needs testing!!!
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
needed_inputs = InputStuffSpecsFactory.make_empty()
for input_name, stuff_spec in self.inputs.root.items():
needed_inputs.add_stuff_spec(
@@ -157,8 +157,8 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
@override
async def _live_run_operator_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -180,8 +180,8 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
async def _run_template_mode(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None,
@@ -230,7 +230,7 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
"compose_mode": "template",
"rendered_text": rendered_template_text,
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeComposeOutput(
working_memory=working_memory,
@@ -239,8 +239,8 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
async def _run_construct_mode(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None,
@@ -283,7 +283,7 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
"compose_mode": "construct",
"fields": composer.field_resolutions,
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeComposeOutput(
working_memory=working_memory,
@@ -293,8 +293,8 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
@override
async def _dry_run_operator_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -333,8 +333,8 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
def _make_mock_construct_output(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
output_name: str | None,
) -> PipeComposeOutput:
@@ -354,12 +354,12 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/compose/pipe_compose_factory.py b/pipelex/pipe_operators/compose/pipe_compose_factory.py
index f3ff4dec2..c16b8837a 100644
--- a/pipelex/pipe_operators/compose/pipe_compose_factory.py
+++ b/pipelex/pipe_operators/compose/pipe_compose_factory.py
@@ -19,8 +19,8 @@ class PipeComposeFactory(PipeFactoryProtocol[PipeComposeBlueprint, PipeCompose])
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
@@ -51,8 +51,8 @@ class PipeComposeFactory(PipeFactoryProtocol[PipeComposeBlueprint, PipeCompose])
@classmethod
def _make_template_mode(
cls,
- pipe_code: str,
*,
+ pipe_code: str,
domain_code: str,
description: str,
inputs: InputStuffSpecs,
diff --git a/pipelex/pipe_operators/extract/pipe_extract.py b/pipelex/pipe_operators/extract/pipe_extract.py
index 55615184e..d0d0abd20 100644
--- a/pipelex/pipe_operators/extract/pipe_extract.py
+++ b/pipelex/pipe_operators/extract/pipe_extract.py
@@ -47,7 +47,7 @@ class PipeExtract(PipeOperator[PipeExtractOutput]):
document_stuff_name: str | None = None
@override
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
return self.inputs
@override
@@ -117,8 +117,8 @@ class PipeExtract(PipeOperator[PipeExtractOutput]):
@override
async def _live_run_operator_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -183,7 +183,7 @@ class PipeExtract(PipeOperator[PipeExtractOutput]):
"should_include_page_views": self.should_include_page_views,
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeExtractOutput(
working_memory=working_memory,
pipeline_run_id=job_metadata.pipeline_run_id,
@@ -191,12 +191,12 @@ class PipeExtract(PipeOperator[PipeExtractOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/extract/pipe_extract_factory.py b/pipelex/pipe_operators/extract/pipe_extract_factory.py
index 937008250..0ba25a202 100644
--- a/pipelex/pipe_operators/extract/pipe_extract_factory.py
+++ b/pipelex/pipe_operators/extract/pipe_extract_factory.py
@@ -17,8 +17,8 @@ class PipeExtractFactory(PipeFactoryProtocol[PipeExtractBlueprint, PipeExtract])
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_operators/func/pipe_func.py b/pipelex/pipe_operators/func/pipe_func.py
index e8c3144dc..17d1f31b1 100644
--- a/pipelex/pipe_operators/func/pipe_func.py
+++ b/pipelex/pipe_operators/func/pipe_func.py
@@ -37,7 +37,7 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
return set()
@override
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
return self.inputs
@field_validator("function_name", mode="before")
@@ -174,8 +174,8 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
@override
async def _live_run_operator_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -243,7 +243,7 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
"function_qualname": getattr(function, "__qualname__", self.function_name),
"output_content_type": type(the_content).__name__,
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeFuncOutput(
working_memory=working_memory,
@@ -253,8 +253,8 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
@override
async def _dry_run_operator_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -304,7 +304,7 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
"output_content_type": type(mock_content).__name__,
"is_mock_output": True,
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeFuncOutput(
working_memory=working_memory,
@@ -313,7 +313,7 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
function = func_registry.get_required_function(self.function_name)
return_type = get_type_hints(function).get("return")
@@ -331,6 +331,6 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/func/pipe_func_factory.py b/pipelex/pipe_operators/func/pipe_func_factory.py
index 1ad0a5b37..506ced7d2 100644
--- a/pipelex/pipe_operators/func/pipe_func_factory.py
+++ b/pipelex/pipe_operators/func/pipe_func_factory.py
@@ -14,8 +14,8 @@ class PipeFuncFactory(PipeFactoryProtocol[PipeFuncBlueprint, PipeFunc]):
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen.py b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
index 18255eb87..3a4d96af6 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
@@ -36,7 +36,7 @@ if TYPE_CHECKING:
from pipelex.core.stuffs.stuff_content import StuffContent
-def resolve_default_size(explicit_aspect_ratio: AspectRatio | None, *, default_size: ImgGenSize | None) -> ImgGenSize | None:
+def resolve_default_size(*, explicit_aspect_ratio: AspectRatio | None, default_size: ImgGenSize | None) -> ImgGenSize | None:
"""Resolve the config-level size default applicable to a pipe, honoring exact-size/aspect-ratio exclusivity.
An exact size implies its own aspect ratio (the blueprint forbids setting both on a pipe), so an
@@ -67,7 +67,7 @@ class PipeImgGen(PipeOperator[PipeImgGenOutput]):
output_multiplicity: VariableMultiplicity
@override
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
"""Needed inputs are the inputs needed to run the pipe, specified in the inputs attribute of the pipe"""
return self.inputs
@@ -168,8 +168,8 @@ class PipeImgGen(PipeOperator[PipeImgGenOutput]):
@override
async def _live_run_operator_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -229,7 +229,7 @@ class PipeImgGen(PipeOperator[PipeImgGenOutput]):
# Build ImgGenJobParams from ImgGenSetting + one-time settings
img_gen_job_params = ImgGenJobParams(
aspect_ratio=self.aspect_ratio or img_gen_param_defaults.aspect_ratio,
- size=self.size or resolve_default_size(self.aspect_ratio, default_size=img_gen_param_defaults.size),
+ size=self.size or resolve_default_size(explicit_aspect_ratio=self.aspect_ratio, default_size=img_gen_param_defaults.size),
background=self.background or img_gen_param_defaults.background,
quality=img_gen_setting.quality,
nb_steps=img_gen_setting.nb_steps,
@@ -315,7 +315,7 @@ class PipeImgGen(PipeOperator[PipeImgGenOutput]):
"nb_images": nb_images,
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeImgGenOutput(
working_memory=working_memory,
pipeline_run_id=job_metadata.pipeline_run_id,
@@ -323,12 +323,12 @@ class PipeImgGen(PipeOperator[PipeImgGenOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py b/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
index 0c78f54e0..8466998d6 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
@@ -22,8 +22,8 @@ class PipeImgGenFactory(PipeFactoryProtocol[PipeImgGenBlueprint, PipeImgGen]):
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_operators/llm/llm_prompt_blueprint.py b/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
index 483265f46..a2be1913b 100644
--- a/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
+++ b/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
@@ -60,8 +60,8 @@ class LLMPromptBlueprint(BaseModel):
# let's get back to it when we have a better solution for structuring_method
async def make_llm_prompt(
self,
- output_concept_ref: str,
*,
+ output_concept_ref: str,
context_provider: ContextProviderAbstract,
output_structure_prompt: str | None = None,
extra_params: dict[str, Any] | None = None,
diff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.py
index b56cf4363..e65604d20 100644
--- a/pipelex/pipe_operators/llm/pipe_llm.py
+++ b/pipelex/pipe_operators/llm/pipe_llm.py
@@ -143,7 +143,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
)
@override
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
needed_inputs = InputStuffSpecsFactory.make_empty()
for input_name, stuff_spec in self.inputs.items:
@@ -186,8 +186,8 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
@override
async def _live_run_operator_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -340,7 +340,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
)
execution_data_dict["structuring_path"] = "text" if output_is_text else "object_direct"
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeLLMOutput(
working_memory=working_memory,
pipeline_run_id=job_metadata.pipeline_run_id,
@@ -348,8 +348,8 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
async def _llm_gen_object_stuff_content(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
pipe_run_params: PipeRunParams,
is_multiple_output: bool,
fixed_nb_output: int | None,
@@ -413,12 +413,12 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/llm/pipe_llm_factory.py b/pipelex/pipe_operators/llm/pipe_llm_factory.py
index 6863e2006..df413c9c9 100644
--- a/pipelex/pipe_operators/llm/pipe_llm_factory.py
+++ b/pipelex/pipe_operators/llm/pipe_llm_factory.py
@@ -25,8 +25,8 @@ class PipeLLMFactory(PipeFactoryProtocol[PipeLLMBlueprint, PipeLLM]):
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_operators/pipe_operator.py b/pipelex/pipe_operators/pipe_operator.py
index aa6b14b2a..29c7f75e3 100644
--- a/pipelex/pipe_operators/pipe_operator.py
+++ b/pipelex/pipe_operators/pipe_operator.py
@@ -30,8 +30,8 @@ class PipeOperator(PipeAbstract, Generic[PipeOperatorOutputType]):
@override
async def _live_run_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -86,8 +86,8 @@ class PipeOperator(PipeAbstract, Generic[PipeOperatorOutputType]):
@override
async def _dry_run_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -100,8 +100,8 @@ class PipeOperator(PipeAbstract, Generic[PipeOperatorOutputType]):
@abstractmethod
async def _live_run_operator_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -110,8 +110,8 @@ class PipeOperator(PipeAbstract, Generic[PipeOperatorOutputType]):
async def _dry_run_operator_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
diff --git a/pipelex/pipe_operators/search/pipe_search.py b/pipelex/pipe_operators/search/pipe_search.py
index add5bf72e..586d65b7e 100644
--- a/pipelex/pipe_operators/search/pipe_search.py
+++ b/pipelex/pipe_operators/search/pipe_search.py
@@ -42,7 +42,7 @@ class PipeSearch(PipeOperator[PipeSearchOutput]):
is_structured_output: bool
@override
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
return self.inputs
@override
@@ -84,8 +84,8 @@ class PipeSearch(PipeOperator[PipeSearchOutput]):
@override
async def _live_run_operator_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -163,7 +163,7 @@ class PipeSearch(PipeOperator[PipeSearchOutput]):
"is_structured_output": self.is_structured_output,
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeSearchOutput(
working_memory=working_memory,
pipeline_run_id=job_metadata.pipeline_run_id,
@@ -171,12 +171,12 @@ class PipeSearch(PipeOperator[PipeSearchOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/search/pipe_search_factory.py b/pipelex/pipe_operators/search/pipe_search_factory.py
index dcca1141e..b0b168d10 100644
--- a/pipelex/pipe_operators/search/pipe_search_factory.py
+++ b/pipelex/pipe_operators/search/pipe_search_factory.py
@@ -18,8 +18,8 @@ class PipeSearchFactory(PipeFactoryProtocol[PipeSearchBlueprint, PipeSearch]):
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_operators/structure/pipe_structure.py b/pipelex/pipe_operators/structure/pipe_structure.py
index d054ffff7..5a9ce8f3c 100644
--- a/pipelex/pipe_operators/structure/pipe_structure.py
+++ b/pipelex/pipe_operators/structure/pipe_structure.py
@@ -45,7 +45,7 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
output_multiplicity: VariableMultiplicity | None = None
@override
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
needed_inputs = InputStuffSpecsFactory.make_empty()
for input_name, stuff_spec in self.inputs.items:
needed_inputs.add_stuff_spec(
@@ -103,8 +103,8 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
@override
async def _live_run_operator_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -196,7 +196,7 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
"rendered_user_prompt": rendered_user_prompt,
"structuring_path": "structure",
}
- self._register_execution_data(job_metadata, execution_data=execution_data_dict)
+ self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeStructureOutput(
working_memory=working_memory,
@@ -208,12 +208,12 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/structure/pipe_structure_factory.py b/pipelex/pipe_operators/structure/pipe_structure_factory.py
index 2d74fb6a9..a33890d5e 100644
--- a/pipelex/pipe_operators/structure/pipe_structure_factory.py
+++ b/pipelex/pipe_operators/structure/pipe_structure_factory.py
@@ -15,8 +15,8 @@ class PipeStructureFactory(PipeFactoryProtocol[PipeStructureBlueprint, PipeStruc
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_run/delivery_executor.py b/pipelex/pipe_run/delivery_executor.py
index e35e19a5d..20173627b 100644
--- a/pipelex/pipe_run/delivery_executor.py
+++ b/pipelex/pipe_run/delivery_executor.py
@@ -106,9 +106,9 @@ class DeliveryExecutor:
data=clean_json_dumps(pipe_output.working_memory_raw, indent=2).encode("utf-8"),
content_type="application/json",
)
- raw_main_stuff = self._get_raw_main_stuff_dict(pipe_output.working_memory_raw)
+ raw_main_stuff = self._get_raw_main_stuff_dict(working_memory_raw=pipe_output.working_memory_raw)
if raw_main_stuff is None:
- main_absence = self._get_raw_main_absence(pipe_output.working_memory_raw)
+ main_absence = self._get_raw_main_absence(working_memory_raw=pipe_output.working_memory_raw)
if main_absence is None:
msg = (
"Delivery of a completed run found neither a main stuff nor a recorded absence in the raw "
@@ -140,7 +140,7 @@ class DeliveryExecutor:
return files
@classmethod
- def _get_raw_main_stuff_dict(cls, working_memory_raw: dict[str, Any]) -> dict[str, Any] | None:
+ def _get_raw_main_stuff_dict(cls, *, working_memory_raw: dict[str, Any]) -> dict[str, Any] | None:
"""Extract the main stuff dict from a raw working_memory, following aliases."""
root: dict[str, Any] = working_memory_raw.get("root", {})
aliases: dict[str, str] = working_memory_raw.get("aliases", {})
@@ -151,7 +151,7 @@ class DeliveryExecutor:
return None
@classmethod
- def _get_raw_main_absence(cls, working_memory_raw: dict[str, Any]) -> AbsenceRecord | None:
+ def _get_raw_main_absence(cls, *, working_memory_raw: dict[str, Any]) -> AbsenceRecord | None:
"""Extract the recorded main-output absence from a raw working_memory's ledger, if any.
A malformed record is treated as missing (the caller then fails the delivery loudly as a
diff --git a/pipelex/pipe_run/dry_run_in_process.py b/pipelex/pipe_run/dry_run_in_process.py
index 34e42ff98..a1b5d68e0 100644
--- a/pipelex/pipe_run/dry_run_in_process.py
+++ b/pipelex/pipe_run/dry_run_in_process.py
@@ -30,7 +30,7 @@ from pipelex.system.telemetry.otel_constants import OTelConstants
from pipelex.tracing.in_memory_event_log import InMemoryEventLog
-async def best_effort_graph_spec(pipe_ref: str | None, *, library_id: str | None, log_context: str) -> GraphSpec | None:
+async def best_effort_graph_spec(*, pipe_ref: str | None, library_id: str | None, log_context: str) -> GraphSpec | None:
"""Best-effort graph arm of the validate surfaces: dry-run ``pipe_ref`` for its graph, or degrade to None.
The ONE implementation of the validate graph-arm contract, shared by every backend
diff --git a/pipelex/pipe_run/pipe_run_params.py b/pipelex/pipe_run/pipe_run_params.py
index e48d046b5..1682ad8af 100644
--- a/pipelex/pipe_run/pipe_run_params.py
+++ b/pipelex/pipe_run/pipe_run_params.py
@@ -120,8 +120,8 @@ class BatchParams(BaseModel):
@classmethod
def make_batch_params(
cls,
- input_list_name: str,
*,
+ input_list_name: str,
input_item_name: str,
) -> BatchParams:
return BatchParams(
diff --git a/pipelex/pipe_signature/pipe_signature.py b/pipelex/pipe_signature/pipe_signature.py
index ad84cc1ba..bf54d2ca0 100644
--- a/pipelex/pipe_signature/pipe_signature.py
+++ b/pipelex/pipe_signature/pipe_signature.py
@@ -52,7 +52,7 @@ class PipeSignature(PipeAbstract):
pass
@override
- def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
+ def needed_inputs(self, *, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
return self.inputs
@override
@@ -62,8 +62,8 @@ class PipeSignature(PipeAbstract):
@override
async def _validate_before_run(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -73,8 +73,8 @@ class PipeSignature(PipeAbstract):
@override
async def _validate_after_run(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -84,8 +84,8 @@ class PipeSignature(PipeAbstract):
@override
async def _live_run_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -96,8 +96,8 @@ class PipeSignature(PipeAbstract):
@override
async def _dry_run_pipe(
self,
- job_metadata: JobMetadata,
*,
+ job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
diff --git a/pipelex/pipe_signature/pipe_signature_factory.py b/pipelex/pipe_signature/pipe_signature_factory.py
index 9a1b8f5ad..d992e28af 100644
--- a/pipelex/pipe_signature/pipe_signature_factory.py
+++ b/pipelex/pipe_signature/pipe_signature_factory.py
@@ -14,8 +14,8 @@ class PipeSignatureFactory(PipeFactoryProtocol[PipeSignatureBlueprint, PipeSigna
@override
def make(
cls,
- pipe_category: Any,
*,
+ pipe_category: Any,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipelex.py b/pipelex/pipelex.py
index 6c00ae4a9..93283c1cc 100644
--- a/pipelex/pipelex.py
+++ b/pipelex/pipelex.py
@@ -149,7 +149,7 @@ class Pipelex(metaclass=MetaSingleton):
log.verbose(f"{PACKAGE_NAME} version {PACKAGE_VERSION} init done")
@staticmethod
- def _get_config_file_not_found_error_msg(component_name: str) -> str:
+ def _get_config_file_not_found_error_msg(*, component_name: str) -> str:
"""Generate error message for missing config files."""
return f"Config files are missing for the {component_name}. Run `pipelex init config` to generate the missing files."
@@ -376,13 +376,13 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
needs_inference=needs_inference,
)
except RoutingProfileLibraryNotFoundError as routing_not_found_exc:
- msg = self._get_config_file_not_found_error_msg("routing profile library")
+ msg = self._get_config_file_not_found_error_msg(component_name="routing profile library")
raise PipelexSetupError(msg) from routing_not_found_exc
except InferenceBackendLibraryNotFoundError as backend_not_found_exc:
- msg = self._get_config_file_not_found_error_msg("inference backend library")
+ msg = self._get_config_file_not_found_error_msg(component_name="inference backend library")
raise PipelexSetupError(msg) from backend_not_found_exc
except ModelDeckNotFoundError as deck_not_found_exc:
- msg = self._get_config_file_not_found_error_msg("model deck")
+ msg = self._get_config_file_not_found_error_msg(component_name="model deck")
raise PipelexSetupError(msg) from deck_not_found_exc
except RoutingProfileDisabledBackendError as routing_profile_exc:
msg = f"Some backend(s) required for a routing profile is not enabled: {routing_profile_exc}"
@@ -431,7 +431,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
storage_provider = storage_provider_registry.get_required(method=storage_config.method)(storage_config)
self.pipelex_hub.set_storage_provider(storage_provider)
- self.pipelex_hub.set_dry_run_forced(not needs_inference)
+ self.pipelex_hub.set_dry_run_forced(is_forced=not needs_inference)
# Injection precedence (codex C8): explicit setup() param > plugin slot-claim thunk > core default.
# A boot-orchestrator plugin (Temporal worker) claims the CONTENT_GENERATOR slot; its thunk runs
# only here, never at register, so booting a non-worker process imports no host-runtime SDK.
diff --git a/pipelex/pipeline/fixes/applier.py b/pipelex/pipeline/fixes/applier.py
index 8ac72687e..5ba23f14f 100644
--- a/pipelex/pipeline/fixes/applier.py
+++ b/pipelex/pipeline/fixes/applier.py
@@ -63,7 +63,7 @@ class FixOpApplication(BaseModel):
detail: str | None = None
-def _resolve_table(toml_doc: TOMLDocument, *, table_path: list[str]) -> dict[str, Any] | None:
+def _resolve_table(*, toml_doc: TOMLDocument, table_path: list[str]) -> dict[str, Any] | None:
"""Walk ``table_path`` down the DOM, returning the addressed table or ``None`` when absent.
Every segment must resolve to a dict-like container (tomlkit tables and inline tables
@@ -78,7 +78,7 @@ def _resolve_table(toml_doc: TOMLDocument, *, table_path: list[str]) -> dict[str
return node
-def _rename_key_in_place(parent_table: dict[str, Any], *, key: str, new_key: str) -> None:
+def _rename_key_in_place(*, parent_table: dict[str, Any], key: str, new_key: str) -> None:
"""Rename ``key`` to ``new_key`` in a resolved table node, preserving position and comments.
tomlkit exposes no public position-preserving rename; ``Container._replace`` is its own
@@ -105,7 +105,7 @@ def _rename_key_in_place(parent_table: dict[str, Any], *, key: str, new_key: str
renamed_in_any = False
for sub_table in parent_table._tables: # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
if key in sub_table:
- _replace_key_in_container(sub_table.value, key=key, new_key=new_key)
+ _replace_key_in_container(container=sub_table.value, key=key, new_key=new_key)
renamed_in_any = True
if not renamed_in_any:
# The caller checked ``key in parent_table``, and the proxy's dict-facade is built from
@@ -114,16 +114,16 @@ def _rename_key_in_place(parent_table: dict[str, Any], *, key: str, new_key: str
raise PipelexUnexpectedError(msg)
return
if isinstance(parent_table, AbstractTable):
- _replace_key_in_container(parent_table.value, key=key, new_key=new_key)
+ _replace_key_in_container(container=parent_table.value, key=key, new_key=new_key)
return
if isinstance(parent_table, Container):
- _replace_key_in_container(parent_table, key=key, new_key=new_key)
+ _replace_key_in_container(container=parent_table, key=key, new_key=new_key)
return
msg = f"cannot rename key in unsupported tomlkit node type '{type(parent_table).__name__}' — applier bug"
raise PipelexUnexpectedError(msg)
-def _replace_key_in_container(container: Container, *, key: str, new_key: str) -> None:
+def _replace_key_in_container(*, container: Container, key: str, new_key: str) -> None:
container._replace(key, new_key, cast("Item", container[key])) # pyright: ignore[reportPrivateUsage]
@@ -173,7 +173,7 @@ def _render_syntax_diagnostic(diagnostic: "Diagnostic") -> str:
return f"{diagnostic['message']} (line {diagnostic_range['start_line']}:{diagnostic_range['start_col']})"
-def apply_fix_ops(toml_doc: TOMLDocument, *, ops: list[FixOp]) -> list[FixOpApplication]:
+def apply_fix_ops(*, toml_doc: TOMLDocument, ops: list[FixOp]) -> list[FixOpApplication]:
"""Apply each op to the DOM in place, returning one application report per op, in order.
Idempotent: re-applying an already-applied op sets the same value / finds the key
@@ -181,18 +181,18 @@ def apply_fix_ops(toml_doc: TOMLDocument, *, ops: list[FixOp]) -> list[FixOpAppl
"""
applications: list[FixOpApplication] = []
for fix_op in ops:
- applications.append(_apply_one_op(toml_doc, fix_op=fix_op))
+ applications.append(_apply_one_op(toml_doc=toml_doc, fix_op=fix_op))
return applications
-def _apply_one_op(toml_doc: TOMLDocument, *, fix_op: FixOp) -> FixOpApplication:
+def _apply_one_op(*, toml_doc: TOMLDocument, fix_op: FixOp) -> FixOpApplication:
table_path_str = ".".join(fix_op.table_path)
match fix_op.kind:
case FixOpKind.SET_KEY:
if fix_op.key is None or fix_op.value is None:
msg = f"set_key op on '{table_path_str}' requires both key and value — planner bug"
raise PipelexUnexpectedError(msg)
- target_table = _resolve_table(toml_doc, table_path=fix_op.table_path)
+ target_table = _resolve_table(toml_doc=toml_doc, table_path=fix_op.table_path)
if target_table is None:
return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"table '{table_path_str}' not found in document")
target_table[fix_op.key] = _as_tomlkit_value(fix_op.value)
@@ -201,10 +201,10 @@ def _apply_one_op(toml_doc: TOMLDocument, *, fix_op: FixOp) -> FixOpApplication:
if not fix_op.table_path:
msg = "ensure_table op requires a non-empty table_path — planner bug"
raise PipelexUnexpectedError(msg)
- existing_table = _resolve_table(toml_doc, table_path=fix_op.table_path)
+ existing_table = _resolve_table(toml_doc=toml_doc, table_path=fix_op.table_path)
if existing_table is not None:
return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"table '{table_path_str}' already exists")
- parent_table = _resolve_table(toml_doc, table_path=fix_op.table_path[:-1])
+ parent_table = _resolve_table(toml_doc=toml_doc, table_path=fix_op.table_path[:-1])
table_key = fix_op.table_path[-1]
if parent_table is None or table_key in parent_table:
return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"parent of table '{table_path_str}' not found")
@@ -214,7 +214,7 @@ def _apply_one_op(toml_doc: TOMLDocument, *, fix_op: FixOp) -> FixOpApplication:
if fix_op.key is None:
msg = f"delete_key op on '{table_path_str}' requires a key — planner bug"
raise PipelexUnexpectedError(msg)
- target_table = _resolve_table(toml_doc, table_path=fix_op.table_path)
+ target_table = _resolve_table(toml_doc=toml_doc, table_path=fix_op.table_path)
if target_table is None:
return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"table '{table_path_str}' not found in document")
if fix_op.key not in target_table:
@@ -225,7 +225,7 @@ def _apply_one_op(toml_doc: TOMLDocument, *, fix_op: FixOp) -> FixOpApplication:
if not fix_op.table_path:
msg = "delete_table op requires a non-empty table_path — planner bug"
raise PipelexUnexpectedError(msg)
- parent_table = _resolve_table(toml_doc, table_path=fix_op.table_path[:-1])
+ parent_table = _resolve_table(toml_doc=toml_doc, table_path=fix_op.table_path[:-1])
table_key = fix_op.table_path[-1]
# The final segment must itself be a table — a scalar there is a drifted target
# (same guarded-skip contract _resolve_table enforces for every other segment).
@@ -237,7 +237,7 @@ def _apply_one_op(toml_doc: TOMLDocument, *, fix_op: FixOp) -> FixOpApplication:
if fix_op.key is None or fix_op.new_key is None:
msg = f"rename_table_key op on '{table_path_str}' requires both key and new_key — planner bug"
raise PipelexUnexpectedError(msg)
- parent_table = _resolve_table(toml_doc, table_path=fix_op.table_path)
+ parent_table = _resolve_table(toml_doc=toml_doc, table_path=fix_op.table_path)
if parent_table is None or fix_op.key not in parent_table:
return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"key '{fix_op.key}' not found in table '{table_path_str}'")
if fix_op.new_key in parent_table:
@@ -249,5 +249,5 @@ def _apply_one_op(toml_doc: TOMLDocument, *, fix_op: FixOp) -> FixOpApplication:
outcome=FixOpOutcome.SKIPPED,
detail=f"cannot rename to '{fix_op.new_key}': already present in table '{table_path_str}'",
)
- _rename_key_in_place(parent_table, key=fix_op.key, new_key=fix_op.new_key)
+ _rename_key_in_place(parent_table=parent_table, key=fix_op.key, new_key=fix_op.new_key)
return FixOpApplication(op=fix_op, outcome=FixOpOutcome.APPLIED)
diff --git a/pipelex/pipeline/fixes/fix_loop.py b/pipelex/pipeline/fixes/fix_loop.py
index d5033d841..e748400e0 100644
--- a/pipelex/pipeline/fixes/fix_loop.py
+++ b/pipelex/pipeline/fixes/fix_loop.py
@@ -100,7 +100,7 @@ def _read_file_snapshot(path: Path) -> _FileSnapshot:
)
-def _write_staged_file(snapshot: _FileSnapshot, *, content: bytes, label: str) -> Path:
+def _write_staged_file(*, snapshot: _FileSnapshot, content: bytes, label: str) -> Path:
"""Write and fsync a same-directory temp file ready for atomic replacement."""
temp_file = tempfile.NamedTemporaryFile( # noqa: SIM115 - closed before the atomic replace
mode="wb",
@@ -125,17 +125,17 @@ def _write_staged_file(snapshot: _FileSnapshot, *, content: bytes, label: str) -
def _stage_file_update(update: _PendingFileUpdate) -> _StagedFileUpdate:
- replacement_path = _write_staged_file(update.snapshot, content=update.new_content.encode("utf-8"), label="new")
+ replacement_path = _write_staged_file(snapshot=update.snapshot, content=update.new_content.encode("utf-8"), label="new")
try:
replacement_snapshot = _read_file_snapshot(replacement_path)
- rollback_path = _write_staged_file(update.snapshot, content=update.snapshot.content, label="rollback")
+ rollback_path = _write_staged_file(snapshot=update.snapshot, content=update.snapshot.content, label="rollback")
except OSError:
replacement_path.unlink(missing_ok=True)
raise
return _StagedFileUpdate(snapshot=update.snapshot, replacement_snapshot=replacement_snapshot, rollback_path=rollback_path)
-def _file_state_matches(current_snapshot: _FileSnapshot, *, expected_snapshot: _FileSnapshot) -> bool:
+def _file_state_matches(*, current_snapshot: _FileSnapshot, expected_snapshot: _FileSnapshot) -> bool:
"""Whether content, permissions, and filesystem identity still match an observed file."""
return (
current_snapshot.content == expected_snapshot.content
@@ -152,7 +152,7 @@ def _assert_snapshot_unchanged(snapshot: _FileSnapshot) -> None:
except FileNotFoundError as exc:
msg = f"refusing to overwrite '{snapshot.path}': the file was removed while fixes were being prepared"
raise FixWriteConflictError(msg) from exc
- if not _file_state_matches(current_snapshot, expected_snapshot=snapshot):
+ if not _file_state_matches(current_snapshot=current_snapshot, expected_snapshot=snapshot):
msg = f"refusing to overwrite '{snapshot.path}': the file changed while fixes were being prepared"
raise FixWriteConflictError(msg)
@@ -164,7 +164,7 @@ def _rollback_committed_updates(committed_updates: list[_StagedFileUpdate]) -> l
target_path = staged_update.snapshot.path
try:
current_snapshot = _read_file_snapshot(target_path)
- if not _file_state_matches(current_snapshot, expected_snapshot=staged_update.replacement_snapshot):
+ if not _file_state_matches(current_snapshot=current_snapshot, expected_snapshot=staged_update.replacement_snapshot):
failures.append(f"{target_path}: file changed after the autofix replacement was committed")
continue
staged_update.rollback_path.replace(target_path)
@@ -645,7 +645,7 @@ async def fix_bundle_file(
toml_doc = tomlkit.loads(snapshot.content.decode("utf-8"))
any_op_applied = False
for target_fix in target_fixes:
- applications = apply_fix_ops(toml_doc, ops=target_fix.ops)
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=target_fix.ops)
if any(application.outcome.did_apply for application in applications):
round_fixes_applied.append(target_fix)
any_op_applied = True
diff --git a/pipelex/pipeline/pipe_io_contracts.py b/pipelex/pipeline/pipe_io_contracts.py
index de47c75de..4e9137dfe 100644
--- a/pipelex/pipeline/pipe_io_contracts.py
+++ b/pipelex/pipeline/pipe_io_contracts.py
@@ -104,7 +104,7 @@ def build_pipe_io_contracts(pipes: Sequence[PipeAbstract]) -> dict[str, PipeIOCo
# Indexing (not .get with a default) is deliberate: a render-shape drift
# must surface as the structured error below, never ship a silently
# empty schema on the wire.
- json_schema = stuff_spec.render_stuff_spec(ConceptRepresentationFormat.SCHEMA)["content"]
+ json_schema = stuff_spec.render_stuff_spec(output_format=ConceptRepresentationFormat.SCHEMA)["content"]
except (ConceptValueError, KeyError, PydanticUserError, PydanticUndefinedAnnotation) as exc:
msg = (
f"Failed to render the JSON Schema for input '{var_name}' of pipe "
diff --git a/pipelex/pipeline/pipeline_factory.py b/pipelex/pipeline/pipeline_factory.py
index b040ea526..c9b8d4221 100644
--- a/pipelex/pipeline/pipeline_factory.py
+++ b/pipelex/pipeline/pipeline_factory.py
@@ -6,7 +6,7 @@ from pipelex.pipeline.pipeline import Pipeline
class PipelineFactory:
@classmethod
- def make_pipeline(cls, pipeline_run_id: str | None = None) -> Pipeline:
+ def make_pipeline(cls, *, pipeline_run_id: str | None = None) -> Pipeline:
pipeline_run_id = pipeline_run_id or cls.make_pipeline_run_id()
log.verbose(f"Making new pipeline with run id: {pipeline_run_id}")
return Pipeline(
diff --git a/pipelex/pipeline/pipeline_manager.py b/pipelex/pipeline/pipeline_manager.py
index f772b62a9..7587a48b4 100644
--- a/pipelex/pipeline/pipeline_manager.py
+++ b/pipelex/pipeline/pipeline_manager.py
@@ -32,12 +32,12 @@ class PipelineManager(PipelineManagerAbstract, RootModel[PipelineManagerRoot]):
raise PipelineManagerNotFoundError(msg)
return pipeline
- def _set_pipeline(self, pipeline_run_id: str, *, pipeline: Pipeline) -> Pipeline:
+ def _set_pipeline(self, *, pipeline_run_id: str, pipeline: Pipeline) -> Pipeline:
self.root[pipeline_run_id] = pipeline
return pipeline
@override
- def add_new_pipeline(self, pipe_code: str | None, *, pipeline_run_id: str | None = None) -> Pipeline:
+ def add_new_pipeline(self, *, pipe_code: str | None, pipeline_run_id: str | None = None) -> Pipeline:
if pipeline_run_id is not None and pipeline_run_id in self.root:
msg = f"Pipeline {pipeline_run_id} already exists"
raise PipelineManagerAlreadyExistsError(msg)
diff --git a/pipelex/pipeline/pipeline_manager_abstract.py b/pipelex/pipeline/pipeline_manager_abstract.py
index 16605f841..1046ae44a 100644
--- a/pipelex/pipeline/pipeline_manager_abstract.py
+++ b/pipelex/pipeline/pipeline_manager_abstract.py
@@ -21,7 +21,7 @@ class PipelineManagerAbstract(ABC):
pass
@abstractmethod
- def add_new_pipeline(self, pipe_code: str | None, *, pipeline_run_id: str | None = None) -> Pipeline:
+ def add_new_pipeline(self, *, pipe_code: str | None, pipeline_run_id: str | None = None) -> Pipeline:
pass
@abstractmethod
diff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.py
index f92a54419..e3e8798a9 100644
--- a/pipelex/pipeline/pipeline_run_setup.py
+++ b/pipelex/pipeline/pipeline_run_setup.py
@@ -42,8 +42,8 @@ if TYPE_CHECKING:
async def pipeline_run_setup(
- execution_config: PipelineExecutionConfig,
*,
+ execution_config: PipelineExecutionConfig,
library_id: str | None = None,
library_dirs: list[str] | None = None,
pipe_code: str | None = None,
diff --git a/pipelex/pipeline/validation_render.py b/pipelex/pipeline/validation_render.py
index b1f9c2c0e..8d78dbdf0 100644
--- a/pipelex/pipeline/validation_render.py
+++ b/pipelex/pipeline/validation_render.py
@@ -59,7 +59,7 @@ def format_validate_markdown(result: dict[str, Any]) -> str:
validated_pipes: list[dict[str, Any]] = result.get("validated_pipes") or []
total_pipes = result.get("total_pipes", len(validated_pipes))
- lines.append(f"Validated {count_with_noun(total_pipes, singular='pipe')}:")
+ lines.append(f"Validated {count_with_noun(count=total_pipes, singular='pipe')}:")
lines.append("")
for entry in validated_pipes:
lines.append(f"- `{entry.get('pipe_ref')}` — {entry.get('status')}")
@@ -253,7 +253,7 @@ def format_validation_error_items_markdown(items: list[ValidationErrorItem]) ->
return "\n".join(lines).rstrip()
-def build_fix_command(executable: str, *, bundle_path: Path, library_dirs: list[Path] | None = None, allow_signatures: bool = False) -> str:
+def build_fix_command(*, executable: str, bundle_path: Path, library_dirs: list[Path] | None = None, allow_signatures: bool = False) -> str:
"""Build the copy-pasteable ``<executable> fix bundle <path>`` command for a fix-aware footer.
Shared by the human ``validate`` footer (``executable="pipelex"``) and the agent ``validate``
diff --git a/pipelex/plugins/anthropic/anthropic_factory.py b/pipelex/plugins/anthropic/anthropic_factory.py
index e74344deb..10baf7270 100644
--- a/pipelex/plugins/anthropic/anthropic_factory.py
+++ b/pipelex/plugins/anthropic/anthropic_factory.py
@@ -249,7 +249,7 @@ class AnthropicFactory:
return nb_tokens_by_category
@staticmethod
- def calculate_safe_max_tokens_for_timeout(timeout_seconds: int) -> int:
+ def calculate_safe_max_tokens_for_timeout(*, timeout_seconds: int) -> int:
"""Calculate max_tokens that won't trigger SDK timeout protection.
Formula: max_tokens = timeout_seconds * 128000 / 3600
diff --git a/pipelex/plugins/anthropic/anthropic_list.py b/pipelex/plugins/anthropic/anthropic_list.py
index 138688fd2..42329f283 100644
--- a/pipelex/plugins/anthropic/anthropic_list.py
+++ b/pipelex/plugins/anthropic/anthropic_list.py
@@ -18,8 +18,8 @@ if TYPE_CHECKING:
async def list_anthropic_models(
- sdk: str,
*,
+ sdk: str,
backend_name: str,
backend: InferenceBackend,
flat: bool,
diff --git a/pipelex/plugins/anthropic/anthropic_llm_worker.py b/pipelex/plugins/anthropic/anthropic_llm_worker.py
index 40fc39568..5c73d05ab 100644
--- a/pipelex/plugins/anthropic/anthropic_llm_worker.py
+++ b/pipelex/plugins/anthropic/anthropic_llm_worker.py
@@ -321,7 +321,7 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
timeout_seconds = anthropic_config.structured_output_timeout_seconds
# Calculate safe max_tokens based on timeout
- safe_max_tokens = AnthropicFactory.calculate_safe_max_tokens_for_timeout(timeout_seconds)
+ safe_max_tokens = AnthropicFactory.calculate_safe_max_tokens_for_timeout(timeout_seconds=timeout_seconds)
# Use minimum of requested and safe limit
requested_max_tokens = job_params.max_tokens or self.default_max_tokens
diff --git a/pipelex/plugins/bedrock/bedrock_list.py b/pipelex/plugins/bedrock/bedrock_list.py
index 7c2920bab..baf2fde2f 100644
--- a/pipelex/plugins/bedrock/bedrock_list.py
+++ b/pipelex/plugins/bedrock/bedrock_list.py
@@ -18,8 +18,8 @@ if TYPE_CHECKING:
def list_bedrock_models(
- sdk: str,
*,
+ sdk: str,
backend_name: str,
backend: InferenceBackend,
flat: bool,
diff --git a/pipelex/plugins/discovery.py b/pipelex/plugins/discovery.py
index 5241dfea9..6aa2d27e2 100644
--- a/pipelex/plugins/discovery.py
+++ b/pipelex/plugins/discovery.py
@@ -38,9 +38,9 @@ def build_registrar(*, config: "PipelexConfig") -> PluginRegistrar:
# Built-ins are already instantiated, so their name is known up front.
for plugin in BUILTIN_PLUGINS:
- if _skip_if_disabled(registrar, name=plugin.name, origin=PluginOrigin.BUILTIN, targets_api=plugin.targets_api, disabled=disabled):
+ if _skip_if_disabled(registrar=registrar, name=plugin.name, origin=PluginOrigin.BUILTIN, targets_api=plugin.targets_api, disabled=disabled):
continue
- _register_plugin(registrar, plugin=plugin, origin=PluginOrigin.BUILTIN)
+ _register_plugin(registrar=registrar, plugin=plugin, origin=PluginOrigin.BUILTIN)
# External entry points: denylist by entry-point name *before* load(), so a
# broken/dependency-missing installed plugin can still be recovered by disabling
@@ -48,17 +48,17 @@ def build_registrar(*, config: "PipelexConfig") -> PluginRegistrar:
# entry-point name; the post-load check honors the denylist on that too, so
# either name disables it.
for entry_point in _external_entry_points():
- if _skip_if_disabled(registrar, name=entry_point.name, origin=PluginOrigin.EXTERNAL, targets_api=None, disabled=disabled):
+ if _skip_if_disabled(registrar=registrar, name=entry_point.name, origin=PluginOrigin.EXTERNAL, targets_api=None, disabled=disabled):
continue
plugin = _load_external_plugin(entry_point)
- if _skip_if_disabled(registrar, name=plugin.name, origin=PluginOrigin.EXTERNAL, targets_api=plugin.targets_api, disabled=disabled):
+ if _skip_if_disabled(registrar=registrar, name=plugin.name, origin=PluginOrigin.EXTERNAL, targets_api=plugin.targets_api, disabled=disabled):
continue
- _register_plugin(registrar, plugin=plugin, origin=PluginOrigin.EXTERNAL)
+ _register_plugin(registrar=registrar, plugin=plugin, origin=PluginOrigin.EXTERNAL)
return registrar
-def _skip_if_disabled(registrar: PluginRegistrar, *, name: str, origin: PluginOrigin, targets_api: int | None, disabled: set[str]) -> bool:
+def _skip_if_disabled(*, registrar: PluginRegistrar, name: str, origin: PluginOrigin, targets_api: int | None, disabled: set[str]) -> bool:
"""Record and skip a denylisted plugin; return ``True`` if it was skipped.
Fail-loud when a core-unconditional plugin is denylisted — that is a
@@ -96,7 +96,7 @@ def _load_external_plugin(entry_point: importlib.metadata.EntryPoint) -> Pipelex
raise BrokenPluginError(plugin_name=entry_point.name, reason=f"failed to load entry point: {exc}") from exc
-def _register_plugin(registrar: PluginRegistrar, *, plugin: PipelexPlugin, origin: PluginOrigin) -> None:
+def _register_plugin(*, registrar: PluginRegistrar, plugin: PipelexPlugin, origin: PluginOrigin) -> None:
targets_api = getattr(plugin, "targets_api", None)
if targets_api != PLUGIN_API_VERSION:
raise PluginApiVersionMismatchError(
diff --git a/pipelex/plugins/gateway/gateway_search_worker.py b/pipelex/plugins/gateway/gateway_search_worker.py
index e19326dc0..ab720f36b 100644
--- a/pipelex/plugins/gateway/gateway_search_worker.py
+++ b/pipelex/plugins/gateway/gateway_search_worker.py
@@ -137,7 +137,7 @@ class GatewaySearchWorker(SearchWorkerAbstract):
nb_tokens[TokenCategory.OUTPUT] = output_tokens
search_tokens_usage.nb_tokens_by_category = nb_tokens
- async def _call_relay(self, model: str, *, content: str) -> GenericResponse:
+ async def _call_relay(self, *, model: str, content: str) -> GenericResponse:
"""Send a request through Portkey to the relay.
Args:
diff --git a/pipelex/plugins/google/google_list.py b/pipelex/plugins/google/google_list.py
index 69b76f73b..30b2b80a0 100644
--- a/pipelex/plugins/google/google_list.py
+++ b/pipelex/plugins/google/google_list.py
@@ -14,8 +14,8 @@ if TYPE_CHECKING:
async def list_google_models(
- sdk: str,
*,
+ sdk: str,
backend_name: str,
backend: InferenceBackend,
flat: bool,
diff --git a/pipelex/plugins/mistral/mistral_list.py b/pipelex/plugins/mistral/mistral_list.py
index 81fc11e81..af704e9f3 100644
--- a/pipelex/plugins/mistral/mistral_list.py
+++ b/pipelex/plugins/mistral/mistral_list.py
@@ -11,8 +11,8 @@ from pipelex.hub import get_console
def list_mistral_models(
- sdk: str,
*,
+ sdk: str,
backend_name: str,
flat: bool,
any_listed: bool,
diff --git a/pipelex/plugins/openai/openai_img_gen_factory.py b/pipelex/plugins/openai/openai_img_gen_factory.py
index 1ce183314..c2d88822e 100644
--- a/pipelex/plugins/openai/openai_img_gen_factory.py
+++ b/pipelex/plugins/openai/openai_img_gen_factory.py
@@ -174,7 +174,7 @@ class OpenAIImgGenFactory:
log.warning(msg)
@classmethod
- def moderation_for_openai_image(cls, is_moderated: bool | None) -> OpenAIImageModerationType:
+ def moderation_for_openai_image(cls, *, is_moderated: bool | None) -> OpenAIImageModerationType:
"""Map the is_moderated flag to OpenAI's moderation parameter: "auto" is standard filtering, "low" is less restrictive."""
if is_moderated is None:
return omit
diff --git a/pipelex/plugins/openai/openai_list.py b/pipelex/plugins/openai/openai_list.py
index b8ae6129b..20be6e9d1 100644
--- a/pipelex/plugins/openai/openai_list.py
+++ b/pipelex/plugins/openai/openai_list.py
@@ -17,8 +17,8 @@ if TYPE_CHECKING:
async def list_openai_models(
- sdk: str,
*,
+ sdk: str,
backend_name: str,
backend: InferenceBackend,
flat: bool,
diff --git a/pipelex/reporting/reporting_manager.py b/pipelex/reporting/reporting_manager.py
index 283a24c79..0ddc53fe1 100644
--- a/pipelex/reporting/reporting_manager.py
+++ b/pipelex/reporting/reporting_manager.py
@@ -71,8 +71,8 @@ class ReportingManager(ReportingProtocol):
@override
def set_event_log(
self,
- context_key: str,
*,
+ context_key: str,
event_log: EventLogProtocol,
workflow_id: str,
pipeline_run_id: str,
@@ -102,7 +102,7 @@ class ReportingManager(ReportingProtocol):
)
@override
- def clear_event_log(self, context_key: str) -> None:
+ def clear_event_log(self, *, context_key: str) -> None:
"""Remove event log configuration for a completed workflow/run."""
self._event_log_contexts.pop(context_key, None)
@@ -199,7 +199,7 @@ class ReportingManager(ReportingProtocol):
if not is_in_isolated_execution():
context = self._event_log_contexts.get(trace_context.lookup_key)
if context is not None:
- self._emit_via_registered_context(context, trace_context=trace_context, tokens_usage=tokens_usage)
+ self._emit_via_registered_context(context=context, trace_context=trace_context, tokens_usage=tokens_usage)
return
self._emit_usage_event_runner_fallback(
@@ -210,8 +210,8 @@ class ReportingManager(ReportingProtocol):
@staticmethod
def _emit_via_registered_context(
- context: _EventLogContext,
*,
+ context: _EventLogContext,
trace_context: TraceContext,
tokens_usage: AnyTokensUsage,
) -> None:
diff --git a/pipelex/reporting/reporting_protocol.py b/pipelex/reporting/reporting_protocol.py
index 87baa0403..467bdb521 100644
--- a/pipelex/reporting/reporting_protocol.py
+++ b/pipelex/reporting/reporting_protocol.py
@@ -15,14 +15,14 @@ class ReportingProtocol(Protocol):
def set_event_log(
self,
- context_key: str,
*,
+ context_key: str,
event_log: EventLogProtocol,
workflow_id: str,
pipeline_run_id: str,
) -> None: ...
- def clear_event_log(self, context_key: str) -> None: ...
+ def clear_event_log(self, *, context_key: str) -> None: ...
class ReportingNoOp(ReportingProtocol):
@@ -41,8 +41,8 @@ class ReportingNoOp(ReportingProtocol):
@override
def set_event_log(
self,
- context_key: str,
*,
+ context_key: str,
event_log: EventLogProtocol,
workflow_id: str,
pipeline_run_id: str,
@@ -50,5 +50,5 @@ class ReportingNoOp(ReportingProtocol):
pass
@override
- def clear_event_log(self, context_key: str) -> None:
+ def clear_event_log(self, *, context_key: str) -> None:
pass
diff --git a/pipelex/runtime_bridge/bootstrap.py b/pipelex/runtime_bridge/bootstrap.py
index e0aba0683..ab99275c9 100644
--- a/pipelex/runtime_bridge/bootstrap.py
+++ b/pipelex/runtime_bridge/bootstrap.py
@@ -22,6 +22,7 @@ _boot_lock = threading.Lock()
def ensure_pipelex_booted(
+ *,
config_overrides: dict[str, Any] | None = None,
) -> None:
"""Boot Pipelex on first call; no-op if already initialized.
diff --git a/pipelex/system/pipelex_service/remote_config_fetcher.py b/pipelex/system/pipelex_service/remote_config_fetcher.py
index 76eb0b6cb..3110da4c2 100644
--- a/pipelex/system/pipelex_service/remote_config_fetcher.py
+++ b/pipelex/system/pipelex_service/remote_config_fetcher.py
@@ -198,7 +198,7 @@ class RemoteConfigFetcher:
return RemoteConfigUnavailableError(msg)
@classmethod
- def fetch_remote_config(cls, require_fresh: bool = False) -> RemoteConfigResult:
+ def fetch_remote_config(cls, *, require_fresh: bool = False) -> RemoteConfigResult:
"""Fetch the Pipelex Service remote configuration.
Args:
diff --git a/pipelex/system/telemetry/otel_factory.py b/pipelex/system/telemetry/otel_factory.py
index 8487fb5bc..170cb9b55 100644
--- a/pipelex/system/telemetry/otel_factory.py
+++ b/pipelex/system/telemetry/otel_factory.py
@@ -213,8 +213,8 @@ class OtelFactory:
@classmethod
def make_ai_tracer(
cls,
- user_id: str | None,
*,
+ user_id: str | None,
custom_posthog_client: "Posthog | None",
custom_redaction_config: TelemetryRedactionConfig,
pipelex_posthog_client: "Posthog | None",
diff --git a/pipelex/system/telemetry/telemetry_config.py b/pipelex/system/telemetry/telemetry_config.py
index 18d4d9a44..b6912e8be 100644
--- a/pipelex/system/telemetry/telemetry_config.py
+++ b/pipelex/system/telemetry/telemetry_config.py
@@ -237,7 +237,7 @@ class TelemetryRedactionConfig(BaseModel):
)
-def load_telemetry_config(secrets_provider: SecretsProviderAbstract) -> TelemetryConfig:
+def load_telemetry_config(*, secrets_provider: SecretsProviderAbstract) -> TelemetryConfig:
"""Load telemetry configuration from a TOML file with variable substitution.
Files are deep-merged in this order (later wins per leaf key):
diff --git a/pipelex/system/telemetry/telemetry_factory.py b/pipelex/system/telemetry/telemetry_factory.py
index 4baa90862..d7183d108 100644
--- a/pipelex/system/telemetry/telemetry_factory.py
+++ b/pipelex/system/telemetry/telemetry_factory.py
@@ -22,8 +22,8 @@ class TelemetryFactory:
@classmethod
def make_telemetry_manager(
cls,
- secrets_provider: SecretsProviderAbstract,
*,
+ secrets_provider: SecretsProviderAbstract,
integration_mode: IntegrationMode,
remote_config: RemoteConfig | None,
is_pipelex_telemetry_enabled: bool = False,
diff --git a/pipelex/system/telemetry/telemetry_manager.py b/pipelex/system/telemetry/telemetry_manager.py
index 85925a924..1e852633d 100644
--- a/pipelex/system/telemetry/telemetry_manager.py
+++ b/pipelex/system/telemetry/telemetry_manager.py
@@ -191,7 +191,7 @@ class TelemetryManager(TelemetryManagerAbstract):
client.capture_exception = sanitized_capture_exception # type: ignore[method-assign]
@override
- def setup(self, integration_mode: IntegrationMode):
+ def setup(self, *, integration_mode: IntegrationMode):
pass
@override
@@ -297,7 +297,7 @@ class TelemetryManager(TelemetryManagerAbstract):
yield
@override
- def is_custom_portkey_logging_enabled(self, is_debug_configured: bool) -> bool:
+ def is_custom_portkey_logging_enabled(self, *, is_debug_configured: bool) -> bool:
is_debug: bool = is_debug_configured
if not is_debug and self.telemetry_config.custom_portkey.force_debug_enabled:
log.verbose("Force-enabling Portkey logging (debug mode) because custom_portkey.force_debug_enabled is set in telemetry configuration")
@@ -319,7 +319,7 @@ class TelemetryManager(TelemetryManagerAbstract):
return False
@override
- def is_pipelex_gateway_portkey_logging_enabled(self, is_debug_configured: bool) -> bool:
+ def is_pipelex_gateway_portkey_logging_enabled(self, *, is_debug_configured: bool) -> bool:
is_debug: bool = is_debug_configured
if (
not is_debug
@@ -390,7 +390,7 @@ class TelemetryManager(TelemetryManagerAbstract):
return self._pipelex_telemetry_enabled
@override
- def handle_trace_start(self, trace_name: str, *, trace_name_redacted: str, trace_id: int) -> None:
+ def handle_trace_start(self, *, trace_name: str, trace_name_redacted: str, trace_id: int) -> None:
"""Hook to do something when a trace starts.
Emits a trace start event to establish the trace name in PostHog.
diff --git a/pipelex/system/telemetry/telemetry_manager_abstract.py b/pipelex/system/telemetry/telemetry_manager_abstract.py
index c01537d95..1c1ffbc59 100644
--- a/pipelex/system/telemetry/telemetry_manager_abstract.py
+++ b/pipelex/system/telemetry/telemetry_manager_abstract.py
@@ -86,7 +86,7 @@ class TelemetryManagerAbstract(metaclass=ABCSingletonMeta):
return instance.is_langfuse_enabled
@abstractmethod
- def setup(self, integration_mode: IntegrationMode):
+ def setup(self, *, integration_mode: IntegrationMode):
pass
@abstractmethod
@@ -103,7 +103,7 @@ class TelemetryManagerAbstract(metaclass=ABCSingletonMeta):
"""Safe context manager for telemetry that works whether telemetry is enabled or not."""
@abstractmethod
- def is_custom_portkey_logging_enabled(self, is_debug_configured: bool) -> bool:
+ def is_custom_portkey_logging_enabled(self, *, is_debug_configured: bool) -> bool:
pass
@abstractmethod
@@ -111,7 +111,7 @@ class TelemetryManagerAbstract(metaclass=ABCSingletonMeta):
pass
@abstractmethod
- def is_pipelex_gateway_portkey_logging_enabled(self, is_debug_configured: bool) -> bool:
+ def is_pipelex_gateway_portkey_logging_enabled(self, *, is_debug_configured: bool) -> bool:
pass
@abstractmethod
@@ -153,7 +153,7 @@ class TelemetryManagerAbstract(metaclass=ABCSingletonMeta):
"""Whether Pipelex internal telemetry is enabled (for gateway usage)."""
@abstractmethod
- def handle_trace_start(self, trace_name: str, *, trace_name_redacted: str, trace_id: int) -> None:
+ def handle_trace_start(self, *, trace_name: str, trace_name_redacted: str, trace_id: int) -> None:
"""Hook to do something when a trace starts.
Args:
@@ -165,7 +165,7 @@ class TelemetryManagerAbstract(metaclass=ABCSingletonMeta):
class TelemetryManagerNoOp(TelemetryManagerAbstract):
@override
- def setup(self, integration_mode: IntegrationMode):
+ def setup(self, *, integration_mode: IntegrationMode):
pass
@override
@@ -184,7 +184,7 @@ class TelemetryManagerNoOp(TelemetryManagerAbstract):
yield
@override
- def is_custom_portkey_logging_enabled(self, is_debug_configured: bool) -> bool:
+ def is_custom_portkey_logging_enabled(self, *, is_debug_configured: bool) -> bool:
return False
@override
@@ -192,7 +192,7 @@ class TelemetryManagerNoOp(TelemetryManagerAbstract):
return False
@override
- def is_pipelex_gateway_portkey_logging_enabled(self, is_debug_configured: bool) -> bool:
+ def is_pipelex_gateway_portkey_logging_enabled(self, *, is_debug_configured: bool) -> bool:
return False
@override
@@ -234,5 +234,5 @@ class TelemetryManagerNoOp(TelemetryManagerAbstract):
return False
@override
- def handle_trace_start(self, trace_name: str, *, trace_name_redacted: str, trace_id: int) -> None:
+ def handle_trace_start(self, *, trace_name: str, trace_name_redacted: str, trace_id: int) -> None:
pass
diff --git a/pipelex/tools/aws/aws_config.py b/pipelex/tools/aws/aws_config.py
index a12f44a03..4c0b30c6f 100644
--- a/pipelex/tools/aws/aws_config.py
+++ b/pipelex/tools/aws/aws_config.py
@@ -35,7 +35,7 @@ class AwsConfig(ConfigModel):
def get_aws_access_keys(self) -> tuple[str, str, str]:
return self.get_aws_access_keys_with_method(api_key_method=self.api_key_method)
- def get_aws_access_keys_with_method(self, api_key_method: AwsKeyMethod) -> tuple[str, str, str]:
+ def get_aws_access_keys_with_method(self, *, api_key_method: AwsKeyMethod) -> tuple[str, str, str]:
match api_key_method:
case AwsKeyMethod.ENV:
log.verbose("Getting AWS access keys from environment (key id and secret access key).")
diff --git a/pipelex/tools/jinja2/image_renderable.py b/pipelex/tools/jinja2/image_renderable.py
index 6a04e9118..c80095012 100644
--- a/pipelex/tools/jinja2/image_renderable.py
+++ b/pipelex/tools/jinja2/image_renderable.py
@@ -35,8 +35,8 @@ class ImageRenderable(Protocol):
def render_with_images(
self,
- registry: ImageRegistry,
*,
+ registry: ImageRegistry,
text_format: TextFormat,
) -> str:
"""Render to string, registering images to the registry.
diff --git a/pipelex/tools/jinja2/jinja2_with_images_filter.py b/pipelex/tools/jinja2/jinja2_with_images_filter.py
index 10908c0d5..a9946774f 100644
--- a/pipelex/tools/jinja2/jinja2_with_images_filter.py
+++ b/pipelex/tools/jinja2/jinja2_with_images_filter.py
@@ -59,7 +59,7 @@ def with_images(context: Context, value: Any, _: Any = None) -> str:
# Protocol-based rendering
if isinstance(value, ImageRenderable):
- return value.render_with_images(registry, text_format=text_format)
+ return value.render_with_images(registry=registry, text_format=text_format)
# Handle plain lists/tuples (structural types that may contain ImageRenderable items)
if isinstance(value, (list, tuple)):
@@ -94,7 +94,7 @@ def _render_sequence_with_images(
parts: list[str] = []
for item in sequence:
if isinstance(item, ImageRenderable):
- rendered = item.render_with_images(registry, text_format=text_format)
+ rendered = item.render_with_images(registry=registry, text_format=text_format)
else:
rendered = str(item)
if rendered:
diff --git a/pipelex/tools/jinja2/text_format_renderable.py b/pipelex/tools/jinja2/text_format_renderable.py
index 549ec9a48..abfc508f7 100644
--- a/pipelex/tools/jinja2/text_format_renderable.py
+++ b/pipelex/tools/jinja2/text_format_renderable.py
@@ -29,7 +29,7 @@ class TextFormatRenderable(Protocol):
- StuffArtefact: delegates to underlying content
"""
- async def rendered_for_template_async(self, text_format: TextFormat) -> str:
+ async def rendered_for_template_async(self, *, text_format: TextFormat) -> str:
"""Render content for templates in the specified text format.
Args:
diff --git a/pipelex/tools/log/log.py b/pipelex/tools/log/log.py
index a177e544a..6b510b15c 100644
--- a/pipelex/tools/log/log.py
+++ b/pipelex/tools/log/log.py
@@ -167,7 +167,7 @@ class Log:
raise RuntimeError(msg)
self.rich_handler.console = Console(file=sys.stderr)
- def set_level_by_int(self, level_int: int):
+ def set_level_by_int(self, *, level_int: int):
"""Set the log level using an integer value.
Args:
@@ -189,7 +189,7 @@ class Log:
level = LOGGING_LEVEL_OFF
else:
level = getattr(logging, level_name.upper())
- self.set_level_by_int(level)
+ self.set_level_by_int(level_int=level)
def set_level(self, level: LogLevel):
"""Set the default log level for all loggers.
diff --git a/pipelex/tools/log/log_levels.py b/pipelex/tools/log/log_levels.py
index 6d5dd2b5c..cd5ba27fa 100644
--- a/pipelex/tools/log/log_levels.py
+++ b/pipelex/tools/log/log_levels.py
@@ -43,7 +43,7 @@ class LogLevel(StrEnum):
return LOGGING_LEVEL_OFF
@staticmethod
- def from_int(logging_level: int) -> "LogLevel":
+ def from_int(*, logging_level: int) -> "LogLevel":
if logging_level == LOGGING_LEVEL_VERBOSE:
return LogLevel.VERBOSE
elif logging_level == LOGGING_LEVEL_DEV:
diff --git a/pipelex/tools/misc/pretty.py b/pipelex/tools/misc/pretty.py
index 1125c5176..cf384e431 100644
--- a/pipelex/tools/misc/pretty.py
+++ b/pipelex/tools/misc/pretty.py
@@ -219,7 +219,7 @@ class PrettyPrinter:
Console(width=console_width).print("", panel, "", sep="\n")
@classmethod
- def pretty_width(cls, width: int | None = None, *, depth: int | None = None) -> int:
+ def pretty_width(cls, *, width: int | None = None, depth: int | None = None) -> int:
terminal_width = shutil.get_terminal_size().columns
absolute_width = width or min(max(PRETTY_WIDTH_MIN, terminal_width // 2), terminal_width)
if depth is not None:
diff --git a/pipelex/tools/misc/string_utils.py b/pipelex/tools/misc/string_utils.py
index bfcd5425d..9f7399389 100644
--- a/pipelex/tools/misc/string_utils.py
+++ b/pipelex/tools/misc/string_utils.py
@@ -332,7 +332,7 @@ def get_root_from_dotted_path(dotted_path: str) -> str:
return dotted_path.split(".", 1)[0]
-def pluralize(count: int, *, singular: str, plural: str | None = None) -> str:
+def pluralize(*, count: int, singular: str, plural: str | None = None) -> str:
"""Pick the singular or plural form of a word based on a count.
Returns ``singular`` when ``count == 1``, otherwise ``plural`` (defaulting to
@@ -348,15 +348,15 @@ def pluralize(count: int, *, singular: str, plural: str | None = None) -> str:
The grammatically-agreed form of the word.
Examples:
- >>> pluralize(1, singular="pipe")
+ >>> pluralize(count=1, singular="pipe")
'pipe'
- >>> pluralize(2, singular="pipe")
+ >>> pluralize(count=2, singular="pipe")
'pipes'
- >>> pluralize(0, singular="pipe")
+ >>> pluralize(count=0, singular="pipe")
'pipes'
- >>> pluralize(1, singular="is", plural="are")
+ >>> pluralize(count=1, singular="is", plural="are")
'is'
- >>> pluralize(3, singular="entry", plural="entries")
+ >>> pluralize(count=3, singular="entry", plural="entries")
'entries'
"""
@@ -365,7 +365,7 @@ def pluralize(count: int, *, singular: str, plural: str | None = None) -> str:
return plural or f"{singular}s"
-def count_with_noun(count: int, *, singular: str, plural: str | None = None) -> str:
+def count_with_noun(*, count: int, singular: str, plural: str | None = None) -> str:
"""Format a count together with its grammatically-agreed noun.
Produces "1 pipe" / "2 pipes" so messages stay clean instead of resorting to
@@ -380,15 +380,15 @@ def count_with_noun(count: int, *, singular: str, plural: str | None = None) ->
The count followed by a space and the agreed noun form.
Examples:
- >>> count_with_noun(1, singular="pipe")
+ >>> count_with_noun(count=1, singular="pipe")
'1 pipe'
- >>> count_with_noun(2, singular="pipe")
+ >>> count_with_noun(count=2, singular="pipe")
'2 pipes'
- >>> count_with_noun(0, singular="entry", plural="entries")
+ >>> count_with_noun(count=0, singular="entry", plural="entries")
'0 entries'
"""
- return f"{count} {pluralize(count, singular=singular, plural=plural)}"
+ return f"{count} {pluralize(count=count, singular=singular, plural=plural)}"
def matches_wildcard_pattern(text: str, *, pattern: str) -> bool:
diff --git a/pipelex/tracing/activity_event_log.py b/pipelex/tracing/activity_event_log.py
index bd550caf0..bfe55d758 100644
--- a/pipelex/tracing/activity_event_log.py
+++ b/pipelex/tracing/activity_event_log.py
@@ -77,7 +77,7 @@ class ActivityEventLogCache:
return cls._cached_event_log
@classmethod
- def log_once_runner_fallback_engaged(cls, workflow_id: str, *, writer_id: str) -> None:
+ def log_once_runner_fallback_engaged(cls, *, workflow_id: str, writer_id: str) -> None:
"""Log a single INFO the first time activity-side emission engages.
The log is per-process; subsequent emissions from the same process are
diff --git a/pipelex/tracing/graphspec_assembler.py b/pipelex/tracing/graphspec_assembler.py
index 1c05825f1..c75fe3412 100644
--- a/pipelex/tracing/graphspec_assembler.py
+++ b/pipelex/tracing/graphspec_assembler.py
@@ -424,7 +424,7 @@ class _AssemblerState:
producer_data = self._nodes.get(producer_node_id)
if producer_data is None:
return False
- return output_digest_is_optional(producer_data.output_specs, digest=digest)
+ return output_digest_is_optional(output_specs=producer_data.output_specs, digest=digest)
def _generate_data_edges(self) -> None:
"""Generate DATA edges by correlating input digests with producer nodes.
diff --git a/subject_grants.toml b/subject_grants.toml
new file mode 100644
index 000000000..04895fb7d
--- /dev/null
+++ b/subject_grants.toml
@@ -0,0 +1,6969 @@
+version = 1
+
+["pipelex/base_exceptions.py::ErrorReport.from_dict"]
+param = "data"
+rationale = "Factory from source: builds the report from the dict; single operand."
+
+["pipelex/base_exceptions.py::PipelexError._enrich_error_report_from_cause"]
+param = "report"
+rationale = "Verb-object: enriches the report; single operand."
+
+["pipelex/base_exceptions.py::_humanize_class_name"]
+param = "class_name"
+rationale = "Transforms the class name into a human title; single operand."
+
+["pipelex/base_exceptions.py::_redact_provider_metadata_for_strict"]
+param = "metadata_payload"
+rationale = "Transforms the metadata payload; single operand."
+
+["pipelex/base_exceptions.py::error_domain_is_input"]
+param = "error_domain"
+rationale = "Predicate on the error domain; single operand."
+
+["pipelex/base_exceptions.py::error_domain_to_http_status"]
+param = "error_domain"
+rationale = "Conversion: maps the error domain to a status; single operand."
+
+["pipelex/base_exceptions.py::iter_cause_chain"]
+param = "exc"
+rationale = "Verb-object: iterates the exception's cause chain; single operand."
+
+["pipelex/builder/concept/concept_spec.py::ConceptSpec._format_type_display"]
+param = "field_spec"
+rationale = "Verb-object: formats the field spec's type display; single operand."
+
+["pipelex/builder/operations/concept_ops.py::concept_spec_to_toml"]
+param = "concept_spec"
+rationale = "Conversion: the concept spec being rendered to TOML; single operand."
+
+["pipelex/builder/operations/concept_ops.py::parse_concept_spec"]
+param = "spec_data"
+rationale = "Verb-object: parses the raw spec data; single operand."
+
+["pipelex/builder/operations/concept_ops.py::structure_field_to_dict"]
+param = "field_spec"
+rationale = "Conversion: the field spec being dictified; single operand."
+
+["pipelex/builder/operations/models_ops.py::_filter_aliases_by_backend"]
+param = "aliases"
+rationale = "Verb-object: the alias mapping being filtered; backend context stays keyword."
+
+["pipelex/builder/operations/models_ops.py::_filter_presets_by_backend"]
+param = "presets_list"
+rationale = "Verb-object: the preset list being filtered; backend context stays keyword."
+
+["pipelex/builder/operations/models_ops.py::_filter_waterfalls_by_backend"]
+param = "waterfalls"
+rationale = "Verb-object: the waterfall mapping being filtered; backend context stays keyword."
+
+["pipelex/builder/operations/models_ops.py::_should_include"]
+param = "category"
+rationale = "Predicate on the candidate category; the filter list stays keyword."
+
+["pipelex/builder/operations/models_ops.py::format_models_markdown"]
+param = "result"
+rationale = "Verb-object: formats the list_models result dict; single operand."
+
+["pipelex/builder/operations/pipe_ops.py::_normalize_output"]
+param = "data"
+rationale = "Single-operand normalization of the raw spec data."
+
+["pipelex/builder/operations/pipe_ops.py::_normalize_pipe_code_aliases"]
+param = "data"
+rationale = "Verb-object: normalizes the dict in place; single operand."
+
+["pipelex/builder/operations/pipe_ops.py::_normalize_prompt_aliases"]
+param = "data"
+rationale = "Verb-object: normalizes the dict in place; single operand."
+
+["pipelex/builder/operations/pipe_ops.py::_normalize_sub_pipe_dict"]
+param = "data"
+rationale = "Verb-object: normalizes the step/branch dict in place; single operand."
+
+["pipelex/builder/operations/pipe_ops.py::_normalize_sub_pipe_list"]
+param = "raw_value"
+rationale = "Verb-object: the raw steps/branches value being normalized; field_name stays keyword."
+
+["pipelex/builder/operations/pipe_ops.py::parse_pipe_spec"]
+param = "spec_data"
+rationale = "Verb-object: parses the raw spec data; pipe_type stays keyword."
+
+["pipelex/builder/operations/pipe_ops.py::pipe_spec_to_toml"]
+param = "pipe_spec"
+rationale = "Conversion: the pipe spec being rendered to TOML; single operand."
+
+["pipelex/builder/operations/validate_ops.py::validate_bundle_content"]
+param = "mthds_contents"
+rationale = "Verb-object: validates the given .mthds contents; single operand."
+
+["pipelex/builder/operations/validate_ops.py::validate_bundle_file"]
+param = "bundle_path"
+rationale = "Verb-object: validates the bundle at the given path; library_dirs stays keyword."
+
+["pipelex/builder/operations/validate_ops.py::validate_pipe"]
+param = "pipe_code"
+rationale = "Verb-object: validates the pipe named by the code; single operand."
+
+["pipelex/builder/pipe/pipe_spec.py::PipeSpec.validate_pipe_code_syntax"]
+param = "pipe_code"
+rationale = "Verb-object: validates/normalizes the pipe code; also invoked positionally by the field validator."
+
+["pipelex/builder/runner_code.py::_collect_imports_for_inputs"]
+param = "inputs"
+rationale = "Verb-object: collects imports for the pipe inputs; single operand."
+
+["pipelex/builder/runner_code.py::_format_representation_as_python"]
+param = "representation"
+rationale = "Verb-object: formats the representation dict as Python; is_multiple stays keyword."
+
+["pipelex/builder/runner_code.py::_is_multiple"]
+param = "multiplicity"
+rationale = "Predicate on the multiplicity value; single operand."
+
+["pipelex/builder/runner_code.py::generate_runner_code"]
+param = "pipe"
+rationale = "Verb-object: generates runner code for the pipe; single obvious operand."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::_agent_error_json"]
+param = "message"
+rationale = "Builds the error JSON around the message; single operand."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::_assemble_error_payload"]
+param = "message"
+rationale = "Assembles the error payload around the message; single operand."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::_build_error_source"]
+param = "exc"
+rationale = "Derives from the exc; single operand."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::_render_error_markdown"]
+param = "payload"
+rationale = "Renders the payload; single operand."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::_render_validate_bundle_markdown"]
+param = "items"
+rationale = "Verb-object: renders the validation error items; the rest is context."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::agent_error"]
+param = "message"
+rationale = "Emits an agent error for the message; single operand."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::agent_error_markdown"]
+param = "message"
+rationale = "Renders the message; single operand."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::agent_error_validate_bundle"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::agent_success"]
+param = "result"
+rationale = "Emits the success result payload; single operand."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::agent_success_formatted"]
+param = "result"
+rationale = "Emits the formatted success result; single operand."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::extract_validation_errors"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::record_setup_warning"]
+param = "warning_payload"
+rationale = "Records the setup-warning payload; single operand."
+
+["pipelex/cli/agent_cli/commands/agent_output.py::set_agent_cli_error_format"]
+param = "error_format"
+rationale = "Setter: installs the agent-CLI error format; single operand."
+
+["pipelex/cli/agent_cli/commands/bundle_path_resolver.py::_handle_resolution_error"]
+param = "error"
+rationale = "Error handler: the resolution error is the single operand handled."
+
+["pipelex/cli/agent_cli/commands/bundle_path_resolver.py::_stringify_library_dirs"]
+param = "library_dirs"
+rationale = "Single-operand conversion of the dirs list."
+
+["pipelex/cli/agent_cli/commands/bundle_path_resolver.py::resolve_bundle_target"]
+param = "path"
+rationale = "Verb-object: resolves the target path; library_dir stays keyword."
+
+["pipelex/cli/agent_cli/commands/check_model_cmd.py::_format_check_markdown"]
+param = "result"
+rationale = "Renders the result; single operand."
+
+["pipelex/cli/agent_cli/commands/codegen/check_cmd.py::_format_codegen_check_markdown"]
+param = "result"
+rationale = "Positional-Callable protocol: passed as markdown_renderer, invoked renderer(result)."
+
+["pipelex/cli/agent_cli/commands/codegen/types_cmd.py::_format_codegen_types_markdown"]
+param = "result"
+rationale = "Positional-Callable protocol: passed as markdown_renderer, invoked renderer(result)."
+
+["pipelex/cli/agent_cli/commands/concept_cmd.py::_concept_spec_to_toml"]
+param = "concept_spec"
+rationale = "Serializes the concept_spec to TOML; single operand."
+
+["pipelex/cli/agent_cli/commands/doctor_cmd.py::_format_doctor_markdown"]
+param = "result"
+rationale = "Renders the result; single operand."
+
+["pipelex/cli/agent_cli/commands/fix/bundle_cmd.py::_failure_message"]
+param = "result"
+rationale = "Noun-named derivation: the failure message for the fix result; single operand."
+
+["pipelex/cli/agent_cli/commands/fix/bundle_cmd.py::_normalize_rule_codes"]
+param = "codes"
+rationale = "Single-operand normalization of the rule codes."
+
+["pipelex/cli/agent_cli/commands/fix/bundle_cmd.py::_result_payload"]
+param = "result"
+rationale = "Noun-named derivation from the fix result; bundle_path stays keyword."
+
+["pipelex/cli/agent_cli/commands/init_cmd.py::_configure_routing"]
+param = "selected_backend_keys"
+rationale = "Configures routing from the selected backend keys; single operand."
+
+["pipelex/cli/agent_cli/commands/init_cmd.py::_copy_inference_templates"]
+param = "target_dir"
+rationale = "Copies the inference templates into the target dir; single operand."
+
+["pipelex/cli/agent_cli/commands/init_cmd.py::_copy_telemetry_template"]
+param = "target_dir"
+rationale = "Copies the telemetry template into the target dir; single operand."
+
+["pipelex/cli/agent_cli/commands/init_cmd.py::_format_init_markdown"]
+param = "result"
+rationale = "Renders the result; single operand."
+
+["pipelex/cli/agent_cli/commands/init_cmd.py::_parse_config_arg"]
+param = "config_arg"
+rationale = "Parses the config_arg; single operand."
+
+["pipelex/cli/agent_cli/commands/inputs/_inputs_core.py::emit_inputs_result"]
+param = "result"
+rationale = "Verb-object: emits the result; format options stay keyword."
+
+["pipelex/cli/agent_cli/commands/pipe_cmd.py::_pipe_spec_to_toml"]
+param = "pipe_spec"
+rationale = "Serializes the pipe_spec to TOML; single operand."
+
+["pipelex/cli/agent_cli/commands/plxt_passthrough.py::run_plxt"]
+param = "subcommand"
+rationale = "Runs the given plxt subcommand; single operand."
+
+["pipelex/cli/agent_cli/commands/run/_output_helpers.py::_render_json_payload_lines"]
+param = "result_payload"
+rationale = "Renders the result_payload; single operand."
+
+["pipelex/cli/agent_cli/commands/run/_output_helpers.py::format_run_markdown"]
+param = "result"
+rationale = "Renders the result; single operand."
+
+["pipelex/cli/agent_cli/commands/run/_run_core.py::run_pipeline_core"]
+param = "pipe_code"
+rationale = "Runs the pipe identified by pipe_code; single operand."
+
+["pipelex/cli/agent_cli/commands/run/_run_core_api.py::run_pipeline_core_api"]
+param = "pipe_code"
+rationale = "Runs the pipe identified by pipe_code via the API; single operand."
+
+["pipelex/cli/agent_cli/commands/run/stdin_resolver.py::_extract_concept_code"]
+param = "concept_data"
+rationale = "Extracts from the concept_data; single operand."
+
+["pipelex/cli/agent_cli/commands/run/stdin_resolver.py::_extract_stuff_entry"]
+param = "stuff_data"
+rationale = "Extracts from the stuff_data; single operand."
+
+["pipelex/cli/agent_cli/commands/run/stdin_resolver.py::_parse_inputs_arg"]
+param = "inputs_arg"
+rationale = "Parses the inputs_arg; single operand."
+
+["pipelex/cli/agent_cli/commands/run/stdin_resolver.py::parse_cli_inputs"]
+param = "inputs_arg"
+rationale = "Parses the inputs_arg; single operand."
+
+["pipelex/cli/agent_cli/commands/run/stdin_resolver.py::resolve_stdin_inputs"]
+param = "stdin_data"
+rationale = "Parses the stdin_data; single operand."
+
+["pipelex/cli/agent_cli/commands/validate/_validate_core.py::validate_bundle_core"]
+param = "bundle_path"
+rationale = "Validates the bundle at the path; single operand."
+
+["pipelex/cli/agent_cli/commands/validate/_validate_core.py::validate_pipe_core"]
+param = "pipe_code"
+rationale = "Validates the pipe identified by pipe_code; single operand."
+
+["pipelex/cli/bundle_target_resolution.py::resolve_bundle_target_core"]
+param = "path"
+rationale = "Verb-object: resolves the target path; library_dir stays keyword."
+
+["pipelex/cli/commands/bundle_path_resolver.py::_handle_resolution_error"]
+param = "error"
+rationale = "Error handler: the resolution error is the single operand handled."
+
+["pipelex/cli/commands/bundle_path_resolver.py::_stringify_library_dirs"]
+param = "library_dirs"
+rationale = "Single-operand conversion of the dirs list."
+
+["pipelex/cli/commands/bundle_path_resolver.py::resolve_bundle_target"]
+param = "path"
+rationale = "Verb-object: resolves the target path; presentation params stay keyword."
+
+["pipelex/cli/commands/codegen/check_cmd.py::_print_report"]
+param = "report"
+rationale = "Verb-object: prints the report; root stays keyword."
+
+["pipelex/cli/commands/doctor_cmd.py::check_kit_template_exists"]
+param = "backend_name"
+rationale = "Verb–object: checks the backend_name; single operand."
+
+["pipelex/cli/commands/doctor_cmd.py::replace_backend_file"]
+param = "backend_name"
+rationale = "Replaces the named backend's file; single operand."
+
+["pipelex/cli/commands/fix/_diff_sandbox.py::PreviewSandbox.to_original"]
+param = "path_str"
+rationale = "Single-operand conversion: maps a sandbox path back to its original."
+
+["pipelex/cli/commands/fix/_diff_sandbox.py::mirror_bundle_for_preview"]
+param = "entry_path"
+rationale = "Verb-object: mirrors the bundle at entry_path; the rest is context."
+
+["pipelex/cli/commands/fix/_fix_core.py::_remap_result_to_originals"]
+param = "result"
+rationale = "Verb-object: remaps the result; sandbox is context."
+
+["pipelex/cli/commands/fix/_fix_core.py::_remap_validation_error_to_original"]
+param = "item"
+rationale = "Verb-object: remaps the error item; sandbox is context."
+
+["pipelex/cli/commands/fix/_fix_core.py::execute_fix"]
+param = "bundle_path"
+rationale = "Verb-object: fixes the bundle at bundle_path; options stay keyword."
+
+["pipelex/cli/commands/graph_cmd.py::_do_graph_render"]
+param = "input_file"
+rationale = "Renders the input file to a graph; single operand."
+
+["pipelex/cli/commands/init/backends.py::disable_gateway_backend"]
+param = "backends_toml_path"
+rationale = "Edits the backends TOML at the path to disable the gateway; single operand."
+
+["pipelex/cli/commands/init/backends.py::get_selected_backend_keys"]
+param = "backends_toml_path"
+rationale = "Derives from the backends_toml_path; single operand."
+
+["pipelex/cli/commands/init/backends.py::update_backends_in_toml"]
+param = "toml_doc"
+rationale = "Mutates the given TOML document in place; single operand."
+
+["pipelex/cli/commands/init/command.py::init_cmd"]
+param = "focus"
+rationale = "The init focus is the single operand; flags keyword-only."
+
+["pipelex/cli/commands/init/credentials.py::get_required_vars_for_enabled_backends"]
+param = "backends_toml_path"
+rationale = "Derives from the backends_toml_path; single operand."
+
+["pipelex/cli/commands/init/credentials.py::read_env_file"]
+param = "env_path"
+rationale = "File op keyed by the env_path path; single operand."
+
+["pipelex/cli/commands/init/credentials.py::write_env_file"]
+param = "env_path"
+rationale = "File op keyed by the env_path path; single operand."
+
+["pipelex/cli/commands/init/ide_extension.py::_install_extension"]
+param = "ide_name"
+rationale = "Installs the extension for the named IDE; single operand."
+
+["pipelex/cli/commands/init/ide_extension.py::_is_extension_installed"]
+param = "cmd"
+rationale = "Operates on the cmd; single operand."
+
+["pipelex/cli/commands/init/routing.py::customize_routing_profile"]
+param = "selected_backend_keys"
+rationale = "Customizes the routing profile from the selected backend keys; single operand."
+
+["pipelex/cli/commands/init/ui/backends_ui.py::build_backend_selection_panel"]
+param = "backend_options"
+rationale = "Derives from the backend_options; single operand."
+
+["pipelex/cli/commands/init/ui/backends_ui.py::get_backend_options_from_toml"]
+param = "template_path"
+rationale = "Derives from the template_path; single operand."
+
+["pipelex/cli/commands/init/ui/backends_ui.py::get_currently_enabled_backends"]
+param = "backends_toml_path"
+rationale = "Derives from the backends_toml_path; single operand."
+
+["pipelex/cli/commands/init/ui/routing_ui.py::build_fallback_order_panel"]
+param = "remaining_backends"
+rationale = "Derives from the remaining_backends; single operand."
+
+["pipelex/cli/commands/init/ui/routing_ui.py::build_primary_backend_panel"]
+param = "backend_keys"
+rationale = "Derives from the backend_keys; single operand."
+
+["pipelex/cli/commands/login/command.py::save_api_key"]
+param = "api_key"
+rationale = "File op keyed by the api_key path; single operand."
+
+["pipelex/cli/commands/login/command.py::serve_until_callback"]
+param = "server"
+rationale = "Serves the HTTP server until the callback fires; single operand."
+
+["pipelex/cli/commands/run/_inputs_file_loader.py::_convert_temporal_inputs"]
+param = "inputs_dict"
+rationale = "Single-operand conversion of the inputs dict."
+
+["pipelex/cli/commands/run/_inputs_file_loader.py::load_inputs_dict_from_path"]
+param = "path"
+rationale = "Factory from source: loads the inputs dict from the file at path."
+
+["pipelex/cli/commands/run/_inputs_file_loader.py::resolve_inputs_arg_against_dir"]
+param = "inputs_arg"
+rationale = "Verb-object: resolves the inputs argument; base_dir is context."
+
+["pipelex/cli/commands/run/_inputs_path_resolver.py::resolve_inputs_paths"]
+param = "inputs_dict"
+rationale = "Operates on the inputs_dict; single operand."
+
+["pipelex/cli/commands/run/_inputs_path_resolver.py::resolve_url_in_value"]
+param = "value"
+rationale = "Operates on the value; single operand."
+
+["pipelex/cli/commands/show_cmd.py::do_show_pipe"]
+param = "pipe_code"
+rationale = "Shows the pipe identified by pipe_code; single operand."
+
+["pipelex/cli/commands/update_cmd.py::_action_description"]
+param = "status"
+rationale = "Renders the status; single operand."
+
+["pipelex/cli/commands/update_cmd.py::_apply_updates"]
+param = "deck_dir"
+rationale = "Applies deck updates in the deck dir; single operand."
+
+["pipelex/cli/commands/update_cmd.py::_print_status_table"]
+param = "report"
+rationale = "Renders the deck-sync report; single operand."
+
+["pipelex/cli/commands/update_cmd.py::_summary_panel"]
+param = "message"
+rationale = "Renders the message; single operand."
+
+["pipelex/cli/commands/which_cmd.py::do_which_pipe"]
+param = "pipe_code"
+rationale = "Locates the pipe identified by pipe_code; single operand."
+
+["pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py::_package_of"]
+param = "key_or_path"
+rationale = "Verb–object: derives the report-grouping package of the key/path; single operand."
+
+["pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py::_print_report"]
+param = "violations"
+rationale = "Verb–object: prints the inventory report of these violations; options are keyword-only."
+
+["pipelex/cli/dev_cli/commands/check_urls_cmd.py::check_all_urls_async"]
+param = "url_pairs"
+rationale = "Verb–object: checks the url_pairs; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/core.py::_normalize_pattern"]
+param = "pattern"
+rationale = "Guard/CLI helper: operates on the pattern; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/core.py::_pattern_to_regex"]
+param = "pattern"
+rationale = "Guard/CLI helper: operates on the pattern; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/core.py::build_plan_packets"]
+param = "manifest"
+rationale = "Derives from the manifest; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/core.py::compute_contract_digest"]
+param = "contract"
+rationale = "Guard/CLI helper: operates on the contract; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/core.py::compute_current_digest"]
+param = "contract"
+rationale = "Guard/CLI helper: operates on the contract; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/core.py::find_dead_patterns"]
+param = "files"
+rationale = "Looks up from the files; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/core.py::find_issues"]
+param = "manifest"
+rationale = "Looks up from the manifest; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/core.py::match_files"]
+param = "files"
+rationale = "Guard/CLI helper: operates on the files; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/core.py::match_pattern"]
+param = "path"
+rationale = "Guard/CLI helper: operates on the path; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/drift_cmd.py::_issue_message"]
+param = "issue"
+rationale = "Operates on the issue; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/drift_cmd.py::_render_packet_markdown"]
+param = "packet"
+rationale = "Renders the packet; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/drift_cmd.py::_resolve_repo_root"]
+param = "repo_root"
+rationale = "Operates on the repo_root; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/drift_cmd.py::_run_verify_commands"]
+param = "commands"
+rationale = "Guard/CLI helper: operates on the commands; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/drift_cmd.py::_warn_uncovered_working_tree"]
+param = "contract"
+rationale = "Warns about the contract's uncovered working tree; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/drift_cmd.py::drift_ack_cmd"]
+param = "contract_id"
+rationale = "Acks the drift contract identified by id; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/drift_cmd.py::drift_plan_cmd"]
+param = "contract_id"
+rationale = "Plans the drift contract identified by id (None = all); single operand."
+
+["pipelex/cli/dev_cli/commands/drift/git_adapter.py::_run_git"]
+param = "args"
+rationale = "Guard/CLI helper: operates on the args; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/git_adapter.py::get_git_user_name"]
+param = "repo_root"
+rationale = "Derives from the repo_root; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/git_adapter.py::read_staged_files"]
+param = "repo_root"
+rationale = "File op keyed by the repo_root path; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/git_adapter.py::read_unstaged_modified"]
+param = "repo_root"
+rationale = "File op keyed by the repo_root path; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/git_adapter.py::read_untracked"]
+param = "repo_root"
+rationale = "File op keyed by the repo_root path; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/models.py::ack_file_path"]
+param = "repo_root"
+rationale = "File op keyed by the repo_root path; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/models.py::load_ack"]
+param = "ack_path"
+rationale = "File op keyed by the ack_path path; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/models.py::load_all_acks"]
+param = "repo_root"
+rationale = "File op keyed by the repo_root path; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/models.py::load_manifest"]
+param = "repo_root"
+rationale = "File op keyed by the repo_root path; single operand."
+
+["pipelex/cli/dev_cli/commands/drift/models.py::save_ack"]
+param = "ack"
+rationale = "File op keyed by the ack path; single operand."
+
+["pipelex/cli/dev_cli/commands/gateway_models_generator.py::extract_reference_data"]
+param = "model_specs"
+rationale = "Extracts from the model_specs; single operand."
+
+["pipelex/cli/dev_cli/commands/gateway_models_generator.py::generate_markdown_table"]
+param = "models"
+rationale = "Renders the models as a markdown table; single operand."
+
+["pipelex/cli/dev_cli/commands/gateway_models_generator.py::generate_markdown_table.sort_by_preferred"]
+param = "items"
+rationale = "Sorts the items by the preferred order; single operand."
+
+["pipelex/cli/dev_cli/commands/gateway_models_generator.py::generate_pure_markdown_list"]
+param = "models"
+rationale = "Renders the models as a plain markdown list; single operand."
+
+["pipelex/cli/dev_cli/commands/gateway_models_generator.py::generate_pure_markdown_list.sort_by_preferred"]
+param = "items"
+rationale = "Sorts the items by the preferred order; single operand."
+
+["pipelex/cli/dev_cli/commands/gateway_models_generator.py::generate_reference_markdown"]
+param = "model_specs"
+rationale = "Renders the model_specs; single operand."
+
+["pipelex/cli/dev_cli/commands/gateway_models_generator.py::generate_reference_pure_markdown"]
+param = "model_specs"
+rationale = "Renders the model_specs; single operand."
+
+["pipelex/cli/dev_cli/commands/gateway_models_generator.py::normalize_for_comparison"]
+param = "content"
+rationale = "Normalizes the content for comparison; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_Collector._visit_function"]
+param = "node"
+rationale = "Guard/CLI helper: operates on the node; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_annotation_has_typer_metadata"]
+param = "annotation"
+rationale = "Guard/CLI helper: operates on the annotation; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_callee_name"]
+param = "func"
+rationale = "Guard/CLI helper: operates on the func; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_decorator_matches_carveout"]
+param = "decorator"
+rationale = "Guard/CLI helper: operates on the decorator; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_def_line_has_escape_hatch"]
+param = "node"
+rationale = "Guard/CLI helper: operates on the node; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_evaluate_def"]
+param = "node"
+rationale = "Guard/CLI helper: operates on the node; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_find_fix_records_in_source"]
+param = "source"
+rationale = "Looks up from the source; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_fix_insertion_point"]
+param = "node"
+rationale = "Guard/CLI helper: operates on the node; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_has_carveout_decorator"]
+param = "node"
+rationale = "Guard/CLI helper: operates on the node; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_has_typer_param_annotation"]
+param = "node"
+rationale = "Guard/CLI helper: operates on the node; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_is_dunder"]
+param = "name"
+rationale = "Operates on the name; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_is_literal_type_name"]
+param = "annotation"
+rationale = "Predicate on its single operand: is this annotation node a bare bool/int/float name."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_is_literal_typed_annotation"]
+param = "annotation"
+rationale = "Predicate on its single operand: does this annotation denote a literal type."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_iter_subscript_metadata"]
+param = "annotation"
+rationale = "Guard/CLI helper: operates on the annotation; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_positional_or_keyword_count"]
+param = "node"
+rationale = "Guard/CLI helper: operates on the node; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_qualify"]
+param = "name"
+rationale = "Guard/CLI helper: operates on the name; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_split_source_lines"]
+param = "source"
+rationale = "Guard/CLI helper: operates on the source; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_subject_param"]
+param = "node"
+rationale = "Verb–object: extracts the subject param of the def node; the node is the single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::_union_members"]
+param = "annotation"
+rationale = "Verb–object: flattens the annotation into its union members; single obvious operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::collect_all_violations"]
+param = "root"
+rationale = "Guard/CLI helper: operates on the root; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::collect_def_infos_in_source"]
+param = "source"
+rationale = "Guard/CLI helper: operates on the source; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::collect_violations_for_files"]
+param = "paths"
+rationale = "Guard/CLI helper: operates on the paths; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::find_violations_in_source"]
+param = "source"
+rationale = "Looks up from the source; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::fix_all_violations"]
+param = "root"
+rationale = "Guard/CLI helper: operates on the root; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::fix_source"]
+param = "source"
+rationale = "Guard/CLI helper: operates on the source; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::iter_source_files"]
+param = "root"
+rationale = "Guard/CLI helper: operates on the root; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::main"]
+param = "argv"
+rationale = "Guard/CLI helper: operates on the argv; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::module_qname_for"]
+param = "path"
+rationale = "Guard/CLI helper: operates on the path; single operand."
+
+["pipelex/cli/dev_cli/commands/keyword_only_guard.py::relative_source_path"]
+param = "path"
+rationale = "Guard/CLI helper: operates on the path; single operand."
+
+["pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py::_display_summary"]
+param = "availability"
+rationale = "Renders the availability; single operand."
+
+["pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py::_extract_models_from_backend_toml"]
+param = "backend_path"
+rationale = "Extracts from the backend_path; single operand."
+
+["pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py::_filter_models_by_profile"]
+param = "availability"
+rationale = "Filters the availability map by profile; single operand."
+
+["pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py::_generate_fixtures_python"]
+param = "combo_pairs"
+rationale = "Generates fixture source from the combo pairs; single operand."
+
+["pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py::_load_test_profile"]
+param = "profile_name"
+rationale = "Loads the named test profile; single operand."
+
+["pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py::_process_collections_from_toml"]
+param = "collections_raw"
+rationale = "Processes the raw collections payload; single operand."
+
+["pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py::_resolve_model_list"]
+param = "raw_list"
+rationale = "Operates on the raw_list; single operand."
+
+["pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py::preprocess_test_models_cmd"]
+param = "profile"
+rationale = "Preprocesses test models for the named profile; single operand."
+
+["pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py::_fetch"]
+param = "url"
+rationale = "Fetches the URL; single operand."
+
+["pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py::_python_string_literal"]
+param = "value"
+rationale = "Renders the value as a Python string literal; single operand."
+
+["pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py::_sha384_sri"]
+param = "payload"
+rationale = "Computes the SRI hash of the payload; single operand."
+
+["pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py::_validate_sri"]
+param = "value"
+rationale = "Validates the SRI value; single operand."
+
+["pipelex/cli/dev_cli/commands/subject_grant_cmd.py::_fail"]
+param = "message"
+rationale = "Verb–object: fails with the given message; single operand, call sites read as a sentence."
+
+["pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py::_display_result"]
+param = "result"
+rationale = "Renders the result; single operand."
+
+["pipelex/cli/dev_cli/commands/sync_main_config_cmd.py::_display_sync_result"]
+param = "result"
+rationale = "Renders the result; single operand."
+
+["pipelex/cli/dev_cli/commands/sync_main_config_cmd.py::_format_value"]
+param = "value"
+rationale = "Renders the value; single operand."
+
+["pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py::_all_references_up_to_date"]
+param = "reference_files"
+rationale = "Predicate: whether the reference files are current; single operand."
+
+["pipelex/cli/error_handlers.py::_validation_category_header"]
+param = "category"
+rationale = "Noun-named derivation: the header text for the category; single operand."
+
+["pipelex/cli/error_handlers.py::handle_gateway_api_key_missing_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/error_handlers.py::handle_gateway_do_not_track_conflict_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/error_handlers.py::handle_gateway_terms_not_accepted_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/error_handlers.py::handle_gateway_unknown_model_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/error_handlers.py::handle_inference_setup_required_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/error_handlers.py::handle_model_availability_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/error_handlers.py::handle_model_choice_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/error_handlers.py::handle_model_deck_preset_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/error_handlers.py::handle_remote_config_unavailable_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/error_handlers.py::handle_remote_config_validation_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/error_handlers.py::handle_telemetry_config_validation_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/error_handlers.py::handle_validate_bundle_error"]
+param = "exc"
+rationale = "Error handler: the exc is the single operand handled."
+
+["pipelex/cli/installed_methods.py::discover_method_at"]
+param = "method_dir"
+rationale = "Looks up from the method_dir; single operand."
+
+["pipelex/cli/installed_methods.py::discover_methods_from_library_dirs"]
+param = "library_dirs"
+rationale = "Looks up from the library_dirs; single operand."
+
+["pipelex/cli/installed_methods.py::find_method_by_full_address"]
+param = "full_address"
+rationale = "Looks up from the full_address; single operand."
+
+["pipelex/cli/installed_methods.py::find_method_by_name"]
+param = "method_name"
+rationale = "Looks up from the method_name; single operand."
+
+["pipelex/cli/method_resolver.py::_find_method_by_exported_pipe"]
+param = "pipe_code"
+rationale = "Looks up from the pipe_code; single operand."
+
+["pipelex/cli/method_resolver.py::_get_all_exported_pipes"]
+param = "method"
+rationale = "Looks up from the method; single operand."
+
+["pipelex/cli/method_resolver.py::is_github_url"]
+param = "target"
+rationale = "Operates on the target; single operand."
+
+["pipelex/cli/method_resolver.py::is_local_path"]
+param = "target"
+rationale = "Operates on the target; single operand."
+
+["pipelex/cli/method_resolver.py::parse_github_url"]
+param = "url"
+rationale = "Parses the url; single operand."
+
+["pipelex/cli/method_resolver.py::resolve_method_from_path"]
+param = "method_path"
+rationale = "Operates on the method_path; single operand."
+
+["pipelex/cli/method_resolver.py::resolve_method_from_url"]
+param = "url"
+rationale = "Operates on the url; single operand."
+
+["pipelex/cli/method_resolver.py::resolve_method_target"]
+param = "method_name"
+rationale = "Operates on the method_name; single operand."
+
+["pipelex/cli/method_resolver.py::resolve_pipe_from_exports"]
+param = "pipe_code"
+rationale = "Operates on the pipe_code; single operand."
+
+["pipelex/codegen/check.py::_read_text_or_none"]
+param = "path"
+rationale = "Verb-object: reads the file at path; single operand."
+
+["pipelex/codegen/crate_encoding.py::_dump_object"]
+param = "obj"
+rationale = "Single-operand conversion of the model."
+
+["pipelex/codegen/crate_encoding.py::_encoding_payload"]
+param = "crate"
+rationale = "Noun-named derivation: the encoding payload for the crate; single operand."
+
+["pipelex/codegen/crate_encoding.py::encode_crate"]
+param = "crate"
+rationale = "Verb-object: encodes the crate; encoding is a mode and stays keyword."
+
+["pipelex/codegen/crate_encoding.py::encode_crate_json"]
+param = "crate"
+rationale = "Verb-object: encodes the crate; single operand."
+
+["pipelex/codegen/crate_encoding.py::encode_crate_toml"]
+param = "crate"
+rationale = "Verb-object: encodes the crate; single operand."
+
+["pipelex/codegen/emission.py::_previous_tracked_paths"]
+param = "lock_path"
+rationale = "Noun-named derivation: reads the tracked paths from the lock file at lock_path."
+
+["pipelex/codegen/emission.py::build_stamped_projection"]
+param = "emitted"
+rationale = "Factory from source: builds the projection from the emitted files; stamp fields stay keyword."
+
+["pipelex/codegen/emission.py::write_stamped_projection"]
+param = "emitted"
+rationale = "Verb-object: writes the projection built from the emitted files; the rest stays keyword."
+
+["pipelex/codegen/emitters/naming.py::_ts_symbols_are_free"]
+param = "type_name"
+rationale = "Predicate on the type name; used_symbols is context."
+
+["pipelex/codegen/emitters/naming.py::allocate_ts_type_names"]
+param = "library"
+rationale = "Single-operand transformation: derives the name mapping over the whole library."
+
+["pipelex/codegen/emitters/naming.py::runtime_to_emitted_class_names"]
+param = "library"
+rationale = "Single-operand transformation: derives the class-name mapping over the whole library."
+
+["pipelex/codegen/emitters/naming.py::snake_to_pascal"]
+param = "name"
+rationale = "Single-operand conversion of the name."
+
+["pipelex/codegen/emitters/python_common.py::class_docstring"]
+param = "description"
+rationale = "Noun-named derivation: builds the docstring from the description; extras stay keyword."
+
+["pipelex/codegen/emitters/python_common.py::escape_py_string"]
+param = "value"
+rationale = "Single-operand conversion of the value."
+
+["pipelex/codegen/emitters/python_common.py::field_line"]
+param = "field"
+rationale = "Noun-named derivation: the source line for the field; annotation stays keyword."
+
+["pipelex/codegen/emitters/python_common.py::format_default_value"]
+param = "value"
+rationale = "Single-operand formatting of the value."
+
+["pipelex/codegen/emitters/python_common.py::order_by_base"]
+param = "concepts"
+rationale = "Verb-object: orders the concepts; in_module is context."
+
+["pipelex/codegen/emitters/python_common.py::order_by_base.visit"]
+param = "concept"
+rationale = "Visitor: visits the concept; single operand."
+
+["pipelex/codegen/emitters/python_pydantic.py::_annotation"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the annotation for the resolved type; context stays keyword."
+
+["pipelex/codegen/emitters/python_pydantic.py::_base_class"]
+param = "concept"
+rationale = "Noun-named derivation: the base class for the concept; context stays keyword."
+
+["pipelex/codegen/emitters/python_pydantic.py::_concept_annotation"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the annotation for the resolved type; context stays keyword."
+
+["pipelex/codegen/emitters/python_pydantic.py::_render_class"]
+param = "concept"
+rationale = "Verb-object: renders the concept; context stays keyword."
+
+["pipelex/codegen/emitters/python_pydantic.py::_render_field"]
+param = "concept_field"
+rationale = "Verb-object: renders the field; context stays keyword."
+
+["pipelex/codegen/emitters/python_pydantic.py::emit_python_pydantic"]
+param = "library"
+rationale = "Verb-object: emits from the resolved library; single operand."
+
+["pipelex/codegen/emitters/python_structures.py::_annotation"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the annotation for the resolved type; context stays keyword."
+
+["pipelex/codegen/emitters/python_structures.py::_base_class"]
+param = "concept"
+rationale = "Noun-named derivation: the base class for the concept; context stays keyword."
+
+["pipelex/codegen/emitters/python_structures.py::_concept_annotation"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the annotation for the resolved type; context stays keyword."
+
+["pipelex/codegen/emitters/python_structures.py::_native_class"]
+param = "concept_ref"
+rationale = "Noun-named derivation: parses the concept_ref and derives its native structure class; imports is an out-param."
+
+["pipelex/codegen/emitters/python_structures.py::_render_class"]
+param = "concept"
+rationale = "Verb-object: renders the concept; context stays keyword."
+
+["pipelex/codegen/emitters/python_structures.py::_render_field"]
+param = "concept_field"
+rationale = "Verb-object: renders the field; context stays keyword."
+
+["pipelex/codegen/emitters/python_structures.py::emit_python_structures"]
+param = "library"
+rationale = "Verb-object: emits from the resolved library; single operand."
+
+["pipelex/codegen/emitters/ts_zod.py::_binder_pair"]
+param = "type_name"
+rationale = "Noun-named derivation: encodes the type name into its parse/serialize pair."
+
+["pipelex/codegen/emitters/ts_zod.py::_concept_dependencies"]
+param = "concept"
+rationale = "Noun-named derivation: the dependency refs of the concept; single operand."
+
+["pipelex/codegen/emitters/ts_zod.py::_concept_schema"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the schema expr for the resolved type; context stays keyword."
+
+["pipelex/codegen/emitters/ts_zod.py::_concept_type"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the TS type for the resolved type; context stays keyword."
+
+["pipelex/codegen/emitters/ts_zod.py::_concept_type_expr"]
+param = "concept"
+rationale = "Noun-named derivation: the type expr for the concept; context stays keyword."
+
+["pipelex/codegen/emitters/ts_zod.py::_emit_binder"]
+param = "concepts"
+rationale = "Verb-object: emits the binder for the concepts; mapping stays keyword."
+
+["pipelex/codegen/emitters/ts_zod.py::_find_recursive_concept_refs"]
+param = "concepts"
+rationale = "Single-operand analysis over the concepts collection."
+
+["pipelex/codegen/emitters/ts_zod.py::_format_default_value"]
+param = "value"
+rationale = "Single-operand formatting of the value."
+
+["pipelex/codegen/emitters/ts_zod.py::_jsdoc"]
+param = "description"
+rationale = "Noun-named derivation: builds the JSDoc from the description; extras stay keyword."
+
+["pipelex/codegen/emitters/ts_zod.py::_render_field"]
+param = "concept_field"
+rationale = "Verb-object: renders the field; context stays keyword."
+
+["pipelex/codegen/emitters/ts_zod.py::_render_schema"]
+param = "concept"
+rationale = "Verb-object: renders the concept's schema; context stays keyword."
+
+["pipelex/codegen/emitters/ts_zod.py::_render_type_field"]
+param = "concept_field"
+rationale = "Verb-object: renders the field's type line; context stays keyword."
+
+["pipelex/codegen/emitters/ts_zod.py::_resolved_type_concept_refs"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the concept refs of the resolved type; single operand."
+
+["pipelex/codegen/emitters/ts_zod.py::_sanitize_jsdoc_text"]
+param = "value"
+rationale = "Single-operand sanitization of the text."
+
+["pipelex/codegen/emitters/ts_zod.py::_schema_expr"]
+param = "concept"
+rationale = "Noun-named derivation: the schema expr for the concept; context stays keyword."
+
+["pipelex/codegen/emitters/ts_zod.py::_ts_type"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the TS type for the resolved type; context stays keyword."
+
+["pipelex/codegen/emitters/ts_zod.py::_zod_type"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the zod expr for the resolved type; context stays keyword."
+
+["pipelex/codegen/emitters/ts_zod.py::emit_ts_zod"]
+param = "library"
+rationale = "Verb-object: emits from the resolved library; single operand."
+
+["pipelex/codegen/emitters/types_emitter.py::emit_types"]
+param = "crate"
+rationale = "Verb-object: emits types from the crate; target is a mode and stays keyword."
+
+["pipelex/codegen/lock.py::_raise_path_error"]
+param = "path"
+rationale = "Error raiser: the offending path is the single operand reported; reason stays keyword."
+
+["pipelex/codegen/lock.py::encode_lock"]
+param = "lock"
+rationale = "Single-operand conversion of the lock."
+
+["pipelex/codegen/lock.py::load_lock"]
+param = "lock_path"
+rationale = "Factory from source: loads the lock from the file at lock_path."
+
+["pipelex/codegen/lock.py::validate_artifact_path"]
+param = "path"
+rationale = "Validator: the path is the single operand validated."
+
+["pipelex/codegen/lock.py::validate_artifact_paths"]
+param = "paths"
+rationale = "Validator: the paths are the operand validated."
+
+["pipelex/codegen/native_expansion.py::_annotation_to_blueprint"]
+param = "annotation"
+rationale = "Single-operand conversion of the annotation; description stays keyword."
+
+["pipelex/codegen/native_expansion.py::_is_nested_model"]
+param = "annotation"
+rationale = "Predicate on the annotation; single operand."
+
+["pipelex/codegen/native_expansion.py::_is_number_union"]
+param = "annotation"
+rationale = "Predicate on the annotation; single operand."
+
+["pipelex/codegen/native_expansion.py::_list_blueprint"]
+param = "list_annotation"
+rationale = "Noun-named derivation from the list annotation; the rest stays keyword."
+
+["pipelex/codegen/native_expansion.py::_native_code_for_content_class"]
+param = "annotation"
+rationale = "Noun-named derivation: inspects the annotation for its native code; single operand."
+
+["pipelex/codegen/native_expansion.py::_scalar_field_type"]
+param = "annotation"
+rationale = "Noun-named derivation: inspects the annotation for its scalar type; single operand."
+
+["pipelex/codegen/native_expansion.py::_strip_optional"]
+param = "annotation"
+rationale = "Single-operand transformation of the annotation."
+
+["pipelex/codegen/native_expansion.py::collect_native_refs_from_structure"]
+param = "structure"
+rationale = "Single-operand analysis over the structure mapping."
+
+["pipelex/codegen/native_expansion.py::materialize_native_concept"]
+param = "native_code"
+rationale = "Factory from source: materializes the concept identified by the native code."
+
+["pipelex/codegen/native_expansion.py::reflect_native_structure"]
+param = "native_code"
+rationale = "Noun-named derivation: the reflected structure for the native code; single operand."
+
+["pipelex/codegen/resolved_concepts.py::_resolve_concept"]
+param = "concept_ref"
+rationale = "Verb-object: resolves the concept_ref; the rest is context."
+
+["pipelex/codegen/resolved_concepts.py::resolve_concepts_from_crate"]
+param = "crate"
+rationale = "Factory from source: resolves the whole crate into a library."
+
+["pipelex/codegen/resolved_fields.py::_resolve_concept"]
+param = "concept_ref"
+rationale = "Verb-object: resolves the concept_ref; local_domain is context."
+
+["pipelex/codegen/resolved_fields.py::_resolve_list_item"]
+param = "blueprint"
+rationale = "Verb-object: resolves the list-item blueprint; local_domain is context."
+
+["pipelex/codegen/resolved_fields.py::_resolve_scalar_type_name"]
+param = "type_name"
+rationale = "Verb-object: resolves the type name; the rest is context."
+
+["pipelex/codegen/resolved_fields.py::_resolve_type"]
+param = "blueprint"
+rationale = "Verb-object: resolves the blueprint's type; local_domain is context."
+
+["pipelex/codegen/resolved_fields.py::iter_imprecision_reasons"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the imprecision reasons of the resolved type; single operand."
+
+["pipelex/codegen/resolved_fields.py::resolve_structure_fields"]
+param = "structure_blueprint"
+rationale = "Verb-object: resolves the structure blueprint's fields; local_domain is context."
+
+["pipelex/codegen/stamp.py::_kind_from_value"]
+param = "value"
+rationale = "Single-operand parse of the value."
+
+["pipelex/codegen/stamp.py::_parse_fields"]
+param = "header_region"
+rationale = "Parser: the header region is the operand; comment_prefix is context."
+
+["pipelex/codegen/stamp.py::_parse_options"]
+param = "options_raw"
+rationale = "Parser: the raw options string is the single operand."
+
+["pipelex/codegen/stamp.py::_parse_projection"]
+param = "projection"
+rationale = "Parser: the projection string is the single operand."
+
+["pipelex/codegen/stamp.py::_target_from_value"]
+param = "value"
+rationale = "Single-operand parse of the value."
+
+["pipelex/codegen/stamp.py::apply_stamp"]
+param = "body"
+rationale = "Verb-object: stamps the body; stamp fields stay keyword."
+
+["pipelex/codegen/stamp.py::comment_prefix_for"]
+param = "filename"
+rationale = "Noun-named derivation: the comment prefix for the filename (suffix-encoded)."
+
+["pipelex/codegen/stamp.py::compute_content_hash"]
+param = "body"
+rationale = "Noun-named derivation: the hash of the body; single operand."
+
+["pipelex/codegen/stamp.py::has_stamp"]
+param = "text"
+rationale = "Predicate on the text; comment_prefix is context."
+
+["pipelex/codegen/stamp.py::parse_stamped"]
+param = "text"
+rationale = "Parser: the text is the operand; comment_prefix is context."
+
+["pipelex/cogt/config_cogt.py::ImgGenConfig.get_num_inference_steps"]
+param = "model_name"
+rationale = "Keyed accessor by the model_name; single operand."
+
+["pipelex/cogt/config_cogt.py::LLMConfig.get_reasoning_budget"]
+param = "prompting_target"
+rationale = "Keyed accessor by the prompting_target; single operand."
+
+["pipelex/cogt/config_cogt.py::LLMConfig.get_template"]
+param = "template_name"
+rationale = "Keyed accessor by the template_name; single operand."
+
+["pipelex/cogt/content_generation/assignment_models.py::LLMAssignment.clone_with_new_prompt"]
+param = "new_prompt"
+rationale = "Operates on the new_prompt; single operand (qualifiers keyword-only)."
+
+["pipelex/cogt/content_generation/assignment_models.py::ObjectAssignment.make_for_class"]
+param = "object_class"
+rationale = "Factory from source: builds the result from the object_class; single operand."
+
+["pipelex/cogt/content_generation/assignment_models.py::SearchObjectAssignment.make_for_class"]
+param = "output_class"
+rationale = "Factory from source: builds the result from the output_class; single operand."
+
+["pipelex/cogt/content_generation/content_generator.py::_revalidate_against_object_class"]
+param = "raw_obj"
+rationale = "Consumes the raw_obj; single operand."
+
+["pipelex/cogt/content_generation/content_generator_protocol.py::ContentGeneratorProtocol.make_search_sourced_answer"]
+param = "search_assignment"
+rationale = "Factory from source: builds the result from the search_assignment; single operand."
+
+["pipelex/cogt/content_generation/content_generator_protocol.py::update_job_metadata"]
+param = "func"
+rationale = "Decorator: wraps the single func operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::_dry_image_content"]
+param = "image_url"
+rationale = "Consumes the image_url; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::_dry_report_func"]
+param = "cogt_run_params"
+rationale = "Consumes the cogt_run_params; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::_leaf_gen_object"]
+param = "object_assignment"
+rationale = "Consumes the object_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::_leaf_gen_object_list"]
+param = "object_assignment"
+rationale = "Consumes the object_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::_nb_list_items"]
+param = "object_assignment"
+rationale = "Consumes the object_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::_reconstruct_object_class"]
+param = "object_assignment"
+rationale = "Consumes the object_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::build_mock_object"]
+param = "model_class"
+rationale = "Factory from source: builds the result from the model_class; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::build_mock_objects"]
+param = "model_class"
+rationale = "Factory from source: builds the result from the model_class; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::dry_extract_page_contents"]
+param = "extract_assignment"
+rationale = "Consumes the extract_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::dry_img_gen_image_contents"]
+param = "img_gen_assignment"
+rationale = "Consumes the img_gen_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::dry_llm_gen_object"]
+param = "object_assignment"
+rationale = "Consumes the object_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::dry_llm_gen_object_list"]
+param = "object_assignment"
+rationale = "Consumes the object_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::dry_llm_gen_text"]
+param = "llm_assignment"
+rationale = "Consumes the llm_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::dry_render_page_views"]
+param = "render_assignment"
+rationale = "Consumes the render_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::dry_search_gen_sourced_answer"]
+param = "search_assignment"
+rationale = "Consumes the search_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::dry_search_gen_structured"]
+param = "search_object_assignment"
+rationale = "Consumes the search_object_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::dry_templating_gen_text"]
+param = "templating_assignment"
+rationale = "Consumes the templating_assignment; single operand."
+
+["pipelex/cogt/content_generation/dry_mock.py::report_dry_llm_job"]
+param = "job_metadata"
+rationale = "Positional-Callable reporter protocol (_ReportLLMJobFunc.__call__): job_metadata stays positional to match report_func(job_metadata, ...)."
+
+["pipelex/cogt/content_generation/dry_mock.py::report_mock_usage_llm_job"]
+param = "job_metadata"
+rationale = "Positional-Callable reporter protocol (_ReportLLMJobFunc.__call__): job_metadata stays positional to match report_func(job_metadata, ...)."
+
+["pipelex/cogt/content_generation/dry_mock.py::stamp_mock_main_coordination"]
+param = "items"
+rationale = "Consumes the items; single operand."
+
+["pipelex/cogt/content_generation/dry_run_factory.py::DryRunFactory._create_nested_factory"]
+param = "nested_class"
+rationale = "Builds a nested mock factory for the class; single operand."
+
+["pipelex/cogt/content_generation/dry_run_factory.py::DryRunFactory._detect_examples_constraints"]
+param = "object_class"
+rationale = "Inspects the object class for example constraints; single operand."
+
+["pipelex/cogt/content_generation/dry_run_factory.py::DryRunFactory._detect_format_constraints"]
+param = "object_class"
+rationale = "Inspects the object class for format constraints; single operand."
+
+["pipelex/cogt/content_generation/dry_run_factory.py::DryRunFactory._detect_literal_fields"]
+param = "object_class"
+rationale = "Inspects the object class for literal fields; single operand."
+
+["pipelex/cogt/content_generation/dry_run_factory.py::DryRunFactory._extract_types_from_annotation"]
+param = "annotation"
+rationale = "Extracts from the annotation; single operand."
+
+["pipelex/cogt/content_generation/dry_run_factory.py::DryRunFactory._find_nested_base_model_classes"]
+param = "object_class"
+rationale = "Inspects the object class for nested models; single operand."
+
+["pipelex/cogt/content_generation/dry_run_factory.py::DryRunFactory._get_examples_from_field"]
+param = "field_info"
+rationale = "Keyed accessor by the field_info; single operand."
+
+["pipelex/cogt/content_generation/dry_run_factory.py::DryRunFactory._get_literal_values_from_annotation"]
+param = "annotation"
+rationale = "Keyed accessor by the annotation; single operand."
+
+["pipelex/cogt/content_generation/dry_run_factory.py::DryRunFactory._get_mock_format_from_field"]
+param = "field_info"
+rationale = "Keyed accessor by the field_info; single operand."
+
+["pipelex/cogt/content_generation/dry_run_factory.py::DryRunFactory._make_example_picker"]
+param = "examples"
+rationale = "Factory from source: builds the result from the examples; single operand."
+
+["pipelex/cogt/content_generation/dry_run_factory.py::DryRunFactory.make_dry_run_factory"]
+param = "object_class"
+rationale = "Factory from source: builds the result from the object_class; single operand."
+
+["pipelex/cogt/content_generation/exceptions.py::DryRunMockBuildError.for_object_class"]
+param = "object_class_name"
+rationale = "Factory from source: builds the result from the object_class_name; single operand."
+
+["pipelex/cogt/content_generation/exceptions.py::DryRunObjectFidelityError.for_object_class"]
+param = "object_class_name"
+rationale = "Factory from source: builds the result from the object_class_name; single operand."
+
+["pipelex/cogt/content_generation/extract_generate.py::extract_gen_pages"]
+param = "extract_assignment"
+rationale = "Extracts from the extract_assignment; single operand."
+
+["pipelex/cogt/content_generation/extract_generate.py::extract_gen_pages_and_store"]
+param = "extract_assignment"
+rationale = "Extracts from the extract_assignment; single operand."
+
+["pipelex/cogt/content_generation/generated_content_factory.py::GeneratedContentFactory._build_storage_key"]
+param = "primary_id"
+rationale = "Builds the storage key from the primary id; single operand."
+
+["pipelex/cogt/content_generation/generated_content_factory.py::GeneratedContentFactory._fetch_remote_content"]
+param = "url"
+rationale = "Fetches the remote content at the URL; single operand."
+
+["pipelex/cogt/content_generation/generated_content_factory.py::GeneratedContentFactory.make_image_content"]
+param = "primary_id"
+rationale = "Factory from source: builds the result from the primary_id; single operand."
+
+["pipelex/cogt/content_generation/generated_content_factory.py::GeneratedContentFactory.make_page_contents"]
+param = "primary_id"
+rationale = "Factory from source: builds the result from the primary_id; single operand."
+
+["pipelex/cogt/content_generation/img_gen_generate.py::img_gen_image_list"]
+param = "img_gen_assignment"
+rationale = "Processes the img-gen assignment; single operand."
+
+["pipelex/cogt/content_generation/img_gen_generate.py::img_gen_image_list_and_store"]
+param = "img_gen_assignment"
+rationale = "Processes the img-gen assignment; single operand."
+
+["pipelex/cogt/content_generation/img_gen_generate.py::img_gen_single_image"]
+param = "img_gen_assignment"
+rationale = "Processes the img-gen assignment; single operand."
+
+["pipelex/cogt/content_generation/img_gen_generate.py::img_gen_single_image_and_store"]
+param = "img_gen_assignment"
+rationale = "Processes the img-gen assignment; single operand."
+
+["pipelex/cogt/content_generation/llm_generate.py::llm_gen_object"]
+param = "object_assignment"
+rationale = "Processes the object assignment; single operand."
+
+["pipelex/cogt/content_generation/llm_generate.py::llm_gen_object_list"]
+param = "object_assignment"
+rationale = "Processes the object assignment; single operand."
+
+["pipelex/cogt/content_generation/llm_generate.py::llm_gen_text"]
+param = "llm_assignment"
+rationale = "Processes the LLM assignment; single operand."
+
+["pipelex/cogt/content_generation/render_generate.py::render_page_views_and_store"]
+param = "render_assignment"
+rationale = "Transforms/renders the render_assignment; single operand."
+
+["pipelex/cogt/content_generation/schema_to_model_factory.py::SchemaToModelFactory._collect_unsafe_extension_paths"]
+param = "node"
+rationale = "Walks the schema node; single operand."
+
+["pipelex/cogt/content_generation/schema_to_model_factory.py::SchemaToModelFactory._exec_and_extract_class"]
+param = "source_code"
+rationale = "Executes the generated source code; single operand."
+
+["pipelex/cogt/content_generation/schema_to_model_factory.py::SchemaToModelFactory._exec_source_to_types"]
+param = "source_code"
+rationale = "Executes the generated source code; single operand."
+
+["pipelex/cogt/content_generation/schema_to_model_factory.py::SchemaToModelFactory._generate_source_from_schema"]
+param = "schema"
+rationale = "Worker verb–object: processes the schema; single operand."
+
+["pipelex/cogt/content_generation/schema_to_model_factory.py::SchemaToModelFactory._normalize_class_name"]
+param = "title"
+rationale = "Transforms/renders the title; single operand."
+
+["pipelex/cogt/content_generation/schema_to_model_factory.py::SchemaToModelFactory._reject_unsafe_schema_extensions"]
+param = "schema"
+rationale = "Rejects unsafe extensions in the schema; single operand."
+
+["pipelex/cogt/content_generation/schema_to_model_factory.py::SchemaToModelFactory.make_from_json_schema"]
+param = "schema"
+rationale = "Factory from source: builds the result from the schema; single operand."
+
+["pipelex/cogt/content_generation/schema_to_model_factory.py::SchemaToModelFactory.make_types_from_source"]
+param = "source_code"
+rationale = "Factory from source: builds the result from the source_code; single operand."
+
+["pipelex/cogt/content_generation/search_generate.py::_make_search_job"]
+param = "search_assignment"
+rationale = "Factory from source: builds the result from the search_assignment; single operand."
+
+["pipelex/cogt/content_generation/search_generate.py::_make_search_worker"]
+param = "search_assignment"
+rationale = "Factory from source: builds the result from the search_assignment; single operand."
+
+["pipelex/cogt/content_generation/search_generate.py::search_gen_sourced_answer"]
+param = "search_assignment"
+rationale = "Worker verb–object: processes the search_assignment; single operand."
+
+["pipelex/cogt/content_generation/search_generate.py::search_gen_structured"]
+param = "search_object_assignment"
+rationale = "Worker verb–object: processes the search_object_assignment; single operand."
+
+["pipelex/cogt/content_generation/templating_generate.py::templating_gen_text"]
+param = "templating_assignment"
+rationale = "Processes the templating assignment; single operand."
+
+["pipelex/cogt/document/prompt_document_utils.py::prep_prompt_documents"]
+param = "prompt_documents"
+rationale = "Prepares the prompt documents; single operand."
+
+["pipelex/cogt/document/prompt_document_utils.py::prepare_prompt_document"]
+param = "prompt_document"
+rationale = "Prepares the prompt document; single operand."
+
+["pipelex/cogt/document/prompt_document_utils.py::prepare_prompt_document_as_base64"]
+param = "prompt_document"
+rationale = "Prepares the prompt document as base64; single operand."
+
+["pipelex/cogt/exceptions.py::CogtError.fill_model_and_provider"]
+param = "model_handle"
+rationale = "Operates on the model_handle; single operand (qualifiers keyword-only)."
+
+["pipelex/cogt/exceptions.py::find_inference_error_category_in_chain"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/extract/extract_job.py::ExtractJob.extract_job_before_start"]
+param = "inference_model"
+rationale = "Extracts from the inference_model; single operand."
+
+["pipelex/cogt/extract/extract_job_factory.py::ExtractJobFactory.make_extract_job"]
+param = "extract_input"
+rationale = "Factory from source: builds the result from the extract_input; single operand."
+
+["pipelex/cogt/extract/extract_report.py::ExtractTokenCostReportField.report_field_for_cost_by_category"]
+param = "token_category"
+rationale = "Derives the report field for the token category; single operand."
+
+["pipelex/cogt/extract/extract_report.py::ExtractTokenCostReportField.report_field_for_nb_tokens_by_category"]
+param = "token_category"
+rationale = "Derives the report field for the token category; single operand."
+
+["pipelex/cogt/extract/extract_worker_abstract.py::ExtractWorkerAbstract._check_can_perform_job"]
+param = "extract_job"
+rationale = "Verb–object: validates/checks the extract_job; single operand."
+
+["pipelex/cogt/extract/extract_worker_abstract.py::ExtractWorkerAbstract._extract_pages"]
+param = "extract_job"
+rationale = "Extracts from the extract_job; single operand."
+
+["pipelex/cogt/extract/extract_worker_abstract.py::ExtractWorkerAbstract.extract_pages"]
+param = "extract_job"
+rationale = "Extracts from the extract_job; single operand."
+
+["pipelex/cogt/extract/extract_worker_factory.py::ExtractWorkerFactory.make_extract_worker"]
+param = "inference_model"
+rationale = "Factory from source: builds the result from the inference_model; single operand."
+
+["pipelex/cogt/file/file_preparation_utils.py::prepare_file_from_uri"]
+param = "uri"
+rationale = "Prepares the file from the URI; single operand."
+
+["pipelex/cogt/image/generated_image.py::GeneratedImageRawDetails.make_from_pil_image"]
+param = "pil_image"
+rationale = "Factory from source: builds the result from the pil_image; single operand."
+
+["pipelex/cogt/image/prompt_image_utils.py::prep_prompt_images"]
+param = "prompt_images"
+rationale = "Prepares the prompt images; single operand."
+
+["pipelex/cogt/image/prompt_image_utils.py::prepare_prompt_image"]
+param = "prompt_image"
+rationale = "Prepares the prompt image; single operand."
+
+["pipelex/cogt/image/prompt_image_utils.py::prepare_prompt_image_as_base64"]
+param = "prompt_image"
+rationale = "Prepares the prompt image as base64; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_for_model"]
+param = "model_rules"
+rationale = "Factory from source: builds the result from the model_rules; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_aspect_ratio"]
+param = "aspect_ratio_taxonomy"
+rationale = "Factory from source: builds the result from the aspect_ratio_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_background"]
+param = "background_taxonomy"
+rationale = "Factory from source: builds the result from the background_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_inference"]
+param = "inference_taxonomy"
+rationale = "Factory from source: builds the result from the inference_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_input_fidelity"]
+param = "input_fidelity_taxonomy"
+rationale = "Factory from source: builds the result from the input_fidelity_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_input_images"]
+param = "input_images_taxonomy"
+rationale = "Factory from source: builds the result from the input_images_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_model_name"]
+param = "model_name_taxonomy"
+rationale = "Factory from source: builds the result from the model_name_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_num_images"]
+param = "num_images_taxonomy"
+rationale = "Factory from source: builds the result from the num_images_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_output_compression"]
+param = "output_compression_taxonomy"
+rationale = "Factory from source: builds the result from the output_compression_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_output_format"]
+param = "output_format_taxonomy"
+rationale = "Factory from source: builds the result from the output_format_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_prompt"]
+param = "prompt_taxonomy"
+rationale = "Factory from source: builds the result from the prompt_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_safety_checker"]
+param = "safety_checker_taxonomy"
+rationale = "Factory from source: builds the result from the safety_checker_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_specific"]
+param = "specific_taxonomy"
+rationale = "Factory from source: builds the result from the specific_taxonomy; single operand."
+
+["pipelex/cogt/img_gen/img_gen_job.py::ImgGenJob.img_gen_job_before_start"]
+param = "inference_model"
+rationale = "Prepares the job against the inference_model; single operand."
+
+["pipelex/cogt/img_gen/img_gen_job_components.py::parse_img_gen_size"]
+param = "value"
+rationale = "Parses the value; single operand."
+
+["pipelex/cogt/img_gen/img_gen_job_factory.py::ImgGenJobFactory.make_img_gen_job_from_prompt"]
+param = "img_gen_prompt"
+rationale = "Factory from source: builds the result from the img_gen_prompt; single operand."
+
+["pipelex/cogt/img_gen/img_gen_job_factory.py::ImgGenJobFactory.make_img_gen_job_from_prompt_contents"]
+param = "positive_text"
+rationale = "Factory from source: builds the result from the positive_text; single operand."
+
+["pipelex/cogt/img_gen/img_gen_report.py::ImgGenTokenCostReportField.report_field_for_cost_by_category"]
+param = "token_category"
+rationale = "Derives the report field for the token category; single operand."
+
+["pipelex/cogt/img_gen/img_gen_report.py::ImgGenTokenCostReportField.report_field_for_nb_tokens_by_category"]
+param = "token_category"
+rationale = "Derives the report field for the token category; single operand."
+
+["pipelex/cogt/img_gen/img_gen_worker_abstract.py::ImgGenWorkerAbstract._check_can_perform_job"]
+param = "img_gen_job"
+rationale = "Verb–object: validates/checks the img_gen_job; single operand."
+
+["pipelex/cogt/img_gen/img_gen_worker_abstract.py::ImgGenWorkerAbstract._gen_image"]
+param = "img_gen_job"
+rationale = "Worker verb–object: processes the img_gen_job; single operand."
+
+["pipelex/cogt/img_gen/img_gen_worker_abstract.py::ImgGenWorkerAbstract._gen_image_list"]
+param = "img_gen_job"
+rationale = "Worker verb–object: processes the img_gen_job; single operand."
+
+["pipelex/cogt/img_gen/img_gen_worker_abstract.py::ImgGenWorkerAbstract.gen_image"]
+param = "img_gen_job"
+rationale = "Worker verb–object: processes the img_gen_job; single operand."
+
+["pipelex/cogt/img_gen/img_gen_worker_abstract.py::ImgGenWorkerAbstract.gen_image_list"]
+param = "img_gen_job"
+rationale = "Worker verb–object: processes the img_gen_job; single operand."
+
+["pipelex/cogt/img_gen/img_gen_worker_factory.py::ImgGenWorkerFactory.make_img_gen_worker"]
+param = "inference_model"
+rationale = "Factory from source: builds the result from the inference_model; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_build_azure_metadata"]
+param = "response"
+rationale = "Extracts/derives from the response; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_google_provider_error_code_from_details"]
+param = "details"
+rationale = "Extracts/derives from the details; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_is_content_policy_violation"]
+param = "error_message"
+rationale = "Predicate on the error_message; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_is_quota_exhaustion_anthropic"]
+param = "error_message"
+rationale = "Predicate on the error_message; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_is_quota_exhaustion_aws"]
+param = "error_message"
+rationale = "Predicate on the error_message; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_is_quota_exhaustion_gateway"]
+param = "error_message"
+rationale = "Predicate on the error_message; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_is_quota_exhaustion_google"]
+param = "error_message"
+rationale = "Predicate on the error_message; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_is_quota_exhaustion_mistral"]
+param = "error_message"
+rationale = "Predicate on the error_message; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_is_quota_exhaustion_openai"]
+param = "error_message"
+rationale = "Predicate on the error_message; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_parse_response_text_body"]
+param = "response"
+rationale = "Parses the response; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_parse_retry_after_seconds"]
+param = "value"
+rationale = "Parses the value; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_provider_error_code_from_body"]
+param = "body"
+rationale = "Extracts/derives from the body; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_provider_error_code_from_flat_body"]
+param = "body"
+rationale = "Extracts/derives from the body; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_resolve_sdk_exception_type"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::_stringify_for_scan"]
+param = "body"
+rationale = "Extracts/derives from the body; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_anthropic_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_azure_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_azure_metadata_from_response"]
+param = "response"
+rationale = "Extracts from the response; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_bedrock_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_fal_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_gateway_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_google_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_huggingface_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_linkup_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_local_extract_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_mistral_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_openai_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
+["pipelex/cogt/inference/error_classification.py::extract_underlying_sdk_exception"]
+param = "instructor_exc"
+rationale = "Extracts from the instructor_exc; single operand."
+
+["pipelex/cogt/inference/error_classify.py::_classify_statusless"]
+param = "metadata"
+rationale = "Classifies the metadata; single operand."
+
+["pipelex/cogt/inference/error_classify.py::classify_inference_error"]
+param = "metadata"
+rationale = "Classifies the metadata; single operand."
+
+["pipelex/cogt/inference/error_render.py::_format_message"]
+param = "metadata"
+rationale = "Transforms/renders the metadata; single operand."
+
+["pipelex/cogt/inference/error_render.py::_render_detail"]
+param = "metadata"
+rationale = "Transforms/renders the metadata; single operand."
+
+["pipelex/cogt/inference/error_render.py::render_inference_error"]
+param = "metadata"
+rationale = "Transforms/renders the metadata; single operand."
+
+["pipelex/cogt/inference/inference_constants.py::InferenceOutputType.is_text"]
+param = "output_desc"
+rationale = "Predicate on the output_desc; single operand."
+
+["pipelex/cogt/inference/inference_manager.py::InferenceManager._setup_one_extract_worker"]
+param = "extract_handle"
+rationale = "Keyed accessor by the extract_handle; single operand."
+
+["pipelex/cogt/inference/inference_manager.py::InferenceManager._setup_one_img_gen_worker"]
+param = "img_gen_handle"
+rationale = "Keyed accessor by the img_gen_handle; single operand."
+
+["pipelex/cogt/inference/inference_manager.py::InferenceManager._setup_one_internal_llm_worker"]
+param = "llm_handle"
+rationale = "Keyed accessor by the llm_handle; single operand."
+
+["pipelex/cogt/inference/inference_manager_protocol.py::InferenceManagerProtocol.get_extract_worker"]
+param = "extract_handle"
+rationale = "Keyed accessor by the extract_handle; single operand."
+
+["pipelex/cogt/inference/inference_manager_protocol.py::InferenceManagerProtocol.get_img_gen_worker"]
+param = "img_gen_handle"
+rationale = "Keyed accessor by the img_gen_handle; single operand."
+
+["pipelex/cogt/inference/inference_manager_protocol.py::InferenceManagerProtocol.get_llm_worker"]
+param = "llm_handle"
+rationale = "Keyed accessor by the llm_handle; single operand."
+
+["pipelex/cogt/inference/transport_retry.py::_make_retry_predicate.should_retry"]
+param = "exc"
+rationale = "Positional-Callable tenacity retry predicate: exc is the single operand tenacity passes."
+
+["pipelex/cogt/inference/transport_retry.py::_parse_retry_after"]
+param = "raw_value"
+rationale = "Parses the raw_value; single operand."
+
+["pipelex/cogt/inference/transport_retry.py::_transport_retry_wait"]
+param = "retry_state"
+rationale = "Positional-Callable tenacity wait strategy: retry_state is the single operand tenacity passes."
+
+["pipelex/cogt/inference/transport_retry.py::request_with_transport_retry"]
+param = "send_request"
+rationale = "Runs the send_request callable under transport retry; single operand."
+
+["pipelex/cogt/llm/llm_job.py::LLMJob.llm_job_before_start"]
+param = "inference_model"
+rationale = "Prepares the job against the inference_model; single operand."
+
+["pipelex/cogt/llm/llm_job_factory.py::LLMJobFactory.make_llm_job"]
+param = "llm_prompt"
+rationale = "Factory from source: builds the result from the llm_prompt; single operand."
+
+["pipelex/cogt/llm/llm_prompt_template_inputs.py::LLMPromptTemplateInputs.complemented_by"]
+param = "additional_template_inputs"
+rationale = "Operates on the additional_template_inputs; single operand (qualifiers keyword-only)."
+
+["pipelex/cogt/llm/llm_prompt_template_inputs.py::LLMPromptTemplateInputs.complemented_by_dict"]
+param = "additional_inputs_dict"
+rationale = "Operates on the additional_inputs_dict; single operand (qualifiers keyword-only)."
+
+["pipelex/cogt/llm/llm_report.py::LLMTokenCostReportField.report_field_for_cost_by_category"]
+param = "token_category"
+rationale = "Derives the report field for the token category; single operand."
+
+["pipelex/cogt/llm/llm_report.py::LLMTokenCostReportField.report_field_for_nb_tokens_by_category"]
+param = "token_category"
+rationale = "Derives the report field for the token category; single operand."
+
+["pipelex/cogt/llm/llm_utils.py::dump_error"]
+param = "error"
+rationale = "Dumps the error for debugging; single operand."
+
+["pipelex/cogt/llm/llm_utils.py::dump_prompt"]
+param = "llm_prompt"
+rationale = "Dumps the llm_prompt for debugging; single operand."
+
+["pipelex/cogt/llm/llm_utils.py::dump_response_from_structured_gen"]
+param = "response"
+rationale = "Dumps the response for debugging; single operand."
+
+["pipelex/cogt/llm/llm_utils.py::dump_response_from_text_gen"]
+param = "response"
+rationale = "Dumps the response for debugging; single operand."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._apply_constraints"]
+param = "llm_job"
+rationale = "Verb-object: applies constraints to the job; single operand."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._before_job"]
+param = "llm_job"
+rationale = "Worker verb–object: processes the llm_job; single operand."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._check_can_perform_job"]
+param = "llm_job"
+rationale = "Verb–object: validates/checks the llm_job; single operand."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._check_document_support"]
+param = "llm_job"
+rationale = "Validator: the job is the single operand checked."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._check_vision_support"]
+param = "llm_job"
+rationale = "Validator: the job is the single operand checked."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._end_otel_span_with_completion_object"]
+param = "span"
+rationale = "Operates on the span; single operand (attached data keyword-only)."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._end_otel_span_with_completion_text"]
+param = "span"
+rationale = "Operates on the span; single operand (attached data keyword-only)."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._end_otel_span_with_error"]
+param = "span"
+rationale = "Operates on the span; single operand (attached data keyword-only)."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._gen_object"]
+param = "llm_job"
+rationale = "Worker verb–object: processes the llm_job; single operand."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._gen_text"]
+param = "llm_job"
+rationale = "Worker verb–object: processes the llm_job; single operand."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._start_otel_span_llm"]
+param = "llm_job"
+rationale = "Operates on the llm_job; single operand (attached data keyword-only)."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._validate_no_reasoning_for_structured_gen"]
+param = "job_params"
+rationale = "Validator: the job params are the single operand checked."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract.gen_object"]
+param = "llm_job"
+rationale = "Worker verb–object: processes the llm_job; single operand."
+
+["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract.gen_text"]
+param = "llm_job"
+rationale = "Worker verb–object: processes the llm_job; single operand."
+
+["pipelex/cogt/llm/llm_worker_factory.py::LLMWorkerFactory.make_llm_worker"]
+param = "inference_model"
+rationale = "Factory from source: builds the result from the inference_model; single operand."
+
+["pipelex/cogt/llm/reasoning_config_base.py::validate_effort_to_level_map"]
+param = "effort_to_level_map"
+rationale = "Verb–object: validates/checks the effort_to_level_map; single operand."
+
+["pipelex/cogt/model_backends/backend.py::InferenceBackend.get_extra_config"]
+param = "key"
+rationale = "Keyed accessor by the key; single operand."
+
+["pipelex/cogt/model_backends/backend.py::InferenceBackend.get_model_spec"]
+param = "model_name"
+rationale = "Keyed accessor by the model_name; single operand."
+
+["pipelex/cogt/model_backends/backend.py::PipelexBackend.is_gateway_backend"]
+param = "backend_name"
+rationale = "Predicate on the backend_name; single operand."
+
+["pipelex/cogt/model_backends/backend_credentials.py::BackendCredentialsErrorMsgFactory.make_comprehensive_error_msg"]
+param = "backend_credential_reports"
+rationale = "Factory from source: builds the result from the backend_credential_reports; single operand."
+
+["pipelex/cogt/model_backends/backend_factory.py::InferenceBackendFactory.make_inference_backend"]
+param = "name"
+rationale = "Factory from source: builds the result from the name; single operand."
+
+["pipelex/cogt/model_backends/backend_library.py::InferenceBackendLibrary._load_gateway_model_specs"]
+param = "gateway_config"
+rationale = "Loads model specs from the gateway config; single operand."
+
+["pipelex/cogt/model_backends/backend_library.py::InferenceBackendLibrary._load_local_model_specs"]
+param = "backend_name"
+rationale = "Loads model specs for the named backend; single operand."
+
+["pipelex/cogt/model_backends/backend_library.py::InferenceBackendLibrary.check_backend_credentials"]
+param = "path"
+rationale = "Verb–object: validates/checks the path; single operand."
+
+["pipelex/cogt/model_backends/backend_library.py::InferenceBackendLibrary.get_inference_backend"]
+param = "backend_name"
+rationale = "Keyed accessor by the backend_name; single operand."
+
+["pipelex/cogt/model_backends/model_lists.py::ModelLister.list_models"]
+param = "backend_name"
+rationale = "Operates on the backend_name; single operand (qualifiers keyword-only)."
+
+["pipelex/cogt/model_backends/model_spec_factory.py::InferenceModelSpecFactory.make_inference_model_spec"]
+param = "backend_name"
+rationale = "Factory from source: builds the result from the backend_name; single operand."
+
+["pipelex/cogt/model_routing/routing_profile_factory.py::RoutingProfileFactory.make_routing_profile"]
+param = "name"
+rationale = "Factory from source: builds the result from the name; single operand."
+
+["pipelex/cogt/model_routing/routing_profile_loader.py::load_active_routing_profile"]
+param = "routing_profile_library_path"
+rationale = "Deck/file op on the routing_profile_library_path; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::DeckSyncReport.files_with_status"]
+param = "status"
+rationale = "Deck/file op on the status; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::_is_managed_deck_filename"]
+param = "filename"
+rationale = "Predicate on the filename; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::_is_manifest_older"]
+param = "manifest_version"
+rationale = "Predicate on the manifest_version; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::_try_parse_version"]
+param = "version"
+rationale = "Deck/file op on the version; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::compute_deck_sync_report"]
+param = "deck_dir"
+rationale = "Deck/file op on the deck_dir; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::compute_file_sha256"]
+param = "path"
+rationale = "Deck/file op on the path; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::compute_sha256"]
+param = "data"
+rationale = "Deck/file op on the data; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::is_deck_stale_fast"]
+param = "deck_dir"
+rationale = "Predicate on the deck_dir; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::list_managed_installed_files"]
+param = "deck_dir"
+rationale = "Deck/file op on the deck_dir; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::manifest_path"]
+param = "deck_dir"
+rationale = "Deck/file op on the deck_dir; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::read_manifest"]
+param = "deck_dir"
+rationale = "Deck/file op on the deck_dir; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::status_rich_label"]
+param = "status"
+rationale = "Deck/file op on the status; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::suggest_x_custom_filename"]
+param = "numbered_filename"
+rationale = "Deck/file op on the numbered_filename; single operand."
+
+["pipelex/cogt/models/deck_manifest.py::write_manifest"]
+param = "manifest"
+rationale = "Deck/file op on the manifest; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck._get_optional_inference_model"]
+param = "model_handle"
+rationale = "Keyed accessor by the model_handle; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck._is_model_available_in_backend"]
+param = "model_handle"
+rationale = "Predicate on the model_handle; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck._raise_handle_not_found_error"]
+param = "ref"
+rationale = "Operates on the ref; single operand (qualifiers keyword-only)."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck._resolve_waterfall"]
+param = "waterfall_name"
+rationale = "Operates on the waterfall_name; single operand (qualifiers keyword-only)."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck._validate_llm_setting"]
+param = "llm_setting"
+rationale = "Verb–object: validates/checks the llm_setting; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_extract"]
+param = "name"
+rationale = "Verb–object: validates/checks the name; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_img_gen"]
+param = "name"
+rationale = "Verb–object: validates/checks the name; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_llm"]
+param = "name"
+rationale = "Verb–object: validates/checks the name; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_search"]
+param = "name"
+rationale = "Verb–object: validates/checks the name; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck.check_llm_choice"]
+param = "llm_choice"
+rationale = "Verb–object: validates/checks the llm_choice; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck.final_validate"]
+param = "deck"
+rationale = "Verb–object: validates/checks the deck; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck.get_aliases_and_waterfalls_for_type"]
+param = "model_type"
+rationale = "Keyed accessor by the model_type; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck.get_extract_setting"]
+param = "extract_choice"
+rationale = "Keyed accessor by the extract_choice; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck.get_img_gen_setting"]
+param = "img_gen_choice"
+rationale = "Keyed accessor by the img_gen_choice; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck.get_llm_setting"]
+param = "llm_choice"
+rationale = "Keyed accessor by the llm_choice; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck.get_optional_inference_model"]
+param = "model_handle"
+rationale = "Keyed accessor by the model_handle; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck.get_required_inference_model"]
+param = "model_handle"
+rationale = "Keyed accessor by the model_handle; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck.get_search_setting"]
+param = "search_choice"
+rationale = "Keyed accessor by the search_choice; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck.is_handle_defined"]
+param = "model_handle"
+rationale = "Predicate on the model_handle; single operand."
+
+["pipelex/cogt/models/model_deck.py::ModelDeck.is_model_handle_defined"]
+param = "model_handle"
+rationale = "Predicate on the model_handle; single operand."
+
+["pipelex/cogt/models/model_deck_check.py::_raise_model_choice_not_found"]
+param = "msg"
+rationale = "Operates on the msg; single operand (qualifiers keyword-only)."
+
+["pipelex/cogt/models/model_deck_check.py::check_extract_choice_with_deck"]
+param = "extract_choice"
+rationale = "Verb–object: validates/checks the extract_choice; single operand."
+
+["pipelex/cogt/models/model_deck_check.py::check_img_gen_choice_with_deck"]
+param = "img_gen_choice"
+rationale = "Verb–object: validates/checks the img_gen_choice; single operand."
+
+["pipelex/cogt/models/model_deck_check.py::check_llm_choice_with_deck"]
+param = "llm_choice"
+rationale = "Verb–object: validates/checks the llm_choice; single operand."
+
+["pipelex/cogt/models/model_deck_check.py::check_search_choice_with_deck"]
+param = "search_choice"
+rationale = "Verb–object: validates/checks the search_choice; single operand."
+
+["pipelex/cogt/models/model_deck_loader.py::load_model_deck_blueprint"]
+param = "model_deck_paths"
+rationale = "Deck/file op on the model_deck_paths; single operand."
+
+["pipelex/cogt/models/model_manager.py::ModelManager._collect_candidates"]
+param = "ref"
+rationale = "Operates on the ref; single operand (qualifiers keyword-only)."
+
+["pipelex/cogt/models/model_manager.py::ModelManager._collect_deck_referenced_handles"]
+param = "deck"
+rationale = "Keyed accessor by the deck; single operand."
+
+["pipelex/cogt/models/model_manager.py::ModelManager._enforce_gateway_model_membership"]
+param = "gateway_config"
+rationale = "Operates on the gateway_config; single operand (qualifiers keyword-only)."
+
+["pipelex/cogt/models/model_manager.py::ModelManager._extract_choice_handle"]
+param = "choice"
+rationale = "Extracts from the choice; single operand."
+
+["pipelex/cogt/models/model_manager.py::ModelManager.build_deck"]
+param = "model_deck_blueprint"
+rationale = "Factory from source: builds the result from the model_deck_blueprint; single operand."
+
+["pipelex/cogt/models/model_manager.py::ModelManager.get_model_deck_paths"]
+param = "deck_dir_path"
+rationale = "Keyed accessor by the deck_dir_path; single operand."
+
+["pipelex/cogt/models/model_manager_abstract.py::ModelManagerAbstract.get_inference_model"]
+param = "model_handle"
+rationale = "Keyed accessor by the model_handle; single operand."
+
+["pipelex/cogt/models/model_manager_abstract.py::ModelManagerAbstract.get_required_inference_backend"]
+param = "backend_name"
+rationale = "Keyed accessor by the backend_name; single operand."
+
+["pipelex/cogt/models/model_reference.py::ModelReference.parse"]
+param = "value"
+rationale = "Parses the value into a model reference; single operand."
+
+["pipelex/cogt/models/model_reference.py::ensure_model_reference"]
+param = "value"
+rationale = "Parses the value; single operand."
+
+["pipelex/cogt/models/model_reference.py::parse_model_reference"]
+param = "value"
+rationale = "Parses the value; single operand."
+
+["pipelex/cogt/models/model_suggestion.py::get_collection_keys"]
+param = "model_deck"
+rationale = "Keyed accessor by the model_deck; single operand."
+
+["pipelex/cogt/search/search_job.py::SearchJob.search_job_before_start"]
+param = "inference_model"
+rationale = "Worker verb–object: processes the inference_model; single operand."
+
+["pipelex/cogt/search/search_job_factory.py::SearchJobFactory.make_search_job"]
+param = "query"
+rationale = "Factory from source: builds the result from the query; single operand."
+
+["pipelex/cogt/search/search_report.py::SearchTokenCostReportField.report_field_for_cost_by_category"]
+param = "token_category"
+rationale = "Derives the report field for the token category; single operand."
+
+["pipelex/cogt/search/search_report.py::SearchTokenCostReportField.report_field_for_nb_tokens_by_category"]
+param = "token_category"
+rationale = "Derives the report field for the token category; single operand."
+
+["pipelex/cogt/search/search_worker_abstract.py::SearchWorkerAbstract._search_sourced_answer"]
+param = "search_job"
+rationale = "Worker verb–object: processes the search_job; single operand."
+
+["pipelex/cogt/search/search_worker_abstract.py::SearchWorkerAbstract._search_structured"]
+param = "search_job"
+rationale = "Worker verb–object: processes the search_job; single operand."
+
+["pipelex/cogt/search/search_worker_abstract.py::SearchWorkerAbstract.search_sourced_answer"]
+param = "search_job"
+rationale = "Worker verb–object: processes the search_job; single operand."
+
+["pipelex/cogt/search/search_worker_abstract.py::SearchWorkerAbstract.search_structured"]
+param = "search_job"
+rationale = "Worker verb–object: processes the search_job; single operand."
+
+["pipelex/cogt/search/search_worker_factory.py::SearchWorkerFactory.make_search_worker"]
+param = "inference_model"
+rationale = "Factory from source: builds the result from the inference_model; single operand."
+
+["pipelex/cogt/templating/template_preprocessor.py::_normalize_and_escape"]
+param = "template"
+rationale = "Transforms/renders the template; single operand."
+
+["pipelex/cogt/templating/template_preprocessor.py::_replace_at_sigil"]
+param = "match"
+rationale = "Transforms/renders the match; single operand."
+
+["pipelex/cogt/templating/template_preprocessor.py::_replace_dollar_sigil"]
+param = "match"
+rationale = "Transforms/renders the match; single operand."
+
+["pipelex/cogt/templating/template_preprocessor.py::_validate_at_sigil_alone_on_line"]
+param = "template"
+rationale = "Verb–object: validates/checks the template; single operand."
+
+["pipelex/cogt/templating/template_preprocessor.py::preprocess_template"]
+param = "template"
+rationale = "Transforms/renders the template; single operand."
+
+["pipelex/cogt/templating/template_preprocessor.py::rewrite_template_sigils"]
+param = "template"
+rationale = "Transforms/renders the template; single operand."
+
+["pipelex/cogt/templating/template_preprocessor.py::validate_template_sigils"]
+param = "template"
+rationale = "Verb–object: validates/checks the template; single operand."
+
+["pipelex/cogt/templating/template_rendering.py::render_template"]
+param = "template"
+rationale = "Transforms/renders the template; single operand."
+
+["pipelex/cogt/usage/cost_registry.py::CostRegistry.aggregate_costs"]
+param = "tokens_usages"
+rationale = "Cost report op on the tokens_usages; single operand."
+
+["pipelex/cogt/usage/cost_registry.py::CostRegistry.build_cost_summary"]
+param = "tokens_usages"
+rationale = "Factory from source: builds the result from the tokens_usages; single operand."
+
+["pipelex/cogt/usage/cost_registry.py::CostRegistry.complete_cost_report"]
+param = "tokens_usage"
+rationale = "Cost report op on the tokens_usage; single operand."
+
+["pipelex/cogt/usage/cost_registry.py::CostRegistry.compute_cost_report"]
+param = "tokens_usage"
+rationale = "Deck/file op on the tokens_usage; single operand."
+
+["pipelex/cogt/usage/cost_registry.py::CostRegistry.generate_report"]
+param = "pipeline_run_id"
+rationale = "Cost report op on the pipeline_run_id; single operand."
+
+["pipelex/cogt/usage/cost_registry.py::CostRegistry.render_report"]
+param = "aggregated"
+rationale = "Transforms/renders the aggregated; single operand."
+
+["pipelex/cogt/usage/cost_registry.py::CostRegistry.save_to_csv"]
+param = "records"
+rationale = "Cost report op on the records; single operand."
+
+["pipelex/core/bundles/pipe_sorter.py::sort_pipes_by_dependencies"]
+param = "pipes"
+rationale = "Verb-object: sorts the pipes; single operand."
+
+["pipelex/core/bundles/pipe_sorter.py::sort_pipes_by_dependencies.visit"]
+param = "pipe_code"
+rationale = "Nested DFS visitor on the pipe code; single operand."
+
+["pipelex/core/bundles/pipelex_bundle_blueprint.py::PipelexBundleBlueprint._collect_local_refs_from_concept"]
+param = "concept_code"
+rationale = "Verb-object: collects refs from the concept named; context stays keyword."
+
+["pipelex/core/bundles/pipelex_bundle_blueprint.py::PipelexBundleBlueprint._collect_local_refs_from_pipe"]
+param = "pipe_code"
+rationale = "Verb-object: collects refs from the pipe named; context stays keyword."
+
+["pipelex/core/bundles/pipelex_bundle_blueprint.py::PipelexBundleBlueprint.get_elaboration_for"]
+param = "pipe_code"
+rationale = "Query accessor keyed by the pipe code; single operand."
+
+["pipelex/core/bundles/pipelex_bundle_blueprint.py::_strippable_same_domain_pipe_code"]
+param = "code"
+rationale = "Single-operand transformation of the code; the rest is context."
+
+["pipelex/core/concepts/concept.py::Concept.is_native_concept"]
+param = "concept"
+rationale = "Predicate on the concept; single operand."
+
+["pipelex/core/concepts/concept.py::Concept.is_valid_structure_class"]
+param = "structure_class_name"
+rationale = "Predicate on the class name; single operand."
+
+["pipelex/core/concepts/concept.py::Concept.sentence_from_concept"]
+param = "concept"
+rationale = "Derivation from the concept; single operand."
+
+["pipelex/core/concepts/concept_factory.py::ConceptFactory._handle_blueprint_with_structure"]
+param = "blueprint"
+rationale = "Verb-object: handles the blueprint; context stays keyword."
+
+["pipelex/core/concepts/concept_factory.py::ConceptFactory._handle_refines"]
+param = "blueprint"
+rationale = "Verb-object: handles the blueprint; context stays keyword."
+
+["pipelex/core/concepts/concept_factory.py::ConceptFactory._handle_structure_with_classname"]
+param = "blueprint"
+rationale = "Verb-object: handles the blueprint; context stays keyword."
+
+["pipelex/core/concepts/concept_factory.py::ConceptFactory.make_domain_and_concept_code_from_concept_ref_or_code"]
+param = "concept_ref_or_code"
+rationale = "Conversion: splits the ref-or-code; fallback domain stays keyword."
+
+["pipelex/core/concepts/concept_factory.py::ConceptFactory.make_native_concept"]
+param = "native_concept_code"
+rationale = "Factory keyed by the native concept code; single operand."
+
+["pipelex/core/concepts/concept_factory.py::ConceptFactory.make_refine"]
+param = "refine"
+rationale = "Verb-object: normalizes the refine string; domain stays keyword."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator._format_python_value"]
+param = "value"
+rationale = "Transforms the value; single operand."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator._generate_basemodel_representation"]
+param = "model_class"
+rationale = "Derivation from the model class; single operand."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator._generate_basic_value"]
+param = "actual_type"
+rationale = "Derivation from the type; single operand."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator._generate_dict_value"]
+param = "field_name"
+rationale = "Derivation keyed by the field name; single operand."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator._generate_enum_value"]
+param = "enum_type"
+rationale = "Derivation from the enum type; single operand."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator._generate_fields_dict"]
+param = "content_class"
+rationale = "Derivation from the content class; single operand."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator._generate_list_value"]
+param = "args"
+rationale = "Derivation from the type args; single operand."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator._generate_literal_value"]
+param = "literal_args"
+rationale = "Derivation from the literal args; single operand."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator._unwrap_optional"]
+param = "field_type"
+rationale = "Transforms the field type; single operand."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator.generate_class_representation"]
+param = "content_class"
+rationale = "Derivation from the content class; single operand."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator.generate_field_value"]
+param = "field_type"
+rationale = "Derivation from the field type; context stays keyword."
+
+["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator.generate_representation"]
+param = "concept_ref"
+rationale = "Derivation keyed by the concept ref; format stays keyword."
+
+["pipelex/core/concepts/concept_representation_generator.py::generate_json_representation"]
+param = "concept_ref"
+rationale = "Derivation keyed by the concept ref; single operand."
+
+["pipelex/core/concepts/concept_representation_generator.py::generate_python_representation"]
+param = "concept_ref"
+rationale = "Derivation keyed by the concept ref; single operand."
+
+["pipelex/core/concepts/helpers.py::extract_concept_code_from_concept_ref_or_code"]
+param = "concept_ref_or_code"
+rationale = "Conversion: extracts from the ref-or-code; single operand."
+
+["pipelex/core/concepts/helpers.py::get_structure_class_name_from_blueprint"]
+param = "blueprint_or_string_description"
+rationale = "Derivation from the blueprint-or-description; single operand."
+
+["pipelex/core/concepts/helpers.py::normalize_structure_blueprint"]
+param = "structure_dict"
+rationale = "Verb-object: normalizes the structure dict; single operand."
+
+["pipelex/core/concepts/helpers.py::strip_markers_from_concept_ref_or_code"]
+param = "concept_ref_or_code"
+rationale = "Single-operand transformation of the ref-or-code string."
+
+["pipelex/core/concepts/native/concept_native.py::NativeConceptCode.get_native_structure_class"]
+param = "class_name"
+rationale = "Lookup keyed by the class name it resolves; single operand."
+
+["pipelex/core/concepts/native/concept_native.py::NativeConceptCode.get_validated_native_concept_ref"]
+param = "concept_ref_or_code"
+rationale = "Verb-object: validates the ref-or-code; single operand."
+
+["pipelex/core/concepts/native/concept_native.py::NativeConceptCode.is_dynamic_concept"]
+param = "concept_code"
+rationale = "Predicate on the concept code; single operand."
+
+["pipelex/core/concepts/native/concept_native.py::NativeConceptCode.is_native_concept_ref_or_code"]
+param = "concept_ref_or_code"
+rationale = "Predicate on the ref-or-code; single operand."
+
+["pipelex/core/concepts/native/concept_native.py::NativeConceptCode.is_native_structure_class"]
+param = "class_name"
+rationale = "Predicate on the class name; single operand."
+
+["pipelex/core/concepts/native/concept_native.py::NativeConceptCode.is_text_concept"]
+param = "concept_code"
+rationale = "Predicate on the concept code; single operand."
+
+["pipelex/core/concepts/native/concept_native.py::NativeConceptCode.is_valid_native_concept_ref"]
+param = "concept_ref"
+rationale = "Predicate on the concept ref; single operand."
+
+["pipelex/core/concepts/native/concept_native.py::NativeConceptCode.validate_native_concept_ref_or_code"]
+param = "concept_ref_or_code"
+rationale = "Verb-object: validates the ref-or-code; single operand."
+
+["pipelex/core/concepts/native/pinned_blueprints.py::_pinned_description"]
+param = "native_code"
+rationale = "Noun-named derivation: the pinned description for the native code; single operand."
+
+["pipelex/core/concepts/native/pinned_blueprints.py::_pinned_structure"]
+param = "native_code"
+rationale = "Noun-named derivation: the pinned structure for the native code; single operand."
+
+["pipelex/core/concepts/native/pinned_blueprints.py::make_pinned_native_blueprint"]
+param = "native_code"
+rationale = "Factory from source: builds the blueprint for the native code; single operand."
+
+["pipelex/core/concepts/structure_generation/exceptions.py::SyntaxErrorData.from_syntax_error"]
+param = "syntax_error"
+rationale = "Factory from source: builds from the syntax error; single operand."
+
+["pipelex/core/concepts/structure_generation/generator.py::StructureGenerator._escape_string_for_python"]
+param = "value"
+rationale = "Transforms the value; single operand."
+
+["pipelex/core/concepts/structure_generation/generator.py::StructureGenerator._format_class_docstring"]
+param = "docstring"
+rationale = "Transforms the docstring; single operand."
+
+["pipelex/core/concepts/structure_generation/generator.py::StructureGenerator._format_default_value"]
+param = "value"
+rationale = "Transforms the value; context stays keyword."
+
+["pipelex/core/concepts/structure_generation/generator.py::StructureGenerator._format_field_description"]
+param = "description"
+rationale = "Transforms the description; single operand."
+
+["pipelex/core/concepts/structure_generation/generator.py::StructureGenerator._generate_field_line"]
+param = "resolved_field"
+rationale = "Noun-named derivation: the source line for the resolved field; single operand."
+
+["pipelex/core/concepts/structure_generation/generator.py::StructureGenerator._python_type_for_concept"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the Python type for the resolved type; single operand."
+
+["pipelex/core/concepts/structure_generation/generator.py::StructureGenerator._python_type_from_resolved"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the Python type for the resolved type; single operand."
+
+["pipelex/core/concepts/structure_generation/generator.py::StructureGenerator._validate_execution"]
+param = "python_code"
+rationale = "Verb-object: validates the python code; single operand."
+
+["pipelex/core/concepts/structure_generation/generator.py::StructureGenerator.validate_generated_code"]
+param = "python_code"
+rationale = "Verb-object: validates the python code; single operand."
+
+["pipelex/core/concepts/validation.py::is_concept_code_valid"]
+param = "concept_code"
+rationale = "Predicate on the concept code; single operand."
+
+["pipelex/core/concepts/validation.py::is_concept_ref_or_code_valid"]
+param = "concept_ref_or_code"
+rationale = "Predicate on the ref-or-code; single operand."
+
+["pipelex/core/concepts/validation.py::is_concept_ref_valid"]
+param = "concept_ref"
+rationale = "Predicate on the concept ref; single operand."
+
+["pipelex/core/concepts/validation.py::validate_concept_code"]
+param = "concept_code"
+rationale = "Verb-object: validates the concept code; single operand."
+
+["pipelex/core/concepts/validation.py::validate_concept_ref"]
+param = "concept_ref"
+rationale = "Verb-object: validates the concept ref; single operand."
+
+["pipelex/core/concepts/validation.py::validate_concept_ref_or_code"]
+param = "concept_ref_or_code"
+rationale = "Verb-object: validates the ref-or-code; single operand."
+
+["pipelex/core/domains/domain.py::SpecialDomain.is_native"]
+param = "domain_code"
+rationale = "Predicate on the domain code; single operand."
+
+["pipelex/core/domains/domain_factory.py::DomainFactory.make_from_blueprint"]
+param = "blueprint"
+rationale = "Factory from source: builds the domain from the blueprint; single operand."
+
+["pipelex/core/domains/validation.py::is_domain_code_valid"]
+param = "code"
+rationale = "Predicate on the domain code; single operand."
+
+["pipelex/core/domains/validation.py::validate_domain_code"]
+param = "code"
+rationale = "Verb-object: validates the domain code; single operand."
+
+["pipelex/core/interpreter/bundle_elaborator.py::BundleElaborator.elaborate"]
+param = "bundle"
+rationale = "Verb-object: elaborates the bundle; single operand."
+
+["pipelex/core/interpreter/bundle_elaborator.py::_is_preliminary_text_pipe"]
+param = "pipe_blueprint"
+rationale = "Predicate on the pipe blueprint; single operand."
+
+["pipelex/core/interpreter/helpers.py::ValidationErrorScope.is_pipe_scope"]
+param = "scope"
+rationale = "Predicate on the scope; single operand."
+
+["pipelex/core/interpreter/helpers.py::get_error_scope"]
+param = "loc"
+rationale = "Derivation from the error loc; single operand."
+
+["pipelex/core/interpreter/helpers.py::is_pipelex_file"]
+param = "file_path"
+rationale = "Predicate on the file path; single operand."
+
+["pipelex/core/interpreter/interpreter.py::PipelexInterpreter.make_pipelex_bundle_blueprint"]
+param = "bundle_path"
+rationale = "Factory from source: parses the bundle at the path; options stay keyword."
+
+["pipelex/core/interpreter/validation_error_categorizer.py::_categorize_concept_validation_error"]
+param = "loc"
+rationale = "Verb-object: categorizes the error at the loc; context stays keyword."
+
+["pipelex/core/interpreter/validation_error_categorizer.py::_categorize_input_validation_error"]
+param = "message"
+rationale = "Verb-object: categorizes the error message; context stays keyword."
+
+["pipelex/core/interpreter/validation_error_categorizer.py::_categorize_syntax_validation_error"]
+param = "message"
+rationale = "Verb-object: categorizes the error message; context stays keyword."
+
+["pipelex/core/interpreter/validation_error_categorizer.py::_categorize_typeless_pipe_error"]
+param = "message"
+rationale = "Verb-object: categorizes the message; the rest is context."
+
+["pipelex/core/interpreter/validation_error_categorizer.py::_extract_variable_names_from_message"]
+param = "message"
+rationale = "Verb-object: extracts from the message; single operand."
+
+["pipelex/core/interpreter/validation_error_categorizer.py::_extract_wrapped_invalid_pipe_code_syntax_error"]
+param = "error"
+rationale = "Extraction from the single error operand."
+
+["pipelex/core/interpreter/validation_error_categorizer.py::_extract_wrapped_native_concept_redeclaration_error"]
+param = "error"
+rationale = "Extraction from the single error operand."
+
+["pipelex/core/interpreter/validation_error_categorizer.py::_is_pydantic_internal_loc_element"]
+param = "element"
+rationale = "Predicate on the loc element; single operand."
+
+["pipelex/core/interpreter/validation_error_categorizer.py::categorize_blueprint_validation_error"]
+param = "error"
+rationale = "Verb-object: categorizes the error; context stays keyword."
+
+["pipelex/core/memory/absence_render.py::build_absence_html"]
+param = "absence_record"
+rationale = "Verb-object: renders the absence record; single operand."
+
+["pipelex/core/memory/absence_render.py::build_absence_json"]
+param = "absence_record"
+rationale = "Verb-object: renders the absence record; single operand."
+
+["pipelex/core/memory/absence_render.py::build_absence_markdown"]
+param = "absence_record"
+rationale = "Verb-object: renders the absence record; single operand."
+
+["pipelex/core/memory/absence_render.py::build_absence_payload"]
+param = "absence_record"
+rationale = "Verb-object: renders the absence record; single operand."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._build_item_content"]
+param = "value"
+rationale = "Verb-object: shapes the raw value into content; the rest is context."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._check_input_names"]
+param = "pipeline_inputs"
+rationale = "Validator: the pipeline inputs are the operand checked against the specs."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._describe_value"]
+param = "value"
+rationale = "Noun-named derivation: describes the value; single operand."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._is_explicit"]
+param = "value"
+rationale = "Predicate on the value; single operand."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._make_content"]
+param = "concept"
+rationale = "Factory keyed by the concept; the value stays keyword."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._peel_multiplicity"]
+param = "multiplicity"
+rationale = "Single-operand transformation of the multiplicity."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._reconcile_explicit_multiplicity"]
+param = "stuff"
+rationale = "Verb-object: reconciles the stuff; the rest is context."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._resolve_local_path"]
+param = "url"
+rationale = "Verb-object: resolves the url; inputs_base_dir is context."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._shape_explicit"]
+param = "value"
+rationale = "Verb-object: shapes the raw value; the rest is context."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._shape_list"]
+param = "value"
+rationale = "Verb-object: shapes the raw value; the rest is context."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._shape_one"]
+param = "value"
+rationale = "Verb-object: shapes the raw value; the rest is context."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._shape_with_multiplicity"]
+param = "value"
+rationale = "Verb-object: shapes the raw value; the rest is context."
+
+["pipelex/core/memory/input_shaper.py::InputShaper._try_shape_csv"]
+param = "value"
+rationale = "Verb-object: shapes the raw value; the rest is context."
+
+["pipelex/core/memory/input_shaper.py::InputShaper.resolve_input_kind"]
+param = "concept"
+rationale = "Noun-named derivation: the input kind of the concept; single operand."
+
+["pipelex/core/memory/input_shaper.py::InputShaper.shape"]
+param = "pipeline_inputs"
+rationale = "Verb-object: shapes the pipeline inputs; specs and context stay keyword."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory._get_typed_items_from_list_content"]
+param = "list_content"
+rationale = "Verb-object: reads the list content; expected type stays keyword."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.add_alias"]
+param = "alias"
+rationale = "Verb-object: the alias being added; its target stays keyword."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_aliases_for"]
+param = "target"
+rationale = "Query keyed by the target name; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_existing_stuffs"]
+param = "names"
+rationale = "Memory getter keyed by the stuff names; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_list_stuff_first_item_as"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; item type stays keyword."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_optional_absence"]
+param = "name"
+rationale = "Entity-keyed getter on working memory."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_optional_stuff"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; content type stays keyword."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as_date"]
+param = "name"
+rationale = "Entity-keyed getter on working memory."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as_document"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as_html"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as_image"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as_list"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; item type stays keyword."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as_mermaid"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as_number"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as_str"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as_text"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as_text_and_image"]
+param = "name"
+rationale = "Memory getter keyed by the stuff name; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuff_as_yes_no"]
+param = "name"
+rationale = "Entity-keyed getter on working memory."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.get_stuffs"]
+param = "names"
+rationale = "Memory getter keyed by the stuff names; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.is_stuff_code_used"]
+param = "stuff_code"
+rationale = "Predicate on the stuff code; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.is_stuff_exists"]
+param = "name"
+rationale = "Predicate on the stuff named; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.list_missing_names"]
+param = "names"
+rationale = "Verb-object: filters the given names to the missing ones; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.main_list_stuff_first_item_as"]
+param = "item_type"
+rationale = "Type-directed accessor: the target item type; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.main_stuff_as"]
+param = "content_type"
+rationale = "Type-directed accessor: the target content type; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.main_stuff_as_list"]
+param = "item_type"
+rationale = "Type-directed accessor: the target item type; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.record_absence"]
+param = "record"
+rationale = "Verb-object: records the absence record; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.record_new_main_absence"]
+param = "record"
+rationale = "Verb-object: records the absence record; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.record_resolved_absence"]
+param = "record"
+rationale = "Verb-object: records the absence record; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.remove_alias"]
+param = "alias"
+rationale = "Verb-object: removes the alias; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.remove_stuff"]
+param = "name"
+rationale = "Verb-object: removes the stuff named; single operand."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.resolve_stuff"]
+param = "name"
+rationale = "Entity-keyed getter on working memory."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.set_alias"]
+param = "alias"
+rationale = "Verb-object: the alias being set; its target stays keyword."
+
+["pipelex/core/memory/working_memory.py::WorkingMemory.set_new_main_stuff"]
+param = "stuff"
+rationale = "Verb-object: installs the stuff as main; name stays keyword."
+
+["pipelex/core/memory/working_memory.py::_encode_composite_for_transport"]
+param = "composite"
+rationale = "Single-operand conversion of the composite content."
+
+["pipelex/core/memory/working_memory.py::_encode_content_with_class_markers"]
+param = "content"
+rationale = "Single-operand conversion of the content."
+
+["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory._get_mockable_class"]
+param = "structure_class"
+rationale = "Derivation from the structure class; single operand."
+
+["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.convert_stuff_spec_to_typed_named"]
+param = "stuff_spec"
+rationale = "Conversion: transforms the stuff spec; context stays keyword."
+
+["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.convert_to_working_memory_format"]
+param = "needed_inputs_spec"
+rationale = "Conversion: transforms the needed-inputs spec; single operand."
+
+["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.make_from_multiple_stuffs"]
+param = "stuff_list"
+rationale = "Factory from source: builds from the stuff list; options stay keyword."
+
+["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.make_from_pipeline_inputs"]
+param = "pipeline_inputs"
+rationale = "Factory from source: builds from the pipeline inputs; options stay keyword."
+
+["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.make_from_single_stuff"]
+param = "stuff"
+rationale = "Factory from source: builds from the stuff; options stay keyword."
+
+["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.make_mock_content"]
+param = "typed_named_stuff_spec"
+rationale = "Factory from source: builds from the typed-named spec; single operand."
+
+["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.make_mock_inputs"]
+param = "needed_inputs"
+rationale = "Factory from source: builds from the needed inputs; single operand."
+
+["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.make_mock_stuff"]
+param = "typed_named_stuff_spec"
+rationale = "Factory from source: builds from the typed-named spec; single operand."
+
+["pipelex/core/pipes/handle_pipe_errors.py::_handle_pipe_errors"]
+param = "error"
+rationale = "Verb-object: handles the error; context stays keyword."
+
+["pipelex/core/pipes/handle_pipe_errors.py::categorize_pipe_factory_error"]
+param = "factory_error"
+rationale = "Verb-object: categorizes the factory error; context stays keyword."
+
+["pipelex/core/pipes/handle_pipe_errors.py::categorize_pipe_validation_error"]
+param = "validation_error"
+rationale = "Verb-object: categorizes the validation error; context stays keyword."
+
+["pipelex/core/pipes/handle_pipe_errors.py::categorize_pipe_validation_with_libraries_error"]
+param = "pipe_error"
+rationale = "Verb-object: categorizes the pipe error; context stays keyword."
+
+["pipelex/core/pipes/handle_pipe_errors.py::extract_wrapped_pipe_validation_error"]
+param = "error"
+rationale = "Verb-object: unwraps the error; single operand."
+
+["pipelex/core/pipes/inputs/input_renderer.py::_delighten_entry"]
+param = "entry"
+rationale = "Single-operand transformation of the entry; kind is a mode and stays keyword."
+
+["pipelex/core/pipes/inputs/input_renderer.py::_delighten_template"]
+param = "envelope_template"
+rationale = "Single-operand transformation of the template; specs stay keyword."
+
+["pipelex/core/pipes/inputs/input_renderer.py::_substitute_none_values"]
+param = "value"
+rationale = "Single-operand transformation of the value."
+
+["pipelex/core/pipes/inputs/input_renderer.py::_to_toml_value"]
+param = "value"
+rationale = "Single-operand conversion of the value."
+
+["pipelex/core/pipes/inputs/input_renderer.py::_unwrap_scalar_content"]
+param = "content"
+rationale = "Single-operand unwrap of the content; envelope is context."
+
+["pipelex/core/pipes/inputs/input_renderer.py::build_concept_comments"]
+param = "input_specs"
+rationale = "Noun-named derivation: the comments mapping for the input specs; single operand."
+
+["pipelex/core/pipes/inputs/input_renderer.py::build_inputs_template"]
+param = "the_pipe"
+rationale = "Noun-named derivation: the inputs template for the pipe; explicit is a mode."
+
+["pipelex/core/pipes/inputs/input_renderer.py::render_inputs"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's inputs; format stays keyword."
+
+["pipelex/core/pipes/inputs/input_renderer.py::render_inputs_toml"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's inputs; explicit is a mode."
+
+["pipelex/core/pipes/inputs/input_renderer.py::serialize_inputs_template_to_toml"]
+param = "template"
+rationale = "Single-operand serialization of the template; options stay keyword."
+
+["pipelex/core/pipes/inputs/input_stuff_specs.py::InputStuffSpecs.get_required_stuff_spec"]
+param = "variable_name"
+rationale = "Specs getter keyed by the variable name; single operand."
+
+["pipelex/core/pipes/inputs/input_stuff_specs.py::InputStuffSpecs.is_variable_existing"]
+param = "variable_name"
+rationale = "Predicate on the variable named; single operand."
+
+["pipelex/core/pipes/inputs/input_stuff_specs.py::InputStuffSpecs.set_default_domain"]
+param = "domain_code"
+rationale = "Setter: installs the default domain code; single operand."
+
+["pipelex/core/pipes/inputs/input_stuff_specs.py::TypedNamedStuffSpec.make_from_named"]
+param = "named"
+rationale = "Factory from source: builds from the named spec; context stays keyword."
+
+["pipelex/core/pipes/output/output_renderer.py::_collect_possible_outputs"]
+param = "the_pipe"
+rationale = "Verb-object: collects from the pipe; single operand."
+
+["pipelex/core/pipes/output/output_renderer.py::_render_json_output"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's output; single operand."
+
+["pipelex/core/pipes/output/output_renderer.py::_render_python_output"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's output; single operand."
+
+["pipelex/core/pipes/output/output_renderer.py::_render_schema_output"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's output; single operand."
+
+["pipelex/core/pipes/output/output_renderer.py::render_output"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's output; format stays keyword."
+
+["pipelex/core/pipes/pipe_abstract.py::PipeAbstract._end_pipe_span_error"]
+param = "span"
+rationale = "Verb-object: ends the span; error fields stay keyword."
+
+["pipelex/core/pipes/pipe_abstract.py::PipeAbstract._end_pipe_span_success"]
+param = "span"
+rationale = "Verb-object: ends the span; result fields stay keyword."
+
+["pipelex/core/pipes/pipe_abstract.py::PipeAbstract._expected_inputs_for_fix"]
+param = "needed_inputs"
+rationale = "Noun-named derivation from the needed inputs; single operand."
+
+["pipelex/core/pipes/pipe_abstract.py::PipeAbstract._format_pipe_run_info"]
+param = "pipe_run_params"
+rationale = "Derivation from the run params; single operand."
+
+["pipelex/core/pipes/pipe_abstract.py::PipeAbstract._make_single_concept_data_for_registry"]
+param = "concept"
+rationale = "Derivation from the concept; single operand."
+
+["pipelex/core/pipes/pipe_blueprint.py::PipeCategory.is_controller_by_str"]
+param = "category_str"
+rationale = "Predicate on the category string; single operand."
+
+["pipelex/core/pipes/pipe_blueprint.py::explicit_signature_tag_migration_message"]
+param = "pipe_code"
+rationale = "Noun-named derivation: the migration message for the given pipe code; single operand."
+
+["pipelex/core/pipes/pipe_output.py::PipeOutput.main_stuff_as"]
+param = "content_type"
+rationale = "Type-directed accessor: the target content type; single operand."
+
+["pipelex/core/pipes/pipe_output.py::PipeOutput.main_stuff_as_items"]
+param = "item_type"
+rationale = "Type-directed accessor: the target item type; single operand."
+
+["pipelex/core/pipes/pipe_output.py::PipeOutput.main_stuff_as_list"]
+param = "item_type"
+rationale = "Type-directed accessor: the target item type; single operand."
+
+["pipelex/core/pipes/validation.py::is_input_used_by_variables"]
+param = "input_name"
+rationale = "Predicate on the input named; the variables stay keyword."
+
+["pipelex/core/pipes/validation.py::is_pipe_code_valid"]
+param = "pipe_code"
+rationale = "Predicate on the pipe code; single operand."
+
+["pipelex/core/pipes/validation.py::is_valid_input_name"]
+param = "input_name"
+rationale = "Predicate on the input name; single operand."
+
+["pipelex/core/pipes/validation.py::is_variable_satisfied_by_inputs"]
+param = "variable_path"
+rationale = "Predicate on the variable path; the inputs stay keyword."
+
+["pipelex/core/pipes/validation.py::validate_input_name"]
+param = "input_name"
+rationale = "Verb-object: validates the input name; single operand."
+
+["pipelex/core/pipes/variable_multiplicity.py::PresenceMarker.from_symbol"]
+param = "symbol"
+rationale = "Factory from source: parses the symbol; single operand."
+
+["pipelex/core/pipes/variable_multiplicity.py::format_concept_with_multiplicity"]
+param = "concept_code_or_string"
+rationale = "Transforms the concept string; multiplicity stays keyword."
+
+["pipelex/core/pipes/variable_multiplicity.py::parse_concept_with_multiplicity"]
+param = "concept_ref_or_code"
+rationale = "Verb-object: parses the ref-or-code; single operand."
+
+["pipelex/core/qualified_ref.py::QualifiedRef.has_cross_package_prefix"]
+param = "raw"
+rationale = "Predicate on the raw ref string; single operand."
+
+["pipelex/core/qualified_ref.py::QualifiedRef.is_address_based_alias"]
+param = "alias"
+rationale = "Predicate on the alias; single operand."
+
+["pipelex/core/qualified_ref.py::QualifiedRef.is_external_to"]
+param = "domain"
+rationale = "Predicate against the domain; single operand."
+
+["pipelex/core/qualified_ref.py::QualifiedRef.is_local_to"]
+param = "domain"
+rationale = "Predicate against the domain; single operand."
+
+["pipelex/core/qualified_ref.py::QualifiedRef.parse"]
+param = "raw"
+rationale = "Verb-object: parses the raw ref string; options stay keyword."
+
+["pipelex/core/qualified_ref.py::QualifiedRef.parse_concept_ref"]
+param = "raw"
+rationale = "Verb-object: parses the raw ref string; options stay keyword."
+
+["pipelex/core/qualified_ref.py::QualifiedRef.parse_pipe_ref"]
+param = "raw"
+rationale = "Verb-object: parses the raw ref string; options stay keyword."
+
+["pipelex/core/qualified_ref.py::QualifiedRef.parse_stripping_cross_package"]
+param = "raw"
+rationale = "Verb-object: parses the raw ref string; options stay keyword."
+
+["pipelex/core/qualified_ref.py::QualifiedRef.split_cross_package_ref"]
+param = "raw"
+rationale = "Verb-object: splits the raw ref string; single operand."
+
+["pipelex/core/stuffs/date_content.py::_is_numeric_string"]
+param = "text"
+rationale = "Predicate on the text; single operand."
+
+["pipelex/core/stuffs/html_rendering.py::render_value_html"]
+param = "value"
+rationale = "Verb-object: renders the value; single operand."
+
+["pipelex/core/stuffs/image_field_search.py::check_generic_container_for_images"]
+param = "container_type"
+rationale = "Verb-object: inspects the container type; context stays keyword."
+
+["pipelex/core/stuffs/image_field_search.py::search_for_nested_image_fields"]
+param = "content_class"
+rationale = "Verb-object: scans the content class; context stays keyword."
+
+["pipelex/core/stuffs/list_content.py::ListContent.get_items"]
+param = "item_type"
+rationale = "Type-directed accessor: the target item type; single operand."
+
+["pipelex/core/stuffs/structured_content.py::StructuredContent._render_value_with_images"]
+param = "value"
+rationale = "Transforms the value; rendering context stays keyword."
+
+["pipelex/core/stuffs/stuff.py::Stuff.as_list_of_fixed_content_type"]
+param = "item_type"
+rationale = "Type-directed accessor: the target item type; single operand."
+
+["pipelex/core/stuffs/stuff.py::Stuff.content_as"]
+param = "content_type"
+rationale = "Type-directed accessor: the target content type; single operand."
+
+["pipelex/core/stuffs/stuff.py::Stuff.make_stuff_name"]
+param = "concept"
+rationale = "Derivation from the concept; single operand."
+
+["pipelex/core/stuffs/stuff.py::Stuff.verify_content_type"]
+param = "content"
+rationale = "Verb-object: verifies the content; expected type stays keyword."
+
+["pipelex/core/stuffs/stuff_artefact.py::StuffArtefact.get"]
+param = "key"
+rationale = "Mapping-protocol getter keyed by the key; single operand."
+
+["pipelex/core/stuffs/stuff_content_factory.py::StuffContentFactory._make_date_content"]
+param = "date_subclass"
+rationale = "Type-directed factory: the subclass selects the product; the value stays keyword."
+
+["pipelex/core/stuffs/stuff_content_factory.py::StuffContentFactory._make_time_content"]
+param = "time_subclass"
+rationale = "Type-directed factory: the subclass selects the product; the value stays keyword."
+
+["pipelex/core/stuffs/stuff_content_factory.py::StuffContentFactory._parse_iso_temporal"]
+param = "value"
+rationale = "Parser: the value string is the single operand."
+
+["pipelex/core/stuffs/stuff_content_factory.py::StuffContentFactory.make_stuff_content_from_concept_required"]
+param = "concept"
+rationale = "Factory keyed by the concept; the value stays keyword."
+
+["pipelex/core/stuffs/stuff_content_factory.py::StuffContentFactory.make_stuff_content_from_concept_with_fallback"]
+param = "concept"
+rationale = "Factory keyed by the concept; the value stays keyword."
+
+["pipelex/core/stuffs/stuff_factory.py::StuffFactory._try_make_csv_list_stuff"]
+param = "concept"
+rationale = "Factory keyed by the concept; the value stays keyword."
+
+["pipelex/core/stuffs/stuff_factory.py::StuffFactory.combine_stuffs"]
+param = "stuff_contents"
+rationale = "Verb-object: combines the stuff contents; options stay keyword."
+
+["pipelex/core/stuffs/stuff_factory.py::StuffFactory.make_from_blueprint"]
+param = "blueprint"
+rationale = "Factory from source: builds the stuff from the blueprint; single operand."
+
+["pipelex/core/stuffs/stuff_factory.py::StuffFactory.make_from_concept_ref"]
+param = "concept_ref"
+rationale = "Factory keyed by the concept ref; the value stays keyword."
+
+["pipelex/core/stuffs/stuff_factory.py::StuffFactory.make_from_str"]
+param = "str_value"
+rationale = "Factory from source: builds from the string value; options stay keyword."
+
+["pipelex/core/stuffs/stuff_factory.py::StuffFactory.make_stuff"]
+param = "concept"
+rationale = "Factory keyed by the concept; content and name stay keyword."
+
+["pipelex/core/stuffs/stuff_factory.py::StuffFactory.make_stuff_from_stuff_content_or_data"]
+param = "stuff_content_or_data"
+rationale = "Factory from source: builds from the content-or-data; options stay keyword."
+
+["pipelex/core/stuffs/stuff_factory.py::StuffFactory.make_stuff_name"]
+param = "concept"
+rationale = "Derivation from the concept; single operand."
+
+["pipelex/core/stuffs/stuff_factory.py::StuffFactory.try_make_csv_list_content"]
+param = "concept"
+rationale = "Factory keyed by the concept; the content stays keyword."
+
+["pipelex/core/stuffs/stuff_viewer.py::_get_html_tab_label"]
+param = "content_type"
+rationale = "Derivation from the content type; single operand."
+
+["pipelex/core/stuffs/stuff_viewer.py::render_stuff_content_viewer"]
+param = "stuff_data"
+rationale = "Verb-object: renders the stuff data; options stay keyword."
+
+["pipelex/core/stuffs/stuff_viewer.py::render_stuff_viewer"]
+param = "stuff"
+rationale = "Verb-object: renders the stuff; options stay keyword."
+
+["pipelex/errors/error_pages_generator.py::_group_by_subsystem"]
+param = "classes"
+rationale = "Verb-object: groups the error classes; single operand."
+
+["pipelex/errors/error_pages_generator.py::_humanize_subsystem"]
+param = "key"
+rationale = "Transforms the subsystem key into a human heading; single operand."
+
+["pipelex/errors/error_pages_generator.py::_is_production_subclass"]
+param = "cls"
+rationale = "Predicate on the error class; single operand."
+
+["pipelex/errors/error_pages_generator.py::_parent_link"]
+param = "cls"
+rationale = "Derivation from the error class ('the parent link of cls'); single operand."
+
+["pipelex/errors/error_pages_generator.py::_remove_orphans"]
+param = "output_dir"
+rationale = "Verb-object: prunes the output dir; expected stems and report stay keyword."
+
+["pipelex/errors/error_pages_generator.py::_resolve_class_level_domain"]
+param = "cls"
+rationale = "Derivation from the error class; single operand."
+
+["pipelex/errors/error_pages_generator.py::_resolve_class_level_user_action"]
+param = "cls"
+rationale = "Derivation from the error class; single operand."
+
+["pipelex/errors/error_pages_generator.py::_short_docstring"]
+param = "cls"
+rationale = "Derivation from the error class; single operand."
+
+["pipelex/errors/error_pages_generator.py::_subsystem_key"]
+param = "cls"
+rationale = "Derivation from the error class; single operand."
+
+["pipelex/errors/error_pages_generator.py::has_authored_marker"]
+param = "content"
+rationale = "Predicate on the page content; single operand."
+
+["pipelex/errors/error_pages_generator.py::page_slug"]
+param = "cls"
+rationale = "Derivation from the error class ('the page slug of cls'); single operand."
+
+["pipelex/errors/error_pages_generator.py::render_error_page"]
+param = "cls"
+rationale = "Verb-object: renders the page for the error class; single operand."
+
+["pipelex/errors/error_pages_generator.py::render_index_page"]
+param = "by_subsystem"
+rationale = "Verb-object: renders the index from the subsystem grouping; single operand."
+
+["pipelex/graph/graph_analysis.py::GraphAnalysis.from_graphspec"]
+param = "graph"
+rationale = "Factory from source: builds the analysis from the graph spec; single operand."
+
+["pipelex/graph/graph_analysis.py::GraphAnalysis.get_children"]
+param = "node_id"
+rationale = "Query accessor keyed by the node it inspects; single operand."
+
+["pipelex/graph/graph_analysis.py::GraphAnalysis.get_consumers"]
+param = "digest"
+rationale = "Query accessor keyed by the stuff digest it inspects; single operand."
+
+["pipelex/graph/graph_analysis.py::GraphAnalysis.get_producer"]
+param = "digest"
+rationale = "Query accessor keyed by the stuff digest it inspects; single operand."
+
+["pipelex/graph/graph_analysis.py::GraphAnalysis.get_stuff_info"]
+param = "digest"
+rationale = "Query accessor keyed by the stuff digest it inspects; single operand."
+
+["pipelex/graph/graph_analysis.py::GraphAnalysis.is_controller"]
+param = "node_id"
+rationale = "Predicate on the node named by the id; single operand."
+
+["pipelex/graph/graph_analysis.py::GraphAnalysis.is_root"]
+param = "node_id"
+rationale = "Predicate on the node named by the id; single operand."
+
+["pipelex/graph/graph_factory.py::generate_graph_outputs"]
+param = "graph_spec"
+rationale = "Verb-object: generates outputs from the graph spec; rendering options stay keyword."
+
+["pipelex/graph/graph_factory.py::save_graph_outputs_to_dir"]
+param = "graph_outputs"
+rationale = "Verb-object: saves the graph outputs; destination stays keyword."
+
+["pipelex/graph/graph_rendering.py::_dry_run_bundle"]
+param = "bundle_path"
+rationale = "Verb-object: dry-runs the bundle at the path; options stay keyword."
+
+["pipelex/graph/graph_rendering.py::_sanitize_graph_name"]
+param = "graph_name"
+rationale = "Transforms the graph name; single operand."
+
+["pipelex/graph/graph_rendering.py::generate_graph_for_bundle"]
+param = "bundle_path"
+rationale = "Verb-object: generates the graph for the bundle at the path; options stay keyword."
+
+["pipelex/graph/graph_rendering.py::generate_view_for_bundle"]
+param = "bundle_path"
+rationale = "Verb-object: generates the view for the bundle at the path; options stay keyword."
+
+["pipelex/graph/graph_rendering.py::render_graph_from_spec"]
+param = "graph_spec"
+rationale = "Verb-object: renders from the graph spec; options stay keyword."
+
+["pipelex/graph/graph_tracer.py::GraphTracer._emit_event"]
+param = "event"
+rationale = "Verb-object: emits the trace event; single operand."
+
+["pipelex/graph/graph_tracer_manager.py::GraphTracerManager._get_tracer"]
+param = "graph_id"
+rationale = "Manager getter keyed by the tracer's graph id; single operand."
+
+["pipelex/graph/graph_tracer_manager.py::GraphTracerManager.close_tracer"]
+param = "tracer_key"
+rationale = "Verb-object: closes the tracer named by the key; single operand."
+
+["pipelex/graph/graph_tracer_manager.py::GraphTracerManager.get_instance_tracer"]
+param = "lookup_key"
+rationale = "Manager getter keyed by the tracer's lookup key; single operand."
+
+["pipelex/graph/graph_tracer_manager.py::GraphTracerManager.get_tracer"]
+param = "graph_id"
+rationale = "Manager getter keyed by the tracer's graph id; single operand."
+
+["pipelex/graph/graph_tracer_manager.py::GraphTracerManager.on_pipe_start"]
+param = "trace_context"
+rationale = "Event handler: the trace context being handled; event fields stay keyword."
+
+["pipelex/graph/graph_tracer_manager.py::GraphTracerManager.open_tracer"]
+param = "graph_id"
+rationale = "Verb-object: opens the tracer for the graph id; config stays keyword."
+
+["pipelex/graph/graph_tracer_protocol.py::GraphTracerProtocol.on_pipe_end_error"]
+param = "node_id"
+rationale = "Protocol event handler: the node whose run ended; event fields stay keyword."
+
+["pipelex/graph/graph_tracer_protocol.py::GraphTracerProtocol.on_pipe_end_skipped"]
+param = "node_id"
+rationale = "Protocol event handler keyed by node_id; details stay keyword."
+
+["pipelex/graph/graph_tracer_protocol.py::GraphTracerProtocol.on_pipe_end_success"]
+param = "node_id"
+rationale = "Protocol event handler: the node whose run ended; event fields stay keyword."
+
+["pipelex/graph/graph_tracer_protocol.py::GraphTracerProtocol.on_pipe_start"]
+param = "trace_context"
+rationale = "Protocol event handler: the trace context being handled; event fields stay keyword."
+
+["pipelex/graph/graphspec.py::_truncate_string"]
+param = "value"
+rationale = "Transforms the value; max_length stays keyword."
+
+["pipelex/graph/mermaidflow/mermaid_html.py::render_mermaid_html"]
+param = "mermaid_code"
+rationale = "Verb-object: renders the mermaid code; presentation options stay keyword."
+
+["pipelex/graph/mermaidflow/mermaid_html.py::render_mermaid_html_async"]
+param = "mermaid_code"
+rationale = "Verb-object: renders the mermaid code; presentation options stay keyword."
+
+["pipelex/graph/mermaidflow/mermaid_html.py::render_mermaid_html_with_data_async"]
+param = "mermaid_code"
+rationale = "Verb-object: renders the mermaid code; data payloads stay keyword."
+
+["pipelex/graph/mermaidflow/mermaidflow_factory.py::MermaidflowFactory._get_node_label"]
+param = "node"
+rationale = "Derivation from the node spec; single operand."
+
+["pipelex/graph/mermaidflow/mermaidflow_factory.py::MermaidflowFactory._render_dashed_edges"]
+param = "edges"
+rationale = "Verb-object: renders the edges; accumulators stay keyword."
+
+["pipelex/graph/mermaidflow/mermaidflow_factory.py::MermaidflowFactory._render_node"]
+param = "node"
+rationale = "Verb-object: renders the node; rendering context stays keyword."
+
+["pipelex/graph/mermaidflow/mermaidflow_factory.py::MermaidflowFactory._render_stuff_node"]
+param = "digest"
+rationale = "Verb-object: renders the stuff node identified by the digest; display fields stay keyword."
+
+["pipelex/graph/mermaidflow/mermaidflow_factory.py::MermaidflowFactory._render_subgraph_recursive"]
+param = "node_id"
+rationale = "Verb-object: renders the subgraph rooted at the node id; lookup maps stay keyword."
+
+["pipelex/graph/mermaidflow/mermaidflow_factory.py::MermaidflowFactory.make_from_graphspec"]
+param = "graph"
+rationale = "Factory from source: builds the diagram from the graph spec; options stay keyword."
+
+["pipelex/graph/mermaidflow/mermaidflow_utils.py::make_stuff_id"]
+param = "digest"
+rationale = "Derivation: encodes the digest into a node id; single operand."
+
+["pipelex/graph/mermaidflow/stuff_collector.py::_collect_stuff_field"]
+param = "graph"
+rationale = "Verb-object: collects from the graph; the extractor stays keyword."
+
+["pipelex/graph/mermaidflow/stuff_collector.py::collect_stuff_content_type"]
+param = "graph"
+rationale = "Verb-object: collects from the graph; single operand."
+
+["pipelex/graph/mermaidflow/stuff_collector.py::collect_stuff_data"]
+param = "graph"
+rationale = "Verb-object: collects from the graph; single operand."
+
+["pipelex/graph/mermaidflow/stuff_collector.py::collect_stuff_data_html"]
+param = "graph"
+rationale = "Verb-object: collects from the graph; single operand."
+
+["pipelex/graph/mermaidflow/stuff_collector.py::collect_stuff_data_text"]
+param = "graph"
+rationale = "Verb-object: collects from the graph; single operand."
+
+["pipelex/graph/mermaidflow/stuff_collector.py::collect_stuff_metadata"]
+param = "graph"
+rationale = "Verb-object: collects from the graph; single operand."
+
+["pipelex/graph/mermaidflow/stuff_collector.py::collect_stuff_metadata.extract_metadata"]
+param = "io_spec"
+rationale = "Positional Callable protocol: passed as the extractor callback, invoked extractor(io_spec)."
+
+["pipelex/graph/reactflow/reactflow_html.py::_build_templating_context"]
+param = "graphspec"
+rationale = "Builds the context from the graph spec; config and title stay keyword."
+
+["pipelex/graph/reactflow/reactflow_html.py::_build_viewer_config"]
+param = "config"
+rationale = "Derives the viewer dict from the rendering config; single operand."
+
+["pipelex/graph/reactflow/reactflow_html.py::generate_reactflow_html"]
+param = "graphspec"
+rationale = "Verb-object: renders the graph spec to HTML; options stay keyword."
+
+["pipelex/graph/reactflow/reactflow_html.py::generate_reactflow_html_async"]
+param = "graphspec"
+rationale = "Verb-object: renders the graph spec to HTML; options stay keyword."
+
+["pipelex/graph/trace_context.py::TraceContext.copy_for_child"]
+param = "child_node_id"
+rationale = "Verb-object: copies the context for the child node; sequence stays keyword."
+
+["pipelex/graph/validation.py::_validate_edge_references"]
+param = "graph"
+rationale = "Verb-object: validates the graph; single operand."
+
+["pipelex/graph/validation.py::_validate_failed_nodes_have_errors"]
+param = "graph"
+rationale = "Verb-object: validates the graph; single operand."
+
+["pipelex/graph/validation.py::_validate_unique_edge_ids"]
+param = "graph"
+rationale = "Verb-object: validates the graph; single operand."
+
+["pipelex/graph/validation.py::_validate_unique_node_ids"]
+param = "graph"
+rationale = "Verb-object: validates the graph; single operand."
+
+["pipelex/graph/validation.py::validate_graphspec"]
+param = "graph"
+rationale = "Verb-object: validates the graph spec; single operand."
+
+["pipelex/hub.py::PipelexHub.set_bundle_validator_registry"]
+param = "bundle_validator_registry"
+rationale = "Hub setter: installs the bundle validator registry; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_class_registry"]
+param = "class_registry"
+rationale = "Hub setter: installs the class registry; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_concept_library"]
+param = "concept_library"
+rationale = "Hub setter: installs the concept library; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_config"]
+param = "config"
+rationale = "Hub setter: installs the config; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_console"]
+param = "console"
+rationale = "Hub setter: installs the console; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_console_print_target"]
+param = "target"
+rationale = "Hub setter: installs the print target; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_content_generator"]
+param = "content_generator"
+rationale = "Hub setter: installs the content generator; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_default_library_dirs"]
+param = "library_dirs"
+rationale = "Hub setter: installs the default library dirs; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_domain_library"]
+param = "domain_library"
+rationale = "Hub setter: installs the domain library; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_func_registry"]
+param = "func_registry"
+rationale = "Hub setter: installs the func registry; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_inference_backend_registry"]
+param = "inference_backend_registry"
+rationale = "Hub setter: installs the inference backend registry; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_inference_manager"]
+param = "inference_manager"
+rationale = "Hub setter: installs the inference manager; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_instance"]
+param = "pipelex_hub"
+rationale = "Hub setter: installs the hub singleton; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_isolated_execution_probe"]
+param = "probe"
+rationale = "Hub setter: installs the execution probe; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_library_manager"]
+param = "library_manager"
+rationale = "Hub setter: installs the library manager; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_model_lister_registry"]
+param = "model_lister_registry"
+rationale = "Hub setter: installs the model lister registry; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_models_manager"]
+param = "models_manager"
+rationale = "Hub setter: installs the models manager; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_observer"]
+param = "observer"
+rationale = "Hub setter: installs the observer; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_orchestrator_registry"]
+param = "orchestrator_registry"
+rationale = "Hub setter: installs the orchestrator registry; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_pipe_library"]
+param = "pipe_library"
+rationale = "Hub setter: installs the pipe library; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_pipe_router"]
+param = "pipe_router"
+rationale = "Hub setter: installs the pipe router; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_pipe_run"]
+param = "pipe_run"
+rationale = "Hub setter: installs the pipe-run holder; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_pipeline_manager"]
+param = "pipeline_manager"
+rationale = "Hub setter: installs the pipeline manager; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_report_delegate"]
+param = "reporting_delegate"
+rationale = "Hub setter: installs the reporting delegate; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_sdk_client_manager"]
+param = "sdk_client_manager"
+rationale = "Hub setter: installs the SDK client manager; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_secrets_provider"]
+param = "secrets_provider"
+rationale = "Hub setter: installs the secrets provider; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_secrets_provider_registry"]
+param = "secrets_provider_registry"
+rationale = "Hub setter: the registry is the operand being installed."
+
+["pipelex/hub.py::PipelexHub.set_storage_provider"]
+param = "storage_provider"
+rationale = "Hub setter: installs the storage provider; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.set_storage_provider_registry"]
+param = "storage_provider_registry"
+rationale = "Hub setter: the registry is the operand being installed."
+
+["pipelex/hub.py::PipelexHub.set_telemetry_manager"]
+param = "telemetry_manager"
+rationale = "Hub setter: installs the telemetry manager; single self-labelling operand."
+
+["pipelex/hub.py::PipelexHub.setup_config"]
+param = "config_cls"
+rationale = "Sets up config from the given config class; single operand."
+
+["pipelex/hub.py::get_extract_worker"]
+param = "extract_handle"
+rationale = "Hub getter keyed by the worker's handle; single operand."
+
+["pipelex/hub.py::get_img_gen_worker"]
+param = "img_gen_handle"
+rationale = "Hub getter keyed by the worker's handle; single operand."
+
+["pipelex/hub.py::get_llm_worker"]
+param = "llm_handle"
+rationale = "Hub getter keyed by the worker's handle; single operand."
+
+["pipelex/hub.py::get_native_concept"]
+param = "native_concept"
+rationale = "Hub getter: the native concept being fetched; single operand."
+
+["pipelex/hub.py::get_optional_domain"]
+param = "domain_code"
+rationale = "Hub getter keyed by the domain code; single operand."
+
+["pipelex/hub.py::get_optional_pipe"]
+param = "pipe_code"
+rationale = "Hub getter keyed by the pipe code; single operand."
+
+["pipelex/hub.py::get_pipe_source"]
+param = "pipe_code"
+rationale = "Hub getter keyed by the pipe code; single operand."
+
+["pipelex/hub.py::get_pipeline"]
+param = "pipeline_run_id"
+rationale = "Hub getter keyed by the pipeline run id; single operand."
+
+["pipelex/hub.py::get_required_concept"]
+param = "concept_ref"
+rationale = "Hub getter keyed by the concept ref; single operand."
+
+["pipelex/hub.py::get_required_domain"]
+param = "domain_code"
+rationale = "Hub getter keyed by the domain code; single operand."
+
+["pipelex/hub.py::get_required_pipe"]
+param = "pipe_code"
+rationale = "Hub getter keyed by the pipe code; single operand."
+
+["pipelex/hub.py::get_secret"]
+param = "secret_id"
+rationale = "Hub getter keyed by the secret id; single operand."
+
+["pipelex/hub.py::resolve_library_dirs"]
+param = "library_dirs"
+rationale = "Verb-object: resolves the given library dirs; single operand."
+
+["pipelex/hub.py::scoped_content_generator"]
+param = "content_generator"
+rationale = "Context manager scoping the given content generator; single self-labelling operand."
+
+["pipelex/hub.py::scoped_current_library"]
+param = "library_id"
+rationale = "Context manager scoping to the library named by the id; single operand."
+
+["pipelex/hub.py::scoped_event_log"]
+param = "event_log"
+rationale = "Context manager scoping the given event log; single self-labelling operand."
+
+["pipelex/hub.py::scoped_pipe_router"]
+param = "pipe_router"
+rationale = "Context manager scoping the given pipe router; single self-labelling operand."
+
+["pipelex/hub.py::set_current_library"]
+param = "library_id"
+rationale = "Module-level setter: selects the library named by the id; single operand."
+
+["pipelex/hub.py::set_pipe_router"]
+param = "pipe_router"
+rationale = "Module-level setter: installs the pipe router; single self-labelling operand."
+
+["pipelex/hub.py::set_pipelex_hub"]
+param = "pipelex_hub"
+rationale = "Module-level setter: installs the hub singleton; single self-labelling operand."
+
+["pipelex/kit/cursor_rules.py::_is_pipelex_managed"]
+param = "mdc_path"
+rationale = "Predicate on the .mdc file path; single operand."
+
+["pipelex/kit/cursor_rules.py::_iter_agent_files"]
+param = "agents_dir"
+rationale = "Verb-object: iterates the agents dir; single operand."
+
+["pipelex/kit/cursor_rules.py::remove_cursor_rules"]
+param = "repo_root"
+rationale = "Verb-object: the repo root being cleaned; kit_index stays keyword."
+
+["pipelex/kit/cursor_rules.py::update_cursor_rules"]
+param = "repo_root"
+rationale = "Verb-object: the repo root being updated; kit context stays keyword."
+
+["pipelex/kit/single_file_agent_rules.py::_demote_headings"]
+param = "md_content"
+rationale = "Verb-object: transforms the markdown content; levels stays keyword."
+
+["pipelex/kit/single_file_agent_rules.py::_demote_headings.demote_match"]
+param = "match"
+rationale = "Positional Callable protocol: re.sub replacement callback, invoked repl(match)."
+
+["pipelex/kit/single_file_agent_rules.py::remove_from_targets"]
+param = "repo_root"
+rationale = "Verb-object: the repo root being cleaned; options stay keyword."
+
+["pipelex/kit/single_file_agent_rules.py::update_single_file_agent_rules"]
+param = "repo_root"
+rationale = "Verb-object: the repo root being updated; options stay keyword."
+
+["pipelex/language/mthds_factory.py::MthdsFactory.add_spaces_to_inline_tables"]
+param = "toml_string"
+rationale = "Verb-object: transforms the TOML string; single operand."
+
+["pipelex/language/mthds_factory.py::MthdsFactory.add_spaces_to_inline_tables.find_and_replace_inline_tables"]
+param = "text"
+rationale = "Nested helper transforming the text; single operand."
+
+["pipelex/language/mthds_factory.py::MthdsFactory.convert_dicts_to_inline_tables"]
+param = "value"
+rationale = "Conversion: the value being recursively converted; field_ordering stays keyword."
+
+["pipelex/language/mthds_factory.py::MthdsFactory.convert_mapping_to_table"]
+param = "mapping"
+rationale = "Conversion: the mapping being converted to a table; field_ordering stays keyword."
+
+["pipelex/language/mthds_factory.py::MthdsFactory.dict_to_mthds_styled_toml"]
+param = "data"
+rationale = "Conversion: the data dict being rendered to styled TOML; single operand."
+
+["pipelex/language/mthds_factory.py::MthdsFactory.format_tomlkit_string"]
+param = "text"
+rationale = "Verb-object: formats the text as a tomlkit string node; single operand."
+
+["pipelex/language/mthds_factory.py::MthdsFactory.make_construct_table"]
+param = "construct_value"
+rationale = "Factory from source: builds the table from the construct mapping; single operand."
+
+["pipelex/language/mthds_factory.py::MthdsFactory.make_mthds_content"]
+param = "blueprint"
+rationale = "Factory from source: renders the bundle blueprint to .mthds content; single operand."
+
+["pipelex/language/mthds_factory.py::MthdsFactory.make_table_obj_for_concept"]
+param = "section_value"
+rationale = "Factory from source: builds the table from the concept section mapping; single operand."
+
+["pipelex/language/mthds_factory.py::MthdsFactory.make_table_obj_for_pipe"]
+param = "section_value"
+rationale = "Factory from source: builds the table from the pipe section mapping; single operand."
+
+["pipelex/language/mthds_factory.py::MthdsFactory.make_template_table"]
+param = "template_value"
+rationale = "Factory from source: builds the table from the template mapping; single operand."
+
+["pipelex/language/mthds_schema_generator.py::_add_taplo_metadata"]
+param = "schema"
+rationale = "Schema-pipeline stage transforming the schema dict; single operand."
+
+["pipelex/language/mthds_schema_generator.py::_convert_to_draft4"]
+param = "schema"
+rationale = "Schema-pipeline stage transforming the schema dict; single operand."
+
+["pipelex/language/mthds_schema_generator.py::_draft4_visitor"]
+param = "node"
+rationale = "Positional Callable protocol: passed as _walk_schema visitor, invoked visitor(node)."
+
+["pipelex/language/mthds_schema_generator.py::_normalize_type_on_pipe_definitions"]
+param = "schema"
+rationale = "Single-operand transformation of the schema."
+
+["pipelex/language/mthds_schema_generator.py::_patch_construct_schema"]
+param = "schema"
+rationale = "Schema-pipeline stage transforming the schema dict; single operand."
+
+["pipelex/language/mthds_schema_generator.py::_promote_schema_required_fields"]
+param = "schema"
+rationale = "Schema-pipeline stage transforming the schema dict; single operand."
+
+["pipelex/language/mthds_schema_generator.py::_remove_from_required"]
+param = "schema_obj"
+rationale = "Verb-object: mutates the schema object's required list; field_names stays keyword."
+
+["pipelex/language/mthds_schema_generator.py::_remove_internal_fields"]
+param = "schema"
+rationale = "Schema-pipeline stage transforming the schema dict; single operand."
+
+["pipelex/language/mthds_schema_generator.py::_walk_schema"]
+param = "node"
+rationale = "Verb-object: walks the schema node tree; the visitor stays keyword."
+
+["pipelex/language/toml_string_utils.py::format_toml_string"]
+param = "text"
+rationale = "Verb-object: formats the text; formatting options stay keyword."
+
+["pipelex/libraries/concept/concept_library.py::ConceptLibrary.get_optional_concept"]
+param = "concept_ref"
+rationale = "Library getter keyed by the concept ref; single operand."
+
+["pipelex/libraries/concept/concept_library.py::ConceptLibrary.is_concept_exists"]
+param = "concept_ref"
+rationale = "Predicate on the concept named by the ref; single operand."
+
+["pipelex/libraries/concept/concept_library.py::ConceptLibrary.set_concept_resolver"]
+param = "resolver"
+rationale = "Setter: installs the resolver; single self-labelling operand."
+
+["pipelex/libraries/concept/concept_library_abstract.py::ConceptLibraryAbstract.add_concepts"]
+param = "concepts"
+rationale = "Verb-object: adds the concepts; single operand."
+
+["pipelex/libraries/concept/concept_library_abstract.py::ConceptLibraryAbstract.add_new_concept"]
+param = "concept"
+rationale = "Verb-object: adds the concept; single operand."
+
+["pipelex/libraries/concept/concept_library_abstract.py::ConceptLibraryAbstract.get_native_concept"]
+param = "native_concept"
+rationale = "Library getter: the native concept being fetched; single operand."
+
+["pipelex/libraries/concept/concept_library_abstract.py::ConceptLibraryAbstract.get_required_concept"]
+param = "concept_ref"
+rationale = "Library getter keyed by the concept ref; single operand."
+
+["pipelex/libraries/concept/concept_library_abstract.py::ConceptLibraryAbstract.get_required_concept_from_concept_ref_or_code"]
+param = "concept_ref_or_code"
+rationale = "Library getter keyed by the ref-or-code; single operand."
+
+["pipelex/libraries/concept/concept_library_abstract.py::ConceptLibraryAbstract.list_concepts_by_domain"]
+param = "domain_code"
+rationale = "Query keyed by the domain code it lists; single operand."
+
+["pipelex/libraries/concept/concept_library_abstract.py::ConceptLibraryAbstract.remove_concepts_by_concept_refs"]
+param = "concept_refs"
+rationale = "Verb-object: the refs naming the removed concepts; single operand."
+
+["pipelex/libraries/concept_reference_validation.py::_split_concept_ref_context"]
+param = "context"
+rationale = "Transforms the context string; single operand."
+
+["pipelex/libraries/concept_reference_validation.py::validate_concept_references_in_blueprints"]
+param = "blueprints"
+rationale = "Verb-object: validates refs within the blueprints; single operand."
+
+["pipelex/libraries/contract_match.py::_canonical_concept_spec"]
+param = "spec"
+rationale = "Derivation: canonicalizes the spec; single operand."
+
+["pipelex/libraries/crate_normalization.py::_domain_of"]
+param = "qualified_ref"
+rationale = "Noun-named derivation: parses the domain out of the qualified ref."
+
+["pipelex/libraries/crate_normalization.py::_flatten_refinement"]
+param = "concepts"
+rationale = "Verb-object: flattens the concepts mapping in place; single operand."
+
+["pipelex/libraries/crate_normalization.py::_io_ref_concept"]
+param = "io_ref"
+rationale = "Noun-named derivation: the concept part of the io ref; single operand."
+
+["pipelex/libraries/crate_normalization.py::_native_effective_structure"]
+param = "native_ref"
+rationale = "Noun-named derivation: the effective structure for the native ref; single operand."
+
+["pipelex/libraries/crate_normalization.py::_normalize_concept"]
+param = "value"
+rationale = "Single-operand normalization of the concept entry; the rest is context."
+
+["pipelex/libraries/crate_normalization.py::_normalize_pipe"]
+param = "blueprint"
+rationale = "Single-operand normalization of the pipe blueprint; owner_domain is context."
+
+["pipelex/libraries/crate_normalization.py::_qualify_concept_ref"]
+param = "concept_ref_or_code"
+rationale = "Single-operand transformation of the ref; domain is context."
+
+["pipelex/libraries/crate_normalization.py::_qualify_io_ref"]
+param = "io_ref"
+rationale = "Single-operand transformation of the ref; domain is context."
+
+["pipelex/libraries/crate_normalization.py::_qualify_pipe_ref"]
+param = "pipe_ref"
+rationale = "Single-operand transformation of the ref; domain is context."
+
+["pipelex/libraries/crate_normalization.py::_qualify_structure_field"]
+param = "field_blueprint"
+rationale = "Single-operand transformation of the field blueprint; domain is context."
+
+["pipelex/libraries/crate_normalization.py::_render_ref_with_markers"]
+param = "concept_ref"
+rationale = "Verb-object: renders the ref; parsed markers stay keyword."
+
+["pipelex/libraries/crate_normalization.py::_resolve_refinement"]
+param = "concept_ref"
+rationale = "Verb-object: resolves the concept ref; concepts and cache are context."
+
+["pipelex/libraries/crate_normalization.py::normalize_crate"]
+param = "crate"
+rationale = "Verb-object: normalizes the crate; mthds_version stays keyword."
+
+["pipelex/libraries/domain/domain_library.py::DomainLibrary.add_domain"]
+param = "domain"
+rationale = "Verb-object: adds the domain; single operand."
+
+["pipelex/libraries/domain/domain_library.py::DomainLibrary.add_domains"]
+param = "domains"
+rationale = "Verb-object: adds the domains; single operand."
+
+["pipelex/libraries/domain/domain_library.py::DomainLibrary.remove_domain_by_code"]
+param = "domain_code"
+rationale = "Verb-object: the code naming the removed domain; single operand."
+
+["pipelex/libraries/domain/domain_library_abstract.py::DomainLibraryAbstract.get_domain"]
+param = "domain_code"
+rationale = "Library getter keyed by the domain code; single operand."
+
+["pipelex/libraries/domain/domain_library_abstract.py::DomainLibraryAbstract.get_required_domain"]
+param = "domain_code"
+rationale = "Library getter keyed by the domain code; single operand."
+
+["pipelex/libraries/library.py::Library._has_unresolved_cross_package_deps"]
+param = "pipe"
+rationale = "Predicate on the pipe; single operand."
+
+["pipelex/libraries/library.py::Library.get_dependency_library"]
+param = "alias"
+rationale = "Library getter keyed by the dependency alias; single operand."
+
+["pipelex/libraries/library.py::Library.resolve_concept"]
+param = "concept_ref"
+rationale = "Verb-object: resolves the concept ref; single operand."
+
+["pipelex/libraries/library.py::Library.set_class_registry"]
+param = "class_registry"
+rationale = "Setter: installs the class registry; single self-labelling operand."
+
+["pipelex/libraries/library_crate.py::_strip_source"]
+param = "dumped"
+rationale = "Single-operand transformation of the dumped mapping."
+
+["pipelex/libraries/library_crate_factory.py::LibraryCrateFactory._contract_mismatch_msg"]
+param = "pipe_ref"
+rationale = "Builds the message for the colliding pipe ref; the declarations stay keyword."
+
+["pipelex/libraries/library_crate_factory.py::LibraryCrateFactory._declaration_sort_key"]
+param = "declaration"
+rationale = "Sort-key function over the declaration; single operand."
+
+["pipelex/libraries/library_crate_factory.py::LibraryCrateFactory._reconcile_pipe_collision"]
+param = "pipe_ref"
+rationale = "Verb-object: reconciles the collision at the pipe ref; the colliding declarations stay keyword."
+
+["pipelex/libraries/library_crate_factory.py::LibraryCrateFactory.make_from_blueprints"]
+param = "blueprints"
+rationale = "Factory from source: builds the crate from the blueprints; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._check_package_visibility"]
+param = "blueprints"
+rationale = "Verb-object: checks visibility across the blueprints; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._detect_concept_cycles"]
+param = "concepts"
+rationale = "Verb-object: detects cycles among the concepts; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._detect_concept_cycles.check_for_cycle"]
+param = "concept_ref"
+rationale = "Nested DFS visitor on the concept ref; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._detect_concept_cycles.get_referenced_concepts"]
+param = "concept"
+rationale = "Nested helper: reads the concept's references; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._detect_concept_cycles.get_referenced_concepts.extract_type_names"]
+param = "annotation"
+rationale = "Nested helper: extracts names from the annotation; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._find_package_root"]
+param = "mthds_paths"
+rationale = "Derivation: finds the root of the given paths; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._load_address_based_dependency"]
+param = "library"
+rationale = "Verb-object: loads the dependency library object; context stays keyword."
+
+["pipelex/libraries/library_manager.py::LibraryManager._load_concepts_from_blueprints"]
+param = "blueprints"
+rationale = "Verb-object: loads concepts from the blueprints; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._load_concepts_from_crate"]
+param = "concepts"
+rationale = "Verb-object: loads the crate concepts; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._load_single_dependency"]
+param = "library"
+rationale = "Verb-object: loads the dependency library object; context stays keyword."
+
+["pipelex/libraries/library_manager.py::LibraryManager._pop_and_teardown_library"]
+param = "library_id"
+rationale = "Verb-object: pops and tears down the library named by the id; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._rebuild_models_with_forward_refs"]
+param = "concepts"
+rationale = "Verb-object: rebuilds the given concepts' models; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._remove_concepts_from_blueprint"]
+param = "blueprint"
+rationale = "Verb-object: strips concepts from the blueprint; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._remove_pipes_from_blueprint"]
+param = "blueprint"
+rationale = "Verb-object: strips pipes from the blueprint; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._topological_load_concepts"]
+param = "ref_to_entry"
+rationale = "Verb-object: loads the ref-to-entry mapping in topological order; single operand."
+
+["pipelex/libraries/library_manager.py::LibraryManager._warn_if_mthds_version_unsatisfied"]
+param = "mthds_version_constraint"
+rationale = "Predicate-style check on the version constraint; single operand."
+
+["pipelex/libraries/library_manager.py::_find_methods_dirs_from_blueprints"]
+param = "blueprints"
+rationale = "Derivation: finds dirs from the blueprints; single operand."
+
+["pipelex/libraries/library_manager_abstract.py::LibraryManagerAbstract.get_crate"]
+param = "library_id"
+rationale = "Manager getter keyed by the library id; single operand."
+
+["pipelex/libraries/library_manager_abstract.py::LibraryManagerAbstract.get_library"]
+param = "library_id"
+rationale = "Manager getter keyed by the library id; single operand."
+
+["pipelex/libraries/library_manager_abstract.py::LibraryManagerAbstract.get_library_class_registry"]
+param = "library_id"
+rationale = "Manager getter keyed by the library id; single operand."
+
+["pipelex/libraries/library_manager_abstract.py::LibraryManagerAbstract.get_pipe_source"]
+param = "pipe_code"
+rationale = "Manager getter keyed by the pipe code; single operand."
+
+["pipelex/libraries/library_manager_abstract.py::LibraryManagerAbstract.open_fresh_library"]
+param = "library_id"
+rationale = "Verb-object: opens the library named by the id; single operand."
+
+["pipelex/libraries/library_manager_abstract.py::LibraryManagerAbstract.open_library"]
+param = "library_id"
+rationale = "Verb-object: opens the library named by the id; single operand."
+
+["pipelex/libraries/library_manager_abstract.py::LibraryManagerAbstract.teardown"]
+param = "library_id"
+rationale = "Verb-object: tears down the library named by the id; single operand."
+
+["pipelex/libraries/library_utils.py::get_pipelex_mthds_files_from_dirs"]
+param = "dirs"
+rationale = "Verb-object: scans the given dirs; single operand."
+
+["pipelex/libraries/library_utils.py::get_pipelex_mthds_files_from_package._find_mthds_in_traversable"]
+param = "traversable"
+rationale = "Nested helper: scans the traversable; single operand."
+
+["pipelex/libraries/pipe/pipe_library.py::PipeLibrary.pretty_list_pipes._format_concept_code"]
+param = "concept_code"
+rationale = "Nested helper: formats the concept code; single operand."
+
+["pipelex/libraries/pipe/pipe_library_abstract.py::PipeLibraryAbstract.add_new_pipe"]
+param = "pipe"
+rationale = "Verb-object: adds the pipe; single operand."
+
+["pipelex/libraries/pipe/pipe_library_abstract.py::PipeLibraryAbstract.add_pipes"]
+param = "pipes"
+rationale = "Verb-object: adds the pipes; single operand."
+
+["pipelex/libraries/pipe/pipe_library_abstract.py::PipeLibraryAbstract.get_optional_pipe"]
+param = "pipe_code"
+rationale = "Library getter keyed by the pipe code; single operand."
+
+["pipelex/libraries/pipe/pipe_library_abstract.py::PipeLibraryAbstract.get_required_pipe"]
+param = "pipe_code"
+rationale = "Library getter keyed by the pipe code; single operand."
+
+["pipelex/libraries/pipe/pipe_library_abstract.py::PipeLibraryAbstract.remove_pipes_by_refs"]
+param = "pipe_refs"
+rationale = "Verb-object: the refs naming the removed pipes; single operand."
+
+["pipelex/libraries/visibility_utils.py::_blueprint_to_metadata"]
+param = "blueprint"
+rationale = "Conversion: derives metadata from the blueprint; single operand."
+
+["pipelex/observer/observer_protocol.py::ObserverProtocol.observe_after_failing_run"]
+param = "payload"
+rationale = "Protocol method: observes the run payload; single operand across implementations."
+
+["pipelex/observer/observer_protocol.py::ObserverProtocol.observe_after_successful_run"]
+param = "payload"
+rationale = "Protocol method: observes the run payload; single operand across implementations."
+
+["pipelex/observer/observer_protocol.py::ObserverProtocol.observe_before_run"]
+param = "payload"
+rationale = "Protocol method: observes the run payload; single operand across implementations."
+
+["pipelex/pipe_controllers/absence_taint.py::is_plural_step_result"]
+param = "pipe"
+rationale = "Predicate on the pipe's step result; modifiers stay keyword."
+
+["pipelex/pipe_controllers/absence_taint.py::scan_taint_triggers"]
+param = "pipe"
+rationale = "Verb-object: scans the pipe for taint triggers; slot_taints is context."
+
+["pipelex/pipe_controllers/batch/pipe_batch.py::PipeBatch._live_run_controller_pipe._run_branch"]
+param = "item_input_stuff"
+rationale = "Verb-object: runs the branch for the item stuff; invoked positionally via functools.partial."
+
+["pipelex/pipe_controllers/batch/pipe_batch.py::resolve_batch_max_concurrency"]
+param = "max_concurrency_setting"
+rationale = "Verb-object: resolves the config setting value; single operand, callers pass a labelled config read."
+
+["pipelex/pipe_controllers/condition/special_outcome.py::SpecialOutcome.is_continue"]
+param = "outcome"
+rationale = "Predicate on the outcome string; single operand."
+
+["pipelex/pipe_controllers/condition/special_outcome.py::SpecialOutcome.is_fail"]
+param = "outcome"
+rationale = "Predicate on the outcome string; single operand."
+
+["pipelex/pipe_controllers/sub_pipe_factory.py::SubPipeFactory.make_from_blueprint"]
+param = "blueprint"
+rationale = "Factory from source: the name names the operand; single obvious operand."
+
+["pipelex/pipe_operators/compose/construct_blueprint.py::ConstructBlueprint.make_from_raw"]
+param = "raw"
+rationale = "Factory from source: builds the blueprint from the raw value; single operand."
+
+["pipelex/pipe_operators/compose/construct_blueprint.py::ConstructFieldBlueprint.make_from_raw"]
+param = "raw"
+rationale = "Factory from source: builds the field blueprint from the raw value; single operand."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._build_field_type_summary"]
+param = "field_values"
+rationale = "Derivation from the field values; single operand."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._convert_content_for_field"]
+param = "stuff_content"
+rationale = "Verb-object: converts the stuff content; target context stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._convert_for_target_type"]
+param = "stuff_content"
+rationale = "Verb-object: converts the stuff content; target type stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._convert_list_content"]
+param = "list_content"
+rationale = "Verb-object: converts the list content; target context stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._convert_list_items_as_dicts"]
+param = "items"
+rationale = "Verb-object: converts the items; target context stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._convert_list_items_as_objects"]
+param = "items"
+rationale = "Verb-object: converts the items; target context stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._convert_list_to_dict_keyed_by"]
+param = "value"
+rationale = "Verb-object: converts the value; key field stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._convert_single_item_as_object"]
+param = "item"
+rationale = "Verb-object: converts the item; target context stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._convert_text_content"]
+param = "text_content"
+rationale = "Verb-object: converts the text content; target context stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._expects_list_content_type"]
+param = "expected_type"
+rationale = "Predicate on the expected type; single operand."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._expects_list_type"]
+param = "expected_type"
+rationale = "Predicate on the expected type; single operand."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._get_field_expected_type"]
+param = "field_name"
+rationale = "Query accessor keyed by the field it inspects; single operand."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._get_list_item_type"]
+param = "expected_type"
+rationale = "Derivation from the expected type; single operand."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._get_nested_field_class"]
+param = "field_name"
+rationale = "Query accessor keyed by the field it inspects; single operand."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._resolve_dotted_path"]
+param = "path"
+rationale = "Verb-object: resolves the dotted path; single operand."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._resolve_field"]
+param = "field_blueprint"
+rationale = "Verb-object: resolves the field blueprint; context stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._resolve_from_stuff_name"]
+param = "name"
+rationale = "Verb-object: resolves the stuff named; context stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._resolve_from_var"]
+param = "field_blueprint"
+rationale = "Verb-object: resolves the field blueprint; context stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._resolve_nested"]
+param = "field_blueprint"
+rationale = "Verb-object: resolves the field blueprint; context stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._resolve_template"]
+param = "field_blueprint"
+rationale = "Verb-object: resolves the field blueprint; context stays keyword."
+
+["pipelex/pipe_operators/compose/structured_content_composer.py::StructuredContentComposer._validate_item_compatibility"]
+param = "item"
+rationale = "Verb-object: validates the item; expectations stay keyword."
+
+["pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py::ImgGenPromptBlueprint._extract_direct_image"]
+param = "image_ref"
+rationale = "Verb-object: extracts from the image ref; context stays keyword."
+
+["pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py::ImgGenPromptBlueprint._extract_direct_list_images"]
+param = "image_ref"
+rationale = "Verb-object: extracts from the image ref; context stays keyword."
+
+["pipelex/pipe_operators/llm/helpers.py::get_output_structure_prompt"]
+param = "concept_ref"
+rationale = "Derivation keyed by the concept ref; single operand."
+
+["pipelex/pipe_operators/llm/llm_prompt_blueprint.py::LLMPromptBlueprint._extract_direct_document"]
+param = "doc_ref"
+rationale = "Verb-object: extracts from the document ref; context stays keyword."
+
+["pipelex/pipe_operators/llm/llm_prompt_blueprint.py::LLMPromptBlueprint._extract_direct_image"]
+param = "image_ref"
+rationale = "Verb-object: extracts from the image ref; context stays keyword."
+
+["pipelex/pipe_operators/llm/llm_prompt_blueprint.py::LLMPromptBlueprint._extract_direct_list_documents"]
+param = "doc_ref"
+rationale = "Verb-object: extracts from the document ref; context stays keyword."
+
+["pipelex/pipe_operators/llm/llm_prompt_blueprint.py::LLMPromptBlueprint._extract_direct_list_images"]
+param = "image_ref"
+rationale = "Verb-object: extracts from the image ref; context stays keyword."
+
+["pipelex/pipe_operators/llm/pipe_llm.py::PipeLLM._format_error_location"]
+param = "pipe_run_params"
+rationale = "Derivation from the run params; single operand."
+
+["pipelex/pipe_operators/llm/pipe_llm.py::PipeLLM._format_llm_error"]
+param = "exc"
+rationale = "Verb-object: formats the exception; context stays keyword."
+
+["pipelex/pipe_operators/llm/pipe_llm.py::PipeLLM.resolve_dynamic_output_stuff_spec"]
+param = "pipe_run_params"
+rationale = "Derivation from the run params; context stays keyword."
+
+["pipelex/pipe_operators/llm/template_document_analyzer.py::TemplateDocumentAnalyzer._resolve_concept"]
+param = "concept_ref_or_code"
+rationale = "Verb-object: resolves the ref-or-code; single operand."
+
+["pipelex/pipe_operators/llm/template_document_analyzer.py::TemplateDocumentAnalyzer._resolve_variable_type"]
+param = "var_path"
+rationale = "Query accessor keyed by the variable path; context stays keyword."
+
+["pipelex/pipe_operators/llm/template_document_analyzer.py::TemplateDocumentAnalyzer.analyze_template_for_documents"]
+param = "template_source"
+rationale = "Verb-object: analyzes the template source; context stays keyword."
+
+["pipelex/pipe_operators/shared/template_image_analyzer.py::TemplateImageAnalyzer._resolve_concept"]
+param = "concept_ref_or_code"
+rationale = "Verb-object: resolves the ref-or-code; single operand."
+
+["pipelex/pipe_operators/shared/template_image_analyzer.py::TemplateImageAnalyzer._resolve_variable_type"]
+param = "var_path"
+rationale = "Query accessor keyed by the variable path; context stays keyword."
+
+["pipelex/pipe_operators/shared/template_image_analyzer.py::TemplateImageAnalyzer.analyze_template_for_images"]
+param = "template_source"
+rationale = "Verb-object: analyzes the template source; context stays keyword."
+
+["pipelex/pipe_operators/shared/template_image_analyzer.py::TemplateImageAnalyzer.validate_unused_inputs"]
+param = "template_sources"
+rationale = "Verb-object: validates the template sources; context stays keyword."
+
+["pipelex/pipe_operators/structure/pipe_structure.py::PipeStructure._format_error_location"]
+param = "pipe_run_params"
+rationale = "Derivation from the run params; single operand."
+
+["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._generate_absence_files"]
+param = "absence_record"
+rationale = "Verb-object: renders the absence record into files; files is an out-param."
+
+["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._generate_graph_files"]
+param = "graph_spec"
+rationale = "Verb-object: renders files from the graph spec; options stay keyword."
+
+["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._generate_main_stuff_files"]
+param = "main_stuff"
+rationale = "Verb-object: renders files from the main stuff; options stay keyword."
+
+["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._generate_main_stuff_files_from_raw"]
+param = "raw_main_stuff"
+rationale = "Verb-object: renders files from the raw main stuff; options stay keyword."
+
+["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._store_results"]
+param = "pipe_output"
+rationale = "Verb-object: stores the pipe output; options stay keyword."
+
+["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor.execute"]
+param = "pipe_output"
+rationale = "Verb-object: executes delivery for the pipe output; options stay keyword."
+
+["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor.generate_result_files"]
+param = "pipe_output"
+rationale = "Verb-object: renders result files from the pipe output; options stay keyword."
+
+["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor.try_local_hydrate_stuff"]
+param = "stuff_raw"
+rationale = "Verb-object: hydrates the raw stuff; single operand."
+
+["pipelex/pipe_run/dry_run_in_process.py::dry_run_pipe_in_process"]
+param = "pipe"
+rationale = "Verb-object: dry-runs the pipe; options stay keyword."
+
+["pipelex/pipe_run/pipe_job_factory.py::PipeJobFactory.make_pipe_job"]
+param = "pipe"
+rationale = "Factory from source: builds the job for the pipe; job fields stay keyword."
+
+["pipelex/pipe_run/pipe_router_protocol.py::PipeRouterProtocol._after_failing_run"]
+param = "pipe_job"
+rationale = "Protocol hook: the pipe job being handled; single operand."
+
+["pipelex/pipe_run/pipe_router_protocol.py::PipeRouterProtocol._after_successful_run"]
+param = "pipe_job"
+rationale = "Protocol hook: the pipe job being handled; single operand."
+
+["pipelex/pipe_run/pipe_router_protocol.py::PipeRouterProtocol._before_run"]
+param = "pipe_job"
+rationale = "Protocol hook: the pipe job being handled; single operand."
+
+["pipelex/pipe_run/pipe_router_protocol.py::PipeRouterProtocol._run_pipe_job"]
+param = "pipe_job"
+rationale = "Protocol hook: runs the pipe job; single operand."
+
+["pipelex/pipe_run/pipe_router_protocol.py::PipeRouterProtocol.run"]
+param = "pipe_job"
+rationale = "Protocol method: runs the pipe job; single operand across implementations."
+
+["pipelex/pipe_run/pipe_run_params.py::PipeRunParams.copy_by_injecting_multiplicity"]
+param = "pipe_run_params"
+rationale = "Verb-object: copies the given run params; multiplicity stays keyword."
+
+["pipelex/pipe_run/pipe_run_params.py::PipeRunParams.pop_pipe_from_stack"]
+param = "pipe_code"
+rationale = "Verb-object: pops the pipe named by the code; single operand."
+
+["pipelex/pipe_run/pipe_run_params.py::PipeRunParams.push_pipe_layer"]
+param = "pipe_code"
+rationale = "Verb-object: pushes the pipe named by the code; single operand."
+
+["pipelex/pipe_run/pipe_run_params.py::PipeRunParams.push_pipe_to_stack"]
+param = "pipe_code"
+rationale = "Verb-object: pushes the pipe named by the code; single operand."
+
+["pipelex/pipe_run/pipe_run_protocol.py::PipeRunProtocol.run"]
+param = "pipe_job"
+rationale = "Protocol method: runs the pipe job; single operand across implementations."
+
+["pipelex/pipe_run/tracing_assembly.py::assemble_tracing"]
+param = "pipeline_run_id"
+rationale = "Verb-object: assembles the trace of the run named by the id; options stay keyword."
+
+["pipelex/pipe_run/tracing_assembly.py::assemble_tracing_on_output"]
+param = "pipe_output"
+rationale = "Verb-object: assembles tracing onto the pipe output; options stay keyword."
+
+["pipelex/pipe_signature/signature_walk.py::collect_signature_paths"]
+param = "pipe"
+rationale = "Verb-object: walks from the root pipe; accumulators stay keyword."
+
+["pipelex/pipe_signature/signature_walk.py::collect_signature_refs"]
+param = "pipe"
+rationale = "Verb-object: walks from the root pipe; visited set stays keyword."
+
+["pipelex/pipeline/blueprint_selection.py::select_primary_blueprint"]
+param = "blueprints"
+rationale = "Verb-object: selects among the blueprints; single operand."
+
+["pipelex/pipeline/bundle_validator.py::BundleValidator.validate_pipes"]
+param = "pipes"
+rationale = "Verb-object: validates the pipes; single operand."
+
+["pipelex/pipeline/controller_taint.py::collect_controller_taint_analyses"]
+param = "pipes"
+rationale = "Single-operand analysis over the pipes collection."
+
+["pipelex/pipeline/dry_run_pipeline.py::dry_run_pipeline"]
+param = "mthds_contents"
+rationale = "Verb-object: dry-runs the given .mthds contents; options stay keyword."
+
+["pipelex/pipeline/execution_seams.py::acquire_library"]
+param = "library_id"
+rationale = "Verb-object: acquires the library named by the id; single operand."
+
+["pipelex/pipeline/execution_seams.py::load_libraries_and_activate"]
+param = "library_dirs"
+rationale = "Verb-object: loads the given library dirs; options stay keyword."
+
+["pipelex/pipeline/execution_seams.py::prepare_pipe_job"]
+param = "pipe"
+rationale = "Verb-object: prepares the job for the pipe; job fields stay keyword."
+
+["pipelex/pipeline/fixes/applicability.py::is_safe_fix_for_load_scope"]
+param = "fix"
+rationale = "Predicate on the fix; is_single_file is context."
+
+["pipelex/pipeline/fixes/applicability.py::is_target_in_write_scope"]
+param = "target_path"
+rationale = "Predicate on the target path; scope params stay keyword."
+
+["pipelex/pipeline/fixes/applier.py::_as_tomlkit_value"]
+param = "value"
+rationale = "Single-operand conversion of the value."
+
+["pipelex/pipeline/fixes/applier.py::_render_syntax_diagnostic"]
+param = "diagnostic"
+rationale = "Verb-object: renders the diagnostic; single operand."
+
+["pipelex/pipeline/fixes/applier.py::serialize_and_format"]
+param = "toml_doc"
+rationale = "Single-operand serialization of the TOML document."
+
+["pipelex/pipeline/fixes/fix_loop.py::_absolute_source_path"]
+param = "path"
+rationale = "Single-operand conversion of the path."
+
+["pipelex/pipeline/fixes/fix_loop.py::_assert_snapshot_unchanged"]
+param = "snapshot"
+rationale = "Validator: the snapshot is the single operand checked."
+
+["pipelex/pipeline/fixes/fix_loop.py::_bind_fixes_to_snapshots"]
+param = "fixes"
+rationale = "Verb-object: binds the fixes; the rest is context."
+
+["pipelex/pipeline/fixes/fix_loop.py::_cleanup_staged_updates"]
+param = "staged_updates"
+rationale = "Verb-object: cleans up the staged updates; single operand."
+
+["pipelex/pipeline/fixes/fix_loop.py::_colliding_op_name"]
+param = "fix_op"
+rationale = "Noun-named derivation from the fix op; scopes stay keyword."
+
+["pipelex/pipeline/fixes/fix_loop.py::_commit_file_updates"]
+param = "updates"
+rationale = "Verb-object: commits the updates; single operand."
+
+["pipelex/pipeline/fixes/fix_loop.py::_commit_staged_updates"]
+param = "staged_updates"
+rationale = "Verb-object: commits the staged updates; single operand."
+
+["pipelex/pipeline/fixes/fix_loop.py::_fix_fingerprint"]
+param = "fix"
+rationale = "Noun-named derivation: the fingerprint of the fix; single operand."
+
+["pipelex/pipeline/fixes/fix_loop.py::_is_signature_pipe_section"]
+param = "pipe_section"
+rationale = "Predicate on the pipe section; single operand."
+
+["pipelex/pipeline/fixes/fix_loop.py::_partition_by_write_scope"]
+param = "fixes"
+rationale = "Verb-object: partitions the fixes; scope params stay keyword."
+
+["pipelex/pipeline/fixes/fix_loop.py::_pending_signatures_from_validation_result"]
+param = "validation_result"
+rationale = "Noun-named derivation from the validation result; single operand."
+
+["pipelex/pipeline/fixes/fix_loop.py::_read_file_snapshot"]
+param = "path"
+rationale = "Factory from source: reads the snapshot of the file at path."
+
+["pipelex/pipeline/fixes/fix_loop.py::_rollback_committed_updates"]
+param = "committed_updates"
+rationale = "Verb-object: rolls back the committed updates; single operand."
+
+["pipelex/pipeline/fixes/fix_loop.py::_safe_fixes"]
+param = "items"
+rationale = "Noun-named derivation: filters the error items down to safe fixes; the rest is context."
+
+["pipelex/pipeline/fixes/fix_loop.py::_split_cross_file_collisions"]
+param = "fixes"
+rationale = "Verb-object: splits the fixes; codes_by_file is context."
+
+["pipelex/pipeline/fixes/fix_loop.py::_stage_file_update"]
+param = "update"
+rationale = "Verb-object: stages the update; single operand."
+
+["pipelex/pipeline/fixes/fix_loop.py::_validation_error_items"]
+param = "exc"
+rationale = "Noun-named derivation from the single error operand."
+
+["pipelex/pipeline/fixes/fix_loop.py::fix_bundle_file"]
+param = "mthds_file_path"
+rationale = "Verb-object: fixes the bundle file at path; options stay keyword."
+
+["pipelex/pipeline/fixes/fix_render.py::_format_fix_file"]
+param = "fix_payload"
+rationale = "Verb-object: formats the fix payload; bundle_path is context."
+
+["pipelex/pipeline/fixes/fix_render.py::format_fix_markdown"]
+param = "result"
+rationale = "Positional-Callable protocol shape: markdown renderer over the result dict."
+
+["pipelex/pipeline/fixes/fix_render.py::format_fix_still_invalid_markdown"]
+param = "result"
+rationale = "Verb-object: formats the fix result; bundle_path is context."
+
+["pipelex/pipeline/fixes/planner.py::_plan_match_sequence_output"]
+param = "error_data"
+rationale = "Verb-object: plans the fix for the error data; single operand."
+
+["pipelex/pipeline/fixes/planner.py::_plan_strip_namespace"]
+param = "error_data"
+rationale = "Verb-object: plans the fix for the error data; single operand."
+
+["pipelex/pipeline/fixes/planner.py::_plan_strip_native_concept_redecl"]
+param = "error_data"
+rationale = "Verb-object: plans the fix for the error data; single operand."
+
+["pipelex/pipeline/fixes/planner.py::_plan_sync_controller_inputs"]
+param = "error_data"
+rationale = "Verb-object: plans the fix for the error data; single operand."
+
+["pipelex/pipeline/fixes/planner.py::plan_fix_for_blueprint_validation_error"]
+param = "error_data"
+rationale = "Verb-object: plans the fix for the error data; single operand."
+
+["pipelex/pipeline/fixes/planner.py::plan_fix_for_pipe_validation_error"]
+param = "error_data"
+rationale = "Verb-object: plans the fix for the error data; single operand."
+
+["pipelex/pipeline/input_normalizer.py::_normalize_list"]
+param = "items"
+rationale = "Verb-object: normalizes the items; context stays keyword."
+
+["pipelex/pipeline/input_normalizer.py::_normalize_list_content"]
+param = "list_content"
+rationale = "Verb-object: normalizes the list content; context stays keyword."
+
+["pipelex/pipeline/input_normalizer.py::_normalize_structured_content"]
+param = "structured_content"
+rationale = "Verb-object: normalizes the structured content; context stays keyword."
+
+["pipelex/pipeline/input_normalizer.py::_normalize_url_content"]
+param = "content"
+rationale = "Verb-object: normalizes the content; context stays keyword."
+
+["pipelex/pipeline/input_normalizer.py::_normalize_value"]
+param = "value"
+rationale = "Verb-object: normalizes the value; context stays keyword."
+
+["pipelex/pipeline/input_normalizer.py::normalize_data_urls_to_storage"]
+param = "working_memory"
+rationale = "Verb-object: rewrites data URLs within the working memory; single operand."
+
+["pipelex/pipeline/liftable_pipes.py::build_liftable_pipes"]
+param = "taint_analyses"
+rationale = "Single-operand derivation over the taint analyses."
+
+["pipelex/pipeline/optionality_warnings.py::build_optionality_warnings"]
+param = "taint_analyses"
+rationale = "Single-operand derivation over the taint analyses."
+
+["pipelex/pipeline/pipe_io_contracts.py::build_pipe_io_contracts"]
+param = "pipes"
+rationale = "Verb-object: builds contracts from the pipes; single operand."
+
+["pipelex/pipeline/pipeline_manager_abstract.py::PipelineManagerAbstract.get_optional_pipeline"]
+param = "pipeline_run_id"
+rationale = "Manager getter keyed by the run id; single operand."
+
+["pipelex/pipeline/pipeline_manager_abstract.py::PipelineManagerAbstract.get_pipeline"]
+param = "pipeline_run_id"
+rationale = "Manager getter keyed by the run id; single operand."
+
+["pipelex/pipeline/pipeline_manager_abstract.py::PipelineManagerAbstract.remove_pipeline"]
+param = "pipeline_run_id"
+rationale = "Verb-object: forgets the run named by the id; single operand."
+
+["pipelex/pipeline/pipeline_response.py::PipelexRunResultExecute.from_pipe_output"]
+param = "pipe_output"
+rationale = "Factory from source: builds the result from the pipe output; single operand."
+
+["pipelex/pipeline/runner.py::_extract_validate_graph_pipe_code"]
+param = "extra"
+rationale = "Derivation: extracts from the extra mapping; single operand."
+
+["pipelex/pipeline/validate_bundle.py::_backfill_pipe_error_source"]
+param = "pipe_error"
+rationale = "Verb-object: backfills the pipe error in place; single operand."
+
+["pipelex/pipeline/validate_bundle.py::_pipes_to_dry_run"]
+param = "loaded_pipes"
+rationale = "Verb-object: selects among the loaded pipes; the requested codes stay keyword."
+
+["pipelex/pipeline/validate_bundle.py::build_pending_signatures"]
+param = "pipes_by_ref"
+rationale = "Verb-object: builds signatures from the pipes-by-ref mapping; single operand."
+
+["pipelex/pipeline/validate_bundle.py::build_validated_pipes"]
+param = "dry_run_result"
+rationale = "Verb-object: builds the pipe list from the dry-run result; single operand."
+
+["pipelex/pipeline/validate_bundle.py::validate_bundle"]
+param = "mthds_file_path"
+rationale = "Verb-object: validates the bundle file at the path; options stay keyword."
+
+["pipelex/pipeline/validate_bundle.py::validate_bundles_from_directory"]
+param = "directory"
+rationale = "Verb-object: validates bundles from the directory; options stay keyword."
+
+["pipelex/pipeline/validation_render.py::_markdown_category_header"]
+param = "category"
+rationale = "Noun-named derivation: the header text for the category; single operand."
+
+["pipelex/pipeline/validation_render.py::_render_error_item_markdown"]
+param = "item"
+rationale = "Verb-object: renders the error item; index is context."
+
+["pipelex/pipeline/validation_render.py::count_applicable_fixes"]
+param = "items"
+rationale = "Single-operand count over the error items; scope stays keyword."
+
+["pipelex/pipeline/validation_render.py::format_validate_markdown"]
+param = "result"
+rationale = "Verb-object: formats the validate result; single operand."
+
+["pipelex/pipeline/validation_render.py::format_validation_error_items_markdown"]
+param = "items"
+rationale = "Verb-object: formats the error items; single operand."
+
+["pipelex/pipeline/validation_render.py::render_invalid_validation_markdown"]
+param = "report"
+rationale = "Verb-object: renders the validation report; single operand."
+
+["pipelex/plugins/anthropic/anthropic_config.py::AnthropicConfig.get_reasoning_level"]
+param = "effort"
+rationale = "Maps the reasoning effort to a provider reasoning level; single operand."
+
+["pipelex/plugins/anthropic/anthropic_factory.py::AnthropicFactory._make_document_block_param"]
+param = "prepped_document"
+rationale = "Factory from source: builds the result from the prepped_document; single operand."
+
+["pipelex/plugins/anthropic/anthropic_factory.py::AnthropicFactory._make_image_block_param"]
+param = "prepped_image"
+rationale = "Factory from source: builds the result from the prepped_image; single operand."
+
+["pipelex/plugins/anthropic/anthropic_factory.py::AnthropicFactory.make_anthropic_client"]
+param = "model_handle"
+rationale = "Factory from source: builds the result from the model_handle; single operand."
+
+["pipelex/plugins/anthropic/anthropic_factory.py::AnthropicFactory.make_nb_tokens_by_category"]
+param = "usage"
+rationale = "Factory from source: builds the result from the usage; single operand."
+
+["pipelex/plugins/anthropic/anthropic_factory.py::AnthropicFactory.make_simple_messages"]
+param = "llm_job"
+rationale = "Factory from source: builds the result from the llm_job; single operand."
+
+["pipelex/plugins/anthropic/anthropic_factory.py::AnthropicFactory.make_user_message"]
+param = "llm_job"
+rationale = "Factory from source: builds the result from the llm_job; single operand."
+
+["pipelex/plugins/anthropic/anthropic_factory.py::AnthropicFactory.openai_typed_user_message"]
+param = "user_content_txt"
+rationale = "Factory from source: builds the result from the user_content_txt; single operand."
+
+["pipelex/plugins/anthropic/anthropic_list.py::_display_anthropic_models_flat"]
+param = "models"
+rationale = "Verb–object: renders the model list; single operand."
+
+["pipelex/plugins/anthropic/anthropic_list.py::_display_anthropic_models_table"]
+param = "models"
+rationale = "Verb–object: renders the model list; single operand."
+
+["pipelex/plugins/anthropic/anthropic_llm_worker.py::AnthropicLLMWorker._build_thinking_params"]
+param = "job_params"
+rationale = "Builds provider thinking params from the job_params; single operand."
+
+["pipelex/plugins/anthropic/anthropic_llm_worker.py::AnthropicLLMWorker._build_thinking_params_for_budget"]
+param = "thinking_mode"
+rationale = "Builds provider thinking params from the thinking_mode; single operand."
+
+["pipelex/plugins/anthropic/anthropic_llm_worker.py::AnthropicLLMWorker._build_thinking_params_for_effort"]
+param = "thinking_mode"
+rationale = "Builds provider thinking params from the thinking_mode; single operand."
+
+["pipelex/plugins/anthropic/anthropic_llms.py::anthropic_list_available_models"]
+param = "model_handle"
+rationale = "Lists the available models for the model handle; single operand."
+
+["pipelex/plugins/anthropic/anthropic_plugin.py::AnthropicPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/azure_rest/azure_img_gen_worker.py::AzureImgGenWorker._raise_categorized_azure_status_error"]
+param = "exc"
+rationale = "Categorizes and re-raises the Azure HTTP status error; single operand."
+
+["pipelex/plugins/azure_rest/azure_rest_plugin.py::AzureRestPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/backend_extras_factory.py::BackendExtrasFactory.make_extras"]
+param = "inference_model"
+rationale = "Factory from source: builds the result from the inference_model; single operand."
+
+["pipelex/plugins/bedrock/bedrock_client_protocol.py::BedrockClientProtocol.chat"]
+param = "messages"
+rationale = "Protocol chat: the messages list is the payload operand; provider params keyword-only."
+
+["pipelex/plugins/bedrock/bedrock_factory.py::BedrockFactory.make_bedrock_client"]
+param = "model_handle"
+rationale = "Factory from source: builds the result from the model_handle; single operand."
+
+["pipelex/plugins/bedrock/bedrock_factory.py::BedrockFactory.make_simple_message"]
+param = "llm_job"
+rationale = "Factory from source: builds the result from the llm_job; single operand."
+
+["pipelex/plugins/bedrock/bedrock_list.py::_display_bedrock_models_flat"]
+param = "models"
+rationale = "Verb–object: renders the model list; single operand."
+
+["pipelex/plugins/bedrock/bedrock_list.py::_display_bedrock_models_table"]
+param = "models"
+rationale = "Verb–object: renders the model list; single operand."
+
+["pipelex/plugins/bedrock/bedrock_llm_worker.py::BedrockLLMWorker._validate_no_reasoning_params"]
+param = "job_params"
+rationale = "Validates the job params carry no unsupported reasoning settings; single operand."
+
+["pipelex/plugins/bedrock/bedrock_llms.py::bedrock_list_available_models"]
+param = "model_handle"
+rationale = "Lists the available models for the model handle; single operand."
+
+["pipelex/plugins/bedrock/bedrock_plugin.py::BedrockPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/blackboxai/blackboxai_plugin.py::BlackboxaiPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/contract.py::PipelexPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/direct/direct_plugin.py::DirectOrchestratorPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/discovery.py::_load_external_plugin"]
+param = "entry_point"
+rationale = "Loads the plugin from the entry point; single operand."
+
+["pipelex/plugins/docling/docling_extract_worker.py::DoclingExtractWorker._extract_from_source"]
+param = "source_uri"
+rationale = "Extracts from the source_uri; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/docling/docling_factory.py::DoclingFactory.make_extract_output_from_docling_document"]
+param = "doc"
+rationale = "Factory from source: builds the result from the doc; single operand."
+
+["pipelex/plugins/docling/docling_plugin.py::DoclingPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/fal/fal_factory.py::FalFactory.make_generated_image"]
+param = "fal_result"
+rationale = "Factory from source: builds the result from the fal_result; single operand."
+
+["pipelex/plugins/fal/fal_factory.py::FalFactory.make_generated_image_list"]
+param = "fal_result"
+rationale = "Factory from source: builds the result from the fal_result; single operand."
+
+["pipelex/plugins/fal/fal_img_gen_worker.py::FalImgGenWorker._submit_and_get_result"]
+param = "img_gen_job"
+rationale = "Submits the img-gen job and returns its result; single operand."
+
+["pipelex/plugins/fal/fal_plugin.py::FalPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/fal/fal_poller.py::FalPoller._is_transient_http"]
+param = "exc"
+rationale = "Predicate on the exc; single operand."
+
+["pipelex/plugins/fal/fal_poller.py::FalPoller.poll_queue_until_complete"]
+param = "response_dict"
+rationale = "Parses/consumes the response_dict; single operand."
+
+["pipelex/plugins/gateway/gateway_completions_factory.py::GatewayCompletionsFactory._extract_content_string_from_response"]
+param = "response"
+rationale = "Extracts from the response; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/gateway/gateway_completions_factory.py::GatewayCompletionsFactory._extract_pages_from_choices_content"]
+param = "response"
+rationale = "Extracts from the response; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/gateway/gateway_completions_factory.py::GatewayCompletionsFactory._make_extract_output_from_response_azure"]
+param = "response"
+rationale = "Factory from source: builds the result from the response; single operand."
+
+["pipelex/plugins/gateway/gateway_completions_factory.py::GatewayCompletionsFactory._make_extract_output_from_response_deepseek"]
+param = "response"
+rationale = "Factory from source: builds the result from the response; single operand."
+
+["pipelex/plugins/gateway/gateway_completions_factory.py::GatewayCompletionsFactory._make_extract_output_from_response_linkup_fetch"]
+param = "response"
+rationale = "Factory from source: builds the result from the response; single operand."
+
+["pipelex/plugins/gateway/gateway_completions_factory.py::GatewayCompletionsFactory._make_extract_output_from_response_mistral"]
+param = "response"
+rationale = "Factory from source: builds the result from the response; single operand."
+
+["pipelex/plugins/gateway/gateway_completions_factory.py::GatewayCompletionsFactory.make_portkey_openai_client_for_completions"]
+param = "model_handle"
+rationale = "Factory from source: builds the result from the model_handle; single operand."
+
+["pipelex/plugins/gateway/gateway_constants.py::GatewayOpenAISdkVariant.is_completions"]
+param = "sdk"
+rationale = "Predicate on the sdk; single operand."
+
+["pipelex/plugins/gateway/gateway_constants.py::GatewayOpenAISdkVariant.is_responses"]
+param = "sdk"
+rationale = "Predicate on the sdk; single operand."
+
+["pipelex/plugins/gateway/gateway_deck.py::GatewayDeck.get_config_id"]
+param = "headers"
+rationale = "Derives the gateway config id from the request headers; single operand."
+
+["pipelex/plugins/gateway/gateway_extract_worker.py::GatewayExtractWorker._extract_base64_url"]
+param = "extract_job"
+rationale = "Extracts from the extract_job; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/gateway/gateway_extract_worker.py::GatewayExtractWorker._extract_document"]
+param = "extract_job"
+rationale = "Extracts from the extract_job; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/gateway/gateway_extract_worker.py::GatewayExtractWorker._extract_web_fetch"]
+param = "extract_job"
+rationale = "Extracts from the extract_job; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/gateway/gateway_factory.py::GatewayFactory._make_gemini_image_config"]
+param = "inference_model"
+rationale = "Factory from source: builds the result from the inference_model; single operand."
+
+["pipelex/plugins/gateway/gateway_factory.py::GatewayFactory.get_api_key"]
+param = "backend"
+rationale = "Derives the value from the backend config; single operand."
+
+["pipelex/plugins/gateway/gateway_factory.py::GatewayFactory.get_endpoint"]
+param = "backend"
+rationale = "Derives the value from the backend config; single operand."
+
+["pipelex/plugins/gateway/gateway_factory.py::GatewayFactory.is_debug_enabled"]
+param = "backend"
+rationale = "Predicate: reports whether debug logging is enabled for the backend; single operand."
+
+["pipelex/plugins/gateway/gateway_factory.py::GatewayFactory.make_extras"]
+param = "inference_model"
+rationale = "Factory from source: builds the result from the inference_model; single operand."
+
+["pipelex/plugins/gateway/gateway_factory.py::GatewayFactory.make_portkey_client"]
+param = "backend"
+rationale = "Factory from source: builds the result from the backend; single operand."
+
+["pipelex/plugins/gateway/gateway_plugin.py::GatewayPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/gateway/gateway_protocols.py::GatewayExtractProtocol.make_from_model_handle"]
+param = "model_handle"
+rationale = "Factory from source: builds the result from the model_handle; single operand."
+
+["pipelex/plugins/gateway/gateway_responses_factory.py::GatewayResponsesFactory.make_portkey_openai_client_for_responses"]
+param = "model_handle"
+rationale = "Factory from source: builds the result from the model_handle; single operand."
+
+["pipelex/plugins/gateway/gateway_search_worker.py::GatewaySearchWorker._extract_content"]
+param = "response"
+rationale = "Extracts from the response; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/gateway/gateway_search_worker.py::GatewaySearchWorker._extract_usage"]
+param = "response"
+rationale = "Extracts from the response; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/google/google_config.py::GoogleConfig.get_reasoning_level"]
+param = "effort"
+rationale = "Maps the reasoning effort to a provider reasoning level; single operand."
+
+["pipelex/plugins/google/google_factory.py::GoogleFactory.extract_text_from_response"]
+param = "response"
+rationale = "Extracts from the response; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/google/google_factory.py::GoogleFactory.extract_token_usage"]
+param = "usage_metadata"
+rationale = "Extracts from the usage_metadata; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/google/google_factory.py::GoogleFactory.make_google_client"]
+param = "backend"
+rationale = "Factory from source: builds the result from the backend; single operand."
+
+["pipelex/plugins/google/google_factory.py::GoogleFactory.prepare_document_part"]
+param = "prompt_document"
+rationale = "Transforms the prompt_document into provider parts; single operand."
+
+["pipelex/plugins/google/google_factory.py::GoogleFactory.prepare_image_part"]
+param = "prompt_image"
+rationale = "Transforms the prompt_image into provider parts; single operand."
+
+["pipelex/plugins/google/google_factory.py::GoogleFactory.prepare_user_contents"]
+param = "llm_prompt"
+rationale = "Transforms the llm_prompt into provider parts; single operand."
+
+["pipelex/plugins/google/google_img_gen_factory.py::GoogleImgGenFactory.aspect_ratio_literal"]
+param = "aspect_ratio"
+rationale = "Converts the aspect ratio to its provider literal; single operand."
+
+["pipelex/plugins/google/google_img_gen_factory.py::GoogleImgGenFactory.derive_ratio_and_size_from_exact_size"]
+param = "taxonomy"
+rationale = "Operates on the aspect-ratio taxonomy; the lookup keys stay keyword-only."
+
+["pipelex/plugins/google/google_img_gen_factory.py::GoogleImgGenFactory.dimensions_for_aspect_ratio_and_size"]
+param = "taxonomy"
+rationale = "Operates on the aspect-ratio taxonomy; the lookup keys stay keyword-only."
+
+["pipelex/plugins/google/google_img_gen_factory.py::GoogleImgGenFactory.grids_for_taxonomy"]
+param = "taxonomy"
+rationale = "Operates on the aspect-ratio taxonomy; the lookup keys stay keyword-only."
+
+["pipelex/plugins/google/google_img_gen_factory.py::GoogleImgGenFactory.image_size_for_tier"]
+param = "tier"
+rationale = "Derives the image size for the size tier; single operand."
+
+["pipelex/plugins/google/google_img_gen_factory.py::GoogleImgGenFactory.img_gen_taxonomy"]
+param = "inference_model"
+rationale = "Operates on the aspect-ratio taxonomy; the lookup keys stay keyword-only."
+
+["pipelex/plugins/google/google_img_gen_factory.py::GoogleImgGenFactory.optional_img_gen_taxonomy"]
+param = "inference_model"
+rationale = "Operates on the aspect-ratio taxonomy; the lookup keys stay keyword-only."
+
+["pipelex/plugins/google/google_img_gen_factory.py::GoogleImgGenFactory.resolve_image_config"]
+param = "taxonomy"
+rationale = "Operates on the aspect-ratio taxonomy; the lookup keys stay keyword-only."
+
+["pipelex/plugins/google/google_list.py::_display_google_models_flat"]
+param = "models"
+rationale = "Verb–object: renders the model list; single operand."
+
+["pipelex/plugins/google/google_list.py::_display_google_models_table"]
+param = "models"
+rationale = "Verb–object: renders the model list; single operand."
+
+["pipelex/plugins/google/google_llm_worker.py::GoogleLLMWorker._build_thinking_config"]
+param = "job_params"
+rationale = "Builds provider thinking params from the job_params; single operand."
+
+["pipelex/plugins/google/google_llm_worker.py::GoogleLLMWorker._build_thinking_config_for_budget"]
+param = "thinking_mode"
+rationale = "Builds provider thinking params from the thinking_mode; single operand."
+
+["pipelex/plugins/google/google_llm_worker.py::GoogleLLMWorker._build_thinking_config_for_effort"]
+param = "thinking_mode"
+rationale = "Builds provider thinking params from the thinking_mode; single operand."
+
+["pipelex/plugins/google/google_plugin.py::GooglePlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/huggingface/huggingface_factory.py::HuggingFaceFactory.make_huggingface_inference_provider"]
+param = "provider_str"
+rationale = "Factory from source: builds the result from the provider_str; single operand."
+
+["pipelex/plugins/huggingface/huggingface_img_gen_worker.py::HuggingFaceImgGenWorker._generate_single_image"]
+param = "img_gen_job"
+rationale = "Generates one image from the img-gen job; single operand."
+
+["pipelex/plugins/huggingface/huggingface_plugin.py::HuggingFacePlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/linkup/linkup_plugin.py::LinkupPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/linkup/linkup_search_worker.py::LinkupSearchWorker._parse_date"]
+param = "date_str"
+rationale = "Parses/consumes the date_str; single operand."
+
+["pipelex/plugins/mistral/mistral_config.py::MistralConfig.get_reasoning_level"]
+param = "effort"
+rationale = "Maps the reasoning effort to a provider reasoning level; single operand."
+
+["pipelex/plugins/mistral/mistral_extract_worker.py::MistralExtractWorker._extract_page_from_image"]
+param = "image_uri"
+rationale = "Extracts from the image_uri; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/mistral/mistral_extract_worker.py::MistralExtractWorker._extract_pages_from_document"]
+param = "document_uri"
+rationale = "Extracts from the document_uri; single operand (qualifiers keyword-only)."
+
+["pipelex/plugins/mistral/mistral_factory.py::MistralFactory._clean_mistral_image_base64"]
+param = "base64_str"
+rationale = "Normalizes the base64 image string; single operand."
+
+["pipelex/plugins/mistral/mistral_factory.py::MistralFactory.make_extract_output_from_mistral_response"]
+param = "mistral_extract_response"
+rationale = "Factory from source: builds the result from the mistral_extract_response; single operand."
+
+["pipelex/plugins/mistral/mistral_factory.py::MistralFactory.make_extracted_image_from_page_from_mistral_ocr_image_obj"]
+param = "mistral_ocr_image_obj"
+rationale = "Factory from source: builds the result from the mistral_ocr_image_obj; single operand."
+
+["pipelex/plugins/mistral/mistral_factory.py::MistralFactory.make_mistral_client"]
+param = "backend"
+rationale = "Factory from source: builds the result from the backend; single operand."
+
+["pipelex/plugins/mistral/mistral_factory.py::MistralFactory.make_mistral_document_url"]
+param = "prompt_document"
+rationale = "Factory from source: builds the result from the prompt_document; single operand."
+
+["pipelex/plugins/mistral/mistral_factory.py::MistralFactory.make_mistral_image_url"]
+param = "prompt_image"
+rationale = "Factory from source: builds the result from the prompt_image; single operand."
+
+["pipelex/plugins/mistral/mistral_factory.py::MistralFactory.make_mistral_image_url_chunk_from_uri"]
+param = "uri"
+rationale = "Factory from source: builds the result from the uri; single operand."
+
+["pipelex/plugins/mistral/mistral_factory.py::MistralFactory.make_nb_tokens_by_category"]
+param = "usage"
+rationale = "Factory from source: builds the result from the usage; single operand."
+
+["pipelex/plugins/mistral/mistral_factory.py::MistralFactory.make_simple_messages"]
+param = "llm_job"
+rationale = "Factory from source: builds the result from the llm_job; single operand."
+
+["pipelex/plugins/mistral/mistral_factory.py::MistralFactory.make_simple_messages_openai_typed"]
+param = "llm_job"
+rationale = "Factory from source: builds the result from the llm_job; single operand."
+
+["pipelex/plugins/mistral/mistral_list.py::_display_mistral_models_flat"]
+param = "models"
+rationale = "Verb–object: renders the model list; single operand."
+
+["pipelex/plugins/mistral/mistral_list.py::_display_mistral_models_table"]
+param = "models"
+rationale = "Verb–object: renders the model list; single operand."
+
+["pipelex/plugins/mistral/mistral_llm_worker.py::MistralLLMWorker._resolve_prompt_mode"]
+param = "job_params"
+rationale = "Resolves the prompt mode from the job params; single operand."
+
+["pipelex/plugins/mistral/mistral_plugin.py::MistralPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/model_handle.py::ModelHandle.make_for_inference_model"]
+param = "inference_model"
+rationale = "Factory from source: builds the result from the inference_model; single operand."
+
+["pipelex/plugins/openai/openai_client_factory.py::OpenAIClientFactory.make_openai_client"]
+param = "model_handle"
+rationale = "Factory from source: builds the result from the model_handle; single operand."
+
+["pipelex/plugins/openai/openai_completions_factory.py::OpenAICompletionsFactory._get_document_filename"]
+param = "prompt_document"
+rationale = "Derives the upload filename from the prompt document; single operand."
+
+["pipelex/plugins/openai/openai_completions_factory.py::OpenAICompletionsFactory.make_nb_tokens_by_category"]
+param = "usage"
+rationale = "Factory from source: builds the result from the usage; single operand."
+
+["pipelex/plugins/openai/openai_completions_factory.py::OpenAICompletionsFactory.make_simple_messages"]
+param = "llm_job"
+rationale = "Factory from source: builds the result from the llm_job; single operand."
+
+["pipelex/plugins/openai/openai_completions_img_gen_worker.py::OpenAICompletionsImgGenWorker._build_messages_with_images"]
+param = "img_gen_job"
+rationale = "Builds the messages payload from the img-gen job; single operand."
+
+["pipelex/plugins/openai/openai_completions_llm_worker.py::OpenAICompletionsLLMWorker._resolve_reasoning_effort"]
+param = "job_params"
+rationale = "Resolves the reasoning effort from the job params; single operand."
+
+["pipelex/plugins/openai/openai_config.py::OpenAIConfig.get_reasoning_level"]
+param = "effort"
+rationale = "Maps the reasoning effort to a provider reasoning level; single operand."
+
+["pipelex/plugins/openai/openai_func.py::create_openai_schema_from_function"]
+param = "func"
+rationale = "Factory from source: builds the OpenAI tool schema from the function; single operand."
+
+["pipelex/plugins/openai/openai_func.py::create_pydantic_model_from_function"]
+param = "func"
+rationale = "Factory from source: builds the pydantic model from the function; single operand."
+
+["pipelex/plugins/openai/openai_func.py::list_openai_tools"]
+param = "openai_message"
+rationale = "Derives the tool-call list from the OpenAI message; single operand."
+
+["pipelex/plugins/openai/openai_img_gen_factory.py::OpenAIImgGenFactory._size_to_string"]
+param = "size"
+rationale = "Converts the image size to its provider string; single operand."
+
+["pipelex/plugins/openai/openai_img_gen_factory.py::OpenAIImgGenFactory.input_fidelity_for_openai_image"]
+param = "input_fidelity"
+rationale = "Derives the OpenAI fidelity literal from the input fidelity; single operand."
+
+["pipelex/plugins/openai/openai_img_gen_worker.py::OpenAIImgGenWorker._get_requested_size"]
+param = "args_dict"
+rationale = "Extracts the requested size from the args dict; single operand."
+
+["pipelex/plugins/openai/openai_list.py::_display_openai_models_flat"]
+param = "models"
+rationale = "Verb–object: renders the model list; single operand."
+
+["pipelex/plugins/openai/openai_list.py::_display_openai_models_table"]
+param = "models"
+rationale = "Verb–object: renders the model list; single operand."
+
+["pipelex/plugins/openai/openai_llms.py::openai_list_available_models"]
+param = "model_handle"
+rationale = "Lists the available models for the model handle; single operand."
+
+["pipelex/plugins/openai/openai_plugin.py::OpenAIPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/openai/openai_responses_factory.py::OpenAIResponsesFactory._get_document_filename"]
+param = "prompt_document"
+rationale = "Derives the upload filename from the prompt document; single operand."
+
+["pipelex/plugins/openai/openai_responses_factory.py::OpenAIResponsesFactory.make_input_items"]
+param = "llm_job"
+rationale = "Factory from source: builds the result from the llm_job; single operand."
+
+["pipelex/plugins/openai/openai_responses_factory.py::OpenAIResponsesFactory.make_nb_tokens_by_category"]
+param = "usage"
+rationale = "Factory from source: builds the result from the usage; single operand."
+
+["pipelex/plugins/openai/openai_responses_llm_worker.py::OpenAIResponsesLLMWorker._resolve_reasoning"]
+param = "job_params"
+rationale = "Resolves the reasoning config from the job params; single operand."
+
+["pipelex/plugins/openai/vertexai_factory.py::VertexAIFactory._make_api_key"]
+param = "gcp_credentials_file_path"
+rationale = "Factory from source: builds the result from the gcp_credentials_file_path; single operand."
+
+["pipelex/plugins/openai/vertexai_factory.py::VertexAIFactory._make_endpoint"]
+param = "gcp_project_id"
+rationale = "Factory from source: builds the result from the gcp_project_id; single operand."
+
+["pipelex/plugins/openai/vertexai_factory.py::VertexAIFactory.make_endpoint_and_api_key"]
+param = "extra_config"
+rationale = "Factory from source: builds the result from the extra_config; single operand."
+
+["pipelex/plugins/openrouter/openrouter_plugin.py::OpenRouterPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/portkey/portkey_completions_factory.py::PortkeyCompletionsFactory.make_portkey_openai_client_for_completions"]
+param = "model_handle"
+rationale = "Factory from source: builds the result from the model_handle; single operand."
+
+["pipelex/plugins/portkey/portkey_constants.py::PortkeyOpenAISdkVariant.is_completions"]
+param = "sdk"
+rationale = "Predicate on the sdk; single operand."
+
+["pipelex/plugins/portkey/portkey_constants.py::PortkeyOpenAISdkVariant.is_responses"]
+param = "sdk"
+rationale = "Predicate on the sdk; single operand."
+
+["pipelex/plugins/portkey/portkey_factory.py::PortkeyFactory.get_api_key"]
+param = "backend"
+rationale = "Derives the value from the backend config; single operand."
+
+["pipelex/plugins/portkey/portkey_factory.py::PortkeyFactory.get_endpoint"]
+param = "backend"
+rationale = "Derives the value from the backend config; single operand."
+
+["pipelex/plugins/portkey/portkey_factory.py::PortkeyFactory.is_debug_enabled"]
+param = "backend"
+rationale = "Predicate: reports whether debug logging is enabled for the backend; single operand."
+
+["pipelex/plugins/portkey/portkey_factory.py::PortkeyFactory.make_extras"]
+param = "inference_model"
+rationale = "Factory from source: builds the result from the inference_model; single operand."
+
+["pipelex/plugins/portkey/portkey_plugin.py::PortkeyPlugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/portkey/portkey_responses_factory.py::PortkeyResponsesFactory.make_portkey_openai_client_for_responses"]
+param = "model_handle"
+rationale = "Factory from source: builds the result from the model_handle; single operand."
+
+["pipelex/plugins/pypdfium2/pypdfium2_plugin.py::Pypdfium2Plugin.register"]
+param = "registrar"
+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."
+
+["pipelex/plugins/pypdfium2/pypdfium2_worker.py::Pypdfium2Worker._resolve_pdf_uri"]
+param = "pdf_uri"
+rationale = "Resolves the PDF URI to a readable local source; single operand."
+
+["pipelex/plugins/registrar.py::PluginRegistrar.add_teardown"]
+param = "callback"
+rationale = "Registers the callback callable as the sole operand."
+
+["pipelex/plugins/registrar.py::PluginRegistrar.claim_content_generator"]
+param = "factory"
+rationale = "Registers the factory callable as the sole operand."
+
+["pipelex/plugins/registrar.py::PluginRegistrar.claim_isolated_execution_probe"]
+param = "factory"
+rationale = "Registers the factory callable as the sole operand."
+
+["pipelex/plugins/registrar.py::PluginRegistrar.claim_pipe_router"]
+param = "factory"
+rationale = "Registers the factory callable as the sole operand."
+
+["pipelex/plugins/registrar.py::PluginRegistrar.claim_pipe_run"]
+param = "factory"
+rationale = "Registers the factory callable as the sole operand."
+
+["pipelex/plugins/registrar.py::PluginRegistrar.claim_task_manager"]
+param = "factory"
+rationale = "Registers the factory callable as the sole operand."
+
+["pipelex/plugins/sdk_client_registry.py::SdkClientRegistry.get"]
+param = "model_handle"
+rationale = "Registry getter keyed by the model handle."
+
+["pipelex/plugins/secrets/secrets_plugin.py::SecretsPlugin.register"]
+param = "registrar"
+rationale = "Duck-typed plugin protocol: discovery invokes plugin.register(registrar) positionally."
+
+["pipelex/plugins/secrets/secrets_plugin.py::_make_env_secrets_provider"]
+param = "config"
+rationale = "Positional-Callable protocol: registered as a SecretsProviderFactoryFn."
+
+["pipelex/plugins/storage/storage_plugin.py::StoragePlugin.register"]
+param = "registrar"
+rationale = "Duck-typed plugin protocol: discovery invokes plugin.register(registrar) positionally."
+
+["pipelex/plugins/storage/storage_plugin.py::_make_gcp_storage_provider"]
+param = "config"
+rationale = "Positional-Callable protocol: registered as a StorageProviderFactoryFn."
+
+["pipelex/plugins/storage/storage_plugin.py::_make_in_memory_storage_provider"]
+param = "config"
+rationale = "Positional-Callable protocol: registered as a StorageProviderFactoryFn."
+
+["pipelex/plugins/storage/storage_plugin.py::_make_local_storage_provider"]
+param = "config"
+rationale = "Positional-Callable protocol: registered as a StorageProviderFactoryFn."
+
+["pipelex/plugins/storage/storage_plugin.py::_make_s3_storage_provider"]
+param = "config"
+rationale = "Positional-Callable protocol: registered as a StorageProviderFactoryFn."
+
+["pipelex/reporting/cost_report_renderer.py::render_cost_report_for_output"]
+param = "pipe_output"
+rationale = "Verb-object: renders the report for the pipe output; single operand."
+
+["pipelex/reporting/reporting_manager.py::ReportingManager._emit_usage_event"]
+param = "inference_job"
+rationale = "Verb-object: emits usage for the inference job; tokens_usage stays keyword."
+
+["pipelex/reporting/reporting_manager.py::ReportingManager._emit_usage_event_runner_fallback"]
+param = "inference_job"
+rationale = "Verb-object: emits usage for the inference job via fallback; context stays keyword."
+
+["pipelex/reporting/reporting_manager.py::ReportingManager._report_extract_job"]
+param = "extract_job"
+rationale = "Verb-object: reports the extract job; single operand."
+
+["pipelex/reporting/reporting_manager.py::ReportingManager._report_img_gen_job"]
+param = "img_gen_job"
+rationale = "Verb-object: reports the img-gen job; single operand."
+
+["pipelex/reporting/reporting_manager.py::ReportingManager._report_llm_job"]
+param = "llm_job"
+rationale = "Verb-object: reports the LLM job; single operand."
+
+["pipelex/reporting/reporting_manager.py::ReportingManager._report_search_job"]
+param = "search_job"
+rationale = "Verb-object: reports the search job; single operand."
+
+["pipelex/reporting/reporting_protocol.py::ReportingProtocol.report_inference_job"]
+param = "inference_job"
+rationale = "Protocol method: reports the inference job; single operand across implementations."
+
+["pipelex/runtime_bridge/primitives/hydration.py::_hydrate_composite_component"]
+param = "raw_value"
+rationale = "Single-operand hydration of the raw value."
+
+["pipelex/runtime_bridge/primitives/hydration.py::_hydrate_list_item"]
+param = "raw_item"
+rationale = "Verb-object: hydrates the raw item; single operand."
+
+["pipelex/runtime_bridge/primitives/hydration.py::hydrate_content"]
+param = "raw_content"
+rationale = "Verb-object: hydrates the raw content; concept stays keyword."
+
+["pipelex/runtime_bridge/primitives/hydration.py::hydrate_working_memory"]
+param = "working_memory_raw"
+rationale = "Verb-object: hydrates the raw working-memory dict; single operand."
+
+["pipelex/runtime_bridge/serialization.py::resolve_main_stuff_root_key"]
+param = "pipe_output"
+rationale = "Derivation from the pipe output; single operand."
+
+["pipelex/runtime_bridge/serialization.py::serialize_completed_output"]
+param = "pipe_output"
+rationale = "Verb-object: serializes the pipe output; workflow_id stays keyword."
+
+["pipelex/runtime_bridge/serialization.py::serialize_pipe_output"]
+param = "pipe_output"
+rationale = "Verb-object: serializes the pipe output; single operand."
+
+["pipelex/system/configuration/config_loader.py::ConfigLoader._override_files_for_dir"]
+param = "config_dir"
+rationale = "Derivation from the config dir; single operand."
+
+["pipelex/system/configuration/config_loader.py::ConfigLoader._plugin_override_files_for_dir"]
+param = "config_dir"
+rationale = "Derivation from the config dir; single operand."
+
+["pipelex/system/configuration/config_loader.py::ConfigLoader.find_project_root"]
+param = "start_dir"
+rationale = "Verb-object: searches upward from the start dir; single operand."
+
+["pipelex/system/configuration/config_loader.py::ConfigLoader.resolve_config_file"]
+param = "relative_path"
+rationale = "Verb-object: resolves the relative path; single operand."
+
+["pipelex/system/configuration/config_model.py::ConfigModel.transform_dict_keys_str_to_enum"]
+param = "input_dict"
+rationale = "Verb-object: transforms the input dict; enum class stays keyword."
+
+["pipelex/system/configuration/config_model.py::ConfigModel.transform_dict_of_floats_str_to_enum"]
+param = "input_dict"
+rationale = "Verb-object: transforms the input dict; enum class stays keyword."
+
+["pipelex/system/configuration/config_model.py::ConfigModel.transform_dict_str_to_enum"]
+param = "input_dict"
+rationale = "Verb-object: transforms the input dict; enum class stays keyword."
+
+["pipelex/system/configuration/config_model.py::ConfigModel.transform_list_of_str_to_enum"]
+param = "input_list"
+rationale = "Verb-object: transforms the input list; enum class stays keyword."
+
+["pipelex/system/configuration/configs.py::MigrationConfig.text_in_renaming_keys"]
+param = "text"
+rationale = "Predicate on the text; single operand."
+
+["pipelex/system/configuration/configs.py::MigrationConfig.text_in_renaming_values"]
+param = "text"
+rationale = "Predicate on the text; single operand."
+
+["pipelex/system/configuration/configs.py::PromptingConfig.get_prompting_style"]
+param = "prompting_target"
+rationale = "Config getter keyed by the prompting target; single operand."
+
+["pipelex/system/environment.py::all_env_vars_are_set"]
+param = "keys"
+rationale = "Predicate on the given env-var keys; single operand."
+
+["pipelex/system/environment.py::any_env_var_is_placeholder"]
+param = "keys"
+rationale = "Predicate on the given env-var keys; single operand."
+
+["pipelex/system/environment.py::get_optional_env"]
+param = "key"
+rationale = "Env getter keyed by the var name; single operand."
+
+["pipelex/system/environment.py::get_required_env"]
+param = "key"
+rationale = "Env getter keyed by the var name; single operand."
+
+["pipelex/system/environment.py::is_env_var_set"]
+param = "key"
+rationale = "Predicate on the var named by the key; single operand."
+
+["pipelex/system/environment.py::is_env_var_truthy"]
+param = "key"
+rationale = "Predicate on the var named by the key; single operand."
+
+["pipelex/system/pipelex_service/gateway_config_merger.py::GatewayConfigMerger.merge"]
+param = "gateway_model_specs"
+rationale = "Verb-object: merges the gateway model specs; merge context stays keyword."
+
+["pipelex/system/pipelex_service/pipelex_details.py::PipelexDetails.make_distinct_id"]
+param = "gateway_api_key"
+rationale = "Derivation: hashes the gateway API key into a distinct id; single operand."
+
+["pipelex/system/pipelex_service/pipelex_service_config.py::is_pipelex_gateway_enabled"]
+param = "backends_file_path"
+rationale = "Predicate inspecting the backends file at the path; single operand."
+
+["pipelex/system/pipelex_service/pipelex_service_config.py::load_pipelex_service_config_if_exists"]
+param = "config_dir"
+rationale = "Verb-object: loads from the config dir; single operand."
+
+["pipelex/system/pipelex_service/remote_config_cache.py::RemoteConfigCache.store"]
+param = "remote_config_payload"
+rationale = "Verb-object: stores the payload; options stay keyword."
+
+["pipelex/system/pipelex_service/remote_config_fetcher.py::RemoteConfigFetcher._build_unavailable_error"]
+param = "fetch_error"
+rationale = "Builds the error from the fetch exception; single operand."
+
+["pipelex/system/pipelex_service/remote_config_fetcher.py::RemoteConfigFetcher._fetch_fresh"]
+param = "url"
+rationale = "Verb-object: fetches the URL; options stay keyword."
+
+["pipelex/system/pipelex_service/remote_config_fetcher.py::RemoteConfigFetcher._fetch_remote_config_with_retry"]
+param = "url"
+rationale = "Verb-object: fetches the URL; options stay keyword."
+
+["pipelex/system/pipelex_service/remote_config_fetcher.py::RemoteConfigFetcher._fetch_remote_config_with_retry._fetch_with_retry"]
+param = "url"
+rationale = "Nested retry closure fetching the URL; single operand."
+
+["pipelex/system/pipelex_service/remote_config_fetcher.py::RemoteConfigFetcher._log_retry_attempt"]
+param = "retry_state"
+rationale = "Positional Callable protocol: tenacity before_sleep callback, invoked callback(retry_state)."
+
+["pipelex/system/registries/class_registry_utils.py::ClassRegistryUtils.auto_register_all_subclasses"]
+param = "base_class"
+rationale = "Verb-object: registers subclasses of the base class; options stay keyword."
+
+["pipelex/system/registries/class_registry_utils.py::ClassRegistryUtils.import_modules_in_folder"]
+param = "folder_path"
+rationale = "Verb-object: imports modules under the folder path; options stay keyword."
+
+["pipelex/system/registries/class_registry_utils.py::ClassRegistryUtils.register_classes_in_file"]
+param = "file_path"
+rationale = "Verb-object: registers classes in the file; options stay keyword."
+
+["pipelex/system/registries/class_registry_utils.py::ClassRegistryUtils.register_classes_in_folder"]
+param = "folder_path"
+rationale = "Verb-object: registers classes under the folder path; options stay keyword."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.check_function_eligibility"]
+param = "func"
+rationale = "Verb-object: checks the function; single operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.get_function"]
+param = "name"
+rationale = "Registry getter keyed by the function name; single operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.get_ineligible_function_info"]
+param = "name"
+rationale = "Registry getter keyed by the function name; single operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.get_required_function"]
+param = "name"
+rationale = "Registry getter keyed by the function name; single operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.get_required_function_with_signature"]
+param = "name"
+rationale = "Registry getter keyed by the function name; single operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.has_function"]
+param = "name"
+rationale = "Predicate on the function named; single operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.is_eligible_function"]
+param = "func"
+rationale = "Predicate on the function; single operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.is_marked_pipe_func"]
+param = "func"
+rationale = "Predicate on the function; single operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.log"]
+param = "message"
+rationale = "Verb-object: logs the message; single operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.register_function"]
+param = "func"
+rationale = "Verb-object: registers the function; options stay keyword."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.register_functions"]
+param = "functions"
+rationale = "Verb-object: registers the functions; options stay keyword."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.register_functions_dict"]
+param = "functions"
+rationale = "Verb-object: registers the functions mapping; single operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.register_ineligible_function"]
+param = "func"
+rationale = "Verb-object: records the function; reason stays keyword."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.set_logger"]
+param = "logger"
+rationale = "Setter: installs the logger; single self-labelling operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.unregister_function"]
+param = "func"
+rationale = "Verb-object: unregisters the function; single operand."
+
+["pipelex/system/registries/func_registry.py::FuncRegistry.unregister_function_by_name"]
+param = "name"
+rationale = "Verb-object: the name of the function being unregistered; single operand."
+
+["pipelex/system/registries/func_registry.py::pipe_func"]
+param = "name"
+rationale = "Decorator factory: the registration name, idiomatically positional at decoration sites."
+
+["pipelex/system/registries/func_registry.py::pipe_func.decorator"]
+param = "func"
+rationale = "Positional Callable protocol: decorator applied to the function by @ syntax."
+
+["pipelex/system/registries/func_registry_utils.py::FuncRegistryUtils._find_functions_in_module"]
+param = "module"
+rationale = "Verb-object: scans the module; single operand."
+
+["pipelex/system/registries/func_registry_utils.py::FuncRegistryUtils._get_function_registration_name"]
+param = "func"
+rationale = "Derivation from the function; single operand."
+
+["pipelex/system/registries/func_registry_utils.py::FuncRegistryUtils._register_funcs_in_file"]
+param = "file_path"
+rationale = "Verb-object: registers funcs in the file; options stay keyword."
+
+["pipelex/system/registries/func_registry_utils.py::FuncRegistryUtils.register_funcs_in_folder"]
+param = "folder_path"
+rationale = "Verb-object: registers funcs under the folder path; options stay keyword."
+
+["pipelex/system/registries/func_registry_utils.py::FuncRegistryUtils.register_pipe_funcs_from_package"]
+param = "package_name"
+rationale = "Verb-object: registers funcs from the named package; single operand."
+
+["pipelex/system/registries/singleton.py::MetaSingleton.clear_subclass_instances"]
+param = "base_cls"
+rationale = "Verb-object: clears instances of the base class; single operand."
+
+["pipelex/system/registries/singleton.py::MetaSingleton.get_subclass_instance"]
+param = "base_cls"
+rationale = "Registry getter keyed by the base class; single operand."
+
+["pipelex/system/runtime.py::RuntimeManager.set_run_mode"]
+param = "run_mode"
+rationale = "Setter: installs the run mode; single self-labelling operand."
+
+["pipelex/system/runtime.py::RuntimeManager.set_worker_mode"]
+param = "worker_mode"
+rationale = "Setter: installs the worker mode; single self-labelling operand."
+
+["pipelex/system/telemetry/exception_capture.py::DualClientExceptionCapture._capture_exception"]
+param = "exc_info"
+rationale = "Verb-object: captures the exc info; single operand."
+
+["pipelex/system/telemetry/exception_capture.py::DualClientExceptionCapture._thread_exception_handler"]
+param = "args"
+rationale = "Positional Callable protocol: threading.excepthook handler, invoked hook(args)."
+
+["pipelex/system/telemetry/otel_constants.py::make_otel_gen_ai_output_type"]
+param = "output_type"
+rationale = "Conversion: maps the output type; single operand."
+
+["pipelex/system/telemetry/otel_factory.py::OtelFactory._is_unresolved_placeholder"]
+param = "value"
+rationale = "Predicate on the value; single operand."
+
+["pipelex/system/telemetry/otel_factory.py::OtelFactory.make_inputs_json"]
+param = "working_memory"
+rationale = "Conversion: serializes the working memory; options stay keyword."
+
+["pipelex/system/telemetry/otel_factory.py::OtelFactory.make_langfuse_exporter"]
+param = "langfuse_config"
+rationale = "Factory from source: builds the exporter from the config; single operand."
+
+["pipelex/system/telemetry/otel_factory.py::OtelFactory.make_output_json"]
+param = "pipe_output"
+rationale = "Conversion: serializes the pipe output; options stay keyword."
+
+["pipelex/system/telemetry/otel_factory.py::OtelFactory.make_trace_id"]
+param = "pipeline_run_id"
+rationale = "Derivation: encodes the run id into a trace id; single operand."
+
+["pipelex/system/telemetry/otel_factory.py::OtelFactory.make_trace_names"]
+param = "pipeline_run_id"
+rationale = "Derivation from the run id; context stays keyword."
+
+["pipelex/system/telemetry/otel_factory.py::OtelFactory.make_truncated_content"]
+param = "content"
+rationale = "Verb-object: truncates the content; limits stay keyword."
+
+["pipelex/system/telemetry/otel_factory.py::OtelFactory.stringify_json"]
+param = "json_conent"
+rationale = "Conversion: stringifies the JSON content; single operand."
+
+["pipelex/system/telemetry/posthog_span_exporter.py::PostHogSpanExporter._apply_content_redaction"]
+param = "properties"
+rationale = "Verb-object: redacts the properties in place; single operand."
+
+["pipelex/system/telemetry/posthog_span_exporter.py::PostHogSpanExporter._build_redacted_generation_span_name"]
+param = "original_span_name"
+rationale = "Transforms the span name; single operand."
+
+["pipelex/system/telemetry/posthog_span_exporter.py::PostHogSpanExporter._build_redacted_pipe_span_name"]
+param = "original_span_name"
+rationale = "Transforms the span name; single operand."
+
+["pipelex/system/telemetry/posthog_span_exporter.py::PostHogSpanExporter._capture_event"]
+param = "event"
+rationale = "Verb-object: captures the event; single operand."
+
+["pipelex/system/telemetry/posthog_span_exporter.py::PostHogSpanExporter._do_export"]
+param = "spans"
+rationale = "Verb-object: exports the spans; single operand."
+
+["pipelex/system/telemetry/posthog_span_exporter.py::PostHogSpanExporter._export_generation_span"]
+param = "span"
+rationale = "Verb-object: exports the span; single operand."
+
+["pipelex/system/telemetry/posthog_span_exporter.py::PostHogSpanExporter._export_pipe_span"]
+param = "span"
+rationale = "Verb-object: exports the span; single operand."
+
+["pipelex/system/telemetry/posthog_span_exporter.py::PostHogSpanExporter._get_base_properties"]
+param = "span"
+rationale = "Derivation from the span; single operand."
+
+["pipelex/system/telemetry/posthog_span_exporter.py::PostHogSpanExporter._get_redacted_output_class_name"]
+param = "output_class_name"
+rationale = "Transforms the class name; single operand."
+
+["pipelex/system/telemetry/posthog_span_exporter.py::PostHogSpanExporter._get_redacted_pipe_code"]
+param = "pipe_code"
+rationale = "Transforms the pipe code; single operand."
+
+["pipelex/system/telemetry/posthog_span_exporter.py::PostHogSpanExporter._truncate_content"]
+param = "content"
+rationale = "Verb-object: truncates the content; limits stay keyword."
+
+["pipelex/system/telemetry/telemetry_config.py::TelemetryConfig.is_custom_telemetry_allowed_for_mode"]
+param = "mode"
+rationale = "Predicate on the integration mode; single operand."
+
+["pipelex/system/telemetry/telemetry_config.py::TelemetryRedactionConfig.make_from_posthog_config"]
+param = "posthog_config"
+rationale = "Factory from source: builds from the posthog config; single operand."
+
+["pipelex/system/telemetry/telemetry_manager.py::TelemetryManager._track_anonymous_event"]
+param = "event_name"
+rationale = "Verb-object: tracks the event named; properties stay keyword."
+
+["pipelex/system/telemetry/telemetry_manager.py::TelemetryManager._track_identified_event"]
+param = "event_name"
+rationale = "Verb-object: tracks the event named; properties stay keyword."
+
+["pipelex/system/telemetry/telemetry_manager.py::TelemetryManager._track_to_pipelex"]
+param = "event_name"
+rationale = "Verb-object: tracks the event named; properties stay keyword."
+
+["pipelex/system/telemetry/telemetry_manager.py::TelemetryManager._wrap_capture_exception"]
+param = "client"
+rationale = "Verb-object: wraps the client's capture; single operand."
+
+["pipelex/system/telemetry/telemetry_manager.py::TelemetryManager._wrap_capture_exception.sanitized_capture_exception"]
+param = "exception"
+rationale = "Positional Callable protocol: replaces client.capture_exception, invoked capture(exception)."
+
+["pipelex/system/telemetry/telemetry_manager_abstract.py::TelemetryManagerAbstract.track_event"]
+param = "event_name"
+rationale = "Verb-object: tracks the event named; properties stay keyword."
+
+["pipelex/test_extras/shared_pytest_plugins.py::_cleanup_placeholder_env_vars"]
+param = "env_var_keys"
+rationale = "Verb-object: the env-var keys being cleaned up; single operand."
+
+["pipelex/test_extras/shared_pytest_plugins.py::_setup_env_var_placeholders"]
+param = "env_var_keys"
+rationale = "Verb-object: the env-var keys being set up; single operand."
+
+["pipelex/test_extras/shared_pytest_plugins.py::is_inference_disabled_in_pipelex"]
+param = "request"
+rationale = "Predicate inspecting the pytest request; single operand."
+
+["pipelex/test_extras/shared_pytest_plugins.py::needs_inference_in_pipelex"]
+param = "request"
+rationale = "Predicate inspecting the pytest request; single operand."
+
+["pipelex/test_extras/shared_pytest_plugins.py::pytest_addoption"]
+param = "parser"
+rationale = "Framework-owned pytest hook signature; pluggy binds by parameter name."
+
+["pipelex/test_extras/shared_pytest_plugins.py::pytest_configure"]
+param = "config"
+rationale = "Framework-owned pytest hook signature; pluggy binds by parameter name."
+
+["pipelex/tools/jinja2/image_registry.py::ImageRegistry.get_image_placeholder"]
+param = "image"
+rationale = "Extracts/derives from the image; single operand."
+
+["pipelex/tools/jinja2/image_registry.py::ImageRegistry.make_finalize.finalize"]
+param = "value"
+rationale = "Positional-Callable jinja2 finalize hook: value is the single operand jinja passes."
+
+["pipelex/tools/jinja2/image_registry.py::ImageRegistry.register_image"]
+param = "image"
+rationale = "Registers the image; single operand."
+
+["pipelex/tools/jinja2/jinja2_environment.py::_register_filters"]
+param = "jinja2_env"
+rationale = "Jinja op on the jinja2_env; single operand (context keyword-only)."
+
+["pipelex/tools/jinja2/jinja2_environment.py::make_jinja2_env_from_registry"]
+param = "template_category"
+rationale = "Factory from source: builds the result from the template_category; single operand."
+
+["pipelex/tools/jinja2/jinja2_environment.py::make_jinja2_env_without_loader"]
+param = "template_category"
+rationale = "Factory from source: builds the result from the template_category; single operand."
+
+["pipelex/tools/jinja2/jinja2_filters.py::escape_script_tag"]
+param = "value"
+rationale = "Transforms the value; single operand."
+
+["pipelex/tools/jinja2/jinja2_optional_guards.py::_GuardWalker._assign_target_names"]
+param = "target"
+rationale = "Noun-named derivation: the assigned names of the target node; single operand."
+
+["pipelex/tools/jinja2/jinja2_optional_guards.py::_GuardWalker._guard_vars"]
+param = "test_node"
+rationale = "Noun-named derivation: the guarded vars of the test node; single operand."
+
+["pipelex/tools/jinja2/jinja2_optional_guards.py::_GuardWalker._is_unguarded_optional"]
+param = "full_path"
+rationale = "Predicate on the path; guard sets stay keyword."
+
+["pipelex/tools/jinja2/jinja2_optional_guards.py::_GuardWalker._record"]
+param = "full_path"
+rationale = "Verb-object: records the path; single operand."
+
+["pipelex/tools/jinja2/jinja2_optional_guards.py::_GuardWalker._walk_body"]
+param = "body_nodes"
+rationale = "Visitor: walks the body nodes; guard sets stay keyword."
+
+["pipelex/tools/jinja2/jinja2_optional_guards.py::_GuardWalker._walk_test"]
+param = "test_node"
+rationale = "Visitor: walks the test node; guard sets stay keyword."
+
+["pipelex/tools/jinja2/jinja2_optional_guards.py::_GuardWalker.walk"]
+param = "node"
+rationale = "Visitor: walks the node; guard sets stay keyword."
+
+["pipelex/tools/jinja2/jinja2_optional_guards.py::_build_full_path"]
+param = "node"
+rationale = "Noun-named derivation: the full dotted path of the node; single operand."
+
+["pipelex/tools/jinja2/jinja2_parsing.py::check_jinja2_parsing"]
+param = "template_source"
+rationale = "Jinja op on the template_source; single operand (context keyword-only)."
+
+["pipelex/tools/jinja2/jinja2_rendering.py::_add_to_templating_context"]
+param = "templating_context"
+rationale = "Transforms the templating_context; single operand."
+
+["pipelex/tools/jinja2/jinja2_rendering.py::_compile_jinja2_template"]
+param = "template_source"
+rationale = "Jinja op on the template_source; single operand (context keyword-only)."
+
+["pipelex/tools/jinja2/jinja2_rendering.py::_make_non_type_error_msg"]
+param = "template_source"
+rationale = "Factory from source: builds the result from the template_source; single operand."
+
+["pipelex/tools/jinja2/jinja2_rendering.py::_make_type_error_msg"]
+param = "template_source"
+rationale = "Factory from source: builds the result from the template_source; single operand."
+
+["pipelex/tools/jinja2/jinja2_rendering.py::_prepare_templating_context"]
+param = "templating_context"
+rationale = "Jinja op on the templating_context; single operand (context keyword-only)."
+
+["pipelex/tools/jinja2/jinja2_rendering.py::_render_template_async"]
+param = "template_source"
+rationale = "Jinja op on the template_source; single operand (context keyword-only)."
+
+["pipelex/tools/jinja2/jinja2_rendering.py::_render_template_sync"]
+param = "template_source"
+rationale = "Jinja op on the template_source; single operand (context keyword-only)."
+
+["pipelex/tools/jinja2/jinja2_rendering.py::render_jinja2_async"]
+param = "template_source"
+rationale = "Jinja op on the template_source; single operand (context keyword-only)."
+
+["pipelex/tools/jinja2/jinja2_rendering.py::render_jinja2_sync"]
+param = "template_source"
+rationale = "Jinja op on the template_source; single operand (context keyword-only)."
+
+["pipelex/tools/jinja2/jinja2_required_variables.py::_build_full_path"]
+param = "node"
+rationale = "Extracts/derives from the node; single operand."
+
+["pipelex/tools/jinja2/jinja2_required_variables.py::_collect_declarations_from_body"]
+param = "body"
+rationale = "Extracts/derives from the body; single operand."
+
+["pipelex/tools/jinja2/jinja2_required_variables.py::_collect_full_variable_paths"]
+param = "node"
+rationale = "Extracts/derives from the node; single operand."
+
+["pipelex/tools/jinja2/jinja2_required_variables.py::_collect_variable_references"]
+param = "node"
+rationale = "Extracts/derives from the node; single operand."
+
+["pipelex/tools/jinja2/jinja2_required_variables.py::_extract_filters_and_variable"]
+param = "node"
+rationale = "Extracts/derives from the node; single operand."
+
+["pipelex/tools/jinja2/jinja2_template_loader.py::TemplateLoader.is_loaded"]
+param = "name"
+rationale = "Predicate on the name; single operand."
+
+["pipelex/tools/jinja2/jinja2_template_loader.py::TemplateLoader.load"]
+param = "name"
+rationale = "Keyed accessor by the name; single operand."
+
+["pipelex/tools/jinja2/jinja2_template_loader.py::TemplateLoader.reload"]
+param = "name"
+rationale = "Keyed accessor by the name; single operand."
+
+["pipelex/tools/jinja2/jinja2_template_registry.py::TemplateRegistry.get"]
+param = "key"
+rationale = "Keyed accessor by the key; single operand."
+
+["pipelex/tools/jinja2/jinja2_template_registry.py::TemplateRegistry.is_registered"]
+param = "key"
+rationale = "Predicate on the key; single operand."
+
+["pipelex/tools/jinja2/jinja2_with_images_filter.py::_render_sequence_with_images"]
+param = "sequence"
+rationale = "Jinja op on the sequence; single operand (context keyword-only)."
+
+["pipelex/tools/log/log.py::Log._should_ignore"]
+param = "problem_id"
+rationale = "Predicate on the problem id; single operand."
+
+["pipelex/tools/log/log.py::Log.configure"]
+param = "log_config"
+rationale = "Setter: installs the log_config; single operand."
+
+["pipelex/tools/log/log.py::Log.configure_if_unset"]
+param = "log_config"
+rationale = "Setter: installs the log_config; single operand."
+
+["pipelex/tools/log/log.py::Log.critical"]
+param = "content"
+rationale = "Logs the content; single operand (formatting keyword-only)."
+
+["pipelex/tools/log/log.py::Log.debug"]
+param = "content"
+rationale = "Logs the content; single operand (formatting keyword-only)."
+
+["pipelex/tools/log/log.py::Log.dev"]
+param = "content"
+rationale = "Logs the content; single operand (formatting keyword-only)."
+
+["pipelex/tools/log/log.py::Log.error"]
+param = "content"
+rationale = "Logs the content; single operand (formatting keyword-only)."
+
+["pipelex/tools/log/log.py::Log.info"]
+param = "content"
+rationale = "Logs the content; single operand (formatting keyword-only)."
+
+["pipelex/tools/log/log.py::Log.set_level"]
+param = "level"
+rationale = "Setter: installs the level; single operand."
+
+["pipelex/tools/log/log.py::Log.set_level_by_name"]
+param = "level_name"
+rationale = "Setter: installs the level_name; single operand."
+
+["pipelex/tools/log/log.py::Log.set_level_for_package"]
+param = "package_name"
+rationale = "Setter: installs the package_name; single operand."
+
+["pipelex/tools/log/log.py::Log.set_levels_for_packages"]
+param = "package_log_levels"
+rationale = "Setter: installs the package_log_levels; single operand."
+
+["pipelex/tools/log/log.py::Log.set_log_mode"]
+param = "mode"
+rationale = "Setter: installs the mode; single operand."
+
+["pipelex/tools/log/log.py::Log.set_poor_log_formatter"]
+param = "formatter"
+rationale = "Setter: installs the formatter; single operand."
+
+["pipelex/tools/log/log.py::Log.verbose"]
+param = "content"
+rationale = "Logs the content; single operand (formatting keyword-only)."
+
+["pipelex/tools/log/log.py::Log.warning"]
+param = "content"
+rationale = "Logs the content; single operand (formatting keyword-only)."
+
+["pipelex/tools/log/log_config.py::CallerInfoTemplate.for_template_key"]
+param = "key"
+rationale = "Factory from source: builds the result from the key; single operand."
+
+["pipelex/tools/log/log_config.py::RichLogConfig.make_rich_handler"]
+param = "target"
+rationale = "Factory from source: builds the result from the target; single operand."
+
+["pipelex/tools/log/log_dispatch.py::LogDispatch._log_data"]
+param = "data"
+rationale = "Logs the content; single operand (formatting keyword-only)."
+
+["pipelex/tools/log/log_dispatch.py::LogDispatch._log_message"]
+param = "message"
+rationale = "Logs the content; single operand (formatting keyword-only)."
+
+["pipelex/tools/log/log_dispatch.py::LogDispatch._log_to_console"]
+param = "message"
+rationale = "Transforms the message; single operand."
+
+["pipelex/tools/log/log_dispatch.py::LogDispatch.configure"]
+param = "log_config"
+rationale = "Setter: installs the log_config; single operand."
+
+["pipelex/tools/log/log_dispatch.py::LogDispatch.dispatch"]
+param = "content"
+rationale = "Logs the content; single operand (formatting keyword-only)."
+
+["pipelex/tools/log/log_dispatch.py::LogDispatch.set_log_mode"]
+param = "mode"
+rationale = "Setter: installs the mode; single operand."
+
+["pipelex/tools/log/log_formatter.py::emoji_for_channel"]
+param = "channel_name"
+rationale = "Renders the channel_name; single operand."
+
+["pipelex/tools/mermaid/mermaid_utils.py::clean_str_for_mermaid_node_title"]
+param = "text"
+rationale = "Transforms the text; single operand."
+
+["pipelex/tools/mermaid/mermaid_utils.py::encode_pako_from_bytes"]
+param = "state_bytes"
+rationale = "Transforms the state_bytes; single operand."
+
+["pipelex/tools/mermaid/mermaid_utils.py::encode_pako_from_string"]
+param = "state"
+rationale = "Transforms the state; single operand."
+
+["pipelex/tools/mermaid/mermaid_utils.py::escape_mermaid_label"]
+param = "label"
+rationale = "Transforms the label; single operand."
+
+["pipelex/tools/mermaid/mermaid_utils.py::make_mermaid_url"]
+param = "mermaid_code"
+rationale = "Factory from source: builds the result from the mermaid_code; single operand."
+
+["pipelex/tools/mermaid/mermaid_utils.py::print_mermaid_url"]
+param = "url"
+rationale = "Renders the url; single operand."
+
+["pipelex/tools/mermaid/mermaid_utils.py::render_mermaid_html_generic"]
+param = "mermaid_code"
+rationale = "Jinja op on the mermaid_code; single operand (context keyword-only)."
+
+["pipelex/tools/mermaid/mermaid_utils.py::render_mermaid_html_generic_async"]
+param = "mermaid_code"
+rationale = "Jinja op on the mermaid_code; single operand (context keyword-only)."
+
+["pipelex/tools/mermaid/mermaid_utils.py::sanitize_mermaid_id"]
+param = "node_id"
+rationale = "Transforms the node_id; single operand."
+
+["pipelex/tools/misc/async_utils.py::_invoke"]
+param = "factory"
+rationale = "Operates on the factory; single operand (qualifiers keyword-only)."
+
+["pipelex/tools/misc/async_utils.py::gather_bounded"]
+param = "task_factories"
+rationale = "Operates on the task_factories; single operand (qualifiers keyword-only)."
+
+["pipelex/tools/misc/attribute_utils.py::AttributePolisher._looks_like_base64"]
+param = "value"
+rationale = "Predicate on the value; single operand."
+
+["pipelex/tools/misc/attribute_utils.py::AttributePolisher._truncate_bytes"]
+param = "value"
+rationale = "Transforms the value; single operand."
+
+["pipelex/tools/misc/attribute_utils.py::AttributePolisher._truncate_string"]
+param = "value"
+rationale = "Transforms the value; single operand."
+
+["pipelex/tools/misc/attribute_utils.py::AttributePolisher.apply_truncation_recursive"]
+param = "obj"
+rationale = "Operates on the obj; single operand (qualifiers keyword-only)."
+
+["pipelex/tools/misc/attribute_utils.py::AttributePolisher.get_truncated_value"]
+param = "value"
+rationale = "Keyed accessor by the value; single operand."
+
+["pipelex/tools/misc/attribute_utils.py::AttributePolisher.should_truncate"]
+param = "value"
+rationale = "Predicate on the value; single operand."
+
+["pipelex/tools/misc/base64_utils.py::extract_base64_str_from_base64_url_if_possible"]
+param = "possibly_base64_url"
+rationale = "Extracts/derives from the possibly_base64_url; single operand."
+
+["pipelex/tools/misc/base64_utils.py::is_prefixed_base64_url"]
+param = "possibly_base64_url"
+rationale = "Predicate on the possibly_base64_url; single operand."
+
+["pipelex/tools/misc/base64_utils.py::load_binary_as_base64"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/misc/base64_utils.py::make_base64_url"]
+param = "base64_data"
+rationale = "Factory from source: builds the result from the base64_data; single operand."
+
+["pipelex/tools/misc/base64_utils.py::make_base64_url_from_bytes"]
+param = "raw_bytes"
+rationale = "Factory from source: builds the result from the raw_bytes; single operand."
+
+["pipelex/tools/misc/base64_utils.py::make_base64_url_from_http_url"]
+param = "url"
+rationale = "Factory from source: builds the result from the url; single operand."
+
+["pipelex/tools/misc/base64_utils.py::make_base64_url_from_path"]
+param = "path"
+rationale = "Factory from source: builds the result from the path; single operand."
+
+["pipelex/tools/misc/base64_utils.py::strip_base64_str_if_needed"]
+param = "base64_str"
+rationale = "Transforms the base64_str; single operand."
+
+["pipelex/tools/misc/context_provider_abstract.py::ContextProviderAbstract.get_typed_object_or_attribute"]
+param = "name"
+rationale = "Keyed accessor by the name; single operand."
+
+["pipelex/tools/misc/dict_utils.py::apply_to_strings_in_list"]
+param = "data"
+rationale = "Transforms the data; single operand."
+
+["pipelex/tools/misc/dict_utils.py::apply_to_strings_recursive"]
+param = "data"
+rationale = "Transforms the data; single operand."
+
+["pipelex/tools/misc/dict_utils.py::extract_vars_from_strings_recursive"]
+param = "data"
+rationale = "Extracts/derives from the data; single operand."
+
+["pipelex/tools/misc/dict_utils.py::extract_vars_from_strings_recursive.extract_from_string"]
+param = "text"
+rationale = "Inner recursion helper: extracts vars from the text; single operand."
+
+["pipelex/tools/misc/dict_utils.py::extract_vars_from_strings_recursive.traverse"]
+param = "value"
+rationale = "Inner recursion helper: traverses the value; single operand."
+
+["pipelex/tools/misc/dict_utils.py::insert_before"]
+param = "dictionary"
+rationale = "Transforms the dictionary; single operand."
+
+["pipelex/tools/misc/dict_utils.py::substitute_nested_in_context"]
+param = "context"
+rationale = "Transforms the context; single operand."
+
+["pipelex/tools/misc/diff.py::_generate_diff_summary"]
+param = "diff_content"
+rationale = "Operates on the diff_content; single operand (qualifiers keyword-only)."
+
+["pipelex/tools/misc/diff.py::has_diff_dirs._filter_excluded_files"]
+param = "file_list"
+rationale = "Inner helper: filters the file list; single operand."
+
+["pipelex/tools/misc/diff.py::has_diff_dirs._has_diff"]
+param = "dir_comparison"
+rationale = "Inner helper: tests the dir comparison; single operand."
+
+["pipelex/tools/misc/diff.py::make_diff_dirs_pretty._collect_diffs"]
+param = "dir_comparison"
+rationale = "Inner helper: collects diffs from the dir comparison; single operand."
+
+["pipelex/tools/misc/diff.py::make_diff_dirs_pretty._filter_excluded_files"]
+param = "file_list"
+rationale = "Inner helper: filters the file list; single operand."
+
+["pipelex/tools/misc/document_utils.py::DocumentFormat.from_mime_type"]
+param = "mime_type"
+rationale = "Factory from source: builds the result from the mime_type; single operand."
+
+["pipelex/tools/misc/document_utils.py::DocumentFormat.is_supported_mime_type"]
+param = "mime_type"
+rationale = "Predicate on the mime_type; single operand."
+
+["pipelex/tools/misc/document_utils.py::DocumentFormat.raise_if_unsupported_mime_type"]
+param = "mime_type"
+rationale = "Validates/checks the mime_type; single operand."
+
+["pipelex/tools/misc/exceptions.py::TomlError.from_tomli_error"]
+param = "exc"
+rationale = "Factory from source: builds the result from the exc; single operand."
+
+["pipelex/tools/misc/file_fetch_utils.py::fetch_file_from_url_httpx"]
+param = "url"
+rationale = "Fetches the file at the URL; single operand."
+
+["pipelex/tools/misc/file_utils.py::_reraise_walk_error"]
+param = "walk_error"
+rationale = "File/path op on the walk_error; single operand."
+
+["pipelex/tools/misc/file_utils.py::copy_file_from_package"]
+param = "package_name"
+rationale = "File/path op on the package_name; single operand."
+
+["pipelex/tools/misc/file_utils.py::copy_folder_from_package"]
+param = "package_name"
+rationale = "File/path op on the package_name; single operand."
+
+["pipelex/tools/misc/file_utils.py::ensure_directory_exists"]
+param = "directory_path"
+rationale = "File/path op on the directory_path; single operand."
+
+["pipelex/tools/misc/file_utils.py::ensure_directory_for_file_path"]
+param = "file_path"
+rationale = "File/path op on the file_path; single operand."
+
+["pipelex/tools/misc/file_utils.py::ensure_path"]
+param = "path"
+rationale = "File/path op on the path; single operand."
+
+["pipelex/tools/misc/file_utils.py::failable_load_text_from_path"]
+param = "path"
+rationale = "Loads text from the path (failable); single operand."
+
+["pipelex/tools/misc/file_utils.py::find_files_in_dir"]
+param = "dir_path"
+rationale = "Extracts/derives from the dir_path; single operand."
+
+["pipelex/tools/misc/file_utils.py::get_incremental_directory_path"]
+param = "base_path"
+rationale = "File/path op on the base_path; single operand."
+
+["pipelex/tools/misc/file_utils.py::get_incremental_file_path"]
+param = "base_path"
+rationale = "File/path op on the base_path; single operand."
+
+["pipelex/tools/misc/file_utils.py::load_binary"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/misc/file_utils.py::load_binary_async"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/misc/file_utils.py::load_text_from_path"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/misc/file_utils.py::path_exists"]
+param = "path_str"
+rationale = "File/path op on the path_str; single operand."
+
+["pipelex/tools/misc/file_utils.py::reject_bare_str_or_path"]
+param = "value"
+rationale = "Validates/checks the value; single operand."
+
+["pipelex/tools/misc/file_utils.py::remove_file"]
+param = "file_path"
+rationale = "File/path op on the file_path; single operand."
+
+["pipelex/tools/misc/file_utils.py::remove_folder"]
+param = "folder_path"
+rationale = "File/path op on the folder_path; single operand."
+
+["pipelex/tools/misc/file_utils.py::save_bytes_to_binary_file"]
+param = "byte_data"
+rationale = "Transforms the byte_data; single operand."
+
+["pipelex/tools/misc/file_utils.py::save_text_to_path"]
+param = "text"
+rationale = "Transforms the text; single operand."
+
+["pipelex/tools/misc/filetype_utils.py::detect_file_type_from_base64"]
+param = "base64_data"
+rationale = "Parses/reads the base64_data; single operand."
+
+["pipelex/tools/misc/filetype_utils.py::detect_file_type_from_bytes"]
+param = "raw_bytes"
+rationale = "Parses/reads the raw_bytes; single operand."
+
+["pipelex/tools/misc/filetype_utils.py::detect_file_type_from_path"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/misc/filetype_utils.py::mime_type_to_extension"]
+param = "mime_type"
+rationale = "Transforms the mime_type; single operand."
+
+["pipelex/tools/misc/hash_utils.py::hash_md5_to_int"]
+param = "string"
+rationale = "Transforms the string; single operand."
+
+["pipelex/tools/misc/hash_utils.py::hash_sha256"]
+param = "data"
+rationale = "Transforms the data; single operand."
+
+["pipelex/tools/misc/http_utils.py::_validate_http_url"]
+param = "url"
+rationale = "Validates/checks the url; single operand."
+
+["pipelex/tools/misc/http_utils.py::_validate_local_path"]
+param = "url"
+rationale = "Validates/checks the url; single operand."
+
+["pipelex/tools/misc/http_utils.py::validate_url_resource_exists"]
+param = "url"
+rationale = "Validates/checks the url; single operand."
+
+["pipelex/tools/misc/image_utils.py::ImageFormat.from_mime_type"]
+param = "mime_type"
+rationale = "Factory from source: builds the result from the mime_type; single operand."
+
+["pipelex/tools/misc/image_utils.py::ImageFormat.is_supported_mime_type"]
+param = "mime_type"
+rationale = "Predicate on the mime_type; single operand."
+
+["pipelex/tools/misc/image_utils.py::ImageFormat.raise_if_unsupported_mime_type"]
+param = "mime_type"
+rationale = "Validates/checks the mime_type; single operand."
+
+["pipelex/tools/misc/image_utils.py::pil_image_to_bytes"]
+param = "pil_image"
+rationale = "Transforms the pil_image; single operand."
+
+["pipelex/tools/misc/json_utils.py::clean_json_content"]
+param = "content"
+rationale = "Transforms the content; single operand."
+
+["pipelex/tools/misc/json_utils.py::clean_json_dumps"]
+param = "data"
+rationale = "Transforms the data; single operand."
+
+["pipelex/tools/misc/json_utils.py::deep_update"]
+param = "target_dict"
+rationale = "Transforms the target_dict; single operand."
+
+["pipelex/tools/misc/json_utils.py::json_str"]
+param = "some_object"
+rationale = "Transforms the some_object; single operand."
+
+["pipelex/tools/misc/json_utils.py::load_json_dict_from_path"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/misc/json_utils.py::load_json_from_path"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/misc/json_utils.py::load_json_list_from_path"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/misc/json_utils.py::pure_json_str"]
+param = "data"
+rationale = "Transforms the data; single operand."
+
+["pipelex/tools/misc/json_utils.py::purify_json"]
+param = "data"
+rationale = "Transforms the data; single operand."
+
+["pipelex/tools/misc/json_utils.py::purify_json_dict"]
+param = "data"
+rationale = "Transforms the data; single operand."
+
+["pipelex/tools/misc/json_utils.py::purify_json_list"]
+param = "data"
+rationale = "Transforms the data; single operand."
+
+["pipelex/tools/misc/json_utils.py::remove_none_values"]
+param = "json_content"
+rationale = "Transforms the json_content; single operand."
+
+["pipelex/tools/misc/json_utils.py::remove_none_values_from_dict"]
+param = "data"
+rationale = "Transforms the data; single operand."
+
+["pipelex/tools/misc/json_utils.py::save_as_json_to_path"]
+param = "object_to_save"
+rationale = "Transforms the object_to_save; single operand."
+
+["pipelex/tools/misc/markdown_utils.py::convert_to_markdown"]
+param = "data"
+rationale = "Transforms the data; single operand."
+
+["pipelex/tools/misc/placeholder.py::make_placeholder_value"]
+param = "key"
+rationale = "Factory from source: builds the result from the key; single operand."
+
+["pipelex/tools/misc/placeholder.py::value_is_placeholder"]
+param = "value"
+rationale = "Predicate on the value; single operand."
+
+["pipelex/tools/misc/pretty.py::PrettyPrinter.make_pretty"]
+param = "value"
+rationale = "Factory from source: builds the result from the value; single operand."
+
+["pipelex/tools/misc/pretty.py::PrettyPrinter.make_pretty_panel"]
+param = "content"
+rationale = "Factory from source: builds the result from the content; single operand."
+
+["pipelex/tools/misc/pretty.py::PrettyPrinter.pretty_html"]
+param = "pretty"
+rationale = "Renders the pretty; single operand."
+
+["pipelex/tools/misc/pretty.py::PrettyPrinter.pretty_print"]
+param = "content"
+rationale = "Renders the content; single operand."
+
+["pipelex/tools/misc/pretty.py::PrettyPrinter.pretty_print_url_without_rich"]
+param = "content"
+rationale = "Renders the content; single operand."
+
+["pipelex/tools/misc/pretty.py::PrettyPrinter.pretty_print_using_rich"]
+param = "content"
+rationale = "Renders the content; single operand."
+
+["pipelex/tools/misc/pretty.py::PrettyPrinter.pretty_print_without_rich"]
+param = "content"
+rationale = "Renders the content; single operand."
+
+["pipelex/tools/misc/pretty.py::PrettyPrinter.pretty_svg"]
+param = "pretty"
+rationale = "Renders the pretty; single operand."
+
+["pipelex/tools/misc/pretty.py::PrettyPrinter.pretty_text"]
+param = "pretty"
+rationale = "Renders the pretty; single operand."
+
+["pipelex/tools/misc/pretty.py::PrettyPrinter.wrap_in_panel"]
+param = "pretty"
+rationale = "Renders the pretty; single operand."
+
+["pipelex/tools/misc/pretty.py::pretty_print"]
+param = "content"
+rationale = "Renders the content; single operand."
+
+["pipelex/tools/misc/pretty.py::pretty_print_md"]
+param = "content"
+rationale = "Renders the content; single operand."
+
+["pipelex/tools/misc/pretty.py::pretty_print_url"]
+param = "url"
+rationale = "Renders the url; single operand."
+
+["pipelex/tools/misc/semver.py::parse_constraint"]
+param = "constraint_str"
+rationale = "Parses/reads the constraint_str; single operand."
+
+["pipelex/tools/misc/semver.py::parse_version"]
+param = "version_str"
+rationale = "Parses/reads the version_str; single operand."
+
+["pipelex/tools/misc/semver.py::parse_version_tag"]
+param = "tag"
+rationale = "Parses/reads the tag; single operand."
+
+["pipelex/tools/misc/semver.py::select_minimum_version"]
+param = "available_versions"
+rationale = "Parses/reads the available_versions; single operand."
+
+["pipelex/tools/misc/semver.py::select_minimum_version_for_multiple_constraints"]
+param = "available_versions"
+rationale = "Parses/reads the available_versions; single operand."
+
+["pipelex/tools/misc/semver.py::version_satisfies"]
+param = "version"
+rationale = "Predicate on the version; single operand."
+
+["pipelex/tools/misc/string_utils.py::camel_to_snake_case"]
+param = "name"
+rationale = "Transforms the name; single operand."
+
+["pipelex/tools/misc/string_utils.py::can_inject_text"]
+param = "value"
+rationale = "Predicate on the value; single operand."
+
+["pipelex/tools/misc/string_utils.py::get_root_from_dotted_path"]
+param = "dotted_path"
+rationale = "Extracts/derives from the dotted_path; single operand."
+
+["pipelex/tools/misc/string_utils.py::has_text"]
+param = "text"
+rationale = "Predicate on the text; single operand."
+
+["pipelex/tools/misc/string_utils.py::is_none_or_has_text"]
+param = "text"
+rationale = "Predicate on the text; single operand."
+
+["pipelex/tools/misc/string_utils.py::is_not_none_and_has_text"]
+param = "text"
+rationale = "Predicate on the text; single operand."
+
+["pipelex/tools/misc/string_utils.py::is_pascal_case"]
+param = "word"
+rationale = "Predicate on the word; single operand."
+
+["pipelex/tools/misc/string_utils.py::is_snake_case"]
+param = "word"
+rationale = "Predicate on the word; single operand."
+
+["pipelex/tools/misc/string_utils.py::matches_wildcard_pattern"]
+param = "text"
+rationale = "Predicate on the text; single operand."
+
+["pipelex/tools/misc/string_utils.py::normalize_to_ascii"]
+param = "text"
+rationale = "Transforms the text; single operand."
+
+["pipelex/tools/misc/string_utils.py::pascal_case_to_kebab"]
+param = "name"
+rationale = "Transforms the name; single operand."
+
+["pipelex/tools/misc/string_utils.py::pascal_case_to_sentence"]
+param = "name"
+rationale = "Transforms the name; single operand."
+
+["pipelex/tools/misc/string_utils.py::pascal_case_to_snake_case"]
+param = "name"
+rationale = "Transforms the name; single operand."
+
+["pipelex/tools/misc/string_utils.py::snake_to_capitalize_first_letter"]
+param = "snake_str"
+rationale = "Transforms the snake_str; single operand."
+
+["pipelex/tools/misc/string_utils.py::snake_to_pascal_case"]
+param = "snake_str"
+rationale = "Transforms the snake_str; single operand."
+
+["pipelex/tools/misc/string_utils.py::snake_to_title_case"]
+param = "snake_str"
+rationale = "Transforms the snake_str; single operand."
+
+["pipelex/tools/misc/tenacity_utils.py::log_retry"]
+param = "retry_state"
+rationale = "Operates on the retry_state; single operand (qualifiers keyword-only)."
+
+["pipelex/tools/misc/toml_sync.py::collect_leaf_key_paths"]
+param = "doc"
+rationale = "Parses/reads the doc; single operand."
+
+["pipelex/tools/misc/toml_sync.py::get_nested_value"]
+param = "doc"
+rationale = "Parses/reads the doc; single operand."
+
+["pipelex/tools/misc/toml_sync.py::set_nested_value"]
+param = "doc"
+rationale = "Setter: installs the doc; single operand."
+
+["pipelex/tools/misc/toml_utils.py::load_toml_from_content"]
+param = "content"
+rationale = "Parses/reads the content; single operand."
+
+["pipelex/tools/misc/toml_utils.py::load_toml_from_path"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/misc/toml_utils.py::load_toml_from_path_and_merge_with_overrides"]
+param = "paths"
+rationale = "Parses/reads the paths; single operand."
+
+["pipelex/tools/misc/toml_utils.py::load_toml_from_path_if_exists"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/misc/toml_utils.py::load_toml_with_tomlkit"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/misc/toml_utils.py::save_toml_to_path"]
+param = "data"
+rationale = "Transforms the data; single operand."
+
+["pipelex/tools/network/host_rules.py::is_disallowed_host"]
+param = "host"
+rationale = "Predicate on the host; single operand."
+
+["pipelex/tools/network/host_rules.py::is_disallowed_ip"]
+param = "host"
+rationale = "Predicate on the host; single operand."
+
+["pipelex/tools/network/ssrf_guard.py::resolve_to_allowed_ips"]
+param = "host"
+rationale = "Parses/reads the host; single operand."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::PyPdfium2Renderer._extract_embedded_images_from_page_sync"]
+param = "pdf_input"
+rationale = "Extracts/derives from the pdf_input; single operand."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::PyPdfium2Renderer._extract_embedded_images_from_pdf_sync"]
+param = "pdf_input"
+rationale = "Extracts/derives from the pdf_input; single operand."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::PyPdfium2Renderer._extract_text_from_pdf_pages_sync"]
+param = "pdf_input"
+rationale = "Extracts/derives from the pdf_input; single operand."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::PyPdfium2Renderer._render_pdf_pages_sync"]
+param = "pdf_input"
+rationale = "Jinja op on the pdf_input; single operand (context keyword-only)."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::PyPdfium2Renderer.extract_embedded_images_from_page"]
+param = "pdf_input"
+rationale = "Extracts/derives from the pdf_input; single operand."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::PyPdfium2Renderer.extract_embedded_images_from_pdf"]
+param = "pdf_input"
+rationale = "Extracts/derives from the pdf_input; single operand."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::PyPdfium2Renderer.extract_embedded_images_from_pdf_uri"]
+param = "pdf_uri"
+rationale = "Extracts/derives from the pdf_uri; single operand."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::PyPdfium2Renderer.extract_text_from_pdf_pages"]
+param = "pdf_input"
+rationale = "Extracts/derives from the pdf_input; single operand."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::PyPdfium2Renderer.extract_text_from_pdf_pages_from_uri"]
+param = "pdf_uri"
+rationale = "Extracts/derives from the pdf_uri; single operand."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::PyPdfium2Renderer.render_pdf_pages"]
+param = "pdf_input"
+rationale = "Jinja op on the pdf_input; single operand (context keyword-only)."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::PyPdfium2Renderer.render_pdf_pages_from_uri"]
+param = "pdf_uri"
+rationale = "Jinja op on the pdf_uri; single operand (context keyword-only)."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::_extract_image_from_pdf_object"]
+param = "image_obj"
+rationale = "Extracts/derives from the image_obj; single operand."
+
+["pipelex/tools/pdf/pypdfium2_renderer.py::_resolve_pdf_uri_to_input"]
+param = "pdf_uri"
+rationale = "Parses/reads the pdf_uri; single operand."
+
+["pipelex/tools/secrets/secrets_provider_abstract.py::SecretsProviderAbstract.get_optional_secret"]
+param = "secret_id"
+rationale = "Keyed accessor by the secret_id; single operand."
+
+["pipelex/tools/secrets/secrets_provider_abstract.py::SecretsProviderAbstract.get_optional_secret_specific_version"]
+param = "secret_id"
+rationale = "Keyed accessor by the secret_id; single operand."
+
+["pipelex/tools/secrets/secrets_provider_abstract.py::SecretsProviderAbstract.get_required_secret"]
+param = "secret_id"
+rationale = "Keyed accessor by the secret_id; single operand."
+
+["pipelex/tools/secrets/secrets_provider_abstract.py::SecretsProviderAbstract.get_required_secret_specific_version"]
+param = "secret_id"
+rationale = "Keyed accessor by the secret_id; single operand."
+
+["pipelex/tools/secrets/secrets_provider_abstract.py::SecretsProviderAbstract.get_secret"]
+param = "secret_id"
+rationale = "Keyed accessor by the secret_id; single operand."
+
+["pipelex/tools/secrets/secrets_provider_abstract.py::SecretsProviderAbstract.set_secret_as_env_var"]
+param = "secret_id"
+rationale = "Setter: installs the secret_id; single operand."
+
+["pipelex/tools/secrets/secrets_utils.py::_get_env_var"]
+param = "var_name"
+rationale = "Keyed accessor by the var_name; single operand."
+
+["pipelex/tools/secrets/secrets_utils.py::_get_secret"]
+param = "secret_name"
+rationale = "Keyed accessor by the secret_name; single operand."
+
+["pipelex/tools/secrets/secrets_utils.py::_handle_fallback_pattern"]
+param = "var_spec"
+rationale = "Operates on the var_spec; single operand (qualifiers keyword-only)."
+
+["pipelex/tools/secrets/secrets_utils.py::substitute_vars"]
+param = "content"
+rationale = "Operates on the content; single operand (qualifiers keyword-only)."
+
+["pipelex/tools/secrets/secrets_utils.py::substitute_vars.replace_var"]
+param = "match"
+rationale = "Positional-Callable re.sub repl: match is the single operand re passes."
+
+["pipelex/tools/storage/gcp_storage_provider.py::GcpStorageProvider._generate_signed_url_sync"]
+param = "key"
+rationale = "Keyed accessor by the key; single operand."
+
+["pipelex/tools/storage/gcp_storage_provider.py::GcpStorageProvider._load_with_metadata_sync"]
+param = "key"
+rationale = "Parses/reads the key; single operand."
+
+["pipelex/tools/storage/gcp_storage_provider.py::GcpStorageProvider._make_public_url"]
+param = "key"
+rationale = "Factory from source: builds the result from the key; single operand."
+
+["pipelex/tools/storage/gcp_storage_provider.py::GcpStorageProvider._store_sync"]
+param = "data"
+rationale = "Stores the data; single operand (key keyword-only)."
+
+["pipelex/tools/storage/local_storage_provider.py::LocalStorageProvider._validate_key"]
+param = "key"
+rationale = "Keyed accessor by the key; single operand."
+
+["pipelex/tools/storage/s3_storage_provider.py::S3StorageProvider._make_public_url"]
+param = "key"
+rationale = "Factory from source: builds the result from the key; single operand."
+
+["pipelex/tools/storage/storage_provider_abstract.py::StorageProviderAbstract._add_scheme"]
+param = "key"
+rationale = "Keyed accessor by the key; single operand."
+
+["pipelex/tools/storage/storage_provider_abstract.py::StorageProviderAbstract._load_with_metadata"]
+param = "key"
+rationale = "Parses/reads the key; single operand."
+
+["pipelex/tools/storage/storage_provider_abstract.py::StorageProviderAbstract._store"]
+param = "data"
+rationale = "Keyed accessor by the data; single operand."
+
+["pipelex/tools/storage/storage_provider_abstract.py::StorageProviderAbstract._strip_scheme"]
+param = "uri"
+rationale = "Keyed accessor by the uri; single operand."
+
+["pipelex/tools/storage/storage_provider_abstract.py::StorageProviderAbstract.load"]
+param = "uri"
+rationale = "Keyed accessor by the uri; single operand."
+
+["pipelex/tools/storage/storage_provider_abstract.py::StorageProviderAbstract.load_with_metadata"]
+param = "uri"
+rationale = "Parses/reads the uri; single operand."
+
+["pipelex/tools/storage/storage_provider_abstract.py::StorageProviderAbstract.public_url"]
+param = "uri"
+rationale = "Keyed accessor by the uri; single operand."
+
+["pipelex/tools/storage/storage_provider_abstract.py::StorageProviderAbstract.store"]
+param = "data"
+rationale = "Keyed accessor by the data; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::_annotation_allows_none"]
+param = "annotation"
+rationale = "Validates/checks the annotation; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::_assert_single_char_delimiter"]
+param = "delimiter"
+rationale = "Validates/checks the delimiter; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::_is_flat_annotation"]
+param = "annotation"
+rationale = "Predicate on the annotation; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::_read_table"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::_row_to_dict"]
+param = "data_row"
+rationale = "Transforms the data_row; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::_to_cell"]
+param = "value"
+rationale = "Transforms the value; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::_validate_header"]
+param = "header"
+rationale = "Validates/checks the header; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::_validation_error_label"]
+param = "error"
+rationale = "Validates/checks the error; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::assert_supported_table_suffix"]
+param = "path"
+rationale = "File/path op on the path; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::csv_from_list_content"]
+param = "list_content"
+rationale = "Transforms the list_content; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::flat_field_names"]
+param = "row_model"
+rationale = "Transforms the row_model; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::is_tabular_path"]
+param = "path"
+rationale = "Predicate on the path; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::list_content_from_csv"]
+param = "path"
+rationale = "Transforms the path; single operand."
+
+["pipelex/tools/tabular/csv_codec.py::read_rows"]
+param = "path"
+rationale = "Parses/reads the path; single operand."
+
+["pipelex/tools/typing/class_utils.py::has_compatible_field"]
+param = "model_cls"
+rationale = "Predicate on the model_cls; single operand."
+
+["pipelex/tools/typing/class_utils.py::has_compatible_field._is_compatible"]
+param = "type_param"
+rationale = "Inner predicate: tests the type param; single operand."
+
+["pipelex/tools/typing/class_utils.py::normalize_properties_for_comparison"]
+param = "properties"
+rationale = "Transforms the properties; single operand."
+
+["pipelex/tools/typing/class_utils.py::normalize_property_for_comparison"]
+param = "prop"
+rationale = "Transforms the prop; single operand."
+
+["pipelex/tools/typing/module_inspector.py::convert_file_path_to_module_path"]
+param = "file_path"
+rationale = "Extracts/derives from the file_path; single operand."
+
+["pipelex/tools/typing/module_inspector.py::find_class_names_in_file"]
+param = "file_path"
+rationale = "Extracts/derives from the file_path; single operand."
+
+["pipelex/tools/typing/module_inspector.py::find_classes_in_module"]
+param = "module"
+rationale = "Extracts/derives from the module; single operand."
+
+["pipelex/tools/typing/module_inspector.py::find_decorated_function_names_in_file"]
+param = "file_path"
+rationale = "Extracts/derives from the file_path; single operand."
+
+["pipelex/tools/typing/module_inspector.py::import_module_from_file"]
+param = "file_path"
+rationale = "Inspects the file_path; single operand."
+
+["pipelex/tools/typing/module_inspector.py::import_module_from_file_if_has_classes"]
+param = "file_path"
+rationale = "Inspects the file_path; single operand."
+
+["pipelex/tools/typing/module_inspector.py::import_module_from_file_if_has_decorated_functions"]
+param = "file_path"
+rationale = "Inspects the file_path; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::_serialize_context"]
+param = "ctx"
+rationale = "Transforms the ctx; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::_serialize_input_value"]
+param = "value"
+rationale = "Transforms the value; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::_truncated_rich_repr_from_items"]
+param = "rich_repr_items"
+rationale = "Transforms the rich_repr_items; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::analyze_pydantic_validation_error"]
+param = "exc"
+rationale = "Validates/checks the exc; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::clean_model_to_dict"]
+param = "obj"
+rationale = "Transforms the obj; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::convert_strenum_to_str"]
+param = "obj"
+rationale = "Transforms the obj; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::empty_dict_factory_of"]
+param = "_key"
+rationale = "Factory from source: builds the result from the _key; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::empty_list_factory_of"]
+param = "_"
+rationale = "Factory from source: builds the result from the _; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::format_pydantic_validation_error"]
+param = "exc"
+rationale = "Validates/checks the exc; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::format_pydantic_validation_error_for_agent"]
+param = "exc"
+rationale = "Validates/checks the exc; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::make_truncated_wrapper"]
+param = "model"
+rationale = "Factory from source: builds the result from the model; single operand."
+
+["pipelex/tools/typing/pydantic_utils.py::make_truncated_wrapper.rich_repr_method"]
+param = "_self"
+rationale = "Positional-Callable __rich_repr__: the bound instance is passed positionally by Rich."
+
+["pipelex/tools/typing/pydantic_utils.py::serialize_model"]
+param = "obj"
+rationale = "Transforms the obj; single operand."
+
+["pipelex/tools/typing/structure_printer.py::StructurePrinter.get_type_structure"]
+param = "tp"
+rationale = "Keyed accessor by the tp; single operand."
+
+["pipelex/tools/typing/structure_printer.py::StructurePrinter.get_type_structure.collect_types"]
+param = "tp"
+rationale = "Inner recursion helper: collects types from tp; single operand."
+
+["pipelex/tools/typing/structure_printer.py::StructurePrinter.get_type_structure.format_type"]
+param = "tp"
+rationale = "Inner recursion helper: formats tp; single operand."
+
+["pipelex/tools/typing/structure_printer.py::StructurePrinter.pretty_type"]
+param = "tp"
+rationale = "Renders the tp; single operand."
+
+["pipelex/tools/typing/validation_utils.py::has_exactly_one_among_attributes_from_list"]
+param = "obj"
+rationale = "Predicate on the obj; single operand."
+
+["pipelex/tools/typing/validation_utils.py::has_more_than_one_among_attributes_from_list"]
+param = "obj"
+rationale = "Predicate on the obj; single operand."
+
+["pipelex/tools/typing/validation_utils.py::has_more_than_one_among_attributes_from_lists"]
+param = "obj"
+rationale = "Predicate on the obj; single operand."
+
+["pipelex/tools/uri/uri_resolver.py::_resolve_base64_data_url"]
+param = "uri"
+rationale = "Parses/reads the uri; single operand."
+
+["pipelex/tools/uri/uri_resolver.py::_resolve_file_uri"]
+param = "uri"
+rationale = "Parses/reads the uri; single operand."
+
+["pipelex/tools/uri/uri_resolver.py::describe_uri"]
+param = "uri"
+rationale = "Parses/reads the uri; single operand."
+
+["pipelex/tools/uri/uri_resolver.py::extract_filename_from_uri"]
+param = "uri"
+rationale = "Extracts/derives from the uri; single operand."
+
+["pipelex/tools/uri/uri_resolver.py::is_relative_local_path"]
+param = "uri"
+rationale = "Predicate on the uri; single operand."
+
+["pipelex/tools/uri/uri_resolver.py::make_base64_url_from_any_uri"]
+param = "uri"
+rationale = "Factory from source: builds the result from the uri; single operand."
+
+["pipelex/tools/uri/uri_resolver.py::resolve_local_path_reference"]
+param = "uri"
+rationale = "Verb-object: resolves the uri; base_dir is context."
+
+["pipelex/tools/uri/uri_resolver.py::resolve_uri"]
+param = "uri"
+rationale = "Parses/reads the uri; single operand."
+
+["pipelex/tracing/activity_event_log.py::ActivityEventLogCache.get_or_create"]
+param = "tracing_config"
+rationale = "Factory from source: builds the event log from the tracing config; single operand."
+
+["pipelex/tracing/dynamodb_event_log.py::DynamoDBEventLog._key_condition"]
+param = "pipeline_run_id"
+rationale = "Derivation: encodes the run id into a key condition; single operand."
+
+["pipelex/tracing/dynamodb_event_log.py::DynamoDBEventLog._make_pk"]
+param = "pipeline_run_id"
+rationale = "Derivation: encodes the run id into the partition key; single operand."
+
+["pipelex/tracing/dynamodb_event_log.py::DynamoDBEventLog._make_sk"]
+param = "workflow_id"
+rationale = "Derivation: encodes the workflow id into the sort key; writer/sequence stay keyword."
+
+["pipelex/tracing/event_log_factory.py::make_event_log"]
+param = "tracing_config"
+rationale = "Factory from source: builds the event log from the tracing config; writer_id stays keyword."
+
+["pipelex/tracing/event_log_protocol.py::EventLogProtocol.cleanup"]
+param = "pipeline_run_id"
+rationale = "Protocol method: purges the run identified by the id; single operand across implementations."
+
+["pipelex/tracing/event_log_protocol.py::EventLogProtocol.emit"]
+param = "event"
+rationale = "Protocol method: emits the trace event; single operand across implementations."
+
+["pipelex/tracing/event_log_protocol.py::EventLogProtocol.read_events"]
+param = "pipeline_run_id"
+rationale = "Protocol method: reads the run identified by the id; single operand across implementations."
+
+["pipelex/tracing/graphspec_assembler.py::GraphSpecAssembler.assemble"]
+param = "events"
+rationale = "Verb-object: assembles the graph from the events; graph metadata stays keyword."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_batch_aggregate"]
+param = "event"
+rationale = "Dispatch handler: handles the event; single operand."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_batch_item"]
+param = "event"
+rationale = "Dispatch handler: handles the event; single operand."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_controller_output"]
+param = "event"
+rationale = "Dispatch handler: handles the event; single operand."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_edge_event"]
+param = "event"
+rationale = "Dispatch handler: handles the event; single operand."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_execution_data"]
+param = "event"
+rationale = "Dispatch handler: handles the event; single operand."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_parallel_combine"]
+param = "event"
+rationale = "Dispatch handler: handles the event; single operand."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_pipe_end_error"]
+param = "event"
+rationale = "Dispatch handler: handles the event; single operand."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_pipe_end_skipped"]
+param = "event"
+rationale = "Protocol event handler: the event is the single operand."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_pipe_end_success"]
+param = "event"
+rationale = "Dispatch handler: handles the event; single operand."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_pipe_start"]
+param = "event"
+rationale = "Dispatch handler: handles the event; single operand."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState._track_earliest_timestamp"]
+param = "event"
+rationale = "Verb-object: reads the event to track its timestamp; single operand."
+
+["pipelex/tracing/graphspec_assembler.py::_AssemblerState.pass_one"]
+param = "events"
+rationale = "First pass over the event sequence; single operand."
+
+["pipelex/tracing/ndjson_event_log.py::NdjsonEventLog._file_name_for"]
+param = "workflow_id"
+rationale = "Derivation: encodes the workflow id into a file name; writer_id stays keyword."
+
+["pipelex/tracing/usage_aggregator.py::UsageAggregator.aggregate"]
+param = "events"
+rationale = "Verb-object: aggregates the events; single operand."
diff --git a/tests/e2e/pipelex/pipes/optionals/test_optionals_showcase_mthds.py b/tests/e2e/pipelex/pipes/optionals/test_optionals_showcase_mthds.py
index e913c915a..2cc2cf437 100644
--- a/tests/e2e/pipelex/pipes/optionals/test_optionals_showcase_mthds.py
+++ b/tests/e2e/pipelex/pipes/optionals/test_optionals_showcase_mthds.py
@@ -129,7 +129,7 @@ class TestOptionalsShowcaseE2E:
also auto-registers the co-located @pipe_func implementations.
"""
await _execute_run(
- "oshow_lift_only_flow",
+ pipe_code="oshow_lift_only_flow",
bundle_path=None,
inputs=None,
save_working_memory=True,
diff --git a/tests/integration/pipelex/cli/commands/init/test_cache_priming.py b/tests/integration/pipelex/cli/commands/init/test_cache_priming.py
index a990d959f..95e73689d 100644
--- a/tests/integration/pipelex/cli/commands/init/test_cache_priming.py
+++ b/tests/integration/pipelex/cli/commands/init/test_cache_priming.py
@@ -125,7 +125,7 @@ class TestCachePriming:
mocker.patch("httpx.get", return_value=_make_httpx_response(_fake_remote_payload()))
console = mocker.create_autospec(Console, instance=True)
- prime_remote_config_cache(console)
+ prime_remote_config_cache(console=console)
cache_path = RemoteConfigCache.cache_path()
assert cache_path.exists(), "priming should write the on-disk cache"
@@ -150,7 +150,7 @@ class TestCachePriming:
mocker.patch("httpx.get", side_effect=httpx.ConnectError("no network"))
console = mocker.create_autospec(Console, instance=True)
- prime_remote_config_cache(console) # must NOT raise
+ prime_remote_config_cache(console=console) # must NOT raise
cache_path = RemoteConfigCache.cache_path()
assert not cache_path.exists(), "priming must not create a cache file when offline"
@@ -166,7 +166,7 @@ class TestCachePriming:
httpx_get_mock = mocker.patch("httpx.get", side_effect=httpx.ConnectError("no network"))
console = mocker.create_autospec(Console, instance=True)
- prime_remote_config_cache(console)
+ prime_remote_config_cache(console=console)
assert fetch_spy.call_count == 0, "priming must not invoke the fetcher when gateway is disabled"
assert httpx_get_mock.call_count == 0, "priming must not hit the network when gateway is disabled"
@@ -201,7 +201,7 @@ class TestCachePriming:
mocker.patch("httpx.get", side_effect=httpx.ConnectError("no network"))
console = mocker.create_autospec(Console, instance=True)
- prime_remote_config_cache(console) # must NOT raise
+ prime_remote_config_cache(console=console) # must NOT raise
printed = " ".join(str(call_args) for call_args in console.print.call_args_list)
assert "yellow" in printed.lower(), f"stale-cache-offline priming must warn; got: {printed!r}"
@@ -254,7 +254,7 @@ class TestCachePriming:
mocker.patch("httpx.get", return_value=_make_httpx_response(_fake_remote_payload()))
console = mocker.create_autospec(Console, instance=True)
- prime_remote_config_cache(console, target_config_dir=target_dir)
+ prime_remote_config_cache(console=console, target_config_dir=target_dir)
assert RemoteConfigCache.cache_path().exists(), (
"priming must run (and write the cache) when the TARGET backends.toml has gateway "
@@ -290,7 +290,7 @@ class TestCachePriming:
httpx_get_mock = mocker.patch("httpx.get", side_effect=httpx.ConnectError("should not be called"))
console = mocker.create_autospec(Console, instance=True)
- prime_remote_config_cache(console, target_config_dir=target_dir)
+ prime_remote_config_cache(console=console, target_config_dir=target_dir)
assert fetch_spy.call_count == 0, "target dir disables the gateway — priming must NOT consult the layered backends.toml"
assert httpx_get_mock.call_count == 0
@@ -320,7 +320,7 @@ class TestCachePriming:
mocker.patch.object(RemoteConfigCache, "store", side_effect=OSError("read-only cache directory"))
console = mocker.create_autospec(Console, instance=True)
- prime_remote_config_cache(console) # must NOT raise
+ prime_remote_config_cache(console=console) # must NOT raise
cache_path = RemoteConfigCache.cache_path()
assert not cache_path.exists(), "no cache file should exist when the write failed"
@@ -352,7 +352,7 @@ class TestCachePriming:
mocker.patch.object(RemoteConfigCache, "store", side_effect=_store_malformed_cache)
console = mocker.create_autospec(Console, instance=True)
- prime_remote_config_cache(console) # must NOT raise
+ prime_remote_config_cache(console=console) # must NOT raise
printed = " ".join(str(call_args) for call_args in console.print.call_args_list)
assert "yellow" in printed.lower(), f"a malformed cached payload must surface a yellow warning; got: {printed!r}"
@@ -382,7 +382,7 @@ class TestCachePriming:
mocker.patch("httpx.get", return_value=_make_httpx_response(_fake_remote_payload()))
console = mocker.create_autospec(Console, instance=True)
- prime_remote_config_cache(console)
+ prime_remote_config_cache(console=console)
fresh_on_disk = json.loads(cache_path.read_text(encoding="utf-8"))
assert fresh_on_disk["raw_config"]["aws_region"] == "us-east-1", "priming must overwrite the existing cache"
diff --git a/tests/unit/pipelex/cli/commands/run/test_inputs_file_probe.py b/tests/unit/pipelex/cli/commands/run/test_inputs_file_probe.py
index 11f2f63ae..733785804 100644
--- a/tests/unit/pipelex/cli/commands/run/test_inputs_file_probe.py
+++ b/tests/unit/pipelex/cli/commands/run/test_inputs_file_probe.py
@@ -19,18 +19,18 @@ class TestFindDefaultInputsFile:
json_file = tmp_path / "inputs.json"
json_file.write_text("{}", encoding="utf-8")
- assert find_default_inputs_file(tmp_path) == json_file
+ assert find_default_inputs_file(directory=tmp_path) == json_file
def test_toml_only_is_found(self, tmp_path: Path) -> None:
"""With only inputs.toml present, the probe returns it."""
toml_file = tmp_path / "inputs.toml"
toml_file.write_text("", encoding="utf-8")
- assert find_default_inputs_file(tmp_path) == toml_file
+ assert find_default_inputs_file(directory=tmp_path) == toml_file
def test_neither_returns_none(self, tmp_path: Path) -> None:
"""With neither default file present, the probe returns None."""
- assert find_default_inputs_file(tmp_path) is None
+ assert find_default_inputs_file(directory=tmp_path) is None
def test_both_present_raises_ambiguity_error(self, tmp_path: Path) -> None:
"""With both default files present, the probe hard-errors telling the user to pass --inputs."""
@@ -38,7 +38,7 @@ class TestFindDefaultInputsFile:
(tmp_path / "inputs.toml").write_text("", encoding="utf-8")
with pytest.raises(AmbiguousInputsFilesError) as exc_info:
- find_default_inputs_file(tmp_path)
+ find_default_inputs_file(directory=tmp_path)
assert "--inputs" in exc_info.value.message
assert "inputs.json" in exc_info.value.message
assert "inputs.toml" in exc_info.value.message
diff --git a/tests/unit/pipelex/cli/conftest.py b/tests/unit/pipelex/cli/conftest.py
index 820b1ded1..3b4cb078d 100644
--- a/tests/unit/pipelex/cli/conftest.py
+++ b/tests/unit/pipelex/cli/conftest.py
@@ -21,9 +21,9 @@ def reset_traceback_requested() -> Iterator[None]:
this flag; without a reset a leaked ``True`` would make a sibling test's "no flag"
assertion order-dependent.
"""
- set_traceback_requested(False)
+ set_traceback_requested(value=False)
yield
- set_traceback_requested(False)
+ set_traceback_requested(value=False)
@pytest.fixture(autouse=True)
diff --git a/tests/unit/pipelex/cli/dev/conftest.py b/tests/unit/pipelex/cli/dev/conftest.py
new file mode 100644
index 000000000..6e4b8f5ac
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/conftest.py
@@ -0,0 +1,74 @@
+"""Shared fixtures for dev CLI unit tests: a real temporary git repository."""
+
+from __future__ import annotations
+
+import subprocess # noqa: S404
+from typing import TYPE_CHECKING
+
+import pytest
+from rich.console import Console
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+
+class GitRepo:
+ """A disposable git repository under tmp_path, with staging/commit helpers."""
+
+ def __init__(self, root: Path) -> None:
+ self.root = root
+
+ def git(self, *args: str) -> str:
+ result = subprocess.run( # noqa: S603
+ ["git", *args], # noqa: S607
+ cwd=self.root,
+ capture_output=True,
+ text=True,
+ timeout=30,
+ check=True,
+ )
+ return result.stdout
+
+ def write(self, relative_path: str, *, content: str) -> Path:
+ target = self.root / relative_path
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_text(content)
+ return target
+
+ def add(self, *paths: str) -> None:
+ self.git("add", "--", *paths)
+
+ def add_all(self) -> None:
+ self.git("add", "-A")
+
+ def commit(self, message: str = "test commit") -> None:
+ self.git("commit", "-q", "--no-verify", "-m", message)
+
+ def write_and_commit(self, relative_path: str, *, content: str) -> Path:
+ target = self.write(relative_path, content=content)
+ self.add(relative_path)
+ self.commit(f"add {relative_path}")
+ return target
+
+
+def drift_console(mocker: MockerFixture) -> Console:
+ """A recording console patched into the drift command module (the hub console binds stdout at creation)."""
+ recorded_console = Console(width=200, record=True, color_system=None)
+ mocker.patch("pipelex.cli.dev_cli.commands.drift.drift_cmd.get_console", return_value=recorded_console)
+ return recorded_console
+
+
+def git_repo(tmp_path: Path) -> GitRepo:
+ """A fresh git repository with local identity configured (independent of the host's config)."""
+ root = tmp_path / "repo"
+ root.mkdir()
+ repo = GitRepo(root)
+ repo.git("init", "-q")
+ repo.git("config", "user.name", "Test User")
+ repo.git("config", "user.email", "[email protected]")
+ repo.git("config", "commit.gpgsign", "false")
+ return repo
diff --git a/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd.py b/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd.py
index 4558c9082..de651912a 100644
--- a/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd.py
+++ b/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd.py
@@ -5,28 +5,46 @@ from __future__ import annotations
import textwrap
from pipelex.cli.dev_cli.commands.keyword_only_guard import (
+ SubjectGrant,
Violation,
+ ViolationKind,
find_violations_in_source,
)
-def _violate(source: str, *, module_qname: str = "pipelex.sample.module", relative_path: str = "pipelex/sample/module.py") -> list[Violation]:
+def _grant(key: str, *, param: str) -> dict[str, SubjectGrant]:
+ """A one-entry grants mapping for an inline snippet."""
+ return {key: SubjectGrant(param=param, rationale="test grant")}
+
+
+def _violate(
+ source: str,
+ *,
+ module_qname: str = "pipelex.sample.module",
+ relative_path: str = "pipelex/sample/module.py",
+ grants: dict[str, SubjectGrant] | None = None,
+) -> list[Violation]:
"""Run the guard over an inline snippet and return its violations."""
- return find_violations_in_source(textwrap.dedent(source), module_qname=module_qname, relative_path=relative_path)
+ return find_violations_in_source(textwrap.dedent(source), module_qname=module_qname, relative_path=relative_path, grants=grants or {})
def _keys(violations: list[Violation]) -> set[str]:
return {violation.key for violation in violations}
+def _kinds(violations: list[Violation]) -> set[ViolationKind]:
+ return {violation.kind for violation in violations}
+
+
class TestCheckKeywordOnly:
- def test_compliant_with_bare_star(self) -> None:
- """A subject followed by keyword-only options is compliant."""
+ def test_compliant_with_bare_star_and_grant(self) -> None:
+ """A granted subject followed by keyword-only options is compliant."""
violations = _violate(
"""
def build_pipe(spec, *, dry_run, retries, validate):
...
- """
+ """,
+ grants=_grant("pipelex/sample/module.py::build_pipe", param="spec"),
)
assert violations == []
@@ -50,34 +68,190 @@ class TestCheckKeywordOnly:
)
assert _keys(violations) == {"pipelex/sample/module.py::copy_file"}
- def test_exception_1_subject_only_positional_compliant(self) -> None:
- """A lone subject (single positional-or-keyword param) is compliant — Exception 1."""
+ def test_granted_lone_subject_compliant(self) -> None:
+ """A lone subject (single positional-or-keyword param) is compliant when granted."""
+ violations = _violate(
+ """
+ def render(node):
+ ...
+ """,
+ grants=_grant("pipelex/sample/module.py::render", param="node"),
+ )
+ assert violations == []
+
+ def test_ungranted_lone_subject_is_a_violation(self) -> None:
+ """A positional subject without a grant is a violation — the generic Exception 1 is gone."""
violations = _violate(
"""
def render(node):
...
"""
)
+ assert _keys(violations) == {"pipelex/sample/module.py::render"}
+ assert _kinds(violations) == {ViolationKind.UNGRANTED_SUBJECT}
+
+ def test_granted_subject_plus_keyword_only_compliant(self) -> None:
+ """A granted subject plus a single keyword-only option is compliant."""
+ violations = _violate(
+ """
+ def truncate(text, *, max_length=80):
+ ...
+ """,
+ grants=_grant("pipelex/sample/module.py::truncate", param="text"),
+ )
assert violations == []
- def test_exception_1_subject_plus_one_keyword_only_compliant(self) -> None:
- """Subject plus a single keyword-only option is compliant — Exception 1."""
+ def test_ungranted_subject_plus_keyword_only_is_a_violation(self) -> None:
+ """The strict-all scope: subject-plus-kwonly defs need a grant just like lone-subject defs."""
violations = _violate(
"""
def truncate(text, *, max_length=80):
...
"""
)
+ assert _kinds(violations) == {ViolationKind.UNGRANTED_SUBJECT}
+
+ def test_grant_param_mismatch_is_a_violation(self) -> None:
+ """A grant whose recorded param no longer matches the def's subject is a violation (symmetric staleness)."""
+ violations = _violate(
+ """
+ def render(new_name):
+ ...
+ """,
+ grants=_grant("pipelex/sample/module.py::render", param="node"),
+ )
+ assert _kinds(violations) == {ViolationKind.GRANT_PARAM_MISMATCH}
+ assert "node" in violations[0].detail
+ assert "new_name" in violations[0].detail
+
+ def test_missing_star_dominates_subject_rules(self) -> None:
+ """A def with a second positional param reports missing-star, even when its subject is granted."""
+ violations = _violate(
+ """
+ def build_pipe(spec, options):
+ ...
+ """,
+ grants=_grant("pipelex/sample/module.py::build_pipe", param="spec"),
+ )
+ assert _kinds(violations) == {ViolationKind.MISSING_STAR}
+
+ def test_same_qualname_defs_share_one_grant(self) -> None:
+ """@overload-style same-qualname defs collapse onto one key; a single grant covers them all (D11)."""
+ source = """
+ def parse(spec, *, strict=False):
+ ...
+
+ def parse(spec):
+ ...
+ """
+ assert _violate(source, grants=_grant("pipelex/sample/module.py::parse", param="spec")) == []
+
+ def test_same_qualname_defs_must_all_match_the_grant(self) -> None:
+ """When same-qualname defs disagree with the recorded param, each mismatching def is flagged."""
+ source = """
+ def parse(spec):
+ ...
+
+ def parse(data):
+ ...
+ """
+ violations = _violate(source, grants=_grant("pipelex/sample/module.py::parse", param="spec"))
+ assert _kinds(violations) == {ViolationKind.GRANT_PARAM_MISMATCH}
+ assert len(violations) == 1
+
+ def test_literal_bool_subject_banned_even_with_grant(self) -> None:
+ """A bool subject is a violation no matter what — a grant cannot cover it."""
+ violations = _violate(
+ """
+ def do_doctor_cmd(fix: bool):
+ ...
+ """,
+ grants=_grant("pipelex/sample/module.py::do_doctor_cmd", param="fix"),
+ )
+ assert _kinds(violations) == {ViolationKind.LITERAL_SUBJECT}
+
+ def test_literal_int_and_float_subjects_banned(self) -> None:
+ """Int and float subjects are banned like bool."""
+ violations = _violate(
+ """
+ def retry(count: int):
+ ...
+
+ def scale(factor: float):
+ ...
+ """
+ )
+ assert _kinds(violations) == {ViolationKind.LITERAL_SUBJECT}
+ assert len(violations) == 2
+
+ def test_literal_optional_and_union_forms_banned(self) -> None:
+ """Optional[X] / X | None / Union[X, None] forms of literal types are banned too."""
+ violations = _violate(
+ """
+ def f1(flag: Optional[bool]):
+ ...
+
+ def f2(flag: bool | None):
+ ...
+
+ def f3(count: Union[int, None]):
+ ...
+
+ def f4(count: None | int):
+ ...
+ """
+ )
+ assert _kinds(violations) == {ViolationKind.LITERAL_SUBJECT}
+ assert len(violations) == 4
+
+ def test_non_literal_union_subject_is_grantable(self) -> None:
+ """A union carrying a non-literal member (int | str) is not literal-typed — a grant covers it."""
+ violations = _violate(
+ """
+ def lookup(key: int | str):
+ ...
+ """,
+ grants=_grant("pipelex/sample/module.py::lookup", param="key"),
+ )
+ assert violations == []
+
+ def test_str_and_unannotated_subjects_stay_grantable(self) -> None:
+ """Str subjects are the house style and unannotated subjects are not provably literal — both grantable."""
+ source = """
+ def by_code(pipe_code: str):
+ ...
+
+ def render(node):
+ ...
+ """
+ grants = {
+ "pipelex/sample/module.py::by_code": SubjectGrant(param="pipe_code", rationale="test grant"),
+ "pipelex/sample/module.py::render": SubjectGrant(param="node", rationale="test grant"),
+ }
+ assert _violate(source, grants=grants) == []
+
+ def test_escape_hatch_beats_subject_rules(self) -> None:
+ """`# kw-only: ignore` short-circuits before the subject rules — no grant needed, literal or not."""
+ violations = _violate(
+ """
+ def version_callback(value: bool): # kw-only: ignore
+ ...
+
+ def render(node): # kw-only: ignore
+ ...
+ """
+ )
assert violations == []
- def test_method_self_dropped_then_subject_only_compliant(self) -> None:
- """`self` is dropped, leaving a lone subject — compliant."""
+ def test_method_self_dropped_then_granted_subject_compliant(self) -> None:
+ """`self` is dropped, leaving a granted lone subject — compliant."""
violations = _violate(
"""
class Foo:
def render(self, node):
...
- """
+ """,
+ grants=_grant("pipelex/sample/module.py::Foo.render", param="node"),
)
assert violations == []
@@ -105,12 +279,13 @@ class TestCheckKeywordOnly:
assert _keys(violations) == {"pipelex/sample/module.py::Bar.make"}
def test_args_kwargs_do_not_count(self) -> None:
- """A lone subject followed only by *args/**kwargs is compliant."""
+ """A granted lone subject followed only by *args/**kwargs is compliant."""
violations = _violate(
"""
def dispatch(subject, *args, **kwargs):
...
- """
+ """,
+ grants=_grant("pipelex/sample/module.py::dispatch", param="subject"),
)
assert violations == []
@@ -312,7 +487,7 @@ class TestCheckKeywordOnly:
false-positive violation on an explicitly-suppressed def (which would wrongly block a hook edit).
"""
source = 'page = "one\x0ctwo"\ndef safe(spec, dry_run): # kw-only: ignore\n return spec\n'
- violations = find_violations_in_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ violations = find_violations_in_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants={})
assert violations == []
def test_async_def_supported(self) -> None:
@@ -333,6 +508,7 @@ class TestCheckKeywordOnly:
def method(self, subject):
def inner(first, second):
...
- """
+ """,
+ grants=_grant("pipelex/sample/module.py::Outer.method", param="subject"),
)
assert _keys(violations) == {"pipelex/sample/module.py::Outer.method.inner"}
diff --git a/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd_fix.py b/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd_fix.py
index b388e775b..c816a0271 100644
--- a/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd_fix.py
+++ b/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd_fix.py
@@ -18,7 +18,7 @@ from rich.console import Console
from pipelex.cli.dev_cli.commands import check_keyword_only_cmd as cmd_mod
from pipelex.cli.dev_cli.commands.check_keyword_only_cmd import check_keyword_only_cmd
-from pipelex.cli.dev_cli.commands.keyword_only_guard import Violation
+from pipelex.cli.dev_cli.commands.keyword_only_guard import Violation, ViolationKind
if TYPE_CHECKING:
from pathlib import Path
@@ -27,7 +27,7 @@ if TYPE_CHECKING:
def _violation(name: str) -> Violation:
- return Violation(relative_path="pipelex/sample/module.py", qualified_name=name, lineno=7)
+ return Violation(relative_path="pipelex/sample/module.py", qualified_name=name, lineno=7, kind=ViolationKind.MISSING_STAR)
class TestCheckKeywordOnlyCmdFix:
@@ -38,6 +38,8 @@ class TestCheckKeywordOnlyCmdFix:
mocker.patch.object(cmd_mod, "get_console", return_value=Console(file=buffer, force_terminal=False, width=200))
# SOURCE_ROOT only needs to exist for the guard's pre-flight check; the scanners are mocked per test.
mocker.patch.object(cmd_mod, "SOURCE_ROOT", tmp_path)
+ # The registry is loaded before any scan; these tests drive the scanners directly, so keep it empty.
+ mocker.patch.object(cmd_mod, "load_subject_grants", return_value={})
return buffer
def test_fix_only_exits_zero_and_reports_fixed(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
diff --git a/tests/unit/pipelex/cli/dev/test_drift_ack_cmd.py b/tests/unit/pipelex/cli/dev/test_drift_ack_cmd.py
new file mode 100644
index 000000000..a42652377
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_drift_ack_cmd.py
@@ -0,0 +1,143 @@
+"""Unit tests for `pipelex-dev drift ack`: verify gating, reviewer resolution, index semantics."""
+
+from __future__ import annotations
+
+import shlex
+import sys
+from typing import TYPE_CHECKING
+
+import pytest
+from typer.testing import CliRunner
+
+from pipelex.cli.dev_cli.commands.drift.drift_cmd import drift_ack_cmd, drift_app, drift_check_cmd
+from pipelex.cli.dev_cli.commands.drift.exceptions import DriftAckError
+from pipelex.cli.dev_cli.commands.drift.git_adapter import read_staged_files
+from pipelex.cli.dev_cli.commands.drift.models import ack_file_path, load_all_acks
+
+if TYPE_CHECKING:
+ from rich.console import Console
+
+ from tests.unit.pipelex.cli.dev.conftest import GitRepo
+
+PYTHON = shlex.quote(sys.executable)
+PASSING_VERIFY = f"{PYTHON} -c 'print(1)'"
+FAILING_VERIFY = f"{PYTHON} -c 'import sys; print(\"boom output\"); sys.exit(3)'"
+
+
+def _manifest(*, verify_commands: list[str] | None = None) -> str:
+ commands = verify_commands or []
+ rendered_commands = ", ".join(f"'''{command}'''" for command in commands)
+ return f"""
+version = 1
+
+[contracts.demo-docs]
+description = "Demo docs must track demo source."
+triggers = ["src/**/*.py"]
+review = ["docs/demo.md"]
+verify_commands = [{rendered_commands}]
+"""
+
+
+def _seed_repo(git_repo: GitRepo, *, verify_commands: list[str] | None = None) -> None:
+ git_repo.write("src/demo.py", content="x = 1\n")
+ git_repo.write("docs/demo.md", content="# Demo\n")
+ git_repo.write("drift.toml", content=_manifest(verify_commands=verify_commands))
+ git_repo.add_all()
+ git_repo.commit("seed")
+
+
+class TestDriftAckCmd:
+ def test_ack_round_trip_then_check_green(self, git_repo: GitRepo, drift_console: Console) -> None:
+ """Stage → ack → check green, with a passing verify command in the loop."""
+ _seed_repo(git_repo, verify_commands=[PASSING_VERIFY])
+ drift_ack_cmd("demo-docs", rationale="Initial review, docs match.", repo_root=git_repo.root)
+ acks = load_all_acks(git_repo.root)
+ assert acks["demo-docs"].rationale == "Initial review, docs match."
+ assert acks["demo-docs"].reviewed_by == "Test User"
+ assert "src/demo.py" in acks["demo-docs"].trigger_files
+ drift_check_cmd(repo_root=git_repo.root)
+ assert "PASSED" in drift_console.export_text()
+
+ def test_ack_then_staged_edit_invalidates(self, git_repo: GitRepo) -> None:
+ _seed_repo(git_repo)
+ drift_ack_cmd("demo-docs", rationale="Initial review.", repo_root=git_repo.root)
+ git_repo.write("src/demo.py", content="x = 2\n")
+ git_repo.add("src/demo.py")
+ with pytest.raises(SystemExit):
+ drift_check_cmd(repo_root=git_repo.root)
+
+ def test_verify_failure_aborts_without_writing(self, git_repo: GitRepo, drift_console: Console) -> None:
+ _seed_repo(git_repo, verify_commands=[FAILING_VERIFY])
+ with pytest.raises(DriftAckError, match="exit 3"):
+ drift_ack_cmd("demo-docs", rationale="Should not be written.", repo_root=git_repo.root)
+ assert not ack_file_path(git_repo.root, contract_id="demo-docs").exists()
+ assert "boom output" in drift_console.export_text()
+
+ def test_verify_stops_at_first_failure(self, git_repo: GitRepo) -> None:
+ marker = git_repo.root / "second_ran.txt"
+ second_command = f'{PYTHON} -c \'open("second_ran.txt", "w").write("ran")\''
+ _seed_repo(git_repo, verify_commands=[FAILING_VERIFY, second_command])
+ with pytest.raises(DriftAckError):
+ drift_ack_cmd("demo-docs", rationale="nope", repo_root=git_repo.root)
+ assert not marker.exists()
+
+ def test_empty_rationale_rejected(self, git_repo: GitRepo) -> None:
+ _seed_repo(git_repo)
+ with pytest.raises(DriftAckError, match="rationale"):
+ drift_ack_cmd("demo-docs", rationale=" ", repo_root=git_repo.root)
+
+ def test_missing_rationale_option_rejected_by_cli(self, git_repo: GitRepo, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.chdir(git_repo.root)
+ _seed_repo(git_repo)
+ runner = CliRunner()
+ result = runner.invoke(drift_app, ["ack", "demo-docs"])
+ assert result.exit_code != 0
+
+ def test_reviewed_by_defaults_from_git_config(self, git_repo: GitRepo) -> None:
+ _seed_repo(git_repo)
+ drift_ack_cmd("demo-docs", rationale="Default reviewer.", repo_root=git_repo.root)
+ assert load_all_acks(git_repo.root)["demo-docs"].reviewed_by == "Test User"
+
+ def test_by_overrides_git_config(self, git_repo: GitRepo) -> None:
+ _seed_repo(git_repo)
+ drift_ack_cmd("demo-docs", rationale="Agent review.", reviewed_by_override="claude/session-42", repo_root=git_repo.root)
+ assert load_all_acks(git_repo.root)["demo-docs"].reviewed_by == "claude/session-42"
+
+ def test_unset_user_name_without_by_is_hard_error(self, git_repo: GitRepo, monkeypatch: pytest.MonkeyPatch) -> None:
+ _seed_repo(git_repo)
+ monkeypatch.setenv("GIT_CONFIG_GLOBAL", "/dev/null")
+ monkeypatch.setenv("GIT_CONFIG_SYSTEM", "/dev/null")
+ git_repo.git("config", "--unset", "user.name")
+ with pytest.raises(DriftAckError, match="--by"):
+ drift_ack_cmd("demo-docs", rationale="No identity.", repo_root=git_repo.root)
+ assert not ack_file_path(git_repo.root, contract_id="demo-docs").exists()
+
+ def test_unknown_contract_is_hard_error(self, git_repo: GitRepo) -> None:
+ _seed_repo(git_repo)
+ with pytest.raises(DriftAckError, match="no-such-contract"):
+ drift_ack_cmd("no-such-contract", rationale="nope", repo_root=git_repo.root)
+
+ def test_ack_permitted_with_dirty_tree_elsewhere(self, git_repo: GitRepo, drift_console: Console) -> None:
+ """A clean tree is not required — only the trigger files' staged state matters."""
+ _seed_repo(git_repo)
+ git_repo.write("docs/demo.md", content="# Demo edited, unstaged\n")
+ drift_ack_cmd("demo-docs", rationale="Dirty elsewhere is fine.", repo_root=git_repo.root)
+ drift_check_cmd(repo_root=git_repo.root)
+ assert "PASSED" in drift_console.export_text()
+
+ def test_unstaged_trigger_edit_warns_and_covers_staged_content(self, git_repo: GitRepo, drift_console: Console) -> None:
+ _seed_repo(git_repo)
+ staged_oid = read_staged_files(git_repo.root)["src/demo.py"]
+ git_repo.write("src/demo.py", content="x = 999 # unstaged\n")
+ drift_ack_cmd("demo-docs", rationale="Covers staged content only.", repo_root=git_repo.root)
+ output = drift_console.export_text()
+ assert "unstaged modifications" in output
+ assert load_all_acks(git_repo.root)["demo-docs"].trigger_files["src/demo.py"] == staged_oid
+
+ def test_untracked_trigger_file_warns(self, git_repo: GitRepo, drift_console: Console) -> None:
+ _seed_repo(git_repo)
+ git_repo.write("src/brand_new.py", content="new = True\n")
+ drift_ack_cmd("demo-docs", rationale="Untracked file present.", repo_root=git_repo.root)
+ output = drift_console.export_text()
+ assert "untracked file matches triggers" in output
+ assert "src/brand_new.py" not in load_all_acks(git_repo.root)["demo-docs"].trigger_files
diff --git a/tests/unit/pipelex/cli/dev/test_drift_check_cmd.py b/tests/unit/pipelex/cli/dev/test_drift_check_cmd.py
new file mode 100644
index 000000000..b71466285
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_drift_check_cmd.py
@@ -0,0 +1,206 @@
+"""Unit tests for `pipelex-dev drift check`: every failure class plus the all-green pass."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pipelex.cli.dev_cli.commands.drift.core import compute_current_digest
+from pipelex.cli.dev_cli.commands.drift.drift_cmd import drift_check_cmd
+from pipelex.cli.dev_cli.commands.drift.exceptions import DriftManifestError
+from pipelex.cli.dev_cli.commands.drift.git_adapter import read_staged_files
+from pipelex.cli.dev_cli.commands.drift.models import DriftAck, ack_file_path, load_manifest, save_ack
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from rich.console import Console
+
+ from tests.unit.pipelex.cli.dev.conftest import GitRepo
+
+MANIFEST = """
+version = 1
+
+[contracts.demo-docs]
+description = "Demo docs must track demo source."
+triggers = ["src/**/*.py"]
+review = ["docs/demo.md"]
+"""
+
+
+def _seed_repo(git_repo: GitRepo, *, manifest: str = MANIFEST) -> None:
+ git_repo.write("src/demo.py", content="x = 1\n")
+ git_repo.write("docs/demo.md", content="# Demo\n")
+ git_repo.write("drift.toml", content=manifest)
+ git_repo.add_all()
+ git_repo.commit("seed")
+
+
+def _ack_contract(repo_root: Path, *, contract_id: str) -> None:
+ """Record a valid ack for the current index state, bypassing the ack command."""
+ manifest = load_manifest(repo_root)
+ staged_oids = read_staged_files(repo_root)
+ result = compute_current_digest(manifest.contracts[contract_id], contract_id=contract_id, staged_oids=staged_oids)
+ ack = DriftAck(
+ contract=contract_id,
+ digest=result.digest,
+ reviewed_by="tester",
+ reviewed_at="2026-07-03T00:00:00Z",
+ rationale="test ack",
+ trigger_files=result.trigger_files,
+ )
+ save_ack(ack, repo_root=repo_root)
+
+
+class TestDriftCheckCmd:
+ def test_all_green_passes(self, git_repo: GitRepo, drift_console: Console) -> None:
+ _seed_repo(git_repo)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ drift_check_cmd(repo_root=git_repo.root)
+ assert "PASSED" in drift_console.export_text()
+
+ def test_missing_ack_fails_and_points_to_plan(self, git_repo: GitRepo, drift_console: Console) -> None:
+ _seed_repo(git_repo)
+ with pytest.raises(SystemExit) as exc_info:
+ drift_check_cmd(repo_root=git_repo.root)
+ assert exc_info.value.code == 1
+ output = drift_console.export_text()
+ assert "no ack recorded" in output
+ assert "run `make drift-plan`" in output
+
+ def test_staged_edit_after_ack_fails(self, git_repo: GitRepo, drift_console: Console) -> None:
+ _seed_repo(git_repo)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ git_repo.write("src/demo.py", content="x = 2\n")
+ git_repo.add("src/demo.py")
+ with pytest.raises(SystemExit):
+ drift_check_cmd(repo_root=git_repo.root)
+ output = drift_console.export_text()
+ assert "changed since last ack" in output
+ assert "run `make drift-plan`" in output
+
+ def test_unstaged_edit_after_ack_still_passes(self, git_repo: GitRepo, drift_console: Console) -> None:
+ """Index semantics: an edit that is not staged does not open the contract."""
+ _seed_repo(git_repo)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ git_repo.write("src/demo.py", content="x = 2\n")
+ drift_check_cmd(repo_root=git_repo.root)
+ assert "PASSED" in drift_console.export_text()
+
+ def test_dead_trigger_glob_fails_with_manifest_hint(self, git_repo: GitRepo, drift_console: Console) -> None:
+ manifest = """
+version = 1
+
+[contracts.demo-docs]
+description = "Demo docs must track demo source."
+triggers = ["nonexistent/**"]
+review = ["docs/demo.md"]
+"""
+ _seed_repo(git_repo, manifest=manifest)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ with pytest.raises(SystemExit):
+ drift_check_cmd(repo_root=git_repo.root)
+ output = drift_console.export_text()
+ assert "trigger pattern 'nonexistent/**' matches no tracked file" in output
+ assert "edit drift.toml first" in output
+
+ def test_zero_match_review_target_fails(self, git_repo: GitRepo, drift_console: Console) -> None:
+ """Rot symmetry: a review target matching no tracked file is as hard an error as a dead trigger."""
+ manifest = """
+version = 1
+
+[contracts.demo-docs]
+description = "Demo docs must track demo source."
+triggers = ["src/**/*.py"]
+review = ["docs/missing.md"]
+"""
+ _seed_repo(git_repo, manifest=manifest)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ with pytest.raises(SystemExit):
+ drift_check_cmd(repo_root=git_repo.root)
+ output = drift_console.export_text()
+ assert "review target 'docs/missing.md' matches no tracked file" in output
+
+ def test_orphan_ack_fails(self, git_repo: GitRepo, drift_console: Console) -> None:
+ _seed_repo(git_repo)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ orphan = DriftAck(
+ contract="removed-contract",
+ digest="sha256:dead",
+ reviewed_by="tester",
+ reviewed_at="2026-07-03T00:00:00Z",
+ rationale="orphan",
+ trigger_files={},
+ )
+ save_ack(orphan, repo_root=git_repo.root)
+ with pytest.raises(SystemExit):
+ drift_check_cmd(repo_root=git_repo.root)
+ assert "no matching contract" in drift_console.export_text()
+
+ def test_ack_contract_field_mismatch_fails(self, git_repo: GitRepo, drift_console: Console) -> None:
+ _seed_repo(git_repo)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ ack_path = ack_file_path(git_repo.root, contract_id="demo-docs")
+ ack_path.write_text(ack_path.read_text().replace('contract = "demo-docs"', 'contract = "other-name"'))
+ with pytest.raises(SystemExit):
+ drift_check_cmd(repo_root=git_repo.root)
+ assert "does not match its filename stem" in drift_console.export_text()
+
+ def test_orphan_ack_with_markup_metacharacters_reports_cleanly(self, git_repo: GitRepo, drift_console: Console) -> None:
+ """An orphan ack whose filename stem contains Rich markup must be reported, not crash the check."""
+ _seed_repo(git_repo)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ weird_ack = ack_file_path(git_repo.root, contract_id="[red]stray")
+ weird_ack.write_text(ack_file_path(git_repo.root, contract_id="demo-docs").read_text())
+ with pytest.raises(SystemExit):
+ drift_check_cmd(repo_root=git_repo.root)
+ assert "no matching contract" in drift_console.export_text()
+
+ def test_triggers_fully_shadowed_by_exclude_is_manifest_rot(self, git_repo: GitRepo, drift_console: Console) -> None:
+ """A contract whose excludes swallow every trigger match can never go stale — flag it as rot."""
+ manifest = """
+version = 1
+
+[contracts.demo-docs]
+description = "Demo docs must track demo source."
+triggers = ["src/**/*.py"]
+exclude = ["src/**"]
+review = ["docs/demo.md"]
+"""
+ _seed_repo(git_repo, manifest=manifest)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ with pytest.raises(SystemExit):
+ drift_check_cmd(repo_root=git_repo.root)
+ output = drift_console.export_text()
+ assert "fully excluded" in output
+ assert "edit drift.toml first" in output
+
+ def test_dead_trigger_does_not_double_report_empty_effective_set(self, git_repo: GitRepo, drift_console: Console) -> None:
+ """When the emptiness is caused by dead trigger globs, only the dead-pattern issue is reported."""
+ manifest = """
+version = 1
+
+[contracts.demo-docs]
+description = "Demo docs must track demo source."
+triggers = ["nonexistent/**"]
+review = ["docs/demo.md"]
+"""
+ _seed_repo(git_repo, manifest=manifest)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ with pytest.raises(SystemExit):
+ drift_check_cmd(repo_root=git_repo.root)
+ output = drift_console.export_text()
+ assert "matches no tracked file" in output
+ assert "fully excluded" not in output
+
+ def test_schema_invalid_manifest_is_hard_error(self, git_repo: GitRepo) -> None:
+ _seed_repo(git_repo, manifest="version = 1\n\n[contracts.demo-docs]\ntriggers = []\n")
+ with pytest.raises(DriftManifestError):
+ drift_check_cmd(repo_root=git_repo.root)
+
+ def test_quiet_success_is_single_line(self, git_repo: GitRepo, drift_console: Console) -> None:
+ _seed_repo(git_repo)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ drift_check_cmd(quiet=True, repo_root=git_repo.root)
+ assert "✓ Drift check: PASSED" in drift_console.export_text()
diff --git a/tests/unit/pipelex/cli/dev/test_drift_core_diff.py b/tests/unit/pipelex/cli/dev/test_drift_core_diff.py
new file mode 100644
index 000000000..e43a367bf
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_drift_core_diff.py
@@ -0,0 +1,46 @@
+"""Unit tests for the plan trigger-diff: stored ack map vs current index map."""
+
+from __future__ import annotations
+
+from pipelex.cli.dev_cli.commands.drift.core import diff_trigger_files
+
+
+class TestDriftCoreDiff:
+ def test_added_removed_modified(self) -> None:
+ stored = {
+ "a.py": "blob:aaa",
+ "b.py": "blob:bbb",
+ "c.py": "blob:ccc",
+ }
+ current = {
+ "b.py": "blob:bbb-changed",
+ "c.py": "blob:ccc",
+ "d.py": "blob:ddd",
+ }
+ diff = diff_trigger_files(stored=stored, current=current)
+ assert diff.added == ["d.py"]
+ assert diff.removed == ["a.py"]
+ assert diff.modified == ["b.py"]
+ assert not diff.is_empty
+
+ def test_identical_maps_yield_empty_diff(self) -> None:
+ stored = {"a.py": "blob:aaa", "b.py": "blob:bbb"}
+ diff = diff_trigger_files(stored=stored, current=dict(stored))
+ assert diff.added == []
+ assert diff.removed == []
+ assert diff.modified == []
+ assert diff.is_empty
+
+ def test_empty_stored_map_reports_everything_added(self) -> None:
+ """With no previous ack, every current trigger file is 'added' — the initial-review case."""
+ diff = diff_trigger_files(stored={}, current={"a.py": "blob:aaa", "b.py": "blob:bbb"})
+ assert diff.added == ["a.py", "b.py"]
+ assert diff.removed == []
+ assert diff.modified == []
+
+ def test_diff_lists_are_sorted(self) -> None:
+ stored = {"z.py": "blob:zzz", "m.py": "blob:mmm"}
+ current = {"a.py": "blob:aaa", "b.py": "blob:bbb"}
+ diff = diff_trigger_files(stored=stored, current=current)
+ assert diff.added == ["a.py", "b.py"]
+ assert diff.removed == ["m.py", "z.py"]
diff --git a/tests/unit/pipelex/cli/dev/test_drift_core_digest.py b/tests/unit/pipelex/cli/dev/test_drift_core_digest.py
new file mode 100644
index 000000000..e13478e37
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_drift_core_digest.py
@@ -0,0 +1,138 @@
+"""Unit tests for the drift contract digest: canonical, deterministic, definition-sensitive."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pipelex.cli.dev_cli.commands.drift.core import compute_contract_digest
+from pipelex.cli.dev_cli.commands.drift.models import DriftContract, load_manifest
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+TRIGGER_FILES = {
+ "pipelex/pipelex.toml": "blob:99ffee0000000000000000000000000000000000",
+ "pipelex/system/configuration/configs.py": "blob:a1b2c30000000000000000000000000000000000",
+}
+
+
+def _contract(**overrides: object) -> DriftContract:
+ fields: dict[str, object] = {
+ "description": "Config docs must track the config model.",
+ "triggers": ["pipelex/system/configuration/**/*.py", "pipelex/pipelex.toml"],
+ "exclude": [],
+ "review": ["docs/configuration/**/*.md"],
+ "verify_commands": ["make tb"],
+ }
+ fields.update(overrides)
+ return DriftContract.model_validate(fields)
+
+
+class TestDriftCoreDigest:
+ def test_digest_is_stable_across_runs(self) -> None:
+ """The same contract and trigger files always produce the same digest."""
+ digest_first = compute_contract_digest(_contract(), contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ digest_second = compute_contract_digest(_contract(), contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ assert digest_first == digest_second
+ assert digest_first.startswith("sha256:")
+
+ def test_glob_list_reorder_keeps_digest(self) -> None:
+ """Reordering trigger globs does not change the digest — matching is order-independent."""
+ reordered = _contract(triggers=["pipelex/pipelex.toml", "pipelex/system/configuration/**/*.py"])
+ digest_original = compute_contract_digest(_contract(), contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ digest_reordered = compute_contract_digest(reordered, contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ assert digest_original == digest_reordered
+
+ def test_defaulted_exclude_equals_explicit_empty(self) -> None:
+ """A contract with no `exclude` key digests identically to one with `exclude = []`."""
+ defaulted = DriftContract.model_validate(
+ {
+ "description": "Config docs must track the config model.",
+ "triggers": ["pipelex/system/configuration/**/*.py", "pipelex/pipelex.toml"],
+ "review": ["docs/configuration/**/*.md"],
+ "verify_commands": ["make tb"],
+ }
+ )
+ digest_defaulted = compute_contract_digest(defaulted, contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ digest_explicit = compute_contract_digest(_contract(), contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ assert digest_defaulted == digest_explicit
+
+ def test_definition_change_changes_digest(self) -> None:
+ """Editing the contract definition (description, review targets) forces a re-ack."""
+ digest_original = compute_contract_digest(_contract(), contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ digest_new_description = compute_contract_digest(_contract(description="Changed."), contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ digest_new_review = compute_contract_digest(
+ _contract(review=["docs/configuration/**/*.md", "docs/other.md"]), contract_id="config-docs", trigger_files=TRIGGER_FILES
+ )
+ assert digest_new_description != digest_original
+ assert digest_new_review != digest_original
+
+ def test_contract_id_is_part_of_the_digest(self) -> None:
+ digest_one = compute_contract_digest(_contract(), contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ digest_two = compute_contract_digest(_contract(), contract_id="renamed-docs", trigger_files=TRIGGER_FILES)
+ assert digest_one != digest_two
+
+ def test_verify_commands_order_is_part_of_the_definition(self) -> None:
+ """verify_commands run in order, so reordering them is a definition change."""
+ two_commands = _contract(verify_commands=["make tb", "make cko"])
+ reordered = _contract(verify_commands=["make cko", "make tb"])
+ digest_one = compute_contract_digest(two_commands, contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ digest_two = compute_contract_digest(reordered, contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ assert digest_one != digest_two
+
+ def test_trigger_file_content_change_changes_digest(self) -> None:
+ changed = dict(TRIGGER_FILES)
+ changed["pipelex/pipelex.toml"] = "blob:1234560000000000000000000000000000000000"
+ digest_original = compute_contract_digest(_contract(), contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ digest_changed = compute_contract_digest(_contract(), contract_id="config-docs", trigger_files=changed)
+ assert digest_original != digest_changed
+
+ def test_trigger_file_added_or_removed_changes_digest(self) -> None:
+ digest_original = compute_contract_digest(_contract(), contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ grown = dict(TRIGGER_FILES)
+ grown["pipelex/system/configuration/new.py"] = "blob:feedbeef00000000000000000000000000000000"
+ shrunk = {"pipelex/pipelex.toml": TRIGGER_FILES["pipelex/pipelex.toml"]}
+ assert compute_contract_digest(_contract(), contract_id="config-docs", trigger_files=grown) != digest_original
+ assert compute_contract_digest(_contract(), contract_id="config-docs", trigger_files=shrunk) != digest_original
+
+ def test_manifest_reformat_and_comments_keep_digest(self, tmp_path: Path) -> None:
+ """Reformatting drift.toml (whitespace, comments, glob order) must not change any digest."""
+ original = tmp_path / "original"
+ reformatted = tmp_path / "reformatted"
+ original.mkdir()
+ reformatted.mkdir()
+ (original / "drift.toml").write_text(
+ """
+version = 1
+
+[contracts.config-docs]
+description = "Config docs must track the config model."
+triggers = ["pipelex/system/configuration/**/*.py", "pipelex/pipelex.toml"]
+review = ["docs/configuration/**/*.md"]
+verify_commands = ["make tb"]
+"""
+ )
+ (reformatted / "drift.toml").write_text(
+ """
+# Drift contracts manifest — reformatted, same meaning.
+version = 1
+
+[contracts.config-docs]
+description = "Config docs must track the config model."
+# glob order swapped, exclude spelled out explicitly
+triggers = [
+ "pipelex/pipelex.toml",
+ "pipelex/system/configuration/**/*.py",
+]
+exclude = []
+review = ["docs/configuration/**/*.md"]
+verify_commands = ["make tb"]
+"""
+ )
+ manifest_original = load_manifest(original)
+ manifest_reformatted = load_manifest(reformatted)
+ digest_original = compute_contract_digest(manifest_original.contracts["config-docs"], contract_id="config-docs", trigger_files=TRIGGER_FILES)
+ digest_reformatted = compute_contract_digest(
+ manifest_reformatted.contracts["config-docs"], contract_id="config-docs", trigger_files=TRIGGER_FILES
+ )
+ assert digest_original == digest_reformatted
diff --git a/tests/unit/pipelex/cli/dev/test_drift_core_matching.py b/tests/unit/pipelex/cli/dev/test_drift_core_matching.py
new file mode 100644
index 000000000..69540981d
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_drift_core_matching.py
@@ -0,0 +1,101 @@
+"""Unit tests for the pure glob-matching helpers of the drift engine (no git, no I/O)."""
+
+from __future__ import annotations
+
+from pipelex.cli.dev_cli.commands.drift.core import find_dead_patterns, match_files, match_pattern
+
+TRACKED_FILES = [
+ "CLAUDE.md",
+ "docs/tools/cli/index.md",
+ "docs/tools/cli/agent.md",
+ "docs/configuration/config.md",
+ "pipelex/pipelex.toml",
+ "pipelex/cli/main.py",
+ "pipelex/cli/agent_cli/CLAUDE.md",
+ "pipelex/cli/dev_cli/commands/drift/core.py",
+ "pipelex/system/configuration/configs.py",
+ "pipelex/system/configuration/nested/deep.py",
+]
+
+
+class TestDriftCoreMatching:
+ def test_exact_path_match(self) -> None:
+ """A pattern without glob characters matches exactly one path."""
+ assert match_pattern("pipelex/pipelex.toml", pattern="pipelex/pipelex.toml")
+ assert not match_pattern("pipelex/pipelex2.toml", pattern="pipelex/pipelex.toml")
+
+ def test_directory_prefix_with_trailing_slash(self) -> None:
+ """A trailing-slash pattern matches every tracked file under the directory."""
+ assert match_pattern("docs/tools/cli/index.md", pattern="docs/tools/cli/")
+ assert match_pattern("docs/tools/cli/sub/page.md", pattern="docs/tools/cli/")
+ assert not match_pattern("docs/tools/climate/index.md", pattern="docs/tools/cli/")
+
+ def test_directory_prefix_without_trailing_slash(self) -> None:
+ """Trailing slashes are normalized: with or without, the same files match."""
+ assert match_pattern("docs/tools/cli/index.md", pattern="docs/tools/cli")
+ assert not match_pattern("docs/tools/climate/index.md", pattern="docs/tools/cli")
+
+ def test_single_star_does_not_cross_slash(self) -> None:
+ """`*` matches within one path segment only."""
+ assert match_pattern("pipelex/main.py", pattern="pipelex/*.py")
+ assert not match_pattern("pipelex/cli/main.py", pattern="pipelex/*.py")
+
+ def test_double_star_matches_zero_or_more_directories(self) -> None:
+ """`**/` spans any number of directories, including none."""
+ pattern = "pipelex/system/configuration/**/*.py"
+ assert match_pattern("pipelex/system/configuration/configs.py", pattern=pattern)
+ assert match_pattern("pipelex/system/configuration/nested/deep.py", pattern=pattern)
+ assert not match_pattern("pipelex/system/other/configs.py", pattern=pattern)
+
+ def test_trailing_double_star_matches_everything_under(self) -> None:
+ """`dir/**` matches every file under dir, and nothing in sibling directories."""
+ pattern = "pipelex/cli/dev_cli/**"
+ assert match_pattern("pipelex/cli/dev_cli/commands/drift/core.py", pattern=pattern)
+ assert not match_pattern("pipelex/cli/dev_cli2/foo.py", pattern=pattern)
+ assert not match_pattern("pipelex/cli/main.py", pattern=pattern)
+
+ def test_leading_double_star_matches_at_any_depth(self) -> None:
+ """`**/NAME` matches the name at the repo root and at any depth."""
+ assert match_pattern("CLAUDE.md", pattern="**/CLAUDE.md")
+ assert match_pattern("pipelex/cli/agent_cli/CLAUDE.md", pattern="**/CLAUDE.md")
+ assert not match_pattern("docs/tools/cli/index.md", pattern="**/CLAUDE.md")
+
+ def test_question_mark_matches_single_non_slash_character(self) -> None:
+ """`?` matches exactly one character within a segment."""
+ assert match_pattern("docs/a.md", pattern="docs/?.md")
+ assert not match_pattern("docs/ab.md", pattern="docs/?.md")
+ assert not match_pattern("docs/a/b.md", pattern="docs/?.md")
+
+ def test_matching_is_case_sensitive(self) -> None:
+ """Matching is case-sensitive per POSIX."""
+ assert not match_pattern("docs/tools/cli/index.md", pattern="Docs/**")
+ assert not match_pattern("pipelex/pipelex.toml", pattern="PIPELEX/pipelex.toml")
+
+ def test_match_files_applies_exclude_and_sorts(self) -> None:
+ """match_files unions the trigger patterns, subtracts excludes, and returns sorted paths."""
+ matched = match_files(
+ TRACKED_FILES,
+ patterns=["pipelex/cli/**/*.py"],
+ exclude=["pipelex/cli/dev_cli/**"],
+ )
+ assert matched == ["pipelex/cli/main.py"]
+
+ def test_match_files_multiple_patterns(self) -> None:
+ matched = match_files(
+ TRACKED_FILES,
+ patterns=["pipelex/system/configuration/**/*.py", "pipelex/pipelex.toml"],
+ )
+ assert matched == [
+ "pipelex/pipelex.toml",
+ "pipelex/system/configuration/configs.py",
+ "pipelex/system/configuration/nested/deep.py",
+ ]
+
+ def test_find_dead_patterns_reports_zero_match_patterns(self) -> None:
+ """Patterns that match no tracked file are reported, in manifest order."""
+ dead = find_dead_patterns(TRACKED_FILES, patterns=["nonexistent/**", "pipelex/pipelex.toml", "docs/missing.md"])
+ assert dead == ["nonexistent/**", "docs/missing.md"]
+
+ def test_find_dead_patterns_all_alive(self) -> None:
+ dead = find_dead_patterns(TRACKED_FILES, patterns=["docs/tools/cli/", "**/CLAUDE.md"])
+ assert dead == []
diff --git a/tests/unit/pipelex/cli/dev/test_drift_git_adapter.py b/tests/unit/pipelex/cli/dev/test_drift_git_adapter.py
new file mode 100644
index 000000000..4ff0e0481
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_drift_git_adapter.py
@@ -0,0 +1,109 @@
+"""Unit tests for the drift git adapter: index reads, OID semantics, failure paths."""
+
+from __future__ import annotations
+
+import subprocess # noqa: S404
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pipelex.cli.dev_cli.commands.drift.exceptions import DriftGitError
+from pipelex.cli.dev_cli.commands.drift.git_adapter import (
+ get_git_user_name,
+ get_repo_toplevel,
+ read_staged_files,
+ read_unstaged_modified,
+ read_untracked,
+)
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+ from tests.unit.pipelex.cli.dev.conftest import GitRepo
+
+ADAPTER_MODULE = "pipelex.cli.dev_cli.commands.drift.git_adapter"
+
+
+class TestDriftGitAdapter:
+ def test_read_staged_files_maps_paths_to_blob_oids(self, git_repo: GitRepo) -> None:
+ git_repo.write_and_commit("docs/page.md", content="# Page\n")
+ git_repo.write("pipelex/mod.py", content="x = 1\n")
+ git_repo.add("pipelex/mod.py")
+ staged = read_staged_files(git_repo.root)
+ assert set(staged) == {"docs/page.md", "pipelex/mod.py"}
+ for oid in staged.values():
+ assert oid.startswith("blob:")
+ assert len(oid) == len("blob:") + 40
+
+ def test_staged_edit_changes_oid_unstaged_does_not(self, git_repo: GitRepo) -> None:
+ """Digest source is the index: a staged edit is reflected, an unstaged edit is NOT."""
+ git_repo.write_and_commit("pipelex/mod.py", content="x = 1\n")
+ oid_initial = read_staged_files(git_repo.root)["pipelex/mod.py"]
+
+ git_repo.write("pipelex/mod.py", content="x = 2\n")
+ oid_after_unstaged_edit = read_staged_files(git_repo.root)["pipelex/mod.py"]
+ assert oid_after_unstaged_edit == oid_initial
+
+ git_repo.add("pipelex/mod.py")
+ oid_after_staging = read_staged_files(git_repo.root)["pipelex/mod.py"]
+ assert oid_after_staging != oid_initial
+
+ def test_untracked_files_are_absent_from_index(self, git_repo: GitRepo) -> None:
+ git_repo.write_and_commit("tracked.md", content="tracked\n")
+ git_repo.write("untracked.md", content="untracked\n")
+ staged = read_staged_files(git_repo.root)
+ assert "untracked.md" not in staged
+ assert read_untracked(git_repo.root) == ["untracked.md"]
+
+ def test_read_unstaged_modified(self, git_repo: GitRepo) -> None:
+ git_repo.write_and_commit("a.md", content="one\n")
+ git_repo.write_and_commit("b.md", content="two\n")
+ git_repo.write("a.md", content="one-edited\n")
+ assert read_unstaged_modified(git_repo.root) == ["a.md"]
+
+ def test_get_repo_toplevel(self, git_repo: GitRepo) -> None:
+ git_repo.write_and_commit("a.md", content="one\n")
+ nested = git_repo.root / "docs"
+ nested.mkdir(exist_ok=True)
+ assert get_repo_toplevel(cwd=nested).resolve() == git_repo.root.resolve()
+
+ def test_not_a_git_repo_is_actionable_error(self, tmp_path: Path) -> None:
+ plain_dir = tmp_path / "plain"
+ plain_dir.mkdir()
+ with pytest.raises(DriftGitError, match="git"):
+ read_staged_files(plain_dir)
+
+ def test_missing_git_binary_is_actionable_error(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ mocker.patch(f"{ADAPTER_MODULE}.subprocess.run", side_effect=FileNotFoundError("git"))
+ with pytest.raises(DriftGitError, match="not found"):
+ read_staged_files(tmp_path)
+
+ def test_git_timeout_is_actionable_error(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ mocker.patch(f"{ADAPTER_MODULE}.subprocess.run", side_effect=subprocess.TimeoutExpired(cmd="git", timeout=30))
+ with pytest.raises(DriftGitError, match="timed out"):
+ read_staged_files(tmp_path)
+
+ def test_malformed_ls_files_output_is_error(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ completed = subprocess.CompletedProcess(args=["git"], returncode=0, stdout="no-tab-entry\0", stderr="")
+ mocker.patch(f"{ADAPTER_MODULE}.subprocess.run", return_value=completed)
+ with pytest.raises(DriftGitError, match=r"[Mm]alformed"):
+ read_staged_files(tmp_path)
+
+ def test_unmerged_index_entry_is_actionable_error(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ stdout = "100644 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1\tconflicted.py\0"
+ completed = subprocess.CompletedProcess(args=["git"], returncode=0, stdout=stdout, stderr="")
+ mocker.patch(f"{ADAPTER_MODULE}.subprocess.run", return_value=completed)
+ with pytest.raises(DriftGitError, match=r"[Uu]nmerged"):
+ read_staged_files(tmp_path)
+
+ def test_get_git_user_name_configured(self, git_repo: GitRepo) -> None:
+ assert get_git_user_name(git_repo.root) == "Test User"
+
+ def test_get_git_user_name_unset_returns_none(self, git_repo: GitRepo, monkeypatch: pytest.MonkeyPatch) -> None:
+ """With local user.name unset and host global/system config masked, the name resolves to None."""
+ monkeypatch.setenv("GIT_CONFIG_GLOBAL", "/dev/null")
+ monkeypatch.setenv("GIT_CONFIG_SYSTEM", "/dev/null")
+ git_repo.git("config", "--unset", "user.name")
+ assert get_git_user_name(git_repo.root) is None
diff --git a/tests/unit/pipelex/cli/dev/test_drift_models.py b/tests/unit/pipelex/cli/dev/test_drift_models.py
new file mode 100644
index 000000000..3686e8f9a
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_drift_models.py
@@ -0,0 +1,168 @@
+"""Unit tests for the drift manifest and ack models: parsing, validation, atomic ack I/O."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pipelex.cli.dev_cli.commands.drift.exceptions import DriftAckError, DriftManifestError
+from pipelex.cli.dev_cli.commands.drift.models import (
+ DriftAck,
+ ack_file_path,
+ load_all_acks,
+ load_manifest,
+ save_ack,
+)
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+VALID_MANIFEST = """
+version = 1
+
+[contracts.config-docs]
+description = "Config docs must track the config model."
+triggers = ["pipelex/system/configuration/**/*.py", "pipelex/pipelex.toml"]
+review = ["docs/configuration/**/*.md"]
+verify_commands = ["make tb"]
+
+[contracts.cli-docs]
+description = "CLI docs must track the CLI surface."
+triggers = ["pipelex/cli/**/*.py"]
+exclude = ["pipelex/cli/dev_cli/**"]
+review = ["docs/tools/cli/", "pipelex/cli/agent_cli/CLAUDE.md"]
+"""
+
+
+def _write_manifest(repo_root: Path, *, content: str) -> None:
+ (repo_root / "drift.toml").write_text(content)
+
+
+def _sample_ack(contract_id: str = "config-docs") -> DriftAck:
+ return DriftAck(
+ contract=contract_id,
+ digest="sha256:4e03f2a1",
+ reviewed_by="louis",
+ reviewed_at="2026-07-03T14:12:09Z",
+ rationale="Initial review.",
+ trigger_files={"pipelex/pipelex.toml": "blob:99ffee"},
+ )
+
+
+class TestDriftModels:
+ def test_load_manifest_happy_path(self, tmp_path: Path) -> None:
+ _write_manifest(tmp_path, content=VALID_MANIFEST)
+ manifest = load_manifest(tmp_path)
+ assert manifest.version == 1
+ assert set(manifest.contracts) == {"config-docs", "cli-docs"}
+ config_docs = manifest.contracts["config-docs"]
+ assert config_docs.description == "Config docs must track the config model."
+ assert config_docs.exclude == []
+ assert config_docs.verify_commands == ["make tb"]
+ cli_docs = manifest.contracts["cli-docs"]
+ assert cli_docs.exclude == ["pipelex/cli/dev_cli/**"]
+ assert cli_docs.verify_commands == []
+
+ def test_load_manifest_missing_file(self, tmp_path: Path) -> None:
+ with pytest.raises(DriftManifestError, match=r"drift\.toml"):
+ load_manifest(tmp_path)
+
+ def test_load_manifest_malformed_toml(self, tmp_path: Path) -> None:
+ _write_manifest(tmp_path, content="version = [unclosed")
+ with pytest.raises(DriftManifestError):
+ load_manifest(tmp_path)
+
+ def test_load_manifest_invalid_contract_id_charset(self, tmp_path: Path) -> None:
+ """Contract ids become filenames and TOML keys — restrict them to [a-z0-9-]+."""
+ _write_manifest(
+ tmp_path,
+ content="""
+version = 1
+
+[contracts."Bad_ID"]
+description = "Nope."
+triggers = ["a.py"]
+review = ["docs/a.md"]
+""",
+ )
+ with pytest.raises(DriftManifestError, match="Bad_ID"):
+ load_manifest(tmp_path)
+
+ def test_load_manifest_unknown_field_rejected(self, tmp_path: Path) -> None:
+ _write_manifest(
+ tmp_path,
+ content="""
+version = 1
+
+[contracts.config-docs]
+description = "Config docs."
+triggers = ["a.py"]
+review = ["docs/a.md"]
+unknown_field = "typo"
+""",
+ )
+ with pytest.raises(DriftManifestError, match="unknown_field"):
+ load_manifest(tmp_path)
+
+ def test_load_manifest_missing_required_field(self, tmp_path: Path) -> None:
+ _write_manifest(
+ tmp_path,
+ content="""
+version = 1
+
+[contracts.config-docs]
+triggers = ["a.py"]
+review = ["docs/a.md"]
+""",
+ )
+ with pytest.raises(DriftManifestError, match="description"):
+ load_manifest(tmp_path)
+
+ def test_load_manifest_empty_triggers_rejected(self, tmp_path: Path) -> None:
+ _write_manifest(
+ tmp_path,
+ content="""
+version = 1
+
+[contracts.config-docs]
+description = "Config docs."
+triggers = []
+review = ["docs/a.md"]
+""",
+ )
+ with pytest.raises(DriftManifestError):
+ load_manifest(tmp_path)
+
+ def test_ack_round_trip(self, tmp_path: Path) -> None:
+ ack = _sample_ack()
+ save_ack(ack, repo_root=tmp_path)
+ ack_path = ack_file_path(tmp_path, contract_id="config-docs")
+ assert ack_path == tmp_path / ".drift" / "acks" / "config-docs.toml"
+ assert ack_path.is_file()
+ loaded = load_all_acks(tmp_path)
+ assert loaded == {"config-docs": ack}
+
+ def test_save_ack_leaves_no_temp_file(self, tmp_path: Path) -> None:
+ """The atomic write must not leave a temp file behind in .drift/acks/."""
+ save_ack(_sample_ack(), repo_root=tmp_path)
+ leftovers = [path.name for path in (tmp_path / ".drift" / "acks").iterdir() if path.suffix != ".toml"]
+ assert leftovers == []
+
+ def test_save_ack_overwrites_existing(self, tmp_path: Path) -> None:
+ save_ack(_sample_ack(), repo_root=tmp_path)
+ updated = _sample_ack().model_copy(update={"rationale": "Second review.", "digest": "sha256:deadbeef"})
+ save_ack(updated, repo_root=tmp_path)
+ loaded = load_all_acks(tmp_path)
+ assert loaded["config-docs"].rationale == "Second review."
+ assert loaded["config-docs"].digest == "sha256:deadbeef"
+
+ def test_load_all_acks_empty_when_no_dir(self, tmp_path: Path) -> None:
+ assert load_all_acks(tmp_path) == {}
+
+ def test_load_all_acks_corrupt_ack_is_hard_error(self, tmp_path: Path) -> None:
+ acks_dir = tmp_path / ".drift" / "acks"
+ acks_dir.mkdir(parents=True)
+ (acks_dir / "config-docs.toml").write_text("contract = [broken")
+ with pytest.raises(DriftAckError, match="config-docs"):
+ load_all_acks(tmp_path)
diff --git a/tests/unit/pipelex/cli/dev/test_drift_plan_cmd.py b/tests/unit/pipelex/cli/dev/test_drift_plan_cmd.py
new file mode 100644
index 000000000..8d1439cd6
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_drift_plan_cmd.py
@@ -0,0 +1,122 @@
+"""Unit tests for `pipelex-dev drift plan`: packet content, diff reporting, exact ack invocation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pipelex.cli.dev_cli.commands.drift.core import compute_current_digest
+from pipelex.cli.dev_cli.commands.drift.drift_cmd import drift_plan_cmd
+from pipelex.cli.dev_cli.commands.drift.exceptions import DriftError
+from pipelex.cli.dev_cli.commands.drift.git_adapter import read_staged_files
+from pipelex.cli.dev_cli.commands.drift.models import DriftAck, load_manifest, save_ack
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from tests.unit.pipelex.cli.dev.conftest import GitRepo
+
+MANIFEST = """
+version = 1
+
+[contracts.demo-docs]
+description = "Demo docs must track demo source."
+triggers = ["src/**/*.py"]
+review = ["docs/demo.md"]
+verify_commands = ["make tb"]
+
+[contracts.other-docs]
+description = "Other docs must track other source."
+triggers = ["other/**/*.py"]
+review = ["docs/other.md"]
+"""
+
+
+def _seed_repo(git_repo: GitRepo) -> None:
+ git_repo.write("src/demo.py", content="x = 1\n")
+ git_repo.write("docs/demo.md", content="# Demo\n")
+ git_repo.write("other/mod.py", content="y = 1\n")
+ git_repo.write("docs/other.md", content="# Other\n")
+ git_repo.write("drift.toml", content=MANIFEST)
+ git_repo.add_all()
+ git_repo.commit("seed")
+
+
+def _ack_contract(repo_root: Path, *, contract_id: str, rationale: str = "test ack") -> None:
+ manifest = load_manifest(repo_root)
+ staged_oids = read_staged_files(repo_root)
+ result = compute_current_digest(manifest.contracts[contract_id], contract_id=contract_id, staged_oids=staged_oids)
+ ack = DriftAck(
+ contract=contract_id,
+ digest=result.digest,
+ reviewed_by="tester",
+ reviewed_at="2026-07-03T14:12:09Z",
+ rationale=rationale,
+ trigger_files=result.trigger_files,
+ )
+ save_ack(ack, repo_root=repo_root)
+
+
+class TestDriftPlanCmd:
+ def test_initial_review_lists_all_trigger_files_as_added(self, git_repo: GitRepo, capfd: pytest.CaptureFixture[str]) -> None:
+ _seed_repo(git_repo)
+ drift_plan_cmd(repo_root=git_repo.root)
+ output = capfd.readouterr().out
+ assert "## Open contract: demo-docs" in output
+ assert "no previous ack — initial review required" in output
+ assert "- added: src/demo.py" in output
+ assert "- docs/demo.md" in output
+
+ def test_ack_invocation_is_exact_and_copy_pasteable(self, git_repo: GitRepo, capfd: pytest.CaptureFixture[str]) -> None:
+ """Agents run the emitted make command verbatim — its shape is part of the contract."""
+ _seed_repo(git_repo)
+ drift_plan_cmd(repo_root=git_repo.root)
+ output = capfd.readouterr().out
+ assert 'make drift-ack CONTRACT=demo-docs RATIONALE="…"' in output
+ assert 'make drift-ack CONTRACT=other-docs RATIONALE="…"' in output
+
+ def test_modified_trigger_and_previous_rationale_are_reported(self, git_repo: GitRepo, capfd: pytest.CaptureFixture[str]) -> None:
+ _seed_repo(git_repo)
+ _ack_contract(git_repo.root, contract_id="demo-docs", rationale="Reviewed the demo docs.")
+ git_repo.write("src/demo.py", content="x = 2\n")
+ git_repo.write("src/new_mod.py", content="z = 1\n")
+ git_repo.add_all()
+ drift_plan_cmd("demo-docs", repo_root=git_repo.root)
+ output = capfd.readouterr().out
+ assert "- modified: src/demo.py" in output
+ assert "- added: src/new_mod.py" in output
+ assert '(by tester, 2026-07-03, "Reviewed the demo docs.")' in output
+
+ def test_fulfilled_contracts_are_excluded(self, git_repo: GitRepo, capfd: pytest.CaptureFixture[str]) -> None:
+ _seed_repo(git_repo)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ drift_plan_cmd(repo_root=git_repo.root)
+ output = capfd.readouterr().out
+ assert "## Open contract: demo-docs" not in output
+ assert "## Open contract: other-docs" in output
+
+ def test_all_fulfilled_prints_nothing_to_review(self, git_repo: GitRepo, capfd: pytest.CaptureFixture[str]) -> None:
+ _seed_repo(git_repo)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ _ack_contract(git_repo.root, contract_id="other-docs")
+ drift_plan_cmd(repo_root=git_repo.root)
+ assert "All drift contracts are fulfilled" in capfd.readouterr().out
+
+ def test_single_fulfilled_contract_argument(self, git_repo: GitRepo, capfd: pytest.CaptureFixture[str]) -> None:
+ _seed_repo(git_repo)
+ _ack_contract(git_repo.root, contract_id="demo-docs")
+ drift_plan_cmd("demo-docs", repo_root=git_repo.root)
+ assert "Contract 'demo-docs' is fulfilled" in capfd.readouterr().out
+
+ def test_unknown_contract_argument_is_hard_error(self, git_repo: GitRepo) -> None:
+ _seed_repo(git_repo)
+ with pytest.raises(DriftError, match="no-such-contract"):
+ drift_plan_cmd("no-such-contract", repo_root=git_repo.root)
+
+ def test_verify_commands_are_listed(self, git_repo: GitRepo, capfd: pytest.CaptureFixture[str]) -> None:
+ _seed_repo(git_repo)
+ drift_plan_cmd("demo-docs", repo_root=git_repo.root)
+ output = capfd.readouterr().out
+ assert "**Verify commands (run by ack):**" in output
+ assert "- make tb" in output
diff --git a/tests/unit/pipelex/cli/dev/test_keyword_only_guard_fix.py b/tests/unit/pipelex/cli/dev/test_keyword_only_guard_fix.py
index 7fc5c37e4..5cffa58e1 100644
--- a/tests/unit/pipelex/cli/dev/test_keyword_only_guard_fix.py
+++ b/tests/unit/pipelex/cli/dev/test_keyword_only_guard_fix.py
@@ -6,7 +6,9 @@ import textwrap
from typing import TYPE_CHECKING
from pipelex.cli.dev_cli.commands.keyword_only_guard import (
+ SubjectGrant,
Violation,
+ ViolationKind,
find_violations_in_source,
fix_all_violations,
fix_source,
@@ -17,19 +19,31 @@ if TYPE_CHECKING:
def _fix(
- source: str, *, module_qname: str = "pipelex.sample.module", relative_path: str = "pipelex/sample/module.py"
+ source: str,
+ *,
+ module_qname: str = "pipelex.sample.module",
+ relative_path: str = "pipelex/sample/module.py",
+ grants: dict[str, SubjectGrant] | None = None,
) -> tuple[str, list[Violation], list[Violation]]:
"""Run the auto-fixer over an inline snippet, returning (new_source, fixed, unfixable)."""
- return fix_source(textwrap.dedent(source), module_qname=module_qname, relative_path=relative_path)
+ return fix_source(textwrap.dedent(source), module_qname=module_qname, relative_path=relative_path, grants=grants or {})
+
+
+def _grant(key: str, *, param: str) -> dict[str, SubjectGrant]:
+ """A one-entry grants mapping for an inline snippet."""
+ return {key: SubjectGrant(param=param, rationale="test grant")}
def _names(violations: list[Violation]) -> list[str]:
return [violation.qualified_name for violation in violations]
-def _is_compliant(source: str) -> bool:
+def _is_compliant(source: str, *, grants: dict[str, SubjectGrant] | None = None) -> bool:
"""Whether a (rewritten) source has no remaining violations."""
- return find_violations_in_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py") == []
+ violations = find_violations_in_source(
+ source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants=grants or {}
+ )
+ return violations == []
class TestKeywordOnlyGuardFix:
@@ -132,28 +146,93 @@ class TestKeywordOnlyGuardFix:
assert "def h(*, x, y, z):" in new_source
assert _is_compliant(new_source)
- def test_compliant_source_unchanged(self) -> None:
+ def test_compliant_source_with_grant_unchanged(self) -> None:
+ grants = _grant("pipelex/sample/module.py::g", param="subject")
source = textwrap.dedent(
"""
def g(subject, *, opt):
return opt
"""
)
- new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ new_source, fixed, unfixable = fix_source(
+ source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants=grants
+ )
assert (fixed, unfixable) == ([], [])
assert new_source == source
- def test_lone_subject_unchanged(self) -> None:
+ def test_granted_lone_subject_unchanged(self) -> None:
+ grants = _grant("pipelex/sample/module.py::render", param="node")
source = textwrap.dedent(
"""
def render(node):
return node
"""
)
- new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ new_source, fixed, unfixable = fix_source(
+ source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants=grants
+ )
assert (fixed, unfixable) == ([], [])
assert new_source == source
+ def test_ungranted_lone_subject_fixed_to_all_keyword(self) -> None:
+ """The fixer's reach covers the new violation kind: an ungranted subject is mechanically keyword-only'd."""
+ new_source, fixed, unfixable = _fix(
+ """
+ def render(node):
+ return node
+ """
+ )
+ assert _names(fixed) == ["render"]
+ assert fixed[0].kind is ViolationKind.UNGRANTED_SUBJECT
+ assert unfixable == []
+ assert "def render(*, node):" in new_source
+ assert _is_compliant(new_source)
+
+ def test_ungranted_literal_subject_fixed_to_all_keyword(self) -> None:
+ """A banned literal-typed subject is mechanically fixable too (call sites are pyright's job)."""
+ new_source, fixed, unfixable = _fix(
+ """
+ def do_doctor_cmd(fix: bool):
+ return fix
+ """
+ )
+ assert _names(fixed) == ["do_doctor_cmd"]
+ assert fixed[0].kind is ViolationKind.LITERAL_SUBJECT
+ assert unfixable == []
+ assert "def do_doctor_cmd(*, fix: bool):" in new_source
+ assert _is_compliant(new_source)
+
+ def test_ungranted_subject_with_keyword_only_section_needs_manual_fix(self) -> None:
+ """An ungranted subject ahead of an existing `*` can't take a second bare `*` — reported for a manual fix."""
+ source = textwrap.dedent(
+ """
+ def g(subject, *, opt):
+ return opt
+ """
+ )
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants={})
+ assert fixed == []
+ assert _names(unfixable) == ["g"]
+ assert unfixable[0].kind is ViolationKind.UNGRANTED_SUBJECT
+ assert new_source == source
+
+ def test_grant_param_mismatch_never_rewritten(self) -> None:
+ """A stale grant is a registry decision, not a signature to silently rewrite — reported unfixable."""
+ grants = _grant("pipelex/sample/module.py::render", param="node")
+ source = textwrap.dedent(
+ """
+ def render(new_name):
+ return new_name
+ """
+ )
+ new_source, fixed, unfixable = fix_source(
+ source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants=grants
+ )
+ assert fixed == []
+ assert _names(unfixable) == ["render"]
+ assert unfixable[0].kind is ViolationKind.GRANT_PARAM_MISMATCH
+ assert new_source == source
+
def test_varargs_reported_unfixable_and_unchanged(self) -> None:
"""A `*args` signature cannot take a bare `*` — reported for a manual fix, source untouched."""
source = textwrap.dedent(
@@ -162,7 +241,7 @@ class TestKeywordOnlyGuardFix:
return a
"""
)
- new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants={})
assert fixed == []
assert _names(unfixable) == ["f"]
assert new_source == source
@@ -175,13 +254,17 @@ class TestKeywordOnlyGuardFix:
return a
"""
)
- new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants={})
assert fixed == []
assert _names(unfixable) == ["f"]
assert new_source == source
def test_positional_only_subject_fixed_after_slash(self) -> None:
- """A single positional-only subject (before `/`) stays positional; the `*` goes right after the `/`."""
+ """A single positional-only subject (before `/`) stays positional; the `*` goes right after the `/`.
+
+ The `/` means the subject cannot be keyword-only'd by the fixer, so the rewritten def still needs
+ a grant (or the `/` removed by hand) — the re-check flags exactly that residue.
+ """
new_source, fixed, unfixable = _fix(
"""
def f(a, /, b, c):
@@ -191,7 +274,8 @@ class TestKeywordOnlyGuardFix:
assert _names(fixed) == ["f"]
assert unfixable == []
assert "def f(a, /, *, b, c):" in new_source
- assert _is_compliant(new_source)
+ assert not _is_compliant(new_source) # the positional-only subject is still ungranted
+ assert _is_compliant(new_source, grants=_grant("pipelex/sample/module.py::f", param="a"))
def test_multiple_positional_only_reported_unfixable(self) -> None:
"""Two+ positional-only params can't be made keyword-only by a bare `*` (it can't precede `/`) — manual fix."""
@@ -201,7 +285,7 @@ class TestKeywordOnlyGuardFix:
return a
"""
)
- new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants={})
assert fixed == []
assert _names(unfixable) == ["f"]
assert new_source == source
@@ -226,7 +310,7 @@ class TestKeywordOnlyGuardFix:
...
"""
)
- new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants={})
assert (fixed, unfixable) == ([], [])
assert new_source == source
@@ -240,7 +324,7 @@ class TestKeywordOnlyGuardFix:
"""
suppressed = "def suppressed(spec, dry_run): # kw-only: ignore"
source = f'BANNER = "page1\x0cpage2"\n{suppressed}\n return spec\n\ndef real(alpha, beta):\n return alpha\n'
- new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants={})
assert _names(fixed) == ["real"]
assert unfixable == []
assert suppressed in new_source # the escape-hatched def is untouched
@@ -257,7 +341,9 @@ class TestKeywordOnlyGuardFix:
)
assert _names(fixed) == ["f"]
assert unfixable == []
- twice, fixed_again, unfixable_again = fix_source(once, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ twice, fixed_again, unfixable_again = fix_source(
+ once, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants={}
+ )
assert (fixed_again, unfixable_again) == ([], [])
assert twice == once
@@ -272,7 +358,7 @@ class TestKeywordOnlyGuardFix:
"""
literal = '"""\naaaa\x0cbbbb\nxxxxxxxxxxxxxxxxxxxx"""'
source = f"page = {literal}\ndef f(a, b):\n return a\n"
- new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants={})
assert _names(fixed) == ["f"]
assert unfixable == []
assert "def f(*, a, b):" in new_source
@@ -288,7 +374,7 @@ class TestKeywordOnlyGuardFix:
touches — most dangerously by emitting bare ``\n`` where the source had ``\r\n``.
"""
source = "X = 1\r\ndef f(a, b):\r\n return a\r\n"
- new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py", grants={})
assert _names(fixed) == ["f"]
assert unfixable == []
# The `*` lands on the def line and every CRLF separator is preserved byte-for-byte.
@@ -303,11 +389,11 @@ class TestKeywordOnlyGuardFix:
sample.mkdir(parents=True)
bad = sample / "bad.py"
good = sample / "good.py"
- good_text = "def g(subject, *, opt):\n return opt\n"
+ good_text = "def g(*, subject, opt):\n return opt\n"
bad.write_text("def f(a, b):\n return a\n", encoding="utf-8")
good.write_text(good_text, encoding="utf-8")
- fixed, unfixable = fix_all_violations(tmp_path / "pipelex")
+ fixed, unfixable = fix_all_violations(tmp_path / "pipelex", grants={})
assert _names(fixed) == ["f"]
assert unfixable == []
diff --git a/tests/unit/pipelex/cli/dev/test_keyword_only_guard_single_file.py b/tests/unit/pipelex/cli/dev/test_keyword_only_guard_single_file.py
index 76e1eeec9..7ef17b8dc 100644
--- a/tests/unit/pipelex/cli/dev/test_keyword_only_guard_single_file.py
+++ b/tests/unit/pipelex/cli/dev/test_keyword_only_guard_single_file.py
@@ -9,20 +9,27 @@ import pytest
from pipelex.cli.dev_cli.commands.keyword_only_guard import (
collect_all_violations,
collect_violations_for_files,
+ load_subject_grants,
main,
relative_source_path,
)
_BAD_SOURCE = "def f(a, b):\n return a\n"
-_GOOD_SOURCE = "def g(subject, *, opt):\n return opt\n"
+_GOOD_SOURCE = "def g(*, subject, opt):\n return opt\n"
+_GRANTED_SOURCE = "def render(node):\n return node\n"
def _make_tree(root: Path) -> None:
- """Create a minimal pipelex source tree with one violating and one compliant module."""
+ """Create a minimal repo tree: violating, compliant, and granted modules, plus the registry."""
sample = root / "pipelex" / "sample"
sample.mkdir(parents=True)
(sample / "bad.py").write_text(_BAD_SOURCE, encoding="utf-8")
(sample / "good.py").write_text(_GOOD_SOURCE, encoding="utf-8")
+ (sample / "granted.py").write_text(_GRANTED_SOURCE, encoding="utf-8")
+ (root / "subject_grants.toml").write_text(
+ 'version = 1\n\n["pipelex/sample/granted.py::render"]\nparam = "node"\nrationale = "test grant"\n',
+ encoding="utf-8",
+ )
class TestKeywordOnlyGuardSingleFile:
@@ -34,21 +41,27 @@ class TestKeywordOnlyGuardSingleFile:
"""
_make_tree(tmp_path)
monkeypatch.chdir(tmp_path)
- single = collect_violations_for_files([Path("pipelex/sample/bad.py")])
- full = collect_all_violations(Path("pipelex"))
- assert [violation.key for violation in single] == [violation.key for violation in full]
+ single = collect_violations_for_files([Path("pipelex/sample/bad.py")], grants={})
+ full = collect_all_violations(Path("pipelex"), grants={})
+ assert [violation.key for violation in single] == [violation.key for violation in full if violation.relative_path.endswith("bad.py")]
assert len(single) == 1
assert single[0].relative_path == "pipelex/sample/bad.py"
assert single[0].qualified_name == "f"
def test_compliant_file_has_no_violations(self, tmp_path: Path) -> None:
_make_tree(tmp_path)
- assert collect_violations_for_files([Path("pipelex/sample/good.py")], root=tmp_path) == []
+ assert collect_violations_for_files([Path("pipelex/sample/good.py")], root=tmp_path, grants={}) == []
+
+ def test_granted_file_has_no_violations(self, tmp_path: Path) -> None:
+ """The lean per-file path honors the grants it is given — a granted subject is clean."""
+ _make_tree(tmp_path)
+ grants = load_subject_grants(root=tmp_path)
+ assert collect_violations_for_files([Path("pipelex/sample/granted.py")], root=tmp_path, grants=grants) == []
def test_absolute_path_is_handled(self, tmp_path: Path) -> None:
_make_tree(tmp_path)
abs_path = tmp_path / "pipelex" / "sample" / "bad.py"
- result = collect_violations_for_files([abs_path], root=tmp_path)
+ result = collect_violations_for_files([abs_path], root=tmp_path, grants={})
assert len(result) == 1
assert result[0].qualified_name == "f"
@@ -56,17 +69,17 @@ class TestKeywordOnlyGuardSingleFile:
"""A .py file outside pipelex/ is not the guard's concern."""
(tmp_path / "tests").mkdir()
(tmp_path / "tests" / "thing.py").write_text(_BAD_SOURCE, encoding="utf-8")
- assert collect_violations_for_files([Path("tests/thing.py")], root=tmp_path) == []
+ assert collect_violations_for_files([Path("tests/thing.py")], root=tmp_path, grants={}) == []
def test_syntax_error_file_skipped(self, tmp_path: Path) -> None:
"""A mid-edit file that does not parse yet is skipped, never raised — the hook must not block on it."""
(tmp_path / "pipelex").mkdir()
(tmp_path / "pipelex" / "broken.py").write_text("def f(a, b\n", encoding="utf-8")
- assert collect_violations_for_files([Path("pipelex/broken.py")], root=tmp_path) == []
+ assert collect_violations_for_files([Path("pipelex/broken.py")], root=tmp_path, grants={}) == []
def test_missing_file_skipped(self, tmp_path: Path) -> None:
(tmp_path / "pipelex").mkdir()
- assert collect_violations_for_files([Path("pipelex/ghost.py")], root=tmp_path) == []
+ assert collect_violations_for_files([Path("pipelex/ghost.py")], root=tmp_path, grants={}) == []
@pytest.mark.parametrize(
"relative",
@@ -99,6 +112,30 @@ class TestKeywordOnlyGuardSingleFile:
assert exit_code == 2
assert "pipelex/sample/bad.py:1" in captured.err
assert "f" in captured.err
+ assert "missing-star" in captured.err # the violation's kind and its remedy are named
+
+ def test_main_reads_the_registry(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None:
+ """The lean entrypoint loads subject_grants.toml itself — a granted subject passes, an ungranted one blocks."""
+ _make_tree(tmp_path)
+ (tmp_path / "pipelex" / "sample" / "ungranted.py").write_text("def render(node):\n return node\n", encoding="utf-8")
+ monkeypatch.chdir(tmp_path)
+ assert main(["pipelex/sample/granted.py"]) == 0
+ exit_code = main(["pipelex/sample/ungranted.py"])
+ captured = capsys.readouterr()
+ assert exit_code == 2
+ assert "ungranted-subject" in captured.err
+ assert "make subject-grant" in captured.err
+
+ def test_main_returns_2_when_registry_missing(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None:
+ """A missing registry is an explicit check error, never a silent empty registry."""
+ _make_tree(tmp_path)
+ (tmp_path / "subject_grants.toml").unlink()
+ monkeypatch.chdir(tmp_path)
+ exit_code = main(["pipelex/sample/good.py"])
+ captured = capsys.readouterr()
+ assert exit_code == 2
+ assert "could not run" in captured.err
+ assert "subject_grants.toml" in captured.err
def test_main_returns_0_for_compliant(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None:
_make_tree(tmp_path)
diff --git a/tests/unit/pipelex/cli/dev/test_subject_grant_cmd.py b/tests/unit/pipelex/cli/dev/test_subject_grant_cmd.py
new file mode 100644
index 000000000..94eef4217
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_subject_grant_cmd.py
@@ -0,0 +1,144 @@
+"""Unit tests for the `pipelex-dev subject-grant` command: refusals and sorted writes."""
+
+from __future__ import annotations
+
+import tomllib
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from rich.console import Console
+
+from pipelex.cli.dev_cli.commands.subject_grant_cmd import subject_grant_cmd
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+_MODULE_SOURCE = """\
+def render(node):
+ return node
+
+
+def build(spec, *, strict=False):
+ return spec
+
+
+def do_doctor_cmd(fix: bool):
+ return fix
+
+
+def all_keyword(*, alpha, beta):
+ return alpha
+
+
+def __dunder_like__(self, key, value):
+ return key
+"""
+
+_OVERLOADS_SOURCE = """\
+def parse(spec):
+ return spec
+
+
+def parse(data):
+ return data
+"""
+
+
+def _read_registry(root: Path) -> dict[str, Any]:
+ return tomllib.loads((root / "subject_grants.toml").read_text(encoding="utf-8"))
+
+
+class TestSubjectGrantCmd:
+ console: Console
+
+ @pytest.fixture(autouse=True)
+ def repo(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, mocker: MockerFixture) -> Path:
+ """A minimal repo tree (source module + empty registry) with cwd and console captured."""
+ sample = tmp_path / "pipelex" / "sample"
+ sample.mkdir(parents=True)
+ (sample / "module.py").write_text(_MODULE_SOURCE, encoding="utf-8")
+ (sample / "overloads.py").write_text(_OVERLOADS_SOURCE, encoding="utf-8")
+ (tmp_path / "subject_grants.toml").write_text("version = 1\n", encoding="utf-8")
+ monkeypatch.chdir(tmp_path)
+ self.console = Console(width=200, record=True, color_system=None)
+ mocker.patch("pipelex.cli.dev_cli.commands.subject_grant_cmd.get_console", return_value=self.console)
+ return tmp_path
+
+ def test_grant_records_param_and_rewrites_sorted(self, repo: Path) -> None:
+ """A grant validates the def, records the subject's param automatically, and keeps the file sorted."""
+ subject_grant_cmd(func_key="pipelex/sample/module.py::render", rationale="Verb-object; single operand.", quiet=True)
+ subject_grant_cmd(func_key="pipelex/sample/module.py::build", rationale="Verb-object; builds the spec.", quiet=True)
+ data = _read_registry(repo)
+ assert data["version"] == 1
+ entry_keys = [key for key in data if key != "version"]
+ assert entry_keys == sorted(entry_keys)
+ assert data["pipelex/sample/module.py::render"] == {"param": "node", "rationale": "Verb-object; single operand."}
+ assert data["pipelex/sample/module.py::build"] == {"param": "spec", "rationale": "Verb-object; builds the spec."}
+
+ def test_grant_updates_existing_entry(self, repo: Path) -> None:
+ """Re-granting an existing entry replaces its rationale and reports the update."""
+ (repo / "subject_grants.toml").write_text(
+ 'version = 1\n\n["pipelex/sample/module.py::render"]\nparam = "node"\nrationale = "Old rationale."\n',
+ encoding="utf-8",
+ )
+ subject_grant_cmd(func_key="pipelex/sample/module.py::render", rationale="Reviewed for real.", quiet=True)
+ data = _read_registry(repo)
+ assert data["pipelex/sample/module.py::render"] == {"param": "node", "rationale": "Reviewed for real."}
+ assert "subject-grant updated" in self.console.export_text()
+
+ def test_refuses_empty_rationale(self, repo: Path) -> None:
+ with pytest.raises(SystemExit) as exc_info:
+ subject_grant_cmd(func_key="pipelex/sample/module.py::render", rationale=" ")
+ assert exc_info.value.code == 1
+ assert "rationale" in self.console.export_text()
+ assert "render" not in _read_registry(repo)
+
+ def test_refuses_literal_subject(self) -> None:
+ with pytest.raises(SystemExit) as exc_info:
+ subject_grant_cmd(func_key="pipelex/sample/module.py::do_doctor_cmd", rationale="please")
+ assert exc_info.value.code == 1
+ assert "literal-typed" in self.console.export_text()
+
+ def test_refuses_non_positional_subject(self) -> None:
+ with pytest.raises(SystemExit) as exc_info:
+ subject_grant_cmd(func_key="pipelex/sample/module.py::all_keyword", rationale="please")
+ assert exc_info.value.code == 1
+ assert "no positional subject" in self.console.export_text()
+
+ def test_refuses_missing_def(self) -> None:
+ with pytest.raises(SystemExit) as exc_info:
+ subject_grant_cmd(func_key="pipelex/sample/module.py::ghost", rationale="please")
+ assert exc_info.value.code == 1
+ assert "no def" in self.console.export_text()
+
+ def test_refuses_exempt_def(self) -> None:
+ with pytest.raises(SystemExit) as exc_info:
+ subject_grant_cmd(func_key="pipelex/sample/module.py::__dunder_like__", rationale="please")
+ assert exc_info.value.code == 1
+ assert "exempt" in self.console.export_text()
+
+ def test_refuses_malformed_key(self) -> None:
+ with pytest.raises(SystemExit) as exc_info:
+ subject_grant_cmd(func_key="pipelex/sample/module.py", rationale="please")
+ assert exc_info.value.code == 1
+ assert "FUNC key" in self.console.export_text()
+
+ def test_refuses_disagreeing_overloads(self) -> None:
+ """Same-qualname defs must agree on the subject name before one grant can cover them (D11)."""
+ with pytest.raises(SystemExit) as exc_info:
+ subject_grant_cmd(func_key="pipelex/sample/overloads.py::parse", rationale="please")
+ assert exc_info.value.code == 1
+ assert "disagree" in self.console.export_text()
+
+ def test_refuses_unknown_registry_key(self, repo: Path) -> None:
+ """The tightened schema: a registry entry carrying any key beyond param/rationale fails the load."""
+ (repo / "subject_grants.toml").write_text(
+ 'version = 1\n\n["pipelex/sample/module.py::render"]\nparam = "node"\nrationale = "ok"\nseeded = true\n',
+ encoding="utf-8",
+ )
+ with pytest.raises(SystemExit) as exc_info:
+ subject_grant_cmd(func_key="pipelex/sample/module.py::build", rationale="Verb-object; builds the spec.")
+ assert exc_info.value.code == 1
+ assert "unknown key" in self.console.export_text()
diff --git a/tests/unit/pipelex/cli/dev/test_subject_grant_registry.py b/tests/unit/pipelex/cli/dev/test_subject_grant_registry.py
new file mode 100644
index 000000000..ae7e5cb7d
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_subject_grant_registry.py
@@ -0,0 +1,137 @@
+"""Unit tests for the subject-grants registry: loading/validation and symmetric staleness (dead grants)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from pipelex.cli.dev_cli.commands.keyword_only_guard import (
+ SubjectGrant,
+ SubjectGrantRegistryError,
+ ViolationKind,
+ collect_all_violations,
+ load_subject_grants,
+)
+
+_VALID_REGISTRY = """\
+version = 1
+
+["pipelex/sample/module.py::render"]
+param = "node"
+rationale = "Verb-object; single operand."
+
+["pipelex/sample/module.py::Builder.build"]
+param = "spec"
+rationale = "Factory from source: builds from the spec."
+"""
+
+
+def _write_registry(root: Path, *, content: str) -> None:
+ (root / "subject_grants.toml").write_text(content, encoding="utf-8")
+
+
+class TestSubjectGrantRegistry:
+ def test_valid_registry_loads(self, tmp_path: Path) -> None:
+ """A well-formed registry round-trips into typed grants."""
+ _write_registry(tmp_path, content=_VALID_REGISTRY)
+ grants = load_subject_grants(root=tmp_path)
+ assert grants == {
+ "pipelex/sample/module.py::render": SubjectGrant(param="node", rationale="Verb-object; single operand."),
+ "pipelex/sample/module.py::Builder.build": SubjectGrant(param="spec", rationale="Factory from source: builds from the spec."),
+ }
+
+ def test_missing_registry_is_an_explicit_error(self, tmp_path: Path) -> None:
+ """No file means no verdict — never a silent empty registry (that would mass-flag every grant)."""
+ with pytest.raises(SubjectGrantRegistryError, match="not found"):
+ load_subject_grants(root=tmp_path)
+
+ def test_invalid_toml_raises(self, tmp_path: Path) -> None:
+ _write_registry(tmp_path, content="version = [broken\n")
+ with pytest.raises(SubjectGrantRegistryError, match="not valid TOML"):
+ load_subject_grants(root=tmp_path)
+
+ def test_missing_version_raises(self, tmp_path: Path) -> None:
+ _write_registry(tmp_path, content='["pipelex/a.py::f"]\nparam = "x"\nrationale = "y"\n')
+ with pytest.raises(SubjectGrantRegistryError, match="version = 1"):
+ load_subject_grants(root=tmp_path)
+
+ def test_wrong_version_raises(self, tmp_path: Path) -> None:
+ _write_registry(tmp_path, content="version = 2\n")
+ with pytest.raises(SubjectGrantRegistryError, match="version = 1"):
+ load_subject_grants(root=tmp_path)
+
+ def test_malformed_key_raises(self, tmp_path: Path) -> None:
+ """An entry key must be '<relative_path>::<qualified_name>' — typos fail the check, they don't rot."""
+ _write_registry(tmp_path, content='version = 1\n["pipelex/a.py"]\nparam = "x"\nrationale = "y"\n')
+ with pytest.raises(SubjectGrantRegistryError, match="not of the form"):
+ load_subject_grants(root=tmp_path)
+
+ def test_unknown_entry_key_raises(self, tmp_path: Path) -> None:
+ _write_registry(tmp_path, content='version = 1\n["pipelex/a.py::f"]\nparam = "x"\nrationale = "y"\nreviewer = "me"\n')
+ with pytest.raises(SubjectGrantRegistryError, match="unknown key"):
+ load_subject_grants(root=tmp_path)
+
+ def test_empty_param_raises(self, tmp_path: Path) -> None:
+ _write_registry(tmp_path, content='version = 1\n["pipelex/a.py::f"]\nparam = ""\nrationale = "y"\n')
+ with pytest.raises(SubjectGrantRegistryError, match="non-empty string `param`"):
+ load_subject_grants(root=tmp_path)
+
+ def test_blank_rationale_raises(self, tmp_path: Path) -> None:
+ _write_registry(tmp_path, content='version = 1\n["pipelex/a.py::f"]\nparam = "x"\nrationale = " "\n')
+ with pytest.raises(SubjectGrantRegistryError, match="non-empty `rationale`"):
+ load_subject_grants(root=tmp_path)
+
+ def test_transitional_seeded_key_rejected(self, tmp_path: Path) -> None:
+ """The transitional `seeded` field is gone from the schema — any surviving entry fails the load."""
+ _write_registry(tmp_path, content='version = 1\n["pipelex/a.py::f"]\nparam = "x"\nrationale = "y"\nseeded = true\n')
+ with pytest.raises(SubjectGrantRegistryError, match="unknown key"):
+ load_subject_grants(root=tmp_path)
+
+ def test_dead_grant_for_deleted_def_flagged(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """A grant whose def no longer exists is a violation — staleness is symmetric (D7)."""
+ source_root = tmp_path / "pipelex" / "sample"
+ source_root.mkdir(parents=True)
+ (source_root / "module.py").write_text("def render(node):\n return node\n", encoding="utf-8")
+ monkeypatch.chdir(tmp_path)
+ grants = {
+ "pipelex/sample/module.py::render": SubjectGrant(param="node", rationale="ok"),
+ "pipelex/sample/module.py::ghost": SubjectGrant(param="spec", rationale="def was deleted"),
+ }
+ violations = collect_all_violations(Path("pipelex"), grants=grants)
+ assert [violation.kind for violation in violations] == [ViolationKind.DEAD_GRANT]
+ assert violations[0].qualified_name == "ghost"
+ assert violations[0].lineno == 0
+
+ def test_dead_grant_for_demoted_def_flagged(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """A grant whose def went fully keyword-only is dead too — the entry must be cleaned up."""
+ source_root = tmp_path / "pipelex" / "sample"
+ source_root.mkdir(parents=True)
+ (source_root / "module.py").write_text("def render(*, node):\n return node\n", encoding="utf-8")
+ monkeypatch.chdir(tmp_path)
+ grants = {"pipelex/sample/module.py::render": SubjectGrant(param="node", rationale="now demoted")}
+ violations = collect_all_violations(Path("pipelex"), grants=grants)
+ assert [violation.kind for violation in violations] == [ViolationKind.DEAD_GRANT]
+
+ def test_dead_grant_for_newly_exempt_def_flagged(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """A def that became carved-out (e.g. @override) no longer holds its grant — forces a registry decision."""
+ source_root = tmp_path / "pipelex" / "sample"
+ source_root.mkdir(parents=True)
+ (source_root / "module.py").write_text(
+ "class Impl:\n @override\n def render(self, node):\n return node\n",
+ encoding="utf-8",
+ )
+ monkeypatch.chdir(tmp_path)
+ grants = {"pipelex/sample/module.py::Impl.render": SubjectGrant(param="node", rationale="now overridden")}
+ violations = collect_all_violations(Path("pipelex"), grants=grants)
+ assert [violation.kind for violation in violations] == [ViolationKind.DEAD_GRANT]
+
+ def test_live_grant_not_flagged_even_while_def_violates_missing_star(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """A granted def that grew a second positional param reports missing-star only — the grant stays alive."""
+ source_root = tmp_path / "pipelex" / "sample"
+ source_root.mkdir(parents=True)
+ (source_root / "module.py").write_text("def render(node, extra):\n return node\n", encoding="utf-8")
+ monkeypatch.chdir(tmp_path)
+ grants = {"pipelex/sample/module.py::render": SubjectGrant(param="node", rationale="ok")}
+ violations = collect_all_violations(Path("pipelex"), grants=grants)
+ assert [violation.kind for violation in violations] == [ViolationKind.MISSING_STAR]
diff --git a/tests/unit/pipelex/cli/test_error_handlers_more.py b/tests/unit/pipelex/cli/test_error_handlers_more.py
index 7938b52fd..a2cd07189 100644
--- a/tests/unit/pipelex/cli/test_error_handlers_more.py
+++ b/tests/unit/pipelex/cli/test_error_handlers_more.py
@@ -60,7 +60,7 @@ class TestErrorHandlersExtended:
"""The panel renders title, aligned fields, error, tip and links in order."""
console = Console(width=120, record=True, color_system=None)
display_error_panel(
- console,
+ console=console,
title="Something failed",
fields=[("Pipe", "'my_pipe'"), ("Model Choice", "'gpt-5'")],
error_message="model not found",
@@ -79,7 +79,7 @@ class TestErrorHandlersExtended:
"""A None error_message omits the Error block entirely."""
console = Console(width=120, record=True, color_system=None)
display_error_panel(
- console,
+ console=console,
title="Soft failure",
fields=[],
error_message=None,
@@ -94,7 +94,7 @@ class TestErrorHandlersExtended:
"""Multi-line tips keep their line structure."""
console = Console(width=120, record=True, color_system=None)
display_error_panel(
- console,
+ console=console,
title="Failure",
fields=[],
error_message=None,
diff --git a/tests/unit/pipelex/cli/test_init_credentials.py b/tests/unit/pipelex/cli/test_init_credentials.py
index c14546931..d15316a2b 100644
--- a/tests/unit/pipelex/cli/test_init_credentials.py
+++ b/tests/unit/pipelex/cli/test_init_credentials.py
@@ -130,7 +130,7 @@ class TestInitCredentials:
)
mock_prompt = mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask")
mock_console: MagicMock = mocker.MagicMock()
- prompt_credentials(mock_console, backends_toml_path=backends_toml)
+ prompt_credentials(console=mock_console, backends_toml_path=backends_toml)
# Should print "already set" message, no Prompt.ask calls
mock_console.print.assert_called()
mock_prompt.assert_not_called()
@@ -152,7 +152,7 @@ class TestInitCredentials:
return_value="sk-test-value",
)
mock_console: MagicMock = mocker.MagicMock()
- prompt_credentials(mock_console, backends_toml_path=backends_toml)
+ prompt_credentials(console=mock_console, backends_toml_path=backends_toml)
# Verify .env was written
env_path = tmp_path / ".env"
@@ -182,7 +182,7 @@ class TestInitCredentials:
return_value="",
)
mock_console: MagicMock = mocker.MagicMock()
- prompt_credentials(mock_console, backends_toml_path=backends_toml)
+ prompt_credentials(console=mock_console, backends_toml_path=backends_toml)
# Verify .env was NOT written (no values entered)
env_path = tmp_path / ".env"
@@ -207,7 +207,7 @@ class TestInitCredentials:
return_value="sk-new",
)
mock_console: MagicMock = mocker.MagicMock()
- prompt_credentials(mock_console, backends_toml_path=backends_toml)
+ prompt_credentials(console=mock_console, backends_toml_path=backends_toml)
result = read_env_file(env_path)
assert result["EXISTING_KEY"] == "existing_value"
@@ -226,5 +226,5 @@ class TestInitCredentials:
)
mock_prompt = mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask")
mock_console: MagicMock = mocker.MagicMock()
- prompt_credentials(mock_console, backends_toml_path=backends_toml)
+ prompt_credentials(console=mock_console, backends_toml_path=backends_toml)
mock_prompt.assert_not_called()
diff --git a/tests/unit/pipelex/cli/test_is_traceback_requested.py b/tests/unit/pipelex/cli/test_is_traceback_requested.py
index 0b4407671..fe51bb30b 100644
--- a/tests/unit/pipelex/cli/test_is_traceback_requested.py
+++ b/tests/unit/pipelex/cli/test_is_traceback_requested.py
@@ -20,7 +20,7 @@ class TestIsTracebackRequested:
subcommand dispatch, which silently disabled --traceback when the flag was read
through click.get_current_context().
"""
- set_traceback_requested(True)
+ set_traceback_requested(value=True)
assert is_traceback_requested() is True
def test_returns_false_when_no_click_context(self) -> None:
diff --git a/tests/unit/pipelex/cli/test_print_traceback_if_requested.py b/tests/unit/pipelex/cli/test_print_traceback_if_requested.py
index 4a1ead564..639afff46 100644
--- a/tests/unit/pipelex/cli/test_print_traceback_if_requested.py
+++ b/tests/unit/pipelex/cli/test_print_traceback_if_requested.py
@@ -24,7 +24,7 @@ class TestPrintTracebackIfRequested:
console = mocker.MagicMock()
ctx = click.Context(click.Command("test"), obj={"traceback": False})
with ctx:
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print.assert_not_called()
def test_prints_traceback_when_flag_set(self, mocker: MockerFixture) -> None:
@@ -36,7 +36,7 @@ class TestPrintTracebackIfRequested:
msg = "test error"
raise ValueError(msg)
except ValueError:
- print_traceback_if_requested(console)
+ print_traceback_if_requested(console=console)
console.print.assert_called_once()
arg = console.print.call_args[0][0]
assert isinstance(arg, Traceback)
diff --git a/tests/unit/pipelex/core/pipes/output/test_output_renderer_anything_formats.py b/tests/unit/pipelex/core/pipes/output/test_output_renderer_anything_formats.py
index d74f643ce..207d0eedf 100644
--- a/tests/unit/pipelex/core/pipes/output/test_output_renderer_anything_formats.py
+++ b/tests/unit/pipelex/core/pipes/output/test_output_renderer_anything_formats.py
@@ -65,7 +65,7 @@ class TestRenderOutputAnythingFormats:
"content": {"text": "summary text"},
}
}
- mapped_pipe.output.render_stuff_spec.assert_called_once_with(ConceptRepresentationFormat.JSON)
+ mapped_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.JSON)
def test_anything_python_renders_option_lines(self, mocker: MockerFixture) -> None:
"""PYTHON format lists each possible output as a commented option with an output_N assignment."""
@@ -84,7 +84,7 @@ class TestRenderOutputAnythingFormats:
assert result_lines[1] == "# The actual output will be one of the following:"
assert "# Option 1: test.Summary" in result_lines
assert 'output_1 = SummaryContent(text="hello")' in result_lines
- mapped_pipe.output.render_stuff_spec.assert_called_once_with(ConceptRepresentationFormat.PYTHON)
+ mapped_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.PYTHON)
def test_anything_schema_renders_schema_options(self, mocker: MockerFixture) -> None:
"""SCHEMA format wraps each possible output under a schema_option_N key with concept and content."""
@@ -106,4 +106,4 @@ class TestRenderOutputAnythingFormats:
"content": schema_content,
}
}
- mapped_pipe.output.render_stuff_spec.assert_called_once_with(ConceptRepresentationFormat.SCHEMA)
+ mapped_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.SCHEMA)
diff --git a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_condition.py b/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_condition.py
index 4d01c8e3b..c1c3c92f1 100644
--- a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_condition.py
+++ b/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_condition.py
@@ -50,7 +50,7 @@ class TestCollectPossibleOutputsCondition:
assert result == [{"concept_ref": "test.Summary", "content": {"text": "summary text"}}]
get_pipe_mock.assert_called_once_with(pipe_code="make_summary")
- mapped_pipe.output.render_stuff_spec.assert_called_once_with(ConceptRepresentationFormat.JSON)
+ mapped_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.JSON)
def test_multiple_mapped_pipes_are_ordered_deterministically(self, mocker: MockerFixture) -> None:
"""With several mapped pipes, outputs come back sorted by pipe code regardless of set iteration order."""
diff --git a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_sequence.py b/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_sequence.py
index 9c077670b..c9017ec5b 100644
--- a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_sequence.py
+++ b/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_sequence.py
@@ -67,7 +67,7 @@ class TestCollectPossibleOutputsSequence:
assert result == [{"concept_ref": "test.Final", "content": {"text": "final output"}}]
get_pipe_mock.assert_called_once_with(pipe_code="final_step")
- final_pipe.output.render_stuff_spec.assert_called_once_with(ConceptRepresentationFormat.JSON)
+ final_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.JSON)
@pytest.mark.parametrize(
"render_error",
@@ -111,4 +111,4 @@ class TestCollectPossibleOutputsSequence:
assert get_pipe_mock.call_count == 2
get_pipe_mock.assert_any_call(pipe_code="mid_sequence")
get_pipe_mock.assert_any_call(pipe_code="leaf_step")
- leaf_pipe.output.render_stuff_spec.assert_called_once_with(ConceptRepresentationFormat.JSON)
+ leaf_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.JSON)
diff --git a/tests/unit/pipelex/core/pipes/test_input_stuff_specs_presence.py b/tests/unit/pipelex/core/pipes/test_input_stuff_specs_presence.py
index 93d442d71..852efe553 100644
--- a/tests/unit/pipelex/core/pipes/test_input_stuff_specs_presence.py
+++ b/tests/unit/pipelex/core/pipes/test_input_stuff_specs_presence.py
@@ -47,7 +47,7 @@ class TestInputStuffSpecsPresence:
def test_add_stuff_spec_carries_presence(self):
specs = InputStuffSpecs(root={})
- specs.add_stuff_spec("maybe_var", concept=_text_concept(), presence=PresenceMarker.OPTIONAL)
+ specs.add_stuff_spec(variable_name="maybe_var", concept=_text_concept(), presence=PresenceMarker.OPTIONAL)
assert specs.root["maybe_var"].presence == PresenceMarker.OPTIONAL
def test_root_validator_preserves_presence(self):
diff --git a/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py b/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py
index e51fd1daa..871a9c793 100644
--- a/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py
+++ b/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py
@@ -67,7 +67,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = content.render_with_images(registry, text_format=TextFormat.PLAIN)
+ result = content.render_with_images(registry=registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_PLAIN_LIST
assert len(registry.images) == 3
@@ -86,7 +86,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = content.render_with_images(registry, text_format=TextFormat.PLAIN)
+ result = content.render_with_images(registry=registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_DICT
assert len(registry.images) == 2
@@ -107,7 +107,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = content.render_with_images(registry, text_format=TextFormat.PLAIN)
+ result = content.render_with_images(registry=registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_NESTED_LIST
assert len(registry.images) == 3
@@ -125,7 +125,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = content.render_with_images(registry, text_format=TextFormat.PLAIN)
+ result = content.render_with_images(registry=registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_IMAGE_RENDERABLE
assert len(registry.images) == 2
@@ -144,7 +144,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = page.render_with_images(registry, text_format=TextFormat.PLAIN)
+ result = page.render_with_images(registry=registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_PAGE_CONTENT_ALL
assert len(registry.images) == 3
@@ -160,7 +160,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = content.render_with_images(registry, text_format=TextFormat.PLAIN)
+ result = content.render_with_images(registry=registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_EMPTY_LIST
assert len(registry.images) == 0
@@ -176,7 +176,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = page.render_with_images(registry, text_format=TextFormat.PLAIN)
+ result = page.render_with_images(registry=registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_NONE_PAGE_VIEW
assert len(registry.images) == 1
@@ -198,4 +198,4 @@ class TestStuffArtefactWithImagesFailFast:
registry = ImageRegistry()
with pytest.raises(TypeError, match="does not implement ImageRenderable"):
- artefact.render_with_images(registry, text_format=TextFormat.PLAIN)
+ artefact.render_with_images(registry=registry, text_format=TextFormat.PLAIN)
diff --git a/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_size_default.py b/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_size_default.py
index dafc94b20..ab602c3f2 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_size_default.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_size_default.py
@@ -25,4 +25,4 @@ class TestResolveDefaultSize:
expected: SizeTier | ImageSize | None,
):
"""An exact-size deck default must not silently defeat a pipe's explicit aspect_ratio; tiers always compose."""
- assert resolve_default_size(explicit_aspect_ratio, default_size=default_size) == expected
+ assert resolve_default_size(explicit_aspect_ratio=explicit_aspect_ratio, default_size=default_size) == expected
diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_applier.py b/tests/unit/pipelex/pipeline/fixes/test_fix_applier.py
index 05224affd..626aa64cf 100644
--- a/tests/unit/pipelex/pipeline/fixes/test_fix_applier.py
+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_applier.py
@@ -35,16 +35,16 @@ class TestFixApplier:
def test_set_key_matches_golden_bytes(self) -> None:
"""Applying the set_key op then formatting yields output byte-equal to the golden file."""
toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))
- applications = apply_fix_ops(toml_doc, ops=[_set_output_op()])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_set_output_op()])
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]
assert serialize_and_format(toml_doc) == _GOLDEN_PATH.read_text(encoding="utf-8")
def test_apply_twice_is_idempotent(self) -> None:
"""Applying the same op twice yields the same bytes as applying it once."""
toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))
- apply_fix_ops(toml_doc, ops=[_set_output_op()])
+ apply_fix_ops(toml_doc=toml_doc, ops=[_set_output_op()])
once = _dumps(toml_doc)
- applications = apply_fix_ops(toml_doc, ops=[_set_output_op()])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_set_output_op()])
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]
assert _dumps(toml_doc) == once
@@ -52,7 +52,7 @@ class TestFixApplier:
"""An op targeting a table absent from the DOM (e.g. a synthetic pipe) is skipped and reported."""
toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))
source_bytes = _dumps(toml_doc)
- applications = apply_fix_ops(toml_doc, ops=[_set_output_op(pipe_code="synthetic_pipe_not_in_file")])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_set_output_op(pipe_code="synthetic_pipe_not_in_file")])
assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]
assert applications[0].detail is not None
assert "pipe" in applications[0].detail
@@ -62,7 +62,7 @@ class TestFixApplier:
"""delete_key removes exactly the addressed key; everything else survives byte-for-byte."""
toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))
delete_op = FixOp(kind=FixOpKind.DELETE_KEY, table_path=["pipe", "gen_ideas"], key="prompt")
- applications = apply_fix_ops(toml_doc, ops=[delete_op])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[delete_op])
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]
dumped = _dumps(toml_doc)
assert "Generate ideas about $topic" not in dumped
@@ -73,7 +73,7 @@ class TestFixApplier:
"""delete_key on an absent key is skipped and reported, not raised."""
toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))
delete_op = FixOp(kind=FixOpKind.DELETE_KEY, table_path=["pipe", "gen_ideas"], key="not_a_key")
- applications = apply_fix_ops(toml_doc, ops=[delete_op])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[delete_op])
assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]
def test_delete_table_on_scalar_leaf_is_skipped(self) -> None:
@@ -81,7 +81,7 @@ class TestFixApplier:
toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))
source_bytes = _dumps(toml_doc)
delete_op = FixOp(kind=FixOpKind.DELETE_TABLE, table_path=["pipe", "gen_ideas", "prompt"])
- applications = apply_fix_ops(toml_doc, ops=[delete_op])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[delete_op])
assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]
assert applications[0].detail is not None
assert _dumps(toml_doc) == source_bytes
@@ -90,7 +90,7 @@ class TestFixApplier:
"""delete_table removes the addressed table and its keys; sibling tables survive."""
toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))
delete_op = FixOp(kind=FixOpKind.DELETE_TABLE, table_path=["pipe", "gen_ideas"])
- applications = apply_fix_ops(toml_doc, ops=[delete_op])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[delete_op])
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]
dumped = _dumps(toml_doc)
assert "[pipe.gen_ideas]" not in dumped
@@ -103,7 +103,7 @@ class TestFixApplier:
"""
source = '[pipe]\nlist_ideas = { type = "PipeSequence", inputs = { topic = "Text" }, output = "Idea" }\n'
toml_doc = tomlkit.loads(source)
- applications = apply_fix_ops(toml_doc, ops=[_set_output_op()])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_set_output_op()])
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]
reloaded = tomlkit.loads(serialize_and_format(toml_doc)).unwrap()["pipe"]["list_ideas"]
assert reloaded["output"] == "Idea[]"
diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_applier_inputs_sync.py b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_inputs_sync.py
index f4a4d1b46..183383621 100644
--- a/tests/unit/pipelex/pipeline/fixes/test_fix_applier_inputs_sync.py
+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_inputs_sync.py
@@ -53,21 +53,21 @@ class TestFixApplierInputsSync:
def test_inline_inputs_diff_matches_golden_bytes(self) -> None:
"""Add + update + delete on an inline inputs table, then format, yields the golden bytes."""
toml_doc = _load("controller_inputs_inline")
- applications = apply_fix_ops(toml_doc, ops=_INLINE_OPS)
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=_INLINE_OPS)
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED] * 3
assert serialize_and_format(toml_doc) == _golden("controller_inputs_inline")
def test_block_inputs_diff_matches_golden_bytes(self) -> None:
"""Update + delete on a block [pipe.x.inputs] table preserves surrounding comments."""
toml_doc = _load("controller_inputs_block")
- applications = apply_fix_ops(toml_doc, ops=_BLOCK_OPS)
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=_BLOCK_OPS)
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED] * 2
assert serialize_and_format(toml_doc) == _golden("controller_inputs_block")
def test_missing_inputs_table_created_as_inline_table(self) -> None:
"""With no inputs declared, one set_key writes the whole mapping as an inline table."""
toml_doc = _load("controller_inputs_missing_table")
- applications = apply_fix_ops(toml_doc, ops=_MISSING_TABLE_OPS)
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=_MISSING_TABLE_OPS)
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED] * 2
assert serialize_and_format(toml_doc) == _golden("controller_inputs_missing_table")
@@ -81,7 +81,7 @@ output = "Text"
# keep this author note
"""
toml_doc = tomlkit.loads(source)
- applications = apply_fix_ops(toml_doc, ops=_MISSING_TABLE_OPS)
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=_MISSING_TABLE_OPS)
assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED, FixOpOutcome.APPLIED]
formatted = serialize_and_format(toml_doc)
@@ -91,9 +91,9 @@ output = "Text"
def test_inline_diff_applied_twice_is_idempotent(self) -> None:
"""Re-applying the same diff yields the same bytes."""
toml_doc = _load("controller_inputs_inline")
- apply_fix_ops(toml_doc, ops=_INLINE_OPS)
+ apply_fix_ops(toml_doc=toml_doc, ops=_INLINE_OPS)
once = _dumps(toml_doc)
- applications = apply_fix_ops(toml_doc, ops=_INLINE_OPS)
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=_INLINE_OPS)
set_outcomes = [application.outcome for application in applications[:2]]
delete_outcome = applications[2].outcome
assert set_outcomes == [FixOpOutcome.APPLIED] * 2
@@ -103,9 +103,9 @@ output = "Text"
def test_missing_table_creation_applied_twice_is_idempotent(self) -> None:
"""Re-applying the whole-table set_key yields the same bytes."""
toml_doc = _load("controller_inputs_missing_table")
- apply_fix_ops(toml_doc, ops=_MISSING_TABLE_OPS)
+ apply_fix_ops(toml_doc=toml_doc, ops=_MISSING_TABLE_OPS)
once = _dumps(toml_doc)
- applications = apply_fix_ops(toml_doc, ops=_MISSING_TABLE_OPS)
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=_MISSING_TABLE_OPS)
assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED, FixOpOutcome.APPLIED]
assert _dumps(toml_doc) == once
@@ -116,7 +116,7 @@ output = "Text"
"""
source = '[pipe.make_summary]\ntype = "PipeSequence"\ninputs = { "cv.name" = "Text", cv = "Curriculum", note = "Text" }\n'
toml_doc = tomlkit.loads(source)
- applications = apply_fix_ops(toml_doc, ops=[FixOp(kind=FixOpKind.DELETE_KEY, table_path=_INPUTS_TABLE_PATH, key="note")])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[FixOp(kind=FixOpKind.DELETE_KEY, table_path=_INPUTS_TABLE_PATH, key="note")])
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]
formatted = serialize_and_format(toml_doc)
assert '"cv.name" = "Text"' in formatted
diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_applier_native_concept.py b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_native_concept.py
index 13450adda..dfc9475a4 100644
--- a/tests/unit/pipelex/pipeline/fixes/test_fix_applier_native_concept.py
+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_native_concept.py
@@ -40,7 +40,7 @@ class TestFixApplierNativeConcept:
def test_strip_matches_golden_bytes(self, fixture_stem: str, concept_code: str) -> None:
"""Deleting the redeclared concept then formatting yields the golden bytes, every form."""
toml_doc = tomlkit.loads((_DATA / f"{fixture_stem}.mthds").read_text(encoding="utf-8"))
- applications = apply_fix_ops(toml_doc, ops=[_delete_concept_op(key=concept_code)])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_delete_concept_op(key=concept_code)])
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]
golden = (_DATA / f"{fixture_stem}.golden.mthds").read_text(encoding="utf-8")
assert serialize_and_format(toml_doc) == golden
@@ -48,7 +48,7 @@ class TestFixApplierNativeConcept:
def test_delete_removes_table_and_its_structure_subtable(self) -> None:
"""Deleting a ``[concept.Text]`` table also drops its ``[concept.Text.structure]`` sub-table."""
toml_doc = tomlkit.loads((_DATA / "native_redecl_table.mthds").read_text(encoding="utf-8"))
- apply_fix_ops(toml_doc, ops=[_delete_concept_op(key="Text")])
+ apply_fix_ops(toml_doc=toml_doc, ops=[_delete_concept_op(key="Text")])
dumped = _dumps(toml_doc)
assert "[concept.Text]" not in dumped
assert "structure" not in dumped
@@ -59,9 +59,9 @@ class TestFixApplierNativeConcept:
def test_apply_twice_is_idempotent(self) -> None:
"""Re-applying the delete finds the key already gone — the bytes do not change."""
toml_doc = tomlkit.loads((_DATA / "native_redecl_inline.mthds").read_text(encoding="utf-8"))
- apply_fix_ops(toml_doc, ops=[_delete_concept_op(key="Text")])
+ apply_fix_ops(toml_doc=toml_doc, ops=[_delete_concept_op(key="Text")])
once = _dumps(toml_doc)
- applications = apply_fix_ops(toml_doc, ops=[_delete_concept_op(key="Text")])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_delete_concept_op(key="Text")])
assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]
assert _dumps(toml_doc) == once
@@ -85,7 +85,7 @@ class TestFixApplierNativeConcept:
'type = "PipeLLM"\n'
)
toml_doc = tomlkit.loads(source)
- apply_fix_ops(toml_doc, ops=[_delete_concept_op(key="Text")])
+ apply_fix_ops(toml_doc=toml_doc, ops=[_delete_concept_op(key="Text")])
dumped = _dumps(toml_doc)
assert "[concept.Text]" not in dumped
# The comment reflowed onto the successor table — it no longer annotates the deleted concept.
@@ -95,6 +95,6 @@ class TestFixApplierNativeConcept:
"""Stripping a concept absent from the document is reported as skipped, not raised."""
toml_doc = tomlkit.loads((_DATA / "native_redecl_inline.mthds").read_text(encoding="utf-8"))
source_bytes = _dumps(toml_doc)
- applications = apply_fix_ops(toml_doc, ops=[_delete_concept_op(key="Number")])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_delete_concept_op(key="Number")])
assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]
assert _dumps(toml_doc) == source_bytes
diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_applier_strip_namespace.py b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_strip_namespace.py
index 866954c28..ec3b91829 100644
--- a/tests/unit/pipelex/pipeline/fixes/test_fix_applier_strip_namespace.py
+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_strip_namespace.py
@@ -110,7 +110,7 @@ class TestFixApplierStripNamespace:
def test_strip_matches_golden_bytes(self) -> None:
"""Renaming the dotted declaration + stripping main_pipe, then formatting, yields the golden."""
toml_doc = tomlkit.loads((_DATA / "strip_namespace_rename.mthds").read_text(encoding="utf-8"))
- applications = apply_fix_ops(toml_doc, ops=_STRIP_OPS)
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=_STRIP_OPS)
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED, FixOpOutcome.APPLIED]
golden = (_DATA / "strip_namespace_rename.golden.mthds").read_text(encoding="utf-8")
assert serialize_and_format(toml_doc) == golden
@@ -118,7 +118,7 @@ class TestFixApplierStripNamespace:
def test_rename_preserves_position_and_comments(self) -> None:
"""The renamed pipe stays between its siblings, keeping its leading and trailing comments."""
toml_doc = tomlkit.loads((_DATA / "strip_namespace_rename.mthds").read_text(encoding="utf-8"))
- apply_fix_ops(toml_doc, ops=_STRIP_OPS)
+ apply_fix_ops(toml_doc=toml_doc, ops=_STRIP_OPS)
dumped = _dumps(toml_doc)
assert '[pipe."namespacefix.hello"]' not in dumped
assert "[pipe.hello]" in dumped
@@ -133,16 +133,16 @@ class TestFixApplierStripNamespace:
def test_apply_twice_is_idempotent(self) -> None:
"""Re-applying finds the dotted key already renamed / main_pipe already stripped — bytes hold."""
toml_doc = tomlkit.loads((_DATA / "strip_namespace_rename.mthds").read_text(encoding="utf-8"))
- apply_fix_ops(toml_doc, ops=_STRIP_OPS)
+ apply_fix_ops(toml_doc=toml_doc, ops=_STRIP_OPS)
once = serialize_and_format(toml_doc)
- second = apply_fix_ops(toml_doc, ops=_STRIP_OPS)
+ second = apply_fix_ops(toml_doc=toml_doc, ops=_STRIP_OPS)
assert [application.outcome for application in second] == [FixOpOutcome.SKIPPED, FixOpOutcome.APPLIED]
assert serialize_and_format(toml_doc) == once
def test_rename_skips_on_collision(self) -> None:
"""Renaming to a key already declared separately is skipped, not applied (no clobber)."""
toml_doc = tomlkit.loads(_COLLISION_MTHDS)
- applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="coll.hello", new_key="hello")])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_rename_op(key="coll.hello", new_key="hello")])
assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]
dumped = _dumps(toml_doc)
# Both declarations survive untouched — nothing was clobbered.
@@ -152,13 +152,13 @@ class TestFixApplierStripNamespace:
def test_rename_skips_when_key_absent(self) -> None:
"""A rename whose source key is not present is a guarded skip (e.g. a stale op)."""
toml_doc = tomlkit.loads(_COLLISION_MTHDS)
- applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="coll.ghost", new_key="ghost")])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_rename_op(key="coll.ghost", new_key="ghost")])
assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]
def test_rename_applies_on_interleaved_pipe_sections(self) -> None:
"""Interleaved ``[pipe.*]``/``[concept.*]`` sections (an ``OutOfOrderTableProxy``) rename in place."""
toml_doc = tomlkit.loads(_INTERLEAVED_MTHDS)
- applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="inter.hello", new_key="hello")])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_rename_op(key="inter.hello", new_key="hello")])
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]
dumped = _dumps(toml_doc)
assert '[pipe."inter.hello"]' not in dumped
@@ -172,7 +172,7 @@ class TestFixApplierStripNamespace:
"""A collision with a bare key living in a *different* ``[pipe.*]`` section is still a skip."""
interleaved_collision = _INTERLEAVED_MTHDS.replace("[pipe.other]", "[pipe.hello]")
toml_doc = tomlkit.loads(interleaved_collision)
- applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="inter.hello", new_key="hello")])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_rename_op(key="inter.hello", new_key="hello")])
assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]
dumped = _dumps(toml_doc)
assert '[pipe."inter.hello"]' in dumped
@@ -185,7 +185,7 @@ class TestFixApplierStripNamespace:
sub-table under the still-invalid ``inter.hello`` key while reporting the op as APPLIED.
"""
toml_doc = tomlkit.loads(_INTERLEAVED_NESTED_MTHDS)
- applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="inter.hello", new_key="hello")])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_rename_op(key="inter.hello", new_key="hello")])
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]
# Pre-format dump: the dotted key is gone everywhere and BOTH the header and the nested
# sub-table now sit under the bare name.
@@ -204,7 +204,7 @@ class TestFixApplierStripNamespace:
def test_rename_applies_on_inline_pipe_table(self) -> None:
"""An inline ``pipe = {...}`` section (an ``InlineTable``) renames in place."""
toml_doc = tomlkit.loads(_INLINE_MTHDS)
- applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="inl.hello", new_key="hello")])
+ applications = apply_fix_ops(toml_doc=toml_doc, ops=[_rename_op(key="inl.hello", new_key="hello")])
assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]
dumped = _dumps(toml_doc)
assert '"inl.hello"' not in dumped
diff --git a/tests/unit/pipelex/pipeline/test_validation_render.py b/tests/unit/pipelex/pipeline/test_validation_render.py
index acfe42f28..b281dc690 100644
--- a/tests/unit/pipelex/pipeline/test_validation_render.py
+++ b/tests/unit/pipelex/pipeline/test_validation_render.py
@@ -196,7 +196,7 @@ class TestValidationRender:
def test_build_fix_command_echoes_library_dirs_and_signatures(self):
"""`build_fix_command` shell-joins the executable, path, each `-L` dir, and `--allow-signatures`."""
command = build_fix_command(
- "pipelex-agent",
+ executable="pipelex-agent",
bundle_path=Path("my bundle.mthds"),
library_dirs=[Path("libs/a"), Path("libs/b")],
allow_signatures=True,
@@ -207,6 +207,6 @@ class TestValidationRender:
def test_build_fix_command_minimal_has_no_flags(self):
"""With no library dirs and signatures disabled, only the bare `fix bundle <path>` is emitted."""
- command = build_fix_command("pipelex", bundle_path=Path("bundle.mthds"))
+ command = build_fix_command(executable="pipelex", bundle_path=Path("bundle.mthds"))
assert command == "pipelex fix bundle bundle.mthds"
diff --git a/tests/unit/pipelex/tools/misc/test_string_utils.py b/tests/unit/pipelex/tools/misc/test_string_utils.py
index a978be73a..70eddee36 100644
--- a/tests/unit/pipelex/tools/misc/test_string_utils.py
+++ b/tests/unit/pipelex/tools/misc/test_string_utils.py
@@ -274,7 +274,7 @@ def test_get_root_from_dotted_path(dotted_path: str, expected: str) -> None:
],
)
def test_pluralize(count: int, singular: str, plural: str | None, expected: str) -> None:
- assert pluralize(count, singular=singular, plural=plural) == expected
+ assert pluralize(count=count, singular=singular, plural=plural) == expected
@pytest.mark.parametrize(
@@ -288,7 +288,7 @@ def test_pluralize(count: int, singular: str, plural: str | None, expected: str)
],
)
def test_count_with_noun(count: int, singular: str, plural: str | None, expected: str) -> None:
- assert count_with_noun(count, singular=singular, plural=plural) == expected
+ assert count_with_noun(count=count, singular=singular, plural=plural) == expected
@pytest.mark.parametrize(
diff --git a/tests/unit/pipelex/tools/test_log_levels.py b/tests/unit/pipelex/tools/test_log_levels.py
index 548093dad..9c5bdc415 100644
--- a/tests/unit/pipelex/tools/test_log_levels.py
+++ b/tests/unit/pipelex/tools/test_log_levels.py
@@ -39,4 +39,4 @@ class TestLogLevels:
],
)
def test_from_int_converts_to_enum(self, raw_level: int, expected_enum: LogLevel) -> None:
- assert LogLevel.from_int(raw_level) == expected_enum
+ assert LogLevel.from_int(logging_level=raw_level) == expected_enum
diff --git a/wip/drift-contracts-design.md b/wip/drift-contracts-design.md
new file mode 100644
index 000000000..b5f8a24de
--- /dev/null
+++ b/wip/drift-contracts-design.md
@@ -0,0 +1,224 @@
+# Drift Contracts — deterministic review obligations between code, docs, and tests
+
+## Status
+
+Design accepted and implemented (engine in Phase 1, wiring/seeds/docs in Phase 2 — see `TODOS.md` for execution state and the engineering-review decisions that refined this text). The main refinement over the original proposal: digests are computed from the **git index** (staged blob OIDs via `git ls-files -s`), not from working-tree bytes — see "The validity rule" below.
+
+## Problem
+
+CLAUDE.md already states the policy ("document at every iteration", "keep the toml files and configs.py in sync", "keep specs and conformance in sync"), but prose policy is advisory: nothing tells a PR author — human or agent — *which* docs and tests are stale relative to *this* change, and nothing records that the check happened. The research brief proposes a deterministic traceability tool for this. This design adapts that proposal to what the Pipelex repo already has, and deliberately simplifies it in several places.
+
+## What the repo already has — and the actual gap
+
+The brief describes a greenfield. We are not greenfield. Three synchronization tiers already exist in some form:
+
+| Tier | Mechanism | Judgment needed | Status in this repo |
+|---|---|---|---|
+| **Derived** | Regenerate + diff: `check-config-sync`, `check-mthds-schema`, `check-gateway-models`, `check-rules`, `generate-error-pages` | None — output is a pure function of sources | **Exists**, wired into `make check` and CI |
+| **Linkage** | Referential integrity of declared cross-references: `conformance/scripts/check-spec-links.py` (spec `> Verified by:` ↔ test `pytest.mark.spec`) | None — links either resolve or they don't | **Exists** for the spec/conformance pair |
+| **Review** | "This code changed → these docs/tests must be *looked at* against this exact change, and the look must be recorded" | Yes — a human or agent must judge whether the prose/tests still hold | **Missing** — this is the gap |
+
+This framing yields the first design principle: **the new tool covers only the review tier**. Derived checks stay exactly where they are (Makefile + `pipelex-dev` commands); they are strictly better than review contracts because they need no judgment and can't be rubber-stamped. Whenever a review contract turns out to be mechanizable — the doc section could be generated, the sync could be checked structurally — the right move is to *delete the review contract and write a derived check*. The best review contract is one you eventually mechanize out of existence.
+
+## Core model
+
+A **drift contract** declares: "when these trigger files change, these review targets must be re-examined, and the examination must be acknowledged." The system has three pieces:
+
+- a **manifest** (`drift.toml`, repo root, human-authored) declaring contracts;
+- **ack state** (`.drift/acks/<contract-id>.toml`, one file per contract, tool-written, committed) recording the last fulfilled review;
+- a **CLI** (`pipelex-dev drift plan|check|ack`) that computes obligations, gates CI, and records acks.
+
+### The validity rule — one equality, no base ref
+
+This is the main deviation from the brief. The brief computes obligations from a git diff against a configurable base ref, then compares hashes against a review record. That drags in a whole class of problems: which base ref, how CI resolves it on stacked branches, force-pushes, merges from dev. None of it is needed. The validity rule is a single equality over tree content:
+
+> A contract is **fulfilled** iff the stored ack digest equals the digest recomputed from the current tree. Otherwise it is **open**.
+
+The digest for a contract is `sha256` over: the contract's own definition (canonically serialized — sorted keys and sorted glob lists, so reformatting or reordering `drift.toml` never churns the digest), plus the sorted list of `(path, content-hash)` pairs for every tracked file matching its trigger globs. Content hashes are the **staged blob OIDs from the git index**, read via a single `git ls-files -s` over the matched paths — matching and hashing share the same index source, hashing is filter-normalized (CRLF/smudge safe), and the digest covers exactly what lands in the commit. The cost of index semantics: trigger files must be `git add`-ed before `drift ack` to be covered (staged, not committed; other unstaged changes are fine).
+
+Properties that fall out of this rule:
+
+- **No base ref, no git diff, no timestamps.** `drift check` needs only the working tree and the committed ack files. It gives the same answer locally, in CI, on a rebase, on a squash-merge.
+- **The ack travels with the content.** Merging dev into a feature branch brings dev's trigger changes *and* dev's acks in the same tree, so digests match again automatically. A PR that changes triggers without re-acking fails; a PR that changes nothing passes; there is no "stale relative to what?" question.
+- **Editing a contract's definition forces a re-ack** (the definition is inside its own digest). Widening a trigger glob or adding a review target is itself a reviewable event.
+- **Adding a contract forces an initial review** — a new contract has no ack, so it is open until someone reviews the targets once and acks. Adoption is explicit, contract by contract.
+- **File deletion and rename are covered** — the matched-file set is part of the digest.
+- **Merges are backstopped by the digest, not by conflicts.** Two branches re-acking the same contract *can* conflict in its ack file, but a line-wise auto-merge can just as well splice the two acks into one neither branch reviewed — do not rely on the conflict. The guarantee is that `drift check` recomputes the digest over the merged tree, so a spliced or stale ack fails the check: the combined content was never reviewed as a whole. Resolution either way — finish the merge, review, re-run `drift ack` on the merged tree.
+
+Timestamps and reviewer identity are recorded for human audit, but they carry no validity semantics — exactly the brief's "hashes over timestamps" conclusion, taken one step further by removing the diff too.
+
+### Directionality
+
+Contracts are directional: triggers on one side, review targets on the other. Docs changing does not require re-reviewing code. Where a doc *is* the source of truth (spec-like pages), list it as a trigger of its own contract — symmetry is expressed by putting paths on both sides, not by a special mode.
+
+## Manifest format
+
+TOML, not YAML — this repo's idiom (`pipelex.toml`, `pyproject.toml`), and `plxt` already formats and lints TOML. Root-level `drift.toml` so it is as visible as the policy it enforces.
+
+```toml
+version = 1
+
+[contracts.config-docs]
+description = "User-facing configuration docs must track the config model and the shipped defaults."
+triggers = [
+ "pipelex/system/configuration/**/*.py",
+ "pipelex/pipelex.toml",
+]
+review = [
+ "docs/configuration/**/*.md",
+]
+verify_commands = ["make tb"]
+
+[contracts.cli-docs]
+description = "CLI docs and the agent-CLI contract doc must track the CLI surface."
+triggers = [
+ "pipelex/cli/**/*.py",
+]
+exclude = [
+ "pipelex/cli/dev_cli/**",
+]
+review = [
+ "docs/tools/cli/",
+ "pipelex/cli/agent_cli/CLAUDE.md",
+]
+verify_commands = []
+```
+
+Notes on the schema:
+
+- One flat `review` list instead of the brief's `docs:/tests:/examples:` sub-maps — paths self-describe their category, and the packet renderer can group by prefix if grouping ever helps. Fewer fields, less ceremony.
+- `triggers`, `exclude`, and `review` take globs or paths, matched against `git ls-files` output only (tracked files — untracked noise and `.gitignore` handling come free, and CI sees the same set).
+- `verify_commands` are commands `drift ack` runs before writing the ack (see below). They should be *targeted* (a specific pytest path, `make tb`), not the full suite — CI runs the full gates anyway.
+
+## Ack state format
+
+One file per contract under `.drift/acks/`, committed. Per-contract files keep unrelated PRs from conflicting on a shared state file; two branches re-acking the *same* contract may conflict, and either way the post-merge digest recompute is what catches an unreviewed combination (see above).
+
+```toml
+contract = "config-docs"
+digest = "sha256:4e03f2a1…"
+reviewed_by = "louis"
+reviewed_at = "2026-07-03T14:12:09Z"
+rationale = "Added the activity_queues setting; documented it in docs/configuration/config-technical/; make tb green. No other config-docs pages affected."
+
+[trigger_files]
+"pipelex/system/configuration/configs.py" = "blob:a1b2c3…"
+"pipelex/pipelex.toml" = "blob:99ffee…"
+```
+
+The per-file map exists for *messaging*, not validity: when a contract is open, `drift plan` diffs the stored map against the current tree to say precisely which trigger files were added, removed, or modified since the last ack — without any git-diff machinery. The previous `rationale` is also shown in the plan packet: the last reviewer's decision is exactly the context the next reviewer wants.
+
+Because acks are committed files, they surface in the PR diff: a reviewer sees the rationale next to the change it covers. That is the audit trail — no CI artifacts, no PR metadata, no bot comments.
+
+## Command surface
+
+Three commands, not the brief's four-plus — manifest validation folds into `check`, and the "review packet" is just the detailed form of `plan`.
+
+```bash
+pipelex-dev drift plan [CONTRACT] # what is open, why, and what to do — markdown by default
+pipelex-dev drift check # CI gate: pure, fast, no command execution
+pipelex-dev drift ack CONTRACT --rationale "…" # run verify_commands, then record the ack
+```
+
+Make wrappers follow the existing pattern: `drift-plan`, `drift-check`, `drift-ack`, with `drift-check` added to the `make check` aggregate.
+
+### `drift plan`
+
+Lists open contracts. Per the workspace surface-output conventions, the default output is Markdown — the primary consumer is an agent handed the packet — with `--format json` for software. For each open contract: description, which trigger files changed/appeared/vanished since the last ack, the review targets, the verify commands, and the previous rationale. With a `CONTRACT` argument, the full packet for that one contract.
+
+```markdown
+## Open contract: config-docs
+
+User-facing configuration docs must track the config model and the shipped defaults.
+
+**Trigger changes since last ack** (by louis, 2026-07-03, "Added the activity_queues setting…"):
+
+- modified: pipelex/system/configuration/configs.py
+- modified: pipelex/pipelex.toml
+
+**Review targets:**
+
+- docs/configuration/**/*.md
+
+**To fulfill:** review the targets against the trigger changes, update what is stale, then run
+`make drift-ack CONTRACT=config-docs RATIONALE="…"` (this runs: make tb).
+```
+
+### `drift check`
+
+The CI gate. Pure and fast (glob matching + digest comparison; it shells only to git plumbing — `ls-files` — and never executes verify commands): it validates that the manifest parses and is schema-valid, that every trigger glob matches at least one tracked file (dead globs are manifest rot — hard error), that every review target resolves to something that exists, that every contract has an ack, and that every ack digest matches the recomputed digest. Non-zero exit prints, per open contract, the same actionable block CI users get from the other check targets — ending with "run `make drift-plan`".
+
+`drift check` goes into `make check` and CI. It deliberately does **not** go into `make agent-check`: that target is the tight post-edit lint loop, and doc-review obligations belong at the end of a change, not after every edit. The failure message in CI is the agent's entry point.
+
+### `drift ack`
+
+Requires `--rationale`. Runs the contract's `verify_commands` first; any failure aborts the ack — no `--skip-verify` flag in the MVP, because every escape hatch here is a rubber-stamp invitation, and the real escape hatch already exists (acking with a rationale that says "no doc change needed" is legitimate and cheap). `reviewed_by` defaults from `git config user.name`, overridable with `--by` (agents pass their identity). Recomputes the digest from the **index** at ack time (stage trigger files with `git add` first — unstaged edits and untracked files are not covered, and the command warns when it sees one matching the triggers), writes the ack file; the ack then gets committed together with the change it covers. If files move again after the ack, CI's `drift check` catches the mismatch — so a clean tree is *not* required.
+
+## Decisions, mapped to the brief's open questions
+
+- **Review state inside the manifest or separate?** Separate. The manifest is human-authored and low-churn; acks are tool-written and change with every fulfilled review. One file per contract to keep any merge conflict scoped to the contract it concerns (the real merge safety net being the post-merge digest recompute).
+- **Acks in repo, CI artifacts, or PR metadata?** In repo. Anything outside the tree breaks the local-equals-CI property and hides the audit trail from the PR diff.
+- **Review identity for agents?** A plain string. Git already attributes the commit; `reviewed_by` is context, not authentication. Agents should pass something resolvable (e.g. model name or session URL).
+- **Should ack require a clean tree?** No. Agents ack mid-flow before committing; digest mismatch after later edits is caught by `check`.
+- **Human override label in CI?** No. The ack *is* the override — it costs one command and one honest sentence. A second bypass channel would only bypass the audit trail.
+- **Granularity for v1?** Files and globs only. Symbol-level triggers (griffe), markdown heading anchors, and pytest node-ID validation are all deferred — they add dependency weight and slow the check, and the seed contracts below don't need them.
+- **Generated docs as review targets?** Excluded. Generated artifacts (`docs/errors/`, `derived/mthds_schema.json`, gateway model docs) belong to the derived tier and must never appear in `review` lists — reviewing generator *output* is how you end up editing generated files, which we already forbid.
+- **Infer candidate contracts from coverage/imports?** Not in scope. Manifest growth should follow pain, not tooling enthusiasm.
+
+## What this deliberately does not do
+
+Unchanged from the brief, and worth restating because they bound the tool's promises:
+
+- It does not prove docs are semantically correct — it proves the declared reviewer looked, at this exact content, and said so on the record.
+- It does not trace the whole repo. Contracts are added one at a time, where staleness has actually hurt.
+- It does not replace the CLAUDE.md documentation culture; it enforces the culture's floor on the few surfaces where silent drift is most expensive.
+
+And one addition: it does not handle cross-repo contracts. The spec/conformance pair spans the workspace root and the `conformance/` repo and already has a purpose-built checker (`check-spec-links.py`) doing linkage-tier validation with in-file markers; `drift` is per-repo and should not absorb it. If cross-repo review contracts become pressing, that is a separate design.
+
+## Failure modes, honestly
+
+- **Rubber-stamping.** The tool cannot force a real review. Mitigations: mandatory rationale, PR-visible ack diffs, verify commands at ack time, and — most importantly — keeping the contract count low enough that each open contract is a genuine event rather than background noise. If we observe reflexive acks ("docs fine" on every PR), the contract is mis-scoped: either narrow its triggers or mechanize it into a derived check.
+- **Review fatigue from over-broad triggers.** `pipelex/cli/**` will open the cli-docs contract on pure refactors. Acceptable at first (the ack costs a sentence); if it grates, narrow triggers to the surface-defining modules rather than adding bypass mechanisms.
+- **Manifest rot.** Dead globs and vanished review targets are hard `check` failures, so rot is loud, not silent.
+- **Ack-file merge conflicts.** Scoped per contract; possible but not guaranteed (a line-wise auto-merge can splice two acks silently). The real safety net is the post-merge digest recompute in `drift check`. Documented resolution: merge, review, then re-ack.
+- **Line-ending/filter edge cases.** Resolved by construction: digests use staged blob OIDs from the index, which are filter-normalized, so a smudge/clean filter or CRLF checkout cannot make local and CI hashes differ.
+
+## Seed contracts
+
+Start with three, all in the `pipelex` repo, all places where prose has already drifted or plausibly will (exact target lists to be settled at implementation time against the current docs tree):
+
+- **config-docs** — triggers: `pipelex/system/configuration/**/*.py`, `pipelex/pipelex.toml`; review: `docs/configuration/**`; verify: `make tb`. The structural toml↔configs.py sync is already mechanized by `check-config-sync` and `make tb`; this contract covers what those cannot — the prose.
+- **cli-docs** — triggers: `pipelex/cli/**/*.py` excluding `dev_cli/`; review: `docs/tools/cli/`, `pipelex/cli/agent_cli/CLAUDE.md`. The agent-CLI output-format contract doc is load-bearing for the whole workspace's surface conventions.
+- **keyword-only-convention** — triggers: `pipelex/cli/dev_cli/commands/keyword_only_guard.py`; review: `docs/contribute/keyword-only-arguments.md`. Small, sharp, and the doc is explicitly the convention's specification.
+
+Candidates deliberately *not* seeded: anything under `wip/` (not release-facing), generated pages (derived tier), broad feature docs (too noisy to start), spec/conformance (covered, cross-repo).
+
+## Rollout plan
+
+### Phase 1 — engine
+
+Implement `drift plan|check|ack` as `pipelex-dev` commands (`pipelex/cli/dev_cli/commands/drift_cmd.py` or a small sub-package), with manifest parsing, digest computation, ack read/write, and unit tests covering: digest stability, contract-definition-in-digest, added/removed/modified trigger reporting, dead-glob and missing-target failures, ack-then-edit invalidation.
+
+**Checkpoint 1:** engine green under `make agent-test`, no Makefile or CI wiring yet. Natural handoff — the remaining work is integration and manifest authoring, a fresh session can pick it up from the tests.
+
+### Phase 2 — wiring and seeds
+
+Add the `drift-plan` / `drift-check` / `drift-ack` Make targets, put `drift-check` into the `make check` aggregate (and thereby CI), author `drift.toml` with the three seed contracts, perform the three initial reviews for real (not rubber-stamped — this is the first dogfood), and commit the initial acks. Document the system: a page under `docs/contribute/` explaining contracts, the ack workflow, and the merge-conflict resolution rule.
+
+**Checkpoint 2:** CI enforcing, seeds live. Then **stop and dogfood for a few weeks of normal PRs** before growing the manifest. The open question that only usage can answer: is the ack friction proportionate to the staleness it catches?
+
+### Phase 3 — agent ergonomics (after dogfooding verdict)
+
+Polish the `plan` packet for agent consumption, add `--format json` for software consumers, and teach the workflow to agents where they already look: a short section in the contributor docs and, if warranted, the failure-message text itself is usually enough — agents follow actionable CI errors well. Consider a repo-local skill only if the raw commands prove insufficient.
+
+### Deferred
+
+- Symbol-level triggers via griffe; markdown-anchor targets; pytest node-ID validation via `--collect-only`.
+- Unifying the derived-tier checks into `drift plan` output as read-only `kind = "derived"` entries, so one command shows the full sync map. Nice-to-have; duplicates Makefile wiring today.
+- Cross-repo contracts (workspace-root specs, conformance, downstream consumers).
+- Semantic assistance: `cocode`'s doc/code drift proofreading could consume the plan packet as its work list — the deterministic layer decides *what* to look at, cocode helps judge *whether* it drifted.
+- Extraction into a standalone tool for the other workspace repos, if the pipelex-repo dogfood earns it.
+
+## Bottom line
+
+Keep the brief's core inversion — a deterministic tool decides which reviews are owed and whether they were fulfilled; agents and humans merely fulfill them — but strip the mechanism to one equality: *ack digest == current digest, computed from tree content alone*. No base refs, no timestamps, no diff plumbing, no separate validate command, no override channel. Three commands, a TOML manifest, per-contract committed acks, three seed contracts, and a hard rule that anything mechanizable becomes a derived check instead. If the dogfood shows the acks catching real staleness at tolerable friction, grow the manifest; if it shows ceremony, we will have learned that cheaply.
diff --git a/wip/drift-contracts/dogfood-log.md b/wip/drift-contracts/dogfood-log.md
new file mode 100644
index 000000000..865b01b3f
--- /dev/null
+++ b/wip/drift-contracts/dogfood-log.md
@@ -0,0 +1,6 @@
+# Drift-contracts dogfood log
+
+One entry per ack. Verdicts: **real-catch** (the review found actual staleness), **clean-pass** (genuinely reviewed, nothing was stale), **friction** (the contract opened on changes that could not have affected the targets — candidate for narrowing or mechanizing).
+
+- **2026-07-10 · keyword-only-convention · real-catch** — the guard gained the subject-grant registry (new violation kinds, literal-subject ban, symmetric staleness); the convention doc was materially stale and was rewritten as part of the same change — exactly the coupling this contract exists to enforce.
+- **2026-07-10 · cli-docs · clean-pass** — the keyword-only sweep touched many pipelex/cli files (kwonly'd internal signatures, two escape hatches, call-site keywords); reviewed docs/tools/cli/ and the agent-CLI CLAUDE.md — no command, flag, or output changed, both targets stay accurate.
diff --git a/wip/drift-contracts/pr-1040-review-notes.md b/wip/drift-contracts/pr-1040-review-notes.md
new file mode 100644
index 000000000..36f3cc2c9
--- /dev/null
+++ b/wip/drift-contracts/pr-1040-review-notes.md
@@ -0,0 +1,23 @@
+# PR #1040 review notes — deferred drift-tooling findings
+
+Two codex findings on `pipelex/cli/dev_cli/commands/drift/drift_cmd.py` from the PR #1040 review pass. Both describe real code behavior (verified against the code), but neither is worth hardening now: the drift tool is an internal dev CLI, CI backstops the first, and the second is a documented design choice with a narrow failure mode. Captured here so the candidate fixes aren't lost.
+
+## A1 — `drift ack` does not stage the ack file, so local `drift check` can false-green
+
+Reporter: codex (P2). Thread: <https://github.com/Pipelex/pipelex/pull/1040#discussion_r3564484373>
+
+`drift check` hashes trigger files from the **git index** but loads ack files from the **working tree** (`load_all_acks` globs `.drift/acks/*.toml` on disk). `drift ack` writes the ack file without staging it. So right after an ack, the local gate passes even though the ack blob is not in the commit being built — if the developer forgets to `git add` the ack, the false green only flips red in CI (fresh checkout: `MISSING_ACK` / `DIGEST_MISMATCH`).
+
+**Why deferred:** the false green is purely local; CI deterministically catches anything that lands. The doc already instructs committing the ack together with the change. Dev-loop papercut, not a correctness hole.
+
+**Recorded candidate fix (clean, low-risk):** have `drift ack` auto-stage the ack file it writes (`git add .drift/acks/<id>.toml` after `save_ack`). The ack is a tool-written artifact, never hand-edited, so auto-staging is safe; it makes the local gate honest (the ack lands in the same index the check reads) and removes the forgot-to-add footgun. Note: the alternative "read acks from the index" would report `MISSING_ACK` immediately after a successful ack unless combined with auto-staging, so auto-staging is the load-bearing part. Test approach: temp-git-repo test asserting the ack path appears in `git diff --cached --name-only` after `drift ack`.
+
+## A2 — verify commands run against the working tree while the ack digest covers staged blobs
+
+Reporter: codex (P2). Thread: <https://github.com/Pipelex/pipelex/pull/1040#discussion_r3564484375>
+
+In `drift_ack_cmd`, verify commands run against the working tree, then the digest is computed from staged blob OIDs, then `_warn_uncovered_working_tree` warns, then the ack is written unconditionally. If a trigger file has staged content plus extra unstaged edits, the ack certifies staged content that the verify commands never ran on exactly.
+
+**Why deferred:** the warn-not-fail behavior is deliberate and documented (`docs/contribute/drift-contracts.md` — the digest is index-based by design, and `drift ack` warns on matching unstaged/untracked files). The failure mode is narrow: stage a trigger, edit it further without re-staging, ack, *and* have the staged-vs-tree delta flip a verify result. Codex's proposed blanket fail-on-any-unstaged-trigger contradicts the documented index-based philosophy and would add friction for the many contracts with no `verify_commands` at all.
+
+**Recorded candidate fix (if ever needed):** escalate warn→fail only when the contract has `verify_commands` AND a matching trigger file is unstaged/untracked — that is the one case where the verify guarantee is meaningfully weakened. Test approach: temp-repo test asserting `drift ack` raises `DriftAckError` for a verify-command contract with a dirty matching trigger, while still only warning for a no-verify contract.
diff --git a/wip/kick-off-drift-hunt.md b/wip/kick-off-drift-hunt.md
new file mode 100644
index 000000000..92907875b
--- /dev/null
+++ b/wip/kick-off-drift-hunt.md
@@ -0,0 +1,86 @@
+# Drift Hunt — one-off full review of the hand-written docs
+
+A campaign, not a feature: sweep every hand-written doc page for code↔doc drift, fix what's stale, and come out with per-section defect-density evidence. The drift-contracts system (see [wip/drift-contracts-design.md](drift-contracts-design.md), `docs/contribute/drift-contracts.md`) enforces the floor *going forward*; this hunt backfills the floor once. It was deliberately scoped out of the tool — it runs as a project instead.
+
+## Cold-start context (update at every checkpoint)
+
+- **Status:** PLAN WRITTEN — nothing started. Next = Stage 0.
+- **Branch / worktree:** `docs/Update` in the `_docs` worktree (treat as repo root). Stage 2 fix batches may land as their own PRs — see Decision D4.
+- **Working artifacts:** everything the hunt produces (pre-screen script, suspect list, findings) lives under `wip/drift-hunt/`.
+- **Decisions taken:** D1–D6 below.
+- **Open questions:** none blocking.
+
+## Decisions
+
+- **D1 — cocode is out of scope.** Not ready for this task (user call, 2026-07-05). The whole hunt runs on the pre-screen script + Claude agent fan-outs; do not reach for cocode even for sub-steps.
+- **D2 — scope = hand-written pages under `docs/`.** Excluded as *generated*: `docs/errors/` (error reference pages, regenerated by `make gep`) and the generated gateway-models doc(s). Excluded as *freshly reviewed*: `docs/configuration/` and the CLI docs (`docs/tools/cli/` + `pipelex/cli/agent_cli/CLAUDE.md`) — they got a genuine review days ago as the drift-contracts seed acks; re-sweeping them now would measure nothing. Everything else under `docs/` is in: building-methods, features, cookbook, under-the-hood, tools (non-CLI), advanced, reliability, get-started, contribute, setup, viewpoint, index/license.
+- **D3 — cookbook ground truth is a sibling repo.** `docs/cookbook/` pages reference examples that do NOT live in this codebase — they live in `../pipelex-cookbook`. Any agent reviewing a cookbook page must verify claims against `../pipelex-cookbook` (read-only), not conclude "referenced example missing" from this tree. The pre-screen's path-existence check must special-case `docs/cookbook/` the same way.
+- **D4 — fixes land in reviewable batches.** One commit per docs section at minimum; separate PRs per section if a batch grows beyond comfortable review size. Default base: `dev`.
+- **D5 — no manifest growth during the hunt.** The drift-contracts dogfood freeze stays in force: the hunt produces *evidence* for which sections might earn a contract later; it does not add contracts to `drift.toml`.
+- **D6 — findings must survive adversarial verification before anything is fixed.** The failure mode of a big sweep is an agent confidently "correcting" a doc that was right. No finding is acted on unless a second, independent agent confirms it against the code with `file:line` evidence. Fix agents re-verify at fix time; a finding that doesn't hold up gets recorded as rejected, not silently dropped.
+
+## What "drift" means here (and what it doesn't)
+
+In scope per page: statements the code can contradict — commands, flags, config keys, defaults, file paths, API/class/function names, described behaviors and sequences, code snippets that should run or parse. Out of scope: editorial quality, tone, structure, SEO, completeness wishes ("this page should also cover X"). This is a drift hunt, not a rewrite; the standing repo rules apply to fixes (docs = current reality, no hardcoded counts, MkDocs conventions).
+
+---
+
+## Stage 0 — inventory + mechanical pre-screen
+
+Deterministic checks that need no judgment, to make the semantic pass sharper and cheaper. The seed-ack dogfood showed this class is rich: several of its real catches (dead config section, phantom CLI flag, dead config field) were mechanically detectable.
+
+- [ ] Build the inventory: every in-scope `.md` page (per D2), grouped by section, committed as `wip/drift-hunt/inventory.md` with a page count per section — this is the denominator for defect density later.
+- [ ] Write the pre-screen script at `wip/drift-hunt/prescreen.py` (throwaway quality is fine — it's campaign tooling, not product; keep it self-contained, stdlib + repo venv only). Checks, each producing `(page, claim, verdict, evidence)` rows:
+ - Referenced repo file paths exist in the tree (special-case `docs/cookbook/` → resolve against `../pipelex-cookbook`, per D3).
+ - Mentioned config keys exist in `pipelex/pipelex.toml` / the `configs.py` model tree.
+ - Mentioned `pipelex` / `pipelex-dev` CLI commands and flags exist in the actual `--help` surfaces.
+ - Fenced `toml` blocks parse; fenced `python` blocks compile (`ast.parse`).
+ - Internal doc links resolve (complementing, not re-implementing, the mkdocs strict build).
+- [ ] Run it; triage the raw hits into `wip/drift-hunt/suspects.md` — per section: confirmed-mechanical defects vs needs-judgment flags vs false positives (note false-positive patterns; they tune Stage 1 prompts).
+- [ ] Fix the confirmed mechanical defects immediately (they need no Stage 1) — one commit, gates: mkdocs strict build green.
+
+### CHECKPOINT 0 — STOP (suspect list in hand)
+
+Commit Stage 0 outputs + fixes; update Cold-start context. **User reviews `suspects.md` and the false-positive patterns, then decides the Stage 1 shape:** full fan-out over all in-scope sections vs worst-sections-first. Also sanity-check Stage 1's cost estimate against the observed page sizes before committing the fleet.
+
+---
+
+## Stage 1 — semantic review fan-out (the judgment work)
+
+A multi-agent Workflow over the in-scope pages — requires the user's explicit go-ahead at Checkpoint 0 (fleet-scale token spend, plausibly on the order of millions of tokens; estimate concretely at Checkpoint 0).
+
+- [ ] Per page, a review agent: read the page, extract its checkable claims, verify each against the current code (cookbook pages → `../pipelex-cookbook`, per D3), report findings with severity (`breaks-a-user` / `wrong` / `misleading` / `stale-detail`) and `file:line` evidence for both the doc claim and the contradicting code. Seed each agent with the page's Stage 0 suspect rows.
+- [ ] Adversarial verify pass (D6): every finding independently re-derived by a verifier agent prompted to refute it; only confirmed findings survive. Run as a pipeline (page-review → verify per finding), not a barrier — sections should flow.
+- [ ] Aggregate into `wip/drift-hunt/findings/<section>.md` (one file per section, findings ranked by severity) plus `wip/drift-hunt/findings/SUMMARY.md`: per-section counts, defect density (findings / pages), and the rejected-findings list with reasons.
+- [ ] Log any observations relevant to the drift-contracts dogfood (e.g. "this section's drift is all mechanically detectable → derived-check candidate, not a contract") — they feed the Phase 3 verdict, per D5.
+
+### CHECKPOINT 1 — STOP (findings, no fixes yet)
+
+Commit findings; update Cold-start context. **Triage with the user:** confirm severity ranking, kill anything that smells like editorial creep (out of scope here), agree the fix order (default: by severity, then by section). This is a natural session handoff — Stage 2 needs no Stage 1 context beyond the findings files.
+
+---
+
+## Stage 2 — fix in batches
+
+- [ ] Fix per section, working from `findings/<section>.md`, highest severity first. Each fix re-verified against the code at fix time (D6) — the finding is the pointer, the code is the authority.
+- [ ] One commit per section; split into separate PRs against `dev` if a batch outgrows comfortable review (D4). Gates per batch: mkdocs strict build + `make check`.
+- [ ] Note: fixing docs does NOT reopen drift contracts (docs are review targets, not triggers — only trigger files feed the ack digest). No ack churn expected; if a fix somehow touches a trigger file, resolve it with the `drift-review` skill as usual.
+- [ ] Mark resolved findings in the findings files as batches land (mark, don't delete — the record is the campaign's audit trail until the final checkpoint).
+
+### CHECKPOINT 2 — STOP (campaign close-out)
+
+- [ ] All batches landed; mkdocs strict + `make check` green on the final state.
+- [ ] Write the close-out in `findings/SUMMARY.md`: defect density per section, top defect classes, and the evidence-based shortlist of sections that might earn a drift contract (or a derived check) after the dogfood period — hand that shortlist to the drift-contracts Phase 3 verdict (TODOS.md), per D5.
+- [ ] Prune `wip/drift-hunt/`: keep SUMMARY + inventory as the record; the per-section findings files and prescreen script can go once everything is landed.
+- [ ] Update this file's Cold-start context to DONE.
+
+---
+
+## Out of scope (explicit)
+
+- cocode, in any role (D1).
+- Growing `drift.toml` (D5 — evidence now, contracts later).
+- Editorial/style/structure rewrites, new content, SEO.
+- Generated docs (`docs/errors/`, gateway models) — fix the generator if one of those is wrong.
+- `docs/configuration/` + CLI docs (just reviewed via seed acks) — unless a Stage 1 finding elsewhere points back into them.
+- Other repos' docs (the hunt reads `../pipelex-cookbook` as ground truth but does not fix it; cookbook-repo defects found along the way get listed in SUMMARY.md as a handoff).
diff --git a/wip/subject-grants/demoted-public-surfaces.md b/wip/subject-grants/demoted-public-surfaces.md
new file mode 100644
index 000000000..d13c371b3
--- /dev/null
+++ b/wip/subject-grants/demoted-public-surfaces.md
@@ -0,0 +1,43 @@
+# Demoted public surfaces — release-wave cross-repo sweep handoff
+
+The subject-grant review demoted every positional first parameter that failed the grant rubric to keyword-only (see `docs/contribute/keyword-only-arguments.md`). No backward compatibility: any external consumer calling these surfaces positionally — or subclassing them with positional signatures — breaks when the release ships. This is the inventory for the release-gated cross-repo sweep; the consumers to check are `pipelex-api`, `pipelex-worker`, the private `pipelex-temporal` plugin, `pipelex-cookbook`, `cocode`, `pipelex-mistralai-workflows`, and any starter/template code.
+
+## Runtime / execution surfaces
+
+- `pipelex.core.pipes.pipe_abstract.PipeAbstract` run family (`run_pipe`, `live_run_pipe`, `dry_run_pipe`, `validate_before_run`, `validate_after_run`, `needed_inputs`) — `job_metadata` / `visited_pipes` now keyword-only; external code subclassing or invoking pipes positionally breaks.
+- `pipelex.runtime_bridge.bootstrap.ensure_pipelex_booted` (`config_overrides`) — runtime_bridge is consumed by pipelex-api / pipelex-worker; positional callers break.
+- `pipelex.pipeline.pipeline_run_setup.pipeline_run_setup` (`execution_config`) and `pipelex.pipeline.pipeline_manager_abstract.add_new_pipeline` (`pipe_code`).
+- `pipelex.libraries.library_manager_abstract.LibraryManagerAbstract` load family (`load_libraries`, `load_from_blueprints`, `load_from_crate`, …) — `library_id` now keyword-only.
+- `pipelex.libraries.concept.concept_library_abstract.ConceptLibraryAbstract.is_compatible` / `ConceptLibrary.is_compatible` (`tested_concept`).
+- `pipelex.graph.graph_tracer_protocol.GraphTracerProtocol.setup` (`graph_id`) + `GraphTracer.setup` / `GraphTracerNoOp.setup` — external tracer implementations must match.
+
+## Content / rendering surfaces
+
+- `pipelex.core.stuffs.stuff_content.StuffContent.rendered_for_prompt` / `rendered_for_template_async` (`text_format`) and `pretty_print_content` (`title`) — public content API; positional `TextFormat` callers break.
+- `pipelex.tools.jinja2.text_format_renderable.TextFormatRenderable.rendered_for_template_async` (`text_format`) — `@runtime_checkable` protocol; external implementers and positional callers break.
+- `pipelex.tools.jinja2.image_renderable.ImageRenderable.render_with_images` (`registry`) — protocol + all content-class implementations.
+- `pipelex.cogt.image.prompt_image_factory.PromptImageFactory.make_prompt_image` (`uri`) and `pipelex.cogt.document.prompt_document_factory.PromptDocumentFactory.make_prompt_document` (`uri`) — public content factories; positional-`uri` callers (cookbook, cocode, app) break.
+
+## Model / backend / reporting surfaces
+
+- `pipelex.cogt.models.model_manager_abstract.ModelManagerAbstract.setup` + `ModelManager.setup` (`secrets_provider`) and `pipelex.cogt.model_backends.backend_library.InferenceBackendLibrary.load` (`secrets_provider`).
+- `pipelex.cogt.llm.llm_setting.LLMSettingChoices.make_completed_with_defaults` (`for_text`) and `pipelex.cogt.model_routing.routing_profile.RoutingProfile.get_backend_match_for_model` (`enabled_backends`).
+- `pipelex.reporting` protocol methods `set_event_log` / `clear_event_log` (`context_key`) — external `ReportingProtocol` implementations must match.
+- `pipelex.system.telemetry.*.is_custom_portkey_logging_enabled` / `is_pipelex_gateway_portkey_logging_enabled` (`is_debug_configured`).
+- `pipelex.plugins.anthropic.anthropic_factory.AnthropicFactory.calculate_safe_max_tokens_for_timeout` (`timeout_seconds`).
+- `pipelex.tools.aws.aws_config.AwsConfig.get_aws_access_keys_with_method` (`api_key_method`).
+
+## Builder / CLI-adjacent importable surfaces
+
+- `pipelex.builder.operations` entry points `build_inputs_for_pipe` (`pipe_code`), `list_models` (`categories`), `validate_all` (`library_dirs`) — agent-CLI/MCP plumbing, but importable.
+- `pipelex.cli.installed_methods.discover_installed_methods` (`include_global`) and `pipelex.cli.commands.init.config_files.init_config` (`reset`).
+- `pipelex.hub.PipelexHub.set_dry_run_forced` (`is_forced`).
+
+## Tools helpers (literal sweep)
+
+- `pipelex.tools.misc.string_utils.pluralize` / `count_with_noun` (`count`).
+- `pipelex.tools.log.log.Log.set_level_by_int` (`level_int`) and `pipelex.tools.log.log_levels.LogLevel.from_int` (`logging_level`).
+- `pipelex.tools.misc.pretty.PrettyPrinter.pretty_width` (`width`).
+- `pipelex.errors.error_pages_generator.generate_error_pages` (`output_dir`) — dev tooling, listed for completeness.
+
+CLI-internal helpers (doctor/show/update/validate `*_cmd` delegates, console UI builders, plugin-internal `list_*_models` / discovery register helpers, gateway `_call_relay`) were also demoted but are not part of the importable public API — they live in the commit diffs, not here.
diff --git a/wip/subject-grants/regrind-after-dev-merge.md b/wip/subject-grants/regrind-after-dev-merge.md
new file mode 100644
index 000000000..bf01e3c05
--- /dev/null
+++ b/wip/subject-grants/regrind-after-dev-merge.md
@@ -0,0 +1,45 @@
+# Regrind record — redoing the Phase-4 grind after the dev merge (Phase M step 5)
+
+The `feature/Signatures` branch was rewound to the pre-grind mechanism commit and `origin/dev` merged there, which reset every grant to `seeded = true` (plus dev's new wave). This record documents how the regrind was executed so its verdicts are auditable against the archived first grind (tag `subject-grants-grind-archive`, tip `2ebf3f293` — checkpoint-2 and checkpoint-3 review records live in that branch's `wip/subject-grants/`).
+
+## Method — classification against the archive
+
+An AST-based classifier compared, per seeded key, the def's signature across three trees: the pre-grind base (`9f5bd54a3`), the archived grind tip, and the merged working tree. Buckets:
+
+| Bucket | Count | Treatment |
+|---|---|---|
+| PORT | 1,470 | Archive KEPT it and dev left the def's signature unchanged → archive rationale ported verbatim (wave A) |
+| REDO_DEMOTE | 148 | Archive demoted it and dev left the def unchanged → the archive's demoted header spliced back over the working-tree def, byte-for-byte (wave B) |
+| REVIEW_NEW | 285 | Dev-new def → genuinely reviewed against the rubric + case-law (wave C) |
+| REVIEW_CHANGED | 24 | Archive had a verdict but dev changed the signature → genuinely re-reviewed (wave C); archive-kept rationales re-used where the verdict stood |
+
+Wave B also re-applied the archive's demotes on `@override`/Protocol implementers (carve-outs, so registry-invisible), recovered pyright-guided; call sites re-labelled with the keyword mechanically.
+
+## Wave C verdicts (the genuine review): 268 kept, 41 demoted
+
+Demote families applied (all existing case-law): console/sink-first params (`_print_*`/`_display_*`/`_render_fix_result(console, …)`), key+payload targets (`apply_fix_ops(toml_doc, *, ops)`, `resolve_field(field_name, *, blueprint)`, `add_stuff_spec`, `normalize_typeless_signature_section`), optional-selector-among-alternatives (`inputs_core(pipe_code=None, …)` family, matching the archive's `build_inputs_for_pipe` demote), config-first (`pipeline_run_setup(execution_config)` — literally the case-law example), lookup-container/scope (`_default_main_pipe_ref(crate)`, `find_default_inputs_file(directory)`, `_iter_stampable_files(directory)`, `_resolve_table(toml_doc, …)`), accumulator-sink (`_add_native_ref(referenced, …)`), same-type pair (`_file_state_matches(current_snapshot, *, expected_snapshot)`), bare-literal call sites (`_text_field("The text", …)`, `build_fix_command("pipelex", …)`), job_metadata run-family (`PipeAbstract._make_lifted_output`), derived-value registry lookup (`_custom_import_statement`, matching the demoted `_get_structure_class_import`).
+
+Protocol parity handled: demoting `GraphTracerProtocol.setup(graph_id)` demoted `GraphTracer.setup` and `GraphTracerNoOp.setup` in the same commit (the manager's `open_tracer(graph_id)` stays granted — entity-keyed, per the archive).
+
+Keeps of note: the codegen emitters/resolvers/parsers (single-operand transformations and noun-named derivations), the `markdown_renderer` formatters and provider factories (positional-`Callable` protocol), `plugin.register(registrar)` (duck-typed third-party dispatch invoked positionally by discovery), the InputShaper `_shape_*` family (the raw value is the operand), WorkingMemory getters/recorders (entity-keyed / verb-object).
+
+Judgment calls worth spot-checking: the record-vs-registry discriminator — extraction from a single record analyzed (`_extract_wrapped_*_error(error)`, `_pending_signatures_from_validation_result`) KEEPS, while lookup of one entry in a keyed container (`_get_raw_main_absence(working_memory_raw)`, `_default_main_pipe_ref(crate)`) DEMOTES; and `_validation_category_header(category)` / `_markdown_category_header(category)` kept as noun-named derivations (pure match/case over the operand) rather than demoted as mode-selectors.
+
+## Gates
+
+Each wave: `make agent-check` green. Full `make agent-test` green after wave B and after wave C (both waves demote framework-adjacent protocol members). `--report`: seeded remaining 0.
+
+## Checkpoint review (Phase M step 6) — 3-agent fan-out over the merge+grind range
+
+Three fresh no-context Sonnet agents reviewed the `d58cd847b..` grind commits, same shape as checkpoint 3. Findings and triage:
+
+- **Code-correctness** — one real defect: `PipeAbstract.validate_before_run` had lost its `-> InputPresenceScan` return annotation in the wave-B splice (the archive grind itself had dropped it, and the byte-for-byte splice faithfully copied the loss). Restored. Everything else clean: no positional call-site breakage, protocol/implementer pairs in lockstep, no framework callbacks wrongly keyword-only'd.
+- **Mechanical-rewrite-safety** — independent AST audit over all demoted defs: zero parameter/default/decorator/docstring losses, zero missed call sites across the tree, registry consistent with the demoted set. Its only confirmed finding was the same annotation loss.
+- **Grant-judgment** — audited rationale quality and same-file consistency (including a mechanical sibling-diff sweep). Verdict: regrind well-applied; case-law families (console-first, key+payload, lookup-container, entity-keyed getters vs payload setters, positional-Callable protocols, two-candidate demotes) all held up on inspection. Three high-confidence inconsistencies, all triaged as real misses and **demoted** (def + call sites + registry entry removed):
+ - `DeliveryExecutor._get_raw_main_stuff_dict(working_memory_raw)` — structurally identical to its sibling `_get_raw_main_absence` (demoted): a keyed-container lookup, the record's own stated DEMOTE discriminator.
+ - `check_keyword_only_cmd.py::_print_violation_lines(violations)` — three same-shape siblings in the same file (`_print_failure_panel`, `_print_failure_quiet`, `_print_violations_by_kind`) were all demoted; "when in doubt → keyword-only" settles the 3-of-4 split.
+ - `kit_cmd.py::_cleanup_other_targets(repo_root)` — `repo_root` is a scope param, not the verb's object (the objects are the keyword params); the lone call site already passed it by keyword.
+
+Post-triage: `make agent-check` green; delivery-executor tests green. Grants total 1,743.
+
+The post-triage full-suite run also caught one failure class the reviews missed: dev-new unit tests stubbing `render_stuff_spec` with mocks asserted the pre-demote positional call (`assert_called_once_with(JSON)`). Mock assertions are invisible to pyright, so the wave-B pyright-guided call-site fixer never flagged them. Rewrote the assertions to the keyword form (`output_format=...`); the `side_effect` usages are exception instances, unaffected. This is a known blind spot of mechanical demotes: mock-based tests only fail at runtime — the full test suite is the safety net.