Skip to content

docs: surface pst!/get! HTTP auto-unwrap forms (#5bm)#526

Merged
danieljohnmorris merged 3 commits into
mainfrom
fix/pst-bang-disco
May 21, 2026
Merged

docs: surface pst!/get! HTTP auto-unwrap forms (#5bm)#526
danieljohnmorris merged 3 commits into
mainfrom
fix/pst-bang-disco

Conversation

@danieljohnmorris
Copy link
Copy Markdown
Collaborator

@danieljohnmorris danieljohnmorris commented May 21, 2026

Summary

The ! auto-unwrap suffix has worked on get / pst / get-to / pst-to since the bang family was generalised, but skills/ilo/ilo-builtins-io.md only called it out under JSON. Several recent persona runs (basic-auth, webhook-sender) reached for the manual ?r{~v:v;^e:^e} shape on every HTTP call site, paying ~30 tokens per call that the bang form would have saved. Pure doc gap, not a runtime gap.

Fix: add a paragraph in the HTTP section showing all three forms (get, get!, get!!) with a one-line caveat on when to reach for which, plus a tiny runnable example so the engines harness pins the contract.

Manifesto framing: token-minimal language only works if the token-minimal idiom is the obvious one. Hiding pst! under the JSON heading made the longer shape feel default.

Repro before / after

Before, basic-auth persona wrote:

r=pst url body
?r{~v:v;^e:^e}

After, same shape collapses to:

v=pst! url body

inside any function that already returns R.

What's in the diff

  • add http-bang example pinning get!/pst! propagation: examples/http-bang.ilo exercises get! / pst! / get-to! / pst-to! via the engines harness. Uses connection-refused on loopback for a stable Err, then matches on the Result tag so the assertion is OS-portable.
  • surface HTTP bang forms in skills io doc: adds the three-form table + one-line caveat to the HTTP section of skills/ilo/ilo-builtins-io.md. Mirrors the wording style of the existing ! paragraph under JSON.

Test plan

  • cargo test --release --features cranelift, full suite green
  • cargo test --release --test examples_engines, http-bang.ilo passes
  • cargo fmt --check
  • cargo clippy --release --features cranelift -- -D warnings
  • Manual: ilo examples/http-bang.ilo --vm probe-{get,pst,get-to,pst-to} all emit err propagated

Follow-ups

None. SPEC.md already documents get!; ai.txt lists the builtin signatures and inherits the ! rule from the language spec. This PR only closes the skills-doc gap.

@codecov
Copy link
Copy Markdown

codecov Bot commented May 21, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

@danieljohnmorris danieljohnmorris merged commit faa4668 into main May 21, 2026
5 checks passed
@danieljohnmorris danieljohnmorris deleted the fix/pst-bang-disco branch May 21, 2026 10:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant