docs: add canonical business record v0.1.1 architecture

2026-08-12 23:12:01 +00:00
parent ff09747d58
commit 2c7b7be707
1 changed files with 157 additions and 0 deletions
@@ -0,0 +1,157 @@
+# 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:
+
+```typescript
+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
+
+```typescript
+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:
+
+```json
+{
+    "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`