test: lock in multi-service contract via EchoService test

Demonstrates that a new service can be implemented using only the
public primitives from src/core/ — HttpClient, StaticAuthHeaderProvider,
and resolveCoreConfig — without touching auth/ or services/atlantic/.

Also asserts the disambiguation property: two services exposing a
method with the same name (e.g. submitQuery) stay unambiguous because
each lives on its own instance/namespace.

The full registration walkthrough (HcloudSurface enum, HcloudClient
namespace, CLI dispatcher list, src/index.ts re-exports) is documented
in docs/guides/adding-a-service.md.

Phase 5 of /docs/plans/2026-05-07-001-feat-rename-to-hcloud-multi-service-sdk-plan.md

Author: skusnierz

docs/brainstorms/atlantic-bun-sdk-requirements.md

@@ -0,0 +1,161 @@
+---
+date: 2026-05-06
+topic: atlantic-bun-sdk
+---
+
+# Atlantic Bun SDK
+
+## Summary
+
+Build a Bun-first TypeScript SDK and CLI for Atlantic that covers the full public API while also providing agent-friendly workflow helpers for query submission, lifecycle tracking, retries, buckets, artifacts, and x402 payments.
+
+---
+
+## Problem Frame
+
+Atlantic already exposes proving, query lifecycle, bucket, and payment capabilities through public API documentation and the `atlantic-api` AI skill. A developer or coding agent can call those endpoints directly, but doing so forces every integration to rediscover request composition, multipart file handling, polling, retry semantics, x402 payment flow, artifact lookup, and error interpretation.
+
+The SDK should make Atlantic easier to use from Bun and TypeScript projects without hiding the underlying API model. It should also give agents a predictable surface with clear method descriptions, safer defaults, and workflow-level helpers so agent-built integrations are less likely to hallucinate endpoints, mishandle payments, or lose query state.
+
+---
+
+## Actors
+
+- A1. SDK user: A developer integrating Atlantic into a Bun or TypeScript application.
+- A2. CLI user: A developer or operator running Atlantic workflows from a terminal.
+- A3. AI agent: A coding or operations agent using the SDK/CLI with limited context and needing strong descriptions and guardrails.
+- A4. Atlantic API: The existing Herodotus Atlantic service that receives queries, tracks jobs, manages buckets, and handles x402 challenges.
+
+---
+
+## Key Flows
+
+- F1. Submit and track a query
+  - **Trigger:** A user wants to submit a Cairo program, PIE, or proof-related input to Atlantic.
+  - **Actors:** A1, A2, A3, A4
+  - **Steps:** The caller prepares input files and query options, submits the request, receives an Atlantic query ID, and can poll or inspect details until the query reaches a terminal state.
+  - **Outcome:** The caller has a durable query ID, current status, and a clear path to metadata or artifacts.
+  - **Covered by:** R1, R2, R5, R8, R9
+
+- F2. Recover or retry a query
+  - **Trigger:** A query fails, a submit operation is ambiguous, or a caller needs to locate a query by deduplication key.
+  - **Actors:** A1, A2, A3, A4
+  - **Steps:** The caller retrieves query details or looks up by deduplication key, determines whether retry is allowed, retries through the API when valid, and surfaces non-retriable states clearly.
+  - **Outcome:** Retriable failures are restarted without guessing; non-retriable failures are explained.
+  - **Covered by:** R3, R4, R6, R9, R10
+
+- F3. Work with Applicative Recursion buckets
+  - **Trigger:** A caller wants to group multiple Atlantic queries into a bucket for Applicative Recursion.
+  - **Actors:** A1, A2, A3, A4
+  - **Steps:** The caller creates or lists buckets, submits bucket-linked queries when supported, inspects bucket details and associated queries, and closes a bucket when ready.
+  - **Outcome:** Bucket workflows are available through both SDK and CLI without manual endpoint composition.
+  - **Covered by:** R7, R8, R9, R11
+
+- F4. Pay with x402 when required
+  - **Trigger:** A submit request receives a payment challenge because project credits are insufficient or the caller uses an anonymous wallet flow.
+  - **Actors:** A1, A3, A4
+  - **Steps:** The SDK exposes the challenge, signs or delegates signing through a wallet adapter, retries the original submit with a payment signature, and returns the settlement response alongside the query result.
+  - **Outcome:** Payment is handled according to the public x402 flow, without preemptive signatures or invented payment endpoints.
+  - **Covered by:** R12, R13, R14, R15
+
+---
+
+## Requirements
+
+**API coverage**
+- R1. The SDK must expose typed methods for every public Atlantic API capability documented in the current Atlantic OpenAPI contract: health check, submit query, get query by ID, get query by dedup ID, list queries, query stats, query jobs, retry query, list buckets, create bucket, get bucket details, and close bucket.
+- R2. Query submission must support the documented Atlantic inputs and options, including program, input, PIE, and proof file inputs; Cairo version and VM options; result selection; layouts; prover selection; declared job size; network selection; deduplication identifiers; external identifiers; and bucket-related fields.
+- R3. Query lookup must support direct query ID lookup and deduplication-key lookup as separate explicit capabilities.
+- R4. Retry support must call the public retry capability and clearly distinguish retriable, non-retriable, max-retry, missing-query, forbidden, and wrong-state outcomes.
+- R5. Query lifecycle support must make status, step, job list, metadata URLs, and terminal-state inspection easy to consume without requiring callers to manually understand every raw API response.
+- R6. List operations must support pagination where the Atlantic API supports it.
+- R7. Bucket support must cover listing buckets, creating buckets, fetching bucket details with associated queries, closing buckets, and submitting bucket-linked queries where the API permits them.
+
+**Agent-first workflow helpers**
+- R8. The SDK must include higher-level helpers for common workflows: submit-and-return-ID, submit-and-wait, wait-for-query, retry-if-retriable, get-query-with-jobs, and bucket-oriented submission.
+- R9. Workflow helpers must preserve caller control over polling intervals, timeout budgets, retry budgets, and terminal-state behavior.
+- R10. The SDK must keep Atlantic query IDs, dedup IDs, and bucket IDs visible as first-class outputs rather than hiding them inside opaque workflow results.
+- R11. Agent-facing helper descriptions must include what the helper does, when to use it, required inputs, important constraints, expected result, and common failure modes.
+
+**x402 payments**
+- R12. The SDK must support Atlantic's documented x402 v2 flow for `submit query`, including challenge parsing, payment-signature retry, and settlement-response parsing.
+- R13. The SDK must support both API-key fallback payments and anonymous wallet payments, while making their behavioral differences explicit to the caller.
+- R14. The SDK must prevent or clearly warn against unsafe x402 usage: preemptive payment signatures, reused successful payment signatures, hardcoded payment requirements, anonymous `dedupId` usage, anonymous bucket usage, and double-payment after ambiguous settlement.
+- R15. x402 signing must be wallet-adapter friendly so applications can provide their own signing implementation rather than coupling the SDK to a single wallet source.
+
+**CLI**
+- R16. The CLI must expose commands for the same main capabilities as the SDK: submit query, retry query, get query details, get query by dedup ID, list queries, get query jobs, query stats, list buckets, create bucket, get bucket, close bucket, and health check.
+- R17. CLI commands must support file-path inputs for query submission and must print machine-readable JSON by default or through an explicit mode.
+- R18. CLI commands must support environment-based configuration for the Atlantic base URL, API key, and payment-related wallet configuration.
+- R19. CLI output must preserve important identifiers, status, payment receipt data, and error details so agents can chain commands reliably.
+
+**Developer experience and quality**
+- R20. The package must be Bun-first while remaining idiomatic TypeScript for library consumers.
+- R21. Public SDK methods must have clear names, strong TypeScript types, and documentation comments that explain behavior rather than merely restating parameter names.
+- R22. The SDK must separate low-level API methods from higher-level workflow helpers so advanced users can keep exact control while agents and common integrations get safer defaults.
+- R23. Errors must be structured enough for callers to branch on category, HTTP status where available, Atlantic message/code where available, and payment-specific failure class where available.
+- R24. The codebase must be organized for maintainability, with focused modules, minimal duplication, and tests that cover request construction, response parsing, x402 behavior, workflow helpers, and CLI command behavior.
+
+---
+
+## Acceptance Examples
+
+- AE1. **Covers R1, R16.** Given a user wants to inspect their Atlantic usage from code or terminal, when they list queries, fetch query details, fetch query jobs, or query stats, then both SDK and CLI expose those capabilities without requiring manual URL construction.
+- AE2. **Covers R2, R8, R10.** Given a user submits a query using a local PIE file, when submission succeeds, then the result includes the Atlantic query ID and any relevant metadata needed for later polling or artifact inspection.
+- AE3. **Covers R4, R23.** Given a failed query is not retriable or has exceeded retry limits, when the caller retries it, then the SDK/CLI returns a structured failure that lets the caller distinguish the reason without parsing prose.
+- AE4. **Covers R7, R16.** Given a user is building an Applicative Recursion flow, when they create a bucket, submit bucket-linked queries, inspect the bucket, and close it, then each step is available through documented SDK methods and CLI commands.
+- AE5. **Covers R12, R14, R15.** Given a submit request receives an x402 challenge, when the caller provides a wallet signing adapter, then the SDK signs the documented payment authorization, retries the original submit, returns the query result and settlement response, and does not reuse a successful payment signature for a later query.
+- AE6. **Covers R11, R21.** Given an AI agent sees only the SDK method descriptions, when it chooses between direct API methods and workflow helpers, then the descriptions are concrete enough to avoid inventing unsupported payment endpoints or unsupported anonymous-flow bucket/dedup behavior.
+- AE7. **Covers R17, R19.** Given an agent runs the CLI in a shell workflow, when a command succeeds or fails, then the output includes stable JSON fields for IDs, status, result data, payment receipt data, and structured errors.
+
+---
+
+## Success Criteria
+
+- A developer can complete a normal Atlantic proof workflow from Bun using the SDK without reading the raw OpenAPI spec for every call.
+- An AI agent can use the SDK/CLI safely for submit, poll, retry, bucket, and x402 workflows with low hallucination risk.
+- Full public API coverage exists without sacrificing clear higher-level workflow helpers.
+- Payment behavior follows Atlantic's documented x402 flow and avoids double-payment or unsupported anonymous-flow behavior.
+- A downstream planning or implementation agent can proceed from this document without inventing SDK product behavior or CLI scope.
+
+---
+
+## Scope Boundaries
+
+- Do not change the Atlantic backend or public API as part of this SDK effort.
+- Do not invent payment endpoints or payment flows outside the documented x402 behavior on query submission.
+- Do not build a GUI, dashboard, or hosted service.
+- Do not hide all Atlantic concepts behind a single opaque workflow; query IDs, dedup IDs, statuses, jobs, buckets, and payment receipts remain visible.
+- Do not implement persistent state storage as a required SDK feature in the first version; applications may persist IDs and results themselves.
+- Do not make on-chain verification adapters a blocker unless they are thin helpers around documented Atlantic results and public integration points.
+
+---
+
+## Key Decisions
+
+- Full API plus agent-first helpers: The SDK should not choose between complete endpoint coverage and ergonomic workflows; it needs both because direct developers and AI agents have different needs.
+- SDK as the source of logic, CLI as operational surface: Shared SDK behavior prevents divergent request handling, x402 semantics, and error interpretation between code and terminal usage.
+- x402 scoped to documented submit flow: This keeps payment support useful while avoiding hallucinated endpoints and unsafe payment abstractions.
+- Explicit IDs and structured errors: Atlantic workflows are asynchronous and operational; callers need durable identifiers and branchable errors more than opaque convenience wrappers.
+- Documentation comments are part of the product: Method descriptions should guide agents and developers toward correct usage, not merely satisfy generated API documentation.
+
+---
+
+## Dependencies / Assumptions
+
+- The current source of truth is the Atlantic OpenAPI contract, the Atlantic API docs, the `atlantic-api` AI skill, and the existing Atlantic route schemas.
+- Bun is the primary runtime and package manager target.
+- TypeScript users are a primary audience, so types and documentation comments carry product value.
+- Wallet signing should be adapter-based because caller environments vary across agents, CLIs, server apps, and local scripts.
+- API-key authentication remains the normal flow; x402 is used when required by Atlantic or when anonymous wallet flow is intentionally used.
+
+---
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R12, R15][Technical] Which wallet/signing adapter shape best supports Bun CLI, server-side SDK use, and external wallet clients without overcoupling?
+- [Affects R17, R18][Technical] What exact CLI command naming and configuration precedence should be used for environment variables, flags, and config files?
+- [Affects R24][Needs research] Should SDK types be generated from OpenAPI, hand-authored from source schemas, or combined with a generated base plus curated workflow types?
+- [Affects R8, R9][Technical] What default polling interval, timeout, and retry budgets should helpers use?