@t4h.framework/core 0.4.0 → 0.5.0

package/.ai/skills/framework-core/SKILL.md

@@ -0,0 +1,403 @@
+---
+name: framework-core
+description: >-
+  Author and test T4H Framework workflows, SyncActivity/AsyncActivity classes,
+  Claim dependencies, App manifests, env access, and in-memory workflow runs.
+  Use when importing @t4h.framework/core, building automation apps, orchestrating
+  with History.reconciler, wiring Claim providers, testing with
+  @t4h.framework/core/testing (WorkflowTesting, mockAsyncActivity), nested
+  startWorkflow, EnvDesign, Authorization manifests, or Internals.runWorkflow /
+  Internals.runActivity.
+---
+
+# @t4h.framework/core
+
+Core primitives for **Workflows** (orchestration), **Activities** (work units), and **Claims** (runtime dependencies). The runtime supplies `env`, `claims`, and `history`; this package defines the author API and in-memory test harness.
+
+| Import | Purpose |
+|--------|---------|
+| `@t4h.framework/core` | Workflows, activities, claims, app, env, internals |
+| `@t4h.framework/core/testing` | `WorkflowTesting` — tests/local only |
+
+Node `>=22`. Schemas use TypeBox (`typebox`). See [README.md](../../../README.md) for diagrams.
+
+---
+
+## Concepts
+
+- **Workflow** — orchestration; composes activities via `History.reconciler` (or helpers like `startWorkflow`).
+- **Activity** — `SyncActivity` (`toInput` → `run` → `toOutput`) or `AsyncActivity` (`toInput` → `bootstrap` → `advance` → `toOutput`, optional `onTimeout`).
+- **Claim** — abstract class; activity maps keys → constructors; runtime provides `{ provide, value }`.
+- **History** — replay: existing history entries skip execution; missing entries run activity and record result (`PushActivity`).
+
+Async helpers on `AsyncActivity`: `this.pending()`, `this.done()`, `this.rejected()`.
+
+---
+
+## Workflows
+
+```typescript
+import Type from 'typebox'
+import { Workflow, env } from '@t4h.framework/core'
+
+const bare = new Workflow(async () => ({ ok: true }))
+
+const withMeta = new Workflow(
+  { id: 'cashback/v1', description: 'Process cashback' },
+  async input => ({ value: input.amount * 0.05 }),
+)
+
+const schema = Type.Object({ userId: Type.String(), amount: Type.Number() })
+const validated = new Workflow({ id: 'cashback/v1', schema }, async input => ({
+  value: input.amount * 0.05,
+}))
+```
+
+- `new Workflow(fn)` or `new Workflow(options, fn)` — bad overload throws `Invalid constructor arguments`.
+- `WorkflowInput<T>` — from schema; `undefined` without schema.
+- `workflow.validate` — Ajv when `schema` set; else `null`.
+- Optional `authorization` on workflow/app → `toManifest()`.
+
+---
+
+## Invoking activities
+
+```typescript
+import { History } from '@t4h.framework/core'
+
+const syncResult = await History.reconciler(MySyncActivity, arg1)
+
+const handle = await History.reconciler(WaitAsyncActivity, 'order-1')
+const out = await handle.wait()
+```
+
+- No history: `toInput` then `PushActivity` → runtime runs `run`/`bootstrap`.
+- Replay: uses stored output; async returns `AsyncActivityAwaitable`; `wait()` throws `PushWaitAsyncActivity` if still `pending`.
+- Must run inside `History.run` (workflow runtime / `WorkflowTesting` provide this).
+
+---
+
+## SyncActivity
+
+```typescript
+import { SyncActivity } from '@t4h.framework/core'
+
+class CalculateCashbackActivity extends SyncActivity<
+  [transaction: { amount: number }], // TArgs
+  { amount: number },                  // TInput (Serializable)
+  number,                              // TSerializableOutput
+  number                               // TOutput
+> {
+  public async toInput(transaction: { amount: number }) {
+    return { amount: transaction.amount }
+  }
+  public run(input: { amount: number }) {
+    return Math.floor(input.amount * 0.05)
+  }
+  public toOutput(output: number) {
+    return output
+  }
+}
+```
+
+`toOutput(output, ...args)` receives original designer args.
+
+---
+
+## AsyncActivity
+
+```typescript
+import Type from 'typebox'
+import { AsyncActivity, AsyncActivityResultPending } from '@t4h.framework/core'
+
+const ApprovalSchema = Type.Object({ approved: Type.Boolean() })
+
+class WaitForApprovalActivity extends AsyncActivity<
+  [orderId: string],
+  { orderId: string },
+  { approved: boolean },
+  { approved: boolean },
+  { requestId: string; orderId: string },
+  typeof ApprovalSchema
+> {
+  public async toInput(orderId: string) {
+    return { orderId }
+  }
+  public async bootstrap(input: { orderId: string }) {
+    return this.pending({
+      payload: { requestId: 'req-123', orderId: input.orderId },
+      schema: ApprovalSchema,
+      timeoutAt: new Date(Date.now() + 3_600_000),
+    })
+  }
+  public async advance(
+    payload: Type.Static<typeof ApprovalSchema>,
+    bootstrap: AsyncActivityResultPending<{ requestId: string; orderId: string }>,
+  ) {
+    return payload.approved
+      ? this.done({ approved: true })
+      : this.rejected({ approved: false, requestId: bootstrap.payload?.requestId })
+  }
+  public toOutput(output: { approved: boolean }) {
+    return output
+  }
+}
+```
+
+Results: `AsyncActivityResultPending` | `AsyncActivityResultFulfilled` | `AsyncActivityResultRejected`. Default `onTimeout` → `rejected({ reason: 'timeout' })`.
+
+---
+
+## Claims
+
+```typescript
+import { SyncActivity, Claim } from '@t4h.framework/core'
+
+abstract class UserRepositoryClaim {
+  abstract findById(id: string): Promise<unknown>
+}
+
+class FetchUserActivity extends SyncActivity<[id: string], { id: string }, unknown, unknown> {
+  private readonly claims = new Claim({ repo: UserRepositoryClaim })
+
+  public async toInput(id: string) {
+    return { id }
+  }
+  public async run(input: { id: string }) {
+    return await this.claims.repo.findById(input.id)
+  }
+  public toOutput(output: unknown) {
+    return output
+  }
+}
+```
+
+Provider: `{ provide: UserRepositoryClaim, value: impl }`. Built-ins: `GetWorkflowUniqueIdentifierClaim`, `GetActivityUniqueIdentifierClaim`, `WorkflowClaim` (for `startWorkflow`).
+
+Exceptions: `ClaimKeyNotFoundException`, `ClaimConstructorNotFoundException`, `ClaimStorageNotActiveException`, `ClaimProviderNotFoundException`. Access `claims.*` only inside `Claim.run`.
+
+---
+
+## Nested workflows
+
+```typescript
+import { startWorkflow, WorkflowClaim } from '@t4h.framework/core'
+
+const ref = await startWorkflow(childWorkflow, { ...input, parallel?: boolean })
+// WorkflowRef: status 'fulfilled' | 'rejected', output Serializable
+```
+
+`StartWorkflowActivity`: `parallel: true` → immediate `done`; else `pending` until `advance`. Requires `WorkflowClaim` provider.
+
+---
+
+## App
+
+```typescript
+import { App, Workflow } from '@t4h.framework/core'
+
+const app = new App({
+  id: 'my-automation',
+  description: 'Cashback automation',
+  workflows: [myWorkflow],
+})
+app.addWorkflow(anotherWorkflow) // throws on duplicate workflow.id
+```
+
+`toManifest()` includes workflows + registered `EnvDesign` entries.
+
+---
+
+## Environment
+
+```typescript
+import { env, EnvDesign } from '@t4h.framework/core'
+
+// Under Env.run — string values
+console.log(env.API_URL)
+
+// Typed parsing (registers for app manifest)
+const config = EnvDesign({
+  API_URL: { type: String },
+  RETRIES: { type: Number, defaultValue: '3' },
+  DEBUG: { type: Boolean, isOptional: true },
+})
+```
+
+---
+
+## Serializable & Authorization
+
+**Serializable:** primitives, `null`, `undefined`, `Binary`, `SerializableClass`, arrays/objects thereof. `Binary`: `contentType`, `contentLength`, `stream()`.
+
+**Authorization:** subclass with `toManifest(): AuthorizationManifest` (`pathToModule`, optional `context`); attach to `Workflow` or `App`.
+
+---
+
+## Internals (runtime / unit tests)
+
+```typescript
+import { Internals } from '@t4h.framework/core'
+
+Internals.runWorkflow(workflow, {
+  input,
+  env: { API_URL: 'https://api.example.com' },
+  claims: [{ provide: UserRepositoryClaim, value: impl }],
+  history: [],
+  logs: [],
+})
+
+Internals.runActivity(FetchUserActivity, { env, claims }, a => a.run({ id: '123' }))
+```
+
+Stack: `Env.run` → `Claim.run` → `History.run` → `Logger.run` (workflows). **Test `advance` here** — not via `WorkflowTesting`.
+
+---
+
+## Testing (`@t4h.framework/core/testing`)
+
+Test-only entrypoint — **not** part of the production runtime contract. Import from the subpath export:
+
+```typescript
+import { WorkflowTesting } from '@t4h.framework/core/testing'
+```
+
+`package.json` maps `"./testing"` → `dist/testing/index.js`. The public API is **`WorkflowTesting.run`** only.
+
+### `WorkflowTesting.run`
+
+```typescript
+const output = await WorkflowTesting.run(workflow, input?, options?)
+```
+
+| Option | Type | Default | Purpose |
+|--------|------|---------|---------|
+| `claims` | `readonly ClaimProvider[]` | `[]` | Concrete claim implementations for the run |
+| `env` | `Env.Entries` | `{}` | String env vars (`Env.run`) |
+| `mockAsyncActivity` | function \| outcome array | — | Required when any async activity returns `pending` |
+| `logs` | `Log[]` | internal | Capture `console.log` / `console.error` once per run |
+| `maxTicks` | `number` | `10_000` | Max activity-resolution loops before error |
+
+Typed input follows `WorkflowInput<T>` when the workflow has a `schema`; omit `input` for workflows without one.
+
+### How the driver works
+
+1. Calls `Internals.runWorkflow` with an empty `history`.
+2. On **`PushActivity`**, runs the pushed activity in-process:
+   - **Sync:** `Internals.runActivity` → `run(input)` → append `{ type: 'sync', output }` to history.
+   - **Async:** real `bootstrap`; if already `done`/`rejected`, record and continue; if **`pending`**, apply `mockAsyncActivity` (throws if missing).
+3. Re-runs the workflow with accumulated history until it returns normally or `maxTicks` is exceeded.
+
+This drives sync activities end-to-end and async activities through bootstrap + mocked resolution — **not** through real `advance`.
+
+### Wiring claims in tests
+
+Pass explicit `{ provide, value }` providers — same shape as `Internals.runWorkflow`:
+
+```typescript
+import { WorkflowTesting } from '@t4h.framework/core/testing'
+import { History, type Log } from '@t4h.framework/core'
+
+const logs: Log[] = []
+const output = await WorkflowTesting.run(workflow, input, {
+  env: { API_URL: 'https://example.com' },
+  claims: [{ provide: UserRepositoryClaim, value: mockRepo }],
+  mockAsyncActivity: () => ({ status: 'fulfilled', output: true }),
+  logs,
+})
+```
+
+For a single activity, prefer `Claim.run([...], fn)` or `Internals.runActivity`. Use `WorkflowTesting.run` for full workflow integration tests.
+
+### `mockAsyncActivity`
+
+Required when `bootstrap` returns `pending`:
+
+| `status` | Effect |
+|----------|--------|
+| `fulfilled` | `{ output }` recorded as async fulfilled |
+| `rejected` | `{ reason }` recorded as async rejected |
+| `timeout` | runs the activity's real `onTimeout(pending)` (throws if undefined) |
+
+**Array** — FIFO, one entry per pending async:
+
+```typescript
+mockAsyncActivity: [
+  { status: 'fulfilled', output: true },
+  { status: 'rejected', reason: false },
+]
+```
+
+**Function** — `(activity, { input, pending, index }) => outcome`:
+
+```typescript
+mockAsyncActivity: (activity, { index }) => {
+  if (activity instanceof WaitForApprovalActivity)
+    return { status: 'fulfilled', output: true }
+  if (index === 1) return { status: 'timeout' }
+  return { status: 'rejected', reason: 'denied' }
+}
+```
+
+Bootstrap that already returns `done`/`rejected` needs no mock. Missing mock on pending throws: `pending and no resolveAsyncActivity`. Exhausted array throws: `No more async outcomes`.
+
+### Examples (from `WorkflowTesting.spec.ts`)
+
+**Sync workflow:**
+
+```typescript
+const workflow = new Workflow({ schema }, async input => {
+  const n = await History.reconciler(AddOneActivity, input.value)
+  return n * 10
+})
+await expect(WorkflowTesting.run(workflow, { value: 4 })).resolves.toBe(50)
+```
+
+**Capture logs:**
+
+```typescript
+const logs: Log[] = []
+await WorkflowTesting.run(workflow, undefined, { logs })
+expect(logs.map(entry => entry.args[0])).toEqual(['before activity', 'after activity'])
+```
+
+**Async fulfilled / rejected / timeout:**
+
+```typescript
+await WorkflowTesting.run(workflow, undefined, {
+  mockAsyncActivity: () => ({ status: 'fulfilled', output: true }),
+})
+await WorkflowTesting.run(workflow, undefined, {
+  mockAsyncActivity: () => ({ status: 'rejected', reason: false }),
+})
+await WorkflowTesting.run(workflow, undefined, {
+  mockAsyncActivity: () => ({ status: 'timeout' }),
+})
+```
+
+**Vitest setup** — add `@t4h.framework/core` and `@t4h.framework/core/testing` as devDependencies; run with Vitest (`vitest run`). See `packages/core/src/testing/__tests__/WorkflowTesting.spec.ts`.
+
+### Limits (use `Internals` instead)
+
+- No real **`advance`** — test `advance` via `Internals.runActivity` on the async class.
+- No **`PushWaitAsyncActivity`** / resuming pending `handle.wait()` across ticks.
+- Do not import `@t4h.framework/core/testing` in production app code.
+
+---
+
+## Anti-patterns
+
+- Claims or `env` outside `Claim.run` / `Env.run`.
+- `History.reconciler` outside `History.run`.
+- Pending async tests without `mockAsyncActivity`.
+- `advance` coverage only via `WorkflowTesting` (use `Internals.runActivity`).
+- Non-`Serializable` activity I/O.
+- Duplicate `workflow.id` in `App`.
+- `@t4h.framework/core/testing` in production.
+- APIs not exported from `core.ts` / `testing/index.ts`.
+
+---
+
+## Exports (main)
+
+`Workflow`, `App`, `SyncActivity`, `AsyncActivity`, `Claim`, `History`, `env`, `EnvDesign`, `Authorization`, `WorkflowRef`, `Binary`, `Serializable`, async result types, `startWorkflow`, `WorkflowClaim`, `Internals`, `isActivity`, `Logger`, `Activity` types, exceptions. **Testing:** `WorkflowTesting` only.

package/.ai/skills/framework-workflow-creation/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: framework-workflow-creation
+description: >-
+  Design and implement T4H Framework workflows with @t4h.framework/core using
+  the project's standard structure for workflow files, app registration, and
+  environment handling. Use this whenever the user asks to create a new
+  workflow, wire it into an App, define orchestration with History.reconciler,
+  or refactor workflow code to remove hardcoded URLs/secrets/client values and
+  move configuration to env constants.
+---
+
+# Create workflows with `@t4h.framework/core`
+
+Use this skill to build production-ready workflow modules that are easy to register, test, and maintain.
+
+## Primary goal
+
+Create workflows that:
+
+- expose a `Workflow` constant with explicit metadata (`id`, optional `description`, optional `schema`);
+- orchestrate work through framework primitives (`History.reconciler`, `startWorkflow`) instead of ad-hoc infrastructure code;
+- register cleanly in `App` with `export default new App({...})`;
+- never hardcode URLs, secrets, tokens, client IDs, or tenants in workflow files.
+
+## Expected project shape
+
+### Workflow module
+
+```ts
+import { Workflow } from '@t4h.framework/core'
+
+export const myWorkflow = new Workflow({ id: 'my-workflow' }, async input => {
+  // orchestration only
+})
+```
+
+### App declaration
+
+```ts
+import { App } from '@t4h.framework/core'
+import { myWorkflow } from './workflows/my-workflow.js'
+
+export default new App({
+  id: 'my-app',
+  description: 'My app',
+  workflows: [myWorkflow],
+})
+```
+
+### Environment constants module
+
+```ts
+import { env } from '@t4h.framework/core'
+
+export const SERVICE_URL = env.SERVICE_URL!
+if (!SERVICE_URL) throw new TypeError('SERVICE_URL is not defined')
+```
+
+Keep this in a dedicated constants file and import values into workflows/activities.
+
+## Core APIs to prefer while authoring workflows
+
+- `Workflow` for orchestration entrypoints.
+- `History.reconciler(ActivityClass, ...args)` to execute activities deterministically.
+- `startWorkflow(childWorkflow, { ...input, parallel? })` for nested workflow orchestration.
+- `App` to register workflow modules for runtime discovery.
+- `env` / `EnvDesign` for configuration contracts (not inline literal secrets).
+
+## Authoring rules
+
+1. Keep workflows orchestration-focused. Put low-level operations in activities and claims.
+2. Define workflow metadata with stable `id`.
+3. Use schema when input validation is needed.
+4. Import configuration from environment constants.
+5. Keep side effects explicit and easy to assert in tests.
+
+## Hard constraints
+
+- Do not hardcode URLs, client IDs, client secrets, API keys, tenants, or tokens.
+- Do not initialize third-party clients with inline credentials inside workflow files.
+- Do not read `process.env` directly in workflow modules when the project uses centralized constants via `env`.
+
+If a required env key is missing, fail fast with a clear `TypeError` in the constants module.
+
+## Workflow implementation recipe
+
+### Step 1: define/extend env constants
+
+- Add required keys in a constants module.
+- Export each key from `env.<KEY>!`.
+- Validate each key immediately with an explicit `TypeError`.
+
+### Step 2: create workflow file
+
+- Import `Workflow` and required orchestration helpers.
+- Import only typed/safe constants (never raw secrets inline).
+- Implement the function body as orchestration steps.
+
+### Step 3: wire in App
+
+- Import the workflow module in `main.tsx`.
+- Add it to `workflows: [...]` in `new App({...})`.
+- Keep `App` declaration as default export for runtime loading.
+
+### Step 4: make it test-friendly
+
+- Keep outputs deterministic where possible.
+- Avoid hidden global state.
+- Structure side effects so they can be mocked by claim/activity tests.
+
+## Recommended patterns
+
+### A) Workflow with validated input schema
+
+```ts
+import Type from 'typebox'
+import { Workflow } from '@t4h.framework/core'
+
+const schema = Type.Object({
+  customerId: Type.String(),
+})
+
+export const customerSync = new Workflow(
+  { id: 'customer-sync', schema },
+  async input => {
+    return { accepted: true, customerId: input.customerId }
+  },
+)
+```
+
+### B) Workflow orchestrating activities
+
+```ts
+import { History, Workflow } from '@t4h.framework/core'
+
+export const processOrder = new Workflow({ id: 'process-order' }, async input => {
+  const prepared = await History.reconciler(PrepareOrderActivity, input)
+  const charged = await History.reconciler(ChargeOrderActivity, prepared)
+  return { charged }
+})
+```
+
+### C) Nested workflow orchestration
+
+```ts
+import { Workflow, startWorkflow } from '@t4h.framework/core'
+import { childWorkflow } from './child-workflow.js'
+
+export const parentWorkflow = new Workflow({ id: 'parent-workflow' }, async input => {
+  const ref = await startWorkflow(childWorkflow, input)
+  return ref.output
+})
+```
+
+## Anti-patterns to remove on sight
+
+- Inline `"https://..."` service endpoints in workflow body.
+- Inline `"secret"` / `"clientId"` string literals in workflow code.
+- Creating SDK/API clients with literal credentials in the workflow function.
+- Large workflow functions doing infrastructure plumbing instead of orchestration.
+- Registering workflows in scattered places instead of centralized `App` declaration.
+
+## Output expectations when executing this skill
+
+When asked to create a workflow, produce:
+
+1. A new workflow file exporting a named `Workflow` constant.
+2. Any required env constants in the central constants module.
+3. `App` registration update with the workflow included.
+4. No hardcoded client, secret, token, tenant, or URL values in workflow code.

package/.ai/skills/framework-workflow-testing/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: framework-workflow-testing
+description: >-
+  Build and maintain high-quality unit tests for T4H Framework workflows using
+  @t4h.framework/core/testing. Use this whenever the user asks to test a
+  workflow, add Vitest coverage for History.reconciler flows, mock claims,
+  validate logs, or simulate async activity outcomes (fulfilled/rejected/timeout),
+  even when they only mention "workflow test", "mock claim", or "run workflow in memory".
+---
+
+# Workflow unit testing with `@t4h.framework/core/testing`
+
+Use this skill to create or improve **workflow-focused unit tests** in T4H Framework projects.
+
+## What this skill optimizes
+
+- Fast in-memory workflow execution with `WorkflowTesting.run`.
+- Reliable claim mocking with real claim instances + `vi.spyOn`.
+- Clear assertions for behavior (calls, payload, order, and logs).
+- Predictable handling of async activities with `mockAsyncActivity`.
+
+## When to choose this skill
+
+Choose this skill when the user asks to:
+
+- test a `Workflow` end-to-end (without infra);
+- mock outbound dependencies used by activities (HTTP, DB, etc.);
+- assert emitted logs for workflow execution paths;
+- simulate async activity outcomes in tests;
+- add or fix `vitest` tests for workflow modules.
+
+If the request is specifically about testing `AsyncActivity.advance`, use `Internals.runActivity` directly instead of only `WorkflowTesting.run`.
+
+## Public API available
+
+```ts
+import { WorkflowTesting } from '@t4h.framework/core/testing'
+```
+
+`WorkflowTesting.run(workflow, input?, options?)`
+
+Supported options:
+
+- `claims`: claim providers used during execution.
+- `env`: environment entries for `Env.run`.
+- `mockAsyncActivity`: function or queue for pending async activities.
+- `logs`: capture runtime logs.
+- `maxTicks`: protect against infinite replay loops (default `10_000`).
+
+## Canonical workflow test pattern
+
+Follow this structure by default:
+
+1. Arrange claims and spies in helper functions.
+2. Initialize setup in `beforeEach`.
+3. Execute workflow with `WorkflowTesting.run`.
+4. Assert calls, payload structure, ordering, and logs.
+
+Base mock style on this pattern:
+
+```ts
+function createClaimsWithHttpSpy() {
+  const http = findClaimByConstructor(DevHttpClientRequestClaim)
+  const mockRequest = vi.spyOn(http, 'request').mockResolvedValue({
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+    body: Readable.from(Buffer.from('{}')),
+  })
+  return { claims, mockRequest }
+}
+```
+
+Why this pattern: it keeps tests close to real wiring while still allowing strict call inspection.
+
+## Standard recipe for new tests
+
+### 1) Create setup helpers
+
+- Put claim setup and spies in dedicated functions (`createClaimsWith...`).
+- Return both `claims` and the spy object(s) for assertions.
+- Keep data decoders (e.g. request-body parser) as small utility functions.
+
+### 2) Execute workflow under test
+
+- Use `await WorkflowTesting.run(workflow, input, { claims, logs, ... })`.
+- Capture logs with `const logs: Log[] = []` when log behavior matters.
+
+### 3) Assert behavior and contract
+
+Prefer these assertions:
+
+- call count (`toHaveBeenCalledTimes`);
+- important call arguments (URL, method, payload);
+- ordering (`mock.calls[0]`, `mock.calls[1]`);
+- final workflow output;
+- log messages and sequence (`logs.map(entry => entry.args[0])`).
+
+### 4) Cover async outcomes when applicable
+
+If any async activity can return `pending`, provide `mockAsyncActivity`.
+
+Function strategy:
+
+```ts
+mockAsyncActivity: (activity, { index, pending }) => {
+  if (index === 0) return { status: 'fulfilled', output: true }
+  return { status: 'rejected', reason: 'denied' }
+}
+```
+
+Queue strategy:
+
+```ts
+mockAsyncActivity: [
+  { status: 'fulfilled', output: true },
+  { status: 'timeout' },
+]
+```
+
+Important behavior:
+
+- no resolver + pending async => throws;
+- timeout outcome runs real `onTimeout`;
+- exhausted queue => throws `No more async outcomes`.
+
+## Mocking guidelines (do this, avoid that)
+
+Do:
+
+- mock concrete claim instances used by runtime providers;
+- use `vi.spyOn` on dependency methods (e.g. `request`);
+- return realistic shapes (status/headers/body) for external call mocks;
+- isolate each test with `beforeEach`.
+
+Avoid:
+
+- over-mocking framework internals;
+- asserting implementation details unrelated to behavior;
+- using `WorkflowTesting.run` to validate real `advance` logic.
+
+## Minimal template to generate quickly
+
+```ts
+import { WorkflowTesting } from '@t4h.framework/core/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+describe('my workflow', () => {
+  let claims: ReturnType<typeof createClaimsWithSpy>['claims']
+  let mockCall: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    const setup = createClaimsWithSpy()
+    claims = setup.claims
+    mockCall = setup.mockCall
+  })
+
+  it('runs to completion with expected side effects', async () => {
+    const logs = []
+    await WorkflowTesting.run(myWorkflow, undefined, { claims, logs })
+    expect(mockCall).toHaveBeenCalledTimes(1)
+  })
+})
+```
+
+## Completion checklist before finishing
+
+- Test imports `WorkflowTesting` from `@t4h.framework/core/testing`.
+- Claim providers are passed via `options.claims`.
+- Pending async paths have `mockAsyncActivity`.
+- Assertions cover side effects and expected ordering.
+- Logs are asserted when they are part of the workflow contract.
+- Test file uses Vitest idioms consistently.

package/README.md

@@ -190,10 +190,7 @@ For long-running operations that need a bootstrap/advance cycle (e.g. waiting fo
 
 ```typescript
 import Type from 'typebox'
-import {
-  AsyncActivity,
-  AsyncActivityResultPending,
-} from '@t4h.framework/core'
+import { AsyncActivity, AsyncActivityResultPending } from '@t4h.framework/core'
 
 const ApprovalSchema = Type.Object({
   approved: Type.Boolean(),
@@ -243,7 +240,10 @@ class WaitForApprovalActivity extends AsyncActivity<
   }
 
   public async onTimeout(
-    bootstrap: AsyncActivityResultPending<{ requestId: string; orderId: string }>,
+    bootstrap: AsyncActivityResultPending<{
+      requestId: string
+      orderId: string
+    }>,
   ) {
     return this.rejected({
       approved: false,
@@ -346,3 +346,76 @@ Env.run → Claim.run → fn(activity)
 ```
 
 **History** handles reconciliation: when an activity has been executed before, the previous result is returned directly (deterministic replay). When there is no history, the activity runs and the result is stored.
+
+---
+
+## Testing
+
+For running a workflow fully in-memory (driving its activities to completion in a
+single process), use the dedicated `testing` entrypoint. It is meant for tests and
+local execution only and is not part of the runtime contract.
+
+```typescript
+import { WorkflowTesting } from '@t4h.framework/core/testing'
+
+const output = await WorkflowTesting.run<MyWorkflow>(myWorkflow, input, {
+  env: { API_URL: 'https://api.example.com' },
+  claims: [
+    { provide: UserRepositoryClaim, value: new UserRepositoryClaimImpl() },
+  ],
+  mockAsyncActivity: () => ({ status: 'fulfilled', output: true }),
+})
+```
+
+### Driving async activities
+
+The harness runs the real `bootstrap`. If it already settles (`done`/`rejected`),
+that result is honored. If it returns `pending`, you **must** provide a
+`mockAsyncActivity` mock that declares the outcome for that activity — otherwise
+the run throws. This forces each test to consciously pick the scenario it covers.
+
+The mock returns an outcome (not an `advance` payload):
+
+```typescript
+// success
+mockAsyncActivity: () => ({ status: 'fulfilled', output: true })
+
+// rejection
+mockAsyncActivity: () => ({ status: 'rejected', reason: 'denied' })
+
+// timeout — runs the activity's real onTimeout(pending) policy
+mockAsyncActivity: () => ({ status: 'timeout' })
+```
+
+For workflows with several async activities in a fixed order, pass an array of
+outcomes — each pending async consumes the next entry (FIFO):
+
+```typescript
+mockAsyncActivity: [
+  { status: 'fulfilled', output: true },
+  { status: 'rejected', reason: 'denied' },
+  { status: 'timeout' },
+]
+```
+
+The mock receives the activity instance and `{ input, pending, index }`, so you
+can branch per activity or per resolution order:
+
+```typescript
+mockAsyncActivity: (activity, { index }) => {
+  if (activity instanceof WaitForApprovalActivity)
+    return { status: 'fulfilled', output: true }
+
+  if (index === 1) return { status: 'timeout' }
+
+  return { status: 'rejected', reason: 'denied' }
+}
+```
+
+You can also build the same FIFO behavior explicitly with
+`resolveAsyncActivitiesInOrder([...])` from `@t4h.framework/core/testing`.
+
+> The real `advance` logic is intentionally **not** exercised here — drive it in a
+> dedicated activity-level test via `Internals.runActivity`. The pending/resume
+> boundary (`PushWaitAsyncActivity`) is also not modeled: an async activity is a
+> single decision point per run.

package/dist/testing/WorkflowTesting.d.ts

@@ -0,0 +1,6 @@
+import { type RunWorkflowOptions } from './run-workflow.js';
+import type { Workflow, WorkflowInput } from '../models/Workflow.js';
+export declare class WorkflowTesting {
+    static run<T extends Workflow<any, any>>(workflow: T, input?: WorkflowInput<T>, options?: RunWorkflowOptions): Promise<any>;
+}
+//# sourceMappingURL=WorkflowTesting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WorkflowTesting.d.ts","sourceRoot":"","sources":["../../src/testing/WorkflowTesting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAEpE,qBAAa,eAAe;WACN,GAAG,CAAC,CAAC,SAAS,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EAClD,QAAQ,EAAE,CAAC,EACX,KAAK,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,OAAO,CAAC,EAAE,kBAAkB;CAI/B"}

package/dist/testing/WorkflowTesting.js

@@ -0,0 +1,7 @@
+import { runWorkflow } from './run-workflow.js';
+export class WorkflowTesting {
+    static async run(workflow, input, options) {
+        return runWorkflow(workflow, input, options);
+    }
+}
+//# sourceMappingURL=WorkflowTesting.js.map

package/dist/testing/WorkflowTesting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkflowTesting.js","sourceRoot":"","sources":["../../src/testing/WorkflowTesting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAA;AAGxE,MAAM,OAAO,eAAe;IACnB,MAAM,CAAC,KAAK,CAAC,GAAG,CACrB,QAAW,EACX,KAAwB,EACxB,OAA4B;QAE5B,OAAO,WAAW,CAAC,QAAQ,EAAE,KAAyB,EAAE,OAAO,CAAC,CAAA;IAClE,CAAC;CACF"}

package/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './WorkflowTesting.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAA"}

package/dist/testing/index.js

@@ -0,0 +1,2 @@
+export * from './WorkflowTesting.js';
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAA"}

package/dist/testing/run-workflow.d.ts

@@ -0,0 +1,31 @@
+import { type AnyAsyncActivity } from '../models/AsyncActivity.js';
+import { AsyncActivityResultPending } from '../models/AsyncActivityAdvanceResult.js';
+import type { ClaimProvider } from '../models/Claim.js';
+import { Env } from '../models/Env.js';
+import type { Log } from '../models/Logger.js';
+import type { Workflow, WorkflowInput } from '../models/Workflow.js';
+interface MockAsyncActivityContext {
+    input: unknown;
+    pending: AsyncActivityResultPending;
+    index: number;
+}
+export type AsyncActivityOutcome = {
+    status: 'fulfilled';
+    output?: unknown;
+} | {
+    status: 'rejected';
+    reason?: unknown;
+} | {
+    status: 'timeout';
+};
+type MockAsyncActivity = (activity: AnyAsyncActivity, context: MockAsyncActivityContext) => AsyncActivityOutcome | Promise<AsyncActivityOutcome>;
+export interface RunWorkflowOptions {
+    claims?: readonly ClaimProvider<any>[];
+    env?: Env.Entries;
+    mockAsyncActivity?: MockAsyncActivity | readonly AsyncActivityOutcome[];
+    maxTicks?: number;
+    logs?: Log[];
+}
+export declare function runWorkflow<T extends Workflow<any, any>>(workflow: T, input: WorkflowInput<T>, options?: RunWorkflowOptions): Promise<any>;
+export {};
+//# sourceMappingURL=run-workflow.d.ts.map

package/dist/testing/run-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-workflow.d.ts","sourceRoot":"","sources":["../../src/testing/run-workflow.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAEL,0BAA0B,EAE3B,MAAM,yCAAyC,CAAA;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAEtC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAA;AAG9C,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAGpE,UAAU,wBAAwB;IAChC,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,0BAA0B,CAAA;IACnC,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACzC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACxC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAA;AAEzB,KAAK,iBAAiB,GAAG,CACvB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,wBAAwB,KAC9B,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;AAEzD,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,SAAS,aAAa,CAAC,GAAG,CAAC,EAAE,CAAA;IACtC,GAAG,CAAC,EAAE,GAAG,CAAC,OAAO,CAAA;IACjB,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,oBAAoB,EAAE,CAAA;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;CACb;AA6BD,wBAAsB,WAAW,CAAC,CAAC,SAAS,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EAC5D,QAAQ,EAAE,CAAC,EACX,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,OAAO,GAAE,kBAAuB,gBAmCjC"}

package/dist/testing/run-workflow.js

@@ -0,0 +1,102 @@
+import { AsyncActivity, } from '../models/AsyncActivity.js';
+import { AsyncActivityResultFulfilled, AsyncActivityResultPending, AsyncActivityResultRejected, } from '../models/AsyncActivityAdvanceResult.js';
+import { Env } from '../models/Env.js';
+import { PushActivity } from '../models/PushActivity.js';
+import { SyncActivity } from '../models/SyncActivity.js';
+import { Internals } from '../tools/Internals.js';
+function mockAsyncActivities(outcomes) {
+    const queue = [...outcomes];
+    return (activity, context) => {
+        const next = queue.shift();
+        if (!next)
+            throw new Error(`No more async outcomes (activity: "${activity.constructor.name}", index: ${context.index}, input: ${JSON.stringify(context.input)})`);
+        return next;
+    };
+}
+function normalizeMockAsyncActivity(mock) {
+    if (!mock)
+        return undefined;
+    if (Array.isArray(mock))
+        return mockAsyncActivities(mock);
+    return mock;
+}
+export async function runWorkflow(workflow, input, options = {}) {
+    const claims = options.claims ?? [];
+    const env = options.env ?? {};
+    const maxTicks = options.maxTicks ?? 10_000;
+    const history = [];
+    const logs = options.logs ?? [];
+    const mocks = normalizeMockAsyncActivity(options.mockAsyncActivity);
+    const resolutionState = { index: 0 };
+    for (let tick = 0; tick < maxTicks; tick++) {
+        try {
+            return await Internals.runWorkflow(workflow, {
+                input,
+                claims,
+                env,
+                history,
+                logs,
+            });
+        }
+        catch (pushOrError) {
+            if (!(pushOrError instanceof PushActivity))
+                throw pushOrError;
+            const item = await resolveActivity(pushOrError, { claims, env }, mocks, resolutionState);
+            history.push(item);
+        }
+    }
+    throw new Error(`Workflow did not settle within ${maxTicks} ticks`);
+}
+async function resolveActivity(push, context, mockAsyncActivity, resolutionState) {
+    const activity = push.activity;
+    if (activity instanceof SyncActivity) {
+        const output = await Internals.runActivity(activity, context, instance => instance.run(push.input));
+        return { type: 'sync', output };
+    }
+    if (activity instanceof AsyncActivity) {
+        const bootstrap = await Internals.runActivity(activity, context, instance => instance.bootstrap(push.input));
+        return resolveAsyncActivity(activity, bootstrap, context, push.input, mockAsyncActivity, resolutionState);
+    }
+    throw new Error('Unknown activity type');
+}
+async function resolveAsyncActivity(activity, bootstrap, context, input, mockAsyncActivity, resolutionState) {
+    if (bootstrap instanceof AsyncActivityResultFulfilled)
+        return { type: 'async', status: 'fulfilled', output: bootstrap.payload };
+    if (bootstrap instanceof AsyncActivityResultRejected)
+        return { type: 'async', status: 'rejected', output: bootstrap.payload };
+    if (!(bootstrap instanceof AsyncActivityResultPending))
+        throw new Error('Unknown async activity result');
+    const name = activity.constructor.name;
+    if (!mockAsyncActivity)
+        throw new Error(`Async activity "${name}" is pending and no resolveAsyncActivity was provided`);
+    const outcome = await mockAsyncActivity(activity, {
+        input,
+        pending: bootstrap,
+        index: resolutionState?.index ?? 0,
+    });
+    if (resolutionState)
+        resolutionState.index++;
+    return outcomeToHistoryItem(activity, outcome, bootstrap, context, name);
+}
+async function outcomeToHistoryItem(activity, outcome, pending, context, name) {
+    switch (outcome.status) {
+        case 'fulfilled':
+            return { type: 'async', status: 'fulfilled', output: outcome.output };
+        case 'rejected':
+            return { type: 'async', status: 'rejected', output: outcome.reason };
+        case 'timeout': {
+            const onTimeout = activity.onTimeout?.bind(activity);
+            if (!onTimeout)
+                throw new Error(`Async activity "${name}" timed out but defines no onTimeout handler`);
+            const result = await Internals.runActivity(activity, context, () => onTimeout(pending));
+            if (result instanceof AsyncActivityResultFulfilled)
+                return { type: 'async', status: 'fulfilled', output: result.payload };
+            if (result instanceof AsyncActivityResultRejected)
+                return { type: 'async', status: 'rejected', output: result.payload };
+            throw new Error(`Async activity "${name}" stayed pending after onTimeout`);
+        }
+        default:
+            throw new Error(`Unknown async activity outcome for "${name}"`);
+    }
+}
+//# sourceMappingURL=run-workflow.js.map

package/dist/testing/run-workflow.js.map

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

package/dist/tools/runWorkflowToCompletion.d.ts

@@ -0,0 +1,15 @@
+import { AsyncActivity } from '../models/AsyncActivity.js';
+import type { ClaimProvider } from '../models/Claim.js';
+import { Env } from '../models/Env.js';
+import type { Log } from '../models/Logger.js';
+import type { Workflow, WorkflowInput } from '../models/Workflow.js';
+export type AsyncActivityResolver = (activity: AsyncActivity<any, any, any, any, any, any>, input: unknown) => unknown | Promise<unknown>;
+export interface RunWorkflowToCompletionOptions {
+    claims?: readonly ClaimProvider<any>[];
+    env?: Env.Entries;
+    resolveAsyncActivity?: AsyncActivityResolver;
+    maxTicks?: number;
+    logs?: Log[];
+}
+export declare function runWorkflowToCompletion<T extends Workflow<any, any>>(workflow: T, input: WorkflowInput<T>, options?: RunWorkflowToCompletionOptions): Promise<any>;
+//# sourceMappingURL=runWorkflowToCompletion.d.ts.map

package/dist/tools/runWorkflowToCompletion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runWorkflowToCompletion.d.ts","sourceRoot":"","sources":["../../src/tools/runWorkflowToCompletion.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAM1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAEtC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAA;AAG9C,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAGpE,MAAM,MAAM,qBAAqB,GAAG,CAClC,QAAQ,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACrD,KAAK,EAAE,OAAO,KACX,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAE/B,MAAM,WAAW,8BAA8B;IAC7C,MAAM,CAAC,EAAE,SAAS,aAAa,CAAC,GAAG,CAAC,EAAE,CAAA;IACtC,GAAG,CAAC,EAAE,GAAG,CAAC,OAAO,CAAA;IACjB,oBAAoB,CAAC,EAAE,qBAAqB,CAAA;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;CACb;AAED,wBAAsB,uBAAuB,CAAC,CAAC,SAAS,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EACxE,QAAQ,EAAE,CAAC,EACX,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,OAAO,GAAE,8BAAmC,gBAgC7C"}

package/dist/tools/runWorkflowToCompletion.js

@@ -0,0 +1,61 @@
+import { AsyncActivity } from '../models/AsyncActivity.js';
+import { AsyncActivityResultFulfilled, AsyncActivityResultPending, AsyncActivityResultRejected, } from '../models/AsyncActivityAdvanceResult.js';
+import { Env } from '../models/Env.js';
+import { PushActivity } from '../models/PushActivity.js';
+import { SyncActivity } from '../models/SyncActivity.js';
+import { Internals } from './Internals.js';
+export async function runWorkflowToCompletion(workflow, input, options = {}) {
+    const claims = options.claims ?? [];
+    const env = options.env ?? {};
+    const maxTicks = options.maxTicks ?? 10_000;
+    const history = [];
+    const logs = options.logs ?? [];
+    for (let tick = 0; tick < maxTicks; tick++) {
+        try {
+            return await Internals.runWorkflow(workflow, {
+                input,
+                claims,
+                env,
+                history,
+                logs,
+            });
+        }
+        catch (pushOrError) {
+            if (!(pushOrError instanceof PushActivity))
+                throw pushOrError;
+            const item = await resolveActivity(pushOrError, { claims, env }, options.resolveAsyncActivity);
+            history.push(item);
+        }
+    }
+    throw new Error(`Workflow did not settle within ${maxTicks} ticks`);
+}
+async function resolveActivity(push, context, resolver) {
+    const activity = push.activity;
+    if (activity instanceof SyncActivity) {
+        const output = await Internals.runActivity(activity, context, instance => instance.run(push.input));
+        return { type: 'sync', output };
+    }
+    if (activity instanceof AsyncActivity) {
+        const bootstrap = await Internals.runActivity(activity, context, instance => instance.bootstrap(push.input));
+        const settled = await settleAsyncActivity(activity, bootstrap, context, push.input, resolver);
+        return settled;
+    }
+    throw new Error('Unknown activity type');
+}
+async function settleAsyncActivity(activity, result, context, input, resolver) {
+    if (result instanceof AsyncActivityResultFulfilled)
+        return { type: 'async', status: 'fulfilled', output: result.payload };
+    if (result instanceof AsyncActivityResultRejected)
+        return { type: 'async', status: 'rejected', output: result.payload };
+    if (!(result instanceof AsyncActivityResultPending))
+        throw new Error('Unknown async activity result');
+    const name = activity.constructor.name;
+    if (!resolver)
+        throw new Error(`Async activity "${name}" is pending and no resolveAsyncActivity was provided`);
+    const payload = await resolver(activity, input);
+    const advanced = await Internals.runActivity(activity, context, instance => instance.advance(payload, result));
+    if (advanced instanceof AsyncActivityResultPending)
+        throw new Error(`Async activity "${name}" stayed pending after advance`);
+    return settleAsyncActivity(activity, advanced, context, input, resolver);
+}
+//# sourceMappingURL=runWorkflowToCompletion.js.map

package/dist/tools/runWorkflowToCompletion.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Core module for the T4H Framework",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/core",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -13,14 +13,21 @@
   "author": "Tech4Humans <contact@tech4h.com.br> (https://tech4h.com.br)",
   "type": "module",
   "exports": {
-    "types": "./dist/core.d.ts",
-    "import": "./dist/core.js"
+    ".": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
   },
   "module": "./dist/core.js",
   "types": "./dist/core.d.ts",
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    ".ai"
   ],
   "scripts": {
     "build": "tsc --project tsconfig.build.json",