eyeling 1.22.1 → 1.22.3

package/examples/arcling/delfour/delfour.spec.md

@@ -1,117 +0,0 @@
-# Delfour — ARC Specification
-
-## Status
-
-This document is the **normative specification** for the Delfour case. The file `delfour.model.go` is the **reference Go implementation** of these clauses. The file `delfour.data.json` is the **instance** evaluated in this bundle. The file `delfour.expected.json` is the **conformance vector** for that instance.
-
-## Insight Economy context
-
-This case is the household-scale reading of Ruben Verborgh’s [Inside the Insight Economy](https://ruben.verborgh.org/blog/2025/08/12/inside-the-insight-economy/). Its core claim is that a person can share a useful shopping hint without exposing sensitive health details. A phone turns a private condition into a neutral, limited insight such as "prefer lower-sugar products", attaches clear usage rules and an expiry time, and sends it to a store scanner.
-
-The scanner may use that insight to suggest a better product, but not for unrelated purposes such as marketing. The scanner does not need the diagnosis. It only needs the right shopping conclusion.
-
-## Conventions
-
-- “iff” means “if and only if”.
-- A clause identifier such as `R1` or `M3` is normative.
-- A conforming implementation may be written in any language, but it shall produce the same derived values and pass/fail outcomes for the supplied instance.
-
-## Vocabulary
-
-**V1. Household condition** is a private fact local to the phone.
-
-**V2. Low-sugar need** is a neutral shopping need derived from the household condition.
-
-**V3. Scanned product** is the product presently under consideration by the store self-scanner.
-
-**V4. Candidate alternative** is a catalog product considered as a possible substitute.
-
-**V5. Insight envelope** is the ordered pair `(insight, policy)` together with integrity metadata.
-
-## Input instance
-
-**I1.** The retailer is `Delfour`.
-
-**I2.** The household condition is `Diabetes`.
-
-**I3.** The scanned product is `Classic Tea Biscuits`.
-
-**I4.** The sugar threshold is `10.0` grams per serving.
-
-**I5.** The catalog contains the four products listed in `delfour.data.json`.
-
-## Derivation clauses
-
-**R1. NeedsLowSugar.** `NeedsLowSugar` holds iff the household condition is `Diabetes`.
-
-**R2. HighSugarScanned.** `HighSugarScanned` holds iff the scanned product has `sugarPerServing ≥ 10.0`.
-
-**R3. LowerSugarCandidate(p).** For a product `p`, `LowerSugarCandidate(p)` holds iff `p.sugarTenths < scannedProduct.sugarTenths`.
-
-**R4. RecommendedAlternative.** `RecommendedAlternative` is the candidate product with minimum `sugarTenths` among all products `p` such that `LowerSugarCandidate(p)` holds.
-
-**R5. AlternativeLowersSugar.** `AlternativeLowersSugar` holds iff the recommended alternative exists and has strictly lower `sugarTenths` than the scanned product.
-
-## Governance clauses
-
-**G1. AuthorizedUse.** `AuthorizedUse` holds iff:
-
-1. the requested action is `odrl:use`;
-2. the requested purpose is `shopping_assist`; and
-3. the authorization time is not later than the expiry time.
-
-**G2. MarketingProhibited.** `MarketingProhibited` holds iff the policy prohibits distribution for purpose `marketing`.
-
-**G3. DutyTimely.** `DutyTimely` holds iff the duty-performance time is not later than the expiry time.
-
-## Integrity and minimization clauses
-
-**M1. CanonicalEnvelope.** The canonical envelope string is the JSON serialization of the ordered pair `(insight, policy)` with keys emitted in this exact sequence:
-
-- insight: `createdAt`, `expiresAt`, `id`, `metric`, `retailer`, `scopeDevice`, `scopeEvent`, `suggestionPolicy`, `threshold`, `type`
-- policy: `duty`, `permission`, `profile`, `prohibition`, `type`
-
-For this case, `threshold` is serialized lexically as `10.0` rather than `10`, because the integrity vector is defined over the exact envelope bytes used by the specialized Delfour driver.
-
-**M2. PayloadHashMatches.** `PayloadHashMatches` holds iff `SHA-256(CanonicalEnvelope) = declaredPayloadHashSHA256`.
-
-**M3. SignatureVerifies.** `SignatureVerifies` holds iff the declared HMAC verifies under the agreed verification mode.
-
-**M4. MinimizationRespected.** `MinimizationRespected` holds iff the serialized insight contains none of the forbidden terms: `diabetes`, `medical`.
-
-**M5. ScopeComplete.** `ScopeComplete` holds iff the insight contains `scopeDevice`, `scopeEvent`, and `expiresAt`.
-
-## Output contract
-
-**O1. Answer.** A conforming renderer shall expose:
-
-- the main recommendation sentence
-- scanned product
-- suggested alternative
-- payload hash
-- envelope HMAC
-
-**O2. Reason Why.** A conforming renderer shall explain the household-to-insight desensitization and the scoped shopping purpose.
-
-**O3. Check.** A conforming renderer shall expose a named yes/no or PASS/FAIL outcome for each of:
-
-- signatureVerifies
-- payloadHashMatches
-- minimizationRespected
-- scopeComplete
-- authorizationAllowed
-- highSugarBanner
-- alternativeLowersSugar
-- dutyTimingConsistent
-- marketingProhibited
-
-## Reference outcome for this instance
-
-For the supplied instance:
-
-- `NeedsLowSugar = true`
-- `HighSugarScanned = true`
-- `RecommendedAlternative = "Low-Sugar Tea Biscuits"`
-- `AlternativeLowersSugar = true`
-
-The expected ARC report and integrity values are recorded in `delfour.expected.json`.

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

@@ -1,106 +0,0 @@
-{
-  "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?",
-  "timestamps": {
-    "createdAt": "2026-04-08T07:00:00+00:00",
-    "expiresAt": "2026-04-08T19:00:00+00:00",
-    "authorizedAt": "2026-04-08T09:15:00+00:00",
-    "dutyPerformedAt": "2026-04-08T18:30:00+00:00"
-  },
-  "evaluationContext": {
-    "scopeDevice": "economic-resilience-board",
-    "scopeEvent": "budget-prep-window",
-    "purpose": "regional_stabilization",
-    "prohibitedReusePurpose": "firm_surveillance"
-  },
-  "thresholds": {
-    "exportOrdersIndexBelow": 90,
-    "technicalVacancyRatePctAbove": 3.9,
-    "gridCongestionHoursAbove": 11,
-    "activeNeedCountAtLeast": 3
-  },
-  "signals": {
-    "clusters": [
-      {
-        "id": "cluster:ANT_CHEM",
-        "name": "Antwerp chemicals",
-        "exportOrdersIndex": 84,
-        "energyIntensity": 92
-      },
-      {
-        "id": "cluster:GNT_MFG",
-        "name": "Ghent manufacturing",
-        "exportOrdersIndex": 87,
-        "energyIntensity": 76
-      }
-    ],
-    "labourMarket": {
-      "technicalVacancyRatePct": 4.6
-    },
-    "grid": {
-      "congestionHours": 19,
-      "renewableCurtailmentMWh": 240
-    }
-  },
-  "budget": {
-    "windowName": "Q2 resilience window",
-    "maxMEUR": 140
-  },
-  "packages": [
-    {
-      "id": "pkg:TRAIN_070",
-      "name": "Flanders Skills Sprint",
-      "costMEUR": 70,
-      "workerCoverage": 900,
-      "gridReliefMW": 0,
-      "coversExportWeakness": false,
-      "coversSkillsStrain": true,
-      "coversGridStress": false
-    },
-    {
-      "id": "pkg:PORT_095",
-      "name": "Schelde Trade Buffer",
-      "costMEUR": 95,
-      "workerCoverage": 300,
-      "gridReliefMW": 10,
-      "coversExportWeakness": true,
-      "coversSkillsStrain": false,
-      "coversGridStress": false
-    },
-    {
-      "id": "pkg:RET_FLEX_120",
-      "name": "Flandor Retooling Pulse",
-      "costMEUR": 120,
-      "workerCoverage": 1200,
-      "gridReliefMW": 85,
-      "coversExportWeakness": true,
-      "coversSkillsStrain": true,
-      "coversGridStress": true
-    },
-    {
-      "id": "pkg:CORRIDOR_165",
-      "name": "Full Corridor Shock Shield",
-      "costMEUR": 165,
-      "workerCoverage": 1600,
-      "gridReliefMW": 110,
-      "coversExportWeakness": true,
-      "coversSkillsStrain": true,
-      "coversGridStress": true
-    }
-  ],
-  "insightPolicy": {
-    "id": "https://example.org/insight/flandor",
-    "metric": "regional_retooling_priority",
-    "type": "ins:Insight",
-    "suggestionPolicy": "lowest_cost_package_covering_all_active_needs",
-    "policyType": "odrl:Policy",
-    "policyProfile": "Flandor-Insight-Policy"
-  },
-  "integrity": {
-    "hashAlgorithm": "SHA-256",
-    "macAlgorithm": "HMAC-SHA-256",
-    "secret": "flandor-demo-shared-secret",
-    "verificationMode": "trustedPrecomputedInput"
-  }
-}

package/examples/arcling/flandor/flandor.expected.json

@@ -1,98 +0,0 @@
-{
-  "caseName": "Flandor",
-  "derived": {
-    "exportWeakness": true,
-    "skillsStrain": true,
-    "gridStress": true,
-    "activeNeedCount": 3,
-    "needsRetoolingPulse": true,
-    "eligiblePackageIds": ["pkg:RET_FLEX_120"],
-    "recommendedPackageId": "pkg:RET_FLEX_120",
-    "recommendedPackageName": "Flandor Retooling Pulse"
-  },
-  "envelope": {
-    "insight": {
-      "createdAt": "2026-04-08T07:00:00+00:00",
-      "expiresAt": "2026-04-08T19:00:00+00:00",
-      "id": "https://example.org/insight/flandor",
-      "metric": "regional_retooling_priority",
-      "region": "Flanders",
-      "scopeDevice": "economic-resilience-board",
-      "scopeEvent": "budget-prep-window",
-      "suggestionPolicy": "lowest_cost_package_covering_all_active_needs",
-      "threshold": 3,
-      "type": "ins:Insight"
-    },
-    "policy": {
-      "duty": {
-        "action": "odrl:delete",
-        "constraint": {
-          "leftOperand": "odrl:dateTime",
-          "operator": "odrl:eq",
-          "rightOperand": "2026-04-08T19:00:00+00:00"
-        }
-      },
-      "permission": {
-        "action": "odrl:use",
-        "constraint": {
-          "leftOperand": "odrl:purpose",
-          "operator": "odrl:eq",
-          "rightOperand": "regional_stabilization"
-        },
-        "target": "https://example.org/insight/flandor"
-      },
-      "profile": "Flandor-Insight-Policy",
-      "prohibition": {
-        "action": "odrl:distribute",
-        "constraint": {
-          "leftOperand": "odrl:purpose",
-          "operator": "odrl:eq",
-          "rightOperand": "firm_surveillance"
-        },
-        "target": "https://example.org/insight/flandor"
-      },
-      "type": "odrl:Policy"
-    }
-  },
-  "integrity": {
-    "canonicalEnvelope": "{\"insight\":{\"createdAt\":\"2026-04-08T07:00:00+00:00\",\"expiresAt\":\"2026-04-08T19:00:00+00:00\",\"id\":\"https://example.org/insight/flandor\",\"metric\":\"regional_retooling_priority\",\"region\":\"Flanders\",\"scopeDevice\":\"economic-resilience-board\",\"scopeEvent\":\"budget-prep-window\",\"suggestionPolicy\":\"lowest_cost_package_covering_all_active_needs\",\"threshold\":3,\"type\":\"ins:Insight\"},\"policy\":{\"duty\":{\"action\":\"odrl:delete\",\"constraint\":{\"leftOperand\":\"odrl:dateTime\",\"operator\":\"odrl:eq\",\"rightOperand\":\"2026-04-08T19:00:00+00:00\"}},\"permission\":{\"action\":\"odrl:use\",\"constraint\":{\"leftOperand\":\"odrl:purpose\",\"operator\":\"odrl:eq\",\"rightOperand\":\"regional_stabilization\"},\"target\":\"https://example.org/insight/flandor\"},\"profile\":\"Flandor-Insight-Policy\",\"prohibition\":{\"action\":\"odrl:distribute\",\"constraint\":{\"leftOperand\":\"odrl:purpose\",\"operator\":\"odrl:eq\",\"rightOperand\":\"firm_surveillance\"},\"target\":\"https://example.org/insight/flandor\"},\"type\":\"odrl:Policy\"}}",
-    "payloadHashSHA256": "78d840cbc98e98d07d97498e8bc1bab716df0fc0c7c221aeaa86644157cfcfb8",
-    "envelopeHmacSHA256": "a907547046c46af6550635d786c1ea82c05e8c119c0c302c132eb799710df96e",
-    "verificationMode": "trustedPrecomputedInput"
-  },
-  "answer": {
-    "name": "Flandor",
-    "region": "Flanders",
-    "metric": "regional_retooling_priority",
-    "activeNeedCount": 3,
-    "threshold": 3,
-    "recommendedPackage": "Flandor Retooling Pulse",
-    "budgetCapMEUR": 140,
-    "packageCostMEUR": 120,
-    "payloadHashSHA256": "78d840cbc98e98d07d97498e8bc1bab716df0fc0c7c221aeaa86644157cfcfb8",
-    "envelopeHmacSHA256": "a907547046c46af6550635d786c1ea82c05e8c119c0c302c132eb799710df96e"
-  },
-  "reasonWhy": [
-    "ExportWeakness holds because at least one cluster has exportOrdersIndex < 90 (Antwerp chemicals=84, Ghent manufacturing=87).",
-    "SkillsStrain holds because the technical vacancy rate is 4.6% and the threshold is > 3.9%.",
-    "GridStress holds because congestion hours = 19 and the threshold is > 11.",
-    "The recommendation rule selects the least-cost package that covers every active need and remains within budget.",
-    "The selected package is \"Flandor Retooling Pulse\" with cost \u20ac120M, workerCoverage=1200, gridReliefMW=85.",
-    "Use is permitted only for purpose \"regional_stabilization\" and expires at 2026-04-08T19:00:00+00:00."
-  ],
-  "checks": {
-    "payloadHashMatches": true,
-    "signatureVerifies": true,
-    "thresholdReached": true,
-    "scopeComplete": true,
-    "minimizationRespected": true,
-    "authorizationAllowed": true,
-    "dutyTimely": true,
-    "surveillanceReuseProhibited": true,
-    "packageWithinBudget": true,
-    "packageCoversAllActiveNeeds": true,
-    "lowestCostEligiblePackageChosen": true
-  },
-  "allChecksPass": true,
-  "arcText": "=== Answer ===\nName: Flandor\nRegion: Flanders\nMetric: regional_retooling_priority\nActive need count: 3/3\nRecommended package: Flandor Retooling Pulse\nBudget cap: \u20ac140M\nPackage cost: \u20ac120M\nPayload SHA-256: 78d840cbc98e98d07d97498e8bc1bab716df0fc0c7c221aeaa86644157cfcfb8\nEnvelope HMAC-SHA-256: a907547046c46af6550635d786c1ea82c05e8c119c0c302c132eb799710df96e\n\n=== Reason Why ===\nExportWeakness holds because at least one cluster has exportOrdersIndex < 90 (Antwerp chemicals=84, Ghent manufacturing=87).\nSkillsStrain holds because the technical vacancy rate is 4.6% and the threshold is > 3.9%.\nGridStress holds because congestion hours = 19 and the threshold is > 11.\nThe recommendation rule selects the least-cost package that covers every active need and remains within budget.\nThe selected package is \"Flandor Retooling Pulse\" with cost \u20ac120M, workerCoverage=1200, gridReliefMW=85.\nUse is permitted only for purpose \"regional_stabilization\" and expires at 2026-04-08T19:00:00+00:00.\n\n=== Check ===\n- PASS: payloadHashMatches\n- PASS: signatureVerifies\n- PASS: thresholdReached\n- PASS: scopeComplete\n- PASS: minimizationRespected\n- PASS: authorizationAllowed\n- PASS: dutyTimely\n- PASS: surveillanceReuseProhibited\n- PASS: packageWithinBudget\n- PASS: packageCoversAllActiveNeeds\n- PASS: lowestCostEligiblePackageChosen"
-}