@avelonjs/conformance 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Yannelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# @avelonjs/conformance
+
+`@avelonjs/conformance` is the load-bearing test artifact for Avelon drivers. It ships one suite per frozen contract, written against the contract rather than any implementation, plus in-memory fakes that run those same suites. Reach for this package when you certify a driver: pass a `create` factory that returns a known-empty instance, and let the suite own the assertions. A passing driver means someone other than the driver author wrote the tests.
+
+## Installation
+
+```sh
+bun add -d @avelonjs/conformance
+```
+
+Suites import `bun:test` and live at `@avelonjs/conformance/suites`. Fakes stay on the package root so a Next or Node production graph can import `FakeMail` without loading the test runner. Point a driver package at `@avelonjs/core` for the contract and at this package for the suite.
+
+## Basic Usage
+
+Wire the shared database suite to an in-memory fake, then swap `create` for your driver when you certify it.
+
+```ts
+import { FakeDatabase } from '@avelonjs/conformance'
+import { databaseSuite } from '@avelonjs/conformance/suites'
+
+databaseSuite({
+  name: 'reference fake',
+  create: () => new FakeDatabase(),
+})
+```
+
+A live driver owns fixture reset and cleanup. The suite still assumes each `create()` returns a known-empty world.
+
+```ts
+import { databaseSuite } from '@avelonjs/conformance/suites'
+import { createPostgresDatabase } from '@avelonjs/postgres'
+
+databaseSuite({
+  name: 'live postgres',
+  create: async () => {
+    const driver = createPostgresDatabase()
+    await driver.resetFixtures()
+    return driver
+  },
+  cleanup: (driver) => driver.close(),
+})
+```
+
+## Shared Suites
+
+Every contract has one suite. You did not write it. That is the point. Call the matching function from a `bun test` file; the suite registers `describe` and `test` blocks itself.
+
+```ts
+import { FakeMail } from '@avelonjs/conformance'
+import { mailSuite } from '@avelonjs/conformance/suites'
+
+mailSuite({
+  name: 'reference fake',
+  create: () => new FakeMail('transactional', 'mailer@example.test'),
+})
+```
+
+A driver either passes a capability's tests or declares that capability `false`. Declaring `true` and failing, or declaring `false` while still implementing the method, is a suite failure.
+
+## Reference Fakes
+
+Each fake is an in-memory implementation of one contract. Fakes run the same suites as live drivers, so `new FakeMail()` cannot drift from the mail contract. Use them in application tests and in this package's own certification of the suites.
+
+Capability-narrowed variants exist where a boolean or spectrum can be off: `FakeFlagsWithoutTargeting`, `FakeNotificationsWithoutChannels`, `FakeQueueWithoutRetries`, `FakeRateLimitWithoutAlgorithms`, and `FakeSearchWithoutFacets`.
+
+```ts
+import { FakeFlags, FakeFlagsWithoutTargeting } from '@avelonjs/conformance'
+
+const withTargeting = new FakeFlags()
+const withoutTargeting = new FakeFlagsWithoutTargeting()
+
+const targeted = await withTargeting.evaluate('assay.targeted', false, { actorId: 'actor-enabled' })
+const globalOnly = await withoutTargeting.evaluate('assay.enabled', false)
+```
+
+## Capability Surfaces
+
+`assertCapabilitySurface` checks both lies: a declared capability whose method is missing, and an implemented method whose capability is `false`. Suites call it; you may also call it from a driver test when a surface is method-gated.
+
+```ts
+import { assertCapabilitySurface, captureFailure, FakeStorage } from '@avelonjs/conformance'
+
+const storage = new FakeStorage()
+assertCapabilitySurface(storage, 'signedUrls', storage.capabilities.signedUrls, ['signedUrl'])
+
+const error = await captureFailure(() => storage.get('missing/avatar.png'))
+```
+
+`captureFailure` returns the thrown value so suites can assert the framework error taxonomy instead of a vendor code.
+
+## Method Reference
+
+| Method / export | Signature | Description |
+|---|---|---|
+| `assertCapabilitySurface` | `(driver: object, capability: string, declared: boolean, methods: readonly string[]) => void` | Fails when a declared method is missing or an undeclared method is present. |
+| `captureFailure` | `(operation: () => Promise<unknown>) => Promise<unknown>` | Runs an operation expected to throw and returns the thrown value. |
+| `SuiteContext` | `interface SuiteContext<TDriver>` | `name`, `create`, optional `cleanup`, and live-service helpers for one suite. |
+| `FakeAI` | `class FakeAI` | In-memory AI driver used as the AI contract reference. |
+| `FakeCache` | `class FakeCache` | In-memory cache driver used as the cache contract reference. |
+| `FakeDatabase` | `class FakeDatabase` | In-memory database driver used as the database contract reference. |
+| `FakeFlags` | `class FakeFlags` | In-memory flags driver with targeting enabled. |
+| `FakeFlagsWithoutTargeting` | `class FakeFlagsWithoutTargeting` | Flags fake with targeting declared unavailable. |
+| `FakeIdentity` | `class FakeIdentity` | In-memory identity driver used as the identity contract reference. |
+| `FakeLogs` | `class FakeLogs` | In-memory log driver with traces enabled. |
+| `FakeTraceRecord` | `interface` | Observable span state retained by `FakeLogs`. |
+| `FakeMail` | `class FakeMail` | In-memory mail driver with hosted templates enabled. |
+| `FakeNotifications` | `class FakeNotifications` | In-memory notifications driver with every channel declared. |
+| `FakeNotificationsWithoutChannels` | `class FakeNotificationsWithoutChannels` | Notifications fake with an empty channel list. |
+| `FakeSentNotification` | `interface` | One notification accepted by a notifications fake. |
+| `FakePayments` | `class FakePayments` | In-memory payments driver used as the payments contract reference. |
+| `FakeQueue` | `class FakeQueue` | In-memory queue driver with retries enabled. |
+| `FakeQueueWithoutRetries` | `class FakeQueueWithoutRetries` | Queue fake with retries declared unavailable. |
+| `FakeRateLimit` | `class FakeRateLimit` | In-memory rate-limit driver with every algorithm declared. |
+| `FakeRateLimitWithoutAlgorithms` | `class FakeRateLimitWithoutAlgorithms` | Rate-limit fake with an empty algorithm list. |
+| `FakeRealtime` | `class FakeRealtime` | In-memory realtime driver used as the realtime contract reference. |
+| `FakeSearch` | `class FakeSearch` | In-memory search driver with facets enabled. |
+| `FakeSearchWithoutFacets` | `class FakeSearchWithoutFacets` | Search fake with facets declared unavailable. |
+| `FakeSocial` | `class FakeSocial` | In-memory social identity driver used as the social contract reference. |
+| `FakeStorage` | `class FakeStorage` | In-memory storage driver used as the storage contract reference. |
+| `FakeTokens` | `class FakeTokens` | In-memory API-token driver used as the tokens contract reference. |
+| `aiSuite` | `(context: SuiteContext<TDriver>) => void` | Shared AI contract suite from `@avelonjs/conformance/suites`. |
+| `cacheSuite` | `(context: SuiteContext<TDriver>) => void` | Shared cache contract suite. |
+| `databaseSuite` | `(context: SuiteContext<TDriver>) => void` | Shared database contract suite. |
+| `flagsSuite` | `(context: SuiteContext<TDriver>) => void` | Shared flags contract suite. |
+| `identitySuite` | `(context: SuiteContext<IdentityFactory<TDriver>>) => void` | Shared identity contract suite. |
+| `logsSuite` | `(context: SuiteContext<TDriver>) => void` | Shared logs contract suite. |
+| `mailSuite` | `(context: SuiteContext<TDriver>) => void` | Shared mail contract suite. |
+| `notificationsSuite` | `(context: SuiteContext<TDriver>) => void` | Shared notifications contract suite. |
+| `paymentsSuite` | `(context: SuiteContext<TDriver>) => void` | Shared payments contract suite. |
+| `queueSuite` | `(context: SuiteContext<TDriver>) => void` | Shared queue contract suite. |
+| `ratelimitSuite` | `(context: SuiteContext<TDriver>) => void` | Shared rate-limit contract suite. |
+| `realtimeSuite` | `(context: SuiteContext<TDriver>) => void` | Shared realtime contract suite. |
+| `searchSuite` | `(context: SuiteContext<TDriver>) => void` | Shared search contract suite. |
+| `socialSuite` | `(context: SuiteContext<TDriver>) => void` | Shared social contract suite. |
+| `storageSuite` | `(context: SuiteContext<TDriver>) => void` | Shared storage contract suite. |
+| `tokensSuite` | `(context: SuiteContext<TDriver>) => void` | Shared tokens contract suite. |
+
+## Testing
+
+This package is the suite. Run it against the shipped fakes here, and again against a real driver in that driver's package. A deliberately broken stub in `tests/` proves the suite rejects compiler defects rather than echoing the fake back to itself.
+
+```ts
+import { FakeStorage } from '@avelonjs/conformance'
+import { storageSuite } from '@avelonjs/conformance/suites'
+
+storageSuite({
+  name: 'reference fake',
+  create: () => new FakeStorage(),
+})
+```
+
+```sh
+bun test
+bun run typecheck
+```

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@avelonjs/conformance",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Contract test suites and in-memory fakes for Avelon drivers.",
+  "license": "MIT",
+  "author": "Ryan Yannelli <ryanyannelli@gmail.com>",
+  "homepage": "https://github.com/yannelli/avelon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yannelli/avelon.git",
+    "directory": "packages/conformance"
+  },
+  "bugs": {
+    "url": "https://github.com/yannelli/avelon/issues"
+  },
+  "keywords": [
+    "avelon",
+    "typescript",
+    "testing",
+    "conformance"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./suites": "./src/suites/index.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@avelonjs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/fakes/ai.ts

@@ -0,0 +1,113 @@
+import {
+  Invalid,
+  type AiDriver,
+  type CompletionAiSurface,
+  type CompletionChunk,
+  type CompletionRequest,
+  type CompletionResult,
+  type EmbeddingAiSurface,
+  type EmbeddingResult,
+  type StreamingAiSurface,
+} from '@avelonjs/core'
+
+const capabilities = {
+  modes: ['completion', 'embedding'],
+  streaming: true,
+} as const
+
+interface FakeAiRaw {
+  readonly completions: number
+  readonly embeddings: number
+}
+
+function completionText(request: CompletionRequest): string {
+  return request.messages.map((message) => message.content).join(' ')
+}
+
+function vector(input: string): readonly number[] {
+  let sum = 0
+  let weighted = 0
+  for (const [index, character] of [...input].entries()) {
+    const code = character.codePointAt(0) ?? 0
+    sum += code
+    weighted += code * (index + 1)
+  }
+  return [input.length, sum % 997, weighted % 991, (sum + weighted) % 983]
+}
+
+/** Deterministic in-memory AI reference implementation used by conformance and application tests. */
+export class FakeAI
+  implements
+    AiDriver<typeof capabilities, FakeAiRaw>,
+    CompletionAiSurface,
+    EmbeddingAiSurface,
+    StreamingAiSurface
+{
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured AI connection name. */
+  readonly instance: string
+
+  /** Exact mode and streaming declaration. */
+  readonly capabilities = capabilities
+
+  #completions = 0
+  #embeddings = 0
+
+  /** Creates an isolated AI connection. */
+  constructor(instance = 'default') {
+    this.instance = instance
+  }
+
+  /** Returns operation counts for the in-memory implementation. */
+  raw(): FakeAiRaw {
+    return { completions: this.#completions, embeddings: this.#embeddings }
+  }
+
+  /** Produces deterministic text from the ordered request messages. */
+  async complete(request: CompletionRequest): Promise<CompletionResult> {
+    this.validateModel(request.model)
+    this.#completions += 1
+    const text = completionText(request)
+    return {
+      text,
+      inputTokens: request.messages.reduce((total, message) => total + message.content.length, 0),
+      outputTokens: text.length,
+    }
+  }
+
+  /** Embeds every input into a deterministic four-dimensional vector. */
+  async embed(model: string, input: string | readonly string[]): Promise<EmbeddingResult> {
+    this.validateModel(model)
+    const inputs = typeof input === 'string' ? [input] : input
+    if (inputs.length === 0) {
+      throw new Invalid('At least one embedding input is required.', {
+        metadata: { fields: { input: ['Provide one or more strings to embed.'] } },
+      })
+    }
+    this.#embeddings += 1
+    return {
+      embeddings: inputs.map(vector),
+      inputTokens: inputs.reduce((total, value) => total + value.length, 0),
+    }
+  }
+
+  /** Streams deterministic completion text in ordered increments followed by one terminal chunk. */
+  async *stream(request: CompletionRequest): AsyncIterable<CompletionChunk> {
+    this.validateModel(request.model)
+    const text = completionText(request)
+    const split = Math.max(1, Math.ceil(text.length / 2))
+    yield { text: text.slice(0, split), done: false }
+    if (split < text.length) yield { text: text.slice(split), done: false }
+    yield { text: '', done: true }
+  }
+
+  private validateModel(model: string): void {
+    if (model.length === 0) {
+      throw new Invalid('An AI model identifier is required.', {
+        metadata: { fields: { model: ['A model identifier is required.'] } },
+      })
+    }
+  }
+}

package/src/fakes/cache.ts

@@ -0,0 +1,153 @@
+import {
+  Conflict,
+  type CacheDriver,
+  type CacheStore,
+  type LockCacheSurface,
+  type TaggedCacheSurface,
+} from '@avelonjs/core'
+
+const capabilities = {
+  tags: true,
+  locks: true,
+} as const
+
+interface CacheEntry {
+  value: unknown
+  expiresAt: number | null
+  tags: ReadonlySet<string>
+}
+
+interface HeldLock {
+  token: symbol
+  expiresAt: number
+}
+
+interface FakeCacheRaw {
+  entries: number
+  locks: number
+}
+
+/** In-memory cache reference implementation used by conformance and application tests. */
+export class FakeCache
+  implements CacheDriver<typeof capabilities, FakeCacheRaw>, TaggedCacheSurface, LockCacheSurface
+{
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured cache store name. */
+  readonly instance: string
+
+  /** Exact optional-feature declaration. */
+  readonly capabilities = capabilities
+
+  readonly #entries = new Map<string, CacheEntry>()
+  readonly #locks = new Map<string, HeldLock>()
+
+  /** Creates an isolated cache store. */
+  constructor(instance = 'default') {
+    this.instance = instance
+  }
+
+  /** Returns observable entry and active-lock counts. */
+  raw(): FakeCacheRaw {
+    return { entries: this.#entries.size, locks: this.#locks.size }
+  }
+
+  /** Reads a value or returns null when absent or expired. */
+  async get<TValue>(key: string): Promise<TValue | null> {
+    return this.getTagged<TValue>(key, [])
+  }
+
+  /** Stores a value with an optional lifetime in seconds. */
+  async put<TValue>(key: string, value: TValue, ttlSeconds?: number): Promise<void> {
+    this.putTagged(key, value, ttlSeconds, [])
+  }
+
+  /** Removes a key when present. */
+  async forget(key: string): Promise<void> {
+    this.forgetTagged(key, [])
+  }
+
+  /** Removes every cache entry. */
+  async flush(): Promise<void> {
+    this.#entries.clear()
+  }
+
+  /** Returns a namespace whose writes carry every supplied tag. */
+  tags(names: readonly string[]): CacheStore {
+    const required = [...new Set(names)]
+    return {
+      get: <TValue>(key: string) => this.getTagged<TValue>(key, required),
+      put: <TValue>(key: string, value: TValue, ttlSeconds?: number) => {
+        this.putTagged(key, value, ttlSeconds, required)
+        return Promise.resolve()
+      },
+      forget: (key: string) => {
+        this.forgetTagged(key, required)
+        return Promise.resolve()
+      },
+      flush: () => {
+        this.flushTagged(required)
+        return Promise.resolve()
+      },
+    }
+  }
+
+  /** Runs a callback with exclusive ownership of a named expiring lock. */
+  async lock<TResult>(
+    key: string,
+    ttlSeconds: number,
+    callback: () => Promise<TResult>,
+  ): Promise<TResult> {
+    const now = Date.now()
+    const held = this.#locks.get(key)
+    if (held && held.expiresAt > now) {
+      throw new Conflict(`Cache lock ${key} is already held.`, {
+        metadata: { resource: 'cache-lock', key },
+      })
+    }
+
+    const token = Symbol(key)
+    this.#locks.set(key, { token, expiresAt: now + ttlSeconds * 1000 })
+    try {
+      return await callback()
+    } finally {
+      if (this.#locks.get(key)?.token === token) this.#locks.delete(key)
+    }
+  }
+
+  private async getTagged<TValue>(key: string, tags: readonly string[]): Promise<TValue | null> {
+    const entry = this.#entries.get(key)
+    if (!entry) return null
+    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+      this.#entries.delete(key)
+      return null
+    }
+    if (!tags.every((tag) => entry.tags.has(tag))) return null
+    return entry.value as TValue
+  }
+
+  private putTagged<TValue>(
+    key: string,
+    value: TValue,
+    ttlSeconds: number | undefined,
+    tags: readonly string[],
+  ): void {
+    this.#entries.set(key, {
+      value,
+      expiresAt: ttlSeconds === undefined ? null : Date.now() + ttlSeconds * 1000,
+      tags: new Set(tags),
+    })
+  }
+
+  private forgetTagged(key: string, tags: readonly string[]): void {
+    const entry = this.#entries.get(key)
+    if (entry && tags.every((tag) => entry.tags.has(tag))) this.#entries.delete(key)
+  }
+
+  private flushTagged(tags: readonly string[]): void {
+    for (const [key, entry] of this.#entries) {
+      if (tags.every((tag) => entry.tags.has(tag))) this.#entries.delete(key)
+    }
+  }
+}