Skip to content

Adds an explanation of why the language is its own - #242

Merged
johnnyt merged 1 commit into
mainfrom
px-wwd7-why-a-predicate-language-of
Oct 5, 2026
Merged

johnnyt merged 1 commit into
mainfrom
px-wwd7-why-a-predicate-language-of

Conversation

@johnnyt

@johnnyt johnnyt commented Oct 5, 2026

Copy link
Copy Markdown
Member

Adds an explanation page, "Why a predicate language of its own", and wires it into hexdocs and the README.

What changes

  • docs/explanation/why-a-predicate-language-of-its-own.md (new): who writes a rule and who executes it, the alternatives turned down (every rule written in code; evaluating the text as Elixir; a tree walker that calls host functions by name; a rule format of the application's own), what a language of its own buys, why it compiles to instructions rather than walking a tree, and what it costs. Examples are set in the library loan (renewals, holds, overdue copies). The page has no numbered steps, no instructions and no code blocks, so nothing on it needs executing to read it.
  • mix.exs: the page is an extra, sits in the existing Explanation group after the architecture page, and is listed in package.files (the README links it relatively).
  • README.md: one line under Understand in the Documentation map.

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

Source material

The page started from the README's "Why a predicate language of its own" paragraph and was written out from the package's own records: the no-eval decision record (ADR-0004) for the threat model and the turned-down implementations, ADR-0001 for the compile-versus-tree-walker trade, ADR-0017 for the rule-format alternative, and the architecture page's design decisions. The docs audit's per-file next actions name no record for this subject.

The README's Why paragraph stays where it is: the README layout requires a Why section (the README check reports no_why without one), so the page deepens the paragraph rather than replacing it. No README text is replaced.

Claims checked against the library at this branch: a missing value returns an UndefinedVariableError; an unregistered function name returns an "Unknown function" error value; a raising host function is rescued into an error value (the evaluator's function dispatch); renewals < 3 AND NOT on_hold with renewals at 3 returns false without reading on_hold.

Checks

  • Full gate (mix quality) green: mix.exs is a build path, so the docs-only exemption did not apply. Doc links: 54 links checked, 0 findings; Docs: no warnings.
  • mix docs --warnings-as-errors clean; the rendered page sits in the Explanation sidebar group and its relative links resolve to the rendered architecture, custom functions, embedding, simple subset and language pages.
  • README check: README.md: 113 lines, every part present.
  • The page carries no result lines, so none is unexecuted.
  • "run" as a noun on the page and in this body: none. Fixture-only domain words on the page and in this body: none.

Provenance

The title is the bead's as given; an explanation title needs no "How to" prefix.

A new explanation page, docs/explanation/why-a-predicate-language-of-
its-own.md, sets out who writes a rule and who executes it, the
alternatives turned down (rules in code, evaluating the text as
Elixir, a tree walker calling host functions by name, a rule format
of the application's own), what the language buys, why it compiles
to instructions, and what it costs. Examples are in the library loan.

The page is an extra in the Explanation group and ships in the
package files; the README's Documentation map links it under
Understand. No library code changes.

Refs: px-wwd7
@codecov

codecov Bot commented Oct 5, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@johnnyt
johnnyt merged commit 0fe08d0 into main Oct 5, 2026
2 checks passed
@johnnyt
johnnyt deleted the px-wwd7-why-a-predicate-language-of branch October 5, 2026 11:44
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