From 24ef5c337f6072548ab3d8048711ded3930c7da9 Mon Sep 17 00:00:00 2001 From: Sigilante Date: Tue, 4 Aug 2026 14:55:58 -0600 Subject: [PATCH] docs: complete Ames task coverage and add a Gifts section Against urbit@08026c84b2. Ames was the worst-covered vane by a wide margin: `+$ task:ames` (lull.hoon:844-902) has 37 cards and ames/tasks.md documented 15; `+$ gift:ames` (lull.hoon:926-946) has 15 cards and NONE were documented. Coverage after this PR is 35/37 tasks and 15/15 gifts, verified by script. The two remaining, %halt and %goad, are added by the Ames backpressure PR, which owns that region of the file -- this PR appends and deliberately does not touch the %heed/%jilt sections that PR replaces. Tasks added, grouped by purpose rather than dumped in one list: Flow and peer management %cork delete a message flow, negotiated with the peer %kroc delete specific flows by bone; the bulk form of %cork %tame delete the cached route for a ship %dear manually associate a ship with a lane, from unix %deep deferred calls to ames, from itself %stun STUN response or failure, from unix %prod re-send a packet per flow; all peers if .ships is ~ %cong adjust congestion control parameters; backs |ames/cong %trim release memory Remote scry key reservation %plug reserve a key for the %shut namespace %gulp the same, for |mesa Directed Messaging migration %mate migrate peer(s) to |mesa %rege regress peer(s) back to |ames %load set which core is used for NEW peers; defaults to %ames so that communication with older peers is always possible Mesa protocol tasks %heer %mess %moke %meek %mage %rate %prog %whey, listed as a group and marked internal to Ames and the runtime. These are not sendable from userspace and documenting each individually would imply otherwise. Descriptions are taken from the source's own comment block above the union (lull.hoon:812-841) wherever it provides one, so the wording matches the kernel author's intent rather than my inference. %plug and %gulp have no comment there; both are handled by +sy-plug (ames.hoon:11562), described in source as "key reservation for %shut namespace", which is what the entries say. Gifts section covers all 15 cards, split into messaging, remote scry, system and mesa groups. The union block was checked against lull.hoon by script. Two verification notes: - An intermediate coverage script reported %flub and %live as undocumented Ames tasks. They are not tasks; the regex had matched them inside COMMENT text on lull.hoon:901-902. Re-ran with comments stripped before trusting the result. - An earlier draft linked %deep to [$deep](data-types.md#deep), but that anchor is added by the backpressure PR and does not exist on master. The reference is prose instead, so this PR does not depend on merge order. Co-Authored-By: Claude Opus 5 --- content/urbit-os/kernel/ames/tasks.md | 220 ++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) diff --git a/content/urbit-os/kernel/ames/tasks.md b/content/urbit-os/kernel/ames/tasks.md index e8cf1e30..2b0df0c0 100644 --- a/content/urbit-os/kernel/ames/tasks.md +++ b/content/urbit-os/kernel/ames/tasks.md @@ -309,3 +309,223 @@ A `%wham` task asks Ames to cancel all existing remote scry requests from all va A `%tune` gift with a null `$data` is given to all listeners. See the [`%keen`](tasks.md#keen) entry for more details of the `%tune` gift. *** + +## Flow and peer management + +These tasks manage message flows and per-peer routing state. + +### `%cork` + +```hoon +[%cork =ship] +``` + +Request to delete a message flow. Ames negotiates the teardown with the peer; a flow is closed on the sender side first and only fully removed once both ends agree. The `/corked` and `/closing` scries report flows in each state. + +*** + +### `%kroc` + +```hoon +[%kroc bones=(list [ship bone])] +``` + +Request to delete specific message flows, identified by their [`$bone`](data-types.md#bone)s. This is the bulk, targeted form of [`%cork`](#cork). + +*** + +### `%tame` + +```hoon +[%tame =ship] +``` + +Request to delete the cached route for a ship, so that its lane is rediscovered. + +*** + +### `%dear` + +```hoon +[%dear =ship =lane] +``` + +A lane from Unix — manually associates a ship with a transport address. This is how a route can be supplied directly rather than discovered. + +*** + +### `%deep` + +```hoon +[%deep =deep] +``` + +Deferred calls to Ames, from itself. Ames passes these to defer work into a later event rather than performing it inline. The `$deep` union covers nack handling, flow teardown (`%cork`, `%kill`), the `%ahoy` migration, and flow halting. + +*** + +### `%stun` + +```hoon +[%stun =stun] +``` + +A STUN response, or failure, from Unix. Ames uses STUN to learn whether it is behind a NAT and what its externally visible address is, which feeds route discovery. + +*** + +### `%prod` + +```hoon +[%prod ships=(list ship)] +``` + +Re-send a packet per flow. If `.ships` is `~`, this applies to all peers. Used to shake loose flows that have stalled. + +*** + +### `%cong` + +```hoon +[%cong msg=@ud mem=@ud] +``` + +Adjust congestion control parameters — the number of messages and the amount of memory Ames will allow to be outstanding before it considers a flow clogged. This backs the `|ames/cong` generator. + +*** + +### `%trim` + +```hoon +$>(%trim vane-task) +``` + +Release memory. This is the standard vane task. + +*** + +## Remote scry key reservation + +### `%plug` + +```hoon +[%plug =path] +``` + +Reserve a key for the `%shut` (encrypted remote scry) namespace at the given path, so that data published there can be read only by holders of the key. + +*** + +### `%gulp` + +```hoon +[%gulp path] +``` + +The same as [`%plug`](#plug), but for the `|mesa` network core. Both are handled by the same arm; they differ only in how the key is derived. + +*** + +## Directed Messaging migration + +Ames contains a second network core, `|mesa`, alongside the original `|ames` one. Peers are migrated between them individually, and Ames records which core each peer is on. These tasks drive that migration; in practice they are sent by the `|ahoy/*`, `|mate`, `|rege` and `|ress` generators rather than directly. + +### `%mate` + +```hoon +[%mate (unit ship) dry=?] +``` + +Migrate a peer, or all peers if the unit is null, to `|mesa`. A true `.dry` performs a test run without applying the migration. + +*** + +### `%rege` + +```hoon +[%rege (unit ship) dry=?] +``` + +Regress a peer, or all peers if null, back to `|ames`. The inverse of [`%mate`](#mate). + +*** + +### `%load` + +```hoon +[%load ?(%mesa %ames)] +``` + +Set which network core is used for *new* peers. The default is `%ames`, so that communication with peers on older kernels is always possible. + +*** + +## Mesa protocol tasks + +The following tasks belong to the `|mesa` core's own packet and message protocol. They are internal to Ames and the runtime, and are not intended to be sent from userspace or from other vanes: + +```hoon +[%heer =lane:pact p=@] :: receive a packet +[%mess =mess] :: receive a message +[%moke =space =spar =path] :: initiate %poke request +[%meek =space =spar] :: initiate %peek request +[%mage =space =spar] :: send %page of data +[%rate =spar rate] :: get rate progress for peeks, from unix +[%prog =spar task=... feq=@ud] :: subscribe to progress %rate +[%whey =spar boq=@ud] :: weight of the noun at .path.spar +``` + +*** + +## Gifts + +The complete `$gift:ames` union: + +```hoon ++$ gift + $~ lost/~ + $% [%boon payload=*] + [%noon id=* payload=*] + [%done error=(unit error)] + [%lost ~] + [%send =lane =blob] + [%nail =ship lanes=(list lane)] + [%stub num=@ud key=@] + [%near spar dat=(unit (unit page))] + [%tune spar roar=(unit roar)] + [%turf turfs=(list turf)] + [%saxo sponsors=(list ship)] + [%push p=(list lane:pact) q=@] + [%sage =sage:mess] + $>(%page mess) + $>(%rate task) + == +``` + +Messaging gifts: + +- `%boon` - A response message from a remote ship, given to the vane that is party to the flow. +- `%noon` - A `%boon` carrying a duct, for clog tracking. +- `%done` - Notifies a vane that the peer acked or nacked our message. A non-null `.error` means it was nacked. +- `%lost` - Notifies a vane that we crashed while processing a `%boon`. +- `%send` - A packet, given to Unix to transmit. +- `%nail` - Lanes for a ship, given to Unix. + +Remote scry gifts: + +- `%tune` - A peek result, as a `(unit roar)`. A null value means the data does not and will never exist. +- `%near` - A peek result for a `%chum` request. +- `%stub` - A reserved key for the `%shut` namespace, given in response to [`%plug`](#plug). + +System gifts: + +- `%turf` - A domain report, relayed from Jael. +- `%saxo` - Our sponsor list. + +Mesa gifts, internal to the `|mesa` core: + +- `%push` - Send a request or response packet. +- `%sage` - Give a deserialized payload. +- `%page` - Give a serialized, sealed payload. +- `%rate` - Report rate progress, mirroring the `%rate` task. +