> ## Documentation Index > Fetch the complete documentation index at: https://praison.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Adapter Conformance > The runnable contract that pins every adapter, and the fixture that pins the contract. A conformance contract asserts an adapter behaves; a fixture asserts the contract still contains those assertions. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph LR Adapter[๐Ÿ”Œ adapter] --> Contract[๐Ÿ“œ conformance contract] Contract --> Fixture[๐Ÿงช broken fixture] Fixture --> Named{โ“ goes red BY NAME?} classDef adapter fill:#6366F1,stroke:#7C90A0,color:#fff classDef contract fill:#F59E0B,stroke:#7C90A0,color:#fff classDef pass fill:#10B981,stroke:#7C90A0,color:#fff classDef defect fill:#8B0000,stroke:#7C90A0,color:#fff class Adapter adapter class Contract contract class Named pass class Fixture defect ``` ## Quick Start Each port ships a runnable contract. Register your adapter and both the fake and the shipping adapter are held to the same cases. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { describeSecretsContract } from "praisonai-mobile/adapters/conformance/secrets-contract"; describeSecretsContract("my adapter", () => createMyAdapter()); ``` The fixture spawns the real contract against a deliberately broken adapter, one break at a time. It takes a single mode string. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} node adapters/src/conformance/contract-fixture.ts ``` The six break modes plus the `none` control: ``` secrets_slot_only secrets_empty_is_absent storage_missing_is_undefined storage_namespaces_collide time_every_fires_once time_clear_does_nothing none ``` `contracts.test.ts` counts passing cases from a real `none` run and asserts a floor per contract: secrets โ‰ฅ 9, storage โ‰ฅ 11, time โ‰ฅ 8, shell โ‰ฅ 35. The `none` control must pass green, so a fixture that failed for an unrelated reason cannot masquerade as proof. This runs automatically inside `contracts.test.ts` under `npm test`. There is no flag to enable and no opt-in. *** ## Why Two Layers The contracts assert on adapter behaviour; the fixture asserts the contracts still contain those assertions. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph TB subgraph "Layer 1 โ€” behaviour" C[๐Ÿ“œ contract] --> A[๐Ÿ”Œ does the adapter behave?] end subgraph "Layer 2 โ€” self-defence" F[๐Ÿงช fixture] --> B[๐Ÿ“œ does the contract still catch a break?] end classDef contract fill:#F59E0B,stroke:#7C90A0,color:#fff classDef adapter fill:#6366F1,stroke:#7C90A0,color:#fff classDef fixture fill:#8B0000,stroke:#7C90A0,color:#fff class C,B contract class A adapter class F fixture ``` A contract with no broken-implementation test is documentation with a `test()` around it. Deleting `assert.ok(fired >= 2)` from the time contract โ€” the one assertion that catches `setInterval` becoming `setTimeout`, which stops every polling loop in the app after a single tick โ€” left the suite at **1035 pass, 0 fail**. Fourteen assertions across all four contracts could be deleted for free. *** ## The Shell Reads What It Forwarded The shell contract now asserts on the value the adapter handed the OS, not just whether the promise settled. `ShellHarness` carries `forwarded(): readonly string[]` โ€” the URLs `openExternal` actually handed the OS, in order. A shell can validate one string and forward another, and `doesNotReject` cannot see the difference, so the harness surfaces the forwarded value and the contract reads it. `forwarded()` is **required, not optional**, so a shell cannot opt out of being checked. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} export interface ShellHarness { readonly shell: ShellPort; // ... forwarded(): readonly string[]; // required โ€” every real shell supplies it } ``` A padded-URL case then reads it directly: a URL that passes the allowlist must reach the OS trimmed (`"https://ok.example"`, never the padded input), and a padded `javascript:` must still be refused before anything is forwarded. *** ## The Six Break Modes Each mode breaks a non-shell adapter in one named way, and the matching contract case must go red by name โ€” the shell contract is guarded by its own case-count floor instead. | break mode | must redden the case named | | ------------------------------ | ---------------------------------------------------- | | `secrets_slot_only` | `two ACCOUNTS in one slot are two different secrets` | | `secrets_empty_is_absent` | `an empty string is a stored value, not an absence` | | `storage_missing_is_undefined` | `a missing key reads as null, never undefined` | | `storage_namespaces_collide` | `namespaces are isolated` | | `time_every_fires_once` | `every() repeats, rather than firing once` | | `time_clear_does_nothing` | `a cleared timer does not fire` | A `none` control runs unbroken, so a fixture that failed for an unrelated reason โ€” a syntax error, a missing import โ€” cannot masquerade as proof. *** ## The Shrink Floor A case with no break mode could still be deleted, so `contracts.test.ts` counts passing cases from a **real** run of the fixture โ€” not a regex over source text โ€” and asserts a floor. | contract | floor | | -------- | ---------- | | secrets | โ‰ฅ 9 cases | | storage | โ‰ฅ 11 cases | | time | โ‰ฅ 8 cases | | shell | โ‰ฅ 35 cases | Raise these numbers when you add cases. A drop means a contract lost coverage, and that is exactly the event worth a red build. The shell contract is protected by this case-count floor rather than by a spawned broken-adapter mode, so the [Six Break Modes](#the-six-break-modes) table below enumerates only the non-shell contracts. Node 22 emits TAP when stdout is a pipe; Node 24 emits the spec reporter. The fixture is spawned with `--test-reporter=tap` so a test grepping for `not ok` behaves the same on both. *** ## Why The Fixture Builds Broken Adapters Inline `adapters` may not import `testing` โ€” enforced by `tools/depgraph.mjs` โ€” so the fixture builds its broken adapters inline, the same way `engines/src/contract-fixture.ts` does. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} function secrets(): SecretsPort { const store = new Map(); // The defect: keying by slot alone, so two accounts share one credential. const key = (ref: { slot: string; account: string }): string => mode === "secrets_slot_only" ? ref.slot : `${ref.slot}:${ref.account}`; // ... } ``` *** ## Adding A New Case Or Break Mode The name is matched by regex, so keep it stable once other code depends on it. Guard the defect behind a `mode === "..."` branch. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} const key = (ref: { namespace: string; id: string }): string => mode === "storage_namespaces_collide" ? ref.id : `${ref.namespace}/${ref.id}`; ``` `contracts.test.ts` maps each mode to the case name it must redden. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { mode: "storage_namespaces_collide", expects: /namespaces are isolated/ }, ``` A new case raises the floor by one, so a later deletion is caught. *** ## Best Practices An inline broken adapter that re-implements the assertion proves an assertion of that shape would catch the defect โ€” not that the contract still contains it. Spawn the real contract instead. Without the unbroken control, a fixture that failed everything โ€” a syntax error, a runner that cannot start โ€” would satisfy every break mode while proving nothing. A regex over `test(` is satisfied by a case that asserts nothing. Counting passing cases from a real `none` run pins behaviour, not shape. Spawn the fixture with `--test-reporter=tap` so a test grepping for `not ok` behaves identically on Node 22 and Node 24. *** ## Related The two ports the secrets and storage break modes pin. The port the two time break modes pin. The shell contract that sits in the same file. The parallel fixture pattern one directory over.