eyelang 1.5.3 → 1.5.5

package/conformance/README.md

@@ -7,7 +7,7 @@ The suite is intentionally file-based so another implementation can run the same
 - `conformance/cases/<profile>/<name>.pl` — input program;
 - `conformance/expected/<profile>/<name>.out` — exact expected standard output.
 
-The current runner compares standard output, including answer facts and their `why/2` explanation facts. Standard error, performance, and resource limits are outside this suite.
+The current runner compares standard output from normal execution. Proof explanations are opt-in in the CLI and are not part of these conformance goldens. Standard error, performance, and resource limits are outside this suite.
 
 ## Running the suite
 
@@ -34,9 +34,9 @@ The runner executes materialized programs in-process through the public JavaScri
 
 ## Profiles
 
-`core` covers the portable core language profile from `../SPEC.md`: lexical syntax, facts, definite clauses, first-order terms, lists, conjunction, unification through user predicates, left-to-right goal-directed proof search, and answer printing.
+`core` covers the portable core language profile from `../SPEC.md`: lexical syntax, facts, definite clauses, first-order terms, lists, conjunction, structured unification through user predicates, left-to-right goal-directed proof search, materialized output, and read-back printing.
 
-`extension` covers the standard built-in and host behavior exercised by the current reference implementation: arithmetic, comparison, strings, list relations, aggregation, formula-term helpers, `memoize/2`, `materialize/2`, and default derived output.
+`extension` covers the standard built-in and host behavior exercised by the current reference implementation: arithmetic, comparison, strings, list relations, aggregation, formula-term helpers, number-theory helpers, finite-search helpers, matrix helpers, `memoize/2`, `materialize/2`, and default derived output.
 
 The profile name `extension` is a test-suite grouping name. It does not mean that these cases are outside the eyelang specification; most of them correspond to the standard built-in profile and standard host profile in `../SPEC.md`.
 

package/conformance/cases/core/021_repeated_variable_head.pl

@@ -0,0 +1,7 @@
+% SPEC 5.1, 7.1: repeated variables in a rule body require the same term.
+pair(a, a).
+pair(a, b).
+pair(c, c).
+diagonal(X) :- pair(X, X).
+answer(diagonal, X) :- diagonal(X).
+materialize(answer, 2).

package/conformance/cases/core/022_rule_head_structure.pl

@@ -0,0 +1,5 @@
+% SPEC 5.3, 6, 7.1: structured rule heads destructure matching goals.
+unpack(pair(X, Y), X, Y).
+answer(first, A) :- unpack(pair(alpha, beta), A, _).
+answer(second, B) :- unpack(pair(alpha, beta), _, B).
+materialize(answer, 2).

package/conformance/cases/core/023_quoted_escapes_readback.pl

@@ -0,0 +1,5 @@
+% SPEC 3.5, 11: quoted strings and atoms preserve escape sequences at read-back.
+raw(string, "line\nnext\t\\slash").
+raw(atom, 'line\nnext\t\\slash').
+answer(K, V) :- raw(K, V).
+materialize(answer, 2).

package/conformance/cases/core/024_numeric_literal_readback.pl

@@ -0,0 +1,6 @@
+% SPEC 3.3, 11: signed, decimal, and exponent numeric literals retain lexical form.
+raw(negative_decimal, -3.5).
+raw(positive_exp, 6.02e23).
+raw(negative_exp, -1.0e-3).
+answer(K, V) :- raw(K, V).
+materialize(answer, 2).

package/conformance/cases/core/025_body_parentheses_with_formula_data.pl

@@ -0,0 +1,5 @@
+% SPEC 5.5, 7: formula data can be passed through parenthesized conjunctions.
+record((left(a), right(b))).
+accept((left(a), right(b))).
+answer(ok, F) :- (record(F), accept(F)).
+materialize(answer, 2).

package/conformance/cases/core/026_underscore_named_variable_reuse.pl

@@ -0,0 +1,5 @@
+% SPEC 3.4, 5.1: variables beginning with underscore are named variables unless exactly _.
+pair(a, a).
+pair(a, b).
+answer(shared, _Value) :- pair(_Value, _Value).
+materialize(answer, 2).

package/conformance/cases/extension/035_date_difference.pl

@@ -0,0 +1,4 @@
+% SPEC 9.1: difference/3 computes ISO date durations.
+answer(duration, D) :- difference("2024-03-01", "2020-02-29", D).
+answer(month_borrow, D) :- difference("2024-03-01", "2024-01-31", D).
+materialize(answer, 2).

package/conformance/cases/extension/036_extended_gcd.pl

@@ -0,0 +1,3 @@
+% SPEC 9.2: extended_gcd/5 returns gcd and Bezout coefficients.
+answer(gcd, result(G, S, T)) :- extended_gcd(240, 46, G, S, T).
+materialize(answer, 2).

package/conformance/cases/extension/037_collatz_trajectory.pl

@@ -0,0 +1,3 @@
+% SPEC 9.2: collatz_trajectory/2 returns the full path to 1.
+answer(path, T) :- collatz_trajectory(6, T).
+materialize(answer, 2).

package/conformance/cases/extension/038_kaprekar_steps.pl

@@ -0,0 +1,3 @@
+% SPEC 9.2: kaprekar_steps/2 counts iterations to 6174.
+answer(steps, N) :- kaprekar_steps(3524, N).
+materialize(answer, 2).

package/conformance/cases/extension/039_goldbach_pair.pl

@@ -0,0 +1,3 @@
+% SPEC 9.2: goldbach_pair/3 enumerates prime decompositions in ascending first prime order.
+answer(pair, pair(P, Q)) :- goldbach_pair(28, P, Q).
+materialize(answer, 2).

package/conformance/cases/extension/040_matrix_operations.pl

@@ -0,0 +1,5 @@
+% SPEC 9.2: matrix helpers handle small ground numeric matrices.
+answer(sum, M) :- matrix_sum([[[1, 2], [3, 4]], [[5, 6], [7, 8]]], M).
+answer(product, M) :- matrix_multiply([[[1, 2], [3, 4]], [[2, 0], [1, 2]]], M).
+answer(determinant, D) :- determinant([[4, 2], [2, 3]], D).
+materialize(answer, 2).

package/conformance/cases/extension/041_atom_range_generators.pl

@@ -0,0 +1,5 @@
+% SPEC 9.5: atom range helpers generate prefixed atoms deterministically.
+answer(single, X) :- atom_range(n, 2, 4, X).
+answer(multiple, X) :- atom_ranges([a, b], 1, 2, X).
+answer(bound_check, yes) :- atom_range(n, 2, 4, n3).
+materialize(answer, 2).

package/conformance/cases/extension/042_n_queens_small.pl

@@ -0,0 +1,3 @@
+% SPEC 9.5: n_queens/2 enumerates finite board solutions.
+answer(solution, Qs) :- n_queens(4, Qs).
+materialize(answer, 2).

package/conformance/cases/extension/043_cnf_model.pl

@@ -0,0 +1,3 @@
+% SPEC 9.5: cnf_model/3 enumerates satisfying truth assignments for a CNF.
+answer(model, M) :- cnf_model([a, b], [[pos(a), pos(b)], [neg(a)]], M).
+materialize(answer, 2).

package/conformance/cases/extension/044_cover9_filter.pl

@@ -0,0 +1,6 @@
+% SPEC 9.5: cover9/1 accepts exactly the digits 1 through 9 once.
+answer(ok, yes) :- cover9([1, 2, 3, 4, 5, 6, 7, 8, 9]).
+answer(candidate, X) :- row(X), cover9(X).
+row([1, 2, 3, 4, 5, 6, 7, 8, 9]).
+row([1, 1, 2, 3, 4, 5, 6, 7, 8]).
+materialize(answer, 2).

package/conformance/cases/extension/045_alphametic_sum_small.pl

@@ -0,0 +1,3 @@
+% SPEC 9.5: alphametic_sum/5 enumerates unique digit assignments for column addition.
+answer(solution, result(Digits, Values)) :- alphametic_sum([a, b], [[a], [a]], [b], Digits, Values).
+materialize(answer, 2).

package/conformance/cases/extension/046_bounded_subset.pl

@@ -0,0 +1,4 @@
+% SPEC 9.5: bounded_subset/7 enumerates subsets within budget and risk caps.
+projects([p(a, 5, 3, 1), p(b, 4, 2, 2), p(c, 7, 5, 3)]).
+answer(selection, result(Names, Value, Cost, Risk)) :- projects(Ps), bounded_subset(Ps, 5, 3, Names, Value, Cost, Risk).
+materialize(answer, 2).

package/conformance/expected/core/021_repeated_variable_head.out

@@ -0,0 +1,2 @@
+answer(diagonal, a).
+answer(diagonal, c).

package/conformance/expected/core/022_rule_head_structure.out

@@ -0,0 +1,2 @@
+answer(first, alpha).
+answer(second, beta).

package/conformance/expected/core/023_quoted_escapes_readback.out

@@ -0,0 +1,2 @@
+answer(string, "line\nnext	\\slash").
+answer(atom, 'line\nnext\t\\slash').

package/conformance/expected/core/024_numeric_literal_readback.out

@@ -0,0 +1,3 @@
+answer(negative_decimal, -3.5).
+answer(positive_exp, 6.02e23).
+answer(negative_exp, -1.0e-3).

package/conformance/expected/core/025_body_parentheses_with_formula_data.out

@@ -0,0 +1 @@
+answer(ok, (left(a), right(b))).

package/conformance/expected/core/026_underscore_named_variable_reuse.out

@@ -0,0 +1 @@
+answer(shared, a).

package/conformance/expected/extension/035_date_difference.out

@@ -0,0 +1,2 @@
+answer(duration, "P4Y1D").
+answer(month_borrow, "P1M-1D").

package/conformance/expected/extension/036_extended_gcd.out

@@ -0,0 +1 @@
+answer(gcd, result(2, -9, 47)).

package/conformance/expected/extension/037_collatz_trajectory.out

@@ -0,0 +1 @@
+answer(path, [6, 3, 10, 5, 16, 8, 4, 2, 1]).

package/conformance/expected/extension/038_kaprekar_steps.out

@@ -0,0 +1 @@
+answer(steps, 3).

package/conformance/expected/extension/039_goldbach_pair.out

@@ -0,0 +1,2 @@
+answer(pair, pair(5, 23)).
+answer(pair, pair(11, 17)).

package/conformance/expected/extension/040_matrix_operations.out

@@ -0,0 +1,3 @@
+answer(sum, [[6, 8], [10, 12]]).
+answer(product, [[4, 4], [10, 8]]).
+answer(determinant, 8.0000000000000018).

package/conformance/expected/extension/041_atom_range_generators.out

@@ -0,0 +1,8 @@
+answer(single, n2).
+answer(single, n3).
+answer(single, n4).
+answer(multiple, a1).
+answer(multiple, a2).
+answer(multiple, b1).
+answer(multiple, b2).
+answer(bound_check, yes).

package/conformance/expected/extension/042_n_queens_small.out

@@ -0,0 +1,2 @@
+answer(solution, [2, 4, 1, 3]).
+answer(solution, [3, 1, 4, 2]).

package/conformance/expected/extension/043_cnf_model.out

@@ -0,0 +1 @@
+answer(model, [value(a, false), value(b, true)]).

package/conformance/expected/extension/044_cover9_filter.out

@@ -0,0 +1,2 @@
+answer(ok, yes).
+answer(candidate, [1, 2, 3, 4, 5, 6, 7, 8, 9]).

package/conformance/expected/extension/045_alphametic_sum_small.out

@@ -0,0 +1,4 @@
+answer(solution, result([1, 2], [1, 1, 2])).
+answer(solution, result([2, 4], [2, 2, 4])).
+answer(solution, result([3, 6], [3, 3, 6])).
+answer(solution, result([4, 8], [4, 4, 8])).

package/conformance/expected/extension/046_bounded_subset.out

@@ -0,0 +1,5 @@
+answer(selection, result([a, b], 9, 5, 3)).
+answer(selection, result([a], 5, 3, 1)).
+answer(selection, result([b], 4, 2, 2)).
+answer(selection, result([c], 7, 5, 3)).
+answer(selection, result([], 0, 0, 0)).

package/examples/access-control-policy.pl

@@ -4,10 +4,12 @@
 % finite logical conditions.  The universal allOf/noneOf checks use negation
 % as failure over bound policy facts.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(policy, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 policy_request(test1, policy_x).
 has(test1, claim_a).
 has(test1, claim_b).
@@ -19,6 +21,7 @@ allOf(policy_x, claim_b).
 anyOf(policy_x, claim_c).
 noneOf(policy_x, claim_d).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 passes_all_of(Request, Policy) :-
   policy_request(Request, Policy),
   policy(Policy),

package/examples/ackermann.pl

@@ -2,8 +2,11 @@
 % The two-argument entry point follows the Eyeling encoding:
 %   ackermann(X, Y) = hyper(X, Y + 3, 2) - 3.
 
+% 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

@@ -3,16 +3,19 @@
 % Is the age of a person above some duration?
 
 % 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,15 +1,22 @@
 % 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.
 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.
 value(nativeMath, X) :- add(0.125, 0.875, X).
 ok(nativeCompare, true) :- lt(2, 3).
 ok(nativeString, true) :- matches("scoped retail insight", "retail|medical").
 tail(nativeList, Tail) :- rest([a, b, c], Tail).
 
+% These names are just user data; eyelang does not give them special meaning.
 example_label(vocabularyExample, "vocabulary names are ordinary predicate names").
 label(vocabularyExample, Text) :- example_label(vocabularyExample, Text).

package/examples/alignment-demo.pl

@@ -4,6 +4,7 @@
 % broader/narrower alignments, their transitive closure, the reflexive
 % narrower-or-equal relation, and the concepts that roll up to ref_car.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(broader, 2).
 materialize(narrower, 2).
 materialize(broaderTransitive, 2).
@@ -11,6 +12,7 @@ materialize(narrowerTransitive, 2).
 materialize(narrowerOrEqualOf, 2).
 materialize(rollsUpTo, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 concept(ref_car).
 concept(tel_car).
 concept(tel_heavy_vehicle).
@@ -22,6 +24,7 @@ assertedBroader(tel_heavy_vehicle, ref_car).
 assertedBroader(anpr_vehicle_with_plate, ref_car).
 assertedNarrower(anpr_vehicle_with_plate, anpr_passenger_car).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 broader(X, Y) :- assertedBroader(X, Y).
 broader(X, Y) :- assertedNarrower(Y, X).
 

package/examples/allen-interval-calculus.pl

@@ -4,11 +4,13 @@
 % The input interval table is a list of records, showing how tabular data can
 % stay scoped as one term instead of many unrelated global start/end facts.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(start, 2).
 materialize(end, 2).
 materialize(duration, 2).
 materialize(statement, 3).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 interval_table([
   interval(a, 10, 12),
   interval(b, 13, 15),
@@ -23,6 +25,7 @@ interval_table([
   interval(k, 13, 14)
 ]).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 interval(I) :- interval_table(Table), member(interval(I, _Start, _End), Table).
 start(I, Start) :- interval_table(Table), member(interval(I, Start, _End), Table).
 end(I, End) :- interval_table(Table), member(interval(I, _Start, End), Table).

package/examples/ancestor.pl

@@ -1,14 +1,21 @@
 % 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.
 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).
 
+% Recursive case: walk one parent edge and continue through the chain.
 ancestor(X, Z) :-
   parent(X, Y),
   ancestor(Y, Z).

package/examples/animal.pl

@@ -3,13 +3,16 @@
 % The Eyelet source uses Unicode predicate names; this eyelang version keeps the
 % same tiny inheritance idea with plain vocabulary names.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(type, 2).
 materialize(subclassOf, 2).
 materialize(succeeds, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 human(joe).
 animal(human).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 animal(X) :- human(X).
 
 type(joe, human) :- human(joe).

package/examples/annotation.pl

@@ -3,17 +3,20 @@
 % The program keeps the annotation as data and derives visible relations from it.
 % Formula members become default output only when explicit rules project them.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(name, 2).
 materialize(log_nameOf, 2).
 materialize(statedBy, 2).
 materialize(recorded, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 annotation(t, (
   name(a, "Alice"),
   statedBy(t, bob),
   recorded(t, "2021-07-07")
 )).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 name(S, O) :-
   annotation(_T, Formula),
   formula_binary(Formula, S, name, O).

package/examples/auroracare.pl

@@ -3,6 +3,7 @@
 % translation materializes the policy decisions, reasons, traces, and ARC-style
 % check values as ordinary relation output.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(label, 2).
 materialize(description, 2).
 materialize(careTeamLinked, 2).
@@ -24,9 +25,11 @@ materialize(checkC8, 2).
 materialize(checkC9, 2).
 materialize(checkC10Text, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 caseName(case, "auroracare").
 question(case, "For each AuroraCare scenario, should the PDP permit or deny the requested use of health data, and why?").
 
+% Policies: primary care, quality improvement, research, and an explicit denial.
 policyUid(policyPrimary, "urn:policy:primary-care-001").
 purposeAllowed(policyPrimary, primaryCareManagement).
 purposeAllowed(policyPrimary, patientRemoteMonitoring).
@@ -64,6 +67,7 @@ primaryPurpose(auroracare, primaryCareManagement).
 primaryPurpose(auroracare, patientRemoteMonitoring).
 prohibitedPurpose(auroracare, insuranceManagement).
 
+% Scenarios A-G mirror the upstream Markdown report cases.
 scenario(scenarioA).
 outputKey(scenarioA, out010A).
 scenario_label(scenarioA, "A – Primary care visit").
@@ -145,6 +149,7 @@ environment(scenarioG, "secure_env").
 category(scenarioG, patientSummary).
 category(scenarioG, labResults).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 label(S, Label) :- scenario_label(S, Label).
 description(S, Description) :- scenario_description(S, Description).
 
@@ -195,9 +200,11 @@ careTeamLinked(S, true) :- care_team_linked(S).
 subjectOptIn(S, true) :- subject_opt_in(S).
 subjectOptOut(S, true) :- subject_opt_out(S).
 
+% Permit when a scenario satisfies one of the allowed policy branches.
 decision(S, "PERMIT") :- primary_policy_match(S).
 decision(S, "PERMIT") :- qi_policy_match(S).
 decision(S, "PERMIT") :- research_policy_match(S).
+% Deny branches preserve the reason that will be materialized for the report.
 decision(S, "DENY") :- insurance_prohibition_match(S).
 decision(S, "DENY") :- ai_training_opt_out_match(S).
 decision(scenarioC, "DENY") :- purpose(scenarioC, ensureQualitySafetyHealthcare).
@@ -223,6 +230,7 @@ trace(S, "urn:policy:deny-insurance:deny:odrl:prohibition_matched") :- insurance
 trace(S, "deny:subject_opted_out_ai_training") :- ai_training_opt_out_match(S).
 trace(scenarioC, "urn:policy:qi-2025-aurora:deny:odrl:no_permission_matched") :- purpose(scenarioC, ensureQualitySafetyHealthcare).
 
+% C1-C10 below are the ARC-style checklist lines from the upstream output.
 checkC1(scenarioA, "SKIPPED - not a prohibited purpose") :- decision(scenarioA, "PERMIT").
 checkC2(scenarioA, "OK - clinician") :- decision(scenarioA, "PERMIT").
 checkC3(scenarioA, "OK - care-team linked") :- decision(scenarioA, "PERMIT").

package/examples/backward.pl

@@ -1,9 +1,12 @@
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(isIndeedMoreInterestingThan, 2).
 
+% 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.
 
+% 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/basic-monadic.pl

@@ -8,8 +8,10 @@
 % EYE reasoning/basic-monadic/10tt_answer.n3 in cardinality and content
 % after translating N3 statements to eyelang relation terms.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(cycle, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 edge(i30, i12, i33).
 edge(i61, i29, i42).
 edge(i57, i46, i87).
@@ -10011,6 +10013,6 @@ edge(i18, i75, i36).
 edge(i48, i89, i48).
 edge(i26, i42, i54).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 cycle(R, Cycle) :-
   fixed_length_cycle(edge, 10, R, Cycle).
-

package/examples/bayes-diagnosis.pl

@@ -4,6 +4,7 @@
 % points, so this example is comparable with examples/output/bayes-diagnosis.n3
 % in the Eyeling repository.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(scores, 2).
 materialize(evidenceTotal, 2).
 materialize(result, 2).
@@ -11,6 +12,7 @@ materialize(disease, 2).
 materialize(unnormalized, 2).
 materialize(posterior, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 disease(covid19).
 disease(influenza).
 disease(allergicRhinitis).
@@ -53,6 +55,7 @@ evidence([
   ev(shortBreath, true)
 ]).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 factor(Disease, Symptom, true, P) :- p_given(Disease, Symptom, P).
 factor(Disease, Symptom, false, Q) :-
   p_given(Disease, Symptom, P),

package/examples/bayes-therapy.pl

@@ -1,5 +1,6 @@
 % 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.
 materialize(diseases, 2).
 materialize(therapies, 2).
 materialize(evidence, 2).
@@ -12,6 +13,7 @@ materialize(expectedAdverse, 2).
 materialize(utility, 2).
 materialize(recommendedTherapy, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(scores_for, 2).
 memoize(likelihood, 3).
 memoize(expected_success, 2).
@@ -81,6 +83,7 @@ adverse(supportiveCare, 0.01).
 benefit_weight(10).
 harm_weight(3).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 factor(Disease, ev(Symptom, true), P) :- p_given(Disease, Symptom, P).
 factor(Disease, ev(Symptom, false), Q) :-
   p_given(Disease, Symptom, P),

package/examples/beam-deflection.pl

@@ -2,18 +2,21 @@
 %
 % The tip deflection for a point load at the free end is F*L^3/(3*E*I).
 
+% 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/blocks-world-planning.pl

@@ -4,11 +4,13 @@
 % are sorted lists of on(Block, Support) facts so equality and visited-state
 % checks are purely structural.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(status, 2).
 materialize(plan, 2).
 materialize(finalState, 2).
 materialize(blockCount, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 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)]).
 
@@ -19,6 +21,7 @@ block(d).
 block(e).
 
 support(table, _State).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 support(Block, State) :-
   block(Block),
   member(on(Block, _Below), State).

package/examples/bmi.pl

@@ -7,6 +7,7 @@
 % For reproducibility and documentation only; not medical advice.
 
 % Editable metric input.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(unitSystem, 2).
 materialize(weight, 2).
 materialize(height, 2).
@@ -39,6 +40,7 @@ materialize(result, 2).
 materialize(healthyWeightRangeKg, 2).
 materialize(checkPassed, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 unitSystem(input, metric).
 weight(input, 72.0).
 height(input, 178.0).
@@ -49,6 +51,7 @@ height(input, 178.0).
 % height(input, 70.08).
 
 % Normalization and BMI calculation.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 weightKg(case, W) :-
   unitSystem(input, metric),
   weight(input, W).

package/examples/braking-safety-worlds.pl

@@ -3,11 +3,13 @@
 % Four simplified models classify the same road scenarios. The example is not a
 % real safety calculator; it demonstrates rule-level model comparison.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(safeInWorld, 2).
 materialize(riskyInWorld, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 scenario(city_dry, 13.9, 0.8, 40.0).
 scenario(highway_dry_short_gap, 27.8, 0.8, 60.0).
 scenario(city_wet, 13.9, 0.4, 40.0).
@@ -18,6 +20,7 @@ world(w1, "simplified braking-only rule without reaction time").
 world(w2, "naive dry-road friction assumption").
 world(w3, "cautious factor over the physics model").
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 stop_distance(Scenario, w0, Distance) :-
   scenario(Scenario, V, Mu, Avail),
   mul(V, 1.0, Reaction),