eyeling 1.17.1 → 1.18.0

package/HANDBOOK.md

@@ -1870,28 +1870,162 @@ That’s the whole engine in miniature: unify, compose substitutions, emit head
 
 Eyeling is small, which makes it pleasant to extend — but there are a few invariants worth respecting.
 
-### 16.1 Adding a builtin
+The most important update is architectural: **you no longer need to patch `lib/builtins.js` just to add a project-specific builtin**. The preferred path is now to load a custom builtin module, either programmatically or from the CLI. Core builtins still live in `lib/builtins.js`, but user extensions can stay outside the engine.
 
-Most extensions belong in `lib/builtins.js` (inside `evalBuiltin`):
+### 16.1 The preferred path: custom builtin modules
 
-- Decide if your builtin is:
-  - a test (0/1 solution)
-  - functional (bind output)
-  - generator (many solutions)
-- Return _deltas_ `{ varName: Term }`, not full substitutions.
-- Be cautious with fully-unbound cases: generators can explode the search space.
-- If you add a _new predicate_ (not just a new case inside an existing namespace), make sure it is recognized by `isBuiltinPred(...)`.
+Eyeling now exposes a small custom-builtin registry.
 
-A small architectural note: `lib/builtins.js` is initialized by the engine via `makeBuiltins(deps)`. It receives hooks (unification, proving, deref, scoped-closure helpers, …) instead of importing the engine directly, which keeps the module graph acyclic and makes browser bundling easier.
+At runtime, builtin predicates can be added with:
+
+- `registerBuiltin(iri, handler)`
+- `unregisterBuiltin(iri)`
+- `registerBuiltinModule(moduleExport, origin?)`
+- `loadBuiltinModule(specifier, { resolveFrom? })`
+- `listBuiltinIris()`
+
+That means the extension story is:
+
+- keep the engine’s shipped builtins in `lib/builtins.js`
+- keep your own application or domain builtins in a separate `.js` module
+- load that module with `--builtin` or from JavaScript
+
+This is the safest way to extend Eyeling because it avoids forking the builtin dispatcher and keeps upgrades merge-friendly.
+
+### 16.2 CLI loading: `--builtin`
+
+The CLI accepts a repeatable `--builtin <module.js>` option:
+
+```bash
+eyeling --builtin ./hello-builtin.js rules.n3
+```
+
+You can pass it more than once:
+
+```bash
+eyeling --builtin ./math-extra.js --builtin ./domain-rules.js input.n3
+```
+
+Each module is loaded before reasoning starts. Paths are resolved from the current working directory.
+
+The same capability is available through the npm wrapper:
+
+```js
+const { reason } = require('eyeling');
+const out = reason({ builtinModules: ['./hello-builtin.js'] }, n3Text);
+```
+
+### 16.3 What a builtin module may export
+
+Eyeling accepts three module shapes.
+
+#### A function export
+
+```js
+module.exports = ({ registerBuiltin, internLiteral, unifyTerm, terms }) => {
+  const { Var } = terms;
+
+  registerBuiltin('http://example.org/custom#hello', ({ goal, subst }) => {
+    const lit = internLiteral('"world"');
+    if (goal.o instanceof Var) {
+      return [{ ...subst, [goal.o.name]: lit }];
+    }
+    const s2 = unifyTerm(goal.o, lit, subst);
+    return s2 ? [s2] : [];
+  });
+};
+```
+
+#### An object with `register(api)`
+
+```js
+module.exports = {
+  register(api) {
+    api.registerBuiltin('http://example.org/custom#ping', ({ subst }) => [subst]);
+  },
+};
+```
+
+#### A plain object mapping predicate IRIs to handlers
+
+```js
+module.exports = {
+  'http://example.org/custom#ok': ({ subst }) => [subst],
+};
+```
+
+If none of those shapes match, Eyeling rejects the module with a descriptive error.
+
+### 16.4 The handler contract
+
+Builtin handlers are called with a context object like:
+
+- `iri` — the predicate IRI string
+- `goal` — the current triple goal
+- `subst` — the current substitution
+- `facts`, `backRules`, `depth`, `varGen`, `maxResults`
+- `api` — the same registration/helper API used by modules
+
+A handler returns **an array of substitutions**:
+
+- `[]` means failure / no solutions
+- `[subst2]` means one successful continuation
+- multiple substitutions mean a generator builtin
+
+In practice:
+
+- Decide if your builtin is a test, a functional relation, or a generator.
+- Return substitutions (or substitution deltas merged into the current substitution), not printed output.
+- Be cautious with fully-unbound generators: they can explode the search space.
+- If a builtin needs inputs to be bound first, it is fine to fail early and let forward-rule proving retry later in the conjunction.
+
+Custom builtin failures are wrapped so the predicate IRI appears in the thrown error message, which makes debugging much easier from the CLI.
+
+### 16.5 The helper API exposed to builtin modules
+
+Builtin modules do not need to import internal engine files directly. Eyeling passes a helper API into module registration, including:
+
+- registration helpers: `registerBuiltin`, `unregisterBuiltin`, `listBuiltinIris`
+- term constructors via `terms` (`Literal`, `Iri`, `Var`, `Blank`, `ListTerm`, `GraphTerm`, `Triple`, `Rule`, ...)
+- literal/term helpers such as `internLiteral`, `internIri`, `literalParts`, `termToN3`, `termToJsString`
+- reasoning helpers such as `unifyTerm`, `applySubstTerm`, `applySubstTriple`, `proveGoals`
+- namespace constants via `ns`
+
+That API keeps the extension boundary explicit: custom builtins get the operations they need without reaching into Eyeling’s private module graph.
+
+### 16.6 A shipped example: the Sudoku builtin
+
+The repository now ships a Sudoku builtin module (`lib/builtin-sudoku.js`) and a matching example program (`sudoku.n3`).
+
+So this works out of the box:
+
+```bash
+eyeling sudoku.n3
+```
+
+That example is useful for two reasons:
+
+- it shows a realistic domain-specific builtin implemented outside the core builtin switchboard
+- it demonstrates the intended deployment model for larger custom relations: keep the N3 logic in the `.n3` file, and keep specialized search/verification code in a loadable builtin module
+
+### 16.7 When you should still edit `lib/builtins.js`
+
+Editing `lib/builtins.js` is still reasonable when you are:
+
+- adding or fixing a **core** Eyeling builtin
+- changing builtin behavior that should ship as part of Eyeling itself
+- modifying the builtin helper API that custom modules depend on
+
+But if the builtin is project-specific, experimental, or domain-bound, prefer a custom module first.
+
+A small architectural note: `lib/builtins.js` is still initialized by the engine via `makeBuiltins(deps)`. It receives hooks (unification, proving, deref, scoped-closure helpers, …) instead of importing the engine directly, which keeps the module graph acyclic and makes browser bundling easier.
 
 If your builtin needs a stable view of the scoped closure, follow the scoped-builtin pattern:
 
 - read from `facts.__scopedSnapshot`
 - honor `facts.__scopedClosureLevel` and priority gating
 
-And if your builtin is “forward-only” (needs inputs bound), it’s fine to **fail early** until inputs are available — forward rule proving enables builtin deferral, so the goal can be retried later in the same conjunction.
-
-### 16.2 Adding new term shapes
+### 16.8 Adding new term shapes
 
 If you add a new Term subclass, you’ll likely need to touch:
 
@@ -1900,7 +2034,7 @@ If you add a new Term subclass, you’ll likely need to touch:
 - variable collection for compaction (`gcCollectVarsInTerm`)
 - groundness checks
 
-### 16.3 Parser extensions
+### 16.9 Parser extensions
 
 If you extend parsing, preserve the Rule invariants:
 
@@ -1983,6 +2117,7 @@ Options:
 
 ```
   -a, --ast                    Print parsed AST as JSON and exit.
+      --builtin <module.js>    Load a custom builtin module (repeatable).
   -d, --deterministic-skolem   Make log:skolem stable across reasoning runs.
   -e, --enforce-https          Rewrite http:// IRIs to https:// for log dereferencing builtins.
   -h, --help                   Show this help and exit.
@@ -2037,10 +2172,23 @@ See also:
 
 Eyeling supports a built-in “standard library” across namespaces like `log:`, `math:`, `string:`, `list:`, `time:`, `crypto:`.
 
+It also supports **custom builtin modules**.
+
+- From the CLI: `eyeling --builtin ./my-builtins.js input.n3`
+- From JavaScript: `reason({ builtinModules: ['./my-builtins.js'] }, input)`
+- Programmatically in-process: `registerBuiltin(...)`, `registerBuiltinModule(...)`, `loadBuiltinModule(...)`
+
+A concrete shipped example is the Sudoku builtin and the root-level `sudoku.n3` program:
+
+```bash
+eyeling sudoku.n3
+```
+
 References:
 
 - W3C N3 Built-ins overview: [https://w3c.github.io/N3/reports/20230703/builtins.html](https://w3c.github.io/N3/reports/20230703/builtins.html)
 - Eyeling implementation details: [Chapter 11 — Built-ins as a standard library](#ch11)
+- Extension API and custom module loading: [Chapter 16 — Extending Eyeling (without breaking it)](#ch16)
 - The shipped builtin catalogue: `eyeling-builtins.ttl` (in this repo)
 
 If you are running untrusted inputs, consider `--super-restricted` to disable all builtins except implication.

package/examples/bmi.n3

@@ -0,0 +1,219 @@
+# ============================================================================
+# BMI — ARC-style Body Mass Index example.
+#
+# This example turns a familiar health calculation into a small, inspectable
+# ARC program. It normalizes either metric or US inputs, computes BMI, assigns
+# a WHO adult category, and derives a healthy-range weight band for the given
+# height. The report explains the result and includes independent checks for
+# boundary handling and category behavior.
+#
+# For reproducibility and documentation only; not medical advice.
+# ============================================================================
+
+@prefix : <https://example.org/bmi#> .
+@prefix log: <http://www.w3.org/2000/10/swap/log#> .
+@prefix math: <http://www.w3.org/2000/10/swap/math#> .
+@prefix string: <http://www.w3.org/2000/10/swap/string#> .
+
+# --------------
+# Editable input
+# --------------
+
+:Input
+  :unitSystem "metric";
+  :weight 72.0;
+  :height 178.0.
+
+# US alternative:
+# :Input
+#   :unitSystem "us";
+#   :weight 158.73;
+#   :height 70.08.
+
+# ---------------------------------
+# Normalization and BMI calculation
+# ---------------------------------
+
+{ :Input :unitSystem "metric"; :weight ?W; :height ?H.
+  (?H 100.0) math:quotient ?M. }
+    =>
+{ :Case :weightKg ?W; :heightM ?M.
+  :Reason :units "Inputs were already metric, so kilograms stay kilograms and centimeters are divided by 100 to obtain meters.". } .
+
+{ :Input :unitSystem "us"; :weight ?W; :height ?H.
+  (?W 0.45359237) math:product ?Kg.
+  (?H 0.0254) math:product ?M. }
+    =>
+{ :Case :weightKg ?Kg; :heightM ?M.
+  :Reason :units "US inputs were converted to SI units: pounds to kilograms and inches to meters.". } .
+
+{ :Case :weightKg ?Kg; :heightM ?M.
+  (?M ?M) math:product ?M2.
+  (?Kg ?M2) math:quotient ?Bmi.
+  (?Bmi 100.0) math:product ?BmiX100.
+  ?BmiX100 math:rounded ?BmiRoundedInt.
+  (?BmiRoundedInt 100.0) math:quotient ?BmiRounded.
+  (18.5 ?M2) math:product ?HealthyMin.
+  (24.9 ?M2) math:product ?HealthyMax.
+  (?HealthyMin 10.0) math:product ?MinX10.
+  (?HealthyMax 10.0) math:product ?MaxX10.
+  ?MinX10 math:rounded ?MinRoundedInt.
+  ?MaxX10 math:rounded ?MaxRoundedInt.
+  (?MinRoundedInt 10.0) math:quotient ?HealthyMinRounded.
+  (?MaxRoundedInt 10.0) math:quotient ?HealthyMaxRounded. }
+    =>
+{ :Case :heightSquared ?M2;
+        :bmi ?Bmi;
+        :bmiRounded ?BmiRounded;
+        :healthyMinKg ?HealthyMin;
+        :healthyMaxKg ?HealthyMax;
+        :healthyMinKgRounded ?HealthyMinRounded;
+        :healthyMaxKgRounded ?HealthyMaxRounded. } .
+
+# ------------------------------------------
+# WHO adult categories (half-open intervals)
+# ------------------------------------------
+
+{ :Case :bmi ?Bmi. ?Bmi math:lessThan 18.5. }
+    => { :Decision :category "Underweight". } .
+
+{ :Case :bmi ?Bmi. ?Bmi math:notLessThan 18.5. ?Bmi math:lessThan 25.0. }
+    => { :Decision :category "Normal". } .
+
+{ :Case :bmi ?Bmi. ?Bmi math:notLessThan 25.0. ?Bmi math:lessThan 30.0. }
+    => { :Decision :category "Overweight". } .
+
+{ :Case :bmi ?Bmi. ?Bmi math:notLessThan 30.0. ?Bmi math:lessThan 35.0. }
+    => { :Decision :category "Obesity I". } .
+
+{ :Case :bmi ?Bmi. ?Bmi math:notLessThan 35.0. ?Bmi math:lessThan 40.0. }
+    => { :Decision :category "Obesity II". } .
+
+{ :Case :bmi ?Bmi. ?Bmi math:notLessThan 40.0. }
+    => { :Decision :category "Obesity III". } .
+
+# ---------------------
+# Answer and reason why
+# ---------------------
+
+{ :Case :bmiRounded ?BmiRounded;
+        :healthyMinKgRounded ?HealthyMinRounded;
+        :healthyMaxKgRounded ?HealthyMaxRounded;
+        :heightM ?M.
+  :Decision :category ?Category.
+  (?M 100.0) math:product ?Cm.
+  ?Cm math:rounded ?CmRounded. }
+    =>
+{ :Answer :bmi ?BmiRounded;
+          :category ?Category;
+          :healthyMinKg ?HealthyMinRounded;
+          :healthyMaxKg ?HealthyMaxRounded;
+          :heightCm ?CmRounded. } .
+
+{ :Case :weightKg ?Kg; :heightM ?M; :heightSquared ?M2; :bmiRounded ?BmiRounded.
+  :Reason :units ?Units.
+  :Decision :category ?Category. }
+    =>
+{ :Reason :formula "BMI is defined as weight in kilograms divided by height in meters squared.";
+          :calculation "The normalized weight and height were used to compute BMI, then the result was mapped to the WHO adult category table.";
+          :categoryRule ?Category;
+          :unitsExplanation ?Units. } .
+
+# ------------------
+# Independent checks
+# ------------------
+
+{ :Case :weightKg ?Kg; :heightM ?M. ?Kg math:greaterThan 0. ?M math:greaterThan 0. }
+    => { :Check :c1 "OK - the input was normalized into positive SI values.". } .
+
+{ :Case :heightM ?M; :heightSquared ?M2. (?M ?M) math:product ?M2. }
+    => { :Check :c2 "OK - height squared was reconstructed from the normalized height.". } .
+
+{ :Case :weightKg ?Kg; :heightSquared ?M2; :bmi ?Bmi. (?Kg ?M2) math:quotient ?Bmi. }
+    => { :Check :c3 "OK - the BMI value matches the BMI = kg / m² formula.". } .
+
+{ 18.49 math:lessThan 18.5. }
+    => { :Check :c4 "OK - a BMI of 18.49 stays below the normal-weight threshold.". } .
+
+{ 18.5 math:notLessThan 18.5. 18.5 math:lessThan 25.0. }
+    => { :Check :c5 "OK - the lower boundary is half-open: BMI 18.5 is classified as Normal.". } .
+
+{ 25.0 math:notLessThan 25.0. 25.0 math:lessThan 30.0. }
+    => { :Check :c6 "OK - BMI 25.0 starts the Overweight category.". } .
+
+{ 30.0 math:notLessThan 30.0. 30.0 math:lessThan 35.0. }
+    => { :Check :c7 "OK - BMI 30.0 starts the Obesity I category.". } .
+
+{ 22.0 math:notLessThan 18.5. 22.0 math:lessThan 25.0.
+  27.0 math:notLessThan 25.0. 27.0 math:lessThan 30.0.
+  41.0 math:notLessThan 40.0. }
+    => { :Check :c8 "OK - classification behavior is monotonic across representative BMI values.". } .
+
+{ :Case :heightSquared ?M2; :healthyMinKg ?Min; :healthyMaxKg ?Max.
+  (18.5 ?M2) math:product ?Min.
+  (24.9 ?M2) math:product ?Max. }
+    => { :Check :c9 "OK - the healthy-weight band was reconstructed from BMI 18.5 to 24.9 at the same height.". } .
+
+# -----
+# Fuses
+# -----
+
+{ :Decision :category ?Any.
+  1 log:notIncludes {
+    :Check :c1 ?C1.
+    :Check :c2 ?C2.
+    :Check :c3 ?C3.
+    :Check :c4 ?C4.
+    :Check :c5 ?C5.
+    :Check :c6 ?C6.
+    :Check :c7 ?C7.
+    :Check :c8 ?C8.
+    :Check :c9 ?C9.
+  }. }
+    => false .
+
+{ :Decision :category ?C1, ?C2.
+  ?C1 log:notEqualTo ?C2. }
+    => false .
+
+# ---------------------------------------------
+# ARC report (built from actual derived values)
+# ---------------------------------------------
+
+{ :Answer :bmi ?BmiRounded;
+          :category ?Category;
+          :healthyMinKg ?HealthyMinRounded;
+          :healthyMaxKg ?HealthyMaxRounded;
+          :heightCm ?CmRounded.
+  :Check :c1 ?C1.
+  :Check :c2 ?C2.
+  :Check :c3 ?C3.
+  :Check :c4 ?C4.
+  :Check :c5 ?C5.
+  :Check :c6 ?C6.
+  :Check :c7 ?C7.
+  :Check :c8 ?C8.
+  :Check :c9 ?C9.
+  (
+    "BMI — ARC-style Body Mass Index example\n\n"
+    "Answer\n"
+    "BMI = " ?BmiRounded "\n"
+    "Category = " ?Category "\n"
+    "At height " ?CmRounded " cm, a healthy-weight range is about " ?HealthyMinRounded "–" ?HealthyMaxRounded " kg (BMI 18.5–24.9).\n\n"
+    "Reason Why\n"
+    "BMI is defined as weight in kilograms divided by height in meters squared. "
+    "This program first normalizes the input to SI units, computes BMI, and then applies WHO adult categories as half-open intervals. "
+    "The healthy-weight band is the weight range at the same height that corresponds to BMI 18.5 through 24.9.\n\n"
+    "Check\n"
+    "C1 " ?C1 "\n"
+    "C2 " ?C2 "\n"
+    "C3 " ?C3 "\n"
+    "C4 " ?C4 "\n"
+    "C5 " ?C5 "\n"
+    "C6 " ?C6 "\n"
+    "C7 " ?C7 "\n"
+    "C8 " ?C8 "\n"
+    "C9 " ?C9 "\n"
+  ) string:concatenation ?Block. }
+    =>
+{ :report log:outputString ?Block. } .

package/examples/output/bmi.n3

@@ -0,0 +1,20 @@
+BMI — ARC-style Body Mass Index example
+
+Answer
+BMI = 22.72
+Category = Normal
+At height 178 cm, a healthy-weight range is about 58.6–78.9 kg (BMI 18.5–24.9).
+
+Reason Why
+BMI is defined as weight in kilograms divided by height in meters squared. This program first normalizes the input to SI units, computes BMI, and then applies WHO adult categories as half-open intervals. The healthy-weight band is the weight range at the same height that corresponds to BMI 18.5 through 24.9.
+
+Check
+C1 OK - the input was normalized into positive SI values.
+C2 OK - height squared was reconstructed from the normalized height.
+C3 OK - the BMI value matches the BMI = kg / m² formula.
+C4 OK - a BMI of 18.49 stays below the normal-weight threshold.
+C5 OK - the lower boundary is half-open: BMI 18.5 is classified as Normal.
+C6 OK - BMI 25.0 starts the Overweight category.
+C7 OK - BMI 30.0 starts the Obesity I category.
+C8 OK - classification behavior is monotonic across representative BMI values.
+C9 OK - the healthy-weight band was reconstructed from BMI 18.5 to 24.9 at the same height.

package/examples/output/pn-junction-tunneling.n3

@@ -0,0 +1,23 @@
+=== Answer ===
+In this toy PN-junction tunneling model, heavy doping narrows the depletion region enough for a tunneling window that rises to a peak and then falls, producing a negative-differential region.
+case                          : pn-junction-tunneling
+peak bias                     : 2
+peak current proxy            : 4
+negative differential region  : yes
+
+=== Reason Why ===
+We model tunneling current as an exact overlap count between filled N-side states and empty P-side states while forward bias shifts the bands. Heavy doping is represented by a much narrower depletion region.
+ordinary depletion width (nm) : 8
+tunnel depletion width (nm)   : 1
+filled N-side states          : [1, 2, 3, 4]
+empty P-side states at 0 bias : [3, 4, 5, 6]
+bias -> overlap current proxy : 0->2, 1->3, 2->4, 3->3, 4->2, 5->1, 6->0
+peak point                    : 2 -> 4
+high-bias point               : 6 -> 0
+
+=== Check ===
+heavily doped barrier is narrower : yes
+peak occurs before overlap closes : yes
+negative differential region present : yes
+high-bias overlap closes           : yes
+peak equals full four-state overlap: yes

package/examples/output/resto.n3

@@ -10,11 +10,11 @@ Reason Why
 The plan resolved the person's address, turned it into a map point, checked the local weather, selected a suitable restaurant, and then created a reservation. Because the weather came back mild and stable (22 C and 1016 mbar), the chosen seating stayed outdoors.
 
 Check
-C1 address resolved.
-C2 location found.
-C3 weather loaded.
-C4 outdoor dining justified.
-C5 reservable restaurant selected.
-C6 requested date preserved.
-C7 outdoor preference preserved.
-C8 original goal pattern satisfied.
+C1 OK - the preferences service resolved the person's address.
+C2 OK - the location service turned the address into map coordinates.
+C3 OK - the weather services supplied temperature and pressure for that location.
+C4 OK - the weather interpretation justified outdoor seating.
+C5 OK - the recommendation step selected a restaurant that can accept reservations.
+C6 OK - the reservation preserved the requested dinner date.
+C7 OK - the reservation preserved the outdoor seating preference.
+C8 OK - the final goal pattern from the original RESTdesc query is satisfied.

package/examples/output/sudoku.n3

@@ -0,0 +1,42 @@
+=== Answer ===
+The puzzle is solved, and the completed grid is the unique valid Sudoku solution.
+case              : sudoku
+default puzzle    : classic
+
+Puzzle
+1 . . | . . 7 | . 9 . 
+. 3 . | . 2 . | . . 8 
+. . 9 | 6 . . | 5 . . 
+
+. . 5 | 3 . . | 9 . . 
+. 1 . | . 8 . | . . 2 
+6 . . | . . 4 | . . . 
+
+3 . . | . . . | . 1 . 
+. 4 . | . . . | . . 7 
+. . 7 | . . . | 3 . . 
+
+Completed grid
+1 6 2 | 8 5 7 | 4 9 3 
+5 3 4 | 1 2 9 | 6 7 8 
+7 8 9 | 6 4 3 | 5 2 1 
+
+4 7 5 | 3 1 2 | 9 8 6 
+9 1 3 | 5 8 6 | 7 4 2 
+6 2 8 | 7 9 4 | 1 3 5 
+
+3 5 6 | 4 7 8 | 2 1 9 
+2 4 1 | 9 3 5 | 8 6 7 
+8 9 7 | 2 6 1 | 3 5 4 
+=== Reason Why ===
+The solver starts from 23 clues and fills the remaining 58 cells by combining constraint propagation with depth-first search. At each step it chooses the empty cell with the fewest legal digits, places forced singles immediately, and only guesses when more than one candidate remains. Across the search it made 213 forced placements and tried 22 guesses, visited 23 search nodes overall, and backtracked 12 times before reaching the completed grid. The solver also confirmed that the solution is unique. Early steps: r2c3=4: guess, r5c3=3: forced, r2c1=5: guess, r2c4=1: guess, r2c6=9: forced, r2c7=6: guess, r2c8=7: forced, r1c7=4: guess, … and 50 more placements
+
+=== Check ===
+C1 OK - every given clue is preserved in the final grid.
+C2 OK - the final grid contains only digits 1 through 9, with no blanks left.
+C3 OK - each row contains every digit exactly once.
+C4 OK - each column contains every digit exactly once.
+C5 OK - each 3×3 box contains every digit exactly once.
+C6 OK - replaying the recorded placements from the original puzzle remains legal at every step.
+C7 OK - the search statistics and the successful proof path are internally consistent.
+C8 OK - a second search found no alternative solution, so the solution is unique.

package/examples/output/transistor-switch.n3

@@ -0,0 +1,24 @@
+=== Answer ===
+In this toy transistor-switch model, a low input leaves the transistor in cutoff (OFF) and a high input drives it into saturation (ON), so the load behaves like an on/off branch rather than a linear amplifier.
+case                             : transistor-switch
+low input state                  : cutoff / OFF
+high input state                 : saturation / ON
+on-state load current            : 4.80 mA
+
+=== Reason Why ===
+We model an NPN low-side switch with exact millivolt and microamp arithmetic. The base current comes from (Vin - Vbe,on)/Rb when the base-emitter junction is forward biased, and the collector current is the smaller of beta * Ib and the load-limited current (Vcc - Vce,sat)/Rl.
+supply voltage                   : 5.00 V
+base resistor                    : 10000 ohms
+load resistor                    : 1000 ohms
+transistor beta proxy            : 100
+low input                        : Vin=0.00 V -> Ib=0.00 mA, Ic=0.00 mA, Vce=5.00 V, state=cutoff / OFF
+high input                       : Vin=5.00 V -> Ib=0.43 mA, Ic=4.80 mA, Vce=0.20 V, state=saturation / ON
+high-input gain limit            : 43.00 mA
+high-input load limit            : 4.80 mA
+
+=== Check ===
+low input stays in cutoff        : yes
+high input reaches saturation    : yes
+switching states differ          : yes
+on-state current is load-limited : yes
+load voltage matches resistor drop : yes