eyelang 1.5.2 → 1.5.4

package/examples/flandor.pl

@@ -0,0 +1,296 @@
+% Flandor insight-economy case adapted from Eyeling flandor.n3.
+% The original N3 renders a Markdown ARC report.  This eyelang translation keeps
+% the neutral insight, policy envelope, authorization, package choice, and checks
+% as materialized relation output.
+
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
+materialize(caseName, 2).
+materialize(regionName, 2).
+materialize(metric, 2).
+materialize(activeNeedCount, 2).
+materialize(activeNeedThreshold, 2).
+materialize(recommendedPackageName, 2).
+materialize(budgetCapMEUR, 2).
+materialize(packageCostMEUR, 2).
+materialize(envelopeExpiresAt, 2).
+materialize(workerCoverage, 2).
+materialize(gridReliefMW, 2).
+materialize(outcome, 2).
+materialize(target, 2).
+materialize(reason, 2).
+materialize(alg, 2).
+materialize(payloadHashSHA256, 2).
+materialize(signatureHMAC, 2).
+materialize(auditEntries, 2).
+materialize(filesWritten, 2).
+materialize(allChecksPass, 2).
+materialize(exportWeakness, 2).
+materialize(skillsStrain, 2).
+materialize(gridStress, 2).
+materialize(needsRetoolingPulse, 2).
+materialize(derivedFromNeed, 2).
+materialize(signatureVerifies, 2).
+materialize(payloadHashMatches, 2).
+materialize(hmacMatches, 2).
+materialize(minimizationStripsSensitiveTerms, 2).
+materialize(scopeComplete, 2).
+materialize(authorizationAllowed, 2).
+materialize(thresholdReached, 2).
+materialize(packageWithinBudget, 2).
+materialize(packageCoversAllNeeds, 2).
+materialize(dutyTimingConsistent, 2).
+materialize(surveillanceReuseProhibited, 2).
+materialize(filesWrittenExpected, 2).
+materialize(lowestCostEligiblePackageChosen, 2).
+
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Case metadata describes the request, audit window, and expected file writes.
+case_name(case, "flandor").
+question(case, "Is the Flemish Economic Resilience Board allowed to use a neutral macro-economic insight for regional stabilization, and if so which package should it activate for Flanders?").
+expectedFilesWritten(case, 6).
+requestPurpose(case, "regional_stabilization").
+requestAction(case, odrlUse).
+hubCreatedAt(case, "2026-04-08T07:00:00+00:00").
+hubExpiresAt(case, "2026-04-08T19:00:00+00:00").
+boardAuthAt(case, "2026-04-08T09:15:00+00:00").
+boardDutyAt(case, "2026-04-08T18:30:00+00:00").
+files_written(case, 6).
+audit_entries(case, 1).
+
+region_name(flanders, "Flanders").
+observedFirms(signals, 217).
+aggregationLevel(signals, "regional_cluster").
+containsFirmNames(signals, false).
+containsPayrollRows(signals, false).
+
+% Signals are intentionally aggregated: no firm names or payroll rows are present.
+industrialCluster(clusterAntwerp).
+clusterName(clusterAntwerp, "Antwerp chemicals").
+exportOrdersIndex(clusterAntwerp, 84).
+energyIntensity(clusterAntwerp, 92).
+industrialCluster(clusterGhent).
+clusterName(clusterGhent, "Ghent manufacturing").
+exportOrdersIndex(clusterGhent, 87).
+energyIntensity(clusterGhent, 76).
+
+techVacancyRateTenths(labourMarket, 46).
+techVacancyRate(labourMarket, 4.6).
+congestionHours(grid, 19).
+renewableCurtailmentMWh(grid, 240).
+maxMEUR(budget, 140).
+windowName(budget, "Q2 resilience window").
+
+% Candidate packages expose cost and which active needs they cover.
+policyPackage(pkgTrainingOnly).
+packageId(pkgTrainingOnly, "pkg:TRAIN_070").
+packageName(pkgTrainingOnly, "Flanders Skills Sprint").
+costMEUR(pkgTrainingOnly, 70).
+worker_coverage(pkgTrainingOnly, 900).
+grid_relief_mw(pkgTrainingOnly, 0).
+coversSkillsStrain(pkgTrainingOnly, true).
+
+policyPackage(pkgLogisticsOnly).
+packageId(pkgLogisticsOnly, "pkg:PORT_095").
+packageName(pkgLogisticsOnly, "Schelde Trade Buffer").
+costMEUR(pkgLogisticsOnly, 95).
+worker_coverage(pkgLogisticsOnly, 300).
+grid_relief_mw(pkgLogisticsOnly, 10).
+coversExportWeakness(pkgLogisticsOnly, true).
+
+policyPackage(pkgFlandor).
+packageId(pkgFlandor, "pkg:RET_FLEX_120").
+packageName(pkgFlandor, "Flandor Retooling Pulse").
+costMEUR(pkgFlandor, 120).
+worker_coverage(pkgFlandor, 1200).
+grid_relief_mw(pkgFlandor, 85).
+coversExportWeakness(pkgFlandor, true).
+coversSkillsStrain(pkgFlandor, true).
+coversGridStress(pkgFlandor, true).
+
+policyPackage(pkgFullCorridor).
+packageId(pkgFullCorridor, "pkg:CORRIDOR_165").
+packageName(pkgFullCorridor, "Full Corridor Shock Shield").
+costMEUR(pkgFullCorridor, 165).
+worker_coverage(pkgFullCorridor, 1600).
+grid_relief_mw(pkgFullCorridor, 110).
+coversExportWeakness(pkgFullCorridor, true).
+coversSkillsStrain(pkgFullCorridor, true).
+coversGridStress(pkgFullCorridor, true).
+
+insight(macroInsight).
+id(macroInsight, "https://example.org/insight/flandor").
+insight_metric(macroInsight, "regional_retooling_priority").
+thresholdScore(macroInsight, 3).
+thresholdDisplay(macroInsight, "3 active needs").
+suggestionPolicy(macroInsight, "lowest_cost_package_covering_all_active_needs").
+scopeDevice(macroInsight, "economic-resilience-board").
+scopeEvent(macroInsight, "budget-prep-window").
+region(macroInsight, "Flanders").
+createdAt(macroInsight, "2026-04-08T07:00:00+00:00").
+expiresAt(macroInsight, "2026-04-08T19:00:00+00:00").
+serializedLowercase(macroInsight, "createdat expiresat insight metric regional_retooling_priority region flanders scopedevice economic-resilience-board scopeevent budget-prep-window suggestionpolicy lowest_cost_package_covering_all_active_needs threshold 3").
+
+envelopeInsight(envelope, macroInsight).
+envelopePolicy(envelope, policy).
+envelopeHash(envelope, "10a85e861075bef2a96c01c7f3238735f82b8f368deb62eafcedd1c4b7f7c707").
+permission(policy, odrlUse, macroInsight, "regional_stabilization").
+prohibition(policy, odrlDistribute, macroInsight, "firm_surveillance").
+duty(policy, odrlDelete, "2026-04-08T19:00:00+00:00").
+
+signature_alg(signature, "HMAC-SHA256").
+keyid(signature, "demo-shared-secret").
+created(signature, "2026-04-08T07:00:00+00:00").
+payload_hash_sha256(signature, "10a85e861075bef2a96c01c7f3238735f82b8f368deb62eafcedd1c4b7f7c707").
+display_payload_hash_sha256(signature, "718f5b17d07ab6a95503bc04a1000ddb132409f600659c03d21def81914b780b").
+signature_hmac(signature, "955968ca99a191783bc00cba068128ccb9ff40a5e6114fda13a52c74ee27329e").
+hmacVerificationMode(signature, trustedPrecomputedInput).
+
+reason_value(reasonText, "Secure aggregates from Flanders indicate simultaneous export weakness, technical labour scarcity, and grid congestion. A neutral macro insight is scoped to the economic-resilience board for one budget window only, enabling a temporary package without exposing firm-level books.").
+
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
+caseName(Case, Name) :- case_name(Case, Name).
+regionName(Region, Name) :- region_name(Region, Name).
+metric(Insight, Metric) :- insight_metric(Insight, Metric).
+alg(Signature, Alg) :- signature_alg(Signature, Alg).
+payloadHashSHA256(Signature, Hash) :- display_payload_hash_sha256(Signature, Hash).
+signatureHMAC(Signature, Hmac) :- signature_hmac(Signature, Hmac).
+auditEntries(Case, Count) :- audit_entries(Case, Count).
+filesWritten(Case, Count) :- files_written(Case, Count).
+
+export_weakness(case) :-
+  industrialCluster(Cluster),
+  exportOrdersIndex(Cluster, Index),
+  lt(Index, 90).
+
+skills_strain(case) :-
+  techVacancyRateTenths(labourMarket, Rate),
+  gt(Rate, 39).
+
+grid_stress(case) :-
+  congestionHours(grid, Hours),
+  gt(Hours, 11).
+
+needs_retooling_pulse(case) :-
+  export_weakness(case),
+  skills_strain(case),
+  grid_stress(case).
+
+payload_hash_matches(check) :-
+  envelopeHash(envelope, Digest),
+  payload_hash_sha256(signature, Digest).
+
+signature_verifies(check) :- hmacVerificationMode(signature, trustedPrecomputedInput).
+hmac_matches(check) :-
+  hmacVerificationMode(signature, trustedPrecomputedInput),
+  signature_hmac(signature, "955968ca99a191783bc00cba068128ccb9ff40a5e6114fda13a52c74ee27329e").
+
+minimization_strips_sensitive_terms(check) :-
+  serializedLowercase(macroInsight, Text),
+  not_matches(Text, "salary|payroll|invoice|medical|firmname").
+
+scope_complete(check) :-
+  scopeDevice(macroInsight, _Device),
+  scopeEvent(macroInsight, _Event),
+  expiresAt(macroInsight, _Expiry).
+
+% Authorization combines policy scope, envelope timing, and use permission.
+authorization_allowed(check) :-
+  permission(policy, odrlUse, macroInsight, "regional_stabilization"),
+  boardAuthAt(case, AuthAt),
+  expiresAt(macroInsight, ExpiresAt),
+  le(AuthAt, ExpiresAt).
+
+decision(decision, "Allowed", macroInsight) :- authorization_allowed(check).
+
+% An eligible package must cover every active need and fit under the budget cap.
+eligible_package(Pkg) :-
+  needs_retooling_pulse(case),
+  maxMEUR(budget, Max),
+  policyPackage(Pkg),
+  costMEUR(Pkg, Cost),
+  coversExportWeakness(Pkg, true),
+  coversSkillsStrain(Pkg, true),
+  coversGridStress(Pkg, true),
+  le(Cost, Max).
+
+lower_cost_eligible_package(Cost) :-
+  eligible_package(Other),
+  costMEUR(Other, OtherCost),
+  lt(OtherCost, Cost).
+
+% The recommendation is the lowest-cost eligible package.
+recommended_package(case, Pkg) :-
+  eligible_package(Pkg),
+  costMEUR(Pkg, Cost),
+  not(lower_cost_eligible_package(Cost)).
+
+package_within_budget(check) :-
+  recommended_package(case, Pkg),
+  costMEUR(Pkg, Cost),
+  maxMEUR(budget, Max),
+  le(Cost, Max).
+
+package_covers_all_needs(check) :-
+  recommended_package(case, Pkg),
+  coversExportWeakness(Pkg, true),
+  coversSkillsStrain(Pkg, true),
+  coversGridStress(Pkg, true).
+
+duty_timing_consistent(check) :-
+  boardDutyAt(case, DutyAt),
+  expiresAt(macroInsight, ExpiresAt),
+  le(DutyAt, ExpiresAt).
+
+surveillance_reuse_prohibited(check) :- prohibition(policy, odrlDistribute, macroInsight, "firm_surveillance").
+files_written_expected(check) :- files_written(case, 6).
+threshold_reached(check) :- export_weakness(case), skills_strain(case), grid_stress(case).
+lowest_cost_eligible_package_chosen(check) :- recommended_package(case, _Pkg).
+
+all_checks_pass(result) :-
+  signature_verifies(check),
+  payload_hash_matches(check),
+  minimization_strips_sensitive_terms(check),
+  scope_complete(check),
+  authorization_allowed(check),
+  package_within_budget(check),
+  package_covers_all_needs(check),
+  duty_timing_consistent(check),
+  surveillance_reuse_prohibited(check),
+  files_written_expected(check).
+
+exportWeakness(case, true) :- export_weakness(case).
+skillsStrain(case, true) :- skills_strain(case).
+gridStress(case, true) :- grid_stress(case).
+needsRetoolingPulse(case, true) :- needs_retooling_pulse(case).
+derivedFromNeed(case, "regional_retooling_and_flexibility") :- needs_retooling_pulse(case).
+activeNeedCount(answer, 3) :- threshold_reached(check).
+activeNeedThreshold(answer, 3) :- thresholdScore(macroInsight, 3).
+recommendedPackageName(answer, Name) :- recommended_package(case, Pkg), packageName(Pkg, Name).
+budgetCapMEUR(answer, Max) :- maxMEUR(budget, Max).
+packageCostMEUR(answer, Cost) :- recommended_package(case, Pkg), costMEUR(Pkg, Cost).
+envelopeExpiresAt(answer, Time) :- expiresAt(macroInsight, Time).
+workerCoverage(why, Workers) :- recommended_package(case, Pkg), worker_coverage(Pkg, Workers).
+gridReliefMW(why, MW) :- recommended_package(case, Pkg), grid_relief_mw(Pkg, MW).
+outcome(decision, Outcome) :- decision(decision, Outcome, _Target).
+target(decision, Target) :- decision(decision, _Outcome, Target).
+allChecksPass(result, true) :- all_checks_pass(result).
+signatureVerifies(check, true) :- signature_verifies(check).
+payloadHashMatches(check, true) :- payload_hash_matches(check).
+hmacMatches(check, true) :- hmac_matches(check).
+minimizationStripsSensitiveTerms(check, true) :- minimization_strips_sensitive_terms(check).
+scopeComplete(check, true) :- scope_complete(check).
+authorizationAllowed(check, true) :- authorization_allowed(check).
+thresholdReached(check, true) :- threshold_reached(check).
+packageWithinBudget(check, true) :- package_within_budget(check).
+packageCoversAllNeeds(check, true) :- package_covers_all_needs(check).
+dutyTimingConsistent(check, true) :- duty_timing_consistent(check).
+surveillanceReuseProhibited(check, true) :- surveillance_reuse_prohibited(check).
+filesWrittenExpected(check, true) :- files_written_expected(check).
+lowestCostEligiblePackageChosen(check, true) :- lowest_cost_eligible_package_chosen(check).
+
+reason(whyExportWeakness, "Export weakness is active because at least one cluster has exportOrdersIndex < 90 (Antwerp chemicals=84, Ghent manufacturing=87).") :- export_weakness(case).
+reason(whySkillsStrain, "Skills strain is active because technical vacancy rate is 4.6% (threshold > 3.9%).") :- skills_strain(case).
+reason(whyGridStress, "Grid stress is active because congestion hours = 19 (threshold > 11).") :- grid_stress(case).
+reason(whyRecommendationPolicy, "The recommendation policy is \"lowest_cost_package_covering_all_active_needs\", so the cheapest package that covers all active needs within budget is selected.") :- recommended_package(case, _Pkg).
+reason(whySelectedPackage, "Selected package \"Flandor Retooling Pulse\" covers export=true, skills=true, grid=true, cost=€120M.") :- recommended_package(case, pkgFlandor).
+reason(whyUsage, "Usage is permitted only for purpose \"regional_stabilization\" and the envelope expires at 2026-04-08T19:00:00+00:00.") :- authorization_allowed(check).

package/examples/floating-point.pl

@@ -1,12 +1,16 @@
 % Floating-point arithmetic and comparisons.
 % Integer-only operands continue to use arbitrary-size integer arithmetic.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(value, 2).
 materialize(than, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Floating-point constants can be mixed with integer constants in built-ins.
 sample(roomC, 21.5).
 sample(targetC, 19.25).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 value(sum, X) :- add(1.5, 2.25, X).
 value(difference, X) :- sub(10.0, 3.125, X).
 value(product, X) :- mul(2.5, 4.0, X).
@@ -15,4 +19,5 @@ value(sqrtByPower, X) :- pow(9.0, 0.5, X).
 value(mathSum, X) :- add(0.125, 0.875, X).
 value(mathProduct, X) :- mul(6.0, 0.5, X).
 than(warmer, targetC) :- sample(roomC, R), sample(targetC, T), gt(R, T).
+% Boolean-like conclusions remain ordinary atoms.
 value(comfortable, true) :- sample(roomC, R), ge(R, 21.0), le(R, 22.0).

package/examples/four-color-map.pl

@@ -4,10 +4,12 @@
 % four colours. This eyelang version keeps the same map/assignment shape and adds
 % a rule-level validation layer that rejects equal colours across borders.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(color, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 country(belgium). country(netherlands). country(luxemburg). country(france).
 country(germany). country(italy). country(denmark). country(ireland).
 country(greece). country(spain). country(portugal). country(austria).
@@ -36,6 +38,7 @@ border(estonia, latvia).
 border(latvia, lithuania).
 border(bulgaria, romania).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 adjacent(A, B) :- border(A, B).
 adjacent(A, B) :- border(B, A).
 

package/examples/fundamental-theorem-arithmetic.pl

@@ -2,6 +2,7 @@
 % Compute a prime factorization by repeated smallest-divisor decomposition,
 % then check product reconstruction and primality of the distinct factors.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(n, 2).
 materialize(factorsSmallest, 2).
 materialize(factorsLargest, 2).
@@ -12,10 +13,12 @@ materialize(distinctPrimeCount, 2).
 materialize(smallestPrimeFactor, 2).
 materialize(largestPrimeFactor, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 case(fta, 202692987).
 expected_factors(fta, [3, 3, 7, 829, 3881]).
 
 % A divides B in positive integers.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 divides(A, B) :-
   gt(A, 0),
   gt(B, 0),

package/examples/gcd-bezout-identity.pl

@@ -4,11 +4,13 @@
 % Each case derives gcd(a,b), coefficients s,t, and validation checks for
 % a*s + b*t = gcd(a,b) and divisibility.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(gcd, 2).
 materialize(bezoutCoefficients, 2).
 materialize(check, 2).
 materialize(status, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 case(c1, 48, 18).
 case(c2, 101, 462).
 case(c3, 0, 5).
@@ -16,6 +18,7 @@ case(c4, 270, 192).
 case(c5, -27, 36).
 case(c6, 123456, 7890).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 answer(Case, Gcd, S, T) :-
   case(Case, A, B),
   extended_gcd(A, B, Gcd, S, T).

package/examples/gd-step-certified.pl

@@ -1,5 +1,6 @@
 % Memoize interval computations reused across width, midpoint, gradient, step,
 % objective, and contraction report relations.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(eta, 2).
 materialize(etaLeHalf, 2).
 materialize(xBounds, 2).
@@ -10,6 +11,7 @@ materialize(stepBounds, 2).
 materialize(objectiveBounds, 2).
 materialize(widthContractsAt, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(x_bounds, 3).
 memoize(width, 2).
 memoize(g_bounds, 3).
@@ -23,6 +25,7 @@ memoize(f_upper, 2).
 
 max_k(10).
 target(1.0).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 eta(Eta) :- div(1.0, 5, Eta).
 x_bounds(0, 0.0, 2.0).
 

package/examples/gdpr-compliance.pl

@@ -1,8 +1,11 @@
 % GDPR-style compliance check: purpose, basis, minimisation, safeguards, and export.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% case_alpha is intended to pass; case_beta is intentionally incomplete.
 processing(case_alpha).
 processing(case_beta).
 
@@ -25,6 +28,8 @@ safeguard(case_beta, encryption).
 third_country_transfer(case_beta).
 adequacy_decision(case_alpha).
 
+% Compliance is decomposed into reusable checks so reasons can be reported.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 has_required_basis(Case) :- legal_basis(Case, explicit_consent).
 has_required_basis(Case) :- legal_basis(Case, medical_care).
 
@@ -43,6 +48,7 @@ compliant(Case) :-
   has_health_safeguards(Case),
   transfer_ok(Case).
 
+% Individual failure rules explain why a case is noncompliant.
 noncompliance_reason(Case, missing_legal_basis) :-
   processing(Case),
   not(has_required_basis(Case)).

package/examples/goldbach-1000.pl

@@ -1,8 +1,10 @@
 % Goldbach pairs up to 1000.
 % Prime numbers are input data; the rule below derives all Goldbach pairs.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(isPrime, 2).
 materialize(goldbachOk, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 prime(2).
 prime(3).
 prime(5).
@@ -172,6 +174,7 @@ prime(983).
 prime(991).
 prime(997).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 even_between_4_1000(N) :- between(4, 1000, N), mod(N, 2, 0).
 
 isPrime(N, true) :-

package/examples/good-cobbler.pl

@@ -3,9 +3,12 @@
 % The Eyeling result is a quoted assertion saying that joe is a good Cobbler.
 % Here the quoted assertion is represented as an eyelang term.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(is, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 assertedIs(joe, good(cobbler)).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 is(test, is(X, good(Y))) :-
   assertedIs(X, good(Y)).

package/examples/gps.pl

@@ -1,5 +1,6 @@
 % Memoize route paths because the same candidate routes are checked repeatedly
 % for explanation and verification relations.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(recommendedRoute, 2).
 materialize(outcome, 2).
 materialize(statement, 3).
@@ -12,6 +13,7 @@ materialize(comfort, 2).
 materialize(selectedRoute, 2).
 materialize(comparison, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(path, 7).
 memoize(traveller_path, 6).
 
@@ -35,6 +37,7 @@ map_graph(mapBE, (
   gps_description(mapBE, description(location(S, brugge), true, location(S, oostende), drive_brugge_oostende, 900.0, 0.004, 0.98, 1.0))
 )).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 case_statement(S, P, O) :-
   case_graph(caseGraph, Formula),
   formula_binary(Formula, S, P, O).

package/examples/graph-reachability.pl

@@ -3,9 +3,11 @@
 % The original uses Prolog negation and member/2 to avoid revisiting nodes.
 % eyelang expresses the same finite search with not(member(...)).
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(reachable, 2).
 materialize(not_reachable, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 edge(a, b).
 edge(a, c).
 edge(b, d).
@@ -15,6 +17,7 @@ edge(e, f).
 edge(f, g).
 
 reachable(Node, Node, _Visited).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 reachable(Start, Goal, Visited) :-
   edge(Start, Next),
   not(member(Next, Visited)),

package/examples/gray-code-counter.pl

@@ -1,8 +1,11 @@
 % Gray-code counter adapted from Eyeling gray-code-counter.n3 and the
 % Clause and Effect example referenced there.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(isgcc, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Boolean gates are truth tables; the circuit rules compose them.
 and(0, 0, 0). and(0, 1, 0). and(1, 0, 0). and(1, 1, 1).
 or(0, 0, 0).  or(0, 1, 1).  or(1, 0, 1).  or(1, 1, 1).
 inv(0, 1). inv(1, 0).
@@ -10,6 +13,7 @@ inv(0, 1). inv(1, 0).
 dff(D, 0, Q, Q).
 dff(D, 1, _Q, D).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 neta(A, B, Q) :-
   and(A, B, T1),
   inv(A, NA),
@@ -26,6 +30,7 @@ netb(A, B, C, Q1, Q2) :-
   or(T1, T2, Q1),
   or(T2, T3, Q2).
 
+% One clock step computes D inputs, then updates the three flip-flops.
 gcc(C, [Qa, Qb, Qc], [Za, Zb, Zc]) :-
   netb(Qa, Qb, Qc, D1, D2),
   neta(Qa, Qb, D3),
@@ -33,6 +38,7 @@ gcc(C, [Qa, Qb, Qc], [Za, Zb, Zc]) :-
   dff(D2, C, Qb, Zb),
   dff(D3, C, Qc, Zc).
 
+% testgcc/3 runs the circuit over a list of clock inputs.
 testgcc([], _State, []).
 testgcc([C|Cs], State, [Next|Rest]) :-
   gcc(C, State, Next),

package/examples/greatest-lower-bound-uniqueness.pl

@@ -1,5 +1,7 @@
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(sameGreatestLowerBound, 4).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Greatest-lower-bound uniqueness example adapted from Eyeling
 % greatest-lower-bound-uniqueness.n3.
 % If M and N are both greatest lower bounds of A and B, each is below the other;
@@ -8,6 +10,7 @@ materialize(sameGreatestLowerBound, 4).
 glbOf(g1, a, b).
 glbOf(g2, a, b).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 lowerBoundOf(M, A, B) :- glbOf(M, A, B).
 
 leq(L, M) :-

package/examples/group-inverse-uniqueness.pl

@@ -3,13 +3,16 @@
 % The output mirrors the Eyeling golden result shape:
 % sameInverse(x, i, j) and sameInverse(x, j, i).
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(sameInverse, 3).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 element(e).
 element(x).
 element(i).
 element(j).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 op(e, X, X) :- element(X).
 op(X, e, X) :- element(X).
 op(i, x, e).

package/examples/hamiltonian-cycle.pl

@@ -5,11 +5,13 @@
 % cycle directions are still distinct, so the count is for cycles from a fixed
 % start in traversal order.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(status, 2).
 materialize(witness, 2).
 materialize(vertexCount, 2).
 materialize(cycleCountFromA, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 edge(a, b).
 edge(a, f).
 edge(a, g).
@@ -28,6 +30,7 @@ edge(e, f).
 edge(f, g).
 edge(g, h).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 adjacent(X, Y) :- edge(X, Y).
 adjacent(X, Y) :- edge(Y, X).
 

package/examples/hamiltonian-path.pl

@@ -4,9 +4,11 @@
 % vertex set directly and derives every path that visits each vertex exactly
 % once.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(hasHamiltonianPath, 2).
 materialize(hamiltonianPath, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(adjacent, 2).
 
 edge(v1, v2).
@@ -21,6 +23,7 @@ edge(v3, v6).
 edge(v4, v5).
 edge(v4, v6).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 adjacent(V, U) :- edge(V, U).
 adjacent(V, U) :- edge(U, V).
 

package/examples/hamming-code.pl

@@ -3,6 +3,7 @@
 % The received word has one corrupted bit. Syndrome bits identify the bad
 % position, then the corrected codeword and decoded payload are derived.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(syndrome, 2).
 materialize(errorBit, 2).
 materialize(correctedCodeword, 2).
@@ -10,6 +11,7 @@ materialize(decodedPayload, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 received_bit(packet1, 1, 1).
 received_bit(packet1, 2, 0).
 received_bit(packet1, 3, 1).
@@ -21,6 +23,7 @@ received_bit(packet1, 7, 0).
 flip(0, 1).
 flip(1, 0).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 parity4(A, B, C, D, Parity) :-
   add(A, B, AB),
   add(AB, C, ABC),

package/examples/hanoi.pl

@@ -1,11 +1,14 @@
 % Towers of Hanoi adapted from Eyeling hanoi.n3.
 % Output is the complete list of moves for size 3.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(answer, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(hanoi, 5).
 
 hanoi(0, _From, _To, _Via, []).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 hanoi(N, From, To, Via, Moves) :-
   gt(N, 0),
   sub(N, 1, N1),