veripath/docs/architecture/canonical-business-record-v0.1.1.md

Canonical Business Record — v0.1.1

Date: 2026-08-13
Status: Draft — Contract v0.1
Owner: Tony / VeriPath
Scope: Architecture

VeriPath is the system of record. This document defines the canonical business record format used for audit output, evidence classification, and downstream handoff. GeoLocal or other consumers treat this as read-only.

---

Field State Model

Every field in the record carries its own provenance:

interface FieldState {
    status: 'observed' | 'verified' | 'stale' | 'disputed';
    evidence_tier: 'tier_1' | 'tier_2' | 'tier_3';
    observed_at: string;
    verified_at: string | null;
    fresh_until: string | null;
    source_independence: 'independent' | 'same_origin' | 'unknown';
    sources: string[];
    action_risk: 'low' | 'medium' | 'high';
}

Status meanings

Status	Meaning
observed	Captured from a source but not independently confirmed
verified	Confirmed by independent sources or owner approval
stale	Previously accurate but freshness has expired
disputed	Conflicting evidence exists; resolution pending

Evidence tiers

Tier	Definition
tier_1	Direct observation, owner-confirmed, or instrument-backed
tier_2	Corroborated from independent sources
tier_3	Single source, probabilistic, or directional

---

Record Domains

Identity

• legal_name
• dba_name
• industry
• naics_code

Location

• street_address
• city
• state
• postal_code
• country
• geo_coordinates

Contact

• phone
• website
• email

Hours

• regular_hours
• holiday_hours
• timezone

Services and Pricing

• service_name
• service_description
• price_point
• pricing_unit

Booking

• booking_url
• booking_provider
• walk_in_accepted

Proof and Reputation

• review_count
• review_sources
• differentiators

---

Metadata and Provenance

interface CanonicalBusinessRecord {
    record_id: string;
    domains: RecordDomains;
    provenance: {
        created_at: string;
        updated_at: string;
        version: string;
        record_owner: string;
    };
    approvals: ApprovalEntry[];
    change_history: ChangeEntry[];
    conflicts: ConflictEntry[];
}

Approvals

• owner_confirmed: boolean
• owner_confirmed_at: string | null
• confirmed_fields: string[]
• disputed_fields: string[]

---

Agent Action Boundaries

The record must not be used by agents to perform transactions. Agents may:

• Provide information (address, hours, services)
• Provide recommendation (services, booking links)
• Display warnings (stale data, disputed claims)

Agents must not:

• Infer availability from hours
• Confirm bookings without live verification
• Present stale data as current
• Treat observed data as verified

---

Response Envelope

Downstream responses include provenance in the body, not only headers:

{
    "data": { "...": "..." },
    "retrieval": {
        "status": "verified",
        "last_checked": "2026-08-13T00:00:00Z",
        "fresh_until": "2026-09-12T00:00:00Z",
        "action_risk": "medium",
        "requires_recheck_before_action": true
    }
}

---

Related documents

• docs/decisions/2026-08-12-veripath-system-of-record-boundary.md
• docs/architecture/evidence-freshness-policy-v0.1.md