@avelonjs/conformance 0.1.0

package/src/suites/ai.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  Invalid,
+  type AiCapabilities,
+  type AiDriver,
+  type CompletionAiSurface,
+  type CompletionChunk,
+  type CompletionRequest,
+  type EmbeddingAiSurface,
+  type StreamingAiSurface,
+} from '@avelonjs/core'
+import { assertCapabilitySurface, captureFailure, type SuiteContext } from '../harness'
+
+type AssayDriver = AiDriver<AiCapabilities> &
+  Partial<CompletionAiSurface & EmbeddingAiSurface & StreamingAiSurface>
+
+function assay<TDriver extends AssayDriver>(
+  context: SuiteContext<TDriver>,
+  name: string,
+  assertion: (driver: TDriver) => Promise<void> | void,
+): void {
+  test(name, async () => {
+    const driver = await context.create()
+    try {
+      await assertion(driver)
+    } finally {
+      await context.cleanup?.(driver)
+    }
+  })
+}
+
+function hasCompletion(driver: AssayDriver): driver is AssayDriver & CompletionAiSurface {
+  return driver.capabilities.modes.includes('completion') && typeof driver.complete === 'function'
+}
+
+function hasEmbedding(driver: AssayDriver): driver is AssayDriver & EmbeddingAiSurface {
+  return driver.capabilities.modes.includes('embedding') && typeof driver.embed === 'function'
+}
+
+function hasStreaming(driver: AssayDriver): driver is AssayDriver & StreamingAiSurface {
+  return (
+    driver.capabilities.modes.includes('completion') &&
+    driver.capabilities.streaming &&
+    typeof driver.stream === 'function'
+  )
+}
+
+async function expectInvalid(operation: () => Promise<unknown>): Promise<Invalid> {
+  const error = await captureFailure(operation)
+  expect(error).toBeInstanceOf(Invalid)
+  if (!(error instanceof Invalid)) throw new Error('Expected Invalid after taxonomy assertion.')
+  expect(error.code).toBe('INVALID')
+  return error
+}
+
+function request(): CompletionRequest {
+  return {
+    model: 'assay-model',
+    temperature: 0,
+    messages: [
+      { role: 'system', content: 'Answer directly.' },
+      { role: 'user', content: 'Explain ordered streaming.' },
+    ],
+  }
+}
+
+/**
+ * Registers the portable AI contract conformance suite.
+ *
+ * The assay model is deterministic at temperature zero, allowing streamed increments to be joined
+ * and compared with the complete result. An embedding batch is "one or more" inputs in the frozen
+ * contract, so an empty batch is pinned to `Invalid`.
+ *
+ * @param context Fresh isolated AI drivers configured with the deterministic assay model.
+ */
+export function aiSuite<TDriver extends AssayDriver>(context: SuiteContext<TDriver>): void {
+  describe(`ai conformance: ${context.name}`, () => {
+    assay(context, 'reports a present and stable resolved ai instance', (driver) => {
+      const instance = driver.instance
+      expect(instance.length).toBeGreaterThan(0)
+      expect(driver.instance).toBe(instance)
+    })
+
+    assay(context, 'enforces every ai capability surface in both directions', (driver) => {
+      const hasCompletionMode = driver.capabilities.modes.includes('completion')
+      const hasEmbeddingMode = driver.capabilities.modes.includes('embedding')
+      const surfaces: readonly [string, boolean, readonly string[]][] = [
+        ['completion', hasCompletionMode, ['complete']],
+        ['embedding', hasEmbeddingMode, ['embed']],
+        ['streaming', hasCompletionMode && driver.capabilities.streaming, ['stream']],
+      ]
+      for (const [capability, declared, methods] of surfaces) {
+        assertCapabilitySurface(driver, capability, declared, methods)
+        assertCapabilitySurface(
+          { capabilities: { [capability]: false } },
+          capability,
+          false,
+          methods,
+        )
+        expect(() =>
+          assertCapabilitySurface(
+            { capabilities: { [capability]: false }, [methods[0] ?? 'missing']: () => undefined },
+            capability,
+            false,
+            methods,
+          ),
+        ).toThrow()
+        expect(() =>
+          assertCapabilitySurface(
+            { capabilities: { [capability]: true } },
+            capability,
+            true,
+            methods,
+          ),
+        ).toThrow()
+      }
+    })
+
+    assay(context, 'returns a complete response when completion is declared', async (driver) => {
+      if (!hasCompletion(driver)) return
+      const result = await driver.complete(request())
+      expect(result.text.length).toBeGreaterThan(0)
+      expect(result.inputTokens).toBeGreaterThan(0)
+      expect(result.outputTokens).toBeGreaterThan(0)
+    })
+
+    assay(context, 'streams chunks in order and terminates exactly once', async (driver) => {
+      if (!hasCompletion(driver) || !hasStreaming(driver)) return
+      const expected = await driver.complete(request())
+      const chunks: CompletionChunk[] = []
+      for await (const chunk of driver.stream(request())) chunks.push(chunk)
+      const terminals = chunks.filter((chunk) => chunk.done)
+      const terminalIndex = chunks.findIndex((chunk) => chunk.done)
+      expect(chunks.length).toBeGreaterThan(1)
+      expect(terminals).toEqual([{ text: '', done: true }])
+      expect(terminalIndex).toBe(chunks.length - 1)
+      expect(
+        chunks
+          .filter((chunk) => !chunk.done)
+          .map((chunk) => chunk.text)
+          .join(''),
+      ).toBe(expected.text)
+    })
+
+    assay(
+      context,
+      'returns stable embedding dimensions while preserving input order',
+      async (driver) => {
+        if (!hasEmbedding(driver)) return
+        const first = await driver.embed('assay-embedding-model', ['alpha', 'beta', 'gamma'])
+        const second = await driver.embed('assay-embedding-model', 'alpha')
+        expect(first.embeddings).toHaveLength(3)
+        const dimensions = first.embeddings.map((embedding) => embedding.length)
+        expect(new Set(dimensions).size).toBe(1)
+        expect(dimensions[0]).toBeGreaterThan(0)
+        expect(second.embeddings[0]?.length).toBe(dimensions[0])
+        expect(first.embeddings[0]).toEqual(second.embeddings[0])
+      },
+    )
+
+    assay(context, 'normalizes an empty embedding batch to Invalid', async (driver) => {
+      if (!hasEmbedding(driver)) return
+      const error = await expectInvalid(() => driver.embed('assay-embedding-model', []))
+      expect(error.metadata.fields?.input).toBeDefined()
+    })
+  })
+}

package/src/suites/cache.ts

@@ -0,0 +1,174 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  type CacheCapabilities,
+  type CacheDriver,
+  type LockCacheSurface,
+  type TaggedCacheSurface,
+} from '@avelonjs/core'
+import { assertCapabilitySurface, captureFailure, type SuiteContext } from '../harness'
+
+type AssayDriver = CacheDriver<CacheCapabilities> & Partial<TaggedCacheSurface & LockCacheSurface>
+
+function assay<TDriver extends AssayDriver>(
+  context: SuiteContext<TDriver>,
+  name: string,
+  assertion: (driver: TDriver) => Promise<void> | void,
+): void {
+  test(name, async () => {
+    const driver = await context.create()
+    try {
+      await assertion(driver)
+    } finally {
+      await context.cleanup?.(driver)
+    }
+  })
+}
+
+function hasTags(driver: AssayDriver): driver is AssayDriver & TaggedCacheSurface {
+  return driver.capabilities.tags && typeof driver.tags === 'function'
+}
+
+function hasLocks(driver: AssayDriver): driver is AssayDriver & LockCacheSurface {
+  return driver.capabilities.locks && typeof driver.lock === 'function'
+}
+
+/**
+ * Registers the portable cache contract conformance suite.
+ *
+ * A tagged namespace matches entries carrying every requested tag. Lock contention may reject the
+ * second acquirer immediately or block it until release, but may never run both callbacks together.
+ *
+ * @param context Fresh isolated cache drivers and optional cleanup.
+ */
+export function cacheSuite<TDriver extends AssayDriver>(context: SuiteContext<TDriver>): void {
+  describe(`cache conformance: ${context.name}`, () => {
+    assay(context, 'reports a present and stable resolved cache instance', (driver) => {
+      const instance = driver.instance
+      expect(instance.length).toBeGreaterThan(0)
+      expect(driver.instance).toBe(instance)
+    })
+
+    assay(context, 'enforces every cache capability surface in both directions', (driver) => {
+      const surfaces: readonly [string, boolean, readonly string[]][] = [
+        ['tags', driver.capabilities.tags, ['tags']],
+        ['locks', driver.capabilities.locks, ['lock']],
+      ]
+      for (const [capability, declared, methods] of surfaces) {
+        assertCapabilitySurface(driver, capability, declared, methods)
+        const unavailable = { capabilities: { [capability]: false } }
+        assertCapabilitySurface(unavailable, capability, false, methods)
+        expect(() =>
+          assertCapabilitySurface(
+            { ...unavailable, [methods[0] ?? 'missing']: () => undefined },
+            capability,
+            false,
+            methods,
+          ),
+        ).toThrow()
+        expect(() =>
+          assertCapabilitySurface(
+            { capabilities: { [capability]: true } },
+            capability,
+            true,
+            methods,
+          ),
+        ).toThrow()
+      }
+    })
+
+    assay(context, 'returns null on a cache miss without throwing', async (driver) => {
+      await expect(driver.get('missing-key')).resolves.toBeNull()
+    })
+
+    assay(context, 'puts, gets, forgets, and flushes values', async (driver) => {
+      await driver.put('actor', { id: 'actor-1', roles: ['admin'] })
+      expect(await driver.get<{ id: string; roles: string[] }>('actor')).toEqual({
+        id: 'actor-1',
+        roles: ['admin'],
+      })
+      await driver.forget('actor')
+      expect(await driver.get('actor')).toBeNull()
+
+      await driver.put('first', 1)
+      await driver.put('second', 2)
+      await driver.flush()
+      expect(await driver.get('first')).toBeNull()
+      expect(await driver.get('second')).toBeNull()
+    })
+
+    assay(context, 'expires values after their TTL elapses', async (driver) => {
+      await driver.put('short-lived', 'value', 1)
+      expect(await driver.get<string>('short-lived')).toBe('value')
+      await new Promise((resolve) => setTimeout(resolve, 1_200))
+      expect(await driver.get('short-lived')).toBeNull()
+    })
+
+    assay(context, 'invalidates exactly the entries carrying a requested tag', async (driver) => {
+      if (!hasTags(driver)) return
+      await driver.put('untagged', 'keep')
+      await driver.tags(['accounts']).put('account', 'remove')
+      await driver.tags(['reports']).put('report', 'keep')
+      await driver.tags(['accounts', 'shared']).put('shared-account', 'remove')
+
+      await driver.tags(['accounts']).flush()
+      expect(await driver.get('account')).toBeNull()
+      expect(await driver.get('shared-account')).toBeNull()
+      expect(await driver.get<string>('untagged')).toBe('keep')
+      expect(await driver.get<string>('report')).toBe('keep')
+    })
+
+    assay(context, 'keeps lock callbacks exclusive and releases after success', async (driver) => {
+      if (!hasLocks(driver)) return
+      let signalStarted: (() => void) | undefined
+      let releaseFirst: (() => void) | undefined
+      const started = new Promise<void>((resolve) => {
+        signalStarted = resolve
+      })
+      const hold = new Promise<void>((resolve) => {
+        releaseFirst = resolve
+      })
+
+      const first = driver.lock('report-generation', 2, async () => {
+        signalStarted?.()
+        await hold
+        return 'first'
+      })
+      await started
+
+      let secondEntered = false
+      const second = driver
+        .lock('report-generation', 2, async () => {
+          secondEntered = true
+          return 'second'
+        })
+        .then(
+          (value) => ({ status: 'acquired' as const, value }),
+          () => ({ status: 'rejected' as const }),
+        )
+
+      await new Promise((resolve) => setTimeout(resolve, 30))
+      expect(secondEntered).toBe(false)
+      releaseFirst?.()
+      expect(await first).toBe('first')
+      const outcome = await second
+      expect(['acquired', 'rejected']).toContain(outcome.status)
+
+      expect(await driver.lock('report-generation', 2, async () => 'after-release')).toBe(
+        'after-release',
+      )
+    })
+
+    assay(context, 'releases a lock when its callback throws', async (driver) => {
+      if (!hasLocks(driver)) return
+      const failure = new Error('callback failed')
+      expect(
+        await captureFailure(() =>
+          driver.lock('failing-lock', 2, async () => {
+            throw failure
+          }),
+        ),
+      ).toBe(failure)
+      expect(await driver.lock('failing-lock', 2, async () => 'recovered')).toBe('recovered')
+    })
+  })
+}