deriva 0.0.14 → 0.0.16

package/README.md

@@ -51,6 +51,22 @@ npm link
 deriva --version
 ```
 
+## STEM showcase: evidence-backed diagnosis
+
+The spacecraft battery example combines sensor telemetry, the physical relation
+`P = I²R`, engineering limits, redundant measurements, and causal rules to
+derive a diagnosis and safety action:
+
+```bash
+node bin/deriva.js examples/spacecraft-battery-diagnosis.pl
+node bin/deriva.js -p examples/spacecraft-battery-diagnosis.pl
+```
+
+The normal output reports computed metrics, a thermal-runaway precursor, and an
+`isolate_and_cool` action. With `-p`, every conclusion carries machine-readable
+evidence back to telemetry facts, arithmetic operations, threshold comparisons,
+and the independent temperature channel.
+
 ## JavaScript API
 
 ```js

package/docs/guide.md

@@ -416,6 +416,7 @@ Use `holds/2` when you want to match the member term directly, for example `name
 | [`hamming-code.pl`](../examples/hamming-code.pl) | Corrects a single-bit Hamming word. | [`output/hamming-code.pl`](../examples/output/hamming-code.pl) |
 | [`hanoi.pl`](../examples/hanoi.pl) | Derives the Towers of Hanoi moves. | [`output/hanoi.pl`](../examples/output/hanoi.pl) |
 | [`heat-loss.pl`](../examples/heat-loss.pl) | Computes conductive heat loss. | [`output/heat-loss.pl`](../examples/output/heat-loss.pl) |
+| [`herbrand-semantics.pl`](../examples/herbrand-semantics.pl) | Shows how unique names and free constructors make symbolic identity predictable. | [`output/herbrand-semantics.pl`](../examples/output/herbrand-semantics.pl) |
 | [`herbrand-witnesses.pl`](../examples/herbrand-witnesses.pl) | Represents existential-style consequences as stable Herbrand witness terms. | [`output/herbrand-witnesses.pl`](../examples/output/herbrand-witnesses.pl) |
 | [`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) |
@@ -478,6 +479,7 @@ Use `holds/2` when you want to match the member term directly, for example `name
 | [`socket-age.pl`](../examples/socket-age.pl) | Shows socket-declared age reasoning inputs and plugs. | [`output/socket-age.pl`](../examples/output/socket-age.pl) |
 | [`socket-family.pl`](../examples/socket-family.pl) | Shows socket-declared family-source inputs and ancestry rules. | [`output/socket-family.pl`](../examples/output/socket-family.pl) |
 | [`socrates.pl`](../examples/socrates.pl) | Derives that Socrates is mortal. | [`output/socrates.pl`](../examples/output/socrates.pl) |
+| [`spacecraft-battery-diagnosis.pl`](../examples/spacecraft-battery-diagnosis.pl) | Combines telemetry, resistive-heating physics, thresholds, and redundant sensing into an evidence-backed diagnosis and safety action. | [`output/spacecraft-battery-diagnosis.pl`](../examples/output/spacecraft-battery-diagnosis.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) |

package/docs/language-reference.md

@@ -440,6 +440,11 @@ different(alice, bob).
 different(ticket(alice), ticket(bob)).
 ```
 
+The complete runnable example, normal output, and proof output are available as
+[`examples/herbrand-semantics.pl`](../examples/herbrand-semantics.pl),
+[`examples/output/herbrand-semantics.pl`](../examples/output/herbrand-semantics.pl),
+and [`examples/proof/herbrand-semantics.pl`](../examples/proof/herbrand-semantics.pl).
+
 In an unrestricted Tarskian interpretation, the constants `alice` and `bob`
 may denote the same domain element unless a distinctness axiom says otherwise.
 Even if they denote different elements, the function denoted by `ticket` need

package/examples/herbrand-semantics.pl

@@ -0,0 +1,16 @@
+% Herbrand terms denote themselves: distinct names and constructor applications
+% remain distinct without extra unique-name or free-constructor axioms.
+
+% Output declaration: materialize/2 selects the relation written to this
+% example's golden output.
+materialize(different, 2).
+
+% Under unrestricted Tarskian semantics, alice and bob could denote the same
+% element. In Deriva's Herbrand universe, their different syntax is enough.
+different(alice, bob) :-
+  neq(alice, bob).
+
+% A general Tarskian function need not be injective. Herbrand compound terms
+% are free constructors, so different arguments produce different terms.
+different(ticket(alice), ticket(bob)) :-
+  neq(ticket(alice), ticket(bob)).

package/examples/output/herbrand-semantics.pl

@@ -0,0 +1,2 @@
+different(alice, bob).
+different(ticket(alice), ticket(bob)).

package/examples/output/spacecraft-battery-diagnosis.pl

@@ -0,0 +1,4 @@
+metric(bp1, thermal_margin_c, -18.0).
+metric(bp1, resistive_heating_w, 16.0).
+diagnosis(bp1, thermal_runaway_precursor).
+action(bp1, isolate_and_cool).

package/examples/proof/herbrand-semantics.pl

@@ -0,0 +1,30 @@
+different(alice, bob).
+why(
+  different(alice, bob),
+  proof(
+    goal(different(alice, bob)),
+    by(rule("herbrand-semantics.pl", clause(2))),
+    uses([
+      proof(
+        goal(neq(alice, bob)),
+        by(builtin(neq, 2))
+      )
+    ])
+  )
+).
+
+different(ticket(alice), ticket(bob)).
+why(
+  different(ticket(alice), ticket(bob)),
+  proof(
+    goal(different(ticket(alice), ticket(bob))),
+    by(rule("herbrand-semantics.pl", clause(3))),
+    uses([
+      proof(
+        goal(neq(ticket(alice), ticket(bob))),
+        by(builtin(neq, 2))
+      )
+    ])
+  )
+).
+

package/examples/proof/spacecraft-battery-diagnosis.pl

@@ -0,0 +1,300 @@
+metric(bp1, thermal_margin_c, -18.0).
+why(
+  metric(bp1, thermal_margin_c, -18.0),
+  proof(
+    goal(metric(bp1, thermal_margin_c, -18.0)),
+    by(rule("spacecraft-battery-diagnosis.pl", clause(14))),
+    bindings([binding("Pack", bp1), binding("Margin", -18.0), binding("Maximum", 60.0), binding("Temperature", 78.0)]),
+    uses([
+      proof(
+        goal(limit(max_safe_temperature_c, 60.0)),
+        by(fact("spacecraft-battery-diagnosis.pl", clause(10)))
+      ),
+      proof(
+        goal(telemetry(bp1, temperature_c, 78.0)),
+        by(fact("spacecraft-battery-diagnosis.pl", clause(4)))
+      ),
+      proof(
+        goal(sub(60.0, 78.0, -18.0)),
+        by(builtin(sub, 3))
+      )
+    ])
+  )
+).
+
+metric(bp1, resistive_heating_w, 16.0).
+why(
+  metric(bp1, resistive_heating_w, 16.0),
+  proof(
+    goal(metric(bp1, resistive_heating_w, 16.0)),
+    by(rule("spacecraft-battery-diagnosis.pl", clause(15))),
+    bindings([binding("Pack", bp1), binding("Heating", 16.0), binding("Current", 32.0), binding("Resistance", 0.015625), binding("CurrentSquared", 1024.0)]),
+    uses([
+      proof(
+        goal(telemetry(bp1, current_a, 32.0)),
+        by(fact("spacecraft-battery-diagnosis.pl", clause(6)))
+      ),
+      proof(
+        goal(telemetry(bp1, internal_resistance_ohm, 0.015625)),
+        by(fact("spacecraft-battery-diagnosis.pl", clause(7)))
+      ),
+      proof(
+        goal(mul(32.0, 32.0, 1024.0)),
+        by(builtin(mul, 3))
+      ),
+      proof(
+        goal(mul(1024.0, 0.015625, 16.0)),
+        by(builtin(mul, 3))
+      )
+    ])
+  )
+).
+
+diagnosis(bp1, thermal_runaway_precursor).
+why(
+  diagnosis(bp1, thermal_runaway_precursor),
+  proof(
+    goal(diagnosis(bp1, thermal_runaway_precursor)),
+    by(rule("spacecraft-battery-diagnosis.pl", clause(21))),
+    bindings([binding("Pack", bp1)]),
+    uses([
+      proof(
+        goal(over_temperature(bp1)),
+        by(rule("spacecraft-battery-diagnosis.pl", clause(16))),
+        bindings([binding("Pack", bp1), binding("Temperature", 78.0), binding("Maximum", 60.0)]),
+        uses([
+          proof(
+            goal(telemetry(bp1, temperature_c, 78.0)),
+            by(fact("spacecraft-battery-diagnosis.pl", clause(4)))
+          ),
+          proof(
+            goal(limit(max_safe_temperature_c, 60.0)),
+            by(fact("spacecraft-battery-diagnosis.pl", clause(10)))
+          ),
+          proof(
+            goal(gt(78.0, 60.0)),
+            by(builtin(gt, 2))
+          )
+        ])
+      ),
+      proof(
+        goal(rapid_heating(bp1)),
+        by(rule("spacecraft-battery-diagnosis.pl", clause(17))),
+        bindings([binding("Pack", bp1), binding("Rate", 4.2), binding("Maximum", 1.5)]),
+        uses([
+          proof(
+            goal(telemetry(bp1, temperature_rise_c_per_min, 4.2)),
+            by(fact("spacecraft-battery-diagnosis.pl", clause(5)))
+          ),
+          proof(
+            goal(limit(max_temperature_rise_c_per_min, 1.5)),
+            by(fact("spacecraft-battery-diagnosis.pl", clause(11)))
+          ),
+          proof(
+            goal(gt(4.2, 1.5)),
+            by(builtin(gt, 2))
+          )
+        ])
+      ),
+      proof(
+        goal(cell_imbalance(bp1)),
+        by(rule("spacecraft-battery-diagnosis.pl", clause(18))),
+        bindings([binding("Pack", bp1), binding("Delta", 0.19), binding("Maximum", 0.08)]),
+        uses([
+          proof(
+            goal(telemetry(bp1, cell_delta_v, 0.19)),
+            by(fact("spacecraft-battery-diagnosis.pl", clause(8)))
+          ),
+          proof(
+            goal(limit(max_cell_delta_v, 0.08)),
+            by(fact("spacecraft-battery-diagnosis.pl", clause(12)))
+          ),
+          proof(
+            goal(gt(0.19, 0.08)),
+            by(builtin(gt, 2))
+          )
+        ])
+      ),
+      proof(
+        goal(heating_exceeds_cooling(bp1)),
+        by(rule("spacecraft-battery-diagnosis.pl", clause(19))),
+        bindings([binding("Pack", bp1), binding("Heating", 16.0), binding("Capacity", 12.0)]),
+        uses([
+          proof(
+            goal(metric(bp1, resistive_heating_w, 16.0)),
+            by(rule("spacecraft-battery-diagnosis.pl", clause(15))),
+            bindings([binding("Pack", bp1), binding("Heating", 16.0), binding("Current", 32.0), binding("Resistance", 0.015625), binding("CurrentSquared", 1024.0)]),
+            uses([
+              proof(
+                goal(telemetry(bp1, current_a, 32.0)),
+                by(fact("spacecraft-battery-diagnosis.pl", clause(6)))
+              ),
+              proof(
+                goal(telemetry(bp1, internal_resistance_ohm, 0.015625)),
+                by(fact("spacecraft-battery-diagnosis.pl", clause(7)))
+              ),
+              proof(
+                goal(mul(32.0, 32.0, 1024.0)),
+                by(builtin(mul, 3))
+              ),
+              proof(
+                goal(mul(1024.0, 0.015625, 16.0)),
+                by(builtin(mul, 3))
+              )
+            ])
+          ),
+          proof(
+            goal(cooling_capacity_w(bp1, 12.0)),
+            by(fact("spacecraft-battery-diagnosis.pl", clause(13)))
+          ),
+          proof(
+            goal(gt(16.0, 12.0)),
+            by(builtin(gt, 2))
+          )
+        ])
+      )
+    ])
+  )
+).
+
+action(bp1, isolate_and_cool).
+why(
+  action(bp1, isolate_and_cool),
+  proof(
+    goal(action(bp1, isolate_and_cool)),
+    by(rule("spacecraft-battery-diagnosis.pl", clause(22))),
+    bindings([binding("Pack", bp1)]),
+    uses([
+      proof(
+        goal(diagnosis(bp1, thermal_runaway_precursor)),
+        by(rule("spacecraft-battery-diagnosis.pl", clause(21))),
+        bindings([binding("Pack", bp1)]),
+        uses([
+          proof(
+            goal(over_temperature(bp1)),
+            by(rule("spacecraft-battery-diagnosis.pl", clause(16))),
+            bindings([binding("Pack", bp1), binding("Temperature", 78.0), binding("Maximum", 60.0)]),
+            uses([
+              proof(
+                goal(telemetry(bp1, temperature_c, 78.0)),
+                by(fact("spacecraft-battery-diagnosis.pl", clause(4)))
+              ),
+              proof(
+                goal(limit(max_safe_temperature_c, 60.0)),
+                by(fact("spacecraft-battery-diagnosis.pl", clause(10)))
+              ),
+              proof(
+                goal(gt(78.0, 60.0)),
+                by(builtin(gt, 2))
+              )
+            ])
+          ),
+          proof(
+            goal(rapid_heating(bp1)),
+            by(rule("spacecraft-battery-diagnosis.pl", clause(17))),
+            bindings([binding("Pack", bp1), binding("Rate", 4.2), binding("Maximum", 1.5)]),
+            uses([
+              proof(
+                goal(telemetry(bp1, temperature_rise_c_per_min, 4.2)),
+                by(fact("spacecraft-battery-diagnosis.pl", clause(5)))
+              ),
+              proof(
+                goal(limit(max_temperature_rise_c_per_min, 1.5)),
+                by(fact("spacecraft-battery-diagnosis.pl", clause(11)))
+              ),
+              proof(
+                goal(gt(4.2, 1.5)),
+                by(builtin(gt, 2))
+              )
+            ])
+          ),
+          proof(
+            goal(cell_imbalance(bp1)),
+            by(rule("spacecraft-battery-diagnosis.pl", clause(18))),
+            bindings([binding("Pack", bp1), binding("Delta", 0.19), binding("Maximum", 0.08)]),
+            uses([
+              proof(
+                goal(telemetry(bp1, cell_delta_v, 0.19)),
+                by(fact("spacecraft-battery-diagnosis.pl", clause(8)))
+              ),
+              proof(
+                goal(limit(max_cell_delta_v, 0.08)),
+                by(fact("spacecraft-battery-diagnosis.pl", clause(12)))
+              ),
+              proof(
+                goal(gt(0.19, 0.08)),
+                by(builtin(gt, 2))
+              )
+            ])
+          ),
+          proof(
+            goal(heating_exceeds_cooling(bp1)),
+            by(rule("spacecraft-battery-diagnosis.pl", clause(19))),
+            bindings([binding("Pack", bp1), binding("Heating", 16.0), binding("Capacity", 12.0)]),
+            uses([
+              proof(
+                goal(metric(bp1, resistive_heating_w, 16.0)),
+                by(rule("spacecraft-battery-diagnosis.pl", clause(15))),
+                bindings([binding("Pack", bp1), binding("Heating", 16.0), binding("Current", 32.0), binding("Resistance", 0.015625), binding("CurrentSquared", 1024.0)]),
+                uses([
+                  proof(
+                    goal(telemetry(bp1, current_a, 32.0)),
+                    by(fact("spacecraft-battery-diagnosis.pl", clause(6)))
+                  ),
+                  proof(
+                    goal(telemetry(bp1, internal_resistance_ohm, 0.015625)),
+                    by(fact("spacecraft-battery-diagnosis.pl", clause(7)))
+                  ),
+                  proof(
+                    goal(mul(32.0, 32.0, 1024.0)),
+                    by(builtin(mul, 3))
+                  ),
+                  proof(
+                    goal(mul(1024.0, 0.015625, 16.0)),
+                    by(builtin(mul, 3))
+                  )
+                ])
+              ),
+              proof(
+                goal(cooling_capacity_w(bp1, 12.0)),
+                by(fact("spacecraft-battery-diagnosis.pl", clause(13)))
+              ),
+              proof(
+                goal(gt(16.0, 12.0)),
+                by(builtin(gt, 2))
+              )
+            ])
+          )
+        ])
+      ),
+      proof(
+        goal(corroborated_over_temperature(bp1)),
+        by(rule("spacecraft-battery-diagnosis.pl", clause(20))),
+        bindings([binding("Pack", bp1), binding("Primary", 78.0), binding("Redundant", 76.0), binding("Maximum", 60.0)]),
+        uses([
+          proof(
+            goal(telemetry(bp1, temperature_c, 78.0)),
+            by(fact("spacecraft-battery-diagnosis.pl", clause(4)))
+          ),
+          proof(
+            goal(redundant_telemetry(bp1, temperature_c, 76.0)),
+            by(fact("spacecraft-battery-diagnosis.pl", clause(9)))
+          ),
+          proof(
+            goal(limit(max_safe_temperature_c, 60.0)),
+            by(fact("spacecraft-battery-diagnosis.pl", clause(10)))
+          ),
+          proof(
+            goal(gt(78.0, 60.0)),
+            by(builtin(gt, 2))
+          ),
+          proof(
+            goal(gt(76.0, 60.0)),
+            by(builtin(gt, 2))
+          )
+        ])
+      )
+    ])
+  )
+).
+

package/examples/spacecraft-battery-diagnosis.pl

@@ -0,0 +1,79 @@
+% Evidence-backed spacecraft battery diagnosis.
+%
+% This compact engineering model combines telemetry, derived physical
+% quantities, threshold checks, redundant sensing, diagnosis, and response.
+% The values and limits are illustrative; they are not operational flight
+% rules.
+
+materialize(metric, 3).
+materialize(diagnosis, 2).
+materialize(action, 2).
+
+% Primary telemetry for battery pack bp1.
+telemetry(bp1, temperature_c, 78.0).
+telemetry(bp1, temperature_rise_c_per_min, 4.2).
+telemetry(bp1, current_a, 32.0).
+telemetry(bp1, internal_resistance_ohm, 0.015625).
+telemetry(bp1, cell_delta_v, 0.19).
+
+% An independent temperature channel provides corroborating evidence.
+redundant_telemetry(bp1, temperature_c, 76.0).
+
+% Illustrative engineering limits and available cooling power.
+limit(max_safe_temperature_c, 60.0).
+limit(max_temperature_rise_c_per_min, 1.5).
+limit(max_cell_delta_v, 0.08).
+cooling_capacity_w(bp1, 12.0).
+
+% Thermal margin is positive below the limit and negative above it.
+metric(Pack, thermal_margin_c, Margin) :-
+  limit(max_safe_temperature_c, Maximum),
+  telemetry(Pack, temperature_c, Temperature),
+  sub(Maximum, Temperature, Margin).
+
+% Resistive heating follows P = I^2 R.
+metric(Pack, resistive_heating_w, Heating) :-
+  telemetry(Pack, current_a, Current),
+  telemetry(Pack, internal_resistance_ohm, Resistance),
+  mul(Current, Current, CurrentSquared),
+  mul(CurrentSquared, Resistance, Heating).
+
+over_temperature(Pack) :-
+  telemetry(Pack, temperature_c, Temperature),
+  limit(max_safe_temperature_c, Maximum),
+  gt(Temperature, Maximum).
+
+rapid_heating(Pack) :-
+  telemetry(Pack, temperature_rise_c_per_min, Rate),
+  limit(max_temperature_rise_c_per_min, Maximum),
+  gt(Rate, Maximum).
+
+cell_imbalance(Pack) :-
+  telemetry(Pack, cell_delta_v, Delta),
+  limit(max_cell_delta_v, Maximum),
+  gt(Delta, Maximum).
+
+heating_exceeds_cooling(Pack) :-
+  metric(Pack, resistive_heating_w, Heating),
+  cooling_capacity_w(Pack, Capacity),
+  gt(Heating, Capacity).
+
+% Require two independent temperature channels above the same safety limit.
+corroborated_over_temperature(Pack) :-
+  telemetry(Pack, temperature_c, Primary),
+  redundant_telemetry(Pack, temperature_c, Redundant),
+  limit(max_safe_temperature_c, Maximum),
+  gt(Primary, Maximum),
+  gt(Redundant, Maximum).
+
+% A diagnosis needs multiple independent signatures, not one threshold alone.
+diagnosis(Pack, thermal_runaway_precursor) :-
+  over_temperature(Pack),
+  rapid_heating(Pack),
+  cell_imbalance(Pack),
+  heating_exceeds_cooling(Pack).
+
+% The safety action additionally requires redundant temperature corroboration.
+action(Pack, isolate_and_cool) :-
+  diagnosis(Pack, thermal_runaway_precursor),
+  corroborated_over_temperature(Pack).

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "Deriva turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",

package/playground.html

@@ -526,6 +526,7 @@
           "hamming-code",
           "hanoi",
           "heat-loss",
+          "herbrand-semantics",
           "herbrand-witnesses",
           "heron-theorem",
           "ideal-gas-law",
@@ -588,6 +589,7 @@
           "socket-age",
           "socket-family",
           "socrates",
+          "spacecraft-battery-diagnosis",
           "stable-marriage",
           "statistics-summary",
           "stirling-bell-numbers",

package/test/run-examples.mjs

@@ -38,12 +38,14 @@ const proofExamples = [
   'graph-reachability.pl',
   'greatest-lower-bound-uniqueness.pl',
   'group-inverse-uniqueness.pl',
+  'herbrand-semantics.pl',
   'list-collection.pl',
   'proof-contrapositive.pl',
   'reusable-builtins.pl',
   'socket-age.pl',
   'socket-family.pl',
   'socrates.pl',
+  'spacecraft-battery-diagnosis.pl',
   'term-tools.pl',
   'witch.pl',
   'beam-deflection.pl',