# @suaveplan/api-tenant-provider-memory - In-memory reference implementation of @suaveplan/api-tenant-provider TenantProvider. Backed by an insertion-ordered Map<TenantId, TenantRecord>, ships stable base64url-JSON cursor pagination, active/suspended/archived filtering matching the abstract contract, out-of-band add/remove/clear admin helpers, idempotent dispose, Zod-validated TenantRecord seeds, and the TENANT_PROVIDER_MEMORY.* error registry (DUPLICATE_TENANT, TENANT_NOT_FOUND, INVALID_RECORD). Passes runTenantProviderConformance verbatim. Used by @suaveplan/api test hosts and small static-tenant deployments.

In-memory reference implementation of the
`@suaveplan/api-tenant-provider` `TenantProvider` contract. Backed by
an insertion-ordered `Map<TenantId, TenantRecord>`. Production-grade
for small static-tenant deployments AND reference-grade for the
downstream DB-backed adapters (Stage 8) that ship the same contract.

The API testing kit (`createTestHost`) uses this provider by
default so unit tests never need a database.

<!-- begin:auto-docs -->
## Documentation tree

- [error-codes](./src/error-codes/error-codes.md) — The in-memory `TenantProvider` adapter has its own narrow error namespace, distinct from the abstract `TENANT_PROVIDER.…
  - [error-codes](./src/error-codes/error-codes.md) — The in-memory `TenantProvider` adapter has its own narrow error namespace, distinct from the abstract `TENANT_PROVIDER.…
- [provider](./src/provider/provider.md) — In-memory reference implementation of the `@suaveplan/api-tenant-provider` `TenantProvider` contract. It is both the de…
  - [provider](./src/provider/provider.md) — In-memory reference implementation of the `@suaveplan/api-tenant-provider` `TenantProvider` contract. It is both the de…
<!-- end:auto-docs -->

## What ships

| Subpath | Module | Doc |
|---|---|---|
| `./provider` | `createMemoryTenantProvider({ tenants? })` + admin helpers | [`src/provider/provider.md`](src/provider/provider.md) |
| `./error-codes` | `TENANT_PROVIDER_MEMORY_CODES` + `TenantProviderMemoryError` | [`src/error-codes/error-codes.md`](src/error-codes/error-codes.md) |

## Surface

- `createMemoryTenantProvider(options?)` — factory returning a
  `MemoryTenantProvider` (the abstract `TenantProvider` interface plus
  out-of-band `add`/`remove`/`clear` admin helpers).
- Active-only filtering by default; `list({ includeSuspended: true })`
  surfaces suspended tenants; `archived` is reachable only through
  `lookup`.
- Cursor pagination via the canonical
  `@suaveplan/api-tenant-provider/pagination` codec — cursors produced
  by this provider round-trip with the abstract decoder.

## Conformance

The package's own test file calls
`runTenantProviderConformance({ label: "memory", factory: ... })` so
every invariant of the abstract contract is verified against this
adapter on every CI run.

## Error namespace

`TENANT_PROVIDER_MEMORY.*` — three codes:

- `DUPLICATE_TENANT` — seed or `add()` collision.
- `TENANT_NOT_FOUND` — `remove()` of unknown id.
- `INVALID_RECORD` — schema failure at the boundary.

Errors that the abstract contract itself can raise
(`TENANT_PROVIDER.INVALID_CURSOR`) flow through unchanged from
`@suaveplan/api-tenant-provider`.

## Out of scope

- DB-backed enumeration — Stage 8 `api-tenant-provider-postgres` /
  `api-tenant-provider-surrealdb`.
- Persistence across process restarts — every `createMemoryTenantProvider`
  call starts from the supplied seed.

## Stage

Stage 4 (Base adapters) of the API plugin system umbrella — see
the design document.