@nebulacomponents/citable 1.18.2 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.18.2",
+  "version": "1.20.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/action-plan.schema.json

@@ -4,11 +4,23 @@
   "title": "Finding action plan",
   "type": "object",
   "additionalProperties": false,
-  "required": ["source_run_id", "source_findings_hash", "generated_at", "summary", "actions"],
+  "required": ["source_run_id", "source_findings_hash", "generated_at", "summary", "actions", "source_coverage"],
   "properties": {
     "source_run_id": { "type": "string", "minLength": 1 },
     "source_findings_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
     "generated_at": { "type": "string" },
+    "source_coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["coverage_status", "determination_status", "evidence_scope", "limitations"],
+      "properties": {
+        "coverage_status": { "type": "string", "enum": ["complete", "truncated", "indeterminate", "not_applicable"] },
+        "determination_status": { "type": "string", "enum": ["supported", "qualified", "indeterminate", "not_applicable"] },
+        "artifact": { "type": ["string", "null"] },
+        "evidence_scope": { "$ref": "#/definitions/evidenceScope" },
+        "limitations": { "type": "array", "items": { "type": "string" } }
+      }
+    },
     "summary": {
       "type": "object",
       "additionalProperties": false,
@@ -40,6 +52,10 @@
           "owner": { "type": ["string", "null"] },
           "decision_owner": { "type": ["string", "null"] },
           "status": { "type": "string", "enum": ["ready", "blocked"] },
+          "coverage_status": { "type": "string", "enum": ["complete", "truncated", "indeterminate", "not_applicable"] },
+          "determination_status": { "type": "string", "enum": ["supported", "qualified", "indeterminate", "not_applicable"] },
+          "evidence_scope": { "$ref": "#/definitions/evidenceScope" },
+          "limitations": { "type": "array", "items": { "type": "string" } },
           "required_input": { "type": "array", "items": { "type": "string" } },
           "semantic_gates": { "type": "array", "items": { "type": "string" } },
           "unsafe_shortcuts": { "type": "array", "items": { "type": "string" } },
@@ -64,5 +80,26 @@
         }
       }
     }
+  },
+  "definitions": {
+    "evidenceScope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requirement", "satisfaction", "coverage_ref", "resource_ids"],
+      "properties": {
+        "requirement": { "type": "string", "minLength": 1 },
+        "satisfaction": { "type": "string", "enum": ["supported", "qualified", "indeterminate", "not_applicable"] },
+        "coverage_ref": { "type": ["string", "null"] },
+        "resource_ids": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "population": { "type": "string", "enum": ["evaluated_subset", "none_observed"] },
+        "evaluated": { "type": ["integer", "null"], "minimum": 0 },
+        "eligible": { "type": ["integer", "null"], "minimum": 0 },
+        "excluded": { "type": ["integer", "null"], "minimum": 0 },
+        "failed": { "type": ["integer", "null"], "minimum": 0 },
+        "indeterminate": { "type": ["integer", "null"], "minimum": 0 },
+        "unvisited": { "type": ["integer", "null"], "minimum": 0 },
+        "denominator": { "type": ["integer", "null"], "minimum": 0 }
+      }
+    }
   }
 }

package/schemas/audit-coverage.schema.json

@@ -0,0 +1,118 @@
+{
+  "$id": "citable://schemas/audit-coverage.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Audit coverage",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "normalization_version",
+    "requested_scope",
+    "discovery",
+    "populations",
+    "resources",
+    "stop_reason",
+    "coverage_status",
+    "reconciliation",
+    "limitations"
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "normalization_version": { "type": "string", "minLength": 1 },
+    "requested_scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["start_url", "origin", "max_pages", "time_budget_seconds"],
+      "properties": {
+        "start_url": { "type": "string", "format": "uri" },
+        "origin": { "type": "string", "format": "uri" },
+        "max_pages": { "type": "integer", "minimum": 1, "maximum": 10000 },
+        "time_budget_seconds": { "type": "integer", "minimum": 1, "maximum": 86400 }
+      }
+    },
+    "discovery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "methods", "limitations"],
+      "properties": {
+        "status": { "type": "string", "enum": ["complete", "truncated", "indeterminate"] },
+        "methods": { "type": "array", "items": { "type": "string" } },
+        "limitations": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "populations": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "discovered",
+        "eligible",
+        "excluded",
+        "attempted",
+        "retrieved",
+        "valid_resource",
+        "evaluated",
+        "valid_but_unevaluated",
+        "failed",
+        "indeterminate",
+        "unvisited"
+      ],
+      "properties": {
+        "discovered": { "$ref": "#/definitions/populationCount" },
+        "eligible": { "$ref": "#/definitions/populationCount" },
+        "excluded": { "$ref": "#/definitions/populationCount" },
+        "attempted": { "$ref": "#/definitions/populationCount" },
+        "retrieved": { "$ref": "#/definitions/populationCount" },
+        "valid_resource": { "$ref": "#/definitions/populationCount" },
+        "evaluated": { "$ref": "#/definitions/populationCount" },
+        "valid_but_unevaluated": { "$ref": "#/definitions/populationCount" },
+        "failed": { "$ref": "#/definitions/populationCount" },
+        "indeterminate": { "$ref": "#/definitions/populationCount" },
+        "unvisited": { "$ref": "#/definitions/populationCount" }
+      }
+    },
+    "resources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "resource_id": { "type": ["string", "null"] },
+          "requested_url": { "type": ["string", "null"] },
+          "effective_url": { "type": ["string", "null"] },
+          "canonical_url": { "type": ["string", "null"] },
+          "response_body_hash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+          "rendered_dom_hash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+          "extracted_text_hash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+          "structured_data_hash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+          "evidence_hash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+          "artifact_hash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" }
+        }
+      }
+    },
+    "stop_reason": {
+      "type": "string",
+      "enum": [
+        "frontier_exhausted",
+        "page_budget_exhausted",
+        "time_budget_exhausted",
+        "fatal_collection_failure"
+      ]
+    },
+    "coverage_status": {
+      "type": "string",
+      "enum": ["complete", "truncated", "indeterminate", "not_applicable"]
+    },
+    "reconciliation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["valid", "errors"],
+      "properties": {
+        "valid": { "type": "boolean" },
+        "errors": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  },
+  "definitions": {
+    "populationCount": { "type": "integer", "minimum": 0 }
+  }
+}

package/schemas/browser-evidence-plan.schema.json

@@ -5,6 +5,181 @@
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_version", "plan_id", "target", "profiles", "limitations"],
+  "definitions": {
+    "network_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "allowed_host_patterns": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "allowed_methods": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"] }
+        },
+        "allowed_resource_types": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "eventsource", "websocket", "manifest", "other"] }
+        },
+        "capture_request_headers": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "capture_response_headers": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "capture_query_params": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "capture_payload": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "request_body": { "type": "boolean" },
+            "response_body": { "type": "boolean" },
+            "allowed_json_fields": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "hash_only": { "type": "boolean" },
+            "max_bytes": { "type": "integer", "minimum": 0, "maximum": 65536 }
+          }
+        },
+        "max_events": { "type": "integer", "minimum": 1, "maximum": 1000 },
+        "max_field_size": { "type": "integer", "minimum": 1, "maximum": 8192 },
+        "settling_timeout_ms": { "type": "integer", "minimum": 0, "maximum": 5000 }
+      }
+    },
+    "state_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "checkpoints": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["initial", "step", "final"] }
+        },
+        "capture_url": { "type": "boolean" },
+        "allowed_query_params": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "capture_referrer": { "type": "boolean" },
+        "capture_navigation": { "type": "boolean" },
+        "cookies": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "allowed_names": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "mode": { "enum": ["presence_only", "hash_only", "allowlist_values"] },
+            "max_keys": { "type": "integer", "minimum": 1, "maximum": 100 }
+          }
+        },
+        "local_storage": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "allowed_keys": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "mode": { "enum": ["presence_only", "hash_only", "allowlist_values"] },
+            "max_keys": { "type": "integer", "minimum": 1, "maximum": 100 }
+          }
+        },
+        "session_storage": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "allowed_keys": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "mode": { "enum": ["presence_only", "hash_only", "allowlist_values"] },
+            "max_keys": { "type": "integer", "minimum": 1, "maximum": 100 }
+          }
+        },
+        "globals": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "expression"],
+            "properties": {
+              "name": { "type": "string", "pattern": "^[a-zA-Z0-9_.-]+$" },
+              "expression": { "type": "string", "pattern": "^[a-zA-Z0-9_$.\\[\\]'\"]+$" },
+              "mode": { "enum": ["presence_only", "type_only", "hash_only", "scalar_value"] }
+            }
+          }
+        },
+        "dom_queries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "selector", "property"],
+            "properties": {
+              "name": { "type": "string", "pattern": "^[a-zA-Z0-9_.-]+$" },
+              "selector": { "type": "string", "minLength": 1 },
+              "property": { "enum": ["presence", "visible", "text_hash", "text_length", "text_content", "attribute_value"] },
+              "attribute_name": { "type": "string" }
+            }
+          }
+        },
+        "max_observations": { "type": "integer", "minimum": 1, "maximum": 500 },
+        "max_value_length": { "type": "integer", "minimum": 1, "maximum": 4096 }
+      }
+    },
+    "runtime_event_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "sources": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["source_id", "type"],
+            "properties": {
+              "source_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+              "type": { "enum": ["global_array", "window_event", "custom_stream"] },
+              "global_name": { "type": "string", "pattern": "^[a-zA-Z0-9_.]+$" },
+              "event_name": { "type": "string", "minLength": 1 },
+              "event_name_key": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "allowed_event_names": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "allowed_fields": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "hash_fields": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "redact_fields": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "max_events": { "type": "integer", "minimum": 1, "maximum": 1000 },
+        "max_payload_depth": { "type": "integer", "minimum": 1, "maximum": 10 },
+        "max_field_size": { "type": "integer", "minimum": 1, "maximum": 4096 }
+      }
+    }
+  },
   "properties": {
     "schema_version": { "const": 1 },
     "plan_id": { "type": "string", "pattern": "^BROWSER-PLAN-[A-Z0-9_-]+$" },
@@ -16,13 +191,16 @@
       "properties": {
         "policy_id": { "type": "string", "pattern": "^RENDER-POLICY-[A-Z0-9_-]+$" },
         "review_owner": { "type": "string", "minLength": 1 },
-        "min_text_retention_ratio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "min_text_retention_ratio": { "number": 0, "minimum": 0, "maximum": 1 },
         "require_heading_parity": { "type": "boolean" },
         "require_link_parity": { "type": "boolean" },
         "require_structured_data_parity": { "type": "boolean" },
         "limitations": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
       }
     },
+    "network_policy": { "$ref": "#/definitions/network_policy" },
+    "state_policy": { "$ref": "#/definitions/state_policy" },
+    "runtime_event_policy": { "$ref": "#/definitions/runtime_event_policy" },
     "profiles": {
       "type": "array",
       "minItems": 1,
@@ -63,6 +241,9 @@
           "locale": { "type": "string", "minLength": 2 },
           "consent_state": { "enum": ["not_present", "denied", "granted", "unresolved", "unknown"] },
           "authentication_state": { "enum": ["anonymous", "owner_authenticated", "unresolved", "unknown"] },
+          "network_policy": { "$ref": "#/definitions/network_policy" },
+          "state_policy": { "$ref": "#/definitions/state_policy" },
+          "runtime_event_policy": { "$ref": "#/definitions/runtime_event_policy" },
           "steps": {
             "type": "array",
             "items": {
@@ -71,13 +252,15 @@
               "required": ["step_id", "action", "locator", "value_env", "key", "url", "required", "capture_screenshot"],
               "properties": {
                 "step_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
-                "action": { "enum": ["navigate", "click", "fill", "select_option", "check", "press", "wait_for", "assert_visible", "scroll"] },
+                "action": { "enum": ["navigate", "click", "fill", "select_option", "check", "press", "wait_for", "assert_visible", "scroll", "checkpoint"] },
                 "locator": { "type": ["string", "null"] },
                 "value_env": { "type": ["string", "null"], "pattern": "^[A-Z][A-Z0-9_]*$" },
                 "key": { "type": ["string", "null"] },
                 "url": { "type": ["string", "null"], "format": "uri" },
                 "required": { "type": "boolean" },
-                "capture_screenshot": { "type": "boolean" }
+                "capture_screenshot": { "type": "boolean" },
+                "checkpoint_id": { "type": ["string", "null"], "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+                "state_checkpoint": { "type": ["boolean", "null"] }
               }
             }
           },

package/schemas/browser-network-events.schema.json

@@ -0,0 +1,142 @@
+{
+  "$id": "citable://schemas/browser-network-events.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Browser network activity evidence artifact",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "plan_id",
+    "profile_id",
+    "collected_at",
+    "capture_policy",
+    "summary",
+    "events"
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "plan_id": { "type": "string" },
+    "profile_id": { "type": "string" },
+    "collected_at": { "type": "string", "format": "date-time" },
+    "capture_policy": { "type": "object" },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total_requests", "successful_responses", "failed_requests", "filtered_requests", "truncated", "status_codes"],
+      "properties": {
+        "total_requests": { "type": "integer", "minimum": 0 },
+        "successful_responses": { "type": "integer", "minimum": 0 },
+        "failed_requests": { "type": "integer", "minimum": 0 },
+        "filtered_requests": { "type": "integer", "minimum": 0 },
+        "in_flight_requests": { "type": "integer", "minimum": 0 },
+        "collector_status": { "enum": ["complete", "truncated", "failed"] },
+        "truncated": { "type": "boolean" },
+        "truncation_reason": { "type": ["string", "null"] },
+        "status_codes": {
+          "type": "object",
+          "additionalProperties": { "type": "integer" }
+        }
+      }
+    },
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "sequence",
+          "transaction_id",
+          "direction",
+          "phase",
+          "timing",
+          "correlation",
+          "request"
+        ],
+        "properties": {
+          "sequence": { "type": "integer", "minimum": 1 },
+          "transaction_id": { "type": "string" },
+          "direction": { "enum": ["request", "response"] },
+          "phase": { "enum": ["request_sent", "response_received", "failed", "redirect"] },
+          "timing": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["monotonic_offset_ms", "timestamp"],
+            "properties": {
+              "monotonic_offset_ms": { "type": "number", "minimum": 0 },
+              "timestamp": { "type": "string", "format": "date-time" }
+            }
+          },
+          "correlation": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["step_id", "step_sequence", "attribution_phase"],
+            "properties": {
+              "step_id": { "type": ["string", "null"] },
+              "step_sequence": { "type": ["integer", "null"] },
+              "checkpoint_id": { "type": ["string", "null"] },
+              "attribution_phase": { "enum": ["initial", "during_step", "between_steps", "post_journey", "ambiguous_async"] },
+              "initiated_step_id": { "type": ["string", "null"] },
+              "completed_step_id": { "type": ["string", "null"] },
+              "ambiguous_async": { "type": "boolean" }
+            }
+          },
+          "request": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["url", "method", "scheme", "host", "path", "resource_type"],
+            "properties": {
+              "url": { "type": "string" },
+              "method": { "type": "string" },
+              "scheme": { "type": "string" },
+              "host": { "type": "string" },
+              "path": { "type": "string" },
+              "resource_type": { "type": "string" },
+              "query": { "type": ["object", "null"] },
+              "query_status": { "enum": ["captured", "not_requested", "filtered", "none_present", "redacted"] },
+              "headers": { "type": ["object", "null"] },
+              "headers_status": { "enum": ["captured", "not_requested", "filtered", "redacted"] },
+              "payload_hash": { "type": ["string", "null"] },
+              "payload_bytes": { "type": ["integer", "null"] },
+              "payload_fields": { "type": ["object", "null"] },
+              "payload_status": { "enum": ["not_requested", "captured", "filtered", "truncated", "unavailable", "hash_only"] }
+            }
+          },
+          "response": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "properties": {
+              "status": { "type": "integer" },
+              "status_text": { "type": "string" },
+              "headers": { "type": ["object", "null"] },
+              "headers_status": { "enum": ["captured", "not_requested", "filtered", "redacted"] },
+              "mime_type": { "type": ["string", "null"] },
+              "body_hash": { "type": ["string", "null"] },
+              "body_bytes": { "type": ["integer", "null"] },
+              "body_fields": { "type": ["object", "null"] },
+              "body_status": { "enum": ["not_requested", "captured", "filtered", "truncated", "unavailable", "hash_only"] },
+              "redirect_url": { "type": ["string", "null"] },
+              "from_cache": { "type": "boolean" }
+            }
+          },
+          "failure": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "properties": {
+              "error_text": { "type": "string" }
+            }
+          },
+          "disposition": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["capture_status", "redacted_count", "filtered_fields"],
+            "properties": {
+              "capture_status": { "enum": ["captured", "filtered", "redacted", "truncated", "error"] },
+              "redacted_count": { "type": "integer", "minimum": 0 },
+              "filtered_fields": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    }
+  }
+}