Local-first software runtime · v0.3.4 · Aziel Eliab · not a hosted company OS
This is the private software runtime — coded constitutional rules, not a PDF dump.
Trades-Runtime is a shadow-first TypeScript operating system for multi-branch HVAC, plumbing, electrical, sewer, and cross-trades field service. The product is the src/ package: append-only chains, Human Authority, confidence≠truth, Call-Fit, CrossTrade (secondary only), Decision Fabric, hash-chained receipts, quality-gated recognition, locked pricebook, weather demand, and demand-first maintenance. This Pages site is a thin UI over that software. Specs stay in the private repo at specs/ and are not published here.
Shadow-first
Observe → sealed counterfactual → compare to actual outcomes. Do not start by replacing ServiceTitan or ProBooks. The goal is not to claim the AI would have performed better; the goal is call-level and day-level evidence showing when it did, when it did not, and why.
Human Authority Rule
Authorized human decisions always win operationally. Trades may recommend against an override and explain why, but it never supersedes authorized human recalibration. The disagreement remains preserved as evidence.
Design target — not a live claim
Operating context for the architecture: ~13–15 branches, 750+ employees, Midwest region, multi-trade field service. This is a design target, not a production deployment or customer count.
Primary integration posture: BYO — each user incorporates their own ServiceTitan and ProBooks into their local runtime. Peer inbound. Read-only. Authoring node / GitHub is not a data custodian. No central dump. No hosted uploader. No phone-home. Credentials stay on the user’s machine.
What Trades-Runtime is not
- Not a simple dispatch optimizer.
- Not a leaderboard that equates revenue with technician quality.
- Not a fixed morning route planner.
- Not an autonomous black box that can silently overrule humans.
- Not an AI that treats a photo inference as proof of fault or misconduct.
- Not a fuel-minimization system that sacrifices technical fit or customer outcome.
- Not a system that assumes a 30-day return visit is automatically a technician callback.
Architecture map
Architecture
v0.2 operating design, engines, storage, and the north star.
Operating model
One canonical live state and role views from the same heartbeat.
Chains A / B / C
Full-Day Trajectory, Call-to-Call Ledger, Human Override / Recalibration.
Shadow & ladder
Observe → Shadow → Recommend → Human Approves → Limited Autonomy → Autonomous.
Decision rules
The v0.1 freeze list. Humans, history, and receipts stay first.
Dispatch / Van
Call-Fit, route drift, exploration, output vs performance.
Workforce
Demand-aware scheduling against the workforce that actually exists.
Multi-fabric
Decision Fabric, pipelines, Pareto frontier, champion/challenger.
Analytics
Four analytical levels and mandatory report metadata.
Software modules
Coded engines from the runtime manifest. No PDFs.
Trade surfaces
HVAC, plumbing, electrical, sewer, cross-trades on the same state.
runtime.json
Machine-readable design catalog. Stub where not implemented.