From da0d20ae788a39f54c9ba3e9f7490b11e92e3062 Mon Sep 17 00:00:00 2001 From: Sigilante Date: Tue, 4 Aug 2026 14:46:53 -0600 Subject: [PATCH] docs: add missing vane Gifts sections and undocumented tasks Against urbit@08026c84b2. Four vanes documented their tasks but never their gifts; the cards existed only as passing mentions under whichever task produced them, if at all. Coverage verified by script against lull.hoon. Gifts sections added: behn 4 cards %doze %wake %meta %heck lull.hoon:2404 dill 8 cards %blit %logo %meld %pack %trim %logs %meme %quac :2861 eyre 6 cards %boon/%done %set-config %sessions %response %bound %grow :2978 iris 3 cards %request %cancel-request %http-response :4131 Two naming collisions are called out explicitly, since both would be easy to misread: - Iris has %request and %cancel-request as BOTH a task and a gift. The task is how a vane asks Iris to fetch something; the gift is how Iris asks Unix to do it. - Dill has %meld, %pack, %trim and %quac in both unions, in opposite directions. Tasks added: dill %mass run a memory report; the mechanism behind |mass dill %quac the runtime's reply carrying that report dill %knob documented AS DEPRECATED -- it is marked `:: deprecated removeme` in lull.hoon, so the entry exists to stop anyone adopting it, not to encourage use eyre %eauth-host set the EAuth base URL; eyre appends /~/eauth internally. Cross-referenced to the existing EAuth guide, which already described this task while tasks.md did not list it eyre %spew set verbosity toggle khan %done external control socket closed Checked and NOT changed: khan already had a complete Gifts section (%arow, %avow), and eyre's %reject-origin and %set-response -- which I could not find in a first partial extraction -- do exist at lull.hoon:3063 and :3069. Neither file has a phantom card. All anchors verified to resolve. Co-Authored-By: Claude Opus 5 --- content/urbit-os/kernel/behn/tasks.md | 23 ++++++++ content/urbit-os/kernel/dill/tasks.md | 77 +++++++++++++++++++++++++++ content/urbit-os/kernel/eyre/tasks.md | 49 +++++++++++++++++ content/urbit-os/kernel/iris/tasks.md | 24 +++++++++ content/urbit-os/kernel/khan/tasks.md | 10 ++++ 5 files changed, 183 insertions(+) diff --git a/content/urbit-os/kernel/behn/tasks.md b/content/urbit-os/kernel/behn/tasks.md index 2b6cefad..eeef3a89 100644 --- a/content/urbit-os/kernel/behn/tasks.md +++ b/content/urbit-os/kernel/behn/tasks.md @@ -164,3 +164,26 @@ You would not use this task from userspace. #### Returns In response to receiving this task, Behn may `%give` a `%doze` gift containing the `@da` of the next timer to elapse. Behn may also `%give` a `%wake` gift to itself. + +--- + +## Gifts {#gifts} + +The complete `$gift:behn` union: + +```hoon ++$ gift + $% [%doze p=(unit @da)] + [%wake error=(unit tang)] + [%meta p=vase] + [%heck syn=sign-arvo] + == +``` + +- `%doze` - The next alarm. Behn gives this to Unix, which does the real + timekeeping. A null `.p` means there is no timer set, so Unix can stop waiting. +- `%wake` - A timer has elapsed, given to whoever set it with [`%wait`](#wait). + A non-null `.error` means the timer fired but the resulting event crashed. +- `%meta` - Gives back the vase from a [`%drip`](#drip), in the following event. +- `%heck` - Gives back the `$sign-arvo` from a [`%huck`](#huck). + diff --git a/content/urbit-os/kernel/dill/tasks.md b/content/urbit-os/kernel/dill/tasks.md index 057f05b0..7b1778a2 100644 --- a/content/urbit-os/kernel/dill/tasks.md +++ b/content/urbit-os/kernel/dill/tasks.md @@ -388,3 +388,80 @@ The `$tape` in `.p` will be printed to the terminal. Dill does not return a gift in response to a `%text` task. *** + +*** + +### `%mass` + +Run a memory report. + +```hoon +[%mass ~] +``` + +Asks the runtime to produce a memory report. This is the mechanism behind `|mass` in the dojo. The runtime replies with a [`%quac`](#quac) task carrying the result. + +#### Returns + +Dill does not return a gift in response to a `%mass` task. + +*** + +### `%quac` + +Memory report from the runtime. + +```hoon +[%quac p=(list quac)] +``` + +Carries the memory report produced in response to [`%mass`](#mass). This comes from the runtime; you would not send it from userspace. + +#### Returns + +Dill gives a `%meme` gift carrying the report. + +*** + +### `%knob` + +Set error volume for a tag. + +```hoon +[%knob tag=term level=?(%hush %soft %loud)] +``` + +**Deprecated.** This task is marked `:: deprecated removeme` in `lull.hoon` and should not be adopted in new code. + +#### Returns + +Dill does not return a gift in response to a `%knob` task. + +*** + +## Gifts + +The complete `$gift:dill` union: + +```hoon ++$ gift + $% [%blit p=(list blit)] + [%logo ~] + [%meld $@(~ [memo=? ford=?])] + [%pack ~] + [%trim p=@ud] + [%logs =told] + [%meme p=(list quac)] + [%quac ~] + == +``` + +- `%blit` - Terminal output, given to Unix as a list of [`$blit`](data-types.md#blit)s. +- `%logo` - Tells the runtime to shut the ship down. +- `%meld` - Asks the runtime to deduplicate memory. Same payload as the [`%meld`](#meld) task. +- `%pack` - Asks the runtime to defragment memory. +- `%trim` - Asks the runtime to free memory. +- `%logs` - System output, given to subscribers of the [`%logs`](#logs) task. +- `%meme` - A memory report, given in response to a [`%quac`](#quac) task. +- `%quac` - Asks the runtime for a memory report; the counterpart of the [`%mass`](#mass) task. + diff --git a/content/urbit-os/kernel/eyre/tasks.md b/content/urbit-os/kernel/eyre/tasks.md index 970637dd..3d8b23d0 100644 --- a/content/urbit-os/kernel/eyre/tasks.md +++ b/content/urbit-os/kernel/eyre/tasks.md @@ -268,3 +268,52 @@ Eyre gives a `%grow` gift in response to a `%set-response` task. A `%grow` gift The `$path` will be of the format `/cache/[revision]/[url]`, for example `/cache/12/~~~2f.foo~2f.bar`. The revision number is incremented each time the entry is updated, including if it's removed, and is in `@ud` format. The url element uses `%t` [`+scot`](../../../hoon/stdlib/4m.md#scot) encoding, so will need to be decoded with `%t` [`+slav`](../../../hoon/stdlib/4m.md#slav). *** + +## `%eauth-host` + +Set the EAuth base URL. + +```hoon +[%eauth-host host=(unit @t)] +``` + +Explicitly sets the base URL used for EAuth, for example `'https://sampel.com'`. Eyre appends `/~/eauth` to it internally when redirecting into the EAuth flow. A null `.host` clears it, so the endpoint is determined implicitly again. + +See the [EAuth guide](eauth.md) for how the endpoint is otherwise derived. + +*** + +## `%spew` + +Set verbosity. + +```hoon +[%spew veb=@] +``` + +Sets Eyre's debug verbosity toggle. + +*** + +## Gifts + +The complete `$gift:eyre` union: + +```hoon ++$ gift + $% $>(?(%boon %done) gift:ames) + [%set-config =http-config] + [%sessions ses=(set @t)] + [%response =http-event:http] + [%bound accepted=? =binding] + [%grow =path] + == +``` + +- `%boon` / `%done` - Ames responses, reused from [`$gift:ames`](../ames/data-types.md). These carry results for requests that arrived over the network. +- `%set-config` - Configures the external HTTP server, given to Unix. +- `%sessions` - The set of valid authentication cookie strings. +- `%response` - A response to an event from Unix, as an [`$http-event:http`](data-types.md#http-eventhttp). +- `%bound` - The result of a [`%connect`](#connect) or [`%serve`](#serve). `.accepted` is false if the binding was rejected, which happens when it duplicates an existing one. +- `%grow` - Notifies that a cache entry has changed. See [`%set-response`](#set-response) for the path format. + diff --git a/content/urbit-os/kernel/iris/tasks.md b/content/urbit-os/kernel/iris/tasks.md index 732d7be9..0611e425 100644 --- a/content/urbit-os/kernel/iris/tasks.md +++ b/content/urbit-os/kernel/iris/tasks.md @@ -70,3 +70,27 @@ Iris does not return any gift in response to a `%cancel-request` task. You will Receives HTTP data from outside. This task is sent to Iris by the runtime, you would not use it manually. The `.id` is a sequential ID for the event and the [$http-event:http](../eyre/data-types.md#http-eventhttp) contains the HTTP headers and data. + +--- + +## Gifts {#gifts} + +The complete `$gift:iris` union: + +```hoon ++$ gift + $% [%request id=@ud request=request:http] + [%cancel-request id=@ud] + [%http-response =client-response] + == +``` + +- `%request` - An outbound HTTP request, given to Unix to perform. Note this + shares a name with the [`%request`](#request) *task*: the task is how a vane + asks Iris to fetch something, and the gift is how Iris asks Unix to do it. +- `%cancel-request` - Tells Unix to cancel a previously given `%request`. The + same naming applies as above. +- `%http-response` - The result, given back to whoever sent the + [`%request`](#request) task, as a + [`$client-response`](data-types.md#client-response). + diff --git a/content/urbit-os/kernel/khan/tasks.md b/content/urbit-os/kernel/khan/tasks.md index df59aa8b..1318a9d9 100644 --- a/content/urbit-os/kernel/khan/tasks.md +++ b/content/urbit-os/kernel/khan/tasks.md @@ -65,6 +65,16 @@ When the thread eventually finishes (or if it fails), Khan with give an [`%arow` --- +### `%done` {#done} + +Socket closed. + +```hoon +[%done ~] +``` + +Tells Khan that the external control socket has closed. This comes from the runtime; you would not send it from userspace. + ## Gifts {#gifts} These are the two gifts Khan can give. In userspace, you'd only receive an [`%arow`](#arow).