SP2: physical project store

[david-w-t]

SP2 — physical project store

Second of the four-sub-project program that separates the shared environment
ontology from per-project instance space (SP1 landed in #52).

Each registered project now gets its own three Mnesia tables —
nodes_<Anchor>, relationships_<Anchor>, counters_<Anchor> — plus its own
nref and rel-id allocators starting at 1. This closes a real nref-collision
defect: before SP2 a project instance and an environment node could occupy the
same integer in the same table.

Design: docs/designs/sp2-physical-project-store-design.md
Plan: docs/superpowers/plans/2026-08-05-sp2-physical-project-store.md

What changed

Module	Change
graphdb_ns	namespace_of/2, target_namespace/2 take a leading Home; new node_table/1 / rel_table/1
graphdb_project	register_project/1 creates the anchor and the three tables; open/1 / require_project/1 replace SP1's open_session/1 / require_session/1; new next_nref/1, next_rel_id_pair/1
graphdb_instance	Fully Project-routed end-to-end — every write primitive and all six instance reads
graphdb_mgr	Project-taking twins: get_node/2, retire_node/2, unretire_node/2, update_node_avps/3, delete_node/2, mutate/2, verify_caches/1, rebuild_caches/1
graphdb_query	Sessions bind a Project; resolve_home/2 resolves bare nrefs

Routing rule: characterization / reciprocal (arc labels), class nodes and
attribute nodes always resolve to the environment; source_nref /
target_nref route through Home :: environment | Project. Instance↔class
membership arcs live in the project's table — including the class→instance row
whose source_nref is an environment class nref.

mutate/1 stays environment-only by design; mutate/2 is the project-aware twin.

Tests

689 passing, 0 failures (544 CT + 145 EUnit), up from 653 pre-SP2.
rebar3 xref added as a CI gate.

Two pre-existing Criticals fixed along the way

Both were invisible to rebar3 compile and to the test suite, because the test
profile defines TEST:

• graphdb_attr:find_attribute_by_name/2 was exported only under
  -ifdef(TEST) but called from production init/1 paths in
  graphdb_language and graphdb_rules. application:start(graphdb) failed
  with undef — rebar3 release produced an unstartable system.
• Same pattern in graphdb_mgr (validate_avp_updates/1,
  apply_avp_updates/2), making every update_relationship* path undef in
  production.

Verified fixed by booting the default (non-TEST) profile directly. The new
xref CI gate is what prevents this class recurring — nothing else catches it.

Review

Every task was reviewed as it landed, then the whole branch was reviewed end to
end, followed by three fix waves and a scoped re-review. Fixes were verified by
reverting each one and confirming the pre-fix failure reproduced, rather than by
inspection.

Notable defects the process caught (each invisible to the compiler, all fixed):
graphdb_mgr calling a function SP1 had deleted; #q_instances_of{} unable to
see project instances at all; project-bound sessions silently dropping
environment labels; malformed handles crashing shared singleton workers;
register_project/1 not actually being idempotent, with a test that asserted a
property the code lacked.

Known deferrals

All recorded in TASKS.md. One is worth flagging here and is covered in a
follow-up comment on this PR: query traversal silently truncates
environment-only paths under a project-bound session.

Draft pending a decision on that item.

[david-w-t]

Deferred defect: query traversal silently truncates environment-only paths

Filed in TASKS.md under Multi-project sessions. Recording the analysis here
because it is the one open item that could reasonably block this PR, and the fix
is a design decision rather than a patch.

Symptom

A #q_find_path{} whose only route runs through a bootstrap nref returns
{ok, no_path} under a session bound to a project with enough instances,
while returning the correct path under an environment session:

A1=1000003  A2=1000004   (runtime-tier environment attributes; neither is shadowed)
Query: #q_find_path{from=A1, to=A2, max_depth=4, arc_kinds=[taxonomy]}

environment session      => {ok, [A1 -via 23-> 6, 6 -via 24-> A2]}
project, 1 instance      => {ok, [A1 -via 23-> 6, 6 -via 24-> A2]}
project, 21 instances    => {ok, no_path}          <-- silently wrong
                            (nref 6 shadowed by the project? true)

No error is raised. The only signal is a collision warning in the log.

Why it happens

resolve_home/2 was designed for entry-point nrefs, where the query
language genuinely has no characterization context to route on. It guesses:
try the bound project's table, fall back to the environment.

But session_read_arcs/4 (graphdb_query.erl:410) and is_scaffold_node/2
(:931) apply that same guess to arc-discovered nrefs — re-deciding Home
for every node the BFS reaches. When an intermediate node's integer happens to
exist in the project, the walk crosses stores mid-traversal and the frontier
truncates.

Both endpoints in the repro are unshadowed, so this is not the documented
"an endpoint resolves to the project by caller intent" behaviour that
resolve_home_prefers_project_and_logs_on_collision covers. That behaviour is
intentional; this is not.

Why it matters more than it looks

Project allocators start at 1. So any project with ≥6 instances shadows nref
6, and ≥35 shadows the entire bootstrap scaffold. This is not an edge case
that needs a contrived setup — it is the steady state of any real project.

What the fix requires

The key asymmetry: arc-discovered nrefs are not ambiguous. Unlike an
entry-point nref, an nref reached by traversing an arc arrives with that arc's
characterization in hand, and the arc label carries a target_kind AVP. So
the guess can be replaced with a deterministic lookup:

1. Route arc-discovered nrefs via graphdb_ns:target_namespace/2 on the arc's
   target_kind, instead of resolve_home/2.
2. Handle the 29/30 class↔instance membership pair as an explicit
   exception — its source and target deliberately live in different Homes
   (the class in the environment, the instance in the project), so the naive
   "reuse the arc's Home" shortcut breaks precisely there. This is the reason
   the fix is not a one-liner and why I did not attempt it inside SP2.
3. Decide what is_scaffold_node/2 should mean under a project-bound session
   — scaffold-ness is an environment property, so it likely should not consult
   the project at all.
4. Keep resolve_home/2's contract unchanged for genuine entry points; other
   callers depend on it, and its collision behaviour there is tested.

Worth adding a regression test that asserts an environment-only path is
returned identically under an environment session and under a project-bound
session with a shadowing instance count — that is the invariant that broke.

Scope note

This is a defect in SP2's own work (introduced by the Task 12 resolve_home/2
design), not inherited. I deferred it rather than fixing it because getting
item 2 right is a modelling decision about how membership arcs are traversed,
and I would rather that be a deliberate call than a patch made under the
momentum of a large branch.