refactor: role rich domain model in core + protocol export

Role is now a rich domain model in @rolexjs/core with ownership isolation,
KV-serializable snapshot/restore, and all domain methods. RoleXService
orchestrates lifecycle. Prototype merged into core. Protocol interface
bundles tools + instructions for channel adapters. rolexjs becomes thin
rendering shell. Minimal public API surface.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: deepracticexs

.changeset/role-rich-model.md

@@ -0,0 +1,15 @@
+---
+"@rolexjs/core": minor
+"rolexjs": minor
+"@rolexjs/mcp-server": patch
+---
+
+Role rich domain model — merge prototype into core, Protocol export
+
+- Role is now a rich domain model in @rolexjs/core with ownership isolation, KV-serializable snapshot/restore, and all domain methods (want, plan, todo, finish, reflect, realize, master, etc.)
+- RoleXService orchestrates Role lifecycle, caching, and persistence in core
+- rolexjs becomes a thin rendering shell delegating to core's RoleXService
+- Protocol interface bundles tools + instructions as a single export for channel adapters
+- Removed scattered exports (render, genesis, createRendererRouter) from rolexjs public API
+- Deleted old Role class and RoleContext from rolexjs (replaced by core's Role)
+- Moved findInState utility to core

apps/mcp-server/src/index.ts

@@ -16,11 +16,10 @@ import {
   detail,
   type ParamDef,
   type ProjectAction,
+  protocol,
   renderProjectResult,
   type State,
   type ToolDef,
-  tools,
-  worldInstructions,
 } from "rolexjs";
 
 import { z } from "zod";
@@ -185,11 +184,11 @@ const executors: Record<string, ToolExecutor> = {
 const server = new FastMCP({
   name: "rolex",
   version: "0.12.0",
-  instructions: worldInstructions,
+  instructions: protocol.instructions,
 });
 
 // Register all tools from unified schema
-for (const toolDef of tools) {
+for (const toolDef of protocol.tools) {
   const executor = executors[toolDef.name];
   if (!executor) {
     throw new Error(`No executor for tool "${toolDef.name}"`);

apps/mcp-server/tests/mcp.test.ts

@@ -1,17 +1,18 @@
 /**
  * MCP server integration tests.
  *
- * Tests the thin MCP layer (state holder) on top of Rolex.
- * Business logic (RoleContext) is tested in rolexjs/tests/context.test.ts.
+ * Tests the thin MCP layer (state holder) on top of RoleX.
+ * Business logic (Role model) is tested in core/tests/unit/role-model.test.ts.
  * Render is now in rolexjs — Role methods return rendered strings directly.
  */
 import { beforeEach, describe, expect, it } from "bun:test";
+import type { CommandResult } from "@rolexjs/core";
 import { localPlatform } from "@rolexjs/local-platform";
-import type { CommandResult } from "@rolexjs/prototype";
-import { createRoleX, type Rolex, render } from "rolexjs";
+import { createRoleX, type RoleX } from "rolexjs";
+import { render } from "../../../packages/rolexjs/src/render.js";
 import { McpState } from "../src/state.js";
 
-let rolex: Rolex;
+let rolex: RoleX;
 let state: McpState;
 
 beforeEach(async () => {
@@ -33,7 +34,7 @@ describe("requireRole", () => {
     const role = await rolex.activate("sean");
     state.role = role;
     expect(state.requireRole()).toBe(role);
-    expect(state.requireRole().roleId).toBe("sean");
+    expect(state.requireRole().id).toBe("sean");
   });
 });
 
@@ -104,19 +105,18 @@ describe("render", () => {
 
 describe("full execution flow", () => {
   it("completes want → plan → todo → finish → reflect → realize through Role API", async () => {
-    // Born + activate
     await rolex.direct("!individual.born", { content: "Feature: Sean", id: "sean" });
     const role = await rolex.activate("sean");
     state.role = role;
 
     // Want
     const goal = await role.want("Feature: Build Auth", "build-auth");
-    expect(role.ctx.focusedGoalId).toBe("build-auth");
+    expect(role.snapshot().focusedGoalId).toBe("build-auth");
     expect(goal).toContain("I →");
 
     // Plan
     const plan = await role.plan("Feature: Auth Plan", "auth-plan");
-    expect(role.ctx.focusedPlanId).toBe("auth-plan");
+    expect(role.snapshot().focusedPlanId).toBe("auth-plan");
     expect(plan).toContain("I →");
 
     // Todo
@@ -129,7 +129,7 @@ describe("full execution flow", () => {
       "Feature: Implemented JWT\n  Scenario: Token pattern\n    Given JWT needed\n    Then tokens work"
     );
     expect(finished).toContain("[encounter]");
-    expect(role.ctx.encounterIds.has("impl-jwt-finished")).toBe(true);
+    expect(role.snapshot().encounterIds).toContain("impl-jwt-finished");
 
     // Reflect: encounter → experience
     const reflected = await role.reflect(
@@ -138,8 +138,8 @@ describe("full execution flow", () => {
       "token-insight"
     );
     expect(reflected).toContain("[experience]");
-    expect(role.ctx.encounterIds.has("impl-jwt-finished")).toBe(false);
-    expect(role.ctx.experienceIds.has("token-insight")).toBe(true);
+    expect(role.snapshot().encounterIds).not.toContain("impl-jwt-finished");
+    expect(role.snapshot().experienceIds).toContain("token-insight");
 
     // Realize: experience → principle
     const realized = await role.realize(
@@ -148,7 +148,7 @@ describe("full execution flow", () => {
       "refresh-tokens"
     );
     expect(realized).toContain("[principle]");
-    expect(role.ctx.experienceIds.has("token-insight")).toBe(false);
+    expect(role.snapshot().experienceIds).not.toContain("token-insight");
   });
 });
 
@@ -163,14 +163,14 @@ describe("focus", () => {
     state.role = role;
 
     await role.want("Feature: Goal A", "goal-a");
-    expect(role.ctx.focusedGoalId).toBe("goal-a");
+    expect(role.snapshot().focusedGoalId).toBe("goal-a");
 
     await role.want("Feature: Goal B", "goal-b");
-    expect(role.ctx.focusedGoalId).toBe("goal-b");
+    expect(role.snapshot().focusedGoalId).toBe("goal-b");
 
     // Switch back to goal A
     await role.focus("goal-a");
-    expect(role.ctx.focusedGoalId).toBe("goal-a");
+    expect(role.snapshot().focusedGoalId).toBe("goal-a");
   });
 });
 
@@ -179,18 +179,16 @@ describe("focus", () => {
 // ================================================================
 
 describe("selective cognition", () => {
-  it("ctx tracks multiple encounters, reflect consumes selectively", async () => {
+  it("tracks multiple encounters, reflect consumes selectively", async () => {
     await rolex.direct("!individual.born", { content: "Feature: Sean", id: "sean" });
     const role = await rolex.activate("sean");
     state.role = role;
 
-    // Create goal + plan + tasks
     await role.want("Feature: Auth", "auth");
     await role.plan("Feature: Plan", "plan1");
     await role.todo("Feature: Login", "login");
     await role.todo("Feature: Signup", "signup");
 
-    // Finish both with encounters
     await role.finish(
       "login",
       "Feature: Login done\n  Scenario: OK\n    Given login\n    Then success"
@@ -200,8 +198,8 @@ describe("selective cognition", () => {
       "Feature: Signup done\n  Scenario: OK\n    Given signup\n    Then success"
     );
 
-    expect(role.ctx.encounterIds.has("login-finished")).toBe(true);
-    expect(role.ctx.encounterIds.has("signup-finished")).toBe(true);
+    expect(role.snapshot().encounterIds).toContain("login-finished");
+    expect(role.snapshot().encounterIds).toContain("signup-finished");
 
     // Reflect only on "login-finished"
     await role.reflect(
@@ -211,9 +209,9 @@ describe("selective cognition", () => {
     );
 
     // "login-finished" consumed, "signup-finished" still available
-    expect(role.ctx.encounterIds.has("login-finished")).toBe(false);
-    expect(role.ctx.encounterIds.has("signup-finished")).toBe(true);
-    // Experience registered
-    expect(role.ctx.experienceIds.has("login-insight")).toBe(true);
+    const snap = role.snapshot();
+    expect(snap.encounterIds).not.toContain("login-finished");
+    expect(snap.encounterIds).toContain("signup-finished");
+    expect(snap.experienceIds).toContain("login-insight");
   });
 });

bdd/features/role-domain.feature

@@ -0,0 +1,41 @@
+@role-domain
+Feature: Role as rich domain model
+  Role is a self-contained stateful entity that holds its own state projection
+  and exposes domain behaviors. Internal state (cursors, cognitive registries)
+  is not exposed — only domain methods.
+
+  Background:
+    Given a fresh Rolex instance
+    And individual "sean" exists
+    And I activate role "sean"
+
+  # ===== Role boundary =====
+
+  Scenario: Role knows its own boundary
+    Given I want goal "auth" with "Feature: Auth"
+    And I plan "jwt" with "Feature: JWT"
+    And I todo "login" with "Feature: Login"
+    Then role "sean" should contain node "auth"
+    And role "sean" should contain node "jwt"
+    And role "sean" should contain node "login"
+
+  # ===== serialization =====
+
+  Scenario: Role serializes cursor and cognitive state
+    Given I want goal "auth" with "Feature: Auth"
+    And I plan "jwt" with "Feature: JWT"
+    And I todo "login" with "Feature: Login"
+    And I finish "login" with encounter "Feature: Login done\n  Scenario: OK\n    Given login\n    Then success"
+    When I serialize the role
+    Then the snapshot should contain focusedGoalId "auth"
+    And the snapshot should contain focusedPlanId "jwt"
+    And the snapshot should contain encounter "login-finished"
+
+  Scenario: Role restores from snapshot and state projection
+    Given I want goal "auth" with "Feature: Auth"
+    And I plan "jwt" with "Feature: JWT"
+    And I serialize the role
+    When I restore the role from snapshot with fresh state projection
+    Then focusedGoalId should be "auth"
+    And focusedPlanId should be "jwt"
+    And focus without args should return "auth"

bdd/features/role-isolation.feature

@@ -0,0 +1,56 @@
+@role-isolation
+Feature: Role isolation
+  Each Role is a self-contained operation domain for one individual.
+  Focus, goals, plans, and cognitive state must never leak between individuals.
+
+  Background:
+    Given a fresh Rolex instance
+    And individual "nuwa" exists with goal "setup-cto"
+    And individual "sean" exists with goal "mcp-args"
+
+  # ===== focus isolation =====
+
+  Scenario: Focus without args returns own goal
+    When I activate role "nuwa"
+    And I focus without args
+    Then focusedGoalId should be "setup-cto"
+    And the output should contain "(setup-cto)"
+
+  Scenario: Focus cannot target another individual's goal
+    When I activate role "nuwa"
+    Then focus on "mcp-args" should fail with ownership error
+
+  Scenario: Switching individuals restores correct focus
+    Given I activate role "sean"
+    And I focus on "mcp-args"
+    When I activate role "nuwa"
+    And I focus without args
+    Then focusedGoalId should be "setup-cto"
+
+  # ===== goal isolation =====
+
+  Scenario: Want creates goal under own individual only
+    When I activate role "nuwa"
+    And I want goal "new-goal" with "Feature: New goal"
+    Then "new-goal" should be under individual "nuwa"
+    And "new-goal" should not be under individual "sean"
+
+  # ===== persistence isolation =====
+
+  Scenario: Persisted focus does not leak across individuals
+    Given I activate role "sean"
+    And I focus on "mcp-args"
+    And role "sean" is persisted
+    When I activate role "nuwa"
+    And I focus without args
+    Then focusedGoalId should be "setup-cto"
+    And focusedGoalId should not be "mcp-args"
+
+  Scenario: Restore from KV returns correct individual state
+    Given I activate role "sean"
+    And I focus on "mcp-args"
+    And role "sean" is persisted
+    When I restore role "sean" from KV
+    Then focusedGoalId should be "mcp-args"
+    When I restore role "nuwa" from KV
+    Then focusedGoalId should be "setup-cto"

bdd/features/rolex-world.feature

@@ -0,0 +1,38 @@
+@rolex-world
+Feature: RoleX as world entry point
+  RoleX is the runtime that manages Role lifecycle and world-level operations.
+  activate produces a Role instance. direct executes world-level commands.
+
+  Background:
+    Given a fresh Rolex instance
+
+  # ===== activate =====
+
+  Scenario: Activate returns a Role instance
+    Given individual "sean" exists
+    When I activate role "sean"
+    Then I should receive a Role with id "sean"
+
+  Scenario: Activate same individual returns same instance
+    Given individual "sean" exists
+    When I activate role "sean"
+    And I activate role "sean" again
+    Then both activations should return the same Role instance
+
+  Scenario: Activate non-existent individual fails
+    When I try to activate role "unknown"
+    Then it should fail with "not found"
+
+  # ===== direct =====
+
+  Scenario: Direct executes world-level commands
+    When I direct "!individual.born" with:
+      | id      | alice          |
+      | content | Feature: Alice |
+    Then individual "alice" should exist
+
+  Scenario: Direct does not require an active Role
+    Given individual "sean" exists
+    When I direct "!census.list" with:
+      | type | individual |
+    Then the direct result should contain "sean"

bdd/steps/context.steps.ts

@@ -75,8 +75,8 @@ When("I activate {string}", async function (this: BddWorld, name: string) {
 Then("focusedGoalId should be {string}", function (this: BddWorld, goalId: string) {
   assert.ok(this.role, "Expected a role but activation failed");
   assert.equal(
-    this.role.ctx.focusedGoalId,
+    this.role.snapshot().focusedGoalId,
     goalId,
-    `Expected focusedGoalId to be "${goalId}" but got "${this.role.ctx.focusedGoalId}"`
+    `Expected focusedGoalId to be "${goalId}" but got "${this.role.snapshot().focusedGoalId}"`
   );
 });