eyeling 1.22.1 → 1.22.3

package/examples/arcling/README.md

@@ -1,185 +1,55 @@
-# Arcling
+# ARC-style examples in Eyeling
 
-This directory holds **Arcling** cases.
+This page points to the ARC-style examples that currently live in [`examples/`](../). The files themselves are one level up; this folder exists as a convenient index for readers who want to browse Eyeling examples that follow the same presentation pattern.
 
-An Arcling case sits alongside the declarative N3 cases in `examples/`. Its purpose is to keep the ARC promise visible while making the case easy to read, easy to rerun, and easy to port.
+## What ARC is
 
-In one line:
+[ARC](https://josd.github.io/arc/) stands for **Answer • Reason Why • Check**. The idea is to make a program do three things at once: give the result, explain the small reason that matters, and include a check that can fail loudly when an assumption is wrong. In practice, ARC turns a runnable example into a small, auditable artifact rather than a black box.
 
-> `examples/arcling/` presents ARC cases in mathematical English with reference Go realizations and JSON test vectors.
+In Eyeling, ARC fits naturally: facts hold the data, rules derive the result, `log:outputString` can render a human-readable report, and `=> false` rules can act as hard validation fuses.
 
-## Insight Economy context
+## What the Insight Economy is
 
-The `delfour`, `medior`, and `flandor` cases are concrete Arcling readings of Ruben Verborgh’s [Inside the Insight Economy](https://ruben.verborgh.org/blog/2025/08/12/inside-the-insight-economy/). The central move is the same in all three cases: what gets traded is not risky raw data, but a narrow, expiring, purpose-bound insight that is useful enough to trigger action. In Ruben’s phrasing, the goal is to “don’t exchange raw data” and to prefer “meaningful insights, not risky raw data”.
+Ruben Verborgh’s [Insight Economy](https://ruben.verborgh.org/blog/2025/08/12/inside-the-insight-economy/) argues that raw data is a bad thing to trade directly. Instead of handing over the source data, a system should refine it into a **specific, purpose-limited, time-bound insight** that is useful in one context, loses value when copied, and can be governed more safely.
 
-In this directory, the three cases show that pattern across three settings:
+That makes the examples below especially relevant: Eyeling can derive those narrow insights explicitly, explain why they hold, and check that the resulting decision respects policy, purpose, and consistency constraints.
 
-- **Delfour** keeps a household-level medical condition private and turns it into a neutral shopping insight such as “prefer lower-sugar products” for shopping assistance.
-- **Medior** keeps laboratory, medication, and readmission evidence local and turns it into a minimal post-discharge coordination insight that can justify activating a continuity bundle.
-- **Flandor** keeps exporter, labour-market, and grid evidence local and turns it into a regional macro-economic insight that justifies a temporary retooling response.
+## ARC-style examples in `examples/`
 
-That progression is intentional: `delfour` is the micro case, `medior` is the care-coordination case, and `flandor` is the macro case. They are easiest to read next to their declarative Eyeling counterparts: `examples/delfour.n3`, `examples/medior.n3`, and `examples/flandor.n3`.
+### Insight Economy and governed-data cases
 
-## Why this directory exists
+- [`../auroracare.n3`](../auroracare.n3) — Purpose-based medical data exchange with explicit allow/deny reasoning and checks around role, purpose, and conditions.
+- [`../calidor.n3`](../calidor.n3) — Heatwave-response case where private household signals become a narrow, expiring cooling-support insight.
+- [`../delfour.n3`](../delfour.n3) — Shopping-assistance case where a private condition becomes a bounded “prefer lower-sugar products” insight.
+- [`../flandor.n3`](../flandor.n3) — Macro-economic coordination case for Flanders that turns sensitive local signals into a regional retooling insight.
+- [`../medior.n3`](../medior.n3) — Post-discharge care-coordination case that derives a minimal continuity-bundle insight without sharing the full record.
+- [`../parcellocker.n3`](../parcellocker.n3) — One-time parcel pickup authorization with a clear permit decision, justification, and misuse checks.
 
-Eyeling already has a strong way to present a case in declarative N3. Arcling adds a second presentation layer for cases that benefit from a normative mathematical-English statement plus a compact reference model.
+### Core ARC-style walkthroughs
 
-Each Arcling case gives you:
+- [`../bmi.n3`](../bmi.n3) — Body Mass Index calculation with normalization, WHO category assignment, and boundary checks.
+- [`../control-system.n3`](../control-system.n3) — Small control-system example that derives actuator commands and explains feedforward and feedback contributions.
+- [`../easter.n3`](../easter.n3) — Gregorian Easter computus with a readable explanation and date-window checks.
+- [`../french-cities.n3`](../french-cities.n3) — Graph reachability over French cities with explicit path reasoning.
+- [`../gps.n3`](../gps.n3) — Tiny route-planning example for western Belgium with route comparison and metric checks.
+- [`../resto.n3`](../resto.n3) — RESTdesc-style service composition from person and date to a concrete restaurant reservation.
+- [`../sudoku.n3`](../sudoku.n3) — Sudoku solver and report generator with consistency checks over the solved grid.
+- [`../wind-turbine.n3`](../wind-turbine.n3) — Predictive-maintenance example that turns sensor readings into an auditable inspection decision.
 
-- a **normative statement** in mathematical English,
-- a **reference realization** in Go,
-- a **concrete instance** in JSON,
-- and an **expected result** for comparison and regression testing.
+### Technical and scientific ARC demos
 
-So Arcling does not replace declarative Eyeling. It complements it.
+- [`../matrix-mechanics.n3`](../matrix-mechanics.n3) — Small 2×2 matrix example deriving trace, determinant, products, and a non-zero commutator.
+- [`../pn-junction-tunneling.n3`](../pn-junction-tunneling.n3) — Semiconductor toy model that explains current-proxy behavior across bias points.
+- [`../transistor-switch.n3`](../transistor-switch.n3) — NPN low-side switch model with exact arithmetic and cutoff-versus-saturation checks.
 
-## The ARC part
+### Deep-classification stress tests
 
-ARC means:
+- [`../deep-taxonomy-10.n3`](../deep-taxonomy-10.n3) — ARC-style deep-taxonomy benchmark at depth 10.
+- [`../deep-taxonomy-100.n3`](../deep-taxonomy-100.n3) — ARC-style deep-taxonomy benchmark at depth 100.
+- [`../deep-taxonomy-1000.n3`](../deep-taxonomy-1000.n3) — ARC-style deep-taxonomy benchmark at depth 1000.
+- [`../deep-taxonomy-10000.n3`](../deep-taxonomy-10000.n3) — ARC-style deep-taxonomy benchmark at depth 10000.
+- [`../deep-taxonomy-100000.n3`](../deep-taxonomy-100000.n3) — ARC-style deep-taxonomy benchmark at depth 100000.
 
-- **Answer**
-- **Reason Why**
-- **Check**
+## Why these examples fit together
 
-A good Arcling case preserves that trust pattern even though it is not written entirely 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/arcling/` when:
-
-- there is a useful ARC-style case in `examples/`,
-- there is value in giving the case a direct operational form,
-- we want the logic to stay explicit and auditable,
-- and we want 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.
-
-## The four files
-
-Each Arcling case should contain these files.
-
-### 1. `name.spec.md`
-
-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 Go 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.go`
-
-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:
-
-- `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.
-
-## How to read an Arcling case
-
-A good reading order is:
-
-1. start with `name.spec.md`,
-2. inspect `name.data.json`,
-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.
-
-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/arcling/` shows the same kind of cases in **mathematical-English specification plus reference Go form**.
-
-So the two collections are complementary:
-
-- **N3** is best for seeing the logic in the open,
-- **Arcling** is best for stating the case normatively and running a portable reference model.
-
-## 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 Go 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`, `medior`, or `flandor` in `examples/`, the Arcling 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 mathematical-English specification of the case.
-3. Move the concrete instance into JSON.
-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.
-
-## What Arcling is not
-
-Arcling 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/arcling/` presents ARC cases in mathematical English with reference Go realizations, JSON instances, and expected results, alongside declarative Eyeling examples.
+These files all present reasoning in a recognizably ARC-like way: they derive an answer, make the reason visible in a compact report, and include checks that are meant to catch real mistakes. Some are classical logic or numeric examples; others show how Eyeling can express policy-aware, insight-oriented decision flows without collapsing everything into opaque application code.