Write-creates — a local write materializes its target (L4 graph)

A local data write to an address that does not resolve creates the vertex, and every missing intermediate along the way, mkdir -p style (RFC-0005 §D; graph_t::ensure_vertex). It is gated by the CREATE access bit on the nearest existing ancestor’s effective ACL — a graph holding no ancestor at all is open, which is why this example needs no ACL setup.

What to notice

  • The asymmetry is the ruling, and it is not shown here. A remote fieldless FWD{WRITE} whose dst resolves to nothing answers tr::path::not_found and creates nothing (RFC-0005 §D amendment 1); a peer creates through the creator endpoint (ADR-0059). Demonstrating that arm needs the wire resolver, so this example asserts only the local half; the remote half is pinned in core/tests/op_resolve_test.cpp, not here.

  • The : control plane does not create. A field write to a nonexistent vertex is NOT_FOUND, because there is no vertex to control. The example writes /zone/b:acl and then confirms /zone/b still does not exist.

  • The created intermediate is real, and empty. /zone/a resolves after the write but was never written itself; reading it serves the composed branch read of its registered subtree — the folded POINT tree, not a NOT_FOUND (RFC-0016).

  • Appearance is the first write. Every way a vertex comes into being is itself a write, so a subtree subscriber above it sees the child appear without any dedicated event type (reference 02 §Observing structural change).

Source

 1/*
 2 * SPDX-License-Identifier: Apache-2.0
 3 * SPDX-FileCopyrightText: Copyright 2026 avatarsd LLC
 4 */
 5
 6/**
 7 * @file
 8 * @brief ONE CONCEPT — write-creates: a LOCAL data write materializes its target.
 9 *
10 * A local data write to an address that does not resolve creates the vertex and every
11 * missing intermediate, `mkdir -p` style (RFC-0005 §D; `graph_t::ensure_vertex`). The
12 * asymmetry is deliberate and is NOT shown here because it needs a peer: a REMOTE fieldless
13 * `FWD{WRITE}` to an unresolved `dst` answers `tr::path::not_found` and creates nothing
14 * (RFC-0005 §D amendment 1) — a peer creates through the ADR-0059 creator endpoint.
15 *
16 * The `:` control plane does not create either: a field write to a nonexistent vertex is
17 * `NOT_FOUND`, because there is no vertex to control (`core/src/graph.cpp`, the field arm of
18 * `write(const path_t&, rope_t)`). That half IS checked here.
19 *
20 * Runs under ctest as `example_graph_write_creates`; returns non-zero on any failed check.
21 */
22
23#include <cstdio>
24#include <span>
25#include <string_view>
26
27#include "libtracer/tracer.hpp"
28
29namespace {
30
31using tr::graph::path_t;
32using tr::graph::status_t;
33
34/** @brief An owned one-segment view over @p text. */
35tr::view::view_t value_of(std::string_view text) {
36    return *tr::view::over_bytes(std::as_bytes(std::span<const char>(text.data(), text.size())));
37}
38
39/** @brief Report expectation @p what and record a failure on @p ok. */
40void check(bool& ok, bool cond, const char* what) {
41    std::printf("  [%s] %s\n", cond ? "ok" : "FAIL", what);
42    ok = ok && cond;
43}
44
45}  // namespace
46
47int main() {
48    tr::graph::graph_t g;
49    bool ok = true;
50
51    // Nothing is registered. One write builds /zone, /zone/a and /zone/a/soil.
52    check(ok, !g.find(path_t("/zone/a/soil").key()), "the target does not exist yet");
53    const auto w = g.write(path_t("/zone/a/soil"), value_of("moist"));
54    check(ok, w.has_value(), "a local data write to an unresolved path succeeds");
55    check(ok, g.find(path_t("/zone/a/soil").key()).has_value(), "the target vertex now exists");
56    check(ok, g.find(path_t("/zone/a").key()).has_value(),
57          "the missing intermediate was created too");
58
59    const auto rb = g.read(path_t("/zone/a/soil"));
60    check(ok, rb.has_value(), "the created vertex serves the value that created it");
61
62    // The intermediate is created but never written: it resolves, and has no value.
63    const auto mid = g.read(path_t("/zone/a"));
64    check(ok, mid.has_value(), "the intermediate reads as a composed branch, not NOT_FOUND");
65
66    // Field writes never create — there is no vertex to control.
67    const auto fw = g.write(path_t("/zone/b:acl"), value_of("x"));
68    check(ok, !fw && fw.error() == status_t::NOT_FOUND,
69          "a :field write to a nonexistent vertex is NOT_FOUND");
70    check(ok, !g.find(path_t("/zone/b").key()), "and it created nothing");
71    return ok ? 0 : 1;
72}

See also: graph module · graph model reference §Vertex lifecycle · retirement (the other half of the lifecycle).