@positronic/core 0.0.1 → 0.0.2

package/dist/types/dsl/brain.d.ts

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import type { ObjectGenerator } from '../clients/types.js';
+import type { State, JsonPatch } from './types.js';
+import { STATUS, BRAIN_EVENTS } from './constants.js';
+import type { Resources } from '../resources/resources.js';
+export type SerializedError = {
+    name: string;
+    message: string;
+    stack?: string;
+};
+interface BaseEvent<TOptions extends object = object> {
+    type: (typeof BRAIN_EVENTS)[keyof typeof BRAIN_EVENTS];
+    options: TOptions;
+    brainRunId: string;
+}
+interface BrainBaseEvent<TOptions extends object = object> extends BaseEvent<TOptions> {
+    brainTitle: string;
+    brainDescription?: string;
+}
+export interface BrainStartEvent<TOptions extends object = object> extends BrainBaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.START | typeof BRAIN_EVENTS.RESTART;
+    initialState: State;
+    status: typeof STATUS.RUNNING;
+}
+export interface BrainCompleteEvent<TOptions extends object = object> extends BrainBaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.COMPLETE;
+    status: typeof STATUS.COMPLETE;
+}
+export interface BrainErrorEvent<TOptions extends object = object> extends BrainBaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.ERROR;
+    status: typeof STATUS.ERROR;
+    error: SerializedError;
+}
+export interface StepStatusEvent<TOptions extends object = object> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.STEP_STATUS;
+    steps: SerializedStepStatus[];
+}
+export interface StepStartedEvent<TOptions extends object = object> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.STEP_START;
+    status: typeof STATUS.RUNNING;
+    stepTitle: string;
+    stepId: string;
+}
+export interface StepCompletedEvent<TOptions extends object = object> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.STEP_COMPLETE;
+    status: typeof STATUS.RUNNING;
+    stepTitle: string;
+    stepId: string;
+    patch: JsonPatch;
+}
+export type BrainEvent<TOptions extends object = object> = BrainStartEvent<TOptions> | BrainCompleteEvent<TOptions> | BrainErrorEvent<TOptions> | StepStatusEvent<TOptions> | StepStartedEvent<TOptions> | StepCompletedEvent<TOptions>;
+export interface SerializedStep {
+    title: string;
+    status: (typeof STATUS)[keyof typeof STATUS];
+    id: string;
+    patch?: JsonPatch;
+}
+export type SerializedStepStatus = Omit<SerializedStep, 'patch'>;
+export interface BrainStructure {
+    title: string;
+    description?: string;
+    steps: Array<{
+        type: 'step' | 'brain';
+        title: string;
+        innerBrain?: BrainStructure;
+    }>;
+}
+export interface BrainFactory {
+    <TOptions extends object = object, TState extends State = object, TServices extends object = object>(brainConfig: string | {
+        title: string;
+        description?: string;
+    }): Brain<TOptions, TState, TServices>;
+}
+interface BaseRunParams<TOptions extends object = object> {
+    client: ObjectGenerator;
+    resources?: Resources;
+    options?: TOptions;
+}
+export interface InitialRunParams<TOptions extends object = object> extends BaseRunParams<TOptions> {
+    initialState?: State;
+    initialCompletedSteps?: never;
+    brainRunId?: string;
+}
+export interface RerunParams<TOptions extends object = object> extends BaseRunParams<TOptions> {
+    initialState: State;
+    initialCompletedSteps: SerializedStep[];
+    brainRunId: string;
+}
+export declare class Brain<TOptions extends object = object, TState extends State = object, TServices extends object = object> {
+    readonly title: string;
+    private description?;
+    private blocks;
+    type: 'brain';
+    private defaultOptions;
+    private services;
+    constructor(title: string, description?: string | undefined);
+    get structure(): BrainStructure;
+    withOptions(options: Partial<TOptions>): this;
+    withServices<TNewServices extends object>(services: TNewServices): Brain<TOptions, TState, TNewServices>;
+    step<TNewState extends State>(title: string, action: (params: {
+        state: TState;
+        options: TOptions;
+        client: ObjectGenerator;
+        resources: Resources;
+    } & TServices) => TNewState | Promise<TNewState>): Brain<TOptions, TNewState, TServices>;
+    brain<TInnerState extends State, TNewState extends State>(title: string, innerBrain: Brain<TOptions, TInnerState, TServices>, action: (params: {
+        state: TState;
+        brainState: TInnerState;
+        services: TServices;
+    }) => TNewState, initialState?: State | ((state: TState) => State)): Brain<TOptions, TNewState, TServices>;
+    prompt<TResponseKey extends string & {
+        readonly brand?: unique symbol;
+    }, TSchema extends z.ZodObject<any>, TNewState extends State = TState & {
+        [K in TResponseKey]: z.infer<TSchema>;
+    }>(title: string, config: {
+        template: (state: TState, resources: Resources) => string | Promise<string>;
+        outputSchema: {
+            schema: TSchema;
+            name: TResponseKey & (string extends TResponseKey ? never : unknown);
+        };
+        client?: ObjectGenerator;
+    }, reduce?: (params: {
+        state: TState;
+        response: z.infer<TSchema>;
+        options: TOptions;
+        prompt: string;
+        resources: Resources;
+    } & TServices) => TNewState | Promise<TNewState>): Brain<TOptions, TNewState, TServices>;
+    run(params: InitialRunParams<TOptions>): AsyncGenerator<BrainEvent<TOptions>>;
+    run(params: RerunParams<TOptions>): AsyncGenerator<BrainEvent<TOptions>>;
+    private withBlocks;
+    private nextBrain;
+}
+export declare const brain: BrainFactory;
+export {};
+//# sourceMappingURL=brain.d.ts.map

package/dist/types/dsl/brain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../../../src/dsl/brain.ts"],"names":[],"mappings":"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"}

package/dist/types/dsl/constants.d.ts

@@ -1,11 +1,11 @@
-export declare const WORKFLOW_EVENTS: {
-    readonly START: "workflow:start";
-    readonly RESTART: "workflow:restart";
+export declare const BRAIN_EVENTS: {
+    readonly START: "brain:start";
+    readonly RESTART: "brain:restart";
     readonly STEP_START: "step:start";
     readonly STEP_COMPLETE: "step:complete";
     readonly STEP_STATUS: "step:status";
-    readonly ERROR: "workflow:error";
-    readonly COMPLETE: "workflow:complete";
+    readonly ERROR: "brain:error";
+    readonly COMPLETE: "brain:complete";
 };
 export declare const STATUS: {
     readonly PENDING: "pending";

package/dist/types/dsl/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/dsl/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe;;;;;;;;CAQlB,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;CAKT,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/dsl/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY;;;;;;;;CAQf,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;CAKT,CAAC"}

package/dist/types/dsl/json-patch.d.ts

@@ -1,4 +1,5 @@
-import { JsonPatch, State } from './types';
+import { JsonPatch, State } from './types.js';
+export type { JsonPatch };
 /**
  * Creates a JSON Patch that describes the changes needed to transform prevState into nextState.
  */

package/dist/types/dsl/json-patch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-patch.d.ts","sourceRoot":"","sources":["../../../src/dsl/json-patch.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAE3C;;GAEG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,GAAG,SAAS,CAKzE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,GAAG,SAAS,EAAE,GAAG,KAAK,CAQlF"}
+{"version":3,"file":"json-patch.d.ts","sourceRoot":"","sources":["../../../src/dsl/json-patch.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE9C,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B;;GAEG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,GAAG,SAAS,CAKzE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,SAAS,GAAG,SAAS,EAAE,GAC/B,KAAK,CAkBP"}

package/dist/types/index.d.ts

@@ -1,12 +1,14 @@
-export { Workflow, workflow } from "./dsl/workflow";
-export { WorkflowRunner } from "./dsl/workflow-runner";
-export { createExtension } from "./dsl/extensions";
-export { STATUS, WORKFLOW_EVENTS } from "./dsl/constants";
-export { Adapter } from "./adapters/types";
-export type { WorkflowEvent, SerializedStep, InitialRunParams, RerunParams, WorkflowStartEvent, WorkflowCompleteEvent, WorkflowErrorEvent, StepStatusEvent, StepStartedEvent, StepCompletedEvent } from "./dsl/workflow";
-export type { PromptClient, ResponseModel } from "./clients/types";
-export type { State } from "./dsl/types";
-export type { FileStore } from "./file-stores/types";
-export { createPatch, applyPatches } from "./dsl/json-patch";
-export { LocalFileStore } from "./file-stores/local-file-store";
+export { Brain, brain } from './dsl/brain.js';
+export { BrainRunner } from './dsl/brain-runner.js';
+export { STATUS, BRAIN_EVENTS } from './dsl/constants.js';
+export type { Adapter } from './adapters/types.js';
+export type { BrainEvent, SerializedStep, InitialRunParams, RerunParams, BrainStartEvent, BrainCompleteEvent, BrainErrorEvent, StepStatusEvent, StepStartedEvent, StepCompletedEvent, BrainStructure, BrainFactory, } from './dsl/brain.js';
+export type { ObjectGenerator, Message } from './clients/types.js';
+export type { State } from './dsl/types.js';
+export { createPatch, applyPatches } from './dsl/json-patch.js';
+export { z } from 'zod';
+export type { ResourceLoader } from './resources/resource-loader.js';
+export { createResources, type Resources } from './resources/resources.js';
+export type { Manifest as ResourceManifest, Entry as ResourceEntry, ResourceType, } from './resources/resources.js';
+export { RESOURCE_TYPES } from './resources/resources.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,YAAY,EACV,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnE,YAAY,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC1D,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACV,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACnE,YAAY,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMhE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC3E,YAAY,EACV,QAAQ,IAAI,gBAAgB,EAC5B,KAAK,IAAI,aAAa,EACtB,YAAY,GACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/types/resources/resource-loader.d.ts

@@ -0,0 +1,6 @@
+export interface ResourceLoader {
+    load(resourceName: string, type?: 'text'): Promise<string>;
+    load(resourceName: string, type: 'binary'): Promise<Buffer>;
+    load(resourceName: string, type?: 'text' | 'binary'): Promise<string | Buffer>;
+}
+//# sourceMappingURL=resource-loader.d.ts.map

package/dist/types/resources/resource-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-loader.d.ts","sourceRoot":"","sources":["../../../src/resources/resource-loader.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3D,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5D,IAAI,CACF,YAAY,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GACvB,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CAC7B"}

package/dist/types/resources/resources.d.ts

@@ -0,0 +1,23 @@
+import { ResourceLoader } from './resource-loader.js';
+export declare const RESOURCE_TYPES: readonly ["text", "binary"];
+export type ResourceType = (typeof RESOURCE_TYPES)[number];
+export interface Entry {
+    type: ResourceType;
+    path: string;
+    key: string;
+}
+export interface Manifest {
+    [key: string]: ManifestEntry;
+}
+type ManifestEntry = Entry | Manifest;
+interface Resource {
+    load: () => Promise<string | Buffer>;
+    loadText: () => Promise<string>;
+    loadBinary: () => Promise<Buffer>;
+}
+export interface Resources {
+    [key: string]: Resource | Resources;
+}
+export declare function createResources<M extends Manifest>(loader: ResourceLoader, initialManifest: M): Resources;
+export {};
+//# sourceMappingURL=resources.d.ts.map

package/dist/types/resources/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../../src/resources/resources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,eAAO,MAAM,cAAc,6BAA8B,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC;CAC9B;AAED,KAAK,aAAa,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEtC,UAAU,QAAQ;IAChB,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IACrC,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,SAAS;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;CACrC;AAMD,wBAAgB,eAAe,CAAC,CAAC,SAAS,QAAQ,EAChD,MAAM,EAAE,cAAc,EACtB,eAAe,EAAE,CAAC,aAwOnB"}

package/dist/types/test-utils.d.ts

@@ -0,0 +1,94 @@
+import type { ObjectGenerator, Message } from './clients/types.js';
+import { z } from 'zod';
+import { jest } from '@jest/globals';
+import type { Brain } from './dsl/brain.js';
+import type { State } from './dsl/types.js';
+import type { Resources } from './resources/resources.js';
+/**
+ * Mock implementation of ObjectGenerator for testing
+ */
+export declare class MockObjectGenerator implements ObjectGenerator {
+    private generateObjectMock;
+    private calls;
+    constructor();
+    generateObject<T extends z.AnyZodObject>(params: Parameters<ObjectGenerator['generateObject']>[0]): Promise<z.infer<T>>;
+    /**
+     * Mock a response for the next generateObject call
+     */
+    mockNextResponse<T>(response: T): void;
+    /**
+     * Mock multiple responses in sequence
+     */
+    mockResponses(...responses: any[]): void;
+    /**
+     * Mock an error for the next generateObject call
+     */
+    mockNextError(error: Error | string): void;
+    /**
+     * Get the underlying jest.Mock for advanced mocking scenarios
+     */
+    get mock(): jest.Mock<any>;
+    /**
+     * Clear all mocks and call history
+     */
+    clear(): void;
+    /**
+     * Reset mock to initial state
+     */
+    reset(): void;
+    /**
+     * Get all calls made to generateObject
+     */
+    getCalls(): {
+        params: Parameters<ObjectGenerator["generateObject"]>[0];
+        timestamp: Date;
+    }[];
+    /**
+     * Get the last call made to generateObject
+     */
+    getLastCall(): {
+        params: Parameters<ObjectGenerator["generateObject"]>[0];
+        timestamp: Date;
+    };
+    /**
+     * Assert that generateObject was called with specific parameters
+     */
+    expectCalledWith(expected: {
+        prompt?: string | ((actual: string) => boolean);
+        schemaName?: string;
+        messages?: Message[];
+        system?: string;
+    }): void;
+    /**
+     * Assert that generateObject was called N times
+     */
+    expectCallCount(count: number): void;
+}
+/**
+ * Creates a mock client for testing brains
+ */
+export declare function createMockClient(): MockObjectGenerator;
+/**
+ * Test runner options
+ */
+export interface TestRunnerOptions<TState extends State = State> {
+    client?: ObjectGenerator;
+    resources?: Resources;
+    initialState?: TState;
+}
+/**
+ * Result of running a brain test
+ */
+export interface TestRunResult<TState extends State = State> {
+    finalState: TState;
+    steps: string[];
+    error: Error | null;
+    completed: boolean;
+}
+/**
+ * Runs a brain with test utilities and returns collected data
+ */
+export declare function runBrainTest<TOptions extends object = {}, TState extends State = {}>(brain: Brain<TOptions, TState, any>, options?: TestRunnerOptions<TState> & {
+    brainOptions?: TOptions;
+}): Promise<TestRunResult<TState>>;
+//# sourceMappingURL=test-utils.d.ts.map

package/dist/types/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../src/test-utils.ts"],"names":[],"mappings":"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"}

package/dist/types/testing.d.ts

@@ -0,0 +1,2 @@
+export { createMockClient, MockObjectGenerator, runBrainTest, type TestRunnerOptions, type TestRunResult, } from './test-utils.js';
+//# sourceMappingURL=testing.d.ts.map

package/dist/types/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/testing.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC"}

package/docs/core-testing-guide.md

@@ -0,0 +1,289 @@
+# Core Testing Guide
+
+## Overview
+
+The Core package tests focus on Brain DSL workflows, event sequences, and state management. This guide helps you write effective tests while avoiding common pitfalls.
+
+## Key Testing Patterns
+
+### 1. Brain Event Collection Pattern
+
+**The Challenge**: Brains emit async events that need to be collected and verified.
+
+**Solution**: Always collect ALL events before making assertions:
+
+```typescript
+// CORRECT: Collect all events first
+const events = [];
+for await (const event of brain.run({ client: mockClient })) {
+  events.push(event);
+}
+
+// Now make assertions
+expect(events.map(e => e.type)).toContain(BRAIN_EVENTS.COMPLETE);
+
+// WRONG: Don't try to assert while iterating
+for await (const event of brain.run()) {
+  expect(event).toBeDefined(); // This can miss events!
+}
+```
+
+### 2. State Reconstruction from Patches
+
+**The Challenge**: Brain state is represented as JSON patches, not direct state objects.
+
+**Solution**: Apply patches to reconstruct final state:
+
+```typescript
+import { applyPatches } from '@positronic/core';
+
+// Helper to reconstruct state
+function reconstructState(events: BrainEvent[]) {
+  let state = {};
+  for (const event of events) {
+    if (event.type === BRAIN_EVENTS.STEP_COMPLETE) {
+      state = applyPatches(state, [event.patch]);
+    }
+  }
+  return state;
+}
+
+// Usage
+const events = await collectAllEvents(brain.run());
+const finalState = reconstructState(events);
+expect(finalState).toEqual({ expected: 'state' });
+```
+
+### 3. Mock Setup for AI Clients
+
+**The Challenge**: Brains often depend on AI client calls that need specific mock setup.
+
+**Solution**: Create properly typed mocks:
+
+```typescript
+// Setup mock client with proper typing
+const mockGenerateObject = jest.fn<ObjectGenerator['generateObject']>();
+const mockClient: jest.Mocked<ObjectGenerator> = {
+  generateObject: mockGenerateObject,
+};
+
+// Configure response BEFORE running brain
+mockGenerateObject.mockResolvedValue({ result: 'test data' });
+
+// Now run the brain
+const brain = brain('test').step('Gen', async ({ client }) => {
+  const res = await client.generateObject({ prompt: 'test' });
+  return { data: res.result };
+});
+```
+
+### 4. Resource Loading Mocks
+
+**The Challenge**: Resources use a proxy API that's tricky to mock.
+
+**Solution**: Mock the underlying loader, not the proxy:
+
+```typescript
+const mockResourceLoad = jest.fn();
+const mockResourceLoader: ResourceLoader = {
+  load: mockResourceLoad,
+};
+
+// Setup resource responses
+const mockResources = {
+  'example.txt': { type: 'text', content: 'Hello' },
+  'data.json': { type: 'text', content: '{"key": "value"}' },
+};
+
+mockResourceLoad.mockImplementation(async (path) => {
+  const resource = mockResources[path];
+  if (!resource) throw new Error(`Resource not found: ${path}`);
+  return resource;
+});
+
+// Use in brain - the proxy API will call your mock
+const brain = brain('test').step('Load', async ({ resources }) => {
+  const text = await resources.example.loadText(); // Proxy API
+  return { content: text };
+});
+```
+
+### 5. Testing Error Events
+
+**The Challenge**: Errors emit special events but brain execution continues.
+
+**Solution**: Look for ERROR events, not exceptions:
+
+```typescript
+const errorBrain = brain('test').step('Fail', () => {
+  throw new Error('Step failed');
+});
+
+const events = [];
+for await (const event of errorBrain.run()) {
+  events.push(event);
+}
+
+// Find the error event
+const errorEvent = events.find(e => e.type === BRAIN_EVENTS.ERROR);
+expect(errorEvent).toBeDefined();
+expect(errorEvent?.error.message).toBe('Step failed');
+
+// Brain still completes!
+expect(events.some(e => e.type === BRAIN_EVENTS.COMPLETE)).toBe(true);
+```
+
+### 6. Type Inference Testing
+
+**The Challenge**: Brain DSL uses complex TypeScript inference that needs testing.
+
+**Solution**: Use compile-time type assertions:
+
+```typescript
+// Define a type equality helper
+type AssertEquals<T, U> = T extends U ? (U extends T ? true : false) : false;
+
+// Test that state types are inferred correctly
+const typedBrain = brain('test')
+  .step('Init', () => ({ count: 0 }))
+  .step('Inc', ({ state }) => ({ count: state.count + 1 }));
+
+// Extract the inferred state type
+type InferredState = typeof typedBrain extends Brain<infer S> ? S : never;
+
+// This line will fail compilation if types don't match
+type Test = AssertEquals<InferredState, { count: number }>;
+const _: Test = true;
+```
+
+## Common Pitfalls & Solutions
+
+### Pitfall 1: Forgetting to Mock Client Methods
+
+```typescript
+// WRONG: Forgot to mock generateObject
+const brain = brain('test').step('Gen', async ({ client }) => {
+  const res = await client.generateObject({ prompt: 'test' });
+  return res;
+});
+
+// This will fail with "mockGenerateObject is not a function"
+await brain.run({ client: mockClient });
+
+// CORRECT: Always mock methods before use
+mockGenerateObject.mockResolvedValue({ data: 'test' });
+```
+
+### Pitfall 2: Testing During Event Iteration
+
+```typescript
+// WRONG: Testing while iterating can miss events
+let foundComplete = false;
+for await (const event of brain.run()) {
+  if (event.type === BRAIN_EVENTS.COMPLETE) {
+    foundComplete = true;
+    break; // Stops iteration early!
+  }
+}
+
+// CORRECT: Collect all events first
+const events = await collectAllEvents(brain.run());
+const foundComplete = events.some(e => e.type === BRAIN_EVENTS.COMPLETE);
+```
+
+### Pitfall 3: Not Handling Async Steps
+
+```typescript
+// WRONG: Synchronous step function when async is needed
+const brain = brain('test').step('Async', ({ client }) => {
+  // This won't wait for the promise!
+  client.generateObject({ prompt: 'test' });
+  return { done: true };
+});
+
+// CORRECT: Use async/await
+const brain = brain('test').step('Async', async ({ client }) => {
+  const result = await client.generateObject({ prompt: 'test' });
+  return { done: true, result };
+});
+```
+
+### Pitfall 4: Incorrect Event Sequence Expectations
+
+```typescript
+// WRONG: Expecting only main events
+expect(events.map(e => e.type)).toEqual([
+  BRAIN_EVENTS.START,
+  BRAIN_EVENTS.COMPLETE
+]);
+
+// CORRECT: Include all events in sequence
+expect(events.map(e => e.type)).toEqual([
+  BRAIN_EVENTS.START,
+  BRAIN_EVENTS.STEP_STATUS,    // Don't forget status events!
+  BRAIN_EVENTS.STEP_START,
+  BRAIN_EVENTS.STEP_COMPLETE,
+  BRAIN_EVENTS.STEP_STATUS,
+  BRAIN_EVENTS.COMPLETE
+]);
+```
+
+## Quick Test Template
+
+```typescript
+import { brain, BRAIN_EVENTS, applyPatches } from '@positronic/core';
+import type { ObjectGenerator, ResourceLoader } from '@positronic/core';
+
+describe('my brain feature', () => {
+  // Setup mocks
+  const mockGenerateObject = jest.fn<ObjectGenerator['generateObject']>();
+  const mockClient: jest.Mocked<ObjectGenerator> = {
+    generateObject: mockGenerateObject,
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should do something', async () => {
+    // Configure mocks
+    mockGenerateObject.mockResolvedValue({ result: 'test' });
+
+    // Define brain
+    const testBrain = brain('test')
+      .step('Process', async ({ client }) => {
+        const res = await client.generateObject({ prompt: 'test' });
+        return { processed: res.result };
+      });
+
+    // Collect all events
+    const events = [];
+    for await (const event of testBrain.run({ client: mockClient })) {
+      events.push(event);
+    }
+
+    // Verify final state
+    let finalState = {};
+    for (const event of events) {
+      if (event.type === BRAIN_EVENTS.STEP_COMPLETE) {
+        finalState = applyPatches(finalState, [event.patch]);
+      }
+    }
+    expect(finalState).toEqual({ processed: 'test' });
+
+    // Verify completion
+    expect(events.some(e => e.type === BRAIN_EVENTS.COMPLETE)).toBe(true);
+  });
+});
+```
+
+## Running Tests
+
+```bash
+# From monorepo root (required!)
+npm test -- packages/core           # Run all core tests
+npm test -- brain.test.ts          # Run specific test file
+npm test -- -t "should process"    # Run tests matching pattern
+npm run test:watch                 # Watch mode
+npm run build:workspaces          # Ensure TypeScript compiles
+```