eyeling 1.21.2 → 1.21.4

package/HANDBOOK.md

@@ -31,6 +31,7 @@
 - [Appendix D — LLM + Eyeling: A Repeatable Logic Toolchain](#app-d)
 - [Appendix E — How Eyeling reaches 100% on `notation3tests`](#app-e)
 - [Appendix F — The ARC approach: Answer • Reason Why • Check](#app-f)
+- [Appendix G — Eyeling and the W3C CG Notation3 Semantics](#app-g)
 
 ---
 
@@ -1572,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)
 
@@ -3104,3 +3109,63 @@ A file really follows ARC only when the answer, the explanation, and the validat
 ### F.9 Why this style is worth using
 
 This style is worth using because it makes an Eyeling file easier to run, easier to inspect, and easier to trust. The result is visible. The key reason is visible. The check is visible. That makes examples better teaching material, makes policy or computation examples easier to audit, and makes the whole file more reusable as a small reasoning artifact instead of an opaque session transcript.
+
+<a id="app-g"></a>
+
+## Appendix G — Eyeling and the W3C CG Notation3 Semantics
+
+The purpose of this appendix is to say where Eyeling tracks the [W3C CG Notation3 semantics](https://w3c.github.io/N3/spec/semantics) closely, and where Eyeling makes deliberate operational choices of its own.
+
+The comparison point here is the W3C CG Notation3 semantics document, not a claim that Eyeling is trying to be a line-by-line implementation of that document. Eyeling is a working reasoner, so some choices are shaped by execution, indexing, determinism, and the practical habits of N3 authors.
+
+### G.1 Where Eyeling is strongly aligned
+
+- **Core term model (IRIs, literals, variables, blank nodes, lists, quoted formulas):** The semantics document treats N3 terms as IRIs, literals, variables, lists, and graph terms. Eyeling’s internal model matches that shape directly through `Iri`, `Literal`, `Var`, `Blank`, `ListTerm`, and `GraphTerm`.
+
+- **Quoted formulas need alpha-equivalence / isomorphism:** The semantics document defines isomorphism for graphs and graph terms using consistent renaming. Eyeling implements the same practical idea operationally as alpha-equivalence for `GraphTerm`, with consistent renaming as the criterion for a match.
+
+- **Rules as implication (and `true` as empty formula):** The semantics document gives a special role to `log:implies` and treats `true` and `false` specially, with `true` corresponding to the empty formula. Eyeling follows that shape: it accepts both `{ P } => { C }` and `{ P } log:implies { C }`, and it treats `true` as `{}`.
+
+- **Lists as first-class citizens (not just RDF collections):** The semantics document treats lists as genuine N3 terms. Eyeling does the same through `ListTerm`, and also materializes RDF `rdf:first` / `rdf:rest` chains into list terms so one list model can be used throughout the engine.
+
+### G.2 Where Eyeling diverges or goes beyond the semantics document
+
+#### G.2.1 Blank nodes in rule bodies: Eyeling chooses common N3 rule-writing practice
+
+The semantics document describes blank nodes as existentially quantified with local scope. Eyeling intentionally rewrites blank nodes in **rule premises** into variables during normalization. In practice this makes body blanks behave like the placeholders many N3 authors expect when they write rules.
+
+That is a real semantic choice. It is useful and intentional, but it is not the same as reading blank nodes as existentials everywhere.
+
+#### G.2.2 Groundness of quoted formulas containing variables
+
+In the semantics document, whether a graph term is ground depends on whether the underlying graph is closed, and nested formulas can still contain free variables when viewed in isolation. Eyeling makes a pragmatic engine choice: variables inside a `GraphTerm` do not make the surrounding triple non-ground. In the handbook this is summarized as “variables inside formulas do not leak.”
+
+That supports indexing, matching, and duplicate checks, but it is not a one-to-one restatement of model-theoretic groundness for graph terms.
+
+#### G.2.3 Eyeling defines operational behavior beyond what the semantics document currently fixes
+
+The semantics document mainly fixes meaning around implication and the core N3 term/formula model. Eyeling goes further and gives operational meaning to a large standard library of builtins and control features. Examples include `math:*`, `string:*`, `list:*`, `time:*`, `log:includes`, `log:notIncludes`, `log:query`, and scoped closure via `log:conclusion`.
+
+So Eyeling is not only implementing the semantics document; it is also defining engine behavior for features that the current document does not fully specify.
+
+#### G.2.4 Inference fuses (`=> false`) are an engine-level procedural feature
+
+The semantics document discusses `false` in relation to implication and constraints. Eyeling turns `{ ... } => false` into an engine-level hard failure with a visible message and failing exit status. That is a practical tooling feature: it lets a rule act like a checked invariant.
+
+This is very useful in real programs, but it is an operational behavior of the reasoner, not something a model-theoretic semantics “executes.”
+
+#### G.2.5 Surface-language coverage is not the same thing as semantic alignment
+
+The semantics document discusses explicit quantification in its abstract syntax. Eyeling mostly exposes implicit quantification through `?x` variables and blank nodes, together with the rule-normalization choices described earlier. The handbook documents the supported surface forms Eyeling actually parses, which may be narrower than the full abstract surface discussed in the semantics document.
+
+So even where the underlying ideas line up, the accepted concrete syntax may still be a proper subset.
+
+### G.3 The practical takeaway
+
+A good short summary is this:
+
+- Eyeling is strongly aligned with the N3 semantics on the **core ontology of terms, quoted formulas, implication, and lists**.
+- Eyeling makes deliberate, implementation-shaped choices around **rule-body blanks, groundness of quoted formulas, and constraint execution**.
+- Eyeling also defines a wider operational language than the current semantics document, especially through builtins and scoped proof/query features.
+
+So the handbook and the semantics document are best read as complementary. The semantics document explains the abstract shape of Notation3. The handbook explains how a compact working reasoner realizes that shape, and where it chooses a practical execution model over a purely model-theoretic presentation.

package/README.md

@@ -16,5 +16,4 @@ echo '@prefix : <http://example.org/> .
 
 - **Handbook:** [eyereasoner.github.io/eyeling/HANDBOOK](https://eyereasoner.github.io/eyeling/HANDBOOK)
 - **Playground:** [eyereasoner.github.io/eyeling/demo](https://eyereasoner.github.io/eyeling/demo)
-- **Semantics:** [eyereasoner.github.io/eyeling/SEMANTICS](https://eyereasoner.github.io/eyeling/SEMANTICS)
 - **Conformance report:** [codeberg.org/phochste/notation3tests/.../report.md](https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md)

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"
+}