# DeltaX Evaluate — Developer Kit v1

## Current hosted soak — beta2

Hosted Evaluate is in controlled free soak (2026-09-16.beta2). Access is restricted. Selection is not execution. The offline kit is the pinned beta1 teaching snapshot.

- Live API version: `2026-09-16.beta2`.
- Route: `POST /v1/evaluations`.
- Profile: `deltax-hosted-bounded-review-evaluation-v1`.
- Restricted access; x402 off; not GA. No public signup, pricing, or SLA.
- Responses do not execute candidates or grant downstream authority.

## Historical / pinned teaching snapshot — beta1

This kit remains `2026-09-16.beta1`. Its OpenAPI, schemas, client, and synthetic
specimens teach that pinned version; they are not the live beta2 contract.
`reference.md` and `openapi.yaml` separate current product status from historical
snapshot metadata. The beta1 `.invalid` token URL is a non-routable placeholder.
Use the approved beta2 contract and configuration for restricted hosted access.

Documentation status annotations have been refreshed. The beta1 protocol,
fixtures, and false effect/authority flags remain pinned. The refreshed package
has new checksums; it is not a beta2 kit or a service-access grant.

## Authority ceiling

- One profile only: `deltax-hosted-bounded-review-evaluation-v1`.
- One operation only: `POST /v1/evaluations`.
- Selectable candidate classes: `analyze`, `compare`, `draft`, `validate`.
- The `external` candidate class is shadow-only and can never be selected.
- A response returns `selected` or `governed_noop_refusal`.
- No response executes a candidate, creates an external effect, applies
  learning, verifies operator-reported context, or authorizes downstream work.
- A selected candidate is not established as correct or safe. A trace is not a
  certification or legal non-repudiation record.

## Verify the kit offline

The verifier uses only the Python standard library and performs no network
calls:

```sh
python3 conformance/run.py
```

It verifies the pinned OpenAPI and reference hashes, manifests, derived JSON
schemas, the complete synthetic contract-specimen matrix, closed authority
flags, client fail-closed behavior, checksums, and (when present) the ZIP
sidecar. Every fixture case is labeled `synthetic_contract_specimen`,
`observed_runtime_result: false`, `live_tested: false`, and
`grants_authority: false`.

You can also inspect the request that the Python client would serialize without
creating a client or making a network call:

```sh
python3 python/deltax_client.py --fixture fixtures/cases.json --case selected
```

## Learn the protocol

1. Open `fixtures/cases.json` and inspect the `selected` request. It contains a
   bounded objective, scalar-only context, and a finite candidate field.
2. Compare it with the paired `selected` response. The chosen candidate is a
   submitted, non-`external` ID; every effect and authority flag stays `false`.
3. Review the `refusal` pair. An all-external field fails closed to
   `governed_noop_refusal`.
4. Read the `unknown_top_level_field`, `wrong_profile`,
   `unknown_semantic_class`, `duplicate_candidate_id`, and `nested_context`
   cases to see strict, fail-closed request validation.
5. Compare `idempotency_replay_exact` with
   `idempotency_conflict_changed_digest`: an exact request with the same scoped
   key replays the byte-identical committed response, while a changed canonical
   request digest under the same key returns `409`.
6. Review `unauthenticated_missing_token`, `forbidden_missing_scope`, and
   `forbidden_not_allowlisted` to distinguish identity, scope, and server-owned
   allowlist failure.
7. Review `rate_limited_retry_after` and
   `service_unavailable_retry_after`; both carry the required bounded
   `Retry-After` specimen and neither authorizes an automatic retry.
8. Use `python/deltax_client.py` as a standard-library reference
   client only after separate access details are issued. It has no default
   hostname, rejects `.invalid` URLs, makes one attempt, and validates the
   no-authority response boundary.

## Request contract

Required headers:

| Header | Rule |
|---|---|
| `Authorization` | OAuth 2.0 bearer token with `deltax:evaluate`; issuer and credentials are unresolved in the historical beta1 snapshot. |
| `Content-Type` | `application/json` with UTF-8-compatible encoding. |
| `X-DeltaX-API-Version` | Exactly `2026-09-16.beta1`. |
| `Idempotency-Key` | 16–128 characters matching `^[A-Za-z0-9._~-]+$`. |

The request body is closed. It requires `profile_id`, `objective`, `context`,
and one to eight `candidates`. Context values must be scalar strings, finite
numbers, booleans, or `null`; nested objects, arrays, URLs, credentials, files,
and executable content are outside the profile.

## Retry contract

Only `408`, `429`, and `503` are marked retryable. `429` and `503` require a
bounded `Retry-After` value. The reference client intentionally performs no
automatic retry: callers must separately define jitter, an attempt ceiling,
and an end-to-end deadline. Never retry `400`, `401`, `403`, `409`, `413`,
`415`, `422`, or `431` without changing the invalid authority or content.

## Synthetic teaching fixture

“Synthetic Evidence Review” is a display label for the examples in this kit,
not a second wire profile, selectable domain, registry entry, or operational
deployment. The wire request still uses the fixed hosted evaluation profile.
Any additional domain or later registry requires its own versioned public
contract, tests, evidence, and explicit release decision.

## Fixture matrix

| Contract condition | Case | Specimen status |
|---|---|---|
| Valid mixed selectable and shadow-only field | `selected` | `200 selected`; all effect and authority flags false |
| External-only field | `refusal` | `200 governed_noop_refusal`; all effect and authority flags false |
| Unknown top-level field | `unknown_top_level_field` | `400 invalid_request` |
| Wrong profile | `wrong_profile` | `400 invalid_request` |
| Unknown semantic class | `unknown_semantic_class` | `422 unprocessable_content` |
| Duplicate candidate ID | `duplicate_candidate_id` | `422 unprocessable_content` |
| Nested context | `nested_context` | Fail closed with `422 unprocessable_content` |
| Exact request replay under the same key | `idempotency_replay_exact` | Byte-identical committed response specimen |
| Changed digest under the same key | `idempotency_conflict_changed_digest` | `409 idempotency_conflict` |
| Missing bearer token | `unauthenticated_missing_token` | `401 unauthenticated` |
| Missing required scope | `forbidden_missing_scope` | `403 forbidden` |
| Principal absent from server allowlist | `forbidden_not_allowlisted` | `403 forbidden` |
| Quota backpressure | `rate_limited_retry_after` | `429 rate_limited` with `Retry-After` |
| Service backpressure | `service_unavailable_retry_after` | `503 service_unavailable` with `Retry-After` |

## Files

| Path | Purpose |
|---|---|
| `openapi.yaml` | Byte-identical normative design contract copy. |
| `reference.md` | Byte-identical generated human reference copy. |
| `agent-contract.json` | Compact machine-readable integration rules. |
| `profile-manifest.json` | One-profile teaching and authority declaration. |
| `schemas/` | Standalone JSON Schema derivatives for local tooling. |
| `fixtures/cases.json` | Complete synthetic contract-specimen matrix; no runtime observations. |
| `python/deltax_client.py` | Typed standard-library reference client; no default live target or retries. |
| `examples/curl.md` | Guarded curl-shaped integration guide requiring explicit values. |
| `conformance/run.py` | Offline integrity and fixture verifier. |
| `SHA256SUMS` | Hashes for all source files included in the archive. |
| `deltax-evaluate-developer-kit-2026-09-16.beta1.zip` | Deterministic archive of this source kit. |
| `deltax-evaluate-developer-kit-2026-09-16.beta1.zip.sha256` | Hash of the deterministic ZIP. |

Bounded evaluation only. A response does not execute or authorize a candidate
and is not professional advice, certification, a safety determination, or
proof of correctness.