eyelang 1.1.17 → 1.1.19

package/docs/guide.md

@@ -397,17 +397,20 @@ Each example has a checked golden output in `examples/output`.
 | [`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) |
@@ -453,7 +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/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

@@ -1,4 +1,8 @@
 % 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.

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

@@ -1,10 +1,13 @@
 % Catalan numbers by memoized convolution.
-% catalan/2 counts binary tree shapes, parenthesizations, and polygon
-% triangulations with the usual index shifts.
+%
+% 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),
@@ -17,6 +20,7 @@ catalan(N, C) :-
      mul(A, B, Product)),
     C).
 
+% An n-gon has C_(n-2) triangulations.
 polygon_triangulations(Sides, Count) :-
   ge(Sides, 3),
   sub(Sides, 2, N),

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

@@ -1,9 +1,14 @@
 % Convergents of sqrt(2) by memoized recurrence.
-% conv(N, P, Q) gives the Nth convergent numerator/denominator for [1;2,2,...].
+%
+% 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) :-
@@ -17,6 +22,7 @@ conv(N, P, Q) :-
   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),

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,

package/examples/cyclic-path.pl

@@ -1,16 +1,18 @@
-% Cyclic transitive closure. The graph contains a directed cycle, but eyelang's
-% variant loop guard prevents recursive proof search from revisiting the same
-% active subgoal forever.
+% Cyclic transitive closure.
+%
+% The graph deliberately contains the directed cycle a -> b -> c -> d -> a.  The
+% recursive path/2 rule therefore has to deal with cycles while still deriving
+% the reachable pairs used by the golden output.
+%
+% This is a compact regression-style example for active-goal handling in recursive
+% graph search.
 
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(path, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 arc(a, b).
 arc(b, c).
 arc(c, d).
 arc(d, a).
 
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
 path(X, Y) :- arc(X, Y).
 path(X, Z) :- arc(X, Y), path(Y, Z).

package/examples/d3-group.pl

@@ -1,12 +1,12 @@
 % Eyelet-inspired D3 group example using findall/3 and sort/2.
-% It enumerates subgroups of the dihedral group of order 6.
+% The six facts are the symmetries of an equilateral triangle, with compose/3 as
+% the Cayley table and inverse/2 as the inverse relation.  Candidate subsets are
+% generated as subsequences, then filtered for subgroup closure.
 
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(subgroups, 2).
 materialize(subgroupCount, 2).
 materialize(reason, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Six symmetries of an equilateral triangle: identity, rotations, reflections.
 symmetry(identity).
 symmetry(rotation_120).
@@ -62,7 +62,6 @@ inverse(reflection_c, reflection_c).
 
 % Candidate subsets are generated as subsequences of the sorted symmetry list.
 subsequence([], []).
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
 subsequence([Head | Tail], [Head | Rest]) :-
   subsequence(Tail, Rest).
 subsequence([_Head | Tail], Rest) :-

package/examples/dairy-energy-balance.pl

@@ -1,21 +1,21 @@
 % EYE-inspired dairy energy balance case study.
-% Cows are classified from maintenance, milk requirement, and ration supply.
-
-% cow(Cow, BodyWeightKg, MilkKgPerDay, RationEnergyMcalPerKgDM, IntakeKgDM).
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
+%
+% cow(Cow, BodyWeightKg, MilkKgPerDay, RationEnergyMcalPerKgDM, IntakeKgDM)
+% records a small herd.  Rules estimate maintenance demand, milk-production
+% demand, ration supply, and the resulting energy-balance class.
 materialize(energyBalance_Mcal, 2).
 materialize(rationSupportedMilk_kg, 2).
 materialize(status, 2).
 materialize(reason, 2).
 materialize(strongestDeficit, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Four cows cover negative, near-neutral, and positive balance cases.
 cow(early_lactation, 650, 38, 6.4, 22).
 cow(mid_lactation, 610, 24, 6.5, 26).
 cow(late_lactation, 580, 16, 6.7, 25).
 cow(grazing, 540, 18, 5.8, 21).
 
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
+% Maintenance scales with body weight; milk requirement scales with daily milk.
 maintenance(C, M) :-
   cow(C, Weight, _, _, _),
   mul(Weight, 0.08, M).
@@ -33,6 +33,7 @@ total_requirement(C, R) :-
   milk_requirement(C, MilkR),
   add(M, MilkR, R).
 
+% energy_balance/2 is intake minus maintenance and milk-production demand.
 energy_balance(C, B) :-
   ration_supply(C, S),
   total_requirement(C, R),

package/examples/data-negotiation.pl

@@ -1,10 +1,10 @@
 % Data negotiation with policies, adapted from Eyelet input/data-negotiation.pl.
-% The accepted negotiation matches Eyelet output-swipl/data-negotiation.pl.
+% Two agents own different datasets.  A negotiation succeeds only when the
+% requester lacks the data, the provider has it, the requester policy allows
+% asking for it, and the provider policy allows sharing it.
 
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(negotiate, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Each agent has local data, desired remote data, and a simple policy.
 hasData(agent1, [data1, data2, data3]).
 hasData(agent2, [data4, data5, data6]).
@@ -13,7 +13,6 @@ want_negotiate(agent1, [agent2, data4]).
 want_negotiate(agent1, [agent2, data5]).
 want_negotiate(agent1, [agent2, data7]).
 
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
 policy(agent1, [request, Data]) :-
   member(Data, [data4, data6]).
 policy(agent2, [accept, Data]) :-

package/examples/deontic-logic.pl

@@ -1,11 +1,12 @@
 % Deontic logic: obligations, prohibitions, compensations, and violations.
+% The example separates normative facts from observed actions.  Missing an
+% obligation and performing a prohibited action are violations, but a prohibited
+% action can be marked compensated when the configured repair action occurred.
 
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(violation, 2).
 materialize(compensation, 2).
 materialize(status, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Facts state what the actor was obliged/prohibited to do and what happened.
 actor(alice).
 action(share_record).
@@ -21,7 +22,6 @@ not_performed(alice, obtain_consent).
 not_performed(alice, delete_unneeded_copy).
 
 % Missing an obligation and performing a prohibited action are both violations.
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
 violation(Actor, missed_obligation(Action)) :-
   obliged(Actor, Action),
   not_performed(Actor, Action).

package/examples/dijkstra-findall-sort.pl

@@ -1,12 +1,12 @@
 % Eyelet-inspired Dijkstra example using findall/3 and sort/2.
-% Adapted to eyelang's explicit built-ins and relation report style.
+% The priority queue is represented as sorted list entries [Cost, Node | Path].
+% Each expansion collects unvisited neighbors with findall/3, appends them to
+% the frontier, and uses sort/2 so the cheapest frontier entry is processed next.
 
-% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(shortestPath, 2).
 materialize(cost, 2).
 materialize(reason, 2).
 
-% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Weighted undirected graph; the symmetric edge rule below adds reverse arcs.
 edge(a, b, 4).
 edge(a, c, 2).
@@ -17,7 +17,6 @@ edge(c, e, 10).
 edge(d, e, 2).
 edge(d, f, 6).
 edge(e, f, 3).
-% Derivation rules: each rule below contributes one logical step toward the displayed results.
 edge(A, B, Cost) :- edge(B, A, Cost).
 
 % The frontier is represented as [Cost, Node | ReversePath] entries.