@nebulacomponents/citable 1.6.0 → 1.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +17 -0
- package/README.md +11 -6
- package/dist/universal/.agents/skills/citable/SKILL.md +12 -2
- package/dist/universal/.agents/skills/citable/VERSION +1 -1
- package/dist/universal/.agents/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.agents/skills/citable/manifest.json +11 -7
- package/dist/universal/.agents/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.agents/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.agents/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.agents/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.agents/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/.claude/skills/citable/SKILL.md +12 -2
- package/dist/universal/.claude/skills/citable/VERSION +1 -1
- package/dist/universal/.claude/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.claude/skills/citable/manifest.json +11 -7
- package/dist/universal/.claude/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.claude/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.claude/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.claude/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.claude/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/.cursor/skills/citable/SKILL.md +12 -2
- package/dist/universal/.cursor/skills/citable/VERSION +1 -1
- package/dist/universal/.cursor/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.cursor/skills/citable/manifest.json +11 -7
- package/dist/universal/.cursor/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.cursor/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.cursor/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.cursor/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.cursor/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/.gemini/skills/citable/SKILL.md +12 -2
- package/dist/universal/.gemini/skills/citable/VERSION +1 -1
- package/dist/universal/.gemini/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.gemini/skills/citable/manifest.json +11 -7
- package/dist/universal/.gemini/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.gemini/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.gemini/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.gemini/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.gemini/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/.github/skills/citable/SKILL.md +12 -2
- package/dist/universal/.github/skills/citable/VERSION +1 -1
- package/dist/universal/.github/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.github/skills/citable/manifest.json +11 -7
- package/dist/universal/.github/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.github/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.github/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.github/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.github/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/.kiro/skills/citable/SKILL.md +12 -2
- package/dist/universal/.kiro/skills/citable/VERSION +1 -1
- package/dist/universal/.kiro/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.kiro/skills/citable/manifest.json +11 -7
- package/dist/universal/.kiro/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.kiro/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.kiro/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.kiro/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.kiro/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/.opencode/skills/citable/SKILL.md +12 -2
- package/dist/universal/.opencode/skills/citable/VERSION +1 -1
- package/dist/universal/.opencode/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.opencode/skills/citable/manifest.json +11 -7
- package/dist/universal/.opencode/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.opencode/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.opencode/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.opencode/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.opencode/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/.pi/agent/skills/citable/SKILL.md +12 -2
- package/dist/universal/.pi/agent/skills/citable/VERSION +1 -1
- package/dist/universal/.pi/agent/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.pi/agent/skills/citable/manifest.json +11 -7
- package/dist/universal/.pi/agent/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.pi/agent/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.pi/agent/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.pi/agent/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.pi/agent/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/.qoder/skills/citable/SKILL.md +12 -2
- package/dist/universal/.qoder/skills/citable/VERSION +1 -1
- package/dist/universal/.qoder/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.qoder/skills/citable/manifest.json +11 -7
- package/dist/universal/.qoder/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.qoder/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.qoder/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.qoder/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.qoder/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/.rovodev/skills/citable/SKILL.md +12 -2
- package/dist/universal/.rovodev/skills/citable/VERSION +1 -1
- package/dist/universal/.rovodev/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.rovodev/skills/citable/manifest.json +11 -7
- package/dist/universal/.rovodev/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.rovodev/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.rovodev/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.rovodev/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.rovodev/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/.trae/skills/citable/SKILL.md +12 -2
- package/dist/universal/.trae/skills/citable/VERSION +1 -1
- package/dist/universal/.trae/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.trae/skills/citable/manifest.json +11 -7
- package/dist/universal/.trae/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.trae/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.trae/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.trae/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.trae/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/.trae-cn/skills/citable/SKILL.md +12 -2
- package/dist/universal/.trae-cn/skills/citable/VERSION +1 -1
- package/dist/universal/.trae-cn/skills/citable/commands/measurement.md +15 -0
- package/dist/universal/.trae-cn/skills/citable/manifest.json +11 -7
- package/dist/universal/.trae-cn/skills/citable/references/evidence-authority.md +43 -0
- package/dist/universal/.trae-cn/skills/citable/schemas/bing-webmaster.schema.json +25 -0
- package/dist/universal/.trae-cn/skills/citable/schemas/crawler-identity.schema.json +42 -0
- package/dist/universal/.trae-cn/skills/citable/schemas/evidence-authority.schema.json +15 -0
- package/dist/universal/.trae-cn/skills/citable/schemas/observation.schema.json +3 -2
- package/dist/universal/manifest.json +135 -87
- package/package.json +1 -1
- package/schemas/bing-webmaster.schema.json +25 -0
- package/schemas/crawler-identity.schema.json +42 -0
- package/schemas/evidence-authority.schema.json +15 -0
- package/schemas/observation.schema.json +3 -2
- package/skill/SKILL.md +12 -2
- package/skill/commands/measurement.md +15 -0
- package/skill/references/evidence-authority.md +43 -0
- package/src/cli/index.js +3 -1
- package/src/commands/observe.js +81 -22
- package/src/observations/authority.js +13 -0
- package/src/observations/common.js +3 -1
- package/src/observations/crawlerIdentity.js +60 -0
|
@@ -1 +1 @@
|
|
|
1
|
-
1.
|
|
1
|
+
1.7.0
|
|
@@ -70,6 +70,21 @@ agent × URL × status; flag 403/429/5xx concentrations against declared-allow
|
|
|
70
70
|
crawlers; note that user-agent strings are spoofable and IP validation is the
|
|
71
71
|
confirmation step (crawler registry ip_validation_method). Compare observed
|
|
72
72
|
access against `crawlers.yaml` decisions (CRAWL-001 logic applied to logs).
|
|
73
|
+
Normalize JSON or CSV edge/origin events into the crawler identity contract.
|
|
74
|
+
Do not label CIDR membership alone verified: preserve range-source provenance,
|
|
75
|
+
DNS, edge, origin, region, collector, stages, and contradiction state.
|
|
76
|
+
Remove credentials, cookies, secrets, and unnecessary personal data before
|
|
77
|
+
import. Citable rejects common sensitive field names but cannot establish that
|
|
78
|
+
arbitrary URL or query values are lawful or appropriately minimized.
|
|
79
|
+
|
|
80
|
+
# Bing owner observations
|
|
81
|
+
|
|
82
|
+
Use `citable observe bing --dataset search_performance|ai_performance --input
|
|
83
|
+
<csv|json>`. This release normalizes owner exports because no supported Bing AI
|
|
84
|
+
Performance API contract has been captured. Citation counts do not indicate
|
|
85
|
+
ranking, authority, placement, page importance, or material support. Grounding
|
|
86
|
+
queries may be sampled. Preserve traffic-source dimensions and never infer
|
|
87
|
+
causation from a temporal change.
|
|
73
88
|
|
|
74
89
|
# monitor-contradictions
|
|
75
90
|
Compare approved entity + claim records against: owned pages (automated, via
|
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "citable",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.7.0",
|
|
4
4
|
"managedBy": "citable-cli",
|
|
5
5
|
"provider": "qoder",
|
|
6
6
|
"providerName": "Qoder",
|
|
7
7
|
"scope": "bundle",
|
|
8
|
-
"sourcePackage": "@nebulacomponents/citable@1.
|
|
8
|
+
"sourcePackage": "@nebulacomponents/citable@1.7.0",
|
|
9
9
|
"variantPath": ".qoder/skills/citable",
|
|
10
10
|
"files": {
|
|
11
11
|
"commands/action-findings.md": "sha256:510361461f24fcd4a550e0a8d960c383aefe23f9a65a54a3ffc44abd4c1293e7",
|
|
12
12
|
"commands/ingest.md": "sha256:cf35659aecd9d0e160909003efdbe056864fc5d824c71b4ef0ee801ce07ff598",
|
|
13
|
-
"commands/measurement.md": "sha256:
|
|
13
|
+
"commands/measurement.md": "sha256:9cade6dfec23338e18aa67ede3335ac9e2888dc577a7d4d8e3ceac948bce403f",
|
|
14
14
|
"commands/observe-and-act.md": "sha256:02a93bbbfddc3d8e11cb921ddccd19b0666133c4bdb4f4a280bcb131bed37e8c",
|
|
15
15
|
"commands/optimize-page.md": "sha256:35866f3d7cdeef0376ea7a7d7036085a9b9cf95bbb300ecf4bd77610ebd74d85",
|
|
16
16
|
"commands/page-work.md": "sha256:965a66e59bdf7b0da482d26fade53b3d265885ece5d463fe83b0789ebefaef3e",
|
|
@@ -20,6 +20,7 @@
|
|
|
20
20
|
"references/aeo-geo-validation.md": "sha256:e45828d3ccca54a08513cb4235578c8a8ecf1dc47d1cb98e4a497838103bef70",
|
|
21
21
|
"references/anti-patterns.md": "sha256:de63f8e646af0fbf479b45eb1d050ae62a8637acc320d21b87e4a083fd4c47e7",
|
|
22
22
|
"references/capability-boundaries.md": "sha256:0d66909025541c1b4b7f5532750fdbfaed9116fb7fc156a67f290024342e30e4",
|
|
23
|
+
"references/evidence-authority.md": "sha256:b81ee09953999f16b19dc0eaba6fffe794b58d152e2adbd95c3179730bc08ffc",
|
|
23
24
|
"rubrics/answer-extractability.md": "sha256:c8e741143c34e53afdb3dc7b6976ce7b4485dce13b12d14c193fccb17bacf1da",
|
|
24
25
|
"rubrics/claim-boundedness.md": "sha256:0bab1b85248c252b966175912ebfae13bf18aa7e41573f7466831ac78b5d3e27",
|
|
25
26
|
"rubrics/comparison-fairness.md": "sha256:7afc86903aa4a695060be7b6bca42ba505c106ea7cfa153344189afc5b78a5ba",
|
|
@@ -34,21 +35,24 @@
|
|
|
34
35
|
"rubrics/semantic-clarity.md": "sha256:66d9f4843a4a620ea8c00625c5e17c02baeaa373f2b445ce13de6f81d78ec7ba",
|
|
35
36
|
"rubrics/source-authority.md": "sha256:8dbfe46bdcd0b5351f038be503601268c7d0abb9bed83be9ca58bf54dec5a73b",
|
|
36
37
|
"schemas/action-plan.schema.json": "sha256:4b6c4c877840a065c7c0c0c7b52f696502bf3d4ca6d31179622fc364ea868d5e",
|
|
38
|
+
"schemas/bing-webmaster.schema.json": "sha256:8357c518a8cb4ccd1def2da38950fbba68270e2b1613ad522b50c568a3b8538f",
|
|
37
39
|
"schemas/claim.schema.json": "sha256:ce79ccbfa34ece9b7a309a6962522ea06a1f44c468b4c472b5c376554a788537",
|
|
38
40
|
"schemas/common.defs.json": "sha256:effdd812910d1c275c50520bb70d8aec085e53fa8cb68054dc58c04a5d4a66b3",
|
|
39
41
|
"schemas/competitor.schema.json": "sha256:2f6fd7e4543846bde56ff4dc62bb41fa366889787b794a7cdb0bff1a3392e591",
|
|
40
42
|
"schemas/config.schema.json": "sha256:a87f3bb0087de09035b9f2dafea66e32e4fcc2e3e329abcd0fd8a5ec33318f2a",
|
|
41
43
|
"schemas/connection.schema.json": "sha256:abcedde8d62d0c0663d4f959e06132a617908058ed965078965445ef3b108310",
|
|
44
|
+
"schemas/crawler-identity.schema.json": "sha256:e1e3e6da203a8bc49fba8f9bbde525368891db022d542fc615b677401825351d",
|
|
42
45
|
"schemas/crawler.schema.json": "sha256:1a113dfb80bc6cde904c3ea648c82ea1d88fe50f2c1a0e7175d44abba28ac64e",
|
|
43
46
|
"schemas/detector-quality.schema.json": "sha256:5e9e1ac80b1198a0ff8fa17b9f7a543d3ccf3ed3d60196152f6ff095cfdebccd",
|
|
44
47
|
"schemas/entity.schema.json": "sha256:78a08c35c8f4eb7a804ab46b61a238502f59621ac5218991e783251fbde61c4f",
|
|
48
|
+
"schemas/evidence-authority.schema.json": "sha256:4f8165a37304ebab019e1c2dfec13f1168ecf89ce9bec88f7dca9c8554e39ac0",
|
|
45
49
|
"schemas/evidence.schema.json": "sha256:76baec7ad7e89c6952473c01dacb9e3b26953c088331e6314d531ce620df9ec1",
|
|
46
50
|
"schemas/experiment.schema.json": "sha256:3cebebc5745a9eb359261408b0a0421b8370d2c94f8244ce939827cd9da41cb6",
|
|
47
51
|
"schemas/finding.schema.json": "sha256:85907cd04cd8d2fe24a1e618e0df7160f6d56aa1818db501f345aebce5eb5edb",
|
|
48
52
|
"schemas/intervention.schema.json": "sha256:fcf28e117b207e64ffc96088aa70a95370841a2a9fa43ecb1c82b34c2058a818",
|
|
49
53
|
"schemas/metric.schema.json": "sha256:2ada648e7274a8d78cc9d6e7ed616f91faa79cf9ed07613e2c1fc53b247aac8d",
|
|
50
54
|
"schemas/objective.schema.json": "sha256:94404dc95d04a6641ea7b9654317d0222793251ad44d3dfd2875738622a36025",
|
|
51
|
-
"schemas/observation.schema.json": "sha256:
|
|
55
|
+
"schemas/observation.schema.json": "sha256:bea8eb7ea74442a1be745aa40ff22d25dcd89a82fb0205dfc6c597da40831f64",
|
|
52
56
|
"schemas/page.schema.json": "sha256:627613c35f461177fa946df08edf66fbf6f6bbdfc57eef812572b3af796d5e07",
|
|
53
57
|
"schemas/project.schema.json": "sha256:ea48fdb6480f7047ba4594bd5908bc1f79c1ad6b9a2c204df900959b5f203dc6",
|
|
54
58
|
"schemas/prompt-result.schema.json": "sha256:b55be47d7d58d7b1dd8c3b1e849e24e55216212c592cde7eb836953379b85737",
|
|
@@ -57,9 +61,9 @@
|
|
|
57
61
|
"schemas/remediation-spec.schema.json": "sha256:6fe8cb773702862ba6d261198bb5cc2dca3eca0a2310a60ebddd04377654df8d",
|
|
58
62
|
"schemas/run.schema.json": "sha256:46c3178620f3a358d936d535aeadb83454b9b35b551e53e6615cc9862063dacb",
|
|
59
63
|
"scripts/README.md": "sha256:1c3e952950ef353849621b07c5f615bf7cd20cc5654da4635492a7bd6384e747",
|
|
60
|
-
"SKILL.md": "sha256:
|
|
64
|
+
"SKILL.md": "sha256:06849d7894538c05b8539d595f8ee8370999db397f7ed552a272f1e0846d3f2a",
|
|
61
65
|
"templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
|
|
62
|
-
"VERSION": "sha256:
|
|
66
|
+
"VERSION": "sha256:bb7320d831e7a151aa901c35e7326c752fa2ef5024f30768c42319b8bed171ed"
|
|
63
67
|
},
|
|
64
|
-
"treeHash": "sha256:
|
|
68
|
+
"treeHash": "sha256:62432b83fd45f3a8fddc60f5b1f273eebb8d6225ef10e1476ed32185edb760b9"
|
|
65
69
|
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Evidence authority and crawler identity
|
|
2
|
+
|
|
3
|
+
An evidence checksum establishes preservation only. It does not establish that
|
|
4
|
+
the source was authentic, the collection was complete, or the observation was
|
|
5
|
+
representative. Report four axes independently on every new observation:
|
|
6
|
+
|
|
7
|
+
1. `source_authority`: provider-published, standards-body, owner-controlled,
|
|
8
|
+
independently controlled, third-party commercial, synthetic, inferred, or
|
|
9
|
+
unknown.
|
|
10
|
+
2. `collection_authority`: direct API, production log, browser capture, owner
|
|
11
|
+
export, third-party export, manual entry, model-generated inference, static
|
|
12
|
+
analysis, or synthetic probe.
|
|
13
|
+
3. `authenticity_status`: cryptographically authenticated, provider-range
|
|
14
|
+
verified, owner-attested, transport-authenticated, checksum-protected only,
|
|
15
|
+
or unverified.
|
|
16
|
+
4. `representativeness`: production population, complete export,
|
|
17
|
+
statistically sampled, controlled experiment, convenience sample, single
|
|
18
|
+
observation, or unknown.
|
|
19
|
+
|
|
20
|
+
Never convert these axes into one authority score.
|
|
21
|
+
|
|
22
|
+
## Crawler identity
|
|
23
|
+
|
|
24
|
+
Contract support and verified observations are different outcomes. The
|
|
25
|
+
`crawler-identity` schema can exist without any production event satisfying it.
|
|
26
|
+
A user-agent match is `declared`. A synthetic request is
|
|
27
|
+
`synthetically_observed`. An observed IP in an imported range is only
|
|
28
|
+
`range_matched`.
|
|
29
|
+
|
|
30
|
+
`fully_verified` requires all of:
|
|
31
|
+
|
|
32
|
+
- a provider and declared user agent;
|
|
33
|
+
- observed source IP matching the captured CIDR set;
|
|
34
|
+
- provider-published range source URL, retrieval time, captured source snapshot,
|
|
35
|
+
and valid snapshot checksum;
|
|
36
|
+
- documented forward/reverse DNS verification where applicable;
|
|
37
|
+
- an explicit edge observation and decision;
|
|
38
|
+
- a correlated origin observation and status;
|
|
39
|
+
- region and collector identity.
|
|
40
|
+
|
|
41
|
+
A failed range or DNS check, or a claimed verification without the required
|
|
42
|
+
chain, is `contradictory`. Missing links are `insufficient_evidence`. Verification
|
|
43
|
+
applies only to the captured event; it does not establish all crawler traffic.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$id": "citable://schemas/bing-webmaster.schema.json",
|
|
3
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
4
|
+
"title": "Normalized Bing Webmaster observation",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"additionalProperties": false,
|
|
7
|
+
"required": ["dataset", "date", "url", "metrics", "dimensions", "interpretation_boundary"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"dataset": { "type": "string", "enum": ["search_performance", "ai_performance"] },
|
|
10
|
+
"date": { "type": "string", "format": "date" },
|
|
11
|
+
"url": { "type": ["string", "null"], "format": "uri", "pattern": "^https?://" },
|
|
12
|
+
"metrics": { "type": "object", "additionalProperties": { "type": ["number", "null"] } },
|
|
13
|
+
"dimensions": {
|
|
14
|
+
"type": "object", "additionalProperties": false,
|
|
15
|
+
"properties": {
|
|
16
|
+
"query": { "type": ["string", "null"] },
|
|
17
|
+
"grounding_query": { "type": ["string", "null"] },
|
|
18
|
+
"source": { "type": ["string", "null"] },
|
|
19
|
+
"country": { "type": ["string", "null"] },
|
|
20
|
+
"device": { "type": ["string", "null"] }
|
|
21
|
+
}
|
|
22
|
+
},
|
|
23
|
+
"interpretation_boundary": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
|
|
24
|
+
}
|
|
25
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$id": "citable://schemas/crawler-identity.schema.json",
|
|
3
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
4
|
+
"title": "Crawler identity evidence contract",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"additionalProperties": false,
|
|
7
|
+
"required": ["provider", "declared_user_agent", "observed_source_ip", "range_source", "cidr_membership", "dns", "edge", "origin", "region", "collector", "stages", "verification_status"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"provider": { "type": "string", "minLength": 1 },
|
|
10
|
+
"declared_user_agent": { "type": "string", "minLength": 1 },
|
|
11
|
+
"observed_source_ip": { "type": ["string", "null"] },
|
|
12
|
+
"range_source": {
|
|
13
|
+
"type": "object", "additionalProperties": false,
|
|
14
|
+
"required": ["url", "retrieved_at", "authority", "checksum", "checksum_scope", "checksum_valid"],
|
|
15
|
+
"properties": {
|
|
16
|
+
"url": { "type": ["string", "null"], "format": "uri" },
|
|
17
|
+
"retrieved_at": { "type": ["string", "null"], "format": "date-time" },
|
|
18
|
+
"authority": { "type": "string", "enum": ["provider_published", "owner_controlled", "third_party", "unknown"] },
|
|
19
|
+
"checksum": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
|
|
20
|
+
"checksum_scope": { "type": "string", "enum": ["source_snapshot", "not_captured"] },
|
|
21
|
+
"checksum_valid": { "type": "boolean" }
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
"cidr_membership": { "type": "string", "enum": ["matched", "not_matched", "not_tested", "invalid"] },
|
|
25
|
+
"dns": {
|
|
26
|
+
"type": "object", "additionalProperties": false, "required": ["status", "method"],
|
|
27
|
+
"properties": { "status": { "type": "string", "enum": ["verified", "failed", "not_tested"] }, "method": { "type": ["string", "null"] } }
|
|
28
|
+
},
|
|
29
|
+
"edge": {
|
|
30
|
+
"type": "object", "additionalProperties": false, "required": ["observed", "decision"],
|
|
31
|
+
"properties": { "observed": { "type": "boolean" }, "decision": { "type": ["string", "null"] } }
|
|
32
|
+
},
|
|
33
|
+
"origin": {
|
|
34
|
+
"type": "object", "additionalProperties": false, "required": ["observed", "status"],
|
|
35
|
+
"properties": { "observed": { "type": "boolean" }, "status": { "type": ["integer", "null"], "minimum": 100, "maximum": 599 } }
|
|
36
|
+
},
|
|
37
|
+
"region": { "type": ["string", "null"] },
|
|
38
|
+
"collector": { "type": "string", "minLength": 1 },
|
|
39
|
+
"stages": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": ["declared", "synthetically_observed", "range_matched", "dns_verified", "edge_observed", "origin_observed", "fully_verified", "contradictory", "insufficient_evidence"] } },
|
|
40
|
+
"verification_status": { "type": "string", "enum": ["declared", "synthetically_observed", "range_matched", "dns_verified", "edge_observed", "origin_observed", "fully_verified", "contradictory", "insufficient_evidence"] }
|
|
41
|
+
}
|
|
42
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$id": "citable://schemas/evidence-authority.schema.json",
|
|
3
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
4
|
+
"title": "Multidimensional evidence authority",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"additionalProperties": false,
|
|
7
|
+
"required": ["source_authority", "collection_authority", "authenticity_status", "representativeness"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"source_authority": { "type": "string", "enum": ["provider_published", "standards_body", "owner_controlled", "independently_controlled", "third_party_commercial", "synthetic", "inferred", "unknown"] },
|
|
10
|
+
"collection_authority": { "type": "string", "enum": ["direct_api", "production_log", "browser_capture", "owner_export", "third_party_export", "manual_entry", "model_generated_inference", "static_analysis", "synthetic_probe"] },
|
|
11
|
+
"authenticity_status": { "type": "string", "enum": ["cryptographically_authenticated", "provider_range_verified", "owner_attested", "transport_authenticated", "checksum_protected_only", "unverified"] },
|
|
12
|
+
"representativeness": { "type": "string", "enum": ["production_population", "complete_export", "statistically_sampled", "controlled_experiment", "convenience_sample", "single_observation", "unknown"] },
|
|
13
|
+
"limitations": { "type": "array", "items": { "type": "string", "minLength": 1 } }
|
|
14
|
+
}
|
|
15
|
+
}
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
"required": ["observation_id", "kind", "state", "collected_at", "collection_method", "confidence", "source", "evidence_hash", "data"],
|
|
8
8
|
"properties": {
|
|
9
9
|
"observation_id": { "type": "string", "minLength": 1 },
|
|
10
|
-
"kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "passage", "canonical_freshness", "performance", "corroboration", "metric"] },
|
|
10
|
+
"kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric"] },
|
|
11
11
|
"state": { "type": "string", "enum": ["observed", "not_observed", "not_evidenced", "incomplete", "review_required", "failed"] },
|
|
12
12
|
"collected_at": { "type": "string", "format": "date-time" },
|
|
13
13
|
"collection_method": { "type": "string", "enum": ["live_api", "browser", "owner_import", "synthetic_fetch", "static_analysis", "human_review"] },
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
"source": { "type": "string", "minLength": 1 },
|
|
16
16
|
"evidence_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
|
|
17
17
|
"data": { "type": "object" },
|
|
18
|
-
"limitations": { "type": "array", "items": { "type": "string" } }
|
|
18
|
+
"limitations": { "type": "array", "items": { "type": "string" } },
|
|
19
|
+
"authority": { "$ref": "citable://schemas/evidence-authority.schema.json" }
|
|
19
20
|
}
|
|
20
21
|
}
|
|
@@ -7,12 +7,16 @@ description: >
|
|
|
7
7
|
generative engine optimization, structured data governance, claim substantiation,
|
|
8
8
|
crawler policy, entity consistency, content discoverability, or wants a site audited
|
|
9
9
|
for how search and AI systems will retrieve, understand, cite, or recommend it.
|
|
10
|
-
version: 1.
|
|
10
|
+
version: 1.7.0
|
|
11
11
|
---
|
|
12
12
|
|
|
13
|
-
# Citable — search
|
|
13
|
+
# Citable — evidence and change control for search and AI citation readiness
|
|
14
14
|
|
|
15
15
|
Citable is an operational quality and governance layer, not a content generator.
|
|
16
|
+
It records what a property makes technically available, what its content can
|
|
17
|
+
support, and what external systems have actually been observed doing. It does
|
|
18
|
+
not score visibility; it establishes what is eligible, supportable, observed,
|
|
19
|
+
changed, and still unknown.
|
|
16
20
|
It treats discoverability as an engineering system: registries as the source of
|
|
17
21
|
truth, deterministic detectors for observable conditions, rubrics for semantic
|
|
18
22
|
judgment, evidence packages for every run, and fail-closed behaviour wherever a
|
|
@@ -70,6 +74,11 @@ Within retrieval, distinguish `allowed_by_policy`, `synthetic_fetch_succeeded`,
|
|
|
70
74
|
citation testing, distinguish mention, citation, material support, canonical
|
|
71
75
|
source selection, and recommendation. These states are not interchangeable.
|
|
72
76
|
|
|
77
|
+
Evidence preservation, authority, authenticity, collection method, and
|
|
78
|
+
representativeness are also independent. Follow
|
|
79
|
+
`references/evidence-authority.md`; a checksum or CIDR match alone never proves
|
|
80
|
+
source authenticity, complete coverage, or verified crawler identity.
|
|
81
|
+
|
|
73
82
|
## Tooling
|
|
74
83
|
|
|
75
84
|
The `citable` CLI in this repository performs the deterministic work. Always
|
|
@@ -86,6 +95,7 @@ citable validate [registries|claims|evidence|schema|links]
|
|
|
86
95
|
citable compare-snapshots [runA runB]
|
|
87
96
|
citable action-plan [run-id] # ordered actions, blockers, semantic gates, verification
|
|
88
97
|
citable observe <mode> [options] # render/index/citation/log/passage/consensus/performance evidence
|
|
98
|
+
citable observe bing --dataset <search_performance|ai_performance> --input <csv|json>
|
|
89
99
|
citable apply --input <spec> [--write] # reviewed, hash-locked remediation; dry run by default
|
|
90
100
|
citable monitor [runA runB] # observation regression alerts
|
|
91
101
|
citable metrics import --provider <name> --input <csv|json>
|
|
@@ -1 +1 @@
|
|
|
1
|
-
1.
|
|
1
|
+
1.7.0
|
|
@@ -70,6 +70,21 @@ agent × URL × status; flag 403/429/5xx concentrations against declared-allow
|
|
|
70
70
|
crawlers; note that user-agent strings are spoofable and IP validation is the
|
|
71
71
|
confirmation step (crawler registry ip_validation_method). Compare observed
|
|
72
72
|
access against `crawlers.yaml` decisions (CRAWL-001 logic applied to logs).
|
|
73
|
+
Normalize JSON or CSV edge/origin events into the crawler identity contract.
|
|
74
|
+
Do not label CIDR membership alone verified: preserve range-source provenance,
|
|
75
|
+
DNS, edge, origin, region, collector, stages, and contradiction state.
|
|
76
|
+
Remove credentials, cookies, secrets, and unnecessary personal data before
|
|
77
|
+
import. Citable rejects common sensitive field names but cannot establish that
|
|
78
|
+
arbitrary URL or query values are lawful or appropriately minimized.
|
|
79
|
+
|
|
80
|
+
# Bing owner observations
|
|
81
|
+
|
|
82
|
+
Use `citable observe bing --dataset search_performance|ai_performance --input
|
|
83
|
+
<csv|json>`. This release normalizes owner exports because no supported Bing AI
|
|
84
|
+
Performance API contract has been captured. Citation counts do not indicate
|
|
85
|
+
ranking, authority, placement, page importance, or material support. Grounding
|
|
86
|
+
queries may be sampled. Preserve traffic-source dimensions and never infer
|
|
87
|
+
causation from a temporal change.
|
|
73
88
|
|
|
74
89
|
# monitor-contradictions
|
|
75
90
|
Compare approved entity + claim records against: owned pages (automated, via
|
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "citable",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.7.0",
|
|
4
4
|
"managedBy": "citable-cli",
|
|
5
5
|
"provider": "rovodev",
|
|
6
6
|
"providerName": "Rovo Dev",
|
|
7
7
|
"scope": "bundle",
|
|
8
|
-
"sourcePackage": "@nebulacomponents/citable@1.
|
|
8
|
+
"sourcePackage": "@nebulacomponents/citable@1.7.0",
|
|
9
9
|
"variantPath": ".rovodev/skills/citable",
|
|
10
10
|
"files": {
|
|
11
11
|
"commands/action-findings.md": "sha256:510361461f24fcd4a550e0a8d960c383aefe23f9a65a54a3ffc44abd4c1293e7",
|
|
12
12
|
"commands/ingest.md": "sha256:cf35659aecd9d0e160909003efdbe056864fc5d824c71b4ef0ee801ce07ff598",
|
|
13
|
-
"commands/measurement.md": "sha256:
|
|
13
|
+
"commands/measurement.md": "sha256:9cade6dfec23338e18aa67ede3335ac9e2888dc577a7d4d8e3ceac948bce403f",
|
|
14
14
|
"commands/observe-and-act.md": "sha256:02a93bbbfddc3d8e11cb921ddccd19b0666133c4bdb4f4a280bcb131bed37e8c",
|
|
15
15
|
"commands/optimize-page.md": "sha256:35866f3d7cdeef0376ea7a7d7036085a9b9cf95bbb300ecf4bd77610ebd74d85",
|
|
16
16
|
"commands/page-work.md": "sha256:965a66e59bdf7b0da482d26fade53b3d265885ece5d463fe83b0789ebefaef3e",
|
|
@@ -20,6 +20,7 @@
|
|
|
20
20
|
"references/aeo-geo-validation.md": "sha256:e45828d3ccca54a08513cb4235578c8a8ecf1dc47d1cb98e4a497838103bef70",
|
|
21
21
|
"references/anti-patterns.md": "sha256:de63f8e646af0fbf479b45eb1d050ae62a8637acc320d21b87e4a083fd4c47e7",
|
|
22
22
|
"references/capability-boundaries.md": "sha256:0d66909025541c1b4b7f5532750fdbfaed9116fb7fc156a67f290024342e30e4",
|
|
23
|
+
"references/evidence-authority.md": "sha256:b81ee09953999f16b19dc0eaba6fffe794b58d152e2adbd95c3179730bc08ffc",
|
|
23
24
|
"rubrics/answer-extractability.md": "sha256:c8e741143c34e53afdb3dc7b6976ce7b4485dce13b12d14c193fccb17bacf1da",
|
|
24
25
|
"rubrics/claim-boundedness.md": "sha256:0bab1b85248c252b966175912ebfae13bf18aa7e41573f7466831ac78b5d3e27",
|
|
25
26
|
"rubrics/comparison-fairness.md": "sha256:7afc86903aa4a695060be7b6bca42ba505c106ea7cfa153344189afc5b78a5ba",
|
|
@@ -34,21 +35,24 @@
|
|
|
34
35
|
"rubrics/semantic-clarity.md": "sha256:66d9f4843a4a620ea8c00625c5e17c02baeaa373f2b445ce13de6f81d78ec7ba",
|
|
35
36
|
"rubrics/source-authority.md": "sha256:8dbfe46bdcd0b5351f038be503601268c7d0abb9bed83be9ca58bf54dec5a73b",
|
|
36
37
|
"schemas/action-plan.schema.json": "sha256:4b6c4c877840a065c7c0c0c7b52f696502bf3d4ca6d31179622fc364ea868d5e",
|
|
38
|
+
"schemas/bing-webmaster.schema.json": "sha256:8357c518a8cb4ccd1def2da38950fbba68270e2b1613ad522b50c568a3b8538f",
|
|
37
39
|
"schemas/claim.schema.json": "sha256:ce79ccbfa34ece9b7a309a6962522ea06a1f44c468b4c472b5c376554a788537",
|
|
38
40
|
"schemas/common.defs.json": "sha256:effdd812910d1c275c50520bb70d8aec085e53fa8cb68054dc58c04a5d4a66b3",
|
|
39
41
|
"schemas/competitor.schema.json": "sha256:2f6fd7e4543846bde56ff4dc62bb41fa366889787b794a7cdb0bff1a3392e591",
|
|
40
42
|
"schemas/config.schema.json": "sha256:a87f3bb0087de09035b9f2dafea66e32e4fcc2e3e329abcd0fd8a5ec33318f2a",
|
|
41
43
|
"schemas/connection.schema.json": "sha256:abcedde8d62d0c0663d4f959e06132a617908058ed965078965445ef3b108310",
|
|
44
|
+
"schemas/crawler-identity.schema.json": "sha256:e1e3e6da203a8bc49fba8f9bbde525368891db022d542fc615b677401825351d",
|
|
42
45
|
"schemas/crawler.schema.json": "sha256:1a113dfb80bc6cde904c3ea648c82ea1d88fe50f2c1a0e7175d44abba28ac64e",
|
|
43
46
|
"schemas/detector-quality.schema.json": "sha256:5e9e1ac80b1198a0ff8fa17b9f7a543d3ccf3ed3d60196152f6ff095cfdebccd",
|
|
44
47
|
"schemas/entity.schema.json": "sha256:78a08c35c8f4eb7a804ab46b61a238502f59621ac5218991e783251fbde61c4f",
|
|
48
|
+
"schemas/evidence-authority.schema.json": "sha256:4f8165a37304ebab019e1c2dfec13f1168ecf89ce9bec88f7dca9c8554e39ac0",
|
|
45
49
|
"schemas/evidence.schema.json": "sha256:76baec7ad7e89c6952473c01dacb9e3b26953c088331e6314d531ce620df9ec1",
|
|
46
50
|
"schemas/experiment.schema.json": "sha256:3cebebc5745a9eb359261408b0a0421b8370d2c94f8244ce939827cd9da41cb6",
|
|
47
51
|
"schemas/finding.schema.json": "sha256:85907cd04cd8d2fe24a1e618e0df7160f6d56aa1818db501f345aebce5eb5edb",
|
|
48
52
|
"schemas/intervention.schema.json": "sha256:fcf28e117b207e64ffc96088aa70a95370841a2a9fa43ecb1c82b34c2058a818",
|
|
49
53
|
"schemas/metric.schema.json": "sha256:2ada648e7274a8d78cc9d6e7ed616f91faa79cf9ed07613e2c1fc53b247aac8d",
|
|
50
54
|
"schemas/objective.schema.json": "sha256:94404dc95d04a6641ea7b9654317d0222793251ad44d3dfd2875738622a36025",
|
|
51
|
-
"schemas/observation.schema.json": "sha256:
|
|
55
|
+
"schemas/observation.schema.json": "sha256:bea8eb7ea74442a1be745aa40ff22d25dcd89a82fb0205dfc6c597da40831f64",
|
|
52
56
|
"schemas/page.schema.json": "sha256:627613c35f461177fa946df08edf66fbf6f6bbdfc57eef812572b3af796d5e07",
|
|
53
57
|
"schemas/project.schema.json": "sha256:ea48fdb6480f7047ba4594bd5908bc1f79c1ad6b9a2c204df900959b5f203dc6",
|
|
54
58
|
"schemas/prompt-result.schema.json": "sha256:b55be47d7d58d7b1dd8c3b1e849e24e55216212c592cde7eb836953379b85737",
|
|
@@ -57,9 +61,9 @@
|
|
|
57
61
|
"schemas/remediation-spec.schema.json": "sha256:6fe8cb773702862ba6d261198bb5cc2dca3eca0a2310a60ebddd04377654df8d",
|
|
58
62
|
"schemas/run.schema.json": "sha256:46c3178620f3a358d936d535aeadb83454b9b35b551e53e6615cc9862063dacb",
|
|
59
63
|
"scripts/README.md": "sha256:1c3e952950ef353849621b07c5f615bf7cd20cc5654da4635492a7bd6384e747",
|
|
60
|
-
"SKILL.md": "sha256:
|
|
64
|
+
"SKILL.md": "sha256:06849d7894538c05b8539d595f8ee8370999db397f7ed552a272f1e0846d3f2a",
|
|
61
65
|
"templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
|
|
62
|
-
"VERSION": "sha256:
|
|
66
|
+
"VERSION": "sha256:bb7320d831e7a151aa901c35e7326c752fa2ef5024f30768c42319b8bed171ed"
|
|
63
67
|
},
|
|
64
|
-
"treeHash": "sha256:
|
|
68
|
+
"treeHash": "sha256:62432b83fd45f3a8fddc60f5b1f273eebb8d6225ef10e1476ed32185edb760b9"
|
|
65
69
|
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Evidence authority and crawler identity
|
|
2
|
+
|
|
3
|
+
An evidence checksum establishes preservation only. It does not establish that
|
|
4
|
+
the source was authentic, the collection was complete, or the observation was
|
|
5
|
+
representative. Report four axes independently on every new observation:
|
|
6
|
+
|
|
7
|
+
1. `source_authority`: provider-published, standards-body, owner-controlled,
|
|
8
|
+
independently controlled, third-party commercial, synthetic, inferred, or
|
|
9
|
+
unknown.
|
|
10
|
+
2. `collection_authority`: direct API, production log, browser capture, owner
|
|
11
|
+
export, third-party export, manual entry, model-generated inference, static
|
|
12
|
+
analysis, or synthetic probe.
|
|
13
|
+
3. `authenticity_status`: cryptographically authenticated, provider-range
|
|
14
|
+
verified, owner-attested, transport-authenticated, checksum-protected only,
|
|
15
|
+
or unverified.
|
|
16
|
+
4. `representativeness`: production population, complete export,
|
|
17
|
+
statistically sampled, controlled experiment, convenience sample, single
|
|
18
|
+
observation, or unknown.
|
|
19
|
+
|
|
20
|
+
Never convert these axes into one authority score.
|
|
21
|
+
|
|
22
|
+
## Crawler identity
|
|
23
|
+
|
|
24
|
+
Contract support and verified observations are different outcomes. The
|
|
25
|
+
`crawler-identity` schema can exist without any production event satisfying it.
|
|
26
|
+
A user-agent match is `declared`. A synthetic request is
|
|
27
|
+
`synthetically_observed`. An observed IP in an imported range is only
|
|
28
|
+
`range_matched`.
|
|
29
|
+
|
|
30
|
+
`fully_verified` requires all of:
|
|
31
|
+
|
|
32
|
+
- a provider and declared user agent;
|
|
33
|
+
- observed source IP matching the captured CIDR set;
|
|
34
|
+
- provider-published range source URL, retrieval time, captured source snapshot,
|
|
35
|
+
and valid snapshot checksum;
|
|
36
|
+
- documented forward/reverse DNS verification where applicable;
|
|
37
|
+
- an explicit edge observation and decision;
|
|
38
|
+
- a correlated origin observation and status;
|
|
39
|
+
- region and collector identity.
|
|
40
|
+
|
|
41
|
+
A failed range or DNS check, or a claimed verification without the required
|
|
42
|
+
chain, is `contradictory`. Missing links are `insufficient_evidence`. Verification
|
|
43
|
+
applies only to the captured event; it does not establish all crawler traffic.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$id": "citable://schemas/bing-webmaster.schema.json",
|
|
3
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
4
|
+
"title": "Normalized Bing Webmaster observation",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"additionalProperties": false,
|
|
7
|
+
"required": ["dataset", "date", "url", "metrics", "dimensions", "interpretation_boundary"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"dataset": { "type": "string", "enum": ["search_performance", "ai_performance"] },
|
|
10
|
+
"date": { "type": "string", "format": "date" },
|
|
11
|
+
"url": { "type": ["string", "null"], "format": "uri", "pattern": "^https?://" },
|
|
12
|
+
"metrics": { "type": "object", "additionalProperties": { "type": ["number", "null"] } },
|
|
13
|
+
"dimensions": {
|
|
14
|
+
"type": "object", "additionalProperties": false,
|
|
15
|
+
"properties": {
|
|
16
|
+
"query": { "type": ["string", "null"] },
|
|
17
|
+
"grounding_query": { "type": ["string", "null"] },
|
|
18
|
+
"source": { "type": ["string", "null"] },
|
|
19
|
+
"country": { "type": ["string", "null"] },
|
|
20
|
+
"device": { "type": ["string", "null"] }
|
|
21
|
+
}
|
|
22
|
+
},
|
|
23
|
+
"interpretation_boundary": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
|
|
24
|
+
}
|
|
25
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$id": "citable://schemas/crawler-identity.schema.json",
|
|
3
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
4
|
+
"title": "Crawler identity evidence contract",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"additionalProperties": false,
|
|
7
|
+
"required": ["provider", "declared_user_agent", "observed_source_ip", "range_source", "cidr_membership", "dns", "edge", "origin", "region", "collector", "stages", "verification_status"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"provider": { "type": "string", "minLength": 1 },
|
|
10
|
+
"declared_user_agent": { "type": "string", "minLength": 1 },
|
|
11
|
+
"observed_source_ip": { "type": ["string", "null"] },
|
|
12
|
+
"range_source": {
|
|
13
|
+
"type": "object", "additionalProperties": false,
|
|
14
|
+
"required": ["url", "retrieved_at", "authority", "checksum", "checksum_scope", "checksum_valid"],
|
|
15
|
+
"properties": {
|
|
16
|
+
"url": { "type": ["string", "null"], "format": "uri" },
|
|
17
|
+
"retrieved_at": { "type": ["string", "null"], "format": "date-time" },
|
|
18
|
+
"authority": { "type": "string", "enum": ["provider_published", "owner_controlled", "third_party", "unknown"] },
|
|
19
|
+
"checksum": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
|
|
20
|
+
"checksum_scope": { "type": "string", "enum": ["source_snapshot", "not_captured"] },
|
|
21
|
+
"checksum_valid": { "type": "boolean" }
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
"cidr_membership": { "type": "string", "enum": ["matched", "not_matched", "not_tested", "invalid"] },
|
|
25
|
+
"dns": {
|
|
26
|
+
"type": "object", "additionalProperties": false, "required": ["status", "method"],
|
|
27
|
+
"properties": { "status": { "type": "string", "enum": ["verified", "failed", "not_tested"] }, "method": { "type": ["string", "null"] } }
|
|
28
|
+
},
|
|
29
|
+
"edge": {
|
|
30
|
+
"type": "object", "additionalProperties": false, "required": ["observed", "decision"],
|
|
31
|
+
"properties": { "observed": { "type": "boolean" }, "decision": { "type": ["string", "null"] } }
|
|
32
|
+
},
|
|
33
|
+
"origin": {
|
|
34
|
+
"type": "object", "additionalProperties": false, "required": ["observed", "status"],
|
|
35
|
+
"properties": { "observed": { "type": "boolean" }, "status": { "type": ["integer", "null"], "minimum": 100, "maximum": 599 } }
|
|
36
|
+
},
|
|
37
|
+
"region": { "type": ["string", "null"] },
|
|
38
|
+
"collector": { "type": "string", "minLength": 1 },
|
|
39
|
+
"stages": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": ["declared", "synthetically_observed", "range_matched", "dns_verified", "edge_observed", "origin_observed", "fully_verified", "contradictory", "insufficient_evidence"] } },
|
|
40
|
+
"verification_status": { "type": "string", "enum": ["declared", "synthetically_observed", "range_matched", "dns_verified", "edge_observed", "origin_observed", "fully_verified", "contradictory", "insufficient_evidence"] }
|
|
41
|
+
}
|
|
42
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$id": "citable://schemas/evidence-authority.schema.json",
|
|
3
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
4
|
+
"title": "Multidimensional evidence authority",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"additionalProperties": false,
|
|
7
|
+
"required": ["source_authority", "collection_authority", "authenticity_status", "representativeness"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"source_authority": { "type": "string", "enum": ["provider_published", "standards_body", "owner_controlled", "independently_controlled", "third_party_commercial", "synthetic", "inferred", "unknown"] },
|
|
10
|
+
"collection_authority": { "type": "string", "enum": ["direct_api", "production_log", "browser_capture", "owner_export", "third_party_export", "manual_entry", "model_generated_inference", "static_analysis", "synthetic_probe"] },
|
|
11
|
+
"authenticity_status": { "type": "string", "enum": ["cryptographically_authenticated", "provider_range_verified", "owner_attested", "transport_authenticated", "checksum_protected_only", "unverified"] },
|
|
12
|
+
"representativeness": { "type": "string", "enum": ["production_population", "complete_export", "statistically_sampled", "controlled_experiment", "convenience_sample", "single_observation", "unknown"] },
|
|
13
|
+
"limitations": { "type": "array", "items": { "type": "string", "minLength": 1 } }
|
|
14
|
+
}
|
|
15
|
+
}
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
"required": ["observation_id", "kind", "state", "collected_at", "collection_method", "confidence", "source", "evidence_hash", "data"],
|
|
8
8
|
"properties": {
|
|
9
9
|
"observation_id": { "type": "string", "minLength": 1 },
|
|
10
|
-
"kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "passage", "canonical_freshness", "performance", "corroboration", "metric"] },
|
|
10
|
+
"kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric"] },
|
|
11
11
|
"state": { "type": "string", "enum": ["observed", "not_observed", "not_evidenced", "incomplete", "review_required", "failed"] },
|
|
12
12
|
"collected_at": { "type": "string", "format": "date-time" },
|
|
13
13
|
"collection_method": { "type": "string", "enum": ["live_api", "browser", "owner_import", "synthetic_fetch", "static_analysis", "human_review"] },
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
"source": { "type": "string", "minLength": 1 },
|
|
16
16
|
"evidence_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
|
|
17
17
|
"data": { "type": "object" },
|
|
18
|
-
"limitations": { "type": "array", "items": { "type": "string" } }
|
|
18
|
+
"limitations": { "type": "array", "items": { "type": "string" } },
|
|
19
|
+
"authority": { "$ref": "citable://schemas/evidence-authority.schema.json" }
|
|
19
20
|
}
|
|
20
21
|
}
|
|
@@ -7,12 +7,16 @@ description: >
|
|
|
7
7
|
generative engine optimization, structured data governance, claim substantiation,
|
|
8
8
|
crawler policy, entity consistency, content discoverability, or wants a site audited
|
|
9
9
|
for how search and AI systems will retrieve, understand, cite, or recommend it.
|
|
10
|
-
version: 1.
|
|
10
|
+
version: 1.7.0
|
|
11
11
|
---
|
|
12
12
|
|
|
13
|
-
# Citable — search
|
|
13
|
+
# Citable — evidence and change control for search and AI citation readiness
|
|
14
14
|
|
|
15
15
|
Citable is an operational quality and governance layer, not a content generator.
|
|
16
|
+
It records what a property makes technically available, what its content can
|
|
17
|
+
support, and what external systems have actually been observed doing. It does
|
|
18
|
+
not score visibility; it establishes what is eligible, supportable, observed,
|
|
19
|
+
changed, and still unknown.
|
|
16
20
|
It treats discoverability as an engineering system: registries as the source of
|
|
17
21
|
truth, deterministic detectors for observable conditions, rubrics for semantic
|
|
18
22
|
judgment, evidence packages for every run, and fail-closed behaviour wherever a
|
|
@@ -70,6 +74,11 @@ Within retrieval, distinguish `allowed_by_policy`, `synthetic_fetch_succeeded`,
|
|
|
70
74
|
citation testing, distinguish mention, citation, material support, canonical
|
|
71
75
|
source selection, and recommendation. These states are not interchangeable.
|
|
72
76
|
|
|
77
|
+
Evidence preservation, authority, authenticity, collection method, and
|
|
78
|
+
representativeness are also independent. Follow
|
|
79
|
+
`references/evidence-authority.md`; a checksum or CIDR match alone never proves
|
|
80
|
+
source authenticity, complete coverage, or verified crawler identity.
|
|
81
|
+
|
|
73
82
|
## Tooling
|
|
74
83
|
|
|
75
84
|
The `citable` CLI in this repository performs the deterministic work. Always
|
|
@@ -86,6 +95,7 @@ citable validate [registries|claims|evidence|schema|links]
|
|
|
86
95
|
citable compare-snapshots [runA runB]
|
|
87
96
|
citable action-plan [run-id] # ordered actions, blockers, semantic gates, verification
|
|
88
97
|
citable observe <mode> [options] # render/index/citation/log/passage/consensus/performance evidence
|
|
98
|
+
citable observe bing --dataset <search_performance|ai_performance> --input <csv|json>
|
|
89
99
|
citable apply --input <spec> [--write] # reviewed, hash-locked remediation; dry run by default
|
|
90
100
|
citable monitor [runA runB] # observation regression alerts
|
|
91
101
|
citable metrics import --provider <name> --input <csv|json>
|
|
@@ -1 +1 @@
|
|
|
1
|
-
1.
|
|
1
|
+
1.7.0
|
|
@@ -70,6 +70,21 @@ agent × URL × status; flag 403/429/5xx concentrations against declared-allow
|
|
|
70
70
|
crawlers; note that user-agent strings are spoofable and IP validation is the
|
|
71
71
|
confirmation step (crawler registry ip_validation_method). Compare observed
|
|
72
72
|
access against `crawlers.yaml` decisions (CRAWL-001 logic applied to logs).
|
|
73
|
+
Normalize JSON or CSV edge/origin events into the crawler identity contract.
|
|
74
|
+
Do not label CIDR membership alone verified: preserve range-source provenance,
|
|
75
|
+
DNS, edge, origin, region, collector, stages, and contradiction state.
|
|
76
|
+
Remove credentials, cookies, secrets, and unnecessary personal data before
|
|
77
|
+
import. Citable rejects common sensitive field names but cannot establish that
|
|
78
|
+
arbitrary URL or query values are lawful or appropriately minimized.
|
|
79
|
+
|
|
80
|
+
# Bing owner observations
|
|
81
|
+
|
|
82
|
+
Use `citable observe bing --dataset search_performance|ai_performance --input
|
|
83
|
+
<csv|json>`. This release normalizes owner exports because no supported Bing AI
|
|
84
|
+
Performance API contract has been captured. Citation counts do not indicate
|
|
85
|
+
ranking, authority, placement, page importance, or material support. Grounding
|
|
86
|
+
queries may be sampled. Preserve traffic-source dimensions and never infer
|
|
87
|
+
causation from a temporal change.
|
|
73
88
|
|
|
74
89
|
# monitor-contradictions
|
|
75
90
|
Compare approved entity + claim records against: owned pages (automated, via
|