Handles the logical mapping and isolation of human-readable references. More...

#include <NamespaceReferenceManager.h>

Public Member Functions
	NamespaceReferenceManager (ObjectManager &objects, IStorageBackend &storage)
	Constructs a NamespaceReferenceManager bound to a registry.
std::vector< std::string >	Resolve (std::vector< std::string > path) const
	Rewrites a logical path through reference reparse rules.

Detailed Description

Handles the logical mapping and isolation of human-readable references.

This manager is the reparse layer of the namespace. Its design mirrors the ReactOS ParseProcedure / STATUS_REPARSE mechanism: a namespace entry whose type carries a ParseProcedure can redirect name resolution to a different path, allowing branch references and ephemeral relations to appear as first-class objects in the namespace without exposing their physical storage paths directly.

Branch references. A path such as /refs/branch/main is a namespace entry backed by a reference object. Its ParseProcedure rewrites the path to the physical snapshot path (e.g. /snapshots/abc123). The caller's handle lands on the snapshot. To advance the HEAD, the caller must explicitly open the reference object itself with WRITE access, which is the sole contention point for that branch.

Ephemeral relation resolution. An ephemeral relation produces tuples through a generator function rather than physical storage; the generator may query base relations on behalf of the runtime to materialise its output. The caller's handle and access mask remain bound to the ephemeral relation. Base relations are accessed only via the ephemeral relation's own type callbacks; the caller never receives a handle on them and does not need explicit permission on them. Capability security is enforced at the ephemeral-relation boundary, not the base relation boundary.

Atomic multi-reference updates. Updating multiple references simultaneously (e.g. advancing both main and audit_log) must be all-or-nothing. The implementation should acquire exclusive locks on all target namespace entries before modifying any. If LifecycleManager::Contention fails on any entry, all locks are released and the batch is aborted. This preserves audit consistency.

Cycle guard. Ephemeral relation definitions may reference other ephemeral relations, and branch aliases may chain. Name resolution must track reparse depth and return an error after a bounded number of iterations to prevent infinite cycles.

Audit branch. Audit requires global access dissociated from any data branch. It should be modelled as an independent branch; its HEAD is the only contention point for audit-affecting operations.

Todo

Implement Resolve(path) with a reparse loop and cycle depth guard.

Define the reference object type with object_type::exclusive = true and a ParseProcedure that rewrites the resolution path.

Define the batch-update API with all-or-nothing contention semantics. See docs/reactos-ob-comparison.md §8.

Constructor & Destructor Documentation

◆ NamespaceReferenceManager()

nt::NamespaceReferenceManager::NamespaceReferenceManager	(	ObjectManager &	objects,
		IStorageBackend &	storage )

Constructs a NamespaceReferenceManager bound to a registry.

Parameters

objects	Registry used to look up reference objects (branches, sessions) during reparse.
storage	KV backend; required to read the branch-tree merkle nodes when resolving /system/branches/<n>/<mg>/... paths through to their snapshot.

Member Function Documentation

◆ Resolve()

std::vector< std::string > nt::NamespaceReferenceManager::Resolve ( std::vector< std::string > path ) const

Rewrites a logical path through reference reparse rules.

Currently handles branch references: /system/branches/<name>/_{... → /system/snapshots/<target_hash>/_{... where target_hash is the value stored on the named Branch object. When the branch is unborn (target_hash empty) or the rest of the path is empty (caller is opening the branch object itself, not something under it), the path is returned unchanged.}}

_{_{Session paths (/system/sessions/<X>/branches/<name>/...) will be added when SESSION objects exist; for now they are returned as-is.}}

_{_{A 30-iteration cycle guard mirrors the ReactOS reparse cap. If the guard trips the returned path is empty, signaling failure to the caller (Find will subsequently miss).}}