mastermind-runtime-research

name	mastermind-runtime-research
description	Gather who already depends on a service, handler, or state owner before changing it, and name the runtime gaps the codegraph cannot span. Use before designing a change to an API, queue consumer, background job, migration, or shared state; it feeds the architecture review rather than replacing it.
metadata	{"version":"0.1.0","authors":["mastermind"],"tags":["workflow","backend","runtime","mmcg"]}

Mastermind runtime research

[[mastermind-architecture-review]] reconstructs the runtime path and judges the design. This runs first and does something narrower: find who already depends on what you are about to change, and state where the graph stops being able to tell you. Feed both into the review.

Zero callers is not zero callers

Start here, because every other answer inherits it. The graph is syntactic, so whole classes of real invocation produce no edge at all:

• A queue, topic, or bus. A producer and its consumer are two separate static islands. There is no edge between them and there never will be.
• Framework registration. A route table, a DI container, a decorator-based dispatcher, or a config-declared handler calls code the graph never links.
• Reflection, dynamic dispatch, and interface indirection. The call lands on a name the source never spells.
• Cross-process and cross-language. A worker invoked by a scheduler, or a service reached over HTTP, is outside the index entirely.

So mmcg_callers returning nothing on a handler means no static caller was found, not nothing calls this. Report it that way, and go find the registration, the topic name, or the schedule by reading. A change that looks unreferenced is the single most expensive thing to get wrong here.

Who depends on this today

mmcg_api_surface src/orders/      # symbols under a prefix used from OUTSIDE it
mmcg_callers <symbol>             # static callers, with the caveat above
mmcg_impact <symbol> --depth 3    # transitive blast radius
mmcg_imported_by <symbol>         # importing files, including barrels

mmcg_api_surface is the one most often skipped and the one that matters most: it reports what the rest of the codebase actually reaches into, independent of what is declared public. A module can export twenty symbols and have three real consumers, or export none and still be reached through a re-export. Change the three, not the twenty.

Who owns the state

Before changing a write path, find every writer — source-of-truth problems start with more than one. mmcg_callers on the mutating function and mmcg_imported_by on the store or model give the static set; the gaps above give you the list of places to read for the rest.

Say plainly whether the change adds a second writer to state that already has one, and whether the new write is authoritative or derived. That single sentence is what the architecture review's source-of-truth check needs as input.

What the change crosses

mmcg_map <dir>                    # components, entry points, boundaries
mmcg_change_impact --since <ref>  # api_crossings, affected_components
mmcg_dependency_cycles            # does this add a cycle

A crossing is where guarantees change: in-process calls become at-least-once delivery, ordering stops being free, and a partial failure becomes visible. List the crossings the change touches so the review can reason about each one instead of rediscovering them.

Output

A short evidence packet, not a verdict:

• consumers found, by query, with the query named;
• state writers found, and whether the change adds one;
• boundaries crossed;
• runtime gaps — every place the graph could not answer, and what you read or still need to read instead.

The gap list is the most valuable line in the packet. An architecture review built on "the graph showed no other callers" without that list is confident about a question nobody asked.

What this does not do

It does not judge the design, reconstruct the ordered runtime path, or produce a verdict — that is [[mastermind-architecture-review]]. It does not establish runtime behaviour: everything here is static evidence plus a list of what static evidence cannot see. Tests, traces, and logs remain the only proof of what actually runs.