feat(schemas): Twin World-Model & GAIA + EvalItem pack

Makefile

@@ -1,12 +1,20 @@
-.PHONY: validate validate-resource-contract validate-measurement validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement
+.PHONY: validate validate-resource-contract validate-measurement validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement validate-world-model-examples validate-eval-item-examples
 
-validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement validate-resource-contract
+validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement validate-world-model-examples validate-eval-item-examples validate-resource-contract
 	@echo "OK: validate"
 
 validate-genesis-inception-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_genesis_inception_examples.py
 
+validate-world-model-examples:
+	python3 -m pip install --user jsonschema >/dev/null
+	python3 tools/validate_world_model_examples.py
+
+validate-eval-item-examples:
+	python3 -m pip install --user jsonschema >/dev/null
+	python3 tools/validate_eval_item_examples.py
+
 validate-agent-system-vocabulary:
 	python3 tools/validate_agent_system_vocabulary.py
 

examples/eval-item.json

@@ -0,0 +1,18 @@
+{
+  "type": "EvalItem",
+  "id": "ev:B/evidence_answer/00123",
+  "source": "internal",
+  "corpus": "B",
+  "task_family": "evidence_answer",
+  "user_question": "A customer reports that release 2026.7 broke SSO for their Okta tenant. Given the linked incident and changelog, what is the root cause and the exact remediation step?",
+  "context_doc_ids": ["inc:2026-07-29/sso-okta", "changelog:2026.7", "kb:okta-saml-clock-skew"],
+  "expected_answer_traits": [
+    "names the SAML clock-skew tolerance change in 2026.7 as the cause",
+    "cites the changelog entry and the incident",
+    "gives the exact config remediation, not a generic 'contact support'",
+    "does not fabricate a CVE or a version that does not appear in context"
+  ],
+  "gold_citations": ["changelog:2026.7#saml-clock-skew", "inc:2026-07-29/sso-okta#rootcause"],
+  "grading_method": "citation_faithfulness",
+  "risk_class": "high"
+}

examples/gaia-observation.json

@@ -0,0 +1,11 @@
+{
+  "type": "GaiaObservation",
+  "observation_id": "gaia:obs/2026-07-31T12:00Z/8928308280fffff/hazard_index",
+  "gaia_cell": { "system": "h3", "cell": "8928308280fffff" },
+  "field": "hazard_index",
+  "value": 0.62,
+  "unit": "index_0_1",
+  "valid_time": "2026-07-31T12:00:00Z",
+  "source": "twc",
+  "provenance_refs": ["gaia:ingest/twc/2026-07-31T12:00Z", "receipt:compute-gateway/materialize/9f2a"]
+}

examples/impulse-gate.json

@@ -0,0 +1,9 @@
+{
+  "type": "ImpulseGate",
+  "gate_id": "gate:twn_mkt-0001/exogenous_shock",
+  "impulse_class": "exogenous_shock",
+  "mode": "attenuated",
+  "gate_factor": 0.35,
+  "fail_closed": true,
+  "admission_rule": "GAIA hazard_index shocks admitted at 0.35 unless the twin is verified and the region is under an active advisory, in which case escalate to human_action gate."
+}

examples/impulse.json

@@ -0,0 +1,13 @@
+{
+  "type": "Impulse",
+  "impulse_id": "imp:twn_mkt-0001/000042",
+  "twin_id": "twn_mkt-0001",
+  "impulse_class": "exogenous_shock",
+  "source": "gaia",
+  "magnitude": 0.62,
+  "target_dims": ["risk", "drift"],
+  "gate_state": "attenuated",
+  "admitted": true,
+  "source_ref": "gaia:obs/2026-07-31T12:00Z/8928308280fffff/hazard_index",
+  "provenance_refs": ["gate:twn_mkt-0001/exogenous_shock", "gaia:obs/2026-07-31T12:00Z/8928308280fffff/hazard_index"]
+}

examples/region.json

@@ -0,0 +1,8 @@
+{
+  "type": "Region",
+  "region_id": "region:au/sydney-ashore",
+  "name": "Sydney · ASX",
+  "centroid": { "lat": -33.87, "lon": 151.21 },
+  "bbox": [150.5, -34.2, 151.6, -33.5],
+  "gaia_cells": ["8928308280fffff", "8928308281fffff", "89283082837ffff"]
+}

examples/state-vector.json

@@ -0,0 +1,8 @@
+{
+  "type": "StateVector",
+  "twin_id": "twn_mkt-0001",
+  "seq": 42,
+  "at": "2026-07-31T12:00:03Z",
+  "dims": { "integrity": 0.88, "risk": 0.61, "load": 0.44, "coverage": 0.72, "drift": 0.39 },
+  "provenance_refs": ["imp:twn_mkt-0001/000042"]
+}

examples/world-model.json

@@ -0,0 +1,19 @@
+{
+  "type": "WorldModel",
+  "model_id": "wm:twn_mkt-0001",
+  "twin_id": "twn_mkt-0001",
+  "state_dims": ["integrity", "risk", "load", "coverage", "drift"],
+  "dynamics": {
+    "relaxation": 0.90,
+    "baseline": { "integrity": 0.85, "risk": 0.30, "load": 0.40, "coverage": 0.70, "drift": 0.20 }
+  },
+  "gates": [
+    { "impulse_class": "device_reading", "mode": "open" },
+    { "impulse_class": "market_data_event", "mode": "open" },
+    { "impulse_class": "exogenous_shock", "mode": "attenuated" },
+    { "impulse_class": "policy_change", "mode": "closed" },
+    { "impulse_class": "human_action", "mode": "open" }
+  ],
+  "region_ref": "region:au/sydney-ashore",
+  "exogenous_source": "gaia"
+}

schemas/EvalItem.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/EvalItem.json",
+  "title": "EvalItem",
+  "description": "One item in the provider-neutral model-tournament corpora that feed the Intelligence-Superiority Bench (iSOTA). An EvalItem is the atomic contract of the Provider Eval Seed Strategy: it declares which corpus it belongs to (A provider-seed / B Sherlock-task / C adversarial), its task family, the question, the traits an answer must have, how it is graded, and its risk class. The load-bearing rule is gradability — an item with no expected_answer_traits cannot be scored and is rejected. Provider-sourced items must name the provider; the harness stays neutral, so provider is a label, never a winner.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "id", "source", "corpus", "task_family", "user_question", "expected_answer_traits", "grading_method", "risk_class"],
+  "properties": {
+    "type": { "const": "EvalItem" },
+    "id": { "type": "string", "minLength": 1 },
+    "source": { "type": "string", "enum": ["provider", "internal"] },
+    "provider": { "type": "string" },
+    "corpus": {
+      "type": "string",
+      "enum": ["A", "B", "C"],
+      "description": "A = provider seed (screening); B = Sherlock task (our workload, weighted heavy); C = adversarial / edge."
+    },
+    "task_family": {
+      "type": "string",
+      "enum": ["support_triage", "duplicate_detection", "evidence_answer", "incident_timeline", "routing_escalation", "repo_diagnosis", "release_impact", "prompt_eng", "rag_grounding", "tool_use", "structured_output", "safety_policy", "adversarial"]
+    },
+    "user_question": { "type": "string", "minLength": 1 },
+    "context_doc_ids": { "type": "array", "items": { "type": "string" } },
+    "expected_answer_traits": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 },
+    "gold_answer": { "type": "string" },
+    "gold_citations": { "type": "array", "items": { "type": "string" } },
+    "grading_method": {
+      "type": "string",
+      "enum": ["exact", "citation_faithfulness", "groundedness", "instruction_following", "tool_accuracy", "case_action", "human", "llm_judge"]
+    },
+    "risk_class": { "type": "string", "enum": ["low", "medium", "high", "critical"] }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "source": { "const": "provider" } } },
+      "then": { "required": ["provider"] }
+    }
+  ]
+}

schemas/GaiaObservation.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/GaiaObservation.json",
+  "title": "GaiaObservation",
+  "description": "An exogenous environmental world-state reading from GAIA — the estate's weather/environmental world model (TWC / IBM alt-data). A GaiaObservation is the grounding for the exogenous state that drives a twin's WorldModel: an ExogenousShock Impulse must cite one, and a Region is grounded in the GAIA cells its observations cover. Provenance is load-bearing — an ungrounded observation is inadmissible (asserted by rejection).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "observation_id", "gaia_cell", "field", "value", "valid_time", "source", "provenance_refs"],
+  "properties": {
+    "type": { "const": "GaiaObservation" },
+    "observation_id": { "type": "string", "minLength": 1 },
+    "gaia_cell": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["system", "cell"],
+      "properties": {
+        "system": { "type": "string", "enum": ["h3", "latlon_grid", "s2"] },
+        "cell": { "type": "string", "minLength": 1 }
+      }
+    },
+    "field": {
+      "type": "string",
+      "enum": ["temperature", "precipitation", "wind_speed", "humidity", "pressure", "air_quality", "hazard_index", "flood_risk", "wildfire_risk", "solar_irradiance"]
+    },
+    "value": { "type": "number" },
+    "unit": { "type": "string" },
+    "valid_time": { "type": "string", "format": "date-time" },
+    "source": { "type": "string", "enum": ["twc", "ibm_environmental", "noaa", "ecmwf", "synthetic"] },
+    "provenance_refs": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+  }
+}

schemas/Impulse.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/Impulse.json",
+  "title": "Impulse",
+  "description": "A typed input to a twin's state-space world model: u in x+ = A*x + B*(G*u). An Impulse records the class, source, magnitude, which state dimensions it targets, and — after the gate has run — whether it was admitted and the gate state that decided it. Two invariants are load-bearing and asserted by rejection: an exogenous_shock MUST cite the GaiaObservation it came from (GAIA is the exogenous world model), and an impulse admitted through a closed gate is a contradiction (fail-closed).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "impulse_id", "twin_id", "impulse_class", "source", "magnitude", "target_dims", "gate_state", "admitted", "provenance_refs"],
+  "properties": {
+    "type": { "const": "Impulse" },
+    "impulse_id": { "type": "string", "minLength": 1 },
+    "twin_id": { "type": "string", "minLength": 1 },
+    "impulse_class": {
+      "type": "string",
+      "enum": ["device_reading", "market_data_event", "exogenous_shock", "policy_change", "human_action"]
+    },
+    "source": { "type": "string", "minLength": 1 },
+    "magnitude": { "type": "number", "minimum": 0, "maximum": 1 },
+    "target_dims": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "gate_state": { "type": "string", "enum": ["open", "attenuated", "closed"] },
+    "admitted": { "type": "boolean" },
+    "source_ref": {
+      "type": "string",
+      "description": "For exogenous_shock: the GaiaObservation.observation_id this impulse was derived from."
+    },
+    "provenance_refs": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "impulse_class": { "const": "exogenous_shock" } } },
+      "then": { "required": ["source_ref"] }
+    },
+    {
+      "if": { "properties": { "gate_state": { "const": "closed" } } },
+      "then": { "properties": { "admitted": { "const": false } } }
+    }
+  ]
+}

schemas/ImpulseGate.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/ImpulseGate.json",
+  "title": "ImpulseGate",
+  "description": "A governed admission gate for one impulse class into a twin's state-space dynamics. The gate is where governance meets dynamics: it decides whether an input of its class may perturb the state vector, and by how much (gate_factor). Fail-closed is the default and the load-bearing rule — a closed gate must have gate_factor 0, so an ungated impulse cannot move the state (asserted by rejection).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "gate_id", "impulse_class", "mode", "gate_factor"],
+  "properties": {
+    "type": { "const": "ImpulseGate" },
+    "gate_id": { "type": "string", "minLength": 1 },
+    "impulse_class": {
+      "type": "string",
+      "enum": ["device_reading", "market_data_event", "exogenous_shock", "policy_change", "human_action"]
+    },
+    "mode": { "type": "string", "enum": ["open", "attenuated", "closed"] },
+    "gate_factor": { "type": "number", "minimum": 0, "maximum": 1 },
+    "fail_closed": { "type": "boolean", "default": true },
+    "admission_rule": { "type": "string" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "mode": { "const": "closed" } } },
+      "then": { "properties": { "gate_factor": { "const": 0 } } }
+    },
+    {
+      "if": { "properties": { "mode": { "const": "open" } } },
+      "then": { "properties": { "gate_factor": { "const": 1 } } }
+    }
+  ]
+}

schemas/Region.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/Region.json",
+  "title": "Region",
+  "description": "A geospatial region a twin is grounded in. A Region is the join between the twin's WorldModel and GAIA: it carries a centroid for the Common Operating Picture and is grounded in one or more GAIA cells, which is where its exogenous (weather/environmental) state is read from. An ungrounded region — no GAIA cells — cannot supply exogenous state and is rejected.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "region_id", "name", "centroid", "gaia_cells"],
+  "properties": {
+    "type": { "const": "Region" },
+    "region_id": { "type": "string", "minLength": 1 },
+    "name": { "type": "string", "minLength": 1 },
+    "centroid": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["lat", "lon"],
+      "properties": {
+        "lat": { "type": "number", "minimum": -90, "maximum": 90 },
+        "lon": { "type": "number", "minimum": -180, "maximum": 180 }
+      }
+    },
+    "bbox": {
+      "type": "array",
+      "description": "[min_lon, min_lat, max_lon, max_lat]",
+      "items": { "type": "number" },
+      "minItems": 4,
+      "maxItems": 4
+    },
+    "gaia_cells": {
+      "type": "array",
+      "description": "GAIA grounding — the environmental world-model cells this region is read through. Must be non-empty.",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1
+    }
+  }
+}

schemas/StateVector.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/StateVector.json",
+  "title": "StateVector",
+  "description": "A reading of a twin's latent world-state x at a point in the replay sequence. Each named dimension is normalized to [0,1]; an out-of-range component is not a valid state and is rejected. A StateVector with no dimensions is not observable and is rejected. Provenance ties the reading back to the Impulse(s) that produced it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "twin_id", "seq", "at", "dims", "provenance_refs"],
+  "properties": {
+    "type": { "const": "StateVector" },
+    "twin_id": { "type": "string", "minLength": 1 },
+    "seq": { "type": "integer", "minimum": 0 },
+    "at": { "type": "string", "format": "date-time" },
+    "dims": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }
+    },
+    "provenance_refs": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+  }
+}