eyeling 1.22.0 → 1.22.1

package/examples/arcling/delfour/delfour.data.json

@@ -1,5 +1,4 @@
 {
-  "$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?",

package/examples/arcling/delfour/delfour.model.go

@@ -1,5 +1,10 @@
 package main
 
+// Delfour is a reference Arcling model written as a small CLI program.
+// It reads delfour.data.json, derives the neutral shopping insight,
+// computes the canonical envelope/hash/HMAC values, and emits either
+// ARC text or a JSON result object.
+
 import (
 	"crypto/hmac"
 	"crypto/sha256"
@@ -13,6 +18,7 @@ import (
 	"time"
 )
 
+// Data mirrors the input instance shape from delfour.data.json.
 type Data struct {
 	CaseName          string            `json:"caseName"`
 	Retailer          string            `json:"retailer"`
@@ -77,6 +83,7 @@ type Integrity struct {
 	VerificationMode string `json:"verificationMode"`
 }
 
+// Insight is the minimized payload shared with the retailer.
 type Insight struct {
 	CreatedAt        string  `json:"createdAt"`
 	ExpiresAt        string  `json:"expiresAt"`
@@ -191,6 +198,7 @@ func readJSON(path string) (Data, error) {
 	return data, err
 }
 
+// validate performs the structural checks that used to live in JSON Schema.
 func validate(data Data) error {
 	if err := must(data.CaseName != "", "caseName is required"); err != nil {
 		return err
@@ -234,6 +242,7 @@ func validate(data Data) error {
 	return nil
 }
 
+// parseTime accepts RFC3339Nano timestamps from the case instance.
 func parseTime(s string) time.Time {
 	t, err := time.Parse(time.RFC3339Nano, s)
 	if err != nil {
@@ -242,6 +251,7 @@ func parseTime(s string) time.Time {
 	return t
 }
 
+// findProduct resolves the scanned or recommended product by its catalog id.
 func findProduct(data Data, id string) *Product {
 	for i := range data.Catalog {
 		if data.Catalog[i].ID == id {
@@ -251,6 +261,7 @@ func findProduct(data Data, id string) *Product {
 	return nil
 }
 
+// deriveInsight strips the household condition down to the neutral shopping insight.
 func deriveInsight(data Data) Insight {
 	return Insight{
 		CreatedAt:        data.Timestamps.CreatedAt,
@@ -266,6 +277,7 @@ func deriveInsight(data Data) Insight {
 	}
 }
 
+// derivePolicy builds the companion ODRL-style policy used for governance checks.
 func derivePolicy(data Data) Policy {
 	return Policy{
 		Duty: Duty{
@@ -299,6 +311,8 @@ func derivePolicy(data Data) Policy {
 	}
 }
 
+// canonicalEnvelope returns the exact byte string used for the integrity vector.
+// The field order and the lexical form of threshold (10.0) are intentional.
 func canonicalEnvelope(insight Insight, policy Policy) string {
 	return fmt.Sprintf(
 		"{\"insight\":{\"createdAt\":\"%s\",\"expiresAt\":\"%s\",\"id\":\"%s\",\"metric\":\"%s\",\"retailer\":\"%s\",\"scopeDevice\":\"%s\",\"scopeEvent\":\"%s\",\"suggestionPolicy\":\"%s\",\"threshold\":10.0,\"type\":\"%s\"},\"policy\":{\"duty\":{\"action\":\"%s\",\"constraint\":{\"leftOperand\":\"%s\",\"operator\":\"%s\",\"rightOperand\":\"%s\"}},\"permission\":{\"action\":\"%s\",\"constraint\":{\"leftOperand\":\"%s\",\"operator\":\"%s\",\"rightOperand\":\"%s\"},\"target\":\"%s\"},\"profile\":\"%s\",\"prohibition\":{\"action\":\"%s\",\"constraint\":{\"leftOperand\":\"%s\",\"operator\":\"%s\",\"rightOperand\":\"%s\"},\"target\":\"%s\"},\"type\":\"%s\"}}",
@@ -348,6 +362,8 @@ func yesNo(v bool) string {
 	return "no"
 }
 
+// evaluate runs the full Arcling pipeline: derive facts, select the recommendation,
+// build the envelope, verify integrity values, and render the final report.
 func evaluate(data Data) (Result, error) {
 	var result Result
 	if err := validate(data); err != nil {
@@ -508,6 +524,8 @@ func evaluate(data Data) (Result, error) {
 	return result, nil
 }
 
+// main is a tiny CLI wrapper around evaluate. It defaults to delfour.data.json,
+// prints ARC text, and switches to JSON output when --json is supplied.
 func main() {
 	inputPath := "delfour.data.json"
 	jsonMode := false

package/examples/arcling/flandor/flandor.data.json

@@ -1,5 +1,4 @@
 {
-  "$schema": "./flandor.instance.schema.json",
   "caseName": "Flandor",
   "region": "Flanders",
   "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?",

package/examples/arcling/flandor/flandor.model.go

@@ -1,5 +1,9 @@
 package main
 
+// Flandor is a reference Arcling model for the regional retooling-pulse case.
+// It evaluates whether a region needs intervention, selects the lowest-cost
+// eligible package, and emits ARC text or a JSON report.
+
 import (
 	"crypto/hmac"
 	"crypto/sha256"
@@ -13,6 +17,7 @@ import (
 	"time"
 )
 
+// Data mirrors the input instance shape from flandor.data.json.
 type Data struct {
 	CaseName          string            `json:"caseName"`
 	Region            string            `json:"region"`
@@ -233,6 +238,8 @@ func parseTime(value string) time.Time {
 	return t
 }
 
+// stableStringify recursively sorts map keys so the canonical envelope is
+// deterministic across runs and implementations.
 func stableStringify(value any) string {
 	switch v := value.(type) {
 	case nil:
@@ -260,6 +267,8 @@ func stableStringify(value any) string {
 	}
 }
 
+// canonicalValue converts typed structs into generic JSON-like values before
+// stable stringification.
 func canonicalValue(value any) any {
 	b, _ := json.Marshal(value)
 	var out any
@@ -267,6 +276,7 @@ func canonicalValue(value any) any {
 	return out
 }
 
+// validateInstance performs the structural checks for the 4-file bundle.
 func validateInstance(data Data) error {
 	if err := assertTrue(data.CaseName != "", "caseName is required"); err != nil {
 		return err
@@ -283,6 +293,7 @@ func validateInstance(data Data) error {
 	return nil
 }
 
+// countTrue is used for the active-need threshold logic in the spec.
 func countTrue(values ...bool) int {
 	total := 0
 	for _, value := range values {
@@ -293,6 +304,7 @@ func countTrue(values ...bool) int {
 	return total
 }
 
+// The R* helpers map directly to named derivation clauses in flandor.spec.md.
 func clauseR1ExportWeakness(data Data) bool {
 	for _, cluster := range data.Signals.Clusters {
 		if cluster.ExportOrdersIndex < data.Thresholds.ExportOrdersIndexBelow {
@@ -318,6 +330,7 @@ func clauseR5NeedsRetoolingPulse(data Data, activeNeedCount int) bool {
 	return activeNeedCount >= data.Thresholds.ActiveNeedCountAtLeast
 }
 
+// deriveInsight produces the minimized regional signal shared with the recipient.
 func deriveInsight(data Data) Insight {
 	return Insight{
 		CreatedAt:        data.Timestamps.CreatedAt,
@@ -333,6 +346,7 @@ func deriveInsight(data Data) Insight {
 	}
 }
 
+// derivePolicy constructs the usage restrictions paired with the insight.
 func derivePolicy(data Data) Policy {
 	return Policy{
 		Duty: Duty{
@@ -366,12 +380,16 @@ func derivePolicy(data Data) Policy {
 	}
 }
 
+// packageCoversAllActiveNeeds checks whether a candidate package addresses every
+// need that is active for this specific instance.
 func packageCoversAllActiveNeeds(pkg Package, exportWeakness, skillsStrain, gridStress bool) bool {
 	return (!exportWeakness || pkg.CoversExportWeakness) &&
 		(!skillsStrain || pkg.CoversSkillsStrain) &&
 		(!gridStress || pkg.CoversGridStress)
 }
 
+// clauseS1EligiblePackages filters to packages that both fit the budget and
+// cover the active needs.
 func clauseS1EligiblePackages(data Data, exportWeakness, skillsStrain, gridStress bool) []Package {
 	eligible := make([]Package, 0)
 	for _, pkg := range data.Packages {
@@ -383,6 +401,8 @@ func clauseS1EligiblePackages(data Data, exportWeakness, skillsStrain, gridStres
 	return eligible
 }
 
+// clauseS2RecommendedPackage applies the tie-breaker: choose the lowest-cost
+// eligible package after sorting by cost.
 func clauseS2RecommendedPackage(data Data, exportWeakness, skillsStrain, gridStress bool) ([]Package, *Package) {
 	eligible := clauseS1EligiblePackages(data, exportWeakness, skillsStrain, gridStress)
 	if len(eligible) == 0 {
@@ -404,6 +424,8 @@ func clauseG3DutyTimely(data Data) bool {
 	return !parseTime(data.Timestamps.DutyPerformedAt).After(parseTime(data.Timestamps.ExpiresAt))
 }
 
+// clauseM1CanonicalEnvelope returns both the structured envelope and the
+// deterministic string hashed/signed by the integrity clauses.
 func clauseM1CanonicalEnvelope(data Data) (Envelope, string) {
 	envelope := Envelope{Insight: deriveInsight(data), Policy: derivePolicy(data)}
 	return envelope, stableStringify(canonicalValue(envelope))
@@ -437,6 +459,8 @@ func yesNo(value bool) string {
 	return "FAIL"
 }
 
+// evaluate computes all derived facts, governance checks, integrity values,
+// and presentation fields expected by flandor.expected.json.
 func evaluate(data Data) (Result, error) {
 	if err := validateInstance(data); err != nil {
 		return Result{}, err
@@ -593,6 +617,7 @@ func derefIntString(value *int) string {
 	return fmt.Sprintf("%d", *value)
 }
 
+// main is the CLI entry point used by the Arcling test runner.
 func main() {
 	inputPath := "flandor.data.json"
 	jsonMode := false

package/examples/arcling/medior/medior.data.json

@@ -1,5 +1,4 @@
 {
-  "$schema": "./medior.instance.schema.json",
   "caseName": "Medior",
   "region": "Flanders",
   "question": "Is the discharge coordination team allowed to use a minimal continuity insight after hospital discharge, and if so which package should it activate?",

package/examples/arcling/medior/medior.model.go

@@ -1,5 +1,9 @@
 package main
 
+// Medior is a reference Arcling model for the care-continuity bundle case.
+// It derives active needs from coarse signals, selects the lowest-cost eligible
+// package, and emits ARC text or a JSON report.
+
 import (
 	"crypto/hmac"
 	"crypto/sha256"
@@ -13,6 +17,7 @@ import (
 	"time"
 )
 
+// Data mirrors the input instance shape from medior.data.json.
 type Data struct {
 	CaseName          string            `json:"caseName"`
 	Region            string            `json:"region"`
@@ -234,6 +239,8 @@ func parseTime(value string) time.Time {
 	return t
 }
 
+// stableStringify recursively sorts map keys so the canonical envelope stays
+// byte-stable across runs and languages.
 func stableStringify(value any) string {
 	switch v := value.(type) {
 	case nil:
@@ -261,6 +268,8 @@ func stableStringify(value any) string {
 	}
 }
 
+// canonicalValue converts typed structs into generic JSON-like values before
+// stable stringification.
 func canonicalValue(value any) any {
 	b, _ := json.Marshal(value)
 	var out any
@@ -268,6 +277,7 @@ func canonicalValue(value any) any {
 	return out
 }
 
+// validateInstance performs the structural checks for the 4-file bundle.
 func validateInstance(data Data) error {
 	if err := assertTrue(data.CaseName != "", "caseName is required"); err != nil {
 		return err
@@ -281,6 +291,7 @@ func validateInstance(data Data) error {
 	return nil
 }
 
+// countTrue is used for the active-need threshold logic in the spec.
 func countTrue(values ...bool) int {
 	total := 0
 	for _, value := range values {
@@ -291,6 +302,7 @@ func countTrue(values ...bool) int {
 	return total
 }
 
+// The R* helpers map directly to named derivation clauses in medior.spec.md.
 func clauseR1RenalSafetyConcern(data Data) bool {
 	return data.Signals.Lab.Egfr < data.Thresholds.EgfrBelow
 }
@@ -315,6 +327,8 @@ func clauseR6NeedsContinuityBundle(data Data, activeNeedCount int) bool {
 	return activeNeedCount >= data.Thresholds.ActiveNeedCountAtLeast
 }
 
+// deriveInsight produces the minimized care-coordination signal shared with
+// the recipient.
 func deriveInsight(data Data) Insight {
 	return Insight{
 		CreatedAt:        data.Timestamps.CreatedAt,
@@ -330,6 +344,7 @@ func deriveInsight(data Data) Insight {
 	}
 }
 
+// derivePolicy constructs the usage restrictions paired with the insight.
 func derivePolicy(data Data) Policy {
 	return Policy{
 		Duty: Duty{
@@ -363,6 +378,8 @@ func derivePolicy(data Data) Policy {
 	}
 }
 
+// packageCoversAllActiveNeeds checks whether a candidate package addresses every
+// active need in this instance.
 func packageCoversAllActiveNeeds(pkg Package, renalSafetyConcern, polypharmacyRisk, readmissionHistory, recentDischargeWindow bool) bool {
 	return (!renalSafetyConcern || pkg.CoversRenalSafetyConcern) &&
 		(!polypharmacyRisk || pkg.CoversPolypharmacyRisk) &&
@@ -370,6 +387,8 @@ func packageCoversAllActiveNeeds(pkg Package, renalSafetyConcern, polypharmacyRi
 		(!recentDischargeWindow || pkg.CoversRecentDischargeWindow)
 }
 
+// clauseS1EligiblePackages filters to packages that both fit the budget and
+// cover the active needs.
 func clauseS1EligiblePackages(data Data, renalSafetyConcern, polypharmacyRisk, readmissionHistory, recentDischargeWindow bool) []Package {
 	eligible := make([]Package, 0)
 	for _, pkg := range data.Packages {
@@ -381,6 +400,8 @@ func clauseS1EligiblePackages(data Data, renalSafetyConcern, polypharmacyRisk, r
 	return eligible
 }
 
+// clauseS2RecommendedPackage applies the tie-breaker: choose the lowest-cost
+// eligible package after sorting by cost.
 func clauseS2RecommendedPackage(data Data, renalSafetyConcern, polypharmacyRisk, readmissionHistory, recentDischargeWindow bool) ([]Package, *Package) {
 	eligible := clauseS1EligiblePackages(data, renalSafetyConcern, polypharmacyRisk, readmissionHistory, recentDischargeWindow)
 	if len(eligible) == 0 {
@@ -402,6 +423,8 @@ func clauseG3DutyTimely(data Data) bool {
 	return !parseTime(data.Timestamps.DutyPerformedAt).After(parseTime(data.Timestamps.ExpiresAt))
 }
 
+// clauseM1CanonicalEnvelope returns both the structured envelope and the
+// deterministic string hashed/signed by the integrity clauses.
 func clauseM1CanonicalEnvelope(data Data) (Envelope, string) {
 	envelope := Envelope{Insight: deriveInsight(data), Policy: derivePolicy(data)}
 	return envelope, stableStringify(canonicalValue(envelope))
@@ -435,6 +458,8 @@ func yesNo(value bool) string {
 	return "FAIL"
 }
 
+// evaluate computes all derived facts, governance checks, integrity values,
+// and presentation fields expected by medior.expected.json.
 func evaluate(data Data) (Result, error) {
 	if err := validateInstance(data); err != nil {
 		return Result{}, err
@@ -589,6 +614,7 @@ func derefIntString(value *int) string {
 	return fmt.Sprintf("%d", *value)
 }
 
+// main is the CLI entry point used by the Arcling test runner.
 func main() {
 	inputPath := "medior.data.json"
 	jsonMode := false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.22.0",
+  "version": "1.22.1",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [

package/test/arcling.test.js

@@ -6,22 +6,30 @@ const assert = require('node:assert/strict');
 const { execFileSync } = require('node:child_process');
 
 const TTY = process.stdout.isTTY;
-const C = TTY ? { g: '', r: '', y: '', dim: '', n: '' } : { g: '', r: '', y: '', dim: '', n: '' };
-const msTag = (ms) => `${C.dim}(${ms} ms)${C.n}`;
+const C = TTY
+  ? { g: '\u001b[32m', r: '\u001b[31m', y: '\u001b[33m', dim: '\u001b[2m', n: '\u001b[0m' }
+  : { g: '', r: '', y: '', dim: '', n: '' };
+
+const ROOT = path.resolve(__dirname, '..');
+const ARCLING_DIR = path.join(ROOT, 'examples', 'arcling');
+const BIN_DIR_NAME = '.arcling-bin';
+
+function msTag(ms) {
+  return `${C.dim}(${ms} ms)${C.n}`;
+}
 
 function ok(msg) {
   console.log(`${C.g}OK ${C.n} ${msg}`);
 }
+
 function info(msg) {
   console.log(`${C.y}==${C.n} ${msg}`);
 }
+
 function fail(msg) {
   console.error(`${C.r}FAIL${C.n} ${msg}`);
 }
 
-const ROOT = path.resolve(__dirname, '..');
-const ARCLING_DIR = path.join(ROOT, 'examples', 'arcling');
-
 function isDirectory(p) {
   try {
     return fs.statSync(p).isDirectory();
@@ -71,12 +79,41 @@ function findCaseFiles(caseDir) {
   return { base, modelPath, dataPath, expectedPath };
 }
 
-function runModelJson(modelPath, dataPath) {
+function binaryExtension() {
+  return process.platform === 'win32' ? '.exe' : '';
+}
+
+function binaryPathFor(caseDir, base) {
+  return path.join(caseDir, BIN_DIR_NAME, `${base}.model${binaryExtension()}`);
+}
+
+function ensureGoBinary(modelPath, caseDir, base) {
+  const outDir = path.join(caseDir, BIN_DIR_NAME);
+  const outPath = binaryPathFor(caseDir, base);
+
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const modelStat = fs.statSync(modelPath);
+  const needsBuild = !fs.existsSync(outPath) || fs.statSync(outPath).mtimeMs < modelStat.mtimeMs;
+
+  if (needsBuild) {
+    execFileSync('go', ['build', '-o', outPath, modelPath], {
+      cwd: caseDir,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+  }
+
+  return outPath;
+}
+
+function runModelJson(modelPath, dataPath, caseDir, base) {
   const ext = path.extname(modelPath);
 
   if (ext === '.go') {
-    const stdout = execFileSync('go', ['run', modelPath, dataPath, '--json'], {
-      cwd: path.dirname(modelPath),
+    const binaryPath = ensureGoBinary(modelPath, caseDir, base);
+    const stdout = execFileSync(binaryPath, [dataPath, '--json'], {
+      cwd: caseDir,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -85,7 +122,7 @@ function runModelJson(modelPath, dataPath) {
 
   if (ext === '.mjs') {
     const stdout = execFileSync(process.execPath, [modelPath, dataPath, '--json'], {
-      cwd: path.dirname(modelPath),
+      cwd: caseDir,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -104,15 +141,14 @@ function assertArcTextShape(arcText, label) {
 
 async function runCase(caseDir) {
   const { base, modelPath, dataPath, expectedPath } = findCaseFiles(caseDir);
-  const data = readJson(dataPath);
   const expected = readJson(expectedPath);
-  const actual = runModelJson(modelPath, dataPath);
+  const actual = runModelJson(modelPath, dataPath, caseDir, base);
 
   assert.equal(actual.allChecksPass, true, `${base}: expected allChecksPass === true`);
   assertArcTextShape(actual.arcText, base);
   assert.deepStrictEqual(actual, expected, `${base}: actual result does not match expected JSON`);
 
-  return { base, caseName: data.caseName, modelPath };
+  return { base, modelPath };
 }
 
 async function main() {
@@ -130,15 +166,14 @@ async function main() {
   for (let i = 0; i < caseDirs.length; i += 1) {
     const start = Date.now();
     const caseDir = caseDirs[i];
-    const n = i + 1;
     const label = path.basename(caseDir);
 
     try {
       await runCase(caseDir);
       passed += 1;
-      ok(`${n}. ${label} ${msTag(Date.now() - start)}`);
+      ok(`${i + 1}. ${label} ${msTag(Date.now() - start)}`);
     } catch (error) {
-      fail(`${n}. ${label} ${msTag(Date.now() - start)}`);
+      fail(`${i + 1}. ${label} ${msTag(Date.now() - start)}`);
       fail(error.stack || String(error));
       process.exit(2);
     }