eyeling 1.22.0 → 1.22.2

package/examples/arcling/calidor/calidor.spec.md

@@ -0,0 +1,166 @@
+# Calidor — ARC Specification
+
+## Status
+
+This document is the normative specification for the Calidor case. The file `calidor.model.go` is the reference Go implementation of these clauses. The file `calidor.data.json` is the instance evaluated in this bundle. The file `calidor.expected.json` is the conformance vector for that instance.
+
+## Insight Economy context
+
+This case models municipal heatwave support. A household gateway observes local indoor heat stress, local vulnerability signals, and local prepaid-energy stress. Those raw details remain local. The system shares only a narrow, expiring insight that the household qualifies for priority cooling support during the current heat-alert window.
+
+The city may use that insight for heatwave response. It may not reuse it for unrelated purposes such as tenant screening.
+
+## Conventions
+
+- “iff” means “if and only if”.
+- A clause identifier such as `R1` or `G2` 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.
+- The reference implementation in this bundle is written in Go.
+- Input validation is part of the reference model. A malformed instance shall fail before evaluation.
+
+## Vocabulary
+
+**V1. Heat alert** is the municipal emergency context.
+
+**V2. Unsafe indoor heat** is sustained indoor temperature at or above the configured threshold.
+
+**V3. Vulnerability presence** is the existence of at least one local heat-sensitivity or mobility-related flag.
+
+**V4. Energy constraint** is insufficient prepaid energy credit to sustain cooling use.
+
+**V5. Support package** is a municipal assistance option with a cost and a set of capabilities.
+
+**V6. Insight envelope** is the ordered pair `(insight, policy)` together with integrity metadata.
+
+## Input instance
+
+**I1.** The municipality is `Calidor`.
+
+**I2.** The current heat alert level is `4`.
+
+**I3.** The alert threshold is `3`.
+
+**I4.** The current indoor temperature is `31.4` °C.
+
+**I5.** Unsafe indoor heat requires at least `30.0` °C for at least `6` hours.
+
+**I6.** The household has local vulnerability flags.
+
+**I7.** Remaining prepaid energy credit is `3.2` EUR.
+
+**I8.** Energy constraint holds at or below `5.0` EUR.
+
+**I9.** Priority cooling support requires at least `3` active needs.
+
+**I10.** The support catalog is the one listed in `calidor.data.json`.
+
+## Derivation clauses
+
+**R1. HeatAlertActive.** `HeatAlertActive` holds iff `currentAlertLevel ≥ alertLevelAtLeast`.
+
+**R2. UnsafeIndoorHeat.** `UnsafeIndoorHeat` holds iff:
+
+1. `currentIndoorTempC ≥ indoorTempCAtLeast`; and
+2. `hoursAtOrAboveThreshold ≥ hoursAtOrAboveThresholdAtLeast`.
+
+**R3. VulnerabilityPresent.** `VulnerabilityPresent` holds iff the local vulnerability flag list is non-empty.
+
+**R4. EnergyConstraint.** `EnergyConstraint` holds iff `remainingPrepaidCreditEur ≤ energyCreditEurAtMost`.
+
+**R5. ActiveNeedCount.** `ActiveNeedCount` is the number of true predicates among:
+
+- `HeatAlertActive`
+- `UnsafeIndoorHeat`
+- `VulnerabilityPresent`
+- `EnergyConstraint`
+
+**R6. PriorityCoolingSupportNeeded.** `PriorityCoolingSupportNeeded` holds iff `ActiveNeedCount ≥ minimumActiveNeedCount`.
+
+**R7. RequiredCapabilities.** The required capability set is formed as follows:
+
+1. if `HeatAlertActive` and `UnsafeIndoorHeat`, include `cooling_kit`;
+2. if `VulnerabilityPresent`, include `welfare_check` and `transport`;
+3. if `EnergyConstraint`, include `bill_credit`.
+
+The resulting set is sorted lexically for reporting.
+
+**R8. EligiblePackage(p).** For a package `p`, `EligiblePackage(p)` holds iff:
+
+1. `p.costEur ≤ maxPackageCostEur`; and
+2. `p.capabilities` cover every entry in `RequiredCapabilities`.
+
+**R9. RecommendedPackage.** `RecommendedPackage` is the eligible package with minimum `costEur`, breaking ties lexically by `id`.
+
+## Governance clauses
+
+**G1. AuthorizedUse.** `AuthorizedUse` holds iff:
+
+1. the requested action is `odrl:use`;
+2. the requested purpose is `heatwave_response`; and
+3. the authorization time is not later than the expiry time.
+
+**G2. TenantScreeningProhibited.** `TenantScreeningProhibited` holds iff the policy prohibits distribution for purpose `tenant_screening`.
+
+**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`, `municipality`, `scopeDevice`, `scopeEvent`, `supportPolicy`, `threshold`, `type`
+- policy: `duty`, `permission`, `profile`, `prohibition`, `type`
+
+For this case, `threshold` is serialized lexically as `3.0` rather than `3`, because the integrity vector is defined over those exact envelope bytes.
+
+**M2. PayloadHashMatches.** `PayloadHashMatches` holds iff the model-computed SHA-256 of `CanonicalEnvelope` equals the expected SHA-256 value recorded in the conformance vector.
+
+**M3. SignatureVerifies.** `SignatureVerifies` holds iff the model-computed HMAC-SHA-256 of `CanonicalEnvelope` equals the expected HMAC value recorded in the conformance vector.
+
+**M4. MinimizationRespected.** `MinimizationRespected` holds iff the serialized insight contains none of the forbidden terms:
+
+- `heat_sensitive_condition`
+- `mobility_limitation`
+- `credit`
+- `meter_trace`
+
+**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
+- recommended package
+- required capabilities
+- payload hash
+- envelope HMAC
+
+**O2. Reason Why.** A conforming renderer shall explain that raw household heat, vulnerability, and prepaid-energy details remain local and that only a narrow heatwave-response insight is shared.
+
+**O3. Check.** A conforming renderer shall expose a named yes/no or PASS/FAIL outcome for each of:
+
+- `signatureVerifies`
+- `payloadHashMatches`
+- `minimizationRespected`
+- `scopeComplete`
+- `authorizationAllowed`
+- `heatAlertActive`
+- `unsafeIndoorHeat`
+- `priorityCoolingSupportNeeded`
+- `recommendedPackageEligible`
+- `dutyTimingConsistent`
+- `tenantScreeningProhibited`
+
+## Reference outcome for this instance
+
+For the supplied instance:
+
+- `HeatAlertActive = true`
+- `UnsafeIndoorHeat = true`
+- `VulnerabilityPresent = true`
+- `EnergyConstraint = true`
+- `ActiveNeedCount = 4`
+- `PriorityCoolingSupportNeeded = true`
+- `RecommendedPackage = "Calidor Priority Cooling Bundle"`
+
+The expected ARC report and integrity values are recorded in `calidor.expected.json`.

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