Write-path transaction-layering seam (graphdb_mgr:transaction/1)

[david-w-t]

Write-path transaction-layering seam

First piece of the write-path completion track. Adds the shared Mnesia
transaction boundary that the upcoming node/relationship mutation work
(delete_node, remove_relationship, a future batch mutate/1) all build
on, so those operations compose into one atomic transaction without nesting.

What's here

• graphdb_mgr:transaction/1 — a plain exported helper that runs a fun
  inside one mnesia:transaction/1 and normalises the result:
  {atomic, R} → {ok, R}, {aborted, Reason} → {error, Reason}. It is a
  plain function (not a gen_server:call) because mnesia:transaction/1
  runs in the calling process — routing writes through the server would
  needlessly serialise them and risk deadlock.
• The three-tier convention it anchors: tier-1 in-transaction primitives
  (signal failure via mnesia:abort/1, never open a transaction → compose);
  tier-2 single-op public wrappers (own one transaction); tier-3
  batch/composite (wrap one transaction, call tier-1 primitives directly →
  no nesting).
• 4 CT cases proving the contract: commit + result passthrough, abort
  rollback, composition rollback (the property tier-3 relies on), and
  uncaught-crash passthrough.

This slice is the minimal seam only — no consumers, no retrofit of the
existing inline {atomic}/{aborted} mapping sites, no batch mutate/1.
Those are tracked follow-ups in TASKS.md. No existing behaviour changes.

Why now

graphdb_mgr already carries the tier-1 pattern in embryo
(expected_parents/1, expected_classes/1, verify_one/1,
rebuild_one/1 are documented "must run inside an active mnesia
transaction") and hand-rolls the {atomic}/{aborted} mapping inline in
do_get_relationships/2, verify_caches/0, and rebuild_caches/0. This
names the convention and factors that mapping into one helper.

Docs

• Design: docs/designs/write-path-transaction-seam-design.md
• Plan: docs/superpowers/plans/2026-06-17-write-path-transaction-seam.md
• TASKS.md write-path section restructured into slices A–E.

Testing

graphdb_mgr_SUITE: 32/32 green (28 pre-existing + 4 new). Full tree
compiles clean, zero warnings. Suite totals: 419 CT + 105 EUnit = 524.

🤖 Generated with Claude Code

[david-w-t]

ok