Audit Engine Findings → Canonical Business Record Mapping

Date: 2026-08-14 Status: Draft Owner: Tony / VeriPath Scope: Architecture

Contract between audit_engine.py output (findings) and canonical-business-record-v0.1.1.md field states.

1. Direct Field Mappings

Each audit finding maps to one or more CBR domains. The finding's evidence drives the field's status, evidence_tier, and action_risk.

Finding ID	CBR Domain	CBR Field(s) Updated
`nap_phone_mismatch`	Contact	`phone`
`nap_address_mismatch`	Location	`street_address`
`nap_website_mismatch`	Contact	`website`
`hours_mismatch`	Hours	`regular_hours`
`rating_delta_high`	Proof & Reputation	`review_count`, `review_sources`
`rating_below_threshold`	Proof & Reputation	`review_count`, `review_sources`
`review_count_delta`	Proof & Reputation	`review_count`, `review_sources`
`reviews_stale`	Proof & Reputation	`review_sources`
`reviews_low_specificity`	Proof & Reputation	`review_sources`, `differentiators`
`category_fragmentation`	Identity	`industry`
`gbp_permanently_closed`	Identity	`industry` (closed status flag)
`gbp_temporarily_closed`	Identity	`industry` (closed status flag)
`no_description`	Proof & Reputation	(description field — not yet in CBR)
`no_price_level`	Services and Pricing	`price_point`
`no_photos`	Proof & Reputation	(photos field — not yet in CBR)
`low_photos`	Proof & Reputation	(photos field — not yet in CBR)
`missing_jsonld_schema`	Identity	(schema field — not yet in CBR)
`schema_wrong_type`	Identity	(schema field — not yet in CBR)
`missing_canonical`	Identity	(schema field — not yet in CBR)
`missing_og_tags`	Identity	(schema field — not yet in CBR)
`website_unreachable`	Contact	`website`
`no_gmaps_url`	Location	`geo_coordinates` (GBP claim URL)
`low_coordinate_precision`	Location	`geo_coordinates`

2. Provenance Rules

Status Assignment

Engine Finding Severity	CBR Field `status`	When
Finding detected, 1 source	`observed`	Single surface has data but no corroboration
Finding detected, 2+ independent sources agree	`verified`	GBP + Apple Maps match, or website + GBP match
Finding detected, sources contradict	`disputed`	GBP says one thing, Apple says another
Previous audit had value, window expired	`stale`	Freshness policy exceeded without re-check

Evidence Tier Assignment

Source Combination	`evidence_tier`	`source_independence`
GBP only	`tier_3`	`unknown`
Apple Maps only	`tier_3`	`unknown`
Bing Places only	`tier_3`	`unknown`
GBP + Apple Maps	`tier_2`	`independent` (different data pipelines)
GBP + Bing Places	`tier_2`	`independent`
Apple Maps + Bing Places	`tier_2`	`independent`
GBP + Apple + Bing	`tier_2`	`independent`
Website schema + GBP	`tier_2`	`independent`
Owner confirmation	`tier_1`	`independent`
Website footer + website schema	`tier_3`	`same_origin`

Rule: Multiple extractions from the same website (footer text, JSON-LD, meta tags) count as same_origin, not independent. Only cross-platform matches upgrade tier.

Freshness Policy Alignment

Each field inherits the freshness window from evidence-freshness-policy-v0.1.md:

CBR Domain	Freshness Window	`fresh_until` calculation
Hours	7 days	`audit_timestamp + 7d`
Services/Pricing	14 days	`audit_timestamp + 14d`
Booking	7 days	`audit_timestamp + 7d`
All other fields	30 days	`audit_timestamp + 30d`

If a finding detects a mismatch on a field whose freshness has expired, set fresh_until to the audit timestamp + that domain's window.

3. Severity → action_risk Translation

Engine Severity	CBR `action_risk`	Rationale
`immediate`	`high`	Data is actively harmful (wrong address, closed status, phone mismatch). Downstream agents must not act on stale values without re-check.
`high`	`high`	Significant credibility signal loss (no photos, rating below 4.0, no website). Display only; block transactions.
`medium`	`medium`	Optimization gap (category misalignment, low review specificity, missing price level). Display with timestamp and recheck notice.
`enhancement`	`low`	Nice-to-have (OG tags, additional photos). Informational display.

4. Gaps and Open Questions

The following audit findings have no clean home in the current CBR v0.1.1 schema:

Finding	Gap	Proposed Resolution
`no_photos` / `low_photos`	No `photos` field in CBR	Add `photos: { count, sources, last_updated }` to Proof & Reputation
`no_description`	No `description` field in CBR	Add `description` to Identity domain
`missing_jsonld_schema` / `schema_wrong_type` / `missing_canonical` / `missing_og_tags`	No technical schema fields in CBR	Add `technical_seo: { jsonld, canonical, og_tags }` as metadata domain
`website_unreachable`	Website status is boolean but CBR only stores URL	Add `website: { url, reachable, last_checked }` sub-object
`reviews_low_specificity`	CBR has `differentiators` but no structured review quality score	Add `review_quality: { specific_ratio, sample_size }` to Proof & Reputation

Decision needed: Do we extend CBR v0.1.2 to include these fields, or keep the engine findings separate from the canonical record until v1.0?

5. Example: Phoenix Salon+Spa Address Mismatch

Finding:

{
  "id": "nap_address_mismatch",
  "severity": "immediate",
  "title": "Address inconsistent across 2 surface(s)",
  "sub_score": "Digital Identity",
  "evidence": {
    "google": "1234 Main St, Ste 4, Los Angeles, CA 90012",
    "apple": "1234 Main St, Los Angeles, CA 90012"
  },
  "recommendation": "Standardize exact address format. GBP address is authoritative."
}

Resulting CBR field state:

{
  "street_address": {
    "value": "1234 Main St, Ste 4, Los Angeles, CA 90012",
    "status": "disputed",
    "evidence_tier": "tier_2",
    "observed_at": "2026-08-14T00:00:00Z",
    "verified_at": null,
    "fresh_until": "2026-09-13T00:00:00Z",
    "source_independence": "independent",
    "sources": ["google_business_profile", "apple_maps"],
    "action_risk": "high",
    "conflict_detail": {
      "google": "1234 Main St, Ste 4, Los Angeles, CA 90012",
      "apple": "1234 Main St, Los Angeles, CA 90012"
    }
  }
}

Decision logic:

GBP is authoritative → GBP value is the canonical value
Apple disagrees → status is disputed, not verified
Two independent sources → evidence_tier is tier_2
Severity immediate → action_risk is high
Domain is Location (regular field) → fresh_until is audit + 30d

docs/architecture/canonical-business-record-v0.1.1.md
docs/architecture/evidence-freshness-policy-v0.1.md
implementation/auditing/audit_engine.py

7.2 KiB Raw Permalink Blame History