2026-11-11 17:03:12 +00:00
# Desk feed door: the list and read wire between Bifrost and a Mind's Huginn
Status, 2026-11-11: the list and read wire described here is on `main` (`DeskRequest::Forks` ,
`DeskRequest::Fork` , `DeskResponse::Forks` , `DeskResponse::Fork` ; `crates/huginn-mind/src/desk_wire.rs`
and `desk_wire/reads.rs` ; the socket is `crates/huginn-daemon/src/desk_door.rs` ). No running daemon
2026-11-11 21:24:36 +00:00
binds a desk socket yet (follow-up `eureka-substrate:follow_up:desk-door-ops-root-run` ). The reader
shapes are built: the card's `raised_at` and `decider_count` , the record's `answerer_count` , the
2026-11-14 02:15:20 +00:00
nullable `answerer` , and the withholding of account ids from a non-decider (below). The listing gate
is built too: a reader who is not a decider sees a fork only while the Mind lists it (Listing, below).
Both are `cut-desk-feed-raised-at` and `cut-desk-feed-listing` in the `eureka-substrate` campaign.
2026-11-11 17:03:12 +00:00
2026-11-14 02:15:20 +00:00
**Operator note.** After deploy, a non-decider's Desk row for a Mind is empty until that Mind lists a
fork. Say so in #minds before the feed goes live. Neither Bifrost's receiver nor the ops root-run
(`desk-door-ops-root-run` ) goes live on a Mind holding private questions before this is deployed.
2026-11-11 17:14:27 +00:00
2026-11-11 17:03:12 +00:00
This page is the wire contract for the consumer, Bifrost's `UnixSocketDeskDoor` (Bifrost PR #67 ,
`docs/desk-feed-design.md` ). The golden bytes are in `crates/huginn-mind/tests/fixtures/desk-feed/` .
Huginn's own encoders write them (`crates/huginn-mind/tests/desk_feed_fixtures.rs` ), so a decoder
2026-11-11 18:27:59 +00:00
that reads them reads the door. The reader-count shapes are CultLib's bytes, vendored in
2026-11-11 21:24:36 +00:00
`cultlib-d3025d3c/` (below); Huginn's types decode and re-encode every vendored vector byte for byte. The document shapes inside the payload (`gamecult.fork.list.v0` ,
2026-11-11 17:03:12 +00:00
`gamecult.fork.entry.v0` , `gamecult.fork.card.v0` , `gamecult.fork.record.v0` ,
`gamecult.desk_answer.v0` , `gamecult.fork.refusal.v0` ) are CultLib's
(`contracts/cultnet/governance/fork-card.md` ) and are not restated here.
## One socket per Mind
- Each Mind's Huginn daemon binds its own socket, given by `--desk-socket <absolute path>` and
`--desk-peer-uid <uid>` (both or neither). The ops plan names `/run/huginn-desk/<mind>.sock` , mode
0660, group `huginn-desk` .
- The kernel's peer credential is checked before a byte is read. Only the configured uid (Bifrost's)
is answered; any other peer is closed with nothing read or written. That check is the whole
authentication: Bifrost vouches for `subject` and `deciders` , and Huginn never sees the member's
token.
- Each connection carries one request frame and gets one reply frame, all within 1 second. A
retry is a new connection. Huginn answers each read from its live image at one snapshot. It keeps
no cache, and Bifrost needs none: the list's `stamp` (`s<N>` ) is the change signal.
- Huginn serves only its own Mind. A request whose `mind` is another instance is refused
(`Refused(...)` ).
2026-11-11 17:14:27 +00:00
## Where forks come from
A fork is any question the Mind holds, in any of its campaigns, that is showable. Showable
(`showable` , `desk_wire.rs` ) means at least two options, no blank option text or `depends` line,
and at least one decider on the call. An in-force question is `open` . A question with any
resolution in force is `recorded` (a closed card, `ruling` set when an in-force ruling answers it).
That set includes the questions holding a spec (`huginn blocked` ) and the open questions of every
campaign (`huginn open` ). Nothing else in the mind is a fork: follow-ups, findings, research and
Persona state never reach the desk.
The fixtures use the fork id `eureka-substrate:question:desk-listing-authority` , a question Eureka's
mind holds. The record's answers, notes and `options_hash` are synthetic: the hash is CultLib's
sample digest.
2026-11-11 17:03:12 +00:00
## Framing and envelope
```
frame = u32 big-endian length || message
message = MessagePack map, CultNet schema v0 (cultnet-rs encode_cultnet_message_to_vec)
payload = message["payload"], standard base64 of named MessagePack (rmp_serde::to_vec_named)
```
- Request message: `schemaVersion` `cultnet.operation_request.v0` , `serviceId` `huginn.desk` ,
`operation` `forks` (list) or `fork` (read), `payloadSchema` `huginn.desk_request.v1` ,
`payloadEncoding` `messagepack-base64` , `messageId` (at most 256 bytes, echoed back).
- Response message: `cultnet.operation_response.v0` , the same `serviceId` , `operation` and
`messageId` , `status` `accepted` or `rejected` , and `sourceRuntimeId` (informational: do not
compare it). The `payloadSchema` is `huginn.desk_response.v1` , or
`gamecult.cultnet.operation_failure.v1` when the envelope or payload did not decode.
2026-11-11 17:14:27 +00:00
- Operation messages (requests, responses, failures) have their keys written in sorted order,
with absent optionals omitted. The CultNet `Error` message does not follow that: its keys come in
CultNet's raw order (`schemaVersion` , `error` , `routingHint` , `code` , `details` ), and absent
values are written as nil (fixture `error.response` ). Decode by key, never by position.
- An operation failure carries `diagnostics` , a list holding the failure code (fixture
`failure.response` ). It is absent on every other response.
- The door also answers `cultnet.schema_catalog_request.v0` with the catalog of the two desk
schemas (`huginn.desk_request.v1` , `huginn.desk_response.v1` , with their JSON Schemas). No
fixture pins that reply, because it embeds the schema text.
2026-11-11 17:03:12 +00:00
- Frame bound: 65536 bytes each way. A reply past it is refused by name, never truncated.
## Payloads
Rust's externally tagged enums: a one-key map from the variant name to its fields. Every field is
written; `null` where absent.
Request (`huginn.desk_request.v1` ):
| operation | payload |
|---|---|
| `forks` | `{"Forks": {mind, subject, deciders, status, cursor, limit}}` . `status` is `"open"` , `"recorded"` or nil (both); `cursor` is `"c<N>"` (N from 1) or nil; `limit` 0..50, where 0 returns counts and stamp only. |
| `fork` | `{"Fork": {mind, subject, deciders, fork_id}}` |
`deciders` is the Mind's admin-set list for this call: 1 to 64 distinct ids, sent on every call.
Huginn keeps no copy. `subject` is the verified Bifrost account id of the reader. The reads carry
no `authority` , and a payload that names it is refused whole.
2026-11-11 17:35:49 +00:00
**Account ids.** `subject` , every `deciders` entry and every stored `answerer` are Bifrost account ids:
`UserAccount.Id` in lowercase D-format, 8-4-4-4-12 lowercase hex (Bifrost renders it in
`DeskEndpoints.cs` with `accountId.Value.ToString("D")` , and `StartupConfigurationValidator.cs`
refuses any decider not in that form). That is the same grammar Huginn names for `RequestId`
(`uuid_text` ). These ids are opaque random UUIDs. A Matrix id, an email, a display name or any other
2026-11-14 02:15:20 +00:00
handle is never one of them. Bifrost enforces the grammar, and so does Huginn's door: `subject` and
every `deciders` entry are read as `AccountId` (`eureka-pipeline` ), and decode refuses any other shape as
`payload-not-a-request` , naming the field and never quoting the value (fixtures
`read-mxid-decider.request` and `read-email-subject.request` , each with its `.failure.response` ). A
subject is stored as `answerer` on an answer, and the stored `desk_answer.answerer` is an `AccountId` too,
so no other shape can enter the mind. The test
2026-11-11 17:35:49 +00:00
`every_account_id_in_the_fixtures_is_a_lowercase_d_format_uuid` pins the grammar. The fixtures use
synthetic UUIDs.
2026-11-11 21:24:36 +00:00
## Account ids by reader
2026-11-11 17:38:52 +00:00
A reader is a **decider ** when the call's `subject` is in the call's `deciders` , compared byte for
2026-11-11 21:24:36 +00:00
byte; both values are in the account-id format above. Any other reader is a non-decider. The
reader is worked out per call and stored nowhere.
2026-11-11 17:38:52 +00:00
- **Ruled (Persona, 2026-11-11; follow-up `chat-mind-20261111T150417226Z-t167` ):** the door, not
Bifrost, withholds account ids from a non-decider and returns a count instead. Bifrost cannot do
2026-11-11 21:24:36 +00:00
it, because the card is opaque to it. A decider sees the ids. The ruling is
2026-11-11 17:44:45 +00:00
`eureka-substrate:ruling:desk-read-visibility-withheld-ids` .
2026-11-11 20:04:04 +00:00
- **The shape**, pinned to CultLib commit `d3025d3c19674803ad32eb2335461b8cbc22bd28` (#118 "null-answerer vectors for
Revision and Retraction", additive over `3a51bbab` #117 "Fork card: decider_count, answerer_count,
nullable answerer (reader views)", on `af914253` #115 `raised_at` ;
2026-11-11 18:27:59 +00:00
ruling `eureka-substrate:ruling:desk-reader-counts-shape` ). The bytes are CultLib's own vectors
(`contracts/cultnet/governance/fork-card-vectors.json` , `messagePackHex` ), vendored unedited in
2026-11-11 20:04:04 +00:00
`crates/huginn-mind/tests/fixtures/desk-feed/cultlib-d3025d3c/` (its README lists each file and
2026-11-11 21:24:36 +00:00
its vector name). Huginn's `ForkCard` , `ForkRecord` , `ForkDeskAnswer` and `ForkEntry` decode all
14 of them and re-encode them byte for byte. Read off those bytes:
2026-11-11 18:27:59 +00:00
- **Card:** 18 keys, header `DE 00 12` (map16): `schemaVersion` plus 17 fields, in this order:
`fork_id, title, context, options, recommendation, depends, leans, flag, raised_in, raised_at,
deciders, decider_count, status, ruling, ruled_from, order, options_hash`. ` raised_at` is an
RFC3339 string or nil, always written. `decider_count` is an integer from 1 to 64 right after
2026-11-11 21:24:36 +00:00
`deciders` : the length of the call's list, for every reader. An empty `deciders` means the ids
are withheld from this reader, never "no deciders"; a non-empty list holds exactly
`decider_count` ids. The card decoder refuses a count outside 1..64 or a non-empty list of
another length.
2026-11-11 18:27:59 +00:00
- **Record:** 6 keys, header `86` : `schemaVersion, fork_id, options_hash, counted_answer_id,
answerer_count, answers`, so ` answerer_count` is the fifth key, right before ` answers`. It is
the number of distinct answerers over ALL the fork's stored answers, refusals included, and is
the same for both readers. In a non-decider's view every answerer is nil, and the count is then
between 1 and the number of answers (0 with no answers).
- **Answer:** `gamecult.desk_answer.v0` keeps its 16 keys (header `DE 00 10` ); `answerer` is a
string or nil, nil only in a non-decider's view, with the key kept. The bytes pin a nil `answerer`
2026-11-11 20:04:04 +00:00
on all four variants, `Counted` (`answer-withheld-answerer` ), `Revision`
(`answer-withheld-answerer-revision` ), `Retraction` (`answer-withheld-answerer-retraction` ) and
2026-11-11 21:24:36 +00:00
`Refused` (the withheld entries), beside each variant's string-`answerer` vector. Stored answers
always carry it, and so does the reply to an answer (`Answered` ), which goes to the answerer.
2026-11-11 18:27:59 +00:00
- **Entry:** header `83` (`schemaVersion, card, record` ). The view is read off `deciders` : a
non-empty `deciders` names every answerer, an empty one names none.
- `options_hash` does not change (still five members).
2026-11-11 21:24:36 +00:00
- **Fixtures:** Huginn's own encoders write entry-bearing fixtures for both views:
`list-open.response` and `read.response` (a decider's; `read.response` has `raised_at` nil),
`list-open-non-decider.response` , `read-non-decider.response` and `record-withheld` , with the
requests `list-non-decider.request` and `read-non-decider.request` . A test searches the
non-decider payloads' bytes for every account id and finds none.
2026-11-11 18:27:59 +00:00
- **Consumers:** Bifrost branch `heimdall/desk-card-repin` (`f977a43` ) vendors Huginn's desk
2026-11-11 21:24:36 +00:00
fixtures from `79d954c` and needs a re-pin to this change. Bifrost's `DeskDocuments.cs` marks
`answerer_count` `JsonRequired` ; the door now sends it.
2026-11-11 17:35:49 +00:00
2026-11-11 17:03:12 +00:00
Response (`huginn.desk_response.v1` ):
| variant | meaning | Bifrost answers |
|---|---|---|
| `{"Forks": {list, as_of}}` | one page, `list` is `gamecult.fork.list.v0` | 200 |
| `{"Fork": {entry, as_of}}` | one fork, `entry` is `gamecult.fork.entry.v0` | 200 |
2026-11-11 17:14:27 +00:00
| `{"NotStored": refusal}` | `gamecult.fork.refusal.v0` : `fork_unknown` , or `fork_too_large` | 404 / 422 |
| `{"Refused": <MindRefusal>}` | a Mind refusal (store fault, wrong instance, a list reply over the cap) | 503 `unavailable` |
The `Refused` value is opaque to Bifrost: any `Refused` is a 503. Its shape depends on the
variant: a variant with fields is a one-key map (`{"Unavailable": {"detail": ...}}` ,
`{"ResponseTooLarge": {"bytes": ..., "limit": ...}}` ), and a unit variant is a bare string
(`"MissingIdentity"` , fixture `refused-unit.response` ).
**`fork_too_large` has two forms, and both are live on `main` .**
- The list form comes from `Mind::desk_forks` when the first entry of a page is alone past the
page budget: `fork_too_large: fork <fork_id> at order <N> is past the page budget by itself;
continue with cursor c<N>`, or ` ...; this is the end of the list` at order 0 (fixture
`list-too-large.response` ).
- The read form comes from the door (`respond` in `desk_door.rs` , `fork_too_large_read` ) when a
read's whole entry is past the 65536-byte reply cap: `fork_too_large: fork <fork_id> is past the
response bound by itself`, with no order and no cursor (fixture ` read-too-large.response`).
CultLib `fork-card.md` limitation 13 still says that an over-cap read reaches Bifrost as
`Refused(ResponseTooLarge)` . That text is stale: Huginn main answers the read form. The refusal
carries no typed order or fork id. A `ForkTooLarge(ForkId[, Order])` in Bifrost must parse them
out of the informational `error` text (CultLib calls the text informational), or use the route's
`fork_id` and the request's cursor instead. The second is the safer choice.
- Any other reply over the cap, which in practice means a list, is `Refused(ResponseTooLarge)` , a
503 (fixture `list-response-too-large.response` ). A list should not reach it, because pages are
budgeted below the cap.
2026-11-11 17:03:12 +00:00
## Failure means 503 for that Mind only
Each of these gives the request 503 `unavailable` with `Retry-After` . Only the Mind addressed is
affected, because each Mind has its own socket and the client asks per Mind:
- the socket is absent, or refuses the connection (`ENOENT` , `ECONNREFUSED` ), or the peer closes it
without a reply frame;
- no whole reply frame arrives within the deadline;
- the reply is a CultNet `Error` message (`cultnet.error.v0` , fixture `error.response` ), an
2026-11-11 17:14:27 +00:00
operation failure (fixture `failure.response` ), or a `Refused` payload (fixtures
`unavailable.response` , `list-response-too-large.response` , `refused-unit.response` ).
2026-11-11 17:03:12 +00:00
An empty list is never served in place of a failure. `open_count: 0` means zero open forks.
2026-11-11 18:27:59 +00:00
## Card fields
2026-11-11 17:03:12 +00:00
2026-11-11 18:27:59 +00:00
`raised_at` is a required card key whose value is an RFC3339 string or nil (CultLib #115 , `af914253` ).
2026-11-11 21:24:36 +00:00
Nil means unknown. A string is the question's first-admission time, which never moves: a UTC `Z` instant at seconds resolution (the form CultLib requires), and nil when the time is unknown, does not parse, or its UTC year is outside 0..9999. It is outside
2026-11-11 18:27:59 +00:00
`options_hash` , which keeps its five members, so the hash vectors do not change. Huginn derives it
from the question's admission: the `committed_at` of the receipt that first admitted the question, or
for an imported question the source mind's `committed_at` (`imported_from.committed_at` ). A value that
does not parse as RFC3339 is served as nil. One known limit: after a campaign has moved twice (A to B
to C), C sees B's admission time, because an import quotes its source's receipt and B's receipt is B's
2026-11-11 17:14:27 +00:00
own (follow-up `desk-raised-at-import-chain` ).
2026-11-11 17:03:12 +00:00
2026-11-14 02:15:20 +00:00
The published schemas (`schemas/cultnet/huginn.desk_response.v1.schema.json` ) type `answerer` and `raised_at` as plain `string` , the existing convention for nullable keys here; a consumer validating against CultLib's own schema must treat nil as allowed for both.
2026-11-11 18:27:59 +00:00
The card's key order and bytes are pinned by the vendored CultLib vectors (above): `card-operator-fork`
2026-11-11 21:24:36 +00:00
(`raised_at` a string), `card-raised-at-nil` and `card-withheld-deciders` , and Huginn's own entry-bearing
fixtures carry it (`list-open.response` a string, `read.response` nil).
2026-11-11 17:03:12 +00:00
2026-11-11 17:38:52 +00:00
## Trust boundary: what Huginn sends, what Bifrost does
2026-11-11 17:03:12 +00:00
2026-11-11 17:38:52 +00:00
- The peer-uid check is the whole authentication, so the socket must belong to Bifrost's uid alone.
2026-11-11 21:24:36 +00:00
- Huginn sends each record with every answer's note (fixture `record-whole` , a decider's view) and
withholds the account ids from a non-decider (above, fixture `record-withheld` ). Notes stay whole
on the wire.
2026-11-11 17:03:12 +00:00
- Bifrost owns three things: the per-request membership check, the `desk.read` token, and
2026-11-11 17:38:52 +00:00
stripping notes for a reader who is not a decider (`DeskNotes` ). It no longer masks answerer
ids.
2026-11-11 17:03:12 +00:00
2026-11-14 02:15:20 +00:00
## Listing: which forks a reader sees (Huginn's)
2026-11-11 17:03:12 +00:00
Huginn owns audience and visibility, at its door. The card has no audience key (CultLib), and
Bifrost's feed applies no fork filter.
- **Default: not listed.** A fork (a showable question) appears in a list or read for a reader who
is not on the call's `deciders` only while a `desk_listing` document for it is in force. Otherwise
the list omits it, it counts in neither `open_count` nor `recorded_count` , and a read of it
answers `fork_unknown` , the same bytes as a fork that does not exist. The counts and the cursor
are computed over the visible set, which is why the gate is Huginn's: a filter applied after
paging would make both wrong.
2026-11-11 17:14:27 +00:00
- **Deciders** see every showable fork whether or not it is listed (ruling
`eureka-substrate:ruling:desk-deciders-see-all` ), because they must see a fork to answer it. The
door compares the call's `subject` with its `deciders` to tell. The wire does not change. An
operator or steward who is not on `deciders` sees only listed forks: reads carry no authority, so
anyone who must see unlisted forks is put on the Mind's decider list in Bifrost's admin.
- **What a non-decider can still infer.** `order` is the fork's rank among all the Mind's
questions, and `stamp` is the Mind's head. So a non-decider sees gaps in `order` (some unlisted or
unshowable questions exist between two listed ones) and sees `stamp` move on any admission. The
gate accepts this leak: no fork's text, id or count leaves the door. Ranking over the visible set
only would make `order` depend on the reader and move whenever a fork is listed, which breaks
CultLib's rule that an order never changes and breaks every held cursor.
2026-11-14 02:15:20 +00:00
- **The listing record** is kind `desk_listing` (`epiphany.pipeline.desk_listing.v2` ), key `<campaign>:desk_listing:<question-label>` ,
2026-11-11 17:15:25 +00:00
fields `campaign` , `listed` (the question's id, in the same campaign) and `reason` (one line: why
2026-11-11 17:14:27 +00:00
members may read it). It is
2026-11-14 02:15:20 +00:00
admitted on the Mind's own Admit door only (the desk door refuses one), so its receipt records who listed it and when. Unlisting is a
2026-11-11 17:03:12 +00:00
`Withdrawn` resolution on it, and relisting withdraws that resolution, which reopens it. Each
flip is a document with its own receipt, so the history is `huginn history <listing id>` . No flag
is stored anywhere else.
2026-11-11 17:14:27 +00:00
- **Who may list or unlist:** the asking Mind herself (ruling
`eureka-substrate:ruling:desk-listing-asking-mind` ). A fork that names a person's matter is listed
only with that person's say.
- **CultLib's text disagrees.** `fork-card.md` (Read and List) says no fork is hidden by
`fork_unknown` and every `desk.read` holder sees every card. That is Libby's to amend for the
listing gate (follow-up `cultlib-fork-card-listing` ).
2026-11-11 17:03:12 +00:00
- **Open for Heimdall:** if Bifrost wants any part of the listing (an operator override at the
desk, a per-Mind default, a reason shown to members), that is his decision to raise. Nothing in
this plan puts listing state in Bifrost.
The fixture `list-empty.response` is also what a reader who is not a decider gets from a Mind
with nothing listed.