refactor: restructure API — rx.individual.activate, rx.inspect, rx.survey

- Rename RoleNamespace → IndividualNamespace (just activate)
- Move inspect and survey to top-level methods on RoleXBuilder
- Remove SurveyNamespace (survey is a world-level observation, not a command namespace)
- Update all consumers: MCP server, tests, BDD steps, docs

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

Author: deepracticexs

README.md

@@ -173,8 +173,8 @@ import { localPlatform } from "@rolexjs/local-platform";
 // Create — synchronous, initialization is lazy
 const rx = createRoleX({ platform: localPlatform() });
 
-// Activate a role
-const role = await rx.role.activate({ individual: "nuwa" });
+// Activate an individual
+const role = await rx.individual.activate({ individual: "nuwa" });
 
 // Typed namespace API — 9 namespaces
 await rx.society.born({ id: "alice", content: "Feature: Alice\n  A frontend engineer." });
@@ -204,19 +204,20 @@ const { tools, instructions } = rx.protocol;
 
 `createRoleX()` returns a `RoleXBuilder` — a synchronous builder with lazy initialization. The first async call triggers init (genesis prototype, world bootstrap).
 
-**9 typed namespaces:**
+**7 typed namespaces + 2 world-level methods:**
 
-| Namespace | Purpose |
-|-----------|---------|
+| API | Purpose |
+|-----|---------|
+| `rx.individual` | Activate an individual — returns a stateful Role |
 | `rx.society` | Individuals & organizations — born, retire, teach, train, found, dissolve |
 | `rx.org` | Membership & governance — charter, hire, fire, establish, abolish |
 | `rx.position` | Roles & duties — charge, require, appoint, dismiss |
 | `rx.project` | Project management — scope, milestone, deliver, wiki |
 | `rx.product` | Product lifecycle — strategy, spec, release, channel |
-| `rx.survey` | World queries — list all entities |
 | `rx.issue` | Issue tracking — publish, comment, assign, label |
 | `rx.resource` | Resource management — add, push, pull, search |
-| `rx.role` | Role operations — activate, inspect, survey |
+| `rx.inspect()` | Examine any node's full state |
+| `rx.survey()` | List individuals, organizations, positions |
 
 **Universal dispatch:**
 

README.zh-CN.md

@@ -173,8 +173,8 @@ import { localPlatform } from "@rolexjs/local-platform";
 // 创建 — 同步返回，初始化延迟到首次调用
 const rx = createRoleX({ platform: localPlatform() });
 
-// 激活角色
-const role = await rx.role.activate({ individual: "nuwa" });
+// 激活个体
+const role = await rx.individual.activate({ individual: "nuwa" });
 
 // 类型化命名空间 API — 9 个命名空间
 await rx.society.born({ id: "alice", content: "Feature: Alice\n  一名前端工程师。" });
@@ -204,19 +204,20 @@ const { tools, instructions } = rx.protocol;
 
 `createRoleX()` 返回 `RoleXBuilder` — 同步构建器，延迟初始化。首次异步调用触发初始化（genesis 原型、世界引导）。
 
-**9 个类型化命名空间：**
+**7 个类型化命名空间 + 2 个世界级方法：**
 
-| 命名空间 | 用途 |
-|---------|------|
+| API | 用途 |
+|-----|------|
+| `rx.individual` | 激活个体 — 返回有状态的 Role |
 | `rx.society` | 个体与组织 — born, retire, teach, train, found, dissolve |
 | `rx.org` | 成员与治理 — charter, hire, fire, establish, abolish |
 | `rx.position` | 职位与职责 — charge, require, appoint, dismiss |
 | `rx.project` | 项目管理 — scope, milestone, deliver, wiki |
 | `rx.product` | 产品生命周期 — strategy, spec, release, channel |
-| `rx.survey` | 世界查询 — 列出所有实体 |
 | `rx.issue` | 议题追踪 — publish, comment, assign, label |
 | `rx.resource` | 资源管理 — add, push, pull, search |
-| `rx.role` | 角色操作 — activate, inspect, survey |
+| `rx.inspect()` | 查看任意节点的完整状态 |
+| `rx.survey()` | 列出个体、组织、职位 |
 
 **统一调度：**
 

apps/mcp-server/src/index.ts

@@ -89,27 +89,20 @@ type ToolExecutor = (params: Record<string, unknown>) => Promise<string>;
 
 const executors: Record<string, ToolExecutor> = {
   async inspect({ id }) {
-    return await rolex.role.inspect({ id: id as string });
+    return await rolex.inspect({ id: id as string });
   },
 
   async survey({ type }) {
-    const response = await rolex.rpc({
-      jsonrpc: "2.0",
-      method: "survey",
-      params: type ? { type: type as string } : {},
-      id: null,
-    });
-    if (response.error) throw new Error(response.error.message);
-    return response.result as string;
+    return await rolex.survey(type ? { type: type as string } : undefined);
   },
 
   async activate({ roleId }) {
     try {
-      const role = await rolex.role.activate({ individual: roleId as string });
+      const role = await rolex.individual.activate({ individual: roleId as string });
       state.role = role;
       return await role.project();
     } catch {
-      const all = await rolex.survey.list();
+      const all = await rolex.survey();
       throw new Error(
         `"${roleId}" not found. Available:\n\n${JSON.stringify(all)}\n\nTry again with the correct id or alias.`
       );

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

@@ -31,7 +31,7 @@ describe("requireRole", () => {
 
   it("returns role after activation", async () => {
     await rolex.society.born({ content: "Feature: Sean", id: "sean" });
-    const role = await rolex.role.activate({ individual: "sean" });
+    const role = await rolex.individual.activate({ individual: "sean" });
     state.role = role;
     expect(state.requireRole()).toBe(role);
     expect(state.requireRole().id).toBe("sean");
@@ -81,7 +81,7 @@ describe("render", () => {
 
   it("Role methods return rendered 3-layer output", async () => {
     await rolex.society.born({ content: "Feature: Sean", id: "sean" });
-    const role = await rolex.role.activate({ individual: "sean" });
+    const role = await rolex.individual.activate({ individual: "sean" });
 
     const output = await role.want("Feature: Test", "test-goal");
     // Layer 1: Status
@@ -100,7 +100,7 @@ describe("render", () => {
 describe("full execution flow", () => {
   it("completes want → plan → todo → finish → reflect → realize through Role API", async () => {
     await rolex.society.born({ content: "Feature: Sean", id: "sean" });
-    const role = await rolex.role.activate({ individual: "sean" });
+    const role = await rolex.individual.activate({ individual: "sean" });
     state.role = role;
 
     // Want
@@ -153,7 +153,7 @@ describe("full execution flow", () => {
 describe("focus", () => {
   it("switches focused goal via Role", async () => {
     await rolex.society.born({ content: "Feature: Sean", id: "sean" });
-    const role = await rolex.role.activate({ individual: "sean" });
+    const role = await rolex.individual.activate({ individual: "sean" });
     state.role = role;
 
     await role.want("Feature: Goal A", "goal-a");
@@ -175,7 +175,7 @@ describe("focus", () => {
 describe("selective cognition", () => {
   it("tracks multiple encounters, reflect consumes selectively", async () => {
     await rolex.society.born({ content: "Feature: Sean", id: "sean" });
-    const role = await rolex.role.activate({ individual: "sean" });
+    const role = await rolex.individual.activate({ individual: "sean" });
     state.role = role;
 
     await role.want("Feature: Auth", "auth");

bdd/steps/context.steps.ts

@@ -66,7 +66,7 @@ Given("no persisted context exists", async function (this: BddWorld) {
 When("I activate {string}", async function (this: BddWorld, name: string) {
   try {
     this.error = undefined;
-    this.role = await this.rolex!.role.activate({ individual: name });
+    this.role = await this.rolex!.individual.activate({ individual: name });
   } catch (e) {
     this.error = e as Error;
     this.role = undefined;

bdd/steps/direct.steps.ts

@@ -139,13 +139,25 @@ Then("it should fail", function (this: BddWorld) {
 // ===== Entity existence assertions =====
 
 Then("individual {string} should exist", async function (this: BddWorld, id: string) {
-  const result = await this.rolex!.survey.list({ type: "individual" });
+  const response = await this.rolex!.rpc({
+    jsonrpc: "2.0",
+    method: "survey.list",
+    params: { type: "individual" },
+    id: null,
+  });
+  const result = response.result as any;
   const ids = (result.state.children ?? []).map((c: any) => c.id);
   assert.ok(ids.includes(id), `Individual "${id}" not found in survey: ${JSON.stringify(ids)}`);
 });
 
 Then("organization {string} should exist", async function (this: BddWorld, id: string) {
-  const result = await this.rolex!.survey.list({ type: "organization" });
+  const response = await this.rolex!.rpc({
+    jsonrpc: "2.0",
+    method: "survey.list",
+    params: { type: "organization" },
+    id: null,
+  });
+  const result = response.result as any;
   const ids = (result.state.children ?? []).map((c: any) => c.id);
   assert.ok(ids.includes(id), `Organization "${id}" not found in survey: ${JSON.stringify(ids)}`);
 });

bdd/steps/isolation.steps.ts

@@ -15,7 +15,7 @@ Given(
   async function (this: BddWorld, id: string, goalId: string) {
     await this.rolex!.society.born({ content: `Feature: ${id}`, id });
     // Create goal through activate + want
-    const role = await this.rolex!.role.activate({ individual: id });
+    const role = await this.rolex!.individual.activate({ individual: id });
     await role.want(`Feature: ${goalId}`, goalId);
   }
 );
@@ -62,7 +62,7 @@ Then(
   "{string} should be under individual {string}",
   async function (this: BddWorld, nodeId: string, individualId: string) {
     // Use rendered project output to check node presence
-    const role = await this.rolex!.role.activate({ individual: individualId });
+    const role = await this.rolex!.individual.activate({ individual: individualId });
     const output = await role.project();
     assert.ok(
       output.includes(`(${nodeId})`),
@@ -74,7 +74,7 @@ Then(
 Then(
   "{string} should not be under individual {string}",
   async function (this: BddWorld, nodeId: string, individualId: string) {
-    const role = await this.rolex!.role.activate({ individual: individualId });
+    const role = await this.rolex!.individual.activate({ individual: individualId });
     const output = await role.project();
     assert.ok(
       !output.includes(`(${nodeId})`),
@@ -95,7 +95,7 @@ When("I restore role {string} from KV", async function (this: BddWorld, id: stri
   await this.newSession();
   try {
     this.error = undefined;
-    this.role = await this.rolex!.role.activate({ individual: id });
+    this.role = await this.rolex!.individual.activate({ individual: id });
   } catch (e) {
     this.error = e as Error;
   }
@@ -107,7 +107,7 @@ let firstRole: Role | undefined;
 
 When("I activate role {string} again", async function (this: BddWorld, id: string) {
   firstRole = this.role;
-  this.role = await this.rolex!.role.activate({ individual: id });
+  this.role = await this.rolex!.individual.activate({ individual: id });
 });
 
 Then("both activations should return the same Role instance", function (this: BddWorld) {
@@ -127,7 +127,7 @@ Then("I should receive a Role with id {string}", function (this: BddWorld, id: s
 When("I try to activate role {string}", async function (this: BddWorld, id: string) {
   try {
     this.error = undefined;
-    this.role = await this.rolex!.role.activate({ individual: id });
+    this.role = await this.rolex!.individual.activate({ individual: id });
   } catch (e) {
     this.error = e as Error;
     this.role = undefined;
@@ -147,7 +147,7 @@ Then("it should fail with {string}", function (this: BddWorld, message: string)
 Then(
   "role {string} should contain node {string}",
   async function (this: BddWorld, roleId: string, nodeId: string) {
-    const role = await this.rolex!.role.activate({ individual: roleId });
+    const role = await this.rolex!.individual.activate({ individual: roleId });
     const output = await role.project();
     assert.ok(output.includes(`(${nodeId})`), `Node "${nodeId}" not found in role "${roleId}"`);
   }

bdd/steps/role.steps.ts

@@ -14,7 +14,7 @@ import type { BddWorld } from "../support/world";
 // ===== Activate =====
 
 Given("I activate role {string}", async function (this: BddWorld, id: string) {
-  this.role = await this.rolex!.role.activate({ individual: id });
+  this.role = await this.rolex!.individual.activate({ individual: id });
 });
 
 // ===== Execution =====

bdd/steps/serialization.steps.ts

@@ -27,7 +27,7 @@ When(
     assert.ok(this.roleSnapshot, "No snapshot captured");
     // Simulate restore: new session + activate (which restores from persisted context)
     await this.newSession();
-    this.role = await this.rolex!.role.activate({ individual: this.roleSnapshot.id });
+    this.role = await this.rolex!.individual.activate({ individual: this.roleSnapshot.id });
   }
 );
 

packages/core/src/builder.ts

@@ -3,32 +3,30 @@
  *
  * Usage:
  *   const rx = createBuilder({ platform, renderer });
- *   const role = await rx.role.activate({ individual: "sean" });
+ *   const role = await rx.individual.activate({ individual: "sean" });
  *   await rx.society.born({ id: "alice", content: "Feature: Alice" });
  */
 
 import type {
   Caller,
+  IndividualNamespace,
   IssueNamespace,
   OrgNamespace,
   PositionNamespace,
   ProductNamespace,
   ProjectNamespace,
   ResourceNamespace,
-  RoleNamespace,
   SocietyNamespace,
-  SurveyNamespace,
 } from "./namespaces.js";
 import {
+  createIndividualNamespace,
   createIssueNamespace,
   createOrgNamespace,
   createPositionNamespace,
   createProductNamespace,
   createProjectNamespace,
   createResourceNamespace,
-  createRoleNamespace,
   createSocietyNamespace,
-  createSurveyNamespace,
 } from "./namespaces.js";
 import type { Platform, PrototypeData } from "./platform.js";
 import type { Renderer } from "./renderer.js";
@@ -47,8 +45,8 @@ export interface RoleXInternal {
 export interface RoleXBuilder {
   /** Society-level operations — born, retire, crown, teach, train, found, dissolve. */
   readonly society: SocietyNamespace;
-  /** Role management — activate, inspect. */
-  readonly role: RoleNamespace;
+  /** Individual operations — activate. */
+  readonly individual: IndividualNamespace;
   /** Organization operations — charter, hire, fire, admin, launch, establish. */
   readonly org: OrgNamespace;
   /** Position operations — charge, require, appoint, dismiss. */
@@ -57,13 +55,16 @@ export interface RoleXBuilder {
   readonly project: ProjectNamespace;
   /** Product operations — strategy, spec, release, channel, own. */
   readonly product: ProductNamespace;
-  /** Survey — world-level queries. */
-  readonly survey: SurveyNamespace;
   /** Issue tracking integration. */
   readonly issue: IssueNamespace;
   /** Resource management integration. */
   readonly resource: ResourceNamespace;
 
+  /** Inspect any node's full state — world-level observation. */
+  inspect(params: { id: string }): Promise<string>;
+  /** Survey the world — list individuals, organizations, positions. */
+  survey(params?: { type?: string }): Promise<string>;
+
   /** Tool schemas + world instructions — the unified contract for any channel adapter. */
   readonly protocol: Protocol;
 
@@ -139,21 +140,20 @@ export function createBuilder(config: BuilderConfig): RoleXBuilder {
 
   // Create namespace instances (synchronous — they're just wrappers)
   const _society = createSocietyNamespace(call);
-  const _role = createRoleNamespace(call);
+  const _individual = createIndividualNamespace(call);
   const _org = createOrgNamespace(call);
   const _position = createPositionNamespace(call);
   const _project = createProjectNamespace(call);
   const _product = createProductNamespace(call);
-  const _survey = createSurveyNamespace(call);
   const _issue = createIssueNamespace(call);
   const _resource = createResourceNamespace(call);
 
   return {
     get society() {
       return _society;
     },
-    get role() {
-      return _role;
+    get individual() {
+      return _individual;
     },
     get org() {
       return _org;
@@ -167,16 +167,21 @@ export function createBuilder(config: BuilderConfig): RoleXBuilder {
     get product() {
       return _product;
     },
-    get survey() {
-      return _survey;
-    },
     get issue() {
       return _issue;
     },
     get resource() {
       return _resource;
     },
 
+    async inspect({ id }: { id: string }) {
+      return call("inspect", { id });
+    },
+
+    async survey(params?: { type?: string }) {
+      return call("survey", params);
+    },
+
     protocol: defaultProtocol,
 
     async rpc<T>(request: JsonRpcRequest): Promise<JsonRpcResponse<T>> {