rhachet 1.17.0 → 1.19.0

package/dist/domain.objects/Actor.d.ts

@@ -0,0 +1,94 @@
+import { DomainEntity } from 'domain-objects';
+import type { z } from 'zod';
+import type { BrainRepl } from './BrainRepl';
+import type { Role, RoleSkillSchema } from './Role';
+/**
+ * .what = extracts skill input type from a RoleSkillSchema
+ * .why = enables type inference for skill arguments
+ */
+export type SkillInput<TSchema extends RoleSkillSchema> = z.infer<TSchema['input']>;
+/**
+ * .what = extracts skill output type from a RoleSkillSchema
+ * .why = enables type inference for skill return values
+ */
+export type SkillOutput<TSchema extends RoleSkillSchema> = z.infer<TSchema['output']>;
+/**
+ * .what = type for actor.act() method
+ * .why = enables type-safe rigid skill invocation
+ */
+export type ActorActOp<TRole extends Role> = <TSkillSlug extends keyof NonNullable<TRole['skills']['rigid']>>(input: {
+    brain?: {
+        repo: string;
+        slug: string;
+    } | BrainRepl;
+    skill: {
+        [K in TSkillSlug]: SkillInput<NonNullable<TRole['skills']['rigid']>[K]>;
+    };
+}) => Promise<SkillOutput<NonNullable<TRole['skills']['rigid']>[TSkillSlug]>>;
+/**
+ * .what = type for actor.run() method
+ * .why = enables type-safe solid skill invocation
+ */
+export type ActorRunOp<TRole extends Role> = <TSkillSlug extends keyof NonNullable<TRole['skills']['solid']>>(input: {
+    skill: {
+        [K in TSkillSlug]: SkillInput<NonNullable<TRole['skills']['solid']>[K]>;
+    };
+}) => Promise<SkillOutput<NonNullable<TRole['skills']['solid']>[TSkillSlug]>>;
+/**
+ * .what = type for actor.ask() method
+ * .why = enables fluid conversation with brain
+ */
+export type ActorAskOp = (input: {
+    prompt: string;
+}) => Promise<{
+    response: string;
+}>;
+/**
+ * .what = a role assumed by a brain, ready for invocation
+ * .why =
+ *   - enables sdk users to import and invoke actors directly
+ *   - composes role (skills + briefs) with brain allowlist
+ *   - provides type-safe .act(), .run(), .ask() methods
+ *
+ * .note = Actor = BrainRepl + Role composition
+ *   - first brain in allowlist is the default
+ *   - .act() invokes rigid skills (deterministic harness, brain operations)
+ *   - .run() invokes solid skills (deterministic, no brain)
+ *   - .ask() starts fluid conversation with default brain
+ */
+export interface Actor<TRole extends Role = Role> {
+    /**
+     * .what = the role this actor assumes
+     */
+    role: TRole;
+    /**
+     * .what = the brains this actor is allowed to use
+     * .note = first brain is the default
+     */
+    brains: BrainRepl[];
+    /**
+     * .what = invokes a rigid skill with brain
+     * .why = deterministic harness with probabilistic brain operations
+     */
+    act: ActorActOp<TRole>;
+    /**
+     * .what = invokes a solid skill via spawn
+     * .why = deterministic shell execution, no brain
+     */
+    run: ActorRunOp<TRole>;
+    /**
+     * .what = starts a fluid conversation with the default brain
+     * .why = open-ended exploration, brain decides path
+     */
+    ask: ActorAskOp;
+}
+export declare class Actor<TRole extends Role = Role> extends DomainEntity<Actor<TRole>> implements Actor<TRole> {
+    static unique: readonly ["role.slug"];
+    /**
+     * .what = creates an Actor with preserved literal skill types from TRole
+     * .why = enables type-safe .act(), .run(), .ask() invocation
+     *
+     * .note = use Actor.typed() instead of raw object cast for proper type preservation
+     */
+    static typed<TRole extends Role>(input: Actor<TRole>): Actor<TRole>;
+}

package/dist/domain.objects/Actor.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Actor = void 0;
+const domain_objects_1 = require("domain-objects");
+class Actor extends domain_objects_1.DomainEntity {
+    /**
+     * .what = creates an Actor with preserved literal skill types from TRole
+     * .why = enables type-safe .act(), .run(), .ask() invocation
+     *
+     * .note = use Actor.typed() instead of raw object cast for proper type preservation
+     */
+    static typed(input) {
+        return new Actor(input);
+    }
+}
+exports.Actor = Actor;
+Actor.unique = ['role.slug'];
+//# sourceMappingURL=Actor.js.map

package/dist/domain.objects/Actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Actor.js","sourceRoot":"","sources":["../../src/domain.objects/Actor.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AAmG9C,MAAa,KACX,SAAQ,6BAA0B;IAKlC;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAqB,KAAmB;QACzD,OAAO,IAAI,KAAK,CAAQ,KAAK,CAAC,CAAC;IACjC,CAAC;;AAdH,sBAeC;AAXe,YAAM,GAAG,CAAC,WAAW,CAAU,CAAC"}

package/dist/domain.objects/ActorRoleSkill.d.ts

@@ -0,0 +1,41 @@
+import { DomainLiteral } from 'domain-objects';
+import type { RoleSkillSchema } from './Role';
+import type { RoleSkillExecutable } from './RoleSkillExecutable';
+/**
+ * .what = a role skill that has been resolved and can be acted upon
+ * .why =
+ *   - unified return type for skill resolution
+ *   - explicit domain object for skill invocation
+ *   - actors use this to invoke skills via .act() and .run()
+ *
+ * .note = executable is required; ActorRoleSkill is only constructable
+ *   when a skill executable has been found
+ */
+export interface ActorRoleSkill {
+    /**
+     * .what = the skill's slug identifier
+     */
+    slug: string;
+    /**
+     * .what = the thought route for this skill
+     * .note = solid = deterministic, rigid = brain-augmented
+     */
+    route: 'solid' | 'rigid';
+    /**
+     * .what = where this skill was resolved from
+     * .note = role.skills takes precedence over .agent/ discovery
+     */
+    source: 'role.skills' | '.agent/';
+    /**
+     * .what = the zod schema for input/output validation
+     * .note = required; skills must have schemas to be executable via actor contracts
+     */
+    schema: RoleSkillSchema;
+    /**
+     * .what = the executable file for this skill
+     * .note = required; skill cannot be acted upon without an executable
+     */
+    executable: RoleSkillExecutable;
+}
+export declare class ActorRoleSkill extends DomainLiteral<ActorRoleSkill> implements ActorRoleSkill {
+}

package/dist/domain.objects/ActorRoleSkill.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActorRoleSkill = void 0;
+const domain_objects_1 = require("domain-objects");
+class ActorRoleSkill extends domain_objects_1.DomainLiteral {
+}
+exports.ActorRoleSkill = ActorRoleSkill;
+//# sourceMappingURL=ActorRoleSkill.js.map

package/dist/domain.objects/ActorRoleSkill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActorRoleSkill.js","sourceRoot":"","sources":["../../src/domain.objects/ActorRoleSkill.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AA6C/C,MAAa,cACX,SAAQ,8BAA6B;CACT;AAF9B,wCAE8B"}

package/dist/domain.objects/BrainAtom.d.ts

@@ -0,0 +1,54 @@
+import { DomainEntity } from 'domain-objects';
+import type { Artifact } from 'rhachet-artifact';
+import type { GitFile } from 'rhachet-artifact-git';
+import type { Empty } from 'type-fns';
+import type { z } from 'zod';
+import type { BrainAtomPlugs } from './BrainAtomPlugs';
+/**
+ * .what = an LLM inference endpoint capable of creative language imagination
+ * .why =
+ *   - enables registration of pluggable LLM atoms (e.g., claude, gpt, llama)
+ *   - provides a standardized contract for single-turn or multi-turn inference
+ *   - enables dynamic swapping of models at runtime
+ */
+export interface BrainAtom {
+    /**
+     * .what = identifier for the plugin package that provides this atom
+     * .example = "anthropic", "openai", "ollama"
+     */
+    repo: string;
+    /**
+     * .what = unique identifier for this specific atom within the repo
+     * .example = "claude-opus-4.5", "gpt-4o", "llama-3-70b"
+     */
+    slug: string;
+    /**
+     * .what = human-readable description of this atom's capabilities
+     * .why = helps developers understand what this atom is best suited for
+     */
+    description: string;
+    /**
+     * .what = the ask operation contract (renamed from imagine)
+     * .why = standardizes how all atoms are invoked, regardless of provider
+     *
+     * .note = plugin is responsible for handling role.briefs appropriately.
+     *   this design maximizes leverage of each brain's unique capabilities:
+     *   - context window optimization (e.g., claude's 200k vs gpt's 128k)
+     *   - provider-specific caching (e.g., anthropic prompt caching)
+     *   - finetuned behaviors (e.g., system prompt placement, formatting)
+     *   - native JSON schema enforcement for structured outputs
+     */
+    ask: <TOutput>(input: {
+        plugs?: BrainAtomPlugs;
+        role: {
+            briefs?: Artifact<typeof GitFile>[];
+        };
+        prompt: string;
+        schema: {
+            output: z.Schema<TOutput>;
+        };
+    }, context?: Empty) => Promise<TOutput>;
+}
+export declare class BrainAtom extends DomainEntity<BrainAtom> implements BrainAtom {
+    static unique: readonly ["repo", "slug"];
+}

package/dist/domain.objects/BrainAtom.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainAtom = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainAtom extends domain_objects_1.DomainEntity {
+}
+exports.BrainAtom = BrainAtom;
+BrainAtom.unique = ['repo', 'slug'];
+//# sourceMappingURL=BrainAtom.js.map

package/dist/domain.objects/BrainAtom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainAtom.js","sourceRoot":"","sources":["../../src/domain.objects/BrainAtom.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AAuD9C,MAAa,SAAU,SAAQ,6BAAuB;;AAAtD,8BAEC;AADe,gBAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAU,CAAC"}

package/dist/domain.objects/BrainAtomPlugs.d.ts

@@ -0,0 +1,17 @@
+import { DomainLiteral } from 'domain-objects';
+/**
+ * .what = configuration plugs for BrainAtom instances
+ * .why = enables extensible configuration for single-turn inference
+ *   without coupling to specific SDK implementations
+ *
+ * .note = placeholder interface; actual configuration TBD
+ */
+export interface BrainAtomPlugs {
+    /**
+     * .what = structured output configuration
+     * .why = enables native JSON schema enforcement for reduced token waste
+     */
+    output?: never;
+}
+export declare class BrainAtomPlugs extends DomainLiteral<BrainAtomPlugs> implements BrainAtomPlugs {
+}

package/dist/domain.objects/BrainAtomPlugs.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainAtomPlugs = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainAtomPlugs extends domain_objects_1.DomainLiteral {
+}
+exports.BrainAtomPlugs = BrainAtomPlugs;
+//# sourceMappingURL=BrainAtomPlugs.js.map

package/dist/domain.objects/BrainAtomPlugs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainAtomPlugs.js","sourceRoot":"","sources":["../../src/domain.objects/BrainAtomPlugs.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AAiB/C,MAAa,cACX,SAAQ,8BAA6B;CACT;AAF9B,wCAE8B"}

package/dist/domain.objects/BrainRepl.d.ts

@@ -0,0 +1,74 @@
+import { DomainEntity } from 'domain-objects';
+import type { Artifact } from 'rhachet-artifact';
+import type { GitFile } from 'rhachet-artifact-git';
+import type { Empty } from 'type-fns';
+import type { z } from 'zod';
+import type { BrainReplPlugs } from './BrainReplPlugs';
+/**
+ * .what = a brain.atom operating behind a REPL (read-execute-print-loop)
+ * .why =
+ *   - enables registration of pluggable agentic repls (e.g., claude-code, codex)
+ *   - provides a standardized contract for agentic tool-using inference
+ *   - enables dynamic swapping of agentic systems at runtime
+ *
+ * .note = repls differ from atoms in that they execute iterative agentic loops
+ *   with tool use, rather than single-turn inference
+ */
+export interface BrainRepl {
+    /**
+     * .what = identifier for the plugin package that provides this repl
+     * .example = "anthropic", "openai"
+     */
+    repo: string;
+    /**
+     * .what = unique identifier for this specific repl within the repo
+     * .example = "claude-code", "codex"
+     */
+    slug: string;
+    /**
+     * .what = human-readable description of this repl's capabilities
+     * .why = helps developers understand what this repl is best suited for
+     */
+    description: string;
+    /**
+     * .what = readonly analysis operation (research, queries, code review)
+     * .why = provides safe, non-mutating agent interactions
+     *   with only read access to filesystem and tools
+     *
+     * .sdk.mapping =
+     *   - claude-agent-sdk: disallowedTools=["Edit","Write","Bash","NotebookEdit"]
+     *   - codex-sdk: --sandbox read-only
+     */
+    ask: <TOutput>(input: {
+        plugs?: BrainReplPlugs;
+        role: {
+            briefs?: Artifact<typeof GitFile>[];
+        };
+        prompt: string;
+        schema: {
+            output: z.Schema<TOutput>;
+        };
+    }, context?: Empty) => Promise<TOutput>;
+    /**
+     * .what = read+write action operation (code changes, file edits)
+     * .why = provides full agentic capabilities with write access
+     *   for tasks that require modifying the codebase
+     *
+     * .sdk.mapping =
+     *   - claude-agent-sdk: allowedTools=["Read","Edit","Write","Bash","Glob","Grep"]
+     *   - codex-sdk: --sandbox workspace-write
+     */
+    act: <TOutput>(input: {
+        plugs?: BrainReplPlugs;
+        role: {
+            briefs?: Artifact<typeof GitFile>[];
+        };
+        prompt: string;
+        schema: {
+            output: z.Schema<TOutput>;
+        };
+    }, context?: Empty) => Promise<TOutput>;
+}
+export declare class BrainRepl extends DomainEntity<BrainRepl> implements BrainRepl {
+    static unique: readonly ["repo", "slug"];
+}

package/dist/domain.objects/BrainRepl.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainRepl = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainRepl extends domain_objects_1.DomainEntity {
+}
+exports.BrainRepl = BrainRepl;
+BrainRepl.unique = ['repo', 'slug'];
+//# sourceMappingURL=BrainRepl.js.map

package/dist/domain.objects/BrainRepl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainRepl.js","sourceRoot":"","sources":["../../src/domain.objects/BrainRepl.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AA2E9C,MAAa,SAAU,SAAQ,6BAAuB;;AAAtD,8BAEC;AADe,gBAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAU,CAAC"}

package/dist/domain.objects/BrainReplPlugs.d.ts

@@ -0,0 +1,34 @@
+import { DomainLiteral } from 'domain-objects';
+/**
+ * .what = configuration plugs for BrainRepl instances
+ * .why = enables extensible tooling, memory management, and access control
+ *   for agentic workloads without coupling to specific SDK implementations
+ */
+export interface BrainReplPlugs {
+    /**
+     * .what = additional tool providers beyond built-in tools
+     * .why = enables domain-specific tooling (databases, browsers, APIs)
+     *   via MCP servers or custom tool definitions
+     *
+     * .example = playwright browser, postgres database, custom APIs
+     */
+    toolboxes?: never;
+    /**
+     * .what = memory and context management strategy
+     * .why = enables custom context compression, session persistence,
+     *   and artifact management for long-running workflows
+     *
+     * .example = session resume, context compaction hooks
+     */
+    memory?: never;
+    /**
+     * .what = permission guard and access control
+     * .why = enables custom authorization logic, audit logging,
+     *   and tool-level access policies beyond SDK defaults
+     *
+     * .example = canUseTool callbacks, preToolUse hooks
+     */
+    access?: never;
+}
+export declare class BrainReplPlugs extends DomainLiteral<BrainReplPlugs> implements BrainReplPlugs {
+}

package/dist/domain.objects/BrainReplPlugs.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainReplPlugs = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainReplPlugs extends domain_objects_1.DomainLiteral {
+}
+exports.BrainReplPlugs = BrainReplPlugs;
+//# sourceMappingURL=BrainReplPlugs.js.map

package/dist/domain.objects/BrainReplPlugs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainReplPlugs.js","sourceRoot":"","sources":["../../src/domain.objects/BrainReplPlugs.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AAsC/C,MAAa,cACX,SAAQ,8BAA6B;CACT;AAF9B,wCAE8B"}

package/dist/domain.objects/ContextBrain.d.ts

@@ -0,0 +1,73 @@
+import { DomainLiteral, type RefByUnique } from 'domain-objects';
+import type { Artifact } from 'rhachet-artifact';
+import type { GitFile } from 'rhachet-artifact-git';
+import type { z } from 'zod';
+import type { BrainAtom } from './BrainAtom';
+import type { BrainAtomPlugs } from './BrainAtomPlugs';
+import type { BrainRepl } from './BrainRepl';
+import type { BrainReplPlugs } from './BrainReplPlugs';
+/**
+ * .what = runtime context providing unified access to brain atoms and repls
+ * .why =
+ *   - provides a clean interface for invoking brains by reference
+ *   - handles lookup, role embedding, and delegation transparently
+ *   - enables dynamic brain swapping without caller changes
+ */
+export interface ContextBrain {
+    /**
+     * .what = interface for invoking brain atoms and repls
+     */
+    brain: {
+        atom: {
+            /**
+             * .what = lookup and invoke a brain atom for single-turn inference
+             * .why = provides ergonomic access to atoms with automatic lookup
+             */
+            ask: <TOutput>(input: {
+                brain: RefByUnique<typeof BrainAtom>;
+                plugs?: BrainAtomPlugs;
+                role: {
+                    briefs?: Artifact<typeof GitFile>[];
+                };
+                prompt: string;
+                schema: {
+                    output: z.Schema<TOutput>;
+                };
+            }) => Promise<TOutput>;
+        };
+        repl: {
+            /**
+             * .what = lookup and invoke a brain repl for readonly analysis
+             * .why = provides safe agentic analysis without file modifications
+             */
+            ask: <TOutput>(input: {
+                brain: RefByUnique<typeof BrainRepl>;
+                plugs?: BrainReplPlugs;
+                role: {
+                    briefs?: Artifact<typeof GitFile>[];
+                };
+                prompt: string;
+                schema: {
+                    output: z.Schema<TOutput>;
+                };
+            }) => Promise<TOutput>;
+            /**
+             * .what = lookup and invoke a brain repl for read+write actions
+             * .why = provides full agentic capabilities with file modifications
+             */
+            act: <TOutput>(input: {
+                brain: RefByUnique<typeof BrainRepl>;
+                plugs?: BrainReplPlugs;
+                role: {
+                    briefs?: Artifact<typeof GitFile>[];
+                };
+                prompt: string;
+                schema: {
+                    output: z.Schema<TOutput>;
+                };
+            }) => Promise<TOutput>;
+        };
+    };
+}
+export declare class ContextBrain extends DomainLiteral<ContextBrain> implements ContextBrain {
+}

package/dist/domain.objects/ContextBrain.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextBrain = void 0;
+const domain_objects_1 = require("domain-objects");
+class ContextBrain extends domain_objects_1.DomainLiteral {
+}
+exports.ContextBrain = ContextBrain;
+//# sourceMappingURL=ContextBrain.js.map

package/dist/domain.objects/ContextBrain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextBrain.js","sourceRoot":"","sources":["../../src/domain.objects/ContextBrain.ts"],"names":[],"mappings":";;;AAAA,mDAAiE;AA+DjE,MAAa,YACX,SAAQ,8BAA2B;CACT;AAF5B,oCAE4B"}

package/dist/domain.objects/InvokeHooks.d.ts

@@ -1,5 +1,31 @@
+import type { z } from 'zod';
 import type { InvokeOpts } from '.';
-export interface InvokeHooks {
+import type { Role, RoleSkillRegistry } from './Role';
+/**
+ * .what = extracts input type for a single skill from a skill registry
+ * .why = enables type inference for skill inputs in hooks
+ */
+type SkillInputFromRegistry<TRegistry extends RoleSkillRegistry, TSkill extends keyof TRegistry> = z.infer<TRegistry[TSkill]['input']>;
+/**
+ * .what = union type of all skill inputs from a registry
+ * .why = enables onInvokeActInput to accept any valid skill input
+ */
+type AnySkillInputFromRegistry<TRegistry extends RoleSkillRegistry> = {
+    [K in keyof TRegistry]: {
+        skill: K;
+        input: SkillInputFromRegistry<TRegistry, K>;
+    };
+}[keyof TRegistry];
+/**
+ * .what = hooks for customizing invoke behavior
+ * .why = enables input transformation before skill execution
+ *
+ * .note = generic TRole enables type-safe onInvokeActInput when Role.typed() is used
+ */
+export interface InvokeHooks<TRole extends Role = Role> {
+    /**
+     * .what = transforms ask input before execution
+     */
     onInvokeAskInput: Array<(input: InvokeOpts<{
         ask: string;
         config: string;
@@ -7,4 +33,15 @@ export interface InvokeHooks {
         ask: string;
         config: string;
     }>>;
+    /**
+     * .what = transforms act input before skill execution
+     * .why = enables input manipulation (e.g., adding defaults, validation)
+     *
+     * .note = strongly typed when TRole preserves literal skill names via Role.typed()
+     */
+    onInvokeActInput?: TRole['skills']['rigid'] extends RoleSkillRegistry ? (input: AnySkillInputFromRegistry<NonNullable<TRole['skills']['rigid']>>) => AnySkillInputFromRegistry<NonNullable<TRole['skills']['rigid']>>['input'] : (input: {
+        skill: string;
+        input: Record<string, unknown>;
+    }) => Record<string, unknown>;
 }
+export {};

package/dist/domain.objects/Role.d.ts

@@ -1,13 +1,33 @@
 import { DomainEntity } from 'domain-objects';
+import type { z } from 'zod';
 import type { RoleSkill } from './RoleSkill';
 import type { RoleTrait } from './RoleTrait';
+/**
+ * .what = type definition for a skill's schema (input/output zod schemas)
+ * .why = enables type-safe skill invocation via .act() and .run()
+ */
+export interface RoleSkillSchema {
+    input: z.ZodSchema;
+    output: z.ZodSchema;
+}
+/**
+ * .what = type for a record of skills with literal keys preserved
+ * .why = enables type inference of skill names via keyof
+ */
+export type RoleSkillRegistry = {
+    readonly [slug: string]: RoleSkillSchema;
+};
 /**
  * .what = defines a role that can have traits, know skills, and be instantiated across thread.context
  * .why =
  *   - enables registration of usable roles (e.g., 'mechanic', 'designer', 'architect', 'ecologist')
  *   - enables instantiation of thread.contexts
+ *
+ * .note = generic type parameters preserve literal skill names for type-safe invocation
+ *   - TSolid: the solid skills record type (e.g., { 'wordcount': { input, output } })
+ *   - TRigid: the rigid skills record type (e.g., { 'review': { input, output } })
  */
-export interface Role {
+export interface Role<TSolid extends RoleSkillRegistry = RoleSkillRegistry, TRigid extends RoleSkillRegistry = RoleSkillRegistry> {
     /**
      * .what = a unique, readable identifier
      * .example = "mechanic"
@@ -40,12 +60,26 @@ export interface Role {
      * .what = the skills known by the role
      * .why = declares what the role can do
      * .how =
+     *   - solid: typed skills for deterministic execution (no brain)
+     *     - enables type-safe .run() invocation
+     *   - rigid: typed skills for deterministic harness with brain operations
+     *     - enables type-safe .act() invocation
      *   - dirs: directory-based skills (e.g., .sh scripts) for linking/booting
      *     - single { uri: string }: symlinks this dir as the full skills dir
      *     - array { uri: string }[]: symlinks each dir within the skills dir
      *   - refs: programmatic RoleSkill references for execution
      */
     skills: {
+        /**
+         * .what = solid skills (deterministic, no brain)
+         * .why = type-safe .run() invocation
+         */
+        solid?: TSolid;
+        /**
+         * .what = rigid skills (deterministic harness, brain operations)
+         * .why = type-safe .act() invocation
+         */
+        rigid?: TRigid;
         dirs: {
             uri: string;
         } | {
@@ -89,6 +123,13 @@ export interface Role {
         }[];
     };
 }
-export declare class Role extends DomainEntity<Role> implements Role {
+export declare class Role<TSolid extends RoleSkillRegistry = RoleSkillRegistry, TRigid extends RoleSkillRegistry = RoleSkillRegistry> extends DomainEntity<Role<TSolid, TRigid>> implements Role<TSolid, TRigid> {
     static unique: readonly ["slug"];
+    /**
+     * .what = creates a Role with preserved literal skill names
+     * .why = enables type-safe skill invocation via genActor
+     *
+     * .note = use Role.typed() instead of new Role() to preserve literal types
+     */
+    static typed<TSolid extends RoleSkillRegistry, TRigid extends RoleSkillRegistry>(input: Role<TSolid, TRigid>): Role<TSolid, TRigid>;
 }

package/dist/domain.objects/Role.js

@@ -3,6 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Role = void 0;
 const domain_objects_1 = require("domain-objects");
 class Role extends domain_objects_1.DomainEntity {
+    /**
+     * .what = creates a Role with preserved literal skill names
+     * .why = enables type-safe skill invocation via genActor
+     *
+     * .note = use Role.typed() instead of new Role() to preserve literal types
+     */
+    static typed(input) {
+        return new Role(input);
+    }
 }
 exports.Role = Role;
 Role.unique = ['slug'];

package/dist/domain.objects/Role.js.map

@@ -1 +1 @@
-{"version":3,"file":"Role.js","sourceRoot":"","sources":["../../src/domain.objects/Role.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AAoF9C,MAAa,IAAK,SAAQ,6BAAkB;;AAA5C,oBAEC;AADe,WAAM,GAAG,CAAC,MAAM,CAAU,CAAC"}
+{"version":3,"file":"Role.js","sourceRoot":"","sources":["../../src/domain.objects/Role.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AA2H9C,MAAa,IAIX,SAAQ,6BAAkC;IAK1C;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAGjB,KAA2B;QAC3B,OAAO,IAAI,IAAI,CAAiB,KAAK,CAAC,CAAC;IACzC,CAAC;;AApBH,oBAqBC;AAde,WAAM,GAAG,CAAC,MAAM,CAAU,CAAC"}

package/dist/domain.objects/index.d.ts

@@ -9,6 +9,11 @@ export * from './StitchStep';
 export * from './StitchTrail';
 export * from './Thread';
 export * from './Threads';
+export * from './Actor';
+export * from './ActorRoleSkill';
+export * from './BrainAtom';
+export * from './BrainRepl';
+export * from './ContextBrain';
 export * from './InvokeHooks';
 export * from './InvokeOpts';
 export * from './Role';