eyelang 1.1.16 → 1.1.18

package/docs/guide.md

@@ -197,7 +197,7 @@ The default output is then:
 answer(case1, accepted).
 ```
 
-`materialize/2` is a declaration, not a logical rule to prove. It affects which predicates the CLI prints, not the meaning of the rules themselves.
+`materialize/2` is a declaration, not a logical rule to prove. It affects which predicates the CLI prints, not the meaning of the rules themselves. Materialized output facts are not inserted back into the running program for later goals; if later output predicates reuse the same derived helper relation, eyelang proves it again unless that helper is declared with `memoize/2`. Source facts are indexed and reused normally, and memoized solved goals are reused inside the same solver run.
 
 ## Writing programs
 
@@ -321,6 +321,7 @@ Each example has a checked golden output in `examples/output`.
 | [`bayes-diagnosis.pl`](../examples/bayes-diagnosis.pl) | Computes scaled Bayesian diagnosis posteriors. | [`output/bayes-diagnosis.pl`](../examples/output/bayes-diagnosis.pl) |
 | [`bayes-therapy.pl`](../examples/bayes-therapy.pl) | Ranks therapies using Bayesian disease likelihoods. | [`output/bayes-therapy.pl`](../examples/output/bayes-therapy.pl) |
 | [`beam-deflection.pl`](../examples/beam-deflection.pl) | Computes cantilever beam deflection. | [`output/beam-deflection.pl`](../examples/output/beam-deflection.pl) |
+| [`binomial-vandermonde.pl`](../examples/binomial-vandermonde.pl) | Computes binomial coefficients and checks Vandermonde's identity. | [`output/binomial-vandermonde.pl`](../examples/output/binomial-vandermonde.pl) |
 | [`blocks-world-planning.pl`](../examples/blocks-world-planning.pl) | Searches a finite blocks-world plan. | [`output/blocks-world-planning.pl`](../examples/output/blocks-world-planning.pl) |
 | [`bmi.pl`](../examples/bmi.pl) | Normalizes BMI inputs and classifies weight. | [`output/bmi.pl`](../examples/output/bmi.pl) |
 | [`braking-safety-worlds.pl`](../examples/braking-safety-worlds.pl) | Classifies braking safety under alternative worlds. | [`output/braking-safety-worlds.pl`](../examples/output/braking-safety-worlds.pl) |
@@ -328,6 +329,7 @@ Each example has a checked golden output in `examples/output`.
 | [`cache-performance.pl`](../examples/cache-performance.pl) | Summarizes cache latency performance. | [`output/cache-performance.pl`](../examples/output/cache-performance.pl) |
 | [`canary-release.pl`](../examples/canary-release.pl) | Decides canary rollout or rollback. | [`output/canary-release.pl`](../examples/output/canary-release.pl) |
 | [`cat-koko.pl`](../examples/cat-koko.pl) | Demonstrates named existential witnesses from a Cat Koko rule pattern. | [`output/cat-koko.pl`](../examples/output/cat-koko.pl) |
+| [`catalan-convolution.pl`](../examples/catalan-convolution.pl) | Computes Catalan numbers by memoized convolution. | [`output/catalan-convolution.pl`](../examples/output/catalan-convolution.pl) |
 | [`chart-parser.pl`](../examples/chart-parser.pl) | Parses small sentences with a memoized chart parser. | [`output/chart-parser.pl`](../examples/output/chart-parser.pl) |
 | [`clinical-trial-screening.pl`](../examples/clinical-trial-screening.pl) | Screens candidates for a trial. | [`output/clinical-trial-screening.pl`](../examples/output/clinical-trial-screening.pl) |
 | [`collatz-1000.pl`](../examples/collatz-1000.pl) | Materializes Collatz trajectories for starts 1000 down to 1. | [`output/collatz-1000.pl`](../examples/output/collatz-1000.pl) |
@@ -337,6 +339,7 @@ Each example has a checked golden output in `examples/output`.
 | [`composition-of-injective-functions-is-injective.pl`](../examples/composition-of-injective-functions-is-injective.pl) | Encodes composition and injectivity of finite functions. | [`output/composition-of-injective-functions-is-injective.pl`](../examples/output/composition-of-injective-functions-is-injective.pl) |
 | [`context-association.pl`](../examples/context-association.pl) | Associates named contexts with their contents. | [`output/context-association.pl`](../examples/output/context-association.pl) |
 | [`context-schema-audit.pl`](../examples/context-schema-audit.pl) | Audits mixed-arity context members with `holds/3`. | [`output/context-schema-audit.pl`](../examples/output/context-schema-audit.pl) |
+| [`continued-fraction-sqrt2.pl`](../examples/continued-fraction-sqrt2.pl) | Computes sqrt(2) continued-fraction convergents and Pell errors. | [`output/continued-fraction-sqrt2.pl`](../examples/output/continued-fraction-sqrt2.pl) |
 | [`control-system.pl`](../examples/control-system.pl) | Evaluates control-system measurements and targets. | [`output/control-system.pl`](../examples/output/control-system.pl) |
 | [`critical-path-schedule.pl`](../examples/critical-path-schedule.pl) | Computes earliest starts and the critical path for a project network. | [`output/critical-path-schedule.pl`](../examples/output/critical-path-schedule.pl) |
 | [`cyclic-path.pl`](../examples/cyclic-path.pl) | Computes paths in a cyclic graph. | [`output/cyclic-path.pl`](../examples/output/cyclic-path.pl) |
@@ -393,16 +396,22 @@ Each example has a checked golden output in `examples/output`.
 | [`heron-theorem.pl`](../examples/heron-theorem.pl) | Computes triangle area by Heron's theorem. | [`output/heron-theorem.pl`](../examples/output/heron-theorem.pl) |
 | [`ideal-gas-law.pl`](../examples/ideal-gas-law.pl) | Applies the ideal gas law. | [`output/ideal-gas-law.pl`](../examples/output/ideal-gas-law.pl) |
 | [`illegitimate-reasoning.pl`](../examples/illegitimate-reasoning.pl) | Detects suspect reasoning patterns. | [`output/illegitimate-reasoning.pl`](../examples/output/illegitimate-reasoning.pl) |
+| [`integer-partitions.pl`](../examples/integer-partitions.pl) | Counts integer partitions with memoized dynamic programming. | [`output/integer-partitions.pl`](../examples/output/integer-partitions.pl) |
+| [`intuitionistic-logic-kripke.pl`](../examples/intuitionistic-logic-kripke.pl) | Emulates intuitionistic Kripke forcing and constructive implication. | [`output/intuitionistic-logic-kripke.pl`](../examples/output/intuitionistic-logic-kripke.pl) |
 | [`job-shop-scheduling.pl`](../examples/job-shop-scheduling.pl) | Searches a small job-shop schedule and minimizes makespan. | [`output/job-shop-scheduling.pl`](../examples/output/job-shop-scheduling.pl) |
 | [`knapsack-optimization.pl`](../examples/knapsack-optimization.pl) | Optimizes a finite 0/1 knapsack pack with aggregation. | [`output/knapsack-optimization.pl`](../examples/output/knapsack-optimization.pl) |
 | [`knowledge-engineering-alignment-flow.pl`](../examples/knowledge-engineering-alignment-flow.pl) | Specializes reusable alignment rules into a target-shaped flow view. | [`output/knowledge-engineering-alignment-flow.pl`](../examples/output/knowledge-engineering-alignment-flow.pl) |
 | [`law-of-cosines.pl`](../examples/law-of-cosines.pl) | Computes a triangle side by cosine law. | [`output/law-of-cosines.pl`](../examples/output/law-of-cosines.pl) |
 | [`least-squares-regression.pl`](../examples/least-squares-regression.pl) | Fits a least-squares regression line. | [`output/least-squares-regression.pl`](../examples/output/least-squares-regression.pl) |
+| [`linear-logic-resources.pl`](../examples/linear-logic-resources.pl) | Emulates linear logic resource consumption with explicit state threading. | [`output/linear-logic-resources.pl`](../examples/output/linear-logic-resources.pl) |
 | [`list-collection.pl`](../examples/list-collection.pl) | Demonstrates list and collection built-ins. | [`output/list-collection.pl`](../examples/output/list-collection.pl) |
 | [`lldm.pl`](../examples/lldm.pl) | Calculates leg-length discrepancy measurements. | [`output/lldm.pl`](../examples/output/lldm.pl) |
 | [`manufacturing-quality-control.pl`](../examples/manufacturing-quality-control.pl) | Evaluates process capability and quality. | [`output/manufacturing-quality-control.pl`](../examples/output/manufacturing-quality-control.pl) |
+| [`matrix-chain-order.pl`](../examples/matrix-chain-order.pl) | Finds an optimal matrix-chain multiplication order. | [`output/matrix-chain-order.pl`](../examples/output/matrix-chain-order.pl) |
 | [`microgrid-dispatch.pl`](../examples/microgrid-dispatch.pl) | Plans microgrid dispatch and reserve. | [`output/microgrid-dispatch.pl`](../examples/output/microgrid-dispatch.pl) |
 | [`missionaries-cannibals.pl`](../examples/missionaries-cannibals.pl) | Solves the missionaries-and-cannibals river crossing puzzle. | [`output/missionaries-cannibals.pl`](../examples/output/missionaries-cannibals.pl) |
+| [`modal-logic-kripke.pl`](../examples/modal-logic-kripke.pl) | Emulates modal box and diamond operators over a finite Kripke frame. | [`output/modal-logic-kripke.pl`](../examples/output/modal-logic-kripke.pl) |
+| [`modular-exponentiation.pl`](../examples/modular-exponentiation.pl) | Computes modular powers by repeated squaring. | [`output/modular-exponentiation.pl`](../examples/output/modular-exponentiation.pl) |
 | [`monkey-bananas.pl`](../examples/monkey-bananas.pl) | Solves the monkey-and-bananas puzzle. | [`output/monkey-bananas.pl`](../examples/output/monkey-bananas.pl) |
 | [`n-queens-8.pl`](../examples/n-queens-8.pl) | Solves the 8-queens search problem with diagonal constraints. | [`output/n-queens-8.pl`](../examples/output/n-queens-8.pl) |
 | [`network-sla.pl`](../examples/network-sla.pl) | Checks network path SLA compliance. | [`output/network-sla.pl`](../examples/output/network-sla.pl) |
@@ -416,6 +425,7 @@ Each example has a checked golden output in `examples/output`.
 | [`path-discovery.pl`](../examples/path-discovery.pl) | Discovers bounded air-route paths. | [`output/path-discovery.pl`](../examples/output/path-discovery.pl) |
 | [`peano-arithmetic.pl`](../examples/peano-arithmetic.pl) | Computes Peano addition, multiplication, and factorial. | [`output/peano-arithmetic.pl`](../examples/output/peano-arithmetic.pl) |
 | [`peasant.pl`](../examples/peasant.pl) | Performs peasant multiplication and exponentiation. | [`output/peasant.pl`](../examples/output/peasant.pl) |
+| [`pell-equation.pl`](../examples/pell-equation.pl) | Generates Pell-equation solutions by recurrence. | [`output/pell-equation.pl`](../examples/output/pell-equation.pl) |
 | [`pendulum-period.pl`](../examples/pendulum-period.pl) | Computes simple pendulum periods. | [`output/pendulum-period.pl`](../examples/output/pendulum-period.pl) |
 | [`polynomial.pl`](../examples/polynomial.pl) | Finds complex integer polynomial roots. | [`output/polynomial.pl`](../examples/output/polynomial.pl) |
 | [`proof-contrapositive.pl`](../examples/proof-contrapositive.pl) | Models proof by contrapositive. | [`output/proof-contrapositive.pl`](../examples/output/proof-contrapositive.pl) |
@@ -433,9 +443,11 @@ Each example has a checked golden output in `examples/output`.
 | [`socrates.pl`](../examples/socrates.pl) | Derives that Socrates is mortal. | [`output/socrates.pl`](../examples/output/socrates.pl) |
 | [`stable-marriage.pl`](../examples/stable-marriage.pl) | Finds stable matchings by excluding blocking pairs. | [`output/stable-marriage.pl`](../examples/output/stable-marriage.pl) |
 | [`statistics-summary.pl`](../examples/statistics-summary.pl) | Computes population statistics for a sample. | [`output/statistics-summary.pl`](../examples/output/statistics-summary.pl) |
+| [`stirling-bell-numbers.pl`](../examples/stirling-bell-numbers.pl) | Computes Stirling numbers and Bell numbers. | [`output/stirling-bell-numbers.pl`](../examples/output/stirling-bell-numbers.pl) |
 | [`sudoku-4x4.pl`](../examples/sudoku-4x4.pl) | Solves a compact 4x4 Sudoku by finite constraint search. | [`output/sudoku-4x4.pl`](../examples/output/sudoku-4x4.pl) |
 | [`superdense-coding.pl`](../examples/superdense-coding.pl) | Models superdense-coding bit transmission. | [`output/superdense-coding.pl`](../examples/output/superdense-coding.pl) |
 | [`term-tools.pl`](../examples/term-tools.pl) | Inspects, builds, renders, and validates terms with reusable term/control builtins. | [`output/term-tools.pl`](../examples/output/term-tools.pl) |
+| [`totient-summatory.pl`](../examples/totient-summatory.pl) | Computes Euler totients and their summatory function. | [`output/totient-summatory.pl`](../examples/output/totient-summatory.pl) |
 | [`trust-flow-provenance-threshold.pl`](../examples/trust-flow-provenance-threshold.pl) | Classifies message trust from provenance confidence scores. | [`output/trust-flow-provenance-threshold.pl`](../examples/output/trust-flow-provenance-threshold.pl) |
 | [`turing.pl`](../examples/turing.pl) | Simulates a binary-increment Turing machine. | [`output/turing.pl`](../examples/output/turing.pl) |
 | [`vector-similarity.pl`](../examples/vector-similarity.pl) | Computes dot product, norm, and cosine similarity. | [`output/vector-similarity.pl`](../examples/output/vector-similarity.pl) |
@@ -444,9 +456,6 @@ Each example has a checked golden output in `examples/output`.
 | [`witch.pl`](../examples/witch.pl) | Derives the classic “burn the witch” rule chain. | [`output/witch.pl`](../examples/output/witch.pl) |
 | [`wolf-goat-cabbage.pl`](../examples/wolf-goat-cabbage.pl) | Solves the wolf-goat-cabbage river crossing. | [`output/wolf-goat-cabbage.pl`](../examples/output/wolf-goat-cabbage.pl) |
 | [`zebra.pl`](../examples/zebra.pl) | Solves the zebra logic puzzle. | [`output/zebra.pl`](../examples/output/zebra.pl) |
-
-
-
 ## Golden outputs, tests, and conformance
 
 Golden answer outputs live in [`examples/output`](../examples/output). `npm run test:eyelang` covers the eyelang integration check, conformance cases, regression checks, runnable examples, and proof-output examples. A curated proof-output suite for `.pl` examples lives in [`examples/proof`](../examples/proof). Example tests pin `local_time/1` to `2026-05-30` so date-dependent examples stay deterministic. Regenerate them after an intentional output or explanation change:

package/docs/language-reference.md

@@ -534,7 +534,7 @@ materialize(status, 2).
 materialize(reason, 2).
 ```
 
-`materialize/2` affects host output selection only; it does not change the logical meaning of the program.
+`materialize/2` affects host output selection only; it does not change the logical meaning of the program. Materialized output facts are not asserted as new source facts for subsequent output goals. A host MAY solve several materialized predicates in one solver run, and memoized predicate answers MAY be reused within that run, but this reuse is controlled by `memoize/2`, not by materialization.
 
 ## 12. Eyelang Sockets
 

package/examples/ackermann.pl

@@ -1,12 +1,13 @@
 % Ackermann-style hyperoperation benchmark adapted from Eyeling ackermann.n3.
-% The two-argument entry point follows the Eyeling encoding:
-%   ackermann(X, Y) = hyper(X, Y + 3, 2) - 3.
+% The public ackermann/2 answers are small, but the helper relation exercises
+% deeply nested arithmetic recursion: hyper/4 encodes successor, addition,
+% multiplication, exponentiation, and then the Ackermann-style offset
+% ackermann(X, Y) = hyper(X, Y + 3, 2) - 3.
+% Keeping the selected inputs explicit avoids unbounded generation while still
+% testing the solver's recursive numeric workload.
 
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(ackermann, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
 ackermann(X, Y, A) :-
   add(Y, 3, B),
   hyper(X, B, 2, C),

package/examples/age.pl

@@ -1,21 +1,19 @@
 % Age checker adapted from Eyeling.
-%
-% Is the age of a person above some duration?
+% The example combines date literals, ISO-8601 duration values, local_time/1,
+% difference/3, and duration comparison.  It deliberately uses the current
+% local date so the derived ageAbove/2 fact remains an executable temporal
+% check rather than a precomputed constant.
 
-% Person data.
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(birthDay, 2).
 materialize(duration, 2).
 materialize(ageAbove, 2).
 materialize(is, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 birthDay(patH, "1944-08-21").
 duration(check, "P80Y").
 
 % A person is above a duration if the local date minus the birthday is greater
 % than that duration.
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
 ageAbove(S, A) :-
   birthDay(S, B),
   duration(check, A),

package/examples/aliases-and-namespaces.pl

@@ -1,17 +1,15 @@
-% Built-ins use one native spelling each.
-% Vocabulary predicate names remain ordinary user predicates.
-
-% The materialized relations below show that built-ins can coexist with
-% ordinary vocabulary predicates that happen to look namespace-like.
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
+% Built-ins use one native spelling each, while vocabulary-style predicate names
+% remain ordinary user predicates.
+%
+% This keeps the language small: add/3, lt/2, matches/3, and rest/2 are native
+% operations, but labels such as nativeMath or vocabularyExample are just data.
 materialize(value, 2).
 materialize(ok, 2).
 materialize(tail, 2).
 materialize(label, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
-% Native operations are called through their canonical predicate names.
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
+% The first four rules call native built-ins; the last two rules show that
+% application vocabulary is modeled with ordinary facts and rules.
 value(nativeMath, X) :- add(0.125, 0.875, X).
 ok(nativeCompare, true) :- lt(2, 3).
 ok(nativeString, true) :- matches("scoped retail insight", "retail|medical").

package/examples/ancestor.pl

@@ -1,17 +1,18 @@
 % Basic recursive relation example.
-% Both input facts and derived recursive answers are printed.
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
+% parent/2 facts form a small family chain.  ancestor/2 has the classic two-rule
+% shape: one base rule copies direct parents, and one recursive rule walks one
+% parent edge before continuing through the chain.  Both source and derived
+% relations are materialized so the output shows the closure explicitly.
+
 materialize(parent, 2).
 materialize(ancestor, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Direct parent facts form a simple chain.
 parent(pat, jan).
 parent(jan, lies).
 parent(lies, emma).
 
 % Base case: every parent is also an ancestor.
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
 ancestor(X, Y) :-
   parent(X, Y).
 

package/examples/backward.pl

@@ -1,12 +1,11 @@
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
-materialize(isIndeedMoreInterestingThan, 2).
+% Backward-rule example adapted from Eyeling backward.n3.
+% Eyeling writes the interestingness rule in a backward style; eyelang records
+% the same dependency as an ordinary Horn rule.  The example is intentionally
+% tiny: it demonstrates that a derived fact can be justified by a numeric
+% comparison in the rule body.
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
-% Backward rule example adapted from Eyeling backward.n3.
-% Eyeling writes the interestingness rule backward; eyelang records the same
-% relation as an ordinary rule whose body is the numeric comparison.
+materialize(isIndeedMoreInterestingThan, 2).
 
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
 moreInterestingThan(X, Y) :- gt(X, Y).
 
 isIndeedMoreInterestingThan(5, 3) :- moreInterestingThan(5, 3).

package/examples/bayes-therapy.pl

@@ -1,6 +1,11 @@
 % Memoize shared inference layers: the score vector, disease likelihood tails,
 % and expected therapy success are reused by several report relations.
 % Output declarations: materialize/2 selects the relations written to this example's golden output.
+%
+% Read this as two stacked inference problems: first infer disease posterior
+% probabilities from symptoms, then score each therapy by averaging outcomes
+% over that posterior distribution. The memoized predicates are exactly the
+% shared layers used by several materialized reports.
 materialize(diseases, 2).
 materialize(therapies, 2).
 materialize(evidence, 2).
@@ -95,6 +100,7 @@ likelihood(Disease, [Evidence|Rest], Likelihood) :-
   likelihood(Disease, Rest, TailLikelihood),
   mul(Factor, TailLikelihood, Likelihood).
 
+% score/2 combines prior probability with the likelihood of the observed evidence.
 score(Disease, Score) :-
   prior(Disease, Prior),
   evidence(case, Evidence),
@@ -131,6 +137,7 @@ expected_success(Therapy, ExpectedSuccess) :-
   success_by_disease(Therapy, SuccessByDisease),
   dot_product(Posteriors, SuccessByDisease, ExpectedSuccess).
 
+% utility/2 turns expected success and adverse effects into a ranking score.
 utility(Therapy, Utility) :-
   expected_success(Therapy, ExpectedSuccess),
   adverse(Therapy, Adverse),

package/examples/beam-deflection.pl

@@ -1,22 +1,20 @@
 % Engineering example: cantilever beam tip deflection.
-%
-% The tip deflection for a point load at the free end is F*L^3/(3*E*I).
+% The beam is modeled with load, span length, elastic modulus, and second moment
+% of area.  The rules compute F*L^3/(3*E*I), convert meters to millimeters, and
+% classify the design against a deflection limit.
 
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(type, 2).
 materialize(tipDeflection_m, 2).
 materialize(tipDeflection_mm, 2).
 materialize(limit_mm, 2).
 materialize(status, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 beam(beam1, force_N, 1200.0).
 beam(beam1, length_m, 2.5).
 beam(beam1, elasticModulus_Pa, 200000000000.0).
 beam(beam1, secondMoment_m4, 0.000008).
 limit(beam1, maxDeflection_mm, 5.0).
 
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
 tip_deflection_m(Beam, Deflection) :-
   beam(Beam, force_N, Force),
   beam(Beam, length_m, Length),

package/examples/binomial-vandermonde.pl

@@ -0,0 +1,49 @@
+% Binomial coefficients and Vandermonde's identity.
+%
+% choose(N,K,C) is computed by a multiplicative recurrence, then vandermonde/5 checks
+% the finite convolution sum: sum_i C(R,i) C(S,N-i) = C(R+S,N).  Memoization keeps
+% the binomial-row prefixes shared across both sides of the identity.
+% choose_step/5 uses the multiplicative recurrence
+%   C(N, I+1) = C(N, I) * (N-I) / (I+1)
+% and is memoized because row sums and identities reuse prefixes.
+materialize(binomial_answer, 2).
+
+memoize(choose_step, 5).
+
+choose(N, K, C) :-
+  ge(K, 0),
+  le(K, N),
+  choose_step(N, K, 0, 1, C).
+
+choose_step(_N, K, K, Acc, Acc).
+choose_step(N, K, I, Acc, C) :-
+  lt(I, K),
+  add(I, 1, I1),
+  sub(N, I, Factor),
+  mul(Acc, Factor, Numerator),
+  div(Numerator, I1, NextAcc),
+  choose_step(N, K, I1, NextAcc, C).
+
+symmetric(N, K) :-
+  choose(N, K, C),
+  sub(N, K, OtherK),
+  choose(N, OtherK, C).
+
+vandermonde_sum(N, M, R, Sum) :-
+  sumall(Product,
+    (between(0, R, K),
+     sub(R, K, RK),
+     choose(N, K, A),
+     choose(M, RK, B),
+     mul(A, B, Product)),
+    Sum).
+
+vandermonde(N, M, R, Sum) :-
+  add(N, M, TotalN),
+  choose(TotalN, R, Sum),
+  vandermonde_sum(N, M, R, Sum).
+
+binomial_answer(choose_24_12, C) :- choose(24, 12, C).
+binomial_answer(symmetry_24_7, true) :- symmetric(24, 7).
+binomial_answer(vandermonde_12_10_8, Sum) :- vandermonde(12, 10, 8, Sum).
+binomial_answer(row_12_sum, Sum) :- sumall(C, (between(0, 12, K), choose(12, K, C)), Sum).

package/examples/blocks-world-planning.pl

@@ -10,7 +10,8 @@ materialize(plan, 2).
 materialize(finalState, 2).
 materialize(blockCount, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% The initial and goal states are lists of on/2 facts.  Sorting successor states
+% gives canonical terms for equality and visited-state checks.
 initial([on(a, table), on(b, a), on(c, b), on(d, c), on(e, d)]).
 goal([on(a, table), on(b, a), on(c, table), on(d, c), on(e, d)]).
 
@@ -21,7 +22,8 @@ block(d).
 block(e).
 
 support(table, _State).
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
+% move/3 chooses a clear block and a clear support; the bounded planner chains
+% those legal moves while avoiding previously seen states.
 support(Block, State) :-
   block(Block),
   member(on(Block, _Below), State).

package/examples/buck-converter-design.pl

@@ -4,6 +4,10 @@
 % inductor ripple current, capacitor ripple voltage, and checks design limits.
 
 % Output declarations: materialize/2 selects the relations written to this example's golden output.
+%
+% The constants describe one regulator design. The rules intentionally keep
+% each engineering equation separate so proof output can point to the exact
+% calculation that made the design pass or fail.
 materialize(dutyCycle, 2).
 materialize(inductorRipple_A, 2).
 materialize(rippleRatio, 2).
@@ -51,6 +55,7 @@ capacitor_ripple_voltage(Converter, RippleVoltage) :-
   mul(EightF, Capacitance, Denominator),
   div(RippleCurrent, Denominator, RippleVoltage).
 
+% within_ripple_limits/1 is the design gate for ripple current and output voltage.
 within_ripple_limits(Converter) :-
   ripple_ratio(Converter, Ratio),
   limit(Converter, maxRippleRatio, MaxRatio),

package/examples/cache-performance.pl

@@ -10,12 +10,14 @@ materialize(averageLatency_ms, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% cache_sample/5 contains hits, misses, and the two latency classes; threshold/3
+% contains the operational targets used by the status rule.
 cache_sample(api_cache, 8600.0, 1400.0, 5.0, 80.0).
 threshold(api_cache, minimum_hit_rate, 0.80).
 threshold(api_cache, maximum_average_latency_ms, 20.0).
 
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
+% The rules compute total requests, hit rate, and weighted latency before
+% applying both acceptance thresholds together.
 total_requests(Cache, Total) :-
   cache_sample(Cache, Hits, Misses, _HitLatency, _MissLatency),
   add(Hits, Misses, Total).

package/examples/canary-release.pl

@@ -10,12 +10,14 @@ materialize(latencyCheck, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% canary/4 records request count, error count, and p95 latency; thresholds
+% make the rollout policy explicit data rather than constants hidden in rules.
 canary(canary42, 5000.0, 75.0, 180.0).
 threshold(canary42, maximum_error_rate, 0.01).
 threshold(canary42, maximum_p95_latency_ms, 200.0).
 
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
+% The latency and error-budget checks are independent so the final rollback
+% reason can point to the failing guard.
 error_rate(Release, Rate) :-
   canary(Release, Requests, Errors, _P95Latency),
   div(Errors, Requests, Rate).

package/examples/catalan-convolution.pl

@@ -0,0 +1,37 @@
+% Catalan numbers by memoized convolution.
+%
+% catalan(N,C) sums all splits of N-1 into left and right substructures.  The same
+% Catalan values appear in binary tree shapes, parenthesizations, and polygon
+% triangulations, shown here with small wrapper predicates.
+materialize(catalan_answer, 2).
+
+memoize(catalan, 2).
+
+% C_0 = 1; higher values are computed by the convolution sum.
+catalan(0, 1).
+catalan(N, C) :-
+  gt(N, 0),
+  sub(N, 1, N1),
+  sumall(Product,
+    (between(0, N1, I),
+     sub(N1, I, J),
+     catalan(I, A),
+     catalan(J, B),
+     mul(A, B, Product)),
+    C).
+
+% An n-gon has C_(n-2) triangulations.
+polygon_triangulations(Sides, Count) :-
+  ge(Sides, 3),
+  sub(Sides, 2, N),
+  catalan(N, Count).
+
+parenthesizations(Factors, Count) :-
+  ge(Factors, 1),
+  sub(Factors, 1, N),
+  catalan(N, Count).
+
+catalan_answer(catalan_12, C) :- catalan(12, C).
+catalan_answer(triangulations_14_gon, Count) :- polygon_triangulations(14, Count).
+catalan_answer(parenthesizations_13_factors, Count) :- parenthesizations(13, Count).
+catalan_answer(first_ten_sum, Sum) :- sumall(C, (between(0, 9, N), catalan(N, C)), Sum).

package/examples/chart-parser.pl

@@ -1,10 +1,14 @@
 % A tiny memoized chart parser for a context-free grammar.
-% span/4 is the dynamic-programming chart relation: sentence, category,
-% start index, and end index.
+%
+% span(Sentence, Category, Start, End) is the dynamic-programming chart item:
+% Category covers a half-open token interval.  Memoizing span/4 turns recursive
+% grammar recognition into chart parsing, so ambiguous phrases share subparses.
 materialize(chart_parser_answer, 2).
 
 memoize(span, 4).
 
+% Two sample sentences share the same tiny grammar but have different parse counts.
+
 sentence(command, 5).
 sentence(ambiguous_pp, 8).
 
@@ -38,10 +42,12 @@ rule(vp, verb, np).
 rule(vp, vp, pp).
 rule(pp, prep, np).
 
+% Lexical chart items come directly from words and terminal categories.
 span(Sentence, Category, Start, End) :-
   word(Sentence, Start, Token),
   terminal(Category, Token),
   add(Start, 1, End).
+% Nonterminal chart items split the interval at a Middle point.
 span(Sentence, Category, Start, End) :-
   rule(Category, Left, Right),
   span(Sentence, Left, Start, Middle),

package/examples/clinical-trial-screening.pl

@@ -5,6 +5,10 @@
 % public relation report.
 
 % Output declarations: materialize/2 selects the relations written to this example's golden output.
+%
+% Inclusion criteria are positive requirements; exclusion criteria veto a
+% candidate even when the inclusion checks pass. The emitted reason/2 facts are
+% the audit trail a coordinator would need for a screen-failure report.
 materialize(type, 2).
 materialize(status, 2).
 materialize(reason, 2).
@@ -58,6 +62,7 @@ exclusion_renal(Patient) :-
 exclusion_pregnancy(Patient) :-
   condition(Patient, pregnant).
 
+% A patient is eligible only when all inclusion checks pass and no exclusion is proven.
 screen_eligible(Patient) :-
   inclusion_adult(Patient),
   inclusion_diagnosis(Patient),

package/examples/combinatorics-findall-sort.pl

@@ -1,15 +1,16 @@
 % Eyelet-inspired combinations example using findall/3 and sort/2.
-% The source-level select/3 relation remains an ordinary eyelang rule.
-
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
+%
+% combination/3 generates the same subset in several selection orders.  findall/3
+% collects those candidates, and sort/2 canonicalizes the list so each unordered
+% 3-combination of five items is reported once.
 materialize(combinations, 2).
 materialize(count, 2).
 materialize(reason, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
-% select/3 nondeterministically removes one item from a list.
+% select/3 nondeterministically removes one item from a list; because it is an
+% ordinary rule, the example also demonstrates user-level list recursion.
 select(Item, [Item | Rest], Rest).
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
+% The recursive clause keeps the non-selected head and searches the tail.
 select(Item, [Head | Tail], [Head | Rest]) :-
   select(Item, Tail, Rest).
 

package/examples/complex.pl

@@ -4,6 +4,10 @@
 % the pair-shaped pair lists used by the Eyeling source.
 
 % Output declarations: materialize/2 selects the relations written to this example's golden output.
+%
+% The example derives arithmetic identities, polar conversions, powers, roots,
+% exponential/trigonometric functions, and distance/normalization results from
+% a small complex-number toolkit.
 materialize(is, 2).
 
 % Program structure: facts set up the scenario, and rules derive the materialized conclusions.
@@ -11,6 +15,7 @@ pi(3.141592653589793).
 e(2.718281828459045).
 
 % Derivation rules: each rule below contributes one logical step toward the displayed results.
+% z^w is evaluated through polar/log form, exposing useful intermediate proof steps.
 complex_exponentiation([A, B], [C, D], [E, F]) :-
   complex_polar([A, B], [R, T]),
   pow(R, C, Z1),

package/examples/continued-fraction-sqrt2.pl

@@ -0,0 +1,36 @@
+% Convergents of sqrt(2) by memoized recurrence.
+%
+% conv(N, P, Q) gives the Nth numerator/denominator pair for [1; 2, 2, ...].
+% Because each convergent depends on the previous two, memoization avoids the
+% exponential recomputation that the direct Horn-clause recurrence would have.
+% pell_error/2 connects the approximation sequence with P^2 - 2Q^2 = +/-1.
+materialize(convergent_answer, 2).
+
+memoize(conv, 3).
+
+% Base convergents are 1/1 and 3/2.
+conv(0, 1, 1).
+conv(1, 3, 2).
+conv(N, P, Q) :-
+  gt(N, 1),
+  sub(N, 1, N1),
+  sub(N, 2, N2),
+  conv(N1, P1, Q1),
+  conv(N2, P2, Q2),
+  mul(2, P1, TwiceP1),
+  add(TwiceP1, P2, P),
+  mul(2, Q1, TwiceQ1),
+  add(TwiceQ1, Q2, Q).
+
+% The signed error alternates between +1 and -1 for these convergents.
+pell_error(N, Error) :-
+  conv(N, P, Q),
+  mul(P, P, P2),
+  mul(Q, Q, Q2),
+  mul(2, Q2, TwiceQ2),
+  sub(P2, TwiceQ2, Error).
+
+convergent_answer(convergent_10, fraction(P, Q)) :- conv(10, P, Q).
+convergent_answer(convergent_15, fraction(P, Q)) :- conv(15, P, Q).
+convergent_answer(pell_error_15, Error) :- pell_error(15, Error).
+convergent_answer(numerator_sum_0_to_10, Sum) :- sumall(P, (between(0, 10, N), conv(N, P, _Q)), Sum).

package/examples/control-system.pl

@@ -4,6 +4,10 @@
 % feedforward compensation, square-root normalization, and nonlinear feedback.
 
 % Output declarations: materialize/2 selects the relations written to this example's golden output.
+%
+% Each derived quantity is represented as its own predicate rather than a single
+% formula blob, making the proof trace useful for debugging a failed actuator
+% normalization or control-signal calculation.
 materialize(controlSignal, 2).
 materialize(status, 2).
 materialize(normalizedMeasurement, 2).

package/examples/critical-path-schedule.pl

@@ -1,11 +1,15 @@
 % Critical-path scheduling for a small project network.
-% earliest_start/2 and finish_time/2 are memoized because many schedule and
-% critical-path queries reuse the same predecessor subproblems.
+%
+% earliest_start/2 is the maximum finish time over all predecessors; finish_time/2
+% adds task duration.  Critical tasks are reconstructed by following predecessors
+% that attain those maxima.  Memoization lets the schedule, finish date, and path
+% queries share the same project-network subproblems.
 materialize(critical_path_answer, 2).
 
 memoize(earliest_start, 2).
 memoize(finish_time, 2).
 
+% Durations are in arbitrary project time units.
 task(requirements, 2).
 task(architecture, 3).
 task(api_design, 2).
@@ -47,6 +51,7 @@ finish_time(Task, Finish) :-
   earliest_start(Task, Start),
   add(Start, Duration, Finish).
 
+% For each task, choose a predecessor that determines its earliest start.
 critical_predecessor(Task, Pred) :-
   depends(Task, _AnyPred),
   aggregate_max(Finish, P,