@rolexjs/core 1.4.0-dev-20260305032702 → 1.4.0-dev-20260305092016

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 import * as _rolexjs_system from '@rolexjs/system';
-import { Runtime, Initializer } from '@rolexjs/system';
+import { Runtime, Initializer, Structure, State } from '@rolexjs/system';
 export { Create, GraphOp, Link, Process, Relation, Remove, Runtime, State, Structure, Transform, Unlink, create, createRuntime, link, process, relation, remove, structure, transform, unlink } from '@rolexjs/system';
 import { IssueXProvider } from '@issuexjs/core';
 import { ResourceXProvider, CustomExecutor } from '@resourcexjs/core';
+import { IssueX, Issue, Comment } from 'issuexjs';
+import { ResourceX, Resource, RXM } from 'resourcexjs';
 
 /**
  * Platform — external integration point for RoleX.
@@ -114,6 +116,7 @@ declare const milestone: _rolexjs_system.Structure;
 declare const deliverable: _rolexjs_system.Structure;
 declare const wiki: _rolexjs_system.Structure;
 
+declare const activate: _rolexjs_system.Process;
 declare const want: _rolexjs_system.Process;
 declare const planGoal: _rolexjs_system.Process;
 declare const todo: _rolexjs_system.Process;
@@ -150,6 +153,397 @@ declare const dissolve: _rolexjs_system.Process;
 declare const abolish: _rolexjs_system.Process;
 declare const rehire: _rolexjs_system.Process;
 
-declare const activate: _rolexjs_system.Process;
+/**
+ * Commands — platform-agnostic command implementations.
+ *
+ * Every RoleX command is a pure function of (Runtime, args) → CommandResult.
+ * No platform-specific code — all I/O goes through injected interfaces.
+ *
+ * Usage:
+ *   const commands = createCommands({ rt, society, past, resolve, find, resourcex });
+ *   const result = commands["individual.born"]("Feature: Sean", "sean");
+ */
+
+interface CommandResult {
+    state: State;
+    process: string;
+}
+interface CommandContext {
+    rt: Runtime;
+    society: Structure;
+    past: Structure;
+    resolve(id: string): Structure | Promise<Structure>;
+    find(id: string): (Structure | null) | Promise<Structure | null>;
+    resourcex?: ResourceX;
+    issuex?: IssueX;
+    prototype?: PrototypeRepository;
+    direct?(locator: string, args?: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * CommandResultMap — typed return type for every command.
+ *
+ * This is the source of truth for what each command returns.
+ * Renderer and consumers use this to know the shape of each result.
+ */
+interface CommandResultMap {
+    "individual.born": CommandResult;
+    "individual.retire": CommandResult;
+    "individual.die": CommandResult;
+    "individual.rehire": CommandResult;
+    "individual.teach": CommandResult;
+    "individual.train": CommandResult;
+    "role.focus": CommandResult;
+    "role.want": CommandResult;
+    "role.plan": CommandResult;
+    "role.todo": CommandResult;
+    "role.finish": CommandResult;
+    "role.complete": CommandResult;
+    "role.abandon": CommandResult;
+    "role.reflect": CommandResult;
+    "role.realize": CommandResult;
+    "role.master": CommandResult;
+    "role.forget": CommandResult;
+    "role.skill": string;
+    "project.launch": CommandResult;
+    "project.scope": CommandResult;
+    "project.milestone": CommandResult;
+    "project.achieve": CommandResult;
+    "project.enroll": CommandResult;
+    "project.remove": CommandResult;
+    "project.deliver": CommandResult;
+    "project.wiki": CommandResult;
+    "project.archive": CommandResult;
+    "org.found": CommandResult;
+    "org.charter": CommandResult;
+    "org.dissolve": CommandResult;
+    "org.hire": CommandResult;
+    "org.fire": CommandResult;
+    "position.establish": CommandResult;
+    "position.charge": CommandResult;
+    "position.require": CommandResult;
+    "position.abolish": CommandResult;
+    "position.appoint": CommandResult;
+    "position.dismiss": CommandResult;
+    "census.list": CommandResult;
+    "issue.publish": Issue;
+    "issue.get": Issue | null;
+    "issue.list": Issue[];
+    "issue.update": Issue;
+    "issue.close": Issue;
+    "issue.reopen": Issue;
+    "issue.assign": Issue;
+    "issue.comment": Comment;
+    "issue.comments": Comment[];
+    "issue.label": Issue | null;
+    "issue.unlabel": Issue | null;
+    "resource.add": Resource;
+    "resource.search": string[];
+    "resource.has": boolean;
+    "resource.info": Resource;
+    "resource.remove": undefined;
+    "resource.push": RXM;
+    "resource.pull": undefined;
+    "resource.clearCache": undefined;
+}
+type Commands = Record<string, (...args: any[]) => any>;
+declare function createCommands(ctx: CommandContext): Commands;
+
+/**
+ * Renderer — framework for rendering command results.
+ *
+ * Renderer interface and RendererRouter live here in prototype
+ * because this layer owns all command types and structures.
+ * Concrete renderers are registered by the upper layer (rolexjs).
+ */
+
+/** Renders a command result into a string (typically Markdown). */
+interface Renderer {
+    render(command: string, result: CommandResult): string;
+}
+/**
+ * RendererRouter — routes commands to namespace-specific renderers.
+ *
+ * Registered renderers handle their namespace (e.g. "role" handles "role.want").
+ * Unregistered commands fall through to the default renderer (JSON serialization).
+ */
+declare class RendererRouter implements Renderer {
+    private readonly renderers;
+    /** Register a renderer for a command namespace. */
+    register(namespace: string, renderer: Renderer): this;
+    /** Route a command to the appropriate renderer. */
+    render(command: string, result: CommandResult): string;
+}
+
+/**
+ * Role — rich domain model (充血模型) for an individual.
+ *
+ * Role is a self-contained operation domain that holds:
+ *   - State projection (read cache from graph)
+ *   - Cursors (focusedGoalId, focusedPlanId)
+ *   - Cognitive registries (encounters, experiences)
+ *   - Domain behaviors (focus, want, plan, todo, finish, etc.)
+ *
+ * Design:
+ *   - Role = Actor State, RoleX = ActorSystem
+ *   - Ownership validation: hasNode() ensures isolation
+ *   - KV-serializable: snapshot() / restore()
+ *   - Single instance per individual
+ */
+
+/** Serializable role state for KV persistence. */
+interface RoleSnapshot {
+    id: string;
+    focusedGoalId: string | null;
+    focusedPlanId: string | null;
+    encounterIds: string[];
+    experienceIds: string[];
+}
+/** Internal dependencies injected by RoleX at activate time. */
+interface RoleDeps {
+    commands: Commands;
+    renderer: Renderer;
+    onSave(snapshot: RoleSnapshot): void | Promise<void>;
+    /** Direct execution — for `use` method. Provided by RoleXService. */
+    direct?<T>(locator: string, args?: Record<string, unknown>): Promise<T>;
+    /** Post-process `use` results (e.g., issue rendering). Provided by upper layer. */
+    transformUseResult?<T>(locator: string, result: T): Promise<T>;
+}
+declare class Role {
+    readonly id: string;
+    private focusedGoalId;
+    private focusedPlanId;
+    private readonly encounterIds;
+    private readonly experienceIds;
+    /** Set of all node ids under this individual — for ownership validation. */
+    private readonly nodeIds;
+    private deps;
+    constructor(id: string, deps: RoleDeps);
+    /** Populate from state projection. Builds nodeIds set + cognitive registries. */
+    hydrate(state: State): void;
+    private walkState;
+    private hasNode;
+    private requireOwnership;
+    private requireGoalId;
+    private requirePlanId;
+    private fmt;
+    private save;
+    /** Serialize to KV-compatible snapshot. */
+    snapshot(): RoleSnapshot;
+    /** Restore cursors and cognitive state from a snapshot. */
+    restore(snap: RoleSnapshot): void;
+    /** Project the individual's state tree (used after activate). */
+    project(): Promise<string>;
+    /** Focus: view or switch focused goal. Validates ownership. */
+    focus(goal?: string): Promise<string>;
+    /** Want: declare a goal under this individual. */
+    want(goal?: string, id?: string, alias?: readonly string[]): Promise<string>;
+    /** Plan: create a plan for the focused goal. */
+    plan(plan?: string, id?: string, after?: string, fallback?: string): Promise<string>;
+    /** Todo: add a task to the focused plan. */
+    todo(task?: string, id?: string, alias?: readonly string[]): Promise<string>;
+    /** Finish: complete a task, optionally record an encounter. */
+    finish(task: string, encounter?: string): Promise<string>;
+    /** Complete: close a plan as done, record encounter. */
+    complete(plan?: string, encounter?: string): Promise<string>;
+    /** Abandon: drop a plan, record encounter. */
+    abandon(plan?: string, encounter?: string): Promise<string>;
+    /** Reflect: consume encounters → experience. */
+    reflect(encounters: string[], experience?: string, id?: string): Promise<string>;
+    /** Realize: consume experiences → principle. */
+    realize(experiences: string[], principle?: string, id?: string): Promise<string>;
+    /** Master: create procedure, optionally consuming experiences. */
+    master(procedure: string, id?: string, experiences?: string[]): Promise<string>;
+    /** Forget: remove any node under this individual by id. */
+    forget(nodeId: string): Promise<string>;
+    /** Skill: load full skill content by locator. */
+    skill(locator: string): Promise<string>;
+    /** Use: subjective execution — `!ns.method` or ResourceX locator. */
+    use<T = unknown>(locator: string, args?: Record<string, unknown>): Promise<T>;
+    private cognitiveHint;
+}
+
+/**
+ * RoleXService — runtime orchestrator (internal).
+ *
+ * Wires Platform → Commands, manages Role lifecycle, handles ResourceX/IssueX.
+ * Not exposed publicly — consumed by the RoleX entry point.
+ *
+ * Key responsibilities:
+ *   - Initialize world roots (society, past)
+ *   - Create and cache Role instances (one per individual)
+ *   - Apply prototypes on first run
+ *   - Dispatch direct commands
+ */
+
+interface RoleX {
+    activate(individual: string): Promise<Role>;
+    direct<T = unknown>(locator: string, args?: Record<string, unknown>, options?: {
+        raw?: boolean;
+    }): Promise<T>;
+}
+declare class RoleXService implements RoleX {
+    private rt;
+    private commands;
+    private resourcex?;
+    private issuex?;
+    private repo;
+    private readonly initializer?;
+    private readonly renderer;
+    private readonly prototypes;
+    private society;
+    private past;
+    /** Cached Role instances — one per individual. */
+    private readonly roles;
+    private constructor();
+    static create(platform: Platform, renderer: Renderer): Promise<RoleXService>;
+    private init;
+    activate(individual: string): Promise<Role>;
+    private findOrAutoBorn;
+    private saveSnapshot;
+    private restoreSnapshot;
+    direct<T = unknown>(locator: string, args?: Record<string, unknown>, options?: {
+        raw?: boolean;
+    }): Promise<T>;
+    private find;
+}
+
+/**
+ * Find — unified node lookup with priority-based disambiguation.
+ *
+ * When multiple nodes share the same id (allowed after relaxing
+ * global uniqueness), prefer "addressable" nodes over internal metadata.
+ *
+ * Priority (lower = preferred):
+ *   0: individual, organization, position   — top-level entities
+ *   1: goal                                  — execution roots
+ *   2: plan, task                            — execution nodes
+ *   3: procedure, principle                  — individual knowledge
+ *   4: encounter, experience                 — cognition artifacts
+ *   5: identity, charter                     — structural definitions
+ *   6: duty, requirement, background, etc.   — internal metadata
+ */
+
+/**
+ * Find a node by id or alias in a state tree.
+ *
+ * When multiple nodes match, returns the one with the highest priority
+ * (top-level entities > execution nodes > knowledge > metadata).
+ */
+declare function findInState(state: State, target: string): Structure | null;
+
+/**
+ * applyPrototype — apply a prototype's migrations incrementally.
+ *
+ * Pure function: receives data + storage + executor, no framework coupling.
+ * Checks migration history, executes only unapplied migrations, records each.
+ */
+
+/** Result of applying a prototype. */
+interface ApplyResult {
+    prototypeId: string;
+    applied: number;
+    skipped: number;
+    upToDate: boolean;
+}
+/**
+ * Apply a prototype — execute unapplied migrations in version order.
+ *
+ * @param data - The prototype data structure with migrations
+ * @param repo - Storage layer for migration history
+ * @param direct - Executor for prototype instructions
+ */
+declare function applyPrototype(data: PrototypeData, repo: PrototypeRepository, direct: (op: string, args: Record<string, unknown>) => Promise<unknown>): Promise<ApplyResult>;
+
+declare const processes: Record<string, string>;
+declare const world: Record<string, string>;
+
+declare const directives: Record<string, Record<string, string>>;
+
+/**
+ * Dispatch — schema-driven argument mapping.
+ *
+ * Replaces the hand-written toArgs switch in rolex.ts with a single
+ * lookup against the instruction registry.
+ */
+/**
+ * Map named arguments to positional arguments for a given operation.
+ *
+ * @param op - Operation key in "namespace.method" format (e.g. "individual.born")
+ * @param args - Named arguments from the caller
+ * @returns Positional argument array matching the method signature
+ */
+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.
+ *
+ * Covers every namespace.method that can be dispatched through `use()`.
+ */
+
+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 ContextData, type Migration, type MigrationRecord, type Platform, type PrototypeData, type PrototypeRepository, type RoleXRepository, abandon, abolish, activate, appoint, archive, background, born, charge, charter, charterOrg, complete, deliverProject, deliverable, die, dismiss, dissolve, duty, encounter, enroll, establish, experience, finish, fire, found, goal, hire, identity, individual, launch, master, milestone, milestoneProject, mindset, organization, past, plan, planGoal, position, principle, procedure, project, realize, reflect, rehire, removeParticipant, requirement, retire, scope, scopeProject, society, task, todo, tone, want, wiki, wikiProject };
+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, charge, charter, charterOrg, complete, createCommands, deliverProject, deliverable, die, directives, dismiss, dissolve, duty, encounter, enroll, establish, experience, findInState, finish, fire, found, goal, hire, identity, individual, instructions, launch, master, milestone, milestoneProject, mindset, organization, past, plan, planGoal, position, principle, procedure, processes, project, protocol, realize, reflect, rehire, removeParticipant, requirement, retire, scope, scopeProject, society, task, toArgs, todo, tone, want, wiki, wikiProject, world };