Operational Trust Pipeline

When trucking operations need human attention, OTP turns raw operational state into a bounded human-action request, routes it through an available channel, and leaves verifiable evidence of what happened.

The problem

Trucking systems already produce plenty of data. The harder problem is the last mile of operational trust: when a trip is late, an acknowledgement is missing, or a driver needs attention, someone still has to decide:

• Does this situation actually require action?
• Who should be contacted?
• Which channel is allowed?
• Was the request merely accepted by a provider, or was it actually acknowledged?
• Can we prove what happened after a restart, outage, or handoff?

Most notification flows blur those states together. OTP keeps them explicit.

What OTP does

RoadStar data
   ↓
Normalize into OperationalEvent
   ↓
Deterministic policy + lease evaluation
   ↓
Sentinel authority boundary
   ↓
ActionRequest
   ↓
LAN / mock / optional external channel
   ↓
Human acknowledgement or explicit uncertainty
   ↓
Verifiable evidence receipt

OTP separates source, decision, authority, transport, persistence, and evidence so that changing a provider or interface does not redefine the operational decision itself.

90-second demo

1. OTP loads RoadStar operational data and identifies the trips that need attention.
2. An overdue trip appears as CRITICAL because its acknowledgement lease expired.
3. The operator clicks Request ACK.
4. OTP creates a bounded ActionRequest and exposes a local LAN acknowledgement page.
5. The page is opened on a phone on the same Wi-Fi network; the recipient taps ACKNOWLEDGE.
6. OTP records the result, resolves the lease, updates the trip state, and produces a SHA-256 evidence receipt.
7. That receipt can be inspected and verified in a single-file offline evidence viewer. Google Drive backup is optional, not required for the core workflow.

Why this matters for owner-operators

OTP is designed to remain useful even when modern cloud infrastructure, perfect connectivity, or high-end hardware cannot be assumed.

• Local-first: the core workflow can run without a cloud backend.
• Crash-aware: SQLite persistence records lifecycle state before external side effects and surfaces interrupted runs without guessing outcomes.
• Provider-agnostic: communication channels are adapters, not business logic.
• Offline evidence: receipts remain inspectable after the live workflow ends.
• Portable profile: a minimal C89/headless implementation exists for older or constrained machines where Python, Qt, or Google integrations are unavailable.

Features may degrade; semantics must not.

Operational honesty

OTP deliberately distinguishes claims that many systems collapse together:

provider accepted request  ≠  recipient received it
recipient received it      ≠  phone rang
phone rang                  ≠  recipient acknowledged

If an external provider accepts a request but OTP cannot prove delivery, the state is DELIVERY UNCERTAIN — not success, and not failure invented from missing evidence.

The same rule applies after crashes: if an ActionRequest was persisted but the result was never recorded, OTP reports the dispatch outcome as UNKNOWN.

Core architecture

Source Adapter → OTP Core → Channel Adapter
                    │
                    ├─ deterministic policies
                    ├─ acknowledgement leases
                    ├─ deny-by-default Sentinel
                    ├─ OperationalRunner
                    ├─ SQLite / Memory persistence
                    └─ SHA-256 evidence receipts

The RoadStar workbook adapter is one source. LAN, mock, and optional telephony adapters are transports. The core does not depend on any one of them.

Persistence and recovery

Normal runs use SQLite at ~/.otp/otp.db; an explicit ephemeral mode uses in-memory storage for tests and demos.

Lifecycle state is persisted across:

RUN_STARTED
→ LEASE_OPEN
→ FINDING_CREATED
→ ACTION_REQUESTED
→ ACTION_RESULT_RECORDED
→ LEASE_EVALUATED
→ RUN_COMPLETED

Incomplete executions are surfaced for recovery instead of silently becoming success or failure.

Evidence

Every receipt binds the operational event, lease, finding, action request, and action result with SHA-256 hashes. Ledger entries chain to the previous receipt so altered components, insertions, reordering, and deleted middle entries can be detected by offline verification.

The evidence viewer is a self-contained HTML artifact: open it locally, inspect the exact event/finding/action/result, and verify receipt integrity without starting the OTP application.

Channels and deployment profiles

• MockChannel — deterministic tests and demos
• LanChannel — local-network acknowledgement from a browser, no mobile app required
• CALL-E adapter — optional telephony boundary; not required by OTP
• Google Drive — optional evidence replica/backup
• OTP Portable (C89) — headless local profile for constrained or older machines

Verification

py -m pytest -q
# 107 passed, 1 skipped

The skipped test is the gated live CALL-E path; the deterministic core, GUI logic, LAN channel, persistence, recovery, Drive sync mocks, and evidence paths are covered by automated tests.

Quick start

# deterministic local demo
py -m otp.cli demo ack-lease

# no disk writes
py -m otp.cli demo ack-lease --ephemeral

# desktop control room
otp gui

# verify persistence
otp persistence verify

Project philosophy

OTP does not try to replace dispatchers or invent certainty that the underlying systems cannot provide.

It does one bounded job:

Detect when operational state needs human attention, route a justified request, and preserve evidence of what actually happened.

The last mile is someone else's infrastructure. OTP ends where it should.

https://youtu.be/PterAIMojxE

Built With

• c89
• flask
• google-drive-api
• pyside6
• pytest
• python
• sqlite