docs: complete Ames task coverage and add a Gifts section - #279
Open
sigilante wants to merge 1 commit into
Open
Conversation
Against urbit/docs.urbit.org@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 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fourteenth PR from the audit against
urbit/urbit@08026c84b2. Ames was the worst-covered vane by a wide margin.+$ task:ames(lull.hoon:844-902)+$ gift:ames(lull.hoon:926-946)Coverage after this PR: 35/37 tasks, 15/15 gifts, verified by script. The two remaining —
%haltand%goad— are added by #269, which owns that region of the file. This PR appends and deliberately does not touch the%heed/%jiltsections #269 replaces.I test-merged the two together: the combined
ames/tasks.mdhas all 37 tasks documented and zero%heed/%jilt.Companion PRs: #266, #267, #269, #270, #271, #272, #273, #274, #275, #276, #277, #278.
Tasks added, grouped by purpose
Flow and peer management —
%cork(delete a flow, negotiated with the peer),%kroc(delete specific flows by bone; the bulk form),%tame(delete a cached route),%dear(manually associate a ship with a lane),%deep(deferred self-calls),%stun(STUN response from Unix),%prod(re-send a packet per flow),%cong(congestion parameters; backs|ames/cong),%trim.Remote scry key reservation —
%plug, and%gulpfor|mesa.Directed Messaging migration —
%mate,%rege,%load.%loadsets which core is used for new peers and defaults to%ames, so 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. Documenting each individually would imply they're sendable from userspace, which they aren't.Descriptions come 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.%plugand%gulphave 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
All 15 cards, split into messaging, remote scry, system and mesa groups. Union block checked against
lull.hoonby script.Two verification notes
%fluband%liveas undocumented Ames tasks. They are not tasks — the regex had matched them inside comment text onlull.hoon:901-902. Re-ran with comments stripped before trusting the result. Worth mentioning because "missing card" findings are exactly what gets acted on.%deepto[$deep](data-types.md#deep), but that anchor is added by docs: replace removed Ames %heed/%jilt with the backpressure protocol #269 and doesn't exist onmaster. The reference is prose instead, so this PR doesn't depend on merge order.All anchors verified to resolve. Test-merged against the thirteen open companion PRs — all clean.
🤖 Generated with Claude Code