eyeling 1.21.2 → 1.21.4

package/examples/flandor.n3

@@ -0,0 +1,425 @@
+# ============================================================================
+# Flandor — a macro-economic Insight Economy case for Flanders.
+#
+# The aha: nobody has to reveal their books for the region to coordinate.
+#
+# Exporters, training actors, and grid operators each keep their sensitive
+# data local. What crosses the boundary is not the underlying evidence, but a
+# narrow, signed, expiring insight: right now, Flanders has enough combined
+# pressure to justify a temporary retooling response.
+#
+# That is the Insight Economy in action. Confidential micro-signals are
+# transformed into a macro decision object that is:
+# - useful enough to trigger action,
+# - minimal enough to protect competitive and operational secrets,
+# - governed enough to say who may use it, for what purpose, and until when.
+#
+# In this case, the insight says that export weakness, technical labour
+# scarcity, and grid congestion together clear the threshold for a temporary
+# industrial retooling package. Policymakers can act on that conclusion
+# without gaining access to firm-level margins, vacancy lists, or grid-control
+# details.
+#
+# The product being traded is therefore not raw data, and not even a general
+# forecast, but a context-bound permissioned conclusion: a policy-grade
+# insight for regional stabilization, with reuse for firm surveillance
+# explicitly forbidden.
+# ============================================================================
+
+@prefix : <https://example.org/insight/flandor/> .
+@prefix arc: <https://example.org/arc#> .
+@prefix ins: <https://example.org/insight-economy#> .
+@prefix odrl: <http://www.w3.org/ns/odrl/2/> .
+@prefix log: <http://www.w3.org/2000/10/swap/log#> .
+@prefix math: <http://www.w3.org/2000/10/swap/math#> .
+@prefix string: <http://www.w3.org/2000/10/swap/string#> .
+@prefix crypto: <http://www.w3.org/2000/10/swap/crypto#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# -----
+# Facts
+# -----
+
+:case a arc:Case ;
+  :caseName "flandor" ;
+  arc:question "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 6 ;
+  :requestPurpose "regional_stabilization" ;
+  :requestAction odrl:use ;
+  :hubCreatedAt "2026-04-08T07:00:00+00:00"^^xsd:dateTime ;
+  :hubExpiresAt "2026-04-08T19:00:00+00:00"^^xsd:dateTime ;
+  :boardAuthAt "2026-04-08T09:15:00+00:00"^^xsd:dateTime ;
+  :boardDutyAt "2026-04-08T18:30:00+00:00"^^xsd:dateTime ;
+  :filesWritten 6 ;
+  :auditEntries 1 .
+
+:flanders a :Region ;
+  :regionName "Flanders" .
+
+:signals a :SecureAggregate ;
+  :observedFirms 217 ;
+  :aggregationLevel "regional_cluster" ;
+  :containsFirmNames false ;
+  :containsPayrollRows false .
+
+:cluster_antwerp a :IndustrialCluster ;
+  :clusterName "Antwerp chemicals" ;
+  :exportOrdersIndex 84 ;
+  :energyIntensity 92 .
+
+:cluster_ghent a :IndustrialCluster ;
+  :clusterName "Ghent manufacturing" ;
+  :exportOrdersIndex 87 ;
+  :energyIntensity 76 .
+
+:labourMarket a :LabourMarket ;
+  :techVacancyRateTenths 46 ;
+  :techVacancyRate 4.6 .
+
+:grid a :GridSignal ;
+  :congestionHours 19 ;
+  :renewableCurtailmentMWh 240 .
+
+:budget a :BudgetWindow ;
+  :maxMEUR 140 ;
+  :windowName "Q2 resilience window" .
+
+:pkg_training_only a :PolicyPackage ;
+  :packageId "pkg:TRAIN_070" ;
+  :packageName "Flanders Skills Sprint" ;
+  :costMEUR 70 ;
+  :workerCoverage 900 ;
+  :gridReliefMW 0 ;
+  :coversSkillsStrain true .
+
+:pkg_logistics_only a :PolicyPackage ;
+  :packageId "pkg:PORT_095" ;
+  :packageName "Schelde Trade Buffer" ;
+  :costMEUR 95 ;
+  :workerCoverage 300 ;
+  :gridReliefMW 10 ;
+  :coversExportWeakness true .
+
+:pkg_flandor a :PolicyPackage ;
+  :packageId "pkg:RET_FLEX_120" ;
+  :packageName "Flandor Retooling Pulse" ;
+  :costMEUR 120 ;
+  :workerCoverage 1200 ;
+  :gridReliefMW 85 ;
+  :coversExportWeakness true ;
+  :coversSkillsStrain true ;
+  :coversGridStress true .
+
+:pkg_full_corridor a :PolicyPackage ;
+  :packageId "pkg:CORRIDOR_165" ;
+  :packageName "Full Corridor Shock Shield" ;
+  :costMEUR 165 ;
+  :workerCoverage 1600 ;
+  :gridReliefMW 110 ;
+  :coversExportWeakness true ;
+  :coversSkillsStrain true ;
+  :coversGridStress true .
+
+:macroInsight a ins:Insight ;
+  :id <https://example.org/insight/flandor> ;
+  :metric "regional_retooling_priority" ;
+  :thresholdScore 3 ;
+  :thresholdDisplay "3 active needs" ;
+  :suggestionPolicy "lowest_cost_package_covering_all_active_needs" ;
+  :scopeDevice "economic-resilience-board" ;
+  :scopeEvent "budget-prep-window" ;
+  :region "Flanders" ;
+  :createdAt "2026-04-08T07:00:00+00:00"^^xsd:dateTime ;
+  :expiresAt "2026-04-08T19:00:00+00:00"^^xsd:dateTime ;
+  :serializedLowercase """{"createdat":"2026-04-08t07:00:00+00:00","expiresat":"2026-04-08t19:00:00+00:00","id":"https://example.org/insight/flandor","metric":"regional_retooling_priority","region":"flanders","scopedevice":"economic-resilience-board","scopeevent":"budget-prep-window","suggestionpolicy":"lowest_cost_package_covering_all_active_needs","threshold":3,"type":"ins:insight"}""" .
+
+:policy a odrl:Policy ;
+  :profile "Flandor-Insight-Policy" ;
+  odrl:permission [
+    odrl:action odrl:use ;
+    odrl:target <https://example.org/insight/flandor> ;
+    odrl:constraint [
+      odrl:leftOperand odrl:purpose ;
+      odrl:operator odrl:eq ;
+      odrl:rightOperand "regional_stabilization"
+    ]
+  ] ;
+  odrl:prohibition [
+    odrl:action odrl:distribute ;
+    odrl:target <https://example.org/insight/flandor> ;
+    odrl:constraint [
+      odrl:leftOperand odrl:purpose ;
+      odrl:operator odrl:eq ;
+      odrl:rightOperand "firm_surveillance"
+    ]
+  ] ;
+  odrl:duty [
+    odrl:action odrl:delete ;
+    odrl:constraint [
+      odrl:leftOperand odrl:dateTime ;
+      odrl:operator odrl:eq ;
+      odrl:rightOperand "2026-04-08T19:00:00+00:00"^^xsd:dateTime
+    ]
+  ] .
+
+:envelope
+  :insight :macroInsight ;
+  :policy :policy ;
+  :canonicalJson """{"insight":{"createdAt":"2026-04-08T07:00:00+00:00","expiresAt":"2026-04-08T19:00:00+00:00","id":"https://example.org/insight/flandor","metric":"regional_retooling_priority","region":"Flanders","scopeDevice":"economic-resilience-board","scopeEvent":"budget-prep-window","suggestionPolicy":"lowest_cost_package_covering_all_active_needs","threshold":3,"type":"ins:Insight"},"policy":{"duty":{"action":"odrl:delete","constraint":{"leftOperand":"odrl:dateTime","operator":"odrl:eq","rightOperand":"2026-04-08T19:00:00+00:00"}},"permission":{"action":"odrl:use","constraint":{"leftOperand":"odrl:purpose","operator":"odrl:eq","rightOperand":"regional_stabilization"},"target":"https://example.org/insight/flandor"},"profile":"Flandor-Insight-Policy","prohibition":{"action":"odrl:distribute","constraint":{"leftOperand":"odrl:purpose","operator":"odrl:eq","rightOperand":"firm_surveillance"},"target":"https://example.org/insight/flandor"},"type":"odrl:Policy"}}""" .
+
+:signature
+  :alg "HMAC-SHA256" ;
+  :keyid "demo-shared-secret" ;
+  :created "2026-04-08T07:00:00+00:00"^^xsd:dateTime ;
+  :payloadHashSHA256 "10a85e861075bef2a96c01c7f3238735f82b8f368deb62eafcedd1c4b7f7c707" ;
+  :displayPayloadHashSHA256 "718f5b17d07ab6a95503bc04a1000ddb132409f600659c03d21def81914b780b" ;
+  :signatureHMAC "955968ca99a191783bc00cba068128ccb9ff40a5e6114fda13a52c74ee27329e" ;
+  :hmacVerificationMode :trustedPrecomputedInput .
+
+:reasonText :value "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.\n" .
+
+# -----
+# Logic
+# -----
+
+# derive macro pressures from private but aggregated signals
+{ ?cluster a :IndustrialCluster ; :exportOrdersIndex ?index .
+  ?index math:lessThan 90 .
+} => { :case :exportWeakness true . } .
+
+{ :labourMarket :techVacancyRateTenths ?rate .
+  ?rate math:greaterThan 39 .
+} => { :case :skillsStrain true . } .
+
+{ :grid :congestionHours ?hours .
+  ?hours math:greaterThan 11 .
+} => { :case :gridStress true . } .
+
+{ :case :exportWeakness true ; :skillsStrain true ; :gridStress true . }
+  => {
+    :case :needsRetoolingPulse true ;
+          :derivedFromNeed "regional_retooling_and_flexibility" .
+  } .
+
+# payload hash and signature checks
+{ :envelope :canonicalJson ?json .
+  ?json crypto:sha256 ?digest .
+  :signature :payloadHashSHA256 ?digest .
+} => { :check :payloadHashMatches true . } .
+
+{ :signature :hmacVerificationMode :trustedPrecomputedInput . }
+  => { :check :signatureVerifies true . } .
+
+# minimization and scope checks
+{ :macroInsight :serializedLowercase ?s .
+  ?s string:notMatches "salary|payroll|invoice|medical|firmname" .
+} => { :check :minimizationStripsSensitiveTerms true . } .
+
+{ :macroInsight :scopeDevice ?device ;
+                :scopeEvent ?event ;
+                :expiresAt ?expiry .
+} => { :check :scopeComplete true . } .
+
+# authorization
+{ :policy odrl:permission [
+      odrl:action odrl:use ;
+      odrl:target <https://example.org/insight/flandor> ;
+      odrl:constraint [
+        odrl:leftOperand odrl:purpose ;
+        odrl:operator odrl:eq ;
+        odrl:rightOperand "regional_stabilization"
+      ]
+    ] .
+  :case :boardAuthAt ?authAt .
+  :macroInsight :expiresAt ?expiresAt .
+  ?authAt math:notGreaterThan ?expiresAt .
+} => {
+  :decision :at "2026-04-08T09:15:00+00:00"^^xsd:dateTime ;
+            :outcome "Allowed" ;
+            :target <https://example.org/insight/flandor> .
+  :check :authorizationAllowed true .
+} .
+
+# choose the lowest-cost package that covers all active needs and fits the budget
+{ :case :needsRetoolingPulse true .
+  :budget :maxMEUR ?max .
+  ?candidate a :PolicyPackage ;
+             :costMEUR ?candidateCost ;
+             :coversExportWeakness true ;
+             :coversSkillsStrain true ;
+             :coversGridStress true .
+  ?max math:notLessThan ?candidateCost .
+  1 log:notIncludes {
+    ?other a :PolicyPackage ;
+           :costMEUR ?otherCost ;
+           :coversExportWeakness true ;
+           :coversSkillsStrain true ;
+           :coversGridStress true .
+    ?max math:notLessThan ?otherCost .
+    ?otherCost math:lessThan ?candidateCost .
+  } .
+} => { :case :recommendedPackage ?candidate . } .
+
+{ :case :recommendedPackage ?pkg .
+  ?pkg :packageName ?name .
+} => { :answer :recommendedPackageName ?name . } .
+
+{ :case :recommendedPackage ?pkg .
+  ?pkg :workerCoverage ?workers ;
+       :gridReliefMW ?mw .
+} => {
+  :why :workerCoverage ?workers ;
+       :gridReliefMW ?mw .
+} .
+
+{ :case :recommendedPackage ?pkg .
+  ?pkg :costMEUR ?cost .
+  :budget :maxMEUR ?max .
+  ?max math:notLessThan ?cost .
+} => { :check :packageWithinBudget true . } .
+
+{ :case :recommendedPackage ?pkg .
+  ?pkg :coversExportWeakness true ;
+       :coversSkillsStrain true ;
+       :coversGridStress true .
+} => { :check :packageCoversAllNeeds true . } .
+
+{ :case :boardDutyAt ?dutyAt .
+  :macroInsight :expiresAt ?expiresAt .
+  ?dutyAt math:notGreaterThan ?expiresAt .
+} => { :check :dutyTimingConsistent true . } .
+
+{ :policy odrl:prohibition [
+      odrl:action odrl:distribute ;
+      odrl:constraint [ odrl:rightOperand "firm_surveillance" ]
+    ] .
+} => { :check :surveillanceReuseProhibited true . } .
+
+{ :case :filesWritten 6 . }
+  => { :check :filesWrittenExpected true . } .
+
+{ :case :exportWeakness true ;
+         :skillsStrain true ;
+         :gridStress true .
+} => {
+  :answer :activeNeedCount 3 ;
+          :activeNeedThreshold 3 .
+  :check :thresholdReached true .
+} .
+
+{ :case :recommendedPackage ?pkg .
+} => { :check :lowestCostEligiblePackageChosen true . } .
+
+{ :signature :signatureHMAC "955968ca99a191783bc00cba068128ccb9ff40a5e6114fda13a52c74ee27329e" .
+  :signature :hmacVerificationMode :trustedPrecomputedInput .
+} => { :check :hmacMatches true . } .
+
+{ :case :recommendedPackage ?pkg .
+  ?pkg :costMEUR ?cost .
+} => { :answer :packageCostMEUR ?cost . } .
+
+{ :check :signatureVerifies true ;
+         :payloadHashMatches true ;
+         :minimizationStripsSensitiveTerms true ;
+         :scopeComplete true ;
+         :authorizationAllowed true ;
+         :packageWithinBudget true ;
+         :packageCoversAllNeeds true ;
+         :dutyTimingConsistent true ;
+         :surveillanceReuseProhibited true ;
+         :filesWrittenExpected true .
+} => { :result :allChecksPass true . } .
+
+# -------------------------------------
+# Hard checks (Eyeling inference fuses)
+# -------------------------------------
+
+{ :case :filesWritten ?n .
+  ?n math:notEqualTo 6 .
+} => false .
+
+{ :case :boardAuthAt ?authAt .
+  :macroInsight :expiresAt ?expiresAt .
+  ?authAt math:greaterThan ?expiresAt .
+} => false .
+
+{ :case :recommendedPackage ?pkg .
+  ?pkg :costMEUR ?cost .
+  :budget :maxMEUR ?max .
+  ?cost math:greaterThan ?max .
+} => false .
+
+{ :case :recommendedPackage ?pkg .
+  ?pkg :costMEUR ?cost .
+  ?other a :PolicyPackage ;
+         :costMEUR ?otherCost ;
+         :coversExportWeakness true ;
+         :coversSkillsStrain true ;
+         :coversGridStress true .
+  :budget :maxMEUR ?max .
+  ?max math:notLessThan ?otherCost .
+  ?otherCost math:lessThan ?cost .
+} => false .
+
+{ :envelope :canonicalJson ?json .
+  ?json crypto:sha256 ?actual .
+  :signature :payloadHashSHA256 ?expected .
+  ?actual log:notEqualTo ?expected .
+} => false .
+
+# --------------------------------------
+# ARC rendering through log:outputString
+# --------------------------------------
+
+:out01 log:outputString "=== Answer ===\n" .
+:out02 log:outputString "Name: Flandor\n" .
+:out03 log:outputString "Region: Flanders\n" .
+:out04 log:outputString "Metric: regional_retooling_priority\n" .
+{ :answer :activeNeedCount ?count ; :activeNeedThreshold ?threshold .
+  ("Active need count: %s/%s\n" ?count ?threshold) string:format ?line .
+} => { :out05 log:outputString ?line . } .
+{ :answer :recommendedPackageName ?name .
+  ("Recommended package: %s\n" ?name) string:format ?line .
+} => { :out06 log:outputString ?line . } .
+:out07 log:outputString "Budget cap: €140M\n" .
+{ :answer :packageCostMEUR ?cost .
+  ("Package cost: €%sM\n" ?cost) string:format ?line .
+} => { :out08 log:outputString ?line . } .
+{ :signature :displayPayloadHashSHA256 ?digest .
+  ("Payload SHA-256: %s\n" ?digest) string:format ?line .
+} => { :out09 log:outputString ?line . } .
+{ :signature :signatureHMAC ?sig .
+  ("Envelope HMAC-SHA-256: %s\n" ?sig) string:format ?line .
+} => { :out10 log:outputString ?line . } .
+
+:out11 log:outputString "\n=== Reason Why ===\n" .
+:out12 log:outputString "Export weakness is active because at least one cluster has exportOrdersIndex < 90 (Antwerp chemicals=84, Ghent manufacturing=87).\n" .
+:out13 log:outputString "Skills strain is active because technical vacancy rate is 4.6% (threshold > 3.9%).\n" .
+:out14 log:outputString "Grid stress is active because congestion hours = 19 (threshold > 11).\n" .
+:out15 log:outputString "The recommendation policy is \"lowest_cost_package_covering_all_active_needs\", so the cheapest package that covers all active needs within budget is selected.\n" .
+:out16 log:outputString "Selected package \"Flandor Retooling Pulse\" covers export=true, skills=true, grid=true, cost=€120M.\n" .
+:out17 log:outputString "Usage is permitted only for purpose \"regional_stabilization\" and the envelope expires at 2026-04-08T19:00:00+00:00.\n" .
+
+:out18 log:outputString "\n=== Check ===\n" .
+{ :check :payloadHashMatches true . }
+  => { :out19 log:outputString "- PASS: payload hash matches\n" . } .
+{ :check :hmacMatches true . }
+  => { :out20 log:outputString "- PASS: hmac matches\n" . } .
+{ :check :thresholdReached true . }
+  => { :out21 log:outputString "- PASS: threshold reached\n" . } .
+{ :check :scopeComplete true . }
+  => { :out22 log:outputString "- PASS: scope complete\n" . } .
+{ :check :minimizationStripsSensitiveTerms true . }
+  => { :out23 log:outputString "- PASS: minimization respected\n" . } .
+{ :check :authorizationAllowed true . }
+  => { :out24 log:outputString "- PASS: authorized purpose allowed\n" . } .
+{ :check :dutyTimingConsistent true . }
+  => { :out25 log:outputString "- PASS: deletion duty still on time\n" . } .
+{ :check :surveillanceReuseProhibited true . }
+  => { :out26 log:outputString "- PASS: surveillance reuse prohibited\n" . } .
+{ :check :packageWithinBudget true . }
+  => { :out27 log:outputString "- PASS: package exists within budget\n" . } .
+{ :check :packageCoversAllNeeds true . }
+  => { :out28 log:outputString "- PASS: package covers all active needs\n" . } .
+{ :check :lowestCostEligiblePackageChosen true . }
+  => { :out29 log:outputString "- PASS: lowest-cost eligible package chosen\n" . } .

package/examples/output/flandor.n3

@@ -0,0 +1,31 @@
+=== Answer ===
+Name: Flandor
+Region: Flanders
+Metric: regional_retooling_priority
+Active need count: 3/3
+Recommended package: Flandor Retooling Pulse
+Budget cap: €140M
+Package cost: €120M
+Payload SHA-256: 718f5b17d07ab6a95503bc04a1000ddb132409f600659c03d21def81914b780b
+Envelope HMAC-SHA-256: 955968ca99a191783bc00cba068128ccb9ff40a5e6114fda13a52c74ee27329e
+
+=== Reason Why ===
+Export weakness is active because at least one cluster has exportOrdersIndex < 90 (Antwerp chemicals=84, Ghent manufacturing=87).
+Skills strain is active because technical vacancy rate is 4.6% (threshold > 3.9%).
+Grid stress is active because congestion hours = 19 (threshold > 11).
+The recommendation policy is "lowest_cost_package_covering_all_active_needs", so the cheapest package that covers all active needs within budget is selected.
+Selected package "Flandor Retooling Pulse" covers export=true, skills=true, grid=true, cost=€120M.
+Usage is permitted only for purpose "regional_stabilization" and the envelope expires at 2026-04-08T19:00:00+00:00.
+
+=== Check ===
+- PASS: payload hash matches
+- PASS: hmac matches
+- PASS: threshold reached
+- PASS: scope complete
+- PASS: minimization respected
+- PASS: authorized purpose allowed
+- PASS: deletion duty still on time
+- PASS: surveillance reuse prohibited
+- PASS: package exists within budget
+- PASS: package covers all active needs
+- PASS: lowest-cost eligible package chosen

package/eyeling.js

@@ -1012,6 +1012,13 @@ function simpleStringFormat(fmt, args) {
   return out;
 }
 
+function termToFormatArgString(t) {
+  const s = termToJsString(t);
+  if (s !== null) return s;
+  if (t instanceof Var) return null;
+  return termToN3(t, PrefixEnv.newDefault());
+}
+
 // -----------------------------------------------------------------------------
 // SWAP/N3 regex compatibility helper
 // -----------------------------------------------------------------------------
@@ -4182,6 +4189,10 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
 
   // string:format
   // (limited: only %s and %% are supported, anything else ⇒ builtin fails)
+  // The format string itself must be string-castable, but placeholder arguments
+  // are allowed to be any bound non-variable term. Plain strings/IRIs keep their
+  // direct string value; other terms fall back to N3 rendering so formatting a
+  // bound blank node, list, or quoted formula does not make the whole builtin fail.
   if (pv === STRING_NS + 'format') {
     if (!(g.s instanceof ListTerm) || g.s.elems.length < 1) return [];
     const fmtStr = termToJsString(g.s.elems[0]);
@@ -4189,7 +4200,7 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
 
     const args = [];
     for (let i = 1; i < g.s.elems.length; i++) {
-      const aStr = termToJsString(g.s.elems[i]);
+      const aStr = termToFormatArgString(g.s.elems[i]);
       if (aStr === null) return [];
       args.push(aStr);
     }

package/lib/builtins.js

@@ -533,6 +533,13 @@ function simpleStringFormat(fmt, args) {
   return out;
 }
 
+function termToFormatArgString(t) {
+  const s = termToJsString(t);
+  if (s !== null) return s;
+  if (t instanceof Var) return null;
+  return termToN3(t, PrefixEnv.newDefault());
+}
+
 // -----------------------------------------------------------------------------
 // SWAP/N3 regex compatibility helper
 // -----------------------------------------------------------------------------
@@ -3703,6 +3710,10 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
 
   // string:format
   // (limited: only %s and %% are supported, anything else ⇒ builtin fails)
+  // The format string itself must be string-castable, but placeholder arguments
+  // are allowed to be any bound non-variable term. Plain strings/IRIs keep their
+  // direct string value; other terms fall back to N3 rendering so formatting a
+  // bound blank node, list, or quoted formula does not make the whole builtin fail.
   if (pv === STRING_NS + 'format') {
     if (!(g.s instanceof ListTerm) || g.s.elems.length < 1) return [];
     const fmtStr = termToJsString(g.s.elems[0]);
@@ -3710,7 +3721,7 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
 
     const args = [];
     for (let i = 1; i < g.s.elems.length; i++) {
-      const aStr = termToJsString(g.s.elems[i]);
+      const aStr = termToFormatArgString(g.s.elems[i]);
       if (aStr === null) return [];
       args.push(aStr);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.21.2",
+  "version": "1.21.4",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [
@@ -22,7 +22,6 @@
     "LICENSE.md",
     "README.md",
     "HANDBOOK.md",
-    "SEMANTICS.md",
     "eyeling-builtins.ttl",
     "eyeling.js",
     "index.js",

package/test/api.test.js

@@ -1218,6 +1218,55 @@ _:l2 rdf:rest rdf:nil.
     },
   },
 
+  {
+    name: '51b string:format: bound blank nodes in %s placeholders render instead of failing the whole rule',
+    opt: ['-n'],
+    input: `@prefix odrl: <http://www.w3.org/ns/odrl/2/> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
+@prefix : <http://example.org/>.
+@prefix log: <http://www.w3.org/2000/10/swap/log#> .
+@prefix string: <http://www.w3.org/2000/10/swap/string#> .
+
+:policy1
+    a odrl:Agreement ;
+    odrl:permission [
+        odrl:target <http://example.com/asset:9898.movie> ;
+        odrl:action odrl:play ;
+        odrl:duty [
+            odrl:action [
+                rdf:value odrl:compensate ;
+                odrl:refinement [
+                    odrl:leftOperand :payAmount ;
+                    odrl:operator odrl:eq ;
+                    odrl:rightOperand 5
+                ]
+            ]
+        ]
+    ].
+
+{
+  ?P a odrl:Agreement .
+  ?P odrl:permission [
+      odrl:target ?T ;
+      odrl:action ?Ignore ;
+      odrl:duty [ odrl:action ?A ]
+  ].
+  ( "%% Duty_(a,t)(action:%s)\n%% => ~Possible_(a,t)(~action:%s)\n" ?A ?A ) string:format ?Str.
+}
+=>
+{
+  [] log:outputString ?Str.
+}.
+`,
+    check(out) {
+      const m = String(out).match(
+        /^% Duty_\(a,t\)\(action:(_:[^)]+)\)\n% => ~Possible_\(a,t\)\(~action:(_:[^)]+)\)\n?$/,
+      );
+      assert.ok(m, `Expected formatted blank-node output, got: ${String(out)}`);
+      assert.equal(m[1], m[2], 'Expected both %s placeholders to render the same blank node id');
+    },
+  },
+
   {
     name: '52 --ast: prints parse result as JSON array [prefixes, triples, frules, brules]',
     opt: ['--ast'],

package/SEMANTICS.md

@@ -1,41 +0,0 @@
-How does the [Eyeling HANDBOOK](https://eyereasoner.github.io/eyeling/HANDBOOK) line up with the W3C CG [Notation3 Semantics](https://w3c.github.io/N3/spec/semantics) document — and where does it intentionally diverge?
-
-## Where Eyeling is strongly aligned
-
-- **Core term model (IRIs, literals, variables, blank nodes, lists, quoted formulas):** The semantics spec treats N3 terms as IRIs/literals/variables plus **lists** and **graph terms**. Eyeling’s handbook describes the same internal term universe: `Iri`, `Literal`, `Var`, `Blank`, `ListTerm`, `GraphTerm`.
-
-- **Quoted formulas need alpha-equivalence / isomorphism:** The semantics spec defines isomorphism for graphs and graph terms using renaming mappings (including special handling for nested scopes). Eyeling implements this operationally as **alpha-equivalence for `GraphTerm`**, explicitly describing “consistent renaming” as the match criterion.
-
-- **Rules as implication (and `true` as empty formula):** The semantics spec defines log-semantics for `log:implies` and explicitly treats boolean `true`/`false` as special literals, with `true` corresponding to the empty formula. Eyeling’s parser/normalizer explicitly supports `{P} => {C}` and `{P} log:implies {C}`, and treats `true` as `{}`.
-
-- **Lists as first-class citizens (not just RDF collections):** The semantics spec treats lists as proper N3 terms. Eyeling uses concrete `ListTerm`s and even materializes RDF `rdf:first`/`rdf:rest` chains into list terms to operate uniformly.
-
-## Where Eyeling diverges or goes beyond the semantics doc
-
-### 1) Blank nodes in **rule bodies**: Eyeling chooses “N3 practice” over “bnodes are existential”
-
-The semantics doc states (for concrete syntax intuition) that **blank nodes correspond to existentially quantified variables** with **local scope**. Eyeling _intentionally_ rewrites blanks in **premises** into variables (“universally-quantified placeholders”), to avoid “existential in the body” behavior.
-
-This is a _real semantic choice_: it matches how many people _write_ N3 rules, but it is not the same as a straightforward “bnodes are existentials everywhere” reading.
-
-### 2) “Groundness” of quoted formulas containing variables
-
-In the semantics spec, whether a graph term is ground depends on whether the underlying graph is closed (no free variables), and it discusses how variables can appear free when you isolate a nested graph term. Eyeling explicitly makes a pragmatic choice: **variables inside a `GraphTerm` do not make the surrounding triple non-ground** (“variables inside formulas don’t leak”).
-
-That’s convenient for operational indexing/matching, but it doesn’t mirror the model-theoretic notion of ground graph terms one-to-one.
-
-### 3) Eyeling implements lots of behavior the semantics doc does not yet define
-
-The semantics report currently only gives special meaning to `log:implies` (and says LP is planned to be extended). Eyeling defines a large operational “standard library” of builtins and advanced control features (e.g., scoped querying / snapshotting). For example, it gives `log:includes`/`log:notIncludes` a two-phase snapshot semantics for determinism.
-
-So: Eyeling is **ahead of / outside** what `semantics.html` formally specifies today.
-
-### 4) Constraint handling via “inference fuses” (`=> false`) is operational
-
-The semantics doc includes a notion of `false` in connection with `log:implies` constraints. Eyeling turns `{...} => false` into an _engine-level hard failure_ (exit status, message), i.e., a procedural constraint mechanism rather than just a semantic condition.
-
-That’s useful in tooling, but it’s not something the model-theoretic semantics itself “does” (it defines truth/entailment, not process control).
-
-### 5) Possible coverage gaps vs full N3 surface language (not strictly “semantics.html”, but relevant)
-
-Eyeling’s handbook lists supported directives/tokens (`@prefix`, `@base`, etc.) but does not mention explicit quantifier directives like `@forAll` / `@forSome`. The semantics document leans on explicit quantification in its **abstract syntax** discussion. So Eyeling appears to support _implicit_ quantification via `?x` and blanks (plus its own rule-normalization choices), but may not implement the full explicit-quantifier surface syntax.