npm package: @openverb/runtime
Description: OpenVerb execution runtime
Latest version: 2.0.0-alpha.6

# @openverb/runtime

The execution runtime for the OpenVerb Framework - a verb-driven application architecture.

## Installation
```bash
npm install @openverb/runtime
```

## Quick Start
```typescript
import { createRuntime, loadVerbs } from '@openverb/runtime'

// Load verb definitions
const verbs = loadVerbs('./verbs')

// Create runtime
const runtime = createRuntime({
  verbs,
  handlers: {
    'handlers/example': async (ctx, args) => {
      return { success: true, data: args }
    }
  },
  adapters: {
    db: myDatabaseAdapter,
    logger: console
  }
})

// Execute a verb
const result = await runtime.execute({
  verbId: 'example.action',
  args: { name: 'test' },
  actor: { type: 'user', id: 'user-123' },
  context: {
    tenantId: 'tenant-1',
    planId: 'free',
    env: 'production',
    requestId: crypto.randomUUID()
  }
})

console.log(result)
// {
//   ok: true,
//   result: { success: true, data: { name: 'test' } },
//   receipt: { ... },
//   events: [ ... ]
// }
```

## Core Concepts

### Verbs
Verbs are JSON definitions that describe actions in your application:
```json
{
  "id": "user.create",
  "version": "1.0.0",
  "summary": "Create a new user",
  "inputSchema": { "type": "object", "properties": { ... } },
  "outputSchema": { "type": "object", "properties": { ... } },
  "effects": ["db.write", "email.send"],
  "handler": "handlers/user/create"
}
```

### Handlers
Handler functions implement the business logic:
```typescript
import type { HandlerContext } from '@openverb/runtime'

export async function handler(
  ctx: HandlerContext,
  args: { email: string; name: string }
) {
  // Access adapters
  await ctx.adapters.db.insert('users', { email: args.email })
  
  // Emit events
  ctx.emitEvent({ type: 'user.created', data: { email: args.email } })
  
  return { userId: '123', email: args.email }
}
```

### Adapters
Adapters provide access to external services:
```typescript
const adapters = {
  db: {
    insert: async (table, data) => { /* ... */ },
    query: async (sql, params) => { /* ... */ }
  },
  logger: console,
  email: emailService
}
```

## API Reference

### `createRuntime(config)`

Creates a new runtime instance.

**Parameters:**
- `config.verbs` - Array of verb definitions
- `config.handlers` - Map of handler functions
- `config.adapters` - External service adapters
- `config.policy?` - Optional policy engine

**Returns:** Runtime instance

### `loadVerbs(directory)`

Loads verb definitions from a directory.

**Parameters:**
- `directory` - Path to directory containing `.json` verb files

**Returns:** Array of verb definitions

### `runtime.execute(request)`

Executes a verb.

**Parameters:**
- `request.verbId` - ID of verb to execute
- `request.args` - Arguments for the verb
- `request.actor` - User/system making the request
- `request.context` - Execution context (tenant, plan, etc.)

**Returns:** `ExecuteResponse` with result, receipt, and events

## Related Packages

- [@openverb/policy](https://www.npmjs.com/package/@openverb/policy) - Policy engine for authorization
- [@openverb/sdk](https://www.npmjs.com/package/@openverb/sdk) - Client SDK with React hooks
- [@openverb/cli](https://www.npmjs.com/package/@openverb/cli) - CLI tools for developers

## License

MIT