lantern

oculus-design-notes-2025-12-13

oculus-design-notes-2025-12-13

December 13, 2025 ~1:00-2:00 AM

Context

Following a day that started with someone unable to read two timestamps, Graeme built a pattern matcher that extracts command shapes from help files, liberated metadata into an API, and posted category theory manifestos on Mastodon. This session captures the architectural insights that emerged while "not going to bed."

The Core Realization: Same Abstraction, Different Projections

The system Graeme has built isn't multiple things. It's one thing that projects into many shapes:

  • Fences = compute (stateless functions)
  • Fences + Virtual Fences = stateful services (compute with persistent backing)
  • Nodes = state containers (markdown files)
  • Edges = transitions with optional transforms (middleware)
  • Navigation = routing (the graph IS the network topology)
  • Context = the data flowing through

This maps directly to Kubernetes concepts without Kubernetes:

  • Stateless pod = ephemeral fence
  • StatefulSet with PV = fence + virtual fence
  • Service mesh = edges/morphisms
  • Load balancer = graph navigation (topology IS routing)

Storage Architecture

Current: Markdown → JSON graph on disk Future path:

  • Graph lives in Mongo (or equivalent)
  • Markdown becomes serialization format, not source of truth
  • Hot storage in memory, cold in database
  • Markdown for human interface / git version control
  • Runtime = pure graph operations

Concurrency model: No hard problems because:

  • Fence execution = stateless, embarrassingly parallel
  • Document render = read from cache
  • Single-user state = one writer, clobber is fine
  • Graph structure changes = git-controlled, offline merge
  • No multiplayer real-time editing required

The Pipeline IDE Vision

Pipelines ARE graph navigation. Draw the pipeline visually:

  • South = next step
  • Fork East = parallel branch
  • Edges = middleware transforms (identity = passthrough)
  • Nodes = stages (restartable checkpoints)
  • Edge activities = stateless transforms (retry from last stage if failed)

Type-Checked Composition

Every node advertises:

  • Requires: what context types must exist upstream
  • Produces: what context types it creates

Validation = trace upstream, check if requirements satisfied. Don't care which node produced it, just that the type exists in ancestry.

git-clone        → produces: [repository]
gradle-builder   → requires: [repository] → produces: [artifact]
artifact-upload  → requires: [artifact] → produces: [artifact-ref]
docker-build     → requires: [artifact] → produces: [image]
ecs-deploy       → requires: [image] → produces: [service, cloudformation]
health-check     → requires: [service] → produces: [health-status]
publisher        → requires: [health-status] → produces: [release]

IDE experience: drag blocks, connect edges, system validates types. Green arrow = valid. Red arrow = missing requirement. Make all arrows green = valid pipeline.

Fractal Graph Structure

Edges aren't just transitions. Edges can be portals into subgraphs.

  • Enter an edge → traverse THAT graph → come out transformed
  • Middleware isn't a function, it's a traversable space
  • Composes infinitely: edges contain graphs contain edges contain graphs...

Mario 3 mental model: pipes take you to sub-worlds, you come back with power-ups (new context, new capabilities).

The Agentic Control Plane

The graph IS the state machine for any agent (human, LLM, script):

  • Graph knows what states exist
  • Graph knows what transitions are legal
  • Graph knows what data is required for each transition
  • Agent says "I want to go there"
  • Graph validates, executes leaf, updates state
  • New options available, loop

Feature flags, circuit breakers, kill switches, permissions = all just graph topology:

  • "Can't go south" = feature disabled
  • "Can't go south from THIS node" = scoped permission
  • "Can't go south if env != prod" = environment gating
  • "Can't go anywhere" = global halt

All just: is this edge traversable given current context?

Agent Learning Through Traversal

The graph IS the spell book. Traversal IS learning.

An agent walks through to do a task. Along the way it passes nodes with fences. The fences are documented. The agent reads them. Now it knows that capability exists.

By task completion, the agent has accumulated knowledge of everything it passed - tools it didn't need this time, but now knows are there.

The graph is tutorial + game + tool chest. The payoff isn't XP. The payoff is: now you can actually cast fireball.

Stages vs Activities

Stage (node):

  • Restartable checkpoint
  • State lives here
  • Resume point

Activity (edge):

  • Stateless transform
  • Runs in transit
  • Idempotent or ephemeral
  • Retry from last stage if failed

Graph structure: stage → activity → stage → activity → stage

Stages = save points. Activities = verbs between them.

What Is This Thing?

It's a computational graph where the primitives are text and topology.

The "do anything" capability comes from: anything that can be modeled as "I'm here, I have this context, what are my options, I pick one, now I'm there with new context" can run on it.

That's most things:

  • How thinking works
  • How workflows work
  • How state machines work
  • How conversations work
  • How pipelines work

The limit: Can you draw it? Can you describe the states? Can you describe the transitions? Can you describe what's legal when?

If yes: it runs on this system.

Remaining Work

  • Wire up the generic component for data-backed fences
  • YAML mapping layer to connect data store to fences
  • Command builder that reads help file shapes
  • Index of commands for the API
  • (Optional) Plan/apply preview - capability is there, nobody's asked

None of this changes the abstraction. It's all just projections of what already exists.

The Yoneda Connection

Tonight was another demonstration: the system is defined by all its projections. Pipeline IDE, agentic control plane, feature flags, type-checked composition - all the same underlying thing, viewed from different angles.

More arrows pointing at the same object. More sentences the word can appear in. Same shape, more understanding.

"You didn't add anything tonight. You recognized what was already there."