SP1: project/environment reference & namespace model

[david-w-t]

Sub-project 1 of the project/environment separation program
(design: docs/designs/project-env-reference-namespace-model-design.md).
Establishes, at the API/code layer only — no node/relationship record
changes, that every nref reference has a derived namespace and that project
operations require a session. Behaviour-preserving against today's single
Mnesia store; SP2 gives the seam physical teeth.

What landed

Milestone A — mechanisms (subagent-implemented + independently reviewed)

• graphdb_ns — pure namespace map (namespace_of/1, target_namespace/1 → environment | project | home); exhaustive table-driven tests. Intentionally unused by production code in SP1 (the classifier the SP2 store-router will consume).
• graphdb_project — project registry (register_project/1, is_project/1) creating the nref-5 anchor; project session (open_session/1, session_project/1, require_session/1).
• Proxy representation contract — seeded "Remote Reference" class + remote_project/remote_nref literal attributes + graphdb_instance:is_proxy/1 / proxy_coordinates/1. Cross-project links are local proxy nodes carrying remote coordinates as AVP payload; no structural reference crosses a project boundary. Representation only (creation/dereference are SP2/SP3). Ontology-tree diagram updated.

Milestone B — required-session threading & relocation

• Project write ops take a Session first arg and reject a missing/invalid one with {error, invalid_session}: create_instance/4,5,6, add_relationship/5,6,7, remove_relationship/4,5, update_relationship/5,6 (+_both), add_class_membership/3; graphdb_mgr:create_instance/4 + add_relationship/5 gain the session too.
• Relationship mutation relocated to the canonical project surface in graphdb_project (env/project split). Tier-1 *_in_txn primitives untouched → graphdb_rules firing unaffected.
• Scope refinement: mutate/1 and the instance reads (get_instance/children/compositional_ancestors/resolve_value) stay namespace-agnostic in SP1 (like get_node/get_relationships): mutate/1 is a mixed env/project batch, and the reads are consumed by graphdb_query (gating them would force the deferred query-session unification). Their routing lands in SP2.

Testing

Full suite green: 510 CT + 141 EUnit = 651, 0 failures, 0 warnings. New bad-session gate tests cover every gated project-write family; also cleared two latent warnings on the branch.

Deferred (tracked in TASKS.md → Multi-project sessions)

SP2 physical per-project store + allocator-from-1; SP3 distribution/residency + proxy dereference; SP4 migration. Also: proxy_coordinates/1 missing-AVP safety (harmless until SP2 proxy creation); session unification with graphdb_query; private environment overlays.

🤖 Generated with Claude Code

[david-w-t]

Is there anything preventing (or making it difficult) to have more than one project open in a session?

[david-w-t]

Nothing prevents it, and little makes it hard — the hard part is semantics, and that lands with SP2, not here.

Why it's not blocked. The session is a deliberately opaque value: only graphdb_project constructs it (open_session/1) and inspects it (session_project/1, require_session/1). graphdb_mgr and graphdb_instance touch it only through require_session/1 and never pattern-match the shape, and in SP1 nothing routes on project yet (the session is inert). So no code assumes single-project-ness — widening #{project => Nref} to a working set + a current/default is a localized change to ~3 functions in one module.

Where the real work is (SP2+):

1. Write targeting — with projects [A, B] open, which does create_instance(Session, …) land in? A current/default project in the session + per-op override, or an explicit per-op project arg. An API decision, not a mechanical blocker.
2. Rule/overlay priority — a declared precedence across open projects (env → A → B), already anticipated in TASKS.md → Multi-project sessions (list of {ProjectId, AnchorNref} + priority).
3. What doesn't get harder — resolving existing data. Because no structural reference crosses a project boundary (cross-project links are proxy nodes), a row's project-local nrefs belong to its home project, so reads/traversal stay well-defined per-row-home even with several projects open. The only ambiguity is for new writes (targeting) and priority.

"Multiple open" is a working-set/targeting convenience for a principal with access to each; it doesn't dissolve the isolation boundary.

Recommendation: keep it singleton in SP1 (behavior-preserving/YAGNI) — it's forward-compatible, and multi-project naturally lands with SP2 when writes actually route. I've added a "multi-project-session forward compatibility" note to the design doc's deferred section (commit 2cc6b75).