storm analyze: one command for entity graph cost and the design budget

[zantvoort]

Two separate pieces of planned work describe the same command.

Part 2 of #325 proposes storm analyze: read the compile-time metamodel index and report, per entity, the eager select join count and a ranked list of Ref candidates by how many joins each cut would save.

docs/entity-design.md describes the entity design budget, a per-table invariant that the inline closure adds at most 10 joins and at most 96 columns beyond the table's own. Generation applies it; enforcement against an existing model was deferred. When it lands it reads the same index and answers the same question, in the same register.

Ship one command, not two verbs that disagree at the margins.

What it reports

Per entity, from the metamodel index:

• the eager select join count, and the inline closure column count
• whether either budget is exceeded, and by how much
• Ref candidates ranked by what each cut removes, in joins and in columns

The win for a field is the size of the subtree that cutting its edge makes unreachable. A table reached by several paths is joined once per path, so cutting a shared hub is worth more than its own size suggests, and the ranking should show that rather than leave it to be inferred.

Reported, never flipped

The command does not rewrite code. An entity over budget produces a diagnostic naming the table and the overrun, and the code is left as written, matching what generation already does when it runs against entities that exist. An entity that diverges is assumed to be doing so deliberately.

Advisory framing throughout: this reports the shape of a graph, it does not prescribe a model.

Opt-in, and gateable

Run on demand, never at boot. A non-zero exit when something is over budget lets a project put it in CI if it wants to; nothing about it fires unless someone asks.

Placement

The npm CLI runs on Node and does init, demo, update, db and mcp. This analysis needs the JVM-side metamodel index, so the analysis itself belongs with the codegen module from #211, with the CLI fronting it and a Maven goal and Gradle task for projects that would rather not add a Node dependency. Sequence it after that module exists.

Relationship to #325

This supersedes part 2 of #325. Part 1 of that issue, the query-time fail-fast when a select would exceed the database's hard join limit, stays there: it is framework work, it runs at query build time rather than on demand, and it is independent of this command.

Tasks

• Static join-graph analysis over the metamodel index: per-entity join count, closure column count, ranked Ref candidates by win
• Budget evaluation (10 joins, 96 columns) reported against existing entities, never applied
• Maven goal and Gradle task, plus the storm CLI front end
• Non-zero exit on overrun, off unless asked for
• Docs: reading the report, in entity-design.md

[zantvoort]

The SQL log's hydration shape (storm.sql-log.hydration, j2 c12 d3 / joins=2 columns=12 graph=Pet(Owner(City)) on summary rows) is removed in #517's branch: it printed a static per-type fact on per-execution lines, behind an option nobody would find. The fact itself belongs here, per type, once. Two things carry over.

The shape derivation

SqlLogRenderer (as of 176a960a, storm-core) derived a type's declared hydration shape at runtime through ORMReflection, cached per type in a ClassValue. The rules it applied are the ones this command should reproduce over the metamodel index:

• an entity component is a join edge and recurses;
• an inline record is columns on the same table and no subgraph, so an entity it carries splices into the parent's children and does not count as a level;
• a Ref is its foreign key column and stops, which is exactly the width a Ref declaration saves;
• a cycle recurses no further, the revisited entity contributing its foreign key column;
• depth counts entity levels along the deepest chain (1 for a flat entity, 3 for Pet(Owner(City)));
• the graph renders as the joined-entity tree, Pet(PetType, Owner(City)).

The runtime version:

private record Shape(int joins, int columns, int depth, String children) {}

private static Shape shape(Class<?> type, Set<Class<?>> path) {
    if (!path.add(type)) {
        return new Shape(0, 1, 0, "");            // cycle: the revisited entity contributes its FK column
    }
    try {
        var reflection = Providers.getORMReflection();
        var recordType = reflection.findRecordType(type).orElse(null);
        if (recordType == null) {
            return new Shape(0, 1, 0, "");
        }
        int joins = 0, columns = 0, depth = 0;
        var children = new StringBuilder();
        for (var field : recordType.fields()) {
            Class<?> fieldType = field.type();
            if (Ref.class.isAssignableFrom(fieldType)) {
                columns++;                        // the FK column; a reference does not widen the read
            } else if (Entity.class.isAssignableFrom(fieldType)) {
                var child = shape(fieldType, path);
                joins += 1 + child.joins();
                columns += child.columns();
                depth = Math.max(depth, 1 + child.depth());
                append(children, fieldType.getSimpleName() + (child.children().isEmpty() ? "" : "(" + child.children() + ")"));
            } else if (reflection.findRecordType(fieldType).isPresent()) {
                var inline = shape(fieldType, path);   // inline record: same table, no level of its own
                joins += inline.joins();
                columns += inline.columns();
                depth = Math.max(depth, inline.depth());
                if (!inline.children().isEmpty()) append(children, inline.children());
            } else {
                columns++;
            }
        }
        return new Shape(joins, columns, depth, children.toString());
    } finally {
        path.remove(type);
    }
}

A per-line signal, later

Once this command owns the per-type report, the SQL log could carry the shape again in the one place it earns a line: as a signal, not a setting. A summary row or slow line for a read whose type is at or beyond the design budget (10 joins / 96 columns, entity-design.md) would say hydrates 8 joins, 96 columns: Pet(Owner(City), PetType, Vet(Clinic)), and a normal read would carry nothing. That ties the log to the budget this command enforces rather than to an option beside it. Not part of the first cut; noted so the removal is not read as the idea being dropped.

[zantvoort]

Elaborating on the shape derivation above: what each rule contributes and why, a worked example, and three points the runtime version left implicit that this command should pin down.

What the numbers mean

An eager read of an entity selects all of its columns and joins the table of every entity-typed component it declares (anything not wrapped in Ref), recursively. The shape summarizes that read: joins beyond the type's own table, columns in the select list, depth in entity levels along the deepest chain (1 flat, 3 for Pet(Owner(City))), and the graph of joined entities.

The rules

Component kind	Contributes	Why
Plain column	1 column	It is on the row.
Entity component (owner: Owner)	1 join plus everything the child joins; the child's entire column count; depth = 1 + child depth; a node in the graph	The join brings the whole child select list along, and the child's own entity components join in turn.
Ref<T> (owner: Ref<Owner>)	1 column, no join, no recursion, no graph node	The FK column is all the read carries; the subgraph is cut here. The difference from the row above is exactly what declaring a Ref saves.
Inline record (address: Address on the same table)	Its columns, no join, no level of its own; an entity inside it splices up as a child of the parent	An inline record is columns on the parent's row, not a table. Owner(Address(City)) renders as Owner(City) at depth 2, because that is what the SQL looks like.
Revisited type (a cycle)	Its FK column, stop	Defensive only: #412 rejects non-Ref FK cycles at compile time, so a valid model never gets here.

Worked example

Type	Declaration	joins	columns	depth	graph
City	id, name	0	2	1	City
Owner	id, first_name, last_name, city: City	1	5	2	Owner(City)
PetType	id, name	0	2	1	PetType
Pet	id, name, type: PetType, owner: Owner	3	9	3	Pet(PetType, Owner(City))
Visit	id, visit_date, description, pet: Ref<Pet>	0	4	1	Visit
Visit with pet: Pet		4	12	4	Visit(Pet(PetType, Owner(City)))

The last two rows are the case for Ref in one line: one declaration turns a 4-join, 12-column read into a 0-join, 4-column one.

Three things to pin down here

1. Which column count the budget uses. The runtime shape counted the type's own columns too; entity-design.md states the budget as at most 10 joins and 96 columns beyond the table's own. Report both; evaluate the budget on the beyond-own figure.
2. Ref candidates and shared hubs. The win of cutting an edge is the size of the subtree reachable only through it. A hub reached through several paths is joined once per path, so cutting it is worth more than its own subtree suggests; rank by reachability, not subtree size. The per-edge subtree sizes fall out of the same walk.
3. Polymorphic components. A component typed as a sealed Data interface with entity subtypes was counted by the runtime walk as one entity join. Depending on how such a component actually hydrates, that may under-count; check against RecordReflection's polymorphic FK handling before the numbers go into a report people act on.

The runtime version walked ORMReflection and cached per type in a ClassValue; this command walks the compile-time metamodel index with the same recursion over declared component kinds (column, entity, ref, inline), no reflection, and no caching concern since it runs once on demand.