Register a vertex, and address it (L4 graph)¶

The first thing a node does. A path_t parses its string once into the canonical PATH-TLV payload — the packed segment records — and the vertex map is keyed on those bytes, never on the string (reference 02 §Dispatch keyed on canonical PATH TLV bytes). register_vertex returns a vertex_handle_t, and find takes the key, which is the same lookup the dispatcher runs.

What to notice¶

The key is the identity, the string is a courtesy. The example prints the byte length of /sensor/temp’s key and resolves the handle through g.find(temp.key()). Two spellings that name one vertex must canonicalize to byte-identical PATH payload bytes.
Two registration doors, one fallible. register_vertex takes a known-good literal and hard-aborts on a collision, because a collision on a compile-site literal is a source bug (ADR-0056). try_register_vertex is the runtime-path form and reports PATH_IN_USE instead.
Registering /sensor/temp does not register /sensor. The intermediate is an unregistered structural placeholder — the addressing scaffolding created it on the way to a deeper registration, and find does not answer for one (CONTEXT.md §Structural vertex). That is distinct from a structural vertex, which is registered and merely carries no application datum.
There is no null handle. “No such vertex” is std::optional<vertex_handle_t>’s empty state, not an invalid handle.

Source¶

/*
 * SPDX-License-Identifier: Apache-2.0
 * SPDX-FileCopyrightText: Copyright 2026 avatarsd LLC
 */

/**
 * @file
 * @brief ONE CONCEPT — register a vertex, and address it by its canonical PATH bytes.
 *
 * A `path_t` parses its string ONCE into the canonical PATH-TLV payload (packed segment
 * records); the vertex map is keyed on those bytes, never on the string
 * (`docs/reference/02-graph-model.md` §Dispatch keyed on canonical PATH TLV bytes). Two
 * further first-contact facts fall out and are checked here: re-registering a live path is
 * `PATH_IN_USE`, and registering `/sensor/temp` does NOT register `/sensor` — the
 * intermediate is an unregistered structural placeholder (`CONTEXT.md` §Structural vertex).
 *
 * Runs under ctest as `example_graph_register`; returns non-zero on any failed check.
 */

#include <cstdio>

#include "libtracer/tracer.hpp"

namespace {

using tr::graph::path_t;
using tr::graph::role_t;
using tr::graph::status_t;
using tr::graph::vertex_handle_t;

/** @brief Report expectation @p what and record a failure on @p ok. */
void check(bool& ok, bool cond, const char* what) {
    std::printf("  [%s] %s\n", cond ? "ok" : "FAIL", what);
    ok = ok && cond;
}

}  // namespace

int main() {
    tr::graph::graph_t g;
    bool ok = true;

    const path_t temp("/sensor/temp");
    const vertex_handle_t vh = g.register_vertex(temp, role_t::STORED_VALUE);
    std::printf("registered /sensor/temp — key is %zu packed bytes\n", temp.key().size());

    // find() takes the KEY, not the string: the same lookup the dispatcher runs.
    const auto found = g.find(temp.key());
    check(ok, found && *found == vh, "find(key) resolves to the registered handle");

    // register_vertex(literal) hard-aborts on a collision (ADR-0056: a source bug); the
    // fallible form is for a genuine runtime path, and reports the collision.
    const auto dup = g.try_register_vertex(path_t("/sensor/temp"), role_t::STORED_VALUE);
    check(ok, !dup && dup.error() == status_t::PATH_IN_USE,
          "re-registering a live path is PATH_IN_USE");

    check(ok, !g.find(path_t("/sensor").key()),
          "the intermediate /sensor stays an unregistered placeholder");
    check(ok, !g.find(path_t("/sensor/humidity").key()), "an unknown path resolves to nothing");
    return ok ? 0 : 1;
}