@nebulacomponents/citable 1.12.0 → 1.13.0

package/schemas/release-manifest.schema.json

@@ -0,0 +1,74 @@
+{
+  "$id": "citable://schemas/release-manifest.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Canonical release manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "release_id", "version", "commit", "generated_at", "toolchain", "facts", "projections", "controlled_surfaces", "manifest_hash"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "release_id": { "type": "string", "pattern": "^RELEASE-v[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "commit": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "toolchain": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["node", "citable"],
+      "properties": {
+        "node": { "type": "string", "minLength": 1 },
+        "citable": { "type": "string", "minLength": 1 }
+      }
+    },
+    "facts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["detectors", "namespaces", "registries", "providers", "distribution_files_per_provider"],
+      "properties": {
+        "detectors": { "type": "integer", "minimum": 0 },
+        "namespaces": { "type": "integer", "minimum": 0 },
+        "registries": { "type": "integer", "minimum": 0 },
+        "providers": { "type": "integer", "minimum": 0 },
+        "distribution_files_per_provider": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "projections": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["projection_id", "path", "sha256", "bytes", "authority"],
+        "properties": {
+          "projection_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+          "path": { "type": "string", "minLength": 1 },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "bytes": { "type": "integer", "minimum": 0 },
+          "authority": { "enum": ["control_plane"] }
+        }
+      }
+    },
+    "controlled_surfaces": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["surface_id", "url", "projection_id", "verification_method", "verification_header", "required_for_finalization"],
+        "properties": {
+          "surface_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+          "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-]+$" },
+          "required_for_finalization": { "type": "boolean" }
+        },
+        "allOf": [
+          { "if": { "properties": { "verification_method": { "const": "exact_response_body" } } }, "then": { "properties": { "verification_header": { "type": "null" } } } },
+          { "if": { "properties": { "verification_method": { "const": "response_header" } } }, "then": { "properties": { "verification_header": { "type": "string", "minLength": 1 } } } }
+        ]
+      }
+    },
+    "manifest_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/release-state.schema.json

@@ -0,0 +1,40 @@
+{
+  "$id": "citable://schemas/release-state.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Governed release state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "release_id", "manifest_hash", "state", "max_dwell_hours", "created_at", "transitions", "receipt_refs", "state_hash"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "release_id": { "type": "string", "pattern": "^RELEASE-v" },
+    "manifest_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "state": { "enum": ["candidate", "published_unfinalized", "finalized", "superseded", "withdrawn"] },
+    "max_dwell_hours": { "type": "integer", "minimum": 1, "maximum": 168 },
+    "created_at": { "type": "string", "format": "date-time" },
+    "published_at": { "type": ["string", "null"], "format": "date-time" },
+    "finalized_at": { "type": ["string", "null"], "format": "date-time" },
+    "resolved_at": { "type": ["string", "null"], "format": "date-time" },
+    "resolution_reason": { "type": ["string", "null"] },
+    "superseding_release_id": { "type": ["string", "null"] },
+    "receipt_refs": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^RECEIPT-" } },
+    "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "transitions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["from", "to", "actor", "timestamp", "reason", "policy_version", "evidence_refs"],
+        "properties": {
+          "from": { "type": ["string", "null"], "enum": [null, "candidate", "published_unfinalized"] },
+          "to": { "enum": ["candidate", "published_unfinalized", "finalized", "superseded", "withdrawn"] },
+          "actor": { "type": "string", "minLength": 1 },
+          "timestamp": { "type": "string", "format": "date-time" },
+          "reason": { "type": "string", "minLength": 1 },
+          "policy_version": { "type": "string", "minLength": 1 },
+          "evidence_refs": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+        }
+      }
+    }
+  }
+}

package/schemas/risk.schema.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/risk.schema.json",
+  "title": "Risk Register",
+  "type": "object",
+  "required": [
+    "version",
+    "kind",
+    "entries"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer"
+    },
+    "kind": {
+      "type": "string",
+      "const": "risks"
+    },
+    "updated": {
+      "type": "string"
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "risk_id",
+          "title",
+          "category",
+          "cause",
+          "event",
+          "consequence",
+          "likelihood",
+          "impact",
+          "gross_exposure",
+          "controls",
+          "residual_exposure",
+          "response",
+          "response_owner",
+          "review_date",
+          "trend",
+          "board_visibility"
+        ],
+        "properties": {
+          "risk_id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "category": {
+            "type": "string",
+            "enum": [
+              "commercial",
+              "product",
+              "detector_quality",
+              "evidence_integrity",
+              "customer_reliance",
+              "platform_dependency",
+              "search_engine_policy",
+              "legal_advertising",
+              "data_rights",
+              "security",
+              "supply_chain",
+              "npm_distribution",
+              "reputational",
+              "operational_capacity"
+            ]
+          },
+          "cause": {
+            "type": "string"
+          },
+          "event": {
+            "type": "string"
+          },
+          "consequence": {
+            "type": "string"
+          },
+          "likelihood": {
+            "type": "string",
+            "enum": [
+              "rare",
+              "unlikely",
+              "possible",
+              "likely",
+              "almost_certain"
+            ]
+          },
+          "impact": {
+            "type": "string",
+            "enum": [
+              "negligible",
+              "minor",
+              "moderate",
+              "major",
+              "catastrophic"
+            ]
+          },
+          "gross_exposure": {
+            "type": "string",
+            "enum": [
+              "low",
+              "medium",
+              "high",
+              "critical"
+            ]
+          },
+          "controls": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "control_owner": {
+            "type": "string"
+          },
+          "control_effectiveness": {
+            "type": "string",
+            "enum": [
+              "none",
+              "weak",
+              "partial",
+              "adequate",
+              "strong"
+            ]
+          },
+          "residual_exposure": {
+            "type": "string",
+            "enum": [
+              "low",
+              "medium",
+              "high",
+              "critical"
+            ]
+          },
+          "key_risk_indicators": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "trigger_threshold": {
+            "type": "string"
+          },
+          "response": {
+            "type": "string"
+          },
+          "response_owner": {
+            "type": "string"
+          },
+          "review_date": {
+            "type": "string"
+          },
+          "trend": {
+            "type": "string",
+            "enum": [
+              "improving",
+              "stable",
+              "deteriorating",
+              "emerging"
+            ]
+          },
+          "board_visibility": {
+            "type": "boolean"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/scenario.schema.json

@@ -0,0 +1,165 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/scenario.schema.json",
+  "title": "Scenario Registry",
+  "type": "object",
+  "required": [
+    "version",
+    "kind",
+    "entries"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer"
+    },
+    "kind": {
+      "type": "string",
+      "const": "scenarios"
+    },
+    "updated": {
+      "type": "string"
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "scenario_id",
+          "title",
+          "variables",
+          "domain_impact",
+          "cascade_analysis",
+          "states",
+          "early_warning_triggers",
+          "hedges",
+          "owner"
+        ],
+        "properties": {
+          "scenario_id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "variables": {
+            "type": "array",
+            "maxItems": 3,
+            "items": {
+              "type": "object",
+              "required": [
+                "variable",
+                "driver"
+              ],
+              "properties": {
+                "variable": {
+                  "type": "string"
+                },
+                "driver": {
+                  "type": "string"
+                },
+                "variable_id": {
+                  "type": "string",
+                  "pattern": "^(KPI-|RISK-)",
+                  "description": "Optional KPI- or RISK-prefixed registry reference"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "domain_impact": {
+            "type": "object",
+            "properties": {
+              "commercial": {
+                "type": "string"
+              },
+              "product": {
+                "type": "string"
+              },
+              "customer": {
+                "type": "string"
+              },
+              "operational": {
+                "type": "string"
+              },
+              "reputational": {
+                "type": "string"
+              }
+            }
+          },
+          "cascade_analysis": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "states": {
+            "type": "object",
+            "required": [
+              "base",
+              "stress",
+              "severe"
+            ],
+            "properties": {
+              "base": {
+                "type": "string"
+              },
+              "stress": {
+                "type": "string"
+              },
+              "severe": {
+                "type": "string"
+              }
+            }
+          },
+          "early_warning_triggers": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "hedges": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "action",
+                "cost",
+                "impact",
+                "owner",
+                "deadline"
+              ],
+              "properties": {
+                "action": {
+                  "type": "string"
+                },
+                "cost": {
+                  "type": "string"
+                },
+                "impact": {
+                  "type": "string"
+                },
+                "owner": {
+                  "type": "string"
+                },
+                "deadline": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "owner": {
+            "type": "string"
+          },
+          "period": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/variance.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/variance.schema.json",
+  "title": "Variance Registry",
+  "type": "object",
+  "required": [
+    "version",
+    "kind",
+    "entries"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer"
+    },
+    "kind": {
+      "type": "string",
+      "const": "variances"
+    },
+    "updated": {
+      "type": "string"
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "variance_id",
+          "metric_id",
+          "period",
+          "actual",
+          "target",
+          "variance_amount",
+          "variance_pct",
+          "materiality",
+          "primary_driver",
+          "controllable",
+          "evidence",
+          "owner"
+        ],
+        "properties": {
+          "variance_id": {
+            "type": "string"
+          },
+          "metric_id": {
+            "type": "string"
+          },
+          "period": {
+            "type": "string"
+          },
+          "actual": {},
+          "target": {},
+          "prior_period": {},
+          "forecast": {},
+          "variance_amount": {},
+          "variance_pct": {
+            "type": "number"
+          },
+          "materiality": {
+            "type": "string",
+            "enum": [
+              "immaterial",
+              "watch",
+              "material",
+              "critical"
+            ]
+          },
+          "primary_driver": {
+            "type": "string"
+          },
+          "secondary_drivers": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "controllable": {
+            "type": "boolean"
+          },
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "management_response": {
+            "type": "string"
+          },
+          "revised_forecast": {},
+          "confidence": {
+            "type": "string",
+            "enum": [
+              "low",
+              "medium",
+              "high"
+            ]
+          },
+          "owner": {
+            "type": "string"
+          },
+          "rejected_causes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}