Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
feature/Runtime-events-always-carry · L-260923-05863c (#1236)
Thomas Hebrard4229087dff34
diff --git a/.drift/acks/pipelex-kernel-docs.toml b/.drift/acks/pipelex-kernel-docs.tomlindex f1b31220b..e90dcc010 100644--- a/.drift/acks/pipelex-kernel-docs.toml+++ b/.drift/acks/pipelex-kernel-docs.toml@@ -1,8 +1,8 @@contract = "pipelex-kernel-docs"-digest = "sha256:38318fc12f2f5c8bc54359c7b41dddf7c81e3cbddc177a9c8c9f3bf087b525c5"-reviewed_by = "Louis Choquel"-reviewed_at = "2026-09-22T11:22:02Z"-rationale = "PipelexKernel.make gained an optional analytics_groups parameter, the opaque host-supplied group mapping, carried onto RunMetadata beside user_id and storage_scope. The kernel doc's run-scoped-state bullet already listed analytics_groups among what run_metadata holds and now also says the host supplies it at make time, which is the seam a multi-tenant embedder needs. The parameter is optional and defaults to an empty mapping, so the doc's two make examples stay correct unchanged."+digest = "sha256:c9de05f94227aa7679111cf720166b97249792b096a54bdcdc2ecac99168b860"+reviewed_by = "thomashebrard"+reviewed_at = "2026-09-24T09:00:51Z"+rationale = "PipelexKernel.make renamed its analytics_groups parameter to extras (opaque host-supplied labels). The kernel doc's run-scoped-state bullet already names extras on run_metadata and says the host supplies it at make time; the two make examples pass neither and stay correct."[trigger_files]"pipelex/kernel/__init__.py" = "blob:c4f1b0fe2ccc17db9110733f71b612f4ac1ba4ce"@@ -20,7 +20,7 @@ rationale = "PipelexKernel.make gained an optional analytics_groups parameter, t"pipelex/kernel/llm_prompt_content.py" = "blob:82c34283dacd2bfd9a2c263915e744736d399875""pipelex/kernel/llm_results.py" = "blob:6e3b8a2878b5bb284ece5fac10262fb59ac2029d""pipelex/kernel/memory_ops.py" = "blob:f6a5745e804ac08f19c70f1beb1f78baf50d51cd"-"pipelex/kernel/pipelex_kernel.py" = "blob:622c379bd9d1bf0041b192275b5aa3b37a7a5ea5"+"pipelex/kernel/pipelex_kernel.py" = "blob:70d0cca4c8c009103e139594dc938fa0de287478""pipelex/kernel/prompt_references.py" = "blob:03ec9ef67ae84f141d072ca2d2c3ef888549ccc0""pipelex/kernel/search_ops.py" = "blob:ed0a8c7953aca1e38de852d0ddef11731b819539""pipelex/kernel/search_results.py" = "blob:101b70dc96cc5ee1721c9f6b1cb725a5ca78ff70"diff --git a/.test_durations b/.test_durationsindex da3c906f2..a851ab339 100644--- a/.test_durations+++ b/.test_durations@@ -676,10 +676,10 @@"tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py::TestPipelineRunIdResubmission::test_setup_failure_frees_entry_even_when_tracer_teardown_raises": 0.6068,"tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py::TestPipelineRunIdResubmission::test_setup_failure_self_cleans_and_same_id_resubmits": 0.391,"tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py::TestPipelineRunIdResubmission::test_success_clears_registry_entry": 2.1802,- "tests/integration/pipelex/pipeline/test_pipeline_run_setup_analytics_groups.py::TestPipelineRunSetupAnalyticsGroups::test_analytics_groups_thread_onto_job_metadata": 1.7073,- "tests/integration/pipelex/pipeline/test_pipeline_run_setup_analytics_groups.py::TestPipelineRunSetupAnalyticsGroups::test_malformed_groups_are_refused_before_the_run_starts": 0.0011,- "tests/integration/pipelex/pipeline/test_pipeline_run_setup_analytics_groups.py::TestPipelineRunSetupAnalyticsGroups::test_omitting_them_leaves_an_empty_mapping": 0.075,- "tests/integration/pipelex/pipeline/test_pipeline_run_setup_analytics_groups.py::TestPipelineRunSetupAnalyticsGroups::test_the_refusal_registers_no_run_and_emits_no_trace_start": 0.0421,+ "tests/integration/pipelex/pipeline/test_pipeline_run_setup_run_extras.py::TestPipelineRunSetupRunExtras::test_run_extras_thread_onto_job_metadata": 1.7073,+ "tests/integration/pipelex/pipeline/test_pipeline_run_setup_run_extras.py::TestPipelineRunSetupRunExtras::test_malformed_extras_are_refused_before_the_run_starts": 0.0011,+ "tests/integration/pipelex/pipeline/test_pipeline_run_setup_run_extras.py::TestPipelineRunSetupRunExtras::test_omitting_them_leaves_an_empty_mapping": 0.075,+ "tests/integration/pipelex/pipeline/test_pipeline_run_setup_run_extras.py::TestPipelineRunSetupRunExtras::test_the_refusal_registers_no_run_and_emits_no_trace_start": 0.0421,"tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py::TestPipelineRunSetupCharacterization::test_empty_inputs_behave_like_no_inputs": 0.4682,"tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py::TestPipelineRunSetupCharacterization::test_failure_after_acquire_restores_outer_current_library": 0.1428,"tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py::TestPipelineRunSetupCharacterization::test_failure_when_outer_is_run_library_clears_instead_of_dangling": 0.3057,@@ -6803,10 +6803,10 @@"tests/unit/pipelex/kernel/test_llm_ops_model_resolution.py::TestConcreteLlmModelHandle::test_an_unknown_reference_is_returned_unchanged_rather_than_raising": 0.1205,"tests/unit/pipelex/kernel/test_llm_text_kernel.py::TestLlmTextKernel::test_the_callers_concept_and_output_class_reach_the_memory": 1.5695,"tests/unit/pipelex/kernel/test_llm_text_kernel.py::TestLlmTextKernel::test_the_defaults_are_what_the_method_used_to_hardcode": 0.7152,- "tests/unit/pipelex/kernel/test_pipelex_kernel_analytics_groups.py::TestPipelexKernelAnalyticsGroups::test_a_malformed_mapping_is_refused_when_the_kernel_is_minted": 0.0304,- "tests/unit/pipelex/kernel/test_pipelex_kernel_analytics_groups.py::TestPipelexKernelAnalyticsGroups::test_omitting_them_leaves_an_empty_mapping": 0.1612,- "tests/unit/pipelex/kernel/test_pipelex_kernel_analytics_groups.py::TestPipelexKernelAnalyticsGroups::test_supplied_groups_land_on_the_runs_metadata": 0.2252,- "tests/unit/pipelex/kernel/test_pipelex_kernel_analytics_groups.py::TestPipelexKernelAnalyticsGroups::test_two_kernels_do_not_share_one_default_mapping": 0.2354,+ "tests/unit/pipelex/kernel/test_pipelex_kernel_run_extras.py::TestPipelexKernelRunExtras::test_a_malformed_mapping_is_refused_when_the_kernel_is_minted": 0.0304,+ "tests/unit/pipelex/kernel/test_pipelex_kernel_run_extras.py::TestPipelexKernelRunExtras::test_omitting_them_leaves_an_empty_mapping": 0.1612,+ "tests/unit/pipelex/kernel/test_pipelex_kernel_run_extras.py::TestPipelexKernelRunExtras::test_supplied_extras_land_on_the_runs_metadata": 0.2252,+ "tests/unit/pipelex/kernel/test_pipelex_kernel_run_extras.py::TestPipelexKernelRunExtras::test_two_kernels_do_not_share_one_default_mapping": 0.2354,"tests/unit/pipelex/kernel/test_pipelex_kernel_run_state.py::TestPipelexKernelRunState::test_a_step_names_the_pipe_it_is_running_when_told_which": 0.0004,"tests/unit/pipelex/kernel/test_pipelex_kernel_run_state.py::TestPipelexKernelRunState::test_a_supplied_trace_context_becomes_the_runs_identity": 1.0298,"tests/unit/pipelex/kernel/test_pipelex_kernel_run_state.py::TestPipelexKernelRunState::test_an_unnamed_step_does_not_erase_the_runs_own_pipe_code": 0.0012,@@ -9833,19 +9833,19 @@"tests/unit/pipelex/runtime_bridge/test_exceptions_disclosure.py::TestRuntimeBridgeExceptionDisclosure::test_generic_plugin_hint_survives_strict_disclosure[acme]": 0.1287,"tests/unit/pipelex/runtime_bridge/test_exceptions_disclosure.py::TestRuntimeBridgeExceptionDisclosure::test_generic_plugin_hint_survives_strict_disclosure[mistral-workflows]": 0.0005,"tests/unit/pipelex/runtime_bridge/test_exceptions_disclosure.py::TestRuntimeBridgeExceptionDisclosure::test_generic_plugin_hint_survives_strict_disclosure[temporal]": 0.8878,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_malformed_groups_are_refused_at_construction[empty-key]": 0.0003,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_malformed_groups_are_refused_at_construction[empty-value]": 0.0007,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_malformed_groups_are_refused_at_construction[hyphen-in-key]": 0.0008,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_malformed_groups_are_refused_at_construction[one-over-the-entry-cap]": 0.0006,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_malformed_groups_are_refused_at_construction[space-in-value]": 0.0007,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_malformed_groups_are_refused_at_construction[trailing-newline-in-value]": 0.0007,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_malformed_groups_are_refused_at_construction[uppercase-key]": 0.0012,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_malformed_groups_are_refused_at_construction[value-one-over-the-length-cap]": 0.0013,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_the_field_defaults_to_an_empty_mapping": 0.2192,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_the_groups_survive_a_json_round_trip": 0.0145,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_well_formed_groups_cross_the_wire[empty-mapping]": 0.2285,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_well_formed_groups_cross_the_wire[the-hosted-plane-shape]": 0.0169,- "tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py::TestTheWireRefusesMalformedAnalyticsGroups::test_well_formed_groups_cross_the_wire[two-group-types]": 1.5976,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_malformed_extras_are_refused_at_construction[empty-key]": 0.0003,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_malformed_extras_are_refused_at_construction[empty-value]": 0.0007,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_malformed_extras_are_refused_at_construction[hyphen-in-key]": 0.0008,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_malformed_extras_are_refused_at_construction[one-over-the-entry-cap]": 0.0006,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_malformed_extras_are_refused_at_construction[space-in-value]": 0.0007,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_malformed_extras_are_refused_at_construction[trailing-newline-in-value]": 0.0007,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_malformed_extras_are_refused_at_construction[uppercase-key]": 0.0012,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_malformed_extras_are_refused_at_construction[value-one-over-the-length-cap]": 0.0013,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_the_field_defaults_to_an_empty_mapping": 0.2192,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_the_extras_survive_a_json_round_trip": 0.0145,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_well_formed_extras_cross_the_wire[empty-mapping]": 0.2285,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_well_formed_extras_cross_the_wire[the-hosted-plane-shape]": 0.0169,+ "tests/unit/pipelex/runtime_bridge/test_input_run_extras.py::TestTheWireRefusesMalformedRunExtras::test_well_formed_extras_cross_the_wire[two-group-types]": 1.5976,"tests/unit/pipelex/runtime_bridge/test_input_models.py::TestInputOutputModels::test_dispatch_ack_forbids_output_fields": 0.1075,"tests/unit/pipelex/runtime_bridge/test_input_models.py::TestInputOutputModels::test_dispatch_ack_requires_both_ids": 0.0003,"tests/unit/pipelex/runtime_bridge/test_input_models.py::TestInputOutputModels::test_input_defaults_match_design": 0.7796,@@ -10115,40 +10115,40 @@"tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py::TestTheErrorSaysWhetherTheFileIsOldOrWrong::test_the_domain_comes_from_the_class_and_the_block_rides_the_report": 0.0534,"tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py::TestTheRemedyIsNamedOnlyWhereItWouldWrite::test_a_file_the_ledger_carries_forward_is_told_to_run_the_command": 0.0512,"tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py::TestTheRemedyIsNamedOnlyWhereItWouldWrite::test_a_file_with_nothing_to_apply_is_told_to_read_the_dry_run": 0.0758,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_an_empty_mapping_is_the_default": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_an_unknown_group_type_is_carried_through": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_copy_with_update_carries_the_groups_through": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[dot-in-key]": 0.0004,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[dot-in-value]": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[empty-key]": 1.5792,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[empty-value]": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[hyphen-in-key]": 0.0009,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[interior-newline-in-value]": 0.0148,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[key-one-over-the-length-cap]": 0.0004,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[key-starting-with-a-digit]": 0.0004,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[key-starting-with-an-underscore]": 0.0146,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[one-over-the-entry-cap]": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[slash-in-value]": 0.0008,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[space-in-key]": 0.0005,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[space-in-value]": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[trailing-carriage-return-in-value]": 1.5962,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[trailing-newline-in-key]": 0.0004,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[trailing-newline-in-value]": 0.0005,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[uppercase-key]": 0.0004,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_malformed_groups_raise_at_construction[value-one-over-the-length-cap]": 0.0005,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_the_copy_does_not_alias_the_parents_mapping": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_the_error_names_the_offending_entry": 0.0009,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_the_helper_raises_value_error_rather_than_a_pydantic_error": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_the_helper_returns_the_mapping_it_was_given": 0.0002,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_the_patterns_are_anchored_by_fullmatch_not_by_the_dollar_sign": 0.0269,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_two_run_metadatas_do_not_share_one_default_mapping": 0.0002,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_well_formed_groups_are_accepted[at-the-entry-cap]": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_well_formed_groups_are_accepted[empty-mapping]": 0.2381,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_well_formed_groups_are_accepted[full-charset]": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_well_formed_groups_are_accepted[longest-key-and-value]": 0.0003,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_well_formed_groups_are_accepted[shortest-key-and-value]": 0.0005,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_well_formed_groups_are_accepted[the-hosted-plane-shape]": 1.6324,- "tests/unit/pipelex/system/test_analytics_groups.py::TestAnalyticsGroups::test_well_formed_groups_are_accepted[two-group-types]": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_an_empty_mapping_is_the_default": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_an_unknown_key_is_carried_through": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_copy_with_update_carries_the_extras_through": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[dot-in-key]": 0.0004,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[dot-in-value]": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[empty-key]": 1.5792,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[empty-value]": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[hyphen-in-key]": 0.0009,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[interior-newline-in-value]": 0.0148,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[key-one-over-the-length-cap]": 0.0004,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[key-starting-with-a-digit]": 0.0004,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[key-starting-with-an-underscore]": 0.0146,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[one-over-the-entry-cap]": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[slash-in-value]": 0.0008,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[space-in-key]": 0.0005,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[space-in-value]": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[trailing-carriage-return-in-value]": 1.5962,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[trailing-newline-in-key]": 0.0004,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[trailing-newline-in-value]": 0.0005,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[uppercase-key]": 0.0004,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_malformed_extras_raise_at_construction[value-one-over-the-length-cap]": 0.0005,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_the_copy_does_not_alias_the_parents_mapping": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_the_error_names_the_offending_entry": 0.0009,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_the_helper_raises_value_error_rather_than_a_pydantic_error": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_the_helper_returns_the_mapping_it_was_given": 0.0002,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_the_patterns_are_anchored_by_fullmatch_not_by_the_dollar_sign": 0.0269,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_two_run_metadatas_do_not_share_one_default_mapping": 0.0002,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_well_formed_extras_are_accepted[at-the-entry-cap]": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_well_formed_extras_are_accepted[empty-mapping]": 0.2381,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_well_formed_extras_are_accepted[full-charset]": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_well_formed_extras_are_accepted[longest-key-and-value]": 0.0003,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_well_formed_extras_are_accepted[shortest-key-and-value]": 0.0005,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_well_formed_extras_are_accepted[the-hosted-plane-shape]": 1.6324,+ "tests/unit/pipelex/system/test_run_extras.py::TestRunExtras::test_well_formed_extras_are_accepted[two-group-types]": 0.0003,"tests/unit/pipelex/system/test_config_resolution.py::TestConfigResolution::test_cross_platform_paths": 0.1478,"tests/unit/pipelex/system/test_config_resolution.py::TestConfigResolution::test_effective_config_dir_falls_back_to_global": 0.0021,"tests/unit/pipelex/system/test_config_resolution.py::TestConfigResolution::test_effective_config_dir_is_project_when_exists": 0.0011,diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ea91f8a49..308729977 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,9 +2,21 @@## [Unreleased]+### Added++- **A caller can be known without a run**: `CallerIdentity` (`pipelex.system.caller_identity`) holds the `user_id` and `extras` a host would state on a run, and `scoped_caller_identity` makes one the ambient caller for a block. An event emitted with no `RunMetadata` in hand reads the caller in scope before it falls back to the configured `user_id`, and `PipelexMTHDSProtocol.caller_identity` exposes the caller a protocol was built for.+### Changed-- **Pipelex's own telemetry stream receives the run's `user_id` as it is**: the Gateway stream sent a one-way digest of the caller taken inside the Gateway-key hash, and carried a `deployment` group instead of the run's own `analytics_groups`. It now resolves identity like the operator's identified stream — the run's `user_id` is the PostHog `distinct_id` and its `analytics_groups` ride the groups facet — so a host's events and the runtime's land on the same person and the same organization. The `NAMESPACED` identity policy and the `deployment` group type are removed. Anything that names no caller still reports under the Gateway-key hash.+- **A run's `analytics_groups` is renamed `extras` (Breaking)**: the base library no longer names an analytics concept in its run model or its job-preparation signatures. `RunMetadata.analytics_groups`, the runtime-bridge payload's `analytics_groups`, and the `analytics_groups` parameter of `pipeline_run_setup`, `prepare_pipe_job`, `PipelexKernel.make` and `PipelexRunner` are now `extras`: an opaque `dict[str, str]` of labels the host attaches to a run, which the library never reads by name. The module `pipelex.system.analytics_groups` is now `pipelex.system.run_extras`, with `validate_run_extras`, `RUN_EXTRAS_KEY_PATTERN`, `RUN_EXTRAS_VALUE_PATTERN` and `RUN_EXTRAS_MAX_ENTRIES`, and the span attribute `pipelex.run.analytics_groups` is now `pipelex.run.extras` (`PipelexSpanAttr.RUN_EXTRAS`). Behaviour is unchanged: the mapping is validated where it enters under the same bounds, and telemetry still forwards it whole as the PostHog groups of each capture. There is no alias; a host passing `analytics_groups` must pass `extras` instead.+- **Pipelex's own telemetry stream receives the run's `user_id` as it is**: the Gateway stream sent a one-way digest of the caller taken inside the Gateway-key hash, and carried a `deployment` group instead of the run's own groups. It now resolves identity like the operator's identified stream — the run's `user_id` is the PostHog `distinct_id` and its `extras` ride the groups facet — so a host's events and the runtime's land on the same person and the same organization. The `NAMESPACED` identity policy and the `deployment` group type are removed. Anything that names no caller still reports under the Gateway-key hash.+- **`BundleValidatorProtocol.validate_bundles` requires `caller_identity` (Breaking)**: a validator is handed who asked for the validation, `None` meaning nobody, so a hosted `/validate` attributes its telemetry to its caller. Every validator implementation must accept the argument, and a host must pass it — `caller_identity=self.caller_identity` from a `PipelexMTHDSProtocol` runner. `validate_bundles_in_process`, `validate_bundle`, `dry_run_pipe_in_process` and the `BundleValidator` sweep methods gain an optional `caller_identity` of their own.++### Fixed++- **A trace's first span carries its run**: the trace-start `$ai_span` captured on both PostHog streams now includes `pipeline_run_id`, so the root of a trace joins its run's other events without going through a child span.+- **A validation is attributed to the caller who asked for it**: the sweep's `pipe_dry_run` event carried no run, so on a hosted plane it went out under the deployment's configured `user_id` whoever validated. It is now emitted with the caller in scope, and the sweep's dry runs and the graph arm's dry run state that caller in their job metadata instead of `dry-run-no-user`. A local validation names nobody and reports under the configured id as before.+- **A crash inside a run is attributed to that run's caller**: the exception autocapture resolved one runless identity when it was built, so every `$exception` on a hosted plane landed on the configured constant. Every pipe now runs with its run's caller in scope, an exception leaving a pipe carries that caller — read back through the `__cause__` and `__context__` chain, so a host's own error raised `from` it still resolves — and the capture resolves each error's identity when it arrives. An error raised outside every run still reports under the fallback, and `mode = "anonymous"` still identifies nobody.## [v0.63.0] - 2026-09-23diff --git a/docs/configuration/config-practical/telemetry-config.md b/docs/configuration/config-practical/telemetry-config.mdindex 063ceb494..7db76f1aa 100644--- a/docs/configuration/config-practical/telemetry-config.md+++ b/docs/configuration/config-practical/telemetry-config.md@@ -111,8 +111,8 @@ The `[custom_posthog]` section configures event tracking and optional AI span tr#### Mode Options- **`"off"`**: No events sent to your PostHog-- **`"anonymous"`**: Events sent without user identification. This covers your users too, and yourself: a run's own caller is never identified, its analytics groups are never sent, and a `user_id` left in the file is not sent either-- **`"identified"`**: Events and spans produced during a run are attributed to that run's caller, with its analytics groups attached. Your `user_id` is what everything else reports under — an event outside any run, and a run that names no distinguishable caller, which is every run on your own machine. The groups ride either way: a run may carry them without naming a caller+- **`"anonymous"`**: Events sent without user identification. This covers your users too, and yourself: a run's own caller is never identified, its `extras` are never sent as groups, and a `user_id` left in the file is not sent either+- **`"identified"`**: Events and spans produced during a run are attributed to that run's caller, with its `extras` attached as groups. Your `user_id` is what everything else reports under — an event outside any run, and a run that names no distinguishable caller, which is every run on your own machine. The extras ride either way: a run may carry them without naming a callerSee [Telemetry Setup](../../setup/telemetry.md) for how a run supplies its caller and its groups.diff --git a/docs/features/telemetry.md b/docs/features/telemetry.mdindex 2132f3efb..de5605723 100644--- a/docs/features/telemetry.md+++ b/docs/features/telemetry.md@@ -25,7 +25,7 @@ Event tracking and AI span tracing with fine-grained privacy controls. Choose be## Per-run attribution-A span or an event produced during a run is attributed to that run's own caller, not to the process that served it — which is what lets one deployment run many people's methods and still see each person's generations on their own timeline. The identity comes from the run: `user_id` is who started it, and the optional `analytics_groups` mapping says which of your entities it belongs to. Both are supplied where the run is, they ride the job through every nested pipe and across a process boundary, and they reach PostHog in the fields it reserves for identity — never as an event property or a span name. Anything that names no caller of its own reports under the `user_id` you configured: an event outside any run, and a run on your own machine, whose caller is the literal `local` rather than a person a backend could tell apart — though its groups still ride, because which entities a run belongs to is a separate question from who started it. Pipelex's own Gateway stream is attributed the same way: the run's `user_id` as it is, and its groups. See [Telemetry Setup](../setup/telemetry.md) for how to supply the groups.+A span or an event produced during a run is attributed to that run's own caller, not to the process that served it — which is what lets one deployment run many people's methods and still see each person's generations on their own timeline. The identity comes from the run: `user_id` is who started it, and the optional `extras` mapping carries your own opaque labels for it, such as which of your entities it belongs to, forwarded to PostHog as groups. Both are supplied where the run is, they ride the job through every nested pipe and across a process boundary, and they reach PostHog in the fields it reserves for identity — never as an event property or a span name. Work a host does for a known caller without it being a run is attributed the same way: validating a bundle, whose `pipe_dry_run` event and dry runs carry the caller the host passed, and an unhandled exception raised inside a run, which carries that run's caller out to the exception hook. Anything that names no caller of its own reports under the `user_id` you configured: an event outside any run and any caller's work, and a run on your own machine, whose caller is the literal `local` rather than a person a backend could tell apart — though its extras still ride as groups, because which entities a run belongs to is a separate question from who started it. Pipelex's own Gateway stream is attributed the same way: the run's `user_id` as it is, and its extras as groups. See [Telemetry Setup](../setup/telemetry.md) for how to supply the extras.## Gateway Telemetrydiff --git a/docs/setup/telemetry.md b/docs/setup/telemetry.mdindex 590a70d71..65e8aabc3 100644--- a/docs/setup/telemetry.md+++ b/docs/setup/telemetry.md@@ -12,7 +12,7 @@ Pipelex supports two independent telemetry streams that serve different purposesWhen you use **Pipelex Gateway** as your inference backend, identified telemetry is **automatically enabled**. This telemetry is tied to your Gateway API key (hashed for security) and operates independently from your `telemetry.toml` settings.-A run that names a caller of its own is attributed to that caller on this stream too: the run's `user_id` is sent as the `distinct_id` exactly as you supplied it, and its `analytics_groups` ride the capture as groups. Anything that names no caller reports under your key's hash.+A run that names a caller of its own is attributed to that caller on this stream too: the run's `user_id` is sent as the `distinct_id` exactly as you supplied it, and its `extras` ride the capture as groups. Anything that names no caller reports under your key's hash.**What we collect:**@@ -104,21 +104,31 @@ When set, this disables:!!! warning "Gateway Requires Telemetry"If you set `DO_NOT_TRACK=1` while using Pipelex Gateway, the Gateway will not function. Use direct provider backends instead if you need to disable all telemetry.-## Attaching your own groups to a run+## Attaching your own labels to a runA host that runs Pipelex for more than one customer usually wants a run's telemetry to belong to the entities *it* cares about — an organization, a workspace, a tenant. Pipelex carries those labels for you without ever learning what they mean.-The run-level metadata every run carries (`RunMetadata`) has an `analytics_groups` field: an opaque mapping of **group type** to **group key** that you supply when you start the run, beside `user_id` and `storage_scope`.+The run-level metadata every run carries (`RunMetadata`) has an `extras` field: an opaque mapping of string keys to string values that you supply when you start the run, beside `user_id` and `storage_scope`. Pipelex never reads a key by name; the telemetry layer forwards the whole mapping as the **groups** of each capture, each key being a group type and its value a group key. Keys are lowercase snake_case starting with a letter (at most 32 characters), values use only letters, digits, `_` and `-` (1 to 128 characters), and a run carries at most five entries; anything else is refused before the run starts.```python-analytics_groups = {"organization": "org_acme"}+extras = {"organization": "org_acme"}```-On **your own** PostHog stream, every span and every event the run produces is then captured under that run's `user_id`, with the groups attached through PostHog's own groups facet — so a generation made for one of your customers appears on that customer's timeline and inside their organization, instead of under one identity per deployment. The same values reach every OpenTelemetry exporter as the span attributes `pipelex.run.user_id` and `pipelex.run.analytics_groups`, and Langfuse receives the user id in the field it reserves for it. Pipelex's own Gateway stream receives the same `user_id` and groups, as described above.+On **your own** PostHog stream, every span and every event the run produces is then captured under that run's `user_id`, with its extras attached through PostHog's own groups facet — so a generation made for one of your customers appears on that customer's timeline and inside their organization, instead of under one identity per deployment. The same values reach every OpenTelemetry exporter as the span attributes `pipelex.run.user_id` and `pipelex.run.extras`, and Langfuse receives the user id in the field it reserves for it. Pipelex's own Gateway stream receives the same `user_id` and groups, as described above.Anything that names no caller of its own keeps reporting under the `user_id` you configured in `telemetry.toml`, which is what that setting now means: the identity of everything that is not one caller's run. That covers an event outside any run — a CLI command listing your pipes — and a run whose caller is not a distinguishable person either: a run on your own machine is attributed to the literal `local`, the same string on every machine, so Pipelex declines it as an identity and uses your configured id instead. The same goes for `single-tenant`, which pipelex-api states for every run when it is deployed with no users. Per-run attribution is for a host that passes a real `user_id` per run.-The groups do not depend on that. A run that leaves `user_id` at its default still carries its `analytics_groups` onto every capture, under your configured id — knowing which entities a run belongs to and naming its caller are two separate decisions, and you may take one without the other.+The extras do not depend on that. A run that leaves `user_id` at its default still carries its `extras` onto every capture, under your configured id — knowing which entities a run belongs to and naming its caller are two separate decisions, and you may take one without the other.++### Work that is not a run, and crashes++A run is not the only thing a host does on a caller's behalf. Validating a bundle dry-runs its pipes without being a run, and an unhandled exception reaches PostHog through the interpreter's exception hook, which is handed nothing but the error. Both are still attributed to the caller when one is known, so your configured `user_id` stands only for work that truly belongs to nobody:++- **Validation.** The validate entry points take a `caller_identity` — the `user_id` and `extras` you would state on a run, as a `CallerIdentity`. `PipelexMTHDSProtocol.validate` passes the caller the protocol was built for, `validate_bundles_in_process`, `validate_bundle` and `BundleValidator` accept one directly, and the `BundleValidatorProtocol` seam requires one (`None` meaning "nobody"). The `pipe_dry_run` event and every dry run the validation performs are then attributed to that caller. A CLI validation on your own machine names nobody and keeps reporting under your configured id.+- **Crashes inside a run.** Every pipe runs with its run's caller in scope, and an exception that escapes the pipe carries that caller with it — through any error a host raises `from` it — so an `$exception` captured once the error reaches the interpreter lands on the person whose run failed, with their groups. An exception raised outside every run reports under your configured id.+- **Anything else with no run in hand.** An event emitted without a run but while a caller is in scope reads that caller. A host can open such a scope around its own work with `scoped_caller_identity(caller_identity=...)` from `pipelex.system.caller_identity`.++The same rules apply to all of these as to a run: a placeholder such as `local` names nobody, `mode = "anonymous"` identifies nobody, and the caller never becomes an event property.!!! note "Anonymous mode covers your users too"With `mode = "anonymous"`, the runtime identifies nobody on your stream: no run's `user_id` is applied, no groups are sent, and the `user_id` you configured is not sent either — a mode that identifies nobody would not be one that still named you. Leaving a `user_id` in `telemetry.toml` while switching to `anonymous` therefore changes nothing. Per-run attribution needs `mode = "identified"`.diff --git a/docs/under-the-hood/orchestrator-plugins.md b/docs/under-the-hood/orchestrator-plugins.mdindex ed7616cf4..a09d27e25 100644--- a/docs/under-the-hood/orchestrator-plugins.md+++ b/docs/under-the-hood/orchestrator-plugins.md@@ -77,6 +77,7 @@ class BundleValidatorProtocol(Protocol):mthds_sources: list[str] | None,allow_signatures: bool,library_dirs: "Sequence[Path] | None",+ caller_identity: CallerIdentity | None,) -> BundleValidationVerdict: ...```@@ -89,6 +90,8 @@ Two contract points distinguish it from `OrchestratorProtocol.execute`:The seam is deliberately typed at the MTHDS-protocol level (`ValidationReport` from `mthds.protocol`), not the concrete `PipelexValidationReport` envelope: the concrete report's module reaches the hub, so naming it from this hub-reachable seam would close an import cycle, and the seam is generic across orchestrators (language-standard altitude), so it speaks the protocol report — the Pipelex-runtime envelope is the concrete `ValidationReport` subtype the validators actually produce, and the API recovers that precise type at its edge. `library_dirs` is host context the in-process arm needs to load the method library; a worker-dispatched arm ignores it — its worker loads its own library.+`caller_identity` is who asked for the validation: the `user_id` and `extras` the host would state on a run, as a `CallerIdentity` (`pipelex/system/caller_identity.py`). It is required, with `None` meaning "nobody", so a host cannot leave it out by accident: a validation is not a run and has no `RunMetadata` to carry its caller, and without this argument its telemetry — the sweep's `pipe_dry_run` event and its dry runs — reported under the deployment's configured id. The in-process arm hands it to `validate_bundles_in_process`, which makes it the ambient caller for the whole pass; a worker-dispatched arm must carry it to the worker and do the same there. A `PipelexMTHDSProtocol` exposes the caller it was built for as `caller_identity`, so a host runner passes `caller_identity=self.caller_identity`.+A plugin contributes one per token, right next to its orchestrator:```pythondiff --git a/docs/under-the-hood/pipelex-kernel.md b/docs/under-the-hood/pipelex-kernel.mdindex acfeee4fa..61b85cf57 100644--- a/docs/under-the-hood/pipelex-kernel.md+++ b/docs/under-the-hood/pipelex-kernel.md@@ -127,7 +127,7 @@ summaries = extract_main_content_as_list(memory=result.memory, item_type=Summary`PipelexKernel` holds run-scoped identity, plus the one seam that identity needs:-- **`job_metadata`** — the run-level metadata. **The two halves are now separate types, and a caller reading a field off this object must know which half it is in.** `JobMetadata.run_metadata` holds what is constant for the whole run — `user_id`, `pipeline_run_id`, `storage_scope`, `request_id`, `analytics_groups` — and the rest of `JobMetadata` holds what changes per step (`pipe_code`, `pipe_run_id`, `otel_context`). So it is `kernel.job_metadata.run_metadata.pipeline_run_id`, not `kernel.job_metadata.pipeline_run_id`; there is deliberately no read-through accessor, so one fact has one spelling. `user_id`, `storage_scope` and `analytics_groups` are supplied by the host at `PipelexKernel.make(...)` — the last of them opaque, so a multi-tenant host can attribute a kernel-driven run to its own entities without the runtime learning what they are. The distinction this bullet already drew informally — run-level metadata, per-step copy — is what the split makes explicit, and it is why the per-step copy can carry the run half through untouched. It is not what a step runs under: every call mints a per-step copy through `make_step_metadata()`, carrying a fresh `pipe_run_id` and inheriting the trace context, so trace and usage attribution stay per-step. This mirrors the interpreter's pass-down-a-modified-copy pattern. `make_step_metadata(pipe_code=…)` names the pipe the step is running — mirroring what the interpreter stamps on its live and dry paths — so log correlation, usage accounting, and the per-step labelling a distributed backend derives see a named step. When no `pipe_code` is supplied the key is omitted from the update rather than passed as `None`, so a run-level `pipe_code` is never silently erased; the direct-call façade (`llm_text`/`llm_object`) stays deliberately anonymous, because the caller ran no pipe.+- **`job_metadata`** — the run-level metadata. **The two halves are now separate types, and a caller reading a field off this object must know which half it is in.** `JobMetadata.run_metadata` holds what is constant for the whole run — `user_id`, `pipeline_run_id`, `storage_scope`, `request_id`, `extras` — and the rest of `JobMetadata` holds what changes per step (`pipe_code`, `pipe_run_id`, `otel_context`). So it is `kernel.job_metadata.run_metadata.pipeline_run_id`, not `kernel.job_metadata.pipeline_run_id`; there is deliberately no read-through accessor, so one fact has one spelling. `user_id`, `storage_scope` and `extras` are supplied by the host at `PipelexKernel.make(...)` — the last of them opaque, so a multi-tenant host can attribute a kernel-driven run to its own entities without the runtime learning what they are. The distinction this bullet already drew informally — run-level metadata, per-step copy — is what the split makes explicit, and it is why the per-step copy can carry the run half through untouched. It is not what a step runs under: every call mints a per-step copy through `make_step_metadata()`, carrying a fresh `pipe_run_id` and inheriting the trace context, so trace and usage attribution stay per-step. This mirrors the interpreter's pass-down-a-modified-copy pattern. `make_step_metadata(pipe_code=…)` names the pipe the step is running — mirroring what the interpreter stamps on its live and dry paths — so log correlation, usage accounting, and the per-step labelling a distributed backend derives see a named step. When no `pipe_code` is supplied the key is omitted from the update rather than passed as `None`, so a run-level `pipe_code` is never silently erased; the direct-call façade (`llm_text`/`llm_object`) stays deliberately anonymous, because the caller ran no pipe.- **`cogt_run_params`** — the execution-mode contract (`run_mode`, and the DRY-only `is_mock_usage` sub-flag) that every cogt leaf reads off the assignment it is handed.- **`step_id_source`** — where each step's `pipe_run_id` comes from, defaulting to a fresh `uuid4`, which is what every in-process run wants. It exists for a kernel hosted inside a replay-based executor, where ids minted from a non-replay-safe source take different values each re-execution; such a host injects its own replay-safe source via `PipelexKernel.make(step_id_source=…)`. It is a seam, not state — the kernel never inspects what it returns.diff --git a/pipelex/kernel/pipelex_kernel.py b/pipelex/kernel/pipelex_kernel.pyindex 622c379bd..70d0cca4c 100644--- a/pipelex/kernel/pipelex_kernel.py+++ b/pipelex/kernel/pipelex_kernel.py@@ -86,7 +86,7 @@ class PipelexKernel:run_mode: PipeRunMode = PipeRunMode.LIVE,user_id: str,storage_scope: str,- analytics_groups: dict[str, str] | None = None,+ extras: dict[str, str] | None = None,is_mock_usage: bool = False,trace_context: TraceContext | None = None,step_id_source: Callable[[], str] | None = None,@@ -109,12 +109,12 @@ class PipelexKernel:across two ids (the registered-context emit path stamps the event log's id, the runnerfallback stamps the metadata's), so the read-back would silently miss half of them.- ``analytics_groups`` is the opaque, host-supplied mapping this run's telemetry belongs to,- carried beside ``user_id`` and ``storage_scope``. This tier is the direct programmatic entry+ ``extras`` is the opaque, host-supplied mapping of labels about this run, carried beside+ ``user_id`` and ``storage_scope``. This tier is the direct programmatic entrypoint, so a multi-tenant host embedding the kernel needs the same seam the pipeline entry- points have — without it a kernel-minted run is permanently group-less and its host has no- supported way to say otherwise. Omitting it leaves the group facet empty, which misattributes- nothing. See :mod:`pipelex.system.analytics_groups`.+ points have — without it a kernel-minted run is permanently unlabelled and its host has no+ supported way to say otherwise. Omitting it leaves the telemetry group facet empty, which+ misattributes nothing. See :mod:`pipelex.system.run_extras`.``step_id_source`` overrides where each step's ``pipe_run_id`` comes from; it defaults to afresh ``uuid4``, which is what every in-process run wants. It exists for a kernel hosted@@ -130,7 +130,7 @@ class PipelexKernel:user_id=user_id,storage_scope=storage_scope,pipeline_run_id=trace_context.graph_id if trace_context is not None else str(uuid4()),- analytics_groups=analytics_groups or {},+ extras=extras or {},),trace_context=trace_context,),diff --git a/pipelex/pipe_machinery/pipe_abstract.py b/pipelex/pipe_machinery/pipe_abstract.pyindex e6f0d23a9..2c4ee1571 100644--- a/pipelex/pipe_machinery/pipe_abstract.py+++ b/pipelex/pipe_machinery/pipe_abstract.py@@ -29,6 +29,7 @@ from pipelex.pipe_machinery.validation import is_variable_satisfied_by_inputsfrom pipelex.pipe_run.pipe_run_params import PipeRunParams, output_multiplicity_to_applyfrom pipelex.pipe_signature.exceptions import PipeSignatureNotExecutableErrorfrom pipelex.pipeline.pipeline_factory import PipelineFactory+from pipelex.system.caller_identity import CallerIdentity, scoped_caller_identityfrom pipelex.system.job_metadata import JobMetadata, OtelContext, RunMetadatafrom pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.registries.class_registry_access import get_class_registry@@ -612,15 +613,22 @@ class PipeAbstract(ABC, BaseModel):# so a failed pipe never leaves a stale frame behind on the shared pipe_stack, where it# could accumulate entries and trip PipeStackOverflowError. Required cleanup belongs in a# `finally` block.+ #+ # The run's caller is made the ambient one for as long as the pipe runs, so a+ # capture with no run in hand — an exception raised in here, captured once it+ # escapes the interpreter — is still attributed to the person the run is for.+ # Every pipe, at every depth, opens the scope from its own job metadata: a+ # Temporal activity runs a sub-pipe with no outer scope to inherit.pipe_run_params.push_pipe_to_stack(pipe_code=self.code)try:- return await self._run_pipe_traced(- job_metadata=job_metadata,- working_memory=working_memory,- pipe_run_params=pipe_run_params,- output_name=output_name,- library_crate=library_crate,- )+ with scoped_caller_identity(caller_identity=CallerIdentity.make_from_run_metadata(run_metadata=job_metadata.run_metadata)):+ return await self._run_pipe_traced(+ job_metadata=job_metadata,+ working_memory=working_memory,+ pipe_run_params=pipe_run_params,+ output_name=output_name,+ library_crate=library_crate,+ )finally:pipe_run_params.pop_pipe_from_stack(pipe_code=self.code)diff --git a/pipelex/pipe_run/dry_run_in_process.py b/pipelex/pipe_run/dry_run_in_process.pyindex c62c8b84d..4b07d29bb 100644--- a/pipelex/pipe_run/dry_run_in_process.py+++ b/pipelex/pipe_run/dry_run_in_process.py@@ -26,6 +26,7 @@ from pipelex.pipe_run.pipe_run import PipeRunfrom pipelex.pipeline.execution_seams import prepare_pipe_jobfrom pipelex.pipeline.pipeline_factory import PipelineFactoryfrom pipelex.runtime_hub import scoped_content_generator, scoped_event_log+from pipelex.system.caller_identity import CallerIdentity, scoped_caller_identityfrom pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.storage_scope import DRY_RUN_STORAGE_SCOPE, DRY_RUN_USER_IDfrom pipelex.tracing.in_memory_event_log import InMemoryEventLog@@ -70,7 +71,7 @@ async def best_effort_graph_spec(*, pipe_ref: str | None, library_id: str | Nonereturn None-async def dry_run_pipe_in_process(pipe: PipeAbstract, *, library_id: str) -> GraphSpec:+async def dry_run_pipe_in_process(pipe: PipeAbstract, *, library_id: str, caller_identity: CallerIdentity | None = None) -> GraphSpec:"""Dry-run ``pipe`` against an already-open library fully in-process, tracing the graph in memory.The in-process twin of :func:`pipelex.pipeline.dry_run_pipeline.dry_run_pipeline` for hosts@@ -98,6 +99,9 @@ async def dry_run_pipe_in_process(pipe: PipeAbstract, *, library_id: str) -> GraArgs:pipe: The pipe to dry-run (resolved against the open library).library_id: The id of the already-open library to run against.+ caller_identity: Who the dry run is done for, when a host knows it. ``None`` inherits+ the caller already in scope — the validate surfaces open one around their whole+ pass — and with none the job states ``DRY_RUN_USER_ID``.Returns:The assembled GraphSpec.@@ -137,14 +141,22 @@ async def dry_run_pipe_in_process(pipe: PipeAbstract, *, library_id: str) -> Gramode=GraphSpecMode.DRY,)try:- with scoped_event_log(event_log), scoped_pipe_router(pipe_router), scoped_content_generator(content_generator):+ with (+ scoped_caller_identity(caller_identity=caller_identity) as effective_caller_identity,+ scoped_event_log(event_log),+ scoped_pipe_router(pipe_router),+ scoped_content_generator(content_generator),+ ):pipe_job = await prepare_pipe_job(pipe=pipe,library_id=library_id,execution_config=execution_config,pipe_run_mode=PipeRunMode.DRY,pipeline_run_id=pipeline_run_id,- user_id=DRY_RUN_USER_ID,+ # The caller the dry run is done for, so its pipe runs are attributed to+ # them; `DRY_RUN_USER_ID` says there is none.+ user_id=effective_caller_identity.user_id if effective_caller_identity is not None else DRY_RUN_USER_ID,+ extras=effective_caller_identity.extras if effective_caller_identity is not None else None,# A dry run provably stores nothing, but `storage_scope` is# required — so it says so, loudly and greppably, instead of# inheriting a default. A silent default on this field isdiff --git a/pipelex/pipeline/bundle_validator.py b/pipelex/pipeline/bundle_validator.pyindex b11d3e859..b83c8ef73 100644--- a/pipelex/pipeline/bundle_validator.py+++ b/pipelex/pipeline/bundle_validator.py@@ -55,6 +55,7 @@ from pipelex.pipe_run.pipe_run import PipeRunfrom pipelex.pipeline.execution_seams import acquire_library, prepare_pipe_jobfrom pipelex.pipeline.pipeline_factory import PipelineFactoryfrom pipelex.runtime_hub import get_telemetry_manager, scoped_content_generator+from pipelex.system.caller_identity import CallerIdentity, scoped_caller_identityfrom pipelex.system.configuration.configs import PipelineExecutionConfigfrom pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.storage_scope import DRY_RUN_STORAGE_SCOPE, DRY_RUN_USER_ID@@ -118,6 +119,7 @@ class BundleValidator:bundle_uris: list[str] | None = None,library_id: str = "",allow_signatures: bool = False,+ caller_identity: CallerIdentity | None = None,) -> dict[str, DryRunOutput]:"""Acquire a fresh library, load dirs + contents, sweep **all** loaded pipes, tear down.@@ -138,7 +140,7 @@ class BundleValidator:try:# acquire_library left the freshly-acquired library current, so the inner sweep over the# current library targets exactly acquired_id (it filters signatures in strict mode itself).- return await self.validate_current_library(allow_signatures=allow_signatures)+ return await self.validate_current_library(allow_signatures=allow_signatures, caller_identity=caller_identity)finally:# Restore the caller's outer current-library FIRST (so the guarantee survives a teardown# raise), then tear the acquired library down — mirroring validate_bundle / acquire_library.@@ -150,7 +152,9 @@ class BundleValidator:clear_current_library()get_library_manager().teardown(library_id=acquired_id)- async def validate_current_library(self, *, allow_signatures: bool = False) -> dict[str, DryRunOutput]:+ async def validate_current_library(+ self, *, allow_signatures: bool = False, caller_identity: CallerIdentity | None = None+ ) -> dict[str, DryRunOutput]:"""Sweep every pipe in the already-open **current** library, **without** tearing it down.The public inner sweep over the active library (D6): the caller owns the library lifecycle —@@ -161,7 +165,12 @@ class BundleValidator:acquires + tears down) and the shared core both the ``validate --all`` CLI and downstreamconsumers (e.g. cocode) build on instead of re-deriving ``get_pipes`` + ``validate_pipes`` by hand."""- return await self.validate_pipes(get_pipe_library().get_pipes(), library_id=get_current_library(), allow_signatures=allow_signatures)+ return await self.validate_pipes(+ get_pipe_library().get_pipes(),+ library_id=get_current_library(),+ allow_signatures=allow_signatures,+ caller_identity=caller_identity,+ )async def validate_pipes(self,@@ -169,6 +178,7 @@ class BundleValidator:*,library_id: str,allow_signatures: bool = False,+ caller_identity: CallerIdentity | None = None,) -> dict[str, DryRunOutput]:"""Classify each pipe ``SUCCESS / FAILURE / SKIPPED`` against an already-open library.@@ -191,9 +201,33 @@ class BundleValidator:the HTTP caller reading ``is_runnable``). A non-signature pipe that *reaches* a signaturedry-runs trivially in both modes (the signature mints a mock), so it is never a failure here.+ ``caller_identity`` is who asked for the sweep, when a host knows it (the hosted+ ``/validate`` route does). It is made the ambient caller for the sweep, so the+ ``PIPE_DRY_RUN`` event and every dry run's job metadata are attributed to that caller+ rather than to the telemetry stream's configured fallback. ``None`` inherits whatever+ caller is already in scope, and with none — a local CLI sweep — the dry runs state+ ``DRY_RUN_USER_ID`` and the event goes out under the fallback, as before.+Returns the per-pipe status map (carrying allowed failures + skips). Raises ``DryRunError``on ≥1 unexpected failure."""+ with scoped_caller_identity(caller_identity=caller_identity) as effective_caller_identity:+ return await self._validate_pipes_for_caller(+ pipes=pipes,+ library_id=library_id,+ allow_signatures=allow_signatures,+ caller_identity=effective_caller_identity,+ )++ async def _validate_pipes_for_caller(+ self,+ *,+ pipes: list[PipeAbstract],+ library_id: str,+ allow_signatures: bool,+ caller_identity: CallerIdentity | None,+ ) -> dict[str, DryRunOutput]:+ """The body of :meth:`validate_pipes`, run inside the caller's scope."""start_time = time.time()# allow_signatures is the sweep-mechanics flag (D-B): in strict mode signature pipes are@@ -225,6 +259,8 @@ class BundleValidator:sweepable_pipes.append(pipe)# 2. One validation telemetry event per sweep (relocated from the CLI's _validate_core).+ # It has no run to hand over — the sweep is not a run — so it is attributed to the+ # caller `validate_pipes` put in scope, and to the stream's fallback only when none is.get_telemetry_manager().track_event(event_name=EventName.PIPE_DRY_RUN, properties={EventProperty.NB_PIPES: len(sweepable_pipes)})# 3. The dry-run sweep. Each pipe is dry-run under a UNIQUE per-sweep pipeline run id (a@@ -255,14 +291,24 @@ class BundleValidator:with scoped_pipe_router(self._pipe_router), scoped_content_generator(ContentGenerator.make_inline()):for pipe in sweepable_pipes:results[pipe.pipe_ref] = await self._classify_pipe(- pipe=pipe, library_id=library_id, execution_config=execution_config, dry_run_pipeline_id=dry_run_pipeline_id+ pipe=pipe,+ library_id=library_id,+ execution_config=execution_config,+ dry_run_pipeline_id=dry_run_pipeline_id,+ caller_identity=caller_identity,)# 4. Aggregate + report.return self._aggregate(results=results, start_time=start_time)async def _classify_pipe(- self, *, pipe: PipeAbstract, library_id: str, execution_config: PipelineExecutionConfig, dry_run_pipeline_id: str+ self,+ *,+ pipe: PipeAbstract,+ library_id: str,+ execution_config: PipelineExecutionConfig,+ dry_run_pipeline_id: str,+ caller_identity: CallerIdentity | None,) -> DryRunOutput:"""Build the mock job and run the pipe DRY through the direct primitive; classify the outcome.@@ -271,6 +317,11 @@ class BundleValidator:plus pydantic ``ValidationError`` and polyfactory ``FactoryException`` (the third-party shapes a``PipeSignature`` mint can raise). The per-pipe step classifies **only** — no ``allowed_to_fail``check and no early raise; those live at the aggregate step.++ The dry run is done for ``caller_identity`` when one is known, so its job metadata states+ that caller — the pipe run opens its caller scope from it — and ``DRY_RUN_USER_ID`` only+ when the sweep belongs to nobody. It stores nothing either way: ``storage_scope`` stays+ ``DRY_RUN_STORAGE_SCOPE``."""try:pipe_job = await prepare_pipe_job(@@ -279,7 +330,8 @@ class BundleValidator:execution_config=execution_config,pipe_run_mode=PipeRunMode.DRY,pipeline_run_id=dry_run_pipeline_id,- user_id=DRY_RUN_USER_ID,+ user_id=caller_identity.user_id if caller_identity is not None else DRY_RUN_USER_ID,+ extras=caller_identity.extras if caller_identity is not None else None,# A dry run provably stores nothing, but `storage_scope` is# required — so it says so, loudly and greppably, instead of# inheriting a default. A silent default on this field isdiff --git a/pipelex/pipeline/direct_bundle_validator.py b/pipelex/pipeline/direct_bundle_validator.pyindex 5b384c757..6fddb8033 100644--- a/pipelex/pipeline/direct_bundle_validator.py+++ b/pipelex/pipeline/direct_bundle_validator.py@@ -23,6 +23,7 @@ if TYPE_CHECKING:from pipelex.base_exceptions import ErrorReportfrom pipelex.pipeline.validation_report import PipelexValidationReport+ from pipelex.system.caller_identity import CallerIdentityclass DirectBundleValidator:@@ -41,6 +42,7 @@ class DirectBundleValidator:mthds_sources: list[str] | None,allow_signatures: bool,library_dirs: Sequence[Path] | None,+ caller_identity: CallerIdentity | None,) -> PipelexValidationReport | ErrorReport:try:return await validate_bundles_in_process(@@ -49,6 +51,7 @@ class DirectBundleValidator:library_dirs=library_dirs,allow_signatures=allow_signatures,log_context="API validate",+ caller_identity=caller_identity,)except ValidateBundleError as exc:# An invalid bundle is a produced verdict, not a fault: surface its structureddiff --git a/pipelex/pipeline/execution_seams.py b/pipelex/pipeline/execution_seams.pyindex 49ada584c..9189f6329 100644--- a/pipelex/pipeline/execution_seams.py+++ b/pipelex/pipeline/execution_seams.py@@ -45,10 +45,10 @@ from pipelex.pipe_run.pipe_run_params import VariableMultiplicityfrom pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactoryfrom pipelex.pipeline.blueprint_selection import select_primary_blueprintfrom pipelex.pipeline.input_normalizer import normalize_data_urls_to_storage-from pipelex.system.analytics_groups import validate_analytics_groupsfrom pipelex.system.configuration.configs import PipelineExecutionConfigfrom pipelex.system.job_metadata import JobMetadata, OtelContext, RunMetadatafrom pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.system.run_extras import validate_run_extrasfrom pipelex.system.storage_scope import validate_storage_scopefrom pipelex.tools.misc.file_utils import reject_bare_str_or_path@@ -165,7 +165,7 @@ async def prepare_pipe_job(pipeline_run_id: str,user_id: str,storage_scope: str,- analytics_groups: dict[str, str] | None = None,+ extras: dict[str, str] | None = None,inputs: PipelineInputs | WorkingMemory | None = None,search_scope: str | None = None,trace_context: "TraceContext | None" = None,@@ -207,13 +207,13 @@ async def prepare_pipe_job(# This is deliberately not a "second gate": it is the FIRST one on this path.storage_scope = validate_storage_scope(value=storage_scope)- # And the groups beside it, for the same reason: `RunMetadata` is built at+ # And the extras beside it, for the same reason: `RunMetadata` is built at# the bottom of this function, below the data-url normalization that writes# to real storage, so validating only there refuses a malformed mapping# after the run has already put bytes in a bucket. `pipeline_run_setup`# validates earlier still — this is the first gate for the callers that# reach this seam directly (`bundle_validator`, `dry_run_in_process`).- analytics_groups = validate_analytics_groups(value=analytics_groups or {})+ extras = validate_run_extras(value=extras or {})working_memory: WorkingMemory | None = None@@ -296,7 +296,7 @@ async def prepare_pipe_job(# Already normalized to a mapping and validated at the top of this# function; the parameter stays nullable only so every existing call# site can keep omitting it.- analytics_groups=analytics_groups,+ extras=extras,),otel_context=otel_context,trace_context=trace_context,diff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.pyindex 8edadae7f..eeeff0367 100644--- a/pipelex/pipeline/pipeline_run_setup.py+++ b/pipelex/pipeline/pipeline_run_setup.py@@ -25,11 +25,11 @@ from pipelex.pipe_run.pipe_run_params import (from pipelex.pipeline.exceptions import PipeExecutionErrorfrom pipelex.pipeline.execution_seams import acquire_library, prepare_pipe_jobfrom pipelex.runtime_hub import get_event_log_override, get_otel_tracer, get_report_delegate, get_telemetry_manager-from pipelex.system.analytics_groups import validate_analytics_groupsfrom pipelex.system.configuration.configs import PipelineExecutionConfigfrom pipelex.system.environment import get_optional_envfrom pipelex.system.job_metadata import OtelContextfrom pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.system.run_extras import validate_run_extrasfrom pipelex.system.storage_scope import LOCAL_STORAGE_SCOPE, validate_storage_scopefrom pipelex.system.telemetry.events import EventName, EventPropertyfrom pipelex.system.telemetry.otel_constants import OTelConstants@@ -58,7 +58,7 @@ async def pipeline_run_setup(is_mock_usage: bool = False,user_id: str,storage_scope: str,- analytics_groups: dict[str, str] | None = None,+ extras: dict[str, str] | None = None,pipeline_run_id: str | None = None,request_id: str | None = None,inputs_base_dir: Path | None = None,@@ -125,14 +125,15 @@ async def pipeline_run_setup(Opaque prefix under which every byte this run writes must land. REQUIRED,validated at ``JobMetadata`` construction. See:mod:`pipelex.system.storage_scope`.- analytics_groups:- Opaque, host-supplied mapping of group type to group key that this run's- telemetry belongs to — the hosted platform sends its organization, a- single-user deployment sends nothing. Never read by name here. Validated+ extras:+ Opaque, host-supplied mapping of labels about this run — the hosted+ platform sends its organization, a single-user deployment sends nothing.+ Never read by name here; telemetry forwards it whole as the groups of+ each capture. Validatedat the TOP of this function, above the pipeline registration and abovethe trace-start event, so a malformed mapping registers nothing and- emits nothing. Optional, and omitting it leaves the group facet empty.- See :mod:`pipelex.system.analytics_groups`.+ emits nothing. Optional, and omitting it leaves the telemetry group facet empty.+ See :mod:`pipelex.system.run_extras`.pipeline_run_id:Pre-generated pipeline run ID. If provided, this ID is used instead ofgenerating a new one. Use this when the run record has already been created@@ -173,7 +174,7 @@ async def pipeline_run_setup(msg = "Either pipe_code or mthds_contents must be provided to the pipeline API."raise ValueError(msg)- # Validate the groups HERE, before this function causes anything observable.+ # Validate the extras HERE, before this function causes anything observable.## `RunMetadata` validates them too, and `prepare_pipe_job` validates them at# its own top — but BOTH run below `add_new_pipeline` and the open tracer, so@@ -184,7 +185,7 @@ async def pipeline_run_setup(## This is the same lesson `storage_scope` learned one seam lower, and the# same cure: ordering, not absence, was the defect.- analytics_groups = validate_analytics_groups(value=analytics_groups or {})+ extras = validate_run_extras(value=extras or {})# And the scope, for the same reason and with more at stake.#@@ -363,7 +364,7 @@ async def pipeline_run_setup(pipeline_run_id=pipeline_run_id,user_id=user_id,storage_scope=storage_scope,- analytics_groups=analytics_groups,+ extras=extras,inputs=inputs,search_scope=search_scope,trace_context=trace_context,diff --git a/pipelex/pipeline/runner.py b/pipelex/pipeline/runner.pyindex da307e78c..c6aee5f5d 100644--- a/pipelex/pipeline/runner.py+++ b/pipelex/pipeline/runner.py@@ -32,6 +32,7 @@ from pipelex.pipeline.pipeline_response import PipelexRunResultExecute, PipelexRfrom pipelex.pipeline.pipeline_run_setup import pipeline_run_setupfrom pipelex.pipeline.validate_in_process import validate_bundles_in_processfrom pipelex.runtime_hub import get_report_delegate, get_telemetry_manager+from pipelex.system.caller_identity import CallerIdentityfrom pipelex.system.storage_scope import LOCAL_STORAGE_SCOPE, LOCAL_USER_IDfrom pipelex.system.telemetry.events import EventName, EventProperty, Outcomefrom pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error@@ -119,10 +120,10 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):# by omission, because `pipeline_run_setup` requires both explicitly.user_id: str = LOCAL_USER_ID,storage_scope: str = LOCAL_STORAGE_SCOPE,- # Opaque groups the host attaches to every run this protocol starts.+ # Opaque labels the host attaches to every run this protocol starts.# No local default: a laptop belongs to no organization, and inventing- # a group here would put every such run into one shared entity.- analytics_groups: dict[str, str] | None = None,+ # a label here would put every such run into one shared entity.+ extras: dict[str, str] | None = None,execution_config: PipelineExecutionConfig | None = None,pipe_run: PipeRunProtocol | None = None,inputs_base_dir: Path | None = None,@@ -134,7 +135,7 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):self.is_mock_usage = is_mock_usageself.user_id = user_idself.storage_scope = storage_scope- self.analytics_groups = analytics_groups+ self.extras = extrasself.execution_config = execution_configself._pipe_run = pipe_run# Directory that bare relative local file paths in `inputs` resolve against (Smart Inputs@@ -142,6 +143,17 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):self.inputs_base_dir = inputs_base_dirself._running_tasks: dict[str, asyncio.Task[PipeOutput]] = {}+ @property+ def caller_identity(self) -> CallerIdentity:+ """The caller this protocol works for: the user and the groups every run it starts states.++ What a validation is attributed to, since a validation is not a run and has no+ `RunMetadata` of its own to carry them. A local runtime states `LOCAL_USER_ID`,+ which telemetry never attributes to a person, so a local validation still reports+ under the stream's fallback.+ """+ return CallerIdentity.make_from_host(user_id=self.user_id, extras=self.extras)+@overrideasync def execute(self,@@ -235,7 +247,7 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):is_mock_usage=self.is_mock_usage,user_id=self.user_id,storage_scope=self.storage_scope,- analytics_groups=self.analytics_groups,+ extras=self.extras,inputs_base_dir=self.inputs_base_dir,)effective_pipe_run = self._pipe_run or get_pipe_run()@@ -442,6 +454,7 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):allow_signatures=allow_signatures,graph_pipe_code=graph_pipe_code,log_context="Protocol validate",+ caller_identity=self.caller_identity,)@overridediff --git a/pipelex/pipeline/validate_bundle.py b/pipelex/pipeline/validate_bundle.pyindex 9cc7d225e..ef99249ad 100644--- a/pipelex/pipeline/validate_bundle.py+++ b/pipelex/pipeline/validate_bundle.py@@ -37,6 +37,7 @@ from pipelex.pipe_machinery.pipe_abstract import PipeAbstractfrom pipelex.pipe_run.exceptions import DryRunErrorfrom pipelex.pipeline.bundle_validator import BundleValidator, DryRunOutput, DryRunStatusfrom pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.system.caller_identity import CallerIdentityfrom pipelex.system.registries.exceptions import FuncRegistryError@@ -247,7 +248,14 @@ async def validate_bundle(library_dirs: Sequence[Path] | None = None,allow_signatures: bool = False,dry_run_pipe_codes: list[str] | None = None,+ caller_identity: CallerIdentity | None = None,) -> ValidateBundleResult:+ """Load one bundle into a fresh library and dry-run its pipes.++ ``caller_identity`` is who asked for the validation, when the host knows it; the dry-run+ sweep is attributed to that caller (see ``BundleValidator.validate_pipes``). ``None``+ inherits the caller already in scope, and with none the sweep belongs to nobody.+ """provided_params = sum([mthds_contents is not None,@@ -314,6 +322,7 @@ async def validate_bundle(pipes=_pipes_to_dry_run(loaded_pipes, dry_run_pipe_codes=dry_run_pipe_codes),library_id=library_id,allow_signatures=allow_signatures,+ caller_identity=caller_identity,)result = ValidateBundleResult(blueprints=loaded_blueprints,@@ -341,6 +350,7 @@ async def validate_bundle(pipes=_pipes_to_dry_run(loaded_pipes, dry_run_pipe_codes=dry_run_pipe_codes),library_id=library_id,allow_signatures=allow_signatures,+ caller_identity=caller_identity,)result = ValidateBundleResult(blueprints=loaded_blueprints,diff --git a/pipelex/pipeline/validate_in_process.py b/pipelex/pipeline/validate_in_process.pyindex 0d0990bb7..2cd5013de 100644--- a/pipelex/pipeline/validate_in_process.py+++ b/pipelex/pipeline/validate_in_process.py@@ -35,6 +35,7 @@ from pipelex.pipeline.input_form import qualify_current_library_cratefrom pipelex.pipeline.liftable_pipes import LiftablePipeEntry, build_liftable_pipesfrom pipelex.pipeline.validate_bundle import validate_bundlefrom pipelex.pipeline.validation_report import PipelexValidationReport, build_validation_report+from pipelex.system.caller_identity import CallerIdentity, scoped_caller_identityif TYPE_CHECKING:from pipelex.graph.graphspec import GraphSpec@@ -48,6 +49,7 @@ async def validate_bundles_in_process(allow_signatures: bool = False,graph_pipe_code: str | None = None,log_context: str = "validate",+ caller_identity: CallerIdentity | None = None,) -> PipelexValidationReport:"""Parse, validate, and dry-run MTHDS bundles in-process; assemble the canonical report.@@ -72,6 +74,10 @@ async def validate_bundles_in_process(selected bundle `main_pipe`. Bare and qualified refs are accepted accordingto the loaded pipe library's normal resolution rules.log_context: Label used in graph-arm degradation and teardown-failure logs.+ caller_identity: Who asked for the validation, when the host knows it. It is the+ ambient caller for the whole pass — the sweep's telemetry event and every dry run,+ the graph arm's included — so none of it falls back to the telemetry stream's+ configured id. ``None`` inherits the caller already in scope, if any.Returns:PipelexValidationReport with the structural artifacts of a valid bundle.@@ -79,6 +85,27 @@ async def validate_bundles_in_process(Raises:PipelexError: When the bundle is invalid (parse, static validation, or dry-run failure)."""+ with scoped_caller_identity(caller_identity=caller_identity):+ return await _validate_bundles_in_scope(+ mthds_contents=mthds_contents,+ mthds_sources=mthds_sources,+ library_dirs=library_dirs,+ allow_signatures=allow_signatures,+ graph_pipe_code=graph_pipe_code,+ log_context=log_context,+ )+++async def _validate_bundles_in_scope(+ *,+ mthds_contents: list[str],+ mthds_sources: list[str] | None,+ library_dirs: Sequence[Path] | None,+ allow_signatures: bool,+ graph_pipe_code: str | None,+ log_context: str,+) -> PipelexValidationReport:+ """The body of :func:`validate_bundles_in_process`, run inside the caller's scope."""# `validate_bundle` deliberately leaves its validation library OPEN and current on# success (the CLI surfaces consume it before process exit). This entry point is# long-lived, so restore the caller's current-library and tear the validation librarydiff --git a/pipelex/plugins/bundle_validator_registry.py b/pipelex/plugins/bundle_validator_registry.pyindex f6fc0c942..db9e6eaae 100644--- a/pipelex/plugins/bundle_validator_registry.py+++ b/pipelex/plugins/bundle_validator_registry.py@@ -30,6 +30,7 @@ from mthds.protocol.models import ValidationReportfrom pipelex.base_exceptions import ErrorReportfrom pipelex.runtime_bridge.orchestration_mode import OrchestrationMode+from pipelex.system.caller_identity import CallerIdentityif TYPE_CHECKING:from collections.abc import Sequence@@ -55,6 +56,13 @@ class BundleValidatorProtocol(Protocol):``library_dirs`` is host context the in-process arm needs to load the method library;a worker-dispatched arm ignores it — its worker loads its own library.++ ``caller_identity`` is who asked for the validation, as the host knows them: the user id+ and the analytics groups it would state on a run. It is required, with ``None`` meaning+ "nobody", so a host cannot forget it — a validation the host serves on a caller's behalf+ must attribute its telemetry to that caller, never to the deployment's configured+ fallback. A worker-dispatched arm carries it to the worker and hands it to the sweep+ there."""async def validate_bundles(@@ -64,6 +72,7 @@ class BundleValidatorProtocol(Protocol):mthds_sources: list[str] | None,allow_signatures: bool,library_dirs: "Sequence[Path] | None",+ caller_identity: CallerIdentity | None,) -> BundleValidationVerdict: ...diff --git a/pipelex/runtime_bridge/payloads.py b/pipelex/runtime_bridge/payloads.pyindex 72c4415c3..a21c3845b 100644--- a/pipelex/runtime_bridge/payloads.py+++ b/pipelex/runtime_bridge/payloads.py@@ -16,9 +16,9 @@ from pipelex.runtime_bridge.delivery_mode import DeliveryModefrom pipelex.runtime_bridge.orchestration_mode import DIRECT_ORCHESTRATION_MODE# Import-light by design (see module docstring): `storage_scope` and-# `analytics_groups` each pull in `re` and nothing else, so validating here+# `extras` each pull in `re` and nothing else, so validating here# costs the boundary nothing.-from pipelex.system.analytics_groups import validate_analytics_groups+from pipelex.system.run_extras import validate_run_extrasfrom pipelex.system.storage_scope import validate_storage_scope@@ -52,15 +52,15 @@ class PipelexPipeRunInput(BaseModel):"""return validate_storage_scope(value=value)- # The opaque groups this run's telemetry belongs to. Unlike the two fields- # above it DEFAULTS: a host with no groups to send invents nothing by+ # The opaque labels the host attaches to this run. Unlike the two fields+ # above it DEFAULTS: a host with no labels to send invents nothing by# staying silent, whereas a missing identity or scope used to be invented- # for it. See `pipelex.system.analytics_groups`.- analytics_groups: dict[str, str] = Field(default_factory=dict)+ # for it. See `pipelex.system.run_extras`.+ extras: dict[str, str] = Field(default_factory=dict)- @field_validator("analytics_groups")+ @field_validator("extras")@classmethod- def _validate_analytics_groups(cls, value: dict[str, str]) -> dict[str, str]:+ def _validate_run_extras(cls, value: dict[str, str]) -> dict[str, str]:"""Refuse a malformed mapping at the WIRE, not inside a telemetry capture.Declaring the field `dict[str, str]` says nothing about its contents,@@ -70,7 +70,7 @@ class PipelexPipeRunInput(BaseModel):carried it. Validating at construction makes it a decoding error namingthe field."""- return validate_analytics_groups(value=value)+ return validate_run_extras(value=value)library_crate_dump: dict[str, Any] | None = None# Two orthogonal axes: which orchestrator runs the pipe (open token, defaults to thediff --git a/pipelex/system/analytics_groups.py b/pipelex/system/analytics_groups.pydeleted file mode 100644index 10111aa26..000000000--- a/pipelex/system/analytics_groups.py+++ /dev/null@@ -1,128 +0,0 @@-"""`analytics_groups` — the opaque group labels a host attaches to a run.--**The runtime does not know what an organization is, and must not learn.** That-is the same rule `pipelex.system.storage_scope` states for where a run's bytes-go, and this module is its telemetry counterpart: a host that runs Pipelex for-many tenants needs a run's spans and events to belong to the entities that-tenant cares about, and Pipelex needs somewhere to put labels it will forward-without reading. `analytics_groups` is that somewhere — an opaque, host-supplied-mapping of group *type* to group *key* that the runtime carries on-`RunMetadata`, unread, for a telemetry consumer that understands groups to-forward. Carrying it unread is all this module does, but it is read downstream:-a run's mapping rides its spans as `pipelex.run.analytics_groups` and becomes-PostHog's own groups facet on the operator's stream and on Pipelex's own, so-whatever is put here is a live group key in those projects and a span attribute-on every OpenTelemetry export.--The hosted Pipelex platform fills it with `{"organization": "<org_id>"}`, but-nothing here knows or checks that: no key is privileged, and a deployment that-sends `{"tenant": …, "plan_tier": …}` is served identically. A single-user-deployment sends nothing at all.--**Why it carries groups and not free properties.** A telemetry backend gives an-event two different destinations. A *group* is an entity the event belongs to,-and it is what makes entity-level counts, funnels and retention possible after-the fact; a *property* is a free scalar on the event and can do none of that. A-generic extras bag would force the runtime to sort entries between the two, and-since it may not read a key by name it would have to send everything one way —-spending a backend's scarce group-type budget on values like a plan tier, or-losing entity analytics entirely. So the facet is named in the field. If a host-ever needs free properties on a run, that is a sibling field routed by facet,-and this one keeps its name and its meaning.--**Why the value is validated on the type.** The mapping is caller data that-arrives over a wire, so its contents are whatever the other side put there. It-is then quoted into log lines and forwarded to a telemetry backend, where a-newline is a log-forging primitive and an unbounded mapping is an unbounded-capture payload. Validating at construction — on `RunMetadata` and on the bridge-payload, through this one helper — means a malformed mapping is a decoding error-naming the field, at the edge, rather than a failure inside whichever capture-first tried to use it.--**Why an empty default is right here and was wrong for `storage_scope`.** An-absent group creates no shared namespace and misattributes nothing; it only-leaves the group facet empty. The doctrine that made `user_id` and-`storage_scope` non-defaulting is about identity and about storage keys, and-both of those still refuse to default.-"""--from __future__ import annotations--import re--# A group TYPE: the facet name, lowercase snake_case, starting with a letter.-#-# Deliberately narrower than the value charset. A group type is a schema-level-# name that a telemetry backend registers once and then shows in a picker, so it-# is written by whoever integrates the host, not derived from tenant data — the-# tight shape costs an integrator nothing and keeps a stray id out of the facet-# list. Applied with `fullmatch` (see below).-ANALYTICS_GROUP_TYPE_PATTERN = re.compile(r"^[a-z][a-z0-9_]{0,31}$")--# A group KEY: the identifier of one entity inside a type.-#-# This one IS tenant data — an org id, a workspace slug — so it admits both-# cases, digits, `_` and `-`, which covers every id shape the platform mints,-# and nothing else. No `/`, no `.`, no whitespace and no control character: the-# value is quoted into log lines and into capture payloads, and a newline in it-# is a log-forging primitive exactly as it is in a storage scope.-ANALYTICS_GROUP_KEY_PATTERN = re.compile(r"^[A-Za-z0-9_-]{1,128}$")--# How many group types one run may carry.-#-# A bound is needed because the mapping is unbounded caller input crossing a-# wire and is attached to every span of a run. It lands at five because that is-# where the most constrained consumer of the group facet sits — a telemetry-# backend typically registers a small fixed number of group types per project —-# so a sixth could not be honoured downstream anyway, and refusing it at the-# edge is more honest than forwarding a value that will be dropped in silence.-ANALYTICS_GROUPS_MAX_ENTRIES = 5---def validate_analytics_groups(*, value: dict[str, str]) -> dict[str, str]:- """Return `value` if it is a usable analytics-groups mapping, else raise `ValueError`.-- Args:- value: The host-supplied mapping of group type to group key. An empty- mapping is valid and means "this run belongs to no group".-- Returns:- The mapping, unchanged — this validator never normalizes, because the- runtime does not own the vocabulary and lowercasing a tenant's id would- silently address a different entity.-- Raises:- ValueError: the mapping holds more than `ANALYTICS_GROUPS_MAX_ENTRIES`- entries, or a key or a value falls outside its charset — which- covers the empty string, whitespace, control characters, and- anything that could forge a line in a log or a capture payload.- """- if len(value) > ANALYTICS_GROUPS_MAX_ENTRIES:- msg = (- f"Invalid analytics_groups: {len(value)} entries, at most {ANALYTICS_GROUPS_MAX_ENTRIES} are accepted. "- "Each entry is one group type a telemetry backend registers for the project, and that budget is "- "small and fixed — an entry beyond it could not be honoured downstream."- )- raise ValueError(msg)-- # `fullmatch`, NOT `match`. A trailing `$` in a `match` still admits one- # final newline, which is how `storage_scope` once let a newline travel into- # every storage key and log line built from it. The anchors below are- # therefore redundant but kept: the patterns are also read on their own.- for group_type, group_key in value.items():- if not ANALYTICS_GROUP_TYPE_PATTERN.fullmatch(group_type):- msg = (- f"Invalid analytics_groups group type {group_type!r} (a key of the mapping): expected lowercase "- "snake_case starting with a letter, at most 32 characters (e.g. 'organization'). A group type is a "- "facet name registered with the telemetry backend, not tenant data."- )- raise ValueError(msg)- if not ANALYTICS_GROUP_KEY_PATTERN.fullmatch(group_key):- msg = (- f"Invalid analytics_groups group key {group_key!r} for group type {group_type!r} (a value of the "- "mapping): expected 1 to 128 characters from [A-Za-z0-9_-] (e.g. 'org_acme'). The group key is "- "quoted into log lines and capture payloads, so whitespace, control characters and separators "- "are refused."- )- raise ValueError(msg)- return valuediff --git a/pipelex/system/caller_identity.py b/pipelex/system/caller_identity.pynew file mode 100644index 000000000..045ae0056--- /dev/null+++ b/pipelex/system/caller_identity.py@@ -0,0 +1,173 @@+"""`CallerIdentity` — who asked for the work in progress, and what they belong to.++**The run is not the only place a caller is known.** `RunMetadata` carries the+caller of a run, and every capture a run emits hands it over explicitly. But a+host also serves work that is not a run — a validation sweep, whose dry runs+exist only to check a bundle — and a crash reaches the interpreter's exception+hooks with nothing but `(type, value, traceback)`. Before this module both+reported under the stream's configured fallback, so on a hosted plane every+validation and every crash landed on one constant id per deployment while the+caller who caused it was known all along.++**Two facts, one object.** A caller is the `user_id` the host states and the+opaque `extras` it attaches — the same two facts `RunMetadata` holds,+without the per-run fields (`pipeline_run_id`, `storage_scope`) that work which+is not a run does not have. Whether a given `user_id` may be attributed to a+person is not decided here: telemetry decides it, once, in+:mod:`pipelex.system.telemetry.telemetry_identity`, so a placeholder such as+`"local"` travels as it is and still resolves to the stream's fallback.++**The ambient caller.** :func:`scoped_caller_identity` makes a caller the+current one for the duration of a block, through a `ContextVar`, so a capture+that has no run in hand — the validation sweep's event, an exception captured+while a pipe runs — reads it instead of falling back. A pipe run opens that+scope from its own `RunMetadata`, so every pipe, at every depth, is covered.++**An exception remembers the caller it escaped from.** By the time an unhandled+exception reaches `sys.excepthook` the stack has unwound and every scope has+closed, so the `ContextVar` alone would always be empty there. The scope+therefore stamps an exception that leaves it with the caller it was serving —+the innermost scope wins, an outer one never overwrites it — and the capture+reads the stamp back, walking the cause and context chain, because a host+usually re-raises its own error `from` the one that escaped the run.+"""++from contextvars import ContextVar, Token+from types import TracebackType+from typing import TYPE_CHECKING++from pydantic import BaseModel, ConfigDict, Field, field_validator++from pipelex.system.run_extras import validate_run_extras++if TYPE_CHECKING:+ from pipelex.system.job_metadata import RunMetadata++# The attribute an exception carries the caller it escaped from under. Namespaced,+# so it can never collide with an attribute an exception class defines itself.+_CALLER_IDENTITY_STAMP = "__pipelex_caller_identity__"+++class CallerIdentity(BaseModel):+ """The caller a piece of work is done for: a user and the extras the host attaches.++ Frozen, and the extras are validated at construction exactly as+ `RunMetadata.extras` is, because they reach a telemetry backend.+ """++ model_config = ConfigDict(frozen=True)++ # The host's own id for the caller, as `RunMetadata.user_id` states it.+ # Placeholders are legal and travel unchanged: whether this id may name a+ # person is decided by telemetry, not here.+ user_id: str++ # The opaque labels the host attaches to the caller — see `pipelex.system.run_extras`.+ extras: dict[str, str] = Field(default_factory=dict)++ @field_validator("extras")+ @classmethod+ def _validate_extras(cls, value: dict[str, str]) -> dict[str, str]:+ return validate_run_extras(value=value)++ @classmethod+ def make_from_run_metadata(cls, *, run_metadata: "RunMetadata") -> "CallerIdentity":+ """The caller of a run, read from the run half of its job metadata."""+ return cls(user_id=run_metadata.user_id, extras=dict(run_metadata.extras))++ @classmethod+ def make_from_host(cls, *, user_id: str, extras: dict[str, str] | None) -> "CallerIdentity":+ """The caller a host states, with no extras meaning an empty mapping."""+ return cls(user_id=user_id, extras=dict(extras or {}))+++_current_caller_identity: ContextVar[CallerIdentity | None] = ContextVar("current_caller_identity", default=None)+++def get_current_caller_identity() -> CallerIdentity | None:+ """The caller of the work in progress in this context, or None when no scope is open."""+ return _current_caller_identity.get()+++class CallerIdentityScope:+ """The context manager behind :func:`scoped_caller_identity`.++ A class rather than a `@contextmanager` generator because it must see the+ exception leaving the block — to stamp it — without catching it: `__exit__`+ receives it and returns None, so it propagates untouched.+ """++ def __init__(self, caller_identity: CallerIdentity | None) -> None:+ self._caller_identity = caller_identity+ self._token: Token[CallerIdentity | None] | None = None++ def __enter__(self) -> CallerIdentity | None:+ if self._caller_identity is not None:+ self._token = _current_caller_identity.set(self._caller_identity)+ return get_current_caller_identity()++ def __exit__(+ self,+ exc_type: type[BaseException] | None,+ exc_value: BaseException | None,+ exc_traceback: TracebackType | None,+ ) -> None:+ if self._token is None:+ return+ if exc_value is not None and self._caller_identity is not None:+ stamp_caller_identity(exception=exc_value, caller_identity=self._caller_identity)+ _current_caller_identity.reset(self._token)+ self._token = None+++def scoped_caller_identity(*, caller_identity: CallerIdentity | None) -> CallerIdentityScope:+ """Make `caller_identity` the current caller for the duration of a `with` block.++ `None` opens no scope at all: the block inherits whatever caller is already+ current, which is what a caller-less entry point nested in a caller's work+ should see.+ """+ return CallerIdentityScope(caller_identity)+++def stamp_caller_identity(*, exception: BaseException, caller_identity: CallerIdentity) -> None:+ """Record on `exception` the caller it escaped from, unless a closer scope already did.++ The innermost scope is the one that knows the work the error came from, so+ an existing stamp is never replaced. An exception type that refuses new+ attributes simply goes unstamped: telemetry must never change how an error+ propagates.+ """+ if hasattr(exception, _CALLER_IDENTITY_STAMP):+ return+ try:+ setattr(exception, _CALLER_IDENTITY_STAMP, caller_identity)+ except (AttributeError, TypeError):+ # An exception type with `__slots__` or a read-only `__setattr__` cannot carry the stamp.+ return+++def find_stamped_caller_identity(*, exception: BaseException) -> CallerIdentity | None:+ """The caller `exception` escaped from, read from it or from any error it links to.++ Walks `__cause__`, `__context__` and the members of an exception group, as+ PostHog's own capture does, because a host that catches a run's error+ usually raises its own `from` it, and that outer error is what reaches the+ interpreter hook. A loop and not a recursion, so a long chain cannot fail the+ lookup, and a seen-set so a cyclic chain cannot loop forever.+ """+ pending: list[BaseException | None] = [exception]+ visited: set[int] = set()+ while pending:+ current = pending.pop()+ if current is None or id(current) in visited:+ continue+ visited.add(id(current))+ stamped = getattr(current, _CALLER_IDENTITY_STAMP, None)+ if isinstance(stamped, CallerIdentity):+ return stamped+ pending.append(current.__context__)+ pending.append(current.__cause__)+ if isinstance(current, BaseExceptionGroup):+ pending.extend(current.exceptions) # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType]+ return Nonediff --git a/pipelex/system/job_metadata.py b/pipelex/system/job_metadata.pyindex 356233122..32678c372 100644--- a/pipelex/system/job_metadata.py+++ b/pipelex/system/job_metadata.py@@ -4,7 +4,7 @@ from typing import Anyfrom pydantic import BaseModel, ConfigDict, Field, field_validator-from pipelex.system.analytics_groups import validate_analytics_groups+from pipelex.system.run_extras import validate_run_extrasfrom pipelex.system.storage_scope import validate_storage_scopefrom pipelex.system.telemetry.otel_context import OtelContextfrom pipelex.system.trace_context import TraceContext@@ -71,13 +71,13 @@ class RunMetadata(BaseModel):here rather than a check at construction that a later assignment undoes.Nothing ever needed to reassign one — these are the facts that are constantfor a whole run, which is the definition this class exists to draw — and- since telemetry began forwarding ``analytics_groups`` to a backend and+ since telemetry began forwarding ``extras`` to a backend andcomposing ``storage_scope`` into storage keys, "validated at construction"has to mean "validated, full stop".**What the freeze does not close**, named here so nobody mistakes any of itfor closed. Freezing refuses a REASSIGNMENT and nothing else, so an in-place- edit of the mapping (``run_metadata.analytics_groups[k] = v``) still reaches+ edit of the mapping (``run_metadata.extras[k] = v``) still reachesa backend unvalidated, and pydantic's two deliberate bypasses —``model_copy(update=...)`` and ``model_construct`` — still build an instancewithout running a validator. The runtime does none of the three, and a@@ -118,18 +118,18 @@ class RunMetadata(BaseModel):# characters into the log lines or ``ErrorReport`` envelopes that quote it.request_id: str | None = Field(default=None, max_length=128, pattern=r"^[\x20-\x7E]+$")- # The opaque groups this run's telemetry belongs to, supplied by the host.- # Forwarded to whichever consumer understands groups and never read by name- # — see `pipelex.system.analytics_groups` for why the host's own concepts+ # The opaque labels the host attaches to this run. Never read by name;+ # telemetry forwards the whole mapping as the groups of each capture+ # — see `pipelex.system.run_extras` for why the host's own concepts# (organization, tenant, plan tier) deliberately do not cross this boundary,# and for the charset and the size bound.## It DEFAULTS, unlike `user_id` and `storage_scope` above, and the asymmetry# is the point: those two refuse to default because a missing identity once- # became a present-looking one and a shared storage prefix. An absent group+ # became a present-looking one and a shared storage prefix. An absent label# creates no namespace and misattributes nothing — it only leaves the group- # facet empty — so a caller with no groups to send says nothing.- analytics_groups: dict[str, str] = Field(default_factory=dict)+ # facet empty — so a caller with no labels to send says nothing.+ extras: dict[str, str] = Field(default_factory=dict)@field_validator("storage_scope")@classmethod@@ -146,9 +146,9 @@ class RunMetadata(BaseModel):"""return validate_storage_scope(value=value)- @field_validator("analytics_groups")+ @field_validator("extras")@classmethod- def _validate_analytics_groups(cls, value: dict[str, str]) -> dict[str, str]:+ def _validate_run_extras(cls, value: dict[str, str]) -> dict[str, str]:"""Refuse a mapping the runtime could not safely forward, at construction.On the TYPE for the same reason as `storage_scope`: the value is caller@@ -161,12 +161,12 @@ class RunMetadata(BaseModel):The guarantee stops at construction, and deliberately so. The model isfrozen, so reassigning the field raises — but freezing does not reachinside the mapping, and mutating it in place- (`run_metadata.analytics_groups[k] = v`) still bypasses this validator.+ (`run_metadata.extras[k] = v`) still bypasses this validator.See the class docstring for that hole and for pydantic's two others.Nothing in the runtime mutates the mapping after construction; a futureconsumer that forwards it must not start."""- return validate_analytics_groups(value=value)+ return validate_run_extras(value=value)class JobMetadata(BaseModel):diff --git a/pipelex/system/run_extras.py b/pipelex/system/run_extras.pynew file mode 100644index 000000000..d807bedb1--- /dev/null+++ b/pipelex/system/run_extras.py@@ -0,0 +1,122 @@+"""`extras` — the opaque labels a host attaches to a run.++**The runtime does not know what an organization is, and must not learn.** That+is the same rule `pipelex.system.storage_scope` states for where a run's bytes+go, and this module is its counterpart for everything else a host wants to say+about a run: a host that runs Pipelex for many tenants needs a run to carry the+host's own labels — which organization, which workspace — and Pipelex needs+somewhere to put labels it will forward without reading. `extras` is that+somewhere — an opaque, host-supplied mapping of string key to string value that+the runtime carries on `RunMetadata`, unread. The run model and the job+preparation signatures therefore name no host concept and no consumer: the+library never reads a key by name, and nothing here says what the labels are for.++**Where the labels go today.** Carrying the mapping unread is all this module+does, but it is read downstream: the telemetry layer writes a run's mapping onto+its spans as `pipelex.run.extras` and forwards it, whole, as the groups of each+PostHog capture — on the operator's stream and on Pipelex's own — because PostHog+is the backend that supports grouping. So whatever is put here is a live group+key in those projects and a span attribute on every OpenTelemetry export, and the+bounds below are shaped by that consumer.++The hosted Pipelex platform fills it with `{"organization": "<org_id>"}`, but+nothing here knows or checks that: no key is privileged, and a deployment that+sends `{"tenant": …, "workspace": …}` is served identically. A single-user+deployment sends nothing at all.++**Why the value is validated on the type.** The mapping is caller data that+arrives over a wire, so its contents are whatever the other side put there. It+is then quoted into log lines and forwarded to a telemetry backend, where a+newline is a log-forging primitive and an unbounded mapping is an unbounded+capture payload. Validating at construction — on `RunMetadata` and on the bridge+payload, through this one helper — means a malformed mapping is a decoding error+naming the field, at the edge, rather than a failure inside whichever capture+first tried to use it.++**Why an empty default is right here and was wrong for `storage_scope`.** An+absent label creates no shared namespace and misattributes nothing; it only+leaves the downstream group facet empty. The doctrine that made `user_id` and+`storage_scope` non-defaulting is about identity and about storage keys, and+both of those still refuse to default.+"""++from __future__ import annotations++import re++# An extras KEY: lowercase snake_case, starting with a letter.+#+# Deliberately narrower than the value charset. The key is forwarded as a group+# type, a schema-level name a telemetry backend registers once and then shows in+# a picker, so it is written by whoever integrates the host, not derived from+# tenant data — the tight shape costs an integrator nothing and keeps a stray id+# out of the facet list. Applied with `fullmatch` (see below).+RUN_EXTRAS_KEY_PATTERN = re.compile(r"^[a-z][a-z0-9_]{0,31}$")++# An extras VALUE: typically the identifier of one of the host's entities.+#+# This one IS tenant data — an org id, a workspace slug — so it admits both+# cases, digits, `_` and `-`, which covers every id shape the platform mints,+# and nothing else. No `/`, no `.`, no whitespace and no control character: the+# value is quoted into log lines and into capture payloads, and a newline in it+# is a log-forging primitive exactly as it is in a storage scope.+RUN_EXTRAS_VALUE_PATTERN = re.compile(r"^[A-Za-z0-9_-]{1,128}$")++# How many entries one run's extras may carry.+#+# A bound is needed because the mapping is unbounded caller input crossing a+# wire and is attached to every span of a run. It lands at five because that is+# where the most constrained consumer sits — every entry is forwarded as a group+# type, and a telemetry backend typically registers a small fixed number of group+# types per project — so a sixth could not be honoured downstream anyway, and+# refusing it at the edge is more honest than forwarding a value that will be+# dropped in silence.+RUN_EXTRAS_MAX_ENTRIES = 5+++def validate_run_extras(*, value: dict[str, str]) -> dict[str, str]:+ """Return `value` if it is a usable run-extras mapping, else raise `ValueError`.++ Args:+ value: The host-supplied mapping of opaque key to opaque value. An empty+ mapping is valid and means "the host attaches no labels to this run".++ Returns:+ The mapping, unchanged — this validator never normalizes, because the+ runtime does not own the vocabulary and lowercasing a tenant's id would+ silently address a different entity.++ Raises:+ ValueError: the mapping holds more than `RUN_EXTRAS_MAX_ENTRIES`+ entries, or a key or a value falls outside its charset — which+ covers the empty string, whitespace, control characters, and+ anything that could forge a line in a log or a capture payload.+ """+ if len(value) > RUN_EXTRAS_MAX_ENTRIES:+ msg = (+ f"Invalid extras: {len(value)} entries, at most {RUN_EXTRAS_MAX_ENTRIES} are accepted. "+ "Each entry is forwarded as one group type a telemetry backend registers for the project, and that "+ "budget is small and fixed — an entry beyond it could not be honoured downstream."+ )+ raise ValueError(msg)++ # `fullmatch`, NOT `match`. A trailing `$` in a `match` still admits one+ # final newline, which is how `storage_scope` once let a newline travel into+ # every storage key and log line built from it. The anchors below are+ # therefore redundant but kept: the patterns are also read on their own.+ for extras_key, extras_value in value.items():+ if not RUN_EXTRAS_KEY_PATTERN.fullmatch(extras_key):+ msg = (+ f"Invalid extras key {extras_key!r}: expected lowercase snake_case starting with a letter, "+ "at most 32 characters (e.g. 'organization'). A key is forwarded as a facet name registered with "+ "the telemetry backend, not tenant data."+ )+ raise ValueError(msg)+ if not RUN_EXTRAS_VALUE_PATTERN.fullmatch(extras_value):+ msg = (+ f"Invalid extras value {extras_value!r} for key {extras_key!r}: expected 1 to 128 characters "+ "from [A-Za-z0-9_-] (e.g. 'org_acme'). The value is quoted into log lines and capture payloads, "+ "so whitespace, control characters and separators are refused."+ )+ raise ValueError(msg)+ return valuediff --git a/pipelex/system/telemetry/exception_capture.py b/pipelex/system/telemetry/exception_capture.pyindex 79e2769da..b1c80ab8b 100644--- a/pipelex/system/telemetry/exception_capture.py+++ b/pipelex/system/telemetry/exception_capture.py@@ -4,8 +4,9 @@ from types import TracebackTypefrom typing import TYPE_CHECKINGfrom pipelex import log+from pipelex.system.caller_identity import CallerIdentity, find_stamped_caller_identity, get_current_caller_identityfrom pipelex.system.telemetry.otel_constants import PostHogAttr-from pipelex.system.telemetry.telemetry_identity import TelemetryIdentity+from pipelex.system.telemetry.telemetry_identity import StreamIdentityRule, TelemetryIdentityif TYPE_CHECKING:# Deferred import: avoid pulling heavy SDK at module-load time@@ -20,10 +21,13 @@ class DualClientExceptionCapture:this implementation sends to both custom and Pipelex PostHog clients.**An `$exception` is attributed like every other capture.** It is resolved- through `TelemetryIdentity` rather than from a raw id, because the two- interpreter hooks below are handed nothing but `(type, value, traceback)`:- they cannot see the run that was in flight, so what they send is the runless- identity of the stream, resolved once here. That resolution is what makes+ through `TelemetryIdentity` rather than from a raw id, and per capture rather+ than once: the two interpreter hooks below are handed nothing but+ `(type, value, traceback)`, so the caller is read back from the error itself+ — the caller of the pipe run it escaped, stamped on it by+ :func:`~pipelex.system.caller_identity.scoped_caller_identity` — and failing+ that from the caller still in scope. Only an error that belongs to no caller+ goes out under the stream's fallback. That resolution is also what makes`anonymous` mode mean the same thing on this path as on every other — a modethat identifies nobody must not identify somebody when the process crashes."""@@ -35,14 +39,14 @@ class DualClientExceptionCapture:def __init__(self,custom_posthog_client: "Posthog | None",- custom_identity: TelemetryIdentity,+ custom_identity_rule: StreamIdentityRule,pipelex_posthog_client: "Posthog | None",- pipelex_identity: TelemetryIdentity,+ pipelex_identity_rule: StreamIdentityRule,):self._custom_client = custom_posthog_client- self._custom_identity = custom_identity+ self._custom_identity_rule = custom_identity_ruleself._pipelex_client = pipelex_posthog_client- self._pipelex_identity = pipelex_identity+ self._pipelex_identity_rule = pipelex_identity_rule# Save original hooksself._original_excepthook = sys.excepthook@@ -92,6 +96,8 @@ class DualClientExceptionCapture:if self.is_marked_as_captured(exception=exc_value):return+ caller_identity = self.resolve_caller_identity(exception=exc_value)+# Create the properly typed tuple for PostHogposthog_exc_info: tuple[type[BaseException], BaseException, TracebackType | None] = (exc_type,@@ -103,7 +109,7 @@ class DualClientExceptionCapture:if self._custom_client:self._capture_to_client(client=self._custom_client,- identity=self._custom_identity,+ identity=self._custom_identity_rule.resolve(caller_identity=caller_identity),posthog_exc_info=posthog_exc_info,stream_name="custom",)@@ -113,11 +119,22 @@ class DualClientExceptionCapture:self._forget_posthog_capture_marks(exc_value=exc_value)self._capture_to_client(client=self._pipelex_client,- identity=self._pipelex_identity,+ identity=self._pipelex_identity_rule.resolve(caller_identity=caller_identity),posthog_exc_info=posthog_exc_info,stream_name="Pipelex",)+ @classmethod+ def resolve_caller_identity(cls, *, exception: BaseException) -> CallerIdentity | None:+ """The caller an error is attributed to: the one it escaped from, else the one in scope, else nobody.++ The stamp comes first because it is the only one that survives the+ unwinding: by the time an error reaches an interpreter hook every scope+ it crossed has closed. The ambient caller answers for an error raised+ where a scope is still open — a thread that inherited a caller's context.+ """+ return find_stamped_caller_identity(exception=exception) or get_current_caller_identity()+def _capture_to_client(self,*,diff --git a/pipelex/system/telemetry/otel_constants.py b/pipelex/system/telemetry/otel_constants.pyindex d52aaa01b..cfcfcf661 100644--- a/pipelex/system/telemetry/otel_constants.py+++ b/pipelex/system/telemetry/otel_constants.py@@ -123,12 +123,12 @@ class PipelexSpanAttr(StrEnum):# The run's identity, set at every span site from `RunMetadata` so the identity# rides the span object to every exporter instead of being correlated back to a- # run through shared state. RUN_USER_ID is who started the run; the groups are+ # run through shared state. RUN_USER_ID is who started the run; RUN_EXTRAS is# the host's opaque labels, serialized as a JSON string because an OTel attribute- # is a scalar or a homogeneous list, never a mapping. The groups attribute is+ # is a scalar or a homogeneous list, never a mapping. The extras attribute is# omitted entirely when a run carries none.RUN_USER_ID = "pipelex.run.user_id"- RUN_ANALYTICS_GROUPS = "pipelex.run.analytics_groups"+ RUN_EXTRAS = "pipelex.run.extras"class LangfuseSpanAttr(StrEnum):diff --git a/pipelex/system/telemetry/telemetry_identity.py b/pipelex/system/telemetry/telemetry_identity.pyindex c6bf34884..3ede5c02e 100644--- a/pipelex/system/telemetry/telemetry_identity.py+++ b/pipelex/system/telemetry/telemetry_identity.py@@ -6,9 +6,11 @@ own stream, the gateway-key hash on Pipelex's — and before this module every sand every event carried that one id. On a host that serves many callers from oneprocess that is exactly wrong: every tenant's generations land under one identityper deployment. The runtime already knows who each run belongs to, on-`RunMetadata.user_id`, and what it belongs to, on `RunMetadata.analytics_groups`;-this module is the single place that turns those two facts into what a capture-needs.+`RunMetadata.user_id`, and the host's opaque labels about it, on+`RunMetadata.extras`; this module is the single place that turns those two+facts into what a capture needs. The extras are forwarded whole as the capture's+groups — the runtime reads no key by name — because PostHog, the backend these+captures go to, is the one that supports grouping.**One resolution, applied everywhere.** The exporter resolves per span, thetracker per event, and both go through `TelemetryIdentity` so they cannot drift.@@ -18,20 +20,24 @@ are two — the enum below says which stream carries which, and why:1. `NONE` — the capture is anonymous whatever the run says, and the caller marksit so. No user, no fallback, no groups.2. `DIRECT` — the run's own `user_id` is the `distinct_id`, spelled as the- operator's own backend already knows it, and the run's groups ride the- capture.+ operator's own backend already knows it, and the run's extras ride the+ capture as its groups.**A run that names nobody** reports under the stream's configured fallback, and-so does an event that belongs to no run at all — a CLI command, a dry-run sweep.+so does an event that belongs to no caller at all — a CLI command, a local+dry-run sweep. An event emitted outside a run but on a known caller's behalf —+a hosted validation sweep, an exception raised while a pipe ran — is not such an+event: it resolves from the ambient :class:`~pipelex.system.caller_identity.CallerIdentity`+the host or the pipe run put in scope, exactly as a run's own event would.`RunMetadata.user_id` is required, but some of its values name a caller withoutdistinguishing one; see `_NON_DISTINGUISHING_RUN_USER_IDS` below. This is why alocal run keeps reporting exactly as it did before per-run attribution existed.-Under `DIRECT` the run's groups still ride such a capture: a host may know which+Under `DIRECT` the run's extras still ride such a capture: a host may know whichentities a run belongs to without naming its caller, and the two facts areindependent.**Where the identity is NOT.** The user id goes on the capture as `distinct_id`-and the groups go through the capture's `groups` argument. Neither is ever copied+and the run's extras go through the capture's `groups` argument. Neither is ever copiedinto an event property or a span name: one field, one meaning, and a second copyis a second thing to keep in step."""@@ -42,6 +48,7 @@ from typing import TYPE_CHECKING, Any, Mappingfrom pydantic import BaseModel, ConfigDict, Field+from pipelex.system.caller_identity import CallerIdentityfrom pipelex.system.storage_scope import DRY_RUN_USER_ID, LOCAL_USER_ID, SINGLE_TENANT_USER_IDfrom pipelex.system.telemetry.otel_constants import LangfuseSpanAttr, PipelexSpanAttrfrom pipelex.system.telemetry.telemetry_config import PostHogMode@@ -105,7 +112,7 @@ def make_run_identity_span_attributes(*, run_metadata: "RunMetadata", is_langfusCalled at each span site from the `JobMetadata` already in hand, so theidentity travels on the span object through the batch processor: no exporterhas to correlate a span back to a run through shared state, and every- exporter sees the same fact. PostHog is the one that reads the groups as+ exporter sees the same fact. PostHog is the one that reads the extras asgroup identity; Langfuse gets the user id in the field it reserves for it,which it has defined and never received until now.@@ -116,8 +123,8 @@ def make_run_identity_span_attributes(*, run_metadata: "RunMetadata", is_langfusthe same value.Returns:- The attributes to merge into the span's attribute dict. The groups entry- is absent — not empty — when the run carries no groups. `pipelex.run.user_id`+ The attributes to merge into the span's attribute dict. The extras entry+ is absent — not empty — when the run carries no extras. `pipelex.run.user_id`is written as the run states it, placeholders included: a span attributerecords what the run IS, and whether that value may be attributed to aperson is a separate decision, taken once in `_resolve` below. Langfuse's@@ -126,8 +133,8 @@ def make_run_identity_span_attributes(*, run_metadata: "RunMetadata", is_langfusthan becoming a person named `local` in the operator's project."""attributes: dict[str, str] = {PipelexSpanAttr.RUN_USER_ID: run_metadata.user_id}- if run_metadata.analytics_groups:- attributes[PipelexSpanAttr.RUN_ANALYTICS_GROUPS] = pure_json_str(data=run_metadata.analytics_groups)+ if run_metadata.extras:+ attributes[PipelexSpanAttr.RUN_EXTRAS] = pure_json_str(data=run_metadata.extras)if is_langfuse_enabled and run_metadata.user_id not in _NON_DISTINGUISHING_RUN_USER_IDS:attributes[LangfuseSpanAttr.USER_ID] = run_metadata.user_idreturn attributes@@ -146,7 +153,7 @@ class TelemetryIdentity(BaseModel):distinct_id: str | None = None# The entities the capture belongs to, forwarded through the backend's own- # groups facet. Empty on an anonymous capture, which has no person for a+ # groups facet: the run's `extras`, whole and unread. Empty on an anonymous capture, which has no person for a# group to qualify.groups: dict[str, str] = Field(default_factory=dict)@@ -165,7 +172,7 @@ class TelemetryIdentity(BaseModel):cls,*,run_user_id: str | None,- run_groups: dict[str, str] | None,+ run_extras: dict[str, str] | None,fallback_distinct_id: str | None,run_identity_policy: RunIdentityPolicy,) -> "TelemetryIdentity":@@ -178,7 +185,7 @@ class TelemetryIdentity(BaseModel):resolved_distinct_id = distinguishing_user_id or fallback_distinct_idif not resolved_distinct_id:return cls.make_anonymous()- return cls(distinct_id=resolved_distinct_id, groups=dict(run_groups or {}))+ return cls(distinct_id=resolved_distinct_id, groups=dict(run_extras or {}))@classmethoddef make_from_run_metadata(@@ -199,7 +206,34 @@ class TelemetryIdentity(BaseModel):"""return cls._resolve(run_user_id=run_metadata.user_id if run_metadata is not None else None,- run_groups=run_metadata.analytics_groups if run_metadata is not None else None,+ run_extras=run_metadata.extras if run_metadata is not None else None,+ fallback_distinct_id=fallback_distinct_id,+ run_identity_policy=run_identity_policy,+ )++ @classmethod+ def make_from_caller_identity(+ cls,+ *,+ caller_identity: CallerIdentity | None,+ fallback_distinct_id: str | None,+ run_identity_policy: RunIdentityPolicy,+ ) -> "TelemetryIdentity":+ """Resolve the attribution of a capture, from the caller it was made for.++ The same resolution as `make_from_run_metadata`, for a capture whose+ caller is known without a run in hand: a validation sweep, or an+ exception raised while a pipe ran.++ Args:+ caller_identity: The caller, or None when the capture belongs to no+ caller at all, which resolves to the stream's fallback.+ fallback_distinct_id: The identity this stream falls back to.+ run_identity_policy: What this stream may do with the caller's identity.+ """+ return cls._resolve(+ run_user_id=caller_identity.user_id if caller_identity is not None else None,+ run_extras=caller_identity.extras if caller_identity is not None else None,fallback_distinct_id=fallback_distinct_id,run_identity_policy=run_identity_policy,)@@ -221,14 +255,14 @@ class TelemetryIdentity(BaseModel):run_user_id = attributes.get(PipelexSpanAttr.RUN_USER_ID)return cls._resolve(run_user_id=run_user_id if isinstance(run_user_id, str) else None,- run_groups=cls._read_groups_attribute(attributes=attributes),+ run_extras=cls._read_extras_attribute(attributes=attributes),fallback_distinct_id=fallback_distinct_id,run_identity_policy=run_identity_policy,)@classmethod- def _read_groups_attribute(cls, *, attributes: Mapping[str, Any]) -> dict[str, str]:- """Read back the groups a span site serialized, refusing anything else.+ def _read_extras_attribute(cls, *, attributes: Mapping[str, Any]) -> dict[str, str]:+ """Read back the extras a span site serialized, refusing anything else.The value was written by `make_run_identity_span_attributes` from analready-validated mapping, so a shape other than a JSON object of strings@@ -236,24 +270,47 @@ class TelemetryIdentity(BaseModel):app, so that is a debug line and an empty mapping — the span stillexports, attributed to the run's user without its groups."""- raw = attributes.get(PipelexSpanAttr.RUN_ANALYTICS_GROUPS)+ raw = attributes.get(PipelexSpanAttr.RUN_EXTRAS)if raw is None:return {}if not isinstance(raw, str):- log.debug(f"Ignoring span attribute '{PipelexSpanAttr.RUN_ANALYTICS_GROUPS}': expected a JSON string, got {type(raw).__name__}")+ log.debug(f"Ignoring span attribute '{PipelexSpanAttr.RUN_EXTRAS}': expected a JSON string, got {type(raw).__name__}")return {}try:decoded = json.loads(raw)except ValueError as exc:- log.debug(f"Ignoring span attribute '{PipelexSpanAttr.RUN_ANALYTICS_GROUPS}': not decodable JSON ({exc})")+ log.debug(f"Ignoring span attribute '{PipelexSpanAttr.RUN_EXTRAS}': not decodable JSON ({exc})")return {}if not isinstance(decoded, dict):- log.debug(f"Ignoring span attribute '{PipelexSpanAttr.RUN_ANALYTICS_GROUPS}': expected a JSON object, got {type(decoded).__name__}")+ log.debug(f"Ignoring span attribute '{PipelexSpanAttr.RUN_EXTRAS}': expected a JSON object, got {type(decoded).__name__}")return {}- groups: dict[str, str] = {}- for group_type, group_key in decoded.items(): # type: ignore[union-attr]- if isinstance(group_type, str) and isinstance(group_key, str):- groups[group_type] = group_key+ extras: dict[str, str] = {}+ for extras_key, extras_value in decoded.items(): # type: ignore[union-attr]+ if isinstance(extras_key, str) and isinstance(extras_value, str):+ extras[extras_key] = extras_valueelse:- log.debug(f"Ignoring a non-string entry in span attribute '{PipelexSpanAttr.RUN_ANALYTICS_GROUPS}'")- return groups+ log.debug(f"Ignoring a non-string entry in span attribute '{PipelexSpanAttr.RUN_EXTRAS}'")+ return extras+++class StreamIdentityRule(BaseModel):+ """How one stream attributes a capture: the id it falls back to, and what it may do with a caller.++ The two settings every resolution takes, held together for the one path+ that cannot resolve when it is built: the exception autocapture learns the+ caller only when an error arrives, so it keeps each stream's rule and+ resolves per capture instead of holding an identity decided up front.+ """++ model_config = ConfigDict(frozen=True)++ fallback_distinct_id: str | None = None+ run_identity_policy: RunIdentityPolicy++ def resolve(self, *, caller_identity: CallerIdentity | None) -> TelemetryIdentity:+ """The identity a capture made for `caller_identity` goes out under on this stream."""+ return TelemetryIdentity.make_from_caller_identity(+ caller_identity=caller_identity,+ fallback_distinct_id=self.fallback_distinct_id,+ run_identity_policy=self.run_identity_policy,+ )diff --git a/pipelex/system/telemetry/telemetry_manager.py b/pipelex/system/telemetry/telemetry_manager.pyindex 3d895c7bf..78f3a6222 100644--- a/pipelex/system/telemetry/telemetry_manager.py+++ b/pipelex/system/telemetry/telemetry_manager.py@@ -10,6 +10,7 @@ from typing_extensions import Unpack, overridefrom pipelex import logfrom pipelex.base_exceptions import PipelexUnexpectedError+from pipelex.system.caller_identity import CallerIdentity, get_current_caller_identityfrom pipelex.system.environment import is_env_var_truthyfrom pipelex.system.exceptions import PipelexErrorfrom pipelex.system.pipelex_service.pipelex_details import PipelexDetails@@ -20,7 +21,7 @@ from pipelex.system.telemetry.exception_capture import DualClientExceptionCapturfrom pipelex.system.telemetry.otel_constants import OTelConstants, PostHogAttr, PostHogEventfrom pipelex.system.telemetry.otel_factory import OtelFactoryfrom pipelex.system.telemetry.telemetry_config import PostHogMode, TelemetryConfig, TelemetryRedactionConfig-from pipelex.system.telemetry.telemetry_identity import RunIdentityPolicy, TelemetryIdentity+from pipelex.system.telemetry.telemetry_identity import RunIdentityPolicy, StreamIdentityRule, TelemetryIdentityfrom pipelex.system.telemetry.telemetry_manager_abstract import TelemetryManagerAbstractif TYPE_CHECKING:@@ -129,29 +130,27 @@ class TelemetryManager(TelemetryManagerAbstract):self._exception_capture = self._make_exception_capture()def _make_exception_capture(self) -> DualClientExceptionCapture:- """Build the exception autocapture, with each stream's runless identity resolved.+ """Build the exception autocapture, with each stream's identity rule.- An unhandled exception belongs to no run that the interpreter hooks can- see — they are handed `(type, value, traceback)` and there is no- ContextVar layer to read a run out of — so what each stream sends is the- identity it uses for a capture that names nobody, resolved through the- same `TelemetryIdentity` as every other path. That is what carries+ An unhandled exception is attributed when it arrives, not here: the+ capture reads back the caller of the pipe run the error escaped from, and+ falls back to the stream's own id only for an error that belongs to no+ caller. What is fixed here is each stream's rule, taken from the same+ settings as every other capture on that stream — which is what carries`anonymous` mode onto this path: a stream that identifies nobody must notidentify somebody when the process crashes.- Stated as its own method so the resolution can be exercised without the+ Stated as its own method so the wiring can be exercised without theconstructor, which builds live clients and registers a singleton."""return DualClientExceptionCapture(custom_posthog_client=self.custom_posthog_client,- custom_identity=TelemetryIdentity.make_from_run_metadata(- run_metadata=None,+ custom_identity_rule=StreamIdentityRule(fallback_distinct_id=self.telemetry_config.custom_posthog.user_id,run_identity_policy=RunIdentityPolicy.make_for_operator_stream(posthog_mode=self.telemetry_config.custom_posthog.mode),),pipelex_posthog_client=self.pipelex_posthog_client,- pipelex_identity=TelemetryIdentity.make_from_run_metadata(- run_metadata=None,+ pipelex_identity_rule=StreamIdentityRule(fallback_distinct_id=self._pipelex_distinct_id,run_identity_policy=RunIdentityPolicy.DIRECT,),@@ -437,6 +436,8 @@ class TelemetryManager(TelemetryManagerAbstract):else:tracked_properties = {}+ caller_identity = self.resolve_event_caller_identity(run_metadata=run_metadata)+# Track to custom PostHog based on user's posthog.modematch self.telemetry_config.custom_posthog.mode:case PostHogMode.ANONYMOUS:@@ -451,8 +452,8 @@ class TelemetryManager(TelemetryManagerAbstract):self._capture_custom_event(event_name,properties=tracked_properties,- identity=TelemetryIdentity.make_from_run_metadata(- run_metadata=run_metadata,+ identity=TelemetryIdentity.make_from_caller_identity(+ caller_identity=caller_identity,fallback_distinct_id=self.telemetry_config.custom_posthog.user_id,run_identity_policy=RunIdentityPolicy.DIRECT,),@@ -462,7 +463,22 @@ class TelemetryManager(TelemetryManagerAbstract):# Always track to Pipelex PostHog if enabled (independent of posthog.mode)if self._pipelex_telemetry_enabled:- self._track_to_pipelex(event_name, properties=tracked_properties, run_metadata=run_metadata)+ self._track_to_pipelex(event_name, properties=tracked_properties, caller_identity=caller_identity)++ @classmethod+ def resolve_event_caller_identity(cls, *, run_metadata: "RunMetadata | None") -> CallerIdentity | None:+ """The caller an event is attributed to: its run's, else the one in scope, else nobody.++ The run an emitter hands over is the most specific fact there is, so it+ wins. An emitter with no run in hand — the validation sweep, which is not+ a run — is still working for somebody when a host or a pipe run opened a+ caller scope around it, and reads that caller rather than falling back to+ the stream's constant. Only an event emitted outside every scope, such as+ a CLI command, belongs to nobody.+ """+ if run_metadata is not None:+ return CallerIdentity.make_from_run_metadata(run_metadata=run_metadata)+ return get_current_caller_identity()def _capture_custom_event(self, event_name: str, *, properties: dict[str, Any], identity: TelemetryIdentity):"""Capture one event on the operator's stream, under the identity resolved for it.@@ -490,7 +506,7 @@ class TelemetryManager(TelemetryManagerAbstract):self.custom_posthog_client.capture(event_name, properties=capture_properties)log.verbose(f"Tracked anonymous event '{event_name}' with properties: {capture_properties}")- def _track_to_pipelex(self, event_name: str, *, properties: dict[str, Any], run_metadata: "RunMetadata | None" = None):+ def _track_to_pipelex(self, event_name: str, *, properties: dict[str, Any], caller_identity: CallerIdentity | None = None):"""Track event to Pipelex's PostHog (always identified, always direct).The stream has no mode to turn identification off. A run's own@@ -500,8 +516,8 @@ class TelemetryManager(TelemetryManagerAbstract):if not self.pipelex_posthog_client or not self._pipelex_distinct_id:log.error("Could not track event to Pipelex telemetry because pipelex_posthog_client or _pipelex_distinct_id is not set")return- identity = TelemetryIdentity.make_from_run_metadata(- run_metadata=run_metadata,+ identity = TelemetryIdentity.make_from_caller_identity(+ caller_identity=caller_identity,fallback_distinct_id=self._pipelex_distinct_id,run_identity_policy=RunIdentityPolicy.DIRECT,)@@ -629,8 +645,10 @@ class TelemetryManager(TelemetryManagerAbstract):run_metadata: The run this trace belongs to. Carries the identity theevent is attributed to, resolved exactly as every pipe span underthe same trace will be, so the trace's first event and its spans- land on the same person. None leaves the stream's fallback.+ land on the same person. None reads the caller in scope, and+ only with none in scope leaves the stream's fallback."""+ caller_identity = self.resolve_event_caller_identity(run_metadata=run_metadata)log.verbose(f"[Telemetry] Emitting trace start event:\n"f" trace_name='{trace_name}'\n"@@ -647,8 +665,10 @@ class TelemetryManager(TelemetryManagerAbstract):PostHogAttr.SPAN_NAME: custom_trace_name,PostHogAttr.TRACE_NAME: custom_trace_name,}- custom_identity = TelemetryIdentity.make_from_run_metadata(- run_metadata=run_metadata,+ if run_metadata is not None:+ custom_properties[EventProperty.PIPELINE_RUN_ID] = run_metadata.pipeline_run_id+ custom_identity = TelemetryIdentity.make_from_caller_identity(+ caller_identity=caller_identity,fallback_distinct_id=self.telemetry_config.custom_posthog.user_id,run_identity_policy=RunIdentityPolicy.make_for_operator_stream(posthog_mode=self.telemetry_config.custom_posthog.mode),)@@ -673,8 +693,10 @@ class TelemetryManager(TelemetryManagerAbstract):PostHogAttr.SPAN_NAME: trace_name_redacted,PostHogAttr.TRACE_NAME: trace_name_redacted,}- pipelex_identity = TelemetryIdentity.make_from_run_metadata(- run_metadata=run_metadata,+ if run_metadata is not None:+ pipelex_properties[EventProperty.PIPELINE_RUN_ID] = run_metadata.pipeline_run_id+ pipelex_identity = TelemetryIdentity.make_from_caller_identity(+ caller_identity=caller_identity,fallback_distinct_id=self._pipelex_distinct_id,run_identity_policy=RunIdentityPolicy.DIRECT,)diff --git a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_analytics_groups.py b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_run_extras.pysimilarity index 82%rename from tests/integration/pipelex/pipeline/test_pipeline_run_setup_analytics_groups.pyrename to tests/integration/pipelex/pipeline/test_pipeline_run_setup_run_extras.pyindex 351f8ee69..53f431674 100644--- a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_analytics_groups.py+++ b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_run_extras.py@@ -1,8 +1,8 @@-"""Integration tests for :func:`pipeline_run_setup` threading ``analytics_groups``+"""Integration tests for :func:`pipeline_run_setup` threading ``extras``onto :class:`JobMetadata`.-The groups ride the ``PipeJob``-(``arg.pipe_job.job_metadata.run_metadata.analytics_groups``) — the same payload-first+The extras ride the ``PipeJob``+(``arg.pipe_job.job_metadata.run_metadata.extras``) — the same payload-firstroute ``request_id`` takes, and for the same reason: there is no ContextVar layerand the worker on the far side of a Temporal hop rehydrates the whole job. ThePostHog exporters read them back off the span attributes; this test pins the@@ -26,8 +26,8 @@ from pipelex.pipeline import pipeline_run_setup as pipeline_run_setup_modulefrom pipelex.pipeline.pipeline_run_setup import pipeline_run_setup_MINIMAL_MTHDS = """-domain = "analytics_groups_test"-description = "Minimal bundle for analytics_groups propagation test"+domain = "extras_test"+description = "Minimal bundle for extras propagation test"[concept.Topic]description = "A topic"@@ -45,9 +45,9 @@ prompt = "Echo the $subject as a topic"@pytest.mark.asyncio(loop_scope="class")-class TestPipelineRunSetupAnalyticsGroups:- async def test_analytics_groups_thread_onto_job_metadata(self) -> None:- """``pipeline_run_setup(..., analytics_groups=...)`` puts them on ``job_metadata.run_metadata``."""+class TestPipelineRunSetupRunExtras:+ async def test_run_extras_thread_onto_job_metadata(self) -> None:+ """``pipeline_run_setup(..., extras=...)`` puts them on ``job_metadata.run_metadata``."""execution_config = get_config().interpreter.pipeline_execution.with_execution_overrides(generate_graph=False,)@@ -57,9 +57,9 @@ class TestPipelineRunSetupAnalyticsGroups:execution_config=execution_config,mthds_contents=[_MINIMAL_MTHDS],pipe_code="echo_topic",- analytics_groups={"organization": "org_acme"},+ extras={"organization": "org_acme"},)- assert pipe_job.job_metadata.run_metadata.analytics_groups == {"organization": "org_acme"}+ assert pipe_job.job_metadata.run_metadata.extras == {"organization": "org_acme"}async def test_omitting_them_leaves_an_empty_mapping(self) -> None:"""Every existing caller omits the field, and an omission is an empty group facet, not an error."""@@ -73,21 +73,21 @@ class TestPipelineRunSetupAnalyticsGroups:mthds_contents=[_MINIMAL_MTHDS],pipe_code="echo_topic",)- assert pipe_job.job_metadata.run_metadata.analytics_groups == {}+ assert pipe_job.job_metadata.run_metadata.extras == {}- async def test_malformed_groups_are_refused_before_the_run_starts(self) -> None:+ async def test_malformed_extras_are_refused_before_the_run_starts(self) -> None:"""The validator on the field is what makes a bad mapping fail at setup rather than at capture."""execution_config = get_config().interpreter.pipeline_execution.with_execution_overrides(generate_graph=False,)- with pytest.raises(ValueError, match="analytics_groups"):+ with pytest.raises(ValueError, match="extras"):await pipeline_run_setup(storage_scope="test/scope",user_id="test-user",execution_config=execution_config,mthds_contents=[_MINIMAL_MTHDS],pipe_code="echo_topic",- analytics_groups={"Organization": "org_acme"},+ extras={"Organization": "org_acme"},)async def test_the_refusal_registers_no_run_and_emits_no_trace_start(self, mocker: MockerFixture) -> None:@@ -109,14 +109,14 @@ class TestPipelineRunSetupAnalyticsGroups:pipeline_manager = mocker.spy(pipeline_run_setup_module, "get_pipeline_manager")telemetry_manager = mocker.spy(pipeline_run_setup_module, "get_telemetry_manager")- with pytest.raises(ValueError, match="analytics_groups"):+ with pytest.raises(ValueError, match="extras"):await pipeline_run_setup(storage_scope="test/scope",user_id="test-user",execution_config=execution_config,mthds_contents=[_MINIMAL_MTHDS],pipe_code="echo_topic",- analytics_groups={"Organization": "org_acme"},+ extras={"Organization": "org_acme"},)pipeline_manager.assert_not_called()diff --git a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_telemetry_identity.py b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_telemetry_identity.pyindex ee4bd873b..eb10b5b47 100644--- a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_telemetry_identity.py+++ b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_telemetry_identity.py@@ -57,7 +57,7 @@ async def _run_setup(*, mocker: MockerFixture) -> Any:mthds_contents=[_MINIMAL_MTHDS],pipe_code="echo_topic",inputs={"subject": "a subject"},- analytics_groups={"organization": "org_acme"},+ extras={"organization": "org_acme"},)return telemetry_manager@@ -70,7 +70,7 @@ class TestPipelineRunSetupTelemetryIdentity:telemetry_manager.handle_trace_start.assert_called_once()run_metadata = telemetry_manager.handle_trace_start.call_args.kwargs["run_metadata"]assert run_metadata.user_id == "user-42"- assert run_metadata.analytics_groups == {"organization": "org_acme"}+ assert run_metadata.extras == {"organization": "org_acme"}async def test_the_pipeline_execute_event_is_handed_the_runs_metadata(self, mocker: MockerFixture) -> None:telemetry_manager = await _run_setup(mocker=mocker)@@ -79,4 +79,4 @@ class TestPipelineRunSetupTelemetryIdentity:assert len(execute_calls) == 1run_metadata = execute_calls[0].kwargs["run_metadata"]assert run_metadata.user_id == "user-42"- assert run_metadata.analytics_groups == {"organization": "org_acme"}+ assert run_metadata.extras == {"organization": "org_acme"}diff --git a/tests/integration/pipelex/pipeline/test_validate_caller_identity.py b/tests/integration/pipelex/pipeline/test_validate_caller_identity.pynew file mode 100644index 000000000..1250122d3--- /dev/null+++ b/tests/integration/pipelex/pipeline/test_validate_caller_identity.py@@ -0,0 +1,99 @@+"""Integration tests: a validation served for a known caller is attributed to that caller.++The unit suite pins each seam with mocks; these run the real validate pass — library load,+the dry-run sweep, the best-effort graph arm — to pin what the seams add up to: the sweep's+`PIPE_DRY_RUN` event is emitted with the caller in scope, and every dry run the pass performs+states that caller in its job metadata, so none of it falls back to the telemetry stream's+configured constant. A local runtime states `local`, which telemetry never attributes to a+person, so a local validation keeps reporting under the fallback.+"""++from typing import Any++import pytest+from pytest_mock import MockerFixture++from pipelex.pipe_run import dry_run_in_process+from pipelex.pipeline import bundle_validator+from pipelex.pipeline.runner import PipelexMTHDSProtocol+from pipelex.pipeline.validate_in_process import validate_bundles_in_process+from pipelex.runtime_hub import get_telemetry_manager+from pipelex.system.caller_identity import CallerIdentity, get_current_caller_identity+from pipelex.system.storage_scope import LOCAL_USER_ID+from pipelex.system.telemetry.events import EventName+from pipelex.system.telemetry.telemetry_identity import RunIdentityPolicy, TelemetryIdentity++_DOMAIN = "validate_caller_identity"+_MTHDS = f"""+domain = "{_DOMAIN}"+description = "Minimal bundle for caller-identity validation tests"+main_pipe = "echo_topic"++[concept.Topic]+description = "A topic"++[concept.Topic.structure]+name = {{ type = "text", description = "Topic name" }}++[pipe.echo_topic]+type = "PipeLLM"+description = "Pipe used only to dry-run through the validate pass"+inputs = {{ subject = "Text" }}+output = "Topic"+prompt = "Echo the $subject as a topic"+"""++_CALLER = CallerIdentity(user_id="caller-7", extras={"organization": "org_caller"})+++def _record_callers(*, mocker: MockerFixture) -> tuple[list[CallerIdentity | None], Any, Any]:+ """Record the caller in scope at each `PIPE_DRY_RUN`, and spy on every dry run's job build."""+ callers_at_dry_run_event: list[CallerIdentity | None] = []++ def record(*_args: Any, **kwargs: Any) -> None:+ if kwargs.get("event_name") == EventName.PIPE_DRY_RUN:+ callers_at_dry_run_event.append(get_current_caller_identity())++ mocker.patch.object(get_telemetry_manager(), "track_event", side_effect=record)+ sweep_prepare_spy = mocker.spy(bundle_validator, "prepare_pipe_job")+ graph_prepare_spy = mocker.spy(dry_run_in_process, "prepare_pipe_job")+ return callers_at_dry_run_event, sweep_prepare_spy, graph_prepare_spy++[email protected](loop_scope="class")+class TestValidateCallerIdentity:+ async def test_a_hosted_validation_is_attributed_to_its_caller(self, mocker: MockerFixture) -> None:+ callers_at_dry_run_event, sweep_prepare_spy, graph_prepare_spy = _record_callers(mocker=mocker)++ report = await validate_bundles_in_process(mthds_contents=[_MTHDS], caller_identity=_CALLER)++ assert report.graph_spec is not None, "the graph arm must have dry-run the main pipe"+ assert callers_at_dry_run_event == [_CALLER]+ dry_run_calls = [*sweep_prepare_spy.call_args_list, *graph_prepare_spy.call_args_list]+ assert len(dry_run_calls) >= 2+ for dry_run_call in dry_run_calls:+ assert dry_run_call.kwargs["user_id"] == "caller-7"+ assert dry_run_call.kwargs["extras"] == {"organization": "org_caller"}+ assert get_current_caller_identity() is None++ async def test_the_protocol_validates_for_the_caller_it_was_built_for(self, mocker: MockerFixture) -> None:+ callers_at_dry_run_event, sweep_prepare_spy, _graph_prepare_spy = _record_callers(mocker=mocker)+ protocol = PipelexMTHDSProtocol(user_id="caller-7", extras={"organization": "org_caller"})++ await protocol.validate(mthds_contents=[_MTHDS])++ assert callers_at_dry_run_event == [_CALLER]+ assert sweep_prepare_spy.call_args.kwargs["user_id"] == "caller-7"++ async def test_a_local_validation_still_reports_under_the_fallback(self, mocker: MockerFixture) -> None:+ callers_at_dry_run_event, _sweep_prepare_spy, _graph_prepare_spy = _record_callers(mocker=mocker)++ await PipelexMTHDSProtocol().validate(mthds_contents=[_MTHDS])++ assert callers_at_dry_run_event == [CallerIdentity(user_id=LOCAL_USER_ID)]+ identity = TelemetryIdentity.make_from_caller_identity(+ caller_identity=callers_at_dry_run_event[0],+ fallback_distinct_id="configured-id",+ run_identity_policy=RunIdentityPolicy.DIRECT,+ )+ assert identity.distinct_id == "configured-id"diff --git a/tests/integration/pipelex/system/telemetry/test_pipe_span_carries_run_identity.py b/tests/integration/pipelex/system/telemetry/test_pipe_span_carries_run_identity.pyindex 6a15f7e75..0d280c14a 100644--- a/tests/integration/pipelex/system/telemetry/test_pipe_span_carries_run_identity.py+++ b/tests/integration/pipelex/system/telemetry/test_pipe_span_carries_run_identity.py@@ -46,7 +46,7 @@ _PARENT_OTEL_CONTEXT = OtelContext()-async def _make_pipe_job(*, analytics_groups: dict[str, str] | None = None) -> PipeJob:+async def _make_pipe_job(*, extras: dict[str, str] | None = None) -> PipeJob:execution_config = get_config().interpreter.pipeline_execution.with_execution_overrides(generate_graph=False)pipe_job, _, _ = await pipeline_run_setup(storage_scope="test/scope",@@ -54,7 +54,7 @@ async def _make_pipe_job(*, analytics_groups: dict[str, str] | None = None) -> Pexecution_config=execution_config,mthds_contents=[_MINIMAL_MTHDS],pipe_code="echo_topic",- analytics_groups=analytics_groups,+ extras=extras,inputs={"subject": "a subject"},)return pipe_job@@ -83,15 +83,15 @@ class TestPipeSpanIdentity:assert _attributes(_start_span(mocker=mocker, pipe_job=pipe_job))[PipelexSpanAttr.RUN_USER_ID] == "user-42"async def test_the_groups_the_caller_supplied_reach_the_span(self, mocker: MockerFixture) -> None:- pipe_job = await _make_pipe_job(analytics_groups={"organization": "org_acme"})+ pipe_job = await _make_pipe_job(extras={"organization": "org_acme"})attributes = _attributes(_start_span(mocker=mocker, pipe_job=pipe_job))- assert attributes[PipelexSpanAttr.RUN_ANALYTICS_GROUPS] == '{"organization": "org_acme"}'+ assert attributes[PipelexSpanAttr.RUN_EXTRAS] == '{"organization": "org_acme"}'async def test_a_run_with_no_groups_writes_no_groups_attribute(self, mocker: MockerFixture) -> None:pipe_job = await _make_pipe_job()- assert PipelexSpanAttr.RUN_ANALYTICS_GROUPS not in _attributes(_start_span(mocker=mocker, pipe_job=pipe_job))+ assert PipelexSpanAttr.RUN_EXTRAS not in _attributes(_start_span(mocker=mocker, pipe_job=pipe_job))async def test_langfuse_gets_the_user_id_when_it_is_enabled(self, mocker: MockerFixture) -> None:pipe_job = await _make_pipe_job()diff --git a/tests/unit/pipelex/kernel/test_pipelex_kernel_analytics_groups.py b/tests/unit/pipelex/kernel/test_pipelex_kernel_run_extras.pysimilarity index 67%rename from tests/unit/pipelex/kernel/test_pipelex_kernel_analytics_groups.pyrename to tests/unit/pipelex/kernel/test_pipelex_kernel_run_extras.pyindex 61acdc82b..8983d3247 100644--- a/tests/unit/pipelex/kernel/test_pipelex_kernel_analytics_groups.py+++ b/tests/unit/pipelex/kernel/test_pipelex_kernel_run_extras.py@@ -1,9 +1,9 @@-"""`PipelexKernel.make` carrying the host's opaque analytics groups.+"""`PipelexKernel.make` carrying the host's opaque extras.The kernel tier is the direct programmatic entry point — the one a host embedswithout going through `pipeline_run_setup` — so it needs the same seam thepipeline entry points have. Without it a kernel-minted run is permanently-group-less and its host has no supported way to say otherwise, while+unlabelled and its host has no supported way to say otherwise, while`docs/under-the-hood/pipelex-kernel.md` lists the field among what`job_metadata.run_metadata` holds."""@@ -14,38 +14,38 @@ from pipelex.kernel.pipelex_kernel import PipelexKernelfrom pipelex.system.pipe_run_mode import PipeRunMode-class TestPipelexKernelAnalyticsGroups:- def test_supplied_groups_land_on_the_runs_metadata(self) -> None:+class TestPipelexKernelRunExtras:+ def test_supplied_extras_land_on_the_runs_metadata(self) -> None:kernel = PipelexKernel.make(storage_scope="test/scope",run_mode=PipeRunMode.DRY,user_id="test-user",- analytics_groups={"organization": "org_acme"},+ extras={"organization": "org_acme"},)- assert kernel.job_metadata.run_metadata.analytics_groups == {"organization": "org_acme"}+ assert kernel.job_metadata.run_metadata.extras == {"organization": "org_acme"}def test_omitting_them_leaves_an_empty_mapping(self) -> None:"""Every existing caller omits the field; an omission is an empty facet, not an error."""kernel = PipelexKernel.make(storage_scope="test/scope", run_mode=PipeRunMode.DRY, user_id="test-user")- assert kernel.job_metadata.run_metadata.analytics_groups == {}+ assert kernel.job_metadata.run_metadata.extras == {}def test_two_kernels_do_not_share_one_default_mapping(self) -> None:- """A mutable default shared between runs would leak one host's groups into another's."""+ """A mutable default shared between runs would leak one host's extras into another's."""first = PipelexKernel.make(storage_scope="test/scope", run_mode=PipeRunMode.DRY, user_id="test-user")second = PipelexKernel.make(storage_scope="test/scope", run_mode=PipeRunMode.DRY, user_id="test-user")- first.job_metadata.run_metadata.analytics_groups["organization"] = "org_acme"+ first.job_metadata.run_metadata.extras["organization"] = "org_acme"- assert second.job_metadata.run_metadata.analytics_groups == {}+ assert second.job_metadata.run_metadata.extras == {}def test_a_malformed_mapping_is_refused_when_the_kernel_is_minted(self) -> None:"""The field's validator is what makes this fail here rather than inside a later capture."""- with pytest.raises(ValueError, match="analytics_groups"):+ with pytest.raises(ValueError, match="extras"):PipelexKernel.make(storage_scope="test/scope",run_mode=PipeRunMode.DRY,user_id="test-user",- analytics_groups={"Organization": "org_acme"},+ extras={"Organization": "org_acme"},)diff --git a/tests/unit/pipelex/pipe_machinery/test_run_pipe_caller_scope.py b/tests/unit/pipelex/pipe_machinery/test_run_pipe_caller_scope.pynew file mode 100644index 000000000..b8ccc14bd--- /dev/null+++ b/tests/unit/pipelex/pipe_machinery/test_run_pipe_caller_scope.py@@ -0,0 +1,98 @@+"""Verify that `PipeAbstract.run_pipe` runs every pipe inside its run's caller scope.++The scope is what attributes a capture made during a run without the run in+hand — an exception, above all, which reaches the interpreter hook only once+the stack has unwound. So these pin both halves: the run's caller is current+while the pipe body runs, and an error escaping the pipe carries that caller.+"""++from typing import Any, Callable++import pytest+from pytest_mock import MockerFixture++from pipelex.core.concepts.concept import Concept+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory+from pipelex.core.stuffs.stuff import Stuff+from pipelex.core.stuffs.text_content import TextContent+from pipelex.pipe_machinery.pipe_abstract import InputPresenceScan+from pipelex.pipe_machinery.pipe_factory import PipeFactory+from pipelex.pipe_operators.llm.pipe_llm import PipeLLM+from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint+from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory+from pipelex.system.caller_identity import CallerIdentity, find_stamped_caller_identity, get_current_caller_identity+from pipelex.system.job_metadata import JobMetadata, RunMetadata+++def _make_pipe(*, mocker: MockerFixture, live_run: Any) -> PipeLLM:+ blueprint = PipeLLMBlueprint(description="Say hello.", output="native.Text", prompt="Say hello.")+ pipe = PipeFactory[PipeLLM].make_from_blueprint(domain_code="caller_domain", pipe_code="say_hello", blueprint=blueprint)+ mocker.patch.object(PipeLLM, "_live_run_operator_pipe", live_run)+ mocker.patch.object(+ PipeLLM,+ "validate_before_run",+ mocker.AsyncMock(return_value=InputPresenceScan(missing_names=[], forced_absent=[], liftable=[])),+ )+ mocker.patch.object(PipeLLM, "validate_after_run", mocker.AsyncMock(return_value=None))+ mocker.patch("pipelex.pipe_machinery.pipe_abstract.GraphTracerManager.get_instance", return_value=None)+ return pipe+++def _job_metadata() -> JobMetadata:+ return JobMetadata(+ run_metadata=RunMetadata(+ storage_scope="tenant/run-1",+ user_id="caller-7",+ pipeline_run_id="run-1",+ extras={"organization": "org_caller"},+ ),+ )+++_EXPECTED_CALLER = CallerIdentity(user_id="caller-7", extras={"organization": "org_caller"})++[email protected](loop_scope="class")+class TestRunPipeCallerScope:+ async def test_the_runs_caller_is_current_while_the_pipe_runs(self, mocker: MockerFixture, load_empty_library: Callable[[], str]) -> None:+ load_empty_library()+ seen: list[CallerIdentity | None] = []+ main_stuff = Stuff(+ stuff_code="main-code",+ stuff_name="main_stuff",+ concept=Concept(code="Text", domain_code="native", description="Plain text", structure_class_name="TextContent"),+ content=TextContent(text="hello"),+ )+ expected_output = mocker.MagicMock()+ expected_output.working_memory.get_main_stuff.return_value = main_stuff+ expected_output.working_memory.resolve_main_stuff.return_value = main_stuff++ def record_caller(*_args: Any, **_kwargs: Any) -> Any:+ seen.append(get_current_caller_identity())+ return expected_output++ pipe = _make_pipe(mocker=mocker, live_run=mocker.AsyncMock(side_effect=record_caller))++ await pipe.run_pipe(+ job_metadata=_job_metadata(),+ working_memory=WorkingMemoryFactory.make_empty(),+ pipe_run_params=PipeRunParamsFactory.make_run_params(),+ )++ assert seen == [_EXPECTED_CALLER]+ assert get_current_caller_identity() is None++ async def test_an_error_escaping_the_pipe_carries_the_runs_caller(self, mocker: MockerFixture, load_empty_library: Callable[[], str]) -> None:+ load_empty_library()++ pipe = _make_pipe(mocker=mocker, live_run=mocker.AsyncMock(side_effect=RuntimeError("the pipe body failed")))++ with pytest.raises(RuntimeError, match="the pipe body failed") as exc_info:+ await pipe.run_pipe(+ job_metadata=_job_metadata(),+ working_memory=WorkingMemoryFactory.make_empty(),+ pipe_run_params=PipeRunParamsFactory.make_run_params(),+ )++ assert find_stamped_caller_identity(exception=exc_info.value) == _EXPECTED_CALLER+ assert get_current_caller_identity() is Nonediff --git a/tests/unit/pipelex/pipeline/test_bundle_validator.py b/tests/unit/pipelex/pipeline/test_bundle_validator.pyindex cc8bcb413..8aefbfb00 100644--- a/tests/unit/pipelex/pipeline/test_bundle_validator.py+++ b/tests/unit/pipelex/pipeline/test_bundle_validator.py@@ -7,6 +7,8 @@ single collect-all aggregate (no per-pipe early abort), and the per-sweep telemeis exercised by the integration suite."""+from typing import Any+import pytestfrom polyfactory.exceptions import FactoryExceptionfrom pydantic import BaseModel, ValidationError@@ -17,9 +19,13 @@ from pipelex.core.pipes.exceptions import PipeRunErrorfrom pipelex.libraries.pipe.exceptions import PipeNotFoundErrorfrom pipelex.pipe_run.exceptions import DryRunErrorfrom pipelex.pipeline.bundle_validator import BundleValidator, DryRunStatus+from pipelex.system.caller_identity import CallerIdentity, get_current_caller_identity, scoped_caller_identityfrom pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.system.storage_scope import DRY_RUN_STORAGE_SCOPE, DRY_RUN_USER_IDfrom pipelex.system.telemetry.events import EventName, EventProperty+_CALLER = CallerIdentity(user_id="caller-7", extras={"organization": "org_caller"})+class TestBundleValidator:def _make_pipe(self, mocker: MockerFixture, *, code: str, pipe_ref: str, is_signature: bool = False):@@ -234,3 +240,66 @@ class TestBundleValidator:threaded_id = prepare.call_args.kwargs["pipeline_run_id"]assert threaded_id.startswith("dry_run_")++ def _patch_caller_env(self, mocker: MockerFixture):+ telemetry_manager = mocker.patch("pipelex.pipeline.bundle_validator.get_telemetry_manager").return_value+ callers_seen_by_the_event: list[CallerIdentity | None] = []++ def record_caller(**_kwargs: Any) -> None:+ callers_seen_by_the_event.append(get_current_caller_identity())++ telemetry_manager.track_event.side_effect = record_caller+ mocker.patch("pipelex.pipeline.bundle_validator.get_config").return_value.inference.dry_run.allowed_to_fail_pipes = []+ prepare_mock = mocker.patch("pipelex.pipeline.bundle_validator.prepare_pipe_job")+ prepare_mock.return_value = mocker.MagicMock(name="pipe_job")+ pipe_run = mocker.MagicMock(name="pipe_run")+ pipe_run.run = mocker.AsyncMock(return_value=mocker.MagicMock(name="pipe_output"))+ mocker.patch("pipelex.pipeline.bundle_validator.PipeRun", return_value=pipe_run)+ pipe = mocker.MagicMock()+ pipe.code = "p"+ pipe.pipe_ref = "dom.p"+ pipe.is_signature = False+ return BundleValidator(), callers_seen_by_the_event, prepare_mock, pipe++ @pytest.mark.asyncio+ async def test_the_sweep_event_is_emitted_inside_the_callers_scope(self, mocker: MockerFixture) -> None:+ validator, callers_seen_by_the_event, _prepare, pipe = self._patch_caller_env(mocker)++ await validator.validate_pipes([pipe], library_id="lib-1", caller_identity=_CALLER)++ assert callers_seen_by_the_event == [_CALLER]+ assert get_current_caller_identity() is None++ @pytest.mark.asyncio+ async def test_each_dry_run_states_the_caller_in_its_job_metadata(self, mocker: MockerFixture) -> None:+ validator, _callers, prepare_mock, pipe = self._patch_caller_env(mocker)++ await validator.validate_pipes([pipe], library_id="lib-1", caller_identity=_CALLER)++ prepare_kwargs = prepare_mock.call_args.kwargs+ assert prepare_kwargs["user_id"] == "caller-7"+ assert prepare_kwargs["extras"] == {"organization": "org_caller"}+ # A dry run still stores nothing, whoever it is done for.+ assert prepare_kwargs["storage_scope"] == DRY_RUN_STORAGE_SCOPE++ @pytest.mark.asyncio+ async def test_a_sweep_with_no_caller_inherits_the_one_in_scope(self, mocker: MockerFixture) -> None:+ validator, callers_seen_by_the_event, prepare_mock, pipe = self._patch_caller_env(mocker)++ with scoped_caller_identity(caller_identity=_CALLER):+ await validator.validate_pipes([pipe], library_id="lib-1")++ assert callers_seen_by_the_event == [_CALLER]+ assert prepare_mock.call_args.kwargs["user_id"] == "caller-7"++ @pytest.mark.asyncio+ async def test_a_sweep_that_belongs_to_nobody_states_the_dry_run_placeholder(self, mocker: MockerFixture) -> None:+ """The local CLI case: no caller, so the event reports under the stream's fallback as before."""+ validator, callers_seen_by_the_event, prepare_mock, pipe = self._patch_caller_env(mocker)++ await validator.validate_pipes([pipe], library_id="lib-1")++ assert callers_seen_by_the_event == [None]+ prepare_kwargs = prepare_mock.call_args.kwargs+ assert prepare_kwargs["user_id"] == DRY_RUN_USER_ID+ assert prepare_kwargs["extras"] is Nonediff --git a/tests/unit/pipelex/pipeline/test_direct_bundle_validator.py b/tests/unit/pipelex/pipeline/test_direct_bundle_validator.pyindex 5c6d3c77b..13c227d5a 100644--- a/tests/unit/pipelex/pipeline/test_direct_bundle_validator.py+++ b/tests/unit/pipelex/pipeline/test_direct_bundle_validator.py@@ -17,6 +17,7 @@ import pytestfrom pipelex.base_exceptions import ErrorReportfrom pipelex.pipeline.direct_bundle_validator import DirectBundleValidatorfrom pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.system.caller_identity import CallerIdentityif TYPE_CHECKING:from pytest_mock import MockerFixture@@ -37,6 +38,7 @@ class TestDirectBundleValidator:mthds_sources=["domain.mthds"],allow_signatures=True,library_dirs=[Path("lib_dir")],+ caller_identity=CallerIdentity(user_id="user-42", extras={"organization": "org_acme"}),)assert verdict is report@@ -46,6 +48,7 @@ class TestDirectBundleValidator:library_dirs=[Path("lib_dir")],allow_signatures=True,log_context="API validate",+ caller_identity=CallerIdentity(user_id="user-42", extras={"organization": "org_acme"}),)async def test_validate_bundle_error_becomes_the_invalid_arm(self, mocker: MockerFixture) -> None:@@ -61,6 +64,7 @@ class TestDirectBundleValidator:mthds_sources=None,allow_signatures=False,library_dirs=None,+ caller_identity=None,)assert isinstance(verdict, ErrorReport)@@ -80,4 +84,5 @@ class TestDirectBundleValidator:mthds_sources=None,allow_signatures=False,library_dirs=None,+ caller_identity=None,)diff --git a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.pyindex 6a51ae81c..f085f0516 100644--- a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py+++ b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py@@ -20,12 +20,14 @@ the artifact builders and asserts nothing about the returned report.from __future__ import annotationsfrom pathlib import Path-from typing import TYPE_CHECKING, NamedTuple+from typing import TYPE_CHECKING, Any, NamedTupleimport pytestfrom pipelex.core.pipes.pipe_io_artifacts import PipeIOArtifactsfrom pipelex.pipeline.runner import PipelexMTHDSProtocol+from pipelex.system.caller_identity import CallerIdentity, get_current_caller_identity+from pipelex.system.storage_scope import LOCAL_USER_IDif TYPE_CHECKING:from pytest_mock import MockerFixture, MockType@@ -104,6 +106,26 @@ class TestRunnerValidatePlumbing:allow_signatures=False,)+ async def test_validation_runs_with_the_protocols_caller_in_scope(self, mocker: MockerFixture) -> None:+ """A validation is not a run, so the caller reaches its telemetry as the ambient one."""+ env = self._patch_env(mocker, library_ids=[None, "val-lib"])+ callers_seen: list[CallerIdentity | None] = []++ def record_caller(**_kwargs: Any) -> Any:+ callers_seen.append(get_current_caller_identity())+ return mocker.MagicMock(name="validate_bundle_result")++ env.validate_bundle_mock.side_effect = record_caller+ runner = PipelexMTHDSProtocol(user_id="caller-7", extras={"organization": "org_caller"})++ await runner.validate(mthds_contents=["bundle-content"])++ assert callers_seen == [CallerIdentity(user_id="caller-7", extras={"organization": "org_caller"})]+ assert get_current_caller_identity() is None++ async def test_a_local_protocol_states_the_local_caller(self) -> None:+ assert PipelexMTHDSProtocol().caller_identity == CallerIdentity(user_id=LOCAL_USER_ID, extras={})+@pytest.mark.parametrize(("prev_library_id", "validation_library_id", "expect_set_prev", "expect_clear", "expect_teardown"),[diff --git a/tests/unit/pipelex/plugins/test_bundle_validator_registry.py b/tests/unit/pipelex/plugins/test_bundle_validator_registry.pyindex b101590eb..90d141c98 100644--- a/tests/unit/pipelex/plugins/test_bundle_validator_registry.py+++ b/tests/unit/pipelex/plugins/test_bundle_validator_registry.py@@ -24,6 +24,7 @@ if TYPE_CHECKING:from pipelex.base_exceptions import ErrorReportfrom pipelex.pipeline.validation_report import PipelexValidationReport+ from pipelex.system.caller_identity import CallerIdentityfrom pipelex.system.configuration.configs import PipelexConfig@@ -37,6 +38,7 @@ class _FakeBundleValidator:mthds_sources: list[str] | None,allow_signatures: bool,library_dirs: Sequence[Path] | None,+ caller_identity: CallerIdentity | None,) -> PipelexValidationReport | ErrorReport:raise NotImplementedErrordiff --git a/tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py b/tests/unit/pipelex/runtime_bridge/test_input_run_extras.pysimilarity index 66%rename from tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.pyrename to tests/unit/pipelex/runtime_bridge/test_input_run_extras.pyindex a71752d8b..e4b07a437 100644--- a/tests/unit/pipelex/runtime_bridge/test_input_analytics_groups.py+++ b/tests/unit/pipelex/runtime_bridge/test_input_run_extras.py@@ -1,6 +1,6 @@-"""The bridge payload refuses malformed analytics groups at the WIRE.+"""The bridge payload refuses malformed extras at the WIRE.-A `PipelexPipeRunInput` crosses a process boundary, so its groups are whatever+A `PipelexPipeRunInput` crosses a process boundary, so its extras are whateverthe other side put there. Declaring the field `dict[str, str]` says nothingabout its contents: a key with a newline in it, or a mapping with a thousandentries, would decode happily and only surface much later, inside whichever@@ -15,41 +15,41 @@ import pytestfrom pydantic import ValidationErrorfrom pipelex.runtime_bridge.payloads import PipelexPipeRunInput-from pipelex.system.analytics_groups import ANALYTICS_GROUPS_MAX_ENTRIES+from pipelex.system.run_extras import RUN_EXTRAS_MAX_ENTRIES-def _payload(analytics_groups: dict[str, str]) -> PipelexPipeRunInput:+def _payload(extras: dict[str, str]) -> PipelexPipeRunInput:return PipelexPipeRunInput(storage_scope="org_a/mt_b/run_c",user_id="test-user",pipe_code="some_pipe",- analytics_groups=analytics_groups,+ extras=extras,)-class TestTheWireRefusesMalformedAnalyticsGroups:+class TestTheWireRefusesMalformedRunExtras:def test_the_field_defaults_to_an_empty_mapping(self) -> None:- """A host with no groups to send sends none, and that is not an error.+ """A host with no extras to send sends none, and that is not an error.`user_id` and `storage_scope` are required here because a missing one- used to be invented; a missing group invents nothing, so it defaults.+ used to be invented; a missing label invents nothing, so it defaults."""payload = PipelexPipeRunInput(storage_scope="org_a/mt_b/run_c", user_id="test-user", pipe_code="some_pipe")- assert payload.analytics_groups == {}+ assert payload.extras == {}@pytest.mark.parametrize(- "groups",+ "extras",[pytest.param({}, id="empty-mapping"),pytest.param({"organization": "org_acme"}, id="the-hosted-plane-shape"),- pytest.param({"organization": "org_acme", "workspace": "ws-1"}, id="two-group-types"),+ pytest.param({"organization": "org_acme", "workspace": "ws-1"}, id="two-keys"),],)- def test_well_formed_groups_cross_the_wire(self, groups: dict[str, str]) -> None:- assert _payload(groups).analytics_groups == groups+ def test_well_formed_extras_cross_the_wire(self, extras: dict[str, str]) -> None:+ assert _payload(extras).extras == extras@pytest.mark.parametrize(- "bad_groups",+ "bad_extras",[pytest.param({"Organization": "org_acme"}, id="uppercase-key"),pytest.param({"org-id": "org_acme"}, id="hyphen-in-key"),@@ -58,16 +58,16 @@ class TestTheWireRefusesMalformedAnalyticsGroups:pytest.param({"organization": "org acme"}, id="space-in-value"),pytest.param({"organization": "org_acme\n"}, id="trailing-newline-in-value"),pytest.param({"organization": "v" * 129}, id="value-one-over-the-length-cap"),- pytest.param({f"g{index}": "v" for index in range(ANALYTICS_GROUPS_MAX_ENTRIES + 1)}, id="one-over-the-entry-cap"),+ pytest.param({f"g{index}": "v" for index in range(RUN_EXTRAS_MAX_ENTRIES + 1)}, id="one-over-the-entry-cap"),],)- def test_malformed_groups_are_refused_at_construction(self, bad_groups: dict[str, str]) -> None:+ def test_malformed_extras_are_refused_at_construction(self, bad_extras: dict[str, str]) -> None:with pytest.raises(ValidationError):- _payload(bad_groups)+ _payload(bad_extras)- def test_the_groups_survive_a_json_round_trip(self) -> None:+ def test_the_extras_survive_a_json_round_trip(self) -> None:"""The payload is decoded from JSON on the far side, so the field must round-trip."""original = _payload({"organization": "org_acme"})round_tripped = PipelexPipeRunInput.model_validate(original.model_dump(mode="json"))assert round_tripped == original- assert round_tripped.analytics_groups == {"organization": "org_acme"}+ assert round_tripped.extras == {"organization": "org_acme"}diff --git a/tests/unit/pipelex/system/telemetry/test_exception_capture_identity.py b/tests/unit/pipelex/system/telemetry/test_exception_capture_identity.pyindex 6cfffef5b..9065cfac8 100644--- a/tests/unit/pipelex/system/telemetry/test_exception_capture_identity.py+++ b/tests/unit/pipelex/system/telemetry/test_exception_capture_identity.py@@ -1,12 +1,14 @@"""Unit tests for the identity an unhandled exception is captured under.An `$exception` is the one capture no run can hand its metadata to: the two-interpreter hooks receive `(type, value, traceback)` and nothing else, and there-is no ContextVar layer for them to read a run out of. So what each stream sends-is its runless identity, resolved once when the capture is built — and these-tests are about that resolution reaching this path, because for a while it did-not: the operator's configured `user_id` went out on every crash, `anonymous`-mode included.+interpreter hooks receive `(type, value, traceback)` and nothing else. So the+caller is read back from the error — the caller of the pipe run it escaped,+stamped on it as it left the run's scope — or from the caller still in scope,+and only an error that belongs to no caller goes out under the stream's+fallback. These tests are about that resolution reaching this path, because for+a while it did not: the operator's configured `user_id` went out on every crash,+`anonymous` mode included, and later the constant went out even for a crash+inside a known caller's run.The manager is built WITHOUT its constructor, as in the tracker tests besidethese, because `TelemetryManager.__init__` creates live PostHog clients, writes@@ -24,6 +26,7 @@ import pytestfrom posthog import Posthogfrom pytest_mock import MockerFixture+from pipelex.system.caller_identity import CallerIdentity, scoped_caller_identity, stamp_caller_identityfrom pipelex.system.telemetry.exception_capture import DualClientExceptionCapturefrom pipelex.system.telemetry.otel_constants import PostHogAttrfrom pipelex.system.telemetry.telemetry_config import PostHogConfig, PostHogMode, TelemetryConfig@@ -66,6 +69,23 @@ def _crash(*, capture: DualClientExceptionCapture) -> None:capture._capture_exception((ValueError, ValueError("boom"), None)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+_CALLER = CallerIdentity(user_id="caller-7", extras={"organization": "org_caller"})+++def _crash_with(*, capture: DualClientExceptionCapture, error: BaseException) -> None:+ capture._capture_exception((type(error), error, None)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+++def _escaped_from_a_run() -> ValueError:+ """An error as it reaches the interpreter hook after leaving a pipe run's caller scope."""+ msg = "boom inside the run"+ try:+ with scoped_caller_identity(caller_identity=_CALLER):+ raise ValueError(msg)+ except ValueError as exc:+ return exc++@pytest.mark.usefixtures("restore_excepthooks")class TestExceptionCaptureIdentity:def test_an_anonymous_stream_captures_an_exception_under_nobody(self, mocker: MockerFixture) -> None:@@ -149,3 +169,72 @@ class TestExceptionCaptureIdentity:custom_client.capture_exception.side_effect = RuntimeError("posthog is down")_crash(capture=capture)++ def test_a_crash_inside_a_run_is_attributed_to_the_runs_caller(self, mocker: MockerFixture) -> None:+ """The hosted plane's constant must not stand in for a caller the run knew."""+ capture, custom_client, _ = _make_capture(mocker=mocker, mode=PostHogMode.IDENTIFIED, configured_user_id="pipelex-worker")++ _crash_with(capture=capture, error=_escaped_from_a_run())++ capture_kwargs = custom_client.capture_exception.call_args.kwargs+ assert capture_kwargs["distinct_id"] == "caller-7"+ assert capture_kwargs["groups"] == {"organization": "org_caller"}++ def test_a_host_error_raised_from_the_runs_error_keeps_the_caller(self, mocker: MockerFixture) -> None:+ """A host wraps the run's failure in its own error, and that outer error is what reaches the hook."""+ capture, custom_client, _ = _make_capture(mocker=mocker, mode=PostHogMode.IDENTIFIED, configured_user_id="pipelex-worker")+ host_error = RuntimeError("the pipeline failed")+ host_error.__cause__ = _escaped_from_a_run()++ _crash_with(capture=capture, error=host_error)++ assert custom_client.capture_exception.call_args.kwargs["distinct_id"] == "caller-7"++ def test_an_error_raised_while_a_caller_is_in_scope_is_attributed_to_it(self, mocker: MockerFixture) -> None:+ """A thread that inherited a caller's context crashes with the scope still open."""+ capture, custom_client, _ = _make_capture(mocker=mocker, mode=PostHogMode.IDENTIFIED, configured_user_id="pipelex-worker")++ with scoped_caller_identity(caller_identity=_CALLER):+ _crash_with(capture=capture, error=ValueError("boom"))++ assert custom_client.capture_exception.call_args.kwargs["distinct_id"] == "caller-7"++ def test_the_stamp_wins_over_the_caller_in_scope(self, mocker: MockerFixture) -> None:+ capture, custom_client, _ = _make_capture(mocker=mocker, mode=PostHogMode.IDENTIFIED, configured_user_id="pipelex-worker")+ error = ValueError("boom")+ stamp_caller_identity(exception=error, caller_identity=_CALLER)++ with scoped_caller_identity(caller_identity=CallerIdentity(user_id="someone-else")):+ _crash_with(capture=capture, error=error)++ assert custom_client.capture_exception.call_args.kwargs["distinct_id"] == "caller-7"++ def test_an_error_that_belongs_to_no_caller_reports_under_the_fallback(self, mocker: MockerFixture) -> None:+ capture, custom_client, _ = _make_capture(mocker=mocker, mode=PostHogMode.IDENTIFIED, configured_user_id="pipelex-worker")++ _crash_with(capture=capture, error=ValueError("boom outside any run"))++ capture_kwargs = custom_client.capture_exception.call_args.kwargs+ assert capture_kwargs["distinct_id"] == "pipelex-worker"+ assert capture_kwargs["groups"] is None++ def test_an_anonymous_stream_identifies_nobody_even_for_a_known_caller(self, mocker: MockerFixture) -> None:+ capture, custom_client, _ = _make_capture(mocker=mocker, mode=PostHogMode.ANONYMOUS, configured_user_id="configured-id")++ _crash_with(capture=capture, error=_escaped_from_a_run())++ capture_kwargs = custom_client.capture_exception.call_args.kwargs+ assert "distinct_id" not in capture_kwargs+ assert capture_kwargs["properties"][PostHogAttr.PROCESS_PERSON_PROFILE] is False++ def test_the_pipelex_stream_resolves_the_caller_under_its_own_policy(self, mocker: MockerFixture) -> None:+ capture, _, pipelex_client = _make_capture(+ mocker=mocker,+ mode=PostHogMode.IDENTIFIED,+ configured_user_id="pipelex-worker",+ pipelex_distinct_id="gateway-hash",+ )++ _crash_with(capture=capture, error=_escaped_from_a_run())++ assert pipelex_client.capture_exception.call_args.kwargs["distinct_id"] == "caller-7"diff --git a/tests/unit/pipelex/system/telemetry/test_llm_span_carries_run_identity.py b/tests/unit/pipelex/system/telemetry/test_llm_span_carries_run_identity.pyindex 76fac84b9..0a8b8634d 100644--- a/tests/unit/pipelex/system/telemetry/test_llm_span_carries_run_identity.py+++ b/tests/unit/pipelex/system/telemetry/test_llm_span_carries_run_identity.py@@ -58,13 +58,13 @@ def _make_worker() -> _StubLLMWorker:return _StubLLMWorker(inference_model=inference_model)-def _make_llm_job(*, analytics_groups: dict[str, str] | None = None) -> LLMJob:+def _make_llm_job(*, extras: dict[str, str] | None = None) -> LLMJob:job_metadata = JobMetadata(run_metadata=RunMetadata(user_id="user-42",pipeline_run_id="run-1",storage_scope="tenant/run-1",- analytics_groups=analytics_groups or {},+ extras=extras or {},),pipe_code="some_pipe",unit_job_id=UnitJobId.LLM_GEN_TEXT,@@ -101,14 +101,14 @@ class TestLLMSpanIdentity:assert _attributes(span)[PipelexSpanAttr.RUN_USER_ID] == "user-42"def test_the_span_carries_the_runs_groups_serialized(self, mocker: MockerFixture) -> None:- span = _start_span(mocker=mocker, llm_job=_make_llm_job(analytics_groups={"organization": "org_acme"}))+ span = _start_span(mocker=mocker, llm_job=_make_llm_job(extras={"organization": "org_acme"}))- assert _attributes(span)[PipelexSpanAttr.RUN_ANALYTICS_GROUPS] == '{"organization": "org_acme"}'+ assert _attributes(span)[PipelexSpanAttr.RUN_EXTRAS] == '{"organization": "org_acme"}'def test_a_run_with_no_groups_writes_no_groups_attribute(self, mocker: MockerFixture) -> None:span = _start_span(mocker=mocker, llm_job=_make_llm_job())- assert PipelexSpanAttr.RUN_ANALYTICS_GROUPS not in _attributes(span)+ assert PipelexSpanAttr.RUN_EXTRAS not in _attributes(span)def test_langfuse_gets_the_user_id_only_when_it_is_enabled(self, mocker: MockerFixture) -> None:mocker.patch.object(TelemetryManagerAbstract, "get_langfuse_enabled", return_value=True)diff --git a/tests/unit/pipelex/system/telemetry/test_observer_telemetry_identity.py b/tests/unit/pipelex/system/telemetry/test_observer_telemetry_identity.pyindex c3de3cad8..6b177e2ab 100644--- a/tests/unit/pipelex/system/telemetry/test_observer_telemetry_identity.py+++ b/tests/unit/pipelex/system/telemetry/test_observer_telemetry_identity.py@@ -21,7 +21,7 @@ _RUN_METADATA = RunMetadata(user_id="user-42",pipeline_run_id="run-1",storage_scope="tenant/run-1",- analytics_groups={"organization": "org_acme"},+ extras={"organization": "org_acme"},)diff --git a/tests/unit/pipelex/system/telemetry/test_posthog_span_exporter.py b/tests/unit/pipelex/system/telemetry/test_posthog_span_exporter.pyindex 70e2e8818..ec2c64978 100644--- a/tests/unit/pipelex/system/telemetry/test_posthog_span_exporter.py+++ b/tests/unit/pipelex/system/telemetry/test_posthog_span_exporter.py@@ -122,7 +122,7 @@ class TestPostHogSpanExporter:span_category=SpanCategory.PIPE,attributes={PipelexSpanAttr.RUN_USER_ID: "user-42",- PipelexSpanAttr.RUN_ANALYTICS_GROUPS: '{"organization": "org_acme"}',+ PipelexSpanAttr.RUN_EXTRAS: '{"organization": "org_acme"}',},)]@@ -155,7 +155,7 @@ class TestPostHogSpanExporter:span_category=SpanCategory.PIPE,attributes={PipelexSpanAttr.RUN_USER_ID: "user-42",- PipelexSpanAttr.RUN_ANALYTICS_GROUPS: '{"organization": "org_acme"}',+ PipelexSpanAttr.RUN_EXTRAS: '{"organization": "org_acme"}',},)]@@ -176,7 +176,7 @@ class TestPostHogSpanExporter:span_category=SpanCategory.INFERENCE,attributes={PipelexSpanAttr.RUN_USER_ID: "user-42",- PipelexSpanAttr.RUN_ANALYTICS_GROUPS: '{"organization": "org_acme"}',+ PipelexSpanAttr.RUN_EXTRAS: '{"organization": "org_acme"}',},)]diff --git a/tests/unit/pipelex/system/telemetry/test_telemetry_identity.py b/tests/unit/pipelex/system/telemetry/test_telemetry_identity.pyindex 4de91cfde..644d17f2f 100644--- a/tests/unit/pipelex/system/telemetry/test_telemetry_identity.py+++ b/tests/unit/pipelex/system/telemetry/test_telemetry_identity.py@@ -17,23 +17,25 @@ which is what every span produced before this release does.import pytest+from pipelex.system.caller_identity import CallerIdentityfrom pipelex.system.job_metadata import RunMetadatafrom pipelex.system.storage_scope import DRY_RUN_USER_ID, LOCAL_USER_ID, SINGLE_TENANT_USER_IDfrom pipelex.system.telemetry.otel_constants import LangfuseSpanAttr, PipelexSpanAttrfrom pipelex.system.telemetry.telemetry_config import PostHogModefrom pipelex.system.telemetry.telemetry_identity import (RunIdentityPolicy,+ StreamIdentityRule,TelemetryIdentity,make_run_identity_span_attributes,)-def _run_metadata(*, user_id: str = "user-42", analytics_groups: dict[str, str] | None = None) -> RunMetadata:+def _run_metadata(*, user_id: str = "user-42", extras: dict[str, str] | None = None) -> RunMetadata:return RunMetadata(user_id=user_id,pipeline_run_id="run-1",storage_scope="tenant/run-1",- analytics_groups=analytics_groups or {},+ extras=extras or {},)@@ -42,7 +44,7 @@ class TestTelemetryIdentity:def test_a_direct_stream_takes_the_runs_user_and_groups(self) -> None:identity = TelemetryIdentity.make_from_run_metadata(- run_metadata=_run_metadata(analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(extras={"organization": "org_acme"}),fallback_distinct_id="configured-id",run_identity_policy=RunIdentityPolicy.DIRECT,)@@ -85,7 +87,7 @@ class TestTelemetryIdentity:def test_the_groups_are_copied_not_shared_with_the_run(self) -> None:"""The identity is a decision already taken; editing it must not reach back into the run."""- run_metadata = _run_metadata(analytics_groups={"organization": "org_acme"})+ run_metadata = _run_metadata(extras={"organization": "org_acme"})identity = TelemetryIdentity.make_from_run_metadata(run_metadata=run_metadata,fallback_distinct_id=None,@@ -94,7 +96,7 @@ class TestTelemetryIdentity:identity.groups["tenant"] = "t-1"- assert run_metadata.analytics_groups == {"organization": "org_acme"}+ assert run_metadata.extras == {"organization": "org_acme"}# ------------------------------------------------------------------- NONE@@ -108,7 +110,7 @@ class TestTelemetryIdentity:span and on the trace-start event."""identity = TelemetryIdentity.make_from_run_metadata(- run_metadata=_run_metadata(analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(extras={"organization": "org_acme"}),fallback_distinct_id="configured-id",run_identity_policy=RunIdentityPolicy.NONE,)@@ -121,7 +123,7 @@ class TestTelemetryIdentity:identity = TelemetryIdentity.make_from_span_attributes(attributes={PipelexSpanAttr.RUN_USER_ID: "user-42",- PipelexSpanAttr.RUN_ANALYTICS_GROUPS: '{"organization": "org_acme"}',+ PipelexSpanAttr.RUN_EXTRAS: '{"organization": "org_acme"}',},fallback_distinct_id="configured-id",run_identity_policy=RunIdentityPolicy.NONE,@@ -176,10 +178,10 @@ class TestTelemetryIdentity:The two facts are independent: groups carry no person identity, so tyingthem to the distinguishing-user test discarded them from every capture ofa run that simply left `user_id` at its default — which is what- `PipelexRunner(analytics_groups=...)` does by default.+ `PipelexRunner(extras=...)` does by default."""identity = TelemetryIdentity.make_from_run_metadata(- run_metadata=_run_metadata(user_id=placeholder, analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(user_id=placeholder, extras={"organization": "org_acme"}),fallback_distinct_id="configured-id",run_identity_policy=RunIdentityPolicy.DIRECT,)@@ -211,12 +213,12 @@ class TestTelemetryIdentity:def test_a_run_with_groups_writes_both_attributes(self) -> None:attributes = make_run_identity_span_attributes(- run_metadata=_run_metadata(analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(extras={"organization": "org_acme"}),is_langfuse_enabled=False,)assert attributes[PipelexSpanAttr.RUN_USER_ID] == "user-42"- assert attributes[PipelexSpanAttr.RUN_ANALYTICS_GROUPS] == '{"organization": "org_acme"}'+ assert attributes[PipelexSpanAttr.RUN_EXTRAS] == '{"organization": "org_acme"}'assert LangfuseSpanAttr.USER_ID not in attributesdef test_a_run_without_groups_omits_the_groups_attribute(self) -> None:@@ -224,7 +226,7 @@ class TestTelemetryIdentity:attributes = make_run_identity_span_attributes(run_metadata=_run_metadata(), is_langfuse_enabled=False)assert attributes[PipelexSpanAttr.RUN_USER_ID] == "user-42"- assert PipelexSpanAttr.RUN_ANALYTICS_GROUPS not in attributes+ assert PipelexSpanAttr.RUN_EXTRAS not in attributesdef test_langfuse_gets_the_user_id_in_the_field_it_reserves_for_it(self) -> None:attributes = make_run_identity_span_attributes(run_metadata=_run_metadata(), is_langfuse_enabled=True)@@ -248,7 +250,7 @@ class TestTelemetryIdentity:assert LangfuseSpanAttr.USER_ID not in attributesdef test_what_a_span_site_writes_is_what_the_exporter_reads_back(self) -> None:- run_metadata = _run_metadata(analytics_groups={"organization": "org_acme", "tenant": "t-1"})+ run_metadata = _run_metadata(extras={"organization": "org_acme", "tenant": "t-1"})attributes = make_run_identity_span_attributes(run_metadata=run_metadata, is_langfuse_enabled=False)identity = TelemetryIdentity.make_from_span_attributes(@@ -276,7 +278,7 @@ class TestTelemetryIdentity:identity = TelemetryIdentity.make_from_span_attributes(attributes={PipelexSpanAttr.RUN_USER_ID: "user-42",- PipelexSpanAttr.RUN_ANALYTICS_GROUPS: "not json at all",+ PipelexSpanAttr.RUN_EXTRAS: "not json at all",},fallback_distinct_id="configured-id",run_identity_policy=RunIdentityPolicy.DIRECT,@@ -289,7 +291,7 @@ class TestTelemetryIdentity:identity = TelemetryIdentity.make_from_span_attributes(attributes={PipelexSpanAttr.RUN_USER_ID: "user-42",- PipelexSpanAttr.RUN_ANALYTICS_GROUPS: '["organization"]',+ PipelexSpanAttr.RUN_EXTRAS: '["organization"]',},fallback_distinct_id=None,run_identity_policy=RunIdentityPolicy.DIRECT,@@ -301,7 +303,7 @@ class TestTelemetryIdentity:identity = TelemetryIdentity.make_from_span_attributes(attributes={PipelexSpanAttr.RUN_USER_ID: "user-42",- PipelexSpanAttr.RUN_ANALYTICS_GROUPS: '{"organization": "org_acme", "count": 3}',+ PipelexSpanAttr.RUN_EXTRAS: '{"organization": "org_acme", "count": 3}',},fallback_distinct_id=None,run_identity_policy=RunIdentityPolicy.DIRECT,@@ -317,3 +319,45 @@ class TestTelemetryIdentity:)assert identity.distinct_id == "configured-id"+++class TestResolutionFromACaller:+ """A caller known without a run resolves exactly as a run naming the same caller would."""++ @pytest.mark.parametrize("policy", list(RunIdentityPolicy))+ @pytest.mark.parametrize("user_id", ["user-42", LOCAL_USER_ID, DRY_RUN_USER_ID])+ def test_a_caller_resolves_like_the_run_it_would_state(self, policy: RunIdentityPolicy, user_id: str) -> None:+ groups = {"organization": "org_acme"}++ from_caller = TelemetryIdentity.make_from_caller_identity(+ caller_identity=CallerIdentity(user_id=user_id, extras=groups),+ fallback_distinct_id="fallback-id",+ run_identity_policy=policy,+ )+ from_run = TelemetryIdentity.make_from_run_metadata(+ run_metadata=_run_metadata(user_id=user_id, extras=groups),+ fallback_distinct_id="fallback-id",+ run_identity_policy=policy,+ )++ assert from_caller == from_run++ def test_no_caller_resolves_to_the_fallback(self) -> None:+ identity = TelemetryIdentity.make_from_caller_identity(+ caller_identity=None,+ fallback_distinct_id="fallback-id",+ run_identity_policy=RunIdentityPolicy.DIRECT,+ )++ assert identity == TelemetryIdentity(distinct_id="fallback-id", groups={})++ def test_a_stream_rule_resolves_per_caller(self) -> None:+ rule = StreamIdentityRule(fallback_distinct_id="fallback-id", run_identity_policy=RunIdentityPolicy.DIRECT)++ assert rule.resolve(caller_identity=CallerIdentity(user_id="user-42")).distinct_id == "user-42"+ assert rule.resolve(caller_identity=None).distinct_id == "fallback-id"++ def test_an_anonymous_stream_rule_identifies_nobody(self) -> None:+ rule = StreamIdentityRule(fallback_distinct_id="fallback-id", run_identity_policy=RunIdentityPolicy.NONE)++ assert rule.resolve(caller_identity=CallerIdentity(user_id="user-42")).is_anonymousdiff --git a/tests/unit/pipelex/system/telemetry/test_telemetry_manager_identity.py b/tests/unit/pipelex/system/telemetry/test_telemetry_manager_identity.pyindex de5ce2796..8ab289b40 100644--- a/tests/unit/pipelex/system/telemetry/test_telemetry_manager_identity.py+++ b/tests/unit/pipelex/system/telemetry/test_telemetry_manager_identity.py@@ -18,19 +18,21 @@ from typing import Anyfrom posthog import Posthogfrom pytest_mock import MockerFixture+from pipelex.system.caller_identity import CallerIdentity, scoped_caller_identityfrom pipelex.system.job_metadata import RunMetadata+from pipelex.system.storage_scope import LOCAL_USER_IDfrom pipelex.system.telemetry.events import EventNamefrom pipelex.system.telemetry.otel_constants import PostHogAttrfrom pipelex.system.telemetry.telemetry_config import PostHogConfig, PostHogMode, PostHogTracingConfig, TelemetryConfigfrom pipelex.system.telemetry.telemetry_manager import TelemetryManager-def _run_metadata(*, user_id: str = "user-42", analytics_groups: dict[str, str] | None = None) -> RunMetadata:+def _run_metadata(*, user_id: str = "user-42", extras: dict[str, str] | None = None) -> RunMetadata:return RunMetadata(user_id=user_id,pipeline_run_id="run-1",storage_scope="tenant/run-1",- analytics_groups=analytics_groups or {},+ extras=extras or {},)@@ -62,13 +64,16 @@ def _make_manager(return manager, custom_client, pipelex_client+_CALLER = CallerIdentity(user_id="caller-7", extras={"organization": "org_caller"})++class TestTelemetryManagerIdentity:def test_an_event_from_a_run_is_attributed_to_the_runs_user(self, mocker: MockerFixture) -> None:manager, custom_client, _ = _make_manager(mocker=mocker, mode=PostHogMode.IDENTIFIED, configured_user_id="configured-id")manager.track_event(EventName.PIPE_RUN,- run_metadata=_run_metadata(analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(extras={"organization": "org_acme"}),)capture_kwargs = custom_client.capture.call_args.kwargs@@ -90,7 +95,7 @@ class TestTelemetryManagerIdentity:manager.track_event(EventName.PIPE_RUN,- run_metadata=_run_metadata(analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(extras={"organization": "org_acme"}),)capture_kwargs = custom_client.capture.call_args.kwargs@@ -117,7 +122,7 @@ class TestTelemetryManagerIdentity:manager.track_event(EventName.PIPE_RUN,- run_metadata=_run_metadata(analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(extras={"organization": "org_acme"}),)capture_kwargs = pipelex_client.capture.call_args.kwargs@@ -160,7 +165,7 @@ class TestTelemetryManagerIdentity:trace_name="some_pipe_abc12345",trace_name_redacted="abc12345",trace_id=1234,- run_metadata=_run_metadata(analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(extras={"organization": "org_acme"}),)capture_kwargs = custom_client.capture.call_args.kwargs@@ -181,7 +186,7 @@ class TestTelemetryManagerIdentity:trace_name="some_pipe_abc12345",trace_name_redacted="abc12345",trace_id=1234,- run_metadata=_run_metadata(analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(extras={"organization": "org_acme"}),)capture_kwargs = custom_client.capture.call_args.kwargs@@ -201,7 +206,7 @@ class TestTelemetryManagerIdentity:trace_name="some_pipe_abc12345",trace_name_redacted="abc12345",trace_id=1234,- run_metadata=_run_metadata(analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(extras={"organization": "org_acme"}),)capture_kwargs = custom_client.capture.call_args.kwargs@@ -222,7 +227,7 @@ class TestTelemetryManagerIdentity:trace_name="some_pipe_abc12345",trace_name_redacted="abc12345",trace_id=1234,- run_metadata=_run_metadata(analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(extras={"organization": "org_acme"}),)capture_kwargs = pipelex_client.capture.call_args.kwargs@@ -236,9 +241,81 @@ class TestTelemetryManagerIdentity:trace_name="some_pipe_abc12345",trace_name_redacted="abc12345",trace_id=1234,- run_metadata=_run_metadata(analytics_groups={"organization": "org_acme"}),+ run_metadata=_run_metadata(extras={"organization": "org_acme"}),)rendered = repr(custom_client.capture.call_args.kwargs["properties"])assert "user-42" not in renderedassert "org_acme" not in rendered++ def test_an_event_with_no_run_is_attributed_to_the_caller_in_scope(self, mocker: MockerFixture) -> None:+ manager, custom_client, _ = _make_manager(mocker=mocker, mode=PostHogMode.IDENTIFIED, configured_user_id="pipelex-runner")++ with scoped_caller_identity(caller_identity=_CALLER):+ manager.track_event(EventName.PIPE_DRY_RUN)++ capture_kwargs = custom_client.capture.call_args.kwargs+ assert capture_kwargs["distinct_id"] == "caller-7"+ assert capture_kwargs["groups"] == {"organization": "org_caller"}++ def test_the_run_in_hand_wins_over_the_caller_in_scope(self, mocker: MockerFixture) -> None:+ """The run the emitter holds is the most specific fact there is."""+ manager, custom_client, _ = _make_manager(mocker=mocker, mode=PostHogMode.IDENTIFIED, configured_user_id="pipelex-runner")++ with scoped_caller_identity(caller_identity=_CALLER):+ manager.track_event(EventName.PIPE_RUN, run_metadata=_run_metadata())++ assert custom_client.capture.call_args.kwargs["distinct_id"] == "user-42"++ def test_a_placeholder_caller_in_scope_still_reports_under_the_configured_id(self, mocker: MockerFixture) -> None:+ """A local runtime states `local`, which names nobody — the CLI keeps reporting as it did."""+ manager, custom_client, _ = _make_manager(mocker=mocker, mode=PostHogMode.IDENTIFIED, configured_user_id="configured-id")++ with scoped_caller_identity(caller_identity=CallerIdentity(user_id=LOCAL_USER_ID)):+ manager.track_event(EventName.PIPE_DRY_RUN)++ assert custom_client.capture.call_args.kwargs["distinct_id"] == "configured-id"++ def test_an_anonymous_stream_identifies_nobody_whatever_the_scope_says(self, mocker: MockerFixture) -> None:+ manager, custom_client, _ = _make_manager(mocker=mocker, mode=PostHogMode.ANONYMOUS, configured_user_id="configured-id")++ with scoped_caller_identity(caller_identity=_CALLER):+ manager.track_event(EventName.PIPE_DRY_RUN)++ capture_kwargs = custom_client.capture.call_args.kwargs+ assert "distinct_id" not in capture_kwargs+ assert capture_kwargs["properties"][PostHogAttr.PROCESS_PERSON_PROFILE] is False++ def test_the_caller_in_scope_never_becomes_a_property(self, mocker: MockerFixture) -> None:+ manager, custom_client, _ = _make_manager(mocker=mocker, mode=PostHogMode.IDENTIFIED, configured_user_id="configured-id")++ with scoped_caller_identity(caller_identity=_CALLER):+ manager.track_event(EventName.PIPE_DRY_RUN)++ properties = custom_client.capture.call_args.kwargs["properties"]+ assert "caller-7" not in repr(properties)+ assert "org_caller" not in repr(properties)++ def test_the_pipelex_stream_resolves_the_caller_in_scope_under_its_own_policy(self, mocker: MockerFixture) -> None:+ manager, _, pipelex_client = _make_manager(+ mocker=mocker,+ mode=PostHogMode.OFF,+ configured_user_id=None,+ pipelex_distinct_id="gateway-hash",+ )+ assert pipelex_client is not None++ with scoped_caller_identity(caller_identity=_CALLER):+ manager.track_event(EventName.PIPE_DRY_RUN)++ assert pipelex_client.capture.call_args.kwargs["distinct_id"] == "caller-7"++ def test_a_trace_start_with_no_run_is_attributed_to_the_caller_in_scope(self, mocker: MockerFixture) -> None:+ manager, custom_client, _ = _make_manager(mocker=mocker, mode=PostHogMode.IDENTIFIED, configured_user_id="pipelex-runner")++ with scoped_caller_identity(caller_identity=_CALLER):+ manager.handle_trace_start(trace_name="some_pipe_abc12345", trace_name_redacted="abc12345", trace_id=1234)++ capture_kwargs = custom_client.capture.call_args.kwargs+ assert capture_kwargs["distinct_id"] == "caller-7"+ assert capture_kwargs["groups"] == {"organization": "org_caller"}diff --git a/tests/unit/pipelex/system/test_caller_identity.py b/tests/unit/pipelex/system/test_caller_identity.pynew file mode 100644index 000000000..57ef50b81--- /dev/null+++ b/tests/unit/pipelex/system/test_caller_identity.py@@ -0,0 +1,167 @@+"""Unit tests for the ambient caller and the stamp an escaping exception carries.++The scope is what lets a capture with no run in hand — the validation sweep's+event, an exception raised while a pipe ran — still name the caller it was made+for. These tests pin its three promises: it is current inside the block and+gone after it, `None` inherits rather than clears, and an exception leaving the+block remembers the caller it escaped from, innermost scope first.+"""++import asyncio++import pytest+from pydantic import ValidationError+from typing_extensions import override++from pipelex.system.caller_identity import (+ CallerIdentity,+ find_stamped_caller_identity,+ get_current_caller_identity,+ scoped_caller_identity,+ stamp_caller_identity,+)+from pipelex.system.job_metadata import RunMetadata++_ALICE = CallerIdentity(user_id="user-alice", extras={"organization": "org_acme"})+_BOB = CallerIdentity(user_id="user-bob")+++class _SlottedError(Exception):+ """An error type that refuses new attributes, so it cannot carry a stamp."""++ __slots__ = ()++ @override+ def __setattr__(self, name: str, value: object) -> None:+ msg = f"'{type(self).__name__}' refuses attribute '{name}'"+ raise AttributeError(msg)+++class TestCallerIdentity:+ def test_it_is_built_from_a_runs_metadata(self) -> None:+ run_metadata = RunMetadata(+ user_id="user-42",+ pipeline_run_id="run-1",+ storage_scope="tenant/run-1",+ extras={"organization": "org_acme"},+ )++ caller_identity = CallerIdentity.make_from_run_metadata(run_metadata=run_metadata)++ assert caller_identity == CallerIdentity(user_id="user-42", extras={"organization": "org_acme"})++ def test_a_host_with_no_groups_states_an_empty_mapping(self) -> None:+ assert CallerIdentity.make_from_host(user_id="user-42", extras=None).extras == {}++ def test_its_groups_are_validated_like_a_runs(self) -> None:+ """The groups reach a telemetry backend, so a malformed key is refused at construction."""+ with pytest.raises(ValidationError, match="extras"):+ CallerIdentity(user_id="user-42", extras={"organization": "has a space"})++ def test_there_is_no_caller_outside_every_scope(self) -> None:+ assert get_current_caller_identity() is None++ def test_the_caller_is_current_inside_the_block_and_gone_after_it(self) -> None:+ with scoped_caller_identity(caller_identity=_ALICE) as current:+ assert current == _ALICE+ assert get_current_caller_identity() == _ALICE+ assert get_current_caller_identity() is None++ def test_none_inherits_the_caller_already_in_scope(self) -> None:+ """A caller-less entry point nested in a caller's work still works for that caller."""+ with scoped_caller_identity(caller_identity=_ALICE):+ with scoped_caller_identity(caller_identity=None) as current:+ assert current == _ALICE+ assert get_current_caller_identity() == _ALICE++ def test_an_inner_caller_replaces_the_outer_one_until_it_closes(self) -> None:+ with scoped_caller_identity(caller_identity=_ALICE):+ with scoped_caller_identity(caller_identity=_BOB):+ assert get_current_caller_identity() == _BOB+ assert get_current_caller_identity() == _ALICE++ @pytest.mark.asyncio+ async def test_concurrent_tasks_do_not_see_each_others_caller(self) -> None:+ """A `ContextVar`, so two requests served on one event loop stay apart."""+ seen: dict[str, CallerIdentity | None] = {}++ async def serve(*, caller_identity: CallerIdentity, name: str) -> None:+ with scoped_caller_identity(caller_identity=caller_identity):+ await asyncio.sleep(0)+ seen[name] = get_current_caller_identity()++ await asyncio.gather(serve(caller_identity=_ALICE, name="alice"), serve(caller_identity=_BOB, name="bob"))++ assert seen == {"alice": _ALICE, "bob": _BOB}++ def test_an_exception_leaving_the_block_is_stamped_and_still_propagates(self) -> None:+ msg = "boom"+ with pytest.raises(ValueError, match="boom") as exc_info, scoped_caller_identity(caller_identity=_ALICE):+ raise ValueError(msg)++ assert find_stamped_caller_identity(exception=exc_info.value) == _ALICE+ assert get_current_caller_identity() is None++ def test_the_innermost_scope_wins_the_stamp(self) -> None:+ """The scope closest to the failure knows the work it came from; an outer one never overwrites it."""+ msg = "boom"+ with (+ pytest.raises(ValueError, match="boom") as exc_info,+ scoped_caller_identity(caller_identity=_ALICE),+ scoped_caller_identity(caller_identity=_BOB),+ ):+ raise ValueError(msg)++ assert find_stamped_caller_identity(exception=exc_info.value) == _BOB++ def test_a_scope_that_opened_nothing_stamps_nothing(self) -> None:+ msg = "boom"+ with pytest.raises(ValueError, match="boom") as exc_info, scoped_caller_identity(caller_identity=None):+ raise ValueError(msg)++ assert find_stamped_caller_identity(exception=exc_info.value) is None++ def test_an_exception_that_refuses_attributes_still_propagates(self) -> None:+ """Telemetry must never change how an error travels."""+ with pytest.raises(_SlottedError), scoped_caller_identity(caller_identity=_ALICE):+ raise _SlottedError++ assert get_current_caller_identity() is None++ def test_it_reads_the_stamp_through_an_explicit_cause(self) -> None:+ """A host re-raises its own error `from` the run's, and that outer error is what reaches the hook."""+ inner = ValueError("inner")+ stamp_caller_identity(exception=inner, caller_identity=_ALICE)+ outer = RuntimeError("outer")+ outer.__cause__ = inner++ assert find_stamped_caller_identity(exception=outer) == _ALICE++ def test_it_reads_the_stamp_through_an_implicit_context(self) -> None:+ inner = ValueError("inner")+ stamp_caller_identity(exception=inner, caller_identity=_ALICE)+ outer = RuntimeError("outer")+ outer.__context__ = inner++ assert find_stamped_caller_identity(exception=outer) == _ALICE++ def test_it_reads_the_stamp_inside_an_exception_group(self) -> None:+ member = ValueError("member")+ stamp_caller_identity(exception=member, caller_identity=_ALICE)++ assert find_stamped_caller_identity(exception=ExceptionGroup("group", [member])) == _ALICE++ def test_a_cyclic_chain_terminates(self) -> None:+ first = ValueError("first")+ second = ValueError("second")+ first.__context__ = second+ second.__context__ = first++ assert find_stamped_caller_identity(exception=first) is None++ def test_an_existing_stamp_is_never_replaced(self) -> None:+ error = ValueError("boom")+ stamp_caller_identity(exception=error, caller_identity=_ALICE)+ stamp_caller_identity(exception=error, caller_identity=_BOB)++ assert find_stamped_caller_identity(exception=error) == _ALICEdiff --git a/tests/unit/pipelex/system/test_analytics_groups.py b/tests/unit/pipelex/system/test_run_extras.pysimilarity index 69%rename from tests/unit/pipelex/system/test_analytics_groups.pyrename to tests/unit/pipelex/system/test_run_extras.pyindex dafc8da12..4c2694e55 100644--- a/tests/unit/pipelex/system/test_analytics_groups.py+++ b/tests/unit/pipelex/system/test_run_extras.py@@ -1,4 +1,4 @@-"""`analytics_groups` — the construction-time guard on the host's opaque group labels.+"""`extras` — the construction-time guard on the host's opaque labels.The mapping is host-supplied and arrives over a wire, so it is exactly the kindof value that must be refused at the type rather than three frames into a run.@@ -14,61 +14,61 @@ from __future__ import annotationsimport pytestfrom pydantic import ValidationError-from pipelex.system.analytics_groups import (- ANALYTICS_GROUP_KEY_PATTERN,- ANALYTICS_GROUP_TYPE_PATTERN,- ANALYTICS_GROUPS_MAX_ENTRIES,- validate_analytics_groups,-)from pipelex.system.job_metadata import JobMetadata, RunMetadata+from pipelex.system.run_extras import (+ RUN_EXTRAS_KEY_PATTERN,+ RUN_EXTRAS_MAX_ENTRIES,+ RUN_EXTRAS_VALUE_PATTERN,+ validate_run_extras,+)-def _metadata(analytics_groups: dict[str, str]) -> JobMetadata:+def _metadata(extras: dict[str, str]) -> JobMetadata:return JobMetadata(run_metadata=RunMetadata(user_id="u1",pipeline_run_id="run_1",storage_scope="tenant/run_1",- analytics_groups=analytics_groups,+ extras=extras,))-class TestAnalyticsGroups:+class TestRunExtras:@pytest.mark.parametrize(- "groups",+ "extras",[pytest.param({}, id="empty-mapping"),pytest.param({"organization": "org_acme"}, id="the-hosted-plane-shape"),- pytest.param({"organization": "org_acme", "workspace": "ws-1"}, id="two-group-types"),+ pytest.param({"organization": "org_acme", "workspace": "ws-1"}, id="two-keys"),pytest.param({"a": "x"}, id="shortest-key-and-value"),pytest.param({"a_b_c9": "A-Z_az-09"}, id="full-charset"),pytest.param({"a" * 32: "v" * 128}, id="longest-key-and-value"),- pytest.param({f"g{index}": "v" for index in range(ANALYTICS_GROUPS_MAX_ENTRIES)}, id="at-the-entry-cap"),+ pytest.param({f"g{index}": "v" for index in range(RUN_EXTRAS_MAX_ENTRIES)}, id="at-the-entry-cap"),],)- def test_well_formed_groups_are_accepted(self, groups: dict[str, str]) -> None:- assert _metadata(groups).run_metadata.analytics_groups == groups+ def test_well_formed_extras_are_accepted(self, extras: dict[str, str]) -> None:+ assert _metadata(extras).run_metadata.extras == extrasdef test_an_empty_mapping_is_the_default(self) -> None:"""Unlike `user_id` and `storage_scope`, this field defaults.- An absent group creates no shared namespace and misattributes nothing —+ An absent label creates no shared namespace and misattributes nothing —it only leaves the group facet empty. The doctrine that made the othertwo required is about IDENTITY, and identity is still non-defaulting."""run_metadata = RunMetadata(user_id="u1", pipeline_run_id="run_1", storage_scope="tenant/run_1")- assert run_metadata.analytics_groups == {}+ assert run_metadata.extras == {}def test_two_run_metadatas_do_not_share_one_default_mapping(self) -> None:- """A mutable default shared between instances would let one run's groups leak into another."""+ """A mutable default shared between instances would let one run's extras leak into another."""first = RunMetadata(user_id="u1", pipeline_run_id="run_1", storage_scope="tenant/run_1")second = RunMetadata(user_id="u2", pipeline_run_id="run_2", storage_scope="tenant/run_2")- first.analytics_groups["organization"] = "org_acme"- assert second.analytics_groups == {}+ first.extras["organization"] = "org_acme"+ assert second.extras == {}@pytest.mark.parametrize(- "groups",+ "extras",[pytest.param({"Organization": "org_acme"}, id="uppercase-key"),pytest.param({"9org": "org_acme"}, id="key-starting-with-a-digit"),@@ -91,65 +91,65 @@ class TestAnalyticsGroups:pytest.param({"organization": "org_acme\r"}, id="trailing-carriage-return-in-value"),pytest.param({"organization\n": "org_acme"}, id="trailing-newline-in-key"),pytest.param({"organization": "v" * 129}, id="value-one-over-the-length-cap"),- pytest.param({f"g{index}": "v" for index in range(ANALYTICS_GROUPS_MAX_ENTRIES + 1)}, id="one-over-the-entry-cap"),+ pytest.param({f"g{index}": "v" for index in range(RUN_EXTRAS_MAX_ENTRIES + 1)}, id="one-over-the-entry-cap"),],)- def test_malformed_groups_raise_at_construction(self, groups: dict[str, str]) -> None:+ def test_malformed_extras_raise_at_construction(self, extras: dict[str, str]) -> None:"""Refused when the object is BUILT, not when a telemetry consumer chokes on it.Same reasoning as `storage_scope`: a `RunMetadata` that exists is one- whose groups are safe to forward, so no downstream exporter has to+ whose extras are safe to forward, so no downstream exporter has tore-check them."""with pytest.raises(ValidationError):- _metadata(groups)+ _metadata(extras)def test_the_error_names_the_offending_entry(self) -> None:"""The caller supplied the mapping, so the message must say which entry it got wrong."""with pytest.raises(ValidationError, match="Organization"):_metadata({"Organization": "org_acme"})- def test_an_unknown_group_type_is_carried_through(self) -> None:+ def test_an_unknown_key_is_carried_through(self) -> None:"""No key is privileged: `organization` is the hosted plane's word, not the runtime's.The runtime is forbidden to learn what an organization is — the same rule- that keeps `storage_scope` opaque — so a group type it has never heard of+ that keeps `storage_scope` opaque — so a key it has never heard ofmust travel exactly as well as the one the platform happens to send."""- groups = {"tenant": "t-1", "plan_tier": "enterprise"}- assert _metadata(groups).run_metadata.analytics_groups == groups+ extras = {"tenant": "t-1", "plan_tier": "enterprise"}+ assert _metadata(extras).run_metadata.extras == extras- def test_copy_with_update_carries_the_groups_through(self) -> None:+ def test_copy_with_update_carries_the_extras_through(self) -> None:"""`copy_with_update` replaces the per-job half and carries the run half intact.A nested pipe's span is part of the same run, so it must attribute to the- same groups. Losing them here would leave the group facet empty for every+ same extras. Losing them here would leave the group facet empty for everyspan but the outermost one."""parent = _metadata({"organization": "org_acme"})child = parent.copy_with_update(otel_context=None, pipe_code="nested_pipe")- assert child.run_metadata.analytics_groups == {"organization": "org_acme"}+ assert child.run_metadata.extras == {"organization": "org_acme"}assert child.pipe_code == "nested_pipe"def test_the_copy_does_not_alias_the_parents_mapping(self) -> None:- """`copy_with_update` deep-copies, so a child mutating its groups cannot reach the parent."""+ """`copy_with_update` deep-copies, so a child mutating its extras cannot reach the parent."""parent = _metadata({"organization": "org_acme"})child = parent.copy_with_update(otel_context=None)- child.run_metadata.analytics_groups["organization"] = "org_other"- assert parent.run_metadata.analytics_groups == {"organization": "org_acme"}+ child.run_metadata.extras["organization"] = "org_other"+ assert parent.run_metadata.extras == {"organization": "org_acme"}def test_the_helper_returns_the_mapping_it_was_given(self) -> None:- groups = {"organization": "org_acme"}- assert validate_analytics_groups(value=groups) == groups+ extras = {"organization": "org_acme"}+ assert validate_run_extras(value=extras) == extrasdef test_the_helper_raises_value_error_rather_than_a_pydantic_error(self) -> None:"""It is shared by the field validator and the wire payload, so it speaks stdlib."""- with pytest.raises(ValueError, match="analytics_groups"):- validate_analytics_groups(value={"Organization": "org_acme"})+ with pytest.raises(ValueError, match="extras"):+ validate_run_extras(value={"Organization": "org_acme"})def test_the_patterns_are_anchored_by_fullmatch_not_by_the_dollar_sign(self) -> None:"""`re.match` with a trailing `$` accepts one final newline; `fullmatch` does not."""- assert ANALYTICS_GROUP_TYPE_PATTERN.match("organization\n") is not None- assert ANALYTICS_GROUP_TYPE_PATTERN.fullmatch("organization\n") is None- assert ANALYTICS_GROUP_KEY_PATTERN.match("org_acme\n") is not None- assert ANALYTICS_GROUP_KEY_PATTERN.fullmatch("org_acme\n") is None+ assert RUN_EXTRAS_KEY_PATTERN.match("organization\n") is not None+ assert RUN_EXTRAS_KEY_PATTERN.fullmatch("organization\n") is None+ assert RUN_EXTRAS_VALUE_PATTERN.match("org_acme\n") is not None+ assert RUN_EXTRAS_VALUE_PATTERN.fullmatch("org_acme\n") is None