@nebulacomponents/citable 1.18.2 → 1.20.0

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

@@ -0,0 +1,112 @@
+{
+  "$id": "citable://schemas/browser-runtime-events.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Browser runtime events 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_events", "by_source", "by_event_name", "truncated"],
+      "properties": {
+        "total_events": { "type": "integer", "minimum": 0 },
+        "filtered_events": { "type": "integer", "minimum": 0 },
+        "collector_status": { "enum": ["complete", "truncated", "failed"] },
+        "by_source": {
+          "type": "object",
+          "additionalProperties": { "type": "integer" }
+        },
+        "by_event_name": {
+          "type": "object",
+          "additionalProperties": { "type": "integer" }
+        },
+        "truncated": { "type": "boolean" },
+        "truncation_reason": { "type": ["string", "null"] },
+        "collector_health": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "status": { "type": "string" },
+            "queue_replaced": { "type": "boolean" },
+            "push_replaced": { "type": "boolean" },
+            "polling_fallback_used": { "type": "boolean" },
+            "supported_contexts": { "type": "array", "items": { "type": "string" } },
+            "unsupported_contexts": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "sequence",
+          "source_id",
+          "event_name",
+          "timing",
+          "correlation",
+          "payload"
+        ],
+        "properties": {
+          "sequence": { "type": "integer", "minimum": 1 },
+          "source_id": { "type": "string" },
+          "event_name": { "type": "string" },
+          "occurrence_index": { "type": "integer", "minimum": 1 },
+          "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" }
+            }
+          },
+          "payload": {
+            "type": "object"
+          },
+          "disposition": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["capture_status", "redacted_count", "filtered_fields"],
+            "properties": {
+              "capture_status": { "enum": ["captured", "filtered", "redacted", "truncated"] },
+              "redacted_count": { "type": "integer", "minimum": 0 },
+              "filtered_fields": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/browser-state-observations.schema.json

@@ -0,0 +1,97 @@
+{
+  "$id": "citable://schemas/browser-state-observations.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Browser state observations evidence artifact",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "plan_id",
+    "profile_id",
+    "collected_at",
+    "capture_policy",
+    "summary",
+    "checkpoints"
+  ],
+  "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_checkpoints", "total_observations", "truncated"],
+      "properties": {
+        "total_checkpoints": { "type": "integer", "minimum": 0 },
+        "total_observations": { "type": "integer", "minimum": 0 },
+        "collector_status": { "enum": ["complete", "truncated", "failed"] },
+        "truncated": { "type": "boolean" },
+        "truncation_reason": { "type": ["string", "null"] }
+      }
+    },
+    "checkpoints": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "checkpoint_id",
+          "sequence",
+          "timing",
+          "correlation",
+          "state"
+        ],
+        "properties": {
+          "checkpoint_id": { "type": "string" },
+          "sequence": { "type": "integer", "minimum": 1 },
+          "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"],
+            "properties": {
+              "step_id": { "type": ["string", "null"] },
+              "step_sequence": { "type": ["integer", "null"] }
+            }
+          },
+          "state": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["url"],
+            "properties": {
+              "url": { "type": "string" },
+              "query_params": { "type": ["object", "null"] },
+              "referrer": { "type": ["string", "null"] },
+              "navigation_type": { "type": ["string", "null"] },
+              "cookies": { "type": ["object", "null"] },
+              "local_storage": { "type": ["object", "null"] },
+              "session_storage": { "type": ["object", "null"] },
+              "globals": { "type": ["object", "null"] },
+              "dom_queries": { "type": ["object", "null"] }
+            }
+          },
+          "disposition": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["observation_status", "redacted_count", "unavailable_items"],
+            "properties": {
+              "observation_status": { "enum": ["observed", "partially_observed", "truncated", "unavailable"] },
+              "redacted_count": { "type": "integer", "minimum": 0 },
+              "unavailable_items": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/collection-result.schema.json

@@ -0,0 +1,35 @@
+{
+  "$id": "citable://schemas/collection-result.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Collection result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "items",
+    "pagination_state",
+    "provider_reported_total",
+    "retrieved_total",
+    "coverage_status",
+    "continuation_state",
+    "limitations",
+    "errors"
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "items": {
+      "type": "array",
+      "items": {}
+    },
+    "pagination_state": { "type": "object" },
+    "provider_reported_total": { "type": ["integer", "null"], "minimum": 0 },
+    "retrieved_total": { "type": "integer", "minimum": 0 },
+    "coverage_status": {
+      "type": "string",
+      "enum": ["complete", "truncated", "indeterminate", "provider_bounded"]
+    },
+    "continuation_state": { "type": ["object", "null"] },
+    "limitations": { "type": "array", "items": { "type": "string" } },
+    "errors": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/config.schema.json

@@ -30,6 +30,8 @@
       "type": "object",
       "properties": {
         "index_target_default": { "type": "boolean" },
+        "max_pages": { "type": "integer", "minimum": 1, "maximum": 10000 },
+        "time_budget_seconds": { "type": "integer", "minimum": 1, "maximum": 86400 },
         "max_crawl_depth": { "type": "integer", "minimum": 1 },
         "thin_content_words": { "type": "integer", "minimum": 1 },
         "fetch_external": { "type": "boolean" },

package/schemas/cro-report.schema.json

@@ -103,7 +103,14 @@
         "source_identifier": { "type": ["string", "null"] },
         "source_findings_count": { "type": "integer", "minimum": 0 },
         "integrity_hash": { "type": ["string", "null"] },
-        "synthetic_evidence": { "type": "boolean" }
+        "synthetic_evidence": { "type": "boolean" },
+        "package_verified": { "type": "boolean" },
+        "integrity_mode": { "type": "string" },
+        "legacy": { "type": "boolean" },
+        "coverage_status": { "type": "string" },
+        "determination_status": { "type": "string" },
+        "evaluated": { "type": ["integer", "null"], "minimum": 0 },
+        "eligible": { "type": ["integer", "null"], "minimum": 0 }
       },
       "additionalProperties": false
     }

package/schemas/finding.schema.json

@@ -17,12 +17,19 @@
     "status"
   ],
   "properties": {
+    "schema_version": {
+      "type": "integer",
+      "enum": [1, 2]
+    },
     "finding_id": {
       "$ref": "citable://schemas/common.defs.json#/definitions/id"
     },
     "detector_id": {
       "$ref": "citable://schemas/common.defs.json#/definitions/id"
     },
+    "detector_name": {
+      "type": "string"
+    },
     "run_id": {
       "type": "string"
     },
@@ -84,6 +91,15 @@
         },
         "rendered_selector": {
           "type": "string"
+        },
+        "resource_id": {
+          "type": "string"
+        },
+        "url_identity": {
+          "type": "object"
+        },
+        "evidence_identity": {
+          "$ref": "#/definitions/evidenceIdentity"
         }
       }
     },
@@ -106,7 +122,10 @@
           }
         },
         "captured_value": {},
-        "expected_value": {}
+        "expected_value": {},
+        "evidence_identity": {
+          "$ref": "#/definitions/evidenceIdentity"
+        }
       }
     },
     "classification": {
@@ -326,6 +345,42 @@
         }
       }
     },
+    "evidence_scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "requirement",
+        "satisfaction",
+        "resource_ids",
+        "coverage_ref"
+      ],
+      "properties": {
+        "requirement": {
+          "type": "string",
+          "minLength": 1
+        },
+        "satisfaction": {
+          "type": "string",
+          "enum": [
+            "supported",
+            "qualified",
+            "indeterminate",
+            "not_applicable"
+          ]
+        },
+        "resource_ids": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string"
+          }
+        },
+        "coverage_ref": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
     "status": {
       "type": "object",
       "required": [
@@ -358,7 +413,55 @@
       }
     }
   },
+  "allOf": [
+    {
+      "if": {
+        "required": ["schema_version"],
+        "properties": {
+          "schema_version": {
+            "const": 2
+          }
+        }
+      },
+      "then": {
+        "required": ["evidence_scope"],
+        "propertyNames": {
+          "enum": [
+            "schema_version",
+            "finding_id",
+            "detector_id",
+            "detector_name",
+            "run_id",
+            "timestamp",
+            "discipline",
+            "subject",
+            "observation",
+            "classification",
+            "reasoning",
+            "remediation",
+            "verification",
+            "provenance",
+            "evidence_scope",
+            "status"
+          ]
+        }
+      }
+    }
+  ],
   "definitions": {
+    "evidenceIdentity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["hash_schema_version", "representation", "hash"],
+      "properties": {
+        "hash_schema_version": { "type": "string", "minLength": 1 },
+        "representation": {
+          "type": "string",
+          "enum": ["response_body", "rendered_dom", "extracted_text", "structured_data", "evidence", "artifact"]
+        },
+        "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
     "impactLevel": {
       "type": "string",
       "enum": [
@@ -370,4 +473,4 @@
       ]
     }
   }
-}
+}

package/schemas/remediation-verification.schema.json

@@ -12,7 +12,7 @@
   "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"] },
+    "status": { "type": "string", "enum": ["verified", "not_resolved", "not_reobserved", "not_comparable", "indeterminate", "blocked", "patch_refused"] },
     "tool_version": { "type": "string" },
     "repository_commit": { "type": ["string", "null"] },
     "source_run_id": { "type": ["string", "null"], "minLength": 1 },
@@ -30,6 +30,7 @@
       "required": ["resolved"],
       "properties": {
         "resolved": { "type": "boolean" },
+        "comparison_state": { "type": "string", "enum": ["persisted", "resolved", "new", "changed", "not_comparable", "not_reobserved", "indeterminate"] },
         "before_finding_ids": { "type": "array", "items": { "type": "string" } },
         "after_finding_ids": { "type": "array", "items": { "type": "string" } },
         "new_regressions": {
@@ -51,6 +52,16 @@
         }
       }
     },
+    "comparison": {
+      "type": "object",
+      "required": ["state", "reason", "coverage_status"],
+      "properties": {
+        "state": { "type": "string", "enum": ["resolved", "not_reobserved", "not_comparable", "indeterminate"] },
+        "reason": { "type": "string" },
+        "coverage_status": { "type": "string" },
+        "resource": { "type": ["string", "null"] }
+      }
+    },
     "patch": {
       "type": ["object", "null"],
       "properties": {

package/schemas/run.schema.json

@@ -5,6 +5,7 @@
   "type": "object",
   "required": ["run_id", "command", "tool_version", "skill_version", "timestamp", "target", "status"],
   "properties": {
+    "schema_version": { "type": "integer", "enum": [1, 2] },
     "run_id": { "type": "string" },
     "command": { "type": "string" },
     "argv": { "type": "array", "items": { "type": "string" } },
@@ -31,6 +32,18 @@
     "incomplete_checks": { "type": "array", "items": { "type": "string" } },
     "errors": { "type": "array", "items": { "type": "string" } },
     "warnings": { "type": "array", "items": { "type": "string" } },
-    "status": { "type": "string", "enum": ["completed", "completed_with_warnings", "incomplete", "failed"] }
-  }
+    "status": { "type": "string", "enum": ["completed", "completed_with_warnings", "incomplete", "failed"] },
+    "execution_status": { "type": "string", "enum": ["completed", "completed_with_warnings", "failed"] },
+    "coverage_status": { "type": "string", "enum": ["complete", "truncated", "indeterminate", "not_applicable"] },
+    "determination_status": { "type": "string", "enum": ["supported", "qualified", "indeterminate", "not_applicable"] }
+  },
+  "allOf": [
+    {
+      "if": {
+        "required": ["schema_version"],
+        "properties": { "schema_version": { "const": 2 } }
+      },
+      "then": { "required": ["execution_status", "coverage_status", "determination_status"] }
+    }
+  ]
 }

package/schemas/search-report.schema.json

@@ -90,7 +90,14 @@
         "source_identifier": { "type": ["string", "null"] },
         "source_findings_count": { "type": "integer", "minimum": 0 },
         "integrity_hash": { "type": ["string", "null"] },
-        "synthetic_evidence": { "type": "boolean" }
+        "synthetic_evidence": { "type": "boolean" },
+        "package_verified": { "type": "boolean" },
+        "integrity_mode": { "type": "string" },
+        "legacy": { "type": "boolean" },
+        "coverage_status": { "type": "string" },
+        "determination_status": { "type": "string" },
+        "evaluated": { "type": ["integer", "null"], "minimum": 0 },
+        "eligible": { "type": ["integer", "null"], "minimum": 0 }
       },
       "additionalProperties": false
     }

package/schemas/summary.schema.json

@@ -0,0 +1,41 @@
+{
+  "$id": "citable://schemas/summary.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Run summary",
+  "type": "object",
+  "required": ["coverage", "posture"],
+  "properties": {
+    "coverage": {
+      "type": ["object", "null"],
+      "required": ["status", "populations", "stop_reason"],
+      "properties": {
+        "status": { "enum": ["complete", "truncated", "indeterminate", "not_applicable"] },
+        "populations": { "$ref": "citable://schemas/audit-coverage.schema.json#/properties/populations" },
+        "stop_reason": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "posture": {
+      "type": "object",
+      "required": ["retrieval_eligibility", "source_extraction_and_support", "observed_citation_behavior"],
+      "properties": {
+        "retrieval_eligibility": { "$ref": "#/definitions/posture" },
+        "source_extraction_and_support": { "$ref": "#/definitions/posture" },
+        "observed_citation_behavior": { "$ref": "#/definitions/posture" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "posture": {
+      "type": "object",
+      "required": ["result"],
+      "properties": {
+        "result": { "type": "string" },
+        "coverage_status": { "enum": ["complete", "truncated", "indeterminate", "not_applicable"] }
+      },
+      "additionalProperties": true
+    }
+  }
+}

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.18.2
+version: 1.20.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -69,6 +69,15 @@ Every report must keep these top-level states separate:
 3. **Observed citation behavior** — only controlled, timestamped provider
    observations; absent observations are `not_evidenced`, never inferred.
 
+Presentation language must preserve those boundaries. An empty finding list,
+legacy package, unverified artifact, incomplete crawl, or indeterminate
+determination must not be described as `clean`, `complete`, `verified`,
+`resolved`, `100%`, or `site-wide`. State the evaluated population and the
+limitation instead (for example, "No findings were produced for the 217
+successfully evaluated resources; corpus-wide absence is not established").
+Positive local observations may remain supported, but they must not be widened
+to pages or resources that were not observed.
+
 Within retrieval, distinguish `allowed_by_policy`, `synthetic_fetch_succeeded`,
 `observed_in_production_logs`, `indexed`, and `returned_by_retrieval`. Within
 citation testing, distinguish mention, citation, material support, canonical
@@ -86,7 +95,7 @@ prefer running it over re-deriving its checks by hand:
 
 ```
 citable init                        # initialize .citable/ (non-destructive)
-citable audit [scope] --target <dir|url> [--base-url <url>] [--ref-date YYYY-MM-DD]
+citable audit [scope] --target <dir|url> [--base-url <url>] [--max-pages <1..10000>] [--time-budget-seconds <1..86400>] [--ref-date YYYY-MM-DD]
 citable plan-audit --target <dir|url> [--base-url <url>]
 citable sweep technical --target <dir|url> # Technical SEO sweep + Core Web Vitals metrics
 citable inspect <page> --target <dir|url>

package/src/acceptance/reproducibility.js

@@ -1,8 +1,8 @@
-import fs from 'node:fs';
 import path from 'node:path';
 import { canonicalJson } from '../release/governance.js';
-import { nowIso, readJson, sha256, sha256File, writeJson } from '../shared/io.js';
+import { nowIso, readJson, sha256, writeJson } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 
 const INCLUDED_FIELDS = [
   'property.target', 'property.source_commit', 'property.content_hashes',
@@ -37,25 +37,6 @@ function normalizedArguments(argv = []) {
   return normalized;
 }
 
-function verifyRunPackage(runDir, manifest) {
-  const manifestCheck = validateAgainst('run.schema.json', manifest);
-  if (!manifestCheck.valid) throw new Error(`run manifest violates contract: ${manifestCheck.errors.join('; ')}`);
-  const checksumsFile = path.join(runDir, 'checksums.json');
-  if (!fs.existsSync(checksumsFile)) throw new Error(`run ${manifest.run_id} has no checksums.json`);
-  const checksums = readJson(checksumsFile);
-  if (!checksums || Array.isArray(checksums) || typeof checksums !== 'object') throw new Error('run checksums must be an object');
-  const failures = [];
-  for (const [relative, expected] of Object.entries(checksums)) {
-    const file = path.resolve(runDir, relative);
-    if (path.isAbsolute(relative) || (!file.startsWith(`${path.resolve(runDir)}${path.sep}`))) failures.push(`${relative} escapes the run package`);
-    else if (!/^[a-f0-9]{64}$/.test(expected)) failures.push(`${relative} has an invalid checksum`);
-    else if (!fs.existsSync(file)) failures.push(`${relative} is missing`);
-    else if (sha256File(file) !== expected) failures.push(`${relative} checksum differs`);
-  }
-  if (failures.length) throw new Error(`run package integrity failed: ${failures.join('; ')}`);
-  return checksums;
-}
-
 function fingerprintPayload(receipt) {
   return {
     property: { target: receipt.property.target, source_commit: receipt.property.source_commit, content_hashes: receipt.property.content_hashes },
@@ -74,11 +55,10 @@ export function createAcceptanceReceipt(root, { runId, context = {}, createdAt =
   const contextCheck = validateAgainst('acceptance-run-context.schema.json', context);
   if (!contextCheck.valid) throw new Error(`acceptance context violates contract: ${contextCheck.errors.join('; ')}`);
   const runDir = path.join(root, '.citable', 'runs', runId);
-  const manifestFile = path.join(runDir, 'manifest.json');
-  if (!fs.existsSync(manifestFile)) throw new Error(`run ${runId} not found`);
-  const manifest = readJson(manifestFile);
+  const verified = loadVerifiedRun(runDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+  const manifest = verified.manifest;
   if (manifest.run_id !== runId) throw new Error(`run manifest id ${manifest.run_id} does not match requested run ${runId}`);
-  const checksums = verifyRunPackage(runDir, manifest);
+  const checksums = verified.artifactHashes;
   const canonicalArtifacts = sortedObject(Object.fromEntries(
     Object.entries(checksums).filter(([name]) => name !== 'manifest.json'),
   ));

package/src/analysis/croRoadmap.js

@@ -18,10 +18,10 @@ export function buildCroRoadmap({ findings = [], targetDomain = 'example.com', d
       'Mobile Tap Sizing: Expand diminutive mobile CTA touch targets to >= 48px standard (CRO-015)',
     ],
     target_outcomes: [
-      '100% conversion funnel continuity intact across all declared paths',
+      'Conversion funnel continuity observed across the declared paths in scope',
       'Keystroke Effort Index: Form completion friction reduced by >= 40%',
-      'Above-the-fold information scent match verified across all primary landing pages',
-      'Zero mobile touch target defects under 48px',
+      'Above-the-fold information scent match observed on evaluated primary landing pages',
+      'No mobile touch-target findings in the evaluated pages',
     ],
     measurable_conversion_kpi: 'Form Completion Rate (+8% to +15% expected relative lift)',
     experiments: backlog.experiments.filter((e) => ['CRO-007', 'CRO-005', 'CRO-015', 'CRO-017', 'CRO-018'].includes(e.detector_id) || e.ice_prioritization.effort <= 3),