boxmaker/docs/specs/2026-09-25-roncho-requirements.md

# roncho: what Boxmaker's `memoryd` needs from it

**For:** the agent that develops `roncho` (`git.wntrmute.dev/kyle/roncho`, `~/src/roncho` on titan).
**From:** Boxmaker's design model, 2026-09-25, for milestone M5b. **Status:** requirements, for the
owner to hand over. Boxmaker's M5b spec is written against the release this produces.
`roncho` was being reworked while this was written: the divergences in 3.4 were last checked at
`a9708f1` and are described by behaviour, not by line. Check each one before fixing it.

## 1. Why

Boxmaker is the owner's personal agent harness (Rust, `~/src/boxmaker`). Its memory daemon,
`memoryd`, will sync finished conversation turns to the owner's Honcho on rift, write some
entries as conclusions, search Honcho, and ask its dialectic. The owner wants it to do that
through `roncho`, not through a second client. Today `roncho` cannot be used from Boxmaker:

- It is async only (tokio, reqwest, hyper, futures). Boxmaker has a standing rule: blocking I/O
  with threads, no async runtime, and `memoryd` is the smallest-authority daemon of the set.
- Some of its request and response shapes disagree with the live server. sift's Go client,
  checked against rift on 2026-09-22, found that workspace search takes `{"query", "limit"}` and
  returns a bare JSON array, not a `Page` (`~/src/sift/internal/fleetctx/fleetctx.go`,
  `~/src/sift/docs/P2.md`).
- It defaults to `https://api.honcho.dev`. For Boxmaker, memory text must never leave the owner's
  hosts, so a default that points at a cloud service is a hazard, not a convenience.

Boxmaker's policy (which turns are synced, trust labels, taint) stays in `memoryd`. `roncho` is
the transport and the types: correct, small, and predictable.

## 2. The deployment it must work against

| Fact | Value | Source |
|---|---|---|
| Honcho API | `http://rift.scylla-hammerhead.ts.net:8000`, plain HTTP over the tailnet | `imladris/hw/orion/default.nix`; `sift/docs/PLAN.md` |
| Version | 3.2.0, image `3.2.0-pr1092-7e57fe2` (roncho's SPEC targets 3.2.1) | `imladris/docs/metrics-plan.md` |
| Authentication | apparently none: sift sends no `Authorization` header and succeeds. **Not confirmed.** | `sift/internal/fleetctx/fleetctx.go` |
| Models | deriver, summaries and dialectic on dixie's `ornith-1.5-9b-uncensored`; dialectic answers take 30 to 50 s | `imladris/hw/dixie/default.nix`; `sift/docs/PLAN.md` |
| Workspaces in use | `hermes-fleet`, `guardian-star` (other agents'); each Boxmaker will have its own | `imladris/hw/orion/default.nix` |

**Never write to a workspace you did not create for testing.** `hermes-fleet` and
`guardian-star` hold other agents' live memory. Write tests go to a throwaway workspace (for
example `roncho-test-<date>`), deleted afterwards.

## 3. Requirements

MUST: Boxmaker cannot use `roncho` without it. SHOULD: Boxmaker can work around it, at a cost.

### 3.1 A blocking client with a small dependency graph

- **R1 (MUST)** A blocking API: every operation in 3.3 as a plain function call that returns when
  the response is read. No async runtime is started, required or depended on.
- **R2 (MUST)** Selected by Cargo features so a consumer can build **only** the blocking client:
  `roncho = { …, default-features = false, features = ["blocking"] }` (the name is yours). With
  that, the dependency graph contains none of `tokio`, `reqwest`, `hyper`, `h2`, `futures`,
  `async-stream`, `bytes`, `webpki-roots`. The async client may stay as the default feature.
- **R3 (MUST)** HTTP/1.1 over plain TCP for `http://` URLs, written on `std::net` or with a
  small blocking crate. Boxmaker already has two such clients (`crates/loopd/src/http.rs`,
  `crates/gatewayd/src/http.rs`): one request per connection, `Connection: close`, chunked and
  `Content-Length` bodies.
- **R4 (SHOULD)** `https://` behind an optional feature, using `rustls` 0.23 with the `ring`
  provider and the platform's certificates (`rustls-native-certs` 0.8). Not `webpki-roots`,
  not `aws-lc-rs`. rift needs no TLS today, so this may come after the rest.
- **R5 (MUST)** Every crate in the blocking graph (with and without R4) is on crates.io, is
  licensed under one of MIT, Apache-2.0, ISC, BSD-3-Clause, Unicode-3.0 or Zlib, and does not
  duplicate a different major version of a crate Boxmaker already locks. Boxmaker locks today:
  `serde` 1.0.229, `serde_json` 1.0.151, `rustls` 0.23.45, `ring` 0.17.14,
  `rustls-native-certs` 0.8.4, `thiserror` 2.0.21, `syn` 3, `toml` 1.1.6, `zeroize` 1.9.0.
  Boxmaker's `cargo deny` runs with `multiple-versions = "deny"`.
- **R6 (SHOULD)** Keep the blocking graph small: beyond `serde` and `serde_json` (and R4's TLS
  crates), add as few crates as you can. Prefer timestamps as RFC 3339 strings, ids as strings and
  URLs parsed by hand over `chrono`, `uuid` and `url` in the blocking models. If you keep any of
  them, use `default-features = false` (for `chrono`, no `clock`, which pulls platform time-zone
  crates) and say why in the README. `thiserror` is acceptable: Boxmaker already locks it.
- **R7 (MUST)** Builds and passes its tests with Rust 1.95 (Boxmaker's `rust-version`). Set
  `rust-version` in `Cargo.toml`.
- **R8 (MUST)** A git tag per release that Boxmaker can pin (`rev` or `tag`), and a changelog
  entry saying what changed in the blocking API. Boxmaker will add the git source to its
  `deny.toml` allow-list for this one URL; publishing to crates.io instead is fine too.

### 3.2 Configuration and safety

- **R9 (MUST)** No default base URL in the blocking client. Building a client without one is an
  error. (Keep the async default if you like; the blocking path must not have one.)
- **R10 (MUST)** The API key is optional. When set, it is sent as `Authorization: Bearer`; when
  not, no `Authorization` header at all. Building without a key is not an error. The key never
  appears in an error, a `Debug` output or a log line.
- **R11 (MUST)** The workspace is set explicitly per client. A client is cheap to clone and one
  client serves one workspace, as today. A client is `Send + Sync`.
- **R12 (MUST)** The blocking client takes its configuration only from the caller. It reads no
  environment variables: not `HONCHO_*` (today `build()` falls back to `HONCHO_WORKSPACE_ID`,
  `HONCHO_API_KEY` and `HONCHO_BASE_URL`), not proxy settings (`HTTP_PROXY`, `ALL_PROXY` and so
  on). It does not follow redirects: a 3xx is returned as an error. Memory text is sent only to
  the configured host.
- **R13 (MUST)** Timeouts are set by the caller, per client: a connect timeout, and a read
  timeout that means "no bytes for N seconds", not a total deadline. A dialectic answer takes 30
  to 50 s on the current hardware, so the caller will set a long one there. No hidden retries:
  either implement `max_retries` for idempotent calls with a documented policy, or remove it. The
  blocking client defaults to no retries.
- **R14 (MUST)** A cap on the size of a response body, set by the caller, with a sensible
  default (for example 8 MiB). A body over the cap is an error, and reading stops at the cap.
- **R15 (MUST)** No background threads, no global state, no logging of request or response
  content, no telemetry, no update checks.

### 3.3 Operations the blocking API provides

Each operation is verified against rift (3.4) before it is released. Names are suggestions.

| # | Operation | Honcho endpoint (as roncho has it today; verify) | Boxmaker's use |
|---|---|---|---|
| O1 | get or create the workspace | `POST /v3/workspaces` (in the async client as `get_or_create_workspace`) | first start |
| O2 | get or create a peer, with metadata and configuration | `POST peers` | the owner, the agent, other agents met in channels |
| O3 | get or create a session, with its peers and each peer's `observe_me` / `observe_others` | `POST sessions` | one Honcho session per Boxmaker session |
| O4 | add messages in a batch, each with `peer_id`, `content`, `metadata` (a JSON object) and `created_at` | `POST sessions/{s}/messages` | the sync of finished turns; the metadata holds Boxmaker's session id, record number and labels |
| O5 | list a session's messages, paged, with filters | `POST sessions/{s}/messages/list` | checking what a sync already sent |
| O6 | delete a session | `DELETE sessions/{s}` | rebuilding |
| O7 | delete the workspace, and report the "active sessions" conflict (409) as its own error | `DELETE /v3/workspaces/{id}` (the async `delete_workspace` returns it as a generic error) | rebuilding |
| O8 | create conclusions in a batch (1 to 100), `content`, `observer_id`, `observed_id`, optional `session_id` | `POST conclusions` | entries moved out of identity; trusted notes |
| O9 | list, query and delete conclusions | `POST conclusions/list`, `POST conclusions/query`, `DELETE conclusions/{id}` | rebuilding; checks |
| O10 | search the workspace, with a result limit | `POST search` (rift: `{"query", "limit"}` and a bare array) | `recall` |
| O11 | search a peer's messages and a session's messages, with a limit | `POST peers/{p}/search`, `POST sessions/{s}/search` | `recall`, narrowed |
| O12 | the dialectic, non-streaming: query, target, session, reasoning level, whether to include evidence | `POST peers/{p}/chat`, `POST chat` | `ask_memory` |
| O13 | a cheap probe that the server is up and speaks the expected version | whatever Honcho 3.2 offers; if nothing, a cheap read (O1's get) | `memoryd`'s startup and health |

- **R16 (MUST)** O1 to O13 in the blocking API, with typed requests and responses. Fields the
  server may add later are ignored when decoding; fields Boxmaker relies on are required.
- **R17 (SHOULD)** O12 streaming, with the read timeout of R13 applying between chunks, so a
  caller can tell a slow answer from a dead one. The SSE must be parsed by lines across network
  chunks (see R20).
- **R18 (MUST)** One error type for the blocking client that lets the caller tell apart: cannot
  connect, timed out (no bytes), HTTP status with the first 4 KiB of the body, response too large,
  response not decodable, invalid configuration, and the workspace-delete conflict. Implements
  `std::error::Error` and `Display`; never contains the API key.

### 3.4 Correctness against rift

- **R19 (MUST)** Every O-operation is exercised against rift 3.2.0 in a throwaway workspace (reads
  may use `hermes-fleet`, writes never), and the result recorded in a compatibility document in
  the repository: endpoint, method, request shape, response shape, the date, and the server's
  version. Where Honcho's docs and rift disagree, rift wins and the document says so.
- **R20 (MUST)** Fix these divergences, found by reading the async client; they apply to the
  blocking client too, and any fix to shared models or request code applies to both:
  - **Search shapes (O10, O11).** rift takes `{"query", "limit"}` at the top level and answers
    with a bare array (sift, above). roncho's workspace search sends `{"query"}` with no limit, and
    its peer and session searches send `{"filters": {"query"}}`; all three decode the answer as a
    `Page`. There is no way to set a limit.
  - **Paging of messages (O5).** `list_messages` builds the `page`, `size` and `reverse` query and
    never sends it, so a paged read can keep getting the first page.
  - **Message fields.** `Message.role` is required when decoding; sift's verified field list has no
    `role`. Make every field Boxmaker does not need optional, and check which fields rift sends.
  - **List methods.** Peer and session lists use `GET`, while Honcho 3's other lists (messages,
    conclusions, workspaces) are `POST …/list`. Settle on what rift does, and the same for
    `peers/{p}/context`.
  - **Streaming.** The SSE reader splits each network chunk into lines on its own, so a line split
    across two chunks is misparsed. Buffer until a newline.
  - **Build errors.** A missing workspace is reported as `MissingApiKey`, and a missing key is an
    error at all (R10).
  - **Retries.** `max_retries` is stored and never read (R13).
  - **Workspace delete.** The "active sessions" conflict is not told apart from other failures
    (O7, R18).
- **R21 (MUST)** Tests for the blocking client against a fake server in the test process
  (`std::net::TcpListener`), covering each O-operation's request bytes and response decoding, and
  also: a refused connection, a server that sends nothing (read timeout), a server that stops
  mid-body, a redirect (refused), an oversized body (capped), a non-JSON body, a 409 on workspace
  delete, and that no `Authorization` header is sent without a key. Every wait in a test has a
  limit.
- **R22 (SHOULD)** A live suite, ignored by default, run with an environment variable naming the
  server, that performs R19's checks and deletes its workspace at the end.

### 3.5 Semantics to find out and write down

Boxmaker's design depends on these answers. For each, check Honcho 3.2's documentation and rift,
and record what you found (or "not found") in the compatibility document. Do not guess.

- **Q1** Is authentication off on rift? If it can be on, are keys scoped per workspace, and is
  there a read-only key?
- **Q2** Can a single message be deleted or edited in 3.2.0? What does deleting a session remove
  from conclusions, representations and summaries derived from it?
- **Q3** The deriver: what triggers it (per message, per batch, per session), how long until
  conclusions appear under normal load, how to see whether a message has been processed, and which
  peer, session or workspace configuration keys turn derivation off for a peer.
- **Q4** Message metadata: can search (O10, O11) and the dialectic (O12) be filtered by metadata
  (so that labelled messages can be excluded), and what is the filter grammar?
- **Q5** What does a conclusion's `source_ids` refer to? Can a conclusion be traced to the
  messages it came from?
- **Q6** When does workspace deletion return 409 ("active sessions"), and how does a caller make a
  session inactive?
- **Q7** Is there a health or version endpoint (O13)?
- **Q8** Does the `3.2.0-pr1092` image differ from upstream 3.2.0 or 3.2.1 in any endpoint above?

## 4. Out of scope for roncho

- Which turns are synced, trust per workspace, taint, sanitising text: Boxmaker's `memoryd`.
- Queues and progress tracking of a sync: `memoryd` keeps its own.
- A CLI. Boxmaker does not need one.

## 5. Done when

- A tagged release exists whose blocking feature meets R1 to R18, with the R20 fixes.
- `cargo tree -e normal --no-default-features -F blocking` (with your feature name) shows no
  crate from R2's list, and every crate meets R5.
- The compatibility document covers O1 to O13 and Q1 to Q8, dated, with rift's version.
- The fake-server tests of R21 pass with Rust 1.95; the live suite of R22 passes against rift.
- The owner is told the tag, and anything in this document that could not be done, and why.