Verification

1. Reproducibility — same input, same output

Run the same request twice. The response body should be byte-identical, and the x-scholar-transform-version header should match. Pin this value in your tests; if it changes, treat it as a signal to re-baseline expected output rather than a regression.

# Run twice, diff the bodies — should be byte-identical.
A=$(curl -sS -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170","style":"vancouver","output":"text"}')
B=$(curl -sS -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170","style":"vancouver","output":"text"}')
diff <(printf '%s' "$A") <(printf '%s' "$B") && echo "OK: identical"

Expected: OK: identical and a non-empty Vancouver-style citation in both responses.

2. Single vs batch parity

The same identifier formatted alone or as part of a batch produces the same item-level output. Batch processing must not silently differ from single processing.

# Single request
curl -sS -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170","style":"vancouver","output":"json"}' | jq .items[0].formatted

# Same DOI in a batch alongside another identifier
curl -sS -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"lines":["10.1038/nphys1170","PMID:30049270"],"style":"vancouver","output":"json"}' | jq .items[0].formatted

Expected: the two items[0].formatted strings are identical for the DOI under test.

3. Provenance headers

Every successful response carries a fixed set of provenance headers. Use curl -i to print them and confirm they exist with the documented values.

curl -i -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170","style":"vancouver","output":"text"}' \
  | grep -iE '^(x-request-id|x-scholar-cache|x-scholar-formatter|x-scholar-style-used|x-scholar-transform-version):'

Expected headers (always present on 2xx /api/format):

• x-request-id — UUID for request correlation
• x-scholar-cache — hit:<key>, miss:<key>, or bypass:<reason>
• x-scholar-transform-version — date-stamped tag for the active normalisation, formatting, and resolver chain

Conditional headers (present only when relevant): x-scholar-formatter, x-scholar-style-used, x-csl-warning, x-csl-alias, x-csl-dependent, x-csl-fetch-style-id.

4. Edge case behaviour

Failure modes follow the contract documented at /engineering-principles. Each curl below should return the documented status code and envelope.

Invalid identifier → 400

curl -sS -i -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"this-is-not-a-doi-or-anything","style":"vancouver"}' \
  | head -n 20

Expected: HTTP/2 400 with body { ok: false, code: BAD_REQUEST, error: <message> }.

Validates but not found → 200 with empty items

# Well-formed DOI that doesn't resolve to any record.
curl -sS -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.9999/this-doi-does-not-exist","style":"vancouver","output":"json"}'

Expected: HTTP/2 200, no successful item resolved. Not-found results are cached briefly to avoid hammering the upstream.

5. Resolver chain

The fallback order per identifier type is published at /.well-known/sources.json and validates against sources.schema.json. Reordering or substituting resolvers is treated as a transform-version change.

# Inspect the live resolver chain manifest.
curl -sS https://scholar-sidekick.com/.well-known/sources.json | jq '.resolvers'

# Confirm transform_version field matches the response header.
curl -sS https://scholar-sidekick.com/.well-known/sources.json | jq -r .transform_version
curl -sSI -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170"}' | grep -i x-scholar-transform-version

Expected: the transform_version in sources.json matches the value in the x-scholar-transform-version response header.

6. OpenAPI contract

The full API surface, schemas, and error semantics are published at the canonical discovery path:

# Fetch the OpenAPI 3.1 spec at the discovery path.
curl -sS https://scholar-sidekick.com/.well-known/openapi.yaml | head -n 40

# AI plugin manifest (points to the same OpenAPI spec).
curl -sS https://scholar-sidekick.com/.well-known/ai-plugin.json | jq .

If something fails

Any verification check that produces unexpected output is a contract violation. File an issue with the request ID (x-request-id) from the offending response, the exact input, and the observed output. Reproducibility is promised; failure to keep that promise is a bug.

Related pages

• Engineering Principles — the determinism contract, edge-case rules, and provenance-header definitions
• API Docs — endpoints, parameters, headers, examples
• /.well-known/sources.json — resolver chain manifest
• /.well-known/openapi.yaml — OpenAPI 3.1 spec