From 77ec242019186a2cb2d1eb141f4c9cc6ee973131 Mon Sep 17 00:00:00 2001 From: Sigilante Date: Tue, 4 Aug 2026 12:35:44 -0600 Subject: [PATCH] docs: replace removed Ames %heed/%jilt with the backpressure protocol Kernel reference corrections against urbit@08026c84b2. These are the changes that make an agent or vane author write code that crashes, so they are batched separately from the larger card-coverage work. Ames %heed / %jilt are GONE (ames/tasks.md, ames/README.md). Neither appears in `+$ task:ames` (lull.hoon:844-903). The only trace left in lull is a comment recording that they were "introduced in state %4, and removed in %21", and ames.hoon carries the migration that drops them (`$: %21 :: remove %heed and %jilt`, ames.hoon:2825, with adapters at :1317-1403 and :3314). A vane passing either today crashes Ames. Replaced with the backpressure cards that supersede them: %halt $>(%halt deep) -- halt a flow after a remote %flub %goad [%goad =ship] -- restart halted flows once the peer is live and their Gall counterparts, `[%flub $@(~ [blocked=? dap=(unit term)])]` and `[%spur ~]` (lull.hoon:3623-3624). The flow-state comment at lull.hoon:1732 gives the two directions: forward, Gall passes a %flub to Ames; backward, a $plea gets %flubbed over the wire. Gall's +mo-halt (gall.hoon:310-319) is what emits the remote %flub as a %boon. Note there are two distinct %halts in the source; the message-pump -> packet-pump %halt (lull.hoon:1280) is unrelated and is not documented here. %clog is no longer an Ames gift (ames/README.md). `+$ gift:ames` (lull.hoon:927-946) has no %clog. It is now `[%clog id=*]` in `+$ task:gall` (lull.hoon:3629), which Ames may pass (ames.hoon:165). lull's own gift comment at :911 still lists %clog -- stale upstream, not something this PR can fix. $peer-state and $alien-agenda lost .heeds (ames/data-types.md). Current `+$ peer-state` is lull.hoon:1160 (`peer-state-31`): no .heeds, and a new `halt=(set bone)`, `=chain` and `tip=...`. Current `+$ alien-agenda` is lull.hoon:1132: no .heeds, `keens` regrew as `(jug [path ints] duct)`, and a new `chums`. The 14 `heeds=(set duct)` hits in ames.hoon are all VERSIONED MIGRATION states (peer-state-5 etc.), not the live type. Verified against a running ship rather than source alone: > .^(ship-state:ames %ax /=//=/peers/~zod) ... snd={} rcv={} nax={} closing={} corked={} keens={} chain={} tip={} halt={} no .heeds. The stale `heeds={...}` line in the scry.md sample output was corrected to the real trailing fields. Added a $deep section (ames/data-types.md), since %halt is written `$>(%halt deep)` and $deep was documented nowhere. Dill %meld payload (dill/tasks.md, dill/data-types.md). Changed from `[%meld ~]` to `[%meld $@(~ [memo=? ford=?])]` in dill's $gift, $task AND $flog (lull.hoon:2864, :2882, :2955). A bare `[%meld ~]` still type-checks, so the new options were invisible. Traced the runtime side to document what they select: u3_meld_all (vere melt.c:205-217) frees the persistent memo cache for `memo` (u3R->cax.per_p) and the Ford build cache for `ford` (u3R->cax.for_p), both before the dedup runs. Also fixed a copy-paste error: %pack said "does not return a gift in response to a %meld task". NOT changed: core-academy/ca08.md quotes %heed/%jilt source at length, but Core Academy states it is a snapshot at Zuse 412k; rewriting quoted source there would misrepresent the snapshot. All anchor links in the touched files were checked to resolve. Co-Authored-By: Claude Opus 5 --- content/urbit-os/kernel/ames/README.md | 6 +++- content/urbit-os/kernel/ames/data-types.md | 35 +++++++++++++++++--- content/urbit-os/kernel/ames/scry.md | 7 +++- content/urbit-os/kernel/ames/tasks.md | 37 +++++++++++++++------- content/urbit-os/kernel/dill/data-types.md | 2 +- content/urbit-os/kernel/dill/tasks.md | 16 ++++++++-- 6 files changed, 81 insertions(+), 22 deletions(-) diff --git a/content/urbit-os/kernel/ames/README.md b/content/urbit-os/kernel/ames/README.md index 898fe039..ef598c3d 100644 --- a/content/urbit-os/kernel/ames/README.md +++ b/content/urbit-os/kernel/ames/README.md @@ -55,7 +55,11 @@ Ames encrypts every message using symmetric-key encryption by performing an elli When a peer suffers a continuity breach, Ames removes all messaging state related to it. Ames does not guarantee that all messages will be fully delivered to the now-stale peer. From Ames's perspective, the newly restarted peer is a new ship. Ames's guarantees are not maintained across a breach. -A vane can pass Ames a `%heed` task to request Ames track a peer's responsiveness. If our `%boon`'s to it start backing up locally, Ames will give a `%clog` back to the requesting vane containing the unresponsive peer's urbit address. This interaction does not use ducts as unique keys. Stop tracking a peer by sending Ames a `%jilt` task. +Ames and Gall apply backpressure to each other so that a peer whose agent cannot currently accept a message does not cause unbounded retries. + +When an agent will not take a `$plea`, Gall gives Ames a `%flub` gift; when it is ready again it gives a `%spur`. On the sending side, Ames halts the flow with a [`%halt`](tasks.md#halt) task, and restarts it with a [`%goad`](tasks.md#goad) once the remote agent is live. A halted flow stops re-sending and starts no new timers. + +Ames may also pass Gall a `%clog` task to signal that `%boon`s to a peer are backing up locally. Note that `%clog` is a `$task:gall` — it is no longer an Ames gift, and the older `%heed`/`%jilt` tasks that drove it have been removed. Debug output can be adjusted using `%sift` and `%spew` task's. diff --git a/content/urbit-os/kernel/ames/data-types.md b/content/urbit-os/kernel/ames/data-types.md index 2e7fc488..97a3b96a 100644 --- a/content/urbit-os/kernel/ames/data-types.md +++ b/content/urbit-os/kernel/ames/data-types.md @@ -77,6 +77,27 @@ Application-level message, as a `%pass`. - `.path` - Internal route on the receiving ship. - `.payload` - Semantic message contents. +## `$deep` {#deep} + +```hoon ++$ deep + $% [%nack =ship =nack=bone =message] + [%sink =ship =target=bone naxplanation=[=message-num =error]] + [%drop =ship =nack=bone =message-num] + [%cork =ship =bone] + [%kill =ship =bone] + [%ahoy =ship =bone] + [%prun =ship =user=path =duct =ames=path] + [%halt =ship agent=term =bone] + == +``` + +Deferred internal operations. Ames passes these to itself so that the work +happens in a later event rather than inside the current one. + +The `%deep` task carries a `$deep`, and the [`%halt`](tasks.md#halt) task is the +`%halt` case of it, written `$>(%halt deep)`. + ## `$spar` {#spar} ```hoon @@ -186,8 +207,8 @@ All Ames knows about a peer. +$ alien-agenda $: messages=(list [=duct =plea]) packets=(set =blob) - heeds=(set duct) - keens=(jug path duct) + keens=(jug [path ints] duct) + chums=(jug [path ints] duct) == ``` @@ -195,8 +216,8 @@ What to do when Ames learns a peer's life and keys. - `messages` - [$plea](#plea)s local vanes have asked Ames to send. - `packets` - Packets we've tried to send. -- `heeds` - Local tracking requests; passed through into [$peer-state](#peer-state). - `keens` - Subscribers to remote scry paths. +- `chums` - Subscribers to remote scry paths via `%chum`. ## `$peer-state` {#peer-state} @@ -214,10 +235,12 @@ What to do when Ames learns a peer's life and keys. snd=(map bone message-pump-state) rcv=(map bone message-sink-state) nax=(set [=bone =message-num]) - heeds=(set duct) closing=(set bone) corked=(set bone) keens=(map path keen-state) + =chain + tip=(jug =user=path [duct =ames=path]) + halt=(set bone) == ``` @@ -229,10 +252,12 @@ State for a peer with known life and keys. - `.snd` - Per-`$bone` message pumps to send messages as fragments. - `.rcv` - Per-`$bone` message sinks to assemble messages from fragments. - `.nax` - Unprocessed nacks (negative acknowledgments). -- `.heeds` - Listeners for `%clog` notifications. - `.closing`: Bones closed on the sender side. - `.corked`: Bones closed on both sender and receiver. - `.keens`: Remote scry state. +- `.chain`: Remote scry key chain. +- `.tip`: Outstanding subscription paths. +- `.halt`: Bones whose flows are halted by backpressure. See [`%halt`](tasks.md#halt). ## `$keen-state` {#keen-state} diff --git a/content/urbit-os/kernel/ames/scry.md b/content/urbit-os/kernel/ames/scry.md index 0349da87..7dd5d1c8 100644 --- a/content/urbit-os/kernel/ames/scry.md +++ b/content/urbit-os/kernel/ames/scry.md @@ -78,7 +78,12 @@ A scry with a `%x` `$care` and a `$path` of `/peers/[ship]` where `[ship]` is a } rcv={} nax={} - heeds={~[/gall/sys/lag /dill //term/1]} + closing={} + corked={} + keens={} + chain={} + tip={} + halt={} ] ``` diff --git a/content/urbit-os/kernel/ames/tasks.md b/content/urbit-os/kernel/ames/tasks.md index e8cf1e30..cacc8eb3 100644 --- a/content/urbit-os/kernel/ames/tasks.md +++ b/content/urbit-os/kernel/ames/tasks.md @@ -43,35 +43,48 @@ There are multiple `+on-hear` arms in `ames.hoon`. Here we refer to `+on-hear:ev *** -### `%heed` +### `%halt` ```hoon -[%heed =ship] +$>(%halt deep) ``` -A vane can pass Ames a `%heed` task to request Ames track a peer's responsiveness. If our `%boon`s to it start backing up locally, Ames will `%give` a `%clog` back to the requesting vane containing the unresponsive peer's Urbit address. +where the relevant case of [`$deep`](data-types.md#deep) is: -Stop tracking a peer by sending Ames a [`%jilt`](tasks.md#jilt) task. +```hoon +[%halt =ship agent=term =bone] +``` + +`%halt` stops a flow after we hear a remote `%flub` — that is, after the peer's +Gall has told us the destination agent will not currently accept the `$plea`. A +halted flow stops re-sending; no new timers are started for it. + +Ames also passes a `%halt` task *to Gall* in the other direction, which is how +the remote `%flub` gets emitted: Gall's `+mo-halt` gives a `%boon` carrying +`%flub` back to the `$plea` sender. -The `$ship` field specifies the peer to be tracked. +The flow's `halt` flag is set in either direction: + +- forward: Gall passes a `%flub` to Ames. +- backward: a `$plea` gets `%flub`bed over the wire. #### Returns -If the `$ship` is indeed being unresponsive, as measured by backed up `%boon`s, Ames will `%give` a `%clog` gift to the requesting vane containing the unresponsive peer's urbit address. +This task returns no gifts. *** -### `%jilt` +### `%goad` ```hoon -[%jilt =ship] +[%goad =ship] ``` -`%jilt` stops tracking a potentially unresponsive peer that was previously being tracked as a result of the [`%heed`](tasks.md#heed) task. - -There are two `+on-jilt` arms, this task utilizes `+on-hear:event-core`. +`%goad` restarts flows to `.ship` that were previously halted, once the remote +agent is live again. Halted flows do not start new timers, so a `%goad` is what +gets them moving. -The `$ship` field specifies the peer we want to stop tracking. +The `$ship` field specifies the peer whose flows should be restarted. #### Returns diff --git a/content/urbit-os/kernel/dill/data-types.md b/content/urbit-os/kernel/dill/data-types.md index 49e4c5f0..60287214 100644 --- a/content/urbit-os/kernel/dill/data-types.md +++ b/content/urbit-os/kernel/dill/data-types.md @@ -169,7 +169,7 @@ Wrapped Dill tasks. $% [%crop p=@ud] :: trim kernel state $>(%crud told) :: [%heft ~] :: - [%meld ~] :: unify memory + [%meld $@(~ [memo=? ford=?])] :: unify memory [%pack ~] :: compact memory $>(%text told) :: [%verb ~] :: verbose mode diff --git a/content/urbit-os/kernel/dill/tasks.md b/content/urbit-os/kernel/dill/tasks.md index 057f05b0..e4452a65 100644 --- a/content/urbit-os/kernel/dill/tasks.md +++ b/content/urbit-os/kernel/dill/tasks.md @@ -116,11 +116,23 @@ A `$told` is either a [`%crud`](tasks.md#crud), [`%talk`](tasks.md#talk) or [`%t Deduplicate persistent state. ```hoon -[%meld ~] +[%meld $@(~ [memo=? ford=?])] ``` Dill asks the runtime to perform the memory deduplication. +The payload may be `~`, or a pair of flags selecting caches to discard *before* +the deduplication runs: + +- `memo` - drop the persistent memo cache. +- `ford` - drop the Ford build cache. + +Dropping a cache frees whatever it held, so it can recover more memory than a +bare `%meld`, at the cost of rebuilding that cache afterwards. A bare `[%meld ~]` +still type-checks and leaves both caches intact. + +The same payload appears in Dill's `$gift` and in [`$flog`](data-types.md#flog). + #### Returns Dill does not return a gift in response to a `%meld` task. @@ -139,7 +151,7 @@ Dill asks the runtime to perform the defragmentation. #### Returns -Dill does not return a gift in response to a `%meld` task. +Dill does not return a gift in response to a `%pack` task. ***