Audit Trail Specifications

Document ID: PLCY-AUD-001
Version: 1.2
Effective Date: January 21, 2026
Last Review: January 21, 2026
Owner: Hop And Haul Team

---

CONFIDENTIAL

This document is CONFIDENTIAL and for internal use only. Do not distribute outside the organization.

1. Purpose

This document specifies the audit trail requirements for Hop And Haul, ensuring complete, immutable, and queryable records of all system activities for SOC II compliance, DOT audits, and insurance disputes.

---

2. Audit Trail Principles

2.1 Core Requirements

Principle	Implementation
Complete	All significant events logged
Accurate	Timestamps and data verified
Immutable	Append-only, no modifications
Timely	Real-time or near-real-time logging
Accessible	Queryable for authorized users
Retained	Per defined retention schedule

2.2 Non-Repudiation

All logged events must be:

• Traceable to a specific actor (user or system)
• Timestamped with server time (not client)
• Cryptographically verifiable
• Tamper-evident

---

3. Events to Log

3.1 Transport Lifecycle Events

Event	Trigger	Data Captured
REQUEST_CREATED	Driver submits transport request	Driver ID, location, time window, reason
REQUEST_UPDATED	Request details modified	Changed fields, timestamp
REQUEST_CANCELLED	Request withdrawn	Cancellation reason, timestamp
MATCH_IDENTIFIED	System finds compatible driver	Match score, candidate list
OFFER_SENT	Offer presented to driver	Offer details, recipient
OFFER_VIEWED	Driver opens offer	View timestamp
OFFER_ACCEPTED	Driver accepts offer	Acceptance timestamp
OFFER_REJECTED	Driver declines offer	Rejection timestamp
OFFER_EXPIRED	Offer times out	Expiration timestamp
SAMSARA_MESSAGE_SENT	Samsara Message sent via API	offer_id, driver_id, template_id, driver_state
SAMSARA_MESSAGE_DELIVERED	API confirms delivery	message_id, delivery_timestamp
SAMSARA_MESSAGE_FAILED	API error on send	error_code, error_message
SAMSARA_RESPONSE_RECEIVED	Polling detects response	driver_id, raw_response_hash, parsed_intent
SAMSARA_RESPONSE_TIMEOUT	Timeout without response	offer_id, timeout_duration, voice_fallback_triggered
SAMSARA_CLARIFICATION_SENT	Clarification message sent	offer_id, driver_id
VOICE_FALLBACK_INITIATED	Voice call after message timeout	offer_id, fallback_reason
OFFER_CONFIRMED_VIA_MESSAGE	Offer accepted via Samsara text	offer_id, response_text_hash
OFFER_DECLINED_VIA_MESSAGE	Offer declined via Samsara text	offer_id, response_text_hash
VOICE_CALL_LOGGED	Automated dispatcher call logged (per PLCY-COM-001 5.1)	timestamp, driver_id, opportunity_id, response_received, time_to_response
DRIVER_PAUSE_REQUESTED	Driver requested pause from automated calls	driver_id, pause_timestamp, pause_duration
DRIVER_PAUSE_ENDED	Driver pause period ended	driver_id, resume_timestamp, pause_duration_actual
OPPORTUNITY_HISTORY_REQUESTED	Driver requested opportunity history review	driver_id, date_range, fulfillment_timestamp
VALIDATION_PASSED	Pre-pickup checks clear	Check results
VALIDATION_FAILED	Pre-pickup check fails	Failed check, reason
PICKUP_CONFIRMED	Passenger in vehicle	Confirmation timestamp, location
RIDE_STARTED	Tracking begins	Start timestamp, route
ROUTE_DEVIATION	Unexpected route change	Deviation details
UNPLANNED_STOP	Vehicle stops unexpectedly	Stop location, duration
DROPOFF_CONFIRMED	Passenger delivered	Completion timestamp, location
RIDE_COMPLETED	Transaction finalized	Final status
RATING_SUBMITTED	Driver submits rating	Rating category, score (not content)
PAYMENT_INITIATED	Settlement triggered	Amount, method
PAYMENT_COMPLETED	Settlement confirmed	Confirmation reference

3.2 Security Events

Event	Trigger	Data Captured
AUTH_SUCCESS	Successful login	User, method, IP, device
AUTH_FAILURE	Failed login attempt	User (if known), IP, reason
AUTH_LOCKOUT	Account locked	User, trigger reason
SESSION_START	Session created	User, session ID, IP
SESSION_END	Session terminated	Reason (logout, timeout, forced)
ACCESS_GRANTED	Resource access allowed	User, resource, permission
ACCESS_DENIED	Resource access blocked	User, resource, reason
PRIVILEGE_ESCALATION	Role/permission change	User, old role, new role
DATA_EXPORT	Data exported from system	User, data type, record count

3.3 Configuration Events

Event	Trigger	Data Captured
CONFIG_CHANGED	System setting modified	Setting, old value, new value
USER_CREATED	New user account	User details, creator
USER_MODIFIED	User account changed	Changed fields
USER_DEACTIVATED	Account disabled	Reason, deactivator
ROLE_ASSIGNED	Role granted to user	User, role, grantor
ROLE_REVOKED	Role removed from user	User, role, revoker

3.4 System Events

Event	Trigger	Data Captured
SYSTEM_START	Application startup	Version, environment
SYSTEM_STOP	Application shutdown	Reason
INTEGRATION_CALL	External API called	Target, request summary, response code
INTEGRATION_ERROR	External API failure	Target, error details
SCHEDULED_JOB	Automated task runs	Job name, result
ERROR_LOGGED	Application error	Error type, stack trace

---

4. Log Record Structure

4.1 Standard Fields

Every log record contains:

{
  "log_id": "uuid-v4",
  "event_type": "EVENT_NAME",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "actor_type": "user|system|service",
  "actor_id": "[tokenized or service name]",
  "session_id": "[if applicable]",
  "ip_address": "[masked if user]",
  "resource_type": "[entity type]",
  "resource_id": "[entity id]",
  "action": "create|read|update|delete|execute",
  "outcome": "success|failure",
  "details": {
    // Event-specific data
  },
  "checksum": "[integrity hash]"
}

4.2 Tokenization Rules

Field	Tokenization
User IDs	Pseudonymized, reversible by security team
Driver IDs	Pseudonymized, reversible by ops
Session IDs	Random UUID, not linked to user directly
IP addresses	Last octet masked for users
Device IDs	Hashed, irreversible
Location data	Stored as coordinates only

---

5. Log Integrity

5.1 Immutability Controls

Control	Implementation
Append-only storage	Write-once log storage
No delete operations	Physical deletion blocked
No update operations	Modification blocked
Versioning	All changes create new records

5.2 Tamper Detection

Method	Implementation
Record checksums	SHA-256 hash per record
Chain linking	Each record references previous
Periodic verification	Automated integrity checks
External archival	Copies to separate system

5.3 Chain Structure

Record N:
  checksum: SHA256(record_data)
  prev_checksum: [checksum of Record N-1]

Record N+1:
  checksum: SHA256(record_data)
  prev_checksum: [checksum of Record N]

---

6. Retention Schedule

See PLCY-RET-001 Records Retention Policy for authoritative retention schedule.

6.1 Retention by Category

Log Category	Retention	Justification
Transport events	24 months	DOT audit window
Security events	24 months	Security analysis + forensics
Configuration events	24 months	Change tracking
System events	12 months	Operational debugging
Error logs	6 months	Troubleshooting

Retention periods aligned with PLCY-RET-001. Refer to that document for legal hold procedures.

6.2 Retention Extensions

Scenario	Action
Active investigation	Preserve until resolved
Legal hold	Indefinite preservation
Audit in progress	Preserve until completion
Dispute filed	Preserve until resolution

6.3 Disposal Process

Step	Action
1	Automated identification of expired logs
2	Verification no hold applies
3	Secure deletion (overwrite)
4	Disposal logged
5	Confirmation record created

---

7. Access Controls

7.1 Log Access Matrix

Role	Access Level
Operations/Safety	Read transport events (filtered)
Security team	Read all events
Auditors	Read all events (time-limited)
System administrators	Read system events
Drivers	Read own events only

7.2 Query Restrictions

Restriction	Implementation
Time-bounded queries	Maximum 90-day range
Result limits	Maximum 10,000 records per query
Rate limiting	Queries per minute capped
Export approval	Large exports require approval

---

8. Query Capabilities

8.1 Standard Queries

Query Type	Parameters
By transaction	transaction_id
By driver	driver_id + date range
By event type	event_type + date range
By outcome	success/failure + date range
By time range	start_time + end_time

8.2 Audit Response Queries

Regulatory Need	Query Support
DOT: Transport documentation	All events for ride ID
Insurance: Incident timeline	Events by time + location
Legal: User activity	All events by user ID
Compliance: Access review	Security events by user

8.3 Export Formats

Format	Use Case
JSON	API consumption
CSV	Spreadsheet analysis
PDF	Formal audit reports

---

9. Monitoring & Alerting

9.1 Log Monitoring

Condition	Alert
Log ingestion failure	Immediate (critical)
Integrity check failure	Immediate (critical)
Unusual event volume	Within 5 minutes
Access pattern anomaly	Within 15 minutes
Retention job failure	Next business day

9.2 Health Metrics

Metric	Threshold
Log latency	< 5 seconds from event
Storage utilization	Alert at 80%
Query response time	< 10 seconds
Integrity check pass rate	100%

---

10. Document Control

Version	Date	Author	Changes
1.0	[DATE]	[NAME]	Initial release
1.1	January 2, 2026	Hop And Haul Team	Added Samsara Messages event types: SAMSARA_MESSAGE_SENT, SAMSARA_MESSAGE_DELIVERED, SAMSARA_MESSAGE_FAILED, SAMSARA_RESPONSE_RECEIVED, SAMSARA_RESPONSE_TIMEOUT, SAMSARA_CLARIFICATION_SENT, VOICE_FALLBACK_INITIATED, OFFER_CONFIRMED_VIA_MESSAGE, OFFER_DECLINED_VIA_MESSAGE
1.2	January 21, 2026	Hop And Haul Team	Aligned with PLCY-COM-001 v3.0: Added VOICE_CALL_LOGGED event type with fields per Section 5.1 (timestamp, driver_id, opportunity_id, response_received, time_to_response). Added driver rights events: DRIVER_PAUSE_REQUESTED, DRIVER_PAUSE_ENDED, OPPORTUNITY_HISTORY_REQUESTED.