@rolexjs/core 1.5.0-dev-20260310031643 → 1.5.0-dev-20260312083443

package/dist/index.d.ts

@@ -87,8 +87,6 @@ interface Platform {
     readonly issuexProvider?: IssueXProvider;
     /** Initializer — bootstrap the world on first run. */
     readonly initializer?: Initializer;
-    /** Prototype data to apply on genesis. */
-    readonly prototypes?: readonly PrototypeData[];
 }
 
 declare const society: _rolexjs_system.Structure;
@@ -455,10 +453,12 @@ declare class RoleXService implements RoleX {
     private past;
     /** Cached Role instances — one per individual. */
     private readonly roles;
+    /** Expose commands for the RPC handler. */
+    get commandMap(): Commands;
     /** Permission registry — maps relation names to permissions. */
     private readonly permissions;
     private constructor();
-    static create(platform: Platform, renderer: Renderer): Promise<RoleXService>;
+    static create(platform: Platform, renderer: Renderer, prototypes?: readonly PrototypeData[]): Promise<RoleXService>;
     private init;
     activate(individual: string): Promise<Role>;
     private findOrAutoBorn;
@@ -473,6 +473,440 @@ declare class RoleXService implements RoleX {
     private find;
 }
 
+/**
+ * JSON-RPC 2.0 types and handler for RoleX.
+ *
+ * The RpcHandler is the single dispatch point for all RoleX operations.
+ * It accepts JSON-RPC 2.0 requests and delegates to the command layer
+ * via toArgs() for named-to-positional argument conversion.
+ */
+
+interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+    id?: string | number | null;
+}
+interface JsonRpcResponse<T = unknown> {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: T;
+    error?: JsonRpcError;
+}
+interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+interface RpcHandlerDeps {
+    commands: Commands;
+    /** Custom method handlers for methods not in the commands map (e.g. activate, inspect, survey). */
+    methods?: Record<string, (params: Record<string, unknown>) => Promise<unknown>>;
+}
+declare class RpcHandler {
+    private commands;
+    private methods;
+    constructor(deps: RpcHandlerDeps);
+    handle<T = unknown>(request: JsonRpcRequest): Promise<JsonRpcResponse<T>>;
+}
+
+/**
+ * Namespace interfaces and factories for RoleX builder API.
+ *
+ * Each namespace is a typed wrapper over the JSON-RPC caller function.
+ * Methods accept named parameter objects (matching JSON-RPC params)
+ * and return typed results.
+ */
+
+type Caller = (method: string, params?: Record<string, unknown>) => Promise<any>;
+interface SocietyNamespace {
+    born(params: {
+        content?: string;
+        id: string;
+        alias?: string[];
+    }): Promise<CommandResult>;
+    retire(params: {
+        individual: string;
+    }): Promise<CommandResult>;
+    die(params: {
+        individual: string;
+    }): Promise<CommandResult>;
+    rehire(params: {
+        individual: string;
+    }): Promise<CommandResult>;
+    teach(params: {
+        individual: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    train(params: {
+        individual: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    found(params: {
+        content?: string;
+        id: string;
+        alias?: string[];
+        admin?: string;
+    }): Promise<CommandResult>;
+    dissolve(params: {
+        org: string;
+    }): Promise<CommandResult>;
+    crown(params: {
+        individual: string;
+    }): Promise<CommandResult>;
+    uncrown(params: {
+        individual: string;
+    }): Promise<CommandResult>;
+}
+interface RoleNamespace {
+    activate(params: {
+        individual: string;
+    }): Promise<Role>;
+    inspect(params: {
+        id: string;
+    }): Promise<string>;
+    survey(params?: {
+        type?: string;
+    }): Promise<string>;
+}
+interface OrgNamespace {
+    charter(params: {
+        org: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    hire(params: {
+        org: string;
+        individual: string;
+    }): Promise<CommandResult>;
+    fire(params: {
+        org: string;
+        individual: string;
+    }): Promise<CommandResult>;
+    admin(params: {
+        org: string;
+        individual: string;
+    }): Promise<CommandResult>;
+    unadmin(params: {
+        org: string;
+        individual: string;
+    }): Promise<CommandResult>;
+    launch(params: {
+        content?: string;
+        id: string;
+        alias?: string[];
+        org?: string;
+        maintainer?: string;
+    }): Promise<CommandResult>;
+    archive(params: {
+        project: string;
+    }): Promise<CommandResult>;
+    establish(params: {
+        content?: string;
+        id: string;
+        alias?: string[];
+    }): Promise<CommandResult>;
+    abolish(params: {
+        position: string;
+    }): Promise<CommandResult>;
+}
+interface PositionNamespace {
+    charge(params: {
+        position: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    require(params: {
+        position: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    appoint(params: {
+        position: string;
+        individual: string;
+    }): Promise<CommandResult>;
+    dismiss(params: {
+        position: string;
+        individual: string;
+    }): Promise<CommandResult>;
+}
+interface ProjectNamespace {
+    scope(params: {
+        project: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    milestone(params: {
+        project: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    achieve(params: {
+        milestone: string;
+    }): Promise<CommandResult>;
+    enroll(params: {
+        project: string;
+        individual: string;
+    }): Promise<CommandResult>;
+    remove(params: {
+        project: string;
+        individual: string;
+    }): Promise<CommandResult>;
+    deliver(params: {
+        project: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    wiki(params: {
+        project: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    produce(params: {
+        project: string;
+        content?: string;
+        id: string;
+        alias?: string[];
+        owner?: string;
+    }): Promise<CommandResult>;
+    maintain(params: {
+        project: string;
+        individual: string;
+    }): Promise<CommandResult>;
+    unmaintain(params: {
+        project: string;
+        individual: string;
+    }): Promise<CommandResult>;
+}
+interface ProductNamespace {
+    strategy(params: {
+        product: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    spec(params: {
+        product: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    release(params: {
+        product: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    channel(params: {
+        product: string;
+        content: string;
+        id: string;
+    }): Promise<CommandResult>;
+    own(params: {
+        product: string;
+        individual: string;
+    }): Promise<CommandResult>;
+    disown(params: {
+        product: string;
+        individual: string;
+    }): Promise<CommandResult>;
+    deprecate(params: {
+        product: string;
+    }): Promise<CommandResult>;
+}
+interface CensusNamespace {
+    list(params?: {
+        type?: string;
+    }): Promise<CommandResult>;
+}
+interface IssueNamespace {
+    publish(params: {
+        title: string;
+        body: string;
+        author: string;
+        assignee?: string;
+    }): Promise<Issue>;
+    get(params: {
+        number: number;
+    }): Promise<Issue | null>;
+    list(params?: {
+        status?: string;
+        author?: string;
+        assignee?: string;
+        label?: string;
+    }): Promise<Issue[]>;
+    update(params: {
+        number: number;
+        title?: string;
+        body?: string;
+        assignee?: string;
+    }): Promise<Issue>;
+    close(params: {
+        number: number;
+    }): Promise<Issue>;
+    reopen(params: {
+        number: number;
+    }): Promise<Issue>;
+    assign(params: {
+        number: number;
+        assignee: string;
+    }): Promise<Issue>;
+    comment(params: {
+        number: number;
+        body: string;
+        author: string;
+    }): Promise<Comment>;
+    comments(params: {
+        number: number;
+    }): Promise<Comment[]>;
+    label(params: {
+        number: number;
+        label: string;
+    }): Promise<Issue | null>;
+    unlabel(params: {
+        number: number;
+        label: string;
+    }): Promise<Issue | null>;
+}
+interface ResourceNamespace {
+    add(params: {
+        path: string;
+    }): Promise<Resource>;
+    search(params?: {
+        query?: string;
+    }): Promise<string[]>;
+    has(params: {
+        locator: string;
+    }): Promise<boolean>;
+    info(params: {
+        locator: string;
+    }): Promise<Resource>;
+    remove(params: {
+        locator: string;
+    }): Promise<undefined>;
+    push(params: {
+        locator: string;
+        registry?: string;
+    }): Promise<RXM>;
+    pull(params: {
+        locator: string;
+        registry?: string;
+    }): Promise<undefined>;
+    clearCache(params?: {
+        registry?: string;
+    }): Promise<undefined>;
+}
+
+/**
+ * Schema types for RoleX instruction definitions.
+ *
+ * These types define the structure of every RoleX operation:
+ * parameter types, descriptions, and positional arg ordering.
+ */
+/** Supported parameter types for instruction definitions. */
+type ParamType = "string" | "number" | "gherkin" | "string[]" | "record";
+/** Definition of a single parameter in an instruction. */
+interface ParamDef {
+    type: ParamType;
+    required: boolean;
+    description: string;
+}
+/**
+ * A single positional argument entry.
+ *
+ * - `string` — simple lookup: `args[name]`
+ * - `{ pack: [...] }` — collect named args into an options object;
+ *   returns `undefined` if all values are absent.
+ */
+type ArgEntry = string | {
+    pack: readonly string[];
+};
+/** Full definition of a RoleX instruction (one namespace.method). */
+interface InstructionDef {
+    namespace: string;
+    method: string;
+    /** Parameter definitions — keyed by param name, used for MCP/CLI schema generation. */
+    params: Record<string, ParamDef>;
+    /** Positional argument order — maps named args to method call positions. */
+    args: readonly ArgEntry[];
+}
+/** RoleX tool definition — schema for a top-level tool (activate, want, use, etc.). */
+interface ToolDef {
+    /** Tool name (e.g. "activate", "use"). */
+    name: string;
+    /** Full Gherkin description of the tool's behavior. */
+    description: string;
+    /** Parameter definitions — keyed by param name. */
+    params: Record<string, ParamDef>;
+}
+
+/**
+ * RoleX tool definitions — the single source of truth for all tool schemas.
+ *
+ * Channel-agnostic: MCP, CLI, REST, A2A each convert to their own format.
+ * Each ToolDef is self-contained: name + description + params.
+ */
+
+/**
+ * Protocol — the complete interface contract for channel adapters.
+ *
+ * Any adapter (MCP, CLI, REST, A2A) only needs this object
+ * to know what tools exist and what instructions to present.
+ */
+interface Protocol {
+    /** All tool definitions — self-contained with description + parameter schemas. */
+    tools: ToolDef[];
+    /** World-level instructions — the cognitive framework for AI roles. */
+    instructions: string;
+}
+/** The protocol instance — single source of truth for all channel adapters. */
+declare const protocol: Protocol;
+
+/**
+ * RoleX Builder — synchronous factory with lazy initialization.
+ *
+ * Usage:
+ *   const rx = createBuilder({ platform, renderer });
+ *   const role = await rx.role.activate({ individual: "sean" });
+ *   await rx.society.born({ id: "alice", content: "Feature: Alice" });
+ */
+
+interface RoleXInternal {
+    service: RoleXService;
+}
+interface RoleXBuilder {
+    /** Society-level operations — born, retire, crown, teach, train, found, dissolve. */
+    readonly society: SocietyNamespace;
+    /** Role management — activate, inspect, survey. */
+    readonly role: RoleNamespace;
+    /** Organization operations — charter, hire, fire, admin, launch, establish. */
+    readonly org: OrgNamespace;
+    /** Position operations — charge, require, appoint, dismiss. */
+    readonly position: PositionNamespace;
+    /** Project operations — scope, milestone, enroll, deliver, produce. */
+    readonly project: ProjectNamespace;
+    /** Product operations — strategy, spec, release, channel, own. */
+    readonly product: ProductNamespace;
+    /** Census — world-level queries. */
+    readonly census: CensusNamespace;
+    /** Issue tracking integration. */
+    readonly issue: IssueNamespace;
+    /** Resource management integration. */
+    readonly resource: ResourceNamespace;
+    /** Tool schemas + world instructions — the unified contract for any channel adapter. */
+    readonly protocol: Protocol;
+    /** Universal JSON-RPC 2.0 dispatch. */
+    rpc<T = unknown>(request: JsonRpcRequest): Promise<JsonRpcResponse<T>>;
+    /** Internal access for testing — not part of the public contract. */
+    _internal(): Promise<RoleXInternal>;
+}
+interface BuilderConfig {
+    platform: Platform;
+    renderer: Renderer;
+    /** Built-in prototypes to apply on initialization (e.g. genesis). */
+    prototypes?: readonly PrototypeData[];
+}
+declare function createBuilder(config: BuilderConfig): RoleXBuilder;
+
 /**
  * Find — unified node lookup with priority-based disambiguation.
  *
@@ -549,47 +983,6 @@ declare const directives: Record<string, Record<string, string>>;
  */
 declare function toArgs(op: string, args: Record<string, unknown>): unknown[];
 
-/**
- * Schema types for RoleX instruction definitions.
- *
- * These types define the structure of every RoleX operation:
- * parameter types, descriptions, and positional arg ordering.
- */
-/** Supported parameter types for instruction definitions. */
-type ParamType = "string" | "number" | "gherkin" | "string[]" | "record";
-/** Definition of a single parameter in an instruction. */
-interface ParamDef {
-    type: ParamType;
-    required: boolean;
-    description: string;
-}
-/**
- * A single positional argument entry.
- *
- * - `string` — simple lookup: `args[name]`
- * - `{ pack: [...] }` — collect named args into an options object;
- *   returns `undefined` if all values are absent.
- */
-type ArgEntry = string | {
-    pack: readonly string[];
-};
-/** Full definition of a RoleX instruction (one namespace.method). */
-interface InstructionDef {
-    namespace: string;
-    method: string;
-    /** Parameter definitions — keyed by param name, used for MCP/CLI schema generation. */
-    params: Record<string, ParamDef>;
-    /** Positional argument order — maps named args to method call positions. */
-    args: readonly ArgEntry[];
-}
-/** RoleX tool definition — schema for a top-level tool (activate, want, use, etc.). */
-interface ToolDef {
-    /** Tool name (e.g. "activate", "use"). */
-    name: string;
-    /** Parameter definitions — keyed by param name. */
-    params: Record<string, ParamDef>;
-}
-
 /**
  * Instruction set — schema definitions for all RoleX operations.
  *
@@ -598,27 +991,4 @@ interface ToolDef {
 
 declare const instructions: Record<string, InstructionDef>;
 
-/**
- * RoleX tool definitions — the single source of truth for all tool schemas.
- *
- * Channel-agnostic: MCP, CLI, REST, A2A each convert to their own format.
- * Description for each tool comes from descriptions/processes via detail().
- * This file only defines the parameter schema.
- */
-
-/**
- * Protocol — the complete interface contract for channel adapters.
- *
- * Any adapter (MCP, CLI, REST, A2A) only needs this object
- * to know what tools exist and what instructions to present.
- */
-interface Protocol {
-    /** All tool definitions with parameter schemas. */
-    tools: ToolDef[];
-    /** World-level instructions — the cognitive framework for AI roles. */
-    instructions: string;
-}
-/** The protocol instance — single source of truth for all channel adapters. */
-declare const protocol: Protocol;
-
-export { type ApplyResult, type ArgEntry, type CommandContext, type CommandResult, type CommandResultMap, type Commands, type ContextData, type InstructionDef, type Migration, type MigrationRecord, type ParamDef, type ParamType, type Platform, type Protocol, type PrototypeData, type PrototypeRepository, type Renderer, RendererRouter, Role, type RoleDeps, type RoleSnapshot, type RoleX, type RoleXRepository, RoleXService, type ToolDef, abandon, abolish, activate, applyPrototype, appoint, archive, background, born, channel, channelProduct, charge, charter, charterOrg, complete, createCommands, deliverProject, deliverable, deprecate, die, directives, dismiss, disownProduct, dissolve, duty, encounter, enroll, establish, experience, findInState, finish, fire, found, goal, hire, identity, individual, instructions, launch, master, milestone, milestoneProject, mindset, organization, ownProduct, past, plan, planGoal, position, principle, procedure, processes, produceProject, product, project, protocol, realize, reflect, rehire, release, releaseProduct, removeParticipant, requirement, retire, scope, scopeProject, society, spec, specProduct, strategy, strategyProduct, task, toArgs, todo, tone, want, wiki, wikiProject, world };
+export { type ApplyResult, type ArgEntry, type BuilderConfig, type Caller, type CensusNamespace, type CommandContext, type CommandResult, type CommandResultMap, type Commands, type ContextData, type InstructionDef, type IssueNamespace, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, type Migration, type MigrationRecord, type OrgNamespace, type ParamDef, type ParamType, type Platform, type PositionNamespace, type ProductNamespace, type ProjectNamespace, type Protocol, type PrototypeData, type PrototypeRepository, type Renderer, RendererRouter, type ResourceNamespace, Role, type RoleDeps, type RoleNamespace, type RoleSnapshot, type RoleX, type RoleXBuilder, type RoleXInternal, type RoleXRepository, RoleXService, RpcHandler, type SocietyNamespace, type ToolDef, abandon, abolish, activate, applyPrototype, appoint, archive, background, born, channel, channelProduct, charge, charter, charterOrg, complete, createBuilder, createCommands, deliverProject, deliverable, deprecate, die, directives, dismiss, disownProduct, dissolve, duty, encounter, enroll, establish, experience, findInState, finish, fire, found, goal, hire, identity, individual, instructions, launch, master, milestone, milestoneProject, mindset, organization, ownProduct, past, plan, planGoal, position, principle, procedure, processes, produceProject, product, project, protocol, realize, reflect, rehire, release, releaseProduct, removeParticipant, requirement, retire, scope, scopeProject, society, spec, specProduct, strategy, strategyProduct, task, toArgs, todo, tone, want, wiki, wikiProject, world };