@nebulacomponents/citable 1.20.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.20.0",
+  "version": "1.21.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/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/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/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/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.21.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 });
+  },
 };

package/src/discovery/searchConsole.js

@@ -0,0 +1,186 @@
+import { createExternalObservation, verifyExternalObservation } from '../evidence/external.js';
+import { canonicalEvidenceJson } from '../evidence/hashes.js';
+import { sha256, nowIso } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import { providerRequest } from '../connectors/http.js';
+import { collectionResult, errorMessage } from '../connectors/collectionResult.js';
+
+const SEARCH_DATA_SCHEMA = 'search-discovery-data.schema.json';
+const BASE = 'https://www.googleapis.com/webmasters/v3';
+const DIMENSIONS = new Set(['date', 'query', 'page', 'country', 'device', 'searchAppearance']);
+const COLLECTOR = { id: 'citable-search-console-observations', version: '1.0.0' };
+const PARSER = { id: 'google-search-analytics-response', version: '1.0.0' };
+
+function assertDate(value, name) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00Z`))) {
+    throw new TypeError(`${name} must be an ISO date (YYYY-MM-DD)`);
+  }
+}
+
+function validateRequest(request) {
+  if (!request || typeof request !== 'object' || Array.isArray(request)) throw new TypeError('Search Console request is required');
+  if (typeof request.property_id !== 'string' || !request.property_id) throw new TypeError('property_id is required');
+  assertDate(request.start_date, 'start_date');
+  assertDate(request.end_date, 'end_date');
+  if (request.start_date > request.end_date) throw new RangeError('start_date must not be after end_date');
+  const dimensions = request.dimensions ?? ['query', 'page'];
+  if (!Array.isArray(dimensions) || dimensions.length === 0 || dimensions.some((item) => !DIMENSIONS.has(item))) throw new TypeError('dimensions contain an unsupported Search Console dimension');
+  const filters = request.filters ?? {};
+  if (!filters || typeof filters !== 'object' || Array.isArray(filters)) throw new TypeError('filters must be an object');
+  const rowLimit = request.row_limit ?? 25000;
+  if (!Number.isInteger(rowLimit) || rowLimit < 1 || rowLimit > 25000) throw new RangeError('row_limit must be an integer from 1 to 25000');
+  return { property_id: request.property_id, start_date: request.start_date, end_date: request.end_date, dimensions: [...new Set(dimensions)], filters, row_limit: rowLimit };
+}
+
+function configurationFor(request) {
+  const configuration = { property_id: request.property_id, dimensions: request.dimensions, filters: request.filters, row_limit: request.row_limit };
+  return { id: `gsc-${sha256(canonicalEvidenceJson(configuration)).slice(0, 16)}`, version: '1.0.0' };
+}
+
+function numberOrNull(value) {
+  return value == null || value === '' || !Number.isFinite(Number(value)) ? null : Number(value);
+}
+
+function requestBody(request, startRow) {
+  const body = { startDate: request.start_date, endDate: request.end_date, dimensions: request.dimensions, rowLimit: request.row_limit, startRow, dataState: 'final' };
+  if (Object.keys(request.filters).length) body.dimensionFilterGroups = [{ groupType: 'and', filters: Object.entries(request.filters).map(([dimension, expression]) => ({ dimension, operator: 'equals', expression: String(expression) })) }];
+  return body;
+}
+
+function normalizeRow(row, request, dimensions, pageStart, coverageStatus, providerTotal, responseHash, origin) {
+  if (!row || !Array.isArray(row.keys)) throw new TypeError('Search Console row is malformed');
+  const values = Object.fromEntries(dimensions.map((name, index) => [name, row.keys[index] ?? null]));
+  const data = {
+    query: values.query ?? null,
+    page: values.page ?? null,
+    interval: { start_date: request.start_date, end_date: request.end_date },
+    metrics: { impressions: numberOrNull(row.impressions), clicks: numberOrNull(row.clicks), ctr: numberOrNull(row.ctr), average_position: numberOrNull(row.position) },
+    dimensions: { country: values.country ?? null, device: values.device ?? null, search_appearance: values.searchAppearance ?? null, date: values.date ?? null },
+    request: { property_id: request.property_id, dimensions: request.dimensions, filters: request.filters, row_limit: request.row_limit },
+    provider_reported: { row_count: providerTotal, page_start: pageStart },
+    coverage_status: coverageStatus,
+    response_hash: responseHash,
+    evidence_origin: origin,
+  };
+  const check = validateAgainst(SEARCH_DATA_SCHEMA, data);
+  if (!check.valid) throw new TypeError(`search discovery data violates contract: ${check.errors.join('; ')}`);
+  const subjectId = `query:${data.query ?? ''}|page:${data.page ?? ''}`;
+  return createExternalObservation({
+    observation_id: `GSC-${sha256(canonicalEvidenceJson({ request, values, row })).slice(0, 24)}`,
+    observation_type: 'EXTERNAL_OBSERVATION',
+    subject: { type: 'search_query_page', id: subjectId || `row:${pageStart}` },
+    source: { provider: 'google_search_console', method: 'search_analytics_api', authority: 'external_provider', account_or_property: request.property_id },
+    collector: COLLECTOR,
+    parser: PARSER,
+    configuration: configurationFor(request),
+    observed_at: nowIso(),
+    retrieved_at: nowIso(),
+    population: { declared: { id: `GSC-${sha256(canonicalEvidenceJson(request)).slice(0, 16)}`, size: providerTotal }, observed: 1, retrieved: 1, evaluated: 1, unavailable: 0, failed: 0 },
+    observation_status: coverageStatus === 'complete' ? 'observed' : 'incomplete',
+    retrieval_status: coverageStatus === 'complete' ? 'retrieved' : coverageStatus === 'indeterminate' ? 'indeterminate' : 'partial',
+    data,
+    lineage: { source_evidence: [responseHash] },
+    limitations: ['Search Console reports provider-returned search analytics rows, not universal search demand.', 'Provider privacy filtering, aggregation, and reporting revisions may limit representativeness.'],
+  });
+}
+
+/**
+ * Collect normalized Search Console search-analytics observations. This is a
+ * provider adapter: credentials are supplied only to the transport and are
+ * never written into observations or continuation state.
+ */
+export async function collectSearchConsoleObservations({ connection, request, token, fetchImpl = globalThis.fetch, maxPages = 1000, evidenceOrigin = 'LIVE_PROVIDER' } = {}) {
+  const normalized = validateRequest(request);
+  if (!['LIVE_PROVIDER', 'RECORDED_FIXTURE', 'SYNTHETIC_TEST'].includes(evidenceOrigin)) throw new TypeError('evidenceOrigin is invalid');
+  if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 10000) throw new RangeError('maxPages must be an integer from 1 to 10000');
+  if (connection?.property_id && connection.property_id !== normalized.property_id) throw new Error('connection property_id does not match request property_id');
+  const dimensions = normalized.dimensions;
+  const rows = [];
+  const observations = [];
+  const errors = [];
+  let startRow = 0;
+  let providerTotal = null;
+  let continuationState = null;
+  let pagesRequested = 0;
+  let pagesRetrieved = 0;
+  let lastResponseHash = null;
+  let response;
+  do {
+    pagesRequested += 1;
+    try {
+      response = await providerRequest(`${BASE}/sites/${encodeURIComponent(normalized.property_id)}/searchAnalytics/query`, {
+        token, fetchImpl, method: 'POST', body: requestBody(normalized, startRow),
+      });
+      if (!response || !Array.isArray(response.rows)) throw new Error('Search Console response rows must be an array');
+    } catch (error) {
+      errors.push(`start row ${startRow}: ${errorMessage(error)}`);
+      continuationState = { start_row: startRow };
+      break;
+    }
+    pagesRetrieved += 1;
+    lastResponseHash = sha256(canonicalEvidenceJson(response));
+    if (Number.isInteger(response.rowCount) && response.rowCount >= 0) providerTotal = response.rowCount;
+    rows.push(...response.rows.map((row) => ({ row, pageStart: startRow, responseHash: lastResponseHash })));
+    const moreRows = providerTotal !== null && rows.length < providerTotal;
+    if (providerTotal !== null && !moreRows) break;
+    if (providerTotal === null && response.rows.length < normalized.row_limit) break;
+    startRow += normalized.row_limit;
+    if (pagesRequested >= maxPages) {
+      continuationState = { start_row: startRow };
+      break;
+    }
+  } while (true);
+
+  const collection = collectionResult({
+    items: rows,
+    paginationState: { pages_requested: pagesRequested, pages_retrieved: pagesRetrieved, boundary: { max_pages: maxPages, row_limit: normalized.row_limit } },
+    providerReportedTotal: providerTotal,
+    continuationState,
+    providerCompleteness: providerTotal !== null ? 'declared' : 'unknown',
+    limitations: ['Search Console privacy filtering and aggregation apply.', 'A complete result is complete only for the declared API request; it is not a census of all search behavior.'],
+    errors,
+  });
+  const normalizedRows = rows.map(({ row, pageStart, responseHash }) => normalizeRow(row, normalized, dimensions, pageStart, collection.coverage_status, providerTotal, responseHash || sha256(canonicalEvidenceJson({ request: normalized, rows: [] })), evidenceOrigin));
+  observations.push(...normalizedRows);
+  return { observations, collection, request: normalized, provider: 'google_search_console', response_hash: lastResponseHash, errors };
+}
+
+export function compareSearchDiscoveryObservations(left, right) {
+  if (!verifyExternalObservation(left).valid || !verifyExternalObservation(right).valid) return { status: 'INDETERMINATE', dimensions: {}, limitations: ['Observation integrity could not be verified.'] };
+  const dimensions = {
+    provider: left.source.provider === right.source.provider ? 'match' : 'mismatch',
+    property: left.source.account_or_property === right.source.account_or_property ? 'match' : 'mismatch',
+    query: left.data.query === right.data.query ? 'match' : 'mismatch',
+    page: left.data.page === right.data.page ? 'match' : 'mismatch',
+    configuration: left.configuration?.id === right.configuration?.id ? 'match' : 'mismatch',
+    interval: JSON.stringify(left.data.interval) === JSON.stringify(right.data.interval) ? 'match' : 'mismatch',
+    coverage: left.data.coverage_status === right.data.coverage_status ? 'match' : 'mismatch',
+  };
+  const hardMismatch = ['provider', 'property', 'query', 'page', 'configuration'].some((key) => dimensions[key] === 'mismatch');
+  const incomplete = [left.data.coverage_status, right.data.coverage_status].some((status) => !['complete'].includes(status));
+  const status = hardMismatch ? 'NOT_COMPARABLE' : incomplete ? 'INDETERMINATE' : dimensions.interval === 'mismatch' ? 'PARTIALLY_COMPARABLE' : 'COMPARABLE';
+  return {
+    comparison_id: `GSC-CMP-${sha256(canonicalEvidenceJson({ left: left.observation_id, right: right.observation_id, dimensions })).slice(0, 16)}`,
+    left_reference: left.observation_id,
+    right_reference: right.observation_id,
+    status,
+    dimensions,
+    limitations: status === 'COMPARABLE' ? [] : ['Search Console interval, configuration, and coverage limitations remain attached; no business opportunity or ranking conclusion is inferred.'],
+  };
+}
+
+function validSearchObservations(observations) {
+  return (Array.isArray(observations) ? observations : []).filter((item) => verifyExternalObservation(item).valid && item.source?.provider === 'google_search_console');
+}
+
+export function pagesForQuery(observations, query) {
+  return validSearchObservations(observations).filter((item) => item.data.query === query && item.data.page).map((item) => item);
+}
+
+export function queriesForPage(observations, page) {
+  return validSearchObservations(observations).filter((item) => item.data.page === page && item.data.query).map((item) => item);
+}
+
+export function relationshipObservations(observations, { query = null, page = null } = {}) {
+  return validSearchObservations(observations).filter((item) => (query == null || item.data.query === query) && (page == null || item.data.page === page));
+}