Query traversal: Home routing for arc-discovered nrefs

[david-w-t]

Closes the defect filed against PR #53 (comment) and recorded in TASKS.md: #q_find_path{} silently returned {ok, no_path} for a path that exists.

The defect

resolve_home/2 resolves a bare nref by trying the session's bound project first and falling back to the environment. That guess is correct and deliberate for entry points, where the query language has no characterization context to route on. But session_read_arcs/4 and is_scaffold_node/2 applied it to arc-discovered nrefs too, re-deciding the store for every node BFS reached.

Project allocators start at 1, so any project with ≥6 instances shadows bootstrap nref 6 and ≥35 shadows the whole scaffold. Two runtime environment attributes whose only route runs through nref 6:

environment session     => {ok, [A1 -23-> 6, 6 -24-> A2]}
project,  1 instance    => {ok, [A1 -23-> 6, 6 -24-> A2]}
project, 21 instances   => {ok, no_path}          <-- silently wrong

Expanding 6, the walk resolved it to the project's instance 6, read relationships_<Anchor>, found no taxonomy arcs, and the frontier emptied.

A second failure, not in the original report

Tracing turned up a worse case. Visited was keyed by bare nref and the target test compared bare integers, so with to = 6 under a shadowing project a walk reaching the environment's attribute 6 reported {found, Path} — a fabricated path claiming to have reached the project's instance 6. A wrong answer rather than a missing one.

The fix

Half A — arc-discovered nrefs stop being ambiguous. New pure graphdb_ns:arc_target_namespace(Home, Kind, Char) derives the target's store from the arc traversed, keyed on #relationship.kind. The instance↔class membership pair is the one arc shape whose ends deliberately live in different Homes, and its characterization is exactly what says which direction is being walked:

arc_target_namespace(_Home, taxonomy,      _C) -> environment;
arc_target_namespace( Home, composition,   _C) -> Home;
arc_target_namespace( Home, connection,    _C) -> Home;
arc_target_namespace(_Home, instantiation, ?ARC_INST_TO_CLASS) -> environment;
arc_target_namespace( Home, instantiation, ?ARC_CLASS_TO_INST) -> Home;
arc_target_namespace( Home, Kind, Char) -> %% logged; degrades to same store

The catch-all is deliberate: this is reachable from the graphdb_query singleton, where a function_clause would take the query server down for every session over one malformed row.

Half B — traversal state is Home-qualified. home_id() :: environment | {project, Anchor} now keys the visited set, the frontier, #cont_path{}, and the public result. resume/2 gains a caller-side validate_cont_homes/2 returning {error, session_project_mismatch}.

A path edge gains home iff the hop crosses stores — absent means "same store as the previous hop". The value is a home_id(), never the raw project handle, so physical table atoms stay out of query results.

Correction to the fix direction I filed on #53

That comment said to route via graphdb_ns:target_namespace/2 on the arc label's target_kind AVP. That does not work. Bootstrap arc labels 21–30 carry no target_kind — bootstrap.terms:122-131 creates all ten with [], and graphdb_attr:init/1 retro-stamps only attribute_type. Arcs 23/24 are the decisive hops in the repro, so the lookup fails precisely where routing matters. docs/Architecture.md asserted the same false premise and is corrected here.

Not changed, deliberately

resolve_home/2, session_read_arcs/4, and session_read_node/2 are untouched. Entry points still use the intent-following guess, and resolve_home_prefers_project_and_logs_on_collision plus the whole q6_find_path group pass unmodified — the executable proof that entry-point behaviour is intact. Only bfs_step/5 changed caller, to the pre-existing session_read_arcs_home/5.

Still open, filed in TASKS.md

• BFS at an environment-homed node reads only the environment relationship table, so an environment class cannot reach its project instances across arc 30. #q_instances_of{} keeps its special case.
• Backfilling target_kind onto arc labels 21–30, which would let graphdb_instance:check_target_kind/3 drop its permissive legacy arm.

Verification

551 CT + 151 EUnit, rebar3 xref clean with no new suppressions, compile and as test compile zero warnings.

Reverting Half A reproduces the filed no_path and surfaces the cache entry {arcs, #{anchor => …}, 6, outgoing, [taxonomy]} => [] — the environment's nref 6 read from the project's table. Reverting Half B's target qualification reproduces the fabricated one-edge path. Neither new test passes vacuously.

Design: docs/designs/query-traversal-home-routing-design.md

🤖 Generated with Claude Code

https://claude.ai/code/session_01EWukKCbrN8GybaScJGU2kF

[david-w-t]

ok.