@openverb/runtime 2.0.0-alpha.1

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@openverb/runtime",
+  "version": "2.0.0-alpha.1",
+  "description": "OpenVerb execution runtime",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "ajv": "^8.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.2",
+    "vitest": "^1.0.4"
+  },
+  "keywords": ["openverb", "runtime", "execution"],
+  "license": "MIT"
+}

package/src/engine.ts

@@ -0,0 +1,166 @@
+import crypto from 'node:crypto'
+import { loadVerbs, getVerbById } from './registry'
+import { validateInput, validateOutput } from './validator'
+import { VerbNotFoundError, PolicyDeniedError, HandlerError } from './errors'
+import type {
+  Runtime,
+  ExecuteRequest,
+  ExecuteResponse,
+  VerbDefinition,
+  PolicyEngine,
+  Handler,
+  Event,
+  Receipt,
+  HandlerContext
+} from './types'
+
+type RuntimeConfig = {
+  verbs?: VerbDefinition[]
+  verbsDir?: string
+  policy: PolicyEngine
+  handlers: Record<string, Handler>
+  adapters?: Record<string, any>
+  onEvent?: (event: Event) => void | Promise<void>
+  onReceipt?: (receipt: Receipt) => void | Promise<void>
+}
+
+export function createRuntime(config: RuntimeConfig): Runtime {
+  const verbs = config.verbs || loadVerbs(config.verbsDir)
+  const events: Event[] = []
+  const executionId = crypto.randomUUID()
+
+  async function execute(req: ExecuteRequest): Promise<ExecuteResponse> {
+    const startTime = Date.now()
+    
+    // Stage 1: Resolve verb
+    const verb = getVerbById(req.verbId, verbs)
+    if (!verb) {
+      const receipt = createReceipt(req, 'error', startTime)
+      return {
+        ok: false,
+        error: `Verb not found: ${req.verbId}`,
+        receipt,
+        events: []
+      }
+    }
+
+    try {
+      // Stage 2: Validate input
+      validateInput(verb.inputSchema, req.args)
+
+      // Stage 3: Policy check
+      const decision = await config.policy(verb, req.actor, req.context)
+      
+      emitEvent({
+        type: decision.decision === 'allow' ? 'policy.allowed' : 'policy.denied',
+        data: { verbId: verb.id, decision }
+      })
+
+      if (decision.decision === 'deny') {
+        const receipt = createReceipt(req, 'denied', startTime)
+        await config.onReceipt?.(receipt)
+        
+        return {
+          ok: false,
+          denied: true,
+          reason: { code: decision.code, message: decision.message },
+          upsell: decision.upsell,
+          receipt,
+          events
+        }
+      }
+
+      // Stage 4: Execute handler
+      const handler = config.handlers[verb.handler]
+      if (!handler) {
+        throw new HandlerError(`Handler not found: ${verb.handler}`)
+      }
+
+      const ctx: HandlerContext = {
+        actor: req.actor,
+        context: req.context,
+        adapters: config.adapters || {},
+        logger: {
+          info: (msg, meta) => console.log(`[INFO] ${msg}`, meta),
+          error: (msg, meta) => console.error(`[ERROR] ${msg}`, meta)
+        },
+        emitEvent
+      }
+
+      const result = await handler(ctx, req.args)
+
+      // Stage 5: Validate output
+      validateOutput(verb.outputSchema, result)
+
+      // Stage 6: Create receipt
+      const receipt = createReceipt(req, 'ok', startTime)
+      await config.onReceipt?.(receipt)
+
+      // Stage 7: Return response
+      return {
+        ok: true,
+        result,
+        receipt,
+        events
+      }
+
+    } catch (error) {
+      emitEvent({
+        type: 'handler.error',
+        data: { error: error instanceof Error ? error.message : 'Unknown error' }
+      })
+
+      const receipt = createReceipt(req, 'error', startTime)
+      await config.onReceipt?.(receipt)
+
+      return {
+        ok: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+        receipt,
+        events
+      }
+    }
+  }
+
+  function emitEvent(event: Omit<Event, 'timestamp' | 'executionId'>) {
+    const fullEvent: Event = {
+      ...event,
+      timestamp: new Date().toISOString(),
+      executionId
+    }
+    events.push(fullEvent)
+    config.onEvent?.(fullEvent)
+  }
+
+  function createReceipt(
+    req: ExecuteRequest,
+    status: 'ok' | 'denied' | 'error',
+    startTime: number
+  ): Receipt {
+    return {
+      executionId,
+      verbId: req.verbId,
+      verbVersion: getVerbById(req.verbId, verbs)?.version || '0.0.0',
+      timestamp: new Date().toISOString(),
+      actorId: req.actor.id,
+      tenantId: req.context.tenantId,
+      status,
+      durationMs: Date.now() - startTime
+    }
+  }
+
+  function introspect(): VerbDefinition[] {
+    return verbs.map(v => ({
+      id: v.id,
+      version: v.version,
+      summary: v.summary,
+      inputSchema: v.inputSchema,
+      outputSchema: v.outputSchema,
+      effects: v.effects,
+      visibility: v.visibility,
+      handler: v.handler
+    }))
+  }
+
+  return { execute, introspect }
+}

package/src/errors.ts

@@ -0,0 +1,31 @@
+export class VerbNotFoundError extends Error {
+  constructor(verbId: string) {
+    super(`Verb not found: ${verbId}`)
+    this.name = 'VerbNotFoundError'
+  }
+}
+
+export class ValidationError extends Error {
+  constructor(message: string, public errors: any[]) {
+    super(message)
+    this.name = 'ValidationError'
+  }
+}
+
+export class PolicyDeniedError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public upsell?: { suggestedPlanId: string; cta: string }
+  ) {
+    super(message)
+    this.name = 'PolicyDeniedError'
+  }
+}
+
+export class HandlerError extends Error {
+  constructor(message: string, public cause?: Error) {
+    super(message)
+    this.name = 'HandlerError'
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+// @openverb/runtime - Main entry point
+export { createRuntime } from './engine'
+export { loadVerbs, getVerbById } from './registry'
+export { validateInput, validateOutput } from './validator'
+export type {
+  Runtime,
+  ExecuteRequest,
+  ExecuteResponse,
+  VerbDefinition,
+  HandlerContext,
+  Handler,
+  Actor,
+  Context,
+  Receipt,
+  Event,
+  PolicyDecision
+} from './types'
+export { VerbNotFoundError, ValidationError, PolicyDeniedError, HandlerError } from './errors'

package/src/registry.ts

@@ -0,0 +1,34 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { VerbDefinition } from './types'
+
+let cachedVerbs: VerbDefinition[] | null = null
+
+export function loadVerbs(verbsDir: string = './openverb/verbs'): VerbDefinition[] {
+  if (cachedVerbs) return cachedVerbs
+
+  const resolvedDir = path.resolve(process.cwd(), verbsDir)
+  
+  if (!fs.existsSync(resolvedDir)) {
+    console.warn(`Verbs directory not found: ${resolvedDir}`)
+    return []
+  }
+
+  const files = fs.readdirSync(resolvedDir).filter(f => f.endsWith('.json'))
+  
+  cachedVerbs = files.map(file => {
+    const content = fs.readFileSync(path.join(resolvedDir, file), 'utf-8')
+    return JSON.parse(content) as VerbDefinition
+  })
+
+  return cachedVerbs
+}
+
+export function getVerbById(verbId: string, verbs?: VerbDefinition[]): VerbDefinition | null {
+  const registry = verbs || loadVerbs()
+  return registry.find(v => v.id === verbId) || null
+}
+
+export function clearCache() {
+  cachedVerbs = null
+}

package/src/types.ts

@@ -0,0 +1,128 @@
+import type { JSONSchemaType } from 'ajv'
+
+// Core types
+export type Actor = {
+  type: 'user' | 'service' | 'ai' | 'system'
+  id: string
+  roles?: string[]
+}
+
+export type Context = {
+  tenantId: string
+  planId: string
+  env: 'dev' | 'staging' | 'prod'
+  requestId: string
+}
+
+export type VerbDefinition = {
+  id: string
+  version: string
+  summary: string
+  description?: string
+  inputSchema: any  // JSON Schema
+  outputSchema: any // JSON Schema
+  effects: string[]
+  visibility: 'public' | 'internal' | 'admin'
+  handler: string
+  policy?: {
+    rolesAllowed?: string[]
+    plansAllowed?: string[]
+  }
+  billing?: {
+    meterKey?: string
+    defaultDelta?: number
+  }
+}
+
+export type PolicyDecision =
+  | {
+      decision: 'allow'
+      reasons: string[]
+      limits?: Record<string, any>
+      meter?: { key: string; delta: number }
+    }
+  | {
+      decision: 'deny'
+      reasons: string[]
+      code: string
+      message: string
+      upsell?: {
+        suggestedPlanId: string
+        cta: string
+      }
+    }
+
+export type Event = {
+  type: string
+  timestamp: string
+  executionId: string
+  data: Record<string, unknown>
+}
+
+export type Receipt = {
+  executionId: string
+  verbId: string
+  verbVersion: string
+  timestamp: string
+  actorId: string
+  tenantId: string
+  status: 'ok' | 'denied' | 'error'
+  durationMs: number
+}
+
+export type HandlerContext = {
+  actor: Actor
+  context: Context
+  adapters: Record<string, any>
+  logger: {
+    info: (message: string, meta?: any) => void
+    error: (message: string, meta?: any) => void
+  }
+  emitEvent: (event: Omit<Event, 'timestamp' | 'executionId'>) => void
+}
+
+export type Handler<TArgs = any, TResult = any> = (
+  ctx: HandlerContext,
+  args: TArgs
+) => Promise<TResult>
+
+export type ExecuteRequest = {
+  verbId: string
+  args: unknown
+  actor: Actor
+  context: Context
+}
+
+export type ExecuteResponse =
+  | {
+      ok: true
+      result: unknown
+      receipt: Receipt
+      events: Event[]
+      uiHints?: Array<{ type: string; level: string; message: string }>
+    }
+  | {
+      ok: false
+      denied: true
+      reason: { code: string; message: string }
+      upsell?: { suggestedPlanId: string; cta: string }
+      receipt: Receipt
+      events: Event[]
+    }
+  | {
+      ok: false
+      error: string
+      receipt: Receipt
+      events: Event[]
+    }
+
+export type PolicyEngine = (
+  verb: VerbDefinition,
+  actor: Actor,
+  context: Context
+) => Promise<PolicyDecision>
+
+export type Runtime = {
+  execute: (req: ExecuteRequest) => Promise<ExecuteResponse>
+  introspect: () => VerbDefinition[]
+}

package/src/validator.ts

@@ -0,0 +1,26 @@
+import Ajv from 'ajv'
+import { ValidationError } from './errors'
+
+const ajv = new Ajv({ allErrors: true })
+
+export function validateInput(schema: any, data: unknown): void {
+  const validate = ajv.compile(schema)
+  const valid = validate(data)
+  
+  if (!valid) {
+    throw new ValidationError(
+      'Input validation failed',
+      validate.errors || []
+    )
+  }
+}
+
+export function validateOutput(schema: any, data: unknown): void {
+  const validate = ajv.compile(schema)
+  const valid = validate(data)
+  
+  if (!valid) {
+    console.error('Output validation failed:', validate.errors)
+    // Don't throw - log warning instead
+  }
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020"],
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}