Huginn/docs/desk-feed-door.md

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 binds a desk socket yet (follow-up eureka-substrate:follow_up:desk-door-ops-root-run). Two parts are planned and not built: the card's raised_at, decider_count and the record's answerer_count and nullable answerer (the shapes pinned below), and the listing gate that decides which forks a reader sees. They are cut specs cut-desk-feed-raised-at and cut-desk-feed-listing in the eureka-substrate campaign.

Not live: the listing gate. On main today every showable question is returned to every reader, whatever the call's deciders say (pinned by the_whole_record_comes_back_whoever_the_deciders_list_leaves_out in desk_wire/reads.rs). The default of not listed, described under Listing below, holds only once cut-desk-feed-listing lands. Until then, neither Bifrost's receiver nor the ops root-run (desk-door-ops-root-run) may go live on a Mind that holds private questions.

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 that reads them reads the door. The reader-count shapes are CultLib's bytes, vendored in cultlib-d3025d3c/ (below). The document shapes inside the payload (gamecult.fork.list.v0, 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(...)).

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.

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.
• 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.
• 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.

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 handle is never one of them. Bifrost enforces the grammar; Huginn's door does not yet: it reads these fields as Short (any text up to 200 bytes) and would accept @x:server or an email. A subject is stored as answerer on an answer, so a wrong value would enter the mind. Refusing every other shape at decode is owed by cut-desk-feed-listing.r6. The test every_account_id_in_the_fixtures_is_a_lowercase_d_format_uuid pins the grammar. The fixtures use synthetic UUIDs.

Account ids by reader (shape pinned in CultLib; Huginn side planned)

A reader is a decider when the call's subject is in the call's deciders, compared byte for byte; both values are in the account-id format above. Any other reader is a non-decider.

• On main today, every reader gets the ids. card.deciders carries the call's decider list on every card, and every answer carries its answerer id. This is not live yet: no receiver is deployed.
• 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 it, because the card is opaque to it. A decider sees the ids. The superseding ruling is in force: eureka-substrate:ruling:desk-read-visibility-withheld-ids.
• 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; 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 crates/huginn-mind/tests/fixtures/desk-feed/cultlib-d3025d3c/ (its README lists each file and its vector name). Read off those bytes:
  • 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 deciders. An empty deciders means the ids are withheld from this reader, never "no deciders"; a non-empty list holds exactly decider_count ids.
  • 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 on all four variants, Counted (answer-withheld-answerer), Revision (answer-withheld-answerer-revision), Retraction (answer-withheld-answerer-retraction) and Refused (the withheld entries), beside each variant's string-answerer vector; ruling eureka-substrate:ruling:desk-reader-counts-shape is the reason, no longer the only evidence. Stored answers always carry it.
  • 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).
  • Consumers: Bifrost branch heimdall/desk-card-repin (f977a43) vendors Huginn's desk fixtures from 79d954c and needs a re-pin after this PR. Bifrost's DeskDocuments.cs marks answerer_count JsonRequired, so its merge must wait for cut-desk-feed-listing: today's door does not send the field.
  • Huginn's real types do not carry these shapes yet: ForkCard has no raised_at or decider_count, ForkRecord no answerer_count, ForkDeskAnswer.answerer is a non-null string, and each type refuses unknown keys. The test huginn_types_do_not_yet_carry_the_pinned_shapes pins that gap, and cut-desk-feed-listing closes it by decoding these same bytes into the real types.

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
{"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.

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 operation failure (fixture failure.response), or a Refused payload (fixtures unavailable.response, list-response-too-large.response, refused-unit.response).

An empty list is never served in place of a failure. open_count: 0 means zero open forks.

Card fields

raised_at is a required card key whose value is an RFC3339 string or nil (CultLib #115, af914253). Nil means unknown. A string is the question's first-admission time, which never moves. It is outside 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 own (follow-up desk-raised-at-import-chain).

The card's key order and bytes are pinned by the vendored CultLib vectors (above): card-operator-fork (raised_at a string), card-raised-at-nil and card-withheld-deciders. The fixtures Huginn's own encoders write carry no entry; entry-bearing list and read fixtures from Huginn's output are added by cut-desk-feed-raised-at and cut-desk-feed-listing.

Trust boundary: what Huginn sends, what Bifrost does

• The peer-uid check is the whole authentication, so the socket must belong to Bifrost's uid alone.
• Today Huginn sends every record whole: every answerer id, every note and the card's deciders (fixture record-whole).
• Once cut-desk-feed-listing and the CultLib change land, Huginn withholds the account ids from a non-decider (above). Notes stay whole on the wire.
• Bifrost owns three things: the per-request membership check, the desk.read token, and stripping notes for a reader who is not a decider (DeskNotes). It no longer masks answerer ids.

Listing: which forks a reader sees (Huginn's; NOT live, see the status above)

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.
• 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.
• The listing record is planned kind desk_listing, key <campaign>:desk_listing:<question-label>, fields campaign, listed (the question's id, in the same campaign) and reason (one line: why members may read it). It is admitted on the Mind's own door, so its receipt records who listed it and when. Unlisting is a 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.
• 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).
• 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.