docs(ir,datamodels): clarify three concept-audit-flagged fields

Pure docstring updates per recent fundamental-concept-audit verdicts.
No behavior change.

- ir.Symbol.origin: document the analyzer-id-vs-synthesis-mechanism axis
  mix and the WI-nusum-nukol re-eval trigger (WI-kiriz).
- datamodels.DataModelKind: surface the three-axis confusion (language
  construct / library / architectural role) and the WI-juvag-numud
  re-eval triggers (WI-sudov).
- ir.UsageContext.kind: surface the syntactic-construct-vs-semantic-role
  axis mix and the WI-gatuh-ruvar re-eval triggers (WI-hofoj).

Closes WI-kiriz, WI-sudov, WI-hofoj.

Signed-off-by: jgstern-agent <josh-agent@iterabloom.com>

Author: jgstern-agent

.ci/affected-tests.txt

@@ -1,12 +1,180 @@
 # Test selection manifest
-# Generated by smart-test at 2026-05-02T03:54:20-04:00
+# Generated by smart-test at 2026-05-02T04:22:28-04:00
 # Mode: targeted
-# Baseline: f71139302408e0bad0a15d4c00c0718f088b0762
-# Changed files: 11
-# Changed source files: 0
-0
-# Selected tests: 1
+# Baseline: 989a35bd7dc16209d641af307605bdcfc6907a11
+# Changed files: 6
+# Changed source files: 2
+# Selected tests: 168
 #
 # === CHANGED_SOURCE_FILES ===
+packages/hypergumbo-core/src/hypergumbo_core/datamodels.py
+packages/hypergumbo-core/src/hypergumbo_core/ir.py
 # === SELECTED_TESTS ===
-tests/test_on_transcript_change.py
+packages/hypergumbo-core/tests/BRANCHES_test_compact.py
+packages/hypergumbo-core/tests/BRANCHES_test_database_query.py
+packages/hypergumbo-core/tests/BRANCHES_test_framework_patterns.py
+packages/hypergumbo-core/tests/BRANCHES_test_graphql.py
+packages/hypergumbo-core/tests/BRANCHES_test_graphql_resolver.py
+packages/hypergumbo-core/tests/BRANCHES_test_http.py
+packages/hypergumbo-core/tests/BRANCHES_test_ipc.py
+packages/hypergumbo-core/tests/BRANCHES_test_openapi.py
+packages/hypergumbo-core/tests/BRANCHES_test_phoenix_ipc.py
+packages/hypergumbo-core/tests/BRANCHES_test_route_handler.py
+packages/hypergumbo-core/tests/BRANCHES_test_slice.py
+packages/hypergumbo-core/tests/BRANCHES_test_subprocess_cli.py
+packages/hypergumbo-core/tests/test_airflow_framework_dispatch_linker.py
+packages/hypergumbo-core/tests/test_analyzer_registry.py
+packages/hypergumbo-core/tests/test_annotation_convention_linker.py
+packages/hypergumbo-core/tests/test_backend_cli_flag.py
+packages/hypergumbo-core/tests/test_base.py
+packages/hypergumbo-core/tests/test_build_grammars.py
+packages/hypergumbo-core/tests/test_build_target_linker.py
+packages/hypergumbo-core/tests/test_cgo_linker.py
+packages/hypergumbo-core/tests/test_cli_basic.py
+packages/hypergumbo-core/tests/test_cli_cache.py
+packages/hypergumbo-core/tests/test_cli_commands.py
+packages/hypergumbo-core/tests/test_cli_config.py
+packages/hypergumbo-core/tests/test_cli_dead_code.py
+packages/hypergumbo-core/tests/test_cli_explain.py
+packages/hypergumbo-core/tests/test_cli_io_boundaries.py
+packages/hypergumbo-core/tests/test_cli_relativize_paths.py
+packages/hypergumbo-core/tests/test_cli_routes.py
+packages/hypergumbo-core/tests/test_cli_run_behavior_map.py
+packages/hypergumbo-core/tests/test_cli_search.py
+packages/hypergumbo-core/tests/test_cli_symbols.py
+packages/hypergumbo-core/tests/test_cli_test_coverage.py
+packages/hypergumbo-core/tests/test_cli_verify_claims.py
+packages/hypergumbo-core/tests/test_compact.py
+packages/hypergumbo-core/tests/test_concept_utils.py
+packages/hypergumbo-core/tests/test_containment_linker.py
+packages/hypergumbo-core/tests/test_controller_routes_linker.py
+packages/hypergumbo-core/tests/test_crypto_flow_linker.py
+packages/hypergumbo-core/tests/test_database_query_linker.py
+packages/hypergumbo-core/tests/test_dataflow.py
+packages/hypergumbo-core/tests/test_datamodels.py
+packages/hypergumbo-core/tests/test_decorator_dispatch_linker.py
+packages/hypergumbo-core/tests/test_dependency_linker.py
+packages/hypergumbo-core/tests/test_django_orm_dispatch_linker.py
+packages/hypergumbo-core/tests/test_entrypoints.py
+packages/hypergumbo-core/tests/test_event_sourcing_linker.py
+packages/hypergumbo-core/tests/test_fastapi_patterns.py
+packages/hypergumbo-core/tests/test_file_excludes.py
+packages/hypergumbo-core/tests/test_framework_patterns.py
+packages/hypergumbo-core/tests/test_frameworks_flag.py
+packages/hypergumbo-core/tests/test_gitleaks.py
+packages/hypergumbo-core/tests/test_go_cobra_linker.py
+packages/hypergumbo-core/tests/test_go_memberlist_linker.py
+packages/hypergumbo-core/tests/test_graphql_linker.py
+packages/hypergumbo-core/tests/test_graphql_resolver_linker.py
+packages/hypergumbo-core/tests/test_grpc_linker.py
+packages/hypergumbo-core/tests/test_handler_slices.py
+packages/hypergumbo-core/tests/test_http_linker.py
+packages/hypergumbo-core/tests/test_inheritance_linker.py
+packages/hypergumbo-core/tests/test_ipc_linker.py
+packages/hypergumbo-core/tests/test_ir.py
+packages/hypergumbo-core/tests/test_jackson_dispatch_linker.py
+packages/hypergumbo-core/tests/test_jni_linker.py
+packages/hypergumbo-core/tests/test_js_module_linker.py
+packages/hypergumbo-core/tests/test_kafka_streams_dispatch_linker.py
+packages/hypergumbo-core/tests/test_linker_di_resolution.py
+packages/hypergumbo-core/tests/test_linker_docstring_fp_regression.py
+packages/hypergumbo-core/tests/test_linker_filtering.py
+packages/hypergumbo-core/tests/test_linker_parse_cache.py
+packages/hypergumbo-core/tests/test_linker_registry.py
+packages/hypergumbo-core/tests/test_locale.py
+packages/hypergumbo-core/tests/test_lua_ffi_linker.py
+packages/hypergumbo-core/tests/test_max_tier.py
+packages/hypergumbo-core/tests/test_message_dispatch_linker.py
+packages/hypergumbo-core/tests/test_message_queue_linker.py
+packages/hypergumbo-core/tests/test_method_call_recovery_linker.py
+packages/hypergumbo-core/tests/test_middleware_chain_linker.py
+packages/hypergumbo-core/tests/test_napi_linker.py
+packages/hypergumbo-core/tests/test_no_first_party_priority.py
+packages/hypergumbo-core/tests/test_openapi_linker.py
+packages/hypergumbo-core/tests/test_orm_linker.py
+packages/hypergumbo-core/tests/test_otp_linker.py
+packages/hypergumbo-core/tests/test_phoenix_ipc_linker.py
+packages/hypergumbo-core/tests/test_profile.py
+packages/hypergumbo-core/tests/test_pyffi_linker.py
+packages/hypergumbo-core/tests/test_ranking.py
+packages/hypergumbo-core/tests/test_react_component_linker.py
+packages/hypergumbo-core/tests/test_route_handler_linker.py
+packages/hypergumbo-core/tests/test_router_routes_linker.py
+packages/hypergumbo-core/tests/test_rubyffi_linker.py
+packages/hypergumbo-core/tests/test_run_behavior_map.py
+packages/hypergumbo-core/tests/test_rust_trait_dispatch_linker.py
+packages/hypergumbo-core/tests/test_schema_compliance.py
+packages/hypergumbo-core/tests/test_schema.py
+packages/hypergumbo-core/tests/test_scip_calls.py
+packages/hypergumbo-core/tests/test_scip_edges.py
+packages/hypergumbo-core/tests/test_scip_index.py
+packages/hypergumbo-core/tests/test_selection_language_proportional.py
+packages/hypergumbo-core/tests/test_sketch.py
+packages/hypergumbo-core/tests/test_sketch_sanity.py
+packages/hypergumbo-core/tests/test_slice.py
+packages/hypergumbo-core/tests/test_slice_tier_filter.py
+packages/hypergumbo-core/tests/test_solidity_abi_linker.py
+packages/hypergumbo-core/tests/test_stable_shape_ids.py
+packages/hypergumbo-core/tests/test_subprocess_linker.py
+packages/hypergumbo-core/tests/test_supply_chain.py
+packages/hypergumbo-core/tests/test_swift_objc_linker.py
+packages/hypergumbo-core/tests/test_symbol_resolution.py
+packages/hypergumbo-core/tests/test_tauri_ipc_linker.py
+packages/hypergumbo-core/tests/test_tree_sitter_analyzer.py
+packages/hypergumbo-core/tests/test_type_hierarchy_linker.py
+packages/hypergumbo-core/tests/test_view_template_linker.py
+packages/hypergumbo-core/tests/test_vue_component_linker.py
+packages/hypergumbo-core/tests/test_vue_template_method_linker.py
+packages/hypergumbo-core/tests/test_wasm_bindgen_linker.py
+packages/hypergumbo-core/tests/test_websocket.py
+packages/hypergumbo-core/tests/test_yjs_crdt_linker.py
+packages/hypergumbo-lang-common/tests/BRANCHES_test_dart.py
+packages/hypergumbo-lang-common/tests/BRANCHES_test_elixir.py
+packages/hypergumbo-lang-common/tests/test_handlebars.py
+packages/hypergumbo-lang-common/tests/test_just.py
+packages/hypergumbo-lang-common/tests/test_qml.py
+packages/hypergumbo-lang-extended1/tests/test_agda.py
+packages/hypergumbo-lang-extended1/tests/test_blade.py
+packages/hypergumbo-lang-extended1/tests/test_circom.py
+packages/hypergumbo-lang-extended1/tests/test_gnuplot.py
+packages/hypergumbo-lang-extended1/tests/test_mermaid.py
+packages/hypergumbo-lang-extended1/tests/test_solidity.py
+packages/hypergumbo-lang-extended1/tests/test_zig.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_cpp.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_c.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_csharp.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_go.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_html.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_java.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_js_ts.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_kotlin.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_php.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_python_ast_analysis.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_ruby.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_rust.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_scala.py
+packages/hypergumbo-lang-mainstream/tests/BRANCHES_test_swift.py
+packages/hypergumbo-lang-mainstream/tests/test_c.py
+packages/hypergumbo-lang-mainstream/tests/test_csharp.py
+packages/hypergumbo-lang-mainstream/tests/test_decorator_edges.py
+packages/hypergumbo-lang-mainstream/tests/test_go.py
+packages/hypergumbo-lang-mainstream/tests/test_groovy.py
+packages/hypergumbo-lang-mainstream/tests/test_html_analysis.py
+packages/hypergumbo-lang-mainstream/tests/test_java.py
+packages/hypergumbo-lang-mainstream/tests/test_js_ts.py
+packages/hypergumbo-lang-mainstream/tests/test_jupyter.py
+packages/hypergumbo-lang-mainstream/tests/test_kotlin.py
+packages/hypergumbo-lang-mainstream/tests/test_manifest_targets.py
+packages/hypergumbo-lang-mainstream/tests/test_markdown.py
+packages/hypergumbo-lang-mainstream/tests/test_php.py
+packages/hypergumbo-lang-mainstream/tests/test_play_routes.py
+packages/hypergumbo-lang-mainstream/tests/test_polyglot_call_site_coverage.py
+packages/hypergumbo-lang-mainstream/tests/test_py_deps.py
+packages/hypergumbo-lang-mainstream/tests/test_python_ast_analysis.py
+packages/hypergumbo-lang-mainstream/tests/test_rust_attribute_edges.py
+packages/hypergumbo-lang-mainstream/tests/test_rust.py
+packages/hypergumbo-lang-mainstream/tests/test_scala.py
+packages/hypergumbo-lang-mainstream/tests/test_starlette_routes.py
+packages/hypergumbo-lang-rust-analyzer/tests/test_analyzer.py
+packages/hypergumbo-lang-rust-analyzer/tests/test_graceful_degrade.py
+packages/hypergumbo-lang-rust-analyzer/tests/test_translate.py

packages/hypergumbo-core/src/hypergumbo_core/datamodels.py

@@ -48,7 +48,24 @@
 
 
 class DataModelKind(Enum):
-    """Types of data models that can be detected."""
+    """Types of data models that can be detected.
+
+    This enum currently mixes three axes:
+      (1) language construct: ``DATACLASS`` (Python ``@dataclass`` decorator).
+      (2) library/framework: ``ORM_MODEL`` (Django/SQLAlchemy/TypeORM/GORM),
+          ``PYDANTIC_MODEL``, ``SCHEMA`` (Marshmallow / GraphQL types).
+      (3) architectural role: ``DTO``, ``DOMAIN_MODEL``, ``ENTITY`` (DDD-style).
+
+    A class may legitimately satisfy values across multiple axes (e.g., a
+    ``@dataclass`` that is also a Pydantic-style validator and is also a DTO).
+    The current detection table at ``MODEL_BASE_CLASSES`` picks one verdict per
+    class via regex priority order, losing the cross-axis information.
+
+    Re-evaluation triggers (any one is sufficient): (a) a consumer needs to
+    filter by axis independently; (b) the detection table grows past ~12
+    values; (c) a class is observed where the picked value visibly hides a
+    cross-axis signal a consumer needs. See the WI-juvag-numud audit thread.
+    """
 
     ORM_MODEL = "orm_model"  # Django Model, SQLAlchemy, TypeORM, etc.
     PYDANTIC_MODEL = "pydantic_model"  # Pydantic BaseModel

packages/hypergumbo-core/src/hypergumbo_core/ir.py

@@ -203,7 +203,15 @@ class Symbol:
         language: Programming language (python, javascript, etc.)
         path: File path where the symbol is defined
         span: Source location with lines and columns
-        origin: Which analysis pass created this symbol
+        origin: Provenance string. For analyzer-emitted symbols, this SHOULD be
+            a versioned analyzer ID such as ``python-v1``, ``go-v1``, etc. (see
+            the analyzer registry for the canonical list). A small set of
+            synthesis-origin values (``inheritance``,
+            ``orchestrator_file_symbol_synthesis``, ``scip``) currently coexist
+            in this field as a documented exception pending a future split into
+            a sibling ``synthesis_mechanism`` field — see the WI-nusum-nukol
+            audit verdict. Do not extend the synthesis-shaped value set without
+            updating the audit thread.
         origin_run_id: Unique execution ID of the analysis run
         origin_run_signature: Run signature for grouping by analyzer config
         stable_id: Semantic identity hash (survives renames/moves)
@@ -546,7 +554,16 @@ class UsageContext:
 
     Attributes:
         id: Unique identifier for this usage context
-        kind: Type of usage context (call, data_value, export, macro)
+        kind: How the surrounding source code references this symbol — either
+            as a syntactic construct (``call``, ``macro``) or as a semantic
+            role (``data_value``, ``export``). The field currently mixes two
+            axes; the union is small enough (4 values) to be tractable, but a
+            fifth value that doesn't fit either axis should trigger a split
+            into separate fields (e.g., ``usage_construct`` + ``usage_role``).
+            Re-evaluation triggers: (a) a fifth value that fits neither
+            construct nor role; (b) a consumer needing per-axis filtering;
+            (c) a bug where the single picked value hides a cross-axis signal
+            a consumer needs. See the WI-gatuh-ruvar audit thread.
         context_name: Name of the function called, var defined, file exported from, etc.
         symbol_ref: ID of the symbol being used (None if inline/anonymous handler)
         position: Where in the context the symbol appears (e.g., "args[1]", ":get", "default")