feat(entrypoints): serializer concept → SERIALIZER entrypoint (WI-gudob Phase 5)

Frameworks instantiate serializer / DTO classes from model data or
request payloads and reflectively call serialize-like methods
(to_representation, dump, to_internal_value, toArray, exposure). The
class body therefore looks dead to the static call graph even when
wired into a reachable route. Classifying any symbol tagged
concept: serializer as a SERIALIZER entrypoint with confidence 0.90
restores its reachability at class level.

This mirrors Phase 4 (form). Serializer producers are uniformly
class-level base_class matches across 9 frameworks (django REST
Serializer / ModelSerializer / HyperlinkedModelSerializer, flask
Marshmallow Schema / SQLAlchemySchema / SQLAlchemyAutoSchema, grape
Grape::Entity, laravel JsonResource / ResourceCollection, litestar
AbstractDTO / DTOData, plus plumber / pyramid / quart / rails), so
the scope is clean — no heterogeneous decorator / call-level noise
of the kind that caused validator / auth to be deferred at Phase 4.

Per-method dispatch (to_representation → field-specific methods) is
deferred to a per-framework dispatch-registry follow-up because each
framework names its reflective methods differently.

docs/CONCEPTS.md regenerated via scripts/generate-concepts:
serializer flipped inert → live (9 producers).

3 new tests in tests/test_entrypoints.py mirror the Phase 4 form
tests: framework-labelled serializer, framework-less serializer
("Serializer" label), and multi-framework dedup (one entrypoint per
symbol even when two framework patterns tag it).

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

Author: jgstern-agent

.ci/affected-tests.txt

@@ -1,13 +1,14 @@
 # Test selection manifest
-# Generated by smart-test at 2026-04-20T10:46:40-04:00
+# Generated by smart-test at 2026-04-20T11:27:57-04:00
 # Mode: targeted
 # Baseline: e82d3803685a1f005db6b87ba33d3b16e11b9178
-# Changed files: 46
-# Changed source files: 7
-# Selected tests: 75
+# Changed files: 51
+# Changed source files: 8
+# Selected tests: 76
 #
 # === CHANGED_SOURCE_FILES ===
 packages/hypergumbo-core/src/hypergumbo_core/cli.py
+packages/hypergumbo-core/src/hypergumbo_core/entrypoints.py
 packages/hypergumbo-core/src/hypergumbo_core/linkers/kafka_streams_dispatch.py
 packages/hypergumbo-tracker/src/hypergumbo_tracker/hotspot_markup.py
 packages/hypergumbo-tracker/src/hypergumbo_tracker/id_matching.py
@@ -32,6 +33,7 @@ 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_crypto_flow_linker.py
+packages/hypergumbo-core/tests/test_entrypoints.py
 packages/hypergumbo-core/tests/test_file_excludes.py
 packages/hypergumbo-core/tests/test_frameworks_flag.py
 packages/hypergumbo-core/tests/test_gitleaks.py

CHANGELOG.md

@@ -12,6 +12,8 @@ This changelog tracks the **tool version** (package releases). The **schema vers
 
 ### Added
 
+- **`serializer` concept → SERIALIZER entrypoint (WI-gudob Phase 5):** mirrors Phase 4 (form) — any symbol tagged `concept: serializer` is classified as a `SERIALIZER` entrypoint with confidence 0.90 and a framework-derived label (``"Django serializer"``, ``"Flask serializer"``, or plain ``"Serializer"`` when no framework attribution is present). Producers are uniformly class-level ``base_class`` matches across 9 frameworks (django DRF `Serializer` / `ModelSerializer` / `HyperlinkedModelSerializer`, flask Marshmallow `Schema` / `SQLAlchemySchema` / `SQLAlchemyAutoSchema`, grape `Grape::Entity`, laravel `JsonResource` / `ResourceCollection`, litestar `AbstractDTO` / `DTOData`, plus plumber/pyramid/quart/rails), so the scope is clean — no heterogeneous decorator/call-level noise of the kind that caused validator/auth to be deferred at Phase 4. Restores class-level reachability for serializer/DTO classes that previously looked dead to the static call graph because the framework instantiates them and reflectively calls `to_representation` / `dump` / `to_internal_value` / `toArray` / `exposure`. Per-method dispatch (`to_representation` → field-specific methods) is deferred to a per-framework dispatch-registry follow-up because each framework names its reflective methods differently. `docs/CONCEPTS.md` regenerated via `scripts/generate-concepts`: `serializer` flipped inert → live (9 producers). 3 new tests (framework label, no-framework fallback, multi-framework dedup) in `tests/test_entrypoints.py`.
+
 - **Kafka Streams topology-callback dispatch linker (WI-lisov):** new Framework-subcategory linker `packages/hypergumbo-core/src/hypergumbo_core/linkers/kafka_streams_dispatch.py` that recovers reflective-dispatch edges the Kafka Streams runtime uses to invoke topology callbacks on a per-record basis. For every Java / Kotlin / Scala class whose declared `base_classes` or `interfaces` short-match one of 17 Kafka Streams callback types (`ValueMapper`, `ValueMapperWithKey`, `KeyValueMapper`, `Predicate`, `ForeachAction`, `Aggregator`, `Reducer`, `Initializer`, `Merger`, `ValueTransformer`, `ValueTransformerWithKey`, `Transformer`, `Processor`, and their four `*Supplier` factory forms), the linker emits `dispatches_to` edges from the class to the interface-specific framework-called methods (`apply`, `transform`, `process`, `get`, `init`, `close`, `test`) with confidence 0.90 and evidence `kafka_streams_dispatch`. Fully-qualified names like `org.apache.kafka.streams.kstream.ValueMapper<K, V, VR>` normalize to the short form before matching, so the Scala wrapper namespace (`org.apache.kafka.streams.scala.kstream.*`) is covered by the same interface table. Lifecycle methods for stateful transformers (`init` / `close`) are emitted alongside the per-record method so slices through a `Transformer` reach the setup and teardown as well. Registered at linker priority 21 (same tier as `jackson-dispatch`) and wired into `cli.py` alongside the other Framework-dispatch linkers. 37 tests in `tests/test_kafka_streams_dispatch_linker.py` cover `_short_type_name` (bare / qualified / generic-parameter / qualified-with-generics), `_callback_interfaces_on` (non-dict meta, base_classes match, interfaces match, qualified-name normalization, unknown-interface reject, dedup across both keys, non-list entry skip, non-string entry skip, missing keys, multi-interface ordered), `_expected_method_names` (single, Transformer lifecycle, multi-interface union, empty-list), `_build_class_method_index` (class grouping, non-method skip, non-JVM-language skip, top-level-function skip), and the integration pass (ValueMapper → apply, Transformer → init/transform/close, qualified-name match, non-callback ignored, non-JVM class ignored, no-classes early return, Kotlin support, Scala support, interface-kind target, existing-edge dedup, ProcessorSupplier → get, multi-interface union, class-without-span emits `line=0`). Scope is intentionally limited to class→method edges (sufficient to lift the 2386 `kafka_streams_internal` dead-code candidates per WI-tubot aggregate-v5); call-site → impl edges are left as a Phase 2 follow-up in WI-lisov.
 
 - **Auto-strip / regression-spawn for `awaits_bakeoff_validation` verdicts (WI-dolil slice 2b):** `scripts/bakeoff-deep-reflect aggregate` gains a `--apply-verdicts` flag that executes the tracker mutations implied by the slice-2 per-claim verdict distribution. On `plurality=moved` the `awaits_bakeoff_validation` tag is stripped from the item and a discuss note records the cohort + per-repo evidence; on `plurality=no_move` a regression sub-item is spawned under the original (kind `work_item`, tags `regression` + `awaits_bakeoff_validation`, priority 1, status `todo_soft`) and a discuss note is posted on the parent; on `plurality=tied` or `inconclusive` the cohort did not settle the claim and no mutation is performed. Default behaviour is dry-run: the plan is printed (one line per step) with `(dry-run; re-run with --apply-verdicts to execute)` so humans can preview before the mutations happen. New pure helpers `build_validation_mutation_plan(summary, cohort_label)` and `apply_mutation_plan(plan, runner=...)` are exercised via an injected runner in tests so no real tracker calls occur. Multi-cohort aggregate (`--all` / `--some`) invokes the surface helper per cohort so a batch re-aggregate can settle every open claim at once. 19 new tests in `tests/test_bakeoff_deep_reflect.py` cover the plan-builder (empty summary, moved → remove_tag+discuss, no_move → spawn_regression+discuss, tied/inconclusive → note-only, missing item_id/plurality skipped, evidence truncation at 120 chars, empty-evidence fallback, `+N more` roll-up when evidence exceeds max_items), the CLI-runner (remove_tag / discuss / spawn_regression argv shapes, note + unknown-action skip, non-zero exit marks failed, `OSError` runner exception marks failed with message captured), and the print/apply surface (no-plan returns None, dry-run prints plan without applying, apply returns stats dict and prints summary line, apply prints per-step failure lines, dry-run prints every action shape). Slice 2b closes the tooling half of WI-dolil; only slice 4 (acceptance demo — a real DEEP cycle exercising the end-to-end tag → validate → strip/regress round-trip) remains.

docs/CONCEPTS.md

@@ -8,7 +8,7 @@ This file enumerates every concept string that the framework-YAML pattern layer
 - **inert** — producers exist but no consumer reads the concept. Candidates for either removing the producer pattern or writing a Framework-subcategory linker that consumes it.
 - **ghost** — a consumer mentions the concept by name but no YAML emits it. Likely dead code or a leftover reference to a removed pattern; investigate.
 
-Total concepts: **317** (live: 40, inert: 277, ghost: 0).
+Total concepts: **317** (live: 41, inert: 276, ghost: 0).
 
 ## Inventory
 
@@ -251,7 +251,7 @@ Total concepts: **317** (live: 40, inert: 277, ghost: 0).
 | `security` | inert | fastapi, flask-appbuilder | _(none)_ |
 | `seeder` | inert | adonisjs, cakephp, codeigniter, laravel, symfony | _(none)_ |
 | `serialization_callback` | live | go-encoding-callbacks | `entrypoints.py` |
-| `serializer` | inert | django, flask, grape, laravel, litestar, plumber, pyramid, quart, rails | _(none)_ |
+| `serializer` | live | django, flask, grape, laravel, litestar, plumber, pyramid, quart, rails | `entrypoints.py` |
 | `serializer_field` | inert | flask-restful | _(none)_ |
 | `server` | inert | cowboy, http4k, http4s, pedestal, plumber, restify, servant, shiny, vertx | _(none)_ |
 | `service` | inert | codeigniter, feathers, guice, hanami, jakarta-cdi, micronaut, nestjs, spring-boot | _(none)_ |

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

@@ -194,6 +194,7 @@ class EntrypointKind(Enum):
     EVENT_HANDLER = "event_handler"  # Event/message handler
     ERROR_HANDLER = "error_handler"  # HTTP / middleware exception handler
     FORM = "form"  # Framework-reflected form class (is_valid/save/authorize)
+    SERIALIZER = "serializer"  # Framework-reflected serializer/DTO class (to_representation / dump / toArray)
     SCHEDULED_TASK = "scheduled_task"  # Cron/scheduled job
     # Library entry points (exported API)
     LIBRARY_EXPORT = "library_export"  # Exported function/class (library entry)
@@ -306,6 +307,7 @@ def _detect_from_concepts(symbols: List[Symbol]) -> List[Entrypoint]:
     - "event_handler" -> EVENT_HANDLER (event/message handler)
     - "error_handler" -> ERROR_HANDLER (HTTP / middleware exception handler)
     - "form" -> FORM (framework-reflected form class)
+    - "serializer" -> SERIALIZER (framework-reflected serializer/DTO class)
     - "command" -> CLI_COMMAND (CLI command handler)
     - "liveview" -> CONTROLLER (Phoenix LiveView - real-time UI)
     - "graphql_resolver" -> GRAPHQL_SERVER (GraphQL resolver)
@@ -537,6 +539,41 @@ def _detect_from_concepts(symbols: List[Symbol]) -> List[Entrypoint]:
                 ))
                 added_kinds.add(EntrypointKind.FORM)
 
+            # Serializer concept -> SERIALIZER (WI-gudob Phase 5):
+            # Framework-reflected serializer / DTO classes (Django REST
+            # Framework Serializer / ModelSerializer, Marshmallow Schema and
+            # SQLAlchemySchema, Grape Entity, Laravel JsonResource /
+            # ResourceCollection, Litestar AbstractDTO / DTOData, ...).
+            # The framework instantiates the class from a model / payload
+            # and reflectively calls a serialize-like method
+            # (``to_representation``, ``dump``, ``to_internal_value``,
+            # ``toArray``, ``exposure``) — the class body therefore looks
+            # dead to the static call graph even when wired into a
+            # reachable route. Classifying the serializer class itself as
+            # an entrypoint restores its reachability at class level;
+            # per-method dispatch (``to_representation`` → field methods)
+            # is deferred to a per-framework dispatch-registry follow-up
+            # because each framework names its reflective methods
+            # differently. 9 framework YAML patterns emit this concept
+            # (django, flask, flask-restful, grape, laravel, litestar,
+            # hanami, django-ninja, pyramid per the WI-dajul concept
+            # registry audit) and the producers are uniformly class-level
+            # ``base_class`` matches, so the scope is clean.
+            elif concept_type == "serializer":
+                if EntrypointKind.SERIALIZER in added_kinds:
+                    continue
+                if framework:
+                    label = f"{framework.title()} serializer"
+                else:
+                    label = "Serializer"
+                entrypoints.append(Entrypoint(
+                    symbol_id=sym.id,
+                    kind=EntrypointKind.SERIALIZER,
+                    confidence=0.90,
+                    label=label,
+                ))
+                added_kinds.add(EntrypointKind.SERIALIZER)
+
             # Command concept -> CLI_COMMAND
             elif concept_type == "command":
                 if EntrypointKind.CLI_COMMAND in added_kinds:

packages/hypergumbo-core/tests/test_entrypoints.py

@@ -718,6 +718,56 @@ def test_form_dedupe_per_symbol(self) -> None:
         form_eps = [e for e in entrypoints if e.kind == EntrypointKind.FORM]
         assert len(form_eps) == 1
 
+    def test_detect_serializer_concept(self) -> None:
+        """Symbol with serializer concept is detected as SERIALIZER entrypoint (WI-gudob Phase 5)."""
+        sym = make_symbol(
+            "UserSerializer",
+            path="myapp/serializers.py",
+            kind="class",
+            meta={
+                "concepts": [
+                    {"concept": "serializer", "framework": "django"}
+                ]
+            },
+        )
+        entrypoints = detect_entrypoints([sym], [])
+        ser_eps = [e for e in entrypoints if e.kind == EntrypointKind.SERIALIZER]
+        assert len(ser_eps) == 1
+        assert ser_eps[0].symbol_id == sym.id
+        assert ser_eps[0].confidence >= 0.85
+        assert "Django" in ser_eps[0].label or "serializer" in ser_eps[0].label.lower()
+
+    def test_detect_serializer_concept_without_framework(self) -> None:
+        """serializer concept without a framework label still produces an entrypoint."""
+        sym = make_symbol(
+            "BareDTO",
+            path="src/dtos.py",
+            kind="class",
+            meta={"concepts": [{"concept": "serializer"}]},
+        )
+        entrypoints = detect_entrypoints([sym], [])
+        ser_eps = [e for e in entrypoints if e.kind == EntrypointKind.SERIALIZER]
+        assert len(ser_eps) == 1
+        assert ser_eps[0].label == "Serializer"
+
+    def test_serializer_dedupe_per_symbol(self) -> None:
+        """A symbol tagged serializer twice (matched by two framework patterns)
+        emits at most one SERIALIZER entrypoint."""
+        sym = make_symbol(
+            "PolySchema",
+            path="src/schemas.py",
+            kind="class",
+            meta={
+                "concepts": [
+                    {"concept": "serializer", "framework": "flask"},
+                    {"concept": "serializer", "framework": "grape"},
+                ],
+            },
+        )
+        entrypoints = detect_entrypoints([sym], [])
+        ser_eps = [e for e in entrypoints if e.kind == EntrypointKind.SERIALIZER]
+        assert len(ser_eps) == 1
+
     def test_detect_command_concept(self) -> None:
         """Symbol with command concept is detected as CLI command entrypoint."""
         sym = make_symbol(