Skip to content

Adds a guide to adding host functions - #210

Merged
johnnyt merged 1 commit into
mainfrom
pts-8f7z-how-to-add-host-functions
Oct 5, 2026
Merged

johnnyt merged 1 commit into
mainfrom
pts-8f7z-how-to-add-host-functions

Conversation

@johnnyt

@johnnyt johnnyt commented Oct 5, 2026

Copy link
Copy Markdown
Member

What this adds

A how-to page, docs/guides/how-to-add-host-functions.md: write a call into a rule's text, supply the function under the functions option of evaluate, and handle a call that fails (the function left out, a function that throws, an answer outside the value domain). Every example is set in the library loan: a renewal rule that asks the application's hold queue whether another patron is waiting for the copy.

The README's Documentation map links the page under Do. The line that pointed Do at the README's Host functions section now points at the page, and that section, which is reference text (how arguments and answers cross into the language's values, how a host name shadows a builtin), gets its own line under Look up. The section itself is unchanged: its example is executed by the README suite, and the page does not replace it.

No file under src/ changes. No changelog fragment: changelog.d/README.md excludes documentation.

Provenance

  • Source material: the docs audit names no span for this subject, so the page is written from the README's Host functions and Evaluation options sections and from call in src/evaluator.ts, each result checked against the built package.
  • The title "How to add host functions" is the one the bead's acceptance dictates, kept as given.
  • Moving the Host functions map line from Do to Look up, and pointing Do at the new page, is an engineering choice decided by the conductor under a standing consent, 2026-10-05: two Do lines for one task would send the reader to two places.

Results on the page

No test executes docs/guides/, so every result line on the page is unexecuted by the suite. Each was re-run by hand against the built package, from the page's own ts fences (type-checked with tsc --strict, then executed), with these answers:

  • compiled.instructions holds ["call", "holds_waiting", 1]
  • holdsWaiting(["atlas-2"]) answers 1
  • renewable is { ok: true, value: true }
  • held is { ok: true, value: false }
  • with functions left out, ok is false and error.reason is "Unknown function: holds_waiting"
  • with a function that throws, error.type is "EvaluationError" and error.reason is the thrown message
  • with a function that answers a symbol, error.reason is "unsupported_host_value"

Checks

  • README linter: README.md: 1169 lines, every part present, no finding.
  • Full gate (mise exec -- pnpm run gate, which gate.also_gated_paths requires for a README change) green on this commit: typecheck, lint, neutrality, the suite with coverage, corpus check, cites, build, identity, resolution, docs.
  • Quadrant self-check: the H1 starts "How to"; the opening states the goal and the starting point; every step is numbered, imperative and shows a result that can come out otherwise; reference detail is linked, not inlined. The goal differs from the README's Basic usage path, and five of the seven steps (writing the function, passing it under functions, and the three failure branches) do not appear there.
  • The page uses "run" as a noun nowhere, and no fixture-only domain word appears in the page or this description.

A how-to page under docs/guides: write a call into a rule, supply the
function under the functions option of evaluate, and handle a call
that fails (a function left out, a function that throws, an answer
outside the value domain), with the result each step shows. The
README's Documentation map links it under Do, and the Host functions
section's line moves to Look up, where its reference text belongs.

Refs: pts-8f7z
@johnnyt
johnnyt merged commit 8b58e12 into main Oct 5, 2026
1 check passed
@johnnyt
johnnyt deleted the pts-8f7z-how-to-add-host-functions branch October 5, 2026 11:35
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