Engineering Graph

Everything in Pulse is a node or an edge in one graph. Developers, projects, organizations, events, proofs and knowledge artifacts are nodes; authorship, membership, ownership, resolution and derivation are edges. Every surface you use — a timeline, a profile, a feed, a leaderboard — is a view of that one structure.

The graph is what turns a pile of events into an engineering record. On its own, an UNLOCK is a note. Connected to the BLOCK it resolved, the project it happened in, the developer who authored it, the proof that confirms it and the knowledge artifact it produced, it becomes a fact you can navigate in five directions — and that navigability is the product.

The graph exists to make the record answerable. Not 'what did this person write' but: what did they resolve, in which systems, with what proof, alongside whom, and did the fix hold. Those questions are impossible in a flat list and trivial in a graph, and they are the questions that actually matter about engineering.

The alternative is what most organizations already have: a repository host, an incident tool, a docs site, a performance-review spreadsheet. Each holds a fragment, none of them agree, and the connections between them — the ones that carry the meaning — exist only in someone's head. When that person leaves, the fragments stop being a record at all.

Modelling everything as one graph means the connections are first-class rather than inferred. The cost is that we had to be rigid about the vocabulary — four event kinds, a fixed set of edges, no custom types — because a graph whose edges mean different things in different corners is not queryable. We took that constraint deliberately. A small, strictly enforced vocabulary is the price of a record that is still coherent in ten years.

A timeline is the most-used view of the graph: events belonging to one node, in the order they occurred. Every primary entity has one, and they are all the same projection with a different filter.

• Project timeline — everything that happened inside a project, from creation through incidents to archival.
• Developer timeline — everything one engineer authored, across every project and every employer they have ever had.
• Organization timeline — the aggregate execution of every project the organization owns.
• Incident arc — the sub-timeline formed by a BLOCK, the work in its room, and the UNLOCK that resolved it.

Timelines are ordered by occurred_at, not by when Pulse learned of the event. A deployment synced an hour late still sits at the moment it deployed. They are append-only: an event never moves, never disappears, and never changes what it says. A timeline can be read from any point in time and will say the same thing it said then.

The graph is the source of truth; it is never read directly by a page. Every surface reads a projection — a derived, rebuildable view: the feed, search, the profile, the project page, the leaderboard, the knowledge index. Projections are disposable by design. If one is wrong, it is rebuilt from the log, because the log is the only thing that was ever authoritative.

1. An event is appended to the log, with its edges: the author, the project, the organization, any event it resolves.
2. Verification mints a proof node and attaches it to the event.
3. The change is published to the projection layer.
4. Every affected view is rebuilt — the project timeline, the author's profile and Build Cred, the feed, search, the knowledge index.
5. Reads are served from those projections. The graph itself is never mutated by a read.

        WRITE                    TRUTH                        READ

   pulse event      ──▶   APPEND-ONLY LOG   ──▶   THE GRAPH   ──▶   PROJECTIONS
   pulse deploy            every event            nodes + edges       Feed
   repository              ever recorded          developer           Search
   pipeline                     │                 project             Profile
                                │                 organization        Project page
                                │                 event               Leaderboard
                                │                 proof               Knowledge index
                                │                 knowledge                 │
                                │                                           │
                                └──── derivation flows ONE way ─────────────┘
                                      ✗ nothing writes back

   A projection can be wrong, and it can be thrown away and rebuilt from the log.
   The log cannot be wrong about what it recorded — which is why the pages can be trusted.

You do not interact with the graph directly. You traverse it, constantly, without noticing.

1. You read an event and follow it to the project it happened in.
2. From the project you follow a contributor to their profile.
3. From their profile you follow a resolved incident to the BLOCK it started as.
4. From the BLOCK you follow the derivation to the knowledge artifact it produced.
5. Every one of those hops is an edge, and every page you landed on was a projection.

The atlas-gateway pooling incident, as it exists in the graph.

{
  "nodes": [
    { "id": "@aria",                  "type": "developer" },
    { "id": "northwind",              "type": "organization" },
    { "id": "atlas-gateway",          "type": "project" },
    { "id": "evt_atlas_pool_block",   "type": "event", "kind": "BLOCK" },
    { "id": "evt_atlas_pool_unlock",  "type": "event", "kind": "UNLOCK" },
    { "id": "proof_2a77b410",         "type": "proof", "level": "L3" },
    { "id": "know_pool_exhaustion",   "type": "knowledge" }
  ],
  "edges": [
    { "from": "@aria",                 "to": "evt_atlas_pool_unlock", "type": "authored" },
    { "from": "@aria",                 "to": "northwind",             "type": "member_of" },
    { "from": "northwind",             "to": "atlas-gateway",         "type": "owns" },
    { "from": "evt_atlas_pool_unlock", "to": "atlas-gateway",         "type": "belongs_to" },
    { "from": "evt_atlas_pool_unlock", "to": "evt_atlas_pool_block",  "type": "resolves" },
    { "from": "proof_2a77b410",        "to": "evt_atlas_pool_unlock", "type": "attests" },
    { "from": "know_pool_exhaustion",  "to": "evt_atlas_pool_unlock", "type": "derived_from" }
  ]
}

# Read one node's slice of the graph from the terminal
pulse logs --project atlas-gateway --since 7d

• Link the UNLOCK to its BLOCK. That single edge is what creates the incident arc, the resolution time and the knowledge artifact — three derived things from one relationship.
• Attribute events to the right project. An event in the wrong container is connected to the wrong everything, and it cannot be moved afterwards.
• Trust the projections, but understand they are derived. If a page looks wrong, the question is what the log says, not what the page says.
• Follow the graph when you are evaluating a record. A score is a summary; the edges are the evidence.

• Expecting to edit the graph directly. There is no write path except appending events — by design.
• Assuming a projection is the truth. It is a cached view of the truth, and it can be rebuilt from the log at any time.
• Recording related events without linking them, then wondering why no arc appears. Unlinked events are islands.
• Reading a timeline as a feed of activity. It is an ordered record — the order is a claim, and it is one Pulse stands behind.

• Projections are eventually consistent. A newly recorded event may take a moment to appear in search or on the leaderboard; the log has it immediately.
• Masking is applied when a projection is built, per viewer — never by mutating the graph. The raw record is always intact underneath.
• Forks keep a derived_from edge to their origin, so lineage is preserved instead of being silently lost.
• Because projections are rebuildable, a bug in a view is a bug in a view. It can never corrupt the record it was derived from.