feat: dependency-aware write sets for mixed-type entity graphs

[zantvoort]

Problem

Inserting an object graph that spans several tables requires hand-rolled choreography: insert parents, correlate generated keys back by position, rebuild children against those keys, repeat per level. The same ordering problem exists in reverse for deletes. Storm's fail-fast validation correctly rejects unsaved references, but the only remedy it could suggest was manual ordering.

Design

A write set applies one write operation to a heterogeneous collection of entities, obtained via orm.writeSet() (also available on repositories, delegating to the template):

orm.writeSet().insert(entities);   // mixed entity types
orm.writeSet().update(entities);
orm.writeSet().upsert(entities);
orm.writeSet().remove(entities);
// plus insertAndFetch / updateAndFetch / upsertAndFetch, and typed single-root variants

Contract:

1. Insert and upsert write the explicit members plus their insertion closure: unsaved entities transitively reachable through insertable, entity-valued foreign key fields (including fields inside inline components and entity-wrapped refs). Referenced entities that already carry a key are never discovered; they only bind as foreign key values.
2. Update and remove write exactly the explicit members. Referenced entities are never written implicitly.
3. Execution order follows the foreign key dependencies: parents first for insert/upsert (covering both unsaved dependencies and keyed member-to-member references), children first for remove (correlated by type and primary key).
4. Generated keys propagate by instance identity via record reconstruction; the same unsaved instance describes one row, equal-but-distinct instances describe two.
5. One batch operation per entity type per dependency level; generated keys are only fetched when a dependent or the caller consumes them, which keeps leaf writes compatible with dialects that cannot return keys for every generation strategy (e.g. H2 with sequences).

Unsaved is the deterministic local test Storm already uses: default primary key with an auto-generation strategy. No session, no cache involvement, no annotation-driven cascade; per-row semantics (callbacks, dirty checking, native upsert, joined inheritance) are exactly those of the per-repository operations, which the executor delegates to.

Fail-fast before any statement executes: unorderable dependency cycles, id-only refs with default ids, unsaved members in update/remove, and unsaved entities behind non-insertable foreign key components.

Implementation notes

• Shared st.orm.WriteSet interface in storm-foundation; executor WriteSetImpl in storm-core; writeSet() on RepositoryLookup/Repository in core, mirrored in storm-java21 and storm-kotlin.
• Ref.of(entity) no longer requires a persisted id, so entity-wrapped refs can carry unsaved instances as graph edges. Key propagation rebuilds ref components by wrapping the persisted instance, preserving concrete subtypes.
• The unsaved-foreign-key error message now points to writeSet().
• Kotlin adds a scoped writeSet { } block (eager; groups calls, never defers or reorders).

Docs and AI assets

• New docs/write-sets.md (sidebar: Operations), README docs table row, comparison table updates (Cascade persist cell + Graph persistence aspect row), llms-full.txt regenerated (page added to the generation script's list), and Write Sets sections in the storm-repository-{java,kotlin} skills served at orm.st/skills.

Tests

24 tests across four suites: WriteSetIntegrationTest (storm-core, 18: closure, shared parents, inline-component and wrapped-ref edges, keyed-member ordering, input-order fetch, equal-but-distinct instances, update/remove isolation, repository access incl. proxy dispatch, single-root variants, fail-fast paths), WriteSetLevelingTest (cycle detection), WriteSetTest.kt (storm-kotlin, data classes, block DSL), H2WriteSetTest (storm-h2, real MERGE upserts, sequence keys, upsert ordering precedence). Full reactor green.

Known limitations

• Remove ordering correlates members by the declared foreign key component type; polymorphic members whose concrete class differs from the declared sealed type do not receive ordering edges.
• Whether upsert can create a row for a member carrying a preset key follows the dialect's per-repository upsert behavior (core default routes keyed members to the update branch; dialect MERGE implementations may create the row). Documented, not unified here.
• Entity callbacks run inside the per-type operations, after discovery and planning; callbacks that alter foreign key fields do not re-plan the graph (documented as a non-goal).

Fixes #269