eyeling 1.21.10 → 1.22.0

package/HANDBOOK.md

@@ -307,6 +307,31 @@ This avoids the “existential in the body” trap and matches how most rule aut
 
 Blanks in the **conclusion** are _not_ lifted — they remain blanks and later become existentials (Chapter 9).
 
+### 5.1.1 Quoted formulas keep their own blank-node scope
+
+There is one important exception to the “lift blanks in rule bodies” rule: **do not descend into a quoted formula** (`GraphTerm`) and lift the blanks that appear _inside_ it.
+
+So this rule body:
+
+```n3
+{
+  ( { ?S a :Subject } { [] a :Thing } ) log:conjunction ?Z.
+} => { ... }.
+```
+
+must keep the inner `[]` as a **formula-local blank node**. Eyeling should treat it as belonging to the quoted graph, not as a rule-body variable that escapes into the surrounding rule.
+
+That distinction matters because quoted formulas play **two different roles** in Eyeling:
+
+1. **Formula as data** — for example when constructing a formula with `log:conjunction` or storing `{ ... }` in a triple. In this role, local blanks stay blanks. They print as blank nodes and participate in alpha-equivalence only within that quoted formula.
+2. **Formula as a query pattern** — for example when `log:includes`, `log:notIncludes`, `log:collectAllIn`, or `log:forAllIn` prove a quoted formula. In that role, the builtin may treat the formula’s **local blanks existentially** while matching.
+
+The practical rule is:
+
+> **Rule normalization preserves blank-node scope inside quoted formulas; builtins may later interpret those preserved blanks as existential query placeholders when the formula is used as a pattern.**
+
+This separation is deliberate. It keeps `log:conjunction` and formula printing honest, while still allowing query-like builtins to match formulas containing local `[]` placeholders.
+
 ### 5.2 Builtin deferral in forward-rule bodies
 
 In a depth-first proof, the order of goals matters. Many built-ins only become informative once parts of the triple are **already instantiated** (for example comparisons, pattern tests, and other built-ins that don’t normally create bindings).
@@ -1481,6 +1506,24 @@ Also supported:
 
 - The object may be the literal `true`, meaning the empty formula, which is always included (subject to the priority gating above).
 
+**Important blank-node note:** when the goal formula is used as a **pattern**, Eyeling treats blank nodes that are **local to that quoted formula** as existential placeholders during the proof.
+
+So a pattern such as:
+
+```n3
+{ ?x :p [] }
+```
+
+means “find an `?x` that has some `:p` value”, not “find the specific blank node label printed here”.
+
+But that existential behavior is intentionally limited:
+
+- it applies only to blanks that are **owned by the quoted formula being proved**
+- it does **not** rename or relax terms that were already supplied by an outer substitution
+- it does **not** turn concrete members of already-bound lists or other already-ground structures into fresh variables
+
+That last point is easy to miss. A builtin may receive a formula after part of it has already been instantiated from outer bindings. Those substituted-in terms are fixed data, not fresh existential placeholders. Keeping that boundary sharp prevents accidental overmatching and keeps numeric/list-oriented examples stable.
+
 #### `log:notIncludes` (test)
 
 Negation-as-failure version: it succeeds iff `log:includes` would yield no solutions (under the same scoping rules).
@@ -1494,6 +1537,8 @@ Negation-as-failure version: it succeeds iff `log:includes` would yield no solut
 - Unifies `OutList` with that list.
 - If `OutList` is a blank node, Eyeling just checks satisfiable without binding/collecting.
 
+As with `log:includes`, blank nodes that are local to `WhereFormula` behave as existential query placeholders while that formula is being proved. But blanks that came from already-bound outer data remain fixed.
+
 This is essentially a list-producing “findall”.
 
 #### `log:forAllIn` (test)

package/examples/arcling/README.md

@@ -6,7 +6,7 @@ An Arcling case sits alongside the declarative N3 cases in `examples/`. Its purp
 
 In one line:
 
-> `examples/arcling/` presents ARC cases in mathematical English with reference ECMAScript realizations and JSON test vectors.
+> `examples/arcling/` presents ARC cases in mathematical English with reference Go realizations and JSON test vectors.
 
 ## Insight Economy context
 
@@ -27,7 +27,7 @@ Eyeling already has a strong way to present a case in declarative N3. Arcling ad
 Each Arcling case gives you:
 
 - a **normative statement** in mathematical English,
-- a **reference realization** in ECMAScript,
+- a **reference realization** in Go,
 - a **concrete instance** in JSON,
 - and an **expected result** for comparison and regression testing.
 
@@ -65,7 +65,7 @@ Typical uses:
 - cases with a stable logical core and a small executable shell,
 - cases that benefit from conformance-style testing.
 
-## The five files
+## The four files
 
 Each Arcling case should contain these files.
 
@@ -75,7 +75,7 @@ The normative case description.
 
 This file should use **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.
+The spec should be written so that a careful reader can understand the case without reading the Go source first.
 
 ### 2. `name.data.json`
 
@@ -83,40 +83,36 @@ 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`
+### 3. `name.model.go`
 
-The reference ECMAScript realization.
+The reference Go 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`
+- `clauseR1ExportWeakness`
+- `clauseS2RecommendedPackage`
+- `clauseG1AuthorizedUse`
+- `clauseM2PayloadHash`
 
 The model is not the normative source. It is the **reference realization** of the normative source.
 
+Input validation is part of the reference model. A malformed instance should fail before evaluation rather than requiring a separate schema artifact.
+
 ### 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 Arcling case
 
 A good reading order is:
 
 1. start with `name.spec.md`,
 2. inspect `name.data.json`,
-3. run `name.model.mjs`,
+3. run `go run name.model.go --json`,
 4. compare the result with `name.expected.json`,
 5. then relate the case back to its N3 counterpart.
 
@@ -127,7 +123,7 @@ That order keeps the meaning visible before the operational details.
 A useful mental model is:
 
 - `examples/` shows ARC cases in **declarative Eyeling form**,
-- `examples/arcling/` shows the same kind of cases in **mathematical-English specification plus reference ECMAScript form**.
+- `examples/arcling/` shows the same kind of cases in **mathematical-English specification plus reference Go form**.
 
 So the two collections are complementary:
 
@@ -144,7 +140,7 @@ The spec should say what the case means. It should not merely paraphrase the cod
 
 ### 2. Keep the code direct
 
-The ECMAScript model should say what it does and do what it says. Avoid unnecessary framework machinery.
+The Go model should say what it does and do what it says. Avoid unnecessary framework machinery.
 
 ### 3. Keep the data separate
 
@@ -163,7 +159,7 @@ If a case is called `delfour`, `medior`, or `flandor` in `examples/`, the Arclin
 1. Start from a strong ARC-style N3 example.
 2. Write a mathematical-English specification of the case.
 3. Move the concrete instance into JSON.
-4. Implement a small ECMAScript reference model.
+4. Implement a small Go reference model.
 5. Capture the expected result in JSON.
 6. Keep the visible output in Answer / Reason Why / Check shape.
 7. Link the Arcling case to its N3 counterpart.
@@ -186,4 +182,4 @@ It exists to make a case simultaneously:
 
 ## In one line
 
-`examples/arcling/` presents ARC cases in mathematical English with reference ECMAScript realizations, JSON instances, and expected results, alongside declarative Eyeling examples.
+`examples/arcling/` presents ARC cases in mathematical English with reference Go realizations, JSON instances, and expected results, alongside declarative Eyeling examples.