@nebulacomponents/citable 1.15.1 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.15.1",
+  "version": "1.17.0",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",

package/schemas/cli-output-envelope.schema.json

@@ -0,0 +1,30 @@
+{
+  "$id": "citable://schemas/cli-output-envelope.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CLI JSON output envelope",
+  "description": "Stable envelope for every `citable <command> --json` output. Consumers read `citable_output_schema` for envelope compatibility and read command data from `result`. The envelope version changes only on breaking envelope changes; command payloads evolve backward-compatibly inside result.",
+  "type": "object",
+  "required": ["citable_output_schema", "tool_version", "generated_at", "result"],
+  "properties": {
+    "citable_output_schema": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Envelope contract version. 1.0 is the initial stable contract."
+    },
+    "tool_version": {
+      "type": "string",
+      "description": "Citable package version that produced the output."
+    },
+    "command": {
+      "type": ["string", "null"],
+      "description": "Top-level command that produced this output."
+    },
+    "generated_at": {
+      "type": "string",
+      "description": "ISO-8601 timestamp of when the output was generated."
+    },
+    "result": {
+      "description": "Command-specific payload. Structure is defined per command and evolves backward-compatibly within an envelope major version."
+    }
+  }
+}

package/schemas/experiment.schema.json

@@ -15,7 +15,7 @@
       "properties": {
         "experiment_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },
         "hypothesis": { "type": "string", "minLength": 10 },
-        "discipline": { "type": "array", "items": { "type": "string", "enum": ["seo", "aeo", "geo"] } },
+        "discipline": { "type": "array", "items": { "type": "string", "enum": ["seo", "aeo", "geo", "cro"] } },
         "primary_metric": { "type": "string" },
         "secondary_metrics": { "type": "array", "items": { "type": "string" } },
         "prompt_cohort": { "type": "array", "items": { "type": "string" } },

package/schemas/finding.schema.json

@@ -257,6 +257,75 @@
         }
       }
     },
+    "provenance": {
+      "type": "object",
+      "required": [
+        "detector_version",
+        "tool_version",
+        "evidence_source",
+        "methodology",
+        "revalidation_required"
+      ],
+      "properties": {
+        "detector_version": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "tool_version": {
+          "type": "string"
+        },
+        "source_url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "source_file": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "evidence_selector": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "evidence_source": {
+          "type": "string",
+          "enum": [
+            "dom_parse",
+            "registry",
+            "registry+dom_parse",
+            "controlled_observation",
+            "configuration"
+          ]
+        },
+        "viewport": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "viewport_note": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "methodology": {
+          "type": "string"
+        },
+        "revalidation_required": {
+          "type": "string",
+          "enum": [
+            "on_next_audit",
+            "human_review_before_action"
+          ]
+        }
+      }
+    },
     "status": {
       "type": "object",
       "required": [

package/schemas/fleet.schema.json

@@ -0,0 +1,93 @@
+{
+  "$id": "citable://schemas/fleet.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Fleet Properties registry",
+  "allOf": [
+    {
+      "$ref": "citable://schemas/common.defs.json#/definitions/registryFile"
+    }
+  ],
+  "properties": {
+    "kind": {
+      "const": "fleet"
+    },
+    "entries": {
+      "items": {
+        "$ref": "#/definitions/fleetProperty"
+      }
+    }
+  },
+  "definitions": {
+    "fleetProperty": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "property_id",
+        "name",
+        "primary_domain",
+        "environment",
+        "status"
+      ],
+      "properties": {
+        "property_id": {
+          "$ref": "citable://schemas/common.defs.json#/definitions/id"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string"
+        },
+        "primary_domain": {
+          "type": "string",
+          "minLength": 3
+        },
+        "domains": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "environment": {
+          "type": "string",
+          "enum": [
+            "production",
+            "staging",
+            "development",
+            "preview"
+          ]
+        },
+        "base_url": {
+          "type": "string"
+        },
+        "built_output_dir": {
+          "type": "string"
+        },
+        "owner": {
+          "type": "string"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "audit_schedule": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "active",
+            "paused",
+            "archived"
+          ]
+        },
+        "updated": {
+          "$ref": "citable://schemas/common.defs.json#/definitions/isoDate"
+        }
+      }
+    }
+  }
+}

package/schemas/funnel.schema.json

@@ -0,0 +1,116 @@
+{
+  "$id": "citable://schemas/funnel.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Conversion Funnel registry",
+  "allOf": [
+    {
+      "$ref": "citable://schemas/common.defs.json#/definitions/registryFile"
+    }
+  ],
+  "properties": {
+    "kind": {
+      "const": "funnels"
+    },
+    "entries": {
+      "items": {
+        "$ref": "#/definitions/funnel"
+      }
+    }
+  },
+  "definitions": {
+    "funnelStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "step_id",
+        "url_pattern",
+        "role"
+      ],
+      "properties": {
+        "step_id": {
+          "$ref": "citable://schemas/common.defs.json#/definitions/id"
+        },
+        "name": {
+          "type": "string"
+        },
+        "url_pattern": {
+          "type": "string",
+          "minLength": 1
+        },
+        "page_id": {
+          "type": "string"
+        },
+        "role": {
+          "type": "string",
+          "enum": [
+            "entry",
+            "consideration",
+            "commitment",
+            "completion"
+          ]
+        },
+        "expected_cta": {
+          "type": "string"
+        },
+        "preserve_params": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "funnel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "funnel_id",
+        "name",
+        "primary_goal",
+        "steps",
+        "status"
+      ],
+      "properties": {
+        "funnel_id": {
+          "$ref": "citable://schemas/common.defs.json#/definitions/id"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 3
+        },
+        "description": {
+          "type": "string"
+        },
+        "primary_goal": {
+          "type": "string",
+          "minLength": 2
+        },
+        "target_audience": {
+          "type": "string"
+        },
+        "owner": {
+          "type": "string"
+        },
+        "steps": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "$ref": "#/definitions/funnelStep"
+          }
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "draft",
+            "active",
+            "deprecated",
+            "archived"
+          ]
+        },
+        "provenance": {
+          "$ref": "citable://schemas/common.defs.json#/definitions/provenance"
+        }
+      }
+    }
+  }
+}

package/schemas/mcp-transport-envelope.schema.json

@@ -0,0 +1,244 @@
+{
+  "$id": "citable://schemas/mcp-transport-envelope.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Model Context Protocol evidence transport envelope",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "transport",
+    "server",
+    "tool",
+    "request",
+    "response",
+    "provenance",
+    "authority",
+    "status",
+    "collected_at"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "transport": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "protocol_version",
+        "timeout_ms",
+        "max_bytes"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "stdio",
+            "http"
+          ]
+        },
+        "protocol_version": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$|^[0-9]+\\.[0-9]+.*$"
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 60000
+        },
+        "max_bytes": {
+          "type": "integer",
+          "minimum": 1024,
+          "maximum": 10485760
+        },
+        "retries": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 5
+        }
+      }
+    },
+    "server": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "server_id",
+        "transport_target",
+        "allowlisted"
+      ],
+      "properties": {
+        "server_id": {
+          "type": "string",
+          "pattern": "^[a-z0-9_.-]+$"
+        },
+        "package_name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "pinned_version": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "transport_target": {
+          "type": "string",
+          "minLength": 1
+        },
+        "allowlisted": {
+          "type": "boolean"
+        },
+        "capabilities": {
+          "type": "object"
+        }
+      }
+    },
+    "tool": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "read_only",
+        "input_schema_hash"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_.-]+$"
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "read_only": {
+          "type": "boolean"
+        },
+        "input_schema_hash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "input_schema": {
+          "type": "object"
+        }
+      }
+    },
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "arguments_hash",
+        "arguments"
+      ],
+      "properties": {
+        "arguments_hash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "arguments": {
+          "type": "object"
+        },
+        "authorization_mode": {
+          "type": "string",
+          "enum": [
+            "none",
+            "environment",
+            "bearer_token",
+            "header"
+          ]
+        },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "raw_sha256",
+        "content_bytes",
+        "is_error",
+        "retention_reason"
+      ],
+      "properties": {
+        "raw_sha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "content_bytes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "is_error": {
+          "type": "boolean"
+        },
+        "retention_reason": {
+          "type": "string",
+          "enum": [
+            "raw_preserved",
+            "hash_locked_only",
+            "redacted_sensitive"
+          ]
+        },
+        "content": {
+          "type": "array"
+        }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "adapter_version",
+        "normalization_version",
+        "sanitized_redactions"
+      ],
+      "properties": {
+        "adapter_version": {
+          "type": "string"
+        },
+        "normalization_version": {
+          "type": "string"
+        },
+        "sanitized_redactions": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "duration_ms": {
+          "type": "number",
+          "minimum": 0
+        }
+      }
+    },
+    "authority": {
+      "$ref": "citable://schemas/evidence-authority.schema.json"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "success",
+        "incomplete",
+        "failed",
+        "unsupported",
+        "unauthorized"
+      ]
+    },
+    "collected_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "limitations": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

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", "browser_journey", "index", "citation", "citation_review", "crawler_log", "crawler_probe", "regional_network", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image", "representation_drift", "stance"] },
+    "kind": { "type": "string", "enum": ["render", "browser_journey", "index", "citation", "citation_review", "crawler_log", "crawler_probe", "regional_network", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image", "representation_drift", "stance", "mcp_transport", "attribution"] },
     "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"] },

package/schemas/remediation-verification.schema.json

@@ -0,0 +1,98 @@
+{
+  "$id": "citable://schemas/remediation-verification.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Remediation verification record",
+  "description": "Closed-loop evidence that a detector finding was addressed: before-run finding, applied patch, re-run detector result, and verdict. Proves only that the detector no longer reports the same subject; it never proves a conversion or outcome guarantee.",
+  "type": "object",
+  "required": [
+    "verification_id", "timestamp", "status", "tool_version",
+    "source_run_id", "detector_id", "subject", "verdict",
+    "provenance", "limitations"
+  ],
+  "properties": {
+    "verification_id": { "type": "string", "pattern": "^VR-[0-9]{14,20}-[a-z0-9]{2,8}$" },
+    "timestamp": { "type": "string" },
+    "status": { "type": "string", "enum": ["verified", "not_resolved", "blocked", "patch_refused"] },
+    "tool_version": { "type": "string" },
+    "repository_commit": { "type": ["string", "null"] },
+    "source_run_id": { "type": ["string", "null"], "minLength": 1 },
+    "recheck_run_id": { "type": ["string", "null"] },
+    "detector_id": { "type": ["string", "null"] },
+    "subject": {
+      "type": ["object", "null"],
+      "properties": {
+        "type": { "type": "string" },
+        "identifier": { "type": ["string", "null"] }
+      }
+    },
+    "verdict": {
+      "type": "object",
+      "required": ["resolved"],
+      "properties": {
+        "resolved": { "type": "boolean" },
+        "before_finding_ids": { "type": "array", "items": { "type": "string" } },
+        "after_finding_ids": { "type": "array", "items": { "type": "string" } },
+        "new_regressions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["finding_id", "detector_id", "severity", "summary"],
+            "properties": {
+              "finding_id": { "type": "string" },
+              "detector_id": { "type": "string" },
+              "severity": { "type": "string" },
+              "summary": { "type": "string" }
+            }
+          }
+        },
+        "resolution_definition": {
+          "type": "string",
+          "description": "States the exact resolution criterion used; detector absence is not an outcome guarantee."
+        }
+      }
+    },
+    "patch": {
+      "type": ["object", "null"],
+      "properties": {
+        "target_file": { "type": "string" },
+        "framework": { "type": ["string", "null"] },
+        "patcher_class": { "type": ["string", "null"] },
+        "confidence": { "type": ["number", "null"] },
+        "validation_passed": { "type": "boolean" },
+        "applied": { "type": "boolean" },
+        "refusal_reason": { "type": ["string", "null"] },
+        "rollback_snapshot": { "type": ["string", "null"] },
+        "before_sha256": { "type": ["string", "null"] },
+        "after_sha256": { "type": ["string", "null"] }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "required": ["command", "recheck_target", "detectors_run"],
+      "properties": {
+        "command": { "type": "string" },
+        "recheck_target": { "type": ["string", "null"] },
+        "detectors_run": { "type": "array", "items": { "type": "string" } },
+        "detectors_skipped": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "detector_id": { "type": "string" },
+              "reason": { "type": "string" }
+            }
+          }
+        },
+        "recheck_errors": { "type": "array", "items": { "type": "string" } },
+        "recheck_warnings": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "limitations": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "bundle_dir": { "type": ["string", "null"] },
+    "bundle_checksums": { "type": "object" }
+  }
+}