Skip to content

Adds a value domain and evaluation options page - #212

Merged
johnnyt merged 1 commit into
mainfrom
pts-v2nr-the-value-domain-and-evaluation
Oct 5, 2026
Merged

johnnyt merged 1 commit into
mainfrom
pts-v2nr-the-value-domain-and-evaluation

Conversation

@johnnyt

@johnnyt johnnyt commented Oct 5, 2026

Copy link
Copy Markdown
Member

Why

The README carried the value domain and the evaluation options as two sections of its long reference tail. A reader looking up a member's TypeScript shape, what the host boundary refuses, or an option's default had to find them inside that tail, and neither section listed every export, every refusal reason or every option type.

What

  • A new reference page, docs/reference/the-value-domain-and-evaluation-options.md, titled "The value domain and evaluation options" (the title the bead names). It describes, in tables: the members and their TypeScript shapes; the member classes and helpers; what each host value normalizes to or is refused with; the refusal reasons and the depth and place limits; the integer rule for lit operands and the cast exemption; the plain projection back to host values; which functions take options; every EvaluateOptions member with its type, default and effect; and TaggedEvaluateOptions.
  • The README's "The value domain" and "Evaluation options" sections are each replaced by one line linking the page; the headings stay, so existing links to those anchors still land.
  • The README's Documentation map: under Look up, one line for the page replaces the two lines that linked the two sections. The Host functions section's mention of the now and random options links the page.
  • Guides that linked the moved sections now link the page: how-to-add-host-functions.md, how-to-compile-and-evaluate-a-rule.md and how-to-run-a-statement-program.md (one link each).

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

Source

Written from the README's two sections and the declarations in src/values.ts, src/evaluator.ts, src/context.ts and src/tagged.ts; the docs audit's next action for this repository names a different subject (the Install section), so no audited span was cut. Every claim the README sections made is on the page except the sentence that a value type the domain lacks is raised upstream rather than added here, which is rationale and stays in ADR-0002.

Checks

  • Full gate (mise exec -- pnpm run gate) green on the branch head; the README is a gated path.
  • README linter: README.md: 1079 lines, every part present.
  • The page's example and its result comments are not executed by the suite (the executed-snippet test reads the README only). They were run against the built package on this branch, with the inline lit example in the integers table and the typeName and normalization rows, and every result matched. The behaviour rows on unbound loads, the clock and host-function failures were also checked against the build.
  • The page carries no "run" as a noun and no fixture-only domain word; the examples are in the library loan.

Provenance

The guide link updates are outside the bead's file map and are forced by the moved sections. The page's paragraphs on unbound loads and on a throwing now describe what the build does, checked by execution: under the default policy a type mismatch over an unbound absence is reported as an unbound-variable error in execute too, and a throwing now read by Date.now() comes back on the failing arm while one read by a relative date propagates.

Closes pts-v2nr.

A reference page under docs/reference: the eleven members of the value
domain and their TypeScript shapes, the member classes and helpers,
what each host value normalizes to or is refused with, the refusal
reasons and their limits, the integer rule for literal operands, the
plain projection back to host values, and every evaluation option with
its type, default and effect, including the tagged request.

The README's two sections on these subjects become one-line links to
the page, its Documentation map links the page under Look up in place
of the two section lines, and the three guides that linked the
sections link the page.

Refs: pts-v2nr
@johnnyt
johnnyt merged commit 1ed938f into main Oct 5, 2026
1 check passed
@johnnyt
johnnyt deleted the pts-v2nr-the-value-domain-and-evaluation branch October 5, 2026 11:53
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