@rolexjs/system

A concept world engine. Define concepts, build a tree, link them with relations — the world emerges.

This package provides the rules of the concept world. It is domain-agnostic — it knows nothing about roles, organizations, or AI agents. The upper layer's job is to define concepts and paint the world using these rules.

The World

The world is a graph made of concepts.

Every node is a Structure — simultaneously three things:

• Concept — what it is (name + description)
• Container — can have child nodes
• Information carrier — can hold information (e.g. a Gherkin Feature text)

There is no special "container" type or "leaf" type. Every node is all three at once.

world
├── agent                          ← concept, also a container
│   ├── knowledge                  ← container (has children)
│   │   ├── pattern                ← information carrier
│   │   │      info: "Feature: ..."
│   │   └── procedure
│   │          info: "Feature: ..."
│   ├── experience                 ← information carrier (no children)
│   │      info: "Feature: I learned..."
│   └── experience                 ← OR a container (has children)
│       └── insight
│              info: "Feature: JWT lesson..."
└── org
    └── position ──relation──→ agent    ← cross-branch link

Tree + Relations = Graph

• Tree (parent → child) provides the hierarchical backbone
• Relations provide cross-branch associations
• Together they form a graph

Four Concepts

Structure   — the node          (what exists)
Relation    — the link          (how they connect)
Process     — the change        (how it evolves)
State       — the projection    (what you see)

Structure

A Structure defines a type of node in the concept world.

import { structure } from "@rolexjs/system";

// Root concept
const world = structure("world", "The concept world", null);

// Child concepts — parent defines where they live in the tree
const agent = structure("agent", "An agent identity", world);
const knowledge = structure("knowledge", "What I know", agent);
const experience = structure("experience", "What I learned", agent);
const insight = structure("insight", "A specific learning", experience);

The parent parameter establishes the tree backbone: insight lives under experience, which lives under agent, which lives under world.

Relation

A Relation defines a cross-branch link type on a Structure.

import { structure, relation } from "@rolexjs/system";

const agent = structure("agent", "An agent identity", world);
const org = structure("org", "An organization", world);

// position lives under org, and can link to agent
const position = structure("position", "A role in an organization", org, [
  relation("appointment", "The individual holding this position", agent),
]);

Relations are declared on the Structure definition as an array. A Structure can have multiple relations pointing to different concept types.

Process

A Process defines how the world changes — a named composition of graph operations.

Five graph primitives:

| Primitive | What it does | | ----------------- | ---------------------------------------------------- | | create(s) | Add a child node of structure type s | | remove(s) | Delete a node of structure type s and its subtree | | transform(a, b) | Harvest from structure a, produce in structure b | | link(s, r) | Establish relation r on structure s | | unlink(s, r) | Remove relation r on structure s |

import { process, create, remove, transform, link, unlink } from "@rolexjs/system";

// Read-only process (no ops) — just projects state
const identity = process("identity", "Project full identity", agent);

// Create process — adds a new concept instance
const want = process("want", "Declare a goal", agent, create(goal));

// Transform process — converts one concept into another
const achieve = process("achieve", "Complete a goal", goal, transform(goal, insight));

// Link process — establishes a cross-branch relation
const appoint = process("appoint", "Assign to position", position, link(position, "appointment"));

// Unlink process — removes a cross-branch relation
const dismiss = process(
  "dismiss",
  "Remove from position",
  position,
  unlink(position, "appointment")
);

State

A State is the projection of a node — a snapshot of its subtree and links.

// State extends Structure, adding:
interface State extends Structure {
  children?: readonly State[]; // subtree
  links?: readonly { relation: string; target: State }[]; // cross-branch links
}

State is never stored — it is computed on demand via runtime.project(node).

Runtime

The Runtime is the execution engine. It operates on concept instances (nodes with id).

import { createRuntime } from "@rolexjs/system";

const rt = createRuntime();

// Create instances
const root = rt.create(null, world);
const sean = rt.create(root, agent, "Feature: I am Sean...");
const dp = rt.create(root, org);
const arch = rt.create(dp, position);

// Link them
rt.link(arch, sean, "appointment");

// Project the state
const state = rt.project(root);
// → world
//   ├── agent (Sean)    info: "Feature: I am Sean..."
//   └── org
//       └── position
//             links: [{ relation: "appointment", target: agent(Sean) }]

// Unlink
rt.unlink(arch, sean, "appointment");

// Remove (cleans up subtree + all related links)
rt.remove(arch);

Runtime API

| Method | Description | | ---------------------------------- | ---------------------------------------------------- | | create(parent, type, info?) | Create a node. parent=null for root. | | remove(node) | Remove a node, its subtree, and all related links. | | transform(source, target, info?) | Produce a new node in target's branch. | | link(from, to, relation) | Establish a cross-branch relation. Idempotent. | | unlink(from, to, relation) | Remove a cross-branch relation. | | project(node) | Compute the current state of a node and its subtree. |

Defining Your World

This package provides the rules. Your job is to define the concepts.

Step 1: Define the concept tree — what kinds of things exist and how they nest.

const society = structure("society", "The world", null);
const individual = structure("individual", "An agent", society);
const persona = structure("persona", "Who I am", individual);
const goal = structure("goal", "What I pursue", individual);
const plan = structure("plan", "How to achieve it", goal);
const task = structure("task", "Concrete work", plan);

Step 2: Define relations — what connects across branches.

const org = structure("organization", "A group", society);
const position = structure("position", "A role in the group", org, [
  relation("appointment", "Who holds this", individual),
]);

Step 3: Define processes — how the world changes.

const want = process("want", "Declare a goal", individual, create(goal));
const design = process("design", "Plan for a goal", goal, create(plan));
const achieve = process("achieve", "Complete a goal", goal, transform(goal, conclusion));
const appoint = process("appoint", "Assign to position", position, link(position, "appointment"));

Step 4: Run it — create instances, link them, project state.

const rt = createRuntime();
const world = rt.create(null, society);
const sean = rt.create(world, individual, "Feature: I am Sean...");
const myGoal = rt.create(sean, goal, "Feature: Build auth system...");
const myPlan = rt.create(myGoal, plan, "Feature: Auth plan...");

The rules are fixed. The world is yours to paint.

Universal Formula

State = Process(Structure, Information?)

Everything reduces to this: a Process operates on a Structure (optionally with Information), and produces a State.

Install

bun add @rolexjs/system