# `persisted-queries` — APQ manifest support

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`persisted-queries` implements Apollo's persisted-query manifest lookup
— the ability for clients to send `{ id }` in place of `{ query }` and
have the engine resolve the id against a build-time-generated manifest.
The feature is Apollo-specific (Yoga uses a different protocol variant)
so the loader lives in this adapter and not in the abstract
`api-graphql` core.

The module exposes three entry points: a filesystem loader, an
in-memory parser for callers that already have the JSON text, and a
direct-from-entries factory for tests. Lookups against an unknown id
raise `GRAPHQL_APOLLO.PERSISTED_QUERY_NOT_FOUND`; malformed input
raises `GRAPHQL_APOLLO.PARSE_FAILED` so callers see a single
configuration-failure code for any manifest shape error.

## Features

- File loader uses `node:fs/promises.readFile` — async-safe in the host
  start-up sequence.
- JSON parser validates the manifest is an object of `string → string`
  before returning; non-string values raise `PARSE_FAILED`.
- Direct factory accepts any `Iterable<[id, query]>` — useful in tests.
- Manifest is frozen on construction; the only mutation surface is
  `lookup(id)` (reads) and `has(id)` (existence check).
- `entries` accessor returns the frozen map for callers that need to
  diff manifests across deploys.

## Usage: Basic

```ts
import { loadPersistedQueryManifest } from "@suaveplan/api-graphql-apollo/persisted-queries";

const manifest = await loadPersistedQueryManifest("./pq.json");
const query = manifest.lookup("abc123");
```

## Usage: Advanced

Build a manifest from an in-process source (e.g. a KV-store fetch) and
wire it into the engine for runtime lookup:

```ts
import { createApolloGraphqlEngine } from "@suaveplan/api-graphql-apollo";
import { createPersistedQueryManifest } from "@suaveplan/api-graphql-apollo/persisted-queries";

const entries = await kv.list("pq:");
const manifest = createPersistedQueryManifest(
    entries.map((e) => [e.key.slice(3), e.value as string])
);
const engine = createApolloGraphqlEngine({ persistedQueries: manifest });
```

## API Reference

- `PersistedQueryManifest` — `{ entries, lookup, has }`.
- `loadPersistedQueryManifest(path: string): Promise<PersistedQueryManifest>`
- `parsePersistedQueryManifest(raw: string): PersistedQueryManifest`
- `createPersistedQueryManifest(entries): PersistedQueryManifest`

## Implementation Notes

Manifest entries are stored in a `Map<string, string>` — O(1) lookup,
deterministic iteration order. The `entries` field returns a new `Map`
constructed from the underlying entries on every access so callers
cannot mutate the live state. The loader maps every filesystem and JSON
failure to `GRAPHQL_APOLLO.PARSE_FAILED` so wire-level diagnostics show
a single code regardless of failure mode.