@nebulacomponents/citable 1.20.0 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.20.0",
+  "version": "1.22.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/citation-provenance.schema.json

@@ -0,0 +1,59 @@
+{
+  "$id": "citable://schemas/citation-provenance.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Provider citation provenance observation data",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["execution_reference", "response_reference", "provider", "span", "citation", "source", "retrieval", "proposition", "support"],
+  "properties": {
+    "execution_reference": { "type": "string", "minLength": 1 },
+    "response_reference": { "type": "string", "minLength": 1 },
+    "provider": { "type": "string", "minLength": 1 },
+    "span": { "$ref": "citable://schemas/response-span.schema.json" },
+    "citation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["citation_id", "ordinal", "raw_marker", "placement", "displayed_title", "displayed_domain", "displayed_url"],
+      "properties": {
+        "citation_id": { "type": "string", "minLength": 1 },
+        "ordinal": { "type": "integer", "minimum": 1 },
+        "raw_marker": { "type": ["string", "null"] },
+        "placement": { "type": "string", "enum": ["inline", "footnote", "card", "source_list", "unknown"] },
+        "displayed_title": { "type": ["string", "null"] },
+        "displayed_domain": { "type": ["string", "null"] },
+        "displayed_url": { "type": ["string", "null"] }
+      }
+    },
+    "source": {
+      "type": "object", "additionalProperties": false,
+      "required": ["identity_status", "resolved_url", "redirect_chain", "canonical_url"],
+      "properties": {
+        "identity_status": { "type": "string", "enum": ["IDENTIFIED", "NOT_IDENTIFIED", "AMBIGUOUS"] },
+        "resolved_url": { "type": ["string", "null"], "format": "uri" },
+        "redirect_chain": { "type": "array", "items": { "type": "string", "format": "uri" } },
+        "canonical_url": { "type": ["string", "null"], "format": "uri" }
+      }
+    },
+    "retrieval": {
+      "type": "object", "additionalProperties": false,
+      "required": ["status", "observation_reference"],
+      "properties": {
+        "status": { "type": "string", "enum": ["NOT_ATTEMPTED", "ATTEMPTED", "SUCCEEDED", "FAILED", "INDETERMINATE"] },
+        "observation_reference": { "type": ["string", "null"] }
+      }
+    },
+    "proposition": {
+      "type": "object", "additionalProperties": false,
+      "required": ["proposition_id", "text"],
+      "properties": { "proposition_id": { "type": "string", "minLength": 1 }, "text": { "type": "string", "minLength": 1 } }
+    },
+    "support": {
+      "type": "object", "additionalProperties": false,
+      "required": ["relevance_status", "support_status", "evidence_references"],
+      "properties": {
+        "relevance_status": { "type": "string", "enum": ["NOT_ASSESSED", "RELEVANT", "IRRELEVANT", "INDETERMINATE"] },
+        "support_status": { "type": "string", "enum": ["NOT_ASSESSED", "SUPPORTED", "PARTIALLY_SUPPORTED", "UNSUPPORTED", "CONTRADICTED", "INDETERMINATE", "NOT_OBSERVED"] },
+        "evidence_references": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/claim-evidence.schema.json

@@ -0,0 +1,21 @@
+{
+  "$id": "citable://schemas/claim-evidence.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claim to evidence lineage",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["claim_id", "claim_version", "proposition", "declared_scope", "evidence_references", "observation_references", "dataset_references", "derivation_references", "assertion", "limitations", "claim_hash"],
+  "properties": {
+    "claim_id": { "type": "string", "minLength": 1 },
+    "claim_version": { "type": "integer", "minimum": 1 },
+    "proposition": { "type": "string", "minLength": 3 },
+    "declared_scope": { "type": "object", "additionalProperties": false, "required": ["type", "generalization"], "properties": { "type": { "type": "string", "enum": ["observation", "dataset", "declared_population"] }, "observation_reference": { "type": "string" }, "dataset_reference": { "type": "string" }, "generalization": { "type": "string", "enum": ["bounded", "universal"] } } },
+    "evidence_references": { "type": "array", "items": { "type": "string" } },
+    "observation_references": { "type": "array", "items": { "type": "string" } },
+    "dataset_references": { "type": "array", "items": { "type": "string" } },
+    "derivation_references": { "type": "array", "items": { "type": "string" } },
+    "assertion": { "type": "object" },
+    "limitations": { "type": "array", "items": { "type": "string" } },
+    "claim_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/claim-verification.schema.json

@@ -0,0 +1,18 @@
+{
+  "$id": "citable://schemas/claim-verification.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Bounded claim verification result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["claim_id", "claim_version", "overall", "proposition_support", "scope_support", "reasons", "lineage"],
+  "properties": {
+    "claim_id": { "type": "string" },
+    "claim_version": { "type": "integer", "minimum": 1 },
+    "overall": { "type": "string", "enum": ["SUPPORTED", "PARTIALLY_SUPPORTED", "UNSUPPORTED", "CONTRADICTED", "INDETERMINATE", "NOT_OBSERVED"] },
+    "proposition_support": { "type": "string", "enum": ["SUPPORTED", "PARTIALLY_SUPPORTED", "UNSUPPORTED", "CONTRADICTED", "INDETERMINATE", "NOT_OBSERVED"] },
+    "scope_support": { "type": "string", "enum": ["SUPPORTED", "PARTIALLY_SUPPORTED", "UNSUPPORTED", "INDETERMINATE", "NOT_OBSERVED"] },
+    "reasons": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } },
+    "lineage": { "type": "object", "additionalProperties": false, "required": ["claim_reference", "observation_references", "dataset_references", "derivation_references"], "properties": { "claim_reference": { "type": "string" }, "observation_references": { "type": "array", "items": { "type": "string" } }, "dataset_references": { "type": "array", "items": { "type": "string" } }, "derivation_references": { "type": "array", "items": { "type": "string" } } } },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/competitor-representation.schema.json

@@ -0,0 +1,36 @@
+{
+  "$id": "citable://schemas/competitor-representation.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Competitor or peer representation observation data",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["execution_reference", "provider", "prompt_reference", "prompt_set_reference", "span", "entity", "representation", "citation_reference", "proposition_reference"],
+  "properties": {
+    "execution_reference": { "type": "string", "minLength": 1 },
+    "provider": { "type": "string", "minLength": 1 },
+    "prompt_reference": { "type": "string", "minLength": 1 },
+    "prompt_set_reference": { "type": "string", "minLength": 1 },
+    "span": { "$ref": "citable://schemas/response-span.schema.json" },
+    "entity": {
+      "type": "object", "additionalProperties": false,
+      "required": ["entity_id", "observed_name", "domain", "resolution_status", "resolution_method"],
+      "properties": {
+        "entity_id": { "type": ["string", "null"] },
+        "observed_name": { "type": "string", "minLength": 1 },
+        "domain": { "type": ["string", "null"] },
+        "resolution_status": { "type": "string", "enum": ["RESOLVED", "AMBIGUOUS", "UNRESOLVED", "NOT_OBSERVED"] },
+        "resolution_method": { "type": "string", "minLength": 1 }
+      }
+    },
+    "representation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["type", "observed_text"],
+      "properties": {
+        "type": { "type": "string", "enum": ["MENTION", "COMPARISON", "ALTERNATIVE", "RECOMMENDATION", "CITED_SOURCE", "CATEGORY_PEER"] },
+        "observed_text": { "type": "string", "minLength": 1 }
+      }
+    },
+    "citation_reference": { "type": ["string", "null"] },
+    "proposition_reference": { "type": ["string", "null"] }
+  }
+}

package/schemas/derivation.schema.json

@@ -0,0 +1,18 @@
+{
+  "$id": "citable://schemas/derivation.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Evidence derivation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["derivation_id", "derivation_version", "operation", "input_observation_references", "result", "implementation", "derivation_hash"],
+  "properties": {
+    "derivation_id": { "type": "string", "minLength": 1 },
+    "derivation_version": { "type": "integer", "minimum": 1 },
+    "operation": { "type": "string", "minLength": 1 },
+    "input_observation_references": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+    "predicate": { "type": "object", "additionalProperties": false, "required": ["path", "operator", "value"], "properties": { "path": { "type": "string" }, "operator": { "type": "string", "enum": ["equals"] }, "value": {} } },
+    "result": { "type": "object" },
+    "implementation": { "type": "object", "additionalProperties": false, "required": ["id", "version"], "properties": { "id": { "type": "string" }, "version": { "type": "string" } } },
+    "derivation_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/external-comparison.schema.json

@@ -0,0 +1,16 @@
+{
+  "$id": "citable://schemas/external-comparison.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "External evidence comparison",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["comparison_id", "left_reference", "right_reference", "status", "dimensions", "limitations"],
+  "properties": {
+    "comparison_id": { "type": "string", "minLength": 1 },
+    "left_reference": { "type": "string", "minLength": 1 },
+    "right_reference": { "type": "string", "minLength": 1 },
+    "status": { "type": "string", "enum": ["COMPARABLE", "PARTIALLY_COMPARABLE", "NOT_COMPARABLE", "INDETERMINATE"] },
+    "dimensions": { "type": "object", "additionalProperties": { "type": "string", "enum": ["match", "mismatch", "missing", "unknown"] } },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/external-observation.schema.json

@@ -0,0 +1,32 @@
+{
+  "$id": "citable://schemas/external-observation.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Provider-neutral external observation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["observation_id", "observation_type", "subject", "source", "collector", "observed_at", "population", "observation_status", "retrieval_status", "data", "evidence_hash"],
+  "properties": {
+    "observation_id": { "type": "string", "minLength": 1 },
+    "observation_type": { "type": "string", "enum": ["PAGE_OBSERVATION", "EXTERNAL_OBSERVATION", "DERIVED_OBSERVATION"] },
+    "subject": { "type": "object", "additionalProperties": false, "required": ["type", "id"], "properties": { "type": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } } },
+    "source": { "type": "object", "additionalProperties": false, "required": ["provider", "method", "authority"], "properties": { "provider": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "authority": { "type": "string", "enum": ["first_party", "external_provider", "third_party", "synthetic", "inferred", "unknown"] }, "account_or_property": { "type": ["string", "null"] } } },
+    "collector": { "type": "object", "additionalProperties": false, "required": ["id", "version"], "properties": { "id": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } } },
+    "parser": { "type": ["object", "null"], "additionalProperties": false, "required": ["id", "version"], "properties": { "id": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } } },
+    "configuration": { "type": ["object", "null"], "additionalProperties": false, "required": ["id", "version"], "properties": { "id": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } } },
+    "observed_at": { "type": "string", "format": "date-time" },
+    "retrieved_at": { "type": ["string", "null"], "format": "date-time" },
+    "executed_at": { "type": ["string", "null"], "format": "date-time" },
+    "population": { "$ref": "#/definitions/population" },
+    "observation_status": { "type": "string", "enum": ["observed", "not_observed", "incomplete", "indeterminate", "failed"] },
+    "retrieval_status": { "type": "string", "enum": ["retrieved", "not_retrieved", "partial", "indeterminate", "failed"] },
+    "determination_status": { "type": ["string", "null"], "enum": ["pass", "fail", "warning", "indeterminate", "not_tested", "error", "not_applicable", null] },
+    "data": { "type": "object" },
+    "context": { "type": "object", "additionalProperties": false, "properties": { "observed": { "type": "object" }, "supplied": { "type": "object" } } },
+    "lineage": { "type": "object", "additionalProperties": false, "properties": { "source_evidence": { "type": "array", "items": { "type": "string" } }, "predecessor_references": { "type": "array", "items": { "type": "string" } }, "successor_references": { "type": "array", "items": { "type": "string" } }, "derivation_inputs": { "type": "array", "items": { "type": "string" } }, "package_reference": { "type": ["string", "null"] } } },
+    "limitations": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "evidence_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  },
+  "definitions": {
+    "population": { "type": "object", "additionalProperties": false, "required": ["declared", "observed", "retrieved", "evaluated", "unavailable", "failed"], "properties": { "declared": { "type": ["object", "null"], "additionalProperties": false, "properties": { "id": { "type": "string" }, "size": { "type": "integer", "minimum": 0 } } }, "observed": { "type": "integer", "minimum": 0 }, "retrieved": { "type": "integer", "minimum": 0 }, "evaluated": { "type": "integer", "minimum": 0 }, "unavailable": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } } }
+  }
+}

package/schemas/prompt-set.schema.json

@@ -0,0 +1,47 @@
+{
+  "$id": "citable://schemas/prompt-set.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Immutable versioned prompt population",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["prompt_set_id", "prompt_set_version", "purpose", "generation_method", "generated_at", "population_size", "sampling_method", "included_prompts", "excluded_prompts", "intended_population", "limitations", "prompt_set_hash"],
+  "properties": {
+    "prompt_set_id": { "type": "string", "minLength": 1 },
+    "prompt_set_version": { "type": "integer", "minimum": 1 },
+    "purpose": { "type": "string", "minLength": 1 },
+    "generation_method": { "type": "string", "minLength": 1 },
+    "generation_method_version": { "type": ["string", "null"] },
+    "generation_input": {},
+    "generated_at": { "type": "string", "format": "date-time" },
+    "population_size": { "type": "integer", "minimum": 0 },
+    "sampling_method": { "type": "string", "minLength": 1 },
+    "included_prompts": { "type": "array", "items": { "$ref": "#/definitions/prompt" } },
+    "excluded_prompts": { "type": "array", "items": { "$ref": "#/definitions/excludedPrompt" } },
+    "intended_population": { "type": "string", "minLength": 1 },
+    "limitations": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "prompt_set_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  },
+  "definitions": {
+    "prompt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["prompt_id", "prompt_text"],
+      "properties": {
+        "prompt_id": { "type": "string", "minLength": 1 },
+        "prompt_text": { "type": "string", "minLength": 1 },
+        "context": { "type": ["object", "null"] },
+        "locale": { "type": ["string", "null"] }
+      }
+    },
+    "excludedPrompt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["prompt_id", "exclusion_reason"],
+      "properties": {
+        "prompt_id": { "type": "string", "minLength": 1 },
+        "prompt_text": { "type": ["string", "null"] },
+        "exclusion_reason": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/schemas/representation-data.schema.json

@@ -0,0 +1,21 @@
+{
+  "$id": "citable://schemas/representation-data.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Provider-neutral AI representation observation data",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["provider", "product", "surface", "model", "prompt", "prompt_set", "execution", "response", "representation", "evidence_origin"],
+  "properties": {
+    "provider": { "type": "string", "minLength": 1 },
+    "product": { "type": "string", "minLength": 1 },
+    "surface": { "type": "string", "minLength": 1 },
+    "model": { "type": "object", "additionalProperties": false, "required": ["value", "status"], "properties": { "value": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["known", "UNKNOWN", "UNAVAILABLE", "NOT_DISCLOSED"] } } },
+    "prompt": { "type": "object", "additionalProperties": false, "required": ["prompt_id", "prompt_version", "prompt_text"], "properties": { "prompt_id": { "type": "string", "minLength": 1 }, "prompt_version": { "type": "integer", "minimum": 1 }, "prompt_text": { "type": "string", "minLength": 1 } } },
+    "prompt_set": { "type": "object", "additionalProperties": false, "required": ["prompt_set_id", "prompt_set_version"], "properties": { "prompt_set_id": { "type": "string", "minLength": 1 }, "prompt_set_version": { "type": "integer", "minimum": 1 } } },
+    "execution": { "type": "object", "additionalProperties": false, "required": ["executed_at", "configuration"], "properties": { "executed_at": { "type": "string", "format": "date-time" }, "configuration": { "type": "object", "additionalProperties": false, "required": ["id", "version"], "properties": { "id": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } } } } },
+    "response": { "type": "object", "additionalProperties": false, "required": ["status", "response_hash", "parser", "raw_response_retained"], "properties": { "status": { "type": "string", "enum": ["succeeded", "refused", "error", "timeout", "rate_limited", "malformed", "unavailable", "parser_failed"] }, "response_hash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" }, "parser": { "type": "object", "additionalProperties": false, "required": ["id", "version"], "properties": { "id": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } } }, "raw_response_retained": { "type": "boolean" }, "provider_metadata": { "type": "object" } } },
+    "representation": { "type": "object", "additionalProperties": false, "required": ["brand_mentioned", "domain_mentioned", "domain_cited", "cited_urls", "mentioned_entities", "cited_domains"], "properties": { "brand_mentioned": { "type": ["boolean", "null"] }, "domain_mentioned": { "type": ["boolean", "null"] }, "domain_cited": { "type": ["boolean", "null"] }, "cited_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "mentioned_entities": { "type": "array", "items": { "type": "string" } }, "cited_domains": { "type": "array", "items": { "type": "string" } } } },
+    "evidence_origin": { "type": "string", "enum": ["LIVE_PROVIDER", "RECORDED_FIXTURE", "SYNTHETIC_TEST"] },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/research-dataset.schema.json

@@ -0,0 +1,27 @@
+{
+  "$id": "citable://schemas/research-dataset.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Immutable research dataset",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["dataset_id", "dataset_version", "declared_purpose", "declared_population", "population_size", "inclusion_criteria", "exclusion_criteria", "collection", "source_references", "observation_references", "normalization", "derivation_references", "coverage", "coverage_status", "limitations", "dataset_hash"],
+  "properties": {
+    "dataset_id": { "type": "string", "minLength": 1 },
+    "dataset_version": { "type": "integer", "minimum": 1 },
+    "declared_purpose": { "type": "string", "minLength": 1 },
+    "declared_population": { "type": "object", "additionalProperties": false, "required": ["type", "id"], "properties": { "type": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "size": { "type": ["integer", "null"], "minimum": 0 } } },
+    "population_size": { "type": ["integer", "null"], "minimum": 0 },
+    "inclusion_criteria": { "type": "array", "items": { "type": "string" } },
+    "exclusion_criteria": { "type": "array", "items": { "type": "string" } },
+    "collection": { "type": "object", "additionalProperties": false, "required": ["started_at", "ended_at"], "properties": { "started_at": { "type": "string", "format": "date-time" }, "ended_at": { "type": "string", "format": "date-time" } } },
+    "source_references": { "type": "array", "items": { "type": "string" } },
+    "source_retrieval_timestamps": { "type": "array", "items": { "type": "string", "format": "date-time" } },
+    "observation_references": { "type": "array", "items": { "type": "string" } },
+    "normalization": { "type": "object", "additionalProperties": false, "required": ["method", "version"], "properties": { "method": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } } },
+    "derivation_references": { "type": "array", "items": { "type": "string" } },
+    "coverage": { "type": "object", "additionalProperties": false, "required": ["declared", "retrieved", "evaluated", "unavailable", "failed"], "properties": { "declared": { "type": "integer", "minimum": 0 }, "retrieved": { "type": "integer", "minimum": 0 }, "evaluated": { "type": "integer", "minimum": 0 }, "unavailable": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } } },
+    "coverage_status": { "type": "string", "enum": ["complete_for_declared_population", "partial", "truncated", "indeterminate", "error"] },
+    "limitations": { "type": "array", "items": { "type": "string" } },
+    "dataset_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/response-span.schema.json

@@ -0,0 +1,16 @@
+{
+  "$id": "citable://schemas/response-span.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Immutable provider response span",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["span_id", "execution_reference", "start", "end", "text", "text_hash"],
+  "properties": {
+    "span_id": { "type": "string", "minLength": 1 },
+    "execution_reference": { "type": "string", "minLength": 1 },
+    "start": { "type": "integer", "minimum": 0 },
+    "end": { "type": "integer", "minimum": 0 },
+    "text": { "type": "string" },
+    "text_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/search-discovery-data.schema.json

@@ -0,0 +1,20 @@
+{
+  "$id": "citable://schemas/search-discovery-data.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Search discovery observation data",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["query", "page", "interval", "metrics", "request", "coverage_status", "evidence_origin"],
+  "properties": {
+    "query": { "type": ["string", "null"] },
+    "page": { "type": ["string", "null"], "format": "uri" },
+    "interval": { "type": "object", "additionalProperties": false, "required": ["start_date", "end_date"], "properties": { "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } } },
+    "metrics": { "type": "object", "additionalProperties": false, "required": ["impressions", "clicks", "ctr", "average_position"], "properties": { "impressions": { "type": ["number", "null"], "minimum": 0 }, "clicks": { "type": ["number", "null"], "minimum": 0 }, "ctr": { "type": ["number", "null"], "minimum": 0 }, "average_position": { "type": ["number", "null"], "minimum": 0 } } },
+    "dimensions": { "type": "object", "additionalProperties": false, "properties": { "country": { "type": ["string", "null"] }, "device": { "type": ["string", "null"] }, "search_appearance": { "type": ["string", "null"] }, "date": { "type": ["string", "null"], "format": "date" } } },
+    "request": { "type": "object", "additionalProperties": false, "required": ["property_id", "dimensions", "filters", "row_limit"], "properties": { "property_id": { "type": "string", "minLength": 1 }, "dimensions": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "object" }, "row_limit": { "type": "integer", "minimum": 1, "maximum": 25000 } } },
+    "provider_reported": { "type": "object", "additionalProperties": false, "properties": { "row_count": { "type": ["integer", "null"], "minimum": 0 }, "page_start": { "type": "integer", "minimum": 0 } } },
+    "response_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "coverage_status": { "type": "string", "enum": ["complete", "truncated", "indeterminate", "provider_bounded"] },
+    "evidence_origin": { "type": "string", "enum": ["LIVE_PROVIDER", "RECORDED_FIXTURE", "SYNTHETIC_TEST"] }
+  }
+}

package/schemas/source-retrieval.schema.json

@@ -0,0 +1,41 @@
+{
+  "$id": "citable://schemas/source-retrieval.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Retrieved citation source observation data",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["citation_reference", "url", "retrieval", "content", "relevance"],
+  "properties": {
+    "citation_reference": { "type": "string", "minLength": 1 },
+    "url": { "type": "string", "format": "uri" },
+    "retrieval": {
+      "type": "object", "additionalProperties": false,
+      "required": ["status", "attempted_at", "final_url", "redirect_chain", "http_status"],
+      "properties": {
+        "status": { "type": "string", "enum": ["SUCCEEDED", "FAILED", "INDETERMINATE"] },
+        "attempted_at": { "type": "string", "format": "date-time" },
+        "final_url": { "type": ["string", "null"], "format": "uri" },
+        "redirect_chain": { "type": "array", "items": { "type": "string", "format": "uri" } },
+        "http_status": { "type": ["integer", "null"], "minimum": 100, "maximum": 599 }
+      }
+    },
+    "content": {
+      "type": "object", "additionalProperties": false,
+      "required": ["observed", "content_hash", "raw_retained"],
+      "properties": {
+        "observed": { "type": "boolean" },
+        "content_hash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+        "raw_retained": { "type": "boolean" }
+      }
+    },
+    "relevance": {
+      "type": "object", "additionalProperties": false,
+      "required": ["status", "support_status", "evidence_references"],
+      "properties": {
+        "status": { "type": "string", "enum": ["NOT_ASSESSED", "RELEVANT", "IRRELEVANT", "INDETERMINATE"] },
+        "support_status": { "type": "string", "enum": ["NOT_ASSESSED", "SUPPORTED", "PARTIALLY_SUPPORTED", "UNSUPPORTED", "CONTRADICTED", "INDETERMINATE", "NOT_OBSERVED"] },
+        "evidence_references": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: >
   generative engine optimization, structured data governance, claim substantiation,
   crawler policy, entity consistency, content discoverability, or wants a site audited
   for how search and AI systems will retrieve, understand, cite, or recommend it.
-version: 1.20.0
+version: 1.22.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness

package/src/connectors/gsc.js

@@ -1,5 +1,6 @@
 import { providerRequest } from './http.js';
 import { collectionResult, errorMessage, paginationBoundary } from './collectionResult.js';
+import { collectSearchConsoleObservations } from '../discovery/searchConsole.js';
 
 const BASE = 'https://www.googleapis.com/webmasters/v3';
 const METRICS = {
@@ -73,4 +74,7 @@ export const gscConnector = {
     });
     return { rows, cursor: endDate, limitations: collection.limitations, collection, ...(connectorError ? { connectorError } : {}) };
   },
+  async collectObservations(connection, request, context = {}) {
+    return collectSearchConsoleObservations({ connection, request, ...context });
+  },
 };