@rolexjs/core 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -26,7 +26,7 @@ interface Scenario extends Scenario$1 {
  * A Gherkin Feature enriched with RDD semantics.
  */
 interface Feature extends Feature$1 {
-    readonly type: "persona" | "knowledge" | "experience" | "voice" | "goal" | "plan" | "task";
+    readonly type: "persona" | "knowledge" | "experience" | "voice" | "goal" | "plan" | "task" | "duty";
     readonly scenarios: Scenario[];
 }
 
@@ -107,6 +107,21 @@ interface Task extends Feature {
     readonly type: "task";
 }
 
+/**
+ * Duty — Responsibilities defined by a Position.
+ *
+ * A Duty IS-A Feature with type='duty'.
+ * Expressed as *.duty.feature files within a position directory.
+ * Injected into role identity when the role is on_duty.
+ */
+
+/**
+ * A duty (responsibility) assigned through a position.
+ */
+interface Duty extends Feature {
+    readonly type: "duty";
+}
+
 /**
  * Skill — Execution capability for a task.
  *
@@ -123,57 +138,131 @@ interface Skill {
     readonly reference: string;
 }
 
+/**
+ * states.ts — Role and Position state definitions.
+ *
+ * Role:     free → member → on_duty
+ * Position: vacant → filled
+ */
+type RoleState = "free" | "member" | "on_duty";
+type PositionState = "vacant" | "filled";
+/**
+ * Derive a role's state from assignment data.
+ */
+declare function getRoleState(assignment: {
+    org: string;
+    position?: string;
+} | null): RoleState;
+/**
+ * Derive a position's state from assignment data.
+ */
+declare function getPositionState(assignedRole: string | null): PositionState;
+
 /**
  * Platform — The abstraction layer for role storage.
  *
- * Defines how roles are loaded and persisted.
+ * Defines how roles, organizations, and positions are stored and managed.
  * LocalPlatform uses the filesystem (.rolex/ directories).
  * Future platforms could use databases, cloud storage, etc.
  *
- * All methods are stateless — role name is passed per call.
+ * Three-entity architecture:
+ *   Role         = WHO  (identity, goals)
+ *   Organization = WHERE (structure, nesting)
+ *   Position     = WHAT  (duties, boundaries)
+ *
+ * All methods are stateless — entity names are passed per call.
  */
 
 /**
- * Role entry in the organization.
+ * Assignment — tracks which org/position a role is assigned to.
  */
-interface RoleEntry {
+interface Assignment {
+    readonly org: string;
+    readonly position?: string;
+}
+/**
+ * OrganizationConfig — stored config for an organization.
+ */
+interface OrganizationConfig {
+    readonly parent?: string;
+    readonly positions: string[];
+}
+/**
+ * RolexConfig — The single source of truth for society state.
+ *
+ * Always exists. Defined in core, persisted by Platform.
+ */
+interface RolexConfig {
+    roles: string[];
+    organizations: Record<string, OrganizationConfig>;
+    assignments: Record<string, Assignment>;
+}
+/**
+ * Organization info (runtime view).
+ */
+interface OrganizationInfo {
     readonly name: string;
-    readonly team: string;
+    readonly parent?: string;
+    readonly positions: string[];
+    readonly members: string[];
 }
 /**
- * Organization structure.
+ * Position info (runtime view).
  */
-interface Organization {
+interface PositionInfo {
     readonly name: string;
-    readonly roles: RoleEntry[];
+    readonly org: string;
+    readonly state: PositionState;
+    readonly assignedRole: string | null;
+    readonly duties: Duty[];
 }
 /**
- * Society directory — all known roles and organizations.
+ * Role directory entry with state information.
+ */
+interface RoleEntry {
+    readonly name: string;
+    readonly state: RoleState;
+    readonly org?: string;
+    readonly position?: string;
+}
+/**
+ * Society directory — all known roles, organizations, and positions.
  */
 interface Directory {
     readonly roles: readonly RoleEntry[];
-    readonly organizations: readonly {
-        readonly name: string;
-    }[];
+    readonly organizations: readonly OrganizationInfo[];
 }
 /**
- * Platform interface — abstracts role storage and retrieval.
- * All methods are stateless — role name identifies the target role.
+ * Platform interface — abstracts entity storage and retrieval.
  */
 interface Platform {
-    /** Found an organization */
-    found(name: string): void;
-    /** Get the organization structure (teams + roles) */
-    organization(): Organization;
-    /** List all born roles in society (regardless of organization membership) */
+    /** List all born roles in society */
     allBornRoles(): string[];
     /** Create a new role with its persona */
     born(name: string, source: string): Feature;
-    /** Hire a role into the organization — establish CAS link */
-    hire(name: string): void;
-    /** Fire a role from the organization — remove CAS link */
-    fire(name: string): void;
-    /** Load all identity features for a role */
+    /** Found an organization, optionally with a parent org and description */
+    found(name: string, source?: string, parent?: string): void;
+    /** Get organization info by name */
+    getOrganization(name: string): OrganizationInfo | null;
+    /** List all organizations */
+    allOrganizations(): OrganizationInfo[];
+    /** Hire a role into an organization */
+    hire(roleId: string, orgName: string): void;
+    /** Fire a role from an organization (auto-dismisses if on_duty) */
+    fire(roleId: string, orgName: string): void;
+    /** Establish a position within an organization */
+    establish(positionName: string, source: string, orgName: string): void;
+    /** Appoint a role to a position */
+    appoint(roleId: string, positionName: string, orgName: string): void;
+    /** Dismiss a role from their position (back to member) */
+    dismiss(roleId: string): void;
+    /** Get duties for a position */
+    positionDuties(positionName: string, orgName: string): Duty[];
+    /** Get a role's current assignment */
+    getAssignment(roleId: string): Assignment | null;
+    /** Get position info */
+    getPosition(positionName: string, orgName: string): PositionInfo | null;
+    /** Load all identity features for a role (includes duties if on_duty) */
     identity(roleId: string): Feature[];
     /** Add a growth dimension to a role's identity */
     growup(roleId: string, type: "knowledge" | "experience" | "voice", name: string, source: string): Feature;
@@ -204,4 +293,55 @@ interface Platform {
     reflect(roleId: string, experienceNames: string[], knowledgeName: string, knowledgeSource: string): Feature;
 }
 
-export type { Directory, Feature, Goal, Identity, Organization, Plan, Platform, Role, RoleEntry, Scenario, Skill, Task };
+/**
+ * transitions.ts — State machine definitions and transition logic.
+ *
+ * Role transitions:
+ *   free --(hire)--> member --(appoint)--> on_duty
+ *   on_duty --(dismiss)--> member --(fire)--> free
+ *   on_duty --(fire)--> free  (auto-dismiss)
+ *
+ * Position transitions:
+ *   vacant --(appoint)--> filled --(dismiss)--> vacant
+ */
+
+interface Transition<S extends string> {
+    readonly from: S;
+    readonly to: S;
+    readonly action: string;
+}
+declare const ROLE_MACHINE: Transition<RoleState>[];
+declare const POSITION_MACHINE: Transition<PositionState>[];
+/**
+ * Find a transition by current state and action.
+ */
+declare function findTransition<S extends string>(machine: Transition<S>[], from: S, action: string): Transition<S> | null;
+/**
+ * Check if a transition is valid.
+ */
+declare function canTransition<S extends string>(machine: Transition<S>[], from: S, action: string): boolean;
+/**
+ * Execute a transition — returns new state or throws.
+ */
+declare function transition<S extends string>(machine: Transition<S>[], from: S, action: string): S;
+
+/**
+ * relations.ts — One-to-one relationship constraints.
+ *
+ * - A role can belong to at most one organization
+ * - A role can hold at most one position
+ * - A position can be held by at most one role
+ */
+interface OneToOneConstraint {
+    readonly entity: string;
+    readonly relation: string;
+    readonly description: string;
+}
+declare const RELATIONS: OneToOneConstraint[];
+/**
+ * Validate that a one-to-one assignment does not conflict.
+ * Throws if the entity is already assigned.
+ */
+declare function validateOneToOne(entityName: string, currentValue: string | null, newValue: string, constraintDesc: string): void;
+
+export { type Assignment, type Directory, type Duty, type Feature, type Goal, type Identity, type OneToOneConstraint, type OrganizationConfig, type OrganizationInfo, POSITION_MACHINE, type Plan, type Platform, type PositionInfo, type PositionState, RELATIONS, ROLE_MACHINE, type Role, type RoleEntry, type RoleState, type RolexConfig, type Scenario, type Skill, type Task, type Transition, canTransition, findTransition, getPositionState, getRoleState, transition, validateOneToOne };

package/dist/index.js

@@ -1 +1,67 @@
+// src/model/states.ts
+function getRoleState(assignment) {
+  if (!assignment) return "free";
+  if (assignment.position) return "on_duty";
+  return "member";
+}
+function getPositionState(assignedRole) {
+  return assignedRole ? "filled" : "vacant";
+}
+
+// src/model/transitions.ts
+var ROLE_MACHINE = [
+  { from: "free", to: "member", action: "hire" },
+  { from: "member", to: "on_duty", action: "appoint" },
+  { from: "on_duty", to: "member", action: "dismiss" },
+  { from: "member", to: "free", action: "fire" },
+  { from: "on_duty", to: "free", action: "fire" }
+];
+var POSITION_MACHINE = [
+  { from: "vacant", to: "filled", action: "appoint" },
+  { from: "filled", to: "vacant", action: "dismiss" }
+];
+function findTransition(machine, from, action) {
+  return machine.find((t) => t.from === from && t.action === action) ?? null;
+}
+function canTransition(machine, from, action) {
+  return findTransition(machine, from, action) !== null;
+}
+function transition(machine, from, action) {
+  const t = findTransition(machine, from, action);
+  if (!t) {
+    throw new Error(`Invalid transition: cannot "${action}" from state "${from}"`);
+  }
+  return t.to;
+}
+
+// src/model/relations.ts
+var RELATIONS = [
+  {
+    entity: "role",
+    relation: "organization",
+    description: "A role can belong to at most one organization"
+  },
+  { entity: "role", relation: "position", description: "A role can hold at most one position" },
+  {
+    entity: "position",
+    relation: "role",
+    description: "A position can be held by at most one role"
+  }
+];
+function validateOneToOne(entityName, currentValue, newValue, constraintDesc) {
+  if (currentValue && currentValue !== newValue) {
+    throw new Error(`${constraintDesc}: "${entityName}" is already assigned to "${currentValue}"`);
+  }
+}
+export {
+  POSITION_MACHINE,
+  RELATIONS,
+  ROLE_MACHINE,
+  canTransition,
+  findTransition,
+  getPositionState,
+  getRoleState,
+  transition,
+  validateOneToOne
+};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/model/states.ts","../src/model/transitions.ts","../src/model/relations.ts"],"sourcesContent":["/**\n * states.ts — Role and Position state definitions.\n *\n * Role:     free → member → on_duty\n * Position: vacant → filled\n */\n\nexport type RoleState = \"free\" | \"member\" | \"on_duty\";\nexport type PositionState = \"vacant\" | \"filled\";\n\n/**\n * Derive a role's state from assignment data.\n */\nexport function getRoleState(assignment: { org: string; position?: string } | null): RoleState {\n  if (!assignment) return \"free\";\n  if (assignment.position) return \"on_duty\";\n  return \"member\";\n}\n\n/**\n * Derive a position's state from assignment data.\n */\nexport function getPositionState(assignedRole: string | null): PositionState {\n  return assignedRole ? \"filled\" : \"vacant\";\n}\n","/**\n * transitions.ts — State machine definitions and transition logic.\n *\n * Role transitions:\n *   free --(hire)--> member --(appoint)--> on_duty\n *   on_duty --(dismiss)--> member --(fire)--> free\n *   on_duty --(fire)--> free  (auto-dismiss)\n *\n * Position transitions:\n *   vacant --(appoint)--> filled --(dismiss)--> vacant\n */\n\nimport type { RoleState, PositionState } from \"./states.js\";\n\nexport interface Transition<S extends string> {\n  readonly from: S;\n  readonly to: S;\n  readonly action: string;\n}\n\nexport const ROLE_MACHINE: Transition<RoleState>[] = [\n  { from: \"free\", to: \"member\", action: \"hire\" },\n  { from: \"member\", to: \"on_duty\", action: \"appoint\" },\n  { from: \"on_duty\", to: \"member\", action: \"dismiss\" },\n  { from: \"member\", to: \"free\", action: \"fire\" },\n  { from: \"on_duty\", to: \"free\", action: \"fire\" },\n];\n\nexport const POSITION_MACHINE: Transition<PositionState>[] = [\n  { from: \"vacant\", to: \"filled\", action: \"appoint\" },\n  { from: \"filled\", to: \"vacant\", action: \"dismiss\" },\n];\n\n/**\n * Find a transition by current state and action.\n */\nexport function findTransition<S extends string>(\n  machine: Transition<S>[],\n  from: S,\n  action: string\n): Transition<S> | null {\n  return machine.find((t) => t.from === from && t.action === action) ?? null;\n}\n\n/**\n * Check if a transition is valid.\n */\nexport function canTransition<S extends string>(\n  machine: Transition<S>[],\n  from: S,\n  action: string\n): boolean {\n  return findTransition(machine, from, action) !== null;\n}\n\n/**\n * Execute a transition — returns new state or throws.\n */\nexport function transition<S extends string>(machine: Transition<S>[], from: S, action: string): S {\n  const t = findTransition(machine, from, action);\n  if (!t) {\n    throw new Error(`Invalid transition: cannot \"${action}\" from state \"${from}\"`);\n  }\n  return t.to;\n}\n","/**\n * relations.ts — One-to-one relationship constraints.\n *\n * - A role can belong to at most one organization\n * - A role can hold at most one position\n * - A position can be held by at most one role\n */\n\nexport interface OneToOneConstraint {\n  readonly entity: string;\n  readonly relation: string;\n  readonly description: string;\n}\n\nexport const RELATIONS: OneToOneConstraint[] = [\n  {\n    entity: \"role\",\n    relation: \"organization\",\n    description: \"A role can belong to at most one organization\",\n  },\n  { entity: \"role\", relation: \"position\", description: \"A role can hold at most one position\" },\n  {\n    entity: \"position\",\n    relation: \"role\",\n    description: \"A position can be held by at most one role\",\n  },\n];\n\n/**\n * Validate that a one-to-one assignment does not conflict.\n * Throws if the entity is already assigned.\n */\nexport function validateOneToOne(\n  entityName: string,\n  currentValue: string | null,\n  newValue: string,\n  constraintDesc: string\n): void {\n  if (currentValue && currentValue !== newValue) {\n    throw new Error(`${constraintDesc}: \"${entityName}\" is already assigned to \"${currentValue}\"`);\n  }\n}\n"],"mappings":";AAaO,SAAS,aAAa,YAAkE;AAC7F,MAAI,CAAC,WAAY,QAAO;AACxB,MAAI,WAAW,SAAU,QAAO;AAChC,SAAO;AACT;AAKO,SAAS,iBAAiB,cAA4C;AAC3E,SAAO,eAAe,WAAW;AACnC;;;ACJO,IAAM,eAAwC;AAAA,EACnD,EAAE,MAAM,QAAQ,IAAI,UAAU,QAAQ,OAAO;AAAA,EAC7C,EAAE,MAAM,UAAU,IAAI,WAAW,QAAQ,UAAU;AAAA,EACnD,EAAE,MAAM,WAAW,IAAI,UAAU,QAAQ,UAAU;AAAA,EACnD,EAAE,MAAM,UAAU,IAAI,QAAQ,QAAQ,OAAO;AAAA,EAC7C,EAAE,MAAM,WAAW,IAAI,QAAQ,QAAQ,OAAO;AAChD;AAEO,IAAM,mBAAgD;AAAA,EAC3D,EAAE,MAAM,UAAU,IAAI,UAAU,QAAQ,UAAU;AAAA,EAClD,EAAE,MAAM,UAAU,IAAI,UAAU,QAAQ,UAAU;AACpD;AAKO,SAAS,eACd,SACA,MACA,QACsB;AACtB,SAAO,QAAQ,KAAK,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,WAAW,MAAM,KAAK;AACxE;AAKO,SAAS,cACd,SACA,MACA,QACS;AACT,SAAO,eAAe,SAAS,MAAM,MAAM,MAAM;AACnD;AAKO,SAAS,WAA6B,SAA0B,MAAS,QAAmB;AACjG,QAAM,IAAI,eAAe,SAAS,MAAM,MAAM;AAC9C,MAAI,CAAC,GAAG;AACN,UAAM,IAAI,MAAM,+BAA+B,MAAM,iBAAiB,IAAI,GAAG;AAAA,EAC/E;AACA,SAAO,EAAE;AACX;;;AClDO,IAAM,YAAkC;AAAA,EAC7C;AAAA,IACE,QAAQ;AAAA,IACR,UAAU;AAAA,IACV,aAAa;AAAA,EACf;AAAA,EACA,EAAE,QAAQ,QAAQ,UAAU,YAAY,aAAa,uCAAuC;AAAA,EAC5F;AAAA,IACE,QAAQ;AAAA,IACR,UAAU;AAAA,IACV,aAAa;AAAA,EACf;AACF;AAMO,SAAS,iBACd,YACA,cACA,UACA,gBACM;AACN,MAAI,gBAAgB,iBAAiB,UAAU;AAC7C,UAAM,IAAI,MAAM,GAAG,cAAc,MAAM,UAAU,6BAA6B,YAAY,GAAG;AAAA,EAC/F;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rolexjs/core",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "RoleX Core - AI Agent Role Management Framework",
   "keywords": [
     "rolex",