eyeling 1.21.3 → 1.21.4

package/HANDBOOK.md

@@ -1573,6 +1573,10 @@ A tiny `sprintf` subset:
 - Supports only `%s` and `%%`.
 - Any other specifier (`%d`, `%f`, …) causes the builtin to fail.
 - Missing arguments are treated as empty strings.
+- The format string `fmt` itself must be string-castable.
+- Each `%s` argument may be any bound non-variable term:
+  - string-castable terms (IRIs and literals) use their direct string value;
+  - other bound terms (blank nodes, lists, quoted formulas, …) are rendered as N3.
 
 ### Length and character utilities (Eyeling extensions)
 

package/dist/browser/eyeling.browser.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/examples/arc-bridge/README.md

@@ -0,0 +1,208 @@
+# ARC Bridge
+
+This directory holds **ARC Bridge** cases.
+
+An ARC Bridge case sits between two existing forms in Eyeling:
+
+- the **declarative N3** case in `examples/`, and
+- the **specialized executable** case in `examples/extra/`.
+
+Its purpose is to keep the ARC promise visible while making the case easy to read, easy to rerun, and easy to port.
+
+In one line:
+
+> `examples/arc-bridge/` presents controlled-English ARC specifications with reference ECMAScript realizations and JSON test vectors.
+
+## Why this directory exists
+
+Eyeling already has two valuable ways to present a case.
+
+The files in `examples/` are ideal for seeing the logic in open declarative form. The files in `examples/extra/` are ideal when a case has already been shaped and we want a compact executable artifact that runs quickly.
+
+ARC Bridge exists for the middle layer. It gives each case:
+
+- a **normative statement** in controlled mathematical English,
+- a **reference realization** in ECMAScript,
+- a **concrete instance** in JSON, and
+- an **expected result** for comparison and regression testing.
+
+So ARC Bridge is not a replacement for either of the existing collections. It is a bridge between them.
+
+## The ARC part
+
+ARC means:
+
+- **Answer**
+- **Reason Why**
+- **Check**
+
+A good ARC Bridge case should preserve that trust pattern even though it is not written directly in N3.
+
+That means:
+
+- the **answer** is clearly identifiable,
+- the **reason why** is visible as named clauses or derived predicates,
+- and the **check** is real, meaning it could fail for a meaningful reason.
+
+## What belongs here
+
+A case belongs in `examples/arc-bridge/` when:
+
+- there is a useful ARC-style case in `examples/`,
+- there is value in giving the case a more direct operational form,
+- but we still want the logic to stay explicit and auditable,
+- with a specification that can be read independently of the code.
+
+Typical uses:
+
+- policy and governance examples,
+- privacy-preserving decision examples,
+- cases with a stable logical core and a small executable shell,
+- cases that benefit from conformance-style testing.
+
+## Directory shape
+
+Each case should live in its own subdirectory.
+
+For example:
+
+```text
+examples/arc-bridge/
+  delfour/
+    delfour.spec.md
+    delfour.data.json
+    delfour.model.mjs
+    delfour.expected.json
+    delfour.instance.schema.json
+  flandor/
+    flandor.spec.md
+    flandor.data.json
+    flandor.model.mjs
+    flandor.expected.json
+    flandor.instance.schema.json
+```
+
+## The five files
+
+Each ARC Bridge case should contain these files.
+
+### 1. `name.spec.md`
+
+The normative case description.
+
+This file should use **controlled mathematical English**. It should define the vocabulary, the inputs, the derived predicates, the decision rule, the governance rule, the checks, and the output contract.
+
+The spec should be written so that a careful reader can understand the case without reading the ECMAScript source first.
+
+### 2. `name.data.json`
+
+The concrete instance data.
+
+This file contains the facts for the case: entities, thresholds, observed values, policies, timestamps, candidate actions, and any other case inputs.
+
+### 3. `name.model.mjs`
+
+The reference ECMAScript realization.
+
+This file should implement the case directly and clearly. A good pattern is to map named clauses in the spec to named functions in the model.
+
+For example:
+
+- `clauseR1_exportWeakness`
+- `clauseS2_recommendedPackage`
+- `clauseG1_authorizedUse`
+- `clauseM2_payloadHash`
+
+The model is not the normative source. It is the **reference realization** of the normative source.
+
+### 4. `name.expected.json`
+
+The expected derived result.
+
+This file is the conformance vector for the case. It should capture the main derived predicates, the selected answer, the visible checks, and any stable integrity values needed for regression testing.
+
+### 5. `name.instance.schema.json`
+
+The instance schema.
+
+This file defines the required structure of the input JSON. It should be strict enough to catch malformed case instances before evaluation.
+
+## How to read an ARC Bridge case
+
+A good reading order is:
+
+1. start with `name.spec.md`,
+2. inspect `name.data.json`,
+3. run `name.model.mjs`,
+4. compare the result with `name.expected.json`,
+5. then relate the case back to its N3 and specialized counterparts.
+
+That order keeps the meaning visible before the operational details.
+
+## Relationship to the rest of `examples/`
+
+A useful mental model is:
+
+- `examples/` shows ARC cases in **declarative Eyeling form**,
+- `examples/arc-bridge/` shows the same kind of cases in **specification-plus-reference form**,
+- `examples/extra/` shows selected cases in **specialized executable form**.
+
+So the three collections are complementary:
+
+- **N3** is best for seeing the logic in the open,
+- **ARC Bridge** is best for stating the case normatively and running a portable reference model,
+- **extra** is best for fast specialized execution.
+
+## Design rules
+
+When adding a case here, prefer the following.
+
+### 1. Keep the spec normative
+
+The spec should say what the case means. It should not merely paraphrase the code.
+
+### 2. Keep the code direct
+
+The ECMAScript model should say what it does and do what it says. Avoid unnecessary framework machinery.
+
+### 3. Keep the data separate
+
+Case facts belong in JSON, not hard-coded into the prose.
+
+### 4. Keep checks substantive
+
+A check should add confidence. It should not only restate the answer.
+
+### 5. Keep names aligned
+
+If a case is called `delfour` in `examples/` and `examples/extra/`, the ARC Bridge case should use the same base name.
+
+## Suggested workflow for a new case
+
+1. Start from a strong ARC-style N3 example.
+2. Write a controlled-English specification of the case.
+3. Move the concrete instance into JSON.
+4. Implement a small ECMAScript reference model.
+5. Capture the expected result in JSON.
+6. Keep the visible output in Answer / Reason Why / Check shape.
+7. Link the bridge case to its N3 and specialized counterparts.
+
+## What ARC Bridge is not
+
+ARC Bridge is not:
+
+- a replacement for declarative Eyeling,
+- a performance collection,
+- a general application framework,
+- or a place for prose that cannot be tested.
+
+It exists to make a case simultaneously:
+
+- readable,
+- executable,
+- checkable,
+- and portable.
+
+## In one line
+
+`examples/arc-bridge/` presents controlled-English ARC case specifications with reference ECMAScript realizations, JSON instances, and expected results, as a bridge between declarative Eyeling examples and specialized executable companions.

package/examples/arc-bridge/delfour/delfour.data.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "./delfour.instance.schema.json",
+  "caseName": "Delfour",
+  "retailer": "Delfour",
+  "question": "Is the Delfour self-scanner allowed to use a neutral shopping insight for shopping assistance, and if so what lower-sugar alternative should it suggest?",
+  "timestamps": {
+    "createdAt": "2025-10-05T20:33:48.907163+00:00",
+    "expiresAt": "2025-10-05T22:33:48.907185+00:00",
+    "authorizedAt": "2025-10-05T20:35:48.907163+00:00",
+    "dutyPerformedAt": "2025-10-05T20:37:48.907163+00:00"
+  },
+  "evaluationContext": {
+    "scopeDevice": "self-scanner",
+    "scopeEvent": "pick_up_scanner",
+    "purpose": "shopping_assist",
+    "prohibitedReusePurpose": "marketing",
+    "requestAction": "odrl:use"
+  },
+  "thresholds": {
+    "sugarPerServingGAtLeast": 10.0
+  },
+  "householdProfile": {
+    "condition": "Diabetes"
+  },
+  "catalog": [
+    {
+      "id": "prod:BIS_001",
+      "name": "Classic Tea Biscuits",
+      "sugarTenths": 120,
+      "sugarPerServing": 12.0
+    },
+    {
+      "id": "prod:BIS_101",
+      "name": "Low-Sugar Tea Biscuits",
+      "sugarTenths": 30,
+      "sugarPerServing": 3.0
+    },
+    {
+      "id": "prod:CHOC_050",
+      "name": "Milk Chocolate Bar",
+      "sugarTenths": 150,
+      "sugarPerServing": 15.0
+    },
+    {
+      "id": "prod:CHOC_150",
+      "name": "85% Dark Chocolate",
+      "sugarTenths": 60,
+      "sugarPerServing": 6.0
+    }
+  ],
+  "scan": {
+    "scannedProductId": "prod:BIS_001"
+  },
+  "insightPolicy": {
+    "id": "https://example.org/insight/delfour",
+    "metric": "sugar_g_per_serving",
+    "type": "ins:Insight",
+    "suggestionPolicy": "lower_metric_first_higher_price_ok",
+    "policyType": "odrl:Policy",
+    "policyProfile": "Delfour-Insight-Policy"
+  },
+  "integrity": {
+    "hashAlgorithm": "SHA-256",
+    "macAlgorithm": "HMAC-SHA-256",
+    "secret": "neutral-insight-demo-shared-secret",
+    "verificationMode": "trustedPrecomputedInput"
+  }
+}

package/examples/arc-bridge/delfour/delfour.expected.json

@@ -0,0 +1,88 @@
+{
+  "caseName": "Delfour",
+  "derived": {
+    "needsLowSugar": true,
+    "highSugarScanned": true,
+    "lowerSugarCandidateIds": ["prod:BIS_101", "prod:CHOC_150"],
+    "recommendedAlternativeId": "prod:BIS_101",
+    "recommendedAlternativeName": "Low-Sugar Tea Biscuits",
+    "alternativeLowersSugar": true
+  },
+  "envelope": {
+    "insight": {
+      "createdAt": "2025-10-05T20:33:48.907163+00:00",
+      "expiresAt": "2025-10-05T22:33:48.907185+00:00",
+      "id": "https://example.org/insight/delfour",
+      "metric": "sugar_g_per_serving",
+      "retailer": "Delfour",
+      "scopeDevice": "self-scanner",
+      "scopeEvent": "pick_up_scanner",
+      "suggestionPolicy": "lower_metric_first_higher_price_ok",
+      "threshold": 10,
+      "type": "ins:Insight"
+    },
+    "policy": {
+      "duty": {
+        "action": "odrl:delete",
+        "constraint": {
+          "leftOperand": "odrl:dateTime",
+          "operator": "odrl:eq",
+          "rightOperand": "2025-10-05T22:33:48.907185+00:00"
+        }
+      },
+      "permission": {
+        "action": "odrl:use",
+        "constraint": {
+          "leftOperand": "odrl:purpose",
+          "operator": "odrl:eq",
+          "rightOperand": "shopping_assist"
+        },
+        "target": "https://example.org/insight/delfour"
+      },
+      "profile": "Delfour-Insight-Policy",
+      "prohibition": {
+        "action": "odrl:distribute",
+        "constraint": {
+          "leftOperand": "odrl:purpose",
+          "operator": "odrl:eq",
+          "rightOperand": "marketing"
+        },
+        "target": "https://example.org/insight/delfour"
+      },
+      "type": "odrl:Policy"
+    }
+  },
+  "integrity": {
+    "canonicalEnvelope": "{\"insight\":{\"createdAt\":\"2025-10-05T20:33:48.907163+00:00\",\"expiresAt\":\"2025-10-05T22:33:48.907185+00:00\",\"id\":\"https://example.org/insight/delfour\",\"metric\":\"sugar_g_per_serving\",\"retailer\":\"Delfour\",\"scopeDevice\":\"self-scanner\",\"scopeEvent\":\"pick_up_scanner\",\"suggestionPolicy\":\"lower_metric_first_higher_price_ok\",\"threshold\":10.0,\"type\":\"ins:Insight\"},\"policy\":{\"duty\":{\"action\":\"odrl:delete\",\"constraint\":{\"leftOperand\":\"odrl:dateTime\",\"operator\":\"odrl:eq\",\"rightOperand\":\"2025-10-05T22:33:48.907185+00:00\"}},\"permission\":{\"action\":\"odrl:use\",\"constraint\":{\"leftOperand\":\"odrl:purpose\",\"operator\":\"odrl:eq\",\"rightOperand\":\"shopping_assist\"},\"target\":\"https://example.org/insight/delfour\"},\"profile\":\"Delfour-Insight-Policy\",\"prohibition\":{\"action\":\"odrl:distribute\",\"constraint\":{\"leftOperand\":\"odrl:purpose\",\"operator\":\"odrl:eq\",\"rightOperand\":\"marketing\"},\"target\":\"https://example.org/insight/delfour\"},\"type\":\"odrl:Policy\"}}",
+    "payloadHashSHA256": "e1ad69852c98ca7697a164dbc6f0ca28f873508a6676865dba37b81faa66ebcb",
+    "envelopeHmacSHA256": "518a84185e2975928c6c935dae6e251a071766078c6e9e70d6f583a1147728db",
+    "verificationMode": "trustedPrecomputedInput"
+  },
+  "answer": {
+    "sentence": "The scanner is allowed to use a neutral shopping insight and recommends Low-Sugar Tea Biscuits instead of Classic Tea Biscuits.",
+    "scannedProduct": "Classic Tea Biscuits",
+    "suggestedAlternative": "Low-Sugar Tea Biscuits",
+    "payloadHashSHA256": "e1ad69852c98ca7697a164dbc6f0ca28f873508a6676865dba37b81faa66ebcb",
+    "envelopeHmacSHA256": "518a84185e2975928c6c935dae6e251a071766078c6e9e70d6f583a1147728db"
+  },
+  "reasonWhy": [
+    "The phone desensitizes a diabetes-related household condition into a scoped low-sugar need, wraps it in an expiring Insight+Policy envelope, and signs it.",
+    "scanned product : Classic Tea Biscuits",
+    "suggested alternative: Low-Sugar Tea Biscuits",
+    "payload SHA-256 : e1ad69852c98ca7697a164dbc6f0ca28f873508a6676865dba37b81faa66ebcb",
+    "HMAC-SHA256 : 518a84185e2975928c6c935dae6e251a071766078c6e9e70d6f583a1147728db"
+  ],
+  "checks": {
+    "signatureVerifies": true,
+    "payloadHashMatches": true,
+    "minimizationRespected": true,
+    "scopeComplete": true,
+    "authorizationAllowed": true,
+    "highSugarBanner": true,
+    "alternativeLowersSugar": true,
+    "dutyTimingConsistent": true,
+    "marketingProhibited": true
+  },
+  "allChecksPass": true,
+  "arcText": "=== Answer ===\nThe scanner is allowed to use a neutral shopping insight and recommends Low-Sugar Tea Biscuits instead of Classic Tea Biscuits.\n\n=== Reason Why ===\nThe phone desensitizes a diabetes-related household condition into a scoped low-sugar need, wraps it in an expiring Insight+Policy envelope, and signs it.\nscanned product : Classic Tea Biscuits\nsuggested alternative: Low-Sugar Tea Biscuits\npayload SHA-256 : e1ad69852c98ca7697a164dbc6f0ca28f873508a6676865dba37b81faa66ebcb\nHMAC-SHA256 : 518a84185e2975928c6c935dae6e251a071766078c6e9e70d6f583a1147728db\n\n=== Check ===\nsignature verifies : yes\npayload hash matches : yes\nminimization strips sensitive terms: yes\nscope complete : yes\nauthorization allowed : yes\nhigh-sugar banner : yes\nalternative lowers sugar : yes\nduty timing consistent : yes\nmarketing prohibited : yes"
+}

package/examples/arc-bridge/delfour/delfour.instance.schema.json

@@ -0,0 +1,201 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.org/schema/delfour.instance.schema.json",
+  "title": "ARC Bridge Flandor instance",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "caseName",
+    "retailer",
+    "question",
+    "timestamps",
+    "evaluationContext",
+    "thresholds",
+    "householdProfile",
+    "catalog",
+    "scan",
+    "insightPolicy",
+    "integrity"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "caseName": {
+      "type": "string",
+      "minLength": 1
+    },
+    "retailer": {
+      "type": "string",
+      "minLength": 1
+    },
+    "question": {
+      "type": "string",
+      "minLength": 1
+    },
+    "timestamps": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["createdAt", "expiresAt", "authorizedAt", "dutyPerformedAt"],
+      "properties": {
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "authorizedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "dutyPerformedAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "evaluationContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scopeDevice", "scopeEvent", "purpose", "prohibitedReusePurpose", "requestAction"],
+      "properties": {
+        "scopeDevice": {
+          "type": "string",
+          "minLength": 1
+        },
+        "scopeEvent": {
+          "type": "string",
+          "minLength": 1
+        },
+        "purpose": {
+          "type": "string",
+          "minLength": 1
+        },
+        "prohibitedReusePurpose": {
+          "type": "string",
+          "minLength": 1
+        },
+        "requestAction": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "thresholds": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sugarPerServingGAtLeast"],
+      "properties": {
+        "sugarPerServingGAtLeast": {
+          "type": "number"
+        }
+      }
+    },
+    "householdProfile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["condition"],
+      "properties": {
+        "condition": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "catalog": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "name", "sugarTenths", "sugarPerServing"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sugarTenths": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "sugarPerServing": {
+            "type": "number",
+            "minimum": 0
+          }
+        }
+      }
+    },
+    "scan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scannedProductId"],
+      "properties": {
+        "scannedProductId": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "insightPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "metric", "type", "suggestionPolicy", "policyType", "policyProfile"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metric": {
+          "type": "string",
+          "minLength": 1
+        },
+        "type": {
+          "type": "string",
+          "minLength": 1
+        },
+        "suggestionPolicy": {
+          "type": "string",
+          "minLength": 1
+        },
+        "policyType": {
+          "type": "string",
+          "minLength": 1
+        },
+        "policyProfile": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "integrity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["hashAlgorithm", "macAlgorithm", "secret", "verificationMode"],
+      "properties": {
+        "hashAlgorithm": {
+          "type": "string",
+          "const": "SHA-256"
+        },
+        "macAlgorithm": {
+          "type": "string",
+          "const": "HMAC-SHA-256"
+        },
+        "secret": {
+          "type": "string",
+          "minLength": 1
+        },
+        "verificationMode": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}