@nebulacomponents/citable 1.12.0 → 1.13.1

package/schemas/customer-outcome.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/customer-outcome.schema.json",
+  "title": "Customer Outcomes Registry",
+  "type": "object",
+  "required": [
+    "version",
+    "kind",
+    "entries"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer"
+    },
+    "kind": {
+      "type": "string",
+      "const": "customer-outcomes"
+    },
+    "updated": {
+      "type": "string"
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "outcome_id",
+          "customer",
+          "property",
+          "baseline",
+          "intervention",
+          "observed_change",
+          "measurement_window",
+          "evidence_package",
+          "customer_confirmed",
+          "causal_confidence"
+        ],
+        "properties": {
+          "outcome_id": {
+            "type": "string"
+          },
+          "customer": {
+            "type": "string"
+          },
+          "property": {
+            "type": "string"
+          },
+          "baseline": {
+            "type": "string"
+          },
+          "intervention": {
+            "type": "string"
+          },
+          "observed_change": {
+            "type": "string"
+          },
+          "measurement_window": {
+            "type": "string"
+          },
+          "confounders": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "evidence_package": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "customer_confirmed": {
+            "type": "boolean"
+          },
+          "independently_verified": {
+            "type": "boolean"
+          },
+          "causal_confidence": {
+            "type": "string",
+            "enum": [
+              "none",
+              "weak",
+              "partial",
+              "strong",
+              "verified"
+            ]
+          },
+          "outcome_stage": {
+            "type": "string",
+            "enum": [
+              "finding_produced",
+              "finding_accepted",
+              "finding_remediated",
+              "remediation_validated",
+              "search_result_changed",
+              "answer_engine_changed",
+              "commercial_outcome_changed",
+              "causal_relationship_established"
+            ]
+          },
+          "commercial_value": {
+            "type": "string"
+          },
+          "publication_permission": {
+            "type": "boolean"
+          },
+          "period": {
+            "type": "string"
+          },
+          "owner": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/decision.schema.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/decision.schema.json",
+  "title": "Decision Registry",
+  "type": "object",
+  "required": [
+    "version",
+    "kind",
+    "entries"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer"
+    },
+    "kind": {
+      "type": "string",
+      "const": "decisions"
+    },
+    "updated": {
+      "type": "string"
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "decision_id",
+          "owner",
+          "deadline",
+          "reversibility",
+          "options",
+          "recommendation",
+          "supporting_evidence",
+          "assumptions"
+        ],
+        "properties": {
+          "decision_id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "owner": {
+            "type": "string"
+          },
+          "consulted": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "deadline": {
+            "type": "string"
+          },
+          "reversibility": {
+            "type": "string",
+            "enum": [
+              "reversible",
+              "costly_to_reverse",
+              "effectively_one_way"
+            ]
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "label",
+                "description",
+                "trade_offs"
+              ],
+              "properties": {
+                "label": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": "string"
+                },
+                "trade_offs": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "recommendation": {
+            "type": "string"
+          },
+          "supporting_evidence": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "contradicting_evidence": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "assumptions": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "what_would_change_recommendation": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "cost_of_delay": {
+            "type": "string"
+          },
+          "legal_review": {
+            "type": "string"
+          },
+          "security_review": {
+            "type": "string"
+          },
+          "financial_model": {
+            "type": "string"
+          },
+          "reopen_conditions": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "open",
+              "decided",
+              "deferred",
+              "superseded"
+            ]
+          },
+          "decided_at": {
+            "type": "string"
+          },
+          "outcome": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/deployment-receipt.schema.json

@@ -0,0 +1,51 @@
+{
+  "$id": "citable://schemas/deployment-receipt.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Publisher-controlled deployment receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "receipt_id", "release_id", "manifest_hash", "surface_id", "url", "projection_id", "verification_method", "verification_header", "expected_projection_hash", "observed_projection_hash", "response_hash", "http", "collector", "collected_at", "expires_at", "authority", "verification_status", "limitations", "receipt_hash"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "receipt_id": { "type": "string", "pattern": "^RECEIPT-[A-F0-9]+$" },
+    "release_id": { "type": "string", "pattern": "^RELEASE-v" },
+    "manifest_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "surface_id": { "type": "string", "minLength": 1 },
+    "url": { "type": "string", "format": "uri", "pattern": "^https://" },
+    "projection_id": { "type": "string", "minLength": 1 },
+    "verification_method": { "enum": ["exact_response_body", "response_header"] },
+    "verification_header": { "type": ["string", "null"], "pattern": "^[a-z0-9-]+$" },
+    "expected_projection_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "observed_projection_hash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+    "response_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "http": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "final_url", "redirect_chain", "headers"],
+      "properties": {
+        "status": { "type": "integer", "minimum": 100, "maximum": 599 },
+        "final_url": { "type": "string", "format": "uri" },
+        "redirect_chain": { "type": "array", "items": { "type": "string", "format": "uri" } },
+        "headers": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    },
+    "collector": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["identity", "version", "method", "request_identity", "region"],
+      "properties": {
+        "identity": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "method": { "type": "string", "minLength": 1 },
+        "request_identity": { "type": "string", "minLength": 1 },
+        "region": { "type": "string", "minLength": 1 }
+      }
+    },
+    "collected_at": { "type": "string", "format": "date-time" },
+    "expires_at": { "type": "string", "format": "date-time" },
+    "authority": { "$ref": "citable://schemas/evidence-authority.schema.json" },
+    "verification_status": { "enum": ["verified", "contradictory", "insufficient_evidence", "failed"] },
+    "limitations": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "receipt_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/field-validation-metrics.schema.json

@@ -0,0 +1,15 @@
+{
+  "$id": "citable://schemas/field-validation-metrics.schema.json", "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Publishable field-validation metrics", "type": "object", "additionalProperties": false,
+  "required": ["schema_version", "corpus_id", "version", "provenance", "evaluation_design", "population", "detector_versions", "detector_accuracy", "reviewer_metrics", "execution_metrics", "remediation_metrics", "metric_definitions", "unknown_false_negatives", "false_negative_discovery_limitations", "causal_limitations", "limitations", "metrics_hash"],
+  "properties": {
+    "schema_version": { "const": 1 }, "corpus_id": { "type": "string" }, "version": { "type": "string" },
+    "provenance": { "type": "object", "additionalProperties": false, "required": ["corpus_hash", "corpus_created_at", "collection_started_at", "collection_ended_at"], "properties": { "corpus_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "corpus_created_at": { "type": "string", "format": "date-time" }, "collection_started_at": { "type": "string", "format": "date-time" }, "collection_ended_at": { "type": "string", "format": "date-time" } } },
+    "evaluation_design": { "type": "object" }, "population": { "type": "object" },
+    "detector_versions": { "type": "object", "additionalProperties": false, "required": ["versions", "mixed_versions", "cases_by_version"], "properties": { "versions": { "type": "array", "items": { "type": "string" } }, "mixed_versions": { "type": "boolean" }, "cases_by_version": { "type": "object" } } },
+    "detector_accuracy": { "type": "object" }, "reviewer_metrics": { "type": "object" }, "execution_metrics": { "type": "object" }, "remediation_metrics": { "type": "object" },
+    "metric_definitions": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "object", "additionalProperties": false, "required": ["value", "numerator", "denominator", "population", "exclusions", "confidence_limitations"], "properties": { "value": { "type": ["number", "null"] }, "numerator": { "type": ["number", "null"] }, "denominator": { "type": ["number", "null"] }, "population": { "type": "string", "minLength": 1 }, "exclusions": { "type": "array", "items": { "type": "string" } }, "confidence_limitations": { "type": "array", "minItems": 1, "items": { "type": "string" } } } } },
+    "unknown_false_negatives": { "type": "object", "additionalProperties": false, "required": ["status", "reason"], "properties": { "status": { "const": "not_quantified" }, "reason": { "type": "string", "minLength": 1 } } },
+    "false_negative_discovery_limitations": { "type": "array" }, "causal_limitations": { "type": "array" }, "limitations": { "type": "array" }, "metrics_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/initiative.schema.json

@@ -0,0 +1,185 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/initiative.schema.json",
+  "title": "Initiative Registry",
+  "type": "object",
+  "required": [
+    "version",
+    "kind",
+    "entries"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer"
+    },
+    "kind": {
+      "type": "string",
+      "const": "initiatives"
+    },
+    "updated": {
+      "type": "string"
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "initiative_id",
+          "title",
+          "customer_demand",
+          "revenue_potential",
+          "strategic_differentiation",
+          "evidence_strength",
+          "engineering_cost",
+          "reversibility",
+          "owner"
+        ],
+        "properties": {
+          "initiative_id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "customer_demand": {
+            "type": "string",
+            "enum": [
+              "none",
+              "low",
+              "medium",
+              "high",
+              "validated"
+            ]
+          },
+          "revenue_potential": {
+            "type": "string",
+            "enum": [
+              "none",
+              "low",
+              "medium",
+              "high",
+              "transformative"
+            ]
+          },
+          "strategic_differentiation": {
+            "type": "string",
+            "enum": [
+              "none",
+              "low",
+              "medium",
+              "high",
+              "critical"
+            ]
+          },
+          "evidence_strength": {
+            "type": "string",
+            "enum": [
+              "assumption",
+              "anecdote",
+              "proxy",
+              "validated",
+              "verified"
+            ]
+          },
+          "engineering_cost": {
+            "type": "string",
+            "enum": [
+              "trivial",
+              "low",
+              "medium",
+              "high",
+              "very_high"
+            ]
+          },
+          "operating_cost": {
+            "type": "string",
+            "enum": [
+              "none",
+              "low",
+              "medium",
+              "high"
+            ]
+          },
+          "maintenance_cost": {
+            "type": "string",
+            "enum": [
+              "none",
+              "low",
+              "medium",
+              "high"
+            ]
+          },
+          "platform_dependency": {
+            "type": "string"
+          },
+          "legal_risk": {
+            "type": "string",
+            "enum": [
+              "none",
+              "low",
+              "medium",
+              "high"
+            ]
+          },
+          "reversibility": {
+            "type": "string",
+            "enum": [
+              "reversible",
+              "costly_to_reverse",
+              "effectively_one_way"
+            ]
+          },
+          "time_to_value": {
+            "type": "string"
+          },
+          "opportunity_cost": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "proposed",
+              "approved",
+              "in_progress",
+              "completed",
+              "deferred",
+              "cancelled"
+            ]
+          },
+          "owner": {
+            "type": "string"
+          },
+          "linked_kpis": {
+            "type": "array",
+            "items": { "type": "string" },
+            "uniqueItems": true
+          },
+          "linked_outcomes": {
+            "type": "array",
+            "items": { "type": "string" },
+            "uniqueItems": true
+          },
+          "linked_risks": {
+            "type": "array",
+            "items": { "type": "string" },
+            "uniqueItems": true
+          },
+          "linked_decisions": {
+            "type": "array",
+            "items": { "type": "string" },
+            "uniqueItems": true
+          },
+          "scoring_weights": {
+            "type": "object",
+            "description": "Explicit weights if weighted scoring is used — weights must be visible"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/kpi.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/kpi.schema.json",
+  "title": "KPI Registry",
+  "type": "object",
+  "required": [
+    "version",
+    "kind",
+    "entries"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer"
+    },
+    "kind": {
+      "type": "string",
+      "const": "kpis"
+    },
+    "updated": {
+      "type": "string"
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "metric_id",
+          "name",
+          "executive_definition",
+          "calculation",
+          "unit",
+          "source_system",
+          "owner",
+          "reporting_cadence"
+        ],
+        "properties": {
+          "metric_id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "executive_definition": {
+            "type": "string"
+          },
+          "calculation": {
+            "type": "string"
+          },
+          "numerator": {
+            "type": "string"
+          },
+          "denominator": {
+            "type": "string"
+          },
+          "unit": {
+            "type": "string"
+          },
+          "source_system": {
+            "type": "string"
+          },
+          "source_query": {
+            "type": "string"
+          },
+          "owner": {
+            "type": "string"
+          },
+          "target": {},
+          "warning_threshold": {},
+          "critical_threshold": {},
+          "reporting_cadence": {
+            "type": "string",
+            "enum": [
+              "daily",
+              "weekly",
+              "monthly",
+              "quarterly",
+              "annual"
+            ]
+          },
+          "restatement_policy": {
+            "type": "string"
+          },
+          "known_limitations": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "comparison_required": {
+            "type": "boolean"
+          },
+          "comparison_basis": {
+            "type": "string",
+            "enum": [
+              "prior_period",
+              "prior_year",
+              "target",
+              "budget",
+              "forecast"
+            ]
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/observation.schema.json

@@ -7,7 +7,7 @@
   "required": ["observation_id", "kind", "state", "collected_at", "collection_method", "confidence", "source", "evidence_hash", "data"],
   "properties": {
     "observation_id": { "type": "string", "minLength": 1 },
-    "kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image"] },
+    "kind": { "type": "string", "enum": ["render", "browser_journey", "index", "citation", "citation_review", "crawler_log", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image", "representation_drift"] },
     "state": { "type": "string", "enum": ["observed", "not_observed", "not_evidenced", "incomplete", "review_required", "failed"] },
     "collected_at": { "type": "string", "format": "date-time" },
     "collection_method": { "type": "string", "enum": ["live_api", "browser", "owner_import", "synthetic_fetch", "static_analysis", "human_review"] },